pi-subagents 0.40.0 → 0.41.0

package/src/api/delegation.ts

@@ -1,8 +1,7 @@
-export const SUBAGENT_DELEGATION_PROTOCOL_VERSION = 1 as const;
-export const SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION = 2 as const;
-
-// This is the established extension-to-extension transport. The public API
-// intentionally reuses it instead of adding a second event protocol.
+// This is the established extension-to-extension transport. The structured
+// delegation API intentionally reuses it instead of adding a second event
+// protocol. Unstructured payloads on the same events remain the legacy
+// prompt-template bridge while we validate whether any integrations still use it.
 export const SUBAGENT_DELEGATION_REQUEST_EVENT = "prompt-template:subagent:request";
 export const SUBAGENT_DELEGATION_STARTED_EVENT = "prompt-template:subagent:started";
 export const SUBAGENT_DELEGATION_UPDATE_EVENT = "prompt-template:subagent:update";
@@ -20,114 +19,36 @@ export interface SubagentDelegationToolBudget {
 	block?: string[] | "*";
 }
 
-export interface SubagentDelegationAgentContract {
-	version: 1;
-}
-
 export type SubagentDelegationJsonSchemaObject = Record<string, unknown>;
 
-export interface SubagentDelegationExecutionResult {
-	status: "completed" | "failed" | "paused" | "stopped" | "detached";
-	success: boolean;
-	exitCode: number;
-	error?: string;
-	interrupted?: boolean;
-	timedOut?: boolean;
-	stopped?: boolean;
-	detached?: boolean;
-}
-
-export interface SubagentDelegationReviewResult {
-	status: "not-requested" | "review-required" | "reviewed" | "blockers";
-	findings?: Array<{ severity: "blocker" | "non-blocking"; file?: string; issue: string; rationale: string }>;
-}
-
-export interface SubagentDelegationEffectsResult {
-	fileMutation?: {
-		status: "not-requested" | "not-applicable" | "observed" | "missing";
-		expected: boolean;
-		attempted: boolean;
-		message?: string;
-	};
-}
-
-export type SubagentDelegationAcceptanceEvidence =
-	| "changed-files"
-	| "tests-added"
-	| "commands-run"
-	| "validation-output"
-	| "residual-risks"
-	| "no-staged-files"
-	| "diff-summary"
-	| "review-findings"
-	| "manual-notes";
-
-export interface SubagentDelegationAcceptanceCriterion {
-	id: string;
-	must: string;
-	evidence?: SubagentDelegationAcceptanceEvidence[];
-	severity?: "required" | "recommended";
-}
-
-export interface SubagentDelegationAcceptanceVerifyCommand {
-	id: string;
-	command: string;
-	timeoutMs?: number;
-	cwd?: string;
-	env?: Record<string, string>;
-	allowFailure?: boolean;
-}
-
-export interface SubagentDelegationAcceptanceReview {
-	agent?: string;
-	focus?: string;
-	required?: boolean;
-}
-
-interface SubagentDelegationAcceptanceFields {
-	criteria?: Array<string | SubagentDelegationAcceptanceCriterion>;
-	evidence?: SubagentDelegationAcceptanceEvidence[];
-	verify?: SubagentDelegationAcceptanceVerifyCommand[];
-	review?: SubagentDelegationAcceptanceReview | false;
-	stopRules?: string[];
-}
-
-export type SubagentDelegationAcceptanceConfig = SubagentDelegationAcceptanceFields & (
-	| { level: "none"; reason: string }
-	| { level?: "auto" | "attested" | "checked" | "verified"; reason?: string }
-);
+export type SubagentDelegationThinking = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 
-export type SubagentDelegationAcceptance =
-	| "auto"
-	| "attested"
-	| "checked"
-	| "verified"
-	| false
-	| SubagentDelegationAcceptanceConfig;
+export type SubagentDelegationResultRequest =
+	| { kind: "text" }
+	| { kind: "structured"; schema: SubagentDelegationJsonSchemaObject };
 
 export interface SubagentDelegationRequest {
-	version: typeof SUBAGENT_DELEGATION_PROTOCOL_VERSION;
 	requestId: string;
+	ownerRunId: string;
+	nodeId: string;
 	agent: string;
 	task: string;
 	context: "fresh" | "fork";
 	cwd: string;
 	model?: string;
+	thinking?: SubagentDelegationThinking;
 	timeoutMs?: number;
 	turnBudget?: SubagentDelegationTurnBudget;
 	toolBudget?: SubagentDelegationToolBudget;
 	skill?: string | string[] | boolean;
-	output?: string | boolean;
-	outputMode?: "inline" | "file-only";
-	outputSchema?: SubagentDelegationJsonSchemaObject;
-	agentContract?: SubagentDelegationAgentContract;
-	acceptance?: SubagentDelegationAcceptance;
 	artifacts?: boolean;
+	result: SubagentDelegationResultRequest;
 }
 
 export interface SubagentDelegationStarted {
-	version: typeof SUBAGENT_DELEGATION_PROTOCOL_VERSION;
 	requestId: string;
+	ownerRunId: string;
+	nodeId: string;
 }
 
 export interface SubagentDelegationUpdate extends SubagentDelegationStarted {
@@ -154,102 +75,14 @@ export type SubagentDelegationStatus =
 	| "structured_output_failed"
 	| "acceptance_failed"
 	| "invalid_request"
-	| "unavailable_context";
-
-export type SubagentDelegationAcceptanceStatus =
-	| "pending"
-	| "not-required"
-	| "claimed"
-	| "attested"
-	| "checked"
-	| "verified"
-	| "review-required"
-	| "reviewed"
-	| "accepted"
-	| "rejected";
-
-export interface SubagentDelegationAcceptanceResult {
-	status: SubagentDelegationAcceptanceStatus;
-	evidenceStatus: Exclude<SubagentDelegationAcceptanceStatus, "review-required" | "reviewed" | "accepted">;
-	explicit: boolean;
-}
-
-export interface SubagentDelegationResponse extends SubagentDelegationStarted {
-	status: SubagentDelegationStatus;
-	error?: string;
-	runId?: string;
-	childIndex?: number;
-	agent?: string;
-	model?: string;
-	exitCode?: number;
-	execution?: SubagentDelegationExecutionResult;
-	output?: string;
-	outputPath?: string;
-	sessionFile?: string;
-	acceptance?: SubagentDelegationAcceptanceResult;
-	review?: SubagentDelegationReviewResult;
-	effects?: SubagentDelegationEffectsResult;
-	turns?: number;
-	toolCount?: number;
-	durationMs?: number;
-	tokens?: number;
-	warnings?: string[];
-}
+	| "unavailable_context"
+	| "duplicate_node";
 
-export interface SubagentDelegationCancel extends SubagentDelegationStarted {}
-
-export type SubagentDelegationV2Thinking = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
-
-export type SubagentDelegationV2ResultRequest =
-	| { kind: "text" }
-	| { kind: "structured"; schema: SubagentDelegationJsonSchemaObject };
-
-export interface SubagentDelegationV2Request {
-	version: typeof SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION;
-	requestId: string;
-	ownerRunId: string;
-	nodeId: string;
-	agent: string;
-	task: string;
-	context: "fresh" | "fork";
-	cwd: string;
-	model?: string;
-	thinking?: SubagentDelegationV2Thinking;
-	timeoutMs?: number;
-	turnBudget?: SubagentDelegationTurnBudget;
-	toolBudget?: SubagentDelegationToolBudget;
-	skill?: string | string[] | boolean;
-	artifacts?: boolean;
-	result: SubagentDelegationV2ResultRequest;
-}
-
-export interface SubagentDelegationV2Started {
-	version: typeof SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION;
-	requestId: string;
-	ownerRunId: string;
-	nodeId: string;
-}
-
-export interface SubagentDelegationV2Update extends SubagentDelegationV2Started {
-	runId?: string;
-	currentTool?: string;
-	currentToolArgs?: string;
-	recentOutput?: string;
-	recentOutputLines?: string[];
-	recentTools?: Array<{ tool: string; args: string }>;
-	model?: string;
-	toolCount?: number;
-	durationMs?: number;
-	tokens?: number;
-}
-
-export type SubagentDelegationV2Status = SubagentDelegationStatus | "duplicate_node";
-
-export type SubagentDelegationV2Value =
+export type SubagentDelegationValue =
 	| { kind: "text"; text: string }
 	| { kind: "structured"; value: unknown };
 
-export interface SubagentDelegationV2Usage {
+export interface SubagentDelegationUsage {
 	input: number;
 	output: number;
 	cacheRead: number;
@@ -260,8 +93,8 @@ export interface SubagentDelegationV2Usage {
 	durationMs: number;
 }
 
-export interface SubagentDelegationV2TerminalResponse extends SubagentDelegationV2Started {
-	status: Exclude<SubagentDelegationV2Status, "invalid_request">;
+export interface SubagentDelegationTerminalResponse extends SubagentDelegationStarted {
+	status: Exclude<SubagentDelegationStatus, "invalid_request">;
 	error?: string;
 	runId?: string;
 	agent?: string;
@@ -269,13 +102,12 @@ export interface SubagentDelegationV2TerminalResponse extends SubagentDelegation
 	thinking?: string;
 	exitCode?: number;
 	launchContractDigest?: string;
-	result?: SubagentDelegationV2Value;
-	usage?: SubagentDelegationV2Usage;
+	result?: SubagentDelegationValue;
+	usage?: SubagentDelegationUsage;
 }
 
-/** A malformed V2 request can only be correlated by the valid identity fields it supplied. */
-export interface SubagentDelegationV2InvalidResponse {
-	version: typeof SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION;
+/** A malformed structured request can only be correlated by the valid identity fields it supplied. */
+export interface SubagentDelegationInvalidResponse {
 	requestId: string;
 	ownerRunId?: string;
 	nodeId?: string;
@@ -283,6 +115,6 @@ export interface SubagentDelegationV2InvalidResponse {
 	error?: string;
 }
 
-export type SubagentDelegationV2Response = SubagentDelegationV2TerminalResponse | SubagentDelegationV2InvalidResponse;
+export type SubagentDelegationResponse = SubagentDelegationTerminalResponse | SubagentDelegationInvalidResponse;
 
-export interface SubagentDelegationV2Cancel extends SubagentDelegationV2Started {}
+export interface SubagentDelegationCancel extends SubagentDelegationStarted {}

package/src/api/external-runs.ts

@@ -0,0 +1,129 @@
+export const EXTERNAL_RUN_REGISTRY_VERSION = 1;
+export const EXTERNAL_RUN_REGISTRY_KEY = "pi-subagents.external-runs.v1";
+
+const MAX_PROVIDERS = 100;
+const MAX_RUNS_PER_PROVIDER = 10_000;
+const MAX_TEXT_LENGTH = 4_096;
+
+export type ExternalRunState = "running" | "completed" | "failed" | "stopped";
+export type ExternalRunCompletionReason = "exit" | "timeout" | "user-kill" | "auto-close-quiet" | "crash" | "unknown";
+
+/** An observational record for work owned by another runtime. */
+export interface ExternalRun {
+	id: string;
+	sessionId: string;
+	source: string;
+	state: ExternalRunState;
+	command?: string;
+	cwd?: string;
+	isolationPath?: string;
+	owner?: string;
+	completionReason?: ExternalRunCompletionReason;
+	reportPath?: string;
+	startedAt?: number;
+	completedAt?: number;
+	exitCode?: number | null;
+	residualRisks?: string[];
+}
+
+export interface ExternalRunProvider {
+	name: string;
+	listExternalRuns(): readonly ExternalRun[];
+}
+
+export interface RegisteredExternalRun extends ExternalRun {
+	provider: string;
+}
+
+interface ExternalRunRegistry {
+	version: typeof EXTERNAL_RUN_REGISTRY_VERSION;
+	providers: Map<string, ExternalRunProvider>;
+}
+
+function registry(): ExternalRunRegistry {
+	const key = Symbol.for(EXTERNAL_RUN_REGISTRY_KEY);
+	const target = globalThis as Record<PropertyKey, unknown>;
+	const existing = target[key];
+	if (existing === undefined) {
+		const created: ExternalRunRegistry = { version: EXTERNAL_RUN_REGISTRY_VERSION, providers: new Map() };
+		target[key] = created;
+		return created;
+	}
+	if (!existing || typeof existing !== "object" || Array.isArray(existing)) throw new Error(`Malformed external-run registry at Symbol.for("${EXTERNAL_RUN_REGISTRY_KEY}").`);
+	const candidate = existing as Partial<ExternalRunRegistry>;
+	if (candidate.version !== EXTERNAL_RUN_REGISTRY_VERSION || !(candidate.providers instanceof Map)) throw new Error(`Unsupported external-run registry at Symbol.for("${EXTERNAL_RUN_REGISTRY_KEY}").`);
+	return candidate as ExternalRunRegistry;
+}
+
+function text(value: unknown, field: string, required = false): string | undefined {
+	if (value === undefined && !required) return undefined;
+	if (typeof value !== "string" || value.length === 0 || value.trim() !== value || value.includes("\0")) throw new Error(`${field} must be a non-empty trimmed string without NUL characters.`);
+	if (value.length > MAX_TEXT_LENGTH) throw new Error(`${field} must be at most ${MAX_TEXT_LENGTH} characters.`);
+	return value;
+}
+
+function timestamp(value: unknown, field: string): number | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error(`${field} must be a non-negative finite number.`);
+	return value;
+}
+
+function validateRun(value: unknown, provider: string, index: number): ExternalRun {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`External-run provider '${provider}' item ${index} must be an object.`);
+	const run = value as Record<string, unknown>;
+	const fields = new Set(["id", "sessionId", "source", "state", "command", "cwd", "isolationPath", "owner", "completionReason", "reportPath", "startedAt", "completedAt", "exitCode", "residualRisks"]);
+	const unknown = Object.keys(run).filter((key) => !fields.has(key));
+	if (unknown.length) throw new Error(`External-run provider '${provider}' item ${index} has unknown fields: ${unknown.join(", ")}.`);
+	if (!["running", "completed", "failed", "stopped"].includes(run.state as string)) throw new Error(`External-run provider '${provider}' item ${index} state is invalid.`);
+	if (run.completionReason !== undefined && !["exit", "timeout", "user-kill", "auto-close-quiet", "crash", "unknown"].includes(run.completionReason as string)) throw new Error(`External-run provider '${provider}' item ${index} completionReason is invalid.`);
+	if (run.exitCode !== undefined && run.exitCode !== null && (!Number.isInteger(run.exitCode) || !Number.isFinite(run.exitCode))) throw new Error(`External-run provider '${provider}' item ${index} exitCode must be an integer or null.`);
+	if (run.residualRisks !== undefined && (!Array.isArray(run.residualRisks) || run.residualRisks.some((risk, riskIndex) => text(risk, `External-run provider '${provider}' item ${index} residualRisks[${riskIndex}]`, true) === undefined))) throw new Error(`External-run provider '${provider}' item ${index} residualRisks must be an array of strings.`);
+	return {
+		id: text(run.id, `External-run provider '${provider}' item ${index} id`, true)!,
+		sessionId: text(run.sessionId, `External-run provider '${provider}' item ${index} sessionId`, true)!,
+		source: text(run.source, `External-run provider '${provider}' item ${index} source`, true)!,
+		state: run.state as ExternalRunState,
+		...(text(run.command, `External-run provider '${provider}' item ${index} command`) !== undefined ? { command: text(run.command, `External-run provider '${provider}' item ${index} command`) } : {}),
+		...(text(run.cwd, `External-run provider '${provider}' item ${index} cwd`) !== undefined ? { cwd: text(run.cwd, `External-run provider '${provider}' item ${index} cwd`) } : {}),
+		...(text(run.isolationPath, `External-run provider '${provider}' item ${index} isolationPath`) !== undefined ? { isolationPath: text(run.isolationPath, `External-run provider '${provider}' item ${index} isolationPath`) } : {}),
+		...(text(run.owner, `External-run provider '${provider}' item ${index} owner`) !== undefined ? { owner: text(run.owner, `External-run provider '${provider}' item ${index} owner`) } : {}),
+		...(run.completionReason !== undefined ? { completionReason: run.completionReason as ExternalRunCompletionReason } : {}),
+		...(text(run.reportPath, `External-run provider '${provider}' item ${index} reportPath`) !== undefined ? { reportPath: text(run.reportPath, `External-run provider '${provider}' item ${index} reportPath`) } : {}),
+		...(timestamp(run.startedAt, `External-run provider '${provider}' item ${index} startedAt`) !== undefined ? { startedAt: timestamp(run.startedAt, `External-run provider '${provider}' item ${index} startedAt`) } : {}),
+		...(timestamp(run.completedAt, `External-run provider '${provider}' item ${index} completedAt`) !== undefined ? { completedAt: timestamp(run.completedAt, `External-run provider '${provider}' item ${index} completedAt`) } : {}),
+		...(run.exitCode !== undefined ? { exitCode: run.exitCode as number | null } : {}),
+		...(run.residualRisks !== undefined ? { residualRisks: [...run.residualRisks] as string[] } : {}),
+	};
+}
+
+/** Register an observational provider. pi-subagents never starts, stops, or steers these processes. */
+export function registerExternalRunProvider(provider: ExternalRunProvider): () => void {
+	if (!provider || typeof provider !== "object" || Array.isArray(provider) || Object.keys(provider).some((key) => key !== "name" && key !== "listExternalRuns")) throw new Error("External-run provider must contain only name and listExternalRuns.");
+	const name = text(provider.name, "External-run provider name", true)!;
+	if (typeof provider.listExternalRuns !== "function") throw new Error(`External-run provider '${name}' must expose listExternalRuns().`);
+	const current = registry();
+	if (!current.providers.has(name) && current.providers.size >= MAX_PROVIDERS) throw new Error(`External-run registry supports at most ${MAX_PROVIDERS} providers.`);
+	current.providers.set(name, provider);
+	return () => { if (current.providers.get(name) === provider) current.providers.delete(name); };
+}
+
+/** Snapshot records for one Pi session. Records are read-only observations of foreign process ownership. */
+export function snapshotExternalRuns(sessionId: string): readonly RegisteredExternalRun[] {
+	text(sessionId, "External-run snapshot sessionId", true);
+	const records: RegisteredExternalRun[] = [];
+	const identities = new Set<string>();
+	for (const [name, provider] of registry().providers) {
+		if (provider.name !== name) throw new Error(`External-run registry key '${name}' does not match provider name '${provider.name}'.`);
+		const runs = provider.listExternalRuns();
+		if (!Array.isArray(runs)) throw new Error(`External-run provider '${name}' listExternalRuns() must return an array.`);
+		if (runs.length > MAX_RUNS_PER_PROVIDER) throw new Error(`External-run provider '${name}' returned more than ${MAX_RUNS_PER_PROVIDER} runs.`);
+		runs.forEach((value, index) => {
+			const run = validateRun(value, name, index);
+			const identity = `${name}\0${run.sessionId}\0${run.id}`;
+			if (identities.has(identity)) throw new Error(`External-run provider '${name}' returned duplicate run '${run.id}' for session '${run.sessionId}'.`);
+			identities.add(identity);
+			if (run.sessionId === sessionId) records.push({ provider: name, ...run });
+		});
+	}
+	return records;
+}

package/src/api/intercom-bridge.ts

@@ -0,0 +1,3 @@
+export {
+	resolveIntercomSessionTarget,
+} from "../intercom/intercom-bridge.ts";

package/src/api/pi-args.ts

@@ -0,0 +1,5 @@
+export {
+	resolvePiLaunchToolPlan,
+	type PiLaunchToolPlan,
+	type ResolvePiLaunchToolPlanInput,
+} from "../runs/shared/pi-args.ts";

package/src/api/preflight.ts

@@ -18,7 +18,7 @@ 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 { DIRS, TEMP_ROOT_DIR } from "../shared/types.ts";
 import { processTerminalCandidatePath, processTerminalPath } from "../runs/background/process-terminal.ts";
 import { nestedResultsPath } from "../runs/shared/nested-events.ts";
 
@@ -292,10 +292,10 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 	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);
+		: path.join(DIRS.async, runId);
 	const lifecycleResultPath = input.nestedRootRunId
 		? nestedResultsPath(input.nestedRootRunId, runId)
-		: path.join(RESULTS_DIR, `${runId}.json`);
+		: path.join(DIRS.results, `${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." });

package/src/api/shared-types.ts

@@ -0,0 +1,19 @@
+export {
+	DEFAULT_FORK_PREAMBLE,
+	wrapForkTask,
+	type AcceptanceEvidenceKind,
+	type AcceptanceInput,
+	type AcceptanceLedger,
+	type AcceptanceLevel,
+	type AsyncStartedEvent,
+	type ControlEvent,
+	type Details,
+	type ExecutionProjection,
+	type JsonSchemaObject,
+	type OutputMode,
+	type ReviewProjection,
+	type SingleResult,
+	type SubagentResultStatus,
+	type SubagentRunMode,
+	type Usage,
+} from "../shared/types.ts";

package/src/extension/config.ts

@@ -1,7 +1,10 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ArtifactDirPreference, ExtensionConfig } from "../shared/types.ts";
+import { validateMissionStoreConfig } from "../missions/store.ts";
+import { validateAuthorityPolicy } from "../policy/authority.ts";
 import { getAgentDir } from "../shared/utils.ts";
+import { validatePermissionConfig } from "../runs/shared/permissions.ts";
 
 const ARTIFACT_DIR_PREFERENCES = new Set<ArtifactDirPreference>(["project", "session", "temp"]);
 
@@ -19,6 +22,9 @@ function readConfigForUpdate(configPath = getConfigPath()): ExtensionConfig {
 	if (config.artifactDir !== undefined && !ARTIFACT_DIR_PREFERENCES.has(config.artifactDir as ArtifactDirPreference)) {
 		throw new Error(`config.artifactDir must be "project", "session", or "temp"`);
 	}
+	validateMissionStoreConfig(config.missions);
+	validateAuthorityPolicy(config.authorityPolicy);
+	validatePermissionConfig(config.permissions);
 	return parsed as ExtensionConfig;
 }
 
@@ -34,6 +40,10 @@ export function updateConfig(updater: (config: ExtensionConfig) => ExtensionConf
 	return next;
 }
 
+export function resolveAsyncByDefault(config: Pick<ExtensionConfig, "asyncByDefault">): boolean {
+	return config.asyncByDefault !== false;
+}
+
 export function loadConfig(): ExtensionConfig {
 	const configPath = getConfigPath();
 	try {

package/src/extension/control-notices.ts

@@ -20,21 +20,6 @@ export function formatSubagentControlNotice(details: SubagentControlMessageDetai
 	return details.noticeText ?? content ?? formatControlNoticeMessage(details.event, controlNoticeTarget(details));
 }
 
-function noticeTimerKey(details: SubagentControlMessageDetails): string {
-	const childIntercomTarget = controlNoticeTarget(details);
-	return `${details.event.runId}:${controlNotificationKey(details.event, childIntercomTarget)}`;
-}
-
-export function clearPendingForegroundControlNotices(state: SubagentState, runId?: string): void {
-	const pending = state.pendingForegroundControlNotices;
-	if (!pending) return;
-	for (const [key, timer] of pending) {
-		if (runId !== undefined && !key.startsWith(`${runId}:`)) continue;
-		clearTimeout(timer);
-		pending.delete(key);
-	}
-}
-
 function deliverControlNotice(input: {
 	pi: Pick<ExtensionAPI, "sendMessage">;
 	visibleControlNotices: Set<string>;
@@ -56,37 +41,18 @@ function deliverControlNotice(input: {
 	);
 }
 
-function isForegroundNoticeStillActionable(state: SubagentState, details: SubagentControlMessageDetails): boolean {
-	const control = state.foregroundControls.get(details.event.runId);
-	if (!control) return false;
-	if (control.currentAgent && control.currentAgent !== details.event.agent) return false;
-	if (details.event.index !== undefined && control.currentIndex !== details.event.index) return false;
-	return control.currentActivityState === "needs_attention";
-}
-
 export function handleSubagentControlNotice(input: {
 	pi: Pick<ExtensionAPI, "sendMessage">;
 	state: SubagentState;
 	visibleControlNotices: Set<string>;
 	details: SubagentControlMessageDetails;
-	foregroundDelayMs?: number;
 }): void {
 	if (!input.details?.event || input.details.event.type === "active_long_running") return;
-	if (input.details.source !== "foreground") {
-		deliverControlNotice(input);
+	if (input.details.source === "foreground") {
+		// A foreground tool blocks Pi from displaying this message. The run can
+		// finish before Pi flushes it, and queued messages cannot be withdrawn.
+		// Foreground control remains available through the live tool and fleet state.
 		return;
 	}
-
-	const pending = input.state.pendingForegroundControlNotices ?? new Map<string, ReturnType<typeof setTimeout>>();
-	input.state.pendingForegroundControlNotices = pending;
-	const timerKey = noticeTimerKey(input.details);
-	const existing = pending.get(timerKey);
-	if (existing) clearTimeout(existing);
-	const timer = setTimeout(() => {
-		pending.delete(timerKey);
-		if (!isForegroundNoticeStillActionable(input.state, input.details)) return;
-		deliverControlNotice(input);
-	}, input.foregroundDelayMs ?? 1000);
-	timer.unref?.();
-	pending.set(timerKey, timer);
+	deliverControlNotice(input);
 }

package/src/extension/doctor.ts

@@ -6,9 +6,8 @@ import { formatSpawnBudgetSummary, getSpawnBudgetSnapshot } from "../runs/shared
 import { diagnoseIntercomBridge, type IntercomBridgeDiagnostic } from "../intercom/intercom-bridge.ts";
 import { discoverAvailableSkills, type SkillSource } from "../agents/skills.ts";
 import {
-	ASYNC_DIR,
+	DIRS,
 	CHAIN_RUNS_DIR,
-	RESULTS_DIR,
 	TEMP_ROOT_DIR,
 	type ExtensionConfig,
 	type SubagentState,
@@ -43,12 +42,14 @@ interface DoctorReportInput {
 	deps?: Partial<DoctorDeps>;
 }
 
-const DEFAULT_PATHS: DoctorPaths = {
-	tempRootDir: TEMP_ROOT_DIR,
-	asyncDir: ASYNC_DIR,
-	resultsDir: RESULTS_DIR,
-	chainRunsDir: CHAIN_RUNS_DIR,
-};
+function defaultPaths(): DoctorPaths {
+	return {
+		tempRootDir: TEMP_ROOT_DIR,
+		asyncDir: DIRS.async,
+		resultsDir: DIRS.results,
+		chainRunsDir: CHAIN_RUNS_DIR,
+	};
+}
 
 const DEFAULT_DEPS: DoctorDeps = {
 	isAsyncAvailable,
@@ -192,7 +193,7 @@ function formatPermissionSystemSection(): string[] {
 }
 
 export function buildDoctorReport(input: DoctorReportInput): string {
-	const paths = input.paths ?? DEFAULT_PATHS;
+	const paths = input.paths ?? defaultPaths();
 	const deps = { ...DEFAULT_DEPS, ...input.deps };
 	const lines = [
 		"Subagents doctor report",

package/src/extension/fanout-child.ts

@@ -11,7 +11,7 @@ import { readNestedControlRequests, resolveNestedRouteFromEnv, writeNestedContro
 import { deliverSubagentIntercomMessageEvent } from "../intercom/result-intercom.ts";
 import { resolveSubagentIntercomTarget } from "../intercom/intercom-bridge.ts";
 import { SubagentParams } from "./schemas.ts";
-import { loadConfig } from "./config.ts";
+import { loadConfig, resolveAsyncByDefault } from "./config.ts";
 import { type Details, type SubagentState } from "../shared/types.ts";
 
 function getSubagentSessionRoot(parentSessionFile: string | null): string {
@@ -37,7 +37,6 @@ function createChildSafeState(): SubagentState {
 		foregroundRuns: new Map(),
 		foregroundControls: new Map(),
 		lastForegroundControlId: null,
-		pendingForegroundControlNotices: new Map(),
 		cleanupTimers: new Map(),
 		lastUiContext: null,
 		poller: null,
@@ -146,7 +145,7 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
 		pi,
 		state,
 		config,
-		asyncByDefault: config.asyncByDefault === true,
+		asyncByDefault: resolveAsyncByDefault(config),
 		waitToolEnabled: resolveWaitToolConfig(config.waitTool).enabled,
 		tempArtifactsDir: getArtifactsDir(null),
 		getSubagentSessionRoot,
@@ -165,7 +164,11 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
 		].join("\n"),
 		parameters: SubagentParams,
 		execute(id, params, signal, onUpdate, ctx) {
-			return executor.execute(id, params as SubagentParamsLike, signal, onUpdate, ctx);
+			const input = params as SubagentParamsLike;
+			if (input.tasks !== undefined || input.chain !== undefined || input.concurrency !== undefined || input.chainDir !== undefined || (input.worktree !== undefined && !(input.worktree === true && input.agent))) {
+				return Promise.resolve({ content: [{ type: "text", text: "Legacy top-level chain and parallel inputs were removed; use workflowScript." }], isError: true, details: { mode: "management", results: [] } });
+			}
+			return executor.execute(id, input, signal ?? new AbortController().signal, onUpdate, ctx);
 		},
 	};