@pi-archimedes/subagent 2.10.4 → 2.11.0

package/src/spawn.ts

@@ -4,7 +4,9 @@ import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
-import { getBus, Events } from "@pi-archimedes/core/bus";
+import type { EventBus } from "@earendil-works/pi-coding-agent";
+import { Events, emitOn } from "@pi-archimedes/core/events";
+import { resolveThinkingLevel } from "./thinking-validation.js";
 import type { AgentConfig } from "./agents.js";
 
 export interface SpawnOptions {
@@ -14,6 +16,8 @@ export interface SpawnOptions {
   cwd: string | undefined;
   signal: AbortSignal | undefined;
   agent: AgentConfig | undefined;
+  /** The parent's host handle (`pi.events`) — see `startAskSocketServer`. */
+  events: EventBus;
 }
 
 /**
@@ -73,25 +77,32 @@ function resolvePiBinary(): string {
 }
 
 /**
- * Start a Unix socket server that bridges the child's ask tool to the parent bus.
+ * Start a Unix socket server that bridges the child's ask tool to the parent's
+ * event handle.
  *
  * The child's ask tool (in packages/ask) connects to PI_SUBAGENT_SOCKET and sends:
  *   { 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, carrying toolCallId), the
+ * We forward the request onto the handle (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.
+ * ASK_RESPONSE on the same handle, 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).
  *
+ * @param events the parent's `pi.events`, injected: this is a plain function, not
+ *               an extension, so the handle has to come from the caller that has
+ *               one. The subscription it opens is closed by the returned
+ *               `cleanup()` — a per-spawn subscription with a per-spawn
+ *               teardown, which is why it cannot accumulate across runs.
+ *
  * Returns the socket path and a cleanup function.
  */
-export function startAskSocketServer(agentName: string): { socketPath: string; cleanup: () => void } {
+export function startAskSocketServer(agentName: string, events: EventBus): { 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);
@@ -103,8 +114,8 @@ export function startAskSocketServer(agentName: string): { socketPath: string; c
   // Map of pending ask requests: requestId → write-back callback
   const pending = new Map<string, (response: unknown) => void>();
 
-  // Listen for ASK_RESPONSE from the bus and route back to the waiting socket conn
-  const unsubResponse = getBus().on(Events.ASK_RESPONSE, (payload: unknown) => {
+  // Listen for ASK_RESPONSE on the handle and route back to the waiting socket conn
+  const unsubResponse = events.on(Events.ASK_RESPONSE, (payload: unknown) => {
     const data = payload as {
       requestId: string;
       cancelled: boolean;
@@ -152,9 +163,9 @@ export function startAskSocketServer(agentName: string): { socketPath: string; c
               }
             });
             socketRequestIds.add(msg.requestId);
-            // Forward to bus — the ask package (or the bridge, in bridge mode)
+            // Forward onto the handle — the ask package (or the bridge, in bridge mode)
             // answers it; toolCallId rides along for Client correlation
-            getBus().emit(Events.ASK_REQUEST, {
+            emitOn(events, Events.ASK_REQUEST, {
               source: `subagent:${agentName}`,
               requestId: msg.requestId,
               questions: msg.questions,
@@ -174,7 +185,7 @@ export function startAskSocketServer(agentName: string): { socketPath: string; c
     socket.on("close", () => {
       for (const rid of socketRequestIds) {
         if (pending.has(rid)) {
-          getBus().emit(Events.ASK_CANCEL, { requestId: rid, source: `subagent:${agentName}` });
+          emitOn(events, Events.ASK_CANCEL, { requestId: rid, source: `subagent:${agentName}` });
           pending.delete(rid);
         }
       }
@@ -208,7 +219,7 @@ export function spawnSubagent(options: SpawnOptions): ChildProcess {
   const agentName = options.agent?.name ?? "general";
 
   // Start ask bridge socket before spawning so the env var is ready
-  const { socketPath, cleanup: cleanupSocket } = startAskSocketServer(agentName);
+  const { socketPath, cleanup: cleanupSocket } = startAskSocketServer(agentName, options.events);
 
   // Build CLI args
   const args: string[] = ["--mode", "json", "--no-session", "-p"];
@@ -219,14 +230,35 @@ export function spawnSubagent(options: SpawnOptions): ChildProcess {
     args.push("--model", model);
   }
 
-  // Thinking level from agent config
-  if (options.agent?.thinking) {
-    args.push("--thinking", options.agent.thinking);
+  // Thinking level from agent config. An unknown level is NOT passed on: pi
+  // warns and drops the flag itself, which leaves the child on the default
+  // level with the explanation in a stderr nobody reads for a successful run.
+  // `index.ts` reports the same drop where the user can see it.
+  const thinking = resolveThinkingLevel(options.agent?.thinking);
+  if (thinking.level !== undefined) {
+    args.push("--thinking", thinking.level);
   }
 
-  // Tool allowlist from agent config
-  if (options.agent?.tools && options.agent.tools.length > 0) {
-    args.push("--tools", options.agent.tools.join(","));
+  // Tool allowlist from agent config.
+  //
+  // pi 1.0.4 changed what a non-empty `--tools` does to MCP tools. It no longer
+  // filters them: unless the list is empty or names an `mcp__` entry, they stay
+  // REGISTERED — reachable through codemode and `tool_search` — even though they
+  // are not *declared* to the model (`agent-session.js`: `_allowlistFiltersMcp`
+  // false → `_isAllowedTool` keeps them, `_isActivatable` withholds the
+  // declaration unless `tool_search` can load them). So the child's tool box is
+  // wider than the three names in the config, which is the hole ADR 0028 closed:
+  // `--no-mcp` stops the servers connecting at all, so there is nothing to reach.
+  // A config that wants the servers asks with `mcp: true` — verified against a
+  // live 1.2.0 child: with `--tools read` it sees exactly `read` either way, so
+  // the opt-in's observable effect today is registration, not a declared list
+  // (see ADR 0028's verification note for the open follow-up).
+  const tools = options.agent?.tools ?? [];
+  if (tools.length > 0) {
+    args.push("--tools", tools.join(","));
+    if (options.agent?.mcp !== true) {
+      args.push("--no-mcp");
+    }
   }
 
   // Always exclude the subagent tool itself to prevent infinite recursion

package/src/stream.test.ts

@@ -1,12 +1,39 @@
 import { EventEmitter } from "node:events";
 import { PassThrough } from "node:stream";
 import type { ChildProcess } from "node:child_process";
-import { describe, expect, it } from "vitest";
-import { getBus, Events } from "@pi-archimedes/core/bus";
+import { describe, expect, it, beforeEach } from "vitest";
+import { Events } from "@pi-archimedes/core/events";
 import { streamEvents, type StreamCallbacks } from "./stream.js";
 
 type FakeChild = ChildProcess & { stdout: PassThrough; stderr: PassThrough };
 
+/** Stands in for the host's `createEventBus()` — the emit/on/unsubscribe contract `pi.events` implements. */
+function fakeBus() {
+  const listeners = new Map<string, Array<(data: unknown) => void>>();
+  return {
+    emit(channel: string, data: unknown): void {
+      for (const handler of [...(listeners.get(channel) ?? [])]) handler(data);
+    },
+    on(channel: string, handler: (data: unknown) => void): () => void {
+      const subs = listeners.get(channel) ?? [];
+      subs.push(handler);
+      listeners.set(channel, subs);
+      return () => {
+        const current = listeners.get(channel) ?? [];
+        const idx = current.indexOf(handler);
+        if (idx !== -1) current.splice(idx, 1);
+      };
+    },
+  };
+}
+
+/** Fresh handle per test: the emitter is handed this, the assertions listen on it. */
+let bus: ReturnType<typeof fakeBus>;
+
+beforeEach(() => {
+  bus = fakeBus();
+});
+
 function fakeChild(): FakeChild {
   const child = new EventEmitter() as FakeChild;
   Object.assign(child, {
@@ -19,10 +46,10 @@ function fakeChild(): FakeChild {
 
 async function finishWith(
   events: Array<Record<string, unknown>>,
-  callbacks: StreamCallbacks = {},
+  callbacks: Partial<StreamCallbacks> = {},
 ) {
   const child = fakeChild();
-  const result = streamEvents(child, callbacks);
+  const result = streamEvents(child, { events: bus, ...callbacks } as StreamCallbacks);
   for (const event of events) {
     child.stdout.write(`${JSON.stringify(event)}\n`);
   }
@@ -65,10 +92,10 @@ describe("streamEvents todo mirroring", () => {
   it("mirrors the child-accepted state from result.details.todos", async () => {
     const updates: Array<{ source: string; todos: unknown[] }> = [];
     const clears: Array<{ source: string }> = [];
-    const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>
+    const off = bus.on(Events.TODOS_UPDATE, (p: unknown) =>
       updates.push(p as (typeof updates)[number]),
     );
-    const offClear = getBus().on(Events.TODOS_CLEAR, (p: unknown) =>
+    const offClear = bus.on(Events.TODOS_CLEAR, (p: unknown) =>
       clears.push(p as { source: string }),
     );
 
@@ -99,15 +126,16 @@ describe("streamEvents todo mirroring", () => {
     expect(updates[0]!.todos).toEqual([
       { content: "Fix auth", status: "pending" },
     ]);
-    // Bus re-drains queued events (emitted while unsubscribed) to the next
-    // subscriber, so stale "subagent:general" clears from earlier tests may
-    // be present — assert on the per-agent source instead of the raw count.
+    // Each test owns its handle now, so `clears` can only hold this test's
+    // emit — but the assertion stays source-scoped, because that is the
+    // contract a reader needs to see: the clear names the child it belongs to.
+    expect(clears.filter((c) => c.source === "subagent:t-acc")).toHaveLength(1);
     expect(clears.filter((c) => c.source === "subagent:t-acc")).toHaveLength(1);
   });
 
   it("mirrors nothing when the tool returned a validation rejection (result.isError)", async () => {
     const updates: Array<{ source: string; todos: unknown[] }> = [];
-    const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>
+    const off = bus.on(Events.TODOS_UPDATE, (p: unknown) =>
       updates.push(p as (typeof updates)[number]),
     );
 
@@ -139,7 +167,7 @@ describe("streamEvents todo mirroring", () => {
 
   it("mirrors nothing when the harness reported an error (event.isError)", async () => {
     const updates: Array<{ source: string; todos: unknown[] }> = [];
-    const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>
+    const off = bus.on(Events.TODOS_UPDATE, (p: unknown) =>
       updates.push(p as (typeof updates)[number]),
     );
 
@@ -166,7 +194,7 @@ describe("streamEvents todo mirroring", () => {
 
   it("falls back to normalized raw args when the accepted result has no details", async () => {
     const updates: Array<{ source: string; todos: unknown[] }> = [];
-    const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>
+    const off = bus.on(Events.TODOS_UPDATE, (p: unknown) =>
       updates.push(p as (typeof updates)[number]),
     );
 
@@ -194,7 +222,7 @@ 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) =>
+    const off = bus.on(Events.TODOS_UPDATE, (p: unknown) =>
       updates.push(p as (typeof updates)[number]),
     );
 
@@ -230,7 +258,7 @@ describe("streamEvents todo mirroring", () => {
 
   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) =>
+    const off = bus.on(Events.TODOS_UPDATE, (p: unknown) =>
       updates.push(p as (typeof updates)[number]),
     );
 
@@ -254,7 +282,7 @@ describe("streamEvents todo mirroring", () => {
 
   it("does not emit for non-todo tools with todoList-shaped args", async () => {
     const updates: Array<{ source: string; todos: unknown[] }> = [];
-    const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>
+    const off = bus.on(Events.TODOS_UPDATE, (p: unknown) =>
       updates.push(p as (typeof updates)[number]),
     );
 
@@ -293,10 +321,10 @@ describe("streamEvents todo mirroring", () => {
   it("uses a unique per-child source when the child provides a session id", async () => {
     const updates: Array<{ source: string; todos: unknown[] }> = [];
     const clears: Array<{ source: string }> = [];
-    const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>
+    const off = bus.on(Events.TODOS_UPDATE, (p: unknown) =>
       updates.push(p as (typeof updates)[number]),
     );
-    const offClear = getBus().on(Events.TODOS_CLEAR, (p: unknown) =>
+    const offClear = bus.on(Events.TODOS_CLEAR, (p: unknown) =>
       clears.push(p as { source: string }),
     );
 
@@ -345,3 +373,173 @@ describe("streamEvents todo mirroring", () => {
   });
 });
 
+
+// ── Run outcomes (CONTEXT.md: *Run outcome*; ADR 0028) ──────────────────────
+//
+// pi 1.2.0 made print mode exit 1 when the final response hit the output token
+// limit, and text-mode truncation is reported that way — so an exit code alone
+// can no longer tell a useful-but-cut-off answer from a crash. The child's own
+// `stopReason` and 1.1.0's `agent_settled.aborted` are what carry the
+// distinction; `agent_end` fires for a cancelled run too and says nothing about
+// either. Cost has to survive all three outcomes.
+
+const USAGE = {
+  input: 100,
+  output: 40,
+  cacheRead: 7,
+  cacheWrite: 2,
+  totalTokens: 149,
+  cost: { input: 0.001, output: 0.002, cacheRead: 0, cacheWrite: 0, total: 0.003 },
+};
+
+function assistantMessage(stopReason: string): Record<string, unknown> {
+  return {
+    type: "message_end",
+    message: {
+      role: "assistant",
+      content: [{ type: "text", text: "partial answer" }],
+      model: "anthropic/claude-opus-4.5",
+      stopReason,
+      usage: USAGE,
+    },
+  };
+}
+
+async function finishChild(
+  events: Array<Record<string, unknown>>,
+  close: [code: number | null, signal?: NodeJS.Signals | null],
+  stderr = "",
+) {
+  const child = fakeChild();
+  const result = streamEvents(child, { agent: "reviewer", task: "t", events: bus });
+  if (stderr) child.stderr.write(stderr);
+  for (const event of events) {
+    child.stdout.write(`${JSON.stringify(event)}\n`);
+  }
+  child.emit("close", close[0], close[1] ?? null);
+  return result;
+}
+
+describe("streamEvents run outcomes", () => {
+  it("a clean finish is `completed`", async () => {
+    const result = await finishChild(
+      [
+        assistantMessage("stop"),
+        { type: "agent_end", messages: [] },
+        { type: "agent_settled", aborted: false },
+      ],
+      [0],
+    );
+    expect(result.outcome).toBe("completed");
+    expect(result.error).toBeUndefined();
+  });
+
+  it("exit 1 with stopReason `length` is `truncated`, not a failure, and keeps the cost", async () => {
+    const result = await finishChild(
+      [
+        assistantMessage("length"),
+        { type: "agent_end", messages: [] },
+        { type: "agent_settled", aborted: false },
+      ],
+      [1],
+      "Response was truncated: the model reached its output token limit.\n",
+    );
+    expect(result.outcome).toBe("truncated");
+    expect(result.error).toBeUndefined();
+    expect(result.usage.cost).toBeCloseTo(0.003);
+    expect(result.usage.input).toBe(100);
+    expect(result.usage.output).toBe(40);
+  });
+
+  it("`--mode json` exits 0 for the same truncation, and it is still `truncated`", async () => {
+    // Verified on 1.2.0: the exit-1 mapping lives in print mode's *text* branch,
+    // so a json child reports truncation only through stopReason.
+    const result = await finishChild(
+      [assistantMessage("length"), { type: "agent_settled", aborted: false }],
+      [0],
+    );
+    expect(result.outcome).toBe("truncated");
+    expect(result.error).toBeUndefined();
+  });
+
+  it("`agent_settled.aborted: true` is `aborted`, whatever the exit code says", async () => {
+    // The child's print mode exits 143 when it is SIGTERM'd on the way out.
+    const result = await finishChild(
+      [assistantMessage("stop"), { type: "agent_settled", aborted: true }],
+      [143],
+    );
+    expect(result.outcome).toBe("aborted");
+    expect(result.error).toBeUndefined();
+    expect(result.usage.cost).toBeCloseTo(0.003);
+  });
+
+  it("a child killed by the abort signal before it settled is `aborted`", async () => {
+    const result = await finishChild([assistantMessage("stop")], [null, "SIGTERM"]);
+    expect(result.outcome).toBe("aborted");
+    expect(result.error).toBeUndefined();
+  });
+
+  it("a real SIGTERM'd child exits 143 with no signal and no settle event, and is still `aborted`", async () => {
+    // The shape a live 1.2.0 child actually produces when the parent's abort
+    // handler SIGTERMs it: print mode catches the signal and `process.exit(143)`,
+    // so there is no `signal`, and the process dies before it can emit
+    // `agent_settled`. Whatever it had printed to stderr (here, an unrelated
+    // provider warning) must not be promoted to an error.
+    const result = await finishChild([assistantMessage("stop")], [143], "LiteLLM discovery: warning");
+    expect(result.outcome).toBe("aborted");
+    expect(result.error).toBeUndefined();
+  });
+
+  it("an assistant message aborted at the provider is `aborted` even with no settle event", async () => {
+    const result = await finishChild([assistantMessage("aborted")], [0]);
+    expect(result.outcome).toBe("aborted");
+  });
+
+  it("a pre/during-run error stays a failure: no outcome, error from stderr", async () => {
+    const result = await finishChild(
+      [assistantMessage("error"), { type: "agent_settled", aborted: false }],
+      [1],
+      "401 unauthorized",
+    );
+    expect(result.outcome).toBeUndefined();
+    expect(result.error).toContain("401");
+  });
+
+  it("a nonzero exit with no run behind it stays a failure", async () => {
+    const result = await finishChild([], [2], "unknown flag --nope");
+    expect(result.outcome).toBeUndefined();
+    expect(result.error).toContain("unknown flag");
+  });
+
+  it("a failed run always says why, even on a clean exit with empty stderr", async () => {
+    // The shape a json child produces when the provider errors mid-run: the last
+    // assistant message ends `stopReason: "error"`, the exit code stays 0 (the
+    // code mapping is print mode's text branch) and stderr is empty. Without a
+    // synthesised explanation this is indistinguishable from a successful run.
+    const result = await finishChild(
+      [assistantMessage("error"), { type: "agent_settled", aborted: false }],
+      [0],
+    );
+    expect(result.outcome).toBeUndefined();
+    expect(result.error).toMatch(/stopReason|failed/i);
+  });
+
+  it("a crash on an unexpected signal is a failure, not a cancellation", async () => {
+    const result = await finishChild([assistantMessage("stop")], [null, "SIGSEGV"]);
+    expect(result.outcome).toBeUndefined();
+    expect(result.error).toBeTruthy();
+  });
+
+  it("the final progress carries the outcome, so the live view can show it", async () => {
+    const seen: Array<string | undefined> = [];
+    const result = await finishChild(
+      [assistantMessage("length"), { type: "agent_settled", aborted: false }],
+      [0],
+    ).then((r) => {
+      seen.push(r.progress?.outcome);
+      return r;
+    });
+    expect(seen).toEqual(["truncated"]);
+    expect(result.progress?.status).toBe("completed");
+  });
+});

package/src/stream.ts

@@ -1,7 +1,8 @@
 import { createInterface } from "node:readline";
 import type { ChildProcess } from "node:child_process";
+import type { EventBus } from "@earendil-works/pi-coding-agent";
 import type { StreamState, SubagentProgress, SubagentResult } from "./types.js";
-import { getBus, Events } from "@pi-archimedes/core/bus";
+import { Events, emitOn } from "@pi-archimedes/core/events";
 import { normalizeTodoItems, pickTodoListRaw } from "@pi-archimedes/todo/prepare-args";
 import {
   type JsonEvent,
@@ -11,11 +12,19 @@ import {
   handleMessageEnd,
   handleAgentEnd,
 } from "./handlers.js";
+import { decideRunOutcome } from "./run-outcome.js";
 
 export interface StreamCallbacks {
   agent?: string;
   task?: string;
   onProgress?: (progress: SubagentProgress) => void;
+  /**
+   * The parent's host handle (`pi.events`), injected. `streamEvents` is a plain
+   * function over a child process, so it has no `pi` of its own; the child's
+   * todo state is announced on the handle the caller is holding, which is the
+   * same one the todo package subscribed on in this process.
+   */
+  events: EventBus;
 }
 
 /**
@@ -27,7 +36,7 @@ export interface StreamCallbacks {
  */
 export function streamEvents(
   child: ChildProcess,
-  callbacks: StreamCallbacks = {},
+  callbacks: StreamCallbacks,
 ): Promise<SubagentResult> {
   return new Promise((resolve, reject) => {
     const startTime = Date.now();
@@ -175,7 +184,7 @@ export function streamEvents(
               const detailsTodos = (result?.details as Record<string, unknown> | undefined)?.todos;
               const todos = normalizeTodoItems(Array.isArray(detailsTodos) ? detailsTodos : stowed);
               if (todos) {
-                getBus().emit(Events.TODOS_UPDATE, { source: subagentSource, todos });
+                emitOn(callbacks.events, Events.TODOS_UPDATE, { source: subagentSource, todos });
               }
             }
           }
@@ -198,21 +207,48 @@ export function streamEvents(
           handleAgentEnd(state, event);
           break;
         }
+        case "agent_settled": {
+          // pi 1.1.0: the child's own statement that its run is over, and
+          // whether it was cancelled. `agent_end` fires for a cancelled run too
+          // (and can fire while a continuation is still pending), so this — not
+          // `agent_end` — is what an outcome is read from.
+          if (event.aborted === true) state.settledAborted = true;
+          break;
+        }
         // Ignore: agent_start, message_start, message_update, turn_end, tool_execution_update
       }
     });
 
     // Handle process exit
-    child.on("close", (code) => {
+    child.on("close", (code, signal) => {
       clearStartupTimer();
       clearInterval(heartbeat);
       const durationMs = Date.now() - startTime;
       const exitCode = code ?? 1;
 
-      // Surface stderr as error if the process failed and we have no other error
-      if (exitCode !== 0 && !error) {
+      const outcome = decideRunOutcome({
+        settledAborted: state.settledAborted === true,
+        stopReason: state.lastStopReason,
+        // The raw code, not `exitCode`: `null` is the difference between "it was
+        // killed" and "it failed", and the outcome table reads that difference.
+        exitCode: code,
+        signal: signal ?? undefined,
+      });
+
+      // stderr explains a failure and nothing else. A truncated run's stderr is
+      // pi's own "Response was truncated" notice and an aborted one's is noise —
+      // promoting either to `error` would report a real answer as a broken one.
+      if (outcome === "failed" && !error) {
         const stderr = Buffer.concat(stderrChunks).toString("utf-8").trim();
         if (stderr) error = stderr;
+        else if (code === null) error = `subagent terminated by ${signal ?? "a signal"}`;
+        // A json child that errored leaves nothing behind to read: the exit code
+        // stays 0 (the stopReason→code mapping is print mode's text branch) and
+        // stderr is clean, which used to make a failed run byte-identical to a
+        // successful one at this boundary. A failed run always says why.
+        else if (state.lastStopReason === "error")
+          error = 'subagent failed: the child\u2019s last response ended with stopReason "error"';
+        else error = `subagent failed with exit code ${code ?? "null"}`;
       }
 
       const result: SubagentResult = {
@@ -220,6 +256,7 @@ export function streamEvents(
         task: callbacks.task ?? "",
         ...(state.childSessionId ? { childSessionId: state.childSessionId } : {}),
         exitCode,
+        ...(outcome === "failed" ? {} : { outcome }),
         model: state.model,
         usage: {
           input: state.totalInput,
@@ -233,7 +270,8 @@ export function streamEvents(
         error,
         progress: {
           ...buildProgress(),
-          status: exitCode === 0 ? "completed" : "failed",
+          status: outcome === "failed" ? "failed" : "completed",
+          ...(outcome === "failed" ? {} : { outcome }),
           durationMs,
         },
         progressSummary: {
@@ -245,8 +283,8 @@ export function streamEvents(
 
       callbacks.onProgress?.(result.progress!);
 
-      // Clear subagent todos from the bus on exit
-      getBus().emit(Events.TODOS_CLEAR, {
+      // Clear subagent todos from the handle on exit
+      emitOn(callbacks.events, Events.TODOS_CLEAR, {
         source: subagentSource,
       });