tooling(hooks): the guards' escape hatch names where it actually works

.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' \

.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

.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

.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

.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

.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

.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'

.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

.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'

.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