Phase 2 — Codex Adapter

Goal

Add the second backend (codex) using the abstraction phase 1 established. The main value of this phase is not the Codex backend itself — it's that two backends prove the abstraction works. Surface every place where Codex's CLI surface doesn't fit cleanly into the phase-1 contracts.

Preconditions

Phase 1 shipped: the AgentAdapter Protocol, AgentEvent union, runner.py, tools/base.py, Tier-0 sandbox, technical-user auth all exist and are exercised by the Claude Code adapter.

Deliverables

1. adapters/codex.py implementing AgentAdapter for the OpenAI Codex CLI.
2. tools/codex.py — a thin subclass of ExternalAgentTool with backend = "codex".
3. Registry entry for codex.
4. Config example for Codex in the plugin's docs / sample codumentor.yaml.
5. Unit tests parallel to the Claude Code tests.
6. If AgentAdapter Protocol or AgentEvent union must change to accommodate Codex, the changes must be strictly backward-compatible (additive fields only; no renames; no removed kinds) and called out in the handoff.

New files

src/codumentor/plugins/external_agent/adapters/codex.py
src/codumentor/plugins/external_agent/tools/codex.py
tests/test_external_agent_adapter_codex.py
tests/fixtures/external_agent/codex_stream_*.jsonl  (or .txt if non-stream)

Touched: registry.py (one new entry), plugin.py (instantiate the Codex tool when configured).

Implementation steps

1. Determine Codex's actual CLI surface. Run codex --help and the help for any subcommands (likely codex exec for non-interactive). Document the exact flags you chose in your handoff. As of the design date, Codex's streaming JSON support was less mature than Claude Code's; if stream-json is not viable, fall back to parse_oneshot and emit a single completed event after the process exits.

1. Auth. OpenAI Codex authenticates with OPENAI_API_KEY (or similar — confirm). The Codex CLI may also have its own login state directory; for phase 2 we use OPENAI_API_KEY via technical-user auth only. Per-user HOME is phase 6.

1. Session resume. If Codex supports a resume mechanism, wire it up in build_argv and extract_session_id. If it does not, set supports_resume = False and document the consequence: a follow-up call to codex(query=..., subagent_id=X) will start a fresh Codex session each time but the Codumentor-side conversation history remains. This is acceptable for phase 2.

1. Event mapping. Map Codex's output to the eight AgentEvent kinds. Anything that doesn't fit one of the existing kinds is dropped silently — do not invent new kinds without orchestrator approval (a new kind is a contract change and must surface).

1. Tests. Same shape as phase 1's tests — fixture-driven, no real binary required.

Acceptance criteria

• make test passes.
• Manual probe with the real codex CLI installed: codex(query="hello") returns a response wrapped in the envelope; transcript card renders.
• If Codex does not support streaming, the card still appears (in a "pending → completed" two-state form) and the test asserts the single completed event is emitted.

Out of scope

• OpenCode / Gemini — phase 4.
• BYO API key for Codex — phase 3.
• Adapter abstraction overhaul. If you find Codex requires substantial changes to AgentAdapter, halt and surface to the orchestrator. The orchestrator decides whether to redesign or to absorb the asymmetry in the Codex adapter alone.

Handoff

Fill out the template from §7 of the index. Be explicit in "Contracts established/changed" about:

• The exact Codex argv invocation.
• Whether supports_resume and supports_stream_json are true or false for Codex.
• Any additive Protocol or union changes (with exact diff).
• Any AgentEvent payload fields that Codex needed which Claude Code did not produce (these may be optional fields that Claude Code's adapter should later be updated to emit too — flag in "Open questions").