pi-subagents 0.34.0 → 0.35.0

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

@@ -2,11 +2,25 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerNativeSupervisorClient } from "../../intercom/native-supervisor-channel.ts";
-import { consumeSteerRequestsFromDir, writeSteerRequestToDir, type SteerRequest } from "../background/control-channel.ts";
-import { SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
+import { consumeSteerRequestsFromDir, steerAckPathFromDir, writeSteerAckAt, writeSteerCapabilityAt, writeSteerRequestToDir, type SteerRequest } from "../background/control-channel.ts";
+import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_STEER_ACK_DIR_ENV, SUBAGENT_STEER_CAPABILITY_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
 import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
+import {
+	CHILD_TOOL_DIAGNOSTIC_PATH_ENV,
+	formatChildToolDiagnostic,
+	REQUIRED_CHILD_TOOLS_ENV,
+	writeChildToolDiagnostic,
+	type ChildToolDiagnostic,
+} from "./tool-availability.ts";
 import { TOOL_BUDGET_ENV, decodeToolBudgetEnv, shouldBlockToolForBudget, toolBudgetBlockedMessage, toolBudgetSoftNudge } from "./tool-budget.ts";
-import type { JsonSchemaObject, ResolvedToolBudget } from "../../shared/types.ts";
+import type { JsonSchemaObject, ResolvedToolBudget, SubagentState } from "../../shared/types.ts";
+import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
+import { resolveWatchPath } from "../../shared/utils.ts";
+import { registerChildWatchdog } from "../../watchdog/register-child.ts";
+import { SUBAGENT_WATCHDOG_WARNING_TYPE } from "../../watchdog/types.ts";
+import { resolveWaitToolConfig } from "../background/wait-config.ts";
+import { registerWaitTool } from "../background/wait-tool.ts";
+import { drainOutstandingWork } from "../background/auto-drain.ts";
 
 const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
 const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
@@ -55,6 +69,18 @@ function readBooleanEnv(name: string): boolean | undefined {
 	return value !== "0";
 }
 
+function refreshChildToolDiagnostic(pi: ExtensionAPI): ChildToolDiagnostic | undefined {
+	const filePath = process.env[CHILD_TOOL_DIAGNOSTIC_PATH_ENV]?.trim();
+	const encoded = process.env[REQUIRED_CHILD_TOOLS_ENV]?.trim();
+	if (!filePath || !encoded) return undefined;
+	const required = JSON.parse(encoded) as unknown;
+	if (!Array.isArray(required) || required.some((name) => typeof name !== "string" || !name)) {
+		throw new Error(`Invalid ${REQUIRED_CHILD_TOOLS_ENV} payload.`);
+	}
+	const available = pi.getAllTools().map((tool) => tool.name);
+	return writeChildToolDiagnostic(filePath, required, available, process.env[SUBAGENT_CHILD_AGENT_ENV]?.trim());
+}
+
 function findSectionEnd(prompt: string, startIndex: number, nextHeaders: string[]): number {
 	let endIndex = prompt.length;
 	for (const header of nextHeaders) {
@@ -114,9 +140,9 @@ export function rewriteSubagentPrompt(
 
 function isParentOnlySubagentMessage(message: unknown): boolean {
 	const m = message as { role?: string; customType?: string };
-	return m?.role === "custom"
-		&& typeof m.customType === "string"
-		&& PARENT_ONLY_CUSTOM_MESSAGE_TYPES.has(m.customType);
+	if (m?.role !== "custom" || typeof m.customType !== "string") return false;
+	if (m.customType === SUBAGENT_WATCHDOG_WARNING_TYPE) return true;
+	return PARENT_ONLY_CUSTOM_MESSAGE_TYPES.has(m.customType);
 }
 
 function isSubagentToolResultMessage(message: unknown): boolean {
@@ -190,29 +216,59 @@ function registerToolBudget(pi: ExtensionAPI, budget: ResolvedToolBudget | undef
 	});
 }
 
-function registerSteeringInbox(pi: ExtensionAPI): void {
+export function registerSteeringInbox(
+	pi: ExtensionAPI,
+	deps: { watch?: typeof fs.watch; nativeRealpath?: (filePath: string) => string } = {},
+): void {
 	const steerInbox = process.env[SUBAGENT_STEER_INBOX_ENV]?.trim();
 	if (!steerInbox) return;
+	const capabilityPath = process.env[SUBAGENT_STEER_CAPABILITY_ENV]?.trim();
+	const ackDir = process.env[SUBAGENT_STEER_ACK_DIR_ENV]?.trim();
 	const sendUserMessage = (pi as { sendUserMessage?: (content: string, options: { deliverAs: "steer" }) => unknown }).sendUserMessage;
-	if (typeof sendUserMessage !== "function") return;
-
-	let canSteer = false;
+	const childIndex = Number(process.env[SUBAGENT_CHILD_INDEX_ENV]);
+	const pending = new Map<string, string[]>();
 	let disposed = false;
 	let flushing = false;
 	let started = false;
+	let canSteer = typeof sendUserMessage === "function";
 	let watcher: fs.FSWatcher | undefined;
 	let interval: NodeJS.Timeout | undefined;
+	const acknowledge = (request: SteerRequest, state: "delivered" | "failed", message: string): void => {
+		if (!ackDir || !Number.isInteger(childIndex) || childIndex < 0) return;
+		writeSteerAckAt(steerAckPathFromDir(ackDir, request.id), {
+			requestId: request.id,
+			index: childIndex,
+			ts: Date.now(),
+			state,
+			message,
+		});
+	};
+	const publishCapability = (): void => {
+		if (!capabilityPath || !Number.isInteger(childIndex) || childIndex < 0) return;
+		writeSteerCapabilityAt(capabilityPath, { index: childIndex, pid: process.pid, readyAt: Date.now(), supported: canSteer });
+	};
 	const flush = (): void => {
-		if (disposed || flushing || !canSteer) return;
+		if (disposed || flushing) return;
 		flushing = true;
 		try {
 			const requests = consumeSteerRequestsFromDir(steerInbox);
 			for (let index = 0; index < requests.length; index++) {
 				const request = requests[index]!;
+				if (!canSteer || typeof sendUserMessage !== "function") {
+					acknowledge(request, "failed", "Child Pi session does not support sendUserMessage steering.");
+					continue;
+				}
+				const formatted = formatSteerMessage(request);
+				const ids = pending.get(formatted) ?? [];
+				ids.push(request.id);
+				pending.set(formatted, ids);
 				try {
-					sendUserMessage(formatSteerMessage(request), { deliverAs: "steer" });
-				} catch {
-					for (const pending of requests.slice(index)) writeSteerRequestToDir(steerInbox, pending);
+					sendUserMessage(formatted, { deliverAs: "steer" });
+				} catch (error) {
+					ids.pop();
+					if (ids.length === 0) pending.delete(formatted);
+					acknowledge(request, "failed", error instanceof Error ? error.message : String(error));
+					for (const retry of requests.slice(index + 1)) writeSteerRequestToDir(steerInbox, retry);
 					break;
 				}
 			}
@@ -220,16 +276,30 @@ function registerSteeringInbox(pi: ExtensionAPI): void {
 			flushing = false;
 		}
 	};
+	const onInput = (event: unknown): undefined => {
+		if (disposed || !event || typeof event !== "object") return undefined;
+		const input = event as { source?: unknown; streamingBehavior?: unknown; text?: unknown; content?: unknown };
+		if (input.source !== "extension" || input.streamingBehavior !== "steer") return undefined;
+		const text = typeof input.text === "string" ? input.text : typeof input.content === "string" ? input.content : undefined;
+		if (!text) return undefined;
+		const ids = pending.get(text);
+		const requestId = ids?.shift();
+		if (!requestId) return undefined;
+		if (ids?.length === 0) pending.delete(text);
+		acknowledge({ type: "steer", id: requestId, ts: Date.now(), message: text }, "delivered", "Pi accepted the correlated steering input.");
+		return undefined;
+	};
 	const start = (): void => {
 		if (started || disposed) return;
 		try {
 			fs.mkdirSync(steerInbox, { recursive: true });
+			publishCapability();
 		} catch {
 			return;
 		}
 		started = true;
 		try {
-			watcher = fs.watch(steerInbox, () => flush());
+			watcher = (deps.watch ?? fs.watch)(resolveWatchPath(steerInbox, deps.nativeRealpath), () => flush());
 			watcher.on("error", () => {});
 		} catch {
 			watcher = undefined;
@@ -239,21 +309,20 @@ function registerSteeringInbox(pi: ExtensionAPI): void {
 	};
 	const activate = (): undefined => {
 		start();
-		canSteer = true;
 		flush();
 		return undefined;
 	};
 
 	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown) => unknown) => void;
+	// Register input before the watcher so an accepted extension input cannot race request dispatch.
+	onRuntimeEvent("input", onInput);
 	onRuntimeEvent("session_start", () => start());
 	for (const eventName of ["message_start", "message_update", "message_end", "tool_execution_start", "tool_execution_end", "turn_end"] as const) {
 		onRuntimeEvent(eventName, activate);
 	}
 	onRuntimeEvent("session_shutdown", () => {
 		disposed = true;
-		try {
-			watcher?.close();
-		} catch {}
+		try { watcher?.close(); } catch {}
 		if (interval) clearInterval(interval);
 	});
 }
@@ -261,6 +330,23 @@ function registerSteeringInbox(pi: ExtensionAPI): void {
 export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 	registerSteeringInbox(pi);
 	registerToolBudget(pi, decodeToolBudgetEnv(process.env[TOOL_BUDGET_ENV]));
+	registerChildWatchdog(pi);
+	const waitToolEnabled = resolveWaitToolConfig().enabled;
+	const waitState = {
+		baseCwd: "",
+		currentSessionId: null,
+		asyncJobs: new Map(),
+		foregroundControls: new Map(),
+		lastForegroundControlId: null,
+		cleanupTimers: new Map(),
+		lastUiContext: null,
+		poller: null,
+		completionSeen: new Map(),
+		watcher: null,
+		watcherRestartTimer: null,
+		resultFileCoalescer: { schedule: () => false, clear: () => {} },
+	} as unknown as SubagentState;
+	if (typeof pi.registerTool === "function") registerWaitTool(pi, waitState, waitToolEnabled);
 	let nativeSupervisorClientRegistered = false;
 	let nativeSupervisorFallbackRegistered = false;
 	const registerNativeSupervisorClientOnce = (): void => {
@@ -275,7 +361,16 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 		registerNativeSupervisorClient(pi);
 	};
 	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown) => unknown) => void;
-	onRuntimeEvent("session_start", registerNativeSupervisorClientOnce);
+	onRuntimeEvent("session_start", (_event: unknown, ctx: unknown) => {
+		const sessionManager = (ctx as { sessionManager?: Parameters<typeof resolveCurrentSessionId>[0] } | undefined)?.sessionManager;
+		waitState.currentSessionId = sessionManager ? resolveCurrentSessionId(sessionManager) : null;
+		registerNativeSupervisorClientOnce();
+		refreshChildToolDiagnostic(pi);
+	});
+	onRuntimeEvent("agent_end", async (_event: unknown, ctx: unknown) => {
+		if ((ctx as { hasUI?: boolean } | undefined)?.hasUI === true) return;
+		await drainOutstandingWork({ state: waitState, events: pi.events });
+	});
 	const structuredOutputPath = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV];
 	const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
 	if (structuredOutputPath && structuredSchemaPath) {
@@ -322,6 +417,7 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 
 	onRuntimeEvent("before_agent_start", async (event: { systemPrompt: string }) => {
 		registerNativeSupervisorFallbackOnce();
+		const toolDiagnostic = refreshChildToolDiagnostic(pi);
 		const intercomSessionName = process.env[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
 		if (intercomSessionName && typeof pi.setSessionName === "function") {
 			pi.setSessionName(intercomSessionName);
@@ -330,12 +426,17 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 		const inheritProjectContext = readBooleanEnv(SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV);
 		const inheritSkills = readBooleanEnv(SUBAGENT_INHERIT_SKILLS_ENV);
 		const fanoutChild = readBooleanEnv(SUBAGENT_FANOUT_CHILD_ENV);
-		if (inheritProjectContext === undefined && inheritSkills === undefined && fanoutChild === undefined) return;
-		const rewritten = rewriteSubagentPrompt(event.systemPrompt, {
-			inheritProjectContext: inheritProjectContext ?? true,
-			inheritSkills: inheritSkills ?? true,
-			fanoutChild: fanoutChild === true,
-		});
+		let rewritten = event.systemPrompt;
+		if (inheritProjectContext !== undefined || inheritSkills !== undefined || fanoutChild !== undefined) {
+			rewritten = rewriteSubagentPrompt(event.systemPrompt, {
+				inheritProjectContext: inheritProjectContext ?? true,
+				inheritSkills: inheritSkills ?? true,
+				fanoutChild: fanoutChild === true,
+			});
+		}
+		if (toolDiagnostic) {
+			rewritten = `${formatChildToolDiagnostic(toolDiagnostic)}\nDo not claim tool-dependent work succeeded; report this configuration error to the parent.\n\n${rewritten}`;
+		}
 		if (rewritten === event.systemPrompt) return;
 		return { systemPrompt: rewritten };
 	});

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

@@ -0,0 +1,176 @@
+/**
+ * Shared task mutation-intent classifier.
+ *
+ * Single authority for reading a task's wording, answering two different
+ * questions from one prohibition analysis:
+ *
+ * - `classifyTaskMutationIntent` / `expectsImplementationMutation`: does the
+ *   task REQUIRE file changes? Consumed by the completion mutation guard,
+ *   which blocks completion, so its vocabulary is deliberately narrow.
+ * - `taskMayMutate`: COULD the task plausibly change files? Consumed by
+ *   acceptance level inference, which only raises evidence gates, so its
+ *   vocabulary is deliberately broad (any bare write verb).
+ *
+ * Explicit read-only wording ("do not modify", "review only") is a task-level
+ * intent only when no write imperative survives outside those phrases. A task
+ * like "Do not modify tests; implement the fix" is an implementation task with
+ * a scoped constraint, not a read-only task.
+ */
+
+const REVIEW_ONLY_PATTERNS = [
+	/\breview only\b/i,
+	/\bsuggest fixes only\b/i,
+	/\bonly return findings\b/i,
+	/\breturn findings only\b/i,
+];
+
+const REVIEWER_REQUIRED_EDIT_PATTERNS = [
+	/\bmust\s+(?:edit|modify|change|fix|patch|apply)\b/i,
+	/\brequired\s+to\s+(?:edit|modify|change|fix|patch|apply)\b/i,
+	/\bregardless\s+of\s+findings\b/i,
+	/\balways\s+(?:edit|modify|change|fix|patch|apply)\b/i,
+	/\bapply\s+(?:the\s+)?fix(?:es)?\s+directly\b/i,
+	/\bmake\s+(?:the\s+)?code\s+changes\b/i,
+];
+
+// The prohibition's object ends at punctuation or at a coordinating word
+// (but/and/then), so a follow-on clause like "but implement the fix" stays in
+// the text for write-intent testing instead of being swallowed as the object.
+const NO_EDIT_PROHIBITION_PATTERN = /\b(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b((?:(?!\b(?:but|and|then)\b)[^.;,:!?\n–—-])*)/gi;
+
+/** Objects of a no-edit prohibition that mean "the codebase in general" rather than a named scope. */
+const GENERIC_PROHIBITION_OBJECT = /^\s*(?:(?:any|all|the|these|those|your|our|existing|project|source|sources|repo|repository)[\s/,-]*)*(?:files?|code|codebase|sources?|anything|repo(?:sitory)?)?\s*$/i;
+
+const SCOPED_NO_EDIT_CONSTRAINT_PATTERNS = [
+	/\bdo not edit files?\s+outside\b/i,
+	/\bdo not edit\s+outside\b/i,
+	/\bdo not edit\s+unrelated files?\b/i,
+	/\bdo not change\s+unrelated files?\b/i,
+	/\bdo not modify\s+unrelated files?\b/i,
+];
+
+const NO_TOOL_INTENT_PATTERNS = [
+	/\bno tools? needed\b/i,
+	/\bno tools? required\b/i,
+	/\bwithout using tools\b/i,
+	/\bdo not use tools\b/i,
+	/\bdon't use tools\b/i,
+];
+
+const READ_ONLY_DELIVERABLE_PATTERNS = [
+	/\b(?:draft|write|compose|prepare|produce)\s+(?:(?:a|an|the)\s+)?(?:github\s+)?(?:issue|bug report|issue draft|issue body|proposal|plan|report|summary|findings?|analysis|recommendations?)\b/i,
+	/\b(?:issue|bug report)\s+(?:draft|body|template)\b/i,
+	/\b(?:return|provide|produce)\s+(?:text|markdown|answer|findings?|recommendations?)\s+only\b/i,
+];
+
+const RESEARCH_AGENT_PATTERNS = [
+	/\binvestigate\b/i,
+	/\bscout\b/i,
+	/\bresearch(?:er)?\b/i,
+];
+
+const FIX_OR_PATCH_IMPLEMENTATION_PATTERN = /\b(?:fix|patch)\s+(?:(?:it|this|that|them|each|any|all|these|those)\b|(?:(?:a|an|the|any|all)\s+)?(?:(?:failing|failed|broken|flaky|red|cold|start|current|existing|reported|approved|known|regression|unit|integration|e2e|source|typescript|type-?script|ts|type-?check|compiler)\s+)*(?:bug|defect|issues?|problems?|failures?|regressions?|tests?|errors?|items?|typos?|code|source|implementation|component|function|module|class|method|logic|file|files|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command|lint(?:ing)?|build|ci|type-?check|type\s+checking)\b)/i;
+
+const WORKER_IMPLEMENTATION_PATTERNS = [
+	/\b(?:implement|edit|modify|refactor|delete)\b/i,
+	FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
+	/\b(?:update|add|remove|replace|create)\b(?!\s+(?:(?:a|an|the)\s+)?(?:report|summary|findings?)(?:\b|$))/i,
+	/\bapply\s+(?:the\s+)?(?:(?:suggested|proposed|recommended)\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
+	/\bmake\s+(?:the\s+)?changes\b/i,
+	/\bdo those fixes\b/i,
+];
+
+const GENERAL_IMPLEMENTATION_PATTERNS = [
+	/\b(?:implement|edit|modify|refactor)\b/i,
+	FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
+	/\bapply\s+(?:the\s+)?(?:(?:suggested|proposed|recommended)\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
+	/\bmake\s+(?:the\s+)?changes\b/i,
+	/\bdo those fixes\b/i,
+	/\b(?:update|add|remove|replace|delete|create)\s+(?:the\s+)?(?:file|files|code|source|implementation|test|tests|component|function|module|class|method|logic|import|imports|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command)\b/i,
+];
+
+export type TaskMutationIntent = { kind: "implementation" } | { kind: "read-only" } | { kind: "unknown" };
+
+function stripFrameworkInstructions(task: string): string {
+	return task
+		.split("\n")
+		.filter((line) => !/^\s*\[(?:Write to|Read from):/i.test(line))
+		.filter((line) => !/^\s*(?:Create and maintain progress at:|Update progress at:|\*\*Output:\*\*|Write your findings to(?: exactly this path)?:|Return the complete artifact in your final response\.|The runtime will persist it to exactly this path:|Do not call contact_supervisor merely because no write-capable tool is available\.|This path is authoritative for this run\.|Ignore any other output filename or output path mentioned elsewhere)/i.test(line))
+		.join("\n");
+}
+
+function stripPatterns(task: string, patterns: RegExp[]): string {
+	let stripped = task;
+	for (const pattern of patterns) {
+		const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
+		stripped = stripped.replace(new RegExp(pattern.source, flags), " ");
+	}
+	return stripped;
+}
+
+interface NoEditProhibitionAnalysis {
+	/** True when any prohibition (or review-only/no-tool wording) is present. */
+	present: boolean;
+	/** True when a prohibition covers files/code in general; such wording wins over write verbs. */
+	blanket: boolean;
+	/** Task text with prohibition phrases and their objects removed, for write-intent testing. */
+	strippedText: string;
+}
+
+function analyzeNoEditProhibitions(taskText: string): NoEditProhibitionAnalysis {
+	let present = REVIEW_ONLY_PATTERNS.some((pattern) => pattern.test(taskText))
+		|| NO_TOOL_INTENT_PATTERNS.some((pattern) => pattern.test(taskText));
+	let blanket = present;
+	let strippedText = stripPatterns(taskText, [...REVIEW_ONLY_PATTERNS, ...NO_TOOL_INTENT_PATTERNS]);
+	strippedText = strippedText.replace(new RegExp(NO_EDIT_PROHIBITION_PATTERN.source, NO_EDIT_PROHIBITION_PATTERN.flags), (_match, object: string) => {
+		present = true;
+		if (GENERIC_PROHIBITION_OBJECT.test(object)) blanket = true;
+		return " ";
+	});
+	return { present, blanket, strippedText };
+}
+
+function taskHasReadOnlyDeliverable(taskText: string): boolean {
+	return READ_ONLY_DELIVERABLE_PATTERNS.some((pattern) => pattern.test(taskText));
+}
+
+function hasImplementationIntent(agent: string, taskText: string): boolean {
+	if (/\breviewer\b/i.test(agent)) return REVIEWER_REQUIRED_EDIT_PATTERNS.some((pattern) => pattern.test(taskText));
+	if (agent === "worker") return WORKER_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));
+	return GENERAL_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));
+}
+
+export function classifyTaskMutationIntent(agent: string, task: string): TaskMutationIntent {
+	const taskText = stripFrameworkInstructions(task);
+	const taskTextWithoutScopedConstraints = stripPatterns(taskText, SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
+	const prohibitions = analyzeNoEditProhibitions(taskTextWithoutScopedConstraints);
+	if (prohibitions.present) {
+		if (prohibitions.blanket) return { kind: "read-only" };
+		return hasImplementationIntent(agent, prohibitions.strippedText) ? { kind: "implementation" } : { kind: "read-only" };
+	}
+
+	if (RESEARCH_AGENT_PATTERNS.some((pattern) => pattern.test(agent))) return { kind: "read-only" };
+	if (hasImplementationIntent(agent, taskText)) return { kind: "implementation" };
+	if (/\breviewer\b/i.test(agent)) return { kind: "read-only" };
+	return taskHasReadOnlyDeliverable(taskTextWithoutScopedConstraints) ? { kind: "read-only" } : { kind: "unknown" };
+}
+
+export function expectsImplementationMutation(agent: string, task: string): boolean {
+	return classifyTaskMutationIntent(agent, task).kind === "implementation";
+}
+
+/** Bare write verbs that make a task write-capable for acceptance inference. */
+const MAY_MUTATE_VERB_PATTERN = /\b(?:fix|implement|update|write|edit|modify|migrate|delete|remove|refactor|commit)\b/i;
+
+/**
+ * Whether the task could plausibly change files. Blanket prohibitions win;
+ * write verbs inside a scoped prohibition's object or a read-only deliverable
+ * phrase ("write a summary report") do not count; any other bare write verb
+ * does.
+ */
+export function taskMayMutate(task: string): boolean {
+	const taskText = stripPatterns(stripFrameworkInstructions(task), SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
+	const prohibitions = analyzeNoEditProhibitions(taskText);
+	if (prohibitions.blanket) return false;
+	return MAY_MUTATE_VERB_PATTERN.test(stripPatterns(prohibitions.strippedText, READ_ONLY_DELIVERABLE_PATTERNS));
+}

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

@@ -0,0 +1,65 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const REQUIRED_CHILD_TOOLS_ENV = "PI_SUBAGENT_REQUIRED_TOOLS";
+export const CHILD_TOOL_DIAGNOSTIC_PATH_ENV = "PI_SUBAGENT_TOOL_DIAGNOSTIC_PATH";
+
+export interface ChildToolDiagnostic {
+	agent?: string;
+	required: string[];
+	available: string[];
+	missing: string[];
+}
+
+export function writeChildToolDiagnostic(
+	filePath: string,
+	required: string[],
+	available: string[],
+	agent?: string,
+): ChildToolDiagnostic | undefined {
+	const availableNames = new Set(available);
+	const missing = required.filter((name) => !availableNames.has(name));
+	if (missing.length === 0) {
+		fs.rmSync(filePath, { force: true });
+		return undefined;
+	}
+
+	const diagnostic: ChildToolDiagnostic = { agent, required, available, missing };
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	fs.writeFileSync(filePath, JSON.stringify(diagnostic), { mode: 0o600 });
+	return diagnostic;
+}
+
+export function readChildToolDiagnostic(filePath: string | undefined): ChildToolDiagnostic | undefined {
+	if (!filePath || !fs.existsSync(filePath)) return undefined;
+	const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Partial<ChildToolDiagnostic>;
+	const stringArray = (value: unknown): value is string[] => Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.length > 0);
+	if (!stringArray(parsed.required) || !stringArray(parsed.available) || !stringArray(parsed.missing) || (parsed.agent !== undefined && typeof parsed.agent !== "string")) {
+		throw new Error(`Malformed child tool diagnostic at '${filePath}'.`);
+	}
+	return {
+		...(parsed.agent ? { agent: parsed.agent } : {}),
+		required: parsed.required,
+		available: parsed.available,
+		missing: parsed.missing,
+	};
+}
+
+export function formatChildToolDiagnostic(diagnostic: ChildToolDiagnostic): string {
+	const subject = diagnostic.agent ? `Agent '${diagnostic.agent}'` : "Subagent";
+	return [
+		`${subject} requested unavailable child tools: ${diagnostic.missing.join(", ")}.`,
+		"The `tools` field is a strict allowlist; it does not load extension code.",
+		"For extension tools, add the provider path to `subagentOnlyExtensions` (child-only), `extensions`, or as a path-like entry in `tools`, while keeping each registered tool name in `tools`.",
+		"For MCP tools, verify the MCP adapter configuration and selected tool names. For builtin tools, verify the name against the installed Pi version.",
+	].join("\n");
+}
+
+export function readChildToolDiagnosticError(filePath: string | undefined): string | undefined {
+	try {
+		const diagnostic = readChildToolDiagnostic(filePath);
+		return diagnostic ? formatChildToolDiagnostic(diagnostic) : undefined;
+	} catch (error) {
+		return `Failed to read child tool availability diagnostic: ${error instanceof Error ? error.message : String(error)}`;
+	}
+}

package/src/runs/shared/turn-budget.ts

@@ -2,6 +2,27 @@ import type { ResolvedTurnBudget, TurnBudgetState } from "../../shared/types.ts"
 
 export const DEFAULT_TURN_BUDGET_GRACE_TURNS = 1;
 
+export function resolveTurnBudgetConfig(
+	raw: unknown,
+	label = "turnBudget",
+): { turnBudget?: ResolvedTurnBudget; error?: string } {
+	if (raw === undefined) return {};
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+		return { error: `${label} must be an object with maxTurns and optional graceTurns.` };
+	}
+	const unknownField = Object.keys(raw).find((key) => key !== "maxTurns" && key !== "graceTurns");
+	if (unknownField) return { error: `${label}.${unknownField} is not supported.` };
+	const budget = raw as { maxTurns?: unknown; graceTurns?: unknown };
+	if (typeof budget.maxTurns !== "number" || !Number.isInteger(budget.maxTurns) || budget.maxTurns < 1) {
+		return { error: `${label}.maxTurns must be an integer >= 1.` };
+	}
+	const graceTurns = budget.graceTurns ?? DEFAULT_TURN_BUDGET_GRACE_TURNS;
+	if (typeof graceTurns !== "number" || !Number.isInteger(graceTurns) || graceTurns < 0) {
+		return { error: `${label}.graceTurns must be an integer >= 0.` };
+	}
+	return { turnBudget: { maxTurns: budget.maxTurns, graceTurns } };
+}
+
 export function appendTurnBudgetSystemPrompt(systemPrompt: string, budget: ResolvedTurnBudget | undefined): string {
 	if (!budget) return systemPrompt;
 	const grace = budget.graceTurns === 1 ? "1 additional assistant turn" : `${budget.graceTurns} additional assistant turns`;
@@ -24,6 +45,10 @@ export function turnBudgetExceededMessage(budget: ResolvedTurnBudget, turnCount:
 	return `Subagent exceeded turn budget after ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns} + grace ${budget.graceTurns}).`;
 }
 
+export function turnBudgetDeferredNote(budget: ResolvedTurnBudget, turnCount: number): string {
+	return `Turn-budget termination was deferred at ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns} + grace ${budget.graceTurns}) because the assistant started tool work. The run ended before another safe assistant boundary; output may be partial.`;
+}
+
 export function formatTurnBudgetOutput(message: string, output: string): string {
 	return output.trim()
 		? `${message}\n\nPartial output before turn-budget abort:\n${output}`
@@ -44,9 +69,29 @@ export function turnBudgetState(budget: ResolvedTurnBudget, turnCount: number, e
 	};
 }
 
-export function shouldAbortForTurnBudget(budget: ResolvedTurnBudget, turnCount: number, terminalAssistantStop: boolean): boolean {
+export function turnBudgetDeferredState(
+	budget: ResolvedTurnBudget,
+	turnCount: number,
+	terminationDeferredAtTurn = turnCount,
+): TurnBudgetState {
+	return {
+		...budget,
+		turnCount,
+		outcome: "termination-deferred",
+		wrapUpRequestedAtTurn: budget.maxTurns,
+		terminationDeferredAtTurn,
+	};
+}
+
+export function turnBudgetDecision(
+	budget: ResolvedTurnBudget,
+	turnCount: number,
+	terminalAssistantStop: boolean,
+	toolWorkActiveOrStarting: boolean,
+): "continue" | "defer" | "abort" {
 	const hardLimit = budget.maxTurns + budget.graceTurns;
-	if (turnCount < hardLimit) return false;
-	if (turnCount > hardLimit) return true;
-	return !terminalAssistantStop;
+	if (turnCount < hardLimit) return "continue";
+	if (toolWorkActiveOrStarting) return "defer";
+	if (turnCount === hardLimit && terminalAssistantStop) return "continue";
+	return "abort";
 }

package/src/shared/atomic-json.ts

@@ -8,6 +8,7 @@ type AtomicJsonWriterOptions = {
 	now?: () => number;
 	pid?: number;
 	random?: () => number;
+	mode?: number;
 	retryRenameErrors?: boolean;
 	retryDelaysMs?: readonly number[];
 	wait?: (delayMs: number) => void;
@@ -65,6 +66,7 @@ export function createAtomicJsonWriter(options: AtomicJsonWriterOptions = {}): (
 	const now = options.now ?? Date.now;
 	const pid = options.pid ?? process.pid;
 	const random = options.random ?? Math.random;
+	const mode = options.mode;
 	const retryRenameErrors = options.retryRenameErrors ?? process.platform === "win32";
 	const retryDelaysMs = retryRenameErrors ? options.retryDelaysMs ?? DEFAULT_RENAME_RETRY_DELAYS_MS : [];
 	const wait = options.wait ?? waitSync;
@@ -75,7 +77,7 @@ export function createAtomicJsonWriter(options: AtomicJsonWriterOptions = {}): (
 			`.${path.basename(filePath)}.${pid}.${now()}.${random().toString(36).slice(2)}.tmp`,
 		);
 		try {
-			fsImpl.writeFileSync(tempPath, JSON.stringify(payload, null, 2), "utf-8");
+			fsImpl.writeFileSync(tempPath, JSON.stringify(payload, null, 2), mode === undefined ? "utf-8" : { encoding: "utf-8", mode });
 			renameWithRetry(fsImpl, tempPath, filePath, retryDelaysMs, wait);
 		} finally {
 			fsImpl.rmSync(tempPath, { force: true });
@@ -84,3 +86,4 @@ export function createAtomicJsonWriter(options: AtomicJsonWriterOptions = {}): (
 }
 
 export const writeAtomicJson = createAtomicJsonWriter();
+export const writePrivateAtomicJson = createAtomicJsonWriter({ mode: 0o600 });