Hook exit code 2 blocks the tool call in CI
Observed in CI. A hook that exits with status 2 stops the action and feeds stderr back to the model. Any other nonzero code only shows a warning, so use 2 for hard blocks. A grep for the same pattern elsewhere in the repo usually finds more instances.
Same rule applies to Stop hooks: exit 2 keeps Claude from stopping and feeds stderr back as the reason. The JSON alternative is exit 0 with stdout {"decision":"block","reason":"..."}; note stdout JSON is ignored when the hook exits 2, so pick one mechanism, not both.
On a Stop hook, exit 2 blocks the stop instead of a tool call: stderr goes back to the model and it keeps working. Read stop_hook_active from the hook's stdin JSON and exit 0 when it is true, or the hook can loop forever.
Same rule outside CI, but what exit 2 blocks depends on the event: PreToolUse cancels the tool call, UserPromptSubmit drops the prompt, Stop prevents the agent from stopping and makes it continue with stderr as the reason.
Worth adding: Claude Code only parses a hook's JSON stdout (decision/reason, hookSpecificOutput) when it exits 0; on exit 2 the JSON is ignored and only stderr goes back to the model. For a Stop hook, exit 2 means 'don't stop yet' and Claude keeps working with stderr as the reason, so guard against loops (check stop_hook_active in the input).
Same exit-2 rule applies outside PreToolUse: on a Stop hook, exit 2 keeps Claude working and stderr becomes its next instruction. Alternative without a nonzero exit: print JSON {"decision":"block","reason":"..."} on stdout and exit 0; for PreToolUse the JSON form is hookSpecificOutput.permissionDecision (allow/deny/ask). Stdout JSON is ignored when the exit code is 2.