@opengsd/gsd-pi 1.3.0 → 1.4.0

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

@@ -74,6 +74,7 @@ import {
 	endWorkflowMcpSdkSession,
 } from "../gsd/workflow-mcp-readiness-cache.js";
 import { getGuidedUnitContext } from "../gsd/guided-unit-context.js";
+import { getActiveAutoUnitType, isAutoActive } from "../gsd/auto-runtime-state.js";
 import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
 import { showInterviewRound, type Question, type RoundResult } from "../shared/tui.js";
 import type {
@@ -100,6 +101,7 @@ export type {
 interface PromptToolContextOptions {
 	workflowMcpServerName?: string | null;
 	browserMcpServerName?: string | null;
+	questionToolAvailable?: boolean;
 }
 
 /** `SimpleStreamOptions` extended with an optional extension UI context for elicitation dialogs. */
@@ -365,31 +367,46 @@ function extractMessageText(msg: { role: string; content: unknown }): string {
 	return "";
 }
 
+// Patterns are anchored to the `UNIT: <Phase>` dispatch header ONLY. The old
+// patterns also matched bare slugs (`run-uat`, `plan-slice`, `gsd_plan_slice`,
+// …) anywhere in the text, so any incidental occurrence — a branch name like
+// `milestone/M039`, an untracked file `m039-s05-…spec.ts`, a forensic report,
+// or the user literally typing "slice"/"UAT" while describing a problem — would
+// misclassify the turn as a dispatched unit. Only the dispatch header is an
+// authoritative phase signal, so match nothing else.
 const GSD_PHASE_PATTERNS: Array<[string, RegExp]> = [
-	["run-uat", /\b(?:UNIT:\s*Run UAT|run-uat)\b/i],
-	["complete-milestone", /\b(?:UNIT:\s*Complete Milestone|complete-milestone)\b/i],
-	["validate-milestone", /\b(?:UNIT:\s*Validate Milestone|validate-milestone)\b/i],
-	["reassess-roadmap", /\b(?:UNIT:\s*Reassess Roadmap|reassess-roadmap)\b/i],
-	["complete-slice", /\b(?:UNIT:\s*Complete Slice|complete-slice)\b/i],
-	["replan-slice", /\b(?:UNIT:\s*Replan Slice|replan-slice)\b/i],
-	["refine-slice", /\b(?:UNIT:\s*Refine Slice|refine-slice)\b/i],
-	["plan-slice", /\b(?:UNIT:\s*Plan Slice|plan-slice|gsd_plan_slice)\b/i],
-	["plan-milestone", /\b(?:UNIT:\s*Plan Milestone|plan-milestone|gsd_plan_milestone)\b/i],
-	["execute-task", /\b(?:UNIT:\s*Execute Task|execute-task|execute-task-simple|reactive-execute)\b/i],
-	["gate-evaluate", /\b(?:UNIT:\s*Gate Evaluate|gate-evaluate|gsd_save_gate_result)\b/i],
-	["research-milestone", /\b(?:UNIT:\s*Research Milestone|research-milestone)\b/i],
-	["research-slice", /\b(?:UNIT:\s*Research Slice|research-slice)\b/i],
-	["research-decision", /\b(?:research decision|research-decision)\b/i],
-	["discuss-milestone", /\b(?:Discuss milestone|discuss-milestone)\b/i],
-	["discuss-slice", /\b(?:Discuss slice|discuss-slice)\b/i],
-	["discuss-project", /\b(?:discuss-project|Discuss project)\b/i],
-	["discuss-requirements", /\b(?:discuss-requirements|Discuss requirements)\b/i],
+	["run-uat", /\bUNIT:\s*Run UAT\b/i],
+	["complete-milestone", /\bUNIT:\s*Complete Milestone\b/i],
+	["validate-milestone", /\bUNIT:\s*Validate Milestone\b/i],
+	["reassess-roadmap", /\bUNIT:\s*Reassess Roadmap\b/i],
+	["complete-slice", /\bUNIT:\s*Complete Slice\b/i],
+	["replan-slice", /\bUNIT:\s*Replan Slice\b/i],
+	["refine-slice", /\bUNIT:\s*Refine Slice\b/i],
+	["plan-slice", /\bUNIT:\s*Plan Slice\b/i],
+	["plan-milestone", /\bUNIT:\s*Plan Milestone\b/i],
+	["execute-task", /\bUNIT:\s*Execute Task\b/i],
+	["gate-evaluate", /\bUNIT:\s*Gate Evaluate\b/i],
+	["research-milestone", /\bUNIT:\s*Research Milestone\b/i],
+	["research-slice", /\bUNIT:\s*Research Slice\b/i],
+	["research-decision", /\bUNIT:\s*Research Decision\b/i],
+	["discuss-milestone", /\bUNIT:\s*Discuss Milestone\b/i],
+	["discuss-slice", /\bUNIT:\s*Discuss Slice\b/i],
+	["discuss-project", /\bUNIT:\s*Discuss Project\b/i],
+	["discuss-requirements", /\bUNIT:\s*Discuss Requirements\b/i],
 ];
 
+/** The set of GSD phases this adapter recognises, derived from the patterns above. */
+const KNOWN_GSD_PHASES = new Set(GSD_PHASE_PATTERNS.map(([phase]) => phase));
+
 export function inferGsdPhaseFromContext(context: Context): string | undefined {
+	// Scan only the system prompt and the most recent user directive. Scanning
+	// the entire scrollback let a phase header that merely appeared in history
+	// (e.g. a SUMMARY the agent read, or a pasted prior dispatch) re-classify
+	// every subsequent turn.
+	const lastUser = [...context.messages].reverse().find((m) => m.role === "user");
 	const text = [
 		context.systemPrompt ?? "",
-		...context.messages.map((message) => extractMessageText(message)),
+		lastUser ? extractMessageText(lastUser) : "",
 	].join("\n");
 	for (const [phase, pattern] of GSD_PHASE_PATTERNS) {
 		if (pattern.test(text)) return phase;
@@ -414,6 +431,27 @@ export function resolveGsdPhaseForSdk(context: Context, projectRoot: string): st
 			return guided.unitType;
 		}
 	}
+	// Auto-mode records the dispatched unit type before each turn — that is the
+	// authoritative phase, so prefer it over any inference. (Guided interactive
+	// dispatch is handled above via getGuidedUnitContext.) Ignore `hook/*`
+	// pseudo-units and anything not a recognised GSD phase.
+	const autoUnit = getActiveAutoUnitType();
+	if (autoUnit && KNOWN_GSD_PHASES.has(autoUnit)) {
+		return autoUnit;
+	}
+
+	// No authoritative guided/auto signal → ad-hoc turn. Do NOT regex-infer a
+	// phase from prose: that would fire the workflow MCP preflight and, for
+	// run-uat, strip Bash/Write/Edit/gsd_exec for the rest of the session the
+	// moment the conversation (or the GSD system prompt itself) happened to
+	// mention a phase token. An ad-hoc turn keeps the full tool surface.
+	//
+	// The header-anchored inference remains only as a last resort while auto is
+	// running but the current unit wasn't recorded for some reason; even then it
+	// matches the `UNIT:` dispatch header only, never bare slugs in scrollback.
+	if (!isAutoActive()) {
+		return undefined;
+	}
 	return inferGsdPhaseFromContext(context);
 }
 
@@ -443,8 +481,10 @@ export function buildPromptFromContext(context: Context, toolContext: PromptTool
 		? "- GSD workflow tools (gsd_exec, gsd_slice_complete, gsd_task_complete, gsd_plan_slice, gsd_save_gate_result, etc.) " +
 			`are MCP tools — call them as mcp__${toolContext.workflowMcpServerName}__<tool_name> ` +
 			`(e.g. mcp__${toolContext.workflowMcpServerName}__gsd_exec, mcp__${toolContext.workflowMcpServerName}__gsd_save_gate_result)\n` +
-			`- Structured user input: call mcp__${toolContext.workflowMcpServerName}__ask_user_questions. ` +
-			"Do not call bare ask_user_questions. Do not call native AskUserQuestion.\n"
+			(toolContext.questionToolAvailable !== false
+				? `- Structured user input: call mcp__${toolContext.workflowMcpServerName}__ask_user_questions. ` +
+					"Do not call bare ask_user_questions. Do not call native AskUserQuestion.\n"
+				: "")
 		: "- GSD workflow MCP tools are unavailable in this Claude Code run.\n";
 	const toolSearchLine = toolContext.workflowMcpServerName
 		? "- ToolSearch is available only for Claude Code deferred workflow MCP hydration. " +
@@ -1716,6 +1756,16 @@ function workflowMcpServerNameFromAllowedTools(allowedTools: unknown): string |
 	return undefined;
 }
 
+function workflowQuestionToolAvailableFromAllowedTools(
+	allowedTools: unknown,
+	workflowMcpServerName: string | undefined,
+	gsdPhase: string | undefined,
+): boolean | undefined {
+	if (!workflowMcpServerName || !gsdPhase) return undefined;
+	return Array.isArray(allowedTools)
+		&& allowedTools.includes(`mcp__${workflowMcpServerName}__ask_user_questions`);
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -1724,6 +1774,15 @@ function isStringRecord(value: unknown): value is Record<string, string> {
 	return isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
 }
 
+export function resolveWorkflowMcpPreflightServerConfig(
+	mcpServers: unknown,
+	workflowServerName: string | undefined,
+): Record<string, unknown> | undefined {
+	if (!workflowServerName || !isRecord(mcpServers)) return undefined;
+	const workflowServerConfig = mcpServers[workflowServerName];
+	return isRecord(workflowServerConfig) ? workflowServerConfig : undefined;
+}
+
 function cloneSdkMcpServerConfig(config: unknown): Record<string, unknown> | undefined {
 	if (!isRecord(config)) return undefined;
 	const cloned: Record<string, unknown> = {};
@@ -2103,6 +2162,19 @@ export function buildSdkOptions(
 // streamSimple implementation
 // ---------------------------------------------------------------------------
 
+let capturedClaudeCodeUIContext: ExtensionUIContext | undefined;
+
+/**
+ * Capture the active extension UI context from `before_provider_request`. Core
+ * invokes `streamSimple` with a plain `SimpleStreamOptions` (no
+ * `extensionUIContext`), so without this the elicitation handler is never wired
+ * and `ask_user_questions` immediately returns cancelled. See index.ts, which
+ * registers the hook that calls this.
+ */
+export function setClaudeCodeUIContext(ui: ExtensionUIContext | undefined): void {
+	capturedClaudeCodeUIContext = ui;
+}
+
 /**
  * GSD streamSimple function that delegates to the Claude Agent SDK.
  *
@@ -2152,7 +2224,7 @@ async function pumpSdkMessages(
 	try {
 		const permissionMode = await resolveClaudePermissionMode();
 		const claudeOptions = options as ClaudeCodeStreamOptions | undefined;
-		const uiContext = claudeOptions?.extensionUIContext;
+		const uiContext = claudeOptions?.extensionUIContext ?? capturedClaudeCodeUIContext;
 		const onExternalToolCall = claudeOptions?.onExternalToolCall;
 		const onExternalToolResult = claudeOptions?.onExternalToolResult;
 		const sdkQueryForTest = claudeOptions?._sdkQueryForTest;
@@ -2198,6 +2270,11 @@ async function pumpSdkMessages(
 		const prompt = buildPromptFromContext(context, {
 			workflowMcpServerName,
 			browserMcpServerName: browserMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
+			questionToolAvailable: workflowQuestionToolAvailableFromAllowedTools(
+				sdkOpts.allowedTools,
+				workflowMcpServerName,
+				gsdPhase,
+			),
 		});
 		const queryPrompt = buildSdkQueryPrompt(context, prompt);
 
@@ -2239,6 +2316,10 @@ async function pumpSdkMessages(
 						unitType: gsdPhase,
 						workflowServerName: workflowMcpServerName,
 						projectRoot,
+						workflowServerConfig: resolveWorkflowMcpPreflightServerConfig(
+							sdkOpts.mcpServers,
+							workflowMcpServerName,
+						),
 						signal: options?.signal,
 					});
 					if (preflightError) {

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

@@ -0,0 +1,61 @@
+// gsd-pi - Claude Code CLI extension wiring tests
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import claudeCodeCli from "../index.ts";
+
+type Handler = (event: unknown, ctx: unknown) => unknown;
+
+function makeMockPi() {
+	const handlers = new Map<string, Handler[]>();
+	const providers: Array<{ name: string; config: Record<string, unknown> }> = [];
+	const pi = {
+		on(event: string, handler: Handler) {
+			const list = handlers.get(event) ?? [];
+			list.push(handler);
+			handlers.set(event, list);
+		},
+		registerProvider(name: string, config: Record<string, unknown>) {
+			providers.push({ name, config });
+		},
+	};
+	return { pi, handlers, providers };
+}
+
+test("registers the claude-code provider with a streamSimple delegate", () => {
+	const { pi, providers } = makeMockPi();
+	claudeCodeCli(pi as never);
+
+	assert.equal(providers.length, 1);
+	assert.equal(providers[0].name, "claude-code");
+	assert.equal(typeof providers[0].config.streamSimple, "function");
+});
+
+test("registers Claude Sonnet 5 as a Claude Code CLI model", () => {
+	const { pi, providers } = makeMockPi();
+	claudeCodeCli(pi as never);
+
+	const models = providers[0].config.models as Array<Record<string, unknown>>;
+	const sonnet5 = models.find((model) => model.id === "claude-sonnet-5");
+
+	assert.ok(sonnet5, "claude-sonnet-5 must be selectable via the claude-code provider");
+	assert.equal(sonnet5.name, "Claude Sonnet 5 (via Claude Code)");
+	assert.equal(sonnet5.reasoning, true);
+	assert.equal(sonnet5.contextWindow, 1_000_000);
+	assert.equal(sonnet5.maxTokens, 128_000);
+});
+
+test("registers a before_provider_request hook to capture the UI context", () => {
+	const { pi, handlers } = makeMockPi();
+	claudeCodeCli(pi as never);
+
+	const registered = handlers.get("before_provider_request");
+	assert.ok(registered && registered.length === 1, "before_provider_request handler must be registered");
+
+	// Without this hook, core calls streamSimple with no UI context and
+	// ask_user_questions self-cancels. The handler must accept both UI states
+	// without throwing and must not mutate the provider payload.
+	const handler = registered[0];
+	const sentinelUi = { kind: "ui" };
+	assert.equal(handler({ type: "before_provider_request" }, { hasUI: true, ui: sentinelUi }), undefined);
+	assert.equal(handler({ type: "before_provider_request" }, { hasUI: false, ui: sentinelUi }), undefined);
+});

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

@@ -45,11 +45,13 @@ import {
 	shouldRetryClaudeCodeToolSurfaceReadiness,
 	buildWorkflowMcpReadinessProgressMessage,
 	pushWorkflowMcpReadinessProgressEvent,
+	resolveWorkflowMcpPreflightServerConfig,
 } from "../stream-adapter.ts";
 import { CLAUDE_CODE_MODELS } from "../models.ts";
 import type { AssistantMessage, Context, Message } from "@gsd/pi-ai";
 import type { SDKUserMessage } from "../sdk-types.ts";
 import { _setAutoActiveForTest } from "../../gsd/auto.ts";
+import { autoSession } from "../../gsd/auto-runtime-state.ts";
 import { getInFlightToolCount, hasInteractiveToolInFlight, clearInFlightTools, isInteractiveElicitationInFlight } from "../../gsd/auto-tool-tracking.ts";
 import { clearMcpConfigCache } from "../../mcp-client/manager.ts";
 import { UNIT_TOOL_CONTRACTS } from "../../gsd/unit-tool-contracts.ts";
@@ -405,6 +407,10 @@ describe("stream-adapter — image prompt forwarding (#4183)", () => {
 			systemPrompt: "UNIT: Run UAT",
 			messages: [{ role: "user", content: "Run UAT." } as Message],
 		};
+		// The test requires a resolved GSD phase so the readiness gate fires.
+		// Auto-mode with a currentUnit provides the authoritative phase signal.
+		_setAutoActiveForTest(true);
+		autoSession.currentUnit = { type: "run-uat", id: "M001/S001", startedAt: 0, workspaceRoot: cwd } as never;
 		try {
 			const stream = streamViaClaudeCode(
 				{ id: "claude-sonnet-4-6" } as any,
@@ -473,6 +479,8 @@ describe("stream-adapter — image prompt forwarding (#4183)", () => {
 			assert.equal(queryCalls, 2);
 			assert.deepEqual(message.content, [{ type: "text", text: "fresh retry result" }]);
 		} finally {
+			autoSession.currentUnit = null;
+			_setAutoActiveForTest(false);
 			rmSync(cwd, { recursive: true, force: true });
 		}
 	});
@@ -1543,18 +1551,43 @@ describe("stream-adapter — session persistence (#2859)", () => {
 		assert.equal(inferGsdPhaseFromContext(context), "plan-milestone");
 	});
 
-	test("inferGsdPhaseFromContext recognizes discuss-slice and refine-slice prompts", () => {
-		const discussSlice = {
-			messages: [{ role: "user", content: "Discuss slice S001 in milestone M001." }],
-		} as Context;
+	test("inferGsdPhaseFromContext recognizes the refine-slice UNIT header", () => {
 		const refineSlice = {
 			messages: [{ role: "user", content: "## UNIT: Refine Slice S001 (\"Auth\") - Milestone M001" }],
 		} as Context;
 
-		assert.equal(inferGsdPhaseFromContext(discussSlice), "discuss-slice");
 		assert.equal(inferGsdPhaseFromContext(refineSlice), "refine-slice");
 	});
 
+	test("inferGsdPhaseFromContext ignores bare phase slugs and prose (only the UNIT header counts)", () => {
+		// Prose mentioning a phase must NOT classify the turn — this was the leak
+		// that stripped tools the moment a user said "slice" or "UAT".
+		const prose = {
+			messages: [{ role: "user", content: "Can you discuss the slice S001 and then run UAT for me?" }],
+		} as Context;
+		const bareSlug = {
+			messages: [{ role: "user", content: "I edited e2e/m039-s05-comparison-legibility.spec.ts (plan-slice, run-uat)" }],
+		} as Context;
+
+		assert.equal(inferGsdPhaseFromContext(prose), undefined);
+		assert.equal(inferGsdPhaseFromContext(bareSlug), undefined);
+	});
+
+	test("inferGsdPhaseFromContext does not match a UNIT header buried in scrollback", () => {
+		// A UNIT header from a prior turn (e.g. a SUMMARY the agent read) must not
+		// re-classify later ad-hoc turns. Only the system prompt + latest user
+		// message are scanned.
+		const context = {
+			messages: [
+				{ role: "user", content: "## UNIT: Run UAT — M001/S001" },
+				{ role: "assistant", content: "Done." },
+				{ role: "user", content: "Thanks, now what files changed?" },
+			],
+		} as Context;
+
+		assert.equal(inferGsdPhaseFromContext(context), undefined);
+	});
+
 	test("resolveGsdPhaseForSdk prefers guided unit context over prompt inference", () => {
 		const projectRoot = "/tmp/gsd-guided-phase-project";
 		clearGuidedUnitContext();
@@ -1582,12 +1615,67 @@ describe("stream-adapter — session persistence (#2859)", () => {
 		}
 	});
 
-	test("resolveGsdPhaseForSdk falls back to prompt inference when guided context is absent", () => {
+	test("resolveGsdPhaseForSdk returns undefined for ad-hoc turns (no guided context, auto inactive)", () => {
+		// The core bug: an ad-hoc turn must keep the full tool surface even when
+		// its text contains a UNIT header (e.g. pasted from a prior unit). No
+		// guided context + auto inactive => no phase, no preflight, no stripping.
 		clearGuidedUnitContext();
-		const context = {
-			messages: [{ role: "user", content: "## UNIT: Run UAT — M001/S001" }],
-		} as Context;
-		assert.equal(resolveGsdPhaseForSdk(context, "/tmp/unrelated-project"), "run-uat");
+		_setAutoActiveForTest(false);
+		try {
+			const context = {
+				messages: [{ role: "user", content: "## UNIT: Run UAT — M001/S001 (pasted from earlier)" }],
+			} as Context;
+			assert.equal(resolveGsdPhaseForSdk(context, "/tmp/unrelated-project"), undefined);
+		} finally {
+			_setAutoActiveForTest(false);
+		}
+	});
+
+	test("resolveGsdPhaseForSdk uses the authoritative auto currentUnit, even with no UNIT header in the prompt", () => {
+		// gate-evaluate / validate-milestone dispatch prompts have no `UNIT:`
+		// header, so header inference alone would drop their phase (and their
+		// workflow-MCP preflight). The dispatched unit type is authoritative.
+		clearGuidedUnitContext();
+		_setAutoActiveForTest(true);
+		autoSession.currentUnit = { type: "gate-evaluate", id: "M001/S001", startedAt: 0, workspaceRoot: "/tmp/p" } as never;
+		try {
+			const context = {
+				messages: [{ role: "user", content: "Quality Gate Evaluation — Parallel Dispatch. Call gsd_save_gate_result." }],
+			} as Context;
+			assert.equal(resolveGsdPhaseForSdk(context, "/tmp/p"), "gate-evaluate");
+		} finally {
+			autoSession.currentUnit = null;
+			_setAutoActiveForTest(false);
+		}
+	});
+
+	test("resolveGsdPhaseForSdk ignores hook/* pseudo-units from currentUnit", () => {
+		clearGuidedUnitContext();
+		_setAutoActiveForTest(true);
+		autoSession.currentUnit = { type: "hook/agent-end", id: "x", startedAt: 0, workspaceRoot: "/tmp/p" } as never;
+		try {
+			const context = { messages: [{ role: "user", content: "no phase here" }] } as Context;
+			assert.equal(resolveGsdPhaseForSdk(context, "/tmp/p"), undefined);
+		} finally {
+			autoSession.currentUnit = null;
+			_setAutoActiveForTest(false);
+		}
+	});
+
+	test("resolveGsdPhaseForSdk infers from the UNIT header only while auto-mode is active and no currentUnit is recorded", () => {
+		// Last-resort fallback: auto running but currentUnit unexpectedly absent.
+		// Classifies from the `UNIT:` dispatch header only.
+		clearGuidedUnitContext();
+		_setAutoActiveForTest(true);
+		autoSession.currentUnit = null;
+		try {
+			const context = {
+				messages: [{ role: "user", content: "## UNIT: Run UAT — M001/S001" }],
+			} as Context;
+			assert.equal(resolveGsdPhaseForSdk(context, "/tmp/unrelated-project"), "run-uat");
+		} finally {
+			_setAutoActiveForTest(false);
+		}
 	});
 
 	test("buildSdkOptions presents ask_user_questions for discuss phases", () => {
@@ -1913,6 +2001,170 @@ describe("stream-adapter — session persistence (#2859)", () => {
 });
 
 describe("stream-adapter — workflow MCP readiness", () => {
+	test("strict slice phase prompt omits workflow MCP question guidance when allowedTools omit it", async () => {
+		const cwd = realpathSync(mkdtempSync(join(tmpdir(), "claude-sdk-strict-question-prompt-")));
+		const restore = setWorkflowMcpEnv({
+			GSD_WORKFLOW_MCP_COMMAND: process.execPath,
+			GSD_WORKFLOW_MCP_NAME: "gsd-workflow",
+			GSD_WORKFLOW_MCP_ARGS: JSON.stringify(["-e", ""]),
+			GSD_WORKFLOW_MCP_CWD: cwd,
+		});
+		const phases = [
+			{ type: "research-slice", label: "Research Slice", expectedTool: "mcp__gsd-workflow__gsd_summary_save" },
+			{ type: "plan-slice", label: "Plan Slice", expectedTool: "mcp__gsd-workflow__gsd_plan_slice" },
+			{ type: "refine-slice", label: "Refine Slice", expectedTool: "mcp__gsd-workflow__gsd_plan_slice" },
+		] as const;
+		clearGuidedUnitContext();
+		_setAutoActiveForTest(true);
+		try {
+			for (const phase of phases) {
+				let capturedPrompt: unknown;
+				let capturedAllowedTools: string[] | undefined;
+				autoSession.currentUnit = { type: phase.type, id: "M001/S001", startedAt: 0, workspaceRoot: cwd } as never;
+				const stream = streamViaClaudeCode(
+					{ id: "claude-sonnet-4-6" } as any,
+					{
+						systemPrompt: `UNIT: ${phase.label}`,
+						messages: [{ role: "user", content: "Complete the strict slice phase." } as Message],
+					},
+					{
+						cwd,
+						_skipWorkflowMcpPreflightForTest: true,
+						async *_sdkQueryForTest(args: {
+							prompt: string | AsyncIterable<unknown>;
+							options?: Record<string, unknown>;
+						}) {
+							capturedPrompt = args.prompt;
+							capturedAllowedTools = args.options?.allowedTools as string[] | undefined;
+							yield {
+								type: "result",
+								subtype: "success",
+								uuid: `result-${phase.type}`,
+								session_id: `session-${phase.type}`,
+								duration_ms: 1,
+								duration_api_ms: 1,
+								is_error: false,
+								num_turns: 1,
+								result: "completed",
+								stop_reason: "end_turn",
+								total_cost_usd: 0,
+								usage: {
+									input_tokens: 0,
+									output_tokens: 0,
+									cache_read_input_tokens: 0,
+									cache_creation_input_tokens: 0,
+								},
+							};
+						},
+					} as any,
+				);
+
+				await stream.result();
+
+				assert.equal(typeof capturedPrompt, "string", phase.type);
+				const prompt = capturedPrompt as string;
+				assert.ok(capturedAllowedTools?.includes(phase.expectedTool), phase.type);
+				assert.ok(!capturedAllowedTools?.includes("mcp__gsd-workflow__ask_user_questions"), phase.type);
+				assert.ok(!prompt.includes("mcp__gsd-workflow__ask_user_questions"), phase.type);
+				assert.ok(!prompt.includes("Do not call bare ask_user_questions"), phase.type);
+				assert.ok(
+					prompt.includes("ToolSearch is available only for Claude Code deferred workflow MCP hydration"),
+					phase.type,
+				);
+			}
+		} finally {
+			autoSession.currentUnit = null;
+			_setAutoActiveForTest(false);
+			restore();
+			rmSync(cwd, { recursive: true, force: true });
+			clearMcpConfigCache();
+		}
+	});
+
+	test("resolves the workflow MCP preflight config from SDK mcpServers", () => {
+		const workflowConfig = { command: "node", args: ["workflow-server.js"] };
+		const browserConfig = { command: "gsd-browser" };
+
+		assert.equal(
+			resolveWorkflowMcpPreflightServerConfig(
+				{ "gsd-workflow": workflowConfig, "gsd-browser": browserConfig },
+				"gsd-workflow",
+			),
+			workflowConfig,
+		);
+		assert.equal(resolveWorkflowMcpPreflightServerConfig({ "gsd-workflow": "invalid" }, "gsd-workflow"), undefined);
+		assert.equal(resolveWorkflowMcpPreflightServerConfig({ "gsd-workflow": workflowConfig }, undefined), undefined);
+	});
+
+	test("workflow MCP preflight uses the same inline config passed to the SDK", async () => {
+		const projectRoot = realpathSync(mkdtempSync(join(tmpdir(), "claude-sdk-inline-preflight-")));
+		const restore = setWorkflowMcpEnv({});
+		let queryCalls = 0;
+		try {
+			const require = createRequire(import.meta.url);
+			const mcpModuleUrl = pathToFileURL(require.resolve("@modelcontextprotocol/sdk/server/mcp.js")).href;
+			const stdioModuleUrl = pathToFileURL(require.resolve("@modelcontextprotocol/sdk/server/stdio.js")).href;
+			const serverPath = join(projectRoot, "fake-workflow-mcp-server.mjs");
+			writeFileSync(
+				serverPath,
+				[
+					`const { McpServer } = await import(${JSON.stringify(mcpModuleUrl)});`,
+					`const { StdioServerTransport } = await import(${JSON.stringify(stdioModuleUrl)});`,
+					'const server = new McpServer({ name: "fake", version: "1.0.0" }, { capabilities: { tools: {} } });',
+					'server.tool("gsd_plan_slice", "Plan slice", {}, async () => ({ content: [{ type: "text", text: "ok" }] }));',
+					'server.tool("gsd_reassess_roadmap", "Reassess roadmap", {}, async () => ({ content: [{ type: "text", text: "ok" }] }));',
+					'await server.connect(new StdioServerTransport());',
+				].join("\n"),
+				"utf-8",
+			);
+			process.env.GSD_WORKFLOW_MCP_COMMAND = process.execPath;
+			process.env.GSD_WORKFLOW_MCP_ARGS = JSON.stringify([serverPath]);
+			process.env.GSD_WORKFLOW_MCP_NAME = "gsd-workflow";
+
+			const stream = streamViaClaudeCode(
+				{ id: "claude-sonnet-4-6" } as any,
+				{
+					systemPrompt: "UNIT: Plan Slice",
+					messages: [{ role: "user", content: "Plan the next slice." } as Message],
+				},
+				{
+					cwd: projectRoot,
+					async *_sdkQueryForTest() {
+						queryCalls += 1;
+						yield {
+							type: "result",
+							subtype: "success",
+							uuid: "result-1",
+							session_id: "session-1",
+							duration_ms: 1,
+							duration_api_ms: 1,
+							is_error: false,
+							num_turns: 1,
+							result: "planned",
+							stop_reason: "end_turn",
+							total_cost_usd: 0,
+							usage: {
+								input_tokens: 0,
+								output_tokens: 0,
+								cache_read_input_tokens: 0,
+								cache_creation_input_tokens: 0,
+							},
+						};
+					},
+				} as any,
+			);
+
+			const message = await stream.result();
+
+			assert.equal(queryCalls, 1);
+			assert.deepEqual(message.content, [{ type: "text", text: "planned" }]);
+		} finally {
+			restore();
+			rmSync(projectRoot, { recursive: true, force: true });
+			clearMcpConfigCache();
+		}
+	});
+
 	test("emits visible progress text before workflow MCP readiness waits", () => {
 		const partial: AssistantMessage = {
 			role: "assistant",