@narumitw/pi-subagents 2.0.1 → 2.0.2

package/src/subagents-extension.ts

@@ -0,0 +1,307 @@
+/**
+ * Subagent Tool - Delegate tasks to specialized agents
+ *
+ * Spawns a separate `pi` process for each subagent invocation,
+ * giving it an isolated context window.
+ *
+ * Supports blocking single, parallel, chain, workflow, and panel modes.
+ *
+ * Uses JSON mode to capture structured output from subagents.
+ */
+
+import {
+	CONFIG_DIR_NAME,
+	type ExtensionAPI,
+	type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { discoverAgentCatalog, formatAgentCatalog } from "./agents/catalog.js";
+import type {
+	ConsultationCwdPolicy,
+	ConsultResourcePolicy,
+	DelegationCwdPolicy,
+	SubagentSettings,
+} from "./agents/types.js";
+import { cachedModuleLoader, throwIfAborted } from "./cached-module-loader.js";
+import { renderCompletionMessage, SUBAGENT_COMPLETION_MESSAGE_TYPE } from "./completion-render.js";
+import {
+	type ConfigRegistrationDependencies,
+	registerSubagentConfigCommand,
+	registerSubagentConfigLifecycle,
+} from "./config-registration.js";
+import {
+	type ConsultRegistrationDependencies,
+	registerSubagentConsult,
+} from "./consult-registration.js";
+import {
+	type InspectRegistrationDependencies,
+	registerSubagentInspect,
+} from "./inspect-registration.js";
+import { MAX_BLOCKING_PARALLEL_CONCURRENCY } from "./limits.js";
+import { SubagentParams } from "./params.js";
+import { renderSubagentCall, renderSubagentResult } from "./render.js";
+import type { SubagentDetails } from "./runner.js";
+import {
+	consumeSubagentSettingsNotice,
+	DEFAULT_CONSULT_RESOURCE_POLICY,
+	DEFAULT_CONSULTATION_CWD_POLICY,
+	DEFAULT_DELEGATION_CWD_POLICY,
+	inspectSubagentSettings,
+	readSubagentSettings,
+	resolveBlockingMaxParallelTasks,
+} from "./settings-reader.js";
+import { registerStatefulSubagents } from "./stateful-registration.js";
+import type { SubagentTransport } from "./transport.js";
+
+type BlockingExecutionModule = Pick<typeof import("./execution.js"), "executeSubagent">;
+
+export interface SubagentsDependencies {
+	loadBlockingExecution?: () => Promise<BlockingExecutionModule>;
+	loadStatefulTransport?: () => Promise<SubagentTransport>;
+	config?: ConfigRegistrationDependencies;
+	consult?: ConsultRegistrationDependencies;
+	inspect?: InspectRegistrationDependencies;
+}
+
+export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies = {}) {
+	pi.registerMessageRenderer(SUBAGENT_COMPLETION_MESSAGE_TYPE, renderCompletionMessage);
+	const loadBlockingExecution = cachedModuleLoader(
+		dependencies.loadBlockingExecution ?? (() => import("./execution.js")),
+	);
+	const configOwner = registerSubagentConfigLifecycle(pi);
+	const settings = readSubagentSettings();
+	let currentSettings: SubagentSettings | undefined = settings;
+	let currentCatalog = "";
+	const blockingEnabled = settings?.blocking?.enabled !== false;
+	const refreshBlockingCatalog = blockingEnabled
+		? registerBlockingSubagent(pi, () => currentSettings, loadBlockingExecution)
+		: () => undefined;
+	let refreshStatefulCatalog: (catalog: string) => void = () => undefined;
+	let refreshConsultCatalog: (catalog: string) => void = () => undefined;
+
+	pi.on("session_start", (_event, ctx) => {
+		// Preserve a one-shot migration notice from extension load while refreshing
+		// validation against settings that may have changed before this session.
+		const loadNotice = consumeSubagentSettingsNotice();
+		const refreshedSettings = readSubagentSettings();
+		const refreshedNotice = consumeSubagentSettingsNotice();
+		if (!inspectSubagentSettings().error) currentSettings = refreshedSettings;
+		const notice = [
+			...new Set([loadNotice, refreshedNotice].filter((value) => value !== undefined)),
+		].join("\n");
+		if (notice) ctx.ui.notify(notice, "warning");
+
+		currentCatalog = formatAgentCatalog(
+			discoverAgentCatalog(ctx.cwd, ctx.isProjectTrusted(), refreshedSettings),
+		).text;
+		refreshBlockingCatalog(currentCatalog);
+		refreshStatefulCatalog(currentCatalog);
+		refreshConsultCatalog(currentCatalog);
+	});
+
+	const statefulRuntime = registerStatefulSubagents(pi, {
+		blockingEnabled,
+		settings: settings?.stateful,
+		getSettings: () => currentSettings,
+		loadTransport: dependencies.loadStatefulTransport,
+	});
+	refreshStatefulCatalog = statefulRuntime.setAgentCatalog;
+	const getBlockingEnabled = () => blockingEnabled;
+	const getMaxParallelTasks = () => resolveBlockingMaxParallelTasks(currentSettings);
+	const getConsultResourcePolicy = () =>
+		currentSettings?.consult?.resources ?? DEFAULT_CONSULT_RESOURCE_POLICY;
+	const getConsultationCwdPolicy = () =>
+		currentSettings?.cwdPolicy?.consultation ?? DEFAULT_CONSULTATION_CWD_POLICY;
+	const getDelegationCwdPolicy = () =>
+		currentSettings?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY;
+	registerSubagentInspect(
+		pi,
+		{
+			...statefulRuntime,
+			getBlockingEnabled,
+			getMaxParallelTasks,
+			getConsultResourcePolicy,
+			getConsultationCwdPolicy,
+			getDelegationCwdPolicy,
+		},
+		dependencies.inspect,
+	);
+	if (blockingEnabled) {
+		refreshConsultCatalog = registerSubagentConsult(
+			pi,
+			{ getSettings: () => currentSettings },
+			dependencies.consult,
+		);
+	}
+	registerSubagentConfigCommand(
+		pi,
+		{
+			...statefulRuntime,
+			getBlockingEnabled,
+			getMaxParallelTasks,
+			getConsultResourcePolicy,
+			getConsultationCwdPolicy,
+			getDelegationCwdPolicy,
+			setMaxParallelTasks(value: number) {
+				const previousSettings = currentSettings;
+				currentSettings = {
+					...(currentSettings ?? {}),
+					blocking: { ...(currentSettings?.blocking ?? {}), maxParallelTasks: value },
+				};
+				try {
+					refreshBlockingCatalog(currentCatalog);
+				} catch (applyError) {
+					currentSettings = previousSettings;
+					try {
+						refreshBlockingCatalog(currentCatalog);
+					} catch (rollbackError) {
+						throw new AggregateError(
+							[applyError, rollbackError],
+							"Failed to apply and roll back the parallel-worker limit",
+						);
+					}
+					throw applyError;
+				}
+			},
+			setConsultResourcePolicy(value: ConsultResourcePolicy) {
+				currentSettings = {
+					...(currentSettings ?? {}),
+					consult: { ...(currentSettings?.consult ?? {}), resources: value },
+				};
+				refreshConsultCatalog(currentCatalog);
+			},
+			setConsultationCwdPolicy(value: ConsultationCwdPolicy) {
+				currentSettings = {
+					...(currentSettings ?? {}),
+					cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), consultation: value },
+				};
+				refreshConsultCatalog(currentCatalog);
+			},
+			setDelegationCwdPolicy(value: DelegationCwdPolicy) {
+				currentSettings = {
+					...(currentSettings ?? {}),
+					cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), delegation: value },
+				};
+				refreshBlockingCatalog(currentCatalog);
+				statefulRuntime.refreshSettingsGuidance();
+			},
+		},
+		configOwner,
+		dependencies.config,
+	);
+}
+
+function registerBlockingSubagent(
+	pi: ExtensionAPI,
+	getSettings: () => SubagentSettings | undefined,
+	loadExecution: () => Promise<BlockingExecutionModule>,
+): (catalog: string) => void {
+	let catalog = "";
+	const activeControllers = new Set<AbortController>();
+	const activeWork = new Set<Promise<unknown>>();
+	const cancelAndWaitForWork = async (reason: string) => {
+		for (const controller of activeControllers) {
+			controller.abort(new DOMException(reason, "AbortError"));
+		}
+		await Promise.allSettled([...activeWork]);
+	};
+	pi.on("session_start", () => cancelAndWaitForWork("Blocking subagent session replaced"));
+	pi.on("session_shutdown", () => cancelAndWaitForWork("Blocking subagent session shut down"));
+	const baseDescription = () =>
+		[
+			"Run specialized subagents as a blocking operation with isolated contexts.",
+			"The call blocks the main agent until every worker and optional aggregator finishes, so queued steering waits.",
+			"Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder), workflow (named dependency tasks with optional capability routing), or panel (independent reviewers plus evidence-preserving synthesis).",
+			"Parallel mode may include an aggregator fan-in step; workflow mode validates dependencies, authority, artifacts, scope conflicts, retries, and hedging before scheduling. Use subagent_consult instead for one synchronous child that must be executor-constrained to read-only tools.",
+			'Default agent scope is "user" (from ~/.pi/agent/agents).',
+			`To enable project-local agents in ${CONFIG_DIR_NAME}/agents, pass agentScope: "both" (or "project") as a top-level argument for that call.`,
+			`Maximum parallel worker tasks per call: ${resolveBlockingMaxParallelTasks(getSettings())}. Parallel execution starts at most ${MAX_BLOCKING_PARALLEL_CONCURRENCY} workers at once.`,
+			`Working-directory target policy: ${getSettings()?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY}. This controls launch targets and protected project resources, not filesystem access or sandboxing.`,
+		].join(" ");
+	const promptGuidelines = () => [
+		"Use subagent only when delegation fits; the main agent should decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
+		"The main agent retains overall planning, immediate critical-path work, integration, final verification, and the final answer.",
+		"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work the main agent can perform directly.",
+		"One ordinary implementation worker should not replace work the main agent can perform directly; use a blocking single only when intentional synchronous isolation or a user-requested specialist justifies waiting.",
+		"Keep ordinary planning in the main agent, or use explicit workflow mode when a genuine dependency graph requires caller-authored orchestration.",
+		"Keep ordinary review in the main agent with a review skill and deterministic checks; reserve panel mode or custom verifier agents for consequential independent verification.",
+		"Use the blocking subagent tool only when delegated outputs are required before the main agent's next action and waiting is intentional; the main agent cannot process queued steering until the call returns.",
+		"Use a blocking subagent single, parallel, chain, workflow, panel, or fan-in call only when synchronous context or output isolation is worth making the main agent unavailable while it runs.",
+		`If a blocking parallel subagent call is genuinely required, keep tasks independent, stay within the configured max ${resolveBlockingMaxParallelTasks(getSettings())}, and avoid write-heavy implementation touching the same files or shared state.`,
+		"For parallel subagent calls, omit the aggregator key entirely unless a fan-in step is required; do not send null, empty strings, or an empty object for unused optional fields.",
+		"Use workflow mode for explicit dependencies or capability routing; declare read/write or ownership scopes, require structured-v2 artifacts when downstream tasks consume them, and use retry or hedging only with the required side-effect contract.",
+		"Use panel mode only for consequential review or research that benefits from at least two independent reviewers and one bounded synthesis; agreement is not proof, dissent and blocking objections remain visible, and simple or latency-sensitive work should not use a panel.",
+		'Do not use subagent with project-local agents unless the user explicitly wants project agents or sets agentScope to "project" or "both"; keep confirmation enabled for untrusted repositories.',
+		"When using subagent, write self-contained tasks with file paths, context, expected output, and whether the subagent may edit files.",
+		"Set subagent timeoutMs to the shortest realistic work deadline for the task difficulty, just as thinkingLevel should match reasoning difficulty; split oversized tasks instead of extending the deadline merely to compensate for broad scope. Use totalTimeoutMs to cap an entire blocking workflow, idleTimeoutMs for stalled work, and maxTurns or maxToolCalls to stop repeated work without progress. Every budget stop preserves a bounded checkpoint and may make one separately bounded summary attempt.",
+	];
+	const definition: ToolDefinition<typeof SubagentParams, SubagentDetails> = {
+		name: "subagent",
+		label: "Blocking Subagent",
+		description: appendAgentCatalog(baseDescription(), catalog),
+		promptSnippet:
+			"Run blocking isolated subagents only when their outputs are required before the main agent can continue.",
+		promptGuidelines: promptGuidelines(),
+		parameters: SubagentParams,
+
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			const lifecycleController = new AbortController();
+			activeControllers.add(lifecycleController);
+			const effectiveSignal = signal
+				? AbortSignal.any([signal, lifecycleController.signal])
+				: lifecycleController.signal;
+			const work = (async () => {
+				throwIfAborted(effectiveSignal, "Blocking subagent execution was cancelled");
+				let executionModule: BlockingExecutionModule;
+				try {
+					executionModule = await loadExecution();
+				} catch (error) {
+					throwIfAborted(
+						effectiveSignal,
+						"Blocking subagent execution was cancelled while loading",
+					);
+					throw error;
+				}
+				throwIfAborted(effectiveSignal, "Blocking subagent execution was cancelled while loading");
+				return executionModule.executeSubagent(
+					toolCallId,
+					params,
+					effectiveSignal,
+					onUpdate,
+					ctx,
+					getSettings(),
+				);
+			})();
+			activeWork.add(work);
+			try {
+				return await work;
+			} finally {
+				activeControllers.delete(lifecycleController);
+				activeWork.delete(work);
+			}
+		},
+
+		renderCall(args, theme) {
+			return renderSubagentCall(args, theme);
+		},
+
+		renderResult(result, options, theme) {
+			return renderSubagentResult(result, options, theme);
+		},
+	};
+	pi.registerTool<typeof SubagentParams, SubagentDetails>(definition);
+	pi.on("tool_result", (event) => {
+		if (event.toolName !== "subagent") return;
+		if ((event.details as (SubagentDetails & { isError?: boolean }) | undefined)?.isError)
+			return { isError: true };
+	});
+	return (nextCatalog: string) => {
+		catalog = nextCatalog;
+		definition.description = appendAgentCatalog(baseDescription(), catalog);
+		definition.promptGuidelines = promptGuidelines();
+		pi.registerTool<typeof SubagentParams, SubagentDetails>(definition);
+	};
+}
+
+function appendAgentCatalog(baseDescription: string, catalog: string): string {
+	return catalog ? `${baseDescription}\n\n${catalog}` : baseDescription;
+}

package/src/subagents.ts

@@ -1,311 +1,3 @@
-/**
- * Subagent Tool - Delegate tasks to specialized agents
- *
- * Spawns a separate `pi` process for each subagent invocation,
- * giving it an isolated context window.
- *
- * Supports blocking single, parallel, chain, workflow, and panel modes.
- *
- * Uses JSON mode to capture structured output from subagents.
- */
-
-import {
-	CONFIG_DIR_NAME,
-	type ExtensionAPI,
-	type ToolDefinition,
-} from "@earendil-works/pi-coding-agent";
-import { discoverAgentCatalog, formatAgentCatalog } from "./agents/catalog.js";
-import type {
-	ConsultationCwdPolicy,
-	ConsultResourcePolicy,
-	DelegationCwdPolicy,
-	SubagentSettings,
-} from "./agents/types.js";
-import { cachedModuleLoader, throwIfAborted } from "./cached-module-loader.js";
-import { renderCompletionMessage, SUBAGENT_COMPLETION_MESSAGE_TYPE } from "./completion-render.js";
-import {
-	type ConfigRegistrationDependencies,
-	registerSubagentConfigCommand,
-	registerSubagentConfigLifecycle,
-} from "./config-registration.js";
-import {
-	type ConsultRegistrationDependencies,
-	registerSubagentConsult,
-} from "./consult-registration.js";
-import {
-	type InspectRegistrationDependencies,
-	registerSubagentInspect,
-} from "./inspect-registration.js";
-import { MAX_BLOCKING_PARALLEL_CONCURRENCY } from "./limits.js";
-import { SubagentParams } from "./params.js";
-import { renderSubagentCall, renderSubagentResult } from "./render.js";
-import type { SubagentDetails } from "./runner.js";
-import {
-	consumeSubagentSettingsNotice,
-	DEFAULT_CONSULT_RESOURCE_POLICY,
-	DEFAULT_CONSULTATION_CWD_POLICY,
-	DEFAULT_DELEGATION_CWD_POLICY,
-	inspectSubagentSettings,
-	readSubagentSettings,
-	resolveBlockingMaxParallelTasks,
-} from "./settings.js";
-import { registerStatefulSubagents } from "./stateful.js";
-import type { SubagentTransport } from "./transport.js";
-
-type BlockingExecutionModule = Pick<typeof import("./execution.js"), "executeSubagent">;
-
-export interface SubagentsDependencies {
-	loadBlockingExecution?: () => Promise<BlockingExecutionModule>;
-	loadStatefulTransport?: () => Promise<SubagentTransport>;
-	config?: ConfigRegistrationDependencies;
-	consult?: ConsultRegistrationDependencies;
-	inspect?: InspectRegistrationDependencies;
-}
-
-export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies = {}) {
-	pi.registerMessageRenderer(SUBAGENT_COMPLETION_MESSAGE_TYPE, renderCompletionMessage);
-	const loadBlockingExecution = cachedModuleLoader(
-		dependencies.loadBlockingExecution ?? (() => import("./execution.js")),
-	);
-	const configOwner = registerSubagentConfigLifecycle(pi);
-	const settings = readSubagentSettings();
-	let currentSettings: SubagentSettings | undefined = settings;
-	let currentCatalog = "";
-	const blockingEnabled = settings?.blocking?.enabled !== false;
-	const refreshBlockingCatalog = blockingEnabled
-		? registerBlockingSubagent(pi, () => currentSettings, loadBlockingExecution)
-		: () => undefined;
-	let refreshStatefulCatalog: (catalog: string) => void = () => undefined;
-	let refreshConsultCatalog: (catalog: string) => void = () => undefined;
-
-	pi.on("session_start", (_event, ctx) => {
-		// Preserve a one-shot migration notice from extension load while refreshing
-		// validation against settings that may have changed before this session.
-		const loadNotice = consumeSubagentSettingsNotice();
-		const refreshedSettings = readSubagentSettings();
-		const refreshedNotice = consumeSubagentSettingsNotice();
-		if (!inspectSubagentSettings().error) currentSettings = refreshedSettings;
-		const notice = [
-			...new Set([loadNotice, refreshedNotice].filter((value) => value !== undefined)),
-		].join("\n");
-		if (notice) ctx.ui.notify(notice, "warning");
-
-		currentCatalog = formatAgentCatalog(
-			discoverAgentCatalog(ctx.cwd, ctx.isProjectTrusted(), refreshedSettings),
-		).text;
-		refreshBlockingCatalog(currentCatalog);
-		refreshStatefulCatalog(currentCatalog);
-		refreshConsultCatalog(currentCatalog);
-	});
-
-	const statefulRuntime = registerStatefulSubagents(pi, {
-		blockingEnabled,
-		settings: settings?.stateful,
-		getSettings: () => currentSettings,
-		loadTransport: dependencies.loadStatefulTransport,
-	});
-	refreshStatefulCatalog = statefulRuntime.setAgentCatalog;
-	const getBlockingEnabled = () => blockingEnabled;
-	const getMaxParallelTasks = () => resolveBlockingMaxParallelTasks(currentSettings);
-	const getConsultResourcePolicy = () =>
-		currentSettings?.consult?.resources ?? DEFAULT_CONSULT_RESOURCE_POLICY;
-	const getConsultationCwdPolicy = () =>
-		currentSettings?.cwdPolicy?.consultation ?? DEFAULT_CONSULTATION_CWD_POLICY;
-	const getDelegationCwdPolicy = () =>
-		currentSettings?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY;
-	registerSubagentInspect(
-		pi,
-		{
-			...statefulRuntime,
-			getBlockingEnabled,
-			getMaxParallelTasks,
-			getConsultResourcePolicy,
-			getConsultationCwdPolicy,
-			getDelegationCwdPolicy,
-		},
-		dependencies.inspect,
-	);
-	if (blockingEnabled) {
-		refreshConsultCatalog = registerSubagentConsult(
-			pi,
-			{ getSettings: () => currentSettings },
-			dependencies.consult,
-		);
-	}
-	registerSubagentConfigCommand(
-		pi,
-		{
-			...statefulRuntime,
-			getBlockingEnabled,
-			getMaxParallelTasks,
-			getConsultResourcePolicy,
-			getConsultationCwdPolicy,
-			getDelegationCwdPolicy,
-			setMaxParallelTasks(value: number) {
-				const previousSettings = currentSettings;
-				currentSettings = {
-					...(currentSettings ?? {}),
-					blocking: { ...(currentSettings?.blocking ?? {}), maxParallelTasks: value },
-				};
-				try {
-					refreshBlockingCatalog(currentCatalog);
-				} catch (applyError) {
-					currentSettings = previousSettings;
-					try {
-						refreshBlockingCatalog(currentCatalog);
-					} catch (rollbackError) {
-						throw new AggregateError(
-							[applyError, rollbackError],
-							"Failed to apply and roll back the parallel-worker limit",
-						);
-					}
-					throw applyError;
-				}
-			},
-			setConsultResourcePolicy(value: ConsultResourcePolicy) {
-				currentSettings = {
-					...(currentSettings ?? {}),
-					consult: { ...(currentSettings?.consult ?? {}), resources: value },
-				};
-				refreshConsultCatalog(currentCatalog);
-			},
-			setConsultationCwdPolicy(value: ConsultationCwdPolicy) {
-				currentSettings = {
-					...(currentSettings ?? {}),
-					cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), consultation: value },
-				};
-				refreshConsultCatalog(currentCatalog);
-			},
-			setDelegationCwdPolicy(value: DelegationCwdPolicy) {
-				currentSettings = {
-					...(currentSettings ?? {}),
-					cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), delegation: value },
-				};
-				refreshBlockingCatalog(currentCatalog);
-				statefulRuntime.refreshSettingsGuidance();
-			},
-		},
-		configOwner,
-		dependencies.config,
-	);
-}
-
-function registerBlockingSubagent(
-	pi: ExtensionAPI,
-	getSettings: () => SubagentSettings | undefined,
-	loadExecution: () => Promise<BlockingExecutionModule>,
-): (catalog: string) => void {
-	let catalog = "";
-	const activeControllers = new Set<AbortController>();
-	const activeWork = new Set<Promise<unknown>>();
-	const cancelAndWaitForWork = async (reason: string) => {
-		for (const controller of activeControllers) {
-			controller.abort(new DOMException(reason, "AbortError"));
-		}
-		await Promise.allSettled([...activeWork]);
-	};
-	pi.on("session_start", () => cancelAndWaitForWork("Blocking subagent session replaced"));
-	pi.on("session_shutdown", () => cancelAndWaitForWork("Blocking subagent session shut down"));
-	const baseDescription = () =>
-		[
-			"Run specialized subagents as a blocking operation with isolated contexts.",
-			"The call blocks the main agent until every worker and optional aggregator finishes, so queued steering waits.",
-			"Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder), workflow (named dependency tasks with optional capability routing), or panel (independent reviewers plus evidence-preserving synthesis).",
-			"Parallel mode may include an aggregator fan-in step; workflow mode validates dependencies, authority, artifacts, scope conflicts, retries, and hedging before scheduling. Use subagent_consult instead for one synchronous child that must be executor-constrained to read-only tools.",
-			'Default agent scope is "user" (from ~/.pi/agent/agents).',
-			`To enable project-local agents in ${CONFIG_DIR_NAME}/agents, pass agentScope: "both" (or "project") as a top-level argument for that call.`,
-			`Maximum parallel worker tasks per call: ${resolveBlockingMaxParallelTasks(getSettings())}. Parallel execution starts at most ${MAX_BLOCKING_PARALLEL_CONCURRENCY} workers at once.`,
-			`Working-directory target policy: ${getSettings()?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY}. This controls launch targets and protected project resources, not filesystem access or sandboxing.`,
-		].join(" ");
-	const promptGuidelines = () => [
-		"Use subagent only when delegation fits; the main agent should decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
-		"The main agent retains overall planning, immediate critical-path work, integration, final verification, and the final answer.",
-		"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work the main agent can perform directly.",
-		"One ordinary implementation worker should not replace work the main agent can perform directly; use a blocking single only when intentional synchronous isolation or a user-requested specialist justifies waiting.",
-		"Keep ordinary planning in the main agent, or use explicit workflow mode when a genuine dependency graph requires caller-authored orchestration.",
-		"Keep ordinary review in the main agent with a review skill and deterministic checks; reserve panel mode or custom verifier agents for consequential independent verification.",
-		"Use the blocking subagent tool only when delegated outputs are required before the main agent's next action and waiting is intentional; the main agent cannot process queued steering until the call returns.",
-		"Use a blocking subagent single, parallel, chain, workflow, panel, or fan-in call only when synchronous context or output isolation is worth making the main agent unavailable while it runs.",
-		`If a blocking parallel subagent call is genuinely required, keep tasks independent, stay within the configured max ${resolveBlockingMaxParallelTasks(getSettings())}, and avoid write-heavy implementation touching the same files or shared state.`,
-		"For parallel subagent calls, omit the aggregator key entirely unless a fan-in step is required; do not send null, empty strings, or an empty object for unused optional fields.",
-		"Use workflow mode for explicit dependencies or capability routing; declare read/write or ownership scopes, require structured-v2 artifacts when downstream tasks consume them, and use retry or hedging only with the required side-effect contract.",
-		"Use panel mode only for consequential review or research that benefits from at least two independent reviewers and one bounded synthesis; agreement is not proof, dissent and blocking objections remain visible, and simple or latency-sensitive work should not use a panel.",
-		'Do not use subagent with project-local agents unless the user explicitly wants project agents or sets agentScope to "project" or "both"; keep confirmation enabled for untrusted repositories.',
-		"When using subagent, write self-contained tasks with file paths, context, expected output, and whether the subagent may edit files.",
-		"Set subagent timeoutMs to the shortest realistic work deadline for the task difficulty, just as thinkingLevel should match reasoning difficulty; split oversized tasks instead of extending the deadline merely to compensate for broad scope. Use totalTimeoutMs to cap an entire blocking workflow, idleTimeoutMs for stalled work, and maxTurns or maxToolCalls to stop repeated work without progress. Every budget stop preserves a bounded checkpoint and may make one separately bounded summary attempt.",
-	];
-	const definition: ToolDefinition<typeof SubagentParams, SubagentDetails> = {
-		name: "subagent",
-		label: "Blocking Subagent",
-		description: appendAgentCatalog(baseDescription(), catalog),
-		promptSnippet:
-			"Run blocking isolated subagents only when their outputs are required before the main agent can continue.",
-		promptGuidelines: promptGuidelines(),
-		parameters: SubagentParams,
-
-		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			const lifecycleController = new AbortController();
-			activeControllers.add(lifecycleController);
-			const effectiveSignal = signal
-				? AbortSignal.any([signal, lifecycleController.signal])
-				: lifecycleController.signal;
-			const work = (async () => {
-				throwIfAborted(effectiveSignal, "Blocking subagent execution was cancelled");
-				let executionModule: BlockingExecutionModule;
-				try {
-					executionModule = await loadExecution();
-				} catch (error) {
-					throwIfAborted(
-						effectiveSignal,
-						"Blocking subagent execution was cancelled while loading",
-					);
-					throw error;
-				}
-				throwIfAborted(effectiveSignal, "Blocking subagent execution was cancelled while loading");
-				return executionModule.executeSubagent(
-					toolCallId,
-					params,
-					effectiveSignal,
-					onUpdate,
-					ctx,
-					getSettings(),
-				);
-			})();
-			activeWork.add(work);
-			try {
-				return await work;
-			} finally {
-				activeControllers.delete(lifecycleController);
-				activeWork.delete(work);
-			}
-		},
-
-		renderCall(args, theme) {
-			return renderSubagentCall(args, theme);
-		},
-
-		renderResult(result, options, theme) {
-			return renderSubagentResult(result, options, theme);
-		},
-	};
-	pi.registerTool<typeof SubagentParams, SubagentDetails>(definition);
-	pi.on("tool_result", (event) => {
-		if (event.toolName !== "subagent") return;
-		if ((event.details as (SubagentDetails & { isError?: boolean }) | undefined)?.isError)
-			return { isError: true };
-	});
-	return (nextCatalog: string) => {
-		catalog = nextCatalog;
-		definition.description = appendAgentCatalog(baseDescription(), catalog);
-		definition.promptGuidelines = promptGuidelines();
-		pi.registerTool<typeof SubagentParams, SubagentDetails>(definition);
-	};
-}
-
-function appendAgentCatalog(baseDescription: string, catalog: string): string {
-	return catalog ? `${baseDescription}\n\n${catalog}` : baseDescription;
-}
-
 export { parsePositiveInteger } from "./execution/runtime-policy.js";
 export { buildPiArgs } from "./pi-args.js";
 export {
@@ -336,4 +28,5 @@ export {
 	updateDelegationWorkflowSetting,
 	updateStatefulLimitSetting,
 } from "./settings.js";
+export { default, type SubagentsDependencies } from "./subagents-extension.js";
 export { formatTokens, formatUsageStats } from "./usage-format.js";