Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

fix(adapters): expand parallel tool_uses wrapper into tool_use blocks

Jack Rudenko954e2a835d78
diff --git a/packages/cli/src/handlers/composed-handler.ts b/packages/cli/src/handlers/composed-handler.ts
index 520215b4..f6b0cf28 100644
--- a/packages/cli/src/handlers/composed-handler.ts
+++ b/packages/cli/src/handlers/composed-handler.ts
@@ -2572,6 +2572,13 @@ export class ComposedHandler implements ModelHandler {
// shared by two conversations the adapter's own map may already
// belong to the next request by now.
toolNameMap,
+ // Claude Code's own tool names: a function_call named `parallel` is the
+ // parallel wrapper only when none of these is called that.
+ declaredToolNames: Array.isArray(claudeRequest?.tools)
+ ? claudeRequest.tools
+ .map((t: { name?: unknown } | null) => t?.name)
+ .filter((n: unknown): n is string => typeof n === "string")
+ : [],
contextWindow: lookupModelForProvider(this.bareModelName, this.provider.name),
onApiError,
priorInputTokens,
diff --git a/packages/cli/src/handlers/shared/stream-parsers/openai-responses-sse.ts b/packages/cli/src/handlers/shared/stream-parsers/openai-responses-sse.ts
index 28d51fb7..a96046de 100644
--- a/packages/cli/src/handlers/shared/stream-parsers/openai-responses-sse.ts
+++ b/packages/cli/src/handlers/shared/stream-parsers/openai-responses-sse.ts
@@ -20,6 +20,11 @@ import { getLogLevel, log } from "../../../logger.js";
import { wrapAnthropicError } from "../anthropic-error.js";
import { messageStartUsage } from "./message-start-usage.js";
import { formatRawSseLogPayload } from "./openai-sse.js";
+import {
+ type ParallelWrapperCall,
+ isParallelWrapperName,
+ parseParallelWrapper,
+} from "./responses/parallel-wrapper.js";
import { sseDataPayload } from "./sse-line.js";
export function createResponsesStreamHandler(
@@ -79,6 +84,13 @@ export function createResponsesStreamHandler(
onAssistantText?: (text: string, kind?: "text" | "reasoning") => void;
onToolCallObserved?: (name: string) => void;
onTurnEnd?: () => void;
+ /**
+ * The request's tool names as Claude Code sent them (decoded, not the
+ * encoded wire names). A function_call named `parallel` is treated as the
+ * parallel wrapper only when no declared tool has that name. Absent → the
+ * values of `toolNameMap`.
+ */
+ declaredToolNames?: string[];
}
): Response {
const reader = response.body?.getReader();
@@ -146,6 +158,24 @@ export function createResponsesStreamHandler(
// Tool blocks that have been started but not yet stopped, in emission order.
const openToolBlocks = new Set<FnCall>();
+ /**
+ * A `parallel` wrapper call being accumulated without a content_block_start
+ * (see responses/parallel-wrapper.ts). Keyed by call_id and item_id, like
+ * `functionCalls`; removed at its output_item.done.
+ */
+ type HeldWrapper = {
+ claudeBaseId: string;
+ arguments: string;
+ doneArgs?: string;
+ /** The reasoning that led to the wrapper, bound to its first expanded call only. */
+ reasoning: CachedReasoningItem[];
+ };
+ const heldWrappers: Map<string, HeldWrapper> = new Map();
+ const declaredToolNames: string[] = opts.declaredToolNames ?? [
+ ...(opts.toolNameMap?.values() ?? []),
+ ];
+ const decodeToolName = (name: string) => opts.toolNameMap?.get(name) || name;
+
const stream = new ReadableStream({
/*
* The SSE event dispatch below has been far over the complexity limit since
@@ -251,6 +281,79 @@ export function createResponsesStreamHandler(
log(`[ResponsesSSE] done arguments diverge from streamed deltas for ${fnCall.name}`);
};
+ /**
+ * End the turn with an SSE `error` event: Claude Code discards the message
+ * (no tool_use of it runs) and retries the turn. Open blocks are closed
+ * first, because their starts are already on the wire. The upstream reader
+ * is cancelled: nothing more of this response will be used.
+ */
+ const endTurnWithStreamError = (message: string) => {
+ closeReasoning();
+ closeText();
+ closeTools();
+ send("error", { type: "error", error: { type: "api_error", message } });
+ isClosed = true;
+ if (pingInterval) {
+ clearInterval(pingInterval);
+ pingInterval = null;
+ }
+ if (opts.onTokenUpdate) opts.onTokenUpdate(inputTokens, outputTokens);
+ reader.cancel().catch(() => {});
+ safeClose();
+ };
+
+ /** A degenerate `parallel` wrapper: never shown to Claude Code. */
+ const endTurnOnDegenerateWrapper = (reason: string, bytes: number) => {
+ log(`[ResponsesSSE] degenerate parallel wrapper (${reason}, ${bytes} bytes) → error event`);
+ endTurnWithStreamError(`degenerate parallel tool wrapper (${reason}, ${bytes} bytes)`);
+ };
+
+ /**
+ * Emit a valid wrapper's entries as ordinary tool_use blocks, one complete
+ * argument delta each (a buffered tool goes through onToolCall first). The
+ * wrapper's reasoning is remembered under the FIRST expanded id only, so the
+ * next request replays it exactly once, before that call.
+ */
+ const repairBufferedCall = (name: string, args: string): string => {
+ if (opts.shouldBufferTool?.(name) !== true) return args;
+ try {
+ const repaired = opts.onToolCall?.(name, args);
+ if (typeof repaired === "string" && repaired !== args) {
+ log(`[ResponsesSSE] tool call repaired: ${name}`);
+ return repaired;
+ }
+ } catch (err) {
+ log(`[ResponsesSSE] onToolCall threw for ${name}: ${err}`);
+ }
+ return args;
+ };
+ const emitExpandedWrapper = (held: HeldWrapper, calls: ParallelWrapperCall[]) => {
+ closeReasoning();
+ closeText();
+ calls.forEach((call, k) => {
+ const id = `${held.claudeBaseId}_p${k}`;
+ const args = repairBufferedCall(call.name, call.arguments);
+ const index = curIdx++;
+ opts.onToolCallObserved?.(call.name);
+ send("content_block_start", {
+ type: "content_block_start",
+ index,
+ content_block: { type: "tool_use", id, name: call.name, input: {} },
+ });
+ send("content_block_delta", {
+ type: "content_block_delta",
+ index,
+ delta: { type: "input_json_delta", partial_json: args },
+ });
+ send("content_block_stop", { type: "content_block_stop", index });
+ if (k === 0 && held.reasoning.length > 0) {
+ rememberReasoningForCall(id, held.reasoning);
+ }
+ });
+ hasToolUse = true;
+ log(`[ResponsesSSE] parallel wrapper expanded into ${calls.length} tool_use block(s)`);
+ };
+
/**
* The five-event tail both in-band error paths emit: a text block carrying
* the message, then a normal `end_turn`. Shared so the two callers cannot
@@ -362,7 +465,22 @@ export function createResponsesStreamHandler(
? openaiCallId
: `toolu_${openaiCallId.replace(/^fc_/, "")}`;
const rawFnName = event.item.name || "";
- const fnName = opts.toolNameMap?.get(rawFnName) || rawFnName;
+ const fnName = decodeToolName(rawFnName);
+
+ if (isParallelWrapperName(fnName, declaredToolNames)) {
+ // HOLD: no content_block_start until the arguments are judged.
+ // The reasoning so far belongs to the wrapper, not to a later call.
+ const held: HeldWrapper = {
+ claudeBaseId: callId,
+ arguments: "",
+ reasoning: pendingReasoning,
+ };
+ pendingReasoning = [];
+ heldWrappers.set(openaiCallId, held);
+ if (itemId && itemId !== openaiCallId) heldWrappers.set(itemId, held);
+ log(`[ResponsesSSE] holding parallel wrapper ${rawFnName}`);
+ continue;
+ }
closeReasoning();
closeText();
@@ -439,6 +557,8 @@ export function createResponsesStreamHandler(
} else if (event.type === "response.function_call_arguments.delta") {
const callId = event.call_id || event.item_id;
const fnCall = functionCalls.get(callId);
+ const held = fnCall ? undefined : heldWrappers.get(callId);
+ if (held) held.arguments += event.delta || "";
if (fnCall) {
fnCall.arguments += event.delta || "";
// Buffered calls emit nothing here — the whole argument object
@@ -457,8 +577,10 @@ export function createResponsesStreamHandler(
// turn with NO argument deltas, so for those calls this (or the
// item at output_item.done) is the only copy of the arguments.
const fnCall = functionCalls.get(event.call_id) || functionCalls.get(event.item_id);
- if (fnCall && typeof event.arguments === "string") {
- fnCall.doneArgs = event.arguments;
+ const held = heldWrappers.get(event.call_id) || heldWrappers.get(event.item_id);
+ if (typeof event.arguments === "string") {
+ if (fnCall) fnCall.doneArgs = event.arguments;
+ else if (held) held.doneArgs = event.arguments;
}
} else if (event.type === "response.output_item.done") {
if (event.item?.type === "reasoning" && event.item.encrypted_content) {
@@ -473,6 +595,21 @@ export function createResponsesStreamHandler(
}
if (event.item?.type === "function_call") {
const callId = event.item.call_id || event.item.id;
+ const held = heldWrappers.get(callId) || heldWrappers.get(event.item.id);
+ if (held) {
+ heldWrappers.delete(callId);
+ heldWrappers.delete(event.item.id);
+ const itemArgs =
+ typeof event.item.arguments === "string" ? event.item.arguments : undefined;
+ const final = held.doneArgs ?? itemArgs ?? held.arguments;
+ const parsed = parseParallelWrapper(final, decodeToolName);
+ if (!parsed.ok) {
+ endTurnOnDegenerateWrapper(parsed.reason, final.length);
+ return;
+ }
+ emitExpandedWrapper(held, parsed.calls);
+ continue;
+ }
const fnCall = functionCalls.get(callId) || functionCalls.get(event.item.id);
if (fnCall && openToolBlocks.has(fnCall)) {
const itemArgs =
@@ -520,6 +657,16 @@ export function createResponsesStreamHandler(
inputTokens = event.response.usage.input_tokens || inputTokens;
outputTokens = event.response.usage.output_tokens || outputTokens;
}
+ // A wrapper still held when the response is cut short never got
+ // its arguments judged: degenerate by definition.
+ const pending = heldWrappers.values().next().value;
+ if (pending) {
+ endTurnOnDegenerateWrapper(
+ "incomplete",
+ (pending.doneArgs ?? pending.arguments).length
+ );
+ return;
+ }
} else if (event.type === "response.completed" || event.type === "response.done") {
if (event.response?.usage) {
inputTokens = event.response.usage.input_tokens || 0;
@@ -579,6 +726,17 @@ export function createResponsesStreamHandler(
}
}
+ // The stream ended while a wrapper was still held: its arguments were
+ // never completed, so there is nothing valid to expand.
+ const unfinished = heldWrappers.values().next().value;
+ if (unfinished) {
+ endTurnOnDegenerateWrapper(
+ "incomplete",
+ (unfinished.doneArgs ?? unfinished.arguments).length
+ );
+ return;
+ }
+
if (pingInterval) {
clearInterval(pingInterval);
pingInterval = null;
diff --git a/packages/cli/src/handlers/shared/stream-parsers/responses/parallel-wrapper.ts b/packages/cli/src/handlers/shared/stream-parsers/responses/parallel-wrapper.ts
new file mode 100644
index 00000000..89de4530
--- /dev/null
+++ b/packages/cli/src/handlers/shared/stream-parsers/responses/parallel-wrapper.ts
@@ -0,0 +1,119 @@
+/**
+ * The `parallel` tool wrapper some OpenAI models emit instead of N separate
+ * function calls.
+ *
+ * Models trained on the ChatGPT tool protocol know a built-in
+ * `multi_tool_use.parallel` tool whose arguments are
+ * `{tool_uses:[{recipient_name:"functions.<tool>", parameters:{...}}]}`. The
+ * Codex backend normally unpacks a valid wrapper itself, so claudish never sees
+ * one; what does reach the Responses stream is a function_call NAMED
+ * `parallel` (or `multi_tool_use.parallel`) that no tool in the request
+ * declares. In the observed failure (~1% of turns,
+ * `ai-docs/reports/codex-parallel-wrapper-degeneration-2026-10.md`) its
+ * arguments are a degenerate 41-96 KB string (`a.ts.tsaaa.ts.ts...`) that
+ * arrives in one burst after a 361-484 s keepalive-only stall, ending on
+ * `response.incomplete` `max_output_tokens`.
+ *
+ * Forwarded as-is, Claude Code receives a call to a tool that does not exist.
+ * So the parser holds such a call (no `content_block_start`) and decides at
+ * `output_item.done`: a valid wrapper becomes one tool_use block per entry; a
+ * degenerate one is never shown to Claude Code.
+ */
+
+/** Wrapper names, with the optional `functions.` namespace stripped first. */
+const WRAPPER_NAMES = new Set(["parallel", "multi_tool_use.parallel"]);
+
+function stripFunctionsPrefix(name: string): string {
+ return name.startsWith("functions.") ? name.slice("functions.".length) : name;
+}
+
+/**
+ * Is this function_call the `parallel` wrapper rather than a real tool?
+ *
+ * True iff the name (optionally `functions.`-prefixed) is `parallel` or
+ * `multi_tool_use.parallel` AND no tool the request declared is called that.
+ * `declaredNames` are the request's tool names as Claude Code sent them (the
+ * DECODED names, not the encoded wire names), so a user tool really named
+ * `parallel` is always forwarded as an ordinary call.
+ */
+export function isParallelWrapperName(name: string, declaredNames: Iterable<string>): boolean {
+ if (!name) return false;
+ const bare = stripFunctionsPrefix(name);
+ if (!WRAPPER_NAMES.has(bare)) return false;
+ for (const declared of declaredNames) {
+ if (declared === name || declared === bare) return false;
+ }
+ return true;
+}
+
+/** One expanded call: the Claude Code tool name and its argument JSON. */
+export interface ParallelWrapperCall {
+ name: string;
+ /** JSON text of the call's arguments, ready for one `input_json_delta`. */
+ arguments: string;
+}
+
+export type ParallelWrapperParse =
+ | { ok: true; calls: ParallelWrapperCall[] }
+ | { ok: false; reason: "unparseable" | "shape" | "empty" };
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+ return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** The argument JSON for one entry's `parameters`, or undefined when it is not an object. */
+function parametersJson(parameters: unknown): string | undefined {
+ if (isPlainObject(parameters)) return JSON.stringify(parameters);
+ if (typeof parameters === "string") {
+ try {
+ const parsed = JSON.parse(parameters);
+ if (isPlainObject(parsed)) return parameters;
+ } catch {
+ return undefined;
+ }
+ }
+ return undefined;
+}
+
+/**
+ * Parse a wrapper's complete argument string.
+ *
+ * Valid: `{tool_uses:[{recipient_name, parameters}, ...]}` with at least one
+ * entry, every `recipient_name` a non-empty string and every `parameters` an
+ * object (or a JSON string of one). Each name has `functions.` stripped and is
+ * then passed through `decode` (the request's encoded-to-Claude tool name map);
+ * an unknown recipient is kept as-is, so Claude Code reports it to the model
+ * rather than claudish dropping it silently.
+ *
+ * Anything else is degenerate: `unparseable` (not JSON), `shape` (JSON of the
+ * wrong shape), `empty` (an empty argument string or an empty `tool_uses`).
+ */
+export function parseParallelWrapper(
+ args: string,
+ decode: (name: string) => string
+): ParallelWrapperParse {
+ if (!args || args.trim() === "") return { ok: false, reason: "empty" };
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(args);
+ } catch {
+ return { ok: false, reason: "unparseable" };
+ }
+ if (!isPlainObject(parsed) || !Array.isArray(parsed.tool_uses)) {
+ return { ok: false, reason: "shape" };
+ }
+ if (parsed.tool_uses.length === 0) return { ok: false, reason: "empty" };
+ const calls: ParallelWrapperCall[] = [];
+ for (const entry of parsed.tool_uses) {
+ if (!isPlainObject(entry)) return { ok: false, reason: "shape" };
+ const recipient = entry.recipient_name;
+ if (typeof recipient !== "string" || recipient.trim() === "") {
+ return { ok: false, reason: "shape" };
+ }
+ const json = parametersJson(entry.parameters);
+ if (json === undefined) return { ok: false, reason: "shape" };
+ const bare = stripFunctionsPrefix(recipient);
+ calls.push({ name: decode(bare) || bare, arguments: json });
+ }
+ return { ok: true, calls };
+}