@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.4813ead6

package/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -10,6 +10,7 @@ import { logError } from "../workflow-logger.js";
 import { getErrorMessage } from "../error-utils.js";
 import { incrementLegacyTelemetry } from "../legacy-telemetry.js";
 import { prepareSaveGateResultArguments } from "../tools/save-gate-result-args.js";
+import { aliasesForWorkflowTool } from "../workflow-tool-surface.js";
 async function loadWorkflowExecutors() {
     return importWorkflowExecutorsModule();
 }
@@ -41,6 +42,13 @@ function registerAlias(pi, toolDef, aliasName, canonicalName) {
         execute,
     });
 }
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- toolDef shape matches ToolDefinition but varies by schema
+function registerWorkflowTool(pi, toolDef) {
+    pi.registerTool(toolDef);
+    for (const alias of aliasesForWorkflowTool(toolDef.name)) {
+        registerAlias(pi, toolDef, alias, toolDef.name);
+    }
+}
 function requirementRootWriteGuard(operation, basePath) {
     const guard = shouldBlockRootArtifactSaveInSnapshot(loadWriteGateSnapshot(basePath), "REQUIREMENTS");
     if (!guard.block)
@@ -155,8 +163,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
     };
-    pi.registerTool(decisionSaveTool);
-    registerAlias(pi, decisionSaveTool, "gsd_save_decision", "gsd_decision_save");
+    registerWorkflowTool(pi, decisionSaveTool);
     // ─── gsd_requirement_update (formerly gsd_update_requirement) ───────────
     const requirementUpdateExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const basePath = resolveCtxCwd(_ctx);
@@ -241,8 +248,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
     };
-    pi.registerTool(requirementUpdateTool);
-    registerAlias(pi, requirementUpdateTool, "gsd_update_requirement", "gsd_requirement_update");
+    registerWorkflowTool(pi, requirementUpdateTool);
     // ─── gsd_requirement_save ─────────────────────────────────────────────
     const requirementSaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const basePath = resolveCtxCwd(_ctx);
@@ -340,8 +346,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
     };
-    pi.registerTool(requirementSaveTool);
-    registerAlias(pi, requirementSaveTool, "gsd_save_requirement", "gsd_requirement_save");
+    registerWorkflowTool(pi, requirementSaveTool);
     // ─── gsd_summary_save (formerly gsd_save_summary) ──────────────────────
     const summarySaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         try {
@@ -397,8 +402,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
     };
-    pi.registerTool(summarySaveTool);
-    registerAlias(pi, summarySaveTool, "gsd_save_summary", "gsd_summary_save");
+    registerWorkflowTool(pi, summarySaveTool);
     // ─── gsd_uat_result_save ─────────────────────────────────────────────────
     const uatResultSaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executeUatResultSave } = await loadWorkflowExecutors();
@@ -480,7 +484,7 @@ export function registerDbTools(pi) {
             return new Text(theme.fg("success", `UAT ${d?.sliceId ?? ""}: ${d?.verdict ?? "saved"}`), 0, 0);
         },
     };
-    pi.registerTool(uatResultSaveTool);
+    registerWorkflowTool(pi, uatResultSaveTool);
     // ─── gsd_milestone_generate_id (formerly gsd_generate_milestone_id) ────
     const milestoneGenerateIdExecute = async (_toolCallId, _params, _signal, _onUpdate, _ctx) => {
         try {
@@ -566,8 +570,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
     };
-    pi.registerTool(milestoneGenerateIdTool);
-    registerAlias(pi, milestoneGenerateIdTool, "gsd_generate_milestone_id", "gsd_milestone_generate_id");
+    registerWorkflowTool(pi, milestoneGenerateIdTool);
     // ─── gsd_plan_milestone (gsd_milestone_plan alias) ─────────────────────
     const planMilestoneExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executePlanMilestone } = await loadWorkflowExecutors();
@@ -633,8 +636,7 @@ export function registerDbTools(pi) {
         }),
         execute: planMilestoneExecute,
     };
-    pi.registerTool(planMilestoneTool);
-    registerAlias(pi, planMilestoneTool, "gsd_milestone_plan", "gsd_plan_milestone");
+    registerWorkflowTool(pi, planMilestoneTool);
     // ─── gsd_plan_slice (gsd_slice_plan alias) ─────────────────────────────
     const planSliceExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executePlanSlice } = await loadWorkflowExecutors();
@@ -678,8 +680,7 @@ export function registerDbTools(pi) {
         }),
         execute: planSliceExecute,
     };
-    pi.registerTool(planSliceTool);
-    registerAlias(pi, planSliceTool, "gsd_slice_plan", "gsd_plan_slice");
+    registerWorkflowTool(pi, planSliceTool);
     // ─── gsd_plan_task (gsd_task_plan alias) ───────────────────────────────
     const planTaskExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const basePath = resolveCtxCwd(_ctx);
@@ -748,8 +749,7 @@ export function registerDbTools(pi) {
         }),
         execute: planTaskExecute,
     };
-    pi.registerTool(planTaskTool);
-    registerAlias(pi, planTaskTool, "gsd_task_plan", "gsd_plan_task");
+    registerWorkflowTool(pi, planTaskTool);
     // ─── gsd_task_complete (gsd_complete_task alias) ────────────────────────
     const taskCompleteExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executeTaskComplete } = await loadWorkflowExecutors();
@@ -809,8 +809,7 @@ export function registerDbTools(pi) {
         }),
         execute: taskCompleteExecute,
     };
-    pi.registerTool(taskCompleteTool);
-    registerAlias(pi, taskCompleteTool, "gsd_complete_task", "gsd_task_complete");
+    registerWorkflowTool(pi, taskCompleteTool);
     // ─── gsd_slice_complete (gsd_complete_slice alias) ─────────────────────
     const sliceCompleteExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executeSliceComplete } = await loadWorkflowExecutors();
@@ -875,8 +874,7 @@ export function registerDbTools(pi) {
         }),
         execute: sliceCompleteExecute,
     };
-    pi.registerTool(sliceCompleteTool);
-    registerAlias(pi, sliceCompleteTool, "gsd_complete_slice", "gsd_slice_complete");
+    registerWorkflowTool(pi, sliceCompleteTool);
     // ─── gsd_skip_slice (#3477 / #3487) ───────────────────────────────────
     const skipSliceExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const basePath = resolveCtxCwd(_ctx);
@@ -941,7 +939,7 @@ export function registerDbTools(pi) {
             };
         }
     };
-    pi.registerTool({
+    registerWorkflowTool(pi, {
         name: "gsd_skip_slice",
         label: "Skip Slice",
         description: "Mark a slice as skipped so auto-mode advances past it without executing. " +
@@ -1000,8 +998,7 @@ export function registerDbTools(pi) {
         }),
         execute: milestoneCompleteExecute,
     };
-    pi.registerTool(milestoneCompleteTool);
-    registerAlias(pi, milestoneCompleteTool, "gsd_milestone_complete", "gsd_complete_milestone");
+    registerWorkflowTool(pi, milestoneCompleteTool);
     // ─── gsd_validate_milestone (gsd_milestone_validate alias) ─────────────
     const milestoneValidateExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executeValidateMilestone } = await loadWorkflowExecutors();
@@ -1035,8 +1032,7 @@ export function registerDbTools(pi) {
         }),
         execute: milestoneValidateExecute,
     };
-    pi.registerTool(milestoneValidateTool);
-    registerAlias(pi, milestoneValidateTool, "gsd_milestone_validate", "gsd_validate_milestone");
+    registerWorkflowTool(pi, milestoneValidateTool);
     // ─── gsd_replan_slice (gsd_slice_replan alias) ─────────────────────────
     const replanSliceExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executeReplanSlice } = await loadWorkflowExecutors();
@@ -1078,8 +1074,7 @@ export function registerDbTools(pi) {
         }),
         execute: replanSliceExecute,
     };
-    pi.registerTool(replanSliceTool);
-    registerAlias(pi, replanSliceTool, "gsd_slice_replan", "gsd_replan_slice");
+    registerWorkflowTool(pi, replanSliceTool);
     // ─── gsd_reassess_roadmap (gsd_roadmap_reassess alias) ─────────────────
     const reassessRoadmapExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executeReassessRoadmap } = await loadWorkflowExecutors();
@@ -1126,8 +1121,7 @@ export function registerDbTools(pi) {
         }),
         execute: reassessRoadmapExecute,
     };
-    pi.registerTool(reassessRoadmapTool);
-    registerAlias(pi, reassessRoadmapTool, "gsd_roadmap_reassess", "gsd_reassess_roadmap");
+    registerWorkflowTool(pi, reassessRoadmapTool);
     // ─── gsd_task_reopen (gsd_reopen_task alias) ───────────────────────────
     // Single-writer v3, Stream 3: reversibility tools for closed units.
     const reopenTaskExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
@@ -1190,8 +1184,7 @@ export function registerDbTools(pi) {
         }),
         execute: reopenTaskExecute,
     };
-    pi.registerTool(reopenTaskTool);
-    registerAlias(pi, reopenTaskTool, "gsd_reopen_task", "gsd_task_reopen");
+    registerWorkflowTool(pi, reopenTaskTool);
     // ─── gsd_slice_reopen (gsd_reopen_slice alias) ─────────────────────────
     const reopenSliceExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const basePath = resolveCtxCwd(_ctx);
@@ -1253,8 +1246,7 @@ export function registerDbTools(pi) {
         }),
         execute: reopenSliceExecute,
     };
-    pi.registerTool(reopenSliceTool);
-    registerAlias(pi, reopenSliceTool, "gsd_reopen_slice", "gsd_slice_reopen");
+    registerWorkflowTool(pi, reopenSliceTool);
     // ─── gsd_milestone_reopen (gsd_reopen_milestone alias) ─────────────────
     const reopenMilestoneExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const basePath = resolveCtxCwd(_ctx);
@@ -1314,8 +1306,7 @@ export function registerDbTools(pi) {
         }),
         execute: reopenMilestoneExecute,
     };
-    pi.registerTool(reopenMilestoneTool);
-    registerAlias(pi, reopenMilestoneTool, "gsd_reopen_milestone", "gsd_milestone_reopen");
+    registerWorkflowTool(pi, reopenMilestoneTool);
     // ─── gsd_save_gate_result ──────────────────────────────────────────────
     const saveGateResultExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const { executeSaveGateResult } = await loadWorkflowExecutors();
@@ -1378,5 +1369,5 @@ export function registerDbTools(pi) {
             return new Text(theme.fg(color, `${d.gateId}: ${d.verdict}`), 0, 0);
         },
     };
-    pi.registerTool(saveGateResultTool);
+    registerWorkflowTool(pi, saveGateResultTool);
 }

package/dist/resources/extensions/gsd/bootstrap/dynamic-tools.js

@@ -2,11 +2,11 @@
 // 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 { 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";
 export function safeWorkspaceCwd() {
@@ -58,44 +58,18 @@ export function resolveWorkflowToolBasePath(ctx, scope) {
     }
     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) {
-    return resolveGsdPathContract(basePath).projectDb;
-}
+export { resolveProjectRootDbPath } from "../db-workspace.js";
 export async function ensureDbOpen(basePath = safeWorkspaceCwd()) {
-    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.message ?? String(err)}`);
-        return false;
+    else {
+        logWarning("bootstrap", `ensureDbOpen failed: ${result.error?.message ?? "open failed"}`);
     }
+    return false;
 }
 export function registerDynamicTools(pi) {
     const fallbackRoot = safeWorkspaceCwd();

package/dist/resources/extensions/gsd/bootstrap/query-tools.js

@@ -3,6 +3,7 @@
 // gsd-pi — Read-only query tools exposing DB state to the LLM via the WAL connection
 import { Type } from "@sinclair/typebox";
 import { ensureDbOpen, resolveCtxCwd } from "./dynamic-tools.js";
+import { checkpointWorkflowDatabase } from "../db-workspace.js";
 export function registerQueryTools(pi) {
     pi.registerTool({
         name: "gsd_milestone_status",
@@ -50,8 +51,7 @@ export function registerQueryTools(pi) {
                     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/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -7,11 +7,12 @@ import { isToolCallEventType } from "@gsd/pi-coding-agent";
 import { ALWAYS_PRESERVED_SHIM_TOOL_NAMES } from "@gsd/pi-ai";
 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";
-import { clearToolInvocationError, getAutoRuntimeSnapshot, getSourceObservationStore, isAutoActive, isAutoCompletionStopInProgress, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError, } from "../auto-runtime-state.js";
+import { clearAutoCompletionStopInProgress, clearToolInvocationError, getAutoRuntimeSnapshot, getSourceObservationStore, 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";
 import { saveActivityLog } from "../activity-log.js";
@@ -22,16 +23,18 @@ 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 { 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;
 async function loadWelcomeScreenModule() {
     const candidates = [];
@@ -109,7 +112,9 @@ export const MINIMAL_GSD_TOOL_NAMES = [
     "gsd_checkpoint_db",
     "gsd_plan_milestone",
     "memory_query",
+    "gsd_memory_query",
     "capture_thought",
+    "gsd_capture_thought",
 ];
 export const MINIMAL_AUTO_BASE_TOOL_NAMES = [
     "ask_user_questions",
@@ -163,15 +168,19 @@ function resolveScopedToolNames(activeToolNames, requestedToolNames) {
     const resolved = new Set();
     for (const requested of requestedToolNames) {
         const scopedMatches = [];
+        const aliasFallbacks = [];
         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)
@@ -212,7 +221,7 @@ export function buildRunUatGsdToolSet(activeToolNames, registeredToolNames = act
         ...RUN_UAT_BROWSER_TOOL_NAMES,
     ]);
     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}`))));
+    const unresolved = RUN_UAT_WORKFLOW_TOOL_NAMES.filter((tool) => !resolved.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)));
     if (unresolved.length > 0) {
         safetyLogWarning("bootstrap", `buildRunUatGsdToolSet: required run-uat workflow tool(s) not found in active/registered surface: ${unresolved.join(", ")}. Session may lack gsd-workflow MCP connection.`);
     }
@@ -269,7 +278,17 @@ function applyMinimalGsdToolSurface(pi) {
         return;
     const dash = getAutoRuntimeSnapshot();
     if (dash.active && dash.currentUnit) {
-        pi.setActiveTools(buildMinimalAutoGsdToolSet(pi.getActiveTools(), dash.currentUnit.type, resolveRegisteredToolNames(pi, pi.getActiveTools())));
+        const currentToolNames = pi.getActiveTools();
+        const registeredToolNames = resolveRegisteredToolNames(pi, currentToolNames);
+        const scopedToolNames = buildMinimalAutoGsdToolSet(currentToolNames, dash.currentUnit.type, registeredToolNames);
+        recordAutoToolSurfaceSnapshot({
+            source: "runtime-scope",
+            unitType: dash.currentUnit.type,
+            modelFacingToolNames: scopedToolNames,
+            registeredToolNames,
+            scopedToolNames,
+        });
+        pi.setActiveTools(scopedToolNames);
         return;
     }
     if (!isGeneralGsdToolScopingRequested())
@@ -284,6 +303,13 @@ export function scopeGsdWorkflowToolsForDispatch(pi, unitType) {
     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) {
@@ -538,6 +564,7 @@ function initSessionNotifications(ctx) {
     initNotificationStore(resolveNotificationStoreBasePath(contextBasePath(ctx)));
     installNotifyInterceptor(ctx);
     initNotificationWidget(ctx);
+    notifyPreferenceDiagnostics(ctx, contextBasePath(ctx), { surface: "session-start" });
 }
 async function prepareWorkflowMcpForHookContext(ctx, basePath) {
     // Skip MCP auto-prep when running inside an auto-worktree. The worktree
@@ -624,6 +651,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
     });
     pi.on("before_agent_start", async (event, ctx) => {
+        clearAutoCompletionStopInProgress();
         resetPendingGatePauseGuard();
         applyMinimalGsdToolSurface(pi);
         // Wait for ecosystem loader to finish (no-op after first turn).
@@ -800,6 +828,20 @@ export function registerHooks(pi, ecosystemHandlers) {
     pi.on("message_update", async (event, ctx) => {
         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;
@@ -1068,77 +1110,32 @@ export function registerHooks(pi, ecosystemHandlers) {
         const basePath = contextBasePath(ctx);
         const milestoneId = await getDiscussionMilestoneIdFor(basePath);
         const details = event.details;
-        // ── 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 = event.input?.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",
-                            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",
+                        text: formatPendingAskUserQuestionsGateMessage(gateResult.pendingGateId, gateResult.interrupted),
+                    }],
+            };
+        }
+        if (gateResult.status === "verified") {
+            clearDeferredApprovalGate(basePath);
         }
         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 (!milestoneId)
             return;
         await saveDiscussionQuestionRound(basePath, milestoneId, questions, details);
@@ -1193,61 +1190,10 @@ export function registerHooks(pi, ecosystemHandlers) {
         const payload = event.payload;
         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, maxChars);
-            }
-            const input = payload.input;
-            if (Array.isArray(input)) {
-                payload.input = truncateResponsesInputResultItems(input, 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)
     // Extensions can override model selection by returning { modelId: "..." }
@@ -1279,16 +1225,35 @@ export function registerHooks(pi, ecosystemHandlers) {
         const registeredToolNames = resolveRegisteredToolNames(pi, event.activeToolNames);
         const compatibleRegisteredToolNames = filterToolsForProvider(registeredToolNames, event.selectedModelApi, event.selectedModelProvider).compatible.filter((name) => !(dropAliases && isWorkflowAliasTool(name)));
         const guidedUnit = getGuidedUnitContext();
-        const requestScoped = buildRequestScopedGsdToolSet(guidedUnit?.unitType === "run-uat" ? aliasFilteredCompatible : providerCompatible, event.requestCustomMessages, guidedUnit?.unitType === "run-uat" ? compatibleRegisteredToolNames : registeredToolNames, guidedUnit?.unitType);
+        const requestRegisteredToolNames = guidedUnit?.unitType === "run-uat"
+            ? compatibleRegisteredToolNames
+            : registeredToolNames;
+        const requestScoped = buildRequestScopedGsdToolSet(guidedUnit?.unitType === "run-uat" ? aliasFilteredCompatible : providerCompatible, event.requestCustomMessages, 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()) {