@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/src/resources/extensions/gsd/bootstrap/tool-call-loop-guard.ts

@@ -1,18 +1,32 @@
 /**
  * Tool-call loop guard.
  *
- * Detects when a model calls the same tool with identical arguments
- * repeatedly within a single agent turn. Works in both auto-mode and
- * interactive sessions by hooking into the `tool_call` event, which
- * fires before execution and can block the call.
+ * Detects when a model repeats tool calls within a single Agent Turn.
+ * Works in both auto-mode and interactive sessions by hooking into the
+ * native engine's `tool_call` event, which fires before execution and can
+ * block the call.
  *
- * The guard uses a sliding window: it tracks the last N tool signatures
- * and blocks when the same signature appears more than MAX_CONSECUTIVE
- * times in a row. Resets on each agent turn (session_start, agent_end)
- * and when a different tool call breaks the streak.
+ * The guard has two independent checks: a sliding window for identical
+ * tool signatures, and a per-tool-name cap for repeated calls with varied
+ * arguments. State resets at Agent Turn boundaries (session_start,
+ * agent_end) and the identical-signature streak also resets when a
+ * different tool call breaks the streak. Block messages instruct the model
+ * to stop tooling for the rest of that turn and answer in text.
+ *
+ * The per-tool-name check (#783 Brief C) tracks call counts within a
+ * turn regardless of args, decaying after successful state-mutating tools.
+ * This catches improvisation
+ * loops where the model attempts the same missing workflow tool through
+ * varied surfaces (bash → `node -e` → CLI), each with a different
+ * signature, so the identical-args streak never trips, while allowing
+ * tool-heavy turns that are making file-mutation progress. Whichever guard
+ * trips first blocks.
  */
 
 import { createHash } from "node:crypto";
+import { INHERENTLY_REPEATABLE_TOOL_SET } from "./core-session-tools.js";
+import { hasBrowserContractPrefix } from "../../shared/browser-contract.js";
+import { canonicalToolName } from "../engine-hook-contract.js";
 
 const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
 
@@ -20,11 +34,31 @@ const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
 const STRICT_LOOP_TOOLS = new Set(["ask_user_questions"]);
 const MAX_CONSECUTIVE_STRICT = 1;
 
+/**
+ * Per-turn cap on calls to the SAME tool name, regardless of args (#783).
+ *
+ * General-purpose execution tools are routinely called many times per turn
+ * (touching multiple files, running several commands), so they get a higher
+ * ceiling. Everything else — workflow one-shot tools (e.g. gsd_complete_milestone)
+ * and any non-allowlisted tool — gets the default cap. The default is generous
+ * enough to absorb legitimate retries but catches the reported improvisation
+ * loop (~51 calls) well before a cost spike.
+ */
+const PER_TOOL_DEFAULT_CAP = 6;
+const PER_TOOL_REPEATABLE_CAP = 15;
+const PER_TOOL_CAP_EXEMPT_TOOLS = new Set(["find", "glob", "grep", "ls", "read", "search_and_read"]);
+const STATE_MUTATING_TOOL_SET = new Set(["edit", "write", "multi_edit", "notebook_edit"]);
+
 let consecutiveCount = 0;
 let lastSignature = "";
 let lastToolName = "";
 let enabled = true;
 
+/** Per-tool-name call counts within the current turn (#783 Brief C). */
+const perToolCounts = new Map<string, number>();
+let mutationEpoch = 0;
+const perToolLastMutationEpoch = new Map<string, number>();
+
 /** Hash tool name + args into a compact signature for comparison. */
 function hashToolCall(toolName: string, args: Record<string, unknown>): string {
   const h = createHash("sha256");
@@ -46,6 +80,13 @@ function hashToolCall(toolName: string, args: Record<string, unknown>): string {
  *
  * Returns `{ block: false }` for allowed calls.
  * Returns `{ block: true, reason }` when the loop threshold is exceeded.
+ *
+ * Two independent guards run; whichever trips first blocks:
+ *  1. Identical-signature streak (MAX_CONSECUTIVE_IDENTICAL_CALLS, strict for
+ *     ask_user_questions).
+ *  2. Per-tool-name cap (PER_TOOL_DEFAULT_CAP / PER_TOOL_REPEATABLE_CAP),
+ *     independent of args, reset after file-mutation progress — catches
+ *     improvisation loops (#783).
  */
 export function checkToolCallLoop(
   toolName: string,
@@ -63,6 +104,7 @@ export function checkToolCallLoop(
     lastToolName = toolName;
   }
 
+  // ── Guard 1: identical-signature streak ──
   const threshold = STRICT_LOOP_TOOLS.has(toolName)
     ? MAX_CONSECUTIVE_STRICT
     : MAX_CONSECUTIVE_IDENTICAL_CALLS;
@@ -71,22 +113,73 @@ export function checkToolCallLoop(
     return {
       block: true,
       reason:
-        `Tool loop detected: ${toolName} called ${consecutiveCount} times ` +
+        `Tool loop detected (identical args): ${toolName} called ${consecutiveCount} times ` +
         `with identical arguments. Blocking to prevent infinite loop. ` +
-        `Try a different approach or modify your arguments.`,
+        `Do not retry this tool or call other tools this turn — stop and respond to the user in text.`,
       count: consecutiveCount,
     };
   }
 
+  // ── Guard 2: per-tool-name cap, independent of args (#783 Brief C) ──
+  // Catches improvisation loops where the same tool is invoked many times with
+  // varied args (e.g. retrying a missing workflow tool via bash/node -e/CLI).
+  const priorPerToolCount =
+    (perToolLastMutationEpoch.get(toolName) ?? mutationEpoch) < mutationEpoch
+      ? 0
+      : (perToolCounts.get(toolName) ?? 0);
+  const perToolCount = priorPerToolCount + 1;
+  perToolCounts.set(toolName, perToolCount);
+  perToolLastMutationEpoch.set(toolName, mutationEpoch);
+
+  // Read-only navigation tools are normal context gathering; Guard 1 still
+  // catches true reread loops with identical arguments. Browser Automation
+  // Contract tools (browser_*) are the same shape: a browser-backed UAT makes
+  // many distinct-arg calls (read a message, count edits, inspect a card, …),
+  // so the arg-independent per-tool cap misfires on legitimate verification;
+  // Guard 1's identical-signature streak still catches a genuinely stuck
+  // browser loop.
+  if (
+    PER_TOOL_CAP_EXEMPT_TOOLS.has(toolName) ||
+    hasBrowserContractPrefix(canonicalToolName(toolName))
+  ) {
+    return { block: false, count: consecutiveCount };
+  }
+
+  const perToolCap = INHERENTLY_REPEATABLE_TOOL_SET.has(toolName)
+    ? PER_TOOL_REPEATABLE_CAP
+    : PER_TOOL_DEFAULT_CAP;
+
+  if (perToolCount > perToolCap) {
+    return {
+      block: true,
+      reason:
+        `Tool loop detected (repeated tool): ${toolName} called ${perToolCount} times ` +
+        `this turn (cap ${perToolCap}). Blocking to prevent infinite loop. ` +
+        `The tool may be unavailable or failing repeatedly. ` +
+        `Do not retry this tool or pivot to other tools this turn — stop and respond to the user in text.`,
+      count: perToolCount,
+    };
+  }
+
   return { block: false, count: consecutiveCount };
 }
 
+/** Record successful mutation progress so Guard 2 can decay on the next count. */
+export function recordToolCallLoopMutation(toolName: string): void {
+  if (!enabled) return;
+  if (!STATE_MUTATING_TOOL_SET.has(toolName)) return;
+  mutationEpoch++;
+}
+
 /** Reset the guard state. Call at agent turn boundaries. */
 export function resetToolCallLoopGuard(): void {
   consecutiveCount = 0;
   lastSignature = "";
   lastToolName = "";
   enabled = true;
+  perToolCounts.clear();
+  mutationEpoch = 0;
+  perToolLastMutationEpoch.clear();
 }
 
 /** Disable the guard (e.g. during shutdown). */
@@ -95,9 +188,20 @@ export function disableToolCallLoopGuard(): void {
   consecutiveCount = 0;
   lastSignature = "";
   lastToolName = "";
+  perToolCounts.clear();
+  mutationEpoch = 0;
+  perToolLastMutationEpoch.clear();
 }
 
 /** Get current consecutive count for diagnostics. */
 export function getToolCallLoopCount(): number {
   return consecutiveCount;
 }
+
+/**
+ * Get the per-tool-name call count for the current turn (#783 Brief C).
+ * Returns 0 for tools not yet called. Diagnostic only.
+ */
+export function getToolCallCountForTool(toolName: string): number {
+  return perToolCounts.get(toolName) ?? 0;
+}

package/src/resources/extensions/gsd/bootstrap/tool-search-shim.ts

@@ -31,8 +31,26 @@ export function registerToolSearchShim(pi: ExtensionAPI): void {
 		},
 	});
 
-	const active = pi.getActiveTools();
-	if (!active.includes("ToolSearch")) {
-		pi.setActiveTools([...active, "ToolSearch"]);
+	// Ensure the shim is part of the active tool set. registerTool() is valid
+	// during extension loading, but getActiveTools()/setActiveTools() are stubs
+	// that throw "Extension runtime not initialized" until runner.bindCore() runs
+	// (after all registerExtension() calls return). When the throw was hit, the
+	// catch in register-extension.ts swallowed it — leaving the whole bootstrap
+	// partially failed and, under Claude Code CLI, the workflow tools could end
+	// up missing from the model's surface, which traps plan-milestone in a
+	// finalize-retry loop with no gsd_plan_milestone available.
+	//
+	// The activation here is also redundant post-bind: ToolSearch is in
+	// MINIMAL_AUTO_BASE_TOOL_NAMES, so buildMinimalAutoGsdToolSet adds it during
+	// adjust_tool_set (before_agent_start). Tolerate the loading-stub throw so
+	// the shim always registers; activation is completed by post-bind scoping.
+	try {
+		const active = pi.getActiveTools();
+		if (!active.includes("ToolSearch")) {
+			pi.setActiveTools([...active, "ToolSearch"]);
+		}
+	} catch {
+		// Pre-bind runtime: getActiveTools/setActiveTools are not yet wired.
+		// The tool is registered; activation happens at adjust_tool_set.
 	}
 }

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -25,6 +25,12 @@ export const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
 const CONTEXT_MILESTONE_RE = /(?:^|[/\\])(M\d+(?:-[a-z0-9]{6})?)-CONTEXT\.md$/i;
 const DEPTH_VERIFICATION_MILESTONE_RE = /depth_verification[_-](M\d+(?:-[a-z0-9]{6})?)/i;
 
+function normalizeMilestoneId(milestoneId: string): string {
+  const match = milestoneId.match(/^(M)(\d+)(?:-([a-z0-9]{6}))?$/i);
+  if (!match) return milestoneId;
+  return `M${match[2]}${match[3] ? `-${match[3].toLowerCase()}` : ""}`;
+}
+
 /**
  * Path segment that identifies .gsd/ planning artifacts.
  * Writes to these paths are allowed during queue mode.
@@ -91,8 +97,19 @@ function createEmptyWriteGateState(): InMemoryWriteGateState {
 
 const writeGateStatesByBasePath = new Map<string, InMemoryWriteGateState>();
 
+/**
+ * Write-gate snapshots are project-scoped, not worktree-scoped. When auto-mode
+ * routes MCP tool writes to `.gsd-worktrees/<MID>/`, depth verification still
+ * lands in the authoritative project `.gsd/runtime/` tree (or external-state
+ * symlink target). Without this canonicalization, `loadWriteGateSnapshot(worktree)`
+ * sees an empty snapshot and CONTEXT saves loop forever (#M020 gate loop).
+ */
+function resolveWriteGateSnapshotRoot(basePath: string): string {
+  return resolve(resolveWorktreeProjectRoot(basePath));
+}
+
 function writeGateStateKey(basePath: string): string {
-  return resolve(basePath);
+  return resolveWriteGateSnapshotRoot(basePath);
 }
 
 function getWriteGateState(basePath: string = process.cwd()): InMemoryWriteGateState {
@@ -155,17 +172,18 @@ function shouldPersistWriteGateSnapshot(env: NodeJS.ProcessEnv = process.env): b
 }
 
 function writeGateSnapshotPath(basePath: string): string {
-  return join(basePath, ".gsd", "runtime", "write-gate-state.json");
+  return join(resolveWriteGateSnapshotRoot(basePath), ".gsd", "runtime", "write-gate-state.json");
 }
 
 function ensureWriteGateSnapshotDirectory(basePath: string): void {
-  const gsdPath = join(basePath, ".gsd");
+  const snapshotRoot = resolveWriteGateSnapshotRoot(basePath);
+  const gsdPath = join(snapshotRoot, ".gsd");
   if (!existsSync(gsdPath)) {
     try {
       const stat = lstatSync(gsdPath);
       if (stat.isSymbolicLink()) {
         const target = readlinkSync(gsdPath);
-        mkdirSync(isAbsolute(target) ? target : resolve(basePath, target), { recursive: true });
+        mkdirSync(isAbsolute(target) ? target : resolve(snapshotRoot, target), { recursive: true });
       }
     } catch {
       // If .gsd truly does not exist, the runtime mkdir below will create it.
@@ -174,7 +192,7 @@ function ensureWriteGateSnapshotDirectory(basePath: string): void {
   mkdirSync(join(gsdPath, "runtime"), { recursive: true });
 }
 
-function currentWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
+export function currentWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
   const state = getWriteGateState(basePath);
   return {
     verifiedDepthMilestones: [...state.verifiedDepthMilestones].sort(),
@@ -228,7 +246,9 @@ function clearPersistedWriteGateSnapshot(basePath: string): void {
 function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
   const record = value && typeof value === "object" ? value as Record<string, unknown> : {};
   const verified = Array.isArray(record.verifiedDepthMilestones)
-    ? record.verifiedDepthMilestones.filter((item): item is string => typeof item === "string")
+    ? record.verifiedDepthMilestones
+        .filter((item): item is string => typeof item === "string")
+        .map(normalizeMilestoneId)
     : [];
   const verifiedGates = Array.isArray(record.verifiedApprovalGates)
     ? record.verifiedApprovalGates.filter((item): item is string => typeof item === "string")
@@ -289,7 +309,7 @@ export function loadWriteGateSnapshot(basePath: string): WriteGateSnapshot {
  *     guard that previously protected only the tool_execution_start window.
  */
 function mergeSnapshotIntoState(state: InMemoryWriteGateState, disk: WriteGateSnapshot): void {
-  for (const milestone of disk.verifiedDepthMilestones) state.verifiedDepthMilestones.add(milestone);
+  for (const milestone of disk.verifiedDepthMilestones) state.verifiedDepthMilestones.add(normalizeMilestoneId(milestone));
   for (const gate of disk.verifiedApprovalGates ?? []) state.verifiedApprovalGates.add(gate);
   state.activeQueuePhase = disk.activeQueuePhase;
   state.pendingGateId = disk.pendingGateId;
@@ -395,7 +415,7 @@ export function isMilestoneDepthVerified(
 ): boolean {
   if (!milestoneId) return false;
   refreshWriteGateStateFromDisk(basePath);
-  return getWriteGateState(basePath).verifiedDepthMilestones.has(milestoneId);
+  return getWriteGateState(basePath).verifiedDepthMilestones.has(normalizeMilestoneId(milestoneId));
 }
 
 export function isMilestoneDepthVerifiedInSnapshot(
@@ -403,7 +423,7 @@ export function isMilestoneDepthVerifiedInSnapshot(
   milestoneId: string | null | undefined,
 ): boolean {
   if (!milestoneId) return false;
-  return snapshot.verifiedDepthMilestones.includes(milestoneId);
+  return snapshot.verifiedDepthMilestones.includes(normalizeMilestoneId(milestoneId));
 }
 
 export function isQueuePhaseActive(basePath: string = process.cwd()): boolean {
@@ -466,7 +486,7 @@ export function isGateQuestionId(questionId: string): boolean {
  */
 export function extractDepthVerificationMilestoneId(questionId: string): string | null {
   const match = questionId.match(DEPTH_VERIFICATION_MILESTONE_RE);
-  return match?.[1] ?? null;
+  return match?.[1] ? normalizeMilestoneId(match[1]) : null;
 }
 
 /**
@@ -474,7 +494,7 @@ export function extractDepthVerificationMilestoneId(questionId: string): string
  */
 function extractContextMilestoneId(inputPath: string): string | null {
   const match = inputPath.match(CONTEXT_MILESTONE_RE);
-  return match?.[1] ?? null;
+  return match?.[1] ? normalizeMilestoneId(match[1]) : null;
 }
 
 /**
@@ -560,7 +580,7 @@ export const hostWriteGateAdapter: WriteGateStateAdapter = {
   markDepthVerified(milestoneId, basePath): void {
     if (!milestoneId) return;
     mutateWriteGateState(basePath, (state) => {
-      state.verifiedDepthMilestones.add(milestoneId);
+      state.verifiedDepthMilestones.add(normalizeMilestoneId(milestoneId));
     }, { writer: "host" });
   },
   markApprovalGateVerified(gateId, basePath): void {
@@ -601,7 +621,7 @@ export const childWriteGateAdapter: WriteGateStateAdapter = {
   markDepthVerified(milestoneId, basePath): void {
     if (!milestoneId) return;
     childMutate(basePath, (state) => {
-      state.verifiedDepthMilestones.add(milestoneId);
+      state.verifiedDepthMilestones.add(normalizeMilestoneId(milestoneId));
     });
   },
   markApprovalGateVerified(gateId, basePath): void {
@@ -735,6 +755,13 @@ export interface AskUserQuestionsGateQuestion {
 export interface AskUserQuestionsGateDetails {
   cancelled?: boolean;
   interrupted?: boolean;
+  /**
+   * True when the host elicitation channel timed out before the user answered.
+   * Distinct from `cancelled` (deliberate dismissal): the gate verdict maps
+   * this to "timeout" so callers pause-and-wait instead of letting the model
+   * re-ask into the same timeout loop (#852).
+   */
+  timed_out?: boolean;
   response?: {
     answers?: Record<string, { selected?: unknown } | undefined>;
   } | null;
@@ -744,7 +771,8 @@ export type AskUserQuestionsGateResult =
   | { status: "not-gate" }
   | { status: "waiting"; pendingGateId: string; interrupted: boolean }
   | { status: "verified"; gateId: string; milestoneId: string | null }
-  | { status: "declined"; gateId: string };
+  | { status: "declined"; gateId: string }
+  | { status: "timeout"; pendingGateId: string; interrupted: boolean };
 
 function findGateQuestion(
   questions: AskUserQuestionsGateQuestion[],
@@ -768,11 +796,22 @@ function verifyAnsweredGate(
 
 /** Map an unresolved (non-verified) gate verdict to the caller-facing result. */
 function unresolvedGateResult(
-  verdict: "declined" | "waiting" | "cancelled",
+  verdict: "declined" | "waiting" | "cancelled" | "timeout",
   gateId: string,
   details: AskUserQuestionsGateDetails,
 ): AskUserQuestionsGateResult {
   if (verdict === "declined") return { status: "declined", gateId };
+  if (verdict === "timeout") {
+    // Host elicitation expired before the user answered. The gate stays
+    // pending (fail-closed — a timeout is never approval), but the status is
+    // "timeout" so the caller pauses-and-waits instead of re-asking into the
+    // same timeout loop (#852).
+    return {
+      status: "timeout",
+      pendingGateId: gateId,
+      interrupted: details.interrupted === true,
+    };
+  }
   // "waiting" (and the unreachable post-cancel case): an empty selection is
   // not an answer — keep the gate pending and make the caller pause.
   return {
@@ -803,6 +842,16 @@ export function applyAskUserQuestionsGateResult(options: {
   const { basePath, questions, details, fallbackMilestoneId } = options;
   const currentPendingGate = getPendingGate(basePath);
   if (currentPendingGate) {
+    if (details.timed_out) {
+      // Host elicitation timed out before the user answered. Keep the gate
+      // pending (fail-closed) but report "timeout" so the caller pauses-and-
+      // waits instead of re-asking into the same timeout loop (#852).
+      return {
+        status: "timeout",
+        pendingGateId: currentPendingGate,
+        interrupted: details.interrupted === true,
+      };
+    }
     if (details.cancelled || !details.response) {
       return {
         status: "waiting",
@@ -821,6 +870,7 @@ export function applyAskUserQuestionsGateResult(options: {
     }
   }
 
+  if (details.timed_out) return { status: "not-gate" };
   if (details.cancelled || !details.response) return { status: "not-gate" };
 
   for (const question of questions) {
@@ -855,6 +905,24 @@ export function formatPendingAskUserQuestionsGateMessage(
   ].join(" ");
 }
 
+/**
+ * Format the LLM-facing message returned when a depth-confirmation gate
+ * elicitation times out. Distinct from {@link formatPendingAskUserQuestionsGateMessage}:
+ * a timeout must NOT tell the model to immediately re-ask (that re-triggers
+ * the same timeout loop). Instead it tells the model to stop, that auto-mode
+ * is paused, and that the user will respond on their own (#852).
+ */
+export function formatTimedOutAskUserQuestionsGateMessage(
+  pendingGateId: string,
+): string {
+  return [
+    `Depth confirmation on gate "${pendingGateId}" timed out waiting for a response.`,
+    "The user did not answer within the host elicitation window — do not re-ask in this turn, it will time out again.",
+    "Auto-mode is paused. Stop calling tools and wait for the user to respond on a new turn.",
+    "When the user replies with confirmation, the gate will be satisfied and work will resume.",
+  ].join(" ");
+}
+
 export function shouldBlockContextWrite(
   toolName: string,
   inputPath: string,
@@ -865,7 +933,7 @@ export function shouldBlockContextWrite(
   if (toolName !== "write") return { block: false };
   if (!MILESTONE_CONTEXT_RE.test(inputPath)) return { block: false };
 
-  const targetMilestoneId = extractContextMilestoneId(inputPath) ?? milestoneId;
+  const targetMilestoneId = extractContextMilestoneId(inputPath) ?? (milestoneId ? normalizeMilestoneId(milestoneId) : null);
   if (!targetMilestoneId) {
     return {
       block: true,
@@ -884,8 +952,8 @@ export function shouldBlockContextWrite(
     reason: [
       `HARD BLOCK: Cannot write to milestone CONTEXT.md without depth verification.`,
       `This is a mechanical gate — you MUST NOT proceed, retry, or rationalize past this block.`,
-      `Required action: call ask_user_questions with question id containing "depth_verification".`,
-      `The user MUST select the "(Recommended)" confirmation option to unlock this gate.`,
+      `Required action: call ask_user_questions with question id "depth_verification_${targetMilestoneId}_confirm".`,
+      `The user MUST select the first "(Recommended)" confirmation option to unlock this gate.`,
       `If the user declines, cancels, or the tool fails, you must re-ask — not bypass.`,
     ].join(" "),
   };
@@ -1101,7 +1169,7 @@ function allowsControlledSubagentDispatch(
   policy: ToolsPolicy,
 ): policy is ToolsPolicy & { readonly allowedSubagents: readonly string[] } {
   return (
-    (policy.mode === "planning-dispatch" || policy.mode === "verification") &&
+    (policy.mode === "planning-dispatch" || policy.mode === "verification" || policy.mode === "workflow-only") &&
     Array.isArray((policy as { readonly allowedSubagents?: unknown }).allowedSubagents)
   );
 }
@@ -1131,6 +1199,7 @@ function warnMissingControlledDispatchAgentClasses(unitType: string, mode: strin
 const PLANNING_SAFE_TOOLS = new Set([
   "read", "grep", "find", "ls", "glob",
   "ask_user_questions",
+  "memory_query",
   "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
   "search_and_read",
 ]);
@@ -1197,6 +1266,9 @@ type PlanningUnitBlockResult = {
  *                  → allows Bash for project verification commands, keeps
  *                    writes restricted to .gsd/, and permits subagent dispatch
  *                    only when the manifest declares allowedSubagents.
+ *   - "workflow-only"
+ *                  → allows reads, GSD workflow tools, and declared read-only
+ *                    subagents; blocks generic Bash and direct file writes.
  *
  * `pathOrCommand` is the file path for write/edit-shaped tools and the
  * shell command for bash. Other tools ignore this argument.
@@ -1286,6 +1358,24 @@ export function shouldBlockPlanningUnit(
     return planningBlock(unitType, policy.mode, "subagent dispatch is not permitted in planning units");
   }
 
+  if (policy.mode === "workflow-only") {
+    if (tool === "bash") {
+      return planningBlock(
+        unitType,
+        policy.mode,
+        `bash is not permitted; use the unit's dedicated GSD workflow tools for durable validation output`,
+      );
+    }
+    if (PLANNING_WRITE_TOOLS.has(tool)) {
+      return planningBlock(
+        unitType,
+        policy.mode,
+        `cannot ${tool} "${pathOrCommand}" — direct artifact writes are disabled; call the required GSD workflow tool instead`,
+      );
+    }
+    return planningBlock(unitType, policy.mode, `tool "${tool}" is not on the workflow-only allowlist`);
+  }
+
   if (tool === "bash") {
     if (policy.mode === "verification") {
       if (BASH_VERIFICATION_RE.test(pathOrCommand) || BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };