Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
bump: patch
---

### Fixed

- The audit skill's write-posture note says the guardrails `settings-write-ask` checkpoint
denies a settings edit in a session nobody can answer, instead of claiming it always asks.
10 changes: 10 additions & 0 deletions .changes/guardrails/fix-guardrails-unattended-deny-32187901.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
bump: patch
---

### Changed

- `settings-write-ask` now returns `deny` instead of `ask` when nobody can answer a prompt:
`CLAUDE_CODE_SESSION_ATTENDED` is not `1` (as in `claude -p` and `claude --bg`), or
`GUARDRAILS_SESSION_UNWATCHED` is `1`. This is the same test the blocking guards use, so an
unattended lane never waits on this hook's prompt.
3 changes: 2 additions & 1 deletion plugins/context-budget/skills/audit/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -366,7 +366,8 @@ Write posture splits by scope, and the split is not negotiable:
with a file-editing tool (`Edit` or `Write`), never through the shell. Where the guardrails
plugin is enabled, its `settings-write-ask` PreToolUse checkpoint returns
`permissionDecision: "ask"` for a file-editing tool call that targets a settings file, so even
in auto mode the write prompts rather than sliding through. It does not see a settings write
in auto mode the write prompts rather than sliding through; in a session nobody can answer it
returns `deny`. It does not see a settings write
made through `Bash` or `PowerShell`, or one rendered into place by another program such as a
dotfile manager (the guardrails README's "Settings-write ask" section names each route and
records why the hook is not widened). **A checkpoint, not a guarantee**: other hooks,
Expand Down
30 changes: 18 additions & 12 deletions plugins/guardrails/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ In a session that loads a mod, don't rely on this plugin's `PreToolUse` hooks al
| **block-lane-pr-disable-auto** | PreToolUse · Bash | **Blocks** (exit 2) | Turning off auto-merge on a pull request the lanes App named by `block_lane_pr_disable_auto_app` opened (unset, a disable on any pull request a GitHub App opened is blocked, and one a person opened passes): `gh pr merge <n> -R <owner>/<repo> --disable-auto`, and the `disablePullRequestAutoMerge` mutation through `gh api graphql`. The pr-merge lane reads a disable by a `User` as the owner's veto and never arms that PR again, and a session runs under the owner's login. The block says to hold the PR with the `do-not-merge` label, which the lane disarms on and re-arms after by itself. The author is read with one `gh pr view <n> -R <owner>/<repo> --json author` call (a GraphQL `node` query for the mutation's `PR_...` id); a PR by any other author passes. A target it cannot read is blocked: a PR number, repo or node id from a shell variable, `$(...)` or backticks, a disable with no PR number or URL, one with no `-R` in a command that changes directory or names `GH_REPO` or `GH_HOST`, a mutation without exactly one literal `PR_...` id, and an author read that fails. Not matched: the PowerShell tool, a mutation read from a file, a command word from an expansion (`$GH pr merge`), a disable inside `bash -c`, `eval` or a wrapper such as `sudo`, and the web UI. With `gh` not on the hook's `PATH`, a target the guard can read passes unchecked. Escape: `block_lane_pr_disable_auto_enabled`. |
| **block-fix-request-post** | PreToolUse · Bash \| PowerShell **and** the GitHub MCP comment, review, issue and pull-request write tools (`mcp__github__add_issue_comment`, `pull_request_review_write`, and the rest named in `hooks/hooks.json`) | **Blocks** (exit 2) | An agent posting the PR-fix lane fix request: a line starting `PR-fix lane: please fix this finding`, any case, which the address-feedback lane (`FIX_REQUEST` in `.github/scripts/pr-unblock/address-feedback.mjs`) acts on with push credentials when someone with write access posts it. A local session posts with the owner's token, so only the owner posts it, typed in the GitHub UI ([#8438](https://github.com/melodic-software/claude-code-plugins/issues/8438)). Covers `gh pr\|issue comment\|review\|create\|edit`, a writing `gh api` (GraphQL only for a mutation), and `curl` with a body to a GitHub API route; the body is read inline, from heredocs, and from every `--body-file`, `-F k=@file`, `--input`, `-d @file`, `cat` or `<` file. A line after `>`, inside a fence, or a mention later in a line passes, as does a command that only reads or greps the phrase. The guard header lists the known gaps. Escape: `block_fix_request_post_enabled`; for sessions working in a repository, `fix_request_post: allow` (default `block`) in its `docs/conventions/guardrails.yaml` at the local `origin/HEAD`, which then applies to posts to any repository. |
| **block-github-post-content** | PreToolUse · Bash \| PowerShell | **Blocks** (exit 2) | A command that posts a secret or a hardcoded machine-specific path to GitHub: `gh pr\|issue comment\|review\|create\|edit`, a writing `gh api`, or `curl` with a body to a GitHub API route, bare or inside `bash -c`, `eval`, or a script wrapper's command after `--` (split on `+++`). Reads the same bodies as block-fix-request-post, through `lib/github-post/github-post-body.sh`, and runs the secret-pattern-detection and hardcoded-path-check pattern sets over them. A secret block names the pattern class, never the value. The path scan skips the whole command and the file paths it names, so a wrapper path or a `--body-file` operand is not judged. Under the Bash tool, an `--attach` operand is judged for paths by what gh can post from it (the text after its first `#` and its base name), so its source directory is exempt, except one whose alt text holds `/` or `\`, one the shell would expand, one that follows a dash flag without `=`, and a joined `--attach=<v>` whose preceding word the shell would expand, which are judged whole. Under PowerShell every `--attach` operand is judged whole, because PowerShell's argument passing to native commands can change what gh receives. A command that posts nothing passes. Escape: `block_github_post_content_enabled`; `secret_pattern_detection_enabled` and `hardcoded_path_check_enabled` turn off their half. |
| **settings-write-ask** | PreToolUse · Write \| Edit \| NotebookEdit | **Asks** (an `ask` decision on stdout, exit 0) | A file-editing tool call aimed at a settings file Claude Code reads, so the edit prompts even in auto mode. Shell writes and files rendered into place are not seen. [Settings-write ask](#settings-write-ask) lists the files and the limits. Kill switch: `settings_write_ask_enabled`. |
| **settings-write-ask** | PreToolUse · Write \| Edit \| NotebookEdit | **Asks** (an `ask` decision on stdout, exit 0) when `CLAUDE_CODE_SESSION_ATTENDED` is `1` and `GUARDRAILS_SESSION_UNWATCHED` is not `1`; **denies** (a `deny` decision) otherwise (see [Unwatched sessions](#unwatched-sessions)) | A file-editing tool call aimed at a settings file Claude Code reads, so the edit prompts even in auto mode. Shell writes and files rendered into place are not seen. [Settings-write ask](#settings-write-ask) lists the files and the limits. Kill switch: `settings_write_ask_enabled`. |
| **connected-page-gate** | PreToolUse · Artifact | **Blocks** (a `deny` decision on stdout, exit 0) | An Artifact publish of an HTML page whose content security policy names a loopback `connect-src`: a connected page (built with `--connect`) works only on this machine and stays a local file. It reads the file content, so a connected page from any builder is caught, in `file_path` or in `files`. Every other Artifact call passes, as does a file it cannot read. It is not the approval-marker publish gate (#7956), and it does not cover `/visualization:present`'s `--argument artifact` flag. Kill switch: `connected_page_guard_enabled`. |
| **cli-flag-verify** | git pre-push, `reference-verify` entry, on `.md`, `.sh`, `.bash`, `.ps1`, `.psm1` | **Fails the push** (exit 1) | Hallucinated CLI flags: a `--flag` written as a command, on a line the pushed commits add, that does not exist in the binary's actual `--help` output. |
| **workflow-resilience-check** | PreToolUse · Workflow | **Advisory** (exit 0) | Workflow fan-out with no wave cap of its own: a script calling `parallel()` / `pipeline()` with no wave-cap throttle (`inWaves` / `inWavesPipeline`) and no retry wrapper (`agentRetry`), which risks a burst 529 under wide Opus fan-out. The runtime's own concurrency limit still applies ([workflows: Behavior and limits](https://code.claude.com/docs/en/workflows#behavior-and-limits)). Surfaces a one-line advisory via `additionalContext` that points at the workflow-authoring skill and names the overloaded-retry backoff ceiling variable with a link to its docs section, never blocks. **Opt-in. Default off since 0.20.0** (behavioral-class injector config-disabled per #2021; set `workflow_resilience_check_enabled=true` to enable). |
Expand Down Expand Up @@ -133,7 +133,7 @@ hooks) under the check-placement convention's contract
(`docs/contracts/check-placement/README.md` in the marketplace repository): local
scope is this clone only. Shared scope with lefthook adds one `remotes:` entry to the
committed `lefthook.yml`, so every clone runs the hooks from this marketplace repository's
`main` branch (`git-hooks/lefthook-remote.yml`), refetched hourly: whoever can merge to that
`main` branch (`git-hooks/lefthook-remote.yml`), refetched hourly, so whoever can merge to that
`main` runs code in every such clone within an hour, with its user's privileges and git
credentials. With husky or plain hooks it commits copies under
`.githooks/guardrails/`. A clone whose fetched remote no longer parses (every commit and
Expand Down Expand Up @@ -162,8 +162,11 @@ edits prompt even in auto mode. It matches only the settings files Claude Code r
`settings.json` and `settings.local.json` in `.claude/` under the project directory or the
session's working directory, `settings.local.json` at the main checkout's root, plus
`managed-settings.json` and `managed-settings.d/` drop-ins in the managed system directory. A
fixture or example named `.claude/settings.json` elsewhere does not prompt. Kill switch: the
`settings_write_ask_enabled` plugin option.
fixture or example named `.claude/settings.json` elsewhere does not prompt. In a session nobody
can answer (`CLAUDE_CODE_SESSION_ATTENDED` not `1`, as in `claude -p` and `claude --bg`, or
`GUARDRAILS_SESSION_UNWATCHED=1`) it returns `deny` instead, the same test the blocking guards
use ([Unwatched sessions](#unwatched-sessions)), so a lane never waits on a prompt. Kill switch:
the `settings_write_ask_enabled` plugin option.

- **Pointer:** where Claude Code keeps each settings file:
[settings § Settings files and who they affect](https://code.claude.com/docs/en/settings#settings-files-and-who-they-affect)
Expand Down Expand Up @@ -199,7 +202,9 @@ working directory:
- The file was not written.

This run cannot tell whether the hook's `ask` alone would have blocked the write: Claude Code's
own check rejected it, so the `ask` was never what resolved the call.
own check rejected it, so the `ask` was never what resolved the call. A headless run reads
`CLAUDE_CODE_SESSION_ATTENDED=0`, so the hook now returns `deny` there; the run still shows what
Claude Code's own check does.

Not measured on 2.1.325: whether the reason shows in an interactive prompt, and the `auto` and
`bypassPermissions` modes. Those two modes were last measured on Claude Code 2.1.263
Expand Down Expand Up @@ -455,7 +460,7 @@ out of scope until such a signal exists.
`mcp__plugin_<plugin>_github__<tool>`. Pointer:
<https://code.claude.com/docs/en/hooks#match-mcp-tools>. As of: 2026-09-27.
Recheck trigger: that section changes how a plugin-bundled server's tools are
named. This closes a real hole. A
named. A
`Write|Edit` matcher does not see an MCP write, so a session could be cleared
by these guards and still push the same secret to a repository by another
route, where there is no local file to fix afterwards and no `pre-commit`
Expand Down Expand Up @@ -1329,7 +1334,7 @@ the always-on write path pays nothing for it.

*Method.* Wall time of 20 to 30 dispatcher runs per payload, divided by the run
count, on an otherwise idle host, `HOOK_TELEMETRY_SINK` unset. Absolute
milliseconds rather than spawn-equivalents: this is a same-host before/after on one
milliseconds rather than spawn-equivalents, because this is a same-host before/after on one
machine, and a spawn-equivalent only survives a host change for a spawn-dominated
hook.

Expand Down Expand Up @@ -1571,8 +1576,8 @@ One further option tunes the hooks' shared plumbing rather than a single guard:
some genuine stalls are still denied for it. On a shell whose `read -t`
accepts fractional values the bound is read in four slices, so a stall is
declared within a quarter of the configured interval of it. That quarter is
the limit of the approximation, and it errs toward waiting rather than toward
calling a live producer dead. Where fractional timeouts are unavailable (Bash
the limit of the approximation, and it waits longer rather than
declaring a live producer dead. Where fractional timeouts are unavailable (Bash
3.2, the macOS system shell) the bound is read as one window instead, and a
producer that sends bytes and then goes silent can take up to **two** intervals
to be declared stalled. A value this shell's
Expand Down Expand Up @@ -1972,12 +1977,13 @@ For a Claude Code release without `plugin configure`, see [Plugin install](https
### Unwatched sessions

block-dangerous-git and block-root-delete-target ask instead of blocking when
`CLAUDE_CODE_SESSION_ATTENDED` is `1`. Every interactive session reads `1`, including one
left running with nobody at it, and there the ask waits for an answer that never comes.
`CLAUDE_CODE_SESSION_ATTENDED` is `1`, and settings-write-ask asks only then, denying
otherwise. Every interactive session reads `1`, including one
left running with nobody at it, and there the ask blocks with nobody to answer it.
Claude Code tells a hook nothing about whether a person is watching, so the session has to
say so: set `GUARDRAILS_SESSION_UNWATCHED=1` in the environment you start it from, or under
`env` in a settings file. Then those guards block as they do in `claude -p`, and the reason
ends with the command for a person to run later. Any other value, or none, leaves the ask in
ends with the command for a person to run later; settings-write-ask denies the settings edit. Any other value, or none, leaves the ask in
place. The variable can only turn an ask into a block, so a repository that sets it in its
own settings loosens nothing.

Expand Down
16 changes: 11 additions & 5 deletions plugins/guardrails/hooks/settings-write-ask.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
// PreToolUse checkpoint: any Write/Edit/NotebookEdit aimed at a Claude Code settings
// surface returns permissionDecision "ask", forcing a prompt even in
// auto mode (the classifier may still deny; it cannot silently approve).
// Unattended or unwatched it denies: https://github.com/melodic-software/claude-code-plugins/blob/main/AGENTS.md#unattended-lanes
//
// This is a CHECKPOINT, NOT A GUARANTEE: other hooks, settings, and permission
// modes decide what happens to its ask. README "Settings-write ask" holds the pointer record
Expand Down Expand Up @@ -93,16 +94,21 @@ process.stdin.on('end', () => {
|| (/local/i.test(name) && cwd !== '' && atRoot(localSettingsRoot(cwd))));
if (!live) process.exit(0);

const asks = process.env.CLAUDE_CODE_SESSION_ATTENDED === '1'
&& process.env.GUARDRAILS_SESSION_UNWATCHED !== '1';
// The permission prompt already shows the target path.
const reason = 'guardrails: this edit changes settings for every future session. Check the diff; '
+ (userGlobal
? '/context-budget:audit fix never writes user-global settings, so this write is not from it.'
: 'from /context-budget:audit fix, it should match the config you approved.');
const reason = 'guardrails: this edit changes settings for every future session. '
+ (!asks
? 'Nobody can answer a prompt in this session (unattended, or GUARDRAILS_SESSION_UNWATCHED=1), '
+ 'so it was refused. Do not retry it another way; report the change for a person to make.'
: userGlobal
? 'Check the diff; /context-budget:audit fix never writes user-global settings, so this write is not from it.'
: 'Check the diff; from /context-budget:audit fix, it should match the config you approved.');

process.stdout.write(JSON.stringify({
hookSpecificOutput: {
hookEventName: 'PreToolUse',
permissionDecision: 'ask',
permissionDecision: asks ? 'ask' : 'deny',
permissionDecisionReason: reason,
},
}));
Expand Down
40 changes: 31 additions & 9 deletions plugins/guardrails/hooks/settings-write-ask.test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@
set -uo pipefail

# The session running this test may export these; the hook reads them.
unset CLAUDE_PROJECT_DIR CLAUDE_CONFIG_DIR GIT_DIR GIT_WORK_TREE GIT_CONFIG
unset CLAUDE_PROJECT_DIR CLAUDE_CONFIG_DIR GIT_DIR GIT_WORK_TREE GIT_CONFIG \
CLAUDE_CODE_SESSION_ATTENDED GUARDRAILS_SESSION_UNWATCHED
export GIT_CONFIG_GLOBAL="${GIT_CONFIG_GLOBAL:-/dev/null}" GIT_CONFIG_NOSYSTEM=1

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
Expand All @@ -43,6 +44,13 @@ assert_asks() {
fail "$2 — no ask in output: $1"
fi
}
assert_denies() {
if grep -q '"permissionDecision":"deny"' <<<"$1"; then
ok "$2"
else
fail "$2 — no deny in output: $1"
fi
}
# assert_silent <hook-output> <message> — the payload must pass untouched
assert_silent() {
if [[ -z "$1" ]]; then
Expand All @@ -63,16 +71,12 @@ git -C "$REPO" -c user.name=t -c user.email=t@t -c commit.gpgsign=false -c core.
commit -q --allow-empty -m init
git -C "$REPO" worktree add -q --detach "$WORK/wt"

# run <tool_name> <file_path> [cwd] [env KEY=VALUE] — prints hook stdout
run() {
local tool="$1" path="$2" cwd="${3:-$REPO}" kv="${4:-}"
local tool="$1" path="$2" cwd="${3:-$REPO}"
shift $(($# < 3 ? $# : 3))
local payload
payload=$(printf '{"tool_name":"%s","cwd":"%s","tool_input":{"file_path":"%s"}}' "$tool" "$cwd" "$path")
if [[ -n "$kv" ]]; then
env HOME="$FAKEHOME" "$kv" node "$HOOK" <<<"$payload"
else
env HOME="$FAKEHOME" node "$HOOK" <<<"$payload"
fi
env HOME="$FAKEHOME" CLAUDE_CODE_SESSION_ATTENDED=1 "$@" node "$HOOK" <<<"$payload"
}

assert_asks "$(run Write "$REPO/.claude/settings.json")" \
Expand Down Expand Up @@ -156,9 +160,27 @@ assert_asks "$(run Edit "$REPO/.claude/settings.LOCAL.json")" \

# Windows-style path separators must still match.
# portability-ok: the doubled backslashes are literal JSON escapes for printf, not a GNU regex class
assert_asks "$(printf '{"tool_name":"Write","cwd":"C:\\\\repo","tool_input":{"file_path":"C:\\\\repo\\\\.claude\\\\settings.json"}}' | node "$HOOK")" \
assert_asks "$(printf '{"tool_name":"Write","cwd":"C:\\\\repo","tool_input":{"file_path":"C:\\\\repo\\\\.claude\\\\settings.json"}}' | CLAUDE_CODE_SESSION_ATTENDED=1 node "$HOOK")" \
"backslash paths normalize and ask"

assert_denies "$(printf '{"tool_name":"Write","cwd":"%s","tool_input":{"file_path":"%s/.claude/settings.json"}}' "$REPO" "$REPO" | HOME="$FAKEHOME" node "$HOOK")" \
"CLAUDE_CODE_SESSION_ATTENDED unset denies"

assert_denies "$(run Write "$REPO/.claude/settings.json" "$REPO" "CLAUDE_CODE_SESSION_ATTENDED=0")" \
"CLAUDE_CODE_SESSION_ATTENDED=0 (claude -p, --bg) denies"

assert_denies "$(run Edit "$FAKEHOME/.claude/settings.json" "$REPO" "CLAUDE_CODE_SESSION_ATTENDED=true")" \
"an ATTENDED value other than 1 denies"

assert_denies "$(run Write "$REPO/.claude/settings.json" "$REPO" "GUARDRAILS_SESSION_UNWATCHED=1")" \
"attended but GUARDRAILS_SESSION_UNWATCHED=1 denies"

assert_asks "$(run Write "$REPO/.claude/settings.json" "$REPO" "GUARDRAILS_SESSION_UNWATCHED=0")" \
"attended with GUARDRAILS_SESSION_UNWATCHED other than 1 asks"

assert_silent "$(run Write "$REPO/src/settings.json" "$REPO" "CLAUDE_CODE_SESSION_ATTENDED=0")" \
"unattended, an unmatched path still passes silently"

# The hook is inert unless hooks.json routes the tools to it, so the registered
# matcher is part of the contract.
matcher=$(node -e '
Expand Down
Loading