gsd-pi 2.78.0 → 2.78.1-dev.2ff77b0ce

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";
@@ -15,13 +14,13 @@ import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile
 import { ensureCodebaseMapFresh, readCodebaseMap } from "../codebase-generator.js";
 import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js";
 import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
-import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-command.js";
+import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-session-state.js";
 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
@@ -52,6 +51,17 @@ export const BUNDLED_SKILL_TRIGGERS: Array<{ trigger: string; skill: string }> =
   { 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(): string {
@@ -70,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) {
@@ -127,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.`,
@@ -207,7 +217,14 @@ export async function buildBeforeAgentStartResult(
     ? `\n\n## Subagent Model\n\nWhen spawning subagents via the \`subagent\` tool, always pass \`model: "${subagentModelConfig.primary}"\` in the tool call parameters. Never omit this — always specify it explicitly.`
     : "";
 
-  const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${codebaseBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}${subagentModelBlock}`;
+  // memoryBlock is FTS-queried against the user prompt and changes per call.
+  // Removing it from `fullSystem` keeps the system-prompt cache breakpoint
+  // stable across calls — the only scoped goal of this fix. The pi-ai
+  // Anthropic adapter additionally cache-marks the last user turn, so the
+  // memoryBlock injected via the context message may itself be cached up to
+  // that boundary; that's orthogonal and unchanged from prior behavior. The
+  // load-bearing win here is preserving the system+tools cache hit. (#5019)
+  const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${codebaseBlock}${newSkillsBlock}${worktreeBlock}${subagentModelBlock}`;
 
   stopContextTimer({
     systemPromptSize: fullSystem.length,
@@ -216,12 +233,7 @@ export async function buildBeforeAgentStartResult(
     hasNewSkills: newSkillsBlock.length > 0,
   });
 
-  // Determine which context message to inject (guided execute takes priority)
-  const contextMessage = injection
-    ? { customType: "gsd-guided-context", content: injection, display: false as const }
-    : forensicsInjection
-      ? { customType: "gsd-forensics", content: forensicsInjection, display: false as const }
-      : null;
+  const contextMessage = buildContextMessage({ memoryBlock, injection, forensicsInjection });
 
   return {
     systemPrompt: fullSystem,
@@ -229,6 +241,35 @@ export async function buildBeforeAgentStartResult(
   };
 }
 
+/**
+ * Route the per-call dynamic blocks (memory, guided-execute, forensics) into a
+ * single user-message context payload so they ride the volatile suffix instead
+ * of the cached system prefix. Priority when both memory and an injection are
+ * present: guided > forensics > memory-only. (#5019)
+ *
+ * Exported for direct unit testing — the surrounding bootstrap has too many
+ * filesystem and DB dependencies to exercise this routing logic in-place.
+ */
+export function buildContextMessage(opts: {
+  memoryBlock: string;
+  injection: string | null;
+  forensicsInjection: string | null;
+}): { customType: string; content: string; display: false } | null {
+  const memoryContent = opts.memoryBlock.trim();
+  if (opts.injection) {
+    const content = memoryContent ? `${memoryContent}\n\n${opts.injection}` : opts.injection;
+    return { customType: "gsd-guided-context", content, display: false as const };
+  }
+  if (opts.forensicsInjection) {
+    const content = memoryContent ? `${memoryContent}\n\n${opts.forensicsInjection}` : opts.forensicsInjection;
+    return { customType: "gsd-forensics", content, display: false as const };
+  }
+  if (memoryContent) {
+    return { customType: "gsd-memory", content: memoryContent, display: false as const };
+  }
+  return null;
+}
+
 /**
  * ADR-013 step 4 — auto-injection parity for the memories table.
  *

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

@@ -3,15 +3,8 @@ import { isAbsolute, join, relative, resolve, sep } from "node:path";
 
 import { minimatch } from "minimatch";
 
-/**
- * Declarative tools-policy for a unit. Inlined here because the worktree
- * branch predates the full unit-context-manifest export (#4934).
- */
-export type ToolsPolicy =
-  | { mode: "all" }
-  | { mode: "read-only" }
-  | { mode: "planning" }
-  | { mode: "docs"; allowedPathGlobs: readonly string[] };
+import type { ToolsPolicy } from "../unit-context-manifest.js";
+import { logWarning } from "../workflow-logger.js";
 
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
@@ -71,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;
 
 /**
@@ -94,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;
 }
@@ -127,6 +126,7 @@ function writeGateSnapshotPath(basePath: string = process.cwd()): string {
 function currentWriteGateSnapshot(): WriteGateSnapshot {
   return {
     verifiedDepthMilestones: [...verifiedDepthMilestones].sort(),
+    verifiedApprovalGates: [...verifiedApprovalGates].sort(),
     activeQueuePhase,
     pendingGateId,
   };
@@ -167,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,
   };
@@ -176,6 +180,7 @@ function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
 
 const EMPTY_SNAPSHOT: WriteGateSnapshot = {
   verifiedDepthMilestones: [],
+  verifiedApprovalGates: [],
   activeQueuePhase: false,
   pendingGateId: null,
 };
@@ -227,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();
@@ -244,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.
  */
@@ -273,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();
 }
 
@@ -296,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,
@@ -314,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.`,
@@ -333,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,
@@ -351,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(" "),
@@ -472,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).
  *
@@ -535,10 +605,76 @@ export function shouldBlockQueueExecutionInSnapshot(
 }
 
 // ─── Planning-unit tools-policy enforcement (#4934) ───────────────────────
+//
+// Runtime half of the declarative ToolsPolicy on UnitContextManifest. The
+// manifest assigns each unit type a tools mode; this predicate is what
+// actually rejects a tool call that violates it.
+//
+// Forensics: a discuss-milestone LLM turn used the host Edit tool to modify
+// index.html in test app b23 (~/Github/test-apps/b23). With this predicate
+// wired into the tool_call hook, the same call returns block=true with a
+// HARD BLOCK reason that the model cannot rationalize past.
+//
+// Activation: the hook supplies the policy resolved from the active unit's
+// manifest. When no unit is active (interactive sessions, unknown unit
+// types), the hook passes null and this predicate is a no-op — falling
+// through to the existing pendingGate / queue-execution / context-write
+// 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 },
+} as const satisfies Record<string, { readonly readOnlySpecialist: boolean }>;
+
+export const ALLOWED_PLANNING_DISPATCH_AGENTS = new Set<string>(
+  Object.entries(PLANNING_DISPATCH_AGENT_REGISTRY)
+    .filter(([, metadata]) => metadata.readOnlySpecialist)
+    .map(([agentId]) => agentId),
+);
+
+let warnedMissingPlanningDispatchAgentClasses = false;
+
+function isReadOnlySpecialist(agentId: string): boolean {
+  const metadata = PLANNING_DISPATCH_AGENT_REGISTRY[agentId as keyof typeof PLANNING_DISPATCH_AGENT_REGISTRY];
+  return metadata?.readOnlySpecialist === true;
+}
+
+function allowedPlanningDispatchAgentsList(): string {
+  return [...ALLOWED_PLANNING_DISPATCH_AGENTS].join(", ");
+}
+
+function warnMissingPlanningDispatchAgentClasses(unitType: string, mode: string, toolName: string): void {
+  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
+ * planning units (which need their full discussion + research surface).
+ *
+ * gsd_* MCP tools are passed through unconditionally — they have their own
+ * domain validation (e.g. depth-verification gate, single-writer DB).
+ */
 const PLANNING_SAFE_TOOLS = new Set([
   "read", "grep", "find", "ls", "glob",
   "ask_user_questions",
@@ -555,6 +691,7 @@ function isPathUnderGsd(absPath: string, basePath: string): boolean {
 function matchesAllowedGlob(absPath: string, basePath: string, globs: readonly string[]): boolean {
   const rel = relative(basePath, absPath);
   if (rel.startsWith("..") || isAbsolute(rel)) return false;
+  // Normalize Windows separators for minimatch.
   const posix = rel.split(sep).join("/");
   return globs.some(g => minimatch(posix, g, { dot: false, nocase: false }));
 }
@@ -576,10 +713,24 @@ function blockReason(unitType: string, mode: string, what: string): string {
  *   - "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.
  *
- * `policy` of null means "no manifest resolved" — pass-through.
+ * `pathOrCommand` is the file path for write/edit-shaped tools and the
+ * shell command for bash. Other tools ignore this argument.
+ *
+ * `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: string,
@@ -587,26 +738,77 @@ export function shouldBlockPlanningUnit(
   basePath: string,
   unitType: string,
   policy: ToolsPolicy | null | undefined,
+  agentClasses?: readonly string[],
 ): { block: boolean; reason?: string } {
   if (!policy) return { block: false };
   if (policy.mode === "all") return { block: false };
 
   const tool = toolName;
 
+  // Read-only mode: only Read-class tools are permitted.
   if (policy.mode === "read-only") {
     if (PLANNING_SAFE_TOOLS.has(tool)) return { block: false };
     if (tool.startsWith("gsd_")) return { block: false };
     if (PLANNING_WRITE_TOOLS.has(tool) || tool === "bash" || PLANNING_SUBAGENT_TOOLS.has(tool)) {
       return { block: true, reason: blockReason(unitType, policy.mode, `${tool} is not permitted (read-only)`) };
     }
+    // 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
+  // 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`) };
   }
 
@@ -628,8 +830,10 @@ export function shouldBlockPlanningUnit(
     }
     const absPath = isAbsolute(pathOrCommand) ? pathOrCommand : resolve(basePath, pathOrCommand);
 
+    // Always allow .gsd/ writes — that's where planning artifacts live.
     if (isPathUnderGsd(absPath, basePath)) return { block: false };
 
+    // docs mode additionally allows the manifest's allowedPathGlobs.
     if (policy.mode === "docs" && matchesAllowedGlob(absPath, basePath, policy.allowedPathGlobs)) {
       return { block: false };
     }
@@ -644,5 +848,8 @@ export function shouldBlockPlanningUnit(
     };
   }
 
+  // Unknown tool name — pass through. Other layers (queue, pending-gate,
+  // CONTEXT.md write) catch known mutating shapes; defaulting to allow here
+  // avoids breaking gsd_* MCP tools or future safe additions.
   return { block: false };
 }

package/src/resources/extensions/gsd/branch-patterns.ts

@@ -3,7 +3,7 @@
  *
  * 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 */
@@ -12,5 +12,5 @@ export const SLICE_BRANCH_RE = /^gsd\/(?:([a-zA-Z0-9_-]+)\/)?(M\d+(?:-[a-z0-9]{6
 /** 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)\//;