fix(hooks): block() must exit 0 with stdout JSON, not exit 2 (v6.1.3)#47
Merged
Merged
Conversation
Both Claude Code and Codex ignore stdout entirely when a hook exits with
code 2 -- the blocking reason must be on stderr. The existing block()
helper in hooks/pre-tool-scope-guard and hooks/subagent-scope-guard was
emitting `{"decision":"block","reason":"..."}` on stdout and then exiting
2, which means:
- Codex surfaced: "PreToolUse hook exited with code 2 but did not write
a blocking reason to stderr"
- Claude Code silently dropped the reason (the tool call was blocked but
no reason text reached the agent or user)
Fixed both hooks by switching to `exit 0` with stdout JSON (the documented
decision-control path on both hosts) and mirroring the reason to stderr
as belt + suspenders. This mirrors the pattern already in use in
hooks/completion-claim-guard, which was correct.
Also switched `jq -n` to `jq -nc` so the emitted JSON is compact and
matches what existing grep-based hook tests look for.
Added two new regression tests in tests/hook-contracts.sh that assert
blocks exit 0, emit stdout JSON, AND mirror the reason to stderr. Both
trigger easily-reproducible block paths: force-push (pre-tool) and
manifest drift (subagent-stop).
Version bump 6.1.2 -> 6.1.3 across all four manifests.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
intel352
added a commit
that referenced
this pull request
May 28, 2026
…nd checks (v6.1.4) (#48) The force-push, history-rewrite, locked-plan-push, and default-branch-push checks were scanning the raw tool_input.command instead of the quote-stripped cmd_no_quotes form (which was already computed for the SUPERPOWERS_ self- bypass detector). The SUPERPOWERS_ check was correct; the four destructive- command checks were not. Real-world false positive encountered during v6.1.3 release: the PR body heredoc for PR #47 quoted the force-push command verbatim as an example in the changelog text. The hook scanned the full Bash command (including the --body arg) and matched the example as a real force push, blocking the very PR meant to ship the v6.1.3 fix. Worked around with --body-file that release. Now fixed at the regex level. Trade-off: an attacker who hides a destructive command inside quoted args would slip through quote-strip. Acceptable edge case vs the much more common false-positive on PR bodies and inline documentation. Same trade-off the SUPERPOWERS_ check already accepted. Added regression test in tests/hook-contracts.sh that asserts no block fires when force-push appears inside a quoted string. Version bump 6.1.3 -> 6.1.4 across all four manifests. Co-authored-by: Jon Langevin <jon@gocodealone.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
hooks/pre-tool-scope-guardandhooks/subagent-scope-guardwere emitting{"decision":"block","reason":"..."}on stdout and thenexit 2, which meant Codex surfacedPreToolUse hook exited with code 2 but did not write a blocking reason to stderrand Claude Code silently dropped the reason text.block()helpers toexit 0with stdout JSON (the documented decision-control path on both hosts per the May 2026 docs) and mirrored the reason to stderr as belt-and-suspenders. Same pattern already in use byhooks/completion-claim-guard.jq -n→jq -ncso emitted JSON is compact (matches existing grep-based test expectations; saves bytes).block()exits 0 + emits stdout JSON + mirrors reason to stderr. Triggers are easily-reproducible: force-push for PreToolUse, manifest drift for SubagentStop.Note:
hooks/scope-lock-{abandon,complete,publish}also use exit 2 but those are CLI scripts invoked via Bash (not registered hooks), where exit 2 is just non-zero error semantics. They already write to stderr first, so they're correct.Test plan
tests/hook-contracts.sh— 49 assertions including 2 new "Codex compat" regressions PASStests/version-check.sh— manifests agree on 6.1.3pre-tool-scope-guardnow prints JSON to stdout + reason to stderr + exits 0References
{"decision":"block","reason":"..."}JSON on stdout with exit 0 is the supported equivalent.Followup
Pre-existing bug:
pre-tool-scope-guard's force-push regex matches the literal stringgit push --forceanywhere in the command line, including inside heredoc bodies / quoted documentation strings. Encountered while opening this very PR — had to switch to--body-fileto avoid a false-positive self-block. Should be fixed by applying the same quote-stripping the SUPERPOWERS_ self-bypass detector already does (line 151). Not bundled into this PR to keep scope tight; will file separately.🤖 Generated with Claude Code