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]-: placement, scopes, matcher-evaluation law, handler types and fields, exec versus shell, JSON output contract.