pi-crew 0.1.39 → 0.1.41

package/src/runtime/group-join.ts

@@ -1,7 +1,7 @@
 import type { CrewRuntimeConfig } from "../config/config.ts";
 import { writeArtifact } from "../state/artifact-store.ts";
 import { appendEvent } from "../state/event-log.ts";
-import { appendMailboxMessage } from "../state/mailbox.ts";
+import { appendMailboxMessage, findMailboxMessageByRequestId, readDeliveryState } from "../state/mailbox.ts";
 import type { ArtifactDescriptor, TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { aggregateTaskOutputs } from "./task-output-context.ts";
 
@@ -18,6 +18,9 @@ export interface CrewGroupJoinDelivery {
 	remaining: string[];
 	artifact?: ArtifactDescriptor;
 	messageId?: string;
+	requestId?: string;
+	ackRequired?: boolean;
+	ackStatus?: "pending" | "acknowledged";
 }
 
 export function resolveGroupJoinMode(runtime?: CrewRuntimeConfig): CrewGroupJoinMode {
@@ -34,6 +37,10 @@ function batchIdFor(runId: string, taskIds: string[]): string {
 	return `${runId}_${taskIds.join("+").replace(/[^a-zA-Z0-9_+-]/g, "_")}`;
 }
 
+function requestIdFor(runId: string, batchId: string, partial: boolean): string {
+	return `${runId}:group-join:${partial ? "partial" : "completed"}:${batchId}`;
+}
+
 function statusList(tasks: TeamTaskState[], status: TeamTaskState["status"]): string[] {
 	return tasks.filter((task) => task.status === status).map((task) => task.id);
 }
@@ -55,7 +62,10 @@ export function deliverGroupJoin(input: {
 	const partial = input.partial ?? remaining.length > 0;
 	const batchId = batchIdFor(input.manifest.runId, taskIds);
 	const summary = aggregateTaskOutputs(latest, input.manifest);
-	const delivery: CrewGroupJoinDelivery = { batchId, mode: input.mode, partial, taskIds, completed, failed, skipped, remaining };
+	const requestId = requestIdFor(input.manifest.runId, batchId, partial);
+	const existingMailbox = findMailboxMessageByRequestId(input.manifest, requestId);
+	const existingStatus = existingMailbox ? readDeliveryState(input.manifest).messages[existingMailbox.id] ?? existingMailbox.status : undefined;
+	const delivery: CrewGroupJoinDelivery = { batchId, mode: input.mode, partial, taskIds, completed, failed, skipped, remaining, requestId, ackRequired: true, ackStatus: existingStatus === "acknowledged" ? "acknowledged" : "pending" };
 	const content = `${JSON.stringify({ ...delivery, createdAt: new Date().toISOString() }, null, 2)}\n`;
 	const artifact = writeArtifact(input.manifest.artifactsRoot, {
 		kind: "metadata",
@@ -63,12 +73,13 @@ export function deliverGroupJoin(input: {
 		producer: "group-join",
 		content,
 	});
-	const mailbox = appendMailboxMessage(input.manifest, {
+	const mailbox = existingMailbox ?? appendMailboxMessage(input.manifest, {
 		direction: "outbox",
 		from: "group-join",
 		to: "leader",
 		body: [
 			`Group join ${partial ? "partial" : "completed"}: ${taskIds.join(", ")}`,
+			`Request: ${requestId}`,
 			`Completed: ${completed.join(", ") || "none"}`,
 			`Failed: ${failed.join(", ") || "none"}`,
 			`Skipped: ${skipped.join(", ") || "none"}`,
@@ -77,12 +88,19 @@ export function deliverGroupJoin(input: {
 			summary,
 		].join("\n"),
 		status: "delivered",
+		data: { kind: "group_join", requestId, batchId, partial, ackRequired: true, taskIds, completed, failed, skipped, remaining },
 	});
 	appendEvent(input.manifest.eventsPath, {
 		type: partial ? "agent.group_join.partial" : "agent.group_join.completed",
 		runId: input.manifest.runId,
 		message: `Group join ${partial ? "partial" : "completed"} for ${taskIds.length} task(s).`,
-		data: { ...delivery, artifactPath: artifact.path, messageId: mailbox.id },
+		data: { ...delivery, artifactPath: artifact.path, messageId: mailbox.id, fallback: "mailbox-delivered", reused: Boolean(existingMailbox) },
+	});
+	if (existingMailbox) appendEvent(input.manifest.eventsPath, {
+		type: "agent.group_join.delivery_reused",
+		runId: input.manifest.runId,
+		message: `Reused group join mailbox delivery for ${taskIds.length} task(s).`,
+		data: { requestId, messageId: mailbox.id, batchId, partial },
 	});
 	return { ...delivery, artifact, messageId: mailbox.id };
 }

package/src/runtime/live-session-runtime.ts

@@ -10,6 +10,7 @@ import { subscribeLiveControlRealtime } from "./live-control-realtime.ts";
 import { eventToSidechainType, sidechainOutputPath, writeSidechainEntry } from "./sidechain-output.ts";
 import type { WorkflowStep } from "../workflows/workflow-config.ts";
 import { isLiveSessionRuntimeAvailable } from "./runtime-resolver.ts";
+import { redactSecrets } from "../utils/redaction.ts";
 
 export interface LiveSessionSpawnInput {
 	manifest: TeamRunManifest;
@@ -25,6 +26,7 @@ export interface LiveSessionSpawnInput {
 	parentContext?: string;
 	parentModel?: unknown;
 	modelRegistry?: unknown;
+	isCurrent?: () => boolean;
 }
 
 export interface LiveSessionRunResult {
@@ -70,7 +72,7 @@ type LiveSessionLike = {
 function appendTranscript(filePath: string | undefined, event: unknown): void {
 	if (!filePath) return;
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
-	fs.appendFileSync(filePath, `${JSON.stringify(event)}\n`, "utf-8");
+	fs.appendFileSync(filePath, `${JSON.stringify(redactSecrets(event))}\n`, "utf-8");
 }
 
 function asRecord(value: unknown): Record<string, unknown> | undefined {
@@ -173,6 +175,7 @@ export async function probeLiveSessionRuntime(): Promise<LiveSessionUnavailableR
 }
 
 export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<LiveSessionRunResult> {
+	const isCurrent = input.isCurrent ?? (() => true);
 	if (process.env.PI_CREW_MOCK_LIVE_SESSION === "success") {
 		const agentId = `${input.manifest.runId}:${input.task.id}`;
 		const inherited = input.runtimeConfig?.inheritContext === true && input.parentContext ? ` with inherited context: ${input.parentContext}` : "";
@@ -183,9 +186,9 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 		const sidechainPath = sidechainOutputPath(input.manifest.stateRoot, input.task.id);
 		writeSidechainEntry(sidechainPath, { agentId, type: "user", message: { role: "user", content: input.prompt }, cwd: input.task.cwd });
 		writeSidechainEntry(sidechainPath, { agentId, type: "message", message: event, cwd: input.task.cwd });
-		input.onEvent?.(event);
+		if (isCurrent()) input.onEvent?.(event);
 		const stdout = `Mock live-session success for ${input.agent.name}${inherited}`;
-		input.onOutput?.(stdout);
+		if (isCurrent()) input.onOutput?.(stdout);
 		updateLiveAgentStatus(agentId, "completed");
 		return { available: true, exitCode: 0, stdout, stderr: "", jsonEvents: 1 };
 	}
@@ -234,7 +237,7 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 		const seenControlRequestIds = new Set<string>();
 		let controlBusy = false;
 		const pollControl = async () => {
-			if (controlBusy || !session) return;
+			if (!isCurrent() || controlBusy || !session) return;
 			controlBusy = true;
 			try {
 				controlCursor = await applyLiveAgentControlRequests({ manifest: input.manifest, taskId: input.task.id, agentId, session, cursor: controlCursor, seenRequestIds: seenControlRequestIds });
@@ -243,11 +246,13 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 			}
 		};
 		unsubscribeControlRealtime = subscribeLiveControlRealtime((request) => {
-			if (request.runId !== input.manifest.runId || request.taskId !== input.task.id || !session) return;
+			if (!isCurrent() || request.runId !== input.manifest.runId || request.taskId !== input.task.id || !session) return;
 			void applyLiveAgentControlRequest({ request, taskId: input.task.id, agentId, session, seenRequestIds: seenControlRequestIds });
 		});
 		await pollControl();
-		controlTimer = setInterval(() => { void pollControl(); }, 500);
+		controlTimer = setInterval(() => {
+			if (isCurrent()) void pollControl();
+		}, 500);
 		let turnCount = 0;
 		let softLimitReached = false;
 		const maxTurns = input.runtimeConfig?.maxTurns;
@@ -256,6 +261,7 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 		writeSidechainEntry(sidechainPath, { agentId, type: "user", message: { role: "user", content: input.prompt }, cwd: input.task.cwd });
 		if (typeof session.subscribe === "function") {
 			unsubscribe = session.subscribe((event) => {
+				if (!isCurrent()) return;
 				jsonEvents += 1;
 				appendTranscript(input.transcriptPath, event);
 				const sidechainType = eventToSidechainType(event);

package/src/runtime/sidechain-output.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { redactSecrets } from "../utils/redaction.ts";
 
 export interface SidechainEntry {
 	isSidechain: true;
@@ -12,7 +13,7 @@ export interface SidechainEntry {
 
 export function writeSidechainEntry(filePath: string, entry: Omit<SidechainEntry, "isSidechain" | "timestamp">): void {
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
-	fs.appendFileSync(filePath, `${JSON.stringify({ isSidechain: true, timestamp: new Date().toISOString(), ...entry })}\n`, "utf-8");
+	fs.appendFileSync(filePath, `${JSON.stringify(redactSecrets({ isSidechain: true, timestamp: new Date().toISOString(), ...entry }))}\n`, "utf-8");
 }
 
 export function sidechainOutputPath(stateRoot: string, taskId: string): string {

package/src/runtime/subagent-manager.ts

@@ -6,6 +6,7 @@ import { DEFAULT_SUBAGENT } from "../config/defaults.ts";
 import { projectCrewRoot } from "../utils/paths.ts";
 import { DEFAULT_PATHS } from "../config/defaults.ts";
 import { logInternalError } from "../utils/internal-error.ts";
+import { redactSecrets } from "../utils/redaction.ts";
 
 export type SubagentStatus = "queued" | "running" | "completed" | "failed" | "cancelled" | "error" | "blocked" | "stopped";
 
@@ -17,6 +18,7 @@ export interface SubagentSpawnOptions {
 	background: boolean;
 	model?: string;
 	maxTurns?: number;
+	ownerSessionGeneration?: number;
 }
 
 export interface SubagentRecord {
@@ -33,6 +35,7 @@ export interface SubagentRecord {
 	resultConsumed?: boolean;
 	model?: string;
 	background: boolean;
+	ownerSessionGeneration?: number;
 	stuckNotified?: boolean;
 	blockedAt?: number;
 	promise?: Promise<void>;
@@ -66,7 +69,7 @@ export function savePersistedSubagentRecord(cwd: string, record: SubagentRecord)
 	try {
 		const filePath = persistedSubagentPath(cwd, record.id);
 		fs.mkdirSync(path.dirname(filePath), { recursive: true });
-		fs.writeFileSync(filePath, `${JSON.stringify(serializableRecord(record), null, 2)}\n`, "utf-8");
+		fs.writeFileSync(filePath, `${JSON.stringify(redactSecrets(serializableRecord(record)), null, 2)}\n`, "utf-8");
 	} catch (error) {
 		logInternalError("subagent-manager.save", error, `id=${record.id}`);
 	}
@@ -136,6 +139,7 @@ export class SubagentManager {
 			startedAt: Date.now(),
 			model: options.model,
 			background: options.background,
+			ownerSessionGeneration: options.ownerSessionGeneration,
 		};
 		this.records.set(record.id, record);
 		this.cwdByRecord.set(record.id, options.cwd);
@@ -373,6 +377,7 @@ export class SubagentManager {
 				id: current.id,
 				runId: current.runId,
 				durationMs: Math.max(0, Date.now() - current.blockedAt),
+				ownerSessionGeneration: current.ownerSessionGeneration,
 			});
 			savePersistedSubagentRecord(cwd, current);
 		};

package/src/runtime/task-runner/live-executor.ts

@@ -24,6 +24,7 @@ export interface RunLiveTaskInput {
 	parentContext?: string;
 	parentModel?: unknown;
 	modelRegistry?: unknown;
+	isCurrent?: () => boolean;
 }
 
 export interface RunLiveTaskOutput {
@@ -65,6 +66,7 @@ export async function runLiveTask(input: RunLiveTaskInput): Promise<RunLiveTaskO
 		}
 	};
 	const attemptStartedAt = new Date();
+	const isCurrent = input.isCurrent ?? (() => input.signal?.aborted !== true);
 	const liveResult = await runLiveSessionTask({
 		manifest,
 		task,
@@ -77,6 +79,7 @@ export async function runLiveTask(input: RunLiveTaskInput): Promise<RunLiveTaskO
 		parentContext: input.parentContext,
 		parentModel: input.parentModel,
 		modelRegistry: input.modelRegistry,
+		isCurrent,
 		onOutput: (text) => appendCrewAgentOutput(manifest, task.id, text),
 		onEvent: (event) => {
 			appendCrewAgentEvent(manifest, task.id, event);

package/src/runtime/task-runner.ts

@@ -25,6 +25,8 @@ import { coordinationBridgeInstructions, renderTaskPrompt } from "./task-runner/
 import { applyAgentProgressEvent, applyUsageToProgress, progressEventSummary, shouldFlushProgressEvent } from "./task-runner/progress.ts";
 import { checkpointTask, persistSingleTaskUpdate, updateTask } from "./task-runner/state-helpers.ts";
 import { cleanResultText, isFinalChildEvent } from "./task-runner/result-utils.ts";
+import { evaluateCompletionMutationGuard } from "./completion-guard.ts";
+import { appendTaskAttentionEvent } from "./attention-events.ts";
 
 export interface TaskRunnerInput {
 	manifest: TeamRunManifest;
@@ -86,6 +88,8 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 	let error: string | undefined;
 	let modelAttempts: ModelAttemptSummary[] | undefined;
 	let parsedOutput: ParsedPiJsonOutput | undefined;
+	let finalStdout = "";
+	let transcriptPath: string | undefined;
 
 	let startupEvidence = createStartupEvidence({ command: runtimeKind === "child-process" ? "pi" : runtimeKind === "live-session" ? "live-session" : "safe-scaffold", startedAt: new Date(task.startedAt ?? new Date().toISOString()), finishedAt: new Date(), promptSentAt: new Date(task.startedAt ?? new Date().toISOString()), promptAccepted: true, exitCode: 0 });
 	const inputsArtifact = writeTaskInputsArtifact(manifest, task, dependencyContext);
@@ -100,10 +104,9 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 		const candidates = modelRoutingPlan.candidates;
 		const attemptModels = candidates.length > 0 ? candidates : [undefined];
 		const logs: string[] = [];
-		let finalStdout = "";
 		let finalStderr = "";
 		modelAttempts = [];
-		const transcriptPath = `${manifest.artifactsRoot}/transcripts/${task.id}.jsonl`;
+		transcriptPath = `${manifest.artifactsRoot}/transcripts/${task.id}.jsonl`;
 		let finalCheckpointWritten = false;
 		let lastAgentRecordPersistedAt = 0;
 		let lastHeartbeatPersistedAt = 0;
@@ -258,6 +261,26 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 		producer: task.id,
 	}) : undefined;
 
+	const mutationGuardMode = input.runtimeConfig?.completionMutationGuard ?? "warn";
+	const mutationGuard = !error && mutationGuardMode !== "off" ? evaluateCompletionMutationGuard({ role: task.role, taskText: `${task.title}\n${input.step.task}`, transcriptPath: runtimeKind === "child-process" ? transcriptPath : transcriptArtifact?.path, stdout: finalStdout }) : undefined;
+	if (mutationGuard?.reason === "no_mutation_observed") {
+		appendTaskAttentionEvent({
+			manifest,
+			taskId: task.id,
+			message: "Implementation-style task completed without an observed mutation tool call.",
+			data: { activityState: "needs_attention", reason: "completion_guard", taskId: task.id, agentName: task.agent, observedTools: mutationGuard.observedTools, suggestedAction: mutationGuardMode === "fail" ? "Review the worker output and rerun with a concrete implementation task." : "Review the worker output; set runtime.completionMutationGuard='fail' to enforce this." },
+		});
+		task = { ...task, agentProgress: { ...(task.agentProgress ?? emptyCrewAgentProgress()), activityState: "needs_attention" } };
+		if (mutationGuardMode === "fail") {
+			error = "Completion mutation guard failed: implementation-style task completed without an observed mutation tool call.";
+			exitCode = exitCode === 0 ? 1 : exitCode;
+			if (modelAttempts?.length) {
+				modelAttempts = modelAttempts.map((attempt, index) => index === modelAttempts!.length - 1 ? { ...attempt, success: false, exitCode, error } : attempt);
+			}
+		}
+		tasks = updateTask(tasks, task);
+	}
+
 	task = {
 		...task,
 		status: error ? "failed" : "completed",

package/src/runtime/team-runner.ts

@@ -24,6 +24,7 @@ import type { MetricRegistry } from "../observability/metric-registry.ts";
 import { childCorrelation, withCorrelation } from "../observability/correlation.ts";
 import { resolveBatchConcurrency } from "./concurrency.ts";
 import { mapConcurrent } from "./parallel-utils.ts";
+import { permissionForRole } from "./role-permission.ts";
 
 export interface ExecuteTeamRunInput {
 	manifest: TeamRunManifest;
@@ -117,8 +118,11 @@ function slug(value: string): string {
 
 function extractAdaptivePlanJson(text: string): string | undefined {
 	const markerMatch = text.match(/ADAPTIVE_PLAN_JSON_START\s*([\s\S]*?)\s*ADAPTIVE_PLAN_JSON_END/);
-	const fencedMatch = markerMatch ? undefined : text.match(/```(?:json)?\s*([\s\S]*?)```/i);
-	return markerMatch?.[1] ?? fencedMatch?.[1];
+	if (markerMatch?.[1]) return markerMatch[1];
+	const startIndex = text.indexOf("ADAPTIVE_PLAN_JSON_START");
+	if (startIndex >= 0) return text.slice(startIndex + "ADAPTIVE_PLAN_JSON_START".length).trim();
+	const fencedMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+	return fencedMatch?.[1];
 }
 
 export function __test__parseAdaptivePlan(text: string, allowedRoles: string[]): AdaptivePlan | undefined {
@@ -178,6 +182,52 @@ function closeUnbalancedJson(raw: string): string {
 	return result;
 }
 
+function salvageCompletePhaseObjects(raw: string): unknown | undefined {
+	const phasesIndex = raw.indexOf('"phases"');
+	if (phasesIndex < 0) return undefined;
+	const arrayStart = raw.indexOf("[", phasesIndex);
+	if (arrayStart < 0) return undefined;
+	const phases: unknown[] = [];
+	let objectStart = -1;
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let index = arrayStart + 1; index < raw.length; index++) {
+		const char = raw[index];
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (char === "\\" && inString) {
+			escaped = true;
+			continue;
+		}
+		if (char === '"') {
+			inString = !inString;
+			continue;
+		}
+		if (inString) continue;
+		if (char === "{") {
+			if (depth === 0) objectStart = index;
+			depth++;
+			continue;
+		}
+		if (char === "}") {
+			if (depth <= 0) continue;
+			depth--;
+			if (depth === 0 && objectStart >= 0) {
+				try {
+					phases.push(JSON.parse(raw.slice(objectStart, index + 1)));
+				} catch {
+					// Ignore malformed trailing phase objects and keep earlier complete phases.
+				}
+				objectStart = -1;
+			}
+		}
+	}
+	return phases.length ? { phases } : undefined;
+}
+
 function adaptiveRoleAlias(role: string, allowed: Set<string>): string | undefined {
 	if (allowed.has(role)) return role;
 	const normalized = slug(role);
@@ -198,6 +248,7 @@ export function __test__repairAdaptivePlan(text: string, allowedRoles: string[])
 	if (!raw) return { repaired: false, reason: "missing-json" };
 	const candidates = [raw, closeUnbalancedJson(raw)];
 	let parsed: unknown;
+	let salvageUsed = false;
 	for (const candidate of candidates) {
 		try {
 			parsed = JSON.parse(candidate);
@@ -206,13 +257,17 @@ export function __test__repairAdaptivePlan(text: string, allowedRoles: string[])
 			// Try the next repair candidate.
 		}
 	}
+	if (!parsed) {
+		parsed = salvageCompletePhaseObjects(raw);
+		salvageUsed = parsed !== undefined;
+	}
 	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { repaired: false, reason: "invalid-json" };
 	const phasesRaw = Array.isArray((parsed as { phases?: unknown }).phases) ? (parsed as { phases: unknown[] }).phases : Array.isArray((parsed as { tasks?: unknown }).tasks) ? [{ name: "adaptive", tasks: (parsed as { tasks: unknown[] }).tasks }] : undefined;
 	if (!phasesRaw) return { repaired: false, reason: "missing-phases" };
 	const allowed = new Set(allowedRoles);
 	const phases: AdaptivePlanPhase[] = [];
 	let total = 0;
-	let repaired = raw !== closeUnbalancedJson(raw);
+	let repaired = salvageUsed || raw !== closeUnbalancedJson(raw);
 	for (const [phaseIndex, phaseRaw] of phasesRaw.entries()) {
 		if (!phaseRaw || typeof phaseRaw !== "object" || Array.isArray(phaseRaw)) continue;
 		const phaseObj = phaseRaw as { name?: unknown; tasks?: unknown };
@@ -398,6 +453,47 @@ function failedTaskFrom(result: { tasks: TeamTaskState[] }, taskId: string): Tea
 	return result.tasks.find((item) => item.id === taskId && item.status === "failed");
 }
 
+function requiresPlanApproval(workflow: WorkflowConfig, runtimeConfig: CrewRuntimeConfig | undefined): boolean {
+	return workflow.name === "implementation" && runtimeConfig?.requirePlanApproval === true;
+}
+
+function isPlanApprovalPending(manifest: TeamRunManifest): boolean {
+	return manifest.planApproval?.required === true && manifest.planApproval.status === "pending";
+}
+
+function isMutatingTask(task: TeamTaskState): boolean {
+	return permissionForRole(task.role) !== "read_only";
+}
+
+function ensurePlanApprovalRequested(manifest: TeamRunManifest, tasks: TeamTaskState[]): TeamRunManifest {
+	if (manifest.planApproval) return manifest;
+	const assessTask = tasks.find((task) => task.stepId === "assess" && task.status === "completed");
+	const now = new Date().toISOString();
+	const updated: TeamRunManifest = {
+		...manifest,
+		updatedAt: now,
+		planApproval: {
+			required: true,
+			status: "pending",
+			requestedAt: now,
+			updatedAt: now,
+			planTaskId: assessTask?.id,
+			planArtifactPath: assessTask?.resultArtifact?.path,
+		},
+	};
+	saveRunManifest(updated);
+	appendEvent(updated.eventsPath, { type: "plan.approval_required", runId: updated.runId, taskId: assessTask?.id, message: "Adaptive implementation plan requires explicit approval before mutating tasks run.", data: { planArtifactPath: assessTask?.resultArtifact?.path } });
+	return updated;
+}
+
+function cancelPlanTasks(tasks: TeamTaskState[], reason: string): TeamTaskState[] {
+	return tasks.map((task) => task.status === "queued" || task.status === "running" ? { ...task, status: "cancelled", finishedAt: new Date().toISOString(), error: reason, graph: task.graph ? { ...task.graph, queue: "done" } : undefined } : task);
+}
+
+function hasPendingMutatingAdaptiveTask(tasks: TeamTaskState[]): boolean {
+	return tasks.some((task) => task.status === "queued" && task.adaptive && isMutatingTask(task));
+}
+
 export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
 	let workflow = input.workflow;
 	let manifest = updateRunStatus(input.manifest, "running", input.executeWorkers ? "Executing team workflow." : "Creating workflow prompts and placeholder results.");
@@ -422,7 +518,18 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 		manifest = updateRunStatus(manifest, "blocked", "Adaptive planner did not produce a valid subagent plan.");
 		return { manifest, tasks };
 	}
-	if (initialAdaptive.injected) queueIndex = buildTaskGraphIndex(tasks);
+	if (initialAdaptive.injected) {
+		manifest = requiresPlanApproval(workflow, input.runtimeConfig) ? ensurePlanApprovalRequested(manifest, tasks) : manifest;
+		queueIndex = buildTaskGraphIndex(tasks);
+	} else if (requiresPlanApproval(workflow, input.runtimeConfig) && hasPendingMutatingAdaptiveTask(tasks)) {
+		manifest = ensurePlanApprovalRequested(manifest, tasks);
+	}
+	if (manifest.planApproval?.status === "cancelled") {
+		tasks = cancelPlanTasks(tasks, "Plan approval was cancelled.");
+		await saveRunTasksAsync(manifest, tasks);
+		manifest = updateRunStatus(manifest, "cancelled", "Plan approval was cancelled.");
+		return { manifest, tasks };
+	}
 	manifest = writeProgress(manifest, tasks, "team-runner");
 	await saveRunManifestAsync(manifest);
 	const runtimeKind = input.runtime?.kind ?? (input.executeWorkers ? "child-process" : "scaffold");
@@ -451,8 +558,16 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 		if (concurrency.reason.includes(";unbounded:")) {
 			appendEvent(manifest.eventsPath, { type: "limits.unbounded", runId: manifest.runId, message: "Unbounded worker concurrency was explicitly enabled for this run.", data: { concurrencyReason: concurrency.reason, maxConcurrent: concurrency.maxConcurrent } });
 		}
-		const readyBatch = getReadyTasks(tasks, concurrency.selectedCount, queueIndex);
+		const approvalPending = isPlanApprovalPending(manifest);
+		const candidateBatch = approvalPending ? getReadyTasks(tasks, tasks.length, queueIndex) : getReadyTasks(tasks, concurrency.selectedCount, queueIndex);
+		const readyBatch = approvalPending ? candidateBatch.filter((task) => !isMutatingTask(task)).slice(0, concurrency.selectedCount) : candidateBatch;
 		if (readyBatch.length === 0) {
+			if (approvalPending && candidateBatch.some(isMutatingTask)) {
+				await saveRunTasksAsync(manifest, tasks);
+				saveCrewAgents(manifest, recordsForMaterializedTasks(manifest, tasks, runtimeKind));
+				manifest = updateRunStatus(manifest, "blocked", "Plan approval required before mutating implementation tasks run.");
+				return { manifest, tasks };
+			}
 			tasks = markBlocked(tasks, "No ready queued task; dependency graph may be invalid.");
 			await saveRunTasksAsync(manifest, tasks);
 			saveCrewAgents(manifest, recordsForMaterializedTasks(manifest, tasks, runtimeKind));
@@ -460,7 +575,7 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 			return { manifest, tasks };
 		}
 
-		appendEvent(manifest.eventsPath, { type: "task.progress", runId: manifest.runId, message: `Starting ready batch with ${readyBatch.length} task(s).`, data: { taskIds: readyBatch.map((task) => task.id), readyCount: snapshot.ready.length, blockedCount: snapshot.blocked.length, runningCount: snapshot.running.length, doneCount: snapshot.done.length, selectedCount: readyBatch.length, maxConcurrent: concurrency.maxConcurrent, defaultConcurrency: concurrency.defaultConcurrency, concurrencyReason: concurrency.reason } });
+		appendEvent(manifest.eventsPath, { type: "task.progress", runId: manifest.runId, message: `Starting ready batch with ${readyBatch.length} task(s).`, data: { taskIds: readyBatch.map((task) => task.id), readyCount: snapshot.ready.length, blockedCount: snapshot.blocked.length, runningCount: snapshot.running.length, doneCount: snapshot.done.length, selectedCount: readyBatch.length, maxConcurrent: concurrency.maxConcurrent, defaultConcurrency: concurrency.defaultConcurrency, concurrencyReason: approvalPending ? `${concurrency.reason};plan-approval-read-only` : concurrency.reason } });
 		const results = await mapConcurrent(
 			readyBatch,
 			concurrency.selectedCount,
@@ -520,7 +635,17 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 			return { manifest, tasks };
 		}
 		if (injectedAfterBatch.injected) {
+			manifest = requiresPlanApproval(workflow, input.runtimeConfig) ? ensurePlanApprovalRequested(manifest, tasks) : manifest;
 			queueIndex = buildTaskGraphIndex(tasks);
+		} else if (requiresPlanApproval(workflow, input.runtimeConfig) && hasPendingMutatingAdaptiveTask(tasks)) {
+			manifest = ensurePlanApprovalRequested(manifest, tasks);
+		}
+		if (manifest.planApproval?.status === "cancelled") {
+			tasks = cancelPlanTasks(tasks, "Plan approval was cancelled.");
+			await saveRunTasksAsync(manifest, tasks);
+			saveCrewAgents(manifest, recordsForMaterializedTasks(manifest, tasks, runtimeKind));
+			manifest = updateRunStatus(manifest, "cancelled", "Plan approval was cancelled.");
+			return { manifest, tasks };
 		}
 		await saveRunTasksAsync(manifest, tasks);
 		saveCrewAgents(manifest, recordsForMaterializedTasks(manifest, tasks, runtimeKind));

package/src/schema/config-schema.ts

@@ -36,6 +36,9 @@ export const PiTeamsRuntimeConfigSchema = Type.Object({
 	inheritContext: Type.Optional(Type.Boolean()),
 	promptMode: Type.Optional(Type.Union([Type.Literal("replace"), Type.Literal("append")])),
 	groupJoin: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("group"), Type.Literal("smart")])),
+	groupJoinAckTimeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
+	requirePlanApproval: Type.Optional(Type.Boolean()),
+	completionMutationGuard: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("warn"), Type.Literal("fail")])),
 }, { additionalProperties: false });
 
 export const PiTeamsControlConfigSchema = Type.Object({

package/src/schema/team-tool-schema.ts

@@ -1,9 +1,18 @@
 import { Type } from "typebox";
 
 const SkillOverride = Type.Unsafe({
-	type: ["string", "array", "boolean"],
-	items: { type: "string" },
 	description: "Skill name(s) to inject, array of skill names, or false to disable role defaults.",
+	anyOf: [
+		{ type: "string" },
+		{ type: "array", items: { type: "string" } },
+		{ type: "boolean" },
+	],
+});
+
+const FreeformConfig = Type.Unsafe({
+	description: "Resource config for management actions.",
+	type: "object",
+	additionalProperties: true,
 });
 
 export const TeamToolParams = Type.Object({
@@ -66,7 +75,7 @@ export const TeamToolParams = Type.Object({
 		Type.Literal("project"),
 		Type.Literal("both"),
 	], { description: "Resource scope for discovery or management." })),
-	config: Type.Optional(Type.Unsafe({ description: "Resource config for management actions." })),
+	config: Type.Optional(FreeformConfig),
 	dryRun: Type.Optional(Type.Boolean({ description: "Preview a management mutation without writing files." })),
 	confirm: Type.Optional(Type.Boolean({ description: "Required for destructive management actions." })),
 	force: Type.Optional(Type.Boolean({ description: "Override reference checks for destructive management actions." })),

package/src/state/artifact-store.ts

@@ -4,6 +4,7 @@ import { createHash } from "node:crypto";
 import type { ArtifactDescriptor } from "./types.ts";
 import { atomicWriteFile } from "./atomic-write.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { redactSecretString } from "../utils/redaction.ts";
 
 function hashContent(content: string): string {
 	return createHash("sha256").update(content).digest("hex");
@@ -108,7 +109,8 @@ export function writeArtifact(artifactsRoot: string, options: ArtifactWriteOptio
 	resolveRealContainedPath(path.dirname(artifactsRoot), path.basename(artifactsRoot));
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	resolveRealContainedPath(artifactsRoot, path.dirname(filePath));
-	atomicWriteFile(filePath, options.content);
+	const content = redactSecretString(options.content);
+	atomicWriteFile(filePath, content);
 	const stats = fs.statSync(filePath);
 	return {
 		kind: options.kind,
@@ -116,7 +118,7 @@ export function writeArtifact(artifactsRoot: string, options: ArtifactWriteOptio
 		createdAt: new Date().toISOString(),
 		producer: options.producer,
 		sizeBytes: stats.size,
-		contentHash: hashContent(options.content),
+		contentHash: hashContent(content),
 		retention: options.retention ?? "run",
 	};
 }

package/src/state/event-log.ts

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import { DEFAULT_EVENT_LOG } from "../config/defaults.ts";
 import { atomicWriteFile } from "./atomic-write.ts";
 import { logInternalError } from "../utils/internal-error.ts";
+import { redactSecrets } from "../utils/redaction.ts";
 
 export type TeamEventProvenance = "live_worker" | "test" | "healthcheck" | "replay" | "api" | "background" | "team_runner";
 export type TeamWatcherAction = "act" | "observe" | "ignore";
@@ -135,7 +136,7 @@ export function appendEvent(eventsPath: string, event: AppendTeamEvent): TeamEve
 	} catch (error) {
 		logInternalError("event-log.size-check", error, `eventsPath=${eventsPath}`);
 	}
-	fs.appendFileSync(eventsPath, `${JSON.stringify(fullEvent)}\n`, "utf-8");
+	fs.appendFileSync(eventsPath, `${JSON.stringify(redactSecrets(fullEvent))}\n`, "utf-8");
 	const seq = fullEvent.metadata?.seq ?? 0;
 	try {
 		const stat = fs.statSync(eventsPath);

package/src/state/jsonl-writer.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { redactJsonLine } from "../utils/redaction.ts";
 
 export interface DrainableSource {
 	pause(): void;
@@ -50,7 +51,8 @@ export function createJsonlWriter(filePath: string | undefined, source: Drainabl
 	return {
 		writeLine(line: string) {
 			if (!stream || closed || !line.trim()) return;
-			const chunk = `${line}\n`;
+			const safeLine = redactJsonLine(line);
+			const chunk = `${safeLine}\n`;
 			const chunkBytes = Buffer.byteLength(chunk, "utf-8");
 			if (bytesWritten + chunkBytes > maxBytes) return;
 			try {