Skip to content
← Back to release · 2.1.299
Improvements / v2.1.299

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 PreToolUse or PermissionRequest command hook that fails with onFailure unset 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_tool hook's server isn't connected, or its tool returns an error. With "block" set on an event such as PreToolUse or UserPromptSubmit, a non-empty answer also counts unless it's {} or JSON that sets a hook output field other than reason
  • 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, and TeammateIdle hooks: 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 async or asyncRewake

[!NOTE]

If you use Code Mode, failures on PreToolUse work differently. See Tool call refused by a hook.

Documentation snapshot · 2026-11-20

Change details