pi-subagents 0.13.1 → 0.13.3

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [0.13.3] - 2026-04-13
+
+### Added
+- Added `intercomBridge.instructionFile` so subagent intercom guidance can be overridden from a Markdown template with `{orchestratorTarget}` interpolation.
+
+### Fixed
+- Intercom-enabled delegated runs now detach only after the child actually starts the `intercom` tool, preserving clean sync behavior until coordination is needed.
+- Graceful intercom coordination no longer leaves detached child runs vulnerable to later parent abort listeners, and reply confirmation follow-ups avoid unnecessary orchestrator aborts.
+- Child process spawn failures now preserve the original error message instead of collapsing to a generic failure.
+
+## [0.13.2] - 2026-04-13
+
+### Changed
+- `intercomBridge` now defaults to `always` so intercom coordination instructions are injected for both `fresh` and `fork` delegated runs when `pi-intercom` is available.
+
 ## [0.13.1] - 2026-04-13
 
 ### Added

package/README.md

@@ -14,12 +14,6 @@ https://github.com/user-attachments/assets/702554ec-faaf-4635-80aa-fb5d6e292fd1
 pi install npm:pi-subagents
 ```
 
-To remove:
-
-```bash
-npx pi-subagents --remove
-```
-
 If you use [pi-prompt-template-model](https://github.com/nicobailon/pi-prompt-template-model), you can wrap subagent delegation in a slash command:
 
 ```markdown
@@ -331,7 +325,7 @@ Chains can be created from the Agents Manager template picker ("Blank Chain"), o
 | Parallel | Yes | `{ tasks: [{agent, task}...] }` - via TUI toggle or converted to chain for async |
 
 Execution context defaults to `context: "fresh"`, which starts each child run from a clean session. Set `context: "fork"` to start each child from a real branched session created from the parent's current leaf.
-When `intercomBridge` is enabled (default: `fork-only`) and `pi-intercom` is installed/enabled, forked children get runtime instructions for contacting the orchestrator session via `intercom({ action: "ask"|"send", ... })`.
+When `intercomBridge` is enabled (default: `always`) and `pi-intercom` is installed/enabled, delegated children get runtime instructions for contacting the orchestrator session via `intercom({ action: "ask"|"send", ... })`.
 
 > **Note:** Intercom bridging requires the [pi-intercom](https://github.com/nicobailon/pi-intercom) extension. Install it with `pi install npm:pi-intercom`.
 
@@ -787,19 +781,34 @@ Controls whether subagents receive runtime intercom coordination instructions (a
 
 ```json
 {
-  "intercomBridge": "fork-only"
+	"intercomBridge": {
+		"mode": "always",
+		"instructionFile": "./intercom-bridge.md"
+	}
 }
 ```
 
-Values:
-- `"fork-only"` (default): inject intercom bridge only when `context: "fork"`
-- `"always"`: inject bridge in both `fresh` and `fork`
-- `"off"`: disable bridge entirely
+Fields:
+- `"mode"` (default: `"always"`): inject bridge in both `fresh` and `fork`, only in `fork`, or disable it entirely
+- `"instructionFile"` (optional): path to a Markdown template that replaces the default injected subagent intercom instructions. Supports `{orchestratorTarget}` placeholder interpolation. Relative paths resolve from `~/.pi/agent/extensions/subagent/`.
+
+Example `instructionFile`:
+
+```md
+Intercom orchestration channel:
+
+Use `intercom` only to coordinate with the orchestrator session `{orchestratorTarget}`.
+
+- Need a decision or you're blocked: `intercom({ action: "ask", to: "{orchestratorTarget}", message: "<question>" })`
+- Need to report progress or completion: `intercom({ action: "send", to: "{orchestratorTarget}", message: "DONE: <summary>" })`
+
+If intercom is unavailable in this run, continue the task normally.
+```
 
 Bridge activation also requires all of the following:
 - [pi-intercom](https://github.com/nicobailon/pi-intercom) is installed (`pi install npm:pi-intercom`)
 - `~/.pi/agent/intercom/config.json` is not set to `"enabled": false`
-- the current session has a name to target as orchestrator
+- the current session has a target name (existing `/name`, or auto-assigned `session-<id>` when unnamed)
 - if agent `extensions` is an explicit allowlist, it must include `pi-intercom`
 
 ### `worktreeSetupHook`

package/execution.ts

@@ -19,6 +19,8 @@ import {
 	type SingleResult,
 	type Usage,
 	DEFAULT_MAX_OUTPUT,
+	INTERCOM_DETACH_REQUEST_EVENT,
+	INTERCOM_DETACH_RESPONSE_EVENT,
 	truncateOutput,
 	getSubagentDepthEnv,
 } from "./types.ts";
@@ -123,7 +125,6 @@ async function runSingleAttempt(
 	const startTime = Date.now();
 	const spawnEnv = { ...process.env, ...sharedEnv, ...getSubagentDepthEnv(options.maxSubagentDepth) };
 
-	let closeJsonlWriter: (() => Promise<void>) | undefined;
 	const exitCode = await new Promise<number>((resolve) => {
 		const spawnSpec = getPiSpawnCommand(args);
 		const proc = spawn(spawnSpec.command, spawnSpec.args, {
@@ -132,9 +133,46 @@ async function runSingleAttempt(
 			stdio: ["ignore", "pipe", "pipe"],
 		});
 		const jsonlWriter = createJsonlWriter(shared.jsonlPath, proc.stdout);
-		closeJsonlWriter = () => jsonlWriter.close();
 		let buf = "";
 		let processClosed = false;
+		let settled = false;
+		let detached = false;
+		let intercomStarted = false;
+		let removeAbortListener: (() => void) | undefined;
+
+		const detachForIntercom = () => {
+			detached = true;
+			processClosed = true;
+			result.detached = true;
+			result.detachedReason = "intercom coordination";
+			progress.status = "detached";
+			progress.durationMs = Date.now() - startTime;
+			result.progressSummary = {
+				toolCount: progress.toolCount,
+				tokens: progress.tokens,
+				durationMs: progress.durationMs,
+			};
+			finish(-2);
+		};
+
+		const unsubscribeIntercomDetach = options.intercomEvents?.on(INTERCOM_DETACH_REQUEST_EVENT, (payload) => {
+			if (!options.allowIntercomDetach || detached || processClosed) return;
+			if (!payload || typeof payload !== "object") return;
+			const requestId = (payload as { requestId?: unknown }).requestId;
+			if (typeof requestId !== "string" || requestId.length === 0) return;
+			const accepted = intercomStarted;
+			options.intercomEvents?.emit(INTERCOM_DETACH_RESPONSE_EVENT, { requestId, accepted });
+			if (!accepted) return;
+			detachForIntercom();
+		});
+
+		const finish = (code: number) => {
+			if (settled) return;
+			settled = true;
+			unsubscribeIntercomDetach?.();
+			removeAbortListener?.();
+			resolve(code);
+		};
 
 		const fireUpdate = () => {
 			if (!options.onUpdate || processClosed) return;
@@ -154,6 +192,9 @@ async function runSingleAttempt(
 				progress.durationMs = now - startTime;
 
 				if (evt.type === "tool_execution_start") {
+					if (options.allowIntercomDetach && evt.toolName === "intercom") {
+						intercomStarted = true;
+					}
 					progress.toolCount++;
 					progress.currentTool = evt.toolName;
 					progress.currentToolArgs = extractToolArgsPreview((evt.args || {}) as Record<string, unknown>);
@@ -215,35 +256,55 @@ async function runSingleAttempt(
 			stderrBuf += d.toString();
 		});
 		proc.on("close", (code) => {
+			void jsonlWriter.close().catch(() => {
+				// JSONL artifact flush is best effort.
+			});
+			cleanupTempDir(tempDir);
+			if (detached) {
+				finish(-2);
+				return;
+			}
 			processClosed = true;
 			if (buf.trim()) processLine(buf);
 			if (code !== 0 && stderrBuf.trim() && !result.error) {
 				result.error = stderrBuf.trim();
 			}
-			resolve(code ?? 0);
+			finish(code ?? 0);
+		});
+		proc.on("error", (error) => {
+			void jsonlWriter.close().catch(() => {
+				// JSONL artifact flush is best effort.
+			});
+			cleanupTempDir(tempDir);
+			if (!result.error) {
+				result.error = error instanceof Error ? error.message : String(error);
+			}
+			finish(1);
 		});
-		proc.on("error", () => resolve(1));
 
 		if (options.signal) {
 			const kill = () => {
+				if (processClosed || detached) return;
+				if (options.allowIntercomDetach && intercomStarted && !detached) {
+					detachForIntercom();
+					return;
+				}
 				proc.kill("SIGTERM");
 				setTimeout(() => !proc.killed && proc.kill("SIGKILL"), 3000);
 			};
 			if (options.signal.aborted) kill();
-			else options.signal.addEventListener("abort", kill, { once: true });
+			else {
+				options.signal.addEventListener("abort", kill, { once: true });
+				removeAbortListener = () => options.signal?.removeEventListener("abort", kill);
+			}
 		}
 	});
-
-	if (closeJsonlWriter) {
-		try {
-			await closeJsonlWriter();
-		} catch {
-			// JSONL artifact flush is best effort.
-		}
-	}
-
-	cleanupTempDir(tempDir);
 	result.exitCode = exitCode;
+	if (result.detached) {
+		result.exitCode = 0;
+		result.finalOutput = "Detached for intercom coordination.";
+		return result;
+	}
 
 	if (exitCode === 0 && !result.error) {
 		const errInfo = detectSubagentError(result.messages);

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, "maxSubagentDepth": 1, "intercomBridge": "fork-only", "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
+ *   { "asyncByDefault": true, "maxSubagentDepth": 1, "intercomBridge": { "mode": "always", "instructionFile": "./intercom-bridge.md" }, "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
  */
 
 import * as fs from "node:fs";

package/intercom-bridge.ts

@@ -2,32 +2,50 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentConfig } from "./agents.ts";
-import type { ExtensionConfig } from "./types.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");
 const INTERCOM_BRIDGE_MARKER = "Intercom orchestration channel:";
-
-export type IntercomBridgeMode = NonNullable<ExtensionConfig["intercomBridge"]>;
+const DEFAULT_INTERCOM_BRIDGE_TEMPLATE = `Use intercom only for coordination with the orchestrator session:
+- Need a decision or blocked: intercom({ action: "ask", to: "{orchestratorTarget}", message: "<question>" })
+- Completion/update: intercom({ action: "send", to: "{orchestratorTarget}", message: "DONE: <summary>" })
+If intercom is unavailable in this run, continue the task normally.`;
 
 export interface IntercomBridgeState {
 	active: boolean;
 	mode: IntercomBridgeMode;
 	orchestratorTarget?: string;
 	extensionDir: string;
+	instruction: string;
 }
 
 interface ResolveIntercomBridgeInput {
-	mode: unknown;
+	config: ExtensionConfig["intercomBridge"];
 	context: "fresh" | "fork" | undefined;
 	orchestratorTarget?: string;
 	extensionDir?: string;
 	configPath?: string;
+	settingsDir?: string;
 }
 
 export function resolveIntercomBridgeMode(value: unknown): IntercomBridgeMode {
 	if (value === "off" || value === "always" || value === "fork-only") return value;
-	return "fork-only";
+	return "always";
+}
+
+function resolveIntercomBridgeConfig(value: ExtensionConfig["intercomBridge"]): Required<IntercomBridgeConfig> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return {
+			mode: "always",
+			instructionFile: "",
+		};
+	}
+	return {
+		mode: resolveIntercomBridgeMode(value.mode),
+		instructionFile: typeof value.instructionFile === "string" ? value.instructionFile : "",
+	};
 }
 
 function intercomEnabled(configPath: string): boolean {
@@ -43,51 +61,84 @@ function intercomEnabled(configPath: string): boolean {
 
 function extensionSandboxAllowsIntercom(extensions: string[] | undefined, extensionDir: string): boolean {
 	if (extensions === undefined) return true;
-	const lowerExtensionDir = extensionDir.toLowerCase();
-	return extensions.some((entry) => {
-		const normalized = entry.toLowerCase();
-		if (normalized.includes(lowerExtensionDir)) return true;
-		return /(^|[\\/])pi-intercom([\\/]|$)/i.test(normalized);
-	});
+
+	const intercomDir = path.resolve(extensionDir).replaceAll("\\", "/").toLowerCase();
+	for (const entry of extensions) {
+		const normalized = entry.trim().replaceAll("\\", "/").toLowerCase();
+		if (normalized === "pi-intercom") return true;
+		if (normalized === intercomDir) return true;
+		if (normalized.startsWith(`${intercomDir}/`)) return true;
+		if (normalized.endsWith("/pi-intercom")) return true;
+		if (normalized.includes("/pi-intercom/")) return true;
+	}
+	return false;
 }
 
-function buildIntercomBridgeInstruction(orchestratorTarget: string): string {
-	const escapedTarget = JSON.stringify(orchestratorTarget);
+function expandTilde(filePath: string): string {
+	return filePath.startsWith("~/") ? path.join(os.homedir(), filePath.slice(2)) : filePath;
+}
+
+function resolveInstructionTemplate(instructionFile: string, settingsDir: string): string {
+	if (!instructionFile) return DEFAULT_INTERCOM_BRIDGE_TEMPLATE;
+	const expandedPath = expandTilde(instructionFile);
+	const resolvedPath = path.isAbsolute(expandedPath)
+		? expandedPath
+		: path.resolve(settingsDir, expandedPath);
+	try {
+		return fs.readFileSync(resolvedPath, "utf-8");
+	} catch (error) {
+		console.warn(`Failed to read intercom bridge instructionFile at '${resolvedPath}'. Using default instructions.`, error);
+		return DEFAULT_INTERCOM_BRIDGE_TEMPLATE;
+	}
+}
+
+function buildIntercomBridgeInstruction(orchestratorTarget: string, template: string): string {
+	const instruction = template.replaceAll("{orchestratorTarget}", orchestratorTarget).trim();
+	if (instruction.startsWith(INTERCOM_BRIDGE_MARKER)) return instruction;
 	return `${INTERCOM_BRIDGE_MARKER}
-Use intercom only for coordination with the orchestrator session:
-- Need a decision or blocked: intercom({ action: "ask", to: ${escapedTarget}, message: "<question>" })
-- Completion/update: intercom({ action: "send", to: ${escapedTarget}, message: "DONE: <summary>" })
-If intercom is unavailable in this run, continue the task normally.`;
+${instruction}`;
 }
 
 export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): IntercomBridgeState {
-	const mode = resolveIntercomBridgeMode(input.mode);
+	const config = resolveIntercomBridgeConfig(input.config);
+	const mode = config.mode;
 	const extensionDir = path.resolve(input.extensionDir ?? DEFAULT_INTERCOM_EXTENSION_DIR);
 	const orchestratorTarget = input.orchestratorTarget?.trim();
+	const settingsDir = path.resolve(input.settingsDir ?? DEFAULT_SUBAGENT_CONFIG_DIR);
+	const defaultInstruction = buildIntercomBridgeInstruction(
+		orchestratorTarget || "{orchestratorTarget}",
+		DEFAULT_INTERCOM_BRIDGE_TEMPLATE,
+	);
 
 	if (mode === "off") {
-		return { active: false, mode, extensionDir };
+		return { active: false, mode, extensionDir, instruction: defaultInstruction };
 	}
 	if (mode === "fork-only" && input.context !== "fork") {
-		return { active: false, mode, extensionDir };
+		return { active: false, mode, extensionDir, instruction: defaultInstruction };
 	}
 	if (!orchestratorTarget) {
-		return { active: false, mode, extensionDir };
+		return { active: false, mode, extensionDir, instruction: defaultInstruction };
 	}
 	if (!fs.existsSync(extensionDir)) {
-		return { active: false, mode, extensionDir };
+		return { active: false, mode, extensionDir, instruction: defaultInstruction };
 	}
 
 	const configPath = path.resolve(input.configPath ?? DEFAULT_INTERCOM_CONFIG_PATH);
 	if (!intercomEnabled(configPath)) {
-		return { active: false, mode, extensionDir };
+		return { active: false, mode, extensionDir, instruction: defaultInstruction };
 	}
 
+	const instruction = buildIntercomBridgeInstruction(
+		orchestratorTarget,
+		resolveInstructionTemplate(config.instructionFile, settingsDir),
+	);
+
 	return {
 		active: true,
 		mode,
 		orchestratorTarget,
 		extensionDir,
+		instruction,
 	};
 }
 
@@ -98,7 +149,7 @@ export function applyIntercomBridgeToAgent(agent: AgentConfig, bridge: IntercomB
 	const tools = agent.tools && !agent.tools.includes("intercom")
 		? [...agent.tools, "intercom"]
 		: agent.tools;
-	const instruction = buildIntercomBridgeInstruction(bridge.orchestratorTarget);
+	const instruction = bridge.instruction;
 	const trimmedPrompt = agent.systemPrompt?.trim() || "";
 	const systemPrompt = trimmedPrompt.includes(INTERCOM_BRIDGE_MARKER)
 		? trimmedPrompt

package/package.json

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

package/render.ts

@@ -195,9 +195,11 @@ export function renderSubagentResult(
 		const isRunning = r.progress?.status === "running";
 		const icon = isRunning
 			? theme.fg("warning", "...")
-			: r.exitCode === 0
-				? theme.fg("success", "ok")
-				: theme.fg("error", "X");
+			: r.detached
+				? theme.fg("warning", "↗")
+				: r.exitCode === 0
+					? theme.fg("success", "ok")
+					: theme.fg("error", "X");
 		const contextBadge = d.context === "fork" ? theme.fg("warning", " [fork]") : "";
 		const output = r.truncation?.text || getSingleResultOutput(r);
 

package/subagent-executor.ts

@@ -995,6 +995,8 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	const r = await runSync(ctx.cwd, agents, params.agent!, task, {
 		cwd: params.cwd,
 		signal,
+		allowIntercomDetach: agentConfig.systemPrompt?.includes("Intercom orchestration channel:") === true,
+		intercomEvents: deps.pi.events,
 		runId,
 		sessionDir: sessionDirForIndex(0),
 		sessionFile: sessionFileForIndex(0),
@@ -1024,6 +1026,19 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		saveError: r.outputSaveError,
 	});
 
+	if (r.detached) {
+		return {
+			content: [{ type: "text", text: `Detached for intercom coordination: ${params.agent}` }],
+			details: {
+				mode: "single",
+				results: [r],
+				progress: params.includeProgress ? allProgress : undefined,
+				artifacts: allArtifactPaths.length ? { dir: artifactsDir, files: allArtifactPaths } : undefined,
+				truncation: r.truncation,
+			},
+		};
+	}
+
 	if (r.exitCode !== 0)
 		return {
 			content: [{ type: "text", text: r.error || "Failed" }],
@@ -1102,12 +1117,15 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		const parentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
 		deps.state.currentSessionId = parentSessionFile ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 		const discoveredAgents = deps.discoverAgents(ctx.cwd, scope).agents;
-		const piWithSessionName = deps.pi as ExtensionAPI & { getSessionName?: () => string | undefined };
-		const orchestratorTarget = piWithSessionName.getSessionName?.();
+		let sessionName = deps.pi.getSessionName()?.trim();
+		if (!sessionName) {
+			sessionName = `session-${ctx.sessionManager.getSessionId().slice(0, 8)}`;
+			deps.pi.setSessionName(sessionName);
+		}
 		const intercomBridge = resolveIntercomBridge({
-			mode: deps.config.intercomBridge,
+			config: deps.config.intercomBridge,
 			context: normalizedParams.context,
-			orchestratorTarget,
+			orchestratorTarget: sessionName,
 		});
 		const agents = intercomBridge.active
 			? discoveredAgents.map((agent) => applyIntercomBridgeToAgent(agent, intercomBridge))

package/types.ts

@@ -58,7 +58,7 @@ export interface ResolvedSkill {
 export interface AgentProgress {
 	index: number;
 	agent: string;
-	status: "pending" | "running" | "completed" | "failed";
+	status: "pending" | "running" | "completed" | "failed" | "detached";
 	task: string;
 	skills?: string[];
 	currentTool?: string;
@@ -94,6 +94,8 @@ export interface SingleResult {
 	agent: string;
 	task: string;
 	exitCode: number;
+	detached?: boolean;
+	detachedReason?: string;
 	messages: Message[];
 	usage: Usage;
 	model?: string;
@@ -237,6 +239,14 @@ export interface ErrorInfo {
 	details?: string;
 }
 
+export interface IntercomEventBus {
+	on(channel: string, handler: (data: unknown) => void): () => void;
+	emit(channel: string, data: unknown): void;
+}
+
+export const INTERCOM_DETACH_REQUEST_EVENT = "pi-intercom:detach-request";
+export const INTERCOM_DETACH_RESPONSE_EVENT = "pi-intercom:detach-response";
+
 // ============================================================================
 // Execution Options
 // ============================================================================
@@ -244,6 +254,8 @@ export interface ErrorInfo {
 export interface RunSyncOptions {
 	cwd?: string;
 	signal?: AbortSignal;
+	allowIntercomDetach?: boolean;
+	intercomEvents?: IntercomEventBus;
 	onUpdate?: (r: import("@mariozechner/pi-agent-core").AgentToolResult<Details>) => void;
 	maxOutput?: MaxOutputConfig;
 	artifactsDir?: string;
@@ -263,13 +275,20 @@ export interface RunSyncOptions {
 	skills?: string[];
 }
 
+export type IntercomBridgeMode = "off" | "fork-only" | "always";
+
+export interface IntercomBridgeConfig {
+	mode?: IntercomBridgeMode;
+	instructionFile?: string;
+}
+
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
 	defaultSessionDir?: string;
 	maxSubagentDepth?: number;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
-	intercomBridge?: "off" | "fork-only" | "always";
+	intercomBridge?: IntercomBridgeConfig;
 }
 
 // ============================================================================