pi-crew 0.1.39 → 0.1.40

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## 0.1.40
+
+### Added
+
+- Added owner-session generation guards for background subagents, async run notifications, result watchers, and live-session callbacks so stale sessions do not receive completions.
+- Added `runtime.requirePlanApproval` with approve/cancel API support to gate mutating adaptive implementation tasks behind an explicit planner artifact approval.
+- Added shared secret redaction for event logs, mailbox persistence, artifacts, JSONL streams, agent records, notifications, metrics, and diagnostics.
+
+### Changed
+
+- Project-local agents, teams, and workflows can no longer shadow builtin or user resources with the same name.
+- Project-level sensitive config such as worker execution, runtime mode, autonomy, agent overrides, worktree setup hooks, and OTLP headers is ignored with warnings unless configured in trusted user scope.
+
+### Fixed
+
+- Fixed lost async completion notifications after auto-compaction/session restart by continuing to track active runs across notifier restarts.
+- Fixed stale background subagent wakeups after session switch/shutdown while preserving terminal results for explicit joins.
+- Fixed resume bypasses in plan approval by re-gating persisted mutating adaptive tasks when approval state is missing or pending.
+- Restricted plan approval and cancellation to non-read-only roles and rejected cancel/approve after the approval state is no longer pending.
+
 ## 0.1.39
 
 ### Fixed

package/README.md

@@ -25,13 +25,14 @@ Current highlights:
 - metadata-aware `recommend` action for routing, decomposition, fanout hints, async/worktree suggestions
 - configurable autonomy profiles: `manual`, `suggested`, `assisted`, `aggressive`
 - builtin agents, teams, and workflows
-- user/project/builtin resource discovery with priority `builtin < user < project`
+- user/project/builtin resource discovery where user resources override builtin resources, and project resources cannot shadow trusted user/builtin names
 - resource format support for routing metadata: `triggers`, `useWhen`, `avoidWhen`, `cost`, `category`
 - durable run state: manifest, tasks, events, artifacts, imports/exports
 - foreground workflow scheduler
 - detached async/background runner
 - stale async PID detection
 - active run summary and async completion notifications in Pi sessions
+- owner-session delivery guards so stale sessions do not receive background subagent/result/live-session completions
 - real child Pi worker execution by default, with explicit scaffold/dry-run opt-out
 - child Pi JSON output parsing for final text, usage, and event counts
 - retryable model fallback attempts per task
@@ -58,6 +59,8 @@ Current highlights:
 - observability metrics: per-session Counter/Gauge/Histogram registry, JSONL sink, `/team-metrics`, dashboard metrics pane, Prometheus/OTLP exporters (OTLP opt-in)
 - reliability hardening: heartbeat gradient watcher, opt-in retry executor with attempt trace, crash-recovery detection, deadletter queue
 - background `Agent`/`crew_agent` completion wake-up so parent sessions can automatically join completed subagent results
+- optional `runtime.requirePlanApproval` gate for planner-first approval before mutating adaptive implementation workers run
+- shared redaction for common secrets before durable event/log/mailbox/artifact/metric/diagnostic persistence
 - package polish: `schema.json`, TypeScript semantic check, strip-types import smoke, cross-platform CI workflow, dry-run package verification
 
 ## Install
@@ -146,9 +149,13 @@ The project root is auto-detected by walking up from the current directory and s
 Config merge priority:
 
 ```text
-user < project
+user < project for ordinary presentation/UX settings
 ```
 
+Trust-boundary exception: project config is intentionally not trusted for sensitive execution controls. Project-level values such as `executeWorkers`, `asyncByDefault`, runtime mode/live-session inheritance, autonomy mode, `agents.disableBuiltins`, `agents.overrides`, `worktree.setupHook`, and `otlp.headers` are ignored with warnings. Set those in user config when you want to trust them explicitly.
+
+Resource discovery trust boundary: project-local agents, teams, and workflows may add new names, but cannot shadow builtin or user resources with the same name.
+
 Supported config:
 
 ```json
@@ -167,6 +174,10 @@ Supported config:
       "review": ["review", "audit", "inspect"]
     }
   },
+  "runtime": {
+    "mode": "auto",
+    "requirePlanApproval": false
+  },
   "limits": {
     "maxConcurrentWorkers": 3,
     "maxTaskDepth": 2,
@@ -222,9 +233,11 @@ Supported config:
 Safety notes:
 
 - Foreground child-process runs continue in the Pi extension process and return control to chat immediately, so large workflows do not block the interactive session. They are interrupted on session shutdown. Use `async: true` only for intentionally detached runs that may survive the current session.
+- Async completion notifications survive extension reload/auto-compaction: active runs are not marked consumed just because the notifier restarts, while stale owner-session callbacks are suppressed after session switches.
 - Background `Agent`/`crew_agent` runs notify the parent session when they reach a terminal state; the parent can then call `get_subagent_result`/`crew_agent_result` and continue the original task.
 - `tools.terminateOnForeground` is an opt-in power-user setting. When true, foreground `Agent`/`crew_agent` calls return with `terminate: true` after the child result is available, saving one follow-up LLM turn. Default is false so the assistant can still summarize raw worker output.
 - Runtime state paths are treated as untrusted data: run ids, import bundles, artifact/transcript paths, mailbox files, and agent control/log files are validated with containment checks before reads or writes.
+- Common secret patterns (`token=`, `apiKey=`, `Authorization: Bearer ...`, private keys, etc.) are redacted before durable logs/events/mailbox/artifacts/metrics/diagnostics are written.
 - `observability.enabled` defaults to true for in-memory metrics and heartbeat watching. Metric JSONL snapshots are gated by `telemetry.enabled`; set `telemetry.enabled=false` to opt out of local telemetry files.
 - `reliability.autoRetry` and `reliability.autoRecover` default to false. Enabling retry may execute an idempotent task more than once; each attempt is recorded in `task.attempts`, and exhausted retries append a deadletter entry.
 - `otlp.enabled` defaults to false. Configure `otlp.endpoint` only when you want to push metrics to an OTLP HTTP collector.
@@ -320,7 +333,7 @@ Supported actions:
 | `config` | Show/update config |
 | `init` | Create project `.pi` layout and update `.gitignore` |
 | `autonomy` | Show/update autonomous delegation settings |
-| `api` | Safe interop for run/task/event/heartbeat/claim/mailbox state |
+| `api` | Safe interop for run/task/event/heartbeat/claim/mailbox state, including plan approval/cancel operations |
 | `help` | Show help text |
 
 ## Example tool calls
@@ -358,6 +371,30 @@ Run with worktrees:
 }
 ```
 
+Require explicit approval after the adaptive planner writes a plan artifact and before mutating workers run:
+
+```json
+{
+  "action": "run",
+  "team": "implementation",
+  "workflow": "implementation",
+  "goal": "Refactor auth and update tests",
+  "config": {
+    "runtime": { "requirePlanApproval": true }
+  }
+}
+```
+
+Approve or cancel the pending plan:
+
+```json
+{
+  "action": "api",
+  "runId": "team_...",
+  "config": { "operation": "approve-plan" }
+}
+```
+
 Inspect a run:
 
 ```json
@@ -438,6 +475,8 @@ Manual slash commands are ops/debug controls. Autonomous tool use via policy/rec
 /team-api team_... ack-message messageId=msg_...
 /team-api team_... read-delivery
 /team-api team_... validate-mailbox repair=true
+/team-api team_... approve-plan
+/team-api team_... cancel-plan
 ```
 
 Use `/team-metrics` for a current metrics snapshot. The optional argument is a glob-style metric filter:

package/package.json

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

package/schema.json

@@ -68,7 +68,8 @@
         "graceTurns": { "type": "integer", "minimum": 1 },
         "inheritContext": { "type": "boolean" },
         "promptMode": { "type": "string", "enum": ["replace", "append"] },
-        "groupJoin": { "type": "string", "enum": ["off", "group", "smart"] }
+        "groupJoin": { "type": "string", "enum": ["off", "group", "smart"] },
+        "requirePlanApproval": { "type": "boolean" }
       }
     },
     "control": {

package/src/agents/discover-agents.ts

@@ -95,7 +95,7 @@ export function discoverAgents(cwd: string): AgentDiscoveryResult {
 
 export function allAgents(discovery: AgentDiscoveryResult): AgentConfig[] {
 	const byName = new Map<string, AgentConfig>();
-	for (const agent of [...discovery.builtin, ...discovery.user, ...discovery.project]) {
+	for (const agent of [...discovery.project, ...discovery.builtin, ...discovery.user]) {
 		byName.set(agent.name.toLowerCase(), agent);
 	}
 	return [...byName.values()].filter((agent) => !agent.disabled).sort((a, b) => a.name.localeCompare(b.name));

package/src/config/config.ts

@@ -39,6 +39,7 @@ export interface CrewRuntimeConfig {
 	inheritContext?: boolean;
 	promptMode?: "replace" | "append";
 	groupJoin?: "off" | "group" | "smart";
+	requirePlanApproval?: boolean;
 }
 
 export interface CrewControlConfig {
@@ -206,6 +207,82 @@ function validateConfigWithWarnings(raw: unknown): string[] {
 	return [];
 }
 
+function projectOverrideWarning(projectPath: string, dottedPath: string): string {
+	return `${projectPath}: project-level sensitive config '${dottedPath}' is ignored; set it in user config to trust it explicitly`;
+}
+
+function sanitizeProjectConfig(projectPath: string, userConfig: PiTeamsConfig, config: PiTeamsConfig): ConfigValidationResult {
+	const sanitized: PiTeamsConfig = { ...config };
+	const warnings: string[] = [];
+	const dropTopLevel = (key: keyof PiTeamsConfig): void => {
+		if (config[key] === undefined) return;
+		delete sanitized[key];
+		warnings.push(projectOverrideWarning(projectPath, String(key)));
+	};
+	dropTopLevel("executeWorkers");
+	dropTopLevel("asyncByDefault");
+	dropTopLevel("requireCleanWorktreeLeader");
+	if (config.runtime) {
+		const runtime = { ...config.runtime };
+		for (const key of ["mode", "preferLiveSession", "allowChildProcessFallback", "inheritContext"] as const) {
+			if (runtime[key] !== undefined) {
+				delete runtime[key];
+				warnings.push(projectOverrideWarning(projectPath, `runtime.${key}`));
+			}
+		}
+		if (runtime.requirePlanApproval === false) {
+			delete runtime.requirePlanApproval;
+			warnings.push(projectOverrideWarning(projectPath, "runtime.requirePlanApproval"));
+		}
+		sanitized.runtime = Object.values(runtime).some((entry) => entry !== undefined) ? runtime : undefined;
+	}
+	if (config.autonomous) {
+		const autonomous = { ...config.autonomous };
+		for (const key of ["profile", "enabled", "injectPolicy", "preferAsyncForLongTasks", "allowWorktreeSuggestion"] as const) {
+			if (autonomous[key] !== undefined) {
+				delete autonomous[key];
+				warnings.push(projectOverrideWarning(projectPath, `autonomous.${key}`));
+			}
+		}
+		sanitized.autonomous = Object.values(autonomous).some((entry) => entry !== undefined) ? autonomous : undefined;
+	}
+	if (config.worktree?.setupHook !== undefined) {
+		sanitized.worktree = { ...config.worktree, setupHook: undefined };
+		if (!Object.values(sanitized.worktree).some((entry) => entry !== undefined)) sanitized.worktree = undefined;
+		warnings.push(projectOverrideWarning(projectPath, "worktree.setupHook"));
+	}
+	if (config.otlp?.headers !== undefined) {
+		sanitized.otlp = { ...config.otlp, headers: undefined };
+		if (!Object.values(sanitized.otlp).some((entry) => entry !== undefined)) sanitized.otlp = undefined;
+		warnings.push(projectOverrideWarning(projectPath, "otlp.headers"));
+	}
+	if (config.agents?.disableBuiltins !== undefined || config.agents?.overrides !== undefined) {
+		const agents = { ...config.agents };
+		if (agents.disableBuiltins !== undefined) {
+			delete agents.disableBuiltins;
+			warnings.push(projectOverrideWarning(projectPath, "agents.disableBuiltins"));
+		}
+		if (agents.overrides !== undefined) {
+			delete agents.overrides;
+			warnings.push(projectOverrideWarning(projectPath, "agents.overrides"));
+		}
+		sanitized.agents = Object.values(agents).some((entry) => entry !== undefined) ? agents : undefined;
+	}
+	if (config.tools?.enableSteer !== undefined || config.tools?.terminateOnForeground !== undefined) {
+		const tools = { ...config.tools };
+		if (tools.enableSteer !== undefined) {
+			delete tools.enableSteer;
+			warnings.push(projectOverrideWarning(projectPath, "tools.enableSteer"));
+		}
+		if (tools.terminateOnForeground !== undefined) {
+			delete tools.terminateOnForeground;
+			warnings.push(projectOverrideWarning(projectPath, "tools.terminateOnForeground"));
+		}
+		sanitized.tools = Object.values(tools).some((entry) => entry !== undefined) ? tools : undefined;
+	}
+	return { config: sanitized, warnings };
+}
+
 function mergeConfig(base: PiTeamsConfig, override: PiTeamsConfig): PiTeamsConfig {
 	const merged: PiTeamsConfig = { ...base, ...withoutUndefined(override as Record<string, unknown>) };
 	if (base.autonomous || override.autonomous) {
@@ -416,6 +493,7 @@ function parseRuntimeConfig(value: unknown): CrewRuntimeConfig | undefined {
 		inheritContext: parseWithSchema(Type.Boolean(), obj.inheritContext),
 		promptMode: parseWithSchema(Type.Union([Type.Literal("replace"), Type.Literal("append")]), obj.promptMode),
 		groupJoin: parseWithSchema(Type.Union([Type.Literal("off"), Type.Literal("group"), Type.Literal("smart")]), obj.groupJoin),
+		requirePlanApproval: parseWithSchema(Type.Boolean(), obj.requirePlanApproval),
 	};
 	return Object.values(runtime).some((entry) => entry !== undefined) ? runtime : undefined;
 }
@@ -639,8 +717,9 @@ export function loadConfig(cwd?: string): LoadedPiTeamsConfig {
 		if (cwd) {
 			const projectPath = projectConfigPath(cwd);
 			const projectConfig = parseConfigWithWarnings(readConfigRecord(projectPath));
-			warnings.push(...projectConfig.warnings.map((warning) => `${projectPath}: ${warning}`));
-			config = mergeConfig(config, projectConfig.config);
+			const projectSafeConfig = sanitizeProjectConfig(projectPath, config, projectConfig.config);
+			warnings.push(...projectConfig.warnings.map((warning) => `${projectPath}: ${warning}`), ...projectSafeConfig.warnings);
+			config = mergeConfig(config, projectSafeConfig.config);
 		}
 		return { path: filePath, paths, config, warnings: warnings.length > 0 ? warnings : undefined };
 	} catch (error) {

package/src/extension/async-notifier.ts

@@ -8,6 +8,13 @@ import { listRuns } from "./run-index.ts";
 export interface AsyncNotifierState {
 	seenFinishedRunIds: Set<string>;
 	interval?: ReturnType<typeof setInterval>;
+	generation?: number;
+	lastStoppedAtMs?: number;
+}
+
+export interface AsyncNotifierOptions {
+	generation?: number;
+	isCurrent?: (generation: number) => boolean;
 }
 
 function isFinished(status: string): boolean {
@@ -18,6 +25,12 @@ function isAsyncTerminalEvent(event: TeamEvent): boolean {
 	return event.type === "async.completed" || event.type === "async.failed" || event.type === "async.died";
 }
 
+function timeMs(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const parsed = new Date(value).getTime();
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
 function latestEventAgeMs(events: TeamEvent[], now = Date.now()): number {
 	const latest = events.at(-1);
 	if (!latest) return Number.POSITIVE_INFINITY;
@@ -38,14 +51,21 @@ export function markDeadAsyncRunIfNeeded(run: TeamRunManifest, now = Date.now(),
 	return failed;
 }
 
-export function startAsyncRunNotifier(ctx: ExtensionContext, state: AsyncNotifierState, intervalMs = 5000): void {
+export function startAsyncRunNotifier(ctx: ExtensionContext, state: AsyncNotifierState, intervalMs = 5000, options: AsyncNotifierOptions = {}): void {
 	if (state.interval) clearInterval(state.interval);
+	const generation = options.generation ?? ((state.generation ?? 0) + 1);
+	state.generation = generation;
+	const startedAtMs = Date.now();
+	const staleBeforeMs = state.lastStoppedAtMs ?? startedAtMs;
 	for (const run of listRuns(ctx.cwd)) {
-		// Treat all pre-existing runs as seen. This avoids noisy error toasts when
-		// an old active/stale run is later inspected and transitions to failed.
-		state.seenFinishedRunIds.add(run.runId);
+		// Suppress only terminal runs that were already finished before this owner
+		// session (or before the previous session switch). Active runs must remain
+		// un-seen so completions during auto-compaction/session restart are delivered.
+		const updatedAtMs = timeMs(run.updatedAt) ?? 0;
+		if (isFinished(run.status) && updatedAtMs < staleBeforeMs) state.seenFinishedRunIds.add(run.runId);
 	}
 	state.interval = setInterval(() => {
+		if (options.isCurrent && !options.isCurrent(generation)) return;
 		try {
 			for (const run of listRuns(ctx.cwd).slice(0, 20)) {
 				const current = markDeadAsyncRunIfNeeded(run) ?? run;
@@ -64,4 +84,6 @@ export function startAsyncRunNotifier(ctx: ExtensionContext, state: AsyncNotifie
 export function stopAsyncRunNotifier(state: AsyncNotifierState): void {
 	if (state.interval) clearInterval(state.interval);
 	state.interval = undefined;
+	state.generation = (state.generation ?? 0) + 1;
+	state.lastStoppedAtMs = Date.now();
 }

package/src/extension/notification-sink.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { NotificationDescriptor } from "./notification-router.ts";
-import { redactSecrets } from "../runtime/diagnostic-export.ts";
+import { redactSecrets } from "../utils/redaction.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 
 export interface NotificationSink {

package/src/extension/register.ts

@@ -53,6 +53,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	}
 	const notifierState: AsyncNotifierState = { seenFinishedRunIds: new Set() };
 	let currentCtx: ExtensionContext | undefined;
+	let sessionGeneration = 0;
 	let rpcHandle: PiCrewRpcHandle | undefined;
 	let cleanedUp = false;
 	let manifestCache = createManifestCache(process.cwd());
@@ -153,6 +154,9 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 			sendFollowUp(pi, [notification.title, notification.body].filter((line): line is string => Boolean(line)).join("\n"));
 		}
 	};
+	const captureSessionGeneration = (): number => sessionGeneration;
+	const isOwnerSessionCurrent = (ownerGeneration: number | undefined): boolean => !cleanedUp && (ownerGeneration === undefined || ownerGeneration === sessionGeneration);
+	const isContextCurrent = (ctx: ExtensionContext, ownerGeneration: number): boolean => !cleanedUp && currentCtx === ctx && sessionGeneration === ownerGeneration;
 	const subagentManager = new SubagentManager(
 		4,
 		(record) => {
@@ -170,6 +174,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 				});
 			}
 			if (!record.background || record.resultConsumed) return;
+			if (!isOwnerSessionCurrent(record.ownerSessionGeneration)) return;
 			if (record.status === "completed" || record.status === "failed" || record.status === "cancelled" || record.status === "blocked" || record.status === "error") {
 				const metadata = JSON.stringify({ id: record.id, status: record.status, type: record.type, runId: record.runId, description: record.description }, null, 2);
 				const joinInstruction = [
@@ -186,6 +191,8 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		},
 		1000,
 		(event, payload) => {
+			const ownerGeneration = typeof payload.ownerSessionGeneration === "number" ? payload.ownerSessionGeneration : undefined;
+			if (ownerGeneration !== undefined && !isOwnerSessionCurrent(ownerGeneration)) return;
 			if (event === "subagent.stuck-blocked") {
 				const id = typeof payload.id === "string" ? payload.id : "unknown";
 				const runId = typeof payload.runId === "string" ? payload.runId : "unknown";
@@ -233,6 +240,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		});
 	};
 	const startForegroundRun = (ctx: ExtensionContext, runner: (signal?: AbortSignal) => Promise<void>, runId?: string): void => {
+		const ownerGeneration = captureSessionGeneration();
 		const controller = new AbortController();
 		foregroundControllers.add(controller);
 		if (ctx.hasUI) {
@@ -251,15 +259,16 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 							logInternalError("register.foreground-run-failure", statusError, `runId=${runId}`);
 						}
 					}
-					ctx.ui.notify(`pi-crew foreground run failed: ${message}`, "error");
+					if (isContextCurrent(ctx, ownerGeneration)) ctx.ui.notify(`pi-crew foreground run failed: ${message}`, "error");
 				})
 				.finally(() => {
 					foregroundControllers.delete(controller);
-					if (ctx.hasUI) {
+					const ownerCurrent = isContextCurrent(ctx, ownerGeneration);
+					if (ownerCurrent && ctx.hasUI) {
 						setWorkingIndicator(ctx);
 						ctx.ui.setWorkingMessage();
 					}
-					if (runId) {
+					if (ownerCurrent && runId) {
 						const loaded = loadRunManifestById(ctx.cwd, runId);
 						const status = loaded?.manifest.status ?? "finished";
 						const level = status === "failed" || status === "blocked" ? "error" : status === "cancelled" ? "warning" : "info";
@@ -287,7 +296,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 							});
 						}
 					}
-					if (currentCtx) {
+					if (ownerCurrent && currentCtx) {
 						const config = loadConfig(currentCtx.cwd).config.ui;
 						updateCrewWidget(currentCtx, widgetState, config, getManifestCache(currentCtx.cwd), getRunSnapshotCache(currentCtx.cwd));
 						updatePiCrewPowerbar(pi.events, currentCtx.cwd, config, getManifestCache(currentCtx.cwd), getRunSnapshotCache(currentCtx.cwd), currentCtx, widgetState.notificationCount ?? 0);
@@ -328,6 +337,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		notificationSink = undefined;
 		rpcHandle?.unsubscribe();
 		rpcHandle = undefined;
+		sessionGeneration += 1;
 		currentCtx = undefined;
 		if (globalStore[runtimeCleanupStoreKey] === cleanupRuntime) delete globalStore[runtimeCleanupStoreKey];
 	};
@@ -337,6 +347,8 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		runArtifactCleanup(ctx.cwd);
 		time("register.session-start");
 		cleanedUp = false;
+		sessionGeneration++;
+		const ownerGeneration = sessionGeneration;
 		currentCtx = ctx;
 		if (widgetState.interval) clearInterval(widgetState.interval);
 		widgetState.interval = undefined;
@@ -346,7 +358,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		configureNotifications(ctx);
 		configureObservability(ctx);
 		registerPiCrewPowerbarSegments(pi.events, loadedConfig.config.ui);
-		startAsyncRunNotifier(ctx, notifierState, loadedConfig.config.notifierIntervalMs ?? DEFAULT_UI.notifierIntervalMs);
+		startAsyncRunNotifier(ctx, notifierState, loadedConfig.config.notifierIntervalMs ?? DEFAULT_UI.notifierIntervalMs, { generation: ownerGeneration, isCurrent: (generation) => generation === sessionGeneration && currentCtx === ctx && !cleanedUp });
 		const cache = getManifestCache(ctx.cwd);
 		updateCrewWidget(ctx, widgetState, loadedConfig.config.ui, cache, getRunSnapshotCache(ctx.cwd));
 		updatePiCrewPowerbar(pi.events, ctx.cwd, loadedConfig.config.ui, cache, getRunSnapshotCache(ctx.cwd), ctx, widgetState.notificationCount ?? 0);
@@ -395,7 +407,11 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 			onInvalidate: () => getRunSnapshotCache(ctx.cwd).invalidate(),
 		});
 	});
-	pi.on("session_before_switch", () => stopSessionBoundSubagents());
+	pi.on("session_before_switch", () => {
+		sessionGeneration++;
+		stopAsyncRunNotifier(notifierState);
+		stopSessionBoundSubagents();
+	});
 	pi.on("session_shutdown", () => cleanupRuntime());
 
 	registerCompactionGuard(pi, { foregroundControllers });
@@ -417,7 +433,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 	});
 
 	registerTeamTool(pi, { foregroundControllers, startForegroundRun, openLiveSidebar, getManifestCache, getRunSnapshotCache, getMetricRegistry: () => metricRegistry, widgetState });
-	registerSubagentTools(pi, subagentManager);
+	registerSubagentTools(pi, subagentManager, { ownerSessionGeneration: captureSessionGeneration });
 	time("register.tools");
 
 	registerTeamCommands(pi, { startForegroundRun, openLiveSidebar, getManifestCache, getRunSnapshotCache, getMetricRegistry: () => metricRegistry, dismissNotifications: () => {

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

@@ -8,7 +8,11 @@ import { loadConfig } from "../../config/config.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 {
+export interface SubagentToolRegistrationOptions {
+	ownerSessionGeneration?: () => number;
+}
+
+export function registerSubagentTools(pi: ExtensionAPI, subagentManager: SubagentManager, options: SubagentToolRegistrationOptions = {}): void {
 	const agentTool: ToolDefinition = {
 		name: "Agent",
 		label: "Agent",
@@ -31,11 +35,12 @@ export function registerSubagentTools(pi: ExtensionAPI, subagentManager: Subagen
 			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") {
+			const spawnOptions = __test__subagentSpawnParams(params as Record<string, unknown>, ctx);
+			spawnOptions.ownerSessionGeneration = options.ownerSessionGeneration?.();
+			if (!spawnOptions.prompt.trim()) return subagentToolResult("Agent requires prompt.", {}, true);
+			const runner = async (currentOptions: SubagentSpawnOptions, childSignal?: AbortSignal) => handleTeamTool({ action: "run", agent: currentOptions.type, goal: currentOptions.prompt, model: currentOptions.model, async: currentOptions.background, config: currentOptions.maxTurns ? { runtime: { maxTurns: currentOptions.maxTurns } } : undefined } as TeamToolParamsValue, currentOptions.background ? { ...ctx, signal: childSignal } : { ...ctx, signal: childSignal });
+			const record = subagentManager.spawn(spawnOptions, runner, spawnOptions.background ? undefined : signal);
+			if (spawnOptions.background || record.status === "queued") {
 				// Phase 1.1a: Terminate turn for background queued — no LLM follow-up needed.
 				// Phase 1.6: Record was terminated for telemetry.
 				record.terminated = true;

package/src/extension/result-watcher.ts

@@ -22,6 +22,7 @@ interface ResultWatcherDependencies {
 export interface ResultWatcherOptions extends ResultWatcherDependencies {
 	eventName?: string;
 	completionTtlMs?: number;
+	isCurrent?: () => boolean;
 }
 
 const RESULT_WATCHER_RESTART_MS = 3000;
@@ -40,10 +41,12 @@ export function createResultWatcher(events: ResultWatcherEvents, resultsDir: str
 	const eventName = options.eventName ?? "pi-crew:run-result";
 	const completionTtlMs = options.completionTtlMs ?? 5 * 60_000;
 	const watch = options.watch ?? watchWithErrorHandler;
+	const isCurrent = options.isCurrent ?? (() => true);
 	const seen = getGlobalSeenMap("pi-crew.result-watcher");
 	let watcher: fs.FSWatcher | null | undefined;
 	let restartTimer: ReturnType<typeof setTimeout> | undefined;
 	const coalescer = createFileCoalescer((file) => {
+		if (!isCurrent()) return;
 		const filePath = path.join(resultsDir, file);
 		if (!file.endsWith(".json") || !fs.existsSync(filePath)) return;
 		const payload = readJson(filePath);
@@ -64,6 +67,7 @@ export function createResultWatcher(events: ResultWatcherEvents, resultsDir: str
 		restartTimer = setTimeout(() => {
 			restartTimer = undefined;
 			try {
+				if (!isCurrent()) return;
 				fs.mkdirSync(resultsDir, { recursive: true });
 				handle.start();
 			} catch (error) {
@@ -74,6 +78,7 @@ export function createResultWatcher(events: ResultWatcherEvents, resultsDir: str
 	};
 	const handle: ResultWatcherHandle = {
 		start() {
+			if (!isCurrent()) return;
 			fs.mkdirSync(resultsDir, { recursive: true });
 			if (watcher) closeWatcher(watcher);
 			watcher = watch(resultsDir, (event, fileName) => {
@@ -83,7 +88,7 @@ export function createResultWatcher(events: ResultWatcherEvents, resultsDir: str
 			watcher?.unref?.();
 		},
 		prime() {
-			if (!fs.existsSync(resultsDir)) return;
+			if (!isCurrent() || !fs.existsSync(resultsDir)) return;
 			for (const file of fs.readdirSync(resultsDir).filter((entry) => entry.endsWith(".json"))) coalescer.schedule(file, 0);
 		},
 		stop() {

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

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import { loadConfig } from "../../config/config.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import { saveRunTasks, loadRunManifestById } from "../../state/state-store.ts";
+import { loadRunManifestById, saveRunManifest, saveRunTasks, updateRunStatus } from "../../state/state-store.ts";
 import { withRunLockSync } from "../../state/locks.ts";
 import { canTransitionTaskStatus, isTeamTaskStatus } from "../../state/contracts.ts";
 import { claimTask, releaseTaskClaim, transitionClaimedTaskStatus } from "../../state/task-claims.ts";
@@ -9,6 +9,7 @@ import { acknowledgeMailboxMessage, appendMailboxMessage, readDeliveryState, rea
 import { appendEvent, readEvents, readEventsCursor } from "../../state/event-log.ts";
 import { resolveCrewRuntime } from "../../runtime/runtime-resolver.ts";
 import { probeLiveSessionRuntime } from "../../subagents/live/session-runtime.ts";
+import { currentCrewRole, permissionForRole } from "../../runtime/role-permission.ts";
 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";
@@ -54,6 +55,13 @@ function snapshotHasRunId(snapshot: { values?: unknown }, runId: string): boolea
 	});
 }
 
+function canApprovePlan(): { allowed: boolean; reason?: string } {
+	const role = currentCrewRole();
+	if (!role) return { allowed: true };
+	if (permissionForRole(role) === "read_only") return { allowed: false, reason: `Role '${role}' is read-only and cannot approve or cancel plan gates.` };
+	return { allowed: true };
+}
+
 export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
 	const cfg = configRecord(params.config);
 	const operation = typeof cfg.operation === "string" ? cfg.operation : "read-manifest";
@@ -74,6 +82,47 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 	if (operation === "read-manifest") {
 		return result(JSON.stringify(loaded.manifest, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 	}
+	if (operation === "approve-plan") {
+		const permission = canApprovePlan();
+		if (!permission.allowed) return result(permission.reason ?? "Plan approval is not allowed in this context.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		try {
+			return withRunLockSync(loaded.manifest, () => {
+				const current = loadRunManifestById(ctx.cwd, loaded.manifest.runId) ?? loaded;
+				const approval = current.manifest.planApproval;
+				if (!approval?.required || approval.status !== "pending") return result("Run has no pending plan approval request.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+				const now = new Date().toISOString();
+				const manifest = { ...current.manifest, updatedAt: now, planApproval: { ...approval, status: "approved" as const, approvedAt: now, updatedAt: now } };
+				saveRunManifest(manifest);
+				appendEvent(manifest.eventsPath, { type: "plan.approved", runId: manifest.runId, taskId: approval.planTaskId, message: "Adaptive implementation plan approved; resume the run to execute mutating tasks.", metadata: { provenance: "api" } });
+				return result(JSON.stringify(manifest.planApproval, null, 2), { action: "api", status: "ok", runId: manifest.runId, artifactsRoot: 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);
+		}
+	}
+	if (operation === "cancel-plan") {
+		const permission = canApprovePlan();
+		if (!permission.allowed) return result(permission.reason ?? "Plan approval cancellation is not allowed in this context.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+		try {
+			return withRunLockSync(loaded.manifest, () => {
+				const current = loadRunManifestById(ctx.cwd, loaded.manifest.runId) ?? loaded;
+				const approval = current.manifest.planApproval;
+				if (!approval?.required || approval.status !== "pending") return result("Run has no pending plan approval request.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+				const now = new Date().toISOString();
+				const tasks = current.tasks.map((task) => task.status === "queued" || task.status === "running" ? { ...task, status: "cancelled" as const, finishedAt: now, error: "Plan approval was cancelled." } : task);
+				let manifest: typeof current.manifest = { ...current.manifest, updatedAt: now, planApproval: { ...approval, status: "cancelled" as const, cancelledAt: now, updatedAt: now } };
+				saveRunManifest(manifest);
+				saveRunTasks(manifest, tasks);
+				appendEvent(manifest.eventsPath, { type: "plan.cancelled", runId: manifest.runId, taskId: approval.planTaskId, message: "Adaptive implementation plan was cancelled.", metadata: { provenance: "api" } });
+				manifest = updateRunStatus(manifest, "cancelled", "Plan approval was cancelled.");
+				return result(JSON.stringify({ planApproval: manifest.planApproval, cancelledTasks: tasks.filter((task) => task.status === "cancelled").map((task) => task.id) }, null, 2), { action: "api", status: "ok", runId: manifest.runId, artifactsRoot: 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);
+		}
+	}
 	if (operation === "list-tasks") {
 		return result(JSON.stringify(loaded.tasks, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 	}

package/src/observability/metric-sink.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { redactSecrets } from "../runtime/diagnostic-export.ts";
+import { redactSecrets } from "../utils/redaction.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import type { MetricRegistry } from "./metric-registry.ts";
 import type { MetricSnapshot } from "./metrics-primitives.ts";

package/src/runtime/child-pi.ts

@@ -7,6 +7,7 @@ import { getPiSpawnCommand } from "./pi-spawn.ts";
 import { DEFAULT_CHILD_PI } from "../config/defaults.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "./post-exit-stdio-guard.ts";
+import { redactJsonLine } from "../utils/redaction.ts";
 
 const POST_EXIT_STDIO_GUARD_MS = DEFAULT_CHILD_PI.postExitStdioGuardMs;
 const FINAL_DRAIN_MS = DEFAULT_CHILD_PI.finalDrainMs;
@@ -118,7 +119,7 @@ export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): S
 function appendTranscript(input: ChildPiRunInput, line: string): void {
 	if (!input.transcriptPath) return;
 	fs.mkdirSync(path.dirname(input.transcriptPath), { recursive: true });
-	fs.appendFileSync(input.transcriptPath, `${line}\n`, "utf-8");
+	fs.appendFileSync(input.transcriptPath, `${redactJsonLine(line)}\n`, "utf-8");
 }
 
 function compactString(value: string, maxChars = MAX_COMPACT_CONTENT_CHARS): string {

package/src/runtime/crew-agent-records.ts

@@ -7,6 +7,7 @@ import type { CrewAgentProgress, CrewAgentRecord, CrewRuntimeKind } from "./crew
 import { taskStatusToAgentStatus } from "./crew-agent-runtime.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { assertSafePathId, resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { redactSecretString, redactSecrets } from "../utils/redaction.ts";
 
 export function agentsPath(manifest: TeamRunManifest): string {
 	return path.join(manifest.stateRoot, "agents.json");
@@ -71,7 +72,7 @@ export function readCrewAgents(manifest: TeamRunManifest): CrewAgentRecord[] {
 
 export function saveCrewAgents(manifest: TeamRunManifest, records: CrewAgentRecord[]): void {
 	fs.mkdirSync(manifest.stateRoot, { recursive: true });
-	atomicWriteJson(agentsPath(manifest), records);
+	atomicWriteJson(agentsPath(manifest), redactSecrets(records));
 	for (const record of records) writeCrewAgentStatus(manifest, record);
 }
 
@@ -84,7 +85,7 @@ export function upsertCrewAgent(manifest: TeamRunManifest, record: CrewAgentReco
 
 export function writeCrewAgentStatus(manifest: TeamRunManifest, record: CrewAgentRecord): void {
 	ensureAgentStateDir(manifest, record.taskId);
-	atomicWriteJson(agentStatusPath(manifest, record.taskId), record);
+	atomicWriteJson(agentStatusPath(manifest, record.taskId), redactSecrets(record));
 }
 
 export function readCrewAgentStatus(manifest: TeamRunManifest, taskOrAgentId: string): CrewAgentRecord | undefined {
@@ -121,7 +122,7 @@ export function appendCrewAgentEvent(manifest: TeamRunManifest, taskId: string,
 	ensureAgentStateDir(manifest, taskId);
 	const filePath = agentStateFile(manifest, taskId, "events.jsonl");
 	const seq = nextAgentEventSeq(filePath);
-	fs.appendFileSync(filePath, `${JSON.stringify({ seq, time: new Date().toISOString(), event })}\n`, "utf-8");
+	fs.appendFileSync(filePath, `${JSON.stringify(redactSecrets({ seq, time: new Date().toISOString(), event }))}\n`, "utf-8");
 	try {
 		const stat = fs.statSync(filePath);
 		agentEventSeqCache.set(filePath, { size: stat.size, mtimeMs: stat.mtimeMs, seq });
@@ -172,7 +173,7 @@ export function readCrewAgentEventsCursor(manifest: TeamRunManifest, taskId: str
 export function appendCrewAgentOutput(manifest: TeamRunManifest, taskId: string, text: string): void {
 	if (!text.trim()) return;
 	ensureAgentStateDir(manifest, taskId);
-	fs.appendFileSync(agentStateFile(manifest, taskId, "output.log"), `${text}\n`, "utf-8");
+	fs.appendFileSync(agentStateFile(manifest, taskId, "output.log"), `${redactSecretString(text)}\n`, "utf-8");
 }
 
 export function emptyCrewAgentProgress(): CrewAgentProgress {

package/src/runtime/diagnostic-export.ts

@@ -9,6 +9,8 @@ import { loadRunManifestById } from "../state/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { summarizeHeartbeats, type HeartbeatSummary } from "../ui/heartbeat-aggregator.ts";
 import type { RunUiSnapshot } from "../ui/snapshot-types.ts";
+import { redactSecrets } from "../utils/redaction.ts";
+export { redactSecrets } from "../utils/redaction.ts";
 
 export interface DiagnosticReport {
 	schemaVersion?: number;
@@ -25,22 +27,6 @@ export interface DiagnosticReport {
 
 const SECRET_KEY_PATTERN = /(token|key|password|secret|credential|auth)/i;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-export function redactSecrets(value: unknown, keyName = ""): unknown {
-	if (SECRET_KEY_PATTERN.test(keyName)) return "***";
-	if (typeof value === "string") return value.replace(/((?:token|key|password|secret|credential|auth)[\w.-]*\s*[=:]\s*)[^\s,;]+/gi, "$1***");
-	if (Array.isArray(value)) return value.map((item) => redactSecrets(item));
-	if (isRecord(value)) {
-		const output: Record<string, unknown> = {};
-		for (const [key, entry] of Object.entries(value)) output[key] = redactSecrets(entry, key);
-		return output;
-	}
-	return value;
-}
-
 function envRedacted(): Record<string, string> {
 	const output: Record<string, string> = {};
 	for (const [key, value] of Object.entries(process.env)) {

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/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;
@@ -398,6 +399,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 +464,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 +504,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 +521,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 +581,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,7 @@ 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")])),
+	requirePlanApproval: Type.Optional(Type.Boolean()),
 }, { additionalProperties: false });
 
 export const PiTeamsControlConfigSchema = Type.Object({

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 {

package/src/state/mailbox.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { TeamRunManifest } from "./types.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { redactSecrets } from "../utils/redaction.ts";
 
 export type MailboxDirection = "inbox" | "outbox";
 export type MailboxMessageStatus = "queued" | "delivered" | "acknowledged";
@@ -190,7 +191,7 @@ export function readDeliveryState(manifest: TeamRunManifest): MailboxDeliverySta
 
 function writeDeliveryState(manifest: TeamRunManifest, state: MailboxDeliveryState): void {
 	ensureRunMailbox(manifest);
-	fs.writeFileSync(deliveryFile(manifest, true), `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+	fs.writeFileSync(deliveryFile(manifest, true), `${JSON.stringify(redactSecrets(state), null, 2)}\n`, "utf-8");
 }
 
 export function appendMailboxMessage(manifest: TeamRunManifest, message: Omit<MailboxMessage, "id" | "runId" | "createdAt" | "status"> & { id?: string; status?: MailboxMessageStatus }): MailboxMessage {
@@ -208,7 +209,7 @@ export function appendMailboxMessage(manifest: TeamRunManifest, message: Omit<Ma
 		status: message.status ?? "queued",
 		taskId: message.taskId,
 	};
-	fs.appendFileSync(mailboxFile(manifest, complete.direction, complete.taskId), `${JSON.stringify(complete)}\n`, "utf-8");
+	fs.appendFileSync(mailboxFile(manifest, complete.direction, complete.taskId), `${JSON.stringify(redactSecrets(complete))}\n`, "utf-8");
 	const delivery = readDeliveryState(manifest);
 	delivery.messages[complete.id] = complete.status;
 	delivery.updatedAt = createdAt;
@@ -249,7 +250,7 @@ export function validateMailbox(manifest: TeamRunManifest, options: { repair?: b
 				const parsed = JSON.parse(line) as unknown;
 				const message = parseMailboxMessage(parsed, direction);
 				if (!message) throw new Error("invalid message schema");
-				validLines.push(JSON.stringify(message));
+				validLines.push(JSON.stringify(redactSecrets(message)));
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
 				issues.push({ level: "error", path: filePath, message });

package/src/state/types.ts

@@ -81,6 +81,17 @@ export interface AsyncRunState {
 	spawnedAt: string;
 }
 
+export interface PlanApprovalState {
+	required: boolean;
+	status: "pending" | "approved" | "cancelled";
+	requestedAt: string;
+	updatedAt: string;
+	approvedAt?: string;
+	cancelledAt?: string;
+	planTaskId?: string;
+	planArtifactPath?: string;
+}
+
 export interface TeamRunManifest {
 	schemaVersion: 1;
 	runId: string;
@@ -98,6 +109,7 @@ export interface TeamRunManifest {
 	eventsPath: string;
 	artifacts: ArtifactDescriptor[];
 	async?: AsyncRunState;
+	planApproval?: PlanApprovalState;
 	summary?: string;
 	policyDecisions?: PolicyDecision[];
 }

package/src/teams/discover-teams.ts

@@ -109,7 +109,7 @@ export function discoverTeams(cwd: string): TeamDiscoveryResult {
 
 export function allTeams(discovery: TeamDiscoveryResult): TeamConfig[] {
 	const byName = new Map<string, TeamConfig>();
-	for (const team of [...discovery.builtin, ...discovery.user, ...discovery.project]) {
+	for (const team of [...discovery.project, ...discovery.builtin, ...discovery.user]) {
 		byName.set(team.name, team);
 	}
 	return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));

package/src/utils/redaction.ts

@@ -0,0 +1,41 @@
+const SECRET_KEY_PATTERN = /(?:^|[_.-])(token|api[-_]?key|password|passwd|secret|credential|authorization|private[-_]?key)(?:$|[_.-])/i;
+const INLINE_SECRET_PATTERN = /(^|[\s,{])(([A-Za-z0-9_.-]*(?:api[-_]?key|token|password|passwd|secret|credential|authorization|private[-_]?key)[A-Za-z0-9_.-]*)\s*[=:]\s*)([^\s,;"'}]+)/gi;
+const AUTH_HEADER_PATTERN = /\b(Authorization\s*:\s*(?:Bearer|Basic|Token)?\s*)([^\r\n]+)/gi;
+const BEARER_PATTERN = /\b(Bearer\s+)([A-Za-z0-9._~+/=-]{8,})\b/g;
+const PEM_PRIVATE_KEY_PATTERN = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isSecretKey(keyName: string): boolean {
+	return SECRET_KEY_PATTERN.test(keyName) || /^(token|apiKey|api_key|password|secret|credential|authorization|privateKey|private_key)$/i.test(keyName);
+}
+
+export function redactSecretString(value: string): string {
+	return value
+		.replace(PEM_PRIVATE_KEY_PATTERN, "***")
+		.replace(AUTH_HEADER_PATTERN, "$1***")
+		.replace(BEARER_PATTERN, "$1***")
+		.replace(INLINE_SECRET_PATTERN, "$1$2***");
+}
+
+export function redactSecrets(value: unknown, keyName = ""): unknown {
+	if (keyName && isSecretKey(keyName)) return "***";
+	if (typeof value === "string") return redactSecretString(value);
+	if (Array.isArray(value)) return value.map((item) => redactSecrets(item));
+	if (isRecord(value)) {
+		const output: Record<string, unknown> = {};
+		for (const [key, entry] of Object.entries(value)) output[key] = redactSecrets(entry, key);
+		return output;
+	}
+	return value;
+}
+
+export function redactJsonLine(line: string): string {
+	try {
+		return JSON.stringify(redactSecrets(JSON.parse(line) as unknown));
+	} catch {
+		return redactSecretString(line);
+	}
+}

package/src/workflows/discover-workflows.ts

@@ -129,7 +129,7 @@ export function discoverWorkflows(cwd: string): WorkflowDiscoveryResult {
 
 export function allWorkflows(discovery: WorkflowDiscoveryResult): WorkflowConfig[] {
 	const byName = new Map<string, WorkflowConfig>();
-	for (const workflow of [...discovery.builtin, ...discovery.user, ...discovery.project]) {
+	for (const workflow of [...discovery.project, ...discovery.builtin, ...discovery.user]) {
 		byName.set(workflow.name, workflow);
 	}
 	return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));