@signalridge/pi-subagents 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.15.0
+### Minor Changes
+
+- a4dc1de: Enforce missing per-invocation safety budgets on resumed agents, including foreground/background calls, nested resumes, mentions, and reused managed threads. Share fresh/resumed turn, token, and tool-call enforcement and terminal outcome mapping; preserve configured grace and tool timeouts. Resume inherits the original invocation's turn budget when not overridden, respects authoritative frontmatter/default policy, validates explicit limits like spawn, and does not let zero erase a configured cap. Nested resumes resolve only their branch-local frontmatter through an in-process budget-policy capability; internal callers without it retain the admitted invocation budget rather than consulting the root registry. Authoritative frontmatter zero remains unlimited after a finite earlier invocation. A retained session's finite or unlimited policy survives later default changes; one manager-resolved cap drives enforcement and queued/running UI counters. Activity updates are invocation-owned and lifetime usage is counted only once.
+  
+  Dispose grouped notifications and pending batch/nudge timers synchronously at confirmed shutdown, retire invocation-owned foreground progress/spinner callbacks before any teardown await, fence captured delivery callbacks, and preserve managed lifecycle/usage receipts while cooperative child teardown completes. Refused/failed resume admissions retire their own UI callbacks, while admitted lifetimes own final cleanup; mention notifications are fenced after asynchronous admission. Vetoable navigation remains unchanged.
+  
+  Selective upstream parity references: tintinweb/pi-subagents `d7c9ec0b027b91c7ab9da0fa5f4ae203474a5bdf`, `ca93a5247e72e7053fcd10bea7125d6c4205f949` (unreleased after the 0.22 tag), and `83be963a969eb359af29cbbb4d4af2d01748bfb5` (released in 0.22). The integrated engine is not imported; managed protocol v4 and payloads are unchanged. Event-based budgets cannot forcibly terminate a provider or tool that ignores abort.
+
+### Patch Changes
+
+- a4dc1de: Distinguish expandable Workflow groups from individual agents with a dedicated `▸` type mark across all run outcomes. Remove the duplicate trailing blank row before the footer while preserving Fleet navigation, exact-owner conversation opening, and the existing Workflow detail UI.
+
 ## 1.14.0
 ### Minor Changes
 

package/README.md

@@ -55,6 +55,8 @@ Derived from [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents)
 
 The container-first FleetView and bounded drill-down patterns are independently adapted from tintinweb/pi-subagents at [`221df02323c6b6350ea8474579e0ee0f6cc84cea`](https://github.com/tintinweb/pi-subagents/tree/221df02323c6b6350ea8474579e0ee0f6cc84cea/src/ui) and [`fd8d81618d80ae83a3faf40cb87dae99cca33264`](https://github.com/tintinweb/pi-subagents/tree/fd8d81618d80ae83a3faf40cb87dae99cca33264/src/ui). Collision-only child-label discriminators are inspired by [nicobailon/pi-subagents `69673c7fbf3351e54a5b0786a7e9d9fff625a749`](https://github.com/nicobailon/pi-subagents/blob/69673c7fbf3351e54a5b0786a7e9d9fff625a749/src/tui/render-helpers.ts). The workflow engine and phase inspector remain owned by `pi-workflows`, not copied into this package. A separate optional, validated UI protocol supplies authoritative run names, statuses and observed phases and opens that owner's inspector. Without that peer, groups retain the observation-only child list. No workflow source imports, inferred DAG state or second queue/model policy are introduced. The managed protocol remains v4.
 
+Resume-budget and shutdown parity fixes selectively adapt upstream work at [`d7c9ec0`](https://github.com/tintinweb/pi-subagents/commit/d7c9ec0b027b91c7ab9da0fa5f4ae203474a5bdf), [`ca93a52`](https://github.com/tintinweb/pi-subagents/commit/ca93a5247e72e7053fcd10bea7125d6c4205f949) (unreleased after the 0.22 tag), and [`83be963`](https://github.com/tintinweb/pi-subagents/commit/83be963a969eb359af29cbbb4d4af2d01748bfb5) (released in 0.22). They retain this fork's manager-owned sessions, resource budgets, activity accounting, and protocol v4; the integrated upstream engine is not imported.
+
 The opt-in parent clarification broker is locally implemented. It uses the existing main session, not an upstream LLM arbitrator, cloned parent history, private UI automation, or an additional Agent per question. Permission gates remain human-owned.
 
 ## Lint policy
@@ -469,6 +471,10 @@ Instead of hard-aborting at the turn limit, agents get a graceful shutdown:
 2. Up to 5 grace turns to finish cleanly
 3. Hard abort only after the grace period
 
+Each resumed prompt gets its own counters, not an unlimited continuation or a deduction from prior turns. This applies to foreground/background resumes, nested children, mentions, and reused managed threads. Agent frontmatter remains authoritative; without a per-resume override, the original invocation's turn limit is inherited, falling back to configured defaults. Resume overrides use the same non-negative safe-integer validation as spawning; caller zero cannot disable an inherited/configured cap. An authoritative frontmatter zero remains unlimited, even after an earlier finite invocation. Nested resumes reload the same branch-local definitions as nested spawns, never the root registry; an internal resume without scoped policy retains its admitted invocation budget. A retained session's admitted turn policy, including unlimited, survives later project-default changes; the manager supplies that same effective cap to queued and running progress trackers. The existing token/tool-call caps and tool timeout also apply to resumed prompts. Budgets are event-based: an already-running provider/tool can overshoot within one event or ignore abort; these are not process-isolation guarantees.
+
+Confirmed shutdown retires grouped completion, batch-finalization, held-nudge timers, and invocation-owned foreground spinners before awaiting child teardown. Captured delivery callbacks cannot wake the main model or publish foreground progress afterward, even while a provider ignores abort. Refused or failed resume admissions retire their own UI callbacks; an admitted run owns cleanup until settlement. Mention continuations cannot publish notifications after their root/runtime retires. Managed lifecycle/usage receipts remain available during cooperative shutdown; vetoable navigation attempts do not dispose these resources.
+
 | Status | Meaning | UI treatment |
 |--------|---------|-------------|
 | `completed` | Finished naturally | `completed` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-subagents",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Signalridge's managed subagent runtime with workflow-owned orchestration RPC.",
   "author": "tintinweb and signalridge contributors",
   "license": "MIT",

package/src/agent-manager.ts

@@ -35,15 +35,19 @@ import {
 import {
   INTERNAL_AGENT_CONFIG_OVERRIDE,
   INTERNAL_PARENT_POLICY_SNAPSHOT,
+  INTERNAL_RESUME_BUDGET_POLICY,
   type InternalAgentConfigOverride,
   type ParentPolicySnapshot,
+  type ResumeBudgetPolicy,
 } from "./internal-run.js";
+import { resolveMaxTurns } from "./invocation-config.js";
 import { assignHandle, handleBase } from "./mention.js";
 import {
   assertParentModelRuntimeAvailable,
   parentModelSessionOptions,
 } from "./model-runtime-bridge.js";
 import type { ParentQuestionHandler } from "./parent-questions.js";
+import { selectResumeTurnPolicy } from "./run-budget-policy.js";
 import { shutdownAndDisposeSession } from "./session-lifecycle.js";
 import type { TierThinking } from "./settings.js";
 import type {
@@ -315,6 +319,21 @@ function snapshotCleanupFailure(
   });
 }
 
+/** Hard budgets take precedence over provider failure, then soft wrap-up. */
+function applyRunOutcome(
+  record: AgentRecord,
+  outcome: { aborted?: boolean; steered?: boolean; failure?: string },
+): void {
+  if (outcome.aborted) {
+    record.status = "aborted";
+  } else if (outcome.failure) {
+    record.status = "error";
+    record.error = outcome.failure;
+  } else {
+    record.status = outcome.steered ? "steered" : "completed";
+  }
+}
+
 interface SpawnArgs {
   pi: ExtensionAPI;
   ctx: ExtensionContext;
@@ -1021,10 +1040,27 @@ export type ManagedSpawnCallbacks = Pick<
   | "onCompaction"
   | "onSpawned"
 > & {
+  /** Reused thread's effective display budget, before queue admission. */
+  onResumeBudgetResolved?: (maxTurns: number | undefined) => void;
   /** Reused thread's actual run boundary, before native steering or prompt. */
   onResumeStarting?: (record: AgentRecord, startMessageIndex: number) => void;
 };
 
+export interface ResumeOptions {
+  readonly [INTERNAL_RESUME_BUDGET_POLICY]?: ResumeBudgetPolicy;
+  isBackground?: boolean;
+  maxTurns?: number;
+  onToolActivity?: (activity: ToolActivity) => void;
+  onTurnEnd?: (count: number) => void;
+  onTextDelta?: (delta: string, fullText: string) => void;
+  onAssistantUsage?: SpawnOptions["onAssistantUsage"];
+  onCompaction?: (info: CompactionInfo) => void;
+  /** Effective display cap, published synchronously before queue admission. */
+  onBudgetResolved?: (maxTurns: number | undefined) => void;
+  /** Called at actual admission, including a queued background resume. */
+  onStarted?: () => void;
+}
+
 interface ResumeTerminalSnapshot {
   status: AgentRecord["status"];
   startedAt: number;
@@ -1863,9 +1899,13 @@ export class AgentManager {
       // only filter excludes only explicit `false`, so undefined agents — which
       // have no inline surface — stay visible instead of vanishing.
       isBackground: options.isBackground,
-      invocation: options.invocation
-        ? cloneFrozenData(options.invocation)
-        : undefined,
+      invocation:
+        options.invocation || options.maxTurns !== undefined
+          ? cloneFrozenData({
+              ...options.invocation,
+              maxTurns: options.maxTurns ?? options.invocation?.maxTurns,
+            })
+          : undefined,
       depth: options.depth ?? 1,
       parentAgentId: options.parentAgentId,
       ...(ancestorAgentIds ? { ancestorAgentIds } : {}),
@@ -2176,9 +2216,13 @@ export class AgentManager {
         }
         void this.resume(threadedId, normalized.prompt, undefined, {
           isBackground: true,
+          maxTurns: policy.maxTurns,
+          onBudgetResolved: callbacks?.onResumeBudgetResolved,
           onStarted: () => {
             void Promise.resolve(callbacks?.onResumeStarting?.(record, record.session!.messages.length)).catch(() => {});
           },
+          onTurnEnd: callbacks?.onTurnEnd,
+          onTextDelta: callbacks?.onTextDelta,
           onToolActivity: callbacks?.onToolActivity,
           onAssistantUsage: callbacks?.onAssistantUsage,
           onCompaction: callbacks?.onCompaction
@@ -2560,14 +2604,7 @@ export class AgentManager {
           // Precedence: a hard abort keeps "aborted"; then a failed final turn
           // (provider error that pi resolved instead of rejecting, #144) is an
           // honest "error" — not a completion with an empty or stale result.
-          if (aborted) {
-            record.status = "aborted";
-          } else if (failure) {
-            record.status = "error";
-            record.error = failure;
-          } else {
-            record.status = steered ? "steered" : "completed";
-          }
+          applyRunOutcome(record, { aborted, steered, failure });
         }
         record.completedAt ??= Date.now();
         detach();
@@ -3094,21 +3131,7 @@ export class AgentManager {
     id: string,
     prompt: string,
     signal?: AbortSignal,
-    options?: {
-      isBackground?: boolean;
-      onToolActivity?: (activity: {
-        type: "start" | "end";
-        toolName: string;
-      }) => void;
-      onAssistantUsage?: (usage: {
-        input: number;
-        output: number;
-        cacheWrite: number;
-      }) => void;
-      onCompaction?: (info: unknown) => void;
-      /** Called once a queued background resume has acquired its run slot. */
-      onStarted?: () => void;
-    },
+    options?: ResumeOptions,
   ): Promise<AgentRecord | undefined> {
     if (this.disposed) return undefined;
     const record = this.agents.get(id);
@@ -3124,6 +3147,28 @@ export class AgentManager {
       record.invocation?.inheritContext === true,
     );
 
+    if (
+      options?.maxTurns !== undefined &&
+      (!Number.isSafeInteger(options.maxTurns) || options.maxTurns < 0)
+    ) {
+      throw new Error("maxTurns must be a non-negative safe integer");
+    }
+    // Nested definitions belong to their branch, never the global root registry.
+    // Without the scoped tool's capability, retain the admitted invocation policy.
+    const policy = record.parentAgentId === undefined
+      ? getAgentConfig(record.type)
+      : options?.[INTERNAL_RESUME_BUDGET_POLICY] ?? record.invocation;
+    const maxTurns = selectResumeTurnPolicy(record.session, resolveMaxTurns(
+      policy,
+      // A caller's zero cannot erase the original/configured safety policy.
+      options?.maxTurns || record.invocation?.maxTurns,
+    ));
+    try {
+      options?.onBudgetResolved?.(maxTurns === 0 ? undefined : maxTurns);
+    } catch {
+      // UI observers cannot alter the authoritative policy or admission.
+    }
+    options = { ...options, maxTurns };
     const snapshot = this.resumeSnapshot(record);
     if (options?.isBackground) {
       // A background resume is one lifecycle, including time spent queued. Keep
@@ -3177,18 +3222,31 @@ export class AgentManager {
     record.result = undefined;
     record.error = undefined;
     try {
-      const { text, failure } = await resumeAgent(record.session, prompt, {
+      options.onStarted?.();
+      const { text, failure, aborted, steered } = await resumeAgent(record.session, prompt, {
+        maxTurns,
+        onTurnEnd: (count) => {
+          if (!record.detached) options.onTurnEnd?.(count);
+        },
+        onTextDelta: (delta, text) => {
+          if (!record.detached) options.onTextDelta?.(delta, text);
+        },
         onToolActivity: (activity) => {
-          if (!record.detached && activity.type === "end") record.toolUses++;
+          if (record.detached) return;
+          if (activity.type === "end") record.toolUses++;
+          options.onToolActivity?.(activity);
         },
         onAssistantUsage: (usage) => {
-          if (!record.detached) addUsage(record.lifetimeUsage, usage);
+          if (record.detached) return;
+          addUsage(record.lifetimeUsage, usage);
+          options.onAssistantUsage?.(usage);
         },
         onCompaction: (info) => {
           if (record.detached) return;
           record.compactionCount++;
           this.syncManagedRecord(record);
           this.onCompact?.(record, info);
+          options.onCompaction?.(info);
         },
         signal: control.controller.signal,
       });
@@ -3197,8 +3255,7 @@ export class AgentManager {
         !control.controller.signal.aborted &&
         (record.status as AgentRecord["status"]) !== "stopped"
       ) {
-        record.status = failure ? "error" : "completed";
-        if (failure) record.error = failure;
+        applyRunOutcome(record, { aborted, steered, failure });
         record.result = text;
         record.completedAt = Date.now();
       }
@@ -3242,21 +3299,7 @@ export class AgentManager {
     record: AgentRecord,
     prompt: string,
     control: ResumeControl,
-    options?: {
-      isBackground?: boolean;
-      onToolActivity?: (activity: {
-        type: "start" | "end";
-        toolName: string;
-      }) => void;
-      onAssistantUsage?: (usage: {
-        input: number;
-        output: number;
-        cacheWrite: number;
-      }) => void;
-      onCompaction?: (info: unknown) => void;
-      /** Called once a queued background resume has acquired its run slot. */
-      onStarted?: () => void;
-    },
+    options?: ResumeOptions,
   ): Promise<string> {
     const snapshot = control.snapshot;
     let slotHeld = false;
@@ -3305,13 +3348,22 @@ export class AgentManager {
       }
 
       try {
-        const { text, failure } = await resumeAgent(record.session!, prompt, {
+        const { text, failure, aborted, steered } = await resumeAgent(record.session!, prompt, {
+          maxTurns: options?.maxTurns,
+          onTurnEnd: (count) => {
+            if (!record.detached) options?.onTurnEnd?.(count);
+          },
+          onTextDelta: (delta, text) => {
+            if (!record.detached) options?.onTextDelta?.(delta, text);
+          },
           onToolActivity: (activity) => {
-            if (!record.detached && activity.type === "end") record.toolUses++;
+            if (record.detached) return;
+            if (activity.type === "end") record.toolUses++;
             options?.onToolActivity?.(activity);
           },
           onAssistantUsage: (usage) => {
-            if (!record.detached) addUsage(record.lifetimeUsage, usage);
+            if (record.detached) return;
+            addUsage(record.lifetimeUsage, usage);
             options?.onAssistantUsage?.(usage);
           },
           onCompaction: (info) => {
@@ -3328,8 +3380,7 @@ export class AgentManager {
           !control.controller.signal.aborted &&
           (record.status as AgentRecord["status"]) !== "stopped"
         ) {
-          record.status = failure ? "error" : "completed";
-          if (failure) record.error = failure;
+          applyRunOutcome(record, { aborted, steered, failure });
           record.result = text;
           record.completedAt = Date.now();
         }

package/src/agent-runner.ts

@@ -48,6 +48,7 @@ import { ANSWER_SUBAGENT_QUESTION, type ParentQuestionHandler } from "./parent-q
 import { captureProjectTrust, childProjectTrust, configurationMcpFactory, isProjectResource } from "./project-trust.js";
 import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
 import { captureQuestionOrigin } from "./question-origin.js";
+import { getDefaultTurnPolicy, type RunBudgets, selectResumeTurnPolicy, sessionBudgets, setDefaultTurnPolicy } from "./run-budget-policy.js";
 import { shutdownAndDisposeSession } from "./session-lifecycle.js";
 import { preloadSkills } from "./skill-loader.js";
 import { createSupervisorTool } from "./supervisor.js";
@@ -353,9 +354,6 @@ async function runConfiguredGate(command: string, cwd: string, pi: ExtensionAPI)
   }
 }
 
-/** Default max turns. undefined = unlimited (no turn limit). */
-let defaultMaxTurns: number | undefined;
-
 /** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
 export function normalizeMaxTurns(n: number | undefined): number | undefined {
   if (n == null || n === 0) return undefined;
@@ -363,9 +361,9 @@ export function normalizeMaxTurns(n: number | undefined): number | undefined {
 }
 
 /** Get the default max turns value. undefined = unlimited. */
-export function getDefaultMaxTurns(): number | undefined { return defaultMaxTurns; }
+export function getDefaultMaxTurns(): number | undefined { return getDefaultTurnPolicy(); }
 /** Set the default max turns value. undefined or 0 = unlimited, otherwise minimum 1. */
-export function setDefaultMaxTurns(n: number | undefined): void { defaultMaxTurns = normalizeMaxTurns(n); }
+export function setDefaultMaxTurns(n: number | undefined): void { setDefaultTurnPolicy(normalizeMaxTurns(n)); }
 
 /** Additional turns allowed after the soft limit steer message. */
 /**
@@ -1810,85 +1808,23 @@ export async function runAgent(
     options.onSessionCreated(session);
   }
 
-  // Track turns for graceful max_turns enforcement
-  let turnCount = 0;
-  const maxTurns = normalizeMaxTurns(options.maxTurns ?? agentConfig?.maxTurns ?? defaultMaxTurns);
-  let softLimitReached = false;
-  let aborted = false;
-
-  // Resource budgets, in the same shape as max_turns: a wrap-up steer at the
-  // soft threshold, an abort at the hard one. They bound what a single agent
-  // can spend on its own, which turn count does not — one turn can burn an
-  // arbitrary number of tokens or tool calls.
-  //
-  // `0` means unlimited here, matching this package's existing convention for
-  // `maxTurns`. That is the opposite of `maxSubagentSpawnsPerBranch`, and
-  // deliberately: these are opt-in resource caps that ship off, while the
-  // branch spawn budget is a safety valve that ships on.
-  const tokenBudget = normalizeMaxTurns(agentConfig?.maxTokens ?? defaultMaxTokens);
-  const toolCallBudget = normalizeMaxTurns(agentConfig?.maxToolCalls ?? defaultMaxToolCalls);
-  let budgetTokens = 0;
-  let budgetToolCalls = 0;
-  let tokenSoftReached = false;
-  let toolSoftReached = false;
-
-  /**
-   * Apply one budget, returning the next soft-limit state.
-   *
-   * The soft threshold is `SOFT_BUDGET_FRACTION` of the budget so the agent has
-   * room left to actually write its answer after being told to wrap up — a
-   * steer sent at 100% would be asking for a final response with no allowance
-   * to produce it.
-   */
-  const applyBudget = (used: number, budget: number | undefined, softReached: boolean, label: string): boolean => {
-    if (budget == null) return softReached;
-    // The hard limit is checked FIRST. One message can consume more than the
-    // whole budget, and testing the soft threshold first would answer that with
-    // a wrap-up steer and no abort — leaving an agent already over budget to
-    // run on until its next event.
-    if (used >= budget) {
-      aborted = true;
-      session.abort();
-      return true;
-    }
-    if (!softReached && used >= budget * SOFT_BUDGET_FRACTION) {
-      session.steer(
-        `You are near your ${label} budget for this task. Wrap up immediately — provide your final answer now.`,
-      );
-      return true;
-    }
-    return softReached;
+  const limits = {
+    maxTurns: options.maxTurns ?? agentConfig?.maxTurns ?? getDefaultMaxTurns(),
+    maxTokens: normalizeMaxTurns(agentConfig?.maxTokens ?? defaultMaxTokens),
+    maxToolCalls: normalizeMaxTurns(agentConfig?.maxToolCalls ?? defaultMaxToolCalls),
   };
+  sessionBudgets.set(session, limits);
+  const budget = createRunBudget(session, limits, options.onTurnEnd);
 
   let currentMessageText = "";
-  // Per-tool timeout: a hung bash/MCP call must not stall the subagent forever.
-  // Each tool_execution_start arms a timer; the matching end clears it. On
-  // timeout the session is aborted — which propagates via the tool's
-  // AbortSignal into the hanging execute() and surfaces as an error result.
-  // `contact_supervisor` is excluded: it intentionally waits for a human.
   const toolTimeouts = createToolTimeouts(session, noExtensions ? 0 : TOOL_CALL_ABORT_GRACE_MS, approvalTimer.isInteractiveAsk);
   approvalTimer.armApproved = toolTimeouts.armApproved;
   approvalTimer.pauseHuman = toolTimeouts.pauseHuman;
-  // Own finalized output before observer dispatch: a synchronous callback
-  // failure must remain visible without erasing the answer it interrupted.
+  // Own finalized output before dispatching observers that may throw.
   const collector = collectResponseText(session);
   const unsubTurns = session.subscribe((event: AgentSessionEvent) => {
-    if (event.type === "turn_end") {
-      turnCount++;
-      options.onTurnEnd?.(turnCount);
-      if (maxTurns != null) {
-        if (!softLimitReached && turnCount >= maxTurns) {
-          softLimitReached = true;
-          session.steer("You have reached your turn limit. Wrap up immediately — provide your final answer now.");
-        } else if (softLimitReached && turnCount >= maxTurns + graceTurns) {
-          aborted = true;
-          session.abort();
-        }
-      }
-    }
-    if (event.type === "message_start") {
-      currentMessageText = "";
-    }
+    budget.onEvent(event);
+    if (event.type === "message_start") currentMessageText = "";
     if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
       currentMessageText += event.assistantMessageEvent.delta;
       options.onTextDelta?.(event.assistantMessageEvent.delta, currentMessageText);
@@ -1900,22 +1836,14 @@ export async function runAgent(
     if (event.type === "tool_execution_end") {
       toolTimeouts.end(event);
       options.onToolActivity?.({ type: "end", toolName: event.toolName });
-      budgetToolCalls++;
-      toolSoftReached = applyBudget(budgetToolCalls, toolCallBudget, toolSoftReached, "tool call");
     }
     if (event.type === "message_end" && event.message.role === "assistant") {
-      const u = (event.message as any).usage;
+      const u = event.message.usage;
       if (u) options.onAssistantUsage?.({
         input: u.input ?? 0,
         output: u.output ?? 0,
         cacheWrite: u.cacheWrite ?? 0,
       });
-      if (u) {
-        // Same total as `getLifetimeTotal`: input + output + cacheWrite, with
-        // cacheRead deliberately excluded.
-        budgetTokens += (u.input ?? 0) + (u.output ?? 0) + (u.cacheWrite ?? 0);
-        tokenSoftReached = applyBudget(budgetTokens, tokenBudget, tokenSoftReached, "token");
-      }
     }
     if (event.type === "compaction_end" && !event.aborted && event.result) {
       options.onCompaction?.({ reason: event.reason, tokensBefore: event.result.tokensBefore });
@@ -1934,20 +1862,16 @@ export async function runAgent(
   }
 
   const baseText = collector.getText();
-  // The acceptance gate runs AFTER the agent is done and its verdict is
-  // appended to the result, so the parent reads the check and the claim it is
-  // checking side by side. It deliberately does not steer the agent to fix
-  // what failed: the gate is evidence for the caller, not another turn.
+  // Acceptance gates report evidence after the run, never spend another turn.
   const responseText = agentConfig?.gate
     ? `${baseText}${await runConfiguredGate(agentConfig.gate, effectiveCwd, options.pi)}`
     : baseText;
   completed = true;
-  return { responseText, session, aborted, steered: softLimitReached, failure: collector.getFailure() };
+  return { responseText, session, ...budget.outcome(), failure: collector.getFailure() };
   } finally {
     cleanupAbort();
-    // The manager takes ownership only after onSessionCreated is invoked. If
-    // setup or the first prompt fails before that hand-off, this runner owns
-    // the session and must close it instead of leaving a live session behind.
+    // Until onSessionCreated hands ownership to the manager, the runner must
+    // close a session whose setup/prompt failed.
     if (!handedOff && !completed) {
       try {
         if (!options.signal?.aborted) await session.abort();
@@ -1958,6 +1882,86 @@ export async function runAgent(
   }
 }
 
+/** One invocation's soft/hard budgets, shared by fresh and resumed prompts. */
+function createRunBudget(session: AgentSession, limits: RunBudgets, onTurnEnd?: (count: number) => void) {
+  let turnCount = 0;
+  const maxTurns = normalizeMaxTurns(limits.maxTurns);
+  let softLimitReached = false;
+  let aborted = false;
+
+  // Resource budgets, in the same shape as max_turns: a wrap-up steer at the
+  // soft threshold, an abort at the hard one. They bound what a single agent
+  // can spend on its own, which turn count does not — one turn can burn an
+  // arbitrary number of tokens or tool calls.
+  //
+  // `0` means unlimited here, matching this package's existing convention for
+  // `maxTurns`. That is the opposite of `maxSubagentSpawnsPerBranch`, and
+  // deliberately: these are opt-in resource caps that ship off, while the
+  // branch spawn budget is a safety valve that ships on.
+  const tokenBudget = limits.maxTokens;
+  const toolCallBudget = limits.maxToolCalls;
+  let budgetTokens = 0;
+  let budgetToolCalls = 0;
+  let tokenSoftReached = false;
+  let toolSoftReached = false;
+
+  /**
+   * Apply one budget, returning the next soft-limit state.
+   *
+   * The soft threshold is `SOFT_BUDGET_FRACTION` of the budget so the agent has
+   * room left to actually write its answer after being told to wrap up — a
+   * steer sent at 100% would be asking for a final response with no allowance
+   * to produce it.
+   */
+  const applyBudget = (used: number, budget: number | undefined, softReached: boolean, label: string): boolean => {
+    if (budget == null) return softReached;
+    // The hard limit is checked FIRST. One message can consume more than the
+    // whole budget, and testing the soft threshold first would answer that with
+    // a wrap-up steer and no abort — leaving an agent already over budget to
+    // run on until its next event.
+    if (used >= budget) {
+      aborted = true;
+      session.abort();
+      return true;
+    }
+    if (!softReached && used >= budget * SOFT_BUDGET_FRACTION) {
+      session.steer(
+        `You are near your ${label} budget for this task. Wrap up immediately — provide your final answer now.`,
+      );
+      return true;
+    }
+    return softReached;
+  };
+
+  return {
+    outcome: () => ({ aborted, steered: softLimitReached }),
+    onEvent: (event: AgentSessionEvent): void => {
+      if (event.type === "turn_end") {
+        turnCount++;
+        if (maxTurns != null) {
+          if (!softLimitReached && turnCount >= maxTurns) {
+            softLimitReached = true;
+            session.steer("You have reached your turn limit. Wrap up immediately — provide your final answer now.");
+          } else if (softLimitReached && turnCount >= maxTurns + graceTurns) {
+            aborted = true;
+            session.abort();
+          }
+        }
+        onTurnEnd?.(turnCount);
+      }
+      if (event.type === "tool_execution_end") {
+        budgetToolCalls++;
+        toolSoftReached = applyBudget(budgetToolCalls, toolCallBudget, toolSoftReached, "tool call");
+      }
+      if (event.type === "message_end" && event.message.role === "assistant" && event.message.usage) {
+        const u = event.message.usage;
+        budgetTokens += (u.input ?? 0) + (u.output ?? 0) + (u.cacheWrite ?? 0);
+        tokenSoftReached = applyBudget(budgetTokens, tokenBudget, tokenSoftReached, "token");
+      }
+    },
+  };
+}
+
 /**
  * Send a new prompt to an existing session (resume).
  */
@@ -1965,34 +1969,48 @@ export async function resumeAgent(
   session: AgentSession,
   prompt: string,
   options: {
+    maxTurns?: number;
+    onTurnEnd?: (count: number) => void;
+    onTextDelta?: (delta: string, fullText: string) => void;
     onToolActivity?: (activity: ToolActivity) => void;
     onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
     onCompaction?: (info: { reason: "manual" | "threshold" | "overflow"; tokensBefore: number }) => void;
     signal?: AbortSignal;
   } = {},
-): Promise<{ text: string; failure?: string }> {
+): Promise<{ text: string; failure?: string; aborted: boolean; steered: boolean }> {
   throwIfAborted(options.signal);
   assertSafeChildSession(session);
   const collector = collectResponseText(session);
   const cleanupAbort = forwardAbortSignal(session, options.signal);
 
-  const unsubEvents = (options.onToolActivity || options.onAssistantUsage || options.onCompaction)
-    ? session.subscribe((event: AgentSessionEvent) => {
-        if (event.type === "tool_execution_start") options.onToolActivity?.({ type: "start", toolName: event.toolName });
-        if (event.type === "tool_execution_end") options.onToolActivity?.({ type: "end", toolName: event.toolName });
-        if (event.type === "message_end" && event.message.role === "assistant") {
-          const u = (event.message as any).usage;
-          if (u) options.onAssistantUsage?.({
-            input: u.input ?? 0,
-            output: u.output ?? 0,
-            cacheWrite: u.cacheWrite ?? 0,
-          });
-        }
-        if (event.type === "compaction_end" && !event.aborted && event.result) {
-          options.onCompaction?.({ reason: event.reason, tokensBefore: event.result.tokensBefore });
-        }
-      })
-    : () => {};
+  const inherited = sessionBudgets.get(session);
+  const budget = createRunBudget(session, {
+    maxTurns: selectResumeTurnPolicy(session, options.maxTurns),
+    maxTokens: inherited ? inherited.maxTokens : normalizeMaxTurns(defaultMaxTokens),
+    maxToolCalls: inherited ? inherited.maxToolCalls : normalizeMaxTurns(defaultMaxToolCalls),
+  }, options.onTurnEnd);
+  let currentMessageText = "";
+  const unsubEvents = session.subscribe((event: AgentSessionEvent) => {
+    budget.onEvent(event);
+    if (event.type === "message_start") currentMessageText = "";
+    if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+      currentMessageText += event.assistantMessageEvent.delta;
+      options.onTextDelta?.(event.assistantMessageEvent.delta, currentMessageText);
+    }
+    if (event.type === "tool_execution_start") options.onToolActivity?.({ type: "start", toolName: event.toolName });
+    if (event.type === "tool_execution_end") options.onToolActivity?.({ type: "end", toolName: event.toolName });
+    if (event.type === "message_end" && event.message.role === "assistant") {
+      const u = event.message.usage;
+      if (u) options.onAssistantUsage?.({
+        input: u.input ?? 0,
+        output: u.output ?? 0,
+        cacheWrite: u.cacheWrite ?? 0,
+      });
+    }
+    if (event.type === "compaction_end" && !event.aborted && event.result) {
+      options.onCompaction?.({ reason: event.reason, tokensBefore: event.result.tokensBefore });
+    }
+  });
   // The child policy and its consent gate survive resumed turns. Replace the
   // original prompt's timer callback so a delayed approval cannot arm a stale
   // timer that the first prompt no longer clears.
@@ -2025,6 +2043,7 @@ export async function resumeAgent(
 
   return {
     text: collector.getText(),
+    ...budget.outcome(),
     failure: collector.getFailure(),
   };
 }

package/src/index.ts

@@ -64,6 +64,7 @@ import {
   type ManagedSpawnRequest,
   type ManagedSpawnResult,
   type ManagedSpawnTombstone,
+  type SpawnOptions,
 } from "./agent-manager.js";
 import {
   getAgentConversation,
@@ -327,7 +328,7 @@ function snapshotOwner(owner: AgentOwner | undefined): AgentOwner | undefined {
  * Create an AgentActivity state and spawn callbacks for tracking tool usage.
  * Used by both foreground and background paths to avoid duplication.
  */
-function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
+function buildActivityTracker(maxTurns: number | undefined, onStreamUpdate: (() => void) | undefined, isCurrent: () => boolean) {
   const state: AgentActivity = {
     activeTools: new Map(),
     toolUses: 0,
@@ -340,6 +341,7 @@ function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
 
   const callbacks = {
     onToolActivity: (activity: { type: "start" | "end"; toolName: string }) => {
+      if (!isCurrent()) return;
       if (activity.type === "start") {
         state.activeTools.set(
           activity.toolName + "_" + Date.now(),
@@ -357,14 +359,17 @@ function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
       onStreamUpdate?.();
     },
     onTextDelta: (_delta: string, fullText: string) => {
+      if (!isCurrent()) return;
       state.responseText = fullText;
       onStreamUpdate?.();
     },
     onTurnEnd: (turnCount: number) => {
+      if (!isCurrent()) return;
       state.turnCount = turnCount;
       onStreamUpdate?.();
     },
     onSessionCreated: (session: any) => {
+      if (!isCurrent()) return;
       state.session = session;
     },
     onAssistantUsage: (usage: {
@@ -372,6 +377,7 @@ function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
       output: number;
       cacheWrite: number;
     }) => {
+      if (!isCurrent()) return;
       addUsage(state.lifetimeUsage, usage);
       onStreamUpdate?.();
     },
@@ -695,17 +701,52 @@ function activateRootRuntime(
   // Holds notifications briefly so get_subagent_result can cancel them
   // before they reach pi.sendMessage (fire-and-forget).
   const pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
+  let notificationsRetired = false;
+  const invocationUiRetirements = new Set<() => void>();
+  const activityRetirements = new WeakMap<AgentActivity, () => void>();
+
+  function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
+    let retired = notificationsRetired;
+    const timers = new Set<ReturnType<typeof setInterval>>();
+    const isCurrent = () => !retired && !notificationsRetired;
+    const retire = () => {
+      retired = true;
+      for (const timer of timers) clearInterval(timer);
+      timers.clear();
+      invocationUiRetirements.delete(retire);
+    };
+    const tracker = buildActivityTracker(maxTurns, () => {
+      if (isCurrent()) onStreamUpdate?.();
+    }, isCurrent);
+    if (!retired) invocationUiRetirements.add(retire);
+    activityRetirements.set(tracker.state, retire);
+    return {
+      ...tracker,
+      isCurrent,
+      retire,
+      onBudgetResolved: (maxTurns: number | undefined) => {
+        if (isCurrent()) tracker.state.maxTurns = maxTurns;
+      },
+      ownTimer: (timer: ReturnType<typeof setInterval>) => {
+        if (isCurrent()) timers.add(timer);
+        else clearInterval(timer);
+      },
+    };
+  }
+
   const NUDGE_HOLD_MS = 200;
   // A queued result wait must observe completion before its held notification
   // can fire, so successful waits can still suppress that redundant nudge.
   const QUEUE_WAIT_POLL_MS = Math.floor(NUDGE_HOLD_MS / 4);
 
   function scheduleNudge(key: string, send: () => void, delay = NUDGE_HOLD_MS) {
+    if (notificationsRetired) return;
     cancelNudge(key);
     pendingNudges.set(
       key,
       setTimeout(() => {
         pendingNudges.delete(key);
+        if (notificationsRetired) return;
         try {
           send();
         } catch {
@@ -725,7 +766,7 @@ function activateRootRuntime(
 
   // ---- Individual nudge helper (async join mode) ----
   function emitIndividualNudge(record: AgentRecord) {
-    if (record.resultConsumed) return; // re-check at send time
+    if (notificationsRetired || record.resultConsumed) return; // re-check at send time
 
     const notification = formatTaskNotification(record, 500);
     const footer = record.outputFile
@@ -755,6 +796,7 @@ function activateRootRuntime(
 
   // ---- Group join manager ----
   const groupJoin = new GroupJoinManager((records, partial) => {
+    if (notificationsRetired) return;
     for (const r of records) {
       agentActivity.delete(r.id);
       fleet.onAgentFinished(r.id);
@@ -951,6 +993,8 @@ function activateRootRuntime(
   const manager = new AgentManager(
     (record) => {
       if (!record.detached) recordSessionUsage(record);
+      const activity = agentActivity.get(record.id);
+      if (activity) activityRetirements.get(activity)?.();
       // Nested children report only through their owning parent's scoped tools.
       // Keep them out of top-level lifecycle, transcript, notification, and UI channels.
       if (record.parentAgentId || record.detached) return;
@@ -999,6 +1043,10 @@ function activateRootRuntime(
         ...(record.owner ? { owner: snapshotOwner(record.owner) } : {}),
       });
 
+      // Shutdown still needs authoritative usage, lifecycle and persistence
+      // receipts above. Only UI/notification delivery is retired.
+      if (notificationsRetired) return;
+
       // Managed workflow agents are consumed by their owner through lifecycle
       // events. Suppress only their automatic main-session nudge/group message.
       if (record.owner) {
@@ -1489,6 +1537,17 @@ function activateRootRuntime(
   let runtimeShutdown: Promise<void> | undefined;
   const shutdownRuntime = (): Promise<void> => {
     runtimeShutdown ??= (async () => {
+      // Retire delivery synchronously, before any provider/workflow await.
+      // Cleared timers may already have a callback captured by the host.
+      notificationsRetired = true;
+      for (const retire of [...invocationUiRetirements]) retire();
+      groupJoin.dispose();
+      if (batchFinalizeTimer) clearTimeout(batchFinalizeTimer);
+      batchFinalizeTimer = undefined;
+      currentBatchAgents = [];
+      for (const timer of pendingNudges.values()) clearTimeout(timer);
+      pendingNudges.clear();
+      agentActivity.clear();
       // session_shutdown is confirmed, unlike either before-event. Start the
       // workflow's owned-agent cleanup while its RPC responder and the old leaf
       // are still available, regardless of which extension loads first.
@@ -1771,12 +1830,14 @@ function activateRootRuntime(
     // Allocate tracking only at a real fresh/reused-thread admission. An
     // idempotent request replay must not create another tracker at all.
     let tracker: ReturnType<typeof createActivityTracker> | undefined;
-    const tracking = () => tracker ??= createActivityTracker(undefined, () => fleet.update());
+    let resolvedResumeMaxTurns: number | undefined;
+    const tracking = () => tracker ??= createActivityTracker(resolvedResumeMaxTurns, () => fleet.update());
     const outputTranscript =
       getAgentConfig(dispatch.type)?.outputTranscript ??
       getOutputTranscriptDefault();
     let id = "";
     const initializeRecord = (spawnedId: string): void => {
+      if (notificationsRetired) return;
       id = spawnedId;
       agentActivity.set(id, tracking().state);
       const record = manager.getRecordMutable(id);
@@ -1802,7 +1863,12 @@ function activateRootRuntime(
       onTurnEnd: count => tracker?.callbacks.onTurnEnd(count),
       onAssistantUsage: usage => tracker?.callbacks.onAssistantUsage(usage),
       onSpawned: initializeRecord,
+      onResumeBudgetResolved: (maxTurns) => {
+        resolvedResumeMaxTurns = maxTurns;
+        tracker?.onBudgetResolved(maxTurns);
+      },
       onResumeStarting: (record: AgentRecord, startMessageIndex: number) => {
+        if (notificationsRetired) return;
         id = record.id;
         const { state } = tracking();
         state.session = record.session;
@@ -1820,6 +1886,7 @@ function activateRootRuntime(
         fleet.update();
       },
       onSessionCreated: (session: AgentSession) => {
+        if (notificationsRetired) return;
         tracking().callbacks.onSessionCreated(session);
         const record = manager.getRecordMutable(id);
         if (record?.outputFile) {
@@ -1832,6 +1899,7 @@ function activateRootRuntime(
         }
       },
       onCompaction: () => {
+        if (notificationsRetired) return;
         fleet.update();
       },
     };
@@ -1907,16 +1975,17 @@ function activateRootRuntime(
   ): string {
     const config = getAgentConfig(type);
     const resolved = resolveAgentInvocationConfig(config, {});
-    const { state, callbacks } = createActivityTracker(undefined, () => {
+    const tracker = createActivityTracker(undefined, () => {
       fleet.update();
     });
+    const { state, callbacks } = tracker;
     // Same sole gate as every other spawn path: `record.outputFile` being set is
     // what every downstream consumer keys off, so an agent whose frontmatter
     // says `output_transcript: false` must not gain one by being mentioned.
     const outputTranscript =
       config?.outputTranscript ?? getOutputTranscriptDefault();
     let id = "";
-    const spawnedId = manager.spawn(pi, ctxRef, type, prompt, {
+    const spawnOptions: SpawnOptions = {
       description: opts.description,
       maxTurns: normalizeMaxTurns(resolved.maxTurns ?? getDefaultMaxTurns()),
       isolated: resolved.isolated,
@@ -1939,6 +2008,7 @@ function activateRootRuntime(
       },
       ...callbacks,
       onSpawned: (newId) => {
+        if (notificationsRetired) return;
         id = newId;
         agentActivity.set(id, state);
         const record = manager.getRecordMutable(id);
@@ -1958,6 +2028,7 @@ function activateRootRuntime(
         fleet.update();
       },
       onSessionCreated: (session) => {
+        if (notificationsRetired) return;
         callbacks.onSessionCreated(session);
         const record = manager.getRecordMutable(id);
         if (record?.outputFile) {
@@ -1976,8 +2047,13 @@ function activateRootRuntime(
           );
         }
       },
-    });
-    return spawnedId;
+    };
+    try {
+      return manager.spawn(pi, ctxRef, type, prompt, spawnOptions);
+    } catch (error) {
+      tracker.retire();
+      throw error;
+    }
   }
 
   // ---- Join mode configuration ----
@@ -2038,6 +2114,7 @@ function activateRootRuntime(
 
   /** Finalize the current batch: if 2+ smart-mode agents, register as a group. */
   function finalizeBatch() {
+    if (notificationsRetired) return;
     batchFinalizeTimer = undefined;
     const batchAgents = [...currentBatchAgents];
     currentBatchAgents = [];
@@ -2240,24 +2317,53 @@ function activateRootRuntime(
       }
 
       if (record.session) {
+        const tracker = createActivityTracker(undefined, () => fleet.update());
+        const { state, callbacks } = tracker;
+        state.session = record.session;
+        const originCurrent = rootUiFence();
+        const session = record.session;
+        const owner = record.owner;
+        const canNotify = () => !notificationsRetired && originCurrent() &&
+          manager.getRecordMutable(record.id) === record && !record.detached &&
+          record.session === session && record.owner === owner;
+        let admitted = false;
         try {
           const resumed = await manager.resume(
             record.id,
             mention.message,
             undefined,
-            { isBackground: true },
+            {
+              isBackground: true,
+              ...callbacks,
+              onBudgetResolved: tracker.onBudgetResolved,
+              onStarted: () => {
+                if (tracker.isCurrent()) agentActivity.set(record.id, state);
+              },
+            },
           );
-          ctx.ui.notify(
+          admitted = resumed?.promise !== undefined;
+          if (resumed && tracker.isCurrent() && (resumed.status === "queued" || resumed.status === "running")) {
+            agentActivity.set(record.id, state);
+          }
+          void resumed?.promise?.finally(() => {
+            tracker.retire();
+            if (agentActivity.get(record.id) !== state) return;
+            agentActivity.delete(record.id);
+            fleet.onAgentFinished(record.id);
+          }).catch(() => {});
+          if (canNotify()) ctx.ui.notify(
             resumed
               ? `Resuming ${target}`
               : `Could not resume ${target} — it is still running.`,
             resumed ? "info" : "warning",
           );
         } catch (error) {
-          ctx.ui.notify(
+          if (canNotify()) ctx.ui.notify(
             `Could not resume ${target}: ${error instanceof Error ? error.message : String(error)}`,
             "warning",
           );
+        } finally {
+          if (!admitted) tracker.retire();
         }
         return { action: "handled" };
       }
@@ -3076,8 +3182,8 @@ Terse command-style prompts produce shallow, generic work.
         // the flag was accepted then silently dropped — a resumed agent always
         // blocked the caller until it finished.
         if (runInBackground) {
-          const { state: bgState, callbacks: bgCallbacks } =
-            createActivityTracker(effectiveMaxTurns);
+          const bgTracker = createActivityTracker(undefined, () => fleet.update());
+          const { state: bgState, callbacks: bgCallbacks } = bgTracker;
           // resumeAgent has no onSessionCreated — the session predates this run
           // — so seed the activity tracker directly.
           bgState.session = existing.session;
@@ -3097,6 +3203,8 @@ Terse command-style prompts produce shallow, generic work.
           // this index, so it is written exactly once.
           const transcriptAnchor = existing.session.messages.length ?? 0;
           const attachTranscript = (): void => {
+            if (!bgTracker.isCurrent()) return;
+            agentActivity.set(existing.id, bgState);
             if (!existing.outputFile || existing.outputCleanup) return;
             existing.outputCleanup = streamToOutputFile(
               existing.session!,
@@ -3106,25 +3214,38 @@ Terse command-style prompts produce shallow, generic work.
               transcriptAnchor,
             );
           };
-          const record = await manager.resume(
-            params.resume,
-            params.prompt,
-            undefined,
-            {
+          let record: AgentRecord | undefined;
+          let admitted = false;
+          try {
+            record = await manager.resume(params.resume, params.prompt, undefined, {
               isBackground: true,
+              maxTurns: params.max_turns,
+              onBudgetResolved: bgTracker.onBudgetResolved,
               onToolActivity: bgCallbacks.onToolActivity,
+              onTurnEnd: bgCallbacks.onTurnEnd,
+              onTextDelta: bgCallbacks.onTextDelta,
               onAssistantUsage: bgCallbacks.onAssistantUsage,
               onStarted: attachTranscript,
-            },
-          );
+            });
+            admitted = record?.promise !== undefined;
+          } finally {
+            if (!admitted) bgTracker.retire();
+          }
           if (!record) {
             return textResult(
               `Cannot resume agent "${params.resume}" in background — it is already running. ` +
                 "Wait for it to settle, or steer it with steer_subagent.",
             );
           }
-          agentActivity.set(params.resume, bgState);
-          void bgCallbacks;
+          if (bgTracker.isCurrent() && (record.status === "queued" || record.status === "running")) {
+            agentActivity.set(params.resume, bgState);
+          }
+          void record.promise?.finally(() => {
+            bgTracker.retire();
+            if (agentActivity.get(record.id) !== bgState) return;
+            agentActivity.delete(record.id);
+            fleet.onAgentFinished(record.id);
+          }).catch(() => {});
           return textResult(
             record.status === "queued"
               ? `Agent "${params.resume}" resumed in background (queued at the concurrency limit).`
@@ -3133,11 +3254,34 @@ Terse command-style prompts produce shallow, generic work.
           );
         }
 
-        const record = await manager.resume(
-          params.resume,
-          params.prompt,
-          signal,
-        );
+        const tracker = createActivityTracker(undefined, () => {
+          if (!tracker.isCurrent()) return;
+          fleet.update();
+          if (!tracker.isCurrent()) return;
+          onUpdate?.(textResult(
+            "Resuming agent...",
+            buildDetails(detailBase, existing, state),
+          ));
+        });
+        const { state, callbacks } = tracker;
+        state.session = existing.session;
+        let record: AgentRecord | undefined;
+        try {
+          record = await manager.resume(params.resume, params.prompt, signal, {
+            ...callbacks,
+            maxTurns: params.max_turns,
+            onBudgetResolved: tracker.onBudgetResolved,
+            onStarted: () => {
+              if (tracker.isCurrent()) agentActivity.set(existing.id, state);
+            },
+          });
+        } finally {
+          tracker.retire();
+          if (agentActivity.get(existing.id) === state) {
+            agentActivity.delete(existing.id);
+            fleet.onAgentFinished(existing.id);
+          }
+        }
         if (!record) {
           return textResult(`Failed to resume agent "${params.resume}".`);
         }
@@ -3146,19 +3290,21 @@ Terse command-style prompts produce shallow, generic work.
         if (record.status === "error") {
           return textResult(
             `Agent failed: ${record.error}${partialOutputSuffix(record)}`,
-            buildDetails(detailBase, record),
+            buildDetails(detailBase, record, state),
           );
         }
+        const output = record.result?.trim() || "No output.";
+        const outcome = getForegroundOutcomeNote(record.status);
         return textResult(
-          record.result?.trim() || "No output.",
-          buildDetails(detailBase, record),
+          outcome ? `${output}\n\n[pi-subagents outcome]${outcome}` : output,
+          buildDetails(detailBase, record, state),
         );
       }
 
       // Background execution
       if (runInBackground) {
-        const { state: bgState, callbacks: bgCallbacks } =
-          createActivityTracker(effectiveMaxTurns);
+        const bgTracker = createActivityTracker(effectiveMaxTurns);
+        const { state: bgState, callbacks: bgCallbacks } = bgTracker;
 
         // Wrap onSessionCreated to wire output file streaming.
         // The callback lazily reads record.outputFile (set right after spawn)
@@ -3166,6 +3312,7 @@ Terse command-style prompts produce shallow, generic work.
         let id: string;
         const origBgOnSession = bgCallbacks.onSessionCreated;
         bgCallbacks.onSessionCreated = (session: any) => {
+          if (notificationsRetired) return;
           origBgOnSession(session);
           const rec = manager.getRecordMutable(id);
           if (rec?.outputFile) {
@@ -3180,7 +3327,7 @@ Terse command-style prompts produce shallow, generic work.
 
         // A startup throw means the agent never started. Let pi mark the tool
         // call as failed instead of returning a successful-looking text result.
-        id = manager.spawn(pi, ctx, subagentType, params.prompt, {
+        const spawnOptions: SpawnOptions = {
           description: params.description,
           model: resolvedConfig.agentTierSelected ? undefined : model,
           maxTurns: effectiveMaxTurns,
@@ -3196,7 +3343,13 @@ Terse command-style prompts produce shallow, generic work.
           invocation: agentInvocation,
           rootSessionId: ctx.sessionManager.getSessionId(),
           ...bgCallbacks,
-        });
+        };
+        try {
+          id = manager.spawn(pi, ctx, subagentType, params.prompt, spawnOptions);
+        } catch (error) {
+          bgTracker.retire();
+          throw error;
+        }
         // The clone needs a positive spawn witness before any UI, transcript,
         // or event observer can throw. A startup failure inside manager.spawn
         // removes its record and does not reach this acknowledgement.
@@ -3275,8 +3428,9 @@ Terse command-style prompts produce shallow, generic work.
       let handedOff = false;
 
       const streamUpdate = () => {
+        if (!fgTracker.isCurrent()) return;
         fleet.update();
-        if (!foregroundUpdates) return;
+        if (!fgTracker.isCurrent() || !foregroundUpdates) return;
         const details: AgentDetails = {
           ...detailBase,
           toolUses: fgState.toolUses,
@@ -3294,16 +3448,15 @@ Terse command-style prompts produce shallow, generic work.
         });
       };
 
-      const { state: fgState, callbacks: fgCallbacks } = createActivityTracker(
-        effectiveMaxTurns,
-        streamUpdate,
-      );
+      const fgTracker = createActivityTracker(effectiveMaxTurns, streamUpdate);
+      const { state: fgState, callbacks: fgCallbacks } = fgTracker;
 
       // Wire session creation: register in the FleetView list + stream to the output file.
       // The output file path is set synchronously after spawn (below),
       // before onSessionCreated fires — same pattern as background agents.
       const origOnSession = fgCallbacks.onSessionCreated;
       fgCallbacks.onSessionCreated = (session: any) => {
+        if (!fgTracker.isCurrent()) return;
         origOnSession(session);
         for (const a of manager.listAgentsMutable()) {
           if (a.session === session) {
@@ -3329,9 +3482,11 @@ Terse command-style prompts produce shallow, generic work.
       };
 
       const spinnerInterval = setInterval(() => {
+        if (!fgTracker.isCurrent()) return;
         spinnerFrame++;
         streamUpdate();
       }, SPINNER_INTERVAL_MS);
+      fgTracker.ownTimer(spinnerInterval);
 
       streamUpdate();
 
@@ -3374,7 +3529,8 @@ Terse command-style prompts produce shallow, generic work.
         // A transfer ends this tool's spinner, not the child's activity or stream.
         foregroundUpdates = false;
         clearInterval(spinnerInterval);
-        if (fgId && !handedOff) {
+        if (!handedOff) fgTracker.retire();
+        if (fgId && !handedOff && !notificationsRetired) {
           agentActivity.delete(fgId);
           fleet.onAgentFinished(fgId);
         }

package/src/internal-run.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Api, Model } from "@earendil-works/pi-ai";
-import type { ThinkingLevel } from "./types.js";
+import type { AgentConfig, ThinkingLevel } from "./types.js";
 
 /**
  * Immutable policy used while asking a model to draft an agent definition.
@@ -39,6 +39,10 @@ export interface ParentPolicySnapshot {
 
 export const INTERNAL_PARENT_POLICY_SNAPSHOT = Symbol("pi-subagents.internal-parent-policy-snapshot");
 
+/** Branch-local frontmatter only; never accepts another run/config capability. */
+export type ResumeBudgetPolicy = Pick<AgentConfig, "maxTurns">;
+export const INTERNAL_RESUME_BUDGET_POLICY = Symbol("pi-subagents.internal-resume-budget-policy");
+
 /** The only no-tool policy currently issued by the package. */
 export const AGENT_DEFINITION_GENERATION_OVERRIDE: InternalAgentConfigOverride = Object.freeze({
   builtinToolNames: Object.freeze([] as string[]),

package/src/invocation-config.ts

@@ -27,6 +27,11 @@ interface AgentInvocationParams {
   isolation?: IsolationMode;
 }
 
+/** Frontmatter is authoritative, including its explicit unlimited value. */
+export function resolveMaxTurns(agentConfig: Pick<AgentConfig, "maxTurns"> | undefined, requested?: number): number | undefined {
+  return agentConfig?.maxTurns ?? requested;
+}
+
 export function resolveAgentInvocationConfig(
   agentConfig: AgentConfig | undefined,
   params: AgentInvocationParams,
@@ -62,7 +67,7 @@ export function resolveAgentInvocationConfig(
     thinking: agentTierSelected
       ? undefined
       : (agentConfig?.thinking ?? params.thinking) as ThinkingLevel | undefined,
-    maxTurns: agentConfig?.maxTurns ?? params.max_turns,
+    maxTurns: resolveMaxTurns(agentConfig, params.max_turns),
     inheritContext:
       agentConfig?.inheritContext ?? params.inherit_context ?? false,
     runInBackground:

package/src/nested-tools.ts

@@ -18,6 +18,7 @@ import {
 } from "./agent-types.js";
 import { INHERIT_CONTEXT_UNAVAILABLE } from "./context-boundary.js";
 import { loadCustomAgents } from "./custom-agents.js";
+import { INTERNAL_RESUME_BUDGET_POLICY, type ResumeBudgetPolicy } from "./internal-run.js";
 import { resolveAgentInvocationConfig } from "./invocation-config.js";
 import { resolveModel } from "./model-resolver.js";
 import { checkModelScope } from "./model-scope.js";
@@ -92,7 +93,7 @@ export interface NestedAgentManager {
   ): Promise<{ id: string; record: AgentRecord }>;
   /** Internal live lookup used only by the scoped manager runtime. */
   getRecordMutable(id: string): AgentRecord | undefined;
-  resume(id: string, prompt: string, signal?: AbortSignal): Promise<AgentRecord | undefined>;
+  resume(id: string, prompt: string, signal?: AbortSignal, options?: { maxTurns?: number; readonly [INTERNAL_RESUME_BUDGET_POLICY]?: ResumeBudgetPolicy }): Promise<AgentRecord | undefined>;
 }
 
 export interface NestedToolContext {
@@ -194,7 +195,11 @@ export function createNestedSubagentTools(context: NestedToolContext): ToolDefin
         if (signal?.aborted) {
           return textResult("Resume aborted.", true);
         }
-        const resumed = await context.manager.resume(params.resume, params.prompt, signal);
+        const config = getAgentConfigIn(loadRegistry(), existing.type);
+        const resumed = await context.manager.resume(params.resume, params.prompt, signal, {
+          maxTurns: params.max_turns,
+          [INTERNAL_RESUME_BUDGET_POLICY]: { maxTurns: config?.maxTurns },
+        });
         return resumed
           ? textResult(formatRecord(resumed, "inline"), resumed.status === "error")
           : textResult(`Failed to resume nested agent "${params.resume}".`, true);

package/src/run-budget-policy.ts

@@ -0,0 +1,22 @@
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+
+export interface RunBudgets {
+  maxTurns?: number;
+  maxTokens?: number;
+  maxToolCalls?: number;
+}
+
+// Session policy survives each prompt; counters and UI observers never do.
+export const sessionBudgets = new WeakMap<AgentSession, RunBudgets>();
+let defaultTurnPolicy: number | undefined;
+
+export function getDefaultTurnPolicy(): number | undefined { return defaultTurnPolicy; }
+export function setDefaultTurnPolicy(value: number | undefined): void { defaultTurnPolicy = value; }
+
+/** Raw zero preserves authoritative unlimited policy across settings changes. */
+export function selectResumeTurnPolicy(session: AgentSession, resolved?: number): number {
+  if (resolved !== undefined) return resolved;
+  const inherited = sessionBudgets.get(session);
+  if (inherited) return inherited.maxTurns ?? 0;
+  return defaultTurnPolicy ?? 0;
+}

package/src/ui/fleet-list.ts

@@ -556,7 +556,9 @@ export class FleetList {
           const color = status === "error" ? "error" : status === "stopped" ? "warning" : selected ? "accent" : "dim";
           const name = sanitizeDisplayText(run.name);
           const phase = run.currentPhase ? ` · ${sanitizeDisplayText(run.currentPhase)}` : "";
-          const left = `  ${theme.fg(color, getAgentStatusMark(status))} ${theme.fg(selected ? "accent" : "muted", name)} · ${theme.fg(color, run.status)}${phase} · ${run.runningCalls}/${run.callCount} running · ${run.completedCalls} done · ${run.failedCalls} failed${run.restored ? " · restored" : ""}`;
+          // A workflow is an expandable group, not another agent. Keep its
+          // type mark distinct at every outcome; color/text still report status.
+          const left = `  ${theme.fg(color, "▸")} ${theme.fg(selected ? "accent" : "muted", name)} · ${theme.fg(color, run.status)}${phase} · ${run.runningCalls}/${run.callCount} running · ${run.completedCalls} done · ${run.failedCalls} failed${run.restored ? " · restored" : ""}`;
           const right = `${formatFleetElapsed(run.elapsedMs)}${run.tokenCount === undefined ? "" : ` · ${formatFleetTokens(run.tokenCount)}`}`;
           lines.push(rightAlign(left, theme.fg("dim", right), width));
         } else {
@@ -567,7 +569,7 @@ export class FleetList {
     }
     if (hiddenBelow > 0) lines.push(rightAlign("", theme.fg("dim", `${hiddenBelow} more below`), width));
 
-    lines.push(""); // breathing room below the roster, including narrow terminals
+    // One separator belongs to Fleet; do not stack two empty rows before the footer.
     return [...lines.slice(0, height - 1), ""].map(line => truncateToWidth(line, Math.max(0, width)));
   }