Official
codex
Codex agent provider: runs the Codex CLI's app-server for each account.
The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install divergence/codex@0.2.4
Permissions in 0.2.4
Files
NOTES.md37.5 KB
# Codex provider plugin — decisions and protocol notes
The backend is `codex app-server` over stdio JSON-RPC. These mappings were checked against the generated Codex 0.169.0 schema and its release notes on 2026-11-14. The original streaming probes used 0.155.1, and admission and recovery probes used 0.160.0. The 0.169.0 additions are verified with schema-shaped scripted peers and unit tests rather than a live model turn.
## Layout
The plugin is sandboxed TypeScript (`"main": "main.ts"`), with scoped Effect handlers. It reaches the CLI only through the broker (`api.process`), and speaks JSON-RPC to it with the provider SDK (`../sdk/`, see `plugins/docs/agent-protocol.md`). It replaced a Rust program, deleted with the other native providers; what that program kept is read once from `legacy/` (`legacy.ts`).
| File | Role |
| -------------- | -------------------------------------------------------------------------------------------- |
| `main.ts` | `activate`: one agent per configured account |
| `instances.ts` | the accounts (plugin storage key `instances`) |
| `legacy.ts` | the Rust plugin's `instances.json`, read once into storage |
| `map.ts` | pure item-to-protocol mapping, and the thread helpers of the v2 schema (all unit-tested) |
| `params.ts` | options, `thread/start` / `resume` / `fork` / `turn/start` params, the prompt as `UserInput` |
| `requests.ts` | the app-server's requests as approval cards and questions, and the replies Codex expects |
| `items.ts` | Maps standalone function outputs, clock sleeps, hook prompts and review markers. |
| `catalog.ts` | Discovers configured providers and keeps their model catalogs separate. |
| `auth.ts` | Handles ChatGPT and targeted gateway authorization. |
| `mcp.ts` | Maps captured MCP Apps and routes app resource reads and tool calls through Codex. |
| `quota.ts` | Merges sparse usage display snapshots by quota bucket. |
| `agent.ts` | connection, session and run state, every agent method |
| `icon.ts` | `icon.svg` as a string (the runtime strips TypeScript and imports JSON) |
| `*.test.ts` | `node --test`; `agent.test.ts` drives the agent against a scripted app-server |
## Connection
One app-server process per account, started lazily on first use and restarted transparently if it died (`CodexAgent.client`; concurrent first calls share one start). The broker finds `codex` on the login PATH (`process: ["codex"]`); a path in `CODEX_PATH` is not honoured any more, since a path needs `process.any`. Handshake is `initialize` with `clientInfo { name: "divergence" }` and `capabilities { experimentalApi: true, requestAttestation: false, requiredHumanApproval: true, explicitGatewayOauth: true }`, then the `initialized` notification.
`experimentalApi` is on because `item/tool/requestUserInput` (the question surface) and the `plan` item type are gated behind it. `requestAttestation` is off, so `attestation/generate` never arrives. `requiredHumanApproval` enables human-command requests with one-time decisions. `explicitGatewayOauth` keeps gateway browser authorization behind the user's sign-in action.
## Sessions
A Divergence session id **is** a Codex thread id.
- `create_session` → `thread/start { cwd, model?, approvalPolicy?, sandbox? }`
- `resume_session` → `thread/resume { threadId, cwd, excludeTurns: true, … }` (`excludeTurns` keeps the resume cheap; history comes from `read_session`)
- `list_sessions` → `thread/list { cwd: <workspace>, limit: 100 }`, following `nextCursor` until every thread of the workspace is listed. The first listing also watches `<home>/sessions` for rollout files of threads the app-server never mentioned (started in the Codex app or CLI) and reports each one's folder once with `sessions_changed`; the manifest's `fs.read` scopes allow it: `~/.codex/sessions` and `~/.codex*/sessions` for the folder itself, which is what is watched (a `/**` scope covers only what is under a folder), and the same with `/**` for the files in it.
**`cwd` is mandatory in practice**: without it the app-server returns the threads of every workspace.
- A fresh thread may report `thread <id> is not materialized yet; thread/turns/list is unavailable before first user message` with code `-32600`. That response means empty history, so the provider skips the legacy full-history read. A live 0.169.0 probe on 2026-11-15 confirmed that both `thread/read { includeTurns: true }` and `thread/resume` reject that fresh thread with `list_turns is not supported yet`. The host keeps using its already attached session for the first Send.
- `read_session` → `thread/read`, then the turns from `thread/turns/list` (newest page first, so a thread over 2000 turns keeps its latest ones and starts with a notice that the older ones are not shown; `thread/read { includeTurns: true }` only for a legacy thread), mapped turn by turn into `TranscriptItem`s. The derived title (thread `name`, else `preview`, else the first user message, trimmed to one line) is pushed as a `SessionInfo` event because `read_session` itself only returns items.
- `close_session` → `thread/unsubscribe`, best effort.
## Runs
Legacy `prompt` returns a run id immediately and `turn/start` is awaited in the background (no timeout, since a turn has no useful timeout). A prompt carrying `delivery` awaits native admission and returns an input receipt as well. The run ends on `turn/completed` — `completed`/`interrupted`/`failed` map to `Completed`/`Cancelled`/`Failed{turn.error.message}`. `finishRun` takes the run out of the session state, so a second signal for the same run is a no-op and **exactly one `RunFinished` is emitted**. The paths that end a run are: `turn/completed`, a failed `turn/start` request, `cancel`, and the app-server exiting (the pump fails every live run when its stdout closes). `error`, even with `willRetry: false`, is a notice, not a terminal turn signal.
**Stop:** `cancel` ends the run at once and sends the interrupts behind it: each subagent's live turn, bounded, then the chat's own `turn/interrupt`. A Stop that comes before Codex names the turn (the `turn/start` reply or `turn/started`, whichever comes first) is remembered on the session (`stopping`), and that turn is fenced and interrupted as soon as it is named, so it neither reopens the chat nor runs on unseen. The thread is let go (`releaseIdle`) only after Codex has answered the interrupt.
Notifications route by `threadId`, with known retired native turn IDs fenced. A completion for a different live turn cannot finish it. A differing ID alone does not suppress child activity or a real `turn/started`. Autonomous turns in known sessions emit `run_started` with a fresh run ID; child turns never finish the parent run. Late start replies cannot retarget a successor.
**Steering:** a `prompt` sent while a run is active becomes `turn/steer { expectedTurnId }` and returns the _existing_ run id, so the two prompts share one run and one `RunFinished`. `capabilities.steer` is true for this reason. While `turn/start` is in flight, steers wait for its native identity rather than issuing another start. Native validation/precondition errors (`-32600`, `-32601`, `-32602`) emit correlated `input_rejected`; a lost write/reply, internal error or malformed response is uncertain, never auto-retried. The host owns explicit queues; passing `delivery.intent: "queue"` is rejected.
`delivery.attemptId` is sent as `clientUserMessageId` on both start and steer. The native reply is admission, not consumption. A matching `userMessage.clientId` on `item/started` or `item/completed` emits `input_consumed` once, tagged with the original run even if it arrives late. Correlation is process-local: a plugin restart loses that lookup, so unknown input must remain held rather than replayed. No per-input native edit, withdrawal or amendment capability is advertised.
## Event mapping
| Codex | Divergence |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `item/agentMessage/delta` | `TextDelta` (append, `item_id` = `itemId`) |
| `item/reasoning/textDelta`, `…/summaryTextDelta` | `ReasoningDelta` (append) |
| `item/completed` `agentMessage` / `reasoning` | `TextDelta`/`ReasoningDelta` **Replace**, only when no delta streamed for that item |
| `item/started` / `item/completed` tool items | `ToolCallStarted` once, then `ToolCallUpdated` |
| `item/commandExecution/outputDelta`, `item/fileChange/outputDelta` | `ToolCallUpdated { output_delta }` |
| `item/fileChange/patchUpdated` | `ToolCallUpdated { content: Diff[] }` |
| `turn/plan/updated` | `Plan` |
| `thread/tokenUsage/updated` | `Usage` |
| `thread/name/updated` | `SessionInfo { title }` |
| `error`, `warning` | `Notice` (error / warning); an `error` Codex retries (`willRetry: true`) is a warning |
| `deprecationNotice`, `configWarning`, `windows/worldWritableWarning` | `Notice` (warning) from `summary` and `details` (the folders, for Windows), each text once per run: every app-server sends them again as it starts |
| `guardianWarning` | Successful automatic approvals stay quiet; denials and review failures become warning notices. |
| `model/rerouted` | `Notice` (info), naming both models |
| `item/reasoning/summaryPartAdded` | a blank line, so summary parts do not run together |
| `item/mcpToolCall/progress` | `ToolCallUpdated { output_delta }` |
| `contextCompaction` item | `Compacted` |
| `collabAgentToolCall` spawn, `subAgentActivity` started, `thread/started` (spawned) | `Task`, plus the child thread's own events tagged with `task_id` |
| `account/rateLimits/updated` | `UsageLimits` |
| `functionCallOutput` | Tool rows retain the native tool name, namespace, text and inline image content, live and in history. |
| `sleep` | A `clock.sleep` tool row runs until the completed item and records `durationMs`. |
| `hookPrompt`, `enteredReviewMode`, `exitedReviewMode` | Notices retain hook fragments and review text, live and in history. |
| `serverRequest/resolved` | `ApprovalResolved` / `QuestionResolved` |
Deltas are forwarded byte for byte; whitespace-only chunks are kept (the live probe streamed `"P"`, `"ONG"`, `" "` as separate deltas). One exception: reasoning whose whole text is `codex exec`'s "Reading additional input from stdin..." is not reasoning and is left out, live (the first text of an item is held while it could still be only that) and in history.
Tool kinds come from Codex's structured `commandActions`, never from the command string: all-`read` → `Read`; all read/`listFiles`/`search` → `Search`; anything else, or no actions at all → `Execute`. `fileChange` → `Edit` with one `ToolContent::Diff` per change carrying the unified `diff` only (Codex never sends whole-file snapshots). `mcpToolCall` and `dynamicToolCall` → `Other`, `webSearch` → `Fetch`, `imageView` → `Read`.
## Approvals and questions
Command and file approvals share the four base decisions `accept`, `acceptForSession`, `decline` and `cancel`. Command approvals also expose only the execpolicy and network amendments supplied by Codex, with the native structured decision returned unchanged. File approvals keep their four decisions. `humanCommand` offers only `accept`, `decline` and `cancel`, and rejects a forged persistent choice. `writeStdin` is presented as input to an existing terminal. Managed network requests show the protocol and destination even when Codex supplies no command. Each request keeps its own choices and reply closure, including requests that share an item ID. Stop answers pending requests with `cancel`, and native resolution withdraws them without sending another reply.
`item/tool/requestUserInput` becomes a `Question` with one `QuestionField` per Codex question, `Select` when it carries options and `Text` otherwise, `allowOther` from `isOther`, and `secret: true` when `isSecret` is true. The host masks secret text answers and excludes them from saved draft answers. The reply is rebuilt as `{ answers: { <questionId>: { answers: [...] } } }`.
`mcpServer/elicitation/request` has three shapes. With `_meta.codex_approval_kind: "mcp_tool_call"` (Computer Use and other MCP tools) it is an `Approval`: `accept` (Allow once), `acceptForSession` when `_meta.persist` is or holds `"session"`, `acceptAlways` when it holds `"always"`, and `cancel`. The reply is `{ action: "accept", content: {}, _meta: null | { persist: "session" | "always" } }`, or `cancel`/`decline` with `content: null`. Mode `url` is a `Question` with `url` and no fields (HTTP(S) only; anything else is cancelled with an error notice), answered `accept` or `cancel`. Modes `form`, `openai/form` and `openaiForm` are a `Question` with one field per `requestedSchema` property (`boolean` → Boolean, `array` → MultiSelect, `oneOf`/`enum` → Select with the titles, anything else → Text; `required`, `title`, `description` carried over), answered with typed content: `integer`/`number` inputs go back as JSON numbers. Any other mode is refused with method-not-found.
Any other server request (`item/permissions/requestApproval`, `account/chatgptAuthTokens/refresh`) is answered with a JSON-RPC method-not-found error so the app-server never waits on us. A request this plugin cannot read or handle (a known method with a field it does not understand) is refused with an error too, and its chat gets a warning notice that names the method, so an approval never disappears silently.
## MCP Apps and host features
`initialize` retains the host's `hostFeatures`. Only a host listing `mcpApps` gets `capabilities.mcpApps` and `mcp_app` tool content. An older host keeps the existing tool content. The mapping prefers the invoked descriptor captured in `mcpToolCall.mcpAppUi.resourceUri`, then the schema's legacy `mcpAppResourceUri`, then `appContext.resourceUri`, and accepts only `ui://` resources. The block names the native server and tool, precedes the existing fallback content, and carries the native result when available. Live starts, completions, late completions and history, including nested subagents, use the same mapping. History versions include the mapping revision and the negotiated app feature so a previous text-only read is refreshed.
`mcp_read_resource` uses `mcpServer/resource/read { threadId, server, uri, originCallId? }`, passing `toolCallId` as `originCallId`. `mcp_call_tool` first pages `mcpServerStatus/list { threadId, serverName, cursor }` and refuses a tool whose reported `_meta.ui.visibility` omits `app`, including an empty list. Missing visibility uses the extension's default. Discovery errors propagate. It then calls `mcpServer/tool/call { threadId, server, tool, arguments }`, leaving native approvals and errors to Codex. That request has no `originCallId` field. Both methods use `loadedConnection`, which starts the shared app-server and resumes a previously unloaded thread as prompts do, and preserve native result fields and resource metadata.
The 0.169.0 `McpToolCallResult` captured in a thread exposes `content`, `structuredContent` and `_meta`, but no `isError`; failures have a separate `error.message`. The plugin keeps those values without manufacturing an MCP error result. The direct `McpServerToolCallResponse` also exposes `isError`, which is returned unchanged. The native plan-step status enum has only `pending`, `inProgress` and `completed`, so even a host listing `planCancelled` receives no invented cancellation status.
The runtime already forwards both MCP handlers. Its shared TypeScript `AgentMethods` declaration still needs `AgentInitializeParams`, `McpReadResourceParams` and `McpCallToolParams` entries, which are outside this plugin's scope.
## Config options
Fetched live; nothing is hardcoded except the two closed enums noted below.
- `model_provider` (Provider) comes from `modelProvider/list`. Each provider has a separate `model/list { modelProvider }` cache. Selecting a provider while idle resumes the thread with that provider and clears its old model, effort and speed overrides. Start, resume and fork capture the effective native provider, so a later default change does not relabel an existing chat. Older servers that explicitly reject discovery as method-not-found retain their own default model catalog; other discovery failures surface.
- `model` (Model) from `model/list`, paginated on `nextCursor`, hidden models dropped. Each choice carries **its own** `reasoning_levels` built from that model's `supportedReasoningEfforts` rows — no shared list.
- `reasoning` (Reasoning) — the efforts of the currently selected model. Changing the model clears the stored reasoning value.
- `permission_mode` (Approval) — the four shared modes, see below.
- `service_tier` (Speed) — the speed tiers of the chosen model, from `serviceTiers`, preceded by Standard (`default`) as in t3code. Selecting Standard explicitly resets a previous Fast selection. Absent for models that offer no additional tiers.
- Defaults come from `config/read { cwd }` (`model`, `model_provider`, `model_reasoning_effort`, `service_tier`, `approval_policy`, `sandbox_mode`), which returns **snake_case** keys unlike the rest of the v2 API.
Speed defaults use a valid chat override, then configured `service_tier`, then the selected model's default tier and finally Standard.
Chosen values are sent per turn (`model`, `effort`, `approvalPolicy`, `sandboxPolicy`, `approvalsReviewer`, `serviceTier`) as well as at `thread/start`, so changing an option mid-session takes effect on the next prompt.
## Accounts (instances)
One Codex install can hold several logins, kept apart by `CODEX_HOME`. The plugin serves one agent per account, described in its own storage under the key `instances`. The Rust plugin read `<data dir>/agents/codex/instances.json`; the first time this plugin loads in its place the host moves that folder into the plugin's data folder (`legacy/`), and `legacy.ts` adds its entries to the stored ones once (`fs.read` of the `data` scope):
```json
[{ "id": "personal", "name": "Codex Personal", "home": "~/.codex_personal", "args": [] }]
```
The default account registers in `activate`; the stored ones register once the storage answers; the runtime tells the host, which lists them. `HOME`, `CODEX_HOME` and `CODEX_ARGS` come from the login environment (`env` grant).
The default account is always served as `codex`; each entry adds `codex:<id>`. `AgentInfo.family` is `codex` for all of them and `continuation_key` is the resolved home, so the UI can offer a compatible account for an existing chat and refuse an incompatible one. Each account gets its own app-server process, model catalog and session map.
`CODEX_ARGS` adds app-server arguments for every account, split like a shell command line (the SDK's `splitArgs`, which Claude Code's launch knobs use too), and an instance's `args` adds them for one. This is how MCP servers reach Codex: the CLI takes them as `-c mcp_servers.<name>.command=…` overrides, so one mechanism covers every Codex setting instead of a flag per feature.
## Permissions
The four shared modes (`divergence_protocol::permission_mode`) replace the old separate approval-policy and sandbox selects:
| Mode | `approvalPolicy` | `sandbox` | `approvalsReviewer` |
| ----------------- | ---------------- | -------------------- | ------------------- |
| Supervised | `untrusted` | `read-only` | `user` |
| Auto-accept edits | `on-request` | `workspace-write` | `user` |
| Auto | `on-request` | `workspace-write` | `auto_review` |
| Full access | `never` | `danger-full-access` | `user` |
`approvalsReviewer` is always sent, including when it is `user`: leaving it out on resume keeps the thread's previous reviewer, so `auto_review` would stay switched on after the user moved back to a stricter mode. A chat that has not chosen a mode starts from the user's own `config/read` defaults (`modeOf`), never in a mode that allows more than they do: a `read-only` sandbox is Supervised, `never` with `danger-full-access` is Full access, `untrusted` is Supervised, any other policy (`on-request`, a `{ granular: … }` object, `never` in a sandbox) is Auto-accept edits, and a configuration that sets no approval policy starts in Auto. `approval_policy` may be an object, so the config schema accepts any value there; a string-only schema once failed the whole read for a granular policy. `turn/start` takes a structured `sandboxPolicy` that replaces the thread's, so for `workspace-write` it carries the user's `sandbox_workspace_write` (`network_access`, extra `writable_roots`, the two tmp exclusions), read with `config/read` and kept per workspace (`configs`); without it every turn switched network access off.
## Subagents
Codex runs each subagent in its own thread; the task id is that thread id. Checked against CLI 0.155.1 and real rollouts (v1 and v2 on disk), and against a live 0.169.0 app-server run kept as `testdata/subagent-v2.jsonl`. In 0.169.0 the model picks the multi-agent version, so a chat with only `[features].multi_agent` still spawns through v2 activities, and the child thread gets no `thread/started`.
**Registration (live).** A child is registered against the chat from any of:
- a v1 `collabAgentToolCall` with `tool: "spawnAgent"`: every `receiverThreadIds` entry; `prompt` (not `input`), `model`, `reasoningEffort` and the item id (`tool_call_id`) come from it;
- a v2 `subAgentActivity` with `kind: "started"` (`agentThreadId`, `agentPath`, and since 0.169.0 the child's resolved `model` and `reasoningEffort`). Other kinds address a child that exists; inside a child, `interacted` with `agentPath: "/root"` is a message to its parent;
- `thread/started` whose `source.subAgent.thread_spawn.parent_thread_id` is a chat here or a known child. Review, compaction and guardian threads and strangers' children are ignored.
A child whose parent is itself a child gets the parent's root chat as its session and `parent_task_id` = the middle child, so grandchildren reach the host at any depth. Every event of a child thread is sent to the root chat with `task_id` = the thread id (`emitFor`); the `Task` snapshot itself is untagged and placed by `parent_task_id`. A collab call or activity naming a child this process never saw (spawned before a restart) adopts it and reads its thread record for names.
**Snapshot.** Title = first line of the prompt; v2 sends the instruction encrypted (the child's `preview` is empty and its first message is an encrypted `NEW_TASK`), so a v2 title is the task name from the path (`/root/pipeline_eval_tools` → "pipeline eval tools"); last resort the nickname. `name` = `agentNickname`, else `agentRole`. `summary` = the child's latest agent message, replaced by the `agentsStates` message (the final answer) when the parent's `wait` returns it; never the title. Status: child turn started → Running, `thread/status/changed` active with flags → Waiting, child turn completed → Idle (resumable), interrupted → Cancelled, failed → Failed (error text as summary); `agentsStates` completed/shutdown → Completed, errored/notFound → Failed, interrupted → Cancelled (`pendingInit`/`running` snapshots are ignored); v2 activity completed → Completed. A Completed child is not reopened by a later Idle. Child `thread/tokenUsage/updated` reports `total.totalTokens` on the task (cumulative) and never touches the chat's meter; child plans are tagged and so ignored by the host. `tool_uses` counts the child's tool items and `activity` is the running tool's title.
**Stop.** `cancel` interrupts every live turn in the chat's subtree first (`turn/interrupt {threadId: child, turnId}`, 3 s each, in parallel, 10 s total), then the chat's own turn, and answers `cancel` to every pending approval of those threads. `cancel_task` (capability on) interrupts that child and its own children and releases their approvals; the chat's run keeps going.
**History.** `read_session` reads the thread (`thread/read` without turns, then `thread/turns/list` pages; single-page `thread/read {includeTurns}` only as a fallback), then reads every child one generation at a time (at most 64 threads). `transcriptWithSubagents` puts a `Task` item (id `task-<thread>`, as the host names a live task) at the spawn or `started` activity, filled from the parent's items (prompt, model, effort, spawn id, final `agentsStates` status and message; a v2 `started` activity gives the model and effort) and the child's record and turns (nickname, preview, turn times, last agent message as a fallback summary), with the child's own transcript inside, recursively. `wait`, `sendInput`, `closeAgent` and the other collab calls are bookkeeping and are left out. `list_sessions` drops threads with `parentThreadId` or a `thread_spawn` source.
## Rate limits
`account/rateLimits/read` runs only when the host asks (`agent/usage_limits`, at most every five minutes while nothing else reported the limits, not in `initialize`) and gives the first snapshot (with `excludeResetCreditDetails`, since the available count is enough to offer a reset) and `account/rateLimits/updated` keeps it current. Sparse pushes merge non-null display values into the latest snapshot by `limitId`, retaining reset credits, labels, durations, reset times and other buckets. Every bucket contributes its own windows. The merged display never supplies recovery permission. The `primary` and `secondary` windows are labelled from `windowDurationMins`, so "5 hours" and "Weekly" come from the data rather than from a guess. Only the window that is actually full is marked blocked.
0.169.0's `GetAccountRateLimitsResponse` includes nullable `ordinaryUsageAllowed` and `accountId`. Only the full read's native permission boolean determines allowed/blocked availability; null is unknown, never inferred from a meter or elapsed reset. Identity comes from the native snapshot account ID, checked against `account/read.workspaceRouting.chatgptAccountId` when present (also a native fallback if the snapshot ID is absent). A mismatch removes recovery authority. Account changes, login/logout and process exit invalidate cached evidence and fence in-flight reads. Email, instance name and CODEX_HOME are not account proof.
`account/rateLimits/updated` is sparse and has no identity or permission boolean: it reports unknown availability and may reuse the last proven account identity. `usageLimitExceeded` alone emits run-scoped `usage_blocked`, without finishing the run or interrupting tools. Generic throttling/429, auth errors, warnings and full meters do not. Reset evidence requires an explicit reached quota/spend-control marker and every responsible deadline; use the latest across exhausted windows and buckets. Any missing deadline or workspace credit/billing ceiling omits the timer. The native error has no responsible window/reset; if no trustworthy usage snapshot supplies those facts, recovery remains manual. Recovery is account-wide, not narrowed to whichever bucket currently happens to be exhausted; a bucket recovering must not change the wait's quota identity. API-key/non-ChatGPT or older servers may provide no account identity/availability; that stays unknown.
## Rollback, fork and compaction
- `rollback` finds the turn holding the item and calls `thread/revert` (`thread/rollback` is deprecated). It rewrites history only; the host pairs it with its own file checkpoint, and rewinds the agent first so a refusal leaves the files untouched.
- `fork_session` uses `thread/fork` with `excludeTurns`.
- `compact` uses `thread/compact/start`; the `contextCompaction` item then arrives as a `Compacted` event.
## Skills
`skills/list` per workspace fills `list_skills`, and the name-to-path map it builds is what lets a `$name` prompt block become Codex's own `UserInput { type: "skill", name, path }`. A skill the CLI does not know falls back to the literal text, so nothing is silently dropped.
Descriptions prefer `interface.shortDescription`, then legacy `shortDescription`, then `description`. The list is asked with `forceReload`, because Codex watches skill folders only while a thread is loaded and otherwise keeps answering from its cache. While it watches, `skills/changed` arrives when a skill is added, changed or removed; the plugin passes it on as the agent-wide `skills_changed` event, and the host lists the skills again for every open chat.
## Gateway sign-in
`initialize` discovers gateway auth methods with `modelProvider/list` and targeted `account/gatewayOAuth/read`. Each advertised method authorizes that provider without changing the configured default. Device authorization is requested only when the native read advertises it. The plugin shows the native user code and opens the verification URL, or opens the browser handoff from `account/gatewayOAuth/changed`. Success waits for native confirmation, including a fresh status read when login returns no prompt. Native failure, browser refusal and process exit fail the call. An abandoned attempt sends `account/gatewayOAuth/cancel`. The model cache for the authorized provider is then invalidated. A default gateway that still needs authorization reports `auth_required`, so the existing Settings button is available. Settings currently hides all auth methods while an agent reports ready, so signing in to a non-default gateway from an otherwise ready account needs a shared Settings change to expose alternate auth methods.
## Updating
`AgentInfo.maintenance` reports the installed version and the installer that owns the binary, proven from the resolved real path (`api.process.which`): a versioned Homebrew keg or cask, `<prefix>/lib/node_modules/`, or a native install. Anything unproven reports the version but stays manual. An npm update pins `--prefix`, because the `npm` on `PATH` can belong to a different Node than the one that owns the CLI.
## Deliberate gaps
- **The `granular` approval policy is not offered.** It needs five sub-toggles that one `ConfigOption` select cannot express, and the four shared permission modes cover what the user actually chooses between.
- **No bundled model manifest.** T3 Code overlays `model-manifest.json` for display names and badges. That is the hardcoded-catalog pattern this project forbids, so the catalog stays whatever `model/list` reports.
- **`thread/start` takes `sandbox` as a mode string while `turn/start` takes a structured `sandboxPolicy`.** `sandboxPolicy()` retains the configured writable roots and network setting alongside the workspace.
- **`slash_commands` is false.** Codex has no slash-command API; the nearest thing is `skills/list`, and skills are invoked through a `UserInput { type: "skill" }` block rather than a `/name` prefix. Wiring skills into the composer needs a product decision, so it is left out.
- **`plan` items are ignored in the live stream.** The structured plan arrives as `turn/plan/updated`, which is what the `Plan` event models; the `plan` item only carries free-form markdown. In `read_session` — where the notification is not replayed — it is kept as a single-entry `Plan`.
- **`Usage.used_tokens` reports `tokenUsage.last.totalTokens`**, the size of the most recent request, because the event documents context-window usage. `total` accumulates across the whole thread and would read as greater than the context window.
- **Sign-in.** `account/read` tells whether `codex login` happened, and the plugin reports `AuthRequired` when it has not. The `chatgpt` auth method sends `account/login/start { type: "chatgpt" }` (the Rust plugin sent `{}`, which the v2 schema refuses) and opens the `authUrl` it answers with. A plugin without views may open it because the runtime opens a web link for a provider while the user signs in to one of its agents; a link it keeps closed (`{ opened: false, reason }`) fails the sign-in with the page's address.
- **Attachment resolution remains unavailable.** `ImageGenerationItem.fileId`, `UserInput.fileId` and function-output `file_id` preserve their identity as visible text when no bytes or saved image path are available. The 0.169.0 client request union exposes no attachment-byte resolver. `thread/attachment/list` returns an opaque JSON payload, with no specified image download contract, so the plugin does not guess a URL or treat an ID as a path. Inline and saved images still render. Full file-ID image rendering needs a native resolver or a documented attachment-store integration.
- **Tool audio needs a shared protocol change.** Function outputs report that audio is present, while encrypted output stays hidden. The host's tool content union cannot play audio or directly display a remote image URL.
- **Provider configuration forms remain outside this adapter.** Existing configured providers can be selected and authorized. Creating providers or editing gateway, Bedrock and GCP settings needs a settings form because `ConfigOption` supports only selects and toggles.
- Not wired: `review/start`, realtime and voice, `feedback/upload`, and the host-service families (`fs/*`, `command/exec`, `process/*`). The host owns those surfaces in Divergence.
- **No cached status across restarts.** A provider plugin is only ever called by the host and cannot call back, so there is nowhere to keep a snapshot. A cold start re-probes.
## Tests
`node --import ./plugins/testing/register.mjs --test plugins/codex/*.test.ts` runs the provider suite without network access. The loader resolves the runtime's `divergence` modules. `audit.test.ts` covers the 0.169.0 additions, including native approval decision payloads, sparse quota merges, provider catalogs, gateway sign-in, item replay, speed defaults and skill metadata. The Rust unit tests are ported: command classification, diff mapping, transcript roles, delta accumulation (with the no-duplicate rule for completed messages), reasoning replacement, terminal output and exit code, run completion/failure/one-shot, usage and titles, approvals and questions answered and withdrawn through a scripted app-server (the SDK's `FakePeer` in place of the Python peers), plugin tool calls, subagents (v1 spawn and `wait`, v2 activity, grandchildren, waiting, Stop order and approval release, `cancel_task`), and the history rebuild at depth 2. Added: initialize, options and `set_option`, prompt and steer, a refused turn, the app-server exiting, paged history, skills, rollback, fork, compact, sign-in, the stdin notice, and the accounts in `main.ts`.
`cargo test -p divergence-host --test e2e -- --ignored` runs the plugin in the real plugin host against the installed CLI: a PONG prompt, a turn that runs `cat` and calls a plugin tool, an imported thread's history, and `initialize` with the maintenance check.
Async `agentMessage` items (`delivery: "async"`, `questions`) emit message-mode questions on completion. Codex supplies the titles and optional choices; custom answers are always allowed. The host sends answers through the normal prompt path, which uses `turn/steer` while a Codex turn is active.
# Background terminals
The background-terminal mapping originally checked against Codex 0.163 also matches the supplied 0.169.0 schema. Its `v2/ThreadItem.ts` gives command executions `processId`, `status` and `aggregatedOutput`; `CommandExecutionOutputDeltaNotification.ts` identifies the thread, original item and output chunk. There is no background-terminal list notification. `process/outputDelta` and `process/exited` instead belong to client-created `process/spawn` requests and are not agent command events.
The provider tracks command items with a process ID and publishes a terminal task when an unfinished command survives its turn. It continues accepting that command's output and final item after the original turn is retired. Foreground commands keep their ordinary tool rows. The 0.163 source in `core/src/unified_exec/process_manager.rs` emits the start with the process ID; `async_watcher.rs` emits output and the eventual completed item. Native output-delta limits still apply, and final aggregated output refreshes the tail.
No comments yet.