@pi-archimedes/subagent 2.7.3 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/subagent",
-  "version": "2.7.3",
+  "version": "2.9.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -15,8 +15,8 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "2.7.3",
-    "@pi-archimedes/todo": "2.7.3"
+    "@pi-archimedes/core": "2.9.0",
+    "@pi-archimedes/todo": "2.9.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.1.0",
@@ -25,9 +25,9 @@
     "typebox": ">=1.1.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.85.1",
-    "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@earendil-works/pi-tui": "^0.85.1",
+    "@earendil-works/pi-ai": "^0.87.0",
+    "@earendil-works/pi-coding-agent": "^0.87.0",
+    "@earendil-works/pi-tui": "^0.87.0",
     "@types/node": "^22.0.0",
     "typebox": "^1.1.38",
     "typescript": "^6.0.3"

package/src/dispatch.test.ts

@@ -0,0 +1,292 @@
+// ── Bridge-mode dispatch (dispatchViaBridge) ─────────────────────────────
+//
+// A fake bridge server (a `net` server on a temp socket — the pattern from
+// packages/core's bridge index.test.ts end-to-end section) stands in for the
+// desktop. The bridge is activated through the real env-gated session_start
+// path (registerBridge), so `getBridge().active` is the real gate.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { randomUUID } from "node:crypto";
+import { registerBridge } from "@pi-archimedes/core/bridge";
+import { dispatchViaBridge } from "./dispatch.js";
+import { resolveModel } from "./spawn.js";
+import type { ExecuteOptions } from "./execute.js";
+import type { AgentConfig } from "./agents.js";
+import type { SubagentResult } from "./types.js";
+
+const ENV_KEYS = [
+  "PI_ARCHIMEDES_BRIDGE",
+  "PI_ARCHIMEDES_BRIDGE_SOCKET",
+  "PI_ARCHIMEDES_BRIDGE_SESSION",
+  "PI_ARCHIMEDES_BRIDGE_SERVER_PID",
+  "PI_SUBAGENT_SOCKET",
+] as const;
+
+const savedEnv: Record<string, string | undefined> = {};
+
+function clearBridgeEnv(): void {
+  for (const k of ENV_KEYS) delete process.env[k];
+}
+
+/** Activate the bridge (env-gated, root-only) pointing at the given socket. */
+function activateBridge(socketPath: string): void {
+  clearBridgeEnv();
+  process.env.PI_ARCHIMEDES_BRIDGE = "1";
+  process.env.PI_ARCHIMEDES_BRIDGE_SOCKET = socketPath;
+  process.env.PI_ARCHIMEDES_BRIDGE_SESSION = "test-desktop-session";
+  process.env.PI_ARCHIMEDES_BRIDGE_SERVER_PID = "12345";
+  // registerBridge evaluates isBridgeMode at session_start — fire the handler.
+  const onSpy = vi.fn();
+  registerBridge({ on: onSpy } as unknown as ExtensionAPI);
+  const calls = onSpy.mock.calls as Array<[string, (e: unknown, ctx: unknown) => void]>;
+  const startCall = calls.find((c) => c[0] === "session_start");
+  expect(startCall).toBeTruthy();
+  startCall![1](null, { mode: "rpc" });
+}
+
+function tempSocketPath(): string {
+  return path.join(os.tmpdir(), `dispatch-test-${randomUUID()}.sock`);
+}
+
+const AGENT: AgentConfig = {
+  name: "reviewer",
+  description: "Code reviewer",
+  systemPrompt: "You are a reviewer.\n",
+  source: "global",
+  filePath: "/tmp/reviewer.md",
+  model: "anthropic/claude-agent",
+  thinking: "medium",
+  tools: ["read", "bash"],
+};
+
+function makeOptions(overrides: Partial<ExecuteOptions> = {}): ExecuteOptions {
+  return {
+    agent: "reviewer",
+    agentConfig: AGENT,
+    task: "review this code",
+    model: "call-model",
+    activeModel: "active-model",
+    cwd: undefined,
+    signal: undefined,
+    onUpdate: undefined,
+    toolCallId: "tc-1",
+    ...overrides,
+  };
+}
+
+/** A fake bridge server: reply to every request frame with the given frame body. */
+function startFakeDesktop(
+  sockPath: string,
+  reply: (msg: { id?: string; type?: string; method?: string; source?: string; toolCallId?: string; params?: unknown }) => unknown,
+): Promise<net.Server> {
+  const server = net.createServer((socket) => {
+    let buffer = "";
+    socket.on("data", (chunk: Buffer) => {
+      buffer += chunk.toString("utf-8");
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+          const msg = JSON.parse(trimmed) as { type?: string; id?: string; method?: string; source?: string; toolCallId?: string; params?: unknown };
+          if (msg.type === "request" && msg.id) {
+            const body = reply(msg);
+            if (body !== undefined) socket.write(JSON.stringify(body) + "\n");
+          }
+        } catch { /* malformed — ignore */ }
+      }
+    });
+    socket.on("error", () => { /* connection dropped */ });
+  });
+  return new Promise((resolve) => server.listen(sockPath, () => resolve(server)));
+}
+
+beforeEach(() => {
+  for (const k of ENV_KEYS) savedEnv[k] = process.env[k];
+  clearBridgeEnv();
+});
+
+afterEach(() => {
+  for (const k of ENV_KEYS) {
+    if (savedEnv[k] === undefined) delete process.env[k];
+    else process.env[k] = savedEnv[k];
+  }
+  clearBridgeEnv();
+});
+
+// ── dispatchViaBridge: response mapping ───────────────────────────────────
+
+describe("dispatchViaBridge", () => {
+  it("(1) maps a success response to a SubagentResult (no fork)", async () => {
+    const sockPath = tempSocketPath();
+    const frames: Array<Record<string, unknown>> = [];
+    const server = await startFakeDesktop(sockPath, (msg) => {
+      frames.push(msg);
+      return {
+        v: 1,
+        type: "response",
+        id: msg.id,
+        result: { output: "done", metrics: { inputTokens: 1, outputTokens: 2, cost: 0.01, durationMs: 5 } },
+      };
+    });
+    activateBridge(sockPath);
+
+    const outcome = await dispatchViaBridge(makeOptions(), undefined, "tc-1");
+
+    // A SubagentResult — NOT the fallback marker.
+    expect("fallback" in outcome).toBe(false);
+    const result = outcome as SubagentResult;
+    expect(result.exitCode).toBe(0);
+    expect(result.finalOutput).toBe("done");
+    expect(result.error).toBeUndefined();
+    expect(result.usage).toEqual({ input: 1, output: 2, cacheRead: 0, cacheWrite: 0, cost: 0.01, turns: 0 });
+    expect(result.model).toBe("anthropic/claude-agent"); // agent.model wins
+    // Synthesized progress (the same defensive synthesis executeSubagent does).
+    expect(result.progress).toBeDefined();
+    expect(result.progress!.status).toBe("completed");
+    expect(result.progress!.agent).toBe("reviewer");
+    expect(result.progress!.durationMs).toBe(5);
+    expect(result.progressSummary).toEqual({ toolCount: 0, tokens: 3, durationMs: 5 });
+
+    // The frame follows the wire contract.
+    const frame = frames.find((f) => f.type === "request");
+    expect(frame).toBeDefined();
+    expect(frame!.method).toBe("dispatch_subagent");
+    expect(frame!.source).toBe("main");
+    expect(frame!.toolCallId).toBe("tc-1");
+    const params = frame!.params as Record<string, unknown>;
+    expect(params.agentName).toBe("reviewer");
+    expect(params.task).toBe("review this code");
+    expect(params.systemPrompt).toBe("You are a reviewer."); // trimmed
+    expect(params.model).toBe("anthropic/claude-agent");
+    expect(params.thinking).toBe("medium");
+    expect(params.tools).toEqual(["read", "bash"]);
+    expect("cwd" in params).toBe(false); // intentionally NOT sent
+
+    server.close();
+    try { fs.unlinkSync(sockPath); } catch { /* already gone */ }
+  });
+
+  it("(2) a terminal error: 'cancelled' frame → a FAILED SubagentResult (NOT a fallback)", async () => {
+    const sockPath = tempSocketPath();
+    const server = await startFakeDesktop(sockPath, (msg) => {
+      return { v: 1, type: "response", id: msg.id, error: "cancelled" };
+    });
+    activateBridge(sockPath);
+
+    const outcome = await dispatchViaBridge(makeOptions(), undefined, "tc-1");
+
+    // The desktop answered — its outcome is authoritative, never a fallback.
+    expect("fallback" in outcome).toBe(false);
+    const result = outcome as SubagentResult;
+    expect(result.exitCode).toBe(1);
+    expect(result.error).toBe("cancelled");
+    expect(result.finalOutput).toBeUndefined();
+    expect(result.progress!.status).toBe("failed");
+    expect(result.progress!.error).toBe("cancelled");
+
+    server.close();
+    try { fs.unlinkSync(sockPath); } catch { /* already gone */ }
+  });
+
+  it("a mid-dispatch abort settles as a FAILED SubagentResult with error 'cancelled' (NOT a fallback — no fork)", async () => {
+    const sockPath = tempSocketPath();
+    const server = await startFakeDesktop(sockPath, () => {
+      /* accept but never respond */
+    });
+    activateBridge(sockPath);
+
+    const controller = new AbortController();
+    const p = dispatchViaBridge(makeOptions({ signal: controller.signal }), controller.signal, "tc-1");
+    await new Promise((r) => setTimeout(r, 50)); // let the socket connect (request sent)
+    controller.abort(); // mid-dispatch: after the request, before the response
+
+    const outcome = await p;
+    // A deliberate cancel must NEVER fork: a FAILED SubagentResult with the
+    // "cancelled" outcome (the same as the desktop's terminal `error:
+    // "cancelled" frame) — NOT the fallback marker.
+    expect("fallback" in outcome).toBe(false);
+    const result = outcome as SubagentResult;
+    expect(result.exitCode).toBe(1);
+    expect(result.error).toBe("cancelled");
+    expect(result.finalOutput).toBeUndefined();
+    expect(result.progress!.status).toBe("failed");
+    expect(result.progress!.error).toBe("cancelled");
+
+    server.close();
+    try { fs.unlinkSync(sockPath); } catch { /* already gone */ }
+  });
+
+  it("any other response-carrying error → a FAILED SubagentResult with the error message (NOT a fallback)", async () => {
+    const sockPath = tempSocketPath();
+    const server = await startFakeDesktop(sockPath, (msg) => {
+      return { v: 1, type: "response", id: msg.id, error: "worker runtime unavailable" };
+    });
+    activateBridge(sockPath);
+
+    const outcome = await dispatchViaBridge(makeOptions(), undefined, "tc-1");
+
+    expect("fallback" in outcome).toBe(false);
+    const result = outcome as SubagentResult;
+    expect(result.exitCode).toBe(1);
+    expect(result.error).toBe("worker runtime unavailable");
+    expect(result.progress!.status).toBe("failed");
+
+    server.close();
+    try { fs.unlinkSync(sockPath); } catch { /* already gone */ }
+  });
+
+  it("(3) an unreachable bridge (no response frame) → { fallback: true }", async () => {
+    // No server on this socket → ECONNREFUSED → BridgeTransportError.
+    activateBridge(tempSocketPath());
+
+    const outcome = await dispatchViaBridge(makeOptions(), undefined, "tc-1");
+    expect(outcome).toEqual({ fallback: true });
+  });
+
+  it("nullifies the params (model/thinking/tools/systemPrompt) for a config-less run", async () => {
+    const sockPath = tempSocketPath();
+    const frames: Array<Record<string, unknown>> = [];
+    const server = await startFakeDesktop(sockPath, (msg) => {
+      frames.push(msg);
+      return { v: 1, type: "response", id: msg.id, result: { output: "ok", metrics: { inputTokens: 0, outputTokens: 0, cost: 0, durationMs: 1 } } };
+    });
+    activateBridge(sockPath);
+
+    const outcome = await dispatchViaBridge(
+      makeOptions({ agent: undefined, agentConfig: undefined, model: undefined, activeModel: undefined }),
+      undefined,
+      "tc-1",
+    );
+    expect("fallback" in outcome).toBe(false);
+
+    const params = (frames.find((f) => f.type === "request")?.params ?? {}) as Record<string, unknown>;
+    expect(params.agentName).toBe("subagent");
+    expect(params.systemPrompt).toBeNull();
+    expect(params.model).toBeNull();
+    expect(params.thinking).toBeNull();
+    expect(params.tools).toBeNull();
+    // The result's model is the (un-nullified) resolution — undefined here.
+    expect((outcome as SubagentResult).model).toBeUndefined();
+
+    server.close();
+    try { fs.unlinkSync(sockPath); } catch { /* already gone */ }
+  });
+});
+
+// ── resolveModel precedence (shared fork + bridge) ────────────────────────
+
+describe("resolveModel", () => {
+  it("(4) agent.model > call model > activeModel; all undefined → undefined", () => {
+    expect(resolveModel({ model: "call-model", activeModel: "active-model", agent: AGENT })).toBe("anthropic/claude-agent");
+    expect(resolveModel({ model: "call-model", activeModel: "active-model", agent: undefined })).toBe("call-model");
+    expect(resolveModel({ model: undefined, activeModel: "active-model", agent: undefined })).toBe("active-model");
+    expect(resolveModel({ model: undefined, activeModel: undefined, agent: undefined })).toBeUndefined();
+  });
+});

package/src/dispatch.ts

@@ -0,0 +1,175 @@
+// ── Bridge-mode dispatch (dispatch_subagent over the bridge channel) ────
+//
+// In bridge mode the subagent tool does NOT fork a child pi process — it
+// sends a `dispatch_subagent` bridge request and the desktop (Client) runs
+// the subagent session (a full ACP session on its worker runtime).
+//
+// Fallback rule (the BridgeTransportError distinction is the trigger):
+//   - NO response frame (unreachable socket / ECONNREFUSED, a mid-connection
+//     error, or a clean close before any response — the desktop is
+//     effectively gone) → { fallback: true } — the fork path keeps the
+//     subagent working (the main agent is still alive — its desktop
+//     connection died, not the agent).
+//   - A response-carrying `error` (the desktop answered — it is alive and
+//     the outcome is authoritative, incl. the terminal `error: "cancelled"`
+//     frame) → a FAILED SubagentResult, NEVER a fallback.
+//   - A DETERMINISTIC LOCAL CANCEL (the tool's AbortSignal → the channel's
+//     cancel() settles with a BridgeCancelledError — the desktop is NOT
+//     gone, the user just cancelled) → a FAILED SubagentResult with error
+//     "cancelled" (the same outcome as the desktop's terminal
+//     `error: "cancelled" frame), NEVER a fallback — a deliberate cancel
+//     must never fork. The cancel is detected by TYPE
+//     (`instanceof BridgeCancelledError`), not by the message string — the
+//     class is the contract between core and this package.
+//
+// The pre-aborted-signal + unreachable-channel corner (cancel() is a no-op
+// there — the executor's early return leaves `finish` as the safe no-op — so
+// the rejection WOULD map to { fallback: true }) is closed at the EXECUTE
+// layer: executeSubagent short-circuits an already-aborted signal to a
+// FAILED result (error "cancelled") before dispatching (the execute layer
+// already has the signal; the channel-level function must not know fork
+// semantics).
+
+import { dispatch, BridgeTransportError, BridgeCancelledError } from "@pi-archimedes/core/bridge";
+import { resolveModel } from "./spawn.js";
+import type { ExecuteOptions } from "./execute.js";
+import type { SubagentProgress, SubagentResult } from "./types.js";
+
+export type DispatchOutcome = SubagentResult | { fallback: true };
+
+/**
+ * Synthesize a FAILED SubagentResult (a task that never completed — a
+ * response-carrying error, a deterministic local cancel, or a pre-aborted
+ * signal). Shared by the bridge error path and executeSubagent's pre-abort
+ * short-circuit (and fork-path catch) so the "cancelled" synthesis is not
+ * duplicated. The progress is the same defensive synthesis executeSubagent
+ * uses: zeros + the real durationMs (the desktop panel is the progress
+ * surface in bridge mode; the TUI has none in RPC mode).
+ */
+export function buildFailedResult(
+  agentName: string,
+  task: string,
+  error: string,
+  model: string | undefined,
+  durationMs: number,
+): SubagentResult {
+  return {
+    agent: agentName,
+    task,
+    exitCode: 1,
+    usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+    model,
+    finalOutput: undefined,
+    error,
+    progress: {
+      agent: agentName,
+      status: "failed",
+      task,
+      currentTool: undefined,
+      currentToolArgs: undefined,
+      currentToolStartedAt: undefined,
+      toolCount: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      tokens: 0,
+      cost: 0,
+      durationMs,
+      error,
+      output: undefined,
+      recentOutput: undefined,
+      toolCalls: undefined,
+      model,
+    },
+    progressSummary: { toolCount: 0, tokens: 0, durationMs },
+  };
+}
+
+export function dispatchViaBridge(
+  options: ExecuteOptions,
+  signal: AbortSignal | undefined,
+  toolCallId: string | undefined,
+): Promise<DispatchOutcome> {
+  const agentName = options.agent ?? "subagent";
+  const model = resolveModel({ model: options.model, activeModel: options.activeModel, agent: options.agentConfig });
+  const startTime = Date.now();
+
+  // `cwd` is intentionally NOT sent — the subagent session's cwd is the
+  // parent's Space folder (the wire contract; the tool's `cwd` param is
+  // ignored in bridge mode).
+  const params = {
+    agentName,
+    task: options.task,
+    systemPrompt: options.agentConfig?.systemPrompt?.trim() || null,
+    model: model ?? null,
+    thinking: options.agentConfig?.thinking ?? null,
+    tools: options.agentConfig?.tools?.length ? options.agentConfig.tools : null,
+  };
+
+  return dispatch(params, toolCallId, signal).then(
+    (res) => {
+      // Success → a SubagentResult with a synthesized progress (the same
+      // defensive synthesis executeSubagent does; the desktop's panel is the
+      // progress surface, so the fields are zeros + the real durationMs).
+      const durationMs = res.metrics.durationMs;
+      const progress: SubagentProgress = {
+        agent: agentName,
+        status: "completed",
+        task: options.task,
+        currentTool: undefined,
+        currentToolArgs: undefined,
+        currentToolStartedAt: undefined,
+        toolCount: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        tokens: 0,
+        cost: 0,
+        durationMs,
+        error: undefined,
+        output: res.output,
+        recentOutput: undefined,
+        toolCalls: undefined,
+        model,
+      };
+      return {
+        agent: agentName,
+        task: options.task,
+        exitCode: 0,
+        usage: {
+          input: res.metrics.inputTokens,
+          output: res.metrics.outputTokens,
+          cacheRead: 0,
+          cacheWrite: 0,
+          cost: res.metrics.cost,
+          turns: 0,
+        },
+        model,
+        finalOutput: res.output,
+        error: undefined,
+        progress,
+        progressSummary: {
+          toolCount: 0,
+          tokens: res.metrics.inputTokens + res.metrics.outputTokens,
+          durationMs,
+        },
+      };
+    },
+    (err: unknown) => {
+      // No response frame (the desktop is effectively gone) → the fork path
+      // keeps the subagent working.
+      if (err instanceof BridgeTransportError) {
+        return { fallback: true };
+      }
+      // A response-carrying error (the desktop answered — authoritative,
+      // incl. the terminal "cancelled" frame) or a DETERMINISTIC LOCAL CANCEL
+      // (the tool's AbortSignal → channel.cancel() settles with a
+      // BridgeCancelledError — the same outcome as the desktop's terminal
+      // `error: "cancelled" frame) → a FAILED SubagentResult (the shared
+      // failed-progress synthesis), NEVER a fallback (a deliberate cancel
+      // must never fork).
+      const isLocalCancel = err instanceof BridgeCancelledError;
+      const errorMessage = isLocalCancel ? "cancelled" : err instanceof Error ? err.message : String(err);
+      const durationMs = Date.now() - startTime;
+      return buildFailedResult(agentName, options.task, errorMessage, model, durationMs);
+    },
+  );
+}

package/src/execute.test.ts

@@ -0,0 +1,180 @@
+// ── executeSubagent bridge branch: a deliberate cancel must never fork ──
+//
+// The "no fork on cancel" guarantee at the execute layer: a mid-dispatch
+// abort settles the bridge dispatch as a FAILED result (error "cancelled")
+// and `spawnSubagent` (the fork path) is NEVER called. The bridge is
+// activated through the real env-gated session_start path (registerBridge),
+// so `getBridge().active` is the real gate.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { randomUUID } from "node:crypto";
+import { registerBridge } from "@pi-archimedes/core/bridge";
+import * as channel from "@pi-archimedes/core/bridge/channel";
+import * as spawn from "./spawn.js";
+import { executeSubagent } from "./execute.js";
+import type { ExecuteOptions } from "./execute.js";
+import type { AgentConfig } from "./agents.js";
+import type { SubagentProgress } from "./types.js";
+
+const ENV_KEYS = [
+  "PI_ARCHIMEDES_BRIDGE",
+  "PI_ARCHIMEDES_BRIDGE_SOCKET",
+  "PI_ARCHIMEDES_BRIDGE_SESSION",
+  "PI_ARCHIMEDES_BRIDGE_SERVER_PID",
+  "PI_SUBAGENT_SOCKET",
+] as const;
+
+const savedEnv: Record<string, string | undefined> = {};
+
+function clearBridgeEnv(): void {
+  for (const k of ENV_KEYS) delete process.env[k];
+}
+
+/** Activate the bridge (env-gated, root-only) pointing at the given socket. */
+function activateBridge(socketPath: string): void {
+  clearBridgeEnv();
+  process.env.PI_ARCHIMEDES_BRIDGE = "1";
+  process.env.PI_ARCHIMEDES_BRIDGE_SOCKET = socketPath;
+  process.env.PI_ARCHIMEDES_BRIDGE_SESSION = "test-desktop-session";
+  process.env.PI_ARCHIMEDES_BRIDGE_SERVER_PID = "12345";
+  const onSpy = vi.fn();
+  registerBridge({ on: onSpy } as unknown as ExtensionAPI);
+  const calls = onSpy.mock.calls as Array<[string, (e: unknown, ctx: unknown) => void]>;
+  const startCall = calls.find((c) => c[0] === "session_start");
+  expect(startCall).toBeTruthy();
+  startCall![1](null, { mode: "rpc" });
+}
+
+function tempSocketPath(): string {
+  return path.join(os.tmpdir(), `execute-test-${randomUUID()}.sock`);
+}
+
+const AGENT: AgentConfig = {
+  name: "reviewer",
+  description: "Code reviewer",
+  systemPrompt: "You are a reviewer.\n",
+  source: "global",
+  filePath: "/tmp/reviewer.md",
+  model: "anthropic/claude-agent",
+  thinking: "medium",
+  tools: ["read", "bash"],
+};
+
+function makeOptions(overrides: Partial<ExecuteOptions> = {}): ExecuteOptions {
+  return {
+    agent: "reviewer",
+    agentConfig: AGENT,
+    task: "review this code",
+    model: "call-model",
+    activeModel: "active-model",
+    cwd: undefined,
+    signal: undefined,
+    onUpdate: undefined,
+    toolCallId: "tc-1",
+    ...overrides,
+  };
+}
+
+function startSilentDesktop(sockPath: string): Promise<net.Server> {
+  const server = net.createServer((socket) => {
+    /* accept but never respond */
+    socket.on("error", () => { /* connection dropped */ });
+  });
+  return new Promise((resolve) => server.listen(sockPath, () => resolve(server)));
+}
+
+beforeEach(() => {
+  for (const k of ENV_KEYS) savedEnv[k] = process.env[k];
+  clearBridgeEnv();
+});
+
+afterEach(() => {
+  for (const k of ENV_KEYS) {
+    if (savedEnv[k] === undefined) delete process.env[k];
+    else process.env[k] = savedEnv[k];
+  }
+  clearBridgeEnv();
+  vi.restoreAllMocks();
+});
+
+describe("executeSubagent (bridge branch)", () => {
+  it("a mid-dispatch abort settles as a FAILED result and NEVER forks (spawnSubagent not called)", async () => {
+    const sockPath = tempSocketPath();
+    const server = await startSilentDesktop(sockPath);
+    activateBridge(sockPath);
+
+    // The fork path: if a deliberate cancel ever fell through to it, the
+    // spy catches the call (the implementation throws so a fall-through is
+    // also loud).
+    const spawnSpy = vi.spyOn(spawn, "spawnSubagent").mockImplementation(() => {
+      throw new Error("fork must not happen on a deliberate cancel");
+    });
+
+    const controller = new AbortController();
+    const p = executeSubagent(makeOptions({ signal: controller.signal }));
+    await new Promise((r) => setTimeout(r, 50)); // let the socket connect (request sent)
+    controller.abort(); // mid-dispatch: after the request, before the response
+
+    const result = await p;
+    // The bridge outcome is authoritative (a FAILED result) — the fork path
+    // (spawnSubagent) is NEVER called for a task the user just cancelled.
+    expect(result.exitCode).toBe(1);
+    expect(result.error).toBe("cancelled");
+    expect(result.progress!.status).toBe("failed");
+    expect(spawnSpy).not.toHaveBeenCalled();
+
+    spawnSpy.mockRestore();
+    server.close();
+    try { fs.unlinkSync(sockPath); } catch { /* already gone */ }
+  });
+
+  it("a pre-aborted signal short-circuits to a FAILED result and NEVER forks (no 'dispatched' placeholder, no fork)", async () => {
+    // The corner: an UNREACHABLE channel (the executor's early return leaves
+    // `finish` as a safe no-op, so `handle.cancel()` is a no-op and
+    // `channel.request` rejects with a BridgeTransportError → { fallback: true }
+    // → the fork path would run for an already-cancelled task). Simulated with
+    // `active: true` + no socket target (the ECONNREFUSED variant is NOT the
+    // corner — there the async socket error loses the race to the synchronous
+    // cancel() and the outcome is already a deterministic "cancelled").
+    activateBridge(tempSocketPath());
+    channel.configure({ active: true, socketPath: undefined });
+
+    // The fork path: if the pre-abort corner ever fell through to it, the spy
+    // catches the call (the implementation throws so a fall-through is also
+    // loud).
+    const spawnSpy = vi.spyOn(spawn, "spawnSubagent").mockImplementation(() => {
+      throw new Error("fork must not happen for a pre-aborted signal");
+    });
+
+    const controller = new AbortController();
+    controller.abort(); // pre-aborted BEFORE dispatch
+
+    const updates: SubagentProgress[] = [];
+    const result = await executeSubagent(
+      makeOptions({ signal: controller.signal, onUpdate: (p) => updates.push(p) }),
+    );
+
+    // A deliberate cancel must NEVER fork — even in the unreachable-channel
+    // corner: a FAILED SubagentResult with the "cancelled" outcome, and the
+    // task does not claim it was "dispatched" (no placeholder before the
+    // short-circuit; the final-failure progress still updates the
+    // executeParallel slot from the pending placeholder to "failed").
+    expect(result.exitCode).toBe(1);
+    expect(result.error).toBe("cancelled");
+    expect(result.progress!.status).toBe("failed");
+    expect(result.progress!.error).toBe("cancelled");
+    expect(spawnSpy).not.toHaveBeenCalled();
+    // Exactly ONE update: the final-failure progress (no "dispatched"
+    // placeholder — a cancelled task does not claim it was dispatched).
+    expect(updates).toHaveLength(1);
+    expect(updates[0]?.status).toBe("failed");
+    expect(updates[0]?.error).toBe("cancelled");
+
+    spawnSpy.mockRestore();
+  });
+});

package/src/execute.ts

@@ -1,8 +1,10 @@
-import { spawnSubagent } from "./spawn.js";
+import { getBridge } from "@pi-archimedes/core/bridge";
+import { spawnSubagent, resolveModel } from "./spawn.js";
+import { dispatchViaBridge, buildFailedResult } from "./dispatch.js";
 import { streamEvents } from "./stream.js";
 import { emitCostUpdate } from "./cost.js";
 import type { AgentConfig } from "./agents.js";
-import type { SubagentProgress, SubagentResult, SubagentUsage } from "./types.js";
+import type { SubagentProgress, SubagentResult } from "./types.js";
 
 export interface ExecuteOptions {
   agent: string | undefined;
@@ -13,6 +15,10 @@ export interface ExecuteOptions {
   cwd: string | undefined;
   signal: AbortSignal | undefined;
   onUpdate: ((progress: SubagentProgress) => void) | undefined;
+  /** The subagent tool-call id (the tool's `_id`) — rides the dispatch frame
+   *  for Client correlation; `undefined` → the frame's `toolCallId` is absent.
+   *  In `executeParallel` all N tasks share the single subagent tool-call's id. */
+  toolCallId?: string;
 }
 
 /**
@@ -22,6 +28,71 @@ export async function executeSubagent(options: ExecuteOptions): Promise<Subagent
   const agentName = options.agent ?? "subagent";
   const startTime = Date.now();
 
+  // Bridge mode: dispatch to the desktop (Client) instead of forking a child
+  // pi process. An UNREACHABLE bridge (no response frame — e.g. macOS, where
+  // the desktop's listener is not started, or Windows, where it is a no-op
+  // stub) falls back to the fork path so subagents keep working everywhere.
+  if (getBridge().active) {
+    const model = resolveModel({ model: options.model, activeModel: options.activeModel, agent: options.agentConfig });
+
+    // A signal that is ALREADY aborted before dispatch: short-circuit to a
+    // FAILED result (error "cancelled") — a deliberate cancel must never
+    // fork, even in the corner where the channel is unreachable (the
+    // executor's early return leaves `finish` as a safe no-op, so
+    // `handle.cancel()` is a no-op and the rejection would map to
+    // { fallback: true } → the fork path for an already-cancelled task).
+    // This layer (not dispatchViaBridge) is the home: the execute layer
+    // already has the signal; the channel-level function must not know fork
+    // semantics. The short-circuit is BEFORE the "dispatched" placeholder —
+    // a cancelled task does not claim it was dispatched — but the final
+    // failure progress IS emitted (the same emit the catch block below does),
+    // so executeParallel's progress slot updates from the pending placeholder
+    // to "failed" instead of a stale "Starting...".
+    if (options.signal?.aborted) {
+      const result = buildFailedResult(agentName, options.task, "cancelled", model, Date.now() - startTime);
+      options.onUpdate?.(result.progress!);
+      return result;
+    }
+
+    // The TUI has no surface in bridge mode (RPC mode) and the desktop panel
+    // is the progress surface — call onUpdate ONCE with a minimal "dispatched"
+    // placeholder so the pi-acp tool_call_update frames stay well-formed, then
+    // no further updates.
+    options.onUpdate?.({
+      agent: agentName,
+      status: "running",
+      task: options.task,
+      currentTool: undefined,
+      currentToolArgs: undefined,
+      currentToolStartedAt: undefined,
+      toolCount: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      tokens: 0,
+      cost: 0,
+      durationMs: 0,
+      error: undefined,
+      output: undefined,
+      recentOutput: undefined,
+      toolCalls: undefined,
+      model,
+    });
+    const outcome = await dispatchViaBridge(options, options.signal, options.toolCallId);
+    if (!("fallback" in outcome)) {
+      // Bridge used (success or a response-carrying error, incl. the terminal
+      // "cancelled" frame — the desktop is alive, its outcome is authoritative):
+      // return it — NO fork fallback, and NO emitCostUpdate here — the PARENT
+      // never pushes the subagent's usage on the PARENT's bus (the fork-delta
+      // semantics: only the fork path reports a child's usage, source
+      // `subagent:<name>`). The subagent process self-emits its own usage to
+      // its OWN bridge (the core self-usage emitter,
+      // `subagent-metrics-cost-push` Task 1) — a different bus, a different
+      // session; no double-count.
+      return outcome;
+    }
+    // { fallback: true } — unreachable bridge: fall through to the fork path.
+  }
+
   // Track previously emitted values to only emit deltas
   let lastEmittedInput = 0;
   let lastEmittedOutput = 0;
@@ -95,46 +166,13 @@ export async function executeSubagent(options: ExecuteOptions): Promise<Subagent
   } catch (err) {
     const errorMessage = err instanceof Error ? err.message : String(err);
     const durationMs = Date.now() - startTime;
-    const result: SubagentResult = {
-      agent: agentName,
-      task: options.task,
-      exitCode: 1,
-      usage: {
-        input: 0,
-        output: 0,
-        cacheRead: 0,
-        cacheWrite: 0,
-        cost: 0,
-        turns: 0,
-      } as SubagentUsage,
-      model: undefined,
-      finalOutput: undefined,
-      error: errorMessage,
-      // Always return a valid progress object so the parallel renderer's
-      // `details.progress[i]` stays aligned with `details.results[i]`.
-      // Returning undefined here would be filtered out and cause index
-      // misalignment between results and progress in the parallel view.
-      progress: {
-        agent: agentName,
-        status: "failed",
-        task: options.task,
-        currentTool: undefined,
-        currentToolArgs: undefined,
-        currentToolStartedAt: undefined,
-        toolCount: 0,
-        inputTokens: 0,
-        outputTokens: 0,
-        tokens: 0,
-        cost: 0,
-        durationMs,
-        error: errorMessage,
-        output: undefined,
-        recentOutput: undefined,
-        toolCalls: undefined,
-        model: undefined,
-      },
-      progressSummary: { toolCount: 0, tokens: 0, durationMs },
-    };
+    // The shared failed-result synthesis (the same one the bridge error path
+    // uses — model is undefined here: the fork never ran, so no model was
+    // chosen). Always returns a valid progress object so the parallel
+    // renderer's `details.progress[i]` stays aligned with `details.results[i]`
+    // (returning undefined would be filtered out and cause index misalignment
+    // between results and progress in the parallel view).
+    const result = buildFailedResult(agentName, options.task, errorMessage, undefined, durationMs);
     // Emit final failure progress so executeParallel's progress slot updates
     // from the pending placeholder to "failed" (prevents stale "Starting..." display).
     options.onUpdate?.(result.progress!);
@@ -146,7 +184,7 @@ export async function executeSubagent(options: ExecuteOptions): Promise<Subagent
  * Execute multiple subagents in parallel.
  */
 export async function executeParallel(options: {
-  tasks: Array<{ agent: string | undefined; agentConfig: AgentConfig | undefined; task: string; model: string | undefined; activeModel: string | undefined; cwd: string | undefined }>;
+  tasks: Array<{ agent: string | undefined; agentConfig: AgentConfig | undefined; task: string; model: string | undefined; activeModel: string | undefined; cwd: string | undefined; toolCallId?: string }>;
   signal: AbortSignal | undefined;
   onUpdate: ((progress: SubagentProgress[]) => void) | undefined;
 }): Promise<SubagentResult[]> {

package/src/index.ts

@@ -96,6 +96,9 @@ export function registerSubagent(pi: ExtensionAPI): void {
             model: t.model,
             activeModel: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined,
             cwd: t.cwd ?? undefined,
+            // All N tasks share the single subagent tool-call's id (the frame
+            // carries it for Client correlation).
+            toolCallId: _id,
           })),
           signal: signal ?? undefined,
           onUpdate: (progress: SubagentProgress[]) => {
@@ -163,6 +166,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
           activeModel: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined,
           cwd: params.cwd ?? undefined,
           signal: signal ?? undefined,
+          toolCallId: _id,
           onUpdate: (progress: SubagentProgress) => {
             onUpdate?.({
               content: [],

package/src/spawn.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import * as net from "node:net";
+import { getBus, Events } from "@pi-archimedes/core/bus";
+import { startAskSocketServer } from "./spawn.js";
+
+// startAskSocketServer is tested directly (not via spawnSubagent, which would
+// spawn a real `pi` process). The real bus is used — subscriptions are
+// unsubscribed in afterEach so they don't leak into other test files in the
+// same worker (the bus is a globalThis singleton).
+
+const cleanups: Array<() => void> = [];
+const unsubs: Array<() => void> = [];
+
+afterEach(() => {
+  unsubs.splice(0).forEach((u) => u());
+  cleanups.splice(0).forEach((c) => c());
+});
+
+function track(fn: () => void): void {
+  cleanups.push(fn);
+}
+
+function connectClient(socketPath: string): Promise<net.Socket> {
+  return new Promise((resolve, reject) => {
+    const client = net.connect(socketPath, () => resolve(client));
+    client.on("error", (err) => reject(err));
+  });
+}
+
+function writeAskRequest(client: net.Socket, requestId: string, toolCallId?: string): void {
+  client.write(
+    JSON.stringify({
+      type: "ask_request",
+      requestId,
+      toolCallId,
+      questions: [{ id: "q1", question: "Which?", options: [{ label: "A" }] }],
+    }) + "\n",
+  );
+}
+
+describe("startAskSocketServer", () => {
+  it("a child ask_request carrying toolCallId → the bus ASK_REQUEST carries the same toolCallId", async () => {
+    const { socketPath, cleanup } = startAskSocketServer("test-agent");
+    track(cleanup);
+    await new Promise((r) => setTimeout(r, 50)); // let the server listen
+
+    const requests: unknown[] = [];
+    unsubs.push(getBus().on(Events.ASK_REQUEST, (p) => requests.push(p)));
+
+    const client = await connectClient(socketPath);
+    writeAskRequest(client, "req-1", "tool-9");
+
+    await vi.waitFor(() => expect(requests.length).toBe(1));
+    const req = requests[0] as { source: string; requestId: string; toolCallId?: string; questions: unknown[] };
+    expect(req.source).toBe("subagent:test-agent");
+    expect(req.requestId).toBe("req-1");
+    expect(req.toolCallId).toBe("tool-9");
+    expect(req.questions).toEqual([{ id: "q1", question: "Which?", options: [{ label: "A" }] }]);
+
+    // Deliver the response (drains pending) before closing so no ASK_CANCEL
+    // leaks onto the global bus queue for the next test
+    getBus().emit(Events.ASK_RESPONSE, {
+      requestId: "req-1",
+      cancelled: false,
+      results: [{ id: "q1", selectedOptions: ["A"] }],
+    });
+    await new Promise((r) => setTimeout(r, 50));
+    client.destroy();
+    await new Promise((r) => setTimeout(r, 50)); // close handler ran (no-op)
+  });
+
+  it("closing the child socket → ASK_CANCEL for the pending requestId + source", async () => {
+    const { socketPath, cleanup } = startAskSocketServer("test-agent");
+    track(cleanup);
+    await new Promise((r) => setTimeout(r, 50)); // let the server listen
+
+    const cancels: unknown[] = [];
+    unsubs.push(getBus().on(Events.ASK_CANCEL, (p) => cancels.push(p)));
+    const requests: unknown[] = [];
+    unsubs.push(getBus().on(Events.ASK_REQUEST, (p) => requests.push(p)));
+
+    const client = await connectClient(socketPath);
+    writeAskRequest(client, "req-2");
+
+    // Wait until the request is registered (pending) before closing
+    await vi.waitFor(() => expect(requests.length).toBe(1));
+    client.destroy();
+
+    await vi.waitFor(() => expect(cancels.length).toBe(1));
+    expect(cancels[0]).toEqual({ requestId: "req-2", source: "subagent:test-agent" });
+  });
+
+  it("no ASK_CANCEL once the response has already been delivered (pending drained)", async () => {
+    const { socketPath, cleanup } = startAskSocketServer("test-agent");
+    track(cleanup);
+    await new Promise((r) => setTimeout(r, 50)); // let the server listen
+
+    const cancels: unknown[] = [];
+    unsubs.push(getBus().on(Events.ASK_CANCEL, (p) => cancels.push(p)));
+    const requests: unknown[] = [];
+    unsubs.push(getBus().on(Events.ASK_REQUEST, (p) => requests.push(p)));
+
+    const client = await connectClient(socketPath);
+    writeAskRequest(client, "req-3");
+    await vi.waitFor(() => expect(requests.length).toBe(1));
+
+    // Deliver the response (drains pending) before the socket closes
+    getBus().emit(Events.ASK_RESPONSE, {
+      requestId: "req-3",
+      cancelled: false,
+      results: [{ id: "q1", selectedOptions: ["A"] }],
+    });
+    await new Promise((r) => setTimeout(r, 50));
+    client.destroy();
+    await new Promise((r) => setTimeout(r, 50)); // close handler ran
+
+    expect(cancels.length).toBe(0);
+  });
+});

package/src/spawn.ts

@@ -16,6 +16,15 @@ export interface SpawnOptions {
   agent: AgentConfig | undefined;
 }
 
+/**
+ * Resolve the model for a subagent run: agent config model > call model >
+ * active (parent) model. Shared by the fork path (spawnSubagent) and the
+ * bridge path (dispatch) so both resolve identically.
+ */
+export function resolveModel(options: Pick<SpawnOptions, "model" | "activeModel"> & { agent?: AgentConfig | undefined }): string | undefined {
+  return options.agent?.model ?? options.model ?? options.activeModel;
+}
+
 /**
  * Resolve the pi binary path.
  *
@@ -67,17 +76,22 @@ function resolvePiBinary(): string {
  * Start a Unix socket server that bridges the child's ask tool to the parent bus.
  *
  * The child's ask tool (in packages/ask) connects to PI_SUBAGENT_SOCKET and sends:
- *   { type: "ask_request", requestId, questions } as a JSON line
+ *   { type: "ask_request", requestId, questions, toolCallId } as a JSON line
  * and waits for:
  *   { type: "ask_response", requestId, cancelled, results } as a JSON line
  *
- * We forward the request onto the bus (ASK_REQUEST), the ask package shows the
- * parent TUI dialog, then emits ASK_RESPONSE on the bus, and we write it back
- * to the socket connection.
+ * We forward the request onto the bus (ASK_REQUEST, carrying toolCallId), the
+ * ask package (or the bridge, in bridge mode) answers it, then emits
+ * ASK_RESPONSE on the bus, and we write it back to the socket connection.
+ *
+ * When the socket closes (child exit, or the child's own 5-min timeout →
+ * socket.end()) we signal the bridge via ASK_CANCEL for any still-pending ask.
+ * We do NOT emit ASK_RESPONSE ourselves — the bridge is the sole emitter
+ * (no double-decrement of its refcount).
  *
  * Returns the socket path and a cleanup function.
  */
-function startAskSocketServer(agentName: string): { socketPath: string; cleanup: () => void } {
+export function startAskSocketServer(agentName: string): { socketPath: string; cleanup: () => void } {
   // Use named pipes on Windows, Unix domain sockets elsewhere.
   // Linux socket path limit is 108 chars — keep it short.
   const id = randomUUID().slice(0, 8);
@@ -110,6 +124,8 @@ function startAskSocketServer(agentName: string): { socketPath: string; cleanup:
 
   const server = net.createServer((socket) => {
     let buffer = "";
+    // requestIds seen on this socket (for the ASK_CANCEL wiring below)
+    const socketRequestIds = new Set<string>();
 
     socket.on("data", (chunk: Buffer) => {
       buffer += chunk.toString("utf-8");
@@ -124,6 +140,7 @@ function startAskSocketServer(agentName: string): { socketPath: string; cleanup:
             type: string;
             requestId: string;
             questions: unknown[];
+            toolCallId?: string;
           };
           if (msg.type === "ask_request") {
             // Register write-back so ASK_RESPONSE handler can find this socket
@@ -134,11 +151,14 @@ function startAskSocketServer(agentName: string): { socketPath: string; cleanup:
                 // socket already closed
               }
             });
-            // Forward to bus — ask package will show the TUI dialog
+            socketRequestIds.add(msg.requestId);
+            // Forward to bus — the ask package (or the bridge, in bridge mode)
+            // answers it; toolCallId rides along for Client correlation
             getBus().emit(Events.ASK_REQUEST, {
               source: `subagent:${agentName}`,
               requestId: msg.requestId,
               questions: msg.questions,
+              toolCallId: msg.toolCallId,
             });
           }
         } catch {
@@ -147,6 +167,19 @@ function startAskSocketServer(agentName: string): { socketPath: string; cleanup:
       }
     });
 
+    // Child exit (or the child's own 5-min timeout → socket.end()) closes the
+    // socket: signal the bridge via ASK_CANCEL for any still-pending ask so it
+    // can cancel the relayed Client request. We only signal — the bridge is
+    // the sole ASK_RESPONSE emitter (no double-decrement of its refcount).
+    socket.on("close", () => {
+      for (const rid of socketRequestIds) {
+        if (pending.has(rid)) {
+          getBus().emit(Events.ASK_CANCEL, { requestId: rid, source: `subagent:${agentName}` });
+          pending.delete(rid);
+        }
+      }
+    });
+
     socket.on("error", () => { /* connection dropped */ });
   });
 
@@ -181,7 +214,7 @@ export function spawnSubagent(options: SpawnOptions): ChildProcess {
   const args: string[] = ["--mode", "json", "--no-session", "-p"];
 
   // Model: agent.model > options.model > options.activeModel
-  const model = options.agent?.model ?? options.model ?? options.activeModel;
+  const model = resolveModel(options);
   if (model) {
     args.push("--model", model);
   }
@@ -245,7 +278,12 @@ export function spawnSubagent(options: SpawnOptions): ChildProcess {
         forceKill.unref();
       }
     };
-    options.signal.addEventListener("abort", abortHandler, { once: true });
+    // A signal that is ALREADY aborted never dispatches its "abort" event (it
+    // fires exactly once, at abort time), so addEventListener alone would never
+    // kill the child — call the handler directly in that case. (kill is
+    // idempotent via the child.killed guard, so both branches coexist safely.)
+    if (options.signal.aborted) abortHandler();
+    else options.signal.addEventListener("abort", abortHandler, { once: true });
     child.on("exit", () => options.signal!.removeEventListener("abort", abortHandler));
   }
 

package/src/stream.test.ts

@@ -192,6 +192,42 @@ describe("streamEvents todo mirroring", () => {
     ]);
   });
 
+  it("stows raw args under the alias key todo_list (result has no details)", async () => {
+    const updates: Array<{ source: string; todos: unknown[] }> = [];
+    const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>
+      updates.push(p as (typeof updates)[number]),
+    );
+
+    await finishWith(
+      [
+        {
+          type: "tool_execution_start",
+          toolCallId: "t-alias",
+          toolName: "manage_todo_list",
+          args: {
+            operation: "write",
+            todo_list: [{ id: 1, title: "Fix auth", status: "not-started" }],
+          },
+        },
+        {
+          type: "tool_execution_end",
+          toolCallId: "t-alias",
+          toolName: "manage_todo_list",
+          isError: false,
+          result: { content: [{ type: "text", text: "ok" }] },
+        },
+      ],
+      { agent: "t-alias" },
+    );
+    off();
+
+    expect(updates).toHaveLength(1);
+    expect(updates[0]!.source).toBe("subagent:t-alias");
+    expect(updates[0]!.todos).toEqual([
+      { content: "Fix auth", status: "pending" },
+    ]);
+  });
+
   it("does not crash or emit when the end event has no matching start", async () => {
     const updates: Array<{ source: string; todos: unknown[] }> = [];
     const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>

package/src/stream.ts

@@ -2,7 +2,7 @@ import { createInterface } from "node:readline";
 import type { ChildProcess } from "node:child_process";
 import type { StreamState, SubagentProgress, SubagentResult } from "./types.js";
 import { getBus, Events } from "@pi-archimedes/core/bus";
-import { normalizeTodoItems } from "@pi-archimedes/todo/prepare-args";
+import { normalizeTodoItems, pickTodoListRaw } from "@pi-archimedes/todo/prepare-args";
 import {
   type JsonEvent,
   handleToolStart,
@@ -150,7 +150,9 @@ export function streamEvents(
           emitProgress();
           if (event.toolName === "manage_todo_list" && typeof event.toolCallId === "string") {
             const args = event.args as Record<string, unknown> | undefined;
-            const todoList = args?.todoList;
+            // Raw (pre-prepareArguments) args: the child model may have used
+            // an alias key (todo_list/todos) — pickTodoListRaw covers it.
+            const todoList = pickTodoListRaw(args);
             if (Array.isArray(todoList)) {
               pendingTodoArgs.set(event.toolCallId, todoList);
             }