opencode-workflow-guard 1.14.1 → 1.15.0

package/docs/agents/lessons.md

@@ -7,3 +7,6 @@ Append-only, evidence-backed lessons from base-loop iterations. Each item: id, e
 - **LL-003 — A freshness gate that only learns from reads makes agents re-read their own writes; seed observations from successful mutations, gated on actual change.** Evidence: the stale-write gate (`src/policies/stale-write.ts`) recorded per-session fingerprints only from successful `read`, so a follow-up `edit` to a file the session had just created or written was blocked with "has not been read by this session" — the top guard block on this device (64 of the audit's `stale_write` decisions, including agent-authored temp scripts such as `order-processing/.tmp-rsi-iter7/step1-transform.js`). The fix adds `recordMutationObservation(path, sessionID, beforeDigest)` called from the V1/V2 after-hooks over the existing post-edit snapshots; it seeds only when the pre/post digest differs, so no-op/failed calls seed nothing and external changes after the mutation still block (tests: write-then-edit allowed, edit-chained allowed, external change blocked, no-op `apply_patch` does not seed a later edit). Lesson: when a concurrency/freshness gate is keyed on prior observation, treat the session's own successful mutation as an observation of the resulting bytes (gated on the bytes actually changing), or it will generate pure-friction re-read loops.
 - **LL-004 — A token detector must distinguish command position from argument position; argument-position matches generate false positives that eventually block the guard's own tooling.** Evidence: `checkProcessMonitorCommand` (`src/policies/shell-safety.ts`) matched the monitor word anywhere as a whitespace-delimited token, so an Azure key-vault secret lookup whose `--name` value was that literal word was blocked as an "interactive process monitor" (device audit, `interactive_tty`), and during this loop the stale installed detector blocked a verification command and a commit whose text merely contained the word — proving the defect against real tooling. The fix flags only the executable of a quote-aware segment after wrapper unwrapping (`sudo`/`env`/`timeout`/…), handles `busybox <cmd>`, mirrors the pager recursion for `eval`/`sh -c`, scopes the batch-mode exemption to the monitor's own flags, and documents residual indirection (`watch`/`xargs`/`man`, `find -exec`/`su -c`, shell loop bodies) plus the pre-existing decode-escape quirk. Lesson: when a detector classifies a token as a command, verify it is in command position (executable after wrappers), and test both the false-positive argument case and the detection cases it replaced.
 - **LL-005 — Lifecycle tools must handle the partially-gone state idempotently, not just the happy path.** Evidence: `cleanupGitWorktree` (`src/lib/worktree.ts`) returned "Worktree path '...' does not exist." for a registered worktree whose directory was missing, so the prunable admin entries that `git worktree list` shows after a manual removal, a crashed add, or external cleanup could not be cleared through the tool. The fix validates ownership first and, for a missing registered path, deregisters the stale entry with `git worktree prune` (exit status reported via `describeGitFailure`) and returns success; outside-storage, unregistered, and primary-tree cases stay refused and no raw deletion is used. Tests assert the prunable state exists before cleanup, that cleanup succeeds and deregisters, and that an unregistered missing path is still refused. Lesson: a create/cleanup pair should treat "the artifact's directory/state is partly gone" as a first-class cleanup case (deregister what exists, refuse what is outside the owned scope), or agents accumulate stale metadata they cannot clear.
+- **LL-006 — Close a reviewer-flagged design trade-off with a narrowly scoped opt-in gate on the exact trust boundary, not by reworking the default path.** Evidence: the review-binding redesign deliberately let any session record a verdict (read-only reviewer toolsets cannot call `record_review`), which the loop-3 review flagged as mechanical root-session self-approval (P2: "recommend an optional strictness knob requiring a subagent recorder"). The fix adds `requireSubagentReview` (project config plus `WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW` env override, default off): in strict mode `record_review` rejects APPROVALS recorded by a session with no parent (audit reason `subagent_recorder_required`) while changes-requested verdicts stay relayable, so the relay flow that motivated the original trade-off keeps working, and `guard_status` echoes the effective requirement. Tests cover root-approval rejection with audit + gate unsatisfied + PR preflight still blocked, root changes-requested relay, subagent-recorder acceptance end-to-end through PR preflight, env on/off overrides, and the default relay flow. Lesson: when a reviewer flags an accepted trade-off as a risk, prefer an opt-in knob that tightens WHO is trusted for the risky action only (approve ≠ speak), rather than weakening or redesigning the default that other documented flows depend on.
+- **LL-007 — When a lock's validity depends on its owner still being active, derive staleness from an authoritative lifecycle record re-checked at decision time, not from a TTL or a pre-await snapshot.** Evidence: a direct-edit file claim (`src/policies/file-claims.ts`) survived its owner's own recorded idle timestamp on-device (2026-09-22: session `ses_f39203782ffeTHMdcufoS6lfH2` idled at 05:38Z per the server record while holding a claim on `test/test.mts`) and blocked every other session's edits to that path until the owner was deleted via the server API — claims have no expiry, and only the owning after-hook or the owner's `session.idle`/`session.deleted` events release them, and the idle event demonstrably did not arrive. A wall-clock TTL was rejected: it would starve legitimate long calls and leave recent dead-owner claims lingering. The takeover instead uses a server-verifiable signal — a claim created before the owner's last recorded `time.idle` cannot belong to an in-flight tool call (that call finished before the turn ended), so it is provably stale — via the same SDK `session.get` the guard already uses for lineage; missing or failing lookups fail closed, and every claim is re-read after the round-trip so a mid-turn refresh (which also fixed a latent stale-callID release miss) keeps living. Lesson: derive "the owner is gone" from an authoritative record of the owner's lifecycle, re-checked after every await, or the guard trades a permanent deadlock for a guess.
+- **LL-008 — A package that can be resolved from several install surfaces must publish the version that is actually running, and the docs must name the surface that wins.** Evidence: the user updated opencode-workflow-guard via `npm i -g` twice (1.14.0, then 1.14.1) and restarted, yet the OpenCode server log kept showing `loading plugin ... entrypoint=file:///var/home/hunter/node_modules/.pnpm/opencode-workflow-guard@1.13.5/...` — a pnpm-managed home-level dependency (`"opencode-workflow-guard": "^1.13.5"` in `~/package.json`) shadowing the global npm copy through Node's parent-directory resolution from `~/.config/opencode`, while OpenCode's own plugin-update check failed with only a server-log `NpmInstallFailedError`. Two releases of "updates" never reached the running enforcement layer, and the empty rubric diff (LL-001's bug) persisted until the home dependency was updated with `pnpm add`; a TUI-only restart also did not reload the background service. The fix adds `loadedPluginVersion()` (`src/lib/version.ts`, read from the adjacent package.json, fail-soft), surfaced as `guard_status`'s `pluginVersion` and in the startup app log, plus installation/troubleshooting documentation of the shadowing behavior, the verification path, and `opencode service restart` as the reload step. Lesson: when "updated" and "running" can silently diverge across install surfaces, the running module must publish its own version — or every resolution mismatch gets misdiagnosed as something else.

package/docs/installation.md

@@ -40,6 +40,8 @@ If you only want the server guard without the TUI companion, add the package to
 
 OpenCode automatically installs configured npm plugins and their dependencies at startup. The npm package contains both server and TUI entrypoints, but OpenCode activates them from separate configuration files. See [OpenCode's npm plugin documentation](https://opencode.ai/docs/plugins/#from-npm) and [plugin installation behavior](https://opencode.ai/docs/plugins/#how-plugins-are-installed).
 
+A configured bare package name is resolved through Node's parent-directory lookup from OpenCode's configuration location: any `node_modules` above that location that contains a copy of the package (a pnpm-managed home directory, a manual `npm install`, or a workspace dependency) is loaded instead, shadowing both OpenCode's own plugin cache and a global `npm install -g` — updating the wrong copy leaves an old version running while the update appears to succeed, and OpenCode's own plugin-update check can fail with only a server-log record (`NpmInstallFailedError`). Update the copy that actually loads (for a pnpm-managed home directory: `pnpm add opencode-workflow-guard@<version>` in that directory, or remove the dependency so OpenCode manages its own copy), then restart the background service (`opencode service restart`) — the plugin loads there, so a TUI-only restart is not enough. Verify what loaded: `guard_status` reports the loaded version as `pluginVersion`, the startup app log states `Workflow Guard v<version> plugin initialized`, and the server log records the resolved module path in its `loading plugin` entry.
+
 ---
 
 ### 2. Manual Local-File Installation (Server Plugin)
@@ -139,6 +141,8 @@ To opt out of the PR secondary review gate for a project, set `requireReview: fa
 
 Or set `WORKFLOW_GUARD_REQUIRE_REVIEW=0` in your environment. Conversely, `WORKFLOW_GUARD_REQUIRE_REVIEW=1` enforces the review gate regardless of repository configuration.
 
+For stricter environments, set `requireSubagentReview: true` in `.opencode/workflow-guard.json` to reject approvals recorded by the root session itself: a passing verdict must then be recorded from a subagent session (one with a parent session), never by the root session approving its own work. Changes-requested findings remain relayable from any session. `WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=1` enables the same requirement for any project; `WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=0` disables it even when project config enables it.
+
 ---
 
 ## Recommended Companion Configuration

package/docs/policies.md

@@ -17,7 +17,7 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 - **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.
 - **Subagent Mutation Budget:** Subagent sessions are protected by a mutation safety budget (`maxSubagentMutations` in project config or `WORKFLOW_GUARD_MAX_SUBAGENT_MUTATIONS` env, default 100) to terminate runaway edit loops deterministically.
-- **Concurrent File Claims:** Direct `edit`, `write`, and `apply_patch` calls claim each canonical target for the tool-call lifetime. A different active session is blocked from racing the same file (including through symlink aliases); claims are released after the call, with session idle/deletion as stale-claim cleanup when an after hook is missed. Shell writers are not covered, and isolated worktrees remain preferred for substantial parallel mutations.
+- **Concurrent File Claims:** Direct `edit`, `write`, and `apply_patch` calls claim each canonical target for the tool-call lifetime. A different active session is blocked from racing the same file (including through symlink aliases); claims are released after the call, with session idle/deletion as stale-claim cleanup when an after hook is missed. A claim created before its owner's last recorded idle timestamp cannot belong to an in-flight tool call, so when another session hits such a conflict the stale claim is released with an audited `stale_claim_takeover` entry — owners still mid-session (no idle timestamp), clients without a session lookup, and failed lookups keep the block (fail-closed). `guard_why` stays read-only and still reports the conflict as blocked. Shell writers are not covered, and isolated worktrees remain preferred for substantial parallel mutations.
 - **Stale-Write Protection:** A successful `read` records a same-session fingerprint for an existing regular file using its canonical path, filesystem identity, size, nanosecond mtime, and SHA-256 content digest; a successful `edit`/`write` also records the resulting bytes (only when the file actually changed), since the session authored them, so iterating on a just-created or just-modified file needs no redundant re-read. Before `edit` or `write` replaces an existing file, that fingerprint must exist and still match; otherwise the call is blocked and must re-read. New-file creation is allowed without a prior read. Fingerprints are not inherited between parent/subagent sessions and are cleared on session idle/deletion. `apply_patch` and shell writers are deliberately outside this bounded mechanism (an `apply_patch` result still seeds the session observation, but its clobbering itself is not pre-checked); the pre-execution comparison also cannot make external changes between the check and OpenCode's write atomic.
 
 ### 2. No Pushes to Protected Branches
@@ -73,6 +73,8 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 
 ### 8. Workspace Boundary Guard
 - File modification tools (`edit`, `write`, `apply_patch`) and recognized shell mutations (redirection `>`, `>>`, `&>`, `>&`, `tee`, `sed -i`, `cp`/`mv`/`ln`, `touch`, `mkdir`, `rm`, `truncate`, `dd of=`, `git apply`/`git am`) are validated to ensure detected targets cannot escape the current workspace root via `../` traversal, symlinks, absolute paths, or shell expansions (`~`, `~user`, `$HOME`). Unresolvable `$VARIABLE` references fail closed. This is command-level enforcement, not filesystem sandboxing; arbitrary programs and dynamically computed paths require the OS isolation described under Known Limits.
+- **Unresolvable variable cause attribution:** a target containing an unresolvable `$VARIABLE` reference (for example `mkdir -p $D/sub` or `> $CACHE/out.txt`) is indeterminate without executing shell semantics, so it is treated as outside the workspace — and the block message says so ("contains an unresolvable variable reference … use a literal workspace-relative path") instead of the generic escape message. Deterministically expandable forms (`~`, `~user`, `$HOME`, `${HOME}`) keep the generic message; cache-path and other literal destinations inside the workspace are unaffected.
+- **Scratch-directory cause attribution:** `/tmp/opencode` is the environment's designated agent scratch space, but the workspace boundary is workspace-absolute and does not cover it — writes there stay blocked. The block message names the directory and points to the remedy (an untracked scratch file inside the workspace, for example `.tmp-notes.md`) instead of reading as a guard bug; the enforcement decision is unchanged.
 - `tee` flag parsing generically skips option flags (`-a`, `--append`, `-ai`, `--`) and validates all specified target files against the boundary.
 - Embedded non-shell comparisons are not mutations: a bare `>` whose target is purely numeric (`WHERE count > 5`, awk `$3 > 100`) and `>=`/`==` operators are treated as comparison operands, not redirects. Real redirects are unaffected (`> src/a.ts`, `>>`, `&>`, `>&`, fd targets like `/dev/null` still follow their existing rules).
 - `mv` sources are validated too: moving a file from outside the workspace (or a protected settings/plugin file to an innocuous name) is blocked, since `mv` mutates the source.
@@ -196,10 +198,11 @@ Besides enforcement hooks, the guard registers companion tools in OpenCode:
 - All spawned git commands run with a sanitized environment: inherited git context variables (`GIT_INDEX_FILE`, `GIT_DIR`, `GIT_WORK_TREE`, ...) are stripped so the tools resolve the repository from their working directory alone. This makes them safe to invoke from inside git hooks, which export those variables.
 
 ### Inspection Tools
-- `guard_status`, `guard_audit`, `guard_why`, `guard_review_rubric`, `record_review`, `guard_review_followups`, and `guard_review_followup_resolve` provide runtime introspection of guardrail state, audit entries, block explanations, reviewer rubric definitions, reviewer decisions, and durable local review debt. `guard_status` also exposes the effective Ralph opt-in, iteration budget, and calling-session outcome when applicable.
+- `guard_status`, `guard_audit`, `guard_why`, `guard_review_rubric`, `record_review`, `guard_review_followups`, and `guard_review_followup_resolve` provide runtime introspection of guardrail state, audit entries, block explanations, reviewer rubric definitions, reviewer decisions, and durable local review debt. `guard_status` also exposes the effective Ralph opt-in, iteration budget, and calling-session outcome when applicable, a read-only `gitHygiene` snapshot (local branches already merged into the mainline, prunable worktree admin entries, and the current branch's base-behind distance — hygiene itself stays manual: the guard reports, it never prunes or deletes branches), and `pluginVersion`, the version of the loaded guard package, so a stale installation is visible.
 - **Priority-Ranked Review Gate:** Secondary review approval (`requireReview`) is enforced by default during PR preflight (`gh pr create` / `az repos pr create`). Before creating a pull request, a secondary reviewer subagent must evaluate the changes using `guard_review_rubric` and record approval with `record_review`. Approvals that include active P0 (blocker) or P1 (major defect) issues are rejected until blockers are resolved. Projects can opt out via `.opencode/workflow-guard.json` (`{ "requireReview": false }`) or environment variable `WORKFLOW_GUARD_REQUIRE_REVIEW=0`. Conversely, `WORKFLOW_GUARD_REQUIRE_REVIEW=1` forces the review requirement regardless of project config.
 - **Review binding is content, not session identity:** a recorded approval satisfies the PR preflight when its binding (same repository, same commit hash, same tracked-content worktree fingerprint) matches the tree the PR would publish - regardless of which session records the verdict or creates the PR. Reviewers record from subagent sessions (binding the verdict to their parent or their own directory) and sessions can move between directories (`session_move`) or spawn subagents from other roots, so keying the gate on the PR-creating session's ID made the documented flow impossible to satisfy from linked worktrees. Freshness is scoped to the reviewed diff (tracked content): untracked scratch-file cleanup and mutations in sibling worktrees cannot invalidate an approval, while any tracked edit or new commit does.
 - **`record_review` accepts any recorder session:** reviewer agents configured with a read-only toolset (e.g. glob/grep/read/webfetch only) cannot call `record_review` themselves, so the tool no longer rejects root/orchestrator sessions; the verdict binds to the recording session's resolved directory, the tool result echoes that binding, and the audit entry (`record_review.verdict`) records the binding key and recorder lineage (`recorderRole: root | subagent`). Prefer relaying through an independent secondary reviewer subagent; the tool result reminds the recorder when it runs from a root session. A verdict recorded against a directory without a computable tracked fingerprint (not a git repository) is rejected loudly and never recorded.
+- **`requireSubagentReview` strict recorder mode (opt-in):** projects that cannot tolerate root-session self-approval can set `requireSubagentReview: true` in `.opencode/workflow-guard.json`, or `WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=1` in the environment. In that mode `record_review` rejects APPROVALS recorded by the root session itself (a session with no parent) with an actionable message and a `subagent_recorder_required` audit entry; the verdict is not recorded and the review gate stays unsatisfied. Changes-requested verdicts remain relayable from any session, and `WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=0` disables the requirement even when project config enables it. The default keeps the documented relay flow for read-only reviewer toolsets.
 - **Durable Lower-Priority Follow-ups:** Accepted review summaries containing a P2 or P3 finding are persisted in the project's local Workflow Guard SQLite database. Open findings are included in compacted agent context and remain open across sessions until explicitly resolved with `guard_review_followup_resolve`; they are not silently discarded with the review session.
 - **Privacy-Safe Local Telemetry:** Guard decisions remain in the local audit JSONL. Tool after-hook observations add `callID` and duration records for local diagnosis and performance analysis; the current hook API does not distinguish success from every failure path, so these records do not claim a success outcome. Command and patch bodies are never written to the journal; only their byte count and SHA-256 fingerprint are retained for correlation.
 

package/docs/troubleshooting.md

@@ -109,4 +109,9 @@ After the command reports `Detected server + tui targets`, confirm it reports re
 - **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.

package/package.json

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

package/src/lib/custom-tools.ts

@@ -27,6 +27,7 @@ import {
 	isRecoveryCheckpointsEnabled,
 	isRalphModeEnabled,
 	isReviewRequired,
+	isSubagentReviewRequired,
 	recordMutation,
 	recordReviewResult,
 	resolveEffectiveWorkspace,
@@ -41,6 +42,8 @@ import { branchHasDocumentationChange } from "../policies/docs.ts";
 import { restoreRecoveryCheckpoint } from "./checkpoint.ts";
 import { audit, getRecentAuditEntries } from "./audit.ts";
 import { guardToolCallImpl } from "./guard-dispatcher.ts";
+import { loadedPluginVersion } from "./version.ts";
+import { gitHygieneSnapshot } from "./hygiene.ts";
 import { discoverPlanningSources } from "../policies/planning.ts";
 import { secretIn } from "../policies/secrets.ts";
 import { currentGitBranch, onProtectedBranch } from "../policies/git.ts";
@@ -205,7 +208,7 @@ 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.",
+			description: "Inspect active guardrails, current branch protection, mutation count, outstanding verification/review requirements, and ralph status. The result includes pluginVersion, the version of the loaded guard package, so a stale installation is visible, and a read-only gitHygiene snapshot (local branches already merged into the mainline, prunable worktree admin entries, base-behind distance). 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)"),
 			},
@@ -249,13 +252,13 @@ export function createCustomTools(options: {
 					recommendedActions.push("All operational requirements are satisfied for task finalization and PR creation.");
 				}
 				const ralphOutcome = runWithRuntimeState(root, client, () => getRalphOutcome(toolContext.sessionID));
-				return JSON.stringify({ workspaceRoot: root, branch, onProtectedBranch: isProtected, outstandingRequirements, recommendedActions, lastMutationTimestamp: lastMut, mutationCount: getWorkspaceMutationCount(root), lastVerify: lastV && verifyEvidence ? { command: lastV.command, passed: lastV.passed, fresh: verifyFresh, evidenceId: verifyEvidence.id, commitHash: lastV.commitHash } : null, lastReview: lastR && reviewEvidenceRecord ? { reviewer: lastR.reviewer, passed: lastR.passed, summary: lastR.summary, fresh: reviewFresh, evidenceId: reviewEvidenceRecord.id } : null, ralph: { enabled: isRalphModeEnabled(root), maxIterations: getRalphMaxIterations(root), outcome: ralphOutcome ?? null }, projectConfig: { profile: getOperationProfile(root), protectedBranches: cfg.protectedBranches ?? ["main", "master"], verifyCommand: verifyCommand ?? null, requireReview: reviewRequired, requireDocumentation: documentationRequired, recoveryCheckpoints: isRecoveryCheckpointsEnabled(root) } }, null, 2);
+				return JSON.stringify({ pluginVersion: loadedPluginVersion() ?? null, workspaceRoot: root, branch, onProtectedBranch: isProtected, outstandingRequirements, recommendedActions, lastMutationTimestamp: lastMut, mutationCount: getWorkspaceMutationCount(root), lastVerify: lastV && verifyEvidence ? { command: lastV.command, passed: lastV.passed, fresh: verifyFresh, evidenceId: verifyEvidence.id, commitHash: lastV.commitHash } : null, lastReview: lastR && reviewEvidenceRecord ? { reviewer: lastR.reviewer, passed: lastR.passed, summary: lastR.summary, fresh: reviewFresh, evidenceId: reviewEvidenceRecord.id } : null, ralph: { enabled: isRalphModeEnabled(root), maxIterations: getRalphMaxIterations(root), outcome: ralphOutcome ?? null }, projectConfig: { profile: getOperationProfile(root), protectedBranches: cfg.protectedBranches ?? ["main", "master"], verifyCommand: verifyCommand ?? null, requireReview: reviewRequired, requireDocumentation: documentationRequired, requireSubagentReview: isSubagentReviewRequired(root), recoveryCheckpoints: isRecoveryCheckpointsEnabled(root) }, gitHygiene: gitHygieneSnapshot(root) ?? null }, null, 2);
 			},
 		}),
 		guard_audit: tool({ description: "View recent audit entries recorded by opencode-workflow-guard. Use to diagnose policy decisions, blocked commands, or outcome telemetry.", args: { limit: tool.schema.number().optional().describe("Maximum entries to return (default 10)") }, execute: async (args) => JSON.stringify(getRecentAuditEntries(typeof args?.limit === "number" ? Math.min(args.limit, 50) : 10), null, 2) }),
 		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).",
+			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). Projects with requireSubagentReview enabled only accept APPROVALS recorded from a subagent session (one with a parent session), never from the root session itself.",
 			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"),
@@ -281,6 +284,15 @@ export function createCustomTools(options: {
 					return `[workflow-guard] Review rejected: the verdict cannot be bound because no tracked-content fingerprint is available for '${reviewWorkspace}' (not a git repository, or git is unavailable). The verdict was NOT recorded. Call record_review with 'directory' set to the reviewed repository worktree, or run it from a session rooted there.`;
 				}
 				const parentSessionID = await runWithRuntimeState(effectiveRoot, client, () => fetchParentSessionID(toolContext.sessionID));
+				if (args.passed && !parentSessionID && isSubagentReviewRequired(reviewWorkspace)) {
+					// Opt-in strict mode: a root session approving its own work
+					// is the self-approval loophole; require the recorder to be
+					// a subagent session (lineage, not agent role, so relay
+					// subagents still work). Content binding is unchanged —
+					// this only tightens WHO may record an approval.
+					auditVerdict("rejected", "subagent_recorder_required", { workspace: reviewWorkspace, recorderSessionID: toolContext.sessionID });
+					return `[workflow-guard] Review rejected: this project requires approvals to be recorded from a subagent session (requireSubagentReview), and '${toolContext.sessionID}' has no parent session. Spawn a secondary reviewer subagent with the task tool and record the verdict from that session, or set requireSubagentReview=false / WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=0.`;
+				}
 				const bindingCommitHash = getCurrentGitCommitHash(reviewWorkspace);
 				const binding = {
 					workspace: reviewWorkspace,
@@ -307,7 +319,7 @@ export function createCustomTools(options: {
 		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)"),
+				base: tool.schema.string().optional().describe("Base ref to diff against (default: origin/main, origin/master, main, master)"),
 				directory: tool.schema.string().optional().describe("Target repository directory (defaults to active session directory or workspace root)"),
 			},
 			execute: async (args, toolContext) => {
@@ -315,8 +327,10 @@ export function createCustomTools(options: {
 				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", "--no-ext-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", "--no-ext-diff", "HEAD~1"], { cwd: rubricWorkspace, encoding: "utf8", timeout: 10_000 }); diffText = last.status === 0 ? last.stdout : "(no diff available)"; }
+				// Revision before the trailing `--` (LL-001) so the base ref is
+				// always parsed as a revision, never as a pathspec.
+				for (const base of bases) { const res = spawnSync("git", ["diff", "--no-ext-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", "--no-ext-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/guard-dispatcher.ts

@@ -38,11 +38,11 @@ import {
 	resolveVerifyTimeoutMs,
 	snipVerifyOutput,
 } from "./verify.ts";
-import { detectShellMutation, extractPatchPaths, guardShellMutation, isPathOutsideWorkspace } from "../policies/boundary.ts";
+import { detectShellMutation, extractPatchPaths, guardShellMutation, hasUnresolvableVariable, isEnvironmentScratchTarget, isPathOutsideWorkspace, OPENCODE_SCRATCH_DIR } from "../policies/boundary.ts";
 import { branchHasChangelogChange, checkLockfileSync, hasPrCreateInvocation, prBodyHasLiteralLineBreakEscapes, prBodyIncludesChangelog } from "../policies/changelog.ts";
 import { extractEditContent, liveMutationIn } from "../policies/destructive.ts";
 import { branchHasDocumentationChange } from "../policies/docs.ts";
-import { claimFiles, fileClaimConflictReason } from "../policies/file-claims.ts";
+import { claimFiles, fileClaimConflictReason, releaseStaleFileClaims } from "../policies/file-claims.ts";
 import {
 	GIT_BRANCH_CREATE_RE,
 	GIT_WRITE_RE,
@@ -223,13 +223,29 @@ export async function guardToolCallImpl(
 				}
 				if (isPathOutsideWorkspace(patchPath, currentRoot)) {
 					logPolicyBlock(`[workflow-guard] blocked apply_patch: patch target escapes workspace: ${patchPath}`);
-					return block("boundary", "workspace_escape", `Blocked: patch targets file '${patchPath}' outside workspace root (${currentRoot}).`);
+					return block(
+						"boundary",
+						"workspace_escape",
+						hasUnresolvableVariable(patchPath)
+							? `Blocked: patch targets file '${patchPath}', which contains an unresolvable variable reference; indeterminate destinations are treated as outside the workspace root (${currentRoot}). Use a literal workspace-relative path.`
+							: isEnvironmentScratchTarget(patchPath, currentRoot)
+								? `Blocked: patch targets file '${patchPath}' under ${OPENCODE_SCRATCH_DIR}, the environment scratch directory the workspace boundary does not cover; write scratch as an untracked file inside the workspace root (${currentRoot}) instead (for example .tmp-notes.md).`
+								: `Blocked: patch targets file '${patchPath}' outside workspace root (${currentRoot}).`,
+					);
 				}
 			}
 		}
 		if (target && isPathOutsideWorkspace(target, currentRoot)) {
 			logPolicyBlock(`[workflow-guard] blocked ${toolName}: path escapes workspace: ${target}`);
-			return block("boundary", "workspace_escape", `Blocked: file path '${target}' escapes workspace root (${currentRoot}). All changes must stay within the workspace.`);
+			return block(
+				"boundary",
+				"workspace_escape",
+				hasUnresolvableVariable(target)
+					? `Blocked: file path '${target}' contains an unresolvable variable reference, so the boundary treats it as outside the workspace root (${currentRoot}). Use a literal workspace-relative path; all changes must stay within the workspace.`
+					: isEnvironmentScratchTarget(target, currentRoot)
+						? `Blocked: file path '${target}' is under ${OPENCODE_SCRATCH_DIR}, the environment scratch directory the workspace boundary does not cover; write scratch as an untracked file inside the workspace root (${currentRoot}) instead (for example .tmp-notes.md).`
+						: `Blocked: file path '${target}' escapes workspace root (${currentRoot}). All changes must stay within the workspace.`,
+			);
 		}
 		for (const content of extractEditContent(input)) {
 			const secret = secretIn(content);
@@ -278,6 +294,12 @@ export async function guardToolCallImpl(
 				}
 			}
 			const targets = editTargets(input, currentRoot);
+			if (!context.simulate) {
+				// A missed idle release can leave a finished session's claims
+				// behind; release provably stale ones before claiming. The
+				// simulate path (guard_why) stays read-only.
+				await releaseStaleFileClaims(targets, context.sessionID);
+			}
 			const claimReason = context.simulate
 				? fileClaimConflictReason(targets, context.sessionID)
 				: context.callID ? claimFiles(targets, context.sessionID, context.callID) : undefined;
@@ -327,7 +349,13 @@ export async function guardToolCallImpl(
 			const normalizedInvocation = `git ${invocation.rest}`;
 			if (isPathOutsideWorkspace(invocation.repoDir, currentRoot) && (GIT_WRITE_RE.test(normalizedInvocation) || /\bgit\s+push\b/.test(normalizedInvocation))) {
 				logPolicyBlock(`[workflow-guard] blocked git mutation on repository outside workspace: ${invocation.repoDir}`);
-				return block("boundary", "workspace_escape", `Blocked: git command targets repository '${invocation.repoDir}' outside workspace root (${currentRoot}). All changes must stay within the workspace.`);
+				return block(
+					"boundary",
+					"workspace_escape",
+					hasUnresolvableVariable(invocation.repoDir)
+						? `Blocked: git command targets repository '${invocation.repoDir}', which contains an unresolvable variable reference; indeterminate destinations are treated as outside the workspace root (${currentRoot}). Use a literal workspace-relative path.`
+						: `Blocked: git command targets repository '${invocation.repoDir}' outside workspace root (${currentRoot}). All changes must stay within the workspace.`,
+				);
 			}
 		}
 		for (const invocation of gitInvocations) {
@@ -359,7 +387,13 @@ export async function guardToolCallImpl(
 			const outsidePath = outsideWritePathInPayload(payload, currentRoot);
 			if (outsidePath) {
 				logPolicyBlock(`[workflow-guard] blocked interpreter payload writing outside workspace: ${outsidePath}`);
-				return block("boundary", "workspace_escape", `Blocked: inline interpreter script targets file '${outsidePath}' outside workspace root (${currentRoot}). All changes must stay within the workspace.`);
+				return block(
+					"boundary",
+					"workspace_escape",
+					hasUnresolvableVariable(outsidePath)
+						? `Blocked: inline interpreter script targets file '${outsidePath}', which contains an unresolvable variable reference; indeterminate destinations are treated as outside the workspace root (${currentRoot}). Use a literal workspace-relative path.`
+						: `Blocked: inline interpreter script targets file '${outsidePath}' outside workspace root (${currentRoot}). All changes must stay within the workspace.`,
+				);
 			}
 			const writePaths = writePathsInPayload(payload);
 			if (writePaths.length > 0) {

package/src/lib/hygiene.ts

@@ -0,0 +1,66 @@
+import { spawnSync } from "node:child_process";
+import { checkBranchBaseIsUpToDate, currentGitBranch } from "../policies/git.ts";
+import { getCleanGitEnv } from "./worktree.ts";
+
+const MERGED_BASES = ["origin/main", "origin/master", "main", "master"];
+const MAX_LISTED_BRANCHES = 10;
+
+export interface GitHygieneSnapshot {
+	/** Local branches fully merged into the mainline, capped for bounded output. */
+	mergedLocalBranches: string[];
+	/** True count of merged local branches (the list above may be capped). */
+	mergedLocalBranchCount: number;
+	/** Worktree admin entries whose directory is missing (clearable via cleanupGitWorktree or git worktree prune). */
+	prunableWorktreeCount: number;
+	/** Commits the current branch's base line is ahead by, when a remote base exists. */
+	baseBehind?: number;
+	baseRef?: string;
+}
+
+function gitOut(args: string[], root: string): string | undefined {
+	const res = spawnSync("git", args, {
+		cwd: root,
+		encoding: "utf8",
+		timeout: 10_000,
+		env: getCleanGitEnv(),
+	});
+	if (res.status !== 0) return undefined;
+	return res.stdout;
+}
+
+/**
+ * Read-only accumulation snapshot for guard_status: local branches already
+ * merged into the mainline, prunable worktree admin entries, and how far the
+ * current branch's base line is ahead. Hygiene itself stays manual — the
+ * guard reports, it never prunes or deletes branches on its own.
+ */
+export function gitHygieneSnapshot(root: string): GitHygieneSnapshot | undefined {
+	const current = currentGitBranch(root);
+	if (current === undefined) {
+		// Not a git repository (or git unavailable): no hygiene snapshot.
+		return undefined;
+	}
+	const snapshot: GitHygieneSnapshot = { mergedLocalBranches: [], mergedLocalBranchCount: 0, prunableWorktreeCount: 0 };
+	for (const base of MERGED_BASES) {
+		const out = gitOut(["branch", "--merged", base, "--format=%(refname:short)"], root);
+		if (out === undefined) continue;
+		const branches = out
+			.split("\n")
+			.map((line) => line.trim())
+			.filter((name) => name.length > 0 && name !== base && name !== current)
+			.sort();
+		snapshot.mergedLocalBranchCount = branches.length;
+		snapshot.mergedLocalBranches = branches.slice(0, MAX_LISTED_BRANCHES);
+		break;
+	}
+	const worktreeOut = gitOut(["worktree", "list", "--porcelain"], root);
+	if (worktreeOut !== undefined) {
+		snapshot.prunableWorktreeCount = worktreeOut.split("\n").filter((line) => line.startsWith("prunable")).length;
+	}
+	const behind = checkBranchBaseIsUpToDate(root);
+	if (behind.isBehind) {
+		snapshot.baseBehind = behind.count;
+		snapshot.baseRef = behind.baseRef;
+	}
+	return snapshot;
+}

package/src/lib/state.ts

@@ -330,6 +330,13 @@ export function isReviewRequired(root: string): boolean {
 	return cfg.requireReview !== false;
 }
 
+export function isSubagentReviewRequired(root: string): boolean {
+	const env = process.env.WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW?.toLowerCase();
+	if (env === "0" || env === "false" || env === "off") return false;
+	if (env === "1" || env === "true" || env === "on") return true;
+	return getProjectConfig(root).requireSubagentReview === true;
+}
+
 export function isDocumentationRequired(root: string): boolean {
 	if (process.env.WORKFLOW_GUARD_REQUIRE_DOCS === "1") return true;
 	const cfg = getProjectConfig(root);

package/src/lib/types.ts

@@ -9,7 +9,14 @@ export interface TodoSdkClient {
 	};
 	session?: {
 		todo?: (opts: { path: { id: string } }) => Promise<{ data?: unknown }>;
-		get?: (opts: { path: { id: string } }) => Promise<{ data?: { parentID?: unknown; title?: unknown } }>;
+		/**
+		 * The returned record's `data.time.idle` (ms epoch, server-recorded
+		 * when a session's turn ends; absent/zero while mid-turn) is the
+		 * stale-claim staleness boundary in src/policies/file-claims.ts. The
+		 * field is assumption-typed because the minimal SDK surface here does
+		 * not declare it; a missing, zero, or non-numeric value fails closed.
+		 */
+		get?: (opts: { path: { id: string } }) => Promise<{ data?: { parentID?: unknown; title?: unknown; time?: { idle?: unknown } } }>;
 		promptAsync?: (opts: {
 			path: { id: string };
 			body: { messageID?: string; parts: Array<{ type: "text"; text: string; synthetic?: boolean }> };
@@ -34,6 +41,14 @@ export interface ProjectConfig {
 		timeoutMs?: number;
 	}>;
 	requireReview?: boolean;
+	/**
+	 * Opt-in strict mode for secondary reviews: when true, record_review
+	 * rejects approvals recorded by the root session itself, so a passing
+	 * verdict must come from a subagent session with a parent. Unset or false
+	 * keeps the documented relay flow where any session may record a verdict
+	 * that is then bound to the reviewed content.
+	 */
+	requireSubagentReview?: boolean;
 	requireDocumentation?: boolean;
 	/**
 	 * Absolute paths of the LIVE control plane (runtime `~/.config/opencode`,
@@ -122,6 +137,8 @@ export interface AuditEntry {
 	evidence?: {
 		mutation?: boolean;
 		targetPath?: string;
+		/** Owner of a released stale file claim (stale_claim_takeover audits). */
+		claimOwnerSessionID?: string;
 		verification?: {
 			command: string;
 			passed: boolean;

package/src/lib/v2-plugin.ts

@@ -59,6 +59,7 @@ import { beginReadObservation, recordMutationObservation, recordSuccessfulRead,
 import { editTargets, runPostEditValidators, snapshotFile } from "../policies/post-edit-validation.ts";
 import { audit, summarizeInput } from "./audit.ts";
 import { asRecord, showBlockToast, isSensitiveEnvKey } from "./utils.ts";
+import { loadedPluginVersion } from "./version.ts";
 import { clearContinuationState, continueUnfinishedSession, isGeneratedContinuationMessage, recordUserMessage } from "../policies/continuation.ts";
 import { createRecoveryCheckpoint, finalizeRecoveryCheckpoint, nextRecoveryRun } from "./checkpoint.ts";
 import { buildCompactionContext, guardToolCall } from "../workflow-guard.ts";
@@ -175,7 +176,7 @@ export const WorkflowGuardV2 = async (ctx: V2Context) => {
 	}
 
 	try {
-		console.log(`[workflow-guard] info: Workflow Guard plugin initialized for ${effectiveRoot}; provenance is plugin-local in V2`);
+		console.log(`[workflow-guard] info: Workflow Guard v${loadedPluginVersion() ?? "unknown"} plugin initialized for ${effectiveRoot}; provenance is plugin-local in V2`);
 	} catch {}
 
 	const toolLifecycle = new ToolInvocationLifecycle();

package/src/lib/version.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The version of the package this module was loaded from, read from the
+ * adjacent package.json (the package ships TypeScript source, so the manifest
+ * always sits two levels above src/). Fail-soft: an unreadable or malformed
+ * manifest (for example a bundled or relocated copy without package.json)
+ * yields undefined, and callers surface that absence rather than guessing.
+ * This exists because OpenCode resolves configured bare package names through
+ * Node's parent-directory lookup from its configuration location, so the
+ * loaded copy can silently differ from a globally npm-installed one.
+ */
+export function loadedPluginVersion(moduleUrl: string = import.meta.url): string | undefined {
+	try {
+		const manifest = JSON.parse(readFileSync(fileURLToPath(new URL("../../package.json", moduleUrl)), "utf8")) as { version?: unknown };
+		return typeof manifest.version === "string" && manifest.version ? manifest.version : undefined;
+	} catch {
+		return undefined;
+	}
+}

package/src/policies/boundary.ts

@@ -53,6 +53,33 @@ export function expandShellTargetPath(targetPath: string): string | null {
 	return out;
 }
 
+/**
+ * A mutation/redirect target whose expansion is indeterminate (it contains an
+ * unresolvable `$VARIABLE` reference): the boundary treats such destinations
+ * as outside the workspace, and block messages attribute that cause instead
+ * of the generic escape message.
+ */
+export function hasUnresolvableVariable(targetPath: string): boolean {
+	return expandShellTargetPath(targetPath) === null;
+}
+
+/**
+ * The OpenCode harness designates this directory as the agents' scratch
+ * space ("pre-created and approved for external access"), but the workspace
+ * boundary is workspace-absolute and does not cover it. Targets under it get
+ * a cause-attributed block message so agents stop treating the block as a
+ * guard bug and write scratch as untracked files inside the workspace
+ * instead. Message-only: the boundary decision itself is unchanged.
+ */
+export const OPENCODE_SCRATCH_DIR = "/tmp/opencode";
+
+export function isEnvironmentScratchTarget(targetPath: string, root: string): boolean {
+	const expanded = expandShellTargetPath(targetPath);
+	if (expanded === null) return false;
+	const resolved = resolve(root, expanded);
+	return resolved === OPENCODE_SCRATCH_DIR || resolved.startsWith(OPENCODE_SCRATCH_DIR + "/");
+}
+
 export function isPathOutsideWorkspace(targetPath: string, root: string): boolean {
 	if (!targetPath) return false;
 	const expanded = expandShellTargetPath(targetPath);
@@ -372,6 +399,9 @@ export async function guardShellMutation(
 					return PROTECTED_PATH_REASON;
 				}
 				if (isPathOutsideWorkspace(source, root)) {
+					if (hasUnresolvableVariable(source)) {
+						return `Blocked: mv source '${source}' contains an unresolvable variable reference; indeterminate destinations are treated as outside the workspace root (${root}). Use a literal workspace-relative path.`;
+					}
 					return `Blocked: mv would remove source '${source}' from outside the workspace root (${root}). File mutations must stay within the workspace.`;
 				}
 			}
@@ -403,6 +433,12 @@ export async function guardShellMutation(
 				// The workspace boundary has no override: a write outside the
 				// workspace is out of bounds even with WORKFLOW_GUARD_ALLOW_LIVE
 				// (that override covers live-system commands, not the boundary).
+				if (hasUnresolvableVariable(target)) {
+					return `Blocked: shell mutation '${mutation.what}' targets '${target}', which contains an unresolvable variable reference; indeterminate destinations are treated as outside the workspace root (${root}). Use a literal workspace-relative path.`;
+				}
+				if (isEnvironmentScratchTarget(target, root)) {
+					return `Blocked: shell mutation '${mutation.what}' targets '${target}' under ${OPENCODE_SCRATCH_DIR}, the environment scratch directory the workspace boundary does not cover; write scratch as an untracked file inside the workspace root (${root}) instead (for example .tmp-notes.md).`;
+				}
 				return `Blocked: shell mutation '${mutation.what}' targets a path outside the workspace root (${root}). All changes must stay within the workspace.`;
 			}
 			if (onProtectedBranch(root)) {

package/src/policies/file-claims.ts

@@ -1,9 +1,13 @@
 import { readlinkSync, realpathSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
+import { audit } from "../lib/audit.ts";
+import { getSdkClient } from "../lib/state.ts";
 
 interface FileClaim {
 	sessionID: string;
 	callID: string;
+	/** Creation timestamp; a claim older than its owner's last idle is stale. */
+	ts: number;
 }
 
 const claims = new Map<string, FileClaim>();
@@ -36,8 +40,14 @@ export function claimFiles(paths: string[], sessionID: string, callID: string):
 	const conflict = fileClaimConflictReason(canonical, sessionID);
 	if (conflict) return conflict;
 	for (const path of canonical) {
-		if (!claims.has(path)) {
-			claims.set(path, { sessionID, callID });
+		const existing = claims.get(path);
+		if (!existing) {
+			claims.set(path, { sessionID, callID, ts: Date.now() });
+		} else if (existing.sessionID === sessionID) {
+			// The same session re-claiming the path refreshes the claim so the
+			// timestamp (and callID) reflect the in-flight call: stale-takeover
+			// never fires for it, and the after-hook release matches.
+			claims.set(path, { sessionID, callID, ts: Date.now() });
 		}
 	}
 	return undefined;
@@ -54,6 +64,62 @@ export function fileClaimConflictReason(paths: string[], sessionID: string): str
 	return undefined;
 }
 
+/**
+ * A claim is normally released by its owning tool call (after-hook) or by the
+ * owner's session.idle/session.deleted events. When an idle release is missed,
+ * the claim would otherwise block every other session forever. A claim created
+ * BEFORE its owner's last recorded idle timestamp cannot belong to an
+ * in-flight tool call — that call finished before the turn ended — so it is
+ * provably stale and is released with an audited takeover. Without an SDK
+ * client, or when the owner record cannot be read, nothing is released:
+ * fail-closed keeps live two-session protection intact. Clock skew between
+ * this process and the server is not expected for a local (same-host)
+ * service: negative skew fails closed; forward skew could make fresh claims
+ * look stale and is accepted for that deployment. Concurrent claimants can
+ * emit duplicate takeover audits (append-only, harmless). Release is
+ * per-claim: only claims whose ts is provably stale are dropped, re-read
+ * AFTER the lookup round-trip so an owner that re-claimed (and refreshed) a
+ * path meanwhile keeps its live claim.
+ */
+export async function releaseStaleFileClaims(paths: string[], claimantSessionID: string): Promise<void> {
+	const canonical = [...new Set(paths.map((path) => canonicalPath(path)))];
+	const staleOwners = new Map<string, string>();
+	for (const path of canonical) {
+		const existing = claims.get(path);
+		if (existing && existing.sessionID !== claimantSessionID && !staleOwners.has(existing.sessionID)) {
+			staleOwners.set(existing.sessionID, path);
+		}
+	}
+	if (staleOwners.size === 0) return;
+	const client = getSdkClient();
+	const session = client?.session;
+	const get = session?.get;
+	if (!session || typeof get !== "function") return;
+	for (const [ownerSessionID] of staleOwners) {
+		try {
+			const result = await get.call(session, { path: { id: ownerSessionID } });
+			const idle = (result as { data?: { time?: { idle?: unknown } } } | undefined)?.data?.time?.idle;
+			if (typeof idle !== "number" || idle <= 0) continue;
+			// Release every claim of this owner that is provably stale. Each
+			// claim is re-read after the lookup round-trip so an owner that
+			// re-claimed (and refreshed) a path meanwhile keeps its live claim.
+			for (const [claimPath, claim] of [...claims]) {
+				if (claim.sessionID !== ownerSessionID || claim.ts >= idle) continue;
+				claims.delete(claimPath);
+				audit({
+					ts: new Date().toISOString(),
+					sessionID: claimantSessionID,
+					tool: "file-claims",
+					decision: "allow",
+					phase: "event",
+					reason: "stale_claim_takeover",
+					evidence: { mutation: false, targetPath: claimPath, claimOwnerSessionID: ownerSessionID },
+				});
+			}
+		} catch {}
+	}
+}
+
 export function releaseFileClaims(sessionID: string, callID?: string): void {
 	for (const [path, claim] of claims) {
 		if (claim.sessionID === sessionID && (callID === undefined || claim.callID === callID)) {

package/src/workflow-guard.ts

@@ -14,6 +14,7 @@ import { WorkflowGuardV2 } from "./lib/v2-plugin.ts";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { join } from "node:path";
+import { loadedPluginVersion } from "./lib/version.ts";
 import { editTargets, runPostEditValidators, snapshotFile } from "./policies/post-edit-validation.ts";
 import { claimFiles, releaseFileClaims } from "./policies/file-claims.ts";
 import { beginReadObservation, clearReadFingerprints, recordMutationObservation, recordSuccessfulRead, staleWriteReason } from "./policies/stale-write.ts";
@@ -70,6 +71,7 @@ import {
 	getOperationProfile,
 	isRecoveryCheckpointsEnabled,
 	isReviewRequired,
+	isSubagentReviewRequired,
 	isDocumentationRequired,
 	getSubagentMutationBudget,
 	isLearningEnabled,
@@ -103,6 +105,7 @@ export {
 	getOperationProfile,
 	isRecoveryCheckpointsEnabled,
 	isReviewRequired,
+	isSubagentReviewRequired,
 	isDocumentationRequired,
 	getSubagentMutationBudget,
 	isLearningEnabled,
@@ -189,6 +192,8 @@ export function managedConfigDiagnostic(platform = process.platform, env: NodeJS
 		: "managed config location is unknown on this platform; plugin provenance is not verified by the OpenCode V1 API";
 }
 
+export { loadedPluginVersion } from "./lib/version.ts";
+
 // ── Verification engine ──────────────────────────────────────────────────────
 import {
 	detectVerifyCommand,
@@ -431,7 +436,7 @@ export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 			body: {
 				service: "workflow-guard",
 				level: "info",
-				message: `Workflow Guard plugin initialized for ${effectiveRoot}; ${managedConfigDiagnostic()}`,
+				message: `Workflow Guard v${loadedPluginVersion() ?? "unknown"} plugin initialized for ${effectiveRoot}; ${managedConfigDiagnostic()}`,
 			},
 		});
 	} catch {}

package/test/test.mts

@@ -2,6 +2,7 @@ import { mkdtempSync, writeFileSync, rmSync, symlinkSync, readFileSync, existsSy
 import { spawn, spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
 import type { PluginModule } from "@opencode-ai/plugin";
 import { getRalphMaxIterations, runWithRuntimeState } from "../src/lib/state.ts";
@@ -74,6 +75,7 @@ import {
 	checkLockfileSync,
 	branchHasDocumentationChange,
 	isDocumentationRequired,
+	loadedPluginVersion,
 	isReviewRequired,
 	getOperationProfile,
 	isRecoveryCheckpointsEnabled,
@@ -678,6 +680,35 @@ check("block write to /etc/passwd", blocked(await call("write", { filePath: "/et
 check("block write to ~ path", blocked(await call("write", { filePath: "~/.bashrc", content: "x" }, { sessionID: "s-active" })));
 check("block write to $HOME path", blocked(await call("write", { filePath: "$HOME/.profile", content: "x" }, { sessionID: "s-active" })));
 check("block write to unresolvable $VAR path", blocked(await call("write", { filePath: "$UNKNOWN_DIR/file.txt", content: "x" }, { sessionID: "s-active" })));
+// Cause attribution: indeterminate $VARIABLE destinations get a message that
+// names the unresolvable reference (the on-device over-block class), while
+// deterministically-outside paths keep the generic escape message.
+const unresolvableWrite = await call("write", { filePath: "$UNKNOWN_DIR/file.txt", content: "x" }, { sessionID: "s-active" });
+check("unresolvable $VAR write names the variable cause", blocked(unresolvableWrite) && String(unresolvableWrite).includes("unresolvable variable reference") && String(unresolvableWrite).includes("$UNKNOWN_DIR"));
+const literalEscapeWrite = await call("write", { filePath: "/etc/passwd", content: "x" }, { sessionID: "s-active" });
+check("literal outside path keeps the generic escape message", blocked(literalEscapeWrite) && String(literalEscapeWrite).includes("escapes workspace root") && !String(literalEscapeWrite).includes("unresolvable variable reference"));
+const homeWrite = await call("write", { filePath: "$HOME/.profile", content: "x" }, { sessionID: "s-active" });
+check("deterministically-expanded $HOME path keeps the generic escape message", blocked(homeWrite) && String(homeWrite).includes("escapes workspace root") && !String(homeWrite).includes("unresolvable variable reference"));
+const unresolvableShell = await call("bash", { command: "mkdir -p $D/sub" }, { sessionID: "s-active" });
+check("shell mutation with unresolvable $VAR names the variable cause", blocked(unresolvableShell) && String(unresolvableShell).includes("unresolvable variable reference") && String(unresolvableShell).includes("$D"));
+const unresolvablePatch = await call("apply_patch", { patchText: "*** Update File: $UNKNOWN_DIR/file.ts\n" }, { sessionID: "s-active" });
+check("apply_patch with unresolvable $VAR names the variable cause", blocked(unresolvablePatch) && String(unresolvablePatch).includes("unresolvable variable reference"));
+const unresolvableMv = await call("bash", { command: "mv $D/foo.txt ./bar.txt" }, { sessionID: "s-active" });
+check("mv source with unresolvable $VAR names the variable cause", blocked(unresolvableMv) && String(unresolvableMv).includes("unresolvable variable reference"));
+const unresolvableGit = await call("bash", { command: "git -C $OTHER_REPO commit -m x" }, { sessionID: "s-active" });
+check("git repoDir with unresolvable $VAR names the variable cause", blocked(unresolvableGit) && String(unresolvableGit).includes("unresolvable variable reference"));
+// Scratch-directory cause attribution: /tmp/opencode is the environment's
+// designated scratch space, but the workspace boundary is workspace-absolute
+// and does not cover it; the message explains that instead of reading as a
+// guard bug (6 of the device audit's boundary blocks were this class).
+const scratchWrite = await call("write", { filePath: "/tmp/opencode/scratch.txt", content: "x" }, { sessionID: "s-active" });
+check("scratch-dir write attributes the environment scratch cause", blocked(scratchWrite) && String(scratchWrite).includes("environment scratch directory") && String(scratchWrite).includes("/tmp/opencode") && !String(scratchWrite).includes("unresolvable variable reference"));
+const scratchRedirect = await call("bash", { command: "echo x > /tmp/opencode/out.md" }, { sessionID: "s-active" });
+check("scratch-dir redirect attributes the environment scratch cause", blocked(scratchRedirect) && String(scratchRedirect).includes("environment scratch directory"));
+const scratchPatch = await call("apply_patch", { patchText: "*** Add File: /tmp/opencode/scratch.ts\n+scratch\n" }, { sessionID: "s-active" });
+check("scratch-dir apply_patch attributes the environment scratch cause", blocked(scratchPatch) && String(scratchPatch).includes("environment scratch directory"));
+const otherOutsideWrite = await call("write", { filePath: "/var/tmp/elsewhere.txt", content: "x" }, { sessionID: "s-active" });
+check("non-scratch outside path keeps the generic escape message", blocked(otherOutsideWrite) && String(otherOutsideWrite).includes("escapes workspace root") && !String(otherOutsideWrite).includes("scratch directory"));
 check("allow apply_patch within workspace", !(await call("apply_patch", { patchText: "*** Update File: src/app.ts\n" }, { sessionID: "s-active" })));
 check("block apply_patch escaping workspace", blocked(await call("apply_patch", { patchText: "*** Update File: ../../secret.env\n" }, { sessionID: "s-active" })));
 
@@ -897,6 +928,169 @@ try {
 }
 check("blocked multi-target patch leaves no partial claims", !partialPatchClaim);
 
+// Stale claim takeover (missed idle release): a claim created BEFORE its
+// owner's last recorded idle timestamp cannot belong to an in-flight tool
+// call, so a leaked claim must not block another session forever. Owners that
+// are still mid-session (no idle timestamp), a client without a session
+// lookup, and a failing lookup all keep the block (fail-closed).
+console.log("- Stale file-claim takeover -");
+const takeoverDir = mkdtempSync(join(tmpdir(), "wg-claim-takeover-"));
+writeFileSync(join(takeoverDir, "stale.ts"), "before");
+writeFileSync(join(takeoverDir, "live.ts"), "before");
+writeFileSync(join(takeoverDir, "refresh.ts"), "before");
+const takeoverIdle = new Map<string, number>();
+const takeoverClient = {
+	session: {
+		todo: fakeClient.session.todo,
+		get: async ({ path }: { path: { id: string } }) => {
+			const idle = takeoverIdle.get(path.id);
+			return { data: { id: path.id, parentID: fakeParents.get(path.id), ...(typeof idle === "number" ? { time: { idle } } : {}) } };
+		},
+	},
+};
+const takeoverHooks = await pluginFn({
+	directory: takeoverDir,
+	client: takeoverClient as any,
+	project: {} as any,
+	worktree: takeoverDir,
+	experimental_workspace: {} as any,
+	serverUrl: new URL("http://localhost:4096"),
+	$: undefined as any,
+});
+todo("s-stale-owner", item("edit stale file", "in_progress"));
+todo("s-live-owner", item("edit live file", "in_progress"));
+todo("s-claimant", item("take over stale claim", "in_progress"));
+const takeoverBefore = takeoverHooks["tool.execute.before"];
+const takeoverAfter = takeoverHooks["tool.execute.after"];
+
+// The owner claims the file, its after-hook is skipped, and it idles LATER.
+await recordRead(takeoverBefore, takeoverAfter, "s-stale-owner", join(takeoverDir, "stale.ts"), "takeover-read-stale");
+await takeoverBefore?.({ tool: "edit", sessionID: "s-stale-owner", callID: "stale-claim" }, { args: { filePath: join(takeoverDir, "stale.ts"), content: "a" } });
+await new Promise((resolve) => setTimeout(resolve, 10));
+takeoverIdle.set("s-stale-owner", Date.now());
+// A live owner, still mid-session, claims the other file.
+await recordRead(takeoverBefore, takeoverAfter, "s-live-owner", join(takeoverDir, "live.ts"), "takeover-read-live");
+await takeoverBefore?.({ tool: "edit", sessionID: "s-live-owner", callID: "live-claim" }, { args: { filePath: join(takeoverDir, "live.ts"), content: "b" } });
+
+await recordRead(takeoverBefore, takeoverAfter, "s-claimant", join(takeoverDir, "stale.ts"), "takeover-read-claimant");
+let staleTakeoverAllowed = true;
+try {
+	await takeoverBefore?.({ tool: "edit", sessionID: "s-claimant", callID: "takeover-claim" }, { args: { filePath: join(takeoverDir, "stale.ts"), content: "c" } });
+} catch {
+	staleTakeoverAllowed = false;
+}
+check("a claim older than its owner's recorded idle is released for the next claimant", staleTakeoverAllowed);
+const takeoverAudit = getRecentAuditEntries(30).find((entry) => entry.tool === "file-claims" && entry.reason === "stale_claim_takeover");
+check("stale claim takeover is audited with the released path and owner", takeoverAudit?.decision === "allow" && typeof takeoverAudit?.evidence?.targetPath === "string" && takeoverAudit.evidence.targetPath.endsWith("stale.ts") && takeoverAudit.evidence.claimOwnerSessionID === "s-stale-owner");
+await takeoverAfter?.({ tool: "edit", sessionID: "s-claimant", callID: "takeover-claim", args: {} }, { title: "edit", output: "edited", metadata: {} });
+
+// A live owner, still mid-turn (no idle timestamp recorded), keeps its claim.
+await recordRead(takeoverBefore, takeoverAfter, "s-claimant", join(takeoverDir, "live.ts"), "takeover-read-live-claimant");
+let liveClaimBlocked = false;
+try {
+	await takeoverBefore?.({ tool: "edit", sessionID: "s-claimant", callID: "live-blocked" }, { args: { filePath: join(takeoverDir, "live.ts"), content: "c" } });
+} catch (error) {
+	liveClaimBlocked = String(error).includes("claimed by another active session");
+}
+check("a live owner without an idle timestamp keeps its claim", liveClaimBlocked);
+await takeoverAfter?.({ tool: "edit", sessionID: "s-live-owner", callID: "live-claim", args: {} }, { title: "edit", output: "edited", metadata: {} });
+
+// A same-session re-claim refreshes the stored claim (new callID/timestamp):
+// an owner that idled with a leaked claim and comes back to the same file
+// mid-turn must not have its fresh claim taken over, and the refreshed
+// callID must be the one the after-hook releases.
+await recordRead(takeoverBefore, takeoverAfter, "s-stale-owner", join(takeoverDir, "refresh.ts"), "takeover-read-refresh");
+await takeoverBefore?.({ tool: "edit", sessionID: "s-stale-owner", callID: "refresh-claim-1" }, { args: { filePath: join(takeoverDir, "refresh.ts"), content: "d" } });
+await new Promise((resolve) => setTimeout(resolve, 10));
+takeoverIdle.set("s-stale-owner", Date.now());
+await takeoverBefore?.({ tool: "edit", sessionID: "s-stale-owner", callID: "refresh-claim-2" }, { args: { filePath: join(takeoverDir, "refresh.ts"), content: "e" } });
+await recordRead(takeoverBefore, takeoverAfter, "s-claimant", join(takeoverDir, "refresh.ts"), "takeover-read-refresh-claimant");
+let refreshClaimBlocked = false;
+try {
+	await takeoverBefore?.({ tool: "edit", sessionID: "s-claimant", callID: "refresh-conflict" }, { args: { filePath: join(takeoverDir, "refresh.ts"), content: "f" } });
+} catch (error) {
+	refreshClaimBlocked = String(error).includes("claimed by another active session");
+}
+check("a same-session re-claim refreshes past the owner's idle so it is not taken over mid-turn", refreshClaimBlocked);
+await takeoverAfter?.({ tool: "edit", sessionID: "s-stale-owner", callID: "refresh-claim-2", args: {} }, { title: "edit", output: "edited", metadata: {} });
+let refreshReleasedAllowed = true;
+try {
+	await takeoverBefore?.({ tool: "edit", sessionID: "s-claimant", callID: "refresh-after-release" }, { args: { filePath: join(takeoverDir, "refresh.ts"), content: "g" } });
+} catch {
+	refreshReleasedAllowed = false;
+}
+check("the refreshed claim releases through its updated callID", refreshReleasedAllowed);
+await takeoverAfter?.({ tool: "edit", sessionID: "s-claimant", callID: "refresh-after-release", args: {} }, { title: "edit", output: "edited", metadata: {} });
+
+// The takeover releases every provably stale claim of the owner, each with
+// its own audit entry: an owner holding two stale paths loses both in one
+// pass, and no fresh claim of that owner is touched.
+writeFileSync(join(takeoverDir, "multi-a.ts"), "before");
+writeFileSync(join(takeoverDir, "multi-b.ts"), "before");
+await recordRead(takeoverBefore, takeoverAfter, "s-stale-owner", join(takeoverDir, "multi-a.ts"), "takeover-read-multi-a");
+await takeoverBefore?.({ tool: "edit", sessionID: "s-stale-owner", callID: "multi-claim-a" }, { args: { filePath: join(takeoverDir, "multi-a.ts"), content: "h" } });
+await recordRead(takeoverBefore, takeoverAfter, "s-stale-owner", join(takeoverDir, "multi-b.ts"), "takeover-read-multi-b");
+await takeoverBefore?.({ tool: "edit", sessionID: "s-stale-owner", callID: "multi-claim-b" }, { args: { filePath: join(takeoverDir, "multi-b.ts"), content: "h" } });
+await new Promise((resolve) => setTimeout(resolve, 10));
+takeoverIdle.set("s-stale-owner", Date.now());
+await recordRead(takeoverBefore, takeoverAfter, "s-claimant", join(takeoverDir, "multi-a.ts"), "takeover-read-multi-a-claimant");
+let multiTakeoverAllowed = true;
+try {
+	await takeoverBefore?.({ tool: "edit", sessionID: "s-claimant", callID: "multi-takeover-a" }, { args: { filePath: join(takeoverDir, "multi-a.ts"), content: "i" } });
+} catch {
+	multiTakeoverAllowed = false;
+}
+check("one conflict releases every provably stale claim of the owner", multiTakeoverAllowed);
+await takeoverAfter?.({ tool: "edit", sessionID: "s-claimant", callID: "multi-takeover-a", args: {} }, { title: "edit", output: "edited", metadata: {} });
+await recordRead(takeoverBefore, takeoverAfter, "s-claimant", join(takeoverDir, "multi-b.ts"), "takeover-read-multi-b-claimant");
+let multiSecondAllowed = true;
+try {
+	await takeoverBefore?.({ tool: "edit", sessionID: "s-claimant", callID: "multi-takeover-b" }, { args: { filePath: join(takeoverDir, "multi-b.ts"), content: "j" } });
+} catch {
+	multiSecondAllowed = false;
+}
+check("the owner's other stale path is released in the same pass", multiSecondAllowed);
+await takeoverAfter?.({ tool: "edit", sessionID: "s-claimant", callID: "multi-takeover-b", args: {} }, { title: "edit", output: "edited", metadata: {} });
+const takeoverAudits = getRecentAuditEntries(30).filter((entry) => entry.reason === "stale_claim_takeover" && typeof entry.evidence?.targetPath === "string" && entry.evidence.targetPath.includes("multi-"));
+check("each released stale path has its own audited takeover entry", takeoverAudits.length === 2 && takeoverAudits.every((entry) => entry.evidence?.claimOwnerSessionID === "s-stale-owner"));
+
+// Fail-closed: no session lookup on the client, and a lookup that throws.
+const noLookupDir = mkdtempSync(join(tmpdir(), "wg-claim-nolookup-"));
+writeFileSync(join(noLookupDir, "file.ts"), "before");
+const noLookupHooks = await pluginFn({ directory: noLookupDir, client: {} as any, project: {} as any, worktree: noLookupDir, experimental_workspace: {} as any, serverUrl: new URL("http://localhost:4096"), $: undefined as any });
+const noLookupBefore = noLookupHooks["tool.execute.before"];
+const noLookupAfter = noLookupHooks["tool.execute.after"];
+todo("s-nolookup-owner", item("edit file", "in_progress"));
+await recordRead(noLookupBefore, noLookupAfter, "s-nolookup-owner", join(noLookupDir, "file.ts"), "nolookup-read-owner");
+await noLookupBefore?.({ tool: "edit", sessionID: "s-nolookup-owner", callID: "nolookup-claim" }, { args: { filePath: join(noLookupDir, "file.ts"), content: "a" } });
+todo("s-nolookup-claimant", item("edit file", "in_progress"));
+await recordRead(noLookupBefore, noLookupAfter, "s-nolookup-claimant", join(noLookupDir, "file.ts"), "nolookup-read-claimant");
+let noLookupBlocked = false;
+try {
+	await noLookupBefore?.({ tool: "edit", sessionID: "s-nolookup-claimant", callID: "nolookup-claimant" }, { args: { filePath: join(noLookupDir, "file.ts"), content: "b" } });
+} catch (error) {
+	noLookupBlocked = String(error).includes("claimed by another active session");
+}
+check("stale takeover fails closed when the client has no session lookup", noLookupBlocked);
+
+const throwLookupDir = mkdtempSync(join(tmpdir(), "wg-claim-throwlookup-"));
+writeFileSync(join(throwLookupDir, "file.ts"), "before");
+const throwLookupHooks = await pluginFn({ directory: throwLookupDir, client: { session: { get: async () => { throw new Error("lookup failed"); } } } as any, project: {} as any, worktree: throwLookupDir, experimental_workspace: {} as any, serverUrl: new URL("http://localhost:4096"), $: undefined as any });
+const throwLookupBefore = throwLookupHooks["tool.execute.before"];
+const throwLookupAfter = throwLookupHooks["tool.execute.after"];
+todo("s-throwlookup-owner", item("edit file", "in_progress"));
+await recordRead(throwLookupBefore, throwLookupAfter, "s-throwlookup-owner", join(throwLookupDir, "file.ts"), "throwlookup-read-owner");
+await throwLookupBefore?.({ tool: "edit", sessionID: "s-throwlookup-owner", callID: "throwlookup-claim" }, { args: { filePath: join(throwLookupDir, "file.ts"), content: "a" } });
+todo("s-throwlookup-claimant", item("edit file", "in_progress"));
+await recordRead(throwLookupBefore, throwLookupAfter, "s-throwlookup-claimant", join(throwLookupDir, "file.ts"), "throwlookup-read-claimant");
+let throwLookupBlocked = false;
+try {
+	await throwLookupBefore?.({ tool: "edit", sessionID: "s-throwlookup-claimant", callID: "throwlookup-claimant" }, { args: { filePath: join(throwLookupDir, "file.ts"), content: "b" } });
+} catch (error) {
+	throwLookupBlocked = String(error).includes("claimed by another active session");
+}
+check("stale takeover fails closed when the session lookup throws", throwLookupBlocked);
+
 // Existing files must be read by the same session before edit/write, and the
 // bytes plus filesystem identity must still match when the mutation starts.
 const staleDir = mkdtempSync(join(tmpdir(), "wg-stale-write-"));
@@ -2427,6 +2621,36 @@ check(
 );
 rmSync(rubricDiffRepo, { recursive: true, force: true });
 
+// The default-bases loop is directly asserted: with no origin remote, the
+// loop falls through origin/main and origin/master to the local main branch
+// and embeds the real branch diff. The spawn also keeps a trailing `--` after
+// the revision so the base ref can never parse as a pathspec (LL-001).
+const rubricNoOrigin = join(root, "wg-rubric-no-origin");
+mkdirSync(rubricNoOrigin, { recursive: true });
+spawnSync("git", ["init", "-b", "main"], { cwd: rubricNoOrigin });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: rubricNoOrigin });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: rubricNoOrigin });
+writeFileSync(join(rubricNoOrigin, "fallthrough.txt"), "base\n");
+spawnSync("git", ["add", "fallthrough.txt"], { cwd: rubricNoOrigin });
+spawnSync("git", ["commit", "-m", "base"], { cwd: rubricNoOrigin });
+spawnSync("git", ["switch", "-c", "feature/rubric-fallthrough"], { cwd: rubricNoOrigin });
+writeFileSync(join(rubricNoOrigin, "fallthrough.txt"), "branch marker\n");
+spawnSync("git", ["add", "fallthrough.txt"], { cwd: rubricNoOrigin });
+spawnSync("git", ["commit", "-qm", "branch change"], { cwd: rubricNoOrigin });
+// An uncommitted tracked edit discriminates the fallbacks: main...HEAD is
+// committed-only and must NOT include it, while the HEAD~1 fallback (commit
+// vs worktree) would — so the assertion proves the base loop won.
+writeFileSync(join(rubricNoOrigin, "fallthrough.txt"), "branch marker\nuncommitted worktree edit\n");
+const rubricFallthrough = await customPlugin.tool?.guard_review_rubric?.execute(
+	{ directory: rubricNoOrigin },
+	{ sessionID: "s-rubric-fallthrough", worktree: rubricNoOrigin, directory: rubricNoOrigin } as any,
+);
+check(
+	"rubric default bases fall through to the local main when no origin exists",
+	typeof rubricFallthrough === "string" && rubricFallthrough.includes("diff --git") && rubricFallthrough.includes("fallthrough.txt") && rubricFallthrough.includes("branch marker") && !rubricFallthrough.includes("uncommitted worktree edit"),
+);
+rmSync(rubricNoOrigin, { recursive: true, force: true });
+
 // Reviewer-type agents often lack record_review in their toolset entirely, so
 // the tool accepts recorders of any session type: the verdict binds to the
 // recording session's directory and the audit trail captures the recorder
@@ -2677,6 +2901,119 @@ check("PR blocked when only the reviewed commit drifted, with a commit-specific
 rmSync(driftRepo, { recursive: true, force: true });
 resetReviewState();
 
+// Strict recorder mode (requireSubagentReview): an opt-in policy that closes
+// the root-session self-approval path which default content binding keeps
+// open for read-only reviewer relays. Approvals must be recorded from a
+// subagent session (lineage, not agent role); changes-requested verdicts
+// stay relayable.
+console.log("- Strict Recorder Mode (requireSubagentReview) -");
+const strictSummary = "Test integrity: covered. Task completeness: complete. Cleanliness: clean. Security: safe. Platform: compatible.";
+const strictRepo = join(root, "wg-review-strict");
+mkdirSync(strictRepo, { recursive: true });
+spawnSync("git", ["init", "-b", "feature/strict-recorder"], { cwd: strictRepo });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: strictRepo });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: strictRepo });
+writeFileSync(join(strictRepo, "code.txt"), "base\n");
+spawnSync("git", ["add", "code.txt"], { cwd: strictRepo });
+spawnSync("git", ["commit", "-m", "base"], { cwd: strictRepo });
+mkdirSync(join(strictRepo, ".opencode"), { recursive: true });
+writeFileSync(join(strictRepo, ".opencode", "workflow-guard.json"), JSON.stringify({ requireReview: true, requireSubagentReview: true }));
+const strictPlugin = await WorkflowGuard({
+	directory: root,
+	worktree: root,
+	client: fakeClient as any,
+	project: {} as any,
+	experimental_workspace: {} as any,
+	serverUrl: new URL("http://localhost:4096"),
+	$: undefined as any,
+});
+const strictPrProbe = { tool: "bash", input: { command: "gh pr create --title t --body 'Changelog: strict'", workdir: strictRepo } };
+
+// Root-session self-approval is rejected before any verdict is recorded
+const strictRootAttempt = await strictPlugin.tool?.record_review?.execute(
+	{ reviewer: "self-approved", summary: strictSummary, passed: true },
+	{ sessionID: "s-strict-root", worktree: strictRepo, directory: strictRepo } as any,
+);
+const strictRootAudit = getRecentAuditEntries(20).find((entry) => entry.tool === "record_review.verdict" && entry.sessionID === "s-strict-root");
+check("strict mode: root-session approval is rejected with an actionable cause", typeof strictRootAttempt === "string" && strictRootAttempt.includes("rejected") && strictRootAttempt.includes("requireSubagentReview") && !strictRootAttempt.includes("APPROVED"));
+check("strict mode: rejected root approval is audited as subagent_recorder_required", strictRootAudit?.reason === "subagent_recorder_required");
+const strictStatusAfterRoot = JSON.parse(String(await strictPlugin.tool?.guard_status?.execute({ directory: strictRepo }, { sessionID: "s-strict-root", worktree: strictRepo, directory: strictRepo } as any)));
+check("strict mode: review gate stays unsatisfied after rejected self-approval", strictStatusAfterRoot.outstandingRequirements.includes("review") && strictStatusAfterRoot.lastReview === null && strictStatusAfterRoot.projectConfig?.requireSubagentReview === true);
+const strictPrAfterRoot = JSON.parse(String(await strictPlugin.tool?.guard_why?.execute(strictPrProbe, { sessionID: "s-strict-root", worktree: strictRepo, directory: strictRepo } as any)));
+check("strict mode: PR preflight still blocked after rejected self-approval", strictPrAfterRoot.status === "blocked" && strictPrAfterRoot.message.includes("Passing secondary review approval is required"));
+
+// Changes-requested findings remain relayable from the root session
+const strictRootNegative = await strictPlugin.tool?.record_review?.execute(
+	{ reviewer: "self-flagged", summary: strictSummary, passed: false },
+	{ sessionID: "s-strict-root", worktree: strictRepo, directory: strictRepo } as any,
+);
+check("strict mode: root session may still relay changes-requested verdicts", typeof strictRootNegative === "string" && strictRootNegative.includes("CHANGES REQUESTED"));
+
+// A subagent session (has a parent) records the approval
+fakeParents.set("s-strict-reviewer", "s-strict-root");
+const strictSubagentResult = await strictPlugin.tool?.record_review?.execute(
+	{ reviewer: "strict-reviewer", summary: strictSummary, passed: true },
+	{ sessionID: "s-strict-reviewer", agent: "general", worktree: strictRepo, directory: strictRepo } as any,
+);
+check("strict mode: subagent recorder records the approval", typeof strictSubagentResult === "string" && strictSubagentResult.includes("APPROVED"));
+const strictStatusAfterSubagent = JSON.parse(String(await strictPlugin.tool?.guard_status?.execute({ directory: strictRepo }, { sessionID: "s-strict-root", worktree: strictRepo, directory: strictRepo } as any)));
+check("strict mode: subagent approval satisfies the review gate", !strictStatusAfterSubagent.outstandingRequirements.includes("review") && strictStatusAfterSubagent.lastReview?.fresh === true);
+const strictPrAfterSubagent = JSON.parse(String(await strictPlugin.tool?.guard_why?.execute(strictPrProbe, { sessionID: "s-strict-root", worktree: strictRepo, directory: strictRepo } as any)));
+check("strict mode: PR preflight passes after subagent-recorded approval", strictPrAfterSubagent.status !== "blocked" && (strictPrAfterSubagent.status === "allowed" || strictPrAfterSubagent.code === "remote_state_unchecked"));
+if (strictPrAfterSubagent.status === "blocked") console.log("   blocked:", strictPrAfterSubagent.message);
+
+// The knob follows the REVIEWED workspace's config, not the caller's: a root
+// session based in a non-strict context cannot approve strictRepo's work by
+// naming it as the reviewed directory from outside strict mode. Note the
+// reviewed workspace comes from the tool ARG (`directory`), not the caller's
+// context; the context worktree below is deliberately the non-strict temp root.
+const strictCrossAttempt = await strictPlugin.tool?.record_review?.execute(
+	{ reviewer: "cross-root", summary: strictSummary, passed: true, directory: strictRepo },
+	{ sessionID: "s-strict-cross", worktree: root, directory: root } as any,
+);
+const strictCrossAudit = getRecentAuditEntries(20).find((entry) => entry.tool === "record_review.verdict" && entry.sessionID === "s-strict-cross");
+check("strict mode: the knob follows the reviewed workspace, not the caller's repo", typeof strictCrossAttempt === "string" && strictCrossAttempt.includes("rejected") && strictCrossAttempt.includes("requireSubagentReview") && !strictCrossAttempt.includes("APPROVED"));
+check("strict mode: cross-repo root approval audited as subagent_recorder_required", strictCrossAudit?.reason === "subagent_recorder_required");
+
+// Env override: =0 disables the knob even when project config enables it
+process.env.WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW = "0";
+const strictEnvOff = await strictPlugin.tool?.record_review?.execute(
+	{ reviewer: "env-off-root", summary: strictSummary, passed: true },
+	{ sessionID: "s-strict-root", worktree: strictRepo, directory: strictRepo } as any,
+);
+check("strict mode env off: WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=0 overrides the enabled project config", typeof strictEnvOff === "string" && strictEnvOff.includes("APPROVED"));
+delete process.env.WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW;
+
+rmSync(strictRepo, { recursive: true, force: true });
+resetReviewState();
+
+// Environment overrides follow the requireReview pattern; the default keeps
+// root-session relay recording allowed without the knob.
+const relaxedRepo = join(root, "wg-review-relaxed");
+mkdirSync(relaxedRepo, { recursive: true });
+spawnSync("git", ["init", "-b", "feature/relaxed-recorder"], { cwd: relaxedRepo });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: relaxedRepo });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: relaxedRepo });
+writeFileSync(join(relaxedRepo, "code.txt"), "base\n");
+spawnSync("git", ["add", "code.txt"], { cwd: relaxedRepo });
+spawnSync("git", ["commit", "-m", "base"], { cwd: relaxedRepo });
+process.env.WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW = "1";
+const relaxedEnvAttempt = await strictPlugin.tool?.record_review?.execute(
+	{ reviewer: "self-approved", summary: strictSummary, passed: true },
+	{ sessionID: "s-relaxed-root", worktree: relaxedRepo, directory: relaxedRepo } as any,
+);
+check("strict recorder env override: WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW=1 applies without project config", typeof relaxedEnvAttempt === "string" && relaxedEnvAttempt.includes("rejected") && relaxedEnvAttempt.includes("subagent"));
+const relaxedEnvStatus = JSON.parse(String(await strictPlugin.tool?.guard_status?.execute({ directory: relaxedRepo }, { sessionID: "s-relaxed-root", worktree: relaxedRepo, directory: relaxedRepo } as any)));
+check("strict recorder env override: status echoes the forced requirement", relaxedEnvStatus.projectConfig?.requireSubagentReview === true);
+delete process.env.WORKFLOW_GUARD_REQUIRE_SUBAGENT_REVIEW;
+const relaxedDefault = await strictPlugin.tool?.record_review?.execute(
+	{ reviewer: "relayed-reviewer", summary: strictSummary, passed: true },
+	{ sessionID: "s-relaxed-root", worktree: relaxedRepo, directory: relaxedRepo } as any,
+);
+check("strict recorder default: root-session relay recording stays allowed without the knob", typeof relaxedDefault === "string" && relaxedDefault.includes("APPROVED"));
+rmSync(relaxedRepo, { recursive: true, force: true });
+resetReviewState();
+
 // Event hook handles permission events
 if (typeof customPlugin.event === "function") {
 	await customPlugin.event({
@@ -4254,6 +4591,80 @@ check("project-memory initialization failure leaves core guard hooks active", ty
 if (prevDataHome === undefined) delete process.env.XDG_DATA_HOME;
 else process.env.XDG_DATA_HOME = prevDataHome;
 
+// Loaded plugin version visibility: OpenCode resolves configured bare plugin
+// names through Node's parent-directory lookup from its configuration
+// location, so the loaded copy can silently differ from a globally
+// npm-installed one (observed on-device: npm i -g updates ignored while a
+// home-level pnpm node_modules copy kept loading). The version is therefore
+// surfaced in guard_status and in the startup app log.
+console.log("- Git hygiene snapshot -");
+const hygieneRepo = join(root, "wg-hygiene");
+mkdirSync(hygieneRepo, { recursive: true });
+const hgit = (args: string[]): string => {
+	const res = spawnSync("git", args, { cwd: hygieneRepo, encoding: "utf8" });
+	if (res.status !== 0) throw new Error(`git ${args.join(" ")} failed: ${res.stderr}`);
+	return res.stdout;
+};
+hgit(["init", "-b", "main"]);
+hgit(["config", "user.email", "test@test.local"]);
+hgit(["config", "user.name", "Test Runner"]);
+writeFileSync(join(hygieneRepo, "base.txt"), "base\n");
+hgit(["add", "base.txt"]);
+hgit(["commit", "-m", "base"]);
+hgit(["switch", "-c", "feature/done"]);
+writeFileSync(join(hygieneRepo, "done.txt"), "done\n");
+hgit(["add", "done.txt"]);
+hgit(["commit", "-m", "done work"]);
+hgit(["switch", "main"]);
+hgit(["merge", "--ff-only", "feature/done"]);
+hgit(["switch", "-c", "feature/open"]);
+writeFileSync(join(hygieneRepo, "open.txt"), "open\n");
+hgit(["add", "open.txt"]);
+hgit(["commit", "-m", "open work"]);
+// Prunable worktree: register one, then delete its directory (crashed-add
+// simulation) so the admin entry stays behind.
+hgit(["worktree", "add", join(root, "wg-hygiene-wt"), "feature/done"]);
+rmSync(join(root, "wg-hygiene-wt"), { recursive: true, force: true });
+const hygieneStatus = JSON.parse(String(await customPlugin.tool?.guard_status?.execute({ directory: hygieneRepo }, { sessionID: "s-hygiene", worktree: hygieneRepo, directory: hygieneRepo } as any)));
+check("guard_status exposes the git hygiene snapshot", typeof hygieneStatus.gitHygiene === "object" && hygieneStatus.gitHygiene !== null);
+check("hygiene lists merged local branches excluding the current and unmerged", Array.isArray(hygieneStatus.gitHygiene.mergedLocalBranches) && hygieneStatus.gitHygiene.mergedLocalBranches.includes("feature/done") && !hygieneStatus.gitHygiene.mergedLocalBranches.includes("feature/open") && !hygieneStatus.gitHygiene.mergedLocalBranches.includes("main"));
+check("hygiene counts prunable worktree admin entries", hygieneStatus.gitHygiene.prunableWorktreeCount === 1);
+check("hygiene omits base-behind without a remote", hygieneStatus.gitHygiene.baseBehind === undefined);
+// The list is capped while the count reflects reality.
+for (let i = 0; i < 12; i++) {
+	hgit(["switch", "main"]);
+	hgit(["switch", "-c", `feature/merged-${i}`]);
+	writeFileSync(join(hygieneRepo, `merged-${i}.txt`), `${i}\n`);
+	hgit(["add", `merged-${i}.txt`]);
+	hgit(["commit", "-m", `merged ${i}`]);
+	hgit(["switch", "main"]);
+	hgit(["merge", "--ff-only", `feature/merged-${i}`]);
+}
+// End on a merged, non-base current branch: the current-branch filter must
+// exclude it from the merged list independently of the base filter.
+hgit(["switch", "feature/merged-11"]);
+const cappedStatus = JSON.parse(String(await customPlugin.tool?.guard_status?.execute({ directory: hygieneRepo }, { sessionID: "s-hygiene-capped", worktree: hygieneRepo, directory: hygieneRepo } as any)));
+check("hygiene branch list is capped, counts reality, and excludes the merged current branch", cappedStatus.gitHygiene.mergedLocalBranchCount === 12 && cappedStatus.gitHygiene.mergedLocalBranches.length === 10 && !cappedStatus.gitHygiene.mergedLocalBranches.includes("feature/merged-11") && cappedStatus.gitHygiene.mergedLocalBranches.includes("feature/merged-10"));
+rmSync(hygieneRepo, { recursive: true, force: true });
+const hygieneNonGit = mkdtempSync(join(tmpdir(), "wg-hygiene-nongit-"));
+const nonGitStatus = JSON.parse(String(await customPlugin.tool?.guard_status?.execute({ directory: hygieneNonGit }, { sessionID: "s-hygiene-nongit", worktree: hygieneNonGit, directory: hygieneNonGit } as any)));
+check("hygiene snapshot is null outside a git repository", nonGitStatus.gitHygiene === null);
+rmSync(hygieneNonGit, { recursive: true, force: true });
+
+console.log("- Loaded plugin version visibility -");
+const expectedVersion = String((JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }).version);
+check("loadedPluginVersion reads the adjacent package manifest", loadedPluginVersion() === expectedVersion);
+check("loadedPluginVersion fails soft for an unreadable manifest", loadedPluginVersion(pathToFileURL(join(root, "wg-version-none", "src", "workflow-guard.ts")).href) === undefined);
+const versionStatus = JSON.parse(String(await customPlugin.tool?.guard_status?.execute({ directory: root }, { sessionID: "s-version", worktree: root, directory: root } as any)));
+check("guard_status exposes the loaded plugin version", versionStatus.pluginVersion === expectedVersion);
+const versionLogs: string[] = [];
+await WorkflowGuard({
+	directory: root,
+	worktree: root,
+	client: { app: { log: async (opts: { body: { message: string } }) => { versionLogs.push(opts.body.message); } } } as any,
+} as any);
+check("startup app log states the loaded plugin version", versionLogs.some((message) => message.startsWith(`Workflow Guard v${expectedVersion} plugin initialized for ${root}; `) && message.includes("managed config")));
+
 console.log("- live control-plane paths (tier port: config-path facts) -");
 const liveBase = mkdtempSync(join(tmpdir(), "wg-lcp-base-"));
 const livePlane = join(liveBase, ".config", "open" + "code");