pi-crew 0.1.45 → 0.1.49

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

@@ -5,7 +5,7 @@ import { loadRunManifestById, saveRunManifest, saveRunTasks, updateRunStatus } f
 import { withRunLockSync } from "../../state/locks.ts";
 import { canTransitionTaskStatus, isTeamTaskStatus } from "../../state/contracts.ts";
 import { claimTask, releaseTaskClaim, transitionClaimedTaskStatus } from "../../state/task-claims.ts";
-import { acknowledgeMailboxMessage, appendMailboxMessage, readDeliveryState, readMailbox, readMailboxMessage, validateMailbox, type MailboxDirection } from "../../state/mailbox.ts";
+import { acknowledgeMailboxMessage, appendFollowUpMessage, appendMailboxMessage, appendSteeringMessage, readDeliveryState, readMailbox, readMailboxMessage, validateMailbox, type MailboxDirection, type MailboxMessageKind } from "../../state/mailbox.ts";
 import { appendEvent, readEvents, readEventsCursor } from "../../state/event-log.ts";
 import { resolveCrewRuntime } from "../../runtime/runtime-resolver.ts";
 import { probeLiveSessionRuntime } from "../../subagents/live/session-runtime.ts";
@@ -14,9 +14,10 @@ import { touchWorkerHeartbeat } from "../../runtime/worker-heartbeat.ts";
 import { agentOutputPath, 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 { getLiveAgent, listLiveAgents, resumeLiveAgent, steerLiveAgent, stopLiveAgent } from "../../subagents/live/manager.ts";
+import { followUpLiveAgent, getLiveAgent, 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 { buildCapabilityInventory } from "../../runtime/capability-inventory.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { configRecord, result, type TeamContext } from "./context.ts";
@@ -76,6 +77,10 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 		});
 		return result(JSON.stringify(filtered, null, 2), { action: "api", status: "ok", ...(runIdFilter ? { runId: runIdFilter } : {}) });
 	}
+	if (operation === "inventory") {
+		const inventory = buildCapabilityInventory(ctx.cwd, ctx.config);
+		return result(JSON.stringify(inventory, null, 2), { action: "api", status: "ok" });
+	}
 	if (!params.runId) return result("API requires runId.", { action: "api", status: "error" }, true);
 	const loaded = loadRunManifestById(ctx.cwd, params.runId);
 	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "api", status: "error" }, true);
@@ -212,7 +217,7 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 		const agent = readCrewAgents(loaded.manifest).find((item) => item.id === agentId || item.taskId === agentId);
 		if (!agent) return result("API nudge-agent requires config.agentId matching an agent id or task id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 		const messageText = typeof cfg.message === "string" && cfg.message.trim() ? cfg.message.trim() : "Please report your current status, blocker, or smallest next step.";
-		const message = appendMailboxMessage(loaded.manifest, { direction: "inbox", from: "leader", to: agent.taskId, taskId: agent.taskId, body: messageText });
+		const message = appendSteeringMessage(loaded.manifest, { taskId: agent.taskId, to: agent.taskId, body: messageText, priority: "normal", data: { source: "nudge-agent" } });
 		appendEvent(loaded.manifest.eventsPath, { type: "agent.nudged", runId: loaded.manifest.runId, taskId: agent.taskId, message: messageText, data: { agentId: agent.id, mailboxMessageId: message.id } });
 		ctx.events?.emit?.("crew.mailbox.message", { runId: loaded.manifest.runId, id: message.id, direction: message.direction, from: message.from, to: message.to, taskId: message.taskId, source: "nudge-agent" });
 		return result(JSON.stringify({ agentId: agent.id, mailboxMessage: message }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
@@ -220,7 +225,7 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 	if (operation === "list-live-agents") {
 		return result(JSON.stringify(listLiveAgents().filter((agent) => agent.runId === loaded.manifest.runId), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 	}
-	if (operation === "steer-agent" || operation === "stop-agent" || operation === "resume-agent" || operation === "interrupt-agent") {
+	if (operation === "steer-agent" || operation === "follow-up-agent" || operation === "stop-agent" || operation === "resume-agent" || operation === "interrupt-agent") {
 		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
 		if (!agentId) return result(`API ${operation} requires config.agentId.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 		const message = typeof cfg.message === "string" && cfg.message.trim() ? cfg.message.trim() : undefined;
@@ -228,7 +233,22 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 		try {
 			const live = getLiveAgent(agentId);
 			if (live && live.runId !== loaded.manifest.runId) return result(`Live agent '${agentId}' does not belong to run ${loaded.manifest.runId}.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
-			if (operation === "steer-agent") return result(JSON.stringify(await steerLiveAgent(agentId, message ?? "Please report current status and wrap up if possible."), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			if (!live && (operation === "steer-agent" || operation === "follow-up-agent")) throw new Error(`Live agent '${agentId}' not found.`);
+			const liveTaskId = live?.taskId;
+			if ((operation === "steer-agent" || operation === "follow-up-agent") && !liveTaskId) throw new Error(`Live agent '${agentId}' not found.`);
+			const targetTaskId = liveTaskId ?? agentId;
+			if (operation === "steer-agent") {
+				const text = message ?? "Please report current status and wrap up if possible.";
+				const realtime = await steerLiveAgent(agentId, text);
+				const mailboxMessage = appendSteeringMessage(loaded.manifest, { taskId: targetTaskId, body: text, status: "delivered", data: { source: "steer-agent", realtime: true } });
+				return result(JSON.stringify({ realtime, mailboxMessage }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			}
+			if (operation === "follow-up-agent") {
+				if (!prompt) return result("API follow-up-agent requires config.prompt or config.message.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+				const realtime = await followUpLiveAgent(agentId, prompt);
+				const mailboxMessage = appendFollowUpMessage(loaded.manifest, { taskId: targetTaskId, body: prompt, status: "delivered", data: { source: "follow-up-agent", realtime: true } });
+				return result(JSON.stringify({ realtime, mailboxMessage }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			}
 			if (operation === "resume-agent") {
 				if (!prompt) return result("API resume-agent requires config.prompt or config.message.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 				return result(JSON.stringify(await resumeLiveAgent(agentId, prompt), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
@@ -243,12 +263,14 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 			const task = loaded.tasks.find((item) => item.id === agent.taskId);
 			if (!task) return result(`API ${operation} agent '${agentId}' does not match a run task.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 			if (operation === "resume-agent" && !prompt) return result("API resume-agent requires config.prompt or config.message.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+			if (operation === "follow-up-agent" && !prompt) return result("API follow-up-agent requires config.prompt or config.message.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 			try {
-				const request = appendLiveAgentControlRequest(loaded.manifest, { taskId: task.id, agentId: agent.id, operation: operation === "resume-agent" ? "resume" : operation === "steer-agent" ? "steer" : "stop", message: operation === "resume-agent" ? prompt : message });
+				const request = appendLiveAgentControlRequest(loaded.manifest, { taskId: task.id, agentId: agent.id, operation: operation === "resume-agent" ? "resume" : operation === "follow-up-agent" ? "follow-up" : operation === "steer-agent" ? "steer" : "stop", message: operation === "resume-agent" || operation === "follow-up-agent" ? prompt : message });
+				const mailboxMessage = operation === "steer-agent" ? appendSteeringMessage(loaded.manifest, { taskId: task.id, to: agent.id, body: message ?? "Please report current status and wrap up if possible.", status: "delivered", data: { source: "steer-agent", liveControlRequestId: request.id } }) : operation === "follow-up-agent" && prompt ? appendFollowUpMessage(loaded.manifest, { taskId: task.id, to: agent.id, body: prompt, status: "delivered", data: { source: "follow-up-agent", liveControlRequestId: request.id } }) : undefined;
 				publishLiveControlRealtime(request);
 				ctx.events?.emit?.("pi-crew:live-control", liveControlRealtimeMessage(request));
-				appendEvent(loaded.manifest.eventsPath, { type: "agent.control.queued", runId: loaded.manifest.runId, taskId: agent.taskId, message: `Queued ${request.operation} control request for live agent.`, data: { request, realtime: true } });
-				return result(JSON.stringify({ queued: true, request }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+				appendEvent(loaded.manifest.eventsPath, { type: "agent.control.queued", runId: loaded.manifest.runId, taskId: agent.taskId, message: `Queued ${request.operation} control request for live agent.`, data: { request, mailboxMessageId: mailboxMessage?.id, realtime: true } });
+				return result(JSON.stringify({ queued: true, request, mailboxMessage }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 			} catch (queueError) {
 				const message = queueError instanceof Error ? queueError.message : String(queueError);
 				return result(message, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
@@ -258,9 +280,10 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 	if (operation === "read-mailbox") {
 		const direction = cfg.direction === "inbox" || cfg.direction === "outbox" ? cfg.direction as MailboxDirection : undefined;
 		const taskId = typeof cfg.taskId === "string" ? cfg.taskId : undefined;
+		const kind = typeof cfg.kind === "string" && ["message", "steer", "follow-up", "response", "group_join"].includes(cfg.kind) ? cfg.kind as MailboxMessageKind : undefined;
 		if (taskId && !loaded.tasks.some((task) => task.id === taskId)) return result(`API read-mailbox taskId '${taskId}' does not match a run task.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 		try {
-			return result(JSON.stringify(readMailbox(loaded.manifest, direction, taskId), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			return result(JSON.stringify(readMailbox(loaded.manifest, direction, taskId, kind), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			return result(message, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
@@ -399,5 +422,20 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 			return result(message, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 		}
 	}
+	if (operation === "diff") {
+		const diffArtifacts = loaded.manifest.artifacts.filter(a => a.kind === "diff" || a.kind === "patch");
+		if (diffArtifacts.length === 0) {
+			return result(`No diff artifacts found for run ${loaded.manifest.runId}. Diffs are captured in worktree mode.`, { action: "api", status: "ok", runId: loaded.manifest.runId, intent: `diff ${loaded.manifest.runId}: no diffs` });
+		}
+		const parts: string[] = [`Diff artifacts for run ${loaded.manifest.runId}:`];
+		for (const artifact of diffArtifacts) {
+			const content = safeReadContainedFile(loaded.manifest.artifactsRoot, artifact.path);
+			if (content) {
+				const display = content.length > 4000 ? content.slice(0, 4000) + "\n... (truncated)" : content;
+				parts.push(`\n--- ${artifact.path} ---\n${display}`);
+			}
+		}
+		return result(parts.join("\n"), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot, intent: `diff ${loaded.manifest.runId}` });
+	}
 	return result(`Unknown API operation: ${operation}`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 }

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

@@ -3,9 +3,13 @@ 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 { cancellationReasonFromUnknown, buildSyntheticTerminalEvidence, type CancellationReason } from "../../runtime/cancellation.ts";
+import { appendEvent } from "../../state/event-log.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
+import { executeHook, appendHookEvent } from "../../hooks/registry.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { result, type TeamContext } from "./context.ts";
+import { enforceDestructiveIntent, intentFromConfig } from "./intent-policy.ts";
 
 export interface AbortOwnedResult {
 	abortedIds: string[];
@@ -55,23 +59,118 @@ export function abortOwned(
 	return result;
 }
 
-export function handleCancel(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+function configFromParams(params: TeamToolParamsValue): Record<string, unknown> | undefined {
+	return params.config && typeof params.config === "object" && !Array.isArray(params.config) ? params.config : undefined;
+}
+
+function cancelReasonFromParams(params: TeamToolParamsValue): CancellationReason {
+	const config = configFromParams(params);
+	const rawReason = config?.reason ?? config?.cancelReason;
+	const reason = rawReason === undefined ? { code: "caller_cancelled" as const, message: "Run cancelled by user request." } : cancellationReasonFromUnknown(rawReason);
+	return { code: reason.code, message: reason.message };
+}
+
+export async function handleRetry(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
+	if (!params.runId) return result("Retry requires runId.", { action: "retry", status: "error" }, true);
+	const loaded = loadRunManifestById(ctx.cwd, params.runId);
+	if (!loaded) return result(`Run '${params.runId}' not found.`, { action: "retry", status: "error" }, true);
+
+	// Pre-lock ownership check: reject foreign-owned runs
+	const foreignRun = typeof loaded.manifest.ownerSessionId === "string" && loaded.manifest.ownerSessionId !== ctx.sessionId;
+	if (foreignRun) {
+		return result(`Run ${loaded.manifest.runId} belongs to another session; not retried.`, { action: "retry", status: "error", runId: loaded.manifest.runId }, true);
+	}
+
+	// Execute before_retry hook after ownership confirmed, before mutation lock
+	const hookReport = await executeHook("before_retry", { runId: loaded.manifest.runId, cwd: ctx.cwd });
+	appendHookEvent(loaded.manifest, hookReport);
+	if (hookReport.outcome === "block") {
+		return result(`Retry blocked by hook: ${hookReport.reason ?? "before_retry hook blocked the operation."}`, { action: "retry", status: "error", runId: loaded.manifest.runId }, true);
+	}
+
+	const targetTaskId = typeof params.taskId === "string" ? params.taskId : undefined;
+
+	return withRunLockSync(loaded.manifest, () => {
+		const retryableStatuses: ReadonlySet<string> = new Set(["failed", "cancelled"]);
+
+		const matchingTasks = loaded.tasks.filter((task) => {
+			if (targetTaskId && task.id !== targetTaskId) return false;
+			return retryableStatuses.has(task.status);
+		});
+
+		if (matchingTasks.length === 0) {
+			return result(targetTaskId ? `Task '${targetTaskId}' is not failed/cancelled; nothing to retry.` : "No failed/cancelled tasks to retry.", { action: "retry", status: "error", runId: loaded.manifest.runId }, true);
+		}
+
+		const retriedIds = new Set(matchingTasks.map((t) => t.id));
+		const tasks = loaded.tasks.map((task) => {
+			if (!retriedIds.has(task.id)) return task;
+			const { error: _error, finishedAt: _finishedAt, terminalEvidence: _terminalEvidence, ...rest } = task;
+			return { ...rest, status: "queued" as const };
+		});
+		saveRunTasks(loaded.manifest, tasks);
+		try {
+			saveCrewAgents(loaded.manifest, tasks.map((task) => recordFromTask(loaded.manifest, task, "child-process")));
+		} catch (error) {
+			logInternalError("team-tool.handleRetry.crewAgents", error, `runId=${loaded.manifest.runId}`);
+		}
+
+		const retriedTaskIds = [...retriedIds];
+		for (const taskId of retriedTaskIds) {
+			appendEvent(loaded.manifest.eventsPath, { type: "task.retried", runId: loaded.manifest.runId, taskId, message: `Task ${taskId} queued for retry.` });
+		}
+
+		return result(`Retried ${retriedTaskIds.length} task(s) in run ${loaded.manifest.runId}.`, {
+			action: "retry",
+			status: "ok",
+			runId: loaded.manifest.runId,
+			retriedTaskIds: retriedTaskIds,
+			intent: `retrying ${retriedTaskIds.length} task(s) in ${loaded.manifest.runId}`,
+		});
+	});
+}
+
+export async function handleCancel(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
+	const intentError = enforceDestructiveIntent("cancel", params, ctx.config);
+	if (intentError) return intentError;
 	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);
+
+	// Pre-lock ownership check: reject foreign-owned runs before executing hooks
+	const preCheck = abortOwned(loaded.manifest.runId, undefined, ctx);
+	if (preCheck.abortedIds.length === 0 && preCheck.foreignIds.length > 0) {
+		return result(`Run ${loaded.manifest.runId} belongs to another session; not cancelled.`, { action: "cancel", status: "error", runId: loaded.manifest.runId, foreignIds: preCheck.foreignIds }, true);
+	}
+
+	// Execute before_cancel hook after ownership confirmed, before mutation lock
+	const hookReport = await executeHook("before_cancel", { runId: loaded.manifest.runId, cwd: ctx.cwd });
+	appendHookEvent(loaded.manifest, hookReport);
+	if (hookReport.outcome === "block") {
+		return result(`Cancel blocked by hook: ${hookReport.reason ?? "before_cancel hook blocked the operation."}`, { action: "cancel", status: "error", runId: loaded.manifest.runId }, true);
+	}
+
 	return withRunLockSync(loaded.manifest, () => {
 		if ((loaded.manifest.status === "completed" || loaded.manifest.status === "cancelled") && !params.force) return result(`Run ${loaded.manifest.runId} is already ${loaded.manifest.status}; nothing to cancel. Use force: true to mark it cancelled anyway.`, { action: "cancel", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 
 		// Classify tasks for foreign-aware cancellation
 		const abortResult = abortOwned(loaded.manifest.runId, undefined, ctx);
 		if (abortResult.abortedIds.length === 0 && abortResult.foreignIds.length > 0) {
-			return result(`Run ${loaded.manifest.runId} belongs to another session; not cancelled.`, { action: "cancel", status: "error", runId: loaded.manifest.runId, foreignIds: abortResult.foreignIds } as never, true);
+			return result(`Run ${loaded.manifest.runId} belongs to another session; not cancelled.`, { action: "cancel", status: "error", runId: loaded.manifest.runId, foreignIds: abortResult.foreignIds }, true);
 		}
 		const cancellableIds = new Set(abortResult.abortedIds);
+		const cancelReason = cancelReasonFromParams(params);
+		const cancelIntent = intentFromConfig(params.config);
+		const cancelData = cancelIntent ? { reason: cancelReason.code, intent: cancelIntent } : { reason: cancelReason.code };
+		const cancelMessage = `${cancelReason.message} (${cancelReason.code})`;
 
 		const tasks = loaded.tasks.map((task) => {
 			if (cancellableIds.has(task.id) && (task.status === "queued" || task.status === "running" || task.status === "waiting")) {
-				return { ...task, status: "cancelled" as const, finishedAt: new Date().toISOString(), error: "Run cancelled by user request." };
+				const base = { ...task, status: "cancelled" as const, finishedAt: new Date().toISOString(), error: cancelMessage };
+				if (task.status === "running") {
+					return { ...base, terminalEvidence: [...(task.terminalEvidence ?? []), buildSyntheticTerminalEvidence("worker", cancelReason, task.startedAt)] };
+				}
+				return base;
 			}
 			return task;
 		});
@@ -82,11 +181,15 @@ export function handleCancel(params: TeamToolParamsValue, ctx: TeamContext): PiT
 			logInternalError("team-tool.handleCancel.crewAgents", error, `runId=${loaded.manifest.runId}`);
 		}
 		try {
-			writeForegroundInterruptRequest(loaded.manifest, "Run cancelled by user request.");
+			writeForegroundInterruptRequest(loaded.manifest, cancelMessage);
 		} 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.");
+		ctx.abortForegroundRun?.(loaded.manifest.runId);
+		for (const taskId of abortResult.abortedIds) {
+			appendEvent(loaded.manifest.eventsPath, { type: "task.cancelled", runId: loaded.manifest.runId, taskId, message: cancelMessage, data: cancelData });
+		}
+		const updated = updateRunStatus(loaded.manifest, "cancelled", `${cancelMessage} Already-finished worker processes are not retroactively changed.`, { data: cancelData });
 
 		// Build descriptive message including foreign/missing info
 		const parts = [`Cancelled run ${updated.runId}.`];
@@ -101,6 +204,7 @@ export function handleCancel(params: TeamToolParamsValue, ctx: TeamContext): PiT
 			abortedIds: abortResult.abortedIds,
 			missingIds: abortResult.missingIds,
 			foreignIds: abortResult.foreignIds,
+			intent: cancelIntent,
 		});
 	});
 }

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

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { PiTeamsConfig } from "../../config/config.ts";
 import type { MetricRegistry } from "../../observability/metric-registry.ts";
 import type { TeamToolDetails } from "../team-tool-types.ts";
 import { toolResult, type PiTeamsToolResult } from "../tool-result.ts";
@@ -11,10 +12,17 @@ export type TeamContext = Pick<ExtensionContext, "cwd"> & Partial<Pick<Extension
 	metricRegistry?: MetricRegistry;
 	signal?: AbortSignal;
 	startForegroundRun?: (runner: (signal?: AbortSignal) => Promise<void>, runId?: string) => void;
+	abortForegroundRun?: (runId: string) => boolean;
 	onRunStarted?: (runId: string) => void;
 	onJsonEvent?: (taskId: string, runId: string, event: unknown) => void;
+	config?: PiTeamsConfig;
 };
 
+export function withSessionId<T extends Pick<ExtensionContext, "sessionManager">>(ctx: T): T & { sessionId?: string } {
+	const sessionId = ctx.sessionManager.getSessionId();
+	return sessionId ? { ...ctx, sessionId } : { ...ctx };
+}
+
 export function result(text: string, details: TeamToolDetails, isError = false): PiTeamsToolResult {
 	return toolResult(text, details, isError);
 }

package/src/extension/team-tool/intent-policy.ts

@@ -0,0 +1,42 @@
+import type { PiTeamsConfig } from "../../config/config.ts";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+import { configRecord, result } from "./context.ts";
+
+export type DestructiveIntentAction = "cancel" | "cleanup" | "delete" | "forget" | "prune";
+
+const DESTRUCTIVE_ACTION_LABELS: Record<DestructiveIntentAction, string> = {
+	cancel: "cancel",
+	cleanup: "forced cleanup",
+	delete: "delete",
+	forget: "forget",
+	prune: "prune",
+};
+
+export function intentFromConfig(config: unknown): string | undefined {
+	const cfg = configRecord(config);
+	const rawIntent = cfg.intent ?? cfg._intent;
+	if (typeof rawIntent !== "string") return undefined;
+	const intent = rawIntent.replace(/\s+/g, " ").trim();
+	return intent ? intent.slice(0, 500) : undefined;
+}
+
+export function shouldRequireIntent(config: PiTeamsConfig | undefined): boolean {
+	return config?.policy?.requireIntentForDestructiveActions === true;
+}
+
+export function enforceDestructiveIntent(
+	action: DestructiveIntentAction,
+	params: TeamToolParamsValue,
+	config: PiTeamsConfig | undefined,
+): PiTeamsToolResult | undefined {
+	if (!shouldRequireIntent(config)) return undefined;
+	if (action === "cleanup" && params.force !== true) return undefined;
+	if (intentFromConfig(params.config)) return undefined;
+	const label = DESTRUCTIVE_ACTION_LABELS[action];
+	return result(
+		`Destructive action '${label}' requires config.intent when policy.requireIntentForDestructiveActions is enabled.`,
+		{ action: action === "delete" ? "management" : action, status: "error" },
+		true,
+	);
+}

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

@@ -1,79 +1,120 @@
-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 });
-}
+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";
+import { enforceDestructiveIntent, intentFromConfig } from "./intent-policy.ts";
+import { executeHook, appendHookEvent } from "../../hooks/registry.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 async function handleExport(params: TeamToolParamsValue, ctx: TeamContext): Promise<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 hookReport = await executeHook("before_publish", { runId: loaded.manifest.runId, cwd: ctx.cwd });
+	appendHookEvent(loaded.manifest, hookReport);
+	if (hookReport.outcome === "block") {
+		return result(`Export blocked by hook: ${hookReport.reason ?? "before_publish hook blocked the operation."}`, { action: "export", status: "error", runId: loaded.manifest.runId }, 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 async function handlePrune(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
+	const intentError = enforceDestructiveIntent("prune", params, ctx.config);
+	if (intentError) return intentError;
+	if (!params.confirm) return result("prune requires confirm: true.", { action: "prune", status: "error" }, true);
+	const keep = params.keep ?? 20;
+	if (keep < 0 || !Number.isInteger(keep)) return result("keep must be an integer >= 0.", { action: "prune", status: "error" }, true);
+	const intent = intentFromConfig(params.config);
+	const pruned = pruneFinishedRuns(ctx.cwd, keep, { intent, signal: ctx.signal });
+	const firstRunId = pruned.kept[0] ?? pruned.removed[0];
+	if (firstRunId) {
+		const manifest = loadRunManifestById(ctx.cwd, firstRunId)?.manifest;
+		if (manifest) {
+			const hookReport = await executeHook("before_cleanup", { runId: manifest.runId, cwd: ctx.cwd });
+			appendHookEvent(manifest, hookReport);
+		}
+	}
+	return result([`Pruned finished pi-crew runs.`, `Kept: ${pruned.kept.length}`, `Removed: ${pruned.removed.length}`, ...(pruned.auditPath ? [`Audit: ${pruned.auditPath}`] : []), ...(pruned.removed.length ? ["Removed runs:", ...pruned.removed.map((runId) => `- ${runId}`)] : [])].join("\n"), { action: "prune", status: "ok", intent });
+}
+
+export async function handleForget(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
+	const intentError = enforceDestructiveIntent("forget", params, ctx.config);
+	if (intentError) return intentError;
+	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 hookReport = await executeHook("before_forget", { runId: loaded.manifest.runId, cwd: ctx.cwd });
+	appendHookEvent(loaded.manifest, hookReport);
+	if (hookReport.outcome === "block") {
+		return result(`Forget blocked by hook: ${hookReport.reason ?? "before_forget hook blocked the operation."}`, { action: "forget", status: "error", runId: loaded.manifest.runId }, 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);
+	const intent = intentFromConfig(params.config);
+	appendEvent(loaded.manifest.eventsPath, { type: "run.forget_requested", runId: loaded.manifest.runId, message: "Run state and artifacts are being forgotten.", data: { force: params.force === true, removedWorktrees: cleanup.removed, preservedWorktrees: cleanup.preserved, intent } });
+	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, intent });
+}
+
+export async function handleCleanup(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
+	const intentError = enforceDestructiveIntent("cleanup", params, ctx.config);
+	if (intentError) return intentError;
+	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 hookReport = await executeHook("before_cleanup", { runId: loaded.manifest.runId, cwd: ctx.cwd });
+	appendHookEvent(loaded.manifest, hookReport);
+	if (hookReport.outcome === "block") {
+		return result(`Cleanup blocked by hook: ${hookReport.reason ?? "before_cleanup hook blocked the operation."}`, { action: "cleanup", status: "error", runId: loaded.manifest.runId }, true);
+	}
+
+	const cleanup = cleanupRunWorktrees(loaded.manifest, { force: params.force, signal: ctx.signal });
+	const intent = intentFromConfig(params.config);
+	appendEvent(loaded.manifest.eventsPath, { type: "worktree.cleanup", runId: loaded.manifest.runId, data: { removed: cleanup.removed, preserved: cleanup.preserved, artifacts: cleanup.artifactPaths, intent } });
+	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, intent });
+}