pi-subagents 0.59.0 → 0.61.0

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,
@@ -66,7 +67,7 @@ import { createJsonlWriter } from "../../shared/jsonl-writer.ts";
 import { createOrcaProgressTab, type OrcaProgressTab } from "../shared/orca-progress-tabs.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
 import { resolvePermissionRules } from "../shared/permissions.ts";
-import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan, type SubagentTaskDelivery } from "../shared/pi-args.ts";
+import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, deriveForkPromptCacheKey, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan, type SubagentTaskDelivery } from "../shared/pi-args.ts";
 import { deriveChildSessionName } from "../../shared/child-session-name.ts";
 import { readRuntimeAcknowledgedExtensions } from "../shared/runtime-acknowledged-extensions.ts";
 import { assertAgentAllowedByCapabilityCeiling, decodeSubagentCapabilityCeiling, intersectSubagentCapabilityCeilings, resolveCurrentSubagentCapabilityCeiling, SUBAGENT_CAPABILITY_CEILING_ENV } from "../shared/capability-ceiling.ts";
@@ -76,7 +77,7 @@ import { MISSING_STRUCTURED_OUTPUT_CALL_ERROR, readStructuredOutput, readStructu
 import { formatMidToolExitError, formatProcessSignalError, isOrdinaryToolForMidToolExit, isUnexplainedProcessSignal } from "../shared/process-signal.ts";
 import { readChildToolDiagnosticError } from "../shared/tool-availability.ts";
 import { buildTimeoutRecoverySummary, collectTrackedMutationEvidence, snapshotTrackedMutations } from "../shared/mutation-evidence.ts";
-import { captureSingleOutputSnapshot, extractChildWrittenOutput, finalizeSingleOutput, formatSavedOutputReference, injectOutputPathSystemPrompt, resolveSingleOutput, validateFileOnlyOutputMode, type SingleOutputSnapshot } from "../shared/single-output.ts";
+import { captureSingleOutputSnapshot, extractChildWrittenOutput, finalizeSingleOutput, formatSavedOutputReference, hasSingleOutputChangedSinceSnapshot, injectOutputPathSystemPrompt, resolveSingleOutput, validateFileOnlyOutputMode, type SingleOutputSnapshot } from "../shared/single-output.ts";
 import {
 	buildModelCandidates,
 	formatSubagentModelVerificationError,
@@ -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 };
 
@@ -380,6 +430,7 @@ async function runSingleAttempt(
 		parentCapabilityToken: options.nestedRoute?.capabilityToken,
 		runFanoutBudget: options.runFanoutBudget,
 		parentSessionId: options.parentSessionId,
+		forkCacheKey: options.context === "fork" ? deriveForkPromptCacheKey(options.parentSessionId) : undefined,
 		steerInboxDir: options.steerInboxDir,
 		steerCapabilityPath: options.steerCapabilityPath,
 		steerAckDir: options.steerAckDir,
@@ -935,6 +986,7 @@ async function runSingleAttempt(
 		};
 
 
+		let lastStructuredDelegationProgressState: StructuredDelegationProgressState | undefined;
 		const emitUpdateSnapshot = (text: string) => {
 			if (!options.onUpdate || processClosed) return;
 			const progressSnapshot = snapshotProgress(progress);
@@ -954,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...)");
 		};
@@ -1527,9 +1583,17 @@ async function runSingleAttempt(
 	result.outputState = fullOutput.trim() || result.structuredOutput !== undefined ? "present" : "absent";
 	if (result.timedOut) {
 		const timeoutMessage = formatTimeoutMessage(options.timeoutMs ?? 0);
+		let requiredOutputMissing: boolean | undefined;
+		if (options.outputMode === "file-only" && options.outputPath) {
+			const outputChanged = hasSingleOutputChangedSinceSnapshot(options.outputPath, shared.outputSnapshot);
+			requiredOutputMissing = outputChanged === undefined ? undefined : !outputChanged;
+		} else if (options.structuredOutput) {
+			requiredOutputMissing = !existsSync(options.structuredOutput.outputPath);
+		}
 		result.timeoutRecovery = buildTimeoutRecoverySummary({
 			termination: "timed-out",
 			evidence: mutationEvidence,
+			requiredOutputMissing,
 			currentTool: progress.currentTool,
 			currentToolArgs: progress.currentToolArgs,
 			currentPath: progress.currentPath,
@@ -1807,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.";
@@ -2150,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),