PreToolUse
A Claude Code hook event, read out of the shipped bundle. No mined inventory carries it: everything below comes from what this site has written about it.
Before a tool call executes. Can block it
Anthropic's own wording. Read off Hooks reference, captured 2026-10-22.
In the changelogs
79Releases whose published page names PreToolUse.
-
v2.1.307
Hook decisions on tool use now go through a central permission check
Allow, ask and deny decisions from PreToolUse and PermissionRequest hooks now pass through a central permission check that handlers can answer
named in this entry, found in this entry's text
-
v2.1.304
Permission request hooks can refuse a tool before you are asked
When a tool would ask for your permission, PermissionRequest hooks can now run first and turn that question into a refusal
found in this entry's text
-
v2.1.304
/claude-api now blocks some
antcommands before they runThe /claude-api skill now blocks
antcommands with certain IDs and managed-agents-secure commands changed from the guidefound in this entry's text
-
v2.1.301
PreToolUse hook results now record which plugin they came from
Results from PreToolUse hooks now carry the ID of the plugin that supplied the hook as a separate value
found in this entry's text, named in this entry
-
v2.1.301
Permission decisions made by hooks now record which hook made them
When a hook allows or blocks a tool, Claude Code now records the hook's event, where the hook came from and, for plugins, the plugin's ID
found in this entry's text, named in this entry
-
v2.1.300
Hook-changed tool input is checked and can be refused if it is malformed
When a hook changes a tool call's input, Claude Code checks it against what the tool accepts and can refuse the call if it does not fit
found in this entry's text, named in this entry
-
v2.1.300
An unfinished PreToolUse hook no longer replaces an existing deny
If a
PreToolUsehook does not finish and the tool call is already denied, the original deny now stays in placefound in this entry's text, named in this entry
-
v2.1.300
Hooks and mods are held back when organization settings can't be read
If your organization's managed settings can't be read, your hooks and mods stay off and tool calls a hook would check ask for permission
found in this entry's text
-
v2.1.300
Tool calls blocked by an unfinished PreToolUse hook are now recorded
When a PreToolUse hook does not finish and Claude Code refuses the tool call, that refusal is now recorded and marked as such
found in this entry's text
-
v2.1.300
Startup warning now says when invalid managed settings drop security hooks
If invalid managed settings include PreToolUse or PermissionRequest hooks, the startup message now says those hooks are not loaded
found in this entry's text
-
v2.1.300
Clearer warning when a managed hook cannot be loaded
Settings checks now explain that an unloadable managed hook, and every other hook in that file, does not run
found in this entry's text
-
v2.1.299
Apps built on the SDK can word their own permission prompts
Apps embedding Claude Code can supply the wording of a permission prompt from a PreToolUse hook, off unless switched on remotely
found in this entry's text, named in this entry
-
v2.1.299
Unfinished PreToolUse hooks now respect onFailure: continue
A
PreToolUsehook withonFailure: continuethat does not finish lets the call run; otherwise the call is blocked with advicefound in this entry's text, named in this entry
-
v2.1.296
Blocking
PreToolUsehooks now show their full reasonWhen a
PreToolUsehook blocks a tool, the hook's extra text is now added to the error message instead of being lostfound in this entry's text
-
v2.1.296
PreToolUse hooks that stop a turn now get the same note as PostToolUse
A PreToolUse hook that stops Claude from continuing now produces the same stop note as PostToolUse, and 422 API errors are shown as 400
found in this entry's text
-
v2.1.295
A new setting limits what your own skills, agents and hooks can do
Setting CLAUDE_CODE_RESTRICT_PERSONAL_CONFIG stops your own skills, agents and hooks from widening permissions, and makes key hooks required
found in this entry's text
-
v2.1.295
New option to block a session when your personal settings file is broken
With
CLAUDE_CODE_RESTRICT_PERSONAL_CONFIGset, errors in your user settings file block every prompt and tool call until they are fixedfound in this entry's text
-
v2.1.295
Hook permission answers are read differently
Claude Code now reads every
PermissionRequesthook answer as allow, and aPreToolUseanswer only when it is set and is not denyfound in this entry's text
-
v2.1.295
Plugin hooks on another machine can no longer change a tool call's input
If a plugin hook on another machine changes a tool call's input, Claude Code now refuses the call instead of running it
found in this entry's text
-
v2.1.293
Hooks running away from the tool can no longer rewrite its input or result
Hooks that ran somewhere other than the tool can no longer change its input or result: input changes become a denial, result changes are dropped
found in this entry's text
-
v2.1.290
PreToolUse hook overrides log the deny reason type, with a second permission check
When a deny rule overrides a PreToolUse hook, the debug log shows the deny's reason type and a second permission check can apply
found in this entry's text
-
v2.1.290
PreToolUse hooks can be matched against more than one tool name
Claude Code's check for PreToolUse hooks now matches against a wider list of names worked out from an extra tool name, not just one
found in this entry's text, named in this entry
-
v2.1.289
Plugin
tool.checkhooks get an extra input when a PreToolUse hook asks for permissionWhen a PreToolUse hook has asked for permission, plugin tool checks are now built with that hook's ask passed in as an extra input
named in this entry, found in this entry's text
-
v2.1.289
Warnings for plugin hooks that were not applied no longer say "skipped"
A plugin hook that was not applied now gets a warning reading "<event> hook: <reason>" instead of "<event> hook skipped: <reason>"
found in this entry's text
-
v2.1.288
PreToolUsehook ask decisions can now be marked as heldWhen a
PreToolUsehook's ask decision is held for a call the server handles, the result now says sofound in this entry's text
-
v2.1.288
Shorter message when a PreToolUse hook cannot run
When a PreToolUse hook cannot run and blocks a tool call, the message now says plainly that the call was not run
found in this entry's text
-
v2.1.288
Shorter reasons when a hook is not sent to a cloud session
With
claude --cloud, notices about hooks held back are shorter and give a cause, with a warning when a changed guard hook blocks tool callsfound in this entry's text
-
v2.1.287
Clearer auto mode messages when a hook rewrites a tool call
Auto mode now tells Claude when a
PreToolUsehook rewrote a call, so it can retry once and then explain the cause to youfound in this entry's text
-
v2.1.287
Cloud hook error now tells you how to fix it with
CLAUDE_CODE_TMPDIRWhen a cloud session cannot store a verified hook copy safely, the error now explains what is blocked and suggests setting
CLAUDE_CODE_TMPDIRfound in this entry's text
-
v2.1.285
Plugin hook modules can block a tool call before it runs
A plugin hook that runs before a tool call can now deny it, and plugins get a clear reason when a message they add to the session is refused
found in this entry's text, named in this entry
-
v2.1.284
Usage reports now say why a project hook could not run in the sandbox for remote calls
When a project pre-tool hook cannot be sandboxed for a remotely served tool call, Claude Code now records why; the hook's outcome is unchanged
found in this entry's text
-
v2.1.284
Headless runs now also wait for MCP servers named in allow rules and hooks
Before a -p run's first turn, Claude Code now also counts MCP servers named in allow rules and mcp_tool hooks as ones to wait for
found in this entry's text
-
v2.1.283
Hooks can no longer change calls to the account memory server
Hooks may still allow or block calls to the account memory server, but a call they try to rewrite is denied and a rewritten result is dropped
found in this entry's text
-
v2.1.282
Skills and plugin commands can no longer grant themselves tools under managed-only permission rules
When policy restricts permission rules to managed settings, tool grants written into skills and plugin commands are ignored
found in this entry's text
-
v2.1.277
Sandboxed execution added for project-defined hook commands (remote tool serving)
Project hook scripts served remotely are now pinned by checksum and run in a sandbox before their block/allow decision is trusted
found in this entry's text
-
v2.1.277
PreToolUse hook warnings identify the tool generically, not by literal name
PreToolUse hook warnings now name tools generically instead of by their literal name
found in this entry's text
-
v2.1.275
tool.call hook-event schema gains a
measurecombinatorThe tool.call hook event gained a 'measure' step that combines context across related events
found in this entry's text
-
v2.1.271
Artifacts gain automatic reference-doc bundling with new telemetry
Artifacts now auto-bundle in reference docs like format and font guides, tracked with a new telemetry event
found in this entry's text
-
v2.1.269
Auto-denial telemetry event now excludes path-scoped deny-rule refusals of file tools
Auto-denial telemetry no longer counts Read/Edit/Write calls blocked by a path-scoped deny rule
found in this entry's text
-
v2.1.265
Hook event names gain a wildcard/negation pattern grammar and a 'classic.' namespace
Hook event names now support wildcard and negation patterns, and internal plugin hooks are namespaced as
classic.<EventName>found in this entry's text
-
v2.1.265
Non-PreToolUse hooks can be routed through a new 'classic' hook chain
Non-PreToolUse hooks can now be routed through a separate 'classic' hook execution chain
found in this entry's text
-
v2.1.265
Functionhooks event registry expands: ui.open/ui.close, command.run/command.describe, classic.PreToolUse
Hooks system adds ui.open/ui.close and command.run/command.describe event types, and renames PreToolUse internally
found in this entry's text
-
v2.1.265
Hook events: PreToolUse split into classic vs. new, and two new synchronous hook events added
PreToolUse hooks are now split into a classic and new form, plus two new synchronous hook events
found in this entry's text
-
v2.1.260
Transcript turn summary rendering refactor
Turn summary rendering code was refactored internally with no visible change.
found in this entry's text
-
v2.1.257
Hook execution now distinguishes 'did not run' from other failures
Hook results now say specifically when the hook's process never ran, separate from a bad exit code or invalid JSON.
found in this entry's text
-
v2.1.257
Hooks declared outside the "hooks" key (or PreToolUse/PermissionRequest nested arrays) now fail to load with a clear error
A plugin or agent declaring PreToolUse or PermissionRequest hooks in the wrong place is now rejected with a clear error.
found in this entry's text, named in this entry
-
v2.1.257
Hook-triggered abort now unwraps sub-agent turn controllers
A hook interrupting a sub-agent or forked turn now aborts the real turn controller instead of doing nothing.
found in this entry's text
-
v2.1.257
Skills reject top-level PreToolUse/PermissionRequest hooks in frontmatter
A skill declaring permission hooks outside the hooks object no longer loads them or its allowed-tools.
found in this entry's text
-
v2.1.257
Same top-level-hooks guard extended to plugin hooks.json files
A plugin hooks.json with permission hooks outside the hooks key now throws instead of loading malformed config.
found in this entry's text
-
v2.1.257
Stricter hook-config validation for PreToolUse/PermissionRequest guard entries
Malformed permission-hook entries are now flagged with a warning that the neighbouring permission guard may not apply.
found in this entry's text
-
v2.1.257
Hooks module scanning now flags PreToolUse/PermissionRequest declared outside the hooks object
Permission hooks declared at the top level of hooks.json now give a message pointing at the misconfiguration.
found in this entry's text
-
v2.1.248
Hook schema failures now print the exact field, a template, and which tool failed
A bad hook response now shows the exact failing field, the output and a template.
found in this entry's text
-
v2.1.248
New hook events and compiled-in plugin admission defaults
Three new hook event names appear, and unverified plugins are still allowed to load.
found in this entry's text
-
v2.1.242
Hooks are held rather than run for tool calls served to a cloud session
Hooks for tool calls served to a cloud session can be held instead of run, turning the call into an ask.
found in this entry's text
-
v2.1.242
A
cloudfield on hooks, and rules for which hooks a cloud session may useHook entries accept a cloud setting deciding whether a cloud session may run them.
found in this entry's text
-
v2.1.242
Each hook event enforces what a plugin is allowed to change
Plugin hooks are limited in what they may rewrite, and cannot take over question prompts.
found in this entry's text
-
v2.1.242
Plugin modules with a
$API that can hook events and redraw the terminal UIPlugins can install code that intercepts tool calls and repaints parts of the terminal interface.
found in this entry's text
-
v2.1.239
Deferred tool calls carry trace context to hooks
Deferred tool-call notifications now carry a traceparent so hook consumers can correlate them.
found in this entry's text
-
v2.1.239
Tool calls relayed from a cloud agent run under a restricted permission mode
Tool calls relayed from a cloud agent are judged strictly: your hooks skip and relaxed permission modes are downgraded.
found in this entry's text
-
v2.1.238
Reconnecting an SDK host swaps its hooks in and settles the ones left waiting
SDK hook swaps no longer leave tool calls hanging; stuck ones now ask you to retry.
found in this entry's text
-
v2.1.236
Some hook events take a separate dispatch path
Six hook events now wait on a readiness step before running; the rest are unchanged.
found in this entry's text
-
v2.1.232
Blocking web fetches with a PreToolUse hook now explains the consequence
Blocking a web fetch via a hook now tells Claude that's the only fetch route, so it stops retrying.
found in this entry's text
-
v2.1.224
Turn summary now counts workshop page edits and hook time
Turn summaries now count workshop page edits and how long PreToolUse hooks took.
found in this entry's text
-
v2.1.210
PreToolUse Hook Timeout Message Improved
found in this entry's text
-
v2.1.199
Hook additionalContext: Structured JSON Output
found in this entry's text
-
v2.1.163
SubagentStop Hook Event
found in this entry's text
-
v2.1.133
Reasoning Effort Exposed to Hooks and Bash
found in this entry's text
-
v2.1.124
update-configskill prompt rewrittenfound in this entry's text
-
v2.1.108
REPL Blocked by PreToolUse Hook
found in this entry's text
-
v2.1.101
Hook Event Validation
found in this entry's text
-
v2.1.79
Slow Hook and Permission Logging
found in this entry's text
- v2.1.75
-
v2.1.28
Simplified Hook Context Session Persistence
found in this entry's text
-
v2.1.0
Pre-emptive Git Commit Trailer Injection
found in this entry's text
-
v2.0.20
Hook Execution Progress Display
found in this entry's text
-
v1.0.41
New SubagentStop Hook Event
found in this entry's text
-
v1.0.38
Major Features
found in this entry's text
-
v1.0.24
New Features
found in this entry's text
-
v1.0.23
Improvements
found in this entry's text
First cited
17The earliest release whose published evidence quoted PreToolUse was v2.1.0, 7 Jan 2026. That is the oldest release this project wrote about it, so it is a floor on the name's age and not the release that introduced it. It is not a presence reading: which builds carried the name is the table below.
11 further spans in the ledger name it. The list above is the earliest first and stops at 6.
Presence across releases
0The miner has never read a build containing this name. It is here because a changelog entry of ours names it, which is evidence that it existed and not evidence of which releases carried it. The inventory starts at v2.1.138 and everything older than that was never mined.
Read out of the published npm bundle release by release, and out of Anthropic's own documentation as this site captured it. Nothing on this page is a description anybody here wrote about what the hook event does. All hook events.