pi-subagents 0.22.0 → 0.23.1

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## [Unreleased]
 
+## [0.23.1] - 2026-05-02
+
+### Added
+- Persist async per-child session metadata and remember recent foreground child session metadata so `resume` can revive multi-child async runs and foreground children by index.
+
+### Fixed
+- Keep foreground children alive when they call `contact_supervisor` for a blocking decision by treating it as intercom coordination during parent detach, matching the generic `intercom` handoff path.
+- Pause foreground parallel and chain flows when a child detaches for intercom coordination instead of counting the child as a successful completed result and continuing the workflow, and suppress grouped completion receipts for detached chains.
+- Tighten resume/revive safety by rejecting pending async children, detached foreground children that may still be live, ambiguous foreground/async id prefixes, and exact invalid resume matches that would otherwise be masked by a prefix match in the other namespace.
+- Preserve child session metadata in stale-run repaired results and avoid advertising revive from top-level-only or missing child session files.
+- Stop builtin `reviewer` runs from writing progress by default, clarify that review-only/no-edit instructions win over progress-writing or artifact-writing instructions, and suppress automatic progress injection for explicit no-edit tasks even when chain templates use `{task}`.
+- Treat parsed provider errors as failed foreground and async subagent attempts even when the child process exits successfully, and baseline saved output files per fallback attempt.
+- Preserve output-file read and inspect errors instead of silently overwriting or falling back when a changed saved-output path cannot be read.
+- Show each active async widget row's lifecycle status (`running`, `complete`, `failed`, or `paused`) alongside activity and usage stats.
+- Start new direct, slash, prompt-template, foreground, and async subagent launches in compact view while keeping `Ctrl+O` available for live detail.
+- Label top-level async parallel completion notifications as parallel runs instead of leaking the internal chain-shaped runner plan.
+
+## [0.23.0] - 2026-05-02
+
+### Fixed
+- Detect `pi-intercom` when installed through the documented `pi install npm:pi-intercom` package flow, instead of only checking the legacy local extension path.
+
+### Changed
+- Store and discover saved chain workflows from dedicated chain directories: user chains in `~/.pi/agent/chains/**/*.chain.md` and project chains in `.pi/chains/**/*.chain.md`.
+- Retry foreground subagent fallback models when Pi reports a retryable provider error, such as 429/quota, even if the child process exits successfully.
+- Align single-run async subagent widgets and `/subagents-status` rendering with foreground subagent result styling for parallel, chain, and grouped chain runs, including inline live detail when tool output expansion is enabled, while keeping multi-job async widgets compact.
+- Render async subagent widgets through an adaptive component so active parallel agent rows fit without Pi's fixed string-widget truncation marker.
+- Tell parent agents that async runs are detached and they should end the turn instead of running sleep/poll loops when no independent work remains.
+
 ## [0.22.0] - 2026-05-02
 
 ### Added

package/README.md

@@ -211,7 +211,7 @@ The package includes reusable prompt templates for common workflows. You do not
 pi install npm:pi-intercom
 ```
 
-Most users do not call `intercom` directly. After `pi-intercom` is installed, `pi-subagents` can automatically give child agents a private coordination channel back to the parent session.
+Most users do not call `intercom` directly. After `pi-intercom` is installed, `pi-subagents` can automatically give child agents a private coordination channel back to the parent session. The bridge recognizes the normal `pi install npm:pi-intercom` package install as well as legacy local extension checkouts.
 
 Use it for work where the child might need a decision instead of guessing:
 
@@ -225,7 +225,7 @@ Ask oracle to review this plan. If it sees a decision I need to make, have it as
 
 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, and `reason: "progress_update"` for short non-blocking updates when a discovery changes the plan.
+- `contact_supervisor`: the child contacts the parent/supervisor session that delegated the task. Use `reason: "need_decision"` for blocking decisions or clarification, 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.
 
 Child-side routine completion handoffs are still not expected. With the intercom bridge active, parent-side `pi-subagents` sends grouped completion results through `pi-intercom`: one grouped message per foreground parent `subagent` run and one per completed async result file. Acknowledged foreground delivery returns a compact receipt with artifact/session paths; if unacknowledged, the normal full output is preserved. Grouped messages include child intercom targets and full child summaries.
 
@@ -332,6 +332,8 @@ You can combine them in either order:
 /run reviewer "review this diff" --bg --fork
 ```
 
+Background runs are detached. If the parent agent has other independent work, it should keep working. If it has nothing useful to do until the background result arrives, it should end the turn instead of running sleep or status-polling loops. Pi will deliver the completion when the run finishes.
+
 The `oracle` and `worker` builtins are designed for an explicit decision loop. A typical pattern is to ask `oracle` for diagnosis and a recommended execution prompt, then only run `worker` after the main agent approves that direction.
 
 ## Clarify and launch UI
@@ -401,7 +403,7 @@ Agent locations, lowest to highest priority:
 | User | `~/.pi/agent/agents/**/*.md` |
 | Project | `.pi/agents/**/*.md` |
 
-Project discovery also reads legacy `.agents/**/*.md` files. Nested subdirectories are discovered recursively. `.chain.md` files are treated as chains, not agents. If both `.agents/` and `.pi/agents/` define the same parsed runtime agent name, `.pi/agents/` wins. Use `agentScope: "user" | "project" | "both"` to control discovery; `both` is the default and project definitions win runtime-name collisions.
+Project discovery also reads legacy `.agents/**/*.md` files. Nested subdirectories are discovered recursively. `.chain.md` files do not define agents. If both `.agents/` and `.pi/agents/` define the same parsed runtime agent name, `.pi/agents/` wins. Use `agentScope: "user" | "project" | "both"` to control discovery; `both` is the default and project definitions win runtime-name collisions.
 
 Builtin agents load at the lowest priority, so a user or project agent with the same name overrides them. They do not pin a provider model; they inherit your current Pi default model unless you set `subagents.agentOverrides.<name>.model`. `oracle` is an advisory reviewer that critiques direction and proposes an execution prompt without editing files. `worker` is the implementation agent for normal tasks and approved oracle handoffs.
 
@@ -531,14 +533,14 @@ When `extensions` is present, it takes precedence over extension paths implied b
 
 ## Chain files
 
-Chains are reusable `.chain.md` workflows stored next to agent files.
+Chains are reusable `.chain.md` workflows stored separately from agent files.
 
 | Scope | Path |
 |-------|------|
-| User | `~/.pi/agent/agents/**/*.chain.md` |
-| Project | `.pi/agents/**/*.chain.md` |
+| User | `~/.pi/agent/chains/**/*.chain.md` |
+| Project | `.pi/chains/**/*.chain.md` |
 
-Project discovery also reads legacy `.agents/**/*.chain.md` files. Nested subdirectories are discovered recursively. If both locations define the same parsed runtime chain name, `.pi/agents/` wins. Chains support the same optional `package` frontmatter as agents; `name: review-flow` plus `package: code-analysis` runs as `code-analysis.review-flow`.
+Nested subdirectories are discovered recursively. If user and project scopes define the same parsed runtime chain name, the project chain wins. Chains support the same optional `package` frontmatter as agents; `name: review-flow` plus `package: code-analysis` runs as `code-analysis.review-flow`.
 
 Example:
 
@@ -778,11 +780,12 @@ Status and control actions:
 subagent({ action: "status" })
 subagent({ action: "status", id: "<run-id>" })
 subagent({ action: "interrupt", id: "<run-id>" })
-subagent({ action: "resume", id: "<async-run-id>", message: "follow-up question" })
+subagent({ action: "resume", id: "<run-id>", message: "follow-up question" })
+subagent({ action: "resume", id: "<run-id>", index: 1, message: "follow-up for child 2" })
 subagent({ action: "doctor" })
 ```
 
-`resume` sends the follow-up directly when the async child is still reachable over intercom. After completion, it starts a new async child from the stored single-child session file.
+`resume` sends the follow-up directly when an async child is still reachable over intercom. After completion, it revives the child by starting a new async child from the stored child session file. Multi-child async runs and remembered foreground single, parallel, or chain runs can be revived by passing `index` to choose the child. Revive starts a new child process from the old session context; it does not restart the same OS process, and it requires the chosen child to have a persisted `.jsonl` session file.
 
 ## Worktree isolation
 
@@ -893,7 +896,7 @@ Fields:
 - `mode`: default `always`; use `fork-only` to inject only for forked runs, or `off` to disable the bridge.
 - `instructionFile`: optional Markdown template replacing the default bridge instructions. `{orchestratorTarget}` is interpolated. Relative paths resolve from `~/.pi/agent/extensions/subagent/`.
 
-Bridge activation also requires `pi-intercom` to be installed and enabled, a targetable current session name or fallback alias, and `pi-intercom` in any explicit agent `extensions` allowlist.
+Bridge activation also requires `pi-intercom` to be installed and enabled through `pi install npm:pi-intercom` or a legacy local extension checkout, a targetable current session name or fallback alias, and `pi-intercom` in any explicit agent `extensions` allowlist.
 
 The default injected guidance tells children to use `contact_supervisor` with `reason: "need_decision"` when blocked or needing a decision, `reason: "progress_update"` only for meaningful blocked/progress updates, generic `intercom` as fallback plumbing, and avoid routine completion handoffs.
 

package/agents/reviewer.md

@@ -7,7 +7,6 @@ systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
 defaultReads: plan.md, progress.md
-defaultProgress: true
 ---
 
 You are a disciplined review subagent. Your job is to inspect, evaluate, and report findings with evidence. You do not guess; you verify from the code, tests, docs, or requirements.
@@ -59,9 +58,10 @@ Review a PR or issue by understanding the context, then verifying:
 - Prefer small corrective edits over broad rewrites.
 - If everything looks good, say so plainly.
 - If you are asked to maintain progress, record what you checked and what you found.
+- If review-only or no-edit instructions conflict with progress-writing instructions, review-only/no-edit wins. Do not write `progress.md`; mention the conflict in your final review only if it matters.
 
 ## Supervisor coordination
-If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the review plan. Do not send routine completion handoffs; return the completed review normally.
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing; no-edit wins. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the review plan. Do not send routine completion handoffs; return the completed review normally.
 
 Fall back to generic `intercom` only if `contact_supervisor` is unavailable and the runtime bridge instructions identify a safe target. If no safe target is discoverable, do not guess.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.22.0",
+  "version": "0.23.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

@@ -105,7 +105,7 @@ Use this at the start of non-trivial work. Launch `scout` for local context and
 
 ### Parallel cleanup technique
 
-Use this after implementation when the user wants cleanup review or when a final pass would reduce AI-slop. Launch two fresh-context `reviewer` tasks with `output: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that reviewer; otherwise inline the criteria. Both reviewers are review-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. The parent decides what to apply and asks before making changes unless cleanup was already authorized.
+Use this after implementation when the user wants cleanup review or when a final pass would reduce AI-slop. Launch two fresh-context `reviewer` tasks with `output: false` and `progress: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that reviewer; otherwise inline the criteria. Both reviewers are review-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. Review-only/no-edit beats progress-writing or artifact-writing instructions. The parent decides what to apply and asks before making changes unless cleanup was already authorized.
 
 ## Builtin Agents
 
@@ -183,11 +183,10 @@ Agent files can live in:
 - legacy `.agents/**/*.md` — still read for compatibility, but `.pi/agents/` wins on conflicts
 
 Chains live in:
-- `~/.pi/agent/agents/**/*.chain.md`
-- `.pi/agents/**/*.chain.md`
-- legacy `.agents/**/*.chain.md`
+- `~/.pi/agent/chains/**/*.chain.md` — user scope
+- `.pi/chains/**/*.chain.md` — project scope
 
-Discovery is recursive. `.chain.md` files are chains, not agents. Agents and chains can set optional frontmatter `package: code-analysis`; `name: scout` plus `package: code-analysis` registers as runtime name `code-analysis.scout` while serialization keeps `name` and `package` separate.
+Discovery is recursive. `.chain.md` files do not define agents. Agents and chains can set optional frontmatter `package: code-analysis`; `name: scout` plus `package: code-analysis` registers as runtime name `code-analysis.scout` while serialization keeps `name` and `package` separate.
 
 Precedence is by parsed runtime name:
 1. project scope
@@ -263,7 +262,9 @@ without forcing each step to rediscover everything.
 
 ### Async/background
 
-Use async mode whenever the parent agent should keep working while a child runs. A normal foreground `subagent(...)` call blocks the parent until the child completes; it is appropriate when the next parent step depends on the child result. If you say you will "ask a reviewer while I continue auditing" or otherwise run local work in parallel with a child, launch with `async: true`. Do not end your turn immediately after launching that async child if you promised to keep working; continue the local inspection or other independent work, then check the async run when its result is needed.
+Use async mode whenever the parent agent should keep working while a child runs. A normal foreground `subagent(...)` call blocks the parent until the child completes; it is appropriate when the next parent step depends on the child result. If you say you will "ask a reviewer while I continue auditing" or otherwise run local work in parallel with a child, launch with `async: true`.
+
+Do not end your turn immediately after launching an async child if you promised to keep working. Continue the local inspection or other independent work, then check the async run when its result is needed. If there is no independent work left and you would only be running `sleep` or status polling commands to wait, end your turn instead. Pi will deliver the async completion when it arrives.
 
 ```typescript
 subagent({
@@ -289,6 +290,21 @@ const run = subagent({
 
 Inspect async runs with `subagent({ action: "status", id: "..." })`, `subagent({ action: "status" })` for active runs, or the `/subagents-status` slash command.
 
+Use `resume` for follow-up work after a delegated run:
+
+```typescript
+subagent({ action: "resume", id: "run-id", message: "Follow up on this point." })
+subagent({ action: "resume", id: "run-id", index: 1, message: "Continue reviewer 2." })
+```
+
+Resume behavior:
+- If an async child is still running and reachable, `resume` sends the follow-up to that live child over intercom.
+- If an async child has completed, `resume` revives it by starting a new async child from the persisted child session file.
+- Multi-child async runs require `index` unless only one running child is selectable.
+- Completed foreground single, parallel, and chain runs can also be revived by `index` while their run metadata remains in extension state.
+- Revive starts a new child process from the old session context; it does not restart the same OS process.
+- If the chosen child has no persisted `.jsonl` session file, resume fails and reports that directly.
+
 Use diagnostics when setup or child startup looks wrong:
 
 ```typescript
@@ -408,6 +424,8 @@ Use `contact_supervisor` with `reason: "need_decision"` when:
 - a child needs clarification instead of guessing
 - an approval, product, API, or scope choice is required before continuing safely
 
+Do not use `contact_supervisor` just to resolve review-only/no-edit versus progress-writing or artifact-writing instructions. No-edit wins, and the child should return review findings without touching files.
+
 Use `contact_supervisor` with `reason: "progress_update"` when:
 - a child is explicitly asked for progress
 - a meaningful discovery changes the plan

package/src/agents/agent-management.ts

@@ -459,7 +459,9 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 	const scope = scopeRaw as ManagementScope;
 	const isChain = hasKey(cfg, "steps");
 	const d = discoverAgentsAll(ctx.cwd);
-	const targetDir = scope === "user" ? d.userDir : d.projectDir ?? path.join(ctx.cwd, ".pi", "agents");
+	const targetDir = isChain
+		? scope === "user" ? d.userChainDir : d.projectChainDir ?? path.join(ctx.cwd, ".pi", "chains")
+		: scope === "user" ? d.userDir : d.projectDir ?? path.join(ctx.cwd, ".pi", "agents");
 	fs.mkdirSync(targetDir, { recursive: true });
 	if (nameExistsInScope(ctx.cwd, scope, runtimeName)) return result(`Name '${runtimeName}' already exists in ${scope} scope. Use update instead.`, true);
 	const targetPath = path.join(targetDir, isChain ? `${runtimeName}.chain.md` : `${runtimeName}.md`);

package/src/agents/agents.ts

@@ -130,6 +130,10 @@ interface AgentDiscoveryResult {
 	projectAgentsDir: string | null;
 }
 
+export function getUserChainDir(): string {
+	return path.join(os.homedir(), ".pi", "agent", "chains");
+}
+
 function splitToolList(rawTools: string[] | undefined): { tools?: string[]; mcpDirectTools?: string[] } {
 	const mcpDirectTools: string[] = [];
 	const tools: string[] = [];
@@ -705,6 +709,17 @@ function resolveNearestProjectAgentDirs(cwd: string): { readDirs: string[]; pref
 		preferredDir,
 	};
 }
+
+function resolveNearestProjectChainDirs(cwd: string): { readDirs: string[]; preferredDir: string | null } {
+	const projectRoot = findNearestProjectRoot(cwd);
+	if (!projectRoot) return { readDirs: [], preferredDir: null };
+
+	const preferredDir = path.join(projectRoot, ".pi", "chains");
+	return {
+		readDirs: isDirectory(preferredDir) ? [preferredDir] : [],
+		preferredDir,
+	};
+}
 const BUILTIN_AGENTS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "agents");
 
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
@@ -742,12 +757,16 @@ export function discoverAgentsAll(cwd: string): {
 	chains: ChainConfig[];
 	userDir: string;
 	projectDir: string | null;
+	userChainDir: string;
+	projectChainDir: string | null;
 	userSettingsPath: string;
 	projectSettingsPath: string | null;
 } {
 	const userDirOld = path.join(os.homedir(), ".pi", "agent", "agents");
 	const userDirNew = path.join(os.homedir(), ".agents");
+	const userChainDir = getUserChainDir();
 	const { readDirs: projectDirs, preferredDir: projectDir } = resolveNearestProjectAgentDirs(cwd);
+	const { readDirs: projectChainDirs, preferredDir: projectChainDir } = resolveNearestProjectChainDirs(cwd);
 	const userSettingsPath = getUserAgentSettingsPath();
 	const projectSettingsPath = getProjectAgentSettingsPath(cwd);
 	const userSettings = readSubagentSettings(userSettingsPath);
@@ -773,18 +792,17 @@ export function discoverAgentsAll(cwd: string): {
 	const project = Array.from(projectMap.values());
 
 	const chainMap = new Map<string, ChainConfig>();
-	for (const dir of projectDirs) {
+	for (const dir of projectChainDirs) {
 		for (const chain of loadChainsFromDir(dir, "project")) {
 			chainMap.set(chain.name, chain);
 		}
 	}
 	const chains = [
-		...loadChainsFromDir(userDirOld, "user"),
-		...loadChainsFromDir(userDirNew, "user"),
+		...loadChainsFromDir(userChainDir, "user"),
 		...Array.from(chainMap.values()),
 	];
 
 	const userDir = fs.existsSync(userDirNew) ? userDirNew : userDirOld;
 
-	return { builtin, user, project, chains, userDir, projectDir, userSettingsPath, projectSettingsPath };
+	return { builtin, user, project, chains, userDir, projectDir, userChainDir, projectChainDir, userSettingsPath, projectSettingsPath };
 }

package/src/extension/doctor.ts

@@ -192,6 +192,7 @@ export function buildDoctorReport(input: DoctorReportInput): string {
 			config: input.config.intercomBridge,
 			context: input.context,
 			orchestratorTarget: input.orchestratorTarget,
+			cwd: input.cwd,
 		}), input.context).join("\n")).split("\n"),
 	];
 	return lines.join("\n");

package/src/extension/index.ts

@@ -24,7 +24,7 @@ import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import { cleanupOldChainDirs } from "../shared/settings.ts";
 import { renderWidget, renderSubagentResult, stopResultAnimations, stopWidgetAnimation, syncResultAnimation } from "../tui/render.ts";
 import { SubagentParams } from "./schemas.ts";
-import { createSubagentExecutor } from "../runs/foreground/subagent-executor.ts";
+import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
 import { createResultWatcher } from "../runs/background/result-watcher.ts";
 import { registerSlashCommands } from "../slash/slash-commands.ts";
@@ -245,6 +245,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		baseCwd: process.cwd(),
 		currentSessionId: null,
 		asyncJobs: new Map(),
+		foregroundRuns: new Map(),
 		foregroundControls: new Map(),
 		lastForegroundControlId: null,
 		pendingForegroundControlNotices: new Map(),
@@ -336,11 +337,16 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		return new SubagentControlNoticeComponent({ ...details, noticeText: formatSubagentControlNotice(details, content) }, theme);
 	});
 
+	const executeSubagentCollapsed = (id: string, params: SubagentParamsLike, signal: AbortSignal, onUpdate: ((result: AgentToolResult<Details>) => void) | undefined, ctx: ExtensionContext) => {
+		if (ctx.hasUI) ctx.ui.setToolsExpanded(false);
+		return executor.execute(id, params, signal, onUpdate, ctx);
+	};
+
 	const slashBridge = registerSlashSubagentBridge({
 		events: pi.events,
 		getContext: () => state.lastUiContext,
 		execute: (id, params, signal, onUpdate, ctx) =>
-			executor.execute(id, params, signal, onUpdate, ctx),
+			executeSubagentCollapsed(id, params, signal, onUpdate, ctx),
 	});
 
 	const promptTemplateBridge = registerPromptTemplateDelegationBridge({
@@ -348,7 +354,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		getContext: () => state.lastUiContext,
 		execute: async (requestId, request, signal, ctx, onUpdate) => {
 			if (request.tasks && request.tasks.length > 0) {
-				return executor.execute(
+				return executeSubagentCollapsed(
 					requestId,
 					{
 						tasks: request.tasks,
@@ -363,7 +369,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 					ctx,
 				);
 			}
-			return executor.execute(
+			return executeSubagentCollapsed(
 				requestId,
 				{
 					agent: request.agent,
@@ -419,14 +425,14 @@ MANAGEMENT (use action field, omit agent/task/chain/tasks):
 CONTROL:
 • { action: "status", id: "..." } - inspect an async/background run by id or prefix
 • { action: "interrupt", id?: "..." } - soft-interrupt the current child turn and leave the run paused
-• { action: "resume", id: "...", message: "..." } - follow up with a live async child or revive a completed single-child async run from its session
+• { action: "resume", id: "...", message: "...", index?: 0 } - follow up with a live async child or revive a completed async/foreground child from its session
 
 DIAGNOSTICS:
 • { action: "doctor" } - read-only report for runtime paths, discovery, sessions, and intercom`,
 		parameters: SubagentParams,
 
 		execute(id, params, signal, onUpdate, ctx) {
-			return executor.execute(id, params, signal, onUpdate, ctx);
+			return executeSubagentCollapsed(id, params, signal, onUpdate, ctx);
 		},
 
 		renderCall(args, theme) {

package/src/extension/schemas.ts

@@ -116,7 +116,7 @@ export const SubagentParams = Type.Object({
 		description: "Async run directory for action='status' or action='resume'."
 	})),
 	index: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based child index for actions that target a specific child." })),
-	message: Type.Optional(Type.String({ description: "Follow-up message for action='resume'." })),
+	message: Type.Optional(Type.String({ description: "Follow-up message for action='resume'. Use index to choose a child from multi-child runs." })),
 	// Chain identifier for management (can't reuse 'chain' — that's the execution array)
 	chainName: Type.Optional(Type.String({
 		description: "Chain name for get/update/delete management actions"

package/src/intercom/intercom-bridge.ts

@@ -1,19 +1,27 @@
+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";
 
-function defaultIntercomExtensionDir(): string {
-	return path.join(os.homedir(), ".pi", "agent", "extensions", "pi-intercom");
+const PI_INTERCOM_PACKAGE_NAME = "pi-intercom";
+const CONFIG_DIR = ".pi";
+
+function defaultAgentDir(): string {
+	return path.join(os.homedir(), ".pi", "agent");
+}
+
+function defaultIntercomExtensionDir(agentDir = defaultAgentDir()): string {
+	return path.join(agentDir, "extensions", PI_INTERCOM_PACKAGE_NAME);
 }
 
-function defaultIntercomConfigPath(): string {
-	return path.join(os.homedir(), ".pi", "agent", "intercom", "config.json");
+function defaultIntercomConfigPath(agentDir = defaultAgentDir()): string {
+	return path.join(agentDir, "intercom", "config.json");
 }
 
-function defaultSubagentConfigDir(): string {
-	return path.join(os.homedir(), ".pi", "agent", "extensions", "subagent");
+function defaultSubagentConfigDir(agentDir = defaultAgentDir()): string {
+	return path.join(agentDir, "extensions", "subagent");
 }
 
 const DEFAULT_INTERCOM_TARGET_PREFIX = "subagent-chat";
@@ -23,6 +31,7 @@ const DEFAULT_INTERCOM_BRIDGE_TEMPLATE = `The inherited thread is reference-only
 Use contact_supervisor first. It resolves the supervisor session "{orchestratorTarget}" and run metadata automatically.
 - Need a decision, blocked, approval, or product/API/scope ambiguity: contact_supervisor({ reason: "need_decision", message: "<question>" })
 - After contact_supervisor with reason "need_decision", stay alive and continue only after the reply arrives. Do not finish your final response with a choose-one question.
+- Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing or artifact-writing instructions. Review-only/no-edit wins; leave files unchanged and mention the conflict in your final result only if it matters.
 - Meaningful progress or unexpected discoveries that change the plan: contact_supervisor({ reason: "progress_update", message: "UPDATE: <summary>" })
 - Generic intercom is lower-level plumbing/fallback only: intercom({ action: "ask", to: "{orchestratorTarget}", message: "<question>" })
 
@@ -56,6 +65,9 @@ interface ResolveIntercomBridgeInput {
 	extensionDir?: string;
 	configPath?: string;
 	settingsDir?: string;
+	cwd?: string;
+	agentDir?: string;
+	globalNpmRoot?: string | null;
 }
 
 export function resolveIntercomSessionTarget(sessionName: string | undefined, sessionId: string): string {
@@ -102,6 +114,121 @@ function intercomConfigStatus(configPath: string): { enabled: boolean; error?: u
 	}
 }
 
+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 = path.join(current, CONFIG_DIR);
+		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 configuredPiIntercomPackageDir(input: ResolveIntercomBridgeInput, agentDir: string): string | undefined {
+	const cwd = path.resolve(input.cwd ?? process.cwd());
+	const projectConfigDir = findNearestProjectConfigDir(cwd);
+	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 ?? defaultIntercomExtensionDir(agentDir));
+	if (fs.existsSync(legacyDir)) return legacyDir;
+	return configuredPiIntercomPackageDir(input, agentDir) ?? legacyDir;
+}
+
 function extensionSandboxAllowsIntercom(extensions: string[] | undefined, extensionDir: string): boolean {
 	if (extensions === undefined) return true;
 
@@ -145,9 +272,10 @@ ${instruction}`;
 export function diagnoseIntercomBridge(input: ResolveIntercomBridgeInput): IntercomBridgeDiagnostic {
 	const config = resolveIntercomBridgeConfig(input.config);
 	const mode = config.mode;
-	const extensionDir = path.resolve(input.extensionDir ?? defaultIntercomExtensionDir());
+	const agentDir = path.resolve(input.agentDir ?? defaultAgentDir());
+	const extensionDir = resolveIntercomExtensionDir(input, agentDir);
 	const orchestratorTarget = input.orchestratorTarget?.trim();
-	const configPath = path.resolve(input.configPath ?? defaultIntercomConfigPath());
+	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;
@@ -183,9 +311,10 @@ export function diagnoseIntercomBridge(input: ResolveIntercomBridgeInput): Inter
 export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): IntercomBridgeState {
 	const config = resolveIntercomBridgeConfig(input.config);
 	const mode = config.mode;
-	const extensionDir = path.resolve(input.extensionDir ?? defaultIntercomExtensionDir());
+	const agentDir = path.resolve(input.agentDir ?? defaultAgentDir());
+	const extensionDir = resolveIntercomExtensionDir(input, agentDir);
 	const orchestratorTarget = input.orchestratorTarget?.trim();
-	const settingsDir = path.resolve(input.settingsDir ?? defaultSubagentConfigDir());
+	const settingsDir = path.resolve(input.settingsDir ?? defaultSubagentConfigDir(agentDir));
 	const defaultInstruction = buildIntercomBridgeInstruction(
 		orchestratorTarget || "{orchestratorTarget}",
 		DEFAULT_INTERCOM_BRIDGE_TEMPLATE,
@@ -204,7 +333,7 @@ export function resolveIntercomBridge(input: ResolveIntercomBridgeInput): Interc
 		return { active: false, mode, extensionDir, instruction: defaultInstruction };
 	}
 
-	const configPath = path.resolve(input.configPath ?? defaultIntercomConfigPath());
+	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) {

package/src/intercom/result-intercom.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
 import {
 	type Details,
 	type IntercomEventBus,
@@ -76,11 +77,15 @@ function asyncResumeGuidance(input: {
 	asyncId?: string;
 }): string | undefined {
 	if (input.source !== "async" || !input.asyncId) return undefined;
-	if (input.children.length === 1 && typeof input.children[0]?.sessionPath === "string") {
+	const resumable = input.children.filter((child) => typeof child.sessionPath === "string" && fs.existsSync(child.sessionPath));
+	if (input.children.length === 1 && resumable.length === 1) {
 		return `Revive: subagent({ action: "resume", id: "${input.asyncId}", message: "..." })`;
 	}
-	if (input.children.length > 1) return "Resume: unsupported for multi-child async runs until per-child session files are persisted.";
-	return "Resume: unavailable; no single child session file was persisted.";
+	if (resumable.length > 0) {
+		const firstIndex = resumable[0]?.index ?? input.children.indexOf(resumable[0]!);
+		return `Revive child: subagent({ action: "resume", id: "${input.asyncId}", index: ${firstIndex}, message: "..." })`;
+	}
+	return "Resume: unavailable; no child session file was persisted.";
 }
 
 function formatSubagentResultIntercomMessage(input: {