opencode-workflow-guard 1.4.0 → 1.4.1

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.4.0",
+  "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/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);
 }

package/src/lib/types.ts

@@ -42,6 +42,9 @@ export interface ReviewResult {
 	timestamp: number;
 	targetSessionID?: string;
 	workspace?: string;
+	commitHash?: string;
+	gitStatus?: string;
+	worktreeFingerprint?: string;
 }
 
 export interface AuditEntry {

package/src/lib/verify.ts

@@ -1,4 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { getCleanEnv, normalize } from "./utils.ts";
@@ -116,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++) {
@@ -295,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/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/workflow-guard.ts

@@ -110,6 +110,7 @@ import {
 	snipVerifyOutput,
 	getCurrentGitCommitHash,
 	getGitStatusSummary,
+	getGitWorktreeFingerprint,
 } from "./lib/verify.ts";
 
 export {
@@ -118,6 +119,7 @@ export {
 	snipVerifyOutput,
 	getCurrentGitCommitHash,
 	getGitStatusSummary,
+	getGitWorktreeFingerprint,
 };
 
 // ── Secondary review rubric ──────────────────────────────────────────────────
@@ -808,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 (