opencode-workflow-guard 1.13.1 → 1.13.3

package/docs/installation.md

@@ -27,12 +27,12 @@ OpenCode 2 documents `opencode plugin add <package>` as the command to install a
 
 Use the same two commands to upgrade after a Workflow Guard release. Keep the explicit version in OpenCode's configuration rather than relying on a bare package name or `@latest`: OpenCode caches npm plugins, and an already-populated `@latest` cache key may continue resolving to the version that originally populated it. An explicit new version creates a new package-cache key without manually deleting OpenCode's cache.
 
-If you only want the server guard without the TUI companion, add the package to your project's `opencode.json` (or global `~/.config/opencode/opencode.json`):
+If you only want the server guard without the TUI companion, add the package to your project's `opencode.json` (or global `~/.config/opencode/opencode.json`). OpenCode 2 uses the plural `plugins` key; OpenCode 1.x uses the singular `plugin` key (V2 normalizes the singular form in memory, but the native shape is `plugins`):
 
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": [
+  "plugins": [
     "opencode-workflow-guard"
   ]
 }
@@ -61,17 +61,31 @@ OpenCode automatically discovers the adapter from the project-level `.opencode/p
 
 To enable the static `Workflow Guard 🛡️` prompt-bar badge, with block details reported separately through warning toasts:
 
-The recommended `opencode plugin "opencode-workflow-guard@$VERSION" --global --force` command configures this automatically. For manual installation, use the same explicit package version in `~/.config/opencode/tui.json`:
+The recommended `opencode plugin add "opencode-workflow-guard@$VERSION"` command configures this automatically: OpenCode detects both targets and registers the server plugin in the global `opencode.json(c)` and the TUI companion in the global `~/.config/opencode/cli.json` (OpenCode 2). For manual installation, use the same explicit package version in the TUI target of your OpenCode generation - global `~/.config/opencode/cli.json` with the `plugins` array on OpenCode 2:
+
+```json
+{
+  "$schema": "https://opencode.ai/v2/cli.json",
+  "plugins": [
+    "opencode-workflow-guard@1.13.2"
+  ]
+}
+```
+
+or `~/.config/opencode/tui.json` with the `plugin` array on OpenCode 1.x:
+
 ```json
 {
   "$schema": "https://opencode.ai/tui.json",
   "plugin": [
-    "opencode-workflow-guard@1.7.2"
+    "opencode-workflow-guard@1.13.2"
   ]
 }
 ```
 
-The version above is illustrative; replace it with the version you intend to install. The package exposes separate server and TUI entrypoints. In `tui.json`, configure the package spec; OpenCode resolves its exported `./tui` entrypoint automatically. Do not place `workflow-guard-ui.ts` under `plugins/`; the server loader rejects TUI-only modules.
+The version above is illustrative; replace it with the version you intend to install. The package exposes separate server and TUI entrypoints. In the terminal-client config, configure the package spec; OpenCode resolves its exported `./tui` entrypoint automatically. Do not place `workflow-guard-ui.ts` under `plugins/`; the server loader rejects TUI-only modules.
+
+On OpenCode 2, `plugin check` and `plugin update` cover both server and TUI-only package plugins.
 
 The TUI badge uses OpenCode's Solid slot API (`@opentui/solid`). It is a runtime `dependency` of this package, so npm installs it automatically alongside `opencode-workflow-guard` - no extra install is needed.
 
@@ -127,7 +141,20 @@ Or set `WORKFLOW_GUARD_REQUIRE_REVIEW=0` in your environment. Conversely, `WORKF
 
 ## Recommended Companion Configuration
 
-For defense in depth, pair `opencode-workflow-guard` with OpenCode's native permission rules in `opencode.json` (see [OpenCode Permissions](https://opencode.ai/docs/permissions/)):
+For defense in depth, pair `opencode-workflow-guard` with OpenCode's native permission rules (see [OpenCode Permissions](https://opencode.ai/docs/permissions/)). OpenCode 2 uses one ordered `permissions` array (`bash` actions are named `shell` in V2):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permissions": [
+    { "action": "shell", "resource": "git push *main*", "effect": "deny" },
+    { "action": "shell", "resource": "git push *master*", "effect": "deny" },
+    { "action": "shell", "resource": "opencode auth*", "effect": "deny" }
+  ]
+}
+```
+
+OpenCode 1.x groups rules by tool under the singular `permission` key:
 
 ```json
 {

package/docs/policies.md

@@ -9,7 +9,7 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 ## Policy Reference
 
 ### 1. Task Breakdown & Lifecycle (`todowrite`)
-- **Pre-edit Gate:** All file-editing tools (`edit`, `write`, `apply_patch`) are blocked until the session has an active task list in OpenCode's native todo system (`todowrite`, persisted at `GET /session/:id/todo`).
+- **Pre-edit Gate:** All file-editing tools (`edit`, `write`, `apply_patch`) are blocked while the session's effective todo list is known and contains no active task. On OpenCode 1.x the list comes from the native todo system (`todowrite`, persisted at `GET /session/:id/todo`). On OpenCode 2.x there is no todo endpoint and no builtin `todowrite`, so the list is reconstructed from the newest applied `todowrite` tool call in the session history (ACP agents may supply that tool). The gate distinguishes a **definitively empty** list (a `todowrite` part exists and reports no active task → still blocked) from an **undeterminable** one (no `todowrite` part exists at all, i.e. no todo capability, or the history cannot be read → the gate fails open). This keeps builtin-only V2 sessions usable instead of deadlocking every edit forever.
 - **Flexible Task Execution:** Tasks can be completed in any order as work concludes without artificial sequential blockers, maintaining maximum pair-programming DX.
 - **No Silent Deletion:** Each `todowrite` update replaces the complete list. Active tasks must remain in subsequent updates until they are explicitly marked `completed` or `cancelled`.
 - **No Silent Early Exit:** When an owning session becomes `session.idle` with unfinished native todos, the guard asynchronously asks OpenCode to resume the existing run. This enforces the session's existing lifecycle state: Workflow Guard does not choose the next task, reorder work, create work, or delegate it. Ordinary automatic continuations are capped at three consecutive attempts and the budget resets on genuine user input. User-initiated interrupts (Esc) surface as `MessageAbortedError` and suspend automatic continuation for that session until genuine user input arrives, mirroring the ralph `user_stopped` semantics. The independently opt-in `ralphMode` uses `ralphMaxIterations` (1-100, default 10) instead; genuine user input terminates an active Ralph run, and unfinished work at the budget limit reports `budget_exhausted` rather than inferring a policy block. Ralph remains disabled by default under every operation profile. Use OpenCode's native `question` tool when user feedback or a decision is required; question and permission interactions wait inside the active run rather than producing an idle completion.
@@ -72,6 +72,7 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 ### 8. Workspace Boundary Guard
 - File modification tools (`edit`, `write`, `apply_patch`) and recognized shell mutations (redirection `>`, `>>`, `&>`, `>&`, `tee`, `sed -i`, `cp`/`mv`/`ln`, `touch`, `mkdir`, `rm`, `truncate`, `dd of=`, `git apply`/`git am`) are validated to ensure detected targets cannot escape the current workspace root via `../` traversal, symlinks, absolute paths, or shell expansions (`~`, `~user`, `$HOME`). Unresolvable `$VARIABLE` references fail closed. This is command-level enforcement, not filesystem sandboxing; arbitrary programs and dynamically computed paths require the OS isolation described under Known Limits.
 - `tee` flag parsing generically skips option flags (`-a`, `--append`, `-ai`, `--`) and validates all specified target files against the boundary.
+- Embedded non-shell comparisons are not mutations: a bare `>` whose target is purely numeric (`WHERE count > 5`, awk `$3 > 100`) and `>=`/`==` operators are treated as comparison operands, not redirects. Real redirects are unaffected (`> src/a.ts`, `>>`, `&>`, `>&`, fd targets like `/dev/null` still follow their existing rules).
 - `mv` sources are validated too: moving a file from outside the workspace (or a protected settings/plugin file to an innocuous name) is blocked, since `mv` mutates the source.
 - External repository git writes (`git -C /other-repo commit`, `git --git-dir=/other-repo/.git push`, `GIT_DIR=/other-repo/.git git push`, `GIT_WORK_TREE=...`) are also confined to the workspace.
 - The boundary has **no override**: `WORKFLOW_GUARD_ALLOW_LIVE=1` covers live-system commands only and never weakens the workspace confinement.

package/docs/troubleshooting.md

@@ -15,8 +15,8 @@ Common issues, root causes, and solutions when using `opencode-workflow-guard`.
 ### 2. Edits Blocked: `Blocked: no active todo item`
 
 - **Symptoms:** The agent attempts an edit (`edit`, `write`, `apply_patch`) and receives a block message directing it to create a task list.
-- **Root Cause:** Policy 1 blocks file-editing tools until the session's native todo list (`GET /session/:id/todo`) contains at least one task with status `pending` or `in_progress`.
-- **Solution:** The agent must call `todowrite` first. Once all tasks are marked `completed` or `cancelled`, edits will block again until a new breakdown is created for subsequent work.
+- **Root Cause:** Policy 1 blocks file-editing tools while the session's **effective** todo list is known and contains no task with status `pending` or `in_progress`. On OpenCode 1.x that list is the native todo state (`GET /session/:id/todo`). On OpenCode 2.x there is no todo endpoint and no builtin `todowrite`, so the list is reconstructed from the newest applied `todowrite` tool call in the session history (some ACP agents supply that tool). A list is only treated as empty when a `todowrite` part actually exists; when the session has no `todowrite` capability at all, the gate fails open rather than blocking every edit forever.
+- **Solution:** The agent must call `todowrite` first. Once all tasks are marked `completed` or `cancelled`, edits will block again until a new breakdown is created for subsequent work. If an agent on OpenCode 2.x is blocked here despite having no todo tool available, that is a bug - report it rather than working around it through shell writes.
 
 ---
 
@@ -82,3 +82,21 @@ opencode plugin "opencode-workflow-guard@$VERSION" --global --force
 OpenCode documents `opencode plugin <module>` as installing a plugin and updating its config, with `--global` for global config and `--force` to replace an existing plugin version: https://opencode.ai/docs/cli/#plugin. Its plugin documentation also describes npm plugins as OpenCode-managed, cached installations: https://opencode.ai/docs/plugins/#how-plugins-are-installed.
 
 After the command reports `Detected server + tui targets`, confirm it reports replacements/additions for both the OpenCode and TUI config files, then restart OpenCode. Manual cache deletion should not be necessary.
+
+---
+
+### 10. TUI companion crashes with `Keymap.Provider is missing` (OpenCode V2)
+
+- **Symptoms:** On opencode v2, the TUI companion plugin fails during setup with `Keymap.Provider is missing` and does not load.
+- **Root Cause:** `ctx.keymap.layer` resolves a Solid context (`useContext(KeymapContext)`) and only works inside the TUI's `Keymap.Provider` render tree; the API documents layers as "owned by the calling component". Plugin `setup()` runs as a plain async call outside that tree, so registering a layer there always throws.
+- **Solution:** Fixed in 1.13.2: the layer is registered from an `app`-slot claim (`ctx.ui.slot({ append: "app", render: () => { ...; return null } })`). Slot renders execute in a reactive scope under the provider, and the same session-panel pattern applies to any plugin API that requires component ownership. If you maintain a TUI plugin that registers keymap layers, commands, or reactive state, register them from a slot render (or a rendered component), never from `setup()`.
+
+---
+
+### 11. Reading tool parts from V2 sessions (integrators)
+
+- **Symptoms:** Code that parses recorded tool calls (message parts, the `part` DB table, or `session.message.content.updated` events) finds no tool name on OpenCode V2, or sees tool names that do not exist in OpenCode's builtin tool list.
+- **Root Cause:** Two independent things:
+  1. V2 message parts record the tool name in the `tool` field; V1 used `name`. Code reading `part.name` silently gets `undefined` on V2.
+  2. V2's builtin tool registry contains only `read`, `glob`, `grep`, `edit`, `write`, `patch`, `shell`, `webfetch`, `websearch`, `question`, `skill`, `subagent`, and `execute`. There is no builtin `todowrite` (the V1 name), and the V1 `task` subagent tool was renamed to `subagent`. `todowrite`/`bash` tool parts observed in V2 sessions come from ACP agents (for example pi) that supply their own tools; those tools are not in the server-side registry and cannot be reached by `ctx.tool.transform`.
+- **Solution:** Read the tool name as `part.tool ?? part.name` and treat tool-part names as agent-reported, not as the builtin registry. `ToolEditor.update` ignores missing IDs, so enriching a tool that does not exist is a harmless no-op.

package/package.json

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

package/src/lib/v2-plugin.ts

@@ -19,7 +19,8 @@ import { Plugin } from "@opencode/plugin";
 import { Message } from "@opencode/ai";
 import { z } from "zod";
 import { join, resolve } from "node:path";
-import type { TodoItem, TodoSdkClient } from "./types.ts";
+import type { TodoSdkClient } from "./types.ts";
+import { scanSessionTodos, toolPartName } from "./v2-todo.ts";
 import { findGitRoot, reloadProjectConfig } from "./project-config.ts";
 import {
 	setWorkspaceRoot,
@@ -66,32 +67,9 @@ type V2Context = Plugin.Context;
 
 // ── V1 SDK client adapter ─────────────────────────────────────────────────────
 
-/**
- * Reconstruct the current todo list for a session from the session message
- * history (V2 exposes no dedicated todo endpoint). The newest applied
- * `todowrite` tool call's input is the current state.
- */
-async function fetchTodosFromContext(ctx: V2Context, sessionID: string): Promise<TodoItem[] | undefined> {
-	try {
-		const messages = (await ctx.session.context({ sessionID })) as unknown as Array<{ content?: unknown }>;
-		for (let i = messages.length - 1; i >= 0; i--) {
-			const content = (messages[i] as { content?: unknown })?.content;
-			if (!Array.isArray(content)) continue;
-			for (let j = content.length - 1; j >= 0; j--) {
-				const part = content[j] as { type?: string; name?: string; state?: { status?: string; input?: { todos?: unknown } } };
-				if (part?.type !== "tool" || typeof part.name !== "string") continue;
-				if (!/^todowrite$/i.test(part.name)) continue;
-				const status = part.state?.status;
-				if (status === "pending" || status === "streaming" || status === "running") continue;
-				const todos = part.state?.input?.todos;
-				if (Array.isArray(todos)) return todos as TodoItem[];
-			}
-		}
-		return [];
-	} catch {
-		return undefined;
-	}
-}
+// V2 has no todo endpoint; `scanSessionTodos` reconstructs one session's list
+// from message history and distinguishes "empty" from "unknown" (no todo
+// capability) so builtin-only sessions are not gated forever. See v2-todo.ts.
 
 function createV2SdkClient(ctx: V2Context): TodoSdkClient {
 	// V2 has no server-side log API or TUI surface, so app.log degrades to
@@ -107,7 +85,7 @@ function createV2SdkClient(ctx: V2Context): TodoSdkClient {
 			},
 		},
 		session: {
-			todo: async ({ path }) => ({ data: await fetchTodosFromContext(ctx, path.id) }),
+			todo: async ({ path }) => ({ data: await scanSessionTodos(ctx, path.id) }),
 			get: async ({ path }) => {
 				const session = await ctx.session.get({ sessionID: path.id });
 				return { data: { parentID: (session as { parentID?: string }).parentID, title: (session as { title?: string }).title } };
@@ -137,6 +115,18 @@ const EDIT_SUFFIX =
 const SUBAGENT_SUFFIX =
 	"\n\nWorkflow Guard subagent guidance: When spawning parallel worker subagents, use guard_worktree_create to isolate file mutations in separate worktrees. When conducting code reviews before task completion or PR creation, fetch the rubric with guard_review_rubric and provide it to a reviewer subagent to evaluate and record via record_review.";
 
+// Builtin tool description enrichment. Candidates are matched against the
+// host's tool registry; `ToolEditor.update` ignores missing IDs, so extra
+// candidates are harmless no-ops.
+//
+// V2.0.10 builtin surface (docs + binary): read, glob, grep, edit, write,
+// patch, shell, webfetch, websearch, question, skill, subagent, execute.
+// - There is no builtin `todowrite` (the V1 name). Todowrite tool parts seen
+//   in V2 sessions come from ACP agents that supply their own tools; those
+//   are not in the server registry, so this enrichment cannot reach them.
+//   The candidate is kept for hosts that do register a todowrite tool.
+// - The V1 subagent tool `task` was renamed to `subagent`; both are kept as
+//   candidates for the same reason.
 const ENRICHMENT_TARGETS: Array<{ candidates: string[]; suffix: string; marker: string }> = [
 	{ candidates: ["todowrite"], suffix: TODOWRITE_SUFFIX, marker: "verification evidence" },
 	{ candidates: [...EDIT_TOOL_NAMES], suffix: EDIT_SUFFIX, marker: "Workflow Guard requirement" },
@@ -514,7 +504,7 @@ async function handleV2Event(
 				type: "tool",
 				sessionID,
 				callID: part.id,
-				tool: part.name,
+				tool: toolPartName(part),
 				state: {
 					status,
 					error: typeof toolState?.error === "string" ? toolState.error : toolState?.error?.message,

package/src/lib/v2-todo.ts

@@ -0,0 +1,76 @@
+/**
+ * V2 todo reconstruction shared by the plugin entrypoint and its V1 SDK
+ * adapter.
+ *
+ * OpenCode V2 exposes no todo endpoint, and its builtin tool registry has no
+ * `todowrite` (the V1 name). Todo state therefore only exists when an ACP agent
+ * supplies its own `todowrite` tool. This module reads that state from session
+ * message history and distinguishes "definitively empty" from "cannot
+ * determine", which the policy layer relies on to decide whether to enforce the
+ * active-todo gate.
+ */
+
+import type { TodoItem } from "./types.ts";
+
+/** Minimal session-context surface needed to read message history. */
+export interface TodoScanContext {
+	session: {
+		context: (input: { sessionID: string }) => Promise<unknown>;
+	};
+}
+
+/**
+ * V2 tool parts carry the tool name in `tool` (the V1 field was `name`); ACP
+ * agents may still report either shape, so accept both.
+ */
+export function toolPartName(part: { tool?: unknown; name?: unknown }): string | undefined {
+	if (typeof part.tool === "string") return part.tool;
+	if (typeof part.name === "string") return part.name;
+	return undefined;
+}
+
+/**
+ * Reconstruct one session's current todo list from its message history. The
+ * newest applied `todowrite` tool call's input is the current state.
+ *
+ * Returns:
+ * - `TodoItem[]` when a `todowrite` part defines the list, including `[]` when
+ *   the newest applied call emptied it;
+ * - `undefined` when todo state is unknown: the history cannot be read, or the
+ *   session contains no `todowrite` part at all (no todo capability).
+ *
+ * Callers must treat `undefined` as "cannot determine" (fail open) and `[]` as
+ * "definitively no active todos" (enforce). Collapsing the two is what
+ * deadlocks builtin-only V2 sessions, which can never create a todo.
+ */
+export async function scanSessionTodos(
+	ctx: TodoScanContext,
+	sessionID: string,
+): Promise<TodoItem[] | undefined> {
+	try {
+		const messages = (await ctx.session.context({ sessionID })) as unknown as Array<{ content?: unknown }>;
+		if (!Array.isArray(messages)) return undefined;
+		let sawTodoWrite = false;
+		for (let i = messages.length - 1; i >= 0; i--) {
+			const content = (messages[i] as { content?: unknown })?.content;
+			if (!Array.isArray(content)) continue;
+			for (let j = content.length - 1; j >= 0; j--) {
+				const part = content[j] as { type?: string; tool?: unknown; name?: unknown; state?: { status?: string; input?: { todos?: unknown } } };
+				if (part?.type !== "tool") continue;
+				const toolName = toolPartName(part);
+				if (toolName === undefined || !/^todowrite$/i.test(toolName)) continue;
+				sawTodoWrite = true;
+				const status = part.state?.status;
+				if (status === "pending" || status === "streaming" || status === "running") continue;
+				const todos = part.state?.input?.todos;
+				if (Array.isArray(todos)) return todos as TodoItem[];
+			}
+		}
+		// A `todowrite` part exists but none is applied yet (e.g. still
+		// streaming): the list is in flux, report it as empty rather than
+		// unknown so the gate stays closed until the write settles.
+		return sawTodoWrite ? [] : undefined;
+	} catch {
+		return undefined;
+	}
+}

package/src/policies/boundary.ts

@@ -129,14 +129,22 @@ export function teeTargetsIn(segment: string): string[] {
 
 function redirectMutationsIn(segment: string): ShellMutation[] {
 	const mutations: ShellMutation[] = [];
-	const redirectRe = /(?:^|[\s>]|(?<=[^\s"']))([0-9]*&?>>?&?)\s*["']?([^\s>&|;"']+)/g;
+	// The `(?!=)` lookahead after the op rejects comparison operators (`>=`,
+	// `==`) so they cannot match as a redirect op with `=` as its target.
+	const redirectRe = /(?:^|[\s>]|(?<=[^\s"']))([0-9]*&?>>?&?(?!=))\s*["']?([^\s>&|;"']+)/g;
 	for (const redirectMatch of segment.matchAll(redirectRe)) {
 		if (!redirectMatch[1] || !redirectMatch[2]) continue;
 		const op = redirectMatch[1];
 		const target = redirectMatch[2];
 		// Filter fd duplication (e.g. 2>&1, >&2) where target is purely an fd number
 		const isFdDup = op.endsWith("&") && /^\d+$/.test(target);
-		if (!isFdDup && !/^\/dev\/(?:null|stdout|stderr|tty|fd\/\d+)$/.test(target)) {
+		// Filter comparison operands from embedded non-shell syntax (SQL, awk,
+		// test expressions): `WHERE count > 5`, `x >= 10`. A bare `>` whose
+		// target is purely numeric is overwhelmingly a comparison operand, not
+		// a redirect into a numeric filename. `>>` and fd forms (`2>`) keep
+		// redirect semantics.
+		const isComparisonOperand = op === ">" && /^\d+$/.test(target);
+		if (!isFdDup && !isComparisonOperand && !/^\/dev\/(?:null|stdout|stderr|tty|fd\/\d+)$/.test(target)) {
 			mutations.push({
 				kind: "redirect",
 				target,

package/src/policies/todo.ts

@@ -62,13 +62,23 @@ export async function effectiveTodosWithOwner(
 	if (!sessionID) return undefined;
 	const seen = new Set<string>();
 	let current: string | undefined = sessionID;
+	let sawUnknown = false;
 	while (current && !seen.has(current)) {
 		seen.add(current);
 		const todos = await fetchSessionTodos(current);
-		if (todos === undefined) return undefined;
-		if (todos.length > 0) return { todos, ownerSessionID: current };
+		if (todos === undefined) {
+			// This link has no determinable list (no todo capability, read
+			// error, or no endpoint). Do not treat it as empty and do not stop
+			// the walk: a parent may still own an applicable list, and keeping
+			// the walk going preserves evidence attribution to that owner. An
+			// unknown link only fails open if no ancestor provides a list.
+			sawUnknown = true;
+		} else if (todos.length > 0) {
+			return { todos, ownerSessionID: current };
+		}
 		current = await fetchParentSessionID(current);
 	}
+	if (sawUnknown) return undefined;
 	return { todos: [] };
 }
 

package/src/workflow-guard-ui.ts

@@ -105,48 +105,64 @@ export const WorkflowGuardTuiV2 = (ctx: TuiContext) => {
 
 	const optionsRoot = () => ctx.location?.directory || process.cwd();
 
-	ctx.keymap.layer(() => ({
-		commands: [{
-			id: "workflow-guard.project-options",
-			title: "Workflow Guard: Project Options",
-			description: "Toggle Workflow Guard project options (recovery checkpoints, project memory, learning, title settle, ralph mode)",
-			group: "Workflow Guard",
-			palette: true,
-			slash: { name: "guard-options" },
-			async run() {
-				const root = optionsRoot();
-				for (;;) {
-					const current = new Map(TOGGLE_OPTIONS.map((option) => [option.key, readProjectOption(root, option.key)]));
-					const choice = await ctx.ui.dialog.select<ProjectToggle>({
-						title: "Workflow Guard Project Options",
-						options: TOGGLE_OPTIONS.map((option) => ({
-							title: `${option.label}: ${current.get(option.key) ? "On" : "Off"}`,
-							value: option.key,
-							description: option.description,
-						})),
-					});
-					if (!choice) break;
-					try {
-						const enabled = !readProjectOption(root, choice);
-						const path = writeProjectOption(root, choice, enabled);
-						ctx.ui.toast.show({
-							variant: "success",
-							title: "Workflow Guard",
-							message: `Saved ${choice} ${enabled ? "on" : "off"} in ${path}. Restart OpenCode to apply.`,
-						});
-					} catch (error) {
-						ctx.ui.toast.show({
-							variant: "error",
-							title: "Workflow Guard",
-							message: error instanceof Error ? error.message : String(error),
-						});
-						break;
-					}
-				}
-			},
-		}],
-		bindings: [],
-	}));
+	// `ctx.keymap.layer` creates a layer owned by the calling component and only
+	// resolves inside the TUI's provider render tree; plugin setup() runs as a
+	// plain async call outside it. Slot renders execute in a reactive scope under
+	// the provider, so the layer is registered from an app-slot claim instead.
+	// The guard keeps repeated renders from stacking duplicate layers; layers and
+	// slot claims are disposed automatically on unload.
+	let keymapLayerRegistered = false;
+	ctx.ui.slot({
+		append: "app",
+		render: () => {
+			if (!keymapLayerRegistered) {
+				keymapLayerRegistered = true;
+				ctx.keymap.layer(() => ({
+					commands: [{
+						id: "workflow-guard.project-options",
+						title: "Workflow Guard: Project Options",
+						description: "Toggle Workflow Guard project options (recovery checkpoints, project memory, learning, title settle, ralph mode)",
+						group: "Workflow Guard",
+						palette: true,
+						slash: { name: "guard-options" },
+						async run() {
+							const root = optionsRoot();
+							for (;;) {
+								const current = new Map(TOGGLE_OPTIONS.map((option) => [option.key, readProjectOption(root, option.key)]));
+								const choice = await ctx.ui.dialog.select<ProjectToggle>({
+									title: "Workflow Guard Project Options",
+									options: TOGGLE_OPTIONS.map((option) => ({
+										title: `${option.label}: ${current.get(option.key) ? "On" : "Off"}`,
+										value: option.key,
+										description: option.description,
+									})),
+								});
+								if (!choice) break;
+								try {
+									const enabled = !readProjectOption(root, choice);
+									const path = writeProjectOption(root, choice, enabled);
+									ctx.ui.toast.show({
+										variant: "success",
+										title: "Workflow Guard",
+										message: `Saved ${choice} ${enabled ? "on" : "off"} in ${path}. Restart OpenCode to apply.`,
+									});
+								} catch (error) {
+									ctx.ui.toast.show({
+										variant: "error",
+										title: "Workflow Guard",
+										message: error instanceof Error ? error.message : String(error),
+									});
+									break;
+								}
+							}
+						},
+					}],
+					bindings: [],
+				}));
+			}
+			return null;
+		},
+	});
 
 	ctx.ui.slot({ append: "home.footer.status", render: () => badge() });
 	ctx.ui.slot({ append: "prompt.footer.status", render: () => badge() });

package/test/test.mts

@@ -115,6 +115,8 @@ import { isProjectMemoryFreshAsync } from "../src/lib/project-memory.ts";
 import { ToolOutcomeTracker } from "../src/lib/tool-outcomes.ts";
 import { createRecoveryCheckpoint, finalizeRecoveryCheckpoint, listRecoveryCheckpoints, restoreRecoveryCheckpoint, setCheckpointGitForTesting } from "../src/lib/checkpoint.ts";
 import { WorkflowGuardTui, formatBadge, readProjectOption, readRecoveryCheckpointsOption, writeRecoveryCheckpointsOption } from "../src/workflow-guard-ui.ts";
+import { scanSessionTodos, toolPartName } from "../src/lib/v2-todo.ts";
+import { effectiveTodosWithOwner } from "../src/policies/todo.ts";
 
 let pass = 0;
 let fail = 0;
@@ -244,6 +246,95 @@ check("missing client fails open", !(await call("edit", { filePath: join(root, "
 check("missing sessionID fails open", !(await call("edit", { filePath: join(root, "a.ts"), content: "x" })));
 setSdkClient(fakeClient);
 
+console.log("- Policy 1: V2 todo reconstruction (no todo capability vs empty list) -");
+const todoPart = (todos: unknown, status = "completed") => ({
+	content: [{ type: "tool", tool: "todowrite", state: { status, input: { todos } } }],
+});
+const ctxWith = (messages: unknown) => ({ session: { context: async () => messages } });
+
+check(
+	"V2: history with no todowrite part reports unknown (no todo capability)",
+	(await scanSessionTodos(ctxWith([{ content: [{ type: "tool", tool: "edit", state: { status: "completed" } }] }]), "s-v2")) === undefined,
+);
+const scanned = await scanSessionTodos(ctxWith([todoPart([item("a", "pending")])]), "s-v2");
+check("V2: completed todowrite defines the list", Array.isArray(scanned) && scanned.length === 1 && scanned[0]!.content === "a");
+const newest = await scanSessionTodos(ctxWith([todoPart([item("old")]), todoPart([item("new", "in_progress")])]), "s-v2");
+check("V2: newest applied todowrite wins", Array.isArray(newest) && newest[0]!.content === "new");
+const emptied = await scanSessionTodos(ctxWith([todoPart([])]), "s-v2");
+check("V2: emptied todowrite reports a definitive empty list", Array.isArray(emptied) && emptied.length === 0);
+check("V2: read rejection reports unknown", (await scanSessionTodos({ session: { context: async () => { throw new Error("boom"); } } }, "s-v2")) === undefined);
+const legacy = await scanSessionTodos(ctxWith([{ content: [{ type: "tool", name: "todowrite", state: { status: "completed", input: { todos: [item("legacy")] } } }] }]), "s-v2");
+check("V2: legacy name field is still accepted", Array.isArray(legacy) && legacy[0]!.content === "legacy");
+const inFlight = await scanSessionTodos(ctxWith([todoPart([item("x")], "pending")]), "s-v2");
+check("V2: in-flight todowrite reports an empty list, not unknown", Array.isArray(inFlight) && inFlight.length === 0);
+check("V2: toolPartName prefers tool and falls back to name", toolPartName({ tool: "shell" }) === "shell" && toolPartName({ name: "bash" }) === "bash" && toolPartName({}) === undefined);
+
+console.log("- Policy 1: parent-chain walk tolerates unknown links (V2) -");
+const walkTodos = new Map<string, TestTodo[] | undefined>();
+const walkParents = new Map<string, string | undefined>();
+setSdkClient({
+	session: {
+		todo: async ({ path }: { path: { id: string } }) => ({ data: walkTodos.get(path.id) }),
+		get: async ({ path }: { path: { id: string } }) => ({ data: { id: path.id, parentID: walkParents.get(path.id) } }),
+	},
+});
+walkTodos.set("v2-child-inherit", undefined);
+walkTodos.set("v2-parent-owner", [item("parent-task", "pending")]);
+walkParents.set("v2-child-inherit", "v2-parent-owner");
+const inherited = await effectiveTodosWithOwner("v2-child-inherit");
+check(
+	"V2: unknown child inherits a parent-owned list (owner attribution preserved)",
+	inherited?.ownerSessionID === "v2-parent-owner" && inherited?.todos[0]?.content === "parent-task",
+);
+walkTodos.set("v2-child-unknown", undefined);
+walkParents.set("v2-child-unknown", undefined);
+check("V2: unknown-only chain fails open", (await effectiveTodosWithOwner("v2-child-unknown")) === undefined);
+walkTodos.set("v2-child-empty", []);
+walkTodos.set("v2-parent-unknown", undefined);
+walkParents.set("v2-child-empty", "v2-parent-unknown");
+check("V2: empty child with unknown ancestor fails open", (await effectiveTodosWithOwner("v2-child-empty")) === undefined);
+walkTodos.set("v2-cycle-a", undefined);
+walkTodos.set("v2-cycle-b", undefined);
+walkParents.set("v2-cycle-a", "v2-cycle-b");
+walkParents.set("v2-cycle-b", "v2-cycle-a");
+check("V2: cycle of unknown links terminates and fails open", (await effectiveTodosWithOwner("v2-cycle-a")) === undefined);
+walkTodos.set("v2-child-all-empty", []);
+walkTodos.set("v2-parent-all-empty", []);
+walkParents.set("v2-child-all-empty", "v2-parent-all-empty");
+walkParents.set("v2-parent-all-empty", undefined);
+const allEmpty = await effectiveTodosWithOwner("v2-child-all-empty");
+check("V2: all-empty chain stays definitively empty (enforce)", Array.isArray(allEmpty?.todos) && allEmpty!.todos.length === 0);
+// Seam: the V2 adapter delegates to scanSessionTodos, so drive that exact path
+// into the edit gate. A builtin-only session (history with no todowrite part)
+// must allow edits; a session whose newest todowrite emptied the list is still
+// gated.
+const scanCtx = (messages: unknown) => ({ session: { context: async () => messages } });
+setSdkClient({
+	session: {
+		todo: async ({ path }: { path: { id: string } }) => ({
+			data: await scanSessionTodos(scanCtx([{ content: [{ type: "tool", tool: "edit", state: { status: "completed" } }] }]), path.id),
+		}),
+		get: async () => ({ data: {} }),
+	},
+});
+check(
+	"V2 builtin-only session (scanner reports unknown) allows edits",
+	!(await call("edit", { filePath: join(root, "a.ts"), content: "x" }, { sessionID: "s-v2-builtin" })),
+);
+setSdkClient({
+	session: {
+		todo: async ({ path }: { path: { id: string } }) => ({
+			data: await scanSessionTodos(scanCtx([todoPart([])]), path.id),
+		}),
+		get: async () => ({ data: {} }),
+	},
+});
+check(
+	"V2 session whose todowrite emptied the list is still gated",
+	blocked(await call("edit", { filePath: join(root, "a.ts"), content: "x" }, { sessionID: "s-v2-emptied" })),
+);
+setSdkClient(fakeClient);
+
 console.log("- Policy 2: push to main/master -");
 check("block git push origin main", blocked(await shell("git push origin main")));
 check("block git push origin master", blocked(await shell("git push origin master")));
@@ -537,6 +628,10 @@ check("inspection command with mutation keywords in grep argument is not blocked
 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("SQL > comparison in query is not a file mutation", !(await call("bash", { command: 'sqlite3 app.db "SELECT id FROM events WHERE count > 5"' }, { sessionID: "s-empty" })));
+check("SQL >= comparison in query is not a file mutation", !(await call("bash", { command: 'psql -c "SELECT 1 FROM metrics WHERE n >= 10"' }, { sessionID: "s-empty" })));
+check("numeric comparison in grep pattern is not a file mutation", !(await call("bash", { command: "grep -E 'latency > 200' src/log.ts" }, { sessionID: "s-empty" })));
+check("real redirect alongside numeric comparison still blocked", blocked(await call("bash", { command: 'echo "x > 5" > src/a.ts' }, { 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" })));
 check("single-file rm outside workspace is blocked", blocked(await call("bash", { command: "rm /tmp/wg-outside-file" }, { sessionID: "s-active" })));