GPT runs through the user's Codex, one app-server per turn

spec:cc-agents.codex-adapter

Use Case / Behavior · featureready floor ready

Packs: none

Design: 4 design entries · 4 pinned declarations · no decisions

specs/runner/codex-adapter.sdp.md

2 open questions and no blocking questions; implementation binding present, verifier binding present, and expected-outcome oracle none.

The adapter is plugin/sidecar/adapters/codex.mjs. It speaks JSON-RPC over stdio to one codex app-server per turn, started under the guard, and uses the user's Codex sign-in and configuration as they are.

Intent

actor: A user who wants a GPT model as a Claude Code agent.
problem: Codex has its own sandbox, approval and tool machinery, and a turn must never get more access than the mode it was asked for.
outcome: A Codex turn runs in the mode asked, exposes no tool outside the sandbox, and returns Codex's own answer and usage.
value: GPT's native Codex capabilities are used as they are, with the sandbox as the only enforcer of the mode.

Open questions

non-blocking · question.fakeAppServer line 27 · specs/runner/codex-adapter.sdp.md:27 · These behaviours are exercised against a fake app-server that speaks Codex's protocol; a real Codex is exercised only by the live suite under tests/live, which runs outside the graph and outside the gate.Decider: ownerProvisional: The unit evidence stands for the protocol; the live suite remains the check against a real Codex.
non-blocking · question.perAccount line 30 · specs/runner/codex-adapter.sdp.md:30 · The README calls the Codex cap per account, while the adapter keeps a single machine-wide bucket named codex whose default is the machine's share.Decider: ownerProvisional: Described here as a machine-wide bucket; no account identity is established.

Behavior

rule.catalogCheck line 36 · specs/runner/codex-adapter.sdp.md:36: A check resolves the model from the header, the option, Codex's configured model or its default, resolves the effort from the header, Codex's configuration or the model's default, and refuses an unknown model or effort listing the ones that work.
no example exercises it
rule.modes line 37 · specs/runner/codex-adapter.sdp.md:37: Read-only runs in Codex's read-only sandbox, write in its workspace-write sandbox over the working directory, the added folders and temporary folders with no network unless asked, and yolo, only when stated, with no sandbox.
no example exercises it
rule.approvalsNever line 38 · specs/runner/codex-adapter.sdp.md:38: The approval policy is never, and any approval request that still arrives is declined with a visible status line.
no example exercises it
rule.mcpOff line 39 · specs/runner/codex-adapter.sdp.md:39: Every turn runs with the user's MCP servers, the apps connectors and the Codex plugins turned off, and a turn in which an MCP server starts anyway fails because the mode could not be enforced.
no example exercises it
rule.guardedAppServer line 40 · specs/runner/codex-adapter.sdp.md:40: The app-server runs under the guard in a process group of its own, and that group is the turn's work, recorded before the turn is submitted.
no example exercises it
rule.exactFinal line 41 · specs/runner/codex-adapter.sdp.md:41: The final text is the Codex answer unchanged, including a character split across two chunks of output, and the usage is the turn's own, not the thread's running total.
no example exercises it
rule.threadResumes line 42 · specs/runner/codex-adapter.sdp.md:42: A follow-up resumes the saved Codex thread, and a steer goes into the running turn once the turn has started.
no example exercises it
rule.interruptConfirmed line 43 · specs/runner/codex-adapter.sdp.md:43: An interrupt asks Codex to stop and, when Codex does not confirm, ends the process group, and the turn ends only once its processes are gone.
no example exercises it
rule.errorKinds line 44 · specs/runner/codex-adapter.sdp.md:44: A Codex error is classified by the protocol's own error kind first and by its message second, as capacity, rate-limit, quota, auth or other, and none of them is retried by the plugin.
no example exercises it
rule.defaultCap line 45 · specs/runner/codex-adapter.sdp.md:45: The default cap of the codex key is the smaller of three turns per available core and the memory divided by 800 MiB, at least one, and the caps option replaces it.
no example exercises it
rule.extraWritableFolders line 46 · specs/runner/codex-adapter.sdp.md:46: The user's extra writable folders, with ~ expanded, are added in write mode only, a relative one is refused, and a job's add-dir comes on top.
no example exercises it

0 unkeyed rules.

Design

binary line 50 · specs/runner/codex-adapter.sdp.md:50: codex, or the path in CC_AGENTS_CODEX_BIN.
no citation recorded
capKey line 51 · specs/runner/codex-adapter.sdp.md:51: codex
no citation recorded
modes line 52 · specs/runner/codex-adapter.sdp.md:52: read-only, write, yolo.
no citation recorded
offSwitches line 53 · specs/runner/codex-adapter.sdp.md:53: -c mcp_servers.<name>.enabled=false for each configured server, -c features.apps=false and -c features.plugins=false.
no citation recorded

Verification

Verifier bindings

test:cc-agents.sidecar-suite · the sidecar, the Codex adapter, the slots and the guard against a fake Codex app-server · anchored · test anchor binding present · tests/sidecar.test.mjs:4

Design view

Requirement drawing

Declared verifying examples: no declared verifying example.

Requirement drawing for spec:cc-agents.codex-adapter

The diagram as text

spec:cc-agents.codex-adapter: GPT runs through the user's Codex, one app-server per turn · declared Spec
spec:cc-agents.runner: Other model families run as real Claude Code agents · declared Spec
impl:cc-agents.codex: the Codex adapter: one guarded app-server per turn, sandbox modes, MCP off · anchored code · plugin/sidecar/adapters/codex.mjs:15
test:cc-agents.sidecar-suite: the sidecar, the Codex adapter, the slots and the guard against a fake Codex app-server · anchored test binding · binding present · tests/sidecar.test.mjs:4
spec:cc-agents.codex-adapter refines spec:cc-agents.runner · declared
impl:cc-agents.codex satisfies spec:cc-agents.codex-adapter · anchored
test:cc-agents.sidecar-suite verifies spec:cc-agents.codex-adapter · anchored

Mermaid source

Copyable source; the Studio draws static SVG.

Preferred and chosen syntax: requirementDiagram; exact refines, satisfies and verifies, with claim words in nodes and per-edge comments.

Mermaid source for Requirement drawing for spec:cc-agents.codex-adapter

requirementDiagram
  requirement n0 {
    text: "GPT runs through the user's Codex, one app-server per turn · declared Spec · spec:cc-agents.codex-adapter"
  }
  element n1 {
    type: "the Codex adapter: one guarded app-server per turn, sandbox modes, MCP off · anchored code · impl:cc-agents.codex"
  }
  element n2 {
    type: "the sidecar, the Codex adapter, the slots and the guard against a fake Codex app-server · anchored test binding · binding present · test:cc-agents.sidecar-suite"
  }
  requirement n3 {
    text: "Other model families run as real Claude Code agents · declared Spec · spec:cc-agents.runner"
  }
  %% claim: anchored
  n1 - satisfies -> n0
  %% claim: declared
  n0 - refines -> n3
  %% claim: anchored
  n2 - verifies -> n0

Decisions

No decision record named.

Runtime

impl:cc-agents.codex · the Codex adapter: one guarded app-server per turn, sandbox modes, MCP off · plugin/sidecar/adapters/codex.mjs:15
Uses
None.

Runtime observation: not tracked.

Evidence

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

Impact

Relations of spec:cc-agents.codex-adapter

The diagram as text

spec:cc-agents.adapter-contract: One adapter module per harness, behind one contract
spec:cc-agents.codex-adapter: GPT runs through the user's Codex, one app-server per turn
spec:cc-agents.hq-links: The one tie between this repository's Specs and HQ's design
spec:cc-agents.runner: Other model families run as real Claude Code agents
spec:cc-agents.work-containment: A guard ends the groups a harness turn started and it has seen, even when the sidecar is killed
spec:cc-agents.codex-adapter dependsOn spec:cc-agents.adapter-contract · declared — the Codex adapter is one implementation of the contract
spec:cc-agents.codex-adapter dependsOn spec:cc-agents.work-containment · declared — the Codex app-server runs under the guard, and its process group is the turn's work
spec:cc-agents.codex-adapter refines spec:cc-agents.runner · declared
spec:cc-agents.hq-links dependsOn spec:cc-agents.codex-adapter · declared — GPT occupies a lane beside Claude

Mermaid source

Copyable source; the Studio draws static SVG.

Preferred syntax: flowchart. Chosen syntax: labelled flowchart, preserving exact relations, claims and folds.

Mermaid source for Relations of spec:cc-agents.codex-adapter

flowchart TB
  n0["Other model families run as real Claude Code agents · spec:cc-agents.runner"]
  n1["One adapter module per harness, behind one contract · spec:cc-agents.adapter-contract"]
  n2["A guard ends the groups a harness turn started and it has seen, even when the sidecar is killed · spec:cc-agents.work-containment"]
  n3["GPT runs through the user's Codex, one app-server per turn · spec:cc-agents.codex-adapter"]
  n4["The one tie between this repository's Specs and HQ's design · spec:cc-agents.hq-links"]
  n3 -->|"dependsOn · declared — the Codex adapter is one implementation of the contract"| n1
  n3 -->|"refines · declared"| n0
  n3 -->|"dependsOn · declared — the Codex app-server runs under the guard, and its process group is the turn's work"| n2
  n4 -->|"dependsOn · declared — GPT occupies a lane beside Claude"| n3

Rests on

refines · spec:cc-agents.runner · stated defined, floor ready
dependsOn · spec:cc-agents.adapter-contract · stated ready, floor ready
dependsOn · spec:cc-agents.work-containment · stated ready, floor ready

Rested on by

Distance 1

spec:cc-agents.hq-links
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None

Relations

Relation and direction	Other end	Claim	Reason	Exercised keys
dependsOn · outgoing	One adapter module per harness, behind one contract `spec:cc-agents.adapter-contract` · resolves	declared	the Codex adapter is one implementation of the contract	None
dependsOn · outgoing	A guard ends the groups a harness turn started and it has seen, even when the sidecar is killed `spec:cc-agents.work-containment` · resolves	declared	the Codex app-server runs under the guard, and its process group is the turn's work	None
refines · outgoing	Other model families run as real Claude Code agents `spec:cc-agents.runner` · resolves	declared	None	None
dependsOn · incoming	The one tie between this repository's Specs and HQ's design `spec:cc-agents.hq-links` · resolves	declared	GPT occupies a lane beside Claude	None

Bindings

Implementation binding: present

impl:cc-agents.codex · the Codex adapter: one guarded app-server per turn, sandbox modes, MCP off · plugin/sidecar/adapters/codex.mjs:15

Design reference: none

Verifier binding: present

test:cc-agents.sidecar-suite · the sidecar, the Codex adapter, the slots and the guard against a fake Codex app-server · anchored · tests/sidecar.test.mjs:4 · test anchor

Expected-outcome oracle: none

Runtime observation: not tracked.

Run results: not recorded in the graph.

Findings

None.

Composing (0)

Composing needs the script.