gsd-pi 2.78.1-dev.84a383f51 → 2.78.1-dev.84c045fd2

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

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { isToolCallEventType } from "@gsd/pi-coding-agent";
 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";
@@ -16,9 +16,12 @@ import { logWarning as safetyLogWarning } from "../workflow-logger.js";
 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) {
     const { deriveState } = await import("../state.js");
     return deriveState(basePath);
@@ -59,6 +62,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         resetWriteGateState();
         resetToolCallLoopGuard();
+        approvalQuestionAbortInFlight = false;
         await resetAskUserQuestionsTurnCache();
         await syncServiceTierStatus(ctx);
         await applyDisabledModelProviderPolicy(ctx);
@@ -133,6 +137,14 @@ export function registerHooks(pi, ecosystemHandlers) {
         // Wait for ecosystem loader to finish (no-op after first turn).
         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);
@@ -172,6 +184,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         };
     });
     pi.on("agent_end", async (event, ctx) => {
+        approvalQuestionAbortInFlight = false;
         resetToolCallLoopGuard();
         await resetAskUserQuestionsTurnCache();
         const { handleAgentEnd } = await import("./agent-end-recovery.js");
@@ -277,6 +290,44 @@ export function registerHooks(pi, ecosystemHandlers) {
             safetyLogWarning("context-mode", `failed to write compaction snapshot: ${err instanceof Error ? err.message : String(err)}`);
         }
     });
+    pi.on("message_update", async (event, ctx) => {
+        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) => {
         const { isParallelActive, shutdownParallel } = await import("../parallel-orchestrator.js");
         if (isParallelActive()) {
@@ -296,15 +347,16 @@ export function registerHooks(pi, ecosystemHandlers) {
     });
     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);
+        const loopCheck = checkToolCallLoop(toolName, event.input);
         if (loopCheck.block) {
             return { block: true, reason: loopCheck.reason };
         }
         // ── 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 = event.input?.questions ?? [];
             const questionId = questions.find((question) => typeof question?.id === "string" && isGateQuestionId(question.id))?.id;
             if (typeof questionId === "string") {
@@ -322,7 +374,7 @@ export function registerHooks(pi, ecosystemHandlers) {
                     return bashGuard;
             }
             else {
-                const gateGuard = shouldBlockPendingGate(event.toolName, milestoneId, isQueuePhaseActive());
+                const gateGuard = shouldBlockPendingGate(toolName, milestoneId, isQueuePhaseActive());
                 if (gateGuard.block)
                     return gateGuard;
             }
@@ -342,7 +394,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             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;
         }
@@ -358,6 +410,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             const manifest = resolveManifest(activeUnitType);
             if (manifest) {
                 let planningInput = "";
+                let agentClasses;
                 if (isToolCallEventType("write", event)) {
                     planningInput = event.input.path;
                 }
@@ -367,7 +420,11 @@ export function registerHooks(pi, ecosystemHandlers) {
                 else if (isToolCallEventType("bash", event)) {
                     planningInput = event.input.command;
                 }
-                const planningGuard = shouldBlockPlanningUnit(event.toolName, planningInput, dash.basePath || discussionBasePath, activeUnitType, manifest.tools);
+                else if (event.toolName === "subagent" || event.toolName === "task") {
+                    // Subagent inputs use { agent }, { tasks: [{ agent }] }, or { chain: [{ agent }] }.
+                    agentClasses = extractSubagentAgentClasses(event.input);
+                }
+                const planningGuard = shouldBlockPlanningUnit(event.toolName, planningInput, dash.basePath || discussionBasePath, activeUnitType, manifest.tools, agentClasses);
                 if (planningGuard.block)
                     return planningGuard;
             }
@@ -401,6 +458,18 @@ export function registerHooks(pi, ecosystemHandlers) {
             return;
         markToolStart(event.toolCallId, event.toolName);
         safetyRecordToolCall(event.toolCallId, event.toolName, event.input);
+        // Persist immediately at dispatch so a mid-unit re-dispatch — which calls
+        // resetEvidence() + loadEvidenceFromDisk() in runUnitPhase — cannot wipe
+        // the entry between tool_call and tool_execution_end. Without this, the
+        // race window equals the tool's runtime, producing the "no bash calls"
+        // false positive when the LLM clearly ran a verification command.
+        const callDash = getAutoRuntimeSnapshot();
+        if (callDash.basePath && callDash.currentUnit?.type === "execute-task") {
+            const { milestone: cMid, slice: cSid, task: cTid } = parseUnitId(callDash.currentUnit.id);
+            if (cMid && cSid && cTid) {
+                saveEvidenceToDisk(callDash.basePath, cMid, cSid, cTid);
+            }
+        }
         // Destructive command classification (warn only, never block)
         if (isToolCallEventType("bash", event)) {
             const classification = classifyCommand(event.input.command);
@@ -429,7 +498,8 @@ export function registerHooks(pi, ecosystemHandlers) {
             // errors and deterministic policy rejections are handled consistently.
             recordToolInvocationError(event.toolName, errorText);
         }
-        if (event.toolName !== "ask_user_questions")
+        const toolName = canonicalToolName(event.toolName);
+        if (toolName !== "ask_user_questions")
             return;
         const milestoneId = await getDiscussionMilestoneIdFor(process.cwd());
         const queueActive = isQueuePhaseActive();
@@ -443,14 +513,30 @@ export function registerHooks(pi, ecosystemHandlers) {
         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",
+                            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();
                     }
                 }
@@ -465,6 +551,9 @@ export function registerHooks(pi, ecosystemHandlers) {
                 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/dist/resources/extensions/gsd/bootstrap/subagent-input.js

@@ -0,0 +1,22 @@
+export function extractSubagentAgentClasses(input) {
+    if (!input || typeof input !== "object")
+        return [];
+    const record = input;
+    const agentClasses = [];
+    const addAgentClass = (value) => {
+        if (typeof value === "string" && value.trim().length > 0)
+            agentClasses.push(value.trim());
+    };
+    const addFromItems = (value) => {
+        if (!Array.isArray(value))
+            return;
+        for (const item of value) {
+            if (item && typeof item === "object")
+                addAgentClass(item.agent);
+        }
+    };
+    addAgentClass(record.agent);
+    addFromItems(record.tasks);
+    addFromItems(record.chain);
+    return agentClasses;
+}

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { logWarning } from "../workflow-logger.js";
 import { debugTime } from "../debug-logger.js";
@@ -17,7 +16,7 @@ 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";
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+import { gsdHome } from "../gsd-home.js";
 /**
  * Bundled skill triggers — resolved dynamically at runtime instead of
  * hardcoding absolute paths in the system prompt template. Only skills
@@ -47,6 +46,17 @@ export const BUNDLED_SKILL_TRIGGERS = [
     { trigger: "HTTP/REST/GraphQL API design — verbs, status codes, pagination, errors, idempotency, versioning", skill: "api-design" },
     { trigger: "Dependency upgrades — risk-batched, verified between batches, one major per commit", skill: "dependency-upgrade" },
     { trigger: "Agent-first observability — structured logs, persisted failure state, health surfaces, explicit failure modes", skill: "observability" },
+    { trigger: "React/Next.js performance — components, data fetching, bundle optimization, rendering patterns from Vercel Engineering", skill: "react-best-practices" },
+    { trigger: "Core Web Vitals — fix LCP, CLS, INP; layout shifts; page experience optimization", skill: "core-web-vitals" },
+    { trigger: "GitHub Actions CI/CD — write, run, and debug workflow files; live syntax and run monitoring", skill: "github-workflows" },
+    { trigger: "Comprehensive web quality audit — performance, accessibility, SEO, and best-practices (Lighthouse-style)", skill: "web-quality-audit" },
+    { trigger: "Browser automation — open sites, fill forms, click, screenshot, scrape, or test web apps programmatically", skill: "agent-browser" },
+    { trigger: "Review UI code for Web Interface Guidelines compliance — UX, design, and accessibility patterns", skill: "web-design-guidelines" },
+    { trigger: "UI/UX patterns reference — animations, CSS, typography, prefetching, icons (file:line findings)", skill: "userinterface-wiki" },
+    { trigger: "Author or refine a GSD skill — SKILL.md structure, frontmatter, and best practices", skill: "create-skill" },
+    { trigger: "Create or debug a GSD extension — tools, commands, event hooks, custom TUI, providers", skill: "create-gsd-extension" },
+    { trigger: "Author a YAML workflow definition — steps, triggers, and templates", skill: "create-workflow" },
+    { trigger: "Deep code optimization audit — perf anti-patterns, memory leaks, algorithmic complexity, bundle size, I/O, caching, dead code (parallel pattern-based hunt)", skill: "code-optimizer" },
 ];
 function buildBundledSkillsTable() {
     const cwd = process.cwd();
@@ -64,7 +74,7 @@ function buildBundledSkillsTable() {
 }
 function warnDeprecatedAgentInstructions() {
     const paths = [
-        join(gsdHome, "agent-instructions.md"),
+        join(gsdHome(), "agent-instructions.md"),
         join(process.cwd(), ".gsd", "agent-instructions.md"),
     ];
     for (const path of paths) {
@@ -108,7 +118,7 @@ export async function buildBeforeAgentStartResult(event, ctx) {
             ctx.ui.notify(`GSD skill preferences: ${report.warnings.length} unresolved skill${report.warnings.length === 1 ? "" : "s"}: ${report.warnings.join(", ")}`, "warning");
         }
     }
-    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.`, "warning");
     }

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -1,6 +1,7 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { minimatch } from "minimatch";
+import { logWarning } from "../workflow-logger.js";
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
  * and unique M001-abc123 formats. Exported so regex-hardening tests
@@ -55,6 +56,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();
+const verifiedApprovalGates = new Set();
 let activeQueuePhase = false;
 /**
  * Discussion gate enforcement state.
@@ -75,14 +77,18 @@ 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) {
+    if (!toolName.startsWith("mcp__"))
+        return toolName;
+    const toolSeparator = toolName.indexOf("__", "mcp__".length);
+    return toolSeparator >= 0 ? toolName.slice(toolSeparator + 2) : toolName;
+}
 /**
  * Persistence is ON by default (opt-out).
  * Set GSD_PERSIST_WRITE_GATE_STATE="0" or GSD_PERSIST_WRITE_GATE_STATE="false"
@@ -99,6 +105,7 @@ function writeGateSnapshotPath(basePath = process.cwd()) {
 function currentWriteGateSnapshot() {
     return {
         verifiedDepthMilestones: [...verifiedDepthMilestones].sort(),
+        verifiedApprovalGates: [...verifiedApprovalGates].sort(),
         activeQueuePhase,
         pendingGateId,
     };
@@ -141,14 +148,19 @@ function normalizeWriteGateSnapshot(value) {
     const verified = Array.isArray(record.verifiedDepthMilestones)
         ? record.verifiedDepthMilestones.filter((item) => typeof item === "string")
         : [];
+    const verifiedGates = Array.isArray(record.verifiedApprovalGates)
+        ? record.verifiedApprovalGates.filter((item) => 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,
     };
 }
 const EMPTY_SNAPSHOT = {
     verifiedDepthMilestones: [],
+    verifiedApprovalGates: [],
     activeQueuePhase: false,
     pendingGateId: null,
 };
@@ -194,11 +206,13 @@ export function setQueuePhaseActive(active) {
 }
 export function resetWriteGateState() {
     verifiedDepthMilestones.clear();
+    verifiedApprovalGates.clear();
     pendingGateId = null;
     persistWriteGateSnapshot();
 }
 export function clearDiscussionFlowState() {
     verifiedDepthMilestones.clear();
+    verifiedApprovalGates.clear();
     activeQueuePhase = false;
     pendingGateId = null;
     clearPersistedWriteGateSnapshot();
@@ -209,6 +223,17 @@ export function markDepthVerified(milestoneId, basePath = process.cwd()) {
     verifiedDepthMilestones.add(milestoneId);
     persistWriteGateSnapshot(basePath);
 }
+export function markApprovalGateVerified(gateId, basePath = process.cwd()) {
+    if (!gateId)
+        return;
+    verifiedApprovalGates.add(gateId);
+    persistWriteGateSnapshot(basePath);
+}
+export function isApprovalGateVerifiedInSnapshot(snapshot, gateId) {
+    if (!gateId)
+        return false;
+    return (snapshot.verifiedApprovalGates ?? []).includes(gateId);
+}
 /**
  * Check whether a question ID matches a recognized gate pattern.
  */
@@ -235,6 +260,10 @@ function extractContextMilestoneId(inputPath) {
  */
 export function setPendingGate(gateId) {
     pendingGateId = gateId;
+    verifiedApprovalGates.delete(gateId);
+    const milestoneId = extractDepthVerificationMilestoneId(gateId);
+    if (milestoneId)
+        verifiedDepthMilestones.delete(milestoneId);
     persistWriteGateSnapshot();
 }
 /**
@@ -255,7 +284,7 @@ export function getPendingGate() {
  * 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, milestoneId, queuePhaseActive) {
     return shouldBlockPendingGateInSnapshot(currentWriteGateSnapshot(), toolName, milestoneId, queuePhaseActive);
@@ -263,16 +292,14 @@ export function shouldBlockPendingGate(toolName, milestoneId, queuePhaseActive)
 export function shouldBlockPendingGateInSnapshot(snapshot, toolName, _milestoneId, _queuePhaseActive) {
     if (!snapshot.pendingGateId)
         return { block: false };
-    if (GATE_SAFE_TOOLS.has(toolName))
+    if (GATE_SAFE_TOOLS.has(canonicalToolName(toolName)))
         return { block: false };
-    // Bash read-only commands are also safe
-    if (toolName === "bash")
-        return { block: false }; // bash is checked separately below
     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.`,
@@ -281,7 +308,7 @@ export function shouldBlockPendingGateInSnapshot(snapshot, toolName, _milestoneI
 }
 /**
  * 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, milestoneId, queuePhaseActive) {
     return shouldBlockPendingGateBashInSnapshot(currentWriteGateSnapshot(), command, milestoneId, queuePhaseActive);
@@ -289,14 +316,12 @@ export function shouldBlockPendingGateBash(command, milestoneId, queuePhaseActiv
 export function shouldBlockPendingGateBashInSnapshot(snapshot, command, _milestoneId, _queuePhaseActive) {
     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(" "),
@@ -389,6 +414,49 @@ export function shouldBlockContextArtifactSaveInSnapshot(snapshot, artifactType,
         ].join(" "),
     };
 }
+const FINAL_ROOT_ARTIFACTS = new Set(["PROJECT", "REQUIREMENTS"]);
+function requiredRootApprovalGateForArtifact(artifactType) {
+    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, artifactType, opts = {}) {
+    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).
  *
@@ -458,6 +526,42 @@ export function shouldBlockQueueExecutionInSnapshot(snapshot, toolName, input, q
 // guards.
 const PLANNING_WRITE_TOOLS = new Set(["write", "edit", "multi_edit", "notebook_edit"]);
 const PLANNING_SUBAGENT_TOOLS = new Set(["subagent", "task"]);
+/**
+ * Canonical registry for agents that planning-dispatch may consider. Unit
+ * manifests still declare per-unit subsets via ToolsPolicy.allowedSubagents.
+ */
+const PLANNING_DISPATCH_AGENT_REGISTRY = {
+    scout: { readOnlySpecialist: true },
+    planner: { readOnlySpecialist: true },
+    reviewer: { readOnlySpecialist: true },
+    security: { readOnlySpecialist: true },
+    tester: { readOnlySpecialist: true },
+};
+export const ALLOWED_PLANNING_DISPATCH_AGENTS = new Set(Object.entries(PLANNING_DISPATCH_AGENT_REGISTRY)
+    .filter(([, metadata]) => metadata.readOnlySpecialist)
+    .map(([agentId]) => agentId));
+let warnedMissingPlanningDispatchAgentClasses = false;
+function isReadOnlySpecialist(agentId) {
+    const metadata = PLANNING_DISPATCH_AGENT_REGISTRY[agentId];
+    return metadata?.readOnlySpecialist === true;
+}
+function allowedPlanningDispatchAgentsList() {
+    return [...ALLOWED_PLANNING_DISPATCH_AGENTS].join(", ");
+}
+function warnMissingPlanningDispatchAgentClasses(unitType, mode, toolName) {
+    if (warnedMissingPlanningDispatchAgentClasses)
+        return;
+    warnedMissingPlanningDispatchAgentClasses = true;
+    // TODO(#5060): Remove this migration shim once all subagent/task callers are verified to forward agent identities.
+    const message = `[write-gate] planning-dispatch: shouldBlockPlanningUnit called for tool "${toolName}" ` +
+        `on unit "${unitType}" without agentClasses - stale caller; blocking dispatch.`;
+    console.warn(message);
+    logWarning("intercept", message, {
+        unitType,
+        mode,
+        toolName,
+    });
+}
 /**
  * Read-only / planning-safe tools that any non-"all" mode allows. Mirrors
  * QUEUE_SAFE_TOOLS / GATE_SAFE_TOOLS but is the inclusive default for
@@ -501,6 +605,10 @@ function blockReason(unitType, mode, what) {
  *   - "read-only"  → blocks all writes, bash, and subagent dispatch.
  *   - "planning"   → blocks writes to paths outside <basePath>/.gsd/,
  *                    bash that isn't read-only, and subagent dispatch.
+ *   - "planning-dispatch"
+ *                  → like "planning", but permits subagent dispatch only
+ *                    when every forwarded agent class is globally allowed
+ *                    and listed in the policy's allowedSubagents.
  *   - "docs"       → like "planning" but also allows writes to paths
  *                    matching `allowedPathGlobs` relative to basePath.
  *
@@ -510,8 +618,13 @@ function blockReason(unitType, mode, what) {
  * `policy` of null means "no manifest resolved" — pass-through. Callers
  * that have no active unit (interactive sessions) pass null and this
  * predicate is a no-op.
+ *
+ * `agentClasses` is supplied by the tool hook for subagent-shaped calls. If
+ * absent, planning-dispatch fails closed so stale callers cannot silently
+ * bypass the agent allowlists. An explicitly supplied-but-empty list is
+ * allowed through so the downstream tool call can reject the malformed input.
  */
-export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitType, policy) {
+export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitType, policy, agentClasses) {
     if (!policy)
         return { block: false };
     if (policy.mode === "all")
@@ -529,12 +642,48 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
         // Unknown tool in read-only mode — block by default.
         return { block: true, reason: blockReason(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`) };
     }
-    // planning / docs modes share the same surface for safe tools, bash, and subagent.
+    // planning / planning-dispatch / docs modes share the same surface for safe tools, bash, and subagent.
     if (PLANNING_SAFE_TOOLS.has(tool))
         return { block: false };
     if (tool.startsWith("gsd_"))
         return { block: false };
     if (PLANNING_SUBAGENT_TOOLS.has(tool)) {
+        if (policy.mode === "planning-dispatch") {
+            const requested = (agentClasses ?? []).map(a => a.trim()).filter(Boolean);
+            const allowedSubagents = Array.isArray(policy.allowedSubagents) ? policy.allowedSubagents : [];
+            const allowed = new Set(allowedSubagents);
+            // When agentClasses is undefined, the caller has not been updated to extract
+            // agent identities yet. Block and warn so stale callers surface in telemetry
+            // instead of silently bypassing the gate.
+            if (agentClasses === undefined) {
+                warnMissingPlanningDispatchAgentClasses(unitType, policy.mode, tool);
+                return {
+                    block: true,
+                    reason: blockReason(unitType, policy.mode, `subagent dispatch blocked: stale caller did not supply agent identities for "${tool}"; update extractSubagentAgentClasses to handle this input shape`),
+                };
+            }
+            // agentClasses was explicitly provided but resolved to an empty list (for
+            // example, a bare tool call with no agent field). Pass through; no agents
+            // to validate means the downstream tool call itself will fail.
+            if (requested.length === 0) {
+                return { block: false };
+            }
+            const globallyDisallowed = requested.find(a => !isReadOnlySpecialist(a));
+            if (globallyDisallowed) {
+                return {
+                    block: true,
+                    reason: blockReason(unitType, policy.mode, `subagent dispatch of "${globallyDisallowed}" not permitted; only read-only specialists (${allowedPlanningDispatchAgentsList()}) may be dispatched from planning-dispatch units`),
+                };
+            }
+            const disallowedByPolicy = requested.find(a => !allowed.has(a));
+            if (disallowedByPolicy) {
+                return {
+                    block: true,
+                    reason: blockReason(unitType, policy.mode, `subagent dispatch of "${disallowedByPolicy}" not permitted by ToolsPolicy.allowedSubagents; permitted agents for this unit: ${allowedSubagents.join(", ")}`),
+                };
+            }
+            return { block: false };
+        }
         return { block: true, reason: blockReason(unitType, policy.mode, `subagent dispatch is not permitted in planning units`) };
     }
     if (tool === "bash") {

package/dist/resources/extensions/gsd/branch-patterns.js

@@ -3,11 +3,11 @@
  *
  * gsd/<worktree>/<milestone>/<slice>  → SLICE_BRANCH_RE
  * gsd/quick/<id>-<slug>               → QUICK_BRANCH_RE
- * gsd/<workflow>/<...>                 → WORKFLOW_BRANCH_RE (non-milestone gsd/ branches)
+ * gsd/<workflow-template>/<...>        → WORKFLOW_BRANCH_RE
  */
 /** Matches gsd/ slice branches: gsd/[worktree/]M001[-hash]/S01 */
 export const SLICE_BRANCH_RE = /^gsd\/(?:([a-zA-Z0-9_-]+)\/)?(M\d+(?:-[a-z0-9]{6})?)\/(S\d+)$/;
 /** Matches gsd/quick/ task branches */
 export const QUICK_BRANCH_RE = /^gsd\/quick\//;
-/** Matches gsd/ workflow branches (non-milestone, e.g. gsd/workflow-name/...) */
-export const WORKFLOW_BRANCH_RE = /^gsd\/(?!M\d)[\w-]+\//;
+/** Matches GSD-generated workflow template branches, not arbitrary user gsd/* branches. */
+export const WORKFLOW_BRANCH_RE = /^gsd\/(?:hotfix|bugfix|small-feature|refactor|spike|security-audit|dep-upgrade|full-project)\//;