@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/subagent/manager.ts

@@ -38,16 +38,24 @@ import type { Message, TextContent } from "../providers/types.js";
 import { createAbortReason } from "../util/abort-reasons.js";
 import { getLogger } from "../util/logger.js";
 import { getSandboxWorkingDir } from "../util/platform.js";
+import { sleep } from "../util/retry.js";
 import { injectMessageIntoParent } from "./notify.js";
+import { isSubagentProgressEvent } from "./progress-events.js";
 import {
+  DEFAULT_SUBAGENT_ROLE,
+  formatSubagentToolStats,
   normalizeSubagentLabel,
   settleUnsupervisedStatus,
   SUBAGENT_LIMITS,
   SUBAGENT_ROLE_REGISTRY,
   type SubagentConfig,
+  subagentOutputContractText,
   type SubagentRole,
+  type SubagentSpawnMode,
   type SubagentState,
   type SubagentStatus,
+  type SubagentToolStatsReading,
+  type SubagentToolStatsSummary,
   TERMINAL_STATUSES,
 } from "./types.js";
 
@@ -68,6 +76,21 @@ const SWEEP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
  */
 const MAX_REHYDRATED_TERMINAL_RECORDS = 200;
 
+/**
+ * How long {@link SubagentManager.settleQueuedTurns} waits for a queued
+ * follow-up turn before reporting the subagent as still moving.
+ *
+ * Sized for the drain handoff, not for the turn itself: the queue is taken
+ * some milliseconds before the processing lock, and a wait shorter than that
+ * gap would mistake a turn that is starting for one that already finished. A
+ * guidance turn that is genuinely mid-flight outlives any budget worth
+ * blocking the parent's tool call for, so it is reported as unfinished instead
+ * of waited out.
+ */
+const QUEUED_TURN_SETTLE_TIMEOUT_MS = 2_000;
+/** Gap between queue observations while a queued turn is waiting to start. */
+const QUEUED_TURN_POLL_MS = 25;
+
 // ── Durable record → state mapping ─────────────────────────────────────
 
 /**
@@ -81,6 +104,11 @@ const MAX_REHYDRATED_TERMINAL_RECORDS = 200;
  * `SubagentConfig` fields that are not persisted (context, prompts, trust,
  * profile overrides) are absent, so this shape answers lifecycle questions
  * only.
+ *
+ * Tool-call counters are in-memory only and the row carries none, so a state
+ * built here never has {@link SubagentState.stats}. What that absence means is
+ * the manager's answer to give, not this shape's: see
+ * {@link SubagentManager.currentToolStats}.
  */
 export function subagentStateFromRecord(rec: SubagentRecord): SubagentState {
   return {
@@ -169,6 +197,18 @@ function extractFinalAssistantText(messages: Message[]): string {
   return "";
 }
 
+/**
+ * Snapshot the child conversation's live tool-call counters before the
+ * conversation is released. The `filesWritten` Set collapses to its size so
+ * nothing keeps a reference into the released conversation.
+ */
+function snapshotToolStats(
+  conversation: Conversation,
+): SubagentToolStatsSummary {
+  const { calls, succeeded, filesWritten } = conversation.subagentToolStats;
+  return { calls, succeeded, filesWritten: filesWritten.size };
+}
+
 /**
  * Pull the user-visible text out of a streaming delta event, or null for any
  * other event type. Used by the synchronous `onText` tap to forward
@@ -191,12 +231,15 @@ export function buildSubagentSystemPrompt(
   role: SubagentRole,
 ): string {
   const roleConfig = SUBAGENT_ROLE_REGISTRY[role];
-  const sections: string[] = [
-    roleConfig.systemPromptPreamble,
-    "",
-    "## Your Task",
-    config.objective,
-  ];
+  const sections: string[] = [roleConfig.systemPromptPreamble];
+  if (config.persona) {
+    sections.push(`- Persona: act as ${config.persona} for this task.`);
+  }
+  const contractText = subagentOutputContractText(config.outputContract);
+  if (contractText) {
+    sections.push(`- Output contract: ${contractText}`);
+  }
+  sections.push("", "## Your Task", config.objective);
   if (config.context) {
     sections.push("", "## Context from Parent", config.context);
   }
@@ -207,6 +250,7 @@ export function buildSubagentSystemPrompt(
     "- You cannot spawn nested subagents.",
     "- Use notify_parent to report important findings, or if you are blocked.",
     '- If the objective needs a capability your role\'s tools do not provide (for example, writing or editing a file, or running a command, with a read-only role), do NOT fabricate a completed result — call notify_parent with urgency "blocked", name the capability you lack (e.g. file_write), and stop.',
+    "- If a tool call fails, or a tool you expected is unavailable, report the failure verbatim and stop that line of work. Never simulate, reconstruct, or invent tool output you did not actually receive.",
   );
   return sections.join("\n");
 }
@@ -234,6 +278,8 @@ export function buildSubagentTerminalMessage(opts: {
   deferred?: boolean;
   /** Tools the subagent attempted but that its role allowlist denied. */
   deniedTools?: string[];
+  /** What the subagent actually ran, harvested when the run ended. */
+  stats?: SubagentToolStatsSummary;
 }): string {
   const {
     label,
@@ -245,6 +291,7 @@ export function buildSubagentTerminalMessage(opts: {
     error,
     deferred,
     deniedTools,
+    stats,
   } = opts;
   const prefix = isFork ? "Fork" : "Subagent";
 
@@ -254,9 +301,14 @@ export function buildSubagentTerminalMessage(opts: {
   const many = (deniedTools?.length ?? 0) > 1;
   const deniedNote =
     deniedTools && deniedTools.length > 0
-      ? `\n\nNote: this ${prefix.toLowerCase()} attempted ${deniedTools.join(", ")} but its role does not permit ${many ? "them" : "it"}. If the objective requires ${many ? "those" : "that"}, re-spawn with a role that includes ${many ? "them" : "it"} (e.g. \`coder\`).`
+      ? `\n\nNote: this ${prefix.toLowerCase()} attempted ${deniedTools.join(", ")} but its role does not permit ${many ? "them" : "it"}. If the objective requires ${many ? "those" : "that"}, re-spawn with a role that includes ${many ? "them" : "it"} (e.g. \`builder\`).`
       : "";
 
+  // Machine truth envelope: the counts the parent can check the synthesis
+  // above against. Absent when the run never reached the harvest, and on the
+  // deferred path, where the counters are still moving (see the caller).
+  const statsNote = stats ? `\n\n${formatSubagentToolStats(stats)}` : "";
+
   if (outcome === "failed") {
     return (
       `[${prefix} "${label}" failed]\n\n` +
@@ -273,7 +325,8 @@ export function buildSubagentTerminalMessage(opts: {
       (silent
         ? `(Use these findings internally; do not relay the raw ${prefix.toLowerCase()} output to the user.)`
         : `(Incorporate this into your reply to the user as appropriate.)`) +
-      deniedNote
+      deniedNote +
+      statsNote
     );
   }
 
@@ -288,7 +341,8 @@ export function buildSubagentTerminalMessage(opts: {
     `[${prefix} "${label}" completed]\n\n` +
     `${reason}. Use subagent_read with subagent_id "${subagentId}"${lastN} for the latest output.` +
     (silent ? ` Keep the result internal.` : ``) +
-    deniedNote
+    deniedNote +
+    statsNote
   );
 }
 
@@ -302,6 +356,14 @@ interface ManagedSubagent {
   parentSendToClient: (msg: AssistantEvent) => void;
   /** Epoch ms after which this terminal entry can be removed by the TTL sweep. */
   retainedUntil?: number;
+  /**
+   * True for an entry the startup rehydration rebuilt from a durable row
+   * rather than a run this process executed. Such an entry sits in the manager
+   * exactly like a live one but can never have tool-call counters, so
+   * {@link SubagentManager.currentToolStats} reads this to tell "never
+   * measured here" apart from "not measured yet".
+   */
+  rehydrated?: boolean;
   /**
    * Sticky monotonic flag: set to true when sendMessage enqueues a follow-up
    * message while a run is in progress, and never cleared. Needed because the
@@ -331,6 +393,15 @@ interface ManagedSubagent {
    * this callback IN ADDITION to the normal `subagent_event` envelope.
    */
   onText?: (chunk: string) => void;
+  /**
+   * Optional liveness tap for the synchronous path. When set,
+   * `wrappedSendToClient` fires it once per event that shows the child is still
+   * moving (see {@link isSubagentProgressEvent}), which is a superset of the
+   * `onText` chunks: a subagent executing a tool streams no token but is not
+   * stalled. Callers that bound a synchronous run by an idle window re-arm it
+   * here.
+   */
+  onProgress?: () => void;
 }
 
 export interface SubagentNotificationInfo {
@@ -413,7 +484,11 @@ export class SubagentManager {
   private async setUpSubagent(
     config: Omit<SubagentConfig, "id">,
     parentSendToClient: (msg: AssistantEvent) => void,
-    opts?: { synchronous?: boolean; onText?: (chunk: string) => void },
+    opts?: {
+      synchronous?: boolean;
+      onText?: (chunk: string) => void;
+      onProgress?: () => void;
+    },
   ): Promise<{ subagentId: string; managed: ManagedSubagent }> {
     // ── Limit checks ────────────────────────────────────────────────
 
@@ -428,22 +503,13 @@ export class SubagentManager {
     }
 
     // ── Resolve role ─────────────────────────────────────────────────
+    // A role is one of the three types, or absent for an internal caller that
+    // states no shape and runs on the default. The `subagent_spawn` tool
+    // resolves whatever the model wrote into a type before it gets here (see
+    // subagent/role-resolution.ts), so an unregistered value at this point is
+    // an internal caller's bug and is worth throwing over.
     const isFork = config.fork === true;
-    const role: SubagentRole = (config.role as SubagentRole) ?? "general";
-    if (isFork && role !== "general") {
-      // A context-inheriting subagent normally keeps the parent's `general`
-      // role so its KV cache stays aligned with the parent conversation. An
-      // explicit non-general role opts out of that alignment on purpose
-      // (e.g. the advisor role running on a stronger profile), so honor it.
-      log.warn(
-        {
-          requestedRole: role,
-          parentConversationId: config.parentConversationId,
-          label: config.label,
-        },
-        "Fork requested with non-general role — caller opted out of parent KV-cache alignment",
-      );
-    }
+    const role: SubagentRole = config.role ?? DEFAULT_SUBAGENT_ROLE;
     if (!SUBAGENT_ROLE_REGISTRY[role]) {
       throw new Error(
         `Invalid subagent role "${config.role}". Must be one of: ${Object.keys(SUBAGENT_ROLE_REGISTRY).join(", ")}`,
@@ -451,14 +517,29 @@ export class SubagentManager {
     }
     const roleConfig = SUBAGENT_ROLE_REGISTRY[role];
 
+    // ── Resolve spawn mode ───────────────────────────────────────────
+    // The spawning call site is the only layer that can tell an advisor
+    // consult or a live-voice continuation apart from a plain fork, so it
+    // declares its mode. The fallback is mechanical rather than NULL: a
+    // future call site that forgets still records honest context-inheritance
+    // shape instead of dropping out of the telemetry breakdown entirely.
+    const spawnMode: SubagentSpawnMode =
+      config.spawnMode ?? (isFork ? "fork" : "regular");
+
     // ── Create conversation ─────────────────────────────────────────
     const subagentId = uuid();
+    // `subagentRole` / `subagentSpawnMode` are stamped on the conversation
+    // row, not just the `subagents` row, because `subagents` rows are deleted
+    // on dispose while usage telemetry flushes on a watermark that can trail
+    // far behind. See migration 362.
     const conversationRecord = await bootstrapConversation({
       conversationType: "background",
       source: "subagent",
       origin: "subagent",
       systemHint: `Subagent: ${config.label}`,
       parentConversationId: config.parentConversationId,
+      subagentRole: role,
+      subagentSpawnMode: spawnMode,
     });
 
     // ── Build conversation dependencies ─────────────────────────────
@@ -555,6 +636,7 @@ export class SubagentManager {
       parentSendToClient,
       ...(opts?.synchronous ? { synchronous: true } : {}),
       ...(opts?.onText ? { onText: opts.onText } : {}),
+      ...(opts?.onProgress ? { onProgress: opts.onProgress } : {}),
     };
 
     // Wrap sendToClient to envelope all events with the subagent ID.
@@ -569,6 +651,11 @@ export class SubagentManager {
           managed.onText(text);
         }
       }
+      // Liveness tap, separate from the text tap because tool activity is
+      // progress the caller must see and is not a chunk it can forward.
+      if (managed.onProgress && isSubagentProgressEvent(msg)) {
+        managed.onProgress();
+      }
       managed.parentSendToClient({
         type: "subagent_event",
         subagentId,
@@ -589,10 +676,11 @@ export class SubagentManager {
         // Records the parent at construction; drives isSubagent and notify
         // routing from non-writable in-process state.
         parentConversationId: config.parentConversationId,
-        // The advisor consult runs tool-less for CLIENT tools but should ground
-        // its guidance with provider-native web search when the resolved
-        // provider supports it. This is a server tool the provider runs itself,
-        // so it stays one-shot — no client tool surfaced, allowlist unchanged.
+        // The advisor consult is scoped to read-only CLIENT tools and should
+        // also ground its guidance with provider-native web search when the
+        // resolved provider supports it. This is a server tool the provider
+        // runs itself, so no client tool is surfaced and the allowlist is
+        // unchanged.
         // Other roles keep the default (no native search appended).
         ...(role === "advisor" ? { enableNativeWebSearch: true } : {}),
       },
@@ -613,10 +701,17 @@ export class SubagentManager {
     // wins over parent inheritance: a parent that stamps trust per-turn (the
     // live-voice bridge) has already cleared it by the time a detached spawn
     // reads it, so its spawner resolves trust itself.
+    //
+    // Inherit the parent's *turn* trust ahead of its conversation-level slot:
+    // the slot holds whichever actor sent most recently, so a spawn during one
+    // actor's turn would otherwise run under another's privileges.
+    const parentTurnTrust =
+      parentConversation?.currentTurnTrustContext ??
+      parentConversation?.trustContext;
     if (config.trustContext) {
       conversation.setTrustContext({ ...config.trustContext });
-    } else if (parentConversation?.trustContext) {
-      conversation.setTrustContext({ ...parentConversation.trustContext });
+    } else if (parentTurnTrust) {
+      conversation.setTrustContext({ ...parentTurnTrust });
     }
     const parentAuthContext = parentConversation?.getAuthContext();
     if (parentAuthContext) {
@@ -645,18 +740,18 @@ export class SubagentManager {
       conversation.hasSystemPromptOverride = true;
     }
 
-    // Apply the role's tool allowlist when one is defined. The `general` role
-    // has `allowedTools: undefined`, so default forks (which keep the general
-    // role) are unaffected; a fork carrying an explicit role gets its
-    // allowlist applied like any other subagent.
+    // Apply the role's tool allowlist when one is defined. `builder` defines
+    // none, so it keeps the full surface its conversation projects; the scoped
+    // roles are filtered to their own list whether or not this is a fork.
     if (roleConfig.allowedTools) {
       conversation.setSubagentAllowedTools(new Set(roleConfig.allowedTools));
     }
 
     // A read-only subagent refuses side-effecting tools regardless of trust
-    // class; the executor gate rejects
-    // any such dispatch and they are kept off the model's tool surface.
-    if (config.denySideEffectTools) {
+    // class; the executor gate rejects any such dispatch and they are kept off
+    // the model's tool surface. The role carries the gate so a caller cannot
+    // spawn a role past it, and a spawn can still ask for it on top.
+    if (config.denySideEffectTools || roleConfig.denySideEffects) {
       conversation.setSubagentDenySideEffects(true);
     }
 
@@ -745,12 +840,20 @@ export class SubagentManager {
   async spawnAndAwait(
     config: Omit<SubagentConfig, "id">,
     parentSendToClient: (msg: AssistantEvent) => void,
-    opts?: { signal?: AbortSignal; onText?: (chunk: string) => void },
+    opts?: {
+      signal?: AbortSignal;
+      onText?: (chunk: string) => void;
+      onProgress?: () => void;
+    },
   ): Promise<string> {
     const { subagentId, managed } = await this.setUpSubagent(
       config,
       parentSendToClient,
-      { synchronous: true, ...(opts?.onText ? { onText: opts.onText } : {}) },
+      {
+        synchronous: true,
+        ...(opts?.onText ? { onText: opts.onText } : {}),
+        ...(opts?.onProgress ? { onProgress: opts.onProgress } : {}),
+      },
     );
 
     // Wire the external signal to abort the child conversation. If the signal
@@ -863,13 +966,24 @@ export class SubagentManager {
       // the generic "complete this task and return your findings" wrapper would
       // fight that framing. The advisor's objective is already the bare advice
       // request (`advisorRequestText()`), so it is sent uncontested.
+      //
+      // A fork's persona and output contract ride in this framing rather than
+      // the system prompt: the prompt is the parent's, inherited verbatim to
+      // keep the KV cache aligned, so the task message is the only place a
+      // fork-specific instruction can land.
       const useForkFraming =
         managed.state.isFork && managed.state.config.role !== "advisor";
+      const forkPersona = managed.state.config.persona;
+      const forkContract = subagentOutputContractText(
+        managed.state.config.outputContract,
+      );
       const message = useForkFraming
         ? [
             "⎯⎯⎯ FORK TASK ⎯⎯⎯",
             "You have been forked from the parent conversation to execute a specific task.",
             "The conversation above is context — do NOT continue it. Do NOT spawn sub-agents.",
+            ...(forkPersona ? [`Act as ${forkPersona} for this task.`] : []),
+            ...(forkContract ? [`Output contract: ${forkContract}`] : []),
             "Complete this task directly and return only your findings:",
             "",
             objective,
@@ -887,6 +1001,11 @@ export class SubagentManager {
         ...(managed.state.config.forceOverrideProfile
           ? { forceOverrideProfile: true }
           : {}),
+        // Stamp the child's usage with the firing that spawned it so schedule
+        // cost reporting sees delegated spend.
+        ...(managed.state.config.cronRunId
+          ? { cronRunId: managed.state.config.cronRunId }
+          : {}),
       });
 
       // Agent loop completed successfully.
@@ -898,6 +1017,12 @@ export class SubagentManager {
       const deniedTools = [...conversation.subagentDeniedToolNames];
       // Copy usage stats from the conversation before sending status (which includes usage).
       managed.state.usage = { ...conversation.usageStats };
+      // Same window for the tool-call counts: the terminal notification below
+      // reads them off the state. This is the first reading, not necessarily
+      // the last, since a follow-up turn queued during the run drains after
+      // this returns and keeps counting into the same conversation. Later
+      // readers go through `currentToolStats` for the settled numbers.
+      managed.state.stats = snapshotToolStats(conversation);
       // Only update state + notify if still non-terminal (guards against abort race).
       if (!TERMINAL_STATUSES.has(managed.state.status)) {
         managed.state.completedAt = Date.now();
@@ -925,6 +1050,7 @@ export class SubagentManager {
       // Copy usage from the captured conversation reference — managed.conversation
       // may have been nulled by an external dispose() before catch runs.
       managed.state.usage = { ...conversation.usageStats };
+      managed.state.stats = snapshotToolStats(conversation);
 
       // Only update status if not already terminal (e.g. aborted).
       if (!TERMINAL_STATUSES.has(managed.state.status)) {
@@ -1167,9 +1293,19 @@ export class SubagentManager {
 
   // ── Send message to subagent ──────────────────────────────────────────
 
+  /**
+   * Deliver a follow-up message to a live subagent.
+   *
+   * `opts.cronRunId` is the firing that produced THIS message, not the one the
+   * subagent was spawned under: a continuation turn's spend belongs to the
+   * firing that asked for it. Only the immediately-processed turn carries it,
+   * since a queued message drains through the conversation's own queue, which
+   * holds no per-message run options.
+   */
   async sendMessage(
     subagentId: string,
     content: string,
+    opts?: { cronRunId?: string | null },
   ): Promise<"sent" | "empty" | "not_found" | "terminal"> {
     const trimmed = content?.trim();
     if (!trimmed) {
@@ -1208,6 +1344,7 @@ export class SubagentManager {
           ...(managed.state.config.forceOverrideProfile
             ? { forceOverrideProfile: true }
             : {}),
+          ...(opts?.cronRunId ? { cronRunId: opts.cronRunId } : {}),
         })
         .catch((err) => {
           log.error({ subagentId, err }, "Subagent message processing failed");
@@ -1222,6 +1359,116 @@ export class SubagentManager {
     return this.subagents.get(subagentId)?.state;
   }
 
+  /**
+   * The subagent's tool-call counters, brought up to date first, or why there
+   * are none (see {@link SubagentToolStatsReading}).
+   *
+   * `runSubagent` harvests when its awaited agent loop returns, but that is not
+   * the end of the child's work: guidance queued during the run drains
+   * afterwards, on the same conversation, and those calls land in the same
+   * counters. So any read taken later re-reads them while the conversation is
+   * still retained (see {@link refreshToolStats}), and the release freezes the
+   * settled numbers. Readers that need the queued turn's calls included wait
+   * for it first, via {@link settleQueuedTurns}.
+   *
+   * An id the manager does not hold is `unrecoverable` rather than unknown:
+   * counters exist nowhere else, so no caller can ever obtain them, and the
+   * only state a caller can be holding for such an id came from the durable
+   * row.
+   */
+  currentToolStats(subagentId: string): SubagentToolStatsReading {
+    const managed = this.subagents.get(subagentId);
+    if (!managed) {
+      return { kind: "unrecoverable" };
+    }
+    this.refreshToolStats(managed);
+    if (managed.state.stats) {
+      return { kind: "counted", stats: managed.state.stats };
+    }
+    return managed.rehydrated
+      ? { kind: "unrecoverable" }
+      : { kind: "unmeasured" };
+  }
+
+  /**
+   * Wait for a follow-up turn queued during the subagent's run to finish.
+   *
+   * `runSubagent` marks the subagent terminal as soon as its own agent loop
+   * returns, and the parent is told to read from there. Guidance queued during
+   * that run drains afterwards though, on the same retained conversation, so a
+   * read taken in that window sees the transcript and the counters from before
+   * the guidance landed and never comes back for the rest. Waiting here closes
+   * the window.
+   *
+   * Resolves `true` once the retained conversation is idle with an empty
+   * queue, and `false` when `timeoutMs` elapses first, so the reader always
+   * gets an answer within a bound and can say the subagent is still moving
+   * rather than pass a partial result off as final.
+   *
+   * `true` comes back immediately when nothing can still be running: no
+   * manager entry, no retained conversation (a released one has its transcript
+   * and counters frozen), or a run that never had anything queued.
+   *
+   * Idle is confirmed across two observations a poll apart. The drain takes
+   * the queue before it takes the processing lock (`drainQueue` shifts the
+   * message, then `drainSingleMessage` awaits slash resolution and the
+   * user-message persist before `runAgentLoop` sets processing), so a single
+   * look into that gap finds an empty queue and an unlocked conversation while
+   * the turn is in fact starting.
+   */
+  async settleQueuedTurns(
+    subagentId: string,
+    timeoutMs: number = QUEUED_TURN_SETTLE_TIMEOUT_MS,
+  ): Promise<boolean> {
+    const managed = this.subagents.get(subagentId);
+    const conversation = managed?.conversation;
+    if (!managed || !conversation || managed.hadEnqueuedMessages !== true) {
+      return true;
+    }
+    const deadline = Date.now() + timeoutMs;
+    let idleObservations = 0;
+    for (;;) {
+      // A release during the wait (the TTL sweep, or a dispose) freezes
+      // everything a reader can see, so there is nothing left to wait for.
+      if (managed.conversation !== conversation) {
+        return true;
+      }
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        return false;
+      }
+      if (conversation.isProcessing()) {
+        idleObservations = 0;
+        await conversation.waitForIdle({ timeoutMs: remainingMs });
+        continue;
+      }
+      if (conversation.hasQueuedMessages()) {
+        idleObservations = 0;
+        await sleep(Math.min(QUEUED_TURN_POLL_MS, remainingMs));
+        continue;
+      }
+      idleObservations += 1;
+      if (idleObservations >= 2) {
+        return true;
+      }
+      await sleep(Math.min(QUEUED_TURN_POLL_MS, remainingMs));
+    }
+  }
+
+  /**
+   * Re-read the child conversation's live counters into its state.
+   *
+   * Only ever updates a harvest that already happened: a run that never
+   * reached its harvest (aborted before the first turn, or still going) has
+   * nothing measured to report, and a zero taken mid-flight would read as
+   * "this subagent used no tools" rather than "not measured yet".
+   */
+  private refreshToolStats(managed: ManagedSubagent): void {
+    if (managed.conversation && managed.state.stats) {
+      managed.state.stats = snapshotToolStats(managed.conversation);
+    }
+  }
+
   getByLabel(
     label: string,
     parentConversationId: string,
@@ -1296,6 +1543,10 @@ export class SubagentManager {
     if (!managed.conversation) {
       return;
     }
+    // Last chance at the counters: on the deferred path this release happens
+    // after the queued follow-up turn drained, so this is the reading that
+    // includes it. Everything read after this point is this snapshot.
+    this.refreshToolStats(managed);
     const conversation = managed.conversation;
     removeSubagentConversation(conversation.conversationId, conversation);
     conversation.dispose();
@@ -1388,7 +1639,7 @@ export class SubagentManager {
         conversationId: state.conversationId,
         label: state.config.label,
         objective: state.config.objective,
-        role: state.config.role ?? "general",
+        role: state.config.role ?? DEFAULT_SUBAGENT_ROLE,
         isFork: state.isFork,
         sendResultToUser: state.config.sendResultToUser ?? null,
         parentToolUseId: state.config.parentToolUseId ?? null,
@@ -1454,6 +1705,7 @@ export class SubagentManager {
         state,
         parentSendToClient: () => {},
         retainedUntil: now + TERMINAL_RETENTION_MS,
+        rehydrated: true,
       };
       this.subagents.set(rec.id, managed);
 
@@ -1609,6 +1861,10 @@ export class SubagentManager {
       ? config.sendResultToUser !== true
       : config.sendResultToUser === false;
 
+    // A queued follow-up turn means the snapshot we hold is stale; defer to a
+    // read pointer so the parent picks up the queued turn's output instead.
+    const deferred = managed.hadEnqueuedMessages === true;
+
     const message = buildSubagentTerminalMessage({
       label: config.label,
       subagentId: config.id,
@@ -1617,10 +1873,14 @@ export class SubagentManager {
       silent,
       finalText,
       error: managed.state.error,
-      // A queued follow-up turn means the snapshot we hold is stale; defer to a
-      // read pointer so the parent picks up the queued turn's output instead.
-      deferred: managed.hadEnqueuedMessages === true,
+      deferred,
       deniedTools,
+      // Same staleness applies to the counters, and worse: the queued turn has
+      // not run yet at this point, so any number quoted here would under-report
+      // it, permanently, in a message that is never rewritten. The deferred
+      // message sends the parent to `subagent_read`, whose footer re-reads the
+      // counters once the queued turn has actually landed.
+      ...(deferred ? {} : { stats: managed.state.stats }),
     });
 
     const notification: SubagentNotificationInfo = {

package/src/subagent/progress-events.ts

@@ -0,0 +1,35 @@
+/**
+ * Classify subagent events as evidence that a child run is still moving.
+ *
+ * A synchronous caller bounds its wait with an idle window, and the only thing
+ * that resets that window is a progress signal. Streamed tokens are the obvious
+ * one, but a subagent that calls a tool goes silent for the whole execution
+ * while producing no delta, so tool activity counts as well: the call being
+ * recognized, its input streaming in, its output streaming out, and its result
+ * landing. Without it, a healthy child reading a large file looks identical to
+ * a stalled one and is aborted before the model ever sees its tool result.
+ *
+ * Its own module so the classification can be unit-tested (and imported by a
+ * deadline test) without pulling in the manager and its Conversation graph.
+ */
+
+import type { AssistantEvent } from "../api/index.js";
+
+const PROGRESS_EVENT_TYPES: ReadonlySet<string> = new Set([
+  "assistant_text_delta",
+  "assistant_thinking_delta",
+  "tool_use_preview_start",
+  "tool_use_start",
+  "tool_input_delta",
+  "tool_output_chunk",
+  "tool_result",
+]);
+
+/**
+ * Whether an event is evidence of forward progress in a child run. Pure, and
+ * deliberately an allowlist: a lifecycle or status event says nothing about
+ * whether work is happening, so an unknown event type never extends a deadline.
+ */
+export function isSubagentProgressEvent(msg: AssistantEvent): boolean {
+  return PROGRESS_EVENT_TYPES.has(msg.type);
+}