opencode-workflow-guard 1.15.5 → 1.17.0

package/src/policies/todo.ts

@@ -1,5 +1,5 @@
 import type { TodoItem } from "../lib/types.ts";
-import { getSessionMutationCount, getSdkClient, getSubagentMutationBudget } from "../lib/state.ts";
+import { getSessionMutationCount, getSdkClient, getSubagentMutationBudget, todoTaskStarts } from "../lib/state.ts";
 
 export const EDIT_TOOL_NAMES = new Set(["edit", "write", "patch", "apply_patch"]);
 export const ACTIVE_TODO_STATUSES = new Set(["pending", "in_progress"]);
@@ -94,6 +94,221 @@ export function hasActiveTodo(todos: TodoItem[]): boolean {
 	return todos.some((todo) => ACTIVE_TODO_STATUSES.has(String(todo.status ?? "")));
 }
 
+/**
+ * Explicit read-only escape. A task whose text carries this marker completes
+ * without a mutation in its window. Every use is journaled, so an agent that
+ * marks real work read-only leaves a visible trail instead of passing silently.
+ */
+export const READ_ONLY_TODO_MARKER = /\[read[-_ ]?only\]/i;
+
+export function isReadOnlyTodo(todo: TodoItem): boolean {
+	return READ_ONLY_TODO_MARKER.test(String(todo.content ?? ""));
+}
+
+/**
+ * Task identity: trimmed content with the read-only marker removed.
+ *
+ * The marker is an annotation about a task, not part of which task it is. An
+ * agent that planned a task and only then discovers it is read-only appends the
+ * marker; that must not read as deleting one task and inventing another, or the
+ * documented remedy would be blocked by the no-silent-deletion rule. It also
+ * keeps the task's window, so annotating instead of re-planning loses nothing.
+ */
+export function todoTaskKey(todo: TodoItem): string {
+	return String(todo.content ?? "")
+		.replace(READ_ONLY_TODO_MARKER, "")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+/** Raw task text, for messages the model has to match against its own list. */
+function todoTaskLabel(todo: TodoItem): string {
+	return String(todo.content ?? "").trim();
+}
+
+/**
+ * Record when each active task entered its current active window, in the
+ * session's mutation count. Completion evidence is judged against this.
+ *
+ * Call this only for a `todowrite` the guard allowed: a blocked write never
+ * becomes the task list, so it must not move a task's start.
+ */
+export function recordTodoTaskStarts(
+	starts: Map<string, number>,
+	previousTodos: TodoItem[] | undefined,
+	nextTodos: TodoItem[],
+	mutationCount: number,
+): void {
+	const previouslyActive = new Set<string>();
+	for (const todo of previousTodos ?? []) {
+		if (ACTIVE_TODO_STATUSES.has(String(todo.status ?? ""))) previouslyActive.add(todoTaskKey(todo));
+	}
+	const live = new Set<string>();
+	for (const todo of nextTodos) {
+		const key = todoTaskKey(todo);
+		if (!key) continue;
+		if (ACTIVE_TODO_STATUSES.has(String(todo.status ?? ""))) {
+			live.add(key);
+			// A task keeps its original window across rewrites and status
+			// changes within the active set. A task returning to active after
+			// finishing starts a fresh window.
+			if (!previouslyActive.has(key) || !starts.has(key)) starts.set(key, mutationCount);
+		}
+	}
+	// Finished or dropped tasks close their window; a later task with the
+	// same text starts clean instead of inheriting stale evidence.
+	for (const key of [...starts.keys()]) {
+		if (!live.has(key)) starts.delete(key);
+	}
+}
+
+/**
+ * Completion evidence, enforced: a task may not move to `completed` unless the
+ * session mutated at least once inside that task's active window. One mutation
+ * cannot vouch for several completions, so N completions need N mutations
+ * counted from the earliest of them.
+ *
+ * Read-only tasks are the documented escape: they carry `[read-only]` in their
+ * text and complete freely. Todos are still not authority on finalization; the
+ * verification gate remains the authority there.
+ *
+ * Tasks are matched to their prior occurrence by count, not by last-write-wins,
+ * so duplicate content cannot hide a new completion behind an already-completed
+ * item of the same text.
+ *
+ * Returns the tasks that still lack evidence. An empty list means the write may
+ * proceed.
+ */
+export function unverifiedTodoCompletions(
+	previousTodos: TodoItem[] | undefined,
+	nextTodos: TodoItem[],
+	starts: Map<string, number>,
+	mutationCount: number,
+): string[] {
+	// Each prior occurrence can absorb at most one new item of the same key. A
+	// prior `completed` occurrence absorbs a new `completed` item silently; any
+	// other prior occurrence leaves the new item as a fresh claim.
+	const absorbable = new Map<string, number>();
+	const absorbCompleted = new Map<string, number>();
+	for (const todo of previousTodos ?? []) {
+		const key = todoTaskKey(todo);
+		if (!key) continue;
+		absorbable.set(key, (absorbable.get(key) ?? 0) + 1);
+		if (String(todo.status ?? "") === "completed") {
+			absorbCompleted.set(key, (absorbCompleted.get(key) ?? 0) + 1);
+		}
+	}
+
+	const claimed: Array<{ task: string; start: number }> = [];
+	for (const todo of nextTodos) {
+		const key = todoTaskKey(todo);
+		if (!key) continue;
+		if (String(todo.status ?? "") !== "completed") continue;
+		const completedBefore = absorbCompleted.get(key) ?? 0;
+		if (completedBefore > 0) {
+			// An unchanged completed item, not a new claim.
+			absorbCompleted.set(key, completedBefore - 1);
+			const remaining = absorbable.get(key) ?? 0;
+			if (remaining > 0) absorbable.set(key, remaining - 1);
+			continue;
+		}
+		const remaining = absorbable.get(key) ?? 0;
+		if (remaining > 0) absorbable.set(key, remaining - 1);
+		if (isReadOnlyTodo(todo)) continue;
+		claimed.push({ task: todoTaskLabel(todo), start: starts.get(key) ?? 0 });
+	}
+
+	if (claimed.length === 0) return [];
+	// Each completion needs its own distinct mutation inside its own window.
+	// Checking only the earliest start would let mutations spent before a later
+	// task began vouch for it. Sorted by window start, a claim can only be
+	// satisfied if the window from that point still holds at least one mutation
+	// per remaining claim; the first failure marks an infeasible suffix, since
+	// every task after it has an equal or narrower window.
+	claimed.sort((a, b) => a.start - b.start);
+	for (let index = 0; index < claimed.length; index++) {
+		const remainingClaims = claimed.length - index;
+		if (mutationCount - claimed[index]!.start < remainingClaims) {
+			return claimed.slice(index).map((claim) => claim.task);
+		}
+	}
+	return [];
+}
+
+export function readOnlyTodoCompletions(
+	previousTodos: TodoItem[] | undefined,
+	nextTodos: TodoItem[],
+): string[] {
+	// Count prior occurrences by key and how many were already completed. An
+	// item carrying the marker is journaled when it is a new completion, which
+	// includes the common case of annotating an already-planned task.
+	const completedBefore = new Map<string, number>();
+	for (const todo of previousTodos ?? []) {
+		const key = todoTaskKey(todo);
+		if (!key) continue;
+		if (String(todo.status ?? "") === "completed") completedBefore.set(key, (completedBefore.get(key) ?? 0) + 1);
+	}
+	const readOnly: string[] = [];
+	for (const todo of nextTodos) {
+		if (String(todo.status ?? "") !== "completed" || !isReadOnlyTodo(todo)) continue;
+		const key = todoTaskKey(todo);
+		if (!key) continue;
+		const unchanged = completedBefore.get(key) ?? 0;
+		if (unchanged > 0) {
+			completedBefore.set(key, unchanged - 1);
+			continue;
+		}
+		readOnly.push(todoTaskLabel(todo));
+	}
+	return readOnly;
+}
+
+export function todoCompletionBlockReason(blocked: string[]): string {
+	const tasks = blocked.map((task) => `'${task}'`).join(", ");
+	return (
+		`Blocked todowrite: ${blocked.length === 1 ? "task" : "tasks"} ${tasks} marked completed without enough recorded work in the task window. ` +
+		"Complete the task's work first, then mark it completed. " +
+		"If the task was genuinely read-only (review, investigation, reading), append the marker `[read-only]` to its text and mark it completed. " +
+		"Use `cancelled` for work that was deliberately dropped."
+	);
+}
+
+/**
+ * Read-only view of a session's task evidence, for `guard_status`. Reports what
+ * the completion gate would decide now, so the requirement is visible before it
+ * blocks anything.
+ */
+export async function todoEvidenceReport(sessionID: string | undefined): Promise<{
+	active: number;
+	completed: number;
+	tasksWithoutRecordedWork: string[];
+	readOnlyTasks: string[];
+}> {
+	if (!sessionID) return { active: 0, completed: 0, tasksWithoutRecordedWork: [], readOnlyTasks: [] };
+	const todos = await effectiveTodos(sessionID);
+	if (!todos) return { active: 0, completed: 0, tasksWithoutRecordedWork: [], readOnlyTasks: [] };
+	const starts = todoTaskStarts(sessionID);
+	const count = getSessionMutationCount(sessionID);
+	const active = todos.filter((todo) => ACTIVE_TODO_STATUSES.has(String(todo.status ?? "")));
+	const tasksWithoutRecordedWork: string[] = [];
+	const readOnlyTasks: string[] = [];
+	for (const todo of active) {
+		const label = todoTaskLabel(todo);
+		if (!label) continue;
+		if (isReadOnlyTodo(todo)) {
+			readOnlyTasks.push(label);
+			continue;
+		}
+		if (count <= (starts.get(todoTaskKey(todo)) ?? 0)) tasksWithoutRecordedWork.push(label);
+	}
+	return {
+		active: active.length,
+		completed: todos.filter((todo) => String(todo.status ?? "") === "completed").length,
+		tasksWithoutRecordedWork,
+		readOnlyTasks,
+	};
+}
+
 export function validateTodoLifecycle(
 	newTodos: TodoItem[],
 	existingTodos: TodoItem[] | undefined,
@@ -115,26 +330,26 @@ export function validateTodoLifecycle(
 			const isReviewObligation = (content: string) => reviewObligation.test(content) && !(remediationAction.test(content) && reviewReference.test(content) && remediationSubject.test(content));
 			const newContentCounts = new Map<string, number>();
 			for (const todo of newTodos) {
-				const content = String(todo.content ?? "").trim();
+				const content = todoTaskKey(todo);
 				newContentCounts.set(content, (newContentCounts.get(content) ?? 0) + 1);
 			}
 			const retainedReviewCounts = new Map<string, number>();
 			for (const todo of activeNew) {
-				const content = String(todo.content ?? "").trim();
+				const content = todoTaskKey(todo);
 				retainedReviewCounts.set(content, (retainedReviewCounts.get(content) ?? 0) + 1);
 			}
 			let retainedReviewObligations = 0;
 			for (const todo of activeExisting) {
-				const content = String(todo.content ?? "").trim();
+				const content = todoTaskKey(todo);
 				const remaining = retainedReviewCounts.get(content) ?? 0;
 				if (remaining > 0 && isReviewObligation(content)) {
 					retainedReviewCounts.set(content, remaining - 1);
 					retainedReviewObligations++;
 				}
 			}
-			let replacementReviewObligations = activeNew.filter((t) => isReviewObligation(String(t.content ?? ""))).length - retainedReviewObligations;
+			let replacementReviewObligations = activeNew.filter((t) => isReviewObligation(todoTaskKey(t))).length - retainedReviewObligations;
 			const missing = activeExisting.find((todo) => {
-				const content = String(todo.content ?? "").trim();
+				const content = todoTaskKey(todo);
 				const remaining = newContentCounts.get(content) ?? 0;
 				if (remaining === 0 && isReviewObligation(content) && replacementReviewObligations > 0) {
 					replacementReviewObligations--;

package/src/workflow-guard.ts

@@ -22,7 +22,7 @@ import { expandShellTargetPath, isPathOutsideWorkspace, OPENCODE_SCRATCH_DIR, re
 import { beginReadObservation, clearReadFingerprints, recordMutationObservation, recordSuccessfulRead, staleWriteReason } from "./policies/stale-write.ts";
 import { ToolInvocationLifecycle } from "./lib/tool-lifecycle.ts";
 import { ToolOutcomeTracker, type ToolOutcomePart } from "./lib/tool-outcomes.ts";
-import { guardToolCallImpl, isReadOnlyRole, SHELL_TOOL_NAMES } from "./lib/guard-dispatcher.ts";
+import { guardToolCallImpl, isMutatingSurfaceTool, isReadOnlyRole, SHELL_TOOL_NAMES } from "./lib/guard-dispatcher.ts";
 import { createCustomTools, buildWorkflowGuardSystemGuidance } from "./lib/custom-tools.ts";
 import type { PolicyDecision, TodoSdkClient } from "./lib/types.ts";
 export { isReadOnlyRole } from "./lib/guard-dispatcher.ts";
@@ -68,6 +68,7 @@ import {
 	resetVerifyState,
 	sessionMutationTimestamps,
 	sessionVerifyResults,
+	clearTodoSessionState,
 	getProjectConfig,
 	getLiveControlPlaneRoots,
 	getOperationProfile,
@@ -75,6 +76,9 @@ import {
 	isReviewRequired,
 	isSubagentReviewRequired,
 	isDocumentationRequired,
+	isLiveDocsRequired,
+	getLiveDocFailureThreshold,
+	getResearchToolPatterns,
 	getSubagentMutationBudget,
 	isLearningEnabled,
 	isProjectMemoryEnabled,
@@ -88,6 +92,7 @@ import {
 	getSessionWorkspace,
 	getSessionBoundWorkspace,
 	registerSessionWorkspaceFromToolCall,
+	resolveInheritedWorkspace,
 	resolveSessionBoundWorkspace,
 	resolveEffectiveWorkspace,
 } from "./lib/state.ts";
@@ -112,6 +117,9 @@ export {
 	isReviewRequired,
 	isSubagentReviewRequired,
 	isDocumentationRequired,
+	isLiveDocsRequired,
+	getLiveDocFailureThreshold,
+	getResearchToolPatterns,
 	getSubagentMutationBudget,
 	isLearningEnabled,
 	getLearningInterventionBudget,
@@ -123,6 +131,7 @@ export {
 	getSessionWorkspace,
 	getSessionBoundWorkspace,
 	registerSessionWorkspaceFromToolCall,
+	resolveInheritedWorkspace,
 	resolveSessionBoundWorkspace,
 	resolveEffectiveWorkspace,
 	findGitRoot,
@@ -200,7 +209,7 @@ export function managedConfigDiagnostic(platform = process.platform, env: NodeJS
 		: "managed config location is unknown on this platform; plugin provenance is not verified by the OpenCode V1 API";
 }
 
-export { loadedPluginVersion } from "./lib/version.ts";
+export { loadedPluginVersion, qualifiedHostVersion } from "./lib/version.ts";
 
 // ── Verification engine ──────────────────────────────────────────────────────
 import {
@@ -327,6 +336,20 @@ import { checkCompletionClaims } from "./policies/completion.ts";
 
 export { checkCompletionClaims };
 
+import { checkSweepingClaims } from "./policies/sweeping-claims.ts";
+
+export { checkSweepingClaims };
+
+import {
+	clearLiveDocsFloor,
+	isResearchTool,
+	liveDocsGatingReason,
+	recordLiveDocsFailure,
+	recordResearchLookup,
+} from "./policies/live-docs.ts";
+
+export { isResearchTool, liveDocsGatingReason };
+
 export { sendDesktopNotification } from "./policies/shell-safety.ts";
 export { checkInteractiveTtyCommand, checkPackageHygiene, escapeAppleScriptString };
 
@@ -338,6 +361,14 @@ function logObservation(client: unknown, message: string): void {
 	} catch {}
 }
 
+function logWarn(client: unknown, message: string): void {
+	try {
+		void (client as TodoSdkClient | undefined)?.app?.log?.({
+			body: { service: "workflow-guard", level: "warn", message },
+		});
+	} catch {}
+}
+
 /**
  * Public guard entry point. Audits every decision (block or allow) to a
  * durable JSONL file before returning.
@@ -487,12 +518,43 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 						: "";
 					throw new Error(`[workflow-guard] ${reason}${circuitBreakerSuffix}`);
 				}
+				// Policy 25: after repeated failures with no live lookup since,
+				// block the guess-and-retry surfaces (mutations and shell) until
+				// the session grounds itself in current documentation. Research
+				// tools are never gated; an allowed research call records the
+				// lookup after it succeeds.
+				if (input.sessionID && isMutatingSurfaceTool(input.tool)) {
+					const threshold = getLiveDocFailureThreshold(toolWorktree);
+					if (isLiveDocsRequired(toolWorktree)) {
+						const researchReason = liveDocsGatingReason(input.sessionID, input.tool, threshold, getResearchToolPatterns(toolWorktree));
+						if (researchReason !== undefined) {
+							await emitBlockFeedback(researchReason);
+							logWarn(ctx.client, `[workflow-guard] ${researchReason}`);
+							audit({
+								ts: new Date().toISOString(),
+								sessionID: input.sessionID,
+								callID: input.callID,
+								tool: input.tool,
+								decision: "block",
+								phase: "decision",
+								reason: "live_docs_research_floor",
+							});
+							throw new Error(`[workflow-guard] ${researchReason}`);
+						}
+					}
+				}
 				toolLifecycle.start(input.sessionID, input.callID);
 				if (input.sessionID) {
 					const record = asRecord(args);
 					const workdir = typeof record?.workdir === "string" ? record.workdir : undefined;
 					const filePath = typeof record?.filePath === "string" ? record.filePath : (typeof record?.path === "string" ? record.path : undefined);
-					registerSessionWorkspaceFromToolCall(input.sessionID, { workdir, filePath, hostWorktree, toolWorktree });
+					await registerSessionWorkspaceFromToolCall(input.sessionID, {
+						workdir,
+						filePath,
+						hostWorktree,
+						toolWorktree,
+						mutating: EDIT_TOOL_NAMES.has(input.tool) || SHELL_TOOL_NAMES.has(input.tool),
+					});
 				}
 				if (input.tool === "read") {
 					const target = editTargets(args, toolWorktree)[0];
@@ -613,7 +675,7 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 					priorityContextBlocks.push(
 						`## Active Tasks${attribution}\n` +
 							lines.join("\n") +
-							"\nComplete tasks efficiently - mark finished items as completed and address remaining ones.",
+							"\nComplete tasks efficiently and address remaining ones. Mark a task completed only after its work is actually done: the guard blocks a completion with no recorded file mutation in that task's window. Append `[read-only]` to a genuinely read-only task (review, investigation), and use `cancelled` for work that was dropped.",
 					);
 				}
 
@@ -718,6 +780,20 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 						input: { claim: check.claim, evidenceState: check.evidenceState },
 					});
 				}
+				// Policy 26: journal sweeping repository claims unsupported by
+				// read coverage. Observability only - never mutates output.text.
+				const sweeping = checkSweepingClaims(text, { sessionID });
+				if (sweeping.sweeping && sweeping.reason) {
+					logObservation(ctx.client, `[workflow-guard] sweeping claim mismatch: ${sweeping.reason}`);
+					audit({
+						ts: new Date().toISOString(),
+						sessionID,
+						tool: "experimental.text.complete",
+						decision: "allow",
+						reason: `Sweeping claim '${sweeping.claim}' with ${sweeping.readFileCount} file(s) read`,
+						input: { claim: sweeping.claim, readFileCount: sweeping.readFileCount },
+					});
+				}
 			} catch {}
 		},
 
@@ -731,7 +807,7 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 				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. Proactively call guard_next_tasks when planning work to discover existing roadmap/TODOs, and guard_status to check outstanding requirements.";
+					"\n\nWorkflow Guard lifecycle: use todowrite to plan before working - it is the only view of progress the operator has, and every file mutation is gated on it. Each call replaces the complete task list: preserve every pending/in_progress task in subsequent updates until you explicitly mark it completed or cancelled, and do not omit active tasks when adding new work. A task may be marked completed only after its own work is recorded: the guard blocks a completion that has no file mutation in that task's active window, and one mutation cannot vouch for several completions. If a task is genuinely read-only (review, investigation, reading), append the marker `[read-only]` to its text; every such use is journaled. Use `cancelled` for work that was deliberately dropped. 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. Proactively call guard_next_tasks when planning work to discover existing roadmap/TODOs, and guard_status to check outstanding requirements.";
 				return;
 			}
 			if (EDIT_TOOL_NAMES.has(input.toolID)) {
@@ -784,6 +860,17 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 			if (event?.type === "message.part.updated") {
 				const outcome = toolOutcomes.record((event.properties as { part?: ToolOutcomePart })?.part ?? {});
 				if (outcome) {
+					// Policy 25 research floor: a failed call accrues debt; a
+					// successful live-source lookup clears it. Unrelated
+					// successes intentionally do not clear it. A research
+					// attempt never accrues debt even when it fails: otherwise
+					// a flaky network would deepen the block the agent is
+					// already trying to escape, and the floor would deadlock.
+					if (isResearchTool(outcome.tool, getResearchToolPatterns(getSessionBoundWorkspace(outcome.sessionID) || effectiveRoot))) {
+						if (outcome.status !== "error") recordResearchLookup(outcome.sessionID);
+					} else if (outcome.status === "error") {
+						recordLiveDocsFailure(outcome.sessionID);
+					}
 					audit({
 						ts: new Date().toISOString(),
 						sessionID: outcome.sessionID,
@@ -810,7 +897,10 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 			}
 			if (event?.type === "session.deleted") {
 				const sessionID = (event.properties as { info?: { id?: unknown } })?.info?.id;
-				if (typeof sessionID === "string") toolOutcomes.clearSession(sessionID);
+				if (typeof sessionID === "string") {
+					toolOutcomes.clearSession(sessionID);
+					clearTodoSessionState(sessionID);
+				}
 			}
 			if (event?.type === "session.idle") {
 				const sessionID = (event.properties as { sessionID?: unknown })?.sessionID;
@@ -853,6 +943,7 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 					clearReadFingerprints(sessionID);
 					toolLifecycle.clearSession(sessionID);
 					toolLifecycle.takeRecoveryRun(sessionID);
+					clearLiveDocsFloor(sessionID);
 					await runWithRuntimeState(effectiveRoot, ctx.client, () => clearContinuationState(sessionID));
 				}
 			}

package/test/test-e2e.mts

@@ -11,8 +11,13 @@ const check = (name: string, cond: unknown): boolean => {
 	cond ? (pass++, console.log("  ok  " + name)) : (fail++, console.log("FAIL  " + name));
 	return Boolean(cond);
 };
+// A live probe can only produce a guard verdict if the model actually ran.
+// These are host/provider errors that mean it did not: the prompt never
+// reached a model, so scoring the probe as a guard failure would be a false
+// accusation. Match the host's literal error shapes, not the bare phrase, so
+// model prose cannot mask a real guard regression.
 const providerUnavailable = (output: string): boolean =>
-	/available credits|insufficient credits|rate limit|too many requests|capacity|overloaded/i.test(output);
+	/available credits|insufficient credits|rate limit|too many requests|capacity|overloaded|Model unavailable:/i.test(output);
 const checkLive = (name: string, cond: unknown, output: string): boolean => {
 	if (!cond && providerUnavailable(output)) {
 		unavailable++;
@@ -45,11 +50,11 @@ const packageEntry = join(testDir, "node_modules", "opencode-workflow-guard", "s
 const installedPackageDir = join(testDir, "node_modules", "opencode-workflow-guard");
 const installedPackageJson = JSON.parse(readFileSync(join(testDir, "node_modules", "opencode-workflow-guard", "package.json"), "utf8"));
 check(
-	"npm package keeps direct dependencies on latest",
+	"npm package pins every direct dependency to an exact version",
 	Object.keys(installedPackageJson.dependencies ?? {}).length > 0 &&
-		Object.values(installedPackageJson.dependencies).every((spec) => spec === "latest") &&
+		Object.values(installedPackageJson.dependencies).every((spec) => /^\d+\.\d+\.\d+$/.test(String(spec))) &&
 		Object.keys(installedPackageJson.devDependencies ?? {}).length > 0 &&
-		Object.values(installedPackageJson.devDependencies).every((spec) => spec === "latest"),
+		Object.values(installedPackageJson.devDependencies).every((spec) => /^\d+\.\d+\.\d+$/.test(String(spec))),
 );
 check(
 	"npm tarball installs modular plugin entrypoint",
@@ -226,6 +231,7 @@ const runV2Probes = async (ctx: any) => {
 \t\t"secrets-shell": { tool: "bash", input: { command: "cat .env" } },
 \t\t"boundary-write": { tool: "write", input: { filePath: "../outside_escaped.txt", content: "probe" } },
 \t\t"shell-tty": { tool: "bash", input: { command: "vim notes.txt" } },
+\t\t"todo-completion": { tool: "todowrite", input: { todos: [{ content: "unstarted e2e work", status: "completed", priority: "medium" }] } },
 \t};
 \tconst whyResults: Record<string, any> = {};
 \tfor (const [name, probe] of Object.entries(whyProbes)) {
@@ -253,6 +259,7 @@ const runV1Probes = async (ctx: any) => {
 \t\t"secrets-shell": { tool: "bash", input: { command: "cat .env" } },
 \t\t"boundary-write": { tool: "write", input: { filePath: "../outside_escaped.txt", content: "probe" } },
 \t\t"shell-tty": { tool: "bash", input: { command: "vim notes.txt" } },
+\t\t"todo-completion": { tool: "todowrite", input: { todos: [{ content: "unstarted e2e work", status: "completed", priority: "medium" }] } },
 \t};
 \tconst whyResults: Record<string, any> = {};
 \tfor (const [name, probe] of Object.entries(whyProbes)) {
@@ -322,8 +329,11 @@ if (isOpenCodeV2) {
 	const servicePort = 49400 + (process.pid % 1000);
 	spawnSync("opencode", ["service", "set", "port", String(servicePort)], { cwd: testDir, encoding: "utf8", env: runtimeEnv, timeout: 30_000 });
 }
+// `run` takes its directory from the process cwd; 2.0.15 rejects `--dir` as an
+// unknown flag, which made every live probe report a flag error instead of a
+// guard verdict.
 const runOpenCode = (args: string[], timeout: number) =>
-	spawnSync("opencode", ["run", "--dir", testDir, ...args], { cwd: testDir, encoding: "utf8", timeout, env: runtimeEnv });
+	spawnSync("opencode", ["run", ...args], { cwd: testDir, encoding: "utf8", timeout, 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 = "";
@@ -401,6 +411,9 @@ check("headless guard_why simulates secret read policy via read tool", whyProbe(
 check("headless guard_why simulates secret read policy via shell", whyProbe("secrets-shell")?.policy === "secrets" && whyProbe("secrets-shell")?.code === "secret_read" && whyProbe("secrets-shell")?.status === "blocked");
 check("headless guard_why simulates workspace boundary policy via write tool", whyProbe("boundary-write")?.policy === "boundary" && whyProbe("boundary-write")?.code === "workspace_escape" && whyProbe("boundary-write")?.status === "blocked");
 check("headless guard_why simulates interactive tty shell-safety policy", whyProbe("shell-tty")?.policy === "shell-safety" && whyProbe("shell-tty")?.code === "interactive_tty" && whyProbe("shell-tty")?.status === "blocked");
+// The completion gate is host-version independent: claiming work the session
+// never did is blocked through the real dispatcher, on both adapter paths.
+check("headless guard_why simulates the todo completion evidence gate", whyProbe("todo-completion")?.policy === "todo" && whyProbe("todo-completion")?.code === "todo_completion_unverified" && whyProbe("todo-completion")?.status === "blocked");
 check("headless guard_status reports project config loaded from .opencode/workflow-guard.json", headlessAccountability?.status?.projectConfig?.protectedBranches?.[0] === "e2e-config-probe-branch" && headlessAccountability?.status?.projectConfig?.requireReview === false);
 if (isOpenCodeV2) {
 	// The V2 adapter runs the shipped setup(ctx) for real; verify the
@@ -421,6 +434,78 @@ if (isOpenCodeV2) {
 	console.log(`  note: builtin todowrite description enriched under V2: ${headlessAccountability?.todowriteEnriched === true ? "yes" : "unknown at setup time"}`);
 }
 
+// The todo capability probe is only meaningful against a host that can gate
+// the tool. Probe the flag rather than the version: a host that does not know
+// `experimental.todo` keeps the capability unavailable, which is the branch
+// the main pass already covers.
+const hostMinor = Number(opencodeSemver.split(".")[1] ?? 0);
+if (isOpenCodeV2 && (opencodeMajor > 2 || (opencodeMajor === 2 && hostMinor >= 1))) {
+	const todoConfig = join(testDir, ".opencode", "opencode.json");
+	const previousConfig = readFileSync(todoConfig, "utf8");
+	const previousAccountability = readFileSync(accountabilityMarker, "utf8");
+	rmSync(initializedMarker, { force: true });
+	// A second pass needs its own XDG roots and service port. Reusing the first
+	// pass's state dirs reconnects to its already-running service, which serves
+	// the config it started with and never re-runs plugin setup.
+	const todoEnv: NodeJS.ProcessEnv = {
+		...runtimeEnv,
+		XDG_CONFIG_HOME: join(testDir, "runtime-config-todo"),
+		XDG_STATE_HOME: join(testDir, "runtime-state-todo"),
+		XDG_DATA_HOME: join(testDir, "runtime-data-todo"),
+	};
+	const todoPort = 49400 + ((process.pid + 500) % 1000);
+	spawnSync("opencode", ["service", "set", "port", String(todoPort)], { cwd: testDir, encoding: "utf8", env: todoEnv, timeout: 30_000 });
+	try {
+		const parsed = JSON.parse(previousConfig);
+		writeFileSync(todoConfig, `${JSON.stringify({ ...parsed, experimental: { ...(parsed.experimental ?? {}), todo: true } }, null, 2)}\n`);
+		const todoProbe = await new Promise<{ status: number | null }>((resolve) => {
+			const child = spawn("opencode", ["debug", "config"], { cwd: testDir, env: todoEnv });
+			let timer: NodeJS.Timeout | undefined;
+			const poll = setInterval(() => {
+				if (existsSync(initializedMarker)) {
+					clearInterval(poll);
+					if (timer) clearTimeout(timer);
+					try { child.kill("SIGTERM"); } catch {}
+					resolve({ status: 0 });
+				}
+			}, 50);
+			timer = setTimeout(() => {
+				clearInterval(poll);
+				try { child.kill("SIGTERM"); } catch {}
+				resolve({ status: null });
+			}, 30_000);
+			child.on("error", () => {
+				clearInterval(poll);
+				if (timer) clearTimeout(timer);
+				resolve({ status: null });
+			});
+		});
+		let flagged: any;
+		try {
+			flagged = JSON.parse(readFileSync(accountabilityMarker, "utf8"));
+		} catch {}
+		// Flag on: the host registry exposes todowrite, so the guard reports the
+		// capability available and the gate stops failing open.
+		check(
+			"V2 todo capability reports available when experimental.todo is enabled",
+			todoProbe.status === 0 &&
+				(flagged?.tools ?? []).includes("todowrite") &&
+				flagged?.status?.todoCapability === "available",
+		);
+		// The main pass ran with the flag off, so the capability there must be
+		// unavailable. Together the two passes prove the probe reads the
+		// registry instead of inferring from history.
+		check(
+			"V2 todo capability reports unavailable when experimental.todo is disabled",
+			(headlessAccountability?.tools ?? []).includes("todowrite") === false &&
+				headlessAccountability?.status?.todoCapability === "unavailable",
+		);
+	} finally {
+		writeFileSync(todoConfig, previousConfig);
+		writeFileSync(accountabilityMarker, previousAccountability);
+	}
+}
+
 if (process.env.WORKFLOW_GUARD_LIVE_E2E !== "1") {
 	console.log("SKIP: model-driven policy probes require WORKFLOW_GUARD_LIVE_E2E=1.");
 	if (!process.env.WG_E2E_KEEP) rmSync(testDir, { recursive: true, force: true });
@@ -450,7 +535,7 @@ console.log(`  Using live model: ${liveModel}`);
 
 // 3. Test: Direct edit without task list is blocked by the loaded plugin
 console.log("  Running live OpenCode prompt to verify plugin intercept...");
-const run1 = runOpenCode(["--model", liveModel, "--print-logs", "--log-level", "DEBUG", "Do not call todowrite. Invoke bash immediately with exactly this command: printf blocked > blocked.txt. This is a guard test; make the tool call even if you expect rejection."], 120_000);
+const run1 = runOpenCode(["--model", liveModel, "--print-logs", "--log-level", "debug", "Do not call todowrite. Invoke bash immediately with exactly this command: printf blocked > blocked.txt. This is a guard test; make the tool call even if you expect rejection."], 120_000);
 
 const output1 = run1.stdout + run1.stderr;
 const adapterInitialized = existsSync(initializedMarker);