cowork-harness 0.1.0

package/baselines/desktop-1.12603.1.json

@@ -0,0 +1,140 @@
+{
+  "baselineVersion": 1,
+  "appVersion": "1.12603.1",
+  "agentVersion": "2.1.170",
+  "agentBinary": {
+    "stagedPath": "~/Library/Application Support/Claude/claude-code-vm/2.1.170/claude",
+    "format": "elf-aarch64",
+    "$comment": "There is NO npm path — the Linux/arm64 ELF is bind-mounted from this staged Desktop install (or COWORK_AGENT_BINARY). npmPackage/preferReuseStaged removed (Q1)."
+  },
+  "guest": {
+    "os": "linux",
+    "arch": "arm64",
+    "baseImage": "ubuntu:22.04"
+  },
+  "spawn": {
+    "$comment": "Binary-verified Desktop->agent spawn contract (asar 1.12603.1). See docs/cowork-spawn-contract-1.12603.1.md.",
+    "configDirInGuest": "mnt/.claude",
+    "settingSources": ["user"],
+    "permissionMode": "default",
+    "maxThinkingTokens": 31999,
+    "effortDefault": "medium",
+    "tools": ["Task","Bash","Glob","Grep","Read","Edit","Write","NotebookEdit","WebFetch","TaskCreate","TaskUpdate","TaskGet","TaskList","TaskStop","WebSearch","Skill","REPL","JavaScript","AskUserQuestion","ToolSearch"],
+    "allowedTools": ["Task","Bash","Glob","Grep","Read","Edit","Write","NotebookEdit","WebFetch","TaskCreate","TaskUpdate","TaskGet","TaskList","TaskStop","WebSearch","Skill","REPL","JavaScript","ToolSearch"],
+    "env": {
+      "CLAUDE_CODE_IS_COWORK": "1",
+      "CLAUDE_CODE_ENTRYPOINT": "local-agent",
+      "CLAUDE_CODE_TAGS": "lam_session_type:chat",
+      "CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST": "1",
+      "CLAUDE_CODE_ENABLE_ASK_USER_QUESTION_TOOL": "true",
+      "CLAUDE_CODE_DISABLE_CRON": "1",
+      "CLAUDE_CODE_DISABLE_BACKGROUND_TASKS": "1",
+      "CLAUDE_CODE_DISABLE_AGENTS_FLEET": "1",
+      "CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT": "1",
+      "CLAUDE_CODE_ENABLE_TASKS": "true",
+      "CLAUDE_CODE_DISABLE_TERMINAL_TITLE": "1",
+      "ENABLE_PROMPT_CACHING_1H": "1",
+      "DISABLE_MICROCOMPACT": "1",
+      "MCP_CONNECTION_NONBLOCKING": "true"
+    },
+    "$comment_notSet": "Deliberately NOT set: CLAUDE_CODE_USE_COWORK_PLUGINS (Desktop never sets it; would flip the agent to cowork_settings.json/cowork_plugins). Host-derived (TZ, account UUIDs, WORKSPACE_HOST_PATHS, OTEL) injected at runtime, not pinned.",
+    "promptTemplate": "prompts/desktop-1.12603.1/system-prompt-append.md",
+    "subagentAppend": "prompts/desktop-1.12603.1/subagent-append-vm.md",
+    "$comment_prompts": "Reconstructed cowork-specific sections (not the full base prompt — not cleanly extractable). The main append is delivered via the --append-system-prompt CLI flag (layered on the agent's built-in base prompt), NOT the initialize handshake; only the subagent append goes over initialize (appendSubagentSystemPrompt), gated on CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT."
+  },
+  "mountLayout": {
+    "sessionRoot": "/sessions/{sessionId}",
+    "cwd": "/sessions/{sessionId}",
+    "mntRoot": "/sessions/{sessionId}/mnt",
+    "$comment_modes": "Mount modes are binary-verified against app.asar 1.12603.1: uploads = 'ro' (read-only); outputs + projects(.projects/<id>) default to 'rw' (delete DENIED) via IX(name,approvedSet,bypass) — they become 'rwd' (delete enabled) ONLY when the mount is in the session's fileDeleteApprovedMounts (toggled by the always-ask allow_cowork_file_delete tool); local/remote-plugins = 'r'. Vocabulary: 'r'=read-only (asar 'ro'), 'rw'=write-no-delete, 'rwd'=write+delete. These are the DEFAULT (unapproved) modes. NOTE: descriptive today (resolveMounts does not enforce them) — the faithful enforcement is deferred sub-project #9-A.",
+    "mounts": [
+      {
+        "name": "uploads",
+        "mountPath": "uploads",
+        "mode": "r",
+        "purpose": "user-uploaded files (read-only — asar 'ro')"
+      },
+      {
+        "name": "projects",
+        "mountPath": ".projects/{projectId}",
+        "mode": "rw",
+        "purpose": "selected work folders (a Space) — delete denied by default (asar IX)"
+      },
+      {
+        "name": "local-plugins",
+        "mountPath": ".local-plugins/cache",
+        "mode": "r",
+        "purpose": "marketplace skills/plugins, runtime-discovered"
+      },
+      {
+        "name": "remote-plugins",
+        "mountPath": ".remote-plugins",
+        "mode": "r",
+        "purpose": "org-remote plugins, runtime-discovered"
+      },
+      {
+        "name": "outputs",
+        "mountPath": "outputs",
+        "mode": "rw",
+        "purpose": "session outputs/artifacts — delete denied by default (asar IX); rwd only when approved"
+      }
+    ]
+  },
+  "network": {
+    "mode": "gvisor",
+    "allowKind": "allowlist",
+    "allowDomains": [
+      "sentry.io",
+      "preview.claude.ai",
+      "downloads.claude.ai",
+      "api.anthropic.com",
+      "a-cdn.anthropic.com",
+      "a-api.anthropic.com",
+      "console.anthropic.com",
+      "api-staging.anthropic.com",
+      "docs.anthropic.com",
+      "mcp-proxy.anthropic.com",
+      "pivot.claude.ai",
+      "support.anthropic.com",
+      "assets.claude.ai"
+    ]
+  },
+  "bgEnvStrip": {
+    "knownVars": [
+      "CLAUDE_CODE_OAUTH_TOKEN",
+      "CLAUDE_CODE_SESSION_KIND",
+      "CLAUDE_CODE_SESSION_ID",
+      "CLAUDE_CODE_SESSION_NAME",
+      "CLAUDE_CODE_SESSION_LOG"
+    ]
+  },
+  "$comment": "Platform baseline auto-derived by `cowork-harness sync` from a live Claude Desktop install + app.asar. VOLATILE per-release facts only. Regenerate per release; review the diff. Captured 2026-06-12 on macOS arm64.",
+  "capturedAt": "2026-06-12",
+  "platform": "darwin-arm64",
+  "settings": {
+    "autoMountFolders": {
+      "key": "autoMountFolders",
+      "default": false
+    },
+    "localAgentModeTrustedFolders": {
+      "key": "localAgentModeTrustedFolders",
+      "default": []
+    }
+  },
+  "provenance": {
+    "asarPath": "/Applications/Claude.app/Contents/Resources/app.asar",
+    "asarFingerprint": "887a3ce86bf07c7f",
+    "gates": {
+      "hostLoop:1143815894": "on(force)",
+      "taskDispatchLimiter:1648655587": "on(force) perTask=1 global=3 (host-side SKIP: recordSkipAndEmit/GCA.PerTaskLimit — NOT queue/deny). A dispatch session launches <=1 sub-task; <=3 concurrent globally.",
+      "coworkRuntimeConfig:1978029737": "on(force) coworkWebFetchViaApi=true coworkWebFetchPrompt=true workspaceBashWaitLonger=true sessionsBridgePollBlockMs=30 — web_fetch is host/API-routed (POST /api/organizations/<org>/cowork/web_fetch), NOT container egress; gated by a separate web-fetch hostname allowlist + URL provenance.",
+      "bridgeSdkTransport:583857784": "on(force) — Cowork uses the SDK-based transport (control protocol), confirming the harness's sdkMcpServers/mcp_message path is the production transport.",
+      "pluginSyncSparkplug:2340532315": "on(force) — startup syncPlugins(); plugins load via --plugin-dir (registry inert in-VM).",
+      "cliPlugin:2307090146": "off(default) — the CLI-plugin credential broker is dark-launched off for standard interactive accounts (Ch23/L106).",
+      "$comment": "Production GrowthBook gate states decoded from ~/Library/Application Support/Claude/fcache (standard interactive Anthropic account, 2026-06-13; binary-verified app.asar 1.12603.1). Pin per release. Behavior-affecting gates the harness models: 1143815894 (loop), 1648655587 (dispatch cap), 1978029737 (web_fetch routing). Telemetry/auth-internal gates omitted."
+    },
+    "eipcChannelUuid": "4f426349-8d6f-45f3-ae22-280fef323564",
+    "$comment": "eipcChannelUuid is per-build; recorded for provenance only — the harness does not use Desktop IPC."
+  },
+  "requireFullVmSandbox": null
+}

package/baselines/prompts/desktop-1.12603.1/host-loop-append.md

@@ -0,0 +1,8 @@
+<!-- host-loop "Shell access" section, reconstructed verbatim from the asar (D8r host
+     branch). Appended to the system prompt only in host-loop. {{vmMnt}} substituted. -->
+
+## Shell access
+
+Shell commands use `mcp__workspace__bash` and run in an isolated Linux environment. Each call is independent — no cwd or env carryover between calls. Use absolute paths.
+
+Paths in bash differ from what file tools (Read/Write/Edit) see. Your connected folders are mounted in bash under {{vmMnt}}/. A file you Read at a host path is reached in bash under {{vmMnt}}/ — translate host paths to their {{vmMnt}} equivalent before using them in bash. In particular, `${CLAUDE_PLUGIN_ROOT}` is a host path; to run a plugin's scripts in bash, locate them under {{vmMnt}} (e.g. `find {{vmMnt}} -path '*/skills/*/scripts'`) rather than using the host path directly.

package/baselines/prompts/desktop-1.12603.1/subagent-append-vm.md

@@ -0,0 +1,3 @@
+## Cowork environment
+
+You are running as a subagent inside a Cowork session. Shell commands execute in an isolated Linux sandbox rooted at {{cwd}} — files created there (or under /tmp) exist only in the sandbox and are not visible to the user unless written to the outputs directory. User-attached folders are mounted under {{cwd}}/mnt/.

package/baselines/prompts/desktop-1.12603.1/system-prompt-append.md

@@ -0,0 +1,18 @@
+<!-- Reconstructed from verbatim asar fragments (build 1.12603.1). NOT the full base
+     prompt (which is assembled from many interpolated fragments and not cleanly
+     extractable) — only the cowork-specific sections that drive skill behavior.
+     Delivered via the `--append-system-prompt` CLI flag (layered on the agent's built-in
+     base prompt), NOT the initialize handshake. Only the subagent append goes over
+     `initialize` (appendSubagentSystemPrompt). Tokens substituted by src/prompt.ts
+     mirroring the Desktop builder `y8r`. -->
+
+<high_level_computer_use_explanation>
+Claude runs in a lightweight Linux VM (Ubuntu 22) on the user's computer. This VM provides a secure sandbox for executing code while allowing controlled access to user files. The working directory is {{cwd}}; user-attached folders are mounted under {{cwd}}/mnt/.
+</high_level_computer_use_explanation>
+
+<file_handling_rules>
+- The outputs directory ({{workspaceFolder}}) is where user-visible deliverables belong. Files written there are surfaced to the user; files written elsewhere in the sandbox are not.
+- Files in the outputs directory cannot be deleted (the operation is not permitted) — overwrite in place instead of delete-and-recreate.
+- Never expose absolute /sessions/ sandbox paths to the user; refer to files by their name or relative location.
+- Skills live under {{skillsDir}}/skills/. When a user request matches a skill, immediately Read the relevant SKILL.md and follow it.
+</file_handling_rules>

package/dist/agent/session.js

@@ -0,0 +1,465 @@
+import { createWriteStream } from "node:fs";
+import { join } from "node:path";
+import readline from "node:readline";
+// ---- Control-response envelopes (verified zod shape; the inner `response` nesting is load-bearing) ----
+/** The one success-envelope shape every control_response shares; the four builders below differ ONLY in
+ *  the inner `body`. Keeping a single core stops the wrapper drifting between them. */
+function successEnvelope(requestId, body) {
+    return { type: "control_response", response: { subtype: "success", request_id: requestId, response: body } };
+}
+export function allowEnvelope(requestId, updatedInput) {
+    return successEnvelope(requestId, { behavior: "allow", updatedInput });
+}
+export function denyEnvelope(requestId, message) {
+    return successEnvelope(requestId, { behavior: "deny", message });
+}
+export function mcpResponseEnvelope(requestId, payload, id) {
+    return successEnvelope(requestId, id !== undefined && id !== null ? { mcp_response: { jsonrpc: "2.0", id, ...payload } } : {});
+}
+const dialogEnvelope = successEnvelope;
+// ---- #8: PreToolUse hooks (the harness mirrors Cowork's host-installed hooks) ----
+// Binary-verified (app.asar 1.12603.1): in cowork mode the host installs a PreToolUse `Task` hook that
+// blocks `run_in_background` ("Background agents disabled"). Over the stream-json transport, `initialize`
+// declares `hooks: {PreToolUse:[{matcher, hookCallbackIds:[id]}]}`; when the hook fires the agent sends a
+// `control_request {subtype:"hook_callback", callback_id, input, tool_use_id}` and we reply with a
+// success control_response carrying the hook output ({decision:"block",…} or {} to allow). The hook is
+// evaluated in the agent loop → tier-uniform (container/microvm/host-loop) by construction.
+const TASK_BG_HOOK_ID = "cowork-task-bg-block";
+/** The PreToolUse hooks the harness installs in cowork mode (sent on `initialize`). */
+export const COWORK_PRETOOLUSE_HOOKS = { PreToolUse: [{ matcher: "Task", hookCallbackIds: [TASK_BG_HOOK_ID] }] };
+/** Pure output for a fired hook callback. Unknown ids → no-op (allow); the only installed hook blocks
+ *  `Task` with `run_in_background` to match Cowork's verbatim reason string. */
+export function hookOutput(callbackId, input) {
+    if (callbackId === TASK_BG_HOOK_ID && input?.tool_input?.run_in_background) {
+        return { decision: "block", reason: "Background agents disabled" };
+    }
+    return {};
+}
+/** The key the in-VM AskUserQuestion handler indexes answers by — it does
+ *  `questions.map(({question}) => answers[question])`, so the answer map MUST be keyed by `question`,
+ *  never `header`. (A header-only gate has an empty key; the run loop rejects it loud.) */
+export function questionKey(q) {
+    return q.question ?? "";
+}
+/** Human-readable label for records/traces/regex-matching — falls back to `header` for display only. */
+export function questionLabel(q) {
+    return q.question || q.header || "";
+}
+/** Serialize a DecisionResponse to the wire envelope for a given request. */
+export function serializeDecision(req, r) {
+    if (req.kind === "permission" && r.kind === "permission") {
+        // Off-wire pin: a web_fetch grant must never be serialized (web_fetch approval is host-synthesized and
+        // never hits the wire). If a grant-bearing permission reaches here, a refactor routed web_fetch through
+        // the protocol — fail loud rather than silently drop `grant`.
+        if (r.grant !== undefined)
+            throw new Error("serializeDecision: a web_fetch `grant` permission must not be serialized (it is off-wire by construction)");
+        return r.behavior === "allow"
+            ? allowEnvelope(req.id, r.updatedInput ?? req.input)
+            : denyEnvelope(req.id, r.message ?? "denied");
+    }
+    if (req.kind === "question" && r.kind === "question") {
+        // AskUserQuestion: the binary's BUILT-IN handler (enabled in cowork mode) executes with this
+        // updatedInput and does `questions.map(({question}) => answers[question])` to build the tool_result
+        // (ELF-verified: `mapToolResultToToolResultBlockParam`). So updatedInput MUST carry the full input —
+        // `questions` AND `answers`. Dropping `questions` → `undefined is not an object (evaluating 'q.map')`,
+        // the answer never reaches the model, and gate-steering silently no-ops (O7).
+        return allowEnvelope(req.id, { questions: req.questions, answers: r.answers });
+    }
+    if (req.kind === "dialog" && r.kind === "dialog") {
+        return dialogEnvelope(req.id, r.behavior === "ok" ? { behavior: "ok", choice: r.choice } : { behavior: "cancelled" });
+    }
+    if (req.kind === "elicit" && r.kind === "elicit") {
+        return dialogEnvelope(req.id, { action: r.action, ...(r.content !== undefined ? { content: r.content } : {}) });
+    }
+    // mismatched kinds → safe cancel/deny
+    return denyEnvelope(req.id, "decider returned a mismatched response kind");
+}
+// ---- Canonical-JSON comparator (for the O7 replay guard) ----
+/** Recursively sort object keys then JSON.stringify — normalises insertion-order differences so a
+ *  semantically-identical key reorder does NOT produce a false mismatch in the replay guard.
+ *  `undefined`-valued keys are dropped by stringify, so absent-vs-undefined still normalises. */
+export function canon(x) {
+    if (x === null || typeof x !== "object")
+        return JSON.stringify(x);
+    if (Array.isArray(x))
+        return "[" + x.map(canon).join(",") + "]";
+    const sorted = Object.keys(x)
+        .sort()
+        .reduce((acc, k) => {
+        const v = x[k];
+        if (v !== undefined)
+            acc[k] = v;
+        return acc;
+    }, {});
+    return ("{" +
+        Object.entries(sorted)
+            .map(([k, v]) => JSON.stringify(k) + ":" + canon(v))
+            .join(",") +
+        "}");
+}
+/** Declared inverse of `serializeDecision` — kept adjacent with a pinning comment.
+ *  Input = the `response.response` body from a recorded `control_response` success envelope.
+ *  Output = the `DecisionResponse` the live decider originally produced.
+ *  Keyed on the LIVE `req.kind` (not the body) to stay consistent with `serializeDecision`.
+ *
+ *  MUST NOT route through `serializeDecision` — that would make the O7 guard circular (the
+ *  re-serialize-and-compare check in CassetteAgentSession.respond() would always match). */
+export function deserializeDecision(req, body) {
+    if (req.kind === "permission") {
+        if (body.behavior === "deny") {
+            return { kind: "permission", behavior: "deny", message: String(body.message ?? "denied") };
+        }
+        // allow: recover updatedInput (may be req.input due to lossy default in serializeDecision:88)
+        if (body.behavior === "allow")
+            return { kind: "permission", behavior: "allow", updatedInput: body.updatedInput };
+        // Any OTHER permission body ({}, {behavior:"cancelled"}, garbage — a corrupt/truncated cassette) must
+        // NOT silently replay as allow. Map to a deny that will NOT re-serialize to the recorded body, so the
+        // O7 guard in respond() trips a loud replay_protocol_fidelity mismatch. Mirrors the elicit branch's
+        // known-action validation below (declared-inverse symmetry).
+        return { kind: "permission", behavior: "deny", message: "deserializeDecision: invalid permission behavior" };
+    }
+    if (req.kind === "question") {
+        // AskUserQuestion: body is { behavior:"allow", updatedInput:{ questions, answers } }
+        // We read `answers` back; `questions` was preserved in recording for the O7 guard.
+        const ui = (body.updatedInput ?? {});
+        return { kind: "question", answers: (ui.answers ?? {}) };
+    }
+    if (req.kind === "dialog") {
+        return {
+            kind: "dialog",
+            behavior: body.behavior === "ok" ? "ok" : "cancelled",
+            ...(body.behavior === "ok" && body.choice !== undefined ? { choice: body.choice } : {}),
+        };
+    }
+    if (req.kind === "elicit") {
+        // #22: validate against the known action set instead of an unchecked `as` cast. A recorded
+        // action that is missing or unrecognized (a corrupt/truncated cassette) maps to "decline" — a
+        // value that will NOT re-serialize back to the corrupt input, so the O7 guard in respond()
+        // trips a loud replay_protocol_fidelity mismatch rather than silently coercing. A valid
+        // "accept"/"cancel"/"decline" passes through and round-trips byte-identically.
+        const raw = body.action;
+        const action = raw === "accept" || raw === "cancel" ? raw : "decline";
+        return {
+            kind: "elicit",
+            action,
+            ...(body.content !== undefined ? { content: body.content } : {}),
+        };
+    }
+    // fallback: deny-like
+    return { kind: "permission", behavior: "deny", message: "deserializeDecision: unknown req kind" };
+}
+export class LiveAgentSession {
+    proc;
+    outDir;
+    events;
+    controlOut;
+    reqById = new Map();
+    sdkMcp;
+    initWritten = false;
+    /** Reject function set when proc emits an error — bridges the callback into the async generator.
+     *  Set before the generator loop starts; called at most once (the Promise settles once). */
+    rejectError;
+    constructor(proc, outDir) {
+        this.proc = proc;
+        this.outDir = outDir;
+        this.events = createWriteStream(join(outDir, "events.jsonl"), { flags: "a" });
+        this.controlOut = createWriteStream(join(outDir, "control-out.jsonl"), { flags: "a" });
+        const errLog = createWriteStream(join(outDir, "agent.stderr.log"), { flags: "a" });
+        this.proc.stderr.pipe(errLog);
+        // #15: attach stdin error listener once at construction so dead-child writes don't produce
+        // unhandled process errors. Routes to the same error path as spawn errors when possible.
+        this.proc.stdin.on("error", (e) => {
+            if (this.rejectError)
+                this.rejectError(e);
+            // else: the error fired before/after the generator — log it but don't throw
+            else
+                this.events.write(JSON.stringify({ _emu: "stdin_error", message: String(e) }) + "\n");
+        });
+    }
+    /**
+     * Write the `initialize` control_request (idempotent). #45: `Run.drive` calls this BEFORE the first
+     * `sendUserTurn` so the wire order matches the SPEC (initialize precedes the user turn); `start()`
+     * also calls it so a standalone `start()` (no prior `init`) still initializes. Guarded so the two
+     * call sites never double-write init-1.
+     */
+    init(opts = {}) {
+        if (this.initWritten)
+            return;
+        this.initWritten = true;
+        this.sdkMcp = opts.sdkMcp;
+        const initRequest = { subtype: "initialize" };
+        if (opts.subagentAppend)
+            initRequest.appendSubagentSystemPrompt = opts.subagentAppend;
+        if (opts.sdkMcp?.servers.length)
+            initRequest.sdkMcpServers = opts.sdkMcp.servers;
+        initRequest.hooks = COWORK_PRETOOLUSE_HOOKS; // #8: block Task run_in_background, mirroring cowork
+        this.write({ type: "control_request", request_id: "init-1", request: initRequest });
+    }
+    async *start(opts = {}) {
+        this.init(opts); // idempotent — a no-op if drive() already wrote init-1 before the first user turn
+        // #13: race-approach latch — `errorPromise` rejects when proc emits an error, which is
+        // outside the readline loop. We race each rl.next() against it so the generator yields a
+        // typed {type:"error"} event and terminates cleanly instead of silently blocking on stdout.
+        let errorPromise = new Promise((_res, rej) => (this.rejectError = rej));
+        // Also write the _emu entry for backwards-compat with any tooling that reads events.jsonl.
+        // #9: route the spawn error through `rejectError` (like the stdin handler) so the Promise.race
+        // below rejects and the generator yields a typed {type:"error"} event instead of hanging on
+        // stdout that will never arrive.
+        this.proc.on("error", (e) => {
+            this.events.write(JSON.stringify({ _emu: "spawn_error", message: String(e) }) + "\n");
+            if (this.rejectError)
+                this.rejectError(e instanceof Error ? e : new Error(String(e)));
+        });
+        const rl = readline.createInterface({ input: this.proc.stdout });
+        const iter = rl[Symbol.asyncIterator]();
+        try {
+            while (true) {
+                // Race the next readline item against a spawn/stdin error.
+                let next;
+                try {
+                    next = await Promise.race([iter.next(), errorPromise]);
+                }
+                catch (spawnErr) {
+                    // Error won the race — emit a typed error event and stop.
+                    const msg = spawnErr instanceof Error ? spawnErr.message : String(spawnErr);
+                    yield { type: "error", source: "spawn", message: msg };
+                    return;
+                }
+                if (next.done)
+                    break;
+                const line = next.value;
+                if (!line.trim())
+                    continue;
+                this.events.write(line + "\n");
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    yield { type: "raw", line };
+                    continue;
+                }
+                yield* this.translate(msg);
+            }
+        }
+        finally {
+            this.rejectError = undefined; // generator is done; stop routing errors here
+            // #46: AWAIT the stream flush before the generator resolves. executeScenario reads/scans/scrubs
+            // events.jsonl + control-out.jsonl immediately after `drive()` returns; a fire-and-forget end()
+            // races the final buffered writes. end(cb) fires the callback on 'finish' (fully flushed).
+            await Promise.all([
+                new Promise((res) => this.events.end(() => res())),
+                new Promise((res) => this.controlOut.end(() => res())),
+            ]);
+        }
+    }
+    async *translate(msg) {
+        // #8: a PreToolUse hook fired pre-dispatch (side-effecting, like mcp_message). Reply with the
+        // installed hook's output so the agent blocks/allows; a dropped reply would deadlock the agent.
+        if (msg.type === "control_request" && msg.request?.subtype === "hook_callback") {
+            this.write(successEnvelope(msg.request_id, hookOutput(msg.request.callback_id, msg.request.input)));
+            return;
+        }
+        // mcp_message is the only side-effecting branch (the driver computes + writes the response).
+        if (msg.type === "control_request" && msg.request?.subtype === "mcp_message") {
+            const server = msg.request.server_name;
+            const jr = msg.request.message ?? {};
+            if (this.sdkMcp) {
+                let out;
+                try {
+                    out = await this.sdkMcp.handle(server, jr); // #30: async (web_fetch may await an approval)
+                }
+                catch (e) {
+                    // A throw from handle() (e.g. a broken allow_if predicate in the decider) must NOT bypass the
+                    // reply — an unanswered mcp_message blocks the in-VM agent on the round-trip forever (deadlock).
+                    // Reply with a JSON-RPC error instead, mirroring the no-handler defense below.
+                    const message = e?.message ?? String(e);
+                    process.stderr.write(`::warning:: sdkMcp.handle threw for "${server}" — replying with a JSON-RPC error: ${message}\n`);
+                    out = { error: { code: -32603, message: `handler error: ${message}` } };
+                }
+                this.write(mcpResponseEnvelope(msg.request_id, out, jr.id));
+                // Echo the MCP round-trip as a SYNTHETIC tool_use for provenance/trace only. The real tool call
+                // also arrives as an assistant tool_use block (live-verified: mcp__workspace__bash co-occurs with
+                // this mcp_message), which is what gets counted — so this is marked synthetic and excluded from
+                // toolsCalled/toolCounts to avoid polluting them with a bogus `mcp__server__*` entry.
+                if (server)
+                    yield {
+                        type: "tool_use",
+                        name: jr.params?.name ? `mcp__${server}__${jr.params.name}` : `mcp__${server}__*`,
+                        input: jr.params ?? {},
+                        synthetic: true,
+                    };
+                return;
+            }
+            // #10: an mcp_message arrived but no sdkMcp handler is configured. Reply with a JSON-RPC error
+            // (well-formed via mcpResponseEnvelope) instead of silently dropping it — a dropped request
+            // leaves the in-VM agent waiting on the round-trip forever (protocol deadlock in host-loop mode).
+            process.stderr.write(`::warning:: mcp_message for server "${server}" arrived but no sdkMcp handler is configured — replying with a JSON-RPC error (would otherwise deadlock)\n`);
+            this.write(mcpResponseEnvelope(msg.request_id, { error: { code: -32601, message: "no sdkMcp handler configured" } }, jr.id));
+            return;
+        }
+        for (const ev of parseMessage(msg)) {
+            if (ev.type === "decision")
+                this.reqById.set(ev.request.id, ev.request);
+            yield ev;
+        }
+    }
+    sendUserTurn(text) {
+        this.write({ type: "user", message: { role: "user", content: [{ type: "text", text }] } });
+    }
+    respond(decisionId, r) {
+        const req = this.reqById.get(decisionId);
+        if (!req) {
+            // #13: an id with no matching request_id is a protocol drift. Writing a guessed envelope would
+            // be worse, but a silent return leaves the agent blocked until timeout (looks like a hang).
+            process.stderr.write(`::warning:: respond() for unknown decision id "${decisionId}" — no matching request_id was seen; the agent may block until timeout (protocol drift)\n`);
+            return;
+        }
+        // #14: serializeDecision returns a safe deny envelope on a kind mismatch (defense in depth). That
+        // deny goes to the agent silently today — surface it loudly so the run record can't read "answered"
+        // while the agent actually received a deny. (serializeDecision stays a pure declared inverse of
+        // deserializeDecision; the warning lives here in the caller, not in the pure function.)
+        if (req.kind !== r.kind)
+            process.stderr.write(`::warning:: decider returned kind "${r.kind}" for a "${req.kind}" request (id ${decisionId}) → sending a safe deny/cancel; the agent did NOT receive an answer\n`);
+        this.write(serializeDecision(req, r));
+    }
+    close() {
+        try {
+            this.proc.stdin.end();
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    write(obj) {
+        const line = JSON.stringify(obj);
+        // #54: the control protocol writes small single-line JSON frames, so stdin backpressure
+        // effectively never engages; we intentionally ignore the write() return / drain here. If frame
+        // sizes ever grow, revisit with a drain-aware queue (which would make write()/respond() async).
+        // #47: guard that assumption — a frame past the threshold warns loudly so the "revisit" trigger
+        // fires instead of silently risking partial buffering on a frame far larger than expected.
+        if (line.length > 256 * 1024)
+            process.stderr.write(`::warning:: control frame is ${line.length} bytes (> 256 KiB) — stdin backpressure may engage; revisit write() with a drain-aware queue\n`);
+        this.controlOut.write(line + "\n");
+        this.proc.stdin.write(line + "\n");
+    }
+}
+/** Pure translation of one parsed stream-json message → AgentEvents (no side-effects). Shared by
+ *  LiveAgentSession and CassetteAgentSession. mcp_message is handled by Live before this is called. */
+export function parseMessage(msg) {
+    const ev = [];
+    switch (msg.type) {
+        case "system":
+            if (msg.subtype === "init")
+                ev.push({ type: "init", tools: msg.tools ?? [], mcpServers: msg.mcp_servers ?? [], cwd: msg.cwd });
+            else if (msg.subtype === "api_metrics")
+                ev.push({ type: "metrics", data: msg });
+            else if (msg.subtype === "thinking")
+                ev.push({ type: "thinking", text: String(msg.content ?? "") });
+            break;
+        case "control_request": {
+            const dr = toDecisionRequest(msg);
+            if (dr)
+                ev.push({ type: "decision", request: dr });
+            break;
+        }
+        case "assistant": {
+            const parentToolUseId = msg.parent_tool_use_id ? String(msg.parent_tool_use_id) : undefined;
+            for (const block of msg.message?.content ?? []) {
+                if (block.type === "text")
+                    ev.push({ type: "assistant_text", text: block.text, parentToolUseId });
+                else if (block.type === "thinking")
+                    ev.push({ type: "thinking", text: block.thinking ?? block.text ?? "" });
+                else if (block.type === "tool_use") {
+                    ev.push({
+                        type: "tool_use",
+                        name: block.name,
+                        input: block.input,
+                        parentToolUseId,
+                        toolUseId: block.id ? String(block.id) : undefined,
+                    });
+                    // Sub-agent dispatch. The real cowork agent uses the `Agent` tool (`{description,
+                    // subagent_type, prompt}`); older/other surfaces use `Task`. We recognize either name, plus
+                    // any tool whose input carries `subagent_type` (rename-robust). Crucially we DON'T match the
+                    // cowork `TaskCreate`/`TaskUpdate` todo-list tools (`{subject, description, activeForm}` /
+                    // `{taskId, status}`) — they have no `subagent_type`, so they're excluded and never miscount.
+                    const inp = (block.input ?? {});
+                    if (block.name === "Agent" || block.name === "Task" || "subagent_type" in inp) {
+                        const declared = Array.isArray(inp.tools)
+                            ? inp.tools.map(String)
+                            : Array.isArray(inp.allowedTools)
+                                ? inp.allowedTools.map(String)
+                                : []; // the `Agent` tool declares no tools list → []; declared-but-unused is legacy-`Task`-only
+                        ev.push({
+                            type: "subagent_dispatch",
+                            toolUseId: String(block.id ?? ""),
+                            // Skills often dispatch with only {description, prompt} (no subagent_type) → agentType is
+                            // "unknown" but the description still identifies the dispatch (e.g. "TOP_DOWN market sizing").
+                            agentType: String(inp.subagent_type ?? inp.subagentType ?? "unknown"),
+                            declaredTools: declared,
+                            description: inp.description != null ? String(inp.description) : undefined,
+                        });
+                    }
+                }
+            }
+            break;
+        }
+        case "user":
+            // Tool OUTCOMES come back as `user` messages carrying tool_result blocks. We never parsed these
+            // before, so every tool result — including the AskUserQuestion `q.map` error — was invisible to the
+            // recorder/trace. Capture them for delivery verification + `trace --tools`/`--gates` (Part 2).
+            for (const block of msg.message?.content ?? []) {
+                if (block.type === "tool_result")
+                    ev.push({
+                        type: "tool_result",
+                        toolUseId: block.tool_use_id ? String(block.tool_use_id) : undefined,
+                        isError: !!block.is_error,
+                        text: toolResultText(block.content),
+                    });
+            }
+            break;
+        case "result":
+            ev.push({ type: "result", isError: !!msg.is_error, usage: msg.usage });
+            break;
+    }
+    return ev;
+}
+/** Flatten a tool_result `content` (a string, or an array of `{type:"text",text}` blocks) to a short string. */
+function toolResultText(content) {
+    if (typeof content === "string")
+        return content.slice(0, 500);
+    if (Array.isArray(content))
+        return content
+            .map((b) => (b && typeof b === "object" && "text" in b ? String(b.text) : ""))
+            .join(" ")
+            .slice(0, 500);
+    return "";
+}
+export function toDecisionRequest(msg) {
+    const sub = msg.request?.subtype;
+    const id = msg.request_id;
+    if (sub === "can_use_tool") {
+        const tool = msg.request.tool_name ?? "";
+        if (tool === "AskUserQuestion")
+            // Capture the `toolu_…` tool_use_id (distinct from the UUID request_id) to pair the gate with its
+            // tool_result later (amendment #1). The SDK puts it on the request envelope.
+            return {
+                id,
+                kind: "question",
+                questions: (msg.request.input?.questions ?? []),
+                toolUseId: msg.request.tool_use_id ? String(msg.request.tool_use_id) : undefined,
+            };
+        return { id, kind: "permission", tool, input: msg.request.input ?? {} };
+    }
+    if (sub === "request_user_dialog")
+        return { id, kind: "dialog", dialogKind: msg.request.dialogKind ?? msg.request.dialog_kind ?? "unknown", payload: msg.request.payload };
+    if (sub === "elicitation" || sub === "side_question")
+        return {
+            id,
+            kind: "elicit",
+            server: msg.request.mcp_server_name ?? msg.request.server,
+            prompt: msg.request.message ?? msg.request.prompt,
+            schema: msg.request.requestedSchema,
+        };
+    return null;
+}