Hook Creator
Overview
Claude Code hooks are user-defined shell commands, LLM prompts, or agent evaluations that execute automatically at specific lifecycle points. Hooks receive JSON context via stdin, take action, and communicate results through exit codes, stdout, and stderr.
When to use: Blocking dangerous commands, auto-formatting after writes, protecting sensitive files, custom notifications, environment setup, enforcing project conventions, auto-approving safe tools, running tests after changes.
When NOT to use: Static context injection (use CLAUDE.md), simple permission rules (use allowlist settings), one-time setup (use shell scripts directly).
Quick Reference
| Pattern | Event | Matcher | Key Points |
|---|---|---|---|
| Block tool call | PreToolUse | Tool name | Exit 2 or JSON permissionDecision: "deny" |
| Auto-approve tool | PreToolUse | Tool name | JSON permissionDecision: "allow" |
| Modify tool input | PreToolUse | Tool name | JSON updatedInput with modified parameters |
| Format after write | PostToolUse | Write|Edit | Run formatter, exit 0 |
| Log tool failures | PostToolUseFailure | Tool name | Fires when tool throws error or returns failure |
| Handle permission | PermissionRequest | Tool name | JSON decision.behavior: "allow" or "deny" |
| Validate user prompt | UserPromptSubmit | No matcher | Exit 2 blocks prompt, stdout adds context |
| Desktop notification | Notification | Notification type | permission_prompt, idle_prompt, etc. |
| Force continue | Stop | No matcher | JSON decision: "block" with reason |
| Subagent lifecycle | SubagentStop | Agent type | Same decision control as Stop |
| Environment setup | SessionStart | Source type | Write to CLAUDE_ENV_FILE to persist env vars |
| Session cleanup | SessionEnd | Exit reason | Cannot block termination |
| Pre-compact context | PreCompact | manual|auto | Fires before context compaction |
| Background tasks | Any post-event | Any | Set async: true on command hooks |
| LLM evaluation | Supported events | Any | Use type: "prompt" for single-turn LLM check |
| Multi-turn verification | Supported events | Any | Use type: "agent" for subagent with tool access |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
| Exit 1 expecting to block a tool call | Use exit 2 to block in PreToolUse and PermissionRequest |
| Printing JSON on exit 2 | JSON output is only processed on exit 0; stderr is used on exit 2 |
| Complex inline bash in settings.json | Extract to a script file, reference with $CLAUDE_PROJECT_DIR |
| Missing timeout on slow hooks | Set timeout field; defaults are 600s command, 30s prompt, 60s agent |
Not quoting $CLAUDE_PROJECT_DIR | Always quote: "$CLAUDE_PROJECT_DIR"/.claude/hooks/script.sh |
Expecting CLAUDE_ENV_FILE in all hooks | Only available in SessionStart hooks |
| Adding matcher to Stop or UserPromptSubmit | These events ignore matchers; they always fire |
Using decision/reason at top level for PreToolUse | Use hookSpecificOutput.permissionDecision and permissionDecisionReason |
Not checking stop_hook_active in Stop hooks | Check this field to prevent infinite continuation loops |
| Mixing exit codes and JSON decisions | Choose one approach per hook: exit codes alone or exit 0 with JSON |
Delegation
- Hook pattern discovery: Use
Exploreagent to find existing hooks in the project - Hook testing and verification: Use
Taskagent to validate hook behavior - Code review: Delegate to
code-revieweragent for hook script review