opencode-workflow-guard 1.5.0 → 1.5.1

package/README.md

@@ -68,6 +68,7 @@ For complete policy specifications and override rules, see [docs/policies.md](do
 
 | Tool | Purpose |
 |---|---|
+| `guard_next_tasks` | Load `TODO.md`, or fall back to repository roadmap/plan/task Markdown when deciding what to work on next |
 | `guard_status` | Inspect active guardrails, current branch protection, and verification/review status |
 | `guard_why` | Simulate and explain whether a specific tool call or command would be blocked |
 | `guard_audit` | View recent audit log entries recorded in `workflow-guard.jsonl` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "OpenCode plugin enforcing workflow discipline through deterministic tool.execute.before hooks",
   "license": "MIT",
   "type": "module",

package/src/lib/types.ts

@@ -7,6 +7,10 @@ export interface TodoSdkClient {
 	session?: {
 		todo?: (opts: { path: { id: string } }) => Promise<{ data?: unknown }>;
 		get?: (opts: { path: { id: string } }) => Promise<{ data?: { parentID?: unknown } }>;
+		promptAsync?: (opts: {
+			path: { id: string };
+			body: { messageID?: string; parts: Array<{ type: "text"; text: string }> };
+		}) => Promise<unknown>;
 	};
 	tui?: {
 		showToast?: (opts: { body: { title?: string; message: string; variant?: string } }) => Promise<unknown>;

package/src/lib/utils.ts

@@ -38,9 +38,7 @@ export function decodeShellEscapes(text: string): string {
 		// Unicode escapes: \uHHHH
 		.replace(/\\u([0-9a-fA-F]{4})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)))
 		// Octal escapes: \0OO or \OOO (e.g. \162 -> 'r')
-		.replace(/\\([0-3][0-7]{2})/g, (_, oct) => String.fromCharCode(parseInt(oct, 8)))
-		// Single character escapes: \c -> c (e.g. \r\m -> rm)
-		.replace(/\\(.)/g, "$1");
+		.replace(/\\([0-3][0-7]{2})/g, (_, oct) => String.fromCharCode(parseInt(oct, 8)));
 }
 
 export function shellWords(command: string): string[] {
@@ -82,22 +80,95 @@ export function shellWords(command: string): string[] {
 	return words;
 }
 
+function envSplitWords(value: string): string[] {
+	const words: string[] = [];
+	let word = "";
+	let quote: "'" | '"' | undefined;
+	let started = false;
+	const push = () => {
+		if (started) words.push(word);
+		word = "";
+		started = false;
+	};
+	for (let i = 0; i < value.length; i += 1) {
+		const char = value[i]!;
+		if (char === "'" || char === '"') {
+			if (!quote) quote = char;
+			else if (quote === char) quote = undefined;
+			else word += char;
+			started = true;
+			continue;
+		}
+		if (char === "\\" && i + 1 < value.length) {
+			const next = value[++i]!;
+			if (quote === "'" && next !== "'" && next !== "\\") {
+				word += `\\${next}`;
+				started = true;
+				continue;
+			}
+			if (next === "c" && !quote) break;
+			if (next === "_" && quote !== "'") {
+				if (quote === '"') {
+					word += " ";
+					started = true;
+				} else push();
+				continue;
+			}
+			const escapes: Record<string, string> = { f: "\f", n: "\n", r: "\r", t: "\t", v: "\v", "#": "#", "$": "$", '"': '"', "'": "'", "\\": "\\" };
+			word += escapes[next] ?? next;
+			started = true;
+			continue;
+		}
+		if (!quote && /[\s\f\v]/.test(char)) {
+			push();
+			continue;
+		}
+		if (!quote && char === "#" && !started) break;
+		if (char === "$" && quote !== "'" && value[i + 1] === "{") {
+			const end = value.indexOf("}", i + 2);
+			if (end >= 0) {
+				const name = value.slice(i + 2, end);
+				word += process.env[name] ?? "";
+				started = true;
+				i = end;
+				continue;
+			}
+		}
+		word += char;
+		started = true;
+	}
+	push();
+	return words;
+}
+
 export function splitShellSegments(command: string): string[] {
 	const segments: string[] = [];
 	let current = "";
-	let quote: "'" | '"' | undefined;
+	let quote: "'" | '"' | "ansi" | undefined;
 	let escaped = false;
-	for (const char of command) {
+	for (let i = 0; i < command.length; i += 1) {
+		const char = command[i]!;
 		if (escaped) {
 			current += char;
 			escaped = false;
 			continue;
 		}
+		if (!quote && char === "$" && command[i + 1] === "'") {
+			current += "$'";
+			quote = "ansi";
+			i += 1;
+			continue;
+		}
 		if (char === "\\" && quote !== "'") {
 			current += char;
 			escaped = true;
 			continue;
 		}
+		if (quote === "ansi" && char === "'") {
+			quote = undefined;
+			current += char;
+			continue;
+		}
 		if (char === "'" || char === '"') {
 			if (!quote) quote = char;
 			else if (quote === char) quote = undefined;
@@ -115,7 +186,7 @@ export function splitShellSegments(command: string): string[] {
 	return segments;
 }
 
-export function unwrapShellWords(command: string): string[] {
+function unwrapShellWordsImpl(command: string): { words: string[]; changesCwd: boolean } {
 	let cleanCmd = decodeShellEscapes(command.trim());
 	// Strip outer grouping parentheses/braces if present e.g. ( git commit ) or { git commit; }
 	while (
@@ -128,6 +199,7 @@ export function unwrapShellWords(command: string): string[] {
 
 	const words = shellWords(cleanCmd);
 	let i = 0;
+	let changesCwd = false;
 	while (i < words.length) {
 		const rawWord = words[i]!;
 		const word = rawWord.replace(/^[\({]+/, "").replace(/[\)};]+$/, "");
@@ -198,6 +270,7 @@ export function unwrapShellWords(command: string): string[] {
 			]);
 			while (i < words.length && words[i]!.startsWith("-")) {
 				const option = words[i++]!;
+				if (option === "-D" || (option.startsWith("-D") && option !== "-D") || option === "--chdir" || option.startsWith("--chdir=")) changesCwd = true;
 				if (valueOptions.has(option) && i < words.length) i++;
 			}
 			continue;
@@ -207,6 +280,7 @@ export function unwrapShellWords(command: string): string[] {
 			const valueOptions = new Set([
 				"-u",
 				"--unset",
+				"--argv0",
 				"-C",
 				"--chdir",
 				"-S",
@@ -214,12 +288,54 @@ export function unwrapShellWords(command: string): string[] {
 			]);
 			while (i < words.length) {
 				const w = words[i]!;
+				if (w === "--") {
+					i++;
+					break;
+				}
 				if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(w)) {
 					i++;
 					continue;
 				}
+				let splitValue: string | undefined;
+				let consumed = 0;
+				const clustered = /^-[iv0]*([SC])(.*)$/.exec(w);
+				if (clustered?.[1] === "C") {
+					changesCwd = true;
+					i++;
+					if (!clustered[2] && i < words.length) i++;
+					continue;
+				}
+				if (clustered?.[1] === "S") {
+					if (clustered[2]) splitValue = clustered[2];
+					else if (i + 1 < words.length) {
+						splitValue = words[i + 1]!;
+						consumed = 1;
+					}
+				}
+				else if (w.startsWith("-S") && w !== "-S") splitValue = w.slice(2);
+				else if (w.startsWith("--split-string=")) splitValue = w.slice("--split-string=".length);
+				else if ((w === "-S" || w === "--split-string") && i + 1 < words.length) {
+					splitValue = words[i + 1]!;
+					consumed = 1;
+				}
+				if (splitValue !== undefined) {
+					words.splice(i, consumed + 1, ...envSplitWords(splitValue));
+					continue;
+				}
+				const clusteredValue = /^-[iv0]*([ua])(.*)$/.exec(w);
+				if (clusteredValue) {
+					i++;
+					if (!clusteredValue[2] && i < words.length) i++;
+					continue;
+				}
+				if (w.startsWith("-C") && w !== "-C") {
+					changesCwd = true;
+					i++;
+					continue;
+				}
 				if (!w.startsWith("-")) break;
 				i++;
+				if (w === "-C" || w === "--chdir" || w.startsWith("--chdir=")) changesCwd = true;
 				if (valueOptions.has(w) && i < words.length) i++;
 			}
 			continue;
@@ -230,10 +346,18 @@ export function unwrapShellWords(command: string): string[] {
 		}
 		break;
 	}
-	return words
+	return { words: words
 		.slice(i)
 		.map((w) => w.replace(/^[\({]+/, "").replace(/[\)};]+$/, ""))
-		.filter(Boolean);
+		.filter(Boolean), changesCwd };
+}
+
+export function unwrapShellWords(command: string): string[] {
+	return unwrapShellWordsImpl(command).words;
+}
+
+export function shellWrappersChangeCwd(command: string): boolean {
+	return unwrapShellWordsImpl(command).changesCwd;
 }
 
 export function unwrapShellCommand(command: string): string {

package/src/policies/changelog.ts

@@ -1,8 +1,8 @@
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { isAbsolute, resolve } from "node:path";
 import { getWorkspaceRoot } from "../lib/state.ts";
-import { splitShellSegments, unwrapShellCommand } from "../lib/utils.ts";
+import { splitShellSegments, unwrapShellCommand, unwrapShellWords } from "../lib/utils.ts";
 
 export const CHANGELOG_SECTION_RE = /^\s*(?:#{1,6}\s*)?changelog\s*(?::|$)/im;
 
@@ -20,6 +20,84 @@ export function hasPrCreateInvocation(command: string): boolean {
 // Accepts either a CHANGELOG file modification or a .changeset/*.md file.
 const CHANGELOG_OR_CHANGESET_RE = /(?:changelog|\.changeset\/[^/]+\.md$)/i;
 
+function decodeAnsiCLineBreaks(value: string): string {
+	let decoded = "";
+	for (let i = 0; i < value.length; i += 1) {
+		if (value[i] !== "\\" || i + 1 >= value.length) {
+			decoded += value[i];
+			continue;
+		}
+		const next = value[++i];
+		if (next === "n") decoded += "\n";
+		else if (next === "r") decoded += "\r";
+		else if (next === "\\") decoded += "\\";
+		else decoded += `\\${next}`;
+	}
+	return decoded;
+}
+
+function preserveAnsiCLineBreaks(command: string): string {
+	return command.replace(/\$'((?:\\.|[^'])*)'/g, (_match, value: string) => {
+		const decoded = decodeAnsiCLineBreaks(value).replace(/'/g, "'\\''");
+		return `'${decoded}'`;
+	});
+}
+
+function prShellWords(command: string): string[] {
+	const words: string[] = [];
+	let word = "";
+	let quote: "'" | '"' | "ansi" | undefined;
+	let started = false;
+	for (let i = 0; i < command.length; i += 1) {
+		const char = command[i]!;
+		if (!quote && char === "$" && command[i + 1] === "'") {
+			quote = "ansi";
+			started = true;
+			i += 1;
+			continue;
+		}
+		if (quote === "ansi") {
+			if (char === "'") {
+				quote = undefined;
+				continue;
+			}
+			if (char === "\\" && i + 1 < command.length) {
+				let escape = char + command[++i];
+				word += decodeAnsiCLineBreaks(escape);
+				continue;
+			}
+			word += char;
+			continue;
+		}
+		if (char === "'" || char === '"') {
+			if (!quote) quote = char;
+			else if (quote === char) quote = undefined;
+			else word += char;
+			started = true;
+			continue;
+		}
+		if (char === "\\" && quote !== "'") {
+			const next = command[++i];
+			if (next !== "\n") {
+				if (quote === '"' && next && !['$', '`', '"', '\\'].includes(next)) word += "\\";
+				word += next ?? "\\";
+			}
+			started = true;
+			continue;
+		}
+		if (!quote && /\s/.test(char)) {
+			if (started) words.push(word);
+			word = "";
+			started = false;
+			continue;
+		}
+		word += char;
+		started = true;
+	}
+	if (started) words.push(word);
+	return words;
+}
+
 export function branchHasChangelogChange(root: string): boolean {
 	try {
 		const baseCandidates = ["origin/HEAD", "origin/main", "origin/master"];
@@ -54,23 +132,44 @@ export function branchHasChangelogChange(root: string): boolean {
 	}
 }
 
-export function prBodyIncludesChangelog(command: string): boolean {
-	const bodyMatch = command.match(
-		/(?:--body|--description|-d|-b)(?:=|\s+)(?:"([^"]*)"|'([^']*)'|([^\s|;&]+))/,
-	);
-	const body = bodyMatch?.[1] ?? bodyMatch?.[2] ?? bodyMatch?.[3] ?? "";
-	if (CHANGELOG_SECTION_RE.test(body)) {
-		return true;
+export function prBodyIncludesChangelog(command: string, invocationRoot: string | null = getWorkspaceRoot()): boolean {
+	const parsedWords = prShellWords(command);
+	const envIndex = parsedWords.indexOf("env");
+	const usesEnvSplitString = envIndex >= 0 && parsedWords.slice(envIndex + 1).some((word) =>
+		word === "-S" || word.startsWith("-S") || word === "--split-string" || word.startsWith("--split-string="));
+	const commandWords = usesEnvSplitString
+		? unwrapShellWords(preserveAnsiCLineBreaks(command))
+		: parsedWords;
+	const cliIndex = commandWords.findIndex((word) => word === "gh" || word === "az");
+	const words = cliIndex >= 0 ? commandWords.slice(cliIndex) : [];
+	let body = "";
+	let bodyFile: string | undefined;
+	const valueOptions = new Set([
+		"--assignee", "--base", "--head", "--head-repo", "--label", "--milestone",
+		"--project", "--recover", "--reviewer", "--template", "--title",
+		"--bypass-policy-reason", "--labels", "--merge-commit-message", "--org",
+		"--repository", "--required-reviewer-ids", "--reviewer-ids", "--source-branch",
+		"--target-branch", "--work-items", "-a", "-B", "-H", "-l", "-m", "-p", "-r", "-T", "-t",
+	]);
+	for (let i = 0; i < words.length; i += 1) {
+		const word = words[i]!;
+		if (["--description", "-d"].includes(word)) {
+			const lines: string[] = [];
+			while (i + 1 < words.length && !words[i + 1]!.startsWith("-")) lines.push(words[++i]!);
+			body = lines.join("\n");
+		}
+		else if (["--body", "-b"].includes(word)) body = words[++i] ?? "";
+		else if (/^(?:--body|--description)=/.test(word)) body = word.slice(word.indexOf("=") + 1);
+		else if (["--body-file", "--description-file", "-F"].includes(word)) bodyFile = words[++i];
+		else if (/^(?:--body-file|--description-file)=/.test(word)) bodyFile = word.slice(word.indexOf("=") + 1);
+		else if (valueOptions.has(word)) i += 1;
 	}
-	const bodyFileMatch = command.match(
-		/(?:--body-file|--description-file|-F)(?:=|\s+)(?:"([^"]*)"|'([^']*)'|([^\s|;&]+))/,
-	);
-	const bodyFile =
-		bodyFileMatch?.[1] ?? bodyFileMatch?.[2] ?? bodyFileMatch?.[3];
+	if (CHANGELOG_SECTION_RE.test(body)) return true;
 	if (bodyFile) {
 		try {
+			if (!isAbsolute(bodyFile) && invocationRoot === null) return false;
 			return CHANGELOG_SECTION_RE.test(
-				readFileSync(resolve(getWorkspaceRoot(), bodyFile), "utf8"),
+				readFileSync(isAbsolute(bodyFile) ? bodyFile : resolve(invocationRoot!, bodyFile), "utf8"),
 			);
 		} catch {
 			return false;

package/src/policies/continuation.ts

@@ -0,0 +1,83 @@
+import { randomUUID } from "node:crypto";
+import { getSdkClient } from "../lib/state.ts";
+import { effectiveTodosWithOwner, hasActiveTodo } from "./todo.ts";
+
+const MAX_CONSECUTIVE_CONTINUATIONS = 3;
+type ContinuationState = {
+	counts: Map<string, number>;
+	generatedMessageIDs: Map<string, Set<string>>;
+	inFlight: Set<string>;
+};
+const states = new WeakMap<object, ContinuationState>();
+
+function getState(): ContinuationState | undefined {
+	const client = getSdkClient();
+	if (!client || (typeof client !== "object" && typeof client !== "function")) return undefined;
+	let state = states.get(client as object);
+	if (!state) {
+		state = { counts: new Map(), generatedMessageIDs: new Map(), inFlight: new Set() };
+		states.set(client as object, state);
+	}
+	return state;
+}
+
+export async function continueUnfinishedSession(sessionID: string): 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;
+
+		const count = state.counts.get(sessionID) ?? 0;
+		if (count >= MAX_CONSECUTIVE_CONTINUATIONS) return false;
+
+		const session = getSdkClient()?.session;
+		if (typeof session?.promptAsync !== "function") return false;
+
+		const messageID = `workflow-guard-${randomUUID()}`;
+		state.counts.set(sessionID, count + 1);
+		const generatedIDs = state.generatedMessageIDs.get(sessionID) ?? new Set<string>();
+		generatedIDs.add(messageID);
+		state.generatedMessageIDs.set(sessionID, generatedIDs);
+		try {
+			await session.promptAsync({
+				path: { id: sessionID },
+				body: {
+					messageID,
+					parts: [{
+						type: "text",
+						text: "Workflow Guard: unfinished todos remain. Continue working through them. If you need user input, use the question tool instead of ending the run.",
+					}],
+				},
+			});
+			return true;
+		} catch {
+			state.counts.set(sessionID, count);
+			generatedIDs.delete(messageID);
+			if (generatedIDs.size === 0) state.generatedMessageIDs.delete(sessionID);
+			return false;
+		}
+	} finally {
+		state.inFlight.delete(sessionID);
+	}
+}
+
+export function recordUserMessage(sessionID: string, messageID?: string): void {
+	const state = getState();
+	if (!state) return;
+	const generatedIDs = state.generatedMessageIDs.get(sessionID);
+	if (messageID && generatedIDs?.delete(messageID)) {
+		if (generatedIDs.size === 0) state.generatedMessageIDs.delete(sessionID);
+		return;
+	}
+	state.counts.delete(sessionID);
+}
+
+export function clearContinuationState(sessionID: string): void {
+	const state = getState();
+	if (!state) return;
+	state.counts.delete(sessionID);
+	state.generatedMessageIDs.delete(sessionID);
+	state.inFlight.delete(sessionID);
+}

package/src/policies/planning.ts

@@ -0,0 +1,50 @@
+import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+
+const PRIMARY_TODO_NAMES = ["TODO.md", "todo.md"];
+const FALLBACK_NAMES = [
+	"ROADMAP.md", "roadmap.md",
+	"PLAN.md", "plan.md",
+	"TASKS.md", "tasks.md",
+	"BACKLOG.md", "backlog.md",
+];
+
+export interface PlanningSource {
+	path: string;
+	content: string;
+}
+
+export function discoverPlanningSources(root: string): PlanningSource[] {
+	let realRoot: string;
+	try {
+		realRoot = realpathSync(root);
+	} catch {
+		return [];
+	}
+	const isConfined = (path: string): boolean => {
+		const rel = relative(realRoot, realpathSync(path));
+		return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+	};
+	const readSources = (paths: string[]): PlanningSource[] => paths.flatMap((path) => {
+		try {
+			// Planning discovery is read-only and must not become a symlink escape hatch.
+			if (!lstatSync(path).isFile() || !isConfined(path)) return [];
+			return [{ path: relative(root, path), content: readFileSync(path, "utf8").slice(0, 20_000) }];
+		} catch {
+			return [];
+		}
+	});
+
+	const primary = readSources(PRIMARY_TODO_NAMES.map((name) => join(root, name)));
+	if (primary.length > 0) return primary;
+
+	const candidates = FALLBACK_NAMES.flatMap((name) => [join(root, name), join(root, "docs", name)]);
+	const plansDir = join(root, "docs", "plans");
+	try {
+		if (!lstatSync(plansDir).isDirectory() || !isConfined(plansDir)) return readSources(candidates);
+		for (const entry of readdirSync(plansDir, { withFileTypes: true })) {
+			if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) candidates.push(join(plansDir, entry.name));
+		}
+	} catch {}
+	return readSources(candidates);
+}

package/src/policies/todo.ts

@@ -35,6 +35,12 @@ export async function fetchParentSessionID(sessionID: string): Promise<string |
 export async function effectiveTodos(
 	sessionID: string | undefined,
 ): Promise<TodoItem[] | undefined> {
+	return (await effectiveTodosWithOwner(sessionID))?.todos;
+}
+
+export async function effectiveTodosWithOwner(
+	sessionID: string | undefined,
+): Promise<{ todos: TodoItem[]; ownerSessionID?: string } | undefined> {
 	if (!sessionID) return undefined;
 	const seen = new Set<string>();
 	let current: string | undefined = sessionID;
@@ -42,10 +48,10 @@ export async function effectiveTodos(
 		seen.add(current);
 		const todos = await fetchSessionTodos(current);
 		if (todos === undefined) return undefined;
-		if (todos.length > 0) return todos;
+		if (todos.length > 0) return { todos, ownerSessionID: current };
 		current = await fetchParentSessionID(current);
 	}
-	return [];
+	return { todos: [] };
 }
 
 export async function effectiveTodoOwnerSessionID(

package/src/workflow-guard.ts

@@ -89,7 +89,9 @@ import {
 	asRecord,
 	extractCommands,
 	normalize,
+	shellWrappersChangeCwd,
 	splitShellSegments,
+	unwrapShellCommand,
 	getCleanEnv,
 	showBlockToast,
 	SENSITIVE_ENV_KEYS,
@@ -204,6 +206,13 @@ import {
 	effectiveTodoOwnerSessionID,
 	hasActiveTodo,
 } from "./policies/todo.ts";
+import {
+	clearContinuationState,
+	continueUnfinishedSession,
+	recordUserMessage,
+} from "./policies/continuation.ts";
+import { discoverPlanningSources } from "./policies/planning.ts";
+export { discoverPlanningSources };
 
 export { validateTodoLifecycle };
 
@@ -301,6 +310,14 @@ function logBlock(message: string): void {
 	} catch {}
 }
 
+function logObservation(client: unknown, message: string): void {
+	try {
+		void (client as any)?.app?.log?.({
+			body: { service: "workflow-guard", level: "info", message },
+		});
+	} catch {}
+}
+
 const READ_ONLY_ROLES = new Set([
 	"reviewer",
 	"planner",
@@ -877,11 +894,19 @@ async function guardToolCallImpl(
 			}
 
 			const branchChangelog = branchHasChangelogChange(currentRoot);
-			const prSegments = splitShellSegments(raw)
-				.filter((segment) => hasPrCreateInvocation(segment));
+			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) => prBodyIncludesChangelog(segment));
+				prSegments.every(({ segment, invocationRoot }) => prBodyIncludesChangelog(segment, invocationRoot));
 			if (!hasChangelog) {
 				preflightFailures.push(`Changelog is required; update a CHANGELOG file or include a 'Changelog:' section in the PR description (${descFlag}).`);
 			}
@@ -991,8 +1016,13 @@ async function emitBlockFeedback(message: string): Promise<void> {
 
 export const WorkflowGuard: Plugin = async (ctx) => {
 	// Honor worktree if present (e.g. opencode worktrees or devcontainers)
-	// so worktree plugins cannot punch through boundary gates.
-	const effectiveRoot = ctx.worktree || ctx.directory || process.cwd();
+	// so worktree plugins cannot punch through boundary gates. When the host
+	// reports the filesystem root, use the SDK's actual project worktree instead.
+	const hostRoot = ctx.worktree || ctx.directory || process.cwd();
+	const hostIsFilesystemRoot = resolve(hostRoot) === resolve(hostRoot, "..");
+	const effectiveRoot = hostIsFilesystemRoot && ctx.project?.worktree
+		? ctx.project.worktree
+		: hostRoot;
 	setWorkspaceRoot(effectiveRoot);
 	setSdkClient(ctx.client);
 	reloadProjectConfig(effectiveRoot);
@@ -1021,6 +1051,17 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 
 	return {
 		tool: {
+			guard_next_tasks: tool({
+				description:
+					"Load durable repository task context when deciding what to work on next. Prefers TODO.md; if absent, discovers conventional roadmap, plan, tasks, backlog, and docs/plans Markdown files.",
+				args: {},
+				execute: async () => {
+					const sources = discoverPlanningSources(effectiveRoot);
+					return sources.length > 0
+						? JSON.stringify({ sources }, null, 2)
+						: JSON.stringify({ sources: [], message: "No TODO, roadmap, plan, tasks, or backlog Markdown files found." });
+				},
+			}),
 			project_memory_search: tool({
 				description: "Search current durable knowledge for this project. Returns concise typed records with provenance; superseded records are excluded.",
 				args: { query: tool.schema.string() },
@@ -1526,7 +1567,7 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 				const text = typeof output.text === "string" ? output.text : "";
 				const check = checkCompletionClaims(text, { sessionID });
 				if (check.claimsCompletion && check.evidenceState && check.evidenceState !== "fresh-pass") {
-					logBlock(`[workflow-guard] completion claim mismatch: ${check.reason}`);
+					logObservation(ctx.client, `[workflow-guard] completion claim mismatch: ${check.reason}`);
 					audit({
 						ts: new Date().toISOString(),
 						sessionID,
@@ -1553,6 +1594,26 @@ export const WorkflowGuard: Plugin = async (ctx) => {
 		event: async ({
 			event,
 		}: { event: { type?: string; properties?: unknown } }) => {
+			if (event?.type === "session.idle") {
+				const sessionID = (event.properties as { sessionID?: unknown })?.sessionID;
+				if (typeof sessionID === "string") {
+					await runWithRuntimeState(effectiveRoot, ctx.client, () => continueUnfinishedSession(sessionID));
+				}
+			}
+			if (event?.type === "message.updated") {
+				const info = (event.properties as { info?: { id?: unknown; role?: unknown; sessionID?: 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);
+					});
+				}
+			}
+			if (event?.type === "session.deleted") {
+				const sessionID = (event.properties as { info?: { id?: unknown } })?.info?.id;
+				if (typeof sessionID === "string") {
+					await runWithRuntimeState(effectiveRoot, ctx.client, () => clearContinuationState(sessionID));
+				}
+			}
 			if (
 				event?.type === "command.executed" ||
 				event?.type === "permission.updated" ||