opencode-workflow-guard 1.15.5 → 1.17.0

package/src/lib/custom-tools.ts

@@ -36,15 +36,17 @@ import {
 	runWithRuntimeState,
 } from "./state.ts";
 import { getRalphOutcome } from "../policies/continuation.ts";
+import { todoEvidenceReport } from "../policies/todo.ts";
 import { findGitRoot, loadProjectConfig, projectRootKey } from "./project-config.ts";
 import { detectVerifyCommand, getCurrentGitCommitHash, getGitWorktreeFingerprint, getTrackedWorktreeFingerprint } from "./verify.ts";
 import { buildReviewRubric } from "./review.ts";
-import { createGitWorktree, cleanupGitWorktree } from "./worktree.ts";
+import { createGitWorktree, cleanupGitWorktree, validateHostWorktreeDirectory } from "./worktree.ts";
+import type { HostWorktreePort } from "./host-worktree.ts";
 import { branchHasDocumentationChange } from "../policies/docs.ts";
 import { restoreRecoveryCheckpoint } from "./checkpoint.ts";
 import { audit, getRecentAuditEntries } from "./audit.ts";
 import { guardToolCallImpl } from "./guard-dispatcher.ts";
-import { loadedPluginVersion } from "./version.ts";
+import { loadedPluginVersion, qualifiedHostVersion } from "./version.ts";
 import { gitHygieneSnapshot } from "./hygiene.ts";
 import { discoverPlanningSources } from "../policies/planning.ts";
 import { secretIn } from "../policies/secrets.ts";
@@ -76,7 +78,7 @@ export function buildWorkflowGuardSystemGuidance(options: {
 	const sections: string[] = [
 		"## Workflow Guard & Operational Tools",
 		"Workflow Guard enforces safe engineering discipline and provides proactive workflow tools:",
-		"- Task Planning: Proactively call `guard_next_tasks` at session start or when planning work to discover repository roadmap, plan, and TODO items. Check `guard_status` to inspect branch protection, mutation count, and outstanding verification/review gates.",
+		"- Task Planning: The session's todo list is the unit of visible progress and it gates every file mutation. Call `todowrite` before starting work, keep exactly the real remaining tasks in it, and mark a task completed only after its work is actually done. A completion is checked against recorded work in that task's window, so finishing a task without doing it is blocked. Genuinely read-only tasks (review, investigation, reading) are marked `[read-only]` in their text. Proactively call `guard_next_tasks` at session start or when planning work to discover repository roadmap, plan, and TODO items, and check `guard_status` to inspect branch protection, mutation count, and outstanding verification/review gates.",
 	];
 
 	if (!options.isReadOnly) {
@@ -89,6 +91,7 @@ export function buildWorkflowGuardSystemGuidance(options: {
 	sections.push(
 		"- Technical Debt: Inspect open P2/P3 review follow-ups with `guard_review_followups` during planning; resolve fixed items with `guard_review_followup_resolve`.",
 		"- Policy Simulation: If uncertain whether a command or file edit is permitted, simulate it with `guard_why`.",
+		"- Live Documentation: Verify APIs, flags, and library behavior against current sources with `websearch`/`webfetch` rather than guessing from training data. After repeated tool failures with no lookup, Workflow Guard blocks further mutations and shell commands until you consult a live source; grounding clears the block.",
 	);
 
 	if (options.projectMemoryEnabled) {
@@ -121,8 +124,25 @@ export function createCustomTools(options: {
 	portableMemoryPath: string;
 	learningInterventions: Map<string, number>;
 	client: unknown;
+	/**
+	 * Host worktree port. When present and available, creation goes through the
+	 * host so the worktree lands in its configured directory and inventory.
+	 * Removal stays with the guard's snapshot-then-remove flow regardless.
+	 */
+	hostWorktree?: HostWorktreePort;
+	/**
+	 * Probed todo capability for this host, reported in `guard_status`.
+	 * Omitted on V1, which has a native todo endpoint and therefore always can
+	 * plan; V2 passes its registry probe so a fail-open gate is visible.
+	 */
+	todoCapability?: () => string;
+	/**
+	 * Live host version, reported next to the version this build was qualified
+	 * against so a mismatch is visible before it becomes a silent no-op.
+	 */
+	hostVersion?: () => string | undefined;
 }) {
-	const { effectiveRoot, projectMemoryEnabled, learningEnabled, projectMemory, followupStore, portableMemoryPath, learningInterventions, client } = options;
+	const { effectiveRoot, projectMemoryEnabled, learningEnabled, projectMemory, followupStore, portableMemoryPath, learningInterventions, client, hostWorktree, todoCapability, hostVersion } = options;
 	// Resolve the workspace for a tool call from the CALL's own context: an
 	// explicit argument first, then the host-provided per-call worktree or
 	// directory (even when unusable — the call declared its target), then the
@@ -276,7 +296,8 @@ export function createCustomTools(options: {
 					recommendedActions.push("All operational requirements are satisfied for task finalization and PR creation.");
 				}
 				const ralphOutcome = runWithRuntimeState(root, client, () => getRalphOutcome(toolContext.sessionID));
-				return JSON.stringify({ pluginVersion: loadedPluginVersion() ?? null, workspaceRoot: root, branch, onProtectedBranch: isProtected, outstandingRequirements, recommendedActions, lastMutationTimestamp: lastMut, mutationCount: getWorkspaceMutationCount(root), lastVerify: lastV && verifyEvidence ? { command: lastV.command, passed: lastV.passed, fresh: verifyFresh, evidenceId: verifyEvidence.id, commitHash: lastV.commitHash } : null, lastReview: lastR && reviewEvidenceRecord ? { reviewer: lastR.reviewer, passed: lastR.passed, summary: lastR.summary, fresh: reviewFresh, evidenceId: reviewEvidenceRecord.id } : null, ralph: { enabled: isRalphModeEnabled(root), maxIterations: getRalphMaxIterations(root), outcome: ralphOutcome ?? null }, projectConfig: { profile: getOperationProfile(root), protectedBranches: cfg.protectedBranches ?? ["main", "master"], verifyCommand: verifyCommand ?? null, requireReview: reviewRequired, requireDocumentation: documentationRequired, requireSubagentReview: isSubagentReviewRequired(root), recoveryCheckpoints: isRecoveryCheckpointsEnabled(root) }, gitHygiene: gitHygieneSnapshot(root) ?? null }, null, 2);
+				const taskEvidence = await runWithRuntimeState(root, client, () => todoEvidenceReport(toolContext.sessionID));
+				return JSON.stringify({ pluginVersion: loadedPluginVersion() ?? null, qualifiedHostVersion: qualifiedHostVersion() ?? null, hostVersion: hostVersion?.() ?? null, workspaceRoot: root, branch, onProtectedBranch: isProtected, todoCapability: todoCapability ? todoCapability() : "available", taskEvidence, outstandingRequirements, recommendedActions, lastMutationTimestamp: lastMut, mutationCount: getWorkspaceMutationCount(root), lastVerify: lastV && verifyEvidence ? { command: lastV.command, passed: lastV.passed, fresh: verifyFresh, evidenceId: verifyEvidence.id, commitHash: lastV.commitHash } : null, lastReview: lastR && reviewEvidenceRecord ? { reviewer: lastR.reviewer, passed: lastR.passed, summary: lastR.summary, fresh: reviewFresh, evidenceId: reviewEvidenceRecord.id } : null, ralph: { enabled: isRalphModeEnabled(root), maxIterations: getRalphMaxIterations(root), outcome: ralphOutcome ?? null }, projectConfig: { profile: getOperationProfile(root), protectedBranches: cfg.protectedBranches ?? ["main", "master"], verifyCommand: verifyCommand ?? null, requireReview: reviewRequired, requireDocumentation: documentationRequired, requireSubagentReview: isSubagentReviewRequired(root), recoveryCheckpoints: isRecoveryCheckpointsEnabled(root) }, gitHygiene: gitHygieneSnapshot(root) ?? null }, null, 2);
 			},
 		}),
 		guard_audit: tool({ description: "View recent audit entries recorded by opencode-workflow-guard. Use to diagnose policy decisions, blocked commands, or outcome telemetry.", args: { limit: tool.schema.number().optional().describe("Maximum entries to return (default 10)") }, execute: async (args) => JSON.stringify(getRecentAuditEntries(typeof args?.limit === "number" ? Math.min(args.limit, 50) : 10), null, 2) }),
@@ -374,17 +395,58 @@ export function createCustomTools(options: {
 			description: "Create an isolated git worktree directory for concurrent subagent execution. Proactively call when launching parallel tasks/subagents to prevent file collision and maintain branch isolation.", args: { branch: tool.schema.string().describe("Branch name for the isolated worktree (e.g. 'feat/subagent-task')"), baseBranch: tool.schema.string().optional().describe("Base branch to branch off of (defaults to HEAD)") },
 			execute: async (args, toolContext) => {
 				const todos = await effectiveTodos(toolContext.sessionID); if (todos !== undefined && !hasActiveTodo(todos)) return "[workflow-guard] Blocked: worktree creation with no active todo item. Break the request down with todowrite first, then create worktrees.";
-				const toolRoot = await resolveCallWorkspace(toolContext); const res = createGitWorktree(args.branch, args.baseBranch ?? "HEAD", toolRoot); if (!res.success) return `[workflow-guard] Failed to create worktree: ${res.error}`;
+				const toolRoot = await resolveCallWorkspace(toolContext);
+				// Host first: it honors the operator's configured worktree directory
+				// and keeps the worktree in host inventory. The result is validated
+				// independently (registered worktree of THIS repo, not the primary
+				// tree); any failure falls back to the guard's git path.
+				//
+				// The host path is used only for the default base. The host create
+				// input's `from` is an absolute directory path, not a git ref, so an
+				// explicit `baseBranch` cannot be expressed there; honoring it via
+				// the git path is better than silently ignoring it.
+				let createdPath: string | undefined;
+				let hostNote = "";
+				const requestedBase = args.baseBranch ?? "HEAD";
+				if (hostWorktree?.available && requestedBase === "HEAD") {
+					const hostResult = await hostWorktree.create({ branch: args.branch });
+					if (hostResult.directory) {
+						const validation = validateHostWorktreeDirectory(hostResult.directory, toolRoot);
+						if (validation.ok) {
+							createdPath = resolve(hostResult.directory);
+							hostNote = " (created by the host worktree strategy)";
+						} else {
+							hostNote = ` Host worktree creation was rejected by the guard (${validation.error}); used the guard's git path instead.`;
+						}
+					} else if (hostResult.error) {
+						hostNote = ` Host worktree creation failed (${hostResult.error}); used the guard's git path instead.`;
+					}
+				}
+				if (!createdPath) {
+					const res = createGitWorktree(args.branch, requestedBase, toolRoot);
+					if (!res.success) return `[workflow-guard] Failed to create worktree: ${res.error}${hostNote}`;
+					createdPath = res.worktreePath;
+				}
 				const mutationRoot = await resolveCallWorkspace(toolContext);
 				await runWithRuntimeState(mutationRoot, client, async () => recordMutation((await effectiveTodoOwnerSessionID(toolContext.sessionID)) ?? toolContext.sessionID, toolContext.sessionID));
-				return `[workflow-guard] Worktree created successfully at: ${res.worktreePath}\nRun subagent tasks or pass worktree directory context to isolate file mutations.`;
+				return `[workflow-guard] Worktree created successfully at: ${createdPath}${hostNote}\nRun subagent tasks or pass worktree directory context to isolate file mutations.`;
 			},
 		}),
 		guard_worktree_cleanup: tool({
 			description: "Commit a final snapshot and remove an isolated git worktree directory. Call to clean up worktrees created with guard_worktree_create after subagent tasks complete.", args: { worktreePath: tool.schema.string().describe("Path of the worktree directory to clean up") },
 			execute: async (args, toolContext) => {
 				const todos = await effectiveTodos(toolContext.sessionID); if (todos !== undefined && !hasActiveTodo(todos)) return "[workflow-guard] Blocked: worktree cleanup with no active todo item. Break the request down with todowrite first, then clean up worktrees.";
-				const toolRoot = await resolveCallWorkspace(toolContext); const res = cleanupGitWorktree(args.worktreePath, toolRoot); if (!res.success) return `[workflow-guard] Failed to clean up worktree: ${res.error}`;
+				const toolRoot = await resolveCallWorkspace(toolContext);
+				// Removal never delegates to the host: its `remove` takes a `force`
+				// flag and has no snapshot step, so it can destroy uncommitted work
+				// the guard's snapshot-then-remove flow preserves. The host list is
+				// used only to authorize a directory outside the guard's storage.
+				const hostWorktrees = hostWorktree?.available ? await hostWorktree.list() : undefined;
+				const res = cleanupGitWorktree(args.worktreePath, toolRoot, { hostWorktrees });
+				if (!res.success) return `[workflow-guard] Failed to clean up worktree: ${res.error}`;
+				// Tell the host its inventory is stale, or it keeps listing the
+				// removed directory until something else refreshes it.
+				await hostWorktree?.refresh();
 				const mutationRoot = await resolveCallWorkspace(toolContext);
 				await runWithRuntimeState(mutationRoot, client, async () => recordMutation((await effectiveTodoOwnerSessionID(toolContext.sessionID)) ?? toolContext.sessionID, toolContext.sessionID));
 				return `[workflow-guard] Worktree at '${args.worktreePath}' cleaned up successfully.`;

package/src/lib/guard-command.ts

@@ -0,0 +1,97 @@
+/**
+ * Server-side `/guard-status` command for OpenCode 2.
+ *
+ * Before this, the only way to read guard state from inside a session was the
+ * separately installed TUI companion, or knowing the `guard_status` tool name.
+ * `ctx.command.transform` registers a command that runs in every V2 client.
+ *
+ * The command computes the report from the guard's own `guard_status` tool and
+ * delivers it as a synthetic message. Two deliberate choices:
+ *
+ * - The report is not relayed through the model. `guard_status` is
+ *   authoritative state; asking a model to restate it would introduce a
+ *   paraphrase step between the operator and the evidence.
+ * - Delivery uses `session.synthetic`, so the command costs no model turn.
+ *   Synthetic messages do not run the `session.prompt` hook, so this cannot
+ *   churn recovery checkpoints.
+ */
+
+import type { Plugin } from "@opencode/plugin";
+import { audit } from "./audit.ts";
+import { runWithRuntimeState } from "./state.ts";
+
+/** The command id. Prefixed so it cannot shadow a user command by accident. */
+export const GUARD_STATUS_COMMAND = "guard-status";
+
+export interface GuardStatusCommandDeps {
+	/** Produces the same JSON report as the `guard_status` tool. */
+	runStatus: (sessionID: string) => Promise<string>;
+	effectiveRoot: string;
+	client: unknown;
+}
+
+interface CommandInvocation {
+	readonly sessionID: string;
+}
+
+/**
+ * Register the command. Registration is additive: a collision with an existing
+ * command id is the host's to resolve, and the `guard-` prefix keeps that from
+ * being accidental.
+ */
+export async function registerGuardStatusCommand(
+	ctx: Plugin.Context,
+	deps: GuardStatusCommandDeps,
+): Promise<void> {
+	const editorHost = ctx.command as unknown as {
+		transform: (callback: (editor: {
+			add: (definition: {
+				name: string;
+				description?: string;
+				execute: (input: CommandInvocation) => Promise<void>;
+			}) => void;
+		}) => void) => Promise<unknown>;
+	};
+	await editorHost.transform((editor) => {
+		editor.add({
+			name: GUARD_STATUS_COMMAND,
+			description: "Show Workflow Guard status: branch protection, mutation count, outstanding verification/review gates, and todo capability.",
+			execute: async ({ sessionID }) => {
+				let report: string;
+				try {
+					report = await deps.runStatus(sessionID);
+				} catch (error) {
+					report = JSON.stringify({
+						error: `guard_status could not be computed: ${(error as Error)?.message ?? "unknown error"}`,
+					});
+				}
+				audit({
+					ts: new Date().toISOString(),
+					sessionID,
+					tool: `command.${GUARD_STATUS_COMMAND}`,
+					decision: "allow",
+					phase: "event",
+					reason: "guard_status_command",
+				});
+				await runWithRuntimeState(deps.effectiveRoot, deps.client, async () => {
+					const session = ctx.session as unknown as {
+						synthetic: (input: { sessionID: string; text: string }) => Promise<unknown>;
+					};
+					try {
+						await session.synthetic({ sessionID, text: `## Workflow Guard status\n\n\`\`\`json\n${report}\n\`\`\`` });
+					} catch (error) {
+						// A client that cannot admit synthetic messages still needs the
+						// report to be visible; fall back to a normal prompt.
+						try {
+							console.warn(`[workflow-guard] warn: /${GUARD_STATUS_COMMAND} synthetic delivery failed (${(error as Error)?.message ?? "unknown error"}); falling back to a prompt.`);
+						} catch {}
+						const sessionPrompt = ctx.session as unknown as {
+							prompt: (input: { sessionID: string; text: string }) => Promise<unknown>;
+						};
+						await sessionPrompt.prompt({ sessionID, text: `Report this guard status verbatim:\n\n${report}` });
+					}
+				});
+			},
+		});
+	});
+}

package/src/lib/guard-dispatcher.ts

@@ -8,6 +8,7 @@ import {
 	getLiveControlPlaneRoots,
 	getSdkClient,
 	getSessionBoundWorkspace,
+	getSessionMutationCount,
 	getWorkspaceRoot,
 	isDocumentationRequired,
 	isReviewRequired,
@@ -17,6 +18,7 @@ import {
 	recordVerifyResult,
 	sessionMutationTimestamps,
 	sessionVerifyResults,
+	todoTaskStarts,
 } from "./state.ts";
 import {
 	dynamicShellSyntaxIn,
@@ -74,12 +76,31 @@ import {
 	effectiveTodos,
 	fetchSessionTodos,
 	hasActiveTodo,
+	readOnlyTodoCompletions,
+	recordTodoTaskStarts,
 	subagentMutationBudgetReason,
+	todoCompletionBlockReason,
+	unverifiedTodoCompletions,
 	validateTodoLifecycle,
 } from "../policies/todo.ts";
+import { recordedTodoCapability, reportTodoGateFailOpen } from "./v2-todo.ts";
 
 export const SHELL_TOOL_NAMES = new Set(["bash", "run_commands", "execute_command", "shell"]);
 
+/**
+ * Tools that can change repository or workspace state, and so sit behind the
+ * Policy 25 research floor. Widening past the edit/shell sets matters because
+ * the guard's own lifecycle tools mutate the repository without a shell.
+ */
+export function isMutatingSurfaceTool(toolName: string): boolean {
+	return (
+		EDIT_TOOL_NAMES.has(toolName) ||
+		SHELL_TOOL_NAMES.has(toolName) ||
+		toolName.startsWith("guard_worktree_") ||
+		toolName === "guard_recovery_restore"
+	);
+}
+
 // dynamic_shell_syntax is fail-closed by design; naming the construct and a
 // remedy keeps agents from retrying near-identical commands. Keyed by the
 // construct strings returned by dynamicShellSyntaxIn; unknown constructs fall
@@ -192,6 +213,22 @@ export async function guardToolCallImpl(
 				logPolicyBlock(`[workflow-guard] ${err}`);
 				return block("todo", "todo_lifecycle", err);
 			}
+			// Per-task completion evidence. Every task may enter `completed`
+			// only after the session mutated inside that task's window. The
+			// check is pure, so simulation reports the same verdict without
+			// journaling or moving any window.
+			const readOnlyCompleted: string[] = [];
+			if (context?.sessionID) {
+				const starts = todoTaskStarts(context.sessionID);
+				const total = getSessionMutationCount(context.sessionID);
+				const unverified = unverifiedTodoCompletions(existingTodos, newTodos, starts, total);
+				if (unverified.length > 0) {
+					const reason = todoCompletionBlockReason(unverified);
+					logPolicyBlock(`[workflow-guard] ${reason}`);
+					return block("todo", "todo_completion_unverified", reason);
+				}
+				if (!context.simulate) readOnlyCompleted.push(...readOnlyTodoCompletions(existingTodos, newTodos));
+			}
 			const allDone = newTodos.length > 0 && newTodos.every((t) => {
 				const s = String(t.status ?? "");
 				return s === "completed" || s === "cancelled";
@@ -227,6 +264,22 @@ export async function guardToolCallImpl(
 					}
 				}
 			}
+			// Only an accepted write becomes the task list, so task windows move
+			// and read-only marker use is journaled after every gate has passed.
+			if (context?.sessionID && !context.simulate) {
+				recordTodoTaskStarts(todoTaskStarts(context.sessionID), existingTodos, newTodos, getSessionMutationCount(context.sessionID));
+				if (readOnlyCompleted.length > 0) {
+					audit({
+						ts: new Date().toISOString(),
+						sessionID: context.sessionID,
+						tool: "todowrite",
+						decision: "allow",
+						phase: "event",
+						reason: "todo_completed_read_only",
+						input: { tasks: readOnlyCompleted, mutationCount: getSessionMutationCount(context.sessionID) },
+					});
+				}
+			}
 		}
 		return allow();
 	}
@@ -309,6 +362,23 @@ export async function guardToolCallImpl(
 			logPolicyBlock(`[workflow-guard] blocked ${toolName}: no active todo item (session ${context?.sessionID ?? "?"})`);
 			return block("todo", "no_active_todo", "Blocked: no active todo item. First break the request down with the todowrite tool (create items with status 'pending' or 'in_progress'), then work them through, marking each completed via todowrite as you finish it. When every item is completed, create a fresh todo list before starting new work.");
 		}
+		if (todos === undefined) {
+			// Fail-open, but never silent: once per session, record that the
+			// gate did not enforce and why. A rails policy that quietly stops
+			// enforcing is indistinguishable from one that was removed.
+			const capability = recordedTodoCapability();
+			if (reportTodoGateFailOpen(context?.sessionID, capability)) {
+				audit({
+					ts: new Date().toISOString(),
+					sessionID: context?.sessionID,
+					tool: "todo.gate",
+					decision: "allow",
+					phase: "event",
+					reason: `todo_gate_fail_open_${capability}`,
+					input: { [toolName]: true },
+				});
+			}
+		}
 		if (context?.sessionID) {
 			const reason = await subagentMutationBudgetReason(context.sessionID, currentRoot);
 			if (reason) {

package/src/lib/host-worktree.ts

@@ -0,0 +1,109 @@
+/**
+ * Host worktree port for the V2 native worktree API.
+ *
+ * The guard hand-rolls `git worktree add` and keeps its own storage directory,
+ * so worktrees it creates are invisible to the host's worktree inventory. The
+ * V2 API exposes `ctx.worktree` with `create`, `list`, `remove`, and `refresh`.
+ *
+ * Adoption is deliberately asymmetric, because the two paths do not carry the
+ * same guarantees:
+ *
+ * - **create** goes through the host first, so the worktree lands where the
+ *   operator configured `worktree.directory` and appears in host inventory.
+ *   The result is validated before it is accepted: the directory must exist,
+ *   must be a worktree of THIS repository, and must not be the primary tree.
+ *   Any failure falls back to the git implementation.
+ * - **remove** stays with the guard. The host's `remove` takes a `force` flag
+ *   and has no snapshot step, so it can destroy uncommitted work that the
+ *   guard's snapshot-then-remove flow preserves. After the guard removes a
+ *   worktree, the port calls `refresh` so host inventory does not keep a
+ *   stale entry.
+ * - **list** supplies the bounded, host-declared set of directories that
+ *   cleanup may touch. This is the same widening authority Task 3 gave
+ *   `hostWorktree`: the host says the directory is its worktree, and the
+ *   guard still independently requires a git registration and a non-primary
+ *   path.
+ *
+ * Unknown or unavailable host surfaces degrade to `undefined`, never to a
+ * guess. The git path stays the only authority for correctness.
+ */
+
+/** Narrow, duck-typed view of `ctx.worktree` so this module stays testable. */
+export interface HostWorktreeApi {
+	create(input: { projectID: string; branch?: string; from?: string; name?: string; directory?: string }): Promise<{ directory?: string } | undefined>;
+	list(input: { projectID: string }): Promise<ReadonlyArray<{ directory?: string }> | undefined>;
+	refresh(input: { projectID: string }): Promise<unknown>;
+}
+
+export interface HostWorktreePort {
+	/** True when the host exposes a usable project id and the create/list calls. */
+	readonly available: boolean;
+	/** Project id used for every call, or undefined when the host did not supply one. */
+	readonly projectID: string | undefined;
+	/**
+	 * Create a worktree. `from` is an absolute DIRECTORY path, matching the host
+	 * schema, not a git ref; callers that need a specific base ref use the git
+	 * path instead of passing a ref here.
+	 */
+	create(input: { branch: string; from?: string }): Promise<{ directory?: string; error?: string }>;
+	list(): Promise<readonly string[] | undefined>;
+	refresh(): Promise<void>;
+}
+
+const unavailable: HostWorktreePort = {
+	available: false,
+	projectID: undefined,
+	create: async () => ({ error: "host worktree API unavailable" }),
+	list: async () => undefined,
+	refresh: async () => {},
+};
+
+/**
+ * Build the port from a V2 plugin context. A missing API, a missing project id,
+ * or a throwing call all downgrade to the git path instead of failing the tool.
+ */
+export function createHostWorktreePort(ctx: unknown): HostWorktreePort {
+	const context = ctx as {
+		location?: { project?: { id?: unknown } };
+		worktree?: Partial<HostWorktreeApi>;
+	} | undefined;
+	const api = context?.worktree;
+	const rawProjectID = context?.location?.project?.id;
+	const projectID = typeof rawProjectID === "string" && rawProjectID.length > 0 ? rawProjectID : undefined;
+	if (!api || typeof api.create !== "function" || typeof api.list !== "function" || !projectID) {
+		return unavailable;
+	}
+	const create = api.create.bind(api);
+	const list = api.list.bind(api);
+	const refresh = typeof api.refresh === "function" ? api.refresh.bind(api) : undefined;
+	return {
+		available: true,
+		projectID,
+		create: async ({ branch, from }) => {
+			try {
+				const result = await create({ projectID, branch, ...(from ? { from } : {}), name: branch.replace(/[/\\:]/g, "-") });
+				const directory = typeof result?.directory === "string" && result.directory.length > 0 ? result.directory : undefined;
+				return directory ? { directory } : { error: "host worktree create returned no directory" };
+			} catch (error) {
+				return { error: `host worktree create failed: ${(error as Error)?.message ?? String(error)}` };
+			}
+		},
+		list: async () => {
+			try {
+				const result = await list({ projectID });
+				if (!Array.isArray(result)) return undefined;
+				return result
+					.map((entry) => (typeof entry?.directory === "string" ? entry.directory : undefined))
+					.filter((directory): directory is string => Boolean(directory));
+			} catch {
+				return undefined;
+			}
+		},
+		refresh: async () => {
+			if (!refresh) return;
+			try {
+				await refresh({ projectID });
+			} catch {}
+		},
+	};
+}

package/src/lib/mcp-inventory.ts

@@ -0,0 +1,86 @@
+/**
+ * Host MCP server inventory for the guard's MCP policy.
+ *
+ * The MCP policy identifies a guarded live-system call by name tokens
+ * (`github`, `azure`, `ado`, ...). That static list covers the common servers,
+ * but it cannot learn a server the operator renamed, and it cannot tell when
+ * the host's roster changed.
+ *
+ * `ctx.mcp.list()` reports the servers for this location, and the
+ * `mcp.tools.changed` event says when that roster went stale. Together they
+ * widen the guarded token set from host-declared names only.
+ *
+ * Two deliberate limits:
+ *
+ * - **Widen-only.** A server the operator removed must not silently unguard a
+ *   tool that still names it. Removal therefore contributes nothing; the
+ *   static defaults in `policies/mcp.ts` remain the floor.
+ * - **Never a replacement for the policy.** A token learned here only reaches
+ *   the same `mcpMutationTool` decision the static list already used. Nothing
+ *   here can allow a call the policy would otherwise block.
+ */
+
+import { addGuardedMcpTokens, GUARDED_MCP_SERVERS } from "../policies/mcp.ts";
+
+/** A server name counts as guarded when it names a known live-system product. */
+const GUARDED_SERVER_TOKEN_RE =
+	/(?:^|[^a-z0-9])(?:github|gh|azure|azmcp|ado|devops|azuredevops)(?:[^a-z0-9]|$)/;
+
+/**
+ * Turn a host server name into tokens for the policy's token scan.
+ *
+ * Host names are free-form (`github`, `github-enterprise`, `Azure DevOps`), so
+ * a guarded server contributes its tokens rather than a single literal. A name
+ * that does not look guarded contributes nothing.
+ */
+export function guardedTokensFromServerName(serverName: string): string[] {
+	if (!serverName || !GUARDED_SERVER_TOKEN_RE.test(serverName.toLowerCase())) return [];
+	return serverName
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, " ")
+		.trim()
+		.split(" ")
+		.filter(Boolean);
+}
+
+/**
+ * Read the MCP servers the host reports.
+ *
+ * `undefined` means "the host could not tell us", which is different from an
+ * empty roster. Callers must not treat unknown as "nothing is guarded".
+ *
+ * The 2.0.10 MCP domain types `list` with a location filter and returns
+ * `{ data: [...] }`; the duck-typed read tolerates a bare array too, because a
+ * shape mismatch must degrade to unknown rather than throw.
+ */
+export async function listHostMcpServerNames(ctx: unknown): Promise<string[] | undefined> {
+	const api = (ctx as { mcp?: { list?: (input?: unknown) => Promise<unknown> } } | undefined)?.mcp;
+	if (!api || typeof api.list !== "function") return undefined;
+	try {
+		const result = await api.list.call(api, {});
+		const data = (result as { data?: unknown } | undefined)?.data;
+		const entries = Array.isArray(data) ? data : Array.isArray(result) ? result : undefined;
+		if (!entries) return undefined;
+		return entries
+			.map((entry) => (typeof entry === "string" ? entry : (entry as { name?: unknown })?.name))
+			.filter((name): name is string => typeof name === "string" && name.length > 0);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Merge host-declared server names into the guarded token set.
+ *
+ * Returns the tokens this call added, so the caller can journal widening once
+ * instead of logging the whole set on every event. `undefined` input (host
+ * could not answer) adds nothing and is not an error.
+ */
+export function recordHostMcpServers(serverNames: readonly string[] | undefined): string[] {
+	if (!serverNames) return [];
+	const tokens = serverNames.flatMap((name) => guardedTokensFromServerName(name));
+	return addGuardedMcpTokens(tokens);
+}
+
+/** Static defaults, for callers that only need to report the floor. */
+export const STATIC_GUARDED_MCP_SERVERS = GUARDED_MCP_SERVERS;

package/src/lib/permission-seat.ts

@@ -0,0 +1,119 @@
+/**
+ * V2 permission seat: `ctx.permission.hook("evaluate")`.
+ *
+ * Two enforcement seats, deliberately complementary:
+ *
+ * - `evaluate` sees the host's normalized permission check (an `action` plus
+ *   its `resources`) before anything runs, so a denial there means the tool
+ *   never starts. It does NOT see raw tool input, so tool-lifecycle work
+ *   (todo transitions, stale-write observations, post-edit snapshots) stays in
+ *   `execute.before`.
+ * - `execute.before` sees the raw arguments and aborts with a specific
+ *   remediation message, but only after the permission layer has allowed.
+ *
+ * The seat can only tighten. An explicit configured `deny` is final: the host
+ * never invokes the hook for it (it resolves deny first and only calls the hook
+ * when the configured effect is allow/ask). A hook denial is therefore always a
+ * response to something the host would otherwise permit.
+ *
+ * Every decision here is a simulation of the policy core: `simulate: true`
+ * skips mutation accounting, file claims, verification runs, and durable audit
+ * writes, because the same call is evaluated for real in `execute.before`.
+ */
+
+import { guardToolCallImpl } from "./guard-dispatcher.ts";
+import { getSessionBoundWorkspace, runWithRuntimeState } from "./state.ts";
+import { mcpMutationTool } from "../policies/mcp.ts";
+import type { PolicyDecision } from "./types.ts";
+
+/** The subset of the host's permission evaluation this seat reads. */
+export interface PermissionSeatEvent {
+	readonly sessionID: string;
+	readonly agent?: string;
+	readonly action: string;
+	readonly resources: readonly string[];
+	readonly effect: "allow" | "deny" | "ask";
+}
+
+export interface PermissionSeatDeps {
+	workspaceRoot: string;
+	client: unknown;
+}
+
+export interface PermissionSeatResult {
+	/** The effect the seat leaves in place. */
+	effect: "allow" | "deny";
+	/** Set only when the seat denied. */
+	decision?: PolicyDecision;
+	/** The guard tool the action was mapped onto, for attribution. */
+	mappedTool?: string;
+}
+
+const EDIT_ACTIONS = new Set(["edit", "write", "patch", "apply_patch"]);
+
+function mappedToolFor(action: string): { tool: string; input: (resource: string) => unknown } | undefined {
+	if (action === "shell" || action === "bash") {
+		return { tool: "bash", input: (resource) => ({ command: resource }) };
+	}
+	if (action === "read" || action === "read_file") {
+		return { tool: "read", input: (resource) => ({ filePath: resource }) };
+	}
+	if (EDIT_ACTIONS.has(action)) {
+		// `edit` is the canonical mutation tool name: it carries the tamper,
+		// secret, boundary, protected-branch, and todo checks.
+		return { tool: "edit", input: (resource) => ({ filePath: resource }) };
+	}
+	return undefined;
+}
+
+/**
+ * Evaluate one host permission request. Returns the effect to leave in place.
+ *
+ * Unmapped actions (`external_directory`, `glob`, `grep`, `webfetch`,
+ * `websearch`, `question`, `subagent`, ...) stay with the host: config policy
+ * and the user prompt are the right seats for them, and the guard's shell,
+ * file, and MCP checks have nothing to add. The hook still journals them.
+ */
+export async function evaluatePermissionSeat(
+	event: PermissionSeatEvent,
+	deps: PermissionSeatDeps,
+): Promise<PermissionSeatResult> {
+	if (event.effect === "deny") return { effect: "deny" };
+	const resources = event.resources.filter((resource): resource is string => typeof resource === "string" && resource.length > 0);
+	if (resources.length === 0) return { effect: "allow" };
+	const workspaceRoot = getSessionBoundWorkspace(event.sessionID) || deps.workspaceRoot;
+	const context = { sessionID: event.sessionID, agent: event.agent, worktree: workspaceRoot, simulate: true };
+	const decide = (tool: string, input: unknown): Promise<PolicyDecision> =>
+		runWithRuntimeState(workspaceRoot, deps.client, () => guardToolCallImpl(tool, input, context));
+
+	const mapping = mappedToolFor(event.action);
+	if (mapping) {
+		for (const resource of resources) {
+			const decision = await decide(mapping.tool, mapping.input(resource));
+			if (decision.status !== "allowed") {
+				return {
+					effect: "deny",
+					decision: { ...decision, message: `[workflow-guard permission.evaluate] ${decision.message}` },
+					mappedTool: mapping.tool,
+				};
+			}
+		}
+		return { effect: "allow", mappedTool: mapping.tool };
+	}
+
+	// `<server>_<tool>` MCP actions: only the guarded live-system servers are
+	// mapped (GitHub/Azure DevOps), matching the execute.before MCP policy.
+	for (const resource of resources) {
+		if (!mcpMutationTool(event.action) && !mcpMutationTool(resource)) continue;
+		const decision = await decide(event.action, {});
+		if (decision.status !== "allowed") {
+			return {
+				effect: "deny",
+				decision: { ...decision, message: `[workflow-guard permission.evaluate] ${decision.message}` },
+				mappedTool: event.action,
+			};
+		}
+		return { effect: "allow", mappedTool: event.action };
+	}
+	return { effect: "allow" };
+}