opencode-workflow-guard 1.8.5 → 1.8.7

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.5",
+  "version": "1.8.7",
   "description": "Deterministic workflow and safety policy enforcement for OpenCode",
   "license": "MIT",
   "type": "module",

package/src/lib/custom-tools.ts

@@ -24,13 +24,14 @@ import {
 	isReviewRequired,
 	recordMutation,
 	recordReviewResult,
+	runWithRuntimeState,
 } from "./state.ts";
 import { loadProjectConfig } from "./project-config.ts";
 import { detectVerifyCommand, getCurrentGitCommitHash } from "./verify.ts";
 import { buildReviewRubric } from "./review.ts";
 import { createGitWorktree, cleanupGitWorktree } from "./worktree.ts";
 import { restoreRecoveryCheckpoint } from "./checkpoint.ts";
-import { getRecentAuditEntries } from "./audit.ts";
+import { audit, getRecentAuditEntries } from "./audit.ts";
 import { guardToolCallImpl } from "./guard-dispatcher.ts";
 import { discoverPlanningSources } from "../policies/planning.ts";
 import { secretIn } from "../policies/secrets.ts";
@@ -53,8 +54,9 @@ 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 ? {
 			guard_recovery_restore: tool({
@@ -154,14 +156,16 @@ export function createCustomTools(options: {
 			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 parentSessionID = await fetchParentSessionID(toolContext.sessionID);
-				if (!parentSessionID) return "[workflow-guard] Review rejected: record_review must be called from a secondary/subagent session.";
+				const auditVerdict = (verdict: "approved" | "changes_requested" | "rejected", reason: string) => audit({ ts: new Date().toISOString(), sessionID: toolContext.sessionID, tool: "record_review.verdict", decision: verdict === "rejected" ? "block" : "allow", phase: "event", reason, evidence: { reviewVerdict: verdict } });
+				const parentSessionID = await runWithRuntimeState(effectiveRoot, client, () => fetchParentSessionID(toolContext.sessionID));
+				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));
-				if (referenced.length < 3) return `[workflow-guard] Review rejected: summary must reference the review axes (found ${referenced.length}/5). Call guard_review_rubric to get the rubric, evaluate each axis, and include findings per axis in the summary.`;
-				if (args.passed && /(?:^|\s)(?:\[p[01]\]|p[01]\s*:\s*(?:blocker|defect|vulnerability|error|bug|issue)|p[01]\s+blocker)/i.test(args.summary)) return "[workflow-guard] Review rejected: cannot record approval when P0 or P1 blockers are flagged in findings. Resolve all P0/P1 issues before approving or record review with passed=false.";
+				if (referenced.length < 3) { auditVerdict("rejected", "insufficient_rubric_axes"); return `[workflow-guard] Review rejected: summary must reference the review axes (found ${referenced.length}/5). Call guard_review_rubric to get the rubric, evaluate each axis, and include findings per axis in the summary.`; }
+				if (args.passed && /(?:^|\s)(?:\[p[01]\]|p[01]\s*:\s*(?:blocker|defect|vulnerability|error|bug|issue)|p[01]\s+blocker)/i.test(args.summary)) { auditVerdict("rejected", "approval_contains_blocker"); return "[workflow-guard] Review rejected: cannot record approval when P0 or P1 blockers are flagged in findings. Resolve all P0/P1 issues before approving or record review with passed=false."; }
 				recordReviewResult(args.reviewer, args.summary, args.passed, parentSessionID, toolContext.worktree || toolContext.directory);
 				if (followupStore && !secretIn(args.summary)) for (const finding of extractReviewFollowups(args.summary)) recordReviewFollowup(followupStore, { severity: finding.severity, summary: finding.summary, reviewer: args.reviewer, sessionID: toolContext.sessionID, commit: getCurrentGitCommitHash(effectiveRoot) });
+				auditVerdict(args.passed ? "approved" : "changes_requested", args.passed ? "approved" : "changes_requested");
 				return args.passed ? `[workflow-guard] Review recorded as APPROVED by ${args.reviewer}.` : `[workflow-guard] Review recorded as CHANGES REQUESTED by ${args.reviewer}.`;
 			},
 		}),

package/src/lib/types.ts

@@ -9,7 +9,7 @@ export interface TodoSdkClient {
 	};
 	session?: {
 		todo?: (opts: { path: { id: string } }) => Promise<{ data?: unknown }>;
-		get?: (opts: { path: { id: string } }) => Promise<{ data?: { parentID?: unknown } }>;
+		get?: (opts: { path: { id: string } }) => Promise<{ data?: { parentID?: unknown; title?: unknown } }>;
 		promptAsync?: (opts: {
 			path: { id: string };
 			body: { messageID?: string; parts: Array<{ type: "text"; text: string; synthetic?: boolean }> };
@@ -36,6 +36,7 @@ export interface ProjectConfig {
 	recoveryCheckpoints?: boolean;
 	projectMemory?: boolean;
 	learning?: boolean;
+	titleSettleWorkaround?: boolean;
 	maxSubagentMutations?: number;
 	maxLearningInterventions?: number;
 }
@@ -83,6 +84,7 @@ export interface AuditEntry {
 			durationMs?: number;
 		};
 		allowLive?: boolean;
+		reviewVerdict?: "approved" | "changes_requested" | "rejected";
 	};
 }
 

package/src/policies/continuation.ts

@@ -3,6 +3,9 @@ import { getSdkClient } from "../lib/state.ts";
 import { effectiveTodosWithOwner, hasActiveTodo } from "./todo.ts";
 
 const MAX_CONSECUTIVE_CONTINUATIONS = 3;
+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>;
 	generatedMessageIDs: Map<string, Set<string>>;
@@ -10,6 +13,20 @@ type ContinuationState = {
 };
 const states = new WeakMap<object, ContinuationState>();
 
+export async function waitForSessionTitle(sessionID: string): Promise<void> {
+	const session = getSdkClient()?.session;
+	if (typeof session?.get !== "function") return;
+	for (let attempt = 0; attempt < TITLE_SETTLE_ATTEMPTS; attempt++) {
+		try {
+			const current = (await session.get({ path: { id: sessionID } }))?.data;
+			if (current?.parentID || typeof current?.title !== "string" || !DEFAULT_SESSION_TITLE.test(current.title)) return;
+		} catch {
+			return;
+		}
+		if (attempt + 1 < TITLE_SETTLE_ATTEMPTS) await new Promise((resolve) => setTimeout(resolve, TITLE_SETTLE_MS));
+	}
+}
+
 function getState(): ContinuationState | undefined {
 	const client = getSdkClient();
 	if (!client || (typeof client !== "object" && typeof client !== "function")) return undefined;
@@ -21,13 +38,14 @@ function getState(): ContinuationState | undefined {
 	return state;
 }
 
-export async function continueUnfinishedSession(sessionID: string): Promise<boolean> {
+export async function continueUnfinishedSession(sessionID: string, settleTitle = false): Promise<boolean> {
 	const state = getState();
 	if (!state || state.inFlight.has(sessionID)) return false;
 	state.inFlight.add(sessionID);
 	try {
 		const effective = await effectiveTodosWithOwner(sessionID);
-		if (!effective || !hasActiveTodo(effective.todos) || effective.ownerSessionID !== sessionID) return false;
+		if (!effective || effective.ownerSessionID !== sessionID || !hasActiveTodo(effective.todos)) return false;
+		if (settleTitle) await waitForSessionTitle(sessionID);
 
 		const count = state.counts.get(sessionID) ?? 0;
 		if (count >= MAX_CONSECUTIVE_CONTINUATIONS) return false;

package/src/policies/todo.ts

@@ -97,14 +97,39 @@ export function validateTodoLifecycle(
 			return s === "pending" || s === "in_progress";
 		});
 		if (activeExisting.length > 0) {
+			const activeNew = newTodos.filter((t) => ACTIVE_TODO_STATUSES.has(String(t.status ?? "")));
+			const reviewObligation = /\b(?:secondary\s+review|re-?review|reviewer|(?:run|perform|request|obtain|complete)\s+(?:an?\s+)?review)\b/i;
+			const remediationAction = /\b(?:address|fix|resolve|remediate)\b/i;
+			const reviewReference = /\b(?:secondary\s+review|re-?review|reviewer|review)\b/i;
+			const remediationSubject = /\b(?:findings?|feedback|comments?|issues?)\b/i;
+			const isReviewObligation = (content: string) => reviewObligation.test(content) && !(remediationAction.test(content) && reviewReference.test(content) && remediationSubject.test(content));
 			const newContentCounts = new Map<string, number>();
 			for (const todo of newTodos) {
 				const content = String(todo.content ?? "").trim();
 				newContentCounts.set(content, (newContentCounts.get(content) ?? 0) + 1);
 			}
+			const retainedReviewCounts = new Map<string, number>();
+			for (const todo of activeNew) {
+				const content = String(todo.content ?? "").trim();
+				retainedReviewCounts.set(content, (retainedReviewCounts.get(content) ?? 0) + 1);
+			}
+			let retainedReviewObligations = 0;
+			for (const todo of activeExisting) {
+				const content = String(todo.content ?? "").trim();
+				const remaining = retainedReviewCounts.get(content) ?? 0;
+				if (remaining > 0 && isReviewObligation(content)) {
+					retainedReviewCounts.set(content, remaining - 1);
+					retainedReviewObligations++;
+				}
+			}
+			let replacementReviewObligations = activeNew.filter((t) => isReviewObligation(String(t.content ?? ""))).length - retainedReviewObligations;
 			const missing = activeExisting.find((todo) => {
 				const content = String(todo.content ?? "").trim();
 				const remaining = newContentCounts.get(content) ?? 0;
+				if (remaining === 0 && isReviewObligation(content) && replacementReviewObligations > 0) {
+					replacementReviewObligations--;
+					return false;
+				}
 				if (remaining === 0) return true;
 				newContentCounts.set(content, remaining - 1);
 				return false;

package/src/workflow-guard-ui.ts

@@ -1,5 +1,4 @@
 import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui";
-import type { BaseRenderable } from "@opentui/core";
 import type { JSX } from "@opentui/solid";
 import { createElement, insert, setProp } from "@opentui/solid";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -31,11 +30,10 @@ function text(props: Record<string, unknown>, children: Child[]) {
 }
 
 const BADGE_ACTIVE = "Workflow Guard 🛡️";
-const BLOCKED_BADGE_DURATION_MS = 5_000;
-let lastBlockedReason: string | undefined;
-const sessionBlockedReasons = new Map<string, string>();
 
-export function readProjectOption(root: string, option: "recoveryCheckpoints" | "projectMemory" | "learning"): boolean {
+type ProjectToggle = "recoveryCheckpoints" | "projectMemory" | "learning" | "titleSettleWorkaround";
+
+export function readProjectOption(root: string, option: ProjectToggle): boolean {
 	const path = projectConfigPath(root);
 	if (!existsSync(path)) return option === "projectMemory";
 	const errors: ParseError[] = [];
@@ -44,7 +42,7 @@ export function readProjectOption(root: string, option: "recoveryCheckpoints" |
 	return option === "projectMemory" ? config?.projectMemory !== false : config?.[option] === true;
 }
 
-function writeProjectOption(root: string, option: "recoveryCheckpoints" | "projectMemory" | "learning", enabled: boolean): string {
+function writeProjectOption(root: string, option: ProjectToggle, enabled: boolean): string {
 	const path = projectConfigPath(root);
 	const raw = existsSync(path) ? readFileSync(path, "utf8") : "{}\n";
 	const errors: ParseError[] = [];
@@ -72,29 +70,11 @@ export function writeRecoveryCheckpointsOption(root: string, enabled: boolean):
 	return writeProjectOption(root, "recoveryCheckpoints", enabled);
 }
 
-export function setLastBlockedReasonForTesting(reason: string | undefined): void {
-	lastBlockedReason = reason;
-	if (reason === undefined) sessionBlockedReasons.clear();
-}
-
-export function getLastBlockedReason(): string | undefined {
-	return lastBlockedReason;
-}
-
-export function formatBadge(sessionID?: string): { text: string; isBlocked: boolean } {
-	const reason = sessionID ? sessionBlockedReasons.get(sessionID) : lastBlockedReason;
-	if (!reason) {
-		return { text: BADGE_ACTIVE, isBlocked: false };
-	}
-	const cleanReason = reason.replace(/^\[workflow-guard\]\s*/i, "").replace(/^Blocked(?::|\s+)\s*/i, "");
-	const shortReason = cleanReason.length > 30 ? cleanReason.slice(0, 27) + "..." : cleanReason;
-	return { text: `[Workflow Guard: Blocked: ${shortReason}]`, isBlocked: true };
+export function formatBadge(): { text: string; isBlocked: boolean } {
+	return { text: BADGE_ACTIVE, isBlocked: false };
 }
 
 export const WorkflowGuardTui: TuiPlugin = async (api) => {
-	const badgeNodes = new Map<string, BaseRenderable>();
-	const blockedBadgeTimers = new Map<string, ReturnType<typeof setTimeout>>();
-
 	api.keymap.registerLayer({
 		commands: [{
 			name: "workflow-guard.project-options",
@@ -107,6 +87,7 @@ export const WorkflowGuardTui: TuiPlugin = async (api) => {
 				const recovery = readProjectOption(root, "recoveryCheckpoints");
 				const memory = readProjectOption(root, "projectMemory");
 				const learning = readProjectOption(root, "learning");
+				const titleSettle = readProjectOption(root, "titleSettleWorkaround");
 				api.ui.dialog.replace(() => api.ui.DialogSelect({
 					title: "Workflow Guard Project Options",
 					current: undefined,
@@ -114,9 +95,10 @@ export const WorkflowGuardTui: TuiPlugin = async (api) => {
 						{ title: `Recovery checkpoints: ${recovery ? "On" : "Off"}`, value: "recoveryCheckpoints", description: "Toggle durable pre-run Git checkpoints" },
 						{ 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" },
 					],
 					onSelect: (option) => {
-						const key = option.value as "recoveryCheckpoints" | "projectMemory" | "learning";
+						const key = option.value as ProjectToggle;
 						const enabled = !readProjectOption(root, key);
 						const path = writeProjectOption(root, key, enabled);
 						api.ui.dialog.clear();
@@ -128,67 +110,18 @@ export const WorkflowGuardTui: TuiPlugin = async (api) => {
 		bindings: [],
 	});
 
-	function scheduleBadgeReset(sessionID?: string): void {
-		const key = sessionID ?? "home";
-		const existing = blockedBadgeTimers.get(key);
-		if (existing) clearTimeout(existing);
-		blockedBadgeTimers.set(key, setTimeout(() => {
-			blockedBadgeTimers.delete(key);
-			if (sessionID) sessionBlockedReasons.delete(sessionID);
-			else lastBlockedReason = undefined;
-			const node = badgeNodes.get(key);
-			if (node) {
-				setProp(node, "content", BADGE_ACTIVE);
-				setProp(node, "fg", api.theme.current.success);
-			}
-		}, BLOCKED_BADGE_DURATION_MS));
-	}
-
-	try {
-		api.event.on("tui.toast.show", (e) => {
-			const title = e.properties.title;
-			const msg = e.properties.message;
-			if (title === "Workflow Guard Blocked" && typeof msg === "string") {
-				const route = api.route.current;
-				const sessionID =
-					route.name === "session" && typeof route.params?.sessionID === "string"
-						? route.params.sessionID
-						: undefined;
-				if (sessionID) sessionBlockedReasons.set(sessionID, msg);
-				else lastBlockedReason = msg;
-				const key = sessionID ?? "home";
-				const node = badgeNodes.get(key);
-				if (node) {
-					const badge = formatBadge(sessionID);
-					setProp(node, "content", badge.text);
-					setProp(node, "fg", badge.isBlocked ? api.theme.current.warning : api.theme.current.success);
-				}
-				scheduleBadgeReset(sessionID);
-			}
-		});
-	} catch {}
-
 	api.slots.register({
 		order: 1,
 		slots: {
 			home_prompt_right() {
 				const theme = api.theme.current;
 				const badge = formatBadge();
-				const node = text({ fg: badge.isBlocked ? theme.warning : theme.success }, [badge.text]);
-				badgeNodes.set("home", node as unknown as BaseRenderable);
-				return node;
+				return text({ fg: theme.success }, [badge.text]);
 			},
 			session_prompt_right() {
 				const theme = api.theme.current;
-				const route = api.route.current;
-				const sessionID =
-					route.name === "session" && typeof route.params?.sessionID === "string"
-						? route.params.sessionID
-						: undefined;
-				const badge = formatBadge(sessionID);
-				const node = text({ fg: badge.isBlocked ? theme.warning : theme.success }, [badge.text]);
-				if (sessionID) badgeNodes.set(sessionID, node as unknown as BaseRenderable);
-				return node;
+				const badge = formatBadge();
+				return text({ fg: theme.success }, [badge.text]);
 			},
 		},
 	});

package/src/workflow-guard.ts

@@ -371,7 +371,7 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 	const toolOutcomes = new ToolOutcomeTracker();
 
 	return {
-		tool: createCustomTools({ effectiveRoot, projectMemoryEnabled, learningEnabled, projectMemory, followupStore, portableMemoryPath, learningInterventions }),
+		tool: createCustomTools({ effectiveRoot, projectMemoryEnabled, learningEnabled, projectMemory, followupStore, portableMemoryPath, learningInterventions, client: ctx.client }),
 
 		"tool.execute.before": async (input, output) => {
 			const toolWorktree =
@@ -650,7 +650,8 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 					if (recoveryRun !== undefined) {
 						finalizeRecoveryCheckpoint(effectiveRoot, sessionID, recoveryRun);
 					}
-					await runWithRuntimeState(effectiveRoot, ctx.client, () => continueUnfinishedSession(sessionID));
+					const settleTitle = getProjectConfig(effectiveRoot).titleSettleWorkaround === true;
+					await runWithRuntimeState(effectiveRoot, ctx.client, () => continueUnfinishedSession(sessionID, settleTitle));
 				}
 			}
 			if (event?.type === "message.updated") {