pi-subagents 0.35.0 → 0.36.0

package/src/runs/shared/acceptance.ts

@@ -6,6 +6,7 @@ import type {
 	AcceptanceConfig,
 	AcceptanceEvidenceKind,
 	AcceptanceInput,
+	AgentContract,
 	AcceptanceLedger,
 	AcceptanceLevel,
 	AcceptanceReport,
@@ -20,6 +21,7 @@ import type {
 	SingleResult,
 	SubagentRunMode,
 } from "../../shared/types.ts";
+import { isAgentContractV1 } from "./agent-contract.ts";
 import { classifyTaskMutationIntent, taskMayMutate } from "./task-intent.ts";
 
 const LEVEL_RANK: Record<Exclude<AcceptanceLevel, "auto">, number> = {
@@ -90,9 +92,9 @@ function inferLevel(input: {
 		&& intent.kind !== "read-only"
 		&& !/\b(?:do not|don't|must not)\s+patch\b/.test(task)
 		&& /\bpatch\s+(?:(?:\.{0,2}[\\/])?(?:[\w.-]+[\\/])+[\w.-]+|[\w.-]+\.[a-z0-9]+\b|(?:the\s+)?parser\b)/.test(task);
-	const taskMayWrite = taskMayMutate(input.task ?? "") || intent.kind === "implementation" || rolePatchTask;
+	const taskMayWrite = readOnlyTask ? false : taskMayMutate(input.task ?? "") || intent.kind === "implementation" || rolePatchTask;
 	const readOnlyAgent = input.acceptanceRole === "read-only"
-		|| (input.acceptanceRole === undefined && /\b(?:reviewer|scout|context-builder|researcher|analyst)\b/.test(agent));
+		|| (input.acceptanceRole === undefined && /\b(?:reviewer|oracle|scout|context-builder|researcher|analyst)\b/.test(agent));
 	const writeTask = taskMayWrite
 		|| (input.acceptanceRole === "writer" && !readOnlyTask)
 		|| (input.acceptanceRole === undefined && /\bworker\b/.test(agent) && !readOnlyTask);
@@ -324,10 +326,32 @@ export function resolveEffectiveAcceptance(input: {
 	async?: boolean;
 	dynamic?: boolean;
 	dynamicGroup?: boolean;
+	agentContract?: AgentContract;
 }): ResolvedAcceptanceConfig {
 	const explicit = normalizeAcceptanceInput(input.explicit);
-	const inferred = inferLevel(input);
 	const explicitLevel = normalizeLevel(explicit.level);
+	if (isAgentContractV1(input.agentContract)) {
+		const level = explicitAcceptanceCanDisable(explicit) || explicitLevel === "auto"
+			? "none"
+			: explicitLevel;
+		const evidence = unique(explicit.evidence ?? []);
+		const criteria = normalizeCriteria(
+			explicit.criteria as Array<string | { id?: string; must?: string; evidence?: AcceptanceEvidenceKind[]; severity?: "required" | "recommended" }> | undefined,
+			evidence,
+		);
+		return {
+			level,
+			explicit: input.explicit !== undefined,
+			inferredReason: [],
+			criteria,
+			evidence,
+			verify: explicit.verify ?? [],
+			review: explicit.review,
+			stopRules: explicit.stopRules ?? [],
+			reason: explicit.reason,
+		};
+	}
+	const inferred = inferLevel(input);
 	const level = explicitAcceptanceCanDisable(explicit)
 		? "none"
 		: explicitLevel === "auto"
@@ -355,8 +379,13 @@ export function resolveEffectiveAcceptance(input: {
 	};
 }
 
-export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig): string {
+function acceptanceRequiresChildReport(acceptance: ResolvedAcceptanceConfig): boolean {
+	return acceptance.criteria.length > 0 || acceptance.evidence.length > 0;
+}
+
+export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig, options: { reportOptional?: boolean } = {}): string {
 	if (acceptance.level === "none") return "";
+	if (options.reportOptional && !acceptanceRequiresChildReport(acceptance)) return "";
 	const lines = [
 		"",
 		"## Acceptance Contract",
@@ -1029,6 +1058,7 @@ export async function evaluateAcceptance(input: {
 	reviewResult?: AcceptanceReviewResult;
 	signal?: AbortSignal;
 	abortMessage?: string;
+	reportOptional?: boolean;
 }): Promise<AcceptanceLedger> {
 	const acceptance = input.acceptance;
 	const ledger: AcceptanceLedger = {
@@ -1050,26 +1080,30 @@ export async function evaluateAcceptance(input: {
 				: { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
 		})()
 		: parseAcceptanceReportSources(input.output, input.fileOutput);
+	const needsReport = acceptanceRequiresChildReport(acceptance);
 	if (parsed.report) {
 		ledger.childReport = parsed.report;
 		ledger.status = "attested";
-	} else {
+	} else if (!input.reportOptional || needsReport || parsed.error !== ACCEPTANCE_REPORT_NOT_FOUND) {
 		ledger.childReportParseError = parsed.error;
 		ledger.runtimeChecks.push({ id: "attestation", status: "failed", message: parsed.error ?? "Structured acceptance report missing." });
-		ledger.status = "rejected";
-		return ledger;
+		if (!input.reportOptional) {
+			ledger.status = "rejected";
+			return ledger;
+		}
+	} else {
+		ledger.childReportParseError = parsed.error;
 	}
 
-	if (LEVEL_RANK[acceptance.level] >= LEVEL_RANK.checked) {
+	if (parsed.report && LEVEL_RANK[acceptance.level] >= LEVEL_RANK.checked) {
 		ledger.runtimeChecks = [
+			...ledger.runtimeChecks,
 			...checkCriteriaSatisfied(acceptance.criteria, parsed.report),
 			...runStructuralChecks(acceptance, parsed.report, input.cwd),
 		];
-		if (ledger.runtimeChecks.some((check) => check.status === "failed")) {
-			ledger.status = "rejected";
-			return ledger;
+		if (!ledger.runtimeChecks.some((check) => check.status === "failed")) {
+			ledger.status = "checked";
 		}
-		ledger.status = "checked";
 	}
 
 	if (LEVEL_RANK[acceptance.level] >= LEVEL_RANK.verified && (acceptance.level === "verified" || acceptance.verify.length > 0)) {
@@ -1087,7 +1121,15 @@ export async function evaluateAcceptance(input: {
 			ledger.status = "rejected";
 			return ledger;
 		}
-		ledger.status = "verified";
+		if (!ledger.runtimeChecks.some((check) => check.status === "failed")) ledger.status = "verified";
+	}
+
+	if (ledger.runtimeChecks.some((check) => check.status === "failed")) {
+		ledger.status = "rejected";
+		return ledger;
+	}
+	if (ledger.status === "claimed" && acceptance.level !== "reviewed") {
+		ledger.status = acceptance.level === "verified" ? "verified" : acceptance.level;
 	}
 
 	if (acceptance.level === "reviewed") {

package/src/runs/shared/agent-contract.ts

@@ -0,0 +1,38 @@
+import type { AgentContract, EffectsProjection, ExecutionProjection, ReviewProjection, SingleResult } from "../../shared/types.ts";
+
+export function isAgentContractV1(contract: AgentContract | undefined): boolean {
+	return contract?.version === 1;
+}
+
+export function buildExecutionProjection(result: Pick<SingleResult, "exitCode" | "error" | "interrupted" | "timedOut" | "stopped" | "detached">): ExecutionProjection {
+	if (result.detached) {
+		return { status: "detached", success: false, exitCode: result.exitCode, detached: true, ...(result.error ? { error: result.error } : {}) };
+	}
+	if (result.stopped) {
+		return { status: "stopped", success: false, exitCode: result.exitCode, stopped: true, ...(result.error ? { error: result.error } : {}) };
+	}
+	if (result.interrupted) {
+		return { status: "paused", success: true, exitCode: result.exitCode, interrupted: true, ...(result.error ? { error: result.error } : {}) };
+	}
+	const success = result.exitCode === 0 && !result.error && !result.timedOut;
+	return {
+		status: success ? "completed" : "failed",
+		success,
+		exitCode: result.exitCode,
+		...(result.error ? { error: result.error } : {}),
+		...(result.timedOut ? { timedOut: true } : {}),
+	};
+}
+
+export function buildReviewProjection(result: Pick<SingleResult, "acceptance">): ReviewProjection {
+	const review = result.acceptance?.reviewResult;
+	if (!review) return { status: "not-requested" };
+	return { status: review.status, findings: review.findings };
+}
+
+export function attachContractProjections<T extends SingleResult>(result: T): T {
+	result.execution = buildExecutionProjection(result);
+	result.review = buildReviewProjection(result);
+	if (!result.effects) result.effects = {} satisfies EffectsProjection;
+	return result;
+}

package/src/runs/shared/child-protocol.ts

@@ -3,7 +3,7 @@ import type { ProtocolOutputLimit } from "../../shared/types.ts";
 
 export type { ProtocolOutputLimit } from "../../shared/types.ts";
 
-export const MAX_CHILD_PENDING_LINE_BYTES = 4 * 1024 * 1024;
+export const MAX_CHILD_PENDING_LINE_BYTES = 16 * 1024 * 1024;
 export const MAX_CHILD_STDERR_BYTES = 128 * 1024;
 const MAX_PROTOCOL_DIAGNOSTIC_BYTES = 4096;
 

package/src/runs/shared/completion-guard.ts

@@ -1,5 +1,5 @@
 import type { Message } from "@earendil-works/pi-ai";
-import { isMutatingBashCommand } from "./long-running-guard.ts";
+import { isMutatingTool } from "./long-running-guard.ts";
 import { expectsImplementationMutation } from "./task-intent.ts";
 
 export { expectsImplementationMutation };
@@ -16,6 +16,12 @@ const READ_ONLY_BUILTIN_TOOLS = new Set([
 	"contact_supervisor",
 ]);
 
+// Cursor native edit/write often land as thinking traces (inactive_trace /
+// transcript_trace) rather than toolCall parts when native tool replay is off
+// or the tool is inactive in context. Match pi-cursor-sdk display labels.
+const CURSOR_FILE_MUTATION_THINKING =
+	/(?:^|\n)\s*Cursor (?:edit|write)\s*:/i;
+
 interface CompletionMutationGuardInput {
 	agent: string;
 	task: string;
@@ -31,21 +37,46 @@ interface CompletionMutationGuardResult {
 }
 
 export function hasMutationToolCapability(tools: string[] | undefined, mcpDirectTools: string[] | undefined): boolean {
-	if (tools === undefined || tools.length === 0 || (mcpDirectTools?.length ?? 0) > 0) return true;
+	if ((mcpDirectTools?.length ?? 0) > 0) return true;
+	if (tools === undefined) return true;
 	return !tools.every((tool) => READ_ONLY_BUILTIN_TOOLS.has(tool));
 }
 
+function hasCheckpointMutationEvidence(message: Message): boolean {
+	const record = message as unknown as {
+		role?: string;
+		type?: string;
+		customType?: unknown;
+		data?: unknown;
+		details?: unknown;
+	};
+	if ((record.role !== "custom" && record.type !== "custom") || record.customType !== "pi-checkpoint") return false;
+	const details = typeof record.details === "object" && record.details !== null && !Array.isArray(record.details)
+		? record.details as Record<string, unknown>
+		: undefined;
+	const data = typeof record.data === "object" && record.data !== null && !Array.isArray(record.data)
+		? record.data as Record<string, unknown>
+		: typeof details?.beforeCommit === "string" || typeof details?.afterCommit === "string"
+			? details
+			: details?.data && typeof details.data === "object" && !Array.isArray(details.data)
+				? details.data as Record<string, unknown>
+				: undefined;
+	return typeof data?.beforeCommit === "string"
+		&& typeof data.afterCommit === "string"
+		&& data.beforeCommit !== data.afterCommit;
+}
+
 export function hasMutationToolCall(messages: Message[]): boolean {
 	for (const message of messages) {
+		if (hasCheckpointMutationEvidence(message)) return true;
 		if (message.role !== "assistant") continue;
 		for (const part of message.content) {
+			if (part.type === "thinking" && CURSOR_FILE_MUTATION_THINKING.test(part.thinking)) return true;
 			if (part.type !== "toolCall") continue;
-			if (part.name === "edit" || part.name === "write") return true;
-			if (part.name !== "bash") continue;
 			const args = typeof part.arguments === "object" && part.arguments !== null && !Array.isArray(part.arguments)
 				? part.arguments as Record<string, unknown>
 				: {};
-			if (typeof args.command === "string" && isMutatingBashCommand(args.command)) return true;
+			if (isMutatingTool(part.name, args)) return true;
 		}
 	}
 	return false;

package/src/runs/shared/context-mode.ts

@@ -0,0 +1,44 @@
+export type ContextMode = "fresh" | "fork";
+export type ContextSummary = ContextMode | "mixed";
+
+export function isContextMode(value: unknown): value is ContextMode {
+	return value === "fresh" || value === "fork";
+}
+
+export function isContextSummary(value: unknown): value is ContextSummary {
+	return isContextMode(value) || value === "mixed";
+}
+
+export function summarizeContextModes(modes: Array<ContextMode | undefined>): ContextSummary | undefined {
+	const resolved = modes.filter(isContextMode);
+	if (resolved.length === 0) return undefined;
+	const first = resolved[0]!;
+	return resolved.every((mode) => mode === first) ? first : "mixed";
+}
+
+export function contextModeLabel(mode: ContextMode | ContextSummary | undefined): string {
+	if (mode === "fork") return "[fork]";
+	if (mode === "fresh") return "[fresh]";
+	if (mode === "mixed") return "[mixed]";
+	return "";
+}
+
+export function contextModeBadge(
+	theme: { fg(name: string, text: string): string },
+	mode: ContextMode | ContextSummary | undefined,
+): string {
+	const label = contextModeLabel(mode);
+	if (!label) return "";
+	if (mode === "fork") return theme.fg("warning", ` ${label}`);
+	return theme.fg("dim", ` ${label}`);
+}
+
+export function contextModePrefix(
+	theme: { fg(name: string, text: string): string },
+	mode: ContextMode | ContextSummary | undefined,
+): string {
+	const label = contextModeLabel(mode);
+	if (!label) return "";
+	if (mode === "fork") return `${theme.fg("warning", label)} `;
+	return `${theme.fg("dim", label)} `;
+}

package/src/runs/shared/dynamic-fanout.ts

@@ -42,11 +42,11 @@ const SAFE_OUTPUT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const ITEM_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const ITEM_REF_PATTERN = /\{([A-Za-z_][A-Za-z0-9_]*)(?:\.([^{}]+))?\}/g;
 const RESERVED_TEMPLATE_NAMES = new Set(["task", "previous", "chain_dir", "outputs"]);
-const DYNAMIC_STEP_KEYS = new Set(["expand", "parallel", "collect", "concurrency", "failFast", "phase", "label", "acceptance"]);
+const DYNAMIC_STEP_KEYS = new Set(["expand", "parallel", "collect", "concurrency", "failFast", "phase", "label", "acceptance", "agentContract", "gateOn"]);
 const RUNNER_DYNAMIC_STEP_KEYS = new Set([...DYNAMIC_STEP_KEYS, "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "sessionFiles", "thinkingOverrides"]);
 const DYNAMIC_EXPAND_KEYS = new Set(["from", "item", "key", "maxItems", "onEmpty"]);
 const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
-const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "toolBudget", "acceptance"]);
+const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "toolBudget", "acceptance", "agentContract", "gateOn"]);
 const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
 	...DYNAMIC_PARALLEL_KEYS,
 	"outputName", "structured", "inheritProjectContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "waitToolEnabled",
@@ -288,9 +288,9 @@ export function collectDynamicResults(
 	});
 }
 
-export function validateDynamicCollection(schema: JsonSchemaObject | undefined, value: DynamicCollectedResult[]): void {
+export async function validateDynamicCollection(schema: JsonSchemaObject | undefined, value: DynamicCollectedResult[]): Promise<void> {
 	if (!schema) return;
-	const validation = validateStructuredOutputValue(schema, value);
+	const validation = await validateStructuredOutputValue(schema, value);
 	if (validation.status === "invalid") {
 		throw new DynamicFanoutError(`Collected output validation failed: ${validation.message}`);
 	}

package/src/runs/shared/long-running-guard.ts

@@ -103,6 +103,10 @@ export function isMutatingBashCommand(command: string): boolean {
 export function isMutatingTool(toolName: string | undefined, args: Record<string, unknown> | undefined): boolean {
 	if (!toolName) return false;
 	if (toolName === "edit" || toolName === "write") return true;
+	if (toolName === "cursor") {
+		const activityTitle = typeof args?.activityTitle === "string" ? args.activityTitle : "";
+		return /^Cursor (?:edit|write)\b/i.test(activityTitle);
+	}
 	if (toolName !== "bash") return false;
 	const command = typeof args?.command === "string" ? args.command : "";
 	if (!command.trim()) return false;

package/src/runs/shared/nested-events.ts

@@ -612,7 +612,9 @@ export function projectNestedEvents(route: NestedRoute): NestedRegistry {
 		} catch {
 			continue;
 		}
-		for (const event of parseNestedEventRecords(content, route)) {
+		const records = parseNestedEventRecords(content, route);
+		if (records.length === 0) continue;
+		for (const event of records) {
 			registry = applyNestedEvent(registry, event);
 			changed = true;
 		}
@@ -620,11 +622,34 @@ export function projectNestedEvents(route: NestedRoute): NestedRegistry {
 		changed = true;
 	}
 	if (changed) {
-		registry = { ...registry, processedEvents: [...seen].slice(-1000) };
+		const processedEvents = [...seen];
+		const retainedEvents = processedEvents.slice(-1000);
+		const evictedEvents = processedEvents.slice(0, -1000);
+		registry = { ...registry, processedEvents: retainedEvents };
 		// Parent projection is the only writer to this sidecar registry. Child and
 		// runner processes only create immutable event files, so parent status.json
 		// remains owned by the existing runner writer and is never rewritten here.
 		writeAtomicJson(registryPath(route), registry);
+
+		// The registry retains only a bounded filename cursor. Remove the old
+		// immutable status records after the cursor is durable; otherwise an evicted
+		// filename is rediscovered on the next projection and replayed forever.
+		for (const entry of evictedEvents) {
+			const eventPath = path.join(route.eventSink, entry);
+			if (!containedPath(route.eventSink, eventPath)) continue;
+			try {
+				const stat = fs.statSync(eventPath);
+				if (!stat.isFile() || stat.size > MAX_EVENT_BYTES) continue;
+				const content = fs.readFileSync(eventPath, "utf-8");
+				const hasStatusRecord = parseNestedEventRecords(content, route).length > 0;
+				const hasControlResult = content
+					.split("\n")
+					.some((line) => line.trim() && parseControlResult(line.trim(), route));
+				if (hasStatusRecord && !hasControlResult) fs.unlinkSync(eventPath);
+			} catch {
+				// A cleanup failure must not make a successfully projected status fail.
+			}
+		}
 	}
 	return registry;
 }

package/src/runs/shared/parallel-handoff.ts

@@ -0,0 +1,154 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import type {
+	ParallelHandoffGroup,
+	ParallelHandoffManifest,
+	ParallelHandoffReference,
+	SubagentResultStatus,
+} from "../../shared/types.ts";
+import type {
+	WorktreeCleanupReport,
+	WorktreeDiff,
+	WorktreeSetup,
+} from "./worktree.ts";
+
+export interface ParallelHandoffResult {
+	agent: string;
+	status: SubagentResultStatus;
+	summary: string;
+	outputPath?: string;
+	structuredOutput?: unknown;
+	structuredOutputPath?: string;
+	sessionPath?: string;
+}
+
+function readManifest(manifestPath: string): ParallelHandoffManifest | undefined {
+	if (!fs.existsSync(manifestPath)) return undefined;
+	const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf-8")) as ParallelHandoffManifest;
+	if (parsed.version !== 1 || !Array.isArray(parsed.groups)) {
+		throw new Error(`Invalid parallel handoff manifest: ${manifestPath}`);
+	}
+	return parsed;
+}
+
+function referenceFor(manifestPath: string, manifest: ParallelHandoffManifest): ParallelHandoffReference {
+	const children = manifest.groups.flatMap((group) => group.children);
+	return {
+		version: 1,
+		path: manifestPath,
+		groupCount: manifest.groups.length,
+		childCount: children.length,
+		changedPatches: children.filter((child) => child.patch.changed).length,
+		cleanupState: manifest.groups.every((group) => group.cleanup.state === "complete") ? "complete" : "partial",
+	};
+}
+
+function safeHandoffAgentName(agent: string): string {
+	return agent.replace(/[^\w.-]/g, "_");
+}
+
+function missingDiff(input: { manifestPath: string; stepIndex: number; taskIndex: number; agent: string; branch?: string }): WorktreeDiff {
+	const patchPath = path.join(path.dirname(input.manifestPath), `missing-diff-step-${input.stepIndex}-task-${input.taskIndex}-${safeHandoffAgentName(input.agent)}.patch`);
+	try {
+		fs.mkdirSync(path.dirname(patchPath), { recursive: true });
+		fs.writeFileSync(patchPath, "", "utf-8");
+	} catch {
+		// Handoff records the artifact failure below; patch creation remains best-effort.
+	}
+	return {
+		index: input.taskIndex,
+		agent: input.agent,
+		branch: input.branch ?? "",
+		diffStat: "",
+		filesChanged: 0,
+		insertions: 0,
+		deletions: 0,
+		patchPath,
+		error: "diff artifact unavailable; no patch was captured",
+	};
+}
+
+export function writeParallelHandoffGroup(input: {
+	manifestPath: string;
+	runId: string;
+	mode: "parallel" | "chain";
+	source: "foreground" | "async";
+	cwd: string;
+	stepIndex: number;
+	flatStartIndex: number;
+	setup: WorktreeSetup;
+	diffs: WorktreeDiff[];
+	cleanup: WorktreeCleanupReport;
+	results: ParallelHandoffResult[];
+	now?: number;
+}): ParallelHandoffReference {
+	const now = input.now ?? Date.now();
+	const existing = readManifest(input.manifestPath);
+	if (existing && (existing.runId !== input.runId || existing.mode !== input.mode || existing.source !== input.source)) {
+		throw new Error(`Parallel handoff manifest belongs to a different run: ${input.manifestPath}`);
+	}
+	const group: ParallelHandoffGroup = {
+		stepIndex: input.stepIndex,
+		baseCommit: input.setup.baseCommit,
+		repoRoot: input.setup.cwd,
+		children: input.results.map((result, taskIndex) => {
+			const diff = input.diffs[taskIndex] ?? missingDiff({
+				manifestPath: input.manifestPath,
+				stepIndex: input.stepIndex,
+				taskIndex,
+				agent: result.agent,
+				branch: input.setup.worktrees[taskIndex]?.branch,
+			});
+			return {
+				index: input.flatStartIndex + taskIndex,
+				taskIndex,
+				agent: result.agent,
+				status: result.status,
+				summary: result.summary,
+				...(result.outputPath ? { outputPath: result.outputPath } : {}),
+				...(result.structuredOutput !== undefined ? { structuredOutput: result.structuredOutput } : {}),
+				...(result.structuredOutputPath ? { structuredOutputPath: result.structuredOutputPath } : {}),
+				...(result.sessionPath ? { sessionPath: result.sessionPath } : {}),
+				patch: {
+					path: diff.patchPath,
+					branch: diff.branch,
+					changed: diff.filesChanged > 0 || diff.insertions > 0 || diff.deletions > 0 || diff.diffStat.trim().length > 0,
+					diffStat: diff.diffStat,
+					filesChanged: diff.filesChanged,
+					insertions: diff.insertions,
+					deletions: diff.deletions,
+					...(diff.error ? { error: diff.error } : {}),
+				},
+			};
+		}),
+		cleanup: input.cleanup,
+	};
+	const groups = existing?.groups.filter((candidate) => candidate.stepIndex !== input.stepIndex) ?? [];
+	groups.push(group);
+	groups.sort((left, right) => left.stepIndex - right.stepIndex);
+	const manifest: ParallelHandoffManifest = {
+		version: 1,
+		runId: input.runId,
+		mode: input.mode,
+		source: input.source,
+		cwd: input.cwd,
+		createdAt: existing?.createdAt ?? now,
+		updatedAt: now,
+		groups,
+	};
+	writeAtomicJson(input.manifestPath, manifest);
+	return referenceFor(input.manifestPath, manifest);
+}
+
+export function parallelHandoffPath(baseDir: string, runId?: string): string {
+	return runId ? path.join(baseDir, "handoffs", `${runId}.json`) : path.join(baseDir, "handoff.json");
+}
+
+export function formatParallelHandoffReference(reference: ParallelHandoffReference): string {
+	return `Parallel handoff: ${reference.path} (${reference.childCount} children, ${reference.changedPatches} changed patches, cleanup ${reference.cleanupState})`;
+}
+
+export function formatParallelHandoffError(error: unknown): string {
+	return `Parallel handoff unavailable: ${error instanceof Error ? error.message : String(error)}`;
+}

package/src/runs/shared/parallel-utils.ts

@@ -3,6 +3,8 @@ export interface RunnerSubagentStep {
 	parentSessionId?: string;
 	agent: string;
 	task: string;
+	/** Resolved launch context for this child. */
+	context?: "fresh" | "fork";
 	importAsyncRoot?: {
 		runId: string;
 		asyncDir: string;
@@ -40,9 +42,11 @@ export interface RunnerSubagentStep {
 		outputPath: string;
 	};
 	structuredOutputSchema?: import("../../shared/types.ts").JsonSchemaObject;
+	agentContract?: import("../../shared/types.ts").AgentContract;
 	effectiveAcceptance?: import("../../shared/types.ts").ResolvedAcceptanceConfig;
 	acceptanceInput?: import("../../shared/types.ts").AcceptanceInput;
 	acceptanceRole?: import("../../shared/types.ts").AcceptanceRole;
+	gateOn?: import("../../shared/types.ts").ChainGateLayer;
 	toolBudget?: import("../../shared/types.ts").ResolvedToolBudget;
 }
 
@@ -66,6 +70,8 @@ export interface DynamicRunnerGroup {
 	effectiveAcceptance?: import("../../shared/types.ts").ResolvedAcceptanceConfig;
 	acceptanceInput?: import("../../shared/types.ts").AcceptanceInput;
 	acceptanceRole?: import("../../shared/types.ts").AcceptanceRole;
+	agentContract?: import("../../shared/types.ts").AgentContract;
+	gateOn?: import("../../shared/types.ts").ChainGateLayer;
 }
 
 export type RunnerStep = RunnerSubagentStep | ParallelStepGroup | DynamicRunnerGroup;

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

@@ -4,13 +4,15 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { encodeNestedPathEnv, parseNestedPathEnv, type NestedPathEntry } from "./nested-path.ts";
 import { resolveMcpDirectToolNames } from "./mcp-direct-tool-allowlist.ts";
+import { resolvePiPackageRoot } from "./pi-spawn.ts";
 import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV } from "./structured-output.ts";
 import { TEMP_ROOT_DIR, type JsonSchemaObject, type ResolvedToolBudget } from "../../shared/types.ts";
 import { THINKING_LEVELS } from "../../shared/model-info.ts";
-import { TOOL_BUDGET_ENV, encodeToolBudgetEnv } from "./tool-budget.ts";
+import { TOOL_BUDGET_ENV, TOOL_BUDGET_ZERO_AUTH_ENV, encodeToolBudgetEnv } from "./tool-budget.ts";
 import { CHILD_TOOL_DIAGNOSTIC_PATH_ENV, REQUIRED_CHILD_TOOLS_ENV } from "./tool-availability.ts";
 import { CHILD_WATCHDOG_CONFIG_ENV, encodeChildWatchdogConfig, type ChildWatchdogConfig } from "../../watchdog/child-status.ts";
 import { WAIT_TOOL_ENABLED_ENV } from "../background/wait-config.ts";
+import { PI_CODING_AGENT_PACKAGE_ROOT_ENV } from "../../shared/utils.ts";
 
 const TASK_ARG_LIMIT = 8000;
 const PROMPT_RUNTIME_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-prompt-runtime.ts");
@@ -78,6 +80,7 @@ interface BuildPiArgsInput {
 		outputPath: string;
 	};
 	toolBudget?: ResolvedToolBudget;
+	allowZeroToolBudget?: boolean;
 	childWatchdog?: ChildWatchdogConfig;
 	waitToolEnabled?: boolean;
 }
@@ -127,27 +130,30 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 		args.push("--model", modelArg);
 	}
 
+	const explicitToolAllowlist = input.tools !== undefined || (input.mcpDirectTools?.length ?? 0) > 0;
 	const declaredBuiltinToolsBase = input.tools?.filter((tool) => !(tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) ?? [];
-	const declaredBuiltinTools = input.requireReadTool && input.tools?.length && !declaredBuiltinToolsBase.includes("read")
+	const declaredBuiltinTools = input.requireReadTool && declaredBuiltinToolsBase.length > 0 && !declaredBuiltinToolsBase.includes("read")
 		? ["read", ...declaredBuiltinToolsBase]
 		: declaredBuiltinToolsBase;
 	const fanoutAuthorized = declaredBuiltinTools.includes("subagent");
 	const toolExtensionPaths: string[] = [];
 	let requiredChildTools: string[] = [];
-	if (input.tools?.length) {
-		const allowedTools = [...declaredBuiltinTools];
-		for (const tool of input.tools) {
-			if (!declaredBuiltinTools.includes(tool) && (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) {
-				toolExtensionPaths.push(tool);
-			}
+	for (const tool of input.tools ?? []) {
+		if (!declaredBuiltinTools.includes(tool) && (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) {
+			toolExtensionPaths.push(tool);
 		}
-		if (allowedTools.length > 0) {
-			if (input.mcpDirectTools?.length) {
-				allowedTools.push(...resolveMcpDirectToolNames(input.mcpDirectTools, input.cwd));
-			}
-			if (input.structuredOutput) allowedTools.push("structured_output");
-			requiredChildTools = [...new Set(allowedTools)];
+	}
+	if (explicitToolAllowlist) {
+		const allowedTools = [
+			...declaredBuiltinTools,
+			...resolveMcpDirectToolNames(input.mcpDirectTools, input.cwd),
+			...(input.structuredOutput ? ["structured_output"] : []),
+		];
+		requiredChildTools = [...new Set(allowedTools)];
+		if (requiredChildTools.length > 0) {
 			args.push("--tools", requiredChildTools.join(","));
+		} else {
+			args.push("--no-tools");
 		}
 	}
 
@@ -190,6 +196,8 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	}
 
 	const env: Record<string, string | undefined> = {};
+	const piPackageRoot = process.env[PI_CODING_AGENT_PACKAGE_ROOT_ENV] ?? resolvePiPackageRoot();
+	if (piPackageRoot) env[PI_CODING_AGENT_PACKAGE_ROOT_ENV] = piPackageRoot;
 	let toolDiagnosticPath: string | undefined;
 	if (requiredChildTools.length > 0) {
 		if (!tempDir) tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
@@ -278,6 +286,7 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	if (input.steerAckDir) env[SUBAGENT_STEER_ACK_DIR_ENV] = input.steerAckDir;
 	const encodedToolBudget = encodeToolBudgetEnv(input.toolBudget);
 	if (encodedToolBudget) env[TOOL_BUDGET_ENV] = encodedToolBudget;
+	env[TOOL_BUDGET_ZERO_AUTH_ENV] = input.allowZeroToolBudget ? "1" : undefined;
 	const encodedChildWatchdog = encodeChildWatchdogConfig(input.childWatchdog);
 	if (encodedChildWatchdog) env[CHILD_WATCHDOG_CONFIG_ENV] = encodedChildWatchdog;