opencode-workflow-guard 1.11.0 → 1.12.1

package/docs/policies.md

@@ -85,7 +85,7 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 - With project `recoveryCheckpoints: true`, or the `autonomous` operation profile unless explicitly overridden, genuine root-session user runs capture a private Git checkpoint before agent work starts. Checkpoints preserve tracked and untracked state without using the user's stash list; subagents and generated continuation prompts do not replace them. At `session.idle`, the run's resulting workspace fingerprint is recorded before automatic continuation. `guard_recovery_restore` is provenance-bound to the same root session and refuses restoration after any intervening workspace change. Operation profiles only set optional workflow defaults and cannot weaken core safety policies.
 - Automatic continuation remains synthetic. By default, an eligible root session with unfinished owned todos briefly waits for OpenCode's native asynchronous title generation before that continuation is sent; set `titleSettleWorkaround: false` to opt out. The bounded wait never rewrites titles or provider/model parameters.
 - **Git State & Snapshot Binding:** Verification evidence records the current git commit hash (`git rev-parse HEAD`) and working tree status. If unverified edits or index modifications occur after verification, fresh verification is enforced.
-- **Durable Disk Cache:** Passing verification results are cached to `~/.local/state/opencode/workflow-guard/last-verify.json`, allowing session restarts and multi-agent handoffs to retain valid verification evidence without redundant test runs. Durable evidence is **workspace-bound**: a cached result is only accepted for the workspace that produced it, so a passing run in one project can never satisfy finalization in another.
+- **Durable Disk Cache:** Passing verification results (`~/.local/state/opencode/workflow-guard/last-verify.json`) and passing secondary review approvals (`~/.local/state/opencode/workflow-guard/last-review.json`) are cached to disk, allowing session restarts and multi-agent handoffs to retain valid verification and review evidence without redundant test runs. Durable evidence is **workspace-bound**: a cached result is only accepted for the workspace that produced it, so a passing run in one project can never satisfy finalization in another.
 - If verification fails, finalization is blocked with a structured summary of error markers, stack traces, and failure output.
 - OpenCode's current `lsp.client.diagnostics` event identifies the server and path but does not expose the diagnostics themselves, so the guard deliberately does not claim an LSP-clean finalization gate until the SDK provides a supported diagnostics source.
 - The verify command is **disabled** when `WORKFLOW_GUARD_VERIFY` is empty (`""`).
@@ -108,11 +108,13 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 
 ### 15. Compaction State & Policy Context Preservation
 - Integrates with OpenCode's `experimental.session.compacting` hook to inject bounded active policy state into `output.context` before context summarization:
+  - Caps injected continuity context at 8,000 characters, preserving operational guard state first and filling the remaining budget with active tasks, review follow-ups, and fresh local project memory.
   - Active `todowrite` tasks with status badges and subagent hierarchy attribution.
   - Active Git branch name and protected branch status.
   - Test verification status (passed/failed, test command, and commit hash).
   - Secondary review verdicts (reviewer name and approval status).
   - Uncommitted mutation counts.
+- Compacted project-memory context points back to `project_memory_search` for deeper historical retrieval instead of attempting to embed the full durable store.
 - Preserves policy-relevant context across session compactions without assigning, prioritizing, or sequencing tasks for the model.
 
 ### 16. TUI Visual Feedback & Static Status Badge
@@ -155,8 +157,13 @@ It is a policy and enforcement layer, not an agent harness. Policies may constra
 - Mismatches (failing verification, stale evidence due to mutations after the verify run, or no evidence at all) are journaled to the audit trail and logged at info level. This is **observability, not gating**: the response is never blocked, but a confident wrap-up cannot silently contradict a failing or absent verification state.
 - Uses the `experimental.text.complete` hook; claim detection is a conservative phrase heuristic to avoid false positives on casual wording.
 
-### Tool Description Honesty
-- Via the `tool.definition` hook, the guard enriches the `todowrite` tool's description with its replacement-list lifecycle and finalization gates (including verification evidence required after the last mutation), so the model is not surprised by preventable lifecycle blocks. Other tools are untouched, and the enrichment is idempotent.
+### Tool Description Honesty & Cross-Model Adherence
+- Via the `tool.definition` hook, the guard enriches tool descriptions to keep them honest and proactive across all model families (OpenAI, Gemini, Claude, and open-weights models):
+  - `todowrite`: Explains its replacement-list lifecycle, finalization verification gate, and directs models to `guard_next_tasks` for roadmap discovery and `guard_status` for gate checks.
+  - Mutating tools (`edit`, `write`, `apply_patch`): States preconditions (active todo, feature branch, prior read).
+  - `task`: Guides orchestrator agents to isolate parallel mutations with `guard_worktree_create` and conduct secondary reviews via `guard_review_rubric` and `record_review`.
+- Via the `experimental.chat.system.transform` hook, the guard provides concise operational guidelines in the system prompt detailing available guard tools (`guard_next_tasks`, `guard_status`, `guard_review_rubric`, `guard_worktree_create`, `project_memory_*`, `learning_*`, `guard_why`), heavily encouraging open models and Gemini/Claude to proactively use workflow discipline features throughout development.
+- Companion tools feature proactive action triggers ("Proactively call...", "Recommended at session start..."), and `guard_status` returns actionable `recommendedActions` directing models to the exact next step.
 
 ---
 

package/package.json

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

package/src/lib/audit.ts

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

package/src/lib/custom-tools.ts

@@ -29,6 +29,7 @@ import {
 	isReviewRequired,
 	recordMutation,
 	recordReviewResult,
+	resolveEffectiveWorkspace,
 	runWithRuntimeState,
 } from "./state.ts";
 import { getRalphOutcome } from "../policies/continuation.ts";
@@ -46,11 +47,64 @@ import { currentGitBranch, onProtectedBranch } from "../policies/git.ts";
 import { effectiveTodoOwnerSessionID, effectiveTodos, fetchParentSession, fetchParentSessionID, hasActiveTodo } from "../policies/todo.ts";
 
 export function extractReviewFollowups(summary: string): Array<{ severity: "P2" | "P3"; summary: string }> {
-	return summary.split(/\r?\n/).map((line) => ({
-		line: line.trim(),
-		severity: line.match(/(?:^|\s)(P[23])(?:\b|[:])/i)?.[1]?.toUpperCase() as "P2" | "P3" | undefined,
-	})).filter((finding): finding is { line: string; severity: "P2" | "P3" } => Boolean(finding.line && finding.severity))
-		.map((finding) => ({ severity: finding.severity, summary: finding.line }));
+	return summary.split(/\r?\n/).map((line) => {
+		const trimmed = line.trim();
+		const match = trimmed.match(/(?:^|\s)(P[23])(?:\b|[:])/i);
+		const severity = match?.[1]?.toUpperCase() as "P2" | "P3" | undefined;
+		return { line: trimmed, severity };
+	}).filter((finding): finding is { line: string; severity: "P2" | "P3" } => {
+		if (!finding.line || !finding.severity) return false;
+		const rest = finding.line.replace(new RegExp(`^.*?(?:${finding.severity})\\s*[:\\-]?\\s*`, "i"), "").trim();
+		if (!rest || /^(?:none|nil|n\/?a|0|zero|no\s+(?:issues|findings|defects|items|blockers)|clean|passed|ok|none\s+identified)\b/i.test(rest)) {
+			return false;
+		}
+		return true;
+	}).map((finding) => ({ severity: finding.severity, summary: finding.line }));
+}
+
+export function buildWorkflowGuardSystemGuidance(options: {
+	projectMemoryEnabled?: boolean;
+	learningEnabled?: boolean;
+	recoveryCheckpointsEnabled?: boolean;
+	isReadOnly?: boolean;
+}): string {
+	const sections: string[] = [
+		"## Workflow Guard & Operational Tools",
+		"Workflow Guard enforces safe engineering discipline and provides proactive workflow tools:",
+		"- Task Planning: Proactively call `guard_next_tasks` at session start or when planning work to discover repository roadmap, plan, and TODO items. Check `guard_status` to inspect branch protection, mutation count, and outstanding verification/review gates.",
+	];
+
+	if (!options.isReadOnly) {
+		sections.push(
+			"- Review & Verification: Before completing tasks or creating PRs, run tests to produce fresh verification evidence, retrieve the review rubric via `guard_review_rubric` (5 core axes: test integrity, task completeness, cleanliness, security, platform), and spawn a reviewer subagent via `task` that records its verdict with `record_review`.",
+			"- Worktree Isolation: When orchestrating parallel subagent tasks with `task`, call `guard_worktree_create` to prevent concurrent file conflicts, and `guard_worktree_cleanup` when finished.",
+		);
+	}
+
+	sections.push(
+		"- Technical Debt: Inspect open P2/P3 review follow-ups with `guard_review_followups` during planning; resolve fixed items with `guard_review_followup_resolve`.",
+		"- Policy Simulation: If uncertain whether a command or file edit is permitted, simulate it with `guard_why`.",
+	);
+
+	if (options.projectMemoryEnabled) {
+		sections.push(
+			"- Project Memory: Proactively call `project_memory_search` before architectural changes or complex implementations. Record durable lessons, architectural decisions, and repo constraints with `project_memory_record`.",
+		);
+	}
+
+	if (options.learningEnabled) {
+		sections.push(
+			"- Socratic Learning: When facing non-trivial architectural trade-offs, design choices, or debugging breakthroughs, call `learning_checkpoint`. If selected (intervene: true), ask one concise question via `question` before proceeding, and capture observed understanding with `learning_record`.",
+		);
+	}
+
+	if (options.recoveryCheckpointsEnabled) {
+		sections.push(
+			"- Recovery: If workspace state needs rollback to the pre-run checkpoint, use `guard_recovery_restore`.",
+		);
+	}
+
+	return sections.join("\n");
 }
 
 export function createCustomTools(options: {
@@ -80,7 +134,7 @@ export function createCustomTools(options: {
 			}),
 		} : {}),
 		guard_next_tasks: tool({
-			description: "Load durable repository task context when deciding what to work on next. Prefers TODO.md; if absent, discovers conventional roadmap, plan, tasks, backlog, and docs/plans Markdown files.",
+			description: "Load durable repository task context when deciding what to work on next or planning upcoming steps. Proactively call at session start or during planning to discover roadmap, plan, tasks, backlog, and TODO.md files.",
 			args: {},
 			execute: async () => {
 				const sources = discoverPlanningSources(effectiveRoot);
@@ -89,12 +143,12 @@ export function createCustomTools(options: {
 		}),
 		...(projectMemoryEnabled ? {
 			project_memory_search: tool({
-				description: "Search current durable knowledge for this project. Returns concise typed records with provenance; superseded records are excluded.",
+				description: "Search current durable knowledge for this project, including past architectural decisions, constraints, and conventions. Proactively call before starting complex architectural changes, refactors, or new feature implementations.",
 				args: { query: tool.schema.string() },
 				execute: async (args) => projectMemory ? JSON.stringify(args.query.length <= 500 ? searchProjectMemory(projectMemory, args.query, 8) : [], null, 2) : "[workflow-guard] Project memory unavailable; core guard enforcement remains active.",
 			}),
 			project_memory_record: tool({
-				description: "Record a durable project fact, decision, constraint, or lesson when it will matter in future sessions. Do not record transient tool output, secrets, or speculative hypotheses.",
+				description: "Record a durable project fact, decision, constraint, or lesson when it will matter in future sessions. Proactively call after making important architectural choices, discovering tricky repo constraints, or establishing new patterns.",
 				args: { kind: tool.schema.string().describe("fact, decision, constraint, or lesson"), content: tool.schema.string(), paths: tool.schema.array(tool.schema.string()), supersedes: tool.schema.string().optional() },
 				execute: async (args, toolContext) => {
 					if (!projectMemory) return "[workflow-guard] Project memory unavailable; core guard enforcement remains active.";
@@ -105,7 +159,7 @@ export function createCustomTools(options: {
 				},
 			}),
 			project_memory_export: tool({
-				description: "Explicitly promote selected durable project-memory records to the human-readable repo-local .opencode/memory/project-memory.jsonl file. Nothing is exported automatically.",
+				description: "Explicitly promote selected durable project-memory records to the human-readable repo-local .opencode/memory/project-memory.jsonl file. Call when durable knowledge should be committed and shared with the team.",
 				args: { ids: tool.schema.array(tool.schema.string()) },
 				execute: async (args) => {
 					if (!projectMemory) return "[workflow-guard] Project memory unavailable; core guard enforcement remains active.";
@@ -114,12 +168,12 @@ export function createCustomTools(options: {
 					return `[workflow-guard] Exported ${count} project-memory record(s) to .opencode/memory/project-memory.jsonl.`;
 				},
 			}),
-			project_memory_import: tool({ description: "Import the fixed repo-local .opencode/memory/project-memory.jsonl file into this project's local working-memory index.", args: {}, execute: async () => projectMemory ? `[workflow-guard] Imported ${importProjectKnowledge(projectMemory, portableMemoryPath, (content) => secretIn(content) !== undefined)} new project-memory record(s).` : "[workflow-guard] Project memory unavailable; core guard enforcement remains active." }),
+			project_memory_import: tool({ description: "Import the repo-local .opencode/memory/project-memory.jsonl file into this project's local working-memory index. Call to synchronize local project memory with shared repository records.", args: {}, execute: async () => projectMemory ? `[workflow-guard] Imported ${importProjectKnowledge(projectMemory, portableMemoryPath, (content) => secretIn(content) !== undefined)} new project-memory record(s).` : "[workflow-guard] Project memory unavailable; core guard enforcement remains active." }),
 		} : {}),
 		...(learningEnabled ? {
-			learning_profile: tool({ description: "Inspect the local evidence-based learner profile so teaching can build on demonstrated knowledge without assuming unobserved concepts are gaps.", args: {}, execute: async () => JSON.stringify(loadLearnerProfile(), null, 2) }),
+			learning_profile: tool({ description: "Inspect the local evidence-based learner profile so explanations and teaching can build on demonstrated knowledge without assuming unobserved concepts are gaps.", args: {}, execute: async () => JSON.stringify(loadLearnerProfile(), null, 2) }),
 			learning_checkpoint: tool({
-				description: "At a high-value design decision, debugging moment, or important new concept, rank candidate Socratic learning opportunities. If one is selected, ask one concise question before continuing the work; do not turn routine syntax into a lesson.",
+				description: "At a high-value design decision, debugging moment, or important new concept, rank candidate Socratic learning opportunities. Proactively call when encountering non-trivial architectural trade-offs, design choices, or tricky bugs. If selected (intervene: true), ask one concise question via question before continuing; do not turn routine syntax into a lesson.",
 				args: { opportunities: tool.schema.array(tool.schema.object({ type: tool.schema.string().describe("design, debugging, or new-concept"), concept: tool.schema.string().describe("Transferable engineering concept"), relevance: tool.schema.number().describe("Current-task relevance from 0 to 1"), consequence: tool.schema.number().describe("Decision consequence from 0 to 1") })) },
 				execute: async (args, toolContext) => {
 					const valid = args.opportunities.slice(0, 20).filter((candidate): candidate is typeof candidate & { type: "design" | "debugging" | "new-concept" } => (candidate.type === "design" || candidate.type === "debugging" || candidate.type === "new-concept") && candidate.concept.length > 0 && candidate.concept.length <= 100 && candidate.relevance >= 0 && candidate.relevance <= 1 && candidate.consequence >= 0 && candidate.consequence <= 1);
@@ -131,7 +185,7 @@ export function createCustomTools(options: {
 				},
 			}),
 			learning_record: tool({
-				description: "Record concise evidence from a real Socratic interaction after observing the learner's reasoning. Record what was demonstrated, not a grade or an inferred deficit.",
+				description: "Record concise evidence from a real Socratic interaction after observing the learner's reasoning and response to a learning checkpoint question. Record what was demonstrated, not a grade or an inferred deficit.",
 				args: { concept: tool.schema.string(), kind: tool.schema.string().describe("exposed, developing, demonstrated, independent, critique, or needs-reinforcement"), summary: tool.schema.string().describe("Short factual description of observed reasoning") },
 				execute: async (args, toolContext) => {
 					const validKinds = new Set(["exposed", "developing", "demonstrated", "independent", "critique", "needs-reinforcement"]);
@@ -151,9 +205,13 @@ export function createCustomTools(options: {
 			}),
 		} : {}),
 		guard_status: tool({
-			description: "Inspect active guardrails, current branch protection, and verification/review status.", args: {},
-			execute: async (_args, toolContext) => {
-				const root = effectiveRoot; const branch = currentGitBranch(root) ?? "unknown"; const isProtected = onProtectedBranch(root); const lastV = getLastVerifyResultForWorkspace(root); const lastR = getLastReviewResultForWorkspace(root); const lastMut = getWorkspaceMutationTimestamp(root); const cfg = loadProjectConfig(root);
+			description: "Inspect active guardrails, current branch protection, mutation count, outstanding verification/review requirements, and ralph status. Proactively call at session start and before completing tasks or creating PRs.",
+			args: {
+				directory: tool.schema.string().optional().describe("Target repository directory to inspect (defaults to active session directory or workspace root)"),
+			},
+			execute: async (args, toolContext) => {
+				const root = await resolveEffectiveWorkspace({ sessionID: toolContext.sessionID, directory: args?.directory, fallback: toolContext.worktree || toolContext.directory || effectiveRoot });
+				const branch = currentGitBranch(root) ?? "unknown"; const isProtected = onProtectedBranch(root); const lastV = getLastVerifyResultForWorkspace(root); const lastR = getLastReviewResultForWorkspace(root); const lastMut = getWorkspaceMutationTimestamp(root); const cfg = loadProjectConfig(root);
 				const subject = { workspace: projectRootKey(root), commitHash: getCurrentGitCommitHash(root), worktreeFingerprint: getGitWorktreeFingerprint(root) };
 				const verifyEvidence = lastV ? verificationEvidence(lastV) : undefined;
 				const reviewEvidenceRecord = lastR ? reviewEvidence(lastR) : undefined;
@@ -167,15 +225,38 @@ export function createCustomTools(options: {
 					...(reviewRequired && !reviewFresh ? ["review"] : []),
 					...(documentationRequired && !branchHasDocumentationChange(root) ? ["documentation"] : []),
 				];
+				const recommendedActions: string[] = [];
+				if (outstandingRequirements.includes("verification")) {
+					recommendedActions.push(verifyCommand ? `Execute test verification command '${verifyCommand}' to produce fresh verification evidence.` : "Run project tests to establish fresh verification evidence.");
+				}
+				if (outstandingRequirements.includes("review")) {
+					recommendedActions.push("Call guard_review_rubric to retrieve the 5-axis review rubric, then spawn a secondary reviewer subagent via task to evaluate changes and record verdict with record_review.");
+				}
+				if (outstandingRequirements.includes("documentation")) {
+					recommendedActions.push("Update documentation files (e.g. README.md, docs/) to satisfy the documentation gate before opening a PR.");
+				}
+				let openFollowupsCount = 0;
+				try { openFollowupsCount = followupStore ? listReviewFollowups(followupStore, "open", 10).length : 0; } catch {}
+				if (openFollowupsCount > 0) {
+					recommendedActions.push(`Inspect ${openFollowupsCount} open P2/P3 review follow-up(s) with guard_review_followups and resolve with guard_review_followup_resolve once addressed.`);
+				}
+				if (recommendedActions.length === 0) {
+					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, 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({ 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);
 			},
 		}),
-		guard_audit: tool({ description: "View recent audit entries recorded by opencode-workflow-guard.", 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.", 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) }),
+		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.",
-			args: { reviewer: tool.schema.string().describe("Identifier/name of the reviewer subagent"), summary: tool.schema.string().describe("Review findings summary across the 5 core review axes"), passed: tool.schema.boolean().describe("True if change is approved, false if changes requested") },
+			description: "Record a secondary reviewer agent's approval or critique of the current changes. The summary must reference the 5 core review axes from guard_review_rubric (test integrity, task completeness, cleanliness, security, platform).",
+			args: {
+				reviewer: tool.schema.string().describe("Identifier/name of the reviewer subagent"),
+				summary: tool.schema.string().describe("Review findings summary across the 5 core review axes"),
+				passed: tool.schema.boolean().describe("True if change is approved, false if changes requested"),
+				directory: tool.schema.string().optional().describe("Target repository directory being reviewed (defaults to parent session's repository or active directory)"),
+			},
 			execute: async (args, toolContext) => {
 				const auditVerdict = (verdict: "approved" | "changes_requested" | "rejected", reason: string) => audit({ ts: new Date().toISOString(), sessionID: toolContext.sessionID, tool: "record_review.verdict", decision: verdict === "rejected" ? "block" : "allow", phase: "event", reason, evidence: { reviewVerdict: verdict } });
 				const parentSessionID = await runWithRuntimeState(effectiveRoot, client, () => fetchParentSessionID(toolContext.sessionID));
@@ -184,27 +265,33 @@ export function createCustomTools(options: {
 				const referenced = axesRefs.filter((axis) => args.summary.toLowerCase().includes(axis));
 				if (referenced.length < 3) { auditVerdict("rejected", "insufficient_rubric_axes"); return `[workflow-guard] Review rejected: summary must reference the review axes (found ${referenced.length}/5). Call guard_review_rubric to get the rubric, evaluate each axis, and include findings per axis in the summary.`; }
 				if (args.passed && /(?:^|\s)(?:\[p[01]\]|p[01]\s*:\s*(?:blocker|defect|vulnerability|error|bug|issue)|p[01]\s+blocker)/i.test(args.summary)) { auditVerdict("rejected", "approval_contains_blocker"); return "[workflow-guard] Review rejected: cannot record approval when P0 or P1 blockers are flagged in findings. Resolve all P0/P1 issues before approving or record review with passed=false."; }
-				recordReviewResult(args.reviewer, args.summary, args.passed, parentSessionID, toolContext.worktree || toolContext.directory);
-				if (followupStore && !secretIn(args.summary)) for (const finding of extractReviewFollowups(args.summary)) recordReviewFollowup(followupStore, { severity: finding.severity, summary: finding.summary, reviewer: args.reviewer, sessionID: toolContext.sessionID, commit: getCurrentGitCommitHash(effectiveRoot) });
+				const reviewWorkspace = await resolveEffectiveWorkspace({ sessionID: toolContext.sessionID, directory: args.directory, fallback: toolContext.worktree || toolContext.directory || effectiveRoot });
+				recordReviewResult(args.reviewer, args.summary, args.passed, parentSessionID, reviewWorkspace);
+				if (followupStore && !secretIn(args.summary)) for (const finding of extractReviewFollowups(args.summary)) recordReviewFollowup(followupStore, { severity: finding.severity, summary: finding.summary, reviewer: args.reviewer, sessionID: toolContext.sessionID, commit: getCurrentGitCommitHash(reviewWorkspace) });
 				auditVerdict(args.passed ? "approved" : "changes_requested", args.passed ? "approved" : "changes_requested");
 				return args.passed ? `[workflow-guard] Review recorded as APPROVED by ${args.reviewer}.` : `[workflow-guard] Review recorded as CHANGES REQUESTED by ${args.reviewer}.`;
 			},
 		}),
-		guard_review_followups: tool({ description: "List durable local P2/P3 review follow-ups for this project. Open findings are technical debt that should be addressed rather than indefinitely deferred.", args: {}, execute: async () => JSON.stringify(followupStore ? listReviewFollowups(followupStore) : [], null, 2) }),
+		guard_review_followups: tool({ description: "List durable local P2/P3 review follow-ups (technical debt) for this project. Proactively check during planning or before final verification to address open findings.", args: {}, execute: async () => JSON.stringify(followupStore ? listReviewFollowups(followupStore) : [], null, 2) }),
 		guard_review_followup_resolve: tool({ description: "Resolve a durable local review follow-up after the underlying issue has been fixed and verified.", args: { id: tool.schema.string() }, execute: async (args) => followupStore && resolveReviewFollowup(followupStore, args.id) ? `[workflow-guard] Review follow-up ${args.id} resolved.` : `[workflow-guard] Review follow-up ${args.id} was not open or was not found.` }),
 		guard_review_rubric: tool({
-			description: "Get the secondary-review rubric for the current branch diff. The orchestrator calls this, spawns a reviewer subagent with the rubric as the prompt, then the reviewer records its verdict via record_review.", args: { base: tool.schema.string().optional().describe("Base ref to diff against (default: origin/main, origin/master, main)") },
-			execute: async (args) => {
+			description: "Get the secondary-review rubric for the current branch diff across 5 core review axes (test integrity, task completeness, cleanliness, security, platform). The orchestrator should call this before finalizing work or creating a PR, then spawn a reviewer subagent with the rubric as the prompt, which records its verdict via record_review.",
+			args: {
+				base: tool.schema.string().optional().describe("Base ref to diff against (default: origin/main, origin/master, main)"),
+				directory: tool.schema.string().optional().describe("Target repository directory (defaults to active session directory or workspace root)"),
+			},
+			execute: async (args, toolContext) => {
 				const sanitizedBase = typeof args.base === "string" && !args.base.startsWith("-") && !/[\s;'"\0]/.test(args.base) ? args.base : undefined;
 				const bases = sanitizedBase ? [sanitizedBase] : ["origin/main", "origin/master", "main", "master"];
+				const rubricWorkspace = await resolveEffectiveWorkspace({ sessionID: toolContext?.sessionID, directory: args?.directory, fallback: toolContext?.worktree || toolContext?.directory || effectiveRoot });
 				let diffText = "";
-				for (const base of bases) { const res = spawnSync("git", ["diff", "--", `${base}...HEAD`], { cwd: getWorkspaceRoot(), encoding: "utf8", timeout: 10_000 }); if (res.status === 0 && res.stdout.trim()) { diffText = res.stdout; break; } }
-				if (!diffText) { const last = spawnSync("git", ["diff", "--", "HEAD~1"], { cwd: getWorkspaceRoot(), encoding: "utf8", timeout: 10_000 }); diffText = last.status === 0 ? last.stdout : "(no diff available)"; }
+				for (const base of bases) { const res = spawnSync("git", ["diff", "--", `${base}...HEAD`], { cwd: rubricWorkspace, encoding: "utf8", timeout: 10_000 }); if (res.status === 0 && res.stdout.trim()) { diffText = res.stdout; break; } }
+				if (!diffText) { const last = spawnSync("git", ["diff", "--", "HEAD~1"], { cwd: rubricWorkspace, encoding: "utf8", timeout: 10_000 }); diffText = last.status === 0 ? last.stdout : "(no diff available)"; }
 				return buildReviewRubric(diffText);
 			},
 		}),
 		guard_worktree_create: tool({
-			description: "Create an isolated git worktree directory for concurrent subagent execution.", args: { branch: tool.schema.string().describe("Branch name for the isolated worktree (e.g. 'feat/subagent-task')"), baseBranch: tool.schema.string().optional().describe("Base branch to branch off of (defaults to HEAD)") },
+			description: "Create an isolated git worktree directory for concurrent subagent execution. Proactively call when launching parallel tasks/subagents to prevent file collision and maintain branch isolation.", args: { branch: tool.schema.string().describe("Branch name for the isolated worktree (e.g. 'feat/subagent-task')"), baseBranch: tool.schema.string().optional().describe("Base branch to branch off of (defaults to HEAD)") },
 			execute: async (args, toolContext) => {
 				const todos = await effectiveTodos(toolContext.sessionID); if (todos !== undefined && !hasActiveTodo(todos)) return "[workflow-guard] Blocked: worktree creation with no active todo item. Break the request down with todowrite first, then create worktrees.";
 				const toolRoot = toolContext.worktree || toolContext.directory || effectiveRoot; const res = createGitWorktree(args.branch, args.baseBranch ?? "HEAD", toolRoot); if (!res.success) return `[workflow-guard] Failed to create worktree: ${res.error}`;
@@ -212,7 +299,7 @@ export function createCustomTools(options: {
 			},
 		}),
 		guard_worktree_cleanup: tool({
-			description: "Commit a final snapshot and remove an isolated git worktree directory.", args: { worktreePath: tool.schema.string().describe("Path of the worktree directory to clean up") },
+			description: "Commit a final snapshot and remove an isolated git worktree directory. Call to clean up worktrees created with guard_worktree_create after subagent tasks complete.", args: { worktreePath: tool.schema.string().describe("Path of the worktree directory to clean up") },
 			execute: async (args, toolContext) => {
 				const todos = await effectiveTodos(toolContext.sessionID); if (todos !== undefined && !hasActiveTodo(todos)) return "[workflow-guard] Blocked: worktree cleanup with no active todo item. Break the request down with todowrite first, then clean up worktrees.";
 				const toolRoot = toolContext.worktree || toolContext.directory || effectiveRoot; const res = cleanupGitWorktree(args.worktreePath, toolRoot); if (!res.success) return `[workflow-guard] Failed to clean up worktree: ${res.error}`;

package/src/lib/evidence.ts

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

package/src/lib/guard-dispatcher.ts

@@ -1,8 +1,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { loadVerifyCache } from "./audit.ts";
+import { loadReviewCache, loadVerifyCache } from "./audit.ts";
 import { isEvidenceFresh, reviewEvidence, verificationEvidence } from "./evidence.ts";
-import { projectRootKey } from "./project-config.ts";
+import { findGitRoot, isSameGitRepo, projectRootKey } from "./project-config.ts";
 import {
 	getLastReviewResult,
 	getSdkClient,
@@ -435,7 +435,13 @@ export async function guardToolCallImpl(
 				if (mergedStatus.merged) preflightFailures.push(mergedStatus.reason ?? "Branch is already merged or closed.");
 			}
 			if (isReviewRequired(prRoot)) {
-				const review = context?.sessionID ? (sessionReviews.get(context.sessionID) ?? getLastReviewResult()) : getLastReviewResult();
+				let review = context?.sessionID ? (sessionReviews.get(context.sessionID) ?? getLastReviewResult()) : getLastReviewResult();
+				if (!review) {
+					const diskCached = loadReviewCache();
+					if (diskCached && diskCached.passed && diskCached.workspace && (projectRootKey(diskCached.workspace) === projectRootKey(prRoot) || isSameGitRepo(diskCached.workspace, prRoot))) {
+						review = diskCached;
+					}
+				}
 				const reviewMatchesContext = review?.passed === true && isEvidenceFresh(reviewEvidence(review), { workspace: projectRootKey(prRoot), commitHash: getCurrentGitCommitHash(prRoot), worktreeFingerprint: getGitWorktreeFingerprint(prRoot), sessionID: review.targetSessionID }, 0) && (!review.targetSessionID || review.targetSessionID === context?.sessionID);
 				if (!reviewMatchesContext) preflightFailures.push("Passing secondary review approval is required; invoke a secondary review subagent and record approval with record_review.");
 			}

package/src/lib/project-config.ts

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

package/src/lib/state.ts

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

package/src/policies/continuation.ts

@@ -73,7 +73,7 @@ export async function continueUnfinishedSession(sessionID: string, settleTitle =
 		const session = getSdkClient()?.session;
 		if (typeof session?.promptAsync !== "function") return false;
 
-		const messageID = `workflow-guard-${randomUUID()}`;
+		const messageID = `msg_wg_${randomUUID().replace(/-/g, "")}`;
 		state.counts.set(sessionID, count + 1);
 		if (ralph) state.ralphOutcomes.set(sessionID, "running");
 		const generatedIDs = state.generatedMessageIDs.get(sessionID) ?? new Set<string>();
@@ -97,7 +97,7 @@ export async function continueUnfinishedSession(sessionID: string, settleTitle =
 					messageID,
 					parts: [{
 						type: "text",
-						text: `Workflow Guard: unfinished todos remain. Continue working through them.${tasksSummary}\nIf you need user input, use the question tool instead of ending the run.`,
+						text: `Workflow Guard: unfinished todos remain. Continue working through them.${tasksSummary}\nIf you need user input, use the question tool instead of ending the run. Check guard_status for outstanding verification/review requirements, and guard_review_rubric before final completion.`,
 						synthetic: true,
 					}],
 				},

package/src/workflow-guard.ts

@@ -18,10 +18,10 @@ import { beginReadObservation, clearReadFingerprints, recordSuccessfulRead, stal
 import { ToolInvocationLifecycle } from "./lib/tool-lifecycle.ts";
 import { ToolOutcomeTracker, type ToolOutcomePart } from "./lib/tool-outcomes.ts";
 import { guardToolCallImpl, isReadOnlyRole } from "./lib/guard-dispatcher.ts";
-import { createCustomTools } from "./lib/custom-tools.ts";
+import { createCustomTools, buildWorkflowGuardSystemGuidance } from "./lib/custom-tools.ts";
 import type { PolicyDecision, TodoSdkClient } from "./lib/types.ts";
 export { isReadOnlyRole } from "./lib/guard-dispatcher.ts";
-export { extractReviewFollowups } from "./lib/custom-tools.ts";
+export { extractReviewFollowups, buildWorkflowGuardSystemGuidance } from "./lib/custom-tools.ts";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 export type {
@@ -74,10 +74,14 @@ import {
 	getLearningInterventionBudget,
 	recordReviewResult,
 	getLastReviewResult,
+	getLastReviewResultForWorkspace,
 	resetReviewState,
 	sessionReviews,
+	setSessionWorkspace,
+	getSessionWorkspace,
+	resolveEffectiveWorkspace,
 } from "./lib/state.ts";
-import { loadProjectConfig, reloadProjectConfig, stripJsonComments } from "./lib/project-config.ts";
+import { findGitRoot, isSameGitRepo, loadProjectConfig, reloadProjectConfig, stripJsonComments } from "./lib/project-config.ts";
 
 export {
 	setWorkspaceRoot,
@@ -101,11 +105,18 @@ export {
 	getLearningInterventionBudget,
 	recordReviewResult,
 	getLastReviewResult,
+	getLastReviewResultForWorkspace,
 	resetReviewState,
+	setSessionWorkspace,
+	getSessionWorkspace,
+	resolveEffectiveWorkspace,
+	findGitRoot,
+	isSameGitRepo,
 };
 
 // ── Shared shell/env utilities ───────────────────────────────────────────────
 import {
+	asRecord,
 	extractRecordTargetPath,
 	getCleanEnv,
 	showBlockToast,
@@ -149,14 +160,17 @@ import { ensureProjectMemoryExcluded, getProjectMemoryIdentity, getRecentProject
 import {
 	getAuditFilePath,
 	getVerifyCacheFilePath,
+	getReviewCacheFilePath,
 	persistVerifyCache,
 	loadVerifyCache,
+	persistReviewCache,
+	loadReviewCache,
 	audit,
 	logDecision,
 	summarizeInput,
 } from "./lib/audit.ts";
 
-export { getAuditFilePath, getVerifyCacheFilePath, getVerifyHistoryFilePath, persistVerifyCache, loadVerifyCache, getRecentAuditEntries, getRecentVerifyHistory } from "./lib/audit.ts";
+export { getAuditFilePath, getVerifyCacheFilePath, getReviewCacheFilePath, getVerifyHistoryFilePath, persistVerifyCache, loadVerifyCache, persistReviewCache, loadReviewCache, getRecentAuditEntries, getRecentVerifyHistory } from "./lib/audit.ts";
 export { summarizeInput };
 
 export function managedConfigDiagnostic(platform = process.platform, env: NodeJS.ProcessEnv = process.env): string {
@@ -345,15 +359,40 @@ async function emitBlockFeedback(message: string): Promise<void> {
 	await showBlockToast(message);
 }
 
+export function buildCompactionContext(operationalState: string, priorityBlocks: string[], maxChars = 8_000): string {
+	if (!Number.isFinite(maxChars) || maxChars < 0 || !Number.isInteger(maxChars)) {
+		throw new RangeError("maxChars must be a non-negative finite integer");
+	}
+	const truncate = (value: string, limit: number): string => {
+		let end = Math.min(value.length, limit);
+		if (end > 0 && end < value.length && /[\uD800-\uDBFF]/.test(value[end - 1])) end -= 1;
+		return value.slice(0, end);
+	};
+	let context = truncate(operationalState, maxChars);
+	for (const block of priorityBlocks) {
+		const remaining = maxChars - context.length - 2;
+		if (remaining <= 0) break;
+		context += `\n\n${truncate(block, remaining)}`;
+	}
+	return context;
+}
+
 export const WorkflowGuard: Plugin = async (ctx) => {
 	// Honor worktree if present (e.g. opencode worktrees or devcontainers)
 	// so worktree plugins cannot punch through boundary gates. When the host
 	// reports the filesystem root, use the SDK's actual project worktree instead.
 	const hostRoot = ctx.worktree || ctx.directory || process.cwd();
 	const hostIsFilesystemRoot = resolve(hostRoot) === resolve(hostRoot, "..");
-	const effectiveRoot = hostIsFilesystemRoot && ctx.project?.worktree
+	let effectiveRoot = hostIsFilesystemRoot && ctx.project?.worktree && resolve(ctx.project.worktree) !== resolve(ctx.project.worktree, "..")
 		? ctx.project.worktree
 		: hostRoot;
+	if (resolve(effectiveRoot) === resolve(effectiveRoot, "..")) {
+		const nonRootCandidate = [ctx.directory, process.cwd()].find((p) => typeof p === "string" && resolve(p) !== resolve(p, ".."));
+		if (nonRootCandidate) {
+			const gitRoot = findGitRoot(nonRootCandidate);
+			effectiveRoot = gitRoot ?? nonRootCandidate;
+		}
+	}
 	setWorkspaceRoot(effectiveRoot);
 	setSdkClient(ctx.client);
 	reloadProjectConfig(effectiveRoot);
@@ -416,11 +455,21 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					await emitBlockFeedback(reason);
 					const failureCount = input.sessionID ? toolOutcomes.getFailureCount(input.sessionID) : 0;
 					const circuitBreakerSuffix = failureCount >= 2
-						? "\n\n[Workflow Guard Circuit Breaker: Repeated failures detected in this session. Stop attempting alternative workarounds or shell laundering. Address the required step above directly.]"
+						? "\n\n[Workflow Guard Circuit Breaker: Repeated failures detected in this session. Stop attempting alternative workarounds or shell laundering. Address the required step above directly, or inspect policy details with guard_status or guard_why.]"
 						: "";
 					throw new Error(`[workflow-guard] ${reason}${circuitBreakerSuffix}`);
 				}
 				toolLifecycle.start(input.sessionID, input.callID);
+				if (input.sessionID) {
+					const record = asRecord(args);
+					const workdir = typeof record?.workdir === "string" ? record.workdir : undefined;
+					const filePath = typeof record?.filePath === "string" ? record.filePath : (typeof record?.path === "string" ? record.path : undefined);
+					const candidatePath = workdir ?? filePath ?? toolWorktree;
+					if (candidatePath) {
+						const gitRoot = findGitRoot(candidatePath);
+						if (gitRoot) setSessionWorkspace(input.sessionID, gitRoot);
+					}
+				}
 				if (input.tool === "read") {
 					const target = editTargets(args, toolWorktree)[0];
 					if (target) {
@@ -484,7 +533,7 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					: getLastReviewResult();
 				const mutationCountVal = sessionID ? sessionMutationCount : getMutationCount();
 
-				const contextBlocks: string[] = [];
+				const priorityContextBlocks: string[] = [];
 
 				if (active && active.length > 0) {
 					const lines = active.slice(0, 20).map(
@@ -497,7 +546,7 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 						: sessionID
 							? ` (Session: ${sessionID})`
 							: "";
-					contextBlocks.push(
+					priorityContextBlocks.push(
 						`## Active Tasks${attribution}\n` +
 							lines.join("\n") +
 							"\nComplete tasks efficiently - mark finished items as completed and address remaining ones.",
@@ -523,9 +572,9 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 				try { openFollowups = followupStore ? listReviewFollowups(followupStore, "open", 8) : []; } catch {}
 				if (openFollowups.length > 0) {
 					stateLines.push(`- Open Review Follow-ups: ${openFollowups.length} local P2/P3 item(s)`);
-					contextBlocks.push(`## Review Follow-ups\n${openFollowups.map((item) => `- [${item.severity}:${item.id.slice(0, 8)}] ${item.summary.slice(0, 300)}`).join("\n")}\nTreat these as durable technical debt: address relevant items when practical and resolve them explicitly after verification.`);
+					priorityContextBlocks.push(`## Review Follow-ups\n${openFollowups.map((item) => `- [${item.severity}:${item.id.slice(0, 8)}] ${item.summary.slice(0, 300)}`).join("\n")}\nTreat these as durable technical debt: address relevant items when practical and resolve them explicitly after verification.`);
 				}
-				contextBlocks.push(stateLines.join("\n"));
+				const operationalState = stateLines.join("\n");
 				let projectKnowledge: ReturnType<typeof getRecentProjectMemory> = [];
 				try {
 					const candidates = (projectMemory ? getRecentProjectMemory(projectMemory, 8) : [])
@@ -535,11 +584,11 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 				} catch {}
 				if (projectKnowledge.length > 0) {
 					const lines = projectKnowledge.map((memory) => `- [${memory.kind}:${memory.id.slice(0, 8)}] ${memory.content.slice(0, 300)}`);
-					contextBlocks.push(`## Project Memory\n${lines.join("\n")}\nTreat these as historical project knowledge; verify against current repository state when relevant files have changed.`);
+					priorityContextBlocks.push(`## Project Memory\nUse project_memory_search when deeper historical context is needed. Treat these as historical project knowledge; verify against current repository state when relevant files have changed.\n${lines.join("\n")}`);
 				}
 
 				if (Array.isArray(output?.context)) {
-					output.context.push(contextBlocks.join("\n\n"));
+					output.context.push(buildCompactionContext(operationalState, priorityContextBlocks));
 				}
 			} catch {}
 		},
@@ -611,13 +660,14 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 		// Keep tool descriptions honest: todowrite's description reflects lifecycle
 		// and finalization gates so the model is not surprised by preventable blocks.
 		// Similarly, mutating tools reflect their active-todo, feature-branch, and prior-read requirements.
+		// Subagent orchestration tools reflect worktree isolation and review expectations.
 		"tool.definition": async (input, output) => {
 			if (input.toolID === "todowrite") {
 				const description = typeof output.description === "string" ? output.description : "";
 				if (description.includes("verification evidence")) return;
 				output.description =
 					description +
-					"\n\nWorkflow Guard lifecycle: each todowrite call replaces the complete task list. Preserve every pending/in_progress task in subsequent updates until you explicitly mark it completed or cancelled; do not omit active tasks when adding new work. Marking every task completed triggers the finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply.";
+					"\n\nWorkflow Guard lifecycle: each todowrite call replaces the complete task list. Preserve every pending/in_progress task in subsequent updates until you explicitly mark it completed or cancelled; do not omit active tasks when adding new work. Marking every task completed triggers the finalization gate - fresh verification evidence (test run) is required after the last mutation, and protected-branch/conflict checks apply. Proactively call guard_next_tasks when planning work to discover existing roadmap/TODOs, and guard_status to check outstanding requirements.";
 				return;
 			}
 			if (EDIT_TOOL_NAMES.has(input.toolID)) {
@@ -628,6 +678,30 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					"\n\nWorkflow Guard requirement: Modifications require an active task in todowrite (status pending or in_progress), a feature branch (edits on main/master are blocked), and a prior read of existing files in the current session.";
 				return;
 			}
+			if (input.toolID === "task") {
+				const description = typeof output.description === "string" ? output.description : "";
+				if (description.includes("Workflow Guard subagent guidance")) return;
+				output.description =
+					description +
+					"\n\nWorkflow Guard subagent guidance: When spawning parallel worker subagents, use guard_worktree_create to isolate file mutations in separate worktrees. When conducting code reviews before task completion or PR creation, fetch the rubric with guard_review_rubric and provide it to a reviewer subagent to evaluate and record via record_review.";
+				return;
+			}
+		},
+
+		"experimental.chat.system.transform": async (input, output) => {
+			try {
+				if (!Array.isArray(output?.system)) return;
+				const existing = output.system.join("\n");
+				if (existing.includes("## Workflow Guard & Operational Tools")) return;
+				const isReadOnly = (input as { agent?: string })?.agent ? isReadOnlyRole((input as { agent?: string }).agent!) : false;
+				const guidance = buildWorkflowGuardSystemGuidance({
+					projectMemoryEnabled,
+					learningEnabled,
+					recoveryCheckpointsEnabled: isRecoveryCheckpointsEnabled(effectiveRoot),
+					isReadOnly,
+				});
+				output.system.push(guidance);
+			} catch {}
 		},
 
 		"chat.message": async (input) => {

package/test/test.mts

@@ -12,6 +12,7 @@ import {
 	setWorkspaceRoot,
 	setSdkClient,
 	WorkflowGuard,
+	buildCompactionContext,
 	detectVerifyCommand,
 	runVerify,
 	getCleanEnv,
@@ -35,6 +36,14 @@ import {
 	getRecentAuditEntries,
 	getRecentVerifyHistory,
 	getVerifyHistoryFilePath,
+	getReviewCacheFilePath,
+	loadReviewCache,
+	persistReviewCache,
+	setSessionWorkspace,
+	getSessionWorkspace,
+	resolveEffectiveWorkspace,
+	getLastReviewResultForWorkspace,
+	isSameGitRepo,
 	managedConfigDiagnostic,
 	summarizeInput,
 	extractReviewFollowups,
@@ -565,6 +574,13 @@ check("multi-target tee with an outside path is blocked", blocked(await call("ba
 check("tee --append within workspace is allowed with todos", !(await call("bash", { command: "echo x | tee --append src/a.ts" }, { sessionID: "s-active" })));
 
 console.log("- Compaction focus preservation & TUI toast -");
+const boundedCompaction = buildCompactionContext("## Operational Guard State\n- critical", ["## Active Tasks\n" + "a".repeat(10_000), "## Project Memory\nshould-not-fit"], 500);
+check("compaction packer enforces its total context budget", boundedCompaction.length === 500);
+check("compaction packer preserves mandatory operational state before optional context", boundedCompaction.startsWith("## Operational Guard State\n- critical") && !boundedCompaction.includes("should-not-fit"));
+check("compaction packer preserves the largest valid Unicode prefix", buildCompactionContext("critical \u{1F680}state", [], 10) === "critical ");
+let invalidCompactionBudgetRejected = false;
+try { buildCompactionContext("critical", [], Number.NaN); } catch (error) { invalidCompactionBudgetRejected = error instanceof RangeError; }
+check("compaction packer rejects invalid public budgets", invalidCompactionBudgetRejected);
 let toasts: unknown[] = [];
 const toastClient = {
 	session: fakeClient.session,
@@ -588,6 +604,8 @@ if (typeof compactFn === "function") {
 	await compactFn({ sessionID: "s-active" } as any, compactOutput as any);
 }
 check("compaction hook injects active tasks into output.context", compactOutput.context.length > 0 && (compactOutput.context[0]?.includes("Active Tasks") ?? false));
+check("compaction hook keeps injected continuity context bounded", compactOutput.context.every((context) => context.length <= 8000));
+check("compaction hook preserves operational guard state within its budget", compactOutput.context.some((context) => context.includes("## Operational Guard State") && context.includes("Git Branch:")));
 
 // Blocked tool call emits one in-app warning via tui.showToast.
 toasts = [];
@@ -1899,6 +1917,10 @@ check("guard_status exposes subject-bound evidence references", parsedStatus.las
 check("guard_status exposes effective operation profile without TUI state", parsedStatus.projectConfig.profile === "interactive" && typeof parsedStatus.projectConfig.recoveryCheckpoints === "boolean");
 check("guard_status exposes disabled-by-default Ralph accountability state", parsedStatus.ralph?.enabled === false && parsedStatus.ralph?.maxIterations === 10 && parsedStatus.ralph?.outcome === null);
 check("guard_status exposes bounded outstanding requirements", Array.isArray(parsedStatus.outstandingRequirements) && parsedStatus.outstandingRequirements.every((requirement: unknown) => ["verification", "review", "documentation"].includes(String(requirement))));
+check("guard_status exposes actionable recommended actions", Array.isArray(parsedStatus.recommendedActions) && parsedStatus.recommendedActions.length > 0);
+check("guard_next_tasks description includes proactive trigger", Boolean(customPlugin.tool?.guard_next_tasks?.description.includes("Proactively call")));
+check("project_memory_search description includes proactive trigger", Boolean(customPlugin.tool?.project_memory_search?.description?.includes("Proactively call")));
+check("guard_review_rubric description includes orchestrator trigger", Boolean(customPlugin.tool?.guard_review_rubric?.description?.includes("orchestrator should call")));
 
 const requirementsRoot = mkdtempSync(join(tmpdir(), "wg-status-requirements-"));
 mkdirSync(join(requirementsRoot, ".opencode"), { recursive: true });
@@ -2086,6 +2108,96 @@ const mainReviewToolResult = await customPlugin.tool?.record_review?.execute(
 );
 check("record_review rejects self-approval from main session", typeof mainReviewToolResult === "string" && mainReviewToolResult.includes("rejected"));
 
+// Secondary Review Approval Handoff & Durable Cache Tests
+console.log("- Secondary Review Approval Handoff & Durability -");
+
+// 1. Negative review statements do not create bogus technical debt items
+const negativeFollowups = extractReviewFollowups(
+	"Test integrity: ok. Task completeness: ok. Cleanliness: ok. Security: ok. Platform: ok.\n" +
+	"P2: None\n" +
+	"P3: 0\n" +
+	"P2: N/A\n" +
+	"P3: No issues identified\n" +
+	"P2: 0 defects\n" +
+	"P3: ok\n" +
+	"P2: clean\n" +
+	"P2: memory leak in worker pool"
+);
+check("extractReviewFollowups filters out negative statements and retains real issues", negativeFollowups.length === 1 && negativeFollowups[0]?.summary.includes("memory leak in worker pool"));
+
+// 2. Secondary review approval handoff from subagent to parent session
+const handoffRepo = join(root, "wg-handoff-repo");
+mkdirSync(handoffRepo, { recursive: true });
+spawnSync("git", ["init", "-b", "feature/handoff"], { cwd: handoffRepo });
+spawnSync("git", ["config", "user.email", "test@test.local"], { cwd: handoffRepo });
+spawnSync("git", ["config", "user.name", "Test Runner"], { cwd: handoffRepo });
+writeFileSync(join(handoffRepo, "code.txt"), "initial\n");
+spawnSync("git", ["add", "code.txt"], { cwd: handoffRepo });
+spawnSync("git", ["commit", "-m", "initial"], { cwd: handoffRepo });
+mkdirSync(join(handoffRepo, ".opencode"), { recursive: true });
+writeFileSync(join(handoffRepo, ".opencode", "workflow-guard.json"), JSON.stringify({ requireReview: true }));
+
+// Simulate host root being the filesystem root ("/") while session operates in handoffRepo
+const handoffPlugin = await WorkflowGuard({
+	directory: root,
+	worktree: "/",
+	client: fakeClient as any,
+	project: {} as any,
+	experimental_workspace: {} as any,
+	serverUrl: new URL("http://localhost:4096"),
+	$: undefined as any,
+});
+
+// Parent session sets active workspace in handoffRepo
+setSessionWorkspace("s-handoff-parent", handoffRepo);
+fakeParents.set("s-handoff-reviewer", "s-handoff-parent");
+
+// Before review: guard_status on parent reports review is unsatisfied
+const statusBeforeReview = JSON.parse(String(await handoffPlugin.tool?.guard_status?.execute({}, { sessionID: "s-handoff-parent", worktree: "/", directory: root } as any)));
+check("before review: guard_status reports review in outstandingRequirements", statusBeforeReview.outstandingRequirements.includes("review") && (statusBeforeReview.lastReview === null || statusBeforeReview.lastReview.fresh === false));
+
+// Before review: PR creation is blocked by missing review
+const prBeforeReview = JSON.parse(String(await handoffPlugin.tool?.guard_why?.execute({ tool: "bash", input: { command: "gh pr create --title test --body 'Summary\n\nRelease notes'", workdir: handoffRepo } }, { sessionID: "s-handoff-parent", worktree: "/", directory: root } as any)));
+check("before review: PR creation blocked by review requirement", prBeforeReview.status === "blocked" && prBeforeReview.message.includes("Passing secondary review approval is required"));
+
+// Subagent calls record_review with passed: true (without explicit directory argument)
+const subagentReviewResult = await handoffPlugin.tool?.record_review?.execute(
+	{
+		reviewer: "secondary-reviewer",
+		summary: "Test integrity: all tests pass. Task completeness: complete. Cleanliness: clean diff. Security: zero secrets. Platform: standard.",
+		passed: true,
+	},
+	{ sessionID: "s-handoff-reviewer", agent: "reviewer", worktree: "/", directory: root } as any,
+);
+check("subagent records review approval successfully", typeof subagentReviewResult === "string" && subagentReviewResult.includes("APPROVED"));
+
+// Parent checks guard_status: handoff succeeds!
+const statusAfterReview = JSON.parse(String(await handoffPlugin.tool?.guard_status?.execute({}, { sessionID: "s-handoff-parent", worktree: "/", directory: root } as any)));
+check("secondary review handoff: lastReview.fresh is true in parent session", statusAfterReview.lastReview?.fresh === true && statusAfterReview.lastReview?.passed === true);
+check("secondary review handoff: review removed from outstandingRequirements", !statusAfterReview.outstandingRequirements.includes("review"));
+
+// Parent checks PR creation via guard_why: handoff allows PR creation!
+const prAfterReview = JSON.parse(String(await handoffPlugin.tool?.guard_why?.execute({ tool: "bash", input: { command: "gh pr create --title test --body 'Summary\n\nRelease notes'", workdir: handoffRepo } }, { sessionID: "s-handoff-parent", worktree: "/", directory: root } as any)));
+check("secondary review handoff: PR creation allowed after review approval", prAfterReview.status !== "blocked" && (prAfterReview.status === "allowed" || prAfterReview.code === "remote_state_unchecked"));
+
+// 3. Durable disk cache persistence & recovery
+check("durable review cache file created on disk", existsSync(getReviewCacheFilePath()));
+const loadedDiskReview = loadReviewCache();
+check("loadReviewCache returns valid passing review", loadedDiskReview?.passed === true && loadedDiskReview?.reviewer === "secondary-reviewer");
+
+// Simulate new session / restart: clear in-memory sessionReviews and lastReview
+const memoryClearedStatus = JSON.parse(String(await handoffPlugin.tool?.guard_status?.execute({ directory: handoffRepo }, { sessionID: "s-fresh-session", worktree: "/", directory: root } as any)));
+check("fresh session recovers durable review cache from disk", memoryClearedStatus.lastReview?.fresh === true && !memoryClearedStatus.outstandingRequirements.includes("review"));
+
+// 4. Worktree compatibility: review recorded in linked worktree is recognized by main repo
+todo("s-handoff-parent", item("worktree test", "in_progress"));
+const handoffWorktreeRes = (await handoffPlugin.tool?.guard_worktree_create?.execute({ branch: "feat/handoff-worktree" }, { sessionID: "s-handoff-parent", worktree: handoffRepo, directory: handoffRepo } as any)) as string;
+check("worktree created for handoff test", typeof handoffWorktreeRes === "string" && handoffWorktreeRes.includes("Worktree created"));
+check("worktree and main repo recognized as same git repository", isSameGitRepo(join(getWorktreeStorageDir(handoffRepo), "feat-handoff-worktree"), handoffRepo));
+
+rmSync(handoffRepo, { recursive: true, force: true });
+resetReviewState();
+
 // Event hook handles permission events
 if (typeof customPlugin.event === "function") {
 	await customPlugin.event({
@@ -2769,6 +2881,7 @@ writeFileSync(join(checkpointHookDir, "tracked.txt"), "agent result\n");
 await checkpointHooks.event?.({ event: { type: "session.idle", properties: { sessionID: "checkpoint-root" } } } as any);
 const generatedCheckpointMessage = checkpointHookPrompts.find((entry) => entry.sessionID === "checkpoint-root")?.messageID;
 check("idle finalizes recovery checkpoint before continuation", Boolean(listRecoveryCheckpoints(checkpointHookDir, "checkpoint-root")[0]?.endFingerprint && generatedCheckpointMessage));
+check("synthetic continuation messageID conforms to OpenCode msg_ prefix schema", typeof generatedCheckpointMessage === "string" && generatedCheckpointMessage.startsWith("msg_"));
 await checkpointHooks["chat.message"]?.({ sessionID: "checkpoint-root", messageID: generatedCheckpointMessage } as any, {} as any);
 check("synthetic continuation does not replace recovery checkpoint", listRecoveryCheckpoints(checkpointHookDir, "checkpoint-root").length === 1);
 checkpointHookParents.set("checkpoint-child", "checkpoint-root");
@@ -3208,6 +3321,26 @@ const editIdemDef = { description: editDef.description, parameters: {} };
 await defPlugin["tool.definition"]?.({ toolID: "edit" } as any, editIdemDef);
 check("tool.definition edit enrichment is idempotent", editIdemDef.description === editDef.description);
 
+const taskDef = { description: "Launch subagents.", parameters: {} };
+await defPlugin["tool.definition"]?.({ toolID: "task" } as any, taskDef);
+check("tool.definition enriches task tool with subagent and review guidance", taskDef.description.includes("Workflow Guard subagent guidance") && taskDef.description.includes("guard_worktree_create") && taskDef.description.includes("guard_review_rubric"));
+const taskIdemDef = { description: taskDef.description, parameters: {} };
+await defPlugin["tool.definition"]?.({ toolID: "task" } as any, taskIdemDef);
+check("tool.definition task enrichment is idempotent", taskIdemDef.description === taskDef.description);
+check("tool.definition todowrite enriches with planning and status guidance", todoDef.description.includes("guard_next_tasks") && todoDef.description.includes("guard_status"));
+
+// experimental.chat.system.transform provides cross-model workflow guidance
+const systemOutput = { system: ["Base system prompt"] };
+await defPlugin["experimental.chat.system.transform"]?.({ model: { id: "gemini-flash" } as any }, systemOutput);
+check("experimental.chat.system.transform adds workflow guard guidance", systemOutput.system.length === 2 && systemOutput.system[1].includes("## Workflow Guard & Operational Tools") && systemOutput.system[1].includes("guard_next_tasks") && systemOutput.system[1].includes("guard_review_rubric"));
+const systemOutputIdem = { system: [...systemOutput.system] };
+await defPlugin["experimental.chat.system.transform"]?.({ model: { id: "gemini-flash" } as any }, systemOutputIdem);
+check("experimental.chat.system.transform is idempotent", systemOutputIdem.system.length === 2);
+
+const readOnlySystemOutput = { system: ["Base system prompt"] };
+await defPlugin["experimental.chat.system.transform"]?.({ agent: "reviewer", model: { id: "claude-sonnet" } as any } as any, readOnlySystemOutput);
+check("experimental.chat.system.transform respects read-only roles", !readOnlySystemOutput.system[1].includes("spawn a reviewer subagent"));
+
 // Socratic learning engine: evidence is explicit and interventions favor
 // relevant gaps without repeatedly interrupting demonstrated knowledge.
 const learner = createLearnerProfile();
@@ -3287,6 +3420,7 @@ const learningPlugin = await WorkflowGuard({ directory: root, worktree: root, cl
 check("learning mode registers profile tool when explicitly enabled", !!learningPlugin.tool?.learning_profile);
 check("learning mode registers adaptive checkpoint tool", !!learningPlugin.tool?.learning_checkpoint);
 check("learning mode registers evidence recorder", !!learningPlugin.tool?.learning_record);
+check("learning_checkpoint description includes proactive trigger", Boolean(learningPlugin.tool?.learning_checkpoint?.description?.includes("Proactively call")));
 const checkpointResult = JSON.parse(await (learningPlugin.tool as any).learning_checkpoint.execute({
 	opportunities: [{ type: "design", concept: "application-state", relevance: 1, consequence: 0.9 }],
 }, { sessionID: "s-learning-tools" }));