NativeToolCallParser.ts

import { parseJSON } from "partial-json"
import { distance } from "fastest-levenshtein"

import { type ToolName, toolNames, type FileEntry, STUB_ARGUMENTS_JSON_PARAM } from "@shofer/types"
import { type ToolUse, type McpToolUse, type ToolParamName, type NativeToolArgs, toolParamNames } from "@shofer/types"
import { customToolRegistry } from "../custom-tools/index.js"

import { resolveToolAlias } from "../tools/tool-aliases.js"
import type {
	ApiStreamToolCallStartChunk,
	ApiStreamToolCallDeltaChunk,
	ApiStreamToolCallEndChunk,
} from "../api/transform/stream.js"
import { MCP_TOOL_PREFIX, MCP_TOOL_SEPARATOR, parseMcpToolName, normalizeMcpToolName } from "../utils/mcp-name.js"

/**
 * Helper type to extract properly typed native arguments for a given tool.
 * Returns the type from NativeToolArgs if the tool is defined there, otherwise never.
 */
type NativeArgsFor<TName extends ToolName> = TName extends keyof NativeToolArgs ? NativeToolArgs[TName] : never

import { isPrivateLmTool } from "../tools/private-tool-registry.js"
import { webviewLog } from "../logging/subsystems.js"

/**
 * Find the closest matching tool name from a list of candidates using
 * Levenshtein distance. Returns the candidate with the smallest edit
 * distance, or undefined if the candidates list is empty.
 */
function findClosestToolName(haystack: string, candidates: readonly string[]): string | undefined {
	if (candidates.length === 0) return undefined

	let best = candidates[0]!
	let bestDist = distance(haystack, best)

	for (let i = 1; i < candidates.length; i++) {
		const dist = distance(haystack, candidates[i]!)
		if (dist < bestDist) {
			bestDist = dist
			best = candidates[i]!
		}
	}

	return best
}

/**
 * Parser for native tool calls (OpenAI-style function calling).
 * Converts native tool call format to ToolUse format for compatibility
 * with existing tool execution infrastructure.
 *
 * For tools with refactored parsers (e.g., read_file), this parser provides
 * typed arguments via nativeArgs. Tool-specific handlers should consume
 * nativeArgs directly rather than relying on synthesized legacy params.
 */
/**
 * Event types returned from raw chunk processing.
 */
export type ToolCallStreamEvent = ApiStreamToolCallStartChunk | ApiStreamToolCallDeltaChunk | ApiStreamToolCallEndChunk

/**
 * Parser for native tool calls (OpenAI-style function calling).
 * Converts native tool call format to ToolUse format for compatibility
 * with existing tool execution infrastructure.
 *
 * For tools with refactored parsers (e.g., read_file), this parser provides
 * typed arguments via nativeArgs. Tool-specific handlers should consume
 * nativeArgs directly rather than relying on synthesized legacy params.
 *
 * This class also handles raw tool call chunk processing, converting
 * provider-level raw chunks into start/delta/end events.
 *
 * **One parser INSTANCE per streaming task.** The parse itself is pure and
 * stays static (`parseToolCall` and its helpers), but the stream-assembly half
 * — `processRawChunk` and the `startStreamingToolCall` / `processStreamingChunk`
 * / `finalizeStreamingToolCall` trio — carries state that is meaningful only
 * within ONE stream and must never be shared. The wire `index` an
 * OpenAI-compatible provider stamps on each argument fragment restarts at 0 for
 * every stream, and after the first fragment a chunk carries nothing else: no
 * id, no name. So a tracker shared by two concurrently streaming tasks — which
 * a headless worker running many tasks per process has — collides on `index`,
 * and the collision does not drop the second stream's fragments: it re-emits
 * them under the FIRST stream's tool-call id, splicing one tool call's
 * arguments character-by-character through the other's. `Task` therefore owns
 * one of these for its lifetime (`Task.nativeToolCallParser`), and a provider
 * that needs to know a tool call ended tracks the ids it saw itself rather than
 * reading another task's assembly state.
 */
/**
 * A single firing of a silent recovery layer (alias coercion, path recovery,
 * etc.). `layerId` names the layer so its hit-rate/correctness can be tracked
 * and the layer retired if it stops earning its keep (audit: tool-call-recovery).
 */
export interface ToolRecoveryRecord {
	layerId: string
	tool: string
	[key: string]: unknown
}

/**
 * A tool call carried the stub escape hatch (`arguments_json`) but its payload
 * was not a JSON object. Distinguished from an ordinary JSON failure so the
 * error handed back to the model names the property it must fix, instead of
 * blaming the outer arguments — which parsed fine, and re-emitting which would
 * reproduce the same failure.
 */
export class StubArgumentsJsonError extends Error {
	constructor(message: string) {
		super(message)
		this.name = "StubArgumentsJsonError"
	}
}

export class NativeToolCallParser {
	/** Stores the last parse error so callers can include specifics in error messages. */
	public static lastParseError: string | null = null

	/** Read and clear the last parse error. */
	public static consumeLastParseError(): string | null {
		const err = this.lastParseError
		this.lastParseError = null
		return err
	}

	/**
	 * Silent recovery-layer firings recorded during the most recent parse, so the
	 * caller (which has model/task context) can emit telemetry for them. The parser
	 * is static and model-agnostic, so it records facts here rather than capturing
	 * telemetry directly — mirroring the {@link lastParseError} pattern. Drained per
	 * parse via {@link consumeRecoveries}.
	 */
	public static lastRecoveries: ToolRecoveryRecord[] = []

	/** Read and clear the recovery-layer firings recorded since the last drain. */
	public static consumeRecoveries(): ToolRecoveryRecord[] {
		const recoveries = this.lastRecoveries
		this.lastRecoveries = []
		return recoveries
	}

	private static recordRecovery(record: ToolRecoveryRecord): void {
		this.lastRecoveries.push(record)
	}

	/**
	 * Per-tool-call argument accumulation for ONE stream (keyed by tool call id).
	 *
	 * Instance state, not static: see the class docstring's "one parser per
	 * task" note. `name` is a string to accommodate dynamic MCP tools
	 * (`mcp--serverName--toolName`).
	 */
	private readonly streamingToolCalls = new Map<
		string,
		{
			id: string
			name: string
			argumentsAccumulator: string
		}
	>()

	/**
	 * Raw chunk tracking for ONE stream, keyed by the wire `index` the provider
	 * assigns to each tool call within that stream.
	 *
	 * The index restarts at 0 for every stream, so this map is only meaningful
	 * scoped to a single stream — hence instance state.
	 */
	private readonly rawChunkTracker = new Map<
		number,
		{
			id: string
			name: string
			hasStarted: boolean
			deltaBuffer: string[]
		}
	>()

	private static coerceOptionalBoolean(value: unknown): boolean | undefined {
		if (typeof value === "boolean") {
			return value
		}
		if (typeof value === "string") {
			const lower = value.trim().toLowerCase()
			if (lower === "true") {
				return true
			}
			if (lower === "false") {
				return false
			}
		}
		return undefined
	}

	/**
	 * Process a raw tool call chunk from the API stream.
	 * Handles tracking, buffering, and emits start/delta/end events.
	 *
	 * This is the entry point for providers that emit tool_call_partial chunks.
	 * Returns an array of events to be processed by the consumer.
	 */
	public processRawChunk(chunk: {
		index: number
		id?: string
		name?: string
		arguments?: string
	}): ToolCallStreamEvent[] {
		const events: ToolCallStreamEvent[] = []
		const { index, id, name, arguments: args } = chunk

		let tracked = this.rawChunkTracker.get(index)

		// Initialize new tool call tracking when we receive an id
		if (id && !tracked) {
			tracked = {
				id,
				name: name || "",
				hasStarted: false,
				deltaBuffer: [],
			}
			this.rawChunkTracker.set(index, tracked)
		}

		if (!tracked) {
			return events
		}

		// Update name if present in chunk and not yet set
		if (name) {
			tracked.name = name
		}

		// Emit start event when we have the name
		if (!tracked.hasStarted && tracked.name) {
			events.push({
				type: "tool_call_start",
				id: tracked.id,
				name: tracked.name,
			})
			tracked.hasStarted = true

			// Flush buffered deltas
			for (const bufferedDelta of tracked.deltaBuffer) {
				events.push({
					type: "tool_call_delta",
					id: tracked.id,
					delta: bufferedDelta,
				})
			}
			tracked.deltaBuffer = []
		}

		// Emit delta event for argument chunks
		if (args) {
			if (tracked.hasStarted) {
				events.push({
					type: "tool_call_delta",
					id: tracked.id,
					delta: args,
				})
			} else {
				tracked.deltaBuffer.push(args)
			}
		}

		return events
	}

	/**
	 * Finalize any remaining tool calls that weren't explicitly ended.
	 * Should be called at the end of stream processing.
	 */
	public finalizeRawChunks(): ToolCallStreamEvent[] {
		const events: ToolCallStreamEvent[] = []

		if (this.rawChunkTracker.size > 0) {
			for (const [, tracked] of this.rawChunkTracker.entries()) {
				if (tracked.hasStarted) {
					events.push({
						type: "tool_call_end",
						id: tracked.id,
					})
				}
			}
			this.rawChunkTracker.clear()
		}

		return events
	}

	/**
	 * Clear this task's raw chunk tracking state.
	 * Should be called when a new API request starts on the SAME task — it must
	 * not be reachable for any other, which is what owning the parser gives.
	 */
	public clearRawChunkState(): void {
		this.rawChunkTracker.clear()
	}

	/**
	 * Start streaming a new tool call.
	 * Initializes tracking for incremental argument parsing.
	 * Accepts string to support both ToolName and dynamic MCP tools (mcp--serverName--toolName).
	 */
	public startStreamingToolCall(id: string, name: string): void {
		this.streamingToolCalls.set(id, {
			id,
			name,
			argumentsAccumulator: "",
		})
	}

	/**
	 * Clear this task's streaming tool call state.
	 * Should be called when a new API request starts on the SAME task, to
	 * prevent leaking accumulators from interrupted streams.
	 */
	public clearAllStreamingToolCalls(): void {
		this.streamingToolCalls.clear()
	}

	/**
	 * Check if there are any active streaming tool calls.
	 * Useful for debugging and testing.
	 */
	public hasActiveStreamingToolCalls(): boolean {
		return this.streamingToolCalls.size > 0
	}

	/**
	 * Process a chunk of JSON arguments for a streaming tool call.
	 * Uses partial-json-parser to extract values from incomplete JSON immediately.
	 * Returns a partial ToolUse with currently parsed parameters.
	 */
	public processStreamingChunk(id: string, chunk: string): ToolUse | null {
		const toolCall = this.streamingToolCalls.get(id)
		if (!toolCall) {
			return null
		}

		// Accumulate the JSON string
		toolCall.argumentsAccumulator += chunk

		// For dynamic MCP tools, we don't return partial updates - wait for final
		const mcpPrefix = MCP_TOOL_PREFIX + MCP_TOOL_SEPARATOR
		if (toolCall.name.startsWith(mcpPrefix)) {
			return null
		}

		// Parse whatever we can from the incomplete JSON!
		// partial-json-parser extracts partial values (strings, arrays, objects) immediately
		try {
			// Resolve tool alias to canonical name
			const resolvedName = resolveToolAlias(toolCall.name) as ToolName

			// A stubbed tool's arguments may arrive JSON-encoded inside
			// `arguments_json`; unwrap leniently so partial rendering sees the same
			// keys a direct-arguments call would. Still-truncated inner JSON yields
			// the wrapper unchanged, which renders as "no arguments yet".
			const partialArgs = NativeToolCallParser.unwrapStubArguments(
				parseJSON(toolCall.argumentsAccumulator),
				resolvedName,
				true,
			)
			NativeToolCallParser.normalizeArgAliases(partialArgs)

			// Preserve original name if it differs from resolved (i.e., it was an alias)
			const originalName = toolCall.name !== resolvedName ? toolCall.name : undefined

			// Create partial ToolUse with extracted values
			return NativeToolCallParser.createPartialToolUse(
				toolCall.id,
				resolvedName,
				partialArgs || {},
				true, // partial
				originalName,
			)
		} catch {
			// Even partial-json-parser can fail on severely malformed JSON
			// Return null and wait for next chunk
			return null
		}
	}

	/**
	 * Finalize a streaming tool call.
	 * Parses the complete JSON and returns the final ToolUse or McpToolUse.
	 */
	public finalizeStreamingToolCall(id: string): ToolUse | McpToolUse | null {
		const toolCall = this.streamingToolCalls.get(id)
		if (!toolCall) {
			NativeToolCallParser.lastParseError = `Unknown streaming tool call ID "${id}" — may have been finalized already or never started`
			return null
		}

		// Parse the complete accumulated JSON
		// Cast to any for the name since parseToolCall handles both ToolName and dynamic MCP tools
		const finalToolUse = NativeToolCallParser.parseToolCall({
			id: toolCall.id,
			name: toolCall.name as ToolName,
			arguments: toolCall.argumentsAccumulator,
		})

		// Clean up streaming state
		this.streamingToolCalls.delete(id)

		return finalToolUse
	}

	/**
	 * Some models (particularly vscode-lm with composite shofer/* models) leak
	 * XML-style <parameter> tags into JSON string values when the parameter
	 * list is complex. This is most commonly observed with apply_diff, where
	 * the model embeds a trailing "\n<parameter name=\"path\" string=\"true\">PATH"
	 * suffix inside the `diff` string value instead of emitting `path` as a
	 * separate JSON key. The JSON is structurally valid ({ "diff": "content" }),
	 * so JSON.parse succeeds, but the `path` guard in the parser switch case
	 * then fails because `args.path` is undefined.
	 *
	 * This helper attempts to recover a `path` from the suffix of a string value
	 * that ends with the proprietary <parameter> leak pattern. Returns the
	 * extracted path and the sanitized string, or null if no leak is detected.
	 */
	private static extractPathFromXMLLeak(value: unknown): { path: string; sanitized: string } | null {
		if (typeof value !== "string") return null
		// Pattern: newline + <parameter name="path" string="true">VALUE at end of string
		// The closing </parameter> may or may not be present.
		// Tolerate corrupted tag prefixes: vscode-lm / deepseek-v4-pro sometimes
		// substitute Unicode box-drawing junk (U+FF5C, U+2BFF, etc.) for the
		// expected "<" and subsequent characters before "parameter".  The .*?
		// quantifier lazily skips any arbitrary bytes between "<" and the
		// literal "parameter" keyword, which is the only anchoring token.
		//
		// Known limitations:
		// - A corrupted prefix that spans multiple lines is not recovered
		//   (no dotAll flag, so "." does not match newlines).  The observed
		//   corruption is single-line, so this is acceptable.
		// - Theoretically, if a diff SEARCH/REPLACE block legitimately ends
		//   with text matching "<parameter name=\"path\" string=\"true\">VALUE",
		//   the recovery could false-match.  In practice the "$" end-of-string
		//   anchor and the ">>>>>>> REPLACE\n" structural barrier make this
		//   extremely unlikely.  No false positives have been observed.
		const match = value.match(/\n<.*?parameter\s+name="path"\s+string="true">([^\n<]+)\s*(?:<\/parameter>)?\s*$/)
		if (!match) return null
		const extractedPath = match[1]!.trim()
		if (!extractedPath) return null
		const sanitized = value.slice(0, match.index!)
		return { path: extractedPath, sanitized }
	}

	/**
	 * Detect whether a diff string value has a leaked `:path` suffix —
	 * the pattern where the model appends "\n:path\nVALUE" after the last
	 * ">>>>>>> REPLACE" barrier instead of emitting `path` as a separate
	 * JSON key. This is a boolean detector (not a recovery extractor) —
	 * it returns true to trigger an actionable rejection that tells the
	 * model exactly what went wrong, so it self-corrects on the next call.
	 *
	 * Observed with: zhipu/glm-5.2 via the shofer proxy.
	 *
	 * The pattern is structurally unambiguous: the ":path" marker appears
	 * after the last ">>>>>>> REPLACE" barrier, which is the structural end
	 * of a well-formed diff. No legitimate diff content follows that barrier.
	 */
	private static detectColonLeak(value: unknown): boolean {
		if (typeof value !== "string") return false
		const lastReplaceIdx = value.lastIndexOf(">>>>>>> REPLACE")
		if (lastReplaceIdx === -1) return false
		const afterReplace = value.slice(lastReplaceIdx)
		// Match: ">>>>>>> REPLACE" followed by optional whitespace/newlines,
		// then ":path", then newline(s), then a non-empty value to end of string.
		return />>>>>>> REPLACE\s*\n:path\s*\n.+$/s.test(afterReplace)
	}

	/**
	 * Unwrap the stub escape hatch: a tool call whose arguments are exactly
	 * `{ arguments_json: "<json object>" }` carries its real arguments inside that
	 * string, and everything downstream — the alias normalizer, the per-tool arg
	 * builders, the missing-field check, a plugin tool's Zod parse, an MCP server's
	 * own validation — must see the UNWRAPPED object. On-demand schema loading
	 * declares the property on every stub because a provider that decodes tool
	 * arguments under a grammar built from the declared schema can emit nothing
	 * else (`prompts/tools/tool-stubs.ts`).
	 *
	 * Applied to EVERY tool call, not only to tools stubbed in this request: a
	 * model that learned the pattern earlier in the conversation keeps using it
	 * after a tool's schema is no longer stubbed, and the parser has no view of
	 * which tier a name was in. That is safe because the trigger is unambiguous —
	 * the property is the SOLE key, its value is a string, and it decodes to a JSON
	 * object. No native, plugin or bundled MCP tool declares a parameter by that
	 * name.
	 *
	 * Three deliberate non-unwraps:
	 * - **alongside other keys** — ambiguous (is it a wrapper or a real argument?),
	 *   so the object passes through untouched and execution-side validation
	 *   speaks;
	 * - **a non-string value** — not the hatch;
	 * - **an empty string** — read as "no arguments", i.e. `{}`, which a zero-arg
	 *   tool may legitimately produce under a constrained decoder; a tool that does
	 *   need arguments then raises its ordinary missing-parameter error.
	 *
	 * @param partial Streaming: the inner string is still arriving, so it is parsed
	 *   leniently and a failure yields the wrapper unchanged rather than an error —
	 *   a half-streamed hatch must render as "nothing decided yet", never as a
	 *   broken call. The authoritative unwrap is the final one.
	 * @throws StubArgumentsJsonError when a complete `arguments_json` is not a JSON
	 *   object, so the model gets an error naming the property rather than one
	 *   blaming the outer arguments, which were well-formed.
	 */
	// eslint-disable-next-line @typescript-eslint/no-explicit-any -- mirrors JSON.parse's `any`; every caller indexes the result by tool-specific keys.
	private static unwrapStubArguments(args: any, toolName: string, partial = false): any {
		if (!args || typeof args !== "object" || Array.isArray(args)) return args

		const keys = Object.keys(args as Record<string, unknown>)
		if (keys.length !== 1 || keys[0] !== STUB_ARGUMENTS_JSON_PARAM) return args

		const encoded = (args as Record<string, unknown>)[STUB_ARGUMENTS_JSON_PARAM]
		if (typeof encoded !== "string") return args
		if (encoded.trim() === "") return {}

		if (partial) {
			try {
				const optimistic = parseJSON(encoded)
				return optimistic && typeof optimistic === "object" && !Array.isArray(optimistic) ? optimistic : args
			} catch {
				return args
			}
		}

		let decoded: unknown
		try {
			decoded = JSON.parse(encoded)
		} catch (error) {
			throw new StubArgumentsJsonError(
				`The '${STUB_ARGUMENTS_JSON_PARAM}' string for tool '${toolName}' is not valid JSON: ` +
					`${error instanceof Error ? error.message : String(error)}. It must contain a JSON OBJECT of this ` +
					`tool's real arguments — e.g. {"${STUB_ARGUMENTS_JSON_PARAM}": "{\\"path\\": \\"src/app.ts\\"}"} — ` +
					`with every inner quote escaped. Re-emit the call with a valid JSON object in ` +
					`'${STUB_ARGUMENTS_JSON_PARAM}', or with the arguments passed directly. Received (truncated): ` +
					`${JSON.stringify(encoded.slice(0, 200))}`,
			)
		}

		if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) {
			throw new StubArgumentsJsonError(
				`The '${STUB_ARGUMENTS_JSON_PARAM}' string for tool '${toolName}' decoded to ` +
					`${Array.isArray(decoded) ? "an array" : `a ${decoded === null ? "null" : typeof decoded}`}, not a ` +
					`JSON object. It must encode an OBJECT mapping this tool's parameter names to their values — ` +
					`e.g. {"${STUB_ARGUMENTS_JSON_PARAM}": "{\\"path\\": \\"src/app.ts\\"}"}. Call describe_tools for ` +
					`the contract if you do not have it.`,
			)
		}

		this.recordRecovery({
			layerId: "stub_arguments_json",
			tool: toolName,
			argCount: Object.keys(decoded as Record<string, unknown>).length,
		})

		return decoded
	}

	/**
	 * Common argument-name aliases that some models emit instead of Shofer's
	 * canonical `path` (e.g. Anthropic/Claude-Code's `file_path`, Cursor's
	 * `target_directory`). Mapped to `path` so a model trained on a different
	 * tool schema still parses. The existing per-tool `?? filePath` fallbacks
	 * stay as a backstop; this centralizes the snake_case variants too.
	 */
	private static readonly PATH_ARG_ALIASES = [
		"directory",
		"file_path",
		"filePath",
		"filepath",
		"target_directory",
		"targetDirectory",
		"directory_path",
		"dir_path",
	]

	/**
	 * Normalize known argument-name aliases onto their canonical Shofer names,
	 * in place. Only fills a canonical field when it is absent (never clobbers an
	 * explicitly-provided value). Applied right after JSON parsing so both the
	 * required-field check and the per-tool arg builders see the canonical name.
	 */
	private static normalizeArgAliases(args: unknown): void {
		if (!args || typeof args !== "object") return
		const a = args as Record<string, unknown>
		if (a.path === undefined) {
			for (const alias of this.PATH_ARG_ALIASES) {
				if (a[alias] !== undefined) {
					a.path = a[alias]
					break
				}
			}
		}
		// Alias Anthropic/Claude naming conventions for delegation/messaging tools.
		// `prompt` (full instructions) → `message` (Shofer canonical name).
		// `description` (short summary) → `title` (optional display label).
		// Only fills when the canonical key is absent, same as PATH_ARG_ALIASES above.
		if (a.message === undefined && a.prompt !== undefined) {
			a.message = a.prompt
		}
		if (a.title === undefined && a.description !== undefined) {
			a.title = a.description
		}
	}

	/**
	 * Compose a `find_files` glob from a (filename) pattern plus an optional
	 * directory. `find_files` runs the pattern through `vscode.RelativePattern`,
	 * where a bare glob like `*.ts` matches the workspace root **only** (not
	 * recursively). Cross-assistant aliases such as Claude Code's `search_file`
	 * supply a `directory` + filename `pattern` and expect a **recursive** search
	 * scoped to that directory — so without composition the call would silently
	 * miss everything in subdirectories. Anchoring the pattern recursively under
	 * the directory (a globstar segment between the dir and the filename pattern)
	 * preserves that intent. When no directory is given the pattern is returned
	 * unchanged (native `find_files` callers keep their exact glob semantics).
	 */
	private static composeFindFilesPattern(pattern: string, dir: unknown): string {
		if (typeof dir !== "string" || dir.trim() === "") return pattern
		const cleanDir = dir.trim().replace(/[/\\]+$/, "")
		if (!cleanDir || cleanDir === ".") return pattern
		// Already absolute or already anchored under the directory → leave as-is.
		if (pattern.startsWith("/") || pattern.startsWith(`${cleanDir}/`)) return pattern
		// Strip a leading `./` and, if the pattern is already recursive (`**/…`),
		// just prefix the directory; otherwise make it recursive under the dir.
		const cleanPattern = pattern.replace(/^\.?[/\\]+/, "")
		return cleanPattern.startsWith("**") ? `${cleanDir}/${cleanPattern}` : `${cleanDir}/**/${cleanPattern}`
	}

	/**
	 * Return the list of required fields that are missing from the parsed
	 * arguments for the given tool. Used by the generic error message in
	 * parseToolCall to tell the model exactly what it forgot.
	 */
	private static missingRequiredFields(toolName: ToolName, args: Record<string, unknown>): string[] {
		const missing: string[] = []
		switch (toolName) {
			case "apply_diff":
				if (args.path === undefined && args.filePath === undefined) missing.push("path")
				if (args.diff === undefined) missing.push("diff")
				break
			case "write_to_file":
				if (args.path === undefined && args.filePath === undefined) missing.push("path")
				if (args.content === undefined) missing.push("content")
				break
			case "execute_command":
				if (args.command === undefined) missing.push("command")
				break
			case "grep_search":
				if (args.path === undefined && args.filePath === undefined) missing.push("path")
				if (args.query === undefined && args.pattern === undefined) missing.push("query")
				break
			case "read_file":
				if (args.path === undefined && args.filePath === undefined) missing.push("path")
				break
			case "sed":
				if (args.path === undefined && args.filePath === undefined) missing.push("path")
				if (args.pattern === undefined) missing.push("pattern")
				if (args.replacement === undefined) missing.push("replacement")
				break
			case "attempt_completion":
				if (args.result === undefined) missing.push("result")
				break
			case "switch_mode":
				if (args.mode_slug === undefined) missing.push("mode_slug")
				if (args.reason === undefined) missing.push("reason")
				break
			case "new_task":
				if (args.mode === undefined) missing.push("mode")
				if (args.message === undefined) missing.push("message")
				break
			default:
				break
		}
		return missing
	}

	private static coerceOptionalNumber(value: unknown): number | undefined {
		if (typeof value === "number" && Number.isFinite(value)) {
			return value
		}
		if (typeof value === "string") {
			const n = Number(value)
			if (Number.isFinite(n)) {
				return n
			}
		}
		return undefined
	}

	/**
	 * Convert raw file entries from API (with line_ranges) to FileEntry objects
	 * (with lineRanges). Handles multiple formats for backward compatibility:
	 *
	 * New tuple format: { path: string, line_ranges: [[1, 50], [100, 150]] }
	 * Object format: { path: string, line_ranges: [{ start: 1, end: 50 }] }
	 * Legacy string format: { path: string, line_ranges: ["1-50"] }
	 *
	 * Returns: { path: string, lineRanges: [{ start: 1, end: 50 }] }
	 */
	private static convertFileEntries(files: unknown[]): FileEntry[] {
		return files.map((file: unknown) => {
			const f = file as Record<string, unknown>
			const entry: FileEntry = { path: f.path as string }
			if (f.line_ranges && Array.isArray(f.line_ranges)) {
				entry.lineRanges = (f.line_ranges as unknown[])
					.map((range: unknown) => {
						// Handle tuple format: [start, end]
						if (Array.isArray(range) && range.length >= 2) {
							return { start: Number(range[0]), end: Number(range[1]) }
						}
						// Handle object format: { start: number, end: number }
						if (typeof range === "object" && range !== null && "start" in range && "end" in range) {
							const r = range as { start: unknown; end: unknown }
							return { start: Number(r.start), end: Number(r.end) }
						}
						// Handle legacy string format: "1-50"
						if (typeof range === "string") {
							const match = range.match(/^(\d+)-(\d+)$/)
							if (match) {
								return { start: parseInt(match[1]!, 10), end: parseInt(match[2]!, 10) }
							}
						}
						return null
					})
					.filter((r): r is { start: number; end: number } => r !== null)
			}
			return entry
		})
	}

	/**
	 * Create a partial ToolUse from currently parsed arguments.
	 * Used during streaming to show progress.
	 * @param originalName - The original tool name as called by the model (if different from canonical name)
	 */
	private static createPartialToolUse(
		id: string,
		name: ToolName,
		// eslint-disable-next-line @typescript-eslint/no-explicit-any
		partialArgs: Record<string, any>,
		partial: boolean,
		originalName?: string,
	): ToolUse | null {
		// Build stringified params for display/partial-progress UI.
		// NOTE: For streaming partial updates, we MUST populate params even for complex types
		// because tool.handlePartial() methods rely on params to show UI updates.
		const params: Partial<Record<ToolParamName, string>> = {}

		// Allow private LM tool params through as well (they aren't in toolParamNames).
		const isExternalTool = isPrivateLmTool(name)

		for (const [key, value] of Object.entries(partialArgs)) {
			if (toolParamNames.includes(key as ToolParamName) || isExternalTool) {
				params[key as ToolParamName] = typeof value === "string" ? value : JSON.stringify(value)
			}
		}

		// Build partial nativeArgs based on what we have so far
		// eslint-disable-next-line @typescript-eslint/no-explicit-any
		let nativeArgs: any = undefined

		// Track if legacy format was used (for telemetry)
		let usedLegacyFormat = false

		switch (name) {
			case "read_file":
				// Check for legacy format first: { files: [...] }
				// Handle both array and stringified array (some models double-stringify)
				if (partialArgs.files !== undefined) {
					let filesArray: unknown[] | null = null

					if (Array.isArray(partialArgs.files)) {
						filesArray = partialArgs.files
					} else if (typeof partialArgs.files === "string") {
						// Handle double-stringified case: files is a string containing JSON array
						try {
							const parsed = JSON.parse(partialArgs.files)
							if (Array.isArray(parsed)) {
								filesArray = parsed
							}
						} catch {
							// Not valid JSON, ignore
						}
					}

					if (filesArray && filesArray.length > 0) {
						usedLegacyFormat = true
						nativeArgs = {
							files: this.convertFileEntries(filesArray),
							_legacyFormat: true as const,
						}
					}
				}
				// New format: { path: "...", mode: "..." }
				// Accept filePath as alias for path (models sometimes hallucinate filePath for read_file)
				if (!nativeArgs && (partialArgs.path !== undefined || partialArgs.filePath !== undefined)) {
					nativeArgs = {
						path: partialArgs.path ?? partialArgs.filePath,
						mode: partialArgs.mode,
						offset: this.coerceOptionalNumber(partialArgs.offset),
						limit: this.coerceOptionalNumber(partialArgs.limit),
						indentation:
							partialArgs.indentation && typeof partialArgs.indentation === "object"
								? {
										anchor_line: this.coerceOptionalNumber(partialArgs.indentation.anchor_line),
										max_levels: this.coerceOptionalNumber(partialArgs.indentation.max_levels),
										max_lines: this.coerceOptionalNumber(partialArgs.indentation.max_lines),
										include_siblings: this.coerceOptionalBoolean(
											partialArgs.indentation.include_siblings,
										),
										include_header: this.coerceOptionalBoolean(
											partialArgs.indentation.include_header,
										),
									}
								: undefined,
					}
				}
				break

			case "attempt_completion":
				if (partialArgs.result) {
					nativeArgs = {
						result: partialArgs.result,
						rating: partialArgs.rating,
						feedback: partialArgs.feedback,
					}
				}
				break

			case "wait":
				// Every param is optional — always emit nativeArgs so the dispatcher
				// does not reject the call as "missing nativeArgs".
				nativeArgs = {
					timeout_sec: this.coerceOptionalNumber(partialArgs.timeout_sec),
					from: Array.isArray(partialArgs.from) ? (partialArgs.from as string[]) : undefined,
					in_reply_to: partialArgs.in_reply_to,
				}
				break

			case "execute_command":
				if (partialArgs.command) {
					nativeArgs = {
						command: partialArgs.command,
						cwd: partialArgs.cwd,
						timeout: partialArgs.timeout,
					}
				}
				break

			case "write_to_file":
				if (partialArgs.path || partialArgs.filePath || partialArgs.content) {
					nativeArgs = {
						path: partialArgs.path ?? partialArgs.filePath,
						content: partialArgs.content,
					}
				}
				break

			case "ask_followup_question":
				if (
					partialArgs.question !== undefined ||
					partialArgs.follow_up !== undefined ||
					partialArgs.form !== undefined
				) {
					nativeArgs = {
						question: partialArgs.question,
						follow_up: Array.isArray(partialArgs.follow_up) ? partialArgs.follow_up : undefined,
						form: Array.isArray(partialArgs.form) ? partialArgs.form : undefined,
					}
				}
				break

			case "apply_diff":
				if (
					partialArgs.path !== undefined ||
					partialArgs.filePath !== undefined ||
					partialArgs.diff !== undefined
				) {
					// No XML-leak path recovery here: we never silently guess the
					// target file from a leaked `<parameter name="path">` suffix. If
					// `path` is genuinely missing, the final parse rejects with
					// actionable feedback (see the apply_diff case in createToolUse).
					const path = (partialArgs.path ?? partialArgs.filePath) as string | undefined
					const diff = partialArgs.diff as string | undefined

					nativeArgs = {
						path,
						diff,
					}
				}
				break

			case "generate_image":
				if (partialArgs.prompt !== undefined || partialArgs.path !== undefined) {
					nativeArgs = {
						prompt: partialArgs.prompt,
						path: partialArgs.path,
						image: partialArgs.image,
					}
				}
				break

			case "run_slash_command":
				if (partialArgs.command !== undefined) {
					nativeArgs = {
						command: partialArgs.command,
						args: partialArgs.args,
					}
				}
				break

			case "skills":
				if (partialArgs.skill !== undefined) {
					nativeArgs = {
						skill: partialArgs.skill,
						args: partialArgs.args,
					}
				}
				break

			case "grep_search":
				if (
					partialArgs.path !== undefined ||
					partialArgs.query !== undefined ||
					partialArgs.pattern !== undefined
				) {
					nativeArgs = {
						path: partialArgs.path,
						query: partialArgs.query ?? partialArgs.pattern,
						fileTypes: partialArgs.fileTypes ?? partialArgs.file_pattern,
						excludePattern: partialArgs.excludePattern,
						isRegex: this.coerceOptionalBoolean(partialArgs.isRegex ?? partialArgs.regex),
						caseSensitive: this.coerceOptionalBoolean(partialArgs.caseSensitive),
						wholeWord: this.coerceOptionalBoolean(partialArgs.wholeWord),
						maxResults: this.coerceOptionalNumber(partialArgs.maxResults),
						contextBefore: this.coerceOptionalNumber(partialArgs.contextBefore),
						contextAfter: this.coerceOptionalNumber(partialArgs.contextAfter),
					}
				}
				break

			case "switch_mode":
				if (partialArgs.mode_slug !== undefined || partialArgs.reason !== undefined) {
					nativeArgs = {
						mode_slug: partialArgs.mode_slug,
						reason: partialArgs.reason,
						task_id: partialArgs.task_id,
					}
				}
				break

			case "update_todo_list":
				if (partialArgs.todos !== undefined) {
					nativeArgs = {
						todos: partialArgs.todos,
					}
				}
				break

			case "set_task_title":
				if (partialArgs.title !== undefined) {
					nativeArgs = {
						title: partialArgs.title,
					}
				}
				break

			case "give_feedback":
				if (partialArgs.feedback !== undefined) {
					nativeArgs = {
						feedback: partialArgs.feedback,
					}
				}
				break

			case "use_mcp_tool":
				if (partialArgs.server_name !== undefined || partialArgs.tool_name !== undefined) {
					nativeArgs = {
						server_name: partialArgs.server_name,
						tool_name: partialArgs.tool_name,
						arguments: partialArgs.arguments,
					}
				}
				break

			case "access_mcp_resource":
				if (partialArgs.server_name !== undefined || partialArgs.uri !== undefined) {
					nativeArgs = {
						server_name: partialArgs.server_name,
						uri: partialArgs.uri,
					}
				}
				break

			case "call_mcp_tool_async":
				if (partialArgs.server_name !== undefined || partialArgs.tool_name !== undefined) {
					nativeArgs = {
						server_name: partialArgs.server_name,
						tool_name: partialArgs.tool_name,
						arguments: partialArgs.arguments,
						source:
							partialArgs.source === "project" || partialArgs.source === "global"
								? partialArgs.source
								: undefined,
					}
				}
				break

			case "check_mcp_call_status":
				if (partialArgs.call_id !== undefined) {
					nativeArgs = {
						call_id: partialArgs.call_id,
					}
				}
				break

			case "wait_for_mcp_call":
				if (partialArgs.call_ids !== undefined) {
					nativeArgs = {
						call_ids: Array.isArray(partialArgs.call_ids) ? partialArgs.call_ids : [partialArgs.call_ids],
						wait: partialArgs.wait === "any" ? "any" : "all",
						timeout: this.coerceOptionalNumber(partialArgs.timeout),
					}
				}
				break

			case "apply_patch":
				if (partialArgs.patch !== undefined) {
					nativeArgs = {
						patch: partialArgs.patch,
					}
				}
				break

			case "search_replace":
				if (
					partialArgs.file_path !== undefined ||
					partialArgs.old_string !== undefined ||
					partialArgs.new_string !== undefined
				) {
					nativeArgs = {
						file_path: partialArgs.file_path,
						old_string: partialArgs.old_string,
						new_string: partialArgs.new_string,
					}
				}
				break

			case "edit":
			case "search_and_replace":
				if (
					partialArgs.file_path !== undefined ||
					partialArgs.old_string !== undefined ||
					partialArgs.new_string !== undefined
				) {
					nativeArgs = {
						file_path: partialArgs.file_path,
						old_string: partialArgs.old_string,
						new_string: partialArgs.new_string,
						replace_all: this.coerceOptionalBoolean(partialArgs.replace_all),
					}
				}
				break

			case "edit_file":
				if (
					partialArgs.file_path !== undefined ||
					partialArgs.old_string !== undefined ||
					partialArgs.new_string !== undefined
				) {
					nativeArgs = {
						file_path: partialArgs.file_path,
						old_string: partialArgs.old_string,
						new_string: partialArgs.new_string,
						expected_replacements: partialArgs.expected_replacements,
					}
				}
				break

			case "list_files":
				if (partialArgs.path !== undefined || partialArgs.filePath !== undefined) {
					nativeArgs = {
						path: partialArgs.path ?? partialArgs.filePath,
						recursive: this.coerceOptionalBoolean(partialArgs.recursive),
					}
				}
				break

			case "new_task":
				if (partialArgs.mode !== undefined || partialArgs.message !== undefined) {
					nativeArgs = {
						mode: partialArgs.mode,
						message: partialArgs.message,
						todos: partialArgs.todos,
						softResultLength: this.coerceOptionalNumber(partialArgs.softResultLength),
						softTimeoutSec: this.coerceOptionalNumber(partialArgs.softTimeoutSec),
						peer_task_ids: Array.isArray(partialArgs.peer_task_ids) ? partialArgs.peer_task_ids : undefined,
						title: partialArgs.title,
					}
				}
				break

			case "check_task_status":
				if (partialArgs.task_id !== undefined) {
					nativeArgs = {
						task_id: partialArgs.task_id,
						include_activity: this.coerceOptionalBoolean(partialArgs.include_activity),
					}
				}
				break

			case "cancel_tasks":
				if (partialArgs.task_ids !== undefined) {
					nativeArgs = {
						task_ids: Array.isArray(partialArgs.task_ids) ? partialArgs.task_ids : [partialArgs.task_ids],
					}
				}
				break

			case "list_background_tasks":
				nativeArgs = {
					scope: partialArgs.scope === "peers" ? "peers" : "children",
				}
				break

			case "describe_tools":
				if (Array.isArray(partialArgs.names)) {
					nativeArgs = {
						names: partialArgs.names,
					}
				}
				break

			case "create_directory":
				if (partialArgs.path !== undefined || partialArgs.filePath !== undefined) {
					nativeArgs = {
						path: partialArgs.path ?? partialArgs.filePath,
					}
				}
				break

			case "create_new_workspace":
				if (
					partialArgs.path !== undefined ||
					partialArgs.filePath !== undefined ||
					partialArgs.name !== undefined
				) {
					nativeArgs = {
						path: partialArgs.path ?? partialArgs.filePath,
						name: partialArgs.name,
						folders: partialArgs.folders,
						openInNewWindow: this.coerceOptionalBoolean(partialArgs.openInNewWindow),
					}
				}
				break

			case "file":
				if (
					partialArgs.subcommand !== undefined ||
					partialArgs.path !== undefined ||
					partialArgs.filePath !== undefined
				) {
					nativeArgs = {
						subcommand: partialArgs.subcommand,
						path: partialArgs.path ?? partialArgs.filePath,
						destination: partialArgs.destination,
						recursive: this.coerceOptionalBoolean(partialArgs.recursive),
					}
				}
				break

			case "fetch_web_page":
				if (partialArgs.urls !== undefined) {
					nativeArgs = {
						urls: partialArgs.urls,
						query: partialArgs.query,
					}
				}
				break

			case "find_files":
				if (partialArgs.pattern !== undefined) {
					nativeArgs = {
						pattern: this.composeFindFilesPattern(partialArgs.pattern, partialArgs.path),
						maxResults: this.coerceOptionalNumber(partialArgs.maxResults),
					}
				}
				break

			case "get_errors":
				nativeArgs = {
					filePaths: partialArgs.filePaths,
				}
				break

			case "get_project_setup_info":
				nativeArgs = {}
				break

				break

			case "insert_edit":
				if (
					partialArgs.path !== undefined ||
					partialArgs.filePath !== undefined ||
					partialArgs.line !== undefined
				) {
					nativeArgs = {
						path: partialArgs.path ?? partialArgs.filePath,
						filePath: partialArgs.filePath,
						line: this.coerceOptionalNumber(partialArgs.line)!,
						column: this.coerceOptionalNumber(partialArgs.column),
						text: partialArgs.text,
					}
				}
				break

			case "list_code_usages":
				if (partialArgs.path !== undefined || partialArgs.filePath !== undefined) {
					nativeArgs = {
						path: partialArgs.path ?? partialArgs.filePath,
						filePath: partialArgs.filePath,
						line: this.coerceOptionalNumber(partialArgs.line)!,
						column: this.coerceOptionalNumber(partialArgs.column)!,
					}
				}
				break

			case "read_project_structure":
				nativeArgs = {
					maxDepth: this.coerceOptionalNumber(partialArgs.maxDepth),
					includeHidden: this.coerceOptionalBoolean(partialArgs.includeHidden),
				}
				break

			case "rename_symbol":
				if (partialArgs.path !== undefined || partialArgs.filePath !== undefined) {
					nativeArgs = {
						path: partialArgs.path ?? partialArgs.filePath,
						filePath: partialArgs.filePath,
						line: this.coerceOptionalNumber(partialArgs.line)!,
						column: this.coerceOptionalNumber(partialArgs.column)!,
						newName: partialArgs.newName,
					}
				}
				break

			case "view_image":
				if (partialArgs.path !== undefined || partialArgs.filePath !== undefined) {
					nativeArgs = {
						path: partialArgs.path ?? partialArgs.filePath,
						filePath: partialArgs.filePath,
					}
				}
				break

			case "lsp_search":
				if (partialArgs.query !== undefined) {
					nativeArgs = {
						query: partialArgs.query,
						maxResults: this.coerceOptionalNumber(partialArgs.maxResults),
					}
				}
				break

			case "read_command_output":
				if (partialArgs.artifact_id !== undefined) {
					nativeArgs = {
						artifact_id: partialArgs.artifact_id,
						search: partialArgs.search,
						offset: this.coerceOptionalNumber(partialArgs.offset),
						limit: this.coerceOptionalNumber(partialArgs.limit),
					}
				}
				break

			case "read_output_channel":
				// All params optional (list mode takes no args) — emit unconditionally.
				nativeArgs = {
					channel: partialArgs.channel,
					search: partialArgs.search,
					severity: partialArgs.severity,
					tail: this.coerceOptionalBoolean(partialArgs.tail),
					offset: this.coerceOptionalNumber(partialArgs.offset),
					limit: this.coerceOptionalNumber(partialArgs.limit),
				}
				break

			case "sed":
				if (partialArgs.path !== undefined || partialArgs.filePath !== undefined) {
					nativeArgs = {
						path: partialArgs.path ?? partialArgs.filePath,
						pattern: partialArgs.pattern,
						replacement: partialArgs.replacement,
						isRegex: this.coerceOptionalBoolean(partialArgs.isRegex),
						global: this.coerceOptionalBoolean(partialArgs.global),
					}
				}
				break

			case "send_message":
				if (partialArgs.to !== undefined || partialArgs.body !== undefined) {
					nativeArgs = {
						to: partialArgs.to,
						body: partialArgs.body,
						kind: partialArgs.kind as "notification" | "request" | undefined,
						subject: partialArgs.subject,
						timeout_sec: this.coerceOptionalNumber(partialArgs.timeout_sec),
						wake: this.coerceOptionalBoolean(partialArgs.wake),
					}
				}
				break

			case "reply":
				if (Array.isArray(partialArgs.replies)) {
					nativeArgs = { replies: partialArgs.replies as Array<{ message_id: string; body: string }> }
				}
				break

			default:
				if (isPrivateLmTool(name)) {
					// Private LM tools: pass partial args through as nativeArgs
					// so the tool handler can process them once the call is complete.
					nativeArgs = partialArgs
				}
				break
		}

		const result: ToolUse = {
			type: "tool_use" as const,
			name,
			params,
			partial,
			nativeArgs,
		}

		// Preserve original name for API history when an alias was used
		if (originalName) {
			result.originalName = originalName
		}

		// Track legacy format usage for telemetry
		if (usedLegacyFormat) {
			result.usedLegacyFormat = true
		}

		return result
	}

	/**
	 * Convert a native tool call chunk to a ToolUse object.
	 *
	 * @param toolCall - The native tool call from the API stream
	 * @returns A properly typed ToolUse object
	 */
	public static parseToolCall<TName extends ToolName>(toolCall: {
		id: string
		name: TName
		arguments: string
	}): ToolUse<TName> | McpToolUse | null {
		// Check if this is a dynamic MCP tool (mcp--serverName--toolName)
		// Also handle models that output underscores instead of hyphens (mcp__serverName__toolName)
		const mcpPrefix = MCP_TOOL_PREFIX + MCP_TOOL_SEPARATOR

		if (typeof toolCall.name === "string") {
			// Normalize the tool name to handle models that output underscores instead of hyphens
			const normalizedName = normalizeMcpToolName(toolCall.name)
			if (normalizedName.startsWith(mcpPrefix)) {
				// Pass the original tool call but with normalized name for parsing
				return this.parseDynamicMcpTool({ ...toolCall, name: normalizedName })
			}
		}

		// Resolve tool alias to canonical name
		const resolvedName = resolveToolAlias(toolCall.name as string) as TName

		// Validate tool name (after alias resolution).
		// Private provider tools are discovered at build time and filtered by mode;
		// allow them through.
		if (
			!toolNames.includes(resolvedName as ToolName) &&
			!customToolRegistry.has(resolvedName) &&
			!isPrivateLmTool(resolvedName)
		) {
			// Compute the closest known tool name via simple Levenshtein
			// distance so we can suggest a correction in the error feedback.
			// Skip private/external tool names — suggest only native tools.
			const suggestion = findClosestToolName(
				resolvedName as string,
				toolNames.filter((t) => !t.startsWith("mcp")),
			)
			const hint = suggestion ? ` Did you mean '${suggestion}'?` : ""
			this.lastParseError =
				`Unknown tool '${resolvedName}'.` +
				hint +
				` Available tools: ${toolNames
					.filter((t) => !t.startsWith("mcp"))
					.sort()
					.join(", ")}.`

			webviewLog.error(`Invalid tool name: ${toolCall.name} (resolved: ${resolvedName})`)
			webviewLog.error(`Valid tool names:`, toolNames)
			return null
		}

		try {
			// Parse the arguments JSON string, then unwrap the stub escape hatch so
			// everything below — params, the typed builders, the required-field check,
			// and every execution-side validator — sees the real arguments.
			const args = this.unwrapStubArguments(
				toolCall.arguments === "" ? {} : JSON.parse(toolCall.arguments),
				resolvedName,
			)
			this.normalizeArgAliases(args)

			// Build stringified params for display/logging.
			// Tool execution MUST use nativeArgs (typed) and does not support legacy fallbacks.
			const params: Partial<Record<ToolParamName, string>> = {}

			for (const [key, value] of Object.entries(args)) {
				// Validate parameter name — skip for external LM tools whose
				// parameter schemas are defined by the registering extension.
				if (
					!toolParamNames.includes(key as ToolParamName) &&
					!customToolRegistry.has(resolvedName) &&
					!isPrivateLmTool(resolvedName)
				) {
					webviewLog.warn(
						`Unknown parameter '${key}' for tool '${resolvedName}' (check the tool schema for valid params)`,
					)
					continue
				}

				// Convert to string for legacy params format
				const stringValue = typeof value === "string" ? value : JSON.stringify(value)
				params[key as ToolParamName] = stringValue
			}

			// Build typed nativeArgs for tool execution.
			// Each case validates the minimum required parameters and constructs a properly typed
			// nativeArgs object. If validation fails, we treat the tool call as invalid and fail fast.
			let nativeArgs: NativeArgsFor<TName> | undefined = undefined

			// Track if legacy format was used (for telemetry)
			let usedLegacyFormat = false

			switch (resolvedName) {
				case "read_file":
					// Check for legacy format first: { files: [...] }
					// Handle both array and stringified array (some models double-stringify)
					if (args.files !== undefined) {
						let filesArray: unknown[] | null = null

						if (Array.isArray(args.files)) {
							filesArray = args.files
						} else if (typeof args.files === "string") {
							// Handle double-stringified case: files is a string containing JSON array
							try {
								const parsed = JSON.parse(args.files)
								if (Array.isArray(parsed)) {
									filesArray = parsed
								}
							} catch {
								// Not valid JSON, ignore
							}
						}

						if (filesArray && filesArray.length > 0) {
							usedLegacyFormat = true
							nativeArgs = {
								files: this.convertFileEntries(filesArray),
								_legacyFormat: true as const,
							} as NativeArgsFor<TName>
						}
					}
					// New format: { path: "...", mode: "..." }
					// Accept filePath as alias for path (models sometimes hallucinate filePath for read_file)
					if (!nativeArgs && (args.path !== undefined || args.filePath !== undefined)) {
						nativeArgs = {
							path: args.path ?? args.filePath,
							mode: args.mode,
							offset: this.coerceOptionalNumber(args.offset),
							limit: this.coerceOptionalNumber(args.limit),
							indentation:
								args.indentation && typeof args.indentation === "object"
									? {
											anchor_line: this.coerceOptionalNumber(args.indentation.anchor_line),
											max_levels: this.coerceOptionalNumber(args.indentation.max_levels),
											max_lines: this.coerceOptionalNumber(args.indentation.max_lines),
											include_siblings: this.coerceOptionalBoolean(
												args.indentation.include_siblings,
											),
											include_header: this.coerceOptionalBoolean(args.indentation.include_header),
										}
									: undefined,
						} as NativeArgsFor<TName>
					}
					break

				case "attempt_completion":
					if (args.result) {
						nativeArgs = {
							result: args.result,
							rating: args.rating,
							feedback: args.feedback,
						} as NativeArgsFor<TName>
					}
					break

				case "wait":
					// Every param is optional — always emit nativeArgs so the dispatcher
					// does not reject the call as "missing nativeArgs".
					nativeArgs = {
						timeout_sec: this.coerceOptionalNumber(args.timeout_sec),
						from: Array.isArray(args.from) ? (args.from as string[]) : undefined,
						in_reply_to: args.in_reply_to,
					} as NativeArgsFor<TName>
					break

				case "execute_command":
					if (args.command) {
						nativeArgs = {
							command: args.command,
							cwd: args.cwd,
							timeout: args.timeout,
						} as NativeArgsFor<TName>
					}
					break

				case "apply_diff":
					if (args.diff !== undefined) {
						const path = args.path ?? (args.filePath as string | undefined)
						const diff = args.diff as string

						// Some models leak a <parameter name="path"> tag into the `diff`
						// value instead of emitting `path` as a separate key. We do NOT
						// silently guess the target file from that leaked suffix and apply
						// a diff to the guessed path — a wrong guess is a confidently-wrong
						// edit to the wrong file. Reject loudly with actionable feedback so
						// the model re-sends a clean call; a retry beats a guessed mutation.
						if (path === undefined && this.extractPathFromXMLLeak(diff)) {
							this.recordRecovery({ layerId: "apply_diff_xml_leak", tool: "apply_diff", rejected: true })
							throw new Error(
								`[NativeToolCallParser] apply_diff is missing the required \`path\` parameter, and a ` +
									`\`<parameter name="path">\` tag appears to have leaked into the \`diff\` value. ` +
									`Re-send apply_diff with \`path\` as a separate parameter and a clean \`diff\` ` +
									`(SEARCH/REPLACE blocks only, no XML parameter tags).`,
							)
						}

						// Some models (notably zhipu/glm-5.2) leak the `path`
						// parameter into the `diff` string value as a trailing
						// "\n:path\nVALUE" suffix instead of emitting `path` as a
						// separate JSON key. The JSON is valid ({ "diff": "...\n:path\nVALUE" }),
						// so JSON.parse succeeds, but `path` is missing as a key.
						// Reject with actionable feedback so the model self-corrects
						// on the next call — same approach as the XML-leak above.
						if (path === undefined && this.detectColonLeak(diff)) {
							this.recordRecovery({
								layerId: "apply_diff_colon_leak",
								tool: "apply_diff",
								rejected: true,
							})
							throw new Error(
								`[NativeToolCallParser] apply_diff is missing the required \`path\` parameter, and a ` +
									`\`:path\` suffix appears to have leaked into the \`diff\` value. ` +
									`The \`diff\` value must contain ONLY SEARCH/REPLACE blocks. ` +
									`Re-send apply_diff with \`path\` as a separate JSON key (e.g., {"path": "src/file.ts", "diff": "..."}) ` +
									`and a clean \`diff\` (SEARCH/REPLACE blocks only, no \`:path\` suffix).`,
							)
						}

						if (path !== undefined) {
							nativeArgs = {
								path,
								diff,
							} as NativeArgsFor<TName>
						}
					}
					break

				case "edit":
				case "search_and_replace":
					if (
						args.file_path !== undefined &&
						args.old_string !== undefined &&
						args.new_string !== undefined
					) {
						nativeArgs = {
							file_path: args.file_path,
							old_string: args.old_string,
							new_string: args.new_string,
							replace_all: this.coerceOptionalBoolean(args.replace_all),
						} as NativeArgsFor<TName>
					}
					break

				case "ask_followup_question":
					// follow_up and form are each optional (provide either); a form
					// presents typed input widgets. Build nativeArgs when the question
					// plus at least one answer channel is present. Passing form through
					// is required — omitting it drops the widgets and the handler reports
					// a missing follow_up.
					if (args.question !== undefined && (args.follow_up !== undefined || args.form !== undefined)) {
						nativeArgs = {
							question: args.question,
							follow_up: args.follow_up,
							form: args.form,
						} as NativeArgsFor<TName>
					}
					break

				case "generate_image":
					if (args.prompt !== undefined && args.path !== undefined) {
						nativeArgs = {
							prompt: args.prompt,
							path: args.path,
							image: args.image,
						} as NativeArgsFor<TName>
					}
					break

				case "run_slash_command":
					if (args.command !== undefined) {
						nativeArgs = {
							command: args.command,
							args: args.args,
						} as NativeArgsFor<TName>
					}
					break

				case "skills":
					if (args.skill !== undefined) {
						nativeArgs = {
							skill: args.skill,
							args: args.args,
						} as NativeArgsFor<TName>
					}
					break

				case "grep_search":
					if (args.path !== undefined && (args.query !== undefined || args.pattern !== undefined)) {
						nativeArgs = {
							path: args.path,
							query: args.query ?? args.pattern,
							fileTypes: args.fileTypes ?? args.file_pattern,
							excludePattern: args.excludePattern,
							isRegex: this.coerceOptionalBoolean(args.isRegex ?? args.regex) ?? true,
							caseSensitive: this.coerceOptionalBoolean(args.caseSensitive) ?? false,
							wholeWord: this.coerceOptionalBoolean(args.wholeWord) ?? false,
							maxResults: this.coerceOptionalNumber(args.maxResults),
							contextBefore: this.coerceOptionalNumber(args.contextBefore),
							contextAfter: this.coerceOptionalNumber(args.contextAfter),
						} as NativeArgsFor<TName>
					}
					break

				case "switch_mode":
					if (args.mode_slug !== undefined && args.reason !== undefined) {
						nativeArgs = {
							mode_slug: args.mode_slug,
							reason: args.reason,
							task_id: args.task_id,
						} as NativeArgsFor<TName>
					}
					break

				case "update_todo_list":
					if (args.todos !== undefined) {
						nativeArgs = {
							todos: args.todos,
						} as NativeArgsFor<TName>
					}
					break

				case "set_task_title":
					if (args.title !== undefined) {
						nativeArgs = {
							title: args.title,
						} as NativeArgsFor<TName>
					}
					break

				case "give_feedback":
					if (args.feedback !== undefined) {
						nativeArgs = {
							feedback: args.feedback,
						} as NativeArgsFor<TName>
					}
					break

				case "read_command_output":
					if (args.artifact_id !== undefined) {
						nativeArgs = {
							artifact_id: args.artifact_id,
							search: args.search,
							offset: args.offset,
							limit: args.limit,
						} as NativeArgsFor<TName>
					}
					break

				case "read_output_channel":
					// All params optional (list mode takes no args) — emit unconditionally.
					nativeArgs = {
						channel: args.channel,
						search: args.search,
						severity: args.severity,
						tail: this.coerceOptionalBoolean(args.tail),
						offset: this.coerceOptionalNumber(args.offset),
						limit: this.coerceOptionalNumber(args.limit),
					} as NativeArgsFor<TName>
					break

				case "write_to_file":
					if ((args.path !== undefined || args.filePath !== undefined) && args.content !== undefined) {
						nativeArgs = {
							path: args.path ?? args.filePath,
							content: args.content,
						} as NativeArgsFor<TName>
					}
					break

				case "use_mcp_tool":
					if (args.server_name !== undefined && args.tool_name !== undefined) {
						nativeArgs = {
							server_name: args.server_name,
							tool_name: args.tool_name,
							arguments: args.arguments,
						} as NativeArgsFor<TName>
					}
					break

				case "access_mcp_resource":
					if (args.server_name !== undefined && args.uri !== undefined) {
						nativeArgs = {
							server_name: args.server_name,
							uri: args.uri,
						} as NativeArgsFor<TName>
					}
					break

				case "call_mcp_tool_async":
					if (args.server_name !== undefined && args.tool_name !== undefined) {
						nativeArgs = {
							server_name: args.server_name,
							tool_name: args.tool_name,
							arguments: args.arguments,
							source: args.source === "project" || args.source === "global" ? args.source : undefined,
						} as NativeArgsFor<TName>
					}
					break

				case "check_mcp_call_status":
					if (args.call_id !== undefined) {
						nativeArgs = {
							call_id: args.call_id,
						} as NativeArgsFor<TName>
					}
					break

				case "wait_for_mcp_call":
					if (args.call_ids !== undefined) {
						nativeArgs = {
							call_ids: Array.isArray(args.call_ids) ? args.call_ids : [args.call_ids],
							wait: args.wait === "any" ? "any" : "all",
							timeout: this.coerceOptionalNumber(args.timeout),
						} as NativeArgsFor<TName>
					}
					break

				case "apply_patch":
					if (args.patch !== undefined) {
						nativeArgs = {
							patch: args.patch,
						} as NativeArgsFor<TName>
					}
					break

				case "search_replace":
					if (
						args.file_path !== undefined &&
						args.old_string !== undefined &&
						args.new_string !== undefined
					) {
						nativeArgs = {
							file_path: args.file_path,
							old_string: args.old_string,
							new_string: args.new_string,
						} as NativeArgsFor<TName>
					}
					break

				case "edit_file":
					if (
						args.file_path !== undefined &&
						args.old_string !== undefined &&
						args.new_string !== undefined
					) {
						nativeArgs = {
							file_path: args.file_path,
							old_string: args.old_string,
							new_string: args.new_string,
							expected_replacements: args.expected_replacements,
						} as NativeArgsFor<TName>
					}
					break

				case "list_files":
					if (args.path !== undefined || args.filePath !== undefined) {
						nativeArgs = {
							path: args.path ?? args.filePath,
							recursive: this.coerceOptionalBoolean(args.recursive),
						} as NativeArgsFor<TName>
					}
					break

				case "new_task":
					if (args.mode !== undefined && args.message !== undefined) {
						nativeArgs = {
							mode: args.mode,
							message: args.message,
							todos: args.todos,
							softResultLength: this.coerceOptionalNumber(args.softResultLength),
							softTimeoutSec: this.coerceOptionalNumber(args.softTimeoutSec),
							peer_task_ids: Array.isArray(args.peer_task_ids) ? args.peer_task_ids : undefined,
							title: args.title,
						} as NativeArgsFor<TName>
					}
					break

				case "check_task_status":
					if (args.task_id !== undefined) {
						nativeArgs = {
							task_id: args.task_id,
							include_activity: this.coerceOptionalBoolean(args.include_activity),
						} as NativeArgsFor<TName>
					}
					break

				case "cancel_tasks":
					if (args.task_ids !== undefined) {
						nativeArgs = {
							task_ids: Array.isArray(args.task_ids) ? args.task_ids : [args.task_ids],
						} as NativeArgsFor<TName>
					}
					break

				case "list_background_tasks":
					nativeArgs = {
						scope: args.scope === "peers" ? "peers" : "children",
					} as NativeArgsFor<TName>
					break

				// Emitted unconditionally: a call with no usable `names` must reach the
				// handler, which raises the missing-parameter error the model can act
				// on. Leaving nativeArgs unset would instead trip the dispatcher's
				// "missing nativeArgs" rejection, which reads as a provider error.
				case "describe_tools":
					nativeArgs = {
						names: Array.isArray(args.names) ? args.names : [],
					} as NativeArgsFor<TName>
					break

				case "create_directory":
					if (args.path !== undefined || args.filePath !== undefined) {
						nativeArgs = {
							path: args.path ?? args.filePath,
						} as NativeArgsFor<TName>
					}
					break

				case "create_new_workspace":
					if ((args.path !== undefined || args.filePath !== undefined) && args.name !== undefined) {
						nativeArgs = {
							path: args.path ?? args.filePath,
							name: args.name,
							folders: args.folders,
							openInNewWindow: this.coerceOptionalBoolean(args.openInNewWindow),
						} as NativeArgsFor<TName>
					}
					break

				case "file":
					if (args.subcommand !== undefined && (args.path !== undefined || args.filePath !== undefined)) {
						nativeArgs = {
							subcommand: args.subcommand,
							path: args.path ?? args.filePath,
							destination: args.destination,
							recursive: this.coerceOptionalBoolean(args.recursive),
						} as NativeArgsFor<TName>
					}
					break

				case "fetch_web_page":
					if (args.urls !== undefined) {
						nativeArgs = {
							urls: args.urls,
							query: args.query,
						} as NativeArgsFor<TName>
					}
					break

				case "find_files":
					if (args.pattern !== undefined) {
						nativeArgs = {
							// Anchor under a supplied directory (e.g. cross-assistant
							// `search_file` passes `path` + filename `pattern`) so the
							// search is recursive within that scope rather than a
							// root-only glob.
							pattern: this.composeFindFilesPattern(args.pattern, args.path),
							maxResults: this.coerceOptionalNumber(args.maxResults),
						} as NativeArgsFor<TName>
					}
					break

				case "get_errors":
					nativeArgs = {
						filePaths: args.filePaths,
					} as NativeArgsFor<TName>
					break

				case "get_project_setup_info":
					nativeArgs = {} as NativeArgsFor<TName>
					break

					break

				case "insert_edit":
					if (
						(args.path !== undefined || args.filePath !== undefined) &&
						args.line !== undefined &&
						args.text !== undefined
					) {
						nativeArgs = {
							path: args.path ?? args.filePath,
							filePath: args.filePath,
							line: this.coerceOptionalNumber(args.line)!,
							column: this.coerceOptionalNumber(args.column),
							text: args.text,
						} as NativeArgsFor<TName>
					}
					break

				case "list_code_usages":
					if (
						(args.path !== undefined || args.filePath !== undefined) &&
						args.line !== undefined &&
						args.column !== undefined
					) {
						nativeArgs = {
							path: args.path ?? args.filePath,
							filePath: args.filePath,
							line: this.coerceOptionalNumber(args.line)!,
							column: this.coerceOptionalNumber(args.column)!,
						} as NativeArgsFor<TName>
					}
					break

				case "read_project_structure":
					nativeArgs = {
						maxDepth: this.coerceOptionalNumber(args.maxDepth),
						includeHidden: this.coerceOptionalBoolean(args.includeHidden),
					} as NativeArgsFor<TName>
					break

				case "rename_symbol":
					if (
						(args.path !== undefined || args.filePath !== undefined) &&
						args.line !== undefined &&
						args.column !== undefined &&
						args.newName !== undefined
					) {
						nativeArgs = {
							path: args.path ?? args.filePath,
							filePath: args.filePath,
							line: this.coerceOptionalNumber(args.line)!,
							column: this.coerceOptionalNumber(args.column)!,
							newName: args.newName,
						} as NativeArgsFor<TName>
					}
					break

				case "view_image":
					if (args.path !== undefined || args.filePath !== undefined) {
						nativeArgs = {
							path: args.path ?? args.filePath,
							filePath: args.filePath,
						} as NativeArgsFor<TName>
					}
					break

				case "lsp_search":
					if (args.query !== undefined) {
						nativeArgs = {
							query: args.query,
							maxResults: this.coerceOptionalNumber(args.maxResults),
						} as NativeArgsFor<TName>
					}
					break

				case "send_message":
					if (args.to !== undefined && args.body !== undefined) {
						nativeArgs = {
							to: args.to,
							body: args.body,
							kind: args.kind as "notification" | "request" | undefined,
							subject: args.subject,
							timeout_sec: this.coerceOptionalNumber(args.timeout_sec),
							wake: this.coerceOptionalBoolean(args.wake),
						} as NativeArgsFor<TName>
					}
					break

				case "reply":
					// The batch is the whole contract — an item-less call is rejected by
					// the handler, not silently turned into a no-op here.
					if (Array.isArray(args.replies)) {
						nativeArgs = {
							replies: args.replies as Array<{ message_id: string; body: string }>,
						} as NativeArgsFor<TName>
					}
					break

				case "sed":
					if (
						(args.path !== undefined || args.filePath !== undefined) &&
						args.pattern !== undefined &&
						args.replacement !== undefined
					) {
						nativeArgs = {
							path: args.path ?? args.filePath,
							pattern: args.pattern,
							replacement: args.replacement,
							isRegex: this.coerceOptionalBoolean(args.isRegex),
							global: this.coerceOptionalBoolean(args.global),
						} as NativeArgsFor<TName>
					}
					break

				default:
					if (customToolRegistry.has(resolvedName)) {
						nativeArgs = args as NativeArgsFor<TName>
					} else if (isPrivateLmTool(resolvedName)) {
						// External LM tools: pass raw arguments through.
						// The actual schema validation is handled by the tool's
						// registered inputSchema when invoked via vscode.lm.invokeTool.
						nativeArgs = args as NativeArgsFor<TName>
					}

					break
			}

			// Native-only: core tools must always have typed nativeArgs.
			// External tools pass raw args and are validated by the tool's own schema.
			// If we couldn't construct it, the model produced an invalid tool call payload.
			if (!nativeArgs && !customToolRegistry.has(resolvedName) && !isPrivateLmTool(resolvedName)) {
				// Identify which required fields are missing so the model can fix the call.
				const missingFields = this.missingRequiredFields(resolvedName, args)
				const receivedSnippet = JSON.stringify(args).slice(0, 500)
				throw new Error(
					`[NativeToolCallParser] Invalid arguments for tool '${resolvedName}'. ` +
						`Native tool calls require a valid JSON payload matching the tool schema. ` +
						(missingFields.length > 0 ? `Missing required field(s): ${missingFields.join(", ")}. ` : "") +
						`Received (truncated): ${receivedSnippet}`,
				)
			}

			const result: ToolUse<TName> = {
				type: "tool_use" as const,
				name: resolvedName,
				params,
				partial: false, // Native tool calls are always complete when yielded
				nativeArgs,
			}

			// Preserve original name for API history when an alias was used
			if (toolCall.name !== resolvedName) {
				result.originalName = toolCall.name
			}

			// Track legacy format usage for telemetry
			if (usedLegacyFormat) {
				result.usedLegacyFormat = true
			}

			return result
		} catch (error) {
			// The outer arguments parsed; it is the hatch's payload that did not. Hand
			// back the error that names it — the generic "arguments are not valid JSON"
			// below would send the model to fix bytes that were already correct.
			if (error instanceof StubArgumentsJsonError) {
				this.lastParseError = error.message
				webviewLog.error(`Failed to parse ${STUB_ARGUMENTS_JSON_PARAM} for '${resolvedName}': ${error.message}`)
				return null
			}

			const rawError = error instanceof Error ? error.message : String(error)

			// Build an actionable error message that helps the LLM understand
			// what went wrong and how to fix it. The raw V8 JSON.parse error
			// (e.g. "Expected ':' after property name in JSON at position 7")
			// is cryptic on its own — we add context about which tool failed,
			// a snippet of the malformed arguments, and explicit retry guidance.
			const argSnippet = toolCall.arguments.slice(0, 200)
			const argLen = toolCall.arguments.length
			this.lastParseError =
				`The arguments for tool '${resolvedName}' are not valid JSON: ${rawError}.` +
				` Received ${argLen} character(s) of arguments` +
				(argLen > 200 ? ` (showing first 200)` : "") +
				`: ${JSON.stringify(argSnippet)}` +
				`. Re-emit the tool call with properly formatted JSON arguments` +
				` — ensure all string values are properly quoted and escaped,` +
				` all key-value pairs are separated by colons, and the entire` +
				` arguments object is a single valid JSON document.`

			webviewLog.error(`Failed to parse tool call arguments: ${rawError}`)
			webviewLog.error(`Tool call: ${JSON.stringify(toolCall, null, 2)}`)
			return null
		}
	}

	/**
	 * Parse dynamic MCP tools (named mcp--serverName--toolName).
	 * These are generated dynamically by getMcpServerTools() and are returned
	 * as McpToolUse objects that preserve the original tool name.
	 */
	public static parseDynamicMcpTool(toolCall: { id: string; name: string; arguments: string }): McpToolUse | null {
		try {
			// Parse the arguments - these are the actual tool arguments passed directly,
			// unless the model used the stub escape hatch, in which case the real ones
			// are JSON-encoded inside it and the SERVER must be handed those.
			const args = this.unwrapStubArguments(JSON.parse(toolCall.arguments || "{}"), toolCall.name)

			// Normalize the tool name to handle models that output underscores instead of hyphens
			// e.g., mcp__serverName__toolName -> mcp--serverName--toolName
			const normalizedName = normalizeMcpToolName(toolCall.name)

			// Extract server_name and tool_name from the tool name itself
			// Format: mcp--serverName--toolName (using -- separator)
			const parsed = parseMcpToolName(normalizedName)
			if (!parsed) {
				webviewLog.error(
					`Invalid dynamic MCP tool name format: ${toolCall.name} (normalized: ${normalizedName})`,
				)
				return null
			}

			const { serverName, toolName } = parsed

			const result: McpToolUse = {
				type: "mcp_tool_use" as const,
				id: toolCall.id,
				// Keep the original tool name (e.g., "mcp--serverName--toolName") for API history
				name: toolCall.name,
				serverName,
				toolName,
				arguments: args,
				partial: false,
			}

			return result
		} catch (error) {
			// An MCP call is the one path whose failure carries no other diagnosis, so
			// record the hatch error for the caller to hand back to the model.
			if (error instanceof StubArgumentsJsonError) {
				this.lastParseError = error.message
			}
			webviewLog.error(`Failed to parse dynamic MCP tool:`, error)
			return null
		}
	}
}