@selesai/code 0.13.39 → 0.14.0

package/dist/extensions/pi-subagents/src/runs/background/wait-tool.ts

@@ -11,14 +11,16 @@ export function registerWaitTool(
 	enabled = resolveWaitToolConfig().enabled,
 	subscriptions?: Pick<WaitSubscriptionManager, "arm">,
 	defaultTimeoutMs?: number,
+	child?: { nestedRootRunId?: string },
+	hasPendingSupervisorRequest?: () => boolean,
 ): void {
 	const description = `Wait for background, provider, or detached work that has no native completion notification, then return.
 
-Ordinary async subagent runs already notify this session natively when they complete or need attention. In an interactive chat, return control instead of calling this merely to wait. Use this tool for provider jobs, remembered detached foreground runs, or other background work without a native notification path. Headless runs auto-drain current-session subagent work at agent_end; use this tool only when the current turn must receive non-notifying background work results.
+${child ? "This child runtime does not install the root session's native completion notifier. Use blocking bg_wait to collect your owned descendants during this turn, then read the returned result references before synthesizing findings. Automatic draining at agent_end keeps owned work alive but does not synthesize its results." : "Ordinary async subagent runs already notify this session natively when they complete or need attention. In an interactive chat, return control instead of calling this merely to wait. Use this tool for provider jobs, remembered detached foreground runs, or other background work without a native notification path. Headless runs auto-drain current-session subagent work at agent_end; use this tool only when the current turn must receive non-notifying background work results."}
 
 • { } — return when the first initially active async run or registered provider item finishes, or when a subagent needs attention.
-• { all: true } — wait for every async run and provider item that was active when the call began.
-• { id: "..." } — wait for one async or remembered detached foreground subagent run (id or prefix).
+• { all: true } — wait for every async run, provider item, and remembered detached foreground descendant that was active when the call began.
+• { id: "..." } — wait for one async or remembered detached foreground subagent run (id or prefix). Named async runs that already finished return their terminal result references.
 • { id: "...", nonBlocking: true } — resolve the prefix once, persist an exact-run wake subscription, and return immediately. Use this for detached work without native completion delivery; the originating interactive session wakes on completion, failure, attention, reconciliation failure, or timeout.
 • { stopOnAttention: false } — for blocking waits only, keep waiting through idle or long-thinking attention; supervisor/contact requests still stop the wait.
 • { timeoutMs: 600000 } — stop waiting after N ms; active work keeps running. Omitted values use waitTool.defaultTimeoutMs, then 30 minutes. Window expiry returns a non-error window_elapsed result with active work identities.
@@ -27,8 +29,10 @@ Non-blocking subscriptions are visible in subagent status and differ from disabl
 
 	const execute: ToolDefinition<typeof SubagentWaitParams, Details>["execute"] = async (_id, params, signal, onUpdate, ctx) => finalizeToolResult(await waitForSubagents(params, signal, {
 		state,
+		nestedRootRunId: child?.nestedRootRunId,
 		events: pi.events,
 		enabled,
+		hasPendingSupervisorRequest,
 		...(defaultTimeoutMs !== undefined ? { defaultTimeoutMs } : {}),
 		onUpdate,
 		...(subscriptions && ctx?.hasUI ? { subscribe: (input) => subscriptions.arm(input) } : {}),
@@ -37,11 +41,6 @@ Non-blocking subscriptions are visible in subagent status and differ from disabl
 		name: "bg_wait",
 		label: "Background Wait",
 		description,
-		...{ discovery: {
-			summary: "Wait for background or detached subagent work to finish",
-			aliases: ["wait for background work", "background wait"],
-			category: "agents",
-		} },
 		parameters: SubagentWaitParams,
 		execute,
 	};
@@ -51,11 +50,6 @@ Non-blocking subscriptions are visible in subagent status and differ from disabl
 		name: "subagent_wait",
 		label: "Subagent Wait (deprecated)",
 		description: "Deprecated compatibility alias for `bg_wait`. Use `bg_wait` for background, provider, or detached work without a native completion notification. It has the same parameters and behavior.",
-		...{ discovery: {
-			summary: "Deprecated compatibility alias for bg_wait",
-			aliases: ["wait for subagent"],
-			category: "agents",
-		} },
 	});
 }
 

package/dist/extensions/pi-subagents/src/runs/background/workflow-terminal-proof.ts

@@ -14,39 +14,57 @@ export type WorkflowChildProcessEvidence =
 	| { state: "observed"; children: ProcessTerminal[] }
 	| { state: "pending" | "unknown"; reason: string };
 
+/** `unresolvedProof` is set only when a terminal child's status matches its roster run id and runner identity, and just its process proof is missing. */
+export type WorkflowChildEvidence =
+	| { state: "resolved"; proof: ProcessTerminal }
+	| { state: "pending" | "unknown"; reason: string; unresolvedProof?: { status: AsyncStatus; proofState: string } };
+
 /**
  * Process evidence for a workflow's async children. Status proofs and capacity
  * release both use this so they cannot disagree about the same workflow.
- * Synchronous children run inside the workflow host and have no process of their own.
  */
 export function readWorkflowChildProcessEvidence(workflowAsyncDir: string, steps: AsyncStatus["steps"]): WorkflowChildProcessEvidence {
+	if (!steps) return { state: "unknown", reason: "workflow child roster is missing" };
 	const children: ProcessTerminal[] = [];
-	for (const step of steps ?? []) {
-		const label = step.workflowKey ?? step.agent;
-		if (typeof step.async !== "boolean") return { state: "unknown", reason: `workflow child ${label} is missing async classification` };
-		if (!step.async) continue;
-		if (!step.runId || path.basename(step.runId) !== step.runId) return { state: "unknown", reason: `async workflow child ${label} is missing run id` };
-		const childDir = path.join(path.dirname(workflowAsyncDir), step.runId);
-		if (!fs.existsSync(childDir)) return { state: "unknown", reason: `async workflow child ${label} directory is missing` };
-		const childStatus = readStatus(childDir);
-		if (!childStatus) return { state: "unknown", reason: `async workflow child ${label} status is missing or unreadable` };
-		if (!isTerminalAsyncState(childStatus.state)) return { state: "pending", reason: `async workflow child ${label} is still ${childStatus.state}` };
-		const recorded = childStatus.processTerminal;
-		if (!recorded?.runnerProcessInstanceId) return { state: "unknown", reason: `async workflow child ${label} has no runner process identity` };
-		// A runner startup failure records `not-started` in status and never writes a process-terminal sidecar.
-		if (recorded.state === "not-started" && recorded.runId === step.runId && typeof childStatus.error === "string" && childStatus.error) {
-			children.push(recorded);
-			continue;
-		}
-		const proof = readProcessTerminal(childDir, { runId: step.runId, runnerProcessInstanceId: recorded.runnerProcessInstanceId });
-		if (proof?.state !== "observed" || proof.runId !== step.runId) {
-			return { state: !proof || proof.state === "pending" ? "pending" : "unknown", reason: `async workflow child ${label} process-terminal proof is ${proof?.state ?? "missing"}` };
-		}
-		children.push(proof);
+	for (const step of steps) {
+		const child = readWorkflowChildEvidence(workflowAsyncDir, step);
+		if (!child) continue;
+		if (child.state !== "resolved") return { state: child.state, reason: child.reason };
+		children.push(child.proof);
 	}
 	return { state: "observed", children };
 }
 
+/** Evidence for one roster entry; undefined for synchronous children, which run inside the workflow host and have no process of their own. */
+export function readWorkflowChildEvidence(workflowAsyncDir: string, step: NonNullable<AsyncStatus["steps"]>[number]): WorkflowChildEvidence | undefined {
+	const label = step.workflowKey ?? step.agent;
+	if (typeof step.async !== "boolean") return { state: "unknown", reason: `workflow child ${label} is missing async classification` };
+	if (!step.async) return undefined;
+	if (!step.runId || path.basename(step.runId) !== step.runId) return { state: "unknown", reason: `async workflow child ${label} is missing run id` };
+	const childDir = path.join(path.dirname(workflowAsyncDir), step.runId);
+	if (!fs.existsSync(childDir)) return { state: "unknown", reason: `async workflow child ${label} directory is missing` };
+	const childStatus = readStatus(childDir);
+	if (!childStatus) return { state: "unknown", reason: `async workflow child ${label} status is missing or unreadable` };
+	if (!isTerminalAsyncState(childStatus.state)) return { state: "pending", reason: `async workflow child ${label} is still ${childStatus.state}` };
+	const recorded = childStatus.processTerminal;
+	if (!recorded?.runnerProcessInstanceId) return { state: "unknown", reason: `async workflow child ${label} has no runner process identity` };
+	// A runner startup failure records `not-started` in status and never writes a process-terminal sidecar.
+	if (recorded.state === "not-started" && recorded.runId === step.runId && typeof childStatus.error === "string" && childStatus.error) {
+		return { state: "resolved", proof: recorded };
+	}
+	const proof = readProcessTerminal(childDir, { runId: step.runId, runnerProcessInstanceId: recorded.runnerProcessInstanceId });
+	if (proof?.state !== "observed" || proof.runId !== step.runId) {
+		const proofState = proof?.state ?? "missing";
+		const bound = childStatus.runId === step.runId && typeof recorded.runnerProcessInstanceId === "string";
+		return {
+			state: !proof || proof.state === "pending" ? "pending" : "unknown",
+			reason: `async workflow child ${label} process-terminal proof is ${proofState}`,
+			...(bound ? { unresolvedProof: { status: childStatus, proofState } } : {}),
+		};
+	}
+	return { state: "resolved", proof };
+}
+
 function unresolved(runId: string, state: "pending" | "unknown", dispatchClosed: boolean, reason: string): WorkflowTerminalProof {
 	return { version: 1, kind: "workflow", runId, state, dispatchClosed, reason };
 }

package/dist/extensions/pi-subagents/src/runs/foreground/async-steering-action.ts

@@ -3,13 +3,18 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import type { AsyncStatus, Details, SubagentState, ToolBudgetConfig } from "../../shared/types.ts";
+import type { AsyncStatus, Details, SteerActionResult, SubagentState, ToolBudgetConfig } from "../../shared/types.ts";
 import { readStatus } from "../../shared/utils.ts";
 import { deliverInterruptRequest, queueRevivalBrief, requestAsyncSteer, type SteerDeliveryMode, type SteerRequest } from "../background/control-channel.ts";
 import { resolveAsyncResumeTarget } from "../background/async-resume.ts";
 import { reconcileAsyncRun } from "../background/stale-run-reconciler.ts";
 import { actionResultFromSteeringStatus, claimSteeringRecovery, createSteeringStatus, recordSteeringRequest, remainingSteeringRecoveryLimits, steeringReceipt, updateSteeringTarget, waitForSteeringAction } from "../background/steering.ts";
 
+function steerTargetsAccepted(result: Pick<SteerActionResult, "targets"> | undefined): boolean {
+	const targets = result?.targets ?? [];
+	return targets.length > 0 && targets.every((target) => target.state === "queued" || target.state === "delivered");
+}
+
 export function canQueueRetainedAsyncFollowUp(status: AsyncStatus, index?: number): boolean {
 	const steps = status.steps ?? [];
 	return status.state === "complete"
@@ -170,9 +175,11 @@ export async function steerAsyncRun(input: {
 	}
 	const finalStatus = readStatus(asyncDir);
 	const finalResult = finalStatus?.steering ? actionResultFromSteeringStatus(finalStatus.steering, status.runId, requestId) : undefined;
-	if (finalResult?.state === "delivered") {
-		return { content: [{ type: "text", text: steeringReceipt(input.message, `Steering delivered for async run ${status.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering: finalResult } };
-	}
+	const acceptedReply = (accepted: SteerActionResult): AgentToolResult<Details> => {
+		const acceptedState = accepted.state === "delivered" ? "delivered" : "queued";
+		return { content: [{ type: "text", text: steeringReceipt(input.message, `Steering ${acceptedState} for async run ${status.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering: accepted } };
+	};
+	if (finalResult && steerTargetsAccepted(finalResult)) return acceptedReply(finalResult);
 	const running = (finalStatus?.steps ?? status.steps ?? []).filter((step) => step.status === "running");
 	const recoveryAllowed = (input.mode ?? "steer") === "steer" && status.mode === "single" && status.isNested !== true && running.length === 1 && Boolean(finalStatus?.steering) && (input.index === undefined || input.index === 0);
 	if (recoveryAllowed && finalResult?.state !== "scheduled" && input.recover) {
@@ -186,17 +193,21 @@ export async function steerAsyncRun(input: {
 		try {
 			const latest = readStatus(asyncDir);
 			const latestResult = latest?.steering ? actionResultFromSteeringStatus(latest.steering, status.runId, requestId) : undefined;
-			if (latestResult?.state === "delivered") return { content: [{ type: "text", text: steeringReceipt(input.message, `Steering delivered for async run ${status.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering: latestResult } };
+			if (latestResult && steerTargetsAccepted(latestResult)) return acceptedReply(latestResult);
 			const committedAt = Date.now();
 			input.onBeforeRecoveryClaim?.(requestId, committedAt);
 			const { claimPath, markerPath } = claimSteeringRecovery(asyncDir, { requestId, sourceRunId: status.runId, committedAt });
 			input.onRecoveryCommitted?.(requestId, committedAt);
 			const preCommitStatus = readStatus(asyncDir);
 			const preCommitResult = preCommitStatus?.steering ? actionResultFromSteeringStatus(preCommitStatus.steering, status.runId, requestId) : undefined;
-			if (preCommitResult?.state === "delivered" && preCommitResult.targets.every((target) => target.deliveredAt !== undefined && target.deliveredAt <= committedAt)) {
+			if (
+				preCommitResult
+				&& preCommitResult.targets.length > 0
+				&& preCommitResult.targets.every((target) => target.state === "queued" || (target.deliveredAt !== undefined && target.deliveredAt <= committedAt))
+			) {
 				fs.rmSync(markerPath, { force: true });
 				fs.rmSync(claimPath, { force: true });
-				return { content: [{ type: "text", text: steeringReceipt(input.message, `Steering delivered for async run ${status.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering: preCommitResult } };
+				return acceptedReply(preCommitResult);
 			}
 			try {
 				deliverInterruptRequest({ asyncDir, source: "steering-recovery" });
@@ -262,4 +273,4 @@ export async function steerAsyncRun(input: {
 		...(isError ? { isError: true } : {}),
 		details: { mode: "management", results: [], steering: result },
 	};
-}
+}

package/dist/extensions/pi-subagents/src/runs/foreground/async-stop-action.ts

@@ -1,9 +1,15 @@
+import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { Details, SubagentState } from "../../shared/types.ts";
-import { deliverStopRequest } from "../background/control-channel.ts";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { DIRS, type AsyncStatus, type Details, type SubagentState } from "../../shared/types.ts";
+import { updateActiveRunIndex } from "../background/active-run-index.ts";
+import { deliverStopRequest, stopInboxClosedPath } from "../background/control-channel.ts";
+import { readProcessTerminal } from "../background/process-terminal.ts";
+import { resultFilePath, resultPayloadFileForSessionRun, resultPayloadPathForSessionRun, writeAsyncResultFile } from "../background/result-files.ts";
 import { reconcileAsyncRun } from "../background/stale-run-reconciler.ts";
-import { isStoppableAsyncStatusStep, resolveAsyncStatusChild, type ResolvedAsyncStatusChild } from "../shared/child-identity.ts";
+import { readStatus } from "../../shared/utils.ts";
+import { isStoppableAsyncStatusStep, resolveAsyncStatusChild, stopStoppableAsyncStatusChildren, type ResolvedAsyncStatusChild } from "../shared/child-identity.ts";
 
 function getAsyncStopTarget(
 	state: SubagentState,
@@ -21,6 +27,99 @@ function getAsyncStopTarget(
 	return direct ? { asyncId: direct.asyncId, asyncDir: direct.asyncDir } : undefined;
 }
 
+const STOP_MESSAGE = "Subagent stopped by user.";
+
+function sealPausedRun(asyncDir: string, status: AsyncStatus): string | undefined {
+	const runnerProcessInstanceId = status.processTerminal?.runnerProcessInstanceId;
+	if (!runnerProcessInstanceId) return "runner process identity is missing";
+	const proof = readProcessTerminal(asyncDir, { runId: status.runId, runnerProcessInstanceId });
+	if (proof?.state !== "observed" || proof.runId !== status.runId || proof.runnerProcessInstanceId !== runnerProcessInstanceId) {
+		return `process-terminal proof is ${proof?.state === "unknown" ? `unknown (${proof.reason})` : proof?.state ?? "missing"}`;
+	}
+	if (!status.sessionId) return "session identity is missing";
+	// The validated lookup skips unreadable or foreign files; those must be refused below, not replaced.
+	const existingResultPath = resultPayloadPathForSessionRun(DIRS.results, status.sessionId, status.runId)
+		?? resultPayloadFileForSessionRun(DIRS.results, status.sessionId, status.runId);
+	let existingResult: Record<string, unknown>;
+	if (!existingResultPath) {
+		// Delivery deletes the paused result, and an interrupted parent may never have received one; seal from status.
+		existingResult = {
+			id: status.runId,
+			mode: status.mode,
+			sessionId: status.sessionId,
+			asyncDir,
+			...(status.completionOwnerId ? { completionOwnerId: status.completionOwnerId } : {}),
+			...(status.toolCallId ? { toolCallId: status.toolCallId } : {}),
+			results: (status.steps ?? []).map((step) => ({
+				agent: step.agent,
+				success: step.status === "complete" || step.status === "completed",
+				...(step.error ? { error: step.error } : {}),
+				...(step.exitCode !== undefined ? { exitCode: step.exitCode } : {}),
+			})),
+		};
+	} else {
+		try {
+			const parsed: unknown = JSON.parse(fs.readFileSync(existingResultPath, "utf-8"));
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("result is not an object");
+			existingResult = parsed as Record<string, unknown>;
+		} catch (error) {
+			return `paused result is unavailable: ${error instanceof Error ? error.message : String(error)}`;
+		}
+	}
+	const resultRunId = typeof existingResult.runId === "string" ? existingResult.runId : existingResult.id;
+	if (resultRunId !== status.runId || existingResult.sessionId !== status.sessionId) {
+		return "paused result identity does not match the run";
+	}
+
+	const now = Date.now();
+	const steps = (status.steps ?? []).map((step) => {
+		if (step.status !== "pending" && step.status !== "running" && step.status !== "paused") return step;
+		const { activityState: _activityState, ...rest } = step;
+		return {
+			...rest,
+			status: "stopped" as const,
+			error: STOP_MESSAGE,
+			exitCode: 1,
+			stopped: true,
+			endedAt: now,
+			durationMs: step.startedAt ? now - step.startedAt : 0,
+			lastActivityAt: now,
+		};
+	});
+	const results = Array.isArray(existingResult.results)
+		? existingResult.results.map((entry, index) => {
+			const stepState = status.steps?.[index]?.status;
+			if ((stepState !== "pending" && stepState !== "running" && stepState !== "paused") || !entry || typeof entry !== "object" || Array.isArray(entry)) return entry;
+			const { interrupted: _interrupted, ...result } = entry as Record<string, unknown>;
+			return { ...result, output: STOP_MESSAGE, error: STOP_MESSAGE, success: false, exitCode: 1, stopped: true };
+		})
+		: existingResult.results;
+	const stoppedResult = {
+		...existingResult,
+		success: false,
+		state: "stopped",
+		summary: STOP_MESSAGE,
+		error: STOP_MESSAGE,
+		stopped: true,
+		exitCode: 1,
+		timestamp: now,
+		...(Array.isArray(existingResult.results) ? { results } : {}),
+	};
+	const stoppedStatus: AsyncStatus = {
+		...status,
+		state: "stopped",
+		stopped: true,
+		error: STOP_MESSAGE,
+		endedAt: now,
+		lastUpdate: now,
+		steps,
+	};
+	delete stoppedStatus.activityState;
+	writeAsyncResultFile(resultFilePath(DIRS.results, status.runId), stoppedResult);
+	writeAtomicJson(path.join(asyncDir, "status.json"), stoppedStatus);
+	updateActiveRunIndex(asyncDir, "stopped", status.toolCallId, { retryCapacityErrors: true, terminalIndexBeforeRelease: true });
+}
+
 export function stopAsyncRun(
 	state: SubagentState,
 	runId: string | undefined,
@@ -29,6 +128,18 @@ export function stopAsyncRun(
 	childId?: string,
 ): AgentToolResult<Details> | null {
 	const target = getAsyncStopTarget(state, runId, location);
+	// An async workflow runs in this process: it has no runner to read a stop request, so stop it through its controller.
+	const workflowRunId = target?.asyncId ?? runId;
+	const workflowController = childId === undefined && workflowRunId ? state.workflowControllers?.get(workflowRunId) : undefined;
+	const workflowAsyncDir = workflowController && workflowRunId ? target?.asyncDir ?? state.asyncJobs.get(workflowRunId)?.asyncDir : undefined;
+	const workflowStatus = workflowAsyncDir ? readStatus(workflowAsyncDir) : undefined;
+	// Controllers outlive a session switch; a workflow owned by another session falls through to the ownership check below.
+	const foreignWorkflow = Boolean(state.currentSessionId && workflowStatus && workflowStatus.sessionId !== state.currentSessionId);
+	if (workflowController && workflowRunId && !foreignWorkflow) {
+		if (workflowStatus) stopStoppableAsyncStatusChildren(workflowStatus, state.workflowChildStops?.get(workflowRunId), "Workflow stopped.");
+		workflowController.abort(new Error("Workflow stopped."));
+		return { content: [{ type: "text", text: `Stop requested for async workflow ${workflowRunId}.` }], details: { mode: "management", results: [] } };
+	}
 	if (!target) return null;
 	const status = reconcileAsyncRun(target.asyncDir, { kill }).status;
 	if (state.currentSessionId && status?.sessionId !== state.currentSessionId) {
@@ -38,7 +149,8 @@ export function stopAsyncRun(
 			details: { mode: "management", results: [] },
 		};
 	}
-	if (!status || (status.state !== "running" && status.state !== "queued")) {
+	const pausedWholeRun = status?.state === "paused" && childId === undefined;
+	if (!status || (status.state !== "running" && status.state !== "queued" && !pausedWholeRun)) {
 		return {
 			content: [{ type: "text", text: `No running or queued async run was found for '${runId ?? "current"}'.` }],
 			isError: true,
@@ -65,14 +177,25 @@ export function stopAsyncRun(
 		}
 	}
 	try {
-		deliverStopRequest({ asyncDir: target.asyncDir, pid: typeof status.pid === "number" ? status.pid : undefined, kill, source: "stop-action", targetIndex: child?.index, childId: child?.id ?? childId });
+		// A paused run whose runner closed its inbox can only be sealed from exact exit proof below.
+		if (!(pausedWholeRun && fs.existsSync(stopInboxClosedPath(target.asyncDir)))) deliverStopRequest({ asyncDir: target.asyncDir, pid: typeof status.pid === "number" ? status.pid : undefined, kill, source: "stop-action", targetIndex: child?.index, childId: child?.id ?? childId });
+		if (pausedWholeRun) {
+			const failure = sealPausedRun(target.asyncDir, status);
+			if (failure) {
+				return {
+					content: [{ type: "text", text: `Stop request persisted for paused async run ${target.asyncId}, but terminal proof is not ready (${failure}). Retry stop after runner shutdown is observed.` }],
+					isError: true,
+					details: { mode: "management", results: [] },
+				};
+			}
+		}
 		const tracked = state.asyncJobs.get(target.asyncId);
 		if (tracked) {
 			tracked.activityState = undefined;
 			tracked.updatedAt = Date.now();
 		}
 		return {
-			content: [{ type: "text", text: child ? `Stop requested for child ${child.id} in async run ${target.asyncId}.` : `Stop requested for async run ${target.asyncId}.` }],
+			content: [{ type: "text", text: pausedWholeRun ? `Stopped paused async run ${target.asyncId}.` : child ? `Stop requested for child ${child.id} in async run ${target.asyncId}.` : `Stop requested for async run ${target.asyncId}.` }],
 			details: { mode: "management", results: [] },
 		};
 	} catch (error) {
@@ -83,4 +206,4 @@ export function stopAsyncRun(
 			details: { mode: "management", results: [] },
 		};
 	}
-}
+}

package/dist/extensions/pi-subagents/src/runs/foreground/command-action.ts

@@ -0,0 +1,41 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Details, SubagentState } from "../../shared/types.ts";
+import { readStatus } from "../../shared/utils.ts";
+import type { ResolvedSubagentRunId } from "../background/run-id-resolver.ts";
+import { supervisorChannelDir } from "../shared/child-tool-plan.ts";
+import { controlChildCommand, type CommandOperation } from "../shared/child-commands.ts";
+
+function commandChildren(state: SubagentState, target: ResolvedSubagentRunId): Array<{ index: number; agent: string }> {
+	if (!state.currentSessionId) throw new Error("Command controls require an owning parent session.");
+	if (target.kind === "nested") throw new Error("Command controls support direct local Pi children only.");
+	if (target.kind === "foreground") {
+		const live = state.foregroundControls.get(target.id);
+		const retained = state.foregroundRuns?.get(target.id);
+		if ((live?.sessionId ?? retained?.sessionId) !== state.currentSessionId) throw new Error("Run is not owned by this session.");
+		if (live?.activeChildren?.size) return [...live.activeChildren.values()].map(({ index, agent }) => ({ index, agent }));
+		if (live?.currentAgent) return [{ index: live.currentIndex ?? 0, agent: live.currentAgent }];
+		return retained?.children.map(({ index, agent }) => ({ index, agent })) ?? [];
+	}
+	const status = target.location.asyncDir ? readStatus(target.location.asyncDir) : undefined;
+	if (status?.sessionId !== state.currentSessionId) throw new Error("Run is not owned by this session.");
+	return status.steps?.map((step, index) => ({ index, agent: step.agent })) ?? [];
+}
+
+export async function commandAction(input: {
+	state: SubagentState;
+	target: ResolvedSubagentRunId;
+	operation: CommandOperation;
+	index?: number;
+	toolCallId?: string;
+	signal?: AbortSignal;
+}): Promise<AgentToolResult<Details>> {
+	const children = commandChildren(input.state, input.target);
+	if (input.index === undefined && children.length !== 1) throw new Error("Command controls require an explicit child index for multi-child runs.");
+	const child = input.index === undefined ? children[0] : children.find(({ index }) => index === input.index);
+	if (!child) throw new Error(`No child index ${input.index ?? 0} in this run.`);
+	const result = await controlChildCommand(supervisorChannelDir(input.target.id, child.agent, child.index), input.operation, input.toolCallId, input.signal);
+	return {
+		content: [{ type: "text", text: JSON.stringify({ runId: input.target.id, index: child.index, commands: result.commands, closed: result.closed }) }],
+		details: { mode: "management", results: [], commands: result.commands },
+	};
+}