Inside the session, beside the controls.

OBSERVE / ENFORCE

Two postures. One permission check, and it is not Cockpit’s.

Sources: docs/orchestration.md, docs/sonnet-led.md, docs/configuration.md, SECURITY.md.

TEXT EQUIVALENT

The same map, in words

You · prompts · /cockpit · /config

The person at the terminal. Some decisions are yours alone. Type prompts and commands; choose options in /config or with claude plugin configure. The Stop guard’s and the alerts’ settings, and the guard and alert commands that acknowledge, label, silence, enroll, release, test, export or delete, are accepted only when typed by a person. Cockpit never takes those settings from a plugin or a model.

Claude Code · the host: model loop, permissions, Agent tool, plugin store

Claude Code runs the session, the model requests, the permission check, subagents and the plugin APIs Cockpit uses. Its controls stay in charge. Raises the events Cockpit’s hooks receive. Decides every tool call through its own permission rules, permission mode and dialog. Spawns subagents with the Agent tool and applies its own effort limits. Cockpit does not replace its permission controls or model controls.

Permission check · tool.check · Claude Code’s own

The host’s decision whether a tool call may run. Decides every call Cockpit lets through. Cockpit has no hook on it and asks no permission decision of its own. Nothing in the plugin approves a call.

Observing hooks · session · turn · tool · agent · usage

The hooks that watch: session and turn events, tool calls and results, agent spawns and endings, model usage and context readings. Turn observed events into task state, the HUD and the Run Ledger. Fingerprint the working tree while a goal check stands, through bounded read-only Git and stat processes. Hidden reasoning is never stored. Shell commands and tool arguments are not ledger fields.

Guards · tool.call · agent.offer/spawn · config.set · /model

Checks that run before Claude Code’s permission check and can only refuse a call or ask you about it. On by default: ask before genuinely destructive commands; keep AI attribution out of commits and ask before CLAUDE.md or AGENTS.md is created unasked. With orchestration: refuse agent spawns that admission does not allow. With blockFable or cobaltStrict: refuse /model and /advisor selections under that policy. A guard that fails refuses what it would have refused (fail-closed). Approve a call. Act as a sandbox: the guards are heuristic and cannot recognise every shell program or obfuscated command.

progress + swarm tools · mcp__cobalt-cockpit__progress · __swarm

The two tools the model reports through: milestones, gates, discovery and the goal check (progress); assignments, waves, results and verification (swarm). Record what the model reports, and refuse malformed or evidence-free claims (an alternative without a reason, ALIGNED without per-criterion evidence). With orchestration, swarm assignments are admitted by dependencies, capacity and ownership. A model that never calls the progress tool has no milestones and is never shown DONE. Cockpit cannot stop a claim of done made only in prose.

Admission and ownership · orchestration: true

The enforcing half of the swarm: the Opus/Sonnet/Haiku policy, pool budgets and explicit task ownership. Queue tasks for capacity, hold them for dependencies, serialise intersecting writers. Limit a scoped helper’s shell to read-only Git inspection of the paths it owns. Spawn agents on its own: queued dispatch stays with the commander.

Task state · in Claude Code’s session memory

The current task, milestones, gates, discovery, goal check, swarm tasks and HUD state. Lasts until the session ends or you run /clear, /resume or /branch; survives a plugin reload. It is not written to disk as such; the Ledger and checkpoints are.

HUD and panes · ui.render · AbovePrompt · Mission Control · Ledger

The band above the prompt, /cockpit Mission Control and the Run Ledger pane. Draw only observed state; reduced motion and narrow terminals are honoured. The dashboard makes no model calls.

Plugin store · Run Ledgers · prefs · alert and guard records

The key-value file Claude Code manages for the plugin, under its configuration directory. Up to eight bounded Run Ledgers, checkpoints, release-review and Stop-guard records, script enrollments, alert records, two preferences. No command erases it; deleting it is a manual step. Treat it as private.

Local telemetry · $XDG_STATE_HOME/cobalt-cockpit/telemetry/

On by default: bounded JSON-lines files of enumerations, booleans and numbers, 4 MiB and 13 months, read by /cockpit stats and /cockpit doctor. Set telemetry to false to stop writing it. No prompt, code, path, command, session id, model id or secret is stored, and nothing is uploaded.

Subagents · Haiku scouts · Sonnet engineers · Opus architect

Agents Claude Code spawns. Cockpit ships agent definitions (Sonnet explorer, researcher, worker, reviewer; Haiku scout, utility; the Opus architect for SONNET_LED). Observed in every mode; admitted, scoped and verified by the commander when orchestration is on. A reported result is not a verified one.

Model provider · the request Claude Code already sends

Where Claude Code sends model requests. Cockpit sends nothing of its own. Cockpit’s two prompt hooks add text to the request Claude Code already sends: the discipline, safety and policy sections, and one line of task status. That is the only route by which anything it observed reaches a model. No fetch, no model call, no MCP call of Cockpit’s own.

Decision router · optional · OFF in every new session

An optional per-session classifier that recommends a route for a new task. /cockpit router nobodywho asks the local router; /cockpit router jev asks the TypeSafe JEV API through your own router. Recommends; Cockpit’s deterministic rules judge every recommendation and decide. In JEV mode, sends only fixed-vocabulary task keywords and a size bucket, never prompt text. Start an agent, admit or skip an Opus consultation, or change a model, effort, permission, ownership rule or gate.

Notification channel · Claude Code’s own · guardAlerts

With owner alerts on, Cobalt Guard asks the host to write a terminal notification when a run needs a person. Report SENT when the host reports writing it; record-only mode sends nothing. No webhook, email or push. SENT never means someone saw it.