pi-subagents 0.34.0 → 0.35.0

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

@@ -45,6 +45,7 @@ export interface PiSpawnDeps {
 	execPath?: string;
 	argv1?: string;
 	existsSync?: (filePath: string) => boolean;
+	realpathSync?: (filePath: string) => string;
 	readFileSync?: (filePath: string, encoding: "utf-8") => string;
 	resolvePackageJson?: () => string;
 	resolvePackageEntry?: () => string;
@@ -69,10 +70,11 @@ function normalizePath(filePath: string): string {
 	return path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
 }
 
-export function resolveWindowsPiCliScript(
+export function resolvePiCliScript(
 	deps: PiSpawnDeps = {},
 ): string | undefined {
 	const existsSync = deps.existsSync ?? fs.existsSync;
+	const realpathSync = deps.realpathSync ?? fs.realpathSync;
 	const readFileSync =
 		deps.readFileSync ??
 		((filePath, encoding) => fs.readFileSync(filePath, encoding));
@@ -81,7 +83,14 @@ export function resolveWindowsPiCliScript(
 	if (argv1) {
 		const argvPath = normalizePath(argv1);
 		if (isRunnableNodeScript(argvPath, existsSync)) {
-			return argvPath;
+			try {
+				const canonicalArgvPath = realpathSync(argvPath);
+				if (isRunnableNodeScript(canonicalArgvPath, existsSync) && findPiPackageRootFromEntry(canonicalArgvPath)) {
+					return canonicalArgvPath;
+				}
+			} catch {
+				// Host package metadata is untrusted here; keep resolving the installed Pi CLI.
+			}
 		}
 	}
 
@@ -115,7 +124,7 @@ export function resolveWindowsPiCliScript(
 			return candidate;
 		}
 	} catch {
-		// Windows CLI resolution is optional; falling back to `pi` lets PATH handle execution.
+		// Verified CLI resolution is optional; falling back to `pi` lets PATH handle execution.
 		return undefined;
 	}
 
@@ -132,15 +141,12 @@ export function getPiSpawnCommand(
 		return { command: piBinary, args };
 	}
 
-	const platform = deps.platform ?? process.platform;
-	if (platform === "win32") {
-		const piCliPath = resolveWindowsPiCliScript(deps);
-		if (piCliPath) {
-			return {
-				command: deps.execPath ?? process.execPath,
-				args: [piCliPath, ...args],
-			};
-		}
+	const piCliPath = resolvePiCliScript(deps);
+	if (piCliPath) {
+		return {
+			command: deps.execPath ?? process.execPath,
+			args: [piCliPath, ...args],
+		};
 	}
 
 	return { command: "pi", args };

package/src/runs/shared/session-lease.ts

@@ -0,0 +1,279 @@
+import { spawnSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createAtomicJsonWriter } from "../../shared/atomic-json.ts";
+import { TEMP_ROOT_DIR } from "../../shared/types.ts";
+
+export const SESSION_LEASES_DIR = path.join(TEMP_ROOT_DIR, "session-leases");
+
+export interface SessionLeaseRequest {
+	sessionFile: string;
+	runId: string;
+	sourceRunId: string;
+	parentSessionId?: string;
+}
+
+export interface SessionLeaseOwner {
+	version: 1;
+	token: string;
+	canonicalSessionFile: string;
+	runId: string;
+	sourceRunId: string;
+	parentSessionId?: string;
+	pid: number;
+	hostname: string;
+	processStartIdentity?: string;
+	writerState: "none" | "spawning" | "running";
+	writerPid?: number;
+	writerProcessStartIdentity?: string;
+	acquiredAt: string;
+	acquiredAtMs: number;
+	updatedAtMs: number;
+}
+
+export interface SessionLeaseHandle {
+	leaseDir: string;
+	owner: SessionLeaseOwner;
+	updateWriter(writer: { state: "none" | "spawning" } | { state: "running"; pid: number }): void;
+	release(): void;
+}
+
+interface SessionLeaseOptions {
+	rootDir?: string;
+	now?: () => number;
+	token?: () => string;
+	pid?: number;
+	hostname?: string;
+	processStartIdentity?: string;
+	isProcessAlive?: (pid: number) => boolean | undefined;
+	getProcessStartIdentity?: (pid: number) => string | undefined;
+}
+
+export class SessionLeaseConflictError extends Error {
+	readonly owner?: SessionLeaseOwner;
+
+	constructor(message: string, owner?: SessionLeaseOwner) {
+		super(message);
+		this.name = "SessionLeaseConflictError";
+		this.owner = owner;
+	}
+}
+
+function getProcessStartIdentity(pid: number): string | undefined {
+	if (process.platform === "linux") {
+		try {
+			const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf-8");
+			const commandEnd = stat.lastIndexOf(")");
+			if (commandEnd === -1) return undefined;
+			const fields = stat.slice(commandEnd + 1).trim().split(/\s+/);
+			const startTicks = fields[19];
+			return startTicks ? `linux:${startTicks}` : undefined;
+		} catch {
+			return undefined;
+		}
+	}
+	if (process.platform === "darwin" || process.platform === "freebsd") {
+		const result = spawnSync("/bin/ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf-8" });
+		const started = result.status === 0 ? result.stdout.trim() : "";
+		return started ? `${process.platform}:${started}` : undefined;
+	}
+	return undefined;
+}
+
+function processIsAlive(pid: number): boolean | undefined {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ESRCH") return false;
+		if (code === "EPERM") return true;
+		return undefined;
+	}
+}
+
+export function canonicalSessionFilePath(sessionFile: string): string {
+	return fs.realpathSync.native(path.resolve(sessionFile));
+}
+
+export function sessionLeaseDir(sessionFile: string, rootDir = SESSION_LEASES_DIR): string {
+	const canonical = canonicalSessionFilePath(sessionFile);
+	const key = process.platform === "win32" ? canonical.toLowerCase() : canonical;
+	const digest = createHash("sha256").update(key).digest("hex");
+	return path.join(rootDir, digest);
+}
+
+function parseOwner(value: unknown): SessionLeaseOwner | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const owner = value as Partial<SessionLeaseOwner>;
+	if (owner.version !== 1
+		|| typeof owner.token !== "string"
+		|| typeof owner.canonicalSessionFile !== "string"
+		|| typeof owner.runId !== "string"
+		|| typeof owner.sourceRunId !== "string"
+		|| typeof owner.pid !== "number"
+		|| !Number.isInteger(owner.pid)
+		|| owner.pid <= 0
+		|| typeof owner.hostname !== "string"
+		|| (owner.writerState !== "none" && owner.writerState !== "spawning" && owner.writerState !== "running")
+		|| typeof owner.acquiredAt !== "string"
+		|| typeof owner.acquiredAtMs !== "number"
+		|| typeof owner.updatedAtMs !== "number") return undefined;
+	if (owner.parentSessionId !== undefined && typeof owner.parentSessionId !== "string") return undefined;
+	if (owner.processStartIdentity !== undefined && typeof owner.processStartIdentity !== "string") return undefined;
+	if (owner.writerPid !== undefined && (typeof owner.writerPid !== "number" || !Number.isInteger(owner.writerPid) || owner.writerPid <= 0)) return undefined;
+	if (owner.writerProcessStartIdentity !== undefined && typeof owner.writerProcessStartIdentity !== "string") return undefined;
+	if (owner.writerState === "running" && owner.writerPid === undefined) return undefined;
+	if (owner.writerState !== "running" && (owner.writerPid !== undefined || owner.writerProcessStartIdentity !== undefined)) return undefined;
+	return owner as SessionLeaseOwner;
+}
+
+function readLeaseOwner(leaseDir: string): SessionLeaseOwner | undefined {
+	try {
+		return parseOwner(JSON.parse(fs.readFileSync(path.join(leaseDir, "owner.json"), "utf-8")));
+	} catch {
+		return undefined;
+	}
+}
+
+function conflictMessage(canonicalSessionFile: string, owner: SessionLeaseOwner | undefined): string {
+	if (!owner) {
+		return `Direct revival of session '${canonicalSessionFile}' is blocked by an existing lease with unreadable owner metadata. Refusing to reclaim it without proof that the owner is stale.`;
+	}
+	const parent = owner.parentSessionId ? `, parent session '${owner.parentSessionId}'` : "";
+	return `Direct revival of session '${canonicalSessionFile}' is already owned by run '${owner.runId}' (source run '${owner.sourceRunId}'${parent}, pid ${owner.pid} on ${owner.hostname}). Wait for that revival to finish or start a separate continuation without reusing this session file.`;
+}
+
+function processDemonstrablyGone(
+	pid: number,
+	startIdentity: string | undefined,
+	options: Required<Pick<SessionLeaseOptions, "isProcessAlive" | "getProcessStartIdentity">>,
+): boolean {
+	const alive = options.isProcessAlive(pid);
+	if (alive === false) return true;
+	if (alive !== true || !startIdentity) return false;
+	const currentIdentity = options.getProcessStartIdentity(pid);
+	return currentIdentity !== undefined && currentIdentity !== startIdentity;
+}
+
+function demonstrablyStale(owner: SessionLeaseOwner, options: Required<Pick<SessionLeaseOptions, "hostname" | "isProcessAlive" | "getProcessStartIdentity">>): boolean {
+	if (owner.hostname !== options.hostname) return false;
+	if (!processDemonstrablyGone(owner.pid, owner.processStartIdentity, options)) return false;
+	if (owner.writerState === "spawning") return false;
+	if (owner.writerState === "none") return true;
+	return owner.writerPid !== undefined
+		&& processDemonstrablyGone(owner.writerPid, owner.writerProcessStartIdentity, options);
+}
+
+function createLeaseDirectory(leaseDir: string, owner: SessionLeaseOwner): boolean {
+	const tempDir = `${leaseDir}.candidate-${owner.token}`;
+	fs.mkdirSync(path.dirname(leaseDir), { recursive: true, mode: 0o700 });
+	fs.rmSync(tempDir, { recursive: true, force: true });
+	fs.mkdirSync(tempDir, { mode: 0o700 });
+	try {
+		fs.writeFileSync(path.join(tempDir, "owner.json"), JSON.stringify(owner, null, 2), { encoding: "utf-8", mode: 0o600 });
+		try {
+			fs.renameSync(tempDir, leaseDir);
+			return true;
+		} catch (error) {
+			if (fs.existsSync(leaseDir)) return false;
+			throw error;
+		}
+	} finally {
+		fs.rmSync(tempDir, { recursive: true, force: true });
+	}
+}
+
+export function acquireSessionLease(request: SessionLeaseRequest, options: SessionLeaseOptions = {}): SessionLeaseHandle {
+	const canonicalSessionFile = canonicalSessionFilePath(request.sessionFile);
+	const rootDir = options.rootDir ?? SESSION_LEASES_DIR;
+	const leaseDir = sessionLeaseDir(canonicalSessionFile, rootDir);
+	const now = options.now ?? Date.now;
+	const pid = options.pid ?? process.pid;
+	const hostname = options.hostname ?? os.hostname();
+	const getIdentity = options.getProcessStartIdentity ?? getProcessStartIdentity;
+	const processStartIdentity = options.processStartIdentity
+		?? getIdentity(pid)
+		?? (pid === process.pid ? `runtime:${Math.round(Date.now() - process.uptime() * 1000)}` : undefined);
+	const acquiredAtMs = now();
+	const owner: SessionLeaseOwner = {
+		version: 1,
+		token: options.token?.() ?? randomUUID(),
+		canonicalSessionFile,
+		runId: request.runId,
+		sourceRunId: request.sourceRunId,
+		...(request.parentSessionId ? { parentSessionId: request.parentSessionId } : {}),
+		pid,
+		hostname,
+		...(processStartIdentity ? { processStartIdentity } : {}),
+		writerState: "none",
+		acquiredAt: new Date(acquiredAtMs).toISOString(),
+		acquiredAtMs,
+		updatedAtMs: acquiredAtMs,
+	};
+	const staleOptions = {
+		hostname,
+		isProcessAlive: options.isProcessAlive ?? processIsAlive,
+		getProcessStartIdentity: getIdentity,
+	};
+
+	for (let attempt = 0; attempt < 4; attempt++) {
+		if (createLeaseDirectory(leaseDir, owner)) {
+			const writeOwner = createAtomicJsonWriter();
+			return {
+				leaseDir,
+				owner,
+				updateWriter(writer) {
+					const currentOwner = readLeaseOwner(leaseDir);
+					if (!currentOwner || currentOwner.token !== owner.token) {
+						throw new Error(`Session revival lease ownership changed for run '${owner.runId}'.`);
+					}
+					const writerProcessStartIdentity = writer.state === "running" ? getIdentity(writer.pid) : undefined;
+					const nextOwner: SessionLeaseOwner = {
+						...owner,
+						writerState: writer.state,
+						...(writer.state === "running" ? { writerPid: writer.pid } : {}),
+						...(writerProcessStartIdentity ? { writerProcessStartIdentity } : {}),
+						updatedAtMs: now(),
+					};
+					delete nextOwner.writerPid;
+					delete nextOwner.writerProcessStartIdentity;
+					if (writer.state === "running") {
+						nextOwner.writerPid = writer.pid;
+						if (writerProcessStartIdentity) nextOwner.writerProcessStartIdentity = writerProcessStartIdentity;
+					}
+					writeOwner(path.join(leaseDir, "owner.json"), nextOwner);
+					delete owner.writerPid;
+					delete owner.writerProcessStartIdentity;
+					Object.assign(owner, nextOwner);
+				},
+				release() {
+					const currentOwner = readLeaseOwner(leaseDir);
+					if (!currentOwner || currentOwner.token !== owner.token) return;
+					fs.rmSync(leaseDir, { recursive: true, force: true });
+				},
+			};
+		}
+
+		const existingOwner = readLeaseOwner(leaseDir);
+		if (!existingOwner || !demonstrablyStale(existingOwner, staleOptions)) {
+			throw new SessionLeaseConflictError(conflictMessage(canonicalSessionFile, existingOwner), existingOwner);
+		}
+		// The per-owner tombstone is retained. Every contender that observed this
+		// stale token targets the same occupied destination, so only the first can
+		// rename it and later contenders cannot move a successor lease by mistake.
+		const tombstone = `${leaseDir}.stale-${existingOwner.token.replace(/[^A-Za-z0-9._-]/g, "-")}`;
+		try {
+			fs.renameSync(leaseDir, tombstone);
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code === "ENOENT" || fs.existsSync(tombstone)) continue;
+			throw error;
+		}
+	}
+
+	const existingOwner = readLeaseOwner(leaseDir);
+	throw new SessionLeaseConflictError(conflictMessage(canonicalSessionFile, existingOwner), existingOwner);
+}

package/src/runs/shared/single-output.ts

@@ -1,6 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import type { Message } from "@earendil-works/pi-ai";
 import type { OutputMode, SavedOutputReference } from "../../shared/types.ts";
+import { hasMutationToolCapability } from "./completion-guard.ts";
 
 export interface SingleOutputSnapshot {
 	exists: boolean;
@@ -8,6 +10,47 @@ export interface SingleOutputSnapshot {
 	size?: number;
 }
 
+/**
+ * Content the child itself sent to the configured output path, taken from its
+ * last `write` tool call whose tool result reports success. Unlike reading the
+ * path from disk, this cannot be polluted by a sibling run writing the same
+ * path (#420); requiring the successful tool result keeps failed, cancelled,
+ * or unanswered write calls from counting as authored output. Returns
+ * undefined when no such write exists (e.g. bash or edit-based construction),
+ * in which case callers must not assume file authorship.
+ */
+export function extractChildWrittenOutput(
+	messages: Message[] | undefined,
+	outputPath: string | undefined,
+	cwd?: string,
+): string | undefined {
+	if (!messages?.length || !outputPath) return undefined;
+	const resolvedTarget = path.resolve(cwd ?? ".", outputPath);
+	const comparableTarget = process.platform === "win32" ? resolvedTarget.toLowerCase() : resolvedTarget;
+	const successfulCallIds = new Set<string>();
+	for (const message of messages) {
+		if (message.role === "toolResult" && message.isError === false && typeof message.toolCallId === "string") {
+			successfulCallIds.add(message.toolCallId);
+		}
+	}
+	let content: string | undefined;
+	for (const message of messages) {
+		if (message.role !== "assistant") continue;
+		for (const part of message.content) {
+			if (part.type !== "toolCall" || part.name !== "write" || !successfulCallIds.has(part.id)) continue;
+			const args = typeof part.arguments === "object" && part.arguments !== null && !Array.isArray(part.arguments)
+				? part.arguments as Record<string, unknown>
+				: {};
+			if (typeof args.path !== "string" || typeof args.content !== "string") continue;
+			const resolvedWritePath = path.resolve(cwd ?? ".", args.path);
+			const comparableWritePath = process.platform === "win32" ? resolvedWritePath.toLowerCase() : resolvedWritePath;
+			if (comparableWritePath !== comparableTarget) continue;
+			content = args.content;
+		}
+	}
+	return content;
+}
+
 export function normalizeSingleOutputOverride(
 	output: string | boolean | undefined,
 	defaultOutput: string | undefined,
@@ -33,22 +76,34 @@ export function resolveSingleOutputPath(
 	return path.resolve(baseCwd, output);
 }
 
-function formatOutputPathInstruction(outputPath: string): string {
+interface OutputInstructionCapabilities {
+	tools?: string[];
+	mcpDirectTools?: string[];
+}
+
+function formatOutputPathInstruction(outputPath: string, capabilities?: OutputInstructionCapabilities): string {
+	const delivery = !capabilities || hasMutationToolCapability(capabilities.tools, capabilities.mcpDirectTools)
+		? `Write your findings to exactly this path: ${outputPath}`
+		: [
+			"Return the complete artifact in your final response.",
+			`The runtime will persist it to exactly this path: ${outputPath}`,
+			"Do not call contact_supervisor merely because no write-capable tool is available.",
+		].join("\n");
 	return [
-		`Write your findings to exactly this path: ${outputPath}`,
+		delivery,
 		"This path is authoritative for this run.",
 		"Ignore any other output filename or output path mentioned elsewhere, including output destinations in the base agent prompt, system prompt, or task instructions.",
 	].join("\n");
 }
 
-export function injectSingleOutputInstruction(task: string, outputPath: string | undefined): string {
+export function injectSingleOutputInstruction(task: string, outputPath: string | undefined, capabilities?: OutputInstructionCapabilities): string {
 	if (!outputPath) return task;
-	return `${task}\n\n---\n**Output:**\n${formatOutputPathInstruction(outputPath)}`;
+	return `${task}\n\n---\n**Output:**\n${formatOutputPathInstruction(outputPath, capabilities)}`;
 }
 
-export function injectOutputPathSystemPrompt(systemPrompt: string, outputPath: string | undefined): string {
+export function injectOutputPathSystemPrompt(systemPrompt: string, outputPath: string | undefined, capabilities?: OutputInstructionCapabilities): string {
 	if (!outputPath) return systemPrompt;
-	const instruction = `Runtime output path override:\n${formatOutputPathInstruction(outputPath)}`;
+	const instruction = `Runtime output path override:\n${formatOutputPathInstruction(outputPath, capabilities)}`;
 	return systemPrompt ? `${systemPrompt}\n\n${instruction}` : instruction;
 }
 

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

@@ -0,0 +1,128 @@
+import {
+	resolveMaxSubagentSpawnsPerSession,
+	type ExtensionConfig,
+	type SpawnBudgetSnapshot,
+	type SubagentState,
+} from "../../shared/types.ts";
+
+const MAX_GRANT_HISTORY = 20;
+
+function sessionState(state: SubagentState, config: ExtensionConfig, sessionId: string | null) {
+	let counters = state.subagentSpawns;
+	if (!counters || counters.sessionId !== sessionId) {
+		counters = {
+			sessionId,
+			count: 0,
+			configuredLimit: resolveMaxSubagentSpawnsPerSession(config.maxSubagentSpawnsPerSession) ?? null,
+			granted: 0,
+			grantHistory: [],
+		};
+		state.subagentSpawns = counters;
+	}
+	if (counters.configuredLimit === undefined) {
+		counters.configuredLimit = resolveMaxSubagentSpawnsPerSession(config.maxSubagentSpawnsPerSession) ?? null;
+	}
+	counters.granted ??= 0;
+	counters.grantHistory ??= [];
+	return counters;
+}
+
+export function getSpawnBudgetSnapshot(
+	state: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string | null = state.currentSessionId,
+): SpawnBudgetSnapshot {
+	const counters = sessionState(state, config, sessionId);
+	const configuredLimit = counters.configuredLimit ?? null;
+	const granted = configuredLimit === null ? 0 : counters.granted ?? 0;
+	const limit = configuredLimit === null ? null : configuredLimit + granted;
+	return {
+		used: counters.count,
+		configuredLimit,
+		granted,
+		limit,
+		remaining: limit === null ? null : Math.max(0, limit - counters.count),
+		grantRemaining: configuredLimit === null ? null : Math.max(0, configuredLimit - granted),
+		grantHistory: [...(counters.grantHistory ?? [])],
+	};
+}
+
+export function formatSpawnBudgetSummary(snapshot: SpawnBudgetSnapshot): string {
+	if (snapshot.limit === null) return "unlimited";
+	return `${snapshot.used}/${snapshot.limit} used, ${snapshot.remaining} remaining (configured ${snapshot.configuredLimit}; granted ${snapshot.granted}; grant allowance ${snapshot.grantRemaining})`;
+}
+
+export function formatSpawnBudget(snapshot: SpawnBudgetSnapshot): string {
+	return `Spawn budget: ${formatSpawnBudgetSummary(snapshot)}`;
+}
+
+export function preflightSpawnBudget(
+	state: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string | null,
+	requested: number,
+): { snapshot: SpawnBudgetSnapshot; error?: string } {
+	const snapshot = getSpawnBudgetSnapshot(state, config, sessionId);
+	if (requested <= 0 || snapshot.limit === null || requested <= (snapshot.remaining ?? 0)) return { snapshot };
+	return {
+		snapshot,
+		error: `Subagent spawn limit reached for this session (${snapshot.used}/${snapshot.limit} used, ${requested} requested). ${snapshot.remaining} remaining; the declared run cannot fit, so no children were started. Grant budget explicitly from the root interactive session or start a new session.`,
+	};
+}
+
+export function reserveSpawnBudget(
+	state: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string | null,
+	requested: number,
+): { snapshot: SpawnBudgetSnapshot; error?: string } {
+	const checked = preflightSpawnBudget(state, config, sessionId, requested);
+	if (checked.error || requested <= 0 || checked.snapshot.limit === null) return checked;
+	state.subagentSpawns!.count += requested;
+	return { snapshot: getSpawnBudgetSnapshot(state, config, sessionId) };
+}
+
+export function preflightSpawnBudgetGrant(
+	state: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string,
+	additional: number,
+): { snapshot: SpawnBudgetSnapshot; error?: string } {
+	const snapshot = getSpawnBudgetSnapshot(state, config, sessionId);
+	if (!Number.isInteger(additional) || additional <= 0) {
+		return { snapshot, error: "action='grant-spawn-budget' requires additional to be a positive integer." };
+	}
+	if (snapshot.configuredLimit === null || snapshot.limit === null) {
+		return { snapshot, error: "The current session has no configured spawn cap, so it does not need a budget grant." };
+	}
+	if (additional > (snapshot.grantRemaining ?? 0)) {
+		return {
+			snapshot,
+			error: `Spawn budget grant rejected: ${additional} requested but only ${snapshot.grantRemaining} of the original configured limit remains grantable.`,
+		};
+	}
+	return { snapshot };
+}
+
+export function grantSpawnBudget(
+	state: SubagentState,
+	config: ExtensionConfig,
+	sessionId: string,
+	additional: number,
+	now = Date.now(),
+): { snapshot: SpawnBudgetSnapshot; error?: string } {
+	const checked = preflightSpawnBudgetGrant(state, config, sessionId, additional);
+	if (checked.error) return checked;
+	const before = checked.snapshot;
+	if (before.limit === null) {
+		return { snapshot: before, error: "The current session has no configured spawn cap, so it does not need a budget grant." };
+	}
+	const counters = state.subagentSpawns!;
+	counters.granted = (counters.granted ?? 0) + additional;
+	const limit = before.limit + additional;
+	counters.grantHistory = [
+		...(counters.grantHistory ?? []),
+		{ sessionId, amount: additional, grantedAt: now, previousLimit: before.limit, limit },
+	].slice(-MAX_GRANT_HISTORY);
+	return { snapshot: getSpawnBudgetSnapshot(state, config, sessionId) };
+}

package/src/runs/shared/subagent-control.ts

@@ -74,9 +74,10 @@ export function deriveActivityState(input: {
 	config: ResolvedControlConfig;
 	startedAt: number;
 	lastActivityAt?: number;
+	currentTool?: string;
 	now?: number;
 }): ActivityState | undefined {
-	if (!input.config.enabled) return undefined;
+	if (!input.config.enabled || input.currentTool) return undefined;
 	const now = input.now ?? Date.now();
 	const lastActivity = input.lastActivityAt ?? input.startedAt;
 	const ageMs = Math.max(0, now - lastActivity);
@@ -174,7 +175,8 @@ export function formatControlNoticeMessage(event: ControlEvent, childIntercomTar
 	}
 
 	const nudgeMessage = "What are you blocked on? Reply with the smallest next step or ask for a decision.";
-	const nudgeCommand = `subagent({ action: "resume", id: "${runTarget}", ${event.index !== undefined ? `index: ${event.index}, ` : ""}message: "${nudgeMessage}" })`;
+	const steerCommand = `subagent({ action: "steer", id: "${runTarget}", ${event.index !== undefined ? `index: ${event.index}, ` : ""}message: "${nudgeMessage}" })`;
+	const nestedResumeCommand = `subagent({ action: "resume", id: "${runTarget}", message: "${nudgeMessage}" })`;
 	if (event.type === "active_long_running") {
 		const facts = formatLongRunningFacts(event);
 		return [
@@ -182,8 +184,9 @@ export function formatControlNoticeMessage(event: ControlEvent, childIntercomTar
 			`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
 			`Signal: ${event.message}`,
 			facts ? `Facts: ${facts}` : undefined,
-			"Hint: Inspect status, then nudge if the work seems stuck. Live async nudges interrupt the child before sending the follow-up.",
-			`Nudge: ${nudgeCommand}`,
+			"Hint: Inspect status first. Use steer for a top-level live async child, routed resume for a live nested child, or resume to revive a paused/completed/failed child.",
+			`Top-level live async nudge: ${steerCommand}`,
+			`Routed live nested nudge: ${nestedResumeCommand}`,
 			childIntercomTarget ? `Direct intercom target: ${childIntercomTarget}` : undefined,
 			`Status: subagent({ action: "status", id: "${runTarget}" })`,
 			`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
@@ -195,8 +198,9 @@ export function formatControlNoticeMessage(event: ControlEvent, childIntercomTar
 		`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
 		`Signal: ${event.message}`,
 		event.recentFailureSummary ? `Recent failures: ${event.recentFailureSummary}` : undefined,
-		"Hint: Inspect status first unless the run is clearly blocked. Live async nudges interrupt the child before sending the follow-up.",
-		`Nudge: ${nudgeCommand}`,
+		"Hint: Inspect status first unless the run is clearly blocked. Use steer for a top-level live async child, routed resume for a live nested child, or resume to revive a paused/completed/failed child.",
+		`Top-level live async nudge: ${steerCommand}`,
+		`Routed live nested nudge: ${nestedResumeCommand}`,
 		childIntercomTarget ? `Direct intercom target: ${childIntercomTarget}` : undefined,
 		`Status: subagent({ action: "status", id: "${runTarget}" })`,
 		`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,