Refuse actions when hooks cannot answer
CHANGELOG · original
Changed actions a plugin hook can block to be refused, not let through, when the hook cannot be handed them or cannot hand back its answer; a tool that already ran has its result withheld Open official changelog ↗ Documentation
Documentation excerpt
Block the action when a hook fails
On most events, when a hook fails or times out, Claude Code still carries out the action. A policy hook with a wrong path or a crashing script then lets everything through. To block the action instead, set "onFailure": "block" on a command, http, or mcp_tool hook. Requires Claude Code v2.1.295 or later. On mcp_tool hooks, onFailure requires v2.1.328 or later.
For Agent SDK callback hooks, see Block the action when a callback fails.
[!NOTE]
On Windows without Git Bash, a shell-form
PreToolUseorPermissionRequestcommand hook that fails withonFailureunset can instead block the tool call.
This PreToolUse hook in .claude/settings.json runs a project script before each Bash command, and blocks the command if the 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 a Bash command such as ls. Claude Code blocks the call, and the error includes failed; blocking because onFailure is "block" followed by node's own error output, trimmed here to one line:
PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block"
Error: Cannot find module '/path/to/project/.claude/hooks/check-command.js'
After a timeout, the message says timed out instead of failed. Without onFailure set, the same missing script is a non-blocking error and ls runs.
Each of these counts as a failure:
- Can't start: a command hook fails to start, for example because the script or executable doesn't exist
- Exit code other than 0 or 2: counts for a command hook even if it printed JSON that allows the action, such as
permissionDecision: "allow". To return a JSON decision, exit 0 - HTTP error: an HTTP hook's connection fails, or the response status isn't 2xx
- MCP failure: an
mcp_toolhook's server isn't connected, or its tool returns an error. With"block"set on an event such asPreToolUseorUserPromptSubmit, a non-empty answer also counts unless it's{}or JSON that sets a hook output field other thanreason - Timeout: the hook reaches its
timeout - Invalid output: the JSON output can't be parsed or fails schema validation. For an HTTP hook, a 2xx body that is neither empty nor a JSON object also counts. Plain-text stdout from a command hook isn't a failure
With "block" set, a failure does what exit code 2 does on that event, except on PermissionRequest, where it denies the request. For example, a PreToolUse failure blocks the tool call and a UserPromptSubmit failure blocks the prompt.
The field has no effect on these hooks:
Stop,SubagentStop,TaskCompleted, andTeammateIdlehooks: exit code 2 on these events sends Claude back to keep working, and Claude can't repair a hook that won't run- Background command hooks: command hooks that set
asyncorasyncRewake
[!NOTE]
If you use Code Mode, failures on
PreToolUsework differently. See Tool call refused by a hook.
Documentation snapshot · 2026-11-20