pi-subagents 0.36.0 → 0.37.1

package/src/api/preflight.ts

@@ -0,0 +1,399 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { discoverAgents, discoverAgentsAll, type AgentConfig, type AgentScope, type AgentSource } from "../agents/agents.ts";
+import { resolveExecutionAgentScope } from "../agents/agent-scope.ts";
+import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../agents/skills.ts";
+import { buildAgentMemoryInjection } from "../agents/agent-memory.ts";
+import { buildModelCandidates, resolveEffectiveSubagentModel, type AvailableModelInfo, type ParentModel } from "../runs/shared/model-fallback.ts";
+import { applyThinkingSuffix, resolvePiLaunchToolPlan, type PiLaunchToolPlan } from "../runs/shared/pi-args.ts";
+import { injectOutputPathSystemPrompt, normalizeSingleOutputOverride, resolveSingleOutputPath } from "../runs/shared/single-output.ts";
+import { getArtifactPaths, getArtifactsDir } from "../shared/artifacts.ts";
+import { resolveEffectiveThinking } from "../shared/model-info.ts";
+import { SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, type ArtifactDirPreference, type ArtifactPaths, type JsonSchemaObject, type OutputMode } from "../shared/types.ts";
+import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "../runs/shared/capability-ceiling.ts";
+import { appendTurnBudgetSystemPrompt } from "../runs/shared/turn-budget.ts";
+import type { ResolvedTurnBudget } from "../shared/types.ts";
+import type { ResolvedMcpDirectToolSelection } from "../runs/shared/mcp-direct-tool-allowlist.ts";
+import { resolveStepBehavior } from "../shared/settings.ts";
+import { agentDefinitionDigest, AGENT_DEFINITION_PROJECTION_VERSION, launchBindingDigest } from "../shared/launch-contract.ts";
+import { ASYNC_DIR, RESULTS_DIR, TEMP_ROOT_DIR } from "../shared/types.ts";
+import { processTerminalCandidatePath, processTerminalPath } from "../runs/background/process-terminal.ts";
+import { nestedResultsPath } from "../runs/shared/nested-events.ts";
+
+export const SUBAGENT_LAUNCH_CONTRACT_VERSION = 2 as const;
+
+export type SubagentLaunchContractReasonCode =
+	| "missing_agent"
+	| "ambiguous_agent"
+	| "missing_skill"
+	| "denied_required_tool"
+	| "invalid_artifact_dir"
+	| "invalid_cwd"
+	| "unsupported_mode";
+
+export interface SubagentLaunchContractDiagnostic {
+	code: SubagentLaunchContractReasonCode | "host_required" | "snapshot_warning";
+	severity: "error" | "warning" | "host-required";
+	message: string;
+}
+
+export interface SubagentLaunchContractInput {
+	agent: string;
+	cwd: string;
+	task?: string;
+	agentScope?: AgentScope;
+	context?: "fresh" | "fork";
+	model?: string;
+	thinking?: string | false;
+	parentModel?: ParentModel;
+	availableModels?: ReadonlyArray<AvailableModelInfo | { provider: string; id: string; fullId?: string; reasoning?: boolean }>;
+	preferredProvider?: string;
+	skill?: string | string[] | boolean;
+	output?: string | boolean;
+	outputMode?: OutputMode;
+	outputSchema?: JsonSchemaObject;
+	turnBudget?: ResolvedTurnBudget;
+	artifacts?: boolean;
+	artifactDir?: ArtifactDirPreference;
+	parentSessionFile?: string | null;
+	sessionRoot?: string;
+	sessionDir?: string;
+	runId?: string;
+	/** Root run id supplied by a host when projecting nested async lifecycle paths. */
+	nestedRootRunId?: string;
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	inheritedCapabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+}
+
+export interface SubagentLaunchContractAgentCandidate {
+	name: string;
+	localName?: string;
+	packageName?: string;
+	source: AgentSource;
+	filePath: string;
+	disabled?: boolean;
+	selected: boolean;
+}
+
+export interface SubagentLaunchContractAgent {
+	name: string;
+	localName?: string;
+	packageName?: string;
+	source: AgentSource;
+	filePath: string;
+	definitionProjectionVersion: typeof AGENT_DEFINITION_PROJECTION_VERSION;
+	definitionDigest: string;
+	shadowedCandidates: SubagentLaunchContractAgentCandidate[];
+}
+
+export interface SubagentLaunchContractSkills {
+	requested: string[];
+	resolved: Array<{ name: string; path: string; source: string }>;
+	missing: string[];
+}
+
+export interface SubagentLaunchContractTools {
+	requestedBuiltin: string[];
+	declaredBuiltin: string[];
+	effectiveAllowlist: string[];
+	explicitAllowlist: boolean;
+	requiredChildTools: string[];
+	internalTools: string[];
+	mcp: ResolvedMcpDirectToolSelection[];
+	effectiveMcpTools: string[];
+	toolExtensionPaths: string[];
+	runtimeExtensions: string[];
+	configuredExtensions: string[];
+	extensionArgs: string[];
+	disableAmbientExtensions: boolean;
+	fanoutAuthorized: boolean;
+	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
+	capabilityAudit?: SubagentCapabilityAudit;
+}
+
+export interface SubagentLaunchContractRoots {
+	cwd: string;
+	sessionRoot?: string;
+	sessionDir?: string;
+	sessionFile?: string;
+	artifactsDir?: string;
+	artifactPaths?: ArtifactPaths;
+	outputPath?: string;
+	lifecycle?: {
+		asyncDir: string;
+		resultPath: string;
+		statusPath: string;
+		eventsPath: string;
+		processTerminalPath: string;
+		processTerminalCandidatePath: string;
+	};
+}
+
+export interface SubagentLaunchContract {
+	version: typeof SUBAGENT_LAUNCH_CONTRACT_VERSION;
+	runId: string;
+	agent: SubagentLaunchContractAgent;
+	context: "fresh" | "fork";
+	model?: string;
+	modelCandidates: string[];
+	thinking?: string;
+	systemPromptMode: AgentConfig["systemPromptMode"];
+	inheritProjectContext: boolean;
+	inheritSkills: boolean;
+	skills: SubagentLaunchContractSkills;
+	tools: SubagentLaunchContractTools;
+	roots: SubagentLaunchContractRoots;
+	protocol: {
+		lifecycleArtifactVersion: number;
+		packageVersion: string;
+	};
+	diagnostics: SubagentLaunchContractDiagnostic[];
+	/** Digest of the resolved child inputs, recomputed by execution paths. */
+	launchContractDigest: string;
+	digest: string;
+}
+
+export type SubagentLaunchContractResult =
+	| { ok: true; contract: SubagentLaunchContract }
+	| { ok: false; code: SubagentLaunchContractReasonCode; message: string; diagnostics: SubagentLaunchContractDiagnostic[] };
+
+function packageVersion(): string {
+	const packagePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+	const parsed = JSON.parse(fs.readFileSync(packagePath, "utf-8")) as { version?: unknown };
+	if (typeof parsed.version !== "string" || !parsed.version.trim()) {
+		throw new Error(`Invalid package version in '${packagePath}'.`);
+	}
+	return parsed.version;
+}
+
+function stableJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+	if (value && typeof value === "object") {
+		return `{${Object.entries(value as Record<string, unknown>)
+			.filter(([, entry]) => entry !== undefined)
+			.sort(([a], [b]) => a.localeCompare(b))
+			.map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+			.join(",")}}`;
+	}
+	return JSON.stringify(value);
+}
+
+function digestContract(contract: Omit<SubagentLaunchContract, "digest">): string {
+	return createHash("sha256").update(stableJson(contract)).digest("hex");
+}
+
+function normalizeAvailableModels(models: SubagentLaunchContractInput["availableModels"]): AvailableModelInfo[] {
+	return (models ?? []).map((model) => ({ ...model, fullId: model.fullId ?? `${model.provider}/${model.id}` }));
+}
+
+function candidateList(inputAgent: string, selected: AgentConfig | undefined, cwd: string): SubagentLaunchContractAgentCandidate[] {
+	const all = discoverAgentsAll(cwd);
+	return [...all.builtin, ...all.package, ...all.user, ...all.project]
+		.filter((agent) => agent.name === inputAgent || agent.localName === inputAgent)
+		.map((agent) => ({
+			name: agent.name,
+			...(agent.localName ? { localName: agent.localName } : {}),
+			...(agent.packageName ? { packageName: agent.packageName } : {}),
+			source: agent.source,
+			filePath: agent.filePath,
+			...(agent.disabled === true ? { disabled: true } : {}),
+			selected: Boolean(selected && agent.filePath === selected.filePath && agent.name === selected.name),
+		}));
+}
+
+export async function resolveSubagentLaunchContract(input: SubagentLaunchContractInput): Promise<SubagentLaunchContractResult> {
+	const diagnostics: SubagentLaunchContractDiagnostic[] = [];
+	const effectiveCwd = path.resolve(input.cwd);
+	try {
+		if (!fs.statSync(effectiveCwd).isDirectory()) {
+			return { ok: false, code: "invalid_cwd", message: `cwd '${effectiveCwd}' is not a directory.`, diagnostics };
+		}
+	} catch (error) {
+		const detail = error instanceof Error ? ` ${error.message}` : "";
+		return { ok: false, code: "invalid_cwd", message: `cwd '${effectiveCwd}' is not a directory.${detail}`, diagnostics };
+	}
+	if (input.context !== undefined && input.context !== "fresh" && input.context !== "fork") {
+		return { ok: false, code: "unsupported_mode", message: `Unsupported context '${String(input.context)}'; expected 'fresh' or 'fork'.`, diagnostics };
+	}
+	if (input.artifactDir !== undefined && input.artifactDir !== "project" && input.artifactDir !== "session" && input.artifactDir !== "temp") {
+		return { ok: false, code: "invalid_artifact_dir", message: `Unsupported artifactDir '${String(input.artifactDir)}'; expected 'project', 'session', or 'temp'.`, diagnostics };
+	}
+	if (input.context === "fork") {
+		diagnostics.push({ code: "host_required", severity: "host-required", message: "Exact fork session branching and fork-thinking downgrade checks require Pi host session and model-registry snapshots." });
+	}
+	const scope = resolveExecutionAgentScope(input.agentScope);
+	const discovered = discoverAgents(effectiveCwd, scope);
+	const matches = discovered.agents.filter((agent) => agent.name === input.agent || agent.localName === input.agent);
+	if (matches.length === 0) {
+		return { ok: false, code: "missing_agent", message: `Unknown agent: ${input.agent}`, diagnostics };
+	}
+	if (matches.length > 1) {
+		return { ok: false, code: "ambiguous_agent", message: `Ambiguous agent: ${input.agent}`, diagnostics };
+	}
+	const agent = matches[0]!;
+	const runId = input.runId ?? "preflight";
+	const skillInput = normalizeSkillInput(input.skill);
+	const outputOverride = normalizeSingleOutputOverride(input.output, agent.output);
+	const behavior = resolveStepBehavior(agent, {
+		...(outputOverride !== undefined ? { output: outputOverride } : {}),
+		...(input.outputMode !== undefined ? { outputMode: input.outputMode } : {}),
+		...(skillInput !== undefined ? { skills: skillInput } : {}),
+		...(input.model !== undefined ? { model: input.model } : {}),
+	});
+	const requestedSkills = behavior.skills === false ? [] : behavior.skills;
+	const resolvedSkills = resolveSkillsWithFallback(
+		requestedSkills,
+		effectiveCwd,
+		effectiveCwd,
+		agent.skillPath,
+		agent.filePath ? path.dirname(agent.filePath) : effectiveCwd,
+	);
+	if (resolvedSkills.missing.includes("pi-subagents")) {
+		return { ok: false, code: "missing_skill", message: "The pi-subagents orchestration skill is not child-injectable.", diagnostics };
+	}
+	if (resolvedSkills.missing.length > 0) diagnostics.push({ code: "missing_skill", severity: "error", message: `Missing skills: ${resolvedSkills.missing.join(", ")}` });
+
+	const availableModels = normalizeAvailableModels(input.availableModels);
+	const preferredProvider = input.preferredProvider ?? input.parentModel?.provider;
+	const primaryModel = resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, { scope: discovered.modelScope });
+	const effectiveThinkingConfig = input.thinking !== undefined ? input.thinking : agent.thinking;
+	const model = applyThinkingSuffix(primaryModel, effectiveThinkingConfig, input.thinking !== undefined);
+	const modelCandidates = buildModelCandidates(primaryModel, agent.fallbackModels, availableModels, preferredProvider, { scope: discovered.modelScope })
+		.map((candidate) => applyThinkingSuffix(candidate, effectiveThinkingConfig, input.thinking !== undefined) ?? candidate);
+	let toolPlan: PiLaunchToolPlan;
+	try {
+		toolPlan = resolvePiLaunchToolPlan({
+			tools: agent.tools,
+			extensions: agent.extensions,
+			subagentOnlyExtensions: agent.subagentOnlyExtensions,
+			mcpDirectTools: agent.mcpDirectTools,
+			cwd: effectiveCwd,
+			requireReadTool: resolvedSkills.resolved.length > 0,
+			structuredOutput: Boolean(input.outputSchema),
+			capabilityCeiling: input.capabilityCeiling,
+			inheritedCapabilityCeiling: input.inheritedCapabilityCeiling,
+		});
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		diagnostics.push({ code: "denied_required_tool", severity: "error", message });
+		return { ok: false, code: "denied_required_tool", message, diagnostics };
+	}
+	const artifactsEnabled = input.artifacts !== false;
+	const artifactsDir = artifactsEnabled ? getArtifactsDir(input.parentSessionFile ?? null, effectiveCwd, input.artifactDir ?? "project") : undefined;
+	const artifactPaths = artifactsDir ? getArtifactPaths(artifactsDir, runId, agent.name, 0) : undefined;
+	const outputPath = resolveSingleOutputPath(behavior.output, effectiveCwd, effectiveCwd, artifactsDir ? path.join(artifactsDir, "outputs", runId) : undefined);
+	const sessionRoot = input.sessionDir ? path.resolve(input.sessionDir) : input.sessionRoot ? path.join(path.resolve(input.sessionRoot), runId) : undefined;
+	const sessionDir = sessionRoot ? path.join(sessionRoot, "run-0") : undefined;
+	const lifecycleAsyncDir = input.nestedRootRunId
+		? path.join(TEMP_ROOT_DIR, "nested-subagent-runs", input.nestedRootRunId, runId)
+		: path.join(ASYNC_DIR, runId);
+	const lifecycleResultPath = input.nestedRootRunId
+		? nestedResultsPath(input.nestedRootRunId, runId)
+		: path.join(RESULTS_DIR, `${runId}.json`);
+	if (!sessionDir) diagnostics.push({ code: "host_required", severity: "host-required", message: "No sessionRoot/sessionDir was supplied; exact child session paths require the Pi host session-root policy." });
+	if (input.availableModels === undefined && (input.model || agent.model || input.parentModel)) {
+		diagnostics.push({ code: "host_required", severity: "host-required", message: "No availableModels snapshot was supplied; model resolution may differ from the active Pi host registry." });
+	}
+	if (resolvedSkills.missing.length > 0) {
+		return { ok: false, code: "missing_skill", message: `Missing skills: ${resolvedSkills.missing.join(", ")}`, diagnostics };
+	}
+	let effectiveSystemPrompt = agent.systemPrompt?.trim() ?? "";
+	if (resolvedSkills.resolved.length > 0) {
+		const skillInjection = buildSkillInjection(resolvedSkills.resolved);
+		effectiveSystemPrompt = effectiveSystemPrompt ? `${effectiveSystemPrompt}\n\n${skillInjection}` : skillInjection;
+	}
+	const memoryInjection = buildAgentMemoryInjection(agent, effectiveCwd);
+	if (memoryInjection) effectiveSystemPrompt = effectiveSystemPrompt ? `${effectiveSystemPrompt}\n\n${memoryInjection}` : memoryInjection;
+	effectiveSystemPrompt = injectOutputPathSystemPrompt(effectiveSystemPrompt, outputPath, agent);
+	const turnBudget = input.turnBudget ?? agent.defaultTurnBudget;
+	effectiveSystemPrompt = appendTurnBudgetSystemPrompt(effectiveSystemPrompt, turnBudget);
+	const candidates = candidateList(input.agent, agent, effectiveCwd);
+	const shadowedCandidates = candidates.filter((candidate) => !candidate.selected);
+	const definitionDigest = agentDefinitionDigest(agent);
+	const contractBase: Omit<SubagentLaunchContract, "digest"> = {
+		version: SUBAGENT_LAUNCH_CONTRACT_VERSION,
+		runId,
+		agent: {
+			name: agent.name,
+			...(agent.localName ? { localName: agent.localName } : {}),
+			...(agent.packageName ? { packageName: agent.packageName } : {}),
+			source: agent.source,
+			filePath: agent.filePath,
+			definitionProjectionVersion: AGENT_DEFINITION_PROJECTION_VERSION,
+			definitionDigest,
+			shadowedCandidates,
+		},
+		context: input.context ?? agent.defaultContext ?? "fresh",
+		...(model ? { model } : {}),
+		modelCandidates,
+		...(resolveEffectiveThinking(model, effectiveThinkingConfig) ? { thinking: resolveEffectiveThinking(model, effectiveThinkingConfig) } : {}),
+		systemPromptMode: agent.systemPromptMode,
+		inheritProjectContext: agent.inheritProjectContext,
+		inheritSkills: agent.inheritSkills,
+		skills: {
+			requested: requestedSkills,
+			resolved: resolvedSkills.resolved.map((skill) => ({ name: skill.name, path: skill.path, source: skill.source })),
+			missing: resolvedSkills.missing,
+		},
+		tools: {
+			requestedBuiltin: toolPlan.requestedBuiltinTools,
+			declaredBuiltin: toolPlan.declaredBuiltinTools,
+			effectiveAllowlist: toolPlan.effectiveToolAllowlist,
+			explicitAllowlist: toolPlan.explicitToolAllowlist,
+			requiredChildTools: toolPlan.requiredChildTools,
+			internalTools: toolPlan.internalTools,
+			mcp: toolPlan.effectiveMcpSelections,
+			effectiveMcpTools: toolPlan.effectiveMcpTools,
+			toolExtensionPaths: toolPlan.toolExtensionPaths,
+			runtimeExtensions: toolPlan.runtimeExtensions,
+			configuredExtensions: toolPlan.configuredExtensions,
+			extensionArgs: toolPlan.extensionArgs,
+			disableAmbientExtensions: toolPlan.disableAmbientExtensions,
+			fanoutAuthorized: toolPlan.fanoutAuthorized,
+			...(toolPlan.capabilityCeiling ? { capabilityCeiling: toolPlan.capabilityCeiling } : {}),
+			...(toolPlan.capabilityAudit ? { capabilityAudit: toolPlan.capabilityAudit } : {}),
+		},
+		roots: {
+			cwd: effectiveCwd,
+			...(sessionRoot ? { sessionRoot } : {}),
+			...(sessionDir ? { sessionDir, sessionFile: path.join(sessionDir, "session.jsonl") } : {}),
+			...(artifactsDir ? { artifactsDir } : {}),
+			...(artifactPaths ? { artifactPaths } : {}),
+			...(outputPath ? { outputPath } : {}),
+			lifecycle: {
+				asyncDir: lifecycleAsyncDir,
+				resultPath: lifecycleResultPath,
+				statusPath: path.join(lifecycleAsyncDir, "status.json"),
+				eventsPath: path.join(lifecycleAsyncDir, "events.jsonl"),
+				processTerminalPath: processTerminalPath(lifecycleAsyncDir),
+				processTerminalCandidatePath: processTerminalCandidatePath(lifecycleAsyncDir),
+			},
+		},
+		protocol: {
+			lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
+			packageVersion: packageVersion(),
+		},
+		diagnostics,
+		launchContractDigest: launchBindingDigest({
+			task: input.task ?? "",
+			definitionDigest,
+			...(model ? { model } : {}),
+			modelCandidates,
+			...(resolveEffectiveThinking(model, effectiveThinkingConfig) ? { thinking: resolveEffectiveThinking(model, effectiveThinkingConfig) } : {}),
+			systemPrompt: effectiveSystemPrompt,
+			systemPromptMode: agent.systemPromptMode,
+			inheritProjectContext: agent.inheritProjectContext,
+			inheritSkills: agent.inheritSkills,
+			skills: requestedSkills,
+			tools: toolPlan.effectiveToolAllowlist,
+			extensions: toolPlan.extensionArgs,
+			mcpDirectTools: toolPlan.effectiveMcpTools,
+			...(outputPath ? { outputPath } : {}),
+			outputMode: input.outputMode ?? "inline",
+			...(input.outputSchema ? { structuredOutputSchema: input.outputSchema } : {}),
+		}),
+	};
+	return { ok: true, contract: { ...contractBase, digest: digestContract(contractBase) } };
+}

package/src/extension/index.ts

@@ -26,7 +26,7 @@ import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import { cleanupOldChainDirs } from "../shared/settings.ts";
 import { clearLegacyResultAnimationTimer, renderSubagentResult } from "../tui/render.ts";
 import { openSubagentFleet } from "../tui/fleet.ts";
-import { SubagentFleetStatus } from "../tui/fleet-status.ts";
+import { SubagentFleetStatus, resolveFleetViewPlacement } from "../tui/fleet-status.ts";
 import { SubagentParams } from "./schemas.ts";
 import { validateChainInput } from "./chain-validation.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
@@ -47,6 +47,7 @@ import { drainOutstandingWork } from "../runs/background/auto-drain.ts";
 import registerSubagentNotify, { parseSubagentNotifyContent, type SubagentNotifyDetails } from "../runs/background/notify.ts";
 import { formatSteeringNotice, handleSubagentSteeringNotice, SUBAGENT_STEERING_MESSAGE_TYPE, type SubagentSteeringMessageDetails } from "./steering-notices.ts";
 import { SUBAGENT_CHILD_ENV, SUBAGENT_PARENT_SESSION_ENV } from "../runs/shared/pi-args.ts";
+import { resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
 import { loadConfig } from "./config.ts";
 import { buildSubagentToolDescription } from "./tool-description.ts";
@@ -142,10 +143,13 @@ function createSlashResultComponent(
 }
 
 class SubagentControlNoticeComponent implements Component {
-	constructor(
-		private readonly details: SubagentControlMessageDetails,
-		private readonly theme: ExtensionContext["ui"]["theme"],
-	) {}
+	private readonly details: SubagentControlMessageDetails;
+	private readonly theme: ExtensionContext["ui"]["theme"];
+
+	constructor(details: SubagentControlMessageDetails, theme: ExtensionContext["ui"]["theme"]) {
+		this.details = details;
+		this.theme = theme;
+	}
 
 	invalidate(): void {}
 
@@ -192,6 +196,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const waitToolConfig = resolveWaitToolConfig(config.waitTool);
 	const asyncByDefault = config.asyncByDefault === true;
 	const fleetViewEnabled = config.fleetView !== false;
+	const fleetViewPlacement = resolveFleetViewPlacement(config.fleetViewPlacement);
 	const asyncWidgetEnabled = config.asyncWidget === true || (!fleetViewEnabled && config.asyncWidget !== false);
 	const tempArtifactsDir = getArtifactsDir(null);
 	cleanupAllArtifactDirs(DEFAULT_ARTIFACT_CONFIG.cleanupDays);
@@ -235,14 +240,17 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			const ctx = state.lastUiContext;
 			if (!ctx?.hasUI) return;
 			await openSubagentFleet(ctx, state, { initialKey: itemKey });
-		})
+		}, { placement: fleetViewPlacement })
 		: undefined;
 	const { startResultWatcher, primeExistingResults, stopResultWatcher } = createResultWatcher(
 		pi,
 		state,
 		RESULTS_DIR,
 		10 * 60 * 1000,
-		{ notifier: completionNotifier },
+		{
+			notifier: completionNotifier,
+			deliverIntercomResults: config.intercomBridge?.resultDelivery !== false,
+		},
 	);
 
 	const runtimeCleanup = () => {
@@ -277,6 +285,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			}
 			return executorExecute(randomUUID(), params, signal, undefined, ctx);
 		},
+		resolveCapabilityCeiling: (sessionId) => resolveCurrentSubagentCapabilityCeiling(sessionId),
 	});
 	const executor = createSubagentExecutor({
 		pi,

package/src/extension/rpc.ts

@@ -6,11 +6,14 @@ import { resolveAsyncRunLocation } from "../runs/background/async-resume.ts";
 import { deliverStopRequest } from "../runs/background/control-channel.ts";
 import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.ts";
 import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
+import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import {
 	type Details,
 	ASYNC_DIR,
 	RESULTS_DIR,
 	SUBAGENT_ASYNC_COMPLETE_EVENT,
+	SUBAGENT_PROCESS_TERMINAL_EVENT,
+	SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
 } from "../shared/types.ts";
 import { readStatus } from "../shared/utils.ts";
 import { SubagentParams } from "./schemas.ts";
@@ -21,7 +24,7 @@ export const SUBAGENT_RPC_REQUEST_EVENT = "subagents:rpc:v1:request";
 export const SUBAGENT_RPC_READY_EVENT = "subagents:rpc:v1:ready";
 export const SUBAGENT_RPC_REPLY_EVENT_PREFIX = "subagents:rpc:v1:reply:";
 
-export const SUBAGENT_RPC_METHODS = ["ping", "status", "spawn", "steer", "interrupt", "stop"] as const;
+export const SUBAGENT_RPC_METHODS = ["ping", "status", "spawn", "steer", "interrupt", "stop", "resume"] as const;
 export type SubagentRpcMethod = typeof SUBAGENT_RPC_METHODS[number];
 
 export interface SubagentRpcRequestEnvelope {
@@ -181,12 +184,15 @@ function pingData(ctx: ExtensionContext | null) {
 			nonRecoveringSteer: true,
 			interrupt: true,
 			stop: true,
+			resume: true,
+			processTerminalProof: { version: 1, lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION },
 		},
 		events: {
 			ready: SUBAGENT_RPC_READY_EVENT,
 			request: SUBAGENT_RPC_REQUEST_EVENT,
 			replyPrefix: SUBAGENT_RPC_REPLY_EVENT_PREFIX,
 			asyncComplete: SUBAGENT_ASYNC_COMPLETE_EVENT,
+			processTerminal: SUBAGENT_PROCESS_TERMINAL_EVENT,
 		},
 		session: sessionData(ctx),
 	};
@@ -234,6 +240,24 @@ function steerParams(params: unknown): SubagentParamsLike {
 	};
 }
 
+function resumeParams(params: unknown): SubagentParamsLike {
+	const input = assertRecordParams(params, "resume");
+	if (typeof input.message !== "string" || !input.message.trim())
+		throw new SubagentRpcError("invalid_params", "RPC resume requires a non-empty message.");
+	const target = normalizeTargetParams(input, "resume");
+	if (!target.id && !target.runId && !target.dir) throw new SubagentRpcError("invalid_params", "RPC resume requires id, runId, or dir.");
+	if (input.output !== undefined && (typeof input.output !== "string" || !input.output.trim()))
+		throw new SubagentRpcError("invalid_params", "RPC resume output must be a non-empty path.");
+	if (input.outputMode !== undefined && input.outputMode !== "file-only")
+		throw new SubagentRpcError("invalid_params", "RPC resume supports only file-only output mode.");
+	return {
+		action: "resume",
+		...target,
+		message: input.message.trim(),
+		...(typeof input.output === "string" ? { output: input.output.trim(), outputMode: "file-only" } : {}),
+	};
+}
+
 function stopAsyncRun(
 	params: unknown,
 	options: RegisterSubagentRpcBridgeOptions,
@@ -253,7 +277,7 @@ function stopAsyncRun(
 		throw new SubagentRpcError("not_found", "Async run not found or already completed; stop requires a live async run directory.");
 	}
 
-	const currentSessionId = ctx.sessionManager.getSessionId();
+	const currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
 	const initialStatus = readStatus(location.asyncDir);
 	const initialRunId = initialStatus?.runId ?? location.resolvedId ?? path.basename(location.asyncDir);
 	if (!initialStatus) throw new SubagentRpcError("not_found", `Status file not found for async run '${initialRunId}'.`);
@@ -320,6 +344,9 @@ async function handleRequest(
 	if (request.method === "stop") {
 		return stopAsyncRun(request.params, options, ctx);
 	}
+	if (request.method === "resume") {
+		return executeChecked(options, ctx, request.requestId, request.method, resumeParams(request.params));
+	}
 	throw new SubagentRpcError("unsupported_method", `Unsupported subagent RPC method: ${String(request.method)}`);
 }
 

package/src/extension/schemas.ts

@@ -67,11 +67,17 @@ const JsonSchemaObject = Type.Unsafe({
 
 const AcceptanceOverride = Type.Unsafe({
 	anyOf: [
-		{ type: "string", enum: ["auto", "attested", "checked", "verified", "reviewed"] },
+		{ type: "string", enum: ["auto", "attested", "checked", "verified"] },
+		{
+			type: "string",
+			enum: ["reviewed"],
+			deprecated: true,
+			description: "Invalid as an explicit policy. Recognized only so preflight can explain that reviewed is an achieved status.",
+		},
 		{ type: "boolean", enum: [false] },
 		{ type: "object", additionalProperties: true },
 	],
-	description: "Optional acceptance policy. In the current/default contract, omitted means auto-inferred; verified requires configured runtime commands. With agentContract.version=1, omitted means not requested and acceptance failures are reported separately from execution.",
+	description: "Optional acceptance policy. For reviewer/read-only calls, omit acceptance. Evidence levels end at verified; require independent review with acceptance.review.required. The value reviewed is an achieved status and is accepted by the schema only for actionable preflight recovery. In the current/default contract, omitted means auto-inferred. With agentContract.version=1, omitted means not requested and acceptance failures are reported separately from execution.",
 });
 
 const AgentContractOverride = Type.Object({
@@ -284,8 +290,8 @@ const SubagentParamsSchema = Type.Object({
 	})),
 	chainDir: Type.Optional(Type.String({ description: "Persistent chain artifact directory; defaults to user-scoped temp storage." })),
 	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
-	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Optional run-level timeout in ms for foreground and async/background runs. Alias of maxRuntimeMs." })),
-	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias of timeoutMs for optional run-level timeout in foreground and async/background runs." })),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Timeout for foreground and async/background runs; foreground defaults to 30m absent call/agent. Alias maxRuntimeMs." })),
+	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias timeoutMs for foreground and async/background runs; foreground defaults to 30m absent call/agent." })),
 	turnBudget: Type.Optional(TurnBudgetOverride),
 	toolBudget: Type.Optional(ToolBudgetOverride),
 	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),

package/src/extension/tool-description.ts

@@ -23,7 +23,8 @@ EXECUTION (use exactly ONE mode):
 • PARALLEL: { tasks: [{agent,task,count?,output?,reads?,progress?}, ...], concurrency?: number, worktree?: true } - concurrent execution (worktree: isolate each task in a git worktree)
 • Optional context: { context: "fresh" | "fork" } (explicit value overrides every child; when omitted, each requested agent uses its own defaultContext, otherwise "fresh"; inspect agent defaults via { action: "list" })
 • Fork thinking: model strings accept a thinking suffix (provider/model:off|minimal|low|medium|high|xhigh|max). Forking over a parent transcript that carries signed Anthropic thinking blocks forces thinking off only when a child's effective primary or fallback model resolves to the Anthropic provider or anthropic-messages API; unresolved models are treated conservatively. The result notes affected children, including on failures. Use fresh context when an Anthropic child needs thinking.
-• Optional timeout: { timeoutMs } or { maxRuntimeMs } sets a run-level max runtime for foreground and async/background runs
+• Optional timeout: { timeoutMs } or { maxRuntimeMs } sets a run-level max runtime for foreground and async/background runs; foreground defaults to 30 minutes only when neither value nor an agent timeout is provided
+• Acceptance: omit acceptance for reviewer/read-only calls. Evidence levels end at verified. Use acceptance.review.required to require independent review of a writer result. Never request acceptance:"reviewed"; reviewed is achieved only after an independent reviewer result.
 • If { action: "list" } shows proactive skill subagent suggestions, consider a small fresh-context fanout for broad tasks where one of those skills would materially help
 
 CHAIN TEMPLATE VARIABLES (use in task strings):
@@ -79,7 +80,8 @@ export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = `To delegate work, call with {
 EXECUTE:
 • Before execution, call { action: "list" }; run only executable/non-disabled configured agents/chains.
 • SINGLE {agent, task?}; PARALLEL {tasks:[{agent,task,count?,output?,reads?,progress?}], concurrency?, worktree?}; CHAIN {chain:[{agent,task?},{parallel:[...]}]}.
-• context can be "fresh" or "fork"; omitted uses each agent defaultContext, otherwise fresh. timeoutMs/maxRuntimeMs apply to foreground and async/background runs.
+• context can be "fresh" or "fork"; omitted uses each agent defaultContext, otherwise fresh. timeoutMs/maxRuntimeMs apply to foreground and async/background runs; foreground defaults to 30 minutes only when neither value nor an agent timeout is provided.
+• Omit acceptance for reviewer/read-only calls. Evidence levels end at verified; use acceptance.review.required for independent writer review. reviewed is an achieved status, never an explicit input.
 • Chain templates may use {task}, {previous}, {chain_dir}, and named outputs. Parallel worktree isolation requires a clean git repo.
 • Chain example: { chain: [{agent:"agent-a", task:"Analyze {task}"}, {parallel: [{agent:"agent-b", task:"Check {previous}", count: 3}]}] }
 • If list shows proactive skill subagent suggestions, use a small fresh-context fanout only when the task is broad enough.

package/src/intercom/intercom-bridge.ts

@@ -32,6 +32,7 @@ Do not use contact_supervisor or intercom for routine completion handoffs. If no
 export interface IntercomBridgeState {
 	active: boolean;
 	mode: IntercomBridgeMode;
+	resultDelivery: boolean;
 	orchestratorTarget?: string;
 	extensionDir: string;
 	instruction: string;
@@ -78,11 +79,12 @@ export function resolveIntercomBridgeMode(value: unknown): IntercomBridgeMode {
 
 function resolveIntercomBridgeConfig(value: ExtensionConfig["intercomBridge"]): Required<IntercomBridgeConfig> {
 	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		return { mode: "always", instructionFile: "" };
+		return { mode: "always", instructionFile: "", resultDelivery: true };
 	}
 	return {
 		mode: resolveIntercomBridgeMode(value.mode),
 		instructionFile: typeof value.instructionFile === "string" ? value.instructionFile : "",
+		resultDelivery: value.resultDelivery !== false,
 	};
 }
 
@@ -146,11 +148,12 @@ export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): Interc
 	);
 	const reason = inactiveReason(mode, input.context, orchestratorTarget);
 	if (reason || !orchestratorTarget) {
-		return { active: false, mode, extensionDir: NATIVE_INTERCOM_EXTENSION_DIR, instruction: defaultInstruction };
+		return { active: false, mode, resultDelivery: config.resultDelivery, extensionDir: NATIVE_INTERCOM_EXTENSION_DIR, instruction: defaultInstruction };
 	}
 	return {
 		active: true,
 		mode,
+		resultDelivery: config.resultDelivery,
 		orchestratorTarget,
 		extensionDir: NATIVE_INTERCOM_EXTENSION_DIR,
 		instruction: buildIntercomBridgeInstruction(orchestratorTarget, resolveInstructionTemplate(config.instructionFile, settingsDir)),