@ferris1225/pi-subagents 4.0.0 → 4.1.1

package/src/completion.ts

@@ -1,160 +1,160 @@
-/**
- * Smart batching for successful background completions.
- *
- * A short debounce coalesces sibling runs while a max-wait timer, measured from
- * the first item in the open group, bounds delivery latency. Failures are
- * intentionally handled by the caller: flush held successes, then emit the
- * failure directly so it is never delayed.
- */
-
-import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } from "./spawn.ts";
-import { formatUsageCompact, sumUsage } from "./monitor.ts";
-import type { UsageStats } from "./rpc-run.ts";
-
-export interface CompletionBatchTimings {
-	debounceMs: number;
-	maxWaitMs: number;
-}
-
-export const DEFAULT_COMPLETION_BATCH_TIMINGS: CompletionBatchTimings = {
-	debounceMs: 150,
-	maxWaitMs: 1_000,
-};
-
-type TimerHandle = ReturnType<typeof setTimeout>;
-
-function unrefHandle(handle: TimerHandle): void {
-	if (
-		handle &&
-		typeof handle === "object" &&
-		"unref" in handle &&
-		typeof (handle as { unref: unknown }).unref === "function"
-	) {
-		(handle as { unref: () => void }).unref();
-	}
-}
-
-export interface CompletionBatcherOptions<T> {
-	emit: (items: T[]) => void;
-	timings?: Partial<CompletionBatchTimings>;
-}
-
-export interface CompletionBatcher<T> {
-	/** Add an item to the current debounced group. */
-	push(item: T): void;
-	/** Emit any held items immediately as one group. */
-	flush(): void;
-	/** Clear timers and return held items without emitting them. */
-	dispose(): T[];
-}
-
-export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>): CompletionBatcher<T> {
-	const timings = { ...DEFAULT_COMPLETION_BATCH_TIMINGS, ...options.timings };
-	let pending: T[] = [];
-	let debounceTimer: TimerHandle | null = null;
-	let maxWaitTimer: TimerHandle | null = null;
-
-	const clearTimers = (): void => {
-		if (debounceTimer !== null) {
-			clearTimeout(debounceTimer);
-			debounceTimer = null;
-		}
-		if (maxWaitTimer !== null) {
-			clearTimeout(maxWaitTimer);
-			maxWaitTimer = null;
-		}
-	};
-
-	const emitGroup = (): void => {
-		clearTimers();
-		if (pending.length === 0) return;
-		const items = pending;
-		pending = [];
-		options.emit(items);
-	};
-
-	return {
-		push(item: T): void {
-			pending.push(item);
-
-			if (debounceTimer !== null) clearTimeout(debounceTimer);
-			debounceTimer = setTimeout(emitGroup, timings.debounceMs);
-			unrefHandle(debounceTimer);
-
-			if (maxWaitTimer === null) {
-				maxWaitTimer = setTimeout(emitGroup, timings.maxWaitMs);
-				unrefHandle(maxWaitTimer);
-			}
-		},
-		flush: emitGroup,
-		dispose(): T[] {
-			clearTimers();
-			const abandoned = pending;
-			pending = [];
-			return abandoned;
-		},
-	};
-}
-
-export interface CompletionMessageItem {
-	agent: string;
-	block: string;
-	triggerTurn: boolean;
-	/** Final usage of the underlying run (or chain); aggregated into the group totals. */
-	usage?: UsageStats;
-}
-
-/** Keep the established single-result shape; add a group header and an aggregate
- * token/cost footer only for real groups. */
-export function formatCompletionMessage(items: readonly CompletionMessageItem[]): string {
-	if (items.length === 0) return "";
-	if (items.length === 1) return items[0].block;
-	const agents = items.map((item) => item.agent).join(", ");
-	const withUsage = items.filter((item) => item.usage !== undefined);
-	const totals = withUsage.length > 0 ? formatUsageCompact(sumUsage(withUsage.map((item) => item.usage!))) : "";
-	const footer = totals ? `\n\nTotals: ${items.length} runs · ${totals}` : "";
-	return `### Subagents completed (${items.length}): ${agents}\n\n${items.map((item) => item.block).join("\n\n")}${footer}`;
-}
-
-/** A grouped completion wakes the main agent when any member requires a turn. */
-export function completionGroupTriggersTurn(items: readonly CompletionMessageItem[]): boolean {
-	return items.some((item) => item.triggerTurn);
-}
-
-/** Passing reviewer notifications may opt out of waking; every other result wakes. */
-export function completionTriggersTurn(result: SingleResult, notifyOnReviewPass: boolean): boolean {
-	if (isFailedResult(result)) return true;
-	return !(
-		notifyOnReviewPass &&
-		result.agent === "reviewer" &&
-		reviewVerdict(getResultOutput(result)) === "pass"
-	);
-}
-
-/** Minimal shape of an active run, for the "others still running" footer. Kept
- * decoupled from the monitor's RunView so this stays a pure, easily tested
- * formatter; the caller maps its live runs into this shape. */
-export interface ActiveRunFoot {
-	id: number;
-	agent: string;
-	/** Optional content label (task-derived) shown next to the agent name. */
-	label?: string;
-}
-
-/**
- * Footer appended to a completion message when OTHER runs are still active, so
- * the main agent does not declare the overall task done prematurely. A result
- * arriving for one run does not mean sibling runs are finished; naming them
- * gives the main agent concrete, in-context awareness to keep waiting.
- *
- * Returns "" when nothing is active (the common, single-run case stays quiet).
- */
-export function formatActiveRunsFooter(runs: readonly ActiveRunFoot[], maxListed = 4): string {
-	if (runs.length === 0) return "";
-	const listed = runs.slice(0, maxListed);
-	const items = listed
-		.map((run) => `#${run.id} ${run.agent}${run.label ? `·${run.label}` : ""}`)
-		.join(", ");
-	const more = runs.length > listed.length ? `, +${runs.length - listed.length} more` : "";
-	return `\n\n⚠ ${runs.length} other run${runs.length === 1 ? "" : "s"} still active: ${items}${more}. Do not conclude the overall task yet — wait for their results (they wake you automatically) or check subagent_status.`;
-}
+/**
+ * Smart batching for successful background completions.
+ *
+ * A short debounce coalesces sibling runs while a max-wait timer, measured from
+ * the first item in the open group, bounds delivery latency. Failures are
+ * intentionally handled by the caller: flush held successes, then emit the
+ * failure directly so it is never delayed.
+ */
+
+import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } from "./spawn.ts";
+import { formatUsageCompact, sumUsage } from "./monitor.ts";
+import type { UsageStats } from "./rpc-run.ts";
+
+export interface CompletionBatchTimings {
+	debounceMs: number;
+	maxWaitMs: number;
+}
+
+export const DEFAULT_COMPLETION_BATCH_TIMINGS: CompletionBatchTimings = {
+	debounceMs: 150,
+	maxWaitMs: 1_000,
+};
+
+type TimerHandle = ReturnType<typeof setTimeout>;
+
+function unrefHandle(handle: TimerHandle): void {
+	if (
+		handle &&
+		typeof handle === "object" &&
+		"unref" in handle &&
+		typeof (handle as { unref: unknown }).unref === "function"
+	) {
+		(handle as { unref: () => void }).unref();
+	}
+}
+
+export interface CompletionBatcherOptions<T> {
+	emit: (items: T[]) => void;
+	timings?: Partial<CompletionBatchTimings>;
+}
+
+export interface CompletionBatcher<T> {
+	/** Add an item to the current debounced group. */
+	push(item: T): void;
+	/** Emit any held items immediately as one group. */
+	flush(): void;
+	/** Clear timers and return held items without emitting them. */
+	dispose(): T[];
+}
+
+export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>): CompletionBatcher<T> {
+	const timings = { ...DEFAULT_COMPLETION_BATCH_TIMINGS, ...options.timings };
+	let pending: T[] = [];
+	let debounceTimer: TimerHandle | null = null;
+	let maxWaitTimer: TimerHandle | null = null;
+
+	const clearTimers = (): void => {
+		if (debounceTimer !== null) {
+			clearTimeout(debounceTimer);
+			debounceTimer = null;
+		}
+		if (maxWaitTimer !== null) {
+			clearTimeout(maxWaitTimer);
+			maxWaitTimer = null;
+		}
+	};
+
+	const emitGroup = (): void => {
+		clearTimers();
+		if (pending.length === 0) return;
+		const items = pending;
+		pending = [];
+		options.emit(items);
+	};
+
+	return {
+		push(item: T): void {
+			pending.push(item);
+
+			if (debounceTimer !== null) clearTimeout(debounceTimer);
+			debounceTimer = setTimeout(emitGroup, timings.debounceMs);
+			unrefHandle(debounceTimer);
+
+			if (maxWaitTimer === null) {
+				maxWaitTimer = setTimeout(emitGroup, timings.maxWaitMs);
+				unrefHandle(maxWaitTimer);
+			}
+		},
+		flush: emitGroup,
+		dispose(): T[] {
+			clearTimers();
+			const abandoned = pending;
+			pending = [];
+			return abandoned;
+		},
+	};
+}
+
+export interface CompletionMessageItem {
+	agent: string;
+	block: string;
+	triggerTurn: boolean;
+	/** Final usage of the underlying run (or chain); aggregated into the group totals. */
+	usage?: UsageStats;
+}
+
+/** Keep the established single-result shape; add a group header and an aggregate
+ * token/cost footer only for real groups. */
+export function formatCompletionMessage(items: readonly CompletionMessageItem[]): string {
+	if (items.length === 0) return "";
+	if (items.length === 1) return items[0].block;
+	const agents = items.map((item) => item.agent).join(", ");
+	const withUsage = items.filter((item) => item.usage !== undefined);
+	const totals = withUsage.length > 0 ? formatUsageCompact(sumUsage(withUsage.map((item) => item.usage!))) : "";
+	const footer = totals ? `\n\nTotals: ${items.length} runs · ${totals}` : "";
+	return `### Subagents completed (${items.length}): ${agents}\n\n${items.map((item) => item.block).join("\n\n")}${footer}`;
+}
+
+/** A grouped completion wakes the main agent when any member requires a turn. */
+export function completionGroupTriggersTurn(items: readonly CompletionMessageItem[]): boolean {
+	return items.some((item) => item.triggerTurn);
+}
+
+/** Passing reviewer notifications may opt out of waking; every other result wakes. */
+export function completionTriggersTurn(result: SingleResult, notifyOnReviewPass: boolean): boolean {
+	if (isFailedResult(result)) return true;
+	return !(
+		notifyOnReviewPass &&
+		result.agent === "reviewer" &&
+		reviewVerdict(getResultOutput(result)) === "pass"
+	);
+}
+
+/** Minimal shape of an active run, for the "others still running" footer. Kept
+ * decoupled from the monitor's RunView so this stays a pure, easily tested
+ * formatter; the caller maps its live runs into this shape. */
+export interface ActiveRunFoot {
+	id: number;
+	agent: string;
+	/** Optional content label (task-derived) shown next to the agent name. */
+	label?: string;
+}
+
+/**
+ * Footer appended to a completion message when OTHER runs are still active, so
+ * the main agent does not declare the overall task done prematurely. A result
+ * arriving for one run does not mean sibling runs are finished; naming them
+ * gives the main agent concrete, in-context awareness to keep waiting.
+ *
+ * Returns "" when nothing is active (the common, single-run case stays quiet).
+ */
+export function formatActiveRunsFooter(runs: readonly ActiveRunFoot[], maxListed = 4): string {
+	if (runs.length === 0) return "";
+	const listed = runs.slice(0, maxListed);
+	const items = listed
+		.map((run) => `#${run.id} ${run.agent}${run.label ? `·${run.label}` : ""}`)
+		.join(", ");
+	const more = runs.length > listed.length ? `, +${runs.length - listed.length} more` : "";
+	return `\n\n⚠ ${runs.length} other run${runs.length === 1 ? "" : "s"} still active: ${items}${more}. Do not conclude the overall task yet — wait for their results (they wake you automatically) or check subagent_status.`;
+}

package/src/config.ts

@@ -25,6 +25,27 @@ export const DEFAULT_ENABLED_AGENTS: readonly string[] = ["explorer", "worker",
 export const AGENT_SCOPE_VALUES = ["user", "project", "both"] as const;
 export type AgentScope = (typeof AGENT_SCOPE_VALUES)[number];
 
+const LEGACY_EXPLORER_NAME = "explore";
+const EXPLORER_NAME = "explorer";
+const CLEANER_NAME = "cleaner";
+const REVIEWER_NAME = "reviewer";
+
+/**
+ * Stamps recorded in `announcedFeatures` by the one-time upgrade that defaults
+ * cleaner on for configs written before it shipped. The first marks a config as
+ * processed, so a later deliberate disable is not undone; the second records
+ * that cleaner was actually injected, so session start can tell the user once;
+ * the third records that reviewer model/thinking settings were actually copied,
+ * so that notice never claims an inheritance that did not happen.
+ */
+export const CLEANER_DEFAULTED_FEATURE = "cleanerDefaulted";
+export const CLEANER_AUTO_ENABLED_FEATURE = "cleanerAutoEnabled";
+export const CLEANER_INHERITED_FEATURE = "cleanerInheritedReviewer";
+
+function migrateAgentName(name: string): string {
+	return name === LEGACY_EXPLORER_NAME ? EXPLORER_NAME : name;
+}
+
 /** Thinking levels accepted by pi's `--thinking` option. */
 export const THINKING_LEVEL_VALUES = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 export type ThinkingLevel = (typeof THINKING_LEVEL_VALUES)[number];
@@ -99,8 +120,9 @@ export interface SubagentsConfig {
 	 */
 	idleTimeoutSec: number;
 	/**
-	 * One-time feature announcements already shown to the user. Persisted so
-	 * the notice never nags again.
+	 * One-time feature announcements already shown to the user, plus schema
+	 * upgrade stamps (e.g. the cleaner default-enable upgrade). Persisted so
+	 * notices and migrations never repeat.
 	 */
 	announcedFeatures: string[];
 }
@@ -156,25 +178,48 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		const names = raw.enabledAgents.filter(
 			(name): name is string => typeof name === "string" && name.trim().length > 0,
 		);
-		// An explicitly empty array is honored (disables all agents); otherwise keep valid names.
-		config.enabledAgents = [...new Set(names.map((name) => name.trim()))];
+		// An explicitly empty array is honored. Rename the former built-in key and
+		// deduplicate when a config already contains both spellings.
+		config.enabledAgents = [...new Set(names.map((name) => migrateAgentName(name.trim())))];
 	}
 
 	if (isRecord(raw.agentModels)) {
-		for (const [key, value] of Object.entries(raw.agentModels)) {
-			if (isModelReference(value)) config.agentModels[key.trim()] = value.trim();
+		const entries = Object.entries(raw.agentModels);
+		// A valid explicit new key wins regardless of JSON property order.
+		for (const [rawKey, value] of entries) {
+			const key = rawKey.trim();
+			if (key !== LEGACY_EXPLORER_NAME && isModelReference(value)) {
+				config.agentModels[key] = value.trim();
+			}
+		}
+		if (!Object.hasOwn(config.agentModels, EXPLORER_NAME)) {
+			const legacy = entries.find(([key, value]) =>
+				key.trim() === LEGACY_EXPLORER_NAME && isModelReference(value)
+			);
+			if (legacy && isModelReference(legacy[1])) config.agentModels[EXPLORER_NAME] = legacy[1].trim();
 		}
 	}
 
 	if (isRecord(raw.agentThinkingLevels)) {
-		for (const [key, value] of Object.entries(raw.agentThinkingLevels)) {
+		const entries = Object.entries(raw.agentThinkingLevels);
+		for (const [rawKey, value] of entries) {
+			const key = rawKey.trim();
 			if (
+				key !== LEGACY_EXPLORER_NAME &&
 				typeof value === "string" &&
 				(THINKING_LEVEL_VALUES as readonly string[]).includes(value)
 			) {
-				config.agentThinkingLevels[key.trim()] = value as ThinkingLevel;
+				config.agentThinkingLevels[key] = value as ThinkingLevel;
 			}
 		}
+		if (!Object.hasOwn(config.agentThinkingLevels, EXPLORER_NAME)) {
+			const legacy = entries.find(([key, value]) =>
+				key.trim() === LEGACY_EXPLORER_NAME &&
+				typeof value === "string" &&
+				(THINKING_LEVEL_VALUES as readonly string[]).includes(value)
+			);
+			if (legacy) config.agentThinkingLevels[EXPLORER_NAME] = legacy[1] as ThinkingLevel;
+		}
 	}
 
 	if (typeof raw.notifyOnReviewPass === "boolean") {
@@ -211,6 +256,32 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		);
 	}
 
+	// One-time upgrade for configs written before cleaner shipped: a non-empty
+	// explicit enabledAgents list gets cleaner defaulted on (inserted before
+	// reviewer, matching the fresh-install order) and inherits the reviewer's
+	// configured model and thinking level — its closest peer. The stamps make
+	// the upgrade idempotent and keep a later deliberate disable from being undone.
+	if (!config.announcedFeatures.includes(CLEANER_DEFAULTED_FEATURE)) {
+		config.announcedFeatures.push(CLEANER_DEFAULTED_FEATURE);
+		if (config.enabledAgents.length > 0 && !config.enabledAgents.includes(CLEANER_NAME)) {
+			const reviewerIndex = config.enabledAgents.indexOf(REVIEWER_NAME);
+			config.enabledAgents.splice(reviewerIndex === -1 ? config.enabledAgents.length : reviewerIndex, 0, CLEANER_NAME);
+			config.announcedFeatures.push(CLEANER_AUTO_ENABLED_FEATURE);
+			let inherited = false;
+			if (!config.agentModels[CLEANER_NAME] && config.agentModels[REVIEWER_NAME]) {
+				config.agentModels[CLEANER_NAME] = config.agentModels[REVIEWER_NAME];
+				inherited = true;
+			}
+			if (!config.agentThinkingLevels[CLEANER_NAME] && config.agentThinkingLevels[REVIEWER_NAME]) {
+				config.agentThinkingLevels[CLEANER_NAME] = config.agentThinkingLevels[REVIEWER_NAME];
+				inherited = true;
+			}
+			// An old explicit list may have no reviewer overrides to copy; only the
+			// copied case is stamped so the one-time notice stays accurate.
+			if (inherited) config.announcedFeatures.push(CLEANER_INHERITED_FEATURE);
+		}
+	}
+
 	return config;
 }
 

package/src/index.ts

@@ -1,93 +1,93 @@
-/**
- * pi-subagents — focused sub-agent delegation for pi.
- *
- * Assembly point: builds the shared runtime and registers everything.
- * The heavy lifting lives in focused modules:
- *   - dispatch.ts         — the `subagent` tool contract and auto-fix chain
- *   - thread-lifecycle.ts — queued generations, resume/fork, isolation settlement
- *   - tools.ts            — subagent_control / subagent_wait / status / stop
- *   - announcements.ts — session-start recovery, notices, and widget install
- *   - widget.ts        — active-only TUI run status
- *   - runtime.ts       — shared per-session state
- *
- * Also registers the `/subagents-setup` command and a `before_agent_start` hook
- * that injects a delegation directive into the parent system prompt so the main
- * model uses the tool proactively.
- *
- * The tool is not registered inside child sub-agent processes, which prevents
- * runaway recursion and keeps child context windows clean.
- */
-
-import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
-import { discoverAgents } from "./agents.ts";
-import { registerAnnouncements } from "./announcements.ts";
-import { getConfigPath, loadConfig } from "./config.ts";
-import { registerSubagentTool } from "./dispatch.ts";
-import { matchRunIds } from "./format.ts";
-import { buildDelegationDirective } from "./prompt.ts";
-import { createRuntime } from "./runtime.ts";
-import { runSetup } from "./setup.ts";
-import { currentSubagentDepth } from "./spawn.ts";
-import { registerLookupTools } from "./tools.ts";
-import { clearActiveRunsWidget } from "./widget.ts";
-
-export { matchRunIds };
-
-export default function (pi: ExtensionAPI): void {
-	const configPath = getConfigPath(getAgentDir());
-	const runtime = createRuntime(pi, configPath);
-
-	// Recursion guard: sub-agent children are leaf processes. The `subagent` tool is
-	// excluded from their toolset at spawn (--exclude-tools); this check is defense
-	// in depth so a child can never expose the tool back to its model, even if
-	// another extension ignores the depth marker.
-	if (currentSubagentDepth() >= 1) {
-		pi.registerCommand("subagents-setup", {
-			description: "Configure pi-subagents (unavailable in nested sub-agent processes)",
-			handler: async (_args, ctx) => {
-				ctx.ui.notify("pi-subagents setup is unavailable in nested sub-agent processes.", "warning");
-			},
-		});
-		return;
-	}
-
-	pi.registerMessageRenderer("subagent-result", (message, _options, theme) =>
-		new Text(
-			`${theme.fg("toolTitle", theme.bold("subagent result"))}\n${message.content}`,
-			0,
-			0,
-		),
-	);
-
-	pi.on("session_shutdown", async (_event, ctx) => {
-		clearActiveRunsWidget(ctx);
-		await runtime.shutdown();
-	});
-
-	registerSubagentTool(pi, runtime);
-	registerLookupTools(pi, runtime);
-
-	pi.registerCommand("subagents-setup", {
-		description: "Configure pi-subagents: agents, selected models, capability-aware thinking, and runtime settings",
-		handler: async (_args, ctx) => {
-			await runSetup(ctx, configPath);
-		},
-	});
-
-	registerAnnouncements(pi, runtime);
-
-	// Proactive dispatch: inject the delegation directive into the parent system prompt.
-	pi.on("before_agent_start", async (event, ctx) => {
-		const config = await loadConfig(configPath);
-		if (!config.proactiveInjection) return undefined;
-		const { agents } = discoverAgents(ctx.cwd, {
-			scope: config.agentScope,
-			enabledNames: config.enabledAgents,
-			projectTrusted: ctx.isProjectTrusted?.() === true,
-		});
-		const directive = buildDelegationDirective(agents);
-		if (!directive) return undefined;
-		return { systemPrompt: `${event.systemPrompt}\n${directive}` };
-	});
-}
+/**
+ * pi-subagents — focused sub-agent delegation for pi.
+ *
+ * Assembly point: builds the shared runtime and registers everything.
+ * The heavy lifting lives in focused modules:
+ *   - dispatch.ts         — the `subagent` tool contract and auto-fix chain
+ *   - thread-lifecycle.ts — queued generations, resume/fork, isolation settlement
+ *   - tools.ts            — subagent_control / subagent_wait / status / stop
+ *   - announcements.ts — session-start recovery, notices, and widget install
+ *   - widget.ts        — active-only TUI run status
+ *   - runtime.ts       — shared per-session state
+ *
+ * Also registers the `/subagents-setup` command and a `before_agent_start` hook
+ * that injects a delegation directive into the parent system prompt so the main
+ * model uses the tool proactively.
+ *
+ * The tool is not registered inside child sub-agent processes, which prevents
+ * runaway recursion and keeps child context windows clean.
+ */
+
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { discoverAgents } from "./agents.ts";
+import { registerAnnouncements } from "./announcements.ts";
+import { getConfigPath, loadConfig } from "./config.ts";
+import { registerSubagentTool } from "./dispatch.ts";
+import { matchRunIds } from "./format.ts";
+import { buildDelegationDirective } from "./prompt.ts";
+import { createRuntime } from "./runtime.ts";
+import { runSetup } from "./setup.ts";
+import { currentSubagentDepth } from "./spawn.ts";
+import { registerLookupTools } from "./tools.ts";
+import { clearActiveRunsWidget } from "./widget.ts";
+
+export { matchRunIds };
+
+export default function (pi: ExtensionAPI): void {
+	const configPath = getConfigPath(getAgentDir());
+	const runtime = createRuntime(pi, configPath);
+
+	// Recursion guard: sub-agent children are leaf processes. The `subagent` tool is
+	// excluded from their toolset at spawn (--exclude-tools); this check is defense
+	// in depth so a child can never expose the tool back to its model, even if
+	// another extension ignores the depth marker.
+	if (currentSubagentDepth() >= 1) {
+		pi.registerCommand("subagents-setup", {
+			description: "Configure pi-subagents (unavailable in nested sub-agent processes)",
+			handler: async (_args, ctx) => {
+				ctx.ui.notify("pi-subagents setup is unavailable in nested sub-agent processes.", "warning");
+			},
+		});
+		return;
+	}
+
+	pi.registerMessageRenderer("subagent-result", (message, _options, theme) =>
+		new Text(
+			`${theme.fg("toolTitle", theme.bold("subagent result"))}\n${message.content}`,
+			0,
+			0,
+		),
+	);
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		clearActiveRunsWidget(ctx);
+		await runtime.shutdown();
+	});
+
+	registerSubagentTool(pi, runtime);
+	registerLookupTools(pi, runtime);
+
+	pi.registerCommand("subagents-setup", {
+		description: "Configure pi-subagents: agents, selected models, capability-aware thinking, and runtime settings",
+		handler: async (_args, ctx) => {
+			await runSetup(ctx, configPath);
+		},
+	});
+
+	registerAnnouncements(pi, runtime);
+
+	// Proactive dispatch: inject the delegation directive into the parent system prompt.
+	pi.on("before_agent_start", async (event, ctx) => {
+		const config = await loadConfig(configPath);
+		if (!config.proactiveInjection) return undefined;
+		const { agents } = discoverAgents(ctx.cwd, {
+			scope: config.agentScope,
+			enabledNames: config.enabledAgents,
+			projectTrusted: ctx.isProjectTrusted?.() === true,
+		});
+		const directive = buildDelegationDirective(agents);
+		if (!directive) return undefined;
+		return { systemPrompt: `${event.systemPrompt}\n${directive}` };
+	});
+}