@narumitw/pi-subagents 0.40.1 → 0.41.0

package/README.md

@@ -58,6 +58,12 @@ The available tools are:
 - `subagent` — delegate blocking single, parallel, fan-in, or chained batch work. The main agent cannot process queued steering until the call returns.
 - `subagent_spawn` and related lifecycle tools — when enabled, start reusable detached work, return immediately, and receive bounded completion messages automatically.
 
+After each session starts, both delegation tools include a bounded parent-facing catalog of the agents
+available in that session. Entries show the source (`built-in`, `user`, or `project`) and the
+`agentScope` needed to invoke them; the `agent` parameters remain unconstrained strings for cwd and
+scope flexibility. The catalog is rebuilt on `/reload` or the next session start, and omitted entries
+are reported explicitly when the catalog exceeds its metadata bounds.
+
 Choose the API by lifecycle:
 
 | Need | Use |
@@ -89,6 +95,17 @@ When registered, the blocking `subagent` tool advertises only blocking guidance.
 are registered, `subagent_spawn` adds detached guidance for the active completion-delivery policy.
 Changing the policy through `/subagents settings` refreshes that guidance immediately.
 
+The same descriptions also advertise the current agent catalog automatically; no preliminary list call is
+needed. Built-ins and user agents appear under the default `agentScope: "user"`. Trusted project
+agents appear separately and explicitly require `agentScope: "project"` or `"both"`; project-authored
+names and descriptions are not read into metadata for untrusted projects. If a project definition
+shares a name with a user or built-in definition, the user version is the default and the project
+version is used only for `"project"`/`"both"`. A user override of a built-in also shows the
+built-in fallback available with `agentScope: "project"`; `"both"` keeps the user definition. The
+catalog is bounded and reports its omission count; metadata discovery also caps files and bytes read
+per scope. Refreshed metadata replaces the previous session's catalog rather than accumulating stale
+entries.
+
 Count-selection guidance:
 
 - Use **no subagent** for simple answers, quick targeted edits, latency-sensitive one-step work, or
@@ -429,8 +446,10 @@ test coverage, and migration risks. Report PASS/FAIL/PARTIAL with evidence.
 ```
 
 `agentScope` is a top-level tool argument supplied per invocation. It is not a setting in
-`~/.pi/agent/pi-subagents.json` and does not belong in agent frontmatter. The scope selects which
-custom agent directories are loaded; built-in agents remain available in every scope:
+`~/.pi/agent/pi-subagents.json` and does not belong in agent frontmatter. The parent-facing tool
+metadata discovers these definitions after session start and labels their source and required scope.
+Edit agent files and run `/reload` (or start a new session) to refresh the catalog; there is no live
+filesystem watcher. The scope selects which custom agent directories are loaded; built-in agents remain available in every scope:
 
 | `agentScope` | Custom agents loaded |
 | --- | --- |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "0.40.1",
+	"version": "0.41.0",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",

package/src/agents.ts

@@ -139,40 +139,109 @@ function workerSystemPrompt(): string {
 export interface AgentDiscoveryResult {
 	agents: AgentConfig[];
 	projectAgentsDir: string | null;
+	omittedAgentDefinitions?: number;
+	metadataDiscoveryIncomplete?: boolean;
 }
 
-function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
-	const agents: AgentConfig[] = [];
+export interface AgentDiscoveryOptions {
+	maxFiles?: number;
+	maxFileBytes?: number;
+	maxTotalBytes?: number;
+}
+
+interface LoadedAgents {
+	agents: AgentConfig[];
+	omittedAgentDefinitions: number;
+	metadataDiscoveryIncomplete: boolean;
+}
 
-	if (!fs.existsSync(dir)) {
-		return agents;
+function readFileBoundedSync(
+	filePath: string,
+	maxBytes: number | undefined,
+): { content?: string; bytes: number; limited: boolean } {
+	if (maxBytes === undefined) {
+		try {
+			const content = fs.readFileSync(filePath, "utf-8");
+			return { content, bytes: Buffer.byteLength(content), limited: false };
+		} catch {
+			return { bytes: 0, limited: false };
+		}
 	}
 
+	const readLimit = Math.max(0, maxBytes);
+	let fd: number | undefined;
+	try {
+		fd = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+		if (!fs.fstatSync(fd).isFile()) return { bytes: 0, limited: false };
+		const buffer = Buffer.allocUnsafe(readLimit + 1);
+		let offset = 0;
+		while (offset < buffer.length) {
+			const bytesRead = fs.readSync(fd, buffer, offset, buffer.length - offset, null);
+			if (bytesRead === 0) break;
+			offset += bytesRead;
+		}
+		if (offset > readLimit) return { bytes: offset, limited: true };
+		return { content: buffer.subarray(0, offset).toString("utf-8"), bytes: offset, limited: false };
+	} catch {
+		return { bytes: 0, limited: false };
+	} finally {
+		if (fd !== undefined) fs.closeSync(fd);
+	}
+}
+
+function loadAgentsFromDir(
+	dir: string,
+	source: "user" | "project",
+	options: AgentDiscoveryOptions = {},
+): LoadedAgents {
+	const agents: AgentConfig[] = [];
+	let omittedAgentDefinitions = 0;
+
 	let entries: fs.Dirent[];
 	try {
 		entries = fs.readdirSync(dir, { withFileTypes: true });
-	} catch {
-		return agents;
+	} catch (error) {
+		return {
+			agents,
+			omittedAgentDefinitions,
+			metadataDiscoveryIncomplete: (error as NodeJS.ErrnoException).code !== "ENOENT",
+		};
 	}
 
-	for (const entry of entries) {
-		if (!entry.name.endsWith(".md")) continue;
-		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+	const agentEntries = entries
+		.filter((entry) => entry.name.endsWith(".md"))
+		.filter((entry) => entry.isFile() || entry.isSymbolicLink());
+	let totalBytes = 0;
 
+	for (const [index, entry] of agentEntries.entries()) {
+		if (options.maxFiles !== undefined && index >= options.maxFiles) {
+			omittedAgentDefinitions += agentEntries.length - index;
+			break;
+		}
 		const filePath = path.join(dir, entry.name);
-		let content: string;
-		try {
-			content = fs.readFileSync(filePath, "utf-8");
-		} catch {
+		const remainingBytes =
+			options.maxTotalBytes === undefined ? undefined : options.maxTotalBytes - totalBytes;
+		if (remainingBytes !== undefined && remainingBytes <= 0) {
+			omittedAgentDefinitions++;
 			continue;
 		}
-
-		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
-
-		if (!frontmatter.name || !frontmatter.description) {
+		const maxBytes =
+			options.maxFileBytes === undefined
+				? remainingBytes
+				: remainingBytes === undefined
+					? options.maxFileBytes
+					: Math.min(options.maxFileBytes, remainingBytes);
+		const loaded = readFileBoundedSync(filePath, maxBytes);
+		totalBytes += Math.min(loaded.bytes, maxBytes ?? loaded.bytes);
+		if (loaded.limited || loaded.content === undefined) {
+			if (loaded.limited) omittedAgentDefinitions++;
 			continue;
 		}
 
+		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(loaded.content);
+
+		if (!frontmatter.name || !frontmatter.description) continue;
+
 		const tools = frontmatter.tools
 			?.split(",")
 			.map((t: string) => t.trim())
@@ -192,7 +261,7 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 		});
 	}
 
-	return agents;
+	return { agents, omittedAgentDefinitions, metadataDiscoveryIncomplete: false };
 }
 
 function isDirectory(p: string): boolean {
@@ -223,13 +292,21 @@ export function discoverAgents(
 	cwd: string,
 	scope: AgentScope,
 	config?: SubagentSettings,
+	options: AgentDiscoveryOptions = {},
 ): AgentDiscoveryResult {
 	const userDir = path.join(getAgentDir(), "agents");
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
 
-	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
-	const projectAgents =
-		scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+	const userLoaded =
+		scope === "project"
+			? { agents: [], omittedAgentDefinitions: 0, metadataDiscoveryIncomplete: false }
+			: loadAgentsFromDir(userDir, "user", options);
+	const projectLoaded =
+		scope === "user" || !projectAgentsDir
+			? { agents: [], omittedAgentDefinitions: 0, metadataDiscoveryIncomplete: false }
+			: loadAgentsFromDir(projectAgentsDir, "project", options);
+	const userAgents = userLoaded.agents;
+	const projectAgents = projectLoaded.agents;
 
 	const agentMap = new Map<string, AgentConfig>();
 
@@ -268,7 +345,16 @@ export function discoverAgents(
 		agentMap.set(name, nextAgent);
 	}
 
-	return { agents: Array.from(agentMap.values()), projectAgentsDir };
+	const omittedAgentDefinitions =
+		userLoaded.omittedAgentDefinitions + projectLoaded.omittedAgentDefinitions;
+	const metadataDiscoveryIncomplete =
+		userLoaded.metadataDiscoveryIncomplete || projectLoaded.metadataDiscoveryIncomplete;
+	return {
+		agents: Array.from(agentMap.values()),
+		projectAgentsDir,
+		...(omittedAgentDefinitions > 0 ? { omittedAgentDefinitions } : {}),
+		...(metadataDiscoveryIncomplete ? { metadataDiscoveryIncomplete } : {}),
+	};
 }
 
 export function formatAgentList(
@@ -283,3 +369,203 @@ export function formatAgentList(
 		remaining,
 	};
 }
+
+export interface AgentCatalog {
+	/** The effective catalog for the default invocation scope. */
+	user: AgentDiscoveryResult;
+	/** The project-scope catalog; custom project definitions are loaded only after project trust. */
+	project?: AgentDiscoveryResult;
+}
+
+export interface AgentCatalogFormatOptions {
+	maxItems?: number;
+	maxDescriptionLength?: number;
+	maxCharacters?: number;
+}
+
+export interface AgentCatalogFormatResult {
+	text: string;
+	omitted: number;
+}
+
+export const DEFAULT_AGENT_CATALOG_MAX_ITEMS = 32;
+export const DEFAULT_AGENT_CATALOG_MAX_DESCRIPTION_LENGTH = 240;
+export const DEFAULT_AGENT_CATALOG_MAX_CHARACTERS = 6_000;
+export const DEFAULT_AGENT_CATALOG_MAX_FILES_PER_SCOPE = 128;
+export const DEFAULT_AGENT_CATALOG_MAX_FILE_BYTES = 64 * 1024;
+export const DEFAULT_AGENT_CATALOG_MAX_TOTAL_BYTES_PER_SCOPE = 2 * 1024 * 1024;
+
+const BUILT_IN_AGENT_ORDER = new Map(BUILT_IN_AGENTS.map((agent, index) => [agent.name, index]));
+
+function compareCatalogAgents(left: AgentConfig, right: AgentConfig): number {
+	const leftBuiltInOrder = BUILT_IN_AGENT_ORDER.get(left.name);
+	const rightBuiltInOrder = BUILT_IN_AGENT_ORDER.get(right.name);
+	if (leftBuiltInOrder !== undefined || rightBuiltInOrder !== undefined) {
+		if (leftBuiltInOrder === undefined) return 1;
+		if (rightBuiltInOrder === undefined) return -1;
+		return leftBuiltInOrder - rightBuiltInOrder;
+	}
+	return left.name.localeCompare(right.name);
+}
+
+function normalizeCatalogDescription(description: string, maxLength: number): string {
+	const normalized = description.replace(/\s+/gu, " ").trim();
+	if (normalized.length <= maxLength) return normalized;
+	const suffix = "…";
+	return `${normalized.slice(0, Math.max(0, maxLength - suffix.length)).trimEnd()}${suffix}`;
+}
+
+type CatalogScope = "user" | "project" | "project-fallback";
+
+function catalogAgentLine(
+	agent: AgentConfig,
+	scope: CatalogScope,
+	userNames: ReadonlySet<string>,
+	maxDescriptionLength: number,
+): string {
+	const scopeLabel =
+		scope === "user"
+			? 'agentScope: "user"'
+			: scope === "project"
+				? 'requires agentScope: "project" or "both"'
+				: 'requires agentScope: "project" ("both" selects the user definition)';
+	const collision =
+		scope !== "user" && userNames.has(agent.name)
+			? scope === "project"
+				? "; overrides the default user definition for project/both"
+				: "; scope-specific fallback for the default user override"
+			: "";
+	return `- ${agent.name} [source: ${agent.source}; ${scopeLabel}${collision}] — ${normalizeCatalogDescription(agent.description, maxDescriptionLength)}`;
+}
+
+/**
+ * Format the effective agent variants that the parent model can invoke.
+ *
+ * User-authored descriptions are prompt text, so this formatter deliberately normalizes and bounds
+ * them. Project definitions are supplied separately by the caller so an untrusted project is never
+ * read merely to build model-facing metadata.
+ */
+export function formatAgentCatalog(
+	catalog: AgentCatalog,
+	options: AgentCatalogFormatOptions = {},
+): AgentCatalogFormatResult {
+	const maxItems = Math.max(0, options.maxItems ?? DEFAULT_AGENT_CATALOG_MAX_ITEMS);
+	const maxDescriptionLength = Math.max(
+		1,
+		options.maxDescriptionLength ?? DEFAULT_AGENT_CATALOG_MAX_DESCRIPTION_LENGTH,
+	);
+	const maxCharacters = Math.max(1, options.maxCharacters ?? DEFAULT_AGENT_CATALOG_MAX_CHARACTERS);
+	const userDiscoveryIncomplete =
+		(catalog.user.omittedAgentDefinitions ?? 0) > 0 ||
+		catalog.user.metadataDiscoveryIncomplete === true;
+	const projectDiscoveryIncomplete =
+		(catalog.project?.omittedAgentDefinitions ?? 0) > 0 ||
+		catalog.project?.metadataDiscoveryIncomplete === true;
+	const discoveredUserAgents = [...catalog.user.agents].sort(compareCatalogAgents);
+	const discoveredProjectScopeAgents = [...(catalog.project?.agents ?? [])].sort(
+		compareCatalogAgents,
+	);
+	const userAgents = userDiscoveryIncomplete ? [] : discoveredUserAgents;
+	const projectScopeAgents = projectDiscoveryIncomplete ? [] : discoveredProjectScopeAgents;
+	const projectAgents = projectScopeAgents.filter((agent) => agent.source === "project");
+	const discoveredUserByName = new Map(discoveredUserAgents.map((agent) => [agent.name, agent]));
+	const userByName = new Map(userAgents.map((agent) => [agent.name, agent]));
+	const userNames = new Set(userByName.keys());
+	const potentialProjectFallbackAgents = discoveredProjectScopeAgents.filter(
+		(agent) =>
+			agent.source === "built-in" && discoveredUserByName.get(agent.name)?.source === "user",
+	);
+	const projectFallbackAgents =
+		userDiscoveryIncomplete || projectDiscoveryIncomplete ? [] : potentialProjectFallbackAgents;
+	const allEntries = [
+		...userAgents.map((agent) => ({ agent, scope: "user" as const })),
+		...projectAgents.map((agent) => ({ agent, scope: "project" as const })),
+		...projectFallbackAgents.map((agent) => ({ agent, scope: "project-fallback" as const })),
+	];
+	const boundedEntries = allEntries.slice(0, maxItems);
+	const suppressedMetadataEntries =
+		(userDiscoveryIncomplete ? discoveredUserAgents.length : 0) +
+		(projectDiscoveryIncomplete
+			? discoveredProjectScopeAgents.filter((agent) => agent.source === "project").length +
+				potentialProjectFallbackAgents.length
+			: 0);
+	const discoveryOmissions =
+		(catalog.user.omittedAgentDefinitions ?? 0) +
+		(catalog.project?.omittedAgentDefinitions ?? 0) +
+		suppressedMetadataEntries;
+	const discoveryIncomplete =
+		catalog.user.metadataDiscoveryIncomplete === true ||
+		catalog.project?.metadataDiscoveryIncomplete === true;
+
+	const render = (entries: typeof allEntries, omitted: number): string => {
+		const lines = [
+			"Available agent definitions (metadata only; runtime validation and trust remain authoritative).",
+		];
+		const userLines = entries
+			.filter((entry) => entry.scope === "user")
+			.map((entry) => catalogAgentLine(entry.agent, entry.scope, userNames, maxDescriptionLength));
+		if (userLines.length > 0) {
+			lines.push('Default scope (agentScope: "user"):');
+			lines.push(...userLines);
+		}
+		const projectLines = entries
+			.filter((entry) => entry.scope !== "user")
+			.map((entry) => catalogAgentLine(entry.agent, entry.scope, userNames, maxDescriptionLength));
+		if (projectLines.length > 0) {
+			lines.push("Trusted project/scope variants (use the required agentScope shown):");
+			lines.push(...projectLines);
+		}
+		const collisionNames = entries
+			.filter((entry) => entry.scope !== "user" && userNames.has(entry.agent.name))
+			.map((entry) => entry.agent.name);
+		if (collisionNames.length > 0 && projectLines.length > 0) {
+			const precedence = entries
+				.filter((entry) => entry.scope !== "user" && userNames.has(entry.agent.name))
+				.map((entry) =>
+					entry.scope === "project"
+						? `${entry.agent.name}: user with "user", project with "project"/"both"`
+						: `${entry.agent.name}: user with "user"/"both", built-in with "project"`,
+				);
+			lines.push(`Same-name precedence: ${precedence.join("; ")}.`);
+		}
+		if (omitted > 0) {
+			lines.push(
+				`[${omitted} additional agent definition${omitted === 1 ? "" : "s"} omitted due to metadata bounds or incomplete discovery.]`,
+			);
+		}
+		if (discoveryIncomplete) {
+			lines.push("[Agent metadata discovery was incomplete; some definitions may be unavailable.]");
+		}
+		return lines.join("\n");
+	};
+
+	let listedCount = boundedEntries.length;
+	let text = render(
+		boundedEntries.slice(0, listedCount),
+		allEntries.length - listedCount + discoveryOmissions,
+	);
+	while (text.length > maxCharacters && listedCount > 0) {
+		listedCount -= 1;
+		text = render(
+			boundedEntries.slice(0, listedCount),
+			allEntries.length - listedCount + discoveryOmissions,
+		);
+	}
+	return { text, omitted: allEntries.length - listedCount + discoveryOmissions };
+}
+
+export function discoverAgentCatalog(
+	cwd: string,
+	projectTrusted: boolean,
+	config?: SubagentSettings,
+): AgentCatalog {
+	const options: AgentDiscoveryOptions = {
+		maxFiles: DEFAULT_AGENT_CATALOG_MAX_FILES_PER_SCOPE,
+		maxFileBytes: DEFAULT_AGENT_CATALOG_MAX_FILE_BYTES,
+		maxTotalBytes: DEFAULT_AGENT_CATALOG_MAX_TOTAL_BYTES_PER_SCOPE,
+	};
+	return {
+		user: discoverAgents(cwd, "user", config, options),
+		project: projectTrusted ? discoverAgents(cwd, "project", config, options) : undefined,
+	};
+}

package/src/stateful.ts

@@ -106,6 +106,7 @@ export interface StatefulSubagentRuntimeStatus {
 export interface StatefulSubagentController {
 	getCompletionDelivery(): CompletionDelivery;
 	setCompletionDelivery(value: CompletionDelivery): void;
+	setAgentCatalog(value: string): void;
 	getRuntimeStatus(): StatefulSubagentRuntimeStatus;
 	listAgents(includeClosed?: boolean): ManagedAgent[];
 	clearAgents(): Promise<number>;
@@ -127,6 +128,7 @@ export function registerStatefulSubagents(
 	const enabled = settings.enabled !== false;
 	const transportKind = resolveStatefulTransportKind(settings.transport);
 	let completionDelivery = resolveCompletionDelivery(settings.completionDelivery);
+	let agentCatalog = "";
 	let completionBroker: CompletionDeliveryBroker | undefined;
 	let refreshSpawnToolRegistration: (() => void) | undefined;
 	let registry: AgentRegistry | undefined;
@@ -161,6 +163,10 @@ export function registerStatefulSubagents(
 			completionBroker?.setDelivery(value);
 			refreshSpawnToolRegistration?.();
 		},
+		setAgentCatalog(value) {
+			agentCatalog = value;
+			refreshSpawnToolRegistration?.();
+		},
 		getRuntimeStatus() {
 			const agents = registry?.list(true) ?? [];
 			return {
@@ -315,11 +321,12 @@ export function registerStatefulSubagents(
 		}
 	});
 
+	const baseSpawnDescription =
+		"Start an addressable background subagent with an optional thinking level chosen for the task difficulty, return immediately with an agentId, and receive its completion asynchronously.";
 	const spawnTool = defineTool({
 		name: "subagent_spawn",
 		label: "Spawn Subagent",
-		description:
-			"Start an addressable background subagent with an optional thinking level chosen for the task difficulty, return immediately with an agentId, and receive its completion asynchronously.",
+		description: appendAgentCatalog(baseSpawnDescription, agentCatalog),
 		promptSnippet: "Start a reusable detached subagent; completion is delivered asynchronously",
 		promptGuidelines: createSpawnPromptGuidelines(completionDelivery, blockingEnabled),
 		parameters: Type.Object({
@@ -399,6 +406,7 @@ export function registerStatefulSubagents(
 		},
 	});
 	refreshSpawnToolRegistration = () => {
+		spawnTool.description = appendAgentCatalog(baseSpawnDescription, agentCatalog);
 		spawnTool.promptGuidelines = createSpawnPromptGuidelines(completionDelivery, blockingEnabled);
 		pi.registerTool(spawnTool);
 	};
@@ -917,6 +925,10 @@ 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.ts

@@ -12,7 +12,8 @@
  * Uses JSON mode to capture structured output from subagents.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { discoverAgentCatalog, formatAgentCatalog } from "./agents.js";
 import { registerSubagentConfigCommand } from "./config-ui.js";
 import { executeSubagent } from "./execution.js";
 import { SubagentParams } from "./params.js";
@@ -23,43 +24,53 @@ import { registerStatefulSubagents } from "./stateful.js";
 
 export default function (pi: ExtensionAPI) {
 	const settings = readSubagentSettings();
-	if (settings?.blocking?.enabled !== false) registerBlockingSubagent(pi);
+	const blockingEnabled = settings?.blocking?.enabled !== false;
+	const refreshBlockingCatalog = blockingEnabled ? registerBlockingSubagent(pi) : () => undefined;
+	let refreshStatefulCatalog: (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();
-		readSubagentSettings();
+		const refreshedSettings = readSubagentSettings();
 		const refreshedNotice = consumeSubagentSettingsNotice();
 		const notice = [
 			...new Set([loadNotice, refreshedNotice].filter((value) => value !== undefined)),
 		].join("\n");
 		if (notice) ctx.ui.notify(notice, "warning");
+
+		const catalog = formatAgentCatalog(
+			discoverAgentCatalog(ctx.cwd, ctx.isProjectTrusted(), refreshedSettings),
+		).text;
+		refreshBlockingCatalog(catalog);
+		refreshStatefulCatalog(catalog);
 	});
 
-	const blockingEnabled = settings?.blocking?.enabled !== false;
 	const statefulRuntime = registerStatefulSubagents(pi, {
 		blockingEnabled,
 		settings: settings?.stateful,
 	});
+	refreshStatefulCatalog = statefulRuntime.setAgentCatalog;
 	registerSubagentConfigCommand(pi, {
 		...statefulRuntime,
 		getBlockingEnabled: () => blockingEnabled,
 	});
 }
 
-function registerBlockingSubagent(pi: ExtensionAPI) {
-	pi.registerTool<typeof SubagentParams, SubagentDetails>({
+function registerBlockingSubagent(pi: ExtensionAPI): (catalog: string) => void {
+	let catalog = "";
+	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).",
+		"Parallel mode may include an aggregator fan-in step that receives all task outputs.",
+		'Default agent scope is "user" (from ~/.pi/agent/agents).',
+		'To enable project-local agents in .pi/agents, pass agentScope: "both" (or "project") as a top-level argument for that call.',
+	].join(" ");
+	const definition: ToolDefinition<typeof SubagentParams, SubagentDetails> = {
 		name: "subagent",
 		label: "Blocking Subagent",
-		description: [
-			"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).",
-			"Parallel mode may include an aggregator fan-in step that receives all task outputs.",
-			'Default agent scope is "user" (from ~/.pi/agent/agents).',
-			'To enable project-local agents in .pi/agents, pass agentScope: "both" (or "project") as a top-level argument for that call.',
-		].join(" "),
+		description: appendAgentCatalog(baseDescription, catalog),
 		promptSnippet:
 			"Run blocking isolated subagents only when their outputs are required before the main agent can continue.",
 		promptGuidelines: [
@@ -85,13 +96,22 @@ function registerBlockingSubagent(pi: ExtensionAPI) {
 		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);
+		pi.registerTool<typeof SubagentParams, SubagentDetails>(definition);
+	};
+}
+
+function appendAgentCatalog(baseDescription: string, catalog: string): string {
+	return catalog ? `${baseDescription}\n\n${catalog}` : baseDescription;
 }
 
 export { parsePositiveInteger } from "./execution.js";