Hook Events
When each event fires, what data it receives, and what it can do.
User sends message → UserPromptSubmit → Claude thinks → PreToolUse → Tool runs → PostToolUse → ... → Claude stops → Stop
PreToolUse
Fires before every tool call. Can block or approve.
| stdin field | Value |
|---|
tool_name | Bash, Edit, Write, Read, Glob, Grep, Agent, Skill, ... |
tool_input | Tool-specific: .command (Bash), .file_path (Edit/Write/Read), .pattern (Grep) |
| Can do | How |
|---|
| Block | exit 2 |
| Approve (skip prompt) | echo '{"decision":"approve"}' |
| Warn | echo "WARNING" >&2 |
| Modify input | Not possible |
PostToolUse
Fires after every tool call. Can validate results.
| stdin field | Value |
|---|
tool_name | Same as PreToolUse |
tool_input | Same as PreToolUse |
tool_result | The tool's output/result |
| Can do | How |
|---|
| Warn about result | echo "SYNTAX ERROR" >&2 |
| Log activity | Write to log file |
| Block (too late) | Tool already ran |
| Modify result | Not possible (without updatedToolOutput) |
Stop
Fires when Claude finishes responding.
| stdin field | Value |
|---|
stop_reason | end_turn, error, max_tokens, etc. |
| Can do | How |
|---|
| Send notification | Desktop alert, sound, webhook |
| Log session summary | Write to proof-log |
| Clean up temp files | Any cleanup script |
UserPromptSubmit
Fires when the user sends a message.
| stdin field | Value |
|---|
prompt | The user's message text |
| Can do | How |
|---|
| Inject reminders | echo "REMINDER: check tests" >&2 |
| Log prompts | Write to log |
| Block submission | exit 2 |
SubagentStop
Fires when a subagent finishes.
| Can do | How |
|---|
| Track subagent completion | Decrement counter |
| Notify | Sound/alert when agent done |
Quick Reference: Which Event?
| I want to... | Event |
|---|
| Block a dangerous command | PreToolUse |
| Auto-approve safe commands | PreToolUse |
| Check syntax after edits | PostToolUse |
| Detect prompt injection | PostToolUse |
| Monitor context usage | PostToolUse |
| Send "task done" notification | Stop |
| Log session summary | Stop |
| Inject reminders per message | UserPromptSubmit |
| Track subagent count | SubagentStop |