Hooks that block Claude's actions, and fail closed
Exit code 2, onFailure block and a mod's tool.call deny: three ways to stop a Claude Code action, and how to make a policy hook fail closed instead of open.
Published . Checked against Claude Code v2.1.329. This site is unofficial; the sources under each section are Anthropic's own pages.
By default, a broken hook lets the action through
On most events, when a hook fails or times out, Claude Code still carries out the action. That is the right default for a formatter, and the wrong one for a policy hook: a wrong script path or a crash then lets every tool call through. Claude Code gives you three ways to block an action, and two ways to make sure a failing guard blocks too.
Note
Anthropic's docs don't use the term "action hooks". This article covers the hooks that can stop an action, which is what the term usually means.
Block on purpose: exit code 2
A command hook blocks by exiting with code 2. On a PreToolUse hook that blocks the tool call, and on UserPromptSubmit it blocks the prompt. Your stderr is the reason. On PreToolUse, a call blocked with exit 2 stays blocked even if the hook also prints JSON that allows it.
Exit code 1 does not block. Without valid JSON output it is a non-blocking error, even though 1 is the usual Unix failure code. If a hook enforces a policy, exit 2. When your script calls another check, pass the check's exit code on, for example with || exit $?, or the hook exits with its last line's code.
Not every event can be blocked. PermissionRequest ignores exit 2, so deny through its decision object instead. On Stop, SubagentStop, TaskCompleted and TeammateIdle, exit 2 sends Claude back to work rather than refusing anything.
Fail closed: onFailure block
Set "onFailure": "block" on a command, http or mcp_tool hook, and a failure does what exit code 2 does on that event, except on PermissionRequest, where it denies the request. It needs v2.1.295 or later, and v2.1.328 or later on mcp_tool hooks. This hook blocks every Bash command if its check script fails:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "node",
"args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],
"onFailure": "block"
}
]
}
]
}
}To test it, leave check-command.js missing and ask Claude to run ls. The call is blocked with failed; blocking because onFailure is "block". Without the field, the same missing script is a non-blocking error and ls runs. These count as a failure:
- A command hook that can't start, or exits with a code other than 0 or 2, even if it printed JSON that allows the action
- An HTTP hook whose connection fails or whose status isn't 2xx
- An
mcp_toolhook whose server isn't connected or whose tool returns an error - A hook that reaches its
timeout - Output that can't be parsed or fails schema validation
The field has no effect on Stop, SubagentStop, TaskCompleted and TeammateIdle hooks, or on command hooks that run with async or asyncRewake. Code Mode handles PreToolUse failures differently: a hook that can't start, is killed or times out refuses the call there even without the field. See Code Mode in Claude Code.
Source: Hooks reference (opens in a new tab), Claude Code changelog (opens in a new tab), Run tool calls from code with Code Mode (opens in a new tab)
Block from a mod: tool.call and .catch
A mod's tool.call hook sees each tool Claude is about to use, including subagent and MCP calls. It refuses a call by returning { deny } without calling next, and Claude reads the deny text as the tool's result, so write it as an instruction. Like a classic hook, a mod hook that throws or times out is skipped and the call goes on. Chain a .catch handler onto the registration to make it fail closed:
on('tool.call', { tool: 'Bash' }, guard).catch(async ($, e, next) => {
// guard had already called next, so return what came back
if (next.called) return next(e)
// next.error.kind says why the handler was asked, such as 'throw' or 'timeout'
return { deny: 'The command guard failed, so this command was not run: ' + next.error.kind }
})The handler has a shorter time limit of its own, and if it fails too, the hook is skipped as if it had no handler. Hooks in managed settings run before any mod's tool.call hook, and when one blocks the call, no mod hook runs for it.
Which one to use
- For a fixed command or path, use a permission rule such as
Bash(npm test). It takes no code. - For a decision that needs logic, use a
PreToolUsehook that exits 2, and add"onFailure": "block"so a broken hook can't wave calls through. - To ask the user first, use a mod: a
tool.callhook can wait on$.ui.askand refuse when nobody answers. - For a decision that depends on the moment, such as the current Git branch, the mods docs point to the
tool.checkevent.
Source: React to events with a mod (opens in a new tab), Hooks reference (opens in a new tab)