pi-improve-interation 0.0.1

package/node_modules/pi-subagents/src/runs/shared/subagent-startup-retry.ts

@@ -0,0 +1,116 @@
+import type { Usage } from "../../shared/types.ts";
+import { formatProcessSignalError } from "./process-signal.ts";
+
+/**
+ * Retry delays for child processes that exit before any model or tool activity.
+ * The schedule is intentionally short and bounded to avoid amplifying persistent
+ * launch failures while allowing concurrent Pi startup locks to clear.
+ */
+export const SUBAGENT_STARTUP_RETRY_DELAYS_MS = [250, 750, 1500] as const;
+
+/** A genuine startup race should fail well before a model request can complete. */
+export const MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS = 2000;
+
+const SIGKILL_PROCESS_SIGNAL_ERROR = formatProcessSignalError("SIGKILL");
+const EXTENSION_REGISTRATION_CONFLICT_PATTERN = /Failed to load extension\b[^\n]*:\s*(?:Tool|Flag)\s+"[^"]+"\s+conflicts with\b/i;
+
+export interface SubagentStartupFailureEvidence {
+	exitCode: number | null | undefined;
+	error?: string;
+	finalOutput?: string;
+	messageCount: number;
+	toolCount: number;
+	usage: Usage;
+	durationMs: number;
+	protocolError?: unknown;
+	processSignal?: string | null;
+	observedMutationAttempt?: boolean;
+	detached?: boolean;
+	interrupted?: boolean;
+	timedOut?: boolean;
+	stopped?: boolean;
+	turnBudgetExceeded?: boolean;
+}
+
+export function formatSubagentExtensionConflictError(
+	error: string | undefined,
+	input: { agent: string; ambientExtensionsEnabled: boolean },
+): string | undefined {
+	if (!error || !input.ambientExtensionsEnabled || !EXTENSION_REGISTRATION_CONFLICT_PATTERN.test(error)) return error;
+	const settings = JSON.stringify({
+		subagents: { agentOverrides: { [input.agent]: { extensions: [] } } },
+	});
+	return `${error}\n\nSubagent startup loaded conflicting ambient Pi extensions. Retry this run after disabling ambient extension discovery for agent ${JSON.stringify(input.agent)} in project .pi/settings.json: ${settings}. Replace the empty array with only the required extension entry paths when this agent needs extension tools.`;
+}
+
+function hasUsage(usage: Usage): boolean {
+	return usage.input !== 0
+		|| usage.output !== 0
+		|| usage.cacheRead !== 0
+		|| usage.cacheWrite !== 0
+		|| usage.cost !== 0
+		|| usage.turns !== 0;
+}
+
+/**
+ * Classify only unexplained, zero-activity child exits as startup failures.
+ * This intentionally fails closed: any model output, tool activity, usage,
+ * mutation evidence, diagnostic, or lifecycle interruption prevents a retry.
+ */
+export function isRetryableSubagentStartupFailure(evidence: SubagentStartupFailureEvidence): boolean {
+	return evidence.exitCode !== undefined
+		&& evidence.exitCode !== null
+		&& evidence.exitCode !== 0
+		&& (!evidence.error?.trim() || evidence.error === SIGKILL_PROCESS_SIGNAL_ERROR)
+		&& !evidence.finalOutput?.trim()
+		&& evidence.messageCount === 0
+		&& evidence.toolCount === 0
+		&& !hasUsage(evidence.usage)
+		&& evidence.durationMs >= 0
+		&& evidence.durationMs <= MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS
+		&& evidence.protocolError === undefined
+		&& (evidence.processSignal === undefined || evidence.processSignal === null || evidence.processSignal === "SIGKILL")
+		&& evidence.observedMutationAttempt !== true
+		&& evidence.detached !== true
+		&& evidence.interrupted !== true
+		&& evidence.timedOut !== true
+		&& evidence.stopped !== true
+		&& evidence.turnBudgetExceeded !== true;
+}
+
+export function formatSubagentStartupRetryNote(input: {
+	model: string;
+	attempt: number;
+	maxAttempts: number;
+	delayMs: number;
+}): string {
+	return `[startup-retry] ${input.model} exited before model or tool activity (attempt ${input.attempt}/${input.maxAttempts}). Retrying the same model in ${input.delayMs}ms.`;
+}
+
+export function formatSubagentStartupRetryExhaustedError(input: {
+	model: string;
+	attempts: number;
+}): string {
+	return `Subagent failed to start after ${input.attempts} attempts on ${input.model}; no model, tool, output, usage, or diagnostic activity was observed. This may be a concurrent Pi startup race. Retry the run or temporarily lower subagent concurrency.`;
+}
+
+/** Wait for a retry delay, returning false when any lifecycle signal aborts it. */
+export async function waitForSubagentStartupRetry(delayMs: number, signals: Array<AbortSignal | undefined>): Promise<boolean> {
+	const activeSignals = signals.filter((signal): signal is AbortSignal => Boolean(signal));
+	if (activeSignals.some((signal) => signal.aborted)) return false;
+	if (delayMs <= 0) return true;
+
+	return await new Promise<boolean>((resolve) => {
+		let settled = false;
+		const finish = (shouldRetry: boolean): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			for (const signal of activeSignals) signal.removeEventListener("abort", abort);
+			resolve(shouldRetry);
+		};
+		const abort = (): void => finish(false);
+		const timer = setTimeout(() => finish(true), delayMs);
+		for (const signal of activeSignals) signal.addEventListener("abort", abort, { once: true });
+	});
+}

package/node_modules/pi-subagents/src/runs/shared/task-intent.ts

@@ -0,0 +1,208 @@
+/**
+ * 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|implement)\b/i,
+	/\brequired\s+to\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
+	/(?:^|[.!?\n]\s*)implement\s+(?:the\s+)?(?:approved|requested|specified|file|code|source|fix(?:es)?|changes?)\b/i,
+	/\bregardless\s+of\s+findings\b/i,
+	/\balways\s+(?:edit|modify|change|fix|patch|apply|implement)\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, a serialized line separator,
+// or 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.
+// Accept serialized line separators too: workflow prompts can carry literal
+// `\\n`/`\\r\\n` between clauses instead of decoded newlines.
+const NO_EDIT_PROHIBITION_PATTERN = /(?:\b|\\(?:r\\n|n))(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b((?:(?!\b(?:but|and|then)\b|\\(?:r\\n|n))[^.;,:!?\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|product|source|sources|config|configs|repo|repository)[\s/,-]*)*(?:files?|code|codebase|sources?|anything|repo(?:sitory)?)?\s*$/i;
+const SCOPED_PROHIBITION_CONTINUATION = /^(?:\\(?:r\\n|n)|\r?\n)\s*(?:in|inside|under|within|outside|except|other\s+than|besides)\b/i;
+const OUTPUT_INSTRUCTION_CONTINUATION = /^(?:\\(?:r\\n|n)|\r?\n)\s*(?:in|inside|within)\s+(?:(?:(?:your|the)\s+)(?:final\s+)?|final\s+)(?:output|response|report|answer|reply|message|summary|findings?|analysis|recommendations?)(?:\s*\/\s*(?:output|response|report|answer|reply|message|summary|findings?|analysis|recommendations?))*\b(?![\\/])/i;
+
+function hasScopedProhibitionContinuation(text: string): boolean {
+	return SCOPED_PROHIBITION_CONTINUATION.test(text) && !OUTPUT_INSTRUCTION_CONTINUATION.test(text);
+}
+
+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,
+];
+
+// Review/severity vocabulary like "must-fix items" or "should-fix tests" is not
+// the verb. Rather than dash-guarding every pattern (which would also suppress
+// CLI flags like "--fix" and genuine clause-level dashes like "branch—fix it"),
+// strip the known severity compounds (must|should|needs + dash + verb) from the
+// task text before matching. Dash coverage: ASCII hyphen + U+2010..U+2015.
+const SEVERITY_COMPOUND_PATTERN = /\b(?:must|should|needs)[\-\u2010-\u2015](?:fix|edit|update|add|remove|replace|create|apply|make|do|implement|modify|delete|patch)\b/gi;
+
+function stripSeverityCompounds(task: string): string {
+	return task.replace(SEVERITY_COMPOUND_PATTERN, " ");
+}
+export { stripSeverityCompounds };
+
+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, offset: number, source: string) => {
+		present = true;
+		if (GENERIC_PROHIBITION_OBJECT.test(object) && !hasScopedProhibitionContinuation(source.slice(offset + match.length))) blanket = true;
+		return " ";
+	});
+	// Restore boundaries after stripping a prohibition from serialized prompts.
+	strippedText = strippedText.replace(/\\(?:r\\n|n)/g, "\n");
+	return { present, blanket, strippedText };
+}
+
+function taskHasReadOnlyDeliverable(taskText: string): boolean {
+	return READ_ONLY_DELIVERABLE_PATTERNS.some((pattern) => pattern.test(taskText));
+}
+
+function isReviewerStyleAgent(agent: string): boolean {
+	return /\b(?:advisor|reviewer|oracle)\b/i.test(agent);
+}
+
+function hasImplementationIntent(agent: string, taskText: string): boolean {
+	if (isReviewerStyleAgent(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 = stripSeverityCompounds(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 (isReviewerStyleAgent(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.
+ * Severity compounds ("must-fix items") are stripped before matching, so they
+ * are not write imperatives, while CLI flags ("--fix", "-w"), clause-level
+ * dashes ("branch—fix it"), and hyphenated imperatives ("hot-fix the bug")
+ * all stay write-capable. */
+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(stripSeverityCompounds(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/node_modules/pi-subagents/src/runs/shared/tool-availability.ts

@@ -0,0 +1,81 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const REQUIRED_CHILD_TOOLS_ENV = "PI_SUBAGENT_REQUIRED_TOOLS";
+export const MCP_DIRECT_CHILD_TOOLS_ENV = "PI_SUBAGENT_MCP_DIRECT_TOOLS";
+export const CHILD_TOOL_DIAGNOSTIC_PATH_ENV = "PI_SUBAGENT_TOOL_DIAGNOSTIC_PATH";
+
+export interface ChildToolDiagnostic {
+	agent?: string;
+	required: string[];
+	available: string[];
+	missing: string[];
+	missingMcpDirectTools?: string[];
+}
+
+export function writeChildToolDiagnostic(
+	filePath: string,
+	required: string[],
+	available: string[],
+	agent?: string,
+	mcpDirectTools?: 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 missingMcpDirectTools = mcpDirectTools?.length
+		? missing.filter((name) => mcpDirectTools.includes(name))
+		: [];
+	const diagnostic: ChildToolDiagnostic = {
+		agent,
+		required,
+		available,
+		missing,
+		...(missingMcpDirectTools.length > 0 ? { missingMcpDirectTools } : {}),
+	};
+	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") || (parsed.missingMcpDirectTools !== undefined && !stringArray(parsed.missingMcpDirectTools))) {
+		throw new Error(`Malformed child tool diagnostic at '${filePath}'.`);
+	}
+	return {
+		...(parsed.agent ? { agent: parsed.agent } : {}),
+		required: parsed.required,
+		available: parsed.available,
+		missing: parsed.missing,
+		...(parsed.missingMcpDirectTools ? { missingMcpDirectTools: parsed.missingMcpDirectTools } : {}),
+	};
+}
+
+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.",
+		...(diagnostic.missingMcpDirectTools?.length
+			? [`Resolved MCP direct tools missing from the child registry: ${diagnostic.missingMcpDirectTools.join(", ")}. This indicates a host/pi-mcp-adapter registration problem, not a tool-call failure.`]
+			: []),
+		"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/node_modules/pi-subagents/src/runs/shared/tool-budget.ts

@@ -0,0 +1,80 @@
+import type { ResolvedToolBudget, ToolBudgetConfig, ToolBudgetState } from "../../shared/types.ts";
+
+export const DEFAULT_TOOL_BUDGET_BLOCK = ["read", "grep", "find", "ls"] as const;
+export const TOOL_BUDGET_ENV = "PI_SUBAGENT_TOOL_BUDGET";
+export const TOOL_BUDGET_ZERO_AUTH_ENV = "PI_SUBAGENT_TOOL_BUDGET_ZERO_AUTH";
+
+export function normalizeToolBudgetBlock(block: ToolBudgetConfig["block"] | undefined): "*" | string[] {
+	if (block === "*") return "*";
+	if (block === undefined) return [...DEFAULT_TOOL_BUDGET_BLOCK];
+	return [...new Set(block.map((tool) => tool.trim()).filter(Boolean))];
+}
+
+export function validateToolBudgetConfig(
+	raw: unknown,
+	label = "toolBudget",
+	options: { minimumHard?: 0 | 1 } = {},
+): { budget?: ResolvedToolBudget; error?: string } {
+	if (raw === undefined) return {};
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { error: `${label} must be an object with hard and optional soft/block.` };
+	const value = raw as ToolBudgetConfig;
+	const minimumHard = options.minimumHard ?? 1;
+	if (typeof value.hard !== "number" || !Number.isInteger(value.hard) || value.hard < minimumHard) {
+		return { error: `${label}.hard must be an integer >= ${minimumHard}.` };
+	}
+	if (value.soft !== undefined && (typeof value.soft !== "number" || !Number.isInteger(value.soft) || value.soft < 1)) {
+		return { error: `${label}.soft must be an integer >= 1 when provided.` };
+	}
+	if (value.soft !== undefined && value.soft > value.hard) {
+		return { error: `${label}.soft must be <= ${label}.hard.` };
+	}
+	if (value.block !== undefined && value.block !== "*") {
+		if (!Array.isArray(value.block)) return { error: `${label}.block must be "*" or an array of tool names.` };
+		if (value.block.length === 0) return { error: `${label}.block must contain at least one tool name.` };
+		for (const item of value.block) {
+			if (typeof item !== "string" || !item.trim()) return { error: `${label}.block must contain non-empty tool names.` };
+		}
+	}
+	return { budget: { hard: value.hard, ...(value.soft !== undefined ? { soft: value.soft } : {}), block: normalizeToolBudgetBlock(value.block) } };
+}
+
+export function initialToolBudgetState(budget: ResolvedToolBudget): ToolBudgetState {
+	return { ...budget, toolCount: 0, outcome: "within-budget" };
+}
+
+export function toolBudgetState(budget: ResolvedToolBudget, toolCount: number, blockedTool?: string): ToolBudgetState {
+	const overHard = toolCount > budget.hard;
+	const overSoft = budget.soft !== undefined && toolCount >= budget.soft;
+	return {
+		...budget,
+		toolCount,
+		outcome: overHard ? "hard-blocked" : overSoft ? "soft-reached" : "within-budget",
+		...(overSoft ? { softReachedAt: budget.soft } : {}),
+		...(overHard ? { hardReachedAt: budget.hard, blockedTool } : {}),
+	};
+}
+
+export function shouldBlockToolForBudget(budget: ResolvedToolBudget, toolName: string, nextToolCount: number): boolean {
+	if (nextToolCount <= budget.hard) return false;
+	return budget.block === "*" || budget.block.includes(toolName);
+}
+
+export function toolBudgetSoftNudge(budget: ResolvedToolBudget, toolCount: number): string {
+	return `Tool budget soft limit reached after ${toolCount} tool call${toolCount === 1 ? "" : "s"} (soft ${budget.soft}, hard ${budget.hard}). Stop starting new browsing/search work and finalize from the context you already have.`;
+}
+
+export function toolBudgetBlockedMessage(budget: ResolvedToolBudget, toolName: string, toolCount: number): string {
+	return `Tool budget hard limit reached after ${toolCount} tool call${toolCount === 1 ? "" : "s"} (hard ${budget.hard}). The '${toolName}' tool is blocked so you can finalize from the context you already have.`;
+}
+
+export function encodeToolBudgetEnv(budget: ResolvedToolBudget | undefined): string | undefined {
+	return budget ? JSON.stringify(budget) : undefined;
+}
+
+export function decodeToolBudgetEnv(value: string | undefined, options: { allowZero?: boolean } = {}): ResolvedToolBudget | undefined {
+	if (!value?.trim()) return undefined;
+	const parsed = JSON.parse(value) as unknown;
+	const normalized = validateToolBudgetConfig(parsed, TOOL_BUDGET_ENV, options.allowZero ? { minimumHard: 0 } : undefined);
+	if (normalized.error) throw new Error(normalized.error);
+	return normalized.budget;
+}

package/node_modules/pi-subagents/src/runs/shared/tool-timeout.ts

@@ -0,0 +1,93 @@
+export const TOOL_TIMEOUT_ENV = "PI_SUBAGENT_TOOL_TIMEOUT_MS";
+
+/** Maximum delay a Node.js timer accepts without overflow. */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+export const DEFAULT_FAST_TOOL_TIMEOUT_MS = 300_000;
+
+export const DEFAULT_FAST_TOOL_TIMEOUT_TOOLS = new Set([
+	"read",
+	"grep",
+	"find",
+	"ls",
+	"edit",
+	"write",
+	"structured_output",
+]);
+
+/** Tools whose normal job can be to wait for a person or another run. */
+export const TOOL_TIMEOUT_EXEMPT_TOOLS = new Set(["contact_supervisor", "intercom", "bg_wait"]);
+
+// Backward-compatible export name for existing callers/tests.
+export const TOOL_TIMEOUT_ALLOWLIST = TOOL_TIMEOUT_EXEMPT_TOOLS;
+
+export function isToolTimeoutExempt(toolName: string | undefined): boolean {
+	return toolName !== undefined && TOOL_TIMEOUT_EXEMPT_TOOLS.has(toolName);
+}
+
+export function defaultToolTimeoutMs(toolName: string | undefined): number | undefined {
+	return toolName !== undefined && DEFAULT_FAST_TOOL_TIMEOUT_TOOLS.has(toolName)
+		? DEFAULT_FAST_TOOL_TIMEOUT_MS
+		: undefined;
+}
+
+export function effectiveToolTimeoutMs(toolName: string | undefined, configuredToolTimeoutMs: number | undefined): number | undefined {
+	if (isToolTimeoutExempt(toolName)) return undefined;
+	return configuredToolTimeoutMs ?? defaultToolTimeoutMs(toolName);
+}
+
+export function formatToolTimeoutMessage(toolName: string, timeoutMs: number): string {
+	return `Tool '${toolName}' exceeded its timeout of ${timeoutMs}ms.`;
+}
+
+export function toolTimeoutCallKey(event: { toolCallId?: unknown; toolName?: unknown }, fallbackId: number): string {
+	return typeof event.toolCallId === "string" && event.toolCallId.length > 0
+		? `id:${event.toolCallId}`
+		: `anon:${String(event.toolName ?? "tool")}:${fallbackId}`;
+}
+
+export interface ToolTimeoutResolutionInput {
+	/** Per-call value from the subagent tool params (highest precedence). */
+	callValue?: unknown;
+	/** Agent frontmatter default (second precedence). */
+	agentValue?: number;
+	/** Global extension config.toolTimeoutMs (third precedence). */
+	configValue?: unknown;
+	/** PI_SUBAGENT_TOOL_TIMEOUT_MS environment override (lowest precedence). */
+	envValue?: string | undefined;
+}
+
+/** Resolve the configured hard timeout. Default fast-tool timeouts apply later per tool name. */
+export function resolveToolTimeoutMs(input: ToolTimeoutResolutionInput): { toolTimeoutMs?: number; error?: string } {
+	const candidates: Array<{ label: string; value: unknown }> = [
+		{ label: "toolTimeoutMs", value: input.callValue },
+		{ label: "agent.toolTimeoutMs", value: input.agentValue },
+		{ label: "config.toolTimeoutMs", value: input.configValue },
+	];
+	let winner: { label: string; value: unknown } | undefined;
+	for (const candidate of candidates) {
+		if (candidate.value === undefined) continue;
+		winner = candidate;
+		break;
+	}
+	if (winner === undefined && input.envValue !== undefined && input.envValue.trim() !== "") {
+		winner = { label: TOOL_TIMEOUT_ENV, value: input.envValue };
+	}
+	if (winner === undefined) return {};
+
+	let raw: unknown = winner.value;
+	let parsed: number;
+	if (winner.label === TOOL_TIMEOUT_ENV && typeof raw === "string") {
+		parsed = Number(raw);
+		if (raw.trim() !== "" && !Number.isNaN(parsed)) raw = parsed;
+	}
+	if (typeof raw !== "number" || !Number.isInteger(raw) || raw <= 0 || raw > MAX_TIMER_DELAY_MS) {
+		return { error: `${winner.label} must be a positive integer no larger than ${MAX_TIMER_DELAY_MS}.` };
+	}
+	return { toolTimeoutMs: raw };
+}
+
+/** Read the environment override without requiring callers to know the name. */
+export function toolTimeoutFromEnv(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	return env[TOOL_TIMEOUT_ENV];
+}

package/node_modules/pi-subagents/src/runs/shared/usage-budget.ts

@@ -0,0 +1,65 @@
+import type { CostSummary, UsageBudgetConfig, UsageBudgetLimitConfig, UsageBudgetState } from "../../shared/types.ts";
+
+function validateLimit(value: unknown, label: string): { limit?: UsageBudgetLimitConfig; error?: string } {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return { error: `${label} must be an object.` };
+	const raw = value as Record<string, unknown>;
+	const unknown = Object.keys(raw).find((key) => key !== "soft" && key !== "hard");
+	if (unknown) return { error: `${label}.${unknown} is not supported.` };
+	if (typeof raw.hard !== "number" || !Number.isFinite(raw.hard) || raw.hard <= 0) return { error: `${label}.hard must be a positive number.` };
+	if (raw.soft !== undefined && (typeof raw.soft !== "number" || !Number.isFinite(raw.soft) || raw.soft <= 0)) return { error: `${label}.soft must be a positive number.` };
+	if (typeof raw.soft === "number" && raw.soft > raw.hard) return { error: `${label}.soft must be less than or equal to ${label}.hard.` };
+	return { limit: { ...(typeof raw.soft === "number" ? { soft: raw.soft } : {}), hard: raw.hard } };
+}
+
+export function validateUsageBudgetConfig(value: unknown, label = "usageBudget"): { budget?: UsageBudgetConfig; error?: string } {
+	if (value === undefined) return {};
+	if (!value || typeof value !== "object" || Array.isArray(value)) return { error: `${label} must be an object.` };
+	const raw = value as Record<string, unknown>;
+	const unknown = Object.keys(raw).find((key) => key !== "tokens" && key !== "costUsd");
+	if (unknown) return { error: `${label}.${unknown} is not supported.` };
+	const budget: UsageBudgetConfig = {};
+	if (raw.tokens !== undefined) {
+		const tokens = validateLimit(raw.tokens, `${label}.tokens`);
+		if (tokens.error) return { error: tokens.error };
+		budget.tokens = tokens.limit;
+	}
+	if (raw.costUsd !== undefined) {
+		const costUsd = validateLimit(raw.costUsd, `${label}.costUsd`);
+		if (costUsd.error) return { error: costUsd.error };
+		budget.costUsd = costUsd.limit;
+	}
+	if (!budget.tokens && !budget.costUsd) return { error: `${label} must include tokens or costUsd.` };
+	return { budget };
+}
+
+function metricState(limit: UsageBudgetLimitConfig | undefined, used: number): UsageBudgetState["tokens"] {
+	if (!limit) return undefined;
+	return {
+		...limit,
+		used,
+		outcome: used >= limit.hard ? "hard-exceeded" : limit.soft !== undefined && used >= limit.soft ? "soft-exceeded" : "within-budget",
+	};
+}
+
+export function usageBudgetState(config: UsageBudgetConfig | undefined, totals: CostSummary | undefined): UsageBudgetState | undefined {
+	if (!config) return undefined;
+	const inputTokens = totals?.inputTokens ?? 0;
+	const outputTokens = totals?.outputTokens ?? 0;
+	const tokens = metricState(config.tokens, inputTokens + outputTokens);
+	const costUsd = metricState(config.costUsd, totals?.costUsd ?? 0);
+	const reason = tokens?.outcome === "hard-exceeded" ? "tokens" : costUsd?.outcome === "hard-exceeded" ? "costUsd" : undefined;
+	return {
+		version: 1,
+		source: "reported",
+		...(tokens ? { tokens } : {}),
+		...(costUsd ? { costUsd } : {}),
+		exhausted: reason !== undefined,
+		...(reason ? { reason } : {}),
+	};
+}
+
+export function usageBudgetExceededMessage(state: UsageBudgetState): string {
+	if (state.reason === "tokens" && state.tokens) return `Usage budget exhausted: reported tokens ${state.tokens.used} reached hard limit ${state.tokens.hard}.`;
+	if (state.reason === "costUsd" && state.costUsd) return `Usage budget exhausted: reported cost $${state.costUsd.used.toFixed(6)} reached hard limit $${state.costUsd.hard.toFixed(6)}.`;
+	return "Usage budget exhausted.";
+}