pi-subagents 0.13.2 → 0.13.4

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [0.13.4] - 2026-04-13
+
+### Fixed
+- Intercom orchestration now uses a runtime-only `subagent-chat-<id>` fallback target for unnamed sessions instead of persisting a generic session title, so `pi --resume` keeps showing transcript snippets while delegated intercom routing still works.
+- GitHub Actions test workflow now uses `actions/checkout@v5` and `actions/setup-node@v5`, removing Node 20 action-runtime deprecation warnings ahead of the enforced Node 24 transition.
+- Worktree cwd mapping now derives repo-relative prefixes from `git rev-parse --show-prefix` instead of `path.relative(realpath, realpath)`, fixing Windows 8.3/canonical-path mismatches that could map `agentCwd` back to the source repo instead of the created worktree.
+- Async background runs now pass the parent process `argv[1]` through to the detached runner, so Windows child spawning keeps targeting the intended `pi` CLI entry point instead of accidentally treating the runner's `jiti` bootstrap script as `pi`.
+- Intercom detach listeners now guard optional event-bus subscriptions with optional-call semantics, so delegated runs no longer fail when host event buses expose `emit` without `on`.
+- Skill discovery no longer depends on runtime imports from `@mariozechner/pi-coding-agent`; it now resolves skills directly from configured filesystem paths, preventing `ERR_MODULE_NOT_FOUND` crashes in local/integration test environments.
+
+## [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

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
@@ -787,21 +781,38 @@ Controls whether subagents receive runtime intercom coordination instructions (a
 
 ```json
 {
-  "intercomBridge": "always"
+	"intercomBridge": {
+		"mode": "always",
+		"instructionFile": "./intercom-bridge.md"
+	}
 }
 ```
 
-Values:
-- `"always"` (default): inject bridge in both `fresh` and `fork`
-- `"fork-only"`: inject bridge only when `context: "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 can be targeted by intercom (existing `/name`, or the runtime-only fallback alias `subagent-chat-<id>` when unnamed)
 - if agent `extensions` is an explicit allowlist, it must include `pi-intercom`
 
+When an unnamed session falls back to `subagent-chat-<id>`, that alias is used only for the live intercom broker. It is not persisted as the Pi session title, so `pi --resume` can still show the transcript snippet.
+
 ### `worktreeSetupHook`
 
 `worktreeSetupHook` configures an optional setup hook for worktree-isolated parallel runs. The hook runs once per created worktree, after `git worktree add` succeeds and before the agent starts.

package/async-execution.ts

@@ -264,6 +264,7 @@ export function executeAsyncChain(
 			asyncDir,
 			sessionId: ctx.currentSessionId,
 			piPackageRoot,
+			piArgv1: process.argv[1],
 			worktreeSetupHook,
 			worktreeSetupHookTimeoutMs,
 		},
@@ -384,6 +385,7 @@ export function executeAsyncSingle(
 			asyncDir,
 			sessionId: ctx.currentSessionId,
 			piPackageRoot,
+			piArgv1: process.argv[1],
 			worktreeSetupHook,
 			worktreeSetupHookTimeoutMs,
 		},

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": "always", "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,27 +2,40 @@ 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 DEFAULT_INTERCOM_TARGET_PREFIX = "subagent-chat";
 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 resolveIntercomSessionTarget(sessionName: string | undefined, sessionId: string): string {
+	const trimmedName = sessionName?.trim();
+	if (trimmedName) return trimmedName;
+	const normalizedSessionId = sessionId.startsWith("session-") ? sessionId.slice("session-".length) : sessionId;
+	return `${DEFAULT_INTERCOM_TARGET_PREFIX}-${normalizedSessionId.slice(0, 8)}`;
 }
 
 export function resolveIntercomBridgeMode(value: unknown): IntercomBridgeMode {
@@ -30,6 +43,19 @@ export function resolveIntercomBridgeMode(value: unknown): IntercomBridgeMode {
 	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 {
 	if (!fs.existsSync(configPath)) return true;
 	try {
@@ -56,43 +82,71 @@ function extensionSandboxAllowsIntercom(extensions: string[] | undefined, extens
 	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,
 	};
 }
 
@@ -103,7 +157,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.2",
+  "version": "0.13.4",
   "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/skills.ts

@@ -6,7 +6,6 @@ import { execSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { loadSkills, type Skill } from "@mariozechner/pi-coding-agent";
 
 export type SkillSource =
 	| "project"
@@ -86,6 +85,7 @@ function getPackageSkillPaths(packageRoot: string): string[] {
 			.filter((s: unknown) => typeof s === "string")
 			.map((s: string) => path.resolve(packageRoot, s));
 	} catch {
+		// Package scanning is opportunistic; ignore malformed/missing package metadata.
 		return [];
 	}
 }
@@ -98,6 +98,7 @@ function getGlobalNpmRoot(): string | null {
 		cachedGlobalNpmRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
 		return cachedGlobalNpmRoot;
 	} catch {
+		// Global npm root is optional in constrained environments.
 		cachedGlobalNpmRoot = ""; // Empty string means "tried but failed"
 		return null;
 	}
@@ -123,6 +124,7 @@ function collectPackageSkillPaths(cwd: string): string[] {
 		try {
 			entries = fs.readdirSync(dir, { withFileTypes: true });
 		} catch {
+			// Ignore unreadable package roots and continue scanning other roots.
 			continue;
 		}
 
@@ -136,6 +138,7 @@ function collectPackageSkillPaths(cwd: string): string[] {
 				try {
 					scopeEntries = fs.readdirSync(scopeDir, { withFileTypes: true });
 				} catch {
+					// Ignore unreadable scoped package directories and continue.
 					continue;
 				}
 				for (const scopeEntry of scopeEntries) {
@@ -178,7 +181,9 @@ function collectSettingsSkillPaths(cwd: string): string[] {
 				}
 				results.push(resolved);
 			}
-		} catch {}
+		} catch {
+			// Settings-provided skills are optional; ignore malformed or missing settings files.
+		}
 	}
 
 	return results;
@@ -196,21 +201,22 @@ function buildSkillPaths(cwd: string): string[] {
 	return [...new Set([...defaultSkillPaths, ...packagePaths, ...settingsPaths])];
 }
 
-function inferSkillSource(sourceInfo: { source: string; scope: string }, filePath: string, cwd: string): SkillSource {
-	const { scope, source } = sourceInfo;
-
-	if (scope === "project" && source === "local") return "project";
-	if (scope === "user" && source === "local") return "user";
+function inferSkillSource(filePath: string, cwd: string): SkillSource {
+	const projectConfigRoot = path.resolve(cwd, CONFIG_DIR);
+	const projectSkillsRoot = path.resolve(cwd, CONFIG_DIR, "skills");
+	const projectPackagesRoot = path.resolve(cwd, CONFIG_DIR, "npm", "node_modules");
+	const projectAgentsRoot = path.resolve(cwd, ".agents");
+	const userSkillsRoot = path.resolve(AGENT_DIR, "skills");
+	const userPackagesRoot = path.resolve(AGENT_DIR, "npm", "node_modules");
+	const userAgentsRoot = path.resolve(os.homedir(), ".agents");
 
-	// Fallback: infer from file path when sourceInfo isn't specific enough
-	// (e.g. scope === "temporary" for skills loaded via explicit skillPaths)
-	const projectRoot = path.resolve(cwd, CONFIG_DIR);
-	const altProjectRoot = path.resolve(cwd, ".agents");
-	const isProjectScoped = isWithinPath(filePath, projectRoot) || isWithinPath(filePath, altProjectRoot);
-	if (isProjectScoped) return "project";
+	if (isWithinPath(filePath, projectPackagesRoot)) return "project-package";
+	if (isWithinPath(filePath, projectSkillsRoot) || isWithinPath(filePath, projectAgentsRoot)) return "project";
+	if (isWithinPath(filePath, projectConfigRoot)) return "project-settings";
 
-	const isUserScoped = isWithinPath(filePath, AGENT_DIR) || isWithinPath(filePath, path.join(os.homedir(), ".agents"));
-	if (isUserScoped) return "user";
+	if (isWithinPath(filePath, userPackagesRoot)) return "user-package";
+	if (isWithinPath(filePath, userSkillsRoot) || isWithinPath(filePath, userAgentsRoot)) return "user";
+	if (isWithinPath(filePath, AGENT_DIR)) return "user-settings";
 
 	const globalRoot = getGlobalNpmRoot();
 	if (globalRoot && isWithinPath(filePath, globalRoot)) return "user-package";
@@ -227,6 +233,99 @@ function chooseHigherPrioritySkill(existing: CachedSkillEntry | undefined, candi
 	return candidate.order < existing.order ? candidate : existing;
 }
 
+function maybeReadSkillDescription(filePath: string): string | undefined {
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		const normalized = content.replace(/\r\n/g, "\n");
+		if (!normalized.startsWith("---")) return undefined;
+
+		const endIndex = normalized.indexOf("\n---", 3);
+		if (endIndex === -1) return undefined;
+
+		const frontmatter = normalized.slice(3, endIndex).trim();
+		const match = frontmatter.match(/^description:\s*(.+)$/m);
+		if (!match) return undefined;
+		return match[1]?.trim().replace(/^['\"]|['\"]$/g, "");
+	} catch {
+		// Description parsing is best-effort metadata extraction.
+		return undefined;
+	}
+}
+
+function collectFilesystemSkills(cwd: string, skillPaths: string[]): CachedSkillEntry[] {
+	const entries: CachedSkillEntry[] = [];
+	const seen = new Set<string>();
+	let order = 0;
+
+	const pushEntry = (name: string, filePath: string) => {
+		const resolvedFile = path.resolve(filePath);
+		if (seen.has(resolvedFile)) return;
+		if (!fs.existsSync(resolvedFile)) return;
+		seen.add(resolvedFile);
+		entries.push({
+			name,
+			filePath: resolvedFile,
+			source: inferSkillSource(resolvedFile, cwd),
+			description: maybeReadSkillDescription(resolvedFile),
+			order: order++,
+		});
+	};
+
+	for (const skillPath of skillPaths) {
+		if (!fs.existsSync(skillPath)) continue;
+
+		let stat: fs.Stats;
+		try {
+			stat = fs.statSync(skillPath);
+		} catch {
+			// Ignore paths that disappear or become unreadable during discovery.
+			continue;
+		}
+
+		if (stat.isFile()) {
+			const fileName = path.basename(skillPath);
+			if (!fileName.toLowerCase().endsWith(".md")) continue;
+			const skillName = fileName.toLowerCase() === "skill.md"
+				? path.basename(path.dirname(skillPath))
+				: path.basename(fileName, path.extname(fileName));
+			pushEntry(skillName, skillPath);
+			continue;
+		}
+
+		if (!stat.isDirectory()) continue;
+
+		const rootSkillFile = path.join(skillPath, "SKILL.md");
+		if (fs.existsSync(rootSkillFile)) {
+			pushEntry(path.basename(skillPath), rootSkillFile);
+		}
+
+		let childEntries: fs.Dirent[];
+		try {
+			childEntries = fs.readdirSync(skillPath, { withFileTypes: true });
+		} catch {
+			// Ignore unreadable skill directories and continue scanning.
+			continue;
+		}
+
+		for (const child of childEntries) {
+			if (child.name.startsWith(".")) continue;
+			const childPath = path.join(skillPath, child.name);
+			if (child.isDirectory() || child.isSymbolicLink()) {
+				const nestedSkillPath = path.join(childPath, "SKILL.md");
+				if (fs.existsSync(nestedSkillPath)) {
+					pushEntry(child.name, nestedSkillPath);
+				}
+				continue;
+			}
+			if (child.isFile() && child.name.toLowerCase().endsWith(".md")) {
+				pushEntry(path.basename(child.name, path.extname(child.name)), childPath);
+			}
+		}
+	}
+
+	return entries;
+}
+
 function getCachedSkills(cwd: string): CachedSkillEntry[] {
 	const now = Date.now();
 	if (loadSkillsCache && loadSkillsCache.cwd === cwd && now - loadSkillsCache.timestamp < LOAD_SKILLS_CACHE_TTL_MS) {
@@ -234,18 +333,10 @@ function getCachedSkills(cwd: string): CachedSkillEntry[] {
 	}
 
 	const skillPaths = buildSkillPaths(cwd);
-	const loaded = loadSkills({ cwd, skillPaths, includeDefaults: false });
+	const loaded = collectFilesystemSkills(cwd, skillPaths);
 	const dedupedByName = new Map<string, CachedSkillEntry>();
 
-	for (let i = 0; i < loaded.skills.length; i++) {
-		const skill = loaded.skills[i] as Skill;
-		const entry: CachedSkillEntry = {
-			name: skill.name,
-			filePath: skill.filePath,
-			source: inferSkillSource(skill.sourceInfo, skill.filePath, cwd),
-			description: skill.description,
-			order: i,
-		};
+	for (const entry of loaded) {
 		const current = dedupedByName.get(entry.name);
 		dedupedByName.set(entry.name, chooseHigherPrioritySkill(current, entry));
 	}
@@ -294,6 +385,7 @@ export function readSkill(
 
 		return skill;
 	} catch {
+		// Treat unreadable skill files as unresolved so callers can surface as missing.
 		return undefined;
 	}
 }

package/subagent-executor.ts

@@ -22,7 +22,7 @@ import {
 import { discoverAvailableSkills, normalizeSkillInput } from "./skills.ts";
 import { executeAsyncChain, executeAsyncSingle, isAsyncAvailable } from "./async-execution.ts";
 import { createForkContextResolver } from "./fork-context.ts";
-import { applyIntercomBridgeToAgent, resolveIntercomBridge } from "./intercom-bridge.ts";
+import { applyIntercomBridgeToAgent, resolveIntercomBridge, resolveIntercomSessionTarget } from "./intercom-bridge.ts";
 import { finalizeSingleOutput, injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.ts";
 import { getSingleResultOutput, mapConcurrent } from "./utils.ts";
 import {
@@ -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,11 @@ 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?.();
+		const sessionName = resolveIntercomSessionTarget(deps.pi.getSessionName(), ctx.sessionManager.getSessionId());
 		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/subagent-runner.ts

@@ -53,6 +53,7 @@ interface SubagentRunConfig {
 	asyncDir: string;
 	sessionId?: string | null;
 	piPackageRoot?: string;
+	piArgv1?: string;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
 }
@@ -156,12 +157,16 @@ function runPiStreaming(
 	outputFile: string,
 	env?: Record<string, string | undefined>,
 	piPackageRoot?: string,
+	piArgv1?: string,
 	maxSubagentDepth?: number,
 ): Promise<{ stdout: string; stderr: string; exitCode: number | null }> {
 	return new Promise((resolve) => {
 		const outputStream = fs.createWriteStream(outputFile, { flags: "w" });
 		const spawnEnv = { ...process.env, ...(env ?? {}), ...getSubagentDepthEnv(maxSubagentDepth) };
-		const spawnSpec = getPiSpawnCommand(args, piPackageRoot ? { piPackageRoot } : undefined);
+		const spawnSpec = getPiSpawnCommand(args, {
+			...(piPackageRoot ? { piPackageRoot } : {}),
+			...(piArgv1 ? { argv1: piArgv1 } : {}),
+		});
 		const child = spawn(spawnSpec.command, spawnSpec.args, { cwd, stdio: ["ignore", "pipe", "pipe"], env: spawnEnv });
 		let stdout = "";
 		let stderr = "";
@@ -340,6 +345,7 @@ interface SingleStepContext {
 	flatStepCount: number;
 	outputFile: string;
 	piPackageRoot?: string;
+	piArgv1?: string;
 }
 
 /** Run a single pi agent step, returning output and metadata */
@@ -401,7 +407,7 @@ async function runSingleStep(
 			promptFileStem: step.agent,
 		});
 		const outputFile = index === 0 ? ctx.outputFile : `${ctx.outputFile}.attempt-${index + 1}`;
-		const run = await runPiStreaming(args, step.cwd ?? ctx.cwd, outputFile, env, ctx.piPackageRoot, step.maxSubagentDepth);
+		const run = await runPiStreaming(args, step.cwd ?? ctx.cwd, outputFile, env, ctx.piPackageRoot, ctx.piArgv1, step.maxSubagentDepth);
 		cleanupTempDir(tempDir);
 
 		const parsed = parseRunOutput(run.stdout);
@@ -759,6 +765,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 							flatIndex: fi, flatStepCount: flatSteps.length,
 							outputFile: path.join(asyncDir, `output-${fi}.log`),
 							piPackageRoot: config.piPackageRoot,
+							piArgv1: config.piArgv1,
 						});
 						if (task.sessionFile) {
 							latestSessionFile = task.sessionFile;
@@ -879,6 +886,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				flatIndex, flatStepCount: flatSteps.length,
 				outputFile: path.join(asyncDir, `output-${flatIndex}.log`),
 				piPackageRoot: config.piPackageRoot,
+				piArgv1: config.piArgv1,
 			});
 			if (seqStep.sessionFile) {
 				latestSessionFile = seqStep.sessionFile;

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;
 }
 
 // ============================================================================

package/worktree.ts

@@ -106,9 +106,11 @@ function resolveRepoState(cwd: string): RepoState {
 	}
 
 	const toplevel = runGitChecked(cwd, ["rev-parse", "--show-toplevel"]).trim();
-	const realCwd = fs.realpathSync(cwd);
-	const realToplevel = fs.realpathSync(toplevel);
-	const cwdRelative = path.relative(realToplevel, realCwd);
+	const rawPrefix = runGitChecked(cwd, ["rev-parse", "--show-prefix"]).trim();
+	const normalizedPrefix = rawPrefix
+		? path.normalize(rawPrefix.replace(/[\\/]+$/, ""))
+		: "";
+	const cwdRelative = normalizedPrefix === "." ? "" : normalizedPrefix;
 
 	const status = runGitChecked(toplevel, ["status", "--porcelain"]);
 	if (status.trim().length > 0) {
@@ -124,6 +126,7 @@ function normalizeComparableCwd(cwd: string): string {
 	try {
 		return fs.realpathSync(resolved);
 	} catch {
+		// Use the unresolved absolute path when realpath resolution is unavailable.
 		return resolved;
 	}
 }
@@ -169,6 +172,7 @@ function linkNodeModulesIfPresent(toplevel: string, worktreePath: string): boole
 		fs.symlinkSync(nodeModulesPath, nodeModulesLinkPath);
 		return true;
 	} catch {
+		// Symlink creation is optional (e.g., unsupported filesystems on CI runners).
 		return false;
 	}
 }
@@ -344,8 +348,12 @@ function createSingleWorktree(
 			syntheticPaths,
 		};
 	} catch (error) {
-		try { runGitChecked(toplevel, ["worktree", "remove", "--force", worktreePath]); } catch {}
-		try { runGitChecked(toplevel, ["branch", "-D", branch]); } catch {}
+		try { runGitChecked(toplevel, ["worktree", "remove", "--force", worktreePath]); } catch {
+			// Best-effort rollback; preserve the original setup failure.
+		}
+		try { runGitChecked(toplevel, ["branch", "-D", branch]); } catch {
+			// Best-effort rollback; preserve the original setup failure.
+		}
 		throw error;
 	}
 }
@@ -453,12 +461,18 @@ function captureWorktreeDiff(
 function writeEmptyPatch(patchPath: string): void {
 	try {
 		fs.writeFileSync(patchPath, "", "utf-8");
-	} catch {}
+	} catch {
+		// Diff artifact writing is best-effort in error paths.
+	}
 }
 
 function cleanupSingleWorktree(repoCwd: string, worktree: WorktreeInfo): void {
-	try { runGitChecked(repoCwd, ["worktree", "remove", "--force", worktree.path]); } catch {}
-	try { runGitChecked(repoCwd, ["branch", "-D", worktree.branch]); } catch {}
+	try { runGitChecked(repoCwd, ["worktree", "remove", "--force", worktree.path]); } catch {
+		// Cleanup is best-effort to avoid masking caller errors.
+	}
+	try { runGitChecked(repoCwd, ["branch", "-D", worktree.branch]); } catch {
+		// Cleanup is best-effort to avoid masking caller errors.
+	}
 }
 
 function hasWorktreeChanges(diff: WorktreeDiff): boolean {
@@ -502,6 +516,7 @@ export function diffWorktrees(setup: WorktreeSetup, agents: string[], diffsDir:
 	try {
 		fs.mkdirSync(diffsDir, { recursive: true });
 	} catch {
+		// Returning no diffs is safer than failing the whole command on artifact-dir issues.
 		return [];
 	}
 
@@ -513,6 +528,7 @@ export function diffWorktrees(setup: WorktreeSetup, agents: string[], diffsDir:
 		try {
 			diffs.push(captureWorktreeDiff(setup, worktree, agent, patchPath));
 		} catch {
+			// Preserve execution flow; failed diff capture maps to an empty per-task patch.
 			writeEmptyPatch(patchPath);
 			diffs.push(emptyDiff(index, agent, worktree.branch, patchPath));
 		}
@@ -525,7 +541,9 @@ export function cleanupWorktrees(setup: WorktreeSetup): void {
 	for (let index = setup.worktrees.length - 1; index >= 0; index--) {
 		cleanupSingleWorktree(setup.cwd, setup.worktrees[index]!);
 	}
-	try { runGitChecked(setup.cwd, ["worktree", "prune"]); } catch {}
+	try { runGitChecked(setup.cwd, ["worktree", "prune"]); } catch {
+		// Pruning is best-effort cleanup.
+	}
 }
 
 export function formatWorktreeDiffSummary(diffs: WorktreeDiff[]): string {