The Hook System — Architecture, Event Taxonomy, and Hook Types
Hooks are shell commands, HTTP endpoints, or LLM calls that fire automatically at specific points in Claude Code's lifecycle. They're the most underused feature in Claude Code — and the one that turns it from a tool into a system.
Quick Reference
- →Hooks fire at lifecycle events: session, turn, tool call, and async/config events
- →4 hook types: command (shell), http (POST endpoint), prompt (LLM eval), agent (subagent)
- →PreToolUse can block actions (exit 2); PostToolUse runs after but cannot undo
- →SessionStart/End for setup and cleanup; PreCompact for saving context before compaction
- →if field for conditional hooks: only fire when condition matches (reduces process spawning)
- →Hook receives JSON on stdin with tool name, args, and session context
- →Hook communicates back via exit code + stdout JSON (command hooks) or response body (http hooks)
- →Configured in settings.json under the hooks object
What Hooks Are
Hooks are user-defined commands that Claude Code executes automatically when specific lifecycle events occur. When an event fires and a matcher matches, Claude passes JSON context about the event to your hook. Your hook responds with an exit code (and optionally JSON output) that Claude reads to decide what to do next.
This makes Claude Code programmable. Instead of just watching Claude work and occasionally intervening, you attach persistent behaviors to its lifecycle. Format code after every edit. Block dangerous bash commands before they run. Log every file change. Send a Slack notification when a task completes. None of this requires Claude's cooperation — it happens because of the hook.
This is the key property: hooks execute independently of Claude's decisions. A PreToolUse hook that blocks git push --force blocks it regardless of what Claude thinks about it or what instructions it was given. Hooks enforce behavior, not suggest it.