opencode-workflow-guard 1.19.1 → 1.19.2

package/docs/policies.md

@@ -4,6 +4,8 @@
 
 On OpenCode 1.x those hooks are `tool.execute.before`, `experimental.session.compacting`, `shell.env`, `permission.ask`, and `event` journaling. On OpenCode 2.x they are `tool.hook("execute.before"/"execute.after")`, `session.hook("context"/"compaction"/"prompt")`, `command.transform`, `permission.hook("evaluate")`, `shell.hook("create.before")`, and `event.subscribe()`. V1 plugin implementations do not run on OpenCode 2. The two lists therefore describe separate entrypoints, not alternatives for the same host.
 
+**A V2 event handler runs only if the host delivers its type.** `ctx.event.subscribe()` is served from `EventManifest.ServerDefinitions`. A type that appears in `EventManifest.Definitions` but not in `ServerDefinitions` is never delivered, so a handler for it is dead code even though it compiles and looks live. Check every `event.type` comparison against that manifest before relying on it. The test suite enforces this structurally: a scan of `src/lib/v2-plugin.ts` asserts every compared literal is delivered.
+
 This is a policy and enforcement layer, not an agent harness. Policies may constrain actions, record or explain decisions, and preserve bounded context. They do not plan, prioritize, delegate, or autonomously sequence work. Where Workflow Guard resumes an idle session, it only enforces already-owned todo lifecycle state. It does not choose what the agent works on next.
 
 ---
@@ -19,7 +21,7 @@ This is a policy and enforcement layer, not an agent harness. Policies may const
   - **Read-only escape:** A task whose text carries `[read-only]`, also `[read_only]` or `[read only]`, completes without a mutation. Review, investigation, and reading are legitimate work that changes no file. The marker is an annotation, not part of task identity, so it can be appended to an already-planned task without reading as a deletion. Every use is journaled as `todo_completed_read_only`, so relabeling real work as read-only stays visible in the audit trail. In a repository with no detectable verify command, that journal is the only counterweight. Work that was deliberately dropped uses `cancelled` instead.
   - `guard_status` reports `taskEvidence` (`active`, `completed`, `tasksWithoutRecordedWork`, `readOnlyTasks`), so the requirement is visible before it blocks anything. This is not task authority. Fresh verification evidence and the review gate remain the authority on finalization.
 - **Todo Capability Visibility:** Because the gate depends on the host exposing `todowrite` at all, `guard_status` reports `todoCapability` (`available` / `unavailable` / `unknown`). A fail-open gate is therefore visible rather than decorative.
-- **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.
+- **No Silent Early Exit:** When an owning session reaches the idle state with unfinished native todos, the guard asynchronously asks OpenCode to resume the existing run. That trigger is `session.status` with `status.type === "idle"` or the deprecated `session.idle`; both are in `EventManifest.ServerDefinitions`, and which one the server publishes is not settled, so neither is relied on alone. A host that emits both for one transition still produces a single continuation prompt, because the send holds a per-session in-flight lock. 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) suspend automatic continuation for that session until genuine user input arrives, mirroring the ralph `user_stopped` semantics. On OpenCode 2 this is driven by `session.execution.interrupted`, and only reason `user` suspends: `shutdown`, `superseded`, and `inactivity` are host-lifecycle events, not user intent, and they leave continuation state alone. 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.
 - **Subagent Inheritance & Role Confinement:** Subagents inherit active tasks from their parent session via the `parentID` hierarchy. Subagents spawned with read-only roles (`reviewer`, `planner`, `advisor`, `critic`, `explorer`, `scout`, `evaluator`) are hard-confined. File mutations, lifecycle tools, and mutating shell commands are strictly blocked. On OpenCode 2 the confinement is two-layered. `session.hook("context")` deletes the mutating tools (`write`, `edit`, `patch`, `apply_patch`, `shell`, `bash`, `execute`, `todowrite`, `subagent`/`task`, worktree lifecycle tools) from that role's per-request tool snapshot. `execute.before` stays as the backstop for tools supplied outside the snapshot, such as ACP agents and nested Code Mode calls. The pruning is journaled as `session.context` / `read_only_role_tools_pruned`.
 - **Handoff Safety:** An idle subagent whose effective todos are inherited from its parent is not auto-continued. Inherited work belongs to the parent and can be handed back normally.
 - **Durable Planning Context Discovery:** `guard_next_tasks` prefers a repository-root `TODO.md`. When it is absent, it reads conventional `ROADMAP.md`, `PLAN.md`, `TASKS.md`, `BACKLOG.md`, their `docs/` counterparts, and Markdown files under `docs/plans/`. The tool exposes candidate planning context without selecting, prioritizing, or sequencing tasks. These files never replace OpenCode's native runtime todo state.
@@ -65,7 +67,7 @@ This is a policy and enforcement layer, not an agent harness. Policies may const
 - MCP tools that mutate live GitHub or Azure/DevOps systems (`create`, `update`, `delete`, `merge`, `push`, `close`, etc.) are blocked.
 - Server names are tokenized on all non-alphanumerics, so `mcp__azure-devops__...`, `mcp__gh__...` and flat legacy names (`azure_devops_*`) are matched.
 - Read-only tools (`get`, `list`, `search`, `query`, etc.) are permitted.
-- On OpenCode 2 the guarded server set is widened from the host's own MCP roster (`ctx.mcp.list()`), refreshed on `mcp.tools.changed`. A renamed or enterprise instance of a guarded product is therefore still matched. Widening is one-way by design: removing a server adds nothing, and the static token list stays the floor. Tool names are model-supplied text, and this is a live-system rail.
+- On OpenCode 2 the guarded server set is widened from the host's own MCP roster (`ctx.mcp.list()`), refreshed on `mcp.status.changed`. That is the delivered trigger: `mcp.tools.changed` is an ephemeral host-internal event absent from `EventManifest.ServerDefinitions`, so a handler for it never runs. A renamed or enterprise instance of a guarded product is therefore still matched, including a server that connects mid-session. Widening is one-way by design: removing a server adds nothing, and the static token list stays the floor. Tool names are model-supplied text, and this is a live-system rail.
 
 ### 6. Settings Tamper Guard
 - Prevents the agent from weakening its own permission gates **via shell or edit tools**:
@@ -110,7 +112,7 @@ This is a policy and enforcement layer, not an agent harness. Policies may const
 - 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.
+- 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 the idle trigger (`session.status` with `status.type === "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.
 - **Git State & Snapshot Binding:** Verification evidence records the current git commit hash (`git rev-parse HEAD`) and working tree status. If unverified edits or index modifications occur after verification, fresh verification is enforced.
 - **Untracked Special Entries:** The worktree fingerprint binds untracked symlinks by their target string. It follows git semantics, so re-pointing a link moves the fingerprint and changing the link target's contents does not. FIFOs and sockets are bound by path and mode. Unopenable entries are skipped with a `worktree-fingerprint` warning in the audit trail instead of voiding the whole fingerprint. One unreadable scratch symlink or `chmod 000` file can no longer make review or verification evidence permanently unfresh. The PR preflight names the actual cause when an approval cannot be matched: no fingerprint binding, fingerprint mismatch, or uncomputable fingerprint. It no longer shows the generic "review approval required". Documented tradeoff: the contents of a skipped entry are excluded from the fingerprint. A file that stays unreadable to the guard's user across the entire window can therefore change contents without moving the fingerprint. Any readability transition is fingerprint-visible (fail-closed), and each skip is named in the durable audit trail.
@@ -128,7 +130,7 @@ This is a policy and enforcement layer, not an agent harness. Policies may const
 - This prevents the agent from carrying live credentials by default. The user can still grant access through OpenCode's own permission system if a task genuinely needs it.
 
 ### 13. Command-Channel Audit
-- User-triggered slash commands (`command.executed` events) are journaled to the audit trail so agents cannot perform hidden work through a user-facing side channel.
+- User-triggered slash commands (`command.executed` events) are journaled to the audit trail so agents cannot perform hidden work through a user-facing side channel. **This audit is V1 only.** On V2 the type sits in `EventManifest.Definitions` but is absent from `ServerDefinitions`, so it is never delivered and no V2 handler can journal it. No delivered V2 event carries a slash-command invocation, so the audit is not re-routed there: `command.updated` reports registry config changes, not invocations.
 
 ### 14. Audit Trail & Permission Journaling
 - Every block and allow decision is appended to `~/.local/state/opencode/workflow-guard/workflow-guard.jsonl`, with XDG_STATE_HOME respected. Each record carries a timestamp, session id, tool name, decision, subagent and parent session attribution, and reason. This is a durable record.
@@ -153,8 +155,9 @@ This is a policy and enforcement layer, not an agent harness. Policies may const
 - Preserves policy-relevant context across session compactions without assigning, prioritizing, or sequencing tasks for the model.
 
 ### 16. TUI Visual Feedback & Static Status Badge
-- Emits real-time warning toasts to the user interface via `tui.showToast` whenever a guard policy blocks a tool call.
-- The companion TUI plugin (`workflow-guard-ui.ts`) keeps `Workflow Guard 🛡️` static in the prompt bar. Block details remain in the warning toast rather than changing badge content or color.
+- On OpenCode 1.x, emits real-time warning toasts to the user interface via `tui.showToast` whenever a guard policy blocks a tool call.
+- On OpenCode 2.x there is no client-side `tui.showToast` on the plugin's client shim, so block paths do not attempt a toast. The thrown tool-hook error carries the reason to the model, which is what the model actually acts on. A V2 session therefore has no toast surface, and the reason arrives as the call's failure message.
+- The companion TUI plugin (`workflow-guard-ui.ts`) keeps `Workflow Guard 🛡️` static in the prompt bar. Block details remain in the warning toast rather than changing badge content or color. That companion is installed separately and is not part of the V2 server entrypoint.
 
 ### 17. Secret-File READ Block & Safe Schema Masking
 - Blocks reading sensitive credential files through the `read` tool, shell commands, or inline interpreter payloads. The credential patterns are `.env*`, `*.pem`, `*.key`, `id_rsa*`, `id_ed25519*`, `*kubeconfig*`, `*credentials*.json`, and `service-account*.json`. The shell commands are `cat`, `less`, `more`, `grep`, `awk`, `head`, `tail`, and `base64`. Interpreter payload examples are `python3 -c "open('.env')"` and `bash -c 'cat id_rsa'`.
@@ -203,7 +206,7 @@ This is a policy and enforcement layer, not an agent harness. Policies may const
 - **A failed research attempt never accrues debt.** Only non-research failures count. Otherwise a flaky or rate-limited search would deepen the block the agent is trying to escape. The floor would then deadlock a session that followed its own advice.
 - **Research recognition:** the builtin names (`websearch`, `webfetch`, and common aliases) match outright. MCP sources match on documented server names, so `mcp__context7__*`, `mcp__deepwiki__*`, `mcp__tavily__*`, `mcp__brave__*`, and similar docs servers count. A guard inspection tool or a generic file reader cannot clear the debt by name accident. Add an unrecognised server with `researchTools` in project config, or `WORKFLOW_GUARD_RESEARCH_TOOLS` (comma-separated name fragments).
 - Prior art: iterative grounding / De-Hallucinator (arXiv 2401.01701), knowledge-lookup gates for agent writes, and deterministic supersession (STALE, arXiv 2605.06527). Failure-mode context: false/illusory completion (agents self-report done) and temporal obsolescence of training data.
-- Enabled **by default** to force the failover. Disable with `.opencode/workflow-guard.json` (`requireLiveDocs: false`) or `WORKFLOW_GUARD_REQUIRE_LIVE_DOCS=0`. Raise or lower the trigger with `liveDocFailureThreshold` or `WORKFLOW_GUARD_LIVE_DOC_THRESHOLD`. An unparseable, zero, or negative threshold falls back to the default of 3, so a typo cannot silently disable the floor. Decisions are journaled (`reason: live_docs_research_floor`) under both entrypoints. On OpenCode 1.x block feedback also reaches `client.app.log` at warn level. OpenCode 2 has no server-side log API, so V2 journals the decision and toasts instead.
+- Enabled **by default** to force the failover. Disable with `.opencode/workflow-guard.json` (`requireLiveDocs: false`) or `WORKFLOW_GUARD_REQUIRE_LIVE_DOCS=0`. Raise or lower the trigger with `liveDocFailureThreshold` or `WORKFLOW_GUARD_LIVE_DOC_THRESHOLD`. An unparseable, zero, or negative threshold falls back to the default of 3, so a typo cannot silently disable the floor. Decisions are journaled (`reason: live_docs_research_floor`) under both entrypoints. On OpenCode 1.x block feedback also reaches `client.app.log` at warn level and a warning toast. OpenCode 2 has no server-side log API and no client toast, so V2 journals the decision and throws it as the call's failure message.
 - **Known limit:** Code Mode `execute` is not gated, because the nested tools it calls do not pass through guard hooks. A session that reaches the floor can still mutate through that path, the same way it can through an unmodelled indirection described under Known Limits.
 - **Prerequisite:** the acting agent must be allowed to call a research tool. An agent whose toolset denies `websearch`/`webfetch` and exposes no MCP docs server cannot satisfy the floor. Grant one, or the agent will (correctly) stall on the block. This is an opt-out-able default for that reason.
 

package/docs/testing.md

@@ -56,6 +56,7 @@ npm run test:all
 | **V2 Permission Seat Abstention** | Verifies the simulated seat denies a real finding, abstains on a decision it cannot make instead of denying, never upgrades a configured `ask`, and journals the abstention as `deferred_to_execute_before` with the preserved decision. Covers both the remote-probe deferral (`remote_state_unchecked`) and the cwd-dependent deferral (`repository_unidentified`). |
 | **Worktree-Aware Git Verdicts** | Verifies a cwd-dependent push or PR creation abstains with `repository_unidentified` instead of being judged against the session-bound checkout, that a non-checkout finding (`cat .env`) in the same compound command is still denied, that an explicit `-C` still runs the core, that a push to `main`/`master` is denied regardless of working directory while a push to a configured `protectedBranches` destination defers, that an explicitly named protected checkout is denied, that an explicitly named repository outside the workspace stays a boundary finding, and that a journaled deferral carries its own code. Also verifies that a `GIT_DIR=` value inside a commit message is not read as a repository claim while a real assignment, including through `env`/`sudo`/`timeout` wrappers, is, that an unresolvable repository selection (`git -C $OTHER_REPO`) stays a boundary block even inside a git workspace, and that a host session move rebinds only on a genuine move rather than on every `session.updated`. Also verifies that a relative shell mutation or git write in a `workdir` outside the workspace is blocked while a read-only command there, and a mutation in a linked worktree of the same repository, are allowed. Also verifies in-command `cd` tracking: `cd <foreign> && git commit`, `cd <foreign> && echo x > f` are blocked while a `cd` there followed by a read stays allowed, a newline-separated `cd <foreign>` moves the tree of the lines that follow for a removal, a git write, and a redirect, while its read-only form stays allowed, a heredoc shell body that cds into a foreign repository is blocked for a removal and a git write, including when the body is unterminated, read by `source`, or piped into a shell or an uncommon executor such as `ash`, `busybox sh`, `make -f -`, or `xargs sh -c`, while a body piped into a known filter such as `grep` stays prose, a body reaching a shell through a later pipeline stage (`| grep x | sh`, `| cat | bash`, `| tee /dev/null | sh`), a body delivered through `|&` to a shell (`|& sh`, `|& ash`) while `|&` into a filter and `||` stay prose, is blocked, a body consumed by a program that can run a command named in its own arguments (`sed 'e'`, `sed -n '1e echo hi'`, `awk '{system($0)}'`, `sort --compress-program`) is blocked, a data heredoc quoting a blocked command shape or a bare `rm` line stays writable and a second body on the same header line stays data, a quoted `"<<"` does not mask a later interpreter payload, a tilde repository selector (`git -C ~/repo`, `git -C~/repo`, `~root/path`) expands through the shell instead of naming a literal `~` directory inside the workspace, an assignment-prefixed `eval` moves the tree of later segments while a harmless one does not, an in-command `cd` into a workspace subdirectory is judged where it lands rather than as a foreign tree, an in-command `cd` into a linked worktree is allowed, an indeterminate `cd $VAR` before a write fails closed, `env -C <foreign> git commit` is blocked, a `cd` inside a grouping subshell does not move a later segment's tree, and nested payloads are judged by their own tree (`bash -c 'cd <foreign> && git commit'` blocked, `execSync(..., {cwd: '<foreign>'})` blocked, `process.chdir('<foreign>')` before a write blocked, an unrelated `{cwd: …}` object key not treated as a working directory, `regex.exec(str, {cwd})` not treated as a spawn, a non-literal `{cwd: process.env.X}` failing closed, a payload launched from an indeterminate `cd` failing closed while its read-only form stays allowed, a doubly nested launcher re-planned to its innermost tree, a payload `git -C` into a foreign repository blocked while a linked worktree stays allowed, a spawn `cwd` after a nested call still read as the working directory, a `pushd` inside a grouping subshell not leaking into a later outer `popd`, a `pushd +N`/`-n` rotation failing closed before a mutation while its read-only form stays allowed, a `cd` inside a `then`/`do`/`case`/brace-group body moving the tree of later segments, a `cd ~user` not read as a workspace-relative path, and a `--head` token inside a quoted PR body not read as the source branch, in-workspace and linked-worktree payloads allowed). |
 | **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`. |
+| **V2 Delivered Event Handlers** | Verifies the deny contract the adapter provides (a rejected `execute.before` surfaces as a tool error carrying the reason), that a tool error recorded from `execute.after` accrues failure debt and raises the circuit-breaker path while a success clears it, that `session.execution.interrupted` with reason `user` suspends continuation while a host-lifecycle reason does not, that an idle `session.status` continues the session while `busy` does not, that the deprecated `session.idle` still continues it because the published idle type is not settled, that both idle types for one transition still yield a single continuation prompt, and that a delivered `mcp.status.changed` refreshes the guarded inventory with additive-only widening. A structural meta-test scans `src/lib/v2-plugin.ts` for every `event.type === "<literal>"` comparison and asserts each literal exists in `EventManifest.ServerDefinitions`, so a handler built on a type the host never delivers fails the suite instead of shipping dead. It also asserts the scan matched a nonzero number of literals, so a broken regex cannot pass vacuously. |
 | **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. |
 | **Dogfood Gate (Policy 27)** | Verifies the gate stays off until a repository opts in, that PR creation is blocked without fresh evidence and allowed with it, that a tracked edit and a new commit each invalidate the record with a named cause, that a HOLD is never durable and removes that host's cached pass so a restart cannot re-satisfy the gate, that a same-millisecond HOLD and PASS resolve to the HOLD in the durable cache so a restart stays unsatisfied, that a later pass on another host cannot resurrect an evicted one, that a HOLD in a cold process or in another workspace leaves unrelated hosts' passes intact, that an out-of-matrix HOLD is not reported as the blocking cause, that a `pass` is refused when any check is skipped or the check list is empty, that a HOLD must name a taxonomy class, that an actor session cannot record its own verdict, that the deploy matrix needs one fresh pass per host, that a newer HOLD on a host reopens the gate, that the PR audit names every covered host, and that per-host retention cannot evict another host's pass. |

package/package.json

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

package/src/lib/guard-api.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared guard entry surface, host-agnostic.
+ *
+ * These three helpers used to live in `workflow-guard.ts`, the V1 entrypoint.
+ * `lib/v2-plugin.ts` imported them from there, which created an import cycle:
+ * `workflow-guard.ts` imports `WorkflowGuardV2` from `lib/v2-plugin.ts`, so the
+ * cycle dragged the whole V1 file, `@opencode-ai/plugin`, and its
+ * `@opencode-ai/sdk` subtree into a V2 host.
+ *
+ * They live here so both entrypoints import a leaf module instead. This is a
+ * pure move: behavior, audit fields, and return values are unchanged.
+ * `workflow-guard.ts` keeps re-exporting them, because the test harness imports
+ * that public surface.
+ */
+
+import { guardToolCallImpl } from "./guard-dispatcher.ts";
+import { getSdkClient, runWithRuntimeState, lastMutationTimestamp, lastVerify } from "./state.ts";
+import { logDecision } from "./audit.ts";
+import { extractRecordTargetPath } from "./utils.ts";
+import type { PolicyDecision } from "./types.ts";
+import { EDIT_TOOL_NAMES } from "../policies/todo.ts";
+
+/**
+ * Public guard entry point. Audits every decision (block or allow) to a
+ * durable JSONL file before returning.
+ */
+export async function guardToolDecision(
+	toolName: string,
+	input: unknown,
+	context?: { sessionID?: string; callID?: string; worktree?: string; directory?: string; agent?: string },
+): Promise<PolicyDecision> {
+	const customRoot = context?.worktree || context?.directory;
+	const runImpl = () => guardToolCallImpl(toolName, input, context);
+	return customRoot
+		? await runWithRuntimeState(customRoot, getSdkClient(), runImpl)
+		: await runImpl();
+}
+
+/** Convenience wrapper: the block reason, or `undefined` when allowed. */
+export async function guardToolCall(
+	toolName: string,
+	input: unknown,
+	context?: { sessionID?: string; callID?: string; worktree?: string; directory?: string; agent?: string },
+): Promise<string | undefined> {
+	const decision = await guardToolDecision(toolName, input, context);
+	const allowLive = process.env.WORKFLOW_GUARD_ALLOW_LIVE === "1";
+	const isMutation = EDIT_TOOL_NAMES.has(toolName);
+	const targetPath = extractRecordTargetPath(input);
+	logDecision(toolName, input, context, decision, {
+		mutation: isMutation,
+		targetPath,
+		allowLive,
+		verification: lastVerify
+			? {
+					command: lastVerify.command,
+					passed: lastVerify.passed,
+					fresh: lastVerify.timestamp >= lastMutationTimestamp,
+					durationMs: lastVerify.durationMs,
+				}
+			: undefined,
+	});
+	return decision.status === "allowed" ? undefined : decision.message;
+}
+
+/**
+ * Build the bounded compaction context from the operational state plus the
+ * priority blocks, capping the total at `maxChars` (default 8,000).
+ */
+export function buildCompactionContext(operationalState: string, priorityBlocks: string[], maxChars = 8_000): string {
+	if (!Number.isFinite(maxChars) || maxChars < 0 || !Number.isInteger(maxChars)) {
+		throw new RangeError("maxChars must be a non-negative finite integer");
+	}
+	const truncate = (value: string, limit: number): string => {
+		let end = Math.min(value.length, limit);
+		if (end > 0 && end < value.length && /[\uD800-\uDBFF]/.test(value[end - 1])) end -= 1;
+		return value.slice(0, end);
+	};
+	let context = truncate(operationalState, maxChars);
+	for (const block of priorityBlocks) {
+		const remaining = maxChars - context.length - 2;
+		if (remaining <= 0) break;
+		context += `\n\n${truncate(block, remaining)}`;
+	}
+	return context;
+}

package/src/lib/permission-seat.ts

@@ -205,8 +205,10 @@ export async function evaluatePermissionSeat(
 
 	// `<server>_<tool>` MCP actions: only the guarded live-system servers are
 	// mapped (GitHub/Azure DevOps), matching the execute.before MCP policy.
+	// Cache the host action's mutability to avoid recomputing it on every iteration.
+	const actionIsMutating = mcpMutationTool(event.action);
 	for (const resource of resources) {
-		if (!mcpMutationTool(event.action) && !mcpMutationTool(resource)) continue;
+		if (!actionIsMutating && !mcpMutationTool(resource)) continue;
 		const decision = await decide(event.action, {});
 		return seatVerdict(decision, event.action) ?? { effect: "allow", mappedTool: event.action };
 	}

package/src/lib/tool-descriptions.ts

@@ -0,0 +1,36 @@
+/**
+ * Single source of truth for the builtin tool-description suffixes.
+ *
+ * Both entrypoints append the same text: the V1 `tool.definition` hook in
+ * `workflow-guard.ts` and the V2 `ctx.tool.transform` enrichment in
+ * `lib/v2-plugin.ts`. Keeping one copy prevents the two hosts from drifting
+ * apart, which would make a model's expectations depend on which host it runs
+ * on.
+ *
+ * Each suffix carries a marker. The marker is the idempotence key: a
+ * description already containing it is left untouched, so a second plugin
+ * instance (or a re-applied transform) cannot append the text twice.
+ */
+
+export const TODOWRITE_MARKER = "verification evidence";
+export const TODOWRITE_SUFFIX =
+	"\n\nWorkflow Guard lifecycle: use todowrite to plan before working - it is the only view of progress the operator has, and every file mutation is gated on it. Each call replaces the complete task list: preserve every pending/in_progress task in subsequent updates until you explicitly mark it completed or cancelled, and do not omit active tasks when adding new work. A task may be marked completed only after its own work is recorded: the guard blocks a completion that has no file mutation in that task's active window, and one mutation cannot vouch for several completions. If a task is genuinely read-only (review, investigation, reading), append the marker `[read-only]` to its text; every such use is journaled. Use `cancelled` for work that was deliberately dropped. Marking every task completed triggers the finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply. Proactively call guard_next_tasks when planning work to discover existing roadmap/TODOs, and guard_status to check outstanding requirements.";
+
+export const EDIT_MARKER = "Workflow Guard requirement";
+export const EDIT_SUFFIX =
+	"\n\nWorkflow Guard requirement: Modifications require an active task in todowrite (status pending or in_progress), a feature branch (edits on main/master are blocked), and a prior read of existing files in the current session.";
+
+export const SUBAGENT_MARKER = "Workflow Guard subagent guidance";
+export 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.";
+
+/**
+ * Append `suffix` unless the description already carries `marker`.
+ *
+ * Returns `undefined` when the suffix is already present, so a caller can tell
+ * "nothing to do" from "wrote an empty string".
+ */
+export function appendToolDescriptionSuffix(description: string, suffix: string, marker: string): string | undefined {
+	if (description.includes(marker)) return undefined;
+	return description + suffix;
+}

package/src/lib/types.ts

@@ -19,8 +19,14 @@ export interface TodoSdkClient {
 		get?: (opts: { path: { id: string } }) => Promise<{ data?: { parentID?: unknown; title?: unknown; time?: { idle?: unknown } } }>;
 		promptAsync?: (opts: {
 			path: { id: string };
-			body: { messageID?: string; parts: Array<{ type: "text"; text: string; synthetic?: boolean }> };
+			body: { messageID?: string; parts: Array<{ type: "text"; text: string; synthetic?: boolean }>; delivery?: "steer" | "queue"; resume?: boolean };
 		}) => Promise<unknown>;
+		/**
+		 * V2 only. The shim forwards a synthetic continuation through here, and
+		 * the presence of this method is what marks a V2 client in
+		 * `policies/continuation.ts` for `delivery`/`resume` support.
+		 */
+		synthetic?: (opts: { sessionID: string; text: string; delivery?: "steer" | "queue"; resume?: boolean }) => Promise<unknown>;
 	};
 	tui?: {
 		showToast?: (opts: { body: { title?: string; message: string; variant?: string } }) => Promise<unknown>;

package/src/lib/v2-plugin.ts

@@ -10,7 +10,7 @@
  * - `ctx.command.transform` for the server-side `/guard-status` command
  * - `ctx.permission.hook("evaluate")` for the pre-execution deny seat
  * - `ctx.shell.hook("create.before")` for env scrubbing
- * - `ctx.mcp.list()` plus `mcp.tools.changed` for the guarded-server inventory
+ * - `ctx.mcp.list()` plus `mcp.status.changed` for the guarded-server inventory
  * - `ctx.event.subscribe()` for tool outcomes, session lifecycle, and claims-vs-evidence
  *
  * The V1 SDK client surface (`TodoSdkClient`) is satisfied by an adapter so
@@ -22,7 +22,7 @@ import { Message } from "@opencode/ai/effect";
 import { z } from "zod";
 import { join, resolve } from "node:path";
 import type { TodoSdkClient } from "./types.ts";
-import { detectTodoCapability, recordTodoCapability, recordedTodoCapability, scanSessionTodos, toolPartName } from "./v2-todo.ts";
+import { detectTodoCapability, recordTodoCapability, recordedTodoCapability, scanSessionTodos } from "./v2-todo.ts";
 import { findGitRoot, reloadProjectConfig } from "./project-config.ts";
 import {
 	setWorkspaceRoot,
@@ -60,7 +60,7 @@ import { secretIn } from "../policies/secrets.ts";
 import { createCustomTools, buildWorkflowGuardSystemGuidance } from "./custom-tools.ts";
 import { isMutatingSurfaceTool, isReadOnlyRole, SHELL_TOOL_NAMES } from "./guard-dispatcher.ts";
 import { ToolInvocationLifecycle } from "./tool-lifecycle.ts";
-import { ToolOutcomeTracker, type ToolOutcomePart } from "./tool-outcomes.ts";
+import { ToolOutcomeTracker } from "./tool-outcomes.ts";
 import { EDIT_TOOL_NAMES, fetchParentSession, fetchParentSessionID, effectiveTodos } from "../policies/todo.ts";
 import { currentGitBranch, isProtectedBranchName } from "../policies/git.ts";
 import { checkCompletionClaims } from "../policies/completion.ts";
@@ -72,11 +72,21 @@ import { editTargets, runPostEditValidators, snapshotFile, type FileSnapshot } f
 import { extractCommands, splitShellSegments } from "./shell.ts";
 import { expandShellTargetPath, isPathOutsideWorkspace, OPENCODE_SCRATCH_DIR, redirectMutationsIn } from "../policies/boundary.ts";
 import { audit, summarizeInput } from "./audit.ts";
-import { asRecord, showBlockToast, isSensitiveEnvKey } from "./utils.ts";
+import { asRecord, isSensitiveEnvKey } from "./utils.ts";
 import { loadedPluginVersion } from "./version.ts";
-import { clearContinuationState, continueUnfinishedSession, isGeneratedContinuationMessage, recordUserMessage } from "../policies/continuation.ts";
+import { clearContinuationState, continueUnfinishedSession, isGeneratedContinuationMessage, markInterrupted, recordUserMessage } from "../policies/continuation.ts";
 import { createRecoveryCheckpoint, finalizeRecoveryCheckpoint, nextRecoveryRun } from "./checkpoint.ts";
-import { buildCompactionContext, evaluateDogfoodGate, guardToolCall } from "../workflow-guard.ts";
+import { buildCompactionContext, guardToolCall } from "./guard-api.ts";
+import { evaluateDogfoodGate } from "./dogfood.ts";
+import {
+	appendToolDescriptionSuffix,
+	EDIT_MARKER,
+	EDIT_SUFFIX,
+	SUBAGENT_MARKER,
+	SUBAGENT_SUFFIX,
+	TODOWRITE_MARKER,
+	TODOWRITE_SUFFIX,
+} from "./tool-descriptions.ts";
 import { registerPluginInstance, releasePluginInstance } from "./plugin-instance.ts";
 import { claimToolCall, releaseToolCallClaim } from "./call-claims.ts";
 import { evaluatePermissionSeat } from "./permission-seat.ts";
@@ -94,11 +104,12 @@ type V2Context = Plugin.Context;
 // 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
-	// console logging and showBlockToast becomes a no-op. Block reasons still
-	// reach the agent through the thrown tool-hook error; keep this adapter
-	// from logging anything beyond guard decision summaries.
-	return {
+	// V2 has no server-side log API or TUI surface. The client shim supplies
+	// only { app, session, lsp }, so there is no `tui.showToast` to call: block
+	// paths on V2 do not attempt a toast and rely on the thrown hook error,
+	// which is what actually reaches the model. Keep this adapter from logging
+	// anything beyond guard decision summaries.
+	const client: TodoSdkClient = {
 		app: {
 			log: async ({ body }) => {
 				try {
@@ -112,10 +123,32 @@ function createV2SdkClient(ctx: V2Context): TodoSdkClient {
 				const session = await ctx.session.get({ sessionID: path.id });
 				return { data: { parentID: (session as { parentID?: string }).parentID, title: (session as { title?: string }).title } };
 			},
+			// V2 only: forwards a synthetic message with `delivery`/`resume`.
+			// Its presence is also what marks this client as V2 for
+			// `policies/continuation.ts`, which is why the values travel here
+			// instead of through the shared `promptAsync` body type.
+			synthetic: async (opts) => {
+				await ctx.session.synthetic({
+					sessionID: opts.sessionID,
+					text: opts.text,
+					...(opts.delivery ? { delivery: opts.delivery } : {}),
+					...(opts.resume === undefined ? {} : { resume: opts.resume }),
+				});
+			},
 			promptAsync: async (opts) => {
-				for (const part of opts.body.parts) {
+				const body = opts.body as {
+					parts: Array<{ type: "text"; text: string; synthetic?: boolean }>;
+					delivery?: "steer" | "queue";
+					resume?: boolean;
+				};
+				for (const part of body.parts) {
 					if (part.synthetic) {
-						await ctx.session.synthetic({ sessionID: opts.path.id, text: part.text });
+						await client.session!.synthetic!({
+							sessionID: opts.path.id,
+							text: part.text,
+							...(body.delivery ? { delivery: body.delivery } : {}),
+							...(body.resume === undefined ? {} : { resume: body.resume }),
+						});
 					} else {
 						await ctx.session.prompt({ sessionID: opts.path.id, text: part.text });
 					}
@@ -124,19 +157,9 @@ function createV2SdkClient(ctx: V2Context): TodoSdkClient {
 		},
 		lsp: {},
 	};
+	return client;
 }
 
-// ── Builtin tool description enrichment ───────────────────────────────────────
-
-const TODOWRITE_SUFFIX =
-	"\n\nWorkflow Guard lifecycle: use todowrite to plan before working - it is the only view of progress the operator has, and every file mutation is gated on it. Each call replaces the complete task list: preserve every pending/in_progress task in subsequent updates until you explicitly mark it completed or cancelled, and do not omit active tasks when adding new work. A task may be marked completed only after its own work is recorded: the guard blocks a completion that has no file mutation in that task's active window, and one mutation cannot vouch for several completions. If a task is genuinely read-only (review, investigation, reading), append the marker `[read-only]` to its text; every such use is journaled. Use `cancelled` for work that was deliberately dropped. Marking every task completed triggers the finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply. Proactively call guard_next_tasks when planning work to discover existing roadmap/TODOs, and guard_status to check outstanding requirements.";
-
-const EDIT_SUFFIX =
-	"\n\nWorkflow Guard requirement: Modifications require an active task in todowrite (status pending or in_progress), a feature branch (edits on main/master are blocked), and a prior read of existing files in the current session.";
-
-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.
@@ -155,9 +178,9 @@ const SUBAGENT_SUFFIX =
 // - 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" },
-	{ candidates: ["task", "subagent"], suffix: SUBAGENT_SUFFIX, marker: "Workflow Guard subagent guidance" },
+	{ candidates: ["todowrite"], suffix: TODOWRITE_SUFFIX, marker: TODOWRITE_MARKER },
+	{ candidates: [...EDIT_TOOL_NAMES], suffix: EDIT_SUFFIX, marker: EDIT_MARKER },
+	{ candidates: ["task", "subagent"], suffix: SUBAGENT_SUFFIX, marker: SUBAGENT_MARKER },
 ];
 
 // ── Setup ─────────────────────────────────────────────────────────────────────
@@ -256,8 +279,8 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 			for (const id of target.candidates) {
 				editor.update(id, (tool) => {
 					const description = typeof tool.description === "string" ? tool.description : "";
-					if (description.includes(target.marker)) return;
-					tool.description = description + target.suffix;
+					const next = appendToolDescriptionSuffix(description, target.suffix, target.marker);
+					if (next !== undefined) tool.description = next;
 				});
 			}
 		}
@@ -300,7 +323,6 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 			});
 			if (reason !== undefined) {
 				releaseToolCallClaim(instance.key, event.sessionID, event.id, event.tool);
-				await showBlockToast(reason);
 				const failureCount = event.sessionID ? toolOutcomes.getFailureCount(event.sessionID) : 0;
 				const circuitBreakerSuffix = failureCount >= 2
 					? "\n\n[Workflow Guard Circuit Breaker: Repeated failures detected in this session. Stop attempting alternative workarounds or shell laundering. Address the required step above directly, or inspect policy details with guard_status or guard_why.]"
@@ -316,7 +338,6 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 					const researchReason = liveDocsGatingReason(event.sessionID, event.tool, threshold, getResearchToolPatterns(toolWorktree));
 					if (researchReason !== undefined) {
 						releaseToolCallClaim(instance.key, event.sessionID, event.id, event.tool);
-						await showBlockToast(researchReason);
 						console.log(`[workflow-guard] warn: ${researchReason}`);
 						audit({
 							ts: new Date().toISOString(),
@@ -383,19 +404,13 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 	await ctx.tool.hook("execute.after", async (event) => {
 		releaseToolCallClaim(instance.key, event.sessionID, event.id, event.tool);
 		const startedAt = toolLifecycle.finish(event.sessionID, event.id);
-		const outcome = toolOutcomes.recordFallbackCompleted(event.sessionID, event.id, event.tool, startedAt === undefined ? undefined : Date.now() - startedAt);
-		if (outcome) {
-			audit({
-				ts: new Date().toISOString(),
-				sessionID: outcome.sessionID,
-				callID: outcome.callID,
-				tool: outcome.tool,
-				decision: "allow",
-				phase: "outcome",
-				durationMs: outcome.durationMs,
-				reason: outcome.status,
-			});
-		}
+		recordV2ToolOutcome(toolOutcomes, effectiveRoot, {
+			tool: event.tool,
+			sessionID: event.sessionID,
+			callID: event.id,
+			status: event.status,
+			error: event.status === "error" ? event.error : undefined,
+		}, startedAt);
 		releaseFileClaims(event.sessionID, event.id);
 		if (event.tool === "read") {
 			const observation = toolLifecycle.takeReadObservation(event.sessionID, event.id);
@@ -721,93 +736,127 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 	};
 };
 
+// ── Tool outcome telemetry ────────────────────────────────────────────────────
+
+/**
+ * Record one tool call's terminal outcome from `execute.after`.
+ *
+ * The former `session.message.content.updated` subscription never fired: that
+ * type is absent from `EventManifest.ServerDefinitions`, so no tool part was
+ * ever mapped and the repeated-failure circuit breaker plus the Policy 25
+ * research floor both read an always-zero count. `execute.after` does fire,
+ * including for a failed call, because the host triggers the hook with
+ * `status: "error"` before it rethrows. The error's own message feeds the
+ * tracker's signature, so repeat detection keys on what the model actually saw.
+ */
+function recordV2ToolOutcome(
+	toolOutcomes: ToolOutcomeTracker,
+	effectiveRoot: string,
+	event: {
+		tool: string;
+		sessionID?: string;
+		callID: string;
+		status?: "completed" | "error";
+		error?: { message?: string } | string;
+	},
+	startedAt?: number,
+): void {
+	const status = event.status;
+	if (status !== "completed" && status !== "error") {
+		// The host's `execute.after` always carries a terminal status. A partial
+		// event from a harness or stub leaves it unknown, so record the
+		// optimistic completion that this hook used to record unconditionally
+		// rather than dropping the call from telemetry entirely. The audit row
+		// is kept here so this path does not lose the coverage it had before
+		// outcomes moved onto `execute.after`.
+		const fallback = toolOutcomes.recordFallbackCompleted(event.sessionID ?? "", event.callID, event.tool, startedAt === undefined ? undefined : Date.now() - startedAt);
+		if (fallback) {
+			audit({
+				ts: new Date().toISOString(),
+				sessionID: fallback.sessionID,
+				callID: fallback.callID,
+				tool: fallback.tool,
+				decision: "allow",
+				phase: "outcome",
+				durationMs: fallback.durationMs,
+				reason: fallback.status,
+			});
+		}
+		return;
+	}
+	const error = typeof event.error === "string" ? event.error : event.error?.message;
+	const outcome = toolOutcomes.record({
+		type: "tool",
+		sessionID: event.sessionID,
+		callID: event.callID,
+		tool: event.tool,
+		state: {
+			status,
+			error,
+			time: startedAt === undefined ? undefined : { start: startedAt, end: Date.now() },
+		},
+	});
+	if (!outcome) return;
+	// Policy 25 research floor (V1 parity): failures accrue debt; successful
+	// live-source lookups clear it. A failed research attempt never accrues
+	// debt, so a flaky lookup cannot deepen the block it was meant to escape.
+	if (isResearchTool(outcome.tool, getResearchToolPatterns(getSessionBoundWorkspace(outcome.sessionID) || effectiveRoot))) {
+		if (outcome.status !== "error") recordResearchLookup(outcome.sessionID);
+	} else if (outcome.status === "error") {
+		recordLiveDocsFailure(outcome.sessionID);
+	}
+	audit({
+		ts: new Date().toISOString(),
+		sessionID: outcome.sessionID,
+		callID: outcome.callID,
+		tool: outcome.tool,
+		decision: "allow",
+		phase: "outcome",
+		durationMs: outcome.durationMs,
+		reason: outcome.status,
+	});
+	if (outcome.status === "error" && outcome.repeatedFailureCount === 3) {
+		audit({
+			ts: new Date().toISOString(),
+			sessionID: outcome.sessionID,
+			callID: outcome.callID,
+			tool: outcome.tool,
+			decision: "allow",
+			phase: "event",
+			reason: "repeated-equivalent-failure:3",
+		});
+		console.log(`[workflow-guard] ${outcome.tool} failed equivalently 3 times in this session; change approach or inspect the underlying failure before retrying.`);
+	}
+}
+
 // ── Event handling ────────────────────────────────────────────────────────────
 
-interface V2EventState {
+export interface V2EventState {
 	effectiveRoot: string;
 	client: unknown;
 	toolLifecycle: ToolInvocationLifecycle;
 	toolOutcomes: ToolOutcomeTracker;
-	/** Re-read the host MCP roster after `mcp.tools.changed`. */
+	/** Re-read the host MCP roster after `mcp.status.changed`. */
 	refreshMcpInventory?: () => Promise<void>;
 }
 
-async function handleV2Event(
+export async function handleV2Event(
 	event: { type?: string; data?: unknown },
 	state: V2EventState,
 ): Promise<void> {
 	const { effectiveRoot, client, toolLifecycle, toolOutcomes } = state;
 
-	if (event.type === "mcp.tools.changed") {
-		// The host's server roster or one server's tool list changed. Re-read it
+	if (event.type === "mcp.status.changed") {
+		// A server's connection status settled (connected, failed, needs_auth,
+		// closed), which is when its tools become callable. Re-read the roster
 		// so a newly connected live-system server is guarded before its tools
-		// are callable. Widen-only: this can add tokens, never remove them.
+		// can be called. Widen-only: this can add tokens, never remove them.
+		// `mcp.resources.changed` is deliberately not a trigger: it reports
+		// resources, not tool availability.
 		await state.refreshMcpInventory?.();
 		return;
 	}
 
-	if (event.type === "session.message.content.updated") {
-		const data = event.data as { sessionID?: unknown; content?: unknown } | undefined;
-		const sessionID = typeof data?.sessionID === "string" ? data.sessionID : undefined;
-		if (!sessionID || !Array.isArray(data?.content)) return;
-		for (const part of data.content as Array<Record<string, unknown>>) {
-			if (part?.type !== "tool") continue;
-			const toolState = part.state as { status?: unknown; error?: { message?: string } | string } | undefined;
-			const status = toolState?.status;
-			if (status !== "completed" && status !== "error") continue;
-			// V2 keeps timing on the tool part itself (part.time), not inside state.
-			const partTime = part.time as { ran?: unknown; completed?: unknown } | undefined;
-			const start = typeof partTime?.ran === "number" ? partTime.ran : undefined;
-			const end = typeof partTime?.completed === "number" ? partTime.completed : undefined;
-			const mapped: ToolOutcomePart = {
-				type: "tool",
-				sessionID,
-				callID: part.id,
-				tool: toolPartName(part),
-				state: {
-					status,
-					error: typeof toolState?.error === "string" ? toolState.error : toolState?.error?.message,
-					time: { start, end },
-				},
-			};
-			const outcome = toolOutcomes.record(mapped);
-			if (outcome) {
-				// Policy 25 research floor (V1 parity): failures accrue debt;
-				// successful live-source lookups clear it. A failed research
-				// attempt never accrues debt, so a flaky lookup cannot deepen
-				// the block it was meant to escape.
-				if (isResearchTool(outcome.tool, getResearchToolPatterns(getSessionBoundWorkspace(outcome.sessionID) || effectiveRoot))) {
-					if (outcome.status !== "error") recordResearchLookup(outcome.sessionID);
-				} else if (outcome.status === "error") {
-					recordLiveDocsFailure(outcome.sessionID);
-				}
-				audit({
-					ts: new Date().toISOString(),
-					sessionID: outcome.sessionID,
-					callID: outcome.callID,
-					tool: outcome.tool,
-					decision: "allow",
-					phase: "outcome",
-					durationMs: outcome.durationMs,
-					reason: outcome.status,
-				});
-				if (outcome.status === "error" && outcome.repeatedFailureCount === 3) {
-					audit({
-						ts: new Date().toISOString(),
-						sessionID: outcome.sessionID,
-						callID: outcome.callID,
-						tool: outcome.tool,
-						decision: "allow",
-						phase: "event",
-						reason: "repeated-equivalent-failure:3",
-					});
-					console.log(`[workflow-guard] ${outcome.tool} failed equivalently 3 times in this session; change approach or inspect the underlying failure before retrying.`);
-				}
-			}
-		}
-		return;
-	}
-
 	if (event.type === "session.text.ended") {
 		const data = event.data as { sessionID?: unknown; text?: unknown } | undefined;
 		const sessionID = typeof data?.sessionID === "string" ? data.sessionID : undefined;
@@ -860,8 +909,36 @@ async function handleV2Event(
 		return;
 	}
 
-	if (event.type === "session.idle") {
-		const data = event.data as { sessionID?: unknown } | undefined;
+	if (event.type === "session.execution.interrupted") {
+		// `reason` is one of "user" | "shutdown" | "superseded" | "inactivity".
+		// Only "user" is user intent (Esc), so only it suspends automatic
+		// continuation. The other three are host-lifecycle events and must
+		// leave continuation state alone.
+		const data = event.data as { sessionID?: unknown; reason?: unknown } | undefined;
+		const sessionID = typeof data?.sessionID === "string" ? data.sessionID : undefined;
+		if (sessionID && data?.reason === "user") {
+			// Continuation state is keyed on the SDK client plus project root,
+			// so it must be reached inside the runtime state.
+			await runWithRuntimeState(effectiveRoot, client, () => markInterrupted(sessionID));
+		}
+		return;
+	}
+
+	// Idle is the trigger for automatic continuation. The host keeps two
+	// event types for it: `session.status` with `status.type === "idle"`, and
+	// the deprecated `session.idle`. Both are in
+	// `EventManifest.ServerDefinitions` on 2.0.15, 2.1.3, and 2.2.0, but which
+	// one the server actually publishes is not settled: the TUI derives idle
+	// from `session.execution.*` instead of consuming `session.status`, and an
+	// upstream report says `session.status` is declared but never published.
+	// Handling both keeps continuation working whichever one arrives, and adds
+	// no new trigger beyond what each host already emits. A host that emits
+	// both for one transition still sends a single prompt, because
+	// `continueUnfinishedSession` holds a per-session in-flight lock for the
+	// whole awaited send. The side effects keep their original order.
+	if (event.type === "session.status" || event.type === "session.idle") {
+		const data = event.data as { sessionID?: unknown; status?: { type?: unknown } } | undefined;
+		if (event.type === "session.status" && data?.status?.type !== "idle") return;
 		const sessionID = typeof data?.sessionID === "string" ? data.sessionID : undefined;
 		if (typeof sessionID === "string") {
 			releaseFileClaims(sessionID);
@@ -909,25 +986,8 @@ async function handleV2Event(
 		});
 		return;
 	}
-	// `command.executed` exists in the V2 event stream (`data: { name, sessionID,
-	// arguments, messageID }`) and carries what the V1 audit wanted: the slash
-	// command name, its arguments, and the session. It is journaled here rather
-	// than dropped, so a command that mutates workspace state stays attributable.
-	if (event.type === "command.executed") {
-		const data = event.data as { sessionID?: unknown; name?: unknown; arguments?: unknown } | undefined;
-		audit({
-			ts: new Date().toISOString(),
-			sessionID: typeof data?.sessionID === "string" ? data.sessionID : undefined,
-			tool: "command.executed",
-			decision: "allow",
-			phase: "event",
-			reason: typeof data?.name === "string" ? data.name : undefined,
-			input: summarizeInput({ name: data?.name, arguments: data?.arguments }),
-		});
-		return;
-	}
 	// Note on V1 events without a V2 counterpart:
 	// - `permission.updated`: replaced by `permission.asked`/`permission.replied` above.
-	// - `session.created`: exists in the V2 union but needed no V1 behavior beyond
-	//   the audit above; session state resets happen on `session.deleted`.
+	// - `session.created`: V2 journals no create event; session state resets on
+	//   `session.deleted`.
 }

package/src/policies/continuation.ts

@@ -19,6 +19,19 @@ type ContinuationState = {
 export type RalphOutcome = "running" | "completed" | "blocked" | "budget_exhausted" | "user_stopped";
 const states = new WeakMap<object, Map<string, ContinuationState>>();
 
+/**
+ * Whether the active client is the V2 shim, which can carry `delivery` and
+ * `resume` on a synthetic continuation. `session.synthetic` is the
+ * discriminator: the V2 shim supplies it, and the V1 SDK client does not
+ * declare it. `session.todo` is required alongside it only because this module
+ * reads todos through the same surface, so a client missing it cannot be the
+ * V2 shim for our purposes.
+ */
+function isV2Host(): boolean {
+	const session = getSdkClient()?.session as { synthetic?: unknown; todo?: unknown } | undefined;
+	return typeof session?.synthetic === "function" && typeof session?.todo === "function";
+}
+
 export async function waitForSessionTitle(sessionID: string): Promise<void> {
 	const session = getSdkClient()?.session;
 	if (typeof session?.get !== "function") return;
@@ -95,17 +108,34 @@ export async function continueUnfinishedSession(sessionID: string, settleTitle =
 			: "";
 
 		try {
-			await session.promptAsync({
-				path: { id: sessionID },
-				body: {
-					messageID,
-					parts: [{
-						type: "text",
-						text: `Workflow Guard: unfinished todos remain. Continue working through them.${tasksSummary}\nIf you need user input, use the question tool instead of ending the run. Check guard_status for outstanding verification/review requirements, and guard_review_rubric before final completion.`,
-						synthetic: true,
-					}],
-				},
-			});
+			// Delivery and resume are stated explicitly so a V2 synthetic
+			// continuation does not depend on host defaults. `queue` keeps it in
+			// the session's inbox instead of steering an in-flight turn, and
+			// `resume: true` starts a run when the session is idle.
+			//
+			// The fields are V2-only. The V1 SDK body type declares neither
+			// (`SessionPromptAsyncData` in @opencode-ai/sdk), so adding them
+			// there would send unmodelled fields to a strict server. The V2
+			// client shim reads them off this same object, so the values travel
+			// without changing the V1 request shape.
+			const promptBody: {
+				messageID: string;
+				parts: Array<{ type: "text"; text: string; synthetic?: boolean }>;
+				delivery?: "steer" | "queue";
+				resume?: boolean;
+			} = {
+				messageID,
+				parts: [{
+					type: "text" as const,
+					text: `Workflow Guard: unfinished todos remain. Continue working through them.${tasksSummary}\nIf you need user input, use the question tool instead of ending the run. Check guard_status for outstanding verification/review requirements, and guard_review_rubric before final completion.`,
+					synthetic: true,
+				}],
+			};
+			if (isV2Host()) {
+				promptBody.delivery = "queue";
+				promptBody.resume = true;
+			}
+			await session.promptAsync({ path: { id: sessionID }, body: promptBody });
 			return true;
 		} catch {
 			state.counts.set(sessionID, count);

package/src/workflow-guard.ts

@@ -22,10 +22,10 @@ import { expandShellTargetPath, isPathOutsideWorkspace, OPENCODE_SCRATCH_DIR, re
 import { beginReadObservation, clearReadFingerprints, recordMutationObservation, recordSuccessfulRead, staleWriteReason } from "./policies/stale-write.ts";
 import { ToolInvocationLifecycle } from "./lib/tool-lifecycle.ts";
 import { ToolOutcomeTracker, type ToolOutcomePart } from "./lib/tool-outcomes.ts";
-import { guardToolCallImpl, isMutatingSurfaceTool, isReadOnlyRole, SHELL_TOOL_NAMES } from "./lib/guard-dispatcher.ts";
+import { isMutatingSurfaceTool, isReadOnlyRole, SHELL_TOOL_NAMES } from "./lib/guard-dispatcher.ts";
 import { createCustomTools, buildWorkflowGuardSystemGuidance } from "./lib/custom-tools.ts";
 import { evaluateDogfoodGate } from "./lib/dogfood.ts";
-import type { PolicyDecision, TodoSdkClient } from "./lib/types.ts";
+import type { TodoSdkClient } from "./lib/types.ts";
 export { isReadOnlyRole } from "./lib/guard-dispatcher.ts";
 export { extractReviewFollowups, buildWorkflowGuardSystemGuidance } from "./lib/custom-tools.ts";
 export { evaluateDogfoodGate } from "./lib/dogfood.ts";
@@ -59,7 +59,6 @@ import {
 	setSdkClient,
 	getSdkClient,
 	runWithRuntimeState,
-	lastMutationTimestamp,
 	getLastMutationTimestamp,
 	getMutationCount,
 	getSessionMutationCount,
@@ -163,7 +162,6 @@ export {
 // ── Shared shell/env utilities ───────────────────────────────────────────────
 import {
 	asRecord,
-	extractRecordTargetPath,
 	getCleanEnv,
 	showBlockToast,
 	isSensitiveEnvKey,
@@ -212,13 +210,19 @@ import {
 	persistReviewCache,
 	loadReviewCache,
 	audit,
-	logDecision,
 	summarizeInput,
 } from "./lib/audit.ts";
 
 export { getAuditFilePath, getVerifyCacheFilePath, getReviewCacheFilePath, getDogfoodCacheFilePath, getVerifyHistoryFilePath, persistVerifyCache, loadVerifyCache, persistReviewCache, loadReviewCache, persistDogfoodCache, loadDogfoodCache, getRecentAuditEntries, getRecentVerifyHistory } from "./lib/audit.ts";
 export { summarizeInput };
 
+// The guard entry surface lives in a leaf module so the V2 entrypoint can
+// import it without pulling in this V1 file (and its SDK subtree) through a
+// cycle. Re-exported here because the test harness imports this public surface.
+export { guardToolCall, guardToolDecision, buildCompactionContext } from "./lib/guard-api.ts";
+import { guardToolCall, buildCompactionContext } from "./lib/guard-api.ts";
+import { TODOWRITE_SUFFIX, TODOWRITE_MARKER, EDIT_SUFFIX, EDIT_MARKER, SUBAGENT_SUFFIX, SUBAGENT_MARKER, appendToolDescriptionSuffix } from "./lib/tool-descriptions.ts";
+
 export function managedConfigDiagnostic(platform = process.platform, env: NodeJS.ProcessEnv = process.env): string {
 	const directory = platform === "darwin"
 		? "/Library/Application Support/opencode"
@@ -398,69 +402,10 @@ function logWarn(client: unknown, message: string): void {
 	} catch {}
 }
 
-/**
- * Public guard entry point. Audits every decision (block or allow) to a
- * durable JSONL file before returning.
- */
-export async function guardToolDecision(
-	toolName: string,
-	input: unknown,
-	context?: { sessionID?: string; callID?: string; worktree?: string; directory?: string; agent?: string },
-): Promise<PolicyDecision> {
-	const customRoot = context?.worktree || context?.directory;
-	const runImpl = () => guardToolCallImpl(toolName, input, context);
-	return customRoot
-		? await runWithRuntimeState(customRoot, getSdkClient(), runImpl)
-		: await runImpl();
-}
-
-export async function guardToolCall(
-	toolName: string,
-	input: unknown,
-	context?: { sessionID?: string; callID?: string; worktree?: string; directory?: string; agent?: string },
-): Promise<string | undefined> {
-	const decision = await guardToolDecision(toolName, input, context);
-	const allowLive = process.env.WORKFLOW_GUARD_ALLOW_LIVE === "1";
-	const isMutation = EDIT_TOOL_NAMES.has(toolName);
-	const targetPath = extractRecordTargetPath(input);
-	logDecision(toolName, input, context, decision, {
-		mutation: isMutation,
-		targetPath,
-		allowLive,
-		verification: lastVerify
-			? {
-					command: lastVerify.command,
-					passed: lastVerify.passed,
-					fresh: lastVerify.timestamp >= lastMutationTimestamp,
-					durationMs: lastVerify.durationMs,
-				}
-			: undefined,
-	});
-	return decision.status === "allowed" ? undefined : decision.message;
-}
-
 async function emitBlockFeedback(message: string): Promise<void> {
 	await showBlockToast(message);
 }
 
-export function buildCompactionContext(operationalState: string, priorityBlocks: string[], maxChars = 8_000): string {
-	if (!Number.isFinite(maxChars) || maxChars < 0 || !Number.isInteger(maxChars)) {
-		throw new RangeError("maxChars must be a non-negative finite integer");
-	}
-	const truncate = (value: string, limit: number): string => {
-		let end = Math.min(value.length, limit);
-		if (end > 0 && end < value.length && /[\uD800-\uDBFF]/.test(value[end - 1])) end -= 1;
-		return value.slice(0, end);
-	};
-	let context = truncate(operationalState, maxChars);
-	for (const block of priorityBlocks) {
-		const remaining = maxChars - context.length - 2;
-		if (remaining <= 0) break;
-		context += `\n\n${truncate(block, remaining)}`;
-	}
-	return context;
-}
-
 export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 	// Honor worktree if present (e.g. opencode worktrees or devcontainers)
 	// so worktree plugins cannot punch through boundary gates. When the host
@@ -839,28 +784,21 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 		// Similarly, mutating tools reflect their active-todo, feature-branch, and prior-read requirements.
 		// Subagent orchestration tools reflect worktree isolation and review expectations.
 		"tool.definition": async (input, output) => {
-			if (input.toolID === "todowrite") {
+			const append = (suffix: string, marker: string) => {
 				const description = typeof output.description === "string" ? output.description : "";
-				if (description.includes("verification evidence")) return;
-				output.description =
-					description +
-					"\n\nWorkflow Guard lifecycle: use todowrite to plan before working - it is the only view of progress the operator has, and every file mutation is gated on it. Each call replaces the complete task list: preserve every pending/in_progress task in subsequent updates until you explicitly mark it completed or cancelled, and do not omit active tasks when adding new work. A task may be marked completed only after its own work is recorded: the guard blocks a completion that has no file mutation in that task's active window, and one mutation cannot vouch for several completions. If a task is genuinely read-only (review, investigation, reading), append the marker `[read-only]` to its text; every such use is journaled. Use `cancelled` for work that was deliberately dropped. Marking every task completed triggers the finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply. Proactively call guard_next_tasks when planning work to discover existing roadmap/TODOs, and guard_status to check outstanding requirements.";
+				const next = appendToolDescriptionSuffix(description, suffix, marker);
+				if (next !== undefined) output.description = next;
+			};
+			if (input.toolID === "todowrite") {
+				append(TODOWRITE_SUFFIX, TODOWRITE_MARKER);
 				return;
 			}
 			if (EDIT_TOOL_NAMES.has(input.toolID)) {
-				const description = typeof output.description === "string" ? output.description : "";
-				if (description.includes("Workflow Guard requirement")) return;
-				output.description =
-					description +
-					"\n\nWorkflow Guard requirement: Modifications require an active task in todowrite (status pending or in_progress), a feature branch (edits on main/master are blocked), and a prior read of existing files in the current session.";
+				append(EDIT_SUFFIX, EDIT_MARKER);
 				return;
 			}
 			if (input.toolID === "task") {
-				const description = typeof output.description === "string" ? output.description : "";
-				if (description.includes("Workflow Guard subagent guidance")) return;
-				output.description =
-					description +
-					"\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.";
+				append(SUBAGENT_SUFFIX, SUBAGENT_MARKER);
 				return;
 			}
 		},

package/test/test.mts

@@ -7,6 +7,8 @@ import { DatabaseSync } from "node:sqlite";
 import type { PluginModule } from "@opencode-ai/plugin";
 import { getRalphMaxIterations, runWithRuntimeState } from "../src/lib/state.ts";
 import { isGeneratedContinuationMessage } from "../src/policies/continuation.ts";
+import { clearContinuationState, continueUnfinishedSession, recordUserMessage } from "../src/policies/continuation.ts";
+import { ToolInvocationLifecycle } from "../src/lib/tool-lifecycle.ts";
 import {
 	guardToolCall,
 	guardToolDecision,
@@ -7646,5 +7648,265 @@ rmSync(liveBase, { recursive: true, force: true });
 
 rmSync(root, { recursive: true, force: true });
 if (prevLive !== undefined) process.env.WORKFLOW_GUARD_ALLOW_LIVE = prevLive;
+
+// ── V2 delivered event handlers ──────────────────────────────────────────────
+// `ctx.event.subscribe()` is served from EventManifest.ServerDefinitions. A type
+// present in `Definitions` but absent from that manifest is never delivered,
+// even when a plugin handles it. Three handlers were built on such types, so
+// tool-outcome telemetry, the Policy 25 research floor, the MCP inventory
+// refresh, and the command audit were all silently dead on V2. These tests pin
+// the repaired paths and add a structural guard against the recurrence.
+console.log("- V2 delivered event handlers -");
+
+const v2EventModule = await import("../src/lib/v2-plugin.ts");
+const { handleV2Event } = v2EventModule;
+const { EventManifest } = await import("@opencode/schema/event-manifest");
+const serverEventTypes = new Set<string>([...EventManifest.ServerDefinitions].map((entry) => entry.type as string));
+
+// E5 (structural, highest value): every literal the plugin compares against
+// `event.type` must be a type the host actually delivers. This is what would
+// have caught the three dead handlers before they shipped.
+{
+	const pluginSource = readFileSync("src/lib/v2-plugin.ts", "utf8");
+	const literals = [...pluginSource.matchAll(/event\??\.type\s*(?:===|!==)\s*"([^"]+)"/g)].map((match) => match[1]);
+	const unique = [...new Set(literals)];
+	const undelivered = unique.filter((type) => !serverEventTypes.has(type));
+	check("V2 event-liveness scan finds the plugin's event comparisons", unique.length >= 5);
+	check("every event.type literal in v2-plugin.ts is in EventManifest.ServerDefinitions", undelivered.length === 0);
+	if (undelivered.length > 0) console.log(`    undelivered literal(s): ${undelivered.join(", ")}`);
+	// The three types that made A1/A3/A4 dead must not come back as literals.
+	check("the replay-only tool-content type is no longer handled", !unique.includes("session.message.content.updated"));
+	check("the ephemeral mcp.tools.changed type is no longer handled", !unique.includes("mcp.tools.changed"));
+	check("the replay-only command.executed type is no longer handled", !unique.includes("command.executed"));
+}
+
+// E1: the deny contract. `execute.before` may reject, and that rejection is what
+// fails the call with the guard's reason. Source-only fact: the adapter wraps
+// only that hook in `Effect.tryPromise`. A real V2 instance is driven so the
+// assertion covers the shipped registration, not a re-creation of it.
+{
+	resetPluginInstancesForTesting();
+	resetToolCallClaimsForTesting();
+	const denyRoot = mkdtempSync(join(tmpdir(), "wg-v2-deny-"));
+	const v2Deny = makeV2Context(denyRoot);
+	await (defaultExport.setup as any)(v2Deny.ctx);
+	const beforeHook = v2Deny.state.beforeHooks[0];
+	check("V2 registers exactly one execute.before hook", v2Deny.state.beforeHooks.length === 1);
+	let rejected: unknown;
+	let allowedReason: unknown = "sentinel";
+	try {
+		await beforeHook({ tool: "write", sessionID: "s-v2-deny", id: "call-deny", agent: "build", messageID: "m1", input: { filePath: join(denyRoot, "..", "escape.txt"), content: "x" } });
+	} catch (error) {
+		rejected = error;
+	}
+	check("a blocked execute.before rejects the call", rejected instanceof Error);
+	check("the rejection carries the workflow-guard reason prefix", rejected instanceof Error && rejected.message.includes("[workflow-guard]"));
+	check("the rejection carries an actionable policy reason", rejected instanceof Error && rejected.message.length > "[workflow-guard] ".length + 10);
+	// A permitted call must stay silent: the hook resolves without throwing.
+	try {
+		allowedReason = await beforeHook({ tool: "read", sessionID: "s-v2-deny", id: "call-allow", agent: "build", messageID: "m2", input: { filePath: join(denyRoot, "ok.txt") } });
+	} catch (error) {
+		allowedReason = error;
+	}
+	check("a permitted execute.before resolves without throwing", !(allowedReason instanceof Error));
+	rmSync(denyRoot, { recursive: true, force: true });
+}
+
+// E2: tool-outcome telemetry (A1). The old subscription keyed on a replay-only
+// event, so nothing ever reached the tracker and the circuit breaker could not
+// fire. Recording now happens in `execute.after`, which does fire for a failed
+// call, so an error accrues failure debt and a success clears it.
+{
+	resetPluginInstancesForTesting();
+	resetToolCallClaimsForTesting();
+	const outcomeRoot = mkdtempSync(join(tmpdir(), "wg-v2-outcome-"));
+	const v2Outcome = makeV2Context(outcomeRoot);
+	await (defaultExport.setup as any)(v2Outcome.ctx);
+	const beforeHook = v2Outcome.state.beforeHooks[0];
+	const afterHook = v2Outcome.state.afterHooks[0];
+	const breaker = (error: unknown) => error instanceof Error && error.message.includes("[Workflow Guard Circuit Breaker");
+	// One error is not enough: the suffix starts at a count of 2.
+	await afterHook({ tool: "write", sessionID: "s-v2-outcome", id: "call-a", agent: "build", messageID: "m1", input: {}, status: "error", error: new Error("boom") });
+	let firstError: unknown;
+	try {
+		await beforeHook({ tool: "write", sessionID: "s-v2-outcome", id: "call-b", agent: "build", messageID: "m2", input: { filePath: join(outcomeRoot, "..", "escape.txt"), content: "x" } });
+	} catch (error) {
+		firstError = error;
+	}
+	check("one failure stays below the circuit-breaker threshold", !breaker(firstError));
+	// A second equivalent error crosses the threshold.
+	await afterHook({ tool: "write", sessionID: "s-v2-outcome", id: "call-c", agent: "build", messageID: "m3", input: {}, status: "error", error: new Error("boom") });
+	let secondError: unknown;
+	try {
+		await beforeHook({ tool: "write", sessionID: "s-v2-outcome", id: "call-d", agent: "build", messageID: "m4", input: { filePath: join(outcomeRoot, "..", "escape.txt"), content: "x" } });
+	} catch (error) {
+		secondError = error;
+	}
+	check("two equivalent tool errors raise the circuit-breaker path", breaker(secondError));
+	// A completed call clears the debt, so the suffix disappears again.
+	await afterHook({ tool: "write", sessionID: "s-v2-outcome", id: "call-e", agent: "build", messageID: "m5", input: {}, status: "completed", result: { content: "ok" } });
+	let clearedError: unknown;
+	try {
+		await beforeHook({ tool: "write", sessionID: "s-v2-outcome", id: "call-f", agent: "build", messageID: "m6", input: { filePath: join(outcomeRoot, "..", "escape.txt"), content: "x" } });
+	} catch (error) {
+		clearedError = error;
+	}
+	check("the circuit-breaker suffix is gone after a success", !breaker(clearedError));
+	check("the failure outcome is journaled for diagnosis", getRecentAuditEntries(50).some((entry) => entry.sessionID === "s-v2-outcome" && entry.phase === "outcome" && entry.reason === "error"));
+	// Read the counter directly, so the debt assertions cannot pass on a call
+	// that throws for an unrelated reason. Two errors accrued, one completion
+	// cleared them; the audit rows are the durable witness for the same state.
+	const outcomeAudit = getRecentAuditEntries(50).filter((entry) => entry.sessionID === "s-v2-outcome" && entry.phase === "outcome");
+	check("two failures and one completion are each journaled", outcomeAudit.filter((entry) => entry.reason === "error").length === 2 && outcomeAudit.some((entry) => entry.reason === "completed"));
+	// A partial event with no terminal status takes the fallback path. That path
+	// must still journal its outcome row, which is the coverage the move onto
+	// `execute.after` nearly dropped.
+	await afterHook({ tool: "write", sessionID: "s-v2-outcome", id: "call-g", agent: "build", messageID: "m7", input: {}, result: { content: "ok" } });
+	check("a status-less after event still journals an outcome row", getRecentAuditEntries(50).some((entry) => entry.sessionID === "s-v2-outcome" && entry.callID === "call-g" && entry.phase === "outcome"));
+	rmSync(outcomeRoot, { recursive: true, force: true });
+}
+
+// E3: a user interrupt suspends continuation on V2 (A2). Only reason `user` is
+// user intent; the other three are host-lifecycle events and must not stop the
+// session's own unfinished work from continuing.
+{
+	const makeState = (root: string, client: unknown) => ({
+		effectiveRoot: root,
+		client,
+		toolLifecycle: new ToolInvocationLifecycle(),
+		toolOutcomes: new ToolOutcomeTracker(),
+	});
+	const interrupts = [
+		{ reason: "user", suspends: true },
+		{ reason: "shutdown", suspends: false },
+		{ reason: "superseded", suspends: false },
+		{ reason: "inactivity", suspends: false },
+	];
+	for (const { reason, suspends } of interrupts) {
+		const sessionID = `s-v2-int-${reason}`;
+		todo(sessionID, item("unfinished work", "pending"));
+		// A continuation can only be observed if the client can actually prompt,
+		// and continuation state is keyed on the client object, so each case
+		// gets its own client and asserts on the delivered prompt rather than on
+		// a false-negative return value.
+		const prompted: string[] = [];
+		const continuationClient = {
+			session: {
+				todo: async ({ path }: { path: { id: string } }) => ({ data: fakeTodos.get(path.id) ?? [] }),
+				get: async ({ path }: { path: { id: string } }) => ({ data: { id: path.id, parentID: fakeParents.get(path.id) } }),
+				promptAsync: async ({ path }: { path: { id: string } }) => { prompted.push(path.id); },
+			},
+		};
+		await handleV2Event({ type: "session.execution.interrupted", data: { sessionID, reason } }, makeState(root, continuationClient) as any);
+		const continued = await runWithRuntimeState(root, continuationClient, () => continueUnfinishedSession(sessionID));
+		check(`session.execution.interrupted reason "${reason}" ${suspends ? "suspends" : "does not suspend"} continuation`, continued === !suspends && prompted.length === (suspends ? 0 : 1));
+		await runWithRuntimeState(root, continuationClient, () => clearContinuationState(sessionID));
+	}
+	// A genuine user message re-enables a suspended session, proven by an
+	// actual continuation prompt: suspension must block it, user input must not.
+	const resumedSession = "s-v2-int-resume";
+	todo(resumedSession, item("unfinished work", "pending"));
+	const resumedPrompts: string[] = [];
+	const resumeClient = {
+		session: {
+			todo: async ({ path }: { path: { id: string } }) => ({ data: fakeTodos.get(path.id) ?? [] }),
+			get: async ({ path }: { path: { id: string } }) => ({ data: { id: path.id, parentID: fakeParents.get(path.id) } }),
+			promptAsync: async ({ path }: { path: { id: string } }) => { resumedPrompts.push(path.id); },
+		},
+	};
+	await handleV2Event({ type: "session.execution.interrupted", data: { sessionID: resumedSession, reason: "user" } }, makeState(root, resumeClient) as any);
+	const suspendedResult = await runWithRuntimeState(root, resumeClient, () => continueUnfinishedSession(resumedSession));
+	check("a suspended session sends no continuation prompt", suspendedResult === false && resumedPrompts.length === 0);
+	// Continuation state is keyed on the client object, so the user-message
+	// record must run against the same client the session was suspended under.
+	await runWithRuntimeState(root, resumeClient, () => recordUserMessage(resumedSession));
+	const afterUserInput = await runWithRuntimeState(root, resumeClient, () => continueUnfinishedSession(resumedSession));
+	check("genuine user input re-enables a suspended continuation", afterUserInput === true && resumedPrompts.length === 1);
+	await runWithRuntimeState(root, resumeClient, () => clearContinuationState(resumedSession));
+}
+
+// E4: the MCP inventory refresh keys on a delivered event (A3), and widening is
+// additive only. A guarded server that connects mid-session must be guarded
+// without waiting for the next session, and a quieter roster must never unguard
+// a token that a static rule already covers.
+{
+	const refreshCalls: string[] = [];
+	const state = {
+		effectiveRoot: root,
+		client: fakeClient,
+		toolLifecycle: new ToolInvocationLifecycle(),
+		toolOutcomes: new ToolOutcomeTracker(),
+		refreshMcpInventory: async () => { refreshCalls.push("refresh"); },
+	};
+	await handleV2Event({ type: "mcp.status.changed", data: { server: "github-enterprise" } }, state as any);
+	check("a delivered mcp.status.changed triggers the inventory refresh", refreshCalls.length === 1);
+	await handleV2Event({ type: "mcp.tools.changed", data: { server: "github-enterprise" } }, state as any);
+	check("the undelivered mcp.tools.changed no longer triggers anything", refreshCalls.length === 1);
+	// Widening is additive: a later roster without the server cannot remove it.
+	resetGuardedMcpTokensForTesting();
+	const added = recordHostMcpServers(["github-enterprise"]);
+	const widened = [...guardedMcpServers()];
+	check("a host-declared guarded server widens the token set", added.length > 0 && widened.some((token) => added.includes(token)));
+	recordHostMcpServers([]);
+	check("an emptied roster never narrows the guarded token set", [...guardedMcpServers()].length >= widened.length);
+	resetGuardedMcpTokensForTesting();
+}
+
+// E6: the idle trigger. The host keeps two event types for it and neither is
+// established as the one the server publishes: `session.status` with
+// `status.type === "idle"`, and the deprecated `session.idle`. Handling only
+// one silently disables automatic continuation if the other is what arrives.
+// The assertions are delivered continuation prompts, not return values.
+{
+	const makeIdleState = (client: unknown) => ({
+		effectiveRoot: root,
+		client,
+		toolLifecycle: new ToolInvocationLifecycle(),
+		toolOutcomes: new ToolOutcomeTracker(),
+	});
+	const idleSession = "s-v2-idle-status";
+	todo(idleSession, item("unfinished work", "pending"));
+	const idlePrompts: string[] = [];
+	const idleClient = {
+		session: {
+			todo: async ({ path }: { path: { id: string } }) => ({ data: fakeTodos.get(path.id) ?? [] }),
+			get: async ({ path }: { path: { id: string } }) => ({ data: { id: path.id, parentID: fakeParents.get(path.id) } }),
+			promptAsync: async ({ path }: { path: { id: string } }) => { idlePrompts.push(path.id); },
+		},
+	};
+	await handleV2Event({ type: "session.status", data: { sessionID: idleSession, status: { type: "busy" } } }, makeIdleState(idleClient) as any);
+	check("a busy session.status does not continue the session", idlePrompts.length === 0);
+	await handleV2Event({ type: "session.status", data: { sessionID: idleSession, status: { type: "idle" } } }, makeIdleState(idleClient) as any);
+	check("an idle session.status continues the session", idlePrompts.length === 1);
+	// The deprecated trigger must still work: a host that emits only this one
+	// would otherwise lose auto-continuation entirely.
+	await handleV2Event({ type: "session.idle", data: { sessionID: idleSession } }, makeIdleState(idleClient) as any);
+	check("the deprecated session.idle still continues the session", idlePrompts.length === 2);
+	await runWithRuntimeState(root, idleClient, () => clearContinuationState(idleSession));
+
+	// A host that emits both types for one transition must produce one prompt.
+	// Each event is handled on its own call, so this pins the in-flight lock
+	// rather than any per-call dedupe.
+	const bothSession = "s-v2-idle-both";
+	todo(bothSession, item("unfinished work", "pending"));
+	let bothPrompts = 0;
+	let releaseBoth!: () => void;
+	const bothGate = new Promise<void>((resolve) => { releaseBoth = resolve; });
+	const bothClient = {
+		session: {
+			todo: async ({ path }: { path: { id: string } }) => ({ data: fakeTodos.get(path.id) ?? [] }),
+			get: async ({ path }: { path: { id: string } }) => ({ data: { id: path.id, parentID: fakeParents.get(path.id) } }),
+			promptAsync: async () => { bothPrompts++; await bothGate; },
+		},
+	};
+	const firstTrigger = handleV2Event({ type: "session.status", data: { sessionID: bothSession, status: { type: "idle" } } }, makeIdleState(bothClient) as any);
+	const secondTrigger = handleV2Event({ type: "session.idle", data: { sessionID: bothSession } }, makeIdleState(bothClient) as any);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	releaseBoth();
+	await Promise.all([firstTrigger, secondTrigger]);
+	check("both idle event types for one transition yield a single continuation prompt", bothPrompts === 1);
+	await runWithRuntimeState(root, bothClient, () => clearContinuationState(bothSession));
+}
+
 console.log(`\n${pass} passed, ${fail} failed`);
 process.exitCode = fail ? 1 : 0;