@opengsd/gsd-pi 1.2.0-dev.fb12b103 → 1.2.0-dev.fbdca60b

package/dist/resources/extensions/gsd/bootstrap/agent-end-recovery.js

@@ -2,7 +2,7 @@
 import { logWarning } from "../workflow-logger.js";
 import { checkDeepProjectSetupAfterTurn, checkAutoStartAfterDiscuss, maybeHandleReadyPhraseWithoutFiles, maybeHandleEmptyIntentTurn, resetEmptyTurnCounter, } from "../guided-flow.js";
 import { clearPathCache } from "../paths.js";
-import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, isAutoCompletionStopInProgress, pauseAuto, setCurrentDispatchedModelId, } from "../auto.js";
+import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, isAutoCompletionStopInProgress, pauseAuto, setCurrentDispatchedModelId, setCurrentUnitModelForRecovery, } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
 import { isSessionSwitchAbortGraceActive, isSessionSwitchInFlight, resolveAgentEnd, resolveAgentEndCancelled, } from "../auto/resolve.js";
@@ -13,7 +13,7 @@ import { clearDiscussionFlowState } from "./write-gate.js";
 import { clearGuidedUnitContext } from "../guided-unit-context.js";
 import { resumeAutoAfterProviderDelay } from "./provider-error-resume.js";
 import { classifyError, createRetryState, resetRetryState, isTransient, } from "../error-classifier.js";
-import { blockModel, isModelBlocked } from "../blocked-models.js";
+import { blockModel, blockModelUntil, isModelBlocked, isModelTemporarilyUnavailable } from "../blocked-models.js";
 import { getProjectGSDPreferencesPath } from "../preferences.js";
 import { resolveProviderErrorGuidance } from "../provider-error-guidance.js";
 import { formatGuidance } from "../guidance.js";
@@ -96,9 +96,12 @@ async function tryProviderModelFallback(params) {
             if (!nextModelId)
                 break;
             const candidate = resolveModelId(nextModelId, availableModels, rejectedProvider);
-            if (candidate && !isModelBlocked(basePath, candidate.provider, candidate.id)) {
+            if (candidate &&
+                !isModelBlocked(basePath, candidate.provider, candidate.id) &&
+                !isModelTemporarilyUnavailable(basePath, candidate.provider, candidate.id)) {
                 const ok = await pi.setModel(candidate, { persist: false });
                 if (ok) {
+                    setCurrentUnitModelForRecovery(candidate);
                     setCurrentDispatchedModelId({ provider: candidate.provider, id: candidate.id });
                     switchedNotify(`${candidate.provider}/${candidate.id}`);
                     pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
@@ -111,11 +114,13 @@ async function tryProviderModelFallback(params) {
     const sessionModel = getAutoModeStartModel();
     if (sessionModel &&
         !(sessionModel.provider === rejectedProvider && sessionModel.id === rejectedId) &&
-        !isModelBlocked(basePath, sessionModel.provider, sessionModel.id)) {
+        !isModelBlocked(basePath, sessionModel.provider, sessionModel.id) &&
+        !isModelTemporarilyUnavailable(basePath, sessionModel.provider, sessionModel.id)) {
         const startModel = availableModels.find((m) => m.provider === sessionModel.provider && m.id === sessionModel.id);
         if (startModel) {
             const ok = await pi.setModel(startModel, { persist: false });
             if (ok) {
+                setCurrentUnitModelForRecovery(startModel);
                 setCurrentDispatchedModelId({ provider: startModel.provider, id: startModel.id });
                 switchedNotify(`${startModel.provider}/${startModel.id}`);
                 pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
@@ -533,6 +538,10 @@ export async function handleAgentEnd(pi, event, ctx) {
             if (currentProvider === "openai-codex" || currentProvider === "google-gemini-cli") {
                 cls.retryAfterMs = Math.min(cls.retryAfterMs, 30_000);
             }
+            const dash = getAutoDashboardData();
+            if (dash.basePath && ctx.model?.provider && ctx.model?.id) {
+                blockModelUntil(dash.basePath, ctx.model.provider, ctx.model.id, Date.now() + cls.retryAfterMs, rawErrorMsg || displayMsg || "rate limit");
+            }
         }
         // ── 2. Decide & Act ──────────────────────────────────────────────────
         // --- Network errors: same-model retry with backoff ---
@@ -572,9 +581,14 @@ export async function handleAgentEnd(pi, event, ctx) {
                         retryState.networkRetryCount = 0;
                         retryState.currentRetryModelId = undefined;
                         const modelToSet = resolveModelId(nextModelId, availableModels, ctx.model?.provider);
-                        if (modelToSet) {
+                        const modelUnavailable = dash.basePath && modelToSet
+                            ? isModelBlocked(dash.basePath, modelToSet.provider, modelToSet.id) ||
+                                isModelTemporarilyUnavailable(dash.basePath, modelToSet.provider, modelToSet.id)
+                            : false;
+                        if (modelToSet && !modelUnavailable) {
                             const ok = await pi.setModel(modelToSet, { persist: false });
                             if (ok) {
+                                setCurrentUnitModelForRecovery(modelToSet);
                                 setCurrentDispatchedModelId({ provider: modelToSet.provider, id: modelToSet.id });
                                 ctx.ui.notify(`Model error${errorDetail}. Switched to fallback: ${nextModelId} and resuming.`, "warning");
                                 pi.sendMessage({ customType: "gsd-auto-timeout-recovery", content: "Continue execution.", display: false }, { triggerTurn: true });
@@ -587,11 +601,17 @@ export async function handleAgentEnd(pi, event, ctx) {
             // Try restoring session model
             const sessionModel = getAutoModeStartModel();
             if (sessionModel) {
-                if (ctx.model?.id !== sessionModel.id || ctx.model?.provider !== sessionModel.provider) {
+                const dash = getAutoDashboardData();
+                const sessionModelUnavailable = dash.basePath
+                    ? isModelBlocked(dash.basePath, sessionModel.provider, sessionModel.id) ||
+                        isModelTemporarilyUnavailable(dash.basePath, sessionModel.provider, sessionModel.id)
+                    : false;
+                if (!sessionModelUnavailable && (ctx.model?.id !== sessionModel.id || ctx.model?.provider !== sessionModel.provider)) {
                     const startModel = ctx.modelRegistry.getAvailable().find((m) => m.provider === sessionModel.provider && m.id === sessionModel.id);
                     if (startModel) {
                         const ok = await pi.setModel(startModel, { persist: false });
                         if (ok) {
+                            setCurrentUnitModelForRecovery(startModel);
                             setCurrentDispatchedModelId({ provider: startModel.provider, id: startModel.id });
                             retryState.networkRetryCount = 0;
                             retryState.currentRetryModelId = undefined;

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

@@ -5,7 +5,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent";
 import { logWarning } from "../workflow-logger.js";
-import { openWorkflowDatabase } from "../db-workspace.js";
+import { getWorkflowDatabaseStatus, openWorkflowDatabase, } from "../db-workspace.js";
 import { getAutoWorktreePath } from "../auto-worktree.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { worktreesDirs } from "../worktree-placement.js";
@@ -61,16 +61,46 @@ export function resolveWorkflowToolBasePath(ctx, scope) {
     return cwd;
 }
 export { resolveProjectRootDbPath } from "../db-workspace.js";
+function sqliteProviderHint(status, nodeVersion) {
+    if (status.provider)
+        return `Provider: ${status.provider}.`;
+    const major = Number.parseInt(nodeVersion.split(".")[0] ?? "", 10);
+    if (Number.isFinite(major) && major < 22) {
+        return (`No SQLite provider available. Upgrade Node to >= 22.0.0 (current: v${nodeVersion}), ` +
+            "use the packaged GSD runtime, or install/restore better-sqlite3 in this runtime.");
+    }
+    return ("No SQLite provider available. Use a Node build with node:sqlite enabled, " +
+        "run the packaged GSD runtime, or install/restore better-sqlite3 in this runtime.");
+}
+function dbOpenPhaseHint(status) {
+    if (status.lastPhase === "open")
+        return "The database file could not be opened";
+    if (status.lastPhase === "initSchema")
+        return "The database schema could not be initialized";
+    if (status.lastPhase === "vacuum-recovery")
+        return "Corruption recovery (VACUUM) failed";
+    if (status.attempted)
+        return "The database could not be opened";
+    return "The database provider could not be loaded";
+}
+export function formatWorkflowDatabaseOpenFailure(result, status, nodeVersion = process.versions.node) {
+    if (result.reason === "missing-gsd-dir") {
+        return `ensureDbOpen failed — no .gsd directory found at ${result.location.projectGsd}`;
+    }
+    if (result.reason === "missing-database") {
+        return `ensureDbOpen failed — no GSD database found at ${result.location.projectDb}`;
+    }
+    const resolvedStatus = status ?? getWorkflowDatabaseStatus();
+    const detail = result.error?.message ?? resolvedStatus.lastError?.message ?? "";
+    const detailSuffix = detail ? ` (${detail})` : "";
+    return (`ensureDbOpen failed for ${result.location.projectDb}: ` +
+        `${dbOpenPhaseHint(resolvedStatus)}${detailSuffix}. ${sqliteProviderHint(resolvedStatus, nodeVersion)}`);
+}
 export async function ensureDbOpen(basePath = safeWorkspaceCwd()) {
     const result = openWorkflowDatabase(basePath);
     if (result.ok)
         return true;
-    if (result.reason === "missing-gsd-dir") {
-        logWarning("bootstrap", "ensureDbOpen failed — no .gsd directory found");
-    }
-    else {
-        logWarning("bootstrap", `ensureDbOpen failed: ${result.error?.message ?? "open failed"}`);
-    }
+    logWarning("bootstrap", formatWorkflowDatabaseOpenFailure(result));
     return false;
 }
 export function registerDynamicTools(pi) {

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

@@ -114,8 +114,8 @@ export function registerExecTools(pi) {
         ],
         parameters: Type.Object({
             query: Type.Optional(Type.String({ description: "Substring matched against id and purpose (case-insensitive)." })),
-            runtime: Type.Optional(Type.Union([Type.Literal("bash"), Type.Literal("node"), Type.Literal("python")], {
-                description: "Restrict to one runtime.",
+            runtime: Type.Optional(Type.String({
+                description: "Restrict to one runtime: bash, node, or python.",
             })),
             failing_only: Type.Optional(Type.Boolean({ description: "Only non-zero exit codes and timeouts." })),
             limit: Type.Optional(Type.Number({ description: "Max results (default 20, cap 200)", minimum: 1, maximum: 200 })),

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, isDepthConfirmationAnswer, 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";
@@ -28,7 +29,7 @@ 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";
@@ -109,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",
@@ -408,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();
@@ -463,17 +482,14 @@ function isShellExecutionTool(canonicalName) {
         canonicalName === "powershell";
 }
 function activateDeferredApprovalGate(basePath) {
-    if (deferredApprovalGate?.basePath !== basePath)
-        return;
-    const gateId = deferredApprovalGate.gateId;
-    deferredApprovalGate = null;
-    const snapshot = refreshWriteGateStateFromDisk(basePath);
-    const milestoneId = extractDepthVerificationMilestoneId(gateId);
-    if (isApprovalGateVerifiedInSnapshot(snapshot, gateId))
+    const gateId = deferredApprovalGates.get(basePath);
+    if (gateId === undefined)
         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 ?? [];
@@ -482,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")
@@ -589,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 };
@@ -598,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(" "),
@@ -714,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) => {
@@ -919,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) {
@@ -933,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.
@@ -959,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);
@@ -1093,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);
@@ -1144,6 +1175,11 @@ export function registerHooks(pi, ecosystemHandlers) {
             }
         }
     });
+    // 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);
@@ -1219,7 +1255,34 @@ 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
@@ -1241,6 +1304,9 @@ 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);
@@ -1249,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") {
@@ -1284,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