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

package/README.md

@@ -31,6 +31,20 @@ filter in `~/.pi/agent/settings.json` using the repository-relative path:
 From this package checkout, load the source directly with
 `pi -e ./src/index.ts`. Requires Node `>=22.19.0` and Pi `>=0.99.0`.
 
+## Typical workflow
+
+1. `subagent` launches a Child Agent from a self-contained task: by default the
+   child starts without the parent's conversation. It returns at once with its `agent_id`,
+   `turn_id`, and resolved model, thinking level, tools, delegation, and any
+   tool-resolution `warnings`. Spawns run sequentially, so a `subagent_wait` or
+   `agent_message` in the same tool batch can target the new child.
+2. `subagent_wait` claims the turn's result, or leave it unclaimed and the final
+   response arrives automatically as a steer message.
+3. `agent_message` continues an idle child: the result reports
+   `disposition: "started-turn"` with the new `turn_id` to wait on.
+4. `subagent_status` inspects children; `subagent_cancel` stops work but keeps
+   the session; `subagent_delete` removes it. Deleted IDs cannot be reused.
+
 ## Configuration
 
 Configure the extension in Pi's standard settings files:
@@ -240,7 +254,32 @@ and `subagent_status`.
 Targeted `subagent_status` includes `recent_activity`, a bounded tail of message
 text, reasoning, tool calls, and tool results. It includes the current streaming
 assistant message but omits image data. Timeout Wait Events include the same
-detailed status snapshot.
+detailed status 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. `subagent_cancel`
+lists in `affected_agent_ids` only agents whose active turns it cancelled.
+
+`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.
+Opt in to `inherit` to copy the parent's conversation, or `compact` to summarize
+it first, only when the child needs that discussion. Inheriting is costly: the
+child's system prompt differs from its parent's, so the copied conversation
+cannot reuse the parent's prompt cache, and `compact` adds a summarization call.
+With either opt-in, the parent's conversation is quoted rather than replayed as
+the child's own turns: each parent message becomes one
+`minimal-subagents.parent-context` custom message, sent to the model as
+user-role text wrapped in `<parent_message from="…" role="…">`. Tool calls and
+results become text, a custom message's label names its `customType`, and an
+errored, aborted, or length-limited parent turn is marked as incomplete. Images
+are kept; parent reasoning and the parent's system prompt and tool declarations
+are omitted, since the child declares its own. Each quoted message stays a
+separate session entry, so `compact` can still summarize older entries. The task
+is then framed as a handoff: the quoted conversation is background, its requests
+belonged to the parent, and the child's own assignment follows. Quoting keeps
+the parent's turns distinct from the child's own; it does not guarantee that a
+child, particularly a small model, ignores the quoted requests. Existing Child Agents keep the mode recorded in their Launch Contracts.
 
 The `subagent` `tools` argument distinguishes configurable Tool Presets from
 exact lists; every selection also receives the permitted Base Toolset described
@@ -260,15 +299,18 @@ tools while the Launch Contract continues to record the originally granted
 capability names.
 
 `agent_message` reports whether a message was delivered through an active
-parent wait, queued for the recipient, or failed. A failed delivery and a
+parent wait (`delivered-via-wait`), queued into the recipient's active turn
+(`queued`), started a new turn on an idle child (`started-turn`, with its
+`turn_id`), or failed. A failed delivery and a
 partially failed `subagent_delete` return an error result (`isError: true`) that
 still carries the declared structured output, so the model sees an error while
 codemode scripts receive the `failures` or `error` data instead of a data-less
 rejection. `subagent_wait` can return an
 intermediate Wait Event containing a Coordination Message before the child turn
 settles. That event claims only its message, so later unconsumed messages and the
-terminal result retain automatic fallback. If the turn has already settled, one
-wait returns its terminal result with queued messages in `messages`. Pass
+terminal result retain automatic fallback. If the turn has already settled, a
+wait returns its terminal result with queued messages in `messages`; waiting
+again for the same settled turn returns the same result. Pass
 optional `turn_id` to address an older retained turn exactly. Without it, waits
 select the oldest observable claimed or pending turn before the active/latest
 turn. A caller may have only one outstanding wait for the same source turn; a
@@ -333,6 +375,18 @@ The coordinator tools declare MCP-style `annotations`, which Pi reports through
 
 ## Status and TUI
 
+Coordinator tool calls and results stay readable without expanding. A
+`subagent` call shows the launch settings the caller chose and its task; an
+`agent_message` call shows its message. While `subagent_wait` blocks, it shows
+the child's tool-call count and, on a tree rail, the latest work of the turn
+being waited on, rendered with Pi's own message and tool components as in the
+`/subagents` viewer and refreshed each second; collapsed, the rail keeps the
+newest items within 20 lines. A settled wait shows the child's output as
+Markdown, or its error, with duration, tokens, and cost. Long text previews its
+first 10 lines, like Pi's `read`. Every collapsed result ends its first line
+with Pi's tool-expansion hint (normally Ctrl+O), which reveals the rest and the
+full detail. Automatic agent results and messages preview the same way.
+
 In TUI mode, `/subagents` or `/subagents status` opens a large, centered,
 framed overlay. Up/Down selects a Child Agent; Enter opens its Child Session
 Transcript. Escape returns to the tree, then Escape closes the overlay. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [

package/src/minimal-subagents-capabilities.ts

@@ -75,7 +75,9 @@ export function resolveOrdinaryToolSelection(
   const ceiling = new Set(context.capabilityCeiling);
   const exceeded = uniqueRequested.filter((name) => !ceiling.has(name));
   if (exceeded.length > 0) {
-    throw new Error(`Minimal subagents capability ceiling exceeded: ${exceeded.join(", ")}`);
+    throw new Error(
+      `Minimal subagents tool selection: ${exceeded.join(", ")} ${exceeded.length === 1 ? "is" : "are"} unknown or outside the caller's capability ceiling. ${describePermittedTools(excludeCoordinatorTools(context.capabilityCeiling))}`,
+    );
   }
 
   const toolsets = context.toolsets ?? DEFAULT_TOOLSETS;
@@ -103,6 +105,15 @@ export function resolveOrdinaryToolSelection(
   };
 }
 
+const PERMITTED_TOOL_LISTING_LIMIT = 40;
+
+function describePermittedTools(permitted: readonly string[]): string {
+  if (permitted.length === 0) return "No ordinary tools are permitted.";
+  const listed = permitted.slice(0, PERMITTED_TOOL_LISTING_LIMIT).join(", ");
+  const remaining = permitted.length - PERMITTED_TOOL_LISTING_LIMIT;
+  return `Permitted ordinary tools: ${listed}${remaining > 0 ? `, and ${remaining} more` : ""}.`;
+}
+
 /** Return an agent's hierarchy depth where the interactive root is depth zero. */
 export function getSubagentDepth(agentId: string): number {
   if (agentId === "root") return 0;

package/src/minimal-subagents-context.ts

@@ -1,7 +1,13 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import { contentText, type ImageContent, type TextContent } from "@earendil-works/pi-ai";
+import {
+  contentText,
+  type AssistantMessage,
+  type ImageContent,
+  type TextContent,
+} from "@earendil-works/pi-ai";
 import { truncateTail } from "@earendil-works/pi-coding-agent";
 import type {
+  ActiveTurnProgress,
   ChildAgentTranscriptSnapshot,
   RecentAgentActivity,
   SessionContextMode,
@@ -141,19 +147,189 @@ export function buildRecentAgentActivity(messages: readonly AgentMessage[]): Rec
   return activity.slice(-RECENT_AGENT_ACTIVITY_LIMIT);
 }
 
+/** A message the child produced during the turn, as opposed to the turn's prompt or coordination input. */
+function isTurnWork(message: AgentMessage, turnStartedAtMs: number): boolean {
+  return (
+    message.timestamp >= turnStartedAtMs &&
+    (message.role === "assistant" || message.role === "toolResult")
+  );
+}
+
+/** Count the tool calls a running turn has made so far. */
+export function buildActiveTurnProgress(
+  messages: readonly AgentMessage[],
+  turnStartedAtMs: number,
+): Omit<ActiveTurnProgress, "turn_id"> {
+  let toolCalls = 0;
+  for (const message of messages) {
+    if (message.role !== "assistant" || !isTurnWork(message, turnStartedAtMs)) continue;
+    toolCalls += message.content.filter((content) => content.type === "toolCall").length;
+  }
+  return { tool_calls: toolCalls };
+}
+
+/**
+ * Keep the running turn's last `assistantMessageCount` assistant messages and the tool results after
+ * them, so a live view renders recent work without the turn's earlier history.
+ */
+export function selectActiveTurnTranscript(
+  snapshot: ChildAgentTranscriptSnapshot,
+  turnStartedAtMs: number,
+  assistantMessageCount: number,
+): ChildAgentTranscriptSnapshot {
+  const work = snapshot.messages.flatMap((message, index) =>
+    isTurnWork(message, turnStartedAtMs) ? [{ message, index }] : [],
+  );
+  const assistantPositions = work.flatMap((entry, position) =>
+    entry.message.role === "assistant" ? [position] : [],
+  );
+  const tail = work.slice(assistantPositions.at(-assistantMessageCount) ?? 0);
+  const streamingPosition = tail.findIndex(
+    (entry) => entry.index === snapshot.streamingAssistantIndex,
+  );
+  return {
+    messages: tail.map((entry) => entry.message),
+    streamingAssistantIndex: streamingPosition >= 0 ? streamingPosition : undefined,
+    toolDefinitions: snapshot.toolDefinitions,
+  };
+}
+
 /** Carries the selected caller messages and whether child preparation should compact them. */
 export interface ImportedSubagentContext {
   messages: AgentMessage[];
   compact: boolean;
 }
 
-/** Select the imported message snapshot and defer expensive compact preparation to the child turn. */
+/** Custom message type carrying one quoted message from a parent's conversation. */
+export const PARENT_CONTEXT_MESSAGE_TYPE = "minimal-subagents.parent-context";
+
+type QuotedContent = TextContent | ImageContent;
+
+function quotedParts(content: string | QuotedContent[]): QuotedContent[] {
+  if (Array.isArray(content)) return content.map((part) => structuredClone(part));
+  return content ? [{ type: "text", text: content }] : [];
+}
+
+function parentMessageBody(
+  message: AgentMessage,
+): { label: string; parts: QuotedContent[] } | undefined {
+  switch (message.role) {
+    case "user":
+      return { label: "user", parts: quotedParts(message.content) };
+    case "assistant": {
+      // Reasoning is omitted: it is model-private and often signature-bound to the parent's model.
+      const parts = message.content.flatMap((content): QuotedContent[] => {
+        if (content.type === "text")
+          return content.text ? [{ type: "text", text: content.text }] : [];
+        if (content.type === "toolCall") {
+          return [
+            {
+              type: "text",
+              text: `[tool call ${content.name}] ${JSON.stringify(content.arguments)}`,
+            },
+          ];
+        }
+        return [];
+      });
+      const stopNote = incompleteAssistantNote(message.stopReason, message.errorMessage);
+      if (stopNote) parts.push({ type: "text", text: stopNote });
+      return { label: "assistant", parts };
+    }
+    case "toolResult":
+      return {
+        label: `tool result ${message.toolName}${message.isError ? " (error)" : ""}`,
+        parts: quotedParts(message.content),
+      };
+    case "custom":
+      return {
+        label: `context message: ${message.customType}`,
+        parts: quotedParts(message.content),
+      };
+    case "bashExecution":
+      if (message.excludeFromContext) return undefined;
+      return {
+        label: "shell command",
+        parts: [{ type: "text", text: `$ ${message.command}\n${message.output || "(no output)"}` }],
+      };
+    case "branchSummary":
+    case "compactionSummary":
+      return {
+        label: message.role === "branchSummary" ? "branch summary" : "compaction summary",
+        parts: quotedParts(message.summary),
+      };
+    case "system":
+      // The parent's prompt sections and tool declarations describe the parent, not the child,
+      // which declares its own prompt and tools on its first request.
+      return undefined;
+    default: {
+      // Fails typecheck when Pi adds a message role, so new roles are quoted deliberately.
+      const unhandled: never = message;
+      return unhandled;
+    }
+  }
+}
+
+/** Mark a parent turn that ended early, so quoted partial output does not read as complete. */
+function incompleteAssistantNote(
+  stopReason: AssistantMessage["stopReason"],
+  errorMessage: string | undefined,
+): string | undefined {
+  if (stopReason === "error") return `[turn failed: ${errorMessage ?? "unknown error"}]`;
+  if (stopReason === "aborted") return "[turn aborted before completion]";
+  if (stopReason === "length") return "[turn stopped at the output length limit]";
+  return undefined;
+}
+
+/**
+ * Quote one parent message as a user-visible custom message. Replaying the parent's assistant
+ * turns as the child's own lets the child continue as its parent; quoting keeps the roles apart
+ * while each message stays a separate entry that child compaction can cut between.
+ */
+function quoteParentMessage(message: AgentMessage, parentId: string): AgentMessage | undefined {
+  const body = parentMessageBody(message);
+  if (!body || body.parts.length === 0) return undefined;
+  return {
+    role: "custom",
+    customType: PARENT_CONTEXT_MESSAGE_TYPE,
+    content: [
+      { type: "text", text: `<parent_message from="${parentId}" role="${body.label}">` },
+      ...body.parts,
+      { type: "text", text: "</parent_message>" },
+    ],
+    display: true,
+    timestamp: message.timestamp,
+  };
+}
+
+/** Select and quote the imported parent conversation; compaction is deferred to the child turn. */
 export function assembleImportedContext(
   mode: SessionContextMode,
-  committedMessages: AgentMessage[],
+  committedMessages: readonly AgentMessage[],
+  parentId: string,
 ): ImportedSubagentContext {
   if (mode === "omit") return { messages: [], compact: false };
-  return { messages: committedMessages, compact: mode === "compact" };
+  return {
+    messages: committedMessages.flatMap((message) => quoteParentMessage(message, parentId) ?? []),
+    compact: mode === "compact",
+  };
+}
+
+/**
+ * Frame a child's task after inherited parent conversation so the child does not adopt the
+ * parent's earlier requests as its own assignment.
+ */
+export function buildInheritedContextTaskPrompt(
+  task: string,
+  agentId: string,
+  parentId: string,
+): string {
+  return [
+    `The parent_message entries above, and any summary of earlier ones, come from the conversation of your parent \`${parentId}\`. They are background context only.`,
+    `Requests and tool calls in them belong to your parent, not to you: do not continue or repeat your parent's work.`,
+    `You are \`${agentId}\`. Your assigned task is:`,
+    "",
+    task,
+  ].join("\n");
 }
 
 /** Detect image content so incompatible child models fail before agent creation. */

package/src/minimal-subagents-coordinator.ts

@@ -2,10 +2,14 @@ import { randomUUID } from "node:crypto";
 import {
   assembleImportedContext,
   boundRecentAgentText,
+  buildActiveTurnProgress,
+  buildInheritedContextTaskPrompt,
   buildRecentAgentActivity,
   contextContainsImages,
+  selectActiveTurnTranscript,
   selectChildAgentTranscript,
 } from "./minimal-subagents-context.js";
+
 import {
   canAgentContractSpawn,
   DEFAULT_MAX_SUBAGENT_DEPTH,
@@ -39,6 +43,7 @@ import { addCoordinatorMessageEnvelope } from "./minimal-subagents-message-envel
 import { unavailableAgent } from "./minimal-subagents-sessions.js";
 import { createRegistryEvent } from "./minimal-subagents-registry.js";
 import type {
+  ActiveTurnProgress,
   AgentDetail,
   AgentMessageDisposition,
   AgentMessageResult,
@@ -70,6 +75,16 @@ const RESERVED_AGENT_IDS = new Set(["root", "parent"]);
 const RECENT_MESSAGE_LIMIT = 20;
 const DEFAULT_AUTOMATIC_DELIVERY_GRACE_MS = 1_000;
 
+/** Assistant messages a waiting parent's live view renders from the child's running turn. */
+const ACTIVE_TURN_TRANSCRIPT_ASSISTANT_MESSAGES = 3;
+
+/** A direct child's running turn as its waiting parent may observe it. */
+interface ObservedActiveTurn {
+  turnId: string;
+  startedAtMs: number;
+  runtime: ChildAgentRuntime;
+}
+
 interface MessageParameters {
   agent_id?: string;
   message: string;
@@ -197,13 +212,15 @@ export class MinimalSubagentsCoordinator {
     this.validateFriendlyId(friendlyId);
     const agentId = this.buildChildAgentId(callerId, friendlyId);
     if (this.tombstones.has(agentId)) {
-      throw new Error(`Minimal subagents agent ID is tombstoned: ${agentId}`);
+      throw new Error(
+        `Minimal subagents agent ID ${agentId} belonged to a deleted agent and cannot be reused; choose a different agent_id`,
+      );
     }
     if (this.agents.has(agentId) || this.pendingAgentIds.has(agentId)) {
       throw new Error(`Minimal subagents duplicate agent ID: ${agentId}`);
     }
 
-    const sessionContext = parameters.session_context ?? "inherit";
+    const sessionContext = parameters.session_context ?? "omit";
     const projectContext = parameters.project_context ?? "inherit";
     const model = parameters.model ?? caller.model;
     const requestedThinking = parameters.thinking_level ?? caller.thinkingLevel;
@@ -218,7 +235,7 @@ export class MinimalSubagentsCoordinator {
       toolsets: this.dependencies.toolsets,
     });
     const committedMessages = structuredClone(caller.messages);
-    const imported = assembleImportedContext(sessionContext, committedMessages);
+    const imported = assembleImportedContext(sessionContext, committedMessages, callerId);
     if (
       contextContainsImages(imported.messages) &&
       !this.dependencies.sessions.modelSupportsImages(model)
@@ -296,11 +313,12 @@ export class MinimalSubagentsCoordinator {
       createRegistryEvent(this.dependencies.registry.rootSessionId, "agent-created", { agent }),
     );
     const turnId = this.beginTurn(agent);
-    if (toolWarnings.length > 0) {
+    const warnings = [...new Set(toolWarnings)];
+    if (warnings.length > 0) {
       this.dependencies.notify?.({
         type: "tool-warning",
         agentId,
-        message: `Minimal subagents tool warnings for ${agentId}:\n- ${[...new Set(toolWarnings)].join("\n- ")}`,
+        message: `Minimal subagents tool warnings for ${agentId}:\n- ${warnings.join("\n- ")}`,
       });
     }
     this.dependencies.notify?.({
@@ -313,13 +331,25 @@ export class MinimalSubagentsCoordinator {
       this.initializeAndRunPrompt(
         agentId,
         turnId,
-        parameters.task,
+        imported.messages.length > 0
+          ? buildInheritedContextTaskPrompt(parameters.task, agentId, callerId)
+          : parameters.task,
         imported.compact,
         caller.model,
         caller.thinkingLevel,
       ),
     );
-    return { agent_id: agentId, turn_id: turnId, status: "running" };
+    const result: SpawnResult = {
+      agent_id: agentId,
+      turn_id: turnId,
+      status: "running",
+      model: agent.launch_contract.model,
+      thinking_level: agent.launch_contract.thinking_level,
+      tools: [...agent.launch_contract.ordinary_tools],
+      delegation: agent.launch_contract.delegation ?? "none",
+    };
+    if (warnings.length > 0) result.warnings = warnings;
+    return result;
   }
 
   /** Capture immutable launch defaults for a nested caller from its active child runtime. */
@@ -365,10 +395,12 @@ export class MinimalSubagentsCoordinator {
         this.queuePendingParentMessage(targetId, message, delivery);
         return { agent_id: targetId, message_id: messageId, disposition: "queued" };
       }
-      const disposition = await this.enqueueRecipientDelivery(targetId, async () =>
+      const { disposition, turnId } = await this.enqueueRecipientDelivery(targetId, async () =>
         this.deliverExplicitMessage(message, targetId, delivery),
       );
-      return { agent_id: targetId, message_id: messageId, disposition };
+      const result: AgentMessageResult = { agent_id: targetId, message_id: messageId, disposition };
+      if (turnId) result.turn_id = turnId;
+      return result;
     } catch (error) {
       const deliveryError = error instanceof Error ? error.message : String(error);
       if (this.isCoordinationDeliveryCurrent(delivery)) {
@@ -423,7 +455,9 @@ export class MinimalSubagentsCoordinator {
     if (pendingMessage) return Promise.resolve(pendingMessage);
     if (agent.active_turn_id !== turnId) {
       return Promise.reject(
-        new Error(`Minimal subagents wait: turn ${turnId} is no longer retained for ${agentId}`),
+        new Error(
+          `Minimal subagents wait: turn ${turnId} is unknown or no longer retained for ${agentId}; omit turn_id to wait for its oldest observable turn`,
+        ),
       );
     }
 
@@ -460,11 +494,11 @@ export class MinimalSubagentsCoordinator {
     });
   }
 
-  /** Return direct-child status authorized for one root or child caller. */
+  /** Return direct-child status for a child caller; the root may inspect any descendant. */
   status(callerId: string, agentId?: string): StatusResult {
     this.assertCallerExists(callerId);
     if (agentId !== undefined) {
-      this.assertCallerTargetsDirectChild(callerId, agentId, "status");
+      if (callerId !== "root") this.assertCallerTargetsDirectChild(callerId, agentId, "status");
       return { agent: this.buildAgentDetail(this.requireAgent(agentId), false) };
     }
     return {
@@ -482,6 +516,56 @@ export class MinimalSubagentsCoordinator {
     };
   }
 
+  /**
+   * Find a direct child's running turn for its parent's live wait view. Only the direct parent
+   * observes it, and a requested `turnId` must be the active turn.
+   */
+  private observeActiveTurn(
+    callerId: string,
+    agentId: string,
+    turnId: string | undefined,
+  ): ObservedActiveTurn | undefined {
+    const agent = this.agents.get(agentId);
+    if (!agent || agent.parent_id !== callerId) return undefined;
+    const activeTurnId = agent.active_turn_id;
+    const startedAt = agent.active_turn_started_at;
+    if (!activeTurnId || !startedAt || (turnId !== undefined && turnId !== activeTurnId)) {
+      return undefined;
+    }
+    const runtime = this.runtimes.get(agentId);
+    if (!runtime) return undefined;
+    return { turnId: activeTurnId, startedAtMs: Date.parse(startedAt), runtime };
+  }
+
+  /** Count a direct child's running-turn tool calls for its waiting parent. */
+  previewActiveTurn(
+    callerId: string,
+    agentId: string,
+    turnId?: string,
+  ): ActiveTurnProgress | undefined {
+    const turn = this.observeActiveTurn(callerId, agentId, turnId);
+    if (!turn) return undefined;
+    return {
+      turn_id: turn.turnId,
+      ...buildActiveTurnProgress(turn.runtime.snapshotActivityMessages(), turn.startedAtMs),
+    };
+  }
+
+  /** Return a direct child's Active Turn Tail, with its tool definitions, for its waiting parent. */
+  inspectActiveTurnTranscript(
+    callerId: string,
+    agentId: string,
+    turnId?: string,
+  ): ChildAgentTranscriptSnapshot | undefined {
+    const turn = this.observeActiveTurn(callerId, agentId, turnId);
+    if (!turn) return undefined;
+    return selectActiveTurnTranscript(
+      this.inspectTranscript(agentId),
+      turn.startedAtMs,
+      ACTIVE_TURN_TRANSCRIPT_ASSISTANT_MESSAGES,
+    );
+  }
+
   /** Lazily inspect one Child Session Transcript without restoring a missing runtime. */
   inspectTranscript(agentId: string): ChildAgentTranscriptSnapshot {
     const agent = this.requireAgent(agentId);
@@ -528,15 +612,18 @@ export class MinimalSubagentsCoordinator {
     this.assertCallerCanManageAgent(callerId, agentId, "cancel");
     const target = this.requireUsableAgent(agentId, "cancel");
     const affected = recursive ? [target, ...this.descendantsOf(agentId)] : [target];
+    const affectedAgentIds: string[] = [];
     const cancelledTurnIds: string[] = [];
     for (const agent of affected) {
       const cancelledTurnId = await this.cancelActiveTurn(agent);
-      if (cancelledTurnId) cancelledTurnIds.push(cancelledTurnId);
+      if (!cancelledTurnId) continue;
+      affectedAgentIds.push(agent.agent_id);
+      cancelledTurnIds.push(cancelledTurnId);
     }
     return {
       agent_id: agentId,
       recursive,
-      affected_agent_ids: affected.map((agent) => agent.agent_id),
+      affected_agent_ids: affectedAgentIds,
       cancelled_turn_ids: cancelledTurnIds,
     };
   }
@@ -1315,24 +1402,27 @@ export class MinimalSubagentsCoordinator {
     message: CoordinatorMessage,
     targetId: string,
     delivery: PersistedCoordinationDelivery,
-  ): Promise<AgentMessageDisposition> {
+  ): Promise<{ disposition: AgentMessageDisposition; turnId?: string }> {
     this.waitHandedDeliveryIds.add(delivery.delivery_id);
     try {
-      await this.deliverToRecipient(targetId, message, () =>
+      const startedTurnId = await this.deliverToRecipient(targetId, message, () =>
         this.isCoordinationDeliveryCurrent(delivery),
       );
-      return "queued";
+      return startedTurnId
+        ? { disposition: "started-turn", turnId: startedTurnId }
+        : { disposition: "queued" };
     } catch (error) {
       this.waitHandedDeliveryIds.delete(delivery.delivery_id);
       throw error;
     }
   }
 
+  /** Deliver one message, returning the turn ID when it starts a new turn on an idle child. */
   private async deliverToRecipient(
     targetId: string,
     message: CoordinatorMessage,
     isCurrentDelivery: () => boolean = () => true,
-  ): Promise<void> {
+  ): Promise<string | undefined> {
     if (!isCurrentDelivery()) {
       throw new Error("Minimal subagents delivery abandoned after session branch change");
     }
@@ -1352,7 +1442,7 @@ export class MinimalSubagentsCoordinator {
     const visibleMessage = addCoordinatorMessageEnvelope(message);
     if (target.active_turn_id || runtime.isRunning) {
       await runtime.queueCoordinatorMessage(visibleMessage);
-      return;
+      return undefined;
     }
     const turnId = this.beginTurn(target);
     const runMessage = runtime
@@ -1374,6 +1464,7 @@ export class MinimalSubagentsCoordinator {
         }
       });
     this.trackBackgroundOperation(runMessage);
+    return turnId;
   }
 
   private trackBackgroundOperation(operation: Promise<void>): void {
@@ -1527,9 +1618,6 @@ export class MinimalSubagentsCoordinator {
 
   private buildAgentSummary(agent: PersistedAgent, includeDescendants = true): AgentSummary {
     const directChildren = this.childrenOf(agent.agent_id);
-    const children = includeDescendants
-      ? directChildren.map((child) => this.buildAgentSummary(child))
-      : [];
     const elapsed = agent.active_turn_started_at
       ? Math.max(0, this.now().getTime() - new Date(agent.active_turn_started_at).getTime())
       : undefined;
@@ -1538,7 +1626,7 @@ export class MinimalSubagentsCoordinator {
       model: agent.launch_contract.model,
       thinking_level: agent.launch_contract.thinking_level,
     };
-    return {
+    const summary: AgentSummary = {
       agent_id: agent.agent_id,
       parent_id: agent.parent_id,
       state: agent.active_turn_id ? "running" : "idle",
@@ -1553,8 +1641,11 @@ export class MinimalSubagentsCoordinator {
       latest_activity_at: agent.latest_activity_at ?? agent.created_at,
       task: agent.task,
       child_count: directChildren.length,
-      children,
     };
+    if (includeDescendants) {
+      summary.children = directChildren.map((child) => this.buildAgentSummary(child));
+    }
+    return summary;
   }
 
   private buildAgentDetail(agent: PersistedAgent, includeDescendants = true): AgentDetail {

package/src/minimal-subagents-extension.ts

@@ -505,6 +505,9 @@ export class MinimalSubagentsLifecycleController {
   private readonly coordinatorOperations: CoordinatorToolOperations = {
     spawn: (...args) => this.requireCoordinator().spawn(...args),
     inspectStatus: (...args) => this.requireCoordinator().inspectStatus(...args),
+    previewActiveTurn: (...args) => this.requireCoordinator().previewActiveTurn(...args),
+    inspectActiveTurnTranscript: (...args) =>
+      this.requireCoordinator().inspectActiveTurnTranscript(...args),
     sendAgentMessage: (...args) => this.requireCoordinator().sendAgentMessage(...args),
     wait: (...args) => this.requireCoordinator().wait(...args),
     status: (...args) => this.requireCoordinator().status(...args),

package/src/minimal-subagents-registry.ts

@@ -1,6 +1,7 @@
 import type { JsonValue } from "@earendil-works/pi-ai";
 import { Value } from "typebox/value";
 import { COORDINATOR_TOOL_NAMES } from "./minimal-subagents-capabilities.js";
+import { normalizeMinimalSubagentsUsage } from "./minimal-subagents-usage.js";
 import {
   createDeliveryLedger,
   deliveryLedgerSnapshot,
@@ -280,7 +281,8 @@ function cloneRegistryTurnResult(value: RegistryTurnResultWire): TurnResult {
     output: value.output,
   };
   if (value.error !== undefined) result.error = value.error;
-  if (value.usage !== undefined) result.usage = structuredClone(value.usage);
+  // Records from older versions may lack optional usage counters.
+  if (value.usage !== undefined) result.usage = normalizeMinimalSubagentsUsage(value.usage);
   if (value.elapsed_ms !== undefined) result.elapsed_ms = value.elapsed_ms;
   return result;
 }