opencode-workflow-guard 1.15.5 → 1.17.0

package/src/lib/v2-todo.ts

@@ -2,12 +2,27 @@
  * V2 todo reconstruction shared by the plugin entrypoint and its V1 SDK
  * adapter.
  *
- * OpenCode V2 exposes no todo endpoint, and its builtin tool registry has no
- * `todowrite` (the V1 name). Todo state therefore only exists when an ACP agent
- * supplies its own `todowrite` tool. This module reads that state from session
- * message history and distinguishes "definitively empty" from "cannot
- * determine", which the policy layer relies on to decide whether to enforce the
- * active-todo gate.
+ * Version boundary, because the two generations need different treatment:
+ *
+ * - **OpenCode 2.0.x** exposes no todo endpoint and its builtin tool registry
+ *   has no `todowrite` (the V1 name). Todo state only exists when an ACP agent
+ *   supplies its own `todowrite` tool, so the list is reconstructed from
+ *   session message history.
+ * - **OpenCode 2.1.x** reintroduces a builtin `todowrite` behind the
+ *   `experimental.todo` config key. When that tool is registered, a session
+ *   with no todo part has never planned, which must gate mutations rather than
+ *   fail open.
+ *
+ * Capability is therefore probed, not inferred from history: `detectTodoCapability`
+ * asks the host's tool registry (`ctx.tool.list()`) whether `todowrite` is
+ * registered. History tells you whether a session planned; the registry tells
+ * you whether planning was possible. Only the second question decides whether
+ * an empty list means "not yet planned" or "cannot plan".
+ *
+ * This module distinguishes "definitively empty" from "cannot determine", which
+ * the policy layer relies on to decide whether to enforce the active-todo gate.
+ * Todos are never evidence: a `todowrite` call replaces the whole list, so a
+ * model can mark everything completed without doing the work.
  */
 
 import type { TodoItem } from "./types.ts";
@@ -19,6 +34,50 @@ export interface TodoScanContext {
 	};
 }
 
+/** Minimal tool-registry surface needed to probe for `todowrite`. */
+export interface TodoCapabilityContext {
+	tool?: {
+		list?: () => Promise<unknown>;
+	};
+}
+
+/**
+ * Whether this host can plan at all.
+ *
+ * - `available`: the registry reports `todowrite`, so an empty list means the
+ *   session never planned and the gate must enforce.
+ * - `unavailable`: the registry answered and has no `todowrite`, so the gate
+ *   must fail open or builtin-only sessions deadlock.
+ * - `unknown`: the registry could not be read. Treat as unavailable for
+ *   enforcement, but say so out loud (the caller logs once per session).
+ */
+export type TodoCapability = "available" | "unavailable" | "unknown";
+
+/**
+ * Probe the host's tool registry for `todowrite`.
+ *
+ * Tool ids on the host are effective names, so a namespaced or prefixed
+ * registration (`todowrite`, `todo.write`) still counts. A registry that throws
+ * or is absent reports `unknown` rather than `unavailable`, because "we could
+ * not ask" must never be reported as "the host said no".
+ */
+export async function detectTodoCapability(ctx: TodoCapabilityContext | undefined): Promise<TodoCapability> {
+	const list = ctx?.tool?.list;
+	if (typeof list !== "function") return "unknown";
+	try {
+		const entries = await list.call(ctx!.tool);
+		if (!Array.isArray(entries)) return "unknown";
+		return entries.some((entry) => {
+			const name = (entry as { name?: unknown; id?: unknown } | undefined)?.name ?? (entry as { id?: unknown } | undefined)?.id;
+			return typeof name === "string" && /^todowrite$/i.test(name);
+		})
+			? "available"
+			: "unavailable";
+	} catch {
+		return "unknown";
+	}
+}
+
 /**
  * V2 tool parts carry the tool name in `tool` (the V1 field was `name`); ACP
  * agents may still report either shape, so accept both.
@@ -29,6 +88,66 @@ export function toolPartName(part: { tool?: unknown; name?: unknown }): string |
 	return undefined;
 }
 
+/**
+ * Proven capability per plugin instance, for reporting and for the fail-open
+ * warning. Held on `globalThis` via `Symbol.for` because OpenCode can load the
+ * same package from two module paths (a cache copy plus a source checkout), and
+ * the capability answer must agree between them.
+ */
+const TODO_CAPABILITY = Symbol.for("opencode-workflow-guard.todo-capability.v1");
+const capabilityRegistry = globalThis as unknown as Record<symbol, TodoCapability | undefined>;
+
+/** Last probed capability. `unknown` before setup, which fails open. */
+export function recordedTodoCapability(): TodoCapability {
+	return capabilityRegistry[TODO_CAPABILITY] ?? "unknown";
+}
+
+/**
+ * Record the probed capability. Returns the previous value so the caller can
+ * tell whether this is the first probe for the process.
+ */
+export function recordTodoCapability(capability: TodoCapability): TodoCapability {
+	const previous = recordedTodoCapability();
+	capabilityRegistry[TODO_CAPABILITY] = capability;
+	return previous;
+}
+
+export function resetTodoCapabilityForTesting(): void {
+	delete capabilityRegistry[TODO_CAPABILITY];
+}
+
+/**
+ * Sessions already warned about the fail-open path. Bounded: the warning is
+ * once per session, and a process that outlives thousands of sessions must not
+ * leak a set for every one of them.
+ */
+const WARNED_SESSIONS = Symbol.for("opencode-workflow-guard.todo-warned.v2");
+const warnedRegistry = globalThis as unknown as Record<symbol, Set<string> | undefined>;
+const warnedSessions: Set<string> =
+	warnedRegistry[WARNED_SESSIONS] ?? (warnedRegistry[WARNED_SESSIONS] = new Set());
+const MAX_WARNED_SESSIONS = 512;
+
+/**
+ * Report the active-todo gate failing open, once per session.
+ *
+ * Silent fail-open is how a rails policy becomes decorative: the gate stops
+ * enforcing and nothing says so. Returns true when this call was the first for
+ * the session, so the caller can journal it exactly once.
+ */
+export function reportTodoGateFailOpen(sessionID: string | undefined, capability: TodoCapability): boolean {
+	const key = sessionID ?? "<no-session>";
+	if (warnedSessions.has(key)) return false;
+	if (warnedSessions.size >= MAX_WARNED_SESSIONS) warnedSessions.clear();
+	warnedSessions.add(key);
+	try {
+		console.warn(
+			`[workflow-guard] warn: active-todo gate is not enforcing for session ${key}: ` +
+				`todoCapability=${capability}. Mutations are allowed without an active todo.`,
+		);
+	} catch {}
+	return true;
+}
+
 /**
  * Reconstruct one session's current todo list from its message history. The
  * newest applied `todowrite` tool call's input is the current state.
@@ -37,7 +156,13 @@ export function toolPartName(part: { tool?: unknown; name?: unknown }): string |
  * - `TodoItem[]` when a `todowrite` part defines the list, including `[]` when
  *   the newest applied call emptied it;
  * - `undefined` when todo state is unknown: the history cannot be read, or the
- *   session contains no `todowrite` part at all (no todo capability).
+ *   session contains no `todowrite` part and the capability is absent.
+ *
+ * `capability` decides what an empty history means. When the host reports
+ * `available`, a session with no `todowrite` part has never planned, so the
+ * result is `[]` and the mutation gate enforces. When it is `unavailable` or
+ * `unknown`, an empty history stays `undefined` so builtin-only sessions fail
+ * open instead of deadlocking on a tool they cannot call.
  *
  * Callers must treat `undefined` as "cannot determine" (fail open) and `[]` as
  * "definitively no active todos" (enforce). Collapsing the two is what
@@ -46,6 +171,7 @@ export function toolPartName(part: { tool?: unknown; name?: unknown }): string |
 export async function scanSessionTodos(
 	ctx: TodoScanContext,
 	sessionID: string,
+	capability: TodoCapability = "unknown",
 ): Promise<TodoItem[] | undefined> {
 	try {
 		const messages = (await ctx.session.context({ sessionID })) as unknown as Array<{ content?: unknown }>;
@@ -66,6 +192,10 @@ export async function scanSessionTodos(
 				if (Array.isArray(todos)) return todos as TodoItem[];
 			}
 		}
+		// No applied `todowrite` part. With a registered tool that means the
+		// session never planned, which must gate. Without one, the session
+		// cannot plan at all, so the gate has nothing to enforce.
+		if (capability === "available") return [];
 		// A `todowrite` part exists but none is applied yet (e.g. still
 		// streaming): the list is in flux, report it as empty rather than
 		// unknown so the gate stays closed until the write settles.

package/src/lib/version.ts

@@ -19,3 +19,25 @@ export function loadedPluginVersion(moduleUrl: string = import.meta.url): string
 		return undefined;
 	}
 }
+
+/**
+ * The OpenCode release this build is qualified against, read from the pinned
+ * `@opencode/plugin` dependency in the same manifest.
+ *
+ * Pinning the host API stops an unreviewed major from floating in, but a
+ * published guard can still be installed into a host that is newer or older
+ * than the one it was verified on. Reporting the qualified pair next to the
+ * loaded host version makes that mismatch visible before it becomes a silent
+ * no-op, which is the failure mode the migration guide names.
+ */
+export function qualifiedHostVersion(moduleUrl: string = import.meta.url): string | undefined {
+	try {
+		const manifest = JSON.parse(readFileSync(fileURLToPath(new URL("../../package.json", moduleUrl)), "utf8")) as {
+			dependencies?: Record<string, unknown>;
+		};
+		const pinned = manifest.dependencies?.["@opencode/plugin"];
+		return typeof pinned === "string" && /^\d+\.\d+\.\d+/.test(pinned) ? pinned : undefined;
+	} catch {
+		return undefined;
+	}
+}

package/src/lib/worktree.ts

@@ -197,6 +197,40 @@ export function createGitWorktree(
 	}
 }
 
+/**
+ * Validate a worktree directory the HOST created before the guard accepts it.
+ *
+ * The host is a widening authority only in the sense that it may choose the
+ * directory (its configured `worktree.directory`). It is never an authority
+ * that the directory is safe: the guard re-checks the filesystem and the git
+ * registration itself, and refuses the primary working tree. A host adapter
+ * that returns a bogus path therefore fails closed.
+ */
+export function validateHostWorktreeDirectory(
+	directory: string,
+	root = getWorkspaceRoot(),
+): { ok: boolean; error?: string } {
+	if (!directory || typeof directory !== "string") {
+		return { ok: false, error: "Host worktree create returned no directory." };
+	}
+	const resolved = resolve(directory);
+	if (!existsSync(resolved)) {
+		return { ok: false, error: `Host declared worktree '${directory}' does not exist.` };
+	}
+	const registered = registeredWorktreePaths(root);
+	if (!registered) {
+		return { ok: false, error: "Failed to list registered worktrees - cannot validate the host worktree." };
+	}
+	const resolvedRegistered = registered.map((path) => resolve(path));
+	if (!resolvedRegistered.includes(resolved)) {
+		return { ok: false, error: `Host declared worktree '${directory}' is not a registered worktree of this repository.` };
+	}
+	if (resolvedRegistered[0] === resolved) {
+		return { ok: false, error: "Host declared the primary working tree as a worktree - refusing." };
+	}
+	return { ok: true };
+}
+
 function registeredWorktreePaths(root: string): string[] | undefined {
 	const res = spawnSync("git", ["worktree", "list", "--porcelain"], {
 		cwd: root,
@@ -215,23 +249,37 @@ function registeredWorktreePaths(root: string): string[] | undefined {
 export function cleanupGitWorktree(
 	worktreePath: string,
 	root = getWorkspaceRoot(),
+	options?: {
+		/**
+		 * Directories the HOST declares as its worktrees for this project
+		 * (`ctx.worktree.list`). This is the only way cleanup may reach a
+		 * worktree outside the guard's own storage directory: the host is the
+		 * authority that the directory belongs to its inventory, and the
+		 * registration and primary-tree checks below still apply. Omitting the
+		 * list keeps the original storage-only behaviour.
+		 */
+		hostWorktrees?: readonly string[];
+	},
 ): { success: boolean; error?: string } {
 	try {
 		const resolved = resolve(worktreePath);
 		const storageBase = resolve(getWorktreeStorageDir(root));
+		const hostOwned = Boolean(options?.hostWorktrees?.some((path) => resolve(path) === resolved));
+		const withinStorage = resolved === storageBase || resolved.startsWith(storageBase + sep);
+		if (!withinStorage && !hostOwned) {
+			return {
+				success: false,
+				error: `Refusing to clean up '${worktreePath}': path is outside the worktree storage directory (${storageBase}) and is not a host-declared worktree.`,
+			};
+		}
 		if (!existsSync(worktreePath)) {
 			// A registered worktree whose directory is gone (manual removal, a
 			// crashed add, external cleanup) still holds a stale admin entry that
 			// keeps it in `git worktree list` as prunable, and must still be
-			// cleanable. Anything outside storage or unregistered is refused.
-			// The primary working tree is never at risk: prune only removes
-			// admin dirs under .git/worktrees/<id>, which the main tree lacks.
-			if (resolved !== storageBase && !resolved.startsWith(storageBase + sep)) {
-				return {
-					success: false,
-					error: `Refusing to clean up '${worktreePath}': path is outside the worktree storage directory (${storageBase}).`,
-				};
-			}
+			// cleanable. Anything outside storage (unless the host declares it)
+			// or unregistered is refused. The primary working tree is never at
+			// risk: prune only removes admin dirs under .git/worktrees/<id>,
+			// which the main tree lacks.
 			const registeredMissing = registeredWorktreePaths(root);
 			if (!registeredMissing) {
 				return { success: false, error: "Failed to list registered worktrees - aborting cleanup." };
@@ -252,15 +300,10 @@ export function cleanupGitWorktree(
 		}
 
 		// Ownership validation: the path must live under the configured worktree
-		// storage directory AND be a registered worktree of this repository. This
-		// refuses arbitrary directories, other repos' worktrees, and the primary
-		// working tree - cleanup must never be an unrestricted delete primitive.
-		if (resolved !== storageBase && !resolved.startsWith(storageBase + sep)) {
-			return {
-				success: false,
-				error: `Refusing to clean up '${worktreePath}': path is outside the worktree storage directory (${storageBase}).`,
-			};
-		}
+		// storage directory (or be declared by the host) AND be a registered
+		// worktree of this repository. This refuses arbitrary directories, other
+		// repos' worktrees, and the primary working tree - cleanup must never be
+		// an unrestricted delete primitive.
 		const registered = registeredWorktreePaths(root);
 		if (!registered) {
 			return { success: false, error: "Failed to list registered worktrees - aborting cleanup." };

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/mcp.ts

@@ -3,7 +3,13 @@ export const MCP_MUTATION_VERB_RE =
 export const MCP_READ_ONLY_RE =
 	/(?:^|_)(?:get|list|search|show|query|describe|find|read|status|diff|log)(?:_|$)/;
 
-export const GUARDED_MCP_SERVERS = new Set([
+/**
+ * Static guarded live-system server tokens.
+ *
+ * These stay in force regardless of host inventory, because tool names are
+ * model-supplied text and the MCP policy is a live-system rail.
+ */
+export const GUARDED_MCP_SERVERS: ReadonlySet<string> = new Set([
 	"github",
 	"gh",
 	"azure",
@@ -13,12 +19,51 @@ export const GUARDED_MCP_SERVERS = new Set([
 	"azuredevops",
 ]);
 
+/**
+ * Tokens learned from the HOST's MCP inventory (`ctx.mcp.list()`), offered by
+ * `lib/mcp-inventory.ts` when a server connects or its tools change.
+ *
+ * Widen-only. A server the operator removed contributes nothing new, but the
+ * static defaults above are never narrowed, so removing a server cannot
+ * unguard a tool that still names it. Empty on hosts without the API, which
+ * leaves behaviour identical to the static list.
+ *
+ * Held on `globalThis` via `Symbol.for` because OpenCode can load the same
+ * package from two distinct module paths (a cache copy plus a source
+ * checkout), and each copy would otherwise get its own set.
+ */
+const HOST_GUARDED_MCP_TOKENS = Symbol.for("opencode-workflow-guard.mcp-tokens.v1");
+const tokenRegistry = globalThis as unknown as Record<symbol, Set<string> | undefined>;
+const hostGuardedMcpTokens: Set<string> =
+	tokenRegistry[HOST_GUARDED_MCP_TOKENS] ?? (tokenRegistry[HOST_GUARDED_MCP_TOKENS] = new Set());
+
+/** Register host-declared server tokens. Returns the tokens that were new. */
+export function addGuardedMcpTokens(tokens: Iterable<string>): string[] {
+	const added: string[] = [];
+	for (const token of tokens) {
+		const normalized = String(token).toLowerCase().trim();
+		if (!normalized || GUARDED_MCP_SERVERS.has(normalized) || hostGuardedMcpTokens.has(normalized)) continue;
+		hostGuardedMcpTokens.add(normalized);
+		added.push(normalized);
+	}
+	return added;
+}
+
+export function resetGuardedMcpTokensForTesting(): void {
+	hostGuardedMcpTokens.clear();
+}
+
+/** Effective guarded token set: static defaults plus host-declared widening. */
+export function guardedMcpServers(): ReadonlySet<string> {
+	return new Set([...GUARDED_MCP_SERVERS, ...hostGuardedMcpTokens]);
+}
+
 export function mcpMutationTool(toolName: string): string | undefined {
 	if (!MCP_MUTATION_VERB_RE.test(toolName) || MCP_READ_ONLY_RE.test(toolName)) {
 		return undefined;
 	}
 	const tokens = toolName.toLowerCase().split(/[^a-z0-9]+/);
-	if (tokens.some((t) => GUARDED_MCP_SERVERS.has(t))) {
+	if (tokens.some((t) => GUARDED_MCP_SERVERS.has(t) || hostGuardedMcpTokens.has(t))) {
 		return "GitHub/Azure DevOps";
 	}
 	return undefined;

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.`,
+	};
+}

package/src/policies/tamper.ts

@@ -11,7 +11,7 @@ export const PROTECTED_PATH_REASON =
 	"these manually in configuration or the UI.";
 
 const GT = String.fromCharCode(62);
-const V_LIST = ["sed\\s+-i", "tee", "mv", "cp", "rm", "chmod", "chown", "ln", "install", "truncate", "dd"].join("|");
+const V_LIST = ["sed\\s+-i", "tee", "mv", "cp", "rm", "chmod", "chown", "ln", "install", "truncate", "dd", "patch", "perl\\s+-[^\\s]*i"].join("|");
 const C_LIST = ["open" + "code\\.jsonc?", "\\.config\\/open" + "code", "\\.open" + "code\\/"].join("|");
 const U_LIST = ["\\.config\\/open" + "code\\/(?:plugins|ui)\\/"].join("|");