@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

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

@@ -27,24 +27,42 @@ import { homedir } from "node:os";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { PartialMessageBuilder, ZERO_USAGE, mapUsage } from "./partial-builder.js";
+import {
+	attachExternalResultsToToolBlocks,
+	buildFinalAssistantContent,
+	extractToolResultsFromSdkUserMessage,
+	handleClaudeCodePartialStreamEvent,
+} from "./turn-assembler.js";
+import type {
+	ExternalToolResultPayload,
+	ToolCallWithExternalResult,
+} from "./turn-assembler.js";
 import {
 	buildWorkflowMcpServers,
 	getRequiredWorkflowToolsForAutoUnit,
 	resolveWorkflowMcpProjectRoot,
 } from "../gsd/workflow-mcp.js";
+import { resolveWorkflowQuestionToolSurface } from "../gsd/question-transport.js";
 import { buildProjectGsdMcpServers, ensureProjectWorkflowMcpConfig } from "../gsd/mcp-project-config.js";
 import { loadProjectGSDPreferences } from "../gsd/preferences.js";
+import { markToolStart, markToolEnd } from "../gsd/auto.js";
+import {
+	markInteractiveElicitationStart,
+	markInteractiveElicitationEnd,
+} from "../gsd/auto-tool-tracking.js";
 import {
 	discoverBrowserMcpServerName,
 	discoverMcpServers,
 	discoverMcpServerNames,
+	discoverUserMcpServerNames,
 	discoverWorkflowMcpServerName,
 	computeMcpDisallowedTools,
 } from "../gsd/mcp-filter.js";
 import { RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES, RUN_UAT_FORBIDDEN_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES, resolveToolPresentationPlan } from "../gsd/tool-presentation-plan.js";
+import { getToolSurfaceReadinessError } from "../gsd/tool-surface-readiness.js";
+import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
 import { showInterviewRound, type Question, type RoundResult } from "../shared/tui.js";
 import type {
-	BetaRawMessageStreamEvent,
 	SDKAssistantMessage,
 	SDKMessage,
 	SDKPartialAssistantMessage,
@@ -52,25 +70,17 @@ import type {
 	SDKUserMessage,
 } from "./sdk-types.js";
 
-/** A single content block returned by an external (SDK-executed) tool call. */
-export interface ExternalToolResultContentBlock {
-	type: string;
-	text?: string;
-	data?: string;
-	mimeType?: string;
-}
-
-/** The full result payload returned by an external tool, including content blocks and error status. */
-export interface ExternalToolResultPayload {
-	content: ExternalToolResultContentBlock[];
-	details?: Record<string, unknown>;
-	isError: boolean;
-}
-
-/** A `ToolCall` block augmented with the external result attached by the SDK synthetic user message. */
-type ToolCallWithExternalResult = ToolCall & {
-	externalResult?: ExternalToolResultPayload;
-};
+export {
+	buildFinalAssistantContent,
+	extractToolResultsFromSdkUserMessage,
+	handleClaudeCodePartialStreamEvent,
+	mergePendingToolCalls,
+} from "./turn-assembler.js";
+export type {
+	ExternalToolResultContentBlock,
+	ExternalToolResultPayload,
+	ToolCallWithExternalResult,
+} from "./turn-assembler.js";
 
 interface PromptToolContextOptions {
 	workflowMcpServerName?: string | null;
@@ -1358,7 +1368,27 @@ export function createClaudeCodeCanUseToolHandler(
 // Elicitation handler
 // ---------------------------------------------------------------------------
 
-/** Create an SDK elicitation handler that routes requests through the extension UI dialogs, or undefined if no UI is available. */
+/**
+ * Create an SDK elicitation handler that routes requests through the extension UI dialogs, or undefined if no UI is available.
+ *
+ * For structured (AskUserQuestion) elicitations, the interview round's result
+ * disambiguates two cases that must not be conflated: an `undefined` result
+ * means the custom UI is unavailable, so we fall back to the simpler `select`
+ * dialogs; an empty-answers result means the user dismissed the question, which
+ * is treated as a clean cancel. Falling back to dialogs on dismissal would
+ * re-ask the same questions (the duplicate-question bug).
+ */
+/**
+ * Monotonic counter so concurrent/sequential elicitations resolved within the
+ * same millisecond get distinct synthetic in-flight-tool ids (the `cc-elicit-*`
+ * namespace never collides with real MCP toolCallIds).
+ */
+let _elicitationSeq = 0;
+function nextElicitationSeq(): number {
+	_elicitationSeq = (_elicitationSeq + 1) % Number.MAX_SAFE_INTEGER;
+	return _elicitationSeq;
+}
+
 export function createClaudeCodeElicitationHandler(
 	ui: ExtensionUIContext | undefined,
 ): ((request: SdkElicitationRequest, options: { signal: AbortSignal }) => Promise<SdkElicitationResult>) | undefined {
@@ -1374,20 +1404,67 @@ export function createClaudeCodeElicitationHandler(
 			const headlessAnswer = answerElicitationFromHeadlessAnswers(questions, loadHeadlessAnswers());
 			if (headlessAnswer) return headlessAnswer;
 
-			const interviewResult = await showInterviewRound(questions, { signal }, { ui } as any).catch(() => undefined);
-			if (interviewResult && Object.keys(interviewResult.answers).length > 0) {
+			// The SDK elicitation blocks waiting for human input, but it is not an
+			// MCP tool dispatch, so markToolStart/markToolEnd are never called for
+			// it. Without this the soft/context/idle/hard watchdogs see zero
+			// in-flight tools and re-dispatch (and ultimately abort) the agent
+			// turn hosting this elicitation, tearing the question down (#2676 /
+			// claude-code-cli self-cancel loop). Bracketing the human wait with
+			// the s.active-gated interactive-tool guard makes it visible to
+			// hasInteractiveToolInFlight()/getInFlightToolCount() so those
+			// watchdogs exempt it. No-op outside auto-mode (wrapper self-gates).
+			//
+			// markInteractiveElicitationStart/End is a SEPARATE, ungated signal that
+			// is observable in FOREGROUND (where the s.active-gated markToolStart is a
+			// no-op). The foreground approval-gate pause path (register-hooks
+			// message_update) consults isInteractiveElicitationInFlight() and bails so
+			// it does not tear down the very elicitation that IS the human boundary
+			// (#cc-elicitation-self-cancel). It clears in the finally on every exit.
+			const elicId = "cc-elicit-" + ((request as { id?: string | number }).id ?? `${Date.now()}-${nextElicitationSeq()}`);
+			markInteractiveElicitationStart();
+			markToolStart(elicId, "ask_user_questions");
+			try {
+				const interviewResult = await showInterviewRound(
+					questions,
+					{ signal, overlay: true },
+					{ ui } as any,
+				).catch(() => undefined);
+				if (interviewResult === undefined) {
+					// `await` so the dialog human-wait stays inside try/finally and the
+					// in-flight guard is held until the dialog resolves. Without it,
+					// `finally` runs the moment the promise is created and the fallback
+					// wait runs with zero in-flight tools — reintroducing the
+					// self-cancel on this path (Bugbot #1c00624d).
+					return await promptElicitationWithDialogs(request, questions, ui, signal);
+				}
+				if (Object.keys(interviewResult.answers).length === 0) {
+					// A system/host teardown (compaction, session_switch, true
+					// interrupt) that aborted the signal mid-wait sets `interrupted`.
+					// Surface that as a non-affirmative `decline` so it is not
+					// laundered into a clean user-declined `cancel` the model re-asks
+					// against. A genuine user dismissal leaves `interrupted` falsy and
+					// keeps the prior `cancel` semantics.
+					return interviewResult.interrupted ? { action: "decline" } : { action: "cancel" };
+				}
 				return {
 					action: "accept",
 					content: roundResultToElicitationContent(questions, interviewResult),
 				};
+			} finally {
+				markToolEnd(elicId);
+				markInteractiveElicitationEnd();
 			}
-
-			return promptElicitationWithDialogs(request, questions, ui, signal);
 		}
 
 		const textFields = parseTextInputElicitation(request);
 		if (textFields) {
-			return promptTextInputElicitation(request, textFields, ui, signal);
+			const elicId = "cc-elicit-" + ((request as { id?: string | number }).id ?? `${Date.now()}-${nextElicitationSeq()}`);
+			markToolStart(elicId, "secure_env_collect");
+			try {
+				return await promptTextInputElicitation(request, textFields, ui, signal);
+			} finally {
+				markToolEnd(elicId);
+			}
 		}
 
 		return { action: "decline" };
@@ -1467,6 +1544,8 @@ function modelSupportsAdaptiveThinking(modelId: string): boolean {
 		|| modelId.includes("opus-4.7")
 		|| modelId.includes("opus-4-8")
 		|| modelId.includes("opus-4.8")
+		|| modelId.includes("fable-5")
+		|| modelId.includes("fable.5")
 		|| modelId.includes("sonnet-4-6")
 		|| modelId.includes("sonnet-4.6")
 		|| modelId.includes("sonnet-4-7")
@@ -1492,6 +1571,8 @@ function mapThinkingLevelToAnthropicEffort(level: ThinkingLevel | undefined, mod
 				|| modelId.includes("opus-4.7")
 				|| modelId.includes("opus-4-8")
 				|| modelId.includes("opus-4.8")
+				|| modelId.includes("fable-5")
+				|| modelId.includes("fable.5")
 			) return "xhigh";
 			if (modelId.includes("opus-4-6") || modelId.includes("opus-4.6")) return "max";
 			return "high";
@@ -1511,7 +1592,7 @@ function browserMcpServerNameFromAllowedTools(allowedTools: unknown): string | u
 		if (typeof toolName !== "string") continue;
 		const parsed = parseAllowedMcpToolName(toolName);
 		if (!parsed) continue;
-		if (parsed.server === "gsd-browser" || parsed.tool.startsWith("browser_")) {
+		if (parsed.server === "gsd-browser" || hasBrowserContractPrefix(parsed.tool)) {
 			return parsed.server;
 		}
 	}
@@ -1524,7 +1605,7 @@ function workflowMcpServerNameFromAllowedTools(allowedTools: unknown): string |
 	for (const toolName of allowedTools) {
 		if (typeof toolName !== "string") continue;
 		const parsed = parseAllowedMcpToolName(toolName);
-		if (!parsed || parsed.server === browserServerName || parsed.tool.startsWith("browser_")) continue;
+		if (!parsed || parsed.server === browserServerName || hasBrowserContractPrefix(parsed.tool)) continue;
 		return parsed.server;
 	}
 	return undefined;
@@ -1658,14 +1739,23 @@ export function buildSdkOptions(
 	const workflowServerName = projectWorkflowServerName ?? injectedWorkflowServerName;
 	const browserServerName = projectBrowserServerName ?? injectedBrowserServerName;
 
-	// If a default GSD MCP server is already declared in the project's .mcp.json
-	// or .claude/settings.json, do not inject it again via mcpServers. Passing the
-	// same server name from two sources causes a duplicate registration conflict
-	// that prevents the MCP server from loading (tools become unavailable).
+	// Non-strict (non-phase) sessions load ~/.claude/settings.json via settingSources
+	// including "user". If the user declared the same server names there, injecting them
+	// again via mcpServers causes duplicate registration and leaves MCP tools unavailable.
+	// Strict (gsdPhase) sessions set settingSources=[] so user settings are not loaded.
+	const userDiscovered = !gsdPhase ? discoverUserMcpServerNames() : [];
+	const allDiscovered = discovered.length > 0 || userDiscovered.length > 0
+		? [...discovered, ...userDiscovered]
+		: discovered;
+
+	// If a default GSD MCP server is already declared in project config or in the user's
+	// ~/.claude/settings.json (when that file will be loaded), do not inject it again via
+	// mcpServers. Passing the same server name from two sources causes a duplicate
+	// registration conflict that prevents the MCP server from loading (tools become unavailable).
 	const workflowAlreadyInProject = projectWorkflowServerName !== undefined
-		|| (injectedWorkflowServerName !== undefined && discovered.includes(injectedWorkflowServerName));
+		|| (injectedWorkflowServerName !== undefined && allDiscovered.includes(injectedWorkflowServerName));
 	const browserAlreadyInProject = projectBrowserServerName !== undefined
-		|| (injectedBrowserServerName !== undefined && discovered.includes(injectedBrowserServerName));
+		|| (injectedBrowserServerName !== undefined && allDiscovered.includes(injectedBrowserServerName));
 	const mcpServersToInject = { ...defaultMcpServers.servers };
 	if (workflowAlreadyInProject && injectedWorkflowServerName) delete mcpServersToInject[injectedWorkflowServerName];
 	if (browserAlreadyInProject && injectedBrowserServerName) delete mcpServersToInject[injectedBrowserServerName];
@@ -1725,14 +1815,21 @@ export function buildSdkOptions(
 	const sdkMcpServers = inlinePhaseMcpServers ?? filteredMcpServers;
 	const strictMcpConfig = !!inlinePhaseMcpServers;
 	// Strict phase configs inline the exact MCP servers GSD needs. Loading
-	// project/local settings at the same time can duplicate those servers and
+	// Claude Code settings at the same time can duplicate those servers and
 	// leave allowed mcp__... tools with no registered backing tool.
-	const settingSources = strictMcpConfig ? [] : ["project", "local"];
+	const settingSources = strictMcpConfig ? [] : ["user", "project", "local"];
 	const exactWorkflowMcpTools = resolveExactWorkflowMcpToolsForPhase(
 		gsdPhase,
 		workflowServerName,
 		workflowExplicitlyBlocked,
 	);
+	const questionToolSurface = resolveWorkflowQuestionToolSurface({
+		workflowServerName,
+		workflowExplicitlyBlocked,
+		workflowMcpTools,
+		exactWorkflowMcpTools,
+		env: process.env,
+	});
 	const runUatDisallowedTools = gsdPhase === "run-uat" && workflowServerName
 		? [
 				...RUN_UAT_FORBIDDEN_TOOL_NAMES.filter((toolName) => !toolName.startsWith("mcp__")),
@@ -1746,6 +1843,7 @@ export function buildSdkOptions(
 	const disallowedTools: string[] = [...new Set([
 		"ToolSearch",
 		...(workflowMcpTools.length > 0 || exactWorkflowMcpTools.length > 0 ? ["AskUserQuestion"] : []),
+		...questionToolSurface.disallowedTools,
 		...runUatDisallowedTools,
 		...extraDisallowedTools,
 	])];
@@ -1807,6 +1905,8 @@ export function buildSdkOptions(
 			|| modelId.includes("opus-4.7")
 			|| modelId.includes("opus-4-8")
 			|| modelId.includes("opus-4.8")
+			|| modelId.includes("fable-5")
+			|| modelId.includes("fable.5")
 		) ? ["context-1m-2025-08-07"] : [],
 		...(thinkingConfig ?? {}),
 		...(effort ? { effort } : {}),
@@ -1814,261 +1914,6 @@ export function buildSdkOptions(
 	};
 }
 
-/** Normalise heterogeneous SDK tool-result content (string, array, or object) into a uniform `ExternalToolResultContentBlock[]`. */
-function normalizeToolResultContent(content: unknown): ExternalToolResultContentBlock[] {
-	if (typeof content === "string") {
-		return [{ type: "text", text: content }];
-	}
-
-	if (!Array.isArray(content)) {
-		if (content == null) return [{ type: "text", text: "" }];
-		return [{ type: "text", text: JSON.stringify(content) }];
-	}
-
-	const blocks: ExternalToolResultContentBlock[] = [];
-
-	for (const item of content) {
-		if (typeof item === "string") {
-			blocks.push({ type: "text", text: item });
-			continue;
-		}
-		if (!item || typeof item !== "object") {
-			blocks.push({ type: "text", text: String(item) });
-			continue;
-		}
-
-		const block = item as Record<string, unknown>;
-		if (block.type === "text") {
-			blocks.push({ type: "text", text: typeof block.text === "string" ? block.text : "" });
-			continue;
-		}
-		if (
-			block.type === "image"
-			&& typeof block.data === "string"
-			&& typeof block.mimeType === "string"
-		) {
-			blocks.push({ type: "image", data: block.data, mimeType: block.mimeType });
-			continue;
-		}
-
-		blocks.push({ type: "text", text: JSON.stringify(block) });
-	}
-
-	return blocks.length > 0 ? blocks : [{ type: "text", text: "" }];
-}
-
-/**
- * Extract a `details` payload from an MCP tool-result block.
- *
- * MCP's `CallToolResult` carries structured data in `structuredContent` — the
- * protocol's supported channel for non-text payloads. Claude Code's synthetic
- * user message may surface that field in one of two shapes depending on SDK
- * version: as a sibling on the `mcp_tool_result` block itself, or as a
- * dedicated content sub-block with `type: "structuredContent"`. Snake-case
- * (`structured_content`) is accepted defensively in case a transport hop
- * rewrites casing. All other shapes fall back to an empty object so callers
- * can rely on `details` being present.
- */
-function extractStructuredDetailsFromBlock(block: Record<string, unknown>): Record<string, unknown> | undefined {
-	const sibling = block.structuredContent ?? (block as Record<string, unknown>).structured_content;
-	if (sibling && typeof sibling === "object" && !Array.isArray(sibling)) {
-		return sibling as Record<string, unknown>;
-	}
-
-	if (Array.isArray(block.content)) {
-		for (const item of block.content) {
-			if (!item || typeof item !== "object") continue;
-			const sub = item as Record<string, unknown>;
-			if (sub.type !== "structuredContent" && sub.type !== "structured_content") continue;
-			const payload = sub.structuredContent ?? sub.structured_content ?? sub.data ?? sub.value;
-			if (payload && typeof payload === "object" && !Array.isArray(payload)) {
-				return payload as Record<string, unknown>;
-			}
-		}
-	}
-
-	// Return undefined (not {}) when no structured payload is present, matching
-	// the pre-#4477 contract where `details` was nullable. An empty-object
-	// sentinel is truthy and breaks downstream consumers that gate on
-	// `if (details)`. `undefined` matches the type of the field these results
-	// flow into (`Record<string, unknown> | undefined`).
-	return undefined;
-}
-
-/**
- * True for items that are MCP `structuredContent` pseudo-blocks living inside
- * a tool-result `content[]` array. These blocks carry the structured payload
- * (extracted separately by `extractStructuredDetailsFromBlock`) and must NOT
- * leak into the visible content rendered to the user — otherwise the renderer
- * stringifies the JSON pseudo-block and shows it next to the actual tool
- * output. See PR #4477 review (post-fix-round).
- */
-function isStructuredContentPseudoBlock(item: unknown): boolean {
-	if (!item || typeof item !== "object") return false;
-	const type = (item as Record<string, unknown>).type;
-	return type === "structuredContent" || type === "structured_content";
-}
-
-/**
- * Strip `structuredContent` pseudo-blocks from a tool-result content array
- * before normalization. The structured payload is extracted via the sibling
- * `structuredContent` field (or a dedicated extractor pass on the raw block);
- * the visible content path must not include the pseudo-block itself.
- */
-function stripStructuredContentPseudoBlocks(content: unknown): unknown {
-	if (!Array.isArray(content)) return content;
-	return content.filter((item) => !isStructuredContentPseudoBlock(item));
-}
-
-/** Extract tool result payloads from an SDK synthetic user message, keyed by tool-use ID. */
-export function extractToolResultsFromSdkUserMessage(message: SDKUserMessage): Array<{
-	toolUseId: string;
-	result: ExternalToolResultPayload;
-}> {
-	const extracted: Array<{ toolUseId: string; result: ExternalToolResultPayload }> = [];
-	const seen = new Set<string>();
-	const rawMessage = message.message as Record<string, unknown> | null | undefined;
-	const content = Array.isArray(rawMessage?.content) ? rawMessage.content : [];
-
-	for (const item of content) {
-		if (!item || typeof item !== "object") continue;
-		const block = item as Record<string, unknown>;
-		const type = typeof block.type === "string" ? block.type : "";
-		if (type !== "tool_result" && type !== "mcp_tool_result") continue;
-
-		const toolUseId = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
-		if (!toolUseId || seen.has(toolUseId)) continue;
-		seen.add(toolUseId);
-
-		extracted.push({
-			toolUseId,
-			result: {
-				content: normalizeToolResultContent(stripStructuredContentPseudoBlocks(block.content)),
-				details: extractStructuredDetailsFromBlock(block),
-				isError: block.is_error === true,
-			},
-		});
-	}
-
-	if (extracted.length === 0) {
-		const fallback = message.tool_use_result;
-		if (fallback && typeof fallback === "object") {
-			const toolResult = fallback as Record<string, unknown>;
-			const toolUseId = typeof toolResult.tool_use_id === "string" ? toolResult.tool_use_id : "";
-			if (toolUseId) {
-				extracted.push({
-					toolUseId,
-					result: {
-						content: normalizeToolResultContent(stripStructuredContentPseudoBlocks(toolResult.content)),
-						details: extractStructuredDetailsFromBlock(toolResult),
-						isError: toolResult.is_error === true,
-					},
-				});
-			}
-		}
-	}
-
-	return extracted;
-}
-
-/** Attach external tool results from the SDK synthetic user message to their corresponding tool-call blocks by ID. */
-function attachExternalResultsToToolBlocks(
-	toolBlocks: AssistantMessage["content"],
-	toolResultsById: ReadonlyMap<string, ExternalToolResultPayload>,
-): void {
-	for (const block of toolBlocks) {
-		if (block.type !== "toolCall" && block.type !== "serverToolUse") continue;
-		const externalResult = toolResultsById.get(block.id);
-		if (!externalResult) continue;
-		(block as ToolCallWithExternalResult & { id: string }).externalResult = externalResult;
-	}
-}
-
-/**
- * Build the final assistant content that Agent Core consumes in
- * `externalToolExecution` mode. This preserves tool-call blocks, attaches any
- * SDK-produced external results by tool-call id, and then appends the final
- * text/thinking blocks for the completed turn.
- */
-export function buildFinalAssistantContent(params: {
-	intermediateToolBlocks: AssistantMessage["content"];
-	pendingContent?: AssistantMessage["content"];
-	toolResultsById: ReadonlyMap<string, ExternalToolResultPayload>;
-	lastThinkingContent?: string;
-	lastTextContent?: string;
-	fallbackResultText?: string;
-}): AssistantMessage["content"] {
-	const mergedToolBlocks = [...params.intermediateToolBlocks];
-	if (params.pendingContent) {
-		mergePendingToolCalls(mergedToolBlocks, params.pendingContent);
-	}
-	attachExternalResultsToToolBlocks(mergedToolBlocks, params.toolResultsById);
-
-	const finalContent: AssistantMessage["content"] = [...mergedToolBlocks];
-	if (params.pendingContent && params.pendingContent.length > 0) {
-		for (const block of params.pendingContent) {
-			if (block.type === "text" || block.type === "thinking") {
-				finalContent.push(block);
-			}
-		}
-	} else {
-		if (params.lastThinkingContent) {
-			finalContent.push({ type: "thinking", thinking: params.lastThinkingContent });
-		}
-		if (params.lastTextContent) {
-			finalContent.push({ type: "text", text: params.lastTextContent });
-		}
-	}
-
-	if (finalContent.length === 0 && params.fallbackResultText) {
-		finalContent.push({ type: "text", text: params.fallbackResultText });
-	}
-
-	return finalContent;
-}
-
-/**
- * Merge tool-call blocks from the active partial-message builder into the
- * running list of intermediate tool calls, preserving order and de-duping
- * by tool-call id. Exposed for testing the F3 fix (final-turn tool calls
- * dropped when `result` arrives without a preceding synthetic `user`).
- */
-export function mergePendingToolCalls(
-	intermediate: AssistantMessage["content"],
-	pending: AssistantMessage["content"],
-): AssistantMessage["content"] {
-	const alreadyIncluded = new Set<string>();
-	for (const block of intermediate) {
-		if (block.type === "toolCall") alreadyIncluded.add(block.id);
-	}
-	for (const block of pending) {
-		if (block.type !== "toolCall") continue;
-		if (alreadyIncluded.has(block.id)) continue;
-		alreadyIncluded.add(block.id);
-		intermediate.push(block);
-	}
-	return intermediate;
-}
-
-export function handleClaudeCodePartialStreamEvent(
-	builder: PartialMessageBuilder | null,
-	event: BetaRawMessageStreamEvent,
-	modelId: string,
-): { builder: PartialMessageBuilder | null; assistantEvent: AssistantMessageEvent | null } {
-	if (event.type === "message_start") {
-		// Claude Code can emit repeated SDK message_start events inside one
-		// logical assistant response. Keep appending until a synthetic user
-		// tool-result boundary explicitly clears the builder.
-		return {
-			builder: builder ?? new PartialMessageBuilder((event as any).message?.model ?? modelId),
-			assistantEvent: null,
-		};
-	}
-
-	if (!builder) return { builder, assistantEvent: null };
-	return { builder, assistantEvent: builder.handleEvent(event) };
-}
-
 // ---------------------------------------------------------------------------
 // streamSimple implementation
 // ---------------------------------------------------------------------------
@@ -2155,8 +2000,9 @@ async function pumpSdkMessages(
 					: {}),
 			},
 		);
+		const workflowMcpServerName = workflowMcpServerNameFromAllowedTools(sdkOpts.allowedTools);
 		const prompt = buildPromptFromContext(context, {
-			workflowMcpServerName: workflowMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
+			workflowMcpServerName,
 			browserMcpServerName: browserMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
 		});
 		const queryPrompt = buildSdkQueryPrompt(context, prompt);
@@ -2198,7 +2044,34 @@ async function pumpSdkMessages(
 			switch (msg.type) {
 				// -- Init --
 				case "system": {
-					// Nothing to emit — the stream is already started.
+					// Tool Surface Readiness gate: the init message is the first (and
+					// only) point where the session reports its live tool surface and
+					// MCP server statuses. If the workflow server failed or has not
+					// registered this Unit's required tools, abort before the first
+					// model turn with a transient, recovery-classifiable error
+					// (tool-unavailable → retry) instead of letting the model hit
+					// "No such tool available" mid-Unit and improvise around it.
+					const init = msg as unknown as {
+						subtype?: string;
+						tools?: string[];
+						mcp_servers?: { name: string; status: string }[];
+					};
+					if (init.subtype === "init") {
+						const readinessError = getToolSurfaceReadinessError({
+							unitType: gsdPhase,
+							workflowServerName: workflowMcpServerName,
+							observation: { tools: init.tools ?? [], mcpServers: init.mcp_servers ?? [] },
+						});
+						if (readinessError) {
+							controller.abort();
+							stream.push({
+								type: "error",
+								reason: "error",
+								error: makeErrorMessage(modelId, readinessError),
+							});
+							return;
+						}
+					}
 					break;
 				}