@selesai/code 0.5.28 → 0.6.1

package/dist/extensions/pi-subagents/src/extension/rpc.ts

@@ -6,8 +6,11 @@ import { resolveAsyncRunLocation } from "../runs/background/async-resume.ts";
 import { deliverStopRequest } from "../runs/background/control-channel.ts";
 import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.ts";
 import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
+import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import {
+	type AsyncJobStep,
 	type Details,
+	type SubagentState,
 	ASYNC_DIR,
 	RESULTS_DIR,
 	SUBAGENT_ASYNC_COMPLETE_EVENT,
@@ -23,7 +26,7 @@ export const SUBAGENT_RPC_REQUEST_EVENT = "subagents:rpc:v1:request";
 export const SUBAGENT_RPC_READY_EVENT = "subagents:rpc:v1:ready";
 export const SUBAGENT_RPC_REPLY_EVENT_PREFIX = "subagents:rpc:v1:reply:";
 
-export const SUBAGENT_RPC_METHODS = ["ping", "status", "spawn", "steer", "interrupt", "stop"] as const;
+export const SUBAGENT_RPC_METHODS = ["ping", "status", "spawn", "steer", "interrupt", "stop", "resume"] as const;
 export type SubagentRpcMethod = typeof SUBAGENT_RPC_METHODS[number];
 
 export interface SubagentRpcRequestEnvelope {
@@ -69,6 +72,200 @@ interface EventBus {
 	emit(event: string, data: unknown): void;
 }
 
+export interface SubagentRpcFleetEntry {
+	/** Opaque key for client-side reconciliation; never a run or async identifier. */
+	key: string;
+	/** Resolved child agent/role name. */
+	agent: string;
+	role?: string;
+	model?: string;
+	effort?: string;
+	startedAt: number;
+	tokens: { input: number; output: number; total: number };
+	goal?: string;
+}
+
+export interface SubagentRpcFleetStatus {
+	version: 1;
+	entries: SubagentRpcFleetEntry[];
+	/** Total active children before the bounded entries window. */
+	totalActive: number;
+	omitted: number;
+}
+
+const MAX_FLEET_ENTRIES = 16;
+const MAX_FLEET_CANDIDATES = 256;
+const MAX_AGENT_LENGTH = 96;
+const MAX_GOAL_LENGTH = 512;
+const MAX_METADATA_LENGTH = 128;
+
+function displayText(value: unknown, maxLength: number): string | undefined {
+	if (typeof value !== "string") return undefined;
+	// Strip complete CSI/OSC/DCS/APC/PM strings and C1 controls before collapsing
+	// whitespace; never leave CSI parameters behind after removing ESC.
+	const normalized = value.slice(0, 4_096)
+		.replace(/\x1b\[[0-?]*[ -/]*[@-~]|\x9b[0-?]*[ -/]*[@-~]|\x1b][\s\S]*?(?:\x07|\x1b\\)|\x1b[PX^_][\s\S]*?\x1b\\|[\u0000-\u001f\u007f-\u009f]/g, " ")
+		.replace(/\s+/g, " ").trim();
+	return normalized ? normalized.slice(0, maxLength) : undefined;
+}
+
+function publicTokens(value: unknown): { input: number; output: number; total: number } {
+	const record = isRecord(value) ? value : {};
+	const count = (field: "input" | "output" | "total") => {
+		const raw = record[field];
+		return typeof raw === "number" && Number.isFinite(raw) && raw >= 0
+			? Math.min(Number.MAX_SAFE_INTEGER, Math.floor(raw))
+			: 0;
+	};
+	const input = count("input");
+	const output = count("output");
+	const sum = Math.min(Number.MAX_SAFE_INTEGER, input + output);
+	return { input, output, total: Math.max(sum, count("total")) };
+}
+
+function activeState(value: unknown): boolean {
+	return value === "running" || value === "queued" || value === "pending";
+}
+
+interface FleetKeyState {
+	sessionId: string | null;
+	next: number;
+	keys: Map<string, string>;
+}
+
+interface FleetCandidate {
+	internalKey: string;
+	agent: unknown;
+	role?: unknown;
+	model?: unknown;
+	effort?: unknown;
+	startedAt: unknown;
+	tokens?: unknown;
+	goal?: unknown;
+}
+
+function buildFleetStatus(
+	state: SubagentState | undefined,
+	keyState: FleetKeyState,
+	sessionId: string | null | undefined,
+): SubagentRpcFleetStatus {
+	const authoritativeSessionId = sessionId ?? null;
+	if (keyState.sessionId !== authoritativeSessionId) {
+		keyState.sessionId = authoritativeSessionId;
+		keyState.next = 0;
+		keyState.keys.clear();
+	}
+	if (!state || !authoritativeSessionId || state.currentSessionId !== authoritativeSessionId) {
+		keyState.keys.clear();
+		return { version: 1, entries: [], totalActive: 0, omitted: 0 };
+	}
+
+	let totalActive = 0;
+	const candidates: FleetCandidate[] = [];
+	const addCandidate = (candidate: FleetCandidate) => {
+		totalActive += 1;
+		if (candidates.length < MAX_FLEET_CANDIDATES) candidates.push(candidate);
+	};
+	for (const control of state.foregroundControls.values()) {
+		if (control.sessionId !== authoritativeSessionId) continue;
+		if (control.activeChildren?.size) {
+			for (const child of control.activeChildren.values()) addCandidate({
+				internalKey: `foreground:${control.runId}:${child.index}`,
+				agent: child.agent,
+				model: child.model,
+				effort: child.thinking,
+				startedAt: child.startedAt,
+				tokens: { input: child.inputTokens ?? 0, output: child.outputTokens ?? 0, total: child.tokens ?? 0 },
+				goal: child.description ?? control.description,
+			});
+		} else {
+			addCandidate({
+				internalKey: `foreground:${control.runId}:${control.currentIndex ?? 0}`,
+				agent: control.currentAgent ?? control.mode,
+				model: control.model,
+				effort: control.thinking,
+				startedAt: control.startedAt,
+				tokens: { input: control.inputTokens ?? 0, output: control.outputTokens ?? 0, total: control.tokens ?? 0 },
+				goal: control.description,
+			});
+		}
+	}
+	for (const job of state.asyncJobs.values()) {
+		if (job.sessionId !== authoritativeSessionId || !activeState(job.status)) continue;
+		const startedAt = job.startedAt ?? job.updatedAt;
+		const steps: AsyncJobStep[] | undefined = job.steps?.length
+			? job.steps
+			: job.agents?.map((agent, index) => ({
+				agent,
+				index,
+				status: job.status === "queued" ? "pending" : "running",
+			}));
+		if (!steps?.length) {
+			addCandidate({
+				internalKey: `async:${job.asyncId}`,
+				agent: job.mode ?? "subagent",
+				startedAt,
+				tokens: job.totalTokens,
+				goal: job.description,
+			});
+			continue;
+		}
+		for (const [offset, step] of steps.entries()) {
+			if (!activeState(step.status)) continue;
+			const index = step.index ?? offset;
+			if (step.status === "pending" && job.mode === "chain" && !job.activeParallelGroup && index !== (job.currentStep ?? 0)) continue;
+			addCandidate({
+				internalKey: `async:${job.asyncId}:${index}`,
+				agent: step.agent,
+				role: step.label,
+				model: step.model,
+				effort: step.thinking,
+				startedAt: step.startedAt ?? startedAt,
+				tokens: step.tokens ?? (steps.length === 1 ? job.totalTokens : undefined),
+				goal: job.description,
+			});
+		}
+	}
+
+	candidates.sort((left, right) => {
+		const leftStarted = typeof left.startedAt === "number" ? left.startedAt : Number.MAX_SAFE_INTEGER;
+		const rightStarted = typeof right.startedAt === "number" ? right.startedAt : Number.MAX_SAFE_INTEGER;
+		return leftStarted - rightStarted || left.internalKey.localeCompare(right.internalKey);
+	});
+	const activeKeys = new Set(candidates.map((candidate) => candidate.internalKey));
+	const entries: SubagentRpcFleetEntry[] = [];
+	for (const candidate of candidates) {
+		if (entries.length >= MAX_FLEET_ENTRIES) break;
+		const agent = displayText(candidate.agent, MAX_AGENT_LENGTH);
+		const startedAt = candidate.startedAt;
+		if (!agent || typeof startedAt !== "number" || !Number.isSafeInteger(startedAt) || startedAt < 0) continue;
+		let key = keyState.keys.get(candidate.internalKey);
+		if (!key) {
+			key = `fleet-${++keyState.next}`;
+			keyState.keys.set(candidate.internalKey, key);
+		}
+		const role = displayText(candidate.role, MAX_AGENT_LENGTH);
+		const model = displayText(candidate.model, MAX_METADATA_LENGTH);
+		const effort = displayText(candidate.effort, MAX_METADATA_LENGTH);
+		const goal = displayText(candidate.goal, MAX_GOAL_LENGTH);
+		entries.push({
+			key,
+			agent,
+			...(role ? { role } : {}),
+			...(model ? { model } : {}),
+			...(effort ? { effort } : {}),
+			startedAt,
+			tokens: publicTokens(candidate.tokens),
+			...(goal ? { goal } : {}),
+		});
+	}
+	for (const internalKey of keyState.keys.keys()) {
+		if (!activeKeys.has(internalKey)) keyState.keys.delete(internalKey);
+	}
+	const omitted = Math.max(0, totalActive - entries.length);
+	return { version: 1, entries, totalActive, omitted };
+}
+
 interface RegisterSubagentRpcBridgeOptions {
 	events: EventBus;
 	getContext: () => ExtensionContext | null;
@@ -83,6 +280,8 @@ interface RegisterSubagentRpcBridgeOptions {
 	resultsDir?: string;
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	now?: () => number;
+	/** Native live state, projected into the optional public fleet-status capability. */
+	state?: SubagentState;
 }
 
 class SubagentRpcError extends Error {
@@ -140,7 +339,9 @@ function textFromToolResult(result: AgentToolResult<Details>): string {
 		.join("\n");
 }
 
-function dataFromToolResult(result: AgentToolResult<Details>): { text: string; details?: Details; isError?: boolean } {
+type ToolResultWithError = AgentToolResult<Details> & { isError?: boolean };
+
+function dataFromToolResult(result: ToolResultWithError): { text: string; details?: Details; isError?: boolean } {
 	return {
 		text: textFromToolResult(result),
 		...(result.details ? { details: result.details } : {}),
@@ -148,7 +349,7 @@ function dataFromToolResult(result: AgentToolResult<Details>): { text: string; d
 	};
 }
 
-function failIfToolError(result: AgentToolResult<Details>): void {
+function failIfToolError(result: ToolResultWithError): void {
 	if (!result.isError) return;
 	throw new SubagentRpcError("execution_failed", textFromToolResult(result) || "Subagent RPC execution failed.");
 }
@@ -178,11 +379,15 @@ function pingData(ctx: ExtensionContext | null) {
 		methods: [...SUBAGENT_RPC_METHODS],
 		capabilities: {
 			status: true,
+			fleetStatus: { version: 1 },
 			asyncSpawn: true,
 			steer: true,
 			nonRecoveringSteer: true,
 			interrupt: true,
 			stop: true,
+			resume: true,
+			launchResolvedExtensions: { version: 1, source: "launch-resolved" },
+			runtimeAcknowledgedExtensions: { version: 1, source: "child-runtime", event: "subagent:acknowledge-extension" },
 			processTerminalProof: { version: 1, lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION },
 		},
 		events: {
@@ -238,6 +443,24 @@ function steerParams(params: unknown): SubagentParamsLike {
 	};
 }
 
+function resumeParams(params: unknown): SubagentParamsLike {
+	const input = assertRecordParams(params, "resume");
+	if (typeof input.message !== "string" || !input.message.trim())
+		throw new SubagentRpcError("invalid_params", "RPC resume requires a non-empty message.");
+	const target = normalizeTargetParams(input, "resume");
+	if (!target.id && !target.runId && !target.dir) throw new SubagentRpcError("invalid_params", "RPC resume requires id, runId, or dir.");
+	if (input.output !== undefined && (typeof input.output !== "string" || !input.output.trim()))
+		throw new SubagentRpcError("invalid_params", "RPC resume output must be a non-empty path.");
+	if (input.outputMode !== undefined && input.outputMode !== "file-only")
+		throw new SubagentRpcError("invalid_params", "RPC resume supports only file-only output mode.");
+	return {
+		action: "resume",
+		...target,
+		message: input.message.trim(),
+		...(typeof input.output === "string" ? { output: input.output.trim(), outputMode: "file-only" } : {}),
+	};
+}
+
 function stopAsyncRun(
 	params: unknown,
 	options: RegisterSubagentRpcBridgeOptions,
@@ -257,7 +480,7 @@ function stopAsyncRun(
 		throw new SubagentRpcError("not_found", "Async run not found or already completed; stop requires a live async run directory.");
 	}
 
-	const currentSessionId = ctx.sessionManager.getSessionId();
+	const currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
 	const initialStatus = readStatus(location.asyncDir);
 	const initialRunId = initialStatus?.runId ?? location.resolvedId ?? path.basename(location.asyncDir);
 	if (!initialStatus) throw new SubagentRpcError("not_found", `Status file not found for async run '${initialRunId}'.`);
@@ -304,6 +527,7 @@ function stopAsyncRun(
 async function handleRequest(
 	request: SubagentRpcRequestEnvelope,
 	options: RegisterSubagentRpcBridgeOptions,
+	fleetKeys: FleetKeyState,
 ): Promise<unknown> {
 	const ctx = options.getContext();
 	if (request.method === "ping") return pingData(ctx);
@@ -313,7 +537,21 @@ async function handleRequest(
 		return executeChecked(options, ctx, request.requestId, request.method, spawnParams(request.params));
 	}
 	if (request.method === "status") {
-		return executeChecked(options, ctx, request.requestId, request.method, { action: "status", ...normalizeTargetParams(request.params, "status") });
+		const status = await executeChecked(
+			options,
+			ctx,
+			request.requestId,
+			request.method,
+			{ action: "status", ...normalizeTargetParams(request.params, "status") },
+		);
+		return {
+			...status,
+			fleet: buildFleetStatus(
+				options.state,
+				fleetKeys,
+				resolveCurrentSessionId(ctx.sessionManager),
+			),
+		};
 	}
 	if (request.method === "steer") {
 		return executeChecked(options, ctx, request.requestId, request.method, steerParams(request.params));
@@ -324,6 +562,9 @@ async function handleRequest(
 	if (request.method === "stop") {
 		return stopAsyncRun(request.params, options, ctx);
 	}
+	if (request.method === "resume") {
+		return executeChecked(options, ctx, request.requestId, request.method, resumeParams(request.params));
+	}
 	throw new SubagentRpcError("unsupported_method", `Unsupported subagent RPC method: ${String(request.method)}`);
 }
 
@@ -377,11 +618,12 @@ export function registerSubagentRpcBridge(options: RegisterSubagentRpcBridgeOpti
 	emitReady: (ctx?: ExtensionContext | null) => void;
 	dispose: () => void;
 } {
+	const fleetKeys: FleetKeyState = { sessionId: null, next: 0, keys: new Map() };
 	const unsubscribe = options.events.on(SUBAGENT_RPC_REQUEST_EVENT, async (raw) => {
 		let request: SubagentRpcRequestEnvelope | undefined;
 		try {
 			request = parseRequest(raw);
-			const data = await handleRequest(request, options);
+			const data = await handleRequest(request, options, fleetKeys);
 			options.events.emit(subagentRpcReplyEvent(request.requestId), {
 				version: SUBAGENT_RPC_PROTOCOL_VERSION,
 				requestId: request.requestId,

package/dist/extensions/pi-subagents/src/extension/schemas.ts

@@ -65,6 +65,18 @@ const JsonSchemaObject = Type.Unsafe({
 	description: "JSON Schema object for strict structured output. Non-object roots are rejected.",
 });
 
+const AcceptanceEvidenceKinds = [
+	"changed-files",
+	"tests-added",
+	"commands-run",
+	"validation-output",
+	"residual-risks",
+	"no-staged-files",
+	"diff-summary",
+	"review-findings",
+	"manual-notes",
+];
+
 const AcceptanceOverride = Type.Unsafe({
 	anyOf: [
 		{ type: "string", enum: ["auto", "attested", "checked", "verified"] },
@@ -77,7 +89,7 @@ const AcceptanceOverride = Type.Unsafe({
 		{ type: "boolean", enum: [false] },
 		{ type: "object", additionalProperties: true },
 	],
-	description: "Optional acceptance policy. For reviewer/read-only calls, omit acceptance. Evidence levels end at verified; require independent review with acceptance.review.required. The value reviewed is an achieved status and is accepted by the schema only for actionable preflight recovery. In the current/default contract, omitted means auto-inferred. With agentContract.version=1, omitted means not requested and acceptance failures are reported separately from execution.",
+	description: `Optional acceptance policy. For reviewer/read-only calls, omit acceptance. Example: { level: "checked", evidence: ["commands-run", "changed-files"] }. Supported evidence kinds: ${AcceptanceEvidenceKinds.join(", ")}. Evidence levels end at verified; use acceptance.review.required for review. Omitted means auto-inferred unless agentContract.version=1.`,
 });
 
 const AgentContractOverride = Type.Object({
@@ -107,6 +119,16 @@ const ToolBudgetOverride = Type.Object({
 	block: Type.Optional(ToolBudgetBlock),
 }, { additionalProperties: false, description: "Optional child tool-call budget. soft nudges the child; after hard, block tools (default read/grep/find/ls, or '*' for all tools) are blocked so the child can finalize." });
 
+const UsageBudgetLimitOverride = Type.Object({
+	soft: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
+	hard: Type.Number({ exclusiveMinimum: 0 }),
+}, { additionalProperties: false });
+
+const UsageBudgetOverride = Type.Object({
+	tokens: Type.Optional(UsageBudgetLimitOverride),
+	costUsd: Type.Optional(UsageBudgetLimitOverride),
+}, { additionalProperties: false, description: "Optional root-only reported-usage budget. Hard limits prevent future child launches; running children are not stopped." });
+
 const TaskItem = Type.Object({
 	agent: Type.String(), 
 	task: Type.String(), 
@@ -183,6 +205,8 @@ export const DynamicCollectSchema = Type.Object({
 
 // Flattened so chain steps do not need an object-shape anyOf/oneOf union.
 export const ChainItem = Type.Object({
+	checkpoint: Type.Optional(Type.String({ description: "Approval checkpoint name. Pauses the chain without launching a child until approve-checkpoint or reject-checkpoint is called." })),
+	message: Type.Optional(Type.String({ description: "Optional approval message shown while the checkpoint is paused." })),
 	agent: Type.Optional(Type.String({ description: "Sequential step agent name" })),
 	task: Type.Optional(Type.String({
 		description: "Task template with variables: {task}=original request, {previous}=prior step's text response, {chain_dir}=shared folder, {outputs.name}=prior named output. Required for first step, defaults to '{previous}' for subsequent steps."
@@ -217,7 +241,7 @@ export const ChainItem = Type.Object({
 		description: "Create isolated git worktrees for each parallel task."
 	})),
 }, {
-	description: "Chain step: use {agent, task?, ...} for sequential, {parallel: [...]} for static concurrent execution, or {expand, parallel: {...}, collect} for dynamic fanout.",
+	description: "Chain step: use {agent, task?, ...} for sequential, {parallel: [...]} for static concurrent execution, {expand, parallel: {...}, collect} for dynamic fanout, or {checkpoint: name, message?} for an approval pause.",
 	additionalProperties: false,
 });
 
@@ -238,16 +262,16 @@ const ControlOverrides = Type.Object({
 
 const SubagentParamsSchema = Type.Object({
 	agent: Type.Optional(Type.String({ description: "Agent name (SINGLE mode) or target for management get/update/delete" })),
-	task: Type.Optional(Type.String({ description: "Task (SINGLE mode, optional for self-contained agents)" })),
+	task: Type.Optional(Type.String({ description: "Task for SINGLE-mode execution, or an optional advisory intent for action:'list' (list only appends a task-aware recommendation and never launches work; explicitly call subagent with the recommended canonical agent name and the task to execute)" })),
 	// Management action (when present, tool operates in management mode)
 	action: Type.Optional(Type.String({
 		description: "Optional management/control action. Omit this field entirely for execution/delegation ({agent, task}, {tasks}, or {chain}); use it only for management/control actions."
 	})),
 	id: Type.Optional(Type.String({
-		description: "Run id or prefix for action='status', action='interrupt', action='stop', action='resume', action='steer', or action='append-step'."
+		description: "Run id or prefix for action='status', action='interrupt', action='stop', action='resume', action='steer', action='append-step', action='approve-checkpoint', or action='reject-checkpoint'."
 	})),
 	runId: Type.Optional(Type.String({
-		description: "Target run ID for action='interrupt', action='stop', action='resume', action='steer', or action='append-step'. Prefer id for new calls."
+		description: "Target run ID for action='interrupt', action='stop', action='resume', action='steer', action='append-step', action='approve-checkpoint', or action='reject-checkpoint'. Prefer id for new calls."
 	})),
 	dir: Type.Optional(Type.String({
 		description: "Async run directory for action='status', action='stop', action='resume', or action='steer'."
@@ -290,13 +314,14 @@ const SubagentParamsSchema = Type.Object({
 	})),
 	chainDir: Type.Optional(Type.String({ description: "Persistent chain artifact directory; defaults to user-scoped temp storage." })),
 	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
-	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Optional run-level timeout in ms for foreground and async/background runs. Alias of maxRuntimeMs." })),
-	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias of timeoutMs for optional run-level timeout in foreground and async/background runs." })),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Timeout for foreground and async/background runs; foreground defaults to 30m absent call/agent. Alias maxRuntimeMs." })),
+	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias timeoutMs for foreground and async/background runs; foreground defaults to 30m absent call/agent." })),
 	turnBudget: Type.Optional(TurnBudgetOverride),
 	toolBudget: Type.Optional(ToolBudgetOverride),
+	usageBudget: Type.Optional(UsageBudgetOverride),
 	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),
 	cwd: Type.Optional(Type.String()),
-	artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: true)" })),
+	artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: false)" })),
 	includeProgress: Type.Optional(Type.Boolean({ description: "Include full progress in result (default: false)" })),
 	share: Type.Optional(Type.Boolean({ description: "Upload session to GitHub Gist for sharing (default: false)" })),
 	sessionDir: Type.Optional(

package/dist/extensions/pi-subagents/src/extension/tool-description.ts

@@ -6,24 +6,38 @@ import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
 const CUSTOM_TOOL_DESCRIPTION_FILE = "subagent-tool-description.md";
 const CUSTOM_TOOL_DESCRIPTION_MAX_BYTES = 50 * 1024;
 
+/**
+ * Generic parent-only delegation routing contract. Deliberately contains no
+ * bundled agent names: agents are selected from runtime catalog metadata only.
+ * Attached to the parent `subagent` tool as promptGuidelines and embedded in
+ * the mandatory safety guidance so custom descriptions cannot remove it.
+ */
+export const SUBAGENT_PARENT_ROUTING_GUIDANCE = `PARENT-ONLY SUBAGENT ROUTING:
+• Before any execution, call { action: "list" } and select only an executable entry using its current role, context, and tool metadata.
+• Keep tiny targeted reads and simple answers local with the parent.
+• Send broad local investigation, external research, and mutation/implementation work to a capable delegated agent.
+• The parent remains the decision-maker and normally the sole writer.`;
+
 export const SUBAGENT_SAFETY_GUIDANCE = `SAFETY-CRITICAL SUBAGENT GUIDANCE:
 • Use { action: "list" } before execution and only run executable/non-disabled agents or chains.
-• Keep execution and management separate: omit action for SINGLE/PARALLEL/CHAIN execution; use action only for list/get/models/create/update/delete/status/grant-spawn-budget/interrupt/stop/resume/append-step/doctor.
+• Keep execution and management separate: omit action for SINGLE/PARALLEL/CHAIN execution; use action only for list/get/models/create/update/delete/status/grant-spawn-budget/interrupt/stop/resume/steer/append-step/approve-checkpoint/reject-checkpoint/doctor.
 • Async/background runs: launch with async:true only when work can proceed independently. Do not sleep or poll status just to wait. In an interactive session, normally return control and let Pi wake you; do not call subagent_wait merely to wait. Override that default and call subagent_wait when the current request is run-to-completion — for example, the user asked you to report results back before continuing or a skill must finish in one turn. Headless sessions auto-drain current-session work at agent_end; use subagent_wait when this turn must receive results before it ends.
 • Child-safety boundary: ordinary child subagents are not orchestrators and must not run subagents. Only explicitly configured fanout children may use the child-safe subagent tool, still bounded by depth/session limits.
 • Writing/review safety: keep one writer for the same cwd/worktree. Use fresh-context read-only reviewers/validators for independent review, then have the parent synthesize and apply fixes as the sole writer unless an isolated worktree was intentionally requested.
-• Artifacts/status essentials: chain outputs live under {chain_dir}; async runs expose asyncId/asyncDir with status.json, events.jsonl, output logs, and status via { action: "status", id }. Include output paths and residual risks when reporting results.`;
+• Artifacts/status essentials: chain outputs live under {chain_dir}; async runs expose asyncId/asyncDir with status.json, events.jsonl, output logs, and status via { action: "status", id }. Normal delegated results are reference-first: completion returns saved-output references plus lifecycle/status information, not child prose — inspect full output through the saved output path, async status/transcript, or resume. Include output paths and residual risks when reporting results.
+
+${SUBAGENT_PARENT_ROUTING_GUIDANCE}`;
 
 export const FULL_SUBAGENT_TOOL_DESCRIPTION = `To delegate work, call with { agent, task }, { tasks }, or { chain }; omit action. Use action only for management/control actions listed below.
 
 EXECUTION (use exactly ONE mode):
 • Before executing, use { action: "list" } to inspect configured agents/chains. Only execute agents listed as executable/non-disabled.
 • SINGLE: { agent, task? } - one task; omit task for self-contained agents
-• CHAIN: { chain: [{agent:"agent-a"}, {parallel:[{agent:"agent-b",count:3}]}] } - sequential pipeline with optional parallel fan-out
+• CHAIN: { chain: [{agent:"agent-a"}, {checkpoint:"review"}, {parallel:[{agent:"agent-b",count:3}]}] } - sequential pipeline with optional approval checkpoints and parallel fan-out
 • PARALLEL: { tasks: [{agent,task,count?,output?,reads?,progress?}, ...], concurrency?: number, worktree?: true } - concurrent execution (worktree: isolate each task in a git worktree)
 • Optional context: { context: "fresh" | "fork" } (explicit value overrides every child; when omitted, each requested agent uses its own defaultContext, otherwise "fresh"; inspect agent defaults via { action: "list" })
 • Fork thinking: model strings accept a thinking suffix (provider/model:off|minimal|low|medium|high|xhigh|max). Forking over a parent transcript that carries signed Anthropic thinking blocks forces thinking off only when a child's effective primary or fallback model resolves to the Anthropic provider or anthropic-messages API; unresolved models are treated conservatively. The result notes affected children, including on failures. Use fresh context when an Anthropic child needs thinking.
-• Optional timeout: { timeoutMs } or { maxRuntimeMs } sets a run-level max runtime for foreground and async/background runs
+• Optional timeout: { timeoutMs } or { maxRuntimeMs } sets a run-level max runtime for foreground and async/background runs; foreground defaults to 30 minutes only when neither value nor an agent timeout is provided
 • Acceptance: omit acceptance for reviewer/read-only calls. Evidence levels end at verified. Use acceptance.review.required to require independent review of a writer result. Never request acceptance:"reviewed"; reviewed is achieved only after an independent reviewer result.
 • If { action: "list" } shows proactive skill subagent suggestions, consider a small fresh-context fanout for broad tasks where one of those skills would materially help
 
@@ -35,10 +49,11 @@ CHAIN TEMPLATE VARIABLES (use in task strings):
 CHAIN EXAMPLES (quick reference for the nested schema):
 • Sequential: { chain: [{agent:"agent-a", task:"Analyze {task}"}, {agent:"agent-b", task:"Plan based on {previous}"}] }
 • Parallel fan-out: { chain: [{parallel: [{agent:"agent-a", task:"Check part of {task}", count: 3}]}] }
-• Mixed: { chain: [{agent:"agent-a", task:"Research {task}"}, {parallel: [{agent:"agent-b", task:"Review {previous}", count: 2}]}, {agent:"agent-c", task:"Summarize {previous}"}] }
+• Mixed: { chain: [{agent:"agent-a", task:"Research {task}"}, {checkpoint:"review", message:"Approve implementation?"}, {parallel: [{agent:"agent-b", task:"Review {previous}", count: 2}]}, {agent:"agent-c", task:"Summarize {previous}"}] }
 
-MANAGEMENT (use action field, omit agent/task/chain/tasks):
+MANAGEMENT (use action field; omit agent/chain/tasks — the sole field exception is list's optional advisory task):
 • { action: "list" } - discover executable agents/chains
+• { action: "list", task: "..." } - same, plus optional task-aware advisory routing: recommends one canonical agent (implementation or read-only) for the task, or explains why none is safe. It only recommends and never launches; to proceed, explicitly call subagent with the recommended canonical agent name and the task.
 • { action: "get", agent: "name" } - full detail; packaged agents use dotted runtime names like "package.agent"
 • { action: "models", agent?: "name" } - show the runtime-loaded builtin subagent model mapping, optionally filtered to one builtin
 • { action: "watchdog.status" | "watchdog.check" | "watchdog.recommend-model" } - inspect the opt-in subagent watchdog and its strong complementary model recommendation
@@ -47,10 +62,10 @@ MANAGEMENT (use action field, omit agent/task/chain/tasks):
 • acceptanceRole affects inferred acceptance only, never tool access. Explicit task mutation/no-edit intent wins; omission preserves name heuristics. Update with false or an empty string to clear it.
 • { action: "update", agent: "code-analysis.custom-agent", config: { package: "analysis", ... } } - merge
 • { action: "delete", agent: "code-analysis.custom-agent" }
-• { action: "eject", agent: "commentator", agentScope?: "user" | "project" } - copy a bundled/package agent to user/project scope as an editable custom file that shadows the original (default scope: user)
-• { action: "disable", agent: "commentator", agentScope?: "user" | "project" } - hide any agent from runtime discovery via a reversible settings override (default scope: user)
-• { action: "enable", agent: "commentator", agentScope?: "user" | "project" } - remove a disabled override and restore discovery
-• { action: "reset", agent: "commentator", agentScope?: "user" | "project" } - delete the scope's custom agent file and/or settings override, restoring the bundled default
+• { action: "eject", agent: "agent-name", agentScope?: "user" | "project" } - copy a bundled/package agent to user/project scope as an editable custom file that shadows the original (default scope: user)
+• { action: "disable", agent: "agent-name", agentScope?: "user" | "project" } - hide any agent from runtime discovery via a reversible settings override (default scope: user)
+• { action: "enable", agent: "agent-name", agentScope?: "user" | "project" } - remove a disabled override and restore discovery
+• { action: "reset", agent: "agent-name", agentScope?: "user" | "project" } - delete the scope's custom agent file and/or settings override, restoring the bundled default
 • { action: "grant-spawn-budget", additional: 10 } - add bounded capacity from the root interactive parent after native user confirmation; grants are rejected while children are active and cumulative grants cannot exceed the original configured cap
 • Use chainName for chain operations; packaged chains also use dotted runtime names
 
@@ -63,6 +78,7 @@ CONTROL:
 • { action: "resume", id: "...", message: "...", index?: 0 } - revive a paused, completed, or failed async/foreground child from its session; stopped runs are non-resumable; routed nested runs may accept live follow-ups; use steer for a live top-level async child
 • { action: "steer", id: "...", message: "...", index?: 0 } - await correlated child-Pi input acceptance for up to 3 seconds; returns delivered, scheduled, pending, partial, recovered, or failed with a request id. Only top-level single runs may recover after a further 15-second pause/revival bound; chain, parallel, and nested runs never auto-interrupt.
 • { action: "append-step", id: "...", chain: [{agent:"agent-c", task:"Use {previous}"}] } - append one step to the tail of a running async chain
+• { action: "approve-checkpoint", id: "..." } / { action: "reject-checkpoint", id: "..." } - decide a paused current-session async chain checkpoint
 
 SCHEDULE (opt-in; requires { "scheduledRuns": { "enabled": true } } in config.json):
 • { action: "schedule", agent, task?, schedule: "+10m" | "2030-01-01T09:00:00Z", scheduleName? } - defer a subagent launch until a future time. Also accepts tasks[] or chain[]. Scheduled runs always launch async with fresh context; they become normal tracked async runs once they fire. Only schedule explicit delayed runs the user asked for.
@@ -79,17 +95,18 @@ export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = `To delegate work, call with {
 
 EXECUTE:
 • Before execution, call { action: "list" }; run only executable/non-disabled configured agents/chains.
-• SINGLE {agent, task?}; PARALLEL {tasks:[{agent,task,count?,output?,reads?,progress?}], concurrency?, worktree?}; CHAIN {chain:[{agent,task?},{parallel:[...]}]}.
-• context can be "fresh" or "fork"; omitted uses each agent defaultContext, otherwise fresh. timeoutMs/maxRuntimeMs apply to foreground and async/background runs.
+• SINGLE {agent, task?}; PARALLEL {tasks:[{agent,task,count?,output?,reads?,progress?}], concurrency?, worktree?}; CHAIN {chain:[{agent,task?},{checkpoint:"review"},{parallel:[...]}]}.
+• context can be "fresh" or "fork"; omitted uses each agent defaultContext, otherwise fresh. timeoutMs/maxRuntimeMs apply to foreground and async/background runs; foreground defaults to 30 minutes only when neither value nor an agent timeout is provided.
 • Omit acceptance for reviewer/read-only calls. Evidence levels end at verified; use acceptance.review.required for independent writer review. reviewed is an achieved status, never an explicit input.
 • Chain templates may use {task}, {previous}, {chain_dir}, and named outputs. Parallel worktree isolation requires a clean git repo.
 • Chain example: { chain: [{agent:"agent-a", task:"Analyze {task}"}, {parallel: [{agent:"agent-b", task:"Check {previous}", count: 3}]}] }
 • If list shows proactive skill subagent suggestions, use a small fresh-context fanout only when the task is broad enough.
 
 MANAGE / CONTROL:
-• Use action without execution fields: list, get, models, create, update, delete, eject, disable, enable, reset, grant-spawn-budget, doctor, watchdog.status, watchdog.check, watchdog.recommend-model, watchdog.configure.
+• Use action without execution fields (list may add an optional advisory task): list, get, models, create, update, delete, eject, disable, enable, reset, grant-spawn-budget, doctor, watchdog.status, watchdog.check, watchdog.recommend-model, watchdog.configure.
+• { action: "list", task: "..." } optionally appends task-aware advisory routing that recommends a canonical agent but never launches; execute the recommended agent explicitly in a separate call.
 • Agent acceptanceRole (read-only or writer) affects inferred acceptance only, never tools. Explicit task intent wins; omission keeps name heuristics. Update with false or an empty string to clear it.
-• Async control actions: status, interrupt, stop, resume, steer, append-step. Use stop with an id for current-session top-level async runs. Use status view:"fleet" for active-run overview, view:"transcript" to tail child output, steer for acknowledged top-level live async guidance, and resume for paused/completed/failed revival or a routed nested follow-up. Stopped runs are non-resumable. Steering delivery means Pi accepted the correlated user input, not model compliance; use index for a specific child.
+• Async control actions: status, interrupt, stop, resume, steer, append-step, approve-checkpoint, reject-checkpoint. Use stop with an id for current-session top-level async runs. Use status view:"fleet" for active-run overview, view:"transcript" to tail child output, steer for acknowledged top-level live async guidance, and resume for paused/completed/failed revival or a routed nested follow-up. Stopped runs are non-resumable. Steering delivery means Pi accepted the correlated user input, not model compliance; use index for a specific child.
 • Opt-in schedule actions: schedule, schedule-list, schedule-status, schedule-cancel. Schedule only explicit delayed runs the user asked for.
 
 ASYNC / WAIT:
@@ -97,6 +114,7 @@ ASYNC / WAIT:
 • Status and artifacts live under asyncId/asyncDir with status.json, events.jsonl, output logs, session files, and { action:"status", id:"..." }.
 
 SAFETY:
+• Parent-only routing: call { action: "list" } before any execution and select only an executable entry using its current role, context, and tool metadata. Keep tiny targeted reads and simple answers local; send broad local investigation, external research, and mutation/implementation work to a capable delegated agent. The parent remains the decision-maker and normally the sole writer.
 • Ordinary child subagents are not orchestrators and must not run subagents. Only explicit fanout children may use child-safe subagent, still bounded by depth/session limits.
 • Keep one writer per cwd/worktree. Use fresh read-only review/validation fanout, then synthesize and apply fixes from the parent unless isolated worktrees were intentionally requested.`;
 

package/dist/extensions/pi-subagents/src/intercom/intercom-bridge.ts

@@ -16,6 +16,7 @@ function defaultSubagentConfigDir(agentDir = defaultAgentDir()): string {
 }
 
 const DEFAULT_INTERCOM_TARGET_PREFIX = "subagent-chat";
+export const PI_INTERCOM_SESSION_ID_ENV = "PI_INTERCOM_SESSION_ID";
 export const INTERCOM_BRIDGE_MARKER = "Intercom orchestration channel:";
 const DEFAULT_INTERCOM_BRIDGE_TEMPLATE = `The inherited thread is reference-only. Do not continue that conversation or send questions, status updates, or completion handoffs to the supervisor in normal assistant text.
 
@@ -32,6 +33,7 @@ Do not use contact_supervisor or intercom for routine completion handoffs. If no
 export interface IntercomBridgeState {
 	active: boolean;
 	mode: IntercomBridgeMode;
+	resultDelivery: boolean;
 	orchestratorTarget?: string;
 	extensionDir: string;
 	instruction: string;
@@ -55,10 +57,11 @@ interface ResolveIntercomBridgeInput {
 	agentDir?: string;
 }
 
-export function resolveIntercomSessionTarget(sessionName: string | undefined, sessionId: string): string {
+export function resolveIntercomSessionTarget(sessionName: string | undefined, sessionId: string, intercomSessionId = process.env[PI_INTERCOM_SESSION_ID_ENV]): string {
 	const trimmedName = sessionName?.trim();
 	if (trimmedName) return trimmedName;
-	const normalizedSessionId = sessionId.startsWith("session-") ? sessionId.slice("session-".length) : sessionId;
+	const fallbackSessionId = intercomSessionId?.trim() || sessionId;
+	const normalizedSessionId = fallbackSessionId.startsWith("session-") ? fallbackSessionId.slice("session-".length) : fallbackSessionId;
 	return `${DEFAULT_INTERCOM_TARGET_PREFIX}-${normalizedSessionId.slice(0, 8)}`;
 }
 
@@ -78,11 +81,12 @@ export function resolveIntercomBridgeMode(value: unknown): IntercomBridgeMode {
 
 function resolveIntercomBridgeConfig(value: ExtensionConfig["intercomBridge"]): Required<IntercomBridgeConfig> {
 	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		return { mode: "always", instructionFile: "" };
+		return { mode: "always", instructionFile: "", resultDelivery: true };
 	}
 	return {
 		mode: resolveIntercomBridgeMode(value.mode),
 		instructionFile: typeof value.instructionFile === "string" ? value.instructionFile : "",
+		resultDelivery: value.resultDelivery !== false,
 	};
 }
 
@@ -146,11 +150,12 @@ export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): Interc
 	);
 	const reason = inactiveReason(mode, input.context, orchestratorTarget);
 	if (reason || !orchestratorTarget) {
-		return { active: false, mode, extensionDir: NATIVE_INTERCOM_EXTENSION_DIR, instruction: defaultInstruction };
+		return { active: false, mode, resultDelivery: config.resultDelivery, extensionDir: NATIVE_INTERCOM_EXTENSION_DIR, instruction: defaultInstruction };
 	}
 	return {
 		active: true,
 		mode,
+		resultDelivery: config.resultDelivery,
 		orchestratorTarget,
 		extensionDir: NATIVE_INTERCOM_EXTENSION_DIR,
 		instruction: buildIntercomBridgeInstruction(orchestratorTarget, resolveInstructionTemplate(config.instructionFile, settingsDir)),