pi-crew 0.1.28 → 0.1.30

package/src/extension/registration/commands.ts

@@ -0,0 +1,208 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { loadConfig } from "../../config/config.ts";
+import { handleTeamTool } from "../team-tool.ts";
+import { piTeamsHelp } from "../help.ts";
+import { handleTeamManagerCommand } from "../team-manager-command.ts";
+import { loadRunManifestById } from "../../state/state-store.ts";
+import type { TeamRunManifest } from "../../state/types.ts";
+import { readCrewAgents } from "../../runtime/crew-agent-records.ts";
+import { AnimatedMascot } from "../../ui/mascot.ts";
+import { RunDashboard, type RunDashboardSelection } from "../../ui/run-dashboard.ts";
+import { DurableTextViewer } from "../../ui/transcript-viewer.ts";
+import { commandText, notifyCommandResult, parseRunArgs, parseScalar, pushUnset, setNestedConfig } from "./command-utils.ts";
+import { openTranscriptViewer, selectAgentTask } from "./viewers.ts";
+import { printTimings, time } from "../../utils/timings.ts";
+
+export interface RegisterTeamCommandsDeps {
+	startForegroundRun: (ctx: ExtensionContext, runner: (signal?: AbortSignal) => Promise<void>, runId?: string) => void;
+	openLiveSidebar: (ctx: ExtensionContext, runId: string) => void;
+	getManifestCache: (cwd: string) => { list(max?: number): TeamRunManifest[] };
+}
+
+export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommandsDeps): void {
+	pi.registerCommand("teams", {
+		description: "List pi-crew teams, workflows, and agents",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			const result = await handleTeamTool({ action: "list" }, ctx);
+			await notifyCommandResult(ctx, commandText(result));
+		},
+	});
+
+	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, runId) => deps.startForegroundRun(ctx as ExtensionContext, runner, runId), onRunStarted: (runId) => deps.openLiveSidebar(ctx as ExtensionContext, runId) });
+			await notifyCommandResult(ctx, commandText(result));
+		},
+	});
+
+	for (const [name, action, description] of [
+		["team-status", "status", "Show pi-crew run status"],
+		["team-resume", "resume", "Resume a pi-crew run by re-queueing failed/cancelled/skipped/running tasks"],
+		["team-summary", "summary", "Show pi-crew run summary"],
+		["team-events", "events", "Show full pi-crew event log for a run"],
+		["team-artifacts", "artifacts", "List pi-crew artifacts for a run"],
+		["team-worktrees", "worktrees", "List pi-crew worktrees for a run"],
+		["team-export", "export", "Export a pi-crew run bundle to artifacts/export"],
+		["team-cancel", "cancel", "Cancel a pi-crew run"],
+	] as const) {
+		pi.registerCommand(name, { description, handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const runId = args.trim() || undefined;
+			const result = await handleTeamTool({ action, runId }, ctx);
+			await notifyCommandResult(ctx, commandText(result));
+		} });
+	}
+
+	pi.registerCommand("team-api", {
+		description: "Run safe pi-crew API interop operations: <runId> <operation> [key=value]",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const tokens = args.trim().split(/\s+/).filter(Boolean);
+			const runId = tokens.find((token) => !token.includes("=") && !token.startsWith("--"));
+			const operation = tokens.find((token) => token !== runId && !token.includes("=") && !token.startsWith("--")) ?? "read-manifest";
+			const config: Record<string, unknown> = { operation };
+			for (const token of tokens.filter((item) => item.includes("="))) {
+				const [key, ...rest] = token.split("=");
+				if (key) config[key] = parseScalar(rest.join("="));
+			}
+			const result = await handleTeamTool({ action: "api", runId, config }, ctx);
+			await notifyCommandResult(ctx, commandText(result));
+		},
+	});
+
+	pi.registerCommand("team-imports", { description: "List imported pi-crew run bundles", handler: async (_args: string, ctx: ExtensionCommandContext) => {
+		const result = await handleTeamTool({ action: "imports" }, ctx);
+		await notifyCommandResult(ctx, commandText(result));
+	} });
+
+	pi.registerCommand("team-import", { description: "Import a pi-crew run-export.json bundle into local imports", handler: async (args: string, ctx: ExtensionCommandContext) => {
+		const tokens = args.trim().split(/\s+/).filter(Boolean);
+		const pathArg = tokens.find((token) => !token.startsWith("--"));
+		const scope = tokens.includes("--user") ? "user" : "project";
+		const result = await handleTeamTool({ action: "import", config: { path: pathArg, scope } }, ctx);
+		await notifyCommandResult(ctx, commandText(result));
+	} });
+
+	pi.registerCommand("team-prune", { description: "Prune old finished pi-crew runs, keeping the newest N", handler: async (args: string, ctx: ExtensionCommandContext) => {
+		const tokens = args.trim().split(/\s+/).filter(Boolean);
+		const keepToken = tokens.find((token) => token.startsWith("--keep="));
+		const keep = keepToken ? Number.parseInt(keepToken.slice("--keep=".length), 10) : undefined;
+		const result = await handleTeamTool({ action: "prune", keep, confirm: tokens.includes("--confirm") }, ctx);
+		await notifyCommandResult(ctx, commandText(result));
+	} });
+
+	pi.registerCommand("team-forget", { description: "Forget a pi-crew run by deleting its state and artifacts", handler: async (args: string, ctx: ExtensionCommandContext) => {
+		const tokens = args.trim().split(/\s+/).filter(Boolean);
+		const runId = tokens.find((token) => !token.startsWith("--"));
+		const result = await handleTeamTool({ action: "forget", runId, force: tokens.includes("--force"), confirm: tokens.includes("--confirm") }, ctx);
+		await notifyCommandResult(ctx, commandText(result));
+	} });
+
+	pi.registerCommand("team-cleanup", { description: "Clean up pi-crew worktrees for a run", handler: async (args: string, ctx: ExtensionCommandContext) => {
+		const tokens = args.trim().split(/\s+/).filter(Boolean);
+		const runId = tokens.find((token) => !token.startsWith("--"));
+		const result = await handleTeamTool({ action: "cleanup", runId, force: tokens.includes("--force") }, ctx);
+		await notifyCommandResult(ctx, commandText(result));
+	} });
+
+	pi.registerCommand("team-manager", { description: "Open a simple pi-crew interactive manager", handler: handleTeamManagerCommand });
+
+	pi.registerCommand("team-result", { description: "Open a pi-crew agent result viewer: <runId> [taskId]", handler: async (args: string, ctx: ExtensionCommandContext) => {
+		const [runId, rawTaskId] = args.trim().split(/\s+/).filter(Boolean);
+		const selected = await selectAgentTask(ctx, runId, rawTaskId);
+		const loaded = selected ? loadRunManifestById(ctx.cwd, selected.runId) : undefined;
+		if (ctx.hasUI && loaded) {
+			const agent = readCrewAgents(loaded.manifest).find((item) => item.taskId === selected?.taskId || item.id === selected?.taskId) ?? readCrewAgents(loaded.manifest)[0];
+			const text = agent?.resultArtifactPath ? commandText(await handleTeamTool({ action: "api", runId: selected!.runId, config: { operation: "read-agent-output", agentId: agent.taskId, maxBytes: 64_000 } }, ctx)) : "(no result)";
+			await ctx.ui.custom<undefined>((_tui, theme, _keybindings, done) => new DurableTextViewer("pi-crew result", `${selected!.runId}:${agent?.taskId ?? "unknown"}`, text.split(/\r?\n/), theme, done), { overlay: true, overlayOptions: { width: "90%", maxHeight: "85%", anchor: "center" } });
+			return;
+		}
+		const result = await handleTeamTool({ action: "api", runId, config: { operation: "read-agent-output", agentId: rawTaskId, maxBytes: 64_000 } }, ctx);
+		await notifyCommandResult(ctx, commandText(result));
+	} });
+
+	pi.registerCommand("team-transcript", { description: "Open a pi-crew transcript viewer: <runId> [taskId]", handler: async (args: string, ctx: ExtensionCommandContext) => {
+		const [runId, taskId] = args.trim().split(/\s+/).filter(Boolean);
+		if (await openTranscriptViewer(ctx, runId, taskId)) return;
+		const result = await handleTeamTool({ action: "api", runId, config: { operation: "read-agent-transcript", agentId: taskId } }, ctx);
+		await notifyCommandResult(ctx, commandText(result));
+	} });
+
+	pi.registerCommand("team-dashboard", { description: "Open a pi-crew run dashboard overlay", handler: async (_args: string, ctx: ExtensionCommandContext) => {
+		for (;;) {
+			const runs = deps.getManifestCache(ctx.cwd).list(50);
+			const uiConfig = loadConfig(ctx.cwd).config.ui;
+			const rightPanel = uiConfig?.dashboardPlacement !== "center";
+			const width = rightPanel ? Math.min(90, Math.max(40, uiConfig?.dashboardWidth ?? 56)) : "90%";
+			const selection = await ctx.ui.custom<RunDashboardSelection | undefined>((_tui, theme, _keybindings, done) => new RunDashboard(runs, done, theme, { placement: rightPanel ? "right" : "center", showModel: uiConfig?.showModel, showTokens: uiConfig?.showTokens, showTools: uiConfig?.showTools }), { overlay: true, overlayOptions: rightPanel ? { width, minWidth: 40, maxHeight: "100%", anchor: "top-right", offsetX: 0, offsetY: 0, margin: { top: 0, right: 0, bottom: 0, left: 0 } } : { width, maxHeight: "90%", anchor: "center", margin: 2 } });
+			if (!selection) return;
+			if (selection.action === "reload") continue;
+			if (selection.action === "agent-transcript" && await openTranscriptViewer(ctx, selection.runId)) continue;
+			const result = selection.action === "api" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-manifest" } }, ctx) : selection.action === "agents" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "agent-dashboard" } }, ctx) : selection.action === "agent-events" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-events", limit: 50 } }, ctx) : selection.action === "agent-output" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-output", maxBytes: 32_000 } }, ctx) : selection.action === "agent-transcript" ? await handleTeamTool({ action: "api", runId: selection.runId, config: { operation: "read-agent-transcript" } }, ctx) : await handleTeamTool({ action: selection.action, runId: selection.runId }, ctx);
+			await notifyCommandResult(ctx, commandText(result));
+			return;
+		}
+	} });
+
+	pi.registerCommand("team-mascot", { description: "Show an animated mascot splash", handler: async (args: string, ctx: ExtensionCommandContext) => {
+		if (!ctx.hasUI) return;
+		const tokens = args.trim().split(/\s+/).filter(Boolean);
+		const uiConfig = loadConfig(ctx.cwd).config.ui;
+		const styleArg = tokens.find((t) => t === "cat" || t === "armin");
+		const effectArg = tokens.find((t) => ["random", "none", "typewriter", "scanline", "rain", "fade", "crt", "glitch", "dissolve"].includes(t));
+		const style = (styleArg as "cat" | "armin" | undefined) ?? uiConfig?.mascotStyle ?? "cat";
+		const effect = (effectArg as "random" | "none" | "typewriter" | "scanline" | "rain" | "fade" | "crt" | "glitch" | "dissolve" | undefined) ?? uiConfig?.mascotEffect ?? "random";
+		await ctx.ui.custom<undefined>((tui, theme, _keybindings, done) => new AnimatedMascot(theme, () => done(undefined), { frameIntervalMs: style === "armin" ? 33 : 180, autoCloseMs: 7000, requestRender: () => (tui as { requestRender?: () => void }).requestRender?.(), style, effect }), { overlay: true, overlayOptions: { width: style === "armin" ? 48 : 62, maxHeight: "85%", anchor: "center" } });
+	} });
+
+	pi.registerCommand("team-init", { description: "Initialize project-local pi-crew directories and gitignore entries", handler: async (args: string, ctx: ExtensionCommandContext) => {
+		const tokens = args.trim().split(/\s+/).filter(Boolean);
+		const result = await handleTeamTool({ action: "init", config: { copyBuiltins: tokens.includes("--copy-builtins"), overwrite: tokens.includes("--overwrite") } }, ctx);
+		await notifyCommandResult(ctx, commandText(result));
+	} });
+
+	pi.registerCommand("team-autonomy", { description: "Show or toggle pi-crew autonomous delegation policy: status|on|off", handler: async (args: string, ctx: ExtensionCommandContext) => {
+		const tokens = args.trim().split(/\s+/).filter(Boolean);
+		const mode = tokens[0]?.toLowerCase();
+		const config = mode === "on" ? { profile: "suggested", enabled: true, injectPolicy: true } : mode === "off" ? { profile: "manual", enabled: false } : mode === "manual" || mode === "suggested" || mode === "assisted" || mode === "aggressive" ? { profile: mode, enabled: mode !== "manual", injectPolicy: mode !== "manual" } : { preferAsyncForLongTasks: tokens.includes("--prefer-async") ? true : undefined, allowWorktreeSuggestion: tokens.includes("--no-worktree-suggest") ? false : undefined };
+		const result = await handleTeamTool({ action: "autonomy", config }, ctx);
+		await notifyCommandResult(ctx, commandText(result));
+	} });
+
+	pi.registerCommand("team-config", { description: "Show or update pi-crew config. Use key=value [--project] to update.", handler: async (args: string, ctx: ExtensionCommandContext) => {
+		const tokens = args.trim().split(/\s+/).filter(Boolean);
+		if (tokens.length === 0) {
+			const result = await handleTeamTool({ action: "config" }, ctx);
+			await notifyCommandResult(ctx, commandText(result));
+			return;
+		}
+		const config: Record<string, unknown> = { scope: tokens.includes("--project") ? "project" : "user" };
+		for (const token of tokens) {
+			if (token.startsWith("--unset=")) {
+				pushUnset(config, token.slice("--unset=".length));
+				continue;
+			}
+			if (!token.includes("=")) continue;
+			const [key, ...rest] = token.split("=");
+			if (!key) continue;
+			const raw = rest.join("=");
+			if (raw === "unset" || raw === "null") pushUnset(config, key);
+			else setNestedConfig(config, key, parseScalar(raw));
+		}
+		const result = await handleTeamTool({ action: "config", config }, ctx);
+		await notifyCommandResult(ctx, commandText(result));
+	} });
+
+	for (const [name, action, description] of [
+		["team-validate", "validate", "Validate pi-crew agents, teams, and workflows"],
+		["team-doctor", "doctor", "Check pi-crew installation and discovery readiness"],
+	] as const) pi.registerCommand(name, { description, handler: async (_args: string, ctx: ExtensionCommandContext) => {
+		const result = await handleTeamTool({ action }, ctx);
+		await notifyCommandResult(ctx, commandText(result));
+	} });
+
+	pi.registerCommand("team-help", { description: "Show pi-crew command help", handler: async (_args: string, ctx: ExtensionCommandContext) => {
+		await notifyCommandResult(ctx, piTeamsHelp());
+	} });
+	time("register.commands");
+	printTimings();
+}

package/src/extension/registration/subagent-helpers.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { loadRunManifestById } from "../../state/state-store.ts";
-import { savePersistedSubagentRecord, type SubagentRecord, type SubagentSpawnOptions } from "../../runtime/subagent-manager.ts";
+import { savePersistedSubagentRecord, type SubagentRecord, type SubagentSpawnOptions } from "../../subagents/manager.ts";
 
 export function sendFollowUp(pi: ExtensionAPI, content: string): void {
 	const sender = (pi as unknown as { sendMessage?: (message: unknown, options?: unknown) => void }).sendMessage;

package/src/extension/registration/subagent-tools.ts

@@ -0,0 +1,110 @@
+import type { ExtensionAPI, ToolDefinition } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import { handleTeamTool } from "../team-tool.ts";
+import { checkSubagentSpawnPermission, currentCrewRole } from "../../runtime/role-permission.ts";
+import { readPersistedSubagentRecord, savePersistedSubagentRecord, type SubagentManager, type SubagentSpawnOptions } from "../../subagents/manager.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { __test__subagentSpawnParams, formatSubagentRecord, readSubagentRunResult, refreshPersistedSubagentRecord, subagentToolResult } from "./subagent-helpers.ts";
+
+export function registerSubagentTools(pi: ExtensionAPI, subagentManager: SubagentManager): void {
+	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 currentRole = currentCrewRole();
+			const permission = checkSubagentSpawnPermission(currentRole);
+			if (!permission.allowed) return subagentToolResult(permission.reason ?? "Current role cannot spawn subagents.", { role: currentRole, mode: permission.mode }, true);
+			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: spawnOptions.background, config: spawnOptions.maxTurns ? { runtime: { maxTurns: spawnOptions.maxTurns } } : undefined } as TeamToolParamsValue, spawnOptions.background ? { ...ctx, signal: childSignal } : { ...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 inMemory = subagentManager.getRecord(p.agent_id);
+			const record = inMemory ?? readPersistedSubagentRecord(ctx.cwd, p.agent_id);
+			if (!record) return subagentToolResult(`Agent not found: ${p.agent_id}`, {}, true);
+			let current = refreshPersistedSubagentRecord(ctx, record);
+			if (!inMemory && !current.runId && (current.status === "running" || current.status === "queued")) {
+				current = { ...current, status: "error", error: "Subagent was interrupted before its durable run id was recorded; it cannot be recovered after restart.", completedAt: current.completedAt ?? Date.now() };
+				savePersistedSubagentRecord(ctx.cwd, current);
+			}
+			if (p.wait && (current.status === "running" || current.status === "queued")) {
+				current.resultConsumed = true;
+				savePersistedSubagentRecord(ctx.cwd, current);
+				const waited = await subagentManager.waitForRecord(current.id);
+				if (waited) current = waited;
+				else while (current.status === "running" || current.status === "queued") {
+					if (signal?.aborted) {
+						current = { ...current, status: "error", error: "Waiting for subagent result was aborted.", completedAt: Date.now() };
+						savePersistedSubagentRecord(ctx.cwd, current);
+						break;
+					}
+					await new Promise((resolve) => setTimeout(resolve, 1000));
+					current = refreshPersistedSubagentRecord(ctx, current);
+					if (!current.runId) break;
+				}
+			}
+			const output = readSubagentRunResult(ctx, current);
+			if (current.status !== "running" && current.status !== "queued") {
+				current.resultConsumed = true;
+				savePersistedSubagentRecord(ctx.cwd, current);
+			}
+			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, _signal, _onUpdate, ctx) {
+			const p = params as { agent_id?: string; message?: string };
+			const record = p.agent_id ? subagentManager.getRecord(p.agent_id) ?? readPersistedSubagentRecord(ctx.cwd, 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 [crewAgentTool, crewAgentResultTool, crewAgentSteerTool]) pi.registerTool(extraTool);
+	for (const extraTool of [agentTool, getSubagentResultTool, steerSubagentTool]) {
+		try {
+			pi.registerTool(extraTool);
+		} catch (error) {
+			logInternalError("register.duplicate-tool", error, `tool=${extraTool.name}`);
+		}
+	}
+}

package/src/extension/registration/team-tool.ts

@@ -0,0 +1,44 @@
+import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@mariozechner/pi-coding-agent";
+import { loadConfig } from "../../config/config.ts";
+import { TeamToolParams, type TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import type { CrewWidgetState } from "../../ui/crew-widget.ts";
+import { updateCrewWidget } from "../../ui/crew-widget.ts";
+import { updatePiCrewPowerbar } from "../../ui/powerbar-publisher.ts";
+import type { createManifestCache } from "../../runtime/manifest-cache.ts";
+import { handleTeamTool } from "../team-tool.ts";
+
+export interface RegisterTeamToolDeps {
+	foregroundControllers: Set<AbortController>;
+	startForegroundRun: (ctx: ExtensionContext, runner: (signal?: AbortSignal) => Promise<void>, runId?: string) => void;
+	openLiveSidebar: (ctx: ExtensionContext, runId: string) => void;
+	getManifestCache: (cwd: string) => ReturnType<typeof createManifestCache>;
+	widgetState: CrewWidgetState;
+}
+
+export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps): void {
+	const tool: ToolDefinition = {
+		name: "team",
+		label: "Team",
+		description: "Coordinate Pi teams. Use proactively for complex multi-file work, planning, implementation, tests, reviews, security audits, research, async/background runs, and worktree-isolated execution. Use action='recommend' when unsure which team/workflow to choose. Destructive actions require explicit user confirmation.",
+		promptSnippet: "Use the team tool proactively for coordinated multi-agent work. If unsure, call { action: 'recommend', goal } first, then run or plan with the suggested team/workflow.",
+		parameters: TeamToolParams as never,
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			const controller = new AbortController();
+			deps.foregroundControllers.add(controller);
+			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, runId) => deps.startForegroundRun(ctx, runner, runId), onRunStarted: (runId) => deps.openLiveSidebar(ctx, runId) });
+				const config = loadConfig(ctx.cwd).config.ui;
+				const cache = deps.getManifestCache(ctx.cwd);
+				updateCrewWidget(ctx, deps.widgetState, config, cache);
+				updatePiCrewPowerbar(pi.events, ctx.cwd, config, cache);
+				return output;
+			} finally {
+				signal?.removeEventListener("abort", abort);
+				deps.foregroundControllers.delete(controller);
+			}
+		},
+	};
+	pi.registerTool(tool);
+}

package/src/extension/team-tool/api.ts

@@ -8,14 +8,14 @@ import { claimTask, releaseTaskClaim, transitionClaimedTaskStatus } from "../../
 import { acknowledgeMailboxMessage, appendMailboxMessage, readDeliveryState, readMailbox, validateMailbox, type MailboxDirection } from "../../state/mailbox.ts";
 import { appendEvent, readEvents, readEventsCursor } from "../../state/event-log.ts";
 import { resolveCrewRuntime } from "../../runtime/runtime-resolver.ts";
-import { probeLiveSessionRuntime } from "../../runtime/live-session-runtime.ts";
+import { probeLiveSessionRuntime } from "../../subagents/live/session-runtime.ts";
 import { touchWorkerHeartbeat } from "../../runtime/worker-heartbeat.ts";
 import { agentEventsPath, agentOutputPath, readCrewAgentEvents, readCrewAgentEventsCursor, readCrewAgentStatus, readCrewAgents } from "../../runtime/crew-agent-records.ts";
 import { buildAgentDashboard, readAgentOutput } from "../../runtime/agent-observability.ts";
 import { readForegroundControlStatus, writeForegroundInterruptRequest } from "../../runtime/foreground-control.ts";
-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 { listLiveAgents, resumeLiveAgent, steerLiveAgent, stopLiveAgent } from "../../subagents/live/manager.ts";
+import { appendLiveAgentControlRequest } from "../../subagents/live/control.ts";
+import { liveControlRealtimeMessage, publishLiveControlRealtime } from "../../subagents/live/realtime.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { configRecord, result, type TeamContext } from "./context.ts";
 

package/src/extension/team-tool/cancel.ts

@@ -0,0 +1,31 @@
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import { withRunLockSync } from "../../state/locks.ts";
+import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../../state/state-store.ts";
+import { saveCrewAgents, recordFromTask } from "../../runtime/crew-agent-records.ts";
+import { writeForegroundInterruptRequest } from "../../runtime/foreground-control.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+import { result, type TeamContext } from "./context.ts";
+
+export function handleCancel(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	if (!params.runId) return result("Cancel requires runId.", { action: "cancel", status: "error" }, true);
+	const loaded = loadRunManifestById(ctx.cwd, params.runId);
+	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "cancel", status: "error" }, true);
+	return withRunLockSync(loaded.manifest, () => {
+		if (loaded.manifest.status === "completed" && !params.force) return result(`Run ${loaded.manifest.runId} is already completed; nothing to cancel. Use force: true to mark it cancelled anyway.`, { action: "cancel", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+		const tasks = loaded.tasks.map((task) => task.status === "queued" || task.status === "running" ? { ...task, status: "cancelled" as const, finishedAt: new Date().toISOString(), error: "Run cancelled by user request." } : task);
+		saveRunTasks(loaded.manifest, tasks);
+		try {
+			saveCrewAgents(loaded.manifest, tasks.map((task) => recordFromTask(loaded.manifest, task, "child-process")));
+		} catch (error) {
+			logInternalError("team-tool.handleCancel.crewAgents", error, `runId=${loaded.manifest.runId}`);
+		}
+		try {
+			writeForegroundInterruptRequest(loaded.manifest, "Run cancelled by user request.");
+		} catch (error) {
+			logInternalError("team-tool.handleCancel.interruptRequest", error, `runId=${loaded.manifest.runId}`);
+		}
+		const updated = updateRunStatus(loaded.manifest, "cancelled", "Run cancelled by user request. Already-finished worker processes are not retroactively changed.");
+		return result(`Cancelled run ${updated.runId}.`, { action: "cancel", status: "ok", runId: updated.runId, artifactsRoot: updated.artifactsRoot });
+	});
+}

package/src/extension/team-tool/inspect.ts

@@ -0,0 +1,41 @@
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import { readEvents } from "../../state/event-log.ts";
+import { loadRunManifestById } from "../../state/state-store.ts";
+import { aggregateUsage, formatUsage } from "../../state/usage.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+import { result, type TeamContext } from "./context.ts";
+
+export function handleEvents(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	if (!params.runId) return result("Events requires runId.", { action: "events", status: "error" }, true);
+	const loaded = loadRunManifestById(ctx.cwd, params.runId);
+	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "events", status: "error" }, true);
+	const events = readEvents(loaded.manifest.eventsPath);
+	const lines = [`Events for ${loaded.manifest.runId}:`, ...(events.length ? events.map((event) => `${event.time} ${event.type}${event.taskId ? ` ${event.taskId}` : ""}${event.message ? `: ${event.message}` : ""}${event.data ? ` ${JSON.stringify(event.data)}` : ""}`) : ["(none)"])];
+	return result(lines.join("\n"), { action: "events", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+}
+
+export function handleArtifacts(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	if (!params.runId) return result("Artifacts requires runId.", { action: "artifacts", status: "error" }, true);
+	const loaded = loadRunManifestById(ctx.cwd, params.runId);
+	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "artifacts", status: "error" }, true);
+	const lines = [`Artifacts for ${loaded.manifest.runId}:`, ...(loaded.manifest.artifacts.length ? loaded.manifest.artifacts.map((artifact) => `- ${artifact.kind}: ${artifact.path}${artifact.sizeBytes !== undefined ? ` (${artifact.sizeBytes} bytes)` : ""}${artifact.contentHash ? ` sha256=${artifact.contentHash.slice(0, 12)}` : ""}`) : ["- (none)"])];
+	return result(lines.join("\n"), { action: "artifacts", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+}
+
+export function handleSummary(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	if (!params.runId) return result("Summary requires runId.", { action: "summary", status: "error" }, true);
+	const loaded = loadRunManifestById(ctx.cwd, params.runId);
+	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "summary", status: "error" }, true);
+	const usage = aggregateUsage(loaded.tasks);
+	const lines = [
+		`Summary for ${loaded.manifest.runId}`,
+		`Status: ${loaded.manifest.status}`,
+		`Team: ${loaded.manifest.team}`,
+		`Workflow: ${loaded.manifest.workflow ?? "(none)"}`,
+		`Goal: ${loaded.manifest.goal}`,
+		`Usage: ${formatUsage(usage)}`,
+		"Tasks:",
+		...loaded.tasks.map((task) => `- ${task.id}: ${task.status} (${task.role} -> ${task.agent})${task.error ? ` - ${task.error}` : ""}`),
+	];
+	return result(lines.join("\n"), { action: "summary", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+}

package/src/extension/team-tool/lifecycle-actions.ts

@@ -0,0 +1,79 @@
+import * as fs from "node:fs";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import { appendEvent } from "../../state/event-log.ts";
+import { loadRunManifestById } from "../../state/state-store.ts";
+import { cleanupRunWorktrees } from "../../worktree/cleanup.ts";
+import { listImportedRuns } from "../import-index.ts";
+import { exportRunBundle } from "../run-export.ts";
+import { importRunBundle } from "../run-import.ts";
+import { pruneFinishedRuns } from "../run-maintenance.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+import { configRecord, result, type TeamContext } from "./context.ts";
+
+export function handleWorktrees(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	if (!params.runId) return result("Worktrees requires runId.", { action: "worktrees", status: "error" }, true);
+	const loaded = loadRunManifestById(ctx.cwd, params.runId);
+	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "worktrees", status: "error" }, true);
+	const withWorktrees = loaded.tasks.filter((task) => task.worktree);
+	const lines = [`Worktrees for ${loaded.manifest.runId}:`, ...(withWorktrees.length ? withWorktrees.map((task) => `- ${task.id}: ${task.worktree!.path} branch=${task.worktree!.branch} reused=${task.worktree!.reused ? "true" : "false"}`) : ["- (none)"])];
+	return result(lines.join("\n"), { action: "worktrees", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+}
+
+export function handleImports(_params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	const imports = listImportedRuns(ctx.cwd);
+	const lines = ["Imported pi-crew runs:", ...(imports.length ? imports.map((entry) => `- ${entry.runId} (${entry.scope})${entry.status ? ` [${entry.status}]` : ""} ${entry.team ?? "unknown"}/${entry.workflow ?? "none"}: ${entry.goal ?? ""}\n  Bundle: ${entry.bundlePath}\n  Summary: ${entry.summaryPath}`) : ["- (none)"])];
+	return result(lines.join("\n"), { action: "imports", status: "ok" });
+}
+
+export function handleImport(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	const cfg = configRecord(params.config);
+	const bundlePath = typeof cfg.path === "string" ? cfg.path : typeof cfg.bundlePath === "string" ? cfg.bundlePath : undefined;
+	if (!bundlePath) return result("Import requires config.path pointing at run-export.json.", { action: "import", status: "error" }, true);
+	const scope = cfg.scope === "user" ? "user" : "project";
+	try {
+		const imported = importRunBundle(ctx.cwd, bundlePath, scope);
+		return result([`Imported run bundle ${imported.runId}.`, `Bundle: ${imported.bundlePath}`, `Summary: ${imported.summaryPath}`].join("\n"), { action: "import", status: "ok" });
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return result(`Import failed: ${message}`, { action: "import", status: "error" }, true);
+	}
+}
+
+export function handleExport(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	if (!params.runId) return result("Export requires runId.", { action: "export", status: "error" }, true);
+	const loaded = loadRunManifestById(ctx.cwd, params.runId);
+	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "export", status: "error" }, true);
+	const exported = exportRunBundle(loaded.manifest, loaded.tasks);
+	appendEvent(loaded.manifest.eventsPath, { type: "run.exported", runId: loaded.manifest.runId, data: exported });
+	return result([`Exported run ${loaded.manifest.runId}.`, `JSON: ${exported.jsonPath}`, `Markdown: ${exported.markdownPath}`].join("\n"), { action: "export", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+}
+
+export function handlePrune(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	const keep = params.keep ?? 20;
+	if (!params.confirm) return result("prune requires confirm: true.", { action: "prune", status: "error" }, true);
+	if (keep < 0 || !Number.isInteger(keep)) return result("keep must be an integer >= 0.", { action: "prune", status: "error" }, true);
+	const pruned = pruneFinishedRuns(ctx.cwd, keep);
+	return result([`Pruned finished pi-crew runs.`, `Kept: ${pruned.kept.length}`, `Removed: ${pruned.removed.length}`, ...(pruned.removed.length ? ["Removed runs:", ...pruned.removed.map((runId) => `- ${runId}`)] : [])].join("\n"), { action: "prune", status: "ok" });
+}
+
+export function handleForget(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	if (!params.runId) return result("Forget requires runId.", { action: "forget", status: "error" }, true);
+	if (!params.confirm) return result("forget requires confirm: true.", { action: "forget", status: "error" }, true);
+	const loaded = loadRunManifestById(ctx.cwd, params.runId);
+	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "forget", status: "error" }, true);
+	const cleanup = cleanupRunWorktrees(loaded.manifest, { force: params.force });
+	if (cleanup.preserved.length > 0 && !params.force) return result([`Run '${params.runId}' has preserved worktrees. Use force: true to forget anyway.`, ...cleanup.preserved.map((item) => `- ${item.path}: ${item.reason}`)].join("\n"), { action: "forget", status: "error", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot }, true);
+	fs.rmSync(loaded.manifest.stateRoot, { recursive: true, force: true });
+	fs.rmSync(loaded.manifest.artifactsRoot, { recursive: true, force: true });
+	return result([`Forgot run ${loaded.manifest.runId}.`, `Removed state: ${loaded.manifest.stateRoot}`, `Removed artifacts: ${loaded.manifest.artifactsRoot}`, ...(cleanup.removed.length ? ["Removed worktrees:", ...cleanup.removed.map((item) => `- ${item}`)] : [])].join("\n"), { action: "forget", status: "ok", runId: loaded.manifest.runId });
+}
+
+export function handleCleanup(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	if (!params.runId) return result("Cleanup requires runId.", { action: "cleanup", status: "error" }, true);
+	const loaded = loadRunManifestById(ctx.cwd, params.runId);
+	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "cleanup", status: "error" }, true);
+	const cleanup = cleanupRunWorktrees(loaded.manifest, { force: params.force });
+	appendEvent(loaded.manifest.eventsPath, { type: "worktree.cleanup", runId: loaded.manifest.runId, data: { removed: cleanup.removed, preserved: cleanup.preserved, artifacts: cleanup.artifactPaths } });
+	const lines = [`Worktree cleanup for ${loaded.manifest.runId}:`, "Removed:", ...(cleanup.removed.length ? cleanup.removed.map((item) => `- ${item}`) : ["- (none)"]), "Preserved:", ...(cleanup.preserved.length ? cleanup.preserved.map((item) => `- ${item.path}: ${item.reason}`) : ["- (none)"]), "Artifacts:", ...(cleanup.artifactPaths.length ? cleanup.artifactPaths.map((item) => `- ${item}`) : ["- (none)"])];
+	return result(lines.join("\n"), { action: "cleanup", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+}

package/src/extension/team-tool/plan.ts

@@ -0,0 +1,19 @@
+import { allTeams, discoverTeams } from "../../teams/discover-teams.ts";
+import { allWorkflows, discoverWorkflows } from "../../workflows/discover-workflows.ts";
+import { validateWorkflowForTeam } from "../../workflows/validate-workflow.ts";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+import { result, type TeamContext } from "./context.ts";
+
+export function handlePlan(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	const teamName = params.team ?? "default";
+	const team = allTeams(discoverTeams(ctx.cwd)).find((item) => item.name === teamName);
+	if (!team) return result(`Team '${teamName}' not found.`, { action: "plan", status: "error" }, true);
+	const workflowName = params.workflow ?? team.defaultWorkflow ?? "default";
+	const workflow = allWorkflows(discoverWorkflows(ctx.cwd)).find((item) => item.name === workflowName);
+	if (!workflow) return result(`Workflow '${workflowName}' not found.`, { action: "plan", status: "error" }, true);
+	const errors = validateWorkflowForTeam(workflow, team);
+	if (errors.length > 0) return result([`Workflow '${workflow.name}' is not valid for team '${team.name}':`, ...errors.map((error) => `- ${error}`)].join("\n"), { action: "plan", status: "error" }, true);
+	const lines = [`Team plan: ${team.name}`, `Workflow: ${workflow.name}`, `Goal: ${params.goal ?? params.task ?? "(not provided)"}`, "", "Steps:", ...workflow.steps.map((step, index) => `${index + 1}. ${step.id} [${step.role}]${step.dependsOn?.length ? ` after ${step.dependsOn.join(", ")}` : ""}`)];
+	return result(lines.join("\n"), { action: "plan", status: "ok" });
+}