ADLC in Codex

The Codex integration is a native plugin, not a Claude compatibility shim. It ships six progressive-disclosure skills, hooks across eight Codex lifecycle events, an allowlisted MCP gate server, and nine project-agent templates. ADLC evidence under .adlc/ remains the source of truth.

Install

See Version requirements for the shared @adlc/cli/plugin lockstep-versioning requirement (1.4.2 or newer is specifically what makes the adlc mcp-server entrypoint available). Codex installs the native plugin through its Git marketplace; installing @adlc/codex with npm alone does not register the plugin with Codex.

npm install -g @adlc/cli@latest
codex plugin marketplace add voodootikigod/adlc --ref main
codex plugin add adlc-codex@adlc
adlc init --root /absolute/path/to/project

The initializer is idempotent. It creates the committable .adlc/ runtime and current .codex/agents/*.toml project roles without modifying ~/.codex or overwriting project-owned files. Start a new Codex thread after installation and review the bundled hooks when Codex prompts you.

If an older compatibility install is producing a translated PostToolUse hook exited with code 1 error, remove it and install the native plugin:

codex plugin remove adlc@plugins-cli
codex plugin add adlc-codex@adlc

Native surfaces

The MCP gate tool exposes a deliberately small read-only allowlist, requires --prompt-only for generative gates, and rejects path escapes, control characters, mutating flags, and nested-command/provider arguments. Commands are executed without a shell. The MCP transport launches the stable CLI entrypoint adlc mcp-server and preserves the active project directory; it does not depend on plugin-root placeholder expansion. Lifecycle hooks separately use Codex's PLUGIN_ROOT and PLUGIN_DATA contracts.

Rail enforcement

The PreToolUse hook automatically arms when .adlc/current-ticket.json selects an incomplete ticket with frozen rails. ADLC_TICKET can select a ticket explicitly. ADLC_P4_ENFORCEMENT=1 forces enforcement and ADLC_P4_ENFORCEMENT=0 deliberately opts out locally.

Once active, conflicting or stale ticket state and writes to frozen rails fail closed. The hook gives immediate feedback, but Codex hooks are guardrails, not a complete security boundary. Keep the repository rails-guard CI job required; it is the authoritative proof over the committed diff.

PostToolUse only tracks repeated failures. Its implementation catches internal errors and exits successfully, so telemetry cannot break a Codex tool call.

Context-rot handoff

When wired, a third PreToolUse hook evaluates the deny-set from @adlc/context-handoff on the same matcher as the rail and build gates.

Once a session passes the handoff band, a deny record is written for it under .adlc/handoffs/denies/. While any such record is open and unauthorized, the session loses structured edits and the shell wholesale — including attempts to run adlc handoff write|resume|bypass|repair|unlock from the agent's own shell. Structured writes to the deny store, resume-auth caches, model-ok stamps, and lock files are refused whether or not a deny is active. The shell is A shell command naming one of those paths — in any literal spelling: relative, dot-relative, absolute, symlinked, or a parent directory that holds them — is refused too, deny-set or not — there is no CI backstop for them, because .adlc/* is gitignored and a deletion never reaches a diff. That check reads literal paths only: it cannot see through a variable, an expansion, or an interpreter one-liner, so it raises the cost of the obvious attempt rather than closing the class.

The session that wrote the record stays denied even after another session consumes it. Clearing the deny is a host action, not an agent one: resume in a fresh session with adlc handoff resume, or repair the record from a terminal.

Session identity comes from the hook payload's session_id and falls back to the transcript_path stem. With neither available, mutations fail closed once the band fires or a deny store already exists — a clean repository is never affected.

A signed resume-auth cache cannot be verified by this hook, and that is deliberate. Codex hooks run from the plugin's installed location and resolve @adlc/context-handoff by walking up into the project's node_modules, so the module they import is project-controlled code. Handing it ADLC_MANIFEST_KEY would let any repository shipping a package under that name exfiltrate the manifest trust anchor. The hook therefore reports resume_auth_unverifiable:no_manifest_key and keeps denying; the way out stays what it already was — continue in a fresh session, or repair from a terminal. (The in-process integrations, opencode and pi, resolve the package through their own declared dependency and do verify.)

Update, inspect, and remove

npm install -g @adlc/cli@latest
codex plugin marketplace upgrade adlc
codex plugin add adlc-codex@adlc
codex plugin list --json --available
codex plugin remove adlc-codex@adlc

Upgrade the CLI and marketplace plugin together, then start a new Codex thread so the refreshed MCP transport is loaded.

Maintainers can run the offline contract and the isolated live install proof:

node scripts/codex-install-smoke.mjs .
ADLC_CODEX_LIVE_INSTALL=1 node scripts/codex-install-smoke.mjs .

The live proof uses throwaway home/config/cache directories, installs through the real Codex marketplace commands, starts the MCP server declared by the installed plugin, makes a successful tool call, exercises the installed hook, and verifies that the user's real home is unchanged.

Phase routing

Source: plugins/adlc-codex/ · design rationale: ADR 0001.