opencode-workflow-guard 1.16.0 → 1.17.0

package/docs/troubleshooting.md

@@ -7,7 +7,7 @@ Common issues, root causes, and solutions when using `opencode-workflow-guard`.
 ### 1. `plugin config hook failed` / `Unexpected server error` on startup
 
 - **Symptoms:** OpenCode crashes or reports `Unexpected server error` when starting a session, with logs showing `TypeError: undefined is not an object (evaluating '...event')`.
-- **Root Cause:** OpenCode 1.18+'s legacy loader treats *every exported function* in a plugin module as a separate plugin instance. If a plugin exports helper functions (like `guardToolCall` or `setWorkspaceRoot`) alongside a default function, OpenCode calls them as plugins, pushes `undefined` into the hook registry, and crashes event dispatch on `session.created`.
+- **Root Cause:** OpenCode 1.18+'s legacy loader treats *every exported function* in a plugin module as a separate plugin instance. A plugin that exports helper functions (like `guardToolCall` or `setWorkspaceRoot`) alongside a default function therefore registers those helpers as plugins too. OpenCode calls them as plugins, pushes `undefined` into the hook registry, and crashes event dispatch on `session.created`.
 - **Solution:** Ensure `src/workflow-guard.ts` uses the V1 `PluginModule` export format (`export default { id: "workflow-guard", server: WorkflowGuard } satisfies PluginModule`). File plugins require an explicit `id` string.
 
 ---
@@ -15,8 +15,8 @@ Common issues, root causes, and solutions when using `opencode-workflow-guard`.
 ### 2. Edits Blocked: `Blocked: no active todo item`
 
 - **Symptoms:** The agent attempts an edit (`edit`, `write`, `apply_patch`) and receives a block message directing it to create a task list.
-- **Root Cause:** Policy 1 blocks file-editing tools while the session's **effective** todo list is known and contains no task with status `pending` or `in_progress`. On OpenCode 1.x that list is the native todo state (`GET /session/:id/todo`). On OpenCode 2.x there is no todo endpoint and no builtin `todowrite`, so the list is reconstructed from the newest applied `todowrite` tool call in the session history (some ACP agents supply that tool). A list is only treated as empty when a `todowrite` part actually exists; when the session has no `todowrite` capability at all, the gate fails open rather than blocking every edit forever.
-- **Solution:** The agent must call `todowrite` first. Once all tasks are marked `completed` or `cancelled`, edits will block again until a new breakdown is created for subsequent work. If an agent on OpenCode 2.x is blocked here despite having no todo tool available, that is a bug - report it rather than working around it through shell writes.
+- **Root Cause:** Policy 1 blocks file-editing tools while the session's **effective** todo list is known and contains no task with status `pending` or `in_progress`. On OpenCode 1.x that list is the native todo state (`GET /session/:id/todo`). Before 2.1.0, OpenCode 2.x has no todo endpoint and no builtin `todowrite`. The list is then reconstructed from the newest applied `todowrite` tool call in the session history, which some ACP agents supply. A list counts as empty only when a `todowrite` part actually exists. When the session has no `todowrite` capability at all, the gate fails open rather than blocking every edit forever.
+- **Solution:** The agent must call `todowrite` first. Once all tasks are marked `completed` or `cancelled`, edits block again until a new breakdown is created for subsequent work. If an agent on OpenCode 2.x is blocked here despite having no todo tool available, that is a bug. Report it rather than working around it through shell writes.
 
 ---
 
@@ -64,7 +64,7 @@ Common issues, root causes, and solutions when using `opencode-workflow-guard`.
 
 - **Symptoms:** A CLI command is rejected with a live-system mutation warning.
 - **Root Cause:** Policy 4 blocks destructive cloud, database, and infrastructure operations.
-- **Solution:** To intentionally run a live command, set `WORKFLOW_GUARD_ALLOW_LIVE=1` in the environment before launching OpenCode. There is no in-command override; an agent cannot grant this permission to itself.
+- **Solution:** To intentionally run a live command, set `WORKFLOW_GUARD_ALLOW_LIVE=1` in the environment before launching OpenCode. There is no in-command override. An agent cannot grant this permission to itself.
 
 ---
 
@@ -88,30 +88,31 @@ After the command reports `Detected server + tui targets`, confirm it reports re
 ### 10. TUI companion crashes with `Keymap.Provider is missing` (OpenCode V2)
 
 - **Symptoms:** On opencode v2, the TUI companion plugin fails during setup with `Keymap.Provider is missing` and does not load.
-- **Root Cause:** `ctx.keymap.layer` resolves a Solid context (`useContext(KeymapContext)`) and only works inside the TUI's `Keymap.Provider` render tree; the API documents layers as "owned by the calling component". Plugin `setup()` runs as a plain async call outside that tree, so registering a layer there always throws.
-- **Solution:** Fixed in 1.13.2: the layer is registered from an `app`-slot claim (`ctx.ui.slot({ append: "app", render: () => { ...; return null } })`). Slot renders execute in a reactive scope under the provider, and the same session-panel pattern applies to any plugin API that requires component ownership. If you maintain a TUI plugin that registers keymap layers, commands, or reactive state, register them from a slot render (or a rendered component), never from `setup()`.
+- **Root Cause:** `ctx.keymap.layer` resolves a Solid context (`useContext(KeymapContext)`), so it only works inside the TUI's `Keymap.Provider` render tree. The API documents layers as "owned by the calling component". Plugin `setup()` runs as a plain async call outside that tree, so registering a layer there always throws.
+- **Solution:** Fixed in 1.13.2. The layer is registered from an `app`-slot claim (`ctx.ui.slot({ append: "app", render: () => { ...; return null } })`). Slot renders execute in a reactive scope under the provider, and the same session-panel pattern applies to any plugin API that requires component ownership. If you maintain a TUI plugin that registers keymap layers, commands, or reactive state, register them from a slot render or a rendered component. Never register them from `setup()`.
 
 ---
 
 ### 11. Reading tool parts from V2 sessions (integrators)
 
-- **Symptoms:** Code that parses recorded tool calls (message parts, the `part` DB table, or `session.message.content.updated` events) finds no tool name on OpenCode V2, or sees tool names that do not exist in OpenCode's builtin tool list.
+- **Symptoms:** Code that parses recorded tool calls finds no tool name on OpenCode V2. It may also see tool names that do not exist in OpenCode's builtin tool list. The affected sources are message parts, the `part` DB table, and `session.message.content.updated` events.
 - **Root Cause:** Two independent things:
-  1. V2 message parts record the tool name in the `tool` field; V1 used `name`. Code reading `part.name` silently gets `undefined` on V2.
-  2. V2's builtin tool registry contains only `read`, `glob`, `grep`, `edit`, `write`, `patch`, `shell`, `webfetch`, `websearch`, `question`, `skill`, `subagent`, and `execute`. There is no builtin `todowrite` (the V1 name), and the V1 `task` subagent tool was renamed to `subagent`. `todowrite`/`bash` tool parts observed in V2 sessions come from ACP agents (for example pi) that supply their own tools; those tools are not in the server-side registry and cannot be reached by `ctx.tool.transform`.
+  1. V2 message parts record the tool name in the `tool` field, where V1 used `name`. Code reading `part.name` silently gets `undefined` on V2.
+  2. V2's builtin tool registry contains only `read`, `glob`, `grep`, `edit`, `write`, `patch`, `shell`, `webfetch`, `websearch`, `question`, `skill`, `subagent`, and `execute`. There is no builtin `todowrite`, which is the V1 name, and the V1 `task` subagent tool was renamed to `subagent`. `todowrite` and `bash` tool parts observed in V2 sessions come from ACP agents, for example pi, that supply their own tools. Those tools are not in the server-side registry and cannot be reached by `ctx.tool.transform`.
 - **Solution:** Read the tool name as `part.tool ?? part.name` and treat tool-part names as agent-reported, not as the builtin registry. `ToolEditor.update` ignores missing IDs, so enriching a tool that does not exist is a harmless no-op.
 
 ---
 
 ### 12. Review recorded with `record_review`, but `pr create` is still blocked
 
-- **Symptoms:** `record_review` returned "Review recorded as APPROVED" and `guard_status` showed a fresh `lastReview`, yet `gh pr create` / `az repos pr create` was blocked with "Passing secondary review approval is required"; or re-calling `record_review` returned success but `guard_status` still showed no fresh review.
-- **Root Cause (fixed by content binding):** The PR preflight previously also required the review's target session to equal the PR-creating session's ID. `record_review` records from a secondary session (binding the verdict to its parent or its own directory), sessions can move between directories mid-flight (`session_move`), and subagents spawn from other roots — so a review recorded against a linked git worktree could never satisfy a PR created from another session there. Mutation invalidation additionally erased the whole review record on any mutation, including unrelated untracked-file cleanup.
-- **Binding rule:** a recorded approval satisfies the preflight when its binding matches the tree the PR publishes — same repository, same commit hash, same tracked-content worktree fingerprint. Review freshness is scoped to tracked content, so deleting an untracked scratch file does not invalidate it; a tracked edit or new commit does. When the tracked fingerprint is unchanged but HEAD moved (for example a review recorded with changes already staged, then committed), the preflight names the commit drift specifically.
-- **Diagnosis:** `guard_audit` now records the binding key (workspace, commit hash, fingerprint prefix, recorder session and `recorderRole`) on every `record_review.verdict` entry, and a `pr-preflight.review-binding` entry when a PR preflight accepts a review. If a verdict cannot bind at all (directory is not a git repository), `record_review` rejects loudly with the reason instead of returning a success string.
-- **Strict recorder mode rejects the approval:** projects with `requireSubagentReview: true` (or `WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=1`) reject `record_review` approval verdicts recorded by the root session with "this project requires approvals to be recorded from a subagent session". Record the verdict from a subagent session instead (one with a parent session), or disable the requirement in project config; the `guard_audit` entry carries reason `subagent_recorder_required`. Changes-requested verdicts remain relayable from any session. The knob is enforced when verdicts are recorded: an approval recorded by the root session before the requirement was enabled — including durable review-cache evidence recovered after a restart — still satisfies the PR preflight until its content binding goes stale, so re-run the secondary review after adopting the knob to re-bind it.
-- **Worktree creation failure leaving a branch behind:** `guard_worktree_create` failures previously surfaced only git's stderr (often checkout progress) and could leave a half-created branch. Failures are now reported with git's exit status, the created branch is rolled back (pre-existing branches are preserved), and stale worktree admin entries are pruned only for the newly-created path. A live registered worktree whose sanitized name collides with the requested branch is left fully intact — rollback never removes pre-existing worktrees. Large checkouts that exceed the 15s timeout can set `WORKFLOW_GUARD_WORKTREE_TIMEOUT_MS`.
-- **Edit blocked by "claimed by another active session" though no other session is working:** a missed `session.idle` release can leave a finished session's direct-edit claim behind, and claims have no expiry, so every other session is blocked from that path until the owning session is deleted or the service restarts. On a real (non-simulated) call the takeover now resolves it: a claim created before its owner's last recorded idle timestamp is provably stale and is released, with `guard_audit` recording a `file-claims` entry with reason `stale_claim_takeover`. Sessions still mid-turn (no idle timestamp) keep their claim, and the takeover fails closed without an SDK session lookup or when the lookup fails. `guard_why` remains read-only and still reports the conflict.
-- **You updated the plugin but the old version still loads:** a configured bare package name is resolved through Node's parent-directory lookup from OpenCode's configuration location, so a copy in any parent `node_modules` (a pnpm-managed home directory or a manual install) shadows OpenCode's own plugin cache and a global `npm install -g`; OpenCode's own update check can fail with only a server-log record (`NpmInstallFailedError`). Verify what actually loaded with `guard_status` (the `pluginVersion` field), the startup app-log line (`Workflow Guard v<version> plugin initialized ...`), or the server log's `loading plugin ... entrypoint=file:///...` record. Then update the resolved copy in place (for a pnpm-managed home directory: `cd ~ && pnpm add opencode-workflow-guard@<version>`) and run `opencode service restart` — the plugin loads in the background service, so restarting only the TUI does not reload it.
-- **A benign-looking command with a shell variable is blocked as "outside the workspace":** a mutation or redirect target containing an unresolvable `$VARIABLE` reference (for example `mkdir -p $D/sub`, `cp a.txt "$D/b.txt"`, `> $CACHE/out.txt`) is indeterminate without executing shell semantics, and the boundary fails closed on indeterminate destinations — the block message names this cause ("contains an unresolvable variable reference … use a literal workspace-relative path"). Deterministically expandable forms (`~`, `$HOME`) and literal paths inside the workspace are unaffected, and reads (including cache-path reads) are not gated. Replace the variable with a literal workspace-relative path in the command, or assign it inside a script file within the workspace that the boundary has already validated. Resolving the variable would require executing shell semantics, which the boundary deliberately does not do (see the shell-expansion hardening notes in the roadmap).
-- **A scratch write to `/tmp/opencode` is blocked:** the environment designates that directory as agent scratch space, but the workspace boundary is workspace-absolute and does not cover it, so writes there stay blocked — the block message names the directory and the remedy. Write scratch as an untracked file inside the workspace instead (for example `.tmp-notes.md`); the boundary has no override for it, and the enforcement decision is unchanged by this attribution.
+- **Symptoms:** `record_review` returned "Review recorded as APPROVED" and `guard_status` showed a fresh `lastReview`, yet `pr create` was blocked with "Passing secondary review approval is required". A re-call of `record_review` may return success while `guard_status` still shows no fresh review.
+- **Root Cause (fixed by content binding):** The PR preflight previously also required the review's target session to equal the PR-creating session's ID. `record_review` records from a secondary session, binding the verdict to its parent or its own directory. Sessions can move between directories mid-flight (`session_move`), and subagents spawn from other roots. A review recorded against a linked git worktree could therefore never satisfy a PR created from another session there. Mutation invalidation also erased the whole review record on any mutation, including unrelated untracked-file cleanup.
+- **Binding rule:** A recorded approval satisfies the preflight when its binding matches the tree the PR publishes. The binding covers the repository, the commit hash, and the tracked-content worktree fingerprint. Review freshness is scoped to tracked content. Deleting an untracked scratch file does not invalidate it, and a tracked edit or new commit does. When the tracked fingerprint is unchanged but HEAD moved, the preflight names the commit drift specifically. That case arises when a review is recorded with changes already staged and then committed. The remedy is the same either way: record the review at the commit that will ship.
+- **Commit before you review:** both evidence gates bind to the HEAD commit hash, so a commit after verification or after the review invalidates that evidence. Finish every tracked change first, then verify, then record the review, then open the PR. Any other order costs a re-run.
+- **Diagnosis:** `guard_audit` records the binding key on every `record_review.verdict` entry. The key covers workspace, commit hash, fingerprint prefix, recorder session, and `recorderRole`. It also records a `pr-preflight.review-binding` entry when a PR preflight accepts a review. A verdict that cannot bind at all is rejected loudly with the reason instead of returning a success string. That case is a directory that is not a git repository.
+- **Strict recorder mode rejects the approval:** Projects with `requireSubagentReview: true` (or `WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=1`) reject `record_review` approval verdicts recorded by the root session. The message reads "this project requires approvals to be recorded from a subagent session", and the `guard_audit` entry carries reason `subagent_recorder_required`. Record the verdict from a subagent session (one with a parent session) instead, or disable the requirement in project config. Changes-requested verdicts remain relayable from any session. The knob is enforced when verdicts are recorded. An approval recorded by the root session before the requirement was enabled still satisfies the PR preflight until its content binding goes stale. That includes durable review-cache evidence recovered after a restart. Re-run the secondary review after adopting the knob to re-bind it.
+- **Worktree creation failure leaving a branch behind:** `guard_worktree_create` failures previously surfaced only git's stderr. That output is often just checkout progress, and the failure could leave a half-created branch. Failures now report git's exit status, and the created branch is rolled back. Pre-existing branches are preserved. Stale worktree admin entries are pruned only for the newly-created path. A live registered worktree whose sanitized name collides with the requested branch is left fully intact, because rollback never removes pre-existing worktrees. Large checkouts that exceed the 15s timeout can raise it with `WORKFLOW_GUARD_WORKTREE_TIMEOUT_MS`.
+- **Edit blocked by "claimed by another active session" though no other session is working:** A missed `session.idle` release can leave a finished session's direct-edit claim behind. Claims have no expiry. Every other session is blocked from that path until the owning session is deleted or the service restarts. On a real (non-simulated) call the takeover resolves it. A claim created before its owner's last recorded idle timestamp is provably stale and is released. `guard_audit` records a `file-claims` entry with reason `stale_claim_takeover`. Sessions still mid-turn (no idle timestamp) keep their claim. The takeover fails closed without an SDK session lookup, and when the lookup fails. `guard_why` remains read-only and still reports the conflict.
+- **You updated the plugin but the old version still loads:** A configured bare package name is resolved through Node's parent-directory lookup from OpenCode's configuration location. A copy in any parent `node_modules` (a pnpm-managed home directory or a manual install) shadows OpenCode's own plugin cache and a global `npm install -g`. OpenCode's own update check can then fail with only a server-log record (`NpmInstallFailedError`). Verify what actually loaded with `guard_status` (the `pluginVersion` field), the startup app-log line (`Workflow Guard v<version> plugin initialized ...`), or the server log's `loading plugin ... entrypoint=file:///...` record. Then update the resolved copy in place (for a pnpm-managed home directory: `cd ~ && pnpm add opencode-workflow-guard@<version>`). Run `opencode service restart`, because the plugin loads in the background service and restarting only the TUI does not reload it.
+- **A benign-looking command with a shell variable is blocked as "outside the workspace":** A mutation or redirect target that contains an unresolvable `$VARIABLE` reference is indeterminate without executing shell semantics. Examples are `mkdir -p $D/sub`, `cp a.txt "$D/b.txt"`, and `> $CACHE/out.txt`. The boundary fails closed on indeterminate destinations. The block message names this cause: "contains an unresolvable variable reference … use a literal workspace-relative path". Deterministically expandable forms (`~`, `$HOME`) and literal paths inside the workspace are unaffected. Reads, including cache-path reads, are not gated. Replace the variable with a literal workspace-relative path in the command. Alternatively, assign it inside a script file within the workspace that the boundary has already validated. Resolving the variable would need shell execution, which the boundary deliberately avoids.
+- **A scratch write to `/tmp/opencode` is blocked:** The environment designates that directory as agent scratch space. The workspace boundary is workspace-absolute, though, and does not cover it. Writes there stay blocked, and the block message names both the directory and the remedy. Write scratch as an untracked file inside the workspace instead, for example `.tmp-notes.md`. The boundary has no override for it, and this attribution does not change the enforcement decision.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",
@@ -50,7 +50,7 @@
     "prepublishOnly": "npm run typecheck"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.18.32",
+    "@opencode-ai/plugin": "1.19.3",
     "@opencode/plugin": "2.1.3",
     "@opentui/solid": "0.6.6",
     "jsonc-parser": "3.3.1",
@@ -58,7 +58,7 @@
   },
   "devDependencies": {
     "@changesets/cli": "3.0.3",
-    "@types/node": "26.6.2",
+    "@types/node": "26.6.5",
     "typescript": "7.0.2"
   },
   "overrides": {

package/src/lib/custom-tools.ts

@@ -91,6 +91,7 @@ export function buildWorkflowGuardSystemGuidance(options: {
 	sections.push(
 		"- Technical Debt: Inspect open P2/P3 review follow-ups with `guard_review_followups` during planning; resolve fixed items with `guard_review_followup_resolve`.",
 		"- Policy Simulation: If uncertain whether a command or file edit is permitted, simulate it with `guard_why`.",
+		"- Live Documentation: Verify APIs, flags, and library behavior against current sources with `websearch`/`webfetch` rather than guessing from training data. After repeated tool failures with no lookup, Workflow Guard blocks further mutations and shell commands until you consult a live source; grounding clears the block.",
 	);
 
 	if (options.projectMemoryEnabled) {

package/src/lib/guard-dispatcher.ts

@@ -87,6 +87,20 @@ import { recordedTodoCapability, reportTodoGateFailOpen } from "./v2-todo.ts";
 
 export const SHELL_TOOL_NAMES = new Set(["bash", "run_commands", "execute_command", "shell"]);
 
+/**
+ * Tools that can change repository or workspace state, and so sit behind the
+ * Policy 25 research floor. Widening past the edit/shell sets matters because
+ * the guard's own lifecycle tools mutate the repository without a shell.
+ */
+export function isMutatingSurfaceTool(toolName: string): boolean {
+	return (
+		EDIT_TOOL_NAMES.has(toolName) ||
+		SHELL_TOOL_NAMES.has(toolName) ||
+		toolName.startsWith("guard_worktree_") ||
+		toolName === "guard_recovery_restore"
+	);
+}
+
 // dynamic_shell_syntax is fail-closed by design; naming the construct and a
 // remedy keeps agents from retrying near-identical commands. Keyed by the
 // construct strings returned by dynamicShellSyntaxIn; unknown constructs fall

package/src/lib/state.ts

@@ -543,6 +543,51 @@ export function isDocumentationRequired(root: string): boolean {
 	return cfg.requireDocumentation === true;
 }
 
+/**
+ * Policy 25 (live-documentation research floor): enabled by default. The env
+ * override mirrors `isReviewRequired`; project config can opt out. The floor
+ * engages after `getLiveDocFailureThreshold` failed tool calls with no live
+ * lookup since the last failure.
+ */
+export function isLiveDocsRequired(root: string): boolean {
+	const env = process.env.WORKFLOW_GUARD_REQUIRE_LIVE_DOCS?.toLowerCase();
+	if (env === "0" || env === "false" || env === "off") return false;
+	if (env === "1" || env === "true" || env === "on") return true;
+	const cfg = getProjectConfig(root);
+	return cfg.requireLiveDocs !== false;
+}
+
+export function getLiveDocFailureThreshold(root: string): number {
+	const env = process.env.WORKFLOW_GUARD_LIVE_DOC_THRESHOLD;
+	if (env !== undefined && env.trim() !== "") {
+		// Number() rejects trailing junk that parseInt would silently accept.
+		const parsed = Number(env.trim());
+		if (Number.isInteger(parsed) && parsed >= 1) return parsed;
+	}
+	const cfg = getProjectConfig(root);
+	if (typeof cfg.liveDocFailureThreshold === "number" && Number.isInteger(cfg.liveDocFailureThreshold) && cfg.liveDocFailureThreshold >= 1) {
+		return cfg.liveDocFailureThreshold;
+	}
+	return 3;
+}
+
+/**
+ * Extra tool-name fragments that count as a live-documentation lookup, so an
+ * operator whose docs server is not in the builtin token set can still satisfy
+ * the floor: `researchTools` in project config or
+ * `WORKFLOW_GUARD_RESEARCH_TOOLS` (comma-separated).
+ */
+export function getResearchToolPatterns(root: string = getWorkspaceRoot()): string[] {
+	const env = process.env.WORKFLOW_GUARD_RESEARCH_TOOLS;
+	if (env !== undefined && env.trim() !== "") {
+		return env.split(",").map((value) => value.trim().toLowerCase()).filter(Boolean);
+	}
+	const configured = getProjectConfig(root).researchTools;
+	return Array.isArray(configured)
+		? configured.filter((value): value is string => typeof value === "string").map((value) => value.trim().toLowerCase()).filter(Boolean)
+		: [];
+}
+
 export function getOperationProfile(root: string): "interactive" | "autonomous" {
 	return getProjectConfig(root).profile === "autonomous" ? "autonomous" : "interactive";
 }

package/src/lib/types.ts

@@ -50,6 +50,21 @@ export interface ProjectConfig {
 	 */
 	requireSubagentReview?: boolean;
 	requireDocumentation?: boolean;
+	/**
+	 * Policy 25 (live-documentation research floor). Enabled by default: after
+	 * `liveDocFailureThreshold` failed tool calls with no live-documentation
+	 * lookup since the last failure, mutating/shell tools are blocked until the
+	 * session consults a current source. Set `false` in project config, or
+	 * `WORKFLOW_GUARD_REQUIRE_LIVE_DOCS=0` in the environment, to disable.
+	 */
+	requireLiveDocs?: boolean;
+	/** Failure count at which the research floor engages (default 3). */
+	liveDocFailureThreshold?: number;
+	/**
+	 * Extra tool-name fragments counted as a live-documentation lookup, for an
+	 * operator whose docs server is not in the builtin research token set.
+	 */
+	researchTools?: string[];
 	/**
 	 * Absolute paths of the LIVE control plane (runtime `~/.config/opencode`,
 	 * the guard's own install). When set, config-path protection classifies by

package/src/lib/v2-plugin.ts

@@ -38,6 +38,9 @@ import {
 	isLearningEnabled,
 	isProjectMemoryEnabled,
 	getProjectConfig,
+	isLiveDocsRequired,
+	getLiveDocFailureThreshold,
+	getResearchToolPatterns,
 } from "./state.ts";
 import {
 	openProjectMemory,
@@ -51,12 +54,14 @@ import {
 } from "./project-memory.ts";
 import { secretIn } from "../policies/secrets.ts";
 import { createCustomTools, buildWorkflowGuardSystemGuidance } from "./custom-tools.ts";
-import { isReadOnlyRole, SHELL_TOOL_NAMES } from "./guard-dispatcher.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 { EDIT_TOOL_NAMES, fetchParentSession, fetchParentSessionID, effectiveTodos } from "../policies/todo.ts";
 import { currentGitBranch, isProtectedBranchName } from "../policies/git.ts";
 import { checkCompletionClaims } from "../policies/completion.ts";
+import { checkSweepingClaims } from "../policies/sweeping-claims.ts";
+import { clearLiveDocsFloor, isResearchTool, liveDocsGatingReason, recordLiveDocsFailure, recordResearchLookup } from "../policies/live-docs.ts";
 import { releaseFileClaims } from "../policies/file-claims.ts";
 import { beginReadObservation, recordMutationObservation, recordSuccessfulRead, clearReadFingerprints } from "../policies/stale-write.ts";
 import { editTargets, runPostEditValidators, snapshotFile, type FileSnapshot } from "../policies/post-edit-validation.ts";
@@ -295,6 +300,30 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 					: "";
 				throw new Error(`[workflow-guard] ${reason}${circuitBreakerSuffix}`);
 			}
+			// Policy 25: repeated failures with no live lookup since block the
+			// guess-and-retry surfaces until the session grounds itself in
+			// current documentation (V1 parity). Research tools are never gated.
+			if (event.sessionID && isMutatingSurfaceTool(event.tool)) {
+				const threshold = getLiveDocFailureThreshold(toolWorktree);
+				if (isLiveDocsRequired(toolWorktree)) {
+					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(),
+							sessionID: event.sessionID,
+							callID: event.id,
+							tool: event.tool,
+							decision: "block",
+							phase: "decision",
+							reason: "live_docs_research_floor",
+						});
+						throw new Error(`[workflow-guard] ${researchReason}`);
+					}
+				}
+			}
 			toolLifecycle.start(event.sessionID, event.id);
 			const record = asRecord(args);
 			const workdir = typeof record?.workdir === "string" ? record.workdir : undefined;
@@ -721,6 +750,15 @@ async function handleV2Event(
 			};
 			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,
@@ -765,6 +803,20 @@ async function handleV2Event(
 					input: { claim: check.claim, evidenceState: check.evidenceState },
 				});
 			}
+			// Policy 26: journal sweeping repository claims unsupported by read
+			// coverage. Observability only - never mutates the response text.
+			const sweeping = checkSweepingClaims(text, { sessionID });
+			if (sweeping.sweeping && sweeping.reason) {
+				console.log(`[workflow-guard] sweeping claim mismatch: ${sweeping.reason}`);
+				audit({
+					ts: new Date().toISOString(),
+					sessionID,
+					tool: "experimental.text.complete",
+					decision: "allow",
+					reason: `Sweeping claim '${sweeping.claim}' with ${sweeping.readFileCount} file(s) read`,
+					input: { claim: sweeping.claim, readFileCount: sweeping.readFileCount },
+				});
+			}
 		} catch {}
 		return;
 	}
@@ -793,6 +845,7 @@ async function handleV2Event(
 			releaseFileClaims(sessionID);
 			clearReadFingerprints(sessionID);
 			toolLifecycle.clearSession(sessionID);
+			clearLiveDocsFloor(sessionID);
 			toolOutcomes.clearSession(sessionID);
 			clearTodoSessionState(sessionID);
 			toolLifecycle.takeRecoveryRun(sessionID);

package/src/policies/live-docs.ts

@@ -0,0 +1,157 @@
+/**
+ * Policy 25: Live-Documentation Research Floor.
+ *
+ * Failure mode this closes: after a handful of failed attempts, an agent keeps
+ * guessing from its training data instead of consulting current documentation,
+ * a live API reference, or a web source. Prior art calls the remedy "iterative
+ * grounding" (De-Hallucinator, arXiv 2401.01701) or a knowledge-lookup gate
+ * ("writes are refused unless a knowledge lookup has run in that turn").
+ *
+ * Scope: the floor blocks only mutation and shell tools - the surfaces where a
+ * guessed API, flag, or documented behavior actually gets written down. It
+ * never blocks a research tool, so the escape hatch is always the thing the
+ * agent should have reached for first.
+ *
+ * Semantics: the floor counts tool failures that occur *since the session last
+ * grounded itself in a live source*. A successful research call clears the
+ * debt; an unrelated successful tool does NOT, because "the guess happened to
+ * work once" is not the same as having consulted the documentation. This is
+ * deliberately stronger than the existing circuit breaker, whose counter resets
+ * on any success and so would be bypassed by a benign command.
+ *
+ * State is module-level, like `file-claims.ts`: verification/review evidence
+ * maps in `state.ts` are process-global by design so parent and subagent
+ * sessions share freshness, and the research floor follows that convention.
+ */
+
+/** Tool names that consult live/external sources (builtin + common aliases). */
+export const RESEARCH_TOOL_NAMES = new Set([
+	"websearch",
+	"webfetch",
+	"web_search",
+	"web_fetch",
+	"search_web",
+	"fetch_page",
+	"fetch_url",
+]);
+
+/**
+ * MCP tool names arrive namespaced (`mcp__<server>__<tool>`, `<server>_<tool>`),
+ * so a docs *server* is what makes a lookup live. Matching only documented
+ * server and API names keeps `read_wiki_index` and
+ * `guard_review_followup_resolve` from clearing debt as if they researched.
+ */
+const RESEARCH_SERVER_TOKENS = new Set([
+	"context7",
+	"deepwiki",
+	"tavily",
+	"brave",
+	"exa",
+	"kagi",
+	"perplexity",
+	"firecrawl",
+]);
+
+/**
+ * Tool-name segments that name a documentation lookup API. Names are split on
+ * non-alphanumerics first, so a multi-segment name matches on its parts: the
+ * `get-library-docs` tool matches via the `context7` server token.
+ */
+const RESEARCH_API_TOKENS = new Set(["docssearch", "searchdocs"]);
+
+/**
+ * A research tool is a recognised builtin/alias name, a documented MCP source
+ * (matched by server name), or an operator-declared name from `researchTools`.
+ */
+export function isResearchTool(toolName: string, extraPatterns: readonly string[] = []): boolean {
+	if (typeof toolName !== "string") return false;
+	const lower = toolName.toLowerCase();
+	if (RESEARCH_TOOL_NAMES.has(lower)) return true;
+	if (lower.includes("resolve-library")) return true;
+	const tokens = lower.split(/[^a-z0-9]+/).filter(Boolean);
+	if (tokens.some((token) => RESEARCH_SERVER_TOKENS.has(token) || RESEARCH_API_TOKENS.has(token))) return true;
+	return extraPatterns.some((pattern) => pattern.length > 0 && lower.includes(pattern));
+}
+
+const MAX_TRACKED_SESSIONS = 4096;
+
+/** Per-session failures accrued since the session last consulted a live source. */
+export class LiveDocsResearchFloor {
+	private readonly failuresSinceResearch = new Map<string, number>();
+
+	private bucket(sessionID: string): number {
+		return this.failuresSinceResearch.get(sessionID) ?? 0;
+	}
+
+	recordFailure(sessionID: string): void {
+		if (!sessionID) return;
+		this.failuresSinceResearch.set(sessionID, this.bucket(sessionID) + 1);
+		if (this.failuresSinceResearch.size > MAX_TRACKED_SESSIONS) {
+			this.failuresSinceResearch.delete(this.failuresSinceResearch.keys().next().value!);
+		}
+	}
+
+	/** A successful live-source lookup clears the session's research debt. */
+	recordResearch(sessionID: string): void {
+		if (!sessionID) return;
+		this.failuresSinceResearch.delete(sessionID);
+	}
+
+	failureCount(sessionID: string): number {
+		return this.bucket(sessionID);
+	}
+
+	/**
+	 * Returns a block reason when a non-research tool call must first consult a
+	 * live source, or `undefined` when the call may proceed. Research tools are
+	 * never gated, and calls below the failure threshold proceed.
+	 */
+	gatingReason(sessionID: string, toolName: string, threshold: number, extraPatterns: readonly string[] = []): string | undefined {
+		if (!sessionID) return undefined;
+		if (!Number.isInteger(threshold) || threshold < 1) return undefined;
+		if (isResearchTool(toolName, extraPatterns)) return undefined;
+		const count = this.bucket(sessionID);
+		if (count < threshold) return undefined;
+		return (
+			`Blocked: ${count} tool failure(s) in this session and no live documentation lookup since. ` +
+			`Stop guessing from training data and consult current sources first with 'websearch' or 'webfetch' ` +
+			`(or an MCP documentation tool), then retry. If the failure is environmental rather than a knowledge gap, ` +
+			`inspect the underlying error before retrying instead. If this session has no research tool at all, ` +
+			`an operator can disable the floor with requireLiveDocs: false or WORKFLOW_GUARD_REQUIRE_LIVE_DOCS=0.`
+		);
+	}
+
+	clearSession(sessionID: string): void {
+		this.failuresSinceResearch.delete(sessionID);
+	}
+}
+
+const floor = new LiveDocsResearchFloor();
+
+/** Record a tool failure for the session's research debt. */
+export function recordLiveDocsFailure(sessionID: string): void {
+	floor.recordFailure(sessionID);
+}
+
+/** Record that the session successfully consulted a live source. */
+export function recordResearchLookup(sessionID: string): void {
+	floor.recordResearch(sessionID);
+}
+
+/** Return the session's failures-since-research count (for tests/inspection). */
+export function liveDocsFailureCount(sessionID: string): number {
+	return floor.failureCount(sessionID);
+}
+
+/**
+ * Policy decision helper for the enforcement hooks: a block reason when a
+ * mutation/shell call must first research, otherwise `undefined`.
+ */
+export function liveDocsGatingReason(sessionID: string, toolName: string, threshold: number, extraPatterns: readonly string[] = []): string | undefined {
+	return floor.gatingReason(sessionID, toolName, threshold, extraPatterns);
+}
+
+/** Drop a session's floor state (session deletion). */
+export function clearLiveDocsFloor(sessionID: string): void {
+	floor.clearSession(sessionID);
+}

package/src/policies/stale-write.ts

@@ -85,3 +85,13 @@ export function staleWriteReason(path: string, sessionID: string): string | unde
 export function clearReadFingerprints(sessionID: string): void {
 	reads.delete(sessionID);
 }
+
+/**
+ * Number of distinct files the session has read or authored (a successful
+ * mutation seeds an observation too). Policy 26 uses this as reading-coverage
+ * evidence: a sweeping repository claim backed by one or two touched files is
+ * a skim, not a review.
+ */
+export function sessionReadFileCount(sessionID: string): number {
+	return reads.get(sessionID)?.size ?? 0;
+}

package/src/policies/sweeping-claims.ts

@@ -0,0 +1,71 @@
+/**
+ * Policy 26: Sweeping-Claim Grounding check (observability-only).
+ *
+ * Second failure mode: an agent skims one or two files and then asserts
+ * sweeping facts about the repository ("every caller does X", "the entire
+ * codebase uses Y", "nothing else references Z"). Prior art is explicit that
+ * adding more context does not fix this: the EPISTEMIC LEDGER work (arXiv
+ * 2602.07549) calls it a "bare assertion" - a claim with no supporting
+ * retrieval - and the agent-control-tower study found agents self-reporting
+ * completion/facts they never verified, with small models overclaiming most.
+ *
+ * This policy therefore does NOT block. Blocking on natural-language repo
+ * claims is false-positive prone (a grep-heavy investigation may legitimately
+ * support "no other callers" while touching few files), and Policy 24 already
+ * keeps this class of check observability-only. Instead it journals a mismatch
+ * between a sweeping claim and thin read coverage so the overclaim is visible
+ * in the audit trail and the app log.
+ *
+ * Coverage signal: distinct files this session has read or authored
+ * (`sessionReadFileCount`). A sweeping claim backed by fewer than
+ * `MIN_SWEEPING_READ_COVERAGE` touched files is a skim, but treat a future
+ * search/grep evidence channel as the authoritative breadth signal when it
+ * exists - this is a conservative floor, not a verdict.
+ */
+
+import { sessionReadFileCount } from "./stale-write.ts";
+
+/**
+ * A sweeping claim is an explicit whole-repo/whole-set assertion. Kept narrow
+ * to high-signal phrasings so casual wording ("check the whole file", "all
+ * files under src") does not trip it; bare file quantifiers are deliberately
+ * excluded and only named set nouns (codebase, repository, project, packages,
+ * modules, components, sources) are matched.
+ */
+const SWEEPING_CLAIM_RE =
+	/\b(?:the\s+)?(?:entire|whole|all|every)\s+(?:codebase|repository|repo|project|application|packages?|modules?|components?|sources?)\b|\b(?:throughout|across)\s+the\s+(?:codebase|repository|repo|project|code|app|application)\b|\bno\s+other\s+(?:place|occurrence|usage|reference|references|callers?|usages?)\b|\bnothing\s+(?:else\s+)?(?:uses?|references?|calls?|depends\s+on)\b|\bnot\s+used\s+anywhere\s+else\b/i;
+
+/** Distinct files that must be touched before a sweeping claim is "backed". */
+export const MIN_SWEEPING_READ_COVERAGE = 2;
+
+export interface SweepingClaimCheck {
+	sweeping: boolean;
+	claim?: string;
+	readFileCount: number;
+	reason?: string;
+}
+
+export function checkSweepingClaims(
+	text: string,
+	context?: { sessionID?: string },
+): SweepingClaimCheck {
+	const readFileCount =
+		context?.sessionID !== undefined ? sessionReadFileCount(context.sessionID) : 0;
+	if (!text) return { sweeping: false, readFileCount };
+
+	const match = text.match(SWEEPING_CLAIM_RE);
+	if (!match) return { sweeping: false, readFileCount };
+
+	if (readFileCount >= MIN_SWEEPING_READ_COVERAGE) {
+		return { sweeping: true, claim: match[0], readFileCount };
+	}
+
+	return {
+		sweeping: true,
+		claim: match[0],
+		readFileCount,
+		reason:
+			`the response makes a sweeping repository claim ("${match[0]}") but this session has read or authored only ` +
+			`${readFileCount} distinct file(s). Verify the claim with a broader search/read before stating it as fact.`,
+	};
+}