pi-subagents 0.35.0 → 0.36.0

package/src/agents/agents.ts

@@ -35,6 +35,7 @@ export interface AgentMemoryConfig {
 }
 
 export const BUILTIN_AGENT_NAMES = [
+	"advisor",
 	"context-builder",
 	"delegate",
 	"oracle",
@@ -476,7 +477,7 @@ function splitToolList(rawTools: string[] | undefined): { tools?: string[]; mcpD
 		}
 	}
 	return {
-		...(tools.length > 0 ? { tools } : {}),
+		...(rawTools !== undefined ? { tools } : {}),
 		...(mcpDirectTools.length > 0 ? { mcpDirectTools } : {}),
 	};
 }
@@ -1159,7 +1160,19 @@ export function removeBuiltinAgentOverrideFields(
 	return { path: filePath, removed: true };
 }
 
-function listFilesRecursive(dir: string, predicate: (fileName: string) => boolean): string[] {
+const DISCOVERY_PRUNED_DIR_NAMES = new Set([".git", "node_modules"]);
+
+function isDiscoveryNestedProjectRoot(dir: string): boolean {
+	return isDirectory(getProjectConfigDir(dir)) || isDirectory(path.join(dir, ".agents"));
+}
+
+function shouldPruneDiscoveryDir(rootDir: string, dir: string, dirName: string): boolean {
+	if (DISCOVERY_PRUNED_DIR_NAMES.has(dirName)) return true;
+	if (fs.existsSync(path.join(dir, ".git"))) return true;
+	return path.resolve(dir) !== path.resolve(rootDir) && isDiscoveryNestedProjectRoot(dir);
+}
+
+function listFilesRecursive(dir: string, predicate: (fileName: string) => boolean, rootDir = dir): string[] {
 	const files: string[] = [];
 	if (!fs.existsSync(dir)) return files;
 
@@ -1173,7 +1186,9 @@ function listFilesRecursive(dir: string, predicate: (fileName: string) => boolea
 	for (const entry of entries) {
 		const filePath = path.join(dir, entry.name);
 		if (entry.isDirectory()) {
-			files.push(...listFilesRecursive(filePath, predicate));
+			if (!shouldPruneDiscoveryDir(rootDir, filePath, entry.name)) {
+				files.push(...listFilesRecursive(filePath, predicate, rootDir));
+			}
 			continue;
 		}
 		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
@@ -1233,7 +1248,9 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 		const runtimeName = buildRuntimeName(localName, packageName);
 
 		const rawTools = parseFrontmatterList(frontmatter.tools);
-		const { tools = [], mcpDirectTools = [] } = splitToolList(rawTools);
+		const parsedTools = splitToolList(rawTools);
+		const tools = parsedTools.tools ?? [];
+		const mcpDirectTools = parsedTools.mcpDirectTools ?? [];
 		const defaultReads = parseFrontmatterList(frontmatter.defaultReads);
 		const skillStr = frontmatter.skill || frontmatter.skills;
 		const skills = parseFrontmatterList(skillStr);
@@ -1315,7 +1332,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			localName,
 			packageName,
 			description: frontmatter.description,
-			tools: tools.length > 0 ? tools : undefined,
+			tools: rawTools !== undefined ? tools : undefined,
 			mcpDirectTools: mcpDirectTools.length > 0 ? mcpDirectTools : undefined,
 			model: frontmatter.model,
 			fallbackModels: fallbackModels && fallbackModels.length > 0 ? fallbackModels : undefined,

package/src/api/delegation.ts

@@ -1,4 +1,5 @@
 export const SUBAGENT_DELEGATION_PROTOCOL_VERSION = 1 as const;
+export const SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION = 2 as const;
 
 // This is the established extension-to-extension transport. The public API
 // intentionally reuses it instead of adding a second event protocol.
@@ -19,6 +20,37 @@ export interface SubagentDelegationToolBudget {
 	block?: string[] | "*";
 }
 
+export interface SubagentDelegationAgentContract {
+	version: 1;
+}
+
+export type SubagentDelegationJsonSchemaObject = Record<string, unknown>;
+
+export interface SubagentDelegationExecutionResult {
+	status: "completed" | "failed" | "paused" | "stopped" | "detached";
+	success: boolean;
+	exitCode: number;
+	error?: string;
+	interrupted?: boolean;
+	timedOut?: boolean;
+	stopped?: boolean;
+	detached?: boolean;
+}
+
+export interface SubagentDelegationReviewResult {
+	status: "not-requested" | "no-blockers" | "blockers" | "needs-parent-decision";
+	findings?: Array<{ severity: "blocker" | "non-blocking"; file?: string; issue: string; rationale: string }>;
+}
+
+export interface SubagentDelegationEffectsResult {
+	fileMutation?: {
+		status: "not-requested" | "not-applicable" | "observed" | "missing";
+		expected: boolean;
+		attempted: boolean;
+		message?: string;
+	};
+}
+
 export type SubagentDelegationAcceptanceEvidence =
 	| "changed-files"
 	| "tests-added"
@@ -87,6 +119,8 @@ export interface SubagentDelegationRequest {
 	skill?: string | string[] | boolean;
 	output?: string | boolean;
 	outputMode?: "inline" | "file-only";
+	outputSchema?: SubagentDelegationJsonSchemaObject;
+	agentContract?: SubagentDelegationAgentContract;
 	acceptance?: SubagentDelegationAcceptance;
 	artifacts?: boolean;
 }
@@ -116,6 +150,7 @@ export type SubagentDelegationStatus =
 	| "interrupted"
 	| "turn_budget_exhausted"
 	| "tool_budget_exhausted"
+	| "structured_output_failed"
 	| "acceptance_failed"
 	| "invalid_request"
 	| "unavailable_context";
@@ -144,10 +179,13 @@ export interface SubagentDelegationResponse extends SubagentDelegationStarted {
 	agent?: string;
 	model?: string;
 	exitCode?: number;
+	execution?: SubagentDelegationExecutionResult;
 	output?: string;
 	outputPath?: string;
 	sessionFile?: string;
 	acceptance?: SubagentDelegationAcceptanceResult;
+	review?: SubagentDelegationReviewResult;
+	effects?: SubagentDelegationEffectsResult;
 	turns?: number;
 	toolCount?: number;
 	durationMs?: number;
@@ -156,3 +194,90 @@ export interface SubagentDelegationResponse extends SubagentDelegationStarted {
 }
 
 export interface SubagentDelegationCancel extends SubagentDelegationStarted {}
+
+export type SubagentDelegationV2Thinking = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+export type SubagentDelegationV2ResultRequest =
+	| { kind: "text" }
+	| { kind: "structured"; schema: SubagentDelegationJsonSchemaObject };
+
+export interface SubagentDelegationV2Request {
+	version: typeof SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION;
+	requestId: string;
+	ownerRunId: string;
+	nodeId: string;
+	agent: string;
+	task: string;
+	context: "fresh" | "fork";
+	cwd: string;
+	model?: string;
+	thinking?: SubagentDelegationV2Thinking;
+	timeoutMs?: number;
+	turnBudget?: SubagentDelegationTurnBudget;
+	toolBudget?: SubagentDelegationToolBudget;
+	skill?: string | string[] | boolean;
+	artifacts?: boolean;
+	result: SubagentDelegationV2ResultRequest;
+}
+
+export interface SubagentDelegationV2Started {
+	version: typeof SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION;
+	requestId: string;
+	ownerRunId: string;
+	nodeId: string;
+}
+
+export interface SubagentDelegationV2Update extends SubagentDelegationV2Started {
+	currentTool?: string;
+	currentToolArgs?: string;
+	recentOutput?: string;
+	recentOutputLines?: string[];
+	recentTools?: Array<{ tool: string; args: string }>;
+	model?: string;
+	toolCount?: number;
+	durationMs?: number;
+	tokens?: number;
+}
+
+export type SubagentDelegationV2Status = SubagentDelegationStatus | "duplicate_node";
+
+export type SubagentDelegationV2Value =
+	| { kind: "text"; text: string }
+	| { kind: "structured"; value: unknown };
+
+export interface SubagentDelegationV2Usage {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	turns: number;
+	toolCalls: number;
+	durationMs: number;
+}
+
+export interface SubagentDelegationV2TerminalResponse extends SubagentDelegationV2Started {
+	status: Exclude<SubagentDelegationV2Status, "invalid_request">;
+	error?: string;
+	runId?: string;
+	agent?: string;
+	model?: string;
+	thinking?: string;
+	exitCode?: number;
+	result?: SubagentDelegationV2Value;
+	usage?: SubagentDelegationV2Usage;
+}
+
+/** A malformed V2 request can only be correlated by the valid identity fields it supplied. */
+export interface SubagentDelegationV2InvalidResponse {
+	version: typeof SUBAGENT_DELEGATION_V2_PROTOCOL_VERSION;
+	requestId: string;
+	ownerRunId?: string;
+	nodeId?: string;
+	status: "invalid_request";
+	error?: string;
+}
+
+export type SubagentDelegationV2Response = SubagentDelegationV2TerminalResponse | SubagentDelegationV2InvalidResponse;
+
+export interface SubagentDelegationV2Cancel extends SubagentDelegationV2Started {}

package/src/extension/config.ts

@@ -1,8 +1,10 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ExtensionConfig } from "../shared/types.ts";
+import type { ArtifactDirPreference, ExtensionConfig } from "../shared/types.ts";
 import { getAgentDir } from "../shared/utils.ts";
 
+const ARTIFACT_DIR_PREFERENCES = new Set<ArtifactDirPreference>(["project", "session", "temp"]);
+
 export function getConfigPath(): string {
 	return path.join(getAgentDir(), "extensions", "subagent", "config.json");
 }
@@ -13,6 +15,10 @@ function readConfigForUpdate(configPath = getConfigPath()): ExtensionConfig {
 	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
 		throw new Error(`Subagent config at '${configPath}' must be a JSON object`);
 	}
+	const config = parsed as Record<string, unknown>;
+	if (config.artifactDir !== undefined && !ARTIFACT_DIR_PREFERENCES.has(config.artifactDir as ArtifactDirPreference)) {
+		throw new Error(`config.artifactDir must be "project", "session", or "temp"`);
+	}
 	return parsed as ExtensionConfig;
 }
 

package/src/extension/index.ts

@@ -20,10 +20,13 @@ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { keyText, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Box, Container, Spacer, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
 import { discoverAgents } from "../agents/agents.ts";
+import { ensureAccessibleDir } from "../shared/accessible-dir.ts";
 import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
 import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import { cleanupOldChainDirs } from "../shared/settings.ts";
 import { clearLegacyResultAnimationTimer, renderSubagentResult } from "../tui/render.ts";
+import { openSubagentFleet } from "../tui/fleet.ts";
+import { SubagentFleetStatus } from "../tui/fleet-status.ts";
 import { SubagentParams } from "./schemas.ts";
 import { validateChainInput } from "./chain-validation.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
@@ -92,28 +95,6 @@ function expandTilde(p: string): string {
 	return p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
 }
 
-/**
- * Create a directory and verify it is actually accessible.
- * On Windows with Azure AD/Entra ID, directories created shortly after
- * wake-from-sleep can end up with broken NTFS ACLs (null DACL) when the
- * cloud SID cannot be resolved without network connectivity. This leaves
- * the directory completely inaccessible to the creating user.
- */
-function ensureAccessibleDir(dirPath: string): void {
-	fs.mkdirSync(dirPath, { recursive: true });
-	try {
-		fs.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
-	} catch {
-		try {
-			fs.rmSync(dirPath, { recursive: true, force: true });
-		} catch {
-			// Best effort: retry mkdir/access even if cleanup fails.
-		}
-		fs.mkdirSync(dirPath, { recursive: true });
-		fs.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
-	}
-}
-
 function isSlashResultRunning(result: { details?: Details }): boolean {
 	return result.details?.progress?.some((entry) => entry.status === "running")
 		|| result.details?.results.some((entry) => entry.progress?.status === "running")
@@ -210,12 +191,16 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const config = loadConfig();
 	const waitToolConfig = resolveWaitToolConfig(config.waitTool);
 	const asyncByDefault = config.asyncByDefault === true;
+	const fleetViewEnabled = config.fleetView !== false;
+	const asyncWidgetEnabled = config.asyncWidget === true || (!fleetViewEnabled && config.asyncWidget !== false);
 	const tempArtifactsDir = getArtifactsDir(null);
 	cleanupAllArtifactDirs(DEFAULT_ARTIFACT_CONFIG.cleanupDays);
 
 	const state: SubagentState = {
 		baseCwd: "",
 		currentSessionId: null,
+		artifactDirPreference: config.artifactDir ?? DEFAULT_ARTIFACT_CONFIG.dir,
+		parentSessionFile: null,
 		subagentInProgress: false,
 		subagentSpawns: {
 			sessionId: null,
@@ -244,22 +229,30 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 
 	const supervisorChannel = createNativeSupervisorChannel(pi, state);
 	const mainWatchdog = registerMainWatchdog(pi);
-	let disposeSubagentNotify = () => {};
+	const completionNotifier = registerSubagentNotify(pi, state, { batchConfig: config.completionBatch });
+	const fleetStatus = fleetViewEnabled
+		? new SubagentFleetStatus(state, async (itemKey) => {
+			const ctx = state.lastUiContext;
+			if (!ctx?.hasUI) return;
+			await openSubagentFleet(ctx, state, { initialKey: itemKey });
+		})
+		: undefined;
 	const { startResultWatcher, primeExistingResults, stopResultWatcher } = createResultWatcher(
 		pi,
 		state,
 		RESULTS_DIR,
 		10 * 60 * 1000,
+		{ notifier: completionNotifier },
 	);
-	startResultWatcher();
-	primeExistingResults();
 
 	const runtimeCleanup = () => {
-		disposeSubagentNotify();
-		mainWatchdog.dispose();
 		stopResultWatcher();
+		state.currentSessionId = null;
+		completionNotifier.dispose();
+		mainWatchdog.dispose();
 		scheduledRunManager.stop();
 		supervisorChannel.dispose();
+		fleetStatus?.dispose();
 		clearPendingForegroundControlNotices(state);
 		if (state.poller) {
 			clearInterval(state.poller);
@@ -269,7 +262,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	globalStore[runtimeCleanupStoreKey] = runtimeCleanup;
 
 	const { ensurePoller, refreshWidget, handleStarted, handleComplete, resetJobs, restoreActiveJobs } = createAsyncJobTracker(pi, state, ASYNC_DIR, {
-		widgetEnabled: config.asyncWidget !== false,
+		widgetEnabled: asyncWidgetEnabled,
 	});
 	let executorExecute: ((id: string, params: SubagentParamsLike, signal: AbortSignal, onUpdate: ((r: AgentToolResult<Details>) => void) | undefined, ctx: ExtensionContext) => Promise<AgentToolResult<Details>>) | undefined;
 	const scheduledRunManager = createScheduledRunManager({
@@ -377,6 +370,10 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		getContext: () => state.lastUiContext,
 		execute: (requestId, params, signal, ctx, onUpdate) =>
 			executeSubagentCollapsed(requestId, params, signal, onUpdate, ctx),
+		executeVersioned: (requestId, params, signal, ctx, onUpdate) => {
+			if (ctx.hasUI) ctx.ui.setToolsExpanded(false);
+			return executor.executeDelegated(requestId, params, signal, onUpdate, ctx);
+		},
 	});
 
 	const rpcBridge = registerSubagentRpcBridge({
@@ -472,8 +469,6 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			}
 		}
 	}
-	disposeSubagentNotify = registerSubagentNotify(pi, state, { batchConfig: config.completionBatch });
-
 	const existingVisibleControlNotices = globalStore[controlNoticeSeenStoreKey];
 	const visibleControlNotices = existingVisibleControlNotices instanceof Set ? existingVisibleControlNotices as Set<string> : new Set<string>();
 	globalStore[controlNoticeSeenStoreKey] = visibleControlNotices;
@@ -488,9 +483,17 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const steeringNoticeHandler = (payload: unknown) => {
 		handleSubagentSteeringNotice({ pi, state, details: payload as SubagentSteeringMessageDetails });
 	};
+	const asyncStartedHandler = (payload: unknown) => {
+		handleStarted(payload);
+		fleetStatus?.refresh();
+	};
+	const asyncCompleteHandler = (payload: unknown) => {
+		handleComplete(payload);
+		fleetStatus?.refresh();
+	};
 	const eventUnsubscribes = [
-		pi.events.on(SUBAGENT_ASYNC_STARTED_EVENT, handleStarted),
-		pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, handleComplete),
+		pi.events.on(SUBAGENT_ASYNC_STARTED_EVENT, asyncStartedHandler),
+		pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, asyncCompleteHandler),
 		pi.events.on(SUBAGENT_CONTROL_EVENT, controlEventHandler),
 		pi.events.on(SUBAGENT_STEERING_NOTICE_EVENT, steeringNoticeHandler),
 		rpcBridge.dispose,
@@ -501,6 +504,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		if (event.toolName !== "subagent") return;
 		if (!ctx.hasUI) return;
 		state.lastUiContext = ctx;
+		fleetStatus?.setContext(ctx);
+		fleetStatus?.refresh();
 		if (state.asyncJobs.size > 0) {
 			refreshWidget(ctx);
 			ensurePoller();
@@ -518,9 +523,10 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		}
 	};
 
-	const resetSessionState = (ctx: ExtensionContext) => {
+	const resetSessionState = (ctx: ExtensionContext, recovering: boolean) => {
 		state.baseCwd = ctx.cwd;
 		state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
+		state.parentSessionFile = ctx.sessionManager.getSessionFile();
 		state.subagentSpawns = {
 			sessionId: state.currentSessionId,
 			count: 0,
@@ -546,17 +552,23 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		restoreActiveJobs(ctx);
 		scheduledRunManager.bindSession(ctx);
 		restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
-		primeExistingResults();
+		startResultWatcher();
+		primeExistingResults({ triggerTurn: !recovering });
+		fleetStatus?.setContext(ctx);
 	};
 
-	pi.on("session_start", (_event, ctx) => {
-		resetSessionState(ctx);
+	pi.on("session_start", (event, ctx) => {
+		const recovering = event.reason === "startup" || event.reason === "reload" || event.reason === "resume";
+		resetSessionState(ctx, recovering);
 		rpcBridge.emitReady(ctx);
 		supervisorChannel.start();
 	});
 
 	pi.on("session_shutdown", () => {
-		disposeSubagentNotify();
+		stopResultWatcher();
+		state.currentSessionId = null;
+		state.parentSessionFile = null;
+		completionNotifier.dispose();
 		delete process.env[SUBAGENT_PARENT_SESSION_ENV];
 		for (const unsubscribe of eventUnsubscribes) {
 			try {
@@ -568,7 +580,6 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		if (globalStore[eventUnsubscribeStoreKey] === eventUnsubscribes) {
 			delete globalStore[eventUnsubscribeStoreKey];
 		}
-		stopResultWatcher();
 		scheduledRunManager.stop();
 		if (state.poller) clearInterval(state.poller);
 		state.poller = null;
@@ -584,6 +595,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		promptTemplateBridge.cancelAll();
 		promptTemplateBridge.dispose();
 		supervisorChannel.dispose();
+		fleetStatus?.dispose();
 		if (globalStore[runtimeCleanupStoreKey] === runtimeCleanup) {
 			delete globalStore[runtimeCleanupStoreKey];
 		}

package/src/extension/rpc.ts

@@ -6,7 +6,12 @@ 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 { type Details, ASYNC_DIR, RESULTS_DIR } from "../shared/types.ts";
+import {
+	type Details,
+	ASYNC_DIR,
+	RESULTS_DIR,
+	SUBAGENT_ASYNC_COMPLETE_EVENT,
+} from "../shared/types.ts";
 import { readStatus } from "../shared/utils.ts";
 import { SubagentParams } from "./schemas.ts";
 import { validateChainInput } from "./chain-validation.ts";
@@ -16,7 +21,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", "interrupt", "stop"] as const;
+export const SUBAGENT_RPC_METHODS = ["ping", "status", "spawn", "steer", "interrupt", "stop"] as const;
 export type SubagentRpcMethod = typeof SUBAGENT_RPC_METHODS[number];
 
 export interface SubagentRpcRequestEnvelope {
@@ -172,6 +177,8 @@ function pingData(ctx: ExtensionContext | null) {
 		capabilities: {
 			status: true,
 			asyncSpawn: true,
+			steer: true,
+			nonRecoveringSteer: true,
 			interrupt: true,
 			stop: true,
 		},
@@ -179,6 +186,7 @@ function pingData(ctx: ExtensionContext | null) {
 			ready: SUBAGENT_RPC_READY_EVENT,
 			request: SUBAGENT_RPC_REQUEST_EVENT,
 			replyPrefix: SUBAGENT_RPC_REPLY_EVENT_PREFIX,
+			asyncComplete: SUBAGENT_ASYNC_COMPLETE_EVENT,
 		},
 		session: sessionData(ctx),
 	};
@@ -212,6 +220,20 @@ function spawnParams(params: unknown): SubagentParamsLike {
 	return { ...(input as SubagentParamsLike), async: true, clarify: false };
 }
 
+function steerParams(params: unknown): SubagentParamsLike {
+	const input = assertRecordParams(params, "steer");
+	if (typeof input.message !== "string" || !input.message.trim())
+		throw new SubagentRpcError("invalid_params", "RPC steer requires a non-empty message.");
+	const target = normalizeTargetParams(input, "steer");
+	if (!target.id && !target.runId && !target.dir) throw new SubagentRpcError("invalid_params", "RPC steer requires id, runId, or dir.");
+	return {
+		action: "steer",
+		...target,
+		message: input.message.trim(),
+		steeringRecovery: false,
+	};
+}
+
 function stopAsyncRun(
 	params: unknown,
 	options: RegisterSubagentRpcBridgeOptions,
@@ -289,6 +311,9 @@ async function handleRequest(
 	if (request.method === "status") {
 		return executeChecked(options, ctx, request.requestId, request.method, { action: "status", ...normalizeTargetParams(request.params, "status") });
 	}
+	if (request.method === "steer") {
+		return executeChecked(options, ctx, request.requestId, request.method, steerParams(request.params));
+	}
 	if (request.method === "interrupt") {
 		return executeChecked(options, ctx, request.requestId, request.method, { action: "interrupt", ...normalizeTargetParams(request.params, "interrupt") });
 	}

package/src/extension/schemas.ts

@@ -71,7 +71,16 @@ const AcceptanceOverride = Type.Unsafe({
 		{ type: "boolean", enum: [false] },
 		{ type: "object", additionalProperties: true },
 	],
-	description: "Optional acceptance policy. Omitted means auto-inferred; verified requires configured runtime commands. Reviewed is inferred-only because explicit runs cannot supply an independent reviewer result. Bare \"none\" requires { level: \"none\", reason: \"...\" }, while false is deprecated.",
+	description: "Optional acceptance policy. In the current/default contract, omitted means auto-inferred; verified requires configured runtime commands. With agentContract.version=1, omitted means not requested and acceptance failures are reported separately from execution.",
+});
+
+const AgentContractOverride = Type.Object({
+	version: Type.Integer({ enum: [1], description: "Opt into generic agent contract v1 for this run/child." }),
+}, { additionalProperties: false, description: "Opt-in compatibility contract. Omit to use current default behavior." });
+
+const ChainGateOverride = Type.String({
+	enum: ["execution", "acceptance"],
+	description: "For agentContract.version=1 chain steps, choose whether the chain advances on execution success or acceptance success. Defaults to execution.",
 });
 
 const TurnBudgetOverride = Type.Object({
@@ -104,7 +113,9 @@ const TaskItem = Type.Object({
 	model: Type.Optional(Type.String({ description: "Override model for this task (e.g. 'google/gemini-3-pro')" })),
 	skill: Type.Optional(SkillOverride),
 	toolBudget: Type.Optional(ToolBudgetOverride),
+	outputSchema: Type.Optional(JsonSchemaObject),
 	acceptance: Type.Optional(AcceptanceOverride),
+	agentContract: Type.Optional(AgentContractOverride),
 });
 
 // Parallel task item (within a parallel step)
@@ -125,6 +136,8 @@ export const ParallelTaskSchema = Type.Object({
 	model: Type.Optional(Type.String({ description: "Override model for this task" })),
 	toolBudget: Type.Optional(ToolBudgetOverride),
 	acceptance: Type.Optional(AcceptanceOverride),
+	agentContract: Type.Optional(AgentContractOverride),
+	gateOn: Type.Optional(ChainGateOverride),
 });
 
 export const DynamicExpandSchema = Type.Object({
@@ -153,6 +166,8 @@ export const DynamicParallelTemplateSchema = Type.Object({
 	model: Type.Optional(Type.String({ description: "Override model for this task" })),
 	toolBudget: Type.Optional(ToolBudgetOverride),
 	acceptance: Type.Optional(AcceptanceOverride),
+	agentContract: Type.Optional(AgentContractOverride),
+	gateOn: Type.Optional(ChainGateOverride),
 }, { additionalProperties: false });
 
 export const DynamicCollectSchema = Type.Object({
@@ -179,6 +194,8 @@ export const ChainItem = Type.Object({
 	model: Type.Optional(Type.String({ description: "Override model for this step" })),
 	toolBudget: Type.Optional(ToolBudgetOverride),
 	acceptance: Type.Optional(AcceptanceOverride),
+	agentContract: Type.Optional(AgentContractOverride),
+	gateOn: Type.Optional(ChainGateOverride),
 	parallel: Type.Optional(Type.Unsafe({
 		anyOf: [
 			Type.Array(ParallelTaskSchema, { minItems: 1, description: "Tasks to run in parallel" }),
@@ -218,7 +235,7 @@ const SubagentParamsSchema = Type.Object({
 	task: Type.Optional(Type.String({ description: "Task (SINGLE mode, optional for self-contained agents)" })),
 	// Management action (when present, tool operates in management mode)
 	action: Type.Optional(Type.String({
-		description: "Management/control action only. Must be omitted for execution mode (single, parallel, or chain)."
+		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'."
@@ -236,6 +253,7 @@ const SubagentParamsSchema = Type.Object({
 	})),
 	lines: Type.Optional(Type.Integer({ minimum: 1, maximum: 500, description: "Maximum transcript lines for action='status', view='transcript'. Defaults to 80." })),
 	message: Type.Optional(Type.String({ description: "Follow-up message for action='resume' (revive paused, completed, or failed children, or reach a routed nested run) or live async guidance for action='steer'. Stopped runs are non-resumable. Use index to choose a child from multi-child runs." })),
+	steeringRecovery: Type.Optional(Type.Boolean({ description: "For action='steer', allow pause-and-revive recovery after a missed acknowledgment. Defaults true for direct tool calls; extension RPC steering forces false so callers retain exact child ownership." })),
 	additional: Type.Optional(Type.Integer({ minimum: 1, description: "Positive launches to add with action='grant-spawn-budget'. Root interactive parent with native user confirmation only; total grants cannot exceed the original configured cap." })),
 	scope: Type.Optional(Type.String({ enum: ["session", "user", "project"], description: "Scope for action='watchdog.configure'. Defaults to session to avoid persistent settings writes unless user/project is explicit." })),
 	target: Type.Optional(Type.String({ enum: ["main", "children", "child"], description: "Target for action='watchdog.configure'. Defaults to main. Use target='child' with agent for a per-agent child watchdog override." })),
@@ -292,6 +310,8 @@ const SubagentParamsSchema = Type.Object({
 	outputMode: Type.Optional(OutputModeOverride),
 	skill: Type.Optional(SkillOverride),
 	model: Type.Optional(Type.String({ description: "Override model for single agent (e.g. 'anthropic/claude-sonnet-4')" })),
+	outputSchema: Type.Optional(JsonSchemaObject),
+	agentContract: Type.Optional(AgentContractOverride),
 	acceptance: Type.Optional(AcceptanceOverride),
 });
 

package/src/extension/tool-description.ts

@@ -14,7 +14,7 @@ export const SUBAGENT_SAFETY_GUIDANCE = `SAFETY-CRITICAL SUBAGENT GUIDANCE:
 • 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.`;
 
-export const FULL_SUBAGENT_TOOL_DESCRIPTION = `Delegate to subagents or manage agent definitions.
+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.
@@ -74,7 +74,7 @@ DIAGNOSTICS:
 
 ${SUBAGENT_SAFETY_GUIDANCE}`;
 
-export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = `Delegate to subagents or manage definitions. Use exactly one mode per call.
+export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = `To delegate work, call with { agent, task }, { tasks }, or { chain }; omit action. Use action only for management/control actions listed below. Use exactly one mode per call.
 
 EXECUTE:
 • Before execution, call { action: "list" }; run only executable/non-disabled configured agents/chains.

package/src/intercom/intercom-bridge.ts

@@ -161,7 +161,7 @@ export function applyIntercomBridgeToAgent(agent: AgentConfig, bridge: IntercomB
 	if (!bridge.active || !bridge.orchestratorTarget) return agent;
 
 	const bridgeTools = ["intercom", "contact_supervisor"];
-	const tools = agent.tools
+	const tools = agent.tools && agent.tools.length > 0
 		? [...agent.tools, ...bridgeTools.filter((tool) => !agent.tools?.includes(tool))]
 		: agent.tools;
 	const instruction = bridge.instruction;