@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -1,37 +1,48 @@
 // Project/App: gsd-pi
 // File Purpose: Registers GSD extension runtime hooks and token-saving tool policies.
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 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 { buildMilestoneFileName, canonicalPhaseDirName, clearPathCache, milestonesDir, legacyMilestonesDir, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
+import { applyAskUserQuestionsGateResult, clearDiscussionFlowState, currentWriteGateSnapshot, formatPendingAskUserQuestionsGateMessage, formatTimedOutAskUserQuestionsGateMessage, hostWriteGateAdapter, isApprovalGateVerifiedInSnapshot, isDepthConfirmationAnswer, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeBash, shouldBlockWorktreeWrite, isGateQuestionId, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { canonicalToolName } from "../engine-hook-contract.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 { clearAutoCompletionStopInProgress, 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 { MINIMAL_AUTO_BASE_TOOL_NAMES } from "./core-session-tools.js";
 import { maybePauseAutoForApprovalGate, resetPendingGatePauseGuard } from "./pending-gate-pause.js";
 import { saveActivityLog } from "../activity-log.js";
 import { recordToolCall as safetyRecordToolCall, recordToolResult as safetyRecordToolResult, saveEvidenceToDisk } from "../safety/evidence-collector.js";
 import { parseUnitId } from "../unit-id.js";
 import { classifyCommand } from "../safety/destructive-guard.js";
-import { logWarning as safetyLogWarning } from "../workflow-logger.js";
+import { confirmDestructiveCommand, consumeDestructiveConfirmation, isDestructiveConfirmGateId, requestDestructiveConfirmation, } from "../safety/destructive-confirmation.js";
+import { logWarning as safetyLogWarning, setStderrLoggingEnabled } from "../workflow-logger.js";
+import { isUnitCloseoutTool, runInteractiveUnitCloseout } from "../unit-closeout.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, evaluateAskUserQuestionsRound, formatUnansweredConsentQuestionMessage, isExplicitApprovalResponse, messageHasPendingAskUserQuestionsTool, shouldPauseForQuestion, } from "../consent-question.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 { hasBrowserContractPrefix } from "../../shared/browser-contract.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";
+import { resolveWorkflowToolBasePath } from "./dynamic-tools.js";
+import { getRequiredWorkflowToolsForUnit } from "../unit-tool-contracts.js";
 let approvalQuestionAbortInFlight = false;
 async function loadWelcomeScreenModule() {
     const candidates = [];
@@ -100,7 +111,22 @@ async function installWelcomeHeader(ctx) {
         /* non-fatal */
     }
 }
-let deferredApprovalGate = null;
+/** Suppress the startup welcome banner without restoring the built-in pi header. */
+function suppressWelcomeHeader(ctx) {
+    if (!ctx.hasUI || typeof ctx.ui?.setHeader !== "function")
+        return;
+    ctx.ui.setHeader(() => ({
+        render() { return []; },
+        invalidate() { },
+    }));
+}
+/**
+ * Approval gates whose durable arming is deferred until tool execution /
+ * agent end, keyed by basePath. A Map (not a single slot) so concurrent
+ * projects in one process cannot lose each other's deferred gate; entries
+ * are bounded — cleared on activation, session boundaries, and verification.
+ */
+const deferredApprovalGates = new Map();
 export const MINIMAL_GSD_TOOL_NAMES = [
     "gsd_exec",
     "gsd_exec_search",
@@ -113,28 +139,13 @@ export const MINIMAL_GSD_TOOL_NAMES = [
     "capture_thought",
     "gsd_capture_thought",
 ];
-export const MINIMAL_AUTO_BASE_TOOL_NAMES = [
-    "ask_user_questions",
-    "bash",
-    "bg_shell",
-    "edit",
-    "find",
-    "glob",
-    "grep",
-    "fetch_page",
-    "search-the-web",
-    "ls",
-    "read",
-    "subagent",
-    "write",
-    "ToolSearch",
-];
+export { MINIMAL_AUTO_BASE_TOOL_NAMES } from "./core-session-tools.js";
 function withPreservedShimTools(toolNames) {
     return [...new Set([...toolNames, ...ALWAYS_PRESERVED_SHIM_TOOL_NAMES])];
 }
 /** True for the browser automation tools (browser_navigate, browser_click, ...). */
 function isBrowserTool(toolName) {
-    return canonicalToolName(toolName).startsWith("browser_");
+    return hasBrowserContractPrefix(canonicalToolName(toolName));
 }
 /**
  * True when any message in the request is driven by a GSD workflow command
@@ -165,15 +176,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)
@@ -192,7 +207,7 @@ export function buildMinimalGsdToolSet(activeToolNames) {
     const minimal = resolveScopedToolNames(activeToolNames, MINIMAL_GSD_TOOL_NAMES);
     return withPreservedShimTools([...new Set([...preserved, ...minimal])]);
 }
-export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registeredToolNames = activeToolNames) {
+export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registeredToolNames = activeToolNames, warnOnUnresolvedRequiredTools = registeredToolNames !== activeToolNames) {
     if (unitType === "run-uat") {
         return buildRunUatGsdToolSet(activeToolNames, registeredToolNames);
     }
@@ -204,7 +219,20 @@ export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registered
             ...availableBaseTools,
         ])];
     const scoped = resolveScopedToolNames([...activeToolNames, ...registeredToolNames], [...MINIMAL_GSD_TOOL_NAMES, ...unitTools]);
-    return withPreservedShimTools([...new Set([...preserved, ...scoped])]);
+    const result = withPreservedShimTools([...new Set([...preserved, ...scoped])]);
+    warnIfRequiredWorkflowToolsUnresolved(unitType, result, warnOnUnresolvedRequiredTools);
+    return result;
+}
+function hasResolvedWorkflowTool(resolvedToolNames, requiredToolName) {
+    return resolvedToolNames.some((name) => name === requiredToolName || mcpToolMatchesBaseName(name, requiredToolName));
+}
+function warnIfRequiredWorkflowToolsUnresolved(unitType, scopedToolNames, shouldWarn) {
+    if (!unitType || !shouldWarn)
+        return;
+    const unresolved = getRequiredWorkflowToolsForUnit(unitType).filter((toolName) => !hasResolvedWorkflowTool(scopedToolNames, toolName));
+    if (unresolved.length === 0)
+        return;
+    safetyLogWarning("bootstrap", `buildMinimalAutoGsdToolSet(${unitType}): required workflow tool(s) not in active/registered surface after scoping: ${unresolved.join(", ")}. Tool registration may have partially failed, provider filtering may have removed a required tool, or workflow MCP may be disconnected.`);
 }
 export function buildRunUatGsdToolSet(activeToolNames, registeredToolNames = activeToolNames) {
     const scoped = resolveScopedToolNames([...activeToolNames, ...registeredToolNames], [
@@ -214,7 +242,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.`);
     }
@@ -230,7 +258,7 @@ export function buildMinimalGsdWorkflowToolSet(activeToolNames, registeredToolNa
     const scoped = resolveScopedToolNames([...activeToolNames, ...registeredToolNames], WORKFLOW_GSD_TOOL_NAMES);
     return withPreservedShimTools([...new Set([...preserved, ...scoped])]);
 }
-export function buildRequestScopedGsdToolSet(activeToolNames, requestCustomMessages, registeredToolNames = activeToolNames, guidedUnitType) {
+export function buildRequestScopedGsdToolSet(activeToolNames, requestCustomMessages, registeredToolNames = activeToolNames, guidedUnitType, warnOnUnresolvedRequiredTools = registeredToolNames !== activeToolNames) {
     for (let index = (requestCustomMessages?.length ?? 0) - 1; index >= 0; index--) {
         const currentCustomType = requestCustomMessages?.[index]?.customType;
         if (currentCustomType === "gsd-run" ||
@@ -238,7 +266,7 @@ export function buildRequestScopedGsdToolSet(activeToolNames, requestCustomMessa
             currentCustomType === "gsd-doctor-heal" ||
             currentCustomType === "gsd-triage") {
             if (guidedUnitType) {
-                return buildMinimalAutoGsdToolSet(activeToolNames, guidedUnitType, registeredToolNames);
+                return buildMinimalAutoGsdToolSet(activeToolNames, guidedUnitType, registeredToolNames, warnOnUnresolvedRequiredTools);
             }
             return buildMinimalGsdWorkflowToolSet(activeToolNames, registeredToolNames);
         }
@@ -271,7 +299,18 @@ 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 hasRegisteredSurface = typeof pi.getAllTools === "function";
+        const registeredToolNames = resolveRegisteredToolNames(pi, currentToolNames);
+        const scopedToolNames = buildMinimalAutoGsdToolSet(currentToolNames, dash.currentUnit.type, registeredToolNames, hasRegisteredSurface);
+        recordAutoToolSurfaceSnapshot({
+            source: "runtime-scope",
+            unitType: dash.currentUnit.type,
+            modelFacingToolNames: scopedToolNames,
+            registeredToolNames,
+            scopedToolNames,
+        });
+        pi.setActiveTools(scopedToolNames);
         return;
     }
     if (!isGeneralGsdToolScopingRequested())
@@ -282,10 +321,18 @@ export function scopeGsdWorkflowToolsForDispatch(pi, unitType) {
     if (isFullGsdToolSurfaceRequested())
         return null;
     const current = pi.getActiveTools();
+    const hasRegisteredSurface = typeof pi.getAllTools === "function";
     const registeredToolNames = resolveRegisteredToolNames(pi, current);
     const scoped = unitType
-        ? buildMinimalAutoGsdToolSet(current, unitType, registeredToolNames)
+        ? buildMinimalAutoGsdToolSet(current, unitType, registeredToolNames, hasRegisteredSurface)
         : 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) {
@@ -363,12 +410,27 @@ async function applyCompactionThresholdOverride(ctx) {
     }
 }
 function clearDeferredApprovalGate(basePath) {
-    if (!basePath || deferredApprovalGate?.basePath === basePath) {
-        deferredApprovalGate = null;
+    if (!basePath) {
+        deferredApprovalGates.clear();
+    }
+    else {
+        deferredApprovalGates.delete(basePath);
     }
 }
 function deferApprovalGate(gateId, basePath) {
-    deferredApprovalGate = { gateId, basePath };
+    // Verified-on-disk wins (same adapter policy as activation/re-arm): if the
+    // workflow MCP child already verified this gate, deferring would block
+    // tools for a gate that can never legitimately arm.
+    const snapshot = hostWriteGateAdapter.readState(basePath);
+    deferApprovalGateFromSnapshot(gateId, basePath, snapshot);
+}
+function deferApprovalGateFromSnapshot(gateId, basePath, snapshot) {
+    if (isApprovalGateVerifiedInSnapshot(snapshot, gateId))
+        return;
+    const milestoneId = extractDepthVerificationMilestoneId(gateId);
+    if (milestoneId && isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId))
+        return;
+    deferredApprovalGates.set(basePath, gateId);
 }
 function contextBasePath(ctx) {
     return typeof ctx?.cwd === "string" ? ctx.cwd : process.cwd();
@@ -418,10 +480,14 @@ function isShellExecutionTool(canonicalName) {
         canonicalName === "powershell";
 }
 function activateDeferredApprovalGate(basePath) {
-    if (deferredApprovalGate?.basePath !== basePath)
+    const gateId = deferredApprovalGates.get(basePath);
+    if (gateId === undefined)
         return;
-    setPendingGate(deferredApprovalGate.gateId, basePath);
-    deferredApprovalGate = null;
+    deferredApprovalGates.delete(basePath);
+    // hostWriteGateAdapter.setPending applies the verified-on-disk-wins merge
+    // policy: it refuses to arm (and thereby clobber) a gate the workflow MCP
+    // child already verified on disk.
+    hostWriteGateAdapter.setPending(gateId, basePath);
 }
 function extractGateQuestionId(input) {
     const questions = input?.questions ?? [];
@@ -430,7 +496,7 @@ function extractGateQuestionId(input) {
 }
 function isApprovalGateBlocking(basePath) {
     return Boolean(getPendingGate(basePath))
-        || (deferredApprovalGate?.basePath === basePath);
+        || deferredApprovalGates.has(basePath);
 }
 function isContextDraftSummarySave(toolName, input) {
     if (toolName !== "gsd_summary_save" && toolName !== "summary_save")
@@ -439,6 +505,25 @@ function isContextDraftSummarySave(toolName, input) {
         return false;
     return input.artifact_type === "CONTEXT-DRAFT";
 }
+/**
+ * External engines (claude-code-cli) deliver ask_user_questions results as
+ * relayed MCP tool results: the structured round payload arrives in
+ * `result.structuredContent`, not in pi-native `event.details`. Without this
+ * fallback, applyAskUserQuestionsGateResult sees no response for an answered
+ * gate question and lands in the "waiting" branch — leaving a re-armed gate
+ * permanently pending and the discuss→auto handoff blocked.
+ */
+function resolveAskUserQuestionsGateDetails(event) {
+    const hasRoundShape = (value) => !!value && typeof value === "object" &&
+        (value.cancelled !== undefined || value.timed_out !== undefined || value.response !== undefined);
+    const details = event.details;
+    if (hasRoundShape(details))
+        return details;
+    const structured = event.result?.structuredContent;
+    if (hasRoundShape(structured))
+        return structured;
+    return details ?? {};
+}
 function selectedAnswerLabel(selected) {
     if (Array.isArray(selected))
         return selected.map(String).join(", ");
@@ -470,8 +555,24 @@ function formatQuestionExchange(questions, answers) {
     return lines.join("\n");
 }
 async function ensureMilestoneShell(basePath, milestoneId) {
+    // When no milestone dir exists yet, prefer the legacy container when it has
+    // at least one milestone subdirectory; an empty milestones/ dir (e.g. one
+    // created by an old bootstrapGsdProject) is not a real legacy layout.
+    const legacy = legacyMilestonesDir(basePath);
+    const isLegacyLayout = existsSync(legacy) && (() => {
+        try {
+            return readdirSync(legacy).some(e => statSync(join(legacy, e)).isDirectory());
+        }
+        catch {
+            return false;
+        }
+    })();
+    const container = isLegacyLayout ? legacy : milestonesDir(basePath);
+    const fallbackDirName = isLegacyLayout
+        ? milestoneId
+        : canonicalPhaseDirName(milestoneId, `New milestone ${milestoneId}`);
     const milestoneDir = resolveMilestonePath(basePath, milestoneId)
-        ?? join(milestonesDir(basePath), milestoneId);
+        ?? join(container, fallbackDirName);
     mkdirSync(milestoneDir, { recursive: true });
     clearPathCache();
     try {
@@ -497,10 +598,14 @@ async function saveDiscussionQuestionRound(basePath, milestoneId, questions, det
     const answers = details?.response?.answers;
     const timestamp = new Date().toISOString();
     const exchange = formatQuestionExchange(questions, answers);
-    const discussionPath = join(milestoneDir, buildMilestoneFileName(milestoneId, "DISCUSSION"));
+    // Layout-aware filename: legacy dirs use MID-SUFFIX.md; flat-phase use NN-SUFFIX.md.
+    const legacyBase = legacyMilestonesDir(basePath);
+    const isLegacyDir = milestoneDir.startsWith(legacyBase + "/") || milestoneDir.startsWith(legacyBase + "\\");
+    const milestoneFileName = (suffix) => isLegacyDir ? `${milestoneId}-${suffix}.md` : buildMilestoneFileName(milestoneId, suffix);
+    const discussionPath = join(milestoneDir, milestoneFileName("DISCUSSION"));
     const existingDiscussion = await loadFile(discussionPath) ?? `# ${milestoneId} Discussion Log\n\n`;
     await saveFile(discussionPath, `${existingDiscussion}## Exchange — ${timestamp}\n\n${exchange}---\n\n`);
-    const draftPath = join(milestoneDir, buildMilestoneFileName(milestoneId, "CONTEXT-DRAFT"));
+    const draftPath = join(milestoneDir, milestoneFileName("CONTEXT-DRAFT"));
     const existingDraft = await loadFile(draftPath);
     const draftHeader = existingDraft
         ?? [
@@ -518,7 +623,8 @@ function withDepthGateDisplayReason(result, displayReason = "Depth confirmation
     return { ...result, displayReason };
 }
 function shouldBlockDeferredApprovalTool(toolName, input, basePath) {
-    if (deferredApprovalGate?.basePath !== basePath)
+    const deferredGateId = deferredApprovalGates.get(basePath);
+    if (deferredGateId === undefined)
         return { block: false };
     if (toolName === "ask_user_questions")
         return { block: false };
@@ -527,7 +633,7 @@ function shouldBlockDeferredApprovalTool(toolName, input, basePath) {
     return withDepthGateDisplayReason({
         block: true,
         reason: [
-            `HARD BLOCK: Approval question "${deferredApprovalGate.gateId}" has been shown to the user.`,
+            `HARD BLOCK: Approval question "${deferredGateId}" has been shown to the user.`,
             `Only CONTEXT-DRAFT persistence may finish in this same assistant turn.`,
             `Wait for the user's answer before calling additional tools.`,
         ].join(" "),
@@ -540,6 +646,10 @@ function initSessionNotifications(ctx) {
     initNotificationStore(resolveNotificationStoreBasePath(contextBasePath(ctx)));
     installNotifyInterceptor(ctx);
     initNotificationWidget(ctx);
+    notifyPreferenceDiagnostics(ctx, contextBasePath(ctx), { surface: "session-start" });
+    if (ctx.hasUI) {
+        setStderrLoggingEnabled(false);
+    }
 }
 async function prepareWorkflowMcpForHookContext(ctx, basePath) {
     // Skip MCP auto-prep when running inside an auto-worktree. The worktree
@@ -574,6 +684,29 @@ export function registerHooks(pi, ecosystemHandlers) {
         await applyDisabledModelProviderPolicy(ctx);
         await applyCompactionThresholdOverride(ctx);
         await prepareWorkflowMcpForHookContext(ctx, basePath);
+        // Migrate legacy .gsd/milestones/ to flat-phase .gsd/phases/ when detected.
+        // Best-effort — never blocks session startup. Skipped inside auto-worktrees
+        // (migration already ran on the project root before the worktree was created).
+        try {
+            const { isInAutoWorktree } = await import("../auto-worktree.js");
+            if (!isInAutoWorktree(basePath)) {
+                const { needsFlatPhaseMigration } = await import("../flat-phase-migration.js");
+                if (needsFlatPhaseMigration(basePath)) {
+                    const { ensureDbOpen } = await import("./dynamic-tools.js");
+                    const opened = await ensureDbOpen(basePath);
+                    if (opened) {
+                        const { migrateToFlatPhase } = await import("../flat-phase-migration.js");
+                        await migrateToFlatPhase(basePath);
+                    }
+                    else {
+                        safetyLogWarning("bootstrap", "flat-phase migration deferred: legacy .gsd/milestones/ layout detected but the workflow database could not be opened — will retry on next session");
+                    }
+                }
+            }
+        }
+        catch (err) {
+            safetyLogWarning("bootstrap", `flat-phase migration: ${err instanceof Error ? err.message : String(err)}`);
+        }
         // Apply show_token_cost preference (#1515)
         try {
             const { loadEffectiveGSDPreferences } = await import("../preferences.js");
@@ -582,7 +715,15 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         catch { /* non-fatal */ }
         if (!preserveCloseoutSurface) {
-            await installWelcomeHeader(ctx);
+            // Per-unit newSession() during auto/step runs fires session_start again.
+            // Keep the welcome banner startup-only — do not overwrite the empty header
+            // that updateProgressWidget installs once work begins.
+            if (isAutoActive() || isAutoPaused()) {
+                suppressWelcomeHeader(ctx);
+            }
+            else {
+                await installWelcomeHeader(ctx);
+            }
         }
         await loadToolApiKeysForSession();
         if (isAutoActive() || preserveCloseoutSurface) {
@@ -601,7 +742,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             catch { /* non-fatal */ }
         }
     });
-    pi.on("session_switch", async (_event, ctx) => {
+    pi.on("session_switch", async (event, ctx) => {
         const basePath = contextBasePath(ctx);
         const preserveCloseoutSurface = isAutoCompletionStopInProgress();
         initSessionNotifications(ctx);
@@ -610,6 +751,13 @@ export function registerHooks(pi, ecosystemHandlers) {
         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);
@@ -635,11 +783,13 @@ export function registerHooks(pi, ecosystemHandlers) {
         const beforeAgentBasePath = contextBasePath(ctx);
         const pendingApprovalGate = getPendingGate(beforeAgentBasePath);
         if (pendingApprovalGate && isExplicitApprovalResponse(event.prompt, pendingApprovalGate)) {
-            markApprovalGateVerified(pendingApprovalGate, beforeAgentBasePath);
+            // Host adapter explicitly: the ambient write-gate exports env-sniff the
+            // adapter per call and are reserved for the MCP child's import surface.
+            hostWriteGateAdapter.markApprovalGateVerified(pendingApprovalGate, beforeAgentBasePath);
             const milestoneId = extractDepthVerificationMilestoneId(pendingApprovalGate);
             if (milestoneId)
-                markDepthVerified(milestoneId, beforeAgentBasePath);
-            clearPendingGate(beforeAgentBasePath);
+                hostWriteGateAdapter.markDepthVerified(milestoneId, beforeAgentBasePath);
+            hostWriteGateAdapter.clearPending(beforeAgentBasePath);
             if (isAutoPaused() && !isAutoActive()) {
                 const { resumeAutoAfterProviderDelay } = await import("./provider-error-resume.js");
                 void resumeAutoAfterProviderDelay(pi, ctx).catch((err) => {
@@ -720,6 +870,10 @@ export function registerHooks(pi, ecosystemHandlers) {
     pi.on("message_end", async (event) => {
         const { suppressTerminalDeletedWorktreeMessageEnd } = await import("./agent-end-recovery.js");
         suppressTerminalDeletedWorktreeMessageEnd(event);
+        if (isAutoActive()) {
+            const { sanitizePrematureCloseoutMessageEnd } = await import("../auto-closeout-messaging.js");
+            sanitizePrematureCloseoutMessageEnd(event);
+        }
     });
     // Squash-merge quick-task branch back to the original branch after the
     // agent turn completes (#2668). cleanupQuickBranch is a no-op when no
@@ -803,6 +957,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;
@@ -826,21 +994,23 @@ export function registerHooks(pi, ecosystemHandlers) {
                 unitId = milestoneId;
             }
         }
-        if (!shouldPauseForUserApprovalQuestion(unitType, [event.message]))
+        if (!shouldPauseForQuestion(unitType, [event.message]))
             return;
         const gateId = approvalGateIdForUnit(unitType, unitId);
         if (gateId) {
+            const basePath = contextBasePath(ctx);
+            const gateSnapshot = currentWriteGateSnapshot(basePath);
             // Skip the gate if this milestone is already depth-verified — the approval
             // pattern matched again on post-verification text (a false-positive re-trigger).
             // Without this guard, the second firing blocks gsd_plan_milestone in the same
             // turn and leaves CONTEXT.md on disk with no DB row (#discuss-milestone-no-db).
             const gateMilestoneId = extractDepthVerificationMilestoneId(gateId);
-            if (gateMilestoneId && isMilestoneDepthVerified(gateMilestoneId, contextBasePath(ctx)))
+            if (gateMilestoneId && isMilestoneDepthVerifiedInSnapshot(gateSnapshot, gateMilestoneId))
                 return;
-            deferApprovalGate(gateId, contextBasePath(ctx));
+            deferApprovalGateFromSnapshot(gateId, basePath, gateSnapshot);
         }
         approvalQuestionAbortInFlight = true;
-        ctx.ui.notify(`${unitType}${unitId ? ` ${unitId}` : ""} is waiting for your approval - pausing before more tool calls run.`, "info");
+        ctx.ui.notify(`${unitType ?? "The discussion"}${unitId ? ` ${unitId}` : ""} is waiting for your approval - pausing before more tool calls run.`, "info");
         // The durable pending gate is activated at agent_end so same-turn
         // CONTEXT-DRAFT persistence can finish after the text boundary streams.
         // The tool_call hook below still blocks non-draft tools in this turn.
@@ -866,6 +1036,13 @@ export function registerHooks(pi, ecosystemHandlers) {
             saveActivityLog(ctx, dash.basePath, dash.currentUnit.type, dash.currentUnit.id);
         }
     });
+    // Engine hook contract (../engine-hook-contract.ts): tool_call is
+    // NATIVE_ONLY_TOOL_HOOKS — it never fires under external engines
+    // (claude-code-cli pre-executes tools). The guards below (loop guard,
+    // pending/deferred gate blocks, queue guard, planning-unit tools policy,
+    // worktree write gate, STATE.md single-writer, context-write depth gate)
+    // are therefore native-engine enforcement only. The write-gate arming
+    // concern has a universal mirror at tool_execution_start below.
     pi.on("tool_call", async (event, ctx) => {
         const discussionBasePath = contextBasePath(ctx);
         const toolName = canonicalToolName(event.toolName);
@@ -975,6 +1152,11 @@ export function registerHooks(pi, ecosystemHandlers) {
             if (wtGuard.block)
                 return wtGuard;
         }
+        if (isToolCallEventType("bash", event)) {
+            const wtBashGuard = shouldBlockWorktreeBash(event.input.command, dash.basePath ?? discussionBasePath, isAutoActive(), dash.currentUnit?.type);
+            if (wtBashGuard.block)
+                return wtBashGuard;
+        }
         // ── Single-writer engine: block direct writes to STATE.md ──────────
         // Covers write, edit, and bash tools to prevent bypass vectors.
         if (isToolCallEventType("write", event)) {
@@ -1000,6 +1182,11 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
     });
     // ── Safety harness: evidence collection + destructive command blocking ──
+    // Engine hook contract: tool_call is NATIVE_ONLY_TOOL_HOOKS. Evidence
+    // collection here is mirrored universally at tool_execution_start
+    // (safetyRecordToolCall dedupes by toolCallId); the destructive-command
+    // hard gate has NO universal mirror — blocking is impossible once an
+    // external engine has already executed the command.
     pi.on("tool_call", async (event, ctx) => {
         markToolStart(event.toolCallId, event.toolName);
         safetyRecordToolCall(event.toolCallId, event.toolName, event.input);
@@ -1017,24 +1204,45 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         // Destructive command classification + hard gate in all modes.
         if (isToolCallEventType("bash", event)) {
-            const classification = classifyCommand(event.input.command);
+            const command = event.input.command;
+            const classification = classifyCommand(command);
             if (classification.destructive) {
+                const guardBasePath = contextBasePath(ctx);
+                // Escape hatch: if the user already confirmed this exact command via a
+                // destructive_confirm gate, consume the one-shot token and let it run.
+                // Without this, the block below loops forever — the model cannot satisfy
+                // "confirm in the current turn" because nothing ever clears the gate.
+                if (consumeDestructiveConfirmation(command, guardBasePath)) {
+                    safetyLogWarning("safety", `destructive command confirmed: ${classification.labels.join(", ")}`, {
+                        command: String(command).slice(0, 200),
+                    });
+                    return;
+                }
+                // Record the command as pending so an affirmative answer to a
+                // destructive_confirm gate (handled in tool_result) can confirm it.
+                requestDestructiveConfirmation(command, guardBasePath);
                 const reason = [
                     "HARD BLOCK: destructive Bash command requires explicit human confirmation.",
                     `Detected: ${classification.labels.join(", ")}`,
-                    "Run this via ask_user_questions, wait for the user's response,",
-                    "then issue the command only when confirmed in the current turn.",
+                    "Call ask_user_questions with a question id containing \"destructive_confirm\"",
+                    "and a first option that affirms the action; wait for the user's response,",
+                    "then re-issue this exact command in the same turn to run it once.",
                 ].join(" ");
                 safetyLogWarning("safety", `destructive command: ${classification.labels.join(", ")}`, {
-                    command: String(event.input.command).slice(0, 200),
+                    command: String(command).slice(0, 200),
                 });
                 if (ctx) {
-                    await maybePauseAutoForApprovalGate(ctx, pi, isAutoActive(), "Depth confirmation is waiting for your answer — pausing auto-mode.");
+                    await maybePauseAutoForApprovalGate(ctx, pi, isAutoActive(), "Destructive-command confirmation is waiting for your answer — pausing auto-mode.");
                 }
                 return { block: true, reason };
             }
         }
     });
+    // Engine hook contract: tool_result is NATIVE_ONLY_TOOL_HOOKS — external
+    // engines skip it. Error classification and markToolEnd are mirrored
+    // universally at tool_execution_end; the ask_user_questions gate lifecycle
+    // here is paired with the tool_execution_start arming path, which external
+    // engines do reach.
     pi.on("tool_result", async (event, ctx) => {
         if (isAutoActive() && typeof event.toolCallId === "string") {
             markToolEnd(event.toolCallId);
@@ -1066,78 +1274,118 @@ export function registerHooks(pi, ecosystemHandlers) {
         else if (isAutoActive()) {
             clearToolInvocationError();
         }
+        // Interactive Closeout adapter (ADR-032): auto-mode owns closeout for its
+        // own units; interactive completions get the durable git subset (commit +
+        // Closeout Git Verdict) instead of silently bypassing git.isolation.
+        if (!event.isError && !isAutoActive() && isUnitCloseoutTool(toolName)) {
+            try {
+                runInteractiveUnitCloseout({
+                    basePath: resolveWorkflowToolBasePath(ctx, event.input),
+                    canonicalToolName: toolName,
+                    input: event.input,
+                });
+            }
+            catch (err) {
+                safetyLogWarning("engine", `interactive unit closeout failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         if (toolName !== "ask_user_questions")
             return;
         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(" "),
-                        }],
-                };
+        const details = resolveAskUserQuestionsGateDetails(event);
+        const questions = event.input?.questions ?? details?.questions ?? [];
+        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.");
             }
-            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);
-                    }
-                }
+            return {
+                content: [{
+                        type: "text",
+                        text: formatPendingAskUserQuestionsGateMessage(gateResult.pendingGateId, gateResult.interrupted),
+                    }],
+            };
+        }
+        if (gateResult.status === "timeout") {
+            // Host elicitation timed out before the user answered. The gate stays
+            // pending (fail-closed), but we reset the loop guard and return a
+            // timeout-specific message so the model does NOT immediately re-ask —
+            // that would just hit the same timeout again. Auto-mode pauses and
+            // waits for the user to respond on a new turn (#852).
+            resetToolCallLoopGuard();
+            if (ctx) {
+                await maybePauseAutoForApprovalGate(ctx, pi, true, "Depth confirmation timed out waiting for a response — pausing auto-mode. Reply to resume.");
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: formatTimedOutAskUserQuestionsGateMessage(gateResult.pendingGateId),
+                    }],
+            };
+        }
+        if (gateResult.status === "verified") {
+            clearDeferredApprovalGate(basePath);
+        }
+        // ── Consent Question policy (consent-question.ts): one home for the
+        // answer lifecycle of every ask_user_questions round. Per-question
+        // verdicts come from the consent-verdict leaf — the same engine
+        // applyAskUserQuestionsGateResult consumed above for gate persistence —
+        // so empty answers on fail-closed kinds never pass as real answers (#528)
+        // and cancellations get one unified handler.
+        const roundOutcome = evaluateAskUserQuestionsRound(questions, details ?? {});
+        if (roundOutcome === "cancelled") {
+            resetToolCallLoopGuard();
+            if (ctx) {
+                await maybePauseAutoForApprovalGate(ctx, pi, true, "ask_user_questions was cancelled before receiving a response — pausing auto-mode until you respond.");
+            }
+            return;
+        }
+        if (roundOutcome === "timeout") {
+            // Non-gate (consent/decision) question timed out at the host elicitation.
+            // Same policy as the gate-timeout branch above: reset the loop guard and
+            // pause-and-wait so the model does not re-ask into the same timeout (#852).
+            resetToolCallLoopGuard();
+            if (ctx) {
+                await maybePauseAutoForApprovalGate(ctx, pi, true, "A user question timed out waiting for a response — pausing auto-mode. Reply to resume.");
             }
+            return;
         }
-        if (details?.cancelled || !details?.response)
+        if (roundOutcome === "waiting") {
+            resetToolCallLoopGuard();
+            if (ctx) {
+                await maybePauseAutoForApprovalGate(ctx, pi, true, "A user question received no answer — pausing auto-mode until you respond.");
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: formatUnansweredConsentQuestionMessage(questions),
+                    }],
+            };
+        }
+        // Cancelled rounds already returned via roundOutcome === "cancelled".
+        if (!details?.response)
             return;
+        // Destructive-command confirmation: an affirmative answer to a
+        // destructive_confirm gate promotes the pending blocked command to a
+        // one-shot confirmed token, which the bash tool_call guard consumes on the
+        // next attempt. Rejecting/declining leaves the command blocked.
+        // (Depth-verification gate handling now lives in
+        // applyAskUserQuestionsGateResult above; only the destructive-confirm gate
+        // is handled inline here.)
         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.
+            if (isDestructiveConfirmGateId(question?.id)) {
                 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);
+                    confirmDestructiveCommand(basePath);
                 }
                 break;
             }
@@ -1146,20 +1394,48 @@ export function registerHooks(pi, ecosystemHandlers) {
             return;
         await saveDiscussionQuestionRound(basePath, milestoneId, questions, details);
     });
+    // Engine hook contract: tool_execution_start is UNIVERSAL_TOOL_HOOKS — the
+    // only pre-execution event that fires for every tool call on every engine.
+    // Universal mirrors live here: write-gate arming and evidence collection.
     pi.on("tool_execution_start", async (event, ctx) => {
         const basePath = contextBasePath(ctx);
         const toolName = canonicalToolName(event.toolName);
         if (toolName === "ask_user_questions") {
             const questionId = extractGateQuestionId(event.args);
             if (typeof questionId === "string") {
-                setPendingGate(questionId, basePath);
+                // External engines (claude-code-cli) ingest the SDK turn's tool blocks
+                // post-hoc, so this event can fire AFTER the workflow MCP child already
+                // verified this gate and allowed the CONTEXT save. Arming also revokes
+                // verifiedDepthMilestones/verifiedApprovalGates, so an unconditional
+                // re-arm here would wipe the child's verification and leave the
+                // discuss→auto handoff permanently blocked. hostWriteGateAdapter
+                // .setPending applies the verified-on-disk-wins policy and skips the
+                // re-arm in that case. Stale verified state cannot leak into a later
+                // re-discussion: a successful handoff deletes the snapshot via
+                // clearDiscussionFlowState.
+                hostWriteGateAdapter.setPending(questionId, basePath);
                 clearDeferredApprovalGate(basePath);
             }
         }
+        // Safety harness: record evidence here, not only in tool_call — see
+        // ../engine-hook-contract.ts for why tool_call never fires under external
+        // engines. recordToolCall dedupes by toolCallId, so native tools (which
+        // hit both events) record once.
+        safetyRecordToolCall(event.toolCallId, event.toolName, (event.args ?? {}));
+        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);
     });
+    // Engine hook contract: tool_execution_end is UNIVERSAL_TOOL_HOOKS — fires
+    // for every finalized tool call on every engine, so error classification
+    // and evidence persistence here cover external engines that skip tool_result.
     pi.on("tool_execution_end", async (event) => {
         markToolEnd(event.toolCallId);
         // #2883/#4974: Capture deterministic invocation/policy errors
@@ -1196,61 +1472,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: "..." }
@@ -1280,18 +1505,38 @@ export function registerHooks(pi, ecosystemHandlers) {
             return surfaceReduced ? { toolNames: providerCompatible } : undefined;
         }
         const registeredToolNames = resolveRegisteredToolNames(pi, event.activeToolNames);
+        const hasRegisteredSurface = typeof pi.getAllTools === "function";
         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, hasRegisteredSurface);
         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, hasRegisteredSurface);
+            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()) {