coderouter-cli 2.7.8__tar.gz → 2.7.9__tar.gz

{coderouter_cli-2.7.8 → coderouter_cli-2.7.9}/CHANGELOG.md

@@ -9,9 +9,103 @@ are kept verbatim where the Japanese text itself is the subject).
 
 ---
 
+## [v2.7.9] — 2026-07-11 (agent_cli Phase 1b: codex)
+
+Adds the third target to the `agent_cli` adapter: `agent: codex` (the OpenAI
+Codex CLI) is now implemented alongside `claude` (Phase 1a) and `grok`
+(Phase 1d). The implementation was verified against the real CLI (codex-cli
+0.144.1, 2026-07-11), and one design-time assumption from the 2026-07
+research did not survive contact with it: `codex exec` has no approval flag
+at all (`-a`/`--ask-for-approval` doesn't exist in `exec --help` on
+0.144.1, since non-interactive execution has no approval prompt to control
+in the first place), so the design's separate `edit`/`full_auto` mappings
+(`-a on-request` / `-a never`) collapse into a single `-s workspace-write`
+mapping — unlike claude/grok, codex does not distinguish `edit` from
+`full_auto`. The verified JSONL `turn.completed.usage` payload also carries
+a field the design didn't record, `reasoning_output_tokens`, which is now
+normalized defensively into `completion_tokens_details.reasoning_tokens`.
+Everything else (stdin prompt delivery, `--skip-git-repo-check`,
+`--ephemeral`, the absence of `--max-turns`/`--timeout`, the ~8-day OAuth
+staleness) matched the design closely. `gemini` remains schema-declared but
+rejected (Phase 1c pending).
+
+### Added
+
+- **`agent: codex` builder/parser in `AgentCliAdapter`**
+  (`coderouter/adapters/agent_cli.py`) — invokes the Codex CLI one-shot as
+  `codex exec --json --skip-git-repo-check --ephemeral -m <model>
+  -C <workdir> -s read-only -` (read_only default). The prompt is delivered
+  on stdin with an explicit trailing `-` sentinel — the same channel as
+  claude, unlike grok's `--prompt-file` delivery. Output is JSONL on
+  stdout (progress goes to stderr); the final answer is the `item.text` of
+  the **last** `item.completed` event whose `item.type=="agent_message"`.
+  Usage comes from `turn.completed.usage` and is normalized as
+  `prompt_tokens=input_tokens` / `completion_tokens=output_tokens`, with
+  `cached_input_tokens` kept as `prompt_tokens_details.cached_tokens` (a
+  subset of `input_tokens`, not added on top — verified 13810 ⊃ 9984) and
+  `reasoning_output_tokens` kept as
+  `completion_tokens_details.reasoning_tokens` when nonzero; multiple
+  `turn.completed` events, if seen, are summed. `thread_id` (from
+  `thread.started`) surfaces as `coderouter_session_id`. Parsing is
+  defensive line-by-line — a non-JSON line doesn't abort the rest of the
+  stream, but no valid `agent_message` (or empty stdout) raises a
+  retryable `AdapterError`, as does any `error` event or `turn.failed`.
+  The CLI is pre-1.0 and `--json`'s alias is still `--experimental-json`
+  (schema not frozen), so version pinning is recommended alongside the
+  defensive parsing.
+- **`sandbox_mode` → codex flag mapping** — `read_only` → `-s read-only`;
+  `edit` → `-s workspace-write`; `full_auto` → `-s workspace-write` (same
+  as `edit` — `exec` has no approval flag in 0.144.1, and
+  `--dangerously-bypass-approvals-and-sandbox` is never used). As with
+  claude/grok, the effective mode is clamped to read-only whenever
+  `allow_file_writes=false`, regardless of `sandbox_mode`.
+- **`--skip-git-repo-check` always passed** — CodeRouter's isolated workdir
+  is never a git repository, and codex's default "trusted directory" check
+  fails immediately outside one (exit 1, stderr `Not inside a trusted
+  directory and --skip-git-repo-check was not specified.` — field-verified).
+  The adapter always passes this flag, so that error should never surface
+  in normal operation.
+- **`--ephemeral` always passed** — prevents the session from persisting to
+  disk, for the same stateless-transformation rationale as grok's
+  `--no-memory`. Not configurable.
+- **`max_turns` ignored for codex** — `codex exec` has neither
+  `--max-turns` nor `--timeout`; `AgentCliConfig.max_turns` has no effect
+  when `agent: codex`, and `exec_timeout_s` + process-group `SIGKILL` is
+  the only time bound.
+- **`coderouter_session_id` via `thread_id`** — same response-metadata
+  treatment as claude's `session_id` and grok's `sessionId`.
+
+### Changed
+
+- **Unsupported-agent error message** — constructing the adapter with a
+  not-yet-implemented agent now lists all three implemented agents (e.g.
+  `agent 'gemini' is not implemented yet (implemented: claude, codex,
+  grok)`) instead of the two-agent wording from v2.7.8.
+- **Schema docstrings** (`coderouter/config/schemas.py`) — `AgentCliConfig`
+  field descriptions updated for the three-agent reality, including the
+  `max_turns` docstring noting codex ignores it.
+- **Docs & examples** — `docs/backends/external-agents.md`/`.en.md` gain a
+  full codex section (config example, adapter argv, stdin-vs-`--prompt-file`
+  contrast with grok, sandbox mapping table with the no-approval-flag-in-exec
+  note, JSONL schema and usage normalization including
+  `reasoning_output_tokens`, OAuth setup with the ~8-day staleness caveat
+  and `CODEX_API_KEY`/`OPENAI_API_KEY`/`CODEX_HOME`, and the pre-1.0
+  version-pin caveat) and updated implementation-status wording (claude +
+  codex + grok implemented; gemini-only rejected). The design doc
+  `docs/designs/external-agents-adapter.md` gets a new appendix §11.4
+  recording the verified deltas between the 2026-07 research and
+  codex-cli 0.144.1 (body text left as the historical record); its header
+  status line now lists Phase 1b alongside 1a/1d.
+  `examples/providers-agent-cli.yaml` promotes codex out of the
+  not-implemented preview into a documented (still commented-out, so
+  copying the file doesn't require codex to be installed) block with
+  `model: gpt-5.5`, `paid: false` for subscription OAuth, and
+  `passthrough_env: []`; the preview section at the bottom is retitled to
+  Phase 1c (gemini only), with codex removed from it.
+
 ## [v2.7.8] — 2026-07-10 (agent_cli Phase 1d: grok)
 
-Adds the second target to the `agent_cli` adapter: `agent: grok` (the xAI
+**PR #68**. Adds the second target to the `agent_cli` adapter: `agent: grok` (the xAI
 Grok CLI) is now implemented alongside `claude` from Phase 1a. The
 implementation was verified against the real CLI (grok v0.2.93, [stable]
 channel, 2026-07-10), and several design-time assumptions from the 2026-07

{coderouter_cli-2.7.8 → coderouter_cli-2.7.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.7.8
+Version: 2.7.9
 Summary: Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible.
 Project-URL: Homepage, https://github.com/zephel01/CodeRouter
 Project-URL: Repository, https://github.com/zephel01/CodeRouter

{coderouter_cli-2.7.8 → coderouter_cli-2.7.9}/coderouter/adapters/agent_cli.py

@@ -18,15 +18,24 @@ CodeRouter merely performs the one conversion. Following the
 ``openai_compat`` precedent, a *single* adapter class fronts *multiple*
 target agents, dispatched on the ``agent`` field.
 
-Implemented agents (Phase 1a + 1d)
-==================================
+Implemented agents (Phase 1a + 1b + 1d)
+========================================
 
-Two targets are implemented here:
+Three targets are implemented here:
 
 * ``claude`` (Claude Code CLI, Phase 1a) — the most stable CLI, the most
   fine-grained safety controls, and the only one that emits
   ``total_cost_usd`` directly (making it the reference implementation for
   the parser / cost path).
+* ``codex`` (codex CLI, Phase 1b) — headless one-shot via ``codex exec
+  --json``, prompt on stdin (like claude). The CLI is pre-1.0 and emits
+  defensively-parsed JSONL (one event per line); usage comes from
+  ``turn.completed`` events, normalized per design §5.1.6 with
+  ``cached_input_tokens`` kept as a *subset* of ``input_tokens`` (unlike
+  claude, which folds its cache buckets into ``prompt_tokens``).
+  ``--skip-git-repo-check`` and ``--ephemeral`` are always passed — the
+  isolated workdir is not a git repo, and the adapter never wants
+  session persistence.
 * ``grok`` (grok CLI, Phase 1d) — headless one-shot via ``--prompt-file`` +
   ``--output-format json``. The CLI emits no token/cost figures, so usage
   is reported as zeros (cost stays 0 unless the operator sets
@@ -34,9 +43,9 @@ Two targets are implemented here:
   so a user-level cross-session memory setting cannot leak state between
   requests.
 
-The remaining agents (codex / gemini) are declared in the config schema so
-providers.yaml is forward-compatible, but constructing an adapter for them
-raises a clear ``AdapterError`` until their phase (1b / 1c) lands.
+The remaining agent (gemini) is declared in the config schema so
+providers.yaml is forward-compatible, but constructing an adapter for it
+raises a clear ``AdapterError`` until its phase (1c) lands.
 
 Security (design §6, non-negotiable)
 ====================================
@@ -44,10 +53,11 @@ Security (design §6, non-negotiable)
 * **allowlist argv only** — the child is launched with
   :func:`asyncio.create_subprocess_exec` and a list argv. ``shell=True`` is
   never used; the prompt is never subject to shell interpretation (claude
-  reads it from stdin; grok reads it from a private ``0600`` prompt file
-  inside the resolved workdir — its ``-p`` requires the prompt as an argv
-  value, and argv would both hit Linux's ~128KiB ``MAX_ARG_STRLEN`` on huge
-  prompts and leak the text into ``ps`` output).
+  and codex read it from stdin — codex's argv carries a trailing ``-``
+  sentinel making that explicit; grok reads it from a private ``0600``
+  prompt file inside the resolved workdir — its ``-p`` requires the prompt
+  as an argv value, and argv would both hit Linux's ~128KiB
+  ``MAX_ARG_STRLEN`` on huge prompts and leak the text into ``ps`` output).
 * **default read-only** — ``allow_file_writes=False`` /
   ``sandbox_mode="read_only"`` are the defaults, mapped to claude's
   ``--permission-mode plan``. Writes require explicit opt-in and the sandbox
@@ -127,6 +137,17 @@ _GROK_SANDBOX_ARGS = {
     "full_auto": ["--sandbox", "workspace", "--always-approve"],
 }
 
+# sandbox_mode → codex ``-s/--sandbox`` value (design §5.4, codex-cli
+# 0.144.1, verified via facts-codex.md). ``codex exec`` has NO approval
+# flag at all (non-interactive, so there is no prompt to approve/skip), so
+# ``full_auto`` collapses onto the same ``workspace-write`` value as
+# ``edit`` — there is nothing further to "auto" beyond granting writes.
+_CODEX_SANDBOX_ARGS = {
+    "read_only": ["-s", "read-only"],
+    "edit": ["-s", "workspace-write"],
+    "full_auto": ["-s", "workspace-write"],
+}
+
 
 def _chunk_text(text: str, size: int = _STREAM_CHUNK_CHARS) -> Iterator[str]:
     """Split ``text`` into ``size``-char pieces for the pseudo-stream."""
@@ -135,7 +156,7 @@ def _chunk_text(text: str, size: int = _STREAM_CHUNK_CHARS) -> Iterator[str]:
 
 
 class AgentCliAdapter(BaseAdapter):
-    """Invoke an external coding-agent CLI one-shot (claude + grok).
+    """Invoke an external coding-agent CLI one-shot (claude + codex + grok).
 
     The ``agent`` field selects the argv builder / output parser via the
     dispatch tables built in :meth:`__init__`, mirroring how
@@ -145,10 +166,10 @@ class AgentCliAdapter(BaseAdapter):
     def __init__(self, config: ProviderConfig) -> None:
         """Bind to a ``ProviderConfig`` and reject unsupported agents.
 
-        Constructing an adapter for an agent other than ``claude`` / ``grok``
-        raises a non-retryable :class:`AdapterError` — the other targets are
-        declared in the schema but not implemented until their phase
-        (design §9).
+        Constructing an adapter for an agent other than ``claude`` /
+        ``codex`` / ``grok`` raises a non-retryable :class:`AdapterError` —
+        the remaining target (gemini) is declared in the schema but not
+        implemented until its phase (design §9).
         """
         super().__init__(config)
         if config.agent_cli is None:  # pragma: no cover - schema enforces this
@@ -158,30 +179,34 @@ class AgentCliAdapter(BaseAdapter):
                 retryable=False,
             )
         self.acfg: AgentCliConfig = config.agent_cli
-        if self.acfg.agent not in ("claude", "grok"):
+        if self.acfg.agent not in ("claude", "codex", "grok"):
             raise AdapterError(
                 f"agent {self.acfg.agent!r} is not implemented yet "
-                f"(implemented: claude, grok). Wait for Phase 1b/1c.",
+                f"(implemented: claude, codex, grok). Wait for Phase 1c.",
                 provider=config.name,
                 retryable=False,
             )
         # agent → argv builder / output parser dispatch tables. claude landed
-        # in Phase 1a, grok in Phase 1d; Phase 1b/1c add codex / gemini.
+        # in Phase 1a, codex in Phase 1b, grok in Phase 1d; Phase 1c adds
+        # gemini.
         self._builders = {
             "claude": self._build_claude_argv,
+            "codex": self._build_codex_argv,
             "grok": self._build_grok_argv,
         }
         self._parsers = {
             "claude": self._parse_claude,
+            "codex": self._parse_codex,
             "grok": self._parse_grok,
         }
-        # Prompt delivery is per-agent: claude reads its print-mode prompt
-        # from stdin (10MB cap), which keeps argv free of the (potentially
+        # Prompt delivery is per-agent: claude and codex read their prompt
+        # from stdin (10MB cap; codex's argv carries a trailing "-" sentinel
+        # making that explicit), which keeps argv free of the (potentially
         # huge) prompt text. grok's ``-p`` REQUIRES the prompt as its argv
         # value (piped stdin is only appended as extra context, verified on
         # v0.2.93), so grok gets the prompt via ``--prompt-file`` instead —
         # see ``_write_prompt_file`` for the rationale.
-        self._uses_stdin = self.acfg.agent == "claude"
+        self._uses_stdin = self.acfg.agent in ("claude", "codex")
 
     # ------------------------------------------------------------------
     # BaseAdapter contract
@@ -465,6 +490,178 @@ class AgentCliAdapter(BaseAdapter):
             usage["duration_ms"] = data["duration_ms"]
         return usage
 
+    # ------------------------------------------------------------------
+    # codex argv builder + output parser (Phase 1b)
+    # ------------------------------------------------------------------
+
+    def _build_codex_argv(self, workdir: str, prompt_file: str | None = None) -> list[str]:
+        """Assemble the ``codex exec`` argv (design §5.1.5 / §5.4, verified
+        against codex-cli 0.144.1 — see ``_codex/facts-codex.md``).
+
+        Shape::
+
+            codex exec --json --skip-git-repo-check --ephemeral
+                       -m <model> -C <workdir> -s <read-only|workspace-write> -
+
+        The prompt is fed on stdin (not argv), so it never appears here and
+        ``prompt_file`` is ignored (it exists only to keep the builder
+        signature uniform across agents) — the trailing ``-`` makes the
+        stdin intent explicit to ``codex exec``, which otherwise treats a
+        bare invocation with no PROMPT arg the same way but reads more
+        ambiguously in a fixed argv list. ``--skip-git-repo-check`` is
+        ALWAYS passed because the isolated workdir is not a git repository
+        (without it the CLI exits 1). ``--ephemeral`` is ALWAYS passed so no
+        session state persists to disk, matching the adapter's stateless
+        one-shot ethos (the same rationale as grok's ``--no-memory``). codex
+        has no ``--max-turns`` equivalent, so ``AgentCliConfig.max_turns`` is
+        silently ignored here (documented in the schema).
+        """
+        del prompt_file  # codex takes the prompt on stdin, not from a file.
+        model = self.acfg.model or self.config.model
+        argv = [
+            self.acfg.command,
+            "exec",
+            "--json",
+            "--skip-git-repo-check",
+            "--ephemeral",
+            "-m",
+            model,
+            "-C",
+            workdir,
+        ]
+        argv += self._codex_sandbox_args()
+        argv += ["-"]
+        return argv
+
+    def _codex_sandbox_args(self) -> list[str]:
+        """Map ``sandbox_mode`` → codex ``-s/--sandbox`` flags, clamped.
+
+        Same clamp as claude/grok (design §5.4): when ``allow_file_writes``
+        is False the effective mode is forced to ``read_only`` regardless of
+        ``sandbox_mode``, so writes always require the explicit opt-in.
+        ``codex exec`` has no approval flag in 0.144.1 (non-interactive, so
+        there is nothing to approve), so ``full_auto`` maps onto the same
+        ``workspace-write`` value as ``edit`` —
+        ``--dangerously-bypass-approvals-and-sandbox`` is never used.
+        """
+        mode = self.acfg.sandbox_mode if self.acfg.allow_file_writes else "read_only"
+        return list(_CODEX_SANDBOX_ARGS[mode])
+
+    def _parse_codex(
+        self, stdout: bytes, stderr: bytes
+    ) -> tuple[str, dict[str, Any], dict[str, Any]]:
+        """Parse codex ``exec --json`` JSONL output (verified codex-cli
+        0.144.1, ``_codex/facts-codex.md``).
+
+        Real-run shape (one JSON object per line, newline-delimited)::
+
+            {"type":"thread.started","thread_id":"<uuid>"}
+            {"type":"turn.started"}
+            {"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"2"}}
+            {"type":"turn.completed","usage":{"input_tokens":13810,"cached_input_tokens":9984,"output_tokens":5,"reasoning_output_tokens":0}}
+
+        The CLI is pre-1.0 and its JSON schema is not frozen, so parsing is
+        deliberately defensive at every level: individual lines that fail to
+        parse (or parse to something other than a JSON object) are SKIPPED
+        rather than aborting the whole parse — stray non-JSON noise on
+        stdout should not sink an otherwise-valid answer. The final answer
+        is the LAST ``item.completed`` event whose ``item`` is an
+        ``agent_message`` with a string ``text``. If a completed answer was
+        found, it is returned even when a later ``error`` / ``turn.failed``
+        event also appears (a completed answer beats a trailing error); if
+        no answer was found, an ``error`` / ``turn.failed`` event (or the
+        total absence of any agent_message) raises a retryable
+        :class:`AdapterError`.
+        """
+        text = stdout.decode("utf-8", "replace")
+        if not text.strip():
+            raise AdapterError(
+                "codex produced no stdout to parse",
+                provider=self.name,
+                retryable=True,
+            )
+
+        final_text: str | None = None
+        thread_id: str | None = None
+        failure_event: dict[str, Any] | None = None
+        prompt_tokens = 0
+        completion_tokens = 0
+        cached_tokens = 0
+        reasoning_tokens = 0
+
+        for line in text.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                # Defensive against stray non-JSON noise (progress text that
+                # leaked onto stdout, partial writes, etc.) — skip the line.
+                continue
+            if not isinstance(event, dict):
+                continue
+
+            etype = event.get("type")
+            if etype == "thread.started":
+                tid = event.get("thread_id")
+                if isinstance(tid, str):
+                    thread_id = tid
+            elif etype == "item.completed":
+                item = event.get("item")
+                if (
+                    isinstance(item, dict)
+                    and item.get("type") == "agent_message"
+                    and isinstance(item.get("text"), str)
+                ):
+                    final_text = item["text"]
+            elif etype == "turn.completed":
+                usage = event.get("usage")
+                usage = usage if isinstance(usage, dict) else {}
+
+                def _int(key: str, _usage: dict[str, Any] = usage) -> int:
+                    value = _usage.get(key)
+                    return int(value) if isinstance(value, (int, float)) else 0
+
+                prompt_tokens += _int("input_tokens")
+                completion_tokens += _int("output_tokens")
+                cached_tokens += _int("cached_input_tokens")
+                reasoning_tokens += _int("reasoning_output_tokens")
+            elif etype in ("error", "turn.failed"):
+                failure_event = event
+
+        if final_text is None:
+            if failure_event is not None:
+                raise AdapterError(
+                    f"codex reported {failure_event.get('type')}: {failure_event!r}"[:500],
+                    provider=self.name,
+                    retryable=True,
+                )
+            raise AdapterError(
+                "codex JSONL output contained no agent_message",
+                provider=self.name,
+                retryable=True,
+            )
+
+        # cached_input_tokens is a SUBSET of input_tokens (not additive) —
+        # verified sample: input 13810 ⊇ cached 9984 — so it is preserved
+        # under prompt_tokens_details rather than folded into prompt_tokens
+        # (this differs from claude's normalization, design §5.1.6).
+        usage_out: dict[str, Any] = {
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+            "total_tokens": prompt_tokens + completion_tokens,
+        }
+        if cached_tokens > 0:
+            usage_out["prompt_tokens_details"] = {"cached_tokens": cached_tokens}
+        if reasoning_tokens > 0:
+            usage_out["completion_tokens_details"] = {"reasoning_tokens": reasoning_tokens}
+
+        meta: dict[str, Any] = {}
+        if thread_id is not None:
+            meta["coderouter_session_id"] = thread_id
+        return final_text, usage_out, meta
+
     # ------------------------------------------------------------------
     # grok argv builder + output parser (Phase 1d)
     # ------------------------------------------------------------------

{coderouter_cli-2.7.8 → coderouter_cli-2.7.9}/coderouter/config/schemas.py

@@ -171,10 +171,10 @@ class AgentCliConfig(BaseModel):
     invokes an external coding-agent CLI (codex / gemini / grok / claude)
     in a single one-shot ``exec`` and returns the final answer as one
     ``prompt in → text out`` transformation. ``claude`` (Claude Code CLI,
-    Phase 1a) and ``grok`` (grok CLI, Phase 1d) are implemented;
-    codex / gemini are declared at the schema level so configs are
-    forward-compatible, but the adapter rejects them until their phase
-    lands.
+    Phase 1a), ``codex`` (codex CLI, Phase 1b) and ``grok`` (grok CLI,
+    Phase 1d) are implemented; ``gemini`` is declared at the schema level
+    so configs are forward-compatible, but the adapter rejects it until its
+    phase (1c) lands.
 
     Auth note (grok): the grok CLI uses OAuth credentials stored under
     ``~/.grok`` (``grok login``), which the adapter's HOME inheritance
@@ -182,6 +182,14 @@ class AgentCliConfig(BaseModel):
     ``GROK_CODE_XAI_API_KEY`` in ``passthrough_env`` (this is grok's key
     env var — NOT ``XAI_API_KEY``).
 
+    Auth note (codex): the codex CLI uses a ChatGPT-plan OAuth login stored
+    under ``~/.codex`` (``codex login``), which the adapter's HOME
+    inheritance already covers — the credentials go stale after roughly 8
+    days and are auto-refreshed on use, so no extra config is needed for
+    interactive/subscription setups. For CI / API-key setups, list
+    ``CODEX_API_KEY`` (exec-only) or ``OPENAI_API_KEY`` (general) in
+    ``passthrough_env``.
+
     Follows the ``extra="forbid"`` convention used across this module so a
     typo'd key fails at config-load rather than being silently ignored.
     """
@@ -191,8 +199,9 @@ class AgentCliConfig(BaseModel):
     agent: Literal["codex", "gemini", "grok", "claude"] = Field(
         ...,
         description=(
-            "External coding-agent CLI to invoke. 'claude' (Phase 1a) and "
-            "'grok' (Phase 1d) are implemented; 'codex' / 'gemini' pending."
+            "External coding-agent CLI to invoke. 'claude' (Phase 1a), "
+            "'codex' (Phase 1b) and 'grok' (Phase 1d) are implemented; "
+            "'gemini' (Phase 1c) pending."
         ),
     )
     command: str | None = Field(

{coderouter_cli-2.7.8 → coderouter_cli-2.7.9}/docs/backends/external-agents.en.md

@@ -2,7 +2,7 @@
 
 > 日本語版: [`external-agents.md`](./external-agents.md)
 
-`kind: "agent_cli"` is an adapter that registers an external coding-agent CLI, such as the Claude Code CLI, as a single CodeRouter provider. It was newly added in v2.7.7 (Phase 1a: claude), and v2.7.8 added grok (Phase 1d). See [`docs/designs/external-agents-adapter.md`](../designs/external-agents-adapter.md) for the full design.
+`kind: "agent_cli"` is an adapter that registers an external coding-agent CLI, such as the Claude Code CLI, as a single CodeRouter provider. It was newly added in v2.7.7 (Phase 1a: claude), v2.7.8 added grok (Phase 1d), and v2.7.9 added codex (Phase 1b). See [`docs/designs/external-agents-adapter.md`](../designs/external-agents-adapter.md) for the full design.
 
 ---
 
@@ -11,16 +11,16 @@
 A coding-agent CLI is normally a stateful control loop that runs many turns autonomously while editing files — a poor fit for CodeRouter's "one request = one transformation" ethos. `agent_cli` reconciles the two by collapsing the CLI into a **one-shot `exec`** (prompt in → final answer text out). Orchestration (multi-turn control, tool execution) stays entirely inside the agent CLI process; from CodeRouter's side it looks like just another provider that answers a single exchange.
 
 - **Supported CLIs**: the `agent` field can declare `claude` / `codex` / `gemini` / `grok`.
-- **Implementation status (as of v2.7.8)**: **`claude` (Claude Code CLI, Phase 1a) and `grok` (Grok CLI, Phase 1d) are implemented**. `codex` / `gemini` can be written into `providers.yaml` at the schema level, but constructing the adapter always rejects them (Phase 1b/1c are not yet implemented). The error message looks roughly like the following (the exact wording may differ between versions):
+- **Implementation status (as of v2.7.9)**: **`claude` (Claude Code CLI, Phase 1a), `codex` (OpenAI Codex CLI, Phase 1b), and `grok` (Grok CLI, Phase 1d) are implemented**. Only `gemini` can be written into `providers.yaml` at the schema level, but constructing the adapter always rejects it (Phase 1c is not yet implemented). The error message looks roughly like the following (the exact wording may differ between versions):
 
   ```
-  AdapterError: agent 'codex' is not implemented yet (implemented: claude, grok).
-  Wait for the agent's phase (1b/1c).
+  AdapterError: agent 'gemini' is not implemented yet (implemented: claude, codex, grok).
+  Wait for the agent's phase (1c).
   ```
 
   This rejection is `retryable=False` — even if other providers exist in the fallback chain, it stops immediately as a configuration error.
 
-- The shared parts of this document (authentication design, configuration reference, limitations) are written against the `claude` target; grok-specific behavior is collected in the [grok (Grok CLI)](#grok-grok-cli) section. Example configs for `codex` / `gemini` exist only as a commented-out preview at the bottom of `examples/providers-agent-cli.yaml` and do not work.
+- The shared parts of this document (authentication design, configuration reference, limitations) are written against the `claude` target; codex- and grok-specific behavior are collected in the [codex (OpenAI Codex CLI)](#codex-openai-codex-cli) and [grok (Grok CLI)](#grok-grok-cli) sections, respectively. Example configs for `gemini` exist only as a commented-out preview at the bottom of `examples/providers-agent-cli.yaml` and do not work.
 
 ---
 
@@ -96,14 +96,14 @@ All fields of the `agent_cli:` sub-config (`AgentCliConfig`) in `providers.yaml`
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `agent` | `"claude" \| "codex" \| "gemini" \| "grok"` | (required) | Which CLI to invoke. **As of v2.7.8, `claude` and `grok` are implemented; `codex` / `gemini` are rejected when the adapter is constructed** |
+| `agent` | `"claude" \| "codex" \| "gemini" \| "grok"` | (required) | Which CLI to invoke. **As of v2.7.9, `claude`, `codex`, and `grok` are implemented; `gemini` is rejected when the adapter is constructed** |
 | `command` | `str \| null` | `null` (defaults to the same name as `agent`) | CLI executable name or absolute path, resolved via `PATH` |
 | `workdir` | `str \| null` | `null` (defaults to `~/.coderouter/agents/<provider name>`) | Working directory for the one-shot exec. `~` / env-var expansion is applied; a path containing `..` is rejected |
 | `exec_timeout_s` | `float` | `600.0` (range `1.0`–`1800.0`) | Forced timeout (seconds) for the whole exec. **Separate** from `ProviderConfig.timeout_s` (the latter is not used by agent_cli) |
 | `allow_file_writes` | `bool` | `false` | Whether to allow file writes. When `false`, the effective mode is clamped to read-only regardless of `sandbox_mode` |
-| `sandbox_mode` | `"read_only" \| "edit" \| "full_auto"` | `"read_only"` | Maps to each CLI's sandbox/approval flags (claude: [table below](#sandbox_mode--permission-mode-mapping-claude); grok: [grok section](#sandbox_mode--grok-flag-mapping)) |
-| `model` | `str \| null` | `null` (defaults to `ProviderConfig.model`) | Model name passed to the CLI's `--model` / `-m` (claude: `opus` / `sonnet` / `haiku` / `fable` etc.; grok: `grok-4.5` etc.) |
-| `max_turns` | `int \| null` | `8` (range `1`–`50`) | Turn cap inside the CLI. Passed as `--max-turns` |
+| `sandbox_mode` | `"read_only" \| "edit" \| "full_auto"` | `"read_only"` | Maps to each CLI's sandbox/approval flags (claude: [table below](#sandbox_mode--permission-mode-mapping-claude); codex: [codex section](#sandbox_mode--codex-flag-mapping); grok: [grok section](#sandbox_mode--grok-flag-mapping)) |
+| `model` | `str \| null` | `null` (defaults to `ProviderConfig.model`) | Model name passed to the CLI's `--model` / `-m` (claude: `opus` / `sonnet` / `haiku` / `fable` etc.; codex: `gpt-5.5` etc.; grok: `grok-4.5` etc.) |
+| `max_turns` | `int \| null` | `8` (range `1`–`50`) | Turn cap inside the CLI. Passed as `--max-turns`. **codex has no corresponding CLI flag, so this is always ignored** (for codex, `exec_timeout_s` + process-group kill is the only time bound) |
 | `passthrough_env` | `list[str]` | `[]` | Allowlist of environment variable names forwarded from the parent process into the child. `ANTHROPIC_API_KEY` is not forwarded unless listed here |
 | `agent_depth_limit` | `int` | `2` (range `1`–`4`) | Recursion nesting cap. When `CODEROUTER_AGENT_DEPTH` reaches or exceeds this, the call stops immediately with `AdapterError(retryable=False)` |
 
@@ -123,6 +123,104 @@ The `agent-claude` provider in the example config `examples/providers-agent-cli.
 
 ---
 
+## codex (OpenAI Codex CLI)
+
+v2.7.9 (Phase 1b) implements `agent: codex`. Like claude, it delivers the prompt via **stdin** (unlike grok's file-based delivery). It has its own behavior around JSONL output, `--ephemeral`, and running outside a git repository. Everything below is based on codex CLI **0.144.1** (field-verified on the author's Mac, 2026-07-11).
+
+### Example configuration
+
+```yaml
+providers:
+  - name: agent-codex
+    kind: agent_cli
+    model: gpt-5.5                # a current frontier-model example; the default depends on the environment/plan, so set it explicitly
+    paid: false                   # ChatGPT-plan subscription OAuth = zero metered cost
+    capabilities:
+      streaming: false
+      tools: false
+    agent_cli:
+      agent: codex
+      command: codex
+      workdir: ~/.coderouter/agents/codex
+      exec_timeout_s: 600
+      allow_file_writes: false
+      sandbox_mode: read_only
+      max_turns: 8                 # ignored by codex — no corresponding flag (see below)
+      passthrough_env: []          # OAuth reads ~/.codex/auth.json via the inherited HOME, so empty is fine.
+                                    # Only list CODEX_API_KEY (exec-only) or OPENAI_API_KEY
+                                    # when using an API key in CI
+```
+
+### The argv the adapter builds
+
+With `sandbox_mode: read_only` (the default), the adapter builds the following argv.
+
+```
+codex exec --json --skip-git-repo-check --ephemeral -m <model> -C <workdir> -s read-only -
+```
+
+### The prompt is delivered via stdin (same as claude, unlike grok)
+
+codex's `exec` subcommand reads the prompt from stdin when the PROMPT argument is omitted (or explicitly given as `-`). The adapter places an explicit trailing `-` on the argv to force this path. Unlike grok, there's no need for a temp file (`--prompt-file`) inside the isolated workdir — this is the same stdin scheme as claude.
+
+### Why `--skip-git-repo-check` is always passed
+
+CodeRouter's isolated workdir is not a git repository. By default, codex runs a "trusted directory" check and, outside a git repo in an unrecognized directory, fails immediately with exit 1 and stderr `Not inside a trusted directory and --skip-git-repo-check was not specified.` (field-verified). The adapter always passes this flag, so this error message should never appear in normal operation.
+
+### Why `--ephemeral` is always passed
+
+`--ephemeral` prevents the session from being persisted to disk. For the same reason as grok's `--no-memory` — keeping with CodeRouter's "one request = one stateless transformation" ethos — the adapter always passes this flag (it cannot be turned off in config).
+
+### `sandbox_mode` → codex flag mapping
+
+As with claude/grok, when `allow_file_writes=false` the effective mode is clamped to `read_only` regardless of `sandbox_mode`.
+
+| `sandbox_mode` | codex flags | Notes |
+|---|---|---|
+| `read_only` (default) | `-s read-only` | No file changes. Always clamped to this mode when `allow_file_writes=false` |
+| `edit` | `-s workspace-write` | Permits file edits inside the workspace-write sandbox |
+| `full_auto` | `-s workspace-write` | **`codex exec` has no approval flag (`-a` / `--ask-for-approval`)** — it's absent from `exec --help` in 0.144.1, since non-interactive execution has no approval prompt to control in the first place. So this maps identically to `edit`. `--dangerously-bypass-approvals-and-sandbox` is never used |
+
+### No `--max-turns` / `--timeout` exist
+
+codex exec has neither `--max-turns` nor `--timeout`. Consequently `AgentCliConfig.max_turns` is **ignored for codex**. The only time bound is the existing `exec_timeout_s` + process-group `SIGKILL`.
+
+### JSONL output and usage normalization
+
+`--json` output is JSONL (one event per line); progress goes to stderr, and the event stream (including the final answer) goes to stdout (confirmed by both the official docs and the real CLI). A verified one-shot run:
+
+```
+$ codex exec --json --skip-git-repo-check "What's 1+1? Answer with just the digit"
+{"type":"thread.started","thread_id":"019f4e74-08fd-77b2-9cc6-9afa744df130"}
+{"type":"turn.started"}
+{"type":"item.completed","item":{"id":"item_0","type":"agent_message","text":"2"}}
+{"type":"turn.completed","usage":{"input_tokens":13810,"cached_input_tokens":9984,"output_tokens":5,"reasoning_output_tokens":0}}
+```
+
+- Final answer: the **last** `item.completed` whose `item.type=="agent_message"`, taking `item.text`.
+- Usage normalization: `turn.completed.usage`'s `input_tokens` → `prompt_tokens`, `output_tokens` → `completion_tokens`, and their sum → `total_tokens`. `cached_input_tokens` is a **subset** of `input_tokens` (measured: input 13810 ⊃ cached 9984), so it is not added on top — it's kept as `prompt_tokens_details.cached_tokens`. When `reasoning_output_tokens` is greater than 0, it's kept as `completion_tokens_details.reasoning_tokens` (defensive). Multiple `turn.completed` events, if they occur, are summed.
+- `thread_id` (from `thread.started`) is surfaced as the `coderouter_session_id` response metadata.
+- If an `error` event or `turn.failed` is seen, or no agent_message is ever produced / stdout is empty / every line is non-JSON, this raises a retryable `AdapterError` and the fallback chain advances to the next provider. Individual non-JSON lines in the JSONL stream don't stop processing of the remaining lines (defense against stray stderr-like output mixed in).
+
+### Authentication (ChatGPT-plan subscription OAuth / API key)
+
+The codex CLI supports ChatGPT-plan OAuth login. Credentials are stored at `~/.codex/auth.json` (or the OS keyring), and the adapter's `HOME` inheritance makes it work with `passthrough_env: []`.
+
+1. Run `codex login` to complete login. `codex login status` exiting 0 confirms you're logged in.
+2. The OAuth token goes **stale after about 8 days**. It auto-refreshes on use, but a setup that doesn't call codex for a long stretch can fail while stale — running codex occasionally, or re-logging in, is recommended.
+
+For CI or metered API-key billing, list `CODEX_API_KEY` (**exec-only**) or `OPENAI_API_KEY` (general) in `passthrough_env`. `CODEX_HOME` can also override the config/credentials directory itself.
+
+### Error reporting
+
+The codex CLI exits 0 on success, and on failure exits non-zero with the error text on stderr (e.g. the git-repo-check message). JSONL may also carry an `error` event or `turn.failed`; both of those also become a retryable `AdapterError` and the fallback chain advances to the next provider.
+
+### Pre-1.0 caveat
+
+The codex CLI is pre-1.0 and releases nearly daily. `--json`'s alias is still `--experimental-json`, and the JSONL schema is not frozen. **Version pinning is recommended** (you can point `command` at a pinned binary's full path). If the schema does change, defensive parsing turns it into a retryable `AdapterError` and the fallback chain demotes to the next provider.
+
+---
+
 ## grok (Grok CLI)
 
 v2.7.8 (Phase 1d) implements `agent: grok`. It uses the same one-shot exec scheme as claude, but grok has its own behavior around prompt delivery, cross-session memory disabling, and usage reporting. Everything below is based on grok CLI **v0.2.93** ([stable] channel, field-verified on 2026-07-10).
@@ -222,7 +320,9 @@ The grok CLI is early beta (v0.2.93 [stable] channel as of 2026-07-10). Its JSON
 | Requests are rejected / not routed, effectively "paid gate blocked" | The `agent_cli` provider has `paid: true` but `ALLOW_PAID` isn't set | For subscription usage, set `paid: false`. For metered API-key billing, set `ALLOW_PAID=true` when starting CodeRouter |
 | `claude exited 1: ...` shows a specific reason | The claude CLI sometimes reports auth/API errors as an `is_error: true` JSON document on **stdout** (with stderr left empty) and exits with code 1 | v2.7.7's `_error_detail()` now prefers the `result` field of that stdout `is_error` JSON (the actual error text, e.g. `Not logged in · Please run /login`) even when stderr is empty, and includes it in the raised error message — use the message shown as your lead |
 | Fails with `grok exited 1: ...` | The grok CLI exits with code 1 on auth/network/runtime errors, with the error text on stderr | The adapter includes a tail of stderr in the `AdapterError`, so use the message shown as your lead. For auth errors, re-run `grok login` and smoke-check that `grok models` works |
-| CLI fails to launch (`failed to launch ...`) | `command` (defaults to the same name as `agent`) isn't on `PATH` | Confirm `claude --version` / `grok --version` works. You can also point `command` at a full path |
+| Fails with `codex exited 1: ...` (suspect stale OAuth) | codex's OAuth token goes stale after about 8 days. It auto-refreshes on use, but a long gap between calls can leave it stale and failing | Check login state with `codex login status` and re-run `codex login` if needed. Running codex occasionally helps avoid staleness |
+| `Not inside a trusted directory and --skip-git-repo-check was not specified.` appears | This should never happen — the adapter always passes `--skip-git-repo-check` | If you see this, it likely indicates a bug in CodeRouter's argv construction. Check your version and file an issue if it reproduces |
+| CLI fails to launch (`failed to launch ...`) | `command` (defaults to the same name as `agent`) isn't on `PATH` | Confirm `claude --version` / `codex --version` / `grok --version` works. You can also point `command` at a full path |
 
 ---