opencode-workflow-guard 1.17.0 → 1.18.1

package/docs/installation.md

@@ -6,8 +6,14 @@
 
 ## Requirements
 
-- **OpenCode >= 1.18** (V1: requires the `GET /session/:id/todo` endpoint and the V1 `PluginModule` loader) or **OpenCode 2.x**. V2 loads through the `@opencode/plugin` API. The current todo list is reconstructed from session message history, or read from the native `todowrite` on 2.1.x when `experimental.todo` is enabled.
+- **OpenCode >= 1.18** (V1: requires the `GET /session/:id/todo` endpoint and the V1 `PluginModule` loader) or **OpenCode 2.x**. V2 loads through the `@opencode/plugin` API. The current todo list is reconstructed from session message history, or read from the native `todowrite` behind `experimental.todo`. The guard probes the host tool registry for that capability instead of assuming it per version.
 - **Node.js >= 22.18** or **Bun** (for running test scripts directly).
+  `@opentui/core` declares `node >=26.4.0` in its own `engines`, and that has
+  been true since at least `0.6.6`. It arrives as a transitive dependency of
+  `@opentui/solid`, so npm reports an engine warning rather than refusing the
+  install, and the server plugin never imports it. Only the optional TUI
+  companion loads `@opentui/solid`. The pin set is exercised on Node 22.18+ in
+  CI, which is the practical floor for the plugin itself.
 
 ### Version Qualification
 
@@ -22,13 +28,24 @@ verified it.
 | 1.16.x | 2.0.15 | `permission.hook("evaluate")`, `tool.hook("execute.before"/"execute.after")`, `session.hook("context")`, `experimental.text.complete`, command registration, `mcp.list`, `worktree` client | Unit and package-loader verified. Live model-driven probes reached the provider and were classified `live unavailable` (`Model unavailable: openrouter/openrouter/auto`), so no guard verdict was produced. |
 | 1.16.x | 2.1.3 | `permission.hook("evaluate")`, `tool.hook(...)`, `session.hook(...)`, `experimental.text.complete`, command registration, `mcp.list`, `worktree` client, `todowrite` behind `experimental.todo` | Package-loader and headless-runtime verified (`npm run test:install`: 30 passed). Live host probe confirmed `ctx.tool.list()` exposes `todowrite` with `experimental.todo: true` and omits it when false. Live static-policy denial canary produced `Blocked by configuration policy`. |
 | 1.16.x | 1.18.32 (`@opencode-ai/plugin`) | V1 `PluginModule` loader, native todo endpoint | Compatibility export only; unit-tested, no live host probe. |
-
-The 2.1.3 pins require the 2.1.x package set. `@opencode/plugin` and
-`@opencode/ai` are pinned to `2.1.3`, which depends on `effect@4.0.1` and
-requires `@opentui/solid >=0.6.6`. The guard pins `0.6.6`. A 2.0.x pin set on a
-2.1.x host fails to load at all. The plugin imports an `effect` path the host no
-longer provides, and the host reports `failed to load plugin` while every
-policy stays inert.
+| 1.18.x | 2.2.0 | `permission.hook("evaluate")`, `tool.hook("execute.before"/"execute.after")`, `session.hook("context"/"compaction"/"prompt")`, `command.transform`, `shell.hook("create.before")`, `event.subscribe()` (completion-claim observation via `session.text.ended`), command registration, `mcp.list`, `worktree` client, `todowrite` behind `experimental.todo` | Package-loader and headless-runtime verified on the 2.2.0 pin set (`npm run test:install`: 32 passed). Registration of the hook seats and custom tools is asserted, not re-derived: the 2.2.0-specific probes are the permission seat (a real finding denies, an undecidable push abstains) and the todo capability (both branches asserted on this host). V2 exposes completion claims through `event.subscribe()` rather than the V1 `experimental.text.complete` hook; the audit trail keeps the V1 tool name for continuity. Live model-driven probes were skipped, so no guard verdict from a model turn is claimed here. |
+
+The 2.2.0 pins require the 2.2.x package set. `@opencode/plugin` and
+`@opencode/ai` are pinned to `2.2.0`, and `@opentui/solid` moves to `0.7.0`
+because `@opencode/plugin@2.2.0` declares that as an exact peer requirement.
+`@opentui/core` is not pinned directly: `@opentui/solid@0.7.0` already declares
+it as an exact dependency, so resolution supplies the matching version. That
+release also moves `Message` out of the `@opencode/ai` root: on 2.2.0 the root
+no longer re-exports the schema surface, so a root named import of `Message`
+throws at load, and the schema lives behind `@opencode/ai/effect`. The guard
+imports from `/effect`, which is the path `@opencode/plugin@2.2.0` uses itself.
+`@opencode/ai@2.1.3` resolves `./effect` only through its `"./*"` wildcard, and
+that release ships no `dist/effect.js` for the wildcard to reach, so the two pin
+sets are not interchangeable: one release's import path does not exist in the
+other.
+
+`@opencode-ai/plugin` stays at `1.19.3`. That is the V1 pin, emitted alongside
+the V2 entrypoint, and the 2.2.0 release does not change it.
 
 `guard_status` reports `pluginVersion`, `qualifiedHostVersion`, and the live
 `hostVersion`, so a mismatch is visible at runtime rather than surfacing as a
@@ -36,21 +53,29 @@ silently inert hook.
 
 ### Dependency Audit Overrides
 
-Two transitive dependencies are pinned above the range their parent declares, to
-clear advisories that would otherwise ship:
+Three transitive dependencies are pinned above the range their parent declares,
+to clear advisories that would otherwise ship:
 
 | Package | Parent constraint | Override | Why |
 |---|---|---|---|
-| `solid-js` | `@opentui/solid@0.6.6` peer-pins exactly `1.9.12` | `1.9.17` | `1.9.12` requires `seroval ~1.5.0`, which carries memory-exhaustion and thenable-assimilation advisories. `1.9.17` requires `seroval ~1.6.8`, which is patched. The TUI imports `solid-js` directly, so the bump is also the version the guard actually runs. |
+| `solid-js` | `@opentui/solid@0.7.0` peer-pins exactly `1.9.12` | `1.9.17` | `1.9.12` requires `seroval ~1.5.0`, which carries memory-exhaustion and thenable-assimilation advisories. `1.9.17` requires `seroval ~1.6.8`, which is patched. The TUI imports `solid-js` directly, so the bump is also the version the guard actually runs. |
 | `toml` | `effect@4.0.0-beta.83` (via `@opencode-ai/plugin`) requires `^4.1.1` | `5.0.1` | `toml <=5.0.0` carries three quadratic-complexity denial-of-service advisories. `5.0.1` keeps the same single `parse` export the caller uses. The guard itself never parses TOML; this is host plumbing. |
+| `zod` | `@opencode-ai/plugin@1.19.3` pins `4.1.8` exactly | `4.6.6` | `GHSA-mrhx-c7xc-m3w5` (published 2026-10-01) covers `zod <4.6.6` with a memory-exhaustion advisory. `4.6.6` is the patched release in the same major line. `zod` reaches the tree only through the V1 host pin, but the guard's own V2 entrypoint imports it, so one deduped patched copy serves both. An override is required where a direct dependency would not do: the V1 pin is exact, so declaring `zod` at the root alone leaves a nested `4.1.8` and the advisory standing. |
 
-Both are `overrides` entries in `package.json`, and `npm audit` reports zero
+All three are `overrides` entries in `package.json`, and `npm audit` reports zero
 vulnerabilities for this repository. `npm overrides` apply only to the root
 project, so they protect this repository's install and its CI, not a consumer's
 transitive tree. A consumer that installs the published package resolves the
-parent-declared ranges unless it declares the same overrides itself. Revisit both
-when `@opentui/solid` or `@opencode-ai/plugin` widen their ranges, and drop the
-override rather than carrying it forward.
+parent-declared ranges unless it declares the same overrides itself. Revisit
+them when `@opentui/solid` or `@opencode-ai/plugin` widen their ranges, and drop
+the override rather than carrying it forward.
+
+Changing an override requires a clean reinstall. `npm install` over an existing
+`node_modules` can leave a lockfile that still resolves the old version, and the
+resulting failure reads like an incompatibility. With the `zod` override, an
+incremental install produced 14 `test:install` failures and a `tsc` error about
+a missing `zod`, while removing `node_modules` and `package-lock.json` and
+reinstalling passed every check.
 
 ---
 

package/docs/policies.md

@@ -104,6 +104,7 @@ This is a policy and enforcement layer, not an agent harness. Policies may const
 - When the agent attempts to mark **every** task completed (finalizing the request), the guard requires passing verification evidence.
 - Verification executes in an isolated environment with scrubbed credentials, output caps, token-efficient stdout/stderr snipping, and strict timeout protection. The command comes from the `WORKFLOW_GUARD_VERIFY` env, the project `verifyCommand`, or an auto-detected test or typecheck runner across ecosystems. Auto-detection covers `package.json` (`npm test`, `npm run typecheck`, `npm run check`, `npm run build`), `Cargo.toml` (`cargo test`), `go.mod` (`go test ./...`), `pytest.ini` or `pyproject.toml` (`pytest`), and `deno.json` (`deno test`). Environment configuration takes precedence over project configuration.
 - The verification timeout defaults to 30 seconds. Raise it per project with `verifyTimeoutMs` in `.opencode/workflow-guard.json`, or per environment with `WORKFLOW_GUARD_VERIFY_TIMEOUT_MS`, which wins over project config. Non-positive values are ignored and fall back to the default. Raise the timeout for suites that legitimately exceed the default, for example this repository's own unit suite.
+- A timeout is reported as `verification_timed_out`, not `verification_failed`. Both block finalization, because neither produced a passing result. They differ in what the agent is told: a timeout says the result is unknown and names the limit and the remedy, while a failure names the failing output. Calling a timeout a failure sent agents looking for an assertion that never ran, and the fix for a timeout is a longer limit rather than a code change.
 - Project `postEditValidators` can run faster targeted checks after a direct file edit actually changes the target. Each entry accepts a workspace-relative glob `pattern` with `*`, `**`, and `?` wildcards. Brace expansion and character classes are not supported. Each entry also accepts a non-empty `command` and an optional positive `timeoutMs`. Invalid entries are reported as advisory feedback rather than silently ignored. Matching commands run from the workspace root with the same scrubbed verification environment. Validator failures and timeouts are appended to the edit result as advisory feedback. They do not replace the blocking whole-project finalization verification. Multi-file `apply_patch` calls validate every changed target.
 - With project `recoveryCheckpoints: true`, or the `autonomous` operation profile unless explicitly overridden, genuine root-session user runs capture a private Git checkpoint before agent work starts. Checkpoints preserve tracked and untracked state without using the user's stash list. Subagents and generated continuation prompts do not replace them. At `session.idle`, the run's resulting workspace fingerprint is recorded before automatic continuation. `guard_recovery_restore` is provenance-bound to the same root session and refuses restoration after any intervening workspace change. Operation profiles only set optional workflow defaults and cannot weaken core safety policies.
 - Automatic continuation remains synthetic. By default, an eligible root session with unfinished owned todos briefly waits for OpenCode's native asynchronous title generation before that continuation is sent. Set `titleSettleWorkaround: false` to opt out. The bounded wait never rewrites titles or provider and model parameters.
@@ -130,11 +131,12 @@ This is a policy and enforcement layer, not an agent harness. Policies may const
 - Permission prompts are journaled at request time via the typed `permission.ask` plugin hook. `permission.replied` outcomes, including rejections, are preserved instead of being labeled as allows.
 - On OpenCode 2, the V2 plugin also *decides* at that seat. `ctx.permission.hook("evaluate")` maps the host's normalized `action` and `resources` back onto the policy core and sets `effect = "deny"` with an attributable message, so the tool never starts. Shell resources feed the shell, git, destructive, and workspace policies. `read` resources feed the secret policy. `edit`, `write`, `patch`, and `apply_patch` resources feed the boundary, tamper, secret, protected-branch, and todo policies. Guarded MCP servers (`GitHub`, `Azure DevOps`) feed the MCP policy.
 - The seat can only tighten. An explicit configured `deny` is final and never reaches the hook. An unmapped host action (`external_directory`, `glob`, `grep`, `webfetch`, `websearch`, `question`, `subagent`) is left to host policy. If the seat itself throws, it fails closed with a deny instead of becoming a pass.
+- **Only a finding denies; an undecidable simulation abstains.** The seat always evaluates the policy core with `simulate: true`, which skips the remote GitHub/Azure PR probe on purpose. The core reports `needs_approval` (`remote_state_unchecked`) when it cannot decide without that probe. Collapsing that status into a denial blocked every non-protected `git push`, so the seat now abstains: it leaves the host's configured effect and message untouched and defers the real decision to `execute.before`, which runs the probe. The abstention is journaled with `decision: "abstain"`, `reason: "deferred_to_execute_before"`, and the preserved `needs_approval` decision, so a skipped probe stays visible instead of reading as a plain allow. `guard_why` keeps reporting `needs_approval`; this is a change to the seat, not to the policy core.
 - `execute.before` is kept as the second, last-resort seat. It sees raw tool input, so todo lifecycle, stale-write observations, and post-edit snapshots stay there. Its thrown message carries the specific remediation text to the model.
 - `client.app.log()` complements the on-disk trail with in-app logs.
 
 ### 15. Compaction State & Policy Context Preservation
-- Integrates with OpenCode's compaction hook to inject bounded active policy state before context summarization. The hook is `experimental.session.compacting` on OpenCode 1.x and `session.hook("compaction")` on OpenCode 2.x, which is stable in the installed 2.1.3 typings:
+- Integrates with OpenCode's compaction hook to inject bounded active policy state before context summarization. The hook is `experimental.session.compacting` on OpenCode 1.x and `session.hook("compaction")` on OpenCode 2.x, which is stable in the installed 2.2.0 typings:
   - Caps injected continuity context at 8,000 characters. Operational guard state is preserved first. The remaining budget holds active tasks, review follow-ups, and fresh local project memory.
   - Active `todowrite` tasks with status badges and subagent hierarchy attribution.
   - Active Git branch name and protected branch status.

package/docs/testing.md

@@ -47,12 +47,13 @@ npm run test:all
 | **Policy 5: MCP Mutations** | Verifies GitHub/Azure mutating MCP tools are blocked while read-only tools pass. |
 | **Policy 6: Settings Tamper** | Verifies protection of `opencode.json`, `~/.config/opencode/*`, and `opencode auth`. |
 | **Policy 8: Workspace Boundary** | Verifies path traversal (`../`), symlinks, and absolute path escape protection in `edit`, `write`, `apply_patch`, and shell mutations. |
-| **Policy 10: Evidence Verification** | Verifies isolated verification execution, timeout handling, scrubbed environment, and finalization gating on fresh passing tests. |
+| **Policy 10: Evidence Verification** | Verifies isolated verification execution, timeout handling, scrubbed environment, and finalization gating on fresh passing tests. A timeout blocks finalization under its own code, and its reason names the limit and the remedy instead of claiming a failing test. |
 | **Adversarial Invariants** | Verifies defense against compound shell mutations, symlink escapes, chained git normalization, verify script abuse, and external repo mutations. |
 | **Audit & Permission Events** | Verifies the typed `permission.ask` hook, permission replies, and command journaling in the audit trail. |
 | **Completion Claims & Tool Honesty** | Verifies the claims-vs-evidence detector (missing/failing/stale/fresh states), `experimental.text.complete` journaling, and `tool.definition` enrichment idempotence. |
 | **Compaction & TUI Feedback** | Verifies active task injection in `experimental.session.compacting`, the static TUI badge, guard block warning toasts, and clean error propagation. |
 | **Runtime Instance Isolation** | Verifies concurrent plugin instances keep workspace root and SDK client state isolated via `runWithRuntimeState`. |
+| **V2 Permission Seat Abstention** | Verifies the simulated seat denies a real finding, abstains on `needs_approval` (`remote_state_unchecked`) instead of denying, never upgrades a configured `ask`, and journals the abstention as `deferred_to_execute_before` with the preserved decision. |
 | **V2 Todo Capability** | Verifies the `todowrite` registry probe (`available` / `unavailable` / `unknown`), that an empty history gates only when planning is possible, the once-per-session fail-open warning and audit record, and `todoCapability` in `guard_status`. |
 | **Per-Task Completion Evidence** | Verifies a task cannot move to `completed` without a mutation in its own window, that one mutation cannot vouch for several completions, that staggered windows reject a claim whose window saw no work, that mutations before a task became active never count, that `[read-only]` completes freely and is journaled, that the marker can be appended to an already-planned task without tripping the no-silent-deletion rule, that duplicate content cannot hide a new completion, and that `guard_why` reports the same verdict while moving no window. |
 | **Static Policy Posture** | Verifies the emitted posture is deny-only, emits both host envelopes (`experimental.policies`/`permission` for 2.0.x, top-level `policies`/`tool.use` for 2.1.x), requires both to reach the same verdict for every probed resource, and matches the intended commands under a replica of the host's whole-string glob matcher, including the compound-command evasion it does not cover. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.17.0",
+  "version": "1.18.1",
   "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",
@@ -51,10 +51,10 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "1.19.3",
-    "@opencode/plugin": "2.1.3",
-    "@opentui/solid": "0.6.6",
-    "jsonc-parser": "3.3.1",
-    "@opencode/ai": "2.1.3"
+    "@opencode/ai": "2.2.0",
+    "@opencode/plugin": "2.2.0",
+    "@opentui/solid": "0.7.0",
+    "jsonc-parser": "3.3.1"
   },
   "devDependencies": {
     "@changesets/cli": "3.0.3",
@@ -63,6 +63,7 @@
   },
   "overrides": {
     "solid-js": "1.9.17",
-    "toml": "5.0.1"
+    "toml": "5.0.1",
+    "zod": "4.6.6"
   }
 }

package/src/lib/guard-dispatcher.ts

@@ -153,6 +153,17 @@ function logBlock(message: string, simulate = false): void {
 	} catch {}
 }
 
+/**
+ * Render a verification timeout limit for the block reason.
+ *
+ * Sub-second limits are exercised by tests, and a bare `Math.round(ms/1000)`
+ * reports those as "0s", which reads as no limit at all.
+ */
+function formatTimeoutLimit(timeoutMs: number | undefined): string {
+	if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) return "the verification timeout";
+	return timeoutMs < 1000 ? `${timeoutMs}ms` : `${Math.round(timeoutMs / 1000)}s`;
+}
+
 export async function guardToolCallImpl(
 	toolName: string,
 	input: unknown,
@@ -256,10 +267,20 @@ export async function guardToolCallImpl(
 						const result = await runVerify(command, currentRoot, resolveVerifyTimeoutMs(currentRoot));
 						recordVerifyResult(command, result, sessionID, currentRoot);
 						if (!result.passed) {
-							const tail = snipVerifyOutput(result.output, result.passed).slice(-500);
-							const reason = `Blocked todowrite: all tasks marked done but verification is failing (${command}). Fix the failure before finishing; output tail: ${tail}`;
+							// A timeout is not a failing test. Both block
+							// finalization, but naming a failure sends the
+							// agent chasing an assertion that never ran, and
+							// the remedy is a longer limit rather than a code
+							// change. The tail is snipped as passing output on
+							// that path, because snipVerifyOutput labels a
+							// failing run with a "Verification Failed" header
+							// that would restate the misattribution.
+							const tail = snipVerifyOutput(result.output, result.timedOut === true).slice(-500);
+							const reason = result.timedOut
+								? `Blocked todowrite: verification did not finish within ${formatTimeoutLimit(result.timeoutMs)} so the result is unknown rather than failing (${command}). Raise the limit in the project .opencode/workflow-guard.json (verifyTimeoutMs) or with WORKFLOW_GUARD_VERIFY_TIMEOUT_MS, then complete the tasks again; output tail: ${tail}`
+								: `Blocked todowrite: all tasks marked done but verification is failing (${command}). Fix the failure before finishing; output tail: ${tail}`;
 							logPolicyBlock(`[workflow-guard] ${reason}`);
-							return block("verification", "verification_failed", reason);
+							return block("verification", result.timedOut ? "verification_timed_out" : "verification_failed", reason);
 						}
 					}
 				}

package/src/lib/permission-seat.ts

@@ -16,6 +16,12 @@
  * when the configured effect is allow/ask). A hook denial is therefore always a
  * response to something the host would otherwise permit.
  *
+ * An `abstain` is the one case where the seat does not tighten. The simulated
+ * core reports `needs_approval` when it cannot decide without the remote
+ * GitHub/Azure PR probe, which simulation skips on purpose. The host's
+ * configured effect then stays untouched and `execute.before` runs the real
+ * check, probe included.
+ *
  * Every decision here is a simulation of the policy core: `simulate: true`
  * skips mutation accounting, file claims, verification runs, and durable audit
  * writes, because the same call is evaluated for real in `execute.before`.
@@ -41,9 +47,13 @@ export interface PermissionSeatDeps {
 }
 
 export interface PermissionSeatResult {
-	/** The effect the seat leaves in place. */
-	effect: "allow" | "deny";
-	/** Set only when the seat denied. */
+	/**
+	 * The effect the seat leaves in place. `abstain` is an explicit third
+	 * state: the simulated policy core could not decide, so the host's
+	 * configured effect stays untouched and `execute.before` enforces.
+	 */
+	effect: "allow" | "deny" | "abstain";
+	/** Set when the seat denied, and kept on an abstention for the audit row. */
 	decision?: PolicyDecision;
 	/** The guard tool the action was mapped onto, for attribution. */
 	mappedTool?: string;
@@ -51,6 +61,25 @@ export interface PermissionSeatResult {
 
 const EDIT_ACTIONS = new Set(["edit", "write", "patch", "apply_patch"]);
 
+/**
+ * Map one simulated policy decision onto the seat's effect.
+ *
+ * Only `needs_approval` abstains. That status means the simulated core could
+ * not decide, because `simulate: true` deliberately skips the remote GitHub or
+ * Azure PR probe. Collapsing it into `deny` would miscategorise an abstention
+ * as a finding and block every non-protected `git push`. Deferring it leaves
+ * the host's configured effect untouched, and `execute.before` runs the real
+ * check with the probe. Every other non-allowed status stays a denial.
+ */
+function seatVerdict(decision: PolicyDecision, mappedTool: string): PermissionSeatResult | undefined {
+	if (decision.status === "allowed") return undefined;
+	return {
+		effect: decision.status === "needs_approval" ? "abstain" : "deny",
+		decision: { ...decision, message: `[workflow-guard permission.evaluate] ${decision.message}` },
+		mappedTool,
+	};
+}
+
 function mappedToolFor(action: string): { tool: string; input: (resource: string) => unknown } | undefined {
 	if (action === "shell" || action === "bash") {
 		return { tool: "bash", input: (resource) => ({ command: resource }) };
@@ -90,13 +119,8 @@ export async function evaluatePermissionSeat(
 	if (mapping) {
 		for (const resource of resources) {
 			const decision = await decide(mapping.tool, mapping.input(resource));
-			if (decision.status !== "allowed") {
-				return {
-					effect: "deny",
-					decision: { ...decision, message: `[workflow-guard permission.evaluate] ${decision.message}` },
-					mappedTool: mapping.tool,
-				};
-			}
+			const verdict = seatVerdict(decision, mapping.tool);
+			if (verdict) return verdict;
 		}
 		return { effect: "allow", mappedTool: mapping.tool };
 	}
@@ -106,14 +130,7 @@ export async function evaluatePermissionSeat(
 	for (const resource of resources) {
 		if (!mcpMutationTool(event.action) && !mcpMutationTool(resource)) continue;
 		const decision = await decide(event.action, {});
-		if (decision.status !== "allowed") {
-			return {
-				effect: "deny",
-				decision: { ...decision, message: `[workflow-guard permission.evaluate] ${decision.message}` },
-				mappedTool: event.action,
-			};
-		}
-		return { effect: "allow", mappedTool: event.action };
+		return seatVerdict(decision, event.action) ?? { effect: "allow", mappedTool: event.action };
 	}
 	return { effect: "allow" };
 }

package/src/lib/types.ts

@@ -143,7 +143,12 @@ export interface AuditEntry {
 	sessionID?: string;
 	callID?: string;
 	tool: string;
-	decision: "allow" | "block";
+	/**
+	 * `abstain` records a decision the guard deferred instead of resolving:
+	 * the simulated permission seat cannot judge remote PR state, so
+	 * `execute.before` decides for real. It is not an allow.
+	 */
+	decision: "allow" | "block" | "abstain";
 	policyDecision?: PolicyDecision;
 	phase?: "decision" | "outcome" | "event";
 	durationMs?: number;

package/src/lib/v2-plugin.ts

@@ -18,7 +18,7 @@
  */
 
 import { Plugin } from "@opencode/plugin";
-import { Message } from "@opencode/ai";
+import { Message } from "@opencode/ai/effect";
 import { z } from "zod";
 import { join, resolve } from "node:path";
 import type { TodoSdkClient } from "./types.ts";
@@ -145,6 +145,9 @@ const SUBAGENT_SUFFIX =
 //   server registry, so this enrichment cannot reach them.
 // - V2.1.x adds a builtin `todowrite` behind the `experimental.todo` config
 //   key, so the candidate below reaches a real registry entry there.
+// - V2.2.x exposes `todowrite` through that same `experimental.todo` opt-in.
+//   The guard probes the registry rather than inferring capability from the
+//   version, so 2.1.x and 2.2.x need no version check here.
 // - 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 }> = [
@@ -583,17 +586,22 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 				},
 				{ workspaceRoot: effectiveRoot, client },
 			);
-			if (seat.decision) {
+			if (seat.effect === "deny" && seat.decision) {
 				event.effect = "deny";
 				event.message = seat.decision.message;
 			}
+			// An abstention leaves the configured effect and message untouched,
+			// and still journals. `execute.before` runs the real check, which
+			// includes the remote PR probe that simulation skips. It records
+			// `abstain` rather than `allow`, so the deferral stays visible.
+			const abstained = seat.effect === "abstain";
 			audit({
 				ts: new Date().toISOString(),
 				sessionID: event.sessionID,
 				tool: "permission.ask",
-				decision: seat.effect === "deny" ? "block" : "allow",
+				decision: seat.effect === "deny" ? "block" : abstained ? "abstain" : "allow",
 				phase: "decision",
-				reason: seat.decision?.code,
+				reason: abstained ? "deferred_to_execute_before" : seat.decision?.code,
 				policyDecision: seat.decision,
 				input: {
 					action: event.action,
@@ -601,6 +609,7 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 					agent: event.agent,
 					configuredEffect,
 					mappedTool: seat.mappedTool,
+					...(abstained ? { deferred: "execute.before" } : {}),
 				},
 			});
 		} catch (error) {

package/src/lib/verify.ts

@@ -231,11 +231,26 @@ export function resolveVerifyTimeoutMs(root: string): number {
 	return typeof configured === "number" && Number.isFinite(configured) && configured > 0 ? configured : 30_000;
 }
 
+export interface VerifyRun {
+	passed: boolean;
+	output: string;
+	durationMs: number;
+	/**
+	 * Set when the command was killed at the timeout rather than exiting on its
+	 * own. A timeout is not a failing assertion: it says nothing about whether
+	 * the change is correct, and the remedy is a longer limit, not a code fix.
+	 * Callers that report a reason must attribute it, or the agent chases a
+	 * failure that does not exist.
+	 */
+	timedOut?: boolean;
+	timeoutMs?: number;
+}
+
 export async function runVerify(
 	command: string,
 	root: string,
 	timeoutMs = 30_000,
-): Promise<{ passed: boolean; output: string; durationMs: number }> {
+): Promise<VerifyRun> {
 	const start = Date.now();
 	const allowLive = process.env.WORKFLOW_GUARD_ALLOW_LIVE === "1";
 
@@ -294,6 +309,8 @@ export async function runVerify(
 					passed: false,
 					output: output + `\n(Verification timed out after ${Math.round(timeoutMs / 1000)}s)`,
 					durationMs: Date.now() - start,
+					timedOut: true,
+					timeoutMs,
 				});
 			});
 		}, timeoutMs);

package/test/test-e2e.mts

@@ -225,6 +225,16 @@ const runV2Probes = async (ctx: any) => {
 \tconst guardWhy = byId("guard_why");
 \tconst pick = (r: any) => (typeof r?.content === "string" ? r.content : JSON.stringify(r));
 \tconst statusRes = guardStatus ? await guardStatus.execute({}, headlessToolContext) : undefined;
+\t// Permission-seat canary. The seat runs inside the real host plugin setup,
+\t// with the workspace taken from the host's own location.directory, so a
+\t// typed-only seat cannot pass. No client is passed: this probe makes no
+\t// remote call, and the push case is the one that must abstain precisely
+\t// because simulation skips the remote PR probe.
+\tconst { evaluatePermissionSeat } = await import("../workflow-guard-source/lib/permission-seat.ts");
+\tconst workspaceRoot = ctx?.location?.directory ?? process.cwd();
+\tconst seatEvent = (action: string, resources: string[]) => ({ sessionID: "headless-e2e-seat", agent: "build", action, resources, effect: "allow" as const });
+\tconst seatDeny = await evaluatePermissionSeat(seatEvent("read", [".env"]), { workspaceRoot, client: undefined });
+\tconst seatPush = await evaluatePermissionSeat(seatEvent("shell", ["git push origin feat/install-verification"]), { workspaceRoot, client: undefined });
 \tconst whyProbes: Record<string, { tool: string; input: Record<string, unknown> }> = {
 \t\tgit: { tool: "bash", input: { command: "git push origin main" } },
 \t\t"secrets-read": { tool: "read", input: { filePath: ".env" } },
@@ -244,6 +254,7 @@ const runV2Probes = async (ctx: any) => {
 \t\tstatus: JSON.parse(pick(statusRes)),
 \t\twhy: whyResults.git,
 \t\twhyProbes: whyResults,
+\t\tseat: { deny: seatDeny, push: seatPush },
 \t}) + "\\n");
 \twriteFileSync(${JSON.stringify(initializedMarker)}, "initialized\\n");
 };
@@ -432,6 +443,21 @@ if (isOpenCodeV2) {
 	check("V2 setup registers the full config-gated guard tool surface", missingGuardTools.length === 0);
 	if (missingGuardTools.length > 0) console.log("  missing guard tools: " + missingGuardTools.join(", "));
 	console.log(`  note: builtin todowrite description enriched under V2: ${headlessAccountability?.todowriteEnriched === true ? "yes" : "unknown at setup time"}`);
+	// Provenance: `workspaceRoot` is the host's own `location.directory`, read
+	// inside the real setup call. The seat runs with no client, so nothing here
+	// depends on hand-built remote state.
+	check(
+		"V2 permission seat denies a real finding against the live host context",
+		headlessAccountability?.seat?.deny?.effect === "deny" &&
+			headlessAccountability?.seat?.deny?.decision?.status === "blocked" &&
+			headlessAccountability?.seat?.deny?.decision?.policy === "secrets" &&
+			headlessAccountability?.seat?.deny?.decision?.code === "secret_read",
+	);
+	check(
+		"V2 permission seat abstains on an undecidable push instead of denying it",
+		headlessAccountability?.seat?.push?.effect === "abstain" &&
+			headlessAccountability?.seat?.push?.decision?.code === "remote_state_unchecked",
+	);
 }
 
 // The todo capability probe is only meaningful against a host that can gate

package/test/test.mts

@@ -122,6 +122,7 @@ import {
 import { prBodyIncludesChangelog } from "../src/policies/changelog.ts";
 import { terminateProcessTree } from "../src/lib/verify.ts";
 import { audit } from "../src/lib/audit.ts";
+import { evaluatePermissionSeat } from "../src/lib/permission-seat.ts";
 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";
@@ -2335,6 +2336,66 @@ check(
 	blocked(failFinalRes),
 );
 
+// A timeout is not a failing test. Both block finalization, but the reason
+// must name the timeout and its remedy. Reporting a timeout as "verification
+// is failing" sends the agent looking for a failing assertion that does not
+// exist, and the real fix is a longer timeout rather than a code change.
+console.log("- Policy 10: verification timeout attribution -");
+// The verify env overrides beat project config, so a developer with either one
+// exported (the docs recommend doing exactly that for this repo's suite) would
+// otherwise make these checks measure their shell instead of the guard.
+const prevTimeoutVerifyEnv = process.env.WORKFLOW_GUARD_VERIFY;
+const prevTimeoutLimitEnv = process.env.WORKFLOW_GUARD_VERIFY_TIMEOUT_MS;
+delete process.env.WORKFLOW_GUARD_VERIFY;
+delete process.env.WORKFLOW_GUARD_VERIFY_TIMEOUT_MS;
+const verifyTimeoutRepo = mkdtempSync(join(tmpdir(), "wg-verify-timeout-finalize-"));
+mkdirSync(join(verifyTimeoutRepo, ".opencode"), { recursive: true });
+// The command prints far more than snipVerifyOutput's line budget, so the
+// tail exercises the snipper rather than a short literal output.
+writeFileSync(
+	join(verifyTimeoutRepo, ".opencode", "workflow-guard.json"),
+	JSON.stringify({
+		verifyCommand: "node -e \"for (let i = 0; i < 60; i++) console.log('noise ' + i); setTimeout(() => {}, 5000)\"",
+		verifyTimeoutMs: 50,
+	}),
+);
+reloadProjectConfig(verifyTimeoutRepo);
+setWorkspaceRoot(verifyTimeoutRepo);
+resetVerifyState();
+todo("s-verify-timeout", item("timeout work", "in_progress"));
+await call(
+	"edit",
+	{ filePath: join(verifyTimeoutRepo, "code.ts"), content: "timeout" },
+	{ sessionID: "s-verify-timeout" },
+);
+const timeoutFinalRes = await call(
+	"todowrite",
+	{ todos: [item("timeout work", "completed")] },
+	{ sessionID: "s-verify-timeout" },
+);
+check("verification timeout blocks finalization", blocked(timeoutFinalRes));
+check(
+	"verification timeout is not reported as a failing test",
+	!String(timeoutFinalRes).includes("verification is failing"),
+);
+check(
+	"a timed-out tail carries no failure header that restates the misattribution",
+	!String(timeoutFinalRes).includes("Verification Failed"),
+);
+check(
+	"verification timeout names the elapsed limit at the precision it was set",
+	String(timeoutFinalRes).includes("timed out") && String(timeoutFinalRes).includes("50ms"),
+);
+check(
+	"verification timeout names a remedy the agent can actually apply",
+	String(timeoutFinalRes).includes("verifyTimeoutMs") && String(timeoutFinalRes).includes("WORKFLOW_GUARD_VERIFY_TIMEOUT_MS"),
+);
+setWorkspaceRoot(verifyRepo);
+reloadProjectConfig(verifyRepo);
+if (prevTimeoutVerifyEnv !== undefined) process.env.WORKFLOW_GUARD_VERIFY = prevTimeoutVerifyEnv;
+if (prevTimeoutLimitEnv !== undefined) process.env.WORKFLOW_GUARD_VERIFY_TIMEOUT_MS = prevTimeoutLimitEnv;
+rmSync(verifyTimeoutRepo, { recursive: true, force: true });
+
 // A subagent mutation governed by the parent's todos must invalidate the
 // parent's cached verification result.
 writeFileSync(
@@ -5705,6 +5766,98 @@ if (prevDuplicateDataHome === undefined) delete process.env.XDG_DATA_HOME;
 else process.env.XDG_DATA_HOME = prevDuplicateDataHome;
 rmSync(v2DuplicateRoot, { recursive: true, force: true });
 
+// ── Permission seat: an undecidable simulation abstains, a finding denies ──
+// The seat always runs the policy core with `simulate: true`, which skips the
+// remote GitHub/Azure PR probe on purpose. `needs_approval` means exactly
+// that: the core could not decide. Collapsing it into a denial blocked every
+// non-protected `git push`, so the seat must abstain and leave the configured
+// effect untouched while `execute.before` runs the real check. A genuine local
+// finding still denies, and an abstention never upgrades a configured `ask`.
+console.log("- V2 permission seat: abstention -");
+const makeSeatRepo = (branch: string): string => {
+	const repo = mkdtempSync(join(tmpdir(), "wg-seat-"));
+	spawnSync("git", ["init", "-b", branch], { cwd: repo });
+	writeFileSync(join(repo, "tracked.txt"), "tracked\n");
+	spawnSync("git", ["add", "tracked.txt"], { cwd: repo });
+	spawnSync("git", ["-c", "user.name=Test", "-c", "user.email=test@example.com", "commit", "-m", "initial"], { cwd: repo });
+	return repo;
+};
+const seatFeatureRepo = makeSeatRepo("feature/push-seat");
+const seatMainRepo = makeSeatRepo("main");
+const seatEvent = (resources: string[], effect: "allow" | "ask" | "deny" = "allow") => ({
+	sessionID: "s-seat-abstain",
+	agent: "build",
+	action: "shell",
+	resources,
+	effect,
+});
+try {
+	const pushSeat = await evaluatePermissionSeat(
+		seatEvent(["git push origin feature/push-seat"]),
+		{ workspaceRoot: seatFeatureRepo, client: fakeClient as unknown },
+	);
+	check(
+		"seat abstains on a non-protected push whose remote PR state is unverified",
+		pushSeat.effect !== "deny" && pushSeat.effect === "abstain",
+	);
+	check(
+		"seat keeps the undecidable decision for audit attribution",
+		pushSeat.decision?.status === "needs_approval" && pushSeat.decision?.code === "remote_state_unchecked",
+	);
+	const protectedPushSeat = await evaluatePermissionSeat(
+		{ ...seatEvent(["git push origin feature/push-seat"]), sessionID: "s-seat-block" },
+		{ workspaceRoot: seatMainRepo, client: fakeClient as unknown },
+	);
+	check(
+		"seat still denies a real finding (push from a protected branch)",
+		protectedPushSeat.effect === "deny" && protectedPushSeat.decision?.status === "blocked" && /protected branch/i.test(String(protectedPushSeat.decision?.message)),
+	);
+	const askedSeat = await evaluatePermissionSeat(
+		{ ...seatEvent(["git push origin feature/push-seat"], "ask"), sessionID: "s-seat-ask" },
+		{ workspaceRoot: seatFeatureRepo, client: fakeClient as unknown },
+	);
+	check("an abstaining seat never upgrades a configured ask to allow", askedSeat.effect === "abstain");
+} finally {
+	rmSync(seatFeatureRepo, { recursive: true, force: true });
+	rmSync(seatMainRepo, { recursive: true, force: true });
+}
+
+// The end-to-end seat: the same undecidable push through the registered hook
+// must leave the configured effect and message untouched, and journal the
+// deferral so the skipped remote probe stays legible.
+{
+	resetPluginInstancesForTesting();
+	const seatHookRepo = makeSeatRepo("feature/push-seat-hook");
+	const prevSeatDataHome = process.env.XDG_DATA_HOME;
+	process.env.XDG_DATA_HOME = join(seatHookRepo, "data");
+	const seatCtx = makeV2Context(seatHookRepo);
+	const seatCleanup = (await defaultExport.setup(seatCtx.ctx as any)) as (() => void) | undefined;
+	const seatAskEvent = { ...permissionEvent("shell", ["git push origin feature/push-seat-hook"], "s-seat-hook-ask"), effect: "ask" as "allow" | "deny" | "ask" };
+	await seatCtx.state.permissionHooks[0]?.(seatAskEvent);
+	check(
+		"evaluate leaves a configured ask in place when the simulation abstains",
+		seatAskEvent.effect === "ask" && seatAskEvent.message === undefined,
+	);
+	const seatPushEvent = permissionEvent("shell", ["git push origin feature/push-seat-hook"], "s-seat-hook");
+	await seatCtx.state.permissionHooks[0]?.(seatPushEvent);
+	check(
+		"evaluate does not deny a non-protected push it cannot decide",
+		seatPushEvent.effect === "allow" && seatPushEvent.message === undefined,
+	);
+	const abstainAudit = getRecentAuditEntries(20).find((entry) => entry.tool === "permission.ask" && entry.phase === "decision" && entry.reason === "deferred_to_execute_before");
+	check(
+		"an abstention is journaled as deferred to execute.before, not as a plain allow",
+		abstainAudit !== undefined &&
+			abstainAudit.policyDecision?.status === "needs_approval" &&
+			abstainAudit.policyDecision?.code === "remote_state_unchecked" &&
+			(abstainAudit.input as any)?.deferred === "execute.before",
+	);
+	seatCleanup?.();
+	if (prevSeatDataHome === undefined) delete process.env.XDG_DATA_HOME;
+	else process.env.XDG_DATA_HOME = prevSeatDataHome;
+	rmSync(seatHookRepo, { recursive: true, force: true });
+}
+
 // ── V2 adopt-now surfaces: command, read-only pruning, worktrees, MCP ──
 // Four additive V2 API adoptions, each tested for its narrowing direction:
 // the command adds an operator surface, pruning removes tools, worktree cleanup