Agent Skills: [H1][HOOKS-BUILDER]

[H1][HOOKS-BUILDER]

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

Build Claude Code hooks—shell commands execute at agent lifecycle events.

Tasks:

1. Read index.md — Reference file listing for navigation
2. Read lifecycle.md — Event table, input schemas, exit codes
3. Read schema.md — Configuration structure, matchers, JSON responses
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:<br>

• 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:<br>

• 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