@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

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

@@ -1,10 +1,14 @@
 // gsd-pi - Claude Code stream adapter regression tests
 import { describe, test } from "node:test";
+import { clearGuidedUnitContext, setGuidedUnitContext } from "../../gsd/guided-unit-context.ts";
 import assert from "node:assert/strict";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
+import { pathToFileURL } from "node:url";
 import {
+	streamViaClaudeCode,
 	makeStreamExhaustedErrorMessage,
 	isClaudeCodeAbortErrorMessage,
 	resolveClaudeCodeAbortedMessageText,
@@ -35,9 +39,22 @@ import {
 	roundResultToElicitationContent,
 	autoInitClaudeCodeWorkflowMcp,
 	inferGsdPhaseFromContext,
+	resolveGsdPhaseForSdk,
+	resolveClaudeCodeToolSurfaceReadinessError,
+	resolveClaudeCodeToolSurfaceReadinessRetryDelayMs,
+	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";
 
 // ---------------------------------------------------------------------------
 // Env helpers — `GSD_WORKFLOW_MCP_*` save/restore
@@ -58,6 +75,7 @@ const WORKFLOW_MCP_ENV_KEYS = [
 	"GSD_WORKFLOW_MCP_ARGS",
 	"GSD_WORKFLOW_MCP_ENV",
 	"GSD_WORKFLOW_MCP_CWD",
+	"GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS",
 	"GSD_PROJECT_ROOT",
 	"GSD_WORKFLOW_PROJECT_ROOT",
 ] as const;
@@ -352,6 +370,120 @@ describe("stream-adapter — image prompt forwarding (#4183)", () => {
 			parent_tool_use_id: null,
 		});
 	});
+
+	test("buildSdkQueryPrompt image iterable can be consumed for each SDK retry", async () => {
+		const context: Context = {
+			messages: [
+				{
+					role: "user",
+					content: [
+						{ type: "image", data: "ZmFrZQ==", mimeType: "image/jpeg" },
+						{ type: "text", text: "Retry with this image." },
+					],
+				} as Message,
+			],
+		};
+		const textPrompt = buildPromptFromContext(context);
+		const prompt = buildSdkQueryPrompt(context, textPrompt);
+
+		const firstAttempt = [];
+		for await (const item of prompt as AsyncIterable<any>) {
+			firstAttempt.push(item);
+		}
+
+		const retryAttempt = [];
+		for await (const item of prompt as AsyncIterable<any>) {
+			retryAttempt.push(item);
+		}
+
+		assert.equal(firstAttempt.length, 1);
+		assert.deepEqual(retryAttempt, firstAttempt);
+	});
+
+	test("SDK readiness retries do not leak partial content into the next attempt", async () => {
+		let queryCalls = 0;
+		const cwd = mkdtempSync(join(tmpdir(), "claude-sdk-retry-state-"));
+		const context: Context = {
+			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,
+				context,
+				{
+					cwd,
+					_skipWorkflowMcpPreflightForTest: true,
+					async *_sdkQueryForTest() {
+						queryCalls += 1;
+						if (queryCalls === 1) {
+							yield {
+								type: "stream_event",
+								event: { type: "message_start", message: { model: "claude-sonnet-4-6" } },
+								parent_tool_use_id: null,
+								uuid: "partial-1",
+								session_id: "session-1",
+							};
+							yield {
+								type: "stream_event",
+								event: { type: "content_block_start", index: 0, content_block: { type: "text", text: "" } },
+								parent_tool_use_id: null,
+								uuid: "partial-1",
+								session_id: "session-1",
+							};
+							yield {
+								type: "stream_event",
+								event: { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "stale retry text" } },
+								parent_tool_use_id: null,
+								uuid: "partial-1",
+								session_id: "session-1",
+							};
+							yield {
+								type: "system",
+								subtype: "init",
+								tools: ["Read"],
+								mcp_servers: [{ name: "gsd-workflow", status: "connected" }],
+							};
+							return;
+						}
+
+						yield {
+							type: "result",
+							subtype: "success",
+							uuid: "result-2",
+							session_id: "session-2",
+							duration_ms: 1,
+							duration_api_ms: 1,
+							is_error: false,
+							num_turns: 1,
+							result: "fresh retry result",
+							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, 2);
+			assert.deepEqual(message.content, [{ type: "text", text: "fresh retry result" }]);
+		} finally {
+			autoSession.currentUnit = null;
+			_setAutoActiveForTest(false);
+			rmSync(cwd, { recursive: true, force: true });
+		}
+	});
 });
 
 // ---------------------------------------------------------------------------
@@ -457,6 +589,33 @@ describe("stream-adapter — no transcript fabrication (#4102)", () => {
 		assert.ok(!prompt.includes("mcp__gsd-workflow__<tool_name>"));
 	});
 
+	test("buildPromptFromContext remaps structured user input to the workflow MCP question tool", () => {
+		const context: Context = {
+			systemPrompt: "Use ask_user_questions for structured user input.",
+			messages: [{ role: "user", content: "Ask the user what comes next" } as Message],
+		};
+
+		const prompt = buildPromptFromContext(context, { workflowMcpServerName: "gsd-workflow" });
+
+		assert.ok(prompt.includes("mcp__gsd-workflow__ask_user_questions"));
+		assert.ok(prompt.includes("Do not call bare ask_user_questions"));
+		assert.ok(prompt.includes("Do not call native AskUserQuestion"));
+	});
+
+	test("buildPromptFromContext allows ToolSearch only for deferred workflow MCP hydration", () => {
+		const context: Context = {
+			messages: [{ role: "user", content: "Plan the slice" } as Message],
+		};
+
+		const prompt = buildPromptFromContext(context, { workflowMcpServerName: "gsd-workflow" });
+
+		assert.ok(prompt.includes("ToolSearch is available only for Claude Code deferred workflow MCP hydration"));
+		assert.ok(prompt.includes("use ToolSearch with select:mcp__gsd-workflow__<tool_name> or the base tool name"));
+		assert.ok(prompt.includes("then call the returned MCP tool directly"));
+		assert.ok(prompt.includes("Do not use ToolSearch for browser_* tools or general discovery"));
+		assert.ok(!prompt.includes("ToolSearch is NOT available"));
+	});
+
 	test("buildPromptFromContext does not advertise workflow MCP tools when unavailable", () => {
 		const context: Context = {
 			messages: [{ role: "user", content: "Check status" } as Message],
@@ -756,6 +915,91 @@ describe("stream-adapter — Claude Code external tool results", () => {
 		assert.deepEqual(finalContent[1], { type: "text", text: "All done." });
 	});
 
+	test("buildFinalAssistantContent suppresses duplicate empty MCP tool-unavailable failures after same-turn success", () => {
+		const finalContent = buildFinalAssistantContent({
+			intermediateToolBlocks: [
+				{
+					type: "toolCall",
+					id: "tool-empty-uat",
+					name: "gsd_uat_exec",
+					arguments: {},
+					mcpServer: "gsd-workflow",
+				} as any,
+				{
+					type: "toolCall",
+					id: "tool-real-uat",
+					name: "gsd_uat_exec",
+					arguments: {
+						milestoneId: "M004",
+						sliceId: "S01",
+						checkId: "S01-UAT-01-smoke",
+						intent: "uat-runtime-check",
+						script: "npx playwright test e2e/priority.spec.js --reporter=line",
+					},
+					mcpServer: "gsd-workflow",
+				} as any,
+			],
+			pendingContent: [{ type: "text", text: "UAT S01 complete." }],
+			toolResultsById: new Map([
+				[
+					"tool-empty-uat",
+					{
+						content: [{
+							type: "text",
+							text: "<tool_use_error>Error: No such tool available: mcp__gsd-workflow__gsd_uat_exec</tool_use_error>",
+						}],
+						isError: true,
+					},
+				],
+				[
+					"tool-real-uat",
+					{
+						content: [{ type: "text", text: "{\"operation\":\"gsd_uat_exec\",\"exit_code\":0}" }],
+						isError: false,
+					},
+				],
+			]),
+		});
+
+		assert.equal(finalContent.length, 2);
+		assert.equal((finalContent[0] as any).id, "tool-real-uat");
+		assert.deepEqual((finalContent[0] as any).externalResult, {
+			content: [{ type: "text", text: "{\"operation\":\"gsd_uat_exec\",\"exit_code\":0}" }],
+			isError: false,
+		});
+		assert.deepEqual(finalContent[1], { type: "text", text: "UAT S01 complete." });
+	});
+
+	test("buildFinalAssistantContent keeps lone MCP tool-unavailable failures", () => {
+		const finalContent = buildFinalAssistantContent({
+			intermediateToolBlocks: [
+				{
+					type: "toolCall",
+					id: "tool-empty-uat",
+					name: "gsd_uat_exec",
+					arguments: {},
+					mcpServer: "gsd-workflow",
+				} as any,
+			],
+			toolResultsById: new Map([
+				[
+					"tool-empty-uat",
+					{
+						content: [{
+							type: "text",
+							text: "<tool_use_error>Error: No such tool available: mcp__gsd-workflow__gsd_uat_exec</tool_use_error>",
+						}],
+						isError: true,
+					},
+				],
+			]),
+		});
+
+		assert.equal(finalContent.length, 1);
+		assert.equal((finalContent[0] as any).id, "tool-empty-uat");
+		assert.equal((finalContent[0] as any).externalResult.isError, true);
+	});
+
 	test("buildFinalAssistantContent keeps final-turn tool calls when result arrives without a synthetic user boundary", () => {
 		const finalContent = buildFinalAssistantContent({
 			intermediateToolBlocks: [],
@@ -790,6 +1034,33 @@ describe("stream-adapter — Claude Code external tool results", () => {
 	});
 });
 
+describe("claude-code-cli — Claude Fable 5 Opus-tier support", () => {
+	test("Fable 5 is exposed in the Claude Code model picker list", () => {
+		const fable = CLAUDE_CODE_MODELS.find((m) => m.id === "claude-fable-5");
+		assert.ok(fable, "claude-fable-5 must appear in CLAUDE_CODE_MODELS");
+		assert.equal(fable!.reasoning, true);
+		assert.equal(fable!.contextWindow, 1_000_000);
+		assert.equal(fable!.maxTokens, 128_000);
+	});
+
+	test("Fable 5 gets Opus-tier gates: xhigh effort, adaptive thinking, 1M-context beta", () => {
+		const options = buildSdkOptions("claude-fable-5", "test prompt", undefined, { reasoning: "xhigh" });
+		assert.equal(options.effort, "xhigh", "xhigh must pass through natively for Fable 5");
+		assert.deepEqual(options.thinking, { type: "adaptive" }, "Fable 5 must use adaptive thinking");
+		assert.ok(
+			Array.isArray(options.betas) && (options.betas as string[]).includes("context-1m-2025-08-07"),
+			"Fable 5 must enable the 1M-context beta",
+		);
+	});
+
+	test("non-Opus models do not receive Fable 5's Opus-tier gates", () => {
+		// Failure/contrast path: Haiku supports adaptive thinking but is not xhigh/1M-tier.
+		const options = buildSdkOptions("claude-haiku-4-5", "test prompt", undefined, { reasoning: "xhigh" });
+		assert.equal(options.effort, "high", "xhigh must clamp to high for non-Opus-tier models");
+		assert.deepEqual(options.betas, [], "Haiku must not enable the 1M-context beta");
+	});
+});
+
 describe("stream-adapter — session persistence (#2859)", () => {
 	test("buildSdkOptions enables persistSession by default", () => {
 		const options = buildSdkOptions("claude-sonnet-4-20250514", "test prompt");
@@ -1022,7 +1293,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, "/tmp/project");
-			assert.deepEqual(options.disallowedTools, ["ToolSearch", "AskUserQuestion"]);
+			assert.deepEqual(options.disallowedTools, ["AskUserQuestion"]);
 			assert.deepEqual(options.allowedTools, [
 				"Read",
 				"Write",
@@ -1043,6 +1314,31 @@ describe("stream-adapter — session persistence (#2859)", () => {
 		}
 	});
 
+	test("buildSdkOptions can disable workflow MCP ask_user_questions explicitly", () => {
+		const restore = setWorkflowMcpEnv({
+			GSD_WORKFLOW_MCP_COMMAND: "node",
+			GSD_WORKFLOW_MCP_NAME: "gsd-workflow",
+			GSD_WORKFLOW_MCP_ARGS: JSON.stringify(["packages/mcp-server/dist/cli.js"]),
+			GSD_WORKFLOW_MCP_CWD: "/tmp/project",
+			GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS: "0",
+		});
+		const originalCwd = process.cwd();
+		const emptyDir = mkdtempSync(join(tmpdir(), "claude-mcp-ask-disabled-"));
+		try {
+			process.chdir(emptyDir);
+			const options = buildSdkOptions("claude-sonnet-4-20250514", "test");
+			assert.ok(
+				(options.disallowedTools as string[]).includes("mcp__gsd-workflow__ask_user_questions"),
+				"explicit opt-out must block the MCP question tool even when workflow wildcard is allowed",
+			);
+			assert.ok((options.disallowedTools as string[]).includes("AskUserQuestion"));
+		} finally {
+			process.chdir(originalCwd);
+			rmSync(emptyDir, { recursive: true, force: true });
+			restore();
+		}
+	});
+
 	test("buildSdkOptions scopes run-uat to exact workflow MCP tools", () => {
 		const restore = setWorkflowMcpEnv({
 			GSD_WORKFLOW_MCP_COMMAND: "node",
@@ -1117,8 +1413,8 @@ describe("stream-adapter — session persistence (#2859)", () => {
 				"plan-milestone must expose exact milestone status helper before ToolSearch is needed",
 			);
 			assert.ok(
-				allowedTools.includes("mcp__gsd-workflow__*"),
-				"non-UAT workflow phases keep the wildcard for existing broad workflow behavior",
+				!allowedTools.includes("mcp__gsd-workflow__*"),
+				"strict GSD phases must not rely on a workflow wildcard that can mask missing exact tools",
 			);
 			assert.ok((options.disallowedTools as string[]).includes("AskUserQuestion"));
 			assert.equal(options.strictMcpConfig, true);
@@ -1130,6 +1426,121 @@ describe("stream-adapter — session persistence (#2859)", () => {
 		}
 	});
 
+	test("buildSdkOptions leaves ToolSearch available for complete-milestone workflow MCP hydration", () => {
+		const restore = setWorkflowMcpEnv({
+			GSD_WORKFLOW_MCP_COMMAND: "node",
+			GSD_WORKFLOW_MCP_NAME: "gsd-workflow",
+			GSD_WORKFLOW_MCP_ARGS: JSON.stringify(["packages/mcp-server/dist/cli.js"]),
+			GSD_WORKFLOW_MCP_ENV: JSON.stringify({ GSD_CLI_PATH: "/tmp/gsd" }),
+			GSD_WORKFLOW_MCP_CWD: "/tmp/project",
+		});
+		const originalCwd = process.cwd();
+		const emptyDir = mkdtempSync(join(tmpdir(), "claude-mcp-complete-milestone-"));
+		try {
+			process.chdir(emptyDir);
+			const options = buildSdkOptions("claude-sonnet-4-20250514", "test", undefined, { gsdPhase: "complete-milestone" });
+			const disallowedTools = options.disallowedTools as string[];
+
+			assert.ok(!disallowedTools.includes("ToolSearch"));
+			assert.ok(disallowedTools.includes("Skill"));
+			assert.ok(disallowedTools.includes("AskUserQuestion"));
+			assert.equal(options.strictMcpConfig, true);
+		} finally {
+			process.chdir(originalCwd);
+			rmSync(emptyDir, { recursive: true, force: true });
+			restore();
+		}
+	});
+
+	test("buildSdkOptions scopes complete-slice away from native write and shell tools", () => {
+		const restore = setWorkflowMcpEnv({
+			GSD_WORKFLOW_MCP_COMMAND: "node",
+			GSD_WORKFLOW_MCP_NAME: "gsd-workflow",
+			GSD_WORKFLOW_MCP_ARGS: JSON.stringify(["packages/mcp-server/dist/cli.js"]),
+			GSD_WORKFLOW_MCP_ENV: JSON.stringify({ GSD_CLI_PATH: "/tmp/gsd" }),
+			GSD_WORKFLOW_MCP_CWD: "/tmp/project",
+		});
+		const originalCwd = process.cwd();
+		const emptyDir = mkdtempSync(join(tmpdir(), "claude-mcp-complete-slice-"));
+		try {
+			process.chdir(emptyDir);
+			const options = buildSdkOptions("claude-sonnet-4-20250514", "test", undefined, { gsdPhase: "complete-slice" });
+			const allowedTools = options.allowedTools as string[];
+
+			assert.ok(allowedTools.includes("Read"));
+			assert.ok(allowedTools.includes("Glob"));
+			assert.ok(allowedTools.includes("Grep"));
+			assert.ok(allowedTools.includes("mcp__gsd-workflow__gsd_exec"));
+			assert.ok(allowedTools.includes("mcp__gsd-workflow__gsd_slice_complete"));
+			assert.ok(!allowedTools.includes("Bash"));
+			assert.ok(!allowedTools.includes("Write"));
+			assert.ok(!allowedTools.includes("Edit"));
+			assert.ok(!allowedTools.includes("mcp__gsd-workflow__*"));
+		} finally {
+			process.chdir(originalCwd);
+			rmSync(emptyDir, { recursive: true, force: true });
+			restore();
+		}
+	});
+
+	test("buildSdkOptions blocks native Skill tool during GSD phases", () => {
+		const restore = setWorkflowMcpEnv({
+			GSD_WORKFLOW_MCP_COMMAND: "node",
+			GSD_WORKFLOW_MCP_NAME: "gsd-workflow",
+			GSD_WORKFLOW_MCP_ARGS: JSON.stringify(["packages/mcp-server/dist/cli.js"]),
+			GSD_WORKFLOW_MCP_ENV: JSON.stringify({ GSD_CLI_PATH: "/tmp/gsd" }),
+			GSD_WORKFLOW_MCP_CWD: "/tmp/project",
+		});
+		const originalCwd = process.cwd();
+		const emptyDir = mkdtempSync(join(tmpdir(), "claude-mcp-no-native-skill-"));
+		try {
+			process.chdir(emptyDir);
+			const options = buildSdkOptions("claude-sonnet-4-20250514", "test", undefined, { gsdPhase: "complete-slice" });
+			const allowedTools = options.allowedTools as string[];
+			const disallowedTools = options.disallowedTools as string[];
+
+			assert.ok(!allowedTools.includes("Skill"));
+			assert.ok(disallowedTools.includes("Skill"));
+		} finally {
+			process.chdir(originalCwd);
+			rmSync(emptyDir, { recursive: true, force: true });
+			restore();
+		}
+	});
+
+	test("buildSdkOptions presents every unit's required workflow MCP tools", () => {
+		const restore = setWorkflowMcpEnv({
+			GSD_WORKFLOW_MCP_COMMAND: "node",
+			GSD_WORKFLOW_MCP_NAME: "gsd-workflow",
+			GSD_WORKFLOW_MCP_ARGS: JSON.stringify(["packages/mcp-server/dist/cli.js"]),
+			GSD_WORKFLOW_MCP_CWD: "/tmp/project",
+		});
+		const originalCwd = process.cwd();
+		const emptyDir = mkdtempSync(join(tmpdir(), "claude-mcp-all-units-"));
+		try {
+			process.chdir(emptyDir);
+			for (const [unitType, contract] of Object.entries(UNIT_TOOL_CONTRACTS)) {
+				const requiredTools = contract.requiredWorkflowTools.filter(
+					(tool) => tool.startsWith("gsd_") || tool === "ask_user_questions",
+				);
+				if (requiredTools.length === 0) continue;
+
+				const options = buildSdkOptions("claude-sonnet-4-20250514", "test", undefined, { gsdPhase: unitType });
+				const allowedTools = options.allowedTools as string[];
+				for (const toolName of requiredTools) {
+					assert.ok(
+						allowedTools.includes(`mcp__gsd-workflow__${toolName}`) || allowedTools.includes("mcp__gsd-workflow__*"),
+						`${unitType} must allow ${toolName}; allowed=${JSON.stringify(allowedTools)}`,
+					);
+				}
+			}
+		} finally {
+			process.chdir(originalCwd);
+			rmSync(emptyDir, { recursive: true, force: true });
+			restore();
+		}
+	});
+
 	test("inferGsdPhaseFromContext recognizes non-UAT unit prompts", () => {
 		const context = {
 			messages: [
@@ -1140,6 +1551,165 @@ describe("stream-adapter — session persistence (#2859)", () => {
 		assert.equal(inferGsdPhaseFromContext(context), "plan-milestone");
 	});
 
+	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(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();
+		setGuidedUnitContext(projectRoot, "discuss-slice");
+		try {
+			const context = {
+				messages: [{ role: "user", content: "Generic workflow task with no phase slug." }],
+			} as Context;
+			assert.equal(resolveGsdPhaseForSdk(context, projectRoot), "discuss-slice");
+		} finally {
+			clearGuidedUnitContext(projectRoot);
+		}
+	});
+
+	test("resolveGsdPhaseForSdk matches guided context across milestone worktrees", () => {
+		const projectRoot = "/tmp/gsd-guided-phase-root";
+		const worktreeRoot = `${projectRoot}/.gsd/worktrees/m001-wt`;
+		clearGuidedUnitContext();
+		setGuidedUnitContext(worktreeRoot, "refine-slice");
+		try {
+			const context = { messages: [{ role: "user", content: "No UNIT header here." }] } as Context;
+			assert.equal(resolveGsdPhaseForSdk(context, projectRoot), "refine-slice");
+		} finally {
+			clearGuidedUnitContext(worktreeRoot);
+		}
+	});
+
+	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();
+		_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", () => {
+		const restore = setWorkflowMcpEnv({
+			GSD_WORKFLOW_MCP_COMMAND: "node",
+			GSD_WORKFLOW_MCP_NAME: "gsd-workflow",
+			GSD_WORKFLOW_MCP_ARGS: JSON.stringify(["packages/mcp-server/dist/cli.js"]),
+			GSD_WORKFLOW_MCP_ENV: JSON.stringify({ GSD_CLI_PATH: "/tmp/gsd" }),
+			GSD_WORKFLOW_MCP_CWD: "/tmp/project",
+		});
+		const originalCwd = process.cwd();
+		const emptyDir = mkdtempSync(join(tmpdir(), "claude-mcp-discuss-"));
+		try {
+			process.chdir(emptyDir);
+			const options = buildSdkOptions("claude-sonnet-4-20250514", "test", undefined, { gsdPhase: "discuss-milestone" });
+			const allowedTools = options.allowedTools as string[];
+			const disallowedTools = options.disallowedTools as string[];
+
+			assert.ok(
+				allowedTools.includes("mcp__gsd-workflow__ask_user_questions"),
+				"discuss phases must expose the exact workflow MCP question tool",
+			);
+			assert.ok(disallowedTools.includes("AskUserQuestion"));
+			assert.ok(
+				!disallowedTools.includes("mcp__gsd-workflow__ask_user_questions"),
+				"workflow MCP ask_user_questions should remain enabled by default",
+			);
+		} finally {
+			process.chdir(originalCwd);
+			rmSync(emptyDir, { recursive: true, force: true });
+			restore();
+		}
+	});
+
 	test("buildSdkOptions prefers custom workflow MCP question tools over native AskUserQuestion", () => {
 		const restore = setWorkflowMcpEnv({
 			GSD_WORKFLOW_MCP_COMMAND: "node",
@@ -1157,7 +1727,7 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			const mcpServers = options.mcpServers as Record<string, any>;
 			assert.ok(mcpServers?.["custom-workflow"], "expected custom workflow server config");
 			assert.ok(mcpServers?.["gsd-browser"], "expected gsd-browser server config");
-			assert.deepEqual(options.disallowedTools, ["ToolSearch", "AskUserQuestion"]);
+			assert.deepEqual(options.disallowedTools, ["AskUserQuestion"]);
 			assert.deepEqual(options.allowedTools, [
 				"Read",
 				"Write",
@@ -1203,7 +1773,7 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			if (mcpServers) {
 				assert.ok(mcpServers["gsd-workflow"], "if present, must include gsd-workflow");
 				assert.ok(mcpServers["gsd-browser"], "if present, must include gsd-browser");
-				assert.deepEqual((options as any).disallowedTools, ["ToolSearch", "AskUserQuestion"]);
+				assert.deepEqual((options as any).disallowedTools, ["AskUserQuestion"]);
 			} else {
 				assert.deepEqual((options as any).disallowedTools, ["ToolSearch"]);
 			}
@@ -1245,7 +1815,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, ["ToolSearch", "AskUserQuestion"]);
+			assert.deepEqual(options.disallowedTools, ["AskUserQuestion"]);
 		} finally {
 			process.chdir(originalCwd);
 			rmSync(repoDir, { recursive: true, force: true });
@@ -1315,7 +1885,7 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			const allowedTools = options.allowedTools as string[];
 			assert.ok(allowedTools.includes("mcp__gsd-workflow__gsd_plan_milestone"));
 			assert.ok(allowedTools.includes("mcp__gsd-workflow__gsd_milestone_status"));
-			assert.ok(allowedTools.includes("mcp__gsd-workflow__*"));
+			assert.ok(!allowedTools.includes("mcp__gsd-workflow__*"));
 		} finally {
 			process.chdir(originalCwd);
 			rmSync(projectDir, { recursive: true, force: true });
@@ -1430,6 +2000,441 @@ 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",
+			content: [],
+			api: "anthropic-messages",
+			provider: "claude-code",
+			model: "claude-sonnet-4-6",
+			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+			stopReason: "stop",
+			timestamp: Date.now(),
+		};
+		const events: any[] = [];
+		const state = {};
+		const message = buildWorkflowMcpReadinessProgressMessage({
+			unitType: "complete-milestone",
+			workflowServerName: "gsd-workflow",
+			stage: "preflight",
+		});
+
+		pushWorkflowMcpReadinessProgressEvent({
+			stream: { push: (event: any) => events.push(event) } as any,
+			partial,
+			state,
+			message,
+		});
+		const retryMessage = buildWorkflowMcpReadinessProgressMessage({
+			unitType: "complete-milestone",
+			workflowServerName: "gsd-workflow",
+			stage: "retry",
+			attempt: 1,
+			delayMs: 1_000,
+		});
+		pushWorkflowMcpReadinessProgressEvent({
+			stream: { push: (event: any) => events.push(event) } as any,
+			partial,
+			state,
+			message: retryMessage,
+		});
+
+		assert.deepEqual(events.map((event) => event.type), ["text_start", "text_delta", "text_delta"]);
+		assert.match(events[1].delta, /Starting gsd-workflow MCP/);
+		assert.match(events[1].delta, /complete-milestone/);
+		assert.match(events[2].delta, /Still waiting for gsd-workflow MCP tools/);
+		assert.match(events[2].delta, /Retrying in 1s/);
+		assert.deepEqual(partial.content, [{ type: "text", text: `${message}\n${retryMessage}` }]);
+	});
+
+	test("execute-task requires gsd_exec before the model follows verification guidance", async () => {
+		const error = await resolveClaudeCodeToolSurfaceReadinessError({
+			unitType: "execute-task",
+			workflowServerName: "gsd-workflow",
+			observation: {
+				tools: [
+					"Read",
+					"Bash",
+					"mcp__gsd-workflow__gsd_task_complete",
+					"mcp__gsd-workflow__gsd_exec_search",
+					"mcp__gsd-workflow__gsd_resume",
+					"mcp__gsd-workflow__gsd_capture_thought",
+				],
+				mcpServers: [{ name: "gsd-workflow", status: "connected" }],
+			},
+		});
+
+		assert.match(error ?? "", /gsd_exec/);
+	});
+
+	test("complete-slice requires gsd_exec before the model follows closeout verification guidance", async () => {
+		const error = await resolveClaudeCodeToolSurfaceReadinessError({
+			unitType: "complete-slice",
+			workflowServerName: "gsd-workflow",
+			observation: {
+				tools: [
+					"Read",
+					"mcp__gsd-workflow__gsd_slice_complete",
+					"mcp__gsd-workflow__gsd_task_reopen",
+					"mcp__gsd-workflow__gsd_replan_slice",
+					"mcp__gsd-workflow__gsd_requirement_update",
+					"mcp__gsd-workflow__gsd_summary_save",
+					"mcp__gsd-workflow__gsd_capture_thought",
+					"mcp__gsd-workflow__gsd_exec_search",
+				],
+				mcpServers: [{ name: "gsd-workflow", status: "connected" }],
+			},
+		});
+
+		assert.match(error ?? "", /gsd_exec/);
+	});
+
+	test("complete-slice requires workflow MCP memory capture before closeout guidance can use it", async () => {
+		const error = await resolveClaudeCodeToolSurfaceReadinessError({
+			unitType: "complete-slice",
+			workflowServerName: "gsd-workflow",
+			observation: {
+				tools: [
+					"Read",
+					"capture_thought",
+					"mcp__gsd-workflow__gsd_exec",
+					"mcp__gsd-workflow__gsd_slice_complete",
+					"mcp__gsd-workflow__gsd_task_reopen",
+					"mcp__gsd-workflow__gsd_replan_slice",
+					"mcp__gsd-workflow__gsd_requirement_update",
+					"mcp__gsd-workflow__gsd_summary_save",
+				],
+				mcpServers: [{ name: "gsd-workflow", status: "connected" }],
+			},
+		});
+
+		assert.match(error ?? "", /gsd_capture_thought/);
+	});
+
+	test("terminal init surface remains not ready even when configured workflow MCP probes available", async () => {
+		const previousGsdHome = process.env.GSD_HOME;
+		const projectRoot = realpathSync(mkdtempSync(join(tmpdir(), "claude-sdk-mcp-pending-ready-")));
+		const gsdHomeDir = realpathSync(mkdtempSync(join(tmpdir(), "claude-sdk-mcp-pending-home-")));
+		try {
+			process.env.GSD_HOME = gsdHomeDir;
+
+			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",
+			);
+			writeFileSync(
+				join(projectRoot, ".mcp.json"),
+				JSON.stringify({ mcpServers: { "gsd-workflow": { command: process.execPath, args: [serverPath] } } }),
+				"utf-8",
+			);
+
+			const error = await resolveClaudeCodeToolSurfaceReadinessError({
+				unitType: "plan-slice",
+				workflowServerName: "gsd-workflow",
+				observation: {
+					tools: ["Read", "Bash"],
+					mcpServers: [{ name: "gsd-workflow", status: "failed" }],
+				},
+			});
+
+			assert.match(error ?? "", /status is "failed"/);
+			assert.match(error ?? "", /gsd_plan_slice/);
+		} finally {
+			if (previousGsdHome === undefined) {
+				delete process.env.GSD_HOME;
+			} else {
+				process.env.GSD_HOME = previousGsdHome;
+			}
+			rmSync(projectRoot, { recursive: true, force: true });
+			rmSync(gsdHomeDir, { recursive: true, force: true });
+			clearMcpConfigCache();
+		}
+	});
+
+	test("pending init surface is not accepted until the live Claude session exposes plan-slice tools", async () => {
+		const projectRoot = realpathSync(mkdtempSync(join(tmpdir(), "claude-sdk-mcp-plan-pending-")));
+		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",
+			);
+			writeFileSync(
+				join(projectRoot, ".mcp.json"),
+				JSON.stringify({ mcpServers: { "gsd-workflow": { command: process.execPath, args: [serverPath] } } }),
+				"utf-8",
+			);
+
+			const error = await resolveClaudeCodeToolSurfaceReadinessError({
+				unitType: "plan-slice",
+				workflowServerName: "gsd-workflow",
+				projectRoot,
+				observation: {
+					tools: ["Read", "Bash"],
+					mcpServers: [{ name: "gsd-workflow", status: "pending" }],
+				},
+			});
+
+			assert.match(error ?? "", /status is "pending"/);
+			assert.match(error ?? "", /gsd_plan_slice/);
+		} finally {
+			rmSync(projectRoot, { recursive: true, force: true });
+			clearMcpConfigCache();
+		}
+	});
+
+	test("pending init surface can be deferred to Claude Code ToolSearch hydration", async () => {
+		const error = await resolveClaudeCodeToolSurfaceReadinessError({
+			unitType: "plan-slice",
+			workflowServerName: "gsd-workflow",
+			allowPendingToolSearchHydration: true,
+			observation: {
+				tools: ["Read", "Bash"],
+				mcpServers: [{ name: "gsd-workflow", status: "pending" }],
+			},
+		});
+
+		assert.equal(error, null);
+	});
+
+	test("complete-milestone pending init surface defers to Claude Code ToolSearch hydration", async () => {
+		const error = await resolveClaudeCodeToolSurfaceReadinessError({
+			unitType: "complete-milestone",
+			workflowServerName: "gsd-workflow",
+			allowPendingToolSearchHydration: true,
+			observation: {
+				tools: ["Read", "Bash"],
+				mcpServers: [{ name: "gsd-workflow", status: "pending" }],
+			},
+		});
+
+		assert.equal(error, null);
+	});
+
+	test("retries transient readiness errors internally but not terminal MCP failures", () => {
+		const pendingError =
+			'workflow tool surface not ready for run-uat: MCP server "gsd-workflow" status is "pending" (not yet connected): gsd_uat_exec';
+		const partialError =
+			'workflow tool surface not ready for run-uat: MCP server "gsd-workflow" is connected but has not registered: gsd_uat_exec';
+		const terminalError =
+			'workflow tool surface not ready for run-uat: MCP server "gsd-workflow" status is "failed" (terminal) — cannot register: gsd_uat_exec';
+
+		assert.equal(shouldRetryClaudeCodeToolSurfaceReadiness(pendingError), true);
+		assert.equal(shouldRetryClaudeCodeToolSurfaceReadiness(partialError), true);
+		assert.equal(shouldRetryClaudeCodeToolSurfaceReadiness(terminalError), false);
+		assert.equal(
+			resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(pendingError, 0),
+			500,
+		);
+		assert.equal(
+			resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(pendingError, 1),
+			1_000,
+		);
+		assert.equal(
+			resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(partialError, 2),
+			2_000,
+		);
+		assert.equal(resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(pendingError, 3), 4_000);
+		assert.equal(resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(pendingError, 4), 8_000);
+		assert.equal(resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(pendingError, 5), 15_000);
+		assert.equal(resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(pendingError, 6), 15_000);
+		assert.equal(resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(pendingError, 7), 15_000);
+		assert.equal(resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(pendingError, 8), null);
+		assert.equal(resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(pendingError, 0, true), 1_000);
+		assert.equal(resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(pendingError, 9, true), 15_000);
+		assert.equal(resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(pendingError, 10, true), null);
+		assert.equal(resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(terminalError, 0), null);
+	});
+});
+
 describe("stream-adapter — MCP elicitation bridge", () => {
 	const askUserQuestionsRequest = {
 		serverName: "gsd-workflow",
@@ -1662,6 +2667,26 @@ describe("stream-adapter — MCP elicitation bridge", () => {
 		});
 	});
 
+	test("createClaudeCodeElicitationHandler returns cancel when custom UI is dismissed", async () => {
+		let selectCalls = 0;
+		const handler = createClaudeCodeElicitationHandler({
+			custom: async () => ({
+				endInterview: false,
+				answers: {},
+			}),
+			select: async () => {
+				selectCalls++;
+				return "Cloud-synced";
+			},
+		} as any);
+		assert.ok(handler);
+
+		const result = await handler!(askUserQuestionsRequest, { signal: new AbortController().signal });
+
+		assert.deepEqual(result, { action: "cancel" });
+		assert.equal(selectCalls, 0, "dismissed custom question must not re-open dialog fallback");
+	});
+
 	test("parseTextInputElicitation recognizes secure free-text MCP forms", () => {
 		const request = {
 			serverName: "gsd-workflow",
@@ -1773,6 +2798,166 @@ describe("stream-adapter — MCP elicitation bridge", () => {
 		assert.equal(inputCalls.length, 1);
 		assert.equal(inputCalls[0]?.opts?.secure, true, "secure_env_collect fields should request secure input");
 	});
+
+	// -- self-cancel loop fix (#2676 / claude-code-cli) ----------------------
+	//
+	// Under claude-code-cli, ask_user_questions arrives as an SDK elicitation,
+	// not an MCP tool dispatch, so the auto-mode watchdogs never saw an in-flight
+	// tool during the human wait and re-dispatched/aborted the turn hosting the
+	// question (the "self-cancel loop"). The fix brackets the human wait with the
+	// interactive-tool guard and disambiguates a system-teardown abort (decline)
+	// from a deliberate user dismissal (cancel).
+
+	test("makes the SDK elicitation visible to the interactive-tool guard during the human wait", async () => {
+		_setAutoActiveForTest(true);
+		clearInFlightTools();
+		try {
+			let countDuringWait = -1;
+			let interactiveDuringWait = false;
+			const handler = createClaudeCodeElicitationHandler({
+				custom: async () => {
+					// Observe the in-flight guard state WHILE the question is open —
+					// this is the window where the watchdogs previously saw 0 tools.
+					countDuringWait = getInFlightToolCount();
+					interactiveDuringWait = hasInteractiveToolInFlight();
+					return {
+						endInterview: false,
+						answers: { storage_scope: { selected: "Cloud-synced", notes: "" }, platform: { selected: ["Web"], notes: "" } },
+					};
+				},
+			} as any);
+			assert.ok(handler);
+
+			const result = await handler!(askUserQuestionsRequest, { signal: new AbortController().signal });
+
+			assert.equal(countDuringWait, 1, "elicitation must register as an in-flight tool during the human wait");
+			assert.equal(interactiveDuringWait, true, "elicitation must be recognized as an interactive tool during the wait");
+			assert.equal(result.action, "accept");
+			assert.equal(getInFlightToolCount(), 0, "in-flight tool must be cleared after the elicitation resolves");
+		} finally {
+			_setAutoActiveForTest(false);
+			clearInFlightTools();
+		}
+	});
+
+	test("clears the in-flight tool even when the interview UI throws (finally)", async () => {
+		_setAutoActiveForTest(true);
+		clearInFlightTools();
+		try {
+			const handler = createClaudeCodeElicitationHandler({
+				// custom throws -> showInterviewRound rejects -> handler falls back
+				// to dialogs; the in-flight entry must still be cleared via finally.
+				custom: async () => {
+					throw new Error("simulated UI failure");
+				},
+				select: async (_title: string, options: string[], opts?: { allowMultiple?: boolean }) => {
+					if (opts?.allowMultiple) return ["Web"];
+					return options[0];
+				},
+				input: async () => "note",
+			} as any);
+			assert.ok(handler);
+
+			await handler!(askUserQuestionsRequest, { signal: new AbortController().signal });
+			assert.equal(getInFlightToolCount(), 0, "in-flight tool must be cleared even when the UI throws");
+		} finally {
+			_setAutoActiveForTest(false);
+			clearInFlightTools();
+		}
+	});
+
+	test("returns decline (not cancel) when an interrupt empties the answers", async () => {
+		// A system/host teardown that aborts the signal mid-wait surfaces as
+		// interrupted:true -> the handler must return decline so the model does
+		// not re-ask against a clean user-declined cancel (the re-ask amplifier).
+		const handler = createClaudeCodeElicitationHandler({
+			custom: async () => ({ endInterview: false, answers: {}, interrupted: true }),
+			select: async () => {
+				throw new Error("interrupted elicitation must not re-open dialogs");
+			},
+		} as any);
+		assert.ok(handler);
+
+		const result = await handler!(askUserQuestionsRequest, { signal: new AbortController().signal });
+		assert.deepEqual(result, { action: "decline" });
+	});
+
+	test("returns cancel (today's semantics) when the user genuinely dismisses", async () => {
+		const handler = createClaudeCodeElicitationHandler({
+			custom: async () => ({ endInterview: false, answers: {} }),
+		} as any);
+		assert.ok(handler);
+
+		const result = await handler!(askUserQuestionsRequest, { signal: new AbortController().signal });
+		assert.deepEqual(result, { action: "cancel" });
+	});
+
+	test("does not register an in-flight tool outside auto-mode (wrapper self-gates)", async () => {
+		_setAutoActiveForTest(false);
+		clearInFlightTools();
+		let countDuringWait = -1;
+		const handler = createClaudeCodeElicitationHandler({
+			custom: async () => {
+				countDuringWait = getInFlightToolCount();
+				return { endInterview: false, answers: { storage_scope: { selected: "Cloud-synced", notes: "" }, platform: { selected: ["Web"], notes: "" } } };
+			},
+		} as any);
+		assert.ok(handler);
+
+		await handler!(askUserQuestionsRequest, { signal: new AbortController().signal });
+		assert.equal(countDuringWait, 0, "foreground/non-auto elicitation must not touch the in-flight guard");
+	});
+
+	// The FOREGROUND self-cancel regression guard: the s.active-gated in-flight
+	// guard above is a no-op in foreground, so the foreground approval-gate pause
+	// path needs a SEPARATE, ungated signal to see the elicitation as the active
+	// human boundary. isInteractiveElicitationInFlight() must be true DURING the
+	// wait and false after, even with auto inactive (#cc-elicitation-self-cancel).
+	test("sets the ungated interactive-elicitation marker in FOREGROUND (auto inactive)", async () => {
+		_setAutoActiveForTest(false);
+		clearInFlightTools();
+		try {
+			let markerDuringWait = false;
+			let countDuringWait = -1;
+			const handler = createClaudeCodeElicitationHandler({
+				custom: async () => {
+					markerDuringWait = isInteractiveElicitationInFlight();
+					countDuringWait = getInFlightToolCount();
+					return {
+						endInterview: false,
+						answers: { storage_scope: { selected: "Cloud-synced", notes: "" }, platform: { selected: ["Web"], notes: "" } },
+					};
+				},
+			} as any);
+			assert.ok(handler);
+
+			const result = await handler!(askUserQuestionsRequest, { signal: new AbortController().signal });
+
+			assert.equal(markerDuringWait, true, "ungated marker must be true during the foreground human wait");
+			assert.equal(countDuringWait, 0, "the separate marker must NOT touch the in-flight tool count in foreground");
+			assert.equal(result.action, "accept");
+			assert.equal(isInteractiveElicitationInFlight(), false, "marker must clear after the elicitation resolves");
+		} finally {
+			clearInFlightTools();
+		}
+	});
+
+	test("clears the ungated marker even when the interview UI throws in FOREGROUND (finally)", async () => {
+		_setAutoActiveForTest(false);
+		clearInFlightTools();
+		try {
+			const handler = createClaudeCodeElicitationHandler({
+				custom: async () => {
+					throw new Error("ui exploded");
+				},
+			} as any);
+			assert.ok(handler);
+			await handler!(askUserQuestionsRequest, { signal: new AbortController().signal }).catch(() => undefined);
+			assert.equal(isInteractiveElicitationInFlight(), false, "marker must clear via finally on throw");
+		} finally {
+			clearInFlightTools();
+		}
+	});
 });
 
 // ---------------------------------------------------------------------------