opencode-workflow-guard 1.15.5 → 1.16.0

package/src/lib/state.ts

@@ -1,7 +1,7 @@
 import { existsSync, unlinkSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { getReviewCacheFilePath, loadReviewCache, persistReviewCache, persistVerifyCache, persistVerifyHistory } from "./audit.ts";
+import { audit, getReviewCacheFilePath, loadReviewCache, persistReviewCache, persistVerifyCache, persistVerifyHistory } from "./audit.ts";
 import { findGitRoot, getCachedProjectConfig, isSameGitRepo, loadProjectConfig, projectRootKey } from "./project-config.ts";
 import { snipVerifyOutput, getCurrentGitCommitHash, getGitStatusSummary, getGitWorktreeFingerprint, getTrackedWorktreeFingerprint } from "./verify.ts";
 import { normalizeLiveControlPlaneRoots } from "./live-control-plane.ts";
@@ -56,6 +56,23 @@ const workspaceMutationCounts = new Map<string, number>();
 export const sessionMutationTimestamps = new Map<string, number>();
 export const sessionMutationCounts = new Map<string, number>();
 export const sessionWorkspaces = new Map<string, string>();
+// Per-session, per-task mutation count recorded when an active task entered
+// its current active window. Completion is judged per task: one mutation
+// cannot vouch for several completions.
+export const sessionTodoTaskStarts = new Map<string, Map<string, number>>();
+
+export function todoTaskStarts(sessionID: string): Map<string, number> {
+	let starts = sessionTodoTaskStarts.get(sessionID);
+	if (!starts) {
+		starts = new Map();
+		sessionTodoTaskStarts.set(sessionID, starts);
+	}
+	return starts;
+}
+
+export function clearTodoSessionState(sessionID: string): void {
+	sessionTodoTaskStarts.delete(sessionID);
+}
 // Sessions whose workspace was registered from their OWN context (tool-call
 // arguments or a host-provided per-call worktree). A session registered only
 // from the plugin-instance default is deliberately left unmarked: concurrent
@@ -89,33 +106,155 @@ export function getSessionBoundWorkspace(sessionID?: string): string | undefined
 }
 
 /**
- * Register a session's workspace from a tool call's own context. Candidates in
- * priority order: tool-argument paths (workdir/filePath — the call's own
- * target), then a host-provided per-call worktree/directory. A session that is
- * already registered is never re-anchored from the plugin-instance fallback:
- * under concurrent loops that fallback can belong to a different session's
- * workspace, which is exactly how workspaces cross-contaminate. Only a
- * session with no registration at all is bootstrapped from the fallback, and
- * such a bootstrap stays unbound (never used to bind review evidence).
+ * The nearest bound workspace up the parent chain, for a session with no
+ * direct binding of its own.
+ *
+ * A subagent's policy root already inherits its parent's workspace, so its
+ * registration must use the same answer. Without this, a child of a bound
+ * session looked unbound to the registration path and its first foreign read
+ * rebound it into another repository: the parent stayed confined and the child
+ * escaped.
+ *
+ * Walks at most `MAX_PARENT_DEPTH` links and stops on a cycle.
+ *
+ * Cost: one `session.get` per parent link, issued only when the session has no
+ * direct binding. A directly bound session returns from the in-memory map with
+ * no RPC, so the common case pays nothing. The walk is depth-capped and
+ * cycle-checked, so a malformed parent graph cannot spin.
+ */
+const MAX_PARENT_DEPTH = 16;
+
+/**
+ * Walk up the parent chain from `sessionID` and return the nearest directly
+ * bound ancestor's workspace.
+ *
+ * Shared by `resolveInheritedWorkspace` (full walk, used by workspace
+ * registration so a subagent cannot rebind out of its parent's boundary) and
+ * `resolveSessionBoundWorkspace` (one level, used by review-verdict binding).
+ * The depth parameter is the only difference; keeping one implementation makes
+ * the one-lookup-per-link cost visible in a single place.
+ */
+async function resolveAncestorBoundWorkspace(sessionID: string, maxDepth: number): Promise<string | undefined> {
+	if (maxDepth <= 0) return undefined;
+	const client = getSdkClient();
+	const session = client?.session;
+	const get = session?.get;
+	if (typeof get !== "function") return undefined;
+	const seen = new Set<string>([sessionID]);
+	let current = sessionID;
+	for (let depth = 0; depth < maxDepth; depth++) {
+		let parentID: unknown;
+		try {
+			const result = await get.call(session, { path: { id: current } });
+			parentID = (result as { data?: { parentID?: unknown } } | undefined)?.data?.parentID;
+		} catch {
+			return undefined;
+		}
+		if (typeof parentID !== "string" || !parentID || seen.has(parentID)) return undefined;
+		const inherited = getSessionBoundWorkspace(parentID);
+		if (inherited) return inherited;
+		seen.add(parentID);
+		current = parentID;
+	}
+	return undefined;
+}
+
+export async function resolveInheritedWorkspace(sessionID?: string): Promise<string | undefined> {
+	if (!sessionID) return undefined;
+	const direct = getSessionBoundWorkspace(sessionID);
+	if (direct) return direct;
+	return resolveAncestorBoundWorkspace(sessionID, MAX_PARENT_DEPTH);
+}
+
+/**
+ * Register a session's workspace from a tool call's own context.
+ *
+ * Two distinct operations, deliberately split:
+ *
+ * - **First bind.** A session with no bound workspace adopts the git root of
+ *   its own call arguments (`workdir`/`filePath`), else the host-provided
+ *   per-call worktree, else a path-derived bootstrap from the plugin-instance
+ *   fallback. A bootstrap from the fallback stays unbound: concurrent loops
+ *   share this process, so a value derived from the last-active plugin
+ *   instance must never bind review evidence.
+ * - **Widen.** Once bound, only an explicit host-declared per-call worktree
+ *   may move the boundary. Worktree isolation and relay flows set it, so it is
+ *   a boundary statement from the host. A bare path candidate outside the
+ *   boundary is a read or write against foreign state, which the boundary
+ *   policy refuses; adopting it would let one allowed external read move the
+ *   whole write boundary.
+ *
+ * "Bound" includes an inherited binding: a subagent with no direct binding of
+ * its own already resolves to its nearest bound ancestor's workspace for
+ * policy decisions, so a path-derived candidate must not bind it elsewhere.
+ *
+ * Every widen and every refused widen is journaled, because the boundary is
+ * what unattended operation rests on.
  */
-export function registerSessionWorkspaceFromToolCall(
+export async function registerSessionWorkspaceFromToolCall(
 	sessionID: string | undefined,
-	call: { workdir?: string; filePath?: string; hostWorktree?: string; toolWorktree: string },
-): void {
+	call: { workdir?: string; filePath?: string; hostWorktree?: string; toolWorktree: string; mutating?: boolean },
+): Promise<void> {
 	if (!sessionID) return;
-	const rawCandidate = call.workdir ?? call.filePath ?? call.hostWorktree;
-	if (rawCandidate) {
-		const candidatePath = isAbsolute(rawCandidate) ? rawCandidate : resolve(call.toolWorktree, rawCandidate);
-		const gitRoot = findGitRoot(candidatePath);
-		if (gitRoot) {
-			sessionWorkspaces.set(sessionID, gitRoot);
-			sessionWorkspaceBound.add(sessionID);
-		}
+	const bound = await resolveInheritedWorkspace(sessionID);
+
+	// A host-declared per-call worktree is an explicit boundary statement.
+	const hostRoot = call.hostWorktree ? findGitRoot(call.hostWorktree) : undefined;
+	if (hostRoot && hostRoot !== bound) {
+		setSessionWorkspace(sessionID, hostRoot);
+		auditWorkspaceRebind(sessionID, bound, hostRoot, "host-worktree");
+		return;
+	}
+
+	const rawCandidate = call.workdir ?? call.filePath;
+	if (!rawCandidate) {
+		if (sessionWorkspaces.has(sessionID)) return;
+		const gitRoot = findGitRoot(call.toolWorktree);
+		sessionWorkspaces.set(sessionID, gitRoot ?? projectRootKey(call.toolWorktree));
 		return;
 	}
-	if (sessionWorkspaces.has(sessionID)) return;
-	const gitRoot = findGitRoot(call.toolWorktree);
-	sessionWorkspaces.set(sessionID, gitRoot ?? projectRootKey(call.toolWorktree));
+
+	const candidatePath = isAbsolute(rawCandidate) ? rawCandidate : resolve(call.toolWorktree, rawCandidate);
+	const gitRoot = findGitRoot(candidatePath);
+	if (!gitRoot) return;
+	if (gitRoot === bound) return;
+
+	if (!bound) {
+		sessionWorkspaces.set(sessionID, gitRoot);
+		sessionWorkspaceBound.add(sessionID);
+		return;
+	}
+	auditWorkspaceRebindRefused(sessionID, bound, gitRoot, call.mutating ? "mutation" : "read");
+}
+
+/** Durable record of a granted boundary widening. */
+function auditWorkspaceRebind(sessionID: string, from: string | undefined, to: string, source: string): void {
+	audit({
+		ts: new Date().toISOString(),
+		sessionID,
+		tool: "workspace.binding",
+		decision: "allow",
+		phase: "event",
+		reason: "workspace_rebind_host_worktree",
+		input: { from, to, source },
+	});
+}
+
+/**
+ * Durable record of a refused widening. The refusal itself is the boundary
+ * policy's decision; this entry exists so an operator can tell whether a
+ * foreign path arrived through a read or a mutation.
+ */
+function auditWorkspaceRebindRefused(sessionID: string, from: string, to: string, source: "read" | "mutation"): void {
+	audit({
+		ts: new Date().toISOString(),
+		sessionID,
+		tool: "workspace.binding",
+		decision: "block",
+		phase: "event",
+		reason: "workspace_rebind_refused",
+		input: { from, to, source },
+	});
 }
 
 /**
@@ -129,19 +268,10 @@ export async function resolveSessionBoundWorkspace(sessionID?: string): Promise<
 	if (!sessionID) return undefined;
 	const direct = getSessionBoundWorkspace(sessionID);
 	if (direct) return direct;
-	try {
-		const client = getSdkClient();
-		const session = client?.session;
-		const get = session?.get;
-		if (typeof get === "function") {
-			const result = await get.call(session, { path: { id: sessionID } });
-			const parent = (result as { data?: { parentID?: unknown } } | undefined)?.data?.parentID;
-			if (typeof parent === "string" && parent && sessionWorkspaceBound.has(parent)) {
-				return sessionWorkspaces.get(parent);
-			}
-		}
-	} catch {}
-	return undefined;
+	// One level only: review-verdict binding asks for the immediate parent, and
+	// walking further would let a grandparent's workspace answer for a child
+	// that was deliberately left unbound.
+	return resolveAncestorBoundWorkspace(sessionID, 1);
 }
 
 export let lastVerify: VerifyResult | undefined;
@@ -242,6 +372,7 @@ export function resetVerifyState(): void {
 	workspaceMutationTimestamps.clear();
 	workspaceMutationCounts.clear();
 	sessionVerifyResults.clear();
+	sessionTodoTaskStarts.clear();
 }
 
 export function recordReviewResult(

package/src/lib/v2-plugin.ts

@@ -6,9 +6,11 @@
  * - `ctx.tool.transform` for custom tools and tool-description enrichment
  * - `ctx.tool.hook("execute.before"/"execute.after")` for deterministic enforcement
  * - `ctx.session.hook("context"/"compaction"/"prompt")` for system guidance,
- *   compaction context, and recovery checkpoints
- * - `ctx.permission.hook("evaluate")` for permission journaling
+ *   read-only tool pruning, compaction context, and recovery checkpoints
+ * - `ctx.command.transform` for the server-side `/guard-status` command
+ * - `ctx.permission.hook("evaluate")` for the pre-execution deny seat
  * - `ctx.shell.hook("create.before")` for env scrubbing
+ * - `ctx.mcp.list()` plus `mcp.tools.changed` for the guarded-server inventory
  * - `ctx.event.subscribe()` for tool outcomes, session lifecycle, and claims-vs-evidence
  *
  * The V1 SDK client surface (`TodoSdkClient`) is satisfied by an adapter so
@@ -20,7 +22,7 @@ import { Message } from "@opencode/ai";
 import { z } from "zod";
 import { join, resolve } from "node:path";
 import type { TodoSdkClient } from "./types.ts";
-import { scanSessionTodos, toolPartName } from "./v2-todo.ts";
+import { detectTodoCapability, recordTodoCapability, recordedTodoCapability, scanSessionTodos, toolPartName } from "./v2-todo.ts";
 import { findGitRoot, reloadProjectConfig } from "./project-config.ts";
 import {
 	setWorkspaceRoot,
@@ -31,6 +33,7 @@ import {
 	getSessionMutationCount,
 	sessionVerifyResults,
 	sessionReviews,
+	clearTodoSessionState,
 	isRecoveryCheckpointsEnabled,
 	isLearningEnabled,
 	isProjectMemoryEnabled,
@@ -65,6 +68,13 @@ import { loadedPluginVersion } from "./version.ts";
 import { clearContinuationState, continueUnfinishedSession, isGeneratedContinuationMessage, recordUserMessage } from "../policies/continuation.ts";
 import { createRecoveryCheckpoint, finalizeRecoveryCheckpoint, nextRecoveryRun } from "./checkpoint.ts";
 import { buildCompactionContext, guardToolCall } from "../workflow-guard.ts";
+import { registerPluginInstance, releasePluginInstance } from "./plugin-instance.ts";
+import { claimToolCall, releaseToolCallClaim } from "./call-claims.ts";
+import { evaluatePermissionSeat } from "./permission-seat.ts";
+import { pruneToolsForReadOnlyRole } from "./read-only-tools.ts";
+import { registerGuardStatusCommand } from "./guard-command.ts";
+import { createHostWorktreePort } from "./host-worktree.ts";
+import { listHostMcpServerNames, recordHostMcpServers } from "./mcp-inventory.ts";
 
 type V2Context = Plugin.Context;
 
@@ -88,7 +98,7 @@ function createV2SdkClient(ctx: V2Context): TodoSdkClient {
 			},
 		},
 		session: {
-			todo: async ({ path }) => ({ data: await scanSessionTodos(ctx, path.id) }),
+			todo: async ({ path }) => ({ data: await scanSessionTodos(ctx, path.id, recordedTodoCapability()) }),
 			get: async ({ path }) => {
 				const session = await ctx.session.get({ sessionID: path.id });
 				return { data: { parentID: (session as { parentID?: string }).parentID, title: (session as { title?: string }).title } };
@@ -110,7 +120,7 @@ function createV2SdkClient(ctx: V2Context): TodoSdkClient {
 // ── Builtin tool description enrichment ───────────────────────────────────────
 
 const TODOWRITE_SUFFIX =
-	"\n\nWorkflow Guard lifecycle: each todowrite call replaces the complete task list. Preserve every pending/in_progress task in subsequent updates until you explicitly mark it completed or cancelled; do not omit active tasks when adding new work. Marking every task completed triggers the finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply. Proactively call guard_next_tasks when planning work to discover existing roadmap/TODOs, and guard_status to check outstanding requirements.";
+	"\n\nWorkflow Guard lifecycle: use todowrite to plan before working - it is the only view of progress the operator has, and every file mutation is gated on it. Each call replaces the complete task list: preserve every pending/in_progress task in subsequent updates until you explicitly mark it completed or cancelled, and do not omit active tasks when adding new work. A task may be marked completed only after its own work is recorded: the guard blocks a completion that has no file mutation in that task's active window, and one mutation cannot vouch for several completions. If a task is genuinely read-only (review, investigation, reading), append the marker `[read-only]` to its text; every such use is journaled. Use `cancelled` for work that was deliberately dropped. Marking every task completed triggers the finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply. Proactively call guard_next_tasks when planning work to discover existing roadmap/TODOs, and guard_status to check outstanding requirements.";
 
 const EDIT_SUFFIX =
 	"\n\nWorkflow Guard requirement: Modifications require an active task in todowrite (status pending or in_progress), a feature branch (edits on main/master are blocked), and a prior read of existing files in the current session.";
@@ -122,12 +132,14 @@ const SUBAGENT_SUFFIX =
 // host's tool registry; `ToolEditor.update` ignores missing IDs, so extra
 // candidates are harmless no-ops.
 //
-// V2.0.10 builtin surface (docs + binary): read, glob, grep, edit, write,
-// patch, shell, webfetch, websearch, question, skill, subagent, execute.
-// - There is no builtin `todowrite` (the V1 name). Todowrite tool parts seen
-//   in V2 sessions come from ACP agents that supply their own tools; those
-//   are not in the server registry, so this enrichment cannot reach them.
-//   The candidate is kept for hosts that do register a todowrite tool.
+// Version boundary for the builtin surface:
+// - V2.0.x (docs + binary, up to and including 2.0.15): read, glob, grep,
+//   edit, write, patch, shell, webfetch, websearch, question, skill, subagent,
+//   execute. There is no builtin `todowrite`; todowrite parts in V2 sessions
+//   come from ACP agents that supply their own tools, which are not in the
+//   server registry, so this enrichment cannot reach them.
+// - V2.1.x adds a builtin `todowrite` behind the `experimental.todo` config
+//   key, so the candidate below reaches a real registry entry there.
 // - The V1 subagent tool `task` was renamed to `subagent`; both are kept as
 //   candidates for the same reason.
 const ENRICHMENT_TARGETS: Array<{ candidates: string[]; suffix: string; marker: string }> = [
@@ -141,7 +153,10 @@ const ENRICHMENT_TARGETS: Array<{ candidates: string[]; suffix: string; marker:
 export const WorkflowGuardV2 = async (ctx: V2Context) => {
 	const hostRoot = ctx.location?.directory || process.cwd();
 	const hostIsFilesystemRoot = resolve(hostRoot) === resolve(hostRoot, "..");
-	const projectDirectory = (ctx.location as { project?: { directory?: string; canonical?: string } })?.project?.directory;
+	// `location.project` is required by the host's `Location.Info` schema
+	// (`@opencode/schema/dist/location.d.ts`), so the optional read is only a
+	// runtime guard for harnesses and stubs that construct a partial context.
+	const projectDirectory = ctx.location.project?.directory;
 	let effectiveRoot = hostIsFilesystemRoot && projectDirectory && resolve(projectDirectory) !== resolve(projectDirectory, "..")
 		? projectDirectory
 		: hostRoot;
@@ -154,6 +169,20 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 	}
 
 	const client = createV2SdkClient(ctx);
+	// Load-once guard: OpenCode 2 merges plugin arrays, so the same package
+	// named in global and project config loads this module twice. A duplicate
+	// stays inert (no hooks, no tools, no second workspace latch) and leaves a
+	// warn-level record; see lib/plugin-instance.ts.
+	const instance = registerPluginInstance({ workspaceRoot: effectiveRoot });
+	if (instance.duplicate) {
+		try {
+			console.warn(
+				`[workflow-guard] warn: duplicate plugin load for ${instance.workspaceRoot} (module ${instance.modulePath}); ` +
+					"this instance stays inert. Configure the guard in one location only.",
+			);
+		} catch {}
+		return () => releasePluginInstance(instance.key);
+	}
 	setWorkspaceRoot(effectiveRoot);
 	setSdkClient(client);
 	reloadProjectConfig(effectiveRoot);
@@ -185,7 +214,7 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 	const toolOutcomes = new ToolOutcomeTracker();
 
 	// ── Custom tools + builtin description enrichment ──
-	const customTools = createCustomTools({ effectiveRoot, projectMemoryEnabled, learningEnabled, projectMemory, followupStore, portableMemoryPath, learningInterventions, client });
+	const customTools = createCustomTools({ effectiveRoot, projectMemoryEnabled, learningEnabled, projectMemory, followupStore, portableMemoryPath, learningInterventions, client, hostWorktree: createHostWorktreePort(ctx), todoCapability: () => recordedTodoCapability(), hostVersion: () => ctx.app?.version });
 	await ctx.tool.transform((editor) => {
 		for (const [name, definition] of Object.entries(customTools)) {
 			editor.add({
@@ -222,8 +251,32 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 		}
 	});
 
+	// ── /guard-status command ──
+	// Reachable from every V2 client without the optional TUI companion. The
+	// report is produced by the same guard_status implementation the tool uses,
+	// then delivered as a synthetic message so it costs no model turn.
+	await registerGuardStatusCommand(ctx, {
+		runStatus: async (sessionID) => {
+			const boundWorktree = getSessionBoundWorkspace(sessionID);
+			const result = await (customTools.guard_status as unknown as {
+				execute: (input: unknown, context: unknown) => Promise<unknown>;
+			}).execute({}, {
+				sessionID,
+				...(boundWorktree ? { worktree: boundWorktree } : {}),
+				directory: boundWorktree ?? effectiveRoot,
+			});
+			return typeof result === "string" ? result : JSON.stringify(result);
+		},
+		effectiveRoot,
+		client,
+	});
+
 	// ── Deterministic enforcement ──
 	await ctx.tool.hook("execute.before", (event) => {
+		// One policy decision per tool call even if a second instance with a
+		// different module path (global cache copy plus a source checkout)
+		// registered too. The owner evaluates; the other defers.
+		if (!claimToolCall(instance.key, event.sessionID, event.id, event.tool)) return;
 		const toolWorktree = getSessionBoundWorkspace(event.sessionID) || effectiveRoot;
 		return runWithRuntimeState(toolWorktree, client, async () => {
 			const args = event.input;
@@ -234,6 +287,7 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 				agent: event.agent,
 			});
 			if (reason !== undefined) {
+				releaseToolCallClaim(instance.key, event.sessionID, event.id, event.tool);
 				await showBlockToast(reason);
 				const failureCount = event.sessionID ? toolOutcomes.getFailureCount(event.sessionID) : 0;
 				const circuitBreakerSuffix = failureCount >= 2
@@ -245,7 +299,12 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 			const record = asRecord(args);
 			const workdir = typeof record?.workdir === "string" ? record.workdir : undefined;
 			const filePath = typeof record?.filePath === "string" ? record.filePath : (typeof record?.path === "string" ? record.path : undefined);
-			registerSessionWorkspaceFromToolCall(event.sessionID, { workdir, filePath, toolWorktree });
+			await registerSessionWorkspaceFromToolCall(event.sessionID, {
+				workdir,
+				filePath,
+				toolWorktree,
+				mutating: EDIT_TOOL_NAMES.has(event.tool) || SHELL_TOOL_NAMES.has(event.tool),
+			});
 			if (event.tool === "read") {
 				const target = editTargets(args, toolWorktree)[0];
 				if (target) {
@@ -286,6 +345,7 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 	});
 
 	await ctx.tool.hook("execute.after", async (event) => {
+		releaseToolCallClaim(instance.key, event.sessionID, event.id, event.tool);
 		const startedAt = toolLifecycle.finish(event.sessionID, event.id);
 		const outcome = toolOutcomes.recordFallbackCompleted(event.sessionID, event.id, event.tool, startedAt === undefined ? undefined : Date.now() - startedAt);
 		if (outcome) {
@@ -339,6 +399,25 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 	// ── Session request hooks ──
 	await ctx.session.hook("context", (event) => {
 		try {
+			// A read-only role must not be able to *choose* a mutating tool. The
+			// execute.before seat still denies it, but pruning the per-request
+			// tool snapshot removes the call before the model plans it. Pruning
+			// is a narrowing only: tools supplied outside the host snapshot
+			// (ACP agents, nested Code Mode calls) still meet the backstop.
+			if (event.agent && isReadOnlyRole(event.agent)) {
+				const removed = pruneToolsForReadOnlyRole(event.tools as Record<string, unknown> | undefined);
+				if (removed.length > 0) {
+					audit({
+						ts: new Date().toISOString(),
+						sessionID: event.sessionID,
+						tool: "session.context",
+						decision: "block",
+						phase: "decision",
+						reason: "read_only_role_tools_pruned",
+						input: { agent: event.agent, removed },
+					});
+				}
+			}
 			const existing = Array.isArray(event.system)
 				? event.system.map((part) => (typeof part === "string" ? part : (part as { text?: string }).text ?? "")).join("\n")
 				: "";
@@ -388,7 +467,7 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 				priorityContextBlocks.push(
 					`## Active Tasks${attribution}\n` +
 						lines.join("\n") +
-						"\nComplete tasks efficiently - mark finished items as completed and address remaining ones.",
+						"\nComplete tasks efficiently and address remaining ones. Mark a task completed only after its work is actually done: the guard blocks a completion with no recorded file mutation in that task's window. Append `[read-only]` to a genuinely read-only task (review, investigation), and use `cancelled` for work that was dropped.",
 				);
 			}
 
@@ -451,22 +530,57 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 		} catch {}
 	});
 
-	// ── Permission journaling ──
-	await ctx.permission.hook("evaluate", (event) => {
+	// ── Permission seat: deny before the tool starts ──
+	// `evaluate` sees normalized `action`/`resources` and runs before the tool,
+	// so it is the earliest hard stop for shell commands, file mutations, and
+	// guarded MCP calls. It cannot see raw tool input, so the raw-argument work
+	// (todo lifecycle, stale-write, post-edit snapshots) stays in
+	// `execute.before`. See lib/permission-seat.ts for the split and the limits.
+	//
+	// Flow limit, documented by the host: an explicit configured `deny` is
+	// resolved before this hook runs, so the hook never sees it. A guard audit
+	// therefore cannot explain a configured deny; only host config can. The
+	// hook runs for allow/ask, and a denial here is always a tightening.
+	await ctx.permission.hook("evaluate", async (event) => {
+		const configuredEffect = event.effect;
 		try {
+			const seat = await evaluatePermissionSeat(
+				{
+					sessionID: event.sessionID,
+					agent: event.agent,
+					action: event.action,
+					resources: event.resources,
+					effect: configuredEffect,
+				},
+				{ workspaceRoot: effectiveRoot, client },
+			);
+			if (seat.decision) {
+				event.effect = "deny";
+				event.message = seat.decision.message;
+			}
 			audit({
 				ts: new Date().toISOString(),
 				sessionID: event.sessionID,
 				tool: "permission.ask",
-				decision: event.effect === "deny" ? "block" : "allow",
+				decision: seat.effect === "deny" ? "block" : "allow",
+				phase: "decision",
+				reason: seat.decision?.code,
+				policyDecision: seat.decision,
 				input: {
 					action: event.action,
 					resources: event.resources,
 					agent: event.agent,
-					effect: event.effect,
+					configuredEffect,
+					mappedTool: seat.mappedTool,
 				},
 			});
-		} catch {}
+		} catch (error) {
+			// Fail closed: a seat that cannot evaluate must not become a pass.
+			try {
+				event.effect = "deny";
+				event.message = `[workflow-guard permission.evaluate] Blocked: the guard could not evaluate this permission request (${(error as Error)?.message ?? "unknown error"}).`;
+			} catch {}
+		}
 	});
 
 	// ── Shell env scrubbing ──
@@ -488,6 +602,47 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 		} catch {}
 	});
 
+	// ── MCP inventory ──
+	// Seed the guarded token set from host-declared servers, then refresh it
+	// whenever the host reports that a server's tools changed. Widen-only:
+	// removal adds nothing, so a renamed or dropped server can never unguard a
+	// tool that still names a live system. The static defaults in
+	// policies/mcp.ts stay the floor.
+	const seedMcpInventory = async () => {
+		try {
+			const added = recordHostMcpServers(await listHostMcpServerNames(ctx));
+			if (added.length > 0) {
+				audit({
+					ts: new Date().toISOString(),
+					tool: "mcp.inventory",
+					decision: "allow",
+					phase: "event",
+					reason: "host_mcp_servers_widened",
+					input: { added },
+				});
+			}
+		} catch {}
+	};
+	await seedMcpInventory();
+
+	// ── Todo capability probe ──
+	// Ask the host's registry whether `todowrite` exists, instead of inferring
+	// it from history. On 2.0.x the answer is no, so the mutation gate fails
+	// open; on 2.1.x with `experimental.todo: true` the answer is yes, so a
+	// session that never planned is gated. Probe once: the registry is fixed
+	// for the life of the process.
+	try {
+		const capability = await detectTodoCapability(ctx);
+		recordTodoCapability(capability);
+		audit({
+			ts: new Date().toISOString(),
+			tool: "todo.capability",
+			decision: "allow",
+			phase: "event",
+			reason: `todo_capability_${capability}`,
+		});
+	} catch {}
+
 	// ── Event stream ──
 	const controller = new AbortController();
 	void (async () => {
@@ -500,6 +655,7 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 						client,
 						toolLifecycle,
 						toolOutcomes,
+						refreshMcpInventory: seedMcpInventory,
 					});
 				} catch {}
 			}
@@ -508,7 +664,10 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 		}
 	})();
 
-	return () => controller.abort();
+	return () => {
+		controller.abort();
+		releasePluginInstance(instance.key);
+	};
 };
 
 // ── Event handling ────────────────────────────────────────────────────────────
@@ -518,6 +677,8 @@ interface V2EventState {
 	client: unknown;
 	toolLifecycle: ToolInvocationLifecycle;
 	toolOutcomes: ToolOutcomeTracker;
+	/** Re-read the host MCP roster after `mcp.tools.changed`. */
+	refreshMcpInventory?: () => Promise<void>;
 }
 
 async function handleV2Event(
@@ -526,6 +687,14 @@ async function handleV2Event(
 ): Promise<void> {
 	const { effectiveRoot, client, toolLifecycle, toolOutcomes } = state;
 
+	if (event.type === "mcp.tools.changed") {
+		// The host's server roster or one server's tool list changed. Re-read it
+		// so a newly connected live-system server is guarded before its tools
+		// are callable. Widen-only: this can add tokens, never remove them.
+		await state.refreshMcpInventory?.();
+		return;
+	}
+
 	if (event.type === "session.message.content.updated") {
 		const data = event.data as { sessionID?: unknown; content?: unknown } | undefined;
 		const sessionID = typeof data?.sessionID === "string" ? data.sessionID : undefined;
@@ -625,6 +794,7 @@ async function handleV2Event(
 			clearReadFingerprints(sessionID);
 			toolLifecycle.clearSession(sessionID);
 			toolOutcomes.clearSession(sessionID);
+			clearTodoSessionState(sessionID);
 			toolLifecycle.takeRecoveryRun(sessionID);
 			await runWithRuntimeState(effectiveRoot, client, () => clearContinuationState(sessionID));
 		}
@@ -646,8 +816,24 @@ async function handleV2Event(
 		});
 		return;
 	}
+	// `command.executed` exists in the V2 event stream (`data: { name, sessionID,
+	// arguments, messageID }`) and carries what the V1 audit wanted: the slash
+	// command name, its arguments, and the session. It is journaled here rather
+	// than dropped, so a command that mutates workspace state stays attributable.
+	if (event.type === "command.executed") {
+		const data = event.data as { sessionID?: unknown; name?: unknown; arguments?: unknown } | undefined;
+		audit({
+			ts: new Date().toISOString(),
+			sessionID: typeof data?.sessionID === "string" ? data.sessionID : undefined,
+			tool: "command.executed",
+			decision: "allow",
+			phase: "event",
+			reason: typeof data?.name === "string" ? data.name : undefined,
+			input: summarizeInput({ name: data?.name, arguments: data?.arguments }),
+		});
+		return;
+	}
 	// Note on V1 events without a V2 counterpart:
-	// - `command.executed`: no V2 event stream equivalent (audit-only in V1; dropped).
 	// - `permission.updated`: replaced by `permission.asked`/`permission.replied` above.
 	// - `session.created`: exists in the V2 union but needed no V1 behavior beyond
 	//   the audit above; session state resets happen on `session.deleted`.