opencode-workflow-guard 1.8.6 → 1.9.0

package/README.md

@@ -23,7 +23,7 @@ opencode plugin "opencode-workflow-guard@$VERSION" --global --force
 
 *Requires OpenCode >= 1.18.* OpenCode detects the package's server and TUI targets and updates both global configs. Use the same command after a release to upgrade; the explicit version gives OpenCode a fresh package-cache key. Restart OpenCode after installation. See [docs/installation.md](docs/installation.md) for details and links to the OpenCode plugin documentation.
 
-For the optional TUI badge, configure `"opencode-workflow-guard"` in `tui.json`. OpenCode resolves the package's exported `./tui` entrypoint automatically for TUI plugins. The companion shows a `Workflow Guard` shield in the prompt bar and reflects blocked state without changing agent behavior. Do not place the TUI module under the server `plugins/` directory.
+For the optional TUI badge, configure `"opencode-workflow-guard"` in `tui.json`. OpenCode resolves the package's exported `./tui` entrypoint automatically for TUI plugins. The companion keeps a static `Workflow Guard` shield in the prompt bar; warning toasts provide block details without changing agent behavior. Do not place the TUI module under the server `plugins/` directory.
 
 ![Workflow Guard status badge in the OpenCode TUI](docs/assets/workflow-guard-tui-badge.png)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.8.6",
+  "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,23 +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";
@@ -53,10 +61,11 @@ export function createCustomTools(options: {
 	followupStore: ProjectMemoryStore | undefined;
 	portableMemoryPath: string;
 	learningInterventions: Map<string, number>;
+	client: unknown;
 }) {
-	const { effectiveRoot, projectMemoryEnabled, learningEnabled, projectMemory, followupStore, portableMemoryPath, learningInterventions } = 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() },
@@ -143,19 +152,33 @@ 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") },
 			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 fetchParentSessionID(toolContext.sessionID);
+				const parentSessionID = await runWithRuntimeState(effectiveRoot, client, () => fetchParentSessionID(toolContext.sessionID));
 				if (!parentSessionID) { auditVerdict("rejected", "missing_parent_session"); return "[workflow-guard] Review rejected: record_review must be called from a secondary/subagent session."; }
 				const axesRefs = ["test integrity", "task completeness", "cleanliness", "security", "platform"];
 				const referenced = axesRefs.filter((axis) => args.summary.toLowerCase().includes(axis));

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);
+}