opencode-workflow-guard 1.13.2 → 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.

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.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.13.2",
+  "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,44 +67,9 @@ type V2Context = Plugin.Context;
 
 // ── V1 SDK client adapter ─────────────────────────────────────────────────────
 
-/**
- * V2 tool parts carry the tool name in `tool` (the V1 field was `name`); ACP
- * agents may still report either shape, so accept both.
- */
-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 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; tool?: unknown; name?: unknown; state?: { status?: string; input?: { todos?: unknown } } };
-				if (part?.type !== "tool") continue;
-				const toolName = toolPartName(part);
-				if (toolName === undefined) continue;
-				if (!/^todowrite$/i.test(toolName)) 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
@@ -119,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 } };

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/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/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")));