pi-subagents 0.31.0 → 0.32.0

package/src/extension/companion-suggestions.ts

@@ -0,0 +1,359 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { diagnoseIntercomBridge, type IntercomBridgeDiagnostic, resolveIntercomSessionTarget } from "../intercom/intercom-bridge.ts";
+import type { CompanionSuggestionPackage, CompanionSuggestionSurface, ExtensionConfig, SubagentState } from "../shared/types.ts";
+import { getAgentDir } from "../shared/utils.ts";
+import { updateConfig } from "./config.ts";
+
+const PROMPT_TEMPLATE_MODEL: CompanionSuggestionPackage = "pi-prompt-template-model";
+const PI_INTERCOM: CompanionSuggestionPackage = "pi-intercom";
+const COMPANION_PACKAGES = [PI_INTERCOM, PROMPT_TEMPLATE_MODEL] as const;
+const DEFAULT_SURFACES: CompanionSuggestionSurface[] = ["session_start", "list", "doctor"];
+
+interface SourceInfoLike {
+	path?: unknown;
+	source?: unknown;
+	baseDir?: unknown;
+}
+
+interface NamedRuntimeResource {
+	name?: unknown;
+	sourceInfo?: unknown;
+}
+
+interface IntercomConfigStatus {
+	enabled: boolean;
+	error?: string;
+}
+
+export interface CompanionPackageStatus {
+	packageName: CompanionSuggestionPackage;
+	active: boolean;
+	disabled: boolean;
+	dismissed: boolean;
+	surfaces: Set<CompanionSuggestionSurface>;
+	installCommand: string;
+	benefit: string;
+	statusSource: string;
+	reason: string;
+	details?: string[];
+	intercomBridge?: IntercomBridgeDiagnostic;
+}
+
+interface CollectCompanionStatusesInput {
+	pi: Pick<ExtensionAPI, "getAllTools" | "getCommands">;
+	config: ExtensionConfig;
+	cwd: string;
+	context?: "fresh" | "fork";
+	orchestratorTarget?: string;
+	workspaceKey?: string;
+	fast?: boolean;
+}
+
+interface CompanionMessageInput {
+	pi: Pick<ExtensionAPI, "sendMessage">;
+	ctx: ExtensionContext;
+	state: SubagentState;
+	statuses: CompanionPackageStatus[];
+}
+
+function commandBaseName(name: string): string {
+	return name.replace(/:\d+$/, "");
+}
+
+function sourceValueMatchesPackage(value: string, packageName: CompanionSuggestionPackage): boolean {
+	const normalized = value.replaceAll("\\", "/").toLowerCase();
+	const escaped = packageName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	return new RegExp(`(^|[/:@])${escaped}($|[/:@])`).test(normalized);
+}
+
+function sourceInfoMatchesPackage(sourceInfo: unknown, packageName: CompanionSuggestionPackage): boolean {
+	if (!sourceInfo || typeof sourceInfo !== "object" || Array.isArray(sourceInfo)) return false;
+	const info = sourceInfo as SourceInfoLike;
+	return [info.path, info.source, info.baseDir]
+		.some((value) => typeof value === "string" && sourceValueMatchesPackage(value, packageName));
+}
+
+function namedResourcesFrom(value: unknown): NamedRuntimeResource[] {
+	return Array.isArray(value) ? value.filter((entry): entry is NamedRuntimeResource => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry)) : [];
+}
+
+function hasPackageCommand(pi: Pick<ExtensionAPI, "getCommands">, packageName: CompanionSuggestionPackage, commandName: string): boolean {
+	return namedResourcesFrom(pi.getCommands()).some((command) =>
+		typeof command.name === "string"
+		&& commandBaseName(command.name) === commandName
+		&& sourceInfoMatchesPackage(command.sourceInfo, packageName)
+	);
+}
+
+function hasPackageTool(pi: Pick<ExtensionAPI, "getAllTools">, packageName: CompanionSuggestionPackage, toolName: string): boolean {
+	return namedResourcesFrom(pi.getAllTools()).some((tool) =>
+		typeof tool.name === "string"
+		&& commandBaseName(tool.name) === toolName
+		&& sourceInfoMatchesPackage(tool.sourceInfo, packageName)
+	);
+}
+
+function nearestGitRoot(cwd: string): string | undefined {
+	let current = path.resolve(cwd);
+	while (true) {
+		if (fs.existsSync(path.join(current, ".git"))) return current;
+		const parent = path.dirname(current);
+		if (parent === current) return undefined;
+		current = parent;
+	}
+}
+
+export function companionWorkspaceKey(cwd: string): string {
+	return nearestGitRoot(cwd) ?? path.resolve(cwd);
+}
+
+function normalizeSurface(value: unknown): CompanionSuggestionSurface | undefined {
+	return value === "session_start" || value === "list" || value === "doctor" ? value : undefined;
+}
+
+function packageConfig(config: ExtensionConfig, packageName: CompanionSuggestionPackage) {
+	const companionConfig = config.companionSuggestions;
+	if (companionConfig === false) return { enabled: false, surfaces: new Set<CompanionSuggestionSurface>(), dismissed: false };
+	const packageSpecific = companionConfig?.packages?.[packageName];
+	const surfaces = Array.isArray(packageSpecific?.surfaces)
+		? packageSpecific.surfaces.map(normalizeSurface).filter((surface): surface is CompanionSuggestionSurface => Boolean(surface))
+		: DEFAULT_SURFACES;
+	return {
+		enabled: companionConfig?.enabled !== false && packageSpecific?.enabled !== false,
+		surfaces: new Set(surfaces),
+		dismissedConfig: packageSpecific?.dismissed,
+	};
+}
+
+function isDismissed(config: ExtensionConfig, packageName: CompanionSuggestionPackage, workspaceKey: string): boolean {
+	const dismissed = packageConfig(config, packageName).dismissedConfig;
+	return dismissed?.user === true || dismissed?.workspaces?.includes(workspaceKey) === true;
+}
+
+function readPiIntercomConfigStatus(agentDir = getAgentDir()): IntercomConfigStatus {
+	const configPath = path.join(agentDir, "intercom", "config.json");
+	if (!fs.existsSync(configPath)) return { enabled: true };
+	try {
+		const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8")) as unknown;
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { enabled: true };
+		return { enabled: (parsed as { enabled?: unknown }).enabled !== false };
+	} catch (error) {
+		return { enabled: true, error: error instanceof Error ? `${error.name}: ${error.message}` : String(error) };
+	}
+}
+
+function promptTemplateModelStatus(input: CollectCompanionStatusesInput, workspaceKey: string): CompanionPackageStatus {
+	const config = packageConfig(input.config, PROMPT_TEMPLATE_MODEL);
+	const active = hasPackageCommand(input.pi, PROMPT_TEMPLATE_MODEL, "prompt-tool");
+	return {
+		packageName: PROMPT_TEMPLATE_MODEL,
+		active,
+		disabled: !config.enabled,
+		dismissed: isDismissed(input.config, PROMPT_TEMPLATE_MODEL, workspaceKey),
+		surfaces: config.surfaces,
+		installCommand: "pi install npm:pi-prompt-template-model",
+		benefit: "reusable prompt-template workflows with model/thinking/skill/subagent frontmatter",
+		statusSource: "active runtime command: prompt-tool",
+		reason: active ? "active" : "prompt-tool command from pi-prompt-template-model is not active in this session",
+	};
+}
+
+function piIntercomStatus(input: CollectCompanionStatusesInput, workspaceKey: string): CompanionPackageStatus {
+	const config = packageConfig(input.config, PI_INTERCOM);
+	const parentToolActive = hasPackageTool(input.pi, PI_INTERCOM, "intercom");
+	const intercomConfig = readPiIntercomConfigStatus();
+	const bridge = diagnoseIntercomBridge({
+		config: input.config.intercomBridge,
+		context: input.context,
+		orchestratorTarget: input.orchestratorTarget,
+		cwd: input.cwd,
+		globalNpmRoot: input.fast ? null : undefined,
+	});
+	const active = parentToolActive && intercomConfig.enabled && (!bridge.wantsIntercom || bridge.piIntercomAvailable);
+	const details = [
+		`parent runtime tool: ${parentToolActive ? "active" : "inactive"}`,
+		`bridge: ${bridge.active ? "active" : "inactive"}${bridge.reason ? ` (${bridge.reason})` : ""}`,
+		...(intercomConfig.error ? [`intercom config warning: ${intercomConfig.error}; runtime assumes enabled`] : []),
+	];
+	return {
+		packageName: PI_INTERCOM,
+		active,
+		disabled: !config.enabled,
+		dismissed: isDismissed(input.config, PI_INTERCOM, workspaceKey),
+		surfaces: config.surfaces,
+		installCommand: "pi install npm:pi-intercom",
+		benefit: "live supervisor decisions, progress updates, and grouped result delivery",
+		statusSource: "active runtime intercom tool plus intercom bridge diagnostics",
+		reason: active
+			? "active"
+			: !intercomConfig.enabled
+				? "pi-intercom config is disabled"
+				: parentToolActive
+					? "pi-intercom is active in the parent runtime, but child bridge discovery is not ready"
+					: "intercom tool from pi-intercom is not active in this session",
+		details,
+		intercomBridge: bridge,
+	};
+}
+
+export function collectCompanionStatuses(input: CollectCompanionStatusesInput): CompanionPackageStatus[] {
+	const workspaceKey = input.workspaceKey ?? companionWorkspaceKey(input.cwd);
+	return [
+		piIntercomStatus(input, workspaceKey),
+		promptTemplateModelStatus(input, workspaceKey),
+	];
+}
+
+function shouldRecommend(status: CompanionPackageStatus, surface: CompanionSuggestionSurface): boolean {
+	if (status.disabled || status.dismissed || status.active || !status.surfaces.has(surface)) return false;
+	if (status.packageName === PI_INTERCOM && status.reason === "pi-intercom config is disabled" && surface !== "doctor") return false;
+	if (status.packageName === PI_INTERCOM && status.intercomBridge?.wantsIntercom === false && surface !== "doctor") return false;
+	return true;
+}
+
+export function buildCompanionListLines(statuses: CompanionPackageStatus[]): string[] {
+	const recommended = statuses.filter((status) => shouldRecommend(status, "list"));
+	if (recommended.length === 0) return [];
+	const lines = ["Recommended companions:"];
+	for (const status of recommended) {
+		lines.push(`- ${status.packageName} is not active in this session.`);
+		lines.push(`  Benefit: ${status.benefit}.`);
+		lines.push(`  Run: ${status.installCommand}, then restart Pi or /reload.`);
+		lines.push(`  Hide: /subagents-companions hide ${status.packageName} workspace`);
+	}
+	return lines;
+}
+
+export function buildCompanionDoctorLines(statuses: CompanionPackageStatus[]): string[] {
+	const lines = ["Companion packages"];
+	for (const status of statuses) {
+		const hidden = status.dismissed ? " recommendation hidden by config" : "";
+		const disabled = status.disabled ? " disabled by config" : "";
+		lines.push(`- ${status.packageName}: ${status.active ? "active" : "inactive"}${hidden}${disabled}`);
+		lines.push(`  install: ${status.installCommand}`);
+		lines.push(`  benefit: ${status.benefit}`);
+		lines.push(`  status source: ${status.statusSource}`);
+		lines.push(`  reason: ${status.reason}`);
+		for (const detail of status.details ?? []) lines.push(`  ${detail}`);
+	}
+	return lines;
+}
+
+export function buildCompanionStartupMessage(statuses: CompanionPackageStatus[]): string | null {
+	const recommended = statuses.filter((status) => shouldRecommend(status, "session_start"));
+	if (recommended.length === 0) return null;
+	const lines = [
+		recommended.length === 1
+			? `Recommended: install ${recommended[0]!.packageName} for pi-subagents.`
+			: "Recommended: install companion packages for pi-subagents.",
+		"",
+	];
+	for (const status of recommended) {
+		lines.push(`- ${status.packageName}: ${status.benefit}.`);
+		lines.push(`  Run: ${status.installCommand}`);
+	}
+	lines.push(
+		"",
+		recommended.length === 1 ? "I can help you run that install command." : "I can help you run those install commands.",
+		"",
+		"Or hide a recommendation:",
+	);
+	for (const status of recommended) {
+		lines.push(`  /subagents-companions hide ${status.packageName} workspace`);
+	}
+	return lines.join("\n");
+}
+
+export function maybeSendCompanionStartupMessage(input: CompanionMessageInput): void {
+	if (!input.ctx.hasUI || input.state.companionSuggestionStartupShown) return;
+	const message = buildCompanionStartupMessage(input.statuses);
+	if (!message) return;
+	input.state.companionSuggestionStartupShown = true;
+	input.pi.sendMessage({
+		customType: "subagent_companion_suggestions",
+		content: message,
+		display: true,
+		details: { packages: input.statuses.filter((status) => shouldRecommend(status, "session_start")).map((status) => status.packageName) },
+	});
+}
+
+function parseCompanionPackage(value: string | undefined): CompanionSuggestionPackage | undefined {
+	return COMPANION_PACKAGES.find((packageName) => packageName === value);
+}
+
+function packageDismissedWorkspaces(value: unknown): string[] {
+	return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+}
+
+export function updateCompanionDismissal(packageName: CompanionSuggestionPackage, scope: "workspace" | "user" | "show", cwd: string): ExtensionConfig {
+	const workspaceKey = companionWorkspaceKey(cwd);
+	return updateConfig((current) => {
+		const companionSuggestions = current.companionSuggestions === false
+			? { enabled: false }
+			: current.companionSuggestions ?? {};
+		const packages = companionSuggestions.packages ?? {};
+		const packageConfig = packages[packageName] ?? {};
+		const dismissed = { ...(packageConfig.dismissed ?? {}) };
+		if (scope === "user") {
+			dismissed.user = true;
+		} else if (scope === "workspace") {
+			dismissed.workspaces = [...new Set([...packageDismissedWorkspaces(dismissed.workspaces), workspaceKey])];
+		} else {
+			delete dismissed.user;
+			dismissed.workspaces = packageDismissedWorkspaces(dismissed.workspaces).filter((entry) => entry !== workspaceKey);
+			if (dismissed.workspaces.length === 0) delete dismissed.workspaces;
+		}
+		return {
+			...current,
+			companionSuggestions: {
+				...companionSuggestions,
+				packages: {
+					...packages,
+					[packageName]: {
+						...packageConfig,
+						...(Object.keys(dismissed).length > 0 ? { dismissed } : { dismissed: undefined }),
+					},
+				},
+			},
+		};
+	});
+}
+
+export function buildCompanionCommandStatus(statuses: CompanionPackageStatus[]): string {
+	return buildCompanionDoctorLines(statuses).join("\n");
+}
+
+export function handleCompanionCommand(args: string, ctx: ExtensionContext, statuses: CompanionPackageStatus[]): { text: string; updatedConfig?: ExtensionConfig; error?: boolean } {
+	const parts = args.trim().split(/\s+/).filter(Boolean);
+	if (parts.length === 0 || parts[0] === "status") {
+		return { text: buildCompanionCommandStatus(statuses) };
+	}
+	if (parts[0] !== "hide" && parts[0] !== "show") {
+		return { text: "Usage: /subagents-companions status | hide <pi-intercom|pi-prompt-template-model> <workspace|user> | show <pi-intercom|pi-prompt-template-model>", error: true };
+	}
+	const packageName = parseCompanionPackage(parts[1]);
+	if (!packageName) {
+		return { text: "Unknown companion package. Use pi-intercom or pi-prompt-template-model.", error: true };
+	}
+	if (parts[0] === "show") {
+		return { text: `Showing ${packageName} recommendations for this workspace again.`, updatedConfig: updateCompanionDismissal(packageName, "show", ctx.cwd) };
+	}
+	const scope = parts[2];
+	if (scope !== "workspace" && scope !== "user") {
+		return { text: "Usage: /subagents-companions hide <pi-intercom|pi-prompt-template-model> <workspace|user>", error: true };
+	}
+	return {
+		text: scope === "user" ? `Hid ${packageName} recommendations for this user.` : `Hid ${packageName} recommendations for this workspace.`,
+		updatedConfig: updateCompanionDismissal(packageName, scope, ctx.cwd),
+	};
+}
+
+export function resolveCompanionOrchestratorTarget(pi: Pick<ExtensionAPI, "getSessionName">, ctx: ExtensionContext): string | undefined {
+	try {
+		return resolveIntercomSessionTarget(pi.getSessionName(), ctx.sessionManager.getSessionId());
+	} catch {
+		return undefined;
+	}
+}

package/src/extension/config.ts

@@ -3,12 +3,35 @@ import * as path from "node:path";
 import type { ExtensionConfig } from "../shared/types.ts";
 import { getAgentDir } from "../shared/utils.ts";
 
+export function getConfigPath(): string {
+	return path.join(getAgentDir(), "extensions", "subagent", "config.json");
+}
+
+function readConfigForUpdate(configPath = getConfigPath()): ExtensionConfig {
+	if (!fs.existsSync(configPath)) return {};
+	const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8")) as unknown;
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`Subagent config at '${configPath}' must be a JSON object`);
+	}
+	return parsed as ExtensionConfig;
+}
+
+export function saveConfig(config: ExtensionConfig, configPath = getConfigPath()): void {
+	fs.mkdirSync(path.dirname(configPath), { recursive: true });
+	fs.writeFileSync(configPath, `${JSON.stringify(config, null, "\t")}\n`, "utf-8");
+}
+
+export function updateConfig(updater: (config: ExtensionConfig) => ExtensionConfig): ExtensionConfig {
+	const configPath = getConfigPath();
+	const next = updater(readConfigForUpdate(configPath));
+	saveConfig(next, configPath);
+	return next;
+}
+
 export function loadConfig(): ExtensionConfig {
-	const configPath = path.join(getAgentDir(), "extensions", "subagent", "config.json");
+	const configPath = getConfigPath();
 	try {
-		if (fs.existsSync(configPath)) {
-			return JSON.parse(fs.readFileSync(configPath, "utf-8")) as ExtensionConfig;
-		}
+		return readConfigForUpdate(configPath);
 	} catch (error) {
 		console.error(`Failed to load subagent config from '${configPath}':`, error);
 	}

package/src/extension/doctor.ts

@@ -39,6 +39,7 @@ interface DoctorReportInput {
 	sessionError?: string;
 	expandTilde?: (value: string) => string;
 	paths?: DoctorPaths;
+	companionPackageLines?: string[];
 	deps?: Partial<DoctorDeps>;
 }
 
@@ -215,6 +216,7 @@ export function buildDoctorReport(input: DoctorReportInput): string {
 			orchestratorTarget: input.orchestratorTarget,
 			cwd: input.cwd,
 		}), input.context).join("\n")).split("\n"),
+		...(input.companionPackageLines?.length ? ["", ...input.companionPackageLines] : []),
 	];
 	return lines.join("\n");
 }

package/src/extension/fanout-child.ts

@@ -31,6 +31,7 @@ function createChildSafeState(): SubagentState {
 		baseCwd: "",
 		currentSessionId: null,
 		subagentInProgress: false,
+		subagentSpawns: { sessionId: null, count: 0 },
 		asyncJobs: new Map(),
 		foregroundRuns: new Map(),
 		foregroundControls: new Map(),

package/src/extension/index.ts

@@ -36,6 +36,14 @@ import registerSubagentNotify, { type SubagentNotifyDetails } from "../runs/back
 import { SUBAGENT_CHILD_ENV, SUBAGENT_PARENT_SESSION_ENV } from "../runs/shared/pi-args.ts";
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
 import { loadConfig } from "./config.ts";
+import {
+	buildCompanionDoctorLines,
+	buildCompanionListLines,
+	collectCompanionStatuses,
+	handleCompanionCommand,
+	maybeSendCompanionStartupMessage,
+	resolveCompanionOrchestratorTarget,
+} from "./companion-suggestions.ts";
 import {
 	type Details,
 	type SubagentState,
@@ -43,6 +51,7 @@ import {
 	DEFAULT_ARTIFACT_CONFIG,
 	RESULTS_DIR,
 	SLASH_RESULT_TYPE,
+	SLASH_TEXT_RESULT_TYPE,
 	SUBAGENT_ASYNC_COMPLETE_EVENT,
 	SUBAGENT_ASYNC_STARTED_EVENT,
 	SUBAGENT_CONTROL_EVENT,
@@ -249,7 +258,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	ensureAccessibleDir(ASYNC_DIR);
 	cleanupOldChainDirs();
 
-	const config = loadConfig();
+	let config = loadConfig();
 	const asyncByDefault = config.asyncByDefault === true;
 	const tempArtifactsDir = getArtifactsDir(null);
 	cleanupAllArtifactDirs(DEFAULT_ARTIFACT_CONFIG.cleanupDays);
@@ -258,6 +267,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		baseCwd: "",
 		currentSessionId: null,
 		subagentInProgress: false,
+		subagentSpawns: { sessionId: null, count: 0 },
 		asyncJobs: new Map(),
 		foregroundRuns: new Map(),
 		foregroundControls: new Map(),
@@ -269,6 +279,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		completionSeen: new Map(),
 		watcher: null,
 		watcherRestartTimer: null,
+		companionSuggestionStartupShown: false,
+		companionSuggestionListShown: false,
 		resultFileCoalescer: {
 			schedule: () => false,
 			clear: () => {},
@@ -294,12 +306,16 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	};
 	globalStore[runtimeCleanupStoreKey] = runtimeCleanup;
 
-	const { ensurePoller, handleStarted, handleComplete, resetJobs } = createAsyncJobTracker(pi, state, ASYNC_DIR);
+	const { ensurePoller, handleStarted, handleComplete, resetJobs, restoreActiveJobs } = createAsyncJobTracker(pi, state, ASYNC_DIR);
 	const executor = createSubagentExecutor({
 		pi,
 		state,
 		config,
 		asyncByDefault,
+		companionSuggestionLines: ({ surface, cwd, context, orchestratorTarget }) => {
+			const statuses = collectCompanionStatuses({ pi, config, cwd, context, orchestratorTarget });
+			return surface === "doctor" ? buildCompanionDoctorLines(statuses) : buildCompanionListLines(statuses);
+		},
 		tempArtifactsDir,
 		getSubagentSessionRoot,
 		expandTilde,
@@ -312,6 +328,16 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		return createSlashResultComponent(details, options, theme);
 	});
 
+	pi.registerMessageRenderer<undefined>(SLASH_TEXT_RESULT_TYPE, (message, _options, _theme) => {
+		const content = typeof message.content === "string"
+			? message.content
+			: message.content
+				.filter((entry) => entry.type === "text")
+				.map((entry) => entry.text)
+				.join("\n");
+		return new Text(content, 0, 0);
+	});
+
 	pi.registerMessageRenderer<SubagentNotifyDetails>("subagent-notify", (message, options, theme) => {
 		const content = typeof message.content === "string" ? message.content : "";
 		const details = (message.details as SubagentNotifyDetails | undefined) ?? parseSubagentNotifyContent(content);
@@ -407,6 +433,28 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		}, 0);
 	}
 
+	pi.registerCommand("subagents-companions", {
+		description: "Show or hide pi-subagents companion package recommendations",
+		handler: async (args, ctx) => {
+			try {
+				const statuses = collectCompanionStatuses({
+					pi,
+					config,
+					cwd: ctx.cwd,
+					orchestratorTarget: resolveCompanionOrchestratorTarget(pi, ctx),
+				});
+				const result = handleCompanionCommand(args, ctx, statuses);
+				if (result.updatedConfig) config = result.updatedConfig;
+				pi.sendMessage({ content: result.text, display: true });
+				if (result.error && ctx.hasUI) ctx.ui.notify(result.text, "error");
+			} catch (error) {
+				const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+				pi.sendMessage({ content: `Failed to update companion suggestions: ${message}`, display: true });
+				if (ctx.hasUI) ctx.ui.notify(`Failed to update companion suggestions: ${message}`, "error");
+			}
+		},
+	});
+
 	const tool: ToolDefinition<typeof SubagentParams, Details> = {
 		name: "subagent",
 		label: "Subagent",
@@ -418,6 +466,7 @@ EXECUTION (use exactly ONE mode):
 • 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):
@@ -460,7 +509,7 @@ DIAGNOSTICS:
 			}
 			const isParallel = (args.tasks?.length ?? 0) > 0;
 			const parallelCount = effectiveParallelTaskCount(args.tasks as Array<{ count?: unknown }> | undefined);
-			const asyncLabel = args.async === true && args.clarify !== true && !isParallel ? theme.fg("warning", " [async]") : "";
+			const asyncLabel = args.async === true && args.clarify !== true ? theme.fg("warning", " [async]") : "";
 			if (args.chain?.length)
 				return new Text(
 					`${theme.fg("toolTitle", theme.bold("subagent "))}chain (${args.chain.length})${asyncLabel}`,
@@ -469,7 +518,7 @@ DIAGNOSTICS:
 				);
 			if (isParallel)
 				return new Text(
-					`${theme.fg("toolTitle", theme.bold("subagent "))}parallel (${parallelCount})`,
+					`${theme.fg("toolTitle", theme.bold("subagent "))}parallel (${parallelCount})${asyncLabel}`,
 					0,
 					0,
 				);
@@ -553,6 +602,7 @@ DIAGNOSTICS:
 	const resetSessionState = (ctx: ExtensionContext) => {
 		state.baseCwd = ctx.cwd;
 		state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
+		state.subagentSpawns = { sessionId: state.currentSessionId, count: 0 };
 		// Set PI_SUBAGENT_PARENT_SESSION for permission-system forwarding.
 		// Only set in the root session (the interactive UI session), not in
 		// child subagent processes — children inherit the parent's value
@@ -565,15 +615,30 @@ DIAGNOSTICS:
 			}
 		}
 		state.lastUiContext = ctx;
+		state.companionSuggestionStartupShown = false;
+		state.companionSuggestionListShown = false;
 		cleanupSessionArtifacts(ctx);
 		clearPendingForegroundControlNotices(state);
 		resetJobs(ctx);
+		restoreActiveJobs(ctx);
 		restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
 		primeExistingResults();
 	};
 
 	pi.on("session_start", (_event, ctx) => {
 		resetSessionState(ctx);
+		maybeSendCompanionStartupMessage({
+			pi,
+			ctx,
+			state,
+			statuses: collectCompanionStatuses({
+				pi,
+				config,
+				cwd: ctx.cwd,
+				orchestratorTarget: resolveCompanionOrchestratorTarget(pi, ctx),
+				fast: true,
+			}),
+		});
 	});
 
 	pi.on("session_shutdown", () => {

package/src/extension/schemas.ts

@@ -235,8 +235,8 @@ const SubagentParamsSchema = Type.Object({
 	})),
 	chainDir: Type.Optional(Type.String({ description: "Persistent chain artifact directory; defaults to user-scoped temp storage." })),
 	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
-	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Foreground timeout ms; alias of maxRuntimeMs." })),
-	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias of timeoutMs for foreground timeout." })),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Optional run-level timeout in ms for foreground and async/background runs. Alias of maxRuntimeMs." })),
+	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias of timeoutMs for optional run-level timeout in foreground and async/background runs." })),
 	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),
 	cwd: Type.Optional(Type.String()),
 	artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: true)" })),

package/src/intercom/intercom-bridge.ts

@@ -199,6 +199,23 @@ function getGlobalNpmRoot(): string | 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 = [
@@ -235,7 +252,14 @@ function configuredPiIntercomPackageDir(input: ResolveIntercomBridgeInput, agent
 function resolveIntercomExtensionDir(input: ResolveIntercomBridgeInput, agentDir: string): string {
 	const legacyDir = path.resolve(input.extensionDir ?? envIntercomExtensionDir() ?? defaultIntercomExtensionDir(agentDir));
 	if (fs.existsSync(legacyDir)) return legacyDir;
-	return configuredPiIntercomPackageDir(input, agentDir) ?? 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 {