[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-standards skill — 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