pi-subagents 0.35.1 → 0.37.0

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

@@ -42,15 +42,15 @@ 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",
-	"structuredOutput", "structuredOutputSchema", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "completionGuard", "systemPrompt",
+	"structuredOutput", "structuredOutputSchema", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "capabilityCeiling", "completionGuard", "systemPrompt",
 	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId",
 ]);
 const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);
@@ -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/mcp-direct-tool-allowlist.ts

@@ -69,14 +69,16 @@ interface MetadataCache {
 	servers: Record<string, ServerCacheEntry>;
 }
 
-export function resolveMcpDirectToolNames(mcpDirectTools: string[] | undefined, cwd = process.cwd()): string[] {
+export interface ResolvedMcpDirectToolSelection { name: string; selector: string }
+
+export function resolveMcpDirectToolSelections(mcpDirectTools: string[] | undefined, cwd = process.cwd()): ResolvedMcpDirectToolSelection[] {
 	if (!mcpDirectTools?.length) return [];
 
 	try {
 		const config = loadMcpConfig(cwd);
 		const cache = loadMetadataCache();
 		if (!cache) return [];
-		return resolveDirectToolNames(config, cache, getToolPrefix(config.settings?.toolPrefix), mcpDirectTools);
+		return resolveDirectToolSelections(config, cache, getToolPrefix(config.settings?.toolPrefix), mcpDirectTools);
 	} catch {
 		return [];
 	}
@@ -195,8 +197,8 @@ function extractServers(config: unknown, kind: ImportKind): Record<string, Serve
 	return servers && typeof servers === "object" && !Array.isArray(servers) ? servers as Record<string, ServerEntry> : {};
 }
 
-function resolveDirectToolNames(config: McpConfig, cache: MetadataCache, prefix: ToolPrefix, envOverride: string[]): string[] {
-	const names: string[] = [];
+function resolveDirectToolSelections(config: McpConfig, cache: MetadataCache, prefix: ToolPrefix, envOverride: string[]): ResolvedMcpDirectToolSelection[] {
+	const names: ResolvedMcpDirectToolSelection[] = [];
 	const seenNames = new Set<string>();
 	const { servers: selectedServers, tools: selectedTools } = parseSelections(envOverride);
 
@@ -216,7 +218,7 @@ function resolveDirectToolNames(config: McpConfig, cache: MetadataCache, prefix:
 			const prefixedName = formatToolName(tool.name, serverName, prefix);
 			if (BUILTIN_TOOL_NAMES.has(prefixedName) || seenNames.has(prefixedName)) continue;
 			seenNames.add(prefixedName);
-			names.push(prefixedName);
+			names.push({ name: prefixedName, selector: `${serverName}/${tool.name}` });
 		}
 
 		if (definition.exposeResources === false) continue;
@@ -228,13 +230,17 @@ function resolveDirectToolNames(config: McpConfig, cache: MetadataCache, prefix:
 			const prefixedName = formatToolName(baseName, serverName, prefix);
 			if (BUILTIN_TOOL_NAMES.has(prefixedName) || seenNames.has(prefixedName)) continue;
 			seenNames.add(prefixedName);
-			names.push(prefixedName);
+			names.push({ name: prefixedName, selector: `${serverName}/${baseName}` });
 		}
 	}
 
 	return names;
 }
 
+export function resolveMcpDirectToolNames(mcpDirectTools: string[] | undefined, cwd = process.cwd()): string[] {
+	return resolveMcpDirectToolSelections(mcpDirectTools, cwd).map((selection) => selection.name);
+}
+
 function parseSelections(selections: string[]): { servers: Set<string>; tools: Map<string, Set<string>> } {
 	const servers = new Set<string>();
 	const tools = new Map<string, Set<string>>();

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

@@ -27,6 +27,7 @@ import {
 	SUBAGENT_PARENT_RUN_ID_ENV,
 } from "./pi-args.ts";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { sanitizeProcessTerminal } from "../background/process-terminal.ts";
 
 export const NESTED_EVENTS_DIR = path.join(TEMP_ROOT_DIR, "nested-subagent-events");
 const ROUTE_FILE = "route.json";
@@ -612,7 +613,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 +623,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;
 }
@@ -848,6 +874,9 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
 		...(status.pid ? { pid: status.pid } : {}),
 		...(status.sessionId ? { sessionId: status.sessionId } : {}),
 		mode: status.mode ?? fallback.mode,
+		...(status.processTerminal ? { processTerminal: sanitizeProcessTerminal(status.processTerminal, { runId: status.runId || fallback.id, runnerProcessInstanceId: status.processTerminal.runnerProcessInstanceId }, `${asyncDir}/status.json`) } : {}),
+		...(status.capabilityCeiling ? { capabilityCeiling: status.capabilityCeiling } : {}),
+		...(status.capabilityAudit ? { capabilityAudit: status.capabilityAudit } : {}),
 		state: status.state,
 		...(status.currentStep !== undefined ? { currentStep: status.currentStep } : {}),
 		...(status.chainStepCount !== undefined ? { chainStepCount: status.chainStepCount } : {}),
@@ -871,7 +900,7 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
 		...(status.endedAt !== undefined ? { endedAt: status.endedAt } : {}),
 		lastUpdate: status.lastUpdate ?? fallback.ts,
 		...(status.sessionFile ? { sessionFile: status.sessionFile } : {}),
-		...(status.steps?.length ? { steps: status.steps.map((step) => ({
+		...(status.steps?.length ? { steps: status.steps.map((step, index) => ({
 			agent: step.agent,
 			status: step.status,
 			...(step.sessionFile ? { sessionFile: step.sessionFile } : {}),
@@ -890,6 +919,9 @@ export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: stri
 			...(step.turnBudget ? { turnBudget: step.turnBudget } : {}),
 			...(step.turnBudgetExceeded !== undefined ? { turnBudgetExceeded: step.turnBudgetExceeded } : {}),
 			...(step.wrapUpRequested !== undefined ? { wrapUpRequested: step.wrapUpRequested } : {}),
+			...(step.processTerminal ? { processTerminal: sanitizeProcessTerminal(step.processTerminal, { runId: status.runId || fallback.id, runnerProcessInstanceId: step.processTerminal.runnerProcessInstanceId }, `${asyncDir}/status.json step ${index}`) } : {}),
+			...(step.capabilityCeiling ? { capabilityCeiling: step.capabilityCeiling } : {}),
+			...(step.capabilityAudit ? { capabilityAudit: step.capabilityAudit } : {}),
 		})).slice(0, MAX_STEPS) } : {}),
 	};
 }

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,10 +42,17 @@ export interface RunnerSubagentStep {
 		outputPath: string;
 	};
 	structuredOutputSchema?: import("../../shared/types.ts").JsonSchemaObject;
+	agentContract?: import("../../shared/types.ts").AgentContract;
+	definitionDigest?: string;
+	launchBindingTask?: string;
+	launchContractDigest?: string;
 	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;
+	capabilityCeiling?: import("./capability-ceiling.ts").ResolvedSubagentCapabilityCeiling;
+	capabilityAudit?: import("./capability-ceiling.ts").SubagentCapabilityAudit;
 }
 
 export interface ParallelStepGroup {
@@ -66,6 +75,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;