@ian-pascoe/pi-minimal-subagents 0.17.0 → 0.18.0

package/README.md

@@ -42,7 +42,9 @@ From this package checkout, load the source directly with
    response arrives automatically as a steer message. Without `turn_id`, a wait
    skips turns whose result you already claimed or received automatically, and
    never repeats an automatically delivered result: it reports
-   `already_delivered: true` instead of the output.
+   `already_delivered: true` instead of the output. If the result is handed to Pi but
+   not yet in your conversation, it also sets `delivery_pending: true` and the
+   result arrives as a separate message; no reread needed.
 3. `agent_message` continues an idle child: the result reports
    `disposition: "started-turn"` with the new `turn_id`. A plain
    `subagent_wait({ agent_id })` targets that new turn, not the first result;
@@ -288,11 +290,22 @@ assistant message but omits image data. Timeout Wait Events carry only a compact
 progress snapshot. Children target only direct children; the Root Agent
 may inspect any descendant. Model-facing status reports a `child_count` but no
 nested `children` summaries. Reported `usage` always includes `cacheWrite1h`
-and `reasoning`, as `0` when the provider reports none. Tool-result text and
-`structuredContent` round every `usage.cost` field to six decimal places of USD;
+and `reasoning`, as `0` when the provider reports none. `structuredContent`
+rounds every `usage.cost` field to six decimal places of USD;
 exact values stay in session data. `subagent_cancel`
 lists in `affected_agent_ids` only agents whose active turns it cancelled.
 
+Coordinator Tools give the model compact text, not JSON: a spawn is one line
+naming the tool preset and count rather than the tool list; a settled wait is
+status, elapsed time, one token and cost total, then the output; cancel and
+delete are one line each, and a cancel that found nothing running says so.
+Targeted `subagent_status` opens with a summary line, lists active tools once,
+describes the Launch Contract grant and capability ceiling relative to them,
+and previews the task, latest output, and last three Recent Activity items;
+`verbose: true` adds the full task, output, ceiling, usage breakdown, recent
+messages, and Recent Activity. Codemode scripts receive the complete record in
+`structuredContent`, and the transcript renderer reads `details`.
+
 `session_context` defaults to `omit`: the child starts with only its system
 prompt and task, so the task should be a self-contained brief covering the goal,
 target files and non-goals, the change or question, and acceptance criteria.
@@ -352,7 +365,9 @@ remaining observable turn, falling back to the active, then latest, turn. When
 that fallback reaches a result already delivered to you automatically, whether
 still queued or settled, the wait returns `event: "turn"` with
 `already_delivered: true`, the turn identity, and status, but no output; it does
-not claim the turn, and `turn_id` rereads the full result. A
+not claim the turn, and `turn_id` rereads the full result. A result handed but
+not yet recorded in your branch also carries `delivery_pending: true`: it will
+arrive as a separate message (redelivered if Pi discards the queued steer), so no reread is needed. A
 caller may have only one outstanding wait for the same source turn; a
 concurrent duplicate is rejected instead of competing for one Wait Event.
 When `timeout_ms` expires, the wait returns an observational `event: "timeout"`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [
@@ -31,7 +31,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@ian-pascoe/pi-utils": "^0.5.0",
+    "@ian-pascoe/pi-utils": "^0.6.0",
     "minimatch": "^10.2.6"
   },
   "peerDependencies": {

package/skills/pi-minimal-subagents/SKILL.md

@@ -9,7 +9,7 @@ disable-model-invocation: true
 
 1. Read the relevant access, spawn, capability, delivery, or recovery section of [`../../README.md`](../../README.md).
 2. For Subagent Access or missing Root Agent Coordinator Tools, run `/subagents status` first and record the effective source plus actual active-tool count.
-3. From the direct parent, use `subagent_status` to capture the Child Agent's Launch Contract, effective tools, Runtime Profile, dependencies, result, and Recent Activity.
+3. From the direct parent, use `subagent_status` with `verbose: true` to capture the Child Agent's Launch Contract, effective tools, Runtime Profile, dependencies, result, and Recent Activity.
 4. Classify the fault as Subagent Access, launch resolution, adjacency, ordinary-tool ceiling, delivery state, or Registry recovery.
 5. For access changes, use the narrowest `/subagents enable|disable|reset` scope. For other configuration, identify the effective layer, make one scoped edit, validate JSON, and reload Pi.
 6. Repeat the same spawn or coordination operation. Finish when it succeeds or one named access, launch, adjacency, capability, delivery, or recovery boundary is evidenced.

package/src/minimal-subagents-coordinator.ts

@@ -70,6 +70,7 @@ import type {
   TurnResult,
   WaitMessageResult,
   WaitTimeoutResult,
+  AutomaticDelivery,
   WaitDeliveredTurnResult,
   WaitResult,
 } from "./minimal-subagents-types.js";
@@ -155,6 +156,7 @@ function terminalWaitResult(result: TurnResult, messages: WaitMessageResult[] =
 function alreadyDeliveredWaitResult(
   result: TurnResult,
   messages: WaitMessageResult[],
+  delivery: AutomaticDelivery,
 ): WaitDeliveredTurnResult {
   const delivered: WaitDeliveredTurnResult = {
     event: "turn",
@@ -163,6 +165,7 @@ function alreadyDeliveredWaitResult(
     status: result.status,
     already_delivered: true,
   };
+  if (delivery === "handed") delivered.delivery_pending = true;
   if (messages.length > 0) delivered.messages = structuredClone(messages);
   return delivered;
 }
@@ -515,8 +518,12 @@ export class MinimalSubagentsCoordinator {
       const messages = this.drainPendingParentMessages(callerId, agentId, turnId);
       // A default wait falls back to the latest turn, whose result may already have been delivered
       // automatically; repeating its output would deliver it twice. An explicit turn_id rereads it.
-      if (requestedTurnId === undefined && this.wasAlreadyDelivered(callerId, retainedResult)) {
-        return Promise.resolve(alreadyDeliveredWaitResult(retainedResult, messages));
+      const delivery =
+        requestedTurnId === undefined
+          ? this.automaticDelivery(callerId, retainedResult)
+          : undefined;
+      if (delivery) {
+        return Promise.resolve(alreadyDeliveredWaitResult(retainedResult, messages, delivery));
       }
       this.claimTerminalDelivery(callerId, retainedResult);
       return Promise.resolve(terminalWaitResult(retainedResult, messages));
@@ -1772,17 +1779,23 @@ export class MinimalSubagentsCoordinator {
   /**
    * Whether this result was already delivered to the caller automatically: it is handed, or the
    * caller's branch holds its automatic result message. A wait's own tool result does not count.
+   * "recorded" means the branch already holds it; "handed" means it is queued to Pi but not yet
+   * recorded, so it still arrives as a separate message (redelivered if Pi discarded the queued steer).
    */
-  private wasAlreadyDelivered(callerId: string, result: TurnResult): boolean {
-    return (
-      this.handedTerminalKeys.has(deliveryTurnKey(result.agent_id, result.turn_id)) ||
+  private automaticDelivery(callerId: string, result: TurnResult): AutomaticDelivery | undefined {
+    if (
       this.hasRecipientDeliveryEvidence(
         callerId,
         result.agent_id,
         result.turn_id,
         automaticResultMessageId(result.agent_id, result.turn_id),
       )
-    );
+    ) {
+      return "recorded";
+    }
+    return this.handedTerminalKeys.has(deliveryTurnKey(result.agent_id, result.turn_id))
+      ? "handed"
+      : undefined;
   }
 
   private hasDeliveryEvidence(delivery: PersistedDelivery): boolean {

package/src/minimal-subagents-render-contract.ts

@@ -147,6 +147,7 @@ const WaitTurnDetailsSchema = Type.Object({
   elapsed_ms: Type.Optional(Type.Number()),
   usage: Type.Optional(RenderUsageSchema),
   already_delivered: Type.Optional(Type.Boolean()),
+  delivery_pending: Type.Optional(Type.Boolean()),
   messages: Type.Optional(Type.Array(WaitMessageDetailsSchema)),
 });
 const WaitTimeoutDetailsSchema = Type.Object({
@@ -314,6 +315,7 @@ export const CoordinatorToolOutputSchemas = {
       ...Type.Pick(CoordinatorTurnOutputSchema, ["agent_id", "turn_id", "status"]).properties,
       event: Type.Literal("turn"),
       already_delivered: Type.Literal(true),
+      delivery_pending: Type.Optional(Type.Literal(true)),
       messages: Type.Optional(Type.Array(CoordinatorWaitMessageOutputSchema)),
       ...CoordinatorWaitSourceOutputSchema,
     }),

package/src/minimal-subagents-rendering.ts

@@ -379,7 +379,7 @@ function latestProgressActivity(activity: readonly RenderRecentActivity[]): Rend
 }
 
 /** Format a turn's cost for summary rows; sub-cent costs keep enough precision to be non-zero. */
-function formatSubagentCost(usage: Usage | undefined): string | undefined {
+export function formatSubagentCost(usage: Usage | undefined): string | undefined {
   const total = usage?.cost.total;
   if (total === undefined || !(total > 0)) return undefined;
   return `$${total.toFixed(total < 0.01 ? 4 : 2)}`;
@@ -591,6 +591,11 @@ function renderWaitProgress(
 
 /** Shown instead of the output of a result already delivered to the parent automatically. */
 const ALREADY_DELIVERED_TEXT = "Already delivered automatically; wait with turn_id to reread it.";
+const DELIVERY_PENDING_TEXT = "Handed to you automatically; it arrives as a separate message.";
+
+function alreadyDeliveredText(details: { delivery_pending?: boolean }): string {
+  return details.delivery_pending ? DELIVERY_PENDING_TEXT : ALREADY_DELIVERED_TEXT;
+}
 
 /** The activity labels of a timeout result, including pre-compact results that carried the full status. */
 function timeoutActivityLabels(
@@ -616,7 +621,7 @@ function collapsedWaitBody(
       : undefined;
   }
   if (details.already_delivered) {
-    return collapsedText(theme, theme.fg("muted", ALREADY_DELIVERED_TEXT));
+    return collapsedText(theme, theme.fg("muted", alreadyDeliveredText(details)));
   }
   const output = details.output ?? "";
   if (status === "completed") {
@@ -691,7 +696,7 @@ function renderWaitResult(
   }
   const output = details.output ?? "";
   if (details.already_delivered) {
-    appendTextSection(container, theme, "Output", ALREADY_DELIVERED_TEXT);
+    appendTextSection(container, theme, "Output", alreadyDeliveredText(details));
   } else if (status === "completed") {
     if (output.length > 0) {
       appendComponentSection(

package/src/minimal-subagents-result-text.ts

@@ -0,0 +1,408 @@
+import type { Usage } from "@earendil-works/pi-ai";
+import {
+  formatSubagentCost,
+  formatSubagentDuration,
+  formatSubagentPreview,
+  formatSubagentTokenCount,
+  formatSubagentUsage,
+} from "./minimal-subagents-rendering.js";
+import type {
+  AgentDetail,
+  AgentMessageResult,
+  AgentSummary,
+  CancelResult,
+  DeleteResult,
+  SpawnResult,
+  StatusResult,
+  ToolSelection,
+  WaitDeliveredTurnResult,
+  WaitMessageResult,
+  WaitResult,
+  WaitTimeoutResult,
+  WaitTurnResult,
+} from "./minimal-subagents-types.js";
+
+/*
+ * Model-facing text for Coordinator Tool results. Each renderer states the facts a model acts on
+ * in a few lines; `details` and `structuredContent` keep the complete record, so nothing dropped
+ * here is lost to codemode scripts or the transcript renderer.
+ */
+
+/** Width of the one-line task preview in summaries. */
+const TASK_PREVIEW_WIDTH = 120;
+/** Width of the one-line latest-result preview in a non-verbose status. */
+const RESULT_PREVIEW_WIDTH = 200;
+/** Width of each one-line Recent Activity preview in a non-verbose status. */
+const ACTIVITY_PREVIEW_WIDTH = 120;
+/** Recent Activity items a non-verbose status previews, newest last. */
+const STATUS_ACTIVITY_PREVIEW_COUNT = 3;
+
+function joinParts(parts: readonly (string | undefined)[]): string {
+  return parts.filter((part): part is string => Boolean(part)).join(" · ");
+}
+
+function profile(model: string, thinkingLevel: string): string {
+  return `${model} (${thinkingLevel})`;
+}
+
+/** One `tokens · cost` total, or undefined when usage is unknown. */
+function usageTotal(usage: Usage | undefined): string | undefined {
+  if (!usage) return undefined;
+  return joinParts([
+    `${formatSubagentTokenCount(usage.totalTokens) ?? "0"} tokens`,
+    formatSubagentCost(usage),
+  ]);
+}
+
+function plural(count: number, singular: string, pluralForm = `${singular}s`): string {
+  return `${count} ${count === 1 ? singular : pluralForm}`;
+}
+
+function listOrNone(values: readonly string[]): string {
+  return values.length === 0 ? "none" : values.join(", ");
+}
+
+function without(values: readonly string[], excluded: readonly string[]): string[] {
+  const excludedSet = new Set(excluded);
+  return values.filter((value) => !excludedSet.has(value));
+}
+
+/** Describe the granted tools relative to the requested selection, without repeating a preset's list. */
+function spawnToolsSummary(
+  granted: readonly string[],
+  requested: ToolSelection | undefined,
+): string {
+  const count = plural(granted.length, "tool");
+  if (requested === undefined) return `tools: inherited, ${count}`;
+  if (!Array.isArray(requested)) return `tools: ${requested} preset, ${count}`;
+  const added = without(granted, requested);
+  const missing = without(requested, granted);
+  const diff = [
+    added.length > 0 ? `+${added.join(", +")}` : undefined,
+    missing.length > 0 ? `-${missing.join(", -")}` : undefined,
+  ].filter(Boolean);
+  return `tools: your list, ${count}${diff.length > 0 ? ` (${diff.join("; ")})` : ""}`;
+}
+
+/** One launch line plus any tool-resolution warnings. */
+export function formatSpawnResultText(
+  result: SpawnResult,
+  requestedTools: ToolSelection | undefined,
+): string {
+  const lines = [
+    joinParts([
+      `Spawned ${result.agent_id} (turn ${result.turn_id}, ${result.status})`,
+      profile(result.model, result.thinking_level),
+      spawnToolsSummary(result.tools, requestedTools),
+      `delegation ${result.delegation}`,
+    ]),
+  ];
+  for (const warning of result.warnings ?? []) lines.push(`warning: ${warning}`);
+  return lines.join("\n");
+}
+
+/** One line naming how the message was delivered, or why it failed. */
+export function formatAgentMessageResultText(result: AgentMessageResult): string {
+  switch (result.disposition) {
+    case "delivered-via-wait":
+      return `Message delivered to ${result.agent_id} through its active wait.`;
+    case "queued":
+      return `Message queued into ${result.agent_id}'s active turn.`;
+    case "started-turn":
+      return `${result.agent_id} was idle; the message started turn ${result.turn_id ?? "(unknown)"}. Wait on it with subagent_wait.`;
+    case "failed":
+      return `Message to ${result.agent_id} failed: ${result.error ?? "unknown error"}`;
+  }
+}
+
+function coordinationMessagesText(
+  agentId: string,
+  messages: readonly WaitMessageResult[] | undefined,
+): string | undefined {
+  if (!messages || messages.length === 0) return undefined;
+  return messages.map((message) => `Message from ${agentId}: ${message.message}`).join("\n");
+}
+
+/**
+ * One line saying an already-delivered result is not repeated and how to reread it, or that a
+ * handed result is still to arrive as a separate message, followed by any Coordination Messages
+ * the wait drained, which the parent has not seen yet.
+ */
+function formatWaitDeliveredText(result: WaitDeliveredTurnResult): string {
+  const subject = `Result of ${result.agent_id} turn ${result.turn_id} (${result.status})`;
+  const notice = result.delivery_pending
+    ? `${subject} was handed to you automatically and arrives as a separate message; no reread is needed.`
+    : `${subject} was already delivered automatically; call subagent_wait with turn_id "${result.turn_id}" to reread it.`;
+  const messages = coordinationMessagesText(result.agent_id, result.messages);
+  return messages ? `${notice}\n${messages}` : notice;
+}
+
+/** A Coordination Message returned before its source turn settled. */
+function formatWaitMessageText(result: WaitMessageResult): string {
+  return `Message from ${result.agent_id} (turn ${result.turn_id} still running):\n${result.message}`;
+}
+
+/** Status and elapsed time, one token/cost total, drained messages, then the turn's output. */
+function formatWaitTurnText(result: WaitTurnResult): string {
+  const header = joinParts([
+    `${result.agent_id} turn ${result.turn_id} ${result.status}`,
+    formatSubagentDuration(result.elapsed_ms),
+  ]);
+  const total = usageTotal(result.usage);
+  const lines = [header];
+  if (total) lines.push(`usage: ${total}`);
+  if (result.error) lines.push(`error: ${result.error}`);
+  const messages = coordinationMessagesText(result.agent_id, result.messages);
+  if (messages) lines.push(messages);
+  return `${lines.join("\n")}\n\n${result.output || "(no output)"}`;
+}
+
+/** The observational timeout snapshot; the wait never cancels the child. */
+function formatWaitTimeoutText(result: WaitTimeoutResult): string {
+  const lines = [
+    `Wait timed out after ${formatSubagentDuration(result.timeout_ms) ?? `${result.timeout_ms}ms`}; ${result.agent_id} is ${result.state} on turn ${result.turn_id} and was not cancelled.`,
+  ];
+  const progress = joinParts([
+    result.elapsed_ms === undefined
+      ? undefined
+      : `elapsed ${formatSubagentDuration(result.elapsed_ms)}`,
+    result.latest_activity_at ? `last activity ${result.latest_activity_at}` : undefined,
+    result.total_tokens === undefined
+      ? undefined
+      : `${formatSubagentTokenCount(result.total_tokens)} tokens`,
+  ]);
+  if (progress) lines.push(progress);
+  if (result.recent_activity_labels.length > 0) {
+    lines.push(`recent activity: ${result.recent_activity_labels.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+/** Any Wait Event: a message, a settled or already-delivered turn, or a timeout. */
+export function formatWaitResultText(result: WaitResult): string {
+  if ("already_delivered" in result) return formatWaitDeliveredText(result);
+  switch (result.event) {
+    case "message":
+      return formatWaitMessageText(result);
+    case "turn":
+      return formatWaitTurnText(result);
+    case "timeout":
+      return formatWaitTimeoutText(result);
+  }
+}
+
+function turnSummary(agent: AgentSummary): string {
+  if (agent.active_turn_id) return `turn ${agent.active_turn_id}`;
+  if (agent.latest_turn)
+    return `latest turn ${agent.latest_turn.turn_id} ${agent.latest_turn.status}`;
+  return "no turns";
+}
+
+function stateSummary(agent: AgentSummary): string {
+  return agent.availability === "unavailable" ? `${agent.state}, unavailable` : agent.state;
+}
+
+/** One line per direct child; nested summaries and tool lists stay in `details`. */
+function formatStatusListText(parentId: string, agents: readonly AgentSummary[]): string {
+  if (agents.length === 0) return `${parentId} has no children.`;
+  const lines = [`${plural(agents.length, "child", "children")} of ${parentId}:`];
+  for (const agent of agents) {
+    lines.push(
+      `- ${joinParts([
+        `${agent.agent_id} ${stateSummary(agent)}`,
+        turnSummary(agent),
+        profile(agent.model, agent.thinking_level),
+        formatSubagentDuration(agent.elapsed_ms),
+        agent.child_count > 0 ? plural(agent.child_count, "child", "children") : undefined,
+        agent.task ? `task: ${formatSubagentPreview(agent.task, TASK_PREVIEW_WIDTH)}` : undefined,
+      ])}`,
+    );
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Active tools, the Launch Contract grant, and the capability ceiling, each listed at most once:
+ * the grant and ceiling are described relative to the list before them.
+ */
+function toolLines(agent: AgentDetail, verbose: boolean): string[] {
+  const active = agent.tools;
+  const granted = agent.launch_contract.ordinary_tools;
+  const ceiling = agent.capability_ceiling;
+  const lines = [`active tools (${active.length}): ${listOrNone(active)}`];
+
+  const inactiveGrants = without(granted, active);
+  const adapterTools = without(active, granted);
+  if (inactiveGrants.length === 0 && adapterTools.length === 0) {
+    lines.push("granted tools: same as active");
+  } else {
+    const differences = [
+      inactiveGrants.length > 0
+        ? `plus ${inactiveGrants.join(", ")} (granted but not active: codemode-only or undeclared)`
+        : undefined,
+      adapterTools.length > 0
+        ? `minus ${adapterTools.join(", ")} (active from a runtime adapter, not granted)`
+        : undefined,
+    ].filter(Boolean);
+    lines.push(`granted tools (${granted.length}): active ${differences.join("; ")}`);
+  }
+
+  const beyondGrant = without(ceiling, granted);
+  if (beyondGrant.length === 0) {
+    lines.push("capability ceiling: same as granted");
+  } else if (verbose) {
+    lines.push(`capability ceiling (${ceiling.length}): granted plus ${beyondGrant.join(", ")}`);
+  } else {
+    lines.push(
+      `capability ceiling: ${ceiling.length} tools, ${beyondGrant.length} beyond the grant`,
+    );
+  }
+  return lines;
+}
+
+function launchLine(agent: AgentDetail): string {
+  const contract = agent.launch_contract;
+  const tools =
+    contract.tools === undefined
+      ? "inherited tools"
+      : Array.isArray(contract.tools)
+        ? "explicit tool list"
+        : `${contract.tools} preset`;
+  const launchedProfile =
+    contract.model !== agent.model || contract.thinking_level !== agent.thinking_level
+      ? `launched as ${profile(contract.model, contract.thinking_level)}`
+      : undefined;
+  return `launch: ${joinParts([
+    contract.role ? `role ${contract.role}` : undefined,
+    launchedProfile,
+    tools,
+    `session context ${contract.session_context}`,
+    `project context ${contract.project_context}`,
+    `delegation ${contract.delegation ?? "none"}`,
+  ])}`;
+}
+
+function indent(text: string): string {
+  return text
+    .split("\n")
+    .map((line) => `  ${line}`)
+    .join("\n");
+}
+
+/**
+ * A summary line, then the Launch Contract, tools, latest result, and Recent Activity. Without
+ * `verbose` the task, result, and activity are one-line previews and the ceiling is a count.
+ */
+function formatStatusDetailText(agent: AgentDetail, verbose: boolean): string {
+  const lines = [
+    joinParts([
+      `${agent.agent_id} ${stateSummary(agent)}`,
+      turnSummary(agent),
+      profile(agent.model, agent.thinking_level),
+      agent.elapsed_ms === undefined
+        ? undefined
+        : `elapsed ${formatSubagentDuration(agent.elapsed_ms)}`,
+      agent.latest_activity_at ? `last activity ${agent.latest_activity_at}` : undefined,
+      usageTotal(agent.usage),
+    ]),
+    joinParts([`parent ${agent.parent_id}`, plural(agent.child_count, "child", "children")]),
+  ];
+  if (agent.unavailable_reason) lines.push(`unavailable: ${agent.unavailable_reason}`);
+  if (agent.missing_dependencies.length > 0) {
+    lines.push(`missing dependencies: ${agent.missing_dependencies.join(", ")}`);
+  }
+  if (agent.task) {
+    lines.push(
+      verbose
+        ? `task:\n${indent(agent.task)}`
+        : `task: ${formatSubagentPreview(agent.task, TASK_PREVIEW_WIDTH)}`,
+    );
+  }
+  lines.push(launchLine(agent), ...toolLines(agent, verbose));
+
+  const latest = agent.latest_result;
+  if (latest) {
+    // The summary line already names an idle child's latest turn.
+    const heading = joinParts([
+      agent.active_turn_id
+        ? `latest result: turn ${latest.turn_id} ${latest.status}`
+        : "latest result",
+      formatSubagentDuration(latest.elapsed_ms),
+    ]);
+    if (latest.error) lines.push(`${heading}\n  error: ${latest.error}`);
+    else lines.push(heading);
+    if (latest.output) {
+      lines.push(
+        verbose
+          ? indent(latest.output)
+          : `  ${formatSubagentPreview(latest.output, RESULT_PREVIEW_WIDTH)}`,
+      );
+    }
+  }
+
+  if (verbose) {
+    const usage = formatSubagentUsage(agent.usage);
+    if (usage) lines.push(`usage: ${usage}`);
+    if (agent.session_file) lines.push(`session file: ${agent.session_file}`);
+    lines.push(`spawn entry: ${agent.spawn_entry_id}`);
+    if (agent.recent_messages.length > 0) {
+      lines.push(`recent messages (${agent.recent_messages.length}):`);
+      for (const message of agent.recent_messages) {
+        lines.push(
+          `- ${message.source_agent_id} (${message.turn_id}):\n${indent(message.content)}`,
+        );
+      }
+    }
+    if (agent.recent_activity.length > 0) {
+      lines.push(`recent activity (${agent.recent_activity.length}):`);
+      for (const activity of agent.recent_activity) {
+        const label = `${activity.label}${activity.truncated ? " (truncated)" : ""}`;
+        lines.push(`- ${label}:\n${indent(activity.content)}`);
+      }
+    }
+    return lines.join("\n");
+  }
+
+  const activity = agent.recent_activity.slice(-STATUS_ACTIVITY_PREVIEW_COUNT);
+  if (activity.length > 0) {
+    lines.push(
+      `recent activity (last ${activity.length} of ${agent.recent_activity.length}):`,
+      ...activity.map(
+        (item) => `- ${item.label}: ${formatSubagentPreview(item.content, ACTIVITY_PREVIEW_WIDTH)}`,
+      ),
+    );
+  }
+  lines.push(
+    "Pass verbose: true for the full task, latest output, capability ceiling, recent messages, and recent activity.",
+  );
+  return lines.join("\n");
+}
+
+/** A direct-children list or one child's detail. */
+export function formatStatusResultText(result: StatusResult, verbose = false): string {
+  return "agent" in result
+    ? formatStatusDetailText(result.agent, verbose)
+    : formatStatusListText(result.parent_id, result.agents);
+}
+
+/** One line naming the cancelled turns, or that no turn was running. */
+export function formatCancelResultText(result: CancelResult): string {
+  if (result.cancelled_turn_ids.length === 0) {
+    return `Nothing cancelled: ${result.agent_id} had no active turn${result.recursive ? ", nor did any descendant" : ""}.`;
+  }
+  return `Cancelled ${plural(result.cancelled_turn_ids.length, "active turn")}: ${result.cancelled_turn_ids.join(", ")}; sessions are kept.`;
+}
+
+/** One line naming the deleted agents, plus one line per failure. */
+export function formatDeleteResultText(result: DeleteResult): string {
+  const lines =
+    result.deleted_agent_ids.length === 0
+      ? [`Deleted no agents under ${result.agent_id}.`]
+      : [
+          `Deleted ${result.deleted_agent_ids.join(", ")}; ${plural(result.trashed_session_files.length, "session file")} moved to trash.`,
+        ];
+  for (const failure of result.failures) {
+    lines.push(`failed: ${failure.agent_id}: ${failure.error}`);
+  }
+  return lines.join("\n");
+}

package/src/minimal-subagents-tool-schemas.ts

@@ -87,6 +87,12 @@ export function createCoordinatorToolSchemas(modelIds: readonly string[]) {
       agent_id: Type.Optional(
         canonicalAgentIdSchema("Direct child canonical agent ID; the root may name any descendant"),
       ),
+      verbose: Type.Optional(
+        Type.Boolean({
+          description:
+            "With agent_id: include the full task, latest output, capability ceiling, usage breakdown, recent messages, and all recent activity",
+        }),
+      ),
     }),
     subagent_cancel: Type.Object({
       agent_id: canonicalAgentIdSchema("Direct child canonical agent ID"),

package/src/minimal-subagents-tools.ts

@@ -10,11 +10,20 @@ import {
   type ToolRenderResultOptions,
 } from "@earendil-works/pi-coding-agent";
 import { Container, type Component, type TUI } from "@earendil-works/pi-tui";
+import { acceptNullForOptionalArguments } from "@ian-pascoe/pi-utils/null-optional-arguments";
 import { appendDurationFooter, callDurationFooter } from "@ian-pascoe/pi-utils/ui";
 import type { MinimalSubagentsCoordinator } from "./minimal-subagents-coordinator.js";
 import { withTroubleshootingHint } from "./troubleshooting-skill.js";
 import type { MinimalSubagentsModelRole } from "./minimal-subagents-config.js";
 import { roundMinimalSubagentsUsageCosts } from "./minimal-subagents-usage.js";
+import {
+  formatAgentMessageResultText,
+  formatCancelResultText,
+  formatDeleteResultText,
+  formatSpawnResultText,
+  formatStatusResultText,
+  formatWaitResultText,
+} from "./minimal-subagents-result-text.js";
 import {
   renderCoordinatorToolCall,
   renderCoordinatorToolResult,
@@ -40,7 +49,6 @@ import type {
   DeleteResult,
   SpawnResult,
   StatusResult,
-  WaitDeliveredTurnResult,
   WaitResult,
 } from "./minimal-subagents-types.js";
 
@@ -202,49 +210,40 @@ function createCoordinatorToolRendering(
  * Serialize a tool result with every nested `usage` cost rounded for presentation. Exact values
  * stay in `details`, the Registry, and session data, which never pass through here.
  */
-function stringifyWithRoundedUsageCosts(
-  result: CoordinatorToolResultDetails,
-  space?: number,
-): string {
+function stringifyWithRoundedUsageCosts(result: CoordinatorToolResultDetails): string {
   // `JSON.stringify` types replacer values as `any`; a usage is recognized by key and `cost` object.
-  return JSON.stringify(
-    result,
-    (key, value) =>
-      key === "usage" && value?.cost ? roundMinimalSubagentsUsageCosts(value) : value,
-    space,
+  return JSON.stringify(result, (key, value) =>
+    key === "usage" && value?.cost ? roundMinimalSubagentsUsageCosts(value) : value,
   );
 }
 
-function structuredToolResult<TDetails extends CoordinatorToolResultDetails>(
-  result: TDetails,
-): AgentToolResult<TDetails> {
-  // Presentation only: `details` keeps the exact values the session persists.
-  const json = stringifyWithRoundedUsageCosts(result, 2);
-  const truncated = truncateHead(json, {
+/** Model-facing text, truncated like Pi's built-in tool output. */
+function textContent(text: string): AgentToolResult<unknown>["content"] {
+  const truncated = truncateHead(text, {
     maxBytes: DEFAULT_MAX_BYTES,
     maxLines: DEFAULT_MAX_LINES,
   });
+  return [{ type: "text" as const, text: truncated.content }];
+}
+
+/**
+ * The model reads compact `text`; codemode scripts and the transcript renderer keep the complete
+ * record in `structuredContent` (costs rounded) and `details` (exact).
+ */
+function structuredToolResult<TDetails extends CoordinatorToolResultDetails>(
+  result: TDetails,
+  text: string,
+): AgentToolResult<TDetails> {
   return {
-    content: [{ type: "text" as const, text: truncated.content }],
+    content: textContent(text),
     details: result,
-    structuredContent: JSON.parse(json),
+    structuredContent: JSON.parse(stringifyWithRoundedUsageCosts(result)),
   };
 }
 
-/**
- * One line saying an already-delivered result is not repeated and how to reread it, followed by
- * any Coordination Messages the wait drained, which the parent has not seen yet.
- */
-function alreadyDeliveredContent(
-  result: WaitDeliveredTurnResult,
-): AgentToolResult<WaitResult>["content"] {
-  const notice = `Result of ${result.agent_id} turn ${result.turn_id} (${result.status}) was already delivered automatically; call subagent_wait with turn_id "${result.turn_id}" to reread it.`;
-  if (!result.messages) return [{ type: "text", text: notice }];
-  const messages = truncateHead(JSON.stringify({ messages: result.messages }, null, 2), {
-    maxBytes: DEFAULT_MAX_BYTES,
-    maxLines: DEFAULT_MAX_LINES,
-  });
-  return [{ type: "text", text: `${notice}\n${messages.content}` }];
+/** One wait result as model-facing text. */
+function waitResultText(result: WaitResult): AgentToolResult<WaitResult>["content"] {
+  return textContent(formatWaitResultText(result));
 }
 
 /**
@@ -254,26 +253,19 @@ function alreadyDeliveredContent(
 function failedStructuredToolResult<TDetails extends CoordinatorToolResultDetails>(
   prefix: string,
   result: TDetails,
+  resultText: string,
   options: { troubleshootingHint: boolean },
 ): AgentToolResult<TDetails> & { isError: true } {
-  const success = structuredToolResult(result);
-  const text = `${prefix}:\n${textOf(success)}`;
+  const text = `${prefix}:\n${resultText}`;
   return {
-    ...success,
-    content: [
-      {
-        type: "text" as const,
-        text: options.troubleshootingHint ? withTroubleshootingHint(text) : text,
-      },
-    ],
+    ...structuredToolResult(
+      result,
+      options.troubleshootingHint ? withTroubleshootingHint(text) : text,
+    ),
     isError: true,
   };
 }
 
-function textOf(result: AgentToolResult<unknown>): string {
-  return result.content.map((part) => (part.type === "text" ? part.text : "")).join("\n");
-}
-
 function callerSourceTurnId(
   coordinator: CoordinatorToolOperations,
   callerId: string,
@@ -319,7 +311,10 @@ export function createCoordinatorToolDefinitions(
         const status = options.coordinator.inspectStatus(result.agent_id);
         const details: SpawnResultDetails = { ...result };
         if ("agent" in status) details.agent = status.agent;
-        return { ...structuredToolResult(result), details };
+        return {
+          ...structuredToolResult(result, formatSpawnResultText(result, parameters.tools)),
+          details,
+        };
       });
     },
     ...createCoordinatorToolRendering(options, "subagent"),
@@ -348,12 +343,13 @@ export function createCoordinatorToolDefinitions(
           },
           callerSourceTurnId(options.coordinator, options.callerId, toolCallId),
         );
+        const text = formatAgentMessageResultText(result);
         return result.disposition === "failed"
-          ? failedStructuredToolResult("Minimal subagents message delivery failed", result, {
+          ? failedStructuredToolResult("Minimal subagents message delivery failed", result, text, {
               // The coordinator already appends the hint to `error`.
               troubleshootingHint: false,
             })
-          : structuredToolResult(result);
+          : structuredToolResult(result, text);
       });
     },
     ...createCoordinatorToolRendering(options, "agent_message"),
@@ -363,7 +359,7 @@ export function createCoordinatorToolDefinitions(
     name: "subagent_wait",
     label: "Subagent Wait",
     description:
-      "Wait for one direct child's oldest observable turn whose result you have neither claimed nor received, or select an exact retained turn_id. An active child may first return event=message; later unconsumed items still fall back automatically. A settled turn returns event=turn, with any queued messages in messages; waiting again returns a result you claimed in full. Without turn_id, a result already delivered to you automatically returns event=turn with already_delivered=true and no output; pass its turn_id to reread it. Timeout returns a compact event=timeout (state, elapsed_ms, latest_activity_at, total_tokens, last few activity labels; use subagent_status for detail) and never cancels the child.",
+      "Wait for one direct child's oldest observable turn whose result you have neither claimed nor received, or select an exact retained turn_id. An active child may first return event=message; later unconsumed items still fall back automatically. A settled turn returns event=turn, with any queued messages in messages; waiting again returns a result you claimed in full. Without turn_id, a result already delivered to you automatically returns event=turn with already_delivered=true and no output; pass its turn_id to reread it. If it was handed to you but is not yet in your conversation, delivery_pending=true and it arrives as a separate message; do not reread. Timeout returns a compact event=timeout (state, elapsed_ms, latest_activity_at, total_tokens, last few activity labels; use subagent_status for detail) and never cancels the child.",
     promptSnippet: "Wait for one direct child's exact turn",
     parameters: options.schemas.subagent_wait,
     annotations: {
@@ -408,10 +404,7 @@ export function createCoordinatorToolDefinitions(
             source_turn_id: result.turn_id,
           };
           return {
-            content:
-              "already_delivered" in result
-                ? alreadyDeliveredContent(result)
-                : structuredToolResult(result).content,
+            content: waitResultText(result),
             details,
             structuredContent: JSON.parse(stringifyWithRoundedUsageCosts(details)),
           };
@@ -427,7 +420,7 @@ export function createCoordinatorToolDefinitions(
     name: "subagent_status",
     label: "Subagent Status",
     description:
-      "List direct children when agent_id is omitted, or inspect one direct child's launch contract, result, usage, dependencies, and bounded recent activity including message text and reasoning. The root may inspect any descendant.",
+      "List direct children when agent_id is omitted, or inspect one direct child's launch contract, result, usage, dependencies, and bounded recent activity including message text and reasoning. Without verbose, the task, latest output, and recent activity are short previews. The root may inspect any descendant.",
     promptSnippet: "Inspect direct child state",
     parameters: options.schemas.subagent_status,
     annotations: {
@@ -437,9 +430,13 @@ export function createCoordinatorToolDefinitions(
       openWorldHint: false,
     },
     async execute(_toolCallId, parameters) {
-      return runCoordinatorToolActivity(options, () =>
-        structuredToolResult(options.coordinator.status(options.callerId, parameters.agent_id)),
-      );
+      return runCoordinatorToolActivity(options, () => {
+        const result = options.coordinator.status(options.callerId, parameters.agent_id);
+        return structuredToolResult(
+          result,
+          formatStatusResultText(result, parameters.verbose ?? false),
+        );
+      });
     },
     ...createCoordinatorToolRendering(options, "subagent_status"),
   });
@@ -458,15 +455,14 @@ export function createCoordinatorToolDefinitions(
       openWorldHint: false,
     },
     async execute(_toolCallId, parameters) {
-      return runCoordinatorToolActivity(options, async () =>
-        structuredToolResult(
-          await options.coordinator.cancel(
-            options.callerId,
-            parameters.agent_id,
-            parameters.recursive ?? true,
-          ),
-        ),
-      );
+      return runCoordinatorToolActivity(options, async () => {
+        const result = await options.coordinator.cancel(
+          options.callerId,
+          parameters.agent_id,
+          parameters.recursive ?? true,
+        );
+        return structuredToolResult(result, formatCancelResultText(result));
+      });
     },
     ...createCoordinatorToolRendering(options, "subagent_cancel"),
   });
@@ -491,13 +487,17 @@ export function createCoordinatorToolDefinitions(
           parameters.agent_id,
           parameters.recursive ?? true,
         );
+        const text = formatDeleteResultText(result);
         if (result.failures.length > 0) {
           options.onAttention?.(`Deletion partially failed for ${parameters.agent_id}`);
-          return failedStructuredToolResult("Minimal subagents deletion partially failed", result, {
-            troubleshootingHint: true,
-          });
+          return failedStructuredToolResult(
+            "Minimal subagents deletion partially failed",
+            result,
+            text,
+            { troubleshootingHint: true },
+          );
         }
-        return structuredToolResult(result);
+        return structuredToolResult(result, text);
       });
     },
     ...createCoordinatorToolRendering(options, "subagent_delete"),
@@ -512,7 +512,9 @@ export function createCoordinatorToolDefinitions(
     Object.assign(deleteTool, { outputSchema: CoordinatorToolOutputSchemas.subagent_delete }),
   ];
   const allowFanoutTools = options.allowFanoutTools ?? options.callerId === "root";
-  return allowFanoutTools
-    ? coordinatorTools
-    : coordinatorTools.filter((tool) => NON_SPAWNING_CHILD_COORDINATOR_TOOL_NAMES.has(tool.name));
+  return (
+    allowFanoutTools
+      ? coordinatorTools
+      : coordinatorTools.filter((tool) => NON_SPAWNING_CHILD_COORDINATOR_TOOL_NAMES.has(tool.name))
+  ).map((tool) => acceptNullForOptionalArguments(tool));
 }

package/src/minimal-subagents-types.ts

@@ -98,6 +98,9 @@ export interface WaitTurnResult extends TurnResult {
   messages?: WaitMessageResult[];
 }
 
+/** How a result reached the caller automatically: handed to Pi but not yet in its branch, or recorded there. */
+export type AutomaticDelivery = "handed" | "recorded";
+
 /**
  * Reports that a default wait selected a terminal turn whose result was already delivered
  * automatically, handed or settled, so the output is not repeated; an explicit `turn_id` rereads it.
@@ -108,6 +111,11 @@ export interface WaitDeliveredTurnResult extends Pick<
 > {
   event: "turn";
   already_delivered: true;
+  /**
+   * Set when the result is handed to Pi but not yet recorded in the caller's branch, so it will
+   * arrive as a separate message and needs no reread.
+   */
+  delivery_pending?: true;
   messages?: WaitMessageResult[];
 }