opencode-workflow-guard 1.1.5 → 1.3.0

package/src/workflow-guard.ts

@@ -1,2321 +1,229 @@
 /**
  * Workflow Guard Plugin for OpenCode (hooks-only - no prompt rules)
  *
- * Deterministic enforcement via the `tool.execute.before` plugin hook
- * (https://opencode.ai/docs/plugins/). Throwing from the hook blocks the
- * tool call outright.
+ * Deterministic enforcement via the tool.execute.before plugin hook.
+ * Throwing from the hook blocks the tool call outright.
  *
- *  1. Task gate: file-editing tools (edit/write/apply_patch) are blocked
- *     until the session's NATIVE todo list (the built-in `todowrite` tool,
- *     https://opencode.ai/docs/tools/#todowrite) has at least one active
- *     item (pending/in_progress). Once every item is completed/cancelled,
- *     edits block again - forcing a fresh breakdown per request. Subagent
- *     sessions (todowrite is denied for them by default) inherit the todo
- *     list of their parent session.
- *  2. Git pushes to main/master (incl. refspecs like HEAD:main or :main)
- *     are hard-blocked.
- *  3. PR creation (gh) requires a changelog - either a CHANGELOG update in
- *     the branch's diff or a "Changelog:" section in the PR body.
- *  4. Live-system guard: destructive commands targeting infrastructure,
- *     databases, or remote APIs are blocked unless the USER overrides with
- *     WORKFLOW_GUARD_ALLOW_LIVE=1 in the environment before launch. There
- *     is deliberately no in-command override - the agent cannot grant it
- *     to itself.
- *  5. MCP mutation guard: GitHub / Azure DevOps MCP tools with mutation
- *     verbs in their names are blocked (read-only verbs pass).
- *  6. Settings tamper guard: the agent cannot edit opencode.json /
- *     permission config / the guard's own plugin files - via shell OR via
- *     the file-editing tools - or run `opencode auth` to weaken its gates.
- *  7. Branch guard: on main/master, file mutations and history-changing
- *     git commands are blocked until a feature branch is created.
- *  8. Workspace boundary guard: file mutations cannot escape the workspace
- *     root - via edit tools, patches, or shell redirection/copy commands.
- *  9. Script laundering guard: content written via edit/write/apply_patch
- *     is scanned for destructive commands, so `write deploy.sh` followed by
- *     `bash deploy.sh` cannot smuggle blocked operations past the shell
- *     guards.
- *
- * Known limits (defense in depth, not a sandbox): these guards match on
- * command/file strings. An agent that base64-encodes a payload or invokes
- * an interpreter directly (`python3 -c ...`) can evade pattern matching.
- * Pair this plugin with OS-level isolation (branch protection, containers)
- * for hard guarantees.
- *
- * Install: copy this file into <project>/.opencode/plugins/ or
- * ~/.config/opencode/plugins/ - files there are auto-loaded at startup.
- * Requires opencode >= 1.18 (todo endpoint GET /session/:id/todo).
- */
-
-import { spawnSync, spawn } from "node:child_process";
-import { mkdirSync, realpathSync, readFileSync, writeFileSync, appendFileSync, existsSync, symlinkSync, rmSync, lstatSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, join, relative, resolve, sep } from "node:path";
-import { tool, type Plugin, type PluginModule } from "@opencode-ai/plugin";
-
-// OpenCode built-in tools (https://opencode.ai/docs/tools/): bash is the
-// shell tool. Legacy/alias names are kept for compatibility.
-const SHELL_TOOL_NAMES = new Set(["bash", "run_commands", "execute_command", "shell"]);
-
-const PROTECTED_BRANCHES = new Set(["main", "master"]);
-
-let workspaceRoot = process.cwd();
-let workspaceRootReal = workspaceRoot;
-try {
-	workspaceRootReal = realpathSync(workspaceRoot);
-} catch {}
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) {
-		return undefined;
-	}
-	return value as Record<string, unknown>;
-}
-
-/** Pull the command string(s) out of a shell tool input. */
-function extractCommands(input: unknown): string[] {
-	if (typeof input === "string") {
-		return [input];
-	}
-	const record = asRecord(input);
-	if (!record) {
-		return [];
-	}
-	const commands: string[] = [];
-	if (typeof record.command === "string") commands.push(record.command);
-	if (Array.isArray(record.commands)) {
-		for (const c of record.commands) {
-			if (typeof c === "string") commands.push(c);
-		}
-	}
-	return commands;
-}
-
-/** Normalize a command for matching: collapse whitespace. */
-function normalize(cmd: string): string {
-	return cmd.replace(/\s+/g, " ");
-}
-
-function shellWords(command: string): string[] {
-	return (command.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? []).map((word) =>
-		word.replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/, "$1$2"),
-	);
-}
-
-function splitShellSegments(command: string): string[] {
-	const segments: string[] = [];
-	let current = "";
-	let quote: "'" | '"' | undefined;
-	let escaped = false;
-	for (const char of command) {
-		if (escaped) {
-			current += char;
-			escaped = false;
-			continue;
-		}
-		if (char === "\\" && quote !== "'") {
-			current += char;
-			escaped = true;
-			continue;
-		}
-		if (char === "'" || char === '"') {
-			if (!quote) quote = char;
-			else if (quote === char) quote = undefined;
-			current += char;
-			continue;
-		}
-		if (!quote && /[\n|;&]/.test(char)) {
-			if (current.trim()) segments.push(current.trim());
-			current = "";
-			continue;
-		}
-		current += char;
-	}
-	if (current.trim()) segments.push(current.trim());
-	return segments;
-}
-
-/** Remove common command wrappers while preserving the underlying invocation. */
-function unwrapShellWords(command: string): string[] {
-	const words = shellWords(command.trim());
-	let i = 0;
-	while (i < words.length) {
-		if (words[i] === "command") {
-			i++;
-			continue;
-		}
-		if (words[i] === "sudo") {
-			i++;
-			const valueOptions = new Set(["-u", "--user", "-g", "--group", "-h", "--host", "-p", "--prompt", "-C", "--close-from", "-R", "--chroot", "-D", "--chdir"]);
-			while (i < words.length && words[i]!.startsWith("-")) {
-				const option = words[i++]!;
-				if (valueOptions.has(option) && i < words.length) i++;
-			}
-			continue;
-		}
-		if (words[i] === "env") {
-			i++;
-			const valueOptions = new Set(["-u", "--unset", "-C", "--chdir", "-S", "--split-string"]);
-			while (i < words.length) {
-				const word = words[i]!;
-				if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) {
-					i++;
-					continue;
-				}
-				if (!word.startsWith("-")) break;
-				i++;
-				if (valueOptions.has(word) && i < words.length) i++;
-			}
-			continue;
-		}
-		if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]!)) {
-			i++;
-			continue;
-		}
-		break;
-	}
-	return words.slice(i);
-}
-
-function unwrapShellCommand(command: string): string {
-	return unwrapShellWords(command).join(" ");
-}
-
-// Matches a direct push of main|master: "git push origin main",
-// "git push main", "git push origin local:main" (refspec), "git push
-// origin :main" (branch deletion), "git push origin +HEAD:master" (forced
-// refspec). The right-hand side of a refspec must be exactly main/master -
-// feature/main-fix or HEAD:main-backup are fine.
-const PUSH_TO_MAIN_RE =
-	/\bgit\s+push\b[^|;&]*(?:^|\s)\+?[\w./-]*:(?:main|master)(?![\w./-])|\bgit\s+push\b[^|;&]*(?:\s|\/)(?:main|master)(?![\w./-])/;
-const CHANGELOG_SECTION_RE = /^\s*(?:#{1,6}\s*)?changelog\s*(?::|$)/im;
-
-function hasPrCreateInvocation(command: string): boolean {
-	return splitShellSegments(command)
-		.some((seg) => {
-			const trimmed = unwrapShellCommand(seg);
-			return (
-				/^gh\b[^|;&]*\bpr\s+create\b/.test(trimmed) ||
-				/^az\b[^|;&]*\brepos\s+pr\s+create\b/.test(trimmed)
-			);
-		});
-}
-
-// ── Task gate (native session todos) ─────────────────────────────────────────
-// opencode has a built-in per-session todo system: the `todowrite` tool
-// stores the list server-side (documented endpoint GET /session/:id/todo,
-// served through the SDK client plugins receive as ctx.client). The task
-// gate requires ACTIVE work in that list before any file edit.
-
-// OpenCode file-mutation tools: `edit`, `write`, `apply_patch` (the `edit`
-// permission covers all three per the permissions docs; the tools docs
-// explicitly note apply_patch is reported as "apply_patch", not "patch").
-const EDIT_TOOL_NAMES = new Set(["edit", "write", "patch", "apply_patch"]);
-
-// Subagent sessions spawn with `todowrite` denied (documented: "This tool
-// is disabled for subagents by default"), so a subagent's own list is
-// usually empty - the gate then falls back to the parent session's list
-// (sessions expose parentID) so delegated work stays gated on the
-// orchestrator's breakdown.
-
-const ACTIVE_TODO_STATUSES = new Set(["pending", "in_progress"]);
-
-export interface TodoItem {
-	content?: unknown;
-	status?: unknown;
-}
-
-// Minimal structural type for the SDK client (documented endpoints
-// GET /session/:id/todo, GET /session/:id, POST /tui/show-toast). Kept structural -
-// not the generated SDK types - so the plugin tolerates SDK minor-version drift.
-export interface TodoSdkClient {
-	session?: {
-		todo?: (opts: { path: { id: string } }) => Promise<{ data?: unknown }>;
-		get?: (opts: { path: { id: string } }) => Promise<{ data?: { parentID?: unknown } }>;
-	};
-	tui?: {
-		showToast?: (opts: { body: { title?: string; message: string; variant?: string } }) => Promise<unknown>;
-	};
-}
-
-let sdkClient: TodoSdkClient | undefined;
-
-/** Provide the SDK client (the plugin passes ctx.client; tests inject a fake). */
-export function setSdkClient(client: unknown): void {
-	sdkClient = client as TodoSdkClient | undefined;
-}
-
-async function fetchSessionTodos(sessionID: string): Promise<TodoItem[] | undefined> {
-	const session = sdkClient?.session;
-	const todo = session?.todo;
-	if (typeof todo !== "function") return undefined;
-	try {
-		const result = await todo.call(session, { path: { id: sessionID } });
-		const data = (result as { data?: unknown } | undefined)?.data;
-		return Array.isArray(data) ? (data as TodoItem[]) : undefined;
-	} catch {
-		return undefined;
-	}
-}
-
-async function fetchParentSessionID(sessionID: string): Promise<string | undefined> {
-	const session = sdkClient?.session;
-	const get = session?.get;
-	if (typeof get !== "function") return undefined;
-	try {
-		const result = await get.call(session, { path: { id: sessionID } });
-		const parent = (result as { data?: { parentID?: unknown } } | undefined)?.data?.parentID;
-		return typeof parent === "string" && parent ? parent : undefined;
-	} catch {
-		return undefined;
-	}
-}
-
-/**
- * Todos governing a session: its own list, or - when it has none (typically
- * subagents, which cannot todowrite) - the nearest ancestor session's list.
- * Returns undefined when the list cannot be determined (client missing or
- * fetch failed); the gate then fails open instead of bricking the agent.
- */
-async function effectiveTodos(
-	sessionID: string | undefined,
-): Promise<TodoItem[] | undefined> {
-	if (!sessionID) return undefined;
-	const seen = new Set<string>();
-	let current: string | undefined = sessionID;
-	while (current && !seen.has(current)) {
-		seen.add(current);
-		const todos = await fetchSessionTodos(current);
-		if (todos === undefined) return undefined;
-		if (todos.length > 0) return todos;
-		current = await fetchParentSessionID(current);
-	}
-	return [];
-}
-
-async function effectiveTodoOwnerSessionID(
-	sessionID: string | undefined,
-): Promise<string | undefined> {
-	if (!sessionID) return undefined;
-	const seen = new Set<string>();
-	let current: string | undefined = sessionID;
-	while (current && !seen.has(current)) {
-		seen.add(current);
-		const todos = await fetchSessionTodos(current);
-		if (todos === undefined) return sessionID;
-		if (todos.length > 0) return current;
-		current = await fetchParentSessionID(current);
-	}
-	return sessionID;
-}
-
-function hasActiveTodo(todos: TodoItem[]): boolean {
-	return todos.some((todo) => ACTIVE_TODO_STATUSES.has(String(todo.status ?? "")));
-}
-
-/**
- * Validates todo discipline rules:
- *  1. Task lifecycle: active tasks cannot silently vanish without being marked
- *     'completed' or 'cancelled'.
- */
-export function validateTodoLifecycle(
-	newTodos: TodoItem[],
-	existingTodos: TodoItem[] | undefined,
-): string | undefined {
-	// Rule: No silent task deletion while active work remains
-	if (existingTodos && existingTodos.length > 0) {
-		const activeExisting = existingTodos.filter((t) => {
-			const s = String(t.status ?? "");
-			return s === "pending" || s === "in_progress";
-		});
-		if (activeExisting.length > 0) {
-			const newContentCounts = new Map<string, number>();
-			for (const todo of newTodos) {
-				const content = String(todo.content ?? "").trim();
-				newContentCounts.set(content, (newContentCounts.get(content) ?? 0) + 1);
-			}
-			const missing = activeExisting.find((todo) => {
-				const content = String(todo.content ?? "").trim();
-				const remaining = newContentCounts.get(content) ?? 0;
-				if (remaining === 0) return true;
-				newContentCounts.set(content, remaining - 1);
-				return false;
-			});
-			if (missing) {
-				return (
-					`Blocked todowrite: active task '${String(missing.content ?? "")}' was removed ` +
-					"without being marked completed or cancelled. Tasks cannot silently disappear."
-				);
-			}
-		}
-	}
-
-	return undefined;
-}
-
-// ── Workspace boundary guard ─────────────────────────────────────────────────
-
-function isPathOutsideWorkspace(targetPath: string, root: string): boolean {
-	if (!targetPath) return false;
-	const resolved = resolve(root, targetPath);
-	const normalizedRoot = root.endsWith("/") ? root : root + "/";
-	if (resolved !== root && !resolved.startsWith(normalizedRoot)) {
-		return true;
-	}
-	// Verify symlink resolution against workspaceRootReal
-	try {
-		const real = realpathSync(resolved);
-		const realRoot = workspaceRootReal.endsWith("/") ? workspaceRootReal : workspaceRootReal + "/";
-		if (real !== workspaceRootReal && !real.startsWith(realRoot)) {
-			return true;
-		}
-	} catch {
-		// Target does not exist yet (e.g. creating new file). Check closest existing ancestor directory.
-		let curr = resolved;
-		while (curr && curr !== "/" && curr !== ".") {
-			const parent = resolve(curr, "..");
-			if (parent === curr) break;
-			curr = parent;
-			try {
-				const realParent = realpathSync(curr);
-				const realRoot = workspaceRootReal.endsWith("/") ? workspaceRootReal : workspaceRootReal + "/";
-				if (realParent !== workspaceRootReal && !realParent.startsWith(realRoot)) {
-					return true;
-				}
-				break;
-			} catch {}
-		}
-	}
-	return false;
-}
-
-function extractPatchPaths(patchText: string): string[] {
-	const paths: string[] = [];
-	const markerRe =
-		/^\*\*\*\s+(?:Add File|Update File|Delete File|Move to|Move from):\s*(\S+)/gm;
-	let match: RegExpExecArray | null;
-	while ((match = markerRe.exec(patchText)) !== null) {
-		if (match[1]) paths.push(match[1]);
-	}
-	const diffRe = /^(?:---|\+\+\+)\s+(?:[ab]\/)?(\S+)/gm;
-	while ((match = diffRe.exec(patchText)) !== null) {
-		if (match[1] && match[1] !== "/dev/null") paths.push(match[1]);
-	}
-	return paths;
-}
-
-// ── Shell file-mutation heuristic ────────────────────────────────────────────
-// The edit/write/apply_patch gates (todo, branch, boundary) are meaningless
-// if the same mutations can happen through the shell. These heuristics catch
-// the common file-writing shell idioms so the same gates apply. This is a
-// heuristic, not a shell parser: exotic redirects can evade it, which is why
-// content scanning of edit payloads (script-laundering guard) also exists.
-
-interface ShellMutation {
-	kind: "redirect" | "command";
-	target?: string;
-	what: string;
-}
-
-/** Extract file paths mutated by a single shell command segment. */
-function shellMutationIn(segment: string): ShellMutation | undefined {
-	// Redirection to a file: > file, >> file, 2> file, | tee file
-	const redirectMatch = segment.match(
-		/(?:^|\s|>)(?:[0-9]*>>?)\s*["']?([^\s>&|;"']+)/,
-	);
-	if (redirectMatch?.[1]) {
-		if (/^\/dev\/(?:null|stdout|stderr|tty|fd\/\d+)$/.test(redirectMatch[1])) {
-			return undefined;
-		}
-		return {
-			kind: "redirect",
-			target: redirectMatch[1],
-			what: `file redirect to '${redirectMatch[1]}'`,
-		};
-	}
-	const teeMatch = segment.match(/\btee\s+(?:-a\s+)?["']?([^\s;&|"']+)/);
-	if (teeMatch?.[1]) {
-		return {
-			kind: "command",
-			target: teeMatch[1],
-			what: `tee to '${teeMatch[1]}'`,
-		};
-	}
-	// In-place editing: sed -i file …
-	const sedMatch = segment.match(/\bsed\s+(?:-(?:[a-zA-Z]*i[a-zA-Z]*|i\S*)\s+)+[^\s;&|]+/);
-	if (sedMatch) {
-		// first non-flag token after the -i flags is the script; the file is
-		// the LAST token (sed -i 's/x/y/' file)
-		const tokens = sedMatch[0]!.split(/\s+/);
-		const target = tokens[tokens.length - 1];
-		return { kind: "command", target, what: `sed -i on '${target}'` };
-	}
-	const transfer = filesystemTransferInfo(segment);
-	if (transfer?.destination) {
-		return {
-			kind: "command",
-			target: transfer.destination,
-			what: `copy/move/link to '${transfer.destination}'`,
-		};
-	}
-	// Common single-target filesystem mutations. Flags are tolerated; the
-	// final operand is the target for these forms.
-	const fsMutationMatch = segment.match(
-		/\b(?:touch|mkdir|rm|unlink|rmdir|ln)\b[^|;&]*\s+["']?([^\s;&|"']+)["']?\s*$/,
-	);
-	if (fsMutationMatch?.[1] && !fsMutationMatch[1].startsWith("-")) {
-		return {
-			kind: "command",
-			target: fsMutationMatch[1],
-			what: `filesystem mutation of '${fsMutationMatch[1]}'`,
-		};
-	}
-	// Copy/move into the workspace: cp/mv/rsync … dest
-	const copyMatch = segment.match(
-		/\b(?:cp|mv|rsync|install|cpio|scp|wget|curl)\b[^|;&]*?(-o\s+)?(["']?)([^\s;&|"']+)\2?\s*$/,
-	);
-	if (copyMatch?.[3] && /\b(?:cp|mv|rsync|install)\b/.test(segment)) {
-		return {
-			kind: "command",
-			target: copyMatch[3],
-			what: `copy/move to '${copyMatch[3]}'`,
-		};
-	}
-	// git apply / git am (mutates working tree via patch stdin/file)
-	if (/\bgit\s+(?:apply|am)\b/.test(segment)) {
-		return { kind: "command", what: "git apply/am (patch via shell)" };
-	}
-	return undefined;
-}
-
-function simpleFilesystemMutations(segment: string): ShellMutation[] {
-	const words = shellWords(unwrapShellCommand(segment));
-	const command = words[0];
-	if (!command || !new Set(["touch", "mkdir", "rm", "unlink", "rmdir"]).has(command)) {
-		return [];
-	}
-	return words
-		.slice(1)
-		.filter((word) => !word.startsWith("-"))
-		.map((target) => ({
-			kind: "command" as const,
-			target,
-			what: `filesystem mutation of '${target}'`,
-		}));
-}
-
-function filesystemTransferInfo(
-	segment: string,
-): { sources: string[]; destination?: string } | undefined {
-	const words = shellWords(unwrapShellCommand(segment));
-	if (!words[0] || !new Set(["cp", "mv", "ln"]).has(words[0])) return undefined;
-	const operands: string[] = [];
-	let targetDirectory: string | undefined;
-	for (let i = 1; i < words.length; i++) {
-		const word = words[i]!;
-		if (word === "-t" || word === "--target-directory") {
-			targetDirectory = words[++i];
-			continue;
-		}
-		if (word.startsWith("--target-directory=")) {
-			targetDirectory = word.slice("--target-directory=".length);
-			continue;
-		}
-		if (word.startsWith("-")) continue;
-		operands.push(word);
-	}
-	if (targetDirectory) return { sources: operands, destination: targetDirectory };
-	return {
-		sources: operands.slice(0, -1),
-		destination: operands.at(-1),
-	};
-}
-
-function secretSourceInFilesystemCommand(segment: string): string | undefined {
-	const transfer = filesystemTransferInfo(segment);
-	if (!transfer) return undefined;
-	for (const source of transfer.sources) {
-		if (isSecretPath(source)) return source;
-	}
-	return undefined;
-}
-
-/**
- * Mutations via the shell are subject to the same gates as direct edits:
- * todo activity, branch protection (targets inside the workspace) and the
- * workspace boundary (targets must not escape). Returns a block reason.
- */
-async function guardShellMutation(
-	command: string,
-	sessionID: string | undefined,
-): Promise<string | undefined> {
-	let hasMutation = false;
-	for (const segment of command.split(/[\n|;&]+/)) {
-		const secretSource = secretSourceInFilesystemCommand(segment);
-		if (secretSource) {
-			return `Blocked: shell command would copy, move, or link sensitive file '${secretSource}' under a non-secret name.`;
-		}
-		// mv mutates its SOURCES too (they are removed from their origin), so
-		// sources must respect the same boundaries as mutation targets: no
-		// moving files in from outside the workspace, no moving protected
-		// (settings/plugin) files to innocuous names.
-		const transfer = filesystemTransferInfo(segment);
-		if (transfer && shellWords(unwrapShellCommand(segment))[0] === "mv") {
-			for (const source of transfer.sources) {
-				if (isProtectedPath(source)) {
-					return PROTECTED_PATH_REASON;
-				}
-				if (isPathOutsideWorkspace(source, workspaceRoot)) {
-					return `Blocked: mv would remove source '${source}' from outside the workspace root (${workspaceRoot}). File mutations must stay within the workspace.`;
-				}
-			}
-		}
-		const simpleMutations = simpleFilesystemMutations(segment);
-		const fallbackMutation = shellMutationIn(segment.trim());
-		const mutations = simpleMutations.length > 0
-			? simpleMutations
-			: fallbackMutation
-				? [fallbackMutation]
-				: [];
-		for (const mutation of mutations) {
-			hasMutation = true;
-			const secret = secretIn(segment);
-			if (secret) {
-				return `Blocked: shell file mutation payload appears to contain a ${secret}. Secrets must not be written to disk from agent commands.`;
-			}
-			const target = mutation.target ?? "";
-			// git apply/am has no explicit filename target - treat as workspace
-			// mutation: subject to todo + branch gates, boundary implicit.
-			if (target && isProtectedPath(target)) {
-				return PROTECTED_PATH_REASON;
-			}
-			if (target && isPathOutsideWorkspace(target, workspaceRoot)) {
-				// The workspace boundary has no override: a write outside the
-				// workspace is out of bounds even with WORKFLOW_GUARD_ALLOW_LIVE
-				// (that override covers live-system commands, not the boundary).
-				return `Blocked: shell mutation '${mutation.what}' targets a path outside the workspace root (${workspaceRoot}). All changes must stay within the workspace.`;
-			}
-			if (onProtectedBranch(workspaceRoot)) {
-				return branchGuardReason();
-			}
-			const todos = await effectiveTodos(sessionID);
-			if (todos !== undefined && !hasActiveTodo(todos)) {
-				return (
-					"Blocked: shell file mutation with no active todo item. " +
-					"Break the request down with todowrite first, then apply " +
-					"changes (the same gates apply to shell redirects, tee, " +
-					"sed -i, cp/mv and git apply as to the edit tools)."
-				);
-			}
-		}
-	}
-	if (hasMutation) {
-		recordMutation(await effectiveTodoOwnerSessionID(sessionID));
-	}
-	return undefined;
-}
-
-// ── Branch guard ─────────────────────────────────────────────────────────────
-
-// Git global options that change which repository/work-tree a command acts
-// on. These must be parsed (not regexed around) so that e.g.
-// `git -C /other/repo commit` is gated on /other/repo's branch, not ours.
-const GIT_DIR_OPTION_TAKES_VALUE = new Set([
-	"-C",
-	"--git-dir",
-	"--work-tree",
-	"-c",
-	"--config-env",
-	"--namespace",
-]);
-const GIT_DIR_OPTION_PREFIXED =
-	/^(--git-dir=|--work-tree=|--namespace=|-c\S|--config-env=)/;
-const GIT_GLOBAL_BOOLEAN_OPTIONS = new Set([
-	"--version",
-	"--help",
-	"--no-pager",
-	"-p",
-	"--paginate",
-	"--bare",
-	"--literal-pathspecs",
-	"--glob-pathspecs",
-	"--noglob-pathspecs",
-	"--icase-pathspecs",
-	"--no-optional-locks",
-	"--exec-path",
-]);
-
-interface GitInvocation {
-	repoDir: string;
-	rest: string;
-}
-
-/**
- * Parse the leading global options off a `git …` command segment, returning
- * the effective repository directory (-C/--git-dir change it; --work-tree
- * alone does not) and the remainder (subcommand + args). Used so that
- * global flags cannot smuggle a guarded subcommand past the regexes.
- */
-function parseGitInvocation(command: string): GitInvocation | undefined {
-	const tokens = unwrapShellWords(command);
-	if (tokens[0] !== "git") return undefined;
-	let i = 1;
-	let repoDir = workspaceRoot;
-	let sawDirOption = false;
-	while (i < tokens.length) {
-		const tok = tokens[i]!;
-		if (GIT_DIR_OPTION_TAKES_VALUE.has(tok)) {
-			const value = tokens[i + 1];
-			if (value === undefined) return { repoDir, rest: "" };
-			if (tok === "-C" || tok === "--git-dir") {
-				repoDir = resolve(workspaceRoot, value);
-				sawDirOption = true;
-			}
-			i += 2;
-			continue;
-		}
-		if (GIT_DIR_OPTION_PREFIXED.test(tok)) {
-			if (tok.startsWith("--git-dir=")) {
-				repoDir = resolve(workspaceRoot, tok.slice("--git-dir=".length));
-				sawDirOption = true;
-			}
-			i += 1;
-			continue;
-		}
-		// Bare global flags that take no value.
-		if (GIT_GLOBAL_BOOLEAN_OPTIONS.has(tok)) {
-			i += 1;
-			continue;
-		}
-		break;
-	}
-	if (!sawDirOption) repoDir = workspaceRoot;
-	return { repoDir, rest: tokens.slice(i).join(" ") };
-}
-
-/**
- * Rewrite a command so every `git [global-opts] <sub>` becomes plain
- * `git <sub>`, letting the guard regexes match the subcommand regardless of
- * global flags. Non-git segments pass through unchanged.
- */
-function normalizeGitCommands(command: string): string {
-	return splitShellSegments(command)
-		.map((segment) => {
-			const parsed = parseGitInvocation(segment);
-			return parsed ? `git ${parsed.rest}` : segment;
-		})
-		.join(" ; ");
-}
-
-const GIT_WRITE_RE =
-	/\bgit\s+(commit|merge|rebase|cherry-pick|revert|stash\s+pop|apply|am|restore|reset|update-ref|filter-branch)\b|\bgit\s+branch\s+(?:[^|;&]*\s)?-[dDM]\b/;
-
-function currentGitBranch(root: string): string | undefined {
-	const result = spawnSync("git", ["branch", "--show-current"], {
-		cwd: root,
-		encoding: "utf8",
-		timeout: 10_000,
-	});
-	if (result.status === 0 && result.stdout.trim()) {
-		return result.stdout.trim();
-	}
-	// Fallback for unborn branches / odd runtimes: read .git/HEAD directly.
-	try {
-		const head = readFileSync(resolve(root, ".git", "HEAD"), "utf8").trim();
-		const match = head.match(/^ref:\s+refs\/heads\/(\S+)/);
-		if (match) return match[1];
-	} catch {
-		// Not a repo (or worktree without .git dir) - no gate.
-	}
-	if (result.status === 0) return ""; // detached HEAD - treat as unprotected
-	return undefined;
-}
-
-// ── Project-level configuration (.opencode/workflow-guard.json) ───────────────
-
-export interface ProjectConfig {
-	protectedBranches?: string[];
-	verifyCommand?: string;
-	requireReview?: boolean;
-	requireDocumentation?: boolean;
-}
-
-let cachedProjectConfig: ProjectConfig | undefined;
-
-export function loadProjectConfig(root: string): ProjectConfig {
-	const candidates = [
-		join(root, ".opencode", "workflow-guard.json"),
-		join(root, ".opencode", "workflow-guard.jsonc"),
-		join(root, "workflow-guard.json"),
-		join(root, "workflow-guard.jsonc"),
-	];
-	for (const candidate of candidates) {
-		try {
-			const raw = readFileSync(candidate, "utf8");
-			return JSON.parse(raw);
-		} catch {}
-	}
-	return {};
-}
-
-export function reloadProjectConfig(root: string): void {
-	cachedProjectConfig = loadProjectConfig(root);
-}
-
-export function isReviewRequired(root: string): boolean {
-	if (process.env.WORKFLOW_GUARD_REQUIRE_REVIEW === "1") return true;
-	const cfg = cachedProjectConfig ?? loadProjectConfig(root);
-	return cfg.requireReview === true;
-}
-
-/**
- * The full protected-branch set for this repository: the built-in
- * main/master set plus any branches configured in
- * `.opencode/workflow-guard.json` (`protectedBranches`). Shared by the
- * branch guard, the push guard and the native worktree tools so every
- * path enforces the same set.
- */
-export function getProtectedBranches(root = workspaceRoot): Set<string> {
-	const cfg = cachedProjectConfig ?? loadProjectConfig(root);
-	const customBranches = Array.isArray(cfg.protectedBranches)
-		? cfg.protectedBranches
-		: [];
-	return new Set([...PROTECTED_BRANCHES, ...customBranches]);
-}
-
-/** True when `branch` is protected for the repository at `root`. */
-export function isProtectedBranchName(branch: string, root = workspaceRoot): boolean {
-	if (!branch) return false;
-	return getProtectedBranches(root).has(branch);
-}
-
-/** Regex-escape a literal string for embedding in a RegExp. */
-function escapeRegExp(text: string): string {
-	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-/**
- * Returns the protected branch a `git push` command targets as its
- * destination, if any. Covers bare refspecs (`git push origin <branch>`)
- * and colon forms (`git push origin HEAD:<branch>`, `:<branch>` deletion,
- * `+<branch>` forced), for every protected branch - built-in and
- * configured - of the repository at `root`.
- */
-function pushedProtectedBranchIn(pushCommand: string, root: string): string | undefined {
-	for (const branch of getProtectedBranches(root)) {
-		const escaped = escapeRegExp(branch);
-		const re = new RegExp(
-			`(?:^|\\s)\\+?[\\w./-]*:${escaped}(?![\\w./-])` +
-				`|(?:\\s|\\/)${escaped}(?![\\w./-])`,
-		);
-		if (re.test(pushCommand)) return branch;
-	}
-	return undefined;
-}
-
-function onProtectedBranch(root: string): boolean {
-	return isProtectedBranchName(currentGitBranch(root) ?? "", root);
-}
-
-function branchGuardReason(): string {
-	return (
-		"Blocked: the workspace is on a protected branch. " +
-		"Create a feature branch first - e.g. " +
-		"`git switch -c feat/description` - and make all changes there, " +
-		"then open a PR. Direct changes on protected branches are not allowed."
-	);
-}
-
-// ── Merged / Closed PR branch check (GitHub & Azure DevOps) ──────────────────
-
-export function isBranchAlreadyMergedOrClosed(
-	root: string,
-	branch: string,
-): { merged: boolean; reason?: string } {
-	if (!branch || PROTECTED_BRANCHES.has(branch)) {
-		return { merged: false };
-	}
-
-	// 1. Check local / remote git ancestors: is branch already fully merged into main/master?
-	for (const base of ["origin/HEAD", "origin/main", "origin/master", "main", "master"]) {
-		const check = spawnSync("git", ["merge-base", "--is-ancestor", branch, base], {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 5_000,
-		});
-		if (check.status === 0) {
-			const unmerged = spawnSync("git", ["rev-list", `${base}..${branch}`, "--count"], {
-				cwd: root,
-				encoding: "utf8",
-				timeout: 5_000,
-			});
-			if (unmerged.status === 0 && unmerged.stdout.trim() === "0") {
-				return {
-					merged: true,
-					reason: `Branch '${branch}' is already merged into '${base}'. Create a fresh feature branch for new changes.`,
-				};
-			}
-		}
-	}
-
-	// 2. Check GitHub PR state if gh CLI is present
-	try {
-		const ghRes = spawnSync(
-			"gh",
-			["pr", "list", "--head", branch, "--state", "all", "--json", "number,state,title", "--limit", "1"],
-			{ cwd: root, encoding: "utf8", timeout: 8_000 },
-		);
-		if (ghRes.status === 0 && ghRes.stdout.trim()) {
-			const prs = JSON.parse(ghRes.stdout.trim());
-			if (Array.isArray(prs) && prs.length > 0) {
-				const pr = prs[0];
-				if (pr && (pr.state === "MERGED" || pr.state === "CLOSED")) {
-					return {
-						merged: true,
-						reason: `Branch '${branch}' is associated with an already ${pr.state.toLowerCase()} GitHub PR (#${pr.number}: ${pr.title ?? ""}). Create a fresh feature branch for new changes.`,
-					};
-				}
-			}
-		}
-	} catch {}
-
-	// 3. Check Azure DevOps PR state if az CLI is present
-	try {
-		const azRes = spawnSync(
-			"az",
-			["repos", "pr", "list", "--source-branch", branch, "--status", "all", "--query", "[0].{id:pullRequestId, status:status, title:title}", "-o", "json"],
-			{ cwd: root, encoding: "utf8", timeout: 8_000 },
-		);
-		if (azRes.status === 0 && azRes.stdout.trim()) {
-			const pr = JSON.parse(azRes.stdout.trim());
-			if (pr && typeof pr === "object" && (pr.status === "completed" || pr.status === "abandoned")) {
-				return {
-					merged: true,
-					reason: `Branch '${branch}' is associated with an already ${pr.status} Azure DevOps PR (#${pr.id}: ${pr.title ?? ""}). Create a fresh feature branch for new changes.`,
-				};
-			}
-		}
-	} catch {}
-
-	return { merged: false };
-}
-
-// ── Merge conflict pre-flight check ──────────────────────────────────────────
-
-export function checkMergeConflicts(root: string): {
-	hasConflicts: boolean;
-	baseBranch?: string;
-	reason?: string;
-} {
-	const candidates = ["origin/HEAD", "origin/main", "origin/master", "main", "master"];
-	for (const base of candidates) {
-		const mergeBaseRes = spawnSync("git", ["merge-base", "HEAD", base], {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 5_000,
-		});
-		if (mergeBaseRes.status !== 0 || !mergeBaseRes.stdout.trim()) continue;
-		const mergeBase = mergeBaseRes.stdout.trim();
-
-		const treeRes = spawnSync("git", ["merge-tree", mergeBase, "HEAD", base], {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 10_000,
-		});
-		if (treeRes.status === 0 && treeRes.stdout.includes("<<<<<<<")) {
-			return {
-				hasConflicts: true,
-				baseBranch: base,
-				reason: `Branch has merge conflicts with base branch '${base}'. Rebase or merge '${base}' to resolve all conflicts before opening a PR or handing off.`,
-			};
-		}
-	}
-	return { hasConflicts: false };
-}
-
-// ── Base branch freshness pre-flight check ───────────────────────────────────
-
-const GIT_BRANCH_CREATE_RE =
-	/\bgit\s+(?:checkout\s+-b|switch\s+(?:-c|--create))\b/;
-
-export function checkBranchBaseIsUpToDate(root: string): {
-	isBehind: boolean;
-	count?: number;
-	baseRef?: string;
-	reason?: string;
-} {
-	for (const base of ["origin/HEAD", "origin/main", "origin/master"]) {
-		const res = spawnSync("git", ["rev-list", `HEAD..${base}`, "--count"], {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 5_000,
-		});
-		if (res.status === 0 && res.stdout.trim()) {
-			const count = parseInt(res.stdout.trim(), 10);
-			if (!isNaN(count) && count > 0) {
-				return {
-					isBehind: true,
-					count,
-					baseRef: base,
-					reason: `Local base branch is ${count} commit(s) behind remote (${base}). Run 'git pull' or 'git fetch' on main before creating a fresh feature branch to prevent upstream conflicts.`,
-				};
-			}
-		}
-	}
-	return { isBehind: false };
-}
-
-// ── Live-system guard ────────────────────────────────────────────────────────
-// The ONLY override is the WORKFLOW_GUARD_ALLOW_LIVE=1 environment variable,
-// which the user must set before launching the agent. There is deliberately
-// no in-command marker: an override the agent can append to its own command
-// (or is told about in an error message) is an override the agent WILL use.
-
-interface LivePattern {
-	re: RegExp;
-	what: string;
-}
-
-const LIVE_MUTATION_PATTERNS: LivePattern[] = [
-	// Only DESTRUCTIVE operations are blocked. Create/update/apply/set-style
-	// commands are allowed - they're normal work and reviewable in diffs.
-	// Filesystem destruction: block rm -rf on system paths, allow workspace cleanup
-	{ re: /\brm\s+(?:-[a-zA-Z]*[rRfF][a-zA-Z]*\s+)*-[a-zA-Z]*[rRfF][a-zA-Z]*\s+(?:\/|~|\*)/, what: "recursive/forced deletion of system/home paths" },
-	{ re: /\b(?:sudo\s+)?rm\s+-(?:[a-zA-Z]*[rRfF][a-zA-Z]*\s+){1,2}(?:\/|~)/, what: "forced deletion of system/home paths" },
-	{ re: /\bgit\s+clean\s+(?:-[a-zA-Z]*[fdx][a-zA-Z]*)(?:\s|$)/, what: "git clean (untracked file deletion)" },
-	{ re: /\bgit\s+push\b[^|;&]*\s\+(?:[\w./-]*:)?/, what: "force push via + refspec" },
-	// Infrastructure / orchestration
-	{ re: /\bkubectl\s+(delete|drain|cordon)\b/, what: "destructive kubectl command" },
-	{ re: /\bkubectl\s+rollout\s+(undo|restart)\b/, what: "destructive kubectl rollout" },
-	{ re: /\bhelm\s+(uninstall|rollback|delete)\b/, what: "helm release removal/rollback" },
-	{ re: /\b(?:terraform|tofu)\s+destroy\b/, what: "terraform/tofu destroy" },
-	{ re: /\bpulumi\s+destroy\b/, what: "pulumi destroy" },
-	// Containers
-	{ re: /\bdocker\s+(?:container\s+)?(?:rm|prune)\b/, what: "docker container/image removal" },
-	{ re: /\bdocker\s+(?:system|image|volume|network)\s+prune\b/, what: "docker prune" },
-	{ re: /\bdocker\s+volume\s+rm\b/, what: "docker volume removal" },
-	// Cloud CLI deletions
-	{ re: /\baz\s+\S+\s+(?:delete|purge)\b/, what: "Azure resource deletion" },
-	{ re: /\baz\s+(?:devops|repos|pipelines|boards|artifacts)\s+[\w-]*\s*(?:delete|abandon)\b/, what: "Azure DevOps deletion" },
-	{ re: /\baws\s+\S+\s+(?:delete|terminate)-?\w*\b/, what: "AWS resource deletion" },
-	{ re: /\bgcloud\s+\S+\s+(?:delete|abandon)\b/, what: "GCP resource deletion" },
-	// Hosted repo / PR destruction via CLI
-	{ re: /\bgh\s+(?:repo|issue|pr|release|secret|variable)\s+(?:delete|close)\b/, what: "gh destructive command" },
-	// Database destruction via CLI clients (insert/update/create are allowed)
-	{ re: /\b(?:psql|mysql|mariadb|mongosh|mongo|redis-cli|sqlite3)\b[^|;&]*\b(?:drop|delete|truncate|flushall|flushdb)\b/i, what: "destructive database command" },
-	{ re: /\b(?:npx|pnpm\s+exec|yarn)\s+prisma\s+migrate\s+reset\b/, what: "prisma migrate reset (database wipe)" },
-	{ re: /\bprisma\s+migrate\s+reset\b/, what: "prisma migrate reset (database wipe)" },
-	// Destructive remote HTTP calls (DELETE only; POST/PUT/PATCH are normal API work)
-	{ re: /\bcurl\b(?=[^|;&]*(?:(?<!\S)(?:-X|--request)\s*=?\s*DELETE))(?=[^|;&]*https?:\/\/(?!localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]))/, what: "remote HTTP DELETE" },
-	{ re: /\b(?:curl|wget)\b[^;&]*\|\s*(?:bash|sh|zsh)\b/, what: "remote download piped directly to a shell" },
-	// Destructive git operations
-	{ re: /\bgit\s+push\b[^|;&]*(?:--force\b|--force-with-lease\b|\s-f\b)/, what: "force push" },
-];
-
-function liveMutationIn(command: string): string | undefined {
-	for (const { re, what } of LIVE_MUTATION_PATTERNS) {
-		if (re.test(command)) {
-			return what;
-		}
-	}
-	return undefined;
-}
-
-// ── Secret content scan ──────────────────────────────────────────────────────
-// Common credential shapes that must never end up committed to a repo. This
-// list is intentionally conservative - it aims to catch obvious accidents
-// (env-file contents, keys copied into source) rather than every secret on
-// earth. False positives return an actionable error.
-
-interface SecretPattern {
-	re: RegExp;
-	what: string;
-}
-
-const SECRET_PATTERNS: SecretPattern[] = [
-	{ re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/, what: "private key material" },
-	{ re: /\bAKIA[0-9A-Z]{16}\b/, what: "AWS access key ID" },
-	{ re: /\bASIA[0-9A-Z]{16}\b/, what: "AWS temporary session credential" },
-	{ re: /\bghp_[A-Za-z0-9]{36}\b/, what: "GitHub personal access token" },
-	{ re: /\bgithub_pat_[A-Za-z0-9_]{82}\b/, what: "GitHub fine-grained PAT" },
-	{ re: /\bgho_[A-Za-z0-9]{36}\b/, what: "GitHub OAuth token" },
-	{ re: /\bghu_[A-Za-z0-9]{36}\b/, what: "GitHub user-to-server token" },
-	{ re: /\bghs_[A-Za-z0-9]{36}\b/, what: "GitHub server-to-server token" },
-	{ re: /\bghr_[A-Za-z0-9]{36}\b/, what: "GitHub refresh token" },
-	{ re: /\bsk-[A-Za-z0-9]{20,}\b/, what: "OpenAI-style API key" },
-	{ re: /\bog-[A-Za-z0-9]{20,}\b/, what: "OpenCode/legacy API key" },
-	{ re: /\bAIza[0-9A-Za-z_-]{35}\b/, what: "Google API key" },
-	{ re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/, what: "Slack token (xox family)" },
-	// Explicit env-style assignments are a common accident in .env files.
-	{ re: /(?:^|\s)(?:AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN)\s*=\s*\S+/, what: "AWS credential assignment" },
-	{ re: /(?:^|\s)(?:OPENAI_API_KEY|ANTHROPIC_API_KEY|OPENAI_KEY)\s*=\s*\S+/, what: "LLM API key assignment" },
-];
-
-function secretIn(content: string): string | undefined {
-	for (const { re, what } of SECRET_PATTERNS) {
-		if (re.test(content)) return what;
-	}
-	return undefined;
-}
-
-/**
- * Extract executable-looking content from file-edit tool input (write/edit
- * payloads, apply_patch texts). Scanned for destructive patterns so that
- * writing a script and executing it cannot launder a blocked command.
- */
-function extractEditContent(input: unknown): string[] {
-	const record = asRecord(input);
-	if (!record) return [];
-	const contents: string[] = [];
-	for (const key of ["content", "newString", "patchText", "patch", "diff"]) {
-		if (typeof record[key] === "string") contents.push(record[key] as string);
-	}
-	// apply_patch in some runtimes is an array of file ops
-	if (Array.isArray(record.changes)) {
-		for (const change of record.changes) {
-			const r = asRecord(change);
-			if (r && typeof r.content === "string") contents.push(r.content);
-		}
-	}
-	return contents;
-}
-
-// ── MCP mutation tool guard ──────────────────────────────────────────────────
-// MCP tools bypass the shell entirely, so they need their own name-based
-// matching. OpenCode exposes MCP tools with names like `mcp__<server>__<tool>`;
-// some runtimes use plain `<server>_<tool>` names instead, so both forms are
-// matched. Read-only tool names (get/list/search/show/query/describe/…) are
-// always allowed; mutating names are blocked unless explicitly allowed.
-
-const MCP_MUTATION_VERB_RE =
-	/(?:^|_)(?:create|update|delete|remove|merge|push|close|edit|set|fork|trigger|cancel|rerun|add|assign|approve|complete|abandon)(?:_|$)/;
-const MCP_READ_ONLY_RE =
-	/(?:^|_)(?:get|list|search|show|query|describe|find|read|status|diff|log)(?:_|$)/;
-
-// Guarded servers. Matched as whole tokens after splitting on
-// non-alphanumerics, so `azure-devops` → {azure, devops}, `gh` → {gh}, etc.
-const GUARDED_MCP_SERVERS = new Set([
-	"github",
-	"gh",
-	"azure",
-	"azmcp",
-	"ado",
-	"devops",
-	"azuredevops",
-]);
-
-function mcpMutationTool(toolName: string): string | undefined {
-	if (!MCP_MUTATION_VERB_RE.test(toolName) || MCP_READ_ONLY_RE.test(toolName)) {
-		return undefined;
-	}
-	const tokens = toolName.toLowerCase().split(/[^a-z0-9]+/);
-	if (tokens.some((t) => GUARDED_MCP_SERVERS.has(t))) {
-		return "GitHub/Azure DevOps";
-	}
-	return undefined;
-}
-
-// ── OpenCode settings tamper guard ───────────────────────────────────────────
-// The model must not be able to weaken its own permission gates by editing
-// opencode.json / permission config, tampering with the guard's own plugin
-// files, or managing auth from the agent. This is enforced in BOTH the
-// shell guard (below) and the file-edit tools (via isProtectedPath), because
-// an agent that can `edit` a config file directly doesn't need the shell.
-
-/**
- * True when a filesystem path targets OpenCode's own configuration, plugin,
- * or auth state - anything the agent could modify to weaken the guard.
- * Checked against the path resolved from the workspace root.
- */
-export function isProtectedPath(targetPath: string): boolean {
-	if (!targetPath) return false;
-	const resolved = resolve(workspaceRoot, targetPath);
-	const matches = (path: string): boolean => {
-		const base = basename(path);
-		const lower = path.toLowerCase();
-		return (
-		// opencode.json / opencode.jsonc anywhere (project config)
-		/^opencode\.jsonc?$/i.test(base) ||
-		// workflow-guard.json / workflow-guard.jsonc anywhere
-		/^workflow-guard\.jsonc?$/i.test(base) ||
-		// the .opencode directory itself and anything under it (project
-		// plugins, agents) - including the exact directory, not just paths
-		// nested inside it
-		lower === ".opencode" ||
-		lower.endsWith("/.opencode") ||
-		lower.includes(`${"/"}.opencode/`) ||
-		// anything under ~/.config/opencode (global config, plugins, ui)
-		lower.includes("/.config/opencode/") ||
-		lower.includes("/.config/opencode.json")
-		);
-	};
-	if (matches(resolved)) return true;
-	try {
-		return matches(realpathSync(resolved));
-	} catch {
-		let ancestor = resolve(resolved, "..");
-		while (ancestor !== resolve(ancestor, "..")) {
-			try {
-				const realAncestor = realpathSync(ancestor);
-				return matches(resolve(realAncestor, relative(ancestor, resolved)));
-			} catch {
-				ancestor = resolve(ancestor, "..");
-			}
-		}
-		return false;
-	}
-}
-
-// ── Sensitive file READ guard (.env*, keys, credentials, kubeconfig) ─────────
-// Reading live secrets into model context leaks credentials. Read-only fixtures
-// (.env.example, .env.sample, .env.template) are safe and permitted.
-
-const SAFE_ENV_FIXTURE_RE =
-	/\.env\.(example|sample|template|dist|schema)(\.[\w-]+)*$/i;
-
-export function isSecretPath(targetPath: string): boolean {
-	if (!targetPath) return false;
-	const resolved = resolve(workspaceRoot, targetPath);
-	const matches = (path: string): boolean => {
-	const base = basename(path).toLowerCase();
-	const full = path.toLowerCase();
-
-	// Safe fixtures
-	if (SAFE_ENV_FIXTURE_RE.test(base)) {
-		return false;
-	}
-
-	// .env files (e.g. .env, .env.local, .env.prod, .env.secret)
-	if (/^\.env(?:\.|$)/i.test(base)) {
-		return true;
-	}
-
-	// SSH & TLS key material
-	if (
-		/^(id_rsa|id_dsa|id_ecdsa|id_ed25519)(?:\.|$)/i.test(base) ||
-		/\.(pem|key|pkcs12|pfx|p12)$/i.test(base)
-	) {
-		return true;
-	}
-
-	// Cloud / cluster / service account credentials
-	if (
-		/kubeconfig/i.test(base) ||
-		full.includes("/.kube/config") ||
-		/^(service[-_]?account|client[-_]?secret).*\.json$/i.test(base) ||
-		/credentials\.json$/i.test(base) ||
-		full.includes("/.aws/credentials") ||
-		full.includes("/.docker/config.json") ||
-		base === ".netrc" ||
-		base === ".git-credentials"
-	) {
-		return true;
-	}
-
-	return false;
-	};
-	if (matches(resolved)) return true;
-	try {
-		return matches(realpathSync(resolved));
-	} catch {
-		return false;
-	}
-}
-
-/**
- * Returns true specifically for environment variable files (.env, .env.local, etc.)
- * that can safely present their schema (masked keys) to agents without exposing secret values.
- */
-export function isEnvFilePath(targetPath: string): boolean {
-	if (!targetPath) return false;
-	const base = basename(targetPath).toLowerCase();
-	if (SAFE_ENV_FIXTURE_RE.test(base)) return false;
-	return /^\.env(?:\.|$)/i.test(base);
-}
-
-/**
- * Parses a raw .env file and returns a sanitized schema mask where variable names
- * and comment structures are preserved, but sensitive values are redacted to '********'.
- */
-export function generateMaskedEnvSchema(content: string): string {
-	const lines = content.split("\n");
-	return lines
-		.map((line) => {
-			const trimmed = line.trim();
-			if (!trimmed || trimmed.startsWith("#")) return line;
-			const eqIdx = line.indexOf("=");
-			if (eqIdx === -1) return line;
-			const key = line.slice(0, eqIdx);
-			return `${key}=********`;
-		})
-		.join("\n");
-}
-
-const SECRET_READ_COMMAND_RE =
-	/(?:^|\s)(?:cat|head|tail|less|more|grep|awk|sed|od|hexdump|strings|base64|xxd|nl|sort|uniq|view|nano|vim?)\s+[^|;&]*?(?:["']?)([\w\/.~-]*\.(?:pem|key|pfx|p12)|[\w\/.~-]*\.env(?:\.[\w-]+)*|[\w\/.~-]*id_(?:rsa|dsa|ecdsa|ed25519)[\w.-]*|[\w\/.~-]*kubeconfig[\w.-]*|[\w\/.~-]*(?:service[-_]?account|credentials|client[-_]?secret)[\w.-]*\.json)(?:["']?)/i;
-const SIMPLE_FILE_READ_COMMAND_RE =
-	/(?:^|\s)(?:cat|head|tail|less|more|od|hexdump|strings|base64|xxd|nl|view|nano|vim?)\s+(?:-\S+\s+)*["']?([^\s|;&"']+)/i;
-
-function secretFileReadIn(segment: string): string | undefined {
-	const match = segment.match(SECRET_READ_COMMAND_RE);
-	if (match?.[1] && isSecretPath(match[1])) {
-		return match[1];
-	}
-	const simpleMatch = segment.match(SIMPLE_FILE_READ_COMMAND_RE);
-	if (simpleMatch?.[1] && isSecretPath(simpleMatch[1])) return simpleMatch[1];
-	return undefined;
-}
-
-// ── Interpreter inline evasion scanner ───────────────────────────────────────
-// Extracts inline script payloads (python -c, node -e, perl -e, ruby -e,
-// powershell -enc, base64 | sh) so the live-mutation and settings-tamper
-// scanners can inspect the actual script content.
-
-export function extractInterpreterPayload(segment: string): string[] {
-	const payloads: string[] = [];
-	const inlineMatch = segment.match(
-		/\b(?:python3?|node|perl|ruby|osascript)\s+(?:-[a-zA-Z]*[ce]\s+)(?:"([^"]*)"|'([^']*)')/i,
-	);
-	if (inlineMatch?.[1] || inlineMatch?.[2]) {
-		payloads.push(inlineMatch[1] ?? inlineMatch[2] ?? "");
-	}
-	const psMatch = segment.match(
-		/\b(?:powershell|pwsh)\s+(?:-[a-zA-Z]*enc[a-zA-Z]*\s+)([A-Za-z0-9+/=]+)/i,
-	);
-	if (psMatch?.[1]) {
-		try {
-			const buf = Buffer.from(psMatch[1], "base64");
-			payloads.push(buf.toString("utf8"), buf.toString("utf16le"));
-		} catch {}
-	}
-	const b64PipeMatch = segment.match(
-		/echo\s+["']?([A-Za-z0-9+/=]{4,})["']?\s*\|\s*base64\s+(?:-[a-zA-Z]*d[a-zA-Z]*|--decode)\s*\|\s*(?:bash|sh|zsh)/i,
-	);
-	if (b64PipeMatch?.[1]) {
-		try {
-			const buf = Buffer.from(b64PipeMatch[1], "base64");
-			payloads.push(buf.toString("utf8"), buf.toString("utf16le"));
-		} catch {}
-	}
-	return payloads;
-}
-
-/**
- * Strip shell quote-concatenation and escape sequences that exist only to
- * break up a literal string: open''code.json -> opencode.json,
- * open""code -> opencode, open\c\ode -> opencode. Applied to each segment
- * before pattern matching so evasion requires more than quoting.
- */
-function normalizeShellEvasion(text: string): string {
-	return text
-		.replace(/'([^']*)'/g, "$1") // open''code -> opencode (quoted content kept)
-		.replace(/"([^"]*)"/g, "$1")
-		.replace(/\\(.)/g, "$1"); // open\c\ode -> opencode
-}
-
-/**
- * Collapse shell glob wildcards on the final path component so that
- * `opencode.jso?` or `opencode.*` still match the protected name.
- */
-function normalizeGlobPathEvasion(text: string): string {
-	return text
-		.replace(/opencode\.jso[?]/gi, "opencode.json")
-		.replace(/opencode\.[?*]/gi, "opencode.json");
-}
-
-// Tamper patterns are evaluated per command segment (split on newlines, |, ;,
-// &) so that tokens appearing on unrelated lines of a multi-line command can't
-// combine into a false match. Patterns that target config PATHS require a
-// write verb or redirect, so merely READING a config file (cat, less, grep)
-// is allowed - only modification attempts are blocked.
-const SETTINGS_TAMPER_PATTERNS: RegExp[] = [
-	// Shell writes to opencode config paths - write verb/redirect required.
-	/(?:^|\s)(?:sed\s+-i|tee|mv|cp|rm|chmod|chown|ln|install|truncate|dd)\s+[^|;&]*?(?:[\w\/.~-]*opencode\.jsonc?|[\w\/.~-]*\.config\/opencode|[\w\/.~-]*\.opencode\/)/i,
-	/>\s*["']?[\w\/.~-]*(?:opencode\.jsonc?|\.config\/opencode|\.opencode\/)/i,
-	// Editing the guard plugin itself or its TUI companion (any file,
-	// not just config) - self-protection.
-	/(?:^|\s)(?:sed\s+-i|tee|mv|cp|rm|chmod|chown|truncate|dd)\s+[^|;&]*?[\w\/.~-]*\.config\/opencode\/(?:plugins|ui)\//i,
-	/>\s*["']?[\w\/.~-]*\.config\/opencode\/(?:plugins|ui)\//i,
-	// CLI config/auth commands - matched as command verbs, not bare words.
-	/\bopencode\s+(?:auth|config|permission)\b/i,
-	// Blanket auto-approval flags on the CLI.
-	/\bopencode\s+(?:run\s+)?--auto\b/i,
-];
-
-const PROTECTED_PATH_REASON =
-	"Blocked: modifying OpenCode config / permissions / auth / the guard " +
-	"plugin itself is not allowed from the agent. The user must change " +
-	"these manually in opencode.json or the UI.";
-
-function isSettingsTamper(command: string): boolean {
-	// Evaluate each segment independently so regexes cannot span lines or
-	// shell separators. Normalize evasion before matching.
-	const segments = command.split(/[\n|;&]+/).map((s) =>
-		normalizeGlobPathEvasion(normalizeShellEvasion(s)),
-	);
-	return segments.some((segment) =>
-		SETTINGS_TAMPER_PATTERNS.some((re) => re.test(segment)),
-	);
-}
-
-// ── PR changelog check ───────────────────────────────────────────────────────
-// Accepts either a CHANGELOG file modification or a .changeset/*.md file.
-
-const CHANGELOG_OR_CHANGESET_RE = /(?:changelog|\.changeset\/[^/]+\.md$)/i;
-
-function branchHasChangelogChange(root: string): boolean {
-	try {
-		const baseCandidates = ["origin/HEAD", "origin/main", "origin/master"];
-		for (const base of baseCandidates) {
-			const mergeBase = spawnSync(
-				"git",
-				["merge-base", "HEAD", base],
-				{ cwd: root, encoding: "utf8", timeout: 10_000 },
-			);
-			if (mergeBase.status !== 0 || !mergeBase.stdout.trim()) continue;
-			const diff = spawnSync(
-				"git",
-				["diff", "--name-only", `${mergeBase.stdout.trim()}...HEAD`],
-				{ cwd: root, encoding: "utf8", timeout: 10_000 },
-			);
-			if (diff.status !== 0) continue;
-			if (diff.stdout.split("\n").some((f) => CHANGELOG_OR_CHANGESET_RE.test(f))) {
-				return true;
-			}
-		}
-		// Last resort: diff against HEAD~1 (single-commit branches).
-		const last = spawnSync("git", ["diff", "--name-only", "HEAD~1"], {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 10_000,
-		});
-		return (
-			last.status === 0 &&
-			last.stdout.split("\n").some((f) => CHANGELOG_OR_CHANGESET_RE.test(f))
-		);
-	} catch {
-		return false;
-	}
-}
-
-// ── Documentation review & synchronization check (Policy 21) ─────────────────
-
-/**
- * True for user-facing documentation files: README.md (root or package
- * level) and anything under a docs/ directory. Deliberately excludes
- * arbitrary markdown (e.g. .changeset/*.md, CHANGELOG.md) so the
- * documentation gate cannot be satisfied by a changeset fragment.
- */
-function isDocumentationFile(filePath: string): boolean {
-	const lower = filePath.toLowerCase();
-	if (lower === "readme.md" || lower.endsWith("/readme.md")) return true;
-	if (lower === "docs" || lower.startsWith("docs/") || lower.includes("/docs/")) return true;
-	return false;
-}
-
-export function branchHasDocumentationChange(root: string): boolean {
-	try {
-		const baseCandidates = ["origin/HEAD", "origin/main", "origin/master", "main", "master"];
-		for (const base of baseCandidates) {
-			const mergeBase = spawnSync("git", ["merge-base", "HEAD", base], {
-				cwd: root,
-				encoding: "utf8",
-				timeout: 5_000,
-			});
-			if (mergeBase.status !== 0 || !mergeBase.stdout.trim()) continue;
-			const diff = spawnSync(
-				"git",
-				["diff", "--name-only", `${mergeBase.stdout.trim()}...HEAD`],
-				{ cwd: root, encoding: "utf8", timeout: 8_000 },
-			);
-			if (diff.status !== 0) continue;
-			const files = diff.stdout.split("\n").filter(Boolean);
-			if (files.some((f) => isDocumentationFile(f))) {
-				return true;
-			}
-		}
-		const last = spawnSync("git", ["diff", "--name-only", "HEAD~1"], {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 5_000,
-		});
-		if (last.status === 0) {
-			const files = last.stdout.split("\n").filter(Boolean);
-			return files.some((f) => isDocumentationFile(f));
-		}
-		return false;
-	} catch {
-		return false;
-	}
-}
-
-// ── Package supply-chain & dependency hygiene guard (Policy 23) ──────────────
-// AI agents frequently run dangerous package manager flags (e.g. npm audit fix --force,
-// npm install --ignore-scripts, pip install --no-verify, global unversioned installs)
-// that introduce breaking changes, downgrade packages insecurely, or execute arbitrary code.
-
-const PACKAGE_HYGIENE_PATTERNS: Array<{ regex: RegExp; name: string; advice: string }> = [
-	{
-		regex: /\bnpm\s+audit\s+fix\s+--force\b/i,
-		name: "destructive npm audit fix --force",
-		advice: "Run 'npm audit' or update dependencies individually in package.json. '--force' introduces breaking major version downgrades.",
-	},
-	{
-		regex: /\b(?:npm|pnpm|yarn|bun)\s+(?:install|i|add)\s+-[a-zA-Z]*g\b/i,
-		name: "global package installation",
-		advice: "Install packages locally as devDependencies (--save-dev) or execute with npx/bunx rather than polluting global machine state.",
-	},
-	{
-		regex: /\bpip\s+install\s+(?:--upgrade\s+)?--force-reinstall\b/i,
-		name: "destructive pip force reinstall",
-		advice: "Specify exact versions in requirements.txt or pyproject.toml instead of force reinstalling.",
-	},
-	{
-		regex: /\b(?:npm|yarn|pnpm|bun)\s+publish\b/i,
-		name: "direct package publish from agent subshell",
-		advice: "Package publishing must be managed by automated release workflows or explicit user release commands.",
-	},
-];
-
-export function checkPackageHygiene(command: string): { isViolating: boolean; name?: string; advice?: string } {
-	for (const { regex, name, advice } of PACKAGE_HYGIENE_PATTERNS) {
-		if (regex.test(command)) {
-			return { isViolating: true, name, advice };
-		}
-	}
-	return { isViolating: false };
-}
-// AI agents running in non-interactive terminal subshells will hang indefinitely
-// if an interactive prompt (e.g. vim, nano, less, top, sudo, npm init without -y,
-// apt-get without -y, git rebase -i) waits for TTY input.
-
-const INTERACTIVE_COMMAND_PATTERNS: Array<{ regex: RegExp; name: string; advice: string }> = [
-	{
-		regex: /\b(?:nano|vim?|emacs|pico|joe|micro)\b/i,
-		name: "interactive text editor",
-		advice: "Use the edit, write, or apply_patch tools instead of interactive terminal editors.",
-	},
-	{
-		regex: /\b(?:less|more|most)\b/i,
-		name: "terminal pager",
-		advice: "Use cat, head, or grep with non-interactive pipes instead of interactive pagers.",
-	},
-	{
-		regex: /\b(?:top|htop|btop|atop|glances)\b/i,
-		name: "interactive process monitor",
-		advice: "Use ps aux, uptime, or batch flags (e.g. top -b -n 1) instead of interactive monitors.",
-	},
-	{
-		regex: /\bsudo\b/i,
-		name: "sudo with password prompt",
-		advice: "Avoid sudo in agent sessions; run commands directly or request user execution.",
-	},
-	{
-		regex: /\bgit\s+rebase\s+-[a-zA-Z]*i/i,
-		name: "git interactive rebase",
-		advice: "Use non-interactive git commands or explicit cherry-pick/merge sequences.",
-	},
-	{
-		regex: /\bgit\s+add\s+-[a-zA-Z]*p/i,
-		name: "git interactive patch",
-		advice: "Use git add <file> or git apply rather than interactive patch selection.",
-	},
-	{
-		regex: /\bnpm\s+init\b(?!\s+(?:-y|--yes|--force))\b/i,
-		name: "npm init without non-interactive flag",
-		advice: "Add -y or --yes flag: npm init -y",
-	},
-	{
-		regex: /\b(?:apt|apt-get)\s+(?:install|remove|purge|upgrade|dist-upgrade)\b(?!\s+(?:-y|--yes|--assume-yes))\b/i,
-		name: "apt command without non-interactive flag",
-		advice: "Add -y flag to avoid interactive confirmation prompts (e.g. apt-get install -y <pkg>).",
-	},
-	{
-		regex: /\b(?:yum|dnf)\s+(?:install|remove|upgrade)\b(?!\s+-y)\b/i,
-		name: "yum/dnf command without non-interactive flag",
-		advice: "Add -y flag to avoid interactive confirmation prompts (e.g. dnf install -y <pkg>).",
-	},
-];
-
-export function checkInteractiveTtyCommand(command: string): { isInteractive: boolean; name?: string; advice?: string } {
-	for (const { regex, name, advice } of INTERACTIVE_COMMAND_PATTERNS) {
-		if (regex.test(command)) {
-			return { isInteractive: true, name, advice };
-		}
-	}
-	return { isInteractive: false };
-}
-
-/**
- * Dispatches a native OS desktop notification (macOS osascript or Linux notify-send)
- * on important guard events (policy blocks, verification completion).
- * Non-blocking, fails gracefully.
- */
-export function sendDesktopNotification(title: string, message: string): void {
-	if (process.env.WORKFLOW_GUARD_NOTIFY === "0") return;
-	const safeTitle = title.replace(/"/g, '\\"');
-	const safeMsg = message.slice(0, 150).replace(/"/g, '\\"');
-
-	try {
-		if (process.platform === "darwin") {
-			const child = spawn(
-				"osascript",
-				["-e", `display notification "${safeMsg}" with title "${safeTitle}"`],
-				{ stdio: "ignore", detached: true },
-			);
-			child.on("error", () => {});
-			child.unref();
-		} else if (process.platform === "linux") {
-			const child = spawn(
-				"notify-send",
-				[safeTitle, safeMsg],
-				{ stdio: "ignore", detached: true },
-			);
-			child.on("error", () => {});
-			child.unref();
-		}
-	} catch {}
-}
-
-export function getWorktreeStorageDir(root = workspaceRoot): string {
-	const base = process.env.WORKFLOW_GUARD_WORKTREE_DIR ??
-		join(process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "opencode", "worktrees");
-	const repoName = basename(root);
-	return join(base, repoName);
-}
-
-/**
- * Returns a copy of process.env with git context variables removed so spawned
- * git commands resolve the repository from their cwd alone. Without this, a
- * caller nested inside a git hook (which exports GIT_INDEX_FILE and friends)
- * would make `git worktree add` fail: the internal checkout of the new
- * worktree resolves the inherited relative GIT_INDEX_FILE against the new
- * worktree root, where `.git` is a file, not a directory.
- */
-export function getCleanGitEnv(): Record<string, string> {
-	const env: Record<string, string> = { ...(process.env as Record<string, string>) };
-	for (const key of [
-		"GIT_INDEX_FILE",
-		"GIT_DIR",
-		"GIT_WORK_TREE",
-		"GIT_COMMON_DIR",
-		"GIT_OBJECT_DIRECTORY",
-		"GIT_ALTERNATE_OBJECT_DIRECTORIES",
-		"GIT_PREFIX",
-	]) {
-		delete env[key];
-	}
-	return env;
-}
-
-/**
- * Validates a branch name using git itself (`git check-ref-format
- * --branch`), with fast local pre-filters for names that must never be
- * passed as arguments at all (leading dash would be parsed as an option).
- */
-export function isValidBranchName(name: string): boolean {
-	if (!name || name.length > 255) return false;
-	if (name.startsWith("-") || name.startsWith(".") || name.endsWith(".") || name.endsWith(".lock")) return false;
-	if (name.includes("..") || name.includes("@{") || name.includes("//")) return false;
-	const res = spawnSync("git", ["check-ref-format", "--branch", name], {
-		encoding: "utf8",
-		timeout: 5_000,
-		env: getCleanGitEnv(),
-	});
-	return res.status === 0;
-}
-
-/** True when `refs/heads/<branch>` exists in the repository at `root`. */
-function localBranchExists(branch: string, root: string): boolean {
-	const res = spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], {
-		cwd: root,
-		encoding: "utf8",
-		timeout: 5_000,
-		env: getCleanGitEnv(),
-	});
-	return res.status === 0;
-}
-
-export function createGitWorktree(
-	branch: string,
-	baseBranch = "HEAD",
-	root = workspaceRoot,
-): { success: boolean; worktreePath?: string; error?: string } {
-	if (!branch || !isValidBranchName(branch)) {
-		return { success: false, error: `Invalid branch name '${branch}' for worktree creation.` };
-	}
-	if (isProtectedBranchName(branch, root)) {
-		return { success: false, error: `Cannot create worktree on protected branch '${branch}'.` };
-	}
-
-	const storageBase = getWorktreeStorageDir(root);
-	const targetPath = join(storageBase, branch.replace(/[/\\:]/g, "-"));
-
-	try {
-		mkdirSync(storageBase, { recursive: true });
-
-		const exists = localBranchExists(branch, root);
-
-		const gitArgs = exists
-			? ["worktree", "add", targetPath, branch]
-			: ["worktree", "add", "-b", branch, targetPath, baseBranch];
-
-		const addRes = spawnSync("git", gitArgs, {
-			cwd: root,
-			env: getCleanGitEnv(),
-			encoding: "utf8",
-			timeout: 15_000,
-		});
-
-		if (addRes.status !== 0) {
-			return { success: false, error: addRes.stderr.trim() || `git worktree add failed` };
-		}
-
-		const nodeModulesSrc = join(root, "node_modules");
-		const nodeModulesDest = join(targetPath, "node_modules");
-		if (existsSync(nodeModulesSrc) && !existsSync(nodeModulesDest)) {
-			try {
-				symlinkSync(nodeModulesSrc, nodeModulesDest, "dir");
-			} catch {}
-		}
-
-		return { success: true, worktreePath: targetPath };
-	} catch (e: any) {
-		return { success: false, error: e?.message ?? String(e) };
-	}
-}
-
-/**
- * Lists the worktree paths registered for the repository at `root`
- * (primary worktree first), or undefined when git cannot be consulted.
- */
-function registeredWorktreePaths(root: string): string[] | undefined {
-	const res = spawnSync("git", ["worktree", "list", "--porcelain"], {
-		cwd: root,
-		encoding: "utf8",
-		timeout: 10_000,
-		env: getCleanGitEnv(),
-	});
-	if (res.status !== 0) return undefined;
-	return res.stdout
-		.split("\n")
-		.filter((line) => line.startsWith("worktree "))
-		.map((line) => line.slice("worktree ".length))
-		.filter((path) => path.length > 0);
-}
-
-export function cleanupGitWorktree(
-	worktreePath: string,
-	root = workspaceRoot,
-): { success: boolean; error?: string } {
-	try {
-		if (!existsSync(worktreePath)) {
-			return { success: false, error: `Worktree path '${worktreePath}' does not exist.` };
-		}
-
-		// Ownership validation: the path must live under the configured
-		// worktree storage directory AND be a registered worktree of this
-		// repository. This refuses arbitrary directories, other repos'
-		// worktrees, and the primary working tree - cleanup must never be
-		// an unrestricted delete primitive.
-		const resolved = resolve(worktreePath);
-		const storageBase = resolve(getWorktreeStorageDir(root));
-		if (resolved !== storageBase && !resolved.startsWith(storageBase + sep)) {
-			return {
-				success: false,
-				error: `Refusing to clean up '${worktreePath}': path is outside the worktree storage directory (${storageBase}).`,
-			};
-		}
-		const registered = registeredWorktreePaths(root);
-		if (!registered) {
-			return { success: false, error: "Failed to list registered worktrees - aborting cleanup." };
-		}
-		const resolvedRegistered = registered.map((path) => resolve(path));
-		if (!resolvedRegistered.includes(resolved)) {
-			return {
-				success: false,
-				error: `Refusing to clean up '${worktreePath}': not a registered worktree of this repository.`,
-			};
-		}
-		if (resolvedRegistered[0] === resolved) {
-			return { success: false, error: "Refusing to remove the primary working tree." };
-		}
-
-		// Snapshot: stage and commit remaining changes. If the snapshot
-		// cannot be established (hook failure, missing identity, lock
-		// error, timeout), abort - never destroy uncommitted work.
-		const addArgs = ["add", "-A", "--", "."];
-		try {
-			// Exclude the plugin-created node_modules symlink so repos that
-			// do not ignore it never commit a machine-local link.
-			if (lstatSync(join(resolved, "node_modules")).isSymbolicLink()) {
-				addArgs.push(":(exclude)node_modules");
-			}
-		} catch {}
-		const addRes = spawnSync("git", addArgs, {
-			cwd: worktreePath,
-			env: getCleanGitEnv(),
-			encoding: "utf8",
-			timeout: 5_000,
-		});
-		if (addRes.status !== 0) {
-			return {
-				success: false,
-				error: `Snapshot failed (git add: ${(addRes.stderr ?? "").trim()}) - worktree left intact.`,
-			};
-		}
-		const commitRes = spawnSync(
-			"git",
-			["commit", "-m", "chore(worktree): auto-snapshot before cleanup", "--allow-empty"],
-			{ cwd: worktreePath, env: getCleanGitEnv(), encoding: "utf8", timeout: 5_000 },
-		);
-		if (commitRes.status !== 0) {
-			return {
-				success: false,
-				error: `Snapshot failed (git commit: ${(commitRes.stderr ?? "").trim().split("\n").pop()?.trim() ?? "unknown error"}) - worktree left intact.`,
-			};
-		}
-
-		const res = spawnSync("git", ["worktree", "remove", "--force", worktreePath], {
-			cwd: root,
-			env: getCleanGitEnv(),
-			encoding: "utf8",
-			timeout: 10_000,
-		});
-		if (res.status !== 0) {
-			// A failed git removal is an error - never authorization for a
-			// raw recursive delete of the directory.
-			return { success: false, error: res.stderr.trim() || "git worktree remove failed." };
-		}
-
-		return { success: true };
-	} catch (e: any) {
-		return { success: false, error: e?.message ?? String(e) };
-	}
-}
-
-export function isDocumentationRequired(root: string): boolean {
-	if (process.env.WORKFLOW_GUARD_REQUIRE_DOCS === "1") return true;
-	const cfg = cachedProjectConfig ?? loadProjectConfig(root);
-	return cfg.requireDocumentation === true;
-}
-
-function prBodyIncludesChangelog(command: string): boolean {
-	// Handle inline --body / --description / -d / -b "..." with a Changelog section.
-	const bodyMatch = command.match(
-		/(?:--body|--description|-d|-b)(?:=|\s+)(?:"([^"]*)"|'([^']*)'|([^\s|;&]+))/,
-	);
-	const body = bodyMatch?.[1] ?? bodyMatch?.[2] ?? bodyMatch?.[3] ?? "";
-	if (CHANGELOG_SECTION_RE.test(body)) {
-		return true;
-	}
-	// Handle --body-file <path> / --description-file <path> / -F <path>: read the referenced file.
-	const bodyFileMatch = command.match(
-		/(?:--body-file|--description-file|-F)(?:=|\s+)(?:"([^"]*)"|'([^']*)'|([^\s|;&]+))/,
-	);
-	const bodyFile =
-		bodyFileMatch?.[1] ?? bodyFileMatch?.[2] ?? bodyFileMatch?.[3];
-	if (bodyFile) {
-		try {
-			return CHANGELOG_SECTION_RE.test(
-				readFileSync(resolve(workspaceRoot, bodyFile), "utf8"),
-			);
-		} catch {
-			return false;
-		}
-	}
-	return false;
-}
-
-// ── Secondary Agent Review Spoke ─────────────────────────────────────────────
-// Supports multi-agent accountability and code review quality gates before PR
-// or final delivery. Ties into the `code-review-and-quality` and
-// `doubt-driven-development` agent skills with a structured evaluation rubric.
-
-let lastReview:
-	| {
-			passed: boolean;
-			reviewer: string;
-			summary: string;
-			timestamp: number;
-			targetSessionID?: string;
-			workspace?: string;
-	  }
-	| undefined;
-const sessionReviews = new Map<string, NonNullable<typeof lastReview>>();
-
-export function recordReviewResult(
-	reviewer: string,
-	summary: string,
-	passed: boolean,
-	targetSessionID?: string,
-	workspace?: string,
-): void {
-	lastReview = {
-		reviewer,
-		summary: summary.slice(-4000),
-		passed,
-		timestamp: Date.now(),
-		targetSessionID,
-		workspace,
-	};
-	if (targetSessionID) sessionReviews.set(targetSessionID, lastReview);
-}
-
-export function getLastReviewResult(): typeof lastReview {
-	return lastReview;
-}
-
-export function resetReviewState(): void {
-	lastReview = undefined;
-	sessionReviews.clear();
-}
-
-/**
- * Builds a structured, adversarial review rubric prompt for a secondary review agent
- * or subagent (combining `code-review-and-quality` and `doubt-driven-development`).
- */
-export function buildReviewRubric(diffText: string, taskPrompt?: string): string {
-	return [
-		"# Secondary Review Agent Quality Gate",
-		"",
-		"Evaluate this code change independently with fresh context across these 5 core axes:",
-		"",
-		"### 1. Test Integrity & Truthfulness (CRITICAL)",
-		"- Are test assertions testing real behavioral outcomes rather than trivial passes (e.g. `expect(true).toBe(true)`)?",
-		"- Were existing tests disabled, bypassed, or weakened?",
-		"- Are edge cases and error paths covered?",
-		"",
-		"### 2. Task Completeness & Intent Alignment",
-		"- Does the implementation genuinely satisfy the user request without shortcut stubs (`// TODO`, `throw new Error('not implemented')`)?",
-		"- Does it introduce regressions in surrounding code?",
-		"",
-		"### 3. Code Cleanliness & Hygiene",
-		"- Is there any orphaned dead code, commented-out code blocks, or temporary debugging logs?",
-		"- Is the logic straightforward and free of unnecessary cognitive complexity?",
-		"",
-		"### 4. Security & Safety Boundaries",
-		"- Are there any hardcoded secrets, unprotected tokens, or unvalidated user inputs?",
-		"- Does the code respect workspace confinement and safe environment practices?",
-		"",
-		"### 5. Platform & Architecture Fit (GitHub & Azure DevOps)",
-		"- Does the change fit established repository patterns and CI/CD pipelines?",
-		"",
-		taskPrompt ? `### User Request / Context:\n${taskPrompt}\n` : "",
-		"### Code Diff Under Review:",
-		"```diff",
-		diffText.slice(0, 30_000),
-		"```",
-		"",
-		"Provide your verdict: `[APPROVE]` or `[REQUEST_CHANGES]` with concise, actionable findings.",
-	].join("\n");
-}
-
-// ── Core guard (exported for testing) ────────────────────────────────────────
-// Returns a block reason string, or undefined when the call is allowed.
-
-// ── Post-edit verification gate ─────────────────────────────────────────────
-// The guard blocks edits before they happen, and validates verification evidence
-// before final completion. When the agent attempts to mark all tasks completed/cancelled,
-// the guard ensures fresh verification has passed since the most recent mutation.
-
-let lastMutationTimestamp = 0;
-let mutationCount = 0;
-const sessionMutationTimestamps = new Map<string, number>();
-const sessionMutationCounts = new Map<string, number>();
-let lastVerify: {
-	passed: boolean;
-	command: string;
-	output: string;
-	timestamp: number;
-	durationMs?: number;
-	commitHash?: string;
-	gitStatus?: string;
-	workspaceRoot?: string;
-} | undefined;
-const sessionVerifyResults = new Map<string, NonNullable<typeof lastVerify>>();
-
-export function recordMutation(sessionID?: string): void {
-	lastMutationTimestamp = Date.now();
-	mutationCount++;
-	if (sessionID) {
-		sessionMutationTimestamps.set(sessionID, lastMutationTimestamp);
-		sessionMutationCounts.set(sessionID, (sessionMutationCounts.get(sessionID) ?? 0) + 1);
-		sessionVerifyResults.delete(sessionID);
-	}
-	if (sessionID) sessionReviews.delete(sessionID);
-	if (!lastReview?.targetSessionID || lastReview.targetSessionID === sessionID) {
-		lastReview = undefined;
-	}
-}
-
-export function getMutationCount(sessionID?: string): number {
-	if (sessionID && sessionMutationCounts.has(sessionID)) {
-		return sessionMutationCounts.get(sessionID) ?? 0;
-	}
-	return mutationCount;
-}
-
-export function getLastMutationTimestamp(): number {
-	return lastMutationTimestamp;
-}
-
-export function getLastVerifyResult(): typeof lastVerify {
-	return lastVerify;
-}
-
-export function resetVerifyState(): void {
-	lastMutationTimestamp = 0;
-	mutationCount = 0;
-	lastVerify = undefined;
-	sessionMutationTimestamps.clear();
-	sessionMutationCounts.clear();
-	sessionVerifyResults.clear();
-}
-
-// Sensitive environment variables scrubbed from agent shells by the
-// shell.env hook. Prefix matches (AWS_*, KUBE*) and exact names are both
-// listed; the exec-check RE handles the prefix family.
-const SENSITIVE_ENV_KEYS = [
-	"GITHUB_TOKEN",
-	"GH_TOKEN",
-	"OPENAI_API_KEY",
-	"ANTHROPIC_API_KEY",
-	"OPENAI_KEY",
-	"KUBECONFIG",
-	"NPM_TOKEN",
-	"DOCKER_AUTH",
-	"GOOGLE_APPLICATION_CREDENTIALS",
-	"GCLOUD_AUTH",
-	"AZURE_CREDENTIALS",
-	"SLACK_TOKEN",
-];
-const SENSITIVE_ENV_RE = /^(AWS_|KUBE|OPENAI|ANTHROPIC|GH_|GITHUB_|GOOGLE_|GCP_|AZURE_|SLACK_|NPM_|DOCKER_|KUBECONFIG)/;
-
-export function getCleanEnv(): Record<string, string> {
-	const env: Record<string, string> = { ...(process.env as Record<string, string>) };
-	for (const key of SENSITIVE_ENV_KEYS) {
-		delete env[key];
-	}
-	for (const key of Object.keys(env)) {
-		if (SENSITIVE_ENV_RE.test(key)) {
-			delete env[key];
-		}
-	}
-	return env;
-}
-
-/**
- * Truncates and snips verification stdout/stderr for token efficiency.
- * When a test suite or compiler passes, verbose log lines are trimmed to a concise summary.
- * When it fails, failure context, error markers, and stack traces are prioritized.
+ * Orchestrator: imports policy modules from ./policies/ and engine services
+ * from ./lib/, and re-exports the public helper surface for tests.
  */
-export function snipVerifyOutput(output: string, passed: boolean, maxLines = 40): string {
-	if (!output) return "(no output)";
-	const lines = output.trim().split("\n");
-	if (lines.length <= maxLines) return output.trim();
-
-	if (passed) {
-		const head = lines.slice(0, 5).join("\n");
-		const tail = lines.slice(-15).join("\n");
-		return `${head}\n... [${lines.length - 20} lines omitted - all tests passing] ...\n${tail}`;
-	}
-
-	// On failure, preserve stack traces, FAIL/Error keywords, and tail
-	const errorLines: string[] = [];
-	for (const line of lines) {
-		if (/(?:fail|error|exception|panic|assert|reject|expected|received|err:)/i.test(line)) {
-			errorLines.push(line);
-		}
-	}
 
-	const head = lines.slice(0, 5).join("\n");
-	const tail = lines.slice(-20).join("\n");
-	const errorSummary = errorLines.slice(-15).join("\n");
-
-	return [
-		head,
-		`\n--- [Verification Failed: ${lines.length} total lines captured] ---`,
-		errorSummary ? `Key Failures:\n${errorSummary}` : "",
-		`Output Tail:\n${tail}`,
-	]
-		.filter(Boolean)
-		.join("\n");
-}
-
-export function getCurrentGitCommitHash(root: string): string | undefined {
-	try {
-		const res = spawnSync("git", ["rev-parse", "HEAD"], {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 5_000,
-		});
-		if (res.status === 0 && res.stdout.trim()) {
-			return res.stdout.trim();
-		}
-	} catch {}
-	return undefined;
-}
+import { tool, type Plugin, type PluginModule } from "@opencode-ai/plugin";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+export type {
+	TodoItem,
+	TodoSdkClient,
+	ProjectConfig,
+	VerifyResult,
+	ReviewResult,
+	AuditEntry,
+	GitInvocation,
+	ShellMutation,
+} from "./lib/types.ts";
+
+// ── State & runtime context ──────────────────────────────────────────────────
+import {
+	setWorkspaceRoot,
+	getWorkspaceRoot,
+	setSdkClient,
+	getSdkClient,
+	runWithRuntimeState,
+	lastMutationTimestamp,
+	getLastMutationTimestamp,
+	getMutationCount,
+	lastVerify,
+	getLastVerifyResult,
+	recordMutation,
+	recordVerifyResult,
+	resetVerifyState,
+	sessionMutationTimestamps,
+	sessionVerifyResults,
+	loadProjectConfig,
+	reloadProjectConfig,
+	isReviewRequired,
+	isDocumentationRequired,
+	recordReviewResult,
+	getLastReviewResult,
+	resetReviewState,
+	sessionReviews,
+} from "./lib/state.ts";
+
+export {
+	setWorkspaceRoot,
+	getWorkspaceRoot,
+	setSdkClient,
+	getLastMutationTimestamp,
+	getMutationCount,
+	getLastVerifyResult,
+	recordMutation,
+	recordVerifyResult,
+	resetVerifyState,
+	loadProjectConfig,
+	reloadProjectConfig,
+	isReviewRequired,
+	isDocumentationRequired,
+	recordReviewResult,
+	getLastReviewResult,
+	resetReviewState,
+};
 
-export function getGitStatusSummary(root: string): string | undefined {
-	try {
-		const res = spawnSync("git", ["status", "--porcelain"], {
-			cwd: root,
-			encoding: "utf8",
-			timeout: 5_000,
-		});
-		if (res.status === 0) {
-			return res.stdout.trim();
-		}
-	} catch {}
-	return undefined;
-}
+// ── Shared shell/env utilities ───────────────────────────────────────────────
+import {
+	asRecord,
+	extractCommands,
+	normalize,
+	splitShellSegments,
+	getCleanEnv,
+	showBlockToast,
+	SENSITIVE_ENV_KEYS,
+	SENSITIVE_ENV_RE,
+} from "./lib/utils.ts";
+
+export { getCleanEnv };
+
+// ── Audit & durable verification cache ───────────────────────────────────────
+import {
+	getAuditFilePath,
+	getVerifyCacheFilePath,
+	persistVerifyCache,
+	loadVerifyCache,
+	getRecentAuditEntries,
+	audit,
+	logDecision,
+	summarizeInput,
+} from "./lib/audit.ts";
+
+export { getAuditFilePath, getVerifyCacheFilePath, persistVerifyCache, loadVerifyCache, getRecentAuditEntries };
+
+// ── Verification engine ──────────────────────────────────────────────────────
+import {
+	detectVerifyCommand,
+	runVerify,
+	snipVerifyOutput,
+	getCurrentGitCommitHash,
+	getGitStatusSummary,
+} from "./lib/verify.ts";
+
+export {
+	detectVerifyCommand,
+	runVerify,
+	snipVerifyOutput,
+	getCurrentGitCommitHash,
+	getGitStatusSummary,
+};
 
-function detectVerifyCommand(root: string): string | undefined {
-	if (process.env.WORKFLOW_GUARD_VERIFY !== undefined) {
-		const cmd = process.env.WORKFLOW_GUARD_VERIFY.trim();
-		return cmd || undefined; // empty string = "disabled"
-	}
-	const cfg = cachedProjectConfig ?? loadProjectConfig(root);
-	if (typeof cfg.verifyCommand === "string") {
-		const cmd = cfg.verifyCommand.trim();
-		return cmd || undefined;
-	}
-	try {
-		const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as {
-			scripts?: Record<string, string>;
-		};
-		if (pkg.scripts?.test) return "npm test";
-	} catch {}
-	return undefined;
-}
+// ── Secondary review rubric ──────────────────────────────────────────────────
+import { buildReviewRubric } from "./lib/review.ts";
+export { buildReviewRubric };
+
+// ── Git worktree lifecycle ───────────────────────────────────────────────────
+import {
+	getWorktreeStorageDir,
+	getCleanGitEnv,
+	isValidBranchName,
+	createGitWorktree,
+	cleanupGitWorktree,
+} from "./lib/worktree.ts";
+
+export {
+	getWorktreeStorageDir,
+	getCleanGitEnv,
+	isValidBranchName,
+	createGitWorktree,
+	cleanupGitWorktree,
+};
 
-export async function runVerify(
-	command: string,
-	root: string,
-	timeoutMs = 30_000,
-): Promise<{ passed: boolean; output: string; durationMs: number }> {
-	const start = Date.now();
-	const allowLive = process.env.WORKFLOW_GUARD_ALLOW_LIVE === "1";
+// ── Policy modules ───────────────────────────────────────────────────────────
+import {
+	EDIT_TOOL_NAMES,
+	validateTodoLifecycle,
+	fetchSessionTodos,
+	fetchParentSessionID,
+	effectiveTodos,
+	effectiveTodoOwnerSessionID,
+	hasActiveTodo,
+} from "./policies/todo.ts";
+
+export { validateTodoLifecycle };
+
+import {
+	PUSH_TO_MAIN_RE,
+	GIT_WRITE_RE,
+	GIT_BRANCH_CREATE_RE,
+	currentGitBranch,
+	onProtectedBranch,
+	isProtectedBranchName,
+	pushedProtectedBranchIn,
+	branchGuardReason,
+	parseGitInvocation,
+	normalizeGitCommands,
+	isBranchAlreadyMergedOrClosed,
+	checkMergeConflicts,
+	checkBranchBaseIsUpToDate,
+} from "./policies/git.ts";
+
+export {
+	isProtectedBranchName,
+	isBranchAlreadyMergedOrClosed,
+	checkMergeConflicts,
+	checkBranchBaseIsUpToDate,
+};
 
-	// Guard against privileged execution of destructive commands or settings tampering in verify scripts
-	if (!allowLive) {
-		const normalized = normalizeGitCommands(normalize(command));
-		const liveCheck = liveMutationIn(normalized);
-		if (liveCheck) {
-			return {
-				passed: false,
-				output: `Verification command blocked: contains live destructive command (${liveCheck})`,
-				durationMs: 0,
-			};
-		}
-		if (isSettingsTamper(command)) {
-			return {
-				passed: false,
-				output: "Verification command blocked: contains settings tamper command",
-				durationMs: 0,
-			};
-		}
-	}
+import {
+	hasPrCreateInvocation,
+	branchHasChangelogChange,
+	prBodyIncludesChangelog,
+} from "./policies/changelog.ts";
 
-	return new Promise((resolve) => {
-		let output = "";
-		let timer: NodeJS.Timeout | undefined;
-		let child: ReturnType<typeof spawn>;
-		try {
-			child = spawn(command, {
-				cwd: root,
-				shell: true,
-				env: getCleanEnv(),
-				stdio: ["ignore", "pipe", "pipe"],
-			});
-		} catch (err: any) {
-			return resolve({
-				passed: false,
-				output: `(spawn failed: ${err?.message ?? "unknown error"})`,
-				durationMs: Date.now() - start,
-			});
-		}
+import { liveMutationIn, extractEditContent } from "./policies/destructive.ts";
 
-		timer = setTimeout(() => {
-			try {
-				child.kill("SIGKILL");
-			} catch {}
-			resolve({
-				passed: false,
-				output: output + `\n(Verification timed out after ${Math.round(timeoutMs / 1000)}s)`,
-				durationMs: Date.now() - start,
-			});
-		}, timeoutMs);
+import { mcpMutationTool } from "./policies/mcp.ts";
 
-		child.stdout?.on("data", (d) => {
-			output += d.toString();
-			if (output.length > 50_000) output = output.slice(-50_000);
-		});
-		child.stderr?.on("data", (d) => {
-			output += d.toString();
-			if (output.length > 50_000) output = output.slice(-50_000);
-		});
-		child.on("close", (code) => {
-			if (timer) clearTimeout(timer);
-			resolve({ passed: code === 0, output, durationMs: Date.now() - start });
-		});
-		child.on("error", (err) => {
-			if (timer) clearTimeout(timer);
-			resolve({ passed: false, output: `(spawn failed: ${err.message})`, durationMs: Date.now() - start });
-		});
-	});
-}
+import {
+	PROTECTED_PATH_REASON,
+	isProtectedPath,
+	isSettingsTamper,
+} from "./policies/tamper.ts";
 
-const AUDIT_DIR = join(
-	process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state"),
-	"opencode",
-	"workflow-guard",
-);
-const AUDIT_FILE = join(AUDIT_DIR, "workflow-guard.jsonl");
-const VERIFY_CACHE_FILE = join(AUDIT_DIR, "last-verify.json");
+export { isProtectedPath };
 
-export function getAuditFilePath(): string {
-	return AUDIT_FILE;
-}
+import {
+	isPathOutsideWorkspace,
+	extractPatchPaths,
+	guardShellMutation,
+} from "./policies/boundary.ts";
 
-export function getVerifyCacheFilePath(): string {
-	return VERIFY_CACHE_FILE;
-}
+import { isSecretPath, secretIn, secretFileReadIn, isEnvFilePath, generateMaskedEnvSchema } from "./policies/secrets.ts";
 
-/**
- * Persists passing verification evidence to disk so session restarts
- * or multi-agent handoffs retain valid verification state.
- */
-export function persistVerifyCache(verifyData: NonNullable<typeof lastVerify>): void {
-	try {
-		mkdirSync(AUDIT_DIR, { recursive: true });
-		writeFileSync(VERIFY_CACHE_FILE, JSON.stringify(verifyData, null, 2), "utf8");
-	} catch {}
-}
+export { isSecretPath, isEnvFilePath, generateMaskedEnvSchema };
 
-/**
- * Loads durable verification evidence from disk if present and fresh.
- */
-export function loadVerifyCache(): typeof lastVerify {
-	try {
-		if (!existsSync(VERIFY_CACHE_FILE)) return undefined;
-		const raw = readFileSync(VERIFY_CACHE_FILE, "utf8");
-		const data = JSON.parse(raw);
-		if (data && typeof data.command === "string" && typeof data.timestamp === "number") {
-			return data;
-		}
-	} catch {}
-	return undefined;
-}
+import { extractInterpreterPayload } from "./policies/interpreter.ts";
+export { extractInterpreterPayload };
 
-export function recordVerifyResult(
-	command: string,
-	result: { passed: boolean; output: string; durationMs?: number },
-	sessionID?: string,
-	root = workspaceRoot,
-): void {
-	const snippedOutput = snipVerifyOutput(result.output, result.passed);
-	const commitHash = getCurrentGitCommitHash(root);
-	const gitStatus = getGitStatusSummary(root);
-
-	lastVerify = {
-		command,
-		passed: result.passed,
-		output: snippedOutput,
-		timestamp: Date.now(),
-		durationMs: result.durationMs,
-		commitHash,
-		workspaceRoot: resolve(root),
-		gitStatus,
-	};
-	if (sessionID && lastVerify) sessionVerifyResults.set(sessionID, lastVerify);
-	if (lastVerify.passed) {
-		persistVerifyCache(lastVerify);
-	}
-}
+import { branchHasDocumentationChange } from "./policies/docs.ts";
+export { branchHasDocumentationChange };
 
-export function getRecentAuditEntries(limit = 10): AuditEntry[] {
-	try {
-		if (!existsSync(AUDIT_FILE)) return [];
-		const lines = readFileSync(AUDIT_FILE, "utf8").trim().split("\n");
-		const entries: AuditEntry[] = [];
-		for (let i = lines.length - 1; i >= 0 && entries.length < limit; i--) {
-			const line = lines[i]?.trim();
-			if (line) {
-				try {
-					entries.push(JSON.parse(line));
-				} catch {}
-			}
-		}
-		return entries;
-	} catch {
-		return [];
-	}
-}
+import {
+	checkInteractiveTtyCommand,
+	checkPackageHygiene,
+	sendDesktopNotification,
+} from "./policies/shell-safety.ts";
 
-export interface AuditEntry {
-	ts: string;
-	sessionID?: string;
-	tool: string;
-	decision: "allow" | "block";
-	reason?: string;
-	input?: unknown;
-	evidence?: {
-		mutation?: boolean;
-		targetPath?: string;
-		verification?: {
-			command: string;
-			passed: boolean;
-			fresh: boolean;
-			durationMs?: number;
-		};
-		allowLive?: boolean;
-	};
-}
+import { checkCompletionClaims } from "./policies/completion.ts";
 
-function audit(entry: AuditEntry): void {
-	try {
-		mkdirSync(AUDIT_DIR, { recursive: true });
-		appendFileSync(AUDIT_FILE, JSON.stringify(entry) + "\n", "utf8");
-	} catch {
-		// Logging must never break the guard.
-	}
-}
+export { checkCompletionClaims };
 
-function logDecision(
-	tool: string,
-	input: unknown,
-	context: { sessionID?: string } | undefined,
-	reason: string | undefined,
-	evidence?: AuditEntry["evidence"],
-): void {
-	audit({
-		ts: new Date().toISOString(),
-		sessionID: context?.sessionID,
-		tool,
-		decision: reason ? "block" : "allow",
-		reason,
-		input: summarizeInput(input),
-		evidence,
-	});
-}
+export { checkInteractiveTtyCommand, checkPackageHygiene, sendDesktopNotification };
 
-function summarizeInput(input: unknown): unknown {
-	const record = asRecord(input);
-	if (!record) return typeof input === "string" ? input.slice(0, 200) : input;
-	if (typeof record.command === "string") return { command: record.command.slice(0, 200) };
-	if (typeof record.filePath === "string") return { filePath: record.filePath };
-	if (typeof record.path === "string") return { path: record.path };
-	if (typeof record.patchText === "string") return { patchText: record.patchText.slice(0, 200) };
-	return { keys: Object.keys(record) };
-}
+const SHELL_TOOL_NAMES = new Set(["bash", "run_commands", "execute_command", "shell"]);
 
 function logBlock(message: string): void {
-	// In OpenCode TUI, writing to process.stderr / console.error writes directly
-	// to the terminal screen and pollutes the interactive chat prompt input box.
-	// We route blocked action logs to the OpenCode app logger instead.
 	try {
-		(sdkClient as any)?.app?.log?.({
+		void (getSdkClient() as any)?.app?.log?.({
 			body: {
 				service: "workflow-guard",
 				level: "warn",
@@ -2330,8 +238,10 @@ async function guardToolCallImpl(
 	input: unknown,
 	context?: { sessionID?: string },
 ): Promise<string | undefined> {
-	// ── Policy 17: Secret file READ guard (.env*, keys, kubeconfig, credentials) ──
-	if (toolName === "read") {
+	const currentRoot = getWorkspaceRoot();
+
+	// ── Policy 17: secret file read block via read tool ──
+	if (toolName === "read" || toolName === "read_file") {
 		const record = asRecord(input);
 		const target =
 			typeof record?.filePath === "string"
@@ -2346,7 +256,7 @@ async function guardToolCallImpl(
 			if (isEnvFilePath(target)) {
 				let schemaHint = "";
 				try {
-					const resolvedTarget = resolve(workspaceRoot, target);
+					const resolvedTarget = resolve(currentRoot, target);
 					if (existsSync(resolvedTarget)) {
 						const raw = readFileSync(resolvedTarget, "utf8");
 						const masked = generateMaskedEnvSchema(raw);
@@ -2366,12 +276,12 @@ async function guardToolCallImpl(
 		return undefined;
 	}
 
-	// ── Policy 1: todowrite lifecycle & focus validation ──
+	// ── Policy 1: todowrite lifecycle validation & finalization gates ──
 	if (toolName === "todowrite") {
 		const record = asRecord(input);
 		const rawTodos = record?.todos;
 		if (Array.isArray(rawTodos)) {
-			const newTodos = rawTodos as TodoItem[];
+			const newTodos = rawTodos as any[];
 			const existingTodos = context?.sessionID
 				? await fetchSessionTodos(context.sessionID)
 				: undefined;
@@ -2381,10 +291,6 @@ async function guardToolCallImpl(
 				return err;
 			}
 
-			// Final-completion gate (Policy 10): when EVERY task is being marked
-			// done, run verification on-demand if a verify command is configured.
-			// This replaces the old background-per-edit approach with a single
-			// verification run at finalization time.
 			const allDone =
 				newTodos.length > 0 &&
 				newTodos.every((t) => {
@@ -2392,49 +298,45 @@ async function guardToolCallImpl(
 					return s === "completed" || s === "cancelled";
 				});
 			if (allDone) {
-				// Conflict-free mergeability gate before task completion/handoff
-				const conflictCheck = checkMergeConflicts(workspaceRoot);
+				// Policy 19: conflict-free mergeability gate before task completion/handoff
+				const conflictCheck = checkMergeConflicts(currentRoot);
 				if (conflictCheck.hasConflicts) {
 					const reason = `Blocked todowrite: ${conflictCheck.reason}`;
 					logBlock(`[workflow-guard] ${reason}`);
 					return reason;
 				}
 
-				const command = detectVerifyCommand(workspaceRoot);
+				// Policy 10: evidence-based verification
+				const command = detectVerifyCommand(currentRoot);
 				if (command) {
 					const sessionID = context?.sessionID;
 					let verifyResult = sessionID
 						? sessionVerifyResults.get(sessionID)
 						: lastVerify;
 
-				// If in-memory cache is missing, attempt to recover from durable disk cache.
-				// Durable evidence is bound to the workspace that produced it: without
-				// this check a passing run from a different project (identical verify
-				// command, non-git state) could satisfy finalization here.
-				if (!verifyResult) {
-					const diskCached = loadVerifyCache();
-					if (
-						diskCached &&
-						diskCached.passed &&
-						diskCached.command === command &&
-						diskCached.workspaceRoot === resolve(workspaceRoot)
-					) {
-						verifyResult = diskCached;
+					// Recover durable evidence from disk when in-memory state is missing.
+					// Durable evidence is bound to the workspace that produced it: without
+					// this check a passing run from a different project (identical verify
+					// command, non-git state) could satisfy finalization here.
+					if (!verifyResult) {
+						const diskCached = loadVerifyCache();
+						if (
+							diskCached &&
+							diskCached.passed &&
+							diskCached.command === command &&
+							diskCached.workspaceRoot === resolve(currentRoot)
+						) {
+							verifyResult = diskCached;
+						}
 					}
-				}
 
 					const mutationTimestamp = sessionID
 						? (sessionMutationTimestamps.get(sessionID) ?? 0)
 						: lastMutationTimestamp;
 
-					const currentCommit = getCurrentGitCommitHash(workspaceRoot);
-					const currentGitStatus = getGitStatusSummary(workspaceRoot);
+					const currentCommit = getCurrentGitCommitHash(currentRoot);
+					const currentGitStatus = getGitStatusSummary(currentRoot);
 
-					// Verification freshness requires:
-					// 1. Result passed
-					// 2. Matching verify command
-					// 3. Timestamp is equal to or newer than the latest mutation
-					// 4. Git commit and git status matches the state when verified (if git repo)
 					const gitStateMatches =
 						!verifyResult?.commitHash ||
 						(verifyResult.commitHash === currentCommit &&
@@ -2448,10 +350,10 @@ async function guardToolCallImpl(
 						gitStateMatches;
 
 					if (!isFresh) {
-						const result = await runVerify(command, workspaceRoot);
-						recordVerifyResult(command, result, sessionID, workspaceRoot);
+						const result = await runVerify(command, currentRoot);
+						recordVerifyResult(command, result, sessionID, currentRoot);
 						if (!result.passed) {
-							const tail = result.output.slice(-500);
+							const tail = snipVerifyOutput(result.output, result.passed).slice(-500);
 							const reason =
 								`Blocked todowrite: all tasks marked done but verification is failing ` +
 								`(${command}). Fix the failure before finishing; ` +
@@ -2479,8 +381,6 @@ async function guardToolCallImpl(
 						? input
 						: "";
 
-		// Settings tamper via edit tools (P0.2): editing opencode config or
-		// the guard's own plugin files is blocked even via the edit tools.
 		if (target && isProtectedPath(target)) {
 			logBlock(`[workflow-guard] blocked ${toolName}: protected path ${target}`);
 			return PROTECTED_PATH_REASON;
@@ -2508,26 +408,22 @@ async function guardToolCallImpl(
 					);
 					return `Blocked: modifying secret file '${patchPath}' directly is not permitted.`;
 				}
-				if (isPathOutsideWorkspace(patchPath, workspaceRoot)) {
+				if (isPathOutsideWorkspace(patchPath, currentRoot)) {
 					logBlock(
 						`[workflow-guard] blocked apply_patch: patch target escapes workspace: ${patchPath}`,
 					);
-					return `Blocked: patch targets file '${patchPath}' outside workspace root (${workspaceRoot}).`;
+					return `Blocked: patch targets file '${patchPath}' outside workspace root (${currentRoot}).`;
 				}
 			}
 		}
 
-		// Workspace boundary check (path traversal guard)
-		if (target && isPathOutsideWorkspace(target, workspaceRoot)) {
+		if (target && isPathOutsideWorkspace(target, currentRoot)) {
 			logBlock(
 				`[workflow-guard] blocked ${toolName}: path escapes workspace: ${target}`,
 			);
-			return `Blocked: file path '${target}' escapes workspace root (${workspaceRoot}). All changes must stay within the workspace.`;
+			return `Blocked: file path '${target}' escapes workspace root (${currentRoot}). All changes must stay within the workspace.`;
 		}
 
-		// Secret-content scan (Policy 12): common credential material must
-		// never be written into the repo. The agent often has access to env
-		// vars the user does NOT want committed; block at the write step.
 		for (const content of extractEditContent(input)) {
 			const secret = secretIn(content);
 			if (secret) {
@@ -2543,16 +439,10 @@ async function guardToolCallImpl(
 			}
 		}
 
-		// Script-laundering guard (P0.5): file payloads that contain
-		// destructive commands or tamper instructions are blocked, so an
-		// agent cannot smuggle a blocked command into a script file and run
-		// it through the shell. We scan line-by-line and skip comment lines
-		// to reduce false positives on documentation.
 		if (!allowLive) {
 			for (const content of extractEditContent(input)) {
 				const lines = content.split("\n");
 				for (const line of lines) {
-					// Skip comment lines (bash, js, python, etc.)
 					const trimmed = line.trim();
 					if (trimmed.startsWith("#") || trimmed.startsWith("//") || trimmed.startsWith("/*") || trimmed.startsWith("*")) {
 						continue;
@@ -2582,9 +472,9 @@ async function guardToolCallImpl(
 			}
 		}
 
-		if (onProtectedBranch(workspaceRoot)) {
+		if (onProtectedBranch(currentRoot)) {
 			logBlock(
-				`[workflow-guard] blocked ${toolName}: on protected branch ${currentGitBranch(workspaceRoot)}`,
+				`[workflow-guard] blocked ${toolName}: on protected branch ${currentGitBranch(currentRoot)}`,
 			);
 			return branchGuardReason();
 		}
@@ -2596,7 +486,7 @@ async function guardToolCallImpl(
 			return (
 				"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 top to bottom, marking " +
+				"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."
@@ -2609,7 +499,6 @@ async function guardToolCallImpl(
 	const allowLive = process.env.WORKFLOW_GUARD_ALLOW_LIVE === "1";
 
 	// ── Policy 5: MCP tools that mutate GitHub / Azure / DevOps ──
-	// MCP calls carry no command string, so the only override is the env var.
 	if (!allowLive) {
 		const mcpWhat = mcpMutationTool(toolName);
 		if (mcpWhat) {
@@ -2634,7 +523,7 @@ async function guardToolCallImpl(
 	for (const raw of commands) {
 		const command = normalize(raw);
 
-		// ── Policy 22: Non-interactive shell & TTY hang guard ───────
+		// ── Policy 22: non-interactive shell & TTY hang guard ──
 		const ttyCheck = checkInteractiveTtyCommand(command);
 		if (ttyCheck.isInteractive) {
 			logBlock(`[workflow-guard] blocked interactive TTY command: ${command.slice(0, 100)}`);
@@ -2644,7 +533,7 @@ async function guardToolCallImpl(
 			);
 		}
 
-		// ── Policy 23: Package supply-chain & dependency hygiene guard ────
+		// ── Policy 23: package supply-chain & dependency hygiene guard ──
 		const packageCheck = checkPackageHygiene(command);
 		if (packageCheck.isViolating && !allowLive) {
 			logBlock(`[workflow-guard] blocked package supply-chain violation: ${command.slice(0, 100)}`);
@@ -2654,27 +543,28 @@ async function guardToolCallImpl(
 			);
 		}
 
-		// Rewrite `git [global-opts] <sub>` to `git <sub>` so global flags
-		// cannot smuggle a guarded subcommand past the regexes.
 		const normalizedCommand = normalizeGitCommands(command);
 		const gitInvocations = splitShellSegments(command)
 			.map((segment) => parseGitInvocation(segment.trim()))
-			.filter((invocation): invocation is GitInvocation => invocation !== undefined);
-		const effectiveRoot = gitInvocations[0]?.repoDir ?? workspaceRoot;
+			.filter((invocation): invocation is NonNullable<ReturnType<typeof parseGitInvocation>> => invocation !== undefined);
+		const effectiveRoot = gitInvocations[0]?.repoDir ?? currentRoot;
 
 		// Workspace boundary check for external git repo targets
 		for (const invocation of gitInvocations) {
 			const normalizedInvocation = `git ${invocation.rest}`;
+			// The workspace boundary has no allow-live override (same invariant as
+			// file redirects/mv): an external repository write is out of bounds even
+			// with WORKFLOW_GUARD_ALLOW_LIVE=1.
 			if (
-				isPathOutsideWorkspace(invocation.repoDir, workspaceRoot) &&
+				isPathOutsideWorkspace(invocation.repoDir, currentRoot) &&
 				(GIT_WRITE_RE.test(normalizedInvocation) || /\bgit\s+push\b/.test(normalizedInvocation))
 			) {
 				logBlock(`[workflow-guard] blocked git mutation on repository outside workspace: ${invocation.repoDir}`);
-				return `Blocked: git command targets repository '${invocation.repoDir}' outside workspace root (${workspaceRoot}). All changes must stay within the workspace.`;
+				return `Blocked: git command targets repository '${invocation.repoDir}' outside workspace root (${currentRoot}). All changes must stay within the workspace.`;
 			}
 		}
 
-		// ── Policy 7: changes only on feature branches ───────────
+		// ── Policy 7: changes only on feature branches ──
 		for (const invocation of gitInvocations) {
 			if (GIT_WRITE_RE.test(`git ${invocation.rest}`) && onProtectedBranch(invocation.repoDir)) {
 				logBlock(
@@ -2684,7 +574,7 @@ async function guardToolCallImpl(
 			}
 		}
 
-		// Check if creating a fresh branch while local base is behind remote
+		// Policy 20: base freshness when creating a fresh branch
 		if (GIT_BRANCH_CREATE_RE.test(normalizedCommand)) {
 			const behindCheck = checkBranchBaseIsUpToDate(effectiveRoot);
 			if (behindCheck.isBehind) {
@@ -2703,7 +593,7 @@ async function guardToolCallImpl(
 			return PROTECTED_PATH_REASON;
 		}
 
-		// ── Policy 17: Secret file reads via shell (cat .env, grep id_rsa, etc.) ──
+		// ── Policy 17: secret file reads via shell ──
 		if (!allowLive) {
 			for (const segment of command.split(/[\n|;&]+/)) {
 				const secretFile = secretFileReadIn(segment.trim());
@@ -2719,7 +609,7 @@ async function guardToolCallImpl(
 			}
 		}
 
-		// ── Policy 18: Interpreter inline evasion scanner ────────
+		// ── Policy 18: interpreter inline evasion scanner ──
 		if (!allowLive) {
 			for (const payload of extractInterpreterPayload(command)) {
 				const normPayload = normalizeGitCommands(normalize(payload));
@@ -2768,7 +658,7 @@ async function guardToolCallImpl(
 			}
 		}
 
-		// ── Policy 2: block git push to main/master ──────────────────
+		// ── Policy 2: block git push to main/master ──
 		if (PUSH_TO_MAIN_RE.test(normalizedCommand)) {
 			logBlock(
 				`[workflow-guard] blocked push to main/master: ${command}`,
@@ -2794,6 +684,7 @@ async function guardToolCallImpl(
 				);
 			}
 		}
+
 		// ── Policy 20: block push from protected or already-merged branches ──
 		for (const invocation of gitInvocations) {
 			if (!/\bgit\s+push\b/.test(`git ${invocation.rest}`)) continue;
@@ -2820,21 +711,19 @@ async function guardToolCallImpl(
 		if (hasPrCreateInvocation(raw)) {
 			const isAz = /\baz\s+repos\s+pr\s+create\b/.test(normalizedCommand);
 			const prTool = isAz ? "az repos pr create" : "gh pr create";
+			const descFlag = isAz ? "--description" : "--body";
 
-			// Policy 19: Conflict-free mergeability gate before opening PR
-			const conflictCheck = checkMergeConflicts(workspaceRoot);
+			// Policy 19: conflict-free mergeability gate before opening PR
+			const conflictCheck = checkMergeConflicts(currentRoot);
 			if (conflictCheck.hasConflicts) {
 				logBlock(`[workflow-guard] blocked ${prTool}: merge conflicts detected`);
 				return `Blocked: ${conflictCheck.reason}`;
 			}
 
-			// Policy 20: Check if branch is already merged/closed
-			const branch = currentGitBranch(workspaceRoot);
+			// Policy 20: branch already merged/closed
+			const branch = currentGitBranch(currentRoot);
 			if (branch) {
-				const mergedStatus = isBranchAlreadyMergedOrClosed(
-					workspaceRoot,
-					branch,
-				);
+				const mergedStatus = isBranchAlreadyMergedOrClosed(currentRoot, branch);
 				if (mergedStatus.merged) {
 					logBlock(
 						`[workflow-guard] blocked ${prTool}: branch already merged/closed`,
@@ -2843,13 +732,13 @@ async function guardToolCallImpl(
 				}
 			}
 
-			if (isReviewRequired(workspaceRoot)) {
+			if (isReviewRequired(currentRoot)) {
 				const review = context?.sessionID
 					? (sessionReviews.get(context.sessionID) ?? getLastReviewResult())
 					: getLastReviewResult();
 				const reviewMatchesContext =
 					review?.passed === true &&
-					(!review.workspace || review.workspace === workspaceRoot) &&
+					(!review.workspace || review.workspace === currentRoot) &&
 					(!review.targetSessionID || review.targetSessionID === context?.sessionID);
 				if (!reviewMatchesContext) {
 					logBlock(`[workflow-guard] blocked ${prTool}: review approval required`);
@@ -2860,9 +749,9 @@ async function guardToolCallImpl(
 				}
 			}
 
-			// Policy 21: Documentation review & update check
-			if (isDocumentationRequired(workspaceRoot)) {
-				const hasDocChange = branchHasDocumentationChange(workspaceRoot);
+			// Policy 21: documentation review & update check
+			if (isDocumentationRequired(currentRoot)) {
+				const hasDocChange = branchHasDocumentationChange(currentRoot);
 				if (!hasDocChange) {
 					logBlock(`[workflow-guard] blocked ${prTool}: documentation update required`);
 					return (
@@ -2872,19 +761,14 @@ async function guardToolCallImpl(
 				}
 			}
 
-			const branchChangelog = branchHasChangelogChange(workspaceRoot);
+			const branchChangelog = branchHasChangelogChange(currentRoot);
 			const prSegments = splitShellSegments(raw)
 				.filter((segment) => hasPrCreateInvocation(segment));
 			const hasChangelog =
 				branchChangelog ||
 				prSegments.every((segment) => prBodyIncludesChangelog(segment));
 			if (!hasChangelog) {
-				const isAz = /\baz\s+repos\s+pr\s+create\b/.test(normalizedCommand);
-				const prTool = isAz ? "az repos pr create" : "gh pr create";
-				const descFlag = isAz ? "--description" : "--body";
-				logBlock(
-					`[workflow-guard] blocked ${prTool}: no changelog found`,
-				);
+				logBlock(`[workflow-guard] blocked ${prTool}: no changelog found`);
 				return (
 					`Blocked: PR must include a changelog. Either update a ` +
 					`CHANGELOG file in this branch's diff, or include a ` +
@@ -2943,27 +827,11 @@ export async function guardToolCall(
 	return reason;
 }
 
-/** Set the workspace root (used by the plugin and tests). */
-export function setWorkspaceRoot(root: string): void {
-	workspaceRoot = root;
-	try {
-		workspaceRootReal = realpathSync(root);
-	} catch {
-		workspaceRootReal = root;
-	}
-}
-
-async function showBlockToast(message: string): Promise<void> {
+async function emitBlockFeedback(message: string): Promise<void> {
 	try {
 		sendDesktopNotification("Workflow Guard Blocked", message);
-		await sdkClient?.tui?.showToast?.({
-			body: {
-				title: "Workflow Guard Blocked",
-				message: message.slice(0, 180),
-				variant: "warning",
-			},
-		});
 	} catch {}
+	await showBlockToast(message);
 }
 
 export const WorkflowGuard: Plugin = async (ctx) => {
@@ -2985,30 +853,32 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 	} catch {}
 
 	return {
-		// Custom inspection and review tools registered in OpenCode
 		tool: {
 			guard_status: tool({
 				description:
 					"Inspect active guardrails, current branch protection, and verification/review status.",
 				args: {},
 				execute: async () => {
-					const branch = currentGitBranch(workspaceRoot) ?? "unknown";
-					const isProtected = onProtectedBranch(workspaceRoot);
+					const root = getWorkspaceRoot();
+					const branch = currentGitBranch(root) ?? "unknown";
+					const isProtected = onProtectedBranch(root);
 					const lastV = getLastVerifyResult();
 					const lastR = getLastReviewResult();
 					const lastMut = getLastMutationTimestamp();
-					const cfg = loadProjectConfig(workspaceRoot);
+					const cfg = loadProjectConfig(root);
 					return JSON.stringify(
 						{
-							workspaceRoot,
+							workspaceRoot: root,
 							branch,
 							onProtectedBranch: isProtected,
 							lastMutationTimestamp: lastMut,
+							mutationCount: getMutationCount(),
 							lastVerify: lastV
 								? {
 										command: lastV.command,
 										passed: lastV.passed,
 										fresh: lastV.timestamp >= lastMut,
+										commitHash: lastV.commitHash,
 									}
 								: null,
 							lastReview: lastR
@@ -3020,9 +890,9 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 								: null,
 							projectConfig: {
 								protectedBranches: cfg.protectedBranches ?? ["main", "master"],
-								verifyCommand: detectVerifyCommand(workspaceRoot) ?? null,
-								requireReview: isReviewRequired(workspaceRoot),
-								requireDocumentation: isDocumentationRequired(workspaceRoot),
+								verifyCommand: detectVerifyCommand(root) ?? null,
+								requireReview: isReviewRequired(root),
+								requireDocumentation: isDocumentationRequired(root),
 							},
 						},
 						null,
@@ -3066,7 +936,7 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 			}),
 			record_review: tool({
 				description:
-					"Record a secondary reviewer agent's approval or critique of the current changes.",
+					"Record a secondary reviewer agent's approval or critique of the current changes. The summary must reference the 5 core review axes from guard_review_rubric.",
 				args: {
 					reviewer: tool.schema
 						.string()
@@ -3083,6 +953,24 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					if (!parentSessionID) {
 						return "[workflow-guard] Review rejected: record_review must be called from a secondary/subagent session.";
 					}
+					// The rubric is the contract: a recorded review must demonstrate it
+					// was evaluated against the 5 axes, not just assert a verdict.
+					const axesRefs = [
+						"test integrity",
+						"task completeness",
+						"cleanliness",
+						"security",
+						"platform",
+					];
+					const summaryLower = args.summary.toLowerCase();
+					const referenced = axesRefs.filter((axis) => summaryLower.includes(axis));
+					if (referenced.length < 3) {
+						return (
+							`[workflow-guard] Review rejected: summary must reference the review axes ` +
+							`(found ${referenced.length}/5). Call guard_review_rubric to get the rubric, ` +
+							`evaluate each axis, and include findings per axis in the summary.`
+						);
+					}
 					recordReviewResult(
 						args.reviewer,
 						args.summary,
@@ -3095,6 +983,42 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 						: `[workflow-guard] Review recorded as CHANGES REQUESTED by ${args.reviewer}.`;
 				},
 			}),
+			guard_review_rubric: tool({
+				description:
+					"Get the secondary-review rubric for the current branch diff. The orchestrator calls this, spawns a reviewer subagent with the rubric as the prompt, then the reviewer records its verdict via record_review.",
+				args: {
+					base: tool.schema
+						.string()
+						.optional()
+						.describe("Base ref to diff against (default: origin/main, origin/master, main)"),
+				},
+				execute: async (args) => {
+					const bases = args.base
+						? [args.base]
+						: ["origin/main", "origin/master", "main", "master"];
+					let diffText = "";
+					for (const base of bases) {
+						const res = spawnSync(
+							"git",
+							["diff", `${base}...HEAD`],
+							{ cwd: getWorkspaceRoot(), encoding: "utf8", timeout: 10_000 },
+						);
+						if (res.status === 0 && res.stdout.trim()) {
+							diffText = res.stdout;
+							break;
+						}
+					}
+					if (!diffText) {
+						const last = spawnSync("git", ["diff", "HEAD~1"], {
+							cwd: getWorkspaceRoot(),
+							encoding: "utf8",
+							timeout: 10_000,
+						});
+						diffText = last.status === 0 ? last.stdout : "(no diff available)";
+					}
+					return buildReviewRubric(diffText);
+				},
+			}),
 			guard_worktree_create: tool({
 				description:
 					"Create an isolated git worktree directory for concurrent subagent execution.",
@@ -3115,12 +1039,14 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 							"Break the request down with todowrite first, then create worktrees."
 						);
 					}
-					const effectiveRoot = toolContext.worktree || toolContext.directory || workspaceRoot;
-					const res = createGitWorktree(args.branch, args.baseBranch ?? "HEAD", effectiveRoot);
+					const toolRoot = toolContext.worktree || toolContext.directory || effectiveRoot;
+					const res = createGitWorktree(args.branch, args.baseBranch ?? "HEAD", toolRoot);
 					if (!res.success) {
 						return `[workflow-guard] Failed to create worktree: ${res.error}`;
 					}
-					recordMutation((await effectiveTodoOwnerSessionID(toolContext.sessionID)) ?? toolContext.sessionID);
+					recordMutation(
+						(await effectiveTodoOwnerSessionID(toolContext.sessionID)) ?? toolContext.sessionID,
+					);
 					return (
 						`[workflow-guard] Worktree created successfully at: ${res.worktreePath}\n` +
 						`Run subagent tasks or pass worktree directory context to isolate file mutations.`
@@ -3143,42 +1069,34 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 							"Break the request down with todowrite first, then clean up worktrees."
 						);
 					}
-					const effectiveRoot = toolContext.worktree || toolContext.directory || workspaceRoot;
-					const res = cleanupGitWorktree(args.worktreePath, effectiveRoot);
+					const toolRoot = toolContext.worktree || toolContext.directory || effectiveRoot;
+					const res = cleanupGitWorktree(args.worktreePath, toolRoot);
 					if (!res.success) {
 						return `[workflow-guard] Failed to clean up worktree: ${res.error}`;
 					}
-					recordMutation((await effectiveTodoOwnerSessionID(toolContext.sessionID)) ?? toolContext.sessionID);
+					recordMutation(
+						(await effectiveTodoOwnerSessionID(toolContext.sessionID)) ?? toolContext.sessionID,
+					);
 					return `[workflow-guard] Worktree at '${args.worktreePath}' cleaned up successfully.`;
 				},
 			}),
 		},
 
-		// OpenCode passes the tool args as the SECOND hook parameter
-		// (`output.args` - documented in the tools docs, e.g. apply_patch
-		// "uses output.args.patchText"; `input` only carries
-		// { tool, sessionID, callID }). The fallback covers hypothetical
-		// runtimes that put args on the input.
 		"tool.execute.before": async (input, output) => {
-			const args =
-				(output as { args?: unknown } | undefined)?.args ??
-				(input as { args?: unknown }).args;
-			const reason = await guardToolCall(input.tool, args, {
-				sessionID: input.sessionID,
+			return runWithRuntimeState(effectiveRoot, ctx.client, async () => {
+				const args =
+					(output as { args?: unknown } | undefined)?.args ??
+					(input as { args?: unknown }).args;
+				const reason = await guardToolCall(input.tool, args, {
+					sessionID: input.sessionID,
+				});
+				if (reason !== undefined) {
+					await emitBlockFeedback(reason);
+					throw new Error(`[workflow-guard] ${reason}`);
+				}
 			});
-			if (reason !== undefined) {
-				await showBlockToast(reason);
-				throw new Error(`[workflow-guard] ${reason}`);
-			}
 		},
 
-		// Post-edit verification runs when the agent attempts to finalize
-		// the todo list (all tasks completed) - enforced in the
-		// tool.execute.before todowrite branch above. This avoids running
-		// tests on intermediate broken states and reduces overhead.
-
-		// Focus preservation across context compaction (documented in
-		// https://opencode.ai/docs/plugins/#compaction-hooks).
 		"experimental.session.compacting": async (input, output) => {
 			try {
 				const sessionID = (input as { sessionID?: string })?.sessionID;
@@ -3188,9 +1106,11 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					const s = String(t.status ?? "");
 					return s === "pending" || s === "in_progress";
 				});
-				const branch = currentGitBranch(workspaceRoot) ?? "unknown";
-				const isProtected = onProtectedBranch(workspaceRoot);
-				const lastV = sessionID ? sessionVerifyResults.get(sessionID) ?? lastVerify : lastVerify;
+				const branch = currentGitBranch(effectiveRoot) ?? "unknown";
+				const isProtected = onProtectedBranch(effectiveRoot);
+				const lastV = sessionID
+					? (sessionVerifyResults.get(sessionID) ?? lastVerify)
+					: lastVerify;
 				const lastR = getLastReviewResult();
 				const mutationCountVal = getMutationCount(sessionID);
 
@@ -3208,12 +1128,11 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 							: "";
 					contextBlocks.push(
 						`## Active Tasks${attribution}\n` +
-						lines.join("\n") +
-						"\nComplete tasks efficiently — mark finished items as completed and address remaining ones.",
+							lines.join("\n") +
+							"\nComplete tasks efficiently - mark finished items as completed and address remaining ones.",
 					);
 				}
 
-				// Inject operational guard state to keep the model grounded after compaction
 				const stateLines: string[] = [
 					`## Operational Guard State`,
 					`- Git Branch: ${branch}${isProtected ? " (PROTECTED BRANCH - edits/commits require feature branch)" : " (feature branch - edits allowed)"}`,
@@ -3237,12 +1156,6 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 			} catch {}
 		},
 
-		// Shell env scrub: sensitive credentials must not leak into agent
-		// shells by default. The hook only documents overwrite, so the
-		// sensitive entries are emptied; the agent cannot carry live
-		// credentials unless the user explicitly allows it elsewhere.
-		// When a scrubbed variable is present, we log a warning so the agent
-		// knows auth failures may be due to scrubbing, not their code.
 		"shell.env": async (input, output) => {
 			try {
 				const env = (output as { env?: Record<string, string> }).env;
@@ -3262,7 +1175,7 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					}
 					if (scrubbed.length > 0) {
 						try {
-							await (sdkClient as any)?.app?.log?.({
+							await (getSdkClient() as any)?.app?.log?.({
 								body: {
 									service: "workflow-guard",
 									level: "warn",
@@ -3275,8 +1188,55 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 			} catch {}
 		},
 
-		// Command & permission event audit trail: journal user commands,
-		// permission requests, and session creations.
+		"permission.ask": async (input, output) => {
+			audit({
+				ts: new Date().toISOString(),
+				sessionID: input.sessionID,
+				tool: "permission.ask",
+				decision: output.status === "deny" ? "block" : "allow",
+				input: {
+					permissionID: input.id,
+					type: input.type,
+					pattern: input.pattern,
+					status: output.status,
+				},
+			});
+		},
+
+		// Policy 24 (observability): claims-vs-evidence. When the assistant's final
+		// text asserts completion or passing verification, compare the claim against
+		// recorded verification evidence. A mismatch is journaled (not blocked) so
+		// confident wrap-ups cannot silently contradict failing or stale state.
+		"experimental.text.complete": async (input, output) => {
+			try {
+				const sessionID = input.sessionID;
+				const text = typeof output.text === "string" ? output.text : "";
+				const check = checkCompletionClaims(text, { sessionID });
+				if (check.claimsCompletion && check.evidenceState && check.evidenceState !== "fresh-pass") {
+					logBlock(`[workflow-guard] completion claim mismatch: ${check.reason}`);
+					audit({
+						ts: new Date().toISOString(),
+						sessionID,
+						tool: "experimental.text.complete",
+						decision: "allow",
+						reason: `Completion claim '${check.claim}' has ${check.evidenceState} verification evidence`,
+						input: { claim: check.claim, evidenceState: check.evidenceState },
+					});
+				}
+			} catch {}
+		},
+
+		// Keep tool descriptions honest: todowrite's description reflects the
+		// finalization gates so the model is not surprised by verification blocks.
+		"tool.definition": async (input, output) => {
+			if (input.toolID !== "todowrite") return;
+			const description = typeof output.description === "string" ? output.description : "";
+			if (description.includes("verification evidence")) return;
+			output.description =
+				description +
+				"\n\nNote: marking every task completed triggers the workflow guard's finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply.";
+		},
+
 		event: async ({
 			event,
 		}: { event: { type?: string; properties?: unknown } }) => {
@@ -3290,7 +1250,13 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					ts: new Date().toISOString(),
 					sessionID: (event.properties as { sessionID?: string })?.sessionID,
 					tool: event.type ?? "event",
-					decision: "allow",
+					decision:
+						event.type === "permission.replied" &&
+						/reject|deny/i.test(
+							String((event.properties as { response?: unknown })?.response ?? ""),
+						)
+							? "block"
+							: "allow",
 					input: summarizeInput(event.properties),
 				});
 			}