What problem does it solve?
Hook authoring and auditing across Claude Code, Codex, and Gemini is easy to get subtly wrong—leading to missed enforcement, inconsistent event taxonomies, incorrect path resolution, or unsafe halts without proper structured handoff.
Core Features & Use Cases
- Single-script, multi-runtime hook behavior: Author one
.claude/hooks/<name>.js that works consistently across CC, Codex, and Gemini by validating COC_RUNTIME and normalizing hook payloads.
- Deterministic halt discipline: Ensure all halting branches use
lib/instruct-and-wait.js::emit() with the required six fields, and enforce the mandatory timeout fallback (setTimeout → {continue: true} → process.exit(1)).
- Security and enforcement correctness: Prevent weak “regex-only” block severity by requiring structural/AST/process-state evidence for
severity: "block", and maintain Codex gap coverage via the MCP guard bijection and validator-13 predicate shapes.
- Portability across CLIs: Resolve project directory safely using
CLAUDE_PROJECT_DIR || GEMINI_PROJECT_DIR || payload.cwd so Codex works without a project-dir env var.
- Audit-ready regression safety: Pair detectors with required audit fixtures and validator/extractor constraints (including predicate-shape compatibility) to avoid silent enforcement drift.
Quick Start
Use the hook-authoring skill to author a new hook script at .claude/hooks/<name>.js, validate it against the required output discipline and timeout fallback, then register it in .claude/settings.json for Claude Code and in the appropriate manifest for Codex/Gemini.
