@opengsd/gsd-pi 1.1.1-dev.9bb7453 → 1.1.1-dev.a5a2de8

package/src/resources/extensions/gsd/auto-dispatch.ts

@@ -96,6 +96,10 @@ import { probeGitConflictState } from "./git-conflict-state.js";
 import { runTurnGitAction } from "./git-service.js";
 import { parseUnitId } from "./unit-id.js";
 import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import {
+  checkCloseoutConsistencyGate,
+  formatCloseoutConsistencyBlock,
+} from "./closeout-consistency-gate.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -1635,6 +1639,16 @@ export const DISPATCH_RULES: DispatchRule[] = [
             prompt: await buildCompleteMilestonePrompt(mid, midTitle, basePath),
           };
         }
+        if (milestone) {
+          const closeoutGate = checkCloseoutConsistencyGate(mid, { refreshFromDisk: true });
+          if (!closeoutGate.ok) {
+            return {
+              action: "stop",
+              reason: formatCloseoutConsistencyBlock(closeoutGate),
+              level: "warning",
+            };
+          }
+        }
       }
       return {
         action: "stop",

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -46,6 +46,7 @@ import { hasBrowserRequiredText } from "./browser-evidence.js";
 import { debugLog } from "./debug-logger.js";
 import { buildSkillActivationBlock, buildSkillDiscoveryVars } from "./skill-activation.js";
 import { findMilestoneIds } from "./milestone-ids.js";
+import { buildRunUatResultPresentation, RUN_UAT_TOOL_PRESENTATION_PLAN_ID } from "./tool-presentation-plan.js";
 
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
 
@@ -3384,6 +3385,7 @@ export async function buildRunUatPrompt(
 
   const uatResultPath = join(base, relSliceFile(base, mid, sliceId, "ASSESSMENT"));
   const uatType = resolveEffectiveUatType(uatContent);
+  const canonicalPresentation = JSON.stringify(buildRunUatResultPresentation(), null, 2);
 
   return loadPrompt("run-uat", {
     workingDirectory: base,
@@ -3392,6 +3394,8 @@ export async function buildRunUatPrompt(
     uatPath,
     uatResultPath,
     uatType,
+    toolPresentationPlanId: RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
+    canonicalPresentation,
     inlinedContext,
     skillActivation: buildSkillActivationBlock({
       base,

package/src/resources/extensions/gsd/auto-recovery.ts

@@ -54,6 +54,7 @@ import { isGsdWorktreePath } from "./worktree-root.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { loadAllCaptures, loadPendingCaptures } from "./captures.js";
+import { checkCloseoutConsistencyGate } from "./closeout-consistency-gate.js";
 
 // Re-export so existing consumers of auto-recovery.ts keep working.
 export { resolveExpectedArtifactPath, diagnoseExpectedArtifact };
@@ -626,9 +627,8 @@ export function verifyExpectedArtifact(
     if (summaryOutcome === "failure") return false;
     const { milestone: mid } = parseUnitId(unitId);
     if (mid && isDbAvailable()) {
-      const dbMilestone = getMilestone(mid);
-      if (!dbMilestone) return false;
-      if (!isClosedStatus(dbMilestone.status) && summaryOutcome !== "success") return false;
+      const closeoutGate = checkCloseoutConsistencyGate(mid, { refreshFromDisk: true });
+      if (!closeoutGate.ok) return false;
     }
     if (hasImplementationArtifacts(base, mid) === "absent") return false;
   }

package/src/resources/extensions/gsd/auto-unit-tool-scope.ts

@@ -1,59 +1,13 @@
 import { parseUnitId } from "./unit-id.js";
-import { RUN_UAT_WORKFLOW_TOOL_NAMES } from "./tool-presentation-plan.js";
-
-export const RUN_UAT_BROWSER_TOOL_NAMES = [
-  "browser_navigate",
-  "browser_click",
-  "browser_type",
-  "browser_fill_form",
-  "browser_click_ref",
-  "browser_fill_ref",
-  "browser_wait_for",
-  "browser_assert",
-  "browser_verify",
-  "browser_screenshot",
-  "browser_snapshot_refs",
-  "browser_find",
-  "browser_get_console_logs",
-  "browser_get_network_logs",
-  "browser_evaluate",
-  "browser_reload",
-  "browser_batch",
-  "browser_act",
-] as const;
+import {
+  AUTO_UNIT_SCOPED_TOOLS,
+  getForbiddenGsdToolReason,
+} from "./unit-tool-contracts.js";
 
-export const AUTO_UNIT_SCOPED_TOOLS: Record<string, readonly string[]> = {
-  "research-milestone": ["gsd_summary_save", "gsd_decision_save"],
-  "plan-milestone": ["gsd_plan_milestone", "gsd_decision_save", "gsd_requirement_update"],
-  "discuss-milestone": [
-    "gsd_summary_save",
-    "gsd_decision_save",
-    "gsd_requirement_save",
-    "gsd_requirement_update",
-    "gsd_plan_milestone",
-    "gsd_milestone_generate_id",
-  ],
-  "discuss-slice": ["gsd_summary_save", "gsd_decision_save"],
-  "validate-milestone": ["gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
-  "complete-milestone": ["gsd_complete_milestone", "subagent"],
-  "research-slice": ["gsd_summary_save", "gsd_decision_save"],
-  "plan-slice": ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
-  "refine-slice": ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
-  "replan-slice": ["gsd_replan_slice", "gsd_plan_task", "gsd_decision_save"],
-  "complete-slice": ["gsd_slice_complete", "gsd_task_reopen", "gsd_replan_slice", "gsd_decision_save", "gsd_requirement_update", "subagent"],
-  "reassess-roadmap": ["gsd_reassess_roadmap"],
-  "execute-task": ["gsd_task_complete", "gsd_decision_save"],
-  "execute-task-simple": ["gsd_task_complete", "gsd_decision_save"],
-  "reactive-execute": ["gsd_task_complete", "gsd_decision_save"],
-  "run-uat": [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent", ...RUN_UAT_BROWSER_TOOL_NAMES],
-  "gate-evaluate": ["gsd_save_gate_result"],
-  "rewrite-docs": ["gsd_summary_save", "gsd_decision_save"],
-  "workflow-preferences": ["gsd_summary_save"],
-  "discuss-project": ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
-  "discuss-requirements": ["gsd_requirement_save", "gsd_summary_save"],
-  "research-decision": ["gsd_summary_save"],
-  "research-project": ["gsd_summary_save", "gsd_decision_save"],
-};
+export {
+  AUTO_UNIT_SCOPED_TOOLS,
+  RUN_UAT_BROWSER_TOOL_NAMES,
+} from "./unit-tool-contracts.js";
 
 const WORKFLOW_TOOL_ALIASES: Record<string, string> = {
   gsd_save_decision: "gsd_decision_save",
@@ -97,6 +51,14 @@ const SCOPED_GSD_LIFECYCLE_TOOLS = new Set(
     .map(canonicalWorkflowToolName),
 );
 
+export const GSD_PHASE_SCOPE_DISPLAY_REASON = "This GSD phase only allows its scoped workflow tools.";
+
+type AutoUnitToolScopeResult = {
+  block: boolean;
+  reason?: string;
+  displayReason?: string;
+};
+
 function stripMcpToolPrefix(toolName: string): string {
   if (!toolName.startsWith("mcp__")) return toolName;
   const toolSeparator = toolName.indexOf("__", "mcp__".length);
@@ -114,12 +76,20 @@ export function isWorkflowAliasTool(toolName: string): boolean {
 
 function hardBlockReason(unitType: string, what: string): string {
   return [
-    `HARD BLOCK: unit "${unitType}" is constrained by auto-unit tool scope — ${what}.`,
+    `HARD BLOCK: Tool Contract failure for unit "${unitType}" — ${what}.`,
     "This is a mechanical phase-boundary gate. You MUST NOT proceed, retry the same call,",
     "or route around this block; the orchestrator owns phase transitions.",
   ].join(" ");
 }
 
+function hardBlock(unitType: string, what: string): AutoUnitToolScopeResult {
+  return {
+    block: true,
+    reason: hardBlockReason(unitType, what),
+    displayReason: GSD_PHASE_SCOPE_DISPLAY_REASON,
+  };
+}
+
 function allowedGsdToolsForUnit(unitType: string): string[] {
   return [...new Set(
     (AUTO_UNIT_SCOPED_TOOLS[unitType] ?? [])
@@ -144,7 +114,7 @@ function shouldBlockTaskCompletionScope(
   unitId: string | undefined,
   toolName: string,
   input: unknown,
-): { block: boolean; reason?: string } {
+): AutoUnitToolScopeResult {
   if (!EXECUTE_TASK_UNIT_TYPES.has(unitType)) return { block: false };
   if (canonicalWorkflowToolName(toolName) !== "gsd_task_complete") return { block: false };
   if (!unitId) return { block: false };
@@ -165,13 +135,10 @@ function shouldBlockTaskCompletionScope(
     return { block: false };
   }
 
-  return {
-    block: true,
-    reason: hardBlockReason(
-      unitType,
-      `gsd_task_complete may only complete the active task ${expected.milestone}/${expected.slice}/${expected.task}; requested ${actualMilestone}/${actualSlice}/${actualTask}`,
-    ),
-  };
+  return hardBlock(
+    unitType,
+    `gsd_task_complete may only complete the active task ${expected.milestone}/${expected.slice}/${expected.task}; requested ${actualMilestone}/${actualSlice}/${actualTask}`,
+  );
 }
 
 export function shouldBlockAutoUnitToolCall(
@@ -179,15 +146,12 @@ export function shouldBlockAutoUnitToolCall(
   toolName: string,
   input?: unknown,
   unitId?: string,
-): { block: boolean; reason?: string } {
+): AutoUnitToolScopeResult {
   const scopedTools = AUTO_UNIT_SCOPED_TOOLS[unitType];
   if (!scopedTools) return { block: false };
 
   if (isNativeWorkflowTool(toolName)) {
-    return {
-      block: true,
-      reason: hardBlockReason(unitType, "native Workflow is not permitted inside a dispatched GSD auto-mode unit"),
-    };
+    return hardBlock(unitType, "native Workflow is not permitted inside a dispatched GSD auto-mode unit");
   }
 
   const taskScope = shouldBlockTaskCompletionScope(unitType, unitId, toolName, input);
@@ -199,11 +163,16 @@ export function shouldBlockAutoUnitToolCall(
   const allowedTools = allowedGsdToolsForUnit(unitType);
   if (allowedTools.includes(canonicalTool)) return { block: false };
 
-  return {
-    block: true,
-    reason: hardBlockReason(
+  const forbiddenReason = getForbiddenGsdToolReason(unitType, canonicalTool);
+  if (forbiddenReason) {
+    return hardBlock(
       unitType,
-      `GSD lifecycle tool "${canonicalTool}" is not permitted; allowed GSD tools: ${allowedTools.length > 0 ? allowedTools.join(", ") : "(none)"}`,
-    ),
-  };
+      `GSD lifecycle tool "${canonicalTool}" is not permitted; ${forbiddenReason} Fix unit-tool-contracts.ts or the ${unitType} prompt.`,
+    );
+  }
+
+  return hardBlock(
+    unitType,
+    `GSD lifecycle tool "${canonicalTool}" is not permitted; allowed GSD tools: ${allowedTools.length > 0 ? allowedTools.join(", ") : "(none)"}`,
+  );
 }

package/src/resources/extensions/gsd/auto-worktree.ts

@@ -83,6 +83,11 @@ import {
   nativeWorktreeList,
   nativeLsFiles,
 } from "./native-git-bridge.js";
+import {
+  CLOSEOUT_CONSISTENCY_BLOCKED_REASON,
+  checkCloseoutConsistencyGate,
+  formatCloseoutConsistencyBlock,
+} from "./closeout-consistency-gate.js";
 import { gsdHome } from "./gsd-home.js";
 import { type MilestoneScope, type GsdWorkspace, createWorkspace } from "./workspace.js";
 import {
@@ -1771,16 +1776,29 @@ export function mergeMilestoneToMain(
   // symlink layout) — ATTACHing a WAL-mode file to itself corrupts the
   // database (#2823).
   if (isDbAvailable()) {
+    const contract = resolveGsdPathContract(worktreeCwd, originalBasePath_);
+    const worktreeDbPath = join(contract.worktreeGsd ?? join(worktreeCwd, ".gsd"), "gsd.db");
+    const mainDbPath = contract.projectDb;
     try {
-      const contract = resolveGsdPathContract(worktreeCwd, originalBasePath_);
-      const worktreeDbPath = join(contract.worktreeGsd ?? join(worktreeCwd, ".gsd"), "gsd.db");
-      const mainDbPath = contract.projectDb;
+      const activeDbPath = getDbPath();
+      if (activeDbPath && _shouldReconcileWorktreeDb(activeDbPath, mainDbPath)) {
+        closeDatabase();
+        if (!openDatabase(mainDbPath)) {
+          throw new Error(`cannot open project DB at ${mainDbPath}`);
+        }
+      }
       if (_shouldReconcileWorktreeDb(worktreeDbPath, mainDbPath)) {
         reconcileWorktreeDb(mainDbPath, worktreeDbPath);
       }
     } catch (err) {
-      /* non-fatal */
-      logError("worktree", `DB reconciliation failed: ${err instanceof Error ? err.message : String(err)}`);
+      const message = `DB reconciliation failed before milestone ${milestoneId} merge: ${err instanceof Error ? err.message : String(err)}`;
+      logError("worktree", message);
+      throw new GSDError(GSD_GIT_ERROR, `${message}. Recovery reason: ${CLOSEOUT_CONSISTENCY_BLOCKED_REASON}.`);
+    }
+
+    const closeoutGate = checkCloseoutConsistencyGate(milestoneId);
+    if (!closeoutGate.ok) {
+      throw new GSDError(GSD_GIT_ERROR, formatCloseoutConsistencyBlock(closeoutGate));
     }
   }
 

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -78,6 +78,9 @@ function readDetails(result: any): any {
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- result shape varies by tool
 function formatToolErrorText(result: any, details: any): string {
+  if (typeof details?.displayReason === "string" && details.displayReason) {
+    return details.displayReason;
+  }
   const message = details?.error
     ?? result?.content?.find((entry: { type?: string; text?: string }) => entry.type === "text")?.text
     ?? "unknown";
@@ -424,6 +427,9 @@ export function registerDbTools(pi: ExtensionAPI): void {
     kind: StringEnum(["gsd_uat_exec", "gsd_exec", "screenshot", "log", "url", "browser"], { description: "Evidence kind" }),
     ref: Type.String({ description: "Evidence ID, approved .gsd path, or URL" }),
     note: Type.Optional(Type.String({ description: "Short evidence note" })),
+    unitType: Type.Optional(Type.String({ description: "Unit that produced the evidence" })),
+    tool: Type.Optional(Type.String({ description: "Tool that produced the evidence" })),
+    executionId: Type.Optional(Type.String({ description: "Stable execution or artifact id" })),
   });
 
   const uatCheck = Type.Object({
@@ -437,17 +443,17 @@ export function registerDbTools(pi: ExtensionAPI): void {
   });
 
   const toolPresentationBlock = Type.Object({
-    surface: StringEnum(["provider-tools", "claude-code-sdk", "mcp", "hybrid"], { description: "Tool presentation surface" }),
+    surface: Type.Optional(StringEnum(["provider-tools", "claude-code-sdk", "mcp", "hybrid"], { description: "Tool presentation surface" })),
     model: Type.Optional(Type.Object({
       provider: Type.Optional(Type.String()),
       api: Type.Optional(Type.String()),
       id: Type.Optional(Type.String()),
     })),
-    presentedTools: Type.Array(Type.String(), { description: "Tool names actually presented to the model" }),
-    blockedTools: Type.Array(Type.Object({
+    presentedTools: Type.Optional(Type.Array(Type.String(), { description: "Tool names actually presented to the model" })),
+    blockedTools: Type.Optional(Type.Array(Type.Object({
       name: Type.String(),
       reason: Type.String(),
-    }), { description: "Tool names blocked from the model with reasons" }),
+    }), { description: "Tool names blocked from the model with reasons" })),
     aliases: Type.Optional(Type.Array(Type.Object({
       requested: Type.String(),
       canonical: Type.String(),
@@ -471,12 +477,12 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "Do not use raw gsd_summary_save as a substitute for UAT results.",
     ],
     parameters: Type.Object({
-      milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
-      sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
-      uatType: StringEnum(["artifact-driven", "browser-executable", "runtime-executable", "live-runtime", "mixed", "human-experience"], { description: "Declared UAT mode" }),
-      verdict: StringEnum(["PASS", "FAIL", "PARTIAL"], { description: "Overall UAT verdict" }),
-      checks: Type.Array(uatCheck, { description: "Structured check results" }),
-      presentation: toolPresentationBlock,
+      milestoneId: Type.Optional(Type.String({ description: "Milestone ID (e.g. M001)" })),
+      sliceId: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
+      uatType: Type.Optional(Type.String({ description: "Declared UAT mode" })),
+      verdict: Type.Optional(Type.String({ description: "Overall UAT verdict: PASS, FAIL, or PARTIAL" })),
+      checks: Type.Optional(Type.Array(uatCheck, { description: "Structured check results" })),
+      presentation: Type.Optional(toolPresentationBlock),
       notes: Type.Optional(Type.String({ description: "Overall verdict rationale" })),
       attempt: Type.Optional(Type.String({ description: "Attempt number or auto" })),
       previousAttemptId: Type.Optional(Type.String({ description: "Prior attempt ID, when retrying" })),

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -38,7 +38,7 @@ import { getGuidedUnitContext } from "../guided-unit-context.js";
 import { registerPlanMilestoneSchemaRecovery } from "./plan-milestone-schema-recovery.js";
 import { AUTO_UNIT_SCOPED_TOOLS, RUN_UAT_BROWSER_TOOL_NAMES, isWorkflowAliasTool } from "../auto-unit-tool-scope.js";
 import { filterToolsForProvider } from "../model-router.js";
-import { RUN_UAT_WORKFLOW_TOOL_NAMES } from "../tool-presentation-plan.js";
+import { RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES } from "../tool-presentation-plan.js";
 
 let approvalQuestionAbortInFlight = false;
 
@@ -252,7 +252,12 @@ export function buildRunUatGsdToolSet(
 ): string[] {
   const scoped = resolveScopedToolNames(
     [...activeToolNames, ...registeredToolNames],
-    [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent", ...RUN_UAT_BROWSER_TOOL_NAMES],
+    [
+      ...RUN_UAT_WORKFLOW_TOOL_NAMES,
+      ...RUN_UAT_READ_ONLY_TOOL_NAMES,
+      "subagent",
+      ...RUN_UAT_BROWSER_TOOL_NAMES,
+    ],
   );
   return [...new Set(scoped)];
 }
@@ -480,22 +485,30 @@ function isContextDraftSummarySave(toolName: string, input: unknown): boolean {
   return (input as { artifact_type?: unknown }).artifact_type === "CONTEXT-DRAFT";
 }
 
+function withDepthGateDisplayReason<T extends { block: boolean; reason?: string }>(
+  result: T,
+  displayReason = "Depth confirmation is waiting for your answer.",
+): T & { displayReason?: string } {
+  if (!result.block) return result;
+  return { ...result, displayReason };
+}
+
 function shouldBlockDeferredApprovalTool(
   toolName: string,
   input: unknown,
   basePath: string,
-): { block: boolean; reason?: string } {
+): { block: boolean; reason?: string; displayReason?: string } {
   if (deferredApprovalGate?.basePath !== basePath) return { block: false };
   if (toolName === "ask_user_questions") return { block: false };
   if (isContextDraftSummarySave(toolName, input)) return { block: false };
-  return {
+  return withDepthGateDisplayReason({
     block: true,
     reason: [
       `HARD BLOCK: Approval question "${deferredApprovalGate.gateId}" has been shown to the user.`,
       `Only CONTEXT-DRAFT persistence may finish in this same assistant turn.`,
       `Wait for the user's answer before calling additional tools.`,
     ].join(" "),
-  };
+  });
 }
 
 export function resolveNotificationStoreBasePath(basePath: string): string {
@@ -917,7 +930,7 @@ export function registerHooks(
               "Depth confirmation is waiting for your answer — pausing auto-mode.",
             );
           }
-          return bashGuard;
+          return withDepthGateDisplayReason(bashGuard);
         }
       } else {
         const gateGuard = shouldBlockPendingGate(
@@ -935,7 +948,7 @@ export function registerHooks(
               "Depth confirmation is waiting for your answer — pausing auto-mode.",
             );
           }
-          return gateGuard;
+          return withDepthGateDisplayReason(gateGuard);
         }
       }
     }
@@ -1040,7 +1053,9 @@ export function registerHooks(
       isQueuePhaseActive(discussionBasePath),
       discussionBasePath,
     );
-    if (result.block) return result;
+    if (result.block) {
+      return withDepthGateDisplayReason(result, "Depth check required before writing milestone context.");
+    }
   });
 
   // ── Safety harness: evidence collection + destructive command blocking ──

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

@@ -4,7 +4,7 @@ import { isAbsolute, join, relative, resolve, sep } from "node:path";
 
 import { minimatch } from "minimatch";
 
-import { shouldBlockAutoUnitToolCall } from "../auto-unit-tool-scope.js";
+import { GSD_PHASE_SCOPE_DISPLAY_REASON, shouldBlockAutoUnitToolCall } from "../auto-unit-tool-scope.js";
 import { getIsolationMode } from "../preferences.js";
 import { compileSubagentPermissionContract, type ToolsPolicy } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
@@ -772,6 +772,20 @@ function blockReason(unitType: string, mode: string, what: string): string {
   ].join(" ");
 }
 
+function planningBlock(unitType: string, mode: string, what: string): PlanningUnitBlockResult {
+  return {
+    block: true,
+    reason: blockReason(unitType, mode, what),
+    displayReason: GSD_PHASE_SCOPE_DISPLAY_REASON,
+  };
+}
+
+type PlanningUnitBlockResult = {
+  block: boolean;
+  reason?: string;
+  displayReason?: string;
+};
+
 /**
  * Planning-unit tool-policy enforcement. Returns { block } per the policy
  * resolved from the active unit's manifest:
@@ -812,7 +826,7 @@ export function shouldBlockPlanningUnit(
   agentClasses?: readonly string[],
   toolInput?: unknown,
   unitId?: string,
-): { block: boolean; reason?: string } {
+): PlanningUnitBlockResult {
   const tool = canonicalToolName(toolName);
   const autoScopeGuard = shouldBlockAutoUnitToolCall(unitType, toolName, toolInput, unitId);
   if (autoScopeGuard.block) return autoScopeGuard;
@@ -825,10 +839,10 @@ export function shouldBlockPlanningUnit(
     if (PLANNING_SAFE_TOOLS.has(tool)) return { block: false };
     if (tool.startsWith("gsd_")) return { block: false };
     if (PLANNING_WRITE_TOOLS.has(tool) || tool === "bash" || PLANNING_SUBAGENT_TOOLS.has(tool)) {
-      return { block: true, reason: blockReason(unitType, policy.mode, `${tool} is not permitted (read-only)`) };
+      return planningBlock(unitType, policy.mode, `${tool} is not permitted (read-only)`);
     }
     // Unknown tool in read-only mode — block by default.
-    return { block: true, reason: blockReason(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`) };
+    return planningBlock(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`);
   }
 
   // planning / planning-dispatch / docs / verification modes share the same surface for safe tools, bash, and subagent.
@@ -846,14 +860,11 @@ export function shouldBlockPlanningUnit(
       // instead of silently bypassing the gate.
       if (agentClasses === undefined) {
         warnMissingControlledDispatchAgentClasses(unitType, policy.mode, tool);
-        return {
-          block: true,
-          reason: blockReason(
-            unitType,
-            policy.mode,
-            `subagent dispatch blocked: stale caller did not supply agent identities for "${tool}"; update extractSubagentAgentClasses to handle this input shape`,
-          ),
-        };
+        return planningBlock(
+          unitType,
+          policy.mode,
+          `subagent dispatch blocked: stale caller did not supply agent identities for "${tool}"; update extractSubagentAgentClasses to handle this input shape`,
+        );
       }
       // agentClasses was explicitly provided but resolved to an empty list (for
       // example, a bare tool call with no agent field). Pass through; no agents
@@ -863,57 +874,45 @@ export function shouldBlockPlanningUnit(
       }
       const globallyDisallowed = requested.find(a => !isReadOnlySpecialist(a));
       if (globallyDisallowed) {
-        return {
-          block: true,
-          reason: blockReason(
-            unitType,
-            policy.mode,
-            `subagent dispatch of "${globallyDisallowed}" not permitted; only read-only specialists (${allowedPlanningDispatchAgentsList()}) may be dispatched from ${policy.mode} units`,
-          ),
-        };
+        return planningBlock(
+          unitType,
+          policy.mode,
+          `subagent dispatch of "${globallyDisallowed}" not permitted; only read-only specialists (${allowedPlanningDispatchAgentsList()}) may be dispatched from ${policy.mode} units`,
+        );
       }
       const disallowedByPolicy = requested.find(a => !allowed.has(a));
       if (disallowedByPolicy) {
-        return {
-          block: true,
-          reason: blockReason(
-            unitType,
-            policy.mode,
-            `subagent dispatch of "${disallowedByPolicy}" not permitted by ToolsPolicy.allowedSubagents; permitted agents for this unit: ${allowedSubagents.join(", ")}`,
-          ),
-        };
+        return planningBlock(
+          unitType,
+          policy.mode,
+          `subagent dispatch of "${disallowedByPolicy}" not permitted by ToolsPolicy.allowedSubagents; permitted agents for this unit: ${allowedSubagents.join(", ")}`,
+        );
       }
       return { block: false };
     }
-    return { block: true, reason: blockReason(unitType, policy.mode, `subagent dispatch is not permitted in planning units`) };
+    return planningBlock(unitType, policy.mode, "subagent dispatch is not permitted in planning units");
   }
 
   if (tool === "bash") {
     if (policy.mode === "verification") {
       if (BASH_VERIFICATION_RE.test(pathOrCommand) || BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };
-      return {
-        block: true,
-        reason: blockReason(
-          unitType,
-          policy.mode,
-          `bash is restricted to build/test verification commands (npm run build, npm test, etc.); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`,
-        ),
-      };
-    }
-    if (BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };
-    return {
-      block: true,
-      reason: blockReason(
+      return planningBlock(
         unitType,
         policy.mode,
-        `bash is restricted to read-only commands (cat/grep/git log/etc); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`,
-      ),
-    };
+        `bash is restricted to build/test verification commands (npm run build, npm test, etc.); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`,
+      );
+    }
+    if (BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };
+    return planningBlock(
+      unitType,
+      policy.mode,
+      `bash is restricted to read-only commands (cat/grep/git log/etc); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`,
+    );
   }
 
   if (PLANNING_WRITE_TOOLS.has(tool)) {
     if (!pathOrCommand) {
-      return { block: true, reason: blockReason(unitType, policy.mode, `${tool} called with empty path`) };
+      return planningBlock(unitType, policy.mode, `${tool} called with empty path`);
     }
     const absPath = isAbsolute(pathOrCommand) ? pathOrCommand : resolve(basePath, pathOrCommand);
 
@@ -925,14 +924,11 @@ export function shouldBlockPlanningUnit(
       return { block: false };
     }
 
-    return {
-      block: true,
-      reason: blockReason(
-        unitType,
-        policy.mode,
-        `cannot ${tool} "${pathOrCommand}" — writes are restricted to .gsd/${policy.mode === "docs" ? " and " + policy.allowedPathGlobs.join(", ") : ""}`,
-      ),
-    };
+    return planningBlock(
+      unitType,
+      policy.mode,
+      `cannot ${tool} "${pathOrCommand}" — writes are restricted to .gsd/${policy.mode === "docs" ? " and " + policy.allowedPathGlobs.join(", ") : ""}`,
+    );
   }
 
   // Unknown tool name — pass through. Other layers (queue, pending-gate,