hooks-builder

name

hooks-builder

description

Builds Claude Code and Codex hooks as one discipline — command, HTTP, MCP-tool, prompt, and agent handlers across the full event surface. Use when building PreToolUse validation, PostToolUse formatting or redaction, PermissionRequest auto-approval, SessionStart context injection, Stop or SubagentStop continuation, PreCompact extraction, async guardrails, telemetry transmitters, a Codex hooks.json or config.toml adapter, or any deterministic blocking and non-blocking agent control — and when porting one canonical hook body across both providers. Where an instruction lives — memory, rule, setting, or hook — belongs to harness-steering.

[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 or observes, handler selection decides whether the verdict is deterministic or judged, and control-channel selection decides how the verdict binds: exit 2 with a stderr reason is the one blocking primitive that behaves identically 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 before it ships. A Python body draws its dependencies from the estate's admitted libraries assumed uv-resolvable — msgspec for wire admission, anyio for structured concurrency and subprocess, httpx for transport, stamina for retry — composing the shipped primitive at full depth rather than a hand-rolled naive reimplementation, 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: carries one canonical body behind thin adapters, the portable exit-2 path, per-event output-dialect divergence, Codex discovery and trust, the component-hook port.
• [04]-SCRIPTING: Python hook body: uv single-file packaging, typed payload admission, channel discipline, hot-path budget.
• [05]-INTEGRATION: path placeholders, context injection, terminal notifications, env persistence, async execution, session-to-pane routing, the telemetry lane, component-scoped frontmatter.
• [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 each advanced move — command decomposition, value rewrite, priority-banded dispatch, the completion loop, data-driven injection, hot-path offload, the telemetry chain, standing permission, durable state, the paired audit — 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 only handler both providers run and the only one that enforces hard security — an mcp_tool disconnect or a prompt model timeout degrades to a non-blocking error, so real policy rides command. Codex parses prompt/agent/async and skips them, and has no http/mcp_tool handler; a dual-provider hook is therefore a command hook. 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, and a rich per-event JSON dialect. Codex is command-only, synchronous, ten events including Stop/SubagentStop, tool coverage limited to Bash/apply_patch/MCP, with notify a separate legacy notification channel beside the bus. Exit 2 plus a stderr reason on the shared tool, prompt, and Stop/SubagentStop events is the one path that behaves identically on both — a hook body that only ever blocks that way ports verbatim with zero dialect branching. Once a hook injects context or rewrites a value through stdout JSON, the per-event dialect diverges and the dual-provider reference owns the exact shape per provider.

[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.