pi-subagents 0.13.0 → 0.13.1

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [0.13.1] - 2026-04-13
+
+### Added
+- Added optional intercom orchestration bridge for delegated runs. When enabled via `intercomBridge` (default `fork-only`) and `pi-intercom` is available, child subagents get runtime coordination instructions for contacting the orchestrator session via `intercom`, and `intercom` is auto-added to the child tool allowlist when needed.
+- Added unit coverage for intercom bridge activation, config handling, and extension allowlist behavior.
+
+### Changed
+- Normalized `subagent-executor.ts` relative imports to `.ts` specifiers to match direct TypeScript runtime loading.
+- Documented `pi-intercom` installation and activation requirements in README.
+
+### Fixed
+- Tightened intercom extension allowlist matching to avoid false positives from similarly named extension paths.
+
 ## [0.13.0] - 2026-04-11
 
 ### Added

package/README.md

@@ -331,6 +331,9 @@ 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", ... })`.
+
+> **Note:** Intercom bridging requires the [pi-intercom](https://github.com/nicobailon/pi-intercom) extension. Install it with `pi install npm:pi-intercom`.
 
 All modes support foreground and background execution. Foreground is the default (the call waits and streams progress). For programmatic background launch, use `clarify: false, async: true`. For interactive background launch, use `clarify: true` and press `b` in the TUI before running. Chains with parallel steps (`{ parallel: [...] }`) run concurrently with configurable `concurrency` and `failFast` options.
 
@@ -778,6 +781,27 @@ Sessions are always enabled — every subagent run gets a session directory for
 
 Per-agent `maxSubagentDepth` can tighten that limit further for child runs, but it does not relax an already inherited stricter limit.
 
+### `intercomBridge`
+
+Controls whether subagents receive runtime intercom coordination instructions (and `intercom` is auto-added to their tool allowlist when needed).
+
+```json
+{
+  "intercomBridge": "fork-only"
+}
+```
+
+Values:
+- `"fork-only"` (default): inject intercom bridge only when `context: "fork"`
+- `"always"`: inject bridge in both `fresh` and `fork`
+- `"off"`: disable bridge entirely
+
+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
+- if agent `extensions` is an explicit allowlist, it must include `pi-intercom`
+
 ### `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/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, "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
+ *   { "asyncByDefault": true, "maxSubagentDepth": 1, "intercomBridge": "fork-only", "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
  */
 
 import * as fs from "node:fs";

package/intercom-bridge.ts

@@ -0,0 +1,115 @@
+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";
+
+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 INTERCOM_BRIDGE_MARKER = "Intercom orchestration channel:";
+
+export type IntercomBridgeMode = NonNullable<ExtensionConfig["intercomBridge"]>;
+
+export interface IntercomBridgeState {
+	active: boolean;
+	mode: IntercomBridgeMode;
+	orchestratorTarget?: string;
+	extensionDir: string;
+}
+
+interface ResolveIntercomBridgeInput {
+	mode: unknown;
+	context: "fresh" | "fork" | undefined;
+	orchestratorTarget?: string;
+	extensionDir?: string;
+	configPath?: string;
+}
+
+export function resolveIntercomBridgeMode(value: unknown): IntercomBridgeMode {
+	if (value === "off" || value === "always" || value === "fork-only") return value;
+	return "fork-only";
+}
+
+function intercomEnabled(configPath: string): boolean {
+	if (!fs.existsSync(configPath)) return true;
+	try {
+		const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8")) as { enabled?: unknown };
+		return parsed.enabled !== false;
+	} catch (error) {
+		console.warn(`Failed to parse intercom config at '${configPath}'. Assuming enabled.`, error);
+		return true;
+	}
+}
+
+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);
+	});
+}
+
+function buildIntercomBridgeInstruction(orchestratorTarget: string): string {
+	const escapedTarget = JSON.stringify(orchestratorTarget);
+	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.`;
+}
+
+export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): IntercomBridgeState {
+	const mode = resolveIntercomBridgeMode(input.mode);
+	const extensionDir = path.resolve(input.extensionDir ?? DEFAULT_INTERCOM_EXTENSION_DIR);
+	const orchestratorTarget = input.orchestratorTarget?.trim();
+
+	if (mode === "off") {
+		return { active: false, mode, extensionDir };
+	}
+	if (mode === "fork-only" && input.context !== "fork") {
+		return { active: false, mode, extensionDir };
+	}
+	if (!orchestratorTarget) {
+		return { active: false, mode, extensionDir };
+	}
+	if (!fs.existsSync(extensionDir)) {
+		return { active: false, mode, extensionDir };
+	}
+
+	const configPath = path.resolve(input.configPath ?? DEFAULT_INTERCOM_CONFIG_PATH);
+	if (!intercomEnabled(configPath)) {
+		return { active: false, mode, extensionDir };
+	}
+
+	return {
+		active: true,
+		mode,
+		orchestratorTarget,
+		extensionDir,
+	};
+}
+
+export function applyIntercomBridgeToAgent(agent: AgentConfig, bridge: IntercomBridgeState): AgentConfig {
+	if (!bridge.active || !bridge.orchestratorTarget) return agent;
+	if (!extensionSandboxAllowsIntercom(agent.extensions, bridge.extensionDir)) return agent;
+
+	const tools = agent.tools && !agent.tools.includes("intercom")
+		? [...agent.tools, "intercom"]
+		: agent.tools;
+	const instruction = buildIntercomBridgeInstruction(bridge.orchestratorTarget);
+	const trimmedPrompt = agent.systemPrompt?.trim() || "";
+	const systemPrompt = trimmedPrompt.includes(INTERCOM_BRIDGE_MARKER)
+		? trimmedPrompt
+		: trimmedPrompt
+			? `${trimmedPrompt}\n\n${instruction}`
+			: instruction;
+
+	if (tools === agent.tools && systemPrompt === agent.systemPrompt) return agent;
+	return {
+		...agent,
+		tools,
+		systemPrompt,
+	};
+}

package/package.json

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

package/subagent-executor.ts

@@ -3,27 +3,28 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
-import { type AgentConfig, type AgentScope } from "./agents.js";
-import { getArtifactsDir } from "./artifacts.js";
-import { ChainClarifyComponent, type ChainClarifyResult, type ModelInfo } from "./chain-clarify.js";
-import { executeChain } from "./chain-execution.js";
-import { resolveExecutionAgentScope } from "./agent-scope.js";
-import { handleManagementAction } from "./agent-management.js";
-import { runSync } from "./execution.js";
-import { aggregateParallelOutputs } from "./parallel-utils.js";
-import { recordRun } from "./run-history.js";
+import { type AgentConfig, type AgentScope } from "./agents.ts";
+import { getArtifactsDir } from "./artifacts.ts";
+import { ChainClarifyComponent, type ChainClarifyResult, type ModelInfo } from "./chain-clarify.ts";
+import { executeChain } from "./chain-execution.ts";
+import { resolveExecutionAgentScope } from "./agent-scope.ts";
+import { handleManagementAction } from "./agent-management.ts";
+import { runSync } from "./execution.ts";
+import { aggregateParallelOutputs } from "./parallel-utils.ts";
+import { recordRun } from "./run-history.ts";
 import {
 	getStepAgents,
 	isParallelStep,
 	resolveStepBehavior,
 	type ChainStep,
 	type SequentialStep,
-} from "./settings.js";
-import { discoverAvailableSkills, normalizeSkillInput } from "./skills.js";
-import { executeAsyncChain, executeAsyncSingle, isAsyncAvailable } from "./async-execution.js";
-import { createForkContextResolver } from "./fork-context.js";
-import { finalizeSingleOutput, injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.js";
-import { getSingleResultOutput, mapConcurrent } from "./utils.js";
+} from "./settings.ts";
+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 { finalizeSingleOutput, injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.ts";
+import { getSingleResultOutput, mapConcurrent } from "./utils.ts";
 import {
 	cleanupWorktrees,
 	createWorktrees,
@@ -32,7 +33,7 @@ import {
 	formatWorktreeDiffSummary,
 	formatWorktreeTaskCwdConflict,
 	type WorktreeSetup,
-} from "./worktree.js";
+} from "./worktree.ts";
 import {
 	type AgentProgress,
 	type ArtifactConfig,
@@ -49,7 +50,7 @@ import {
 	resolveChildMaxSubagentDepth,
 	resolveCurrentMaxSubagentDepth,
 	wrapForkTask,
-} from "./types.js";
+} from "./types.ts";
 
 interface TaskParam {
 	agent: string;
@@ -1100,7 +1101,17 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		const scope: AgentScope = resolveExecutionAgentScope(normalizedParams.agentScope);
 		const parentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
 		deps.state.currentSessionId = parentSessionFile ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-		const agents = deps.discoverAgents(ctx.cwd, scope).agents;
+		const discoveredAgents = deps.discoverAgents(ctx.cwd, scope).agents;
+		const piWithSessionName = deps.pi as ExtensionAPI & { getSessionName?: () => string | undefined };
+		const orchestratorTarget = piWithSessionName.getSessionName?.();
+		const intercomBridge = resolveIntercomBridge({
+			mode: deps.config.intercomBridge,
+			context: normalizedParams.context,
+			orchestratorTarget,
+		});
+		const agents = intercomBridge.active
+			? discoveredAgents.map((agent) => applyIntercomBridgeToAgent(agent, intercomBridge))
+			: discoveredAgents;
 		const runId = randomUUID().slice(0, 8);
 		const shareEnabled = normalizedParams.share === true;
 		const hasChain = (normalizedParams.chain?.length ?? 0) > 0;

package/types.ts

@@ -269,6 +269,7 @@ export interface ExtensionConfig {
 	maxSubagentDepth?: number;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	intercomBridge?: "off" | "fork-only" | "always";
 }
 
 // ============================================================================