@opengsd/gsd-pi 1.2.0-dev.5457a158 → 1.2.0-dev.822c9439

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

@@ -13,7 +13,8 @@ import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-exten
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
 
 import { buildMilestoneFileName, clearPathCache, milestonesDir, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { applyAskUserQuestionsGateResult, canonicalToolName, clearDiscussionFlowState, formatPendingAskUserQuestionsGateMessage, isApprovalGateVerifiedInSnapshot, isMilestoneDepthVerified, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, loadWriteGateSnapshot, markApprovalGateVerified, markDepthVerified, refreshWriteGateStateFromDisk, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeWrite, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { 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";
@@ -39,6 +40,12 @@ 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";
@@ -49,29 +56,28 @@ import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { extractSubagentAgentClasses } from "./subagent-input.js";
 import {
   approvalGateIdForUnit,
+  evaluateAskUserQuestionsRound,
+  formatUnansweredConsentQuestionMessage,
   isExplicitApprovalResponse,
   messageHasPendingAskUserQuestionsTool,
-  shouldPauseForUserApprovalQuestion,
-} from "../user-input-boundary.js";
+  shouldPauseForQuestion,
+} from "../consent-question.js";
 import { resolveSkillManifest } from "../skill-manifest.js";
 import { applyUnitSkillVisibility, unitHasSkillManifest } from "../skill-scope.js";
 import { getGuidedUnitContext } from "../guided-unit-context.js";
 import { registerPlanMilestoneSchemaRecovery } from "./plan-milestone-schema-recovery.js";
 import { AUTO_UNIT_SCOPED_TOOLS, RUN_UAT_BROWSER_TOOL_NAMES, 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;
 
-interface DeferredApprovalGate {
-  gateId: string;
-  basePath: string;
-}
-
 type WelcomeScreenModule = {
   buildWelcomeScreenLines(opts: { version: string; remoteChannel?: string; width?: number }): string[];
 };
@@ -142,7 +148,13 @@ async function installWelcomeHeader(ctx: ExtensionContext): Promise<void> {
   }
 }
 
-let deferredApprovalGate: DeferredApprovalGate | null = 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<string, string>();
 
 export const MINIMAL_GSD_TOOL_NAMES = [
   "gsd_exec",
@@ -180,7 +192,7 @@ function withPreservedShimTools(toolNames: readonly string[]): string[] {
 
 /** True for the browser automation tools (browser_navigate, browser_click, ...). */
 function isBrowserTool(toolName: string): boolean {
-  return canonicalToolName(toolName).startsWith("browser_");
+  return hasBrowserContractPrefix(canonicalToolName(toolName));
 }
 
 /**
@@ -261,6 +273,7 @@ export function buildMinimalAutoGsdToolSet(
   activeToolNames: readonly string[],
   unitType: string | undefined,
   registeredToolNames: readonly string[] = activeToolNames,
+  warnOnUnresolvedRequiredTools = registeredToolNames !== activeToolNames,
 ): string[] {
   if (unitType === "run-uat") {
     return buildRunUatGsdToolSet(activeToolNames, registeredToolNames);
@@ -276,7 +289,36 @@ export function buildMinimalAutoGsdToolSet(
     [...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: readonly string[],
+  requiredToolName: string,
+): boolean {
+  return resolvedToolNames.some(
+    (name) => name === requiredToolName || mcpToolMatchesBaseName(name, requiredToolName),
+  );
+}
+
+function warnIfRequiredWorkflowToolsUnresolved(
+  unitType: string | undefined,
+  scopedToolNames: readonly string[],
+  shouldWarn: boolean,
+): void {
+  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(
@@ -329,6 +371,7 @@ export function buildRequestScopedGsdToolSet(
   requestCustomMessages: readonly { customType?: string }[] | undefined,
   registeredToolNames: readonly string[] = activeToolNames,
   guidedUnitType?: string,
+  warnOnUnresolvedRequiredTools = registeredToolNames !== activeToolNames,
 ): string[] | undefined {
   for (let index = (requestCustomMessages?.length ?? 0) - 1; index >= 0; index--) {
     const currentCustomType = requestCustomMessages?.[index]?.customType;
@@ -339,7 +382,12 @@ export function buildRequestScopedGsdToolSet(
       currentCustomType === "gsd-triage"
     ) {
       if (guidedUnitType) {
-        return buildMinimalAutoGsdToolSet(activeToolNames, guidedUnitType, registeredToolNames);
+        return buildMinimalAutoGsdToolSet(
+          activeToolNames,
+          guidedUnitType,
+          registeredToolNames,
+          warnOnUnresolvedRequiredTools,
+        );
       }
       return buildMinimalGsdWorkflowToolSet(activeToolNames, registeredToolNames);
     }
@@ -388,11 +436,13 @@ function applyMinimalGsdToolSurface(pi: ExtensionAPI): void {
   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,
+      hasRegisteredSurface,
     );
     recordAutoToolSurfaceSnapshot({
       source: "runtime-scope",
@@ -414,9 +464,10 @@ export function scopeGsdWorkflowToolsForDispatch(
 ): ScopedGsdWorkflowState | null {
   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",
@@ -511,13 +562,22 @@ async function applyCompactionThresholdOverride(ctx: ExtensionContext): Promise<
 }
 
 function clearDeferredApprovalGate(basePath?: string): void {
-  if (!basePath || deferredApprovalGate?.basePath === basePath) {
-    deferredApprovalGate = null;
+  if (!basePath) {
+    deferredApprovalGates.clear();
+  } else {
+    deferredApprovalGates.delete(basePath);
   }
 }
 
 function deferApprovalGate(gateId: string, basePath: string): void {
-  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?: { cwd?: string }): string {
@@ -574,14 +634,13 @@ function isShellExecutionTool(canonicalName: string): boolean {
 }
 
 function activateDeferredApprovalGate(basePath: string): void {
-  if (deferredApprovalGate?.basePath !== basePath) 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);
+  const gateId = deferredApprovalGates.get(basePath);
+  if (gateId === undefined) return;
+  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: unknown): string | undefined {
@@ -592,7 +651,7 @@ function extractGateQuestionId(input: unknown): string | undefined {
 
 function isApprovalGateBlocking(basePath: string): boolean {
   return Boolean(getPendingGate(basePath))
-    || (deferredApprovalGate?.basePath === basePath);
+    || deferredApprovalGates.has(basePath);
 }
 
 function isContextDraftSummarySave(toolName: string, input: unknown): boolean {
@@ -737,13 +796,14 @@ function shouldBlockDeferredApprovalTool(
   input: unknown,
   basePath: string,
 ): { block: boolean; reason?: string; displayReason?: string } {
-  if (deferredApprovalGate?.basePath !== basePath) return { block: false };
+  const deferredGateId = deferredApprovalGates.get(basePath);
+  if (deferredGateId === undefined) return { block: false };
   if (toolName === "ask_user_questions") return { block: false };
   if (isContextDraftSummarySave(toolName, input)) return { block: false };
   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(" "),
@@ -873,10 +933,12 @@ export function registerHooks(
     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);
+      if (milestoneId) hostWriteGateAdapter.markDepthVerified(milestoneId, beforeAgentBasePath);
+      hostWriteGateAdapter.clearPending(beforeAgentBasePath);
       if (isAutoPaused() && !isAutoActive()) {
         const { resumeAutoAfterProviderDelay } = await import("./provider-error-resume.js");
         void resumeAutoAfterProviderDelay(pi, ctx).catch((err) => {
@@ -1100,7 +1162,7 @@ export function registerHooks(
       }
     }
 
-    if (!shouldPauseForUserApprovalQuestion(unitType, [event.message])) return;
+    if (!shouldPauseForQuestion(unitType, [event.message])) return;
 
     const gateId = approvalGateIdForUnit(unitType, unitId);
     if (gateId) {
@@ -1115,7 +1177,7 @@ export function registerHooks(
 
     approvalQuestionAbortInFlight = true;
     ctx.ui.notify(
-      `${unitType}${unitId ? ` ${unitId}` : ""} is waiting for your approval - pausing before more tool calls run.`,
+      `${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
@@ -1143,6 +1205,13 @@ export function registerHooks(
     }
   });
 
+  // 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);
@@ -1330,6 +1399,11 @@ export function registerHooks(
   });
 
   // ── 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 as Record<string, unknown>);
@@ -1349,23 +1423,39 @@ export function registerHooks(
 
     // 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.",
+            "Destructive-command confirmation is waiting for your answer — pausing auto-mode.",
           );
         }
         return { block: true, reason };
@@ -1373,6 +1463,11 @@ export function registerHooks(
     }
   });
 
+  // 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);
@@ -1453,11 +1548,70 @@ export function registerHooks(
       clearDeferredApprovalGate(basePath);
     }
 
-    if (details?.cancelled || !details?.response) return;
+    // ── 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" as const,
+          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);
@@ -1466,31 +1620,23 @@ export function registerHooks(
       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 ?? {}) as Record<string, unknown>);
     const execDash = getAutoRuntimeSnapshot();
     if (execDash.basePath && execDash.currentUnit?.type === "execute-task") {
@@ -1504,6 +1650,9 @@ export function registerHooks(
     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
@@ -1580,6 +1729,7 @@ export function registerHooks(
       return surfaceReduced ? { toolNames: providerCompatible } : undefined;
     }
     const registeredToolNames = resolveRegisteredToolNames(pi, event.activeToolNames);
+    const hasRegisteredSurface = typeof pi.getAllTools === "function";
     const compatibleRegisteredToolNames = filterToolsForProvider(
       registeredToolNames,
       event.selectedModelApi,
@@ -1594,6 +1744,7 @@ export function registerHooks(
       event.requestCustomMessages,
       requestRegisteredToolNames,
       guidedUnit?.unitType,
+      hasRegisteredSurface,
     );
     if (requestScoped) {
       recordAutoToolSurfaceSnapshot({
@@ -1614,6 +1765,7 @@ export function registerHooks(
         dash.currentUnit.type === "run-uat" ? aliasFilteredCompatible : providerCompatible,
         dash.currentUnit.type,
         registeredForUnit,
+        hasRegisteredSurface,
       );
       recordAutoToolSurfaceSnapshot({
         source: "provider-adjustment",