gsd-pi 2.80.0-dev.e146beb20 → 2.80.0-dev.e6c48c3af

package/src/resources/extensions/gsd/auto-direct-dispatch.ts

@@ -306,7 +306,7 @@ export async function dispatchDirectPhase(
       return;
     }
 
-    const result = await ctx.newSession();
+    const result = await ctx.newSession({ cwd: dispatchBase });
     if (result.cancelled) {
       ctx.ui.notify("Session creation cancelled.", "warning");
       return;

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -35,6 +35,7 @@ import {
 import { formatDecisionsCompact, formatRequirementsCompact } from "./structured-data-formatter.js";
 import { readPhaseAnchor, formatAnchorForPrompt } from "./phase-anchor.js";
 import { composeContextModeInstructions, composeInlinedContext, type ArtifactResolver, type ContextModeRenderMode } from "./unit-context-composer.js";
+import { readCompactionSnapshot } from "./compaction-snapshot.js";
 import { logWarning } from "./workflow-logger.js";
 import { inlineGraphSubgraph } from "./graph-context.js";
 import { buildExtractionStepsBlock } from "./commands-extract-learnings.js";
@@ -205,13 +206,28 @@ function renderContextModeForPrompt(
   });
 }
 
+function renderContextModeBlockForPrompt(
+  unitType: string,
+  base: string,
+  renderMode: ContextModeRenderMode = "standalone",
+): string {
+  const contextMode = renderContextModeForPrompt(unitType, base, renderMode);
+  if (!contextMode) return "";
+  if (renderMode === "nested") return contextMode;
+
+  const snapshot = readCompactionSnapshot(base);
+  if (!snapshot?.trim()) return contextMode;
+
+  return `${contextMode}\n\n## Context Snapshot\nSource: \`.gsd/last-snapshot.md\`\n\n${snapshot.trimEnd()}`;
+}
+
 function prependContextModeToBlock(
   unitType: string,
   base: string,
   block: string,
   renderMode: ContextModeRenderMode = "standalone",
 ): string {
-  const contextMode = renderContextModeForPrompt(unitType, base, renderMode);
+  const contextMode = renderContextModeBlockForPrompt(unitType, base, renderMode);
   if (!contextMode) return block;
   if (!block.trim()) return contextMode;
   return `${contextMode}\n\n${block}`;

package/src/resources/extensions/gsd/auto-recovery.ts

@@ -67,6 +67,60 @@ export {
 
 // ─── Artifact Resolution & Verification ───────────────────────────────────────
 
+export type ArtifactRecoveryDbRefreshResult =
+  | { ok: true }
+  | { ok: false; fatal: boolean; message: string; reason: string };
+
+export function refreshRecoveryDbForArtifact(
+  unitType: string,
+  unitId: string,
+): ArtifactRecoveryDbRefreshResult {
+  if (unitType !== "plan-slice" && unitType !== "execute-task") return { ok: true };
+  if (!isDbAvailable()) return { ok: true };
+
+  if (!refreshOpenDatabaseFromDisk()) {
+    return {
+      ok: false,
+      fatal: unitType === "execute-task",
+      reason: `${unitType}-db-refresh-failed`,
+      message: `Stuck recovery found ${unitType} ${unitId} artifacts, but the DB refresh failed.`,
+    };
+  }
+
+  if (unitType !== "execute-task") return { ok: true };
+
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
+  if (!mid || !sid || !tid) {
+    return {
+      ok: false,
+      fatal: true,
+      reason: "execute-task-invalid-unit-id",
+      message: `Stuck recovery found execute-task ${unitId} artifacts, but the unit id could not be parsed for DB verification.`,
+    };
+  }
+
+  const task = getTask(mid, sid, tid);
+  if (!task) {
+    return {
+      ok: false,
+      fatal: true,
+      reason: "execute-task-artifact-db-missing",
+      message: `Stuck recovery found execute-task ${unitId} artifacts, but no matching DB task row exists after refresh.`,
+    };
+  }
+
+  if (!isClosedStatus(task.status)) {
+    return {
+      ok: false,
+      fatal: true,
+      reason: "execute-task-artifact-db-mismatch",
+      message: `Stuck recovery found execute-task ${unitId} artifacts, but the DB task status is still '${task.status}' after refresh.`,
+    };
+  }
+
+  return { ok: true };
+}
+
 function hasCapturedWorkflowPrefs(base: string): boolean {
   const prefsPath = resolveExpectedArtifactPath("workflow-preferences", "WORKFLOW-PREFS", base);
   if (!prefsPath || !existsSync(prefsPath)) return false;

package/src/resources/extensions/gsd/auto-supervisor.ts

@@ -32,6 +32,7 @@ let _currentSigtermHandler: (() => void) | null = null;
 export function registerSigtermHandler(
   currentBasePath: string,
   previousHandler: (() => void) | null,
+  onSignalCleanup?: () => void,
 ): () => void {
   // Remove the explicitly-passed previous handler
   if (previousHandler) {
@@ -43,6 +44,12 @@ export function registerSigtermHandler(
     for (const sig of CLEANUP_SIGNALS) process.off(sig, _currentSigtermHandler);
   }
   const handler = () => {
+    try {
+      onSignalCleanup?.();
+    } catch {
+      void 0;
+      // Signal cleanup is best-effort; lock cleanup and process exit still run.
+    }
     clearLock(currentBasePath);
     releaseSessionLock(currentBasePath);
     process.exit(0);

package/src/resources/extensions/gsd/auto-timeout-recovery.ts

@@ -71,14 +71,14 @@ export async function recoverTimedOutUnit(
       recovery: status,
     });
 
-    const durableComplete = status.summaryExists && status.taskChecked && status.nextActionAdvanced;
+    const durableComplete = status.dbComplete || (status.summaryExists && status.taskChecked && status.nextActionAdvanced);
     if (durableComplete) {
       writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
         phase: "finalized",
         recovery: status,
       });
       ctx.ui.notify(
-        `${reason === "idle" ? "Idle" : "Timeout"} recovery: ${unitType} ${unitId} already completed on disk. Continuing auto-mode. (attempt ${attemptNumber})`,
+        `${reason === "idle" ? "Idle" : "Timeout"} recovery: ${unitType} ${unitId} already completed. Continuing auto-mode. (attempt ${attemptNumber})`,
         "info",
       );
       unitRecoveryCount.delete(recoveryKey);

package/src/resources/extensions/gsd/auto.ts

@@ -59,6 +59,7 @@ import {
   isLockProcessAlive,
   formatCrashInfo,
   emitCrashRecoveredUnitEnd,
+  emitOpenUnitEndForUnit,
 } from "./crash-recovery.js";
 import {
   acquireSessionLock,
@@ -200,6 +201,8 @@ import {
   detectWorkingTreeActivity,
 } from "./auto-supervisor.js";
 import { isDbAvailable, getMilestone } from "./gsd-db.js";
+import { markLatestActiveForWorkerCanceled } from "./db/unit-dispatches.js";
+import { writeUnitRuntimeRecord } from "./unit-runtime.js";
 import { countPendingCaptures } from "./captures.js";
 import { CMUX_CHANNELS, type CmuxLogLevel } from "../shared/cmux-events.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
@@ -242,6 +245,20 @@ import {
   type WorktreeResolverDeps,
 } from "./worktree-resolver.js";
 import { reorderForCaching } from "./prompt-ordering.js";
+import { initTokenCounter } from "./token-counter.js";
+
+// Warm the tiktoken encoder at extension startup so context-budget computations
+// can use accurate token counts via countTokensSync without paying the load
+// cost mid-prompt-build. Fire-and-forget — failure falls back to the
+// provider-aware char-ratio estimator already used by getCharsPerToken().
+// Catch rejections explicitly: an unhandled rejection at module-import time
+// can destabilize startup before the engine logger is configured.
+void initTokenCounter().catch((err) => {
+  logWarning(
+    "engine",
+    `token counter warm-up failed: ${err instanceof Error ? err.message : String(err)}`,
+  );
+});
 
 // ─── Session State ─────────────────────────────────────────────────────────
 
@@ -293,11 +310,15 @@ const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
  * the DB is unavailable (e.g. fresh project before init) we skip registration
  * silently rather than blocking session start.
  */
-function registerAutoWorkerForSession(session: AutoSession): void {
+function registerAutoWorkerForSession(
+  session: AutoSession,
+  projectRootOverride?: string,
+): void {
   if (session.workerId) return; // already registered (e.g. resume re-runs)
   try {
     const projectRootRealpath = normalizeRealPath(
-      session.scope?.workspace.projectRoot
+      projectRootOverride
+        ?? session.scope?.workspace.projectRoot
         ?? (session.originalBasePath || session.basePath),
     );
     session.workerId = registerAutoWorker({ projectRootRealpath });
@@ -501,9 +522,54 @@ export {
   getBudgetEnforcementAction,
 } from "./auto-budget.js";
 
+function closeOutSignalInterruptedUnit(currentBasePath: string): void {
+  const currentUnit = s.currentUnit;
+  if (!currentUnit) return;
+
+  const reason = "Auto-mode process received a termination signal";
+  const errorContext: ErrorContext = {
+    message: reason,
+    category: "aborted",
+    isTransient: false,
+  };
+  const basePath = s.basePath || currentBasePath;
+
+  try {
+    emitOpenUnitEndForUnit(basePath, currentUnit.type, currentUnit.id, "cancelled", errorContext);
+  } catch (err) {
+    logWarning("engine", `signal unit-end cleanup failed: ${getErrorMessage(err)}`, { file: "auto.ts" });
+  }
+
+  try {
+    writeUnitRuntimeRecord(basePath, currentUnit.type, currentUnit.id, currentUnit.startedAt, {
+      phase: "crashed",
+      lastProgressAt: Date.now(),
+      lastProgressKind: "signal",
+    });
+  } catch (err) {
+    logWarning("engine", `signal runtime cleanup failed: ${getErrorMessage(err)}`, { file: "auto.ts" });
+  }
+
+  try {
+    if (s.workerId) markLatestActiveForWorkerCanceled(s.workerId, "signal-exit");
+  } catch (err) {
+    logWarning("engine", `signal dispatch cleanup failed: ${getErrorMessage(err)}`, { file: "auto.ts" });
+  }
+
+  try {
+    resolveAgentEndCancelled(errorContext);
+  } catch (err) {
+    logWarning("engine", `signal resolve cleanup failed: ${getErrorMessage(err)}`, { file: "auto.ts" });
+  }
+}
+
 /** Wrapper: register SIGTERM handler and store reference. */
 function registerSigtermHandler(currentBasePath: string): void {
-  s.sigtermHandler = _registerSigtermHandler(currentBasePath, s.sigtermHandler);
+  s.sigtermHandler = _registerSigtermHandler(
+    currentBasePath,
+    s.sigtermHandler,
+    () => closeOutSignalInterruptedUnit(currentBasePath),
+  );
 }
 
 /** Wrapper: deregister SIGTERM handler and clear reference. */
@@ -968,6 +1034,8 @@ export async function stopAuto(
       if (s.workerId) {
         markWorkerStopping(s.workerId);
       }
+      s.workerId = null;
+      s.milestoneLeaseToken = null;
     } catch (e) {
       debugLog("stop-cleanup-coordination", { error: e instanceof Error ? e.message : String(e) });
     }
@@ -1105,6 +1173,21 @@ export async function stopAuto(
       debugLog("stop-cleanup-basepath", { error: e instanceof Error ? e.message : String(e) });
     }
 
+    // Re-root the active command session/tool runtime after worktree teardown.
+    // mergeAndExit restores process.cwd(), but AgentSession has already captured
+    // its own cwd for tools and system prompt; refresh it before returning to the
+    // user so follow-up commands do not target a removed milestone worktree.
+    if (s.originalBasePath && ctx && s.cmdCtx) {
+      try {
+        const result = await s.cmdCtx.newSession({ cwd: s.basePath });
+        if (result.cancelled) {
+          logWarning("engine", "post-stop session re-root was cancelled", { file: "auto.ts", basePath: s.basePath });
+        }
+      } catch (err) {
+        logWarning("engine", `post-stop session re-root failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts", basePath: s.basePath });
+      }
+    }
+
     // ── Step 8: Ledger notification ──
     try {
       const ledger = getLedger();
@@ -1971,6 +2054,10 @@ export async function startAuto(
       : new URL("../../../resource-loader.js", import.meta.url).href;
     const { initResources } = await import(resourceLoaderPath);
     initResources(agentDir);
+    // initResources() uses synchronous fs APIs, so the prompt-template cache
+    // can be primed immediately — no need for the legacy 1s setTimeout deferral.
+    const { primeCache } = await import("./prompt-loader.js");
+    primeCache();
     // Open the project DB before rebuild/derive so resume uses DB-backed
     // state instead of falling back to stale markdown parsing (#2940).
     await openProjectDbIfPresent(s.basePath);
@@ -2057,6 +2144,11 @@ export async function startAuto(
     buildResolver,
   };
 
+  // Register the worker before bootstrap enters a milestone worktree.
+  // This ensures enterMilestone can claim a lease and seed dispatch claims
+  // for crash-recovery fidelity (#5405).
+  registerAutoWorkerForSession(s, base);
+
   const ready = await bootstrapAutoSession(
     s,
     ctx,
@@ -2241,7 +2333,7 @@ export async function dispatchHookUnit(
     return false;
   }
 
-  const result = await s.cmdCtx!.newSession();
+  const result = await s.cmdCtx!.newSession({ cwd: s.basePath });
   if (result.cancelled) {
     await stopAuto(ctx, pi);
     return false;

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -153,9 +153,29 @@ export async function handleAgentEnd(
   if (maybeHandleEmptyIntentTurn(event, isAutoActive())) return;
 
   if (!isAutoActive()) return;
-  if (isSessionSwitchInFlight()) return;
 
   const lastMsg = event.messages[event.messages.length - 1];
+  if (isSessionSwitchInFlight()) {
+    if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "error") {
+      const rawErrorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : "";
+      if (isUserInitiatedAbortMessage(rawErrorMsg)) {
+        resolveAgentEndCancelled({
+          message: rawErrorMsg,
+          category: "aborted",
+          isTransient: false,
+        });
+      }
+    } else if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "aborted") {
+      const content = "content" in lastMsg ? lastMsg.content : undefined;
+      const hasEmptyContent = Array.isArray(content) && content.length === 0;
+      const hasErrorMessage = "errorMessage" in lastMsg && !!lastMsg.errorMessage;
+      if (!hasEmptyContent || hasErrorMessage) {
+        resolveAgentEndCancelled(_buildAbortedPauseContext(lastMsg as { errorMessage?: unknown }));
+      }
+    }
+    return;
+  }
+
   if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "aborted") {
     // Empty content with aborted stopReason is a non-fatal agent stop (the LLM
     // chose to end without producing output). Only pause on genuine fatal aborts

package/src/resources/extensions/gsd/bootstrap/exec-tools.ts

@@ -6,23 +6,36 @@
 import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 
+async function loadContextModePreferences(baseDir: string) {
+  const [{ loadEffectiveGSDPreferences }, { logWarning }] = await Promise.all([
+    import("../preferences.js"),
+    import("../workflow-logger.js"),
+  ]);
+  try {
+    return loadEffectiveGSDPreferences(baseDir)?.preferences ?? null;
+  } catch (err) {
+    logWarning("tool", `Context Mode tool could not load preferences: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+
 export function registerExecTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "gsd_exec",
     label: "Exec (Sandboxed)",
     description:
-      "Run a short script (bash/node/python) in a subprocess. Full stdout/stderr persist to " +
+      "Run a short script (bash/node/python) in a subprocess. Capped stdout/stderr and metadata persist to " +
       ".gsd/exec/<id>.{stdout,stderr,meta.json}; only a short digest returns in context. Use " +
       "this instead of reading many files or emitting large tool outputs — e.g. have the script " +
       "count/grep/summarize and log the finding. Enabled by default; opt out via " +
       "preferences.context_mode.enabled=false.",
     promptSnippet:
-      "Run a bash/node/python script in a sandbox; full output is saved to disk and only a digest returns",
+      "Run a bash/node/python script in a sandbox; capped output is saved to disk and only a digest returns",
     promptGuidelines: [
       "Prefer gsd_exec for analyses that would otherwise read >3 files or produce large tool output.",
       "Write scripts that log the finding (counts, matches, summaries) rather than raw dumps.",
       "The digest is the last ~300 chars of stdout — size your log output accordingly.",
-      "Need the full output? Read the stdout_path returned in details (file on local disk).",
+      "Need persisted output? Read the stdout_path returned in details (file on local disk).",
     ],
     parameters: Type.Object({
       runtime: Type.Union(
@@ -40,20 +53,11 @@ export function registerExecTools(pi: ExtensionAPI): void {
       ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-      const [{ executeGsdExec }, { loadEffectiveGSDPreferences }, { logWarning }] = await Promise.all([
-        import("../tools/exec-tool.js"),
-        import("../preferences.js"),
-        import("../workflow-logger.js"),
-      ]);
-      let prefs: ReturnType<typeof loadEffectiveGSDPreferences> | null = null;
-      try {
-        prefs = loadEffectiveGSDPreferences();
-      } catch (err) {
-        logWarning("tool", `gsd_exec could not load preferences: ${err instanceof Error ? err.message : String(err)}`);
-      }
+      const { executeGsdExec } = await import("../tools/exec-tool.js");
+      const baseDir = process.cwd();
       return executeGsdExec(params as Parameters<typeof executeGsdExec>[0], {
-        baseDir: process.cwd(),
-        preferences: prefs?.preferences ?? null,
+        baseDir,
+        preferences: await loadContextModePreferences(baseDir),
       });
     },
   });
@@ -67,7 +71,7 @@ export function registerExecTools(pi: ExtensionAPI): void {
     promptSnippet: "Search prior gsd_exec runs by substring, runtime, or failing-only filter",
     promptGuidelines: [
       "Use this before re-running an expensive analysis — the prior run's stdout file may still answer.",
-      "The preview shows the trailing ~300 chars of stdout; read stdout_path for the full transcript.",
+      "The preview shows the trailing ~300 chars of stdout; read stdout_path for persisted output.",
     ],
     parameters: Type.Object({
       query: Type.Optional(Type.String({ description: "Substring matched against id and purpose (case-insensitive)." })),
@@ -81,8 +85,10 @@ export function registerExecTools(pi: ExtensionAPI): void {
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       const { executeExecSearch } = await import("../tools/exec-search-tool.js");
+      const baseDir = process.cwd();
       return executeExecSearch(params as Parameters<typeof executeExecSearch>[0], {
-        baseDir: process.cwd(),
+        baseDir,
+        preferences: await loadContextModePreferences(baseDir),
       });
     },
   });
@@ -102,8 +108,10 @@ export function registerExecTools(pi: ExtensionAPI): void {
     parameters: Type.Object({}),
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       const { executeResume } = await import("../tools/resume-tool.js");
+      const baseDir = process.cwd();
       return executeResume(params as Parameters<typeof executeResume>[0], {
-        baseDir: process.cwd(),
+        baseDir,
+        preferences: await loadContextModePreferences(baseDir),
       });
     },
   });

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

@@ -31,6 +31,13 @@ import { approvalGateIdForUnit, isExplicitApprovalResponse, shouldPauseForUserAp
 let isFirstSession = true;
 let approvalQuestionAbortInFlight = false;
 
+interface DeferredApprovalGate {
+  gateId: string;
+  basePath: string;
+}
+
+let deferredApprovalGate: DeferredApprovalGate | null = null;
+
 async function deriveGsdState(basePath: string) {
   const { deriveState } = await import("../state.js");
   return deriveState(basePath);
@@ -65,6 +72,66 @@ async function applyDisabledModelProviderPolicy(ctx: ExtensionContext): Promise<
   }
 }
 
+/**
+ * Bridge `context_management.compaction_threshold_percent` from GSD preferences
+ * into the agent's runtime compaction settings (#5475). The preference is
+ * validated to (0.5, 0.95) at load time, but defense-in-depth normalization
+ * here protects against a stale or hand-edited prefs file. Calling with
+ * `undefined` clears any prior override so a removed preference does not leak.
+ */
+async function applyCompactionThresholdOverride(ctx: ExtensionContext): Promise<void> {
+  try {
+    const { loadEffectiveGSDPreferences } = await import("../preferences.js");
+    const prefs = loadEffectiveGSDPreferences();
+    const raw = prefs?.preferences.context_management?.compaction_threshold_percent;
+    const value =
+      typeof raw === "number" && Number.isFinite(raw) && raw > 0 && raw < 1 ? raw : undefined;
+    ctx.setCompactionThresholdOverride(value);
+  } catch {
+    // Non-fatal: leave any existing override in place.
+  }
+}
+
+function clearDeferredApprovalGate(basePath?: string): void {
+  if (!basePath || deferredApprovalGate?.basePath === basePath) {
+    deferredApprovalGate = null;
+  }
+}
+
+function deferApprovalGate(gateId: string, basePath: string): void {
+  deferredApprovalGate = { gateId, basePath };
+}
+
+function activateDeferredApprovalGate(basePath: string): void {
+  if (deferredApprovalGate?.basePath !== basePath) return;
+  setPendingGate(deferredApprovalGate.gateId, basePath);
+  deferredApprovalGate = null;
+}
+
+function isContextDraftSummarySave(toolName: string, input: unknown): boolean {
+  if (toolName !== "gsd_summary_save" && toolName !== "summary_save") return false;
+  if (!input || typeof input !== "object") return false;
+  return (input as { artifact_type?: unknown }).artifact_type === "CONTEXT-DRAFT";
+}
+
+function shouldBlockDeferredApprovalTool(
+  toolName: string,
+  input: unknown,
+  basePath: string,
+): { block: boolean; reason?: string } {
+  if (deferredApprovalGate?.basePath !== basePath) return { block: false };
+  if (toolName === "ask_user_questions") return { block: false };
+  if (isContextDraftSummarySave(toolName, input)) return { block: false };
+  return {
+    block: true,
+    reason: [
+      `HARD BLOCK: Approval question "${deferredApprovalGate.gateId}" 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(" "),
+  };
+}
+
 export function resolveNotificationStoreBasePath(cwd: string = process.cwd()): string {
   return resolveWorktreeProjectRoot(cwd);
 }
@@ -120,9 +187,11 @@ export function registerHooks(
     resetWriteGateState(process.cwd());
     resetToolCallLoopGuard();
     approvalQuestionAbortInFlight = false;
+    clearDeferredApprovalGate();
     await resetAskUserQuestionsTurnCache();
     await syncServiceTierStatus(ctx);
     await applyDisabledModelProviderPolicy(ctx);
+    await applyCompactionThresholdOverride(ctx);
     // Skip MCP auto-prep when running inside an auto-worktree (see session_switch below).
     const { isInAutoWorktree } = await import("../auto-worktree.js");
     if (!isInAutoWorktree(process.cwd())) {
@@ -168,10 +237,12 @@ export function registerHooks(
     initSessionNotifications(ctx);
     resetWriteGateState(process.cwd());
     resetToolCallLoopGuard();
+    clearDeferredApprovalGate();
     await resetAskUserQuestionsTurnCache();
     clearDiscussionFlowState(process.cwd());
     await syncServiceTierStatus(ctx);
     await applyDisabledModelProviderPolicy(ctx);
+    await applyCompactionThresholdOverride(ctx);
     // Skip MCP auto-prep when running inside an auto-worktree. The worktree
     // already has .mcp.json from createAutoWorktree, and re-running the writer
     // post-chdir rewrites the file mid-run (non-idempotent due to cwd-relative
@@ -203,6 +274,7 @@ export function registerHooks(
       if (milestoneId) markDepthVerified(milestoneId, beforeAgentBasePath);
       clearPendingGate(beforeAgentBasePath);
     }
+    clearDeferredApprovalGate(beforeAgentBasePath);
 
     // GSD's own context injection (existing behavior — unchanged).
     const { buildBeforeAgentStartResult } = await import("./system-context.js");
@@ -253,7 +325,11 @@ export function registerHooks(
     resetToolCallLoopGuard();
     await resetAskUserQuestionsTurnCache();
     const { handleAgentEnd } = await import("./agent-end-recovery.js");
-    await handleAgentEnd(pi, event, ctx);
+    try {
+      await handleAgentEnd(pi, event, ctx);
+    } finally {
+      activateDeferredApprovalGate(process.cwd());
+    }
   });
 
   // Squash-merge quick-task branch back to the original branch after the
@@ -355,15 +431,16 @@ export function registerHooks(
     if (!shouldPauseForUserApprovalQuestion(unitType, [event.message])) return;
 
     const gateId = approvalGateIdForUnit(unitType, unitId);
-    if (gateId) setPendingGate(gateId, process.cwd());
+    if (gateId) deferApprovalGate(gateId, process.cwd());
 
     approvalQuestionAbortInFlight = true;
     ctx.ui.notify(
       `${unitType}${unitId ? ` ${unitId}` : ""} is waiting for your approval - pausing before more tool calls run.`,
       "info",
     );
-    // The pending gate set above blocks subsequent non-read-only tool calls
-    // via the tool_call hook below, so we do not abort the in-flight stream.
+    // 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.
     // Aborting mid-stream eats the model's question text on external CLI
     // providers (Claude Code SDK) because lastTextContent isn't populated
     // from in-flight builder state — the user only ever sees "Claude Code
@@ -395,6 +472,13 @@ export function registerHooks(
       return { block: true, reason: loopCheck.reason };
     }
 
+    const deferredGateGuard = shouldBlockDeferredApprovalTool(
+      toolName,
+      event.input,
+      discussionBasePath,
+    );
+    if (deferredGateGuard.block) return deferredGateGuard;
+
     // ── Discussion gate enforcement: track pending gate questions ─────────
     // Only gate-shaped ask_user_questions calls should block execution.
     // The gate stays pending until the user selects the approval option.