opencode-workflow-guard 1.12.0 → 1.13.1

package/README.md

@@ -14,15 +14,18 @@ Workflow Guard is deliberately **not an agent harness**: it can constrain action
 
 ### 1. Installation
 
-Install the current published version globally with OpenCode's plugin installer:
+Install the current published version globally:
 
 ```bash
 VERSION=$(npm view opencode-workflow-guard version)
-opencode plugin "opencode-workflow-guard@$VERSION" --global --force
+opencode plugin add "opencode-workflow-guard@$VERSION"   # OpenCode 2.x
+opencode plugin "opencode-workflow-guard@$VERSION" --global --force   # OpenCode 1.x
 ```
 
 *Requires OpenCode >= 1.18.* OpenCode detects the package's server and TUI targets and updates both global configs. Use the same command after a release to upgrade; the explicit version gives OpenCode a fresh package-cache key. Restart OpenCode after installation. See [docs/installation.md](docs/installation.md) for details and links to the OpenCode plugin documentation.
 
+The plugin supports both generations from one package: **OpenCode 1.x** loads the `server()` entrypoint, and **OpenCode 2.x** loads the `setup()` entrypoint (`@opencode/plugin`). Policies, tools, and configuration behave the same on both; V2 load tests run against a real OpenCode 2 binary in `npm run test:install`.
+
 For the optional TUI badge, configure `"opencode-workflow-guard"` in `tui.json`. OpenCode resolves the package's exported `./tui` entrypoint automatically for TUI plugins. The companion keeps a static `Workflow Guard` shield in the prompt bar; warning toasts provide block details without changing agent behavior. Do not place the TUI module under the server `plugins/` directory.
 
 ![Workflow Guard status badge in the OpenCode TUI](docs/assets/workflow-guard-tui-badge.png)

package/docs/installation.md

@@ -6,7 +6,7 @@
 
 ## Requirements
 
-- **OpenCode >= 1.18** (requires the `GET /session/:id/todo` endpoint and V1 `PluginModule` loader).
+- **OpenCode >= 1.18** (V1: requires the `GET /session/:id/todo` endpoint and the V1 `PluginModule` loader) or **OpenCode 2.x** (V2: loads through the `@opencode/plugin` API; the current todo list is reconstructed from the session message history because V2 has no todo endpoint).
 - **Node.js >= 22.18** or **Bun** (for running test scripts directly).
 
 ---
@@ -19,10 +19,11 @@ Install the current published version with OpenCode's plugin command:
 
 ```bash
 VERSION=$(npm view opencode-workflow-guard version)
-opencode plugin "opencode-workflow-guard@$VERSION" --global --force
+opencode plugin add "opencode-workflow-guard@$VERSION"                    # OpenCode 2.x
+opencode plugin "opencode-workflow-guard@$VERSION" --global --force       # OpenCode 1.x
 ```
 
-OpenCode documents `opencode plugin <module>` as the command to install a plugin and update its config, `--global` as global installation, and `--force` as replacing an existing plugin version. Workflow Guard exposes both server and TUI targets, so OpenCode detects both and updates their global configuration files. Restart OpenCode after installation because configuration is loaded at startup. See the [OpenCode plugin CLI documentation](https://opencode.ai/docs/cli/#plugin).
+OpenCode 2 documents `opencode plugin add <package>` as the command to install a plugin and add it to the global configuration; OpenCode 1 documents `opencode plugin <module>` with `--global` and `--force`. Workflow Guard exposes both server and TUI targets, so OpenCode detects both and updates their global configuration files (OpenCode 2 uses one global `cli.json` for terminal-client settings). Restart OpenCode after installation because configuration is loaded at startup. See the [OpenCode plugin CLI documentation](https://opencode.ai/docs/cli/#plugin).
 
 Use the same two commands to upgrade after a Workflow Guard release. Keep the explicit version in OpenCode's configuration rather than relying on a bare package name or `@latest`: OpenCode caches npm plugins, and an already-populated `@latest` cache key may continue resolving to the version that originally populated it. An explicit new version creates a new package-cache key without manually deleting OpenCode's cache.
 

package/docs/policies.md

@@ -12,7 +12,7 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 - **Pre-edit Gate:** All file-editing tools (`edit`, `write`, `apply_patch`) are blocked until the session has an active task list in OpenCode's native todo system (`todowrite`, persisted at `GET /session/:id/todo`).
 - **Flexible Task Execution:** Tasks can be completed in any order as work concludes without artificial sequential blockers, maintaining maximum pair-programming DX.
 - **No Silent Deletion:** Each `todowrite` update replaces the complete list. Active tasks must remain in subsequent updates until they are explicitly marked `completed` or `cancelled`.
-- **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. 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 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.
 - **Subagent Inheritance & Role Confinement:** Subagents automatically 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.
 - **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.
@@ -60,6 +60,8 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
   - Direct edits of the same paths through the `edit`/`write`/`apply_patch` tools
   - Shell commands invoking `opencode auth`, `opencode config`, `opencode permission`, or `opencode run --auto`
   - Evasion-normalized: quote-concatenation (`open''code.json`), escapes (`open\c\ode`), and glob wildcards (`opencode.jso?`) are stripped before matching.
+- Collaboration commands (`gh issue`, `gh pr`, `glab issue`, `glab pr`, `az repos pr`) and document content mentioning guarded paths are not tampering: quoted arguments are command data, not shell syntax (redirect analysis runs on the quote-stripped residue), and the redirect heuristic applies to shell commands only (write/edit content is guarded by the target path check instead).
+- Plan files under `.opencode/plans/` are exempt: opencode's plan mode writes agent-authored plan markdown there, and plans are content, not configuration. Everything else under `.opencode/` (including the directory itself) stays protected.
 - **Read-only access is allowed** (`cat`, `less`, `grep`, `head`, `tail` on config files) - only modification attempts trigger the guard.
 
 ### 7. Feature-Branch Workflow
@@ -75,17 +77,18 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 - The boundary has **no override**: `WORKFLOW_GUARD_ALLOW_LIVE=1` covers live-system commands only and never weakens the workspace confinement.
 
 ### 9. Script-Laundering Guard
-- Content written via `edit`, `write`, or `apply_patch` is scanned for destructive CLI commands and settings tamper payloads.
+- Content written via `edit`, `write`, or `apply_patch` is scanned for destructive CLI commands.
 - Prevents agents from bypassing shell guards by writing destructive commands to script files (e.g. `write deploy.sh` -> `bash deploy.sh`).
 
 ### 10. Evidence-Based Verification
 - When the agent attempts to mark **every** task completed (finalizing the request), the guard requires passing verification evidence.
 - Verification (`WORKFLOW_GUARD_VERIFY` env, project `verifyCommand`, or auto-detected test/typecheck runner across ecosystems: `package.json` (`npm test`, `npm run typecheck`, `npm run check`, `npm run build`), `Cargo.toml` (`cargo test`), `go.mod` (`go test ./...`), `pytest.ini`/`pyproject.toml` (`pytest`), or `deno.json` (`deno test`)) executes in an isolated environment with scrubbed credentials, output caps, token-efficient stdout/stderr snipping, and strict timeout protection. Environment configuration takes precedence over project configuration.
+- The verification timeout defaults to 30 seconds and can be raised per project (`verifyTimeoutMs` in `.opencode/workflow-guard.json`) or per environment (`WORKFLOW_GUARD_VERIFY_TIMEOUT_MS`, which wins over project config); non-positive values are ignored and fall back to the default. Raise it for suites that legitimately exceed the default - for example this repository's own unit suite.
 - Project `postEditValidators` can run faster targeted checks after a direct file edit actually changes the target. Each entry accepts a workspace-relative glob `pattern` (`*`, `**`, and `?` wildcards; brace expansion and character classes are not supported), 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 and do not replace the blocking whole-project finalization verification. Multi-file `apply_patch` calls validate every changed target.
 - With project `recoveryCheckpoints: true`, or the `autonomous` operation profile unless explicitly overridden, genuine root-session user runs capture a private Git checkpoint before agent work starts. Checkpoints preserve tracked and untracked state without using the user's stash list; subagents and generated continuation prompts do not replace them. At `session.idle`, the run's resulting workspace fingerprint is recorded before automatic continuation. `guard_recovery_restore` is provenance-bound to the same root session and refuses restoration after any intervening workspace change. Operation profiles only set optional workflow defaults and cannot weaken core safety policies.
 - Automatic continuation remains synthetic. By default, an eligible root session with unfinished owned todos briefly waits for OpenCode's native asynchronous title generation before that continuation is sent; set `titleSettleWorkaround: false` to opt out. The bounded wait never rewrites titles or provider/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.
-- **Durable Disk Cache:** Passing verification results are cached to `~/.local/state/opencode/workflow-guard/last-verify.json`, allowing session restarts and multi-agent handoffs to retain valid verification evidence without redundant test runs. Durable evidence is **workspace-bound**: a cached result is only accepted for the workspace that produced it, so a passing run in one project can never satisfy finalization in another.
+- **Durable Disk Cache:** Passing verification results (`~/.local/state/opencode/workflow-guard/last-verify.json`) and passing secondary review approvals (`~/.local/state/opencode/workflow-guard/last-review.json`) are cached to disk, allowing session restarts and multi-agent handoffs to retain valid verification and review evidence without redundant test runs. Durable evidence is **workspace-bound**: a cached result is only accepted for the workspace that produced it, so a passing run in one project can never satisfy finalization in another.
 - If verification fails, finalization is blocked with a structured summary of error markers, stack traces, and failure output.
 - OpenCode's current `lsp.client.diagnostics` event identifies the server and path but does not expose the diagnostics themselves, so the guard deliberately does not claim an LSP-clean finalization gate until the SDK provides a supported diagnostics source.
 - The verify command is **disabled** when `WORKFLOW_GUARD_VERIFY` is empty (`""`).
@@ -135,6 +138,7 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 ### 20. Merged Branch & Base Freshness Guard
 - Blocks pushing to branches already merged or associated with closed PRs in GitHub or Azure DevOps.
 - Blocks creating fresh feature branches when the local base branch is behind the remote, prompting the agent to pull latest changes first.
+- Tag push refspecs are exempt: publishing an existing tag (`git push origin v1.2.0`, `git push origin refs/tags/v1.2.0`) and creating tags (`git tag v1.2.0`, `git tag -a -m ...`) are release operations, not branch mutations - only tag deletions (`git tag -d`, `git push origin :refs/tags/v1.2.0`, `--delete`) stay blocked.
 
 ### 21. Documentation Review & Synchronization Guard
 - Ensures that relevant documentation is updated whenever changes introduce new features, policies, or public tools before PR creation. Configurable via `.opencode/workflow-guard.json` (`requireDocumentation: true`) or `WORKFLOW_GUARD_REQUIRE_DOCS=1`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",
@@ -48,8 +48,10 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "latest",
+    "@opencode/plugin": "latest",
     "@opentui/solid": "latest",
-    "jsonc-parser": "latest"
+    "jsonc-parser": "latest",
+    "@opencode/ai": "latest"
   },
   "devDependencies": {
     "@changesets/cli": "latest",

package/src/lib/audit.ts

@@ -3,7 +3,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { Database, type SqliteDatabase } from "./sqlite.ts";
-import type { AuditEntry, PolicyDecision, VerifyResult } from "./types.ts";
+import type { AuditEntry, PolicyDecision, VerifyResult, ReviewResult } from "./types.ts";
 import { asRecord } from "./utils.ts";
 
 const AUDIT_DIR = join(
@@ -14,6 +14,7 @@ const AUDIT_DIR = join(
 const AUDIT_FILE = join(AUDIT_DIR, "workflow-guard.jsonl");
 const VERIFY_CACHE_FILE = join(AUDIT_DIR, "last-verify.json");
 const VERIFY_HISTORY_FILE = join(AUDIT_DIR, "verify-history.jsonl");
+const REVIEW_CACHE_FILE = join(AUDIT_DIR, "last-review.json");
 const MAX_AUDIT_BYTES = 4 * 1024 * 1024;
 const RETAIN_AUDIT_BYTES = 2 * 1024 * 1024;
 const MAX_VERIFY_HISTORY_BYTES = 1024 * 1024;
@@ -62,6 +63,10 @@ export function getVerifyHistoryFilePath(): string {
 	return VERIFY_HISTORY_FILE;
 }
 
+export function getReviewCacheFilePath(): string {
+	return REVIEW_CACHE_FILE;
+}
+
 function appendBoundedJsonlUnlocked(path: string, value: unknown, maxBytes: number, retainBytes: number): void {
 	appendFileSync(path, JSON.stringify(value) + "\n", { encoding: "utf8", mode: 0o600 });
 	chmodSync(path, 0o600);
@@ -156,6 +161,33 @@ export function loadVerifyCache(): VerifyResult | undefined {
 	return undefined;
 }
 
+/**
+ * Persists passing secondary review approval to disk so session restarts
+ * or multi-agent handoffs retain valid review approval state.
+ */
+export function persistReviewCache(reviewData: ReviewResult): void {
+	try {
+		mkdirSync(AUDIT_DIR, { recursive: true });
+		writeFileSync(REVIEW_CACHE_FILE, JSON.stringify(reviewData, null, 2), { encoding: "utf8", mode: 0o600 });
+		chmodSync(REVIEW_CACHE_FILE, 0o600);
+	} catch {}
+}
+
+/**
+ * Loads durable review approval from disk if present.
+ */
+export function loadReviewCache(): ReviewResult | undefined {
+	try {
+		if (!existsSync(REVIEW_CACHE_FILE)) return undefined;
+		const raw = readFileSync(REVIEW_CACHE_FILE, "utf8");
+		const data = JSON.parse(raw);
+		if (data && typeof data.reviewer === "string" && typeof data.timestamp === "number" && typeof data.passed === "boolean") {
+			return data;
+		}
+	} catch {}
+	return undefined;
+}
+
 /**
  * Reads recent audit entries from the end of the JSONL audit log with a bounded
  * buffer window to prevent memory spikes on long-lived installations.

package/src/lib/custom-tools.ts

@@ -29,6 +29,7 @@ import {
 	isReviewRequired,
 	recordMutation,
 	recordReviewResult,
+	resolveEffectiveWorkspace,
 	runWithRuntimeState,
 } from "./state.ts";
 import { getRalphOutcome } from "../policies/continuation.ts";
@@ -46,11 +47,19 @@ import { currentGitBranch, onProtectedBranch } from "../policies/git.ts";
 import { effectiveTodoOwnerSessionID, effectiveTodos, fetchParentSession, fetchParentSessionID, hasActiveTodo } from "../policies/todo.ts";
 
 export function extractReviewFollowups(summary: string): Array<{ severity: "P2" | "P3"; summary: string }> {
-	return summary.split(/\r?\n/).map((line) => ({
-		line: line.trim(),
-		severity: line.match(/(?:^|\s)(P[23])(?:\b|[:])/i)?.[1]?.toUpperCase() as "P2" | "P3" | undefined,
-	})).filter((finding): finding is { line: string; severity: "P2" | "P3" } => Boolean(finding.line && finding.severity))
-		.map((finding) => ({ severity: finding.severity, summary: finding.line }));
+	return summary.split(/\r?\n/).map((line) => {
+		const trimmed = line.trim();
+		const match = trimmed.match(/(?:^|\s)(P[23])(?:\b|[:])/i);
+		const severity = match?.[1]?.toUpperCase() as "P2" | "P3" | undefined;
+		return { line: trimmed, severity };
+	}).filter((finding): finding is { line: string; severity: "P2" | "P3" } => {
+		if (!finding.line || !finding.severity) return false;
+		const rest = finding.line.replace(new RegExp(`^.*?(?:${finding.severity})\\s*[:\\-]?\\s*`, "i"), "").trim();
+		if (!rest || /^(?:none|nil|n\/?a|0|zero|no\s+(?:issues|findings|defects|items|blockers)|clean|passed|ok|none\s+identified)\b/i.test(rest)) {
+			return false;
+		}
+		return true;
+	}).map((finding) => ({ severity: finding.severity, summary: finding.line }));
 }
 
 export function buildWorkflowGuardSystemGuidance(options: {
@@ -196,9 +205,13 @@ export function createCustomTools(options: {
 			}),
 		} : {}),
 		guard_status: tool({
-			description: "Inspect active guardrails, current branch protection, mutation count, outstanding verification/review requirements, and ralph status. Proactively call at session start and before completing tasks or creating PRs.", args: {},
-			execute: async (_args, toolContext) => {
-				const root = effectiveRoot; const branch = currentGitBranch(root) ?? "unknown"; const isProtected = onProtectedBranch(root); const lastV = getLastVerifyResultForWorkspace(root); const lastR = getLastReviewResultForWorkspace(root); const lastMut = getWorkspaceMutationTimestamp(root); const cfg = loadProjectConfig(root);
+			description: "Inspect active guardrails, current branch protection, mutation count, outstanding verification/review requirements, and ralph status. Proactively call at session start and before completing tasks or creating PRs.",
+			args: {
+				directory: tool.schema.string().optional().describe("Target repository directory to inspect (defaults to active session directory or workspace root)"),
+			},
+			execute: async (args, toolContext) => {
+				const root = await resolveEffectiveWorkspace({ sessionID: toolContext.sessionID, directory: args?.directory, fallback: toolContext.worktree || toolContext.directory || effectiveRoot });
+				const branch = currentGitBranch(root) ?? "unknown"; const isProtected = onProtectedBranch(root); const lastV = getLastVerifyResultForWorkspace(root); const lastR = getLastReviewResultForWorkspace(root); const lastMut = getWorkspaceMutationTimestamp(root); const cfg = loadProjectConfig(root);
 				const subject = { workspace: projectRootKey(root), commitHash: getCurrentGitCommitHash(root), worktreeFingerprint: getGitWorktreeFingerprint(root) };
 				const verifyEvidence = lastV ? verificationEvidence(lastV) : undefined;
 				const reviewEvidenceRecord = lastR ? reviewEvidence(lastR) : undefined;
@@ -238,7 +251,12 @@ export function createCustomTools(options: {
 		guard_why: tool({ description: "Simulate and return the structured policy decision for a specific tool call or command. Proactively use before executing questionable or complex commands to check if they would be blocked by guard policies.", args: { tool: tool.schema.string().describe("Tool name (e.g. bash, edit, write, read, apply_patch)"), input: tool.schema.record(tool.schema.string(), tool.schema.any()).optional().describe("Tool input arguments") }, execute: async (args, toolContext) => JSON.stringify(await runWithRuntimeState(effectiveRoot, client, () => guardToolCallImpl(args.tool, args.input ?? {}, { sessionID: toolContext.sessionID, worktree: toolContext.worktree, directory: toolContext.directory, simulate: true })), null, 2) }),
 		record_review: tool({
 			description: "Record a secondary reviewer agent's approval or critique of the current changes. The summary must reference the 5 core review axes from guard_review_rubric (test integrity, task completeness, cleanliness, security, platform).",
-			args: { reviewer: tool.schema.string().describe("Identifier/name of the reviewer subagent"), summary: tool.schema.string().describe("Review findings summary across the 5 core review axes"), passed: tool.schema.boolean().describe("True if change is approved, false if changes requested") },
+			args: {
+				reviewer: tool.schema.string().describe("Identifier/name of the reviewer subagent"),
+				summary: tool.schema.string().describe("Review findings summary across the 5 core review axes"),
+				passed: tool.schema.boolean().describe("True if change is approved, false if changes requested"),
+				directory: tool.schema.string().optional().describe("Target repository directory being reviewed (defaults to parent session's repository or active directory)"),
+			},
 			execute: async (args, toolContext) => {
 				const auditVerdict = (verdict: "approved" | "changes_requested" | "rejected", reason: string) => audit({ ts: new Date().toISOString(), sessionID: toolContext.sessionID, tool: "record_review.verdict", decision: verdict === "rejected" ? "block" : "allow", phase: "event", reason, evidence: { reviewVerdict: verdict } });
 				const parentSessionID = await runWithRuntimeState(effectiveRoot, client, () => fetchParentSessionID(toolContext.sessionID));
@@ -247,8 +265,9 @@ export function createCustomTools(options: {
 				const referenced = axesRefs.filter((axis) => args.summary.toLowerCase().includes(axis));
 				if (referenced.length < 3) { auditVerdict("rejected", "insufficient_rubric_axes"); return `[workflow-guard] Review rejected: summary must reference the review axes (found ${referenced.length}/5). Call guard_review_rubric to get the rubric, evaluate each axis, and include findings per axis in the summary.`; }
 				if (args.passed && /(?:^|\s)(?:\[p[01]\]|p[01]\s*:\s*(?:blocker|defect|vulnerability|error|bug|issue)|p[01]\s+blocker)/i.test(args.summary)) { auditVerdict("rejected", "approval_contains_blocker"); return "[workflow-guard] Review rejected: cannot record approval when P0 or P1 blockers are flagged in findings. Resolve all P0/P1 issues before approving or record review with passed=false."; }
-				recordReviewResult(args.reviewer, args.summary, args.passed, parentSessionID, toolContext.worktree || toolContext.directory);
-				if (followupStore && !secretIn(args.summary)) for (const finding of extractReviewFollowups(args.summary)) recordReviewFollowup(followupStore, { severity: finding.severity, summary: finding.summary, reviewer: args.reviewer, sessionID: toolContext.sessionID, commit: getCurrentGitCommitHash(effectiveRoot) });
+				const reviewWorkspace = await resolveEffectiveWorkspace({ sessionID: toolContext.sessionID, directory: args.directory, fallback: toolContext.worktree || toolContext.directory || effectiveRoot });
+				recordReviewResult(args.reviewer, args.summary, args.passed, parentSessionID, reviewWorkspace);
+				if (followupStore && !secretIn(args.summary)) for (const finding of extractReviewFollowups(args.summary)) recordReviewFollowup(followupStore, { severity: finding.severity, summary: finding.summary, reviewer: args.reviewer, sessionID: toolContext.sessionID, commit: getCurrentGitCommitHash(reviewWorkspace) });
 				auditVerdict(args.passed ? "approved" : "changes_requested", args.passed ? "approved" : "changes_requested");
 				return args.passed ? `[workflow-guard] Review recorded as APPROVED by ${args.reviewer}.` : `[workflow-guard] Review recorded as CHANGES REQUESTED by ${args.reviewer}.`;
 			},
@@ -256,13 +275,18 @@ export function createCustomTools(options: {
 		guard_review_followups: tool({ description: "List durable local P2/P3 review follow-ups (technical debt) for this project. Proactively check during planning or before final verification to address open findings.", args: {}, execute: async () => JSON.stringify(followupStore ? listReviewFollowups(followupStore) : [], null, 2) }),
 		guard_review_followup_resolve: tool({ description: "Resolve a durable local review follow-up after the underlying issue has been fixed and verified.", args: { id: tool.schema.string() }, execute: async (args) => followupStore && resolveReviewFollowup(followupStore, args.id) ? `[workflow-guard] Review follow-up ${args.id} resolved.` : `[workflow-guard] Review follow-up ${args.id} was not open or was not found.` }),
 		guard_review_rubric: tool({
-			description: "Get the secondary-review rubric for the current branch diff across 5 core review axes (test integrity, task completeness, cleanliness, security, platform). The orchestrator should call this before finalizing work or creating a PR, then spawn a reviewer subagent with the rubric as the prompt, which records its verdict via record_review.", args: { base: tool.schema.string().optional().describe("Base ref to diff against (default: origin/main, origin/master, main)") },
-			execute: async (args) => {
+			description: "Get the secondary-review rubric for the current branch diff across 5 core review axes (test integrity, task completeness, cleanliness, security, platform). The orchestrator should call this before finalizing work or creating a PR, then spawn a reviewer subagent with the rubric as the prompt, which records its verdict via record_review.",
+			args: {
+				base: tool.schema.string().optional().describe("Base ref to diff against (default: origin/main, origin/master, main)"),
+				directory: tool.schema.string().optional().describe("Target repository directory (defaults to active session directory or workspace root)"),
+			},
+			execute: async (args, toolContext) => {
 				const sanitizedBase = typeof args.base === "string" && !args.base.startsWith("-") && !/[\s;'"\0]/.test(args.base) ? args.base : undefined;
 				const bases = sanitizedBase ? [sanitizedBase] : ["origin/main", "origin/master", "main", "master"];
+				const rubricWorkspace = await resolveEffectiveWorkspace({ sessionID: toolContext?.sessionID, directory: args?.directory, fallback: toolContext?.worktree || toolContext?.directory || effectiveRoot });
 				let diffText = "";
-				for (const base of bases) { const res = spawnSync("git", ["diff", "--", `${base}...HEAD`], { cwd: getWorkspaceRoot(), encoding: "utf8", timeout: 10_000 }); if (res.status === 0 && res.stdout.trim()) { diffText = res.stdout; break; } }
-				if (!diffText) { const last = spawnSync("git", ["diff", "--", "HEAD~1"], { cwd: getWorkspaceRoot(), encoding: "utf8", timeout: 10_000 }); diffText = last.status === 0 ? last.stdout : "(no diff available)"; }
+				for (const base of bases) { const res = spawnSync("git", ["diff", "--", `${base}...HEAD`], { cwd: rubricWorkspace, encoding: "utf8", timeout: 10_000 }); if (res.status === 0 && res.stdout.trim()) { diffText = res.stdout; break; } }
+				if (!diffText) { const last = spawnSync("git", ["diff", "--", "HEAD~1"], { cwd: rubricWorkspace, encoding: "utf8", timeout: 10_000 }); diffText = last.status === 0 ? last.stdout : "(no diff available)"; }
 				return buildReviewRubric(diffText);
 			},
 		}),

package/src/lib/evidence.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import type { ToolOutcome } from "./tool-outcomes.ts";
 import type { EvidenceRecord, EvidenceSubject, PolicyDecision, ReviewResult, VerifyResult } from "./types.ts";
+import { isSameGitRepo } from "./project-config.ts";
 
 function evidenceId(kind: EvidenceRecord["kind"], observedAt: number, subject: EvidenceRecord["subject"], source: Record<string, unknown>): string {
 	return createHash("sha256").update(JSON.stringify({ kind, observedAt, subject, source })).digest("hex");
@@ -40,7 +41,11 @@ export function agentAssertionEvidence(assertion: string, observedAt: number, su
 }
 
 export function evidenceMatchesSubject(evidence: EvidenceRecord, subject: EvidenceSubject): boolean {
-	return evidence.subject.workspace === subject.workspace &&
+	const workspaceMatches =
+		evidence.subject.workspace === subject.workspace ||
+		(Boolean(evidence.subject.workspace && subject.workspace) &&
+			isSameGitRepo(evidence.subject.workspace, subject.workspace));
+	return workspaceMatches &&
 		evidence.subject.commitHash === subject.commitHash &&
 		evidence.subject.worktreeFingerprint === subject.worktreeFingerprint &&
 		evidence.subject.sessionID === subject.sessionID;

package/src/lib/guard-dispatcher.ts

@@ -1,8 +1,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { loadVerifyCache } from "./audit.ts";
+import { loadReviewCache, loadVerifyCache } from "./audit.ts";
 import { isEvidenceFresh, reviewEvidence, verificationEvidence } from "./evidence.ts";
-import { projectRootKey } from "./project-config.ts";
+import { findGitRoot, isSameGitRepo, projectRootKey } from "./project-config.ts";
 import {
 	getLastReviewResult,
 	getSdkClient,
@@ -34,6 +34,7 @@ import {
 	getGitStatusSummary,
 	getGitWorktreeFingerprint,
 	runVerify,
+	resolveVerifyTimeoutMs,
 	snipVerifyOutput,
 } from "./verify.ts";
 import { detectShellMutation, extractPatchPaths, guardShellMutation, isPathOutsideWorkspace } from "../policies/boundary.ts";
@@ -55,6 +56,7 @@ import {
 	onProtectedBranch,
 	parseGitInvocation,
 	pushedProtectedBranchIn,
+	tagRefspecIn,
 } from "../policies/git.ts";
 import { extractInterpreterPayload, outsideWritePathInPayload, secretPathInPayload, writePathsInPayload } from "../policies/interpreter.ts";
 import { mcpMutationTool } from "../policies/mcp.ts";
@@ -180,7 +182,7 @@ export async function guardToolCallImpl(
 					const isFresh = verifyResult !== undefined && verifyResult.passed && verifyResult.command === command && isEvidenceFresh(verificationEvidence(verifyResult, sessionID), currentSubject, mutationTimestamp);
 					if (!isFresh) {
 						if (context?.simulate) return block("verification", "verification_required", `Blocked: finalization requires fresh passing verification (${command}).`);
-						const result = await runVerify(command, currentRoot);
+						const result = await runVerify(command, currentRoot, resolveVerifyTimeoutMs(currentRoot));
 						recordVerifyResult(command, result, sessionID, currentRoot);
 						if (!result.passed) {
 							const tail = snipVerifyOutput(result.output, result.passed).slice(-500);
@@ -248,7 +250,6 @@ export async function guardToolCallImpl(
 				}
 			}
 		}
-		for (const content of extractEditContent(input)) if (isSettingsTamper(content)) return block("tamper", "settings_tamper", PROTECTED_PATH_REASON);
 		if (onProtectedBranch(currentRoot)) {
 			logPolicyBlock(`[workflow-guard] blocked ${toolName}: on protected branch ${currentGitBranch(currentRoot)}`);
 			return block("git", "protected_branch", branchGuardReason());
@@ -329,6 +330,7 @@ export async function guardToolCallImpl(
 			}
 		}
 		for (const invocation of gitInvocations) {
+			if (tagRefspecIn(`git ${invocation.rest}`, invocation.repoDir)) continue;
 			if (GIT_WRITE_RE.test(`git ${invocation.rest}`) && onProtectedBranch(invocation.repoDir)) {
 				logPolicyBlock(`[workflow-guard] blocked git write on protected branch: ${command.slice(0, 120)}`);
 				return block("git", "protected_branch", branchGuardReason());
@@ -397,6 +399,7 @@ export async function guardToolCallImpl(
 		for (const invocation of gitInvocations) {
 			const pushText = `git ${invocation.rest}`;
 			if (!/\bgit\s+push\b/.test(pushText)) continue;
+			if (tagRefspecIn(pushText, invocation.repoDir)) continue;
 			const pushedBranch = pushedProtectedBranchIn(pushText, invocation.repoDir);
 			if (pushedBranch) {
 				logPolicyBlock(`[workflow-guard] blocked push to protected branch '${pushedBranch}': ${command}`);
@@ -405,6 +408,7 @@ export async function guardToolCallImpl(
 		}
 		for (const invocation of gitInvocations) {
 			if (!/\bgit\s+push\b/.test(`git ${invocation.rest}`)) continue;
+			if (tagRefspecIn(`git ${invocation.rest}`, invocation.repoDir)) continue;
 			if (onProtectedBranch(invocation.repoDir)) {
 				logPolicyBlock(`[workflow-guard] blocked push from protected branch: ${command}`);
 				return block("git", "protected_branch", branchGuardReason());
@@ -435,7 +439,13 @@ export async function guardToolCallImpl(
 				if (mergedStatus.merged) preflightFailures.push(mergedStatus.reason ?? "Branch is already merged or closed.");
 			}
 			if (isReviewRequired(prRoot)) {
-				const review = context?.sessionID ? (sessionReviews.get(context.sessionID) ?? getLastReviewResult()) : getLastReviewResult();
+				let review = context?.sessionID ? (sessionReviews.get(context.sessionID) ?? getLastReviewResult()) : getLastReviewResult();
+				if (!review) {
+					const diskCached = loadReviewCache();
+					if (diskCached && diskCached.passed && diskCached.workspace && (projectRootKey(diskCached.workspace) === projectRootKey(prRoot) || isSameGitRepo(diskCached.workspace, prRoot))) {
+						review = diskCached;
+					}
+				}
 				const reviewMatchesContext = review?.passed === true && isEvidenceFresh(reviewEvidence(review), { workspace: projectRootKey(prRoot), commitHash: getCurrentGitCommitHash(prRoot), worktreeFingerprint: getGitWorktreeFingerprint(prRoot), sessionID: review.targetSessionID }, 0) && (!review.targetSessionID || review.targetSessionID === context?.sessionID);
 				if (!reviewMatchesContext) preflightFailures.push("Passing secondary review approval is required; invoke a secondary review subagent and record approval with record_review.");
 			}

package/src/lib/project-config.ts

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync, realpathSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { spawnSync } from "node:child_process";
 import type { ProjectConfig } from "./types.ts";
 
 const projectConfigCache = new Map<string, ProjectConfig>();
@@ -12,6 +13,55 @@ export function projectRootKey(root: string): string {
 	}
 }
 
+export function findGitRoot(startPath?: string): string | undefined {
+	if (!startPath || typeof startPath !== "string") return undefined;
+	try {
+		const resolved = resolve(startPath);
+		let dir = resolved;
+		try {
+			const stat = statSync(resolved);
+			dir = stat.isDirectory() ? resolved : dirname(resolved);
+		} catch {
+			dir = dirname(resolved);
+		}
+		const res = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (res.status === 0 && res.stdout.trim()) {
+			return projectRootKey(res.stdout.trim());
+		}
+	} catch {}
+	return undefined;
+}
+
+export function getGitCommonDir(root: string): string | undefined {
+	try {
+		const res = spawnSync("git", ["-C", root, "rev-parse", "--path-format=absolute", "--git-common-dir"], {
+			encoding: "utf8",
+			timeout: 5_000,
+		});
+		if (res.status === 0 && res.stdout.trim()) {
+			return projectRootKey(res.stdout.trim());
+		}
+	} catch {}
+	return undefined;
+}
+
+export function isSameGitRepo(pathA?: string, pathB?: string): boolean {
+	if (!pathA || !pathB) return false;
+	const keyA = projectRootKey(pathA);
+	const keyB = projectRootKey(pathB);
+	if (keyA === keyB) return true;
+	const commonA = getGitCommonDir(keyA);
+	const commonB = getGitCommonDir(keyB);
+	if (commonA && commonB && commonA === commonB) return true;
+	const rootA = findGitRoot(keyA);
+	const rootB = findGitRoot(keyB);
+	if (rootA && rootB && rootA === rootB) return true;
+	return false;
+}
+
 export function projectConfigCandidates(root: string): string[] {
 	return [
 		join(root, ".opencode", "workflow-guard.json"),

package/src/lib/state.ts

@@ -1,8 +1,8 @@
-import { realpathSync } from "node:fs";
+import { realpathSync, existsSync, unlinkSync } from "node:fs";
 import { resolve } from "node:path";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { persistVerifyCache, persistVerifyHistory } from "./audit.ts";
-import { getCachedProjectConfig, loadProjectConfig, projectRootKey } from "./project-config.ts";
+import { getReviewCacheFilePath, loadReviewCache, persistReviewCache, persistVerifyCache, persistVerifyHistory } from "./audit.ts";
+import { findGitRoot, getCachedProjectConfig, isSameGitRepo, loadProjectConfig, projectRootKey } from "./project-config.ts";
 import { snipVerifyOutput, getCurrentGitCommitHash, getGitStatusSummary, getGitWorktreeFingerprint } from "./verify.ts";
 import type {
 	TodoSdkClient,
@@ -74,6 +74,18 @@ const workspaceMutationTimestamps = new Map<string, number>();
 const workspaceMutationCounts = new Map<string, number>();
 export const sessionMutationTimestamps = new Map<string, number>();
 export const sessionMutationCounts = new Map<string, number>();
+export const sessionWorkspaces = new Map<string, string>();
+
+export function setSessionWorkspace(sessionID: string, workspace: string): void {
+	if (!sessionID || !workspace) return;
+	const gitRoot = findGitRoot(workspace);
+	sessionWorkspaces.set(sessionID, gitRoot ?? projectRootKey(workspace));
+}
+
+export function getSessionWorkspace(sessionID?: string): string | undefined {
+	if (!sessionID) return undefined;
+	return sessionWorkspaces.get(sessionID);
+}
 
 export let lastVerify: VerifyResult | undefined;
 export const sessionVerifyResults = new Map<string, NonNullable<VerifyResult>>();
@@ -95,6 +107,10 @@ export function recordMutation(sessionID?: string, actorSessionID?: string): voi
 	}
 	if (!lastReview?.targetSessionID || lastReview.targetSessionID === sessionID || lastReview.targetSessionID === actorSessionID) {
 		lastReview = undefined;
+		try {
+			const p = getReviewCacheFilePath();
+			if (existsSync(p)) unlinkSync(p);
+		} catch {}
 	}
 }
 
@@ -192,23 +208,95 @@ export function recordReviewResult(
 		worktreeFingerprint: getGitWorktreeFingerprint(root),
 	};
 	if (targetSessionID) sessionReviews.set(targetSessionID, lastReview);
+	if (passed) {
+		persistReviewCache(lastReview);
+	}
 }
 
 export function getLastReviewResult(): typeof lastReview {
-	return lastReview;
+	if (lastReview) return lastReview;
+	const diskCached = loadReviewCache();
+	if (diskCached) {
+		lastReview = diskCached;
+		return lastReview;
+	}
+	return undefined;
 }
 
 export function getLastReviewResultForWorkspace(root: string): typeof lastReview {
 	const workspace = projectRootKey(root);
 	const candidates = [lastReview, ...sessionReviews.values()].filter(
-		(result): result is ReviewResult => result?.workspace != null && projectRootKey(result.workspace) === workspace,
+		(result): result is ReviewResult => result?.workspace != null && (projectRootKey(result.workspace) === workspace || isSameGitRepo(result.workspace, root)),
 	);
-	return candidates.reduce<ReviewResult | undefined>((latest, result) => !latest || result.timestamp > latest.timestamp ? result : latest, undefined);
+	const latest = candidates.reduce<ReviewResult | undefined>((best, result) => !best || result.timestamp > best.timestamp ? result : best, undefined);
+	if (latest) return latest;
+	const diskCached = loadReviewCache();
+	if (diskCached?.workspace && (projectRootKey(diskCached.workspace) === workspace || isSameGitRepo(diskCached.workspace, root))) {
+		return diskCached;
+	}
+	return undefined;
 }
 
 export function resetReviewState(): void {
 	lastReview = undefined;
 	sessionReviews.clear();
+	try {
+		const p = getReviewCacheFilePath();
+		if (existsSync(p)) unlinkSync(p);
+	} catch {}
+}
+
+export async function resolveEffectiveWorkspace(options: {
+	sessionID?: string;
+	directory?: string;
+	fallback?: string;
+}): Promise<string> {
+	if (options.directory) {
+		const gitRoot = findGitRoot(options.directory);
+		return gitRoot ?? projectRootKey(options.directory);
+	}
+	const fallbackRoot = options.fallback ? projectRootKey(options.fallback) : undefined;
+	const isFallbackFsRoot = fallbackRoot ? resolve(fallbackRoot) === resolve(fallbackRoot, "..") : true;
+
+	if (fallbackRoot && !isFallbackFsRoot) {
+		if (options.sessionID) {
+			const sessionWs = sessionWorkspaces.get(options.sessionID);
+			if (sessionWs && isSameGitRepo(sessionWs, fallbackRoot)) {
+				return sessionWs;
+			}
+		}
+		return fallbackRoot;
+	}
+
+	if (options.sessionID) {
+		const sessionWs = sessionWorkspaces.get(options.sessionID);
+		if (sessionWs) return sessionWs;
+		try {
+			const client = getSdkClient();
+			const session = client?.session;
+			const get = session?.get;
+			if (typeof get === "function") {
+				const result = await get.call(session, { path: { id: options.sessionID } });
+				const parent = (result as { data?: { parentID?: unknown } } | undefined)?.data?.parentID;
+				if (typeof parent === "string" && parent && sessionWorkspaces.has(parent)) {
+					const parentWs = sessionWorkspaces.get(parent)!;
+					sessionWorkspaces.set(options.sessionID, parentWs);
+					return parentWs;
+				}
+			}
+		} catch {}
+	}
+	const activeRoot = getWorkspaceRoot();
+	if (activeRoot && resolve(activeRoot) !== resolve(activeRoot, "..")) {
+		const gitRoot = findGitRoot(activeRoot);
+		if (gitRoot) return gitRoot;
+		return activeRoot;
+	}
+	try {
+		const cwdGitRoot = findGitRoot(process.cwd());
+		if (cwdGitRoot) return cwdGitRoot;
+	} catch {}
+	return fallbackRoot || activeRoot || getWorkspaceRoot();
 }
 
 export function getProjectConfig(root: string): ProjectConfig {

package/src/lib/types.ts

@@ -27,6 +27,7 @@ export interface ProjectConfig {
 	profile?: "interactive" | "autonomous";
 	protectedBranches?: string[];
 	verifyCommand?: string;
+	verifyTimeoutMs?: number;
 	postEditValidators?: Array<{
 		pattern: string;
 		command: string;