opencode-workflow-guard 1.8.7 → 1.9.1

package/docs/troubleshooting.md

@@ -0,0 +1,84 @@
+# Troubleshooting Guide
+
+Common issues, root causes, and solutions when using `opencode-workflow-guard`.
+
+---
+
+### 1. `plugin config hook failed` / `Unexpected server error` on startup
+
+- **Symptoms:** OpenCode crashes or reports `Unexpected server error` when starting a session, with logs showing `TypeError: undefined is not an object (evaluating '...event')`.
+- **Root Cause:** OpenCode 1.18+'s legacy loader treats *every exported function* in a plugin module as a separate plugin instance. If a plugin exports helper functions (like `guardToolCall` or `setWorkspaceRoot`) alongside a default function, OpenCode calls them as plugins, pushes `undefined` into the hook registry, and crashes event dispatch on `session.created`.
+- **Solution:** Ensure `src/workflow-guard.ts` uses the V1 `PluginModule` export format (`export default { id: "workflow-guard", server: WorkflowGuard } satisfies PluginModule`). File plugins require an explicit `id` string.
+
+---
+
+### 2. Edits Blocked: `Blocked: no active todo item`
+
+- **Symptoms:** The agent attempts an edit (`edit`, `write`, `apply_patch`) and receives a block message directing it to create a task list.
+- **Root Cause:** Policy 1 blocks file-editing tools until the session's native todo list (`GET /session/:id/todo`) contains at least one task with status `pending` or `in_progress`.
+- **Solution:** The agent must call `todowrite` first. Once all tasks are marked `completed` or `cancelled`, edits will block again until a new breakdown is created for subsequent work.
+
+---
+
+### 3. Multiple tasks are `in_progress`
+
+- **Symptoms:** A task list contains multiple `in_progress` items during parallel work.
+- **Root Cause:** This is supported. Policy 1 permits multiple tasks to be `in_progress` so independent work and subagents can proceed concurrently.
+- **Solution:** No correction is required. Keep each active item in every replacement list until it is explicitly marked `completed` or `cancelled`.
+
+---
+
+### 4. `Blocked todowrite: active task '...' was removed`
+
+- **Symptoms:** `todowrite` is blocked after an active item disappears from the submitted list.
+- **Root Cause:** Each `todowrite` call replaces the complete list. Policy 1 therefore requires active tasks to be explicitly completed or cancelled rather than silently omitted. Independent items may otherwise be completed out of order.
+- **Solution:** Keep the task in the list and mark it `completed` or `cancelled` before removing it in a later request.
+
+---
+
+### 5. Edits Blocked: `Blocked: the workspace is on a protected branch (main/master)`
+
+- **Symptoms:** Direct edits or git commit/merge commands are rejected.
+- **Root Cause:** Policy 7 requires all code modifications to happen on a feature branch.
+- **Solution:** Switch to a feature branch (`git switch -c feat/my-feature`) before making changes.
+
+---
+
+### 6. Edits Blocked: `Blocked: file path '...' escapes workspace root`
+
+- **Symptoms:** Edits targeting files with `../` or external absolute paths are rejected.
+- **Root Cause:** Policy 8 prevents directory traversal outside the workspace root.
+- **Solution:** Ensure all target file paths resolve within the project directory.
+
+---
+
+### 7. Subagents Cannot Edit Files
+
+- **Symptoms:** A subagent spawned via `task` fails to edit files.
+- **Root Cause:** OpenCode disables `todowrite` for subagents by default.
+- **Solution:** The guard automatically walks up the `parentID` session hierarchy so subagents inherit the parent session's active tasks. Ensure the parent session has active tasks before a subagent attempts guarded mutations.
+
+---
+
+### 8. Destructive Commands Blocked (`kubectl`, `terraform`, `psql`, etc.)
+
+- **Symptoms:** A CLI command is rejected with a live-system mutation warning.
+- **Root Cause:** Policy 4 blocks destructive cloud, database, and infrastructure operations.
+- **Solution:** To intentionally run a live command, set `WORKFLOW_GUARD_ALLOW_LIVE=1` in the environment before launching OpenCode. There is no in-command override; an agent cannot grant this permission to itself.
+
+---
+
+### 9. TUI plugin is missing or remains on an older release
+
+- **Symptoms:** Workflow Guard does not appear in the TUI, or npm reports a newer Workflow Guard release while OpenCode still runs an older one.
+- **Root Cause:** OpenCode caches npm plugins. A bare package name is resolved as `@latest`, but an already-populated package cache can continue using the version that originally populated that cache key. Running `npm update` in `~/.config/opencode` does not update this OpenCode-managed plugin installation.
+- **Solution:** Use OpenCode's documented plugin installer with the explicit version you want. `--force` replaces the configured plugin version, and the explicit version gives OpenCode a new package-cache key:
+
+```bash
+VERSION=$(npm view opencode-workflow-guard version)
+opencode plugin "opencode-workflow-guard@$VERSION" --global --force
+```
+
+OpenCode documents `opencode plugin <module>` as installing a plugin and updating its config, with `--global` for global config and `--force` to replace an existing plugin version: https://opencode.ai/docs/cli/#plugin. Its plugin documentation also describes npm plugins as OpenCode-managed, cached installations: https://opencode.ai/docs/plugins/#how-plugins-are-installed.
+
+After the command reports `Detected server + tui targets`, confirm it reports replacements/additions for both the OpenCode and TUI config files, then restart OpenCode. Manual cache deletion should not be necessary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.8.7",
+  "version": "1.9.1",
   "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",
@@ -22,7 +22,10 @@
   },
   "files": [
     "bin/",
+    "docs/",
     "src/",
+    "test/",
+    "tsconfig.json",
     "README.md",
     "LICENSE",
     "ACKNOWLEDGEMENTS.md"

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