@pi-archimedes/subagent 2.10.4 → 2.11.1

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,
       });
 

package/src/thinking-validation.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest";
+import {
+  THINKING_LEVELS,
+  THINKING_LEVELS_PI_VERSION,
+  isThinkingLevel,
+  resolveThinkingLevel,
+  formatUnknownThinkingWarning,
+} from "./thinking-validation.js";
+
+// pi's CLI keeps its own list of accepted `--thinking` levels and, for anything
+// outside it, warns and drops the flag rather than failing
+// (`pi/dist/cli/args.js`: `VALID_THINKING_LEVELS`). A child configured with a
+// level pi does not take therefore runs at the default while its config claims
+// otherwise, and in `--mode json` the warning lands in stderr — which the stream
+// reader only ever shows for a failed run.
+//
+// This file pins the copy of that list the suite checks against. The host's own
+// validator cannot be consulted: pi's `exports` map publishes only `"."` and
+// `"./rpc-entry"`, so `dist/cli/args.js` is not importable, and the root entry
+// re-exports neither `isValidThinkingLevel` nor `VALID_THINKING_LEVELS` nor the
+// `ThinkingLevel` type that could pin it at compile time. What the test can do is
+// pin the list and the pi version it claims to describe, so drift is a
+// deliberately-edited constant rather than an invisible difference — and the
+// consequence of not editing it stays a warning plus pi's default, never a
+// dispatch refused over a word the host has since learned.
+
+describe("isThinkingLevel", () => {
+  it("accepts exactly pi's seven levels", () => {
+    expect([...THINKING_LEVELS]).toEqual([
+      "off",
+      "minimal",
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+      "max",
+    ]);
+    for (const level of THINKING_LEVELS) expect(isThinkingLevel(level)).toBe(true);
+  });
+
+  it("refines the value it accepts", () => {
+    const value: unknown = "high";
+    if (isThinkingLevel(value)) {
+      const asString: string = value;
+      expect(asString).toBe("high");
+    } else {
+      throw new Error("high should be a thinking level");
+    }
+  });
+
+  it("refuses a level pi warns about and drops", () => {
+    for (const bad of ["ultra", "Medium", "medium ", "highest", "auto", "0"]) {
+      expect(isThinkingLevel(bad), bad).toBe(false);
+    }
+  });
+
+  it("refuses anything that is not a string at all", () => {
+    for (const bad of [undefined, null, 2, true, ["low"]]) {
+      expect(isThinkingLevel(bad)).toBe(false);
+    }
+  });
+});
+
+describe("resolveThinkingLevel", () => {
+  it("passes a valid level through", () => {
+    expect(resolveThinkingLevel("xhigh")).toEqual({ level: "xhigh", warning: undefined });
+  });
+
+  it("says nothing when the config set no level", () => {
+    expect(resolveThinkingLevel(undefined)).toEqual({ level: undefined, warning: undefined });
+    expect(resolveThinkingLevel("")).toEqual({ level: undefined, warning: undefined });
+  });
+
+  it("withholds a level pi would drop, and says so", () => {
+    const resolved = resolveThinkingLevel("ultra");
+    expect(resolved.level).toBeUndefined();
+    expect(resolved.warning).toContain('"ultra"');
+    expect(resolved.warning).toMatch(/default thinking level/i);
+    for (const level of THINKING_LEVELS) {
+      expect(resolved.warning).toContain(level);
+    }
+  });
+});
+
+describe("formatUnknownThinkingWarning", () => {
+  it("names the value rather than describing the problem in the abstract", () => {
+    expect(formatUnknownThinkingWarning("turbo")).toContain("turbo");
+  });
+
+  it("says which pi the level list came from", () => {
+    // The list is a copy of the host's, so the sentence that quotes it has to
+    // say whose list it is — a reader on a newer pi should question it rather
+    // than trust it.
+    expect(formatUnknownThinkingWarning("turbo")).toContain(THINKING_LEVELS_PI_VERSION);
+  });
+});

package/src/thinking-validation.ts

@@ -0,0 +1,78 @@
+// ── The `thinking:` field: what the child will actually accept ─────────────
+//
+// A child is spawned with `--thinking <level>`, and pi's CLI parser keeps its
+// own list (`pi/dist/cli/args.js`: `VALID_THINKING_LEVELS`, `isValidThinkingLevel`).
+// A level outside that list is **not** an error there: the parser pushes a
+// `warning` diagnostic and drops the flag, so the child runs at the default
+// thinking level while the config says something else. In `--mode json` that
+// warning goes to stderr, and `stream.ts` only reads stderr for a *failed* run —
+// so a successful dispatch reported "thinking: medium" having run nothing of the
+// sort. Greptile found it; a live 1.2.0 child confirmed the mechanism.
+//
+// So the suite drops the same value first and says so out loud, at dispatch,
+// where the user is watching. Not a refusal: the run still happens, at exactly
+// the level pi would have used anyway — the difference is that it is now named
+// instead of swallowed. That is also what keeps this safe across a pi upgrade
+// that *adds* a level: the worst case is a warning and the default, never a
+// dispatch refused over a word the host has since learned.
+//
+// The list is duplicated here because there is no other way to read it. pi
+// exports only `"."` and `"./rpc-entry"` (its package `exports` map), so
+// `@earendil-works/pi-coding-agent/dist/cli/args.js` — where `isValidThinkingLevel`
+// and `VALID_THINKING_LEVELS` live — is not importable; the root entry does not
+// re-export either, nor the `ThinkingLevel` type that would pin the set at
+// compile time (that lives in `@earendil-works/pi-agent-core`, which this package
+// cannot resolve). So the copy below is checked by test, not by the host, and the
+// warning names the pi version it was read from — `thinking-validation.test.ts`
+// pins both. `model-validation.ts` (ADR 0008) already keeps a host-owned set the
+// same way for model ids, obtaining those through the `modelRegistry` handle
+// instead, which for levels does not exist.
+
+/** pi's own `VALID_THINKING_LEVELS` were read from, and the version they were
+ * read from. The warning quotes the version so a reader on a newer host knows
+ * which list they are being handed. */
+export const THINKING_LEVELS_PI_VERSION = "1.2.0";
+
+/** pi 1.2.0's `VALID_THINKING_LEVELS`, in pi's order. */
+export const THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const;
+
+/** Whether `level` is a thinking level pi's own `--thinking` accepts. */
+export function isThinkingLevel(level: unknown): level is string {
+  return typeof level === "string" && (THINKING_LEVELS as readonly string[]).includes(level);
+}
+
+/**
+ * The thinking level to put on the child's command line, and what to say about
+ * the one we are not putting there.
+ *
+ * `level` is what to pass (undefined = no `--thinking` flag at all); `warning`
+ * is set when the config asked for something pi would have dropped anyway.
+ */
+export function resolveThinkingLevel(
+  configured: string | undefined,
+): { level: string | undefined; warning: string | undefined } {
+  if (configured === undefined || configured === "") return { level: undefined, warning: undefined };
+  if (isThinkingLevel(configured)) return { level: configured, warning: undefined };
+  return { level: undefined, warning: formatUnknownThinkingWarning(configured) };
+}
+
+/**
+ * The warning for a level pi's `--thinking` does not take.
+ *
+ * It names the value, the accepted set, and what the child is running at
+ * instead — "the flag was dropped" is only useful if you learn the consequence.
+ */
+export function formatUnknownThinkingWarning(configured: string): string {
+  return [
+    `Subagent asked for thinking level "${configured}", which pi's --thinking does not take.`,
+    `The run proceeds at pi's default thinking level. Valid levels (pi ${THINKING_LEVELS_PI_VERSION}): ${THINKING_LEVELS.join(", ")}.`,
+  ].join(" ");
+}

package/src/tool-declarations.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Task 11 item 3 — `subagent` is for the model, not for scripts, and
+ * `list_agents` stays reachable both ways.
+ *
+ * `exposure: "model-only"` is measured, not assumed (see the same file in
+ * `ask` for the method and the pi source references). For `subagent` the cost is
+ * concrete and it was observed before the change: a codemode script called
+ * `tools.subagent({ task: "Reply with exactly the single word: child" })` and
+ * got the whole run back as a structured value —
+ * `{"mode":"single","results":[{... "outcome":"completed","finalOutput":"child" ...}]}`.
+ * After the change that same script line reports
+ * `tools.subagent does not exist` and `subagent` is absent from `ALL_TOOLS`.
+ *
+ * The plan takes the exposure anyway (`docs/roadmap/pi-1-x-alignment.md`,
+ * Task 11 item 3): a subagent dispatch is an orchestration step that pi's own
+ * docs file under "Use it for orchestrating or interactive tools", the model
+ * still drives it, and the nested-call path it does remove is one where the
+ * child's row renders inside a script row the user cannot expand. Say so to the
+ * maintainer rather than discover it later.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { registerSubagent } from "./index.js";
+
+type RegisteredTool = { name: string; exposure?: string; annotations?: Record<string, boolean> };
+
+function register(): Record<string, RegisteredTool> {
+  const tools: RegisteredTool[] = [];
+  registerSubagent({
+    registerTool: (t: unknown) => tools.push(t as RegisteredTool),
+    on: () => {},
+    getAllTools: () => [],
+    events: { emit: () => {}, on: () => () => {} },
+  } as never);
+  return Object.fromEntries(tools.map((t) => [t.name, t]));
+}
+
+describe("subagent exposure", () => {
+  it("subagent is model-only: declared to the model, never callable from a script", () => {
+    expect(register().subagent!.exposure).toBe("model-only");
+  });
+
+  it("list_agents stays direct — a script that dispatches nothing still reads the catalogue", () => {
+    expect(register().list_agents!.exposure ?? "direct").toBe("direct");
+  });
+
+  it("neither tool carries annotations", () => {
+    const tools = register();
+    expect(tools.subagent!.annotations).toBeUndefined();
+    expect(tools.list_agents!.annotations).toBeUndefined();
+  });
+
+  it("nothing in this package is codemode or deferred exposure (ADR 0029)", () => {
+    for (const tool of Object.values(register())) {
+      expect(["codemode", "deferred", "hidden"]).not.toContain(tool.exposure);
+    }
+  });
+});