opencode-workflow-guard 1.8.7 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.8.7",
+  "version": "1.9.0",
   "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, VerifyResult } from "./types.ts";
+import type { AuditEntry, PolicyDecision, VerifyResult } from "./types.ts";
 import { asRecord } from "./utils.ts";
 
 const AUDIT_DIR = join(
@@ -207,17 +207,19 @@ export function logDecision(
 	tool: string,
 	input: unknown,
 	context: { sessionID?: string; callID?: string } | undefined,
-	reason: string | undefined,
+	policyDecision: PolicyDecision,
 	evidence?: AuditEntry["evidence"],
 ): void {
+	const blocked = policyDecision.status !== "allowed";
 	audit({
 		ts: new Date().toISOString(),
 		sessionID: context?.sessionID,
 		callID: context?.callID,
 		tool,
-		decision: reason ? "block" : "allow",
+		decision: blocked ? "block" : "allow",
+		policyDecision,
 		phase: "decision",
-		reason,
+		reason: blocked ? policyDecision.message : undefined,
 		input: summarizeInput(input),
 		evidence,
 	});

package/src/lib/custom-tools.ts

@@ -12,24 +12,31 @@ import {
 	searchProjectMemory,
 } from "./project-memory.ts";
 import { loadLearnerProfile, recordLearningEvidence, selectLearningOpportunity, updateLearnerProfile } from "./learning.ts";
+import { isEvidenceFresh, reviewEvidence, verificationEvidence } from "./evidence.ts";
 import {
 	getLearningInterventionBudget,
+	getOperationProfile,
 	getProjectConfig,
-	getLastMutationTimestamp,
-	getLastReviewResult,
-	getLastVerifyResult,
-	getMutationCount,
+	getRalphMaxIterations,
+	getLastReviewResultForWorkspace,
+	getLastVerifyResultForWorkspace,
+	getWorkspaceMutationCount,
+	getWorkspaceMutationTimestamp,
 	getWorkspaceRoot,
 	isDocumentationRequired,
+	isRecoveryCheckpointsEnabled,
+	isRalphModeEnabled,
 	isReviewRequired,
 	recordMutation,
 	recordReviewResult,
 	runWithRuntimeState,
 } from "./state.ts";
-import { loadProjectConfig } from "./project-config.ts";
-import { detectVerifyCommand, getCurrentGitCommitHash } from "./verify.ts";
+import { getRalphOutcome } from "../policies/continuation.ts";
+import { loadProjectConfig, projectRootKey } from "./project-config.ts";
+import { detectVerifyCommand, getCurrentGitCommitHash, getGitWorktreeFingerprint } from "./verify.ts";
 import { buildReviewRubric } from "./review.ts";
 import { createGitWorktree, cleanupGitWorktree } from "./worktree.ts";
+import { branchHasDocumentationChange } from "../policies/docs.ts";
 import { restoreRecoveryCheckpoint } from "./checkpoint.ts";
 import { audit, getRecentAuditEntries } from "./audit.ts";
 import { guardToolCallImpl } from "./guard-dispatcher.ts";
@@ -58,7 +65,7 @@ export function createCustomTools(options: {
 }) {
 	const { effectiveRoot, projectMemoryEnabled, learningEnabled, projectMemory, followupStore, portableMemoryPath, learningInterventions, client } = options;
 	return {
-		...(getProjectConfig(effectiveRoot).recoveryCheckpoints === true ? {
+		...(isRecoveryCheckpointsEnabled(effectiveRoot) ? {
 			guard_recovery_restore: tool({
 				description: "Restore this root session's workspace to its pre-run recovery checkpoint. Refuses if the run has not gone idle or if the workspace changed after that boundary.",
 				args: { run: tool.schema.number() },
@@ -145,13 +152,27 @@ export function createCustomTools(options: {
 		} : {}),
 		guard_status: tool({
 			description: "Inspect active guardrails, current branch protection, and verification/review status.", args: {},
-			execute: async () => {
-				const root = getWorkspaceRoot(); const branch = currentGitBranch(root) ?? "unknown"; const isProtected = onProtectedBranch(root); const lastV = getLastVerifyResult(); const lastR = getLastReviewResult(); const lastMut = getLastMutationTimestamp(); const cfg = loadProjectConfig(root);
-				return JSON.stringify({ workspaceRoot: root, branch, onProtectedBranch: isProtected, lastMutationTimestamp: lastMut, mutationCount: getMutationCount(), lastVerify: lastV ? { command: lastV.command, passed: lastV.passed, fresh: lastV.timestamp >= lastMut, commitHash: lastV.commitHash } : null, lastReview: lastR ? { reviewer: lastR.reviewer, passed: lastR.passed, summary: lastR.summary } : null, projectConfig: { protectedBranches: cfg.protectedBranches ?? ["main", "master"], verifyCommand: detectVerifyCommand(root) ?? null, requireReview: isReviewRequired(root), requireDocumentation: isDocumentationRequired(root) } }, null, 2);
+			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);
+				const subject = { workspace: projectRootKey(root), commitHash: getCurrentGitCommitHash(root), worktreeFingerprint: getGitWorktreeFingerprint(root) };
+				const verifyEvidence = lastV ? verificationEvidence(lastV) : undefined;
+				const reviewEvidenceRecord = lastR ? reviewEvidence(lastR) : undefined;
+				const verifyCommand = detectVerifyCommand(root);
+				const verifyFresh = Boolean(lastV && verifyEvidence && lastV.passed && lastV.command === verifyCommand && isEvidenceFresh(verifyEvidence, subject, lastMut));
+				const reviewRequired = isReviewRequired(root);
+				const reviewFresh = Boolean(lastR && reviewEvidenceRecord && lastR.passed && isEvidenceFresh(reviewEvidenceRecord, { ...subject, sessionID: lastR.targetSessionID }, lastMut));
+				const documentationRequired = isDocumentationRequired(root);
+				const outstandingRequirements = [
+					...(verifyCommand && !verifyFresh ? ["verification"] : []),
+					...(reviewRequired && !reviewFresh ? ["review"] : []),
+					...(documentationRequired && !branchHasDocumentationChange(root) ? ["documentation"] : []),
+				];
+				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);
 			},
 		}),
 		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 explain whether a specific tool call or command would be blocked by guardrails.", 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) => { const reason = await guardToolCallImpl(args.tool, args.input ?? {}); return reason ? `BLOCKED: ${reason}` : "ALLOWED: Satisfies all current guardrails."; } }),
+		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) }),
 		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") },

package/src/lib/evidence.ts

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import type { ToolOutcome } from "./tool-outcomes.ts";
+import type { EvidenceRecord, EvidenceSubject, PolicyDecision, ReviewResult, VerifyResult } from "./types.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");
+}
+
+export function verificationEvidence(result: VerifyResult, sessionID?: string): EvidenceRecord {
+	const subject = { workspace: result.workspaceRoot, commitHash: result.commitHash, worktreeFingerprint: result.worktreeFingerprint, sessionID };
+	const source = { command: result.command, passed: result.passed, durationMs: result.durationMs, gitStatus: result.gitStatus };
+	return { id: evidenceId("verification", result.timestamp, subject, source), kind: "verification", confidence: "deterministic_observation", observedAt: result.timestamp, subject, source };
+}
+
+export function reviewEvidence(result: ReviewResult): EvidenceRecord {
+	const subject = { workspace: result.workspace, commitHash: result.commitHash, worktreeFingerprint: result.worktreeFingerprint, sessionID: result.targetSessionID, actor: result.reviewer };
+	const source = { reviewer: result.reviewer, passed: result.passed, summary: result.summary, gitStatus: result.gitStatus };
+	return { id: evidenceId("review", result.timestamp, subject, source), kind: "review", confidence: "attestation", observedAt: result.timestamp, subject, source };
+}
+
+export function toolOutcomeEvidence(outcome: ToolOutcome, observedAt: number, workspace?: string): EvidenceRecord {
+	const subject = { workspace, sessionID: outcome.sessionID, callID: outcome.callID };
+	const source = { tool: outcome.tool, status: outcome.status, durationMs: outcome.durationMs, repeatedFailureCount: outcome.repeatedFailureCount };
+	return { id: evidenceId("tool_outcome", observedAt, subject, source), kind: "tool_outcome", confidence: "deterministic_observation", observedAt, subject, source };
+}
+
+export function policyDecisionEvidence(decision: PolicyDecision, observedAt: number, subject: EvidenceSubject): EvidenceRecord {
+	const source = { status: decision.status, code: decision.code, policy: decision.policy };
+	return { id: evidenceId("policy_evaluation", observedAt, subject, source), kind: "policy_evaluation", confidence: "deterministic_observation", observedAt, subject, source };
+}
+
+export function lifecycleStateEvidence(state: string, observedAt: number, subject: EvidenceSubject, source: Record<string, unknown> = {}): EvidenceRecord {
+	const lifecycleSource = { state, ...source };
+	return { id: evidenceId("lifecycle_state", observedAt, subject, lifecycleSource), kind: "lifecycle_state", confidence: "derived_state", observedAt, subject, source: lifecycleSource };
+}
+
+export function agentAssertionEvidence(assertion: string, observedAt: number, subject: EvidenceSubject): EvidenceRecord {
+	const source = { assertion };
+	return { id: evidenceId("agent_assertion", observedAt, subject, source), kind: "agent_assertion", confidence: "agent_assertion", observedAt, subject, source };
+}
+
+export function evidenceMatchesSubject(evidence: EvidenceRecord, subject: EvidenceSubject): boolean {
+	return evidence.subject.workspace === subject.workspace &&
+		evidence.subject.commitHash === subject.commitHash &&
+		evidence.subject.worktreeFingerprint === subject.worktreeFingerprint &&
+		evidence.subject.sessionID === subject.sessionID;
+}
+
+export function isEvidenceFresh(evidence: EvidenceRecord, subject: EvidenceSubject, mutationTimestamp: number): boolean {
+	// HEAD is legitimately absent in a freshly initialized repository, but the
+	// worktree fingerprint remains available there and is required for freshness.
+	if (!evidence.subject.worktreeFingerprint || !subject.worktreeFingerprint) return false;
+	return evidence.observedAt >= mutationTimestamp && evidenceMatchesSubject(evidence, subject);
+}

package/src/lib/guard-dispatcher.ts

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { loadVerifyCache } from "./audit.ts";
+import { isEvidenceFresh, reviewEvidence, verificationEvidence } from "./evidence.ts";
+import { projectRootKey } from "./project-config.ts";
 import {
 	getLastReviewResult,
 	getSdkClient,
@@ -24,6 +26,7 @@ import {
 	unwrapShellCommand,
 } from "./shell.ts";
 import { asRecord, extractTargetPath } from "./utils.ts";
+import type { PolicyDecision } from "./types.ts";
 import { getProjectMemoryIdentity } from "./project-memory.ts";
 import {
 	detectVerifyCommand,
@@ -37,7 +40,7 @@ import { detectShellMutation, extractPatchPaths, guardShellMutation, isPathOutsi
 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 } from "../policies/file-claims.ts";
+import { claimFiles, fileClaimConflictReason } from "../policies/file-claims.ts";
 import {
 	GIT_BRANCH_CREATE_RE,
 	GIT_WRITE_RE,
@@ -88,7 +91,8 @@ export function isReadOnlyRole(agent?: string): boolean {
 	return READ_ONLY_ROLES.has(lower) || Array.from(READ_ONLY_ROLES).some((r) => lower.includes(r));
 }
 
-function logBlock(message: string): void {
+function logBlock(message: string, simulate = false): void {
+	if (simulate) return;
 	try {
 		void getSdkClient()?.app?.log?.({
 			body: {
@@ -103,22 +107,27 @@ function logBlock(message: string): void {
 export async function guardToolCallImpl(
 	toolName: string,
 	input: unknown,
-	context?: { sessionID?: string; callID?: string; worktree?: string; directory?: string; agent?: string },
-): Promise<string | undefined> {
+	context?: { sessionID?: string; callID?: string; worktree?: string; directory?: string; agent?: string; simulate?: boolean },
+): Promise<PolicyDecision> {
+	const logPolicyBlock = (message: string) => logBlock(message, context?.simulate);
 	const currentRoot = getWorkspaceRoot();
+	const allow = (): PolicyDecision => ({ status: "allowed", code: "allowed", message: "Allowed by current guardrails." });
+	const block = (policy: string, code: string, message: string): PolicyDecision => ({ status: "blocked", policy, code, message });
+	const needsApproval = (policy: string, code: string, message: string): PolicyDecision => ({ status: "needs_approval", policy, code, message });
+	let remotePrStateUnchecked = false;
 
 	if (context?.agent && isReadOnlyRole(context.agent)) {
 		if (EDIT_TOOL_NAMES.has(toolName) || toolName.startsWith("guard_worktree_")) {
 			const reason = `Blocked: subagent with read-only role '${context.agent}' cannot perform file mutations or lifecycle changes.`;
-			logBlock(`[workflow-guard] ${reason}`);
-			return reason;
+			logPolicyBlock(`[workflow-guard] ${reason}`);
+			return block("subagent-role", "read_only_role", reason);
 		}
 	}
 
 	if (toolName === "read" || toolName === "read_file") {
 		const target = extractTargetPath(input) ?? "";
 		if (target && isSecretPath(target)) {
-			logBlock(`[workflow-guard] blocked read: secret file ${target}`);
+			logPolicyBlock(`[workflow-guard] blocked read: secret file ${target}`);
 			if (isEnvFilePath(target)) {
 				let schemaHint = "";
 				try {
@@ -129,11 +138,11 @@ export async function guardToolCallImpl(
 						schemaHint = `\n\nSafe variable schema mask:\n\`\`\`\n${masked.slice(0, 800)}\n\`\`\``;
 					}
 				} catch {}
-				return `Blocked: reading sensitive credential file '${target}' directly is not permitted. Use environment variables or reference safe templates.${schemaHint}`;
+				return block("secrets", "secret_read", `Blocked: reading sensitive credential file '${target}' directly is not permitted. Use environment variables or reference safe templates.${schemaHint}`);
 			}
-			return `Blocked: reading sensitive credential/secret file '${target}' is not permitted. Reference environment variables by name or inspect safe templates (e.g. .env.example) instead.`;
+			return block("secrets", "secret_read", `Blocked: reading sensitive credential/secret file '${target}' is not permitted. Reference environment variables by name or inspect safe templates (e.g. .env.example) instead.`);
 		}
-		return undefined;
+		return allow();
 	}
 
 	if (toolName === "todowrite") {
@@ -144,8 +153,8 @@ export async function guardToolCallImpl(
 			const existingTodos = context?.sessionID ? await fetchSessionTodos(context.sessionID) : undefined;
 			const err = validateTodoLifecycle(newTodos, existingTodos);
 			if (err) {
-				logBlock(`[workflow-guard] ${err}`);
-				return err;
+				logPolicyBlock(`[workflow-guard] ${err}`);
+				return block("todo", "todo_lifecycle", err);
 			}
 			const allDone = newTodos.length > 0 && newTodos.every((t) => {
 				const s = String(t.status ?? "");
@@ -155,8 +164,8 @@ export async function guardToolCallImpl(
 				const conflictCheck = checkMergeConflicts(currentRoot);
 				if (conflictCheck.hasConflicts) {
 					const reason = `Blocked todowrite: ${conflictCheck.reason}`;
-					logBlock(`[workflow-guard] ${reason}`);
-					return reason;
+					logPolicyBlock(`[workflow-guard] ${reason}`);
+					return block("git", "merge_conflict", reason);
 				}
 				const command = detectVerifyCommand(currentRoot);
 				if (command) {
@@ -164,27 +173,26 @@ export async function guardToolCallImpl(
 					let verifyResult = sessionID ? sessionVerifyResults.get(sessionID) : lastVerify;
 					if (!verifyResult) {
 						const diskCached = loadVerifyCache();
-						if (diskCached && diskCached.passed && diskCached.command === command && diskCached.workspaceRoot === resolve(currentRoot)) verifyResult = diskCached;
+						if (diskCached && diskCached.passed && diskCached.command === command && diskCached.workspaceRoot && projectRootKey(diskCached.workspaceRoot) === projectRootKey(currentRoot)) verifyResult = diskCached;
 					}
 					const mutationTimestamp = sessionID ? (sessionMutationTimestamps.get(sessionID) ?? 0) : lastMutationTimestamp;
-					const currentCommit = getCurrentGitCommitHash(currentRoot);
-					const currentGitStatus = getGitStatusSummary(currentRoot);
-					const gitStateMatches = !verifyResult?.commitHash || (verifyResult.commitHash === currentCommit && verifyResult.gitStatus === currentGitStatus);
-					const isFresh = verifyResult !== undefined && verifyResult.passed && verifyResult.command === command && verifyResult.timestamp >= mutationTimestamp && gitStateMatches;
+					const currentSubject = { workspace: projectRootKey(currentRoot), commitHash: getCurrentGitCommitHash(currentRoot), worktreeFingerprint: getGitWorktreeFingerprint(currentRoot), sessionID };
+					const isFresh = verifyResult !== undefined && verifyResult.passed && verifyResult.command === command && isEvidenceFresh(verificationEvidence(verifyResult, sessionID), currentSubject, mutationTimestamp);
 					if (!isFresh) {
+						if (context?.simulate) return block("verification", "verification_required", `Blocked: finalization requires fresh passing verification (${command}).`);
 						const result = await runVerify(command, currentRoot);
 						recordVerifyResult(command, result, sessionID, currentRoot);
 						if (!result.passed) {
 							const tail = snipVerifyOutput(result.output, result.passed).slice(-500);
 							const reason = `Blocked todowrite: all tasks marked done but verification is failing (${command}). Fix the failure before finishing; output tail: ${tail}`;
-							logBlock(`[workflow-guard] ${reason}`);
-							return reason;
+							logPolicyBlock(`[workflow-guard] ${reason}`);
+							return block("verification", "verification_failed", reason);
 						}
 					}
 				}
 			}
 		}
-		return undefined;
+		return allow();
 	}
 
 	if (EDIT_TOOL_NAMES.has(toolName)) {
@@ -192,39 +200,39 @@ export async function guardToolCallImpl(
 		const record = asRecord(input);
 		const target = extractTargetPath(input) ?? "";
 		if (target && isProtectedPath(target)) {
-			logBlock(`[workflow-guard] blocked ${toolName}: protected path ${target}`);
-			return PROTECTED_PATH_REASON;
+			logPolicyBlock(`[workflow-guard] blocked ${toolName}: protected path ${target}`);
+			return block("tamper", "protected_path", PROTECTED_PATH_REASON);
 		}
 		if (target && isSecretPath(target)) {
-			logBlock(`[workflow-guard] blocked ${toolName}: secret file path ${target}`);
-			return `Blocked: modifying secret file '${target}' directly is not permitted. Store credentials in environment variables or safe secret stores instead.`;
+			logPolicyBlock(`[workflow-guard] blocked ${toolName}: secret file path ${target}`);
+			return block("secrets", "secret_write", `Blocked: modifying secret file '${target}' directly is not permitted. Store credentials in environment variables or safe secret stores instead.`);
 		}
 		if (toolName === "apply_patch") {
 			const patchText = typeof record?.patchText === "string" ? record.patchText : "";
 			for (const patchPath of extractPatchPaths(patchText)) {
 				if (isProtectedPath(patchPath)) {
-					logBlock(`[workflow-guard] blocked apply_patch: protected path ${patchPath}`);
-					return PROTECTED_PATH_REASON;
+					logPolicyBlock(`[workflow-guard] blocked apply_patch: protected path ${patchPath}`);
+					return block("tamper", "protected_path", PROTECTED_PATH_REASON);
 				}
 				if (isSecretPath(patchPath)) {
-					logBlock(`[workflow-guard] blocked apply_patch: secret file path ${patchPath}`);
-					return `Blocked: modifying secret file '${patchPath}' directly is not permitted.`;
+					logPolicyBlock(`[workflow-guard] blocked apply_patch: secret file path ${patchPath}`);
+					return block("secrets", "secret_write", `Blocked: modifying secret file '${patchPath}' directly is not permitted.`);
 				}
 				if (isPathOutsideWorkspace(patchPath, currentRoot)) {
-					logBlock(`[workflow-guard] blocked apply_patch: patch target escapes workspace: ${patchPath}`);
-					return `Blocked: patch targets file '${patchPath}' outside workspace root (${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}).`);
 				}
 			}
 		}
 		if (target && isPathOutsideWorkspace(target, currentRoot)) {
-			logBlock(`[workflow-guard] blocked ${toolName}: path escapes workspace: ${target}`);
-			return `Blocked: file path '${target}' escapes workspace root (${currentRoot}). All changes must stay within the workspace.`;
+			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.`);
 		}
 		for (const content of extractEditContent(input)) {
 			const secret = secretIn(content);
 			if (secret) {
-				logBlock(`[workflow-guard] blocked ${toolName}: payload contains ${secret}`);
-				return `Blocked: payload appears to contain a ${secret}. Secrets must not be committed to the repository. Store them in a secret manager or environment file excluded from git, and reference them by name instead.`;
+				logPolicyBlock(`[workflow-guard] blocked ${toolName}: payload contains ${secret}`);
+				return block("secrets", "secret_payload", `Blocked: payload appears to contain a ${secret}. Secrets must not be committed to the repository. Store them in a secret manager or environment file excluded from git, and reference them by name instead.`);
 			}
 		}
 		if (!allowLive) {
@@ -234,58 +242,61 @@ export async function guardToolCallImpl(
 					if (trimmed.startsWith("#") || trimmed.startsWith("//") || trimmed.startsWith("/*") || trimmed.startsWith("*")) continue;
 					const what = liveMutationIn(normalizeGitCommands(line));
 					if (what) {
-						logBlock(`[workflow-guard] blocked ${toolName}: payload contains ${what}`);
-						return `Blocked: the file you are writing contains a ${what}. Script files are not a way to smuggle destructive commands past the shell guard. Only the user can allow live mutations (WORKFLOW_GUARD_ALLOW_LIVE=1).`;
+						logPolicyBlock(`[workflow-guard] blocked ${toolName}: payload contains ${what}`);
+						return block("destructive", "live_mutation_payload", `Blocked: the file you are writing contains a ${what}. Script files are not a way to smuggle destructive commands past the shell guard. Only the user can allow live mutations (WORKFLOW_GUARD_ALLOW_LIVE=1).`);
 					}
 				}
 			}
 		}
-		for (const content of extractEditContent(input)) if (isSettingsTamper(content)) return PROTECTED_PATH_REASON;
+		for (const content of extractEditContent(input)) if (isSettingsTamper(content)) return block("tamper", "settings_tamper", PROTECTED_PATH_REASON);
 		if (onProtectedBranch(currentRoot)) {
-			logBlock(`[workflow-guard] blocked ${toolName}: on protected branch ${currentGitBranch(currentRoot)}`);
-			return branchGuardReason();
+			logPolicyBlock(`[workflow-guard] blocked ${toolName}: on protected branch ${currentGitBranch(currentRoot)}`);
+			return block("git", "protected_branch", branchGuardReason());
 		}
 		const todos = await effectiveTodos(context?.sessionID);
 		if (todos !== undefined && !hasActiveTodo(todos)) {
-			logBlock(`[workflow-guard] blocked ${toolName}: no active todo item (session ${context?.sessionID ?? "?"})`);
-			return "Blocked: no active todo item. First break the request down with the todowrite tool (create items with status 'pending' or 'in_progress'), then work them through, marking each completed via todowrite as you finish it. When every item is completed, create a fresh todo list before starting new work.";
+			logPolicyBlock(`[workflow-guard] blocked ${toolName}: no active todo item (session ${context?.sessionID ?? "?"})`);
+			return block("todo", "no_active_todo", "Blocked: no active todo item. First break the request down with the todowrite tool (create items with status 'pending' or 'in_progress'), then work them through, marking each completed via todowrite as you finish it. When every item is completed, create a fresh todo list before starting new work.");
 		}
 		if (context?.sessionID) {
 			const reason = await subagentMutationBudgetReason(context.sessionID, currentRoot);
 			if (reason) {
-				logBlock(`[workflow-guard] ${reason}`);
-				return reason;
+				logPolicyBlock(`[workflow-guard] ${reason}`);
+				return block("todo", "mutation_budget", reason);
 			}
 		}
-		if (context?.sessionID && context.callID) {
+		if (context?.sessionID) {
 			if (toolName === "edit" || toolName === "write") {
 				for (const path of editTargets(input, currentRoot)) {
 					const staleReason = staleWriteReason(path, context.sessionID);
 					if (staleReason) {
-						logBlock(`[workflow-guard] ${staleReason}`);
-						return staleReason;
+						logPolicyBlock(`[workflow-guard] ${staleReason}`);
+						return block("stale-write", "stale_write", staleReason);
 					}
 				}
 			}
-			const claimReason = claimFiles(editTargets(input, currentRoot), context.sessionID, context.callID);
+			const targets = editTargets(input, currentRoot);
+			const claimReason = context.simulate
+				? fileClaimConflictReason(targets, context.sessionID)
+				: context.callID ? claimFiles(targets, context.sessionID, context.callID) : undefined;
 			if (claimReason) {
-				logBlock(`[workflow-guard] ${claimReason}`);
-				return claimReason;
+				logPolicyBlock(`[workflow-guard] ${claimReason}`);
+				return block("file-claims", "file_claim_conflict", claimReason);
 			}
 		}
-		recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID), context?.sessionID);
-		return undefined;
+		if (!context?.simulate) recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID), context?.sessionID);
+		return allow();
 	}
 
 	const allowLive = process.env.WORKFLOW_GUARD_ALLOW_LIVE === "1";
 	if (!allowLive) {
 		const mcpWhat = mcpMutationTool(toolName);
 		if (mcpWhat) {
-			logBlock(`[workflow-guard] blocked MCP tool ${toolName} (${mcpWhat} mutation)`);
-			return `Blocked: ${toolName} mutates ${mcpWhat} - a live system. Changes must be made in code unless the user explicitly allows live changes. Only the user can override this, via the WORKFLOW_GUARD_ALLOW_LIVE=1 environment variable set before launching the agent.`;
+			logPolicyBlock(`[workflow-guard] blocked MCP tool ${toolName} (${mcpWhat} mutation)`);
+			return block("mcp", "live_mcp_mutation", `Blocked: ${toolName} mutates ${mcpWhat} - a live system. Changes must be made in code unless the user explicitly allows live changes. Only the user can override this, via the WORKFLOW_GUARD_ALLOW_LIVE=1 environment variable set before launching the agent.`);
 		}
 	}
-	if (!SHELL_TOOL_NAMES.has(toolName)) return undefined;
+	if (!SHELL_TOOL_NAMES.has(toolName)) return allow();
 	const shellWorkdir = asRecord(input)?.workdir;
 	const requestedShellRoot = typeof shellWorkdir === "string" ? resolve(currentRoot, shellWorkdir) : currentRoot;
 	const shellRoot = !isPathOutsideWorkspace(requestedShellRoot, currentRoot) || getProjectMemoryIdentity(requestedShellRoot) === getProjectMemoryIdentity(currentRoot)
@@ -294,116 +305,117 @@ export async function guardToolCallImpl(
 
 	for (const raw of extractCommands(input)) {
 		const dynamicSyntax = dynamicShellSyntaxIn(raw);
-		if (dynamicSyntax) return `Blocked: command contains ${dynamicSyntax} that cannot be safely classified without executing shell expansion.`;
+		if (dynamicSyntax) return block("shell-safety", "dynamic_shell_syntax", `Blocked: command contains ${dynamicSyntax} that cannot be safely classified without executing shell expansion.`);
 		const command = normalize(raw);
 		const ttyCheck = checkInteractiveTtyCommand(command);
 		if (ttyCheck.isInteractive) {
-			logBlock(`[workflow-guard] blocked interactive TTY command: ${command.slice(0, 100)}`);
-			return `Blocked: '${command.slice(0, 60)}' is an ${ttyCheck.name} and will hang non-interactive agent execution. ${ttyCheck.advice}`;
+			logPolicyBlock(`[workflow-guard] blocked interactive TTY command: ${command.slice(0, 100)}`);
+			return block("shell-safety", "interactive_tty", `Blocked: '${command.slice(0, 60)}' is an ${ttyCheck.name} and will hang non-interactive agent execution. ${ttyCheck.advice}`);
 		}
 		const packageCheck = checkPackageHygiene(command);
 		if (packageCheck.isViolating && !allowLive) {
-			logBlock(`[workflow-guard] blocked package supply-chain violation: ${command.slice(0, 100)}`);
-			return `Blocked: '${command.slice(0, 60)}' is a ${packageCheck.name}. ${packageCheck.advice}`;
+			logPolicyBlock(`[workflow-guard] blocked package supply-chain violation: ${command.slice(0, 100)}`);
+			return block("shell-safety", "package_hygiene", `Blocked: '${command.slice(0, 60)}' is a ${packageCheck.name}. ${packageCheck.advice}`);
 		}
 		const normalizedCommand = normalizeGitCommands(command);
-		if (hasUnsafeGitAlias(command)) return "Blocked: per-invocation Git aliases cannot be used because they can hide guarded Git operations.";
+		if (hasUnsafeGitAlias(command)) return block("git", "unsafe_git_alias", "Blocked: per-invocation Git aliases cannot be used because they can hide guarded Git operations.");
 		const gitInvocations = splitShellSegments(command).map((segment) => parseGitInvocation(segment.trim())).filter((invocation): invocation is NonNullable<ReturnType<typeof parseGitInvocation>> => invocation !== undefined);
 		const effectiveRoot = gitInvocations[0]?.repoDir ?? currentRoot;
 		for (const invocation of gitInvocations) {
 			const normalizedInvocation = `git ${invocation.rest}`;
 			if (isPathOutsideWorkspace(invocation.repoDir, currentRoot) && (GIT_WRITE_RE.test(normalizedInvocation) || /\bgit\s+push\b/.test(normalizedInvocation))) {
-				logBlock(`[workflow-guard] blocked git mutation on repository outside workspace: ${invocation.repoDir}`);
-				return `Blocked: git command targets repository '${invocation.repoDir}' outside workspace root (${currentRoot}). All changes must stay within the workspace.`;
+				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.`);
 			}
 		}
 		for (const invocation of gitInvocations) {
 			if (GIT_WRITE_RE.test(`git ${invocation.rest}`) && onProtectedBranch(invocation.repoDir)) {
-				logBlock(`[workflow-guard] blocked git write on protected branch: ${command.slice(0, 120)}`);
-				return branchGuardReason();
+				logPolicyBlock(`[workflow-guard] blocked git write on protected branch: ${command.slice(0, 120)}`);
+				return block("git", "protected_branch", branchGuardReason());
 			}
 		}
 		if (GIT_BRANCH_CREATE_RE.test(normalizedCommand)) {
 			const behindCheck = checkBranchBaseIsUpToDate(effectiveRoot);
 			if (behindCheck.isBehind) {
-				logBlock(`[workflow-guard] blocked branch creation: base is behind remote ${behindCheck.baseRef}`);
-				return `Blocked: ${behindCheck.reason}`;
+				logPolicyBlock(`[workflow-guard] blocked branch creation: base is behind remote ${behindCheck.baseRef}`);
+				return block("git", "branch_base_behind", `Blocked: ${behindCheck.reason}`);
 			}
 		}
 		if (isSettingsTamper(command)) {
-			logBlock(`[workflow-guard] blocked settings tamper: ${command.slice(0, 120)}`);
-			return PROTECTED_PATH_REASON;
+			logPolicyBlock(`[workflow-guard] blocked settings tamper: ${command.slice(0, 120)}`);
+			return block("tamper", "settings_tamper", PROTECTED_PATH_REASON);
 		}
 		for (const segment of command.split(/[\n|;&]+/)) {
 			const secretFile = secretFileReadIn(segment.trim());
 			if (secretFile) {
-				logBlock(`[workflow-guard] blocked shell read of secret file: ${secretFile}`);
-				return `Blocked: reading sensitive credential/secret file '${secretFile}' via shell is not permitted. Reference environment variables by name or inspect safe templates (e.g. .env.example) instead.`;
+				logPolicyBlock(`[workflow-guard] blocked shell read of secret file: ${secretFile}`);
+				return block("secrets", "secret_read", `Blocked: reading sensitive credential/secret file '${secretFile}' via shell is not permitted. Reference environment variables by name or inspect safe templates (e.g. .env.example) instead.`);
 			}
 		}
 		for (const payload of extractInterpreterPayload(raw)) {
 			const outsidePath = outsideWritePathInPayload(payload, currentRoot);
 			if (outsidePath) {
-				logBlock(`[workflow-guard] blocked interpreter payload writing outside workspace: ${outsidePath}`);
-				return `Blocked: inline interpreter script targets file '${outsidePath}' outside workspace root (${currentRoot}). All changes must stay within the workspace.`;
+				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.`);
 			}
 			const writePaths = writePathsInPayload(payload);
 			if (writePaths.length > 0) {
-				if (context?.agent && isReadOnlyRole(context.agent)) return `Blocked: subagent with read-only role '${context.agent}' cannot perform shell file mutations.`;
-				for (const path of writePaths) if (isProtectedPath(path)) return PROTECTED_PATH_REASON;
-				if (onProtectedBranch(currentRoot)) return branchGuardReason();
+				if (context?.agent && isReadOnlyRole(context.agent)) return block("subagent-role", "read_only_role", `Blocked: subagent with read-only role '${context.agent}' cannot perform shell file mutations.`);
+				for (const path of writePaths) if (isProtectedPath(path)) return block("tamper", "protected_path", PROTECTED_PATH_REASON);
+				if (onProtectedBranch(currentRoot)) return block("git", "protected_branch", branchGuardReason());
 				const todos = await effectiveTodos(context?.sessionID);
-				if (todos !== undefined && !hasActiveTodo(todos)) return "Blocked: inline interpreter file mutation with no active todo item.";
-				recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID), context?.sessionID);
+				if (todos !== undefined && !hasActiveTodo(todos)) return block("todo", "no_active_todo", "Blocked: inline interpreter file mutation with no active todo item.");
+				if (!context?.simulate) recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID), context?.sessionID);
 			}
 			if (!allowLive) {
 				const liveCheck = liveMutationIn(normalizeGitCommands(normalize(payload)));
 				if (liveCheck) {
-					logBlock(`[workflow-guard] blocked interpreter payload containing ${liveCheck}`);
-					return `Blocked: inline interpreter script contains a ${liveCheck}. Interpreter payloads cannot smuggle live destructive commands past the guard.`;
+					logPolicyBlock(`[workflow-guard] blocked interpreter payload containing ${liveCheck}`);
+					return block("destructive", "live_mutation_payload", `Blocked: inline interpreter script contains a ${liveCheck}. Interpreter payloads cannot smuggle live destructive commands past the guard.`);
 				}
 			}
-			if (isSettingsTamper(payload)) return PROTECTED_PATH_REASON;
+			if (isSettingsTamper(payload)) return block("tamper", "settings_tamper", PROTECTED_PATH_REASON);
 			const secretPath = secretPathInPayload(payload);
-			if (secretPath) return `Blocked: reading sensitive credential/secret file '${secretPath}' via inline interpreter script is not permitted.`;
+			if (secretPath) return block("secrets", "secret_read", `Blocked: reading sensitive credential/secret file '${secretPath}' via inline interpreter script is not permitted.`);
 		}
-		const shellMutationReason = await guardShellMutation(command, context?.sessionID);
+		const shellMutationReason = await guardShellMutation(command, context?.sessionID, !context?.simulate);
 		if (shellMutationReason) {
-			logBlock(`[workflow-guard] blocked shell mutation: ${command.slice(0, 120)}`);
-			return shellMutationReason;
+			logPolicyBlock(`[workflow-guard] blocked shell mutation: ${command.slice(0, 120)}`);
+			return block("boundary", "shell_mutation", shellMutationReason);
 		}
 		if (!allowLive) {
 			const what = liveMutationIn(normalizedCommand) ?? liveMutationIn(command);
 			if (what) {
-				logBlock(`[workflow-guard] blocked ${what}: ${command.slice(0, 120)}`);
-				return `Blocked: ${what} targets a live system. Changes must be made in code (IaC, migrations, source) unless the user explicitly allows live changes. Only the user can override this, via the WORKFLOW_GUARD_ALLOW_LIVE=1 environment variable set before launching the agent.`;
+				logPolicyBlock(`[workflow-guard] blocked ${what}: ${command.slice(0, 120)}`);
+				return block("destructive", "live_mutation", `Blocked: ${what} targets a live system. Changes must be made in code (IaC, migrations, source) unless the user explicitly allows live changes. Only the user can override this, via the WORKFLOW_GUARD_ALLOW_LIVE=1 environment variable set before launching the agent.`);
 			}
 		}
 		if (PUSH_TO_MAIN_RE.test(normalizedCommand)) {
-			logBlock(`[workflow-guard] blocked push to main/master: ${command}`);
-			return "Blocked: direct pushes to main/master are not allowed. Create a feature branch and open a PR instead.";
+			logPolicyBlock(`[workflow-guard] blocked push to main/master: ${command}`);
+			return block("git", "protected_branch_push", "Blocked: direct pushes to main/master are not allowed. Create a feature branch and open a PR instead.");
 		}
 		for (const invocation of gitInvocations) {
 			const pushText = `git ${invocation.rest}`;
 			if (!/\bgit\s+push\b/.test(pushText)) continue;
 			const pushedBranch = pushedProtectedBranchIn(pushText, invocation.repoDir);
 			if (pushedBranch) {
-				logBlock(`[workflow-guard] blocked push to protected branch '${pushedBranch}': ${command}`);
-				return `Blocked: direct pushes to protected branch '${pushedBranch}' are not allowed. Create a feature branch and open a PR instead.`;
+				logPolicyBlock(`[workflow-guard] blocked push to protected branch '${pushedBranch}': ${command}`);
+				return block("git", "protected_branch_push", `Blocked: direct pushes to protected branch '${pushedBranch}' are not allowed. Create a feature branch and open a PR instead.`);
 			}
 		}
 		for (const invocation of gitInvocations) {
 			if (!/\bgit\s+push\b/.test(`git ${invocation.rest}`)) continue;
 			if (onProtectedBranch(invocation.repoDir)) {
-				logBlock(`[workflow-guard] blocked push from protected branch: ${command}`);
-				return branchGuardReason();
+				logPolicyBlock(`[workflow-guard] blocked push from protected branch: ${command}`);
+				return block("git", "protected_branch", branchGuardReason());
 			}
 			const branch = currentGitBranch(invocation.repoDir);
 			if (branch) {
-				const mergedStatus = isBranchAlreadyMergedOrClosed(invocation.repoDir, branch);
+				if (context?.simulate) remotePrStateUnchecked = true;
+				const mergedStatus = isBranchAlreadyMergedOrClosed(invocation.repoDir, branch, !context?.simulate);
 				if (mergedStatus.merged) {
-					logBlock(`[workflow-guard] blocked push to merged/closed branch: ${branch}`);
-					return `Blocked: ${mergedStatus.reason}`;
+					logPolicyBlock(`[workflow-guard] blocked push to merged/closed branch: ${branch}`);
+					return block("git", "merged_branch", `Blocked: ${mergedStatus.reason}`);
 				}
 			}
 		}
@@ -418,12 +430,13 @@ export async function guardToolCallImpl(
 			if (conflictCheck.hasConflicts) preflightFailures.push(conflictCheck.reason ?? "Branch has merge conflicts with its base branch.");
 			const branch = currentGitBranch(prRoot);
 			if (branch) {
-				const mergedStatus = isBranchAlreadyMergedOrClosed(prRoot, branch);
+				if (context?.simulate) remotePrStateUnchecked = true;
+				const mergedStatus = isBranchAlreadyMergedOrClosed(prRoot, branch, !context?.simulate);
 				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();
-				const reviewMatchesContext = review?.passed === true && review.workspace === resolve(prRoot) && (!review.targetSessionID || review.targetSessionID === context?.sessionID) && review.commitHash === getCurrentGitCommitHash(prRoot) && review.gitStatus === getGitStatusSummary(prRoot) && review.worktreeFingerprint === getGitWorktreeFingerprint(prRoot);
+				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.");
 			}
 			if (isDocumentationRequired(prRoot) && !branchHasDocumentationChange(prRoot)) preflightFailures.push("Documentation update is required (Policy 21); update README.md or relevant documentation in docs/.");
@@ -444,8 +457,8 @@ export async function guardToolCallImpl(
 			if (lockCheck.isOutOfSync) preflightFailures.push(lockCheck.reason ?? "Dependency lockfile is out of sync with its manifest.");
 			if (preflightFailures.length > 0) {
 				const reason = `Blocked: PR preflight failed:\n${preflightFailures.map((failure) => `- ${failure}`).join("\n")}`;
-				logBlock(`[workflow-guard] blocked ${prTool}: ${preflightFailures.length} preflight requirement(s) failed`);
-				return reason;
+				logPolicyBlock(`[workflow-guard] blocked ${prTool}: ${preflightFailures.length} preflight requirement(s) failed`);
+				return block("pr-preflight", "pr_preflight_failed", reason,);
 			}
 		}
 		const hasGitMutation = gitInvocations.some((invocation) => {
@@ -455,12 +468,12 @@ export async function guardToolCallImpl(
 		if (context?.agent && isReadOnlyRole(context.agent)) {
 			const mutation = detectShellMutation(command);
 			if (mutation) {
-				logBlock(`[workflow-guard] blocked shell mutation for read-only role ${context.agent}: ${mutation.what}`);
-				return `Blocked: subagent with read-only role '${context.agent}' cannot perform shell file mutations (${mutation.what}).`;
+				logPolicyBlock(`[workflow-guard] blocked shell mutation for read-only role ${context.agent}: ${mutation.what}`);
+				return block("subagent-role", "read_only_role", `Blocked: subagent with read-only role '${context.agent}' cannot perform shell file mutations (${mutation.what}).`);
 			}
 			if (hasGitMutation) {
-				logBlock(`[workflow-guard] blocked git mutation for read-only role ${context.agent}`);
-				return `Blocked: subagent with read-only role '${context.agent}' cannot mutate git history or state.`;
+				logPolicyBlock(`[workflow-guard] blocked git mutation for read-only role ${context.agent}`);
+				return block("subagent-role", "read_only_role", `Blocked: subagent with read-only role '${context.agent}' cannot mutate git history or state.`);
 			}
 		}
 		const shellMut = detectShellMutation(command);
@@ -468,12 +481,13 @@ export async function guardToolCallImpl(
 			if (context?.sessionID) {
 				const reason = await subagentMutationBudgetReason(context.sessionID, currentRoot);
 				if (reason) {
-					logBlock(`[workflow-guard] ${reason}`);
-					return reason;
+					logPolicyBlock(`[workflow-guard] ${reason}`);
+					return block("todo", "mutation_budget", reason);
 				}
 			}
 		}
-		if (hasGitMutation) recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID), context?.sessionID);
+		if (hasGitMutation && !context?.simulate) recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID), context?.sessionID);
 	}
-	return undefined;
+	if (remotePrStateUnchecked) return needsApproval("git", "remote_state_unchecked", "Remote GitHub/Azure PR state was not queried during simulation; no deterministic local guardrail blocked this call, but final allow/block status requires real enforcement.");
+	return allow();
 }

package/src/lib/project-config.ts

@@ -1,8 +1,16 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
 import type { ProjectConfig } from "./types.ts";
 
-let cachedProjectConfig: ProjectConfig | undefined;
+const projectConfigCache = new Map<string, ProjectConfig>();
+
+export function projectRootKey(root: string): string {
+	try {
+		return realpathSync(root);
+	} catch {
+		return resolve(root);
+	}
+}
 
 export function projectConfigCandidates(root: string): string[] {
 	return [
@@ -60,9 +68,9 @@ export function loadProjectConfig(root: string): ProjectConfig {
 }
 
 export function reloadProjectConfig(root: string): void {
-	cachedProjectConfig = loadProjectConfig(root);
+	projectConfigCache.set(projectRootKey(root), loadProjectConfig(root));
 }
 
-export function getCachedProjectConfig(): ProjectConfig | undefined {
-	return cachedProjectConfig;
+export function getCachedProjectConfig(root: string): ProjectConfig | undefined {
+	return projectConfigCache.get(projectRootKey(root));
 }

package/src/lib/state.ts

@@ -2,7 +2,7 @@ import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { persistVerifyCache, persistVerifyHistory } from "./audit.ts";
-import { getCachedProjectConfig, loadProjectConfig } from "./project-config.ts";
+import { getCachedProjectConfig, loadProjectConfig, projectRootKey } from "./project-config.ts";
 import { snipVerifyOutput, getCurrentGitCommitHash, getGitStatusSummary, getGitWorktreeFingerprint } from "./verify.ts";
 import type {
 	TodoSdkClient,
@@ -70,6 +70,8 @@ export function runWithRuntimeState<T>(root: string, client: unknown, fn: () =>
 
 export let lastMutationTimestamp = 0;
 export let mutationCount = 0;
+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>();
 
@@ -82,6 +84,9 @@ export const sessionReviews = new Map<string, ReviewResult>();
 export function recordMutation(sessionID?: string, actorSessionID?: string): void {
 	lastMutationTimestamp = Date.now();
 	mutationCount++;
+	const workspace = projectRootKey(runtimeState.getStore()?.workspaceRoot ?? getWorkspaceRoot());
+	workspaceMutationTimestamps.set(workspace, lastMutationTimestamp);
+	workspaceMutationCounts.set(workspace, (workspaceMutationCounts.get(workspace) ?? 0) + 1);
 	for (const id of new Set([sessionID, actorSessionID].filter((value): value is string => Boolean(value)))) {
 		sessionMutationTimestamps.set(id, lastMutationTimestamp);
 		sessionMutationCounts.set(id, (sessionMutationCounts.get(id) ?? 0) + 1);
@@ -108,10 +113,26 @@ export function getLastMutationTimestamp(): number {
 	return lastMutationTimestamp;
 }
 
+export function getWorkspaceMutationTimestamp(root: string): number {
+	return workspaceMutationTimestamps.get(projectRootKey(root)) ?? 0;
+}
+
+export function getWorkspaceMutationCount(root: string): number {
+	return workspaceMutationCounts.get(projectRootKey(root)) ?? 0;
+}
+
 export function getLastVerifyResult(): typeof lastVerify {
 	return lastVerify;
 }
 
+export function getLastVerifyResultForWorkspace(root: string): typeof lastVerify {
+	const workspace = projectRootKey(root);
+	const candidates = [lastVerify, ...sessionVerifyResults.values()].filter(
+		(result): result is NonNullable<VerifyResult> => result?.workspaceRoot != null && projectRootKey(result.workspaceRoot) === workspace,
+	);
+	return candidates.reduce<NonNullable<VerifyResult> | undefined>((latest, result) => !latest || result.timestamp > latest.timestamp ? result : latest, undefined);
+}
+
 export function recordVerifyResult(
 	command: string,
 	result: { passed: boolean; output: string; durationMs?: number },
@@ -126,7 +147,8 @@ export function recordVerifyResult(
 		durationMs: result.durationMs,
 		commitHash: getCurrentGitCommitHash(root),
 		gitStatus: getGitStatusSummary(root),
-		workspaceRoot: resolve(root),
+		workspaceRoot: projectRootKey(root),
+		worktreeFingerprint: getGitWorktreeFingerprint(root),
 	};
 	if (sessionID && lastVerify) sessionVerifyResults.set(sessionID, lastVerify);
 	persistVerifyHistory(lastVerify);
@@ -145,6 +167,8 @@ export function resetVerifyState(): void {
 	lastVerify = undefined;
 	sessionMutationTimestamps.clear();
 	sessionMutationCounts.clear();
+	workspaceMutationTimestamps.clear();
+	workspaceMutationCounts.clear();
 	sessionVerifyResults.clear();
 }
 
@@ -155,7 +179,7 @@ export function recordReviewResult(
 	targetSessionID?: string,
 	workspace?: string,
 ): void {
-	const root = resolve(workspace ?? getWorkspaceRoot());
+	const root = projectRootKey(workspace ?? getWorkspaceRoot());
 	lastReview = {
 		reviewer,
 		summary: summary.slice(-4000),
@@ -174,6 +198,14 @@ export function getLastReviewResult(): typeof lastReview {
 	return lastReview;
 }
 
+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,
+	);
+	return candidates.reduce<ReviewResult | undefined>((latest, result) => !latest || result.timestamp > latest.timestamp ? result : latest, undefined);
+}
+
 export function resetReviewState(): void {
 	lastReview = undefined;
 	sessionReviews.clear();
@@ -181,8 +213,8 @@ export function resetReviewState(): void {
 
 export function getProjectConfig(root: string): ProjectConfig {
 	const active = runtimeState.getStore();
-	if (active?.workspaceRoot === root) return active.projectConfig;
-	return getCachedProjectConfig() ?? loadProjectConfig(root);
+	if (active && projectRootKey(active.workspaceRoot) === projectRootKey(root)) return active.projectConfig;
+	return getCachedProjectConfig(root) ?? loadProjectConfig(root);
 }
 
 export function isReviewRequired(root: string): boolean {
@@ -197,6 +229,25 @@ export function isDocumentationRequired(root: string): boolean {
 	return cfg.requireDocumentation === true;
 }
 
+export function getOperationProfile(root: string): "interactive" | "autonomous" {
+	return getProjectConfig(root).profile === "autonomous" ? "autonomous" : "interactive";
+}
+
+export function isRecoveryCheckpointsEnabled(root: string): boolean {
+	const cfg = getProjectConfig(root);
+	return cfg.recoveryCheckpoints ?? getOperationProfile(root) === "autonomous";
+}
+
+export function isRalphModeEnabled(root: string): boolean {
+	return getProjectConfig(root).ralphMode === true;
+}
+
+export function getRalphMaxIterations(root: string): number {
+	const configured = getProjectConfig(root).ralphMaxIterations;
+	if (typeof configured === "number" && Number.isInteger(configured) && configured > 0 && configured <= 100) return configured;
+	return 10;
+}
+
 export function getSubagentMutationBudget(root: string): number {
 	if (process.env.WORKFLOW_GUARD_MAX_SUBAGENT_MUTATIONS) {
 		const parsed = parseInt(process.env.WORKFLOW_GUARD_MAX_SUBAGENT_MUTATIONS, 10);

package/src/lib/types.ts

@@ -24,6 +24,7 @@ export interface TodoSdkClient {
 }
 
 export interface ProjectConfig {
+	profile?: "interactive" | "autonomous";
 	protectedBranches?: string[];
 	verifyCommand?: string;
 	postEditValidators?: Array<{
@@ -37,10 +38,22 @@ export interface ProjectConfig {
 	projectMemory?: boolean;
 	learning?: boolean;
 	titleSettleWorkaround?: boolean;
+	ralphMode?: boolean;
+	ralphMaxIterations?: number;
 	maxSubagentMutations?: number;
 	maxLearningInterventions?: number;
 }
 
+export type PolicyDecisionStatus = "allowed" | "blocked" | "needs_approval" | "verification_failed";
+
+export interface PolicyDecision {
+	status: PolicyDecisionStatus;
+	code: string;
+	policy?: string;
+	message: string;
+	details?: Record<string, unknown>;
+}
+
 export interface VerifyResult {
 	passed: boolean;
 	command: string;
@@ -50,6 +63,7 @@ export interface VerifyResult {
 	commitHash?: string;
 	gitStatus?: string;
 	workspaceRoot?: string;
+	worktreeFingerprint?: string;
 }
 
 export interface ReviewResult {
@@ -64,12 +78,33 @@ export interface ReviewResult {
 	worktreeFingerprint?: string;
 }
 
+export type EvidenceConfidence = "deterministic_observation" | "attestation" | "derived_state" | "agent_assertion";
+
+export interface EvidenceRecord {
+	id: string;
+	kind: "verification" | "review" | "tool_outcome" | "policy_evaluation" | "lifecycle_state" | "agent_assertion";
+	confidence: EvidenceConfidence;
+	observedAt: number;
+	subject: {
+		workspace?: string;
+		commitHash?: string;
+		worktreeFingerprint?: string;
+		sessionID?: string;
+		callID?: string;
+		actor?: string;
+	};
+	source: Record<string, unknown>;
+}
+
+export type EvidenceSubject = EvidenceRecord["subject"];
+
 export interface AuditEntry {
 	ts: string;
 	sessionID?: string;
 	callID?: string;
 	tool: string;
 	decision: "allow" | "block";
+	policyDecision?: PolicyDecision;
 	phase?: "decision" | "outcome" | "event";
 	durationMs?: number;
 	reason?: string;

package/src/policies/boundary.ts

@@ -317,6 +317,7 @@ export function detectShellMutation(command: string): ShellMutation | undefined
 export async function guardShellMutation(
 	command: string,
 	sessionID: string | undefined,
+	record = true,
 ): Promise<string | undefined> {
 	const root = getWorkspaceRoot();
 	let hasMutation = false;
@@ -383,7 +384,7 @@ export async function guardShellMutation(
 			}
 		}
 	}
-	if (hasMutation) {
+	if (hasMutation && record) {
 		recordMutation(await effectiveTodoOwnerSessionID(sessionID), sessionID);
 	}
 	return undefined;

package/src/policies/completion.ts

@@ -1,5 +1,8 @@
-import { sessionVerifyResults, lastVerify, sessionMutationTimestamps, lastMutationTimestamp } from "../lib/state.ts";
+import { isEvidenceFresh, verificationEvidence } from "../lib/evidence.ts";
+import { projectRootKey } from "../lib/project-config.ts";
+import { getWorkspaceRoot, sessionVerifyResults, lastVerify, sessionMutationTimestamps, lastMutationTimestamp } from "../lib/state.ts";
 import type { VerifyResult } from "../lib/types.ts";
+import { getCurrentGitCommitHash, getGitWorktreeFingerprint } from "../lib/verify.ts";
 
 /**
  * Claims-vs-evidence check (Policy 24): when the assistant's final text
@@ -60,7 +63,12 @@ export function checkCompletionClaims(
 	} else if (!verifyResult.passed) {
 		evidenceState = "failing";
 	} else if (
-		verifyResult.timestamp < mutationTimestamp ||
+		!isEvidenceFresh(verificationEvidence(verifyResult, context?.sessionID), {
+			workspace: projectRootKey(getWorkspaceRoot()),
+			commitHash: getCurrentGitCommitHash(getWorkspaceRoot()),
+			worktreeFingerprint: getGitWorktreeFingerprint(getWorkspaceRoot()),
+			sessionID: context?.sessionID,
+		}, mutationTimestamp) ||
 		Date.now() - verifyResult.timestamp > VERIFICATION_FRESH_WINDOW_MS
 	) {
 		evidenceState = "stale-pass";

package/src/policies/continuation.ts

@@ -1,17 +1,22 @@
 import { randomUUID } from "node:crypto";
-import { getSdkClient } from "../lib/state.ts";
+import { getRalphMaxIterations, getSdkClient, getWorkspaceRoot, isRalphModeEnabled } from "../lib/state.ts";
+import { projectRootKey } from "../lib/project-config.ts";
 import { effectiveTodosWithOwner, hasActiveTodo } from "./todo.ts";
 
 const MAX_CONSECUTIVE_CONTINUATIONS = 3;
+const MAX_GENERATED_MESSAGE_IDS = 100;
 const TITLE_SETTLE_MS = 250;
 const TITLE_SETTLE_ATTEMPTS = 8;
 const DEFAULT_SESSION_TITLE = /^(?:New session - |Child session - )\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
 type ContinuationState = {
 	counts: Map<string, number>;
+	ralphOutcomes: Map<string, RalphOutcome>;
 	generatedMessageIDs: Map<string, Set<string>>;
+	lastUserMessageIDs: Map<string, string>;
 	inFlight: Set<string>;
 };
-const states = new WeakMap<object, ContinuationState>();
+export type RalphOutcome = "running" | "completed" | "blocked" | "budget_exhausted" | "user_stopped";
+const states = new WeakMap<object, Map<string, ContinuationState>>();
 
 export async function waitForSessionTitle(sessionID: string): Promise<void> {
 	const session = getSdkClient()?.session;
@@ -30,10 +35,16 @@ export async function waitForSessionTitle(sessionID: string): Promise<void> {
 function getState(): ContinuationState | undefined {
 	const client = getSdkClient();
 	if (!client || (typeof client !== "object" && typeof client !== "function")) return undefined;
-	let state = states.get(client as object);
+	let clientStates = states.get(client as object);
+	if (!clientStates) {
+		clientStates = new Map();
+		states.set(client as object, clientStates);
+	}
+	const root = projectRootKey(getWorkspaceRoot());
+	let state = clientStates.get(root);
 	if (!state) {
-		state = { counts: new Map(), generatedMessageIDs: new Map(), inFlight: new Set() };
-		states.set(client as object, state);
+		state = { counts: new Map(), ralphOutcomes: new Map(), generatedMessageIDs: new Map(), lastUserMessageIDs: new Map(), inFlight: new Set() };
+		clientStates.set(root, state);
 	}
 	return state;
 }
@@ -43,19 +54,33 @@ export async function continueUnfinishedSession(sessionID: string, settleTitle =
 	if (!state || state.inFlight.has(sessionID)) return false;
 	state.inFlight.add(sessionID);
 	try {
+		const ralph = isRalphModeEnabled(getWorkspaceRoot());
+		if (ralph && state.ralphOutcomes.get(sessionID) === "user_stopped") return false;
 		const effective = await effectiveTodosWithOwner(sessionID);
-		if (!effective || effective.ownerSessionID !== sessionID || !hasActiveTodo(effective.todos)) return false;
+		if (!effective || effective.ownerSessionID !== sessionID || !hasActiveTodo(effective.todos)) {
+			if (ralph && state.ralphOutcomes.has(sessionID)) state.ralphOutcomes.set(sessionID, "completed");
+			return false;
+		}
 		if (settleTitle) await waitForSessionTitle(sessionID);
 
 		const count = state.counts.get(sessionID) ?? 0;
-		if (count >= MAX_CONSECUTIVE_CONTINUATIONS) return false;
+		const maxContinuations = ralph ? getRalphMaxIterations(getWorkspaceRoot()) : MAX_CONSECUTIVE_CONTINUATIONS;
+		if (count >= maxContinuations) {
+			if (ralph) state.ralphOutcomes.set(sessionID, "budget_exhausted");
+			return false;
+		}
 
 		const session = getSdkClient()?.session;
 		if (typeof session?.promptAsync !== "function") return false;
 
 		const messageID = `workflow-guard-${randomUUID()}`;
 		state.counts.set(sessionID, count + 1);
+		if (ralph) state.ralphOutcomes.set(sessionID, "running");
 		const generatedIDs = state.generatedMessageIDs.get(sessionID) ?? new Set<string>();
+		if (generatedIDs.size >= MAX_GENERATED_MESSAGE_IDS) {
+			const oldestID = generatedIDs.values().next().value;
+			if (oldestID) generatedIDs.delete(oldestID);
+		}
 		generatedIDs.add(messageID);
 		state.generatedMessageIDs.set(sessionID, generatedIDs);
 		try {
@@ -86,11 +111,18 @@ export function recordUserMessage(sessionID: string, messageID?: string): void {
 	const state = getState();
 	if (!state) return;
 	const generatedIDs = state.generatedMessageIDs.get(sessionID);
-	if (messageID && generatedIDs?.delete(messageID)) {
-		if (generatedIDs.size === 0) state.generatedMessageIDs.delete(sessionID);
-		return;
-	}
+	if (messageID && generatedIDs?.has(messageID)) return;
+	if (messageID && state.lastUserMessageIDs.get(sessionID) === messageID) return;
+	if (messageID) state.lastUserMessageIDs.set(sessionID, messageID);
 	state.counts.delete(sessionID);
+	if (isRalphModeEnabled(getWorkspaceRoot()) && state.ralphOutcomes.has(sessionID)) {
+		if (state.ralphOutcomes.get(sessionID) === "user_stopped") state.ralphOutcomes.delete(sessionID);
+		else state.ralphOutcomes.set(sessionID, "user_stopped");
+	}
+}
+
+export function getRalphOutcome(sessionID: string): RalphOutcome | undefined {
+	return getState()?.ralphOutcomes.get(sessionID);
 }
 
 export function isGeneratedContinuationMessage(sessionID: string, messageID?: string): boolean {
@@ -102,6 +134,8 @@ export function clearContinuationState(sessionID: string): void {
 	const state = getState();
 	if (!state) return;
 	state.counts.delete(sessionID);
+	state.ralphOutcomes.delete(sessionID);
 	state.generatedMessageIDs.delete(sessionID);
+	state.lastUserMessageIDs.delete(sessionID);
 	state.inFlight.delete(sessionID);
 }

package/src/policies/file-claims.ts

@@ -33,15 +33,22 @@ export function canonicalPath(path: string, seen = new Set<string>()): string {
 
 export function claimFiles(paths: string[], sessionID: string, callID: string): string | undefined {
 	const canonical = [...new Set(paths.map((path) => canonicalPath(path)))];
+	const conflict = fileClaimConflictReason(canonical, sessionID);
+	if (conflict) return conflict;
 	for (const path of canonical) {
-		const existing = claims.get(path);
-		if (existing && existing.sessionID !== sessionID) {
-			return `Blocked: file '${path}' is claimed by another active session ('${existing.sessionID}'). Wait for that edit to finish or use an isolated worktree.`;
+		if (!claims.has(path)) {
+			claims.set(path, { sessionID, callID });
 		}
 	}
+	return undefined;
+}
+
+export function fileClaimConflictReason(paths: string[], sessionID: string): string | undefined {
+	const canonical = [...new Set(paths.map((path) => canonicalPath(path)))];
 	for (const path of canonical) {
-		if (!claims.has(path)) {
-			claims.set(path, { sessionID, callID });
+		const existing = claims.get(path);
+		if (existing && existing.sessionID !== sessionID) {
+			return `Blocked: file '${path}' is claimed by another active session ('${existing.sessionID}'). Wait for that edit to finish or use an isolated worktree.`;
 		}
 	}
 	return undefined;

package/src/policies/git.ts

@@ -195,6 +195,7 @@ export function branchGuardReason(): string {
 export function isBranchAlreadyMergedOrClosed(
 	root: string,
 	branch: string,
+	checkRemotePrs = true,
 ): { merged: boolean; reason?: string } {
 	if (!branch || PROTECTED_BRANCHES.has(branch)) {
 		return { merged: false };
@@ -220,6 +221,7 @@ export function isBranchAlreadyMergedOrClosed(
 			}
 		}
 	}
+	if (!checkRemotePrs) return { merged: false };
 
 	try {
 		const ghRes = spawnSync(

package/src/workflow-guard-ui.ts

@@ -31,7 +31,7 @@ function text(props: Record<string, unknown>, children: Child[]) {
 
 const BADGE_ACTIVE = "Workflow Guard 🛡️";
 
-type ProjectToggle = "recoveryCheckpoints" | "projectMemory" | "learning" | "titleSettleWorkaround";
+type ProjectToggle = "recoveryCheckpoints" | "projectMemory" | "learning" | "titleSettleWorkaround" | "ralphMode";
 
 export function readProjectOption(root: string, option: ProjectToggle): boolean {
 	const path = projectConfigPath(root);
@@ -88,6 +88,7 @@ export const WorkflowGuardTui: TuiPlugin = async (api) => {
 				const memory = readProjectOption(root, "projectMemory");
 				const learning = readProjectOption(root, "learning");
 				const titleSettle = readProjectOption(root, "titleSettleWorkaround");
+				const ralphMode = readProjectOption(root, "ralphMode");
 				api.ui.dialog.replace(() => api.ui.DialogSelect({
 					title: "Workflow Guard Project Options",
 					current: undefined,
@@ -96,6 +97,7 @@ export const WorkflowGuardTui: TuiPlugin = async (api) => {
 						{ title: `Project memory: ${memory ? "On" : "Off"}`, value: "projectMemory", description: "Toggle durable local project memory" },
 						{ title: `Learner mode: ${learning ? "On" : "Off"}`, value: "learning", description: "Toggle evidence-based learning tools" },
 						{ title: `Title settle workaround: ${titleSettle ? "On" : "Off"}`, value: "titleSettleWorkaround", description: "Delay automatic continuation while OpenCode generates a session title" },
+						{ title: `Ralph mode: ${ralphMode ? "On" : "Off"}`, value: "ralphMode", description: "Opt into bounded autonomous continuation of already-owned todos" },
 					],
 					onSelect: (option) => {
 						const key = option.value as ProjectToggle;

package/src/workflow-guard.ts

@@ -19,7 +19,7 @@ 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 type { TodoSdkClient } from "./lib/types.ts";
+import type { PolicyDecision, TodoSdkClient } from "./lib/types.ts";
 export { isReadOnlyRole } from "./lib/guard-dispatcher.ts";
 export { extractReviewFollowups } from "./lib/custom-tools.ts";
 
@@ -30,6 +30,11 @@ export type {
 	VerifyResult,
 	ReviewResult,
 	AuditEntry,
+	PolicyDecision,
+	PolicyDecisionStatus,
+	EvidenceRecord,
+	EvidenceConfidence,
+	EvidenceSubject,
 	GitInvocation,
 	ShellMutation,
 	LearnerProfile,
@@ -37,6 +42,8 @@ export type {
 	LearningOpportunity,
 } from "./lib/types.ts";
 export type { TodoSdkClient };
+export { verificationEvidence, reviewEvidence, toolOutcomeEvidence, policyDecisionEvidence, lifecycleStateEvidence, agentAssertionEvidence, evidenceMatchesSubject, isEvidenceFresh } from "./lib/evidence.ts";
+export { getRalphOutcome } from "./policies/continuation.ts";
 
 // ── State & runtime context ──────────────────────────────────────────────────
 import {
@@ -57,6 +64,8 @@ import {
 	sessionMutationTimestamps,
 	sessionVerifyResults,
 	getProjectConfig,
+	getOperationProfile,
+	isRecoveryCheckpointsEnabled,
 	isReviewRequired,
 	isDocumentationRequired,
 	getSubagentMutationBudget,
@@ -83,6 +92,8 @@ export {
 	loadProjectConfig,
 	reloadProjectConfig,
 	stripJsonComments,
+	getOperationProfile,
+	isRecoveryCheckpointsEnabled,
 	isReviewRequired,
 	isDocumentationRequired,
 	getSubagentMutationBudget,
@@ -293,20 +304,28 @@ function logObservation(client: unknown, message: string): void {
  * Public guard entry point. Audits every decision (block or allow) to a
  * durable JSONL file before returning.
  */
-export async function guardToolCall(
+export async function guardToolDecision(
 	toolName: string,
 	input: unknown,
 	context?: { sessionID?: string; callID?: string; worktree?: string; directory?: string; agent?: string },
-): Promise<string | undefined> {
+): Promise<PolicyDecision> {
 	const customRoot = context?.worktree || context?.directory;
 	const runImpl = () => guardToolCallImpl(toolName, input, context);
-	const reason = customRoot
+	return customRoot
 		? await runWithRuntimeState(customRoot, getSdkClient(), runImpl)
 		: await runImpl();
+}
+
+export async function guardToolCall(
+	toolName: string,
+	input: unknown,
+	context?: { sessionID?: string; callID?: string; worktree?: string; directory?: string; agent?: string },
+): Promise<string | undefined> {
+	const decision = await guardToolDecision(toolName, input, context);
 	const allowLive = process.env.WORKFLOW_GUARD_ALLOW_LIVE === "1";
 	const isMutation = EDIT_TOOL_NAMES.has(toolName);
 	const targetPath = extractRecordTargetPath(input);
-	logDecision(toolName, input, context, reason, {
+	logDecision(toolName, input, context, decision, {
 		mutation: isMutation,
 		targetPath,
 		allowLive,
@@ -319,7 +338,7 @@ export async function guardToolCall(
 				}
 			: undefined,
 	});
-	return reason;
+	return decision.status === "allowed" ? undefined : decision.message;
 }
 
 async function emitBlockFeedback(message: string): Promise<void> {
@@ -597,7 +616,7 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 		},
 
 		"chat.message": async (input) => {
-			if (getProjectConfig(effectiveRoot).recoveryCheckpoints !== true) return;
+			if (!isRecoveryCheckpointsEnabled(effectiveRoot)) return;
 			if (isGeneratedContinuationMessage(input.sessionID, input.messageID)) return;
 			const parent = await runWithRuntimeState(effectiveRoot, ctx.client, () => fetchParentSession(input.sessionID));
 			if (!parent.ok || parent.parentID) return;