opencode-workflow-guard 1.12.1 → 1.13.2

package/src/policies/boundary.ts

@@ -8,7 +8,7 @@ import {
 	recordMutation,
 } from "../lib/state.ts";
 import { shellWords, unwrapShellCommand } from "../lib/shell.ts";
-import { isProtectedPath, PROTECTED_PATH_REASON } from "./tamper.ts";
+import { isCollaborationInvocation, isProtectedPath, PROTECTED_PATH_REASON } from "./tamper.ts";
 import { isSecretPath, secretIn } from "./secrets.ts";
 import { onProtectedBranch, branchGuardReason } from "./git.ts";
 import {
@@ -129,14 +129,22 @@ export function teeTargetsIn(segment: string): string[] {
 
 function redirectMutationsIn(segment: string): ShellMutation[] {
 	const mutations: ShellMutation[] = [];
-	const redirectRe = /(?:^|[\s>]|(?<=[^\s"']))([0-9]*&?>>?&?)\s*["']?([^\s>&|;"']+)/g;
+	// The `(?!=)` lookahead after the op rejects comparison operators (`>=`,
+	// `==`) so they cannot match as a redirect op with `=` as its target.
+	const redirectRe = /(?:^|[\s>]|(?<=[^\s"']))([0-9]*&?>>?&?(?!=))\s*["']?([^\s>&|;"']+)/g;
 	for (const redirectMatch of segment.matchAll(redirectRe)) {
 		if (!redirectMatch[1] || !redirectMatch[2]) continue;
 		const op = redirectMatch[1];
 		const target = redirectMatch[2];
 		// Filter fd duplication (e.g. 2>&1, >&2) where target is purely an fd number
 		const isFdDup = op.endsWith("&") && /^\d+$/.test(target);
-		if (!isFdDup && !/^\/dev\/(?:null|stdout|stderr|tty|fd\/\d+)$/.test(target)) {
+		// Filter comparison operands from embedded non-shell syntax (SQL, awk,
+		// test expressions): `WHERE count > 5`, `x >= 10`. A bare `>` whose
+		// target is purely numeric is overwhelmingly a comparison operand, not
+		// a redirect into a numeric filename. `>>` and fd forms (`2>`) keep
+		// redirect semantics.
+		const isComparisonOperand = op === ">" && /^\d+$/.test(target);
+		if (!isFdDup && !isComparisonOperand && !/^\/dev\/(?:null|stdout|stderr|tty|fd\/\d+)$/.test(target)) {
 			mutations.push({
 				kind: "redirect",
 				target,
@@ -303,8 +311,17 @@ export function secretSourceInFilesystemCommand(segment: string): string | undef
 	return undefined;
 }
 
+// Remove single- and double-quoted spans from a shell segment. Used to
+// analyze the residue of collaboration invocations: quoted arguments are
+// command data and can never be shell redirects, while unquoted redirects
+// keep receiving full validation.
+function stripQuotedSpans(segment: string): string {
+	return segment.replace(/'[^'\n]*'/g, " ").replace(/"[^"\n]*"/g, " ");
+}
+
 export function detectShellMutation(command: string): ShellMutation | undefined {
-	for (const segment of command.split(/[\n|;&]+/)) {
+	for (const rawSegment of command.split(/[\n|;&]+/)) {
+		const segment = isCollaborationInvocation(rawSegment) ? stripQuotedSpans(rawSegment) : rawSegment;
 		const simpleMutations = simpleFilesystemMutations(segment);
 		if (simpleMutations.length > 0) return simpleMutations[0];
 		const teeTargets = teeTargetsIn(segment);
@@ -328,7 +345,11 @@ export async function guardShellMutation(
 ): Promise<string | undefined> {
 	const root = getWorkspaceRoot();
 	let hasMutation = false;
-	for (const segment of command.split(/[\n|;&]+/)) {
+	for (const rawSegment of command.split(/[\n|;&]+/)) {
+		// Same residue analysis as detectShellMutation: quoted arguments of
+		// gh/glab/az PR/issue commands are command data, not shell redirects,
+		// while unquoted redirects still get full validation below.
+		const segment = isCollaborationInvocation(rawSegment) ? stripQuotedSpans(rawSegment) : rawSegment;
 		const secretSource = secretSourceInFilesystemCommand(segment);
 		if (secretSource) {
 			return `Blocked: shell command would copy, move, or link sensitive file '${secretSource}' under a non-secret name.`;

package/src/policies/continuation.ts

@@ -14,6 +14,7 @@ type ContinuationState = {
 	generatedMessageIDs: Map<string, Set<string>>;
 	lastUserMessageIDs: Map<string, string>;
 	inFlight: Set<string>;
+	interrupted: Set<string>;
 };
 export type RalphOutcome = "running" | "completed" | "blocked" | "budget_exhausted" | "user_stopped";
 const states = new WeakMap<object, Map<string, ContinuationState>>();
@@ -43,7 +44,7 @@ function getState(): ContinuationState | undefined {
 	const root = projectRootKey(getWorkspaceRoot());
 	let state = clientStates.get(root);
 	if (!state) {
-		state = { counts: new Map(), ralphOutcomes: new Map(), generatedMessageIDs: new Map(), lastUserMessageIDs: new Map(), inFlight: new Set() };
+		state = { counts: new Map(), ralphOutcomes: new Map(), generatedMessageIDs: new Map(), lastUserMessageIDs: new Map(), inFlight: new Set(), interrupted: new Set() };
 		clientStates.set(root, state);
 	}
 	return state;
@@ -56,6 +57,9 @@ export async function continueUnfinishedSession(sessionID: string, settleTitle =
 	try {
 		const ralph = isRalphModeEnabled(getWorkspaceRoot());
 		if (ralph && state.ralphOutcomes.get(sessionID) === "user_stopped") return false;
+		// A user-initiated interrupt (Esc) suspends automatic continuation:
+		// only genuine user input re-enables it (see recordUserMessage).
+		if (state.interrupted.has(sessionID)) return false;
 		const effective = await effectiveTodosWithOwner(sessionID);
 		if (!effective || effective.ownerSessionID !== sessionID || !hasActiveTodo(effective.todos)) {
 			if (ralph && state.ralphOutcomes.has(sessionID)) state.ralphOutcomes.set(sessionID, "completed");
@@ -122,12 +126,26 @@ export function recordUserMessage(sessionID: string, messageID?: string): void {
 	if (messageID && state.lastUserMessageIDs.get(sessionID) === messageID) return;
 	if (messageID) state.lastUserMessageIDs.set(sessionID, messageID);
 	state.counts.delete(sessionID);
+	state.interrupted.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");
 	}
 }
 
+// Record a user-initiated interrupt (Esc): the session's run was aborted
+// from the user side, so automatic continuation must stop. Ralph runs are
+// marked user_stopped, mirroring genuine user input. A later genuine user
+// message re-enables continuation (recordUserMessage clears the flag).
+export function markInterrupted(sessionID: string): void {
+	const state = getState();
+	if (!state) return;
+	state.interrupted.add(sessionID);
+	if (isRalphModeEnabled(getWorkspaceRoot()) && state.ralphOutcomes.has(sessionID)) {
+		state.ralphOutcomes.set(sessionID, "user_stopped");
+	}
+}
+
 export function getRalphOutcome(sessionID: string): RalphOutcome | undefined {
 	return getState()?.ralphOutcomes.get(sessionID);
 }
@@ -145,4 +163,5 @@ export function clearContinuationState(sessionID: string): void {
 	state.generatedMessageIDs.delete(sessionID);
 	state.lastUserMessageIDs.delete(sessionID);
 	state.inFlight.delete(sessionID);
+	state.interrupted.delete(sessionID);
 }

package/src/policies/git.ts

@@ -123,7 +123,7 @@ export function normalizeGitCommands(command: string): string {
 }
 
 export const GIT_WRITE_RE =
-	/\bgit\s+(add|rm|mv|commit|merge|rebase|cherry-pick|revert|stash\s+pop|apply|am|restore|reset|update-ref|filter-branch)\b|\bgit\s+tag\s+(?!--?list\b|-l\b)|\bgit\s+checkout\s+(?!-b\b)|\bgit\s+branch\s+(?:[^|;&]*\s)?-[dDM]\b/;
+	/\bgit\s+(add|rm|mv|commit|merge|rebase|cherry-pick|revert|stash\s+pop|apply|am|restore|reset|update-ref|filter-branch)\b|\bgit\s+tag\s+(?!--?list\b|-l\b)(?:[^|;&]*\s)?(?:-d\b|--delete\b)|\bgit\s+checkout\s+(?!-b\b)|\bgit\s+branch\s+(?:[^|;&]*\s)?-[dDM]\b/;
 
 export function currentGitBranch(root: string): string | undefined {
 	const result = spawnSync("git", ["branch", "--show-current"], {
@@ -179,6 +179,47 @@ export function pushedProtectedBranchIn(pushCommand: string, root: string): stri
 	return undefined;
 }
 
+/**
+ * True when a `git push` command pushes a tag refspec: an explicit
+ * `refs/tags/<name>` destination, or a short name that resolves to an
+ * existing tag in the repository at `root`. Publishing a tag is a release
+ * operation, not a branch mutation, so callers exempt it from the
+ * protected-branch and merged-branch push rules (#134). Deletion refspecs
+ * (`:refs/tags/<name>`, `git push --delete`, `-d`) return false so tag
+ * deletions stay blocked.
+ */
+export function tagRefspecIn(pushCommand: string, root: string): boolean {
+	if (/\s--delete\b|\s-d(?:\b|$)/.test(pushCommand)) return false;
+	for (const segment of splitShellSegments(pushCommand)) {
+		const parsed = parseGitInvocation(segment);
+		if (!parsed || !/\bpush\b/.test(parsed.rest)) continue;
+		const tokens = parsed.rest.split(/\s+/).slice(1);
+		let remoteSeen = false;
+		for (const rawToken of tokens) {
+			if (rawToken.startsWith("-")) continue;
+			if (!remoteSeen) {
+				remoteSeen = true;
+				continue;
+			}
+			const token = rawToken.replace(/^\+/, "");
+			if (!token) continue;
+			if (token.startsWith(":")) continue; // deletion refspec: empty source
+			if (token.includes(":")) {
+				if (token.includes(":refs/tags/")) return true; // <src>:refs/tags/<name>
+				continue;
+			}
+			if (token.startsWith("refs/tags/")) return true; // explicit tag refspec
+			const probe = spawnSync("git", ["show-ref", "--verify", "--quiet", `refs/tags/${token}`], {
+				cwd: root,
+				encoding: "utf8",
+				timeout: 10_000,
+			});
+			if (probe.status === 0) return true;
+		}
+	}
+	return false;
+}
+
 export function onProtectedBranch(root: string): boolean {
 	return isProtectedBranchName(currentGitBranch(root) ?? "", root);
 }

package/src/policies/tamper.ts

@@ -36,11 +36,23 @@ export function normalizeGlobPathEvasion(text: string): string {
 		.replace(/opencode\.[?*]/gi, ocJson);
 }
 
+// Collaboration invocations (hosted-git/PR/issue CLIs) never write local
+// configuration: their arguments may legitimately mention guarded paths.
+const COLLABORATION_INVOCATION_PATTERNS: RegExp[] = [
+	/^\s*(?:gh|glab)\s+(?:issue|pr)\b/,
+	/^\s*az\s+repos\s+pr\b/,
+];
+
+export function isCollaborationInvocation(segment: string): boolean {
+	return COLLABORATION_INVOCATION_PATTERNS.some((re) => re.test(segment));
+}
+
 export function isSettingsTamper(command: string): boolean {
 	const segments = command.split(/[\n|;&]+/).map((s) =>
 		normalizeGlobPathEvasion(normalizeShellEvasion(s)),
 	);
 	return segments.some((segment) =>
+		!isCollaborationInvocation(segment) &&
 		SETTINGS_TAMPER_PATTERNS.some((re) => re.test(segment)),
 	);
 }
@@ -53,6 +65,11 @@ export function isProtectedPath(targetPath: string): boolean {
 		const base = basename(path);
 		const lower = path.toLowerCase();
 		const dotOc = "." + "opencode/";
+		// opencode plan mode writes agent plan markdown under the project's
+		// .opencode/plans/ directory - plan files are documents, not
+		// configuration. The trailing slash keeps the plans directory
+		// itself protected.
+		if (lower.includes("/" + dotOc + "plans/")) return false;
 		const cfgOc = "/.config/" + "opencode/";
 		const cfgOcJson = "/.config/" + "opencode.json";
 		return (

package/src/workflow-guard-ui.ts

@@ -1,4 +1,14 @@
+/**
+ * Workflow Guard TUI companion plugin for OpenCode V2 (CLI plugin API).
+ *
+ * - Registers the `/guard-options` palette + slash command to toggle project options.
+ * - Renders the Workflow Guard badge in the home and prompt footer status slots.
+ *
+ * The V1 entrypoint (`WorkflowGuardTui`) remains for OpenCode 1.x TUI clients.
+ */
+
 import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui";
+import { Plugin } from "@opencode/plugin/tui";
 import type { JSX } from "@opentui/solid";
 import { createElement, insert, setProp } from "@opentui/solid";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -75,6 +85,95 @@ export function formatBadge(): { text: string; isBlocked: boolean } {
 	return { text: BADGE_ACTIVE, isBlocked: false };
 }
 
+// ── V2 CLI plugin ─────────────────────────────────────────────────────────────
+
+type TuiContext = Plugin.Context;
+
+const TOGGLE_OPTIONS: Array<{ key: ProjectToggle; label: string; description: string }> = [
+	{ key: "recoveryCheckpoints", label: "Recovery checkpoints", description: "Toggle durable pre-run Git checkpoints" },
+	{ key: "projectMemory", label: "Project memory", description: "Toggle durable local project memory" },
+	{ key: "learning", label: "Learner mode", description: "Toggle evidence-based learning tools" },
+	{ key: "titleSettleWorkaround", label: "Title settle workaround", description: "Delay automatic continuation while OpenCode generates a session title" },
+	{ key: "ralphMode", label: "Ralph mode", description: "Opt into bounded autonomous continuation of already-owned todos" },
+];
+
+export const WorkflowGuardTuiV2 = (ctx: TuiContext) => {
+	const badge = () => {
+		const formatted = formatBadge();
+		return text({ fg: ctx.theme.text.feedback.success.base }, [formatted.text]);
+	};
+
+	const optionsRoot = () => ctx.location?.directory || process.cwd();
+
+	// `ctx.keymap.layer` creates a layer owned by the calling component and only
+	// resolves inside the TUI's provider render tree; plugin setup() runs as a
+	// plain async call outside it. Slot renders execute in a reactive scope under
+	// the provider, so the layer is registered from an app-slot claim instead.
+	// The guard keeps repeated renders from stacking duplicate layers; layers and
+	// slot claims are disposed automatically on unload.
+	let keymapLayerRegistered = false;
+	ctx.ui.slot({
+		append: "app",
+		render: () => {
+			if (!keymapLayerRegistered) {
+				keymapLayerRegistered = true;
+				ctx.keymap.layer(() => ({
+					commands: [{
+						id: "workflow-guard.project-options",
+						title: "Workflow Guard: Project Options",
+						description: "Toggle Workflow Guard project options (recovery checkpoints, project memory, learning, title settle, ralph mode)",
+						group: "Workflow Guard",
+						palette: true,
+						slash: { name: "guard-options" },
+						async run() {
+							const root = optionsRoot();
+							for (;;) {
+								const current = new Map(TOGGLE_OPTIONS.map((option) => [option.key, readProjectOption(root, option.key)]));
+								const choice = await ctx.ui.dialog.select<ProjectToggle>({
+									title: "Workflow Guard Project Options",
+									options: TOGGLE_OPTIONS.map((option) => ({
+										title: `${option.label}: ${current.get(option.key) ? "On" : "Off"}`,
+										value: option.key,
+										description: option.description,
+									})),
+								});
+								if (!choice) break;
+								try {
+									const enabled = !readProjectOption(root, choice);
+									const path = writeProjectOption(root, choice, enabled);
+									ctx.ui.toast.show({
+										variant: "success",
+										title: "Workflow Guard",
+										message: `Saved ${choice} ${enabled ? "on" : "off"} in ${path}. Restart OpenCode to apply.`,
+									});
+								} catch (error) {
+									ctx.ui.toast.show({
+										variant: "error",
+										title: "Workflow Guard",
+										message: error instanceof Error ? error.message : String(error),
+									});
+									break;
+								}
+							}
+						},
+					}],
+					bindings: [],
+				}));
+			}
+			return null;
+		},
+	});
+
+	ctx.ui.slot({ append: "home.footer.status", render: () => badge() });
+	ctx.ui.slot({ append: "prompt.footer.status", render: () => badge() });
+
+	return () => {
+		// Slot claims and keymap layers are disposed automatically on unload.
+	};
+};
+
+// ── V1 TUI plugin ─────────────────────────────────────────────────────────────
+
 export const WorkflowGuardTui: TuiPlugin = async (api) => {
 	api.keymap.registerLayer({
 		commands: [{
@@ -85,11 +184,6 @@ export const WorkflowGuardTui: TuiPlugin = async (api) => {
 			slashName: "guard-options",
 			run() {
 				const root = api.state.path.worktree || api.state.path.directory;
-				const recovery = readProjectOption(root, "recoveryCheckpoints");
-				const memory = readProjectOption(root, "projectMemory");
-				const learning = readProjectOption(root, "learning");
-				const titleSettle = readProjectOption(root, "titleSettleWorkaround");
-				const ralphMode = readProjectOption(root, "ralphMode");
 				const toggle = (key: ProjectToggle) => {
 					const enabled = !readProjectOption(root, key);
 					const path = writeProjectOption(root, key, enabled);
@@ -99,13 +193,12 @@ export const WorkflowGuardTui: TuiPlugin = async (api) => {
 				api.ui.dialog.replace(() => api.ui.DialogSelect({
 					title: "Workflow Guard Project Options",
 					current: undefined,
-					options: [
-						{ title: `Recovery checkpoints: ${recovery ? "On" : "Off"}`, value: "recoveryCheckpoints", description: "Toggle durable pre-run Git checkpoints", onSelect: () => toggle("recoveryCheckpoints") },
-						{ title: `Project memory: ${memory ? "On" : "Off"}`, value: "projectMemory", description: "Toggle durable local project memory", onSelect: () => toggle("projectMemory") },
-						{ title: `Learner mode: ${learning ? "On" : "Off"}`, value: "learning", description: "Toggle evidence-based learning tools", onSelect: () => toggle("learning") },
-						{ title: `Title settle workaround: ${titleSettle ? "On" : "Off"}`, value: "titleSettleWorkaround", description: "Delay automatic continuation while OpenCode generates a session title", onSelect: () => toggle("titleSettleWorkaround") },
-						{ title: `Ralph mode: ${ralphMode ? "On" : "Off"}`, value: "ralphMode", description: "Opt into bounded autonomous continuation of already-owned todos", onSelect: () => toggle("ralphMode") },
-					],
+					options: TOGGLE_OPTIONS.map((option) => ({
+						title: `${option.label}: ${readProjectOption(root, option.key) ? "On" : "Off"}`,
+						value: option.key,
+						description: option.description,
+						onSelect: () => toggle(option.key),
+					})),
 				}));
 			},
 		}],
@@ -129,7 +222,11 @@ export const WorkflowGuardTui: TuiPlugin = async (api) => {
 	});
 };
 
+// Default export supports BOTH generations: V1 TUI clients call tui(), V2 reads setup().
 export default {
-	id: "workflow-guard-ui",
+	...Plugin.define({
+		id: "workflow-guard-ui",
+		setup: WorkflowGuardTuiV2,
+	}),
 	tui: WorkflowGuardTui,
-} satisfies TuiPluginModule;
+} as const satisfies TuiPluginModule;

package/src/workflow-guard.ts

@@ -8,7 +8,9 @@
  * from ./lib/, and re-exports the public helper surface for tests.
  */
 
-import { type Plugin, type PluginModule } from "@opencode-ai/plugin";
+import { type Plugin as V1Plugin, type PluginModule } from "@opencode-ai/plugin";
+import { Plugin } from "@opencode/plugin";
+import { WorkflowGuardV2 } from "./lib/v2-plugin.ts";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { join } from "node:path";
@@ -188,6 +190,7 @@ export function managedConfigDiagnostic(platform = process.platform, env: NodeJS
 // ── Verification engine ──────────────────────────────────────────────────────
 import {
 	detectVerifyCommand,
+	resolveVerifyTimeoutMs,
 	runVerify,
 	snipVerifyOutput,
 	getCurrentGitCommitHash,
@@ -197,6 +200,7 @@ import {
 
 export {
 	detectVerifyCommand,
+	resolveVerifyTimeoutMs,
 	runVerify,
 	snipVerifyOutput,
 	getCurrentGitCommitHash,
@@ -239,6 +243,7 @@ import {
 	clearContinuationState,
 	continueUnfinishedSession,
 	isGeneratedContinuationMessage,
+	markInterrupted,
 	recordUserMessage,
 } from "./policies/continuation.ts";
 import {
@@ -377,7 +382,7 @@ export function buildCompactionContext(operationalState: string, priorityBlocks:
 	return context;
 }
 
-export const WorkflowGuard: Plugin = async (ctx) => {
+export const WorkflowGuard: V1Plugin = async (ctx: Parameters<V1Plugin>[0]) => {
 	// Honor worktree if present (e.g. opencode worktrees or devcontainers)
 	// so worktree plugins cannot punch through boundary gates. When the host
 	// reports the filesystem root, use the SDK's actual project worktree instead.
@@ -763,12 +768,24 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 				}
 			}
 			if (event?.type === "message.updated") {
-				const info = (event.properties as { info?: { id?: unknown; role?: unknown; sessionID?: unknown } })?.info;
+				const info = (event.properties as { info?: { id?: unknown; role?: unknown; sessionID?: unknown; error?: { name?: unknown } } })?.info;
 				if (info?.role === "user" && typeof info.sessionID === "string") {
 					await runWithRuntimeState(effectiveRoot, ctx.client, () => {
 						recordUserMessage(info.sessionID as string, typeof info.id === "string" ? info.id : undefined);
 					});
 				}
+				// A user-initiated interrupt (Esc) surfaces as an aborted
+				// assistant message: stop automatic continuation for the
+				// session until genuine user input arrives.
+				if (info?.role === "assistant" && typeof info.sessionID === "string" && info.error?.name === "MessageAbortedError") {
+					await runWithRuntimeState(effectiveRoot, ctx.client, () => markInterrupted(info.sessionID as string));
+				}
+			}
+			if (event?.type === "session.error") {
+				const props = event.properties as { sessionID?: unknown; error?: { name?: unknown } };
+				if (typeof props?.sessionID === "string" && props?.error?.name === "MessageAbortedError") {
+					await runWithRuntimeState(effectiveRoot, ctx.client, () => markInterrupted(props.sessionID as string));
+				}
 			}
 			if (event?.type === "session.deleted") {
 				const sessionID = (event.properties as { info?: { id?: unknown } })?.info?.id;
@@ -804,8 +821,12 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 	};
 };
 
-// Default export MUST be a V1 PluginModule record.
+// Default export supports BOTH generations: V1 calls server(), V2 reads id+setup().
+// Spread Plugin.define() so the V2 definition type-checks separately from server().
 export default {
-	id: "workflow-guard",
+	...Plugin.define({
+		id: "workflow-guard",
+		setup: WorkflowGuardV2,
+	}),
 	server: WorkflowGuard,
 } satisfies PluginModule;