feat: add toggle for single-file read mode to fix model confusion

- Add useSingleFileReadMode setting to global settings schema
- Update shouldUseSingleFileRead function to check user preference
- Add UI toggle in Context settings section
- Add comprehensive test coverage
- Fixes issue #8848 where models like Qwen3-Coder get confused by multi-file args format

Author: roomote

packages/types/src/__tests__/single-file-read-models.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest"
+import { shouldUseSingleFileRead } from "../single-file-read-models.js"
+
+describe("shouldUseSingleFileRead", () => {
+	describe("with user setting", () => {
+		it("should return true when useSingleFileReadMode is true, regardless of model", () => {
+			// Test various models when user setting is enabled
+			expect(shouldUseSingleFileRead("claude-3-5-sonnet", true)).toBe(true)
+			expect(shouldUseSingleFileRead("gpt-4", true)).toBe(true)
+			expect(shouldUseSingleFileRead("qwen-coder", true)).toBe(true)
+			expect(shouldUseSingleFileRead("any-random-model", true)).toBe(true)
+		})
+
+		it("should return false when useSingleFileReadMode is false and model is not in the list", () => {
+			// Test models that are not in the single-file list when user setting is disabled
+			expect(shouldUseSingleFileRead("claude-3-5-sonnet", false)).toBe(false)
+			expect(shouldUseSingleFileRead("gpt-4", false)).toBe(false)
+			expect(shouldUseSingleFileRead("qwen-coder", false)).toBe(false)
+		})
+
+		it("should respect false setting even for models that normally use single-file mode", () => {
+			// When user explicitly sets to false, it should override model defaults
+			expect(shouldUseSingleFileRead("grok-code-fast-1", false)).toBe(false)
+			expect(shouldUseSingleFileRead("code-supernova", false)).toBe(false)
+			expect(shouldUseSingleFileRead("some-model-with-grok-code-fast-1-in-name", false)).toBe(false)
+		})
+	})
+
+	describe("without user setting (undefined)", () => {
+		it("should return true for models that include the special strings", () => {
+			// Exact matches
+			expect(shouldUseSingleFileRead("grok-code-fast-1", undefined)).toBe(true)
+			expect(shouldUseSingleFileRead("code-supernova", undefined)).toBe(true)
+
+			// Models that contain the special strings
+			expect(shouldUseSingleFileRead("x/grok-code-fast-1", undefined)).toBe(true)
+			expect(shouldUseSingleFileRead("provider/code-supernova-v2", undefined)).toBe(true)
+			expect(shouldUseSingleFileRead("grok-code-fast-1-turbo", undefined)).toBe(true)
+		})
+
+		it("should return false for models not in the single-file list", () => {
+			expect(shouldUseSingleFileRead("claude-3-5-sonnet", undefined)).toBe(false)
+			expect(shouldUseSingleFileRead("gpt-4", undefined)).toBe(false)
+			expect(shouldUseSingleFileRead("gemini-pro", undefined)).toBe(false)
+			expect(shouldUseSingleFileRead("any-other-model", undefined)).toBe(false)
+			expect(shouldUseSingleFileRead("", undefined)).toBe(false)
+		})
+
+		it("should return false when no parameters are provided", () => {
+			expect(shouldUseSingleFileRead(undefined, undefined)).toBe(false)
+		})
+	})
+
+	describe("edge cases", () => {
+		it("should handle empty model string", () => {
+			expect(shouldUseSingleFileRead("", true)).toBe(true) // User setting takes precedence
+			expect(shouldUseSingleFileRead("", false)).toBe(false)
+			expect(shouldUseSingleFileRead("", undefined)).toBe(false)
+		})
+
+		it("should handle undefined model", () => {
+			expect(shouldUseSingleFileRead(undefined, true)).toBe(true) // User setting takes precedence
+			expect(shouldUseSingleFileRead(undefined, false)).toBe(false)
+			expect(shouldUseSingleFileRead(undefined, undefined)).toBe(false)
+		})
+
+		it("should handle partial model name matches correctly", () => {
+			// The function uses includes(), so partial matches matter
+			expect(shouldUseSingleFileRead("grok-code", undefined)).toBe(false) // Doesn't include full "grok-code-fast-1"
+			expect(shouldUseSingleFileRead("code-fast-1", undefined)).toBe(false) // Doesn't include full "grok-code-fast-1"
+			expect(shouldUseSingleFileRead("supernova", undefined)).toBe(false) // Doesn't include full "code-supernova"
+			expect(shouldUseSingleFileRead("grok", undefined)).toBe(false) // Too short
+			expect(shouldUseSingleFileRead("code", undefined)).toBe(false) // Too short
+		})
+
+		it("should be case-sensitive", () => {
+			// The function uses includes() which is case-sensitive
+			expect(shouldUseSingleFileRead("GROK-CODE-FAST-1", undefined)).toBe(false)
+			expect(shouldUseSingleFileRead("Code-Supernova", undefined)).toBe(false)
+			expect(shouldUseSingleFileRead("Grok-Code-Fast-1", undefined)).toBe(false)
+			expect(shouldUseSingleFileRead("CODE-SUPERNOVA", undefined)).toBe(false)
+		})
+	})
+
+	describe("user preference priority", () => {
+		it("should always prioritize explicit user preference over model defaults", () => {
+			// User explicitly wants single-file mode for a model that doesn't require it
+			expect(shouldUseSingleFileRead("claude-3-5-sonnet", true)).toBe(true)
+
+			// User explicitly doesn't want single-file mode for models that typically require it
+			expect(shouldUseSingleFileRead("grok-code-fast-1", false)).toBe(false)
+			expect(shouldUseSingleFileRead("code-supernova", false)).toBe(false)
+			expect(shouldUseSingleFileRead("provider/grok-code-fast-1-latest", false)).toBe(false)
+		})
+	})
+})

packages/types/src/global-settings.ts

@@ -130,6 +130,7 @@ export const globalSettingsSchema = z.object({
 	maxReadFileLine: z.number().optional(),
 	maxImageFileSize: z.number().optional(),
 	maxTotalImageSize: z.number().optional(),
+	useSingleFileReadMode: z.boolean().optional(),
 
 	terminalOutputLineLimit: z.number().optional(),
 	terminalOutputCharacterLimit: z.number().optional(),

packages/types/src/single-file-read-models.ts

@@ -7,8 +7,20 @@
 /**
  * Check if a model should use single file read format
  * @param modelId The model ID to check
+ * @param useSingleFileReadMode Optional user preference to force single file mode
  * @returns true if the model should use single file reads
  */
-export function shouldUseSingleFileRead(modelId: string): boolean {
+export function shouldUseSingleFileRead(modelId: string | undefined, useSingleFileReadMode?: boolean): boolean {
+	// If user has explicitly set the preference, use it (both true and false)
+	if (useSingleFileReadMode !== undefined) {
+		return useSingleFileReadMode
+	}
+
+	// If no modelId provided, default to false
+	if (!modelId) {
+		return false
+	}
+
+	// Otherwise, check if the model is known to have issues with multi-file format
 	return modelId.includes("grok-code-fast-1") || modelId.includes("code-supernova")
 }

src/core/assistant-message/presentAssistantMessage.ts

@@ -470,7 +470,8 @@ export async function presentAssistantMessage(cline: Task) {
 				case "read_file":
 					// Check if this model should use the simplified single-file read tool
 					const modelId = cline.api.getModel().id
-					if (shouldUseSingleFileRead(modelId)) {
+					const useSingleFileReadMode = (await cline.providerRef.deref()?.getState())?.useSingleFileReadMode
+					if (shouldUseSingleFileRead(modelId, useSingleFileReadMode)) {
 						await simpleReadFileTool(
 							cline,
 							block,

src/core/prompts/tools/index.ts

@@ -35,7 +35,8 @@ const toolDescriptionMap: Record<string, (args: ToolArgs) => string | undefined>
 	read_file: (args) => {
 		// Check if the current model should use the simplified read_file tool
 		const modelId = args.settings?.modelId
-		if (modelId && shouldUseSingleFileRead(modelId)) {
+		const useSingleFileReadMode = args.settings?.useSingleFileReadMode
+		if (modelId && shouldUseSingleFileRead(modelId, useSingleFileReadMode)) {
 			return getSimpleReadFileDescription(args)
 		}
 		return getReadFileDescription(args)

src/core/webview/ClineProvider.ts

@@ -1794,6 +1794,7 @@ export class ClineProvider
 			maxReadFileLine,
 			maxImageFileSize,
 			maxTotalImageSize,
+			useSingleFileReadMode,
 			terminalCompressProgressBar,
 			historyPreviewCollapsed,
 			reasoningBlockCollapsed,
@@ -1924,6 +1925,7 @@ export class ClineProvider
 			maxReadFileLine: maxReadFileLine ?? -1,
 			maxImageFileSize: maxImageFileSize ?? 5,
 			maxTotalImageSize: maxTotalImageSize ?? 20,
+			useSingleFileReadMode: useSingleFileReadMode ?? false,
 			maxConcurrentFileReads: maxConcurrentFileReads ?? 5,
 			settingsImportedAt: this.settingsImportedAt,
 			terminalCompressProgressBar: terminalCompressProgressBar ?? true,
@@ -2143,6 +2145,7 @@ export class ClineProvider
 			maxReadFileLine: stateValues.maxReadFileLine ?? -1,
 			maxImageFileSize: stateValues.maxImageFileSize ?? 5,
 			maxTotalImageSize: stateValues.maxTotalImageSize ?? 20,
+			useSingleFileReadMode: stateValues.useSingleFileReadMode ?? false,
 			maxConcurrentFileReads: stateValues.maxConcurrentFileReads ?? 5,
 			historyPreviewCollapsed: stateValues.historyPreviewCollapsed ?? false,
 			reasoningBlockCollapsed: stateValues.reasoningBlockCollapsed ?? true,

src/core/webview/__tests__/ClineProvider.spec.ts

@@ -562,6 +562,7 @@ describe("ClineProvider", () => {
 			taskSyncEnabled: false,
 			featureRoomoteControlEnabled: false,
 			checkpointTimeout: DEFAULT_CHECKPOINT_TIMEOUT_SECONDS,
+			useSingleFileReadMode: false,
 		}
 
 		const message: ExtensionMessage = {

src/core/webview/webviewMessageHandler.ts

@@ -1639,6 +1639,10 @@ export const webviewMessageHandler = async (
 			await updateGlobalState("maxReadFileLine", message.value)
 			await provider.postStateToWebview()
 			break
+		case "useSingleFileReadMode":
+			await updateGlobalState("useSingleFileReadMode", message.bool ?? false)
+			await provider.postStateToWebview()
+			break
 		case "maxImageFileSize":
 			await updateGlobalState("maxImageFileSize", message.value)
 			await provider.postStateToWebview()

src/shared/ExtensionMessage.ts

@@ -316,6 +316,7 @@ export type ExtensionState = Pick<
 	maxReadFileLine: number // Maximum number of lines to read from a file before truncating
 	maxImageFileSize: number // Maximum size of image files to process in MB
 	maxTotalImageSize: number // Maximum total size for all images in a single read operation in MB
+	useSingleFileReadMode: boolean // Force use of single-file read mode for models that struggle with multi-file args
 
 	experiments: Experiments // Map of experiment IDs to their enabled state
 

src/shared/WebviewMessage.ts

@@ -174,6 +174,7 @@ export interface WebviewMessage {
 		| "maxReadFileLine"
 		| "maxImageFileSize"
 		| "maxTotalImageSize"
+		| "useSingleFileReadMode"
 		| "maxConcurrentFileReads"
 		| "includeDiagnosticMessages"
 		| "maxDiagnosticMessages"