@bitkyc08/opencodex 2.63.0 → 2.64.0

package/src/adapters/coding-agent/protocol.ts

@@ -138,25 +138,72 @@ function asString(value: unknown): string | undefined {
   return typeof value === "string" ? value : undefined;
 }
 
-/** Extract OpenCodex usage from a `result` frame's Anthropic-shaped usage object. */
-export function usageFromResult(message: StreamMessage): OcxUsage | undefined {
-  const usage = asRecord(message.usage);
-  if (!usage) return undefined;
+/** Extract OpenCodex usage from the Anthropic-shaped usage record shared by frames and deltas. */
+function usageFromAnthropicShape(usage: Record<string, unknown>): OcxUsage | undefined {
   const inputTokens = typeof usage.input_tokens === "number" ? usage.input_tokens : 0;
   const outputTokens = typeof usage.output_tokens === "number" ? usage.output_tokens : 0;
   const cachedInputTokens = typeof usage.cache_read_input_tokens === "number" ? usage.cache_read_input_tokens : undefined;
   const cacheCreationInputTokens =
     typeof usage.cache_creation_input_tokens === "number" ? usage.cache_creation_input_tokens : undefined;
-  if (inputTokens === 0 && outputTokens === 0 && cachedInputTokens === undefined) return undefined;
+  // A snapshot is zero-only when every counter is absent or zero. Testing only the cache-read
+  // field dropped a cache-creation-only snapshot (input/output 0 with, say, 200 cache-creation
+  // tokens), and a capture-only tool leg terminated at message_stop never sees a result frame
+  // that could carry those tokens instead, so the turn under-reported usage and cost.
+  const cacheReadTotal = cachedInputTokens ?? 0;
+  const cacheCreationTotal = cacheCreationInputTokens ?? 0;
+  if (inputTokens === 0 && outputTokens === 0 && cacheReadTotal === 0 && cacheCreationTotal === 0) {
+    return undefined;
+  }
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens: inputTokens + outputTokens,
+    ...(cacheReadTotal > 0 ? { cachedInputTokens: cacheReadTotal, cacheReadInputTokens: cacheReadTotal } : {}),
+    ...(cacheCreationTotal > 0 ? { cacheCreationInputTokens: cacheCreationTotal } : {}),
+  };
+}
+
+/** Extract OpenCodex usage from a `result` frame's Anthropic-shaped usage object. */
+export function usageFromResult(message: StreamMessage): OcxUsage | undefined {
+  const usage = asRecord(message.usage);
+  return usage ? usageFromAnthropicShape(usage) : undefined;
+}
+
+/**
+ * Fold a pre-result usage snapshot into the running partial usage.
+ *
+ * `message_delta` and assistant-frame snapshots are cumulative per message, but a later snapshot
+ * can repeat or extend an earlier one, so each field keeps its maximum. The `result` frame stays
+ * authoritative for a text-only turn; partial state exists so a capture-only tool-bridge turn —
+ * which is terminated at `message_stop` before any result frame can arrive — still reports real
+ * token usage instead of zero.
+ */
+function mergePartialUsage(previous: OcxUsage | undefined, next: OcxUsage): OcxUsage {
+  if (!previous) return next;
+  const inputTokens = Math.max(previous.inputTokens, next.inputTokens);
+  const outputTokens = Math.max(previous.outputTokens, next.outputTokens);
+  const cacheRead = Math.max(
+    previous.cacheReadInputTokens ?? previous.cachedInputTokens ?? 0,
+    next.cacheReadInputTokens ?? next.cachedInputTokens ?? 0,
+  );
+  const cacheCreation = Math.max(previous.cacheCreationInputTokens ?? 0, next.cacheCreationInputTokens ?? 0);
   return {
     inputTokens,
     outputTokens,
     totalTokens: inputTokens + outputTokens,
-    ...(cachedInputTokens !== undefined ? { cachedInputTokens, cacheReadInputTokens: cachedInputTokens } : {}),
-    ...(cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens } : {}),
+    ...(cacheRead > 0 ? { cachedInputTokens: cacheRead, cacheReadInputTokens: cacheRead } : {}),
+    ...(cacheCreation > 0 ? { cacheCreationInputTokens: cacheCreation } : {}),
   };
 }
 
+/** Record one usage snapshot; absent, malformed, or zero-only snapshots leave state untouched. */
+function observePartialUsage(state: StreamParseState, value: unknown): void {
+  const usage = asRecord(value);
+  if (!usage) return;
+  const next = usageFromAnthropicShape(usage);
+  if (next) state.partialUsage = mergePartialUsage(state.partialUsage, next);
+}
+
 /**
  * Mutable per-turn parse state shared across frames of one stream (§十二).
  * Thinking and text states are strictly decoupled.
@@ -166,6 +213,16 @@ export interface StreamParseState {
   sawPartialThinking: boolean;
   sawTerminalResult: boolean;
   openToolCallId?: string;
+  /** A `message_stop` stream event arrived: the assistant message is complete. */
+  sawMessageStop?: boolean;
+  /** Completed tool_use content blocks observed in this stream. */
+  completedToolCalls?: number;
+  /** Tool IDs already captured through partial events, for complete-assistant deduplication. */
+  partialToolCallIds?: Set<string>;
+  /** A complete assistant tool block had no matching partial capture. */
+  uncapturedToolUse?: boolean;
+  /** Highest-seen usage snapshot from `message_delta`/assistant frames before a terminal result. */
+  partialUsage?: OcxUsage;
 }
 
 /**
@@ -188,7 +245,8 @@ export function mapStreamMessageToEvents(message: StreamMessage, state: StreamPa
   if (type === "assistant") {
     // Fallback path: a complete assistant message. Surface text and thinking independently
     // only when the partial delta stream did not already carry them (§十二).
-    const content = asRecord(message.message)?.content;
+    const messageRecord = asRecord(message.message);
+    const content = messageRecord?.content;
     if (Array.isArray(content)) {
       for (const block of content) {
         const part = asRecord(block);
@@ -200,9 +258,13 @@ export function mapStreamMessageToEvents(message: StreamMessage, state: StreamPa
         } else if (blockType === "thinking" && !state.sawPartialThinking) {
           const thinking = asString(part.thinking);
           if (thinking) events.push({ type: "thinking_delta", thinking });
+        } else if (blockType === "tool_use") {
+          const id = asString(part.id);
+          if (!id || !state.partialToolCallIds?.has(id)) state.uncapturedToolUse = true;
         }
       }
     }
+    observePartialUsage(state, messageRecord?.usage);
     return events;
   }
 
@@ -281,8 +343,9 @@ function mapRawStreamEvent(event: StreamMessage, state: StreamParseState): Adapt
         events.push({ type: "thinking_delta", thinking });
       }
     } else if (deltaType === "input_json_delta") {
-      // Tool-input streaming. Inert while tools are disabled (Codex's catalog is not advertised),
-      // but parsed so the seam is ready and an unexpected frame never crashes.
+      // Tool-input streaming. Live for capture-only bridge turns, where the advertised MCP
+      // catalog makes the CLI emit real tool_use blocks; parsed unconditionally so a stray
+      // frame on a tools-disabled turn is ignored rather than crashing.
       const partial = asString(delta?.partial_json);
       if (partial && state.openToolCallId) events.push({ type: "tool_call_delta", arguments: partial });
     }
@@ -296,6 +359,7 @@ function mapRawStreamEvent(event: StreamMessage, state: StreamParseState): Adapt
       const name = asString(block?.name) ?? "tool";
       if (id) {
         state.openToolCallId = id;
+        state.partialToolCallIds?.add(id);
         events.push({ type: "tool_call_start", id, name });
       }
     }
@@ -305,14 +369,63 @@ function mapRawStreamEvent(event: StreamMessage, state: StreamParseState): Adapt
   if (eventType === "content_block_stop") {
     if (state.openToolCallId) {
       state.openToolCallId = undefined;
+      state.completedToolCalls = (state.completedToolCalls ?? 0) + 1;
       events.push({ type: "tool_call_end" });
     }
     return events;
   }
 
+  if (eventType === "message_stop") {
+    state.sawMessageStop = true;
+    return events;
+  }
+
+  if (eventType === "message_start") {
+    // Anthropic-shaped streams report input tokens on `message_start.message.usage` and output
+    // tokens later on `message_delta.usage`. A capture-only tool leg is terminated at
+    // `message_stop`, so without this branch the synthesized done(tool_use) undercounts input
+    // tokens whenever the CLI puts them here (and `message_stop` arrives before any assistant
+    // fallback frame that would otherwise carry them).
+    const messageRecord = asRecord(event.message);
+    observePartialUsage(state, messageRecord?.usage);
+    return events;
+  }
+
+  if (eventType === "message_delta") {
+    // Pre-result usage snapshots: a capture-only tool-bridge turn ends at message_stop with no
+    // result frame, so these snapshots are the only token accounting that leg will ever see.
+    observePartialUsage(state, event.usage);
+    return events;
+  }
+
   return events;
 }
 
+/**
+ * Validate a `system/init` frame against an active capture-only tool bridge.
+ *
+ * With the bridge armed, the CLI must report exactly the bridge's MCP server as connected: a
+ * missing or failed server means the model never saw the advertised catalog, so the turn fails
+ * closed instead of silently degrading to a text-only answer.
+ */
+export function toolBridgeInitError(message: StreamMessage, serverName: string): string | undefined {
+  if (message.type !== "system" || message.subtype !== "init") return undefined;
+  const servers = message.mcp_servers;
+  if (!Array.isArray(servers) || servers.length !== 1) {
+    return "Coding-agent system/init reported an unexpected MCP server set for the tool bridge.";
+  }
+  const server = servers[0];
+  if (
+    !server
+    || typeof server !== "object"
+    || server.name !== serverName
+    || server.status !== "connected"
+  ) {
+    return `Coding-agent system/init did not report the ${serverName} MCP server as connected.`;
+  }
+  return undefined;
+}
+
 /** One content part on the stream-json input wire (Anthropic message shape). */
 type WireContentPart = Record<string, unknown>;
 

package/src/adapters/coding-agent/turn.ts

@@ -1,9 +1,21 @@
 import { execFileSync, spawn as nodeSpawn, type ChildProcess, type SpawnOptions } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig } from "../../types";
 import { commandInvocation } from "../../lib/win-exec";
+import { isStandaloneBinary } from "../../lib/standalone";
 import { modelRecordValue } from "../../reasoning-effort";
 import type { IncomingMeta } from "../base";
-import { buildConversationInput, CodingAgentProtocolError, mapStreamMessageToEvents, projectedHistoryCharLimit, readJsonLines, type StreamParseState } from "./protocol";
+import {
+  buildConversationInput,
+  CodingAgentProtocolError,
+  mapStreamMessageToEvents,
+  projectedHistoryCharLimit,
+  readJsonLines,
+  toolBridgeInitError,
+  type StreamParseState,
+} from "./protocol";
 import { resolveCodingAgentBinary, resolveProfileByBaseUrl, type CodingAgentProviderProfile, type WhichFn } from "./profile";
 
 /** Injectable spawn for tests; production uses node:child_process. */
@@ -26,6 +38,8 @@ export interface CodingAgentDeps {
   platform?: NodeJS.Platform;
   /** Test seam for terminating a Windows CLI and all descendants. */
   killWindowsProcessTree?: KillWindowsProcessTreeFn;
+  /** Test seam for a catalog/config write failure after private bridge-directory creation. */
+  writeToolBridgeFile?: typeof writeFile;
 }
 
 const DEFAULT_TIMEOUT_MS = 300_000;
@@ -88,9 +102,41 @@ export interface CodingAgentTurnInput {
   buildArgs: (profile: CodingAgentProviderProfile, parsed: OcxParsedRequest, provider: OcxProviderConfig) => string[];
   /** Family-specific scoped env builder (credential + region switch on top of baseScopedEnv). */
   buildEnv: (profile: CodingAgentProviderProfile, apiKey: string) => Record<string, string>;
+  /**
+   * Opt-in capture-only tool bridge. When present with a non-empty catalog, the turn writes a
+   * validated catalog plus an MCP config to a private temp dir, passes `--mcp-config` (with exact
+   * `--allowedTools`) alongside the family's tools-disabled args, translates captured tool_use
+   * names back to request wire names, and terminates the process tree at `message_stop` because
+   * the capture-only MCP handler intentionally never answers. Execution stays with the client.
+   */
+  toolBridge?: CodingAgentToolBridgeInput;
   deps: CodingAgentDeps;
 }
 
+/** Opt-in capture-only tool bridge for one coding-agent CLI turn. */
+export interface CodingAgentToolBridgeInput {
+  /** MCP server name advertised to the CLI; tool_use blocks render it as `mcp__<name>__<tool>`. */
+  serverName: string;
+  /** Absolute path of the capture-only MCP server module, run with the serving runtime. */
+  serverModulePath: string;
+  /** Validated tool catalog advertised over ListTools; the server never executes a call. */
+  tools: ReadonlyArray<{ name: string; description: string; inputSchema: Record<string, unknown> }>;
+  /** CLI-emitted tool name (`mcp__<server>__<tool>`) to the request's wire tool name. */
+  emittedNameMap: Map<string, string>;
+  /** Captured tool_use blocks accepted in one assistant message. */
+  maxTurnToolCalls: number;
+  /**
+   * The request's `tool_choice` requires a tool call (`required`, or a named selection).
+   * The nested CLI has no documented force-tool flag, so this is enforced locally: a
+   * terminal text result on a required turn fails closed instead of silently succeeding.
+   */
+  requireToolCall?: boolean;
+}
+
+export function codeBuddyMcpInvocation(serverModulePath: string, catalogPath: string, standalone = isStandaloneBinary()): string[] {
+  return standalone ? ["__codebuddy-mcp", catalogPath] : [serverModulePath, catalogPath];
+}
+
 /**
  * Run one headless coding-agent CLI turn as an OpenCodex `runTurn` (§七/§三十).
  *
@@ -153,7 +199,62 @@ export async function runCodingAgentTurn(input: CodingAgentTurnInput): Promise<v
     return;
   }
 
+  const toolBridge = input.toolBridge;
+  const writeToolBridgeFile = deps.writeToolBridgeFile ?? writeFile;
+  let toolBridgeDir: string | undefined;
+  let toolBridgeMcpConfigPath: string | undefined;
+  if (toolBridge) {
+    if (toolBridge.tools.length === 0 || toolBridge.emittedNameMap.size === 0) {
+      emit({
+        type: "error",
+        message: "Coding-agent tool bridge was supplied without any isolated tools.",
+        status: 500,
+        errorType: "server_error",
+        code: "tool_bridge_empty",
+        retryable: false,
+      });
+      return;
+    }
+    try {
+      toolBridgeDir = await mkdtemp(join(tmpdir(), "ocx-coding-agent-tools-"));
+      const catalogPath = join(toolBridgeDir, "catalog.json");
+      toolBridgeMcpConfigPath = join(toolBridgeDir, "mcp.json");
+      await writeToolBridgeFile(catalogPath, JSON.stringify(toolBridge.tools), { encoding: "utf8", mode: 0o600, flag: "wx" });
+      await writeToolBridgeFile(
+        toolBridgeMcpConfigPath,
+        JSON.stringify({
+          mcpServers: {
+            [toolBridge.serverName]: {
+              type: "stdio",
+              command: process.execPath,
+              args: codeBuddyMcpInvocation(toolBridge.serverModulePath, catalogPath),
+              defer_loading: false,
+              alwaysLoad: true,
+            },
+          },
+        }),
+        { encoding: "utf8", mode: 0o600, flag: "wx" },
+      );
+    } catch {
+      emit({
+        type: "error",
+        message: "Coding-agent tool bridge could not be staged securely.",
+        status: 500,
+        errorType: "server_error",
+        code: "tool_bridge_setup_failed",
+        retryable: false,
+      });
+      if (toolBridgeDir) await rm(toolBridgeDir, { recursive: true, force: true }).catch(() => undefined);
+      return;
+    }
+  }
+
   const args = buildArgs(profile, parsed, provider);
+  if (toolBridge && toolBridgeMcpConfigPath) {
+    // Exact names close the wildcard domain; --strict-mcp-config (family args) keeps user
+    // servers out, so the capture server is the only capability this turn can reach.
+    args.push("--allowedTools", [...toolBridge.emittedNameMap.keys()].join(","), "--mcp-config", toolBridgeMcpConfigPath);
+  }
   const env = buildEnv(profile, apiKey);
   const invocation = commandInvocation(binary, args, platform, { env });
 
@@ -174,6 +275,9 @@ export async function runCodingAgentTurn(input: CodingAgentTurnInput): Promise<v
       code: "cli_spawn_failed",
       retryable: false,
     });
+    // A synchronous spawn() throw skips the event-loop `finally` below, so the private
+    // bridge dir would leak unless it is removed here as well.
+    if (toolBridgeDir) await rm(toolBridgeDir, { recursive: true, force: true }).catch(() => undefined);
     return;
   }
 
@@ -218,6 +322,9 @@ export async function runCodingAgentTurn(input: CodingAgentTurnInput): Promise<v
         return;
       } catch { /* fall back to terminating the direct child */ }
     }
+    // The capture-only MCP server is the CLI's child. Its stdin closes when the CLI dies, and
+    // mcp-server.ts exits on stdin EOF, so this ladder reaps the whole tree without knowing
+    // the grandchild pid.
     try { child.kill("SIGTERM"); } catch { /* already gone */ }
     killTimer = setTimeout(() => {
       try { child.kill("SIGKILL"); } catch { /* already gone */ }
@@ -253,11 +360,18 @@ export async function runCodingAgentTurn(input: CodingAgentTurnInput): Promise<v
 
   let streamProtocolError: string | undefined;
   let turnError: string | undefined;
+  // A successful result frame that arrived after every captured tool call completed but
+  // before message_stop. The bridge contract still ends the leg with the synthesized
+  // done(tool_use) at message_stop, so the result-derived done(stop) is deferred and its
+  // usage (authoritative vendor accounting) is folded into the synthesis. Set inside the
+  // stream loop; read by the synthesis and the stream-end error selection below.
+  let deferredResultDone: Extract<AdapterEvent, { type: "done" }> | undefined;
   const state: StreamParseState = {
     sawPartialText: false,
     sawPartialThinking: false,
     sawTerminalResult: false,
     openToolCallId: undefined,
+    partialToolCallIds: toolBridge ? new Set<string>() : undefined,
   };
 
   try {
@@ -278,13 +392,209 @@ export async function runCodingAgentTurn(input: CodingAgentTurnInput): Promise<v
     const stdout = child.stdout;
     if (!stdout) throw new CodingAgentProtocolError(`${profile.label} CLI produced no stdout stream`);
     try {
+      let initValidated = false;
+      let toolCallStarts = 0;
+      let failClosed = false;
       for await (const message of readJsonLines(stdout)) {
         if (incoming.abortSignal?.aborted) break;
-        for (const event of mapStreamMessageToEvents(message, state)) {
+        if (toolBridge) {
+          const initError = toolBridgeInitError(message, toolBridge.serverName);
+          if (initError) {
+            emitOnce({
+              type: "error",
+              message: initError,
+              status: 502,
+              errorType: "upstream_error",
+              code: "tool_bridge_init_mismatch",
+              retryable: false,
+            });
+            kill();
+            break;
+          }
+          if (message.type === "system" && message.subtype === "init") initValidated = true;
+        }
+        const mappedEvents = mapStreamMessageToEvents(message, state);
+        if (toolBridge && state.uncapturedToolUse) {
+          emitOnce({
+            type: "error",
+            message: "Coding-agent CLI returned a tool call without a partial tool capture.",
+            status: 502,
+            errorType: "upstream_error",
+            code: "protocol_error",
+            retryable: false,
+          });
+          kill();
+          break;
+        }
+        for (const event of mappedEvents) {
+          if (toolBridge && !initValidated && event.type === "done") {
+            emitOnce({
+              type: "error",
+              message: "Coding-agent CLI ended before the tool bridge init handshake completed.",
+              status: 502,
+              errorType: "upstream_error",
+              code: "tool_bridge_init_missing",
+              retryable: false,
+            });
+            failClosed = true;
+            kill();
+            break;
+          }
+          if (toolBridge && event.type === "tool_call_start") {
+            // The catalog is only advertised once the CLI has acknowledged the bridge server in
+            // its init handshake. A tool call that arrives before that acknowledgement means the
+            // model acted on a catalog this bridge never validated, so fail closed before the
+            // call is counted or renamed. Checking at arrival matters: a later init frame used to
+            // set initValidated and let an early call finish as a successful done(tool_use).
+            if (!initValidated) {
+              emitOnce({
+                type: "error",
+                message: "Coding-agent CLI called a tool before the tool bridge init handshake completed.",
+                status: 502,
+                errorType: "upstream_error",
+                code: "tool_bridge_init_missing",
+                retryable: false,
+              });
+              failClosed = true;
+              kill();
+              break;
+            }
+            toolCallStarts += 1;
+            if (toolCallStarts > toolBridge.maxTurnToolCalls) {
+              emitOnce({
+                type: "error",
+                message: `Coding-agent CLI returned more than the ${toolBridge.maxTurnToolCalls}-tool-call turn limit.`,
+                status: 502,
+                errorType: "upstream_error",
+                code: "tool_call_limit",
+                retryable: false,
+              });
+              failClosed = true;
+              kill();
+              break;
+            }
+            const wireName = toolBridge.emittedNameMap.get(event.name);
+            if (wireName === undefined) {
+              emitOnce({
+                type: "error",
+                message: "Coding-agent CLI called a tool outside the isolated catalog.",
+                status: 502,
+                errorType: "upstream_error",
+                code: "undeclared_tool_call",
+                retryable: false,
+              });
+              failClosed = true;
+              kill();
+              break;
+            }
+            emitOnce({ ...event, name: wireName });
+            continue;
+          }
+          if (
+            toolBridge?.requireToolCall === true
+            && !terminalEmitted
+            && event.type === "done"
+            && event.stopReason !== "tool_use"
+            && (state.completedToolCalls ?? 0) === 0
+          ) {
+            // `tool_choice: required|named` on a bridge turn: a text-only terminal result must not
+            // become a successful completion the client can accept. The capture-only bridge has no
+            // way to force the nested CLI, so fail closed with the same stable error shape the
+            // other bridge contract violations use.
+            emitOnce({
+              type: "error",
+              message: "CodeBuddy finished without calling the required tool.",
+              status: 502,
+              errorType: "upstream_error",
+              code: "tool_call_required",
+              retryable: false,
+            });
+            failClosed = true;
+            kill();
+            break;
+          }
+          if (
+            toolBridge
+            && !terminalEmitted
+            && event.type === "done"
+            && toolCallStarts > 0
+            && (state.completedToolCalls ?? 0) !== toolCallStarts
+          ) {
+            // A terminal result that arrives while a captured tool call is still open must not
+            // become a successful completion the client can accept. The message_stop check after
+            // the event loop cannot cover this path: the CLI normally parks on the
+            // never-answering capture server, but a stream that delivers the result frame
+            // without (or before) message_stop emits done here, and started-but-unfinished
+            // calls slipped through as successful turns.
+            emitOnce({
+              type: "error",
+              message: "Coding-agent CLI ended with an incomplete tool call.",
+              status: 502,
+              errorType: "upstream_error",
+              code: "protocol_error",
+              retryable: false,
+            });
+            failClosed = true;
+            kill();
+            break;
+          }
+          if (
+            toolBridge
+            && !terminalEmitted
+            && event.type === "done"
+            && toolCallStarts > 0
+            && (state.completedToolCalls ?? 0) === toolCallStarts
+          ) {
+            // Every captured call completed and the CLI settled with a successful result before
+            // message_stop (instead of parking on the never-answering capture server). Emitting
+            // this done(stop) now would end the turn as a text completion and skip the
+            // synthesized done(tool_use) the client contract expects. Defer it: message_stop
+            // synthesis emits the terminal event with this frame's usage, and a stream that
+            // ends without message_stop fails closed with protocol_error below.
+            deferredResultDone = event;
+            continue;
+          }
           emitOnce(event.type === "error"
             ? { ...event, message: redactSecrets(event.message, profile.tokenEnv, apiKey) }
             : event);
         }
+        if (failClosed) break;
+        if (
+          toolBridge
+          && !terminalEmitted
+          && state.sawMessageStop
+          && toolCallStarts > 0
+          && (state.completedToolCalls ?? 0) !== toolCallStarts
+        ) {
+          emitOnce({
+            type: "error",
+            message: "Coding-agent CLI ended with an incomplete tool call.",
+            status: 502,
+            errorType: "upstream_error",
+            code: "protocol_error",
+            retryable: false,
+          });
+          kill();
+          break;
+        }
+        if (toolBridge && !terminalEmitted && state.sawMessageStop && (state.completedToolCalls ?? 0) > 0) {
+          // No init re-check here: a completed call implies a tool_call_start was mapped, and the
+          // arrival-time gate above already refuses any start that lands before the handshake.
+          // The capture-only MCP handler never answers, so the CLI parks after message_stop.
+          // The completed tool_use blocks are this turn's structured output: end the leg here
+          // and terminate the tree; the client executes, and the next request continues.
+          // Pre-result usage snapshots keep this terminated leg accountable: no result frame
+          // ever arrives for a turn parked on the never-answering capture server.
+          const terminalUsage = deferredResultDone?.usage ?? state.partialUsage;
+          emitOnce({
+            type: "done",
+            stopReason: "tool_use",
+            endTurn: false,
+            ...(terminalUsage ? { usage: terminalUsage } : {}),
+          });
+          kill();
+          break;
+        }
         if (terminalEmitted) break;
       }
     } catch (err) {
@@ -296,6 +606,9 @@ export async function runCodingAgentTurn(input: CodingAgentTurnInput): Promise<v
     turnError = err instanceof Error ? err.message : String(err);
   } finally {
     cleanup();
+    if (toolBridgeDir) {
+      await rm(toolBridgeDir, { recursive: true, force: true }).catch(() => undefined);
+    }
   }
 
   // Reap the process so no zombie is left behind (§三十): wait for the real `close`, and
@@ -353,6 +666,15 @@ export async function runCodingAgentTurn(input: CodingAgentTurnInput): Promise<v
         code: "process_exit_error",
         retryable: false,
       });
+    } else if (toolBridge && deferredResultDone !== undefined && !state.sawMessageStop) {
+      emitOnce({
+        type: "error",
+        message: `${profile.label} CLI delivered a terminal result before message_stop on a tool-bridge turn.`,
+        status: 502,
+        errorType: "upstream_error",
+        code: "protocol_error",
+        retryable: false,
+      });
     } else if (!state.sawTerminalResult) {
       const msg = stderr
         ? `${profile.label} CLI ended without a terminal result frame: ${stderr}`