@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-subagents/src/runs/shared/async-status-projection.ts

@@ -1,5 +1,6 @@
 import { sanitizeDisplayText, truncateDisplayText } from "../../shared/display-text.ts";
 import { formatModelThinking } from "../../shared/formatters.ts";
+import { childThinkingLevel, type ThinkingLevel } from "../../shared/model-info.ts";
 import type { AsyncJobState, AsyncJobStep, HostStepFreshness, HostStepMonitorKind, HostStepNode, HostStepState, HostStepVerdict, NestedRunSummary, NestedStepSummary, SubagentRunMode, WorkflowGraphSnapshot, WorkflowPreflightLane, WorkflowPreflight } from "../../shared/types.ts";
 import { HOST_STEP_MAX_COUNT, HOST_STEP_MAX_DETAIL_CHARS, HOST_STEP_MAX_LABEL_CHARS, HOST_STEP_MAX_PROVIDER_CHARS, HOST_STEP_MAX_REASON_CHARS, HOST_STEP_MAX_REF_CHARS, HOST_STEP_MAX_ROLE_CHARS, HOST_STEP_MAX_TARGET_CHARS, hostStepReportName, parseHostStepNode, validHostStepNodes } from "./host-step-status.ts";
 import { workflowPreflightLaneForRuntimeKey } from "../../workflows/workflow-preflight.ts";
@@ -106,8 +107,12 @@ export interface AsyncStatusWorkflowRow {
 	kind?: HostStepMonitorKind;
 	context?: AsyncJobStep["context"];
 	modelThinking?: string;
+	/** Thinking level of the child a child row stands for. */
+	thinking?: ThinkingLevel;
 	activity?: string;
 	startedAt?: number;
+	endedAt?: number;
+	durationMs?: number;
 	tokens?: number;
 	window?: number;
 	overflow?: number;
@@ -222,16 +227,25 @@ function appendBoundedChildren(children: AsyncStatusSnapshotNode[], source: read
 	ctx.omitted.children += Math.max(0, source.length - remaining);
 }
 
+function stepIdentity(step: AsyncJobStep | NestedStepSummary, index: number, ctx: ProjectionContext) {
+	return {
+		id: publicText("workflowKey" in step && step.workflowKey ? step.workflowKey : "runId" in step && step.runId ? step.runId : `step:${index}`, `step:${index}`, ctx.caps.maxStringLength),
+		label: publicText("label" in step && step.label ? step.label : step.agent, "step", ctx.caps.maxStringLength),
+	};
+}
+
 function projectStep(step: AsyncJobStep | NestedStepSummary, index: number, depth: number, ctx: ProjectionContext): AsyncStatusSnapshotNode {
 	const state = normalizeState(step.status);
 	const startedAt = publicTime(step.startedAt);
-	const endedAt = publicTime(step.endedAt);
+	const durationMs = "durationMs" in step ? publicTime(step.durationMs) : undefined;
+	const endedAt = publicTime(step.endedAt) ?? (terminalState(state) && startedAt !== undefined && durationMs !== undefined ? publicTime(startedAt + durationMs) : undefined);
 	const updatedAt = endedAt ?? publicTime(step.lastActivityAt) ?? startedAt;
 	const activity = activityFor(step, ctx);
+	const { id, label } = stepIdentity(step, index, ctx);
 	const node: AsyncStatusSnapshotNode = {
-		id: publicText("workflowKey" in step && step.workflowKey ? step.workflowKey : "runId" in step && step.runId ? step.runId : `step:${index}`, `step:${index}`, ctx.caps.maxStringLength),
+		id,
 		kind: "step",
-		label: publicText("label" in step && step.label ? step.label : step.agent, "step", ctx.caps.maxStringLength),
+		label,
 		state,
 		...(startedAt !== undefined ? { startedAt } : {}),
 		...(updatedAt !== undefined ? { updatedAt } : {}),
@@ -249,16 +263,6 @@ function projectStep(step: AsyncJobStep | NestedStepSummary, index: number, dept
 	return node;
 }
 
-function projectWorkflowGraphNode(node: WorkflowGraphSnapshot["nodes"][number], index: number, depth: number, ctx: ProjectionContext): AsyncStatusSnapshotNode {
-	const step: AsyncJobStep = {
-		agent: node.agent ?? node.label,
-		status: workflowGraphStepStatus(node.status),
-		workflowKey: node.id,
-		label: node.label,
-	};
-	return projectStep(step, node.flatIndex ?? index, depth, ctx);
-}
-
 function projectNestedRun(child: NestedRunSummary, index: number, depth: number, ctx: ProjectionContext): AsyncStatusSnapshotNode {
 	const state = normalizeState(child.state);
 	const startedAt = publicTime(child.startedAt);
@@ -322,7 +326,86 @@ function projectHostStep(hostStep: HostStepNode, ctx: ProjectionContext): AsyncS
 	};
 }
 
-function projectRun(job: AsyncJobState, ctx: ProjectionContext): AsyncStatusSnapshotNode {
+type MaterializedChildren = Map<string, AsyncJobState[]>;
+
+function asyncJobOrder(left: AsyncJobState, right: AsyncJobState): number {
+	const leftRank = left.status === "running" ? 0 : left.status === "queued" ? 1 : 2;
+	const rightRank = right.status === "running" ? 0 : right.status === "queued" ? 1 : 2;
+	const leftTime = left.updatedAt ?? left.startedAt ?? 0;
+	const rightTime = right.updatedAt ?? right.startedAt ?? 0;
+	return leftRank - rightRank || rightTime - leftTime || left.asyncId.localeCompare(right.asyncId);
+}
+
+function hasCyclicWorkflowParent(job: AsyncJobState, parents: ReadonlyMap<string, AsyncJobState>): boolean {
+	const seen = new Set([job.asyncId]);
+	let parentId = job.parentWorkflowRunId;
+	while (parentId) {
+		if (seen.has(parentId)) return true;
+		seen.add(parentId);
+		parentId = parents.get(parentId)?.parentWorkflowRunId;
+	}
+	return false;
+}
+
+function groupMaterializedChildren(jobs: readonly AsyncJobState[]) {
+	const parents = new Map(jobs.filter((job) => job.mode === "workflow").map((job) => [job.asyncId, job]));
+	const childrenByParent: MaterializedChildren = new Map();
+	const liveRoots = new Set<AsyncJobState>();
+	const roots: AsyncJobState[] = [];
+	for (const job of jobs) {
+		const parent = job.parentWorkflowRunId ? parents.get(job.parentWorkflowRunId) : undefined;
+		const keepLiveRoot = (job.status === "running" || job.status === "queued") && parent?.status !== "running";
+		if (parent && !hasCyclicWorkflowParent(job, parents)) {
+			const siblings = childrenByParent.get(parent.asyncId) ?? [];
+			siblings.push(job);
+			childrenByParent.set(parent.asyncId, siblings);
+			if (keepLiveRoot) {
+				liveRoots.add(job);
+				roots.push(job);
+			}
+		} else {
+			roots.push(job);
+		}
+	}
+	for (const children of childrenByParent.values()) children.sort(asyncJobOrder);
+	return { roots, childrenByParent, liveRoots };
+}
+
+function assignMaterializedChildren(steps: readonly AsyncJobStep[], children: readonly AsyncJobState[]): Map<AsyncJobStep, AsyncJobState> {
+	const assigned = new Map<AsyncJobStep, AsyncJobState>();
+	const claimed = new Set<AsyncJobState>();
+	for (const step of steps) {
+		if (!step.runId) continue;
+		const child = children.find((candidate) => !claimed.has(candidate) && candidate.asyncId === step.runId);
+		if (child) {
+			assigned.set(step, child);
+			claimed.add(child);
+		}
+	}
+	for (const step of steps) {
+		if (assigned.has(step) || !step.workflowKey) continue;
+		const child = children.find((candidate) => !claimed.has(candidate) && candidate.workflowKey === step.workflowKey);
+		if (child) {
+			assigned.set(step, child);
+			claimed.add(child);
+		}
+	}
+	return assigned;
+}
+
+function projectMaterializedStep(step: AsyncJobStep, index: number, child: AsyncJobState, depth: number, ctx: ProjectionContext, childrenByParent: MaterializedChildren, liveRoots: ReadonlySet<AsyncJobState>): AsyncStatusSnapshotNode {
+	const { id, label } = stepIdentity(step, index, ctx);
+	const selfStep = child.mode === undefined || child.mode === "single" ? child.steps?.[0] : undefined;
+	const live = projectRun(child, ctx, depth, childrenByParent, liveRoots, selfStep !== undefined);
+	const laneActivity = activityFor(step, ctx);
+	const selfActivity = selfStep ? activityFor(selfStep, ctx) : undefined;
+	const activity = laneActivity || selfActivity || live.activity ? { ...laneActivity, ...selfActivity, ...live.activity } : undefined;
+	const node: AsyncStatusSnapshotNode = { ...live, id, kind: "step", label };
+	if (activity) node.activity = activity;
+	return node;
+}
+
+function projectRun(job: AsyncJobState, ctx: ProjectionContext, depth: number, childrenByParent: MaterializedChildren, liveRoots: ReadonlySet<AsyncJobState>, omitSteps = false): AsyncStatusSnapshotNode {
 	const state = normalizeState(job.status);
 	const startedAt = publicTime(job.startedAt);
 	const updatedAt = publicTime(job.updatedAt) ?? startedAt;
@@ -337,16 +420,32 @@ function projectRun(job: AsyncJobState, ctx: ProjectionContext): AsyncStatusSnap
 		...(terminalState(state) && updatedAt !== undefined ? { endedAt: updatedAt } : {}),
 		...(activity ? { activity } : {}),
 	};
-	if (ctx.caps.maxDepth > 0) {
-		const stepChildren = job.steps?.map((step, index) => projectStep(step, step.index ?? index, 1, ctx)) ?? [];
-		const loadedKeys = new Set(job.steps?.flatMap((step) => step.workflowKey ? [step.workflowKey] : []) ?? []);
-		const graphStages = job.mode === "workflow" ? workflowGraphStageNodes(job.workflowGraph) : [];
-		const graphChildren = graphStages
-			.filter((graphNode) => !loadedKeys.has(graphNode.id))
-			.map((graphNode, index) => projectWorkflowGraphNode(graphNode, index, 1, ctx));
-		const nestedChildren = job.nestedChildren?.map((child, index) => projectNestedRun(child, index, 1, ctx)) ?? [];
+	const steps = omitSteps ? [] : job.steps ?? [];
+	const materialized = childrenByParent.get(job.asyncId) ?? [];
+	const nestedSummaries = (job.nestedChildren ?? []).filter((child) => !materialized.some((live) => live.asyncId === child.id));
+	const loadedKeys = new Set(steps.flatMap((step) => step.workflowKey ? [step.workflowKey] : []));
+	const graphStages = job.mode === "workflow" ? workflowGraphStageNodes(job.workflowGraph).filter((graphNode) => !loadedKeys.has(graphNode.id)) : [];
+	const graphSteps = graphStages.map((node, index) => ({
+		step: { agent: node.agent ?? node.label, status: workflowGraphStepStatus(node.status), workflowKey: node.id, label: node.label },
+		index: node.flatIndex ?? index,
+	}));
+	const lanes = [...steps, ...graphSteps.map(({ step }) => step)];
+	const assigned = assignMaterializedChildren(lanes, materialized);
+	const claimed = new Set(assigned.values());
+	if (depth < ctx.caps.maxDepth) {
+		const childDepth = depth + 1;
+		const projectLane = (step: AsyncJobStep, index: number): AsyncStatusSnapshotNode | undefined => {
+			const child = assigned.get(step);
+			if (!child) return projectStep(step, index, childDepth, ctx);
+			if (liveRoots.has(child)) return undefined;
+			return projectMaterializedStep(step, index, child, childDepth, ctx, childrenByParent, liveRoots);
+		};
+		const stepChildren = steps.map((step, index) => projectLane(step, step.index ?? index)).filter((child): child is AsyncStatusSnapshotNode => child !== undefined);
+		const graphChildren = graphSteps.map(({ step, index }) => projectLane(step, index)).filter((child): child is AsyncStatusSnapshotNode => child !== undefined);
+		const nestedChildren = nestedSummaries.map((child, index) => projectNestedRun(child, index, childDepth, ctx));
+		const unclaimedChildren = materialized.filter((child) => !claimed.has(child) && !liveRoots.has(child)).map((child) => projectRun(child, ctx, childDepth, childrenByParent, liveRoots));
 		const hostStepChildren = validHostStepList(job.hostSteps).map((hostStep) => projectHostStep(hostStep, ctx));
-		const ordinaryChildren = [...stepChildren, ...graphChildren, ...nestedChildren];
+		const ordinaryChildren = [...stepChildren, ...graphChildren, ...nestedChildren, ...unclaimedChildren];
 		const retainedHostSteps = hostStepChildren.slice(0, ctx.caps.maxChildrenPerNode);
 		const retainedOrdinaryChildren = ordinaryChildren.slice(0, ctx.caps.maxChildrenPerNode - retainedHostSteps.length);
 		const bounded: AsyncStatusSnapshotNode[] = [];
@@ -354,10 +453,9 @@ function projectRun(job: AsyncJobState, ctx: ProjectionContext): AsyncStatusSnap
 		ctx.omitted.children += ordinaryChildren.length - retainedOrdinaryChildren.length + hostStepChildren.length - retainedHostSteps.length;
 		if (bounded.length) node.children = bounded;
 	} else {
-		const loadedKeys = new Set(job.steps?.flatMap((step) => step.workflowKey ? [step.workflowKey] : []) ?? []);
-		const graphStages = job.mode === "workflow" ? workflowGraphStageNodes(job.workflowGraph) : [];
-		const graphCount = graphStages.filter((graphNode) => !loadedKeys.has(graphNode.id)).length;
-		ctx.omitted.children += (job.steps?.length ?? 0) + graphCount + (job.nestedChildren?.length ?? 0) + validHostStepList(job.hostSteps).length;
+		const rootAssignments = [...assigned.values()].filter((child) => liveRoots.has(child)).length;
+		const unclaimedChildren = materialized.filter((child) => !claimed.has(child) && !liveRoots.has(child)).length;
+		ctx.omitted.children += lanes.length - rootAssignments + nestedSummaries.length + unclaimedChildren + validHostStepList(job.hostSteps).length;
 	}
 	return node;
 }
@@ -528,14 +626,18 @@ export function projectAsyncWorkflowRows(
 
 function projectLoadedWorkflowRow(step: AsyncJobStep, index: number, preflight?: WorkflowPreflightLane): AsyncStatusWorkflowRow {
 	const modelThinking = formatModelThinking(step.model, step.thinking) || undefined;
+	const thinking = childThinkingLevel(step);
 	const activity = workflowStepActivity(step);
 	return {
 		name: workflowStepName(step, index),
 		state: step.status,
 		...(step.context ? { context: step.context } : {}),
 		...(modelThinking ? { modelThinking } : {}),
+		...(thinking ? { thinking } : {}),
 		...(activity ? { activity } : {}),
 		...(step.startedAt !== undefined ? { startedAt: step.startedAt } : {}),
+		...(step.endedAt !== undefined ? { endedAt: step.endedAt } : {}),
+		...(step.durationMs !== undefined ? { durationMs: step.durationMs } : {}),
 		...(step.tokens?.total !== undefined ? { tokens: step.tokens.total } : {}),
 		...(step.tokens?.window !== undefined ? { window: step.tokens.window } : {}),
 		...(preflight ? { preflight } : {}),
@@ -546,11 +648,8 @@ function projectLoadedWorkflowRow(step: AsyncJobStep, index: number, preflight?:
 export function projectAsyncStatusSnapshot(jobs: Iterable<AsyncJobState>, options: AsyncStatusSnapshotOptions = {}): AsyncStatusSnapshot {
 	const caps = resolveCaps(options);
 	const ctx: ProjectionContext = { caps, omitted: { runs: 0, children: 0, byteLimitExceeded: false } };
-	const sorted = [...jobs].sort((left, right) => {
-		const leftUpdated = left.updatedAt ?? left.startedAt ?? 0;
-		const rightUpdated = right.updatedAt ?? right.startedAt ?? 0;
-		return rightUpdated - leftUpdated || left.asyncId.localeCompare(right.asyncId);
-	});
+	const { roots, childrenByParent, liveRoots } = groupMaterializedChildren([...jobs]);
+	const sorted = roots.sort(asyncJobOrder);
 	ctx.omitted.runs += Math.max(0, sorted.length - caps.maxRuns);
 	const snapshot: AsyncStatusSnapshot = {
 		kind: ASYNC_STATUS_SNAPSHOT_KIND,
@@ -558,8 +657,8 @@ export function projectAsyncStatusSnapshot(jobs: Iterable<AsyncJobState>, option
 		generatedAt: options.generatedAt ?? Date.now(),
 		caps,
 		omitted: ctx.omitted,
-		runs: sorted.slice(0, caps.maxRuns).map((job) => projectRun(job, ctx)),
+		runs: sorted.slice(0, caps.maxRuns).map((job) => projectRun(job, ctx, 0, childrenByParent, liveRoots)),
 	};
 	enforceByteLimit(snapshot);
 	return snapshot;
-}
+}

package/dist/extensions/pi-subagents/src/runs/shared/capability-ceiling.ts

@@ -29,6 +29,7 @@ export interface SubagentCapabilityAudit {
 	effectiveMcpTools: string[];
 	agentAllowed: boolean;
 	agentRestrictionSources?: string[];
+	/** Builtin tools declared but unavailable on the host runtime. */
 }
 
 export interface RegisterSubagentCapabilityCeilingOptions {
@@ -62,6 +63,10 @@ function validateText(value: unknown, field: string): string {
 	return value.trim();
 }
 
+export function normalizeCapabilityCeilingAllowedAgents(values: unknown): string[] {
+	return normalizeCeiling({ allowedAgents: values } as SubagentCapabilityCeiling).allowedAgents!;
+}
+
 function normalizeCeiling(ceiling: SubagentCapabilityCeiling): ResolvedSubagentCapabilityCeiling {
 	if (!ceiling || typeof ceiling !== "object" || Array.isArray(ceiling)) throw new Error("Invalid capability ceiling; expected an object.");
 	const hasAllowedTools = Object.hasOwn(ceiling, "allowedTools");
@@ -206,4 +211,4 @@ export function decodeSubagentCapabilityCeiling(value: string | undefined): Reso
 		throw new Error("Invalid inherited capability ceiling version.");
 	}
 	return parseSubagentCapabilityCeiling(parsed, "inherited capability ceiling");
-}
+}

package/dist/extensions/pi-subagents/src/runs/shared/child-commands.ts

@@ -0,0 +1,228 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Type } from "typebox";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ToolDefinition } from "@selesai/code";
+import { createAtomicJsonWriter } from "../../shared/atomic-json.ts";
+import { watchAsyncControlInbox, requestAsyncCommand, type CommandRequest } from "../background/control-channel.ts";
+
+export const CHILD_COMMAND_TOOL = "subagent_command";
+export type CommandOperation = "status" | "yield" | "cancel";
+export interface ChildCommandSnapshot {
+	toolCallId: string;
+	state: "running" | "yielded" | "cancel_requested" | "completed" | "failed" | "cancelled";
+	startedAt: number;
+	endedAt?: number;
+	output: string;
+	fullOutputPath?: string;
+}
+interface CommandJob {
+	snapshot: ChildCommandSnapshot;
+	controller: AbortController;
+	yieldResult: () => void;
+	settled: Promise<void>;
+	yielded?: boolean;
+}
+export interface ChildCommandState {
+	ownerId: string;
+	closed: boolean;
+	commands: ChildCommandSnapshot[];
+}
+const writeAtomicJson = createAtomicJsonWriter({ mode: 0o600 });
+const MAX_OUTPUT_BYTES = 8 * 1024;
+const RECENT_COMMANDS = 20;
+
+function childCommandStatePath(channelDir: string): string {
+	return path.join(channelDir, "commands.json");
+}
+export function readChildCommandState(channelDir: string): ChildCommandState | undefined {
+	try { return JSON.parse(fs.readFileSync(childCommandStatePath(channelDir), "utf8")) as ChildCommandState; }
+	catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; }
+}
+function active(job: CommandJob): boolean { return job.snapshot.endedAt === undefined; }
+function text(result: AgentToolResult<unknown>): string {
+	return Buffer.from(result.content.filter((part) => part.type === "text").map((part) => part.text).join("\n")).subarray(-MAX_OUTPUT_BYTES).toString("utf8");
+}
+
+/** Owns command lifetimes, not shell execution. The supplied Pi tool still executes the command. */
+export function createChildCommandRuntime(channelDir: string) {
+	const ownerId = randomUUID();
+	const jobs = new Map<string, CommandJob>();
+	const usedIds = new Set<string>();
+	let closed = false;
+	let disposeInbox: (() => void) | undefined;
+	const state = (): ChildCommandState => ({ ownerId, closed, commands: [...jobs.values()].map((job) => ({ ...job.snapshot })) });
+	const persist = () => writeAtomicJson(childCommandStatePath(channelDir), {
+		ownerId, closed,
+		commands: [...jobs.values()].map((job) => ({ ...job.snapshot, output: job.yielded ? job.snapshot.output : "" })),
+	});
+	const operate = (operation: CommandOperation, toolCallId?: string): ChildCommandState => {
+		if (operation === "status" && toolCallId === undefined) return state();
+		const job = toolCallId ? jobs.get(toolCallId) : undefined;
+		if (!job) throw new Error(`No retained command '${toolCallId ?? ""}' in this child session.`);
+		if (operation !== "status" && closed) throw new Error("Child command controller is closed.");
+		const before = job.snapshot.state;
+		if (active(job)) {
+			if (operation === "yield" && job.snapshot.state === "running") {
+				job.yielded = true;
+				job.snapshot.state = "yielded";
+				job.yieldResult();
+			} else if (operation === "cancel") {
+				job.snapshot.state = "cancel_requested";
+				job.controller.abort();
+			}
+		}
+		if (job.snapshot.state !== before) persist();
+		return { ownerId, closed, commands: [{ ...job.snapshot }] };
+	};
+	const startInbox = () => {
+		if (disposeInbox) return;
+		disposeInbox = watchAsyncControlInbox(channelDir, {
+			onCommand(request) {
+				const replyPath = commandReplyPath(channelDir, request.id);
+				try {
+					if (request.ownerId !== ownerId) throw new Error("Command request belongs to another child session.");
+					if (Date.now() > request.deadlineAt) throw new Error("Command request expired before delivery.");
+					writeAtomicJson(replyPath, { state: operate(request.operation, request.toolCallId) });
+				} catch (error) {
+					writeAtomicJson(replyPath, { error: error instanceof Error ? error.message : String(error) });
+				}
+			},
+		});
+	};
+	const stop = async () => {
+		closed = true;
+		disposeInbox?.();
+		for (const job of jobs.values()) if (active(job)) {
+			job.snapshot.state = "cancel_requested";
+			job.controller.abort();
+		}
+		await Promise.all([...jobs.values()].map((job) => job.settled));
+		if (jobs.size) persist();
+	};
+	return {
+		state,
+		operate,
+		shutdown: stop,
+		async finish() {
+			const pending = [...jobs.values()].filter(active);
+			if (!pending.length) return;
+			await stop();
+			throw new Error(`Child finished with unfinished commands: ${pending.map((job) => job.snapshot.toolCallId).join(", ")}. Commands were cancelled; query or cancel background commands before finishing.`);
+		},
+		wrap(tool: ToolDefinition): ToolDefinition {
+			return {
+				...tool,
+				parameters: Type.Unsafe({ ...tool.parameters, properties: {
+					...(tool.parameters as { properties?: object }).properties,
+					yieldTimeMs: Type.Optional(Type.Integer({ minimum: 0, maximum: 30_000, description: "Return a managed command handle after this wait; does not terminate the command. Omit to wait for completion." })),
+				} }),
+				description: `${tool.description}\nOptional yieldTimeMs returns a command handle without stopping execution. Use subagent_command to query or cancel it. Finish or cancel every command before completing the task.`,
+				async execute(toolCallId, params, signal, onUpdate, ctx) {
+					if (closed) throw new Error("Child command controller is closed.");
+					if (usedIds.has(toolCallId)) throw new Error(`Command id '${toolCallId}' was already used in this child session.`);
+					usedIds.add(toolCallId);
+					const { yieldTimeMs, ...args } = params as Record<string, unknown>;
+					const controller = new AbortController();
+					const commandSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+					let yieldResult!: () => void;
+					const yielded = new Promise<void>((resolve) => { yieldResult = resolve; });
+					const job: CommandJob = { snapshot: { toolCallId, state: "running", startedAt: Date.now(), output: "" }, controller, yieldResult, settled: Promise.resolve() };
+					// Keep active commands and a bounded recent history; never retain full outputs.
+					const completed = [...jobs].filter(([, candidate]) => !active(candidate));
+					for (const [id] of completed.slice(0, Math.max(0, completed.length - RECENT_COMMANDS + 1))) jobs.delete(id);
+					jobs.set(toolCallId, job);
+					persist();
+					startInbox();
+					let timer: ReturnType<typeof setTimeout> | undefined;
+					if (typeof yieldTimeMs === "number") timer = setTimeout(() => operate("yield", toolCallId), yieldTimeMs);
+					const execution = Promise.resolve().then(() => tool.execute(toolCallId, args, commandSignal, (update) => {
+						job.snapshot.output = text(update);
+						if (job.snapshot.state === "running") onUpdate?.(update);
+					}, ctx)).then((result) => {
+						job.snapshot.output = text(result);
+						job.snapshot.state = "completed";
+						const fullOutputPath = (result.details as { fullOutputPath?: string } | undefined)?.fullOutputPath;
+						if (fullOutputPath) job.snapshot.fullOutputPath = fullOutputPath;
+						return result;
+					}, (error: unknown) => {
+						job.snapshot.state = controller.signal.aborted ? "cancelled" : "failed";
+						job.snapshot.output = String(error).slice(-MAX_OUTPUT_BYTES);
+						throw error;
+					}).finally(() => {
+						if (timer) clearTimeout(timer);
+						job.snapshot.endedAt = Date.now();
+						persist();
+					});
+					job.settled = execution.then(() => {}, () => {});
+					const result = await Promise.race([execution.then((value) => ({ value })), yielded.then(() => undefined)]);
+					if (result) return result.value;
+					return { content: [{ type: "text", text: `Command is still running (toolCallId: ${toolCallId}). This is not a successful exit. Use subagent_command({ action: "status", toolCallId: ${JSON.stringify(toolCallId)} }) to inspect or wait, or action: "cancel" to stop it.\n${job.snapshot.output}` }], details: { command: { ...job.snapshot } } };
+				},
+			};
+		},
+		tool(): ToolDefinition {
+			return {
+				name: CHILD_COMMAND_TOOL, label: "Child command",
+				description: "Inspect or cancel bash commands owned by this child. Cancellation stops only the selected command, not the agent. Check terminal state before finishing.",
+				parameters: Type.Object({ action: Type.String({ enum: ["status", "cancel"] }), toolCallId: Type.Optional(Type.String()), waitMs: Type.Optional(Type.Integer({ minimum: 0, maximum: 30_000 })) }),
+				async execute(_id, params, signal) {
+					const { action, toolCallId, waitMs = 0 } = params as { action: "status" | "cancel"; toolCallId?: string; waitMs?: number };
+					operate(action, toolCallId);
+					const job = toolCallId ? jobs.get(toolCallId) : undefined;
+					if (job && active(job) && waitMs > 0) await waitForCommand(job.settled, waitMs, signal);
+					const snapshot = operate("status", toolCallId);
+					return { content: [{ type: "text", text: JSON.stringify(snapshot) }], details: snapshot };
+				},
+			};
+		},
+	};
+}
+
+async function waitForCommand(settled: Promise<void>, waitMs: number, signal?: AbortSignal): Promise<void> {
+	let timer: ReturnType<typeof setTimeout>;
+	let abort!: () => void;
+	const wait = new Promise<void>((resolve, reject) => {
+		timer = setTimeout(resolve, waitMs);
+		abort = () => reject(new Error("Command wait aborted; command remains managed by the child."));
+		if (signal?.aborted) abort();
+		else signal?.addEventListener("abort", abort, { once: true });
+	});
+	try { await Promise.race([settled, wait]); }
+	finally { clearTimeout(timer!); signal?.removeEventListener("abort", abort); }
+}
+function commandReplyPath(channelDir: string, id: string): string {
+	return path.join(channelDir, "command-replies", `${id}.json`);
+}
+export async function controlChildCommand(channelDir: string, operation: CommandOperation, toolCallId?: string, signal?: AbortSignal): Promise<ChildCommandState> {
+	const current = readChildCommandState(channelDir);
+	if (!current) throw new Error("No command controller is available for this child. Command controls require a local native Pi child with bash.");
+	if (current.closed) {
+		if (operation === "status") {
+			if (toolCallId === undefined) return current;
+			const command = current.commands.find((entry) => entry.toolCallId === toolCallId);
+			if (!command) throw new Error(`No retained command '${toolCallId}' in this child session.`);
+			return { ...current, commands: [command] };
+		}
+		throw new Error("Child command controller is closed.");
+	}
+	if (operation !== "status" && !toolCallId) throw new Error("An exact toolCallId is required; command controls never target the next command.");
+	const id = randomUUID();
+	const deadlineAt = Date.now() + 5_000;
+	const request: CommandRequest = { type: "command", id, ownerId: current.ownerId, operation, ...(toolCallId ? { toolCallId } : {}), deadlineAt };
+	requestAsyncCommand(channelDir, request);
+	const replyPath = commandReplyPath(channelDir, id);
+	try {
+		while (Date.now() < deadlineAt) {
+			if (signal?.aborted) throw new Error("Command control wait aborted; delivery may still be pending.");
+			try {
+				const reply = JSON.parse(fs.readFileSync(replyPath, "utf8")) as { state?: ChildCommandState; error?: string };
+				if (reply.error) throw new Error(reply.error);
+				if (reply.state) return reply.state;
+			} catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+			await new Promise((resolve) => setTimeout(resolve, 20));
+		}
+		throw new Error("Command control acknowledgement timed out. Inspect command status; cancellation is not confirmed.");
+	} finally { fs.rmSync(replyPath, { force: true }); }
+}

package/dist/extensions/pi-subagents/src/runs/shared/child-hooks.ts

@@ -1,7 +1,7 @@
-import type { ExtensionAPI, ExtensionContext } from "@selesai/code";
+import type { ExtensionAPI } from "@selesai/code";
 import { listBackgroundWorkProviders } from "../../api/background-work.ts";
 import { ReadonlyDrainObservation } from "./readonly-drain-observation.ts";
-import registerFanoutChildSubagentExtension from "../../extension/fanout-child.ts";
+import registerFanoutChildSubagentExtension, { createChildSafeState } from "../../extension/fanout-child.ts";
 import registerSubagentFastModeExtension from "./fast-mode-extension.ts";
 import registerSubagentPromptRuntime from "./subagent-prompt-runtime.ts";
 import type { ChildRuntimeConfig } from "./child-runtime-config.ts";
@@ -127,41 +127,41 @@ export function createChildHooks(config: ChildRuntimeConfig): ChildHookExtension
 }
 
 /** Launch-owned bookkeeping, paired with the same private hook certificate (no callback registration API). */
-export function createCapturedChildHooks(config: ChildRuntimeConfig, runner = false) {
+export function createCapturedChildHooks(config: ChildRuntimeConfig) {
 	let diagnostic: ChildToolDiagnostic | undefined;
 	let acknowledgedIds: string[] | undefined;
-	let completionIntentContext: Pick<ExtensionContext, "model" | "modelRegistry"> | undefined;
+	let finalDrainHeld = false;
 	const capture: OwnedCapture = {
 		toolDiagnostic: (value) => { diagnostic = value; },
 		runtimeAcknowledgements: (ids) => { acknowledgedIds = ids; },
 	};
 	Object.assign(config, capture);
-	const hooks = childHooks(config, capture);
-	if (runner) {
-		hooks.push({ name: "pi-subagents:completion-intent", factory: (pi) => pi.on("session_start", (_event, childCtx) => {
-			// Retain only attempt model services, not the live child session.
-			completionIntentContext = { model: childCtx.model, modelRegistry: childCtx.modelRegistry };
-		}) });
-		const proof = promptProofs.get(hooks[0]!.factory);
-		if (proof) proof.factories = hooks.map((hook) => hook.factory);
-	}
+	const hooks = childHooks(config, capture, (held) => { finalDrainHeld = held; });
 	return {
 		hooks,
-		completionIntentContext: () => completionIntentContext,
 		toolDiagnostic: () => diagnostic,
 		runtimeAcknowledgedExtensions: () => acknowledgedIds ? projectRuntimeAcknowledgedExtensions(acknowledgedIds) : undefined,
+		finalDrainHeld: () => finalDrainHeld,
 	};
 }
 
-function childHooks(config: ChildRuntimeConfig, capture?: OwnedCapture): ChildHookExtension[] {
+function childHooks(config: ChildRuntimeConfig, capture?: OwnedCapture, holdFinalDrain?: (held: boolean) => void): ChildHookExtension[] {
 	const snapshot = readonlyConfig(config, capture);
 	const proof: PromptProof | undefined = snapshot === undefined ? undefined : { config, snapshot, capture };
+	const runtime = Object.create(config) as ChildRuntimeConfig;
+	const ownedState = Object.getOwnPropertyDescriptor(config, "runtimeState");
+	if (!ownedState || !("value" in ownedState) || ownedState.value == null) {
+		Object.defineProperty(runtime, "runtimeState", { configurable: true, enumerable: true, writable: true, value: createChildSafeState() });
+	}
+	if (holdFinalDrain) {
+		Object.defineProperty(runtime, "holdFinalDrain", { configurable: true, enumerable: true, writable: true, value: holdFinalDrain });
+	}
 	const hooks: ChildHookExtension[] = [
 		{ name: "pi-subagents:prompt-runtime", factory: function promptRuntime(pi) {
-			if (!proof?.observeNext) return registerSubagentPromptRuntime(pi, config);
+			if (!proof?.observeNext) return registerSubagentPromptRuntime(pi, runtime);
 			proof.observation = proof.observeNext;
 			proof.observeNext = undefined;
-			registerSubagentPromptRuntime(pi, config, proof.observation);
+			registerSubagentPromptRuntime(pi, runtime, proof.observation);
 		} },
 	];
 	if (proof) {
@@ -169,6 +169,6 @@ function childHooks(config: ChildRuntimeConfig, capture?: OwnedCapture): ChildHo
 		promptProofs.set(hooks[0]!.factory, proof);
 	}
 	if (config.fast) hooks.push({ name: "pi-subagents:fast-mode", factory: (pi) => registerSubagentFastModeExtension(pi) });
-	if (config.fanoutChild) hooks.push({ name: "pi-subagents:fanout-child", factory: (pi) => registerFanoutChildSubagentExtension(pi, config) });
+	if (config.fanoutChild) hooks.push({ name: "pi-subagents:fanout-child", factory: (pi) => registerFanoutChildSubagentExtension(pi, runtime) });
 	return hooks;
 }

package/dist/extensions/pi-subagents/src/runs/shared/child-launch-plan.ts

@@ -1,7 +1,7 @@
 import * as path from "node:path";
 import type { AgentConfig } from "../../agents/agents.ts";
 import { resolveChildCwd } from "../../shared/utils.ts";
-import type { OutputMode } from "../../shared/types.ts";
+import type { JsonSchemaObject, OutputMode } from "../../shared/types.ts";
 import { resolveSingleOutputPath } from "./single-output.ts";
 
 export interface ResolvedStepBehavior {
@@ -12,6 +12,7 @@ export interface ResolvedStepBehavior {
 	skills: string[] | false;
 	model?: string;
 	fast?: boolean;
+	outputSchema?: JsonSchemaObject;
 }
 
 export type OutputOverrideInput = string | boolean;
@@ -24,6 +25,7 @@ export interface StepOverrides {
 	skills?: string[] | false;
 	model?: string;
 	fast?: boolean;
+	outputSchema?: JsonSchemaObject | false;
 }
 
 export interface ChildLaunchPlanInput {
@@ -35,6 +37,7 @@ export interface ChildLaunchPlanInput {
 	runtimeCwd: string;
 	stepCwdInput?: string;
 	behaviorCwd?: string;
+	machineCwd?: string;
 	chainSkills?: string[];
 	outputBaseDir?: string;
 	parallelOutputNamespace?: { stepIndex: number; taskIndex?: number };
@@ -58,6 +61,14 @@ export function normalizeOutputOverride(output: unknown): string | false | undef
 	return typeof output === "string" && output.length > 0 ? output : undefined;
 }
 
+export const resolveEffectiveOutputSchema = (agentConfig: AgentConfig, override?: JsonSchemaObject | false): JsonSchemaObject | undefined => override === false ? undefined : override !== undefined ? override : agentConfig.outputSchema;
+
+type OutputSchemaStep = { agent: string; outputSchema?: JsonSchemaObject | false };
+export function projectChainOutputSchemas<S extends OutputSchemaStep, R = S, G = { parallel: R[] | R }>(chain: readonly (S | { parallel: S[] | S })[], agents: AgentConfig[], projectStep?: (step: S, outputSchema: JsonSchemaObject | undefined) => R, projectGroup?: (step: { parallel: S[] | S }, parallel: R[] | R) => G): Array<R | G> {
+	const project = (step: S): R => { const agent = agents.find((candidate) => candidate.name === step.agent); if (!agent && !projectStep) return step as unknown as R; const outputSchema = agent && resolveEffectiveOutputSchema(agent, step.outputSchema); return projectStep ? projectStep(step, outputSchema) : { ...step, outputSchema } as unknown as R; };
+	return chain.map((step) => { if (!("parallel" in step)) return project(step as S); const parallel = Array.isArray(step.parallel) ? step.parallel.map(project) : project(step.parallel as S); return projectGroup ? projectGroup(step, parallel) : { ...step, parallel } as unknown as G; });
+}
+
 export function resolveStepBehavior(
 	agentConfig: AgentConfig,
 	stepOverrides: StepOverrides,
@@ -94,7 +105,8 @@ export function resolveStepBehavior(
 	const outputMode = stepOverrides.outputMode ?? agentConfig.outputMode ?? "inline";
 	const model = stepOverrides.model ?? agentConfig.model;
 	const fast = stepOverrides.fast ?? agentConfig.fast;
-	return { output, outputMode, reads, progress, skills, model, fast };
+	const outputSchema = resolveEffectiveOutputSchema(agentConfig, stepOverrides.outputSchema);
+	return { output, outputMode, reads, progress, skills, model, fast, ...(outputSchema !== undefined ? { outputSchema } : {}) };
 }
 
 export function resolveTaskTextForFileUpdatePolicy(task: string | undefined, originalTask?: string): string | undefined {
@@ -117,7 +129,7 @@ export function suppressProgressForReadOnlyTask(behavior: ResolvedStepBehavior,
 }
 
 export function planChildLaunch(input: ChildLaunchPlanInput): ChildLaunchPlan {
-	const stepCwd = resolveChildCwd(input.runnerCwd, input.stepCwdInput);
+	const stepCwd = input.machineCwd ?? resolveChildCwd(input.runnerCwd, input.stepCwdInput);
 	const instructionCwd = input.behaviorCwd ?? stepCwd;
 	const readExistenceCwd = input.behaviorCwd ? stepCwd : instructionCwd;
 	let behavior = suppressProgressForReadOnlyTask(
@@ -148,4 +160,4 @@ export function planChildLaunch(input: ChildLaunchPlanInput): ChildLaunchPlan {
 	const outputPath = resolveSingleOutputPath(behavior.output, input.runtimeCwd, instructionCwd, input.outputBaseDir);
 
 	return { stepCwd, instructionCwd, readExistenceCwd, behavior, inheritedRelativeParallelOutput, namespaceOutputPath, outputPath, skillNames };
-}
+}