From c5da747399dc3dd9e286f580528673daf2c7a108 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 21 Nov 2026 12:20:15 -0500 Subject: [PATCH 1/2] fix(guardrails): deny settings writes when nobody can answer the prompt settings-write-ask returned permissionDecision "ask" in every session, so a claude --bg lane that edited a settings file waited on a prompt nobody answers. AGENTS.md "Unattended lanes" says lane sessions carry no hook ask. The hook now asks only when CLAUDE_CODE_SESSION_ATTENDED is exactly 1 and GUARDRAILS_SESSION_UNWATCHED is not 1, the test refuse.sh uses for the blocking guards, and denies otherwise. The contract test covers unset, 0, a non-1 value and the unwatched flag. Co-Authored-By: Claude Opus 5.5 --- ...fix-guardrails-unattended-deny-79660f88.md | 8 ++++ ...fix-guardrails-unattended-deny-32187901.md | 10 +++++ plugins/context-budget/skills/audit/SKILL.md | 3 +- plugins/guardrails/README.md | 18 ++++++--- .../guardrails/hooks/settings-write-ask.mjs | 16 +++++--- .../hooks/settings-write-ask.test.sh | 40 ++++++++++++++----- 6 files changed, 74 insertions(+), 21 deletions(-) create mode 100644 .changes/context-budget/fix-guardrails-unattended-deny-79660f88.md create mode 100644 .changes/guardrails/fix-guardrails-unattended-deny-32187901.md diff --git a/.changes/context-budget/fix-guardrails-unattended-deny-79660f88.md b/.changes/context-budget/fix-guardrails-unattended-deny-79660f88.md new file mode 100644 index 00000000000..e745361b7e3 --- /dev/null +++ b/.changes/context-budget/fix-guardrails-unattended-deny-79660f88.md @@ -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. diff --git a/.changes/guardrails/fix-guardrails-unattended-deny-32187901.md b/.changes/guardrails/fix-guardrails-unattended-deny-32187901.md new file mode 100644 index 00000000000..4ea02937495 --- /dev/null +++ b/.changes/guardrails/fix-guardrails-unattended-deny-32187901.md @@ -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. diff --git a/plugins/context-budget/skills/audit/SKILL.md b/plugins/context-budget/skills/audit/SKILL.md index 21c042f1c7b..8c5fa0b4a8f 100644 --- a/plugins/context-budget/skills/audit/SKILL.md +++ b/plugins/context-budget/skills/audit/SKILL.md @@ -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, diff --git a/plugins/guardrails/README.md b/plugins/guardrails/README.md index a096df2ed41..c2349c7ceb4 100644 --- a/plugins/guardrails/README.md +++ b/plugins/guardrails/README.md @@ -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 -R / --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 -R / --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=` 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). | @@ -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) @@ -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 @@ -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 +`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 waits for an answer that never comes. 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. diff --git a/plugins/guardrails/hooks/settings-write-ask.mjs b/plugins/guardrails/hooks/settings-write-ask.mjs index b55f64dbf93..6e0f83e5a58 100755 --- a/plugins/guardrails/hooks/settings-write-ask.mjs +++ b/plugins/guardrails/hooks/settings-write-ask.mjs @@ -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 @@ -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, }, })); diff --git a/plugins/guardrails/hooks/settings-write-ask.test.sh b/plugins/guardrails/hooks/settings-write-ask.test.sh index 399fdb36baa..2fdcce3dbde 100755 --- a/plugins/guardrails/hooks/settings-write-ask.test.sh +++ b/plugins/guardrails/hooks/settings-write-ask.test.sh @@ -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)" @@ -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 — the payload must pass untouched assert_silent() { if [[ -z "$1" ]]; then @@ -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 [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")" \ @@ -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 ' From d230c046bcd4c8219c7f35fdc2a7b738e8a68e90 Mon Sep 17 00:00:00 2001 From: "melodic-automation-lanes[bot]" <337595936+melodic-automation-lanes[bot]@users.noreply.github.com> Date: Sat, 21 Nov 2026 21:11:57 +0000 Subject: [PATCH 2/2] Apply fix-docs on fix/guardrails-unattended-deny Lane-Activity: pr-refine/fix-docs --- plugins/guardrails/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/plugins/guardrails/README.md b/plugins/guardrails/README.md index c2349c7ceb4..fa2cdcd37cc 100644 --- a/plugins/guardrails/README.md +++ b/plugins/guardrails/README.md @@ -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 @@ -460,7 +460,7 @@ out of scope until such a signal exists. `mcp__plugin__github__`. Pointer: . 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` @@ -1334,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. @@ -1576,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 @@ -1979,7 +1979,7 @@ For a Claude Code release without `plugin configure`, see [Plugin install](https block-dangerous-git and block-root-delete-target ask instead of blocking when `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 waits for an answer that never comes. +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