# Authoritative spec — cowork-harness The single source of truth for **what the harness must produce** given its inputs. Golden snapshot tests assert the **contract layer** against this; live contract tests assert the **runtime layer** against the real binary. Anything that contradicts the binary wins over this doc — keep them in sync via `cowork-harness sync` + the [spawn contract](./docs/cowork-spawn-contract-1.12603.1.md) (historical, pinned to 1.12603.1 and not updated per release — live values are in `baseline.spawn` / `baselines/desktop-*.json`). > **Reading this for how-to?** This is the *contract* (envelopes, exit codes, assertion semantics). To > author a scenario or run the harness, start at the [README](./README.md) and [docs/](./docs/README.md); > come here when a doc and the code disagree. ## 0. Model ``` platform baseline (baselines/desktop-*.json) what Cowork's runtime IS this release (auto-synced) session setup (sessions/*.yaml) what the user set up pre-prompt (model, folders, plugins, …) scenario (scenarios/*.yaml | `skill` cmd) the prompt + scripted answers + assertions │ ▼ buildLaunchPlan(session, baseline) ──► LaunchPlan (pure data) │ decideLoop(baseline, overrides) ──► effective fidelity │ ┌─────────────────────┼───────────────────────────────────────┐ ▼ (pure: argv+env) ▼ ▼ contract layer runtime layer (stage fs, spawn, drive) egress sidecar ``` Two layers, tested differently: - **Contract layer** — pure functions of `(baseline, session, scenario, sessionId)`: the launch plan, the docker/limactl **argv + env**, the control-protocol **messages**, the loop **decision**, the **assertions**. Deterministic ⇒ golden snapshot tests (§7). - **Runtime layer** — fs staging, process spawn, the live agent. Needs Docker + a token ⇒ live contract tests (§8). ## 1. Loop decision (`src/loop-decision.ts`) — exact replica of Cowork `f_()` ``` decideLoop(i): if i.requireFullVmSandbox === true → "vm" # HeA() if i.devForceHostLoop === true → "host" # CLAUDE_FORCE_HOST_LOOP=1 + dev-approved return i.gateHostLoopOn ? "host" : "vm" # gate 1143815894 ``` `fidelity: cowork` ⇒ `decideLoopFromBaseline(baseline)` → `host`⇒`hostloop`, `vm`⇒`container`. Gate state from `baseline.provenance.gates["hostLoop:1143815894"]` (synced from `fcache`; currently `on(force)` ⇒ `cowork → hostloop`). Explicit `protocol|container|microvm|hostloop` bypass the decision. `execution` (scenario field, `src/types.ts`) is a separate axis, orthogonal to `fidelity` (a privilege/sandbox tier): `local` (default — run the agent locally) | `cloud-describe` (RESERVED — no runner exists yet; authoring it is a load-time error, not a silent no-op). ## 2. Launch plan (`buildLaunchPlan`) — pure Given a session + baseline, returns: | field | value | |---|---| | `configDir` | managed host dir (or `session.plugins.config_dir`); contains `settings.json`, `cowork_settings.json`, `skills/` | | `mounts[]` | `{hostPath, mountPath, mode}`, `mountPath` **relative to mnt**: `uploads/`, `` (work folders), `.local-plugins/marketplaces//` (marketplace-resolved), `.local-plugins/cache/` (direct `local_plugins`), `.remote-plugins/plugin_` (uploaded / org-remote; `id` is a stable hash of the DECLARED source, not a basename — two entries sharing a basename would collide). (≥1.14271.0; older baselines mount work folders at `.projects/`, which is now a reserved name.) | | `pluginDirs[]` | mnt-relative plugin roots → `--plugin-dir` (incl. marketplace-resolved plugins) | | `model/effort/extendedThinking/permissionMode/permissionParity` | from session | | `egressAllow[]` | `baseline.network.allowDomains` + `session.egress.extra_allow` (or `["*"]` if unrestricted) | **Marketplace resolution (required):** for each `local_marketplaces` dir, parse `.claude-plugin/marketplace.json`; for each `session.plugins.enabled` entry `name@mkt` matching `manifest.name`, resolve `manifest.plugins[name].source` → a `.local-plugins/marketplaces//` mount + pluginDir. This reproduces the real desktop spawn argv (`--plugin-dir …/marketplaces//`). (Cowork loads plugins via `--plugin-dir`; the registry is inert in-VM — §6.) ## 3. Spawn argv + env (contract layer) — what each tier MUST emit Resolved inputs: `sessionRoot=/sessions/`, `mntRoot=/sessions//mnt`, `configGuest=/sessions//mnt/.claude`. ### 3.1 Common agent args (container, microvm, and hostloop's native process) Hostloop's agent process is a NATIVE host spawn (§3.4), not a container occupant — it reuses this exact arg-building function (`baseAgentArgs`) but with **HOST paths** for the two guest-relative params (`mntRoot`/`mcpGuest` become real host paths to the staged mnt tree/mcp.json), and the argv is passed directly to `child_process.spawn(nativeBinary, args, …)` with **no leading `claude` token** (container/ microvm still prepend it for the `docker run … claude …`/`limactl … claude …` command form). ``` claude -p --verbose --input-format stream-json --output-format stream-json --permission-prompt-tool stdio --permission-mode --setting-sources user --effort # always emitted; medium fallback; per-model validated (--max-thinking-tokens 31999 | --thinking disabled) # session.extended_thinking on|off (default on) # debug.max_thinking_tokens → --max-thinking-tokens (fenced, non-Cowork) [--append-system-prompt ] [--model ] [--mcp-config /mcp.json] # if session.mcp.config set — HONORED in plain cowork mode (§6) (--plugin-dir /

)… # one per pluginDirs entry --tools # variadic, LAST --allowedTools # variadic, LAST ``` Variadic `--tools`/`--allowedTools` MUST be last (they consume to end-of-args). ### 3.2 Spawn env (container/microvm) Hostloop's native process does NOT use this env shape — see §3.4 for its own `hostNativeSpawnEnv` (deliberately different: real `HOME`, no forced `/tmp`, no HTTP(S)_PROXY). ``` # CLAUDE_CODE_IS_COWORK=1, ENTRYPOINT=local-agent, # DISABLE_BACKGROUND_TASKS=1, ENABLE_APPEND_SUBAGENT_PROMPT=1, … CLAUDE_CONFIG_DIR = # NO MAX_THINKING_TOKENS — real Cowork delivers the thinking budget via the CLI flag only (see §3.1), never an env var HOME = /tmp HTTP(S)_PROXY / http(s)_proxy = [TZ] [ANTHROPIC_API_KEY] [CLAUDE_CODE_OAUTH_TOKEN] # passthrough iff set in host env ``` MUST NOT set `CLAUDE_CODE_USE_COWORK_PLUGINS`. MUST NOT blanket-passthrough host `CLAUDE_*`. **Auth-env fidelity note (2026-06-13).** Real Cowork passes **only** the OAuth token: the desktop's VM-env builder `rtA()` sets `CLAUDE_CODE_OAUTH_TOKEN` and blanks `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_CUSTOM_HEADERS` to `""`, then `itA()` **deletes** each empty one — so the final env has the token and **no** API-key vars at all. **IMPLEMENTED** (`host-env.ts` `runtimeAuthEnv()`): when `CLAUDE_CODE_OAUTH_TOKEN` is present the harness mirrors the desktop and passes **only** the token, dropping `ANTHROPIC_API_KEY`; `ANTHROPIC_API_KEY` is forwarded **only** when there is no token (the CI/headless fallback the harness intentionally keeps). (`CLAUDE_CODE_EXECPATH` is the agent's *own* `process.execPath` — never forward a host value; covered by the "no blanket `CLAUDE_*`" rule above.) ### 3.3 L1 container (`spawnContainer`) ``` docker run --rm -i --platform linux/arm64 --network [--cap-drop ALL --security-opt no-new-privileges --read-only --tmpfs /tmp:… --pids-limit 1024] # lockdown -w /sessions/ -e …(§3.2) -v :/usr/local/bin/claude:ro -v :/sessions/ # writable session world cowork-agent-base:2 claude …(§3.1) ``` ### 3.4 host-loop (`spawnHostLoop`) — a NATIVE host process + a no-agent Docker VM sidecar Reproduces production's real host-loop architecture: the agent LOOP is a native macOS process spawned directly on the host (no container around its file tools), while `bash` routes into a Docker container that never runs an agent at all. `web_fetch` does **not**: it is host-routed (§6, and the `web_fetch` note in the SDK-servers section below), so it never crosses the container egress boundary. **The native process:** ``` child_process.spawn(, [ …§3.1 args, HOST paths … ], { cwd: /outputs, env: { ...process.env, ...hostNativeSpawnEnv(baseline, { configDir: plan.configDir, … }) }, }) ``` - `--disallowedTools Bash WebFetch NotebookEdit`; append `mcp__workspace__bash mcp__workspace__web_fetch` to `--tools`/`--allowedTools`. (The asar `HOST_LOOP_EXCLUDED_BUILTIN_TOOLS` = {Bash, NotebookEdit, REPL, JavaScript, WebFetch}; only Bash/NotebookEdit/WebFetch exist in the CLI agent's 26-tool registry — REPL/JavaScript are absent here.) - `CLAUDE_PLUGIN_ROOT` / `--plugin-dir` point at the STAGED plugin copy — a REAL host path (`join(mntHost, m.mountPath)`), the same directory the sidecar's bind mount below also targets. (2+ configured plugins keep an unresolvable sentinel for both consumers — a pre-existing per-plugin-hook scoping limitation.) - `cwd` = the harness-owned `/outputs` dir — this MUST equal the PreToolUse gate's `hostCwd` (below); a mismatch is cross-checked live via the hook payload's `input.cwd` and warned loudly, never silently trusted. - Connected folders are NEVER staged/copied for the native process — they're read directly at their real `Mount.hostPath` (bind-mounted into the sidecar too, so the native tools and `bash` see the same bytes). - system-prompt append includes the host-loop "Shell access" section (unchanged generator). - the driver declares `sdkMcpServers:["workspace"]` and handles `mcp_message` (§4, §5) — this is unchanged; the workspace MCP server still routes `bash` into the sidecar container regardless of who runs the agent loop (`web_fetch` is host-routed on both paths — see the `web_fetch` note below). - a `hooks` bundle (§4a) installs the PreToolUse path-containment gate alongside the always-on Task-bg-block hook. **The VM sidecar container** (`docker run`, `--name cowork-hl-` so the driver can `docker exec`): ``` docker run --rm -i --platform linux/arm64 --network [lockdown flags, same as §3.3] -w /sessions/ -e HTTP_PROXY/HTTPS_PROXY/http_proxy/https_proxy/NO_PROXY/no_proxy (the run's egress proxy — `docker exec` inherits container env, so this is bash's egress config at this tier; empty when there is no proxy. NO agent-env, and specifically NO CLAUDE_PLUGIN_ROOT: real host-loop leaves it unset in the guest and the agent self-heals by `find`ing the mount) -v :/sessions/ # outputs/uploads/staged plugins [-v /mnt/

:/sessions//mnt/

:ro]… # mode:r NON-folder mounts only -v :/sessions//mnt/[:ro]… # REAL folder paths — never copies -v /skills:/sessions//mnt/.claude/skills:ro -v /projects:/sessions//mnt/.claude/projects:ro cowork-agent-base:2 -v :/usr/local/bin/claude:ro (parity/inspection; nothing spawned runs it) sleep infinity # NO agent ARGV runs here ``` No `claude …` argv runs in this container — it exists solely as a `docker exec` target. The agent ELF **is** bind-mounted (`-v :/usr/local/bin/claude:ro`), for parity and inspection only: nothing the harness spawns executes it here, since the agent is the native host process. Read "no agent runs" as a statement about the argv, not about the bind. The full `.claude` dir is NOT bound wholesale (that shape is VM-loop only); this sidecar sees only `.claude/skills` + `.claude/projects`, matching production. `bash`'s exec cwd is `/sessions//mnt/` (production's real `vmCwd` semantics — never the bare session root or bare `mnt/`). **Caution for a future edit:** `mode:"r"` non-folder mounts get their `:ro` overlay from `readOnlyMountPaths`; `mode:"r"` FOLDER mounts get their `:ro` from the folder-bind line above instead — composing both for the same folder produces two `-v` flags at one destination, a Docker "duplicate mount point" hard failure. `readOnlyMountPaths` MUST exclude `kind:"folder"` mounts. ### 3.4a The PreToolUse path-containment gate (`src/hostloop/pretooluse-path-hook.ts`) With no container around the native file tools, this gate — a byte-faithful port of production's own inline PreToolUse hook body — is hostloop's ENTIRE security boundary for real filesystem access. Installed via the `hooks` seam (§4, a caller-supplied `HookBundle` merged onto the always-on `COWORK_PRETOOLUSE_HOOKS` in the `initialize` control_request). Denies any `Read`/`Write`/`Edit`/`Glob`/ `Grep`/`MultiEdit` whose resolved path falls outside the session's allowed roots (outputs, uploads, spooled projects, skills, writable connected folders, the staged plugin copy). Three of those roots are READ-ONLY categories, not a blanket allow: a mutating call into `uploads` (hardlink write-block — per-session-type text), the spooled-projects dir, or the staged skills/plugin copies (no exemption for plugin content anymore) is denied with that category's own message while remaining readable. A `/sessions/...`-shaped path is denied with a distinct "is a VM path, use bash" message. A run-end runtime tripwire (`execute.ts`'s `findUngatedPathToolCalls` / `chat.ts`'s inline `tripwireHook`) hard-fails the run/session if a gated tool call ever completes successfully with no evidence the gate fired for it — version-skew insurance, not doubt about the currently-pinned binary. A `hostloop` scenario with a WRITABLE connected folder requires the top-level `allow_host_writes: true` scenario field (or `--allow-host-writes` for `chat`) — `checkHostLoopWriteConsent` refuses to spawn otherwise. Read-only folders and folder-less/scratch hostloop runs need no opt-in. ### 3.5 L2 microvm (`spawnMicroVm`) `limactl shell sh -c 'set -e; cd /sessions/ 2>/dev/null || { echo "" >&2; exit 1; }; while IFS= read -r __cs; do [ "$__cs" = "__COWORK_SECRETS_END__" ] && break; export "$__cs"; done; exec "$@"' _ env claude …(§3.1)`. The work root (`VM_WORK_HOST`) is mounted **directly at `/sessions`** (not `/cowork-work` + a per-run symlink), so `/sessions/` is a real dir — `getcwd()` = `/sessions/` (§9), the encoded-cwd matches the container tier, and `CLAUDE_CONFIG_DIR` is a writable host-mounted path so the agent persists its session (enabling `--resume`). `set -e` + the explicit `cd` guard make a missing mount FAIL LOUD (a stale/un-provisioned VM) instead of silently exec'ing with the wrong cwd. `` is **hash-derived** (`cowork-vm-`): a config change (mounts/image/provision/agent-version) yields a new name ⇒ a fresh VM, so a stale-config VM is never silently reused (no drift). Egress: host proxy at `192.168.5.2:` + guest default-deny iptables. **Secrets: the auth token rides a stdin PROLOGUE** (one `KEY=value` per line up to the `__COWORK_SECRETS_END__` sentinel; the shell `read`s + `export`s them, then `exec`s `claude` with stdin positioned at the control stream) — off the host argv (`ps`/`limactl`) AND off disk. Non-secret env still rides argv via `env `. ### 3.6 L0 protocol (`spawnProtocol`) Host `claude` (NO `--cowork`, NO cowork env), `cwd = work/`, mounts flattened under `work/`. Control-loop validation only. ## 4. Control protocol (`src/agent/session.ts` — `LiveAgentSession`) The protocol seam is `LiveAgentSession` (the old monolithic `src/control/controller.ts` was split into the three seams `AgentSession` (`src/agent/session.ts`) / `Decider` (`src/decide/decider.ts`) / `Run` (`src/run/run.ts`)). Golden snapshots are built by the shared envelope builders in `src/run/envelope.ts`. 1. Driver → CLI **first**: `{type:"control_request", request_id:"init-1", request:{subtype:"initialize", [appendSubagentSystemPrompt], [sdkMcpServers], hooks:{PreToolUse:[…]}}}`. `hooks.PreToolUse` always includes the Task-`run_in_background`-block entry; a caller-supplied `HookBundle` (opts.hooks — hostloop's path-containment gate, §3.4a) appends its own matcher/callback-id, never replacing the built-in one. A `hook_callback` control_request for an id the driver doesn't recognize as a built-in is dispatched to the bundle's `handle()`; a throw there is treated as `{decision:"block"}` (fail-closed), never silently allowed. 2. Driver → CLI: the user turn (`sendUserTurn`; multi-turn capable). 3. CLI → driver `can_use_tool` / `request_user_dialog` / `elicitation` → `Decider` replies (§5); `request_user_dialog` has a ~6 s auto-cancel. 4. CLI → driver `mcp_message` (host-loop) → driver replies `mcp_response` (§5); both directions recorded (`events.jsonl` + `control-out.jsonl`). 5. CLI → driver `result` → `Run` pulls the next turn, or `close()` ends stdin. ### 4.1 `events.jsonl` schema (what `parseMessage` reads; `trace` digests) Each line is one stream-json message. The message types that carry signal: - `{type:"system", subtype:"init", tools:[…], mcp_servers:[…], cwd}` — the registry + cwd. - `{type:"assistant", parent_tool_use_id?, message:{content:[…]}}` — content blocks are `{type:"text"}`, `{type:"thinking"}`, or `{type:"tool_use", id, name, input}`. A non-null `parent_tool_use_id` means the block ran **inside a sub-agent**. - `{type:"control_request", request_id, request:{subtype}}` — `can_use_tool` (→ permission, or question when `tool_name==="AskUserQuestion"`), `request_user_dialog`, `elicitation`/`side_question`, `mcp_message`. - `{type:"result", is_error, usage}` — turn end. **Sub-agent dispatch recognition (binary fact):** the real cowork dispatch tool is **`Agent`** (agent ELF 2.1.197 as of baseline desktop-1.18286.0: `{name:"Agent", aliases:["Task"], description:"Launch a new agent", inputSchema:{description, subagent_type, prompt}}`). `parseMessage` synthesizes a `subagent_dispatch` for a `tool_use` whose `name` is `Agent` **or** `Task` (the alias) **or** whose `input` carries `subagent_type`. The cowork **`TaskCreate`/`TaskUpdate`** tools are the *todo list* (`{subject, description, activeForm}` / `{taskId, status}`) and **`Monitor`** is a command watcher — none carry `subagent_type`, so they are NOT dispatches. `subagent_declared_but_unused` needs a declared tools list, which the `Agent` tool does not provide → inert on the cowork path (legacy-`Task` only). ### 4.2 Deciders (the terminal of the chain: scripted → parity → terminal) The chain `Chain(ScriptedDecider, PermissionDefaultDecider, terminal)` resolves each `decision` event; the terminal is one of: - **`FailDecider`/`FirstOptionDecider`/`PromptDecider`** — `--on-unanswered fail|first|prompt`. - **`LlmDecider`** (CLI `--decider-llm [--intent "…"]`; scenario YAML `on_unanswered: llm`) — per question, the answering model (host `claude -p`; defaults to Sonnet, override via `--decider-model` / `COWORK_HARNESS_DECIDER_MODEL`) picks a label; out-of-set → `UnansweredError` (loud, no `coerceLabel` fallback). Transport is `claude -p` not a direct `/v1/messages` (the harness process is not behind the egress proxy); a transient non-zero exit is bounded-retried (`COWORK_HARNESS_LLM_RETRIES`, default 2, clamped 0–10; timeout/byte-overflow/spawn-failure are not retried) and the exit error carries the child's stdout/stderr so the failure is diagnosable. The run is flagged `nonDeterministic`. - **`ExternalDecider`** over a `DecisionChannel` (`src/decide/external-channel.ts`) — two transports of the SAME wire protocol: **spawn** (`--decider-cmd ''` → a `shell:true` helper) and **file rendezvous** (`--decider-dir

` → `req-N.json`/`resp-N.json`). For each unscripted decision it emits `{type:"decision_request", id, runId, kind, …payload, context, reply_with}` (secret-scrubbed before write — `0600` files for the dir; the helper's own pipe for spawn) and reads one reply; answers are coerced via `coerceLabel(raw, labels, enableFirstShorthand)`. **CB-1:** `ExternalDecider` calls `coerceLabel` with `enableFirstShorthand=false` — a helper returning the literal string `"first"` must match an actual label named `"first"`; it is NOT silently coerced to option 1. (The `"first"` shorthand remains active at its default `true` for internal deciders only.) EOF / invalid JSON / wrong-`id` / timeout → `UnansweredError` (exit 2). A question that reaches the terminal unanswered (`ABSTAIN`) **throws** — never a silent option-1 (`run.ts`). Both external channels keep the CLI's stdout FREE (the protocol is on the helper's own pipes / in files), so both compose with `--output-format json` (no terminal `{type:"result"}` line). The legacy **stdio** channel (`--on-unanswered external`) — which seized the CLI's own stdout/stdin as a JSONL stream — was **removed**; `--decider-dir` subsumes it without owning stdout (passing it now fails loud at `resolvePolicy` with a redirect). `--decider-dir` is flagged `nonDeterministic` (a driving agent answers). The harness owns its transport: `cowork-harness gates --follow` streams one JSON line per pending gate + a terminal `{"done":true}` (a `process.on("exit")` marker guarantees completion on any exit path), and `cowork-harness answer --gate --choose