pi-subagents 0.21.0 → 0.21.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.21.1] - 2026-04-30
+
+### Changed
+- Changed the `/agents` new-agent shortcut from `Alt+N` to `Shift+Ctrl+N`, and added `agentManager.newShortcut` config for overriding it.
+
+### Fixed
+- Fall back to polling async result files when native result watching is unavailable due to `EMFILE` or `ENOSPC`.
+- Treat forced final-drain termination after a valid final assistant output as cleanup success instead of failing the subagent run.
+- Hide disabled builtin agents from `subagent({ action: "list" })` output so agent-facing choices match executable runtime discovery.
+- Resolve intercom bridge default paths at runtime so tests and isolated environments that change `HOME` use the correct `pi-intercom` location.
+- Made the tool-description source check tolerant of Windows line endings.
+
 ## [0.21.0] - 2026-04-29
 
 ### Changed

package/README.md

@@ -374,7 +374,7 @@ Useful keys:
 
 - type to search the list
 - `Enter` opens detail screens
-- `Alt+N` creates an agent or chain from a template
+- `Shift+Ctrl+N` creates an agent or chain from a template
 - `Ctrl+R` launches selected agents as a run or chain
 - `Ctrl+P` opens the parallel builder
 - `Tab` selects agents in the list or toggles skip-clarify in task input
@@ -432,7 +432,7 @@ Supported override fields are `model`, `fallbackModels`, `thinking`, `systemProm
 
 You can also manage builtin overrides from `/agents`. On a builtin detail screen, press `e`, choose user or project scope if needed, and save the fields you want to override.
 
-Set `disabled: true` to hide a builtin from runtime discovery while keeping it visible in `/agents`. For bulk control, set `subagents.disableBuiltins: true` in settings. Overridden builtins show badges like `[builtin+user]` or `[builtin+project]`; disabled builtins show `off` badges in the manager.
+Set `disabled: true` to hide a builtin from runtime discovery and agent-facing `subagent({ action: "list" })` output while keeping it visible in `/agents`. For bulk control, set `subagents.disableBuiltins: true` in settings. Overridden builtins show badges like `[builtin+user]` or `[builtin+project]`; disabled builtins show `off` badges in the manager.
 
 ### Prompt assembly
 
@@ -833,6 +833,18 @@ Session directory precedence is: `params.sessionDir`, then `config.defaultSessio
 
 Controls nested delegation when no inherited `PI_SUBAGENT_MAX_DEPTH` is already in effect. Per-agent `maxSubagentDepth` can tighten the limit for that agent’s child runs, but cannot relax an inherited stricter limit.
 
+### `agentManager.newShortcut`
+
+```json
+{
+  "agentManager": {
+    "newShortcut": "shift+ctrl+n"
+  }
+}
+```
+
+Sets the `/agents` list shortcut for opening the new agent/chain template picker. The default is `shift+ctrl+n`; use Pi key names such as `ctrl+n` if your terminal cannot distinguish Shift for control chords.
+
 ### `intercomBridge`
 
 ```json

package/agent-management.ts

@@ -378,16 +378,12 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
 	const d = discoverAgentsAll(ctx.cwd);
 	const scopedAgents = allAgents(d).filter((a) => scope === "both" || a.source === "builtin" || a.source === scope).sort((a, b) => a.name.localeCompare(b.name));
 	const agents = scopedAgents.filter((a) => !a.disabled);
-	const disabledBuiltins = scopedAgents.filter((a) => a.source === "builtin" && a.disabled);
 	const chains = d.chains.filter((c) => scope === "both" || c.source === scope).sort((a, b) => a.name.localeCompare(b.name));
 	const lines = [
 		"Executable agents:",
 		...(agents.length
 			? agents.map((a) => `- ${a.name} (${a.source}${a.defaultContext ? `, context: ${a.defaultContext}` : ""}): ${a.description}`)
 			: ["- (none)"]),
-		...(disabledBuiltins.length
-			? ["", "Disabled builtins:", ...disabledBuiltins.map((a) => `- ${a.name} (${a.source}${a.defaultContext ? `, context: ${a.defaultContext}` : ""}, disabled): ${a.description}`)]
-			: []),
 		"",
 		"Chains:",
 		...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"]),

package/agent-manager-list.ts

@@ -22,6 +22,12 @@ export interface ListState {
 	selected: string[];
 }
 
+export interface ListShortcuts {
+	newShortcut: string;
+}
+
+export const DEFAULT_AGENT_MANAGER_NEW_SHORTCUT = "shift+ctrl+n";
+
 export type ListAction =
 	| { type: "open-detail"; id: string }
 	| { type: "clone"; id: string }
@@ -57,7 +63,7 @@ function clampCursor(state: ListState, filtered: ListAgent[]): void {
 	}
 }
 
-export function handleListInput(state: ListState, agents: ListAgent[], data: string): ListAction | undefined {
+export function handleListInput(state: ListState, agents: ListAgent[], data: string, shortcuts: ListShortcuts = { newShortcut: DEFAULT_AGENT_MANAGER_NEW_SHORTCUT }): ListAction | undefined {
 	const filtered = fuzzyFilter(agents, state.filterQuery);
 
 	if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
@@ -98,7 +104,7 @@ export function handleListInput(state: ListState, agents: ListAgent[], data: str
 		return;
 	}
 
-	if (matchesKey(data, "alt+n")) {
+	if (matchesKey(data, shortcuts.newShortcut)) {
 		return { type: "new" };
 	}
 
@@ -160,6 +166,7 @@ export function renderList(
 	width: number,
 	theme: Theme,
 	statusMessage?: { text: string; type: "error" | "info" },
+	shortcuts: ListShortcuts = { newShortcut: DEFAULT_AGENT_MANAGER_NEW_SHORTCUT },
 ): string[] {
 	const lines: string[] = [];
 	const filtered = fuzzyFilter(agents, state.filterQuery);
@@ -269,7 +276,7 @@ export function renderList(
 		? ` [ctrl+r] chain  [ctrl+p] parallel  [tab] add  [shift+tab] remove  [esc] clear (${selCount}) `
 		: selCount === 1
 			? " [ctrl+r] run  [ctrl+p] parallel  [tab] add more  [shift+tab] remove  [esc] clear "
-			: " [enter] view  [ctrl+r] run  [tab] select  [alt+n] new  [esc] close ";
+			: ` [enter] view  [ctrl+r] run  [tab] select  [${shortcuts.newShortcut}] new  [esc] close `;
 	lines.push(renderFooter(footerText, width, theme));
 
 	return lines;

package/agent-manager.ts

@@ -18,7 +18,7 @@ import {
 import { serializeAgent } from "./agent-serializer.ts";
 import { TEMPLATE_ITEMS, type AgentTemplate, type TemplateItem } from "./agent-templates.ts";
 import { parseChain, serializeChain } from "./chain-serializer.ts";
-import { renderList, handleListInput, type ListAgent, type ListState, type ListAction } from "./agent-manager-list.ts";
+import { DEFAULT_AGENT_MANAGER_NEW_SHORTCUT, renderList, handleListInput, type ListAgent, type ListShortcuts, type ListState, type ListAction } from "./agent-manager-list.ts";
 import { createParallelState, handleParallelInput, renderParallel, formatParallelTitle, type ParallelState, type AgentOption } from "./agent-manager-parallel.ts";
 import { renderDetail, handleDetailInput, renderTaskInput, type DetailState, type DetailAction, type LaunchToggleState } from "./agent-manager-detail.ts";
 import { renderChainDetail, handleChainDetailInput, type ChainDetailAction, type ChainDetailState } from "./agent-manager-chain-detail.ts";
@@ -43,6 +43,7 @@ interface ChainEntry { id: string; kind: "chain"; config: ChainConfig; }
 interface NameInputState { mode: "new-agent" | "clone-agent" | "clone-chain" | "new-chain"; editor: TextEditorState; scope: "user" | "project"; allowProject: boolean; sourceId?: string; template?: AgentTemplate; error?: string; }
 interface StatusMessage { text: string; type: "error" | "info"; }
 interface OverrideScopeState { selectedScope: "user" | "project"; allowProject: boolean; }
+export interface AgentManagerOptions { newShortcut?: string; }
 
 const BUILTIN_OVERRIDE_FIELDS: EditField[] = ["model", "fallbackModels", "thinking", "systemPromptMode", "inheritProjectContext", "inheritSkills", "defaultContext", "disabled", "tools", "skills", "prompt"];
 
@@ -131,14 +132,16 @@ export class AgentManagerComponent implements Component {
 	private models: ModelInfo[];
 	private skills: SkillInfo[];
 	private done: (result: ManagerResult) => void;
+	private shortcuts: ListShortcuts;
 
-	constructor(tui: TUI, theme: Theme, agentData: AgentData, models: ModelInfo[], skills: SkillInfo[], done: (result: ManagerResult) => void) {
+	constructor(tui: TUI, theme: Theme, agentData: AgentData, models: ModelInfo[], skills: SkillInfo[], done: (result: ManagerResult) => void, options: AgentManagerOptions = {}) {
 		this.tui = tui;
 		this.theme = theme;
 		this.agentData = agentData;
 		this.models = models;
 		this.skills = skills;
 		this.done = done;
+		this.shortcuts = { newShortcut: options.newShortcut?.trim() || DEFAULT_AGENT_MANAGER_NEW_SHORTCUT };
 		this.loadEntries();
 	}
 
@@ -518,7 +521,7 @@ export class AgentManagerComponent implements Component {
 		if (this.screen === "list" && this.statusMessage) this.clearStatus();
 		if (this.screen.startsWith("edit") && this.editState?.error) this.editState.error = undefined;
 		switch (this.screen) {
-			case "list": { const action = handleListInput(this.listState, this.listAgents(), data); if (action) this.handleListAction(action); this.tui.requestRender(); return; }
+			case "list": { const action = handleListInput(this.listState, this.listAgents(), data, this.shortcuts); if (action) this.handleListAction(action); this.tui.requestRender(); return; }
 			case "template-select": this.handleTemplateSelectInput(data); return;
 			case "override-scope": this.handleOverrideScopeInput(data); return;
 			case "detail": {
@@ -671,14 +674,14 @@ export class AgentManagerComponent implements Component {
 	render(width: number): string[] {
 		this.overlayWidth = width; const w = this.overlayWidth;
 		switch (this.screen) {
-			case "list": return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage);
+			case "list": return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage, this.shortcuts);
 			case "template-select": return this.renderTemplateSelect(w);
 			case "override-scope": return this.renderOverrideScope(w);
-			case "detail": { const entry = this.getAgentEntry(this.currentAgentId); if (!entry) return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage); return renderDetail(this.detailState, entry.config, this.agentData.cwd, w, this.theme); }
-			case "chain-detail": { const entry = this.getChainEntry(this.currentChainId); if (!entry) return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage); return renderChainDetail(this.chainDetailState, entry.config, w, this.theme); }
+			case "detail": { const entry = this.getAgentEntry(this.currentAgentId); if (!entry) return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage, this.shortcuts); return renderDetail(this.detailState, entry.config, this.agentData.cwd, w, this.theme); }
+			case "chain-detail": { const entry = this.getChainEntry(this.currentChainId); if (!entry) return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage, this.shortcuts); return renderChainDetail(this.chainDetailState, entry.config, w, this.theme); }
 			case "edit": case "edit-field": case "edit-prompt": return this.editState ? renderEdit(this.screen as EditScreen, this.editState, w, this.theme) : [];
 			case "parallel-builder": {
-				if (!this.parallelState) return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage);
+				if (!this.parallelState) return renderList(this.listState, this.listAgents(), w, this.theme, this.statusMessage, this.shortcuts);
 				const agentOptions: AgentOption[] = this.agents.map((e) => ({ name: e.config.name, description: e.config.description, model: e.config.model }));
 				return renderParallel(this.parallelState, agentOptions, w, this.theme);
 			}

package/execution.ts

@@ -232,6 +232,8 @@ async function runSingleAttempt(
 		const HARD_KILL_MS = 3000;
 		let childExited = false;
 		let forcedTerminationSignal = false;
+		let finalAssistantDelivered = false;
+		let finalDrainCleanupWarning: string | undefined;
 		let finalDrainTimer: NodeJS.Timeout | undefined;
 		let finalHardKillTimer: NodeJS.Timeout | undefined;
 		const clearFinalDrainTimers = () => {
@@ -251,8 +253,8 @@ async function runSingleAttempt(
 				const termSent = trySignalChild(proc, "SIGTERM");
 				if (!termSent) return;
 				forcedTerminationSignal = true;
-				result.error = result.error
-					?? `Subagent process did not exit within ${FINAL_DRAIN_MS}ms after its final message. Forcing termination.`;
+				finalDrainCleanupWarning = `Subagent process did not exit within ${FINAL_DRAIN_MS}ms after its final message. Forcing termination.`;
+				if (!finalAssistantDelivered) result.error = result.error ?? finalDrainCleanupWarning;
 				finalHardKillTimer = setTimeout(() => {
 					if (settled || processClosed || detached) return;
 					forcedTerminationSignal = trySignalChild(proc, "SIGKILL") || forcedTerminationSignal;
@@ -462,7 +464,9 @@ async function runSingleAttempt(
 					const stopReason = (evt.message as { stopReason?: string }).stopReason;
 					const hasToolCall = Array.isArray(evt.message.content)
 						&& evt.message.content.some((part) => (part as { type?: string }).type === "toolCall");
+					const finalText = extractTextFromContent(evt.message.content).trim();
 					if (stopReason === "stop" && !hasToolCall) {
+						finalAssistantDelivered ||= !evt.message.errorMessage && finalText.length > 0;
 						startFinalDrain();
 					}
 				}
@@ -541,10 +545,14 @@ async function runSingleAttempt(
 			}
 			processClosed = true;
 			if (buf.trim()) processLine(buf);
-			if (code !== 0 && stderrBuf.trim() && !result.error) {
+			const forcedDrainAfterFinalSuccess = forcedTerminationSignal && finalAssistantDelivered;
+			if (code !== 0 && stderrBuf.trim() && !result.error && !forcedDrainAfterFinalSuccess) {
 				result.error = stderrBuf.trim();
 			}
-			const finalCode = forcedTerminationSignal || signal ? (code ?? 1) : (code ?? 0);
+			if (forcedDrainAfterFinalSuccess && finalDrainCleanupWarning) {
+				appendRecentOutput(progress, [`Warning: ${finalDrainCleanupWarning}`]);
+			}
+			const finalCode = forcedDrainAfterFinalSuccess ? 0 : forcedTerminationSignal || signal ? (code ?? 1) : (code ?? 0);
 			finish(finalCode);
 		});
 		proc.on("error", (error) => {

package/index.ts

@@ -9,7 +9,7 @@
  * Toggle: async parameter (default: false, configurable via config.json)
  *
  * Config file: ~/.pi/agent/extensions/subagent/config.json
- *   { "asyncByDefault": true, "forceTopLevelAsync": true, "maxSubagentDepth": 1, "intercomBridge": { "mode": "always", "instructionFile": "./intercom-bridge.md" }, "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
+ *   { "asyncByDefault": true, "forceTopLevelAsync": true, "maxSubagentDepth": 1, "agentManager": { "newShortcut": "shift+ctrl+n" }, "intercomBridge": { "mode": "always", "instructionFile": "./intercom-bridge.md" }, "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
  */
 
 import * as fs from "node:fs";
@@ -418,7 +418,7 @@ CHAIN TEMPLATE VARIABLES (use in task strings):
 Example: { chain: [{agent:"agent-a", task:"Analyze {task}"}, {agent:"agent-b", task:"Plan based on {previous}"}] }
 
 MANAGEMENT (use action field, omit agent/task/chain/tasks):
-• { action: "list" } - discover executable agents/chains and any disabled builtins
+• { action: "list" } - discover executable agents/chains
 • { action: "get", agent: "name" } - full detail
 • { action: "create", config: { name, systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext, ... } }
 • { action: "update", agent: "name", config: { ... } } - merge
@@ -475,7 +475,7 @@ DIAGNOSTICS:
 	};
 
 	pi.registerTool(tool);
-	registerSlashCommands(pi, state);
+	registerSlashCommands(pi, state, config);
 
 	const eventUnsubscribeStoreKey = "__piSubagentEventUnsubscribes";
 	const controlNoticeSeenStoreKey = "__piSubagentVisibleControlNotices";

package/intercom-bridge.ts

@@ -4,9 +4,18 @@ import * as path from "node:path";
 import type { AgentConfig } from "./agents.ts";
 import type { ExtensionConfig, IntercomBridgeConfig, IntercomBridgeMode } from "./types.ts";
 
-const DEFAULT_INTERCOM_EXTENSION_DIR = path.join(os.homedir(), ".pi", "agent", "extensions", "pi-intercom");
-const DEFAULT_INTERCOM_CONFIG_PATH = path.join(os.homedir(), ".pi", "agent", "intercom", "config.json");
-const DEFAULT_SUBAGENT_CONFIG_DIR = path.join(os.homedir(), ".pi", "agent", "extensions", "subagent");
+function defaultIntercomExtensionDir(): string {
+	return path.join(os.homedir(), ".pi", "agent", "extensions", "pi-intercom");
+}
+
+function defaultIntercomConfigPath(): string {
+	return path.join(os.homedir(), ".pi", "agent", "intercom", "config.json");
+}
+
+function defaultSubagentConfigDir(): string {
+	return path.join(os.homedir(), ".pi", "agent", "extensions", "subagent");
+}
+
 const DEFAULT_INTERCOM_TARGET_PREFIX = "subagent-chat";
 export const INTERCOM_BRIDGE_MARKER = "Intercom orchestration channel:";
 const DEFAULT_INTERCOM_BRIDGE_TEMPLATE = `The inherited thread is reference-only. Do not continue that conversation or send questions, status updates, or completion handoffs to the orchestrator in normal assistant text.
@@ -135,9 +144,9 @@ ${instruction}`;
 export function diagnoseIntercomBridge(input: ResolveIntercomBridgeInput): IntercomBridgeDiagnostic {
 	const config = resolveIntercomBridgeConfig(input.config);
 	const mode = config.mode;
-	const extensionDir = path.resolve(input.extensionDir ?? DEFAULT_INTERCOM_EXTENSION_DIR);
+	const extensionDir = path.resolve(input.extensionDir ?? defaultIntercomExtensionDir());
 	const orchestratorTarget = input.orchestratorTarget?.trim();
-	const configPath = path.resolve(input.configPath ?? DEFAULT_INTERCOM_CONFIG_PATH);
+	const configPath = path.resolve(input.configPath ?? defaultIntercomConfigPath());
 	const wantsIntercom = mode !== "off" && !(mode === "fork-only" && input.context !== "fork");
 	const piIntercomAvailable = fs.existsSync(extensionDir);
 	let configStatus: ReturnType<typeof intercomConfigStatus> | undefined;
@@ -173,9 +182,9 @@ export function diagnoseIntercomBridge(input: ResolveIntercomBridgeInput): Inter
 export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): IntercomBridgeState {
 	const config = resolveIntercomBridgeConfig(input.config);
 	const mode = config.mode;
-	const extensionDir = path.resolve(input.extensionDir ?? DEFAULT_INTERCOM_EXTENSION_DIR);
+	const extensionDir = path.resolve(input.extensionDir ?? defaultIntercomExtensionDir());
 	const orchestratorTarget = input.orchestratorTarget?.trim();
-	const settingsDir = path.resolve(input.settingsDir ?? DEFAULT_SUBAGENT_CONFIG_DIR);
+	const settingsDir = path.resolve(input.settingsDir ?? defaultSubagentConfigDir());
 	const defaultInstruction = buildIntercomBridgeInstruction(
 		orchestratorTarget || "{orchestratorTarget}",
 		DEFAULT_INTERCOM_BRIDGE_TEMPLATE,
@@ -194,7 +203,7 @@ export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): Interc
 		return { active: false, mode, extensionDir, instruction: defaultInstruction };
 	}
 
-	const configPath = path.resolve(input.configPath ?? DEFAULT_INTERCOM_CONFIG_PATH);
+	const configPath = path.resolve(input.configPath ?? defaultIntercomConfigPath());
 	const intercomStatus = intercomConfigStatus(configPath);
 	if (intercomStatus.error) console.warn(`Failed to parse intercom config at '${configPath}'. Assuming enabled.`, intercomStatus.error);
 	if (!intercomStatus.enabled) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",

package/result-watcher.ts

@@ -13,11 +13,36 @@ import {
 	resolveSubagentResultStatus,
 } from "./result-intercom.ts";
 
+const WATCHER_RESTART_DELAY_MS = 3000;
+const POLL_INTERVAL_MS = 3000;
+
+type ResultWatcherFs = Pick<typeof fs, "existsSync" | "readFileSync" | "unlinkSync" | "readdirSync" | "mkdirSync" | "watch">;
+
+type ResultWatcherTimers = {
+	setTimeout: typeof setTimeout;
+	clearTimeout: typeof clearTimeout;
+	setInterval: typeof setInterval;
+	clearInterval: typeof clearInterval;
+};
+
+type ResultWatcherDeps = {
+	fs?: ResultWatcherFs;
+	timers?: ResultWatcherTimers;
+};
+
+function getErrorCode(error: unknown): string | undefined {
+	return typeof error === "object" && error !== null && "code" in error
+		? (error as NodeJS.ErrnoException).code
+		: undefined;
+}
+
 function isNotFoundError(error: unknown): boolean {
-	return typeof error === "object"
-		&& error !== null
-		&& "code" in error
-		&& (error as NodeJS.ErrnoException).code === "ENOENT";
+	return getErrorCode(error) === "ENOENT";
+}
+
+function shouldFallBackToPolling(error: unknown): boolean {
+	const code = getErrorCode(error);
+	return code === "EMFILE" || code === "ENOSPC";
 }
 
 export function createResultWatcher(
@@ -25,16 +50,20 @@ export function createResultWatcher(
 	state: SubagentState,
 	resultsDir: string,
 	completionTtlMs: number,
+	deps: ResultWatcherDeps = {},
 ): {
 	startResultWatcher: () => void;
 	primeExistingResults: () => void;
 	stopResultWatcher: () => void;
 } {
+	const fsApi = deps.fs ?? fs;
+	const timers = deps.timers ?? { setTimeout, clearTimeout, setInterval, clearInterval };
+
 	const handleResult = async (file: string) => {
 		const resultPath = path.join(resultsDir, file);
-		if (!fs.existsSync(resultPath)) return;
+		if (!fsApi.existsSync(resultPath)) return;
 		try {
-			const data = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as {
+			const data = JSON.parse(fsApi.readFileSync(resultPath, "utf-8")) as {
 				id?: string;
 				runId?: string;
 				agent?: string;
@@ -62,7 +91,7 @@ export function createResultWatcher(
 			const now = Date.now();
 			const completionKey = buildCompletionKey(data, `result:${file}`);
 			if (markSeenWithTtl(state.completionSeen, completionKey, now, completionTtlMs)) {
-				fs.unlinkSync(resultPath);
+				fsApi.unlinkSync(resultPath);
 				return;
 			}
 
@@ -114,7 +143,7 @@ export function createResultWatcher(
 			}
 
 			pi.events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, data);
-			fs.unlinkSync(resultPath);
+			fsApi.unlinkSync(resultPath);
 		} catch (error) {
 			if (isNotFoundError(error)) return;
 			console.error(`Failed to process subagent result file '${resultPath}':`, error);
@@ -125,50 +154,91 @@ export function createResultWatcher(
 		void handleResult(file);
 	}, 50);
 
+	const primeExistingResults = () => {
+		try {
+			fsApi.readdirSync(resultsDir)
+				.filter((f) => f.endsWith(".json"))
+				.forEach((file) => state.resultFileCoalescer.schedule(file, 0));
+		} catch (error) {
+			if (isNotFoundError(error)) return;
+			console.error(`Failed to scan subagent result directory '${resultsDir}':`, error);
+		}
+	};
+
+	const startPollingFallback = (reason: unknown) => {
+		state.watcher?.close();
+		state.watcher = null;
+		if (state.watcherRestartTimer) return;
+
+		console.error(
+			`Subagent result watcher for '${resultsDir}' fell back to polling because native fs.watch is unavailable (${getErrorCode(reason) ?? "unknown error"}).`,
+		);
+		primeExistingResults();
+		state.watcherRestartTimer = timers.setInterval(primeExistingResults, POLL_INTERVAL_MS);
+		state.watcherRestartTimer.unref?.();
+	};
+
 	const scheduleRestart = () => {
-		state.watcherRestartTimer = setTimeout(() => {
+		if (state.watcherRestartTimer) return;
+		state.watcherRestartTimer = timers.setTimeout(() => {
+			state.watcherRestartTimer = null;
 			try {
-				fs.mkdirSync(resultsDir, { recursive: true });
+				fsApi.mkdirSync(resultsDir, { recursive: true });
 				startResultWatcher();
 			} catch (error) {
+				if (shouldFallBackToPolling(error)) {
+					startPollingFallback(error);
+					return;
+				}
 				console.error(`Failed to restart subagent result watcher for '${resultsDir}':`, error);
+				scheduleRestart();
 			}
-		}, 3000);
+		}, WATCHER_RESTART_DELAY_MS);
+		state.watcherRestartTimer.unref?.();
 	};
 
 	const startResultWatcher = () => {
-		state.watcherRestartTimer = null;
+		if (state.watcher) return;
+		if (state.watcherRestartTimer) {
+			timers.clearTimeout(state.watcherRestartTimer);
+			timers.clearInterval(state.watcherRestartTimer);
+			state.watcherRestartTimer = null;
+		}
 		try {
-			state.watcher = fs.watch(resultsDir, (ev, file) => {
+			state.watcher = fsApi.watch(resultsDir, (ev, file) => {
 				if (ev !== "rename" || !file) return;
 				const fileName = file.toString();
 				if (!fileName.endsWith(".json")) return;
 				state.resultFileCoalescer.schedule(fileName);
 			});
 			state.watcher.on("error", (error) => {
+				if (shouldFallBackToPolling(error)) {
+					startPollingFallback(error);
+					return;
+				}
 				console.error(`Subagent result watcher failed for '${resultsDir}':`, error);
+				state.watcher?.close();
 				state.watcher = null;
 				scheduleRestart();
 			});
 			state.watcher.unref?.();
 		} catch (error) {
+			if (shouldFallBackToPolling(error)) {
+				startPollingFallback(error);
+				return;
+			}
 			console.error(`Failed to start subagent result watcher for '${resultsDir}':`, error);
 			state.watcher = null;
 			scheduleRestart();
 		}
 	};
 
-	const primeExistingResults = () => {
-		fs.readdirSync(resultsDir)
-			.filter((f) => f.endsWith(".json"))
-			.forEach((file) => state.resultFileCoalescer.schedule(file, 0));
-	};
-
 	const stopResultWatcher = () => {
 		state.watcher?.close();
 		state.watcher = null;
 		if (state.watcherRestartTimer) {
-			clearTimeout(state.watcherRestartTimer);
+			timers.clearTimeout(state.watcherRestartTimer);
+			timers.clearInterval(state.watcherRestartTimer);
 		}
 		state.watcherRestartTimer = null;
 		state.resultFileCoalescer.clear();

package/skills/pi-subagents/SKILL.md

@@ -44,6 +44,7 @@ Packaged prompt shortcuts are also available for repeatable workflows:
 - `/parallel-review` — fresh-context reviewers with distinct review angles, then synthesis
 - `/parallel-research` — combine `researcher` and `scout` for external evidence plus local code context
 - `/gather-context-and-clarify` — scout/research first, then ask the user clarifying questions with `interview`
+- `/parallel-cleanup` — two fresh-context reviewers (deslop + verbosity passes) for an adversarial cleanup review of the current diff
 
 ## Builtin Agents
 
@@ -439,8 +440,9 @@ copying a full builtin file.
 ## Prompt Template Integration
 
 The package includes prompt shortcuts for common workflows: `/parallel-review`,
-`/parallel-research`, and `/gather-context-and-clarify`. Use them when the user
-wants repeatable review, research, or clarification patterns.
+`/parallel-research`, `/gather-context-and-clarify`, and `/parallel-cleanup`.
+Use them when the user wants repeatable review, research, clarification, or
+cleanup-review patterns.
 
 If `pi-prompt-template-model` is installed, additional user prompt templates can delegate into
 `pi-subagents`. This is useful when a slash command should always run through a

package/slash-commands.ts

@@ -23,6 +23,7 @@ import {
 	SLASH_SUBAGENT_RESPONSE_EVENT,
 	SLASH_SUBAGENT_STARTED_EVENT,
 	SLASH_SUBAGENT_UPDATE_EVENT,
+	type ExtensionConfig,
 	type SingleResult,
 	type SubagentState,
 } from "./types.ts";
@@ -324,6 +325,7 @@ async function runSlashSubagent(
 async function openAgentManager(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
+	config: ExtensionConfig = {},
 ): Promise<void> {
 	const agentData = { ...discoverAgentsAll(ctx.cwd), cwd: ctx.cwd };
 	const models = ctx.modelRegistry.getAvailable().map((m) => ({
@@ -334,7 +336,7 @@ async function openAgentManager(
 	const skills = discoverAvailableSkills(ctx.cwd);
 
 	const result = await ctx.ui.custom<ManagerResult>(
-		(tui, theme, _kb, done) => new AgentManagerComponent(tui, theme, agentData, models, skills, done),
+		(tui, theme, _kb, done) => new AgentManagerComponent(tui, theme, agentData, models, skills, done, { newShortcut: config.agentManager?.newShortcut }),
 		{ overlay: true, overlayOptions: { anchor: "center", width: 84, maxHeight: "80%" } },
 	);
 	if (!result) return;
@@ -448,11 +450,12 @@ const parseAgentArgs = (
 export function registerSlashCommands(
 	pi: ExtensionAPI,
 	state: SubagentState,
+	config: ExtensionConfig = {},
 ): void {
 	pi.registerCommand("agents", {
 		description: "Open the Agents Manager",
 		handler: async (_args, ctx) => {
-			await openAgentManager(pi, ctx);
+			await openAgentManager(pi, ctx, config);
 		},
 	});
 
@@ -578,7 +581,7 @@ export function registerSlashCommands(
 
 	pi.registerShortcut("ctrl+shift+a", {
 		handler: async (ctx) => {
-			await openAgentManager(pi, ctx);
+			await openAgentManager(pi, ctx, config);
 		},
 	});
 }

package/subagent-runner.ts

@@ -282,7 +282,11 @@ function runPiStreaming(
 				const stopReason = (event.message as { stopReason?: string }).stopReason;
 				const hasToolCall = Array.isArray(event.message.content)
 					&& event.message.content.some((part) => (part as { type?: string }).type === "toolCall");
-				if (stopReason === "stop" && !hasToolCall) startFinalDrain();
+				const finalText = extractTextFromContent(event.message.content).trim();
+				if (stopReason === "stop" && !hasToolCall) {
+					finalAssistantDelivered ||= !event.message.errorMessage && finalText.length > 0;
+					startFinalDrain();
+				}
 			}
 		};
 
@@ -305,6 +309,8 @@ function runPiStreaming(
 		const HARD_KILL_MS = 3000;
 		let childExited = false;
 		let forcedTerminationSignal = false;
+		let finalAssistantDelivered = false;
+		let finalDrainCleanupWarning: string | undefined;
 		let finalDrainTimer: NodeJS.Timeout | undefined;
 		let finalHardKillTimer: NodeJS.Timeout | undefined;
 		let settled = false;
@@ -346,8 +352,9 @@ function runPiStreaming(
 				const termSent = trySignalChild(child, "SIGTERM");
 				if (!termSent) return;
 				forcedTerminationSignal = true;
-				if (!error) {
-					error = `Subagent process did not exit within ${FINAL_DRAIN_MS}ms after its final message. Forcing termination.`;
+				finalDrainCleanupWarning = `Subagent process did not exit within ${FINAL_DRAIN_MS}ms after its final message. Forcing termination.`;
+				if (!finalAssistantDelivered && !error) {
+					error = finalDrainCleanupWarning;
 				}
 				finalHardKillTimer = setTimeout(() => {
 					if (settled) return;
@@ -370,13 +377,14 @@ function runPiStreaming(
 			if (stderrBuf.trim()) appendChildLine("subagent.child.stderr", stderrBuf);
 			outputStream.end();
 			const finalOutput = getFinalOutput(messages) || rawStdoutLines.join("\n").trim();
+			const forcedDrainAfterFinalSuccess = forcedTerminationSignal && finalAssistantDelivered;
 			resolve({
 				stderr,
-				exitCode: interrupted ? 0 : forcedTerminationSignal || signal ? (exitCode ?? 1) : exitCode,
+				exitCode: interrupted || forcedDrainAfterFinalSuccess ? 0 : forcedTerminationSignal || signal ? (exitCode ?? 1) : exitCode,
 				messages,
 				usage,
 				model,
-				error: interrupted ? undefined : error,
+				error: interrupted || forcedDrainAfterFinalSuccess ? undefined : error,
 				finalOutput,
 				interrupted,
 				observedMutationAttempt,

package/types.ts

@@ -445,6 +445,10 @@ interface TopLevelParallelConfig {
 	concurrency?: number;
 }
 
+interface AgentManagerConfig {
+	newShortcut?: string;
+}
+
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
 	forceTopLevelAsync?: boolean;
@@ -452,6 +456,7 @@ export interface ExtensionConfig {
 	maxSubagentDepth?: number;
 	control?: ControlConfig;
 	parallel?: TopLevelParallelConfig;
+	agentManager?: AgentManagerConfig;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
 	intercomBridge?: IntercomBridgeConfig;