@opengsd/gsd-pi 1.1.1-dev.74e8dd1 → 1.1.1-dev.a5a2de8

package/src/resources/extensions/gsd/auto-runtime-state.ts

@@ -42,6 +42,10 @@ export function isAutoPaused(): boolean {
   return autoSession.paused;
 }
 
+export function isAutoCompletionStopInProgress(): boolean {
+  return autoSession.completionStopInProgress;
+}
+
 export function markToolStart(toolCallId: string, toolName?: string): void {
   markTrackedToolStart(toolCallId, autoSession.active, toolName);
 }

package/src/resources/extensions/gsd/auto-tool-tracking.ts

@@ -94,7 +94,7 @@ export function clearInFlightTools(): void {
  * from the tool handler. When these errors occur, retrying the same unit will
  * produce the same failure, so the retry loop must be broken.
  */
-const TOOL_INVOCATION_ERROR_RE = /Validation failed for tool|Expected ',' or '\}'(?: after property value)?(?: in JSON)?|Unexpected end of JSON|Unexpected token.*in JSON|does not provide an export named|Named export .* not found|Cannot find module|ERR_MODULE_NOT_FOUND|ERR_MODULE_NOT_EXPORTED|ERR_PACKAGE_PATH_NOT_EXPORTED/i;
+const TOOL_INVOCATION_ERROR_RE = /Validation failed for tool|Input validation error|Invalid arguments for tool|MCP error -32602|No such tool available|Expected ',' or '\}'(?: after property value)?(?: in JSON)?|Unexpected end of JSON|Unexpected token.*in JSON|does not provide an export named|Named export .* not found|Cannot find module|ERR_MODULE_NOT_FOUND|ERR_MODULE_NOT_EXPORTED|ERR_PACKAGE_PATH_NOT_EXPORTED/i;
 const DETERMINISTIC_POLICY_ERROR_RE = /(?:^|\b)(?:HARD BLOCK:|Blocked: \/gsd queue is a planning tool|Direct writes to \.gsd\/STATE\.md and \.gsd\/gsd\.db are blocked|This is a mechanical gate)/i;
 
 /**

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/auto.ts

@@ -2311,10 +2311,20 @@ export function createWiredAutoOrchestrationModule(
       async reconcileBeforeDispatch() {
         const activeBasePath = getLiveDispatchBasePath();
         const result = await reconcileBeforeDispatch(activeBasePath);
-        if (result.blockers.length > 0) {
+        // Failure-path summaries written by gsd_summary_save create
+        // artifact-db-status-divergence blockers for tasks that are still
+        // pending (gsd_task_complete never ran). These tasks can still be
+        // dispatched and the drift self-heals once they complete successfully.
+        const hardBlockers = result.blockers.filter(
+          (b) =>
+            !b.includes("has SUMMARY artifact while DB status is") &&
+            !b.includes("has SUMMARY on disk while DB status is") &&
+            !b.includes("has task SUMMARY artifacts but no DB tasks"),
+        );
+        if (hardBlockers.length > 0) {
           return {
             ok: false,
-            reason: result.blockers[0],
+            reason: hardBlockers[0],
             stateSnapshot: result.stateSnapshot,
           };
         }

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" })),
@@ -832,7 +838,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
         recommendation: Type.String({ description: "Option id the executor recommends." }),
         recommendationRationale: Type.String({ description: "Why the recommendation — 1–2 sentences." }),
         continueWithDefault: Type.Boolean({
-          description: "When true, loop continues (artifact logged for later review). When false, auto-mode pauses until the user resolves via /gsd escalate resolve.",
+          description: "When true, the recommendation is recorded as the default, but auto-mode still pauses until the user resolves via /gsd escalate resolve.",
         }),
       }, { description: "ADR-011 Phase 2: optional escalation payload. Only honored when phases.mid_execution_escalation is true." })),
       verificationEvidence: Type.Optional(Type.Array(
@@ -881,7 +887,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       sliceTitle: Type.String({ description: "Title of the slice" }),
       oneLiner: Type.String({ description: "One-line summary of what the slice accomplished" }),
       narrative: Type.String({ description: "Detailed narrative of what happened across all tasks" }),
-      verification: Type.String({ description: "What was verified across all tasks" }),
+      verification: Type.Optional(Type.String({ description: "What was verified across all tasks — if omitted, summary records verification as passed without detail." })),
       uatContent: Type.String({ description: "UAT test content (markdown body)" }),
       // ── Enrichment metadata (optional — defaults to empty) ────────────
       deviations: Type.Optional(Type.String({ description: "Deviations from the slice plan, or 'None.'" })),
@@ -1095,7 +1101,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     promptGuidelines: [
       "Use gsd_validate_milestone when all slices are done and the milestone needs validation before completion.",
       "Parameters: milestoneId, verdict, remediationRound, successCriteriaChecklist, sliceDeliveryAudit, crossSliceIntegration, requirementCoverage, verificationClasses (optional), verdictRationale, remediationPlan (optional).",
-      "If verification classes were planned, verificationClasses must include canonical class rows using the exact class names Contract, Integration, Operational, and UAT when present in planning.",
+      "If verification classes were planned, verificationClasses must be a complete canonical table with one row for every applicable planned class using the exact class names Contract, Integration, Operational, and UAT. Do not submit a partial table.",
       "Planned verification text marked as none/not required/not applicable/N/A (including suffixed variants such as 'not required - backend-only') is treated as not applicable and does not require a class row.",
       "If verdict is 'needs-remediation', also provide remediationPlan and use gsd_reassess_roadmap to add remediation slices to the roadmap.",
       "On success, returns validationPath where VALIDATION.md was written.",
@@ -1108,7 +1114,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       sliceDeliveryAudit: Type.String({ description: "Markdown table auditing each slice's claimed vs delivered output" }),
       crossSliceIntegration: Type.String({ description: "Markdown describing any cross-slice boundary mismatches" }),
       requirementCoverage: Type.String({ description: "Markdown describing any unaddressed requirements" }),
-      verificationClasses: Type.Optional(Type.String({ description: "Markdown describing verification class compliance and gaps using canonical class names (Contract, Integration, Operational, UAT) for each applicable planned class" })),
+      verificationClasses: Type.Optional(Type.String({ description: "Complete markdown table describing verification class compliance and gaps; include one canonical row for every applicable planned class (Contract, Integration, Operational, UAT)" })),
       verdictRationale: Type.String({ description: "Why this verdict was chosen" }),
       remediationPlan: Type.Optional(Type.String({ description: "Remediation plan (required if verdict is needs-remediation)" })),
     }),

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

@@ -17,7 +17,7 @@ import { canonicalToolName, clearDiscussionFlowState, isDepthConfirmationAnswer,
 import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
-import { clearToolInvocationError, getAutoRuntimeSnapshot, isAutoActive, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError } from "../auto-runtime-state.js";
+import { clearToolInvocationError, getAutoRuntimeSnapshot, isAutoActive, isAutoCompletionStopInProgress, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError } from "../auto-runtime-state.js";
 
 import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { maybePauseAutoForApprovalGate, resetPendingGatePauseGuard } from "./pending-gate-pause.js";
@@ -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 {
@@ -535,8 +548,9 @@ export function registerHooks(
 
   pi.on("session_start", async (_event, ctx) => {
     const basePath = contextBasePath(ctx);
+    const preserveCloseoutSurface = isAutoCompletionStopInProgress();
     initSessionNotifications(ctx);
-    if (!isAutoActive()) {
+    if (!isAutoActive() && !preserveCloseoutSurface) {
       const { initHealthWidget } = await import("../health-widget.js");
       initHealthWidget(ctx);
     }
@@ -556,15 +570,18 @@ export function registerHooks(
       const prefs = loadEffectiveGSDPreferences(basePath);
       process.env.GSD_SHOW_TOKEN_COST = prefs?.preferences.show_token_cost ? "1" : "";
     } catch { /* non-fatal */ }
-    await installWelcomeHeader(ctx);
+    if (!preserveCloseoutSurface) {
+      await installWelcomeHeader(ctx);
+    }
     await loadToolApiKeysForSession();
-    if (isAutoActive()) {
+    if (isAutoActive() || preserveCloseoutSurface) {
       ctx.ui.setWidget("gsd-health", undefined);
     }
   });
 
   pi.on("session_switch", async (_event, ctx) => {
     const basePath = contextBasePath(ctx);
+    const preserveCloseoutSurface = isAutoCompletionStopInProgress();
     initSessionNotifications(ctx);
     resetWriteGateState(basePath);
     resetToolCallLoopGuard();
@@ -576,7 +593,7 @@ export function registerHooks(
     await applyCompactionThresholdOverride(ctx);
     await prepareWorkflowMcpForHookContext(ctx, basePath);
     await loadToolApiKeysForSession();
-    if (!isAutoActive()) {
+    if (!isAutoActive() && !preserveCloseoutSurface) {
       ctx.ui.setWidget("gsd-progress", undefined);
       ctx.ui.setWidget("gsd-outcome", undefined);
       const { initHealthWidget } = await import("../health-widget.js");
@@ -913,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(
@@ -931,7 +948,7 @@ export function registerHooks(
               "Depth confirmation is waiting for your answer — pausing auto-mode.",
             );
           }
-          return gateGuard;
+          return withDepthGateDisplayReason(gateGuard);
         }
       }
     }
@@ -1036,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 ──