@opengsd/gsd-pi 1.2.0-dev.5457a158 → 1.2.0-dev.6ccd27b3

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

@@ -15,7 +15,7 @@ import { homedir } from "node:os";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { ZERO_USAGE, mapUsage } from "./partial-builder.js";
-import { attachExternalResultsToToolBlocks, buildFinalAssistantContent, extractToolResultsFromSdkUserMessage, handleClaudeCodePartialStreamEvent, } from "./turn-assembler.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";
@@ -24,9 +24,13 @@ 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 { 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 { hasBrowserContractPrefix } from "../shared/browser-contract.js";
 import { showInterviewRound } from "../shared/tui.js";
-export { buildFinalAssistantContent, extractToolResultsFromSdkUserMessage, handleClaudeCodePartialStreamEvent, mergePendingToolCalls, } from "./turn-assembler.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
@@ -178,13 +182,18 @@ const GSD_PHASE_PATTERNS = [
     ["reassess-roadmap", /\b(?:UNIT:\s*Reassess Roadmap|reassess-roadmap)\b/i],
     ["complete-slice", /\b(?:UNIT:\s*Complete Slice|complete-slice)\b/i],
     ["replan-slice", /\b(?:UNIT:\s*Replan Slice|replan-slice)\b/i],
+    ["refine-slice", /\b(?:UNIT:\s*Refine Slice|refine-slice)\b/i],
     ["plan-slice", /\b(?:UNIT:\s*Plan Slice|plan-slice|gsd_plan_slice)\b/i],
     ["plan-milestone", /\b(?:UNIT:\s*Plan Milestone|plan-milestone|gsd_plan_milestone)\b/i],
     ["execute-task", /\b(?:UNIT:\s*Execute Task|execute-task|execute-task-simple|reactive-execute)\b/i],
     ["gate-evaluate", /\b(?:UNIT:\s*Gate Evaluate|gate-evaluate|gsd_save_gate_result)\b/i],
     ["research-milestone", /\b(?:UNIT:\s*Research Milestone|research-milestone)\b/i],
     ["research-slice", /\b(?:UNIT:\s*Research Slice|research-slice)\b/i],
+    ["research-decision", /\b(?:research decision|research-decision)\b/i],
     ["discuss-milestone", /\b(?:Discuss milestone|discuss-milestone)\b/i],
+    ["discuss-slice", /\b(?:Discuss slice|discuss-slice)\b/i],
+    ["discuss-project", /\b(?:discuss-project|Discuss project)\b/i],
+    ["discuss-requirements", /\b(?:discuss-requirements|Discuss requirements)\b/i],
 ];
 export function inferGsdPhaseFromContext(context) {
     const text = [
@@ -197,6 +206,24 @@ 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;
+        }
+    }
+    return inferGsdPhaseFromContext(context);
+}
 /**
  * Build a full conversational prompt from GSD's context messages.
  *
@@ -222,10 +249,15 @@ 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` +
+            `- 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 " +
@@ -319,9 +351,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
@@ -340,6 +374,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;
@@ -1290,7 +1358,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;
         }
     }
@@ -1304,7 +1372,7 @@ 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;
     }
@@ -1353,11 +1421,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({
@@ -1367,6 +1437,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 {
@@ -1378,6 +1467,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.
  *
@@ -1509,34 +1643,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);
@@ -1593,33 +1720,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;
+        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.
@@ -1637,18 +1764,13 @@ 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,
             browserMcpServerName: browserMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
         });
         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",
@@ -1661,192 +1783,303 @@ 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": {
-                    // 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 = getToolSurfaceReadinessError({
-                            unitType: gsdPhase,
-                            workflowServerName: workflowMcpServerName,
-                            observation: { tools: init.tools ?? [], mcpServers: init.mcp_servers ?? [] },
+        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,
+                        signal: options?.signal,
+                    });
+                    if (preflightError) {
+                        stream.push({
+                            type: "error",
+                            reason: "error",
+                            error: makeErrorMessage(modelId, preflightError),
                         });
-                        if (readinessError) {
-                            controller.abort();
+                        return;
+                    }
+                    workflowMcpPreflightVerified = true;
+                }
+                finally {
+                    uiContext?.setStatus?.("gsd-step", "");
+                }
+                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: "error",
-                                error: makeErrorMessage(modelId, readinessError),
+                                reason: "aborted",
+                                error: makeAbortedMessage(modelId, lastTextContent),
                             });
                             return;
                         }
-                    }
-                    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);
+                        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;
+                                    }
                                 }
+                                break;
                             }
-                        }
-                    }
-                    break;
-                }
-                // -- 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;
+                            // -- 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);
+                                            }
+                                        }
+                                    }
+                                }
+                                break;
                             }
-                            else if (block.type === "toolCall" || block.type === "serverToolUse") {
-                                // Collect tool blocks for externalToolExecution rendering
-                                intermediateToolBlocks.push(block);
+                            // -- 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;
                             }
-                        }
-                    }
-                    // 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,
-                                    });
+                            // -- 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);
+                                        }
+                                    }
                                 }
-                                catch (error) {
-                                    console.warn("[claude-code] onExternalToolResult callback failed:", error);
+                                // 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);
                                 }
-                                stream.push({
-                                    type: "toolcall_end",
-                                    contentIndex,
-                                    toolCall: block,
-                                    partial: builder.message,
-                                });
+                                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,
+                                            });
+                                        }
+                                    }
+                                }
+                                builder = null;
+                                break;
                             }
-                            else if (block.type === "serverToolUse") {
-                                try {
-                                    await onExternalToolResult?.({
-                                        toolCall: serverToolUseToToolCallLike(block),
-                                        result: extResult,
-                                    });
+                            // -- 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 });
                                 }
-                                catch (error) {
-                                    console.warn("[claude-code] onExternalToolResult callback failed:", error);
+                                else {
+                                    stream.push({ type: "done", reason: "stop", message: finalMessage });
                                 }
-                                stream.push({
-                                    type: "server_tool_use",
-                                    contentIndex,
-                                    partial: builder.message,
-                                });
+                                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.