Claude Code Hooks Events Tool

Claude Code Hooks: Tool Events

These events fire before a tool runs, and when a permission is asked for or denied. The events are PreToolUse, PermissionRequest, and PermissionDenied. They are the main place to approve, change, or block a tool call. For example, a PreToolUse hook on Bash can deny each command that holds rm -rf. All three events match on tool name. MCP tools are named mcp__<server>__<tool>.

PreToolUse

Mark	Item	What it does	How it works	Where it can be used	Source
✅	PreToolUse	Fires after Claude builds the tool input and before the tool runs	Matcher is the tool name. Exit 2 blocks and stderr is the reason. Does not fire for @ file mentions	command, http, mcp_tool, prompt, agent	Hooks Reference, PreToolUseHookInput
✅	tool_name	Tool name	Any tool except EndConversation	stdin	Hooks Reference
✅	tool_input	The tool arguments	Shape by tool, see the next table. File paths are absolute	stdin	Hooks Reference
✅	tool_use_id	Tool call ID	A string	stdin	Hooks Reference
✅	permissionDecision	allow, deny, ask, defer	allow skips the prompt but not deny or ask rules. Order: deny > defer > ask > allow. defer works only in -p with one tool call	hookSpecificOutput	Hooks Reference
✅	permissionDecisionReason	Reason text	ask: shown in the prompt. deny: shown to Claude. Others: debug log	hookSpecificOutput	Hooks Reference
✅	updatedInput	Replaces the whole input	Rules and background checks use the new input. Needed with allow for AskUserQuestion and ExitPlanMode. Ignored with defer	hookSpecificOutput	Hooks Reference
✅	additionalContext	Text next to the tool result	Ignored with defer	hookSpecificOutput	Hooks Reference
🔍	permissionDisplay	Words for a permission card	An internal field for the desktop host only. Object {title (200), description (2000), displayName (64)}. Ignored with a debug line if a text cannot be shown	hookSpecificOutput	bundle
⚠️	Top-level decision and reason	Deprecated for this event	approve maps to allow and block maps to deny. The bundle schema accepts the enum on all events	stdout	Hooks Reference, bundle
✅	ask label	Prompt shows [settings], [plugin:<name>], or [skill]	An ask also forces a prompt in auto mode	Permission prompt	Hooks Reference

Tool Input Shapes

Mark	Item	What it does	How it works	Where it can be used	Source
✅	Bash	Run a command	command, description, timeout (ms), run_in_background	tool_input	Hooks Reference
✅	PowerShell	Run a PowerShell command	Same keys as Bash. Match Bash|PowerShell	tool_input	Hooks Reference
✅	Write	Write a file	file_path, content	tool_input	Hooks Reference
✅	Edit	Replace a string	file_path, old_string, new_string, replace_all	tool_input	Hooks Reference
✅	Read	Read a file	file_path, offset, limit	tool_input	Hooks Reference
✅	Glob	Find files	pattern, path	tool_input	Hooks Reference
✅	Grep	Search content	pattern, path, glob, output_mode, -i, multiline	tool_input	Hooks Reference
✅	WebFetch	Fetch a page	url, prompt, offset (2.1.290)	tool_input	Hooks Reference
✅	WebSearch	Search the web	query, allowed_domains, blocked_domains	tool_input	Hooks Reference
✅	Agent	Start a subagent	prompt, description, subagent_type, model	tool_input	Hooks Reference
✅	AskUserQuestion	Ask 1 to 4 questions	questions, and answers (set only through updatedInput)	tool_input	Hooks Reference
✅	ExitPlanMode	Ask to leave plan mode	Claude Code injects plan and planFilePath	tool_input	Hooks Reference
❌	allowedPrompts	Accepted and ignored	Used before 2.1.205	ExitPlanMode	Hooks Reference

The docs name Workflow as a matchable tool and give no input shape for it.

PermissionRequest

Mark	Item	What it does	How it works	Where it can be used	Source
✅	PermissionRequest	Fires when a prompt would show, or when a call that cannot prompt would be denied	Matcher is the tool name. Exit 2 is not honored. No event for a sandbox network request. Use the decision object to deny	command, http, mcp_tool, prompt (an agent hook is skipped)	Hooks Reference, PermissionRequestHookInput
✅	tool_name, tool_input	Same as PreToolUse	No tool_use_id	stdin	Hooks Reference
✅	permission_suggestions	Updates that Claude Code suggests	The same shape as updatedPermissions. A dialog may show other options	stdin	Hooks Reference
✅	decision.behavior	allow or deny	Deny and ask rules still apply	hookSpecificOutput	Hooks Reference, PermissionRequestDecision
✅	decision.updatedInput	New tool input	allow only. Checked again against deny and ask rules	hookSpecificOutput	Hooks Reference
✅	decision.updatedPermissions	Permission updates to apply	allow only	hookSpecificOutput	Hooks Reference
✅	decision.message	Why it was denied	deny only. Goes to Claude	hookSpecificOutput	Hooks Reference
✅	decision.interrupt	Stops Claude	deny only	hookSpecificOutput	Hooks Reference

Permission Update Entries

Mark	Item	What it does	How it works	Where it can be used	Source
✅	addRules, replaceRules, removeRules	Change rules	Fields rules ({toolName, ruleContent?}), behavior (allow, deny, ask), destination	updatedPermissions, permission_suggestions	Hooks Reference, PermissionUpdate
✅	setMode	Change the permission mode	mode: default, auto, acceptEdits, dontAsk, bypassPermissions, plan. bypassPermissions works only if bypass was on at launch	Same	Hooks Reference
✅	addDirectories, removeDirectories	Change working directories	Field directories	Same	Hooks Reference
⚠️	destination	Where the change is kept	Docs: session, localSettings, projectSettings, userSettings. The d.ts also has cliArg	Same	Hooks Reference, PermissionUpdateDestination

PermissionDenied

Mark	Item	What it does	How it works	Where it can be used	Source
✅	PermissionDenied	Fires only when auto mode denies a call, also with no classifier verdict	Matcher is the tool name. Not for manual denials, PreToolUse blocks, or deny rules. Exit code and stderr are ignored	All five types, but prompt and agent output is dropped	Hooks Reference, PermissionDeniedHookInput
✅	tool_name, tool_input, tool_use_id, mcp_server	As in PreToolUse		stdin	Hooks Reference
✅	reason	Why auto mode denied	Rule name in brackets, such as [Data Exfiltration]. Other fixed texts are in the docs	stdin	Hooks Reference
✅	retry	true tells the model it may retry	The denial stands. Ignored for no-verdict denials	hookSpecificOutput	Hooks Reference

Sources

• Hooks Reference.
• d.ts types PreToolUseHookInput, PermissionRequestHookInput, PermissionDeniedHookInput, PermissionRequestDecision, PermissionUpdate.
• Bundle: the hook output schema and the permissionDisplay schema.

Not Yet Checked

• Not verified: any input shape for Workflow, Skill, and MCP tools beyond their tool_input being unknown in the d.ts.

See Also

• Hooks, with the legend of marks
• Tool Result Events
• Output