@ian-pascoe/pi-minimal-subagents 0.12.0 → 0.14.0

package/src/minimal-subagents-status-panel.ts

@@ -1,21 +1,10 @@
 import { stripVTControlCharacters } from "node:util";
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import { contentText } from "@earendil-works/pi-ai";
 import {
-  AssistantMessageComponent,
-  BashExecutionComponent,
-  BranchSummaryMessageComponent,
-  CompactionSummaryMessageComponent,
-  CustomMessageComponent,
-  ToolExecutionComponent,
-  UserMessageComponent,
   type ExtensionContext,
   type KeybindingsManager,
   type Theme,
-  type TruncationResult,
 } from "@earendil-works/pi-coding-agent";
 import {
-  Container,
   Text,
   matchesKey,
   truncateToWidth,
@@ -28,11 +17,14 @@ import type { MinimalSubagentsCoordinator } from "./minimal-subagents-coordinato
 import {
   formatSubagentDuration,
   orderActiveAgentSubtrees,
-  renderMinimalSubagentsMessage,
-  renderMinimalSubagentsResult,
   subagentStatusLadder,
 } from "./minimal-subagents-rendering.js";
 import { COORDINATOR_TOOL_NAMES } from "./minimal-subagents-capabilities.js";
+import {
+  createTranscriptRenderCache,
+  renderTranscriptSnapshot,
+  type TranscriptLayout,
+} from "./minimal-subagents-transcript.js";
 import type { SubagentAccessSnapshot } from "./minimal-subagents-access.js";
 import type {
   AgentSummary,
@@ -66,7 +58,7 @@ function flattenStatusAgents(status: HierarchyStatusResult): FlattenedStatusAgen
   const flattened: FlattenedStatusAgent[] = [];
   const visit = (agent: AgentSummary, depth: number): void => {
     flattened.push({ agent, depth });
-    for (const child of agent.children) visit(child, depth + 1);
+    for (const child of agent.children ?? []) visit(child, depth + 1);
   };
   const roots = "agents" in status ? status.agents : [status.agent];
   for (const agent of orderActiveAgentSubtrees(roots)) visit(agent, 0);
@@ -90,16 +82,20 @@ function statusAccessSourceLabel(source: SubagentAccessSnapshot["source"]): stri
   }
 }
 
-interface CachedTranscriptMessage {
-  container: Container;
-  tools: Map<string, ToolExecutionComponent>;
-  expanded: boolean;
-  streaming: boolean;
-}
-
-interface TranscriptLayout {
-  lines: string[];
-  messageStarts: number[];
+const BACKGROUND_CLEARING_SEQUENCES = ["\u001b[0m", "\u001b[m", "\u001b[49m"] as const;
+
+/**
+ * Re-open the panel background after each sequence that clears it. Truncation ends its cut text
+ * and ellipsis with full resets, and embedded native components may reset or close their own
+ * backgrounds; without this the rest of the row (ellipsis, padding, border) loses the panel fill.
+ */
+function keepBackgroundThroughResets(text: string, backgroundOpen: string): string {
+  if (!backgroundOpen) return text;
+  let result = text;
+  for (const sequence of BACKGROUND_CLEARING_SEQUENCES) {
+    result = result.replaceAll(sequence, `${sequence}${backgroundOpen}`);
+  }
+  return result;
 }
 
 function transcriptText(line: string): string {
@@ -137,180 +133,6 @@ function anchoredTranscriptOffset(
   return nextStart + Math.max(0, newLines.length - 1);
 }
 
-interface TranscriptRenderCache {
-  messages: WeakMap<AgentMessage, CachedTranscriptMessage>;
-  results: WeakMap<ToolExecutionComponent, AgentMessage>;
-}
-
-function renderTranscriptSnapshot(
-  snapshot: ChildAgentTranscriptSnapshot,
-  tui: TUI,
-  cwd: string,
-  expanded: boolean,
-  width: number,
-  cache: TranscriptRenderCache,
-): TranscriptLayout {
-  if (snapshot.messages.length === 0) {
-    return {
-      lines: new Text(snapshot.fallback || "No conversation messages yet.", 3, 0).render(width),
-      messageStarts: [0],
-    };
-  }
-  const blocks: Container[] = [];
-  const tools = new Map(
-    snapshot.toolDefinitions.map((definition) => [definition.name, definition]),
-  );
-  const pendingTools = new Map<string, ToolExecutionComponent>();
-  const currentMessages = new Set(snapshot.messages);
-
-  for (const [messageIndex, message] of snapshot.messages.entries()) {
-    if (message.role === "toolResult") {
-      const paired = pendingTools.get(message.toolCallId);
-      if (paired) {
-        if (cache.results.get(paired) !== message) {
-          paired.updateResult(message);
-          cache.results.set(paired, message);
-        }
-        pendingTools.delete(message.toolCallId);
-        blocks.push(new Container());
-        continue;
-      }
-    }
-    const streaming = messageIndex === snapshot.streamingAssistantIndex;
-    const cached = cache.messages.get(message);
-    const staleResult =
-      cached &&
-      [...cached.tools.values()].some((tool) => {
-        const result = cache.results.get(tool);
-        return result !== undefined && !currentMessages.has(result);
-      });
-    if (cached && !staleResult && cached.expanded === expanded && cached.streaming === streaming) {
-      blocks.push(cached.container);
-      for (const [id, tool] of cached.tools) pendingTools.set(id, tool);
-      continue;
-    }
-    const container = new Container();
-    const messageTools = new Map<string, ToolExecutionComponent>();
-    switch (message.role) {
-      case "user": {
-        const text = contentText(message.content, "\n\n");
-        if (text) container.addChild(new UserMessageComponent(text));
-        break;
-      }
-      case "assistant": {
-        const assistant = new AssistantMessageComponent(message);
-        assistant.updateContent(message, messageIndex === snapshot.streamingAssistantIndex);
-        container.addChild(assistant);
-        for (const content of message.content) {
-          if (content.type !== "toolCall") continue;
-          const tool = new ToolExecutionComponent(
-            content.name,
-            content.id,
-            content.arguments,
-            { showImages: false },
-            tools.get(content.name) ?? {},
-            tui,
-            cwd,
-          );
-          tool.setExpanded(expanded);
-          container.addChild(tool);
-          if (message.stopReason === "aborted" || message.stopReason === "error") {
-            tool.updateResult({
-              content: [
-                {
-                  type: "text",
-                  text:
-                    message.stopReason === "aborted"
-                      ? "Operation aborted"
-                      : (message.errorMessage ?? "Error"),
-                },
-              ],
-              isError: true,
-            });
-          } else {
-            pendingTools.set(content.id, tool);
-            messageTools.set(content.id, tool);
-          }
-        }
-        break;
-      }
-      case "toolResult": {
-        const inherited = new ToolExecutionComponent(
-          message.toolName,
-          message.toolCallId,
-          {},
-          { showImages: false },
-          {},
-          tui,
-          cwd,
-        );
-        inherited.setExpanded(expanded);
-        inherited.updateResult(message);
-        container.addChild(inherited);
-        break;
-      }
-      case "custom": {
-        if (!message.display) break;
-        const renderer =
-          message.customType === "minimal-subagents.message"
-            ? renderMinimalSubagentsMessage
-            : message.customType === "minimal-subagents.result"
-              ? renderMinimalSubagentsResult
-              : undefined;
-        const custom = new CustomMessageComponent(message, renderer);
-        custom.setExpanded(expanded);
-        container.addChild(custom);
-        break;
-      }
-      case "bashExecution": {
-        const bash = new BashExecutionComponent(message.command, tui, message.excludeFromContext);
-        if (message.output) bash.appendOutput(message.output);
-        bash.setComplete(
-          message.exitCode,
-          message.cancelled,
-          // SAFETY: Persisted bash messages retain only the truncation flag; BashExecutionComponent reads that flag here.
-          message.truncated ? ({ truncated: true } as TruncationResult) : undefined,
-          message.fullOutputPath,
-        );
-        bash.setExpanded(expanded);
-        container.addChild(bash);
-        break;
-      }
-      case "branchSummary": {
-        const summary = new BranchSummaryMessageComponent(message);
-        summary.setExpanded(expanded);
-        container.addChild(summary);
-        break;
-      }
-      case "compactionSummary": {
-        const summary = new CompactionSummaryMessageComponent(message);
-        summary.setExpanded(expanded);
-        container.addChild(summary);
-        break;
-      }
-    }
-    cache.messages.set(message, { container, tools: messageTools, expanded, streaming });
-    blocks.push(container);
-  }
-  let length = 0;
-  const messageStarts: number[] = [];
-  const lines = blocks.flatMap((block) => {
-    messageStarts.push(length);
-    // Native user-message prompt zones belong to the main terminal, not an embedded overlay.
-    const rendered = block
-      .render(width)
-      .map((line) =>
-        line
-          .replaceAll("\x1b]133;A\x07", "")
-          .replaceAll("\x1b]133;B\x07", "")
-          .replaceAll("\x1b]133;C\x07", ""),
-      );
-    length += rendered.length;
-    return rendered;
-  });
-  return { lines, messageStarts };
-}
-
 /** Interactive, read-only Child Agent hierarchy and transcript status component. */
 export class MinimalSubagentsStatusPanelComponent implements Component {
   private status!: HierarchyStatusResult;
@@ -324,10 +146,7 @@ export class MinimalSubagentsStatusPanelComponent implements Component {
   private following = true;
   private transcriptLineCount = 0;
   private transcriptLayout?: TranscriptLayout;
-  private readonly transcriptCache: TranscriptRenderCache = {
-    messages: new WeakMap(),
-    results: new WeakMap(),
-  };
+  private readonly transcriptCache = createTranscriptRenderCache();
   private bodyHeight = 1;
   private ensureSelectionVisible = true;
   private toolOutputExpanded = false;
@@ -461,8 +280,12 @@ export class MinimalSubagentsStatusPanelComponent implements Component {
     const visibleBody = body.slice(this.scrollOffset, this.scrollOffset + this.bodyHeight);
     while (visibleBody.length < this.bodyHeight) visibleBody.push("");
     const border = (text: string) => this.theme.fg("border", text);
+    const backgroundOpen = this.theme.getBgAnsi("customMessageBg");
     const rows = [...visibleHeader, ...visibleBody, ...help].map((line) => {
-      const content = truncateToWidth(line, innerWidth, "…");
+      const content = keepBackgroundThroughResets(
+        truncateToWidth(line, innerWidth, "…"),
+        backgroundOpen,
+      );
       return this.theme.bg(
         "customMessageBg",
         `${border("│")} ${content}${" ".repeat(innerWidth - visibleWidth(content))} ${border("│")}`,

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

@@ -2,7 +2,10 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { THINKING_LEVELS } from "./minimal-subagents-capabilities.js";
 
-const SessionContextSchema = StringEnum(["inherit", "compact", "omit"] as const);
+const SessionContextSchema = StringEnum(["inherit", "compact", "omit"] as const, {
+  description:
+    "Default omit: the child starts blank, so write a self-contained task. inherit copies your whole conversation (costly; no prompt-cache reuse); compact summarizes it first (adds a summarization call). Opt in only when the child needs the discussion itself.",
+});
 const ProjectContextSchema = StringEnum(["inherit", "omit"] as const, {
   description:
     "Whether to include project-scoped AGENTS.md instructions and skills. Settings, extensions, providers, and tools remain available.",
@@ -23,6 +26,13 @@ const ToolSelectionSchema = Type.Union(
       'Configurable presets: "read" adds readToolset; "modify" adds readToolset plus modifyToolset. Defaults: read, grep, find, ls; modify additionally grants bash, edit, write. Configured baseToolset applies to all selections, including "none" and exact arrays. Omit to inherit the caller\'s active ordinary tools plus base. All grants stay within the caller\'s capability ceiling; coordinator tools are injected separately.',
   },
 );
+// Deliberately a plain string rather than an enum of the configured roles: settings can change, and
+// the tool definition must stay byte-identical for the session so provider prompt caches survive.
+const ModelRoleSchema = Type.String({
+  minLength: 1,
+  description:
+    "Name of a configured model role (minimalSubagents.modelRoles) listed in the Subagent tool guidelines. Resolves to the role's model and, when the role has one, its thinking level. An explicit model or thinking_level overrides the role's value. An unknown role is rejected with the configured role names.",
+});
 const FRIENDLY_AGENT_ID_PATTERN = "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$";
 const CANONICAL_AGENT_ID_PATTERN =
   "^(?:root\\.)?[A-Za-z0-9][A-Za-z0-9_-]{0,63}(?:\\.[A-Za-z0-9][A-Za-z0-9_-]{0,63})*$";
@@ -38,7 +48,11 @@ export function createCoordinatorToolSchemas(modelIds: readonly string[]) {
     firstModelId === undefined ? Type.Never() : StringEnum([firstModelId, ...remainingModelIds]);
   return {
     subagent: Type.Object({
-      task: Type.String({ minLength: 1, description: "Task for the persistent child agent" }),
+      task: Type.String({
+        minLength: 1,
+        description:
+          "Self-contained brief for the persistent child agent: the goal and relevant background, target files and non-goals, the change or question, and observable acceptance criteria. Reference large inputs by file path instead of pasting them.",
+      }),
       agent_id: Type.Optional(
         Type.String({
           pattern: FRIENDLY_AGENT_ID_PATTERN,
@@ -48,6 +62,7 @@ export function createCoordinatorToolSchemas(modelIds: readonly string[]) {
       ),
       session_context: Type.Optional(SessionContextSchema),
       project_context: Type.Optional(ProjectContextSchema),
+      role: Type.Optional(ModelRoleSchema),
       model: Type.Optional(explicitModelSchema),
       thinking_level: Type.Optional(ThinkingLevelSchema),
       tools: Type.Optional(ToolSelectionSchema),
@@ -69,7 +84,9 @@ export function createCoordinatorToolSchemas(modelIds: readonly string[]) {
       timeout_ms: Type.Optional(Type.Integer({ minimum: 0 })),
     }),
     subagent_status: Type.Object({
-      agent_id: Type.Optional(canonicalAgentIdSchema("Direct child canonical agent ID")),
+      agent_id: Type.Optional(
+        canonicalAgentIdSchema("Direct child canonical agent ID; the root may name any descendant"),
+      ),
     }),
     subagent_cancel: Type.Object({
       agent_id: canonicalAgentIdSchema("Direct child canonical agent ID"),

package/src/minimal-subagents-tools.ts

@@ -9,6 +9,7 @@ import {
   type ToolDefinition,
   type ToolRenderResultOptions,
 } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
 import type { MinimalSubagentsCoordinator } from "./minimal-subagents-coordinator.js";
 import { withTroubleshootingHint } from "./troubleshooting-skill.js";
 import type { MinimalSubagentsModelRole } from "./minimal-subagents-config.js";
@@ -16,13 +17,21 @@ import {
   renderCoordinatorToolCall,
   renderCoordinatorToolResult,
   type CoordinatorToolName,
+  type LiveTurnRenderer,
 } from "./minimal-subagents-rendering.js";
+import {
+  createTranscriptRenderCache,
+  TranscriptRail,
+  type TranscriptRenderCache,
+} from "./minimal-subagents-transcript.js";
 import {
   CoordinatorToolOutputSchemas,
   type CoordinatorToolCallInput,
 } from "./minimal-subagents-render-contract.js";
 import type { createCoordinatorToolSchemas } from "./minimal-subagents-tool-schemas.js";
 import type {
+  ActiveTurnProgress,
+  AgentDetail,
   AgentMessageResult,
   CallerSnapshot,
   CancelResult,
@@ -41,7 +50,15 @@ const ORDINARY_CHILD_COORDINATOR_TOOL_NAMES = new Set([
 /** Coordinator operations consumed by the six public coordinator tool definitions. */
 export type CoordinatorToolOperations = Pick<
   MinimalSubagentsCoordinator,
-  "spawn" | "inspectStatus" | "sendAgentMessage" | "wait" | "status" | "cancel" | "delete"
+  | "spawn"
+  | "inspectStatus"
+  | "previewActiveTurn"
+  | "inspectActiveTurnTranscript"
+  | "sendAgentMessage"
+  | "wait"
+  | "status"
+  | "cancel"
+  | "delete"
 >;
 
 /** Dependencies and caller policy used to create caller-bound coordinator tools. */
@@ -65,8 +82,11 @@ function buildModelRolePromptGuidelines(
     return `  - ${role.name} → model=${role.model}${thinkingGuidance}${role.hint ? ` — ${role.hint}` : ""}`;
   });
   return [
-    ["Configured model roles are guidance, not constraints:", ...roleLines].join("\n"),
-    "Choose a model based on the task. A listed thinking_level is a preference, not a constraint. Callers choose thinking_level independently for roles without one.",
+    [
+      "Configured model roles are guidance, not constraints. Pass role to launch with a role's model and thinking_level; an explicit model or thinking_level overrides the role's value:",
+      ...roleLines,
+    ].join("\n"),
+    "Choose a role or model based on the task. A listed thinking_level is a preference, not a constraint. Callers choose thinking_level independently for roles without one.",
   ];
 }
 
@@ -81,37 +101,84 @@ async function runCoordinatorToolActivity<T>(
   }
 }
 
+/** The compact launch result, plus the full agent detail its transcript renderer displays. */
+type SpawnResultDetails = SpawnResult & { agent?: AgentDetail };
+
 type CoordinatorToolResultDetails =
-  | SpawnResult
+  | SpawnResultDetails
   | AgentMessageResult
   | WaitResult
   | StatusResult
   | CancelResult
   | DeleteResult
-  | { agent_id: string; status: "waiting"; elapsed_ms: number };
+  | WaitProgressDetails;
+
+/** Partial `subagent_wait` details: elapsed wait time plus the child's running-turn progress. */
+type WaitProgressDetails = {
+  agent_id: string;
+  status: "waiting";
+  elapsed_ms: number;
+} & Partial<ActiveTurnProgress>;
 
 type CoordinatorToolDefinition = ToolDefinition & {
   readonly outputSchema: (typeof CoordinatorToolOutputSchemas)[keyof typeof CoordinatorToolOutputSchemas];
 };
 
-function createCoordinatorToolRendering(toolName: CoordinatorToolName) {
+/** Native transcript components are re-rendered on each wait update, so their render requests are not needed. */
+const NON_RENDERING_TUI: Pick<TUI, "requestRender"> = { requestRender: () => undefined };
+
+/** Pi's per-call render context; the installed Pi does not export its named type. */
+type CoordinatorToolRenderContext = Parameters<NonNullable<ToolDefinition["renderResult"]>>[3];
+
+/** Renderer state Pi keeps for one tool row across its partial and final renders. */
+interface CoordinatorToolRowState {
+  liveTurnCache?: TranscriptRenderCache;
+}
+
+function createCoordinatorToolRendering(
+  options: CoordinatorToolDefinitionOptions,
+  toolName: CoordinatorToolName,
+) {
   return {
-    renderCall: (args: CoordinatorToolCallInput, theme: Theme) =>
-      renderCoordinatorToolCall(toolName, args, theme),
+    renderCall: (
+      args: CoordinatorToolCallInput,
+      theme: Theme,
+      context: { expanded: boolean } | undefined,
+    ) => renderCoordinatorToolCall(toolName, args, theme, context?.expanded ?? false),
     renderResult: (
       result: AgentToolResult<CoordinatorToolResultDetails>,
       renderOptions: ToolRenderResultOptions,
       theme: Theme,
-      context: { args: CoordinatorToolCallInput; isError: boolean },
-    ) =>
-      renderCoordinatorToolResult(
+      context: CoordinatorToolRenderContext,
+    ) => {
+      const rowState: CoordinatorToolRowState = context.state;
+      const renderLiveTurn: LiveTurnRenderer = (agentId, turnId, expanded) => {
+        const snapshot = options.coordinator.inspectActiveTurnTranscript(
+          options.callerId,
+          agentId,
+          turnId,
+        );
+        if (!snapshot || snapshot.messages.length === 0) return undefined;
+        return new TranscriptRail(
+          snapshot,
+          // SAFETY: Native transcript components only call requestRender on the TUI they receive.
+          NON_RENDERING_TUI as TUI,
+          context.cwd,
+          expanded,
+          (rowState.liveTurnCache ??= createTranscriptRenderCache()),
+          theme,
+        );
+      };
+      return renderCoordinatorToolResult(
         toolName,
         result,
         renderOptions,
         theme,
         context.args,
         context.isError,
-      ),
+        toolName === "subagent_wait" ? renderLiveTurn : undefined,
+      );
+    },
   };
 }
 
@@ -178,10 +245,12 @@ export function createCoordinatorToolDefinitions(
     name: "subagent",
     label: "Subagent",
     description:
-      "Create a persistent nested agent asynchronously. Returns its canonical agent ID and active turn ID immediately. Root-child IDs omit the root prefix; nested IDs retain the parent path.",
+      "Create a persistent nested agent asynchronously. Returns its canonical agent ID, active turn ID, and resolved model and tools immediately. Root-child IDs omit the root prefix; nested IDs retain the parent path. Children start without your conversation unless session_context opts in, so the task must be self-contained. Its final response is delivered automatically unless you claim it with subagent_wait. To continue an idle child later, send it agent_message; that starts a new turn you can wait on.",
     promptSnippet: "Spawn a persistent child with a prefix-free root-child ID",
     promptGuidelines: modelRolePromptGuidelines,
     parameters: options.schemas.subagent,
+    // A spawn must finish registering before a wait or message in the same batch can target it.
+    executionMode: "sequential",
     annotations: {
       readOnlyHint: false,
       destructiveHint: true,
@@ -195,24 +264,22 @@ export function createCoordinatorToolDefinitions(
           parameters,
           options.captureCaller(context),
         );
+        // The model and codemode receive the compact launch result; the transcript renderer
+        // additionally receives the full detail it displays.
         const status = options.coordinator.inspectStatus(result.agent_id);
-        const details: SpawnResult & {
-          agent?: import("./minimal-subagents-types.js").AgentDetail;
-        } = {
-          ...result,
-        };
-        if (status && "agent" in status) details.agent = status.agent;
-        return structuredToolResult(details);
+        const details: SpawnResultDetails = { ...result };
+        if ("agent" in status) details.agent = status.agent;
+        return { ...structuredToolResult(result), details };
       });
     },
-    ...createCoordinatorToolRendering("subagent"),
+    ...createCoordinatorToolRendering(options, "subagent"),
   });
 
   const messageTool = defineTool({
     name: "agent_message",
     label: "Agent Message",
     description:
-      "Send one mid-turn coordination message to a direct parent, direct sibling, or direct child. The result says whether it was delivered through an active wait, queued for the recipient, or failed.",
+      "Send one coordination message to a direct parent, direct sibling, or direct child. The result says whether it was delivered through an active wait, queued into the recipient's active turn, started a new turn on an idle child (with its turn_id), or failed.",
     promptSnippet: "Coordinate required mid-turn action with one adjacent agent",
     parameters: options.schemas.agent_message,
     annotations: {
@@ -239,14 +306,14 @@ export function createCoordinatorToolDefinitions(
           : structuredToolResult(result);
       });
     },
-    ...createCoordinatorToolRendering("agent_message"),
+    ...createCoordinatorToolRendering(options, "agent_message"),
   });
 
   const waitTool = defineTool({
     name: "subagent_wait",
     label: "Subagent Wait",
     description:
-      "Wait for one direct child's oldest observable turn, or select an exact retained turn_id. An active child may first return event=message; later unconsumed items still fall back automatically. An already settled turn returns event=turn once with queued messages in messages. Timeout returns event=timeout with detailed child status 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 the same result. Timeout returns event=timeout with detailed child status and never cancels the child.",
     promptSnippet: "Wait for one direct child's exact turn",
     parameters: options.schemas.subagent_wait,
     annotations: {
@@ -257,15 +324,22 @@ export function createCoordinatorToolDefinitions(
     },
     async execute(_toolCallId, parameters, signal, onUpdate) {
       const startedAt = Date.now();
-      const updateWaitingResult = () =>
+      const updateWaitingResult = () => {
+        const details: WaitProgressDetails = {
+          agent_id: parameters.agent_id,
+          status: "waiting",
+          elapsed_ms: Date.now() - startedAt,
+          ...options.coordinator.previewActiveTurn(
+            options.callerId,
+            parameters.agent_id,
+            parameters.turn_id,
+          ),
+        };
         onUpdate?.({
           content: [{ type: "text", text: `Waiting for ${parameters.agent_id}` }],
-          details: {
-            agent_id: parameters.agent_id,
-            status: "waiting",
-            elapsed_ms: Date.now() - startedAt,
-          },
+          details,
         });
+      };
       updateWaitingResult();
       const waitingInterval = setInterval(updateWaitingResult, 1_000);
       waitingInterval.unref?.();
@@ -293,14 +367,14 @@ export function createCoordinatorToolDefinitions(
         clearInterval(waitingInterval);
       }
     },
-    ...createCoordinatorToolRendering("subagent_wait"),
+    ...createCoordinatorToolRendering(options, "subagent_wait"),
   });
 
   const statusTool = defineTool({
     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.",
+      "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.",
     promptSnippet: "Inspect direct child state",
     parameters: options.schemas.subagent_status,
     annotations: {
@@ -314,7 +388,7 @@ export function createCoordinatorToolDefinitions(
         structuredToolResult(options.coordinator.status(options.callerId, parameters.agent_id)),
       );
     },
-    ...createCoordinatorToolRendering("subagent_status"),
+    ...createCoordinatorToolRendering(options, "subagent_status"),
   });
 
   const cancelTool = defineTool({
@@ -341,7 +415,7 @@ export function createCoordinatorToolDefinitions(
         ),
       );
     },
-    ...createCoordinatorToolRendering("subagent_cancel"),
+    ...createCoordinatorToolRendering(options, "subagent_cancel"),
   });
 
   const deleteTool = defineTool({
@@ -375,7 +449,7 @@ export function createCoordinatorToolDefinitions(
         return structuredToolResult(result);
       });
     },
-    ...createCoordinatorToolRendering("subagent_delete"),
+    ...createCoordinatorToolRendering(options, "subagent_delete"),
   });
 
   const coordinatorTools: CoordinatorToolDefinition[] = [