Claude Code Hooks
Hook Events
| Event | Fires When | Can Control |
|---|---|---|
| PreToolUse | Before tool execution | Allow/deny/modify tool calls |
| PostToolUse | After tool execution | Provide feedback to Claude |
| PermissionRequest | Permission dialog shown | Allow/deny |
| UserPromptSubmit | User submits prompt | Modify/block prompt |
| Notification | Claude sends notification | Custom handling |
| Stop | Claude finishes responding | Force continuation |
| SubagentStop | Subagent completes | Force continuation |
| PreCompact | Before compaction | Preserve info |
| SessionStart | Session begins | Load context, set env |
| SessionEnd | Session ends | Cleanup, logging |
Hook Types
Command Hook (deterministic)
{"type": "command", "command": "bash /path/to/script.sh", "timeout": 60}
Prompt Hook (LLM-driven)
{"type": "prompt", "prompt": "Evaluate safety of: $TOOL_INPUT", "timeout": 30}
Configuration (settings.json)
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{"type": "command", "command": "bash audit-command.sh"}]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{"type": "command", "command": "npx prettier --write $FILE_PATH"}]
}
],
"Stop": [
{
"matcher": "*",
"hooks": [{"type": "prompt", "prompt": "Verify all requirements are met before stopping."}]
}
],
"SessionStart": [
{
"matcher": "*",
"hooks": [{"type": "command", "command": "bash load-env.sh"}]
}
]
}
}
Matchers
| Pattern | Matches |
|---|---|
"Write" |
Exact tool name |
"Read|Write|Edit" |
OR matching |
"*" |
All tools |
"mcp__.*" |
Regex for MCP tools |
"mcp__.*__delete.*" |
Regex with specificity |
Case-sensitive. First matching hook wins.
Hook Input (JSON via stdin)
Common fields: session_id, transcript_path, cwd, permission_mode, hook_event_name
PreToolUse/PostToolUse: + tool_name, tool_input, tool_result
UserPromptSubmit: + user_prompt
Stop/SubagentStop: + reason
Hook Output
PreToolUse
{
"hookSpecificOutput": {
"permissionDecision": "allow",
"updatedInput": {"command": "sanitized-command"}
},
"systemMessage": "Command was sanitized for safety."
}
Decisions: "allow", "deny", "ask"
Stop
{
"decision": "block",
"reason": "Tests not yet run",
"systemMessage": "Please run the test suite before completing."
}
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success (stdout added to transcript) |
| 1 | Non-blocking error (logged, continues) |
| 2 | Blocking error (stderr fed to Claude) |
Environment Variables
$CLAUDE_PROJECT_DIR, $CLAUDE_PLUGIN_ROOT, $CLAUDE_ENV_FILE (SessionStart only)
Production Patterns
Auto-Format on Save
{
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": [{"type": "command", "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\""}]
}]
}
File Protection
{
"PreToolUse": [{
"matcher": "Edit|Write",
"hooks": [{"type": "command", "command": "bash check-protected.sh"}]
}]
}
Audit Logging
{
"PreToolUse": [{
"matcher": "Bash",
"hooks": [{"type": "command", "command": "echo \"$(date) $TOOL_INPUT\" >> ~/.claude/audit.log"}]
}]
}
Session Context Loading
{
"SessionStart": [{
"matcher": "*",
"hooks": [{"type": "command", "command": "echo 'export PROJECT_ENV=production' >> \"$CLAUDE_ENV_FILE\""}]
}]
}
Multi-Stage Validation
Combine command hook (fast check) + prompt hook (deep analysis):
{
"PreToolUse": [{
"matcher": "Bash",
"hooks": [
{"type": "command", "command": "bash quick-check.sh", "timeout": 5},
{"type": "prompt", "prompt": "Is this command safe? $TOOL_INPUT", "timeout": 30}
]
}]
}