fix(openai-shim): recover <tool_call> text tool calls on Ollama streams (#2476)

* fix(openai-shim): recover <tool_call> text tool calls on Ollama streams Qwen-family models served by Ollama (e.g. qwen2.5-coder) can return their template-format tool call, `<tool_call>{"name":…,"arguments":…}</tool_call>`, in message.content instead of message.tool_calls. The Ollama stream fallback only parsed bare/fenced JSON, and the XML fallback is skipped for Ollama streams, so the call was shown as text and Bash never ran. Fall back to the existing XML tool-call parser when the JSON text parser finds nothing on an Ollama terminal finish. Refs #2040 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(openai-shim): keep reasoning and JSON arguments out of Ollama XML tool recovery The Ollama terminal XML fallback parsed raw accumulated text, so a <tool_call> inside <think> reasoning became an executable tool_use. Parse the stream's think-filtered visible text instead and strip ranges from that same text. The standard XML dialect selector matched <function=...> anywhere in a block before recognising a JSON envelope, so XML-looking text inside JSON arguments replaced the outer tool name and input. Apply the existing JSON-envelope guard (already used for arg_key/arg_value) to the <function=...> dialect too. Refs #2040 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(openai-shim): keep visible XML tool-call arguments verbatim Parsing the think-filtered buffer removed <think>...</think> text from the arguments of visible calls, silently altering e.g. Write content. Parse the raw text again and decide per block whether it opens inside reasoning, using the stream's think filter; visible blocks are copied verbatim and only reasoning outside them is dropped. A JSON-envelope <tool_call> block now ends at its balanced closing brace, so a </tool_call> inside a JSON string no longer cuts the block short and lets markup embedded in the arguments run as another call. Refs #2040 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(openai-shim): keep tool-call blocks whole when removing Ollama reasoning The reasoning filter decided visibility from named-call ranges by the opener alone, then fed hidden blocks through the stateful think filter or copied visible blocks verbatim. Those ranges come from a reasoning-unaware parse, so a block could cross a reasoning boundary: a `</think>` inside a hidden call's argument ended the reasoning and exposed nested markup, a visible opener whose block ran into reasoning carried reasoning bytes into a call, and a block opened in reasoning that ran into a visible call stripped that call's arguments. Blocks that do not parse as a named call were not protected at all, and an unclosed reasoning tag running into a block opener was not recognised. Treat every tool-call block the parser delimits as one unit that never reaches the filter: visible blocks are copied verbatim and hidden blocks are dropped, with a boundary marker so a partial tag cannot join across a dropped block. When reasoning markup touches a non-JSON block or runs into a block opener, or the re-parse yields a call the raw text did not contain, ownership is ambiguous, so XML recovery fails closed and the response stays text, as before this PR. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(openai-shim): let every dialect-C JSON envelope own its tool-call block Three checks decided whether a <tool_call> body is a JSON envelope, and they disagreed. The block scanner and the dialect A/B guard required `{` as the first character, while the dialect-C extractor took the first `{` anywhere. A body with a `json` label or a ```json fence before the object was still parsed as a dialect-C call, but its block ended at the first `</tool_call>` and `<function=...>` text inside its argument strings matched dialect A. Text inside such a call's arguments could replace it with a different tool, and the new Ollama fallback now executes these. Locate the envelope once: the first `{` before the closing tag, with no dialect A/B markup before it, that starts a valid JSON object. The block ends at the first closing tag after that object. The parser takes that object for dialect C, and the Ollama reasoning check looks for reasoning markup only outside it. Dialect A/B parsing, malformed and truncated bodies, and every other route's behavior are unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 12:50:54 -04:00 · 2026-10-31 08:24:47 -07:00
parent beecf58f86
commit cd6655470a
4 changed files with 461 additions and 34 deletions
@@ -658,3 +658,207 @@ describe('Ollama streaming — non-stop terminal finish reasons flush buffer', (
    expect(delta?.stop_reason).not.toBe('tool_use')
  })
 })
+
+describe('Ollama streaming — <tool_call>-wrapped JSON text fallback (#2040)', () => {
+  let originalFetch: FetchType
+  let restoreEnv: () => void
+  beforeEach(() => {
+    originalFetch = globalThis.fetch
+    restoreEnv = snapshotEnv(ENV_KEYS)
+    process.env.OLLAMA_BASE_URL = 'http://localhost:11434'
+    process.env.OPENAI_API_KEY = 'test-key'
+    process.env.OPENAI_BASE_URL = 'http://localhost:11434/v1'
+  })
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+    restoreEnv()
+  })
+
+  test('Qwen-style <tool_call>{json}</tool_call> text becomes a tool_use block', async () => {
+    // Repro: Ollama returns the model's template-format tool call (prose then
+    // <tool_call>{json}</tool_call>) in message.content, not message.tool_calls.
+    globalThis.fetch = (async () =>
+      makeOllamaNativeStreamingResponse(
+        makeNdjsonChunks([
+          ollamaChunk('I will build the project.\n<tool_call>\n'),
+          ollamaChunk('{"name": "Bash", "arguments": {"command": "npm run build"}}\n'),
+          ollamaChunk('</tool_call>'),
+          ollamaChunk('', 'stop'),
+        ]),
+      )) as unknown as FetchType
+
+    const client = createOpenAIShimClient({}) as OpenAIShimClient
+    const result = await client.beta.messages
+      .create({
+        model: 'qwen2.5-coder:14b',
+        messages: [{ role: 'user', content: 'build the project' }],
+        max_tokens: 64,
+        stream: true,
+      })
+      .withResponse()
+
+    const events: Record<string, unknown>[] = []
+    for await (const event of result.data) events.push(event)
+
+    const allText = events
+      .filter(e => e.type === 'content_block_delta' && (e.delta as Record<string, string>)?.type === 'text_delta')
+      .map(e => (e.delta as Record<string, string>).text)
+      .join('')
+    expect(allText).toBe('I will build the project.')
+
+    const toolStarts = events.filter(
+      e => e.type === 'content_block_start' && (e.content_block as Record<string, string>)?.type === 'tool_use',
+    )
+    expect(toolStarts).toHaveLength(1)
+    expect((toolStarts[0].content_block as Record<string, string>).name).toBe('Bash')
+    const toolInput = events
+      .filter(e => e.type === 'content_block_delta' && (e.delta as Record<string, string>)?.type === 'input_json_delta')
+      .map(e => (e.delta as Record<string, string>).partial_json)
+      .join('')
+    expect(JSON.parse(toolInput)).toEqual({ command: 'npm run build' })
+
+    const messageDelta = events.find(e => e.type === 'message_delta') as Record<string, unknown> | undefined
+    expect((messageDelta?.delta as Record<string, unknown>)?.stop_reason).toBe('tool_use')
+  })
+
+  async function streamOllamaContent(content: string) {
+    globalThis.fetch = (async () =>
+      makeOllamaNativeStreamingResponse(
+        makeNdjsonChunks([ollamaChunk(content), ollamaChunk('', 'stop')]),
+      )) as unknown as FetchType
+
+    const client = createOpenAIShimClient({}) as OpenAIShimClient
+    const result = await client.beta.messages
+      .create({
+        model: 'qwen2.5-coder:14b',
+        messages: [{ role: 'user', content: 'go' }],
+        max_tokens: 64,
+        stream: true,
+      })
+      .withResponse()
+
+    const events: Record<string, unknown>[] = []
+    for await (const event of result.data) events.push(event)
+
+    const deltas = events
+      .filter(e => e.type === 'content_block_delta')
+      .map(e => e.delta as Record<string, string>)
+    const messageDelta = events.find(e => e.type === 'message_delta') as Record<string, unknown> | undefined
+    return {
+      text: deltas.filter(d => d.type === 'text_delta').map(d => d.text).join(''),
+      tools: events
+        .filter(e => e.type === 'content_block_start' && (e.content_block as Record<string, string>)?.type === 'tool_use')
+        .map(e => (e.content_block as Record<string, string>).name),
+      inputs: deltas.filter(d => d.type === 'input_json_delta').map(d => JSON.parse(d.partial_json)),
+      stopReason: (messageDelta?.delta as Record<string, unknown>)?.stop_reason,
+    }
+  }
+
+  const xmlCall = (command: string) =>
+    `<tool_call>{"name":"Bash","arguments":{"command":"${command}"}}</tool_call>`
+
+  test.each([
+    ['closed', `<think>I could call ${xmlCall('echo speculative')} but should ask first.</think>Please confirm the operation.`],
+    ['unterminated', `Please confirm the operation. <think>I could call ${xmlCall('echo speculative')}`],
+  ])('<tool_call> inside %s reasoning is not recovered as a tool call', async (_kind, content) => {
+    const { text, tools, stopReason } = await streamOllamaContent(content)
+    expect(text.trim()).toBe('Please confirm the operation.')
+    expect(tools).toEqual([])
+    expect(stopReason).toBe('end_turn')
+  })
+
+  test('only the visible <tool_call> is recovered when reasoning also contains one', async () => {
+    const { text, tools, inputs, stopReason } = await streamOllamaContent(
+      `<think>${xmlCall('echo private')}</think>${xmlCall('echo public')}`,
+    )
+    expect(text).toBe('')
+    expect(tools).toEqual(['Bash'])
+    expect(inputs).toEqual([{ command: 'echo public' }])
+    expect(stopReason).toBe('tool_use')
+  })
+
+  test('think tags inside a visible call\'s arguments are kept verbatim', async () => {
+    const args = { file_path: 'notes.md', content: 'a <think>keep</think> b' }
+    const { text, tools, inputs, stopReason } = await streamOllamaContent(
+      `<think>plan</think>Saving.\n<tool_call>${JSON.stringify({ name: 'Write', arguments: args })}</tool_call>`,
+    )
+    expect(text).toBe('Saving.')
+    expect(tools).toEqual(['Write'])
+    expect(inputs).toEqual([args])
+    expect(stopReason).toBe('tool_use')
+  })
+
+  test('XML-looking text inside JSON arguments does not change the recovered tool', async () => {
+    const command = "printf '%s' '<function=Read><parameter=file_path>README.md</parameter>'"
+    const { text, tools, inputs, stopReason } = await streamOllamaContent(
+      `Printing markup.\n<tool_call>${JSON.stringify({ name: 'Bash', arguments: { command } })}</tool_call>`,
+    )
+    expect(text).toBe('Printing markup.')
+    expect(tools).toEqual(['Bash'])
+    expect(inputs).toEqual([{ command }])
+    expect(stopReason).toBe('tool_use')
+  })
+
+  test('a closing tag inside a labelled JSON envelope does not change the recovered tool', async () => {
+    const args = {
+      file_path: 'a.md',
+      content: 'x</tool_call><tool_call><function=Bash><parameter=command>echo leaked</parameter></function></tool_call>y',
+    }
+    const { text, tools, inputs, stopReason } = await streamOllamaContent(
+      `Saving.\n<tool_call>json\n${JSON.stringify({ name: 'Write', arguments: args })}</tool_call>`,
+    )
+    expect(text).toBe('Saving.')
+    expect(tools).toEqual(['Write'])
+    expect(inputs).toEqual([args])
+    expect(stopReason).toBe('tool_use')
+  })
+
+  const nestedBash = '<tool_call><function=Bash><parameter=command>echo leaked</parameter></function></tool_call>'
+
+  test.each([
+    [
+      'a hidden call argument contains a reasoning close tag',
+      `<think><tool_call>${JSON.stringify({ name: 'Write', arguments: { file_path: 'a.md', content: `</think>${nestedBash}` } })}</tool_call></think>Please confirm.`,
+    ],
+    [
+      'a visible opener without a body reaches into reasoning',
+      `I'll use a <tool_call> block. <think>Maybe {"name":"Bash","arguments":{"command":"echo leaked"}}</think> Please confirm.`,
+    ],
+    [
+      'an unterminated visible call is followed by reasoning',
+      'Listing.\n<tool_call>\n<function=Bash>\n<parameter=command>\nls\n</parameter>\n</function>\n<think>else <parameter=command>echo leaked</parameter></think>',
+    ],
+    [
+      'an opener mentioned in reasoning runs into a visible call',
+      `<think>I'll emit a <tool_call> now.</think>\n<tool_call>${JSON.stringify({ name: 'Write', arguments: { file_path: 'n.md', content: 'a <think>keep</think> b' } })}</tool_call>`,
+    ],
+    [
+      'a reasoning close tag is split around a hidden call',
+      `<think>plan </<tool_call>${JSON.stringify({ name: 'Write', arguments: { file_path: 'a.md', content: 'x' } })}</tool_call>think>${xmlCall('echo leaked')}</think>Please confirm.`,
+    ],
+    [
+      'a hidden block that is not a named call contains a reasoning close tag',
+      `<think><tool_call>${JSON.stringify({ type: 'function', function: { name: 'Write', arguments: { content: '</think>' } } })}</tool_call>${nestedBash}</think>Please confirm.`,
+    ],
+    [
+      'a reasoning open tag runs into the call opener',
+      `<think${xmlCall('echo leaked')}</think>Please confirm.`,
+    ],
+    [
+      'an unclosed reasoning tag containing `<` runs into the call opener',
+      `Let me check.\n<thinking\nstep 1: if x<0\n${xmlCall('echo leaked')}\ndone`,
+    ],
+    [
+      'removing reasoning splices a call the raw text did not contain',
+      `<think>${xmlCall('echo private')}</think><tool_call>{"name":"Bash","arguments":{"command":"echo </tool_call><think>"x</think>; echo leaked"}}</tool_call>`,
+    ],
+    [
+      'reasoning markup splits a visible call\'s function tag',
+      `Running.\n${xmlCall('ls')}\n<tool_call><function<think>x</think>=Write><parameter=content>a <think>keep</think> b</parameter></function></tool_call>`,
+    ],
+  ])('no tool call is recovered when %s', async (_case, content) => {
+    const { tools, stopReason } = await streamOllamaContent(content)
+    expect(tools).toEqual([])
+    expect(stopReason).toBe('end_turn')
+  })
+})
@@ -17,6 +17,10 @@ import {
  processStreamChunk,
 } from '../../../utils/streamingOptimizer.js'
 import type { createProviderStreamTrace } from './streamControl.js'
+import {
+  findXmlToolCallBlockRanges,
+  xmlToolCallBlockMarkup,
+} from './xmlToolCallParsing.js'

 type ParsedRawToolCall = { id: string; name: string; argumentsJson: string }
 type ParsedTextToolCall = { id: string; name: string; arguments: unknown }
@@ -99,6 +103,60 @@ const JSON_REPAIR_SUFFIXES = [
  '}', '"}', ']}', '"]}', '}}', '"}}', ']}}', '"]}}', '"]}]}', '}]}',
 ]

+// Fed to the think filter at each block boundary. It cannot continue a tag, so
+// a partial tag held before a block never joins the text after it.
+const TOOL_CALL_BLOCK_BOUNDARY = '\u0000'
+
+/**
+ * Whether reasoning markup touches the tool-call block at `start`: a reasoning
+ * tag inside the block (outside a JSON envelope's object, whose tag-like text
+ * is data), or a tag that runs from the preceding text into the block's opener
+ * (a tag ends at the first `>`, so any tag in the text after the last `>`
+ * before the block ends at its opener). Either way the block's range may cross
+ * a reasoning boundary.
+ */
+function reasoningMarkupTouchesBlock(text: string, start: number, block: string): boolean {
+  const markup = xmlToolCallBlockMarkup(block)
+  if (stripThinkTags(markup) !== markup) return true
+  const lastTagEnd = start > 0 ? text.lastIndexOf('>', start - 1) : -1
+  const openerTail = text.slice(lastTagEnd + 1, text.indexOf('>', start) + 1)
+  return stripThinkTags(openerTail) !== openerTail
+}
+
+/**
+ * Applies the streaming think filter to `text` but treats each tool-call block
+ * as one unit that never reaches the filter: blocks that open in visible text
+ * are copied verbatim, so think tags inside their JSON arguments survive, and
+ * blocks that open inside reasoning are dropped, so nothing inside them can end
+ * the reasoning. Returns null when reasoning markup touches a block or blocks
+ * partially overlap: no call parsed from such a block can be attributed to
+ * visible text.
+ */
+function visibleTextKeepingToolCallBlocks(
+  text: string,
+  blockRanges: Array<[number, number]>,
+): string | null {
+  const filter = createThinkTagFilter()
+  let visible = ''
+  let position = 0
+  for (const [start, end] of blockRanges) {
+    if (start < position) {
+      if (end > position) return null
+      continue
+    }
+    const block = text.slice(start, end)
+    if (reasoningMarkupTouchesBlock(text, start, block)) return null
+    const before = filter.feed(text.slice(position, start) + TOOL_CALL_BLOCK_BOUNDARY)
+    if (filter.isInsideBlock()) {
+      visible += before
+    } else {
+      visible += before.slice(0, -1) + block
+    }
+    position = end
+  }
+  return visible + filter.feed(text.slice(position))
+}
+
 export function convertOpenAIStreamUsage(
  usage: Record<string, unknown> | undefined,
 ): Partial<AnthropicUsage> | undefined {
@@ -800,12 +858,46 @@ export async function* openaiStreamToAnthropic(
          const originalFinishReason = choice.finish_reason
          let ollamaClosedContentBlock = false
          if (isTerminalOllamaFinish) {
-            const { calls: textToolCalls, toolCallRanges } = parseTextToolCalls(accumulatedText)
+            let toolCallSource = accumulatedText
+            let { calls: textToolCalls, toolCallRanges } = parseTextToolCalls(accumulatedText)
+            // Qwen-family templates wrap tool calls in `<tool_call>` tags, which
+            // Ollama can leave unparsed in message.content (#2040). Only blocks
+            // that open in visible text count: re-parse without reasoning so
+            // markup inside it never becomes an executable call, and recover
+            // nothing when a block crosses a reasoning boundary. Removing
+            // reasoning may only drop calls: a re-parsed call that the raw text
+            // did not contain was spliced across reasoning, so recover nothing.
+            if (textToolCalls.length === 0) {
+              ;({ calls: textToolCalls, toolCallRanges } = parseXmlToolCalls(
+                accumulatedText,
+                allowHy3ToolCalls,
+              ))
+              const visibleSource = textToolCalls.length > 0
+                ? visibleTextKeepingToolCallBlocks(
+                  accumulatedText,
+                  findXmlToolCallBlockRanges(accumulatedText, allowHy3ToolCalls),
+                )
+                : accumulatedText
+              const callKey = (tc: ParsedTextToolCall) =>
+                `${tc.name}\0${JSON.stringify(tc.arguments)}`
+              const rawCallKeys = new Set(textToolCalls.map(callKey))
+              if (visibleSource !== null && visibleSource !== accumulatedText) {
+                toolCallSource = visibleSource
+                ;({ calls: textToolCalls, toolCallRanges } = parseXmlToolCalls(
+                  toolCallSource,
+                  allowHy3ToolCalls,
+                ))
+              }
+              if (visibleSource === null || textToolCalls.some(tc => !rawCallKeys.has(callKey(tc)))) {
+                textToolCalls = []
+                toolCallRanges = []
+              }
+            }
            if (textToolCalls.length > 0) {
              ollamaClosedContentBlock = true
              // Compute visible prose (tool-call JSON stripped, think-tags removed).
-              // Use accumulatedText (raw) as source because toolCallRanges are relative to it.
-              const stripped = stripRanges(accumulatedText, toolCallRanges).trim()
+              // toolCallRanges are relative to the text the calls were parsed from.
+              const stripped = stripRanges(toolCallSource, toolCallRanges).trim()
              const strippedVisible = stripThinkTags(stripped).trim()
              if (hasEmittedContentStart) {
                // Text block was already open — emit stripped prose then close it.
@@ -138,6 +138,48 @@ describe('parseXmlToolCalls', () => {
    expect(calls[0].arguments).toEqual({ command: 'pwd' })
  })

+  const xmlLookingCommand =
+    "printf '%s' '<function=Read><parameter=file_path>README.md</parameter>'"
+  test.each([
+    ['object', { command: xmlLookingCommand }],
+    ['JSON string', JSON.stringify({ command: xmlLookingCommand })],
+  ])('dialect C: XML-looking text in %s arguments stays data', (_encoding, args) => {
+    const text = `<tool_call>${JSON.stringify({ name: 'Bash', arguments: args })}</tool_call>`
+    const { calls, toolCallRanges } = parseXmlToolCalls(text)
+    expect(calls).toHaveLength(1)
+    expect(calls[0].name).toBe('Bash')
+    expect(calls[0].arguments).toEqual({ command: xmlLookingCommand })
+    expect(toolCallRanges).toEqual([[0, text.length]])
+  })
+
+  test('dialect C: a closing tag inside a JSON string does not end the block', () => {
+    const content =
+      'x</tool_call><tool_call><function=Bash><parameter=command>rm -rf build</parameter></function></tool_call>y'
+    const text = `<tool_call>${JSON.stringify({ name: 'Write', arguments: { file_path: 'a.md', content } })}</tool_call> done`
+    const { calls, toolCallRanges } = parseXmlToolCalls(text)
+    expect(calls).toHaveLength(1)
+    expect(calls[0].name).toBe('Write')
+    expect(calls[0].arguments).toEqual({ file_path: 'a.md', content })
+    expect(toolCallRanges).toEqual([[0, text.length - ' done'.length]])
+  })
+
+  test.each([
+    ['a `json` label', (json: string) => `json\n${json}`],
+    ['a Markdown fence', (json: string) => `\n\`\`\`json\n${json}\n\`\`\`\n`],
+  ])('dialect C: a JSON envelope behind %s owns its block', (_wrapper, wrap) => {
+    for (const content of [
+      'x</tool_call><tool_call><function=Bash><parameter=command>rm -rf build</parameter></function></tool_call>y',
+      '<function=Read><parameter=file_path>README.md</parameter>',
+    ]) {
+      const block = `<tool_call>${wrap(JSON.stringify({ name: 'Write', arguments: { file_path: 'a.md', content } }))}</tool_call>`
+      const { calls, toolCallRanges } = parseXmlToolCalls(`${block} done`)
+      expect(calls).toHaveLength(1)
+      expect(calls[0].name).toBe('Write')
+      expect(calls[0].arguments).toEqual({ file_path: 'a.md', content })
+      expect(toolCallRanges).toEqual([[0, block.length]])
+    }
+  })
+
  test('preserves source order when mixing standard XML and HY3 dialects', () => {
    const text =
      'before <tool_call>{"name":"xml_first","arguments":{}}</tool_call> ' +
@@ -54,9 +54,8 @@ const XML_TOOL_CALL_OPENERS = [
  HY3_TOOL_CALLS_OPEN,
  HY3_TOOL_CALL_OPEN,
 ]
-// Non-greedy block matcher; the `$` alternative tolerates a truncated final
-// block (stream cut off before the closing tag).
-const XML_TOOL_CALL_BLOCK_RE = /<tool_call>([\s\S]*?)(?:<\/tool_call>|$)/g
+const XML_TOOL_CALL_CLOSE = '</tool_call>'
+const XML_ARG_KEY_OPEN = '<arg_key>'
 const HY3_TOOL_CALLS_BLOCK_RE = /<tool_calls:[^>\s]+>([\s\S]*?)(?:<\/tool_calls(?::[^>\s]+)?>|$)/g
 const HY3_TOOL_CALL_BLOCK_RE = /<tool_call:[^>\s]+>([\s\S]*?)(?:<\/tool_call(?::[^>\s]+)?>|$)/g
 const XML_FUNCTION_NAME_RE = /<function=([^>\s]+)\s*>/
@@ -94,19 +93,122 @@ export function findXmlToolCallOpener(text: string, allowHy3: boolean): number {
  }, -1)
 }

+function isJsonText(raw: string): boolean {
+  try {
+    JSON.parse(raw)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Locates the JSON envelope (dialect C) of the body starting at `bodyStart`:
+ * the first `{` before the closing tag, with no dialect A/B markup before it,
+ * starting a valid JSON object. A label or Markdown fence may surround the
+ * object (`json\n{…}`, ```` ```json\n{…}\n``` ````). The body ends at the first
+ * closing tag after the object, or at the end of the text.
+ */
+function findJsonEnvelopeBody(
+  text: string,
+  bodyStart: number,
+): { json: [number, number]; bodyEnd: number; end: number } | null {
+  const firstClose = text.indexOf(XML_TOOL_CALL_CLOSE, bodyStart)
+  const jsonStart = text.indexOf('{', bodyStart)
+  if (jsonStart === -1 || (firstClose !== -1 && jsonStart > firstClose)) return null
+  const lead = text.slice(bodyStart, jsonStart)
+  if (XML_FUNCTION_NAME_RE.test(lead) || lead.includes(XML_ARG_KEY_OPEN)) return null
+  const json = extractBalancedJson(text, jsonStart)
+  if (!json || !isJsonText(json)) return null
+  const jsonEnd = jsonStart + json.length
+  const closeIndex = text.indexOf(XML_TOOL_CALL_CLOSE, jsonEnd)
+  return closeIndex === -1
+    ? { json: [jsonStart, jsonEnd], bodyEnd: text.length, end: text.length }
+    : { json: [jsonStart, jsonEnd], bodyEnd: closeIndex, end: closeIndex + XML_TOOL_CALL_CLOSE.length }
+}
+
+/**
+ * The part of a single tool-call block that can hold markup. For a standard
+ * `<tool_call>` block with a JSON envelope this is the block without its JSON
+ * object, since tag-like text inside the object lies in JSON strings; for any
+ * other block it is the whole block.
+ */
+export function xmlToolCallBlockMarkup(block: string): string {
+  if (!block.startsWith(XML_TOOL_CALL_OPEN)) return block
+  const envelope = findJsonEnvelopeBody(block, XML_TOOL_CALL_OPEN.length)
+  if (envelope?.end !== block.length) return block
+  return block.slice(0, envelope.json[0]) + block.slice(envelope.json[1])
+}
+
+/**
+ * Finds standard `<tool_call>` blocks. A JSON-envelope body (dialect C) is
+ * bounded by its balanced JSON object, so a `</tool_call>` inside a JSON string
+ * is data and cannot end the block early. Other bodies end at the first closing
+ * tag; a missing closing tag runs to the end of the text (stream cut off).
+ */
+function findStandardXmlToolCallBlocks(
+  text: string,
+): Array<{ range: [number, number]; inner: string; json?: string }> {
+  const blocks: Array<{ range: [number, number]; inner: string; json?: string }> = []
+  let start = text.indexOf(XML_TOOL_CALL_OPEN)
+  while (start !== -1) {
+    const bodyStart = start + XML_TOOL_CALL_OPEN.length
+    const envelope = findJsonEnvelopeBody(text, bodyStart)
+    let end: number
+    if (envelope) {
+      end = envelope.end
+      blocks.push({
+        range: [start, end],
+        inner: text.slice(bodyStart, envelope.bodyEnd),
+        json: text.slice(envelope.json[0], envelope.json[1]),
+      })
+    } else {
+      const closeIndex = text.indexOf(XML_TOOL_CALL_CLOSE, bodyStart)
+      const bodyEnd = closeIndex === -1 ? text.length : closeIndex
+      end = closeIndex === -1 ? text.length : closeIndex + XML_TOOL_CALL_CLOSE.length
+      blocks.push({ range: [start, end], inner: text.slice(bodyStart, bodyEnd) })
+    }
+    start = text.indexOf(XML_TOOL_CALL_OPEN, end)
+  }
+  return blocks
+}
+
+/**
+ * Ranges of every tool-call block in `text`, whether or not it parses as a
+ * call, in source order. HY3 wrappers come before the blocks they contain.
+ */
+export function findXmlToolCallBlockRanges(
+  text: string,
+  allowHy3 = false,
+): Array<[number, number]> {
+  const ranges = findStandardXmlToolCallBlocks(text).map(block => block.range)
+  if (allowHy3) {
+    for (const blockRe of [HY3_TOOL_CALLS_BLOCK_RE, HY3_TOOL_CALL_BLOCK_RE]) {
+      for (const block of text.matchAll(blockRe)) {
+        ranges.push([block.index!, block.index! + block[0].length])
+      }
+    }
+  }
+  return ranges.sort((left, right) => left[0] - right[0] || right[1] - left[1])
+}
+
 /**
 * Parse XML / HY3 tool-call markup from assistant text.
 * Callers must inject the session sequencer so XML and raw-text fallbacks
 * share one id space (see openaiShim façade `nextTextToolCallSequence`).
 */
-function parseStandardXmlToolCallInner(inner: string): {
+function parseStandardXmlToolCallInner(inner: string, envelopeJson?: string): {
  name?: string
  args: Record<string, unknown>
 } {
  let name: string | undefined
  const args: Record<string, unknown> = {}

-  const fnMatch = inner.match(XML_FUNCTION_NAME_RE)
+  const trimmedInner = inner.trim()
+  // A JSON envelope (dialect C) owns the block: XML-looking text inside its
+  // argument strings is data, not dialect A/B markup.
+  const isJsonEnvelope = envelopeJson !== undefined
+  const fnMatch = isJsonEnvelope ? null : inner.match(XML_FUNCTION_NAME_RE)
  if (fnMatch) {
    // Dialect A: <function=NAME><parameter=KEY>VALUE</parameter>…
    name = fnMatch[1]
@@ -115,9 +217,8 @@ function parseStandardXmlToolCallInner(inner: string): {
      if (key) args[key] = coerceXmlToolValue(p[2] ?? '')
    }
  } else {
-    const trimmedInner = inner.trim()
    const argPairs = [...inner.matchAll(XML_ARG_PAIR_RE)]
-    if (argPairs.length > 0 && !trimmedInner.startsWith('{')) {
+    if (argPairs.length > 0 && !isJsonEnvelope && !trimmedInner.startsWith('{')) {
      // Dialect B: leading token is the function name, then arg_key/arg_value.
      const nameTok = trimmedInner.split(/[\n<]/, 1)[0]?.trim()
      if (nameTok) name = nameTok
@@ -125,26 +226,18 @@ function parseStandardXmlToolCallInner(inner: string): {
        const key = (p[1] ?? '').trim()
        if (key) args[key] = coerceXmlToolValue(p[2] ?? '')
      }
-    } else {
-      // Dialect C: a JSON tool-call object inside the tags.
-      const jsonStart = trimmedInner.indexOf('{')
-      if (jsonStart !== -1) {
-        const jsonRaw = extractBalancedJson(trimmedInner, jsonStart)
-        if (jsonRaw) {
+    } else if (isJsonEnvelope) {
+      // Dialect C: the JSON tool-call object located by findJsonEnvelopeBody.
+      const obj = JSON.parse(envelopeJson) as Record<string, unknown>
+      if (typeof obj['name'] === 'string') {
+        name = obj['name'] as string
+        const rawArgs = obj['arguments']
+        if (typeof rawArgs === 'string') {
          try {
-            const obj = JSON.parse(jsonRaw) as Record<string, unknown>
-            if (typeof obj['name'] === 'string') {
-              name = obj['name'] as string
-              const rawArgs = obj['arguments']
-              if (typeof rawArgs === 'string') {
-                try {
-                  Object.assign(args, JSON.parse(rawArgs))
-                } catch {}
-              } else if (rawArgs && typeof rawArgs === 'object') {
-                Object.assign(args, rawArgs as Record<string, unknown>)
-              }
-            }
+            Object.assign(args, JSON.parse(rawArgs))
          } catch {}
+        } else if (rawArgs && typeof rawArgs === 'object') {
+          Object.assign(args, rawArgs as Record<string, unknown>)
        }
      }
    }
@@ -218,12 +311,8 @@ export function parseXmlToolCalls(
    })
  }

-  for (const block of text.matchAll(XML_TOOL_CALL_BLOCK_RE)) {
-    const range: [number, number] = [
-      block.index!,
-      block.index! + block[0].length,
-    ]
-    const { name, args } = parseStandardXmlToolCallInner(block[1] ?? '')
+  for (const { range, inner, json } of findStandardXmlToolCallBlocks(text)) {
+    const { name, args } = parseStandardXmlToolCallInner(inner, json)
    if (!name) continue
    candidates.push({
      range,