[H1][HOOKS-BUILDER]
Dictum: *Deterministic behavior requires hooks; prompts fail execution guarantees.*
Build Claude Code hooks—shell commands execute at agent lifecycle events.
Tasks:
- Read index.md — Reference file listing for navigation
- Read lifecycle.md — Event table, input schemas, exit codes
- Read schema.md — Configuration structure, matchers, JSON responses
- (integration) Read integration.md — Environment variables, context injection
- (scripting) Read scripting.md — Python standards, security patterns
- (recipes) Read recipes.md — Proven implementation patterns
- (troubleshooting) Read troubleshooting.md — Known issues, platform workarounds
- (prose) Load
style-standardsskill — Voice, formatting, constraints - Validate — Quality gate; see §VALIDATION
Scope:
- *Event Selection:* Choose hook type by automation goal (blocking vs observing).
- *Configuration:* Author settings.json entries with matchers and timeouts.
- *Response Handling:* Control agent via exit codes, JSON responses, or prompt evaluation.
[REFERENCE]: index.md — Complete reference file listing
[1][EVENT_SELECTION]
Dictum: *Automation goal determines hook type; blocking capability varies by event.*
Decision Gate:
- *Intercept before execution?* → PreToolUse (validate/block/modify parameters)
- *Control permission dialogs?* → PermissionRequest (auto-approve/deny)
- *React after completion?* → PostToolUse (format, lint, add context)
- *Inject at session boundaries?* → SessionStart (context), UserPromptSubmit (per-message)
- *Evaluate task completion?* → Stop/SubagentStop (prompt type for LLM judgment)
Blocking vs Observing:
- *Blocking (exit 2):* PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, Stop, SubagentStop
- *Observing only:* Notification, PreCompact, SessionStart, SessionEnd
[2][CONFIGURATION]
Dictum: *Centralized configuration enables scope-aware hook precedence.*
| [INDEX] | [SCOPE] | [PATH] | [USE] | [GIT] |
|---|---|---|---|---|
| [1] | User | ~/.claude/settings.json | Global, all projects | N/A |
| [2] | Project | .claude/settings.json | Shared, committed | Commit |
| [3] | Local | .claude/settings.local.json | Personal, testing | Ignore |
Precedence: Local > Project > User.
[3][IMPLEMENTATION]
Dictum: *Deterministic and evaluative patterns require distinct execution modes.*
| [INDEX] | [TYPE] | [USE_CASE] | [TIMEOUT] | [CHARACTERISTICS] |
|---|---|---|---|---|
| [1] | command | Validation, formatting, rules | 60s | Deterministic, fast |
| [2] | prompt | Complex evaluation, LLM judgment | 30s | Context-aware, flexible |
Prompt Type Scope: Stop and SubagentStop events only; Haiku provides fast LLM evaluation.
Guidance:
Command hooks— Deterministic scripts receive JSON stdin; return exit codes + optional JSON stdout.Prompt hooks— LLM evaluates decisions; response schema:{"decision": "approve"|"block", "reason": "..."}.Blocking— Exit code 2 blocks action; stderr routes to Claude. Exit 1 also blocks (known bug #4809).
[4][SCRIPTING]
Dictum: *Hook reliability requires functional pipeline patterns.*
Python 3.14+ with strict typing. Zero imperative patterns.
[5][VALIDATION]
Dictum: *Gates prevent incomplete artifacts.*
[VERIFY] Completion:
- Event: Selected correct hook type for automation goal.
- Schema: Configuration structure validated per schema.md.
- Integration: Environment variables and context injection applied.
- Scripting: Security patterns and tooling gates passed.
- Quality: JSON syntax valid, timeouts appropriate.
[REFERENCE] Operational checklist: →validation.md