# DESIGN — parity model, deltas, and the maintenance contract This document is the reference for *how faithful* each tier is, *what we deliberately don't reproduce*, and *why the chosen seams keep parity cheap to maintain*. Everything here is grounded in analysis of the live Claude Desktop `app.asar` (spawn contract and gates first verified at build 1.12603.1; updated through the newest baseline in `baselines/` (see `baselines/desktop-*.json`; `cowork-harness sync --diff` adds the next one)) and the on-disk runtime state on macOS. > **Just want to pick a tier or write a scenario?** This doc is the *why*. For the *how*, start at the > [README](./README.md) (tiers, quick start) and [docs/](./docs/README.md) (scenario/session reference). > Read on for the parity model, the deliberate deltas, and the maintenance contract. ## Architecture at a glance ```mermaid flowchart TB SCN["scenario.yaml"] --> CLI SYNC["cowork-sync
reads live Desktop install + app.asar"] subgraph CLI["cowork-harness · TypeScript CLI"] direction TB BL["baseline loader
baselines/desktop-*.json
agent ver · mounts · egress allowlist"] RS["runtime selector → L0 / L1 / L2"] end SYNC -.->|derives| BL CLI -->|"spawns + speaks stream-json"| AGENT subgraph AGENT["Agent · claude -p · CLAUDE_CODE_IS_COWORK=1"] direction TB IO["--input-format / --output-format stream-json"] FS["cwd = /sessions/<id>
mnt/uploads · mnt/<folder-name> · plugins"] end AGENT -->|"decision control request
(tool · question · dialog · elicitation)"| DRV["AgentSession → Decider → Run
protocol seam · policy seam · turn loop + RunRecord"] AGENT -->|"outbound network"| EG["Egress proxy
default-deny · allowlist = synced vmAllowedDomains()"] ``` (README carries the same diagram in ASCII, since npm doesn't render Mermaid.) ## 1. What "real Cowork" actually is (and why scripting it is closed) Cowork runs a session in one of two lanes. This section describes the **local** lane — the Desktop app driving the agent on the user's own machine, with an **Apple Virtualization.framework microVM** as the sandbox — which is the lane this harness emulates. Where the agent LOOP runs inside that lane is a separate axis, and on the pinned baseline it is the host, not the VM: see "Which Cowork? — both are implemented" under [§6, Control protocol mapping](#6-control-protocol-mapping) below, which is authoritative over the sandbox-centric description here. The **remote** lane runs the agent in an Anthropic-hosted cloud container instead, and is the default for new sessions from 2026-07-07 (local stays available, and both are in active use). The lanes differ in how a file reaches the user, which is what changes skill behaviour: see [docs/fidelity-gaps.md](./docs/fidelity-gaps.md) → "File delivery" for the split and [docs/scenario.md](./docs/scenario.md)'s `lane:` key for holding a run to either contract. The local lane: - VM bundle: `~/Library/Application Support/Claude/vm_bundles/claudevm.bundle/` (`rootfs.img`, `sessiondata.img`, `efivars.fd`, `machineIdentifier`, `gvisorMacAddress`, `vmIP`); a warm pool at `vm_bundles/warm//`. - In-VM agent: `~/Library/Application Support/Claude/claude-code-vm//claude` (currently **2.1.246**, per `baselines/desktop-1.37937.1.json`, an **ELF aarch64** binary), spawned by the host **in cowork mode via the `CLAUDE_CODE_IS_COWORK=1` env var** — *not* a `--cowork` flag (that flag is plugin-scope and the staged agent rejects it; see the control-protocol note below). Each baseline records this ELF's `sha256` (`agentBinary.sha256`/`shaProvenance`), and the resolver integrity-checks the binary it's about to run against that hash by default (opt out `COWORK_HARNESS_VERIFY_AGENT_SHA=0`), so "the same pinned agent" is enforced, not just asserted. Old versions are re-downloadable + verifiable from the official release channel (see `docs/maintenance.md`). - Network: `vm_network_mode: "gvisor"`, egress through a userspace netstack with a **compiled domain allowlist**; off-list partners rejected (`partner rejected: entry not on compiled allowlist`). - Control plane: Electron renderer→main typed IPC on channels named `$eipc_message$__$_claude.web_$__$_`, every handler validating `event.senderFrame.url` against a trusted-origin allowlist. The session manager is `LocalAgentModeSessions` (80 methods: `start`, `sendMessage`, `setDraftSessionFolders`, `onToolPermissionRequest`, `respondToToolPermission`, `getTranscript`, `onEvent`, …), bridged to the renderer as `window.cowork`. **Why you can't script it:** the only in-context entry is the renderer, and remote debugging is closed on the shipping build — verified empirically (`--remote-debugging-port` opens no listener across clean trials) and structurally (Electron `EnableNodeCliInspectArguments` fuse OFF). Deep links don't create sessions; there's no host CLI entry (cowork mode is an in-guest env var, `CLAUDE_CODE_IS_COWORK=1` — not a `--cowork` flag; see §"Cowork mode is enabled by env" below). So we emulate the **contract**, not the app. ## 2. Parity matrix (per tier) > Rows below are the three **isolation tiers** (L0/L1/L2). The two **loop-mode** tiers — > `hostloop` (production split-execution) and `cowork` (auto-picks host-loop vs container) — > are overlays on these and are covered in §"Spawn contract + host-loop vs VM-loop" below > and the README tier table, not as separate columns here. > > **L0/L1/L2 are doc shorthand only** — the actual `fidelity:` values you write are `protocol` / > `container` / `microvm` (plus the `hostloop` / `cowork` overlays). You never write `L1`. | Aspect | Real Cowork | L0 protocol | L1 container | L2 microvm | |---|---|---|---|---| | Agent binary | staged `claude-code-vm/`, `CLAUDE_CODE_IS_COWORK=1` | host `claude` (may differ), run plain (control-loop only) | **pinned** ``, `CLAUDE_CODE_IS_COWORK=1` | pinned ``, `CLAUDE_CODE_IS_COWORK=1` | | CPU/OS | linux/arm64 guest | host OS | linux/arm64 container | linux/arm64 guest | | Mount layout | `/sessions//mnt/...` | cwd only (no mnt tree) | **full mnt tree** (bind) | **full mnt tree** | | Skill discovery | plugin mount, runtime | local dir | **plugin mount** | **plugin mount** | | Permission/question protocol | `can_use_tool` via IPC | `can_use_tool` stream-json | `can_use_tool` stream-json | `can_use_tool` stream-json | | Egress control | gVisor + allowlist | **none** | allowlist proxy (default-deny) | allowlist proxy (default-deny, guest iptables) | | Net transport | gVisor netstack | host | proxy (TCP/HTTP CONNECT) | proxy (TCP/HTTP CONNECT) | | Filesystem isolation | VM | process | **container** | **VM** | | Speed | — | fastest | fast | slow | | CI-friendly | — | yes | **yes** | no | **Rule of thumb:** test skill *logic + question handling* at L0; test skill *behavior under Cowork's mounts + egress* at L1; reach for L2 only when you need VM-grade escape isolation of untrusted code — L2's egress transport equals L1's (the same allowlist proxy), so it adds no network-transport fidelity. ## 3. Deliberate deltas (a green test still means something) | Delta | Why it's acceptable for skill testing | When it bites | |---|---|---| | No Apple VZ kernel | Skills are agent-loop + tool behavior; kernel-invisible | Skill probes `/proc`, kernel version, VM artifacts | | L1 and L2 egress is a proxy, not gVisor | Allow/deny is decided per domain against the pinned allowlist, which is what skills observe | Skill depends on raw-socket / non-HTTP egress behavior, or on a domain where the pinned list and production's server-delivered set differ | | No host-loop staging / mountPath RPC / bridge | Those are Desktop host services, not part of a portable skill | Skill calls a Desktop-only host RPC (non-portable by definition) | | Host `claude` at L0 may differ from pinned ver | L0 is the fast lane; use L1 for version-exact | Version-specific tool/flag behavior — pin via L1 | | Files mounted locally, not via `/v1/files` + `stage_file` | The skill only needs the file *present* at `mnt/uploads/`; it `Read`s the same path either way | Skill depends on the Files-API round-trip itself (id, gating) rather than file contents | | Sessions resumed via the agent's native `--resume` + work-dir reuse, not the cloud `/v1/sessions` event log / cross-session store | The agent reloads `messages` + `fileHistorySnapshots` + `deferredToolUse` from its own sessionFile — behaviorally identical for a gate round-trip | Skill reads the server-side session event stream or the cross-session document store directly | These are surfaced in the run report so a passing scenario is honest about which tier produced it. The file/persistence deltas are **local-fidelity by design** — see SPEC §4.3; the resume path is binary- verified (a fact set in run 1 is recalled after `--resume` in run 2). ## 4. The maintenance seam (why this survives releases) Parity rot happens when release-specific facts are hard-coded in logic. We isolate them: ``` STABLE (rarely changes; lives in code) - the stream-json control protocol (can_use_tool / hook_callback / mcp_message / ...) - the scenario schema and assertions - the runtime selector and proxy mechanism VOLATILE (changes per release; lives in baselines/*.json, sync-regenerated) - agentVersion - network.allowDomains + network.mode + requireFullVmSandbox - gates - asarFingerprint (provenance + "unknown delta" tripwire) HAND-AUTHORED (in baselines/*.json, drift-guarded — sync does NOT extract these) - mountLayout (mount modes) - spawn.env.CLAUDE_CODE_IS_COWORK + bgEnvStrip.knownVars (BG env-strip list) ``` The sync extractor (`src/sync/cowork-sync.ts`, driven by `cowork-harness sync`): 1. reads the live install (`claude-code-vm/.sdk-version`, `config.json`) and the `app.asar` main bundle, 2. re-derives every VOLATILE field, 3. computes an `asarFingerprint` over the cowork-relevant code regions, 4. emits `baselines/desktop-.json` and diffs against the committed one. If the fingerprint changes but no known field did, sync reports `unknown delta` — your signal that Anthropic moved something the extractor doesn't read yet. That converts silent parity rot into a visible, actionable diff. ### Per-release runbook ```bash cowork-harness sync --diff # review agent bump / allowlist change / mount change # extend src/sync/cowork-sync.ts if "unknown delta" is reported git add baselines/desktop-.json && git commit -m "parity: sync to Desktop " cowork-harness run examples/scenarios/ # regression: drift now shows as test diffs ``` ### Rootfs / image drift checks The agent *image* is a second fidelity surface (separate from the baseline facts above), and its drift is caught the same "silent rot → visible signal" way: - `scripts/capture-rootfs-manifest.ts --check ` diffs the **whole** Layer-A pip set — generated from `docker/Dockerfile.agent` rather than a hand-maintained subset, so a missing PDF/image package (pdf2image, pypdfium2, seaborn, …) fails the check instead of slipping through — plus the Node version, the apt document stack (`dpkg-query`), and global npm packages (`npm ls -g`). - `scripts/build-rootfs-image.ts` tags the imported image by a **content hash** of `rootfs.img` (not size+mtime), so an in-place content change can't reuse a stale cached image; the hash is printed in build output. - The image-capability probe cache keys on the image's **content** (id + created time), not a mutable tag — a rebuilt-in-place tag re-probes instead of serving stale capability facts. ## 5. Egress model details Real Cowork compiles `{kind:"allowlist", domains:[...vmAllowedDomains(), ...coworkEgressAllowedHosts]}` (or `{kind:"unrestricted"}` iff the set contains `"*"`). The default allowlist below is a **pinned, hand-curated reconstruction, not an extraction** — on the first-party deployment this harness models the VM egress allowlist is not in the app bundle at all (that deployment class returns `vmEgressPolicy(){return null}`, so the session's SERVER-DELIVERED `egressAllowedDomains` is used instead), which means it cannot be read out of the asar. It is the list the harness **enforces**; whether it equals production's server-delivered set is unverified, and four entries (`www.`, `console.`, `support.`, `docs.anthropic.com`) are flagged unverified-as-VM-egress in the baseline's own `network.$comment`. `sync` carries the list forward and never re-derives it: ``` api.anthropic.com a-api.anthropic.com a-cdn.anthropic.com api-staging.anthropic.com console.anthropic.com docs.anthropic.com mcp-proxy.anthropic.com support.anthropic.com www.anthropic.com *.claude.ai (assets / downloads / pivot / preview) sentry.io ``` L1 reproduces this as a **default-deny forward proxy**: the agent's `HTTP(S)_PROXY` points at it, and only allowlisted hosts (baseline + the session's `egress.extra_allow`) get `CONNECT`-through; everything else is refused and logged to `egress.log`. Scenario `expect_denied` asserts denials. This matches what a skill *observes* (a blocked host fails) even though the transport differs from gVisor. > Security note: the proxy is a **test fixture**, not a security boundary. Don't run untrusted skills against real credentials at L1 expecting VM-grade isolation; use L2 (real VM) for that. L1's job is faithful *behavioral* egress, not adversarial containment. ## 6. Control protocol mapping | Cowork (Desktop IPC) | Harness (stream-json control) | |---|---| | `onToolPermissionRequest` (subscribe) | inbound `can_use_tool` control_request | | `respondToToolPermission(allow/deny)` | `control_response` allow/deny | | AskUserQuestion answered by question UI | allow + `updatedInput = {questions, answers}` — BOTH keys required (Record) | | `onEvent` live stream | stream-json assistant/tool messages → `events.jsonl` | | `getTranscript` | accumulated stream → the `transcript` line in `run.jsonl` | | `setDraftSessionFolders` / `addFolderToSession` | bind-mount into `mnt/` before launch | The policy that produces those `allow`/`deny` responses is the **Decider** seam (see the architecture diagram); to smoke-test a decider against a sample question without a full run, use `cowork-harness decide`. > **Machine-readable form:** the five shapes below are schema'd as `schema/protocol.v1.json`, with a golden vector pack at `fixtures/protocol/v1/` — see [docs/protocol.md](./docs/protocol.md) for scope, versioning, and how to conformance-test against them. ### Control protocol — VERIFIED end-to-end against the live host CLI (macOS. The staged in-VM agent that L1/L2 run is **2.1.246**, the native host app that `hostloop` runs is **2.1.246**, baseline **`desktop-1.37937.1`** — a fresh live end-to-end pass across the `protocol`, `container`, and `hostloop` tiers was run against this baseline on 2026-08-26, superseding the prior `1.32885.1` pin. Scope and caveats of that pass are in the note directly below; read it before citing this heading.) The subsequent `desktop-1.20186.1` baseline is a patch-only Desktop release (egress allowlist, spawn config, and the Cowork system-prompt fingerprint unchanged from 1.20186.0; the staged VM ELF re-synced 2.1.202 → 2.1.205) — the live pass is deliberately not restamped onto it. > **Scope of that claim, stated plainly.** `2026-08-26 / desktop-1.37937.1` is the baseline carrying the latest **full live end-to-end pass**, and it is also the newest committed baseline — **no baselines have shipped since**, so nothing in `baselines/` is currently unverified for want of a live run. The pass ran against agent **2.1.246** (the staged VM ELF and the native `.app` are both at that version) and covered all three tiers: `protocol` (the matrix runner's own live e2e plus its unanswered-gate regression pin), `container` (the spawn contract against the staged binary, resume continuity across the container boundary, and the outputs-delete guard), and `hostloop` (the sub-agent relative-`Write` acceptance probe, resume continuity on the native binary, critique at the unpinned tier, uploads readability, sub-agent WebSearch capture, and the discovery-server declaration check). It was one invocation of `npm run test:live` — **4 suites, 19 assertions, 19 green / 0 skipped**. **Nothing was gated out**, which is the part worth stating: every `describe` in this lane is `skipIf`-gated on Docker, the staged-binary version and the token, so a gated case reports as SKIPPED rather than passing vacuously — vitest reported zero skips, and the 19 that ran are exactly the 19 the suite enumerates. **Scope-out, so this is not read as more than it is.** (a) The assertion population is 19 here against the 24 recorded for the 1.32885.1 pass; cases have been retired and consolidated since (the `live-outputs-delete` whole-line-`#`-comment case was retired in 1.25.0 after its pinned command stopped being executed by the model), so the two counts are not comparable and the drop is not coverage lost in this pass. (b) The `boundary-check` sandbox proof and the example-scenario suite were part of the 1.32885.1 stamp and were **NOT** run here — this paragraph claims `npm run test:live` only. (c) A live pass verifies observed behaviour, not the whole spawn contract by construction. **These suites are model-dependent, so a single red is evidence of model variance until a re-run says otherwise, not of a regression** — which is why the gated cases skip loudly rather than fail. Separately and not a live matter: the three committed example cassettes (`example-pdf-skill` at `container`, `example-multiselect-gate` at `protocol`, `hostloop-computer-links` at `hostloop`) were re-recorded against this baseline in the same change, so nothing in `examples/replays/` is stale against it. Re-stamp this paragraph, naming the baseline, whenever a live pass is actually re-run. > The staged agent ELF is unchanged (2.1.181) across the 1.14271.0→1.15200.0 asar bump, and 2.1.187 across the 1.15200.0→1.15962.0 bump. The live scenario suite (`protocol` + `container` tiers) was re-run against the 1.15200.0 baseline; the 1.15962.0 bump was verified via asar analysis (content byte-identical: host-loop generator, system prompt, identity string, gates, and egress domains all unchanged) plus a full local test suite pass. The 1.15962.1→1.17377.1 bump moved the staged agent to **2.1.197** and added `api.claude.ai` to the egress allowlist; re-verified via `sync` (no unknown deltas) plus a manual asar spot-check of the reconstructed prompt content (substantively unchanged — see the Parity entry in CHANGELOG.md) and a full live scenario-suite pass (`protocol` + `container` tiers). The handshake and shapes below were confirmed empirically with an end-to-end run, not inferred: 1. **Spawn flags:** `-p --verbose --input-format stream-json --output-format stream-json --permission-prompt-tool stdio`. The `stdio` permission-prompt-tool is what routes `can_use_tool`/AskUserQuestion to the driver; `--verbose` is required by `--output-format=stream-json --print`. 2. **Handshake:** the driver sends `{type:"control_request", request_id, request:{subtype:"initialize"}}` as the first message, then the user turn. Without it, permissions/questions are auto-handled (AskUserQuestion is silently dismissed). 3. **Inbound permission/question:** `{type:"control_request", request_id, request:{subtype:"can_use_tool", tool_name, input, tool_use_id}}`. For AskUserQuestion, `input.questions[] = {question, header, options:[{label,description}], multiSelect}`. 4. **Response envelope (nested!):** `{type:"control_response", response:{subtype:"success", request_id, response:{behavior:"allow", updatedInput} | {behavior:"deny", message}}}`. The payload sits under an **inner** `response`; missing that nesting yields `ZodError: expected object, received undefined`. 5. **AskUserQuestion answer:** allow with `updatedInput = {questions, answers}` — BOTH keys required (dropping `questions` breaks the binary's built-in `questions.map(...)` handler); `answers = Record` (the CLI's own schema is `z.record(z.string(), z.string())`). The model receives the answer and proceeds. > **Cowork mode is enabled by env, not a flag.** In the staged agent (2.1.197) `--cowork` is a *plugin-scope* flag ("can only be used with user scope") and is rejected by the agent invocation; cowork mode is entered via **`CLAUDE_CODE_IS_COWORK=1`**. (Do **not** also set `CLAUDE_CODE_USE_COWORK_PLUGINS` — Desktop doesn't, and it flips the agent's userSettings filename to `cowork_settings.json` and plugin cache to `cowork_plugins/` via `TSO()` — the minified Desktop helper that derives the cowork settings/cache paths; plugins are delivered via `--plugin-dir`.) The host CLI is a different (macOS) build, so L0 runs plain (control-loop validation only); L1/L2 run the staged **Linux/arm64** binary — bind-mounted from the user's own install. ### Spawn contract + host-loop vs VM-loop (binary-verified through asar 1.17377.1; asar analysis since carried through 1.20186.0 — the full spawn contract is byte-identical across the 1.18286.0→1.18286.2 bump, and behaviorally identical across the 1.18286.2→1.19367.0→1.20186.0 re-minifications: the value-resolved contract is unchanged and only minified symbol names + bundle layout moved (in 1.20186.0, hoisted helpers became namespace-method calls and const spreads became export aliases), re-verified via the structural anchors and the live-asar spawn-contract tests plus a 1.20186.0-shaped drift-guard fixture — the live end-to-end pass now covers `1.20186.0` too (see the "Control protocol" note above), superseding the prior `1.19367.0` pin) The full Desktop→agent spawn contract (cwd `/sessions/`, `CLAUDE_CONFIG_DIR=mnt/.claude`, the env object, `--tools`/`--allowedTools`/`--plugin-dir`/`--effort`/`--setting-sources`, permission layers, prompt templates) is documented in [docs/cowork-spawn-contract-1.12603.1.md](./docs/cowork-spawn-contract-1.12603.1.md) — historical, pinned to 1.12603.1 and not updated per release — and encoded in `baseline.spawn`, which is the live source of truth. **Which Cowork? — both are implemented.** Production runs **host-loop** (the host-loop GrowthBook gate `1143815894`, forced on per the decoded *fcache* — Desktop's on-disk GrowthBook feature-flag cache): the agent loop runs on the host, shell is `mcp__workspace__bash` into the VM, `${CLAUDE_PLUGIN_ROOT}` is a host path. VM-loop (gate off / `requireCoworkFullVmSandbox` orgs) runs the whole agent in the sandbox. - `fidelity: container | microvm` → **VM-loop** (the whole agent in the sandbox). - `fidelity: hostloop` → **host-loop**: the agent LOOP is a **native process spawned directly on the host** (Desktop stages this same native macOS binary alongside the Linux/arm64 ELF the other tiers use), with native Bash/WebFetch disabled (`--disallowedTools`) and the agent's shell routed through the **workspace SDK-MCP server** — declared via `sdkMcpServers:["workspace"]` in the `initialize` handshake, with the driver (`src/agent/session.ts` + `src/hostloop/workspace-handler.ts`) handling `mcp_message` JSON-RPC and executing `bash` via `docker exec` into a VM sidecar container (no agent runs inside it) at `/sessions//mnt`. `${CLAUDE_PLUGIN_ROOT}` for the native process points at the staged plugin copy directly (a real host path); bash's `docker exec` still gets an intentionally-unresolvable sentinel so it self-heals via `find /sessions//mnt …`, exactly like production. Connected folders are bind-mounted (never copied) into both the native process's view and the VM sidecar, so the native file tools and bash see the same bytes. With no container around the native file tools, a PreToolUse hook (`src/hostloop/pretooluse-path-hook.ts`, a byte-faithful port of production's own containment check) is the security boundary for real filesystem access — see [docs/boundary.md](./docs/boundary.md) for the full safety posture (writable-folder consent, the runtime tripwire). - `fidelity: cowork` → **auto-picks** host-loop vs VM-loop using Cowork's own decision logic (`src/loop-decision.ts`, an exact replica of Desktop's minified `f_()` loop-decision function): `requireFullVmSandbox ? vm : (dev override ? host : gate 1143815894)`. With the synced gate forced on, `cowork → hostloop`. (The replicated `f_()` **decision shape** is pinned to asar 1.12603.1 per `src/loop-decision.ts`; the 1.15200.0→1.15962.0 sync re-derives only the **gate value** it reads, not the logic.) The **bash-visible world is identical** in both (`/sessions//mnt/...`); the agent-loop world differs (`${CLAUDE_PLUGIN_ROOT}` resolution, the shell tool). Use `hostloop` (or `cowork`) for production-faithful skill testing; `container` for fast VM-loop.