1. Three Hook Types:
- command — shell command, deterministic, fast. Exit 0 = proceed, exit 2 = block. JSON stdout for structured control.
- prompt — single-turn LLM evaluation (Haiku default). Returns
{"ok": true} or {"ok": false, "reason": "..."}.
- agent — multi-turn subagent with tool access (up to 50 turns). Same ok/reason output. Use when verification needs codebase access.
2. Event → Matcher → Hook — Events (PreToolUse, Stop, etc.) trigger matchers (regex on tool name/context) which fire hooks. See <quick_reference> for the full event table.
3. Configuration Locations (highest priority first):
- User-global:
~/.claude/settings.json
- Project shared:
.claude/settings.json
- Project local:
.claude/settings.local.json
- Or use
/hooks interactive menu in Claude Code
4. Environment Variables:
| Variable |
Value |
$CLAUDE_PROJECT_DIR |
Project root directory |
${CLAUDE_PLUGIN_ROOT} |
Plugin directory (plugin hooks only) |
$ARGUMENTS |
Hook input JSON (prompt/agent hooks only) |
$CLAUDE_ENV_FILE |
Path for persisting environment variables |
5. Safety Essentials:
- Stop hook loops: Always check
stop_hook_active field in Stop/SubagentStop hooks — exit 0 if true
- Timeouts: Set reasonable values in seconds (default: 10 min commands, 60s agents, 30s prompts)
- Permissions:
chmod +x on script files
- Path safety: Quote
"$CLAUDE_PROJECT_DIR" for spaces
- Shell profiles: Wrap echo in
~/.zshrc/~/.bashrc with [[ $- == *i* ]] checks — non-interactive shells can corrupt JSON output
- PermissionRequest: Doesn't fire in headless mode (
-p); use PreToolUse instead
- Create a new hook
- Debug / fix a hook
- Create a toolkit hook (distributable)
- Get guidance on hook design
If $ARGUMENTS provides clear intent, skip the menu and route directly.
Intent-based routing (when $ARGUMENTS provides clear intent):
- "block dangerous commands" → workflows/create-hook.md
- "my hook isn't triggering" → workflows/debug-hook.md
- "package for toolkit" → workflows/create-toolkit-hook.md
- "what event should I use" → workflows/get-guidance.md
After reading the workflow, follow it exactly.
See references/hook-types.md for detailed schemas and use cases for each event.
Types & Events: hook-types.md — complete event schemas and use cases
Hook Types: command-vs-prompt.md — decision tree for command vs prompt vs agent
Matchers: matchers.md — regex patterns, event-specific matching, MCP tools
I/O Schemas: input-output-schemas.md — stdin JSON, exit codes, hookSpecificOutput
Examples: examples.md — notifications, file protection, auto-format, logging, Stop hooks
Troubleshooting: troubleshooting.md — hooks not triggering, JSON corruption, loops
Toolkit: toolkit-structure.md — distributable hook packaging for claude-code-toolkit
| Workflow |
Purpose |
| create-hook.md |
Build a hook from scratch |
| debug-hook.md |
Diagnose and fix broken hooks |
| create-toolkit-hook.md |
Package hook for toolkit distribution |
| get-guidance.md |
Help decide event, type, and matcher |
|
|
- Valid JSON in the appropriate settings file (validated with
jq)
- Appropriate hook event selected for the use case
- Correct matcher pattern matching target tools/contexts
- Command, prompt, or agent that executes without errors
- Proper output (exit codes for commands, ok/reason for prompts/agents)
- Tested with
--debug flag or Ctrl+O verbose mode showing expected behavior
- No infinite loops in Stop/SubagentStop hooks (checks
stop_hook_active flag)
- Reasonable timeout set in seconds
- Executable permissions on script files
- No shell profile interference with JSON output
1---2name: create-hooks3description: <essential_principles>4---56<essential_principles>7Hooks are event-driven automation for Claude Code that execute shell commands, LLM prompts, or multi-turn agents in response to tool usage, session events, and user interactions. They provide deterministic control over Claude's behavior without modifying core code.89**1. Three Hook Types:**10- **command** — shell command, deterministic, fast. Exit 0 = proceed, exit 2 = block. JSON stdout for structured control.11- **prompt** — single-turn LLM evaluation (Haiku default). Returns `{"ok": true}` or `{"ok": false, "reason": "..."}`.12- **agent** — multi-turn subagent with tool access (up to 50 turns). Same ok/reason output. Use when verification needs codebase access.1314**2. Event → Matcher → Hook** — Events (PreToolUse, Stop, etc.) trigger matchers (regex on tool name/context) which fire hooks. See `<quick_reference>` for the full event table.1516**3. Configuration Locations** (highest priority first):17- User-global: `~/.claude/settings.json`18- Project shared: `.claude/settings.json`19- Project local: `.claude/settings.local.json`20- Or use `/hooks` interactive menu in Claude Code2122**4. Environment Variables:**23| Variable | Value |24|----------|-------|25| `$CLAUDE_PROJECT_DIR` | Project root directory |26| `${CLAUDE_PLUGIN_ROOT}` | Plugin directory (plugin hooks only) |27| `$ARGUMENTS` | Hook input JSON (prompt/agent hooks only) |28| `$CLAUDE_ENV_FILE` | Path for persisting environment variables |2930**5. Safety Essentials:**31- **Stop hook loops**: Always check `stop_hook_active` field in Stop/SubagentStop hooks — exit 0 if true32- **Timeouts**: Set reasonable values in seconds (default: 10 min commands, 60s agents, 30s prompts)33- **Permissions**: `chmod +x` on script files34- **Path safety**: Quote `"$CLAUDE_PROJECT_DIR"` for spaces35- **Shell profiles**: Wrap echo in `~/.zshrc`/`~/.bashrc` with `[[ $- == *i* ]]` checks — non-interactive shells can corrupt JSON output36- **PermissionRequest**: Doesn't fire in headless mode (`-p`); use PreToolUse instead37</essential_principles>3839<intake>40What would you like to do?41421. Create a new hook432. Debug / fix a hook443. Create a toolkit hook (distributable)454. Get guidance on hook design4647**If `$ARGUMENTS` provides clear intent, skip the menu and route directly.**48</intake>4950<routing>51| Response | Intent Phrases | Workflow |52|----------|---------------|----------|53| 1, "create", "add", "build", "set up" | "create a hook", "add a PreToolUse hook", "block rm -rf" | workflows/create-hook.md |54| 2, "debug", "fix", "not working", "broken" | "hook not firing", "debug my hook", "fix hook" | workflows/debug-hook.md |55| 3, "toolkit", "package", "distribute", "install" | "create toolkit hook", "package hook" | workflows/create-toolkit-hook.md |56| 4, "guidance", "help", "recommend", "which" | "which event?", "how do hooks work?", "recommend" | workflows/get-guidance.md |5758**Intent-based routing (when `$ARGUMENTS` provides clear intent):**59- "block dangerous commands" → workflows/create-hook.md60- "my hook isn't triggering" → workflows/debug-hook.md61- "package for toolkit" → workflows/create-toolkit-hook.md62- "what event should I use" → workflows/get-guidance.md6364**After reading the workflow, follow it exactly.**65</routing>6667<quick_reference>68| Event | When it fires | Can block? | Matcher filters |69|-------|---------------|------------|-----------------|70| **PreToolUse** | Before tool execution | Yes | tool name |71| **PostToolUse** | After tool succeeds | Yes (`decision: "block"`) | tool name |72| **PostToolUseFailure** | After tool fails | No | tool name |73| **PermissionRequest** | Permission dialog appears | Yes | tool name |74| **UserPromptSubmit** | User submits a prompt | Yes | no matcher support |75| **Stop** | Claude finishes responding | Yes | no matcher support |76| **SubagentStart** | Subagent is spawned | No | agent type |77| **SubagentStop** | Subagent finishes | Yes | agent type |78| **SessionStart** | Session begins/resumes | No | source (`startup`, `resume`, `clear`, `compact`) |79| **SessionEnd** | Session terminates | No | reason (`clear`, `logout`, etc.) |80| **PreCompact** | Before context compaction | No | trigger (`manual`, `auto`) |81| **Notification** | Claude needs attention | No | type (`permission_prompt`, `idle_prompt`, etc.) |82| **TeammateIdle** | Agent about to go idle | Yes (exit 2) | no matcher support |83| **TaskCompleted** | Task marked complete | Yes (exit 2) | no matcher support |84| **ConfigChange** | Config file changes | Yes (`decision: "block"`) | config type |8586See [references/hook-types.md](references/hook-types.md) for detailed schemas and use cases for each event.87</quick_reference>8889<reference_index>90All in `references/`:9192**Types & Events:** hook-types.md — complete event schemas and use cases93**Hook Types:** command-vs-prompt.md — decision tree for command vs prompt vs agent94**Matchers:** matchers.md — regex patterns, event-specific matching, MCP tools95**I/O Schemas:** input-output-schemas.md — stdin JSON, exit codes, hookSpecificOutput96**Examples:** examples.md — notifications, file protection, auto-format, logging, Stop hooks97**Troubleshooting:** troubleshooting.md — hooks not triggering, JSON corruption, loops98**Toolkit:** toolkit-structure.md — distributable hook packaging for claude-code-toolkit99</reference_index>100101<workflows_index>102All in `workflows/`:103104| Workflow | Purpose |105|----------|---------|106| create-hook.md | Build a hook from scratch |107| debug-hook.md | Diagnose and fix broken hooks |108| create-toolkit-hook.md | Package hook for toolkit distribution |109| get-guidance.md | Help decide event, type, and matcher |110</workflows_index>111112<success_criteria>113A working hook configuration has:114115- Valid JSON in the appropriate settings file (validated with `jq`)116- Appropriate hook event selected for the use case117- Correct matcher pattern matching target tools/contexts118- Command, prompt, or agent that executes without errors119- Proper output (exit codes for commands, ok/reason for prompts/agents)120- Tested with `--debug` flag or `Ctrl+O` verbose mode showing expected behavior121- No infinite loops in Stop/SubagentStop hooks (checks `stop_hook_active` flag)122- Reasonable timeout set in seconds123- Executable permissions on script files124- No shell profile interference with JSON output125</success_criteria>