Hook Events Reference

Hook Events Reference

Complete reference for all Claude Code hook event types, their behaviors, and use cases.

Claude Code Tools Reference

Complete list of all Claude Code tools that can be matched by hooks. Use these tool names in matcher patterns to intercept specific operations.

Core File Operations

Read - Read file contents from the filesystem

• Hook use cases: Auto-approve documentation reads, audit sensitive file access, inject file context
• Example matcher: "Read"
• Common validations: Check for sensitive paths (.env, credentials), verify file exists in project

Write - Create new files or overwrite existing files

• Hook use cases: Format code after write, backup files, validate file paths, block overwriting sensitive files
• Example matcher: "Write"
• Common validations: Prevent path traversal, block sensitive file creation, enforce naming conventions

Edit - Modify existing files with find/replace operations

• Hook use cases: Auto-format after edits, run linters, create backup copies, validate changes
• Example matcher: "Edit" or "Write|Edit" for both
• Common validations: Block edits to sensitive files, verify file exists, check edit safety

NotebookEdit - Edit Jupyter notebook (.ipynb) cells

• Hook use cases: Validate notebook cell changes, auto-format code cells, backup notebooks
• Example matcher: "NotebookEdit"
• Common validations: Verify notebook structure, check cell types

Code Search Operations

Glob - Find files matching glob patterns (e.g., **/*.js)

• Hook use cases: Audit file searches, restrict search scope, log search patterns
• Example matcher: "Glob"
• Common validations: Prevent searching outside project directory

Grep - Search file contents using regex patterns

• Hook use cases: Audit content searches, restrict search scope, log sensitive searches
• Example matcher: "Grep"
• Common validations: Block searches for credentials/secrets, limit search scope

Command Execution

Bash - Execute shell commands

• Hook use cases: Block dangerous commands (rm -rf, sudo), validate command safety, log all commands
• Example matcher: "Bash"
• Common validations: Block rm -rf /, block sudo/su, prevent fork bombs, validate command syntax

BashOutput - Retrieve output from background bash shells

• Hook use cases: Monitor background processes, audit shell access
• Example matcher: "BashOutput"
• Common validations: Verify shell ID exists

KillShell - Terminate background bash shells

• Hook use cases: Audit process termination, log killed shells
• Example matcher: "KillShell"
• Common validations: Verify shell exists before killing

Sub-agent Operations

Task - Launch specialized sub-agents for complex tasks

• Hook use cases: Audit sub-agent usage, log agent launches, validate agent permissions
• Example matcher: "Task"
• Common validations: Verify agent type exists, check permissions for agent launch

ExitPlanMode - Exit planning mode and begin execution

• Hook use cases: Validate plan completeness, log plan approval
• Example matcher: "ExitPlanMode"
• Common validations: Ensure plan is documented

Web Operations

WebFetch - Fetch and process web content with AI

• Hook use cases: Audit web requests, block sensitive URLs, log external access
• Example matcher: "WebFetch"
• Common validations: Whitelist/blacklist domains, prevent credential URLs

WebSearch - Search the web using search engines

• Hook use cases: Audit search queries, log searches, restrict search topics
• Example matcher: "WebSearch"
• Common validations: Block sensitive search terms

Task Management

TodoWrite - Create and update todo lists for task tracking

• Hook use cases: Audit task creation, log todo changes, validate task structure
• Example matcher: "TodoWrite"
• Common validations: Verify todo format, check task descriptions

MCP (Model Context Protocol) Tools

ListMcpResources - List available resources from MCP servers

• Hook use cases: Audit MCP resource access, log resource queries
• Example matcher: "ListMcpResources"

ReadMcpResource - Read content from MCP server resources

• Hook use cases: Audit MCP resource reads, log accessed resources
• Example matcher: "ReadMcpResource"

MCP server tools - External tools provided by MCP servers

• Naming pattern: mcp__<server>__<tool>
• Examples:
  • mcp__filesystem__read_file
  • mcp__github__create_issue
  • mcp__postgres__query
  • mcp__slack__send_message
• Hook use cases: Validate MCP operations, audit external API calls, enforce MCP policies
• Example matchers:
  • "mcp__.*" - All MCP tools
  • "mcp__github__.*" - All GitHub operations
  • "mcp__.*__write.*" - All write operations across MCP servers
  • "mcp__postgres__.*" - All PostgreSQL operations

Common Matcher Patterns

Combine multiple tools using regex:

• "Write|Edit" - Match file write or edit operations
• "Glob|Grep" - Match any search operation
• "Bash|BashOutput|KillShell" - Match all bash-related operations
• "Read|Write|Edit" - Match all file operations
• "WebFetch|WebSearch" - Match all web operations
• "Task|ExitPlanMode" - Match agent-related operations
• "mcp__.*" - Match all MCP tool calls
• "*" or "" - Match all tools

PreToolUse

Execute after Claude creates tool parameters but before processing the tool call.

Common Matchers

• Bash - Shell commands
• Write|Edit - File modifications
• Read - File reading
• Glob|Grep - File searching
• mcp__.* - All MCP tools
• * or "" - All tools

Use Cases

• Validate inputs before tool execution
• Block dangerous operations
• Auto-approve safe operations
• Modify tool parameters
• Enforce security policies

Input Schema

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/directory",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  }
}

Exit Code Behavior

• Exit 0: Allow tool to proceed
• Exit 2: Block tool call, show stderr to Claude
• Other: Non-blocking error, show stderr to user

JSON Output for Permission Control

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",  // "allow", "deny", "ask"
    "permissionDecisionReason": "Documentation file auto-approved"
  },
  "suppressOutput": true
}

Permission decisions:

• allow - Bypass permission system, proceed automatically
• deny - Block tool call, show reason to Claude
• ask - Prompt user for confirmation

PostToolUse

Execute immediately after a tool completes successfully.

Common Matchers

Same as PreToolUse

Use Cases

• Format code after writing
• Run linters after edits
• Send notifications
• Log tool usage
• Provide feedback to Claude
• Trigger CI/CD workflows

Input Schema

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/directory",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  }
}

Exit Code Behavior

• Exit 0: Success, stdout shown in transcript
• Exit 2: Show stderr to Claude (tool already ran)
• Other: Non-blocking error, show stderr to user

JSON Output for Feedback

{
  "decision": "block",  // or undefined
  "reason": "Formatting failed",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "File formatting completed. All style rules applied."
  }
}

UserPromptSubmit

Execute when user submits a prompt, before Claude processes it.

Matchers

Not applicable - no matcher needed for this event

Use Cases

• Add contextual information
• Validate prompt content
• Block prompts with sensitive data
• Inject current environment state
• Load project-specific context

Input Schema

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/directory",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "User's submitted prompt text"
}

Exit Code Behavior

• Exit 0: stdout added as context for Claude
• Exit 2: Not applicable for UserPromptSubmit
• Other: Error, stderr shown to user

JSON Output for Blocking

{
  "decision": "block",  // Prevents prompt processing
  "reason": "Security: Potential secret detected. Please rephrase.",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Additional context added to prompt"
  }
}

Blocking behavior:

• decision: "block" - Prompt is erased, not processed
• reason - Shown to user (not added to context)
• additionalContext - Added to context if not blocked

SessionStart

Execute when Claude Code starts or resumes a session.

Matchers

• startup - New session started
• resume - Session resumed
• clear - After /clear command
• compact - After compaction

Use Cases

• Load recent git commits
• Show current branch and status
• Display open issues
• Check environment state
• Initialize session context

Input Schema

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "hook_event_name": "SessionStart",
  "source": "startup"  // or "resume", "clear", "compact"
}

Exit Code Behavior

• Exit 0: stdout added as context for Claude
• Exit 2: Not applicable
• Other: Error logged to debug

JSON Output for Context

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "## Recent Commits\n\n[git log output]"
  }
}

SessionEnd

Execute when a Claude Code session ends.

Matchers

Not applicable

Use Cases

• Save session statistics
• Clean temporary files
• Log activity
• Backup work
• Send notifications

Input Schema

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/directory",
  "hook_event_name": "SessionEnd",
  "reason": "exit"  // "clear", "logout", "prompt_input_exit", "other"
}

Exit Code Behavior

• Exit 0: Success, logged to debug
• Exit 2: Not applicable
• Other: Error logged to debug

Note: SessionEnd hooks cannot block session termination.

Stop

Execute when the main Claude Code agent attempts to stop.

Matchers

Not applicable

Use Cases

• Ensure tasks are complete
• Run final checks
• Force Claude to continue if needed
• Validate outputs

Input Schema

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "hook_event_name": "Stop",
  "stop_hook_active": false  // true if already continuing from Stop hook
}

Exit Code Behavior

• Exit 0: Allow Claude to stop
• Exit 2: Block stopping, show stderr to Claude
• Other: Error shown to user

JSON Output for Continuation

{
  "decision": "block",  // Prevents Claude from stopping
  "reason": "Tasks incomplete. Please finish pending work."
}

Important: Check stop_hook_active to prevent infinite loops. If true, allow Claude to stop.

SubagentStop

Execute when a sub-agent (Task tool call) attempts to stop.

Matchers

Not applicable

Use Cases

Same as Stop event, but for sub-agents

Input Schema

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false
}

Exit Code Behavior

• Exit 0: Allow sub-agent to stop
• Exit 2: Block stopping, show stderr to sub-agent
• Other: Error shown to user

JSON Output for Continuation

Same as Stop event.

PreCompact

Execute before Claude Code compacts conversation history.

Matchers

• manual - /compact command
• auto - Automatic compaction

Use Cases

• Save important context
• Log conversation statistics
• Prepare for compaction

Input Schema

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "hook_event_name": "PreCompact",
  "trigger": "manual",  // or "auto"
  "custom_instructions": ""  // From /compact args (manual only)
}

Exit Code Behavior

• Exit 0: Success, logged to debug
• Exit 2: Not applicable
• Other: Error shown to user

Note: PreCompact hooks cannot block compaction.

Notification

Execute when Claude Code sends notifications.

Matchers

Not applicable

Use Cases

• Forward notifications to external systems
• Log notification events
• Trigger alerts

Notifications Sent

• Permission requests: "Claude needs your permission to use Bash"
• Idle prompts: "Claude is waiting for your input" (after 60s)

Input Schema

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/directory",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission to use Bash"
}

Exit Code Behavior

• Exit 0: Success, logged to debug only
• Exit 2: Not applicable
• Other: Error logged to debug

Hook Execution Details

Timeout

• Default: 60 seconds per hook
• Configurable per command via timeout field
• Individual command timeout doesn't affect other commands

Parallelization

• All matching hooks run in parallel
• Multiple hooks can respond to same event

Environment

• Runs in current directory
• CLAUDE_PROJECT_DIR environment variable available
• Contains absolute path to project root

Input/Output

• PreToolUse/PostToolUse/Stop/SubagentStop: Progress shown in transcript (Ctrl-R)
• Notification/SessionEnd: Logged to debug only (--debug)
• UserPromptSubmit/SessionStart: stdout added as context for Claude

MCP Tool Naming

MCP tools follow the pattern mcp__<server>__<tool>:

• mcp__filesystem__read_file
• mcp__github__create_issue
• mcp__postgres__query

Match MCP tools with:

• mcp__.* - All MCP tools
• mcp__github__.* - All GitHub server tools
• mcp__.*__write.* - All write operations across servers