CASAN/packages/casan-devkit/templates/codex/README.md

CASAN Codex adoption template (Plan-20)

casan init --client codex merges hooks.json into .codex/hooks.json. Each handler calls .casan/casan-hook.py, which resolves and verifies the pinned global harness before dispatching the Codex adapter. No custom [casan] TOML keys are required.

The generated hooks.json intentionally keeps only the top-level hooks key. This remains compatible with Codex CLI 0.142.5, which rejects newer optional top-level metadata such as description.

This one integration covers the local Codex runtime across the desktop app, CLI, and IDE extension. It does not claim coverage for Codex Cloud/Web, where a repo-local process and its .casan/casan-hook.py bootstrap are not the local execution boundary.

Important Codex-specific facts (Spike-20 §4.2):

• Trust review is mandatory. Codex loads project-local hooks only after the user accepts a trust prompt. Run casan doctor --client codex (or the bridge doctor op) to confirm the trust/onboarding state — it is never hidden from a member.
• Tool hooks are a guardrail, not a complete boundary. Hosted/specialized tools may fall outside hook coverage; a turn that uses an uncovered tool is downgraded (non-certified), not silently certified.
• Token/cost source is not assumed. Unless Codex supplies a stable usage source, H6 records the number as null with telemetry_quality=partial — it is never invented (Spike-20 X6).
• For enterprise enforcement, pin hooks via managed policy so a member cannot disable them and set CASAN_AGENTIC_INTEGRATION_MODE=managed_hook through the managed environment (not the committed config).

The command shape follows current Codex hooks: nested command handlers, timeout in seconds, continue/stopReason for turn events, and exit 2 for a denied PreToolUse. The adapter reads documented fields plus defensive aliases.