@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.955e4da0

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

@@ -13,7 +13,7 @@ import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-exten
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
 
 import { buildMilestoneFileName, clearPathCache, milestonesDir, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { canonicalToolName, clearDiscussionFlowState, isDepthConfirmationAnswer, isMilestoneDepthVerified, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeWrite, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { applyAskUserQuestionsGateResult, canonicalToolName, clearDiscussionFlowState, formatPendingAskUserQuestionsGateMessage, isApprovalGateVerifiedInSnapshot, isMilestoneDepthVerified, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, loadWriteGateSnapshot, markApprovalGateVerified, markDepthVerified, refreshWriteGateStateFromDisk, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeWrite, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
 import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
@@ -25,10 +25,13 @@ import {
   isAutoActive,
   isAutoCompletionStopInProgress,
   isAutoPaused,
+  isInteractiveElicitationInFlight,
   markToolEnd,
   markToolStart,
+  recordAutoToolSurfaceSnapshot,
   recordToolInvocationError,
 } from "../auto-runtime-state.js";
+import { applyProviderPayloadPolicy } from "../provider-payload-policy.js";
 
 import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { maybePauseAutoForApprovalGate, resetPendingGatePauseGuard } from "./pending-gate-pause.js";
@@ -40,17 +43,25 @@ import { logWarning as safetyLogWarning } from "../workflow-logger.js";
 import { installNotifyInterceptor } from "./notify-interceptor.js";
 import { initNotificationStore } from "../notification-store.js";
 import { initNotificationWidget } from "../notification-widget.js";
+import { notifyPreferenceDiagnostics } from "../preferences-diagnostics.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { extractSubagentAgentClasses } from "./subagent-input.js";
-import { approvalGateIdForUnit, isExplicitApprovalResponse, shouldPauseForUserApprovalQuestion } from "../user-input-boundary.js";
+import {
+  approvalGateIdForUnit,
+  isExplicitApprovalResponse,
+  messageHasPendingAskUserQuestionsTool,
+  shouldPauseForUserApprovalQuestion,
+} from "../user-input-boundary.js";
 import { resolveSkillManifest } from "../skill-manifest.js";
 import { applyUnitSkillVisibility, unitHasSkillManifest } from "../skill-scope.js";
 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 { AUTO_UNIT_SCOPED_TOOLS, RUN_UAT_BROWSER_TOOL_NAMES, canonicalWorkflowToolName, isWorkflowAliasTool } from "../auto-unit-tool-scope.js";
 import { filterToolsForProvider } from "../model-router.js";
+import { mcpToolMatchesBaseName } from "../mcp-tool-name.js";
 import { RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES } from "../tool-presentation-plan.js";
-import { injectSourceContextBlockIntoPayload, supportsSourceObservationsForUnit } from "../source-observations.js";
+import { supportsSourceObservationsForUnit } from "../source-observations.js";
+import { clearPendingAutoStart } from "../pending-auto-start.js";
 
 let approvalQuestionAbortInFlight = false;
 
@@ -210,16 +221,22 @@ function resolveScopedToolNames(
 
   for (const requested of requestedToolNames) {
     const scopedMatches: string[] = [];
+    const aliasFallbacks: string[] = [];
 
     for (const activeName of activeToolNames) {
-      if (!activeName.startsWith("mcp__")) continue;
-      const toolSeparator = activeName.indexOf("__", "mcp__".length);
-      if (toolSeparator < 0) continue;
-      if (activeName.slice(toolSeparator + 2) === requested) {
+      if (mcpToolMatchesBaseName(activeName, requested)) {
         scopedMatches.push(activeName);
+      } else if (isWorkflowAliasTool(activeName) && canonicalWorkflowToolName(activeName) === requested) {
+        aliasFallbacks.push(activeName);
       }
     }
 
+    // Only use alias as fallback when canonical is absent — not directly and not via MCP scoping.
+    // Prevents the alias from resurfacing alongside the canonical when both are in the active set.
+    if (!exact.has(requested) && scopedMatches.length === 0) {
+      scopedMatches.push(...aliasFallbacks);
+    }
+
     if (requested.startsWith("browser_") && scopedMatches.length > 0) {
       for (const match of scopedMatches) resolved.add(match);
       continue;
@@ -276,7 +293,7 @@ export function buildRunUatGsdToolSet(
   const resolved = [...new Set(scoped)];
 
   const unresolved = RUN_UAT_WORKFLOW_TOOL_NAMES.filter(
-    (tool) => !resolved.some((name) => name === tool || (name.startsWith("mcp__") && name.endsWith(`__${tool}`))),
+    (tool) => !resolved.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)),
   );
   if (unresolved.length > 0) {
     safetyLogWarning(
@@ -368,11 +385,21 @@ function applyMinimalGsdToolSurface(pi: ExtensionAPI): void {
   if (isFullGsdToolSurfaceRequested()) return;
   const dash = getAutoRuntimeSnapshot();
   if (dash.active && dash.currentUnit) {
-    pi.setActiveTools(buildMinimalAutoGsdToolSet(
-      pi.getActiveTools(),
+    const currentToolNames = pi.getActiveTools();
+    const registeredToolNames = resolveRegisteredToolNames(pi, currentToolNames);
+    const scopedToolNames = buildMinimalAutoGsdToolSet(
+      currentToolNames,
       dash.currentUnit.type,
-      resolveRegisteredToolNames(pi, pi.getActiveTools()),
-    ));
+      registeredToolNames,
+    );
+    recordAutoToolSurfaceSnapshot({
+      source: "runtime-scope",
+      unitType: dash.currentUnit.type,
+      modelFacingToolNames: scopedToolNames,
+      registeredToolNames,
+      scopedToolNames,
+    });
+    pi.setActiveTools(scopedToolNames);
     return;
   }
   if (!isGeneralGsdToolScopingRequested()) return;
@@ -389,6 +416,13 @@ export function scopeGsdWorkflowToolsForDispatch(
   const scoped = unitType
     ? buildMinimalAutoGsdToolSet(current, unitType, registeredToolNames)
     : buildMinimalGsdWorkflowToolSet(current, registeredToolNames);
+  recordAutoToolSurfaceSnapshot({
+    source: "dispatch-scope",
+    unitType,
+    modelFacingToolNames: scoped,
+    registeredToolNames,
+    scopedToolNames: scoped,
+  });
   const toolsChanged = !(scoped.length === current.length && scoped.every((name, index) => name === current[index]));
   const canScopeSkills = unitHasSkillManifest(unitType) && pi.getVisibleSkills && pi.setVisibleSkills;
   if (!toolsChanged && !canScopeSkills) {
@@ -539,8 +573,14 @@ function isShellExecutionTool(canonicalName: string): boolean {
 
 function activateDeferredApprovalGate(basePath: string): void {
   if (deferredApprovalGate?.basePath !== basePath) return;
-  setPendingGate(deferredApprovalGate.gateId, basePath);
+  const gateId = deferredApprovalGate.gateId;
   deferredApprovalGate = null;
+  refreshWriteGateStateFromDisk(basePath);
+  const snapshot = loadWriteGateSnapshot(basePath);
+  const milestoneId = extractDepthVerificationMilestoneId(gateId);
+  if (isApprovalGateVerifiedInSnapshot(snapshot, gateId)) return;
+  if (milestoneId && isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId)) return;
+  setPendingGate(gateId, basePath);
 }
 
 function extractGateQuestionId(input: unknown): string | undefined {
@@ -697,6 +737,7 @@ function initSessionNotifications(ctx: ExtensionContext): void {
   initNotificationStore(resolveNotificationStoreBasePath(contextBasePath(ctx)));
   installNotifyInterceptor(ctx);
   initNotificationWidget(ctx);
+  notifyPreferenceDiagnostics(ctx, contextBasePath(ctx), { surface: "session-start" });
 }
 
 async function prepareWorkflowMcpForHookContext(
@@ -768,7 +809,7 @@ export function registerHooks(
     }
   });
 
-  pi.on("session_switch", async (_event, ctx) => {
+  pi.on("session_switch", async (event, ctx) => {
     const basePath = contextBasePath(ctx);
     const preserveCloseoutSurface = isAutoCompletionStopInProgress();
     initSessionNotifications(ctx);
@@ -777,6 +818,13 @@ export function registerHooks(
     clearDeferredApprovalGate();
     await resetAskUserQuestionsTurnCache();
     clearDiscussionFlowState(basePath);
+    // /clear or /new destroys the conversation holding a discuss interview, so
+    // its pending discuss→auto handoff can never be answered — clear it. Resume
+    // restores the interview transcript, so the entry survives. Auto-mode's own
+    // newSession() calls are safe: the handoff consumes the entry on agent_end.
+    if (event.reason === "new") {
+      clearPendingAutoStart(basePath);
+    }
     await syncServiceTierStatus(ctx);
     await applyDisabledModelProviderPolicy(ctx);
     await applyCompactionThresholdOverride(ctx);
@@ -994,6 +1042,18 @@ export function registerHooks(
 
   pi.on("message_update", async (event, ctx: ExtensionContext) => {
     if (approvalQuestionAbortInFlight) return;
+    // If the model asked via ask_user_questions, that in-flight elicitation IS
+    // the human boundary. Arming the pause/gate here (and emitting the "waiting
+    // for your approval - pausing" notice) would tear it down and trigger the
+    // foreground self-cancel/re-ask loop. The marker is set only by the
+    // claude-code-cli SDK elicitation handler and is ungated, so it is true in
+    // foreground; under the native-TUI provider it is always false and this path
+    // runs unchanged (#cc-elicitation-self-cancel).
+    if (isInteractiveElicitationInFlight()) return;
+    // Prose with "?" can stream before the MCP tool/elicitation starts. When the
+    // structured ask_user_questions call is already in the partial message, the
+    // tool IS the human boundary — do not arm the text-based approval pause.
+    if (messageHasPendingAskUserQuestionsTool(event.message)) return;
 
     const dash = getAutoRuntimeSnapshot();
     if (dash.active) return;
@@ -1328,81 +1388,37 @@ export function registerHooks(
 
     const details = event.details as any;
 
-    // ── Discussion gate enforcement: handle gate question responses ──
-    // If the result is cancelled or has no response, the pending gate stays active
-    // so the model is blocked from non-read-only tools until it re-asks.
-    // If the user responded at all (even "needs adjustment"), clear the pending gate
-    // because the user engaged — the prompt handles the re-ask-after-adjustment flow.
     const questions: any[] = (event.input as any)?.questions ?? [];
-    const currentPendingGate = getPendingGate(basePath);
-    if (currentPendingGate) {
-      if (details?.cancelled || !details?.response) {
-        // Gate stays pending. Direct the agent to the most reliable recovery
-        // path — re-calling ask_user_questions with the same gate id — without
-        // misrepresenting the plain-text path. The plain-text path also works
-        // (isExplicitApprovalResponse on the next before_agent_start clears
-        // the gate when the user replies with an approval keyword), but the
-        // structured re-ask is more deterministic and gives the user a clear UI.
-        resetToolCallLoopGuard();
-        const interrupted = details?.interrupted === true;
-        if (ctx) {
-          await maybePauseAutoForApprovalGate(
-            ctx,
-            pi,
-            true,
-            interrupted
-              ? "Depth confirmation was interrupted — pausing auto-mode until you respond."
-              : "Depth confirmation is waiting for your answer — pausing auto-mode.",
-          );
-        }
-        return {
-          content: [{
-            type: "text" as const,
-            text: [
-              `Waiting for depth confirmation on gate "${currentPendingGate}".`,
-              interrupted
-                ? "The confirmation question was interrupted before a response was recorded."
-                : "No user response was received for the confirmation question.",
-              "Do not infer approval from earlier or prior messages.",
-              "Do not proceed, write files, save artifacts, or call other tools.",
-              `Re-call ask_user_questions with the same gate question id ("${currentPendingGate}") and wait for the user's response.`,
-            ].join(" "),
-          }],
-        };
-      } else {
-        const pendingQuestion = questions.find((question) => question?.id === currentPendingGate);
-        if (pendingQuestion) {
-          const answer = details.response?.answers?.[currentPendingGate];
-          if (isDepthConfirmationAnswer(answer?.selected, pendingQuestion.options)) {
-            markApprovalGateVerified(currentPendingGate, basePath);
-            const milestoneIdFromGate = extractDepthVerificationMilestoneId(currentPendingGate);
-            if (milestoneIdFromGate) markDepthVerified(milestoneIdFromGate, basePath);
-            clearPendingGate(basePath);
-            clearDeferredApprovalGate(basePath);
-          }
-        }
+    const gateResult = applyAskUserQuestionsGateResult({
+      basePath,
+      questions,
+      details,
+      fallbackMilestoneId: milestoneId,
+    });
+    if (gateResult.status === "waiting") {
+      resetToolCallLoopGuard();
+      if (ctx) {
+        await maybePauseAutoForApprovalGate(
+          ctx,
+          pi,
+          true,
+          gateResult.interrupted
+            ? "Depth confirmation was interrupted — pausing auto-mode until you respond."
+            : "Depth confirmation is waiting for your answer — pausing auto-mode.",
+        );
       }
+      return {
+        content: [{
+          type: "text" as const,
+          text: formatPendingAskUserQuestionsGateMessage(gateResult.pendingGateId, gateResult.interrupted),
+        }],
+      };
     }
-
-    if (details?.cancelled || !details?.response) return;
-
-    for (const question of questions) {
-      if (typeof question.id === "string" && question.id.includes("depth_verification")) {
-        // Only unlock the gate if the user selected the first option (confirmation).
-        // Cross-references against the question's defined options to reject free-form "Other" text.
-        const answer = details.response?.answers?.[question.id];
-        const inferredMilestoneId = extractDepthVerificationMilestoneId(question.id) ?? milestoneId;
-        if (isDepthConfirmationAnswer(answer?.selected, question.options)) {
-          if (currentPendingGate && question.id !== currentPendingGate) break;
-          markApprovalGateVerified(question.id, basePath);
-          markDepthVerified(inferredMilestoneId, basePath);
-          clearPendingGate(basePath);
-          clearDeferredApprovalGate(basePath);
-        }
-        break;
-      }
+    if (gateResult.status === "verified") {
+      clearDeferredApprovalGate(basePath);
     }
 
+    if (details?.cancelled || !details?.response) return;
     if (!milestoneId) return;
     await saveDiscussionQuestionRound(basePath, milestoneId, questions, details);
   });
@@ -1417,6 +1433,21 @@ export function registerHooks(
         clearDeferredApprovalGate(basePath);
       }
     }
+
+    // Safety harness: record evidence here, not only in tool_call. External
+    // engines (claude-code-cli) pre-execute tools, so the agent loop skips
+    // beforeToolCall/tool_call for them — tool_execution_start is the only
+    // event that fires for every tool call. recordToolCall dedupes by
+    // toolCallId, so native tools (which hit both events) record once.
+    safetyRecordToolCall(event.toolCallId, event.toolName, (event.args ?? {}) as Record<string, unknown>);
+    const execDash = getAutoRuntimeSnapshot();
+    if (execDash.basePath && execDash.currentUnit?.type === "execute-task") {
+      const { milestone: xMid, slice: xSid, task: xTid } = parseUnitId(execDash.currentUnit.id);
+      if (xMid && xSid && xTid) {
+        saveEvidenceToDisk(execDash.basePath, xMid, xSid, xTid);
+      }
+    }
+
     if (!isAutoActive()) return;
     markToolStart(event.toolCallId, event.toolName);
   });
@@ -1458,66 +1489,10 @@ export function registerHooks(
     const payload = event.payload as Record<string, unknown> | null;
     if (!payload || typeof payload !== "object") return;
 
-    // ── Context Management ──────────────────────────────────────────────
-    // Load preferences once for both masking and truncation.
-    try {
-      const { loadEffectiveGSDPreferences } = await import("../preferences.js");
-      const {
-        createObservationMask,
-        createResponsesInputObservationMask,
-        truncateContextResultMessages,
-        truncateResponsesInputResultItems,
-      } = await import("../context-masker.js");
-      const prefs = loadEffectiveGSDPreferences();
-      const cmConfig = prefs?.preferences.context_management;
-
-      // Observation masking: replace old tool results with placeholders.
-      // Only active during auto-mode when context_management.observation_masking is enabled.
-      if (isAutoActive() && cmConfig?.observation_masking !== false) {
-        const keepTurns = cmConfig?.observation_mask_turns ?? 8;
-        const messages = payload.messages;
-        if (Array.isArray(messages)) {
-          payload.messages = createObservationMask(keepTurns)(messages);
-        }
-        const input = payload.input;
-        if (Array.isArray(input)) {
-          payload.input = createResponsesInputObservationMask(keepTurns)(input);
-        }
-      }
-
-      // Tool result truncation: cap individual tool result content length.
-      // Applies in ALL modes (auto + interactive) to prevent context bloat.
-      // In pi-ai format, toolResult messages have role: "toolResult" and content: TextContent[].
-      // Creates new objects to avoid mutating shared conversation state.
-      const maxChars = cmConfig?.tool_result_max_chars ?? 800;
-      const msgs = payload.messages;
-      if (Array.isArray(msgs)) {
-        payload.messages = truncateContextResultMessages(msgs as any, maxChars);
-      }
-      const input = payload.input;
-      if (Array.isArray(input)) {
-        payload.input = truncateResponsesInputResultItems(input as any, maxChars);
-      }
-    } catch { /* non-fatal */ }
-
-    try {
-      if (isAutoActive()) {
-        const sourceContextBlock = getSourceObservationStore().renderActiveBlock();
-        if (sourceContextBlock) {
-          const nextPayload = injectSourceContextBlockIntoPayload(payload, sourceContextBlock);
-          Object.assign(payload, nextPayload);
-        }
-      }
-    } catch { /* non-fatal */ }
-
-    // ── Service Tier ────────────────────────────────────────────────────
-    const modelId = event.model?.id;
-    if (!modelId) return payload;
-    const { getEffectiveServiceTier, supportsServiceTier } = await import("../service-tier.js");
-    const tier = getEffectiveServiceTier();
-    if (!tier || !supportsServiceTier(modelId)) return payload;
-    payload.service_tier = tier;
-    return payload;
+    return applyProviderPayloadPolicy({
+      payload,
+      modelId: event.model?.id,
+    });
   });
 
   // Capability-aware model routing hook (ADR-004)
@@ -1559,25 +1534,44 @@ export function registerHooks(
       event.selectedModelProvider,
     ).compatible.filter((name) => !(dropAliases && isWorkflowAliasTool(name)));
     const guidedUnit = getGuidedUnitContext();
+    const requestRegisteredToolNames = guidedUnit?.unitType === "run-uat"
+      ? compatibleRegisteredToolNames
+      : registeredToolNames;
     const requestScoped = buildRequestScopedGsdToolSet(
       guidedUnit?.unitType === "run-uat" ? aliasFilteredCompatible : providerCompatible,
       event.requestCustomMessages,
-      guidedUnit?.unitType === "run-uat" ? compatibleRegisteredToolNames : registeredToolNames,
+      requestRegisteredToolNames,
       guidedUnit?.unitType,
     );
     if (requestScoped) {
+      recordAutoToolSurfaceSnapshot({
+        source: "provider-adjustment",
+        unitType: guidedUnit?.unitType,
+        modelFacingToolNames: requestScoped,
+        registeredToolNames: requestRegisteredToolNames,
+        scopedToolNames: requestScoped,
+      });
       return { toolNames: requestScoped };
     }
     const dash = getAutoRuntimeSnapshot();
     if (dash.active && dash.currentUnit) {
+      const registeredForUnit = dash.currentUnit.type === "run-uat"
+        ? compatibleRegisteredToolNames
+        : resolveRegisteredToolNames(pi, event.activeToolNames);
+      const scopedToolNames = buildMinimalAutoGsdToolSet(
+        dash.currentUnit.type === "run-uat" ? aliasFilteredCompatible : providerCompatible,
+        dash.currentUnit.type,
+        registeredForUnit,
+      );
+      recordAutoToolSurfaceSnapshot({
+        source: "provider-adjustment",
+        unitType: dash.currentUnit.type,
+        modelFacingToolNames: scopedToolNames,
+        registeredToolNames: registeredForUnit,
+        scopedToolNames,
+      });
       return {
-        toolNames: buildMinimalAutoGsdToolSet(
-          dash.currentUnit.type === "run-uat" ? aliasFilteredCompatible : providerCompatible,
-          dash.currentUnit.type,
-          dash.currentUnit.type === "run-uat"
-            ? compatibleRegisteredToolNames
-            : resolveRegisteredToolNames(pi, event.activeToolNames),
-        ),
+        toolNames: scopedToolNames,
       };
     }
     if (isGeneralGsdToolScopingRequested()) {

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

@@ -5,10 +5,12 @@ import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { minimatch } from "minimatch";
 
 import { GSD_PHASE_SCOPE_DISPLAY_REASON, shouldBlockAutoUnitToolCall } from "../auto-unit-tool-scope.js";
+import { stripMcpToolPrefix } from "../mcp-tool-name.js";
 import { getIsolationMode } from "../preferences.js";
 import { compileSubagentPermissionContract, type ToolsPolicy } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
+import { worktreesDirs } from "../worktree-placement.js";
 
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
@@ -123,9 +125,7 @@ const GATE_SAFE_TOOLS = new Set([
 ]);
 
 export function canonicalToolName(toolName: string): string {
-  if (!toolName.startsWith("mcp__")) return toolName;
-  const toolSeparator = toolName.indexOf("__", "mcp__".length);
-  return toolSeparator >= 0 ? toolName.slice(toolSeparator + 2) : toolName;
+  return stripMcpToolPrefix(toolName);
 }
 
 export interface WriteGateSnapshot {
@@ -245,6 +245,23 @@ export function loadWriteGateSnapshot(basePath: string): WriteGateSnapshot {
   }
 }
 
+/**
+ * Merge the persisted write-gate snapshot into the in-process Map entry.
+ * The workflow MCP server runs in a child process and records depth
+ * verification there; without this refresh the extension host keeps stale
+ * pending-gate memory and `activateDeferredApprovalGate` can re-arm a gate
+ * that the subprocess already cleared on disk.
+ */
+export function refreshWriteGateStateFromDisk(basePath: string): void {
+  if (!shouldPersistWriteGateSnapshot()) return;
+  const snapshot = loadWriteGateSnapshot(basePath);
+  const state = getWriteGateState(basePath);
+  state.pendingGateId = snapshot.pendingGateId;
+  state.activeQueuePhase = snapshot.activeQueuePhase;
+  state.verifiedDepthMilestones = new Set(snapshot.verifiedDepthMilestones);
+  state.verifiedApprovalGates = new Set(snapshot.verifiedApprovalGates ?? []);
+}
+
 export function isDepthVerified(basePath: string = process.cwd()): boolean {
   return getWriteGateState(basePath).verifiedDepthMilestones.size > 0;
 }
@@ -257,6 +274,7 @@ export function isMilestoneDepthVerified(
   basePath: string = process.cwd(),
 ): boolean {
   if (!milestoneId) return false;
+  refreshWriteGateStateFromDisk(basePath);
   return getWriteGateState(basePath).verifiedDepthMilestones.has(milestoneId);
 }
 
@@ -358,6 +376,7 @@ export function clearPendingGate(basePath: string): void {
  * Get the currently pending gate, if any.
  */
 export function getPendingGate(basePath: string = process.cwd()): string | null {
+  refreshWriteGateStateFromDisk(basePath);
   return getWriteGateState(basePath).pendingGateId;
 }
 
@@ -462,6 +481,111 @@ export function isDepthConfirmationAnswer(
   return false;
 }
 
+export interface AskUserQuestionsGateQuestion {
+  id?: unknown;
+  options?: Array<{ label?: string }>;
+}
+
+export interface AskUserQuestionsGateDetails {
+  cancelled?: boolean;
+  interrupted?: boolean;
+  response?: {
+    answers?: Record<string, { selected?: unknown } | undefined>;
+  } | null;
+}
+
+export type AskUserQuestionsGateResult =
+  | { status: "not-gate" }
+  | { status: "waiting"; pendingGateId: string; interrupted: boolean }
+  | { status: "verified"; gateId: string; milestoneId: string | null }
+  | { status: "answered"; gateId: string };
+
+function findGateQuestion(
+  questions: AskUserQuestionsGateQuestion[],
+  gateId: string,
+): AskUserQuestionsGateQuestion | undefined {
+  return questions.find((question) => question?.id === gateId);
+}
+
+function readSelectedGateAnswer(
+  details: AskUserQuestionsGateDetails,
+  questionId: string,
+): unknown {
+  return details.response?.answers?.[questionId]?.selected;
+}
+
+function verifyAnsweredGate(
+  basePath: string,
+  question: AskUserQuestionsGateQuestion,
+  fallbackMilestoneId?: string | null,
+): AskUserQuestionsGateResult {
+  const gateId = typeof question.id === "string" ? question.id : "";
+  const milestoneId = extractDepthVerificationMilestoneId(gateId) ?? fallbackMilestoneId ?? null;
+  markApprovalGateVerified(gateId, basePath);
+  markDepthVerified(milestoneId, basePath);
+  clearPendingGate(basePath);
+  return { status: "verified", gateId, milestoneId };
+}
+
+export function applyAskUserQuestionsGateResult(options: {
+  basePath: string;
+  questions: AskUserQuestionsGateQuestion[];
+  details: AskUserQuestionsGateDetails;
+  fallbackMilestoneId?: string | null;
+}): AskUserQuestionsGateResult {
+  const { basePath, questions, details, fallbackMilestoneId } = options;
+  const currentPendingGate = getPendingGate(basePath);
+  if (currentPendingGate) {
+    if (details.cancelled || !details.response) {
+      return {
+        status: "waiting",
+        pendingGateId: currentPendingGate,
+        interrupted: details.interrupted === true,
+      };
+    }
+
+    const pendingQuestion = findGateQuestion(questions, currentPendingGate);
+    if (pendingQuestion) {
+      const selected = readSelectedGateAnswer(details, currentPendingGate);
+      if (isDepthConfirmationAnswer(selected, pendingQuestion.options)) {
+        return verifyAnsweredGate(basePath, pendingQuestion, fallbackMilestoneId);
+      }
+      return { status: "answered", gateId: currentPendingGate };
+    }
+  }
+
+  if (details.cancelled || !details.response) return { status: "not-gate" };
+
+  for (const question of questions) {
+    if (typeof question.id !== "string" || !isGateQuestionId(question.id)) continue;
+    const selected = readSelectedGateAnswer(details, question.id);
+    if (!isDepthConfirmationAnswer(selected, question.options)) {
+      return { status: "answered", gateId: question.id };
+    }
+    if (currentPendingGate && question.id !== currentPendingGate) {
+      return { status: "answered", gateId: currentPendingGate };
+    }
+    return verifyAnsweredGate(basePath, question, fallbackMilestoneId);
+  }
+
+  return { status: "not-gate" };
+}
+
+export function formatPendingAskUserQuestionsGateMessage(
+  pendingGateId: string,
+  interrupted: boolean,
+): string {
+  return [
+    `Waiting for depth confirmation on gate "${pendingGateId}".`,
+    interrupted
+      ? "The confirmation question was interrupted before a response was recorded."
+      : "No user response was received for the confirmation question.",
+    "Do not infer approval from earlier or prior messages.",
+    "Do not proceed, write files, save artifacts, or call other tools.",
+    `Re-call ask_user_questions with the same gate question id ("${pendingGateId}") and wait for the user's response.`,
+  ].join(" ");
+}
+
 export function shouldBlockContextWrite(
   toolName: string,
   inputPath: string,
@@ -1034,10 +1158,12 @@ export function shouldBlockWorktreeWrite(
   const realTarget = realpathOrResolve(absTarget);
   const realRoot = realpathOrResolve(projectRoot);
   const realGsd = realpathOrResolve(join(projectRoot, ".gsd"));
-  const realWorktreesDir = realpathOrResolve(join(projectRoot, ".gsd", "worktrees"));
 
-  // Allow writes inside the legitimate worktrees subtree.
-  if (isPathContained(realTarget, realWorktreesDir)) return { block: false };
+  // Allow writes inside a legitimate worktrees subtree (canonical
+  // .gsd-worktrees/ or legacy .gsd/worktrees/).
+  for (const container of worktreesDirs(projectRoot)) {
+    if (isPathContained(realTarget, realpathOrResolve(container))) return { block: false };
+  }
 
   // Allow writes to .gsd/ planning artifacts, but reject siblings whose name
   // starts with "worktrees" (the worktrees-extra prefix trick — case 4).

package/src/resources/extensions/gsd/captures.ts

@@ -9,9 +9,10 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
+import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { gsdRoot } from "./paths.js";
+import { findWorktreeSegment } from "./worktree-root.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -60,20 +61,10 @@ const VALID_CLASSIFICATIONS: readonly string[] = [
  */
 export function resolveCapturesPath(basePath: string): string {
   const resolved = resolve(basePath);
-  // Direct layout: /.gsd/worktrees/
-  const worktreeMarker = `${sep}.gsd${sep}worktrees${sep}`;
-  let idx = resolved.indexOf(worktreeMarker);
-  if (idx === -1) {
-    // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
-    const symlinkRe = new RegExp(
-      `\\${sep}\\.gsd\\${sep}projects\\${sep}[a-f0-9]+\\${sep}worktrees\\${sep}`,
-    );
-    const match = resolved.match(symlinkRe);
-    if (match && match.index !== undefined) idx = match.index;
-  }
-  if (idx !== -1) {
+  const segment = findWorktreeSegment(resolved.replaceAll("\\", "/"));
+  if (segment) {
     // basePath is inside a worktree — resolve to project root
-    const projectRoot = resolved.slice(0, idx);
+    const projectRoot = resolved.slice(0, segment.gsdIdx);
     return join(projectRoot, ".gsd", CAPTURES_FILENAME);
   }
   return join(gsdRoot(basePath), CAPTURES_FILENAME);