@pi-archimedes/subagent 2.10.4 → 2.11.1

package/src/format.ts

@@ -1,4 +1,4 @@
-import type { SubagentResult } from "./types.js";
+import type { RunOutcome, SubagentResult } from "./types.js";
 
 export function formatTokens(n: number): string {
   if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + "M";
@@ -22,27 +22,6 @@ export function formatCost(cost: number): string {
   return "$" + cost.toFixed(2);
 }
 
-/**
- * Truncate plain text to a max character length, appending "..." if truncated.
- *
- * Unlike truncateToWidth from pi-tui, this does not handle wide characters or
- * measure ANSI display width. The benefit: the "..." is plain text so it
- * inherits any ANSI color wrapper applied around the result (pi-tui's
- * truncateToWidth appends "..." after closing color codes, leaving it unstyled).
- *
- * If the text contains newlines, truncates at the first newline boundary
- * rather than bleeding into the next line.
- */
-export function truncLine(text: string, maxLen: number): string {
-  // Check for newline first — it's a hard boundary regardless of length
-  const nlIdx = text.indexOf("\n");
-  if (nlIdx !== -1) {
-    return text.slice(0, nlIdx).slice(0, maxLen - 3) + "...";
-  }
-  if (text.length <= maxLen) return text;
-  return text.slice(0, maxLen - 3) + "...";
-}
-
 /**
  * Renders one section per parallel result. The header line is intentionally
  * byte-identical to the pre-#55 metrics summary (a contract, not an
@@ -50,20 +29,84 @@ export function truncLine(text: string, maxLen: number): string {
  * (finalOutput ?? error ?? "completed"), `trimEnd()`-ed so sections stay
  * separated by exactly one blank line, and is deliberately untruncated by
  * design (see docs/decisions/0020-subagent-parallel-full-output.md).
+ *
+ * A run that merely completed keeps that header exactly as it was. A truncated
+ * or aborted one says so on the row, because a "✓" the calling model has no way
+ * to check would be the worse kind of lie.
+ *
+ * The failure check reads `error`, not the exit code, and comes before the
+ * success marker: a `--mode json` child whose last response errored **exits 0**
+ * (`stream.ts` turns that into `error` with no `outcome`), and `index.ts` calls
+ * the same result `isError`. A header keyed off `exitCode` alone told the model
+ * the opposite of the flag on the tool result it was reading.
  */
 export function formatParallelResults(results: SubagentResult[]): string {
   const sections = results.map((r) => {
-    const status = r.exitCode === 0 ? "✓" : "✗";
+    const status =
+      r.outcome === "truncated"
+        ? "⚠ truncated"
+        : r.outcome === "aborted"
+          ? "⚠ aborted"
+          : r.error || r.exitCode !== 0
+            ? "✗"
+            : "✓";
     const summary = r.progressSummary
       ? `${r.progressSummary.toolCount} tools · ${Math.round(r.progressSummary.tokens / 1000)}k tok · ${Math.round(r.progressSummary.durationMs / 1000)}s`
       : "";
     const header = `${status} ${r.agent}${summary ? " " + summary : ""}`;
-    const body = (r.finalOutput ?? r.error ?? "completed").trimEnd();
+    const body = (r.finalOutput ?? r.error ?? fallbackBody(r)).trimEnd();
     return `${header}\n${body}`;
   });
   return sections.join("\n\n");
 }
 
+/** What to say when a result has neither output nor an error to show. */
+function fallbackBody(result: SubagentResult): string {
+  return result.outcome ? "(no output)" : "completed";
+}
+
+/**
+ * The single-run result text the calling model reads.
+ *
+ * The outcome is spelled out in words as well as carried in
+ * `details.results[].outcome`, because `content` is the half of the contract the
+ * model is guaranteed to see — and "this answer was cut off" is not something it
+ * can recover from the answer itself.
+ */
+export function formatSingleResult(result: SubagentResult): string {
+  const body = result.finalOutput ?? result.error ?? fallbackBody(result);
+  const note =
+    result.outcome === "truncated"
+      ? "[truncated: the subagent reached its output token limit — the answer above is partial]"
+      : result.outcome === "aborted"
+        ? "[aborted: the subagent run was cancelled — anything above is partial]"
+        : undefined;
+  return note ? `${body}\n\n${note}` : body;
+}
+
+/**
+ * The finished-run row, shared by the compact and expanded views.
+ *
+ * `undefined` means "nothing to report yet" (the run is still going), which is
+ * what leaves the callers' running / tool-call rendering untouched.
+ *
+ * The error text is not capped here: rows are cut at the width pi renders them
+ * at, by `RowBlock` (see `row-block.ts`). A fixed character cap is what made
+ * these rows die at a third of the frame on a wide terminal.
+ */
+export function buildOutcomeLine(
+  data: { outcome?: RunOutcome | undefined; error: string | undefined },
+  theme: { fg: (token: string, text: string) => string },
+): string | undefined {
+  if (data.error) return theme.fg("error", "✗ " + data.error);
+  if (data.outcome === "truncated") {
+    return theme.fg("warning", "⚠ Truncated — hit the output token limit, answer is partial");
+  }
+  if (data.outcome === "aborted") return theme.fg("warning", "⚠ Aborted");
+  if (data.outcome === "completed") return theme.fg("success", "✓ Done");
+  return undefined;
+}
+
 export interface StatsData {
   turns: number | undefined;
   toolCount: number | undefined;
@@ -96,9 +139,9 @@ export function buildStatsLine(
   return parts.map(p => theme.fg("dim", "· " + p)).join(" ");
 }
 
-// Build an agent label for display: "agentName: truncated task preview".
-// Truncation width of 60 keeps compact rows readable on standard terminal widths
-// while still showing meaningful task context.
+// Build an agent label for display: "agentName: task preview".
+// The task is passed through whole: the row it lands on is cut at the render
+// width by `RowBlock`, so the preview fills whatever frame pi draws it in.
 export function buildAgentLabel(
   agent: string,
   task: string | undefined,
@@ -106,7 +149,7 @@ export function buildAgentLabel(
 ): string {
   const name = theme.bold(agent);
   if (task) {
-    return name + theme.fg("dim", ": " + truncLine(task, 60));
+    return name + theme.fg("dim", ": " + task);
   }
   return name;
 }

package/src/frontmatter-io.test.ts

@@ -1,6 +1,13 @@
 import { describe, it, expect } from "vitest";
 import * as fc from "fast-check";
 import { validateAgentName, serializeAgent, AGENT_NAME_REGEX } from "./frontmatter-io.js";
+// Imported here rather than inside the tests below: nothing in this file mocks
+// `parseFrontmatter`, so a dynamic `await import()` in a test body only served
+// to charge whichever test ran first with loading the whole pi-coding-agent
+// package — measured at 2.6s alone, 6-7.8s on a loaded machine, against a 5s
+// per-test timeout. That is the "Test timed out in 5000ms" flake, and it lands
+// on collection instead, where no test budget is spent.
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "./agents.js";
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
@@ -117,3 +124,58 @@ describe("serializeAgent", () => {
     );
   });
 });
+
+// ── mcp round-trip (the writer's half of ADR 0028) ──────────────────────────
+
+describe("serializeAgent: mcp opt-in", () => {
+  it("writes the mcp key when the agent opts in", () => {
+    const output = serializeAgent(makeAgent({ tools: ["read", "bash"], mcp: true }));
+    expect(output).toContain("mcp: true");
+  });
+
+  it("writes no mcp key when the field is absent or false (closed is the default)", () => {
+    expect(serializeAgent(makeAgent({ tools: ["read"] }))).not.toContain("mcp:");
+    expect(serializeAgent(makeAgent({ tools: ["read"], mcp: false }))).not.toContain("mcp:");
+  });
+
+  it("survives a write → read round trip as a real boolean, not a string", () => {
+    const output = serializeAgent(makeAgent({ tools: ["read", "bash"], mcp: true }));
+    const { frontmatter } = parseFrontmatter(output);
+    expect(frontmatter.mcp).toBe(true);
+  });
+
+  it("keeps the tools list intact alongside the mcp key", () => {
+    const output = serializeAgent(makeAgent({ tools: ["read", "bash"], mcp: true }));
+    expect(output).toContain("tools: read, bash");
+    expect(output).toContain("mcp: true");
+  });
+});
+
+// ── One `tools:` key, whatever the config object looks like ───────────────
+
+describe("serializeAgent: never writes two tools keys", () => {
+  // The read path preserves an unreadable `tools:` in `extraFields` so a save
+  // cannot delete a line the user typed, while `applyToolEntries` owns the real
+  // `tools` field. If both are populated the file gets two `tools:` keys and the
+  // last one wins on the next read — which is the broken one.
+  const toolsKeys = (yaml: string): string[] =>
+    yaml.split("\n").filter((line) => /^tools:/.test(line));
+
+  it("writes the real field and drops the preserved raw value when both exist", () => {
+    const output = serializeAgent(
+      makeAgent({ tools: ["read"], extraFields: { tools: "read, +web_search", owner: "x" } }),
+    );
+    expect(toolsKeys(output)).toEqual(["tools: read"]);
+    expect(parseFrontmatter(output).frontmatter.tools).toBe("read");
+    // The unrelated extra still round-trips.
+    expect(output).toContain("owner: x");
+  });
+
+  it("still writes a preserved raw value when there is no parsed list to replace it", () => {
+    // This is the preservation the read path promised: an agent whose `tools:`
+    // was rejected keeps its line on save, rather than being silently rewritten
+    // without it.
+    const output = serializeAgent(makeAgent({ extraFields: { tools: "read, +web_search" } }));
+    expect(toolsKeys(output)).toEqual(["tools: read, +web_search"]);
+  });
+});

package/src/frontmatter-io.ts

@@ -65,8 +65,17 @@ export function serializeAgent(config: AgentConfig): string {
   lines.push(`description: ${quoteYamlValue(config.description)}`);
 
   // Optional known fields
-  if (config.tools && config.tools.length > 0) {
-    lines.push(`tools: ${quoteYamlValue(config.tools.join(", "))}`);
+  const toolsLine =
+    config.tools && config.tools.length > 0
+      ? `tools: ${quoteYamlValue(config.tools.join(", "))}`
+      : undefined;
+  if (toolsLine !== undefined) {
+    lines.push(toolsLine);
+  }
+  // Only the opt-in is written: a closed allowlist is the default, so the
+  // absence of the key is the meaningful statement (ADR 0028).
+  if (config.mcp === true) {
+    lines.push("mcp: true");
   }
   if (config.model) {
     lines.push(`model: ${quoteYamlValue(config.model)}`);
@@ -78,6 +87,11 @@ export function serializeAgent(config: AgentConfig): string {
   // Extra fields (sorted alphabetically)
   if (config.extraFields) {
     for (const key of Object.keys(config.extraFields).sort()) {
+      // `extraFields.tools` is the read path's copy of a `tools:` line it could
+      // not read, kept so a save cannot delete it. It only gets to speak for
+      // `tools:` when there is no parsed list to speak for it — otherwise this
+      // loop writes a second `tools:` key and the later one wins on reload.
+      if (key === "tools" && toolsLine !== undefined) continue;
       const value = config.extraFields[key]!;
       if (typeof value === "string") {
         lines.push(`${key}: ${quoteYamlValue(value)}`);

package/src/handlers.test.ts

@@ -4,9 +4,27 @@ import { extractArgsPreview } from "./handlers.js";
 // ── extractArgsPreview ──────────────────────────────────────────────────────
 
 describe("extractArgsPreview", () => {
-  it("returns string args truncated", () => {
-    const long = "a".repeat(200);
-    expect(extractArgsPreview(long)).toBe("a".repeat(120));
+  // The preview feeds a transcript row, and the row is what decides how much of
+  // it fits (`RowBlock` cuts at the width pi renders at). A cap here is therefore
+  // a second, invisible limit: cut it tighter than any terminal is wide and the
+  // row stops short of the frame with no cut marker, which is the defect #108
+  // set out to remove. pi's own bash row keeps the command whole for the same
+  // reason. It stays bounded, because the preview is carried in the streamed
+  // progress object for the life of the run.
+  it("keeps enough of a long command for a wide frame to draw", () => {
+    const long = "a".repeat(300);
+    expect(extractArgsPreview(long)).toBe(long);
+  });
+
+  it("still bounds what it returns, since the preview is streamed", () => {
+    const preview = extractArgsPreview("a".repeat(100_000));
+    expect(preview.length).toBeLessThan(1_000);
+  });
+
+  it("bounds the serialised form of object args too", () => {
+    const preview = extractArgsPreview({ a: "b".repeat(100_000), c: 1 });
+    expect(preview.length).toBeLessThan(1_000);
+    expect(preview.length).toBeGreaterThanOrEqual(300);
   });
 
   it("replaces newlines in string args", () => {

package/src/handlers.ts

@@ -1,7 +1,19 @@
 import type { StreamState } from "./types.js";
 
 // Truncation limits for previews
-const ARGS_PREVIEW_MAX = 120;
+//
+// The args preview is drawn on a transcript row, and the row is what decides how
+// much of it fits: `RowBlock` cuts at the width pi hands `render()` (see
+// `row-block.ts`). A cap here is therefore a second, invisible character limit —
+// the very defect #108 removed — because a preview shorter than the frame ends
+// mid-word with no cut marker. pi's own bash row keeps the command whole for the
+// same reason (`formatShellCall`). So this bound sits above anything a terminal
+// can draw, and exists only to keep the preview from growing the streamed
+// progress object without limit (it is carried for the life of the run).
+const ARGS_PREVIEW_MAX = 512;
+// `recentOutput` is carried in the progress object but drawn by no row, so it
+// keeps the old, tighter bound: widening it would only grow what is streamed.
+const OUTPUT_LINE_MAX = 120;
 const TOOL_CALLS_MAX = 50;
 const RECENT_OUTPUT_MAX = 50;
 
@@ -97,13 +109,13 @@ export function handleToolResult(state: StreamState, event: JsonEvent): void {
 
   if (typeof content === "string" && content.trim()) {
     const lines = content.split("\n").filter((l) => l.trim());
-    state.recentOutput.push(`[${toolName}] ${lines[0]?.slice(0, ARGS_PREVIEW_MAX)}`);
+    state.recentOutput.push(`[${toolName}] ${lines[0]?.slice(0, OUTPUT_LINE_MAX)}`);
   } else if (Array.isArray(content)) {
     for (const part of content) {
       if (part.type === "text" && (part.text as string)?.trim()) {
         const text = part.text as string;
         const lines = text.split("\n").filter((l) => l.trim());
-        state.recentOutput.push(`[${toolName}] ${lines[0]?.slice(0, ARGS_PREVIEW_MAX)}`);
+        state.recentOutput.push(`[${toolName}] ${lines[0]?.slice(0, OUTPUT_LINE_MAX)}`);
         break;
       }
     }
@@ -126,6 +138,13 @@ export function handleMessageEnd(state: StreamState, event: JsonEvent): void {
     state.model = message.model as string;
   }
 
+  // How this response ended. The LAST assistant message's stopReason is what
+  // decides the run's outcome (`length` ⇒ truncated, `aborted` ⇒ cancelled,
+  // `error` ⇒ failed) — the exit code cannot tell them apart.
+  if (typeof message.stopReason === "string") {
+    state.lastStopReason = message.stopReason;
+  }
+
   // Collect text + thinking output
   const content = message.content as Array<Record<string, unknown>> | string | undefined;
   if (typeof content === "string" && content.trim()) {

package/src/index.output-schema.test.ts

@@ -0,0 +1,317 @@
+/**
+ * Task 11 item 2 — `subagent` as a programmatic tool.
+ *
+ * `details` is the renderer's payload: per-run reports plus the live-progress
+ * blob (`progress`, with the child's whole streamed output and its tool-call
+ * history). A script wants the run reports, not the scrollback, so the
+ * structured content is the report set with `progress` left out — see the
+ * comment at the declaration in `index.ts`.
+ *
+ * `subagent` already reports failure as `isError` rather than throwing (ADR
+ * 0028), and that shape is unchanged here; what is new is that the failure
+ * results carry no structured content, so a script keeps rejecting with the
+ * text it rejects with today.
+ *
+ * `./agents.js` and `./execute.js` are mocked (as `index.test.ts` does) so the
+ * assertions are about the result contract rather than a real child process.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Value } from "typebox/value";
+
+const discoverAgents = vi.hoisted(() => vi.fn());
+const executeSubagent = vi.hoisted(() => vi.fn());
+const executeParallel = vi.hoisted(() => vi.fn());
+
+vi.mock("./agents.js", async (importOriginal) => ({
+  ...((await importOriginal()) as Record<string, unknown>),
+  discoverAgents,
+}));
+vi.mock("./execute.js", () => ({ executeSubagent, executeParallel }));
+
+const { registerSubagent } = await import("./index.js");
+const { formatSingleResult, formatParallelResults } = await import("./format.js");
+
+type RegisteredTool = {
+  name: string;
+  outputSchema?: unknown;
+  execute: (
+    id: string,
+    params: unknown,
+    signal: AbortSignal | undefined,
+    onUpdate: unknown,
+    ctx: unknown,
+  ) => Promise<{
+    content: Array<{ type: "text"; text: string }>;
+    details: unknown;
+    structuredContent?: unknown;
+    isError?: boolean;
+  }>;
+};
+
+function subagent(): RegisteredTool {
+  const tools: RegisteredTool[] = [];
+  registerSubagent({
+    registerTool: (t: unknown) => tools.push(t as RegisteredTool),
+    on: () => {},
+    getAllTools: () => [{ name: "read" }, { name: "bash" }],
+    events: { emit: () => {}, on: () => () => {} },
+  } as never);
+  const tool = tools.find((t) => t.name === "subagent");
+  if (!tool) throw new Error("subagent tool was not registered");
+  return tool;
+}
+
+function makeCtx(overrides: Record<string, unknown> = {}) {
+  return {
+    cwd: "/tmp",
+    model: undefined,
+    modelRegistry: { getAll: () => [], getAvailable: () => [] },
+    hasUI: true,
+    ui: { notify: vi.fn() },
+    ...overrides,
+  };
+}
+
+/** A completed run, with the live-progress blob a real stream would attach. */
+const okResult = {
+  agent: "reviewer",
+  task: "review it",
+  childSessionId: "child-uuid",
+  exitCode: 0,
+  outcome: "completed" as const,
+  usage: { input: 10, output: 5, cacheRead: 1, cacheWrite: 2, cost: 0.01, turns: 1 },
+  model: "anthropic/claude-opus-4.5",
+  finalOutput: "all good",
+  error: undefined,
+  progress: {
+    agent: "reviewer",
+    status: "completed" as const,
+    outcome: "completed" as const,
+    task: "review it",
+    currentTool: undefined,
+    currentToolArgs: undefined,
+    currentToolStartedAt: undefined,
+    toolCount: 1,
+    inputTokens: 10,
+    outputTokens: 5,
+    tokens: 15,
+    cost: 0.01,
+    durationMs: 10,
+    error: undefined,
+    model: "anthropic/claude-opus-4.5",
+    output: "the child's entire scrollback, which a script does not need twice",
+    recentOutput: ["x"],
+    toolCalls: [{ name: "read", argsPreview: "file", error: false }],
+  },
+  progressSummary: { toolCount: 1, tokens: 15, durationMs: 10 },
+};
+
+function agentConfig(overrides: Record<string, unknown> = {}) {
+  return {
+    name: "reviewer",
+    description: "d",
+    systemPrompt: "p",
+    source: "user",
+    filePath: "/tmp/agents/reviewer.md",
+    ...overrides,
+  };
+}
+
+function check(tool: RegisteredTool, value: unknown): boolean {
+  expect(tool.outputSchema, "subagent declares no outputSchema").toBeDefined();
+  return Value.Check(tool.outputSchema as never, value);
+}
+
+beforeEach(() => {
+  discoverAgents.mockReset();
+  executeSubagent.mockReset();
+  executeParallel.mockReset();
+  discoverAgents.mockReturnValue([agentConfig()]);
+  executeSubagent.mockResolvedValue(okResult);
+  executeParallel.mockResolvedValue([okResult]);
+});
+
+describe("subagent outputSchema", () => {
+  it("declares one, describing mode + results", () => {
+    const tool = subagent();
+    expect(tool.outputSchema).toBeDefined();
+    const props = (tool.outputSchema as { properties?: Record<string, unknown> }).properties ?? {};
+    expect(Object.keys(props).sort()).toEqual(["mode", "results"]);
+  });
+});
+
+describe("subagent structuredContent — single mode", () => {
+  it("a completed run reports itself structurally, without the live-progress blob", async () => {
+    const tool = subagent();
+    const result = await tool.execute("c1", { agent: "reviewer", task: "review it" }, undefined, undefined, makeCtx());
+
+    expect(result.content[0]!.text).toBe(formatSingleResult(okResult as never));
+    expect(result.isError).toBe(false);
+    expect(result.structuredContent).toEqual({
+      mode: "single",
+      results: [
+        {
+          agent: "reviewer",
+          task: "review it",
+          childSessionId: "child-uuid",
+          exitCode: 0,
+          outcome: "completed",
+          usage: { input: 10, output: 5, cacheRead: 1, cacheWrite: 2, cost: 0.01, turns: 1 },
+          model: "anthropic/claude-opus-4.5",
+          finalOutput: "all good",
+          progressSummary: { toolCount: 1, tokens: 15, durationMs: 10 },
+        },
+      ],
+    });
+    expect(check(tool, result.structuredContent)).toBe(true);
+    // The scrollback stays in `details` for the renderer, out of the structured payload.
+    expect(JSON.stringify(result.structuredContent)).not.toContain("scrollback");
+  });
+
+  it("a failed run is isError with no structured content, content text unchanged", async () => {
+    const failed = { ...okResult, outcome: undefined, error: "child crashed", finalOutput: undefined };
+    executeSubagent.mockResolvedValueOnce(failed);
+
+    const tool = subagent();
+    const result = await tool.execute("c1", { agent: "reviewer", task: "review it" }, undefined, undefined, makeCtx());
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toBe(formatSingleResult(failed as never));
+    expect("structuredContent" in result).toBe(false);
+  });
+
+  it("an unknown agent stays isError with the same text, and carries no structured content", async () => {
+    const tool = subagent();
+    const result = await tool.execute("c1", { agent: "ghost", task: "t" }, undefined, undefined, makeCtx());
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain('Unknown agent: "ghost"');
+    expect("structuredContent" in result).toBe(false);
+  });
+
+  it("a call with no task stays isError with the same text", async () => {
+    const tool = subagent();
+    const result = await tool.execute("c1", {}, undefined, undefined, makeCtx());
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toBe("Missing task parameter");
+    expect("structuredContent" in result).toBe(false);
+  });
+});
+
+describe("subagent structuredContent — parallel mode", () => {
+  it("reports every run, in task order", async () => {
+    // Both agents must exist, or the batch is rejected before anything runs.
+    discoverAgents.mockReturnValue([agentConfig(), agentConfig({ name: "explorer" })]);
+    const second = { ...okResult, agent: "explorer", task: "look around", finalOutput: "noted" };
+    executeParallel.mockResolvedValueOnce([okResult, second]);
+
+    const tool = subagent();
+    const result = await tool.execute(
+      "c2",
+      { tasks: [{ agent: "reviewer", task: "review it" }, { agent: "explorer", task: "look around" }] },
+      undefined,
+      undefined,
+      makeCtx(),
+    );
+
+    expect(result.content[0]!.text).toBe(formatParallelResults([okResult, second] as never));
+    const structured = result.structuredContent as { mode: string; results: Array<{ agent: string }> };
+    expect(structured.mode).toBe("parallel");
+    expect(structured.results.map((r) => r.agent)).toEqual(["reviewer", "explorer"]);
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("a rejected batch (unknown agent in one task) is isError, no structured content", async () => {
+    const tool = subagent();
+    const result = await tool.execute(
+      "c2",
+      { tasks: [{ agent: "ghost", task: "t" }] },
+      undefined,
+      undefined,
+      makeCtx(),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain("Unknown agent(s)");
+    expect("structuredContent" in result).toBe(false);
+  });
+});
+
+// The outcomes above tests never produced. `truncated` and `aborted` are declared
+// in `SUBAGENT_OUTPUT_SCHEMA`'s outcome union, and ADR 0028 makes them ordinary
+// successes (something was produced, so the run is not `isError`) — so their
+// reports reach the structured payload, and the declaration has to hold for them
+// too. Nothing here was previously exercised: the suite only ever handed back a
+// `completed` run.
+describe("subagent structuredContent — the other run outcomes", () => {
+  it.each(["truncated", "aborted"] as const)("%s run: not an error, carries a report, validates", async (outcome) => {
+    discoverAgents.mockReturnValue([agentConfig()]);
+    executeSubagent.mockResolvedValueOnce({ ...okResult, outcome, finalOutput: "a partial answer" });
+
+    const tool = subagent();
+    const result = await tool.execute("c3", { agent: "reviewer", task: "review it" }, undefined, undefined, makeCtx());
+
+    expect(result.isError).toBe(false);
+    const report = (result.structuredContent as { results: Array<Record<string, unknown>> }).results[0]!;
+    expect(report["outcome"]).toBe(outcome);
+    expect(report["error"]).toBeUndefined();
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("a run reporting almost nothing (no session id, model, output or summary) validates", async () => {
+    discoverAgents.mockReturnValue([]);
+    // The bare shape `executeSubagent` produces for a config-less run that had
+    // nothing else to report: every optional field absent, not present-and-null.
+    executeSubagent.mockResolvedValueOnce({
+      agent: "subagent",
+      task: "t",
+      exitCode: 0,
+      usage: { input: 1, output: 2, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 1 },
+    });
+
+    const tool = subagent();
+    const result = await tool.execute("c4", { task: "t" }, undefined, undefined, makeCtx());
+
+    expect(result.structuredContent).toEqual({
+      mode: "single",
+      results: [
+        {
+          agent: "subagent",
+          task: "t",
+          exitCode: 0,
+          usage: { input: 1, output: 2, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 1 },
+        },
+      ],
+    });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("a parallel batch with one failed run reports it per-run, inside a valid payload", async () => {
+    discoverAgents.mockReturnValue([agentConfig(), agentConfig({ name: "explorer" })]);
+    executeParallel.mockResolvedValueOnce([
+      okResult,
+      { ...okResult, agent: "explorer", task: "look around", outcome: undefined, finalOutput: undefined, error: "child died" },
+    ]);
+
+    const tool = subagent();
+    const result = await tool.execute(
+      "c5",
+      { tasks: [{ agent: "reviewer", task: "review it" }, { agent: "explorer", task: "look around" }] },
+      undefined,
+      undefined,
+      makeCtx(),
+    );
+
+    // The batch is not `isError` — it is, and was before these schemas existed:
+    // one run failing inside a batch is reported per run, in the text (`✗ explorer`)
+    // and in the report (`error`). `error` is declared optional for exactly this.
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0]!.text).toContain("✗ explorer");
+    const reports = (result.structuredContent as { results: Array<Record<string, unknown>> }).results;
+    expect(reports[1]!["error"]).toBe("child died");
+    expect(reports[0]!["error"]).toBeUndefined();
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+});