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

package/README.md

@@ -39,9 +39,13 @@ From this package checkout, load the source directly with
    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.
+   response arrives automatically as a steer message. Without `turn_id`, a wait
+   skips turns whose result you already claimed or received automatically.
 3. `agent_message` continues an idle child: the result reports
-   `disposition: "started-turn"` with the new `turn_id` to wait on.
+   `disposition: "started-turn"` with the new `turn_id`. A plain
+   `subagent_wait({ agent_id })` targets that new turn, not the first result;
+   pass `turn_id` to re-read a turn whose result is still retained, claimed or
+   not.
 4. `subagent_status` inspects children; `subagent_cancel` stops work but keeps
    the session; `subagent_delete` removes it. Deleted IDs cannot be reused.
 
@@ -93,10 +97,10 @@ source branch, and a new branch without an override follows settings.
 
 ## Model roles
 
-`minimalSubagents.modelRoles` gives the parent agent advisory names for
+`minimalSubagents.modelRoles` gives the parent agent named, advisory choices of
 eligible models. The extension defines no roles itself, performs no task
-classification, and does not route launches. The parent still passes the
-ordinary `model` and `thinking_level` arguments separately.
+classification, and does not route launches: the parent names the role it wants
+with the optional `role` argument of `subagent`.
 
 ```json
 {
@@ -113,8 +117,9 @@ ordinary `model` and `thinking_level` arguments separately.
 ```
 
 A recognized final suffix (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`,
-or `max`) is a preferred `thinking_level`, not part of the canonical model
-passed to `subagent`. Unsuffixed roles leave thinking selection independent.
+or `max`) is the role's `thinking_level`, not part of the canonical model.
+Unsuffixed roles leave thinking selection independent: the child uses the
+caller's thinking level unless `thinking_level` is passed.
 Role names and hints are trimmed, single-line text. Names may be up to 64
 characters and hints up to 500 characters. Models use canonical
 `provider/model` IDs and must be available under the effective `enabledModels`
@@ -125,6 +130,27 @@ preference. A thinking level pinned in `enabledModels` neither supplies nor
 constrains a role preference, and normal spawn-time model-capability clamping
 still applies.
 
+### Launching with a role
+
+`subagent({ task, role: "design" })` launches the child with the `design` role's
+model and, when the role has a suffix, its thinking level. An explicit `model` or
+`thinking_level` overrides the role's value independently, so
+`{ role: "design", thinking_level: "low" }` keeps the role's model with a
+different thinking level. The role is recorded even when explicit `model` and
+`thinking_level` override all of its values. An unknown `role` fails before any
+child is created and lists the configured role names. The Launch Contract
+records the resolved `model` and `thinking_level` together with the `role` used
+(`role` is absent when none was named), and `subagent_status` and the expanded
+`subagent` result show it. Recording the name does not tie the child to the role: later settings
+changes never alter an existing Launch Contract.
+
+Roles are read when the session starts, so editing `modelRoles` mid-session
+changes nothing until a reload. The `role` parameter is a plain string rather
+than an enum of the configured names, so the tool definition stays
+byte-identical when `modelRoles` changes. Only the role list in the system
+prompt (the `subagent` prompt guidelines) changes, and only at reload. The
+`model` enum is separate: it already follows the eligible models.
+
 Global and project roles merge by name in settings order. Expanded role
 objects merge by field; a project string replaces the whole global entry. A
 project can remove one inherited role with `null`, or clear all inherited
@@ -310,10 +336,13 @@ 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, 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
+again for the same settled turn returns the same result while it is retained. Pass
+optional `turn_id` to address a retained turn exactly, including one whose
+result you already claimed (a claimed result stays retained until Delivery
+Evidence settles it). Without it, waits skip claimed turns and turns whose
+result was already delivered to you automatically, and select the oldest
+remaining observable turn, falling back to the active, then 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.
 When `timeout_ms` expires, the wait returns an observational `event: "timeout"`
 with the requested turn identity and the same detailed Child Agent status used
@@ -321,20 +350,26 @@ by targeted `subagent_status`. It removes only the waiter, leaving the child
 running and all pending delivery unclaimed. Abort signals remain errors.
 
 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. 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 while batching queued messages from one source turn into one
-Pi steer. Root-bound messages remain batchable while the root turn is active; a
-pending terminal result absorbs them. Child sessions drain all available steers
-before the next model call. Destination-session Delivery Evidence still settles
-each batched ledger item independently, 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 details.
+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. 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 while batching queued messages from one source turn into one Pi
+steer. Root-bound messages remain batchable while the root turn is active; a
+pending terminal result absorbs them. If Pi discards a root-bound steer before
+consuming it, as Esc does, the next root turn boundary reporting an empty Pi
+queue releases the result: a default wait selects it again at once, and
+automatic fallback re-sends it, ahead of newer results, into the root run if it
+is still going, or, after an abort such as Esc, when the root's next run starts.
+Recovery never starts a root turn by itself. Child sessions drain all available
+steers before the next model call. Destination-session Delivery Evidence still
+settles each batched ledger item independently, 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
+details.
 
 Deleting a child first verifies its session header and persistent identity,
 then uses the optional `trash` command when available and falls back to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [
@@ -53,7 +53,7 @@
     ]
   },
   "scripts": {
-    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   }
 }

package/src/minimal-subagents-config.ts

@@ -45,6 +45,16 @@ const ModelRolesSettingSchema = Type.Union([ModelRoleEntriesSchema, Type.Null()]
 
 type ModelRoleThinkingLevel = (typeof THINKING_LEVELS)[number];
 
+/** Whether `name` is trimmed single-line text of at most 64 characters, as every role name must be. */
+export function isModelRoleName(name: string): boolean {
+  return (
+    name.length > 0 &&
+    name === name.trim() &&
+    !/[\r\n]/.test(name) &&
+    name.length <= MODEL_ROLE_NAME_MAX_LENGTH
+  );
+}
+
 /** Describes one user-authored advisory model role shown to subagent callers. */
 export interface MinimalSubagentsModelRole {
   name: string;
@@ -294,12 +304,7 @@ function parseModelRoles(
   const roles: MinimalSubagentsModelRole[] = [];
   for (const [name, entry] of entries) {
     const path = `${entry.scope} minimalSubagents.modelRoles.${name}`;
-    if (
-      name.length === 0 ||
-      name !== name.trim() ||
-      /[\r\n]/.test(name) ||
-      name.length > MODEL_ROLE_NAME_MAX_LENGTH
-    ) {
+    if (!isModelRoleName(name)) {
       warnings.push(`${path}: role name must be trimmed single-line text up to 64 characters`);
       continue;
     }

package/src/minimal-subagents-coordinator.ts

@@ -23,6 +23,7 @@ import {
   claimDeliveryLedgerTurn,
   createDeliveryLedger,
   deliveryLedgerSnapshot,
+  deliveryTurnKey,
   findCoordinationDelivery,
   findTerminalDelivery,
   isDeliveryLedgerTurnClaimed,
@@ -42,6 +43,7 @@ import { withTroubleshootingHint } from "./troubleshooting-skill.js";
 import { addCoordinatorMessageEnvelope } from "./minimal-subagents-message-envelope.js";
 import { unavailableAgent } from "./minimal-subagents-sessions.js";
 import { createRegistryEvent } from "./minimal-subagents-registry.js";
+import type { MinimalSubagentsModelRole } from "./minimal-subagents-config.js";
 import type {
   ActiveTurnProgress,
   AgentDetail,
@@ -109,6 +111,16 @@ interface PendingParentMessage {
   cancelGrace?: () => void;
 }
 
+/** One terminal result queued to its parent, until Delivery Evidence settles it or Pi discards it. */
+interface TerminalHandOff {
+  /** Hand-off order, compared with the root's last ended message at a turn boundary. */
+  order: number;
+  /** Whether the result entered Pi's clearable steer queue instead of starting a root turn. */
+  queued: boolean;
+  /** Coordination Messages batched into the same steer. */
+  coordinationDeliveryIds: readonly string[];
+}
+
 function agentDeliveryKey(agentId: string, turnId: string): string {
   return `${agentId}\u0000${turnId}`;
 }
@@ -162,9 +174,18 @@ 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 automaticDeliveryKeys = new Set<string>();
+  /** In-flight automatic result hand-offs, each with the lifecycle epoch that owns it. */
+  private readonly automaticDeliveryKeys = new Map<string, number>();
   private readonly automaticCoordinationDeliveryIds = new Set<string>();
   private readonly waitHandedDeliveryIds = new Set<string>();
+  /** Terminal results already queued to their parent, until Delivery Evidence settles them. */
+  private readonly handedTerminalKeys = new Map<string, TerminalHandOff>();
+  /** Monotonic order of hand-offs, compared against the root's last ended message. */
+  private handOffOrder = 0;
+  /** The latest hand-off order a root `message_end` has seen; later hand-offs may postdate Pi's queue snapshot. */
+  private rootMessageEndOrder = 0;
+  /** Root results Pi discarded, awaiting the root's next run; each keeps its Delivery Ledger sequence. */
+  private readonly discardedRootResultKeys = new Set<string>();
   private readonly backgroundOperations = new Set<Promise<void>>();
   private acceptingOperations = true;
   private lifecycleEpoch = 0;
@@ -222,8 +243,10 @@ export class MinimalSubagentsCoordinator {
 
     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;
+    const role = parameters.role === undefined ? undefined : this.requireModelRole(parameters.role);
+    const model = parameters.model ?? role?.model ?? caller.model;
+    const requestedThinking =
+      parameters.thinking_level ?? role?.thinkingLevel ?? caller.thinkingLevel;
     const thinkingLevel = this.dependencies.sessions.resolveThinkingLevel(model, requestedThinking);
     const {
       ordinaryTools,
@@ -268,6 +291,8 @@ export class MinimalSubagentsCoordinator {
       missing_dependencies: [],
       recent_messages: [],
     };
+    // Added after `delegation`, matching the key order of replayed Launch Contracts.
+    if (role) agent.launch_contract.role = role.name;
     this.pendingAgentIds.add(agentId);
     let identity: ReturnType<AgentSessionFactory["createIdentity"]>;
     try {
@@ -352,6 +377,19 @@ export class MinimalSubagentsCoordinator {
     return result;
   }
 
+  private requireModelRole(name: string): MinimalSubagentsModelRole {
+    const roles = this.dependencies.modelRoles ?? [];
+    const role = roles.find((candidate) => candidate.name === name);
+    if (role) return role;
+    throw new Error(
+      `Minimal subagents spawn validation: unknown role ${JSON.stringify(name)}; ${
+        roles.length === 0
+          ? "no model roles are configured"
+          : `configured roles: ${roles.map((candidate) => candidate.name).join(", ")}`
+      }`,
+    );
+  }
+
   /** Capture immutable launch defaults for a nested caller from its active child runtime. */
   snapshotChildCaller(agentId: string, spawnEntryId: string): CallerSnapshot {
     const agent = this.requireAgent(agentId);
@@ -456,7 +494,7 @@ export class MinimalSubagentsCoordinator {
     if (agent.active_turn_id !== turnId) {
       return Promise.reject(
         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`,
+          `Minimal subagents wait: turn ${turnId} is unknown or no longer retained for ${agentId}; omit turn_id to wait for its oldest observable turn you have neither claimed nor received`,
         ),
       );
     }
@@ -720,6 +758,8 @@ export class MinimalSubagentsCoordinator {
     this.waiters.clear();
     this.waitHandedDeliveryIds.clear();
     this.automaticDeliveryKeys.clear();
+    this.handedTerminalKeys.clear();
+    this.discardedRootResultKeys.clear();
     this.automaticCoordinationDeliveryIds.clear();
     this.deliveryLedger = createDeliveryLedger({
       deliveries: snapshot.deliveries,
@@ -864,6 +904,102 @@ export class MinimalSubagentsCoordinator {
     await Promise.allSettled(scheduled);
   }
 
+  /** Note that a root message ended; results handed before it reached Pi's queue before the next turn boundary. */
+  recordRootMessageEnd(): void {
+    this.rootMessageEndOrder = this.handOffOrder;
+  }
+
+  /**
+   * Release results Pi discarded from the root's steer queue, as Esc does.
+   *
+   * Call only at a root turn boundary whose pending-message snapshot is empty. Pi persists a
+   * consumed steer before that boundary, so a queued result handed before the turn's last message
+   * either has Delivery Evidence and settles, or was discarded. A discarded result is selectable
+   * by a default wait again at once, with its batched Coordination Messages; automatic fallback
+   * re-sends it when the root's next run starts (`deliverDiscardedRootResults`).
+   */
+  requeueDiscardedRootResults(): void {
+    if (!this.acceptingOperations) return;
+    const candidates = this.deliveryLedger.terminalDeliveries
+      .filter((delivery) => {
+        if (delivery.destination_agent_id !== "root") return false;
+        const handOff = this.handedTerminalKeys.get(
+          deliveryTurnKey(delivery.source_agent_id, delivery.source_turn_id),
+        );
+        return handOff?.queued === true && handOff.order <= this.rootMessageEndOrder;
+      })
+      .sort(
+        (left, right) =>
+          (left.sequence ?? Number.MAX_SAFE_INTEGER) - (right.sequence ?? Number.MAX_SAFE_INTEGER),
+      );
+
+    for (const delivery of candidates) {
+      const handedKey = deliveryTurnKey(delivery.source_agent_id, delivery.source_turn_id);
+      const handOff = this.handedTerminalKeys.get(handedKey);
+      if (!handOff) continue;
+      const batched = handOff.coordinationDeliveryIds.flatMap((deliveryId) => {
+        const item = findCoordinationDelivery(this.deliveryLedger, deliveryId);
+        return item ? [item] : [];
+      });
+      if (this.hasDeliveryEvidence(delivery)) {
+        for (const item of batched) {
+          if (this.hasCoordinationDeliveryEvidence(item)) this.settleCoordinationDelivery(item);
+        }
+        this.settleDelivery(delivery);
+        continue;
+      }
+
+      this.handedTerminalKeys.delete(handedKey);
+      this.discardedRootResultKeys.add(handedKey);
+      for (const item of batched) {
+        this.waitHandedDeliveryIds.delete(item.delivery_id);
+        this.queuePendingParentMessage("root", item.message, item);
+      }
+    }
+  }
+
+  /** Whether a root result waits in Pi's clearable steer queue, so turn boundaries must be watched. */
+  hasQueuedRootHandOffs(): boolean {
+    for (const handOff of this.handedTerminalKeys.values()) if (handOff.queued) return true;
+    return false;
+  }
+
+  /**
+   * Queue results Pi discarded into a root run that just started, in Delivery Ledger sequence.
+   *
+   * Recovery never starts a root turn by itself, so Esc stays respected: the results wait, still
+   * selectable by a default wait, until the user or another delivery starts the root's next run.
+   */
+  deliverDiscardedRootResults(): void {
+    if (
+      this.discardedRootResultKeys.size === 0 ||
+      !this.acceptingOperations ||
+      this.dependencies.root.isIdle()
+    )
+      return;
+    const discarded = this.deliveryLedger.terminalDeliveries
+      .filter((delivery) =>
+        this.discardedRootResultKeys.has(
+          deliveryTurnKey(delivery.source_agent_id, delivery.source_turn_id),
+        ),
+      )
+      .sort(
+        (left, right) =>
+          (left.sequence ?? Number.MAX_SAFE_INTEGER) - (right.sequence ?? Number.MAX_SAFE_INTEGER),
+      );
+    this.discardedRootResultKeys.clear();
+    for (const delivery of discarded) {
+      const result = delivery.result ?? this.agents.get(delivery.source_agent_id)?.latest_result;
+      if (
+        delivery.path !== "message" ||
+        result?.status !== "completed" ||
+        result.turn_id !== delivery.source_turn_id
+      )
+        continue;
+      this.trackBackgroundOperation(this.deliverAutomaticResult(result, delivery, true));
+    }
+  }
+
   /** 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");
@@ -1157,17 +1293,27 @@ export class MinimalSubagentsCoordinator {
     if (result.status !== "completed") this.removeSettledEmptyTurnClaim(agent.agent_id, turnId);
   }
 
+  /**
+   * Hand one terminal result to its parent through automatic fallback.
+   *
+   * By default it waits its turn in the recipient queue, then the wait-claim grace period. A
+   * `resume` hand-off re-sends a root result Pi discarded: its grace period has passed and its
+   * sequence precedes everything still queued, so it is handed at once, synchronously up to Pi.
+   */
   private async deliverAutomaticResult(
     result: TurnResult,
     delivery: PersistedDelivery,
+    resume = false,
   ): Promise<void> {
     const deliveryKey = agentDeliveryKey(delivery.source_agent_id, delivery.source_turn_id);
+    const handedKey = deliveryTurnKey(delivery.source_agent_id, delivery.source_turn_id);
     if (this.automaticDeliveryKeys.has(deliveryKey)) return;
-    this.automaticDeliveryKeys.add(deliveryKey);
-    const graceMs = this.deliveryGraceMs();
+    const epoch = this.lifecycleEpoch;
+    this.automaticDeliveryKeys.set(deliveryKey, epoch);
+    const graceMs = resume ? 0 : this.deliveryGraceMs();
     let batchedCoordinationDeliveries: PersistedCoordinationDelivery[] = [];
     try {
-      await this.enqueueRecipientDelivery(delivery.destination_agent_id, async () => {
+      const handOff = async () => {
         if (delivery.destination_agent_id !== "root") {
           await this.ensureRuntime(
             this.requireUsableAgent(delivery.destination_agent_id, "message"),
@@ -1175,6 +1321,8 @@ export class MinimalSubagentsCoordinator {
           if (!this.isTerminalDeliveryCurrent(delivery)) return;
         }
         if (graceMs > 0) await new Promise((resolve) => setTimeout(resolve, graceMs));
+        // A branch change during the grace period abandons this hand-off; restore replays it.
+        if (epoch !== this.lifecycleEpoch) return;
         if (!this.acceptingOperations || this.shouldStopAutomaticTerminalDelivery(delivery)) return;
         if (this.hasDeliveryEvidence(delivery)) {
           this.settleDelivery(delivery);
@@ -1200,6 +1348,13 @@ export class MinimalSubagentsCoordinator {
         for (const batchedDelivery of batchedCoordinationDeliveries) {
           this.waitHandedDeliveryIds.add(batchedDelivery.delivery_id);
         }
+        // Installed before delivery so a settlement inside it removes the marker. Delivery up to
+        // Pi's `sendMessage` is synchronous, so the idle check predicts a steer versus a new turn.
+        this.handedTerminalKeys.set(handedKey, {
+          order: ++this.handOffOrder,
+          queued: delivery.destination_agent_id === "root" && !this.dependencies.root.isIdle(),
+          coordinationDeliveryIds: batchedCoordinationDeliveries.map((item) => item.delivery_id),
+        });
         await this.deliverToRecipient(
           delivery.destination_agent_id,
           combineCoordinatorMessages([
@@ -1210,8 +1365,14 @@ export class MinimalSubagentsCoordinator {
             this.isTerminalDeliveryCurrent(delivery) &&
             batchedCoordinationDeliveries.every((item) => this.isCoordinationDeliveryCurrent(item)),
         );
-      });
+      };
+      await (resume
+        ? handOff()
+        : this.enqueueRecipientDelivery(delivery.destination_agent_id, handOff));
     } catch (error) {
+      // A hand-off abandoned by a branch change must not touch the restored branch's state.
+      if (epoch !== this.lifecycleEpoch) return;
+      this.handedTerminalKeys.delete(handedKey);
       for (const batchedDelivery of batchedCoordinationDeliveries) {
         this.waitHandedDeliveryIds.delete(batchedDelivery.delivery_id);
       }
@@ -1231,7 +1392,10 @@ export class MinimalSubagentsCoordinator {
         }),
       );
     } finally {
-      this.automaticDeliveryKeys.delete(deliveryKey);
+      // Restore's replay may own the key again; release it only from the call that holds it.
+      if (this.automaticDeliveryKeys.get(deliveryKey) === epoch) {
+        this.automaticDeliveryKeys.delete(deliveryKey);
+      }
     }
   }
 
@@ -1317,6 +1481,7 @@ export class MinimalSubagentsCoordinator {
       sourceAgentId,
       destinationAgentId,
       waitHandedDeliveryIds: this.waitHandedDeliveryIds,
+      handedTurnKeys: this.handedTerminalKeys,
       activeTurnId: agent?.active_turn_id,
       latestResultTurnId: agent?.latest_result?.turn_id,
     });
@@ -1532,6 +1697,19 @@ export class MinimalSubagentsCoordinator {
         }),
       );
     }
+    this.dropStaleHandedTerminalKeys();
+  }
+
+  /** Forget handed markers whose terminal delivery left the ledger by settlement, pruning, or deletion. */
+  private dropStaleHandedTerminalKeys(): void {
+    const pending = new Set(
+      this.deliveryLedger.terminalDeliveries.map((delivery) =>
+        deliveryTurnKey(delivery.source_agent_id, delivery.source_turn_id),
+      ),
+    );
+    for (const key of this.handedTerminalKeys.keys()) {
+      if (!pending.has(key)) this.handedTerminalKeys.delete(key);
+    }
   }
 
   private isTerminalDeliveryCurrent(delivery: PersistedDelivery): boolean {
@@ -1607,6 +1785,7 @@ export class MinimalSubagentsCoordinator {
       delivery.source_agent_id,
       delivery.source_turn_id,
     ).ledger;
+    this.dropStaleHandedTerminalKeys();
     this.dependencies.registry.append(
       createRegistryEvent(this.dependencies.registry.rootSessionId, "delivery-settled", {
         source_agent_id: delivery.source_agent_id,
@@ -1672,6 +1851,7 @@ export class MinimalSubagentsCoordinator {
   private pruneDeliveryStateForDeletedAgent(agentId: string): void {
     const previousCoordinationDeliveries = this.deliveryLedger.coordinationDeliveries;
     this.deliveryLedger = pruneDeliveryLedgerAgents(this.deliveryLedger, [agentId]).ledger;
+    this.dropStaleHandedTerminalKeys();
     for (const delivery of previousCoordinationDeliveries) {
       if (!this.isCoordinationDeliveryCurrent(delivery)) {
         this.waitHandedDeliveryIds.delete(delivery.delivery_id);

package/src/minimal-subagents-delivery-ledger.ts

@@ -45,16 +45,19 @@ export interface AddedCoordinationDelivery extends DeliveryLedgerTransition {
   delivery: PersistedCoordinationDelivery;
 }
 
-/** Describes caller-visible inputs used to select the oldest observable source turn. */
+/** Describes caller-visible inputs used to select the oldest observable source turn the destination has neither claimed nor received. */
 export interface SelectObservableDeliveryTurnOptions {
   sourceAgentId: string;
   destinationAgentId: string;
   waitHandedDeliveryIds: ReadonlySet<string>;
+  /** `deliveryTurnKey`s of terminal results already queued to the destination automatically. */
+  handedTurnKeys?: { has(key: string): boolean };
   activeTurnId?: string;
   latestResultTurnId?: string;
 }
 
-function deliveryTurnKey(sourceAgentId: string, sourceTurnId: string): string {
+/** Compound source-agent and source-turn key shared by claims and process-local handed markers. */
+export function deliveryTurnKey(sourceAgentId: string, sourceTurnId: string): string {
   return `${sourceAgentId}\u0000${sourceTurnId}`;
 }
 
@@ -420,19 +423,20 @@ export function releaseEmptyDeliveryLedgerTurn(
     : releaseDeliveryLedgerTurn(ledger, sourceAgentId, sourceTurnId);
 }
 
-/** Select the oldest claimed, then oldest sequenced, observable source turn. */
+/**
+ * Select the oldest sequenced observable source turn whose terminal result the caller has neither
+ * claimed nor been handed automatically, falling back to the active, then latest, turn.
+ */
 export function selectObservableDeliveryTurn(
   ledger: DeliveryLedger,
   options: SelectObservableDeliveryTurnOptions,
 ): string | undefined {
-  const candidates = new Map<string, { claimed: boolean; sequence: number }>();
+  const candidates = new Map<string, number>();
   const addCandidate = (turnId: string, sequence: number) => {
-    const candidate = {
-      claimed: ledger.waitClaimedTurns.includes(deliveryTurnKey(options.sourceAgentId, turnId)),
-      sequence,
-    };
+    const turnKey = deliveryTurnKey(options.sourceAgentId, turnId);
+    if (ledger.waitClaimedTurns.includes(turnKey) || options.handedTurnKeys?.has(turnKey)) return;
     const existing = candidates.get(turnId);
-    if (!existing || sequence < existing.sequence) candidates.set(turnId, candidate);
+    if (existing === undefined || sequence < existing) candidates.set(turnId, sequence);
   };
   for (const delivery of ledger.coordinationDeliveries) {
     if (
@@ -451,10 +455,7 @@ export function selectObservableDeliveryTurn(
       addCandidate(delivery.source_turn_id, delivery.sequence ?? Number.MAX_SAFE_INTEGER);
     }
   }
-  const retained = [...candidates.entries()].sort((left, right) => {
-    if (left[1].claimed !== right[1].claimed) return left[1].claimed ? -1 : 1;
-    return left[1].sequence - right[1].sequence;
-  })[0]?.[0];
+  const retained = [...candidates.entries()].sort((left, right) => left[1] - right[1])[0]?.[0];
   return retained ?? options.activeTurnId ?? options.latestResultTurnId;
 }
 

package/src/minimal-subagents-extension.ts

@@ -17,6 +17,7 @@ import {
   type SessionShutdownEvent,
   type SessionStartEvent,
   type SessionTreeEvent,
+  type TurnEndEvent,
 } from "@earendil-works/pi-coding-agent";
 import { isKeyRelease, isKeyRepeat, matchesKey } from "@earendil-works/pi-tui";
 import {
@@ -182,9 +183,12 @@ function rootCallerSnapshot(pi: ExtensionAPI, context: ExtensionContext): Caller
 function createRootConversationEndpoint(
   pi: ExtensionAPI,
   context: ExtensionContext,
+  onSteer: () => void,
 ): RootConversationEndpoint {
   return {
     async queueCoordinatorMessage(message) {
+      // A running root takes the message as a clearable steer; an idle root starts a turn with it.
+      if (!context.isIdle()) onSteer();
       pi.sendMessage(
         {
           customType: message.customType,
@@ -517,6 +521,7 @@ export class MinimalSubagentsLifecycleController {
   private uiController: MinimalSubagentsUiController | undefined;
   private statusPanelController: MinimalSubagentsStatusPanelController | undefined;
   private viewerShortcut: ReturnType<typeof installViewerShortcut> | undefined;
+  private unwatchRootTurnEnds: (() => void) | undefined;
   private accessSession: ActiveSubagentAccessSession | undefined;
   private preparedFork:
     | { sourceSessionFile: string; selectedBranchSnapshot: RegistrySnapshot }
@@ -528,7 +533,10 @@ export class MinimalSubagentsLifecycleController {
     private readonly effects: MinimalSubagentsLifecycleEffects,
   ) {}
 
-  /** Register stable tools, renderers, and the six Pi lifecycle event handlers. */
+  /**
+   * Register stable tools, renderers, and the six static Pi lifecycle event handlers. `turn_end` is
+   * registered only while a result waits in the root's steer queue (`watchRootTurnEnds`).
+   */
   register(): void {
     const rootTools = createCoordinatorToolDefinitions({
       coordinator: this.coordinatorOperations,
@@ -552,6 +560,7 @@ 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_start", () => this.deliverDiscardedRootResults());
     this.pi.on("session_shutdown", (event, context) => this.shutdownSession(event, context));
   }
 
@@ -645,9 +654,10 @@ export class MinimalSubagentsLifecycleController {
     });
     activeCoordinator = new MinimalSubagentsCoordinator({
       sessions: sessionFactory,
-      root: createRootConversationEndpoint(this.pi, context),
+      root: createRootConversationEndpoint(this.pi, context, () => this.watchRootTurnEnds()),
       maxSubagentDepth: minimalSubagentsConfig.maxSubagentDepth,
       toolsets: minimalSubagentsConfig.toolsets,
+      modelRoles: minimalSubagentsConfig.modelRoles,
       registry: {
         rootSessionId,
         append: (registryEvent) => this.pi.appendEntry(REGISTRY_ENTRY_TYPE, registryEvent),
@@ -925,16 +935,63 @@ export class MinimalSubagentsLifecycleController {
     _context: ExtensionContext,
   ): Promise<void> {
     if (!this.coordinator) return;
+    this.coordinator.recordRootMessageEnd();
     if (event.message.role === "toolResult" || event.message.role === "custom") {
       await this.coordinator.reconcileDeliveries();
       this.uiController?.refresh();
     }
   }
 
+  /**
+   * Watch root turn boundaries while a result waits in the root's steer queue. Pi builds a boundary
+   * preview for every `turn_end` while any handler listens, so the handler is removed again once no
+   * queued result remains.
+   */
+  private watchRootTurnEnds(): void {
+    this.unwatchRootTurnEnds ??= this.pi.on("turn_end", (event, context) =>
+      this.requeueDiscardedRootResults(event, context),
+    );
+  }
+
+  private stopWatchingRootTurnEnds(): void {
+    this.unwatchRootTurnEnds?.();
+    this.unwatchRootTurnEnds = undefined;
+  }
+
+  /**
+   * Pi gives extensions no queue-cleared event, so Esc's discarded steers are found here: the turn
+   * boundary's pending-message preview is empty. Returns nothing, so the transcript, system prompt,
+   * and tools are unchanged.
+   *
+   * A queue clear without an abort (dequeue, RPC `clear_queue`) leaves the run going, so released
+   * results are steered back at once and Pi's poll after this boundary takes them in the same run.
+   * Esc aborts the run, so its released results wait for the root's next run.
+   */
+  private requeueDiscardedRootResults(event: TurnEndEvent, context: ExtensionContext): void {
+    if (!this.coordinator) {
+      this.stopWatchingRootTurnEnds();
+      return;
+    }
+    if (event.context.pendingMessages.length === 0) {
+      this.coordinator.requeueDiscardedRootResults();
+      if (context.signal && !context.signal.aborted) {
+        this.coordinator.deliverDiscardedRootResults();
+      }
+      this.uiController?.refresh();
+    }
+    if (!this.coordinator.hasQueuedRootHandOffs()) this.stopWatchingRootTurnEnds();
+  }
+
+  /** Re-send discarded results into a root run that just started; recovery never starts one. */
+  private deliverDiscardedRootResults(): void {
+    this.coordinator?.deliverDiscardedRootResults();
+  }
+
   private async shutdownSession(
     event: SessionShutdownEvent,
     context: ExtensionContext,
   ): Promise<void> {
+    this.stopWatchingRootTurnEnds();
     this.viewerShortcut?.dispose();
     this.viewerShortcut = undefined;
     this.statusPanelController?.dispose();

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

@@ -56,6 +56,7 @@ const ToolSelectionWireSchema = Type.Union([
 
 /** Parses persisted immutable Launch Contracts without coercion. */
 export const RegistryLaunchContractWireSchema = Type.Object({
+  role: Type.Optional(NonEmptyStringSchema),
   session_context: Type.Union([
     Type.Literal("inherit"),
     Type.Literal("compact"),

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 { isModelRoleName } from "./minimal-subagents-config.js";
 import { normalizeMinimalSubagentsUsage } from "./minimal-subagents-usage.js";
 import {
   createDeliveryLedger,
@@ -304,6 +305,7 @@ function parseRegistryLaunchContract(
 ): LaunchContract | undefined {
   if (
     !isCanonicalModelId(value.model) ||
+    (value.role !== undefined && !isModelRoleName(value.role)) ||
     !isUniqueNonEmptyStringArray(value.ordinary_tools) ||
     !excludesCoordinatorToolNames(value.ordinary_tools) ||
     (Array.isArray(value.tools) &&
@@ -320,6 +322,7 @@ function parseRegistryLaunchContract(
     ordinary_tools: [...value.ordinary_tools],
   };
   if (value.delegation !== undefined) launchContract.delegation = value.delegation;
+  if (value.role !== undefined) launchContract.role = value.role;
   return launchContract;
 }
 

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

@@ -23,6 +23,7 @@ const RenderUsageSchema = Type.Object({
 });
 
 const RenderLaunchContractSchema = Type.Object({
+  role: Type.Optional(Type.String()),
   session_context: Type.Optional(Type.String()),
   project_context: Type.Optional(Type.String()),
   model: Type.Optional(Type.String()),
@@ -87,6 +88,7 @@ const SpawnCallArgumentsSchema = Type.Object({
   agent_id: Type.Optional(Type.String()),
   session_context: Type.Optional(Type.String()),
   project_context: Type.Optional(Type.String()),
+  role: Type.Optional(Type.String()),
   model: Type.Optional(Type.String()),
   thinking_level: Type.Optional(Type.String()),
   delegation: Type.Optional(Type.String()),
@@ -219,6 +221,7 @@ const CoordinatorAgentDetailOutputSchema = Type.Object({
   ...CoordinatorAgentSummaryOutputSchema.properties,
   session_file: Type.Optional(Type.String()),
   launch_contract: Type.Object({
+    role: Type.Optional(Type.String()),
     session_context: Type.String(),
     project_context: Type.String(),
     model: Type.String(),

package/src/minimal-subagents-rendering.ts

@@ -445,6 +445,7 @@ function spawnCallLaunchSummary(args: SpawnCallArguments): string[] {
       ? undefined
       : `tools ${Array.isArray(args.tools) ? args.tools.join(", ") || "none" : args.tools}`;
   return [
+    args.role ? `role ${args.role}` : undefined,
     profile,
     tools,
     args.session_context && args.session_context !== "omit"
@@ -507,6 +508,7 @@ function renderSpawnResult(
     `delegation ${launchContract?.delegation ?? args.delegation ?? "none"}`,
     `session context ${launchContract?.session_context ?? args.session_context ?? "omit"}`,
     `project context ${launchContract?.project_context ?? args.project_context ?? "inherit"}`,
+    launchContract?.role ? `role ${launchContract.role}` : undefined,
     resolvedModel ? `model ${resolvedModel}` : undefined,
     resolvedThinking ? `thinking ${resolvedThinking}` : undefined,
   ].filter((value): value is string => value !== undefined);
@@ -770,6 +772,7 @@ function renderDetailedStatusAgent(
     const launchValues = [
       `session context ${launchContract.session_context ?? "inherit"}`,
       `project context ${launchContract.project_context ?? "inherit"}`,
+      ...(launchContract.role ? [`role ${launchContract.role}`] : []),
       `model ${launchContract.model ?? agent.model ?? "unknown"}`,
       `thinking ${launchContract.thinking_level ?? agent.thinking_level ?? "unknown"}`,
       `delegation ${launchContract.delegation ?? "none"}`,

package/src/minimal-subagents-sessions.ts

@@ -503,7 +503,9 @@ export function findDeliveryEvidence(
           ))
       );
     }
-    if (waitToolResult && details.event === "message") return false;
+    // A message or timeout wait result never carried the turn's terminal result.
+    if (waitToolResult && (details.event === "message" || details.event === "timeout"))
+      return false;
     return details.source_agent_id === sourceAgentId && details.source_turn_id === sourceTurnId;
   });
 }

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

@@ -26,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})*$";
@@ -55,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),

package/src/minimal-subagents-tools.ts

@@ -82,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.",
   ];
 }
 
@@ -310,7 +313,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. 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.",
+      "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: {

package/src/minimal-subagents-types.ts

@@ -1,6 +1,7 @@
 import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Usage } from "@earendil-works/pi-ai";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { MinimalSubagentsModelRole } from "./minimal-subagents-config.js";
 
 /** Controls how much committed caller conversation enters a new child session. */
 export type SessionContextMode = "inherit" | "compact" | "omit";
@@ -35,6 +36,8 @@ export interface SpawnParameters {
   agent_id?: string;
   session_context?: SessionContextMode;
   project_context?: ProjectContextMode;
+  /** Configured model role whose model and thinking level apply unless overridden below. */
+  role?: string;
   model?: string;
   thinking_level?: ThinkingLevel;
   tools?: ToolSelection;
@@ -199,6 +202,8 @@ export interface DeleteResult {
 
 /** Persists immutable context, model, thinking, and ordinary-tool launch choices. */
 export interface LaunchContract extends RuntimeProfile {
+  /** Configured model role the caller named at launch; absent when none was used. */
+  role?: string;
   session_context: SessionContextMode;
   project_context: ProjectContextMode;
   tools: ToolSelection | undefined;
@@ -424,6 +429,7 @@ export interface CoordinatorDependencies {
   root: RootConversationEndpoint;
   maxSubagentDepth?: number;
   toolsets?: MinimalSubagentsToolsets;
+  modelRoles?: readonly MinimalSubagentsModelRole[];
   now?: () => Date;
   automaticDeliveryGraceMs?: number;
   notify?: (notification: CoordinatorNotification) => void;