pi-subagents 0.60.0 → 0.62.0

package/src/runs/shared/pi-spawn.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import { PI_CODING_AGENT_PACKAGE_ROOT_ENV } from "../../shared/utils.ts";
 
 export const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
 export const PI_SUBAGENT_PI_BINARY_ENV = "PI_SUBAGENT_PI_BINARY";
@@ -23,9 +24,13 @@ export function findPiPackageRootFromEntry(
 }
 
 export function resolveInstalledPiPackageRoot(): string | undefined {
-	return findPiPackageRootFromEntry(
-		fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PACKAGE)),
-	);
+	try {
+		return findPiPackageRootFromEntry(
+			fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PACKAGE)),
+		);
+	} catch {
+		return undefined;
+	}
 }
 
 export function resolvePiPackageRoot(): string | undefined {
@@ -58,12 +63,21 @@ interface PiSpawnCommand {
 	args: string[];
 }
 
+interface PiPackageJson {
+	name?: unknown;
+	bin?: string | Record<string, string>;
+}
+
+function isNodeScriptPath(filePath: string): boolean {
+	return /\.(?:mjs|cjs|js)$/i.test(filePath);
+}
+
 function isRunnableNodeScript(
 	filePath: string,
 	existsSync: (filePath: string) => boolean,
 ): boolean {
 	if (!existsSync(filePath)) return false;
-	return /\.(?:mjs|cjs|js)$/i.test(filePath);
+	return isNodeScriptPath(filePath);
 }
 
 function normalizePath(filePath: string): string {
@@ -75,6 +89,23 @@ function isStandalonePiExecutable(execPath: string): boolean {
 	return /^pi(?:\.exe)?$/i.test(executableName ?? "");
 }
 
+function resolvePiCliScriptFromPackageJson(
+	packageJsonPath: string,
+	readFileSync: (filePath: string, encoding: "utf-8") => string,
+	existsSync: (filePath: string) => boolean,
+): string | undefined {
+	const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as PiPackageJson;
+	if (packageJson.name !== PI_CODING_AGENT_PACKAGE) return undefined;
+	const binField = packageJson.bin;
+	const binPath =
+		typeof binField === "string"
+			? binField
+			: (binField?.pi ?? Object.values(binField ?? {})[0]);
+	if (!binPath) return undefined;
+	const candidate = path.resolve(path.dirname(packageJsonPath), binPath);
+	return isRunnableNodeScript(candidate, existsSync) ? candidate : undefined;
+}
+
 export function resolvePiCliScript(
 	deps: PiSpawnDeps = {},
 ): string | undefined {
@@ -84,6 +115,7 @@ export function resolvePiCliScript(
 		deps.readFileSync ??
 		((filePath, encoding) => fs.readFileSync(filePath, encoding));
 	const argv1 = deps.argv1 ?? process.argv[1];
+	const env = deps.env ?? process.env;
 
 	if (argv1) {
 		const argvPath = normalizePath(argv1);
@@ -99,38 +131,28 @@ export function resolvePiCliScript(
 		}
 	}
 
-	try {
-		const resolvePackageJson =
-			deps.resolvePackageJson ??
-			(() => {
-				const root = deps.piPackageRoot ?? resolvePiPackageRoot();
-				if (root) return path.join(root, "package.json");
-				const packageRoot = deps.resolvePackageEntry
-					? findPiPackageRootFromEntry(deps.resolvePackageEntry())
-					: resolveInstalledPiPackageRoot();
-				if (!packageRoot)
-					throw new Error(
-						`Could not resolve ${PI_CODING_AGENT_PACKAGE} package root`,
-					);
-				return path.join(packageRoot, "package.json");
-			});
-		const packageJsonPath = resolvePackageJson();
-		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as {
-			bin?: string | Record<string, string>;
-		};
-		const binField = packageJson.bin;
-		const binPath =
-			typeof binField === "string"
-				? binField
-				: (binField?.pi ?? Object.values(binField ?? {})[0]);
-		if (!binPath) return undefined;
-		const candidate = path.resolve(path.dirname(packageJsonPath), binPath);
-		if (isRunnableNodeScript(candidate, existsSync)) {
-			return candidate;
+	const packageJsonCandidates: Array<() => string | undefined> = [];
+	if (deps.resolvePackageJson) packageJsonCandidates.push(deps.resolvePackageJson);
+	for (const root of [deps.piPackageRoot, env[PI_CODING_AGENT_PACKAGE_ROOT_ENV], resolvePiPackageRoot()]) {
+		const trimmed = root?.trim();
+		if (trimmed) packageJsonCandidates.push(() => path.join(trimmed, "package.json"));
+	}
+	packageJsonCandidates.push(() => {
+		const packageRoot = deps.resolvePackageEntry
+			? findPiPackageRootFromEntry(deps.resolvePackageEntry())
+			: resolveInstalledPiPackageRoot();
+		return packageRoot ? path.join(packageRoot, "package.json") : undefined;
+	});
+
+	for (const candidatePackageJson of packageJsonCandidates) {
+		try {
+			const packageJsonPath = candidatePackageJson();
+			if (!packageJsonPath) continue;
+			const candidate = resolvePiCliScriptFromPackageJson(packageJsonPath, readFileSync, existsSync);
+			if (candidate) return candidate;
+		} catch {
+			// Keep resolving; callers decide whether a PATH fallback is safe.
 		}
-	} catch {
-		// Verified CLI resolution is optional; falling back to `pi` lets PATH handle execution.
-		return undefined;
 	}
 
 	return undefined;
@@ -140,9 +162,16 @@ export function getPiSpawnCommand(
 	args: string[],
 	deps: PiSpawnDeps = {},
 ): PiSpawnCommand {
+	const platform = deps.platform ?? process.platform;
 	const env = deps.env ?? process.env;
 	const piBinary = env[PI_SUBAGENT_PI_BINARY_ENV]?.trim();
 	if (piBinary) {
+		if (platform === "win32" && isNodeScriptPath(piBinary)) {
+			return {
+				command: deps.execPath ?? process.execPath,
+				args: [piBinary, ...args],
+			};
+		}
 		return { command: piBinary, args };
 	}
 
@@ -158,6 +187,11 @@ export function getPiSpawnCommand(
 			args: [piCliPath, ...args],
 		};
 	}
+	if (platform === "win32") {
+		throw new Error(
+			`Could not resolve the Pi CLI on Windows. Set ${PI_SUBAGENT_PI_BINARY_ENV} or ensure ${PI_CODING_AGENT_PACKAGE} is installed.`,
+		);
+	}
 
 	return { command: "pi", args };
 }

package/src/runs/shared/structured-output.ts

@@ -5,17 +5,21 @@ import * as path from "node:path";
 import { pathToFileURL } from "node:url";
 import { PI_CODING_AGENT_PACKAGE_ROOT_ENV } from "../../shared/utils.ts";
 import type { JsonSchemaObject } from "../../shared/types.ts";
+import type { ResolvedAcceptanceReportMode } from "./acceptance.ts";
 
 export const STRUCTURED_OUTPUT_SCHEMA_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA";
 export const STRUCTURED_OUTPUT_CAPTURE_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_CAPTURE";
 export const STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE";
+export const STRUCTURED_OUTPUT_ACCEPTANCE_REQUIRED_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_ACCEPTANCE_REQUIRED";
 export const MISSING_STRUCTURED_OUTPUT_CALL_ERROR = "Missing structured_output call; this step has outputSchema and must finish by calling structured_output.";
+export const MISSING_STRUCTURED_ACCEPTANCE_REPORT_ERROR = "Missing acceptanceReport in structured_output call; acceptance.report is \"on\".";
 
 export interface StructuredOutputRuntime {
 	schema: JsonSchemaObject;
 	schemaPath: string;
 	outputPath: string;
 	acceptanceReportPath?: string;
+	acceptanceReportRequired?: boolean;
 }
 
 const SCHEMA_MAP_KEYWORDS = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"] as const;
@@ -61,14 +65,14 @@ function rewriteLocalJsonPointerRefs(schema: unknown, pointerPrefix: string, inh
 	return rewritten;
 }
 
-export function createStructuredOutputToolParameters(schema: JsonSchemaObject, options: { acceptanceReport?: boolean } = {}): JsonSchemaObject {
+export function createStructuredOutputToolParameters(schema: JsonSchemaObject, options: { acceptanceReport?: "optional" | "required" } = {}): JsonSchemaObject {
 	return {
 		type: "object",
 		properties: {
 			value: rewriteLocalJsonPointerRefs(schema, "#/properties/value"),
 			...(options.acceptanceReport ? { acceptanceReport: { type: "object" } } : {}),
 		},
-		required: ["value"],
+		required: ["value", ...(options.acceptanceReport === "required" ? ["acceptanceReport"] : [])],
 		additionalProperties: false,
 	};
 }
@@ -129,7 +133,7 @@ export function assertJsonSchemaObject(schema: unknown, label = "outputSchema"):
 	}
 }
 
-export function createStructuredOutputRuntime(schema: JsonSchemaObject, baseDir?: string, options: { captureAcceptanceReport?: boolean } = {}): StructuredOutputRuntime {
+export function createStructuredOutputRuntime(schema: JsonSchemaObject, baseDir?: string, options: { acceptanceReport?: ResolvedAcceptanceReportMode } = {}): StructuredOutputRuntime {
 	assertJsonSchemaObject(schema);
 	const rootDir = baseDir ?? os.tmpdir();
 	fs.mkdirSync(rootDir, { recursive: true });
@@ -137,7 +141,14 @@ export function createStructuredOutputRuntime(schema: JsonSchemaObject, baseDir?
 	const schemaPath = path.join(dir, "schema.json");
 	const outputPath = path.join(dir, "output.json");
 	fs.writeFileSync(schemaPath, JSON.stringify(schema), { mode: 0o600 });
-	return { schema, schemaPath, outputPath, ...(options.captureAcceptanceReport ? { acceptanceReportPath: path.join(dir, "acceptance-report.json") } : {}) };
+	return {
+		schema,
+		schemaPath,
+		outputPath,
+		...(options.acceptanceReport && options.acceptanceReport !== "off"
+			? { acceptanceReportPath: path.join(dir, "acceptance-report.json"), acceptanceReportRequired: options.acceptanceReport === "required" }
+			: {}),
+	};
 }
 
 export async function validateStructuredOutputValue(schema: JsonSchemaObject, value: unknown): Promise<{ status: "valid" } | { status: "invalid"; message: string }> {
@@ -178,14 +189,30 @@ export async function readStructuredOutput(runtime: StructuredOutputRuntime): Pr
 }
 
 export function readStructuredOutputAcceptanceReport(runtime: StructuredOutputRuntime): { value?: unknown; error?: string } {
-	if (!runtime.acceptanceReportPath || !fs.existsSync(runtime.acceptanceReportPath)) return {};
+	if (!runtime.acceptanceReportPath) return {};
+	if (!fs.existsSync(runtime.acceptanceReportPath)) {
+		return runtime.acceptanceReportRequired ? { error: MISSING_STRUCTURED_ACCEPTANCE_REPORT_ERROR } : {};
+	}
 	try {
-		return { value: JSON.parse(fs.readFileSync(runtime.acceptanceReportPath, "utf-8")) };
+		return { value: JSON.parse(fs.readFileSync(runtime.acceptanceReportPath, "utf-8")) as unknown };
 	} catch (error) {
 		return { error: `Failed to read structured output acceptance report: ${error instanceof Error ? error.message : String(error)}` };
 	}
 }
 
+export function clearStructuredOutputCaptures(runtime: StructuredOutputRuntime): string | undefined {
+	let cleanupError: string | undefined;
+	for (const filePath of [runtime.outputPath, runtime.acceptanceReportPath]) {
+		if (!filePath) continue;
+		try {
+			if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+		} catch (error) {
+			cleanupError ??= `Failed to clear stale structured output capture ${filePath}: ${error instanceof Error ? error.message : String(error)}`;
+		}
+	}
+	return cleanupError;
+}
+
 export function cleanupStructuredOutputRuntime(runtime: StructuredOutputRuntime | undefined): void {
 	if (!runtime) return;
 	try {

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -8,7 +8,8 @@ import { decodePermissionRules, permissionDecision, PERMISSION_AUDIT_PATH_ENV, P
 import { consumeSteerRequestsFromDir, MAX_STEER_QUEUE_SIZE, steerAckPathFromDir, writeSteerAckAt, writeSteerCapabilityAt, writeSteerRequestToDir, type SteerDeliveryStatus, type SteerRequest } from "../background/control-channel.ts";
 import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_FORK_CACHE_KEY_ENV, SUBAGENT_INHERIT_GLOBAL_CONTEXT_ENV, SUBAGENT_STEER_ACK_DIR_ENV, SUBAGENT_STEER_CAPABILITY_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
 import { RUNTIME_EXTENSION_ACK_EVENT, RUNTIME_EXTENSION_ACK_PATH_ENV, isRuntimeAcknowledgedExtensionId, writeRuntimeAcknowledgedExtensions } from "./runtime-acknowledged-extensions.ts";
-import { createStructuredOutputToolParameters, STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV, STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
+import { createStructuredOutputToolParameters, MISSING_STRUCTURED_ACCEPTANCE_REPORT_ERROR, STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV, STRUCTURED_OUTPUT_ACCEPTANCE_REQUIRED_ENV, STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
+import { validateAcceptanceReport } from "./acceptance.ts";
 import {
 	CHILD_TOOL_DIAGNOSTIC_PATH_ENV,
 	formatChildToolDiagnostic,
@@ -729,10 +730,14 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 	});
 	const structuredOutputPath = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV];
 	const structuredAcceptanceReportPath = process.env[STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV];
+	const structuredAcceptanceReportRequired = process.env[STRUCTURED_OUTPUT_ACCEPTANCE_REQUIRED_ENV] === "1";
 	const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
 	if (structuredOutputPath && structuredSchemaPath) {
 		const schema = JSON.parse(fs.readFileSync(structuredSchemaPath, "utf-8")) as JsonSchemaObject;
-		const parameters = createStructuredOutputToolParameters(schema, { acceptanceReport: Boolean(structuredAcceptanceReportPath) });
+		const acceptanceReportMode = structuredAcceptanceReportPath
+			? structuredAcceptanceReportRequired ? "required" as const : "optional" as const
+			: undefined;
+		const parameters = createStructuredOutputToolParameters(schema, { acceptanceReport: acceptanceReportMode });
 		const registerTool = pi.registerTool as unknown as (tool: {
 			name: string;
 			label: string;
@@ -750,11 +755,23 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 				if (validation.status === "invalid") {
 					throw new Error(`Structured output validation failed: ${validation.message}`);
 				}
+				if (structuredAcceptanceReportRequired && params.acceptanceReport === undefined) {
+					throw new Error(MISSING_STRUCTURED_ACCEPTANCE_REPORT_ERROR);
+				}
+				if (structuredAcceptanceReportRequired && params.acceptanceReport !== undefined) {
+					const acceptanceValidation = validateAcceptanceReport(params.acceptanceReport, "acceptanceReport");
+					if (!acceptanceValidation.report) {
+						throw new Error(`Invalid structured output acceptance report: ${acceptanceValidation.errors.join("; ")}`);
+					}
+				}
 				fs.mkdirSync(path.dirname(structuredOutputPath), { recursive: true });
-				fs.writeFileSync(structuredOutputPath, JSON.stringify(params.value), { mode: 0o600 });
 				if (structuredAcceptanceReportPath && params.acceptanceReport !== undefined) {
+					fs.mkdirSync(path.dirname(structuredAcceptanceReportPath), { recursive: true });
 					fs.writeFileSync(structuredAcceptanceReportPath, JSON.stringify(params.acceptanceReport), { mode: 0o600 });
+				} else if (structuredAcceptanceReportPath && fs.existsSync(structuredAcceptanceReportPath)) {
+					fs.unlinkSync(structuredAcceptanceReportPath);
 				}
+				fs.writeFileSync(structuredOutputPath, JSON.stringify(params.value), { mode: 0o600 });
 				return {
 					content: [{ type: "text", text: "Structured output captured." }],
 					details: { path: structuredOutputPath },

package/src/runs/shared/task-intent.ts

@@ -34,13 +34,22 @@ const REVIEWER_REQUIRED_EDIT_PATTERNS = [
 	/\bmake\s+(?:the\s+)?code\s+changes\b/i,
 ];
 
-// The prohibition's object ends at punctuation or at a coordinating word
-// (but/and/then), so a follow-on clause like "but implement the fix" stays in
-// the text for write-intent testing instead of being swallowed as the object.
-const NO_EDIT_PROHIBITION_PATTERN = /\b(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b((?:(?!\b(?:but|and|then)\b)[^.;,:!?\n–—-])*)/gi;
+// The prohibition's object ends at punctuation, a serialized line separator,
+// or a coordinating word (but/and/then), so a follow-on clause like "but
+// implement the fix" stays in the text for write-intent testing instead of
+// being swallowed as the object.
+// Accept serialized line separators too: workflow prompts can carry literal
+// `\\n`/`\\r\\n` between clauses instead of decoded newlines.
+const NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b((?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\n–—-])*)/gi;
 
 /** Objects of a no-edit prohibition that mean "the codebase in general" rather than a named scope. */
 const GENERIC_PROHIBITION_OBJECT = /^\s*(?:(?:any|all|the|these|those|your|our|existing|project|product|source|sources|config|configs|repo|repository)[\s/,-]*)*(?:files?|code|codebase|sources?|anything|repo(?:sitory)?)?\s*$/i;
+const SCOPED_PROHIBITION_CONTINUATION = /^(?:\\(?:r\\n|n)|\r?\n)\s*(?:in|inside|under|within|outside|except|other\s+than|besides)\b/i;
+const OUTPUT_INSTRUCTION_CONTINUATION = /^(?:\\(?:r\\n|n)|\r?\n)\s*(?:in|inside|within)\s+(?:(?:(?:your|the)\s+)(?:final\s+)?|final\s+)(?:output|response|report|answer|reply|message|summary|findings?|analysis|recommendations?)(?:\s*\/\s*(?:output|response|report|answer|reply|message|summary|findings?|analysis|recommendations?))*\b(?![\\/])/i;
+
+function hasScopedProhibitionContinuation(text: string): boolean {
+	return SCOPED_PROHIBITION_CONTINUATION.test(text) && !OUTPUT_INSTRUCTION_CONTINUATION.test(text);
+}
 
 const SCOPED_NO_EDIT_CONSTRAINT_PATTERNS = [
 	/\bdo not edit files?\s+outside\b/i,
@@ -135,11 +144,13 @@ function analyzeNoEditProhibitions(taskText: string): NoEditProhibitionAnalysis
 		|| NO_TOOL_INTENT_PATTERNS.some((pattern) => pattern.test(taskText));
 	let blanket = present;
 	let strippedText = stripPatterns(taskText, [...REVIEW_ONLY_PATTERNS, ...NO_TOOL_INTENT_PATTERNS]);
-	strippedText = strippedText.replace(new RegExp(NO_EDIT_PROHIBITION_PATTERN.source, NO_EDIT_PROHIBITION_PATTERN.flags), (_match, object: string) => {
+	strippedText = strippedText.replace(new RegExp(NO_EDIT_PROHIBITION_PATTERN.source, NO_EDIT_PROHIBITION_PATTERN.flags), (match, object: string, offset: number, source: string) => {
 		present = true;
-		if (GENERIC_PROHIBITION_OBJECT.test(object)) blanket = true;
+		if (GENERIC_PROHIBITION_OBJECT.test(object) && !hasScopedProhibitionContinuation(source.slice(offset + match.length))) blanket = true;
 		return " ";
 	});
+	// Restore boundaries after stripping a prohibition from serialized prompts.
+	strippedText = strippedText.replace(/\\(?:r\\n|n)/g, "\n");
 	return { present, blanket, strippedText };
 }
 

package/src/runs/shared/tool-timeout.ts

@@ -16,7 +16,7 @@ export const DEFAULT_FAST_TOOL_TIMEOUT_TOOLS = new Set([
 ]);
 
 /** Tools whose normal job can be to wait for a person or another run. */
-export const TOOL_TIMEOUT_EXEMPT_TOOLS = new Set(["contact_supervisor", "intercom", "subagent_wait"]);
+export const TOOL_TIMEOUT_EXEMPT_TOOLS = new Set(["contact_supervisor", "intercom", "bg_wait"]);
 
 // Backward-compatible export name for existing callers/tests.
 export const TOOL_TIMEOUT_ALLOWLIST = TOOL_TIMEOUT_EXEMPT_TOOLS;

package/src/runs/shared/workflow-graph.ts

@@ -15,7 +15,8 @@ export interface WorkflowGraphBuildInput {
 
 /** Return displayable workflow stages while hiding structural parallel groups and host monitors. */
 export function workflowGraphStageNodes(graph: WorkflowGraphSnapshot | undefined): WorkflowGraphNode[] {
-	if (!graph?.nodes?.length) return [];
+	const nodes = graph?.nodes;
+	if (!nodes?.length) return [];
 	const stages: WorkflowGraphNode[] = [];
 	const visit = (node: WorkflowGraphNode): void => {
 		if (node.kind === "parallel-group" || node.kind === "dynamic-parallel-group") {
@@ -24,7 +25,7 @@ export function workflowGraphStageNodes(graph: WorkflowGraphSnapshot | undefined
 		}
 		if (node.kind !== "host-step") stages.push(node);
 	};
-	for (const node of graph.nodes) visit(node);
+	for (const node of nodes) visit(node);
 	return stages;
 }
 

package/src/shared/atomic-json.ts

@@ -15,6 +15,7 @@ type AtomicJsonWriterOptions = {
 	mode?: number;
 	retryRenameErrors?: boolean;
 	retryDirectoryErrors?: boolean;
+	ignoreCleanupErrorAfterSuccess?: boolean;
 	retryDelaysMs?: readonly number[];
 	wait?: (delayMs: number) => void;
 };
@@ -46,6 +47,7 @@ export function createAtomicJsonWriter(options: AtomicJsonWriterOptions = {}): (
 	const mode = options.mode;
 	const retryRenameErrors = options.retryRenameErrors ?? process.platform === "win32";
 	const retryDirectoryErrors = options.retryDirectoryErrors ?? retryRenameErrors;
+	const ignoreCleanupErrorAfterSuccess = options.ignoreCleanupErrorAfterSuccess ?? false;
 	const retryDelaysMs = options.retryDelaysMs ?? DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS;
 	const renameRetryDelaysMs = retryRenameErrors ? retryDelaysMs : [];
 	const directoryRetryDelaysMs = retryDirectoryErrors ? retryDelaysMs : [];
@@ -71,7 +73,7 @@ export function createAtomicJsonWriter(options: AtomicJsonWriterOptions = {}): (
 			} catch (cleanupError) {
 				// Preserve the write/rename failure: cleanup is best effort and must
 				// not hide the error callers need to classify or report.
-				if (writeError === undefined) throw cleanupError;
+				if (writeError === undefined && !ignoreCleanupErrorAfterSuccess) throw cleanupError;
 			}
 		}
 	};

package/src/shared/fork-context.ts

@@ -174,18 +174,6 @@ function readSessionEntries(sessionFile: string): BranchSessionEntry[] {
 	});
 }
 
-/** Keep Pi from restoring a forked session into the parent's cwd instead of the child launch cwd. */
-export function alignForkedSessionCwd(sessionFile: string, cwd: string): void {
-	const entries = readSessionEntries(sessionFile);
-	const header = entries[0];
-	if (header?.type !== "session") throw new Error(`Forked session ${sessionFile} does not start with a session header.`);
-	const resolvedCwd = path.resolve(cwd);
-	const effectiveCwd = fs.realpathSync.native(resolvedCwd);
-	if (header.cwd === effectiveCwd) return;
-	header.cwd = effectiveCwd;
-	fs.writeFileSync(sessionFile, `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf-8");
-}
-
 export function createForkContextResolver(
 	sessionManager: ForkableSessionManager,
 	requestedContext: unknown,

package/src/shared/fork-session-cwd.ts

@@ -0,0 +1,27 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+interface SessionEntry {
+	type?: string;
+	cwd?: string;
+	[key: string]: unknown;
+}
+
+/** Keep Pi from restoring a forked session into the parent's cwd instead of the child launch cwd. */
+export function alignForkedSessionCwd(sessionFile: string, cwd: string): void {
+	const lines = fs.readFileSync(sessionFile, "utf-8").split("\n").filter((line) => line.trim().length > 0);
+	const entries = lines.map((line, index) => {
+		try {
+			return JSON.parse(line) as SessionEntry;
+		} catch (error) {
+			const cause = error instanceof Error ? error : new Error(String(error));
+			throw new Error(`Unable to inspect forked session ${sessionFile}: invalid JSONL on line ${index + 1}: ${cause.message}`, { cause });
+		}
+	});
+	const header = entries[0];
+	if (header?.type !== "session") throw new Error(`Forked session ${sessionFile} does not start with a session header.`);
+	const effectiveCwd = fs.realpathSync.native(path.resolve(cwd));
+	if (header.cwd === effectiveCwd) return;
+	header.cwd = effectiveCwd;
+	fs.writeFileSync(sessionFile, `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`, "utf-8");
+}

package/src/shared/launch-contract.ts

@@ -51,6 +51,7 @@ export function projectAgentDefinition(agent: AgentConfig): Record<string, unkno
 		fast: agent.fast,
 		thinking: agent.thinking,
 		tools: agent.tools,
+		excludeTools: agent.excludeTools,
 		allowNestedSubagents: agent.allowNestedSubagents,
 		mcpDirectTools: agent.mcpDirectTools,
 		extensions: agent.extensions,
@@ -93,6 +94,7 @@ export interface LaunchBindingInput {
 	inheritSkills: boolean;
 	skills?: string[];
 	tools?: string[];
+	excludeTools?: string[];
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
 	mcpDirectTools?: string[];
@@ -120,6 +122,7 @@ export function projectLaunchBinding(input: LaunchBindingInput): Record<string,
 		inheritSkills: input.inheritSkills,
 		skills: input.skills,
 		tools: input.tools,
+		excludeTools: input.excludeTools,
 		extensions: input.extensions,
 		subagentOnlyExtensions: input.subagentOnlyExtensions,
 		mcpDirectTools: input.mcpDirectTools,

package/src/shared/types.ts

@@ -143,6 +143,20 @@ export interface WorkflowRecoveryAction {
 	taskRequired: true;
 }
 
+/**
+ * Bounded, host-generated identity for a resolved pi-subagents workflow resource.
+ * Permission/policy extensions can use it to distinguish resolved content from
+ * raw workflow scripts. This audit projection never grants execution authority.
+ */
+export interface WorkflowResourceProvenanceV1 {
+	kind: "workflow";
+	name: string;
+	version: number;
+	invocation: "named";
+	expansion: "resolved";
+	id: string;
+}
+
 /**
  * Bounded, launch-declared workflow lane metadata. This is display and
  * triage information only; capability ceilings, authorization, and cleanup
@@ -189,6 +203,7 @@ export type WorkflowReceiptEntry = WorkflowReceiptEntryResumability & {
 	requestedContext?: "fresh" | "fork";
 	resolvedContext?: "fresh" | "fork" | "mixed";
 	outputReference?: string;
+	acceptanceRecovery?: AcceptanceRecoveryMetadata;
 	externalAdapter?: ExternalCliReceiptMetadata;
 	continuation: { runIds: string[] };
 };
@@ -199,6 +214,7 @@ export interface WorkflowReceipt {
 	state: WorkflowReceiptState;
 	createdAt: number;
 	entries: Record<string, WorkflowReceiptEntry>;
+	resource?: WorkflowResourceProvenanceV1;
 	hostSteps?: HostStepNodeV1[];
 	workflowChildren?: WorkflowChildSummaryV1;
 	workflowResolution?: WorkflowTerminalResolution;
@@ -330,7 +346,7 @@ export interface CompletionBatchConfig {
 
 export interface WaitToolConfigObject {
 	enabled?: boolean;
-	/** Default blocking window for subagent_wait calls that omit timeoutMs. */
+	/** Default blocking window for bg_wait calls that omit timeoutMs. */
 	defaultTimeoutMs?: number;
 }
 
@@ -758,11 +774,13 @@ export interface SteeringRecoveryDescriptor {
 	model?: string;
 	modelProvider?: string;
 	modelOverrideFromParent?: boolean;
+	modelOrigin?: "explicit" | "inherited" | "configured";
 	fallbackModels?: string[];
 	fast?: boolean;
 	thinking?: string;
 	thinkingCeiling?: ThinkingLevel;
 	tools?: string[];
+	excludeTools?: string[];
 	allowNestedSubagents?: boolean;
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
@@ -977,6 +995,7 @@ export interface AcceptanceReviewGate {
 
 export interface AcceptanceConfig {
 	level?: AcceptanceLevel;
+	report?: "on" | "off";
 	criteria?: Array<string | AcceptanceGate>;
 	evidence?: AcceptanceEvidenceKind[];
 	verify?: AcceptanceVerifyCommand[];
@@ -1086,6 +1105,18 @@ export type AcceptanceLedgerStatus =
 	| "reviewed"
 	| "accepted";
 
+/**
+ * Durable child evidence that can be handed to a read-only review after the
+ * acceptance envelope itself was rejected. This never upgrades acceptance;
+ * the enclosing ledger remains rejected and the child remains unsuccessful.
+ */
+export interface AcceptanceRecoveryMetadata {
+	status: "available-for-review";
+	reason: "acceptance-metadata-rejected";
+	reportPath: string;
+	reportHash: string;
+}
+
 export interface AcceptanceLedger {
 	status: AcceptanceLedgerStatus;
 	evidenceStatus: AcceptanceEvidenceStatus;
@@ -1095,6 +1126,7 @@ export interface AcceptanceLedger {
 	criteria: ResolvedAcceptanceGate[];
 	childReport?: AcceptanceReport;
 	childReportParseError?: string;
+	recovery?: AcceptanceRecoveryMetadata;
 	runtimeChecks: AcceptanceRuntimeCheck[];
 	verifyRuns: AcceptanceVerifyResult[];
 	reviewResult?: AcceptanceReviewResult;
@@ -1283,7 +1315,7 @@ export interface WaitCompletionChild {
 }
 
 /**
- * Terminal completion observed for a run a subagent_wait call covered. Carries run
+ * Terminal completion observed for a run a bg_wait call covered. Carries run
  * identity and the artifact trail; output text stays in the tool result content.
  */
 export interface WaitCompletion {
@@ -1312,7 +1344,7 @@ export interface AgentCapabilityRow {
 	restrictionSources?: string[];
 	aliases?: string[];
 	runner: { type: "pi" } | { type: "external-cli"; adapter?: string; capabilities: ExternalCliCapabilities } | { type: "external-job"; provider: string; available?: boolean; capabilities: ExternalJobRunnerStatus["capabilities"] };
-	tools: { ambient: boolean; names: string[]; mcpDirectTools: string[]; mutationTools?: string[] };
+	tools: { ambient: boolean; names: string[]; excludeTools?: string[]; mcpDirectTools: string[]; mutationTools?: string[] };
 	model?: { value?: string; fallbackModels?: string[]; thinking?: string | false };
 	execution?: { defaultAsync?: boolean; timeoutMs?: number };
 	output?: { path?: string; mode?: OutputMode };
@@ -1329,7 +1361,7 @@ export interface Details {
 	results: SingleResult[];
 	workflowChildren?: WorkflowChildSummaryV1;
 	/**
-	 * Terminal completion payloads for runs this subagent_wait call observed
+	 * Terminal completion payloads for runs this bg_wait call observed
 	 * finishing. Async completions travel as result files that are consumed and
 	 * deleted after text delivery, so without this field their run and artifact
 	 * identity never reaches tool_result details.
@@ -1401,6 +1433,7 @@ export interface Details {
 	mission?: MissionRecord;
 	workflow?: {
 		value?: unknown;
+		resource?: WorkflowResourceProvenanceV1;
 		preflightWarnings?: string[];
 		trace: Array<{
 			operation: "run" | "status" | "steer" | "host";
@@ -2117,6 +2150,8 @@ export interface ActiveAsyncCapacitySnapshot {
 export interface SubagentState {
 	baseCwd: string;
 	currentSessionId: string | null;
+	/** Session for which active status projections were restored successfully. */
+	statusProjectionSessionId?: string | null;
 	/** Reload-stable identity for this parent Pi process/window. */
 	completionOwnerId?: string;
 	/** Runtime-owned artifact resolution inputs used by Fleet transcript targeting. */
@@ -2283,6 +2318,8 @@ export interface RunSyncOptions {
 	allowIntercomDetach?: boolean;
 	intercomEvents?: IntercomEventBus;
 	onUpdate?: (r: import("@earendil-works/pi-agent-core").AgentToolResult<Details>) => void;
+	/** Internal structured-delegation transport optimization: skip unchanged live snapshots. */
+	suppressUnchangedDelegationUpdates?: boolean;
 	onControlEvent?: (event: ControlEvent) => void;
 	/** Exposes a non-terminating detach callback while the child is active. */
 	onDetachReady?: (detach: (reason?: string) => boolean) => void;
@@ -2318,6 +2355,8 @@ export interface RunSyncOptions {
 	fast?: boolean;
 	/** The override came from the running parent session, not configuration. */
 	modelOverrideFromParent?: boolean;
+	/** How the launch model was selected: explicit per-call, configured agent primary, or inherited parent. */
+	modelOrigin?: "explicit" | "inherited" | "configured";
 	/** LLM intent arbiter for the completion mutation guard (rescues read-only review runs). */
 	llmIntentArbiter?: import("../runs/shared/llm-intent-arbiter.ts").TaskMutationArbiter;
 	/** Override the agent's default thinking level for this run */