pi-subagents 0.32.0 → 0.33.0

package/src/extension/tool-description.ts

@@ -0,0 +1,200 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionConfig, ToolDescriptionMode } from "../shared/types.ts";
+import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
+
+const CUSTOM_TOOL_DESCRIPTION_FILE = "subagent-tool-description.md";
+const CUSTOM_TOOL_DESCRIPTION_MAX_BYTES = 50 * 1024;
+
+export const SUBAGENT_SAFETY_GUIDANCE = `SAFETY-CRITICAL SUBAGENT GUIDANCE:
+• Use { action: "list" } before execution and only run executable/non-disabled agents or chains.
+• Keep execution and management separate: omit action for SINGLE/PARALLEL/CHAIN execution; use action only for list/get/models/create/update/delete/status/interrupt/resume/append-step/doctor.
+• Async/background runs: launch with async:true only when work can proceed independently. Do not sleep or poll status just to wait; if this turn must block, use the wait tool. Otherwise continue useful work or respond and let completion notifications arrive.
+• Child-safety boundary: ordinary child subagents are not orchestrators and must not run subagents. Only explicitly configured fanout children may use the child-safe subagent tool, still bounded by depth/session limits.
+• Writing/review safety: keep one writer for the same cwd/worktree. Use fresh-context read-only reviewers/validators for independent review, then have the parent synthesize and apply fixes as the sole writer unless an isolated worktree was intentionally requested.
+• Artifacts/status essentials: chain outputs live under {chain_dir}; async runs expose asyncId/asyncDir with status.json, events.jsonl, output logs, and status via { action: "status", id }. Include output paths and residual risks when reporting results.`;
+
+export const FULL_SUBAGENT_TOOL_DESCRIPTION = `Delegate to subagents or manage agent definitions.
+
+EXECUTION (use exactly ONE mode):
+• Before executing, use { action: "list" } to inspect configured agents/chains. Only execute agents listed as executable/non-disabled.
+• SINGLE: { agent, task? } - one task; omit task for self-contained agents
+• CHAIN: { chain: [{agent:"agent-a"}, {parallel:[{agent:"agent-b",count:3}]}] } - sequential pipeline with optional parallel fan-out
+• PARALLEL: { tasks: [{agent,task,count?,output?,reads?,progress?}, ...], concurrency?: number, worktree?: true } - concurrent execution (worktree: isolate each task in a git worktree)
+• Optional context: { context: "fresh" | "fork" } (explicit value overrides every child; when omitted, each requested agent uses its own defaultContext, otherwise "fresh"; inspect agent defaults via { action: "list" })
+• Optional timeout: { timeoutMs } or { maxRuntimeMs } sets a run-level max runtime for foreground and async/background runs
+• If { action: "list" } shows proactive skill subagent suggestions, consider a small fresh-context fanout for broad tasks where one of those skills would materially help
+
+CHAIN TEMPLATE VARIABLES (use in task strings):
+• {task} - The original task/request from the user
+• {previous} - Text response from the previous step (empty for first step)
+• {chain_dir} - Shared directory for chain files (e.g., <tmpdir>/pi-subagents-<scope>/chain-runs/abc123/)
+
+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
+• { action: "get", agent: "name" } - full detail; packaged agents use dotted runtime names like "package.agent"
+• { action: "models", agent?: "name" } - show the runtime-loaded builtin subagent model mapping, optionally filtered to one builtin
+• { action: "create", config: { name: "custom-agent", package: "code-analysis", systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext, ... } }
+• { action: "update", agent: "code-analysis.custom-agent", config: { package: "analysis", ... } } - merge
+• { action: "delete", agent: "code-analysis.custom-agent" }
+• { action: "eject", agent: "reviewer", agentScope?: "user" | "project" } - copy a bundled/package agent to user/project scope as an editable custom file that shadows the original (default scope: user)
+• { action: "disable", agent: "reviewer", agentScope?: "user" | "project" } - hide any agent from runtime discovery via a reversible settings override (default scope: user)
+• { action: "enable", agent: "reviewer", agentScope?: "user" | "project" } - remove a disabled override and restore discovery
+• { action: "reset", agent: "reviewer", agentScope?: "user" | "project" } - delete the scope's custom agent file and/or settings override, restoring the bundled default
+• Use chainName for chain operations; packaged chains also use dotted runtime names
+
+CONTROL:
+• { action: "status", id: "..." } - inspect an async/background run by id or prefix
+• { action: "status", view: "fleet" } - read-only active foreground/async fleet view with transcript commands
+• { action: "status", id: "...", view: "transcript", index?: 0, lines?: 80 } - tail a run or child output/session transcript
+• { action: "interrupt", id?: "..." } - soft-interrupt the current child turn and leave the run paused
+• { action: "resume", id: "...", message: "...", index?: 0 } - interrupt then follow up with a live async child, or revive a completed async/foreground child from its session
+• { action: "steer", id: "...", message: "...", index?: 0 } - queue non-terminal guidance for a live/queued async Pi child when supported
+• { action: "append-step", id: "...", chain: [{agent:"agent-c", task:"Use {previous}"}] } - append one step to the tail of a running async chain
+
+SCHEDULE (opt-in; requires { "scheduledRuns": { "enabled": true } } in config.json):
+• { action: "schedule", agent, task?, schedule: "+10m" | "2030-01-01T09:00:00Z", scheduleName? } - defer a subagent launch until a future time. Also accepts tasks[] or chain[]. Scheduled runs always launch async with fresh context; they become normal tracked async runs once they fire. Only schedule explicit delayed runs the user asked for.
+• { action: "schedule-list" } - list scheduled runs for this session
+• { action: "schedule-status", id: "..." } - inspect one scheduled run
+• { action: "schedule-cancel", id: "..." } - cancel a scheduled run before it fires
+
+DIAGNOSTICS:
+• { action: "doctor" } - read-only report for runtime paths, discovery, sessions, and intercom
+
+${SUBAGENT_SAFETY_GUIDANCE}`;
+
+export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = `Delegate to subagents or manage definitions. Use exactly one mode per call.
+
+EXECUTE:
+• Before execution, call { action: "list" }; run only executable/non-disabled configured agents/chains.
+• SINGLE {agent, task?}; PARALLEL {tasks:[{agent,task,count?,output?,reads?,progress?}], concurrency?, worktree?}; CHAIN {chain:[{agent,task?},{parallel:[...]}]}.
+• context can be "fresh" or "fork"; omitted uses each agent defaultContext, otherwise fresh. timeoutMs/maxRuntimeMs apply to foreground and async/background runs.
+• Chain templates may use {task}, {previous}, {chain_dir}, and named outputs. Parallel worktree isolation requires a clean git repo.
+• If list shows proactive skill subagent suggestions, use a small fresh-context fanout only when the task is broad enough.
+
+MANAGE / CONTROL:
+• Use action without execution fields: list, get, models, create, update, delete, eject, disable, enable, reset, doctor.
+• Async control actions: status, interrupt, resume, steer, append-step. Use status view:"fleet" for active-run overview, view:"transcript" to tail child output, and steer for non-terminal live guidance. Use id/runId prefixes carefully; use index for a specific child.
+• Opt-in schedule actions: schedule, schedule-list, schedule-status, schedule-cancel. Schedule only explicit delayed runs the user asked for.
+
+ASYNC / WAIT:
+• async:true detaches background work. Do not sleep or poll just to wait; use the wait tool only when this turn must block. Otherwise continue useful work or respond and let completion notifications arrive.
+• Status and artifacts live under asyncId/asyncDir with status.json, events.jsonl, output logs, session files, and { action:"status", id:"..." }.
+
+SAFETY:
+• Ordinary child subagents are not orchestrators and must not run subagents. Only explicit fanout children may use child-safe subagent, still bounded by depth/session limits.
+• Keep one writer per cwd/worktree. Use fresh read-only review/validation fanout, then synthesize and apply fixes from the parent unless isolated worktrees were intentionally requested.`;
+
+function isToolDescriptionMode(value: unknown): value is ToolDescriptionMode {
+	return value === "full" || value === "compact" || value === "custom";
+}
+
+function warn(options: ToolDescriptionOptions | undefined, message: string): void {
+	(options?.warn ?? console.warn)(`[pi-subagents] ${message}`);
+}
+
+export interface ToolDescriptionOptions {
+	cwd?: string;
+	agentDir?: string;
+	warn?: (message: string) => void;
+}
+
+export function resolveToolDescriptionMode(config: Pick<ExtensionConfig, "toolDescriptionMode">, options?: ToolDescriptionOptions): ToolDescriptionMode {
+	const mode = config.toolDescriptionMode;
+	if (mode === undefined) return "full";
+	if (isToolDescriptionMode(mode)) return mode;
+	warn(options, `Ignoring invalid toolDescriptionMode ${JSON.stringify(mode)}; expected "full", "compact", or "custom".`);
+	return "full";
+}
+
+function customDescriptionPaths(options?: ToolDescriptionOptions): string[] {
+	const cwd = options?.cwd ?? process.cwd();
+	const agentDir = options?.agentDir ?? getAgentDir();
+	return [
+		path.join(getProjectConfigDir(cwd), CUSTOM_TOOL_DESCRIPTION_FILE),
+		path.join(agentDir, CUSTOM_TOOL_DESCRIPTION_FILE),
+	];
+}
+
+function renderCustomTemplate(template: string, options?: ToolDescriptionOptions): string {
+	const cwd = options?.cwd ?? process.cwd();
+	const agentDir = options?.agentDir ?? getAgentDir();
+	const projectConfigDir = getProjectConfigDir(cwd);
+	const variables: Record<string, () => string> = {
+		fullDescription: () => FULL_SUBAGENT_TOOL_DESCRIPTION,
+		full: () => FULL_SUBAGENT_TOOL_DESCRIPTION,
+		compactDescription: () => COMPACT_SUBAGENT_TOOL_DESCRIPTION,
+		compact: () => COMPACT_SUBAGENT_TOOL_DESCRIPTION,
+		safetyGuidance: () => SUBAGENT_SAFETY_GUIDANCE,
+		safety: () => SUBAGENT_SAFETY_GUIDANCE,
+		agentDir: () => agentDir,
+		projectConfigDir: () => projectConfigDir,
+	};
+	return template.replace(/\{\{(\w+)\}\}/g, (raw, name: string) => {
+		const replacement = variables[name];
+		if (replacement) return replacement();
+		warn(options, `${CUSTOM_TOOL_DESCRIPTION_FILE}: unknown placeholder ${raw} left unchanged.`);
+		return raw;
+	});
+}
+
+function loadCustomToolDescription(options?: ToolDescriptionOptions): string | undefined {
+	for (const filePath of customDescriptionPaths(options)) {
+		let stat: fs.Stats;
+		try {
+			stat = fs.statSync(filePath);
+		} catch (error) {
+			if (typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") continue;
+			warn(options, `Failed to inspect custom tool description '${filePath}': ${error instanceof Error ? error.message : String(error)}`);
+			continue;
+		}
+		if (!stat.isFile()) {
+			warn(options, `Ignoring custom tool description '${filePath}' because it is not a file.`);
+			continue;
+		}
+		if (stat.size > CUSTOM_TOOL_DESCRIPTION_MAX_BYTES) {
+			warn(options, `Ignoring custom tool description '${filePath}' because it is larger than ${CUSTOM_TOOL_DESCRIPTION_MAX_BYTES} bytes.`);
+			continue;
+		}
+		try {
+			const template = fs.readFileSync(filePath, "utf-8").trim();
+			if (!template) {
+				warn(options, `Ignoring empty custom tool description '${filePath}'.`);
+				continue;
+			}
+			const rendered = renderCustomTemplate(template, options).trim();
+			if (!rendered) {
+				warn(options, `Ignoring custom tool description '${filePath}' because it rendered empty.`);
+				continue;
+			}
+			return rendered;
+		} catch (error) {
+			warn(options, `Failed to read custom tool description '${filePath}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return undefined;
+}
+
+function withMandatorySafetyGuidance(description: string): string {
+	const customDescription = description
+		.split(SUBAGENT_SAFETY_GUIDANCE)
+		.map((part) => part.trim())
+		.filter(Boolean)
+		.join("\n\n");
+	return customDescription
+		? `${customDescription}\n\n${SUBAGENT_SAFETY_GUIDANCE}`
+		: SUBAGENT_SAFETY_GUIDANCE;
+}
+
+export function buildSubagentToolDescription(config: Pick<ExtensionConfig, "toolDescriptionMode"> = {}, options?: ToolDescriptionOptions): string {
+	const mode = resolveToolDescriptionMode(config, options);
+	if (mode === "compact") return COMPACT_SUBAGENT_TOOL_DESCRIPTION;
+	if (mode === "custom") {
+		const custom = loadCustomToolDescription(options);
+		if (custom) return withMandatorySafetyGuidance(custom);
+		warn(options, `${CUSTOM_TOOL_DESCRIPTION_FILE} was not found or valid for toolDescriptionMode "custom"; using full description.`);
+	}
+	return FULL_SUBAGENT_TOOL_DESCRIPTION;
+}

package/src/intercom/intercom-bridge.ts

@@ -1,35 +1,16 @@
-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 type { AgentConfig } from "../agents/agents.ts";
 import type { ExtensionConfig, IntercomBridgeConfig, IntercomBridgeMode } from "../shared/types.ts";
-import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
+import { getAgentDir } from "../shared/utils.ts";
 
-const PI_INTERCOM_PACKAGE_NAME = "pi-intercom";
+export const NATIVE_INTERCOM_EXTENSION_DIR = "native:pi-subagents-supervisor-channel";
 
 function defaultAgentDir(): string {
 	return getAgentDir();
 }
 
-function defaultIntercomExtensionDir(agentDir = defaultAgentDir()): string {
-	return path.join(agentDir, "extensions", PI_INTERCOM_PACKAGE_NAME);
-}
-
-export const INTERCOM_EXTENSION_DIR_ENV = "PI_INTERCOM_EXTENSION_DIR";
-
-// Launcher-provided override for the pi-intercom package directory. Lets a hermetic
-// wrapper point the subagent intercom bridge at a read-only install (e.g. a Nix-store
-// path) instead of seeding the package into the writable agent dir.
-function envIntercomExtensionDir(): string | undefined {
-	const dir = process.env[INTERCOM_EXTENSION_DIR_ENV]?.trim();
-	return dir ? dir : undefined;
-}
-
-function defaultIntercomConfigPath(agentDir = defaultAgentDir()): string {
-	return path.join(agentDir, "intercom", "config.json");
-}
-
 function defaultSubagentConfigDir(agentDir = defaultAgentDir()): string {
 	return path.join(agentDir, "extensions", "subagent");
 }
@@ -59,25 +40,18 @@ export interface IntercomBridgeDiagnostic {
 	active: boolean;
 	mode: IntercomBridgeMode;
 	wantsIntercom: boolean;
-	piIntercomAvailable: boolean;
+	supervisorChannelAvailable: boolean;
 	extensionDir: string;
-	configPath?: string;
 	orchestratorTarget?: string;
 	reason?: string;
-	intercomConfigEnabled?: boolean;
-	intercomConfigError?: string;
 }
 
 interface ResolveIntercomBridgeInput {
 	config: ExtensionConfig["intercomBridge"];
 	context: "fresh" | "fork" | undefined;
 	orchestratorTarget?: string;
-	extensionDir?: string;
-	configPath?: string;
 	settingsDir?: string;
-	cwd?: string;
 	agentDir?: string;
-	globalNpmRoot?: string | null;
 }
 
 export function resolveIntercomSessionTarget(sessionName: string | undefined, sessionId: string): string {
@@ -103,10 +77,7 @@ export function resolveIntercomBridgeMode(value: unknown): IntercomBridgeMode {
 
 function resolveIntercomBridgeConfig(value: ExtensionConfig["intercomBridge"]): Required<IntercomBridgeConfig> {
 	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		return {
-			mode: "always",
-			instructionFile: "",
-		};
+		return { mode: "always", instructionFile: "" };
 	}
 	return {
 		mode: resolveIntercomBridgeMode(value.mode),
@@ -114,169 +85,6 @@ function resolveIntercomBridgeConfig(value: ExtensionConfig["intercomBridge"]):
 	};
 }
 
-function intercomConfigStatus(configPath: string): { enabled: boolean; error?: unknown } {
-	if (!fs.existsSync(configPath)) return { enabled: true };
-	try {
-		const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8")) as { enabled?: unknown };
-		return { enabled: parsed.enabled !== false };
-	} catch (error) {
-		return { enabled: true, error };
-	}
-}
-
-function readJsonBestEffort(filePath: string): unknown {
-	try {
-		return JSON.parse(fs.readFileSync(filePath, "utf-8"));
-	} catch (error) {
-		const code = error && typeof error === "object" && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
-		if (code !== "ENOENT") console.warn(`Failed to read JSON from '${filePath}'.`, error);
-		return null;
-	}
-}
-
-function packageHasPiExtension(packageRoot: string): boolean {
-	if (!fs.existsSync(packageRoot)) return false;
-	const pkg = readJsonBestEffort(path.join(packageRoot, "package.json"));
-	if (pkg && typeof pkg === "object" && !Array.isArray(pkg)) {
-		const pi = (pkg as { pi?: unknown }).pi;
-		if (pi && typeof pi === "object" && !Array.isArray(pi)) {
-			const extensions = (pi as { extensions?: unknown }).extensions;
-			return Array.isArray(extensions) && extensions.some((entry) => typeof entry === "string" && entry.trim() !== "");
-		}
-	}
-	return fs.existsSync(path.join(packageRoot, "extensions"));
-}
-
-function isSafePackagePath(value: string): boolean {
-	return value.length > 0
-		&& !path.isAbsolute(value)
-		&& value.split(/[\\/]/).every((part) => part.length > 0 && part !== "." && part !== "..");
-}
-
-function parseNpmPackageName(source: string): string | undefined {
-	const spec = source.slice(4).trim();
-	if (!spec) return undefined;
-	const match = spec.match(/^(@?[^@]+(?:\/[^@]+)?)(?:@(.+))?$/);
-	const packageName = match?.[1] ?? spec;
-	return isSafePackagePath(packageName) ? packageName : undefined;
-}
-
-function packageEntrySource(entry: unknown): string | undefined {
-	if (typeof entry === "string") return entry;
-	if (entry && typeof entry === "object" && !Array.isArray(entry) && typeof (entry as { source?: unknown }).source === "string") {
-		return (entry as { source: string }).source;
-	}
-	return undefined;
-}
-
-function packageEntryAllowsExtensions(entry: unknown): boolean {
-	if (!entry || typeof entry !== "object" || Array.isArray(entry)) return true;
-	const extensions = (entry as { extensions?: unknown }).extensions;
-	return !Array.isArray(extensions) || extensions.length > 0;
-}
-
-function findNearestProjectConfigDir(cwd: string): string | undefined {
-	let current = path.resolve(cwd);
-	while (true) {
-		const configDir = getProjectConfigDir(current);
-		if (fs.existsSync(path.join(configDir, "settings.json"))) return configDir;
-		const parent = path.dirname(current);
-		if (parent === current) return undefined;
-		current = parent;
-	}
-}
-
-let cachedGlobalNpmRoot: string | null | undefined;
-
-function getGlobalNpmRoot(): string | null {
-	if (cachedGlobalNpmRoot !== undefined) return cachedGlobalNpmRoot;
-	try {
-		cachedGlobalNpmRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
-		return cachedGlobalNpmRoot;
-	} catch {
-		cachedGlobalNpmRoot = null;
-		return null;
-	}
-}
-
-function tmpNpmIntercomPackageDir(agentDir: string): string | undefined {
-	const tmpNpmDir = path.join(agentDir, "tmp", "extensions", "npm");
-	try {
-		const entries = fs.readdirSync(tmpNpmDir, { withFileTypes: true });
-		for (const entry of entries) {
-			if (!entry.isDirectory()) continue;
-			const pkgDir = path.join(tmpNpmDir, entry.name, "node_modules", PI_INTERCOM_PACKAGE_NAME);
-			if (fs.existsSync(pkgDir) && packageHasPiExtension(pkgDir)) {
-				return path.resolve(pkgDir);
-			}
-		}
-	} catch {
-		// ignore ENOTDIR, ENOENT, permission errors
-	}
-	return undefined;
-}
-
-function configuredPiIntercomPackageDir(input: ResolveIntercomBridgeInput, agentDir: string): string | undefined {
-	const projectConfigDir = input.cwd ? findNearestProjectConfigDir(path.resolve(input.cwd)) : undefined;
-	const settingsFiles = [
-		...(projectConfigDir ? [{ file: path.join(projectConfigDir, "settings.json"), configDir: projectConfigDir, scope: "project" as const }] : []),
-		{ file: path.join(agentDir, "settings.json"), configDir: agentDir, scope: "user" as const },
-	];
-	const globalNpmRoot = input.globalNpmRoot === undefined ? getGlobalNpmRoot() : input.globalNpmRoot;
-
-	for (const { file, configDir, scope } of settingsFiles) {
-		const settings = readJsonBestEffort(file);
-		if (!settings || typeof settings !== "object" || Array.isArray(settings)) continue;
-		const packages = (settings as { packages?: unknown }).packages;
-		if (!Array.isArray(packages)) continue;
-
-		for (const entry of packages) {
-			if (!packageEntryAllowsExtensions(entry)) continue;
-			const source = packageEntrySource(entry)?.trim();
-			if (!source?.startsWith("npm:")) continue;
-			const packageName = parseNpmPackageName(source);
-			if (packageName !== PI_INTERCOM_PACKAGE_NAME) continue;
-			const candidates = scope === "project"
-				? [path.join(configDir, "npm", "node_modules", packageName)]
-				: [
-					...(globalNpmRoot ? [path.join(globalNpmRoot, packageName)] : []),
-					path.join(agentDir, "npm", "node_modules", packageName),
-				];
-			const packageRoot = candidates.find(packageHasPiExtension);
-			if (packageRoot) return path.resolve(packageRoot);
-		}
-	}
-	return undefined;
-}
-
-function resolveIntercomExtensionDir(input: ResolveIntercomBridgeInput, agentDir: string): string {
-	const legacyDir = path.resolve(input.extensionDir ?? envIntercomExtensionDir() ?? defaultIntercomExtensionDir(agentDir));
-	if (fs.existsSync(legacyDir)) return legacyDir;
-
-	const configured = configuredPiIntercomPackageDir(input, agentDir);
-	if (configured) return configured;
-
-	const tmpDir = tmpNpmIntercomPackageDir(agentDir);
-	if (tmpDir) return tmpDir;
-
-	return legacyDir;
-}
-
-function extensionSandboxAllowsIntercom(extensions: string[] | undefined, extensionDir: string): boolean {
-	if (extensions === undefined) return true;
-
-	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 expandTilde(filePath: string): string {
 	return filePath.startsWith("~/") ? path.join(os.homedir(), filePath.slice(2)) : filePath;
 }
@@ -298,98 +106,58 @@ function resolveInstructionTemplate(instructionFile: string, settingsDir: string
 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}
-${instruction}`;
+	return `${INTERCOM_BRIDGE_MARKER}\n${instruction}`;
+}
+
+function inactiveReason(mode: IntercomBridgeMode, context: "fresh" | "fork" | undefined, orchestratorTarget: string | undefined): string | undefined {
+	if (mode === "off") return "bridge mode is off";
+	if (mode === "fork-only" && context !== "fork") return "bridge mode is fork-only and context is not fork";
+	if (!orchestratorTarget) return "orchestrator target is not available";
+	return undefined;
 }
 
 export function diagnoseIntercomBridge(input: ResolveIntercomBridgeInput): IntercomBridgeDiagnostic {
 	const config = resolveIntercomBridgeConfig(input.config);
 	const mode = config.mode;
-	const agentDir = path.resolve(input.agentDir ?? defaultAgentDir());
-	const extensionDir = resolveIntercomExtensionDir(input, agentDir);
 	const orchestratorTarget = input.orchestratorTarget?.trim();
-	const configPath = path.resolve(input.configPath ?? defaultIntercomConfigPath(agentDir));
 	const wantsIntercom = mode !== "off" && !(mode === "fork-only" && input.context !== "fork");
-	const piIntercomAvailable = fs.existsSync(extensionDir);
-	let configStatus: ReturnType<typeof intercomConfigStatus> | undefined;
-	let reason: string | undefined;
-	if (mode === "off") reason = "bridge mode is off";
-	else if (mode === "fork-only" && input.context !== "fork") reason = "bridge mode is fork-only and context is not fork";
-	else if (!orchestratorTarget) reason = "orchestrator target is not available";
-	else if (!piIntercomAvailable) reason = "pi-intercom extension was not found";
-	else {
-		configStatus = intercomConfigStatus(configPath);
-		if (!configStatus.enabled) reason = "intercom config is disabled";
-	}
-	let intercomConfigError: string | undefined;
-	if (configStatus?.error) {
-		const error = configStatus.error;
-		intercomConfigError = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
-	}
-
+	const reason = inactiveReason(mode, input.context, orchestratorTarget);
 	return {
 		active: reason === undefined,
 		mode,
 		wantsIntercom,
-		piIntercomAvailable,
-		extensionDir,
-		configPath,
+		supervisorChannelAvailable: true,
+		extensionDir: NATIVE_INTERCOM_EXTENSION_DIR,
 		...(orchestratorTarget ? { orchestratorTarget } : {}),
 		...(reason ? { reason } : {}),
-		...(configStatus ? { intercomConfigEnabled: configStatus.enabled } : {}),
-		...(intercomConfigError ? { intercomConfigError } : {}),
 	};
 }
 
 export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): IntercomBridgeState {
 	const config = resolveIntercomBridgeConfig(input.config);
 	const mode = config.mode;
-	const agentDir = path.resolve(input.agentDir ?? defaultAgentDir());
-	const extensionDir = resolveIntercomExtensionDir(input, agentDir);
 	const orchestratorTarget = input.orchestratorTarget?.trim();
+	const agentDir = path.resolve(input.agentDir ?? defaultAgentDir());
 	const settingsDir = path.resolve(input.settingsDir ?? defaultSubagentConfigDir(agentDir));
 	const defaultInstruction = buildIntercomBridgeInstruction(
 		orchestratorTarget || "{orchestratorTarget}",
 		DEFAULT_INTERCOM_BRIDGE_TEMPLATE,
 	);
-
-	if (mode === "off") {
-		return { active: false, mode, extensionDir, instruction: defaultInstruction };
+	const reason = inactiveReason(mode, input.context, orchestratorTarget);
+	if (reason || !orchestratorTarget) {
+		return { active: false, mode, extensionDir: NATIVE_INTERCOM_EXTENSION_DIR, instruction: defaultInstruction };
 	}
-	if (mode === "fork-only" && input.context !== "fork") {
-		return { active: false, mode, extensionDir, instruction: defaultInstruction };
-	}
-	if (!orchestratorTarget) {
-		return { active: false, mode, extensionDir, instruction: defaultInstruction };
-	}
-	if (!fs.existsSync(extensionDir)) {
-		return { active: false, mode, extensionDir, instruction: defaultInstruction };
-	}
-
-	const configPath = path.resolve(input.configPath ?? defaultIntercomConfigPath(agentDir));
-	const intercomStatus = intercomConfigStatus(configPath);
-	if (intercomStatus.error) console.warn(`Failed to parse intercom config at '${configPath}'. Assuming enabled.`, intercomStatus.error);
-	if (!intercomStatus.enabled) {
-		return { active: false, mode, extensionDir, instruction: defaultInstruction };
-	}
-
-	const instruction = buildIntercomBridgeInstruction(
-		orchestratorTarget,
-		resolveInstructionTemplate(config.instructionFile, settingsDir),
-	);
-
 	return {
 		active: true,
 		mode,
 		orchestratorTarget,
-		extensionDir,
-		instruction,
+		extensionDir: NATIVE_INTERCOM_EXTENSION_DIR,
+		instruction: buildIntercomBridgeInstruction(orchestratorTarget, resolveInstructionTemplate(config.instructionFile, settingsDir)),
 	};
 }
 
 export function applyIntercomBridgeToAgent(agent: AgentConfig, bridge: IntercomBridgeState): AgentConfig {
 	if (!bridge.active || !bridge.orchestratorTarget) return agent;
-	if (!extensionSandboxAllowsIntercom(agent.extensions, bridge.extensionDir)) return agent;
 
 	const bridgeTools = ["intercom", "contact_supervisor"];
 	const tools = agent.tools