Hook Events Reference

PreToolUse

Runs after Claude creates tool parameters and before processing the tool call. Can block, allow, or prompt for user approval.

Common matchers:

• Task — subagent tasks
• Bash — shell commands
• Glob — file pattern matching
• Grep — content search
• Read — file reading
• Edit, MultiEdit — file editing
• Write — file writing
• WebFetch, WebSearch — web operations

Input:

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

PostToolUse

Runs immediately after a tool completes successfully. Same matchers as PreToolUse.

Input:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": { "file_path": "...", "content": "..." },
  "tool_response": { "filePath": "...", "success": true }
}

Notification

Runs when Claude Code sends notifications:

1. Claude needs your permission to use a tool
2. The prompt input has been idle for at least 60 seconds

{
  "hook_event_name": "Notification",
  "message": "Claude needs your permission to use Bash"
}

UserPromptSubmit

Runs when the user submits a prompt, before Claude processes it. Can inject context or block prompts.

{
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Refactor the auth module to use JWT"
}

Special behavior: If exit code is 0, stdout is added to the context (unique among hook events — other events do NOT show stdout to Claude on exit 0).

Stop

Runs when the main Claude Code agent has finished responding. Does not run if the user interrupted.

{
  "hook_event_name": "Stop",
  "stop_hook_active": true
}

stop_hook_active is true when Claude is already continuing due to a previous stop hook. Check this to prevent infinite loops.

SubagentStop

Runs when a Claude Code subagent (Task tool call) has finished responding.

{
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false
}

PreCompact

Runs before Claude Code runs a compact operation.

Matchers:

• manual — invoked from /compact
• auto — invoked from auto-compact (full context window)

{
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

SessionStart

Runs when Claude Code starts or resumes a session. Useful for loading project context.

Matchers:

• startup — invoked from startup
• resume — invoked from --resume, --continue, or /resume
• clear — invoked from /clear

{
  "hook_event_name": "SessionStart",
  "source": "startup"
}

Use case: Load recent git log, current branch, open issues, or any project state you want available at session start.

Hook Execution Details

• Timeout: 60 seconds per hook (configurable per command)
• Parallelization: All matching hooks run in parallel
• Environment: Runs in current directory with Claude Code's environment
• CLAUDE_PROJECT_DIR: Available as an env var in all hook commands — use this for relative paths to your scripts
• Input: JSON via stdin