SOURCE / docs/orchestration.mdAT / 2dbeaf1View on GitHub ↗History ↗

Orchestration, elastic execution and dynamic reasoning

Part of the Cobalt Cockpit documentation. This text was moved here from the root README when the README was restructured for v0.6.0; the wording is unchanged unless a sentence says otherwise. Overview: Swarm architecture.

The Sonnet-led profile has its own page: sonnet-led.md.

Orchestration#

Observation is the public default. With orchestration: false, Cockpit observes your existing Claude Code activity without enforcing model routing, subagent budgets, Fable blocking, or subscription-only authentication. The bundled explorer/researcher/worker/reviewer agent definitions use Sonnet 5.5; scout/utility use Haiku 5.5.

Set orchestration: true to enforce the Opus/Sonnet/Haiku policy, independent pool resource budgets, and explicit task ownership. Orchestration does not by itself block Fable outside routed work. blockFable is a separate opt-in. cobaltStrict is an optional stricter preset that also blocks Fable/external advisor selection and requires subscription-style authentication. These models must be available to your account; Cockpit cannot grant model access.

The strict preset takes precedence over individual enforcement switches. NobodyWho remains optional: Cockpit observes its local receipts if configured and does not install it. It sends the local router a request only in a session where you selected a router with /cockpit router.

Elastic execution#

Opus remains the single commander: architecture, planning, decomposition, integration, escalation decisions and final verification. Sonnet engineers substantial bounded changes and independent reviews. Haiku scouts repositories and processes extractive, repetitive work. Small or tightly coupled work stays in the main session.

The swarm tool records bounded assignments before spawning. Each assignment carries a task ID, parent, tier, semantic role, objective, scope, dependencies, resource ownership, read/write mode and spawn reason. Include the exact [task:ID] marker in the Agent description. Queued tasks wait for resource capacity; blocked tasks wait for dependencies; intersecting write scopes are serialized. Read-only scopes may overlap. Scoped agents use Read/Grep/Glob for inspection and Edit/Write for changes. Shell or custom tools require exclusive wildcard ownership, with one exception: read-only Git inspection. A task that owns named paths can run git diff, show, log, status, grep and ls-files on those paths (one plain command, options from a fixed list, revisions proved to be commits, an explicit -- and literal paths inside its scope); a wildcard read-only task keeps a wider set of safe Git inspection commands. In both cases the command that runs is rebuilt from its parsed words behind safe flags, and Claude Code's own permission rules still apply to it. The exact rules: implementation-v0.6.1.md. Path canonicalization fails conservatively to wildcard when unavailable. Resource budgets replace the old three-agent ceiling; AUTO provides backpressure rather than uncontrolled fan-out.

Each assignment also records the tier Cockpit's own route would suggest for it, read from the mode, the role's class, a named effort and the wave. It is advice: the commander's tier is the one admitted and spawned, the reply to assign names a differing suggestion, and /cockpit agents shows suggested, requested, admitted, spawned, completed and verified per tier. Nothing is spawned or re-tiered by it (how it is derived).

Run waves are reconnaissance → engineering → review → integration → verification. Waves are observable phases; they do not replace dependency checks. Haiku may escalate reasoning to Sonnet; Sonnet escalates ambiguity, architecture and high-risk changes to Opus. Handoffs preserve objectives, discoveries, evidence, unresolved questions, risk and next actions. Escalation is distinct from ordinary completion. Agents return concise conclusion/evidence/change/check/uncertainty artifacts; commanders verify claims independently.

/cockpit groups observed tiers, compresses pools larger than eight agents and reports task progress, queue, blockers, ownership conflicts and escalations. While a task is blocked, quiet (the swarm's stalled mark: no activity observed for the threshold) or escalated, the HUD adds one static line, SWARM: 2 BLOCKED · 1 QUIET 5m+ · 1 ESCALATED · /cockpit agents, read from the Ledger the render already holds; with none of those there is no line (details). The Activity Field retains its crawler/spine identity and aggregates utility pools. The Run Ledger and replay explain assignment, spawn reason, wave, completion, escalation and verification. Escalated results remain unresolved after their host stops; the commander uses swarm resolve with evidence before dependent work can proceed. Queued dispatch stays under the commander through Agent, rather than automatic spawn loops. Active cancellation suppresses further model/tool actions and retains ownership until host termination is observed (the host exposes no stop API). For a running pre-v0.2 agent with unknown ownership, the commander explicitly assigns its scope then uses swarm adopt with the observed agent_id; until then further agent tool effects are held. Older ledgers default to an empty swarm; unavailable telemetry stays unknown. NobodyWho boundaries remain read-only.

output

Opus 5.5          — commander / integration / final verification, at your /effort
  ├─ Sonnet 5.5     — 0..N bounded engineering and review, effort per task
  └─ Haiku 5.5      — 0..N scouts and utility work, effort per task
       escalation → Sonnet → Opus
Cobalt Cockpit — ownership / waves / backpressure / HUD / ledger / replay
NobodyWho     — local Decision / Pruning / read-only control telemetry

Dynamic reasoning#

Model selection and effort selection are separate decisions. The 5.5 tiers still command, engineer and scout. You control the main Opus loop's effort; Cockpit manages the subagents', per task rather than fixed per tier.

AUTO (default) names a level from the task: extractive inventories, classification and summaries run light; normal feature work, bug fixes and refactors run medium; complex debugging, concurrency, migrations, security analysis and high-risk architectural reasoning run high or xhigh; unusually difficult high-stakes reasoning may use max. A task that names no class falls back to its tier's baseline.
A commander can name a level explicitly per assignment with the swarm tool's effort field (LOW / MEDIUM / HIGH / XHIGH / MAX, or AUTO). A named level wins AUTO. MANUAL mode instead honours the fixed per-tier levels and leaves Haiku unspecified.
A task's level is requested, not guaranteed. The operator's maxEffort cap applies to subagents, and the host can apply its own limits. The Ledger distinguishes the requested level from the engine-resolved level and names a mismatch (EFFORT FALLBACK). This is host-resolution evidence, not an independently captured wire receipt. Unknown stays unknown.
A subagent's level is set natively, on its own Agent call's effort parameter (Claude Code 2.1.292 or newer): one level per invocation, with no global setting for parallel agents to race on. It overrides the agent definition's effort frontmatter and a per-model effortLevel for that subagent only. The engine's own limits still win — maxEffortLevel, an organization's cap, CLAUDE_CODE_EFFORT_LEVEL and the model's support — and the level the engine resolves is what the ledger records as applied. When that is not the level asked for, the difference is named with both levels; it is never rewritten back.
The main loop's effort is never written by Cockpit. A turn.step rewrite sits above everything in the engine's order (rewrite, then CLAUDE_CODE_EFFORT_LEVEL, then a session level from /effort, --effort or the model picker, then the settings' effortLevel, then the model's default, all under maxEffortLevel), and most of those cannot be seen from a plugin, so there is no way to offer a level beneath your own choice. The level the engine resolved is sent untouched and recorded as engine, with what was seen of its origin: the variable, a /effort typed this session, the settings, or host when none of those accounts for it. A cap that lowered your selection is named with both levels. AUTO and MANUAL, the maxEffort ceiling and every subagent launch leave it alone. With no selection of your own the main loop runs at the host's default for the model, which is not necessarily the level AUTO would name: /cockpit version then says what AUTO would name, as advice, and /effort <level> sets it.
A subagent on an older engine, or one that no Agent call launched, gets its level from a per-request turn.step rewrite instead. The engine does not report that rewrite back, so there the ledger shows the level as requested (request), leaves observed unknown, and learns nothing about capability from the engine's reports.
A failing task escalates one step at a time: raise effort within the tier first, then move a tier (Haiku → Sonnet → Opus). It never jumps to the top and stops at the budget rather than retrying forever.

The HUD shows the applied effort beside the model; /cockpit version prints the reasoning mode, the ceiling, the main loop's host-resolved level and where it was seen to come from, how a subagent's level reaches the engine, and only the capability this session has really observed.