opencode-workflow-guard 1.9.3 → 1.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.9.3",
+  "version": "1.10.1",
   "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",

package/src/lib/tool-outcomes.ts

@@ -27,6 +27,7 @@ export class ToolOutcomeTracker {
 	private readonly terminalCalls = new Map<string, Set<string>>();
 	private readonly fallbackCalls = new Map<string, Set<string>>();
 	private readonly failures = new Map<string, { signature: string; count: number }>();
+	private readonly consecutiveFailures = new Map<string, number>();
 
 	record(part: ToolOutcomePart): ToolOutcome | undefined {
 		if (part.type !== "tool" || typeof part.sessionID !== "string" || typeof part.callID !== "string" || typeof part.tool !== "string") return undefined;
@@ -51,6 +52,7 @@ export class ToolOutcomeTracker {
 		const durationMs = typeof start === "number" && Number.isFinite(start) && typeof end === "number" && Number.isFinite(end) ? Math.max(0, end - start) : undefined;
 		if (status === "completed") {
 			this.failures.delete(part.sessionID);
+			this.consecutiveFailures.delete(part.sessionID);
 			return { sessionID: part.sessionID, callID: part.callID, tool: part.tool, status, durationMs };
 		}
 
@@ -59,6 +61,10 @@ export class ToolOutcomeTracker {
 		const previous = this.failures.get(part.sessionID);
 		const count = previous?.signature === signature ? previous.count + 1 : 1;
 		this.failures.set(part.sessionID, { signature, count });
+
+		const consecutive = (this.consecutiveFailures.get(part.sessionID) ?? 0) + 1;
+		this.consecutiveFailures.set(part.sessionID, consecutive);
+
 		return { sessionID: part.sessionID, callID: part.callID, tool: part.tool, status, durationMs, repeatedFailureCount: count };
 	}
 
@@ -74,8 +80,15 @@ export class ToolOutcomeTracker {
 		return { sessionID, callID, tool, status: "completed", durationMs };
 	}
 
+	getFailureCount(sessionID: string): number {
+		const consecutive = this.consecutiveFailures.get(sessionID) ?? 0;
+		const equivalent = this.failures.get(sessionID)?.count ?? 0;
+		return Math.max(consecutive, equivalent);
+	}
+
 	clearSession(sessionID: string): void {
 		this.failures.delete(sessionID);
+		this.consecutiveFailures.delete(sessionID);
 		this.terminalCalls.delete(sessionID);
 		this.fallbackCalls.delete(sessionID);
 	}

package/src/policies/boundary.ts

@@ -158,13 +158,9 @@ export function shellMutationIn(segment: string): ShellMutation | undefined {
 			what: `tee to '${teeTargets[0]!}'`,
 		};
 	}
-	const sedWords = shellWords(unwrapShellCommand(segment));
-	if (sedWords[0] === "sed" && sedWords.slice(1).some((word) => /^-(?:[a-zA-Z]*i|i\S*)$/.test(word) || /^--in-place(?:=.*)?$/.test(word))) {
-		const operands = sedWords.slice(1).filter((word) => !word.startsWith("-"));
-		const target = operands.at(-1);
-		if (!target) return undefined;
-		return { kind: "command", target, what: `sed -i on '${target}'` };
-	}
+	const simple = simpleFilesystemMutations(segment);
+	if (simple.length > 0) return simple[0];
+
 	const transfer = filesystemTransferInfo(segment);
 	if (transfer?.destination) {
 		return {
@@ -173,34 +169,45 @@ export function shellMutationIn(segment: string): ShellMutation | undefined {
 			what: `copy/move/link to '${transfer.destination}'`,
 		};
 	}
-	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]}'`,
-		};
+	const words = shellWords(unwrapShellCommand(segment));
+	const command = words[0];
+	if (!command) return undefined;
+
+	if (command === "curl") {
+		for (let i = 1; i < words.length; i++) {
+			const w = words[i]!;
+			if ((w === "-o" || w === "--output") && i + 1 < words.length) {
+				return { kind: "command", target: words[i + 1]!, what: `curl output to '${words[i + 1]!}'` };
+			}
+			if (w.startsWith("--output=")) {
+				const target = w.slice("--output=".length);
+				return { kind: "command", target, what: `curl output to '${target}'` };
+			}
+		}
 	}
-	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]}'`,
-		};
+	if (command === "wget") {
+		for (let i = 1; i < words.length; i++) {
+			const w = words[i]!;
+			if ((w === "-O" || w === "--output-document") && i + 1 < words.length) {
+				return { kind: "command", target: words[i + 1]!, what: `wget output to '${words[i + 1]!}'` };
+			}
+			if (w.startsWith("--output-document=")) {
+				const target = w.slice("--output-document=".length);
+				return { kind: "command", target, what: `wget output to '${target}'` };
+			}
+		}
 	}
-	if (/\bgit\s+(?:apply|am)\b/.test(segment)) {
-		return { kind: "command", what: "git apply/am (patch via shell)" };
+	if (command === "git") {
+		const sub = words.slice(1).find((w) => !w.startsWith("-"));
+		if (sub === "apply" || sub === "am") {
+			return { kind: "command", what: "git apply/am (patch via shell)" };
+		}
 	}
 	return undefined;
 }
 
 const SIMPLE_MUTATION_COMMANDS = new Set(["touch", "mkdir", "rm", "unlink", "rmdir", "truncate", "chmod", "chown", "chgrp"]);
-const TRANSFER_COMMANDS = new Set(["cp", "mv", "ln"]);
+const TRANSFER_COMMANDS = new Set(["cp", "mv", "ln", "rsync", "install", "cpio", "scp"]);
 
 export function simpleFilesystemMutations(segment: string): ShellMutation[] {
 	const words = shellWords(unwrapShellCommand(segment));

package/src/policies/continuation.ts

@@ -83,6 +83,13 @@ export async function continueUnfinishedSession(sessionID: string, settleTitle =
 		}
 		generatedIDs.add(messageID);
 		state.generatedMessageIDs.set(sessionID, generatedIDs);
+		const activeTasks = (effective.todos ?? [])
+			.filter((t) => t.status === "in_progress" || t.status === "pending")
+			.slice(0, 10);
+		const tasksSummary = activeTasks.length > 0
+			? "\nRemaining active tasks:\n" + activeTasks.map((t) => `- [${t.status === "in_progress" ? "IN_PROGRESS" : "PENDING"}] ${t.content}`).join("\n")
+			: "";
+
 		try {
 			await session.promptAsync({
 				path: { id: sessionID },
@@ -90,7 +97,7 @@ export async function continueUnfinishedSession(sessionID: string, settleTitle =
 					messageID,
 					parts: [{
 						type: "text",
-						text: "Workflow Guard: unfinished todos remain. Continue working through them. If you need user input, use the question tool instead of ending the run.",
+						text: `Workflow Guard: unfinished todos remain. Continue working through them.${tasksSummary}\nIf you need user input, use the question tool instead of ending the run.`,
 						synthetic: true,
 					}],
 				},

package/src/workflow-guard.ts

@@ -414,7 +414,11 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 				});
 				if (reason !== undefined) {
 					await emitBlockFeedback(reason);
-					throw new Error(`[workflow-guard] ${reason}`);
+					const failureCount = input.sessionID ? toolOutcomes.getFailureCount(input.sessionID) : 0;
+					const circuitBreakerSuffix = failureCount >= 2
+						? "\n\n[Workflow Guard Circuit Breaker: Repeated failures detected in this session. Stop attempting alternative workarounds or shell laundering. Address the required step above directly.]"
+						: "";
+					throw new Error(`[workflow-guard] ${reason}${circuitBreakerSuffix}`);
 				}
 				toolLifecycle.start(input.sessionID, input.callID);
 				if (input.tool === "read") {
@@ -606,13 +610,24 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 
 		// Keep tool descriptions honest: todowrite's description reflects lifecycle
 		// and finalization gates so the model is not surprised by preventable blocks.
+		// Similarly, mutating tools reflect their active-todo, feature-branch, and prior-read requirements.
 		"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\nWorkflow Guard lifecycle: each todowrite call replaces the complete task list. Preserve every pending/in_progress task in subsequent updates until you explicitly mark it completed or cancelled; do not omit active tasks when adding new work. Marking every task completed triggers the finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply.";
+			if (input.toolID === "todowrite") {
+				const description = typeof output.description === "string" ? output.description : "";
+				if (description.includes("verification evidence")) return;
+				output.description =
+					description +
+					"\n\nWorkflow Guard lifecycle: each todowrite call replaces the complete task list. Preserve every pending/in_progress task in subsequent updates until you explicitly mark it completed or cancelled; do not omit active tasks when adding new work. Marking every task completed triggers the finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply.";
+				return;
+			}
+			if (EDIT_TOOL_NAMES.has(input.toolID)) {
+				const description = typeof output.description === "string" ? output.description : "";
+				if (description.includes("Workflow Guard requirement")) return;
+				output.description =
+					description +
+					"\n\nWorkflow Guard requirement: Modifications require an active task in todowrite (status pending or in_progress), a feature branch (edits on main/master are blocked), and a prior read of existing files in the current session.";
+				return;
+			}
 		},
 
 		"chat.message": async (input) => {

package/test/test-e2e.mts

@@ -1,5 +1,5 @@
 import { mkdtempSync, rmSync, existsSync, readFileSync, copyFileSync, cpSync, mkdirSync, writeFileSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { parse as parseJsonc } from "jsonc-parser";
@@ -143,9 +143,30 @@ if (opencodeCheck.status !== 0) {
 }
 console.log(`  Found OpenCode version: ${opencodeCheck.stdout.trim()}`);
 
-const pluginsDir = join(testDir, ".opencode", "plugins");
+const opencodeDir = join(testDir, ".opencode");
+const pluginsDir = join(opencodeDir, "plugins");
 mkdirSync(pluginsDir, { recursive: true });
 
+// Pre-seed .opencode with dependencies already installed into testDir
+// so opencode does not execute a cold network install at runtime startup.
+const opencodeVersion = opencodeCheck.stdout.trim();
+const lockPath = join(testDir, "package-lock.json");
+if (existsSync(lockPath) && existsSync(join(testDir, "node_modules"))) {
+	try {
+		const lock = JSON.parse(readFileSync(lockPath, "utf8"));
+		lock.name = ".opencode";
+		if (lock.packages?.["node_modules/@opencode-ai/plugin"]) {
+			lock.packages["node_modules/@opencode-ai/plugin"].version = opencodeVersion;
+		}
+		if (lock.packages?.[""]) {
+			lock.packages[""].dependencies = { "@opencode-ai/plugin": opencodeVersion };
+		}
+		writeFileSync(join(opencodeDir, "package-lock.json"), JSON.stringify(lock, null, 2) + "\n");
+		writeFileSync(join(opencodeDir, "package.json"), JSON.stringify({ name: ".opencode", dependencies: { "@opencode-ai/plugin": opencodeVersion } }, null, 2) + "\n");
+		cpSync(join(testDir, "node_modules"), join(opencodeDir, "node_modules"), { recursive: true });
+	} catch {}
+}
+
 const sourcePlugin = join(import.meta.dirname, "..", "src", "workflow-guard.ts");
 const sourceDir = join(testDir, ".opencode", "workflow-guard-source");
 mkdirSync(sourceDir, { recursive: true });
@@ -189,9 +210,43 @@ const runtimeEnv: NodeJS.ProcessEnv = {
 };
 delete runtimeEnv.OPENCODE_PID;
 delete runtimeEnv.OPENCODE_PURE;
+delete runtimeEnv.OPENCODE;
 const runOpenCode = (args: string[], timeout: number) =>
 	spawnSync("opencode", ["run", "--dir", testDir, ...args], { cwd: testDir, encoding: "utf8", timeout, env: runtimeEnv });
-const configProbe = spawnSync("opencode", ["debug", "config"], { cwd: testDir, encoding: "utf8", timeout: 30_000, env: runtimeEnv });
+const configProbe = await new Promise<{ status: number | null; stdout: string; stderr: string }>((resolve) => {
+	const child = spawn("opencode", ["debug", "config"], { cwd: testDir, env: runtimeEnv });
+	let stdout = "";
+	let stderr = "";
+	let timer: NodeJS.Timeout | undefined;
+	let pollInterval: NodeJS.Timeout | undefined;
+
+	const done = (status: number | null) => {
+		if (timer) clearTimeout(timer);
+		if (pollInterval) clearInterval(pollInterval);
+		try { child.kill("SIGTERM"); } catch {}
+		resolve({ status: status ?? 0, stdout, stderr });
+	};
+
+	const checkReady = () => {
+		try {
+			if (JSON.parse(stdout)?.plugin_origins && existsSync(initializedMarker)) {
+				done(0);
+			}
+		} catch {}
+	};
+
+	pollInterval = setInterval(checkReady, 50);
+
+	child.stdout?.on("data", (d) => {
+		stdout += d.toString();
+		checkReady();
+	});
+	child.stderr?.on("data", (d) => { stderr += d.toString(); });
+	child.on("close", (code) => done(code));
+	child.on("error", () => done(null));
+
+	timer = setTimeout(() => done(null), 30_000);
+});
 let configLoadsLocalPlugin = false;
 try {
 	const config = JSON.parse(configProbe.stdout);

package/test/test.mts

@@ -497,6 +497,9 @@ check("sed -i on opencode.json blocked (tamper)", blocked(await call("bash", { c
 check("git apply needs todos (patch via shell)", blocked(await call("bash", { command: "git apply patch.diff" }, { sessionID: "s-empty" })));
 check("git apply allowed with todos", !(await call("bash", { command: "git apply patch.diff" }, { sessionID: "s-active" })));
 check("non-mutating shell unaffected (ls, cat)", !(await call("bash", { command: "ls -la && cat file" }, { sessionID: "s-empty" })));
+check("inspection command with mutation keywords in grep argument is not blocked", !(await call("bash", { command: 'strings /bin/opencode | grep -E "install plugin and update config" -C 10' }, { sessionID: "s-empty" })));
+check("git log with mutation keywords in grep argument is not blocked", !(await call("bash", { command: 'git log --grep="rm old files"' }, { sessionID: "s-empty" })));
+check("grep searching for mutation command name is not blocked", !(await call("bash", { command: 'grep -rn "mkdir" src/' }, { sessionID: "s-empty" })));
 check("stderr redirect to /dev/null is not a file mutation", !(await call("bash", { command: "ls missing 2>/dev/null" }, { sessionID: "s-empty" })));
 check("touch outside workspace is blocked", blocked(await call("bash", { command: "touch /tmp/wg-outside-touch" }, { sessionID: "s-active" })));
 check("mkdir outside workspace is blocked", blocked(await call("bash", { command: "mkdir /tmp/wg-outside-dir" }, { sessionID: "s-active" })));
@@ -1096,6 +1099,14 @@ if (typeof cmdEvt.event === "function") {
 }
 check("tool.execute.after provides deduplicated fallback outcome telemetry", getRecentAuditEntries(10).filter((entry) => entry.callID === "after-only-outcome" && entry.phase === "outcome").length === 1);
 
+let circuitBreakerMessage = "";
+try {
+	await cmdEvt["tool.execute.before"]?.({ tool: "edit", sessionID: "s-outcome", callID: "call-cb" } as any, { args: { filePath: join(root, "file.txt"), content: "hello" } } as any);
+} catch (err) {
+	circuitBreakerMessage = (err as Error).message;
+}
+check("repeated failures trigger circuit breaker guidance in block error", circuitBreakerMessage.includes("Workflow Guard Circuit Breaker") && circuitBreakerMessage.includes("Repeated failures detected"));
+
 const outcomeTracker = new ToolOutcomeTracker();
 const failedPart = (callID: string, error: string) => ({ type: "tool", sessionID: "s-tracker", callID, tool: "bash", state: { status: "error", error } } as const);
 check("duplicate terminal tool updates are ignored", !!outcomeTracker.record(failedPart("duplicate", "same failure")) && outcomeTracker.record(failedPart("duplicate", "same failure")) === undefined);
@@ -1104,6 +1115,12 @@ outcomeTracker.record({ type: "tool", sessionID: "s-tracker", callID: "success",
 check("successful tool outcomes reset equivalent failure tracking", outcomeTracker.record(failedPart("after-success", "same failure"))?.repeatedFailureCount === 1);
 outcomeTracker.record(failedPart("different", "different failure"));
 check("distinct failures reset equivalent failure tracking", outcomeTracker.record(failedPart("after-different", "same failure"))?.repeatedFailureCount === 1);
+const consecutiveTracker = new ToolOutcomeTracker();
+consecutiveTracker.record(failedPart("diverse-1", "failure A"));
+consecutiveTracker.record(failedPart("diverse-2", "failure B"));
+check("consecutive diverse failures track failure count for circuit breaker", consecutiveTracker.getFailureCount("s-tracker") === 2);
+consecutiveTracker.record({ type: "tool", sessionID: "s-tracker", callID: "diverse-success", tool: "bash", state: { status: "completed" } });
+check("successful tool outcome resets consecutive failure count", consecutiveTracker.getFailureCount("s-tracker") === 0);
 const boundedTracker = new ToolOutcomeTracker();
 for (let i = 0; i < 4096; i++) boundedTracker.record({ type: "tool", sessionID: "s-bounded", callID: `call-${i}`, tool: "bash", state: { status: "completed" } });
 check("terminal call deduplication remains stable within its bounded window", boundedTracker.record({ type: "tool", sessionID: "s-bounded", callID: "call-0", tool: "bash", state: { status: "completed" } }) === undefined);
@@ -3141,6 +3158,13 @@ const idemDef = { description: todoDef.description, parameters: {} };
 await defPlugin["tool.definition"]?.({ toolID: "todowrite" } as any, idemDef);
 check("tool.definition enrichment is idempotent", idemDef.description === todoDef.description);
 
+const editDef = { description: "Edit a file.", parameters: {} };
+await defPlugin["tool.definition"]?.({ toolID: "edit" } as any, editDef);
+check("tool.definition enriches edit tool with preconditions", editDef.description.includes("Workflow Guard requirement") && editDef.description.includes("todowrite"));
+const editIdemDef = { description: editDef.description, parameters: {} };
+await defPlugin["tool.definition"]?.({ toolID: "edit" } as any, editIdemDef);
+check("tool.definition edit enrichment is idempotent", editIdemDef.description === editDef.description);
+
 // Socratic learning engine: evidence is explicit and interventions favor
 // relevant gaps without repeatedly interrupting demonstrated knowledge.
 const learner = createLearnerProfile();