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

package/dist/resources/extensions/browser-tools/index.js

@@ -1,7 +1,7 @@
 /** browser-tools — Pi Browser Automation Contract adapter. */
 import { importExtensionModule } from "@gsd/pi-coding-agent";
 import { closeManagedGsdBrowser, registerManagedGsdBrowserTools, warmUpManagedGsdBrowser } from "./engine/managed-gsd-browser.js";
-import { resolveBrowserEngineMode } from "./engine/selection.js";
+import { commitBrowserEngineResolution, resolveAmbientBrowserEngineResolution } from "./engine/selection.js";
 import { setArtifactRootForCwd } from "./state.js";
 import { detectWebApp } from "./web-app-detect.js";
 let legacyRegistrationPromise = null;
@@ -130,12 +130,56 @@ function withBrowserArtifactCwdScope(pi) {
         },
     };
 }
-async function registerBrowserTools(pi) {
-    const engine = resolveBrowserEngineMode();
+/** Daemon-connect budget when the probe-resolved managed engine is verified at session start. */
+const PROBE_WARMUP_TIMEOUT_MS = 10_000;
+async function registerBrowserTools(pi, ctx) {
+    const projectRoot = ctx.cwd || process.cwd();
+    const resolution = resolveAmbientBrowserEngineResolution(projectRoot);
+    let engine = resolution.engine;
     if (engine === "off")
         return;
+    // A probe-resolved managed engine is only a prediction that gsd-browser
+    // works — prove it by connecting the daemon before committing the session's
+    // tool registrations to it. Connect failure falls back to legacy Playwright
+    // (the failure mode that made ADR-024 freeze the old default) and commits
+    // the outcome so ambient readers see the engine actually in use. When eager
+    // warm-up is disabled the daemon-connect proof cannot run, so the probe
+    // default treats the managed engine as unprovable and falls back to legacy
+    // rather than registering it unverified. An explicit
+    // GSD_BROWSER_ENGINE=gsd-browser override skips the gate and is honored
+    // verbatim, matching prior behavior.
+    if (engine === "gsd-browser" && resolution.source === "probe" && !registeredEngine) {
+        if (isWarmUpDisabled()) {
+            engine = commitLegacyFallback(projectRoot, "warm-up disabled; managed engine unverifiable; using legacy Playwright");
+        }
+        else {
+            const warmUp = await warmUpManagedGsdBrowser(ctx, AbortSignal.timeout(PROBE_WARMUP_TIMEOUT_MS));
+            if (!warmUp.ok) {
+                engine = commitLegacyFallback(projectRoot, `gsd-browser daemon connect failed (${warmUp.error}); using legacy Playwright`);
+                if (ctx.hasUI) {
+                    ctx.ui.notify(`gsd-browser engine unavailable (${warmUp.error}); using Playwright browser tools for this session.`, "warning");
+                }
+            }
+            else if (warmUp.coverageWarning && ctx.hasUI) {
+                ctx.ui.notify(warmUp.coverageWarning, "warning");
+            }
+        }
+    }
+    // Browser tool registrations are process-global and cannot be swapped once
+    // live. When an earlier session in this process already registered an engine
+    // and this project resolved a different one (per-project probe resolution can
+    // diverge across projects in a multi-session process), adopt the registered
+    // engine rather than throwing — a throw surfaces as "browser-tools failed to
+    // load" and leaves this session with no browser tools at all. Commit the
+    // adoption so ambient readers (UAT guidance, warm-up) describe the engine
+    // actually in use.
     if (registeredEngine && registeredEngine !== engine) {
-        throw new Error(`Browser tools already registered with GSD_BROWSER_ENGINE=${registeredEngine}. Restart GSD before switching to ${engine}.`);
+        engine = registeredEngine;
+        commitBrowserEngineResolution(projectRoot, {
+            engine,
+            source: "probe",
+            reason: `browser tools already registered with ${engine} earlier in this process; adopting it`,
+        });
     }
     let registration;
     if (engine === "legacy") {
@@ -165,27 +209,40 @@ async function registerBrowserTools(pi) {
         throw error;
     }
 }
+function commitLegacyFallback(projectRoot, reason) {
+    commitBrowserEngineResolution(projectRoot, { engine: "legacy", source: "probe", reason });
+    return "legacy";
+}
 function isWarmUpDisabled() {
     const value = process.env.GSD_BROWSER_WARMUP?.trim().toLowerCase();
     return value === "0" || value === "false" || value === "off";
 }
 /**
- * Auto-initialize the managed gsd-browser engine only when explicitly selected
- * for a web app. Best-effort and non-blocking: warm-up runs in the background
- * and only surfaces a warning if it fails.
+ * Auto-initialize the managed gsd-browser engine when it was selected via the
+ * explicit GSD_BROWSER_ENGINE override, which registers without the
+ * daemon-connect gate. Best-effort and non-blocking: warm-up runs in the
+ * background and only surfaces a warning if it fails. Probe-resolved sessions
+ * already connected (or fell back) during registration, so they are excluded
+ * to avoid re-warming and double-notifying.
  */
 function maybeWarmUpManagedEngine(pi, ctx) {
     if (isWarmUpDisabled())
         return;
-    if (resolveBrowserEngineMode() !== "gsd-browser")
-        return;
     const projectRoot = ctx.cwd || process.cwd();
+    const resolution = resolveAmbientBrowserEngineResolution(projectRoot);
+    if (resolution.engine !== "gsd-browser" || resolution.source !== "env")
+        return;
     if (!detectWebApp(projectRoot))
         return;
     void warmUpManagedGsdBrowser(ctx).then((result) => {
-        if (!result.ok && ctx.hasUI) {
+        if (!ctx.hasUI)
+            return;
+        if (!result.ok) {
             ctx.ui.notify(`gsd-browser auto-init failed: ${result.error}. Browser UAT tools will retry on first use; run /gsd doctor if this persists.`, "warning");
         }
+        else if (result.coverageWarning) {
+            ctx.ui.notify(result.coverageWarning, "warning");
+        }
     });
 }
 async function closeActiveBrowserEngines() {
@@ -198,14 +255,14 @@ async function closeActiveBrowserEngines() {
 export default function (pi) {
     pi.on("session_start", async (_event, ctx) => {
         if (ctx.hasUI) {
-            void registerBrowserTools(pi)
+            void registerBrowserTools(pi, ctx)
                 .then(() => maybeWarmUpManagedEngine(pi, ctx))
                 .catch((error) => {
                 ctx.ui.notify(`browser-tools failed to load: ${error instanceof Error ? error.message : String(error)}`, "warning");
             });
             return;
         }
-        await registerBrowserTools(pi);
+        await registerBrowserTools(pi, ctx);
         maybeWarmUpManagedEngine(pi, ctx);
     });
     pi.on("session_shutdown", async () => {

package/dist/resources/extensions/claude-code-cli/models.js

@@ -37,6 +37,15 @@ export const CLAUDE_CODE_MODELS = [
         contextWindow: 1_000_000,
         maxTokens: 128_000,
     },
+    {
+        id: "claude-fable-5",
+        name: "Claude Fable 5 (via Claude Code)",
+        reasoning: true,
+        input: ["text", "image"],
+        cost: ZERO_COST,
+        contextWindow: 1_000_000,
+        maxTokens: 128_000,
+    },
     {
         id: "claude-sonnet-4-6",
         name: "Claude Sonnet 4.6 (via Claude Code)",

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

@@ -14,13 +14,20 @@ 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, } 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 { discoverBrowserMcpServerName, discoverMcpServers, discoverMcpServerNames, discoverWorkflowMcpServerName, computeMcpDisallowedTools, } from "../gsd/mcp-filter.js";
+import { markToolStart, markToolEnd } from "../gsd/auto.js";
+import { markInteractiveElicitationStart, markInteractiveElicitationEnd, } from "../gsd/auto-tool-tracking.js";
+import { discoverBrowserMcpServerName, discoverMcpServers, discoverMcpServerNames, discoverUserMcpServerNames, discoverWorkflowMcpServerName, computeMcpDisallowedTools, } from "../gsd/mcp-filter.js";
 import { RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES, RUN_UAT_FORBIDDEN_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES, resolveToolPresentationPlan } from "../gsd/tool-presentation-plan.js";
+import { getToolSurfaceReadinessError } from "../gsd/tool-surface-readiness.js";
+import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
 import { showInterviewRound } from "../shared/tui.js";
+export { buildFinalAssistantContent, extractToolResultsFromSdkUserMessage, handleClaudeCodePartialStreamEvent, mergePendingToolCalls, } from "./turn-assembler.js";
 export function serverToolUseToToolCallLike(block) {
     const argumentsValue = block.input && typeof block.input === "object" && !Array.isArray(block.input)
         ? block.input
@@ -1078,7 +1085,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 +1117,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 +1244,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 +1267,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 +1291,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,7 +1305,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;
     }
@@ -1341,14 +1417,22 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
     const projectBrowserServerName = discoverBrowserMcpServerName(projectRoot);
     const workflowServerName = projectWorkflowServerName ?? injectedWorkflowServerName;
     const browserServerName = projectBrowserServerName ?? injectedBrowserServerName;
-    // If a default GSD MCP server is already declared in the project's .mcp.json
-    // or .claude/settings.json, do not inject it again via mcpServers. Passing the
-    // same server name from two sources causes a duplicate registration conflict
-    // that prevents the MCP server from loading (tools become unavailable).
+    // Non-strict (non-phase) sessions load ~/.claude/settings.json via settingSources
+    // including "user". If the user declared the same server names there, injecting them
+    // again via mcpServers causes duplicate registration and leaves MCP tools unavailable.
+    // Strict (gsdPhase) sessions set settingSources=[] so user settings are not loaded.
+    const userDiscovered = !gsdPhase ? discoverUserMcpServerNames() : [];
+    const allDiscovered = discovered.length > 0 || userDiscovered.length > 0
+        ? [...discovered, ...userDiscovered]
+        : discovered;
+    // If a default GSD MCP server is already declared in project config or in the user's
+    // ~/.claude/settings.json (when that file will be loaded), do not inject it again via
+    // mcpServers. Passing the same server name from two sources causes a duplicate
+    // registration conflict that prevents the MCP server from loading (tools become unavailable).
     const workflowAlreadyInProject = projectWorkflowServerName !== undefined
-        || (injectedWorkflowServerName !== undefined && discovered.includes(injectedWorkflowServerName));
+        || (injectedWorkflowServerName !== undefined && allDiscovered.includes(injectedWorkflowServerName));
     const browserAlreadyInProject = projectBrowserServerName !== undefined
-        || (injectedBrowserServerName !== undefined && discovered.includes(injectedBrowserServerName));
+        || (injectedBrowserServerName !== undefined && allDiscovered.includes(injectedBrowserServerName));
     const mcpServersToInject = { ...defaultMcpServers.servers };
     if (workflowAlreadyInProject && injectedWorkflowServerName)
         delete mcpServersToInject[injectedWorkflowServerName];
@@ -1405,10 +1489,17 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
     const sdkMcpServers = inlinePhaseMcpServers ?? filteredMcpServers;
     const strictMcpConfig = !!inlinePhaseMcpServers;
     // Strict phase configs inline the exact MCP servers GSD needs. Loading
-    // project/local settings at the same time can duplicate those servers and
+    // Claude Code settings at the same time can duplicate those servers and
     // leave allowed mcp__... tools with no registered backing tool.
-    const settingSources = strictMcpConfig ? [] : ["project", "local"];
+    const settingSources = strictMcpConfig ? [] : ["user", "project", "local"];
     const exactWorkflowMcpTools = resolveExactWorkflowMcpToolsForPhase(gsdPhase, workflowServerName, workflowExplicitlyBlocked);
+    const questionToolSurface = resolveWorkflowQuestionToolSurface({
+        workflowServerName,
+        workflowExplicitlyBlocked,
+        workflowMcpTools,
+        exactWorkflowMcpTools,
+        env: process.env,
+    });
     const runUatDisallowedTools = gsdPhase === "run-uat" && workflowServerName
         ? [
             ...RUN_UAT_FORBIDDEN_TOOL_NAMES.filter((toolName) => !toolName.startsWith("mcp__")),
@@ -1422,6 +1513,7 @@ export function buildSdkOptions(modelId, prompt, overrides, extraOptions = {}) {
     const disallowedTools = [...new Set([
             "ToolSearch",
             ...(workflowMcpTools.length > 0 || exactWorkflowMcpTools.length > 0 ? ["AskUserQuestion"] : []),
+            ...questionToolSurface.disallowedTools,
             ...runUatDisallowedTools,
             ...extraDisallowedTools,
         ])];
@@ -1478,234 +1570,14 @@ 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
 // ---------------------------------------------------------------------------
@@ -1765,8 +1637,9 @@ async function pumpSdkMessages(model, context, options, stream) {
                 }
                 : {}),
         });
+        const workflowMcpServerName = workflowMcpServerNameFromAllowedTools(sdkOpts.allowedTools);
         const prompt = buildPromptFromContext(context, {
-            workflowMcpServerName: workflowMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
+            workflowMcpServerName,
             browserMcpServerName: browserMcpServerNameFromAllowedTools(sdkOpts.allowedTools),
         });
         const queryPrompt = buildSdkQueryPrompt(context, prompt);
@@ -1804,7 +1677,30 @@ async function pumpSdkMessages(model, context, options, stream) {
             switch (msg.type) {
                 // -- Init --
                 case "system": {
-                    // Nothing to emit — the stream is already started.
+                    // Tool Surface Readiness gate: the init message is the first (and
+                    // only) point where the session reports its live tool surface and
+                    // MCP server statuses. If the workflow server failed or has not
+                    // registered this Unit's required tools, abort before the first
+                    // model turn with a transient, recovery-classifiable error
+                    // (tool-unavailable → retry) instead of letting the model hit
+                    // "No such tool available" mid-Unit and improvise around it.
+                    const init = msg;
+                    if (init.subtype === "init") {
+                        const readinessError = getToolSurfaceReadinessError({
+                            unitType: gsdPhase,
+                            workflowServerName: workflowMcpServerName,
+                            observation: { tools: init.tools ?? [], mcpServers: init.mcp_servers ?? [] },
+                        });
+                        if (readinessError) {
+                            controller.abort();
+                            stream.push({
+                                type: "error",
+                                reason: "error",
+                                error: makeErrorMessage(modelId, readinessError),
+                            });
+                            return;
+                        }
+                    }
                     break;
                 }
                 // -- Streaming partial messages --