pi-subagents 0.33.0 → 0.33.1

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [0.33.1] - 2026-07-03
+
+### Fixed
+- Avoid native supervisor-channel tool conflicts when `pi-intercom` is also installed by deferring native tool registration until runtime startup and keeping a namespaced native supervisor reply tool.
+
 ## [0.33.0] - 2026-07-03
 
 ### Added

package/README.md

@@ -267,7 +267,7 @@ Add `autofix` to `/parallel-review` or `/parallel-cleanup` to apply only the syn
 
 ## Native supervisor coordination
 
-Child agents can talk back to the parent Pi session without installing `pi-intercom`. `pi-subagents` now provides the child-facing `contact_supervisor` tool and the parent-facing `intercom({ action: "reply" })` path natively.
+Child agents can talk back to the parent Pi session without installing `pi-intercom`. `pi-subagents` now provides the child-facing `contact_supervisor` tool and the parent-facing `subagent_supervisor({ action: "reply" })` path natively. If no external `pi-intercom` tool owns the `intercom` name, the native channel also exposes `intercom` as a compatibility fallback.
 
 Use it for work where the child might need a decision instead of guessing:
 
@@ -283,7 +283,7 @@ The child can use one dedicated coordination tool:
 
 - `contact_supervisor`: the child contacts the parent/supervisor session that delegated the task. Use `reason: "need_decision"` for blocking decisions or clarification, `reason: "interview_request"` for structured input, and `reason: "progress_update"` for short non-blocking updates when a discovery changes the plan. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing or artifact-writing instructions; no-edit wins.
 
-Supervisor messages are scoped to the exact Pi session id that spawned the child. A second Pi session in the same repository does not receive those requests.
+The parent replies with `subagent_supervisor({ action: "reply", replyTo, message })` or checks pending requests with `subagent_supervisor({ action: "pending" })`. Supervisor messages are scoped to the exact Pi session id that spawned the child. A second Pi session in the same repository does not receive those requests.
 
 Child-side routine completion handoffs are still not expected. If a child appears stalled, needs-attention notices can show up in the parent session with useful next actions, such as checking `subagent({ action: "status" })`, interrupting the run, or nudging the child.
 

package/package.json

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

package/skills/pi-subagents/SKILL.md

@@ -550,18 +550,20 @@ contact_supervisor({
 })
 ```
 
-The parent replies with:
+The parent replies with the native supervisor tool:
 
 ```typescript
-intercom({ action: "reply", message: "Optimize for readability." })
+subagent_supervisor({ action: "reply", message: "Optimize for readability." })
 ```
 
 Or inspects unresolved asks first:
 
 ```typescript
-intercom({ action: "pending" })
+subagent_supervisor({ action: "pending" })
 ```
 
+If no external `pi-intercom` tool owns the `intercom` name, native supervisor coordination may also expose `intercom` as a compatibility fallback. Prefer `subagent_supervisor` for parent replies because it never overrides installed `pi-intercom`.
+
 If intercom messages do not show up, run `subagent({ action: "doctor" })` or `/subagents-doctor`.
 
 ## Management Mode

package/src/intercom/native-supervisor-channel.ts

@@ -18,6 +18,7 @@ import { writeAtomicJson } from "../shared/atomic-json.ts";
 const SUPERVISOR_CHANNEL_ROOT = path.join(TEMP_ROOT_DIR, "supervisor-channels");
 const REQUESTS_DIR = "requests";
 const REPLIES_DIR = "replies";
+export const NATIVE_SUPERVISOR_TOOL_NAME = "subagent_supervisor";
 const MAX_MESSAGE_BYTES = 64 * 1024;
 const DEFAULT_ASK_TIMEOUT_MS = 10 * 60 * 1000;
 const CHANNEL_POLL_MS = Math.min(POLL_INTERVAL_MS, 500);
@@ -275,8 +276,9 @@ function hasTool(pi: ExtensionAPI, name: string): boolean {
 	}
 }
 
-export function registerNativeSupervisorClient(pi: ExtensionAPI): void {
+export function registerNativeSupervisorClient(pi: ExtensionAPI, options: { includeIntercomFallback?: boolean } = {}): void {
 	if (!readChildMetadata()) return;
+	const includeIntercomFallback = options.includeIntercomFallback !== false;
 	if (!hasTool(pi, "contact_supervisor")) {
 		const tool: ToolDefinition<typeof ContactSupervisorParamsSchema, Record<string, unknown>> = {
 			name: "contact_supervisor",
@@ -289,7 +291,7 @@ export function registerNativeSupervisorClient(pi: ExtensionAPI): void {
 		};
 		pi.registerTool(tool);
 	}
-	if (!hasTool(pi, "intercom")) {
+	if (includeIntercomFallback && !hasTool(pi, "intercom")) {
 		const tool: ToolDefinition<typeof IntercomParamsSchema, Record<string, unknown>> = {
 			name: "intercom",
 			label: "Intercom",
@@ -349,12 +351,13 @@ function listRequestFiles(): Array<{ channelDir: string; file: string }> {
 }
 
 function currentContextSessionId(state: Pick<SubagentState, "currentSessionId">, ctx: ExtensionContext): string | undefined {
-	if (state.currentSessionId) return state.currentSessionId;
 	try {
-		return ctx.sessionManager.getSessionId();
+		const sessionId = ctx.sessionManager.getSessionId();
+		if (sessionId) return sessionId;
 	} catch {
-		return undefined;
+		// Fall through to the last known identity.
 	}
+	return state.currentSessionId ?? undefined;
 }
 
 function requestMatchesContext(request: SupervisorRequest, state: Pick<SubagentState, "currentSessionId">, ctx: ExtensionContext): boolean {
@@ -363,14 +366,14 @@ function requestMatchesContext(request: SupervisorRequest, state: Pick<SubagentS
 }
 
 function formatPendingLine(request: PendingSupervisorRequest): string {
-	const replyHint = request.expectsReply ? ` Reply: intercom({ action: "reply", replyTo: "${request.id}", message: "..." })` : "";
+	const replyHint = request.expectsReply ? ` Reply: ${NATIVE_SUPERVISOR_TOOL_NAME}({ action: "reply", replyTo: "${request.id}", message: "..." })` : "";
 	return `- ${request.id}: ${request.agent} [${request.runId}#${request.childIndex}] ${request.reason}.${replyHint}`;
 }
 
 function requestVisibleText(request: PendingSupervisorRequest): string {
 	const lines = [request.message];
 	if (request.expectsReply) {
-		lines.push("", `Reply with: intercom({ action: "reply", replyTo: "${request.id}", message: "..." })`);
+		lines.push("", `Reply with: ${NATIVE_SUPERVISOR_TOOL_NAME}({ action: "reply", replyTo: "${request.id}", message: "..." })`);
 	}
 	return lines.join("\n");
 }
@@ -424,11 +427,13 @@ function publicPendingRequests(pending: Map<string, PendingSupervisorRequest>):
 	}));
 }
 
-function buildParentIntercomTool(pending: Map<string, PendingSupervisorRequest>): ToolDefinition<typeof IntercomParamsSchema, Record<string, unknown>> {
+function buildParentIntercomTool(pending: Map<string, PendingSupervisorRequest>, name = "intercom"): ToolDefinition<typeof IntercomParamsSchema, Record<string, unknown>> {
 	return {
-		name: "intercom",
-		label: "Intercom",
-		description: "Native pi-subagents supervisor channel. Use reply/pending/status to answer child subagent requests.",
+		name,
+		label: name === "intercom" ? "Intercom" : "Subagent Supervisor",
+		description: name === "intercom"
+			? "Native pi-subagents supervisor channel. Use reply/pending/status to answer child subagent requests."
+			: "Native pi-subagents supervisor channel. Use reply/pending/status to answer child subagent requests without overriding pi-intercom.",
 		parameters: IntercomParamsSchema,
 		async execute(_id, params) {
 			const input = params as IntercomParams;
@@ -458,7 +463,10 @@ export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentS
 	const seenFiles = new Set<string>();
 	let poller: ReturnType<typeof setInterval> | undefined;
 
-	if (!hasTool(pi, "intercom")) pi.registerTool(buildParentIntercomTool(pending));
+	const registerParentTools = (): void => {
+		if (!hasTool(pi, NATIVE_SUPERVISOR_TOOL_NAME)) pi.registerTool(buildParentIntercomTool(pending, NATIVE_SUPERVISOR_TOOL_NAME));
+		if (!hasTool(pi, "intercom")) pi.registerTool(buildParentIntercomTool(pending));
+	};
 
 	const poll = (): void => {
 		const ctx = state.lastUiContext;
@@ -495,6 +503,7 @@ export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentS
 	return {
 		start: () => {
 			if (poller) return;
+			registerParentTools();
 			poll();
 			poller = setInterval(poll, CHANNEL_POLL_MS);
 			poller.unref?.();

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -261,7 +261,21 @@ function registerSteeringInbox(pi: ExtensionAPI): void {
 export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 	registerSteeringInbox(pi);
 	registerToolBudget(pi, decodeToolBudgetEnv(process.env[TOOL_BUDGET_ENV]));
-	registerNativeSupervisorClient(pi);
+	let nativeSupervisorClientRegistered = false;
+	let nativeSupervisorFallbackRegistered = false;
+	const registerNativeSupervisorClientOnce = (): void => {
+		if (nativeSupervisorClientRegistered) return;
+		nativeSupervisorClientRegistered = true;
+		registerNativeSupervisorClient(pi, { includeIntercomFallback: false });
+	};
+	const registerNativeSupervisorFallbackOnce = (): void => {
+		registerNativeSupervisorClientOnce();
+		if (nativeSupervisorFallbackRegistered) return;
+		nativeSupervisorFallbackRegistered = true;
+		registerNativeSupervisorClient(pi);
+	};
+	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown) => unknown) => void;
+	onRuntimeEvent("session_start", registerNativeSupervisorClientOnce);
 	const structuredOutputPath = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV];
 	const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
 	if (structuredOutputPath && structuredSchemaPath) {
@@ -300,7 +314,6 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 		});
 	}
 
-	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown) => unknown) => void;
 	onRuntimeEvent("context", (event: { messages: unknown[] }) => {
 		const messages = stripParentOnlySubagentMessages(event.messages);
 		if (messages === event.messages) return undefined;
@@ -308,6 +321,7 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 	});
 
 	onRuntimeEvent("before_agent_start", async (event: { systemPrompt: string }) => {
+		registerNativeSupervisorFallbackOnce();
 		const intercomSessionName = process.env[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
 		if (intercomSessionName && typeof pi.setSessionName === "function") {
 			pi.setSessionName(intercomSessionName);