pi-subagents 0.60.0 → 0.61.0

package/src/runs/background/subagent-wait.ts

@@ -1,5 +1,5 @@
 /**
- * `subagent_wait` tool: block the current turn until outstanding async runs
+ * `bg_wait` tool: block the current turn until outstanding async runs
  * or a named remembered detached foreground run finishes.
  *
  * Background subagent runs are detached. In an interactive session the parent
@@ -8,33 +8,33 @@
  * cannot work at all non-interactively (`pi -p ...`), where the run is a single
  * turn: once the turn ends there is nothing left to receive the notification.
  *
- * `subagent_wait` closes that gap. It keeps the turn alive until a tracked async
+ * `bg_wait` closes that gap. It keeps the turn alive until a tracked async
  * run for this session reaches a terminal state (complete / failed / paused),
  * the caller-supplied timeout elapses, or the turn is aborted. Because it awaits
  * inside the turn, the completion the model was told to wait for is actually
  * observed before the tool returns.
  *
- * By default `subagent_wait` returns as soon as ONE run finishes, so a fleet
+ * By default `bg_wait` returns as soon as ONE run finishes, so a fleet
  * manager can use it in a rolling-replacement loop: launch N workers, wait for
- * the next one to finish, spawn its replacement, then call `subagent_wait`
+ * the next one to finish, spawn its replacement, then call `bg_wait`
  * again — keeping N in flight instead of draining to zero between batches.
  * Pass `all: true` to block until every tracked async run is terminal, or `id`
  * to block on one specific async or remembered detached foreground run.
  *
- * `subagent_wait` also returns when a run needs attention — not just on
+ * `bg_wait` also returns when a run needs attention — not just on
  * completion. A child that goes idle or blocks for a decision surfaces
  * `needs_attention` (the same signal Pi shows as a control notice and,
- * interactively, wakes the parent with). Since `subagent_wait` is used exactly
+ * interactively, wakes the parent with). Since `bg_wait` is used exactly
  * where there is no next turn to receive that notice, it must break on it too,
  * or a stuck child would stall the loop until the timeout. Attention runs are
  * reported so the caller can inspect / nudge / resume / interrupt them.
  *
- * Wake mechanism: when given Pi's event bus (`deps.events`), `subagent_wait`
+ * Wake mechanism: when given Pi's event bus (`deps.events`), `bg_wait`
  * subscribes to the subagent completion/control channels and wakes the instant
  * any fires, rather than waiting out a fixed poll interval. A poll still runs
  * on the interval as a reconciliation fallback (crashed runners, missed
  * events), and the poll is the source of truth for what actually changed — the
- * event only ends the sleep early. With no bus, `subagent_wait` degrades to pure
+ * event only ends the sleep early. With no bus, `bg_wait` degrades to pure
  * polling.
  */
 
@@ -82,9 +82,8 @@ export interface SubagentWaitParams {
 	nonBlocking?: boolean;
 	/**
 	 * When true, block until EVERY active run in this session (or matching `id`)
-	 * is terminal. Default false: return as soon as the first run finishes, so a
-	 * fleet manager can spawn a replacement and wait again. Ignored when `id`
-	 * targets a single run.
+	 * is terminal. Default false: return when the first tracked run or provider
+	 * item finishes or needs attention. Ignored when `id` targets a single run.
 	 */
 	all?: boolean;
 	/** Give up after this many milliseconds. Defaults to waitTool.defaultTimeoutMs, then 30 minutes. */
@@ -241,7 +240,7 @@ function foregroundChildrenNeedingAttention(run: ForegroundResumeRun, indices: S
 function formatForegroundAttention(run: ForegroundResumeRun, children: ReturnType<typeof foregroundChildrenNeedingAttention>, elapsedMs: number): AgentToolResult<Details> {
 	const childList = children.map((child) => `${child.agent}${child.index !== undefined ? `#${child.index}` : ""}`).join(", ");
 	return result(
-		`Waited ${formatDuration(elapsedMs)} for remembered detached foreground run "${run.runId}"; attention required. ${children.length} child run(s) need attention: ${childList}. Reply to any pending supervisor request, then call subagent_wait({ id: "${run.runId}" }) again or inspect status; do not resume or launch a replacement while it remains detached.`,
+		`Waited ${formatDuration(elapsedMs)} for remembered detached foreground run "${run.runId}"; attention required. ${children.length} child run(s) need attention: ${childList}. Reply to any pending supervisor request, then call bg_wait({ id: "${run.runId}" }) again or inspect status; do not resume or launch a replacement while it remains detached.`,
 	);
 }
 
@@ -262,7 +261,7 @@ function backgroundWorkIdentity(item: RegisteredBackgroundWorkItem): string {
 
 function backgroundWorkForSession(deps: SubagentWaitDeps, nowMs: number): BackgroundWorkSnapshot {
 	const sessionId = deps.state.currentSessionId;
-	if (!sessionId) throw new Error("subagent_wait requires an active session identity to scope background work safely.");
+	if (!sessionId) throw new Error("bg_wait requires an active session identity to scope background work safely.");
 	return deps.backgroundWork?.snapshot(sessionId, nowMs) ?? snapshotBackgroundWork(sessionId, nowMs);
 }
 
@@ -376,7 +375,7 @@ function windowElapsedResult(
 	};
 }
 
-/** Build the live status shown while async work keeps subagent_wait blocked. */
+/** Build the live status shown while async work keeps bg_wait blocked. */
 function asyncWaitUpdate(runs: AsyncRunSummary[], providerCount: number, elapsedMs: number): AgentToolResult<Details> {
 	const activity = runs.flatMap((run) => {
 		const activeSteps = run.steps.filter((step) => step.status === "pending" || step.status === "running");
@@ -524,7 +523,7 @@ async function waitForDetachedForegroundRun(
 		}
 		if (now() - startedAt >= timeoutMs) {
 			return windowElapsedResult(
-				`Wait window elapsed after ${formatDuration(timeoutMs)} with remembered foreground run "${run.runId}" still detached. Reply to any pending supervisor request, then call subagent_wait({ id: "${run.runId}" }) again or inspect status; do not resume or launch a replacement while it remains detached.`,
+				`Wait window elapsed after ${formatDuration(timeoutMs)} with remembered foreground run "${run.runId}" still detached. Reply to any pending supervisor request, then call bg_wait({ id: "${run.runId}" }) again or inspect status; do not resume or launch a replacement while it remains detached.`,
 				[run.runId],
 			);
 		}
@@ -543,10 +542,10 @@ export async function waitForSubagents(
 	deps: SubagentWaitDeps,
 ): Promise<AgentToolResult<Details>> {
 	if (deps.enabled === false) {
-		return result("subagent_wait is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED; returning immediately without blocking background work. Active work keeps going, and you can inspect subagents with subagent({ action: \"status\" }) or rely on completion notifications.");
+		return result("bg_wait is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED; returning immediately without blocking background work. Active work keeps going, and you can inspect subagents with subagent({ action: \"status\" }) or rely on completion notifications.");
 	}
 	if (!deps.state.currentSessionId) {
-		return result("subagent_wait requires an active session identity to scope background work safely.", true);
+		return result("bg_wait requires an active session identity to scope background work safely.", true);
 	}
 
 	const now = deps.now ?? Date.now;
@@ -587,7 +586,7 @@ export async function waitForSubagents(
 		const selected = matches[0];
 		if (selected && params.nonBlocking) {
 			if (!deps.subscribe) {
-				return result("Non-blocking wait subscriptions require a long-lived interactive subagent runtime; this runtime can only use blocking subagent_wait calls.", true);
+				return result("Non-blocking wait subscriptions require a long-lived interactive subagent runtime; this runtime can only use blocking bg_wait calls.", true);
 			}
 			try {
 				const registration = deps.subscribe({ targetKind: selected.kind, runId: selected.id, requestedId: params.id, timeoutMs });
@@ -641,7 +640,7 @@ export async function waitForSubagents(
 		}
 		if (now() - startedAt >= timeoutMs) {
 			return windowElapsedResult(
-				`Wait window elapsed after ${formatDuration(timeoutMs)} with ${activeInitialRuns.length} async run(s) and ${activeInitialProviderItems.length} provider item(s) still active: ${stillActive}. The work keeps going; call subagent_wait again or inspect subagent status.`,
+				`Wait window elapsed after ${formatDuration(timeoutMs)} with ${activeInitialRuns.length} async run(s) and ${activeInitialProviderItems.length} provider item(s) still active: ${stillActive}. The work keeps going; call bg_wait again or inspect subagent status.`,
 				activeInitialRuns.map((run) => run.id),
 				activeInitialProviderItems,
 			);
@@ -653,7 +652,7 @@ export async function waitForSubagents(
 			providerSnapshot = params.id ? providerSnapshot : backgroundWorkForSession(deps, now());
 			for (const provider of initialProviderNames) {
 				if (!providerSnapshot.providers.includes(provider)) {
-					return result(`Background-work provider '${provider}' disappeared while subagent_wait was tracking its active work; completion cannot be confirmed.`, true);
+					return result(`Background-work provider '${provider}' disappeared while bg_wait was tracking its active work; completion cannot be confirmed.`, true);
 				}
 			}
 			providerActive = providerSnapshot.items;
@@ -711,7 +710,7 @@ export async function waitForSubagents(
 	const finishedCount = finishedAsyncCount + providerFinishedCount;
 	const subject = initialProviderIds.size === 0 ? "run(s)" : "item(s)";
 	const remainder = stillRunning > 0
-		? ` ${stillRunning} ${subject} still in flight — call subagent_wait again to catch the next one.`
+		? ` ${stillRunning} ${subject} still in flight — call bg_wait again to catch the next one.`
 		: relevantAttention.length > 0
 			? " No other work is waitable until attention is handled."
 			: initialProviderIds.size === 0 ? " No runs remain in flight." : " No work remains in flight.";

package/src/runs/background/wait-completions.ts

@@ -99,7 +99,7 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
 }
 
 /**
- * Record a consumed terminal payload for later surfacing by subagent_wait, pruning
+ * Record a consumed terminal payload for later surfacing by bg_wait, pruning
  * stale entries with the same TTL that dedupes completion notifications. The result
  * file is deleted after delivery, so this record is the only in-process source once
  * the watcher has consumed it.

package/src/runs/background/wait-tool.ts

@@ -12,32 +12,38 @@ export function registerWaitTool(
 	subscriptions?: Pick<WaitSubscriptionManager, "arm">,
 	defaultTimeoutMs?: number,
 ): void {
-	const tool: ToolDefinition<typeof SubagentWaitParams, Details> = {
-		name: "subagent_wait",
-		label: "Subagent Wait",
-		description: `Block until background work owned by this session changes, then return.
+	const description = `Wait for background, provider, or detached work that has no native completion notification, then return.
 
-In an interactive chat, do not call this merely to wait: return control to the user and let Pi wake the session on completion. Override that default and call it when the current request is run-to-completion — for example, the user asked you to report results back before continuing or a skill cannot return before its work finishes. Headless runs auto-drain current-session work at agent_end; call this when the current turn must receive results before it ends.
+Ordinary async subagent runs already notify this session natively when they complete or need attention. In an interactive chat, return control instead of calling this merely to wait. Use this tool for provider jobs, remembered detached foreground runs, or other background work without a native notification path. Headless runs auto-drain current-session subagent work at agent_end; use this tool only when the current turn must receive non-notifying background work results.
 
 • { } — return when the first initially active async run or registered provider item finishes, or when a subagent needs attention.
 • { all: true } — wait for every async run and provider item that was active when the call began.
 • { id: "..." } — wait for one async or remembered detached foreground subagent run (id or prefix).
-• { id: "...", nonBlocking: true } — resolve the prefix once, persist an exact-run wake subscription, and return immediately. The originating interactive session wakes on completion, failure, attention, reconciliation failure, or timeout.
+• { id: "...", nonBlocking: true } — resolve the prefix once, persist an exact-run wake subscription, and return immediately. Use this for detached work without native completion delivery; the originating interactive session wakes on completion, failure, attention, reconciliation failure, or timeout.
 • { stopOnAttention: false } — for blocking waits only, keep waiting through idle or long-thinking attention; supervisor/contact requests still stop the wait.
 • { timeoutMs: 600000 } — stop waiting after N ms; active work keeps running. Omitted values use waitTool.defaultTimeoutMs, then 30 minutes. Window expiry returns a non-error window_elapsed result with active work identities.
 
-Non-blocking subscriptions are visible in subagent status and differ from disabling waitTool: waitTool.enabled=false returns immediately without registering any future wake. Provider jobs are session-scoped and identified exactly, so replacing one job with another cannot hide a completion. Provider extensions must be explicitly loaded in this process. In a child agent, keep \`subagent_wait\` in the child tool allowlist and load each provider through the agent's extensions or subagentOnlyExtensions; this tool never loads providers or grants tools itself.${enabled ? "" : "\n\nConfigured behavior: subagent_wait is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED and returns immediately without blocking."}`,
+Non-blocking subscriptions are visible in subagent status and differ from disabling waitTool: waitTool.enabled=false returns immediately without registering any future wake. Provider jobs are session-scoped and identified exactly, so replacing one job with another cannot hide a completion. Provider extensions must be explicitly loaded in this process. In a child agent, keep \`bg_wait\` (or the deprecated \`subagent_wait\` compatibility alias) in the child tool allowlist and load each provider through the agent's extensions or subagentOnlyExtensions; this tool never loads providers or grants tools itself.${enabled ? "" : "\n\nConfigured behavior: bg_wait and its subagent_wait compatibility alias are disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED and return immediately without blocking."}`;
+	const execute: ToolDefinition<typeof SubagentWaitParams, Details>["execute"] = async (_id, params, signal, onUpdate, ctx) => finalizeToolResult(await waitForSubagents(params, signal, {
+		state,
+		events: pi.events,
+		enabled,
+		...(defaultTimeoutMs !== undefined ? { defaultTimeoutMs } : {}),
+		onUpdate,
+		...(subscriptions && ctx?.hasUI ? { subscribe: (input) => subscriptions.arm(input) } : {}),
+	}));
+	const primaryTool: ToolDefinition<typeof SubagentWaitParams, Details> = {
+		name: "bg_wait",
+		label: "Background Wait",
+		description,
 		parameters: SubagentWaitParams,
-		async execute(_id, params, signal, onUpdate, ctx) {
-			return finalizeToolResult(await waitForSubagents(params, signal, {
-				state,
-				events: pi.events,
-				enabled,
-				...(defaultTimeoutMs !== undefined ? { defaultTimeoutMs } : {}),
-				onUpdate,
-				...(subscriptions && ctx?.hasUI ? { subscribe: (input) => subscriptions.arm(input) } : {}),
-			}));
-		},
+		execute,
 	};
-	pi.registerTool(tool);
+	pi.registerTool(primaryTool);
+	pi.registerTool({
+		...primaryTool,
+		name: "subagent_wait",
+		label: "Subagent Wait (deprecated)",
+		description: "Deprecated compatibility alias for `bg_wait`. Use `bg_wait` for background, provider, or detached work without a native completion notification. It has the same parameters and behavior.",
+	});
 }

package/src/runs/foreground/execution.ts

@@ -49,6 +49,7 @@ import {
 	formatEmptyTerminalAssistantResponseError,
 	extractToolArgsPreview,
 	extractTextFromContent,
+	MAX_STREAMED_RECENT_TOOLS,
 	boundStreamedRecentTools,
 	boundStreamedRecentOutput,
 	boundStreamedToolCalls,
@@ -297,6 +298,55 @@ function snapshotStreamResult(result: SingleResult, progress: AgentProgress): Si
 	return snapshot;
 }
 
+interface StructuredDelegationProgressState {
+	currentTool?: string;
+	currentToolArgs?: string;
+	recentOutput: string[];
+	recentTools: Array<{ tool: string; args: string }>;
+	activityState?: AgentProgress["activityState"];
+	model?: string;
+	toolCount: number;
+	tokens: number;
+}
+
+function captureStructuredDelegationProgressState(progress: AgentProgress, result: SingleResult): StructuredDelegationProgressState {
+	return {
+		currentTool: progress.currentTool,
+		currentToolArgs: progress.currentToolArgs,
+		recentOutput: [...progress.recentOutput],
+		recentTools: progress.recentTools.slice(-MAX_STREAMED_RECENT_TOOLS).map(({ tool, args }) => ({ tool, args })),
+		activityState: progress.activityState,
+		model: progress.model ?? result.model,
+		toolCount: progress.toolCount,
+		tokens: progress.tokens,
+	};
+}
+
+function structuredDelegationProgressChanged(
+	previous: StructuredDelegationProgressState,
+	progress: AgentProgress,
+	result: SingleResult,
+): boolean {
+	if (previous.currentTool !== progress.currentTool
+		|| previous.currentToolArgs !== progress.currentToolArgs
+		|| previous.activityState !== progress.activityState
+		|| previous.model !== (progress.model ?? result.model)
+		|| previous.toolCount !== progress.toolCount
+		|| previous.tokens !== progress.tokens
+		|| previous.recentOutput.length !== progress.recentOutput.length) return true;
+	for (let index = 0; index < progress.recentOutput.length; index++) {
+		if (previous.recentOutput[index] !== progress.recentOutput[index]) return true;
+	}
+	const recentToolsStart = Math.max(0, progress.recentTools.length - MAX_STREAMED_RECENT_TOOLS);
+	if (previous.recentTools.length !== progress.recentTools.length - recentToolsStart) return true;
+	for (let index = recentToolsStart; index < progress.recentTools.length; index++) {
+		const previousTool = previous.recentTools[index - recentToolsStart];
+		const currentTool = progress.recentTools[index];
+		if (previousTool?.tool !== currentTool?.tool || previousTool?.args !== currentTool?.args) return true;
+	}
+	return false;
+}
+
 const AFTER_COMPACTION_SETTLEMENT = Symbol("afterCompactionSettlement");
 type AbortRecoverySingleResult = SingleResult & { [AFTER_COMPACTION_SETTLEMENT]?: true };
 
@@ -936,6 +986,7 @@ async function runSingleAttempt(
 		};
 
 
+		let lastStructuredDelegationProgressState: StructuredDelegationProgressState | undefined;
 		const emitUpdateSnapshot = (text: string) => {
 			if (!options.onUpdate || processClosed) return;
 			const progressSnapshot = snapshotProgress(progress);
@@ -955,6 +1006,10 @@ async function runSingleAttempt(
 		const fireUpdate = () => {
 			if (!options.onUpdate || processClosed) return;
 			progress.durationMs = Date.now() - startTime;
+			if (options.suppressUnchangedDelegationUpdates) {
+				if (lastStructuredDelegationProgressState && !structuredDelegationProgressChanged(lastStructuredDelegationProgressState, progress, result)) return;
+				lastStructuredDelegationProgressState = captureStructuredDelegationProgressState(progress, result);
+			}
 			const output = result.timedOut && result.finalOutput ? result.finalOutput : getFinalOutput(result.messages ?? []);
 			emitUpdateSnapshot(output || "(running...)");
 		};
@@ -1816,7 +1871,11 @@ async function runSyncCompletionInner(
 		agent.fallbackModels,
 		options.availableModels,
 		agent.modelProvider ?? options.preferredModelProvider,
-		{ scope: options.modelScope, primaryModelFromParent: options.modelOverrideFromParent },
+		{
+			scope: options.modelScope,
+			primaryModelFromParent: options.modelOverrideFromParent,
+			origin: options.modelOrigin ?? (options.modelOverrideFromParent ? "inherited" : "configured"),
+		},
 	);
 	if (options.workflowChildPermitLaunch && candidates.length > 1) {
 		const error = "Workflow child permit does not support model fallback.";
@@ -2159,7 +2218,7 @@ async function runSyncCompletionInner(
 				report: (result as SingleResult & { structuredAcceptanceReport?: import("../../shared/types.ts").AcceptanceReport; structuredAcceptanceReportError?: string }).structuredAcceptanceReport,
 				reportError: (result as SingleResult & { structuredAcceptanceReport?: import("../../shared/types.ts").AcceptanceReport; structuredAcceptanceReportError?: string }).structuredAcceptanceReportError,
 				fileOutput: childWrittenOutput !== undefined && options.outputPath
-					? { content: childWrittenOutput, path: options.outputPath, authoritative: options.outputMode === "file-only" }
+					? { content: childWrittenOutput, path: options.outputPath, authoritative: options.outputMode === "file-only", durable: result.savedOutputPath !== undefined }
 					: undefined,
 				cwd: options.cwd ?? runtimeCwd,
 				reportOptional: isAgentContractV1(options.agentContract),