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

package/dist/resources/extensions/claude-code-cli/stream-adapter.js

@@ -14,13 +14,24 @@ import { existsSync, readFileSync } from "node:fs";
 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 { ZERO_USAGE, mapUsage } from "./partial-builder.js";
+import { attachExternalResultsToToolBlocks, buildFinalAssistantContent, extractToolResultsFromSdkUserMessage, handleClaudeCodePartialStreamEvent, shouldSuppressDuplicateToolUnavailableBlock, } 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 { getUnitToolSurfaceContract } from "../gsd/unit-tool-contracts.js";
+import { awaitWorkflowMcpToolRegistration, getToolSurfaceReadinessError, POST_PREFLIGHT_READINESS_RETRY_DELAYS_MS, POST_PREFLIGHT_SDK_SETTLE_MS, TOOL_SURFACE_NOT_READY, } from "../gsd/tool-surface-readiness.js";
+import { beginWorkflowMcpSdkSession, 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 } from "../shared/tui.js";
+export { buildFinalAssistantContent, extractToolResultsFromSdkUserMessage, handleClaudeCodePartialStreamEvent, mergePendingToolCalls, shouldSuppressDuplicateToolUnavailableBlock, } from "./turn-assembler.js";
 export function serverToolUseToToolCallLike(block) {
     const argumentsValue = block.input && typeof block.input === "object" && !Array.isArray(block.input)
         ? block.input
@@ -165,25 +176,44 @@ function extractMessageText(msg) {
     }
     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 = [
-    ["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],
-    ["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],
-    ["discuss-milestone", /\b(?:Discuss milestone|discuss-milestone)\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) {
+    // 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))
@@ -191,6 +221,44 @@ export function inferGsdPhaseFromContext(context) {
     }
     return undefined;
 }
+/**
+ * Resolve the GSD unit phase for Claude Code SDK sessions. Guided-flow
+ * dispatch records the authoritative unit type before the turn is queued;
+ * prefer that over regex inference from prompt text.
+ */
+export function resolveGsdPhaseForSdk(context, projectRoot) {
+    const resolvedRoot = resolveWorkflowMcpProjectRoot(projectRoot);
+    const guided = getGuidedUnitContext(resolvedRoot)
+        ?? getGuidedUnitContext(projectRoot)
+        ?? getGuidedUnitContext();
+    if (guided?.unitType) {
+        const guidedRoot = resolveWorkflowMcpProjectRoot(guided.basePath);
+        if (guidedRoot === resolvedRoot) {
+            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);
+}
 /**
  * Build a full conversational prompt from GSD's context messages.
  *
@@ -216,10 +284,17 @@ export function buildPromptFromContext(context, toolContext = {}) {
     const workflowToolLine = toolContext.workflowMcpServerName
         ? "- 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`
+            `(e.g. mcp__${toolContext.workflowMcpServerName}__gsd_exec, mcp__${toolContext.workflowMcpServerName}__gsd_save_gate_result)\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 NOT available — never use it to discover tools; invoke the MCP tool directly\n"
+        ? "- ToolSearch is available only for Claude Code deferred workflow MCP hydration. " +
+            `If mcp__${toolContext.workflowMcpServerName}__<tool_name> is missing or Claude Code reports the server is still connecting, ` +
+            `use ToolSearch with select:mcp__${toolContext.workflowMcpServerName}__<tool_name> or the base tool name, then call the returned MCP tool directly. ` +
+            "Do not use ToolSearch for browser_* tools or general discovery.\n"
         : "- ToolSearch is NOT available — never use it to discover tools\n";
     const browserToolLine = toolContext.browserMcpServerName
         ? "- Browser verification uses gsd-browser MCP by default — call browser tools as " +
@@ -313,9 +388,11 @@ export function buildSdkQueryPrompt(context, textPrompt = buildPromptFromContext
         message: { role: "user", content },
         parent_tool_use_id: null,
     };
-    return (async function* () {
-        yield sdkMessage;
-    })();
+    return {
+        async *[Symbol.asyncIterator]() {
+            yield sdkMessage;
+        },
+    };
 }
 // ---------------------------------------------------------------------------
 // Error helper
@@ -334,6 +411,40 @@ function makeErrorMessage(model, errorMsg) {
         timestamp: Date.now(),
     };
 }
+export function buildWorkflowMcpReadinessProgressMessage(input) {
+    const { unitType, workflowServerName, stage } = input;
+    if (stage === "preflight") {
+        return `Starting ${workflowServerName} MCP for ${unitType}; waiting for workflow tools to register...`;
+    }
+    const attempt = input.attempt === undefined ? "" : ` attempt ${input.attempt}`;
+    const delay = input.delayMs === undefined ? "" : ` Retrying in ${formatReadinessDelay(input.delayMs)}.`;
+    return `Still waiting for ${workflowServerName} MCP tools for ${unitType}${attempt}.${delay}`;
+}
+function formatReadinessDelay(delayMs) {
+    if (delayMs < 1_000)
+        return `${delayMs}ms`;
+    const seconds = delayMs / 1_000;
+    return Number.isInteger(seconds) ? `${seconds}s` : `${seconds.toFixed(1)}s`;
+}
+export function pushWorkflowMcpReadinessProgressEvent(input) {
+    const { stream, partial, state, message } = input;
+    if (!message)
+        return;
+    let contentIndex = state.contentIndex;
+    const existing = contentIndex === undefined ? undefined : partial.content[contentIndex];
+    if (contentIndex === undefined || existing?.type !== "text") {
+        contentIndex = partial.content.length;
+        state.contentIndex = contentIndex;
+        partial.content.push({ type: "text", text: "" });
+        stream.push({ type: "text_start", contentIndex, partial });
+    }
+    const block = partial.content[contentIndex];
+    if (block.type !== "text")
+        return;
+    const delta = block.text.length === 0 ? message : `\n${message}`;
+    block.text += delta;
+    stream.push({ type: "text_delta", contentIndex, delta, partial });
+}
 export function isClaudeCodeAbortErrorMessage(message) {
     if (!message)
         return false;
@@ -1078,7 +1189,26 @@ export function createClaudeCodeCanUseToolHandler(ui) {
 // ---------------------------------------------------------------------------
 // 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() {
+    _elicitationSeq = (_elicitationSeq + 1) % Number.MAX_SAFE_INTEGER;
+    return _elicitationSeq;
+}
 export function createClaudeCodeElicitationHandler(ui) {
     if (!ui)
         return undefined;
@@ -1091,18 +1221,64 @@ export function createClaudeCodeElicitationHandler(ui) {
             const headlessAnswer = answerElicitationFromHeadlessAnswers(questions, loadHeadlessAnswers());
             if (headlessAnswer)
                 return headlessAnswer;
-            const interviewResult = await showInterviewRound(questions, { signal }, { ui }).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.id ?? `${Date.now()}-${nextElicitationSeq()}`);
+            markInteractiveElicitationStart();
+            markToolStart(elicId, "ask_user_questions");
+            try {
+                const interviewResult = await showInterviewRound(questions, { signal, overlay: true }, { ui }).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),
                 };
             }
-            return promptElicitationWithDialogs(request, questions, ui, signal);
+            finally {
+                markToolEnd(elicId);
+                markInteractiveElicitationEnd();
+            }
         }
         const textFields = parseTextInputElicitation(request);
         if (textFields) {
-            return promptTextInputElicitation(request, textFields, ui, signal);
+            const elicId = "cc-elicit-" + (request.id ?? `${Date.now()}-${nextElicitationSeq()}`);
+            markToolStart(elicId, "secure_env_collect");
+            try {
+                return await promptTextInputElicitation(request, textFields, ui, signal);
+            }
+            finally {
+                markToolEnd(elicId);
+            }
         }
         return { action: "decline" };
     };
@@ -1172,6 +1348,8 @@ function modelSupportsAdaptiveThinking(modelId) {
         || 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")
@@ -1193,7 +1371,9 @@ function mapThinkingLevelToAnthropicEffort(level, modelId) {
             if (modelId.includes("opus-4-7")
                 || modelId.includes("opus-4.7")
                 || modelId.includes("opus-4-8")
-                || 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";
@@ -1215,7 +1395,7 @@ function browserMcpServerNameFromAllowedTools(allowedTools) {
         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;
         }
     }
@@ -1229,18 +1409,30 @@ function workflowMcpServerNameFromAllowedTools(allowedTools) {
         if (typeof toolName !== "string")
             continue;
         const parsed = parseAllowedMcpToolName(toolName);
-        if (!parsed || parsed.server === browserServerName || parsed.tool.startsWith("browser_"))
+        if (!parsed || parsed.server === browserServerName || hasBrowserContractPrefix(parsed.tool))
             continue;
         return parsed.server;
     }
     return undefined;
 }
+function workflowQuestionToolAvailableFromAllowedTools(allowedTools, workflowMcpServerName, gsdPhase) {
+    if (!workflowMcpServerName || !gsdPhase)
+        return undefined;
+    return Array.isArray(allowedTools)
+        && allowedTools.includes(`mcp__${workflowMcpServerName}__ask_user_questions`);
+}
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
 function isStringRecord(value) {
     return isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
 }
+export function resolveWorkflowMcpPreflightServerConfig(mcpServers, workflowServerName) {
+    if (!workflowServerName || !isRecord(mcpServers))
+        return undefined;
+    const workflowServerConfig = mcpServers[workflowServerName];
+    return isRecord(workflowServerConfig) ? workflowServerConfig : undefined;
+}
 function cloneSdkMcpServerConfig(config) {
     if (!isRecord(config))
         return undefined;
@@ -1278,11 +1470,13 @@ function resolveProjectMcpServerConfigs(projectRoot, serverNames, fallbackServer
 function resolveExactWorkflowMcpToolsForPhase(gsdPhase, workflowServerName, workflowExplicitlyBlocked) {
     if (!gsdPhase || !workflowServerName || workflowExplicitlyBlocked)
         return [];
-    const requiredTools = gsdPhase === "run-uat"
+    const requestedTools = gsdPhase === "run-uat"
         ? [...RUN_UAT_WORKFLOW_TOOL_NAMES]
-        : getRequiredWorkflowToolsForAutoUnit(gsdPhase);
-    const supportTools = gsdPhase === "run-uat" ? [] : ["gsd_milestone_status"];
-    const requestedToolNames = [...new Set([...requiredTools, ...supportTools])];
+        : [
+            ...(getUnitToolSurfaceContract(gsdPhase)?.allowedGsdTools ?? []),
+            ...getRequiredWorkflowToolsForAutoUnit(gsdPhase),
+        ];
+    const requestedToolNames = [...new Set(requestedTools.filter((toolName) => toolName.startsWith("gsd_") || toolName === "ask_user_questions"))];
     if (requestedToolNames.length === 0)
         return [];
     return resolveToolPresentationPlan({
@@ -1292,6 +1486,25 @@ function resolveExactWorkflowMcpToolsForPhase(gsdPhase, workflowServerName, work
         requestedToolNames,
     }).presentedToolNames;
 }
+function resolveClaudeNativeToolsForPhase(gsdPhase) {
+    const standardClaudeTools = [
+        "Read",
+        "Write",
+        "Edit",
+        "Glob",
+        "Grep",
+        "Bash",
+        "Agent",
+        "WebFetch",
+        "WebSearch",
+    ];
+    if (!gsdPhase)
+        return standardClaudeTools;
+    if (gsdPhase === "run-uat" || gsdPhase === "complete-slice") {
+        return [...RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES];
+    }
+    return standardClaudeTools;
+}
 export function autoInitClaudeCodeWorkflowMcp(cwd) {
     const projectRoot = resolveWorkflowMcpProjectRoot(cwd);
     try {
@@ -1303,6 +1516,51 @@ export function autoInitClaudeCodeWorkflowMcp(cwd) {
         }
     }
 }
+export function resolveClaudeCodeToolSurfaceReadinessError(input) {
+    const error = getToolSurfaceReadinessError(input);
+    if (error
+        && input.allowPendingToolSearchHydration
+        && input.workflowServerName
+        && input.observation.mcpServers.some((server) => server.name === input.workflowServerName && server.status === "pending")) {
+        return Promise.resolve(null);
+    }
+    return Promise.resolve(error);
+}
+export { awaitWorkflowMcpToolRegistration } from "../gsd/tool-surface-readiness.js";
+const TOOL_SURFACE_READINESS_RETRY_DELAYS_MS = [500, 1_000, 2_000, 4_000, 8_000, 15_000, 15_000, 15_000];
+export function shouldRetryClaudeCodeToolSurfaceReadiness(error) {
+    if (!error)
+        return false;
+    return error.includes(TOOL_SURFACE_NOT_READY) && !/\bterminal\b/i.test(error);
+}
+export function resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(error, attempt, preflightVerified = false) {
+    if (!shouldRetryClaudeCodeToolSurfaceReadiness(error))
+        return null;
+    const delays = preflightVerified
+        ? POST_PREFLIGHT_READINESS_RETRY_DELAYS_MS
+        : TOOL_SURFACE_READINESS_RETRY_DELAYS_MS;
+    return delays[attempt] ?? null;
+}
+function makeAbortError() {
+    const error = new Error("AbortError: The operation was aborted");
+    error.name = "AbortError";
+    return error;
+}
+function delay(ms, signal) {
+    if (signal?.aborted)
+        return Promise.reject(makeAbortError());
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timeout);
+            reject(makeAbortError());
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
 /**
  * Build the options object passed to the Claude Agent SDK's `query()` call.
  *
@@ -1417,6 +1675,13 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
     // leave allowed mcp__... tools with no registered backing tool.
     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__")),
@@ -1427,33 +1692,27 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
             `mcp__${workflowServerName}__gsd_save_gate_result`,
         ]
         : [];
+    const allowToolSearchForWorkflowMcp = workflowMcpTools.length > 0 || exactWorkflowMcpTools.length > 0;
     const disallowedTools = [...new Set([
-            "ToolSearch",
+            ...(allowToolSearchForWorkflowMcp ? [] : ["ToolSearch"]),
+            ...(gsdPhase ? ["Skill"] : []),
             ...(workflowMcpTools.length > 0 || exactWorkflowMcpTools.length > 0 ? ["AskUserQuestion"] : []),
+            ...questionToolSurface.disallowedTools,
             ...runUatDisallowedTools,
             ...extraDisallowedTools,
         ])];
-    const standardClaudeTools = [
-        "Read",
-        "Write",
-        "Edit",
-        "Glob",
-        "Grep",
-        "Bash",
-        "Agent",
-        "WebFetch",
-        "WebSearch",
-    ];
+    const nativeTools = resolveClaudeNativeToolsForPhase(gsdPhase);
     const allowedTools = gsdPhase === "run-uat"
         ? [
-            ...RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES,
+            ...nativeTools,
             ...(exactWorkflowMcpTools.length > 0 ? exactWorkflowMcpTools : []),
             ...allowedBrowserMcpTools,
         ]
         : [
-            ...standardClaudeTools,
+            ...nativeTools,
             ...exactWorkflowMcpTools,
-            ...(workflowMcpTools.length > 0 ? workflowMcpTools : ["AskUserQuestion"]),
+            ...(!gsdPhase && workflowMcpTools.length > 0 ? workflowMcpTools : []),
+            ...(workflowMcpTools.length === 0 && exactWorkflowMcpTools.length === 0 ? ["AskUserQuestion"] : []),
             ...allowedBrowserMcpTools,
         ];
     const supportsAdaptive = modelSupportsAdaptiveThinking(modelId);
@@ -1486,237 +1745,28 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
             || modelId.includes("opus-4-7")
             || modelId.includes("opus-4.7")
             || modelId.includes("opus-4-8")
-            || modelId.includes("opus-4.8")) ? ["context-1m-2025-08-07"] : [],
+            || modelId.includes("opus-4.8")
+            || modelId.includes("fable-5")
+            || modelId.includes("fable.5")) ? ["context-1m-2025-08-07"] : [],
         ...(thinkingConfig ?? {}),
         ...(effort ? { effort } : {}),
         ...sdkExtraOptions,
     };
 }
-/** Normalise heterogeneous SDK tool-result content (string, array, or object) into a uniform `ExternalToolResultContentBlock[]`. */
-function normalizeToolResultContent(content) {
-    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 = [];
-    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;
-        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) {
-    const sibling = block.structuredContent ?? block.structured_content;
-    if (sibling && typeof sibling === "object" && !Array.isArray(sibling)) {
-        return sibling;
-    }
-    if (Array.isArray(block.content)) {
-        for (const item of block.content) {
-            if (!item || typeof item !== "object")
-                continue;
-            const sub = item;
-            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;
-            }
-        }
-    }
-    // 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) {
-    if (!item || typeof item !== "object")
-        return false;
-    const type = item.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) {
-    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) {
-    const extracted = [];
-    const seen = new Set();
-    const rawMessage = message.message;
-    const content = Array.isArray(rawMessage?.content) ? rawMessage.content : [];
-    for (const item of content) {
-        if (!item || typeof item !== "object")
-            continue;
-        const block = item;
-        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;
-            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, toolResultsById) {
-    for (const block of toolBlocks) {
-        if (block.type !== "toolCall" && block.type !== "serverToolUse")
-            continue;
-        const externalResult = toolResultsById.get(block.id);
-        if (!externalResult)
-            continue;
-        block.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) {
-    const mergedToolBlocks = [...params.intermediateToolBlocks];
-    if (params.pendingContent) {
-        mergePendingToolCalls(mergedToolBlocks, params.pendingContent);
-    }
-    attachExternalResultsToToolBlocks(mergedToolBlocks, params.toolResultsById);
-    const finalContent = [...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, pending) {
-    const alreadyIncluded = new Set();
-    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, event, modelId) {
-    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.message?.model ?? modelId),
-            assistantEvent: null,
-        };
-    }
-    if (!builder)
-        return { builder, assistantEvent: null };
-    return { builder, assistantEvent: builder.handleEvent(event) };
-}
 // ---------------------------------------------------------------------------
 // streamSimple implementation
 // ---------------------------------------------------------------------------
+let capturedClaudeCodeUIContext;
+/**
+ * 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) {
+    capturedClaudeCodeUIContext = ui;
+}
 /**
  * GSD streamSimple function that delegates to the Claude Agent SDK.
  *
@@ -1730,33 +1780,33 @@ export function streamViaClaudeCode(model, context, options) {
     void pumpSdkMessages(model, context, options, stream);
     return stream;
 }
+function createSdkAttemptMessageState() {
+    return {
+        builder: null,
+        intermediateToolBlocks: [],
+        toolResultsById: new Map(),
+    };
+}
 /** Async pump that drives the Claude Agent SDK's async-iterable message stream and pushes events into `stream`. */
 async function pumpSdkMessages(model, context, options, stream) {
     const modelId = model.id;
-    let builder = null;
     /** Track the last text content seen across all assistant turns for the final message. */
     let lastTextContent = "";
     let lastThinkingContent = "";
-    /** Collect tool blocks from intermediate SDK turns for tool execution rendering. */
-    const intermediateToolBlocks = [];
-    /** Preserve real external tool results from Claude Code's synthetic user messages. */
-    const toolResultsById = new Map();
     try {
-        // Dynamic import — the SDK is an optional dependency.
-        const sdkModule = "@anthropic-ai/claude-agent-sdk";
-        const sdk = (await import(/* webpackIgnore: true */ sdkModule));
-        // Bridge GSD's AbortSignal to SDK's AbortController
-        const controller = new AbortController();
-        if (options?.signal) {
-            options.signal.addEventListener("abort", () => controller.abort(), { once: true });
-        }
         const permissionMode = await resolveClaudePermissionMode();
-        const uiContext = options?.extensionUIContext;
-        const onExternalToolCall = options?.onExternalToolCall;
-        const onExternalToolResult = options?.onExternalToolResult;
+        const claudeOptions = options;
+        const uiContext = claudeOptions?.extensionUIContext ?? capturedClaudeCodeUIContext;
+        const onExternalToolCall = claudeOptions?.onExternalToolCall;
+        const onExternalToolResult = claudeOptions?.onExternalToolResult;
+        const sdkQueryForTest = claudeOptions?._sdkQueryForTest;
+        const query = sdkQueryForTest ?? 
+        // Dynamic import — the SDK is an optional dependency.
+        (await import(/* webpackIgnore: true */ "@anthropic-ai/claude-agent-sdk")).query;
         const cwd = resolveClaudeCodeCwd(options);
+        const projectRoot = resolveWorkflowMcpProjectRoot(cwd);
         autoInitClaudeCodeWorkflowMcp(cwd);
-        const gsdPhase = inferGsdPhaseFromContext(context);
+        const gsdPhase = resolveGsdPhaseForSdk(context, projectRoot);
         const canUseToolHandler = createClaudeCodeCanUseToolHandler(uiContext);
         // When no UI is available (headless / auto-mode), auto-approve all
         // tool requests. This replaces the old bypassPermissions workaround.
@@ -1773,18 +1823,15 @@ async function pumpSdkMessages(model, context, options, stream) {
                 }
                 : {}),
         });
+        const workflowMcpServerName = workflowMcpServerNameFromAllowedTools(sdkOpts.allowedTools);
+        const allowPendingToolSearchHydration = Boolean(workflowMcpServerName && gsdPhase)
+            && !sdkOpts.disallowedTools?.includes("ToolSearch");
         const prompt = buildPromptFromContext(context, {
-            workflowMcpServerName: workflowMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
+            workflowMcpServerName,
             browserMcpServerName: browserMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
+            questionToolAvailable: workflowQuestionToolAvailableFromAllowedTools(sdkOpts.allowedTools, workflowMcpServerName, gsdPhase),
         });
         const queryPrompt = buildSdkQueryPrompt(context, prompt);
-        const queryResult = sdk.query({
-            prompt: queryPrompt,
-            options: {
-                ...sdkOpts,
-                abortController: controller,
-            },
-        });
         // Emit start with an empty partial
         const initialPartial = {
             role: "assistant",
@@ -1797,169 +1844,304 @@ async function pumpSdkMessages(model, context, options, stream) {
             timestamp: Date.now(),
         };
         stream.push({ type: "start", partial: initialPartial });
-        for await (const msg of queryResult) {
-            if (options?.signal?.aborted) {
-                // User-initiated cancel — emit an aborted error so the agent
-                // loop classifies this as a deliberate stop, not a transient
-                // provider failure that should be retried.
-                stream.push({
-                    type: "error",
-                    reason: "aborted",
-                    error: makeAbortedMessage(modelId, lastTextContent),
-                });
-                return;
-            }
-            switch (msg.type) {
-                // -- Init --
-                case "system": {
-                    // Nothing to emit — the stream is already started.
-                    break;
-                }
-                // -- Streaming partial messages --
-                case "stream_event": {
-                    const partial = msg;
-                    const event = partial.event;
-                    const result = handleClaudeCodePartialStreamEvent(builder, event, modelId);
-                    builder = result.builder;
-                    const assistantEvent = result.assistantEvent;
-                    if (assistantEvent) {
-                        stream.push(assistantEvent);
-                        if (assistantEvent.type === "toolcall_start") {
-                            const toolBlock = assistantEvent.partial.content[assistantEvent.contentIndex];
-                            if (toolBlock?.type === "toolCall") {
-                                try {
-                                    await onExternalToolCall?.(toolBlock);
-                                }
-                                catch (error) {
-                                    console.warn("[claude-code] onExternalToolCall callback failed:", error);
-                                }
-                            }
-                        }
+        const readinessProgressState = {};
+        const trackWorkflowMcpSdk = Boolean(workflowMcpServerName && gsdPhase);
+        if (trackWorkflowMcpSdk)
+            beginWorkflowMcpSdkSession();
+        try {
+            let workflowMcpPreflightVerified = false;
+            const shouldRunWorkflowMcpPreflight = workflowMcpServerName && gsdPhase && !claudeOptions?._skipWorkflowMcpPreflightForTest;
+            if (shouldRunWorkflowMcpPreflight) {
+                try {
+                    const progressMessage = buildWorkflowMcpReadinessProgressMessage({
+                        unitType: gsdPhase,
+                        workflowServerName: workflowMcpServerName,
+                        stage: "preflight",
+                    });
+                    pushWorkflowMcpReadinessProgressEvent({
+                        stream,
+                        partial: initialPartial,
+                        state: readinessProgressState,
+                        message: progressMessage,
+                    });
+                    uiContext?.setStatus?.("gsd-step", progressMessage);
+                    const preflightError = await awaitWorkflowMcpToolRegistration({
+                        unitType: gsdPhase,
+                        workflowServerName: workflowMcpServerName,
+                        projectRoot,
+                        workflowServerConfig: resolveWorkflowMcpPreflightServerConfig(sdkOpts.mcpServers, workflowMcpServerName),
+                        signal: options?.signal,
+                    });
+                    if (preflightError) {
+                        stream.push({
+                            type: "error",
+                            reason: "error",
+                            error: makeErrorMessage(modelId, preflightError),
+                        });
+                        return;
                     }
-                    break;
+                    workflowMcpPreflightVerified = true;
                 }
-                // -- Complete assistant message (non-streaming fallback) --
-                case "assistant": {
-                    const sdkAssistant = msg;
-                    // Capture text content from complete messages
-                    for (const block of sdkAssistant.message.content) {
-                        if (block.type === "text") {
-                            lastTextContent = block.text;
-                        }
-                        else if (block.type === "thinking") {
-                            lastThinkingContent = block.thinking;
-                        }
-                    }
-                    break;
+                finally {
+                    uiContext?.setStatus?.("gsd-step", "");
                 }
-                // -- User message (synthetic tool result — signals turn boundary) --
-                case "user": {
-                    // Capture content from the completed turn before resetting
-                    if (builder) {
-                        for (const block of builder.message.content) {
-                            if (block.type === "text" && block.text) {
-                                lastTextContent = block.text;
-                            }
-                            else if (block.type === "thinking" && block.thinking) {
-                                lastThinkingContent = block.thinking;
-                            }
-                            else if (block.type === "toolCall" || block.type === "serverToolUse") {
-                                // Collect tool blocks for externalToolExecution rendering
-                                intermediateToolBlocks.push(block);
-                            }
+                if (workflowMcpPreflightVerified) {
+                    await delay(POST_PREFLIGHT_SDK_SETTLE_MS, options?.signal);
+                }
+            }
+            sdkAttemptLoop: for (let readinessAttempt = 0;; readinessAttempt++) {
+                let { builder, intermediateToolBlocks, toolResultsById } = createSdkAttemptMessageState();
+                const controller = new AbortController();
+                const forwardAbort = () => controller.abort();
+                if (options?.signal) {
+                    options.signal.addEventListener("abort", forwardAbort, { once: true });
+                }
+                const queryResult = query({
+                    prompt: queryPrompt,
+                    options: {
+                        ...sdkOpts,
+                        abortController: controller,
+                    },
+                });
+                try {
+                    for await (const msg of queryResult) {
+                        if (options?.signal?.aborted) {
+                            // User-initiated cancel — emit an aborted error so the agent
+                            // loop classifies this as a deliberate stop, not a transient
+                            // provider failure that should be retried.
+                            stream.push({
+                                type: "error",
+                                reason: "aborted",
+                                error: makeAbortedMessage(modelId, lastTextContent),
+                            });
+                            return;
                         }
-                    }
-                    // Extract tool results from the SDK's synthetic user message
-                    // and attach to corresponding tool call blocks immediately.
-                    for (const { toolUseId, result } of extractToolResultsFromSdkUserMessage(msg)) {
-                        toolResultsById.set(toolUseId, result);
-                    }
-                    attachExternalResultsToToolBlocks(intermediateToolBlocks, toolResultsById);
-                    // Push a synthetic toolcall_end for each tool call from this turn
-                    // so the TUI can render tool results in real-time during the SDK
-                    // session instead of waiting until the entire session completes.
-                    if (builder) {
-                        for (const block of builder.message.content) {
-                            const extResult = block.externalResult;
-                            if (!extResult)
-                                continue;
-                            const contentIndex = builder.message.content.indexOf(block);
-                            if (contentIndex < 0)
-                                continue;
-                            // Push synthetic completion events with result attached so the
-                            // chat-controller can update pending ToolExecutionComponents.
-                            if (block.type === "toolCall") {
-                                try {
-                                    await onExternalToolResult?.({
-                                        toolCall: block,
-                                        result: extResult,
+                        switch (msg.type) {
+                            // -- Init --
+                            case "system": {
+                                // 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;
+                                if (init.subtype === "init") {
+                                    const readinessError = await resolveClaudeCodeToolSurfaceReadinessError({
+                                        unitType: gsdPhase,
+                                        workflowServerName: workflowMcpServerName,
+                                        projectRoot,
+                                        observation: { tools: init.tools ?? [], mcpServers: init.mcp_servers ?? [] },
+                                        allowPendingToolSearchHydration,
                                     });
+                                    if (readinessError) {
+                                        const retryDelayMs = resolveClaudeCodeToolSurfaceReadinessRetryDelayMs(readinessError, readinessAttempt, workflowMcpPreflightVerified);
+                                        if (retryDelayMs !== null && !options?.signal?.aborted) {
+                                            controller.abort();
+                                            const progressMessage = buildWorkflowMcpReadinessProgressMessage({
+                                                unitType: gsdPhase ?? "workflow unit",
+                                                workflowServerName: workflowMcpServerName ?? "workflow",
+                                                stage: "retry",
+                                                attempt: readinessAttempt + 1,
+                                                delayMs: retryDelayMs,
+                                            });
+                                            pushWorkflowMcpReadinessProgressEvent({
+                                                stream,
+                                                partial: initialPartial,
+                                                state: readinessProgressState,
+                                                message: progressMessage,
+                                            });
+                                            uiContext?.setStatus?.("gsd-step", progressMessage);
+                                            await delay(retryDelayMs, options?.signal);
+                                            uiContext?.setStatus?.("gsd-step", "");
+                                            continue sdkAttemptLoop;
+                                        }
+                                        controller.abort();
+                                        stream.push({
+                                            type: "error",
+                                            reason: "error",
+                                            error: makeErrorMessage(modelId, readinessError),
+                                        });
+                                        return;
+                                    }
                                 }
-                                catch (error) {
-                                    console.warn("[claude-code] onExternalToolResult callback failed:", error);
+                                break;
+                            }
+                            // -- Streaming partial messages --
+                            case "stream_event": {
+                                const partial = msg;
+                                const event = partial.event;
+                                const result = handleClaudeCodePartialStreamEvent(builder, event, modelId);
+                                builder = result.builder;
+                                const assistantEvent = result.assistantEvent;
+                                if (assistantEvent) {
+                                    stream.push(assistantEvent);
+                                    if (assistantEvent.type === "toolcall_start") {
+                                        const toolBlock = assistantEvent.partial.content[assistantEvent.contentIndex];
+                                        if (toolBlock?.type === "toolCall") {
+                                            try {
+                                                await onExternalToolCall?.(toolBlock);
+                                            }
+                                            catch (error) {
+                                                console.warn("[claude-code] onExternalToolCall callback failed:", error);
+                                            }
+                                        }
+                                    }
                                 }
-                                stream.push({
-                                    type: "toolcall_end",
-                                    contentIndex,
-                                    toolCall: block,
-                                    partial: builder.message,
-                                });
+                                break;
                             }
-                            else if (block.type === "serverToolUse") {
-                                try {
-                                    await onExternalToolResult?.({
-                                        toolCall: serverToolUseToToolCallLike(block),
-                                        result: extResult,
-                                    });
+                            // -- Complete assistant message (non-streaming fallback) --
+                            case "assistant": {
+                                const sdkAssistant = msg;
+                                // Capture text content from complete messages
+                                for (const block of sdkAssistant.message.content) {
+                                    if (block.type === "text") {
+                                        lastTextContent = block.text;
+                                    }
+                                    else if (block.type === "thinking") {
+                                        lastThinkingContent = block.thinking;
+                                    }
+                                }
+                                break;
+                            }
+                            // -- User message (synthetic tool result — signals turn boundary) --
+                            case "user": {
+                                // Capture content from the completed turn before resetting
+                                if (builder) {
+                                    for (const block of builder.message.content) {
+                                        if (block.type === "text" && block.text) {
+                                            lastTextContent = block.text;
+                                        }
+                                        else if (block.type === "thinking" && block.thinking) {
+                                            lastThinkingContent = block.thinking;
+                                        }
+                                        else if (block.type === "toolCall" || block.type === "serverToolUse") {
+                                            // Collect tool blocks for externalToolExecution rendering
+                                            intermediateToolBlocks.push(block);
+                                        }
+                                    }
+                                }
+                                // Extract tool results from the SDK's synthetic user message
+                                // and attach to corresponding tool call blocks immediately.
+                                for (const { toolUseId, result } of extractToolResultsFromSdkUserMessage(msg)) {
+                                    toolResultsById.set(toolUseId, result);
                                 }
-                                catch (error) {
-                                    console.warn("[claude-code] onExternalToolResult callback failed:", error);
+                                attachExternalResultsToToolBlocks(intermediateToolBlocks, toolResultsById);
+                                // Push a synthetic toolcall_end for each tool call from this turn
+                                // so the TUI can render tool results in real-time during the SDK
+                                // session instead of waiting until the entire session completes.
+                                if (builder) {
+                                    for (const block of builder.message.content) {
+                                        const extResult = block.externalResult;
+                                        if (!extResult)
+                                            continue;
+                                        const contentIndex = builder.message.content.indexOf(block);
+                                        if (contentIndex < 0)
+                                            continue;
+                                        const suppressDuplicateUnavailable = shouldSuppressDuplicateToolUnavailableBlock(block, builder.message.content);
+                                        // Push synthetic completion events with result attached so the
+                                        // chat-controller can update pending ToolExecutionComponents.
+                                        if (block.type === "toolCall") {
+                                            if (suppressDuplicateUnavailable) {
+                                                delete block.externalResult;
+                                                stream.push({
+                                                    type: "toolcall_end",
+                                                    contentIndex,
+                                                    toolCall: block,
+                                                    partial: builder.message,
+                                                });
+                                                block.externalResult = extResult;
+                                                continue;
+                                            }
+                                            try {
+                                                await onExternalToolResult?.({
+                                                    toolCall: block,
+                                                    result: extResult,
+                                                });
+                                            }
+                                            catch (error) {
+                                                console.warn("[claude-code] onExternalToolResult callback failed:", error);
+                                            }
+                                            stream.push({
+                                                type: "toolcall_end",
+                                                contentIndex,
+                                                toolCall: block,
+                                                partial: builder.message,
+                                            });
+                                        }
+                                        else if (block.type === "serverToolUse") {
+                                            try {
+                                                await onExternalToolResult?.({
+                                                    toolCall: serverToolUseToToolCallLike(block),
+                                                    result: extResult,
+                                                });
+                                            }
+                                            catch (error) {
+                                                console.warn("[claude-code] onExternalToolResult callback failed:", error);
+                                            }
+                                            stream.push({
+                                                type: "server_tool_use",
+                                                contentIndex,
+                                                partial: builder.message,
+                                            });
+                                        }
+                                    }
                                 }
-                                stream.push({
-                                    type: "server_tool_use",
-                                    contentIndex,
-                                    partial: builder.message,
+                                builder = null;
+                                break;
+                            }
+                            // -- Result (terminal) --
+                            case "result": {
+                                const result = msg;
+                                const finalContent = buildFinalAssistantContent({
+                                    intermediateToolBlocks,
+                                    pendingContent: builder?.message.content,
+                                    toolResultsById,
+                                    lastThinkingContent,
+                                    lastTextContent,
+                                    fallbackResultText: result.subtype === "success" && result.result ? result.result : undefined,
                                 });
+                                const finalMessage = {
+                                    role: "assistant",
+                                    content: finalContent,
+                                    api: "anthropic-messages",
+                                    provider: "claude-code",
+                                    model: modelId,
+                                    usage: mapUsage(result.usage, result.total_cost_usd),
+                                    stopReason: result.is_error ? "error" : "stop",
+                                    timestamp: Date.now(),
+                                };
+                                if (result.is_error) {
+                                    finalMessage.errorMessage = getResultErrorMessage(result);
+                                    stream.push({ type: "error", reason: "error", error: finalMessage });
+                                }
+                                else {
+                                    stream.push({ type: "done", reason: "stop", message: finalMessage });
+                                }
+                                return;
                             }
+                            default:
+                                break;
                         }
                     }
-                    builder = null;
-                    break;
                 }
-                // -- Result (terminal) --
-                case "result": {
-                    const result = msg;
-                    const finalContent = buildFinalAssistantContent({
-                        intermediateToolBlocks,
-                        pendingContent: builder?.message.content,
-                        toolResultsById,
-                        lastThinkingContent,
-                        lastTextContent,
-                        fallbackResultText: result.subtype === "success" && result.result ? result.result : undefined,
-                    });
-                    const finalMessage = {
-                        role: "assistant",
-                        content: finalContent,
-                        api: "anthropic-messages",
-                        provider: "claude-code",
-                        model: modelId,
-                        usage: mapUsage(result.usage, result.total_cost_usd),
-                        stopReason: result.is_error ? "error" : "stop",
-                        timestamp: Date.now(),
-                    };
-                    if (result.is_error) {
-                        finalMessage.errorMessage = getResultErrorMessage(result);
-                        stream.push({ type: "error", reason: "error", error: finalMessage });
-                    }
-                    else {
-                        stream.push({ type: "done", reason: "stop", message: finalMessage });
-                    }
-                    return;
+                finally {
+                    options?.signal?.removeEventListener("abort", forwardAbort);
                 }
-                default:
-                    break;
+                // The SDK stream ended without a terminal `result` message and
+                // without a readiness retry (the only restart path, via
+                // `continue sdkAttemptLoop`). Break out so the post-loop
+                // exhaustion handler emits a transient stream-exhausted error,
+                // instead of silently starting another SDK session and looping
+                // forever.
+                break sdkAttemptLoop;
             }
         }
+        finally {
+            if (trackWorkflowMcpSdk)
+                endWorkflowMcpSdkSession();
+        }
         // Generator exhaustion without a terminal result is a stream interruption,
         // not a successful completion. Emitting an error lets GSD classify it as a
         // transient provider failure instead of advancing auto-mode state.