Spec Studio

Other model families run as real Claude Code agents

spec:cc-agents.runnerUse Case / Behavior · epicdefined floor ready

Next 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
actor
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.teams line 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.nativeGrok line 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.claudeStaysHost line 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.twoFamilies line 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.oneSidecarPerSession line 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.capacityIsMachineWide line 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.harnessEnforcesMode line 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.noApprovals line 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.exactAnswer line 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.
Requirement drawing for spec:cc-agents.runner
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
Relations of spec:cc-agents.runner
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

Rested on by

Distance 1

  • spec:cc-agents.adapter-contract

    Implementing units

    • impl:cc-agents.codex · plugin/sidecar/adapters/codex.mjs:15
    • impl:cc-agents.opencode · plugin/sidecar/adapters/opencode.mjs:26
    • impl: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:12
    • impl: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:5
    • impl: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:5
    • impl: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:9
    • impl:cc-agents.relay-header · plugin/sidecar/relay-header.mjs:9
    • impl: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:7
    • impl: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:9
    • impl: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:13
    • impl:cc-agents.guard · plugin/sidecar/guard.mjs:16

    Referencing units

    None.

    Enabled verifiers: test:cc-agents.sidecar-suite

    Packs: None

Relations

Relation and directionOther endClaimReasonExercised keys
dependsOn · outgoingOne adapter module per harness, behind one contract
spec:cc-agents.adapter-contract · resolves
declaredthe seam that keeps every harness out of the other two layersNone
dependsOn · outgoingThe mod answers an agent's steps from the sidecar and never calls a model
spec:cc-agents.mod-layer · resolves
declaredthe layer that speaks to Claude CodeNone
dependsOn · outgoingOne sidecar per Claude session owns the session's harness turns
spec:cc-agents.sidecar · resolves
declaredthe per-session process that owns every harness turnNone
dependsOn · incomingThe one tie between this repository's Specs and HQ's design
spec:cc-agents.hq-links · resolves
declaredthe job runner, which answers the provider and template rules belowNone
refines · incomingOne adapter module per harness, behind one contract
spec:cc-agents.adapter-contract · resolves
declaredNoneNone
refines · incomingGPT runs through the user's Codex, one app-server per turn
spec:cc-agents.codex-adapter · resolves
declaredNoneNone
refines · incomingA cap on concurrent turns holds across every Claude session on the machine
spec:cc-agents.cross-session-slots · resolves
declaredNoneNone
refines · incomingThe agent's last message is exactly the harness's final answer
spec:cc-agents.exact-answer · resolves
declaredNoneNone
refines · incomingThe plugin installs from a marketplace, updates by version and changes nothing global
spec:cc-agents.installation · resolves
declaredNoneNone
refines · incomingA critically loaded machine refuses new agents and stops none
spec:cc-agents.machine-guard · resolves
declaredNoneNone
refines · incomingThe mod answers an agent's steps from the sidecar and never calls a model
spec:cc-agents.mod-layer · resolves
declaredNoneNone
refines · incomingClaude reads a model guide that fits the harnesses installed here
spec:cc-agents.model-templates · resolves
declaredNoneNone
refines · incomingEvery other family runs through the user's OpenCode service
spec:cc-agents.opencode-adapter · resolves
declaredNoneNone
refines · incomingThe session's agents, their caps and the machine are always in view
spec:cc-agents.pane · resolves
declaredNoneNone
refines · incomingThe job agent takes Relay's header and returns Relay's state block
spec:cc-agents.relay-job-type · resolves
declaredNoneNone
refines · incomingOne sidecar per Claude session owns the session's harness turns
spec:cc-agents.sidecar · resolves
declaredNoneNone
refines · incomingA message reaches the running turn at once, and a stop ends the harness turn
spec:cc-agents.steering-and-stop · resolves
declaredNoneNone
refines · incomingA guard ends the groups a harness turn started and it has seen, even when the sidecar is killed
spec:cc-agents.work-containment · resolves
declaredNoneNone

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.