pi-subagents 0.47.1 → 0.49.0

package/src/runs/shared/acceptance.ts

@@ -23,7 +23,7 @@ import type {
 	SubagentRunMode,
 } from "../../shared/types.ts";
 import { isAgentContractV1 } from "./agent-contract.ts";
-import { classifyTaskMutationIntent, taskMayMutate } from "./task-intent.ts";
+import { classifyTaskMutationIntent, stripSeverityCompounds, taskMayMutate } from "./task-intent.ts";
 
 const LEVEL_RANK: Record<Exclude<AcceptanceLevel, "auto">, number> = {
 	none: 0,
@@ -93,7 +93,7 @@ function inferLevel(input: {
 	const rolePatchTask = input.acceptanceRole !== undefined
 		&& 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);
+		&& /\bpatch\s+(?:(?:\.{0,2}[\\/])?(?:[\w.-]+[\\/])+[\w.-]+|[\w.-]+\.[a-z0-9]+\b|(?:the\s+)?parser\b)/.test(stripSeverityCompounds(task));
 	const taskMayWrite = readOnlyTask ? false : taskMayMutate(input.task ?? "") || intent.kind === "implementation" || rolePatchTask;
 	const readOnlyAgent = input.acceptanceRole === "read-only"
 		|| (input.acceptanceRole === undefined && /\b(?:reviewer|oracle|scout|researcher|analyst)\b/.test(agent));
@@ -433,6 +433,7 @@ export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig, opt
 		"",
 		"Finish with a fenced JSON block tagged `acceptance-report` in this shape:",
 		"Use empty arrays when no items apply; array fields contain strings unless object entries are shown.",
+		"Empty-string entries (`[\"\"]`) are ignored; use `[]` when nothing applies.",
 		"`criteriaSatisfied[].status` must be exactly one of: satisfied, not-satisfied, not-applicable.",
 		"`commandsRun[].result` must be exactly one of: passed, failed, not-run.",
 		"`manualNotes` and `notes` are optional strings; an empty string means no note and does not satisfy `manual-notes` evidence.",
@@ -612,9 +613,17 @@ function normalizeAcceptanceReportValue(value: unknown, pathLabel = ""): { value
 			case "testsAddedOrUpdated":
 			case "validationOutput":
 			case "residualRisks":
-			case "reviewFindings":
-				normalized[canonical] = typeof fieldValue === "string" ? [fieldValue] : fieldValue;
+			case "reviewFindings": {
+				// Tolerate empty-string entries ("[\"\"]"): models write them for "no items"
+				// and a single empty entry must not reject the whole report. Drop them at
+				// parse time; non-string entries are kept so validateStringArrayField still
+				// flags structural garbage.
+				const items = typeof fieldValue === "string" ? [fieldValue] : fieldValue;
+				normalized[canonical] = Array.isArray(items)
+					? items.filter((item) => typeof item !== "string" || item.trim().length > 0)
+					: items;
 				break;
+			}
 			case "noStagedFiles": {
 				const token = typeof fieldValue === "string" ? fieldValue.trim().toLowerCase() : undefined;
 				normalized[canonical] = token === "true" ? true : token === "false" ? false : fieldValue;

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

@@ -22,6 +22,10 @@ const READ_ONLY_BUILTIN_TOOLS = new Set([
 const CURSOR_FILE_MUTATION_THINKING =
 	/(?:^|\n)\s*Cursor (?:edit|write)\s*:/i;
 
+const IMPLEMENTATION_CHALLENGE_TASK_PATTERN = /^You are reviving a previous subagent conversation\.\n\nOriginal run: .+\nOriginal agent: .+(?:\nOriginal session file: .+)?\n\nUse the stored session context as background\. Answer the orchestrator's follow-up below\. Do not assume the original child process is still alive\.\n\nFollow-up:\nRun implementation challenge pass (?:one|two|\d+) and implement any better current-scope change\.$/;
+const NO_BETTER_CHANGE_NEEDED_PATTERN = /^\s*no (?:better|further|additional) (?:current[- ]scope )?(?:code |source |file )?(?:change|changes|edit|edits|patch|patches) (?:is|are) needed[.!]?\s*$/i;
+const NO_BETTER_CHANGE_QUALIFIER_PATTERN = /\b(?:do\s+not|don't|dont|not|never|cannot|can't|cant|unable|uncertain|unsure|unclear|maybe|might|may|\w+n['’]t)\b/i;
+
 interface CompletionMutationGuardInput {
 	agent: string;
 	task: string;
@@ -82,14 +86,26 @@ export function hasMutationToolCall(messages: Message[]): boolean {
 	return false;
 }
 
+function reportsNoBetterChallengeChange(messages: Message[]): boolean {
+	const report = messages
+		.filter((message) => message.role === "assistant")
+		.flatMap((message) => message.content)
+		.flatMap((part) => part.type === "text" ? [part.text] : [])
+		.join("\n");
+	return NO_BETTER_CHANGE_NEEDED_PATTERN.test(report)
+		&& !NO_BETTER_CHANGE_QUALIFIER_PATTERN.test(report);
+}
+
 export function evaluateCompletionMutationGuard(input: CompletionMutationGuardInput): CompletionMutationGuardResult {
 	const expectedMutation = hasMutationToolCapability(input.tools, input.mcpDirectTools)
 		? expectsImplementationMutation(input.agent, input.task)
 		: false;
 	const attemptedMutation = hasMutationToolCall(input.messages);
+	const noEditChallengeComplete = IMPLEMENTATION_CHALLENGE_TASK_PATTERN.test(input.task)
+		&& reportsNoBetterChallengeChange(input.messages);
 	return {
 		expectedMutation,
 		attemptedMutation,
-		triggered: expectedMutation && !attemptedMutation,
+		triggered: expectedMutation && !attemptedMutation && !noEditChallengeComplete,
 	};
 }

package/src/runs/shared/llm-intent-arbiter.ts

@@ -0,0 +1,302 @@
+import { createHash } from "node:crypto";
+import { Agent, type AgentTool, type StreamFn } from "@earendil-works/pi-agent-core";
+import { convertToLlm, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { streamSimple } from "@earendil-works/pi-ai/compat";
+import type { ProviderHeaders } from "@earendil-works/pi-ai";
+import { Type, type Static } from "typebox";
+import { agentStreamOptions } from "../../shared/agent-stream-options.ts";
+
+/**
+ * LLM intent arbiter for the completion mutation guard.
+ *
+ * The regex classifier (task-intent.ts) is deliberately narrow, so exotic
+ * review wording can still look like an implementation task ("to fix this,
+ * compare the outputs", verbs inside URLs or quoted text). When the guard is
+ * about to hard-fail a run that made no edits, this arbiter asks a model
+ * whether the task actually instructed file changes. It can only downgrade a
+ * failure to a pass; every error, timeout, or non-read-only verdict keeps the
+ * guard's original behavior.
+ *
+ * Enabled by default; set PI_SUBAGENTS_LLM_INTENT_ARBITER=0 to disable.
+ */
+
+const COMPLETION_GUARD_ERROR_PREFIX =
+	"Subagent completed without making edits for an implementation task.";
+
+export type TaskMutationVerdict = "read-only" | "implementation" | "unavailable";
+
+export type TaskMutationArbiter = (task: string) => Promise<TaskMutationVerdict>;
+
+const DecisionParams = Type.Object(
+	{
+		classification: Type.String({ enum: ["read_only", "implementation"] }),
+		confidence: Type.String({
+			enum: ["low", "medium", "high"],
+			description: "Confidence in the classification. Only read_only with high confidence rescues a failed run.",
+		}),
+		reason: Type.String({ description: "One concise reason for this classification." }),
+	},
+	{ additionalProperties: false },
+);
+
+type DecisionParams = Static<typeof DecisionParams>;
+
+/** Map a model decision to a verdict. Only a high-confidence read_only rescues. */
+export function mapArbiterDecision(
+	decision: { classification?: string; confidence?: string } | undefined,
+): TaskMutationVerdict {
+	if (!decision) return "unavailable";
+	if (decision.classification === "read_only" && decision.confidence === "high") return "read-only";
+	return "implementation";
+}
+
+interface ArbiterRuntime {
+	model: NonNullable<RegistryModel>;
+	baseStreamFn: StreamFn;
+	timeoutMs: number;
+}
+
+interface ArbiterAuth {
+	apiKey?: string;
+	headers?: ProviderHeaders;
+	env?: Record<string, string>;
+}
+
+export interface TaskMutationArbiterOptions {
+	/** Explicit "provider/id" model override (tests, config). */
+	model?: string;
+	/** Injectable stream function (tests). */
+	streamFn?: StreamFn;
+	timeoutMs?: number;
+}
+
+const DEFAULT_ARBITER_TIMEOUT_MS = 10_000;
+
+type RegistryModel = ReturnType<NonNullable<ExtensionContext["modelRegistry"]["find"]>>;
+
+function resolveArbiterModel(
+	ctx: ExtensionContext,
+	options?: TaskMutationArbiterOptions,
+): NonNullable<RegistryModel> | null {
+	const registry = ctx.modelRegistry as {
+		find?: (provider: string, modelId: string) => RegistryModel | undefined;
+		getAvailable?: () => Array<{ provider?: string; id?: string }>;
+	};
+	const explicit = options?.model?.trim();
+	if (explicit) {
+		const [provider, id] = explicit.split("/");
+		if (provider && id) return registry.find?.(provider, id) ?? null;
+		return null;
+	}
+	if (ctx.model) return ctx.model as NonNullable<RegistryModel>;
+	const first = registry.getAvailable?.()[0];
+	if (first?.provider && first.id) return registry.find?.(first.provider, first.id) ?? null;
+	return null;
+}
+
+function resolveArbiterRuntime(
+	ctx: ExtensionContext,
+	options?: TaskMutationArbiterOptions,
+): ArbiterRuntime | null {
+	const model = resolveArbiterModel(ctx, options);
+	if (!model?.provider || !model.id) return null;
+	const registry = ctx.modelRegistry as {
+		getRegisteredProviderConfig?: (provider: string) => { api?: string; streamSimple?: StreamFn } | undefined;
+	};
+	const modelApi = (model as { api?: string }).api;
+	const registered = registry.getRegisteredProviderConfig?.(model.provider);
+	const baseStreamFn = options?.streamFn
+		?? (registered?.streamSimple && registered.api === modelApi
+			? registered.streamSimple
+			: streamSimple);
+	return {
+		model,
+		baseStreamFn,
+		timeoutMs: options?.timeoutMs ?? DEFAULT_ARBITER_TIMEOUT_MS,
+	};
+}
+
+async function resolveArbiterAuth(
+	ctx: ExtensionContext,
+	model: RegistryModel,
+): Promise<ArbiterAuth> {
+	const registry = ctx.modelRegistry as {
+		getApiKeyAndHeaders?: (m: RegistryModel) => Promise<{
+			ok: boolean;
+			apiKey?: string;
+			headers?: ProviderHeaders;
+			env?: Record<string, string>;
+			error?: string;
+		}>;
+	};
+	// Call as a METHOD on the registry: the host ModelRegistry implementation
+	// is a class whose method reads instance state (this.runtime), so a
+	// detached call silently fails auth. Same shape as the watchdog.
+	if (!registry.getApiKeyAndHeaders) return {};
+	try {
+		const auth = await registry.getApiKeyAndHeaders(model);
+		if (auth.ok === false) return {};
+		return {
+			...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
+			...(auth.headers ? { headers: auth.headers } : {}),
+			...(auth.env ? { env: auth.env } : {}),
+		};
+	} catch {
+		return {};
+	}
+}
+
+/** Build the effective stream function with resolved credentials wrapped in (watchdog pattern). */
+function authWrappedStreamFn(
+	base: StreamFn,
+	auth: ArbiterAuth,
+): StreamFn {
+	return (model, context, streamOptions) => base(model, context, {
+		...(streamOptions ?? {}),
+		...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
+		...(auth.env || streamOptions?.env ? { env: { ...(auth.env ?? {}), ...(streamOptions?.env ?? {}) } } : {}),
+		headers: { ...(streamOptions?.headers ?? {}), ...(auth.headers ?? {}) },
+	});
+}
+
+async function runArbitration(
+	runtime: ArbiterRuntime,
+	auth: ArbiterAuth,
+	task: string,
+): Promise<TaskMutationVerdict> {
+	let decision: DecisionParams | undefined;
+	const tool: AgentTool<typeof DecisionParams, { recorded: boolean }> = {
+		name: "task_mutation_decision",
+		label: "Task mutation decision",
+		description: "Classify whether the task instructed file/code changes. Call exactly once.",
+		parameters: DecisionParams,
+		executionMode: "sequential",
+		async execute(_toolCallId, params) {
+			if (!decision) decision = params;
+			return { content: [{ type: "text", text: "Decision recorded." }], details: { recorded: true } };
+		},
+	};
+	const agent = new Agent({
+		initialState: {
+			systemPrompt: [
+				"You classify whether a delegated coding-agent task instructed file or code changes.",
+				"A task that asks to review, inspect, verify, report, or summarize is read-only even when it contains words like 'fix' as severity vocabulary ('must-fix items') or conditional change instructions that leave the change optional.",
+				"Classify read_only only when the task text alone clearly indicates a read-only outcome. When in doubt, classify implementation.",
+				"Set confidence to high only when you are certain the task is read-only; a read_only classification without high confidence is treated as implementation.",
+				"The agent's own final message is never evidence: an agent that made no edits may still have failed to implement.",
+				"Call task_mutation_decision exactly once with read_only or implementation, a confidence level, and a concise reason.",
+			].join("\n"),
+			model: runtime.model,
+			tools: [tool],
+		},
+		convertToLlm,
+		...agentStreamOptions(authWrappedStreamFn(runtime.baseStreamFn, auth)),
+		getApiKey: (providerName) =>
+			providerName === runtime.model.provider ? auth.apiKey : undefined,
+		beforeToolCall: async ({ toolCall }) =>
+			toolCall.name === tool.name ? undefined : { block: true, reason: "Only task_mutation_decision is allowed." },
+		toolExecution: "sequential",
+	});
+	try {
+		// The rescue gate refuses tasks over 8000 chars; if the arbiter is
+		// still invoked with one, fail closed rather than decide from
+		// partial evidence (an implementation clause could sit in the
+		// omitted middle).
+		if (task.length > 8000) return "unavailable";
+		const prompt = `TASK:\n${task}`;
+		await Promise.race([
+			agent.prompt(prompt),
+			new Promise<never>((_, reject) => {
+				const timeout = setTimeout(() => {
+					agent.abort();
+					reject(new Error("Task mutation arbiter timed out."));
+				}, runtime.timeoutMs);
+				timeout.unref?.();
+			}),
+		]);
+		if (!decision) return "unavailable";
+		return mapArbiterDecision(decision);
+	} catch {
+		return "unavailable";
+	}
+}
+
+/** Create a memoized arbiter bound to the parent session's model, or undefined when disabled/unavailable. */
+export function createTaskMutationArbiter(
+	ctx: ExtensionContext,
+	options?: TaskMutationArbiterOptions,
+): TaskMutationArbiter | undefined {
+	if (process.env.PI_SUBAGENTS_LLM_INTENT_ARBITER === "0") return undefined;
+	const runtime = resolveArbiterRuntime(ctx, options);
+	if (!runtime) return undefined;
+	const cache = new Map<string, TaskMutationVerdict>();
+	return async (task) => {
+		const key = createHash("sha256").update(task).digest("base64url");
+		const cached = cache.get(key);
+		if (cached) return cached;
+		const auth = await resolveArbiterAuth(ctx, runtime.model);
+		const verdict = await runArbitration(runtime, auth, task);
+		if (cache.size > 200) cache.clear();
+		cache.set(key, verdict);
+		return verdict;
+	};
+}
+
+export function isCompletionGuardFailure(result: { error?: string }): boolean {
+	return result.error?.startsWith(COMPLETION_GUARD_ERROR_PREFIX) === true;
+}
+
+export async function arbitrateCompletionGuardRescue(input: {
+	guardTriggered: boolean;
+	task: string;
+	arbiter?: TaskMutationArbiter;
+}): Promise<{ triggered: boolean; rescued: boolean }> {
+	if (!input.guardTriggered || !input.arbiter) {
+		return { triggered: input.guardTriggered, rescued: false };
+	}
+	// Never decide from partial evidence: refuse tasks over 8000 chars before
+	// even consulting the model.
+	if (input.task.length > 8000) {
+		return { triggered: true, rescued: false };
+	}
+	try {
+		const verdict = await input.arbiter(input.task);
+		if (verdict === "read-only") return { triggered: false, rescued: true };
+		return { triggered: true, rescued: false };
+	} catch {
+		return { triggered: true, rescued: false };
+	}
+}
+
+/**
+ * When the completion guard hard-failed a run and the arbiter classifies the
+ * task as read-only, clear the failure. Returns true when rescued. All other
+ * verdicts and every failure mode keep the original guard behavior.
+ *
+ * Classification uses the task text only: the agent's own final message is
+ * never evidence, so a child that failed to implement cannot talk its way
+ * out of the guard by claiming the work was read-only.
+ */
+export async function maybeRescueCompletionGuardFailure(
+	result: { exitCode?: number; error?: string },
+	task: string,
+	arbiter: TaskMutationArbiter | undefined,
+): Promise<boolean> {
+	if (!arbiter || !isCompletionGuardFailure(result)) return false;
+	const verdict = await arbitrateWithGuard(arbiter, task);
+	if (verdict !== "read-only") return false;
+	result.exitCode = 0;
+	delete result.error;
+	return true;
+}
+
+async function arbitrateWithGuard(
+	arbiter: TaskMutationArbiter,
+	task: string,
+): Promise<TaskMutationVerdict> {
+	try {
+		return await arbiter(task);
+	} catch {
+		return "unavailable";
+	}
+}

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

@@ -61,6 +61,8 @@ export interface RunnerSubagentStep {
 	toolBudget?: import("../../shared/types.ts").ResolvedToolBudget;
 	capabilityCeiling?: import("./capability-ceiling.ts").ResolvedSubagentCapabilityCeiling;
 	capabilityAudit?: import("./capability-ceiling.ts").SubagentCapabilityAudit;
+	/** Private stable logical-child path for inherited run fan-out accounting. */
+	runFanoutPath?: string;
 }
 
 export interface RunnerCheckpointStep {

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

@@ -23,8 +23,10 @@ import {
 	type JsonSchemaObject,
 	type LaunchResolvedChildExtensionsV1,
 	type ResolvedToolBudget,
+	type RunFanoutBudgetDescriptor,
 } from "../../shared/types.ts";
 import { THINKING_LEVELS } from "../../shared/model-info.ts";
+import { encodeRunFanoutBudgetDescriptor, RUN_FANOUT_BUDGET_ENV } from "./run-fanout-budget.ts";
 import {
 	TOOL_BUDGET_ENV,
 	TOOL_BUDGET_ZERO_AUTH_ENV,
@@ -63,6 +65,32 @@ import {
 } from "./capability-ceiling.ts";
 
 const TASK_ARG_LIMIT = 8000;
+
+/**
+ * Env override for how the task text reaches the child process. Endpoint
+ * protection (EDR) pre-execution command-line scanning may deny exec of
+ * children whose argv embeds a long natural-language task, which surfaces
+ * as an immediate zero-activity SIGKILL. File delivery keeps the task out
+ * of argv entirely.
+ */
+export const SUBAGENT_TASK_DELIVERY_ENV = "PI_SUBAGENT_TASK_DELIVERY";
+
+export type SubagentTaskDelivery = "auto" | "file";
+
+export function resolveSubagentTaskDelivery(
+	env: NodeJS.ProcessEnv = process.env,
+): SubagentTaskDelivery {
+	return env[SUBAGENT_TASK_DELIVERY_ENV]?.trim().toLowerCase() === "file"
+		? "file"
+		: "auto";
+}
+
+function shouldDeliverTaskViaFile(
+	task: string,
+	delivery: SubagentTaskDelivery,
+): boolean {
+	return delivery === "file" || task.length > TASK_ARG_LIMIT;
+}
 const MAX_LAUNCH_RESOLVED_EXTENSION_IDS = 32;
 const PROMPT_RUNTIME_EXTENSION_PATH = path.join(
 	path.dirname(fileURLToPath(import.meta.url)),
@@ -136,6 +164,7 @@ export interface BuildPiArgsInput {
 	parentDepth?: number;
 	parentPath?: NestedPathEntry[];
 	parentCapabilityToken?: string;
+	runFanoutBudget?: RunFanoutBudgetDescriptor;
 	steerInboxDir?: string;
 	steerCapabilityPath?: string;
 	steerAckDir?: string;
@@ -149,6 +178,12 @@ export interface BuildPiArgsInput {
 	permissionRules?: PermissionRules;
 	permissionAuditPath?: string;
 	childWatchdog?: ChildWatchdogConfig;
+	/**
+	 * Per-launch override of the task delivery mode. Startup-retry paths set
+	 * this to "file" after an unexplained zero-activity SIGKILL so the retry
+	 * keeps the task text out of the child's argv.
+	 */
+	taskDelivery?: SubagentTaskDelivery;
 	waitToolEnabled?: boolean;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 }
@@ -585,7 +620,12 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 		);
 	}
 
-	if (input.task.length > TASK_ARG_LIMIT) {
+	if (
+		shouldDeliverTaskViaFile(
+			input.task,
+			input.taskDelivery ?? resolveSubagentTaskDelivery(),
+		)
+	) {
 		if (!tempDir) {
 			tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
 		}
@@ -694,6 +734,9 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 			process.env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] ??
 			"")
 		: "";
+	env[RUN_FANOUT_BUDGET_ENV] = toolPlan.fanoutAuthorized
+		? (input.runFanoutBudget ? encodeRunFanoutBudgetDescriptor(input.runFanoutBudget) : process.env[RUN_FANOUT_BUDGET_ENV])
+		: undefined;
 	env.PI_SUBAGENT_INHERIT_PROJECT_CONTEXT = input.inheritProjectContext
 		? "1"
 		: "0";