@ian-pascoe/pi-minimal-subagents 0.2.1 → 0.2.2

package/README.md

@@ -141,22 +141,24 @@ the complete read-only discovery bundle.
 `agent_message` reports whether a message was delivered through an active
 parent wait, queued for the recipient, or failed. `subagent_wait` can return an
 intermediate Wait Event containing a Coordination Message before the child turn
-settles; call it again for the terminal turn 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 concurrent duplicate
-is rejected instead of competing for one Wait Event.
+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
+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
+concurrent duplicate is rejected instead of competing for one Wait Event.
 
 The persisted Delivery Ledger records Coordination Messages, terminal results,
 globally increasing sequence, and wait ownership before delivery. Existing
 items retain their sequence; gaps from skipped malformed records are valid.
-Claims can name only active, latest, or retained turns. Once a wait returns an
-intermediate message, that wait path owns the rest of the source turn across
-reloads, forks, and newer turns. Automatic fallback retains its ordered queue
-reservation, treats idle notifications as advisory, and rechecks actual
-recipient idleness before injecting a message. Destination-session Delivery
-Evidence settles and compacts ledger items, preventing duplicate delivery and
-unbounded checkpoint growth. The pure Delivery Ledger state machine retains at
+Claims can name only active, latest, or retained turns. Wait-returned messages
+retain individual delivery evidence; terminal wait ownership remains durable
+across reloads, forks, and newer turns. Automatic fallback retains its ordered
+queue reservation and sends every unclaimed Coordination Message and terminal
+result as a Pi steer, including while the recipient is active. Destination-session
+Delivery Evidence settles and compacts ledger items, preventing duplicate delivery
+and unbounded checkpoint growth. The pure Delivery Ledger state machine retains at
 most 20 pending wait-only terminal results per source agent; Coordination
 Messages are not removed by that terminal-retention limit. Delivered messages
 include stable delivery, source-agent, and source-turn identities in persisted

package/package.json

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

package/src/minimal-subagents-coordinator.ts

@@ -53,6 +53,7 @@ import type {
   StatusResult,
   TurnId,
   TurnResult,
+  WaitMessageResult,
   WaitResult,
 } from "./minimal-subagents-types.js";
 
@@ -85,11 +86,6 @@ interface PendingParentMessage {
   cancelGrace?: () => void;
 }
 
-interface CancelableWait {
-  promise: Promise<void>;
-  cancel: () => void;
-}
-
 function agentDeliveryKey(agentId: string, turnId: string): string {
   return `${agentId}\u0000${turnId}`;
 }
@@ -109,8 +105,9 @@ function terminalTurnResult(
   };
 }
 
-function terminalWaitResult(result: TurnResult): WaitResult {
-  return { event: "turn", ...structuredClone(result) };
+function terminalWaitResult(result: TurnResult, messages: WaitMessageResult[] = []): WaitResult {
+  const terminal = { event: "turn" as const, ...structuredClone(result) };
+  return messages.length === 0 ? terminal : { ...terminal, messages: structuredClone(messages) };
 }
 
 /** One root-owned coordinator for persistent nested Pi child sessions. */
@@ -124,11 +121,9 @@ export class MinimalSubagentsCoordinator {
   private readonly waiters = new Map<string, Set<TurnWaiter>>();
   private readonly pendingParentMessages = new Map<string, PendingParentMessage[]>();
   private readonly recipientQueues = new Map<string, Promise<unknown>>();
-  private readonly recipientIdleWaiters = new Map<string, Set<() => void>>();
   private readonly automaticDeliveryKeys = new Set<string>();
   private readonly automaticCoordinationDeliveryIds = new Set<string>();
   private readonly waitHandedDeliveryIds = new Set<string>();
-  private readonly automaticDeliveryClaimWaiters = new Map<string, Set<() => void>>();
   private readonly backgroundOperations = new Set<Promise<void>>();
   private acceptingOperations = true;
   private lifecycleEpoch = 0;
@@ -363,15 +358,16 @@ export class MinimalSubagentsCoordinator {
         new Error(`Minimal subagents duplicate wait: ${callerId} is already waiting for ${turnId}`),
       );
     }
-    const pendingMessage = this.claimPendingParentMessage(callerId, agentId, turnId);
-    if (pendingMessage) return Promise.resolve(pendingMessage);
     const retainedResult =
       findTerminalDelivery(this.deliveryLedger, agentId, turnId)?.result ??
       (agent.latest_result?.turn_id === turnId ? agent.latest_result : undefined);
     if (retainedResult) {
+      const messages = this.drainPendingParentMessages(callerId, agentId, turnId);
       this.claimTerminalDelivery(callerId, retainedResult);
-      return Promise.resolve(terminalWaitResult(retainedResult));
+      return Promise.resolve(terminalWaitResult(retainedResult, messages));
     }
+    const pendingMessage = this.claimPendingParentMessage(callerId, agentId, turnId);
+    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}`),
@@ -543,7 +539,6 @@ export class MinimalSubagentsCoordinator {
     this.agents.clear();
     this.deliveryLedger = createDeliveryLedger();
     this.pendingParentMessages.clear();
-    this.releaseAllRecipientIdleWaiters();
     this.recipientQueues.clear();
     this.backgroundOperations.clear();
     await Promise.allSettled(
@@ -558,12 +553,10 @@ export class MinimalSubagentsCoordinator {
     this.waiters.clear();
     this.pendingParentMessages.clear();
     this.waitHandedDeliveryIds.clear();
-    this.releaseAllRecipientIdleWaiters();
     this.recipientQueues.clear();
     this.backgroundOperations.clear();
     this.automaticDeliveryKeys.clear();
     this.automaticCoordinationDeliveryIds.clear();
-    this.automaticDeliveryClaimWaiters.clear();
     this.deliveryLedger = createDeliveryLedger({
       deliveries: snapshot.deliveries,
       coordination_deliveries: snapshot.coordination_deliveries,
@@ -720,13 +713,6 @@ export class MinimalSubagentsCoordinator {
     await Promise.allSettled(scheduled);
   }
 
-  /** Release ordered automatic deliveries after one recipient conversation becomes idle. */
-  markRecipientIdle(agentId: string): void {
-    const waiters = this.recipientIdleWaiters.get(agentId);
-    this.recipientIdleWaiters.delete(agentId);
-    for (const resolve of waiters ?? []) resolve();
-  }
-
   /** Clone complete child leaves for root fork ownership without ever sharing source session paths. */
   async prepareFork(sourceRootSessionFile: string): Promise<ForkSnapshot> {
     const activeRootChildren = this.childrenOf("root");
@@ -785,7 +771,6 @@ export class MinimalSubagentsCoordinator {
   shutdown(): Promise<void> {
     if (this.shutdownPromise) return this.shutdownPromise;
     this.acceptingOperations = false;
-    this.releaseAllRecipientIdleWaiters();
     this.shutdownPromise = this.finishShutdown();
     return this.shutdownPromise;
   }
@@ -999,7 +984,6 @@ export class MinimalSubagentsCoordinator {
       });
     }
     if (result.status !== "completed") this.removeSettledEmptyTurnClaim(agent.agent_id, turnId);
-    this.markRecipientIdle(agent.agent_id);
   }
 
   private async deliverAutomaticResult(
@@ -1024,15 +1008,6 @@ export class MinimalSubagentsCoordinator {
           this.settleDelivery(delivery);
           return;
         }
-        while (!this.isRecipientIdle(delivery.destination_agent_id)) {
-          const idleWait = this.createRecipientIdleWait(delivery.destination_agent_id);
-          const claimWait = this.createAutomaticDeliveryClaimWait(deliveryKey);
-          await Promise.race([idleWait.promise, claimWait.promise]);
-          idleWait.cancel();
-          claimWait.cancel();
-          if (!this.acceptingOperations || this.shouldStopAutomaticTerminalDelivery(delivery))
-            return;
-        }
         if (!this.acceptingOperations || this.shouldStopAutomaticTerminalDelivery(delivery)) return;
         if (this.hasDeliveryEvidence(delivery)) {
           this.settleDelivery(delivery);
@@ -1051,11 +1026,8 @@ export class MinimalSubagentsCoordinator {
             usage: result.usage,
           },
         };
-        await this.deliverToRecipient(
-          delivery.destination_agent_id,
-          message,
-          () => this.isTerminalDeliveryCurrent(delivery),
-          true,
+        await this.deliverToRecipient(delivery.destination_agent_id, message, () =>
+          this.isTerminalDeliveryCurrent(delivery),
         );
       });
     } catch (error) {
@@ -1263,7 +1235,6 @@ export class MinimalSubagentsCoordinator {
     targetId: string,
     message: CoordinatorMessage,
     isCurrentDelivery: () => boolean = () => true,
-    requireIdleRecipient = false,
   ): Promise<void> {
     if (!isCurrentDelivery()) {
       throw new Error("Minimal subagents delivery abandoned after session branch change");
@@ -1281,9 +1252,6 @@ export class MinimalSubagentsCoordinator {
       throw new Error("Minimal subagents delivery abandoned after session branch change");
     }
     const visibleMessage = addCoordinatorMessageEnvelope(message);
-    if (requireIdleRecipient && (target.active_turn_id || runtime.isRunning)) {
-      throw new Error(`Minimal subagents automatic delivery recipient became active: ${targetId}`);
-    }
     if (target.active_turn_id || runtime.isRunning) {
       await runtime.queueCoordinatorMessage(visibleMessage);
       return;
@@ -1367,8 +1335,6 @@ export class MinimalSubagentsCoordinator {
   private applyDeliveryLedgerTransition(transition: DeliveryLedgerTransition): void {
     this.deliveryLedger = transition.ledger;
     for (const delivery of transition.prunedTerminalDeliveries) {
-      const key = agentDeliveryKey(delivery.source_agent_id, delivery.source_turn_id);
-      this.releaseAutomaticDeliveryClaimWaiters(key);
       this.dependencies.registry.append(
         createRegistryEvent(this.dependencies.registry.rootSessionId, "delivery-pruned", {
           source_agent_id: delivery.source_agent_id,
@@ -1504,16 +1470,8 @@ export class MinimalSubagentsCoordinator {
   }
 
   private pruneDeliveryStateForDeletedAgent(agentId: string): void {
-    const previousTerminalDeliveries = this.deliveryLedger.terminalDeliveries;
     const previousCoordinationDeliveries = this.deliveryLedger.coordinationDeliveries;
     this.deliveryLedger = pruneDeliveryLedgerAgents(this.deliveryLedger, [agentId]).ledger;
-    for (const delivery of previousTerminalDeliveries) {
-      if (!this.isTerminalDeliveryCurrent(delivery)) {
-        this.releaseAutomaticDeliveryClaimWaiters(
-          agentDeliveryKey(delivery.source_agent_id, delivery.source_turn_id),
-        );
-      }
-    }
     for (const delivery of previousCoordinationDeliveries) {
       if (!this.isCoordinationDeliveryCurrent(delivery)) {
         this.waitHandedDeliveryIds.delete(delivery.delivery_id);
@@ -1673,7 +1631,6 @@ export class MinimalSubagentsCoordinator {
       (candidate) => candidate.callerId === destinationAgentId,
     );
     if (!waiter) return false;
-    this.claimDeliveryTurn(message.details.source_agent_id, message.details.source_turn_id);
     this.deliveryLedger = setCoordinationDeliveryPath(
       this.deliveryLedger,
       delivery.delivery_id,
@@ -1698,7 +1655,7 @@ export class MinimalSubagentsCoordinator {
     callerId: string,
     sourceAgentId: string,
     sourceTurnId: string,
-  ): WaitResult | undefined {
+  ): WaitMessageResult | undefined {
     const key = agentDeliveryKey(sourceAgentId, sourceTurnId);
     const pendingMessages = this.pendingParentMessages.get(key);
     const index = pendingMessages?.findIndex(
@@ -1715,7 +1672,6 @@ export class MinimalSubagentsCoordinator {
         )
         .sort((left, right) => left.sequence - right.sequence)[0];
       if (!retained) return undefined;
-      this.claimDeliveryTurn(sourceAgentId, sourceTurnId);
       this.deliveryLedger = setCoordinationDeliveryPath(
         this.deliveryLedger,
         retained.delivery_id,
@@ -1735,7 +1691,6 @@ export class MinimalSubagentsCoordinator {
     }
     const pending = pendingMessages[index];
     if (!pending) return undefined;
-    this.claimDeliveryTurn(sourceAgentId, sourceTurnId);
     const delivery = findCoordinationDelivery(this.deliveryLedger, pending.deliveryId);
     if (delivery) {
       this.deliveryLedger = setCoordinationDeliveryPath(
@@ -1747,10 +1702,6 @@ export class MinimalSubagentsCoordinator {
       if (currentDelivery) this.persistCoordinationDeliveryState(currentDelivery);
       this.waitHandedDeliveryIds.add(delivery.delivery_id);
     }
-    const sourceResult = this.agents.get(sourceAgentId)?.latest_result;
-    if (sourceResult?.turn_id === sourceTurnId) {
-      this.setTerminalDeliveryPathToWait(callerId, sourceResult);
-    }
     pending.claimed = true;
     pending.cancelGrace?.();
     pending.releaseClaim();
@@ -1766,6 +1717,20 @@ export class MinimalSubagentsCoordinator {
     };
   }
 
+  private drainPendingParentMessages(
+    callerId: string,
+    sourceAgentId: string,
+    sourceTurnId: string,
+  ): WaitMessageResult[] {
+    const messages: WaitMessageResult[] = [];
+    let message = this.claimPendingParentMessage(callerId, sourceAgentId, sourceTurnId);
+    while (message) {
+      messages.push(message);
+      message = this.claimPendingParentMessage(callerId, sourceAgentId, sourceTurnId);
+    }
+    return messages;
+  }
+
   private queuePendingParentMessage(
     targetId: string,
     message: CoordinatorMessage,
@@ -1821,20 +1786,11 @@ export class MinimalSubagentsCoordinator {
       pending.cancelGrace?.();
       pending.cancelGrace = undefined;
       if (!this.acceptingOperations || pending.claimed || turnClaimed()) return;
-      while (!this.isRecipientIdle(targetId)) {
-        const idleWait = this.createRecipientIdleWait(targetId);
-        await Promise.race([pending.claimPromise, idleWait.promise]);
-        idleWait.cancel();
-        if (!this.acceptingOperations || pending.claimed || turnClaimed()) return;
-      }
       if (!this.acceptingOperations || pending.claimed || turnClaimed()) return;
       this.removePendingParentMessage(key, pending);
       this.waitHandedDeliveryIds.add(delivery.delivery_id);
-      await this.deliverToRecipient(
-        targetId,
-        message,
-        () => this.isCoordinationDeliveryCurrent(delivery),
-        true,
+      await this.deliverToRecipient(targetId, message, () =>
+        this.isCoordinationDeliveryCurrent(delivery),
       );
     });
     void operation.catch((cause) => {
@@ -1874,14 +1830,12 @@ export class MinimalSubagentsCoordinator {
   }
 
   private setTerminalDeliveryPathToWait(callerId: string, result: TurnResult): void {
-    const key = agentDeliveryKey(result.agent_id, result.turn_id);
     const delivery = findTerminalDelivery(this.deliveryLedger, result.agent_id, result.turn_id);
     if (!delivery || delivery.destination_agent_id !== callerId || delivery.path === "wait") return;
     this.applyDeliveryLedgerTransition(
       setTerminalDeliveryPath(this.deliveryLedger, result.agent_id, result.turn_id, "wait"),
     );
     const retained = findTerminalDelivery(this.deliveryLedger, result.agent_id, result.turn_id);
-    this.releaseAutomaticDeliveryClaimWaiters(key);
     if (!retained) return;
     this.dependencies.registry.append(
       createRegistryEvent(this.dependencies.registry.rootSessionId, "delivery-pending", {
@@ -1890,57 +1844,6 @@ export class MinimalSubagentsCoordinator {
     );
   }
 
-  private isRecipientIdle(agentId: string): boolean {
-    if (agentId === "root") return this.dependencies.root.isIdle();
-    const agent = this.agents.get(agentId);
-    if (!agent || agent.active_turn_id) return false;
-    return !this.runtimes.get(agentId)?.isRunning;
-  }
-
-  private createRecipientIdleWait(agentId: string): CancelableWait {
-    const { promise, resolve: release } = Promise.withResolvers<void>();
-    const waiters = this.recipientIdleWaiters.get(agentId) ?? new Set();
-    waiters.add(release);
-    this.recipientIdleWaiters.set(agentId, waiters);
-    return {
-      promise,
-      cancel: () => {
-        const currentWaiters = this.recipientIdleWaiters.get(agentId);
-        currentWaiters?.delete(release);
-        if (currentWaiters?.size === 0) this.recipientIdleWaiters.delete(agentId);
-      },
-    };
-  }
-
-  private createAutomaticDeliveryClaimWait(deliveryKey: string): CancelableWait {
-    const { promise, resolve: release } = Promise.withResolvers<void>();
-    const waiters = this.automaticDeliveryClaimWaiters.get(deliveryKey) ?? new Set();
-    waiters.add(release);
-    this.automaticDeliveryClaimWaiters.set(deliveryKey, waiters);
-    return {
-      promise,
-      cancel: () => {
-        const currentWaiters = this.automaticDeliveryClaimWaiters.get(deliveryKey);
-        currentWaiters?.delete(release);
-        if (currentWaiters?.size === 0) this.automaticDeliveryClaimWaiters.delete(deliveryKey);
-      },
-    };
-  }
-
-  private releaseAutomaticDeliveryClaimWaiters(deliveryKey: string): void {
-    const waiters = this.automaticDeliveryClaimWaiters.get(deliveryKey);
-    this.automaticDeliveryClaimWaiters.delete(deliveryKey);
-    for (const resolve of waiters ?? []) resolve();
-  }
-
-  private releaseAllRecipientIdleWaiters(): void {
-    const allWaiters = [...this.recipientIdleWaiters.values()];
-    this.recipientIdleWaiters.clear();
-    for (const waiters of allWaiters) {
-      for (const resolve of waiters) resolve();
-    }
-  }
-
   private async cancelDuringShutdown(agentId: string): Promise<void> {
     const target = this.agents.get(agentId);
     if (!target) return;

package/src/minimal-subagents-extension.ts

@@ -5,7 +5,6 @@ import {
   getAgentDir,
   SessionManager,
   SettingsManager,
-  type AgentSettledEvent,
   type ExtensionAPI,
   type ExtensionContext,
   type ExtensionFactory,
@@ -107,7 +106,6 @@ function createRootConversationEndpoint(
         sourceTurnId,
         deliveryId,
       ),
-    isIdle: () => context.isIdle(),
   };
 }
 
@@ -331,7 +329,6 @@ export class MinimalSubagentsLifecycleController {
     this.pi.on("session_before_fork", (event, context) => this.prepareSessionFork(event, context));
     this.pi.on("session_tree", (event, context) => this.restoreSessionTree(event, context));
     this.pi.on("message_end", (event, context) => this.reconcileMessageDelivery(event, context));
-    this.pi.on("agent_settled", (event, context) => this.releaseSettledRecipient(event, context));
     this.pi.on("session_shutdown", (event, context) => this.shutdownSession(event, context));
   }
 
@@ -554,12 +551,6 @@ export class MinimalSubagentsLifecycleController {
     }
   }
 
-  private releaseSettledRecipient(_event: AgentSettledEvent, context: ExtensionContext): void {
-    if (!this.coordinator) return;
-    if (context.isIdle()) this.coordinator.markRecipientIdle("root");
-    this.uiController?.refresh();
-  }
-
   private async shutdownSession(
     event: SessionShutdownEvent,
     context: ExtensionContext,

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

@@ -132,6 +132,7 @@ const WaitMessageDetailsSchema = Type.Object({
   agent_id: Type.String(),
   turn_id: Type.String(),
   message_id: Type.String(),
+  delivery_id: Type.Optional(Type.String()),
   message: Type.String(),
   elapsed_ms: Type.Optional(Type.Number()),
   usage: Type.Optional(RenderUsageSchema),
@@ -145,6 +146,7 @@ const WaitTurnDetailsSchema = Type.Object({
   error: Type.Optional(Type.String()),
   elapsed_ms: Type.Optional(Type.Number()),
   usage: Type.Optional(RenderUsageSchema),
+  messages: Type.Optional(Type.Array(WaitMessageDetailsSchema)),
 });
 const StatusDetailsSchema = Type.Union([
   Type.Object({

package/src/minimal-subagents-rendering.ts

@@ -341,9 +341,12 @@ function renderWaitResult(
       : details.status;
   const duration = formatSubagentDuration(details.elapsed_ms);
   const tokens = formatSubagentTokenCount(details.usage?.totalTokens);
-  const metrics = [duration, tokens ? `${tokens} tokens` : undefined].filter(
-    (metric): metric is string => metric !== undefined,
-  );
+  const drainedMessageCount = details.event === "message" ? 0 : (details.messages?.length ?? 0);
+  const metrics = [
+    duration,
+    tokens ? `${tokens} tokens` : undefined,
+    drainedMessageCount > 0 ? `${drainedMessageCount} messages` : undefined,
+  ].filter((metric): metric is string => metric !== undefined);
   const summary = renderSubagentSummary(theme, status, agentId, metrics);
   if (options.isPartial || !options.expanded) {
     return new Text(`${summary}${options.isPartial ? "" : collapsedExpansionHint(theme)}`, 0, 0);
@@ -356,6 +359,14 @@ function renderWaitResult(
     container.addChild(renderLabelValue(theme, "Message ID", details.message_id));
     return container;
   }
+  if (details.messages && details.messages.length > 0) {
+    appendTextSection(
+      container,
+      theme,
+      "Messages",
+      details.messages.map((message) => message.message).join("\n\n"),
+    );
+  }
   const output = details.output ?? "";
   if (status === "completed") {
     if (output.length > 0) {

package/src/minimal-subagents-session-wire.ts

@@ -28,6 +28,11 @@ export const ForkOwnershipRecordSchema = Type.Object({
   direct_parent_id: Type.String(),
 });
 
+const DeliveryEvidenceMessageSchema = Type.Object({
+  delivery_id: Type.Optional(Type.String()),
+  message_id: Type.Optional(Type.String()),
+});
+
 /** Parses durable custom-message and wait-tool Delivery Evidence details. */
 export const DeliveryEvidenceDetailsSchema = Type.Object({
   event: Type.Optional(Type.String()),
@@ -35,6 +40,7 @@ export const DeliveryEvidenceDetailsSchema = Type.Object({
   source_turn_id: Type.String(),
   delivery_id: Type.Optional(Type.String()),
   message_id: Type.Optional(Type.String()),
+  messages: Type.Optional(Type.Array(DeliveryEvidenceMessageSchema)),
 });
 
 export type ChildSessionIdentityRecord = Static<typeof ChildSessionIdentityRecordSchema>;

package/src/minimal-subagents-sessions.ts

@@ -411,7 +411,11 @@ export function findDeliveryEvidence(
       return (
         details.source_agent_id === sourceAgentId &&
         details.source_turn_id === sourceTurnId &&
-        (details.delivery_id === deliveryId || details.message_id === deliveryId)
+        (details.delivery_id === deliveryId ||
+          details.message_id === deliveryId ||
+          details.messages?.some(
+            (message) => message.delivery_id === deliveryId || message.message_id === deliveryId,
+          ))
       );
     }
     if (waitToolResult && details.event === "message") return false;

package/src/minimal-subagents-tools.ts

@@ -202,7 +202,7 @@ export function createCoordinatorToolDefinitions(
     name: "subagent_wait",
     label: "Subagent Wait",
     description:
-      "Wait for one direct child's oldest observable turn, or select an exact retained turn_id. A Wait Event containing a Coordination Message may arrive first as event=message; call again for the terminal turn result. A successful wait durably claims that turn so later messages and its terminal result return through wait without duplicate automatic delivery. Timeout never cancels the child.",
+      "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 never cancels the child.",
     promptSnippet: "Wait for one direct child's exact turn",
     parameters: options.schemas.subagent_wait,
     async execute(_toolCallId, parameters, signal, onUpdate) {

package/src/minimal-subagents-types.ts

@@ -75,8 +75,14 @@ export interface WaitMessageResult {
   message: string;
 }
 
+/** Reports one terminal child turn and any earlier messages drained by the same wait. */
+export interface WaitTurnResult extends TurnResult {
+  event: "turn";
+  messages?: WaitMessageResult[];
+}
+
 /** Reports one terminal child turn returned by subagent_wait. */
-export type WaitResult = WaitMessageResult | ({ event: "turn" } & TurnResult);
+export type WaitResult = WaitMessageResult | WaitTurnResult;
 
 /** Provides bounded hierarchy, usage, and best-known Runtime Profile data for one persistent agent. */
 export interface AgentSummary extends RuntimeProfile {
@@ -243,8 +249,6 @@ export interface RootConversationEndpoint {
   /** Queue one typed coordinator message into the root conversation. */
   queueCoordinatorMessage(message: CoordinatorMessage): Promise<void>;
   hasDeliveryEvidence(sourceAgentId: string, sourceTurnId: string, deliveryId?: string): boolean;
-  /** Report whether automatic delivery can start a new root turn without racing an active wait. */
-  isIdle(): boolean;
 }
 
 /** Stores root-owned agent identity, launch contract, availability, and latest activity. */