create-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:

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>

See references/hook-types.md for detailed schemas and use cases for each event. </quick_reference>

<reference_index> All in references/:

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

<workflows_index> All in workflows/:

<success_criteria> A working hook configuration has:

• 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 </success_criteria>