pi-crew 0.1.17 → 0.1.19

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.1.19
+
+- Added Claude-style `Agent`, `get_subagent_result`, and `steer_subagent` tools backed by pi-crew's durable worker runtime, plus conflict-safe `crew_agent`, `crew_agent_result`, and `crew_agent_steer` aliases.
+- Added a durable subagent manager with background queueing, completion notifications, result joins, session-bound cleanup, and direct single-agent runs via `team run agent=...`.
+- Disabled risky auto-opening of the right sidebar by default, added foreground completion notifications, and reduced duplicate widget/sidebar UI.
+- Added progress coalescing and workflow concurrency helpers to keep foreground sessions responsive during busy worker output.
+- Fixed live-session runs being classified as scaffold when workers are enabled and hardened session switch/shutdown cleanup for foreground child processes.
+
+## 0.1.18
+
+- Added a built-in `parallel-research` team/workflow for map-reduce style source audits with dynamic `Source/pi-*` fanout and parallel explorer shards.
+- Made the live right sidebar the default foreground UI: active foreground runs auto-open a top-right live sidebar when the terminal is wide enough.
+- Added live sidebar sections for active agents, waiting tasks, completed agents, task graph, model, tool, and token/usage details.
+- Stopped materializing queued dependency tasks as child-process agents; status now separates active agents, waiting tasks, and completed agents.
+- Added workflow-aware default concurrency so research/parallel-research can use ready parallel work instead of always running one worker.
+- Dropped user/system prompt messages from child event persistence to avoid prompt/context leakage in agent event logs.
+- Tightened child event compaction with separate assistant/tool input/tool result caps and improved powerbar active/waiting/model/token summaries.
+
 ## 0.1.17
 
 - Fixed terminal/completed workers being incorrectly escalated as stale heartbeat blockers after all tasks completed.

package/README.md

@@ -52,6 +52,7 @@ Current highlights:
 - run-level and task-level mailbox files with validation/repair support
 - `/team-manager` interactive helper
 - `/team-dashboard` custom TUI overlay with progress preview, action shortcuts, and reload
+- `parallel-research` team/workflow for dynamic `Source/pi-*` fanout and parallel shard exploration
 - package polish: `schema.json`, TypeScript semantic check, strip-types import smoke, cross-platform CI workflow, dry-run package verification
 
 ## Install
@@ -171,7 +172,10 @@ Supported config:
     "widgetMaxLines": 8,
     "powerbar": true,
     "dashboardPlacement": "right",
-    "dashboardWidth": 52,
+    "dashboardWidth": 56,
+    "dashboardLiveRefreshMs": 1000,
+    "autoOpenDashboard": false,
+    "autoOpenDashboardForForegroundRuns": true,
     "showModel": true,
     "showTokens": true,
     "showTools": true
@@ -186,7 +190,9 @@ Safety notes:
 UI notes:
 
 - `widgetPlacement`/`widgetMaxLines` keep the persistent active-run widget compact.
-- `dashboardPlacement: "right"` opens `/team-dashboard` as a right-side overlay panel instead of a centered modal.
+- `dashboardPlacement: "right"` is the default for `/team-dashboard`; automatic overlay opening is opt-in because Pi custom overlays can be modal/focus-capturing in some terminals.
+- `autoOpenDashboard`/`autoOpenDashboardForForegroundRuns` control whether the live sidebar opens automatically.
+- `dashboardLiveRefreshMs` controls the live sidebar refresh cadence.
 - `showModel`, `showTokens`, and `showTools` show worker model attempts, token usage, and tool activity in dashboard agent rows.
 
 Show config:

package/docs/usage.md

@@ -34,7 +34,10 @@ Supported fields:
     "widgetMaxLines": 8,
     "powerbar": true,
     "dashboardPlacement": "right",
-    "dashboardWidth": 52,
+    "dashboardWidth": 56,
+    "dashboardLiveRefreshMs": 1000,
+    "autoOpenDashboard": false,
+    "autoOpenDashboardForForegroundRuns": true,
     "showModel": true,
     "showTokens": true,
     "showTools": true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/schema.json

@@ -87,9 +87,12 @@
         "widgetPlacement": { "type": "string", "enum": ["aboveEditor", "belowEditor"] },
         "widgetMaxLines": { "type": "integer", "minimum": 1, "maximum": 50 },
         "powerbar": { "type": "boolean" },
-        "dashboardPlacement": { "type": "string", "enum": ["center", "right"], "description": "Place /team-dashboard as a centered overlay or right-side panel." },
-        "dashboardWidth": { "type": "integer", "minimum": 32, "maximum": 120 },
-        "showModel": { "type": "boolean", "description": "Show worker model attempts in dashboard agent rows." },
+        "dashboardPlacement": { "type": "string", "enum": ["center", "right"], "default": "right", "description": "Place /team-dashboard as a centered overlay or right-side panel." },
+        "dashboardWidth": { "type": "integer", "minimum": 32, "maximum": 120, "default": 56 },
+        "dashboardLiveRefreshMs": { "type": "integer", "minimum": 250, "maximum": 60000, "default": 1000 },
+        "autoOpenDashboard": { "type": "boolean", "default": false, "description": "Opt in to automatically opening the live right sidebar for foreground runs when UI is available. Disabled by default because Pi overlays are modal in some terminals." },
+        "autoOpenDashboardForForegroundRuns": { "type": "boolean", "default": true },
+        "showModel": { "type": "boolean", "default": true, "description": "Show worker model attempts in dashboard agent rows." },
         "showTokens": { "type": "boolean", "description": "Show token usage in dashboard agent rows." },
         "showTools": { "type": "boolean", "description": "Show tool activity in dashboard agent rows." }
       }

package/src/config/config.ts

@@ -53,6 +53,9 @@ export interface CrewUiConfig {
 	powerbar?: boolean;
 	dashboardPlacement?: "center" | "right";
 	dashboardWidth?: number;
+	dashboardLiveRefreshMs?: number;
+	autoOpenDashboard?: boolean;
+	autoOpenDashboardForForegroundRuns?: boolean;
 	showModel?: boolean;
 	showTokens?: boolean;
 	showTools?: boolean;
@@ -316,6 +319,9 @@ function parseUiConfig(value: unknown): CrewUiConfig | undefined {
 		powerbar: typeof obj.powerbar === "boolean" ? obj.powerbar : undefined,
 		dashboardPlacement: obj.dashboardPlacement === "center" || obj.dashboardPlacement === "right" ? obj.dashboardPlacement : undefined,
 		dashboardWidth: parsePositiveInteger(obj.dashboardWidth, 120),
+		dashboardLiveRefreshMs: parsePositiveInteger(obj.dashboardLiveRefreshMs, 60_000),
+		autoOpenDashboard: typeof obj.autoOpenDashboard === "boolean" ? obj.autoOpenDashboard : undefined,
+		autoOpenDashboardForForegroundRuns: typeof obj.autoOpenDashboardForForegroundRuns === "boolean" ? obj.autoOpenDashboardForForegroundRuns : undefined,
 		showModel: typeof obj.showModel === "boolean" ? obj.showModel : undefined,
 		showTokens: typeof obj.showTokens === "boolean" ? obj.showTokens : undefined,
 		showTools: typeof obj.showTools === "boolean" ? obj.showTools : undefined,

package/src/extension/register.ts

@@ -1,4 +1,6 @@
+import * as fs from "node:fs";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, ToolDefinition } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
 import { loadConfig } from "../config/config.ts";
 import { registerAutonomousPolicy } from "./autonomous-policy.ts";
 import { TeamToolParams, type TeamToolParamsValue } from "../schema/team-tool-schema.ts";
@@ -9,6 +11,7 @@ import { handleTeamManagerCommand } from "./team-manager-command.ts";
 import { handleTeamTool, type TeamToolDetails } from "./team-tool.ts";
 import { listRecentRuns } from "./run-index.ts";
 import { RunDashboard, type RunDashboardSelection } from "../ui/run-dashboard.ts";
+import { LiveRunSidebar } from "../ui/live-run-sidebar.ts";
 import { registerPiCrewRpc, type PiCrewRpcHandle } from "./cross-extension-rpc.ts";
 import { stopCrewWidget, updateCrewWidget, type CrewWidgetState } from "../ui/crew-widget.ts";
 import { clearPiCrewPowerbar, registerPiCrewPowerbarSegments, updatePiCrewPowerbar } from "../ui/powerbar-publisher.ts";
@@ -16,6 +19,7 @@ import { DurableTextViewer, DurableTranscriptViewer } from "../ui/transcript-vie
 import { loadRunManifestById } from "../state/state-store.ts";
 import { readCrewAgents } from "../runtime/crew-agent-records.ts";
 import { terminateActiveChildPiProcesses } from "../runtime/child-pi.ts";
+import { SubagentManager, type SubagentRecord, type SubagentSpawnOptions } from "../runtime/subagent-manager.ts";
 
 function parseRunArgs(args: string): TeamToolParamsValue {
 	const tokens = args.match(/"[^"]*"|'[^']*'|\S+/g)?.map((token) => token.replace(/^['"]|['"]$/g, "")) ?? [];
@@ -99,6 +103,55 @@ function setNestedConfig(config: Record<string, unknown>, key: string, value: un
 	target[parts[parts.length - 1]!] = value;
 }
 
+function sendFollowUp(pi: ExtensionAPI, content: string): void {
+	const sender = (pi as unknown as { sendMessage?: (message: unknown, options?: unknown) => void }).sendMessage;
+	if (typeof sender !== "function") return;
+	sender.call(pi, { customType: "pi-crew-subagent-notification", content, display: true }, { deliverAs: "followUp", triggerTurn: true });
+}
+
+function formatSubagentRecord(record: SubagentRecord): string {
+	const duration = record.completedAt ? `${Math.round((record.completedAt - record.startedAt) / 1000)}s` : "running";
+	return [
+		`Agent: ${record.id}`,
+		`Type: ${record.type}`,
+		`Status: ${record.status}`,
+		record.runId ? `Run: ${record.runId}` : undefined,
+		`Description: ${record.description}`,
+		record.model ? `Model: ${record.model}` : undefined,
+		`Duration: ${duration}`,
+		record.error ? `Error: ${record.error}` : undefined,
+	].filter((line): line is string => Boolean(line)).join("\n");
+}
+
+function readSubagentRunResult(ctx: ExtensionContext | ExtensionCommandContext, record: SubagentRecord): string | undefined {
+	if (!record.runId) return record.result;
+	const loaded = loadRunManifestById(ctx.cwd, record.runId);
+	const task = loaded?.tasks.find((item) => item.resultArtifact) ?? loaded?.tasks[0];
+	const path = task?.resultArtifact?.path;
+	if (!path) return undefined;
+	try {
+		return fs.readFileSync(path, "utf-8").trim();
+	} catch {
+		return undefined;
+	}
+}
+
+function subagentToolResult(text: string, details: Record<string, unknown> = {}, isError = false) {
+	return { content: [{ type: "text" as const, text }], details, isError };
+}
+
+export function __test__subagentSpawnParams(params: Record<string, unknown>, ctx: Pick<ExtensionContext, "cwd">): SubagentSpawnOptions {
+	return {
+		cwd: ctx.cwd,
+		type: typeof params.subagent_type === "string" && params.subagent_type.trim() ? params.subagent_type.trim() : "executor",
+		description: typeof params.description === "string" && params.description.trim() ? params.description.trim() : "pi-crew subagent",
+		prompt: typeof params.prompt === "string" ? params.prompt : "",
+		background: params.run_in_background === true,
+		model: typeof params.model === "string" && params.model.trim() ? params.model.trim() : undefined,
+		maxTurns: typeof params.max_turns === "number" && Number.isFinite(params.max_turns) ? params.max_turns : undefined,
+	};
+}
+
 export function registerPiTeams(pi: ExtensionAPI): void {
 	const globalStore = globalThis as Record<string, unknown>;
 	const runtimeCleanupStoreKey = "__piCrewRuntimeCleanup";
@@ -111,8 +164,51 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	let rpcHandle: PiCrewRpcHandle | undefined;
 	let cleanedUp = false;
 	const widgetState: CrewWidgetState = { frame: 0 };
+	const subagentManager = new SubagentManager(4, (record) => {
+		if (!record.background || record.resultConsumed) return;
+		if (record.status === "completed" || record.status === "failed" || record.status === "cancelled" || record.status === "error") {
+			sendFollowUp(pi, [`pi-crew subagent ${record.id} ${record.status}.`, record.runId ? `Run: ${record.runId}` : undefined, `Use get_subagent_result with agent_id=${record.id} for output.`].filter((line): line is string => Boolean(line)).join("\n"));
+		}
+	});
 	const foregroundControllers = new Set<AbortController>();
-	const startForegroundRun = (ctx: ExtensionContext, runner: (signal?: AbortSignal) => Promise<void>): void => {
+	let liveSidebarRunId: string | undefined;
+	let liveSidebarTimer: ReturnType<typeof setInterval> | undefined;
+	const requestRender = (ctx: ExtensionContext): void => (ctx.ui as { requestRender?: () => void }).requestRender?.();
+	const stopSessionBoundSubagents = (): void => {
+		for (const controller of foregroundControllers) controller.abort();
+		foregroundControllers.clear();
+		subagentManager.abortAll();
+		terminateActiveChildPiProcesses();
+		if (liveSidebarTimer) clearInterval(liveSidebarTimer);
+		liveSidebarTimer = undefined;
+		liveSidebarRunId = undefined;
+		if (currentCtx) stopCrewWidget(currentCtx, widgetState, loadConfig(currentCtx.cwd).config.ui);
+		clearPiCrewPowerbar(pi.events);
+	};
+	const openLiveSidebar = (ctx: ExtensionContext, runId: string): void => {
+		const uiConfig = loadConfig(ctx.cwd).config.ui;
+		const autoOpen = uiConfig?.autoOpenDashboard === true;
+		const foregroundAutoOpen = uiConfig?.autoOpenDashboardForForegroundRuns !== false;
+		if (!ctx.hasUI || !autoOpen || !foregroundAutoOpen || (uiConfig?.dashboardPlacement ?? "right") !== "right") return;
+		if (liveSidebarRunId === runId) return;
+		if (liveSidebarTimer) clearInterval(liveSidebarTimer);
+		liveSidebarRunId = runId;
+		ctx.ui.setWidget("pi-crew", undefined, { placement: uiConfig?.widgetPlacement ?? "aboveEditor" });
+		ctx.ui.setWidget("pi-crew-active", undefined, { placement: uiConfig?.widgetPlacement ?? "aboveEditor" });
+		const width = Math.min(90, Math.max(40, uiConfig?.dashboardWidth ?? 56));
+		liveSidebarTimer = setInterval(() => requestRender(ctx), uiConfig?.dashboardLiveRefreshMs ?? 1000);
+		liveSidebarTimer.unref?.();
+		void ctx.ui.custom<undefined>((_tui, theme, _keybindings, done) => new LiveRunSidebar({ cwd: ctx.cwd, runId, done, theme, config: uiConfig }), {
+			overlay: true,
+			overlayOptions: { width, minWidth: 40, maxHeight: "100%", anchor: "top-right", offsetX: 0, offsetY: 0, margin: { top: 0, right: 0, bottom: 0, left: 0 }, visible: (termWidth: number) => termWidth >= 100 },
+		}).finally(() => {
+			if (liveSidebarRunId === runId) liveSidebarRunId = undefined;
+			if (liveSidebarTimer) clearInterval(liveSidebarTimer);
+			liveSidebarTimer = undefined;
+			updateCrewWidget(ctx, widgetState, loadConfig(ctx.cwd).config.ui);
+		});
+	};
+	const startForegroundRun = (ctx: ExtensionContext, runner: (signal?: AbortSignal) => Promise<void>, runId?: string): void => {
 		const controller = new AbortController();
 		foregroundControllers.add(controller);
 		setImmediate(() => {
@@ -123,6 +219,12 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 				})
 				.finally(() => {
 					foregroundControllers.delete(controller);
+					if (runId) {
+						const loaded = loadRunManifestById(ctx.cwd, runId);
+						const status = loaded?.manifest.status ?? "finished";
+						const level = status === "failed" || status === "blocked" ? "error" : status === "cancelled" ? "warning" : "info";
+						ctx.ui.notify(`pi-crew run ${runId} ${status}. Use /team-summary ${runId} or /team-status ${runId}.`, level as "info" | "warning" | "error");
+					}
 					if (currentCtx) {
 						const config = loadConfig(currentCtx.cwd).config.ui;
 						updateCrewWidget(currentCtx, widgetState, config);
@@ -136,9 +238,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	const cleanupRuntime = (): void => {
 		if (cleanedUp) return;
 		cleanedUp = true;
-		for (const controller of foregroundControllers) controller.abort();
-		foregroundControllers.clear();
-		terminateActiveChildPiProcesses();
+		stopSessionBoundSubagents();
 		stopAsyncRunNotifier(notifierState);
 		stopCrewWidget(currentCtx, widgetState, currentCtx ? loadConfig(currentCtx.cwd).config.ui : undefined);
 		clearPiCrewPowerbar(pi.events);
@@ -152,6 +252,8 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	pi.on("session_start", (_event, ctx) => {
 		cleanedUp = false;
 		currentCtx = ctx;
+		if (widgetState.interval) clearInterval(widgetState.interval);
+		widgetState.interval = undefined;
 		notifyActiveRuns(ctx);
 		const loadedConfig = loadConfig(ctx.cwd);
 		registerPiCrewPowerbarSegments(pi.events, loadedConfig.config.ui);
@@ -161,11 +263,19 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		widgetState.interval = setInterval(() => {
 			if (!currentCtx) return;
 			const config = loadConfig(currentCtx.cwd).config.ui;
-			updateCrewWidget(currentCtx, widgetState, config);
+			if (liveSidebarRunId) {
+				currentCtx.ui.setWidget("pi-crew", undefined, { placement: config?.widgetPlacement ?? "aboveEditor" });
+				currentCtx.ui.setWidget("pi-crew-active", undefined, { placement: config?.widgetPlacement ?? "aboveEditor" });
+			} else {
+				updateCrewWidget(currentCtx, widgetState, config);
+			}
 			updatePiCrewPowerbar(pi.events, currentCtx.cwd, config);
 		}, 1000);
 		widgetState.interval.unref?.();
 	});
+	pi.on("session_before_switch", () => {
+		stopSessionBoundSubagents();
+	});
 	pi.on("session_shutdown", () => {
 		cleanupRuntime();
 	});
@@ -182,7 +292,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 			const abort = (): void => controller.abort();
 			signal?.addEventListener("abort", abort, { once: true });
 			try {
-				const output = await handleTeamTool(params as TeamToolParamsValue, { ...ctx, signal: controller.signal, startForegroundRun: (runner) => startForegroundRun(ctx, runner) });
+				const output = await handleTeamTool(params as TeamToolParamsValue, { ...ctx, signal: controller.signal, startForegroundRun: (runner, runId) => startForegroundRun(ctx, runner, runId), onRunStarted: (runId) => openLiveSidebar(ctx, runId) });
 				const config = loadConfig(ctx.cwd).config.ui;
 				updateCrewWidget(ctx, widgetState, config);
 				updatePiCrewPowerbar(pi.events, ctx.cwd, config);
@@ -196,6 +306,106 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 
 	pi.registerTool(tool);
 
+	const agentTool: ToolDefinition = {
+		name: "Agent",
+		label: "Agent",
+		description: "Launch a real pi-crew subagent. Uses pi-crew's durable child-process runtime by default; set run_in_background=true for parallel/background work, then use get_subagent_result.",
+		promptSnippet: "Use Agent to delegate focused work to a real pi-crew subagent. Use run_in_background=true for parallel work and get_subagent_result to join results.",
+		promptGuidelines: [
+			"Use Agent for independent exploration, review, verification, or implementation subtasks instead of doing all work in the parent turn.",
+			"For parallel work, launch multiple Agent calls with run_in_background=true, then call get_subagent_result for each result.",
+			"Available pi-crew subagent types include explorer, planner, analyst, executor, reviewer, verifier, writer, security-reviewer, and test-engineer.",
+		],
+		parameters: Type.Object({
+			prompt: Type.String({ description: "The task for the subagent to perform." }),
+			description: Type.String({ description: "Short 3-5 word task description." }),
+			subagent_type: Type.String({ description: "pi-crew agent name, e.g. explorer, planner, executor, reviewer, verifier, writer, security-reviewer, test-engineer." }),
+			model: Type.Optional(Type.String({ description: "Optional model override. If omitted, pi-crew uses Pi-configured model fallback." })),
+			max_turns: Type.Optional(Type.Number({ description: "Reserved for live-session subagents; child-process runtime may ignore this." })),
+			run_in_background: Type.Optional(Type.Boolean({ description: "Run in background and return an agent ID immediately." })),
+		}) as never,
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			const options = __test__subagentSpawnParams(params as Record<string, unknown>, ctx);
+			if (!options.prompt.trim()) return subagentToolResult("Agent requires prompt.", {}, true);
+			const runner = async (spawnOptions: SubagentSpawnOptions, childSignal?: AbortSignal) => handleTeamTool({
+				action: "run",
+				agent: spawnOptions.type,
+				goal: spawnOptions.prompt,
+				model: spawnOptions.model,
+				async: false,
+			}, spawnOptions.background ? { ...ctx, signal: childSignal, startForegroundRun: (run, runId) => startForegroundRun(ctx, run, runId), onRunStarted: (runId) => openLiveSidebar(ctx, runId) } : { ...ctx, signal: childSignal });
+			const record = subagentManager.spawn(options, runner, options.background ? undefined : signal);
+			if (options.background || record.status === "queued") {
+				return subagentToolResult([`Agent ${record.status === "queued" ? "queued" : "started"}.`, `Agent ID: ${record.id}`, `Type: ${record.type}`, `Description: ${record.description}`, "Use get_subagent_result to retrieve output. Do not duplicate this agent's work."].join("\n"), { agentId: record.id, status: record.status });
+			}
+			await record.promise;
+			const output = readSubagentRunResult(ctx, record) ?? record.result ?? "No output.";
+			return subagentToolResult([`Agent ${record.id} ${record.status}.`, "", output].join("\n"), { agentId: record.id, runId: record.runId, status: record.status }, record.status === "failed" || record.status === "error");
+		},
+	};
+
+	const getSubagentResultTool: ToolDefinition = {
+		name: "get_subagent_result",
+		label: "Get Agent Result",
+		description: "Check status and retrieve results from a pi-crew background subagent.",
+		parameters: Type.Object({
+			agent_id: Type.String({ description: "Agent ID returned by Agent." }),
+			wait: Type.Optional(Type.Boolean({ description: "Wait for completion before returning." })),
+			verbose: Type.Optional(Type.Boolean({ description: "Include status metadata before output." })),
+		}) as never,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const p = params as { agent_id?: string; wait?: boolean; verbose?: boolean };
+			if (!p.agent_id) return subagentToolResult("get_subagent_result requires agent_id.", {}, true);
+			const record = subagentManager.getRecord(p.agent_id);
+			if (!record) return subagentToolResult(`Agent not found: ${p.agent_id}`, {}, true);
+			let current = record;
+			if (p.wait && (current.status === "running" || current.status === "queued")) {
+				current.resultConsumed = true;
+				current = await subagentManager.waitForRecord(current.id) ?? current;
+			}
+			const output = readSubagentRunResult(ctx, current);
+			if (current.status !== "running" && current.status !== "queued") current.resultConsumed = true;
+			const text = [p.verbose ? formatSubagentRecord(current) : undefined, output ? `${p.verbose ? "\n" : ""}${output}` : current.status === "running" || current.status === "queued" ? "Agent is still running. Use wait=true or check again later." : current.error ?? "No output."].filter((line): line is string => Boolean(line)).join("\n");
+			return subagentToolResult(text, { agentId: current.id, runId: current.runId, status: current.status }, current.status === "failed" || current.status === "error");
+		},
+	};
+
+	const steerSubagentTool: ToolDefinition = {
+		name: "steer_subagent",
+		label: "Steer Agent",
+		description: "Send a steering note to a running pi-crew subagent. Live-session steering is planned; child-process runs expose durable status and can be cancelled if needed.",
+		parameters: Type.Object({ agent_id: Type.String(), message: Type.String() }) as never,
+		async execute(_id, params) {
+			const p = params as { agent_id?: string; message?: string };
+			const record = p.agent_id ? subagentManager.getRecord(p.agent_id) : undefined;
+			if (!record) return subagentToolResult(`Agent not found: ${p.agent_id ?? ""}`, {}, true);
+			return subagentToolResult([`Steering request noted for ${record.id}.`, "Current default pi-crew backend is child-process, so mid-turn session.steer is not available yet.", record.runId ? `Use team cancel runId=${record.runId} if the agent must be interrupted.` : undefined].filter((line): line is string => Boolean(line)).join("\n"), { agentId: record.id, runId: record.runId, status: record.status });
+		},
+	};
+
+	const crewAgentTool: ToolDefinition = {
+		...agentTool,
+		name: "crew_agent",
+		label: "Crew Agent",
+		description: "Launch a real pi-crew subagent using a conflict-safe pi-crew-specific tool name.",
+		promptSnippet: "Use crew_agent when you need pi-crew subagents and another extension may own the generic Agent tool.",
+	};
+	const crewAgentResultTool: ToolDefinition = {
+		...getSubagentResultTool,
+		name: "crew_agent_result",
+		label: "Get Crew Agent Result",
+		description: "Check status and retrieve results from a pi-crew subagent using the conflict-safe tool name.",
+	};
+	const crewAgentSteerTool: ToolDefinition = {
+		...steerSubagentTool,
+		name: "crew_agent_steer",
+		label: "Steer Crew Agent",
+		description: "Send a steering note to a pi-crew subagent using the conflict-safe tool name.",
+	};
+	for (const extraTool of [agentTool, getSubagentResultTool, steerSubagentTool, crewAgentTool, crewAgentResultTool, crewAgentSteerTool]) {
+		pi.registerTool(extraTool);
+	}
+
 	pi.registerCommand("teams", {
 		description: "List pi-crew teams, workflows, and agents",
 		handler: async (_args: string, ctx: ExtensionCommandContext) => {
@@ -207,7 +417,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	pi.registerCommand("team-run", {
 		description: "Manually start a pi-crew run (agent may also use the team tool autonomously)",
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
-			const result = await handleTeamTool(parseRunArgs(args), { ...ctx, startForegroundRun: (runner) => startForegroundRun(ctx as ExtensionContext, runner) });
+			const result = await handleTeamTool(parseRunArgs(args), { ...ctx, startForegroundRun: (runner, runId) => startForegroundRun(ctx as ExtensionContext, runner, runId), onRunStarted: (runId) => openLiveSidebar(ctx as ExtensionContext, runId) });
 			await notifyCommandResult(ctx, commandText(result));
 		},
 	});

package/src/extension/team-recommendation.ts

@@ -12,8 +12,8 @@ export interface RecommendedSubtask {
 }
 
 export interface TeamRecommendation {
-	team: "default" | "implementation" | "review" | "fast-fix" | "research";
-	workflow: "default" | "implementation" | "review" | "fast-fix" | "research";
+	team: string;
+	workflow: string;
 	action: "plan" | "run";
 	async: boolean;
 	workspaceMode: "single" | "worktree";
@@ -23,7 +23,8 @@ export interface TeamRecommendation {
 }
 
 const REVIEW_TERMS = ["review", "audit", "security", "vulnerability", "diff", "pr", "pull request"];
-const RESEARCH_TERMS = ["research", "investigate", "compare", "analyze", "document", "docs", "explain", "architecture"];
+const RESEARCH_TERMS = ["research", "investigate", "compare", "analyze", "document", "docs", "explain", "architecture", "đọc sâu", "source", "projects"];
+const PARALLEL_RESEARCH_RE = /(?:đọc sâu|deep read|deep research|source audit|multiple projects|các project|pi-\*|source\/|@source)/i;
 const FAST_FIX_TERMS = ["quick fix", "fast-fix", "small bug", "typo", "one-line", "minor", "lint"];
 const IMPLEMENTATION_TERMS = ["implement", "refactor", "migrate", "feature", "tests", "test", "integration", "upgrade", "build", "create", "add"];
 const RISKY_TERMS = ["migration", "refactor", "large", "multiple", "parallel", "concurrent", "risky", "critical"];
@@ -122,6 +123,11 @@ export function recommendTeam(goal: string, config: PiTeamsAutonomousConfig = {}
 		workflow = "review";
 		confidence = "high";
 		reasons.push(`Review/audit terms detected: ${reviewMatches.join(", ") || "explicit review intent"}.`);
+	} else if (PARALLEL_RESEARCH_RE.test(goal) || (researchMatches.length >= 2 && (normalized.includes("multiple") || normalized.includes("source") || normalized.includes("project") || normalized.includes("pi-")))) {
+		team = "parallel-research";
+		workflow = "parallel-research";
+		confidence = "high";
+		reasons.push("Deep/multi-source research detected; use parallel shard exploration.");
 	} else if (intents.includes("research") || (researchMatches.length > 0 && implementationMatches.length === 0)) {
 		team = "research";
 		workflow = "research";

package/src/extension/team-tool.ts

@@ -5,6 +5,7 @@ import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { allAgents, discoverAgents } from "../agents/discover-agents.ts";
 import { allTeams, discoverTeams } from "../teams/discover-teams.ts";
 import { allWorkflows, discoverWorkflows } from "../workflows/discover-workflows.ts";
+import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
 import { effectiveAutonomousConfig, loadConfig, updateAutonomousConfig, updateConfig, type PiTeamsAutonomousConfig, type PiTeamsConfig } from "../config/config.ts";
 import { projectPiRoot, userPiRoot } from "../utils/paths.ts";
 import type { TeamToolParamsValue } from "../schema/team-tool-schema.ts";
@@ -44,6 +45,7 @@ import { readForegroundControlStatus, writeForegroundInterruptRequest } from "..
 import { listLiveAgents, resumeLiveAgent, steerLiveAgent, stopLiveAgent } from "../runtime/live-agent-manager.ts";
 import { appendLiveAgentControlRequest } from "../runtime/live-agent-control.ts";
 import { liveControlRealtimeMessage, publishLiveControlRealtime } from "../runtime/live-control-realtime.ts";
+import { formatTaskGraphLines, waitingReason } from "../runtime/task-display.ts";
 
 export interface TeamToolDetails {
 	action: string;
@@ -57,7 +59,8 @@ type TeamContext = Pick<ExtensionContext, "cwd"> & Partial<Pick<ExtensionContext
 	sessionManager?: { getBranch?: () => unknown[] };
 	events?: { emit?: (event: string, data: unknown) => void };
 	signal?: AbortSignal;
-	startForegroundRun?: (runner: (signal?: AbortSignal) => Promise<void>) => void;
+	startForegroundRun?: (runner: (signal?: AbortSignal) => Promise<void>, runId?: string) => void;
+	onRunStarted?: (runId: string) => void;
 };
 
 function result(text: string, details: TeamToolDetails, isError = false): PiTeamsToolResult {
@@ -168,6 +171,48 @@ function commandExists(command: string, args: string[]): { ok: boolean; detail:
 	return { ok: false, detail: output.error?.message ?? firstOutputLine(output.stdout, output.stderr) };
 }
 
+function sourcePiProjects(cwd: string): string[] {
+	const sourceDir = path.join(cwd, "Source");
+	try {
+		return fs.readdirSync(sourceDir, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory() && entry.name.startsWith("pi-"))
+			.map((entry) => `Source/${entry.name}`)
+			.sort();
+	} catch {
+		return [];
+	}
+}
+
+function chunkProjects(projects: string[], target = 4): string[][] {
+	const chunks = Array.from({ length: Math.min(Math.max(1, target), Math.max(1, projects.length)) }, () => [] as string[]);
+	projects.forEach((project, index) => chunks[index % chunks.length]!.push(project));
+	return chunks.filter((chunk) => chunk.length > 0);
+}
+
+function expandParallelResearchWorkflow(workflow: WorkflowConfig, cwd: string): WorkflowConfig {
+	if (workflow.name !== "parallel-research") return workflow;
+	const projects = sourcePiProjects(cwd);
+	if (projects.length === 0) return workflow;
+	const chunks = chunkProjects(projects, Math.min(6, Math.max(4, Math.ceil(projects.length / 4))));
+	const exploreSteps: WorkflowStep[] = chunks.map((paths, index) => ({
+		id: `explore-shard-${index + 1}`,
+		role: "explorer",
+		dependsOn: ["discover"],
+		parallelGroup: "explore",
+		reads: paths,
+		task: [`Explore this dynamic shard for: {goal}`, "", "Paths:", ...paths.map((item) => `- ${item}`), "", "Focus on purpose, architecture, runtime/UI patterns, package config, docs, and lessons for pi-crew."].join("\n"),
+	}));
+	return {
+		...workflow,
+		steps: [
+			{ id: "discover", role: "explorer", task: `Discover and validate ${projects.length} pi-* projects for: {goal}\n\nProjects:\n${projects.map((item) => `- ${item}`).join("\n")}` },
+			...exploreSteps,
+			{ id: "synthesize", role: "analyst", dependsOn: exploreSteps.map((step) => step.id), task: "Synthesize all dynamic shard findings. Identify common patterns, gaps, and concrete recommendations." },
+			{ id: "write", role: "writer", dependsOn: ["synthesize"], output: "research-summary.md", task: "Write a concise final summary with evidence, risks, and actionable next steps." },
+		],
+	};
+}
+
 function effectiveRunConfig(base: PiTeamsConfig, rawOverride: unknown): PiTeamsConfig {
 	const patch = configPatchFromConfig(rawOverride);
 	return {
@@ -255,12 +300,29 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 	const teams = allTeams(discoverTeams(ctx.cwd));
 	const workflows = allWorkflows(discoverWorkflows(ctx.cwd));
 	const agents = allAgents(discoverAgents(ctx.cwd));
+	const directAgent = params.agent ? agents.find((item) => item.name === params.agent) : undefined;
+	if (params.agent && !directAgent) return result(`Agent '${params.agent}' not found.`, { action: "run", status: "error" }, true);
 	const teamName = params.team ?? "default";
-	const team = teams.find((item) => item.name === teamName);
+	const team = directAgent ? {
+		name: `direct-${directAgent.name}`,
+		description: `Direct subagent run for ${directAgent.name}`,
+		source: "builtin" as const,
+		filePath: "<generated>",
+		roles: [{ name: params.role ?? "agent", agent: directAgent.name, description: directAgent.description }],
+		defaultWorkflow: "direct-agent",
+		workspaceMode: params.workspaceMode,
+	} : teams.find((item) => item.name === teamName);
 	if (!team) return result(`Team '${teamName}' not found.`, { action: "run", status: "error" }, true);
-	const workflowName = params.workflow ?? team.defaultWorkflow ?? "default";
-	const workflow = workflows.find((item) => item.name === workflowName);
-	if (!workflow) return result(`Workflow '${workflowName}' not found.`, { action: "run", status: "error" }, true);
+	const workflowName = directAgent ? "direct-agent" : params.workflow ?? team.defaultWorkflow ?? "default";
+	const baseWorkflow = directAgent ? {
+		name: "direct-agent",
+		description: `Direct task for ${directAgent.name}`,
+		source: "builtin" as const,
+		filePath: "<generated>",
+		steps: [{ id: "01_agent", role: params.role ?? "agent", task: "{goal}", model: params.model }],
+	} : workflows.find((item) => item.name === workflowName);
+	if (!baseWorkflow) return result(`Workflow '${workflowName}' not found.`, { action: "run", status: "error" }, true);
+	const workflow = directAgent ? baseWorkflow : expandParallelResearchWorkflow(baseWorkflow, ctx.cwd);
 
 	const validationErrors = validateWorkflowForTeam(workflow, team);
 	if (validationErrors.length > 0) {
@@ -306,12 +368,13 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 	}
 
 	const runtime = await resolveCrewRuntime(effectiveRunConfig(loadedConfig.config, params.config));
-	const executeWorkers = runtime.kind === "child-process";
+	const executeWorkers = runtime.kind !== "scaffold";
 	const executedConfig = effectiveRunConfig(loadedConfig.config, params.config);
 	if (executeWorkers && ctx.startForegroundRun) {
+		ctx.onRunStarted?.(updatedManifest.runId);
 		ctx.startForegroundRun(async (signal) => {
 			await executeTeamRun({ manifest: updatedManifest, tasks, team, workflow, agents, executeWorkers, limits: executedConfig.limits, runtime, runtimeConfig: executedConfig.runtime, parentContext: buildParentContext(ctx), parentModel: ctx.model, modelRegistry: ctx.modelRegistry, modelOverride: params.model, signal });
-		});
+		}, updatedManifest.runId);
 		const text = [
 			`Started foreground pi-crew run ${updatedManifest.runId}.`,
 			`Team: ${team.name}`,
@@ -368,6 +431,10 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 	const crewAgents = readCrewAgents(manifest).map((agent) => applyAttentionState(manifest, agent, controlConfig));
 	const artifactLines = manifest.artifacts.slice(-10).map((artifact) => `- ${artifact.kind}: ${artifact.path}${artifact.sizeBytes !== undefined ? ` (${artifact.sizeBytes} bytes)` : ""}`);
 	const totalUsage = aggregateUsage(tasks);
+	const activeAgents = crewAgents.filter((agent) => agent.status === "running");
+	const completedAgents = crewAgents.filter((agent) => agent.status !== "running");
+	const waitingTasks = tasks.filter((task) => task.status === "queued");
+	const agentLine = (agent: typeof crewAgents[number]): string => `- ${agent.id} [${agent.status}] ${agent.role} -> ${agent.agent} runtime=${agent.runtime}${agent.model ? ` model=${agent.model}` : ""}${agent.usage ? ` usage=${formatUsage(agent.usage)}` : ""}${agent.progress?.activityState === "needs_attention" ? " needs_attention" : ""}${formatActivityAge(agent) ? ` activity=${formatActivityAge(agent)}` : ""}${agent.progress?.currentTool ? ` tool=${agent.progress.currentTool}` : ""}${agent.toolUses ? ` tools=${agent.toolUses}` : ""}${!agent.usage && agent.progress?.tokens ? ` tokens=${agent.progress.tokens}` : ""}${agent.progress?.turns ? ` turns=${agent.progress.turns}` : ""}${agent.jsonEvents !== undefined ? ` jsonEvents=${agent.jsonEvents}` : ""}${agent.statusPath ? ` status=${agent.statusPath}` : ""}${agent.error ? ` error=${agent.error}` : ""}`;
 	const lines = [
 		`Run: ${manifest.runId}`,
 		`Team: ${manifest.team}`,
@@ -380,11 +447,17 @@ export function handleStatus(params: TeamToolParamsValue, ctx: TeamContext): PiT
 		`State: ${manifest.stateRoot}`,
 		`Artifacts: ${manifest.artifactsRoot}`,
 		...(asyncLivenessLine ? [asyncLivenessLine] : []),
+		"Task graph:",
+		...formatTaskGraphLines(tasks),
 		"Tasks:",
 		...(tasks.length ? tasks.map((task) => `- ${task.id} [${task.status}] ${task.role} -> ${task.agent}${task.taskPacket ? ` scope=${task.taskPacket.scope}` : ""}${task.verification ? ` green=${task.verification.observedGreenLevel}/${task.verification.requiredGreenLevel}` : ""}${task.modelAttempts?.length ? ` attempts=${task.modelAttempts.length}` : ""}${task.jsonEvents !== undefined ? ` jsonEvents=${task.jsonEvents}` : ""}${task.usage ? ` usage=${JSON.stringify(task.usage)}` : ""}${task.worktree ? ` worktree=${task.worktree.path}` : ""}${task.error ? ` error=${task.error}` : ""}`) : ["- (none)"]),
 		`Task counts: ${[...counts.entries()].map(([status, count]) => `${status}=${count}`).join(", ") || "none"}`,
-		"Agents:",
-		...(crewAgents.length ? crewAgents.map((agent) => `- ${agent.id} [${agent.status}] ${agent.role} -> ${agent.agent} runtime=${agent.runtime}${agent.model ? ` model=${agent.model}` : ""}${agent.usage ? ` usage=${formatUsage(agent.usage)}` : ""}${agent.progress?.activityState === "needs_attention" ? " needs_attention" : ""}${formatActivityAge(agent) ? ` activity=${formatActivityAge(agent)}` : ""}${agent.progress?.currentTool ? ` tool=${agent.progress.currentTool}` : ""}${agent.toolUses ? ` tools=${agent.toolUses}` : ""}${!agent.usage && agent.progress?.tokens ? ` tokens=${agent.progress.tokens}` : ""}${agent.progress?.turns ? ` turns=${agent.progress.turns}` : ""}${agent.jsonEvents !== undefined ? ` jsonEvents=${agent.jsonEvents}` : ""}${agent.statusPath ? ` status=${agent.statusPath}` : ""}${agent.error ? ` error=${agent.error}` : ""}`) : ["- (none)"]),
+		"Active agents:",
+		...(activeAgents.length ? activeAgents.map(agentLine) : ["- (none)"]),
+		"Waiting tasks:",
+		...(waitingTasks.length ? waitingTasks.map((task) => `- ${task.id} [queued] ${task.role} -> ${task.agent} ${waitingReason(task, tasks) ?? "waiting"}`) : ["- (none)"]),
+		"Completed agents:",
+		...(completedAgents.length ? completedAgents.map(agentLine) : ["- (none)"]),
 		"Policy decisions:",
 		...(manifest.policyDecisions?.length ? manifest.policyDecisions.map((item) => `- ${item.action} (${item.reason})${item.taskId ? ` ${item.taskId}` : ""}: ${item.message}`) : ["- (none)"]),
 		`Total usage: ${formatUsage(totalUsage)}`,
@@ -450,7 +523,7 @@ export async function handleResume(params: TeamToolParamsValue, ctx: TeamContext
 		appendEvent(loaded.manifest.eventsPath, { type: "run.resume_requested", runId: loaded.manifest.runId });
 		const loadedConfig = loadConfig(ctx.cwd);
 		const runtime = await resolveCrewRuntime(loadedConfig.config);
-		const executeWorkers = runtime.kind === "child-process";
+		const executeWorkers = runtime.kind !== "scaffold";
 		const executed = await executeTeamRun({ manifest: loaded.manifest, tasks: resetTasks, team, workflow, agents: allAgents(discoverAgents(ctx.cwd)), executeWorkers, limits: loadedConfig.config.limits, runtime, runtimeConfig: loadedConfig.config.runtime, parentContext: buildParentContext(ctx), parentModel: ctx.model, modelRegistry: ctx.modelRegistry, modelOverride: params.model, signal: ctx.signal });
 		return result([`Resumed run ${executed.manifest.runId}.`, `Status: ${executed.manifest.status}`, `Tasks: ${executed.tasks.length}`, `Artifacts: ${executed.manifest.artifactsRoot}`].join("\n"), { action: "resume", status: executed.manifest.status === "failed" ? "error" : "ok", runId: executed.manifest.runId, artifactsRoot: executed.manifest.artifactsRoot }, executed.manifest.status === "failed");
 	});