pi-subagents 0.40.0 → 0.42.0

package/src/runs/shared/acceptance.ts

@@ -169,6 +169,7 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
 		if (input === "reviewed") errors.push(`${pathLabel} ${EXPLICIT_REVIEWED_UNAVAILABLE}`);
 		else if (!VALID_LEVELS.has(input as AcceptanceLevel)) errors.push(`${pathLabel} has invalid level '${input}'.`);
 		else if (input === "none") errors.push(`${pathLabel} level "none" requires a reason; use { level: "none", reason: "..." }.`);
+		else if (input === "verified") errors.push(`${pathLabel} level "verified" requires object form with at least one runtime verify command. Use level "checked" or provide a non-empty acceptance.verify array.`);
 		return errors;
 	}
 	if (!input || typeof input !== "object" || Array.isArray(input)) {
@@ -232,7 +233,11 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
 	} else if (value.evidence !== undefined) {
 		errors.push(`${pathLabel}.evidence must be an array. ${ACCEPTANCE_EVIDENCE_HELP}`);
 	}
-	if (value.verify !== undefined && !Array.isArray(value.verify)) errors.push(`${pathLabel}.verify must be an array.`);
+	if (value.level === "verified" && (!Array.isArray(value.verify) || value.verify.length === 0)) {
+		errors.push(`${pathLabel}.verify must contain at least one runtime command when level is verified. Use level "checked" or provide a non-empty acceptance.verify array.`);
+	} else if (value.verify !== undefined && !Array.isArray(value.verify)) {
+		errors.push(`${pathLabel}.verify must be an array.`);
+	}
 	if (Array.isArray(value.verify)) {
 		for (const [index, command] of value.verify.entries()) {
 			if (!command || typeof command !== "object" || Array.isArray(command)) {
@@ -311,7 +316,7 @@ export function validateExecutionAcceptance(input: {
 }
 
 function normalizeCriteria(criteria: Array<string | { id?: string; must?: string; evidence?: AcceptanceEvidenceKind[]; severity?: "required" | "recommended" }> | undefined, evidence: AcceptanceEvidenceKind[]): ResolvedAcceptanceGate[] {
-	return (criteria ?? []).map((criterion, index) => {
+	return (criteria ?? []).map((criterion, index): ResolvedAcceptanceGate => {
 		if (typeof criterion === "string") {
 			return { id: `criterion-${index + 1}`, must: criterion, evidence, severity: "required" };
 		}
@@ -405,7 +410,7 @@ export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig, opt
 		lines.push("", "Runtime verification commands configured by parent:");
 		for (const command of acceptance.verify) lines.push(`- ${command.id}: ${command.command}`);
 	}
-	if (acceptance.review && acceptance.review !== false) {
+	if (acceptance.review) {
 		lines.push("", `Review gate: ${acceptance.review.required === false ? "optional" : "required"}${acceptance.review.agent ? ` by ${acceptance.review.agent}` : ""}.`);
 		if (acceptance.review.focus) lines.push(`Review focus: ${acceptance.review.focus}`);
 	}
@@ -650,6 +655,21 @@ function parseAcceptanceReportBody(body: string): { report?: AcceptanceReport; e
 	return validateAcceptanceReport(parseReportJson(body));
 }
 
+function parseUnterminatedAcceptanceReportFence(output: string): { report?: AcceptanceReport; error?: string } {
+	const opener = /```acceptance[-_]report\b[^\n]*\n/gi.exec(output);
+	if (!opener) return {};
+	const bodyStart = opener.index + opener[0].length;
+	if (output.indexOf("```", bodyStart) !== -1) return {};
+	try {
+		const validation = validateAcceptanceReport(JSON.parse(output.slice(bodyStart).trim()) as unknown);
+		return validation.report
+			? { report: validation.report }
+			: { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
+	} catch (error) {
+		return { error: `Failed to parse acceptance-report: ${error instanceof Error ? error.message : String(error)}` };
+	}
+}
+
 function parseGenericJsonAcceptanceReportBody(body: string): { report?: AcceptanceReport; error?: string } {
 	const parsed = parseReportJson(body);
 	const normalized = normalizeAcceptanceReportValue(parsed);
@@ -681,6 +701,8 @@ export function parseAcceptanceReport(output: string): { report?: AcceptanceRepo
 	}
 	if (parseErrors.length > 0) return { error: `Failed to parse acceptance-report: ${parseErrors.join("; ")}` };
 	if (explicitFencePresent) {
+		const recovered = parseUnterminatedAcceptanceReportFence(output);
+		if (recovered.report || recovered.error) return recovered;
 		return { error: "Failed to parse acceptance-report: Empty or unterminated acceptance-report fence." };
 	}
 	for (const body of fencedBlocks(output, "(?:json|jsonc|json5)")) {
@@ -942,7 +964,7 @@ function uniqueStrings(items: Array<string | undefined>): string[] {
 }
 
 export function aggregateAcceptanceReport(input: {
-	results: Array<Pick<SingleResult, "agent" | "acceptance" | "error" | "exitCode">>;
+	results: Array<Pick<SingleResult, "agent" | "acceptance" | "error"> & { exitCode: number | null }>;
 	notes?: string;
 }): AcceptanceReport {
 	const childReports = input.results.map((result) => result.acceptance?.childReport).filter((report): report is AcceptanceReport => Boolean(report));
@@ -952,7 +974,7 @@ export function aggregateAcceptanceReport(input: {
 		criteriaSatisfied: [
 			{ id: "criterion-1", status: successfulChildren ? "satisfied" : "not-satisfied", evidence: successfulChildren ? `All ${input.results.length} dynamic child run(s) completed without child or acceptance blockers.` : "Dynamic fanout produced no accepted child evidence." },
 			{ id: "criterion-2", status: successfulChildren ? "satisfied" : "not-satisfied", evidence: successfulChildren ? "Collected child acceptance evidence for aggregate review." : "Dynamic fanout produced no aggregate review evidence." },
-			...input.results.map((result, index) => ({
+			...input.results.map((result, index): { id?: string; status: "satisfied" | "not-satisfied" | "not-applicable"; evidence: string } => ({
 				id: `child-${index + 1}`,
 				status: result.exitCode === 0 && result.acceptance?.status !== "rejected" ? "satisfied" : "not-satisfied",
 				evidence: `${result.agent}: acceptance ${result.acceptance?.status ?? "unreported"}${result.error ? ` (${result.error})` : ""}`,
@@ -1148,7 +1170,7 @@ export async function evaluateAcceptance(input: {
 		ledger.evidenceStatus = ledger.status;
 	}
 
-	if (acceptance.review && acceptance.review !== false) {
+	if (acceptance.review) {
 		if (input.reviewResult?.status === "reviewed") {
 			ledger.reviewResult = input.reviewResult;
 			ledger.status = "reviewed";

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

@@ -6,6 +6,236 @@ export type { ProtocolOutputLimit } from "../../shared/types.ts";
 export const MAX_CHILD_PENDING_LINE_BYTES = 16 * 1024 * 1024;
 export const MAX_CHILD_STDERR_BYTES = 128 * 1024;
 const MAX_PROTOCOL_DIAGNOSTIC_BYTES = 4096;
+const MAX_PROJECTED_JSON_DEPTH = 256;
+
+export interface OversizedLineProjection {
+	push(chunk: Buffer): boolean;
+	finish(): string | undefined;
+}
+
+export interface OversizedLineProjector {
+	accepts(prefix: string): boolean;
+	create(): OversizedLineProjection;
+}
+
+type JsonContainer =
+	| { type: "array"; state: "value-or-end" | "value" | "comma-or-end" }
+	| { type: "object"; state: "key-or-end" | "key" | "colon" | "value" | "comma-or-end"; key?: string };
+
+type JsonToken =
+	| { type: "string"; role: "key" | "value"; value: string; capture: boolean; escape: boolean; unicodeDigits: number; unicodeValue: string }
+	| { type: "literal"; expected: string; index: number; value: boolean | null }
+	| { type: "number"; phase: "minus" | "zero" | "int" | "dot" | "frac" | "exp" | "exp-sign" | "exp-digits" };
+
+function createPiAggregateProjection(): OversizedLineProjection {
+	const decoder = new TextDecoder("utf-8", { fatal: true });
+	const stack: JsonContainer[] = [];
+	let rootState: "value" | "end" = "value";
+	let token: JsonToken | undefined;
+	let valid = true;
+	let eventType: string | undefined;
+	let willRetry: boolean | undefined;
+
+	const parent = (): JsonContainer | undefined => stack.at(-1);
+	const isTopLevelField = (key: string | undefined): boolean => stack.length === 1 && parent()?.type === "object" && (key === "type" || key === "willRetry");
+
+	const completeValue = (value?: string | boolean | null): void => {
+		const container = parent();
+		if (!container) {
+			rootState = "end";
+			return;
+		}
+		if (container.type === "object") {
+			if (stack.length === 1 && container.key === "type" && typeof value === "string") eventType = value;
+			if (stack.length === 1 && container.key === "willRetry" && typeof value === "boolean") willRetry = value;
+			container.key = undefined;
+			container.state = "comma-or-end";
+		} else container.state = "comma-or-end";
+	};
+
+	const startValue = (char: string): boolean => {
+		const container = parent();
+		const key = container?.type === "object" ? container.key : undefined;
+		if (isTopLevelField(key)) {
+			if (key === "type") eventType = undefined;
+			else willRetry = undefined;
+		}
+		if (char === "{" || char === "[") {
+			if (stack.length >= MAX_PROJECTED_JSON_DEPTH) return false;
+			stack.push(char === "{" ? { type: "object", state: "key-or-end" } : { type: "array", state: "value-or-end" });
+			return true;
+		}
+		if (char === '"') {
+			token = { type: "string", role: "value", value: "", capture: key === "type" && stack.length === 1, escape: false, unicodeDigits: 0, unicodeValue: "" };
+			return true;
+		}
+		if (char === "t") token = { type: "literal", expected: "true", index: 1, value: true };
+		else if (char === "f") token = { type: "literal", expected: "false", index: 1, value: false };
+		else if (char === "n") token = { type: "literal", expected: "null", index: 1, value: null };
+		else if (char === "-") token = { type: "number", phase: "minus" };
+		else if (char === "0") token = { type: "number", phase: "zero" };
+		else if (char >= "1" && char <= "9") token = { type: "number", phase: "int" };
+		else return false;
+		return true;
+	};
+
+	const closeContainer = (): true => {
+		stack.pop();
+		completeValue();
+		return true;
+	};
+
+	const processChar = (char: string): boolean => {
+		if (token?.type === "string") {
+			if (token.unicodeDigits > 0) {
+				if (!/[0-9a-fA-F]/.test(char)) return false;
+				token.unicodeValue += char;
+				token.unicodeDigits--;
+				if (token.unicodeDigits === 0 && token.capture) {
+					if (token.value.length >= 64) return false;
+					token.value += String.fromCharCode(Number.parseInt(token.unicodeValue, 16));
+				}
+				return true;
+			}
+			if (token.escape) {
+				token.escape = false;
+				if (char === "u") { token.unicodeDigits = 4; token.unicodeValue = ""; return true; }
+				if (!'"\\/bfnrt'.includes(char)) return false;
+				if (token.capture) {
+					if (token.value.length >= 64) return false;
+					token.value += ({ b: "\b", f: "\f", n: "\n", r: "\r", t: "\t" } as Record<string, string>)[char] ?? char;
+				}
+				return true;
+			}
+			if (char === "\\") { token.escape = true; return true; }
+			if (char === '"') {
+				const finished = token;
+				token = undefined;
+				if (finished.role === "key") {
+					const container = parent();
+					if (!container || container.type !== "object") return false;
+					container.key = finished.value;
+					container.state = "colon";
+				} else completeValue(finished.capture ? finished.value : undefined);
+				return true;
+			}
+			if (char.charCodeAt(0) < 0x20) return false;
+			if (token.capture) {
+				if (token.value.length >= 64) return false;
+				token.value += char;
+			}
+			return true;
+		}
+		if (token?.type === "literal") {
+			if (char !== token.expected[token.index]) return false;
+			token.index++;
+			if (token.index === token.expected.length) {
+				const value = token.value;
+				token = undefined;
+				completeValue(value);
+			}
+			return true;
+		}
+		if (token?.type === "number") {
+			const phase = token.phase;
+			if (phase === "minus") {
+				if (char === "0") token.phase = "zero";
+				else if (char >= "1" && char <= "9") token.phase = "int";
+				else return false;
+				return true;
+			}
+			if (phase === "zero" || phase === "int") {
+				if (char >= "0" && char <= "9") { if (phase === "zero") return false; return true; }
+				if (char === ".") { token.phase = "dot"; return true; }
+				if (char === "e" || char === "E") { token.phase = "exp"; return true; }
+			} else if (phase === "dot") {
+				if (char >= "0" && char <= "9") { token.phase = "frac"; return true; }
+				return false;
+			} else if (phase === "frac") {
+				if (char >= "0" && char <= "9") return true;
+				if (char === "e" || char === "E") { token.phase = "exp"; return true; }
+			} else if (phase === "exp") {
+				if (char === "+" || char === "-") { token.phase = "exp-sign"; return true; }
+				if (char >= "0" && char <= "9") { token.phase = "exp-digits"; return true; }
+				return false;
+			} else if (phase === "exp-sign") {
+				if (char >= "0" && char <= "9") { token.phase = "exp-digits"; return true; }
+				return false;
+			} else if (phase === "exp-digits" && char >= "0" && char <= "9") return true;
+			if (!["zero", "int", "frac", "exp-digits"].includes(phase)) return false;
+			token = undefined;
+			completeValue();
+			return processChar(char);
+		}
+		if (char === " " || char === "\t" || char === "\r" || char === "\n") return true;
+		const container = parent();
+		if (!container) return rootState === "value" ? startValue(char) : false;
+		if (container.type === "object") {
+			if (container.state === "key-or-end" || container.state === "key") {
+				if (char === "}" && container.state === "key-or-end") return closeContainer();
+				if (char !== '"') return false;
+				token = { type: "string", role: "key", value: "", capture: stack.length === 1, escape: false, unicodeDigits: 0, unicodeValue: "" };
+				return true;
+			}
+			if (container.state === "colon") {
+				if (char !== ":") return false;
+				container.state = "value";
+				return true;
+			}
+			if (container.state === "value") return startValue(char);
+			if (char === ",") { container.state = "key"; return true; }
+			if (char === "}") return closeContainer();
+			return false;
+		}
+		if (container.state === "value-or-end" || container.state === "value") {
+			if (char === "]" && container.state === "value-or-end") return closeContainer();
+			return startValue(char);
+		}
+		if (char === ",") { container.state = "value"; return true; }
+		if (char === "]") return closeContainer();
+		return false;
+	};
+
+	const processText = (text: string): boolean => {
+		for (const char of text) if (!processChar(char)) return false;
+		return true;
+	};
+
+	return {
+		push(chunk) {
+			if (!valid) return false;
+			try { valid = processText(decoder.decode(chunk, { stream: true })); }
+			catch { valid = false; }
+			return valid;
+		},
+		finish() {
+			try { valid = valid && processText(decoder.decode()); }
+			catch { valid = false; }
+			if (token?.type === "number" && ["zero", "int", "frac", "exp-digits"].includes(token.phase)) {
+				token = undefined;
+				completeValue();
+			}
+			if (!valid || token || stack.length !== 0 || rootState !== "end") return undefined;
+			if (eventType === "turn_end") return '{"type":"turn_end"}';
+			if (eventType === "agent_end" && typeof willRetry === "boolean") return JSON.stringify({ type: "agent_end", willRetry });
+			return undefined;
+		},
+	};
+}
+
+/**
+ * Pi JSON mode emits granular message/tool events followed by aggregate
+ * `turn_end` and `agent_end` events that duplicate those payloads. Parallel
+ * image reads can make one aggregate record exceed the child line limit even
+ * though every granular event was valid. Replace only syntactically valid,
+ * redundant records with the lifecycle fields the runners consume.
+ */
+export const PI_AGGREGATE_EVENT_PROJECTOR: OversizedLineProjector = {
+	accepts(prefix) {
+		return prefix.startsWith('{"type":"turn_end"') || prefix.startsWith('{"type":"agent_end"');
+	},
+	create: createPiAggregateProjection,
+};
 
 export function formatProtocolOutputLimit(limit: ProtocolOutputLimit): string {
 	return `${limit.code}: child ${limit.stream} line exceeded ${limit.limitBytes} bytes (observed at least ${limit.observedBytes} bytes without a newline).`;
@@ -14,6 +244,7 @@ export function formatProtocolOutputLimit(limit: ProtocolOutputLimit): string {
 export function createBoundedLineReader(options: {
 	stream?: "stdout" | "stderr";
 	maxPendingLineBytes?: number;
+	oversizedLineProjector?: OversizedLineProjector;
 	onLine: (line: string) => void;
 	onLimit: (limit: ProtocolOutputLimit) => void;
 }): {
@@ -27,17 +258,67 @@ export function createBoundedLineReader(options: {
 	}
 	let pending: Buffer[] = [];
 	let pendingBytes = 0;
+	let projectedPrefix: Buffer<ArrayBufferLike> = Buffer.alloc(0);
+	let projectedTail: Buffer<ArrayBufferLike> = Buffer.alloc(0);
+	let projectedBytes = 0;
+	let projection: OversizedLineProjection | undefined;
+	let projectingOversizedLine = false;
 	let limitExceeded = false;
 
-	const emitPending = (): void => {
-		if (pendingBytes === 0) return;
-		options.onLine(Buffer.concat(pending, pendingBytes).toString("utf8"));
+	const diagnosticTail = (prior: Buffer, segment: Buffer): Buffer => {
+		const tailFromSegment = segment.subarray(Math.max(0, segment.length - MAX_PROTOCOL_DIAGNOSTIC_BYTES));
+		return tailFromSegment.length === MAX_PROTOCOL_DIAGNOSTIC_BYTES
+			? tailFromSegment
+			: Buffer.concat([prior.subarray(Math.max(0, prior.length - (MAX_PROTOCOL_DIAGNOSTIC_BYTES - tailFromSegment.length))), tailFromSegment]);
+	};
+
+	const failLimit = (observedBytes: number, prefix: Buffer, tail: Buffer): false => {
+		limitExceeded = true;
+		pending = [];
+		pendingBytes = 0;
+		projectingOversizedLine = false;
+		projection = undefined;
+		projectedPrefix = Buffer.alloc(0);
+		projectedTail = Buffer.alloc(0);
+		projectedBytes = 0;
+		options.onLimit({
+			code: "protocol_output_limit",
+			stream: options.stream ?? "stdout",
+			limitBytes: maxPendingLineBytes,
+			observedBytes,
+			diagnosticPrefix: prefix.toString("utf8"),
+			diagnosticTail: tail.toString("utf8"),
+		});
+		return false;
+	};
+
+	const finishLine = (): void => {
+		if (projectingOversizedLine) {
+			const projected = projection?.finish();
+			if (projected === undefined) {
+				failLimit(projectedBytes, projectedPrefix, projectedTail);
+			} else {
+				options.onLine(projected);
+			}
+		} else if (pendingBytes > 0) {
+			options.onLine(Buffer.concat(pending, pendingBytes).toString("utf8"));
+		}
 		pending = [];
 		pendingBytes = 0;
+		projectingOversizedLine = false;
+		projection = undefined;
+		projectedPrefix = Buffer.alloc(0);
+		projectedTail = Buffer.alloc(0);
+		projectedBytes = 0;
 	};
 
 	const append = (segment: Buffer): boolean => {
 		if (segment.length === 0) return true;
+		if (projectingOversizedLine) {
+			projectedBytes += segment.length;
+			projectedTail = diagnosticTail(projectedTail, segment);
+			return projection?.push(segment) === true || failLimit(projectedBytes, projectedPrefix, projectedTail);
+		}
 		const observedBytes = pendingBytes + segment.length;
 		if (observedBytes > maxPendingLineBytes) {
 			const prior = pendingBytes > 0 ? Buffer.concat(pending, pendingBytes) : Buffer.alloc(0);
@@ -45,22 +326,20 @@ export function createBoundedLineReader(options: {
 			const prefix = prefixFromPrior.length === MAX_PROTOCOL_DIAGNOSTIC_BYTES
 				? prefixFromPrior
 				: Buffer.concat([prefixFromPrior, segment.subarray(0, MAX_PROTOCOL_DIAGNOSTIC_BYTES - prefixFromPrior.length)]);
-			const tailFromSegment = segment.subarray(Math.max(0, segment.length - MAX_PROTOCOL_DIAGNOSTIC_BYTES));
-			const tail = tailFromSegment.length === MAX_PROTOCOL_DIAGNOSTIC_BYTES
-				? tailFromSegment
-				: Buffer.concat([prior.subarray(Math.max(0, prior.length - (MAX_PROTOCOL_DIAGNOSTIC_BYTES - tailFromSegment.length))), tailFromSegment]);
-			limitExceeded = true;
-			pending = [];
-			pendingBytes = 0;
-			options.onLimit({
-				code: "protocol_output_limit",
-				stream: options.stream ?? "stdout",
-				limitBytes: maxPendingLineBytes,
-				observedBytes,
-				diagnosticPrefix: prefix.toString("utf8"),
-				diagnosticTail: tail.toString("utf8"),
-			});
-			return false;
+			const tail = diagnosticTail(prior, segment);
+			if (options.oversizedLineProjector?.accepts(prefix.toString("utf8"))) {
+				const candidate = options.oversizedLineProjector.create();
+				if (!candidate.push(prior) || !candidate.push(segment)) return failLimit(observedBytes, prefix, tail);
+				pending = [];
+				pendingBytes = 0;
+				projectingOversizedLine = true;
+				projection = candidate;
+				projectedPrefix = prefix;
+				projectedTail = tail;
+				projectedBytes = observedBytes;
+				return true;
+			}
+			return failLimit(observedBytes, prefix, tail);
 		}
 		pending.push(segment);
 		pendingBytes = observedBytes;
@@ -75,13 +354,14 @@ export function createBoundedLineReader(options: {
 			for (let index = 0; index < bytes.length; index++) {
 				if (bytes[index] !== 0x0a) continue;
 				if (!append(bytes.subarray(start, index))) return;
-				emitPending();
+				finishLine();
+				if (limitExceeded) return;
 				start = index + 1;
 			}
 			append(bytes.subarray(start));
 		},
 		end() {
-			if (!limitExceeded) emitPending();
+			if (!limitExceeded) finishLine();
 		},
 		exceeded: () => limitExceeded,
 	};
@@ -100,7 +380,7 @@ export function createBoundedByteTail(maxBytes = MAX_CHILD_STDERR_BYTES): {
 	byteLength(): number;
 } {
 	if (!Number.isInteger(maxBytes) || maxBytes < 1) throw new Error("maxBytes must be a positive integer.");
-	let tail = Buffer.alloc(0);
+	let tail: Buffer<ArrayBufferLike> = Buffer.alloc(0);
 	return {
 		push(chunk) {
 			const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;

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

@@ -264,7 +264,7 @@ export function materializeDynamicParallelStep(step: DynamicParallelStep, output
 export function collectDynamicResults(
 	step: DynamicParallelStep,
 	items: DynamicMaterializedItem[],
-	results: Array<Pick<SingleResult, "agent" | "exitCode" | "error" | "timedOut" | "stopped" | "structuredOutput" | "artifactPaths" | "savedOutputPath"> & { output?: string; finalOutput?: string }>,
+	results: Array<Pick<SingleResult, "agent" | "error" | "timedOut" | "stopped" | "structuredOutput" | "artifactPaths" | "savedOutputPath"> & { exitCode: number | null; output?: string; finalOutput?: string }>,
 ): DynamicCollectedResult[] {
 	return items.map((entry, index) => {
 		const result = results[index];

package/src/runs/shared/external-cli-runner.ts

@@ -0,0 +1,130 @@
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { finished } from "node:stream/promises";
+import { trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
+import type { ExternalProcessStatus } from "../../shared/types.ts";
+
+const HARD_KILL_DELAY_MS = 2_000;
+const MAX_OUTPUT_TAIL_BYTES = 64 * 1024;
+const MAX_ERROR_TAIL_BYTES = 64 * 1024;
+
+export function buildExternalCliPrompt(systemInstructions: string, task: string): string {
+	return `<System instructions>\n${systemInstructions.trim()}\n\n<Task>\n${task}`;
+}
+
+export interface ExternalCliRunResult {
+	output: string;
+	exitCode: number | null;
+	error?: string;
+	timedOut?: boolean;
+	stopped?: boolean;
+	processSignal?: string | null;
+	externalProcess: ExternalProcessStatus;
+}
+
+export function runExternalCli(input: {
+	command: string;
+	args?: string[];
+	cwd: string;
+	prompt: string;
+	asyncDir: string;
+	stepIndex: number;
+	registerTimeout?: (stop: (() => void) | undefined) => void;
+	registerStop?: (stop: (() => void) | undefined) => void;
+	timeoutMessage?: string;
+	stopMessage?: string;
+	onProcess?: (process: ExternalProcessStatus) => void;
+}): Promise<ExternalCliRunResult> {
+	return new Promise((resolve, reject) => {
+		const startedAt = Date.now();
+		const stdoutPath = path.join(input.asyncDir, `external-${input.stepIndex}.stdout.log`);
+		const stderrPath = path.join(input.asyncDir, `external-${input.stepIndex}.stderr.log`);
+		fs.mkdirSync(input.asyncDir, { recursive: true });
+		const stdoutStream = fs.createWriteStream(stdoutPath, { flags: "w" });
+		const stderrStream = fs.createWriteStream(stderrPath, { flags: "w" });
+		const streamsFinished = Promise.allSettled([finished(stdoutStream), finished(stderrStream)]);
+		let stdoutTail = Buffer.alloc(0);
+		let stderrTail = Buffer.alloc(0);
+		let timedOut = false;
+		let stopped = false;
+		let settled = false;
+		let hardKillTimer: NodeJS.Timeout | undefined;
+		const child = spawn(input.command, input.args ?? [], {
+			cwd: input.cwd,
+			stdio: ["pipe", "pipe", "pipe"],
+			shell: false,
+			windowsHide: true,
+		});
+		const initialProcess: ExternalProcessStatus = {
+			...(typeof child.pid === "number" ? { pid: child.pid } : {}),
+			startedAt,
+			stdoutPath,
+			stderrPath,
+		};
+		input.onProcess?.(initialProcess);
+		child.stdout.on("data", (chunk: Buffer) => {
+			stdoutStream.write(chunk);
+			stdoutTail = Buffer.concat([stdoutTail, chunk]);
+			if (stdoutTail.length > MAX_OUTPUT_TAIL_BYTES) stdoutTail = stdoutTail.subarray(stdoutTail.length - MAX_OUTPUT_TAIL_BYTES);
+		});
+		child.stderr.on("data", (chunk: Buffer) => {
+			stderrStream.write(chunk);
+			stderrTail = Buffer.concat([stderrTail, chunk]);
+			if (stderrTail.length > MAX_ERROR_TAIL_BYTES) stderrTail = stderrTail.subarray(stderrTail.length - MAX_ERROR_TAIL_BYTES);
+		});
+		const terminate = (reason: "timeout" | "stop") => {
+			if (settled || timedOut || stopped) return;
+			timedOut = reason === "timeout";
+			stopped = reason === "stop";
+			trySignalChild(child, "SIGTERM");
+			hardKillTimer = setTimeout(() => {
+				if (!settled) trySignalChild(child, "SIGKILL");
+			}, HARD_KILL_DELAY_MS);
+			hardKillTimer.unref?.();
+		};
+		input.registerTimeout?.(() => terminate("timeout"));
+		input.registerStop?.(() => terminate("stop"));
+		child.stdin.on("error", () => {});
+		child.stdin.end(input.prompt);
+		let spawnError: Error | undefined;
+		child.once("error", (error) => { spawnError = error; });
+		child.once("close", (exitCode, signal) => {
+			settled = true;
+			if (hardKillTimer) clearTimeout(hardKillTimer);
+			input.registerTimeout?.(undefined);
+			input.registerStop?.(undefined);
+			const endedAt = Date.now();
+			const externalProcess: ExternalProcessStatus = {
+				...initialProcess,
+				endedAt,
+				durationMs: endedAt - startedAt,
+				exitCode,
+				processSignal: signal,
+			};
+			input.onProcess?.(externalProcess);
+			const stderr = stderrTail.toString("utf-8").trim();
+			const error = stopped
+				? input.stopMessage ?? "Subagent stopped by user."
+				: timedOut
+					? input.timeoutMessage ?? "Subagent timed out."
+					: spawnError?.message ?? (exitCode === 0 ? undefined : stderr || `External CLI exited with code ${exitCode}.`);
+			const result: ExternalCliRunResult = {
+				output: stdoutTail.toString("utf-8").trim(),
+				exitCode: timedOut || stopped || spawnError ? 1 : exitCode,
+				...(error ? { error } : {}),
+				...(timedOut ? { timedOut: true } : {}),
+				...(stopped ? { stopped: true } : {}),
+				processSignal: signal,
+				externalProcess,
+			};
+			stdoutStream.end();
+			stderrStream.end();
+			void streamsFinished.then((streamResults) => {
+				const streamFailure = streamResults.find((streamResult) => streamResult.status === "rejected");
+				if (streamFailure?.status === "rejected") reject(streamFailure.reason);
+				else resolve(result);
+			});
+		});
+	});
+}

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

@@ -96,8 +96,49 @@ function hasUnquotedFileRedirection(command: string): boolean {
 	return false;
 }
 
+function unquotedShellText(command: string): string {
+	let inSingle = false;
+	let inDouble = false;
+	let escaped = false;
+	let result = "";
+	for (const char of command) {
+		if (escaped) {
+			result += inSingle || inDouble ? "_" : char;
+			escaped = false;
+			continue;
+		}
+		if (char === "\\" && !inSingle) {
+			escaped = true;
+			result += inDouble ? "_" : char;
+			continue;
+		}
+		if (char === "'" && !inDouble) {
+			inSingle = !inSingle;
+			continue;
+		}
+		if (char === '"' && !inSingle) {
+			inDouble = !inDouble;
+			continue;
+		}
+		result += inSingle || inDouble ? "_" : char;
+	}
+	return result;
+}
+
+function hasMutatingGitCommand(command: string): boolean {
+	const unquoted = unquotedShellText(command);
+	for (const segment of unquoted.split(/(?:&&|\|\||[;|()\n])/)) {
+		const trimmed = segment.trim();
+		if (!trimmed || /^(?:echo|printf)\b/.test(trimmed)) continue;
+		if (/^git\s+(?:(?:(?:-C|--git-dir|--work-tree)\s+\S+|(?:--git-dir|--work-tree)=\S+|--paginate)\s+)*(?:add|commit|push)\b/.test(trimmed)) return true;
+	}
+	return false;
+}
+
 export function isMutatingBashCommand(command: string): boolean {
-	return hasUnquotedFileRedirection(command) || MUTATING_BASH_PATTERNS.some((pattern) => pattern.test(command));
+	return hasUnquotedFileRedirection(command)
+		|| hasMutatingGitCommand(command)
+		|| MUTATING_BASH_PATTERNS.some((pattern) => pattern.test(command));
 }
 
 export function isMutatingTool(toolName: string | undefined, args: Record<string, unknown> | undefined): boolean {