feat: add backward compatibility for legacy read_file format

- Restore convertFileEntries() function in NativeToolCallParser
- Detect and handle both old { files: [...] } and new { path, mode, ... } formats
- Handle double-stringified JSON from models (files as string vs array)
- Add executeLegacy() method in ReadFileTool for multi-file batch processing
- Add READ_FILE_LEGACY_FORMAT_USED telemetry event
- Add console.warn indicator when legacy format is detected (for testing)
- Add 7 new tests for backward compatibility scenarios
- Add legacy param names (files, line_ranges) to toolParamNames

Author: hannesrudolph

packages/types/src/telemetry.ts

@@ -73,6 +73,7 @@ export enum TelemetryEventName {
 	CODE_INDEX_ERROR = "Code Index Error",
 	TELEMETRY_SETTINGS_CHANGED = "Telemetry Settings Changed",
 	MODEL_CACHE_EMPTY_RESPONSE = "Model Cache Empty Response",
+	READ_FILE_LEGACY_FORMAT_USED = "Read File Legacy Format Used",
 }
 
 /**
@@ -203,6 +204,7 @@ export const rooCodeTelemetryEventSchema = z.discriminatedUnion("type", [
 			TelemetryEventName.TAB_SHOWN,
 			TelemetryEventName.MODE_SETTINGS_CHANGED,
 			TelemetryEventName.CUSTOM_MODE_CREATED,
+			TelemetryEventName.READ_FILE_LEGACY_FORMAT_USED,
 		]),
 		properties: telemetryPropertiesSchema,
 	}),

packages/types/src/tool-params.ts

@@ -26,7 +26,7 @@ export interface IndentationParams {
 }
 
 /**
- * Parameters for the read_file tool.
+ * Parameters for the read_file tool (new format).
  *
  * NOTE: This is the canonical, single-file-per-call shape.
  */
@@ -43,6 +43,55 @@ export interface ReadFileParams {
 	indentation?: IndentationParams
 }
 
+// ─── Legacy Format Types (Backward Compatibility) ─────────────────────────────
+
+/**
+ * Line range specification for legacy read_file format.
+ * Represents a contiguous range of lines [start, end] (1-based, inclusive).
+ */
+export interface LineRange {
+	start: number
+	end: number
+}
+
+/**
+ * File entry for legacy read_file format.
+ * Supports reading multiple disjoint line ranges from a single file.
+ */
+export interface FileEntry {
+	/** Path to the file, relative to workspace */
+	path: string
+	/** Optional list of line ranges to read (if omitted, reads entire file) */
+	lineRanges?: LineRange[]
+}
+
+/**
+ * Legacy parameters for the read_file tool (pre-refactor format).
+ * Supports reading multiple files in a single call with optional line ranges.
+ *
+ * @deprecated Use ReadFileParams instead. This format is maintained for
+ * backward compatibility with existing chat histories.
+ */
+export interface LegacyReadFileParams {
+	/** Array of file entries to read */
+	files: FileEntry[]
+	/** Discriminant flag for type narrowing */
+	_legacyFormat: true
+}
+
+/**
+ * Union type for read_file tool parameters.
+ * Supports both new single-file format and legacy multi-file format.
+ */
+export type ReadFileToolParams = ReadFileParams | LegacyReadFileParams
+
+/**
+ * Type guard to check if params are in legacy format.
+ */
+export function isLegacyReadFileParams(params: ReadFileToolParams): params is LegacyReadFileParams {
+	return "_legacyFormat" in params && params._legacyFormat === true
+}
+
 export interface Coordinate {
 	x: number
 	y: number

src/core/assistant-message/NativeToolCallParser.ts

@@ -1,6 +1,6 @@
 import { parseJSON } from "partial-json"
 
-import { type ToolName, toolNames } from "@roo-code/types"
+import { type ToolName, toolNames, type FileEntry } from "@roo-code/types"
 import { customToolRegistry } from "@roo-code/core"
 
 import {
@@ -326,6 +326,47 @@ export class NativeToolCallParser {
 		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.
@@ -352,9 +393,40 @@ export class NativeToolCallParser {
 		// Build partial nativeArgs based on what we have so far
 		let nativeArgs: any = undefined
 
+		// Track if legacy format was used (for telemetry)
+		let usedLegacyFormat = false
+
 		switch (name) {
 			case "read_file":
-				if (partialArgs.path !== undefined) {
+				// 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: "..." }
+				if (!nativeArgs && partialArgs.path !== undefined) {
 					nativeArgs = {
 						path: partialArgs.path,
 						mode: partialArgs.mode,
@@ -589,6 +661,11 @@ export class NativeToolCallParser {
 			result.originalName = originalName
 		}
 
+		// Track legacy format usage for telemetry
+		if (usedLegacyFormat) {
+			result.usedLegacyFormat = true
+		}
+
 		return result
 	}
 
@@ -652,9 +729,40 @@ export class NativeToolCallParser {
 			// 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":
-					if (args.path !== undefined) {
+					// 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: "..." }
+					if (!nativeArgs && args.path !== undefined) {
 						nativeArgs = {
 							path: args.path,
 							mode: args.mode,
@@ -921,6 +1029,11 @@ export class NativeToolCallParser {
 				result.originalName = toolCall.name
 			}
 
+			// Track legacy format usage for telemetry
+			if (usedLegacyFormat) {
+				result.usedLegacyFormat = true
+			}
+
 			return result
 		} catch (error) {
 			console.error(