pi-subagents 0.35.1 → 0.37.0

package/src/runs/foreground/execution.ts

@@ -9,6 +9,7 @@ import type { Message } from "@earendil-works/pi-ai";
 import type { AgentConfig } from "../../agents/agents.ts";
 import {
 	ensureArtifactsDir,
+	formatOutputArtifactContent,
 	getArtifactPaths,
 	writeArtifact,
 	writeMetadata,
@@ -41,6 +42,7 @@ import {
 	getFinalOutput,
 	findLatestSessionFile,
 	detectSubagentError,
+	hasEmptyTerminalAssistantResponse,
 	extractToolArgsPreview,
 	extractTextFromContent,
 } from "../../shared/utils.ts";
@@ -50,8 +52,10 @@ import { evaluateCompletionMutationGuard } from "../shared/completion-guard.ts";
 import { getPiSpawnCommand } from "../shared/pi-spawn.ts";
 import { createJsonlWriter } from "../../shared/jsonl-writer.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
-import { applyThinkingSuffix, buildPiArgs, cleanupTempDir } from "../shared/pi-args.ts";
-import { readStructuredOutput } from "../shared/structured-output.ts";
+import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, resolvePiLaunchToolPlan } from "../shared/pi-args.ts";
+import { decodeSubagentCapabilityCeiling, resolveCurrentSubagentCapabilityCeiling, SUBAGENT_CAPABILITY_CEILING_ENV } from "../shared/capability-ceiling.ts";
+import { resolveEffectiveThinking } from "../../shared/model-info.ts";
+import { MISSING_STRUCTURED_OUTPUT_CALL_ERROR, readStructuredOutput } from "../shared/structured-output.ts";
 import { readChildToolDiagnosticError } from "../shared/tool-availability.ts";
 import { captureSingleOutputSnapshot, extractChildWrittenOutput, formatSavedOutputReference, injectOutputPathSystemPrompt, resolveSingleOutput, validateFileOnlyOutputMode, type SingleOutputSnapshot } from "../shared/single-output.ts";
 import {
@@ -71,9 +75,11 @@ import {
 	summarizeRecentMutatingFailures,
 } from "../shared/long-running-guard.ts";
 import { acceptanceFailureMessage, buildSkippedAcceptanceLedger, evaluateAcceptance, formatAcceptancePrompt, resolveEffectiveAcceptance, stripAcceptanceReport } from "../shared/acceptance.ts";
+import { attachContractProjections, isAgentContractV1 } from "../shared/agent-contract.ts";
 import { appendTurnBudgetSystemPrompt, formatTurnBudgetOutput, initialTurnBudgetState, turnBudgetDecision, turnBudgetDeferredNote, turnBudgetDeferredState, turnBudgetExceededMessage, turnBudgetSoftNote, turnBudgetState } from "../shared/turn-budget.ts";
 import { initialToolBudgetState, toolBudgetState } from "../shared/tool-budget.ts";
 import { resolveWatchdogConfig } from "../../watchdog/settings.ts";
+import { agentDefinitionDigest, launchBindingDigest } from "../../shared/launch-contract.ts";
 import { createBoundedByteTail, createBoundedLineReader, formatProtocolOutputLimit, MAX_CHILD_STDERR_BYTES, projectChildLifecycle, type ChildLifecycleAction, type ProtocolOutputLimit } from "../shared/child-protocol.ts";
 import {
 	acceptChildWatchdogEvent,
@@ -90,6 +96,12 @@ function emptyUsage(): Usage {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
 }
 
+function withRunContext<T extends SingleResult>(result: T, context: RunSyncOptions["context"]): T {
+	if (!context) return result;
+	result.context = context;
+	return result;
+}
+
 function sumUsage(target: Usage, source: Usage): void {
 	target.input += source.input;
 	target.output += source.output;
@@ -116,6 +128,7 @@ function resolveAttemptTimeout(options: RunSyncOptions): { timeoutMs: number; re
 function buildPendingAcceptanceLedger(acceptance: ResolvedAcceptanceConfig): AcceptanceLedger {
 	return {
 		status: "pending",
+		evidenceStatus: "pending",
 		explicit: acceptance.explicit,
 		effectiveAcceptance: acceptance,
 		inferredReason: acceptance.inferredReason,
@@ -185,6 +198,7 @@ async function runSingleAttempt(
 		sessionEnabled: boolean;
 		systemPrompt: string;
 		resolvedSkillNames?: string[];
+		modelCandidates?: string[];
 		skillsWarning?: string;
 		jsonlPath?: string;
 		artifactPaths?: ArtifactPaths;
@@ -196,6 +210,7 @@ async function runSingleAttempt(
 ): Promise<SingleResult> {
 	const effectiveThinking = options.thinkingOverride ?? agent.thinking;
 	const modelArg = applyThinkingSuffix(model, effectiveThinking, options.thinkingOverride !== undefined);
+	const resolvedThinking = resolveEffectiveThinking(modelArg, effectiveThinking);
 	const watchdogConfig = resolveWatchdogConfig(options.cwd ?? runtimeCwd);
 	const childWatchdog = watchdogConfig.ok
 		? resolveChildWatchdogConfig({
@@ -205,7 +220,7 @@ async function runSingleAttempt(
 			childIndex: options.index ?? 0,
 		})
 		: undefined;
-	const { args, env: sharedEnv, tempDir, toolDiagnosticPath } = buildPiArgs({
+	const { args, env: sharedEnv, tempDir, toolDiagnosticPath, capabilityAudit } = buildPiArgs({
 		baseArgs: ["--mode", "json", "-p"],
 		task,
 		sessionEnabled: shared.sessionEnabled,
@@ -236,24 +251,61 @@ async function runSingleAttempt(
 		parentSessionId: options.parentSessionId,
 		structuredOutput: options.structuredOutput,
 		toolBudget: options.toolBudget,
+		allowZeroToolBudget: options.allowZeroToolBudget,
 		childWatchdog,
 		waitToolEnabled: options.waitToolEnabled,
+		capabilityCeiling: options.capabilityCeiling,
 	});
 
-	const result: SingleResult = {
+	const effectiveSystemPrompt = appendTurnBudgetSystemPrompt(shared.systemPrompt, options.turnBudget);
+	const toolPlan = resolvePiLaunchToolPlan({
+		tools: agent.tools,
+		extensions: agent.extensions,
+		subagentOnlyExtensions: agent.subagentOnlyExtensions,
+		mcpDirectTools: agent.mcpDirectTools,
+		cwd: options.cwd ?? runtimeCwd,
+		requireReadTool: Boolean(shared.resolvedSkillNames?.length),
+		structuredOutput: Boolean(options.structuredOutput),
+		capabilityCeiling: options.capabilityCeiling,
+		inheritedCapabilityCeiling: decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]),
+	});
+	const launchContractDigest = launchBindingDigest({
+		definitionDigest: agentDefinitionDigest(agent),
+		task: shared.originalTask ?? task,
+		...(modelArg ? { model: modelArg } : {}),
+		modelCandidates: shared.modelCandidates,
+		...(resolvedThinking ? { thinking: resolvedThinking } : {}),
+		systemPrompt: effectiveSystemPrompt,
+		systemPromptMode: agent.systemPromptMode,
+		inheritProjectContext: agent.inheritProjectContext,
+		inheritSkills: agent.inheritSkills,
+		skills: shared.resolvedSkillNames ?? [],
+		tools: toolPlan.effectiveToolAllowlist,
+		extensions: toolPlan.extensionArgs,
+		mcpDirectTools: toolPlan.effectiveMcpTools,
+		...(options.outputPath ? { outputPath: options.outputPath } : {}),
+		outputMode: options.outputMode ?? "inline",
+		...(options.structuredOutput ? { structuredOutputSchema: options.structuredOutput.schema } : {}),
+	});
+	const result: SingleResult = withRunContext({
 		agent: agent.name,
 		task: shared.originalTask ?? task,
+		...(options.agentContract ? { agentContract: options.agentContract } : {}),
+		launchContractDigest,
 		exitCode: 0,
 		messages: [],
 		usage: emptyUsage(),
 		model: modelArg,
+		...(resolvedThinking ? { thinking: resolvedThinking } : {}),
 		artifactPaths: shared.artifactPaths,
 		transcriptPath: shared.transcriptWriter ? shared.artifactPaths?.transcriptPath : undefined,
 		skills: shared.resolvedSkillNames,
 		skillsWarning: shared.skillsWarning,
 		...(options.turnBudget ? { turnBudget: initialTurnBudgetState(options.turnBudget) } : {}),
 		...(options.toolBudget ? { toolBudget: initialToolBudgetState(options.toolBudget) } : {}),
-	};
+		...(options.capabilityCeiling ? { capabilityCeiling: options.capabilityCeiling } : {}),
+		...(capabilityAudit ? { capabilityAudit } : {}),
+	}, options.context);
 	const startTime = Date.now();
 	if (options.structuredOutput) {
 		try {
@@ -307,6 +359,7 @@ async function runSingleAttempt(
 	}
 	const spawnEnv = { ...process.env, ...sharedEnv, ...getSubagentDepthEnv(options.maxSubagentDepth) };
 	let observedMutationAttempt = false;
+	let structuredOutputToolInvoked = false;
 
 	const exitCode = await new Promise<number>((resolve) => {
 		const spawnSpec = getPiSpawnCommand(args);
@@ -592,7 +645,7 @@ async function runSingleAttempt(
 				result.wrapUpRequested = true;
 				appendRecentOutput(progress, [turnBudgetSoftNote(budget, turnCount)]);
 			}
-			const decision = turnBudgetDecision(budget, turnCount, terminalAssistantStop, toolWorkActiveOrStarting);
+			const decision = turnBudgetDecision(budget, turnCount, terminalAssistantStop, toolWorkActiveOrStarting, options.enforceHardTurnLimit);
 			if (decision === "defer") {
 				result.turnBudget = turnBudgetDeferredState(
 					budget,
@@ -646,7 +699,7 @@ async function runSingleAttempt(
 		const fireUpdate = () => {
 			if (!options.onUpdate || processClosed) return;
 			progress.durationMs = Date.now() - startTime;
-			const output = (result.timedOut || result.turnBudgetExceeded) && result.finalOutput ? result.finalOutput : getFinalOutput(result.messages);
+			const output = (result.timedOut || result.turnBudgetExceeded) && result.finalOutput ? result.finalOutput : getFinalOutput(result.messages ?? []);
 			emitUpdateSnapshot(output || "(running...)");
 		};
 
@@ -696,6 +749,7 @@ async function runSingleAttempt(
 				const toolArgs = evt.args && typeof evt.args === "object" && !Array.isArray(evt.args)
 					? evt.args as Record<string, unknown>
 					: {};
+				if (options.structuredOutput && evt.toolName === "structured_output") structuredOutputToolInvoked = true;
 				if (options.allowIntercomDetach && (evt.toolName === "intercom" || evt.toolName === "contact_supervisor")) {
 					intercomStarted = true;
 				}
@@ -729,15 +783,20 @@ async function runSingleAttempt(
 			}
 
 			if (evt.type === "message_end" && evt.message) {
-				result.messages.push(evt.message);
+				result.messages!.push(evt.message);
 				if (evt.message.role === "assistant") {
 					result.usage.turns++;
 					progress.turnCount = result.usage.turns;
 					const stopReason = (evt.message as { stopReason?: string }).stopReason;
-					const hasToolCall = Array.isArray(evt.message.content)
-						&& evt.message.content.some((part) => (part as { type?: string }).type === "toolCall");
+					const toolCalls = Array.isArray(evt.message.content)
+						? evt.message.content.filter((part) => (part as { type?: string }).type === "toolCall")
+						: [];
+					const hasToolCall = toolCalls.length > 0;
 					const terminalAssistantStop = stopReason === "stop" && !hasToolCall;
-					updateTurnBudget(result.usage.turns, terminalAssistantStop, hasToolCall || Boolean(progress.currentTool));
+					const terminalStructuredOutputCall = Boolean(options.structuredOutput)
+						&& toolCalls.length === 1
+						&& (toolCalls[0] as { name?: string }).name === "structured_output";
+					updateTurnBudget(result.usage.turns, terminalAssistantStop || terminalStructuredOutputCall, hasToolCall || Boolean(progress.currentTool));
 					const u = evt.message.usage;
 					if (u) {
 						result.usage.input += u.input || 0;
@@ -763,7 +822,7 @@ async function runSingleAttempt(
 			}
 
 			if (evt.type === "tool_result_end" && evt.message) {
-				result.messages.push(evt.message);
+				result.messages!.push(evt.message);
 				const resultText = extractTextFromContent(evt.message.content);
 				if (options.toolBudget && pendingToolResult && resultText.includes("Tool budget hard limit reached")) {
 					result.toolBudgetBlocked = true;
@@ -1021,37 +1080,43 @@ async function runSingleAttempt(
 		result.exitCode = 1;
 	}
 	if (result.exitCode === 0 && !result.error) {
-		const errInfo = detectSubagentError(result.messages);
-		if (errInfo.hasError) {
-			result.exitCode = errInfo.exitCode ?? 1;
-			result.error = errInfo.details
-				? `${errInfo.errorType} failed (exit ${errInfo.exitCode}): ${errInfo.details}`
-				: `${errInfo.errorType} failed with exit code ${errInfo.exitCode}`;
-		}
-	}
-	if (result.exitCode === 0 && !result.error) {
-		const finalText = getFinalOutput(result.messages);
+		const messages = result.messages ?? [];
+		const finalText = getFinalOutput(messages);
 		const missingStructuredOutput = options.structuredOutput
 			? !existsSync(options.structuredOutput.outputPath)
 			: false;
-		if (!finalText?.trim() && (!options.structuredOutput || missingStructuredOutput)) {
+		const errInfo = detectSubagentError(messages);
+		const missingOutput = !finalText?.trim() && (!options.structuredOutput || missingStructuredOutput);
+		if (missingOutput && (!errInfo.hasError || hasEmptyTerminalAssistantResponse(messages))) {
 			result.exitCode = 1;
 			result.error = "Subagent produced no output (possible model cold-start or empty response).";
+		} else if (errInfo.hasError) {
+			result.exitCode = errInfo.exitCode ?? 1;
+			result.error = errInfo.details
+				? `${errInfo.errorType} failed (exit ${errInfo.exitCode}): ${errInfo.details}`
+				: `${errInfo.errorType} failed with exit code ${errInfo.exitCode}`;
 		}
 	}
 	if (options.structuredOutput && result.exitCode === 0 && !result.error) {
-		const structured = readStructuredOutput({
-			schema: options.structuredOutput.schema,
-			schemaPath: options.structuredOutput.schemaPath,
-			outputPath: options.structuredOutput.outputPath,
-		});
 		result.structuredOutputSchemaPath = options.structuredOutput.schemaPath;
 		result.structuredOutputPath = options.structuredOutput.outputPath;
-		if (structured.error) {
+		if (!structuredOutputToolInvoked) {
 			result.exitCode = 1;
-			result.error = structured.error;
+			result.error = MISSING_STRUCTURED_OUTPUT_CALL_ERROR;
+			result.structuredOutputFailed = true;
 		} else {
-			result.structuredOutput = structured.value;
+			const structured = await readStructuredOutput({
+				schema: options.structuredOutput.schema,
+				schemaPath: options.structuredOutput.schemaPath,
+				outputPath: options.structuredOutput.outputPath,
+			});
+			if (structured.error) {
+				result.exitCode = 1;
+				result.error = structured.error;
+				result.structuredOutputFailed = true;
+			} else {
+				result.structuredOutput = structured.value;
+			}
 		}
 	}
 
@@ -1070,7 +1135,7 @@ async function runSingleAttempt(
 		durationMs: progress.durationMs,
 	};
 
-	const acceptanceOutput = getFinalOutput(result.messages);
+	const acceptanceOutput = getFinalOutput(result.messages ?? []);
 	let fullOutput = stripAcceptanceReport(acceptanceOutput);
 	if (result.timedOut) {
 		const timeoutMessage = formatTimeoutMessage(options.timeoutMs ?? 0);
@@ -1086,16 +1151,29 @@ async function runSingleAttempt(
 		const note = turnBudgetSoftNote(result.turnBudget, result.turnBudget.wrapUpRequestedAtTurn ?? result.turnBudget.turnCount);
 		fullOutput = fullOutput.trim() ? `${note}\n\n${fullOutput}` : note;
 	}
-	const completionGuard = result.exitCode === 0 && !result.error && agent.completionGuard !== false
+	const completionGuardEnabled = isAgentContractV1(options.agentContract) ? agent.completionGuard === true : agent.completionGuard !== false;
+	const completionGuard = result.exitCode === 0 && !result.error && completionGuardEnabled
 		? evaluateCompletionMutationGuard({
 			agent: agent.name,
 			task: shared.originalTask ?? task,
-			messages: result.messages,
+			messages: result.messages ?? [],
 			tools: agent.tools,
 			mcpDirectTools: agent.mcpDirectTools,
 		})
 		: undefined;
-	if (completionGuard?.triggered && !observedMutationAttempt) {
+	const completionGuardTriggered = completionGuard?.triggered === true && !observedMutationAttempt;
+	if (completionGuard) {
+		result.effects = {
+			...(result.effects ?? {}),
+			fileMutation: {
+				status: completionGuard.expectedMutation ? completionGuardTriggered ? "missing" : "observed" : "not-applicable",
+				expected: completionGuard.expectedMutation,
+				attempted: completionGuard.attemptedMutation || observedMutationAttempt,
+				...(completionGuardTriggered ? { message: "Subagent completed without making edits for an implementation task." } : {}),
+			},
+		};
+	}
+	if (completionGuardTriggered && !isAgentContractV1(options.agentContract)) {
 		result.exitCode = 1;
 		result.error = "Subagent completed without making edits for an implementation task.\nIt appears to have returned planning or scratchpad output instead of applying changes.";
 		progress.status = "failed";
@@ -1154,20 +1232,24 @@ export async function runSync(
 	task: string,
 	options: RunSyncOptions,
 ): Promise<SingleResult> {
+	options = {
+		...options,
+		capabilityCeiling: options.capabilityCeiling ?? resolveCurrentSubagentCapabilityCeiling(options.parentSessionId),
+	};
 	const agent = agents.find((a) => a.name === agentName);
 	if (!agent) {
-		return {
+		return withRunContext({
 			agent: agentName,
 			task,
 			exitCode: 1,
 			messages: [],
 			usage: emptyUsage(),
 			error: `Unknown agent: ${agentName}`,
-		};
+		}, options.context);
 	}
 	const outputModeValidationError = validateFileOnlyOutputMode(options.outputMode, options.outputPath, `Single run (${agentName})`);
 	if (outputModeValidationError) {
-		return {
+		return withRunContext({
 			agent: agentName,
 			task,
 			exitCode: 1,
@@ -1175,7 +1257,7 @@ export async function runSync(
 			usage: emptyUsage(),
 			outputMode: options.outputMode,
 			error: outputModeValidationError,
-		};
+		}, options.context);
 	}
 
 	const shareEnabled = options.share === true;
@@ -1188,8 +1270,9 @@ export async function runSync(
 		async: options.acceptanceContext?.async,
 		dynamic: options.acceptanceContext?.dynamic,
 		dynamicGroup: options.acceptanceContext?.dynamicGroup,
+		agentContract: options.agentContract,
 	});
-	const acceptancePrompt = formatAcceptancePrompt(effectiveAcceptance);
+	const acceptancePrompt = formatAcceptancePrompt(effectiveAcceptance, { reportOptional: isAgentContractV1(options.agentContract) });
 	const taskWithAcceptance = acceptancePrompt ? `${task}\n${acceptancePrompt}` : task;
 	const sessionEnabled = Boolean(options.sessionFile || options.sessionDir) || shareEnabled;
 	const skillNames = options.skills ?? agent.skills ?? [];
@@ -1202,14 +1285,14 @@ export async function runSync(
 		agent.filePath ? path.dirname(agent.filePath) : skillCwd,
 	);
 	if (skillNames.some((skill) => skill.trim() === "pi-subagents") && missingSkills.includes("pi-subagents")) {
-		return {
+		return withRunContext({
 			agent: agentName,
 			task,
 			exitCode: 1,
 			messages: [],
 			usage: emptyUsage(),
 			error: "Skills not found: pi-subagents",
-		};
+		}, options.context);
 	}
 	let systemPrompt = agent.systemPrompt?.trim() || "";
 	if (resolvedSkills.length > 0) {
@@ -1275,7 +1358,14 @@ export async function runSync(
 			durationMs: target.progressSummary?.durationMs,
 			toolCount: target.progressSummary?.toolCount,
 			error: target.error,
+			agentContract: target.agentContract,
+			launchContractDigest: target.launchContractDigest,
+			execution: target.execution,
 			acceptance: target.acceptance,
+			capabilityCeiling: target.capabilityCeiling,
+			capabilityAudit: target.capabilityAudit,
+			review: target.review,
+			effects: target.effects,
 			...(transcriptWriter ? { transcriptPath: artifactPathsResult.transcriptPath } : {}),
 			transcriptError: target.transcriptError,
 			skills: target.skills,
@@ -1299,10 +1389,11 @@ export async function runSync(
 							? { content: childWrittenOutput, path: options.outputPath, authoritative: options.outputMode === "file-only" }
 							: undefined,
 						cwd: options.cwd ?? runtimeCwd,
+						reportOptional: isAgentContractV1(options.agentContract),
 					});
 					const acceptanceFailure = acceptanceFailureMessage(recoveredResult.acceptance);
 					stripAcceptanceReportsFromMessages(recoveredResult.messages);
-					if (acceptanceFailure && recoveredResult.acceptance.explicit && recoveredResult.exitCode === 0) {
+					if (acceptanceFailure && recoveredResult.acceptance.explicit && recoveredResult.exitCode === 0 && !isAgentContractV1(options.agentContract)) {
 						recoveredResult.exitCode = 1;
 						recoveredResult.error = recoveredResult.error ? `${recoveredResult.error}\n${acceptanceFailure}` : acceptanceFailure;
 						if (recoveredResult.progress) {
@@ -1310,6 +1401,7 @@ export async function runSync(
 							recoveredResult.progress.error = recoveredResult.error;
 						}
 					}
+					if (isAgentContractV1(options.agentContract)) attachContractProjections(recoveredResult);
 					persistResultMetadata(recoveredResult);
 					options.onDetachedExit?.(recoveredResult);
 				})().catch((error) => {
@@ -1336,6 +1428,7 @@ export async function runSync(
 			artifactPaths: artifactPathsResult,
 			transcriptWriter,
 			attemptNotes,
+			modelCandidates: candidates.map((candidate) => applyThinkingSuffix(candidate, options.thinkingOverride ?? agent.thinking, options.thinkingOverride !== undefined)),
 			outputSnapshot,
 			originalTask: task,
 		});
@@ -1366,14 +1459,14 @@ export async function runSync(
 		attemptNotes.push(formatModelAttemptNote(attempt, modelsToTry[i + 1]));
 	}
 
-	const result = lastResult ?? {
+	const result = withRunContext(lastResult ?? {
 		agent: agentName,
 		task,
 		exitCode: 1,
 		messages: [],
 		usage: emptyUsage(),
 		error: "Subagent did not produce a result.",
-	} satisfies SingleResult;
+	} satisfies SingleResult, options.context);
 
 	result.usage = aggregateUsage;
 	result.attemptedModels = attemptedModels.length > 0 ? attemptedModels : undefined;
@@ -1396,7 +1489,12 @@ export async function runSync(
 	if (artifactPathsResult && options.artifactConfig?.enabled !== false) {
 		result.artifactPaths = artifactPathsResult;
 		if (options.artifactConfig?.includeOutput !== false) {
-			writeArtifact(artifactPathsResult.outputPath, artifactOutputByResult.get(result) ?? result.finalOutput ?? "");
+			writeArtifact(artifactPathsResult.outputPath, formatOutputArtifactContent({
+				output: artifactOutputByResult.get(result) ?? result.finalOutput ?? "",
+				error: result.error,
+				transcriptPath: result.transcriptPath,
+				metadataPath: options.artifactConfig?.includeMetadata === false ? undefined : artifactPathsResult.metadataPath,
+			}));
 		}
 		if (options.maxOutput) {
 			const config = { ...DEFAULT_MAX_OUTPUT, ...options.maxOutput };
@@ -1435,11 +1533,12 @@ export async function runSync(
 				? { content: childWrittenOutput, path: options.outputPath, authoritative: options.outputMode === "file-only" }
 				: undefined,
 			cwd: options.cwd ?? runtimeCwd,
+			reportOptional: isAgentContractV1(options.agentContract),
 		});
 	}
 	const acceptanceFailure = acceptanceFailureMessage(result.acceptance);
 	stripAcceptanceReportsFromMessages(result.messages);
-	if (acceptanceFailure && result.acceptance.explicit && result.exitCode === 0 && !result.detached && !result.interrupted && !result.timedOut) {
+	if (acceptanceFailure && result.acceptance.explicit && result.exitCode === 0 && !result.detached && !result.interrupted && !result.timedOut && !isAgentContractV1(options.agentContract)) {
 		result.exitCode = 1;
 		result.error = result.error ? `${result.error}\n${acceptanceFailure}` : acceptanceFailure;
 		if (result.progress) {
@@ -1447,6 +1546,7 @@ export async function runSync(
 			result.progress.error = result.error;
 		}
 	}
+	if (isAgentContractV1(options.agentContract)) attachContractProjections(result);
 	persistResultMetadata(result);
 
 	return result;

package/src/runs/foreground/foreground-control.ts

@@ -0,0 +1,90 @@
+import type { AgentProgress, ForegroundChildControl, ForegroundRunControl } from "../../shared/types.ts";
+
+interface BeginForegroundChildInput {
+	index: number;
+	agent: string;
+	description?: string;
+	interrupt: () => boolean;
+}
+
+function copyProgress(target: ForegroundChildControl, progress: AgentProgress | undefined): void {
+	if (!progress) return;
+	target.currentActivityState = progress.activityState;
+	target.lastActivityAt = progress.lastActivityAt;
+	target.currentTool = progress.currentTool;
+	target.currentToolStartedAt = progress.currentToolStartedAt;
+	target.currentPath = progress.currentPath;
+	target.turnCount = progress.turnCount;
+	target.tokens = progress.tokens;
+	target.toolCount = progress.toolCount;
+}
+
+function syncCurrentChild(control: ForegroundRunControl, child: ForegroundChildControl): void {
+	control.currentAgent = child.agent;
+	control.currentIndex = child.index;
+	control.description = child.description;
+	control.currentActivityState = child.currentActivityState;
+	control.lastActivityAt = child.lastActivityAt;
+	control.currentTool = child.currentTool;
+	control.currentToolStartedAt = child.currentToolStartedAt;
+	control.currentPath = child.currentPath;
+	control.turnCount = child.turnCount;
+	control.tokens = child.tokens;
+	control.toolCount = child.toolCount;
+	control.interrupt = child.interrupt;
+	control.updatedAt = child.updatedAt;
+}
+
+function clearCurrentChild(control: ForegroundRunControl): void {
+	control.currentAgent = undefined;
+	control.currentIndex = undefined;
+	control.currentActivityState = undefined;
+	control.lastActivityAt = undefined;
+	control.currentTool = undefined;
+	control.currentToolStartedAt = undefined;
+	control.currentPath = undefined;
+	control.turnCount = undefined;
+	control.tokens = undefined;
+	control.toolCount = undefined;
+	control.interrupt = undefined;
+}
+
+export function beginForegroundChild(control: ForegroundRunControl, input: BeginForegroundChildInput): void {
+	const now = Date.now();
+	const child: ForegroundChildControl = {
+		index: input.index,
+		agent: input.agent,
+		...(input.description ? { description: input.description } : {}),
+		startedAt: now,
+		updatedAt: now,
+	};
+	child.interrupt = () => {
+		if (!input.interrupt()) return false;
+		child.currentActivityState = undefined;
+		child.updatedAt = Date.now();
+		syncCurrentChild(control, child);
+		return true;
+	};
+	control.activeChildren ??= new Map();
+	control.activeChildren.set(input.index, child);
+	syncCurrentChild(control, child);
+}
+
+export function updateForegroundChild(control: ForegroundRunControl, index: number, progress: AgentProgress | undefined): void {
+	const child = control.activeChildren?.get(index);
+	if (!child) return;
+	copyProgress(child, progress);
+	child.updatedAt = Date.now();
+	syncCurrentChild(control, child);
+}
+
+export function finishForegroundChild(control: ForegroundRunControl, index: number): void {
+	control.activeChildren?.delete(index);
+	if (control.currentIndex === index) {
+		const next = [...(control.activeChildren?.values() ?? [])]
+			.sort((left, right) => right.updatedAt - left.updatedAt || left.index - right.index)[0];
+		if (next) syncCurrentChild(control, next);
+		else clearCurrentChild(control);
+	}
+	control.updatedAt = Date.now();
+}