From a4f2124a4f8c56d0b58d57f7d6789bcda5dbd8c7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 5 Sep 2026 17:18:21 +0000
Subject: [PATCH] tooling(hooks): the guards' escape hatch names where it
 actually works
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every guard's refusal ended by telling the reader to re-run the blocked thing with
OS_ALLOW_*=1 as a command prefix. A VAR=1 prefix sets the variable in the environment
of THAT COMMAND; the hook is not that command, and it reads the variable from its own
environment — so the one place an operator naturally applies the printed remedy is the
one place it cannot work, and a remedy that does not work is an invitation to route
around the guard.

The hatch stays: it is the repo's sanctioned deliberate exception, named in CLAUDE.md.
What changes is that the sentence now names the environment the hook actually reads and
says plainly that a prefix never reaches it. One wording, byte-identical across all six
message sites, so the objectui twins can mirror it mechanically.

Message text only — no predicate, no env check, no block/allow verdict is touched. Each
matrix gains the absence assertion (the dead prefix remedy is gone) and its positive twin
(the sentence names the environment the hook reads); the Bash matrix also pins the card's
own reproduction, that the prefix spelled as the old message told the reader to spell it
still blocks.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019RfFHiRCSs3JXLK4cwcfox
---
 .../hooks/guard-governed-enqueue.selftest.sh  |  8 ++++
 .claude/hooks/guard-governed-enqueue.sh       |  5 +-
 .../guard-main-checkout-bash.selftest.sh      | 47 +++++++++++++++++++
 .claude/hooks/guard-main-checkout-bash.sh     |  5 +-
 .claude/hooks/guard-main-checkout.selftest.sh | 46 ++++++++++++++++++
 .claude/hooks/guard-main-checkout.sh          | 10 +++-
 .claude/hooks/guard-shared-stash.selftest.sh  | 39 +++++++++++++++
 .claude/hooks/guard-shared-stash.sh           |  5 +-
 .claude/hooks/guard-tree-enum.selftest.sh     | 41 ++++++++++++++++
 .claude/hooks/guard-tree-enum.sh              |  5 +-
 10 files changed, 205 insertions(+), 6 deletions(-)

diff --git a/.claude/hooks/guard-governed-enqueue.selftest.sh b/.claude/hooks/guard-governed-enqueue.selftest.sh
index 6f19676ddf..46a88dea88 100755
--- a/.claude/hooks/guard-governed-enqueue.selftest.sh
+++ b/.claude/hooks/guard-governed-enqueue.selftest.sh
@@ -161,6 +161,14 @@ expect_says 'does NOT re-run on a later approval' 'the no-re-run reason is state
   "$(mcp $AUTO 13794)" "OS_GOVERNED_ENQUEUE_FIXTURE=$F_UNAPPROVED"
 expect_says 'OS_ALLOW_GOVERNED_ENQUEUE=1' 'the deliberate exception is named' \
   "$(mcp $AUTO 13794)" "OS_GOVERNED_ENQUEUE_FIXTURE=$F_UNAPPROVED"
+# …and it names WHERE that variable has to be set. A VAR=1 prefix sets the variable in the
+# environment of THAT COMMAND; this hook is not that command, and it reads its own
+# environment, so a prefix never reaches it (#15971). The `lacks` row is the shape shared
+# with the other four matrices, where the dead prefix remedy was actually printed.
+expect_lacks 're-run with' 'no prefix remedy is offered for the exception' \
+  "$(mcp $AUTO 13794)" "OS_GOVERNED_ENQUEUE_FIXTURE=$F_UNAPPROVED"
+expect_says 'hook itself runs in' 'the exception names the environment this hook reads' \
+  "$(mcp $AUTO 13794)" "OS_GOVERNED_ENQUEUE_FIXTURE=$F_UNAPPROVED"
 expect_says "$HEAD_SHA" 'the current head sha is named so the reader knows which PR state this is' \
   "$(mcp $AUTO 13794)" "OS_GOVERNED_ENQUEUE_FIXTURE=$F_UNAPPROVED"
 expect_says 'does NOT have to sit on the' 'the remedy states the 2026-09-04 predicate, not the retired sha pin' \
diff --git a/.claude/hooks/guard-governed-enqueue.sh b/.claude/hooks/guard-governed-enqueue.sh
index 112b8c5748..961088ab3d 100755
--- a/.claude/hooks/guard-governed-enqueue.sh
+++ b/.claude/hooks/guard-governed-enqueue.sh
@@ -555,6 +555,9 @@ approvals, decided by the register (check-governed-merges.mjs), not here.
 
 Verdict source: check-governed-merges.mjs --test (governed) +
 authorizedApprovalVerdict/GOVERNED_APPROVERS from check-governed-queue-guard.mjs.
-Deliberate exception (you know this one is right): OS_ALLOW_GOVERNED_ENQUEUE=1.
+Deliberate exception (you know this one is right): set OS_ALLOW_GOVERNED_ENQUEUE=1 in the
+environment this hook itself runs in — a local settings "env" entry, or whatever this
+agent process was started with. A VAR=1 prefix on a command sets it for that command
+only, and this hook is not that command, so a prefix never reaches it.
 EOF
 exit 2
diff --git a/.claude/hooks/guard-main-checkout-bash.selftest.sh b/.claude/hooks/guard-main-checkout-bash.selftest.sh
index 9de71357b1..d5943e7616 100755
--- a/.claude/hooks/guard-main-checkout-bash.selftest.sh
+++ b/.claude/hooks/guard-main-checkout-bash.selftest.sh
@@ -84,6 +84,34 @@ expect() { # expect <block|allow> <command> [env…]
   fi
 }
 
+stderr_of() { # stderr_of <command> [env…] -> the refusal text an agent actually reads
+  local cmd="$1"; shift
+  local payload
+  payload="$(jq -nc --arg c "$cmd" --arg w "$CWD" \
+    '{cwd:$w,tool_name:"Bash",tool_input:{command:$c}}')"
+  printf '%s' "$payload" | env "$@" "$hook" 2>&1 >/dev/null
+}
+
+says() { # says <needle> <label> <command> [env…]
+  local needle="$1" label="$2" subject="$3"; shift 3
+  local out; out="$(stderr_of "$subject" "$@")"
+  case "$out" in
+    *"$needle"*) pass=$((pass + 1)); printf '  ok   says   %s\n' "$label" ;;
+    *) fail=$((fail + 1)); printf '  FAIL missing "%s"  %s\n' "$needle" "$label" ;;
+  esac
+}
+
+lacks() { # lacks <needle> <label> <command> [env…]
+  # The direction only an ABSENCE assertion can hold: a remedy that stopped being true stays
+  # in the text a reader acts on long after the thing it described stopped working.
+  local needle="$1" label="$2" subject="$3"; shift 3
+  local out; out="$(stderr_of "$subject" "$@")"
+  case "$out" in
+    *"$needle"*) fail=$((fail + 1)); printf '  FAIL still says "%s"  %s\n' "$needle" "$label" ;;
+    *) pass=$((pass + 1)); printf '  ok   lacks  %s\n' "$label" ;;
+  esac
+}
+
 echo "== writes into the shared PRIMARY checkout are blocked =="
 CWD="$MAIN"
 expect block "sed -i s/a/b/ $MAIN/pkg/x.ts"
@@ -290,6 +318,25 @@ CWD="$MAIN"
 expect allow 'sed -i s/a/b/ pkg/x.ts' OS_ALLOW_MAIN_EDITS=1
 expect allow 'echo x > README.md' OS_ALLOW_MAIN_EDITS=1
 
+echo "== the hatch names WHERE it works: this hook's own environment, never a prefix =="
+# The refusal used to end by telling the reader to re-run the same thing with the variable
+# as a VAR=1 command prefix — an instruction that cannot work where it is printed. A VAR=1
+# prefix sets the variable in the environment of THAT COMMAND; this hook is not that
+# command, and it reads the variable from its own environment, so the prefix changes
+# nothing and the refusal repeats (#15971). An instruction that does not work is an
+# invitation to route around the guard, so both directions are pinned: the dead remedy is
+# gone, and the sentence names the environment the hook actually reads. The `allow` rows
+# next door — the variable really in the hook's environment — are this pair's other half.
+# The first row is the card's own reproduction, kept as a case: the prefix spelled exactly
+# as the old message told the reader to spell it must still BLOCK, because it never reaches
+# this hook. It is the twin of the `allow` rows above, where the same variable is really in
+# the hook's environment.
+CWD="$MAIN"
+expect block "OS_ALLOW_MAIN_EDITS=1 rm -f $MAIN/x"
+expect block 'OS_ALLOW_MAIN_EDITS=1 sed -i s/a/b/ pkg/x.ts'
+lacks 're-run with' 'the refusal no longer prints the prefix remedy' 'sed -i s/a/b/ pkg/x.ts'
+says 'hook itself runs in' 'the refusal names the environment this hook reads' 'sed -i s/a/b/ pkg/x.ts'
+
 echo "== unparseable / absent payload fails open =="
 for probe in '{"tool_name":"Bash","tool_input":{}}' 'not json at all' '{}'; do
   if printf '%s' "$probe" | "$hook" >/dev/null 2>&1; then
diff --git a/.claude/hooks/guard-main-checkout-bash.sh b/.claude/hooks/guard-main-checkout-bash.sh
index 117c74d915..1fd91d0a83 100755
--- a/.claude/hooks/guard-main-checkout-bash.sh
+++ b/.claude/hooks/guard-main-checkout-bash.sh
@@ -571,7 +571,10 @@ Always fine, no flag needed:
   writes into a linked worktree  sed -i … ../${name}-<task>/packages/…
   writes outside any repo        /tmp/…, the scratchpad, \$HOME dotfiles
 
-Deliberate non-task exception: re-run with OS_ALLOW_MAIN_EDITS=1.
+Deliberate non-task exception: set OS_ALLOW_MAIN_EDITS=1 in the
+environment this hook itself runs in — a local settings "env" entry, or whatever this
+agent process was started with. A VAR=1 prefix on a command sets it for that command
+only, and this hook is not that command, so a prefix never reaches it.
 EOF
       exit 2
     fi
diff --git a/.claude/hooks/guard-main-checkout.selftest.sh b/.claude/hooks/guard-main-checkout.selftest.sh
index ffe50a4355..afe706891c 100755
--- a/.claude/hooks/guard-main-checkout.selftest.sh
+++ b/.claude/hooks/guard-main-checkout.selftest.sh
@@ -123,6 +123,31 @@ expect() { # expect <block|allow> <file_path> [env…] — the common case
   check "$want" "$f" "$(payload "$f")" "$@"
 }
 
+stderr_of() { # stderr_of <payload> [env…] -> the refusal text an agent actually reads
+  local payload="$1"; shift
+  ( cd "$CWD" && printf '%s' "$payload" | env CLAUDE_PROJECT_DIR="$PROJ" "$@" "$hook" 2>&1 >/dev/null )
+}
+
+says() { # says <needle> <label> <payload> [env…]
+  local needle="$1" label="$2" subject="$3"; shift 3
+  local out; out="$(stderr_of "$subject" "$@")"
+  case "$out" in
+    *"$needle"*) pass=$((pass + 1)); printf '  ok   says   %s\n' "$label" ;;
+    *) fail=$((fail + 1)); printf '  FAIL missing "%s"  %s\n' "$needle" "$label" ;;
+  esac
+}
+
+lacks() { # lacks <needle> <label> <payload> [env…]
+  # The direction only an ABSENCE assertion can hold: a remedy that stopped being true stays
+  # in the text a reader acts on long after the thing it described stopped working.
+  local needle="$1" label="$2" subject="$3"; shift 3
+  local out; out="$(stderr_of "$subject" "$@")"
+  case "$out" in
+    *"$needle"*) fail=$((fail + 1)); printf '  FAIL still says "%s"  %s\n' "$needle" "$label" ;;
+    *) pass=$((pass + 1)); printf '  ok   lacks  %s\n' "$label" ;;
+  esac
+}
+
 echo "== the core verdict: shared PRIMARY checkout is blocked =="
 expect block "$MAIN/pkg/x.ts"
 expect block "$MAIN/pkg/deep/y.ts"
@@ -194,6 +219,27 @@ check block 'OS_ALLOW_MAIN_EDITS=yes'              "$(payload "$MAIN/pkg/x.ts")"
 check block 'OS_ALLOW_MAIN_EDITS=11'               "$(payload "$MAIN/pkg/x.ts")" OS_ALLOW_MAIN_EDITS=11
 check block 'OS_ALLOW_MAIN_EDITS=" 1" (padded)'    "$(payload "$MAIN/pkg/x.ts")" OS_ALLOW_MAIN_EDITS=" 1"
 
+echo "== the hatch names WHERE it works: this hook's own environment, never a prefix =="
+# The refusal used to end by telling the reader to re-run the same thing with the variable
+# as a VAR=1 command prefix — an instruction that cannot work where it is printed. A VAR=1
+# prefix sets the variable in the environment of THAT COMMAND; this hook is not that
+# command, and it reads the variable from its own environment, so the prefix changes
+# nothing and the refusal repeats (#15971). An instruction that does not work is an
+# invitation to route around the guard, so both directions are pinned: the dead remedy is
+# gone, and the sentence names the environment the hook actually reads. The `allow` rows
+# next door — the variable really in the hook's environment — are this pair's other half.
+# Both of this hook's message sites carry the sentence: the ordinary refusal and the
+# schema-drift refusal, which is why each is asserted separately here.
+CWD="$PLAIN"; PROJ="$PLAIN"
+lacks 're-run with' 'the block message no longer prints the prefix remedy' \
+  "$(payload "$MAIN/pkg/x.ts")"
+says 'hook itself runs in' 'the block message names the environment this hook reads' \
+  "$(payload "$MAIN/pkg/x.ts")"
+lacks 're-run with' 'the drift message no longer prints the prefix remedy' \
+  '{"tool_name":"Edit","tool_input":{}}'
+says 'hook itself runs in' 'the drift message names the environment this hook reads' \
+  '{"tool_name":"Edit","tool_input":{}}'
+
 echo "== a ROUTED tool whose payload lacks its own path key is drift — it blocks, never guesses =="
 # The dangerous branch is the one that turns an unreadable payload into a confident verdict.
 # For a tool this guard is routed, an absent path key is not "no path given", it is the
diff --git a/.claude/hooks/guard-main-checkout.sh b/.claude/hooks/guard-main-checkout.sh
index 2e62396a59..480797e122 100755
--- a/.claude/hooks/guard-main-checkout.sh
+++ b/.claude/hooks/guard-main-checkout.sh
@@ -83,7 +83,10 @@ blocks instead.
 Fix the row for $tool in this hook's known_path_keys table, then re-run
 .claude/hooks/guard-main-checkout.selftest.sh.
 
-Deliberate non-task exception: re-run with OS_ALLOW_MAIN_EDITS=1.
+Deliberate non-task exception: set OS_ALLOW_MAIN_EDITS=1 in the
+environment this hook itself runs in — a local settings "env" entry, or whatever this
+agent process was started with. A VAR=1 prefix on a command sets it for that command
+only, and this hook is not that command, so a prefix never reaches it.
 EOF
   exit 2
 fi
@@ -137,6 +140,9 @@ branch on the shared checkout is NOT enough; you must be in a dedicated worktree
 
 This guard checks the edited file's OWN repo, so sibling repos are covered too.
 
-Deliberate non-task exception: re-run with OS_ALLOW_MAIN_EDITS=1.
+Deliberate non-task exception: set OS_ALLOW_MAIN_EDITS=1 in the
+environment this hook itself runs in — a local settings "env" entry, or whatever this
+agent process was started with. A VAR=1 prefix on a command sets it for that command
+only, and this hook is not that command, so a prefix never reaches it.
 EOF
 exit 2
diff --git a/.claude/hooks/guard-shared-stash.selftest.sh b/.claude/hooks/guard-shared-stash.selftest.sh
index 4cb2b145a8..b606d0f86c 100755
--- a/.claude/hooks/guard-shared-stash.selftest.sh
+++ b/.claude/hooks/guard-shared-stash.selftest.sh
@@ -44,6 +44,33 @@ expect() { # expect <block|allow> <command> [env…]
   fi
 }
 
+stderr_of() { # stderr_of <command> [env…] -> the refusal text an agent actually reads
+  local cmd="$1"; shift
+  local payload
+  payload="$(jq -nc --arg c "$cmd" '{tool_name:"Bash",tool_input:{command:$c}}')"
+  printf '%s' "$payload" | env "$@" "$hook" 2>&1 >/dev/null
+}
+
+says() { # says <needle> <label> <command> [env…]
+  local needle="$1" label="$2" subject="$3"; shift 3
+  local out; out="$(stderr_of "$subject" "$@")"
+  case "$out" in
+    *"$needle"*) pass=$((pass + 1)); printf '  ok   says   %s\n' "$label" ;;
+    *) fail=$((fail + 1)); printf '  FAIL missing "%s"  %s\n' "$needle" "$label" ;;
+  esac
+}
+
+lacks() { # lacks <needle> <label> <command> [env…]
+  # The direction only an ABSENCE assertion can hold: a remedy that stopped being true stays
+  # in the text a reader acts on long after the thing it described stopped working.
+  local needle="$1" label="$2" subject="$3"; shift 3
+  local out; out="$(stderr_of "$subject" "$@")"
+  case "$out" in
+    *"$needle"*) fail=$((fail + 1)); printf '  FAIL still says "%s"  %s\n' "$needle" "$label" ;;
+    *) pass=$((pass + 1)); printf '  ok   lacks  %s\n' "$label" ;;
+  esac
+}
+
 echo "== mutating forms must be blocked =="
 expect block 'git stash'
 expect block 'git stash push -- packages/spec/src/kernel/metadata-plugin.zod.ts'
@@ -134,6 +161,18 @@ expect block "echo 'a \\' ; git stash pop"
 echo "== escape hatch =="
 expect allow 'git stash pop' OS_ALLOW_STASH=1
 
+echo "== the hatch names WHERE it works: this hook's own environment, never a prefix =="
+# The refusal used to end by telling the reader to re-run the same thing with the variable
+# as a VAR=1 command prefix — an instruction that cannot work where it is printed. A VAR=1
+# prefix sets the variable in the environment of THAT COMMAND; this hook is not that
+# command, and it reads the variable from its own environment, so the prefix changes
+# nothing and the refusal repeats (#15971). An instruction that does not work is an
+# invitation to route around the guard, so both directions are pinned: the dead remedy is
+# gone, and the sentence names the environment the hook actually reads. The `allow` rows
+# next door — the variable really in the hook's environment — are this pair's other half.
+lacks 're-run with' 'the refusal no longer prints the prefix remedy' 'git stash pop'
+says 'hook itself runs in' 'the refusal names the environment this hook reads' 'git stash pop'
+
 echo "== payload with no command fails open =="
 if printf '%s' '{"tool_name":"Bash","tool_input":{}}' | "$hook" >/dev/null 2>&1; then
   pass=$((pass + 1)); printf '  ok   allow  (empty tool_input)\n'
diff --git a/.claude/hooks/guard-shared-stash.sh b/.claude/hooks/guard-shared-stash.sh
index 086c457a94..4eb3233cfa 100755
--- a/.claude/hooks/guard-shared-stash.sh
+++ b/.claude/hooks/guard-shared-stash.sh
@@ -221,7 +221,10 @@ Already allowed, no flag needed:
   git stash list | git stash show | git stash create
   git stash apply <sha> | git stash store <sha>    # literal hex id, never stash@{N}
 
-Deliberate exception (the stack really is yours alone): re-run with OS_ALLOW_STASH=1.
+Deliberate exception (the stack really is yours alone): set OS_ALLOW_STASH=1 in the
+environment this hook itself runs in — a local settings "env" entry, or whatever this
+agent process was started with. A VAR=1 prefix on a command sets it for that command
+only, and this hook is not that command, so a prefix never reaches it.
 EOF
   exit 2
 done
diff --git a/.claude/hooks/guard-tree-enum.selftest.sh b/.claude/hooks/guard-tree-enum.selftest.sh
index 460ca1fa17..507b6dc8d3 100755
--- a/.claude/hooks/guard-tree-enum.selftest.sh
+++ b/.claude/hooks/guard-tree-enum.selftest.sh
@@ -47,6 +47,33 @@ expect() { # expect <block|allow> <command> [env…]
   fi
 }
 
+stderr_of() { # stderr_of <command> [env…] -> the refusal text an agent actually reads
+  local cmd="$1"; shift
+  local payload
+  payload="$(jq -nc --arg c "$cmd" '{tool_name:"Bash",tool_input:{command:$c}}')"
+  printf '%s' "$payload" | env "$@" "$hook" 2>&1 >/dev/null
+}
+
+says() { # says <needle> <label> <command> [env…]
+  local needle="$1" label="$2" subject="$3"; shift 3
+  local out; out="$(stderr_of "$subject" "$@")"
+  case "$out" in
+    *"$needle"*) pass=$((pass + 1)); printf '  ok   says   %s\n' "$label" ;;
+    *) fail=$((fail + 1)); printf '  FAIL missing "%s"  %s\n' "$needle" "$label" ;;
+  esac
+}
+
+lacks() { # lacks <needle> <label> <command> [env…]
+  # The direction only an ABSENCE assertion can hold: a remedy that stopped being true stays
+  # in the text a reader acts on long after the thing it described stopped working.
+  local needle="$1" label="$2" subject="$3"; shift 3
+  local out; out="$(stderr_of "$subject" "$@")"
+  case "$out" in
+    *"$needle"*) fail=$((fail + 1)); printf '  FAIL still says "%s"  %s\n' "$needle" "$label" ;;
+    *) pass=$((pass + 1)); printf '  ok   lacks  %s\n' "$label" ;;
+  esac
+}
+
 echo "== THE MEASURED SIGNATURE: working-tree list + origin/main read in one command =="
 # objectui, 2026-08-29 — the loop that reported "no workflow subscribes ready_for_review"
 expect block 'for f in .github/workflows/*.yml; do git show "origin/main:$f" | grep -q ready_for_review && echo "$f"; done'
@@ -101,6 +128,20 @@ expect allow 'git worktree add ../objectstack-issue-13305 -b claude/issue-13305
 echo "== the deliberate exception releases it =="
 expect allow 'for f in .github/workflows/*.yml; do git show "origin/main:$f"; done' OS_ALLOW_TREE_ENUM=1
 
+echo "== the hatch names WHERE it works: this hook's own environment, never a prefix =="
+# The refusal used to end by telling the reader to re-run the same thing with the variable
+# as a VAR=1 command prefix — an instruction that cannot work where it is printed. A VAR=1
+# prefix sets the variable in the environment of THAT COMMAND; this hook is not that
+# command, and it reads the variable from its own environment, so the prefix changes
+# nothing and the refusal repeats (#15971). An instruction that does not work is an
+# invitation to route around the guard, so both directions are pinned: the dead remedy is
+# gone, and the sentence names the environment the hook actually reads. The `allow` rows
+# next door — the variable really in the hook's environment — are this pair's other half.
+lacks 're-run with' 'the refusal no longer prints the prefix remedy' \
+  'for f in .github/workflows/*.yml; do git show "origin/main:$f"; done'
+says 'hook itself runs in' 'the refusal names the environment this hook reads' \
+  'for f in .github/workflows/*.yml; do git show "origin/main:$f"; done'
+
 echo "== fails OPEN on payloads it cannot parse =="
 printf '%s' '{"tool_name":"Bash","tool_input":{}}' | "$hook" >/dev/null 2>&1
 if [ $? -eq 0 ]; then pass=$((pass + 1)); printf '  ok   allow  <no command in payload>\n'
diff --git a/.claude/hooks/guard-tree-enum.sh b/.claude/hooks/guard-tree-enum.sh
index 6f536d4157..b8f2029be6 100755
--- a/.claude/hooks/guard-tree-enum.sh
+++ b/.claude/hooks/guard-tree-enum.sh
@@ -312,7 +312,10 @@ A command that enumerates with git ls-tree is never blocked here, however it the
 Either half alone is fine too — this fires only on the two together.
 
 Deliberate exception (the working tree really is the population you mean — e.g. asking
-what YOUR branch changed): re-run with OS_ALLOW_TREE_ENUM=1.
+what YOUR branch changed): set OS_ALLOW_TREE_ENUM=1 in the
+environment this hook itself runs in — a local settings "env" entry, or whatever this
+agent process was started with. A VAR=1 prefix on a command sets it for that command
+only, and this hook is not that command, so a prefix never reaches it.
 EOF
   exit 2
 fi