What
A hook is a command you set to run at a given moment. A PreToolUse hook runs before a tool call and can block it. When such a hook does not finish, Claude Code now looks at its onFailure setting:
- With
onFailure: continue, the tool call goes ahead. - Otherwise the call is blocked, and the message saying the hook did not finish can now include advice about what to do.
Before, only a narrower set of calls was refused this way, with a fixed message.
Why
Hook authors can choose whether an unfinished hook lets calls through or stops them, and can give guidance when it stops them.
Names in the bundlePreToolUseonFailure
The entry above is what we published on the day. These lines were added later, as Anthropic's own pages caught up, and they sit beside the original rather than replacing it.
Added since
A small documentation edit on Hooks reference touched a line naming PreToolUse after this was published.
An [Agent SDK callback hook](/docs/en/agent-sdk/hooks) on `PreToolUse` that exceeds its timeout blocks the tool call, and Claude receives an error result naming the timeout.hooks see the edit
Confirmed since
Anthropic's documentation has since written up onFailure, on MCP, plugins, skills, and hooks.
A [`PreToolUse`](https://code.claude.com/docs/en/hooks#pretooluse) hook that runs this way and has no `onFailure` field blocks the tool call when it fails or times out. The hook error that Claude receives includes `blocking because Git Bas…third-party/claude-desktop/extensions see the edit
Confirmed since
Anthropic's documentation has since written up PreToolUse, on Orchestrate subagents at scale with dynamic workflows.
* **A hook**: return `"allow"` for the call from a [`PreToolUse`](/docs/en/hooks#pretooluse) hook. In [plan mode](/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode), the workflow doesn't start on the hook's approval alone, s…workflows see the edit
Two sources agreeTwo things we can check say the same as this entry.
Anthropic's documentation agrees
Anthropic's documentation has since written up PreToolUse, on Orchestrate subagents at scale with dynamic workflows.
Anthropic's release notes agree
Fixed plan mode running a write (an MCP tool's, a file's, a shell command's) that a PreToolUse hook or a mod's tool.check hook allowed