@opengsd/gsd-pi 1.2.0-dev.5457a158 → 1.2.0-dev.6ccd27b3

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

@@ -7,7 +7,8 @@ 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 { applyAskUserQuestionsGateResult, canonicalToolName, clearDiscussionFlowState, formatPendingAskUserQuestionsGateMessage, isApprovalGateVerifiedInSnapshot, isMilestoneDepthVerified, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, refreshWriteGateStateFromDisk, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeWrite, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { applyAskUserQuestionsGateResult, clearDiscussionFlowState, formatPendingAskUserQuestionsGateMessage, hostWriteGateAdapter, isApprovalGateVerifiedInSnapshot, isDepthConfirmationAnswer, isMilestoneDepthVerified, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, 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";
@@ -19,6 +20,7 @@ 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 { confirmDestructiveCommand, consumeDestructiveConfirmation, isDestructiveConfirmGateId, requestDestructiveConfirmation, } from "../safety/destructive-confirmation.js";
 import { logWarning as safetyLogWarning } from "../workflow-logger.js";
 import { isUnitCloseoutTool, runInteractiveUnitCloseout } from "../unit-closeout.js";
 import { installNotifyInterceptor } from "./notify-interceptor.js";
@@ -27,17 +29,19 @@ 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, messageHasPendingAskUserQuestionsTool, 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, 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 { 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 = [];
@@ -106,7 +110,13 @@ async function installWelcomeHeader(ctx) {
         /* non-fatal */
     }
 }
-let deferredApprovalGate = null;
+/**
+ * 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",
@@ -140,7 +150,7 @@ function withPreservedShimTools(toolNames) {
 }
 /** 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
@@ -202,7 +212,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);
     }
@@ -214,7 +224,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], [
@@ -240,7 +263,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" ||
@@ -248,7 +271,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);
         }
@@ -282,8 +305,9 @@ function applyMinimalGsdToolSurface(pi) {
     const dash = getAutoRuntimeSnapshot();
     if (dash.active && dash.currentUnit) {
         const currentToolNames = pi.getActiveTools();
+        const hasRegisteredSurface = typeof pi.getAllTools === "function";
         const registeredToolNames = resolveRegisteredToolNames(pi, currentToolNames);
-        const scopedToolNames = buildMinimalAutoGsdToolSet(currentToolNames, dash.currentUnit.type, registeredToolNames);
+        const scopedToolNames = buildMinimalAutoGsdToolSet(currentToolNames, dash.currentUnit.type, registeredToolNames, hasRegisteredSurface);
         recordAutoToolSurfaceSnapshot({
             source: "runtime-scope",
             unitType: dash.currentUnit.type,
@@ -302,9 +326,10 @@ 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",
@@ -390,12 +415,24 @@ 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);
+    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();
@@ -445,17 +482,14 @@ function isShellExecutionTool(canonicalName) {
         canonicalName === "powershell";
 }
 function activateDeferredApprovalGate(basePath) {
-    if (deferredApprovalGate?.basePath !== basePath)
+    const gateId = deferredApprovalGates.get(basePath);
+    if (gateId === undefined)
         return;
-    const gateId = deferredApprovalGate.gateId;
-    deferredApprovalGate = null;
-    const snapshot = refreshWriteGateStateFromDisk(basePath);
-    const milestoneId = extractDepthVerificationMilestoneId(gateId);
-    if (isApprovalGateVerifiedInSnapshot(snapshot, gateId))
-        return;
-    if (milestoneId && isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId))
-        return;
-    setPendingGate(gateId, basePath);
+    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 ?? [];
@@ -464,7 +498,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")
@@ -571,7 +605,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 };
@@ -580,7 +615,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(" "),
@@ -696,11 +731,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) => {
@@ -901,7 +938,7 @@ 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) {
@@ -915,7 +952,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             deferApprovalGate(gateId, contextBasePath(ctx));
         }
         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.
@@ -941,6 +978,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);
@@ -1075,6 +1119,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);
@@ -1092,24 +1141,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);
@@ -1185,12 +1255,58 @@ export function registerHooks(pi, ecosystemHandlers) {
         if (gateResult.status === "verified") {
             clearDeferredApprovalGate(basePath);
         }
-        if (details?.cancelled || !details?.response)
+        // ── 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 === "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 (isDestructiveConfirmGateId(question?.id)) {
+                const answer = details.response?.answers?.[question.id];
+                if (isDepthConfirmationAnswer(answer?.selected, question.options)) {
+                    confirmDestructiveCommand(basePath);
+                }
+                break;
+            }
+        }
         if (!milestoneId)
             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);
@@ -1199,29 +1315,22 @@ export function registerHooks(pi, ecosystemHandlers) {
             if (typeof questionId === "string") {
                 // 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. setPendingGate also
-                // revokes verifiedDepthMilestones/verifiedApprovalGates, so an
-                // unconditional re-arm here wipes the child's verification and leaves
-                // the discuss→auto handoff permanently blocked. Skip the re-arm when
-                // the snapshot already records this exact gate as verified — mirrors
-                // activateDeferredApprovalGate's guard. Stale verified state cannot
-                // leak into a later re-discussion: a successful handoff deletes the
-                // snapshot via clearDiscussionFlowState.
-                const snapshot = refreshWriteGateStateFromDisk(basePath);
-                const gateMilestoneId = extractDepthVerificationMilestoneId(questionId);
-                const alreadyVerified = isApprovalGateVerifiedInSnapshot(snapshot, questionId) ||
-                    isMilestoneDepthVerifiedInSnapshot(snapshot, gateMilestoneId);
-                if (!alreadyVerified) {
-                    setPendingGate(questionId, basePath);
-                }
+                // 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. External
-        // engines (claude-code-cli) pre-execute tools, so the agent loop skips
-        // beforeToolCall/tool_call for them — tool_execution_start is the only
-        // event that fires for every tool call. recordToolCall dedupes by
-        // toolCallId, so native tools (which hit both events) record once.
+        // 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") {
@@ -1234,6 +1343,9 @@ export function registerHooks(pi, ecosystemHandlers) {
             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
@@ -1303,12 +1415,13 @@ 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 requestRegisteredToolNames = guidedUnit?.unitType === "run-uat"
             ? compatibleRegisteredToolNames
             : registeredToolNames;
-        const requestScoped = buildRequestScopedGsdToolSet(guidedUnit?.unitType === "run-uat" ? aliasFilteredCompatible : providerCompatible, event.requestCustomMessages, requestRegisteredToolNames, guidedUnit?.unitType);
+        const requestScoped = buildRequestScopedGsdToolSet(guidedUnit?.unitType === "run-uat" ? aliasFilteredCompatible : providerCompatible, event.requestCustomMessages, requestRegisteredToolNames, guidedUnit?.unitType, hasRegisteredSurface);
         if (requestScoped) {
             recordAutoToolSurfaceSnapshot({
                 source: "provider-adjustment",
@@ -1324,7 +1437,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             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);
+            const scopedToolNames = buildMinimalAutoGsdToolSet(dash.currentUnit.type === "run-uat" ? aliasFilteredCompatible : providerCompatible, dash.currentUnit.type, registeredForUnit, hasRegisteredSurface);
             recordAutoToolSurfaceSnapshot({
                 source: "provider-adjustment",
                 unitType: dash.currentUnit.type,