opencode-workflow-guard 1.5.0 → 1.6.0

package/src/lib/guard-dispatcher.ts

@@ -0,0 +1,471 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadVerifyCache } from "./audit.ts";
+import {
+	getLastReviewResult,
+	getSdkClient,
+	getWorkspaceRoot,
+	isDocumentationRequired,
+	isReviewRequired,
+	lastMutationTimestamp,
+	lastVerify,
+	recordMutation,
+	recordVerifyResult,
+	sessionMutationTimestamps,
+	sessionReviews,
+	sessionVerifyResults,
+} from "./state.ts";
+import {
+	dynamicShellSyntaxIn,
+	extractCommands,
+	normalize,
+	shellWrappersChangeCwd,
+	splitShellSegments,
+	unwrapShellCommand,
+} from "./shell.ts";
+import { asRecord, extractTargetPath } from "./utils.ts";
+import {
+	detectVerifyCommand,
+	getCurrentGitCommitHash,
+	getGitStatusSummary,
+	getGitWorktreeFingerprint,
+	runVerify,
+	snipVerifyOutput,
+} from "./verify.ts";
+import { detectShellMutation, extractPatchPaths, guardShellMutation, isPathOutsideWorkspace } from "../policies/boundary.ts";
+import { branchHasChangelogChange, checkLockfileSync, hasPrCreateInvocation, 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 {
+	GIT_BRANCH_CREATE_RE,
+	GIT_WRITE_RE,
+	PUSH_TO_MAIN_RE,
+	branchGuardReason,
+	checkBranchBaseIsUpToDate,
+	checkMergeConflicts,
+	currentGitBranch,
+	hasUnsafeGitAlias,
+	isBranchAlreadyMergedOrClosed,
+	normalizeGitCommands,
+	onProtectedBranch,
+	parseGitInvocation,
+	pushedProtectedBranchIn,
+} from "../policies/git.ts";
+import { extractInterpreterPayload, outsideWritePathInPayload, secretPathInPayload, writePathsInPayload } from "../policies/interpreter.ts";
+import { mcpMutationTool } from "../policies/mcp.ts";
+import { editTargets } from "../policies/post-edit-validation.ts";
+import { generateMaskedEnvSchema, isEnvFilePath, isSecretPath, secretFileReadIn, secretIn } from "../policies/secrets.ts";
+import { checkInteractiveTtyCommand, checkPackageHygiene } from "../policies/shell-safety.ts";
+import { staleWriteReason } from "../policies/stale-write.ts";
+import { PROTECTED_PATH_REASON, isProtectedPath, isSettingsTamper } from "../policies/tamper.ts";
+import {
+	EDIT_TOOL_NAMES,
+	effectiveTodoOwnerSessionID,
+	effectiveTodos,
+	fetchSessionTodos,
+	hasActiveTodo,
+	subagentMutationBudgetReason,
+	validateTodoLifecycle,
+} from "../policies/todo.ts";
+
+const SHELL_TOOL_NAMES = new Set(["bash", "run_commands", "execute_command", "shell"]);
+
+const READ_ONLY_ROLES = new Set([
+	"reviewer",
+	"planner",
+	"advisor",
+	"critic",
+	"explorer",
+	"scout",
+	"evaluator",
+]);
+
+export function isReadOnlyRole(agent?: string): boolean {
+	if (!agent) return false;
+	const lower = agent.toLowerCase().trim();
+	return READ_ONLY_ROLES.has(lower) || Array.from(READ_ONLY_ROLES).some((r) => lower.includes(r));
+}
+
+function logBlock(message: string): void {
+	try {
+		void (getSdkClient() as any)?.app?.log?.({
+			body: {
+				service: "workflow-guard",
+				level: "warn",
+				message,
+			},
+		});
+	} catch {}
+}
+
+export async function guardToolCallImpl(
+	toolName: string,
+	input: unknown,
+	context?: { sessionID?: string; callID?: string; worktree?: string; directory?: string; agent?: string },
+): Promise<string | undefined> {
+	const currentRoot = getWorkspaceRoot();
+
+	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;
+		}
+	}
+
+	if (toolName === "read" || toolName === "read_file") {
+		const target = extractTargetPath(input) ?? "";
+		if (target && isSecretPath(target)) {
+			logBlock(`[workflow-guard] blocked read: secret file ${target}`);
+			if (isEnvFilePath(target)) {
+				let schemaHint = "";
+				try {
+					const resolvedTarget = resolve(currentRoot, target);
+					if (existsSync(resolvedTarget)) {
+						const raw = readFileSync(resolvedTarget, "utf8");
+						const masked = generateMaskedEnvSchema(raw);
+						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 `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;
+	}
+
+	if (toolName === "todowrite") {
+		const record = asRecord(input);
+		const rawTodos = record?.todos;
+		if (Array.isArray(rawTodos)) {
+			const newTodos = rawTodos as any[];
+			const existingTodos = context?.sessionID ? await fetchSessionTodos(context.sessionID) : undefined;
+			const err = validateTodoLifecycle(newTodos, existingTodos);
+			if (err) {
+				logBlock(`[workflow-guard] ${err}`);
+				return err;
+			}
+			const allDone = newTodos.length > 0 && newTodos.every((t) => {
+				const s = String(t.status ?? "");
+				return s === "completed" || s === "cancelled";
+			});
+			if (allDone) {
+				const conflictCheck = checkMergeConflicts(currentRoot);
+				if (conflictCheck.hasConflicts) {
+					const reason = `Blocked todowrite: ${conflictCheck.reason}`;
+					logBlock(`[workflow-guard] ${reason}`);
+					return reason;
+				}
+				const command = detectVerifyCommand(currentRoot);
+				if (command) {
+					const sessionID = context?.sessionID;
+					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;
+					}
+					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;
+					if (!isFresh) {
+						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;
+						}
+					}
+				}
+			}
+		}
+		return undefined;
+	}
+
+	if (EDIT_TOOL_NAMES.has(toolName)) {
+		const allowLive = process.env.WORKFLOW_GUARD_ALLOW_LIVE === "1";
+		const record = asRecord(input);
+		const target = extractTargetPath(input) ?? "";
+		if (target && isProtectedPath(target)) {
+			logBlock(`[workflow-guard] blocked ${toolName}: protected path ${target}`);
+			return 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.`;
+		}
+		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;
+				}
+				if (isSecretPath(patchPath)) {
+					logBlock(`[workflow-guard] blocked apply_patch: secret file path ${patchPath}`);
+					return `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}).`;
+				}
+			}
+		}
+		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.`;
+		}
+		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.`;
+			}
+		}
+		if (!allowLive) {
+			for (const content of extractEditContent(input)) {
+				for (const line of content.split("\n")) {
+					const trimmed = line.trim();
+					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).`;
+					}
+				}
+			}
+		}
+		for (const content of extractEditContent(input)) if (isSettingsTamper(content)) return PROTECTED_PATH_REASON;
+		if (onProtectedBranch(currentRoot)) {
+			logBlock(`[workflow-guard] blocked ${toolName}: on protected branch ${currentGitBranch(currentRoot)}`);
+			return 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.";
+		}
+		if (context?.sessionID) {
+			const reason = await subagentMutationBudgetReason(context.sessionID, currentRoot);
+			if (reason) {
+				logBlock(`[workflow-guard] ${reason}`);
+				return reason;
+			}
+		}
+		if (context?.sessionID && context.callID) {
+			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;
+					}
+				}
+			}
+			const claimReason = claimFiles(editTargets(input, currentRoot), context.sessionID, context.callID);
+			if (claimReason) {
+				logBlock(`[workflow-guard] ${claimReason}`);
+				return claimReason;
+			}
+		}
+		recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID));
+		return undefined;
+	}
+
+	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.`;
+		}
+	}
+	if (!SHELL_TOOL_NAMES.has(toolName)) return undefined;
+
+	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.`;
+		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}`;
+		}
+		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}`;
+		}
+		const normalizedCommand = normalizeGitCommands(command);
+		if (hasUnsafeGitAlias(command)) return "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.`;
+			}
+		}
+		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();
+			}
+		}
+		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}`;
+			}
+		}
+		if (isSettingsTamper(command)) {
+			logBlock(`[workflow-guard] blocked settings tamper: ${command.slice(0, 120)}`);
+			return 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.`;
+			}
+		}
+		for (const payload of extractInterpreterPayload(command)) {
+			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.`;
+			}
+			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();
+				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));
+			}
+			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.`;
+				}
+			}
+			if (isSettingsTamper(payload)) return PROTECTED_PATH_REASON;
+			const secretPath = secretPathInPayload(payload);
+			if (secretPath) return `Blocked: reading sensitive credential/secret file '${secretPath}' via inline interpreter script is not permitted.`;
+		}
+		const shellMutationReason = await guardShellMutation(command, context?.sessionID);
+		if (shellMutationReason) {
+			logBlock(`[workflow-guard] blocked shell mutation: ${command.slice(0, 120)}`);
+			return 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.`;
+			}
+		}
+		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.";
+		}
+		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.`;
+			}
+		}
+		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();
+			}
+			const branch = currentGitBranch(invocation.repoDir);
+			if (branch) {
+				const mergedStatus = isBranchAlreadyMergedOrClosed(invocation.repoDir, branch);
+				if (mergedStatus.merged) {
+					logBlock(`[workflow-guard] blocked push to merged/closed branch: ${branch}`);
+					return `Blocked: ${mergedStatus.reason}`;
+				}
+			}
+		}
+		if (hasPrCreateInvocation(raw)) {
+			const isAz = /\baz\s+repos\s+pr\s+create\b/.test(normalizedCommand);
+			const prTool = isAz ? "az repos pr create" : "gh pr create";
+			const descFlag = isAz ? "--description" : "--body";
+			const preflightFailures: string[] = [];
+			const conflictCheck = checkMergeConflicts(currentRoot);
+			if (conflictCheck.hasConflicts) preflightFailures.push(conflictCheck.reason ?? "Branch has merge conflicts with its base branch.");
+			const branch = currentGitBranch(currentRoot);
+			if (branch) {
+				const mergedStatus = isBranchAlreadyMergedOrClosed(currentRoot, branch);
+				if (mergedStatus.merged) preflightFailures.push(mergedStatus.reason ?? "Branch is already merged or closed.");
+			}
+			if (isReviewRequired(currentRoot)) {
+				const review = context?.sessionID ? (sessionReviews.get(context.sessionID) ?? getLastReviewResult()) : getLastReviewResult();
+				const reviewMatchesContext = review?.passed === true && review.workspace === resolve(currentRoot) && (!review.targetSessionID || review.targetSessionID === context?.sessionID) && review.commitHash === getCurrentGitCommitHash(currentRoot) && review.gitStatus === getGitStatusSummary(currentRoot) && review.worktreeFingerprint === getGitWorktreeFingerprint(currentRoot);
+				if (!reviewMatchesContext) preflightFailures.push("Passing secondary review approval is required; invoke a secondary review subagent and record approval with record_review.");
+			}
+			if (isDocumentationRequired(currentRoot) && !branchHasDocumentationChange(currentRoot)) preflightFailures.push("Documentation update is required (Policy 21); update README.md or relevant documentation in docs/.");
+			const branchChangelog = branchHasChangelogChange(currentRoot);
+			let shellCwdKnown = true;
+			const prSegments: Array<{ segment: string; invocationRoot: string | null }> = [];
+			for (const segment of splitShellSegments(raw)) {
+				const unwrapped = unwrapShellCommand(segment);
+				if (/(?:^|\s)(?:(?:builtin|command)\s+)?(?:cd|pushd|popd)(?:\s|$)/.test(unwrapped)) shellCwdKnown = false;
+				if (hasPrCreateInvocation(segment)) {
+					const wrapperChangesCwd = shellWrappersChangeCwd(segment);
+					prSegments.push({ segment, invocationRoot: shellCwdKnown && !wrapperChangesCwd ? currentRoot : null });
+				}
+			}
+			const hasChangelog = branchChangelog || prSegments.every(({ segment, invocationRoot }) => prBodyIncludesChangelog(segment, invocationRoot));
+			if (!hasChangelog) preflightFailures.push(`Release information is required; update a CHANGELOG/changeset file or include a Summary, Changes, Release notes, or Changelog section in the PR description (${descFlag}).`);
+			const lockCheck = checkLockfileSync(currentRoot);
+			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;
+			}
+		}
+		const hasGitMutation = gitInvocations.some((invocation) => {
+			const normalizedInvocation = `git ${invocation.rest}`;
+			return GIT_WRITE_RE.test(normalizedInvocation) || /\bgit\s+(?:switch|checkout)\b/.test(normalizedInvocation);
+		});
+		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}).`;
+			}
+			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.`;
+			}
+		}
+		const shellMut = detectShellMutation(command);
+		if (hasGitMutation || shellMut) {
+			if (context?.sessionID) {
+				const reason = await subagentMutationBudgetReason(context.sessionID, currentRoot);
+				if (reason) {
+					logBlock(`[workflow-guard] ${reason}`);
+					return reason;
+				}
+			}
+		}
+		if (hasGitMutation) recordMutation(await effectiveTodoOwnerSessionID(context?.sessionID));
+	}
+	return undefined;
+}

package/src/lib/project-config.ts

@@ -0,0 +1,68 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ProjectConfig } from "./types.ts";
+
+let cachedProjectConfig: ProjectConfig | undefined;
+
+export function projectConfigCandidates(root: string): string[] {
+	return [
+		join(root, ".opencode", "workflow-guard.json"),
+		join(root, ".opencode", "workflow-guard.jsonc"),
+		join(root, "workflow-guard.json"),
+		join(root, "workflow-guard.jsonc"),
+	];
+}
+
+export function projectConfigPath(root: string): string {
+	const candidates = projectConfigCandidates(root);
+	return candidates.find(existsSync) ?? candidates[0]!;
+}
+
+/** Strip JSONC comments and trailing commas without altering string literals. */
+export function stripJsonComments(jsonc: string): string {
+	let insideString = false;
+	let stringQuote = "";
+	let escaped = false;
+	let output = "";
+	let i = 0;
+	while (i < jsonc.length) {
+		const char = jsonc[i]!;
+		const next = jsonc[i + 1];
+		if (escaped) { output += char; escaped = false; i++; continue; }
+		if (char === "\\") { output += char; escaped = true; i++; continue; }
+		if (char === '"' || char === "'") {
+			if (!insideString) { insideString = true; stringQuote = char; }
+			else if (stringQuote === char) insideString = false;
+			output += char; i++; continue;
+		}
+		if (!insideString && char === "/" && next === "/") {
+			i += 2;
+			while (i < jsonc.length && jsonc[i] !== "\n" && jsonc[i] !== "\r") i++;
+			continue;
+		}
+		if (!insideString && char === "/" && next === "*") {
+			i += 2;
+			while (i < jsonc.length && !(jsonc[i] === "*" && jsonc[i + 1] === "/")) i++;
+			i += 2; continue;
+		}
+		output += char; i++;
+	}
+	return output.replace(/,(\s*[}\]])/g, "$1");
+}
+
+export function loadProjectConfig(root: string): ProjectConfig {
+	for (const candidate of projectConfigCandidates(root)) {
+		try {
+			return JSON.parse(stripJsonComments(readFileSync(candidate, "utf8")));
+		} catch {}
+	}
+	return {};
+}
+
+export function reloadProjectConfig(root: string): void {
+	cachedProjectConfig = loadProjectConfig(root);
+}
+
+export function getCachedProjectConfig(): ProjectConfig | undefined {
+	return cachedProjectConfig;
+}

package/src/lib/project-memory.ts

@@ -3,7 +3,7 @@ import { appendFileSync, mkdirSync, readFileSync, renameSync, statSync, writeFil
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { DatabaseSync } from "node:sqlite";
-import type { ProjectMemoryInput, ProjectMemoryKind, ProjectMemoryRecord, ProjectMemorySource } from "./types.ts";
+import type { ProjectMemoryInput, ProjectMemoryKind, ProjectMemoryRecord, ProjectMemorySource, ReviewFollowup, ReviewFollowupInput } from "./types.ts";
 
 const KINDS = new Set<ProjectMemoryKind>(["fact", "decision", "constraint", "lesson"]);
 const SOURCES = new Set<ProjectMemorySource>(["user", "file", "git", "tool", "agent", "portable"]);
@@ -58,10 +58,53 @@ export function openProjectMemory(projectId: string, directory = getProjectMemor
 			paths TEXT NOT NULL, supersedes TEXT, status TEXT NOT NULL DEFAULT 'current'
 		);
 		CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(id UNINDEXED, content);
+		CREATE TABLE IF NOT EXISTS review_followups (
+			id TEXT PRIMARY KEY, project_id TEXT NOT NULL, severity TEXT NOT NULL, summary TEXT NOT NULL,
+			reviewer TEXT NOT NULL, created_at INTEGER NOT NULL, resolved_at INTEGER, session_id TEXT,
+			commit_sha TEXT, paths TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'open'
+		);
 	`);
 	return { db, projectId, close: () => db.close() };
 }
 
+function followupRowToRecord(row: Record<string, unknown>): ReviewFollowup {
+	return {
+		id: String(row.id), projectId: String(row.project_id), severity: String(row.severity) as ReviewFollowup["severity"],
+		summary: String(row.summary), reviewer: String(row.reviewer), createdAt: Number(row.created_at),
+		resolvedAt: row.resolved_at ? Number(row.resolved_at) : undefined, sessionID: row.session_id ? String(row.session_id) : undefined,
+		commit: row.commit_sha ? String(row.commit_sha) : undefined, paths: JSON.parse(String(row.paths)) as string[],
+		status: String(row.status) as ReviewFollowup["status"],
+	};
+}
+
+export function recordReviewFollowup(store: ProjectMemoryStore, input: ReviewFollowupInput, id: string = randomUUID()): ReviewFollowup {
+	if (input.severity !== "P2" && input.severity !== "P3") throw new Error("Review follow-up severity must be P2 or P3.");
+	if (!input.summary.trim() || input.summary.length > 4000) throw new Error("Review follow-up summary must be 1-4000 characters.");
+	if (!input.reviewer.trim() || input.reviewer.length > 200) throw new Error("Invalid review follow-up reviewer.");
+	if ((input.paths?.length ?? 0) > 20 || input.paths?.some((path) => !path || path.length > 500 || isAbsolute(path) || path.split(/[\\/]/).includes("..") || /[\0\r\n]/.test(path))) throw new Error("Invalid review follow-up paths.");
+	if (input.sessionID && input.sessionID.length > 200) throw new Error("Invalid review follow-up session ID.");
+	if (input.commit && !/^[0-9a-f]{7,64}$/i.test(input.commit)) throw new Error("Invalid review follow-up commit.");
+	const createdAt = Date.now();
+	store.db.prepare("INSERT INTO review_followups VALUES (?, ?, ?, ?, ?, ?, NULL, ?, ?, ?, 'open')").run(
+		id, store.projectId, input.severity, input.summary.trim(), input.reviewer.trim(), createdAt,
+		input.sessionID ?? null, input.commit ?? null, JSON.stringify(input.paths ?? []),
+	);
+	return { id, projectId: store.projectId, ...input, summary: input.summary.trim(), reviewer: input.reviewer.trim(), paths: input.paths ?? [], createdAt, status: "open" };
+}
+
+export function listReviewFollowups(store: ProjectMemoryStore, status: "open" | "resolved" = "open", limit = 50): ReviewFollowup[] {
+	const rows = store.db.prepare("SELECT * FROM review_followups WHERE project_id = ? AND status = ? ORDER BY created_at DESC LIMIT ?")
+		.all(store.projectId, status, Math.max(1, Math.min(limit, 200))) as Record<string, unknown>[];
+	return rows.map(followupRowToRecord);
+}
+
+export function resolveReviewFollowup(store: ProjectMemoryStore, id: string): boolean {
+	if (!id || id.length > 200 || /[\0\r\n]/.test(id)) return false;
+	const result = store.db.prepare("UPDATE review_followups SET status = 'resolved', resolved_at = ? WHERE id = ? AND project_id = ? AND status = 'open'")
+		.run(Date.now(), id, store.projectId);
+	return Number(result.changes) === 1;
+}
+
 function validateInput(input: ProjectMemoryInput): void {
 	if (!KINDS.has(input.kind) || !SOURCES.has(input.source)) throw new Error("Invalid project memory kind or source.");
 	if (!input.content.trim() || input.content.length > 4000) throw new Error("Project memory content must be 1-4000 characters.");