pi-subagents 0.35.0 → 0.36.0

package/src/intercom/native-supervisor-channel.ts

@@ -447,6 +447,43 @@ function requestMatchesContext(request: SupervisorRequest, state: Pick<SubagentS
 	return Boolean(currentSessionId && request.orchestratorSessionId === currentSessionId);
 }
 
+function rememberedForegroundChild(request: SupervisorRequest, state: SubagentState) {
+	const run = state.foregroundRuns?.get(request.runId);
+	const child = run?.children.find((candidate) => candidate.index === request.childIndex && candidate.agent === request.agent)
+		?? run?.children[request.childIndex];
+	return run && child ? { run, child } : undefined;
+}
+
+function markForegroundSupervisorAttention(request: SupervisorRequest, state: SubagentState): void {
+	const remembered = rememberedForegroundChild(request, state);
+	if (!remembered || remembered.child.status !== "detached") return;
+	const updatedAt = Date.now();
+	remembered.run.updatedAt = updatedAt;
+	remembered.child.activityState = "needs_attention";
+	remembered.child.lastActivityAt = request.createdAt;
+	remembered.child.currentTool = "contact_supervisor";
+	remembered.child.currentToolStartedAt = request.createdAt;
+	remembered.child.updatedAt = updatedAt;
+}
+
+function clearForegroundSupervisorAttention(request: SupervisorRequest, pending: Map<string, PendingSupervisorRequest>, state: SubagentState): void {
+	if ([...pending.values()].some((candidate) =>
+		candidate.expectsReply
+		&& candidate.runId === request.runId
+		&& candidate.agent === request.agent
+		&& candidate.childIndex === request.childIndex
+	)) return;
+	const remembered = rememberedForegroundChild(request, state);
+	if (!remembered || remembered.child.status !== "detached" || remembered.child.currentTool !== "contact_supervisor") return;
+	const updatedAt = Date.now();
+	remembered.run.updatedAt = updatedAt;
+	remembered.child.activityState = undefined;
+	remembered.child.lastActivityAt = updatedAt;
+	remembered.child.currentTool = undefined;
+	remembered.child.currentToolStartedAt = undefined;
+	remembered.child.updatedAt = updatedAt;
+}
+
 function removeRequestFile(file: string): void {
 	try {
 		fs.rmSync(file, { force: true });
@@ -465,10 +502,8 @@ function requestExpiresAt(request: SupervisorRequest, now: number): number {
 
 function requestRunInactive(request: SupervisorRequest, state: SubagentState): boolean {
 	if (state.foregroundControls.has(request.runId)) return false;
-	const foregroundRun = state.foregroundRuns?.get(request.runId);
-	const foregroundChild = foregroundRun?.children.find((child) => child.index === request.childIndex && child.agent === request.agent)
-		?? foregroundRun?.children[request.childIndex];
-	if (foregroundChild) return foregroundChild.status !== "detached";
+	const foreground = rememberedForegroundChild(request, state);
+	if (foreground) return foreground.child.status !== "detached";
 
 	const asyncJob = state.asyncJobs.get(request.runId);
 	if (!asyncJob) return false;
@@ -580,6 +615,7 @@ function buildParentIntercomTool(pending: Map<string, PendingSupervisorRequest>,
 				const request = resolvePendingRequest(pending, input);
 				writeReply(request, input.message ?? "");
 				pending.delete(request.id);
+				clearForegroundSupervisorAttention(request, pending, state);
 				return { content: [{ type: "text", text: `Replied to supervisor request ${request.id}.` }], details: { replyTo: request.id, runId: request.runId, agent: request.agent } };
 			}
 			if (input.action === "send" || input.action === "ask") {
@@ -629,7 +665,10 @@ export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentS
 				continue;
 			}
 			seenFiles.add(file);
-			if (request.expectsReply) pending.set(request.id, request);
+			if (request.expectsReply) {
+				pending.set(request.id, request);
+				markForegroundSupervisorAttention(request, state);
+			}
 			else {
 				removeRequestFile(request.requestFile);
 			}
@@ -645,7 +684,7 @@ export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentS
 					agent: request.agent,
 					childIndex: request.childIndex,
 				},
-			});
+			}, { triggerTurn: true });
 			if (request.expectsReply) {
 				(pi as { events?: IntercomEventBus }).events?.emit(INTERCOM_DETACH_REQUEST_EVENT, {
 					requestId: request.id,

package/src/intercom/result-intercom.ts

@@ -5,6 +5,7 @@ import {
 	type IntercomEventBus,
 	type NestedRunSummary,
 	type PublicNestedRunSummary,
+	type ParallelHandoffReference,
 	type SingleResult,
 	type SubagentResultIntercomChild,
 	type SubagentResultIntercomPayload,
@@ -179,6 +180,7 @@ interface GroupedResultIntercomMessageInput {
 	asyncId?: string;
 	asyncDir?: string;
 	chainSteps?: number;
+	parallelHandoff?: ParallelHandoffReference;
 }
 
 function asyncResumeGuidance(input: {
@@ -207,6 +209,7 @@ function formatSubagentResultIntercomMessage(input: {
 	asyncId?: string;
 	asyncDir?: string;
 	chainSteps?: number;
+	parallelHandoff?: ParallelHandoffReference;
 }): string {
 	const counts = countStatuses(input.children);
 	const lines: string[] = [
@@ -222,6 +225,7 @@ function formatSubagentResultIntercomMessage(input: {
 	}
 	if (input.asyncId) lines.push(`Async id: ${input.asyncId}`);
 	if (input.asyncDir) lines.push(`Async dir: ${input.asyncDir}`);
+	if (input.parallelHandoff) lines.push(`Parallel handoff: ${input.parallelHandoff.path}`);
 	const resumeGuidance = asyncResumeGuidance(input);
 	if (resumeGuidance) lines.push(resumeGuidance);
 	if (input.children.some((child) => child.intercomTarget)) {
@@ -266,6 +270,7 @@ export function buildSubagentResultIntercomPayload(input: GroupedResultIntercomM
 		...(input.asyncId ? { asyncId: input.asyncId } : {}),
 		...(input.asyncDir ? { asyncDir: input.asyncDir } : {}),
 		...(typeof input.chainSteps === "number" ? { chainSteps: input.chainSteps } : {}),
+		...(input.parallelHandoff ? { parallelHandoff: input.parallelHandoff } : {}),
 		...(firstChild?.agent ? { agent: firstChild.agent } : {}),
 		...(firstChild?.index !== undefined ? { index: firstChild.index } : {}),
 		...(firstChild?.artifactPath ? { artifactPath: firstChild.artifactPath } : {}),
@@ -352,6 +357,8 @@ export function formatSubagentResultReceipt(input: {
 		`Children: ${formatStatusCounts(counts)}`,
 	];
 
+	if (input.payload.parallelHandoff) lines.push(`Parallel handoff: ${input.payload.parallelHandoff.path}`);
+
 	const artifacts = input.payload.children.filter((child) => typeof child.artifactPath === "string");
 	if (artifacts.length > 0) {
 		lines.push("Artifacts:");

package/src/runs/background/async-execution.ts

@@ -15,6 +15,7 @@ import { applyThinkingSuffix } from "../shared/pi-args.ts";
 import { injectOutputPathSystemPrompt, injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { buildChainInstructions, isDynamicParallelStep, isParallelStep, resolveStepBehavior, suppressProgressForReadOnlyTask, writeInitialProgressFile, type ChainStep, type ResolvedStepBehavior, type SequentialStep, type StepOverrides } from "../../shared/settings.ts";
 import type { RunnerStep } from "../shared/parallel-utils.ts";
+import type { ContextMode } from "../shared/context-mode.ts";
 import { resolvePiPackageRoot } from "../shared/pi-spawn.ts";
 import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../../agents/skills.ts";
 import { buildAgentMemoryInjection } from "../../agents/agent-memory.ts";
@@ -29,8 +30,10 @@ import { createStructuredOutputRuntime } from "../shared/structured-output.ts";
 import { resolveEffectiveAcceptance } from "../shared/acceptance.ts";
 import {
 	type AcceptanceInput,
+	type AgentContract,
 	type ArtifactConfig,
 	type Details,
+	type JsonSchemaObject,
 	type MaxOutputConfig,
 	type NestedRouteInfo,
 	type ResolvedControlConfig,
@@ -131,9 +134,11 @@ interface AsyncChainParams {
 	artifactConfig: ArtifactConfig;
 	shareEnabled: boolean;
 	sessionRoot?: string;
+	agentContract?: AgentContract;
 	chainSkills?: string[];
 	sessionFilesByFlatIndex?: (string | undefined)[];
 	thinkingOverridesByFlatIndex?: (AgentConfig["thinking"] | undefined)[];
+	contextForAgent?: (agentName: string) => ContextMode;
 	progressDir?: string;
 	dynamicFanoutMaxItems?: number;
 	maxSubagentDepth: number;
@@ -170,10 +175,13 @@ interface AsyncSingleParams {
 	sessionDir?: string;
 	sessionFile?: string;
 	revivalLease?: SessionLeaseRequest;
+	context?: ContextMode;
 	skills?: string[];
 	output?: string | boolean;
 	outputMode?: "inline" | "file-only";
 	outputBaseDir?: string;
+	agentContract?: AgentContract;
+	structuredOutputSchema?: JsonSchemaObject;
 	modelOverride?: string;
 	thinkingOverride?: AgentConfig["thinking"];
 	availableModels?: AvailableModelInfo[];
@@ -212,7 +220,9 @@ export interface AsyncRunnerStepBuildParams {
 	chainSkills?: string[];
 	sessionFilesByFlatIndex?: (string | undefined)[];
 	thinkingOverridesByFlatIndex?: (AgentConfig["thinking"] | undefined)[];
+	contextForAgent?: (agentName: string) => ContextMode;
 	progressDir?: string;
+	agentContract?: AgentContract;
 	dynamicFanoutMaxItems?: number;
 	maxSubagentDepth: number;
 	waitToolEnabled?: boolean;
@@ -624,10 +634,13 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 		const thinkingOverride = flatIndex === undefined ? undefined : thinkingOverridesByFlatIndex?.[flatIndex];
 		const effectiveThinking = thinkingOverride ?? a.thinking;
 		const model = applyThinkingSuffix(primaryModel, effectiveThinking, thinkingOverride !== undefined);
+		const agentContract = s.agentContract ?? params.agentContract;
 		return {
 			parentSessionId: ctx.parentSessionId ?? ctx.currentSessionId,
 			agent: s.agent,
 			task,
+			...(params.contextForAgent ? { context: params.contextForAgent(s.agent) } : {}),
+			...(agentContract ? { agentContract } : {}),
 			phase: s.phase,
 			label: s.label,
 			outputName: s.as,
@@ -662,9 +675,11 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 				mode: resultMode,
 				async: true,
 				dynamic: false,
+				agentContract,
 			}),
 			acceptanceInput: s.acceptance,
 			acceptanceRole: a.acceptanceRole,
+			...(s.gateOn ? { gateOn: s.gateOn } : {}),
 			...(s.outputSchema ? { structuredOutputSchema: s.outputSchema } : {}),
 			...(s.outputSchema ? { structuredOutput: createStructuredOutputRuntime(s.outputSchema, path.join(asyncDir, "structured-output")) } : {}),
 			...(resolvedToolBudget.budget ? { toolBudget: resolvedToolBudget.budget } : {}),
@@ -707,7 +722,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 							}
 						}
 						const staticStep = nextFlatStep();
-						return buildSeqStep(t, staticStep.sessionFile, behaviorCwd, progressPrecreated, parallelBehaviors[taskIndex], staticStep.index, { stepIndex, taskIndex });
+						return buildSeqStep({ ...t, agentContract: t.agentContract ?? s.agentContract, gateOn: t.gateOn ?? s.gateOn }, staticStep.sessionFile, behaviorCwd, progressPrecreated, parallelBehaviors[taskIndex], staticStep.index, { stepIndex, taskIndex });
 					}),
 					concurrency: s.concurrency,
 					failFast: s.failFast,
@@ -724,7 +739,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 				}
 				const maxItems = s.expand.maxItems ?? params.dynamicFanoutMaxItems ?? 0;
 				const dynamicFlatSteps = Array.from({ length: maxItems }, () => nextFlatStep());
-				const parallel = buildSeqStep(s.parallel as SequentialStep, undefined, undefined, progressPrecreated, behavior, undefined, { stepIndex });
+				const parallel = buildSeqStep({ ...(s.parallel as SequentialStep), agentContract: s.parallel.agentContract ?? s.agentContract, gateOn: s.parallel.gateOn ?? s.gateOn }, undefined, undefined, progressPrecreated, behavior, undefined, { stepIndex });
 				return {
 					expand: s.expand,
 					parallel,
@@ -743,9 +758,12 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 						mode: resultMode,
 						async: true,
 						dynamicGroup: true,
+						agentContract: s.agentContract ?? params.agentContract,
 					}),
 					acceptanceInput: s.acceptance,
 					acceptanceRole: agent.acceptanceRole,
+					...(s.agentContract ?? params.agentContract ? { agentContract: s.agentContract ?? params.agentContract } : {}),
+					...(s.gateOn ? { gateOn: s.gateOn } : {}),
 				};
 			}
 			const staticStep = nextFlatStep();
@@ -844,7 +862,9 @@ export function executeAsyncChain(
 		chainSkills: params.chainSkills,
 		sessionFilesByFlatIndex,
 		thinkingOverridesByFlatIndex,
+		contextForAgent: params.contextForAgent,
 		progressDir: params.progressDir ?? (artifactsDir ? path.join(artifactsDir, "progress", id) : resultMode === "parallel" ? path.join(asyncDir, "progress") : undefined),
+		agentContract: params.agentContract,
 		outputBaseDir: artifactsDir ? path.join(artifactsDir, "outputs", id) : undefined,
 		dynamicFanoutMaxItems: params.dynamicFanoutMaxItems,
 		maxSubagentDepth,
@@ -1126,6 +1146,9 @@ export function executeAsyncSingle(
 	if (timeoutMs !== undefined && timeoutMs <= 0) return formatAsyncStartError("single", "The source run's absolute deadline expired before recovery could launch.");
 	const initialTurnBudget = params.turnBudget ? initialTurnBudgetState(params.turnBudget) : undefined;
 	const resolvedSessionDir = params.sessionDir ?? (sessionRoot ? path.join(sessionRoot, `async-${id}`) : undefined);
+	const structuredOutput = params.structuredOutputSchema
+		? createStructuredOutputRuntime(params.structuredOutputSchema, path.join(asyncDir, "structured-output"))
+		: undefined;
 	const resolvedAcceptance = resolveEffectiveAcceptance({
 		explicit: params.acceptance,
 		agentName: agent,
@@ -1133,10 +1156,12 @@ export function executeAsyncSingle(
 		task,
 		mode: "single",
 		async: true,
+		agentContract: params.agentContract,
 	});
 	const recoveryDescriptor: SteeringRecoveryDescriptor = {
 		version: 1,
 		sourceRunId: id,
+		...(params.agentContract ? { agentContract: params.agentContract } : {}),
 		agent,
 		...(sessionFile ? { sessionFile } : {}),
 		cwd: runnerCwd,
@@ -1158,7 +1183,8 @@ export function executeAsyncSingle(
 		...(agentConfig.memory ? { memory: { ...agentConfig.memory } } : {}),
 		...(outputPath ? { outputPath } : {}),
 		outputMode,
-		...(resolvedAcceptance ? { acceptance: resolvedAcceptance } : {}),
+		...(params.structuredOutputSchema ? { structuredOutputSchema: params.structuredOutputSchema } : {}),
+		...(params.acceptance !== undefined ? { acceptance: params.acceptance } : {}),
 		...(controlConfig ? { controlConfig } : {}),
 		...(deadlineAt !== undefined ? { absoluteDeadlineAt: deadlineAt } : {}),
 		...(params.turnBudget ? { initialTurnBudget: params.turnBudget } : {}),
@@ -1185,6 +1211,7 @@ export function executeAsyncSingle(
 						parentSessionId: ctx.parentSessionId ?? ctx.currentSessionId,
 						agent,
 						task: taskWithOutputInstruction,
+						...(params.context ? { context: params.context } : {}),
 						cwd: runnerCwd,
 						model,
 						thinking: resolveEffectiveThinking(model, effectiveThinking),
@@ -1206,7 +1233,10 @@ export function executeAsyncSingle(
 						sessionFile,
 						maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, agentConfig.maxSubagentDepth),
 						waitToolEnabled: params.waitToolEnabled,
+						...(params.agentContract ? { agentContract: params.agentContract } : {}),
 						effectiveAcceptance: resolvedAcceptance,
+						...(structuredOutput ? { structuredOutput } : {}),
+						...(params.structuredOutputSchema ? { structuredOutputSchema: params.structuredOutputSchema } : {}),
 						...(resolvedToolBudget.budget ? { toolBudget: resolvedToolBudget.budget } : {}),
 					},
 				],
@@ -1309,6 +1339,6 @@ export function executeAsyncSingle(
 
 	return {
 		content: [{ type: "text", text: formatAsyncStartedMessage(`Async: ${agent} [${id}]`, ctx.interactive === true) }],
-		details: { mode: "single", runId: id, results: [], asyncId: id, asyncDir, ...(timeoutMs !== undefined ? { timeoutMs, deadlineAt } : {}), ...(params.turnBudget ? { turnBudget: params.turnBudget } : {}), ...(params.toolBudget ? { toolBudget: params.toolBudget } : {}) },
+		details: { mode: "single", runId: id, results: [], asyncId: id, asyncDir, ...(params.context ? { context: params.context } : {}), ...(timeoutMs !== undefined ? { timeoutMs, deadlineAt } : {}), ...(params.turnBudget ? { turnBudget: params.turnBudget } : {}), ...(params.toolBudget ? { toolBudget: params.toolBudget } : {}) },
 	};
 }

package/src/runs/background/async-job-tracker.ts

@@ -91,6 +91,8 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			toolCount: run.toolCount,
 			steering: run.steering,
 			mode: run.mode,
+			context: run.context,
+			cwd: run.cwd,
 			agents: visibleSteps.map((step) => step.agent),
 			currentStep: run.currentStep,
 			chainStepCount: run.chainStepCount,
@@ -397,10 +399,12 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		state.asyncJobs.set(info.id, {
 			asyncId: info.id,
 			asyncDir,
+			...(typeof info.cwd === "string" ? { cwd: path.resolve(info.cwd) } : {}),
 			status: "queued",
 			pid: typeof info.pid === "number" ? info.pid : undefined,
 			...(typeof info.sessionId === "string" ? { sessionId: info.sessionId } : {}),
 			mode: info.mode ?? (info.chain ? "chain" : "single"),
+			description: info.goal ?? info.task,
 			agents,
 			chainStepCount: info.chainStepCount,
 			parallelGroups: validParallelGroups,

package/src/runs/background/async-resume.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { ASYNC_DIR, RESULTS_DIR, type AsyncStatus, type SteeringRecoveryDescriptor } from "../../shared/types.ts";
+import { ASYNC_DIR, RESULTS_DIR, type AcceptanceInput, type AsyncStatus, type SteeringRecoveryDescriptor } from "../../shared/types.ts";
 import type { AgentConfig } from "../../agents/agents.ts";
 import { validateAcceptanceInput } from "../shared/acceptance.ts";
 import { validateToolBudgetConfig } from "../shared/tool-budget.ts";
@@ -250,6 +250,21 @@ function validateStatusForResume(status: AsyncStatus | null, source: string): vo
 	}
 }
 
+function normalizeRecoveryAcceptance(value: unknown, descriptorPath: string): AcceptanceInput | undefined {
+	if (value && typeof value === "object" && !Array.isArray(value) && ("explicit" in value || "inferredReason" in value)) {
+		const { explicit, inferredReason: _inferredReason, ...publicAcceptance } = value as Record<string, unknown>;
+		if (explicit === false) return undefined;
+		if (publicAcceptance.level === "reviewed") {
+			publicAcceptance.level = "verified";
+			delete publicAcceptance.review;
+		}
+		value = publicAcceptance;
+	}
+	const errors = validateAcceptanceInput(value, "recoveryDescriptor.acceptance");
+	if (errors.length) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${errors.join(" ")}`);
+	return value as AcceptanceInput;
+}
+
 export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): SteeringRecoveryDescriptor | undefined {
 	if (!asyncDir) return undefined;
 	const descriptorPath = path.join(asyncDir, "recovery-descriptor.json");
@@ -263,9 +278,9 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': expected an object.`);
 	const parsed = value as Record<string, unknown>;
 	const allowedFields = new Set([
-		"version", "sourceRunId", "agent", "sessionFile", "cwd", "model", "fallbackModels", "thinking", "tools", "extensions",
+		"version", "sourceRunId", "agentContract", "agent", "sessionFile", "cwd", "model", "fallbackModels", "thinking", "tools", "extensions",
 		"subagentOnlyExtensions", "mcpDirectTools", "systemPrompt", "systemPromptMode", "inheritProjectContext", "inheritSkills", "skills",
-		"skillPath", "agentFilePath", "completionGuard", "memory", "outputPath", "outputMode", "acceptance", "sessionDir", "artifactConfig",
+		"skillPath", "agentFilePath", "completionGuard", "memory", "outputPath", "outputMode", "structuredOutputSchema", "acceptance", "sessionDir", "artifactConfig",
 		"artifactsDir", "maxOutput", "controlConfig", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share",
 	]);
 	for (const field of Object.keys(parsed)) {
@@ -276,6 +291,11 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 		if (typeof parsed[field] !== "string" || !(parsed[field] as string).trim()) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a non-empty string.`);
 	}
 	if (parsed.version !== 1) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': version must be 1.`);
+	if (parsed.agentContract !== undefined) {
+		if (!parsed.agentContract || typeof parsed.agentContract !== "object" || Array.isArray(parsed.agentContract)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': agentContract must be an object.`);
+		const contract = parsed.agentContract as Record<string, unknown>;
+		if (contract.version !== 1 || Object.keys(contract).some((key) => key !== "version")) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': agentContract must be { version: 1 }.`);
+	}
 	if (parsed.systemPromptMode !== "append" && parsed.systemPromptMode !== "replace") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': systemPromptMode is invalid.`);
 	if (parsed.outputMode !== "inline" && parsed.outputMode !== "file-only") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': outputMode is invalid.`);
 	for (const field of ["inheritProjectContext", "inheritSkills", "share"] as const) {
@@ -291,6 +311,7 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 		if (parsed[field] !== undefined && (typeof parsed[field] !== "string" || !(parsed[field] as string).trim())) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a non-empty string.`);
 	}
 	if (parsed.completionGuard !== undefined && typeof parsed.completionGuard !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': completionGuard must be a boolean.`);
+	if (parsed.structuredOutputSchema !== undefined && (!parsed.structuredOutputSchema || typeof parsed.structuredOutputSchema !== "object" || Array.isArray(parsed.structuredOutputSchema))) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': structuredOutputSchema must be an object.`);
 	if (parsed.memory !== undefined) {
 		if (!parsed.memory || typeof parsed.memory !== "object" || Array.isArray(parsed.memory)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': memory must be an object.`);
 		const memory = parsed.memory as Record<string, unknown>;
@@ -335,8 +356,9 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 		if (!Array.isArray(control.notifyChannels) || control.notifyChannels.some((item) => item !== "event" && item !== "async" && item !== "intercom")) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.notifyChannels is invalid.`);
 	}
 	if (parsed.acceptance !== undefined) {
-		const errors = validateAcceptanceInput(parsed.acceptance, "recoveryDescriptor.acceptance");
-		if (errors.length) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${errors.join(" ")}`);
+		const acceptance = normalizeRecoveryAcceptance(parsed.acceptance, descriptorPath);
+		if (acceptance === undefined) delete parsed.acceptance;
+		else parsed.acceptance = acceptance;
 	}
 	return parsed as unknown as SteeringRecoveryDescriptor;
 }

package/src/runs/background/async-status.ts

@@ -7,11 +7,13 @@ import { readStatus } from "../../shared/utils.ts";
 import { attachRootChildrenToSteps, buildNestedRouteIndex, type NestedRoute, projectNestedEvents } from "../shared/nested-events.ts";
 import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
 import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-groups.ts";
+import { contextModeLabel, summarizeContextModes, type ContextMode, type ContextSummary } from "../shared/context-mode.ts";
 import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
 
 interface AsyncRunStepSummary {
 	index: number;
 	agent: string;
+	context?: ContextMode;
 	label?: string;
 	phase?: string;
 	outputName?: string;
@@ -35,12 +37,19 @@ interface AsyncRunStepSummary {
 	model?: string;
 	thinking?: string;
 	attemptedModels?: string[];
+	sessionFile?: string;
+	transcriptPath?: string;
 	error?: string;
 	timedOut?: boolean;
 	stopped?: boolean;
 	turnBudget?: TurnBudgetState;
 	turnBudgetExceeded?: boolean;
 	wrapUpRequested?: boolean;
+	acceptance?: AsyncJobStep["acceptance"];
+	agentContract?: AsyncJobStep["agentContract"];
+	execution?: AsyncJobStep["execution"];
+	review?: AsyncJobStep["review"];
+	effects?: AsyncJobStep["effects"];
 	children?: NestedRunSummary[];
 }
 
@@ -59,6 +68,7 @@ export interface AsyncRunSummary {
 	toolCount?: number;
 	steering?: SteeringStatus;
 	mode: SubagentRunMode;
+	context?: ContextSummary;
 	cwd?: string;
 	startedAt: number;
 	lastUpdate?: number;
@@ -92,6 +102,7 @@ interface AsyncRunListOptions {
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	now?: () => number;
 	reconcile?: boolean;
+	runId?: string;
 }
 
 function getErrorMessage(error: unknown): string {
@@ -117,6 +128,45 @@ function isAsyncRunDir(root: string, entry: string): boolean {
 	}
 }
 
+type TargetedAsyncRunResolution =
+	| { kind: "exact"; id: string }
+	| { kind: "scan" }
+	| { kind: "reject" };
+
+/**
+ * Resolve an exact targeted run without following a run-directory symlink or
+ * accepting a path whose canonical location escaped the async root.
+ */
+export function resolveTargetedAsyncRun(asyncDirRoot: string, id: string, sessionId?: string): TargetedAsyncRunResolution {
+	if (!id || id === "." || id === ".." || path.basename(id) !== id) return { kind: "reject" };
+	const asyncDir = path.join(asyncDirRoot, id);
+	let entryStat: fs.Stats;
+	try {
+		entryStat = fs.lstatSync(asyncDir);
+	} catch (error) {
+		if (isNotFoundError(error)) return { kind: "scan" };
+		throw new Error(`Failed to inspect async run path '${asyncDir}': ${getErrorMessage(error)}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+	if (!entryStat.isDirectory() || entryStat.isSymbolicLink()) return { kind: "reject" };
+	try {
+		const canonicalRoot = fs.realpathSync(asyncDirRoot);
+		const canonicalDir = fs.realpathSync(asyncDir);
+		if (canonicalDir !== canonicalRoot && !canonicalDir.startsWith(`${canonicalRoot}${path.sep}`)) return { kind: "reject" };
+	} catch (error) {
+		if (isNotFoundError(error)) return { kind: "reject" };
+		throw new Error(`Failed to resolve async run path '${asyncDir}': ${getErrorMessage(error)}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+	if (sessionId !== undefined) {
+		const status = readStatus(asyncDir);
+		if (status?.sessionId !== sessionId) return { kind: "scan" };
+	}
+	return { kind: "exact", id };
+}
+
 function outputFileMtime(outputFile: string | undefined): number | undefined {
 	if (!outputFile) return undefined;
 	try {
@@ -163,6 +213,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 		return {
 			index,
 			agent: step.agent,
+			...(step.context ? { context: step.context } : {}),
 			...(step.label ? { label: step.label } : {}),
 			...(step.phase ? { phase: step.phase } : {}),
 			...(step.outputName ? { outputName: step.outputName } : {}),
@@ -186,12 +237,19 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 			...(step.model ? { model: step.model } : {}),
 			...(step.thinking ? { thinking: step.thinking } : {}),
 			...(step.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
+			...(step.sessionFile ? { sessionFile: step.sessionFile } : {}),
+			...(step.transcriptPath ? { transcriptPath: step.transcriptPath } : {}),
 			...(step.error ? { error: step.error } : {}),
 			...(step.timedOut !== undefined ? { timedOut: step.timedOut } : {}),
 			...(step.stopped !== undefined ? { stopped: step.stopped } : {}),
 			...(step.turnBudget ? { turnBudget: step.turnBudget } : {}),
 			...(step.turnBudgetExceeded !== undefined ? { turnBudgetExceeded: step.turnBudgetExceeded } : {}),
 			...(step.wrapUpRequested !== undefined ? { wrapUpRequested: step.wrapUpRequested } : {}),
+			...(step.acceptance ? { acceptance: step.acceptance } : {}),
+			...(step.agentContract ? { agentContract: step.agentContract } : {}),
+			...(step.execution ? { execution: step.execution } : {}),
+			...(step.review ? { review: step.review } : {}),
+			...(step.effects ? { effects: step.effects } : {}),
 			...(step.children?.length ? { children: step.children } : {}),
 		};
 	});
@@ -211,6 +269,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 		toolCount: status.toolCount,
 		steering: status.steering,
 		mode: status.mode,
+		...(summarizeContextModes(summarizedSteps.map((step) => step.context)) ? { context: summarizeContextModes(summarizedSteps.map((step) => step.context)) } : {}),
 		cwd: status.cwd,
 		startedAt: status.startedAt,
 		lastUpdate: status.lastUpdate,
@@ -264,7 +323,19 @@ function sortRuns(runs: AsyncRunSummary[]): AsyncRunSummary[] {
 export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions = {}): AsyncRunSummary[] {
 	let entries: string[];
 	try {
-		entries = fs.readdirSync(asyncDirRoot).filter((entry) => isAsyncRunDir(asyncDirRoot, entry));
+		if (options.runId !== undefined) {
+			const resolution = resolveTargetedAsyncRun(asyncDirRoot, options.runId, options.sessionId);
+			entries = resolution.kind === "exact"
+				? [resolution.id]
+				: resolution.kind === "scan"
+					? fs.readdirSync(asyncDirRoot).filter((entry) =>
+						(entry === options.runId || entry.startsWith(options.runId!))
+						&& resolveTargetedAsyncRun(asyncDirRoot, entry, options.sessionId).kind === "exact"
+					)
+					: [];
+		} else {
+			entries = fs.readdirSync(asyncDirRoot).filter((entry) => isAsyncRunDir(asyncDirRoot, entry));
+		}
 	} catch (error) {
 		if (isNotFoundError(error)) return [];
 		throw new Error(`Failed to list async runs in '${asyncDirRoot}': ${getErrorMessage(error)}`, {
@@ -333,8 +404,9 @@ function formatActivityFacts(input: { activityState?: ActivityState; lastActivit
 
 function formatStepLine(step: AsyncRunStepSummary): string {
 	const display = step.label ? `${step.label} (${step.agent})` : step.agent;
+	const context = contextModeLabel(step.context);
 	const phase = step.phase ? `[${step.phase}] ` : "";
-	const parts = [`${step.index + 1}. ${phase}${display}`, step.status];
+	const parts = [`${step.index + 1}. ${phase}${display}${context ? ` ${context}` : ""}`, step.status];
 	const activity = formatActivityFacts(step);
 	if (activity) parts.push(activity);
 	const modelThinking = formatModelThinking(step.model, step.thinking);
@@ -375,7 +447,8 @@ function formatRunHeader(run: AsyncRunSummary): string {
 	const cwd = run.cwd ? shortenPath(run.cwd) : shortenPath(run.asyncDir);
 	const activity = formatActivityFacts(run);
 	const pending = run.pendingAppends ? ` | ${run.pendingAppends} pending append${run.pendingAppends === 1 ? "" : "s"}` : "";
-	return `${run.id} | ${run.state}${activity ? ` | ${activity}` : ""} | ${run.mode} | ${stepLabel}${pending} | ${cwd}`;
+	const context = contextModeLabel(run.context);
+	return `${run.id} | ${run.state}${activity ? ` | ${activity}` : ""} | ${run.mode}${context ? ` ${context}` : ""} | ${stepLabel}${pending} | ${cwd}`;
 }
 
 export function formatAsyncRunList(runs: AsyncRunSummary[], heading = "Active async runs"): string {

package/src/runs/background/chain-append.ts

@@ -131,6 +131,7 @@ export function consumeChainAppendRequests(asyncDir: string): ChainAppendRequest
 function statusStepForTask(task: RunnerSubagentStep): StatusStep {
 	return {
 		agent: task.agent,
+		...(task.context ? { context: task.context } : {}),
 		phase: task.phase,
 		label: task.label,
 		outputName: task.outputName,
@@ -151,6 +152,7 @@ function statusStepsForRunnerStep(step: RunnerStep): StatusStep[] {
 	if (isDynamicRunnerGroup(step)) {
 		return [{
 			agent: `expand:${step.parallel.agent}`,
+			...(step.parallel.context ? { context: step.parallel.context } : {}),
 			phase: step.phase ?? step.parallel.phase,
 			label: step.label ?? step.parallel.label ?? `Dynamic fanout (${step.collect.as})`,
 			outputName: step.collect.as,

package/src/runs/background/completion-batcher.ts

@@ -89,8 +89,8 @@ export interface CompletionBatcher<T> {
 	push(item: T): void;
 	/** Emit any held items immediately as a single group. */
 	flush(): void;
-	/** Clear timers without emitting. */
-	dispose(): void;
+	/** Clear timers and return items that were never emitted. */
+	dispose(): T[];
 }
 
 /**
@@ -109,7 +109,7 @@ export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>)
 				options.emit([item]);
 			},
 			flush() {},
-			dispose() {},
+			dispose() { return []; },
 		};
 	}
 
@@ -160,7 +160,9 @@ export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>)
 		flush: emitGroup,
 		dispose() {
 			clearTimers();
+			const abandoned = pending;
 			pending = [];
-		},
+			return abandoned;
+		}
 	};
 }

package/src/runs/background/completion-dedupe.ts

@@ -20,9 +20,9 @@ function asFiniteNumber(value: unknown): number | undefined {
 }
 
 export function buildCompletionKey(data: CompletionDataLike, fallback: string): string {
-	const id = asNonEmptyString(data.id);
-	if (id) return `id:${id}`;
 	const sessionId = asNonEmptyString(data.sessionId) ?? "no-session";
+	const id = asNonEmptyString(data.id);
+	if (id) return `session:${sessionId}:id:${id}`;
 	const agent = asNonEmptyString(data.agent) ?? "unknown";
 	const timestamp = asFiniteNumber(data.timestamp);
 	const taskIndex = asFiniteNumber(data.taskIndex);
@@ -52,12 +52,3 @@ export function markSeenWithTtl(seen: Map<string, number>, key: string, now: num
 	seen.set(key, now);
 	return false;
 }
-
-export function getGlobalSeenMap(storeKey: string): Map<string, number> {
-	const globalStore = globalThis as Record<string, unknown>;
-	const existing = globalStore[storeKey];
-	if (existing instanceof Map) return existing as Map<string, number>;
-	const map = new Map<string, number>();
-	globalStore[storeKey] = map;
-	return map;
-}