@narumitw/pi-subagents 2.1.0 → 2.1.1

package/src/stateful-guidance.ts

@@ -1,17 +1,4 @@
-import type { CompletionDelivery } from "./agents/types.js";
-
-export function createSpawnPromptGuidelines(
-	completionDelivery: CompletionDelivery,
-	blockingEnabled = true,
-): string[] {
-	const deliveryGuidance =
-		completionDelivery === "auto-resume"
-			? blockingEnabled
-				? "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or consequential independent review that covers related branches even when the final answer depends on its result; do not choose blocking parallel fan-out merely to keep delegation in the same turn."
-				: "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or consequential independent review that covers related branches even when the final answer depends on its result."
-			: blockingEnabled
-				? "With subagent_spawn completion delivery set to next-turn (the default), prefer one subagent_spawn for broad asynchronous research or consequential independent review only when the current response does not depend on its result; when it does, use subagent_spawn only with useful overlap and call subagent_await after that overlap is complete. Do not migrate new work to the deprecated subagent tool."
-				: "With subagent_spawn completion delivery set to next-turn (the default), use subagent_spawn only when the current response does not depend on its result; complete final-answer-dependent work directly because an idle root is not awakened.";
+export function createSpawnPromptGuidelines(blockingEnabled = true): string[] {
 	return [
 		"Do not use subagent_spawn for simple or critical-path work that the main agent can perform directly. The main agent retains overall planning, immediate critical-path work, integration, final verification, and the final answer.",
 		"Before one ordinary subagent_spawn, identify concrete useful non-overlapping main-agent work you can start immediately and a supported completion integration path. If none exists, perform the task directly instead of calling subagent_spawn.",
@@ -21,12 +8,8 @@ export function createSpawnPromptGuidelines(
 		"For an ordinary subagent_spawn, omit contract; use a delegation contract only when explicit acceptance, authority, evidence, or admission semantics are required.",
 		"Do not set subagent_spawn contract enforcement to enforce with requestedAuthority readPaths, writePaths, network, or secrets; those guarantees are unsupported and reject before child launch, while capabilities and tools remain enforceable.",
 		"If subagent_spawn rejects an unsupported guarantee, retry once with those fields removed or enforcement set to audit only when they were advisory; when any field is a required security boundary, stop instead of weakening it.",
-		deliveryGuidance,
-		...(completionDelivery === "auto-resume"
-			? [
-					'Track every final-answer-dependent subagent_spawn by setting completionRequirement to "required" and retaining its returned agentId or taskPath; treat interim output as progress, and synthesize only after every corresponding completion message is visible or terminal.',
-				]
-			: []),
+		"Read the current pi-subagents session-guidance message before choosing detached completion behavior. With next-turn delivery, use subagent_spawn only when the current response does not depend on its result unless useful overlap ends with an intentional subagent_await. With auto-resume delivery, final-answer-dependent detached work may continue asynchronously.",
+		'Track every final-answer-dependent subagent_spawn by setting completionRequirement to "required" and retaining its returned agentId or taskPath; treat interim output as progress, and synthesize only after every corresponding completion message is visible or terminal.',
 		"Keep ordinary review in the main agent with a review skill and deterministic checks; use subagent_spawn for detached review only when consequential independent verification has concrete parallel value.",
 		"Use a single subagent_spawn for a bounded implementation slice with clear ownership only when it can run beside the identified main-agent work.",
 		"Use a single subagent_spawn without concurrent main-agent work only for an explicit user-requested specialist model, tool profile, or isolation boundary.",

package/src/stateful-registration.ts

@@ -20,7 +20,6 @@ import type { CompletionDeliveryBroker } from "./completion-delivery.js";
 import {
 	CompletionRequirementModeSchema,
 	completionRequirementsFromBranch,
-	reconcileRequiredCompletionContext,
 } from "./completion-requirement.js";
 import type { ContextMode } from "./context.js";
 import type { CreateStatefulTransportOptions } from "./create-stateful-transport.js";
@@ -267,8 +266,6 @@ export interface StatefulSubagentRuntimeStatus {
 export interface StatefulSubagentController {
 	getCompletionDelivery(): CompletionDelivery;
 	setCompletionDelivery(value: CompletionDelivery): void;
-	setAgentCatalog(value: string): void;
-	refreshSettingsGuidance(): void;
 	getRuntimeStatus(): StatefulSubagentRuntimeStatus;
 	listAgents(includeClosed?: boolean): ManagedAgent[];
 	listRunInspection(includeClosed?: boolean): AgentRunInspectionSummary[];
@@ -293,10 +290,8 @@ export function registerStatefulSubagents(
 	const transportKind = resolveStatefulTransportKind(settings.transport);
 	let completionDelivery = resolveCompletionDelivery(settings.completionDelivery);
 	let runtimeLimits = resolveStatefulLimits(settings);
-	let agentCatalog = "";
 	let completionBroker: CompletionDeliveryBroker | undefined;
 	let peerBroker: import("./peer-communication.js").PeerCommunicationBroker | undefined;
-	let refreshSpawnToolRegistration: (() => void) | undefined;
 	let registry: AgentRegistry | undefined;
 	let persistence: AgentPersistence | undefined;
 	let sweepTimer: NodeJS.Timeout | undefined;
@@ -350,14 +345,6 @@ export function registerStatefulSubagents(
 		setCompletionDelivery(value) {
 			completionDelivery = value;
 			completionBroker?.setDelivery(value);
-			refreshSpawnToolRegistration?.();
-		},
-		setAgentCatalog(value) {
-			agentCatalog = value;
-			refreshSpawnToolRegistration?.();
-		},
-		refreshSettingsGuidance() {
-			refreshSpawnToolRegistration?.();
 		},
 		getRuntimeStatus() {
 			const counts = registry?.inspectionCounts() ?? { activeAgents: 0, retainedAgents: 0 };
@@ -617,7 +604,6 @@ export function registerStatefulSubagents(
 				if (completion.recipientId === "root") sessionBroker.enqueue(completion);
 			}
 			runtimeLimits = nextLimits;
-			refreshSpawnToolRegistration?.();
 			const sweepEveryMs = Math.max(
 				1_000,
 				Math.min(sessionSettings.idleTtlMs ?? 60 * 60 * 1000, 60_000),
@@ -642,9 +628,6 @@ export function registerStatefulSubagents(
 
 	pi.on("context", (event) => {
 		completionBroker?.onParentContext(event.messages);
-		const agents = registry?.list() ?? [];
-		const messages = reconcileRequiredCompletionContext(event.messages, agents);
-		if (messages !== event.messages) return { messages };
 	});
 
 	pi.on("agent_settled", () => {
@@ -687,14 +670,13 @@ export function registerStatefulSubagents(
 		await transition;
 	});
 
-	const baseSpawnDescription = () =>
-		`Start an addressable background subagent with an opaque agentId and canonical taskPath, plus an optional thinking level and execution budgets chosen for the task difficulty, return immediately with an agentId, and receive its completion asynchronously. Detached capacity: ${runtimeLimits.maxAgents} retained agents, ${runtimeLimits.maxActiveTurns} active turns, ${runtimeLimits.maxChildrenPerAgent} direct children per agent, and depth ${runtimeLimits.maxDepth}. Working-directory target policy: ${dependencies.getSettings?.()?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY}. This controls launch targets and protected project resources, not filesystem access or sandboxing.`;
 	const spawnTool = defineTool({
 		name: "subagent_spawn",
 		label: "Spawn Subagent",
-		description: appendAgentCatalog(baseSpawnDescription(), agentCatalog),
+		description:
+			"Start an addressable background subagent with an opaque agentId and canonical taskPath, an optional thinking level and execution budgets chosen for the task difficulty, and asynchronous completion delivery. The current bounded capacity, completion policy, working-directory policy, and available agent definitions are published in the pi-subagents session-guidance message. Working-directory policy controls launch targets and protected project resources, not filesystem access or sandboxing.",
 		promptSnippet: "Start a reusable detached subagent; completion is delivered asynchronously",
-		promptGuidelines: createSpawnPromptGuidelines(completionDelivery, blockingEnabled),
+		promptGuidelines: createSpawnPromptGuidelines(blockingEnabled),
 		parameters: grammarSafeToolObject({
 			agent: Type.String({ minLength: 1 }),
 			taskName: Type.Optional(
@@ -975,12 +957,7 @@ export function registerStatefulSubagents(
 			}
 		},
 	});
-	refreshSpawnToolRegistration = () => {
-		spawnTool.description = appendAgentCatalog(baseSpawnDescription(), agentCatalog);
-		spawnTool.promptGuidelines = createSpawnPromptGuidelines(completionDelivery, blockingEnabled);
-		pi.registerTool(spawnTool);
-	};
-	refreshSpawnToolRegistration();
+	pi.registerTool(spawnTool);
 
 	pi.registerTool({
 		name: "subagent_send",
@@ -1303,10 +1280,6 @@ async function cleanupClosedWorkspaces(
 	}
 }
 
-function appendAgentCatalog(baseDescription: string, catalog: string): string {
-	return catalog ? `${baseDescription}\n\n${catalog}` : baseDescription;
-}
-
 function result(agent: ManagedAgent, text: string) {
 	return {
 		content: [{ type: "text" as const, text }],

package/src/subagents-extension.ts

@@ -39,6 +39,10 @@ import {
 import { MAX_BLOCKING_PARALLEL_CONCURRENCY } from "./limits.js";
 import { SubagentParams } from "./params.js";
 import { renderSubagentCall, renderSubagentResult } from "./render.js";
+import {
+	registerSubagentSessionGuidance,
+	type SubagentSessionGuidanceSnapshot,
+} from "./session-guidance-contract.js";
 import {
 	consumeSubagentSettingsNotice,
 	DEFAULT_CONSULT_RESOURCE_POLICY,
@@ -80,11 +84,10 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 	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;
+	const statefulEnabled = settings?.stateful?.enabled !== false;
+	if (blockingEnabled) {
+		registerBlockingSubagent(pi, () => currentSettings, statefulEnabled, loadBlockingExecution);
+	}
 
 	pi.on("session_start", async (event, ctx) => {
 		// Preserve a one-shot migration notice from extension load while refreshing
@@ -101,9 +104,6 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 		currentCatalog = formatAgentCatalog(
 			discoverAgentCatalog(ctx.cwd, ctx.isProjectTrusted(), refreshedSettings),
 		).text;
-		refreshBlockingCatalog(currentCatalog);
-		refreshStatefulCatalog(currentCatalog);
-		refreshConsultCatalog(currentCatalog);
 		await usageRecording.startSession({
 			enabled: resolveUsageRecordingEnabled(currentSettings?.usageRecording),
 			surfaceArm: usageSurfaceArm(blockingEnabled, statefulRuntime.getRuntimeStatus().enabled),
@@ -121,7 +121,6 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 		loadTransport: dependencies.loadStatefulTransport,
 		usageRecording,
 	});
-	refreshStatefulCatalog = statefulRuntime.setAgentCatalog;
 	const getBlockingEnabled = () => blockingEnabled;
 	const getMaxParallelTasks = () => resolveBlockingMaxParallelTasks(currentSettings);
 	const getConsultResourcePolicy = () =>
@@ -144,16 +143,34 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 		dependencies.inspect,
 	);
 	if (blockingEnabled) {
-		refreshConsultCatalog = registerSubagentConsult(
-			pi,
-			{ getSettings: () => currentSettings },
-			dependencies.consult,
-		);
+		registerSubagentConsult(pi, { getSettings: () => currentSettings }, dependencies.consult);
 	}
+	const sessionGuidance = registerSubagentSessionGuidance(
+		pi,
+		(): SubagentSessionGuidanceSnapshot => {
+			const runtimeStatus = statefulRuntime.getRuntimeStatus();
+			return {
+				blockingEnabled,
+				statefulEnabled: runtimeStatus.enabled,
+				completionDelivery: runtimeStatus.completionDelivery,
+				blockingMaxParallelTasks: resolveBlockingMaxParallelTasks(currentSettings),
+				statefulLimits: runtimeStatus.limits,
+				consultationCwdPolicy: getConsultationCwdPolicy(),
+				delegationCwdPolicy: getDelegationCwdPolicy(),
+				consultResourcePolicy: getConsultResourcePolicy(),
+				agentCatalog: currentCatalog,
+			};
+		},
+		() => statefulRuntime.listAgents(),
+	);
 	registerSubagentConfigCommand(
 		pi,
 		{
 			...statefulRuntime,
+			setCompletionDelivery(value) {
+				statefulRuntime.setCompletionDelivery(value);
+				sessionGuidance.publish();
+			},
 			getBlockingEnabled,
 			getMaxParallelTasks,
 			getConsultResourcePolicy,
@@ -169,47 +186,32 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 				};
 			},
 			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;
-				}
+				sessionGuidance.publish();
 			},
 			setConsultResourcePolicy(value: ConsultResourcePolicy) {
 				currentSettings = {
 					...(currentSettings ?? {}),
 					consult: { ...(currentSettings?.consult ?? {}), resources: value },
 				};
-				refreshConsultCatalog(currentCatalog);
+				sessionGuidance.publish();
 			},
 			setConsultationCwdPolicy(value: ConsultationCwdPolicy) {
 				currentSettings = {
 					...(currentSettings ?? {}),
 					cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), consultation: value },
 				};
-				refreshConsultCatalog(currentCatalog);
+				sessionGuidance.publish();
 			},
 			setDelegationCwdPolicy(value: DelegationCwdPolicy) {
 				currentSettings = {
 					...(currentSettings ?? {}),
 					cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), delegation: value },
 				};
-				refreshBlockingCatalog(currentCatalog);
-				statefulRuntime.refreshSettingsGuidance();
+				sessionGuidance.publish();
 			},
 		},
 		configOwner,
@@ -228,9 +230,9 @@ function usageSurfaceArm(blockingEnabled: boolean, statefulEnabled: boolean): Us
 function registerBlockingSubagent(
 	pi: ExtensionAPI,
 	getSettings: () => SubagentSettings | undefined,
+	statefulEnabled: boolean,
 	loadExecution: () => Promise<BlockingExecutionModule>,
-): (catalog: string) => void {
-	let catalog = "";
+): void {
 	let deprecationWarningShown = false;
 	const activeControllers = new Set<AbortController>();
 	const activeWork = new Set<Promise<unknown>>();
@@ -245,26 +247,24 @@ function registerBlockingSubagent(
 		return cancelAndWaitForWork("Blocking subagent session replaced");
 	});
 	pi.on("session_shutdown", () => cancelAndWaitForWork("Blocking subagent session shut down"));
-	const statefulEnabled = () => getSettings()?.stateful?.enabled !== false;
 	const deprecationAlternatives = () =>
-		statefulEnabled()
+		statefulEnabled
 			? "Prefer the main agent for tightly coupled work, subagent_spawn for detached work, subagent_await for an intentional retained-agent join, or subagent_consult for bounded synchronous read-only evidence."
 			: "Prefer the main agent for tightly coupled work or subagent_consult for bounded synchronous read-only evidence; enable the background workflow before using detached alternatives.";
-	const baseDescription = () =>
-		[
-			"Deprecated compatibility tool: do not choose subagent for new work.",
-			deprecationAlternatives(),
-			"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 = () => [
-		statefulEnabled()
+	const baseDescription = [
+		"Deprecated compatibility tool: do not choose subagent for new work.",
+		deprecationAlternatives(),
+		"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.`,
+		`Configured parallel limits never exceed ${MAX_BLOCKING_PARALLEL_CONCURRENCY} concurrently started workers. The current call limit, working-directory policy, and available agent definitions are published in the pi-subagents session-guidance message.`,
+		"Working-directory policy controls launch targets and protected project resources, not filesystem access or sandboxing.",
+	].join(" ");
+	const promptGuidelines = [
+		statefulEnabled
 			? "The subagent tool is deprecated for new work; prefer the main agent, subagent_spawn with supported completion delivery, subagent_await for an intentional retained-agent join, or subagent_consult for bounded synchronous read-only evidence."
 			: "The subagent tool is deprecated for new work; prefer the main agent or subagent_consult for bounded synchronous read-only evidence, and enable the background workflow before using detached alternatives.",
 		"Use deprecated subagent only for an existing caller or an explicit user request whose blocking chain, fan-in, panel, or workflow semantics do not yet have a detached replacement.",
@@ -275,7 +275,7 @@ function registerBlockingSubagent(
 		"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.",
 		"A compatibility subagent call blocks the main agent from processing queued steering until it returns; use it only when the explicit legacy workflow justifies making Pi unavailable.",
-		`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.`,
+		"If a blocking parallel subagent call is genuinely required, keep tasks independent, stay within the configured maximum from the current pi-subagents session-guidance message, 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.",
@@ -286,10 +286,10 @@ function registerBlockingSubagent(
 	const definition: ToolDefinition<typeof SubagentParams, SubagentDetails> = {
 		name: "subagent",
 		label: "Blocking Subagent · Deprecated",
-		description: appendAgentCatalog(baseDescription(), catalog),
+		description: baseDescription,
 		promptSnippet:
 			"Deprecated blocking subagent compatibility tool; prefer detached or read-only alternatives.",
-		promptGuidelines: promptGuidelines(),
+		promptGuidelines,
 		parameters: SubagentParams,
 
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
@@ -303,7 +303,7 @@ function registerBlockingSubagent(
 				if (!deprecationWarningShown && ctx.hasUI) {
 					deprecationWarningShown = true;
 					ctx.ui.notify(
-						statefulEnabled()
+						statefulEnabled
 							? "subagent is deprecated for new work. Prefer the main agent, subagent_spawn with completion delivery, subagent_await for an intentional join, or subagent_consult for synchronous read-only evidence."
 							: "subagent is deprecated for new work. Prefer the main agent or subagent_consult; enable the background workflow before using detached alternatives.",
 						"warning",
@@ -352,14 +352,4 @@ function registerBlockingSubagent(
 		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;
 }