Module 1.2

What Hooks Are

Hooks are shell commands (or LLM prompts, or agents) that Claude Code runs automatically at specific points in its lifecycle. Define them once in your settings and they fire silently in the background.

Two roles they play:

• Observers - log activity, send notifications, run tests after edits
• Gatekeepers - block Claude from taking an action before it happens

The 17 Hook Events

Where Config Lives

Three Handler Types

1. Command (type: "command") - run a shell script. Most common.

2. Prompt (type: "prompt") - send a prompt to a Claude model (Haiku by default) for a yes/no decision. No shell needed. Good for simple evaluation logic.

3. Agent (type: "agent") - spawn a subagent that can use tools (Read, Grep, Glob) to investigate before deciding. Most powerful - use when verification requires inspecting actual files or test output.

Configuration Structure

Handler fields (all types):

Command-specific fields:

matcher is a regex string:

• "Bash" - only Bash tool calls
• "Write\|Edit" - Write or Edit
• "mcp__memory__.*" - all tools from the memory MCP server
• "mcp__.*" - all MCP tools
• Omit entirely to match every occurrence of that event

What Hooks Receive (stdin JSON)

All hooks receive these common fields:

tool_name and tool_input are event-specific fields added on top. The tool_input schema varies by tool - for Bash it has command, for Write it has file_path and content, for Edit it has file_path, old_string, new_string, etc.

Exit Codes

The effect of exit code 2 depends on the event:

JSON Output (Finer-Grained Control)

Instead of exit codes alone, exit 0 and print JSON to stdout. Claude Code reads specific fields from it.

Universal fields (work on all events):

PreToolUse — use hookSpecificOutput:

PermissionRequest — use hookSpecificOutput:

PostToolUse, Stop, SubagentStop, UserPromptSubmit — top-level decision:

SessionStart / SubagentStart — inject context:

Prompt Hook — LLM Evaluates Yes/No

The model (Haiku by default) must respond with:

Agent Hook — Subagent Investigates

The subagent can use Read, Grep, Glob to inspect actual files - not just evaluate the hook input. Same { "ok": true/false } response format as prompt hooks.

Async Hooks

Set "async": true on a command hook to run it in the background. Claude continues working immediately while the hook runs.

When the async hook finishes, if it outputs JSON with systemMessage or additionalContext, that gets delivered to Claude on the next conversation turn.

Limitations of async hooks:

• Only works with type: "command" - not prompt or agent hooks
• Cannot block tool calls (action already proceeded)
• Output delivered on next turn, not immediately

Real Examples

1. Block rm -rf commands (PreToolUse)

2. Auto-run tests after file edits, async (PostToolUse)

3. Desktop notification on task finish (Stop)

4. Log every tool call (PostToolUse)

5. Inject git context at session start (SessionStart)

File Structure

~/.claude/
├── settings.json           ← global hook config
└── hooks/
    ├── guard.sh            ← blocks dangerous commands
    ├── notify.sh           ← desktop notifications
    └── logger.sh           ← tool call logging

.claude/                    ← inside your project repo
├── settings.json           ← project hooks (committable)
├── settings.local.json     ← project hooks (gitignored)
└── hooks/
    ├── run-tests.sh
    └── lint-check.sh

Always use $CLAUDE_PROJECT_DIR to reference project scripts:

SessionStart: Persist Environment Variables

SessionStart hooks have access to $CLAUDE_ENV_FILE - a special file where you can write export statements that persist for the entire session:

Variables written here are available in all Bash commands Claude runs during the session.

Power User Tips

• /hooks menu - type /hooks in Claude Code to view, add, and delete hooks without editing JSON. Changes don't take effect until reviewed here (security feature).
• Hooks in skills/agents - define hooks in YAML frontmatter of a skill or agent file; they're scoped to that component's lifetime only
• MCP tool matching - mcp__memory__.* matches all tools from the memory server; mcp__.*__write.* matches any write-type tool across all servers
• stop_hook_active - the Stop event includes this field; check it to prevent infinite loops (if it's true, your Stop hook is already running)
• claude --debug - shows which hooks matched, their exit codes, and stdout/stderr output
• Identical handlers deduplicated - if multiple matchers trigger the same command, it only runs once

Security Note

Hooks run with your full user permissions. Always:

• Quote shell variables: "$VAR" not $VAR
• Validate and sanitize stdin input before using it
• Use absolute paths for scripts
• Keep sensitive hooks in settings.local.json (gitignored), not settings.json

Sources

• Claude Code Hooks Reference (official docs)
• Hooks Quickstart Guide (official docs)