gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.42ef05fbe

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

@@ -128,7 +128,6 @@ import {
 } from "./metrics.js";
 import { setLogBasePath, logWarning, logError } from "./workflow-logger.js";
 import { preflightCleanRoot, postflightPopStash } from "./clean-root-preflight.js";
-import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
@@ -250,6 +249,7 @@ export type {
   StartModel,
 } from "./auto/session.js";
 import { autoSession as s } from "./auto-runtime-state.js";
+import { gsdHome } from "./gsd-home.js";
 
 // ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
 // ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
@@ -373,10 +373,7 @@ export function startAutoDetached(
 
 /** Returns true if the project is configured for `isolation:worktree` mode. */
 export function shouldUseWorktreeIsolation(basePath?: string): boolean {
-  const prefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
-  if (prefs?.isolation === "worktree") return true;
-  // Default is false — worktree isolation requires explicit opt-in
-  return false;
+  return getIsolationMode(basePath) === "worktree";
 }
 
 /** Crash recovery prompt — set by startAuto, consumed by the main loop */
@@ -1189,6 +1186,19 @@ export async function pauseAuto(
     s.currentUnit = null;
   }
 
+  // Keep STATE.md aligned with the DB-backed state before releasing pause state.
+  // Without this, an interrupted deep run can leave STATE.md saying "no active
+  // milestone" even after the DB/disk reconciliation has recovered the next unit.
+  if (s.basePath) {
+    try {
+      await rebuildState(s.basePath);
+    } catch (e) {
+      debugLog("pause-rebuild-state-failed", {
+        error: e instanceof Error ? e.message : String(e),
+      });
+    }
+  }
+
   if (lockBase()) {
     releaseSessionLock(lockBase());
     clearLock(lockBase());
@@ -1651,7 +1661,7 @@ export async function startAuto(
     // tree; deployed extensions live at ~/.gsd/agent/extensions/gsd/ where the
     // relative path resolves to ~/.gsd/agent/resource-loader.js which doesn't exist.
     // Using GSD_PKG_ROOT constructs a correct absolute path in both contexts (#3949).
-    const agentDir = process.env.GSD_CODING_AGENT_DIR || join(process.env.GSD_HOME || homedir(), ".gsd", "agent");
+    const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
     const pkgRoot = process.env.GSD_PKG_ROOT;
     const resourceLoaderPath = pkgRoot
       ? pathToFileURL(join(pkgRoot, "dist", "resource-loader.js")).href

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

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
 import { logWarning } from "../workflow-logger.js";
 import {
+  checkDeepProjectSetupAfterTurn,
   checkAutoStartAfterDiscuss,
   maybeHandleReadyPhraseWithoutFiles,
   maybeHandleEmptyIntentTurn,
@@ -13,6 +14,7 @@ import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../prefe
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
 import { isSessionSwitchInFlight, resolveAgentEnd } from "../auto-loop.js";
 import { resolveModelId } from "../auto-model-selection.js";
+import { resolveProjectRoot } from "../worktree.js";
 import { clearDiscussionFlowState } from "./write-gate.js";
 import { resumeAutoAfterProviderDelay } from "./provider-error-resume.js";
 import {
@@ -46,6 +48,14 @@ export function resetTransientRetryState(): void {
   resetRetryState(retryState);
 }
 
+function resolveAgentEndBasePath(): string | undefined {
+  try {
+    return resolveProjectRoot(process.cwd());
+  } catch {
+    return undefined;
+  }
+}
+
 async function pauseTransientWithBackoff(
   cls: ErrorClass,
   pi: ExtensionAPI,
@@ -95,6 +105,15 @@ export async function handleAgentEnd(
   // rejected" loop even though the files are on disk.
   clearPathCache();
 
+  try {
+    if (await checkDeepProjectSetupAfterTurn(event, ctx, resolveAgentEndBasePath())) {
+      return;
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logWarning("bootstrap", `checkDeepProjectSetupAfterTurn failed: ${message}`);
+  }
+
   if (checkAutoStartAfterDiscuss()) {
     clearDiscussionFlowState();
     return;

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

@@ -4,6 +4,7 @@ import { Text } from "@gsd/pi-tui";
 
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { ensureDbOpen } from "./dynamic-tools.js";
+import { loadWriteGateSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "./write-gate.js";
 import { StringEnum } from "@gsd/pi-ai";
 import { logError } from "../workflow-logger.js";
 import { getErrorMessage } from "../error-utils.js";
@@ -26,6 +27,16 @@ function registerAlias(pi: ExtensionAPI, toolDef: any, aliasName: string, canoni
   });
 }
 
+function requirementRootWriteGuard(operation: string): { content: Array<{ type: "text"; text: string }>; details: Record<string, unknown>; isError: true } | null {
+  const guard = shouldBlockRootArtifactSaveInSnapshot(loadWriteGateSnapshot(process.cwd()), "REQUIREMENTS");
+  if (!guard.block) return null;
+  return {
+    content: [{ type: "text", text: `Error ${operation} requirement: ${guard.reason ?? "requirements write blocked"}` }],
+    details: { operation, error: "root_artifact_write_blocked" },
+    isError: true,
+  };
+}
+
 /**
  * Read a tool result's structured payload, accommodating MCP's `details` →
  * `structuredContent` rename (#4472, #4477). In-process executions still
@@ -130,6 +141,8 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_requirement_update (formerly gsd_update_requirement) ───────────
 
   const requirementUpdateExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const gateBlock = requirementRootWriteGuard("update_requirement");
+    if (gateBlock) return gateBlock;
     const dbAvailable = await ensureDbOpen();
     if (!dbAvailable) {
       return {
@@ -208,6 +221,8 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_requirement_save ─────────────────────────────────────────────
 
   const requirementSaveExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
+    const gateBlock = requirementRootWriteGuard("save_requirement");
+    if (gateBlock) return gateBlock;
     const dbAvailable = await ensureDbOpen();
     if (!dbAvailable) {
       return {
@@ -253,13 +268,28 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "Requirement IDs are auto-assigned — never provide an ID manually.",
     promptSnippet: "Record a new GSD requirement to the database (auto-assigns ID, regenerates REQUIREMENTS.md)",
     promptGuidelines: [
-      "Use gsd_requirement_save when recording a new functional, non-functional, or operational requirement.",
+      "Use gsd_requirement_save when recording a new capability, quality attribute, constraint, or anti-feature requirement.",
+      "Use one of these classes: core-capability, primary-user-loop, launchability, continuity, failure-visibility, integration, quality-attribute, operability, admin/support, compliance/security, differentiator, constraint, anti-feature.",
       "Requirement IDs are auto-assigned (R001, R002, ...) — never guess or provide an ID.",
       "class, description, why, and source are required. All other fields are optional.",
       "The tool writes to the DB and regenerates .gsd/REQUIREMENTS.md automatically.",
     ],
     parameters: Type.Object({
-      class: Type.String({ description: "Requirement class (e.g. 'functional', 'non-functional', 'operational')" }),
+      class: StringEnum([
+        "core-capability",
+        "primary-user-loop",
+        "launchability",
+        "continuity",
+        "failure-visibility",
+        "integration",
+        "quality-attribute",
+        "operability",
+        "admin/support",
+        "compliance/security",
+        "differentiator",
+        "constraint",
+        "anti-feature",
+      ], { description: "Requirement class" }),
       description: Type.String({ description: "Short description of the requirement" }),
       why: Type.String({ description: "Why this requirement matters" }),
       source: Type.String({ description: "Origin of the requirement (e.g. 'user-research', 'design', 'M001')" }),
@@ -305,19 +335,29 @@ export function registerDbTools(pi: ExtensionAPI): void {
       "Computes the file path from milestone/slice/task IDs automatically.",
     promptSnippet: "Save a GSD artifact (summary/research/context/assessment) to DB and disk",
     promptGuidelines: [
-      "Use gsd_summary_save to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT).",
-      "milestone_id is required. slice_id and task_id are optional — they determine the file path.",
+      "Use gsd_summary_save to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT).",
+      "milestone_id is required for milestone/slice/task artifacts. Omit milestone_id only for root-level PROJECT/PROJECT-DRAFT/REQUIREMENTS/REQUIREMENTS-DRAFT.",
       "The tool computes the relative path automatically: milestones/M001/M001-SUMMARY.md, milestones/M001/slices/S01/S01-SUMMARY.md, etc.",
-      "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT.",
+      "Root-level artifact paths are PROJECT.md, PROJECT-DRAFT.md, REQUIREMENTS.md, and REQUIREMENTS-DRAFT.md.",
+      "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT.",
       "Use CONTEXT-DRAFT for incremental draft persistence; use CONTEXT for the final milestone context after depth verification.",
     ],
-    parameters: Type.Object({
-      milestone_id: Type.String({ description: "Milestone ID (e.g. M001)" }),
-      slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
-      task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
-      artifact_type: Type.String({ description: "One of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT" }),
-      content: Type.String({ description: "The full markdown content of the artifact" }),
-    }),
+    parameters: Type.Union([
+      Type.Object({
+        milestone_id: Type.String({ description: "Milestone ID (e.g. M001)" }),
+        slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
+        task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
+        artifact_type: StringEnum(["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT", "CONTEXT-DRAFT"], { description: "Milestone-scoped artifact type" }),
+        content: Type.String({ description: "The full markdown content of the artifact" }),
+      }),
+      Type.Object({
+        milestone_id: Type.Optional(Type.String({ description: "Omit for root artifacts" })),
+        slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
+        task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
+        artifact_type: StringEnum(["PROJECT", "PROJECT-DRAFT", "REQUIREMENTS", "REQUIREMENTS-DRAFT"], { description: "Root artifact type" }),
+        content: Type.String({ description: "The full markdown content of the artifact" }),
+      }),
+    ]),
     execute: summarySaveExecute,
     renderCall(args: any, theme: any) {
       let text = theme.fg("toolTitle", theme.bold("summary_save "));

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

@@ -7,7 +7,7 @@ import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-exten
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
 
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { canonicalToolName, clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.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";
@@ -23,10 +23,12 @@ import { installNotifyInterceptor } from "./notify-interceptor.js";
 import { initNotificationStore } from "../notification-store.js";
 import { initNotificationWidget } from "../notification-widget.js";
 import { extractSubagentAgentClasses } from "./subagent-input.js";
+import { approvalGateIdForUnit, isExplicitApprovalResponse, shouldPauseForUserApprovalQuestion } from "../user-input-boundary.js";
 
 // Skip the welcome screen on the very first session_start — cli.ts already
 // printed it before the TUI launched. Only re-print on /clear (subsequent sessions).
 let isFirstSession = true;
+let approvalQuestionAbortInFlight = false;
 
 async function deriveGsdState(basePath: string) {
   const { deriveState } = await import("../state.js");
@@ -76,6 +78,7 @@ export function registerHooks(
     }
     resetWriteGateState();
     resetToolCallLoopGuard();
+    approvalQuestionAbortInFlight = false;
     await resetAskUserQuestionsTurnCache();
     await syncServiceTierStatus(ctx);
     await applyDisabledModelProviderPolicy(ctx);
@@ -152,6 +155,14 @@ export function registerHooks(
     const { getEcosystemReadyPromise } = await import("../ecosystem/loader.js");
     await getEcosystemReadyPromise();
 
+    const pendingApprovalGate = getPendingGate();
+    if (pendingApprovalGate && isExplicitApprovalResponse(event.prompt, pendingApprovalGate)) {
+      markApprovalGateVerified(pendingApprovalGate);
+      const milestoneId = extractDepthVerificationMilestoneId(pendingApprovalGate);
+      if (milestoneId) markDepthVerified(milestoneId);
+      clearPendingGate();
+    }
+
     // GSD's own context injection (existing behavior — unchanged).
     const { buildBeforeAgentStartResult } = await import("./system-context.js");
     const gsdResult = await buildBeforeAgentStartResult(event, ctx);
@@ -197,6 +208,7 @@ export function registerHooks(
   });
 
   pi.on("agent_end", async (event, ctx: ExtensionContext) => {
+    approvalQuestionAbortInFlight = false;
     resetToolCallLoopGuard();
     await resetAskUserQuestionsTurnCache();
     const { handleAgentEnd } = await import("./agent-end-recovery.js");
@@ -305,6 +317,50 @@ export function registerHooks(
     }
   });
 
+  pi.on("message_update", async (event, ctx: ExtensionContext) => {
+    if (approvalQuestionAbortInFlight) return;
+
+    const dash = getAutoRuntimeSnapshot();
+    let unitType = dash.currentUnit?.type;
+    let unitId = dash.currentUnit?.id;
+
+    if (!unitType) {
+      try {
+        const { getPendingDeepProjectSetupUnitForContext } = await import("../guided-flow.js");
+        const pending = getPendingDeepProjectSetupUnitForContext(ctx, process.cwd());
+        unitType = pending?.unitType;
+        unitId = pending?.unitId;
+      } catch {
+        // Best-effort foreground detection only.
+      }
+    }
+
+    if (!unitType) {
+      const milestoneId = await getDiscussionMilestoneIdFor(process.cwd());
+      if (milestoneId) {
+        unitType = "discuss-milestone";
+        unitId = milestoneId;
+      }
+    }
+
+    if (!shouldPauseForUserApprovalQuestion(unitType, [event.message])) return;
+
+    const gateId = approvalGateIdForUnit(unitType, unitId);
+    if (gateId) setPendingGate(gateId);
+
+    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.
+    // 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
+    // stream aborted by caller" instead of the question.
+  });
+
   pi.on("session_shutdown", async (_event, ctx: ExtensionContext) => {
     const { isParallelActive, shutdownParallel } = await import("../parallel-orchestrator.js");
     if (isParallelActive()) {
@@ -323,8 +379,9 @@ export function registerHooks(
 
   pi.on("tool_call", async (event) => {
     const discussionBasePath = process.cwd();
+    const toolName = canonicalToolName(event.toolName);
     // ── Loop guard: block repeated identical tool calls ──
-    const loopCheck = checkToolCallLoop(event.toolName, event.input as Record<string, unknown>);
+    const loopCheck = checkToolCallLoop(toolName, event.input as Record<string, unknown>);
     if (loopCheck.block) {
       return { block: true, reason: loopCheck.reason };
     }
@@ -332,7 +389,7 @@ export function registerHooks(
     // ── 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.
-    if (event.toolName === "ask_user_questions") {
+    if (toolName === "ask_user_questions") {
       const questions: any[] = (event.input as any)?.questions ?? [];
       const questionId = questions.find((question) => typeof question?.id === "string" && isGateQuestionId(question.id))?.id;
       if (typeof questionId === "string") {
@@ -354,7 +411,7 @@ export function registerHooks(
         if (bashGuard.block) return bashGuard;
       } else {
         const gateGuard = shouldBlockPendingGate(
-          event.toolName,
+          toolName,
           milestoneId,
           isQueuePhaseActive(),
         );
@@ -375,7 +432,7 @@ export function registerHooks(
       } else if (isToolCallEventType("bash", event)) {
         queueInput = event.input.command;
       }
-      const queueGuard = shouldBlockQueueExecution(event.toolName, queueInput, true);
+      const queueGuard = shouldBlockQueueExecution(toolName, queueInput, true);
       if (queueGuard.block) return queueGuard;
     }
 
@@ -496,7 +553,8 @@ export function registerHooks(
       // errors and deterministic policy rejections are handled consistently.
       recordToolInvocationError(event.toolName, errorText);
     }
-    if (event.toolName !== "ask_user_questions") return;
+    const toolName = canonicalToolName(event.toolName);
+    if (toolName !== "ask_user_questions") return;
     const milestoneId = await getDiscussionMilestoneIdFor(process.cwd());
     const queueActive = isQueuePhaseActive();
 
@@ -511,13 +569,28 @@ export function registerHooks(
     const currentPendingGate = getPendingGate();
     if (currentPendingGate) {
       if (details?.cancelled || !details?.response) {
-        // Gate stays pending — model will be blocked from non-read-only tools
-        // until it re-asks and gets a valid response
+        // Gate stays pending. Return a hard instruction as the tool result so
+        // the model cannot reinterpret a cancelled prompt as prior approval.
+        return {
+          content: [{
+            type: "text" as const,
+            text: [
+              `HARD BLOCK: approval gate "${currentPendingGate}" is still pending.`,
+              "No user response was received for the confirmation question.",
+              "Do not infer approval from earlier or prior messages.",
+              "Do not proceed, write files, save artifacts, or call more tools.",
+              "Ask the user to confirm in plain chat, then stop and wait for their next message.",
+            ].join(" "),
+          }],
+        };
       } else {
         const pendingQuestion = questions.find((question) => question?.id === currentPendingGate);
         if (pendingQuestion) {
           const answer = details.response?.answers?.[currentPendingGate];
           if (isDepthConfirmationAnswer(answer?.selected, pendingQuestion.options)) {
+            markApprovalGateVerified(currentPendingGate);
+            const milestoneIdFromGate = extractDepthVerificationMilestoneId(currentPendingGate);
+            if (milestoneIdFromGate) markDepthVerified(milestoneIdFromGate);
             clearPendingGate();
           }
         }
@@ -533,6 +606,8 @@ export function registerHooks(
         const answer = details.response?.answers?.[question.id];
         const inferredMilestoneId = extractDepthVerificationMilestoneId(question.id) ?? milestoneId;
         if (isDepthConfirmationAnswer(answer?.selected, question.options)) {
+          if (currentPendingGate && question.id !== currentPendingGate) break;
+          markApprovalGateVerified(question.id);
           markDepthVerified(inferredMilestoneId);
           clearPendingGate();
         }

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
@@ -20,8 +19,8 @@ import { deriveState } from "../state.js";
 import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";
 import { toPosixPath } from "../../shared/mod.js";
 import { autoEnableCmuxPreferences } from "../commands-cmux.js";
+import { gsdHome } from "../gsd-home.js";
 
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 
 /**
  * Bundled skill triggers — resolved dynamically at runtime instead of
@@ -81,7 +80,7 @@ function buildBundledSkillsTable(): string {
 
 function warnDeprecatedAgentInstructions(): void {
   const paths = [
-    join(gsdHome, "agent-instructions.md"),
+    join(gsdHome(), "agent-instructions.md"),
     join(process.cwd(), ".gsd", "agent-instructions.md"),
   ];
   for (const path of paths) {
@@ -138,7 +137,7 @@ export async function buildBeforeAgentStartResult(
     }
   }
 
-  const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome, process.cwd());
+  const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome(), process.cwd());
   if (globalSizeKb > 4) {
     ctx.ui.notify(
       `GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`,

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -64,6 +64,7 @@ const QUEUE_SAFE_TOOLS = new Set([
 const BASH_READ_ONLY_RE = /^\s*(cat|head|tail|less|more|wc|file|stat|du|df|which|type|echo|printf|ls|find|grep|rg|awk|sed\b(?!.*-i)|sort|uniq|diff|comm|tr|cut|tee\s+-a\s+\/dev\/null|git\s+(log|show|diff|status|branch|tag|remote|rev-parse|ls-files|blame|shortlog|describe|stash\s+list|config\s+--get|cat-file)|gh\s+(issue|pr|api|repo|release)\s+(view|list|diff|status|checks)|mkdir\s+-p\s+\.gsd|rtk\s|npm\s+run\s+(test|test:\w+|lint|lint:\w+|typecheck|type-check|type-check:\w+|check|verify|audit|outdated|format:check|ci|validate)\b|npm\s+(ls|list|info|view|show|outdated|audit|explain|doctor|ping|--version|-v)\b|npx\s|tsx\s|node\s+(--print|--version|-v\b)|python[23]?\s+(-c\s+'[^']*'|--version|-V\b|-m\s+(pip\s+show|pip\s+list|site))|pip[23]?\s+(show|list|freeze|check|index\s+versions)\b|jq\s|yq\s|curl\s+(-s\b|--silent\b)(?!\s+[^|>]*\s-[oO]\b)(?!\s+[^|>]*\s--output\b)[^|>]*$|openssl\s+(version|x509|s_client)|env\b|printenv\b|true\b|false\b)/;
 
 const verifiedDepthMilestones = new Set<string>();
+const verifiedApprovalGates = new Set<string>();
 let activeQueuePhase = false;
 
 /**
@@ -87,17 +88,22 @@ const GATE_QUESTION_PATTERNS = [
 
 /**
  * Tools that are safe to call while a gate is pending.
- * Includes read-only tools and ask_user_questions itself (so the model can re-ask).
+ * Only ask_user_questions may run: once the assistant asks for confirmation,
+ * further reads/searches bury the actual question in tool output.
  */
 const GATE_SAFE_TOOLS = new Set([
   "ask_user_questions",
-  "read", "grep", "find", "ls", "glob",
-  "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
-  "search_and_read",
 ]);
 
+export function canonicalToolName(toolName: string): string {
+  if (!toolName.startsWith("mcp__")) return toolName;
+  const toolSeparator = toolName.indexOf("__", "mcp__".length);
+  return toolSeparator >= 0 ? toolName.slice(toolSeparator + 2) : toolName;
+}
+
 export interface WriteGateSnapshot {
   verifiedDepthMilestones: string[];
+  verifiedApprovalGates?: string[];
   activeQueuePhase: boolean;
   pendingGateId: string | null;
 }
@@ -120,6 +126,7 @@ function writeGateSnapshotPath(basePath: string = process.cwd()): string {
 function currentWriteGateSnapshot(): WriteGateSnapshot {
   return {
     verifiedDepthMilestones: [...verifiedDepthMilestones].sort(),
+    verifiedApprovalGates: [...verifiedApprovalGates].sort(),
     activeQueuePhase,
     pendingGateId,
   };
@@ -160,8 +167,12 @@ function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
   const verified = Array.isArray(record.verifiedDepthMilestones)
     ? record.verifiedDepthMilestones.filter((item): item is string => typeof item === "string")
     : [];
+  const verifiedGates = Array.isArray(record.verifiedApprovalGates)
+    ? record.verifiedApprovalGates.filter((item): item is string => typeof item === "string")
+    : [];
   return {
     verifiedDepthMilestones: [...new Set(verified)].sort(),
+    verifiedApprovalGates: [...new Set(verifiedGates)].sort(),
     activeQueuePhase: record.activeQueuePhase === true,
     pendingGateId: typeof record.pendingGateId === "string" ? record.pendingGateId : null,
   };
@@ -169,6 +180,7 @@ function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
 
 const EMPTY_SNAPSHOT: WriteGateSnapshot = {
   verifiedDepthMilestones: [],
+  verifiedApprovalGates: [],
   activeQueuePhase: false,
   pendingGateId: null,
 };
@@ -220,12 +232,14 @@ export function setQueuePhaseActive(active: boolean): void {
 
 export function resetWriteGateState(): void {
   verifiedDepthMilestones.clear();
+  verifiedApprovalGates.clear();
   pendingGateId = null;
   persistWriteGateSnapshot();
 }
 
 export function clearDiscussionFlowState(): void {
   verifiedDepthMilestones.clear();
+  verifiedApprovalGates.clear();
   activeQueuePhase = false;
   pendingGateId = null;
   clearPersistedWriteGateSnapshot();
@@ -237,6 +251,20 @@ export function markDepthVerified(milestoneId?: string | null, basePath: string
   persistWriteGateSnapshot(basePath);
 }
 
+export function markApprovalGateVerified(gateId?: string | null, basePath: string = process.cwd()): void {
+  if (!gateId) return;
+  verifiedApprovalGates.add(gateId);
+  persistWriteGateSnapshot(basePath);
+}
+
+export function isApprovalGateVerifiedInSnapshot(
+  snapshot: WriteGateSnapshot,
+  gateId?: string | null,
+): boolean {
+  if (!gateId) return false;
+  return (snapshot.verifiedApprovalGates ?? []).includes(gateId);
+}
+
 /**
  * Check whether a question ID matches a recognized gate pattern.
  */
@@ -266,6 +294,9 @@ function extractContextMilestoneId(inputPath: string): string | null {
  */
 export function setPendingGate(gateId: string): void {
   pendingGateId = gateId;
+  verifiedApprovalGates.delete(gateId);
+  const milestoneId = extractDepthVerificationMilestoneId(gateId);
+  if (milestoneId) verifiedDepthMilestones.delete(milestoneId);
   persistWriteGateSnapshot();
 }
 
@@ -289,7 +320,7 @@ export function getPendingGate(): string | null {
  * is pending (ask_user_questions was called but not confirmed).
  *
  * Returns { block: true, reason } if the tool should be blocked.
- * Read-only tools and ask_user_questions itself are always allowed.
+ * ask_user_questions itself is allowed so the model can re-ask the gate.
  */
 export function shouldBlockPendingGate(
   toolName: string,
@@ -307,16 +338,14 @@ export function shouldBlockPendingGateInSnapshot(
 ): { block: boolean; reason?: string } {
   if (!snapshot.pendingGateId) return { block: false };
 
-  if (GATE_SAFE_TOOLS.has(toolName)) return { block: false };
-
-  // Bash read-only commands are also safe
-  if (toolName === "bash") return { block: false }; // bash is checked separately below
+  if (GATE_SAFE_TOOLS.has(canonicalToolName(toolName))) return { block: false };
 
   return {
     block: true,
     reason: [
       `HARD BLOCK: Discussion gate "${snapshot.pendingGateId}" has not been confirmed by the user.`,
-      `You MUST re-call ask_user_questions with the gate question before making any other tool calls.`,
+      `The assistant already asked for user confirmation, so do not call more tools.`,
+      `Wait for the user's answer, or re-call ask_user_questions with the gate question if the question was not delivered.`,
       `If the previous ask_user_questions call failed, errored, was cancelled, or the user's response`,
       `did not match a provided option, you MUST re-ask — never rationalize past the block.`,
       `Do NOT proceed, do NOT use alternative approaches, do NOT skip the gate.`,
@@ -326,7 +355,7 @@ export function shouldBlockPendingGateInSnapshot(
 
 /**
  * Check whether a bash command should be blocked because a discussion gate is pending.
- * Read-only bash commands are allowed; mutating commands are blocked.
+ * All bash is blocked while waiting for confirmation so the question stays visible.
  */
 export function shouldBlockPendingGateBash(
   command: string,
@@ -344,14 +373,12 @@ export function shouldBlockPendingGateBashInSnapshot(
 ): { block: boolean; reason?: string } {
   if (!snapshot.pendingGateId) return { block: false };
 
-  // Allow read-only bash commands
-  if (BASH_READ_ONLY_RE.test(command)) return { block: false };
-
   return {
     block: true,
     reason: [
       `HARD BLOCK: Discussion gate "${snapshot.pendingGateId}" has not been confirmed by the user.`,
-      `You MUST re-call ask_user_questions with the gate question before running mutating commands.`,
+      `The assistant already asked for user confirmation, so do not run bash commands.`,
+      `Wait for the user's answer, or re-call ask_user_questions with the gate question if the question was not delivered.`,
       `If the previous ask_user_questions call failed, errored, was cancelled, or the user's response`,
       `did not match a provided option, you MUST re-ask — never rationalize past the block.`,
     ].join(" "),
@@ -465,6 +492,56 @@ export function shouldBlockContextArtifactSaveInSnapshot(
   };
 }
 
+const FINAL_ROOT_ARTIFACTS = new Set(["PROJECT", "REQUIREMENTS"]);
+
+function requiredRootApprovalGateForArtifact(artifactType: string): string | null {
+  if (artifactType === "PROJECT") return "depth_verification_project_confirm";
+  if (artifactType === "REQUIREMENTS") return "depth_verification_requirements_confirm";
+  return null;
+}
+
+/**
+ * Final root project artifacts are the output of the project/requirements
+ * approval gates. Drafts remain writable so the agent can prepare previews,
+ * but PROJECT.md and REQUIREMENTS.md must wait for explicit approval. Deep
+ * mode can additionally require a positive verified gate, not just no pending
+ * gate, so missed detectors fail closed.
+ */
+export function shouldBlockRootArtifactSaveInSnapshot(
+  snapshot: WriteGateSnapshot,
+  artifactType: string,
+  opts: { requireVerifiedApproval?: boolean } = {},
+): { block: boolean; reason?: string } {
+  if (!FINAL_ROOT_ARTIFACTS.has(artifactType)) return { block: false };
+
+  if (snapshot.pendingGateId) {
+    return {
+      block: true,
+      reason: [
+        `HARD BLOCK: Cannot save ${artifactType}.md because discussion gate "${snapshot.pendingGateId}" has not been confirmed by the user.`,
+        `This is a mechanical gate — wait for explicit user approval before writing final project setup artifacts.`,
+        `If approval was requested in plain text, the user must reply with explicit approval before this write is allowed.`,
+      ].join(" "),
+    };
+  }
+
+  if (opts.requireVerifiedApproval) {
+    const requiredGate = requiredRootApprovalGateForArtifact(artifactType);
+    if (requiredGate && !isApprovalGateVerifiedInSnapshot(snapshot, requiredGate)) {
+      return {
+        block: true,
+        reason: [
+          `HARD BLOCK: Cannot save ${artifactType}.md before explicit approval gate "${requiredGate}" is verified.`,
+          `Deep planning root artifacts are fail-closed: absence of a pending gate is not approval.`,
+          `Ask the user to confirm the ${artifactType}.md preview and wait for an explicit approval response.`,
+        ].join(" "),
+      };
+    }
+  }
+
+  return { block: false };
+}
+
 /**
  * Queue-mode execution guard (#2545).
  *