@signalridge/pi-subagents 1.13.0 → 1.15.0

package/src/agent-runner.ts

@@ -21,6 +21,7 @@ import {
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
+import { type ApprovalEvents, captureApprovalService, queryApprovalAdapter, requiresApprovalAdapter, schemaRequiresApprovalAdapter } from "@signalridge/pi-approval-core";
 import { type AgentTierResolutionSnapshot, resolveAgentTier } from "./agent-tiers.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
 import { createAskGate } from "./ask-tools.js";
@@ -42,9 +43,12 @@ import { type ModelRegistry, resolveModel, shortModelLabel } from "./model-resol
 import { parentModelSessionOptions } from "./model-runtime-bridge.js";
 import { checkModelScope } from "./model-scope.js";
 import { createNestedSubagentTools, getMaxSubagentDepth, type NestedAgentManager } from "./nested-tools.js";
+import { createChildApprovalTools } from "./operation-approvals.js";
 import { ANSWER_SUBAGENT_QUESTION, type ParentQuestionHandler } from "./parent-questions.js";
 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";
@@ -350,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;
@@ -360,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. */
 /**
@@ -396,9 +397,11 @@ const TOOL_CALL_ABORT_GRACE_MS = 25;
 interface ApprovalTimer {
   isInteractiveAsk: (name: string) => boolean;
   armApproved: (toolCallId: string, toolName: string) => void;
+  pauseHuman: (toolCallId: string) => () => void;
 }
 // The policy survives runAgent for resumed turns; the current prompt owns its
-// abort timers, so resume replaces armApproved instead of arming a stale timer.
+// abort timers, so resume replaces both approval callbacks instead of using
+// a stale execution budget.
 const approvalTimers = new WeakMap<AgentSession, ApprovalTimer>();
 let defaultToolTimeoutMs = DEFAULT_TOOL_TIMEOUT_MS;
 export function getDefaultToolTimeoutMs(): number { return defaultToolTimeoutMs; }
@@ -427,7 +430,8 @@ export function withTimeout<T>(promise: Promise<T>, ms: number, label: string):
 function createToolTimeouts(session: AgentSession, grace: number, isInteractiveAsk: (name: string) => boolean) {
   const pending = new Map<string, ReturnType<typeof setTimeout>>();
   const due = new Map<string, number>();
-  const paused = new Map<string, { remaining: number; children: Set<string> }>();
+  const paused = new Map<string, { remaining: number; children: Set<string>; human: number }>();
+  let disposed = false;
   const clear = (id: string): void => {
     const handle = pending.get(id);
     if (handle) clearTimeout(handle);
@@ -436,7 +440,7 @@ function createToolTimeouts(session: AgentSession, grace: number, isInteractiveA
     paused.delete(id);
   };
   const arm = (id: string, name: string, delay = defaultToolTimeoutMs + grace): void => {
-    if (defaultToolTimeoutMs <= 0 || name === "contact_supervisor") return;
+    if (disposed || defaultToolTimeoutMs <= 0 || name === "contact_supervisor") return;
     due.set(id, performance.now() + delay);
     const handle = setTimeout(() => {
       pending.delete(id);
@@ -450,25 +454,42 @@ function createToolTimeouts(session: AgentSession, grace: number, isInteractiveA
     handle.unref?.();
     pending.set(id, handle);
   };
+  const pause = (id: string) => {
+    const existing = paused.get(id);
+    if (existing) return existing;
+    const handle = pending.get(id);
+    const deadline = due.get(id);
+    if (!handle || deadline === undefined) return undefined;
+    clearTimeout(handle);
+    pending.delete(id);
+    due.delete(id);
+    const state = { remaining: Math.max(0, deadline - performance.now()), children: new Set<string>(), human: 0 };
+    paused.set(id, state);
+    return state;
+  };
+  const resume = (id: string): void => {
+    const state = paused.get(id);
+    if (!state || state.children.size || state.human) return;
+    paused.delete(id);
+    arm(id, "", state.remaining);
+  };
   return {
     armApproved: (id: string, name: string): void => arm(id, name),
+    pauseHuman: (id: string): (() => void) => {
+      const state = pause(id);
+      if (!state) return () => {};
+      state.human++;
+      let finished = false;
+      return () => {
+        if (finished) return;
+        finished = true;
+        state.human--;
+        resume(id);
+      };
+    },
     start: (event: { toolCallId: string; toolName: string; parentToolCallId?: string }): void => {
       if (event.parentToolCallId) {
-        const parent = paused.get(event.parentToolCallId);
-        if (parent) parent.children.add(event.toolCallId);
-        else {
-          const handle = pending.get(event.parentToolCallId);
-          const deadline = due.get(event.parentToolCallId);
-          if (handle && deadline !== undefined) {
-            clearTimeout(handle);
-            pending.delete(event.parentToolCallId);
-            due.delete(event.parentToolCallId);
-            paused.set(event.parentToolCallId, {
-              remaining: Math.max(0, deadline - performance.now()),
-              children: new Set([event.toolCallId]),
-            });
-          }
-        }
+        pause(event.parentToolCallId)?.children.add(event.toolCallId);
       }
       if (!isInteractiveAsk(event.toolName)) arm(event.toolCallId, event.toolName);
     },
@@ -478,11 +499,10 @@ function createToolTimeouts(session: AgentSession, grace: number, isInteractiveA
       const parent = paused.get(event.parentToolCallId);
       if (!parent) return;
       parent.children.delete(event.toolCallId);
-      if (parent.children.size > 0) return;
-      paused.delete(event.parentToolCallId);
-      arm(event.parentToolCallId, "", parent.remaining);
+      resume(event.parentToolCallId);
     },
     dispose: (): void => {
+      disposed = true;
       for (const handle of pending.values()) clearTimeout(handle);
       pending.clear();
       due.clear();
@@ -844,9 +864,11 @@ function resolveConfiguredSessionDir(sessionDir: string | undefined, cwd: string
  * reads instead, leaving registration/unsubscription and all metadata intact.
  * Each read wraps the CURRENT callbacks before Pi takes its event snapshot.
  */
+type ToolCallAdmission = () => ToolCallEventResult | undefined;
 function guardExtensionToolCalls(
   extension: Extension,
   deadlines: WeakMap<object, number>,
+  admissions: WeakMap<object, ToolCallAdmission>,
 ): Extension {
   type Handler = NonNullable<ReturnType<Extension["handlers"]["get"]>>[number];
   const guarded = new WeakMap<Handler, Handler>();
@@ -864,18 +886,23 @@ function guardExtensionToolCalls(
                 return { block: true, reason: "Invalid subagent tool_call event." };
               }
               const deadline = deadlines.get(call);
-              if (deadline === undefined) {
+              const admission = admissions.get(call);
+              if (deadline === undefined || !admission) {
                 return { block: true, reason: "Subagent tool policy was bypassed." };
               }
-              if (deadline === Infinity) return handler(...args);
               const toolName = Reflect.get(call, "toolName");
               const label = `tool_call for "${typeof toolName === "string" ? toolName : "unknown"}"`;
               const remaining = Math.ceil(deadline - performance.now());
               if (remaining <= 0) return { block: true, reason: `${label} timed out before the extension handler.` };
               try {
-                // This race blocks the call; it cannot cancel side effects of
-                // a handler that keeps running after its Promise loses.
-                return await withTimeout(Promise.resolve().then(() => handler(...args)), remaining, label);
+                // This race cannot cancel side effects in a timed-out handler.
+                const result = deadline === Infinity ? await handler(...args)
+                  : await withTimeout(Promise.resolve().then(() => handler(...args)), remaining, label);
+                if (deadline <= performance.now()) return { block: true, reason: `${label} timed out` };
+                // Later handlers mutate the native args object. Check after EACH
+                // handler using the original execution name/schema, not its mutable
+                // event.toolName. This admission never invokes askGate again.
+                return admission() ?? result;
               } catch (error) {
                 // Pi does not catch tool_call handler failures. A timeout must
                 // block the tool, not leave a rejected event or an awaited hook.
@@ -908,6 +935,11 @@ export async function runAgent(
   // an already-cancelled caller. This matters for tool-call signals: the
   // caller may be cancelled before this async function gets its first turn.
   throwIfAborted(options.signal);
+  // Capture the ROOT peer synchronously, before discovery or resource allocation.
+  // Only absence is optional; malformed/duplicate peers must fail closed here.
+  const approvalCapture = options.pi.events ? captureApprovalService(options.pi.events) : undefined;
+  const approvalService = approvalCapture?.service;
+  const approvalRootOrigin = approvalService ? captureQuestionOrigin(ctx) : undefined;
   if (options.supervisorQuestions === "parent" && !options.parentQuestion) {
     throw new Error('Parent clarification requires a manager-issued background channel. Use Agent with run_in_background: true and supervisor_questions: "parent".');
   }
@@ -1144,11 +1176,15 @@ export async function runAgent(
   const approvalTimer: ApprovalTimer = {
     isInteractiveAsk: (name) => interactiveAskNames.has(name.toLowerCase()),
     armApproved: () => {},
+    pauseHuman: () => () => {},
   };
   // The policy starts a single monotonic deadline for each public tool_call
   // event. All subsequently selected extension handlers share its remainder,
   // including calls initiated by another tool through ctx.executeTool().
   const toolCallDeadlines = new WeakMap<object, number>();
+  const toolCallAdmissions = new WeakMap<object, ToolCallAdmission>();
+  let captureAdmission: (name: string, input: unknown) => ToolCallAdmission =
+    () => () => ({ block: true, reason: "Subagent tool policy is not ready." });
   const extensionsOverride = (base: LoadExtensionsResult): LoadExtensionsResult => {
     const policy = base.extensions.find((e) => e.path === `<inline:${TOOL_POLICY_EXTENSION}>`);
     if (!policy) throw new Error("Subagent tool policy extension failed to load.");
@@ -1171,7 +1207,7 @@ export async function runAgent(
     return {
       ...base,
       extensions: [policy, ...selected.filter((e) => e !== policy)
-        .map((extension) => guardExtensionToolCalls(extension, toolCallDeadlines))],
+        .map((extension) => guardExtensionToolCalls(extension, toolCallDeadlines, toolCallAdmissions))],
     };
   };
 
@@ -1179,12 +1215,14 @@ export async function runAgent(
   // ctx.executeTool calls. A policy factory also loads with noExtensions: true,
   // without loading any discovered extension. Deny until the child policy is
   // installed, including calls an extension might make during session_start.
-  let checkToolCall: (name: string, input: unknown, deadline: number) => Promise<ToolCallEventResult | undefined> =
+  let checkToolCall: (name: string, input: unknown, deadline: number, admission: ToolCallAdmission) => Promise<ToolCallEventResult | undefined> =
     async () => ({ block: true, reason: "Subagent tool policy is not ready." });
+  let childApprovalEvents: ApprovalEvents | undefined;
   const extensionFactories: InlineExtension[] = [{
     name: TOOL_POLICY_EXTENSION,
     hidden: true,
     factory: (pi) => {
+      childApprovalEvents = pi.events;
       pi.on("tool_call", async (event, hookCtx) => {
         if (hookCtx?.signal?.aborted) return { block: true, reason: "Subagent tool call was aborted." };
         const waitingForHuman = approvalTimer.isInteractiveAsk(event.toolName);
@@ -1195,7 +1233,9 @@ export async function runAgent(
           ? performance.now() + defaultToolTimeoutMs
           : Infinity;
         toolCallDeadlines.set(event, deadline);
-        const decision = await checkToolCall(event.toolName, event.input, deadline);
+        const admission = captureAdmission(event.toolName, event.input);
+        toolCallAdmissions.set(event, admission);
+        const decision = await checkToolCall(event.toolName, event.input, deadline, admission);
         // Abort cannot interrupt an already-open human dialog on these hosts.
         // Do not execute a tool if that dialog eventually approves a stopped run.
         if (hookCtx?.signal?.aborted) return { block: true, reason: "Subagent tool call was aborted." };
@@ -1279,6 +1319,10 @@ export async function runAgent(
       .flatMap(resource => resolvedNames.get(resource.path) ?? []));
     let warnedBackground = false;
     const admitChildExtension = (resource: ResolvedResource, intentional: boolean): boolean => {
+      if (approvalService && resolvedNames.get(resource.path)?.includes("pi-approvals")) {
+        if (intentional) throw new Error(`pi-approvals cannot load in agent "${type}"; integrate approvals in the root session instead (requested extension "${resource.path}").`);
+        return false;
+      }
       if (!resolvedNames.get(resource.path)?.includes("pi-background")) return true;
       const reason = `pi-background cannot load in agent "${type}": managed child sessions do not support asynchronous model wakes after completion/worktree cleanup`;
       if (intentional) throw new Error(`${reason} (requested extension "${resource.path}").`);
@@ -1517,9 +1561,34 @@ export async function runAgent(
           },
         })
       : [];
-  // One list from here on: both sets are custom tools this package injects, and
-  // the scoping pass below keeps exactly the names it is given.
-  const injectedTools = [...nestedTools, ...supervisorTools];
+  // Reviewed replacements are SDK tools, not inherited extension permissions.
+  // Admit only canonical names already allowed by the child policy.
+  let approvalSession: AgentSession | undefined;
+  // SDK winner metadata alone misses a losing late extension registration.
+  // Inspect live public maps at bind, admission and every execute guard.
+  const hasCanonicalConflict = (name: string): boolean =>
+    loader.getExtensions().extensions.some(extension => extension.tools.has(name));
+  const reviewedTools = approvalCapture && approvalService && approvalRootOrigin && toolNames.some(name => ["edit", "write", "bash"].includes(name) && !disallowedSet?.has(name))
+    ? createChildApprovalTools({
+        service: approvalService, root: ctx, rootOrigin: approvalRootOrigin, agentId: options.agentId, settings: settingsManager,
+        assertServiceCurrent: approvalCapture.assertCurrent,
+        isToolCurrent: (name) => approvalSession?.getActiveToolNames().includes(name) === true,
+        waiting: (id) => approvalSession ? approvalTimers.get(approvalSession)?.pauseHuman(id) ?? (() => {}) : () => {},
+        isBound: (): boolean => {
+          const tools = approvalSession?.getAllTools();
+          return [...reviewedNames].every(name => !hasCanonicalConflict(name) && tools?.find(tool => tool.name === name)?.sourceInfo.path === `<sdk:${name}>`);
+        },
+      }).filter(tool => toolNames.includes(tool.name) && !disallowedSet?.has(tool.name))
+    : [];
+  const reviewedNames = new Set(reviewedTools.map(tool => tool.name));
+  for (const extension of loader.getExtensions().extensions) {
+    for (const name of reviewedNames) {
+      if (extension.tools.has(name)) {
+        throw new Error(`Approval-required tool "${name}" was shadowed by "${extension.path}"; remove the conflicting child extension.`);
+      }
+    }
+  }
+  const injectedTools = [...nestedTools, ...supervisorTools, ...reviewedTools];
   const nestedToolNames = new Set(injectedTools.map(tool => tool.name));
   const askGate = createAskGate({
     askTools: agentConfig?.askTools ?? [],
@@ -1637,6 +1706,7 @@ export async function runAgent(
   }
 
   const { session } = await runInChildSessionContext(() => createAgentSession(sessionOpts));
+  approvalSession = session;
   approvalTimers.set(session, approvalTimer);
   // Install the forwarding listener immediately after session creation, before
   // bindExtensions/session_start can do asynchronous work. The old placement
@@ -1650,12 +1720,42 @@ export async function runAgent(
   const inScope = noExtensions ? undefined : extensionToolNamesInScope(session, {
     loader, toolNames, disallowedSet, extNames, narrowing, nestedToolNames, resolvedNames,
   });
-  checkToolCall = async (name, input, deadline) => {
+  captureAdmission = (name, input) => {
+    // Pi executes these captured args, even if a handler reassigns event.input.
+    const captured = session.getAllTools().find(tool => tool.name === name);
+    const requiresSchema = !!approvalService && !!captured && schemaRequiresApprovalAdapter(captured.parameters);
+    return () => {
+      if (!approvalService) return undefined;
+      if (reviewedNames.has(name)) {
+        if (hasCanonicalConflict(name) || session.getAllTools().find(tool => tool.name === name)?.sourceInfo.path !== `<sdk:${name}>`)
+          return { block: true, reason: `Approval-required tool "${name}" was shadowed; remove the conflicting child extension.` };
+        return undefined;
+      }
+      const effective = session.getAllTools().find(tool => tool.name === name);
+      if (requiresApprovalAdapter(input) || requiresSchema) {
+        try {
+          if (!captured || !effective || !childApprovalEvents || effective.parameters !== captured.parameters ||
+              effective.description !== captured.description || effective.sourceInfo.path !== captured.sourceInfo.path)
+            throw new Error("Child approval binding changed");
+          queryApprovalAdapter(childApprovalEvents, name, captured.parameters);
+        } catch {
+          return { block: true, reason: `Tool "${name}" requires exactly one live cooperative approval adapter; unreviewed fallback is blocked.` };
+        }
+      }
+      return undefined;
+    };
+  };
+  checkToolCall = async (name, input, deadline, admission) => {
     const run = async (): Promise<ToolCallEventResult | undefined> => {
       // Scope first, then approval: never prompt for a tool this child cannot use.
       if (inScope && !inScope().has(name)) {
         return { block: true, reason: `Tool "${name}" is not available to this subagent.` };
       }
+      if (reviewedNames.has(name) && (hasCanonicalConflict(name) || session.getAllTools().find(tool => tool.name === name)?.sourceInfo.path !== `<sdk:${name}>`)) {
+        return { block: true, reason: `Approval-required tool "${name}" was shadowed; only its reviewed SDK binding may execute.` };
+      }
+      const denied = admission();
+      if (denied) return denied;
       return askGate?.(name, input);
     };
     if (deadline === Infinity) return run();
@@ -1686,6 +1786,11 @@ export async function runAgent(
     },
   });
   throwIfAborted(options.signal);
+  for (const name of reviewedNames) {
+    if (hasCanonicalConflict(name) || session.getAllTools().find(tool => tool.name === name)?.sourceInfo.path !== `<sdk:${name}>`) {
+      throw new Error(`Approval-required tool "${name}" was shadowed; remove the conflicting child extension.`);
+    }
+  }
 
   // With `allowedToolNames` unset, the ACTIVE set still needs managing: Pi
   // activates default built-ins and eligible extension tools at registration.
@@ -1703,84 +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;
-  // Own finalized output before observer dispatch: a synchronous callback
-  // failure must remain visible without erasing the answer it interrupted.
+  approvalTimer.pauseHuman = toolTimeouts.pauseHuman;
+  // 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);
@@ -1792,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 });
@@ -1819,26 +1855,23 @@ export async function runAgent(
     await session.prompt(prompt);
   } finally {
     approvalTimer.armApproved = () => {};
+    approvalTimer.pauseHuman = () => () => {};
     unsubTurns();
     collector.unsubscribe();
     toolTimeouts.dispose();
   }
 
   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();
@@ -1849,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).
  */
@@ -1856,41 +1969,58 @@ 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.
   const approvalTimer = approvalTimers.get(session);
   const toolTimeouts = createToolTimeouts(session, TOOL_CALL_ABORT_GRACE_MS,
     approvalTimer?.isInteractiveAsk ?? (() => false));
-  if (approvalTimer) approvalTimer.armApproved = toolTimeouts.armApproved;
+  if (approvalTimer) {
+    approvalTimer.armApproved = toolTimeouts.armApproved;
+    approvalTimer.pauseHuman = toolTimeouts.pauseHuman;
+  }
   const unsubResumeTimeout = session.subscribe((event: AgentSessionEvent) => {
     if (event.type === "tool_execution_start") toolTimeouts.start(event);
     else if (event.type === "tool_execution_end") toolTimeouts.end(event);
@@ -1900,7 +2030,10 @@ export async function resumeAgent(
     throwIfAborted(options.signal);
     await session.prompt(prompt);
   } finally {
-    if (approvalTimer) approvalTimer.armApproved = () => {};
+    if (approvalTimer) {
+      approvalTimer.armApproved = () => {};
+      approvalTimer.pauseHuman = () => () => {};
+    }
     collector.unsubscribe();
     unsubEvents();
     unsubResumeTimeout();
@@ -1910,6 +2043,7 @@ export async function resumeAgent(
 
   return {
     text: collector.getText(),
+    ...budget.outcome(),
     failure: collector.getFailure(),
   };
 }