| name | hooks-builder |
| description | Builds Claude Code and Codex hooks — enforcement, where a rule the model keeps ignoring becomes a deterministic exit-2 block, one body serving both providers. Use for PreToolUse gates, PostToolUse formatting/redaction, PermissionRequest auto-approval, SessionStart injection, Stop/SubagentStop continuation, PreCompact extraction, async guardrails, and Codex hooks.json/config.toml adapters. |
[HOOKS_BUILDER]
A hook binds a handler — shell command, HTTP endpoint, MCP tool call, single-turn prompt, or multi-turn agent — to a lifecycle event, filtered by a matcher and an optional if rule. Event selection decides what the automation intercepts, handler selection decides whether the verdict is deterministic or judged, and control-channel selection decides how it binds: exit 2 with a stderr reason is the one blocking primitive identical on both providers, and exit-0 stdout JSON is the scalpel that rewrites input, redacts output, or injects context.
Build order: pick the event, pick the handler, write the config into the provider's settings surface, then prove it with a direct stdin replay. A Python body draws its dependencies from the estate's admitted uv-resolvable libraries — msgspec for wire admission, anyio for structured concurrency and subprocess, httpx for transport, stamina for retry — composing each primitive at full depth, msgspec-lean on the hot path and richer off it.
[01]-[ROUTING]
[REFERENCES]:
- [01]-EVENTS: censuses both providers' events — matcher values, input payload, exit-2 blockability, decision-control fields.
- [02]-CONFIG: placement, scopes, matcher-evaluation law, handler types and fields, exec versus shell, JSON output contract.
- [03]-DUAL_PROVIDER: one canonical body behind thin per-provider adapters; exit-2 portability, dialect divergence.
- [04]-SCRIPTING: Python hook body: uv single-file packaging, typed payload admission, channel discipline, hot-path budget.
- [05]-INTEGRATION: harness seams — placeholders, context injection, env persistence, async lanes, telemetry.
- [06]-SECURITY: owns the threat surface, the enforcement-locus law, disposition by role, and supply-chain trust.
- [07]-VERIFICATION: fixture replay, malformed-payload and timeout cases, red-team harness, diagnostics, symptom index.
- [08]-RECIPES: catalogs every advanced move with its hinge and the naive form it beats.
[TEMPLATES]:
- [01]-PRETOOLUSE_GATE: typed validator, per-command semantic dispatch, sandbox admission, fail-closed exit-2 block.
- [02]-POSTTOOLUSE_FORMAT: MODE-polymorphic owner formatting through the
fmt router, redacting tool output.
- [03]-SESSION_CONTEXT: SessionStart injector with gated probes, session-to-pane routing capture, and env persistence.
- [04]-STOP_CONTINUATION: Stop/SubagentStop evaluator: durable counter, layered detection, error-aware reprompt.
- [05]-ASYNC_GUARDRAIL: off-hot-path
asyncRewake check waking the session only on findings new since the baseline.
- [06]-PRECOMPACT_EXTRACT: writes a typed transcript summary as the handoff across the compaction boundary.
- [07]-CODEX_ADAPTER: thin per-provider adapter piping a Codex payload into one canonical body.
[EXAMPLES]: complete droppable exemplars, each composing several recipe moves into one production hook.
- [01]-DISPATCH_DAEMON: priority-banded handler registry on a session-scoped Unix socket, in-process when none answers.
- [02]-REDTEAM_HARNESS: paired-corpus auditor, subprocess or in-process; reports each fixture against its benign twin.
- [03]-TELEMETRY_TRANSMITTER: async CloudEvents or private-tier, chained after policy, fail-open by construction.
- [04]-PERMISSION_AUTOAPPROVE: persists a durable PermissionRequest rule; codex brand strips reserved fields.
- [05]-NUDGE_INJECTOR: UserPromptSubmit table decoded from
nudges.json with match/exclude regex and a priority band.
[02]-[EVENT_SELECTION]
- Intercept before execution ->
PreToolUse (block, rewrite input, or defer).
- Permission dialogs ->
PermissionRequest; after an auto-mode denial -> PermissionDenied (retry signal).
- React after completion ->
PostToolUse (format, lint, redact output), PostToolUseFailure (error handling).
- After a parallel batch, before the next model call ->
PostToolBatch.
- Session boundaries ->
SessionStart (context, watch paths, session title), SessionEnd (cleanup); one-time provisioning -> Setup.
- Per-prompt ->
UserPromptSubmit (inject context or block); command expansion -> UserPromptExpansion.
- Displayed text ->
MessageDisplay (display-only rewrite).
- Completion judgment ->
Stop/SubagentStop (prompt or agent handler, or a completion-token command hook).
- Teams and tasks ->
TeammateIdle (keep working), TaskCreated (roll back), TaskCompleted (gate completion).
- Environment reactivity ->
FileChanged, CwdChanged, ConfigChange (audit or block settings edits), InstructionsLoaded (observe memory loads).
- Worktrees ->
WorktreeCreate/WorktreeRemove; compaction -> PreCompact/PostCompact; MCP input -> Elicitation/ElicitationResult.
- Observation only ->
Notification, SubagentStart, StopFailure (API-error autopsy; output and exit code ignored).
Codex carries ten of these events, Stop/SubagentStop among them; the team and extra-lifecycle tiers are Claude-only. Its delta and fill are the events reference.
[03]-[HANDLER_SELECTION]
| [INDEX] | [TYPE] | [OWNS] | [DEFAULT_TIMEOUT] |
|---|
| [01] | command | Deterministic validation, formatting, transforms | 600s |
| [02] | http | POSTing event JSON to a service endpoint | 600s |
| [03] | mcp_tool | Calling a connected MCP server tool | 600s |
| [04] | prompt | Single-turn LLM judgment, {ok, reason} decision | 30s |
| [05] | agent | Multi-turn tool-using verification, up to 50 turns | 60s |
command is the shared handler and owns deterministic policy. Codex parses prompt/agent/async and skips them, so a dual-provider hook uses command. Prompt and agent handlers bind only to the judgment-eligible events; the eligibility roster is the config reference.
[04]-[PROVIDER_DIVERGENCE]
Claude Code is the superset: thirty events, five handler types, terminalSequence, async, a rich per-event JSON dialect. Codex is command-only and synchronous with ten events. Exit 2 with a stderr reason on the shared tool, prompt, and Stop/SubagentStop events behaves identically on both, so a body that only ever blocks that way ports verbatim. Once a hook injects context or rewrites a value through stdout JSON, the dialects diverge and the dual-provider reference owns the exact shape.
[05]-[GATE]
A built hook proves before it ships: the settings JSON parses (python3 -c "import json; json.load(open('.claude/settings.json'))"), the script is executable, and a fixture replay exercises the handler — printf '%s' '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"npm test"}}' | ./hook.py; echo $? returns the intended exit code, with a malformed-payload replay proving the fail-closed path. Full verification battery, dual-mode red-team harness, and diagnostic surfaces are the verification reference.
