[H1][HOOKS-BUILDER]

Dictum: Deterministic behavior requires hooks; prompts fail execution guarantees.

Build Claude Code hooks—shell commands, prompt evaluations, or multi-turn agents execute at 15 agent lifecycle events.

Tasks:

1. Read index.md — Reference file listing for navigation
2. Read lifecycle.md — 14 events, input schemas, exit codes, blocking behavior
3. Read schema.md — Configuration structure, matchers, JSON responses, hook types
4. (integration) Read integration.md — Environment variables, context injection
5. (scripting) Read scripting.md — Python standards, security patterns
6. (recipes) Read recipes.md — Proven implementation patterns
7. (troubleshooting) Read troubleshooting.md — Known issues, platform workarounds
8. (prose) Load style-standards skill — Voice, formatting, constraints
9. 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)
• React after failure? → PostToolUseFailure (error handling, retry logic)
• Inject at session boundaries? → SessionStart (context), UserPromptSubmit (per-message)
• One-time provisioning? → Setup (tool installation, dependency setup via claude --init)
• Evaluate task completion? → Stop/SubagentStop (prompt/agent type for LLM judgment)
• Coordinate teams? → TeammateIdle (prevent idle), TaskCompleted (validate completion)
• Observe subagent lifecycle? → SubagentStart/SubagentStop (logging)

Blocking Events (exit 2 blocks action):

Non-blocking Events (exit 2 shows stderr only):

[2][CONFIGURATION]

Dictum: Centralized configuration enables scope-aware hook precedence.

Precedence: Local > Project > User. Same-event hooks from all scopes run in parallel.

Snapshot: Hooks captured at startup; mid-session edits require /hooks review to reload.

[3][IMPLEMENTATION]

Dictum: Deterministic and evaluative patterns require distinct execution modes.

Prompt/Agent Eligible Events: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted.

[CRITICAL] TeammateIdle does NOT support prompt or agent hooks — exit codes only.

Prompt/Agent Response Schema:

{"ok": true}
{"ok": false, "reason": "Explanation shown to Claude"}

ok: true allows the action. ok: false blocks it with the provided reason.

Command Hook Fields:

Prompt/Agent Hook Fields:

[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.
• Blocking: Verified event supports blocking (7 events) or observing (8 events).
• Schema: Configuration structure validated per schema.md.
• Timeout: Correct units (seconds): command=600, prompt=30, agent=60.
• 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