opencode-workflow-guard 1.15.5 → 1.16.0

package/src/lib/call-claims.ts

@@ -0,0 +1,71 @@
+/**
+ * Cross-instance tool-call claiming.
+ *
+ * OpenCode 2 merges plugin arrays, so naming the guard in both the global and
+ * the project config loads the same module twice under two ids. Both instances
+ * register `tool.execute.before`, which evaluated and audited every call twice
+ * and let a second instance's decision shadow the first.
+ *
+ * The first instance to reach a given (session, call, tool) owns the decision.
+ * A second instance for the same call defers instead of evaluating again, so a
+ * call produces exactly one policy decision and one decision audit record.
+ * Within a single instance nothing is skipped: the claim only deduplicates
+ * *across* instances, because one instance must still evaluate each of its own
+ * calls even if a host reuses call ids.
+ */
+
+const MAX_CLAIMS = 4096;
+// Process-global, not module-global: OpenCode can load the guard from two
+// distinct paths (a cache copy plus a source checkout), and each copy
+// evaluates this module separately. A `Symbol.for` slot on `globalThis` keeps
+// ONE claim table so the second copy still defers to the first.
+const CLAIMS_REGISTRY = Symbol.for("opencode-workflow-guard.call-claims.v1");
+const globalRegistry = globalThis as unknown as Record<symbol, Map<string, string> | undefined>;
+const claims: Map<string, string> = globalRegistry[CLAIMS_REGISTRY] ?? (globalRegistry[CLAIMS_REGISTRY] = new Map());
+
+function claimKey(sessionID: string | undefined, callID: string | undefined, tool: string): string | undefined {
+	if (!sessionID || !callID) return undefined;
+	return `${sessionID}::${callID}::${tool}`;
+}
+
+/**
+ * Claim a tool call for `instanceKey`. Returns true when the caller owns the
+ * decision. Returns false when another instance already claimed it, which means
+ * the caller must defer (no evaluation, no audit) to keep one decision per call.
+ */
+export function claimToolCall(
+	instanceKey: string,
+	sessionID: string | undefined,
+	callID: string | undefined,
+	tool: string,
+): boolean {
+	const key = claimKey(sessionID, callID, tool);
+	if (!key) return true;
+	const owner = claims.get(key);
+	if (owner === undefined) {
+		claims.set(key, instanceKey);
+		if (claims.size > MAX_CLAIMS) {
+			const oldest = claims.keys().next().value;
+			if (oldest !== undefined) claims.delete(oldest);
+		}
+		return true;
+	}
+	return owner === instanceKey;
+}
+
+/** Release a claim after the call settles so the map stays bounded in long sessions. */
+export function releaseToolCallClaim(
+	instanceKey: string,
+	sessionID: string | undefined,
+	callID: string | undefined,
+	tool: string,
+): void {
+	const key = claimKey(sessionID, callID, tool);
+	if (!key) return;
+	if (claims.get(key) === instanceKey) claims.delete(key);
+}
+
+/** Test seam. */
+export function resetToolCallClaimsForTesting(): void {
+	claims.clear();
+}

package/src/lib/config-writer.d.mts

@@ -0,0 +1,13 @@
+/** Types for `config-writer.mjs`, the testable half of the `setup` command. */
+
+export declare const PACKAGE_NAME: string;
+export declare function pluginKeyFor(config: Record<string, unknown>, explicitMajor?: number): "plugin" | "plugins";
+export declare function matchesPackageSpec(entry: unknown, spec: string): boolean;
+export declare function preparePluginUpdate(
+	path: string,
+	schema: string,
+	spec: string,
+	legacySpec?: string,
+	explicitMajor?: number,
+	key?: "plugin" | "plugins",
+): string | undefined;

package/src/lib/config-writer.mjs

@@ -0,0 +1,89 @@
+/**
+ * Config writing for `opencode-workflow-guard setup`.
+ *
+ * Split out of the bin script so the key-selection rules are testable without
+ * writing a live config. The bin stays a thin wrapper.
+ *
+ * Which key the target host reads:
+ *
+ * - OpenCode 1.x reads the singular `plugin` key.
+ * - OpenCode 2.x reads only the plural `plugins` key. The 2.0.10 config schema
+ *   drops a singular `plugin` key without an error
+ *   (`Schema.decodeUnknownSync(Config.Info)` returns an object with no `plugin`
+ *   field), so writing the wrong key produces a config that looks configured
+ *   and loads nothing.
+ *
+ * `--major` states the target explicitly. Without it, the existing config
+ * decides: a `plugins` key means 2.x, a `plugin` key means 1.x. A fresh config
+ * defaults to 2, because this package's host dependency is pinned to a 2.x
+ * release.
+ *
+ * `tui.json` is the exception. Its schema is singular `plugin` on both majors:
+ * OpenCode 2 reads `tui.json` with that key and migrates it into
+ * `cli.json.plugins`. Writing `plugins` there on 2.x produces a file the TUI
+ * schema ignores, so the TUI plugin silently never loads. Callers pass
+ * `key` to pin the TUI array's key independently of the server config.
+ *
+ * Evidence for that migration, since no TUI schema is vendored here: the
+ * installed 2.0.15 binary's cli-config migration step reads
+ * `join(config, "tui.json")`, decodes it with a schema whose only plugin field
+ * is singular `plugin`, and emits `plugins` into `cli.json`. The unit tests
+ * therefore pin the writer's key choice; the host behavior itself is
+ * host-version-dependent and is re-checked by `npm run test:install`.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { applyEdits, modify, parse } from "jsonc-parser";
+
+export const PACKAGE_NAME = "opencode-workflow-guard";
+
+/** Which plugin array key the target OpenCode major reads. */
+export function pluginKeyFor(config, explicitMajor) {
+	const major = explicitMajor ?? (config.plugins !== undefined ? 2 : config.plugin !== undefined ? 1 : 2);
+	return major === 1 ? "plugin" : "plugins";
+}
+
+export function matchesPackageSpec(entry, spec) {
+	const value = Array.isArray(entry) ? entry[0] : entry;
+	return typeof value === "string" && (value === spec || value.startsWith(`${spec}@`));
+}
+
+/**
+ * Prepare an updated config document adding `spec` to the target's plugin
+ * array, removing a `legacySpec` entry when one is supplied.
+ *
+ * Returns `undefined` when the document already names the package, so an
+ * unchanged config is never rewritten. Throws on an unparseable document or a
+ * non-array plugin key rather than clobbering a config it does not understand.
+ */
+export function preparePluginUpdate(path, schema, spec, legacySpec, explicitMajor, key) {
+	const source = existsSync(path)
+		? readFileSync(path, "utf8")
+		: `{
+  "$schema": "${schema}"
+}\n`;
+	const errors = [];
+	const config = parse(source, errors, { allowTrailingComma: true, disallowComments: false });
+	if (errors.length > 0 || !config || typeof config !== "object" || Array.isArray(config)) {
+		throw new Error(`Cannot update invalid config: ${path}`);
+	}
+	const targetKey = key ?? pluginKeyFor(config, explicitMajor);
+	if (config[targetKey] !== undefined && !Array.isArray(config[targetKey])) {
+		throw new Error(`Cannot update ${path}: "${targetKey}" must be an array`);
+	}
+	const plugins = config[targetKey] ?? [];
+	const hasSpec = plugins.some((entry) => matchesPackageSpec(entry, PACKAGE_NAME));
+	const updatedPlugins = legacySpec
+		? plugins.filter((entry) => !matchesPackageSpec(entry, legacySpec))
+		: plugins;
+	if (updatedPlugins.length !== plugins.length) {
+		if (!hasSpec) updatedPlugins.push(spec);
+		return applyEdits(source, modify(source, [targetKey], updatedPlugins, {
+			formattingOptions: { insertSpaces: true, tabSize: 2 },
+		}));
+	}
+	if (hasSpec) return undefined;
+	return applyEdits(source, modify(source, [targetKey, plugins.length], spec, {
+		formattingOptions: { insertSpaces: true, tabSize: 2 },
+	}));
+}

package/src/lib/custom-tools.ts

@@ -36,15 +36,17 @@ import {
 	runWithRuntimeState,
 } from "./state.ts";
 import { getRalphOutcome } from "../policies/continuation.ts";
+import { todoEvidenceReport } from "../policies/todo.ts";
 import { findGitRoot, loadProjectConfig, projectRootKey } from "./project-config.ts";
 import { detectVerifyCommand, getCurrentGitCommitHash, getGitWorktreeFingerprint, getTrackedWorktreeFingerprint } from "./verify.ts";
 import { buildReviewRubric } from "./review.ts";
-import { createGitWorktree, cleanupGitWorktree } from "./worktree.ts";
+import { createGitWorktree, cleanupGitWorktree, validateHostWorktreeDirectory } from "./worktree.ts";
+import type { HostWorktreePort } from "./host-worktree.ts";
 import { branchHasDocumentationChange } from "../policies/docs.ts";
 import { restoreRecoveryCheckpoint } from "./checkpoint.ts";
 import { audit, getRecentAuditEntries } from "./audit.ts";
 import { guardToolCallImpl } from "./guard-dispatcher.ts";
-import { loadedPluginVersion } from "./version.ts";
+import { loadedPluginVersion, qualifiedHostVersion } from "./version.ts";
 import { gitHygieneSnapshot } from "./hygiene.ts";
 import { discoverPlanningSources } from "../policies/planning.ts";
 import { secretIn } from "../policies/secrets.ts";
@@ -76,7 +78,7 @@ export function buildWorkflowGuardSystemGuidance(options: {
 	const sections: string[] = [
 		"## Workflow Guard & Operational Tools",
 		"Workflow Guard enforces safe engineering discipline and provides proactive workflow tools:",
-		"- Task Planning: Proactively call `guard_next_tasks` at session start or when planning work to discover repository roadmap, plan, and TODO items. Check `guard_status` to inspect branch protection, mutation count, and outstanding verification/review gates.",
+		"- Task Planning: The session's todo list is the unit of visible progress and it gates every file mutation. Call `todowrite` before starting work, keep exactly the real remaining tasks in it, and mark a task completed only after its work is actually done. A completion is checked against recorded work in that task's window, so finishing a task without doing it is blocked. Genuinely read-only tasks (review, investigation, reading) are marked `[read-only]` in their text. Proactively call `guard_next_tasks` at session start or when planning work to discover repository roadmap, plan, and TODO items, and check `guard_status` to inspect branch protection, mutation count, and outstanding verification/review gates.",
 	];
 
 	if (!options.isReadOnly) {
@@ -121,8 +123,25 @@ export function createCustomTools(options: {
 	portableMemoryPath: string;
 	learningInterventions: Map<string, number>;
 	client: unknown;
+	/**
+	 * Host worktree port. When present and available, creation goes through the
+	 * host so the worktree lands in its configured directory and inventory.
+	 * Removal stays with the guard's snapshot-then-remove flow regardless.
+	 */
+	hostWorktree?: HostWorktreePort;
+	/**
+	 * Probed todo capability for this host, reported in `guard_status`.
+	 * Omitted on V1, which has a native todo endpoint and therefore always can
+	 * plan; V2 passes its registry probe so a fail-open gate is visible.
+	 */
+	todoCapability?: () => string;
+	/**
+	 * Live host version, reported next to the version this build was qualified
+	 * against so a mismatch is visible before it becomes a silent no-op.
+	 */
+	hostVersion?: () => string | undefined;
 }) {
-	const { effectiveRoot, projectMemoryEnabled, learningEnabled, projectMemory, followupStore, portableMemoryPath, learningInterventions, client } = options;
+	const { effectiveRoot, projectMemoryEnabled, learningEnabled, projectMemory, followupStore, portableMemoryPath, learningInterventions, client, hostWorktree, todoCapability, hostVersion } = options;
 	// Resolve the workspace for a tool call from the CALL's own context: an
 	// explicit argument first, then the host-provided per-call worktree or
 	// directory (even when unusable — the call declared its target), then the
@@ -276,7 +295,8 @@ export function createCustomTools(options: {
 					recommendedActions.push("All operational requirements are satisfied for task finalization and PR creation.");
 				}
 				const ralphOutcome = runWithRuntimeState(root, client, () => getRalphOutcome(toolContext.sessionID));
-				return JSON.stringify({ pluginVersion: loadedPluginVersion() ?? null, workspaceRoot: root, branch, onProtectedBranch: isProtected, outstandingRequirements, recommendedActions, lastMutationTimestamp: lastMut, mutationCount: getWorkspaceMutationCount(root), lastVerify: lastV && verifyEvidence ? { command: lastV.command, passed: lastV.passed, fresh: verifyFresh, evidenceId: verifyEvidence.id, commitHash: lastV.commitHash } : null, lastReview: lastR && reviewEvidenceRecord ? { reviewer: lastR.reviewer, passed: lastR.passed, summary: lastR.summary, fresh: reviewFresh, evidenceId: reviewEvidenceRecord.id } : null, ralph: { enabled: isRalphModeEnabled(root), maxIterations: getRalphMaxIterations(root), outcome: ralphOutcome ?? null }, projectConfig: { profile: getOperationProfile(root), protectedBranches: cfg.protectedBranches ?? ["main", "master"], verifyCommand: verifyCommand ?? null, requireReview: reviewRequired, requireDocumentation: documentationRequired, requireSubagentReview: isSubagentReviewRequired(root), recoveryCheckpoints: isRecoveryCheckpointsEnabled(root) }, gitHygiene: gitHygieneSnapshot(root) ?? null }, null, 2);
+				const taskEvidence = await runWithRuntimeState(root, client, () => todoEvidenceReport(toolContext.sessionID));
+				return JSON.stringify({ pluginVersion: loadedPluginVersion() ?? null, qualifiedHostVersion: qualifiedHostVersion() ?? null, hostVersion: hostVersion?.() ?? null, workspaceRoot: root, branch, onProtectedBranch: isProtected, todoCapability: todoCapability ? todoCapability() : "available", taskEvidence, outstandingRequirements, recommendedActions, lastMutationTimestamp: lastMut, mutationCount: getWorkspaceMutationCount(root), lastVerify: lastV && verifyEvidence ? { command: lastV.command, passed: lastV.passed, fresh: verifyFresh, evidenceId: verifyEvidence.id, commitHash: lastV.commitHash } : null, lastReview: lastR && reviewEvidenceRecord ? { reviewer: lastR.reviewer, passed: lastR.passed, summary: lastR.summary, fresh: reviewFresh, evidenceId: reviewEvidenceRecord.id } : null, ralph: { enabled: isRalphModeEnabled(root), maxIterations: getRalphMaxIterations(root), outcome: ralphOutcome ?? null }, projectConfig: { profile: getOperationProfile(root), protectedBranches: cfg.protectedBranches ?? ["main", "master"], verifyCommand: verifyCommand ?? null, requireReview: reviewRequired, requireDocumentation: documentationRequired, requireSubagentReview: isSubagentReviewRequired(root), recoveryCheckpoints: isRecoveryCheckpointsEnabled(root) }, gitHygiene: gitHygieneSnapshot(root) ?? null }, null, 2);
 			},
 		}),
 		guard_audit: tool({ description: "View recent audit entries recorded by opencode-workflow-guard. Use to diagnose policy decisions, blocked commands, or outcome telemetry.", args: { limit: tool.schema.number().optional().describe("Maximum entries to return (default 10)") }, execute: async (args) => JSON.stringify(getRecentAuditEntries(typeof args?.limit === "number" ? Math.min(args.limit, 50) : 10), null, 2) }),
@@ -374,17 +394,58 @@ export function createCustomTools(options: {
 			description: "Create an isolated git worktree directory for concurrent subagent execution. Proactively call when launching parallel tasks/subagents to prevent file collision and maintain branch isolation.", args: { branch: tool.schema.string().describe("Branch name for the isolated worktree (e.g. 'feat/subagent-task')"), baseBranch: tool.schema.string().optional().describe("Base branch to branch off of (defaults to HEAD)") },
 			execute: async (args, toolContext) => {
 				const todos = await effectiveTodos(toolContext.sessionID); if (todos !== undefined && !hasActiveTodo(todos)) return "[workflow-guard] Blocked: worktree creation with no active todo item. Break the request down with todowrite first, then create worktrees.";
-				const toolRoot = await resolveCallWorkspace(toolContext); const res = createGitWorktree(args.branch, args.baseBranch ?? "HEAD", toolRoot); if (!res.success) return `[workflow-guard] Failed to create worktree: ${res.error}`;
+				const toolRoot = await resolveCallWorkspace(toolContext);
+				// Host first: it honors the operator's configured worktree directory
+				// and keeps the worktree in host inventory. The result is validated
+				// independently (registered worktree of THIS repo, not the primary
+				// tree); any failure falls back to the guard's git path.
+				//
+				// The host path is used only for the default base. The host create
+				// input's `from` is an absolute directory path, not a git ref, so an
+				// explicit `baseBranch` cannot be expressed there; honoring it via
+				// the git path is better than silently ignoring it.
+				let createdPath: string | undefined;
+				let hostNote = "";
+				const requestedBase = args.baseBranch ?? "HEAD";
+				if (hostWorktree?.available && requestedBase === "HEAD") {
+					const hostResult = await hostWorktree.create({ branch: args.branch });
+					if (hostResult.directory) {
+						const validation = validateHostWorktreeDirectory(hostResult.directory, toolRoot);
+						if (validation.ok) {
+							createdPath = resolve(hostResult.directory);
+							hostNote = " (created by the host worktree strategy)";
+						} else {
+							hostNote = ` Host worktree creation was rejected by the guard (${validation.error}); used the guard's git path instead.`;
+						}
+					} else if (hostResult.error) {
+						hostNote = ` Host worktree creation failed (${hostResult.error}); used the guard's git path instead.`;
+					}
+				}
+				if (!createdPath) {
+					const res = createGitWorktree(args.branch, requestedBase, toolRoot);
+					if (!res.success) return `[workflow-guard] Failed to create worktree: ${res.error}${hostNote}`;
+					createdPath = res.worktreePath;
+				}
 				const mutationRoot = await resolveCallWorkspace(toolContext);
 				await runWithRuntimeState(mutationRoot, client, async () => recordMutation((await effectiveTodoOwnerSessionID(toolContext.sessionID)) ?? toolContext.sessionID, toolContext.sessionID));
-				return `[workflow-guard] Worktree created successfully at: ${res.worktreePath}\nRun subagent tasks or pass worktree directory context to isolate file mutations.`;
+				return `[workflow-guard] Worktree created successfully at: ${createdPath}${hostNote}\nRun subagent tasks or pass worktree directory context to isolate file mutations.`;
 			},
 		}),
 		guard_worktree_cleanup: tool({
 			description: "Commit a final snapshot and remove an isolated git worktree directory. Call to clean up worktrees created with guard_worktree_create after subagent tasks complete.", args: { worktreePath: tool.schema.string().describe("Path of the worktree directory to clean up") },
 			execute: async (args, toolContext) => {
 				const todos = await effectiveTodos(toolContext.sessionID); if (todos !== undefined && !hasActiveTodo(todos)) return "[workflow-guard] Blocked: worktree cleanup with no active todo item. Break the request down with todowrite first, then clean up worktrees.";
-				const toolRoot = await resolveCallWorkspace(toolContext); const res = cleanupGitWorktree(args.worktreePath, toolRoot); if (!res.success) return `[workflow-guard] Failed to clean up worktree: ${res.error}`;
+				const toolRoot = await resolveCallWorkspace(toolContext);
+				// Removal never delegates to the host: its `remove` takes a `force`
+				// flag and has no snapshot step, so it can destroy uncommitted work
+				// the guard's snapshot-then-remove flow preserves. The host list is
+				// used only to authorize a directory outside the guard's storage.
+				const hostWorktrees = hostWorktree?.available ? await hostWorktree.list() : undefined;
+				const res = cleanupGitWorktree(args.worktreePath, toolRoot, { hostWorktrees });
+				if (!res.success) return `[workflow-guard] Failed to clean up worktree: ${res.error}`;
+				// Tell the host its inventory is stale, or it keeps listing the
+				// removed directory until something else refreshes it.
+				await hostWorktree?.refresh();
 				const mutationRoot = await resolveCallWorkspace(toolContext);
 				await runWithRuntimeState(mutationRoot, client, async () => recordMutation((await effectiveTodoOwnerSessionID(toolContext.sessionID)) ?? toolContext.sessionID, toolContext.sessionID));
 				return `[workflow-guard] Worktree at '${args.worktreePath}' cleaned up successfully.`;

package/src/lib/guard-command.ts

@@ -0,0 +1,97 @@
+/**
+ * Server-side `/guard-status` command for OpenCode 2.
+ *
+ * Before this, the only way to read guard state from inside a session was the
+ * separately installed TUI companion, or knowing the `guard_status` tool name.
+ * `ctx.command.transform` registers a command that runs in every V2 client.
+ *
+ * The command computes the report from the guard's own `guard_status` tool and
+ * delivers it as a synthetic message. Two deliberate choices:
+ *
+ * - The report is not relayed through the model. `guard_status` is
+ *   authoritative state; asking a model to restate it would introduce a
+ *   paraphrase step between the operator and the evidence.
+ * - Delivery uses `session.synthetic`, so the command costs no model turn.
+ *   Synthetic messages do not run the `session.prompt` hook, so this cannot
+ *   churn recovery checkpoints.
+ */
+
+import type { Plugin } from "@opencode/plugin";
+import { audit } from "./audit.ts";
+import { runWithRuntimeState } from "./state.ts";
+
+/** The command id. Prefixed so it cannot shadow a user command by accident. */
+export const GUARD_STATUS_COMMAND = "guard-status";
+
+export interface GuardStatusCommandDeps {
+	/** Produces the same JSON report as the `guard_status` tool. */
+	runStatus: (sessionID: string) => Promise<string>;
+	effectiveRoot: string;
+	client: unknown;
+}
+
+interface CommandInvocation {
+	readonly sessionID: string;
+}
+
+/**
+ * Register the command. Registration is additive: a collision with an existing
+ * command id is the host's to resolve, and the `guard-` prefix keeps that from
+ * being accidental.
+ */
+export async function registerGuardStatusCommand(
+	ctx: Plugin.Context,
+	deps: GuardStatusCommandDeps,
+): Promise<void> {
+	const editorHost = ctx.command as unknown as {
+		transform: (callback: (editor: {
+			add: (definition: {
+				name: string;
+				description?: string;
+				execute: (input: CommandInvocation) => Promise<void>;
+			}) => void;
+		}) => void) => Promise<unknown>;
+	};
+	await editorHost.transform((editor) => {
+		editor.add({
+			name: GUARD_STATUS_COMMAND,
+			description: "Show Workflow Guard status: branch protection, mutation count, outstanding verification/review gates, and todo capability.",
+			execute: async ({ sessionID }) => {
+				let report: string;
+				try {
+					report = await deps.runStatus(sessionID);
+				} catch (error) {
+					report = JSON.stringify({
+						error: `guard_status could not be computed: ${(error as Error)?.message ?? "unknown error"}`,
+					});
+				}
+				audit({
+					ts: new Date().toISOString(),
+					sessionID,
+					tool: `command.${GUARD_STATUS_COMMAND}`,
+					decision: "allow",
+					phase: "event",
+					reason: "guard_status_command",
+				});
+				await runWithRuntimeState(deps.effectiveRoot, deps.client, async () => {
+					const session = ctx.session as unknown as {
+						synthetic: (input: { sessionID: string; text: string }) => Promise<unknown>;
+					};
+					try {
+						await session.synthetic({ sessionID, text: `## Workflow Guard status\n\n\`\`\`json\n${report}\n\`\`\`` });
+					} catch (error) {
+						// A client that cannot admit synthetic messages still needs the
+						// report to be visible; fall back to a normal prompt.
+						try {
+							console.warn(`[workflow-guard] warn: /${GUARD_STATUS_COMMAND} synthetic delivery failed (${(error as Error)?.message ?? "unknown error"}); falling back to a prompt.`);
+						} catch {}
+						const sessionPrompt = ctx.session as unknown as {
+							prompt: (input: { sessionID: string; text: string }) => Promise<unknown>;
+						};
+						await sessionPrompt.prompt({ sessionID, text: `Report this guard status verbatim:\n\n${report}` });
+					}
+				});
+			},
+		});
+	});
+}

package/src/lib/guard-dispatcher.ts

@@ -8,6 +8,7 @@ import {
 	getLiveControlPlaneRoots,
 	getSdkClient,
 	getSessionBoundWorkspace,
+	getSessionMutationCount,
 	getWorkspaceRoot,
 	isDocumentationRequired,
 	isReviewRequired,
@@ -17,6 +18,7 @@ import {
 	recordVerifyResult,
 	sessionMutationTimestamps,
 	sessionVerifyResults,
+	todoTaskStarts,
 } from "./state.ts";
 import {
 	dynamicShellSyntaxIn,
@@ -74,9 +76,14 @@ import {
 	effectiveTodos,
 	fetchSessionTodos,
 	hasActiveTodo,
+	readOnlyTodoCompletions,
+	recordTodoTaskStarts,
 	subagentMutationBudgetReason,
+	todoCompletionBlockReason,
+	unverifiedTodoCompletions,
 	validateTodoLifecycle,
 } from "../policies/todo.ts";
+import { recordedTodoCapability, reportTodoGateFailOpen } from "./v2-todo.ts";
 
 export const SHELL_TOOL_NAMES = new Set(["bash", "run_commands", "execute_command", "shell"]);
 
@@ -192,6 +199,22 @@ export async function guardToolCallImpl(
 				logPolicyBlock(`[workflow-guard] ${err}`);
 				return block("todo", "todo_lifecycle", err);
 			}
+			// Per-task completion evidence. Every task may enter `completed`
+			// only after the session mutated inside that task's window. The
+			// check is pure, so simulation reports the same verdict without
+			// journaling or moving any window.
+			const readOnlyCompleted: string[] = [];
+			if (context?.sessionID) {
+				const starts = todoTaskStarts(context.sessionID);
+				const total = getSessionMutationCount(context.sessionID);
+				const unverified = unverifiedTodoCompletions(existingTodos, newTodos, starts, total);
+				if (unverified.length > 0) {
+					const reason = todoCompletionBlockReason(unverified);
+					logPolicyBlock(`[workflow-guard] ${reason}`);
+					return block("todo", "todo_completion_unverified", reason);
+				}
+				if (!context.simulate) readOnlyCompleted.push(...readOnlyTodoCompletions(existingTodos, newTodos));
+			}
 			const allDone = newTodos.length > 0 && newTodos.every((t) => {
 				const s = String(t.status ?? "");
 				return s === "completed" || s === "cancelled";
@@ -227,6 +250,22 @@ export async function guardToolCallImpl(
 					}
 				}
 			}
+			// Only an accepted write becomes the task list, so task windows move
+			// and read-only marker use is journaled after every gate has passed.
+			if (context?.sessionID && !context.simulate) {
+				recordTodoTaskStarts(todoTaskStarts(context.sessionID), existingTodos, newTodos, getSessionMutationCount(context.sessionID));
+				if (readOnlyCompleted.length > 0) {
+					audit({
+						ts: new Date().toISOString(),
+						sessionID: context.sessionID,
+						tool: "todowrite",
+						decision: "allow",
+						phase: "event",
+						reason: "todo_completed_read_only",
+						input: { tasks: readOnlyCompleted, mutationCount: getSessionMutationCount(context.sessionID) },
+					});
+				}
+			}
 		}
 		return allow();
 	}
@@ -309,6 +348,23 @@ export async function guardToolCallImpl(
 			logPolicyBlock(`[workflow-guard] blocked ${toolName}: no active todo item (session ${context?.sessionID ?? "?"})`);
 			return block("todo", "no_active_todo", "Blocked: no active todo item. First break the request down with the todowrite tool (create items with status 'pending' or 'in_progress'), then work them through, marking each completed via todowrite as you finish it. When every item is completed, create a fresh todo list before starting new work.");
 		}
+		if (todos === undefined) {
+			// Fail-open, but never silent: once per session, record that the
+			// gate did not enforce and why. A rails policy that quietly stops
+			// enforcing is indistinguishable from one that was removed.
+			const capability = recordedTodoCapability();
+			if (reportTodoGateFailOpen(context?.sessionID, capability)) {
+				audit({
+					ts: new Date().toISOString(),
+					sessionID: context?.sessionID,
+					tool: "todo.gate",
+					decision: "allow",
+					phase: "event",
+					reason: `todo_gate_fail_open_${capability}`,
+					input: { [toolName]: true },
+				});
+			}
+		}
 		if (context?.sessionID) {
 			const reason = await subagentMutationBudgetReason(context.sessionID, currentRoot);
 			if (reason) {

package/src/lib/host-worktree.ts

@@ -0,0 +1,109 @@
+/**
+ * Host worktree port for the V2 native worktree API.
+ *
+ * The guard hand-rolls `git worktree add` and keeps its own storage directory,
+ * so worktrees it creates are invisible to the host's worktree inventory. The
+ * V2 API exposes `ctx.worktree` with `create`, `list`, `remove`, and `refresh`.
+ *
+ * Adoption is deliberately asymmetric, because the two paths do not carry the
+ * same guarantees:
+ *
+ * - **create** goes through the host first, so the worktree lands where the
+ *   operator configured `worktree.directory` and appears in host inventory.
+ *   The result is validated before it is accepted: the directory must exist,
+ *   must be a worktree of THIS repository, and must not be the primary tree.
+ *   Any failure falls back to the git implementation.
+ * - **remove** stays with the guard. The host's `remove` takes a `force` flag
+ *   and has no snapshot step, so it can destroy uncommitted work that the
+ *   guard's snapshot-then-remove flow preserves. After the guard removes a
+ *   worktree, the port calls `refresh` so host inventory does not keep a
+ *   stale entry.
+ * - **list** supplies the bounded, host-declared set of directories that
+ *   cleanup may touch. This is the same widening authority Task 3 gave
+ *   `hostWorktree`: the host says the directory is its worktree, and the
+ *   guard still independently requires a git registration and a non-primary
+ *   path.
+ *
+ * Unknown or unavailable host surfaces degrade to `undefined`, never to a
+ * guess. The git path stays the only authority for correctness.
+ */
+
+/** Narrow, duck-typed view of `ctx.worktree` so this module stays testable. */
+export interface HostWorktreeApi {
+	create(input: { projectID: string; branch?: string; from?: string; name?: string; directory?: string }): Promise<{ directory?: string } | undefined>;
+	list(input: { projectID: string }): Promise<ReadonlyArray<{ directory?: string }> | undefined>;
+	refresh(input: { projectID: string }): Promise<unknown>;
+}
+
+export interface HostWorktreePort {
+	/** True when the host exposes a usable project id and the create/list calls. */
+	readonly available: boolean;
+	/** Project id used for every call, or undefined when the host did not supply one. */
+	readonly projectID: string | undefined;
+	/**
+	 * Create a worktree. `from` is an absolute DIRECTORY path, matching the host
+	 * schema, not a git ref; callers that need a specific base ref use the git
+	 * path instead of passing a ref here.
+	 */
+	create(input: { branch: string; from?: string }): Promise<{ directory?: string; error?: string }>;
+	list(): Promise<readonly string[] | undefined>;
+	refresh(): Promise<void>;
+}
+
+const unavailable: HostWorktreePort = {
+	available: false,
+	projectID: undefined,
+	create: async () => ({ error: "host worktree API unavailable" }),
+	list: async () => undefined,
+	refresh: async () => {},
+};
+
+/**
+ * Build the port from a V2 plugin context. A missing API, a missing project id,
+ * or a throwing call all downgrade to the git path instead of failing the tool.
+ */
+export function createHostWorktreePort(ctx: unknown): HostWorktreePort {
+	const context = ctx as {
+		location?: { project?: { id?: unknown } };
+		worktree?: Partial<HostWorktreeApi>;
+	} | undefined;
+	const api = context?.worktree;
+	const rawProjectID = context?.location?.project?.id;
+	const projectID = typeof rawProjectID === "string" && rawProjectID.length > 0 ? rawProjectID : undefined;
+	if (!api || typeof api.create !== "function" || typeof api.list !== "function" || !projectID) {
+		return unavailable;
+	}
+	const create = api.create.bind(api);
+	const list = api.list.bind(api);
+	const refresh = typeof api.refresh === "function" ? api.refresh.bind(api) : undefined;
+	return {
+		available: true,
+		projectID,
+		create: async ({ branch, from }) => {
+			try {
+				const result = await create({ projectID, branch, ...(from ? { from } : {}), name: branch.replace(/[/\\:]/g, "-") });
+				const directory = typeof result?.directory === "string" && result.directory.length > 0 ? result.directory : undefined;
+				return directory ? { directory } : { error: "host worktree create returned no directory" };
+			} catch (error) {
+				return { error: `host worktree create failed: ${(error as Error)?.message ?? String(error)}` };
+			}
+		},
+		list: async () => {
+			try {
+				const result = await list({ projectID });
+				if (!Array.isArray(result)) return undefined;
+				return result
+					.map((entry) => (typeof entry?.directory === "string" ? entry.directory : undefined))
+					.filter((directory): directory is string => Boolean(directory));
+			} catch {
+				return undefined;
+			}
+		},
+		refresh: async () => {
+			if (!refresh) return;
+			try {
+				await refresh({ projectID });
+			} catch {}
+		},
+	};
+}