gsd-pi 2.70.1-dev.3591dcf → 2.70.1-dev.3e19108

package/packages/pi-coding-agent/src/modes/interactive/controllers/chat-controller.ts

@@ -9,6 +9,18 @@ import { appKey } from "../components/keybinding-hints.js";
 // Tracks the last processed content index to avoid re-scanning all blocks on every message_update
 let lastProcessedContentIndex = 0;
 
+function hasVisibleAssistantContent(message: { content: Array<any> }): boolean {
+	return message.content.some(
+		(c) =>
+			(c.type === "text" && typeof c.text === "string" && c.text.trim().length > 0)
+			|| (c.type === "thinking" && typeof c.thinking === "string" && c.thinking.trim().length > 0),
+	);
+}
+
+function hasAssistantToolBlocks(message: { content: Array<any> }): boolean {
+	return message.content.some((c) => c.type === "toolCall" || c.type === "serverToolUse");
+}
+
 export async function handleAgentEvent(host: InteractiveModeStateHost & {
 	init: () => Promise<void>;
 	getMarkdownThemeWithSettings: () => any;
@@ -104,45 +116,55 @@ export async function handleAgentEvent(host: InteractiveModeStateHost & {
 				host.updatePendingMessagesDisplay();
 				host.ui.requestRender();
 			} else if (event.message.role === "assistant") {
-				host.streamingComponent = new AssistantMessageComponent(
-					undefined,
-					host.hideThinkingBlock,
-					host.getMarkdownThemeWithSettings(),
-					host.settingsManager.getTimestampFormat(),
-				);
 				host.streamingMessage = event.message;
-				host.chatContainer.addChild(host.streamingComponent);
-				host.streamingComponent.updateContent(host.streamingMessage);
+				// External-tool providers can stream multiple assistant turns through
+				// one response. Delay component creation until visible assistant text
+				// arrives so tool outputs keep chronological ordering.
 				host.ui.requestRender();
 			}
 			break;
 
 		case "message_update":
-			if (host.streamingComponent && event.message.role === "assistant") {
+			if (event.message.role === "assistant") {
 				host.streamingMessage = event.message;
-				host.streamingComponent.updateContent(host.streamingMessage);
-
-				// When the stream adapter signals a completed tool call with an
-				// external result (from Claude Code SDK), update the pending
-				// ToolExecutionComponent immediately so output is visible in
-				// real-time instead of waiting for the session to end.
 				const innerEvent = event.assistantMessageEvent;
+
+				if (!host.streamingComponent && hasVisibleAssistantContent(host.streamingMessage)) {
+					host.streamingComponent = new AssistantMessageComponent(
+						undefined,
+						host.hideThinkingBlock,
+						host.getMarkdownThemeWithSettings(),
+						host.settingsManager.getTimestampFormat(),
+					);
+					host.chatContainer.addChild(host.streamingComponent);
+				}
+				if (host.streamingComponent) {
+					host.streamingComponent.updateContent(host.streamingMessage);
+				}
+
+				let externalToolResult:
+					| { toolCallId: string; content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>; details: Record<string, unknown>; isError: boolean }
+					| undefined;
 				if (innerEvent.type === "toolcall_end" && innerEvent.toolCall) {
 					const tc = innerEvent.toolCall as any;
-					const externalResult = tc.externalResult;
-					if (externalResult) {
-						const component = host.pendingTools.get(tc.id);
-						if (component) {
-							component.updateResult({
-								content: externalResult.content ?? [{ type: "text", text: "" }],
-								details: externalResult.details ?? {},
-								isError: externalResult.isError ?? false,
-							});
-						}
+					const ext = tc.externalResult;
+					if (ext) {
+						externalToolResult = {
+							toolCallId: tc.id,
+							content: ext.content ?? [{ type: "text", text: "" }],
+							details: ext.details ?? {},
+							isError: ext.isError ?? false,
+						};
 					}
 				}
 
 				const contentBlocks = host.streamingMessage.content;
+				// Some adapters reuse a single assistant lifecycle while internally
+				// spanning multiple provider turns. When a new turn starts, content
+				// length can shrink back to 0/1; reset scan index to avoid skipping.
+				if (lastProcessedContentIndex >= contentBlocks.length) {
+					lastProcessedContentIndex = 0;
+				}
 				for (let i = lastProcessedContentIndex; i < contentBlocks.length; i++) {
 					const content = contentBlocks[i];
 					if (content.type === "toolCall") {
@@ -192,6 +214,22 @@ export async function handleAgentEvent(host: InteractiveModeStateHost & {
 						}
 					}
 				}
+
+				// When the stream adapter signals a completed tool call with an
+				// external result (from Claude Code SDK), update the pending
+				// ToolExecutionComponent immediately so output is visible in
+				// real-time instead of waiting for the session to end.
+				if (externalToolResult) {
+					const component = host.pendingTools.get(externalToolResult.toolCallId);
+					if (component) {
+						component.updateResult({
+							content: externalToolResult.content,
+							details: externalToolResult.details,
+							isError: externalToolResult.isError,
+						});
+					}
+				}
+
 				// Update index: fully processed blocks won't need re-scanning.
 				// Keep the last block's index (it may still be accumulating data),
 				// so we re-check it next time but skip all earlier ones.
@@ -204,7 +242,7 @@ export async function handleAgentEvent(host: InteractiveModeStateHost & {
 
 		case "message_end":
 			if (event.message.role === "user") break;
-			if (host.streamingComponent && event.message.role === "assistant") {
+			if (event.message.role === "assistant") {
 				host.streamingMessage = event.message;
 				let errorMessage: string | undefined;
 				if (host.streamingMessage.stopReason === "aborted") {
@@ -214,7 +252,25 @@ export async function handleAgentEvent(host: InteractiveModeStateHost & {
 						: "Operation aborted";
 					host.streamingMessage.errorMessage = errorMessage;
 				}
-				host.streamingComponent.updateContent(host.streamingMessage);
+
+				const shouldRenderAssistant = hasVisibleAssistantContent(host.streamingMessage)
+					|| (
+						(host.streamingMessage.stopReason === "aborted" || host.streamingMessage.stopReason === "error")
+						&& !hasAssistantToolBlocks(host.streamingMessage)
+					);
+				if (!host.streamingComponent && shouldRenderAssistant) {
+					host.streamingComponent = new AssistantMessageComponent(
+						undefined,
+						host.hideThinkingBlock,
+						host.getMarkdownThemeWithSettings(),
+						host.settingsManager.getTimestampFormat(),
+					);
+					host.chatContainer.addChild(host.streamingComponent);
+				}
+				if (host.streamingComponent) {
+					host.streamingComponent.updateContent(host.streamingMessage);
+				}
+
 				if (host.streamingMessage.stopReason === "aborted" || host.streamingMessage.stopReason === "error") {
 					if (!errorMessage) {
 						errorMessage = host.streamingMessage.errorMessage || "Error";

package/src/resources/extensions/claude-code-cli/stream-adapter.ts

@@ -398,6 +398,7 @@ export function buildSdkOptions(
 	extraOptions: Record<string, unknown> = {},
 ): Record<string, unknown> {
 	const mcpServers = buildWorkflowMcpServers();
+	const disallowedTools = ["AskUserQuestion"];
 	return {
 		pathToClaudeCodeExecutable: getClaudePath(),
 		model: modelId,
@@ -408,6 +409,7 @@ export function buildSdkOptions(
 		allowDangerouslySkipPermissions: true,
 		settingSources: ["project"],
 		systemPrompt: { type: "preset", preset: "claude_code" },
+		disallowedTools,
 		...(mcpServers ? { mcpServers } : {}),
 		betas: modelId.includes("sonnet") ? ["context-1m-2025-08-07"] : [],
 		...extraOptions,

package/src/resources/extensions/claude-code-cli/tests/stream-adapter.test.ts

@@ -220,6 +220,35 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			assert.equal(srv.env.GSD_CLI_PATH, "/tmp/gsd");
 			assert.equal(srv.env.GSD_PERSIST_WRITE_GATE_STATE, "1");
 			assert.equal(srv.env.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project");
+			assert.deepEqual(options.disallowedTools, ["AskUserQuestion"]);
+		} finally {
+			process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND;
+			process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME;
+			process.env.GSD_WORKFLOW_MCP_ARGS = prev.GSD_WORKFLOW_MCP_ARGS;
+			process.env.GSD_WORKFLOW_MCP_ENV = prev.GSD_WORKFLOW_MCP_ENV;
+			process.env.GSD_WORKFLOW_MCP_CWD = prev.GSD_WORKFLOW_MCP_CWD;
+		}
+	});
+
+	test("buildSdkOptions disables AskUserQuestion for custom workflow MCP server names", () => {
+		const prev = {
+			GSD_WORKFLOW_MCP_COMMAND: process.env.GSD_WORKFLOW_MCP_COMMAND,
+			GSD_WORKFLOW_MCP_NAME: process.env.GSD_WORKFLOW_MCP_NAME,
+			GSD_WORKFLOW_MCP_ARGS: process.env.GSD_WORKFLOW_MCP_ARGS,
+			GSD_WORKFLOW_MCP_ENV: process.env.GSD_WORKFLOW_MCP_ENV,
+			GSD_WORKFLOW_MCP_CWD: process.env.GSD_WORKFLOW_MCP_CWD,
+		};
+		try {
+			process.env.GSD_WORKFLOW_MCP_COMMAND = "node";
+			process.env.GSD_WORKFLOW_MCP_NAME = "custom-workflow";
+			process.env.GSD_WORKFLOW_MCP_ARGS = JSON.stringify(["packages/mcp-server/dist/cli.js"]);
+			process.env.GSD_WORKFLOW_MCP_ENV = JSON.stringify({ GSD_CLI_PATH: "/tmp/gsd" });
+			process.env.GSD_WORKFLOW_MCP_CWD = "/tmp/project";
+
+			const options = buildSdkOptions("claude-sonnet-4-20250514", "test");
+			const mcpServers = options.mcpServers as Record<string, any>;
+			assert.ok(mcpServers?.["custom-workflow"], "expected custom workflow server config");
+			assert.deepEqual(options.disallowedTools, ["AskUserQuestion"]);
 		} finally {
 			process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND;
 			process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME;
@@ -255,6 +284,9 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			const mcpServers = (options as any).mcpServers;
 			if (mcpServers) {
 				assert.ok(mcpServers["gsd-workflow"], "if present, must be gsd-workflow");
+				assert.deepEqual((options as any).disallowedTools, ["AskUserQuestion"]);
+			} else {
+				assert.deepEqual((options as any).disallowedTools, ["AskUserQuestion"]);
 			}
 			rmSync(emptyDir, { recursive: true, force: true });
 		} finally {
@@ -301,6 +333,7 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			assert.equal(srv.env.GSD_CLI_PATH, "/tmp/gsd");
 			assert.equal(srv.env.GSD_PERSIST_WRITE_GATE_STATE, "1");
 			assert.equal(srv.env.GSD_WORKFLOW_PROJECT_ROOT, resolvedRepoDir);
+			assert.deepEqual(options.disallowedTools, ["AskUserQuestion"]);
 		} finally {
 			process.chdir(originalCwd);
 			rmSync(repoDir, { recursive: true, force: true });

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

@@ -335,19 +335,9 @@ export async function bootstrapAutoSession(
       }
     }
 
-    if (ctx.model?.provider === "claude-code") {
-      try {
-        const { ensureProjectWorkflowMcpConfig } = await import("./mcp-project-config.js");
-        const result = ensureProjectWorkflowMcpConfig(base);
-        if (result.status !== "unchanged") {
-          ctx.ui.notify(`Claude Code MCP prepared at ${result.configPath}`, "info");
-        }
-      } catch (err) {
-        ctx.ui.notify(
-          `Claude Code MCP prep failed: ${err instanceof Error ? err.message : String(err)}`,
-          "warning",
-        );
-      }
+    {
+      const { prepareWorkflowMcpForProject } = await import("./workflow-mcp-auto-prep.js");
+      prepareWorkflowMcpForProject(ctx, base);
     }
 
     // Initialize GitServiceImpl

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

@@ -45,6 +45,8 @@ export function registerHooks(pi: ExtensionAPI): void {
     resetToolCallLoopGuard();
     resetAskUserQuestionsCache();
     await syncServiceTierStatus(ctx);
+    const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
+    prepareWorkflowMcpForProject(ctx, process.cwd());
 
     // Apply show_token_cost preference (#1515)
     try {
@@ -85,6 +87,8 @@ export function registerHooks(pi: ExtensionAPI): void {
     resetAskUserQuestionsCache();
     clearDiscussionFlowState();
     await syncServiceTierStatus(ctx);
+    const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
+    prepareWorkflowMcpForProject(ctx, process.cwd());
     loadToolApiKeys();
   });
 

package/src/resources/extensions/gsd/guided-flow.ts

@@ -426,8 +426,9 @@ function resolveAvailableModel<T extends { id: string; provider: string }>(
  * Build the discuss-and-plan prompt for a new milestone.
  * Used by all three "new milestone" paths (first ever, no active, all complete).
  */
-function buildDiscussPrompt(nextId: string, preamble: string, _basePath: string, preparationContext?: string): string {
+function buildDiscussPrompt(nextId: string, preamble: string, _basePath: string, pi: ExtensionAPI, ctx: ExtensionCommandContext, preparationContext?: string): string {
   const milestoneRel = `.gsd/milestones/${nextId}`;
+  const structuredQuestionsAvailable = getStructuredQuestionsAvailability(pi, ctx);
   const inlinedTemplates = [
     inlineTemplate("project", "Project"),
     inlineTemplate("requirements", "Requirements"),
@@ -439,6 +440,7 @@ function buildDiscussPrompt(nextId: string, preamble: string, _basePath: string,
     milestoneId: nextId,
     preamble,
     preparationContext: preparationContext ?? "",
+    structuredQuestionsAvailable,
     contextPath: `${milestoneRel}/${nextId}-CONTEXT.md`,
     roadmapPath: `${milestoneRel}/${nextId}-ROADMAP.md`,
     inlinedTemplates,
@@ -486,6 +488,7 @@ function buildHeadlessDiscussPrompt(nextId: string, seedContext: string, _basePa
  */
 async function prepareAndBuildDiscussPrompt(
   ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
   nextId: string,
   preamble: string,
   basePath: string,
@@ -520,7 +523,7 @@ async function prepareAndBuildDiscussPrompt(
     }
   }
 
-  return buildDiscussPrompt(nextId, preamble, basePath, preparationContext);
+  return buildDiscussPrompt(nextId, preamble, basePath, pi, ctx, preparationContext);
 }
 
 /**
@@ -780,7 +783,7 @@ export async function showDiscuss(
       const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
       const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds);
       pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: false, createdAt: Date.now() });
-      await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
+      await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
     }
     return;
   }
@@ -1185,7 +1188,7 @@ async function handleMilestoneActions(
     const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
     const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds);
     pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
-    await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, nextId,
+    await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId,
       `New milestone ${nextId}.`,
       basePath
     ), "gsd-run", ctx, "discuss-milestone");
@@ -1375,7 +1378,7 @@ export async function showSmartEntry(
     if (isFirst) {
       // First ever — skip wizard, just ask directly
       pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
-      await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, nextId,
+      await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId,
         `New project, milestone ${nextId}. Do NOT read or explore .gsd/ — it's empty scaffolding.`,
         basePath
       ), "gsd-run", ctx, "discuss-milestone");
@@ -1396,7 +1399,7 @@ export async function showSmartEntry(
 
       if (choice === "new_milestone") {
         pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
-        await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, nextId,
+        await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId,
           `New milestone ${nextId}.`,
           basePath
         ), "gsd-run", ctx, "discuss-milestone");
@@ -1435,7 +1438,7 @@ export async function showSmartEntry(
       const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds);
 
       pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
-      await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, nextId,
+      await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId,
         `New milestone ${nextId}.`,
         basePath
       ), "gsd-run", ctx, "discuss-milestone");
@@ -1502,7 +1505,7 @@ export async function showSmartEntry(
       const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
       const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds);
       pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
-      await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, nextId,
+      await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId,
         `New milestone ${nextId}.`,
         basePath
       ), "gsd-run", ctx, "discuss-milestone");
@@ -1599,7 +1602,7 @@ export async function showSmartEntry(
         const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
         const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds);
         pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
-        await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, nextId,
+        await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId,
           `New milestone ${nextId}.`,
           basePath
         ), "gsd-run", ctx, "discuss-milestone");

package/src/resources/extensions/gsd/init-wizard.ts

@@ -274,19 +274,9 @@ export async function showProjectInit(
     // Non-fatal — STATE.md will be regenerated on next /gsd invocation
   }
 
-  if (ctx.model?.provider === "claude-code") {
-    try {
-      const { ensureProjectWorkflowMcpConfig } = await import("./mcp-project-config.js");
-      const result = ensureProjectWorkflowMcpConfig(basePath);
-      if (result.status !== "unchanged") {
-        ctx.ui.notify(`Claude Code MCP prepared at ${result.configPath}`, "info");
-      }
-    } catch (err) {
-      ctx.ui.notify(
-        `Claude Code MCP prep failed: ${err instanceof Error ? err.message : String(err)}`,
-        "warning",
-      );
-    }
+  {
+    const { prepareWorkflowMcpForProject } = await import("./workflow-mcp-auto-prep.js");
+    prepareWorkflowMcpForProject(ctx, basePath);
   }
 
   ctx.ui.notify("GSD initialized. Starting your first milestone...", "info");

package/src/resources/extensions/gsd/prompts/discuss.md

@@ -49,6 +49,26 @@ This happens ONCE, before the first round. The goal: your first questions should
 
 For subsequent rounds, continue investigating between rounds — check docs, search, or scout as needed to make each round's questions smarter. But the first-round investigation is mandatory and explicit. Distribute searches across turns rather than clustering them in one turn.
 
+## Question Rounds
+
+Ask **1–3 questions per round**. Keep each round tightly focused on one or two of the depth checklist dimensions — do not try to cover all six in one round.
+
+**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` for each round. 1–3 questions per call, each as a separate question object. Keep option labels short (3–5 words). Always include a freeform "Other / let me explain" option. When the user picks that option or writes a long freeform answer, switch to plain text follow-up for that thread before resuming structured questions. **IMPORTANT: Call `ask_user_questions` exactly once per turn. Never make multiple calls with the same or overlapping questions — wait for the user's response before asking the next round.**
+
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask questions in plain text. Keep each round to 1–3 focused questions. Wait for answers before asking the next round.
+
+After each answer set, investigate further if any answer opens a new unknown, then ask the next round.
+
+### Round cadence
+
+After each round of answers, decide whether you already have enough depth to write strong output.
+
+- **Incremental persistence:** After every 2 question rounds, silently save a `{{milestoneId}}-CONTEXT-DRAFT.md` using `gsd_summary_save` with `artifact_type: "CONTEXT-DRAFT"` and `milestone_id: "{{milestoneId}}"`. This protects confirmed work against session crashes. Do NOT mention this save to the user.
+- If not ready, continue to the next round immediately. Do **not** ask a meta "ready to wrap up?" question after every round.
+- **Depth-matching rule:** Simple, well-defined work needs fewer rounds — maybe 1–2. Large, ambiguous visions need more — maybe 4+. Do not pad rounds to hit a number. Stop when the Depth Enforcement checklist below is fully satisfied.
+- Do not count the reflection step as a question round. Rounds start after reflection is confirmed.
+- When you genuinely believe the depth checklist is satisfied, move to the Depth Verification step below. Do not ask a separate "ready to wrap up?" gate — the depth verification IS the gate.
+
 ## Questioning Philosophy
 
 You are a thinking partner, not an interviewer.
@@ -94,29 +114,27 @@ Do NOT offer to proceed until ALL of the following are satisfied. Track these in
 
 Before offering to proceed, demonstrate absorption: reference specific things the user emphasized, specific terminology they used, specific nuance they sharpened — and show how those shaped your understanding. Synthesize, don't recite. "Your emphasis on X led me to prioritize Y over Z" is good. "You said X, you said Y, you said Z" is not. The user should feel heard in the specifics, not just acknowledged in the abstract.
 
-**Questioning depth should match scope.** Simple, well-defined work needs fewer rounds — maybe 1-2. Large, ambiguous visions need more — maybe 4+. Don't pad rounds to hit a number. Stop when the depth checklist is satisfied and you genuinely understand the work.
-
-Do not count the reflection step as a question round. Rounds start after reflection is confirmed.
-
 ## Depth Verification
 
 Before moving to the wrap-up gate, present a structured depth summary as a checkpoint.
 
 **Print the summary as normal chat text first** — this is where the formatting renders properly. Structure the summary across the depth checklist dimensions using the user's own terminology and framing. Cover: what you understood them to be building, what shaped your understanding most (their emphasis, constraints, concerns), and any areas where you're least confident in your understanding.
 
-**Then** use `ask_user_questions` with a short confirmation question — NOT the summary itself. The question field is designed for single sentences, not multi-paragraph summaries.
+**Then confirm:**
 
-**Convention:** The question ID must contain `depth_verification` (e.g., `depth_verification_confirm`). This naming convention enables downstream mechanical detection of this step.
+**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` with:
+- header: "Depth Check"
+- question: "Did I capture the depth right?"
+- options: "Yes, you got it (Recommended)", "Not quite — let me clarify"
+- **The question ID must contain `depth_verification`** (e.g., `depth_verification_confirm`) — this naming convention enables downstream mechanical detection and the write-gate.
 
-Example flow:
-1. Print in chat: the full depth summary with markdown formatting (headers, bold, bullets)
-2. Call `ask_user_questions` with: header "Depth Check", question "Did I capture the depth right?", options "Yes, you got it (Recommended)" and "Not quite — let me clarify"
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? If not, tell me what I missed." Wait for explicit confirmation before proceeding. **The same non-bypassable gate applies to the plain-text path** — if the user does not respond, gives an ambiguous answer, or does not explicitly confirm, you MUST re-ask. Never rationalize past a missing confirmation.
 
 If they clarify, absorb the correction and re-verify.
 
 The depth verification is the required write-gate. Do **not** add another meta "ready to proceed?" checkpoint immediately after it unless there is still material ambiguity.
 
-**CRITICAL — Non-bypassable gate:** The system mechanically blocks CONTEXT.md writes until the user selects the "(Recommended)" option. If the user declines, cancels, or the tool fails, you MUST re-ask — never rationalize past the block ("tool not responding, I'll proceed" is forbidden). The gate exists to protect the user's work; treat a block as an instruction, not an obstacle to work around.
+**CRITICAL — Non-bypassable gate:** The system mechanically blocks CONTEXT.md writes until the user selects the "(Recommended)" option (structured path) or explicitly confirms (plain-text path). If the user declines, cancels, does not respond, or the tool fails, you MUST re-ask — never rationalize past the block ("tool not responding, I'll proceed" is forbidden). The gate exists to protect the user's work; treat a block as an instruction, not an obstacle to work around.
 
 ## Wrap-up Gate
 
@@ -244,7 +262,7 @@ If a milestone has no dependencies, omit the frontmatter. The dependency chain f
 
 #### Phase 3: Sequential readiness gate for remaining milestones
 
-For each remaining milestone **one at a time, in sequence**, decide the most likely readiness mode from the evidence you already have, then use `ask_user_questions` to let the user correct that recommendation. **Non-bypassable:** If `ask_user_questions` fails, errors, returns no response, or the user's response does not match a provided option, you MUST re-ask — never rationalize past the block or auto-select a readiness mode. Present three options:
+For each remaining milestone **one at a time, in sequence**, decide the most likely readiness mode from the evidence you already have, then present the three options below to the user. **If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions`. **If `{{structuredQuestionsAvailable}}` is `false`:** present the options as a plain-text numbered list and ask the user to type their choice. **Non-bypassable:** If the user does not respond, gives an ambiguous answer, or the tool fails, you MUST re-ask — never rationalize past the block or auto-select a readiness mode. Present three options:
 
 - **"Discuss now"** — The user wants to conduct a focused discussion for this milestone in the current session, while the context from the broader discussion is still fresh. Proceed with a focused discussion for this milestone (reflection → investigation → questioning → depth verification). When the discussion concludes, write a full `CONTEXT.md`. Then move to the gate for the next milestone.
 - **"Write draft for later"** — This milestone has seed material from the current conversation but needs its own dedicated discussion in a future session. Write a `CONTEXT-DRAFT.md` capturing the seed material (what was discussed, key ideas, provisional scope, open questions). Mark it clearly as a draft, not a finalized context. **What happens downstream:** When auto-mode reaches this milestone, it pauses and notifies the user: "M00x has draft context — needs discussion. Run /gsd." The `/gsd` wizard shows a "Discuss from draft" option that seeds the new discussion with this draft, so nothing from the current conversation is lost. After the dedicated discussion produces a full CONTEXT.md, the draft file is automatically deleted.
@@ -256,9 +274,9 @@ Before writing each milestone's CONTEXT.md (whether primary or secondary), you M
 
 1. **Read the actual code** for every file or module you reference. Confirm APIs exist, check what functions actually do, identify phantom capabilities (code that exists but isn't wired up).
 2. **Check for stale assumptions** — the codebase changes. Verify referenced modules still work as described.
-3. **Present findings** — use `ask_user_questions` with a question ID containing BOTH `depth_verification` AND the milestone ID (e.g., `depth_verification_M002`). Present: what you're about to write, key technical findings from investigation, risks the code review surfaced.
+3. **Present findings** — **If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` with a question ID containing BOTH `depth_verification` AND the milestone ID (e.g., `depth_verification_M002`). Present: what you're about to write, key technical findings from investigation, risks the code review surfaced. **If `{{structuredQuestionsAvailable}}` is `false`:** present the same findings in plain text and ask for explicit confirmation before proceeding.
 
-**The system mechanically blocks CONTEXT.md writes until the per-milestone depth verification passes.** Each milestone needs its own verification — one global verification does not unlock all milestones.
+**The system mechanically blocks CONTEXT.md writes until the per-milestone depth verification passes** (structured path: user selects "(Recommended)" option; plain-text path: user explicitly confirms). Each milestone needs its own verification — one global verification does not unlock all milestones.
 
 **Why sequential, not batch:** After writing the primary milestone's context and roadmap, the agent still has context window capacity. Asking one milestone at a time lets the user decide per-milestone whether to invest that remaining capacity in a focused discussion now, or defer to a future session. A batch question ("Ready/Draft/Queue for M002, M003, M004?") forces the user to decide everything upfront without knowing how much session capacity remains.
 

package/src/resources/extensions/gsd/tests/discuss-incremental-persistence.test.ts

@@ -27,10 +27,19 @@ describe("discuss incremental persistence (#2152)", () => {
     assert.match(content, /Incremental persistence/, "should have incremental persistence section");
   });
 
+  test("new-project discuss prompt includes CONTEXT-DRAFT save instruction", () => {
+    const content = readFileSync(join(promptsDir, "discuss.md"), "utf-8");
+    assert.match(content, /CONTEXT-DRAFT/, "should mention CONTEXT-DRAFT");
+    assert.match(content, /Incremental persistence/, "should have incremental persistence section");
+    assert.match(content, /gsd_summary_save/, "should use gsd_summary_save tool");
+  });
+
   test("drafts are saved silently without user notification", () => {
     const milestone = readFileSync(join(promptsDir, "guided-discuss-milestone.md"), "utf-8");
     const slice = readFileSync(join(promptsDir, "guided-discuss-slice.md"), "utf-8");
+    const discuss = readFileSync(join(promptsDir, "discuss.md"), "utf-8");
     assert.match(milestone, /Do NOT mention this save to the user/);
     assert.match(slice, /Do NOT mention this to the user/);
+    assert.match(discuss, /Do NOT mention this save to the user/);
   });
 });

package/src/resources/extensions/gsd/tests/workflow-mcp-auto-prep.test.ts

@@ -0,0 +1,76 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { prepareWorkflowMcpForProject, shouldAutoPrepareWorkflowMcp } from "../workflow-mcp-auto-prep.ts";
+
+test("shouldAutoPrepareWorkflowMcp enables prep for externalCli local transport", () => {
+  const result = shouldAutoPrepareWorkflowMcp({
+    model: { provider: "claude-code", baseUrl: "local://claude-code" },
+    modelRegistry: {
+      getProviderAuthMode: () => "externalCli",
+      isProviderRequestReady: () => false,
+    },
+  });
+
+  assert.equal(result, true);
+});
+
+test("shouldAutoPrepareWorkflowMcp enables prep when claude-code provider is ready", () => {
+  const result = shouldAutoPrepareWorkflowMcp({
+    model: { provider: "openai", baseUrl: "https://api.openai.com" },
+    modelRegistry: {
+      getProviderAuthMode: () => "apiKey",
+      isProviderRequestReady: (provider: string) => provider === "claude-code",
+    },
+  });
+
+  assert.equal(result, true);
+});
+
+test("shouldAutoPrepareWorkflowMcp enables prep when claude-code provider is registered", () => {
+  const result = shouldAutoPrepareWorkflowMcp({
+    model: { provider: "openai", baseUrl: "https://api.openai.com" },
+    modelRegistry: {
+      getProviderAuthMode: (provider: string) => provider === "claude-code" ? "externalCli" : "apiKey",
+      isProviderRequestReady: () => false,
+    },
+  });
+
+  assert.equal(result, true);
+});
+
+test("shouldAutoPrepareWorkflowMcp stays disabled when neither transport nor provider readiness match", () => {
+  const result = shouldAutoPrepareWorkflowMcp({
+    model: { provider: "openai", baseUrl: "https://api.openai.com" },
+    modelRegistry: {
+      getProviderAuthMode: () => "apiKey",
+      isProviderRequestReady: () => false,
+    },
+  });
+
+  assert.equal(result, false);
+});
+
+test("prepareWorkflowMcpForProject warns with /gsd mcp init guidance when prep fails", () => {
+  const notifications: Array<{ message: string; level: "info" | "warning" | "error" | "success" }> = [];
+  const result = prepareWorkflowMcpForProject(
+    {
+      model: { provider: "claude-code", baseUrl: "local://claude-code" },
+      modelRegistry: {
+        getProviderAuthMode: () => "externalCli",
+        isProviderRequestReady: () => true,
+      },
+      ui: {
+        notify: (message: string, level?: "info" | "warning" | "error" | "success") => {
+          notifications.push({ message, level: level ?? "info" });
+        },
+      },
+    },
+    "/",
+  );
+
+  assert.equal(result, null);
+  assert.equal(notifications.length, 1);
+  assert.equal(notifications[0].level, "warning");
+  assert.match(notifications[0].message, /Please run \/gsd mcp init \./);
+});