Hook Block Decisions Hold in More Cases Since Claude Code 2.1.326¶
Claude Code 2.1.326 makes a hook's block decision hold in more cases. The changelog does not list them, so audit every hook that prints one.
Claude Code 2.1.326 (November 16, 2026) "Changed a hook’s "decision": "block" to hold in more cases, so a hook that always prints one may start blocking calls" (changelog 2.1.326). The entry names no cases, so you cannot check whether your hook falls in one. Treat every block your hook prints as live, and make it print one only when it means to refuse.
What a block does on each event¶
"block" is the only value decision takes. The hooks reference says: "To allow the action to proceed, omit decision from your JSON, or exit 0 without any JSON at all". A hook that prints {"decision": "block"} on its allow path asks Claude Code to block.
What that costs depends on the event:
| Event | Effect of "block", per the hooks reference |
|---|---|
UserPromptSubmit |
"rejects the prompt" |
PostToolUse |
"adds the reason next to the tool result". The tool has already run. |
Stop |
"prevents Claude from stopping". After eight consecutive continuations the cap overrides the next block; the count resets when Claude calls a tool |
PreToolUse |
Top-level decision is deprecated, and "block" maps to "deny" |
An old-format PreToolUse hook still gates tool calls. The reference says the deprecated values ""approve" and "block" map to "allow" and "deny" respectively" (hooks reference).
A printed block has gone unhonored before. The reference records that "Claude Code ignored a top-level decision from Elicitation and ElicitationResult hooks from v2.1.105 until the fix in v2.1.284" (hooks reference).
Find and fix the hooks¶
- List the hooks that run. The hooks guide says to "Run
/hooksand confirm the hook appears under the correct event", and warns that/hooks"doesn’t list hooks from a skill that hasn’t been invoked in the session" (hooks guide). Invoke those skills first, then run/hooksagain. - In each script, find every place it prints
decision. Check that each print sits inside a branch that runs only when the hook means to refuse. - On the allow path, exit 0 and print nothing, or print JSON without
decision. Build the JSON "with a JSON encoder such asjqinstead of string concatenation" (hooks guide). - Move
PreToolUsehooks tohookSpecificOutput.permissionDecision, which the reference says to use instead.
Test before you upgrade¶
The hooks guide gives a manual test: pipe sample JSON to the script and check its exit code (hooks guide). Run it on inputs the hook should allow:
echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $?
If stdout carries "decision": "block" for an input the hook should allow, the hook blocks unconditionally on that path. After the upgrade, start Claude Code with claude --debug-file <path>, which writes hook execution details to that file (hooks reference), and look for blocks you did not expect.
Why it works¶
On exit 0, Claude Code applies the JSON output fields a hook prints (hooks reference), and the documented way to allow is to omit decision (hooks reference). A hook that never prints a block on an allow path has nothing for a newly honored case to act on. The audit removes the need to know which cases 2.1.326 covers.
When this backfires¶
- A hook meant to refuse every call its matcher catches gets flagged for nothing. Leave it alone.
- Async hooks gain nothing from the audit. The reference says "Async hooks can’t block or control Claude’s behavior" (hooks reference).
- A text search for
"block"misses JSON built from a template or in another language. Read the code path as well as the string. - A
Stophook that always blocks shows up as extra continuations, not as a refused call, so it is easy to miss in a short test.
Key Takeaways¶
- The 2.1.326 entry does not list its cases, so an audit cannot target them.
- Print
decisiononly inside the branch that refuses. To allow, omit it and exit 0. - Old-format
PreToolUsehooks still deny on"block". Move them topermissionDecision. - Pipe allow inputs through each hook and check stdout before you upgrade.