fix(mcp): surface tool-level isError and structuredContent

Author: TheGreatAxios

src/mcp/client-envelope.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { defined } from "../../tests/helpers/defined.js";
 import { withMockedModule } from "../../tests/helpers/mock-module.js";
 import { connectMCPServer } from "./client.js";
 
@@ -25,14 +26,6 @@ await withMockedModule(
   }),
 );
 
-await withMockedModule(
-  import.meta.resolve("@modelcontextprotocol/sdk/client/stdio.js"),
-  (real: typeof import("@modelcontextprotocol/sdk/client/stdio.js")) => ({
-    ...real,
-    StdioClientTransport: class {},
-  }),
-);
-
 describe("mcp client tool envelope", () => {
   test("callResult preserves isError and structuredContent from the SDK", async () => {
     scriptedCallToolResult = {
@@ -45,11 +38,10 @@ describe("mcp client tool envelope", () => {
       {},
     );
     if (!connected.ok) throw new Error("expected stdio connect to succeed");
-    const envelope = await connected.client.callResult(
-      "do_thing",
-      {},
-      new AbortController().signal,
-    );
+    const envelope = await defined(
+      connected.client.callResult,
+      "mcp client callResult",
+    )("do_thing", {}, new AbortController().signal);
 
     expect(envelope.isError).toBe(true);
     expect(envelope.blocks).toEqual([

src/mcp/client.ts

@@ -27,6 +27,23 @@ export interface MCPContentBlock {
   [key: string]: unknown;
 }
 
+/**
+ * Scope lock (CL-8992): the pinned @modelcontextprotocol/sdk v1 CallToolResult
+ * is `{ content: blocks[] (default []), structuredContent?: Record<string,
+ * unknown>, isError?: boolean }` — a tool-level failure still succeeds at the
+ * protocol layer. The envelope carries all three so the plugin can surface
+ * failures as errors and structured-only payloads as readable text.
+ * `structuredContent` reaches the model JSON-serialized into the content
+ * string under MCP_STRUCTURED_CONTENT_MARKER (see plugin.ts) with the raw
+ * (policy-scrubbed) record preserved under ToolResult `detail` and in the
+ * evidence archive — never raw.
+ */
+export interface MCPToolResultEnvelope {
+  blocks: MCPContentBlock[];
+  isError: boolean;
+  structuredContent?: Record<string, unknown>;
+}
+
 export interface MCPClient {
   serverName: string;
   tools: MCPTool[];
@@ -41,6 +58,12 @@ export interface MCPClient {
     args: Record<string, unknown>,
     signal: AbortSignal,
   ): Promise<MCPContentBlock[]>;
+  /** Full tool-result envelope: blocks plus tool-level isError/structuredContent. */
+  callResult?(
+    toolName: string,
+    args: Record<string, unknown>,
+    signal: AbortSignal,
+  ): Promise<MCPToolResultEnvelope>;
   close(): Promise<void>;
 }
 
@@ -566,6 +589,29 @@ async function finishClient(
   return {
     serverName,
     tools,
+    async callResult(toolName, args, signal) {
+      const context =
+        authContext === undefined ? undefined : { ...authContext, signal };
+      const result = await withHTTPAuthorizationRecovery(context, () =>
+        client.callTool({ name: toolName, arguments: args }, undefined, {
+          signal,
+        }),
+      );
+      const envelope: MCPToolResultEnvelope = {
+        blocks: validateMcpContentBlocks(result.content),
+        isError: result.isError === true,
+      };
+      if (
+        result.structuredContent !== null &&
+        typeof result.structuredContent === "object"
+      ) {
+        envelope.structuredContent = result.structuredContent as Record<
+          string,
+          unknown
+        >;
+      }
+      return envelope;
+    },
     async callBlocks(toolName, args, signal) {
       const context =
         authContext === undefined ? undefined : { ...authContext, signal };

src/mcp/plugin.ts

@@ -11,13 +11,24 @@ import {
   type SpillBlobWriter,
 } from "../plugins/result-truncation-plugin.js";
 import type { CompactionArchive } from "../session/compaction-archive.js";
-import type { MCPClient, MCPContentBlock } from "./client.js";
+import type {
+  MCPClient,
+  MCPContentBlock,
+  MCPToolResultEnvelope,
+} from "./client.js";
 import { mcpToolName } from "./tool-name.js";
 import { unwrapToolContent } from "./client.js";
 
 export const MCP_RECONNECTING_TOOL_ERROR =
   "MCP server is reconnecting; retry the call once it reports connected.";
 
+/**
+ * Stable marker prefixing JSON-serialized `structuredContent` when it is the
+ * only payload (or supplements an empty flatten). Lets the model — and log
+ * grep — distinguish server-structured data from free text.
+ */
+export const MCP_STRUCTURED_CONTENT_MARKER = "mcp structured result:";
+
 /** True while the server keeps its tools mounted but cannot execute. */
 export function isDegradedMcpState(state: { state: string }): boolean {
   return state.state === "reconnecting";
@@ -90,22 +101,51 @@ export function mcpClientTools(
         signal: AbortSignal,
       ): Promise<ToolResult> => {
         try {
-          const rawBlocks =
-            typeof client.callBlocks === "function"
-              ? await client.callBlocks(tool.name, call.arguments, signal)
-              : [
-                  {
-                    type: "text",
-                    text: await client.call(tool.name, call.arguments, signal),
-                  } satisfies MCPContentBlock,
-                ];
-          const authorizedBlocks = applyPolicyToBlocks(rawBlocks);
+          const envelope: MCPToolResultEnvelope =
+            typeof client.callResult === "function"
+              ? await client.callResult(tool.name, call.arguments, signal)
+              : typeof client.callBlocks === "function"
+                ? {
+                    blocks: await client.callBlocks(
+                      tool.name,
+                      call.arguments,
+                      signal,
+                    ),
+                    isError: false,
+                  }
+                : {
+                    blocks: [
+                      {
+                        type: "text",
+                        text: await client.call(
+                          tool.name,
+                          call.arguments,
+                          signal,
+                        ),
+                      } satisfies MCPContentBlock,
+                    ],
+                    isError: false,
+                  };
+          const authorizedBlocks = applyPolicyToBlocks(envelope.blocks);
+          const scrubbedStructured =
+            envelope.structuredContent === undefined
+              ? undefined
+              : (scrubSecretShapedValue(envelope.structuredContent) as Record<
+                  string,
+                  unknown
+                >);
           const archive = getEvidenceArchive?.();
           if (archive !== undefined) {
             try {
               await archive.recordAuthorizedPayload({
                 kind: "tool_result",
-                payload: { blocks: authorizedBlocks },
+                payload:
+                  scrubbedStructured === undefined
+                    ? { blocks: authorizedBlocks }
+                    : {
+                        blocks: authorizedBlocks,
+                        structuredContent: scrubbedStructured,
+                      },
                 callId: call.id,
                 provenance: "mcp:post-policy-pre-flatten",
               });
@@ -114,6 +154,15 @@ export function mcpClientTools(
             }
           }
           const flattened = unwrapToolContent(authorizedBlocks);
+          const isError = envelope.isError === true;
+          const baseContent =
+            flattened !== ""
+              ? flattened
+              : scrubbedStructured !== undefined
+                ? `${MCP_STRUCTURED_CONTENT_MARKER}\n${JSON.stringify(scrubbedStructured)}`
+                : isError
+                  ? `MCP tool ${client.serverName}/${tool.name} reported an error with empty content.`
+                  : flattened;
           const writeBlob = getBlobWriter?.();
           const contextDir = getContextDir?.();
           const spill =
@@ -124,8 +173,15 @@ export function mcpClientTools(
                   ...(contextDir !== undefined ? { contextDir } : {}),
                 }
               : undefined;
-          const content = await sanitizeMcpResultContent(flattened, spill);
-          return { callId: call.id, content };
+          const content = await sanitizeMcpResultContent(baseContent, spill);
+          return {
+            callId: call.id,
+            content,
+            ...(isError ? { isError: true as const } : {}),
+            ...(scrubbedStructured !== undefined
+              ? { detail: scrubbedStructured }
+              : {}),
+          };
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
           const scrubbed = scrubSecretShapedContent(message);

src/session/hooks.ts

@@ -501,6 +501,7 @@ function truncateToolResultForHookPayload(result: ToolResult): ToolResult {
     callId: result.callId,
     content,
     ...(result.isError !== undefined ? { isError: result.isError } : {}),
+    ...(result.detail !== undefined ? { detail: result.detail } : {}),
     ...(result.pendingMarker !== undefined
       ? { pendingMarker: result.pendingMarker }
       : {}),