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

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

@@ -2,14 +2,14 @@
 // File Purpose: Registers workspace-aware dynamic filesystem and shell tools.
 import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent";
 
 import { DEFAULT_BASH_TIMEOUT_SECS } from "../constants.js";
-import { setLogBasePath, logWarning } from "../workflow-logger.js";
-import { resolveGsdPathContract } from "../paths.js";
+import { logWarning } from "../workflow-logger.js";
+import { openWorkflowDatabase } from "../db-workspace.js";
 import { getAutoWorktreePath } from "../auto-worktree.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 
@@ -64,45 +64,18 @@ export function resolveWorkflowToolBasePath(
   return cwd;
 }
 
-/**
- * Resolve the correct DB path for the current working directory.
- * If `basePath` is inside a `.gsd/worktrees/<MID>/` directory, returns
- * the project root's `.gsd/gsd.db` (shared WAL — R012). Otherwise
- * returns `<basePath>/.gsd/gsd.db`.
- */
-export function resolveProjectRootDbPath(basePath: string): string {
-  return resolveGsdPathContract(basePath).projectDb;
-}
+export { resolveProjectRootDbPath } from "../db-workspace.js";
 
 export async function ensureDbOpen(basePath: string = safeWorkspaceCwd()): Promise<boolean> {
-  try {
-    const db = await import("../gsd-db.js");
-    const contract = resolveGsdPathContract(basePath);
-    const dbPath = contract.projectDb;
-    const gsdDir = contract.projectGsd;
-    const projectRoot = dirname(dirname(dbPath));
-
-    // Open existing DB file (may be at project root for worktrees)
-    if (existsSync(dbPath)) {
-      const opened = db.openDatabase(dbPath);
-      if (opened) setLogBasePath(projectRoot);
-      return opened;
-    }
-
-    // No DB file — create an empty authoritative DB. Markdown migration is
-    // explicit-only; runtime startup must not import projections into state.
-    if (existsSync(gsdDir)) {
-      const opened = db.openDatabase(dbPath);
-      if (opened) setLogBasePath(projectRoot);
-      return opened;
-    }
+  const result = openWorkflowDatabase(basePath);
+  if (result.ok) return true;
 
+  if (result.reason === "missing-gsd-dir") {
     logWarning("bootstrap", "ensureDbOpen failed — no .gsd directory found");
-    return false;
-  } catch (err) {
-    logWarning("bootstrap", `ensureDbOpen failed: ${(err as Error).message ?? String(err)}`);
-    return false;
+  } else {
+    logWarning("bootstrap", `ensureDbOpen failed: ${result.error?.message ?? "open failed"}`);
   }
+  return false;
 }
 
 export function registerDynamicTools(pi: ExtensionAPI): void {

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

@@ -5,6 +5,7 @@
 import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { ensureDbOpen, resolveCtxCwd } from "./dynamic-tools.js";
+import { checkpointWorkflowDatabase } from "../db-workspace.js";
 
 
 export function registerQueryTools(pi: ExtensionAPI): void {
@@ -57,8 +58,7 @@ export function registerQueryTools(pi: ExtensionAPI): void {
           details: { operation: "checkpoint_db", error: "db_unavailable" },
         };
       }
-      const { checkpointDatabase } = await import("../gsd-db.js");
-      checkpointDatabase();
+      checkpointWorkflowDatabase();
       return {
         content: [{ type: "text", text: "WAL checkpoint complete. gsd.db is now up to date and safe to stage with git add." }],
         details: { operation: "checkpoint_db", status: "ok" },

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, isMilestoneDepthVerified, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, 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,24 @@ 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";
 
 let approvalQuestionAbortInFlight = false;
 
@@ -210,16 +220,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 +292,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 +384,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 +415,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) {
@@ -697,6 +730,7 @@ function initSessionNotifications(ctx: ExtensionContext): void {
   initNotificationStore(resolveNotificationStoreBasePath(contextBasePath(ctx)));
   installNotifyInterceptor(ctx);
   initNotificationWidget(ctx);
+  notifyPreferenceDiagnostics(ctx, contextBasePath(ctx), { surface: "session-start" });
 }
 
 async function prepareWorkflowMcpForHookContext(
@@ -994,6 +1028,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 +1374,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);
   });
@@ -1458,66 +1460,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 +1505,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,6 +5,7 @@ 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";
@@ -123,9 +124,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 {
@@ -462,6 +461,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,