opencode-workflow-guard 1.3.8 → 1.4.1

package/ACKNOWLEDGEMENTS.md

@@ -19,5 +19,8 @@
 * **[`changesets`](https://github.com/changesets/changesets)** by the [Changesets Team](https://github.com/changesets/changesets)  
   * For the fragment-based changelog and versioning model that prevents merge conflicts across parallel feature PRs.
 
+* **[`oh-my-pi`](https://github.com/can1357/oh-my-pi)** by [@can1357](https://github.com/can1357), **`omp-guardrails`** by [@breathi3552](https://github.com/breathi3552), **`agentsflow`** by [@xzhang17](https://github.com/xzhang17), **`tools`** by [@marcelsud](https://github.com/marcelsud), and the **Claude Code** security hook community  
+  * Inspired the hardened shell wrapper tokenization/normalization in **`unwrapShellWords`**, multi-ecosystem verification detection in **Policy 10**, structured severity ranking (P0-P3 blocker gate) for the secondary review rubric in **Policy 19 / `guard_review_rubric`**, disk wipe, reverse shell & system permission signatures in **Policy 4**, lockfile synchronization checks in **Policy 3**, and subagent read-only role confinement & mutation budgets in **Policy 1**.
+
 * **[OpenCode Team at Anomaly](https://github.com/anomalyco/opencode)**  
   * For building the OpenCode terminal AI coding agent and its extensible plugin architecture (`@opencode-ai/plugin`).

package/README.md

@@ -25,6 +25,8 @@ Add to your project's `opencode.json` or global `~/.config/opencode/opencode.jso
 
 *Requires OpenCode >= 1.18.* See [docs/installation.md](docs/installation.md) for full setup options and TUI companion badge configuration.
 
+For the optional TUI badge, configure `"opencode-workflow-guard"` in `tui.json` as well. Do not use `opencode-workflow-guard/ui`; npm parses that unscoped slash form as GitHub shorthand rather than a package export, which can trigger Git credential prompts. The package exposes OpenCode's native `./server` and `./tui` entrypoints so the package root is sufficient in both configs.
+
 ### 2. Verification
 
 ```bash
@@ -41,7 +43,7 @@ The plugin enforces **24 deterministic policy rules** across four main pillars:
 
 * **Branch & History Protection:** Enforces feature-branch workflows (blocks edits/commits on `main`/`master`), hard-blocks direct or forced pushes to protected branches, enforces mergeability pre-flight checks, and requires PR changelogs / changesets.
 * **Task & Verification Discipline:** Gates file mutations on active `todowrite` tasks with subagent inheritance, blocks silent task deletion, enforces fresh test verification evidence before task completion, and journals completion claims vs. verification mismatches.
-* **Secrets & Workspace Confinement:** Confines all edits, shell redirects, and git operations within the workspace root (symlink & `../` escape safe), scrubs sensitive environment variables in agent subshells, and redacts `.env` reads with safe schema masks.
+* **Secrets & Workspace Confinement:** Confines edit tools and recognized shell/git mutations within the workspace root (including symlink and `../` escape checks), scrubs sensitive environment variables in agent subshells, and redacts `.env` reads with safe schema masks. Arbitrary executables are not OS-sandboxed; use containers or filesystem isolation when hard confinement is required.
 * **Destructive CLI & Environment Safety:** Intercepts destructive cloud/database/infrastructure commands, stops script laundering and interpreter evasion, blocks TTY hangs (`vim`, `nano`, `sudo`), and guards against dangerous package manager flags.
 
 For complete policy specifications and override rules, see [docs/policies.md](docs/policies.md).

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.3.8",
+  "version": "1.4.1",
   "description": "OpenCode plugin enforcing workflow discipline through deterministic tool.execute.before hooks",
   "license": "MIT",
   "type": "module",
   "main": "src/workflow-guard.ts",
   "exports": {
     ".": "./src/workflow-guard.ts",
-    "./ui": "./src/workflow-guard-ui.ts"
+    "./server": "./src/workflow-guard.ts",
+    "./tui": "./src/workflow-guard-ui.ts"
   },
   "publishConfig": {
     "access": "public"

package/src/lib/review.ts

@@ -34,12 +34,18 @@ export function buildReviewRubric(diffText: string, taskPrompt?: string): string
 		"### 5. Platform & Architecture Fit (GitHub & Azure DevOps)",
 		"- Does the change fit established repository patterns and CI/CD pipelines?",
 		"",
+		"### Finding Severity & Priority Tiers (inspired by OMP Advisor):",
+		"- **P0**: Blocker / security vulnerability / data loss risk / release-blocking regression (must block approval).",
+		"- **P1**: Major defect / missing core requirement / broken error handling (must block approval).",
+		"- **P2**: Minor bug / edge case / hygiene issue / missing unit test.",
+		"- **P3**: Suggestion / nitpick / optimization idea.",
+		"",
 		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.",
+		"Provide your verdict: `[APPROVE]` or `[REQUEST_CHANGES]` with concise, actionable findings ranked by priority (P0-P3).",
 	].join("\n");
 }

package/src/lib/state.ts

@@ -2,7 +2,7 @@ import { realpathSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { persistVerifyCache } from "./audit.ts";
-import { snipVerifyOutput, getCurrentGitCommitHash, getGitStatusSummary } from "./verify.ts";
+import { snipVerifyOutput, getCurrentGitCommitHash, getGitStatusSummary, getGitWorktreeFingerprint } from "./verify.ts";
 import type {
 	TodoSdkClient,
 	ProjectConfig,
@@ -149,13 +149,17 @@ export function recordReviewResult(
 	targetSessionID?: string,
 	workspace?: string,
 ): void {
+	const root = resolve(workspace ?? getWorkspaceRoot());
 	lastReview = {
 		reviewer,
 		summary: summary.slice(-4000),
 		passed,
 		timestamp: Date.now(),
 		targetSessionID,
-		workspace,
+		workspace: root,
+		commitHash: getCurrentGitCommitHash(root),
+		gitStatus: getGitStatusSummary(root),
+		worktreeFingerprint: getGitWorktreeFingerprint(root),
 	};
 	if (targetSessionID) sessionReviews.set(targetSessionID, lastReview);
 }
@@ -275,3 +279,15 @@ export function isDocumentationRequired(root: string): boolean {
 	const cfg = getProjectConfig(root);
 	return cfg.requireDocumentation === true;
 }
+
+export function getSubagentMutationBudget(root: string): number {
+	if (process.env.WORKFLOW_GUARD_MAX_SUBAGENT_MUTATIONS) {
+		const parsed = parseInt(process.env.WORKFLOW_GUARD_MAX_SUBAGENT_MUTATIONS, 10);
+		if (!Number.isNaN(parsed) && parsed > 0) return parsed;
+	}
+	const cfg = getProjectConfig(root);
+	if (typeof cfg.maxSubagentMutations === "number" && cfg.maxSubagentMutations > 0) {
+		return cfg.maxSubagentMutations;
+	}
+	return 50;
+}

package/src/lib/types.ts

@@ -21,6 +21,7 @@ export interface ProjectConfig {
 	verifyCommand?: string;
 	requireReview?: boolean;
 	requireDocumentation?: boolean;
+	maxSubagentMutations?: number;
 }
 
 export interface VerifyResult {
@@ -41,6 +42,9 @@ export interface ReviewResult {
 	timestamp: number;
 	targetSessionID?: string;
 	workspace?: string;
+	commitHash?: string;
+	gitStatus?: string;
+	worktreeFingerprint?: string;
 }
 
 export interface AuditEntry {

package/src/lib/utils.ts

@@ -29,6 +29,20 @@ export function normalize(cmd: string): string {
 	return cmd.replace(/\s+/g, " ");
 }
 
+export function decodeShellEscapes(text: string): string {
+	return text
+		// ANSI-C quoting wrapper: $'...' -> ...
+		.replace(/\$'([^']*)'/g, "$1")
+		// Hex escapes: \xHH
+		.replace(/\\x([0-9a-fA-F]{2})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)))
+		// Unicode escapes: \uHHHH
+		.replace(/\\u([0-9a-fA-F]{4})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)))
+		// Octal escapes: \0OO or \OOO (e.g. \162 -> 'r')
+		.replace(/\\([0-3][0-7]{2})/g, (_, oct) => String.fromCharCode(parseInt(oct, 8)))
+		// Single character escapes: \c -> c (e.g. \r\m -> rm)
+		.replace(/\\(.)/g, "$1");
+}
+
 export function shellWords(command: string): string[] {
 	return (command.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? []).map((word) =>
 		word.replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/, "$1$2"),
@@ -69,14 +83,69 @@ export function splitShellSegments(command: string): string[] {
 }
 
 export function unwrapShellWords(command: string): string[] {
-	const words = shellWords(command.trim());
+	let cleanCmd = decodeShellEscapes(command.trim());
+	// Strip outer grouping parentheses/braces if present e.g. ( git commit ) or { git commit; }
+	while (
+		(cleanCmd.startsWith("(") && cleanCmd.endsWith(")")) ||
+		(cleanCmd.startsWith("{") && cleanCmd.endsWith("}"))
+	) {
+		cleanCmd = cleanCmd.slice(1, -1).trim();
+		if (cleanCmd.endsWith(";")) cleanCmd = cleanCmd.slice(0, -1).trim();
+	}
+
+	const words = shellWords(cleanCmd);
 	let i = 0;
 	while (i < words.length) {
-		if (words[i] === "command") {
+		const rawWord = words[i]!;
+		const word = rawWord.replace(/^[\({]+/, "").replace(/[\)};]+$/, "");
+		if (!word) {
+			i++;
+			continue;
+		}
+
+		if (word === "command" || word === "exec" || word === "eval" || word === "nohup") {
+			i++;
+			continue;
+		}
+		if (word === "nice") {
+			i++;
+			if (i < words.length && (words[i] === "-n" || words[i]?.startsWith("-n"))) {
+				if (words[i] === "-n") i += 2;
+				else i++;
+			}
+			continue;
+		}
+		if (word === "timeout") {
+			i++;
+			while (i < words.length && words[i]!.startsWith("-")) {
+				const opt = words[i++]!;
+				if ((opt === "-k" || opt === "-s" || opt === "--signal" || opt === "--kill-after") && i < words.length) {
+					i++;
+				}
+			}
+			if (i < words.length && /^\d+[smhd]?$/.test(words[i]!)) {
+				i++;
+			}
+			continue;
+		}
+		if (word === "stdbuf") {
 			i++;
+			while (i < words.length && words[i]!.startsWith("-")) {
+				const opt = words[i++]!;
+				if ((opt === "-i" || opt === "-o" || opt === "-e") && i < words.length) {
+					i++;
+				}
+			}
+			continue;
+		}
+		if (word === "time") {
+			i++;
+			while (i < words.length && words[i]!.startsWith("-")) {
+				i++;
+			}
 			continue;
 		}
-		if (words[i] === "sudo") {
+		if (word === "sudo" || word === "doas") {
 			i++;
 			const valueOptions = new Set([
 				"-u",
@@ -100,7 +169,7 @@ export function unwrapShellWords(command: string): string[] {
 			}
 			continue;
 		}
-		if (words[i] === "env") {
+		if (word === "env") {
 			i++;
 			const valueOptions = new Set([
 				"-u",
@@ -111,24 +180,27 @@ export function unwrapShellWords(command: string): string[] {
 				"--split-string",
 			]);
 			while (i < words.length) {
-				const word = words[i]!;
-				if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) {
+				const w = words[i]!;
+				if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(w)) {
 					i++;
 					continue;
 				}
-				if (!word.startsWith("-")) break;
+				if (!w.startsWith("-")) break;
 				i++;
-				if (valueOptions.has(word) && i < words.length) i++;
+				if (valueOptions.has(w) && i < words.length) i++;
 			}
 			continue;
 		}
-		if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]!)) {
+		if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) {
 			i++;
 			continue;
 		}
 		break;
 	}
-	return words.slice(i);
+	return words
+		.slice(i)
+		.map((w) => w.replace(/^[\({]+/, "").replace(/[\)};]+$/, ""))
+		.filter(Boolean);
 }
 
 export function unwrapShellCommand(command: string): string {

package/src/lib/verify.ts

@@ -1,5 +1,6 @@
 import { spawn, spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { getCleanEnv, normalize } from "./utils.ts";
 import { getProjectConfig } from "./state.ts";
@@ -18,11 +19,35 @@ export function detectVerifyCommand(root: string): string | undefined {
 		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";
+		const pkgPath = join(root, "package.json");
+		if (existsSync(pkgPath)) {
+			const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as {
+				scripts?: Record<string, string>;
+			};
+			if (pkg.scripts?.test) return "npm test";
+			if (pkg.scripts?.typecheck) return "npm run typecheck";
+			if (pkg.scripts?.check) return "npm run check";
+			if (pkg.scripts?.build) return "npm run build";
+		}
 	} catch {}
+
+	if (existsSync(join(root, "Cargo.toml"))) {
+		return "cargo test";
+	}
+	if (existsSync(join(root, "go.mod"))) {
+		return "go test ./...";
+	}
+	if (
+		existsSync(join(root, "pytest.ini")) ||
+		existsSync(join(root, "pyproject.toml")) ||
+		existsSync(join(root, "setup.py"))
+	) {
+		return "pytest";
+	}
+	if (existsSync(join(root, "deno.json")) || existsSync(join(root, "deno.jsonc"))) {
+		return "deno test";
+	}
+
 	return undefined;
 }
 
@@ -92,6 +117,43 @@ export function getGitStatusSummary(root: string): string | undefined {
 	return undefined;
 }
 
+export function getGitWorktreeFingerprint(root: string): string | undefined {
+	try {
+		// Index listing captures the exact staged/tracked content (blob hashes);
+		// a worktree-vs-index diff captures unstaged edits; untracked file
+		// contents cover files git does not yet track. Together these bind the
+		// fingerprint to file contents regardless of whether HEAD exists, so
+		// freshly initialized (commitless) repositories are covered too.
+		const staged = spawnSync("git", ["ls-files", "--stage", "-z"], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		const unstaged = spawnSync("git", ["diff", "--no-ext-diff", "--"], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		const untracked = spawnSync("git", ["ls-files", "--others", "--exclude-standard", "-z"], {
+			cwd: root,
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (staged.status !== 0 || unstaged.status !== 0 || untracked.status !== 0) return undefined;
+		const hash = createHash("sha256").update(staged.stdout).update(unstaged.stdout);
+		for (const file of untracked.stdout.split("\0").filter(Boolean).sort()) {
+			hash.update("\0" + file + "\0");
+			try {
+				hash.update(readFileSync(join(root, file)));
+			} catch {
+				return undefined;
+			}
+		}
+		return hash.digest("hex");
+	} catch {}
+	return undefined;
+}
+
 export async function runVerify(
 	command: string,
 	root: string,

package/src/policies/boundary.ts

@@ -127,23 +127,29 @@ export function teeTargetsIn(segment: string): string[] {
 	return targets;
 }
 
-export function shellMutationIn(segment: string): ShellMutation | undefined {
-	const redirectMatch = segment.match(
-		/(?:^|[\s>]|(?<=[^\s"']))([0-9]*&?>>?&?)\s*["']?([^\s>&|;"']+)/,
-	);
-	if (redirectMatch?.[1] && redirectMatch?.[2]) {
+function redirectMutationsIn(segment: string): ShellMutation[] {
+	const mutations: ShellMutation[] = [];
+	const redirectRe = /(?:^|[\s>]|(?<=[^\s"']))([0-9]*&?>>?&?)\s*["']?([^\s>&|;"']+)/g;
+	for (const redirectMatch of segment.matchAll(redirectRe)) {
+		if (!redirectMatch[1] || !redirectMatch[2]) continue;
 		const op = redirectMatch[1];
 		const target = redirectMatch[2];
 		// Filter fd duplication (e.g. 2>&1, >&2) where target is purely an fd number
 		const isFdDup = op.endsWith("&") && /^\d+$/.test(target);
 		if (!isFdDup && !/^\/dev\/(?:null|stdout|stderr|tty|fd\/\d+)$/.test(target)) {
-			return {
+			mutations.push({
 				kind: "redirect",
 				target,
 				what: `file redirect to '${target}'`,
-			};
+			});
 		}
 	}
+	return mutations;
+}
+
+export function shellMutationIn(segment: string): ShellMutation | undefined {
+	const redirectMutation = redirectMutationsIn(segment)[0];
+	if (redirectMutation) return redirectMutation;
 	const teeTargets = teeTargetsIn(segment);
 	if (teeTargets.length > 0) {
 		return {
@@ -192,12 +198,29 @@ export function shellMutationIn(segment: string): ShellMutation | undefined {
 	return undefined;
 }
 
+const SIMPLE_MUTATION_COMMANDS = new Set(["touch", "mkdir", "rm", "unlink", "rmdir", "truncate"]);
+const TRANSFER_COMMANDS = new Set(["cp", "mv", "ln"]);
+
 export 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)) {
+	if (!command) {
 		return [];
 	}
+	if (command === "dd") {
+		return words
+			.slice(1)
+			.filter((word) => word.startsWith("of=") && word.length > 3)
+			.map((word) => {
+				const target = word.slice(3);
+				return {
+					kind: "command" as const,
+					target,
+					what: `dd output to '${target}'`,
+				};
+			});
+	}
+	if (!SIMPLE_MUTATION_COMMANDS.has(command)) return [];
 	return words
 		.slice(1)
 		.filter((word) => !word.startsWith("-"))
@@ -212,7 +235,7 @@ export 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;
+	if (!words[0] || !TRANSFER_COMMANDS.has(words[0])) return undefined;
 	const operands: string[] = [];
 	let targetDirectory: string | undefined;
 	for (let i = 1; i < words.length; i++) {
@@ -244,6 +267,24 @@ export function secretSourceInFilesystemCommand(segment: string): string | undef
 	return undefined;
 }
 
+export function detectShellMutation(command: string): ShellMutation | undefined {
+	for (const segment of command.split(/[\n|;&]+/)) {
+		const simpleMutations = simpleFilesystemMutations(segment);
+		if (simpleMutations.length > 0) return simpleMutations[0];
+		const teeTargets = teeTargetsIn(segment);
+		if (teeTargets.length > 0) {
+			return {
+				kind: "command",
+				target: teeTargets[0],
+				what: `tee to '${teeTargets[0]}'`,
+			};
+		}
+		const fallback = shellMutationIn(segment.trim());
+		if (fallback) return fallback;
+	}
+	return undefined;
+}
+
 export async function guardShellMutation(
 	command: string,
 	sessionID: string | undefined,
@@ -277,14 +318,12 @@ export async function guardShellMutation(
 			target,
 			what: `tee to '${target}'`,
 		}));
-		const fallbackMutation = shellMutationIn(segment.trim());
-		const mutations = simpleMutations.length > 0
-			? simpleMutations
-			: teeMutations.length > 0
-				? teeMutations
-				: fallbackMutation
-					? [fallbackMutation]
-					: [];
+		const redirectMutations = redirectMutationsIn(segment.trim());
+		const mutations = [...simpleMutations, ...teeMutations, ...redirectMutations];
+		if (mutations.length === 0) {
+			const fallbackMutation = shellMutationIn(segment.trim());
+			if (fallbackMutation) mutations.push(fallbackMutation);
+		}
 		for (const mutation of mutations) {
 			hasMutation = true;
 			const secret = secretIn(segment);

package/src/policies/changelog.ts

@@ -78,3 +78,62 @@ export function prBodyIncludesChangelog(command: string): boolean {
 	}
 	return false;
 }
+
+export function checkLockfileSync(root: string): { isOutOfSync: boolean; manifest?: string; lockfile?: string; reason?: string } {
+	try {
+		let modifiedFiles: string[] = [];
+		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: 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 && diff.stdout.trim()) {
+				modifiedFiles = diff.stdout.split("\n").map((f) => f.trim()).filter(Boolean);
+				break;
+			}
+		}
+		const headDiff = spawnSync("git", ["diff", "--name-only", "HEAD"], { cwd: root, encoding: "utf8", timeout: 10_000 });
+		if (headDiff.status === 0 && headDiff.stdout.trim()) {
+			const uncommitted = headDiff.stdout.split("\n").map((f) => f.trim()).filter(Boolean);
+			modifiedFiles = Array.from(new Set([...modifiedFiles, ...uncommitted]));
+		}
+		const untracked = spawnSync("git", ["status", "--porcelain"], { cwd: root, encoding: "utf8", timeout: 10_000 });
+		if (untracked.status === 0 && untracked.stdout.trim()) {
+			const files = untracked.stdout.split("\n").map((l) => l.slice(3).trim()).filter(Boolean);
+			modifiedFiles = Array.from(new Set([...modifiedFiles, ...files]));
+		}
+
+		const manifestToLockfiles: Array<{ manifest: RegExp; lockfiles: RegExp; name: string }> = [
+			{
+				manifest: /(?:^|\/)package\.json$/,
+				lockfiles: /(?:^|\/)(?:package-lock\.json|bun\.lock|bun\.lockb|pnpm-lock\.yaml|yarn\.lock)$/,
+				name: "package.json",
+			},
+			{
+				manifest: /(?:^|\/)Cargo\.toml$/,
+				lockfiles: /(?:^|\/)Cargo\.lock$/,
+				name: "Cargo.toml",
+			},
+			{
+				manifest: /(?:^|\/)go\.mod$/,
+				lockfiles: /(?:^|\/)go\.sum$/,
+				name: "go.mod",
+			},
+		];
+
+		for (const item of manifestToLockfiles) {
+			const hasManifest = modifiedFiles.some((f) => item.manifest.test(f));
+			if (hasManifest) {
+				const hasLockfile = modifiedFiles.some((f) => item.lockfiles.test(f));
+				if (!hasLockfile) {
+					return {
+						isOutOfSync: true,
+						manifest: item.name,
+						reason: `Package manifest '${item.name}' was modified without updating its corresponding lockfile. Run the package manager install/lock command before opening a PR.`,
+					};
+				}
+			}
+		}
+	} catch {}
+	return { isOutOfSync: false };
+}

package/src/policies/destructive.ts

@@ -48,6 +48,18 @@ export const LIVE_MUTATION_PATTERNS: LivePattern[] = [
 	{ re: /\b(?:curl|wget)\b[^;&]*\|\s*(?:bash|sh|zsh)\b/, what: ["remote ", "download piped directly to a shell"].join("") },
 	// Destructive git operations
 	{ re: /\bgit\s+push\b[^|;&]*(?:--force\b|--force-with-lease\b|\s-f\b)/, what: ["force ", "push"].join("") },
+	// Low-level disk / filesystem / partition destruction
+	{ re: /\b(?:mkfs(?:\.[a-z0-9]+)?|wipefs|parted|sfdisk|gdisk)\b/, what: ["disk/filesystem ", "format or partition manipulation"].join("") },
+	{ re: /\bdd\s+[^|;&]*\bof=\/dev\/(?:sd[a-z]|nvme\d|vd[a-z]|hd[a-z]|disk\d|rdisk\d|loop\d)/, what: ["raw disk/block device ", "overwrite via dd"].join("") },
+	{ re: /\bshred\s+[^|;&]*\/dev\/(?:sd[a-z]|nvme\d|vd[a-z]|hd[a-z]|disk\d|rdisk\d|loop\d)/, what: ["disk device ", "shredding"].join("") },
+	// Recursive permission/ownership clobbering on root or home
+	{ re: /\bchmod\s+-[a-zA-Z]*[rR][a-zA-Z]*\s+\S+\s+(?:\/|~|\$HOME)(?:\s|$)/, what: ["recursive ", "permission clobbering of root/home path"].join("") },
+	{ re: /\bchown\s+-[a-zA-Z]*[rR][a-zA-Z]*\s+\S+\s+(?:\/|~|\$HOME)(?:\s|$)/, what: ["recursive ", "ownership clobbering of root/home path"].join("") },
+	// Network reverse shell / raw socket execution / data exfiltration channels
+	{ re: /\/dev\/(?:tcp|udp)\/[a-zA-Z0-9_.-]+\/\d+/, what: ["raw network socket / ", "reverse shell channel (/dev/tcp or /dev/udp)"].join("") },
+	{ re: /\b(?:nc|ncat|netcat)\b[^|;&]*-[a-zA-Z]*e[a-zA-Z]*\s+(?:\/bin\/(?:ba)?sh|sh|bash|cmd\.exe|powershell)/i, what: ["netcat reverse ", "shell execution (-e)"].join("") },
+	{ re: /\bsocat\b[^|;&]*\bexec:\s*['"]?(?:\/bin\/(?:ba)?sh|sh|bash)/i, what: ["socat interactive ", "reverse shell spawn"].join("") },
+	{ re: /\bmknod\s+\S+\s+p\b/, what: ["named FIFO pipe ", "creation (reverse shell backpipe)"].join("") },
 ];
 
 export function liveMutationIn(command: string): string | undefined {

package/src/policies/shell-safety.ts

@@ -38,7 +38,9 @@ export function checkPackageHygiene(command: string): { isViolating: boolean; na
 
 // AI agents running in non-interactive terminal subshells hang indefinitely when an
 // interactive prompt (vim, nano, less, top, sudo, npm init without -y, apt without -y,
-// git rebase -i) waits for TTY input.
+// git rebase -i) waits for TTY input. Process monitors are handled separately in
+// checkProcessMonitorCommand because `top` can run in a safe batch mode, while the
+// other monitors cannot.
 
 const INTERACTIVE_COMMAND_PATTERNS: Array<{ regex: RegExp; name: string; advice: string }> = [
 	{
@@ -51,11 +53,6 @@ const INTERACTIVE_COMMAND_PATTERNS: Array<{ regex: RegExp; name: string; advice:
 		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",
@@ -88,7 +85,29 @@ const INTERACTIVE_COMMAND_PATTERNS: Array<{ regex: RegExp; name: string; advice:
 	},
 ];
 
+const MONITOR_ADVICE = "Use ps aux, uptime, or batch flags (e.g. top -b -n 1) instead of interactive monitors.";
+// Process monitoring tokens are matched on whitespace/segment boundaries so that
+// an unrelated word such as `desktop`, a hyphenated filename like `top-level-dir`,
+// or a quoted argument like `echo "top"` is not mistaken for the `top` command.
+const ALWAYS_INTERACTIVE_MONITOR_RE = /(?:^|[;&|\s])(?:htop|btop|atop|glances)(?:$|[;&|\s])/i;
+const TOP_COMMAND_RE = /(?:^|[;&|\s])top(?:$|[;&|\s])/i;
+const TOP_BATCH_FLAG_RE = /(?:^|\s)(?:--batch|-[A-Za-z]*b[A-Za-z]*)(?:\s|$)/i;
+
+function checkProcessMonitorCommand(command: string): { isInteractive: boolean; name?: string; advice?: string } {
+	for (const segment of command.split(/[;&|\n]+/)) {
+		if (ALWAYS_INTERACTIVE_MONITOR_RE.test(segment)) {
+			return { isInteractive: true, name: "interactive process monitor", advice: MONITOR_ADVICE };
+		}
+		if (TOP_COMMAND_RE.test(segment) && !TOP_BATCH_FLAG_RE.test(segment)) {
+			return { isInteractive: true, name: "interactive process monitor", advice: MONITOR_ADVICE };
+		}
+	}
+	return { isInteractive: false };
+}
+
 export function checkInteractiveTtyCommand(command: string): { isInteractive: boolean; name?: string; advice?: string } {
+	const monitor = checkProcessMonitorCommand(command);
+	if (monitor.isInteractive) return monitor;
 	for (const { regex, name, advice } of INTERACTIVE_COMMAND_PATTERNS) {
 		if (regex.test(command)) {
 			return { isInteractive: true, name, advice };

package/src/policies/tamper.ts

@@ -1,6 +1,7 @@
 import { realpathSync } from "node:fs";
 import { basename, relative, resolve } from "node:path";
 import { getWorkspaceRoot } from "../lib/state.ts";
+import { decodeShellEscapes } from "../lib/utils.ts";
 
 export const PROTECTED_PATH_REASON =
 	"Blocked: modifying Open" +
@@ -23,10 +24,9 @@ export const SETTINGS_TAMPER_PATTERNS: RegExp[] = [
 ];
 
 export function normalizeShellEvasion(text: string): string {
-	return text
+	return decodeShellEscapes(text)
 		.replace(/'([^']*)'/g, "$1")
-		.replace(/"([^"]*)"/g, "$1")
-		.replace(/\\(.)/g, "$1");
+		.replace(/"([^"]*)"/g, "$1");
 }
 
 export function normalizeGlobPathEvasion(text: string): string {

package/src/workflow-guard.ts

@@ -47,6 +47,7 @@ import {
 	stripJsonComments,
 	isReviewRequired,
 	isDocumentationRequired,
+	getSubagentMutationBudget,
 	recordReviewResult,
 	getLastReviewResult,
 	resetReviewState,
@@ -68,6 +69,7 @@ export {
 	stripJsonComments,
 	isReviewRequired,
 	isDocumentationRequired,
+	getSubagentMutationBudget,
 	recordReviewResult,
 	getLastReviewResult,
 	resetReviewState,
@@ -108,6 +110,7 @@ import {
 	snipVerifyOutput,
 	getCurrentGitCommitHash,
 	getGitStatusSummary,
+	getGitWorktreeFingerprint,
 } from "./lib/verify.ts";
 
 export {
@@ -116,6 +119,7 @@ export {
 	snipVerifyOutput,
 	getCurrentGitCommitHash,
 	getGitStatusSummary,
+	getGitWorktreeFingerprint,
 };
 
 // ── Secondary review rubric ──────────────────────────────────────────────────
@@ -179,8 +183,11 @@ import {
 	hasPrCreateInvocation,
 	branchHasChangelogChange,
 	prBodyIncludesChangelog,
+	checkLockfileSync,
 } from "./policies/changelog.ts";
 
+export { checkLockfileSync };
+
 import { liveMutationIn, extractEditContent } from "./policies/destructive.ts";
 
 import { mcpMutationTool } from "./policies/mcp.ts";
@@ -197,6 +204,7 @@ import {
 	isPathOutsideWorkspace,
 	extractPatchPaths,
 	guardShellMutation,
+	detectShellMutation,
 } from "./policies/boundary.ts";
 
 import { isSecretPath, secretIn, secretFileReadIn, isEnvFilePath, generateMaskedEnvSchema } from "./policies/secrets.ts";
@@ -240,13 +248,38 @@ function logBlock(message: string): void {
 	} catch {}
 }
 
+const READ_ONLY_ROLES = new Set([
+	"reviewer",
+	"planner",
+	"advisor",
+	"critic",
+	"explorer",
+	"scout",
+	"evaluator",
+]);
+
+export function isReadOnlyRole(agent?: string): boolean {
+	if (!agent) return false;
+	const lower = agent.toLowerCase().trim();
+	return READ_ONLY_ROLES.has(lower) || Array.from(READ_ONLY_ROLES).some((r) => lower.includes(r));
+}
+
 async function guardToolCallImpl(
 	toolName: string,
 	input: unknown,
-	context?: { sessionID?: string },
+	context?: { sessionID?: string; worktree?: string; directory?: string; agent?: string },
 ): Promise<string | undefined> {
 	const currentRoot = getWorkspaceRoot();
 
+	// ── Role confinement: subagents in read-only roles cannot mutate files ──
+	if (context?.agent && isReadOnlyRole(context.agent)) {
+		if (EDIT_TOOL_NAMES.has(toolName) || toolName.startsWith("guard_worktree_")) {
+			const reason = `Blocked: subagent with read-only role '${context.agent}' cannot perform file mutations or lifecycle changes.`;
+			logBlock(`[workflow-guard] ${reason}`);
+			return reason;
+		}
+	}
+
 	// ── Policy 17: secret file read block via read tool ──
 	if (toolName === "read" || toolName === "read_file") {
 		const record = asRecord(input);
@@ -499,6 +532,18 @@ async function guardToolCallImpl(
 				"starting new work."
 			);
 		}
+		if (context?.sessionID) {
+			const parentID = await fetchParentSessionID(context.sessionID);
+			if (parentID) {
+				const count = getMutationCount(context.sessionID);
+				const budget = getSubagentMutationBudget(currentRoot);
+				if (count >= budget) {
+					const reason = `Blocked: subagent session '${context.sessionID}' has reached its mutation budget (${count}/${budget}). Hand work back to parent orchestrator.`;
+					logBlock(`[workflow-guard] ${reason}`);
+					return reason;
+				}
+			}
+		}
 		recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID));
 		return undefined;
 	}
@@ -765,8 +810,11 @@ async function guardToolCallImpl(
 					: getLastReviewResult();
 				const reviewMatchesContext =
 					review?.passed === true &&
-					(!review.workspace || review.workspace === currentRoot) &&
-					(!review.targetSessionID || review.targetSessionID === context?.sessionID);
+					review.workspace === resolve(currentRoot) &&
+					(!review.targetSessionID || review.targetSessionID === context?.sessionID) &&
+					review.commitHash === getCurrentGitCommitHash(currentRoot) &&
+					review.gitStatus === getGitStatusSummary(currentRoot) &&
+					review.worktreeFingerprint === getGitWorktreeFingerprint(currentRoot);
 				if (!reviewMatchesContext) {
 					logBlock(`[workflow-guard] blocked ${prTool}: review approval required`);
 					return (
@@ -802,6 +850,13 @@ async function guardToolCallImpl(
 					`'Changelog:' section in the PR description (${descFlag}).`
 				);
 			}
+
+			// Lockfile synchronization pre-flight gate
+			const lockCheck = checkLockfileSync(currentRoot);
+			if (lockCheck.isOutOfSync) {
+				logBlock(`[workflow-guard] blocked ${prTool}: ${lockCheck.reason}`);
+				return `Blocked: ${lockCheck.reason}`;
+			}
 		}
 
 		const hasGitMutation = gitInvocations.some((invocation) => {
@@ -811,6 +866,35 @@ async function guardToolCallImpl(
 				/\bgit\s+(?:switch|checkout)\b/.test(normalizedInvocation)
 			);
 		});
+
+		if (context?.agent && isReadOnlyRole(context.agent)) {
+			const mutation = detectShellMutation(command);
+			if (mutation) {
+				logBlock(`[workflow-guard] blocked shell mutation for read-only role ${context.agent}: ${mutation.what}`);
+				return `Blocked: subagent with read-only role '${context.agent}' cannot perform shell file mutations (${mutation.what}).`;
+			}
+			if (hasGitMutation) {
+				logBlock(`[workflow-guard] blocked git mutation for read-only role ${context.agent}`);
+				return `Blocked: subagent with read-only role '${context.agent}' cannot mutate git history or state.`;
+			}
+		}
+
+		const shellMut = detectShellMutation(command);
+		if (hasGitMutation || shellMut) {
+			if (context?.sessionID) {
+				const parentID = await fetchParentSessionID(context.sessionID);
+				if (parentID) {
+					const count = getMutationCount(context.sessionID);
+					const budget = getSubagentMutationBudget(currentRoot);
+					if (count >= budget) {
+						const reason = `Blocked: subagent session '${context.sessionID}' has reached its mutation budget (${count}/${budget}). Hand work back to parent orchestrator.`;
+						logBlock(`[workflow-guard] ${reason}`);
+						return reason;
+					}
+				}
+			}
+		}
+
 		if (hasGitMutation) {
 			recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID));
 		}
@@ -826,9 +910,13 @@ async function guardToolCallImpl(
 export async function guardToolCall(
 	toolName: string,
 	input: unknown,
-	context?: { sessionID?: string },
+	context?: { sessionID?: string; worktree?: string; directory?: string; agent?: string },
 ): Promise<string | undefined> {
-	const reason = await guardToolCallImpl(toolName, input, context);
+	const customRoot = context?.worktree || context?.directory;
+	const runImpl = () => guardToolCallImpl(toolName, input, context);
+	const reason = customRoot
+		? await runWithRuntimeState(customRoot, getSdkClient(), runImpl)
+		: await runImpl();
 	const allowLive = process.env.WORKFLOW_GUARD_ALLOW_LIVE === "1";
 	const isMutation = EDIT_TOOL_NAMES.has(toolName);
 	const record = asRecord(input);
@@ -998,6 +1086,14 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 							`evaluate each axis, and include findings per axis in the summary.`
 						);
 					}
+					if (args.passed) {
+						if (/(?:^|\s)(?:\[p[01]\]|p[01]\s*:\s*(?:blocker|defect|vulnerability|error|bug|issue)|p[01]\s+blocker)/i.test(args.summary)) {
+							return (
+								"[workflow-guard] Review rejected: cannot record approval when P0 or P1 blockers are flagged in findings. " +
+								"Resolve all P0/P1 issues before approving or record review with passed=false."
+							);
+						}
+					}
 					recordReviewResult(
 						args.reviewer,
 						args.summary,
@@ -1116,12 +1212,23 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 		},
 
 		"tool.execute.before": async (input, output) => {
-			return runWithRuntimeState(effectiveRoot, ctx.client, async () => {
+			const toolWorktree =
+				(input as { worktree?: string })?.worktree ||
+				(input as { directory?: string })?.directory ||
+				(output as { worktree?: string })?.worktree ||
+				(output as { directory?: string })?.directory ||
+				effectiveRoot;
+			const toolAgent =
+				(input as { agent?: string })?.agent ||
+				(output as { agent?: string })?.agent;
+			return runWithRuntimeState(toolWorktree, 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,
+					worktree: toolWorktree,
+					agent: toolAgent,
 				});
 				if (reason !== undefined) {
 					await emitBlockFeedback(reason);