opencode-workflow-guard 1.13.1 → 1.13.2

package/docs/policies.md

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

@@ -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.2",
   "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",

package/src/lib/v2-plugin.ts

@@ -66,6 +66,16 @@ 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
@@ -78,9 +88,11 @@ async function fetchTodosFromContext(ctx: V2Context, sessionID: string): Promise
 			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 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;
@@ -137,6 +149,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 +538,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/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/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

@@ -537,6 +537,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" })));