manage-hooks

<essential_principles> Hooks 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.

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 </essential_principles>

1. Create a new hook
2. Debug / fix a hook
3. Create a toolkit hook (distributable)
4. 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.

<quick_reference>

Event	When it fires	Can block?	Matcher filters
PreToolUse	Before tool execution	Yes	tool name
PostToolUse	After tool succeeds	Yes (decision: "block")	tool name
PostToolUseFailure	After tool fails	No	tool name
PermissionRequest	Permission dialog appears	Yes	tool name
UserPromptSubmit	User submits a prompt	Yes	no matcher support
Stop	Claude finishes responding	Yes	no matcher support
SubagentStart	Subagent is spawned	No	agent type
SubagentStop	Subagent finishes	Yes	agent type
SessionStart	Session begins/resumes	No	source (startup, resume, clear, compact)
SessionEnd	Session terminates	No	reason (clear, logout, etc.)
PreCompact	Before context compaction	No	trigger (manual, auto)
Notification	Claude needs attention	No	type (permission_prompt, idle_prompt, etc.)
TeammateIdle	Agent about to go idle	Yes (exit 2)	no matcher support
TaskCompleted	Task marked complete	Yes (exit 2)	no matcher support
ConfigChange	Config file changes	Yes (decision: "block")	config type