actorOther model families run as real Claude Code agents
spec:cc-agents.runnerNext rung ready: nothing blocks; it waits only for the author's statement.
Packs: none
Design: no design entries · no pinned declarations · no decisions
Findings: no errors, no warnings
specs/runner/runner.sdp.md
2 open questions and no blocking questions; implementation binding none, verifier binding none, and expected-outcome oracle none.
The job runner is a Claude Code plugin in plain JavaScript with no dependencies. A user, or a Workflow script, starts an agent of type cc-agents:<harness>; Claude Code runs it as an ordinary subagent with its own id, transcript and rows, and the plugin answers each of its model steps from a turn of another harness. Three layers carry that: a mod that speaks to Claude Code and knows no harness, a sidecar process per Claude session that owns the harness turns, and one adapter module per harness. The children of this epic describe the layers and the machine-wide machinery beside them; delivery facts belong to the children, none to the epic.
Intent
- A Claude Code user, or a Workflow script, that delegates a task to a model family Claude does not run.
problem- Running a foreign model beside Claude needs a Claude model in the middle to relay its work, which costs tokens, can alter the answer, and hides what the foreign model is doing.
outcome- A foreign model occupies an agent or Workflow role as itself: started, steered, stopped and watched like a Claude agent, returning exactly the text it answered.
value- Work that suits another family runs in the user's own Claude Code session on that family's own sign-in, with no Claude model spending tokens on the task.
Open questions
- non-blocking ·
question.teamsline 28 · specs/runner/runner.sdp.md:28· Agent-team teammates are refused by design for now, and the question of whether they should ever be supported is deferred.Decider: ownerProvisional: A foreign agent runs as a subagent only; the mod denies a spawn that asks to be a teammate. - non-blocking ·
question.nativeGrokline 31 · specs/runner/runner.sdp.md:31· Grok runs through OpenCode only; a native adapter for it was left for later.Decider: ownerProvisional: Every family other than GPT goes through the OpenCode adapter.
Behavior
rule.claudeStaysHostline 37 ·specs/runner/runner.sdp.md:37- Claude Code stays the host: the agent is a real subagent, and no Claude model works on its task, because every step is answered from the harness's events.
no example exercises it
rule.twoFamiliesline 38 ·specs/runner/runner.sdp.md:38- GPT runs through Codex natively and every other family through OpenCode, one adapter per harness, and nothing about a harness sits outside its adapter.
no example exercises it
rule.oneSidecarPerSessionline 39 ·specs/runner/runner.sdp.md:39- Each Claude session has its own sidecar, which owns the session's harness turns and exits when the session's process does.
no example exercises it
rule.capacityIsMachineWideline 40 ·specs/runner/runner.sdp.md:40- How many turns may run at once is counted across every Claude session on the machine, and a new start is refused only while the machine itself is critically loaded.
no example exercises it
rule.harnessEnforcesModeline 41 ·specs/runner/runner.sdp.md:41- A mode of read-only or write is enforced by the harness, never granted by the plugin, and a harness that cannot enforce a mode refuses it before anything starts.
no example exercises it
rule.noApprovalsline 42 ·specs/runner/runner.sdp.md:42- A request for approval from a harness is declined and shown, never put to the user.
no example exercises it
rule.exactAnswerline 43 ·specs/runner/runner.sdp.md:43- The agent's last message is the harness's final answer, unchanged.
no example exercises it
0 unkeyed rules.
Verification
Verifier bindings
No verifier binding recorded.
Design view
Requirement drawing
- Declared verifying examples: no declared verifying example.
The diagram as text
- spec:cc-agents.runner: Other model families run as real Claude Code agents · declared Spec · no satisfying binding
- spec:cc-agents.adapter-contract: One adapter module per harness, behind one contract · declared Spec
- spec:cc-agents.codex-adapter: GPT runs through the user's Codex, one app-server per turn · declared Spec
- spec:cc-agents.cross-session-slots: A cap on concurrent turns holds across every Claude session on the machine · declared Spec
- spec:cc-agents.exact-answer: The agent's last message is exactly the harness's final answer · declared Spec
- spec:cc-agents.installation: The plugin installs from a marketplace, updates by version and changes nothing global · declared Spec · no satisfying binding
- spec:cc-agents.machine-guard: A critically loaded machine refuses new agents and stops none · declared Spec
- spec:cc-agents.mod-layer: The mod answers an agent's steps from the sidecar and never calls a model · declared Spec
- spec:cc-agents.model-templates: Claude reads a model guide that fits the harnesses installed here · declared Spec
- spec:cc-agents.opencode-adapter: Every other family runs through the user's OpenCode service · declared Spec
- spec:cc-agents.pane: The session's agents, their caps and the machine are always in view · declared Spec
- spec:cc-agents.relay-job-type: The job agent takes Relay's header and returns Relay's state block · declared Spec
- spec:cc-agents.sidecar: One sidecar per Claude session owns the session's harness turns · declared Spec
- spec:cc-agents.steering-and-stop: A message reaches the running turn at once, and a stop ends the harness turn · declared Spec
- spec:cc-agents.work-containment: A guard ends the groups a harness turn started and it has seen, even when the sidecar is killed · 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 - impl:cc-agents.groups: records the process groups of a guarded turn and tells whether its work still runs · anchored code ·
plugin/sidecar/groups.mjs:13 - impl:cc-agents.guard: runs one harness process in a group it leads and ends everything the turn started · anchored code ·
plugin/sidecar/guard.mjs:16 - impl:cc-agents.harness-options: reads the per-harness options, picks the model-guide template and builds the /harnesses text · anchored code ·
plugin/hooks/harnesses.js:5 - impl:cc-agents.launch: starts the sidecar detached and returns once it answers on its socket · anchored code ·
plugin/sidecar/launch.mjs:7 - impl:cc-agents.machine: judges how loaded the machine is and admits a start unless it is critical · anchored code ·
plugin/sidecar/machine.mjs:20 - impl:cc-agents.mod: answers each step of an agent from the sidecar's events, hands back the exact answer, steers and stops, and returns the job state block · anchored code ·
plugin/hooks/register.js:9 - impl:cc-agents.opencode: the OpenCode adapter: a session on the user's service, polled by transcript, reaped by lease · anchored code ·
plugin/sidecar/adapters/opencode.mjs:26 - impl:cc-agents.pane: draws the lanes, the band and the pane from the sidecar's status · anchored code ·
plugin/hooks/pane.js:13 - impl:cc-agents.relay-header: turns Relay's job header into a harness, a model and the turn's options · anchored code ·
plugin/sidecar/relay-header.mjs:9 - impl:cc-agents.sidecar: the per-session sidecar: owns each harness turn, its events and its slot, and drives every adapter through the contract · anchored code ·
plugin/sidecar/server.mjs:12 - impl:cc-agents.slots: the machine-wide cap on concurrent turns, held with OS locks that die with their holder · anchored code ·
plugin/sidecar/slots.mjs:16 - impl:cc-agents.sync-templates: copies the rendered model guides into the plugin and refuses a private word · anchored code ·
scripts/sync-templates.mjs:10 - test:cc-agents.machine-suite: the machine guard against recorded sensor readings · anchored test binding · binding present ·
tests/machine.test.mjs:4 - test:cc-agents.mod-suite: the mod against a scripted sidecar · anchored test binding · binding present ·
plugin/tests/mod.test.ts:4 - test:cc-agents.opencode-suite: the OpenCode adapter against a fake OpenCode service · anchored test binding · binding present ·
tests/adapters/opencode.test.mjs:4 - test:cc-agents.pane-suite: the pane against a scripted status · anchored test binding · binding present ·
plugin/tests/pane.test.ts:4 - 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.adapter-contract refines spec:cc-agents.runner · declared
- spec:cc-agents.codex-adapter refines spec:cc-agents.runner · declared
- spec:cc-agents.cross-session-slots refines spec:cc-agents.runner · declared
- spec:cc-agents.exact-answer refines spec:cc-agents.runner · declared
- spec:cc-agents.installation refines spec:cc-agents.runner · declared
- spec:cc-agents.machine-guard refines spec:cc-agents.runner · declared
- spec:cc-agents.mod-layer refines spec:cc-agents.runner · declared
- spec:cc-agents.model-templates refines spec:cc-agents.runner · declared
- spec:cc-agents.opencode-adapter refines spec:cc-agents.runner · declared
- spec:cc-agents.pane refines spec:cc-agents.runner · declared
- spec:cc-agents.relay-job-type refines spec:cc-agents.runner · declared
- spec:cc-agents.sidecar refines spec:cc-agents.runner · declared
- spec:cc-agents.steering-and-stop refines spec:cc-agents.runner · declared
- spec:cc-agents.work-containment refines spec:cc-agents.runner · declared
- impl:cc-agents.codex satisfies spec:cc-agents.codex-adapter · anchored
- impl:cc-agents.codex satisfies spec:cc-agents.adapter-contract · anchored
- impl:cc-agents.groups satisfies spec:cc-agents.work-containment · anchored
- impl:cc-agents.guard satisfies spec:cc-agents.work-containment · anchored
- impl:cc-agents.harness-options satisfies spec:cc-agents.model-templates · anchored
- impl:cc-agents.harness-options satisfies spec:cc-agents.pane · anchored
- impl:cc-agents.harness-options references spec:cc-agents.installation · anchored
- impl:cc-agents.launch satisfies spec:cc-agents.sidecar · anchored
- impl:cc-agents.machine satisfies spec:cc-agents.machine-guard · anchored
- impl:cc-agents.mod satisfies spec:cc-agents.mod-layer · anchored
- impl:cc-agents.mod satisfies spec:cc-agents.exact-answer · anchored
- impl:cc-agents.mod satisfies spec:cc-agents.steering-and-stop · anchored
- impl:cc-agents.mod satisfies spec:cc-agents.relay-job-type · anchored
- impl:cc-agents.mod satisfies spec:cc-agents.model-templates · anchored
- impl:cc-agents.opencode satisfies spec:cc-agents.opencode-adapter · anchored
- impl:cc-agents.opencode satisfies spec:cc-agents.adapter-contract · anchored
- impl:cc-agents.pane satisfies spec:cc-agents.pane · anchored
- impl:cc-agents.relay-header satisfies spec:cc-agents.relay-job-type · anchored
- impl:cc-agents.sidecar satisfies spec:cc-agents.sidecar · anchored
- impl:cc-agents.sidecar satisfies spec:cc-agents.cross-session-slots · anchored
- impl:cc-agents.sidecar satisfies spec:cc-agents.adapter-contract · anchored
- impl:cc-agents.sidecar satisfies spec:cc-agents.relay-job-type · anchored
- impl:cc-agents.sidecar satisfies spec:cc-agents.steering-and-stop · anchored
- impl:cc-agents.sidecar references spec:cc-agents.machine-guard · anchored
- impl:cc-agents.slots satisfies spec:cc-agents.cross-session-slots · anchored
- impl:cc-agents.sync-templates references spec:cc-agents.model-templates · anchored
- test:cc-agents.machine-suite verifies spec:cc-agents.machine-guard · anchored
- test:cc-agents.mod-suite verifies spec:cc-agents.mod-layer · anchored
- test:cc-agents.mod-suite verifies spec:cc-agents.exact-answer · anchored
- test:cc-agents.mod-suite verifies spec:cc-agents.steering-and-stop · anchored
- test:cc-agents.mod-suite verifies spec:cc-agents.relay-job-type · anchored
- test:cc-agents.mod-suite verifies spec:cc-agents.model-templates · anchored
- test:cc-agents.mod-suite verifies spec:cc-agents.pane · anchored
- test:cc-agents.opencode-suite verifies spec:cc-agents.opencode-adapter · anchored
- test:cc-agents.opencode-suite verifies spec:cc-agents.adapter-contract · anchored
- test:cc-agents.pane-suite verifies spec:cc-agents.pane · anchored
- test:cc-agents.sidecar-suite verifies spec:cc-agents.sidecar · anchored
- test:cc-agents.sidecar-suite verifies spec:cc-agents.adapter-contract · anchored
- test:cc-agents.sidecar-suite verifies spec:cc-agents.codex-adapter · anchored
- test:cc-agents.sidecar-suite verifies spec:cc-agents.cross-session-slots · anchored
- test:cc-agents.sidecar-suite verifies spec:cc-agents.work-containment · anchored
- test:cc-agents.sidecar-suite verifies spec:cc-agents.relay-job-type · anchored
- test:cc-agents.sidecar-suite verifies spec:cc-agents.machine-guard · anchored
- test:cc-agents.sidecar-suite verifies spec:cc-agents.steering-and-stop · anchored
Mermaid source
Copyable source; the Studio draws static SVG.
Preferred syntax: requirementDiagram. Chosen syntax: flowchart TB because references, folds require exact labels unavailable in requirement syntax.
Decisions
No decision record named.
Runtime
No implementation neighborhood recorded.
Runtime observation: not tracked.
Evidence
Runtime observation: not tracked.
Build attestations: not tracked.
Deployments: not tracked.
Bills of materials: not tracked.
Impact
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.cross-session-slots: A cap on concurrent turns holds across every Claude session on the machine
- spec:cc-agents.exact-answer: The agent's last message is exactly the harness's final answer
- spec:cc-agents.hq-links: The one tie between this repository's Specs and HQ's design
- spec:cc-agents.installation: The plugin installs from a marketplace, updates by version and changes nothing global
- spec:cc-agents.machine-guard: A critically loaded machine refuses new agents and stops none
- spec:cc-agents.mod-layer: The mod answers an agent's steps from the sidecar and never calls a model
- spec:cc-agents.model-templates: Claude reads a model guide that fits the harnesses installed here
- spec:cc-agents.opencode-adapter: Every other family runs through the user's OpenCode service
- spec:cc-agents.pane: The session's agents, their caps and the machine are always in view
- spec:cc-agents.relay-job-type: The job agent takes Relay's header and returns Relay's state block
- spec:cc-agents.runner: Other model families run as real Claude Code agents
- spec:cc-agents.sidecar: One sidecar per Claude session owns the session's harness turns
- spec:cc-agents.steering-and-stop: A message reaches the running turn at once, and a stop ends the harness turn
- 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.runner dependsOn spec:cc-agents.adapter-contract · declared — the seam that keeps every harness out of the other two layers
- spec:cc-agents.runner dependsOn spec:cc-agents.mod-layer · declared — the layer that speaks to Claude Code
- spec:cc-agents.runner dependsOn spec:cc-agents.sidecar · declared — the per-session process that owns every harness turn
- spec:cc-agents.hq-links dependsOn spec:cc-agents.runner · declared — the job runner, which answers the provider and template rules below
- spec:cc-agents.adapter-contract refines spec:cc-agents.runner · declared
- spec:cc-agents.codex-adapter refines spec:cc-agents.runner · declared
- spec:cc-agents.cross-session-slots refines spec:cc-agents.runner · declared
- spec:cc-agents.exact-answer refines spec:cc-agents.runner · declared
- spec:cc-agents.installation refines spec:cc-agents.runner · declared
- spec:cc-agents.machine-guard refines spec:cc-agents.runner · declared
- spec:cc-agents.mod-layer refines spec:cc-agents.runner · declared
- spec:cc-agents.model-templates refines spec:cc-agents.runner · declared
- spec:cc-agents.opencode-adapter refines spec:cc-agents.runner · declared
- spec:cc-agents.pane refines spec:cc-agents.runner · declared
- spec:cc-agents.relay-job-type refines spec:cc-agents.runner · declared
- spec:cc-agents.sidecar refines spec:cc-agents.runner · declared
- spec:cc-agents.steering-and-stop refines spec:cc-agents.runner · declared
- spec:cc-agents.work-containment refines spec:cc-agents.runner · declared
Mermaid source
Copyable source; the Studio draws static SVG.
Preferred syntax: flowchart. Chosen syntax: labelled flowchart, preserving exact relations, claims and folds.
Rests on
- dependsOn · spec:cc-agents.adapter-contract · stated ready, floor ready
- dependsOn · spec:cc-agents.mod-layer · stated ready, floor ready
- dependsOn · spec:cc-agents.sidecar · stated ready, floor ready
Rested on by
Distance 1
- spec:cc-agents.adapter-contract
Implementing units
impl:cc-agents.codex·plugin/sidecar/adapters/codex.mjs:15impl:cc-agents.opencode·plugin/sidecar/adapters/opencode.mjs:26impl:cc-agents.sidecar·plugin/sidecar/server.mjs:12
Referencing units
None.
Enabled verifiers: test:cc-agents.opencode-suite, test:cc-agents.sidecar-suite
Packs: None
- spec:cc-agents.codex-adapter
Implementing units
impl:cc-agents.codex·plugin/sidecar/adapters/codex.mjs:15
Referencing units
None.
Enabled verifiers: test:cc-agents.sidecar-suite
Packs: None
- spec:cc-agents.cross-session-slots
Implementing units
impl:cc-agents.sidecar·plugin/sidecar/server.mjs:12impl:cc-agents.slots·plugin/sidecar/slots.mjs:16
Referencing units
None.
Enabled verifiers: test:cc-agents.sidecar-suite
Packs: None
- spec:cc-agents.exact-answer
Implementing units
impl:cc-agents.mod·plugin/hooks/register.js:9
Referencing units
None.
Enabled verifiers: test:cc-agents.mod-suite
Packs: None
- spec:cc-agents.hq-links
Implementing units
None.
Referencing units
None.
Enabled verifiers: None
Packs: None
- spec:cc-agents.installation
Implementing units
None.
Referencing units
impl:cc-agents.harness-options·plugin/hooks/harnesses.js:5
Enabled verifiers: None
Packs: None
- spec:cc-agents.machine-guard
Implementing units
impl:cc-agents.machine·plugin/sidecar/machine.mjs:20
Referencing units
impl:cc-agents.sidecar·plugin/sidecar/server.mjs:12
Enabled verifiers: test:cc-agents.machine-suite, test:cc-agents.sidecar-suite
Packs: None
- spec:cc-agents.mod-layer
Implementing units
impl:cc-agents.mod·plugin/hooks/register.js:9
Referencing units
None.
Enabled verifiers: test:cc-agents.mod-suite
Packs: None
- spec:cc-agents.model-templates
Implementing units
impl:cc-agents.harness-options·plugin/hooks/harnesses.js:5impl:cc-agents.mod·plugin/hooks/register.js:9
Referencing units
impl:cc-agents.sync-templates·scripts/sync-templates.mjs:10
Enabled verifiers: test:cc-agents.mod-suite
Packs: None
- spec:cc-agents.opencode-adapter
Implementing units
impl:cc-agents.opencode·plugin/sidecar/adapters/opencode.mjs:26
Referencing units
None.
Enabled verifiers: test:cc-agents.opencode-suite
Packs: None
- spec:cc-agents.pane
Implementing units
impl:cc-agents.harness-options·plugin/hooks/harnesses.js:5impl:cc-agents.pane·plugin/hooks/pane.js:13
Referencing units
None.
Enabled verifiers: test:cc-agents.mod-suite, test:cc-agents.pane-suite
Packs: None
- spec:cc-agents.relay-job-type
Implementing units
impl:cc-agents.mod·plugin/hooks/register.js:9impl:cc-agents.relay-header·plugin/sidecar/relay-header.mjs:9impl:cc-agents.sidecar·plugin/sidecar/server.mjs:12
Referencing units
None.
Enabled verifiers: test:cc-agents.mod-suite, test:cc-agents.sidecar-suite
Packs: None
- spec:cc-agents.sidecar
Implementing units
impl:cc-agents.launch·plugin/sidecar/launch.mjs:7impl:cc-agents.sidecar·plugin/sidecar/server.mjs:12
Referencing units
None.
Enabled verifiers: test:cc-agents.sidecar-suite
Packs: None
- spec:cc-agents.steering-and-stop
Implementing units
impl:cc-agents.mod·plugin/hooks/register.js:9impl:cc-agents.sidecar·plugin/sidecar/server.mjs:12
Referencing units
None.
Enabled verifiers: test:cc-agents.mod-suite, test:cc-agents.sidecar-suite
Packs: None
- spec:cc-agents.work-containment
Implementing units
impl:cc-agents.groups·plugin/sidecar/groups.mjs:13impl:cc-agents.guard·plugin/sidecar/guard.mjs:16
Referencing units
None.
Enabled verifiers: test:cc-agents.sidecar-suite
Packs: None
Relations
| Relation and direction | Other end | Claim | Reason | Exercised keys |
|---|---|---|---|---|
| dependsOn · outgoing | One adapter module per harness, behind one contractspec:cc-agents.adapter-contract · resolves | declared | the seam that keeps every harness out of the other two layers | None |
| dependsOn · outgoing | The mod answers an agent's steps from the sidecar and never calls a modelspec:cc-agents.mod-layer · resolves | declared | the layer that speaks to Claude Code | None |
| dependsOn · outgoing | One sidecar per Claude session owns the session's harness turnsspec:cc-agents.sidecar · resolves | declared | the per-session process that owns every harness turn | None |
| dependsOn · incoming | The one tie between this repository's Specs and HQ's designspec:cc-agents.hq-links · resolves | declared | the job runner, which answers the provider and template rules below | None |
| refines · incoming | One adapter module per harness, behind one contractspec:cc-agents.adapter-contract · resolves | declared | None | None |
| refines · incoming | GPT runs through the user's Codex, one app-server per turnspec:cc-agents.codex-adapter · resolves | declared | None | None |
| refines · incoming | A cap on concurrent turns holds across every Claude session on the machinespec:cc-agents.cross-session-slots · resolves | declared | None | None |
| refines · incoming | The agent's last message is exactly the harness's final answerspec:cc-agents.exact-answer · resolves | declared | None | None |
| refines · incoming | The plugin installs from a marketplace, updates by version and changes nothing globalspec:cc-agents.installation · resolves | declared | None | None |
| refines · incoming | A critically loaded machine refuses new agents and stops nonespec:cc-agents.machine-guard · resolves | declared | None | None |
| refines · incoming | The mod answers an agent's steps from the sidecar and never calls a modelspec:cc-agents.mod-layer · resolves | declared | None | None |
| refines · incoming | Claude reads a model guide that fits the harnesses installed herespec:cc-agents.model-templates · resolves | declared | None | None |
| refines · incoming | Every other family runs through the user's OpenCode servicespec:cc-agents.opencode-adapter · resolves | declared | None | None |
| refines · incoming | The session's agents, their caps and the machine are always in viewspec:cc-agents.pane · resolves | declared | None | None |
| refines · incoming | The job agent takes Relay's header and returns Relay's state blockspec:cc-agents.relay-job-type · resolves | declared | None | None |
| refines · incoming | One sidecar per Claude session owns the session's harness turnsspec:cc-agents.sidecar · resolves | declared | None | None |
| refines · incoming | A message reaches the running turn at once, and a stop ends the harness turnspec:cc-agents.steering-and-stop · resolves | declared | None | None |
| refines · incoming | A guard ends the groups a harness turn started and it has seen, even when the sidecar is killedspec:cc-agents.work-containment · resolves | declared | None | None |
Bindings
Implementation binding: none
Design reference: none
Verifier binding: none
Expected-outcome oracle: none
Runtime observation: not tracked.
Run results: not recorded in the graph.
Findings
None.
Composing (0)
Composing needs the script.