codex-hooks-builder

Codex Hooks Builder

Philosophy

Keep the workflow focused on the requested hook decision. Prefer repo-local contracts, wrappers, and validation before generic advice.

When To Use

• The user wants Codex hooks created, upgraded, installed, or audited.
• Repo-local or user-level .codex hook runtime files need hardening.
• A hook pack needs scaffold scripts or validation fixtures.
• The user wants runtime cards, subagent lifecycle hooks, artifact verification, hook decision telemetry, or claim-vs-evidence Stop checks.

Inputs

Require the target hook pack path, install boundary (repo-local, user-level, or plugin-owned), trigger events, script runtime, validation commands, schema/runtime evidence source, active hook sources, and rollback owner before writing.

Outputs

For non-trivial hook work, return schema_version: 1, target hook pack, install boundary, changed paths, runtime contract, validation evidence, rollback, blocker or residual risk, and confidence. The runtime contract must name the runtime-card source, task-envelope injection, SubagentStop reviewer-receipt validation, JSONL telemetry sink, and Stop claim-versus-evidence checks when those lifecycle hooks are selected.

Discovery Interview

• Ask one round at a time.
• Use a plain-language question.
• Explain why this matters for the current skill decision.
• avoid dumping the whole interview plan at once.
• Read references/discovery-interview.md when the request is underspecified.

Workflow

1. Start with 2-3 focused surfaces:
   • Find hook config: rg -n "SessionStart|SubagentStart|SubagentStop|PreToolUse|PermissionRequest|PostToolUse|PreCompact|PostCompact|UserPromptSubmit|Stop|hooks" .codex codex hooks . 2>/dev/null
   • Find executable scripts: find . -path '*hook*' -type f -maxdepth 5
   • Check source ownership before projection: rg -n "allow_managed_hooks_only|hooks.json|codex_hooks" .
2. Confirm repo-local versus user-level ownership before editing.
3. Inspect hook config, scripts, install path, active sources, and trust state.
4. Check current schema/runtime evidence before changing events, matchers, flags, or output handling.
5. Model supported events: SessionStart, SubagentStart, SubagentStop, PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, UserPromptSubmit, Stop.
6. Make the smallest source edit; use scaffold helpers only when they fit.
7. For lifecycle or closeout hooks, define the runtime card path, task-envelope source, artifact receipt schema, blocked-state taxonomy, and telemetry sink before implementation.
8. Validate config, script permissions, effective hook listing, and scaffold tests; fix the first failed gate before continuing.