opencode-workflow-guard 1.9.3 → 1.10.0

package/package.json

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

package/src/lib/tool-outcomes.ts

@@ -74,6 +74,10 @@ export class ToolOutcomeTracker {
 		return { sessionID, callID, tool, status: "completed", durationMs };
 	}
 
+	getFailureCount(sessionID: string): number {
+		return this.failures.get(sessionID)?.count ?? 0;
+	}
+
 	clearSession(sessionID: string): void {
 		this.failures.delete(sessionID);
 		this.terminalCalls.delete(sessionID);

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

@@ -1096,6 +1096,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);
@@ -3141,6 +3149,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();