@pi-archimedes/subagent 2.11.0 → 2.11.2

package/README.md

@@ -44,7 +44,7 @@ The `agent` field is optional — omitting it is not a built-in default agent, a
 }
 ```
 
-**The dispatch waits.** A call — single or parallel — blocks until every task completes and returns the combined results, each optionally carrying the child's `childSessionId`. There is an `async` field in the schema; the implementation ignores it, so don't plan on fire-and-forget: batch the work into `tasks` and let the call block on all of it. In parallel mode each result section carries the child's final output beneath its metrics line.
+**The dispatch waits.** A call — single or parallel — blocks until every task completes and returns the combined results, each optionally carrying the child's `childSessionId`. There is no async mode: an `async` parameter was deleted in #114 because the schema declared it and the implementation ignored it, and a parameter the model is told about but nothing reads is a false promise. Implementing fire-and-forget is deferred to #113; until then, batch the work into `tasks` and let the call block on all of it. In parallel mode each result section carries the child's final output beneath its metrics line.
 
 ### Model and thinking resolution
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/subagent",
-  "version": "2.11.0",
+  "version": "2.11.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -15,8 +15,8 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "2.11.0",
-    "@pi-archimedes/todo": "2.11.0"
+    "@pi-archimedes/core": "2.11.2",
+    "@pi-archimedes/todo": "2.11.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=1.2.0",

package/src/expanded.test.ts

@@ -1,7 +1,8 @@
 import { describe, it, expect } from "vitest";
-import { buildExpandedText } from "./expanded.js";
-import type { RowSegment } from "./row-block.js";
-import type { SubagentResult } from "./types.js";
+import { stripTerminalSequences, visibleWidth } from "@earendil-works/pi-tui";
+import { buildExpandedText, buildProgressExpandedText, renderExpanded, renderProgressExpanded } from "./expanded.js";
+import { RowBlock, type RowSegment, RESET } from "./row-block.js";
+import type { RunOutcome, SubagentProgress, SubagentResult } from "./types.js";
 
 // The expanded row is what the user reads after `ctrl+o`; the compact row is
 // what they see while it runs. Both have to carry the *Run outcome* vocabulary
@@ -59,3 +60,413 @@ describe("expanded view: run outcomes", () => {
     expect(out).toContain("401 unauthorized");
   });
 });
+
+// ── A multi-line error, read in full (issue #112) ───────────────────────────
+
+/**
+ * What a failed child actually reports: a command line, a compiler diagnostic, a
+ * stack frame, and the exit status on the last line. The last line is the one
+ * whoever reads it wants (`rc=1` says what happened), and it is exactly what the
+ * row cut threw away — so every assertion below keys off it.
+ */
+const MULTI_LINE_ERROR = [
+  "Command failed: pnpm -r exec -- tsc --noEmit",
+  "packages/subagent/src/index.ts:42:7 - error TS2345: Argument of type 'string' is not assignable",
+  "    at runChild (/home/daniel/Coding/Javascript/pi-archimedes/packages/subagent/src/spawn.ts:88:12)",
+  "error: subagent exited with rc=1",
+].join("\n");
+const ERROR_LINES = MULTI_LINE_ERROR.split("\n");
+/** Everything after the head — the part that moved from the row into the block. */
+const TAIL_ERROR_LINES = ERROR_LINES.slice(1);
+const FIRST_ERROR_LINE = ERROR_LINES[0]!;
+const LAST_ERROR_LINE = ERROR_LINES[ERROR_LINES.length - 1]!;
+
+/** `theme.fg` for real SGR bytes, so the rendered lines carry an ANSI state. */
+const ERROR_SGR = "\x1b[31m";
+const sgrTheme = {
+  fg: (token: string, text: string) =>
+    `${token === "error" ? ERROR_SGR : "\x1b[2m"}${text}\x1b[0m`,
+  bold: (t: string) => `\x1b[1m${t}\x1b[0m`,
+};
+
+/** A `RowBlock` that remembers the segments it was last given, without faking the row layer. */
+class CapturingRowBlock extends RowBlock {
+  /** Named apart from `RowBlock`'s own private field of the same name. */
+  lastSegments: RowSegment[] | undefined = undefined;
+  /** A builder that handed its content over `setText` instead would land here. */
+  lastSetText: string | undefined = undefined;
+
+  override setSegments(segments: RowSegment[]): void {
+    this.lastSegments = segments;
+    super.setSegments(segments);
+  }
+
+  override setText(text: string): void {
+    this.lastSetText = text;
+    super.setText(text);
+  }
+}
+
+/**
+ * What the builder handed the row layer — asserted rather than assumed. Hooking
+ * `setText` and checking it here means a builder that switched to `setText`
+ * fails as a readable assertion instead of a `TypeError` on `lastSegments!`.
+ */
+function captured(rows: CapturingRowBlock): RowSegment[] {
+  expect(rows.lastSetText, "the builder handed its content over setText, so nothing below reads it")
+    .toBeUndefined();
+  expect(rows.lastSegments, "setSegments was never called, so nothing below reads the view").toBeDefined();
+  return rows.lastSegments!;
+}
+
+/** Strip this file's fake `theme.fg` markers, line by line — a block carries one per line. */
+const plainLines = (text: string): string[] => text.split("\n").map((l) => l.replace(/^\[[a-z]+\]/, ""));
+
+const content = (line: string): string => stripTerminalSequences(line).replace(/\s+$/, "");
+
+function makeProgress(overrides: Partial<SubagentProgress> = {}): SubagentProgress {
+  return {
+    agent: "reviewer",
+    status: "failed",
+    task: "review the diff",
+    currentTool: undefined,
+    currentToolArgs: undefined,
+    currentToolStartedAt: undefined,
+    toolCount: 2,
+    inputTokens: 10,
+    outputTokens: 5,
+    tokens: 15,
+    cost: 0.01,
+    durationMs: 1000,
+    error: MULTI_LINE_ERROR,
+    model: "anthropic/claude-opus-4.5",
+    output: undefined,
+    recentOutput: undefined,
+    toolCalls: undefined,
+    ...overrides,
+  };
+}
+
+/** A failed run: an error and no outcome, which is what `stream.ts` reports. */
+function failedResult(overrides: Partial<SubagentResult> = {}): SubagentResult {
+  const result = makeResult({ exitCode: 1, error: MULTI_LINE_ERROR, ...overrides });
+  // A failed run claims no outcome — `stream.ts` leaves the field off entirely.
+  if (!("outcome" in overrides)) delete result.outcome;
+  return result;
+}
+
+describe("expanded view: a multi-line error is readable in full (issue #112)", () => {
+  /**
+   * The guarantee, asserted the same way for all three builders: the error's last
+   * line is present, and a `block` carries it. `block` is this repo's mechanism
+   * for "read this in full" (`row-block.ts`; issue #112), so the assertion is on
+   * the segment kind rather than on the joined text — a change that pushes the
+   * error back through `row()` fails here even though the joined text would still
+   * contain the line.
+   *
+   * Order and grouping are asserted too, because a builder that emitted one block
+   * per line, or emitted the tail bottom-up, would satisfy the checks above: the
+   * tail is exactly one block and its lines are in the order the child wrote them.
+   */
+  const revealsTheWholeError = (segments: RowSegment[]): void => {
+    expect(drawnText(segments)).toContain(LAST_ERROR_LINE);
+    expect(
+      segments.filter((s) => s.text.includes(LAST_ERROR_LINE)).map((s) => s.kind),
+      "the error's last line is inside a row again",
+    ).toEqual(["block"]);
+    const heads = segments
+      .map((s, i) => ({ s, i }))
+      .filter(({ s }) => s.kind === "row" && s.text.includes(FIRST_ERROR_LINE));
+    expect(heads, "the error's first line is no longer the row it was").toHaveLength(1);
+    const tails = segments.filter(
+      (s) => s.kind === "block" && TAIL_ERROR_LINES.some((line) => s.text.includes(line)),
+    );
+    // One block, not one per line: `RowBlock` renders a block by wrapping it, so
+    // N blocks for N lines would draw the tail the same at a wide frame and hide
+    // the difference at a narrow one (where each block re-wraps on its own).
+    expect(tails, "the error's tail is not carried by exactly one block").toHaveLength(1);
+    const [tail] = tails;
+    expect(
+      tail === undefined ? [] : plainLines(tail.text),
+      "the error's tail block does not carry its lines in order",
+    ).toEqual(TAIL_ERROR_LINES);
+    expect(
+      segments.indexOf(tail!),
+      "the tail block was emitted before the row head, so the error reads bottom-up",
+    ).toBeGreaterThan(heads[0]!.i);
+  };
+
+  it("shows every line of a finished run's error, the last one as a block", () => {
+    const segments = buildExpandedText(failedResult(), undefined, theme);
+    revealsTheWholeError(segments);
+    // The marker convention survives: the first line is still the outcome row,
+    // with the ✗ error marker in front of it. Pinned exactly, because that row is
+    // what the collapsed view draws too — only the tail moves into a block.
+    const heads = segments.filter((s) => s.kind === "row" && s.text.includes("✗ "));
+    expect(heads).toEqual([{ kind: "row", text: "[error]✗ " + FIRST_ERROR_LINE }]);
+  });
+
+  it("shows every line of a streaming run's error, the last one as a block", () => {
+    const rows = new CapturingRowBlock();
+    renderProgressExpanded(rows, makeProgress({ status: "failed" }), theme);
+    revealsTheWholeError(captured(rows));
+  });
+
+  it("shows every line of a streaming parallel run's error, the last one as a block", () => {
+    revealsTheWholeError(buildProgressExpandedText(makeProgress({ status: "failed" }), theme));
+  });
+
+  // Both streaming builders choose this branch on `status === "completed" ||
+  // outcome`, and still pass `progress.error` down, where `outcomeSegments` reads
+  // `error` before `outcome` — mirroring `buildOutcomeLine` (`format.ts:101`).
+  // `stream.ts` only ever sets `error` for a failed run today, but `progress` is
+  // also data read back out of a persisted session, and the branch's own contract
+  // is "state or outcome, plus whatever error came with it" — so the error has to
+  // be revealed here too. Until now it was the one place the finished view's fix
+  // had not reached: same run, full error in `buildExpandedText`, one line here.
+  it("shows every line of a *completed* streaming run's error, not just a failed one's", () => {
+    const rows = new CapturingRowBlock();
+    renderProgressExpanded(rows, makeProgress({ status: "completed" }), theme);
+    revealsTheWholeError(captured(rows));
+  });
+
+  it("shows every line of a *completed* parallel streaming run's error", () => {
+    revealsTheWholeError(buildProgressExpandedText(makeProgress({ status: "completed" }), theme));
+  });
+
+  it("reveals the tail for a still-running progress that already carries an outcome", () => {
+    // The `|| progress.outcome` half of the same condition.
+    const rows = new CapturingRowBlock();
+    renderProgressExpanded(rows, makeProgress({ status: "running", outcome: "truncated" }), theme);
+    revealsTheWholeError(captured(rows));
+  });
+
+  it("draws the whole error on screen at a narrow width as well as a wide one", () => {
+    // Through the real row component, so this is about what lands on screen and
+    // not about the intermediate segments (the style of the width audit).
+    const [headLine, ...carriedLines] = MULTI_LINE_ERROR.split("\n");
+    for (const width of [200, 120, 80, 40]) {
+      const rows = new CapturingRowBlock();
+      renderExpanded(rows, failedResult(), undefined, sgrTheme);
+      const rendered = rows.render(width);
+      const joined = rendered.map(content).join("").replace(/\s+/g, "");
+      // Every line the block carries survives the wrap, whole. (The first line
+      // stays a row — cut at the frame like every other row, which is why it is
+      // not in this list.)
+      for (const line of carriedLines) {
+        // A wrapped line may break a long line across rows, so compare with the
+        // whitespace removed, exactly like the width audit does.
+        expect(joined, `line lost at ${width}: ${JSON.stringify(rendered.map(content))}`)
+          .toContain(line.replace(/\s+/g, ""));
+      }
+      // The last line — the one the old cut discarded outright — is on a row of
+      // its own rather than smeared across a wrap boundary.
+      expect(
+        rendered.map(content).some((l) => l.includes(carriedLines[carriedLines.length - 1]!)),
+        `last error line missing at ${width}: ${JSON.stringify(rendered.map(content))}`,
+      ).toBe(true);
+      // And the head is still there, cut the way a row cuts, marker and all.
+      expect(rendered.map(content)[0]).toContain("reviewer");
+      expect(
+        rendered.map(content).some((l) => l.includes("✗ " + headLine!.slice(0, 10))),
+        `error head missing at ${width}: ${JSON.stringify(rendered.map(content))}`,
+      ).toBe(true);
+      for (const line of rendered) {
+        expect(visibleWidth(line), `row over the frame at ${width}`).toBeLessThanOrEqual(width);
+      }
+    }
+  });
+
+  it("closes the error colour on every line it drew, so colour does not bleed", () => {
+    // Wide enough that nothing wraps: every logical line is one rendered line, so
+    // each one has to carry its own complete SGR pair. Handing `block` the whole
+    // `theme.fg("error", "✗ " + error)` string instead would open one span over
+    // every line and land the single reset on the last one only — the padding of
+    // the earlier lines then sits inside an open span.
+    const rows = new CapturingRowBlock();
+    renderExpanded(rows, failedResult(), undefined, sgrTheme);
+    const drawn = rows.render(200);
+    const errorLines = drawn.filter((l) => l.includes(ERROR_SGR));
+    expect(errorLines.length).toBe(MULTI_LINE_ERROR.split("\n").length);
+    for (const line of errorLines) {
+      expect(line.startsWith(ERROR_SGR), `line does not open its own span: ${JSON.stringify(line)}`)
+        .toBe(true);
+      expect(
+        line.trimEnd().endsWith(RESET),
+        `line leaves its span open across the padding: ${JSON.stringify(line)}`,
+      ).toBe(true);
+    }
+  });
+
+  it("leaves a single-line error exactly as it was rendered before", () => {
+    // Byte-identical: only the multi-line case changes, so every existing
+    // assertion about the outcome row keeps its meaning.
+    const failed = makeResult({ exitCode: 1, error: "401 unauthorized" });
+    delete failed.outcome;
+    const segments = buildExpandedText(failed, undefined, theme);
+    const outcome = segments.filter((s) => s.text.includes("401 unauthorized"));
+    expect(outcome).toEqual([{ kind: "row", text: "[error]✗ 401 unauthorized" }]);
+    // Counted as segments, because a segment's text is already multi-line: the
+    // claim is "the error reached the row layer exactly once", which a duplicate
+    // (the same line in a row *and* in a block) would fail.
+    expect(segments.filter((s) => s.text.includes("401"))).toHaveLength(1);
+  });
+
+  it("draws no blank row for an error that merely ends in a newline", () => {
+    // A trailing newline is not a line of content, and opening a block for it
+    // would add a blank row to the bottom of every failed run.
+    const failed = makeResult({ exitCode: 1, error: "401 unauthorized\n" });
+    delete failed.outcome;
+    const segments = buildExpandedText(failed, undefined, theme);
+    expect(segments.filter((s) => s.kind === "block" && s.text.trim() === "")).toEqual([]);
+    // And through the real row component, because the segment layer cannot see
+    // the failure this guards against: an emitted `row("")` is invisible in the
+    // list above yet `RowBlock` would draw it as a blank bottom row.
+    const rows = new CapturingRowBlock();
+    renderExpanded(rows, failed, undefined, theme);
+    const drawn = rows.render(200).map(content);
+    expect(drawn.filter((l) => l.includes("401"))).toHaveLength(1);
+    expect(
+      drawn[drawn.length - 1],
+      `a blank row was drawn under the outcome: ${JSON.stringify(drawn)}`,
+    ).toContain("401 unauthorized");
+  });
+
+  it("still lets the error win over the outcome, even when the error is multi-line", () => {
+    // Pinned as-is, not decided here: `outcomeSegments` reads `data.error`
+    // before the outcome — the same precedence `buildOutcomeLine` gives it — so an
+    // error and an outcome together report the error. Both halves of
+    // the text have to survive that precedence now that the error is a block.
+    const out = drawnText(
+      buildExpandedText(failedResult({ outcome: "truncated", finalOutput: "partial" }), undefined, theme),
+    );
+    expect(out).toContain(FIRST_ERROR_LINE);
+    expect(out).toContain(LAST_ERROR_LINE);
+    expect(out).not.toMatch(/Truncated/);
+  });
+
+  // The collapsed half of this asymmetry is pinned where that code lives, not here: `compact.test.ts` ("hands over three row segments carrying whole fields, so newlines reach the row cut") and `tool-row.width-audit.test.ts` ("keeps a multiline task or error to three rows per agent (collapsed)").
+
+  describe("a child that wrote CRLF line endings (a Windows child)", () => {
+    // `stream.ts` reads stderr as `Buffer.concat(...).toString("utf-8").trim()` —
+    // no newline normalisation — so `\r\n` arrives intact from a Windows child.
+    // `pi-tui`'s `wrapTextWithAnsi` splits on `/\r\n|\r|\n/` but `truncateRow`
+    // splits on `"\n"`, so a `\r` surviving the split rides inside a `row` and
+    // gets drawn: pi-tui does not strip it, and a terminal interpreting a bare CR
+    // rewinds the cursor to column 0 and paints the row over itself.
+    const CRLF_ERROR = ERROR_LINES.join("\r\n");
+
+    it("keeps every carriage return out of the segments and off the screen", () => {
+      const builders: Array<[string, () => RowSegment[]]> = [
+        ["buildExpandedText", () => buildExpandedText(failedResult({ error: CRLF_ERROR }), undefined, theme)],
+        ["renderProgressExpanded", () => {
+          const rows = new CapturingRowBlock();
+          renderProgressExpanded(rows, makeProgress({ status: "completed", error: CRLF_ERROR }), theme);
+          return captured(rows);
+        }],
+        ["buildProgressExpandedText", () => buildProgressExpandedText(makeProgress({ status: "failed", error: CRLF_ERROR }), theme)],
+      ];
+      for (const [name, build] of builders) {
+        const segments = build();
+        expect(
+          segments.filter((s) => s.text.includes("\r")).map((s) => s.text),
+          `${name} left a carriage return inside a segment`,
+        ).toEqual([]);
+      }
+      // Asserted on the RAW rendered lines: `content()` trims trailing whitespace,
+      // so it would swallow the very byte this is about.
+      for (const width of [200, 80]) {
+        const rows = new CapturingRowBlock();
+        renderExpanded(rows, failedResult({ error: CRLF_ERROR }), undefined, sgrTheme);
+        const rendered = rows.render(width);
+        for (const line of rendered) {
+          expect(JSON.stringify(line), `a bare CR was drawn at width ${width}`).not.toContain("\\r");
+        }
+        // Nothing was lost by the split either — every line still reaches the frame.
+        const joined = rendered.map(content).join("").replace(/\s+/g, "");
+        for (const line of ERROR_LINES) {
+          expect(joined, `line lost at ${width}: ${JSON.stringify(rendered.map(content))}`)
+            .toContain(line.replace(/\s+/g, ""));
+        }
+      }
+    });
+  });
+});
+
+// ── The fallback each builder keeps (the legacy-session shape) ──────────────
+
+describe("expanded view: a run with nothing to report falls back the way its own builder did", () => {
+  // `outcome` is optional (`types.ts:38,70,134`) and only populated from 8cf0d12
+  // (#103) on, so both shapes below reach the empty case: a session JSON persisted
+  // before it renders the finished view with `status:"completed"` and no outcome,
+  // and a progress that reports a terminal state and no outcome renders the two
+  // streaming views that way. Each site's fallback is load-bearing there, and they
+  // are *not* the same fallback: the finished view says `✗ Failed`, the two
+  // streaming views say `✓ Done`. Relabelling a completed run failed is how a
+  // useful answer gets thrown away by whoever reads it.
+  const saysDoneAndNeverFailed = (text: string): void => {
+    expect(text).toContain("✓ Done");
+    expect(text).not.toMatch(/Failed/);
+  };
+
+  it("says Done for a finished result that predates the outcome field", () => {
+    const legacy = makeResult();
+    delete legacy.outcome;
+    saysDoneAndNeverFailed(drawnText(buildExpandedText(legacy, undefined, theme)));
+  });
+
+  it("says Done for streaming progress that predates the outcome field", () => {
+    const rows = new CapturingRowBlock();
+    renderProgressExpanded(rows, makeProgress({ status: "completed", error: undefined }), theme);
+    saysDoneAndNeverFailed(drawnText(captured(rows)));
+  });
+
+  it("says Done for parallel streaming progress that predates the outcome field", () => {
+    saysDoneAndNeverFailed(
+      drawnText(buildProgressExpandedText(makeProgress({ status: "completed", error: undefined }), theme)),
+    );
+  });
+
+  it("still names a truncated or aborted streaming run by its outcome, not as failed", () => {
+    // The same sites, one step on from the legacy shape: a real outcome has to win
+    // over the caller's fallback, and `✓ Done` must not flatten it either.
+    for (const outcome of ["truncated", "aborted"] as const) {
+      const expected = outcome === "truncated" ? /truncated/i : /aborted/i;
+      const rows = new CapturingRowBlock();
+      renderProgressExpanded(rows, makeProgress({ status: "completed", outcome, error: undefined }), theme);
+      const streaming = drawnText(captured(rows));
+      expect(streaming, `renderProgressExpanded flattened ${outcome}`).toMatch(expected);
+      expect(streaming).not.toMatch(/Failed|✓ Done/);
+      const parallel = drawnText(
+        buildProgressExpandedText(makeProgress({ status: "completed", outcome, error: undefined }), theme),
+      );
+      expect(parallel, `buildProgressExpandedText flattened ${outcome}`).toMatch(expected);
+      expect(parallel).not.toMatch(/Failed|✓ Done/);
+    }
+  });
+
+  it("falls back to Failed on the finished view when a result reports nothing at all", () => {
+    // One door onto the finished view's bottom row: a result with neither an
+    // outcome nor an error and a nonzero exit — `buildExpandedText`'s own `else`,
+    // which keeps saying Failed because such a run has no success to claim.
+    const nothing = makeResult({ exitCode: 1 });
+    delete nothing.outcome;
+    const out = drawnText(buildExpandedText(nothing, undefined, theme));
+    expect(out).toContain("✗ Failed");
+    expect(out).not.toMatch(/✓ Done/);
+  });
+
+  it("falls back to Failed — not Done — for an outcome this build cannot name", () => {
+    // The other door, and the one that only exists now the fallback is the
+    // caller's: `outcome` set to something `buildOutcomeLine` has no case for (a
+    // session written by a newer build, or a widened *Run outcome* axis) leaves it
+    // returning `undefined`, and the segment `buildExpandedText` passes in is what
+    // gets drawn. It stays Failed — a run whose ending this code cannot read is
+    // not a success this code may claim — which is the byte this site rendered
+    // before the fallback moved, so moving it changed nothing here.
+    const unknown = makeResult({ exitCode: 1, outcome: "detached" as RunOutcome });
+    const out = drawnText(buildExpandedText(unknown, undefined, theme));
+    expect(out).toContain("✗ Failed");
+    expect(out).not.toMatch(/✓ Done/);
+  });
+});

package/src/expanded.ts

@@ -6,12 +6,18 @@ import { renderToolCallLine } from "@pi-archimedes/core/tool-render";
 type Theme = { fg: (token: string, text: string) => string; bold: (text: string) => string };
 
 // The expanded view mixes two kinds of line and says which is which (see
-// `row-block.ts`): a **row** (label, activity, outcome) stays one line and fills
-// the frame; a **block** (the stats line, the task text, the tool-call history,
-// the output) keeps wrapping, because the expanded view is where all of it is
-// meant to be readable (ADR 0020). The stats line is a block and not a row
-// because nothing else repeats its numbers: cut at the frame, its tail — tokens,
-// duration, cost — would simply be gone on a narrow terminal.
+// `row-block.ts`): a **row** (label, activity, the first line of an outcome) stays
+// one line and fills the frame; a **block** (the stats line, the task text, the
+// tool-call history, the output, the lines of an error after the first) keeps
+// wrapping, because the expanded view is where all of it is meant to be readable
+// (issue #112; its counterpart — the collapsed view cutting at the first line — is
+// pinned in `tool-row.width-audit.test.ts`). The stats line is a block and not a
+// row so the view reads on its own, without the reader collapsing back to the row
+// to get the numbers back. They do live elsewhere too — `compact.ts` builds the
+// identical `buildStatsLine`, `formatParallelResults` puts tools / tokens /
+// seconds in the model-facing content, and `usage` reaches pi's `/session` — but
+// every row is cut at the frame, so the tail of the stats (tokens, duration,
+// cost) is exactly what a narrow terminal would drop from this view.
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -27,18 +33,74 @@ function formatToolCall(call: SubagentToolCall | string, theme: Theme): string {
   return renderToolCallLine(status, call.name, suffix, theme);
 }
 
-// The bottom row of a finished view. The *Run outcome* wins over the done/failed
+// The bottom of an expanded view. The *Run outcome* wins over the done/failed
 // pair: a truncated answer is not a failed run, and labelling it "✗ Failed" is
 // how a useful answer gets thrown away by whoever reads it.
-function outcomeRow(
+//
+// An error is often stderr or a thrown Error's message — the second kind never
+// touched a stream (`dispatch.ts`'s `buildFailedResult` carries `err.message`, and
+// `stream.ts` synthesises strings like "subagent failed with exit code N"). Either
+// way it arrives with newlines in it, and as one `row` the view could only ever
+// show its first line: `truncateRow` treats a newline as a hard boundary (see
+// `row-block.ts`), which is right for the collapsed view (the three-rows-per-agent
+// shape is pinned in `tool-row.width-audit.test.ts`) and wrong here: the expanded
+// view is where everything is meant to be readable (issue #112), and a stack
+// trace's last line is usually the informative one. So the first line stays the
+// row it was, and the lines after it are handed over as one `block` — this repo's
+// existing mechanism for "read this in full".
+//
+// The raw error is split *before* anything is coloured, and every line is
+// coloured on its own. `theme.fg("error", "✗ " + error)` wraps the whole
+// multi-line string in one span whose reset lands on the last line only, so
+// every earlier line would be drawn — padding included — inside an open span.
+// Measured against `wrapTextWithAnsi`: it re-opens the active codes at the start
+// of a continuation line but never invents a reset at the end of one.
+function outcomeSegments(
   data: { outcome?: RunOutcome | undefined; error: string | undefined },
   theme: Theme,
-  fallback: { failed: string },
-): string {
-  const line = buildOutcomeLine({ outcome: data.outcome, error: data.error }, theme);
-  if (line) return line;
-  if (data.error) return theme.fg("error", "✗ " + data.error);
-  return theme.fg("error", "✗ " + fallback.failed);
+  // The segment to draw when there is nothing to report, rendered by the caller
+  // rather than decided here, because the five call sites do not agree on it — and
+  // they disagree per *branch*, not per builder: the finished view's single call
+  // says `✗ Failed` (an `outcome` this build cannot name is not a success this
+  // build may claim), while each streaming builder passes `✓ Done` from its
+  // completed branch and `✗ Failed` from its failed one. So "nothing to report"
+  // means something different at each site, and the `✓ Done` ones are why the
+  // answer cannot be baked in here: `outcome` is optional on `SubagentProgress`
+  // (`types.ts:38`; `SubagentResult` at `:70`, `SubagentRunReport` at `:134`), so a
+  // run can report a terminal status with no outcome at all — every session
+  // persisted before #103 / 8cf0d12 added the field — and a helper-wide
+  // `✗ Failed` there would relabel a finished run a broken one.
+  fallback: RowSegment,
+): RowSegment[] {
+  // Same precedence as `buildOutcomeLine` (`format.ts:101`): `error` is read first,
+  // so a run that carries both reports the error and not the outcome. Pinned in
+  // `expanded.test.ts` rather than re-decided here. It is also why neither streaming
+  // branch may assume it has no error in hand: each opens on a completed *status* or
+  // on any reported outcome, and either can arrive together with a multi-line one,
+  // so a completed progress's error gets the same head-row-then-block treatment here
+  // that the failed branch gives its own (#112).
+  if (data.error) {
+    // `/\r\n|\r|\n/`, not `"\n"`: `stream.ts` reads stderr as
+    // `Buffer.concat(...).toString("utf-8").trim()` with no newline
+    // normalisation, so a Windows child's `\r\n` arrives intact. pi-tui's
+    // `wrapTextWithAnsi` splits on all three endings but `truncateRow` splits on
+    // `"\n"`, so a `\r` left inside a row would be *drawn*, and a terminal that
+    // honours a bare CR repaints the row from column 0.
+    const [head, ...tail] = data.error.split(/\r\n|\r|\n/);
+    const segments: RowSegment[] = [row(theme.fg("error", "✗ " + head))];
+    // A tail of nothing but blanks gets no block: a synthesised error, or any
+    // producer that does not `trim()` its stderr, can end in a newline, and
+    // opening a block for that would add a blank row under every failed run.
+    if (tail.some((line) => line.trim() !== "")) {
+      segments.push(block(tail.map((line) => (line ? theme.fg("error", line) : "")).join("\n")));
+    }
+    return segments;
+  }
+  const line = buildOutcomeLine({ outcome: data.outcome, error: undefined }, theme);
+  // The outcome vocabulary stays `buildOutcomeLine`'s and this helper still owns
+  // the row decision; only "nothing to report" hands back the segment the caller
+  // rendered for itself.
+  return [line === undefined ? fallback : row(line)];
 }
 
 // ── Expanded completed result ───────────────────────────────────────────────
@@ -65,9 +127,9 @@ export function buildExpandedText(
   }, theme);
   const statsParts = [modelLabel, statsLine].filter(Boolean);
   if (statsParts.length > 0) {
-    // A block, not a row: this is the only place the run's numbers appear, and
-    // the expanded view is where they are meant to be readable however narrow
-    // the frame is (ADR 0020).
+    // A block, not a row: the expanded view has to read on its own, so the
+    // numbers cannot depend on the reader collapsing the row to get them back
+    // however narrow the frame is.
     lines.push(block(statsParts.join(" ")));
   }
 
@@ -90,6 +152,11 @@ export function buildExpandedText(
   const outputText = progress?.output ?? result.finalOutput;
   if (outputText) {
     lines.push(row(""));
+    // A block, uncapped: ADR 0020 is the precedent that this package does not cap
+    // output where the reader has no other source for it. Read it precisely — ADR
+    // 0020 governs the *tool-result content* the model reads, not this view — and
+    // the same reasoning carries over: the answer shown here is the child's, and
+    // nothing else spells it out for whoever is reading the transcript.
     lines.push(block(outputText));
   }
 
@@ -97,7 +164,20 @@ export function buildExpandedText(
   if (result.error || result.outcome || result.exitCode === 0) {
     lines.push(row(""));
     if (result.outcome || result.error) {
-      lines.push(row(outcomeRow({ outcome: result.outcome, error: result.error }, theme, { failed: "Failed" })));
+      // The fallback covers exactly one case here: an `outcome` this build cannot
+      // name, which leaves `buildOutcomeLine` with nothing to return. It is
+      // Failed, because a run whose ending this code cannot read is not a success
+      // this code may claim. The never-settled legacy shape — no outcome, no
+      // error, a non-zero exit — is not this fallback's: the `else` below prints
+      // it. The streaming builders' completed branch passes ✓ Done instead (see
+      // `outcomeSegments`' third parameter for why it is not decided here).
+      lines.push(
+        ...outcomeSegments(
+          { outcome: result.outcome, error: result.error },
+          theme,
+          row(theme.fg("error", "✗ Failed")),
+        ),
+      );
     } else {
       lines.push(row(theme.fg("success", "✓ Done")));
     }
@@ -170,14 +250,25 @@ export function renderProgressExpanded(
     lines.push(row(renderToolCallLine("running", progress.currentTool, suffix, theme)));
   }
 
-  // Status at bottom
+  // Status at bottom. Which fallback each branch hands the helper, and why the
+  // helper is not the one to decide it, is written once above `outcomeSegments`.
   if (progress.status === "completed" || progress.outcome) {
     lines.push(row(""));
-    const outcomeLine = buildOutcomeLine({ outcome: progress.outcome, error: progress.error }, theme);
-    lines.push(row(outcomeLine ?? theme.fg("success", "✓ Done")));
+    // `✓ Done`: this branch's agent reached a terminal state, so a run with nothing
+    // to name its outcome by is finished work here — the ✗ below would bury it.
+    lines.push(...outcomeSegments(
+      { outcome: progress.outcome, error: progress.error },
+      theme,
+      row(theme.fg("success", "✓ Done")),
+    ));
   } else if (progress.status === "failed") {
     lines.push(row(""));
-    lines.push(row(outcomeRow({ outcome: undefined, error: progress.error }, theme, { failed: "Failed" })));
+    // The only branch here that may call a run broken, so it passes `✗ Failed`.
+    lines.push(...outcomeSegments(
+      { outcome: undefined, error: progress.error },
+      theme,
+      row(theme.fg("error", "✗ Failed")),
+    ));
   }
 
   rows.setSegments(lines);
@@ -240,14 +331,27 @@ export function buildProgressExpandedText(
     lines.push(row(line));
   }
 
-  // Status at bottom
+  // Status at bottom — the same pair of branches `renderProgressExpanded` draws for
+  // the single running agent, here as one block of the parallel view. What each
+  // branch passes, and why the helper cannot decide it, is written once above
+  // `outcomeSegments`.
   if (progress.status === "completed" || progress.outcome) {
     lines.push(row(""));
-    const outcomeLine = buildOutcomeLine({ outcome: progress.outcome, error: progress.error }, theme);
-    lines.push(row(outcomeLine ?? theme.fg("success", "✓ Done")));
+    // `✓ Done`, and never the failed branch's segment: this block claims its agent
+    // finished, and a batch read as failed is a batch whose answers get discarded.
+    lines.push(...outcomeSegments(
+      { outcome: progress.outcome, error: progress.error },
+      theme,
+      row(theme.fg("success", "✓ Done")),
+    ));
   } else if (progress.status === "failed") {
     lines.push(row(""));
-    lines.push(row(outcomeRow({ outcome: undefined, error: progress.error }, theme, { failed: "Failed" })));
+    // `✗ Failed`: this branch got a broken run, the only one allowed to say so.
+    lines.push(...outcomeSegments(
+      { outcome: undefined, error: progress.error },
+      theme,
+      row(theme.fg("error", "✗ Failed")),
+    ));
   }
 
   return lines;

package/src/index.test.ts

@@ -484,3 +484,83 @@ describe("dispatch: cost is reported natively, not on the bus", () => {
     expect(busEmits.filter(([channel]) => channel === Events.COST_UPDATE)).toEqual([]);
   });
 });
+
+// The shape handed to the executor, pinned as data.
+//
+// `index.ts` maps each incoming task into the object `executeParallel` receives
+// (and builds the single equivalent for `executeSubagent`). That map is the only
+// place a per-task `cwd` or `model` reaches the child, and it had no guard: the
+// tests above drive both branches through the mocked executors and assert the
+// outcome, never the argument, so deleting a forwarded key stayed green
+// everywhere. This is the behavioural replacement for the source-text scanner
+// deleted in the same branch: it pins what is actually handed over by running the
+// tool, instead of parsing `index.ts` and risking a red run on an unrelated edit.
+// It is a narrower claim than the scanner's — it says nothing about whether the
+// executor later reads a key it is given — see the header of
+// `tool-schema.test.ts`, which states the residue that leaves uncovered.
+describe("dispatch: the object forwarded to the executor", () => {
+  it("forwards the full per-task shape to executeParallel", async () => {
+    discoverAgents.mockReturnValue([agentConfig()]);
+    await subagent(register()).execute(
+      "c",
+      { tasks: [{ agent: "reviewer", task: "a", model: "anthropic/claude-opus-4.5", cwd: "/tmp/work" }] },
+      undefined,
+      undefined,
+      makeCtx(),
+    );
+
+    expect(executeParallel).toHaveBeenCalledTimes(1);
+    const calls = executeParallel.mock.calls as unknown as Array<[{ tasks: Array<Record<string, unknown>> }]>;
+    const forwarded = calls[0]![0].tasks[0]!;
+    // Exact and sorted, so it fails in both directions: dropping a forward
+    // (`cwd`, `model`, …) silently loses a documented per-task option, and
+    // adding one changes the executor's input contract.
+    expect(Object.keys(forwarded).sort()).toEqual([
+      "activeModel",
+      "agent",
+      "agentConfig",
+      "cwd",
+      "model",
+      "task",
+      "toolCallId",
+    ]);
+    // The key set alone would still pass with the values swapped or dropped to
+    // undefined, so the two the #114 discussion cares about are pinned by value.
+    expect(forwarded.cwd).toBe("/tmp/work");
+    expect(forwarded.model).toBe("anthropic/claude-opus-4.5");
+    expect(forwarded.task).toBe("a");
+    expect(forwarded.toolCallId).toBe("c");
+  });
+
+  it("forwards the same per-task shape to executeSubagent on the single-run path", async () => {
+    discoverAgents.mockReturnValue([agentConfig()]);
+    await subagent(register()).execute(
+      "c",
+      { agent: "reviewer", task: "t", model: "anthropic/claude-opus-4.5", cwd: "/tmp/work" },
+      undefined,
+      undefined,
+      makeCtx(),
+    );
+
+    expect(executeSubagent).toHaveBeenCalledTimes(1);
+    const calls = executeSubagent.mock.calls as unknown as Array<[Record<string, unknown>]>;
+    const forwarded = calls[0]![0];
+    // The single path takes its arguments flat rather than nested under `tasks`,
+    // so its key set differs from the parallel item's by exactly that: no
+    // nesting, and `signal` / `events` / `onUpdate` carried per run.
+    expect(Object.keys(forwarded).sort()).toEqual([
+      "activeModel",
+      "agent",
+      "agentConfig",
+      "cwd",
+      "events",
+      "model",
+      "onUpdate",
+      "signal",
+      "task",
+      "toolCallId",
+    ]);
+    expect(forwarded.cwd).toBe("/tmp/work");
+    expect(forwarded.model).toBe("anthropic/claude-opus-4.5");
+  });
+});

package/src/index.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Text, type TUI } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { SUBAGENT_PARAMS_SCHEMA, SUBAGENT_OUTPUT_SCHEMA, subagentStructuredContent } from "./tool-schema.js";
+import { SUBAGENT_PARAMS_SCHEMA, SUBAGENT_OUTPUT_SCHEMA, subagentStructuredContent, type SubagentParams } from "./tool-schema.js";
 import { executeSubagent, executeParallel } from "./execute.js";
 import { formatParallelResults, formatSingleResult } from "./format.js";
 // agent-manager.js lazy-loaded below to keep subagent tool registration fast
@@ -71,14 +71,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
 
     async execute(
       _id: string,
-      params: {
-        agent?: string;
-        task?: string;
-        tasks?: Array<{ agent?: string; task: string; count?: number; model?: string; cwd?: string }>;
-        model?: string;
-        cwd?: string;
-        async?: boolean;
-      },
+      params: SubagentParams,
       signal: AbortSignal | undefined,
       onUpdate: ((update: SubagentToolResult) => void) | undefined,
       ctx: ExtensionContext,

package/src/row-block.test.ts

@@ -14,12 +14,11 @@
  */
 
 import { describe, it, expect } from "vitest";
-import { Text, stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { RowBlock, block, row, truncateRow } from "./row-block.js";
+import { Box, Text, stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { RowBlock, block, row, truncateRow, RESET } from "./row-block.js";
 
-const dim = (t: string) => `\x1b[2m${t}\x1b[0m`;
-const bold = (t: string) => `\x1b[1m${t}\x1b[0m`;
-const RESET = "\x1b[0m";
+const dim = (t: string) => `\x1b[2m${t}${RESET}`;
+const bold = (t: string) => `\x1b[1m${t}${RESET}`;
 
 const drawn = (line: string) => visibleWidth(stripTerminalSequences(line).replace(/\s+$/, ""));
 
@@ -93,6 +92,42 @@ describe("truncateRow", () => {
     }
   });
 
+  it("never emits a full SGR reset (\\x1b[0m) that would kill a container Box background", () => {
+    // Both when cut on width and when cut on a newline
+    const cutOnWidth = truncateRow(dim(LONG), 40);
+    expect(cutOnWidth.includes("\x1b[0m")).toBe(false);
+    expect(cutOnWidth.includes("\x1b[m")).toBe(false);
+
+    const cutOnNewline = truncateRow("general: Check status\nsecond line", 80);
+    expect(cutOnNewline.includes("\x1b[0m")).toBe(false);
+    expect(cutOnNewline.includes("\x1b[m")).toBe(false);
+
+    // Embedded \x1b[0m is safely converted to style reset
+    const embedded = truncateRow("\x1b[31merror\x1b[0m: details", 80);
+    expect(embedded.includes("\x1b[0m")).toBe(false);
+    expect(embedded.includes("\x1b[m")).toBe(false);
+  });
+
+  it("preserves an enclosing Box background across the entire row including padding", () => {
+    const bgFn = (t: string) => `\x1b[48;2;33;34;44m${t}\x1b[49m`;
+    const box = new Box(1, 1, bgFn);
+    const rows = new RowBlock();
+    rows.setSegments([
+      row("general: Check the status of PR #23 on danielcherubini/archimedes:\nsomething else"),
+    ]);
+    box.addChild(rows);
+    const lines = box.render(100);
+    // Line 1 is the content row
+    const contentLine = lines[1]!;
+    expect(contentLine).toBeDefined();
+    // Background escape was applied at the start and closed at the end
+    expect(contentLine.startsWith("\x1b[48;2;33;34;44m")).toBe(true);
+    expect(contentLine.endsWith("\x1b[49m")).toBe(true);
+    // No full reset in the middle that would kill the background before the padding
+    expect(contentLine.includes("\x1b[0m")).toBe(false);
+    expect(contentLine.includes("\x1b[m")).toBe(false);
+  });
+
   it("survives widths with no room for an ellipsis", () => {
     expect(truncateRow(LONG, 3)).toBe("...");
     expect(truncateRow(LONG, 2)).toBe("..");
@@ -192,4 +227,18 @@ describe("RowBlock", () => {
     const lines = rows.render(60);
     for (const line of lines) expect(padTo(line, 60)).toBe(line);
   });
+
+  it("sanitizes embedded \\x1b[0m in block segments to RESET when rendered and padded", () => {
+    const rows = new RowBlock();
+    rows.setSegments([block("\x1b[31merror message\x1b[0m: line one\nsecond line with \x1b[32msuccess\x1b[m details")]);
+    const lines = rows.render(80);
+    expect(lines.length).toBe(2);
+    for (const line of lines) {
+      expect(line.includes("\x1b[0m")).toBe(false);
+      expect(line.includes("\x1b[m")).toBe(false);
+      expect(visibleWidth(line)).toBe(80);
+    }
+    expect(lines[0]!).toContain(`\x1b[31merror message${RESET}: line one`);
+    expect(lines[1]!).toContain(`second line with \x1b[32msuccess${RESET} details`);
+  });
 });

package/src/row-block.ts

@@ -27,8 +27,28 @@ import { Text, sliceByColumn, visibleWidth, wrapTextWithAnsi } from "@earendil-w
 /** The marker appended to a row that was cut. Plain text, so it inherits colour. */
 export const ROW_ELLIPSIS = "...";
 
-/** SGR reset, appended after a cut so the row's padding is not painted. */
-const RESET = "\x1b[0m";
+/**
+ * SGR reset for styled rows: resets foreground color and font styles (bold,
+ * dim, italic, underline, reverse video, strikethrough), but never resets the
+ * background color (SGR 49).
+ *
+ * Inside pi's tool execution component, rows are rendered inside a Box that
+ * applies a panel background (e.g. toolSuccessBg / toolPendingBg) across the
+ * entire row: `theme.bg(token, paddedLine)`. A full SGR reset (`\x1b[0m` or
+ * `\x1b[m`) cancels the Box-painted background mid-line, causing all subsequent
+ * padding spaces and trailing content to fall through to the terminal's default
+ * background (appearing as an unsightly mid-grey or mismatched bar after
+ * truncated text or early newlines).
+ */
+export const RESET = "\x1b[22;23;24;27;29;39m";
+
+/**
+ * Replace any full SGR resets (\x1b[0m or \x1b[m) with a style-and-foreground reset
+ * so the line never kills an enclosing container's background color mid-line.
+ */
+export function sanitizeRowResets(line: string): string {
+  return line.replace(/\x1b\[0?m/g, RESET);
+}
 
 /** How `Text` renders a tab; kept identical so short rows stay byte-identical. */
 const TAB_WIDTH = 3;
@@ -82,13 +102,16 @@ export function truncateRow(line: string, width: number): string {
   if (width <= 0) return "";
   const nlIdx = line.indexOf("\n");
   const firstLine = nlIdx === -1 ? line : line.slice(0, nlIdx);
-  if (nlIdx === -1 && visibleWidth(firstLine) <= width) return firstLine;
+  if (nlIdx === -1 && visibleWidth(firstLine) <= width) {
+    return sanitizeRowResets(firstLine);
+  }
 
   const budget = width - ROW_ELLIPSIS.length;
   // No room for both content and dots: show as many dots as the frame holds, so
   // the row still reads as "cut" rather than as "the whole task".
   if (budget <= 0) return sliceByColumn(ROW_ELLIPSIS, 0, width, true);
-  return sliceByColumn(firstLine, 0, budget, true) + ROW_ELLIPSIS + RESET;
+  const sliced = sliceByColumn(firstLine, 0, budget, true);
+  return sanitizeRowResets(sliced + ROW_ELLIPSIS) + RESET;
 }
 
 /** Pad a rendered line out to the frame, the way `Text` does. */
@@ -175,7 +198,7 @@ export class RowBlock extends Text {
       const text = segment.text.replace(/\t/g, " ".repeat(TAB_WIDTH));
       if (segment.kind === "block") {
         for (const wrapped of wrapTextWithAnsi(text, width)) {
-          lines.push(padToWidth(wrapped, width));
+          lines.push(padToWidth(sanitizeRowResets(wrapped), width));
         }
       } else {
         lines.push(padToWidth(truncateRow(text, width), width));

package/src/tool-schema.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Issue #114 — the parameter set `subagent` declares is the whole contract, so
+ * every name in it must be a name `execute` actually reads.
+ *
+ * #114 deleted a declared `async` boolean ("Run asynchronously
+ * (fire-and-forget)") that nothing read: a model that passed `async: true` got a
+ * fully synchronous run with no warning. That is a false statement in a
+ * model-facing contract, and worse than a missing feature, because the contract
+ * *is* what the model believes about the tool — it is what gets rendered into
+ * the tool list, what the model plans around, what a wrong answer gets blamed
+ * on. Deleting the claim is the fix; implementing fire-and-forget is out of
+ * scope and blocked on #113 (reaping subagent children across session
+ * replacement).
+ *
+ * The review that followed found a SECOND instance of the same defect class the
+ * issue never named: `count?: number` on the parallel task item, read nowhere.
+ * It differed from `async` in one instructive way: it lived only in the
+ * hand-written `params` type on `execute` in `index.ts`, never in `TaskItem`, so
+ * the JSON Schema the model sees never advertised it and a guard that enumerates
+ * the schema alone could not have caught it. The root cause of both was one
+ * contract stated twice — once for the model, once for TypeScript — with nothing
+ * keeping the two in step. So the fix is structural rather than another
+ * assertion: `SubagentParams` in `tool-schema.ts` is
+ * `Static<typeof SUBAGENT_PARAMS_SCHEMA>` and `execute` takes that, which is the
+ * `ask` / `sudo` precedent. There is no second list left to drift on its own, so
+ * the only low-friction way to introduce a `count` is to say so at one of the
+ * two surfaces a reviewer reads: the schema, or `execute`'s signature.
+ *
+ * What is guarded where, stated honestly:
+ *
+ *   - the schema's declared sets are pinned below, exactly and enumerated from
+ *     the schema object rather than restated;
+ *   - there is no second TS-side list left for a test to police. `tsc` does
+ *     reject a params type that *contradicts* the schema — `model?: number` at
+ *     the params position fails `registerTool`'s `execute` with TS2322 — but
+ *     that check is neither new nor the derivation's doing: `registerTool`
+ *     infers `TParams` from `parameters` and declares `execute`'s `params` as
+ *     `Static<TParams>` (`pi-coding-agent` `dist/core/extensions/types.d.ts:514`),
+ *     so the same TS2322 fires with or without `SubagentParams` (measured against
+ *     the pre-derivation literal, and it failed there too).
+ *   - what `tsc` never caught, and still does not, is the phantom itself. An
+ *     extra *optional* member only widens the params type, and pi declares
+ *     `execute` as a method, so method parameters are bivariant: `count?: number`
+ *     in the old literal, in `TaskItem` inside that literal, and spliced on as
+ *     `params: SubagentParams & { count?: number }` all compile (each measured).
+ *     So the derivation removes the *place* a phantom hid — it does not add a
+ *     compiler check that would catch one. Writing a phantom now takes a
+ *     deliberate `& { … }` at the params position, an edit a reviewer sees, where
+ *     before it was the default way to state the contract.
+ *   - the residual gap, stated against what this branch removed rather than
+ *     against the compiler. The ~370-line source-text scanner deleted in
+ *     `ca1a328` DID catch a declared-and-unread task field: it parsed
+ *     `index.ts` as text, derived the task fields the parallel branch reads
+ *     (`readTaskFields()`) and compared them against
+ *     `declaredTaskItemParams()`, pinning both directions — declared and not
+ *     read, and read and not declared. So type erasure was never what defeated
+ *     that guard: it read the file, and a test over source text does see what
+ *     the body reads. It was deleted for its false-positive cost, not because it
+ *     did not work — it could redden on an unrelated `index.ts` edit (Greptile's
+ *     P2 on PR #143), and that brittleness is why the maintainer took the
+ *     schema-shared-type option instead. Losing it has a real price: on the
+ *     task-item surface a schema field that `execute` declares but ignores is
+ *     once again undetectable here, which is exactly how `async` survived. The
+ *     cheap, non-brittle replacement is a BEHAVIOURAL pin, not a second parser:
+ *     `index.test.ts` ("the object forwarded to the executor") now asserts the
+ *     exact key set handed to `executeParallel` / `executeSubagent`, so dropping
+ *     a forwarded task field — or adding one nobody declared — fails a test. Its
+ *     limit, stated rather than sold: it pins the shape handed over, so a schema
+ *     field that `execute` never forwards at all is invisible to it, and it
+ *     cannot prove the executor reads a key it is handed. That residue is the
+ *     phantom class, and it is genuinely uncovered again. What still covers it is
+ *     the two pins below, a schema small enough to read in one screen — five
+ *     top-level parameters, four task fields — and review.
+ *
+ * If a name reappears here it has to arrive together with the behaviour that
+ * honours it (#113 first, for `async`) and a consumer that reads it; until then
+ * the honest description is the one that does not mention it.
+ */
+
+import { describe, it, expect } from "vitest";
+import { Value } from "typebox/value";
+import { SUBAGENT_PARAMS_SCHEMA } from "./tool-schema.js";
+
+/** Read a schema node's declared property names, failing loudly if it has none. */
+function propertyNames(node: unknown, what: string): string[] {
+  const properties = (node as { properties?: Record<string, unknown> }).properties;
+  if (!properties) throw new Error(`${what} declares no properties`);
+  return Object.keys(properties);
+}
+
+/** The top-level parameters `subagent` declares. Read from the schema, never restated. */
+function declaredParams(): string[] {
+  return propertyNames(SUBAGENT_PARAMS_SCHEMA, "SUBAGENT_PARAMS_SCHEMA");
+}
+
+/**
+ * The properties declared for ONE entry of the `tasks` array — `TaskItem`.
+ * Reached through the schema rather than exported from `tool-schema.ts`, so the
+ * guard depends on the contract the model actually receives and the module
+ * keeps its current public surface (`TaskItem` is deliberately unexported).
+ */
+function declaredTaskItemParams(): string[] {
+  const tasks = (SUBAGENT_PARAMS_SCHEMA as { properties?: Record<string, unknown> }).properties?.tasks;
+  if (!tasks) throw new Error("SUBAGENT_PARAMS_SCHEMA declares no `tasks` property");
+  const items = (tasks as { items?: unknown }).items;
+  if (!items) throw new Error("`tasks` is not an array schema — no item schema to enumerate");
+  return propertyNames(items, "The `tasks` item schema (TaskItem)");
+}
+
+describe("SUBAGENT_PARAMS_SCHEMA — declared parameter set (issue #114)", () => {
+  it("pins the five declared parameters", () => {
+    // Exact and sorted, so it fails in BOTH directions: adding a name the pin
+    // does not know (`async` would) and deleting one of the five. Read from the
+    // schema object, never restated by hand. And because `SubagentParams` is
+    // derived, adding a name here is also adding it to what `execute` is handed,
+    // so this pin is where a new name has to be justified. What it does NOT
+    // check is whether anything reads the name — that cross-surface claim
+    // belonged to the scanner described in the header and no longer exists, so
+    // the name says only what the body proves.
+    expect([...declaredParams()].sort()).toEqual(["agent", "cwd", "model", "task", "tasks"]);
+  });
+});
+
+describe("TaskItem — declared parallel task item (issue #114, second instance: `count`)", () => {
+  it("pins the four declared task-item properties", () => {
+    // `count` was the proof this surface needs its own pin: a phantom can be
+    // added to the task item while the top-level set above stays green. Like the
+    // pin above this one enumerates the SCHEMA only — with the scanner gone
+    // nothing here compares the four against what the parallel branch reads, so
+    // the name claims the enumeration and no more.
+    expect([...declaredTaskItemParams()].sort()).toEqual(["agent", "cwd", "model", "task"]);
+  });
+});
+
+// Legacy-caller compatibility check — a real behavioural guarantee, so it is
+// pinned rather than assumed. TypeBox `Type.Object` does not set
+// `additionalProperties: false`, so deleting `async` — and deleting `count` from
+// the TS type, which the schema never advertised anyway — stops promising the
+// option without turning an existing caller's payload into a validation error: a
+// caller still passing `async: true`, or a `count` on a task, keeps validating, it
+// just no longer gets a promise about it. That is what makes both deletions safe
+// to land in a patch release, and it is the one thing here that fails on its own
+// if anyone ever tightens the schema with `additionalProperties: false`.
+describe("SUBAGENT_PARAMS_SCHEMA — legacy callers passing the deleted fields still validate", () => {
+  it("accepts a payload carrying `async`", () => {
+    expect(Value.Check(SUBAGENT_PARAMS_SCHEMA as never, { task: "x", async: true })).toBe(true);
+  });
+
+  it("accepts a task item carrying `count`", () => {
+    expect(
+      Value.Check(SUBAGENT_PARAMS_SCHEMA as never, { tasks: [{ task: "x", count: 1 }] }),
+    ).toBe(true);
+  });
+});

package/src/tool-schema.ts

@@ -1,4 +1,4 @@
-import { Type } from "typebox";
+import { Type, type Static } from "typebox";
 import type { SubagentResult, SubagentRunReport } from "./types.js";
 
 // ── JSON Schema for tool parameters (TypeBox) ──────────────────────────────
@@ -25,14 +25,31 @@ export const SUBAGENT_PARAMS_SCHEMA = Type.Object({
   model: Type.Optional(Type.String({
     description: "Model override for the subagent",
   })),
-  async: Type.Optional(Type.Boolean({
-    description: "Run asynchronously (fire-and-forget)",
-  })),
   cwd: Type.Optional(Type.String({
     description: "Working directory for the subagent",
   })),
 });
 
+/**
+ * What `execute` is handed, derived from the schema rather than written out —
+ * the `ask` / `sudo` precedent (`AskParams`, `SudoExecInput`).
+ *
+ * #114's two phantoms were only possible because one contract was stated twice,
+ * independently: `async` in this schema, `count?: number` in the hand-written
+ * `params` type in `index.ts`. Nothing kept the two in step, and only one of them
+ * is what the model sees. Stating the contract once removes the second list: the
+ * schema is now the only *default* source of a name in `execute`'s declared
+ * params type — see the caveat below, which is the whole difference between
+ * "only default" and "only".
+ *
+ * That is a structural fix, not a check. It does not stop anyone reading a
+ * declared field, and it does not make a phantom a compile error — `execute` is
+ * declared as a method, so bivariant parameters accept a widening `& { … }` at
+ * the params position. See the header of `tool-schema.test.ts` for what is
+ * enforced where, measured.
+ */
+export type SubagentParams = Static<typeof SUBAGENT_PARAMS_SCHEMA>;
+
 // ── JSON Schema for `structuredContent` ────────────────────────────────
 //
 // One report per run: what ran, how it ended, what it cost, what it answered.