Merge feat/chunked-read-file

Exposes the existing useAutoCondense setting as a CLI flag, following
the same pattern as --double-check-completion. This allows enabling
auto-condense in eval runs (e.g. SWE-bench via Harbor) to reduce
context exhaustion failures.

Made-with: Cursor

cli/src/index.test.ts

@@ -33,6 +33,8 @@ describe("CLI Commands", () => {
 			.option("--thinking [tokens]", "Enable extended thinking")
 			.option("--reasoning-effort <effort>", "Reasoning effort")
 			.option("--max-consecutive-mistakes <count>", "Maximum consecutive mistakes")
+			.option("--double-check-completion", "Reject first completion attempt to force re-verification")
+			.option("--auto-condense", "Enable AI-powered context compaction instead of mechanical truncation")
 			.action(() => {})
 
 		program
@@ -72,6 +74,8 @@ describe("CLI Commands", () => {
 			.option("--thinking [tokens]", "Enable extended thinking")
 			.option("--reasoning-effort <effort>", "Reasoning effort")
 			.option("--max-consecutive-mistakes <count>", "Maximum consecutive mistakes")
+			.option("--double-check-completion", "Reject first completion attempt to force re-verification")
+			.option("--auto-condense", "Enable AI-powered context compaction instead of mechanical truncation")
 			.action(() => {})
 	})
 
@@ -171,6 +175,20 @@ describe("CLI Commands", () => {
 			expect(taskCmd.opts().maxConsecutiveMistakes).toBe("999")
 		})
 
+		it("should parse --double-check-completion flag", () => {
+			const taskCmd = program.commands.find((c) => c.name() === "task")!
+			const args = ["test prompt", "--double-check-completion"]
+			taskCmd.parse(args, { from: "user" })
+			expect(taskCmd.opts().doubleCheckCompletion).toBe(true)
+		})
+
+		it("should parse --auto-condense flag", () => {
+			const taskCmd = program.commands.find((c) => c.name() === "task")!
+			const args = ["test prompt", "--auto-condense"]
+			taskCmd.parse(args, { from: "user" })
+			expect(taskCmd.opts().autoCondense).toBe(true)
+		})
+
 		it("should parse short flags", () => {
 			const taskCmd = program.commands.find((c) => c.name() === "task")!
 			const args = ["test prompt", "-a", "-v", "-m", "gpt-4"]

cli/src/index.ts

@@ -62,6 +62,7 @@ interface TaskOptions {
 	maxConsecutiveMistakes?: string
 	yolo?: boolean
 	doubleCheckCompletion?: boolean
+	autoCondense?: boolean
 	timeout?: string
 	json?: boolean
 	stdinWasPiped?: boolean
@@ -203,6 +204,10 @@ function applyTaskOptions(options: TaskOptions): void {
 		StateManager.get().setGlobalState("doubleCheckCompletionEnabled", true)
 		telemetryService.captureHostEvent("double_check_completion_flag", "true")
 	}
+
+	if (options.autoCondense) {
+		StateManager.get().setGlobalState("useAutoCondense", true)
+	}
 }
 
 /**
@@ -738,6 +743,7 @@ program
 	.option("--max-consecutive-mistakes <count>", "Maximum consecutive mistakes before halting in yolo mode")
 	.option("--json", "Output messages as JSON instead of styled text")
 	.option("--double-check-completion", "Reject first completion attempt to force re-verification")
+	.option("--auto-condense", "Enable AI-powered context compaction instead of mechanical truncation")
 	.option("-T, --taskId <id>", "Resume an existing task by ID")
 	.action((prompt, options) => {
 		if (options.taskId) {
@@ -905,6 +911,7 @@ program
 	.option("--max-consecutive-mistakes <count>", "Maximum consecutive mistakes before halting in yolo mode")
 	.option("--json", "Output messages as JSON instead of styled text")
 	.option("--double-check-completion", "Reject first completion attempt to force re-verification")
+	.option("--auto-condense", "Enable AI-powered context compaction instead of mechanical truncation")
 	.option("--acp", "Run in ACP (Agent Client Protocol) mode for editor integration")
 	.option("-T, --taskId <id>", "Resume an existing task by ID")
 	.action(async (prompt, options) => {

src/core/api/providers/gemini.ts

@@ -236,19 +236,47 @@ export class GeminiHandler implements ApiHandler {
 					}
 					if (part.functionCall) {
 						const functionCall = part.functionCall
-						const args = Object.entries(functionCall.args || {}).filter(([_key, val]) => !!val)
-						if (functionCall.args && args.length > 0) {
-							yield {
-								type: "tool_calls",
-								id: chunk.responseId,
-								tool_call: {
-									function: {
-										id: chunk.responseId,
-										name: functionCall.name,
-										arguments: JSON.stringify(functionCall.args),
+
+						if (functionCall.name === "multi_tool_use_parallel") {
+							// Expand the meta-tool into individual tool_call events so the
+							// normal parallel execution pipeline handles each sub-call.
+							const toolUses =
+								(functionCall.args?.tool_uses as Array<{
+									recipient_name: string
+									parameters: Record<string, unknown>
+								}>) || []
+							for (let i = 0; i < toolUses.length; i++) {
+								const use = toolUses[i]
+								if (!use?.recipient_name) continue
+								const innerName = use.recipient_name.replace(/^functions\./, "")
+								yield {
+									type: "tool_calls",
+									id: `${chunk.responseId}_mtu_${i}`,
+									tool_call: {
+										function: {
+											id: `${chunk.responseId}_mtu_${i}`,
+											name: innerName,
+											arguments: JSON.stringify(use.parameters ?? {}),
+										},
 									},
-								},
-								signature: part.thoughtSignature,
+									signature: part.thoughtSignature,
+								}
+							}
+						} else {
+							const args = Object.entries(functionCall.args || {}).filter(([_key, val]) => !!val)
+							if (functionCall.args && args.length > 0) {
+								yield {
+									type: "tool_calls",
+									id: chunk.responseId,
+									tool_call: {
+										function: {
+											id: chunk.responseId,
+											name: functionCall.name,
+											arguments: JSON.stringify(functionCall.args),
+										},
+									},
+									signature: part.thoughtSignature,
+								}
 							}
 						}
 					}

src/core/assistant-message/index.ts

@@ -54,6 +54,8 @@ export const toolParamNames = [
 	"prompt_3",
 	"prompt_4",
 	"prompt_5",
+	"start_line",
+	"end_line",
 ] as const
 
 export type ToolParamName = (typeof toolParamNames)[number]

src/core/prompts/__tests__/toolSpecificMissingParamErrors.test.ts

@@ -0,0 +1,67 @@
+import { describe, it } from "mocha"
+import "should"
+import { formatResponse } from "../responses"
+
+describe("formatResponse.replaceInFileMissingDiffError", () => {
+	it("should include the file path in the error message", () => {
+		const result = formatResponse.replaceInFileMissingDiffError("src/index.ts")
+		result.should.containEql("src/index.ts")
+	})
+
+	it("should mention that the diff parameter was empty", () => {
+		const result = formatResponse.replaceInFileMissingDiffError("src/index.ts")
+		result.should.containEql("'diff' parameter was empty")
+	})
+
+	it("should include the SEARCH/REPLACE block format", () => {
+		const result = formatResponse.replaceInFileMissingDiffError("src/index.ts")
+		result.should.containEql("<<<<<<< SEARCH")
+		result.should.containEql("=======")
+		result.should.containEql(">>>>>>> REPLACE")
+	})
+
+	it("should include rules about exact matching", () => {
+		const result = formatResponse.replaceInFileMissingDiffError("src/index.ts")
+		result.should.containEql("match existing file content exactly")
+	})
+
+	it("should suggest using read_file if unsure", () => {
+		const result = formatResponse.replaceInFileMissingDiffError("src/index.ts")
+		result.should.containEql("read_file")
+	})
+
+	it("should NOT include the generic toolUseInstructionsReminder", () => {
+		const result = formatResponse.replaceInFileMissingDiffError("src/index.ts")
+		result.should.not.containEql("Reminder: Instructions for Tool Use")
+	})
+
+	it("should work with different file paths", () => {
+		const result = formatResponse.replaceInFileMissingDiffError("components/App.tsx")
+		result.should.containEql("components/App.tsx")
+	})
+})
+
+describe("formatResponse.executeCommandMissingCommandError", () => {
+	it("should mention that the command parameter was empty", () => {
+		const result = formatResponse.executeCommandMissingCommandError()
+		result.should.containEql("'command' parameter was empty")
+	})
+
+	it("should include a concrete XML example", () => {
+		const result = formatResponse.executeCommandMissingCommandError()
+		result.should.containEql("<execute_command>")
+		result.should.containEql("<command>")
+		result.should.containEql("</command>")
+		result.should.containEql("</execute_command>")
+	})
+
+	it("should include requires_approval in the example", () => {
+		const result = formatResponse.executeCommandMissingCommandError()
+		result.should.containEql("<requires_approval>")
+	})
+
+	it("should NOT include the generic toolUseInstructionsReminder", () => {
+		const result = formatResponse.executeCommandMissingCommandError()
+		result.should.not.containEql("Reminder: Instructions for Tool Use")
+	})
+})

src/core/prompts/responses.ts

@@ -96,6 +96,33 @@ Otherwise, if you have not completed the task and do not need additional informa
 		)
 	},
 
+	replaceInFileMissingDiffError: (relPath: string): string => {
+		return (
+			`Failed to edit '${relPath}': The 'diff' parameter was empty.\n\n` +
+			`The diff parameter must contain SEARCH/REPLACE blocks in this format:\n` +
+			"<<<<<<< SEARCH\n" +
+			"exact lines to find\n" +
+			"=======\n" +
+			"replacement lines\n" +
+			">>>>>>> REPLACE\n\n" +
+			`Rules:\n` +
+			`- The SEARCH block must match existing file content exactly (including whitespace and indentation)\n` +
+			`- You can include multiple SEARCH/REPLACE blocks in a single diff parameter\n` +
+			`- If you're unsure of the exact content, use read_file first to see the current file`
+		)
+	},
+
+	executeCommandMissingCommandError: (): string => {
+		return (
+			"The 'command' parameter was empty. Provide the shell command to execute.\n\n" +
+			"Example:\n" +
+			"<execute_command>\n" +
+			"<command>cd /path && python -m pytest tests/</command>\n" +
+			"<requires_approval>false</requires_approval>\n" +
+			"</execute_command>"
+		)
+	},
+
 	invalidMcpToolArgumentError: (serverName: string, toolName: string) =>
 		`Invalid JSON argument used with ${serverName} for ${toolName}. Please retry with a properly formatted JSON argument.`,
 

src/core/prompts/system-prompt/__tests__/__snapshots__/anthropic_claude_sonnet_4-basic.snap

@@ -39,13 +39,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -90,6 +94,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -129,7 +134,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>
@@ -640,6 +645,8 @@ RULES
 - Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
 - When writing output files, produce exactly what the task specifies—no extra columns, fields, debug output, or commentary. Match the requested format precisely.
 - When the task specifies numerical thresholds or accuracy targets, verify your result meets the criteria before completing. If close but not passing, iterate rather than declaring completion.
+- When fixing a bug, if existing tests fail after your change, your code is likely wrong. Fix your code to pass the tests rather than modifying test assertions to match your new behavior, unless the user explicitly asks you to update tests.
+- After fixing a bug, verify your change by running the project's existing test suite rather than only a reproduction script you wrote. If you're unsure which tests to run, search for test files related to the code you changed.
 - The user may ask generic non-development tasks, such as "what\'s the latest news" or "look up the weather in San Diego", in which case you might use the browser_action tool to complete the task if it makes sense to do so, rather than trying to create a website or using curl to answer the question. However, if an available MCP server tool or resource can be used instead, you should prefer to use it over browser_action.
 - NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
 - You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.

src/core/prompts/system-prompt/__tests__/__snapshots__/anthropic_claude_sonnet_4-no-browser.snap

@@ -39,13 +39,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -90,6 +94,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -129,7 +134,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>
@@ -604,6 +609,8 @@ RULES
 - Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
 - When writing output files, produce exactly what the task specifies—no extra columns, fields, debug output, or commentary. Match the requested format precisely.
 - When the task specifies numerical thresholds or accuracy targets, verify your result meets the criteria before completing. If close but not passing, iterate rather than declaring completion.
+- When fixing a bug, if existing tests fail after your change, your code is likely wrong. Fix your code to pass the tests rather than modifying test assertions to match your new behavior, unless the user explicitly asks you to update tests.
+- After fixing a bug, verify your change by running the project's existing test suite rather than only a reproduction script you wrote. If you're unsure which tests to run, search for test files related to the code you changed.
 - NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
 - You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.
 - When presented with images, utilize your vision capabilities to thoroughly examine them and extract meaningful information. Incorporate these insights into your thought process as you accomplish the user's task.

src/core/prompts/system-prompt/__tests__/__snapshots__/anthropic_claude_sonnet_4-no-focus-chain.snap

@@ -36,12 +36,16 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 </read_file>
 
 ## write_to_file
@@ -83,6 +87,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 Usage:
 <replace_in_file>
 <path>File path here</path>
@@ -116,7 +121,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 Usage:
 <list_code_definition_names>
 <path>Directory path here</path>
@@ -559,6 +564,8 @@ RULES
 - Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
 - When writing output files, produce exactly what the task specifies—no extra columns, fields, debug output, or commentary. Match the requested format precisely.
 - When the task specifies numerical thresholds or accuracy targets, verify your result meets the criteria before completing. If close but not passing, iterate rather than declaring completion.
+- When fixing a bug, if existing tests fail after your change, your code is likely wrong. Fix your code to pass the tests rather than modifying test assertions to match your new behavior, unless the user explicitly asks you to update tests.
+- After fixing a bug, verify your change by running the project's existing test suite rather than only a reproduction script you wrote. If you're unsure which tests to run, search for test files related to the code you changed.
 - The user may ask generic non-development tasks, such as "what\'s the latest news" or "look up the weather in San Diego", in which case you might use the browser_action tool to complete the task if it makes sense to do so, rather than trying to create a website or using curl to answer the question. However, if an available MCP server tool or resource can be used instead, you should prefer to use it over browser_action.
 - NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
 - You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.

src/core/prompts/system-prompt/__tests__/__snapshots__/anthropic_claude_sonnet_4-no-mcp.snap

@@ -39,13 +39,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -90,6 +94,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -129,7 +134,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>
@@ -618,6 +623,8 @@ RULES
 - Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
 - When writing output files, produce exactly what the task specifies—no extra columns, fields, debug output, or commentary. Match the requested format precisely.
 - When the task specifies numerical thresholds or accuracy targets, verify your result meets the criteria before completing. If close but not passing, iterate rather than declaring completion.
+- When fixing a bug, if existing tests fail after your change, your code is likely wrong. Fix your code to pass the tests rather than modifying test assertions to match your new behavior, unless the user explicitly asks you to update tests.
+- After fixing a bug, verify your change by running the project's existing test suite rather than only a reproduction script you wrote. If you're unsure which tests to run, search for test files related to the code you changed.
 - The user may ask generic non-development tasks, such as "what\'s the latest news" or "look up the weather in San Diego", in which case you might use the browser_action tool to complete the task if it makes sense to do so, rather than trying to create a website or using curl to answer the question. However, if an available MCP server tool or resource can be used instead, you should prefer to use it over browser_action.
 - NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
 - You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.

src/core/prompts/system-prompt/__tests__/__snapshots__/cline_devstral-basic.snap

@@ -39,13 +39,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -90,6 +94,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -129,7 +134,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>
@@ -661,6 +666,8 @@ RULES
 - Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
 - When writing output files, produce exactly what the task specifies—no extra columns, fields, debug output, or commentary. Match the requested format precisely.
 - When the task specifies numerical thresholds or accuracy targets, verify your result meets the criteria before completing. If close but not passing, iterate rather than declaring completion.
+- When fixing a bug, if existing tests fail after your change, your code is likely wrong. Fix your code to pass the tests rather than modifying test assertions to match your new behavior, unless the user explicitly asks you to update tests.
+- After fixing a bug, verify your change by running the project's existing test suite rather than only a reproduction script you wrote. If you're unsure which tests to run, search for test files related to the code you changed.
 - The user may ask generic non-development tasks, such as "what\'s the latest news" or "look up the weather in San Diego", in which case you might use the browser_action tool to complete the task if it makes sense to do so, rather than trying to create a website or using curl to answer the question. However, if an available MCP server tool or resource can be used instead, you should prefer to use it over browser_action.
 - NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
 - You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.

src/core/prompts/system-prompt/__tests__/__snapshots__/cline_devstral-no-browser.snap

@@ -39,13 +39,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -90,6 +94,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -129,7 +134,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>
@@ -625,6 +630,8 @@ RULES
 - Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
 - When writing output files, produce exactly what the task specifies—no extra columns, fields, debug output, or commentary. Match the requested format precisely.
 - When the task specifies numerical thresholds or accuracy targets, verify your result meets the criteria before completing. If close but not passing, iterate rather than declaring completion.
+- When fixing a bug, if existing tests fail after your change, your code is likely wrong. Fix your code to pass the tests rather than modifying test assertions to match your new behavior, unless the user explicitly asks you to update tests.
+- After fixing a bug, verify your change by running the project's existing test suite rather than only a reproduction script you wrote. If you're unsure which tests to run, search for test files related to the code you changed.
 - NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
 - You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.
 - When presented with images, utilize your vision capabilities to thoroughly examine them and extract meaningful information. Incorporate these insights into your thought process as you accomplish the user's task.

src/core/prompts/system-prompt/__tests__/__snapshots__/cline_devstral-no-focus-chain.snap

@@ -36,12 +36,16 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 </read_file>
 
 ## write_to_file
@@ -83,6 +87,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 Usage:
 <replace_in_file>
 <path>File path here</path>
@@ -116,7 +121,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 Usage:
 <list_code_definition_names>
 <path>Directory path here</path>
@@ -585,6 +590,8 @@ RULES
 - Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
 - When writing output files, produce exactly what the task specifies—no extra columns, fields, debug output, or commentary. Match the requested format precisely.
 - When the task specifies numerical thresholds or accuracy targets, verify your result meets the criteria before completing. If close but not passing, iterate rather than declaring completion.
+- When fixing a bug, if existing tests fail after your change, your code is likely wrong. Fix your code to pass the tests rather than modifying test assertions to match your new behavior, unless the user explicitly asks you to update tests.
+- After fixing a bug, verify your change by running the project's existing test suite rather than only a reproduction script you wrote. If you're unsure which tests to run, search for test files related to the code you changed.
 - The user may ask generic non-development tasks, such as "what\'s the latest news" or "look up the weather in San Diego", in which case you might use the browser_action tool to complete the task if it makes sense to do so, rather than trying to create a website or using curl to answer the question. However, if an available MCP server tool or resource can be used instead, you should prefer to use it over browser_action.
 - NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
 - You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.

src/core/prompts/system-prompt/__tests__/__snapshots__/cline_devstral-no-mcp.snap

@@ -39,13 +39,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -90,6 +94,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -129,7 +134,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>
@@ -639,6 +644,8 @@ RULES
 - Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
 - When writing output files, produce exactly what the task specifies—no extra columns, fields, debug output, or commentary. Match the requested format precisely.
 - When the task specifies numerical thresholds or accuracy targets, verify your result meets the criteria before completing. If close but not passing, iterate rather than declaring completion.
+- When fixing a bug, if existing tests fail after your change, your code is likely wrong. Fix your code to pass the tests rather than modifying test assertions to match your new behavior, unless the user explicitly asks you to update tests.
+- After fixing a bug, verify your change by running the project's existing test suite rather than only a reproduction script you wrote. If you're unsure which tests to run, search for test files related to the code you changed.
 - The user may ask generic non-development tasks, such as "what\'s the latest news" or "look up the weather in San Diego", in which case you might use the browser_action tool to complete the task if it makes sense to do so, rather than trying to create a website or using curl to answer the question. However, if an available MCP server tool or resource can be used instead, you should prefer to use it over browser_action.
 - NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
 - You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.

src/core/prompts/system-prompt/__tests__/__snapshots__/cline_native_next_gen.tools.snap

@@ -59,7 +59,7 @@
     "type": "function",
     "function": {
       "name": "read_file",
-      "description": "Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.",
+      "description": "Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.",
       "strict": false,
       "parameters": {
         "type": "object",
@@ -68,6 +68,14 @@
             "type": "string",
             "description": "The path of the file to read (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}}"
           },
+          "start_line": {
+            "type": "integer",
+            "description": "The 1-based line number to start reading from (inclusive). Defaults to 1."
+          },
+          "end_line": {
+            "type": "integer",
+            "description": "The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files."
+          },
           "task_progress": {
             "type": "string",
             "description": "A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)"
@@ -125,7 +133,7 @@
           },
           "diff": {
             "type": "string",
-            "description": "One or more SEARCH/REPLACE blocks following this exact format:\n  ```\n  ------- SEARCH\n  [exact content to find]\n  =======\n  [new content to replace with]\n  +++++++ REPLACE\n  ```\n  Critical rules:\n  1. SEARCH content must match the associated file section to find EXACTLY:\n     * Match character-for-character including whitespace, indentation, line endings\n     * Include all comments, docstrings, etc.\n  2. SEARCH/REPLACE blocks will ONLY replace the first match occurrence.\n     * Including multiple unique SEARCH/REPLACE blocks if you need to make multiple changes.\n     * Include *just* enough lines in each SEARCH section to uniquely match each set of lines that need to change.\n     * When using multiple SEARCH/REPLACE blocks, list them in the order they appear in the file.\n  3. Keep SEARCH/REPLACE blocks concise:\n     * Break large SEARCH/REPLACE blocks into a series of smaller blocks that each change a small portion of the file.\n     * Include just the changing lines, and a few surrounding lines if needed for uniqueness.\n     * Do not include long runs of unchanging lines in SEARCH/REPLACE blocks.\n     * Each line must be complete. Never truncate lines mid-way through as this can cause matching failures.\n  4. Special operations:\n     * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)\n     * To delete code: Use empty REPLACE section"
+            "description": "One or more SEARCH/REPLACE blocks following this exact format:\n  ```\n  ------- SEARCH\n  [exact content to find]\n  =======\n  [new content to replace with]\n  +++++++ REPLACE\n  ```\n  Critical rules:\n  1. SEARCH content must match the associated file section to find EXACTLY:\n     * Match character-for-character including whitespace, indentation, line endings\n     * Include all comments, docstrings, etc.\n  2. SEARCH/REPLACE blocks will ONLY replace the first match occurrence.\n     * Including multiple unique SEARCH/REPLACE blocks if you need to make multiple changes.\n     * Include *just* enough lines in each SEARCH section to uniquely match each set of lines that need to change.\n     * When using multiple SEARCH/REPLACE blocks, list them in the order they appear in the file.\n  3. Keep SEARCH/REPLACE blocks concise:\n     * Break large SEARCH/REPLACE blocks into a series of smaller blocks that each change a small portion of the file.\n     * Include just the changing lines, and a few surrounding lines if needed for uniqueness.\n     * Do not include long runs of unchanging lines in SEARCH/REPLACE blocks.\n     * Each line must be complete. Never truncate lines mid-way through as this can cause matching failures.\n  4. Special operations:\n     * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)\n     * To delete code: Use empty REPLACE section\n  5. If your source context came from read_file and includes line labels (for example, \"L42: const x = 1\"), do NOT include the \"L42: \" prefix in SEARCH or REPLACE content. Match only the raw file text."
           },
           "task_progress": {
             "type": "string",
@@ -214,7 +222,7 @@
         "properties": {
           "path": {
             "type": "string",
-            "description": "The path of the directory (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}} to list top level source code definitions for."
+            "description": "The path of a directory (not a file) relative to the current working directory {{CWD}}{{MULTI_ROOT_HINT}}. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead."
           },
           "task_progress": {
             "type": "string",

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_3-basic.snap

@@ -39,13 +39,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -90,6 +94,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -129,7 +134,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>
@@ -629,6 +634,8 @@ RULES
 - Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
 - When writing output files, produce exactly what the task specifies—no extra columns, fields, debug output, or commentary. Match the requested format precisely.
 - When the task specifies numerical thresholds or accuracy targets, verify your result meets the criteria before completing. If close but not passing, iterate rather than declaring completion.
+- When fixing a bug, if existing tests fail after your change, your code is likely wrong. Fix your code to pass the tests rather than modifying test assertions to match your new behavior, unless the user explicitly asks you to update tests.
+- After fixing a bug, verify your change by running the project's existing test suite rather than only a reproduction script you wrote. If you're unsure which tests to run, search for test files related to the code you changed.
 - The user may ask generic non-development tasks, such as "what\'s the latest news" or "look up the weather in San Diego", in which case you might use the browser_action tool to complete the task if it makes sense to do so, rather than trying to create a website or using curl to answer the question. However, if an available MCP server tool or resource can be used instead, you should prefer to use it over browser_action.
 - NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
 - You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_3-no-browser.snap

@@ -39,13 +39,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -90,6 +94,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -129,7 +134,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>
@@ -593,6 +598,8 @@ RULES
 - Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
 - When writing output files, produce exactly what the task specifies—no extra columns, fields, debug output, or commentary. Match the requested format precisely.
 - When the task specifies numerical thresholds or accuracy targets, verify your result meets the criteria before completing. If close but not passing, iterate rather than declaring completion.
+- When fixing a bug, if existing tests fail after your change, your code is likely wrong. Fix your code to pass the tests rather than modifying test assertions to match your new behavior, unless the user explicitly asks you to update tests.
+- After fixing a bug, verify your change by running the project's existing test suite rather than only a reproduction script you wrote. If you're unsure which tests to run, search for test files related to the code you changed.
 - NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
 - You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.
 - When presented with images, utilize your vision capabilities to thoroughly examine them and extract meaningful information. Incorporate these insights into your thought process as you accomplish the user's task.

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_3-no-focus-chain.snap

@@ -36,12 +36,16 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 </read_file>
 
 ## write_to_file
@@ -83,6 +87,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 Usage:
 <replace_in_file>
 <path>File path here</path>
@@ -116,7 +121,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 Usage:
 <list_code_definition_names>
 <path>Directory path here</path>
@@ -557,6 +562,8 @@ RULES
 - Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
 - When writing output files, produce exactly what the task specifies—no extra columns, fields, debug output, or commentary. Match the requested format precisely.
 - When the task specifies numerical thresholds or accuracy targets, verify your result meets the criteria before completing. If close but not passing, iterate rather than declaring completion.
+- When fixing a bug, if existing tests fail after your change, your code is likely wrong. Fix your code to pass the tests rather than modifying test assertions to match your new behavior, unless the user explicitly asks you to update tests.
+- After fixing a bug, verify your change by running the project's existing test suite rather than only a reproduction script you wrote. If you're unsure which tests to run, search for test files related to the code you changed.
 - The user may ask generic non-development tasks, such as "what\'s the latest news" or "look up the weather in San Diego", in which case you might use the browser_action tool to complete the task if it makes sense to do so, rather than trying to create a website or using curl to answer the question. However, if an available MCP server tool or resource can be used instead, you should prefer to use it over browser_action.
 - NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
 - You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_3-no-mcp.snap

@@ -39,13 +39,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -90,6 +94,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -129,7 +134,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>
@@ -607,6 +612,8 @@ RULES
 - Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
 - When writing output files, produce exactly what the task specifies—no extra columns, fields, debug output, or commentary. Match the requested format precisely.
 - When the task specifies numerical thresholds or accuracy targets, verify your result meets the criteria before completing. If close but not passing, iterate rather than declaring completion.
+- When fixing a bug, if existing tests fail after your change, your code is likely wrong. Fix your code to pass the tests rather than modifying test assertions to match your new behavior, unless the user explicitly asks you to update tests.
+- After fixing a bug, verify your change by running the project's existing test suite rather than only a reproduction script you wrote. If you're unsure which tests to run, search for test files related to the code you changed.
 - The user may ask generic non-development tasks, such as "what\'s the latest news" or "look up the weather in San Diego", in which case you might use the browser_action tool to complete the task if it makes sense to do so, rather than trying to create a website or using curl to answer the question. However, if an available MCP server tool or resource can be used instead, you should prefer to use it over browser_action.
 - NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
 - You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_5-basic.snap

@@ -39,13 +39,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -90,6 +94,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -129,7 +134,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_5-no-browser.snap

@@ -39,13 +39,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -90,6 +94,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -129,7 +134,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_5-no-focus-chain.snap

@@ -36,12 +36,16 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 </read_file>
 
 ## write_to_file
@@ -83,6 +87,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 Usage:
 <replace_in_file>
 <path>File path here</path>
@@ -116,7 +121,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 Usage:
 <list_code_definition_names>
 <path>Directory path here</path>

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_5-no-mcp.snap

@@ -39,13 +39,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -90,6 +94,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -129,7 +134,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_5_1_native.tools.snap

@@ -29,7 +29,7 @@
     "type": "function",
     "function": {
       "name": "read_file",
-      "description": "Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.",
+      "description": "Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.",
       "strict": false,
       "parameters": {
         "type": "object",
@@ -38,6 +38,14 @@
             "type": "string",
             "description": "The path of the file to read (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}}"
           },
+          "start_line": {
+            "type": "integer",
+            "description": "The 1-based line number to start reading from (inclusive). Defaults to 1."
+          },
+          "end_line": {
+            "type": "integer",
+            "description": "The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files."
+          },
           "task_progress": {
             "type": "string",
             "description": "A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)"
@@ -149,7 +157,7 @@
         "properties": {
           "path": {
             "type": "string",
-            "description": "The path of the directory (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}} to list top level source code definitions for."
+            "description": "The path of a directory (not a file) relative to the current working directory {{CWD}}{{MULTI_ROOT_HINT}}. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead."
           },
           "task_progress": {
             "type": "string",

src/core/prompts/system-prompt/__tests__/__snapshots__/openai_gpt_5_native.tools.snap

@@ -29,7 +29,7 @@
     "type": "function",
     "function": {
       "name": "read_file",
-      "description": "Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.",
+      "description": "Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.",
       "strict": false,
       "parameters": {
         "type": "object",
@@ -38,6 +38,14 @@
             "type": "string",
             "description": "The path of the file to read (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}}"
           },
+          "start_line": {
+            "type": "integer",
+            "description": "The 1-based line number to start reading from (inclusive). Defaults to 1."
+          },
+          "end_line": {
+            "type": "integer",
+            "description": "The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files."
+          },
           "task_progress": {
             "type": "string",
             "description": "A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)"
@@ -149,7 +157,7 @@
         "properties": {
           "path": {
             "type": "string",
-            "description": "The path of the directory (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}} to list top level source code definitions for."
+            "description": "The path of a directory (not a file) relative to the current working directory {{CWD}}{{MULTI_ROOT_HINT}}. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead."
           },
           "task_progress": {
             "type": "string",

src/core/prompts/system-prompt/__tests__/__snapshots__/openrouter_arcee_ai_trinity_large_preview-basic.snap

@@ -48,13 +48,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -99,6 +103,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -138,7 +143,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>

src/core/prompts/system-prompt/__tests__/__snapshots__/openrouter_arcee_ai_trinity_large_preview-no-browser.snap

@@ -48,13 +48,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -99,6 +103,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -138,7 +143,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>

src/core/prompts/system-prompt/__tests__/__snapshots__/openrouter_arcee_ai_trinity_large_preview-no-focus-chain.snap

@@ -45,12 +45,16 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 </read_file>
 
 ## write_to_file
@@ -92,6 +96,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 Usage:
 <replace_in_file>
 <path>File path here</path>
@@ -125,7 +130,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 Usage:
 <list_code_definition_names>
 <path>Directory path here</path>

src/core/prompts/system-prompt/__tests__/__snapshots__/openrouter_arcee_ai_trinity_large_preview-no-mcp.snap

@@ -48,13 +48,17 @@ Usage:
 </execute_command>
 
 ## read_file
-Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.
+Description: Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.
 Parameters:
 - path: (required) The path of the file to read (relative to the current working directory /test/project)
+- start_line: (optional) The 1-based line number to start reading from (inclusive). Defaults to 1.
+- end_line: (optional) The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <read_file>
 <path>File path here</path>
+<start_line>1</start_line>
+<end_line>1000</end_line>
 <task_progress>Checklist here (optional)</task_progress>
 </read_file>
 
@@ -99,6 +103,7 @@ Parameters:
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
      * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <replace_in_file>
@@ -138,7 +143,7 @@ Usage:
 ## list_code_definition_names
 Description: Request to list definition names (classes, functions, methods, etc.) used in source code files at the top level of the specified directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.
 Parameters:
-- path: (required) The path of the directory (relative to the current working directory /test/project) to list top level source code definitions for.
+- path: (required) The path of a directory (not a file) relative to the current working directory /test/project. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.
 - task_progress: (optional) A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)
 Usage:
 <list_code_definition_names>

src/core/prompts/system-prompt/__tests__/__snapshots__/vertex_gemini3.tools.snap

@@ -6,10 +6,12 @@
       "type": "OBJECT",
       "properties": {
         "command": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The CLI command to execute. This should be valid for the current operating system. For command chaining, use proper shell operators like && to chain commands (e.g., 'cd path && command'). Do not use the ~ character or $HOME to refer to the home directory. Always use absolute paths. Do not run search/grep commands that may return thousands of results."
         },
         "requires_approval": {
-          "type": "BOOLEAN"
+          "type": "BOOLEAN",
+          "description": "To indicate whether this command requires explicit user approval or interaction before it should be executed. For system/file altering operations like installing/uninstalling packages, removing/overwriting files, system configuration changes, network operations, or any commands that are considered potentially dangerous must be set to true. False for safe operations like running development servers, building projects, and other non-destructive operations."
         }
       },
       "required": [
@@ -20,15 +22,23 @@
   },
   {
     "name": "read_file",
-    "description": "Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.",
+    "description": "Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string.",
     "parameters": {
       "type": "OBJECT",
       "properties": {
         "path": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The path of the file to read (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}}"
+        },
+        "start_line": {
+          "type": "NUMBER"
+        },
+        "end_line": {
+          "type": "NUMBER"
         },
         "task_progress": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)"
         }
       },
       "required": [
@@ -43,13 +53,16 @@
       "type": "OBJECT",
       "properties": {
         "path": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The path of the file to write to (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}}"
         },
         "content": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The content to write to the file. ALWAYS provide the COMPLETE intended content of the file, without any truncation or omissions. You MUST include ALL parts of the file, even if they haven't been modified."
         },
         "task_progress": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)"
         }
       },
       "required": [
@@ -65,13 +78,16 @@
       "type": "OBJECT",
       "properties": {
         "path": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The path of the file to modify (relative to the current working directory {{CWD}})"
         },
         "diff": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "One or more SEARCH/REPLACE blocks following this exact format:\n  ```\n  ------- SEARCH\n  [exact content to find]\n  =======\n  [new content to replace with]\n  +++++++ REPLACE\n  ```\n  Critical rules:\n  1. SEARCH content must match the associated file section to find EXACTLY:\n     * Match character-for-character including whitespace, indentation, line endings\n     * Include all comments, docstrings, etc.\n  2. SEARCH/REPLACE blocks will ONLY replace the first match occurrence.\n     * Including multiple unique SEARCH/REPLACE blocks if you need to make multiple changes.\n     * Include *just* enough lines in each SEARCH section to uniquely match each set of lines that need to change.\n     * When using multiple SEARCH/REPLACE blocks, list them in the order they appear in the file.\n  3. Keep SEARCH/REPLACE blocks concise:\n     * Break large SEARCH/REPLACE blocks into a series of smaller blocks that each change a small portion of the file.\n     * Include just the changing lines, and a few surrounding lines if needed for uniqueness.\n     * Do not include long runs of unchanging lines in SEARCH/REPLACE blocks.\n     * Each line must be complete. Never truncate lines mid-way through as this can cause matching failures.\n  4. Special operations:\n     * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)\n     * To delete code: Use empty REPLACE section"
         },
         "task_progress": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)"
         }
       },
       "required": [
@@ -87,16 +103,20 @@
       "type": "OBJECT",
       "properties": {
         "path": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The path of the directory to search in (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}}. This directory will be recursively searched."
         },
         "regex": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The regular expression pattern to search for. Uses Rust regex syntax."
         },
         "file_pattern": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "Glob pattern to filter files (e.g., '*.ts' for TypeScript files). If not provided, it will search all files (*)."
         },
         "task_progress": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)"
         }
       },
       "required": [
@@ -112,13 +132,16 @@
       "type": "OBJECT",
       "properties": {
         "path": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The path of the directory to list contents for (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}}"
         },
         "recursive": {
-          "type": "BOOLEAN"
+          "type": "BOOLEAN",
+          "description": "Whether to list files recursively. Use true for recursive listing, false or omit for top-level only."
         },
         "task_progress": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)"
         }
       },
       "required": [
@@ -133,10 +156,12 @@
       "type": "OBJECT",
       "properties": {
         "path": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The path of the directory (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}} to list top level source code definitions for."
         },
         "task_progress": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)"
         }
       },
       "required": [
@@ -151,16 +176,20 @@
       "type": "OBJECT",
       "properties": {
         "action": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The action to perform. The available actions are: \n\t* launch: Launch a new Puppeteer-controlled browser instance at the specified URL. This **must always be the first action**. \n\t\t- Use with the `url` parameter to provide the URL. \n\t\t- Ensure the URL is valid and includes the appropriate protocol (e.g. http://localhost:3000/page, file:///path/to/file.html, etc.) \n\t* click: Click at a specific x,y coordinate. \n\t\t- Use with the `coordinate` parameter to specify the location. \n\t\t- Always click in the center of an element (icon, button, link, etc.) based on coordinates derived from a screenshot. \n\t* type: Type a string of text on the keyboard. You might use this after clicking on a text field to input text. \n\t\t- Use with the `text` parameter to provide the string to type. \n\t* scroll_down: Scroll down the page by one page height. \n\t* scroll_up: Scroll up the page by one page height. \n\t* close: Close the Puppeteer-controlled browser instance. This **must always be the final browser action**. \n\t    - Example: `<action>close</action>`"
         },
         "url": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "Use this for providing the URL for the `launch` action. \n\t* Example: <url>https://example.com</url>"
         },
         "coordinate": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The X and Y coordinates for the `click` action. Coordinates should be within the **1280x720** resolution. \n\t* Example: <coordinate>450,300</coordinate>"
         },
         "text": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "Use this for providing the text for the `type` action. \n\t* Example: <text>Hello, world!</text>"
         }
       },
       "required": [
@@ -175,16 +204,20 @@
       "type": "OBJECT",
       "properties": {
         "server_name": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The name of the MCP server providing the tool"
         },
         "tool_name": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The name of the tool to execute"
         },
         "arguments": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A JSON object containing the tool's input parameters, following the tool's input schema"
         },
         "task_progress": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)"
         }
       },
       "required": [
@@ -201,13 +234,16 @@
       "type": "OBJECT",
       "properties": {
         "server_name": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The name of the MCP server providing the resource"
         },
         "uri": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The URI identifying the specific resource to access"
         },
         "task_progress": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)"
         }
       },
       "required": [
@@ -223,13 +259,16 @@
       "type": "OBJECT",
       "properties": {
         "question": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The question to ask the user. This should be a clear, specific question that addresses the information you need."
         },
         "options": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "An array of 2-5 options for the user to choose from. Each option should be a string describing a possible answer. You may not always need to provide options, but it may be helpful in many cases where it can save the user from having to type out a response manually. IMPORTANT: NEVER include an option to toggle to Act mode, as this would be something you need to direct the user to do manually themselves if needed."
         },
         "task_progress": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A checklist showing task progress after this tool use is completed. The task_progress parameter must be included as a separate parameter inside of the parent tool call, it must be separate from other parameters such as content, arguments, etc. (See 'UPDATING TASK PROGRESS' section for more details)"
         }
       },
       "required": [
@@ -244,13 +283,16 @@
       "type": "OBJECT",
       "properties": {
         "result": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The result of the tool use. This should be a clear, specific description of the result."
         },
         "command": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A CLI command to execute to show a live demo of the result to the user. For example, use `open index.html` to display a created html website, or `open localhost:3000` to display a locally running development server. But DO NOT use commands like `echo` or `cat` that merely print text. This command should be valid for the current operating system. Ensure the command is properly formatted and does not contain any harmful instructions"
         },
         "task_progress": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A checklist showing task progress after this tool use is completed. (See 'Updating Task Progress' section for more details)"
         }
       },
       "required": [
@@ -265,7 +307,8 @@
       "type": "OBJECT",
       "properties": {
         "context": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The context to preload the new task with. If applicable based on the current task, this should include:\n  1. Current Work: Describe in detail what was being worked on prior to this request to create a new task. Pay special attention to the more recent messages / conversation.\n  2. Key Technical Concepts: List all important technical concepts, technologies, coding conventions, and frameworks discussed, which might be relevant for the new task.\n  3. Relevant Files and Code: If applicable, enumerate specific files and code sections examined, modified, or created for the task continuation. Pay special attention to the most recent messages and changes.\n  4. Problem Solving: Document problems solved thus far and any ongoing troubleshooting efforts.\n  5. Pending Tasks and Next Steps: Outline all pending tasks that you have explicitly been asked to work on, as well as list the next steps you will take for all outstanding work, if applicable. Include code snippets where they add clarity. For any next steps, include direct quotes from the most recent conversation showing exactly what task you were working on and where you left off. This should be verbatim to ensure there's no information loss in context between tasks. It's important to be detailed here."
         }
       },
       "required": [
@@ -280,13 +323,16 @@
       "type": "OBJECT",
       "properties": {
         "response": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A chat message response to the user."
         },
         "needs_more_exploration": {
-          "type": "BOOLEAN"
+          "type": "BOOLEAN",
+          "description": "needs_more_exploration can be set to true if it is determined that further exploration with read_file/search tools is necessary to formulate a complete plan. This determination can be reached during the response generation process, but should not be acknowledged until this parameter is set to true if required."
         },
         "task_progress": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A checklist showing task progress after this tool use is completed. If you are presenting a final implementation plan to the user with needs_more_exploration set to false, you should include a checklist of items to be completed during Act Mode when implementation is underway. (See 'Updating Task Progress' section for more details)"
         }
       },
       "required": [
@@ -301,10 +347,12 @@
       "type": "OBJECT",
       "properties": {
         "response": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The message to provide to the user. This should explain what you're about to do, your current progress, or your reasoning. The response should be brief and conversational in tone, aiming to keep the user informed without overwhelming them with details."
         },
         "task_progress": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A checklist showing task progress with the latest status of each subtasks included previously if any."
         }
       },
       "required": [
@@ -328,13 +376,16 @@
       "type": "OBJECT",
       "properties": {
         "title": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "A descriptive title for the diff view (e.g., 'Changes in commit abc123', 'PR #42: Add authentication', 'Changes between main and feature-branch')"
         },
         "from_ref": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The git reference for the 'before' state. Can be a commit hash, branch name, tag, or relative reference like HEAD~1, HEAD^, origin/main, etc."
         },
         "to_ref": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "The git reference for the 'after' state. Can be a commit hash, branch name, tag, or relative reference. If not provided, compares to the current working directory (including uncommitted changes)."
         }
       },
       "required": [
@@ -350,19 +401,24 @@
       "type": "OBJECT",
       "properties": {
         "prompt_1": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "First subagent prompt."
         },
         "prompt_2": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "Optional second subagent prompt."
         },
         "prompt_3": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "Optional third subagent prompt."
         },
         "prompt_4": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "Optional fourth subagent prompt."
         },
         "prompt_5": {
-          "type": "STRING"
+          "type": "STRING",
+          "description": "Optional fifth subagent prompt."
         }
       },
       "required": [

src/core/prompts/system-prompt/__tests__/__snapshots__/vertex_gemini_3-basic.snap

@@ -2,7 +2,9 @@ You are Cline, a software engineering AI. Your mission is to execute precisely w
 
 TOOL USE
 
-You have access to a set of tools that are executed upon the user's approval. You should use a single tool at a time and wait for the result before proceeding. You will receive the results of all tool uses in the user's response.
+You have access to a set of tools that are executed upon the user's approval. You will receive the results of all tool uses in the user's response.
+
+Use a single tool at a time and wait for the result before proceeding.
 
 When using tools, proceed directly with tool calls. Save explanations for the attempt_completion summary. Both attempt_completion and plan_mode_respond display to the user as assistant messages, so include your message content within the tool call itself rather than duplicating it outside.
 

src/core/prompts/system-prompt/__tests__/__snapshots__/vertex_gemini_3-no-browser.snap

@@ -2,7 +2,9 @@ You are Cline, a software engineering AI. Your mission is to execute precisely w
 
 TOOL USE
 
-You have access to a set of tools that are executed upon the user's approval. You should use a single tool at a time and wait for the result before proceeding. You will receive the results of all tool uses in the user's response.
+You have access to a set of tools that are executed upon the user's approval. You will receive the results of all tool uses in the user's response.
+
+Use a single tool at a time and wait for the result before proceeding.
 
 When using tools, proceed directly with tool calls. Save explanations for the attempt_completion summary. Both attempt_completion and plan_mode_respond display to the user as assistant messages, so include your message content within the tool call itself rather than duplicating it outside.
 

src/core/prompts/system-prompt/__tests__/__snapshots__/vertex_gemini_3-no-focus-chain.snap

@@ -2,7 +2,9 @@ You are Cline, a software engineering AI. Your mission is to execute precisely w
 
 TOOL USE
 
-You have access to a set of tools that are executed upon the user's approval. You should use a single tool at a time and wait for the result before proceeding. You will receive the results of all tool uses in the user's response.
+You have access to a set of tools that are executed upon the user's approval. You will receive the results of all tool uses in the user's response.
+
+Use a single tool at a time and wait for the result before proceeding.
 
 When using tools, proceed directly with tool calls. Save explanations for the attempt_completion summary. Both attempt_completion and plan_mode_respond display to the user as assistant messages, so include your message content within the tool call itself rather than duplicating it outside.
 

src/core/prompts/system-prompt/__tests__/__snapshots__/vertex_gemini_3-no-mcp.snap

@@ -2,7 +2,9 @@ You are Cline, a software engineering AI. Your mission is to execute precisely w
 
 TOOL USE
 
-You have access to a set of tools that are executed upon the user's approval. You should use a single tool at a time and wait for the result before proceeding. You will receive the results of all tool uses in the user's response.
+You have access to a set of tools that are executed upon the user's approval. You will receive the results of all tool uses in the user's response.
+
+Use a single tool at a time and wait for the result before proceeding.
 
 When using tools, proceed directly with tool calls. Save explanations for the attempt_completion summary. Both attempt_completion and plan_mode_respond display to the user as assistant messages, so include your message content within the tool call itself rather than duplicating it outside.
 

src/core/prompts/system-prompt/__tests__/spec.test.ts

@@ -0,0 +1,96 @@
+import { expect } from "chai"
+import { describe, it } from "mocha"
+import { ModelFamily } from "@/shared/prompts"
+import { ClineDefaultTool } from "@/shared/tools"
+import type { ClineToolSpec } from "../spec"
+import { toolSpecFunctionDeclarations, toolSpecInputSchema } from "../spec"
+import type { SystemPromptContext } from "../types"
+
+const mockContext: SystemPromptContext = {
+	cwd: "/test/project",
+	ide: "TestIde",
+	supportsBrowserUse: true,
+	clineWebToolsEnabled: true,
+	subagentsEnabled: true,
+	providerInfo: { providerId: "test", model: { id: "test-model", info: { supportsPromptCache: false } }, mode: "act" },
+	enableNativeToolCalls: false,
+	isTesting: true,
+}
+
+const makeTool = (overrides?: Partial<ClineToolSpec>): ClineToolSpec => ({
+	variant: ModelFamily.GENERIC,
+	id: ClineDefaultTool.FILE_READ,
+	name: "read_file",
+	description: "Read a file",
+	parameters: [
+		{
+			name: "path",
+			required: true,
+			instruction: "The path of the file to read relative to {{CWD}}",
+		},
+		{
+			name: "optional_param",
+			required: false,
+			instruction: "An optional parameter",
+		},
+	],
+	...overrides,
+})
+
+describe("toolSpecFunctionDeclarations (Gemini)", () => {
+	it("includes parameter descriptions from instruction field", () => {
+		const result = toolSpecFunctionDeclarations(makeTool(), mockContext)
+
+		const pathParam = result.parameters?.properties?.["path"] as any
+		expect(pathParam).to.exist
+		expect(pathParam.description).to.be.a("string")
+		expect(pathParam.description).to.include("path of the file to read")
+	})
+
+	it("includes descriptions for all parameters", () => {
+		const result = toolSpecFunctionDeclarations(makeTool(), mockContext)
+
+		const props = result.parameters?.properties as any
+		expect(props["path"].description).to.be.a("string").and.not.be.empty
+		expect(props["optional_param"].description).to.be.a("string").and.not.be.empty
+	})
+
+	it("handles function-type instructions", () => {
+		const tool = makeTool({
+			parameters: [
+				{
+					name: "dynamic",
+					required: true,
+					instruction: (ctx: SystemPromptContext) => `Dynamic value: ${ctx.cwd}`,
+				},
+			],
+		})
+		const result = toolSpecFunctionDeclarations(tool, mockContext)
+
+		const param = result.parameters?.properties?.["dynamic"] as any
+		expect(param.description).to.equal("Dynamic value: /test/project")
+	})
+
+	it("omits description when instruction is empty", () => {
+		const tool = makeTool({
+			parameters: [{ name: "empty", required: false, instruction: "" }],
+		})
+		const result = toolSpecFunctionDeclarations(tool, mockContext)
+
+		const param = result.parameters?.properties?.["empty"] as any
+		expect(param.description).to.be.undefined
+	})
+})
+
+describe("Gemini and Anthropic parameter descriptions match", () => {
+	it("both converters produce the same description text", () => {
+		const tool = makeTool()
+		const gemini = toolSpecFunctionDeclarations(tool, mockContext)
+		const anthropic = toolSpecInputSchema(tool, mockContext)
+
+		const geminiDesc = (gemini.parameters?.properties?.["path"] as any)?.description
+		const anthropicDesc = (anthropic.input_schema as any).properties["path"]?.description
+
+		expect(geminiDesc).to.equal(anthropicDesc)
+	})
+})

src/core/prompts/system-prompt/components/rules.ts

@@ -6,7 +6,7 @@ const BROWSER_RULES = `- The user may ask generic non-development tasks, such as
 
 const BROWSER_WAIT_RULES = ` Then if you want to test your work, you might use browser_action to launch the site, wait for the user's response confirming the site was launched along with a screenshot, then perhaps e.g., click a button to test functionality if needed, wait for the user's response confirming the button was clicked along with a screenshot of the new state, before finally closing the browser.`
 
-const CLI_RULES = `- After making code changes, consider running any available validation tools for the project (such as type checkers, linters, or build scripts like \`npm run lint\`, \`npx tsc --noEmit\`, \`npm run build\`) to catch errors, since you won't receive automatic diagnostics after edits.\n`
+const CLI_RULES = `- After making code changes, consider running any available validation tools for the project (such as type checkers, linters, test suites, or build scripts) to catch errors, since you won't receive automatic diagnostics after edits.\n`
 
 const getRulesTemplateText = (context: SystemPromptContext) => `RULES
 
@@ -27,6 +27,8 @@ const getRulesTemplateText = (context: SystemPromptContext) => `RULES
 - Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
 - When writing output files, produce exactly what the task specifies—no extra columns, fields, debug output, or commentary. Match the requested format precisely.
 - When the task specifies numerical thresholds or accuracy targets, verify your result meets the criteria before completing. If close but not passing, iterate rather than declaring completion.
+- When fixing a bug, if existing tests fail after your change, your code is likely wrong. Fix your code to pass the tests rather than modifying test assertions to match your new behavior, unless the user explicitly asks you to update tests.
+- After fixing a bug, verify your change by running the project's existing test suite rather than only a reproduction script you wrote. If you're unsure which tests to run, search for test files related to the code you changed.
 {{BROWSER_RULES}}{{CLI_RULES}}- NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
 - You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.
 - When presented with images, utilize your vision capabilities to thoroughly examine them and extract meaningful information. Incorporate these insights into your thought process as you accomplish the user's task.

src/core/prompts/system-prompt/registry/ClineToolSet.ts

@@ -2,7 +2,13 @@ import { AgentConfigLoader } from "@core/task/tools/subagent/AgentConfigLoader"
 import { CLINE_MCP_TOOL_IDENTIFIER, McpServer } from "@/shared/mcp"
 import { ModelFamily } from "@/shared/prompts"
 import { ClineDefaultTool } from "@/shared/tools"
-import { type ClineToolSpec, toolSpecFunctionDeclarations, toolSpecFunctionDefinition, toolSpecInputSchema } from "../spec"
+import {
+	type ClineToolSpec,
+	MULTI_TOOL_USE_PARALLEL,
+	toolSpecFunctionDeclarations,
+	toolSpecFunctionDefinition,
+	toolSpecInputSchema,
+} from "../spec"
 import { PromptVariant, SystemPromptContext } from "../types"
 
 export class ClineToolSet {
@@ -187,8 +193,16 @@ export class ClineToolSet {
 			(tool) => typeof tool.description === "string" && tool.description.trim().length > 0,
 		)
 		const converter = ClineToolSet.getNativeConverter(context.providerInfo.providerId, context.providerInfo.model.id)
+		const tools = enabledTools.map((tool) => converter(tool, context))
 
-		return enabledTools.map((tool) => converter(tool, context))
+		// Append the multi_tool_use_parallel meta-tool for Gemini when parallel calling is on.
+		// Gives the model a concrete mechanism to batch independent calls in one turn.
+		const isGemini = context.providerInfo.providerId === "gemini" || context.providerInfo.providerId === "vertex"
+		if (isGemini && context.enableParallelToolCalling) {
+			tools.push(MULTI_TOOL_USE_PARALLEL)
+		}
+
+		return tools
 	}
 }
 

src/core/prompts/system-prompt/spec.ts

@@ -235,6 +235,41 @@ const GOOGLE_TOOL_PARAM_MAP: Record<string, string> = {
 	array: "STRING",
 }
 
+/**
+ * Meta-tool that instructs Gemini to call multiple tools in a single turn.
+ * Mirrors the multi_tool_use.parallel pattern used by Cursor/OpenAI agents.
+ * When called, gemini.ts expands it into individual tool_calls events.
+ */
+export const MULTI_TOOL_USE_PARALLEL: GoogleTool = {
+	name: "multi_tool_use_parallel",
+	description:
+		"Run multiple tools simultaneously. Use whenever you need to call two or more independent tools — do this even if the prompt suggests sequential calls.",
+	parameters: {
+		type: GoogleToolParamType.OBJECT,
+		properties: {
+			tool_uses: {
+				type: GoogleToolParamType.ARRAY,
+				description: "List of tool calls to execute in parallel",
+				items: {
+					type: GoogleToolParamType.OBJECT,
+					properties: {
+						recipient_name: {
+							type: GoogleToolParamType.STRING,
+							description: "Name of the tool to call (e.g. 'read_file', 'search_files')",
+						},
+						parameters: {
+							type: GoogleToolParamType.OBJECT,
+							description: "Parameters to pass to the tool",
+						},
+					},
+					required: ["recipient_name", "parameters"],
+				},
+			},
+		},
+		required: ["tool_uses"],
+	},
+}
+
 /**
  * Converts a ClineToolSpec into a Google Gemini function.
  * Docs: https://ai.google.dev/gemini-api/docs/function-calling
@@ -269,6 +304,13 @@ export function toolSpecFunctionDeclarations(tool: ClineToolSpec, context: Syste
 				type: GOOGLE_TOOL_PARAM_MAP[param.type || "string"] || GoogleToolParamType.OBJECT,
 			}
 
+			if (param.instruction) {
+				const desc = replacer(resolveInstruction(param.instruction, context), context)
+				if (desc) {
+					paramSchema.description = desc
+				}
+			}
+
 			if (param.properties) {
 				paramSchema.properties = {}
 				for (const [key, prop] of Object.entries<any>(param.properties)) {

src/core/prompts/system-prompt/tools/list_code_definition_names.ts

@@ -15,7 +15,7 @@ const generic: ClineToolSpec = {
 		{
 			name: "path",
 			required: true,
-			instruction: `The path of the directory (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}} to list top level source code definitions for.`,
+			instruction: `The path of a directory (not a file) relative to the current working directory {{CWD}}{{MULTI_ROOT_HINT}}. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.`,
 			usage: "Directory path here",
 		},
 		TASK_PROGRESS_PARAMETER,
@@ -32,7 +32,7 @@ const NATIVE_GPT_5: ClineToolSpec = {
 		{
 			name: "path",
 			required: true,
-			instruction: `The path of the directory (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}} to list top level source code definitions for.`,
+			instruction: `The path of a directory (not a file) relative to the current working directory {{CWD}}{{MULTI_ROOT_HINT}}. Lists definitions across all source files in that directory. To inspect a single file, use read_file instead.`,
 		},
 		TASK_PROGRESS_PARAMETER,
 	],

src/core/prompts/system-prompt/tools/read_file.ts

@@ -5,38 +5,48 @@ import { TASK_PROGRESS_PARAMETER } from "../types"
 
 const id = ClineDefaultTool.FILE_READ
 
+const READ_FILE_DESCRIPTION =
+	"Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Returned text lines are prefixed with line labels (e.g. `L1:`, `L2:`). These labels are metadata, not part of the file content. For large files, output is automatically limited to 1000 lines. Use start_line and end_line to read specific sections. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string."
+
+const READ_FILE_PARAMETERS: ClineToolSpec["parameters"] = [
+	{
+		name: "path",
+		required: true,
+		instruction: `The path of the file to read (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}}`,
+		usage: "File path here",
+	},
+	{
+		name: "start_line",
+		required: false,
+		type: "integer",
+		instruction: "The 1-based line number to start reading from (inclusive). Defaults to 1.",
+		usage: "1",
+	},
+	{
+		name: "end_line",
+		required: false,
+		type: "integer",
+		instruction:
+			"The 1-based line number to stop reading at (inclusive). Defaults to start_line + 1000. Use with start_line to read specific sections of large files.",
+		usage: "1000",
+	},
+	TASK_PROGRESS_PARAMETER,
+]
+
 const generic: ClineToolSpec = {
 	variant: ModelFamily.GENERIC,
 	id,
 	name: "read_file",
-	description:
-		"Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.",
-	parameters: [
-		{
-			name: "path",
-			required: true,
-			instruction: `The path of the file to read (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}}`,
-			usage: "File path here",
-		},
-		TASK_PROGRESS_PARAMETER,
-	],
+	description: READ_FILE_DESCRIPTION,
+	parameters: READ_FILE_PARAMETERS,
 }
 
 const NATIVE_GPT_5: ClineToolSpec = {
 	variant: ModelFamily.NATIVE_GPT_5,
 	id,
 	name: "read_file",
-	description:
-		"Request to read the contents of a file at the specified path. Use this when you need to examine the contents of an existing file you do not know the contents of, for example to analyze code, review text files, or extract information from configuration files. Automatically extracts raw text from PDF and DOCX files. May not be suitable for other types of binary files, as it returns the raw content as a string. Do NOT use this tool to list the contents of a directory. Only use this tool on files.",
-	parameters: [
-		{
-			name: "path",
-			required: true,
-			instruction: `The path of the file to read (relative to the current working directory {{CWD}}){{MULTI_ROOT_HINT}}`,
-			usage: "File path here",
-		},
-		TASK_PROGRESS_PARAMETER,
-	],
+	description: READ_FILE_DESCRIPTION,
+	parameters: READ_FILE_PARAMETERS,
 }
 
 const NATIVE_NEXT_GEN: ClineToolSpec = {

src/core/prompts/system-prompt/tools/replace_in_file.ts

@@ -36,7 +36,8 @@ const BASE_DIFF_INSTRUCTIONS = `One or more SEARCH/REPLACE blocks following this
      * Each line must be complete. Never truncate lines mid-way through as this can cause matching failures.
   4. Special operations:
      * To move code: Use two SEARCH/REPLACE blocks (one to delete from original + one to insert at new location)
-     * To delete code: Use empty REPLACE section`
+     * To delete code: Use empty REPLACE section
+  5. If your source context came from read_file and includes line labels (for example, "L42: const x = 1"), do NOT include the "L42: " prefix in SEARCH or REPLACE content. Match only the raw file text.`
 
 const NOTEBOOK_INSTRUCTIONS = `
   5. For Jupyter Notebook (.ipynb) files:

src/core/prompts/system-prompt/variants/gemini-3/overrides.ts

@@ -6,7 +6,15 @@ const GEMINI_3_AGENT_ROLE_TEMPLATE = (_context: SystemPromptContext) =>
 
 const GEMINI_3_TOOL_USE_TEMPLATE = (context: SystemPromptContext) => `TOOL USE
 
-You have access to a set of tools that are executed upon the user's approval.${context.enableParallelToolCalling ? " You may use multiple tools in a single response when the operations are independent (e.g., reading several files, searching in parallel). For dependent operations where one result informs the next, use tools sequentially." : " You should use a single tool at a time and wait for the result before proceeding."} You will receive the results of all tool uses in the user's response.
+You have access to a set of tools that are executed upon the user's approval. You will receive the results of all tool uses in the user's response.
+
+${
+	context.enableParallelToolCalling
+		? `When you need to perform multiple independent operations (reading files, searching, listing directories), you MUST batch them into a single turn using the \`multi_tool_use_parallel\` tool. Do not wait for one result before issuing the next independent call.
+
+Example — reading two files: instead of read_file(a.py) → wait → read_file(b.py), call multi_tool_use_parallel with both read_file calls at once. Only use sequential calls when the second depends on the result of the first.`
+		: `Use a single tool at a time and wait for the result before proceeding.`
+}
 
 When using tools, proceed directly with tool calls. Save explanations for the attempt_completion summary. Both attempt_completion and plan_mode_respond display to the user as assistant messages, so include your message content within the tool call itself rather than duplicating it outside.`
 
@@ -15,7 +23,7 @@ const GEMINI_3_OBJECTIVE_TEMPLATE = (context: SystemPromptContext) => `OBJECTIVE
 You accomplish a given task iteratively, breaking it down into clear steps and working through them methodically.
 
 1. Analyze the user's task and set clear, achievable goals to accomplish it. Prioritize these goals in a logical order.
-2. Work through these goals sequentially, utilizing available tools as necessary. ${context.enableParallelToolCalling ? "You may call multiple independent tools in a single response to work efficiently." : "Use a single tool at a time and wait for the result before proceeding."} Each goal should correspond to a distinct step in your problem-solving process. You will be informed on the work completed and what's remaining as you go.
+2. Work through these goals sequentially, utilizing available tools as necessary. ${context.enableParallelToolCalling ? "Batch all independent tool calls (reads, searches, etc.) via multi_tool_use_parallel — do not issue them one at a time." : "Use a single tool at a time and wait for the result before proceeding."} Each goal should correspond to a distinct step in your problem-solving process. You will be informed on the work completed and what's remaining as you go.
 3. Remember, you have extensive capabilities with access to a wide range of tools that can be used in powerful and clever ways as necessary to accomplish each goal. First, analyze the file structure provided in environment_details to gain context and insights for proceeding effectively. Then, think about which of the provided tools is the most relevant tool to accomplish the user's task. Next, go through each of the required parameters of the relevant tool and determine if the user has directly provided or given enough information to infer a value. When deciding if the parameter can be inferred, carefully consider all the context to see if it supports a specific value. If all of the required parameters are present or can be reasonably inferred, close the thinking tag and proceed with the tool use.${context.yoloModeToggled !== true ? " If one of the values for a required parameter is missing, ask the user to provide the missing parameters using the ask_followup_question tool (use your tools to gather information when possible to avoid unnecessary questions)." : ""} Focus on required parameters only - proceed with defaults for optional parameters.
 4. Before using attempt_completion, verify the task requirements with available tools. Confirm required output files exist, required content and format constraints are satisfied, and no forbidden extra artifacts were introduced. If checks fail, continue working until the result is verifiably correct.
 5. Once you've completed the user's task and verified the result, use the attempt_completion tool to present the result. Provide a CLI command to showcase your work when applicable (e.g., \`open index.html\` for web development).

src/core/prompts/system-prompt/variants/next-gen/template.ts

@@ -69,6 +69,8 @@ export const rules_template = (context: SystemPromptContext) => `RULES
 - Your goal is to try to accomplish the user's task, NOT engage in a back and forth conversation.
 - When writing output files, produce exactly what the task specifies—no extra columns, fields, debug output, or commentary. Match the requested format precisely.
 - When the task specifies numerical thresholds or accuracy targets, verify your result meets the criteria before completing. If close but not passing, iterate rather than declaring completion.
+- When fixing a bug, if existing tests fail after your change, your code is likely wrong. Fix your code to pass the tests rather than modifying test assertions to match your new behavior, unless the user explicitly asks you to update tests.
+- After fixing a bug, verify your change by running the project's existing test suite rather than only a reproduction script you wrote. If you're unsure which tests to run, search for test files related to the code you changed.
 {{BROWSER_RULES}}- NEVER end attempt_completion result with a question or request to engage in further conversation! Formulate the end of your result in a way that is final and does not require further input from the user.
 - You are STRICTLY FORBIDDEN from starting your messages with "Great", "Certainly", "Okay", "Sure". You should NOT be conversational in your responses, but rather direct and to the point. For example you should NOT say "Great, I've updated the CSS" but instead something like "I've updated the CSS". It is important you be clear and technical in your messages.
 - When presented with images, utilize your vision capabilities to thoroughly examine them and extract meaningful information. Incorporate these insights into your thought process as you accomplish the user's task.

src/core/task/tools/handlers/ExecuteCommandToolHandler.ts

@@ -100,7 +100,11 @@ export class ExecuteCommandToolHandler implements IFullyManagedTool {
 		// Validate required parameters
 		if (!command) {
 			config.taskState.consecutiveMistakeCount++
-			return await config.callbacks.sayAndCreateMissingParamError(this.name, "command")
+			await config.callbacks.say(
+				"error",
+				"Cline tried to use execute_command without value for required parameter 'command'. Retrying...",
+			)
+			return formatResponse.toolError(formatResponse.executeCommandMissingCommandError())
 		}
 
 		if (!requiresApprovalRaw) {

src/core/task/tools/handlers/ReadFileToolHandler.ts

@@ -15,6 +15,51 @@ import type { TaskConfig } from "../types/TaskConfig"
 import type { StronglyTypedUIHelpers } from "../types/UIHelpers"
 import { ToolResultUtils } from "../utils/ToolResultUtils"
 
+export const DEFAULT_MAX_LINES = 1000
+const FILE_TRUNCATED_MARKER = "\n\n---\n\n[FILE TRUNCATED:"
+
+/**
+ * Slice file content to the requested line range, add L-prefixed line labels,
+ * and append a continuation hint when the file has more lines to read.
+ */
+export function formatFileContentWithLineNumbers(content: string, startLine?: number, endLine?: number): string {
+	if (!content) {
+		return content
+	}
+
+	// Separate any byte-truncation notice appended by content-limits.ts
+	let body = content
+	let truncationSuffix = ""
+	const truncationIndex = content.indexOf(FILE_TRUNCATED_MARKER)
+	if (truncationIndex !== -1) {
+		body = content.slice(0, truncationIndex)
+		truncationSuffix = content.slice(truncationIndex)
+	}
+
+	const lines = body.split(/\r?\n/)
+	if (body.endsWith("\n") && lines.length > 0) {
+		lines.pop()
+	}
+	const totalLines = lines.length
+
+	const start = Math.max(1, startLine ?? 1)
+	const end = Math.min(totalLines, endLine ?? start + DEFAULT_MAX_LINES - 1)
+
+	const slice = lines.slice(start - 1, end)
+	const labeled = slice.map((line, i) => `L${start + i}: ${line}`).join("\n")
+
+	let suffix = truncationSuffix
+	if (!truncationSuffix) {
+		if (end < totalLines) {
+			suffix = `\n\n(Showing lines ${start}-${end} of ${totalLines} total. Use start_line=${end + 1} to continue reading.)`
+		} else {
+			suffix = `\n\n(File has ${totalLines} lines total.)`
+		}
+	}
+
+	return labeled + suffix
+}
+
 export class ReadFileToolHandler implements IFullyManagedTool {
 	readonly name = ClineDefaultTool.FILE_READ
 
@@ -179,8 +224,12 @@ export class ReadFileToolHandler implements IFullyManagedTool {
 		// Handle image blocks separately - they need to be pushed to userMessageContent
 		if (fileContent.imageBlock) {
 			config.taskState.userMessageContent.push(fileContent.imageBlock)
+			return fileContent.text
 		}
 
-		return fileContent.text
+		const startLine = block.params.start_line ? Number.parseInt(block.params.start_line, 10) : undefined
+		const endLine = block.params.end_line ? Number.parseInt(block.params.end_line, 10) : undefined
+
+		return formatFileContentWithLineNumbers(fileContent.text, startLine, endLine)
 	}
 }

src/core/task/tools/handlers/WriteToFileToolHandler.ts

@@ -114,7 +114,12 @@ export class WriteToFileToolHandler implements IFullyManagedTool {
 		if (block.name === "replace_in_file" && !rawDiff) {
 			config.taskState.consecutiveMistakeCount++
 			await config.services.diffViewProvider.reset()
-			return await config.callbacks.sayAndCreateMissingParamError(block.name, "diff")
+			const relPath = rawRelPath || "unknown"
+			await config.callbacks.say(
+				"error",
+				`Cline tried to use replace_in_file for '${relPath}' without value for required parameter 'diff'. Retrying...`,
+			)
+			return formatResponse.toolError(formatResponse.replaceInFileMissingDiffError(relPath))
 		}
 
 		if (block.name === "write_to_file" && !rawContent) {

src/core/task/tools/handlers/__tests__/ReadFileToolHandler.lineNumbers.test.ts

@@ -0,0 +1,111 @@
+import assert from "node:assert/strict"
+import { describe, it } from "mocha"
+import { DEFAULT_MAX_LINES, formatFileContentWithLineNumbers } from "../ReadFileToolHandler"
+
+describe("formatFileContentWithLineNumbers", () => {
+	describe("line labels", () => {
+		it("adds 1-indexed line prefixes", () => {
+			const result = formatFileContentWithLineNumbers("alpha\nbeta")
+			assert.ok(result.startsWith("L1: alpha\nL2: beta"))
+		})
+
+		it("does not add an extra numbered line for trailing newline", () => {
+			const result = formatFileContentWithLineNumbers("alpha\nbeta\n")
+			assert.ok(result.startsWith("L1: alpha\nL2: beta"))
+			assert.ok(!result.includes("L3:"))
+		})
+
+		it("returns empty content unchanged", () => {
+			const result = formatFileContentWithLineNumbers("")
+			assert.equal(result, "")
+		})
+	})
+
+	describe("chunked reads", () => {
+		const tenLines = Array.from({ length: 10 }, (_, i) => `line${i + 1}`).join("\n")
+
+		it("defaults to reading from line 1", () => {
+			const result = formatFileContentWithLineNumbers(tenLines)
+			assert.ok(result.startsWith("L1: line1\n"))
+		})
+
+		it("respects start_line parameter", () => {
+			const result = formatFileContentWithLineNumbers(tenLines, 5)
+			assert.ok(result.startsWith("L5: line5\n"))
+			assert.ok(!result.includes("L4:"))
+		})
+
+		it("respects start_line and end_line parameters", () => {
+			const result = formatFileContentWithLineNumbers(tenLines, 3, 5)
+			assert.ok(result.startsWith("L3: line3\n"))
+			assert.ok(result.includes("L4: line4\n"))
+			assert.ok(result.includes("L5: line5"))
+			assert.ok(!result.includes("L2:"))
+			assert.ok(!result.includes("L6:"))
+		})
+
+		it("clamps start_line to 1 if below", () => {
+			const result = formatFileContentWithLineNumbers(tenLines, -5, 3)
+			assert.ok(result.startsWith("L1: line1\n"))
+		})
+
+		it("clamps end_line to total lines if beyond", () => {
+			const result = formatFileContentWithLineNumbers(tenLines, 8, 999)
+			assert.ok(result.includes("L10: line10"))
+			assert.ok(!result.includes("L11:"))
+		})
+	})
+
+	describe("continuation hints", () => {
+		const tenLines = Array.from({ length: 10 }, (_, i) => `line${i + 1}`).join("\n")
+
+		it("shows continuation hint when more lines remain", () => {
+			const result = formatFileContentWithLineNumbers(tenLines, 1, 5)
+			assert.ok(result.includes("Showing lines 1-5 of 10 total"))
+			assert.ok(result.includes("start_line=6"))
+		})
+
+		it("shows total-lines footer when entire file is returned", () => {
+			const result = formatFileContentWithLineNumbers(tenLines, 1, 10)
+			assert.ok(result.includes("File has 10 lines total"))
+		})
+
+		it("shows total-lines footer when file fits within default limit", () => {
+			const result = formatFileContentWithLineNumbers(tenLines)
+			assert.ok(result.includes("File has 10 lines total"))
+		})
+	})
+
+	describe("default max lines", () => {
+		const bigContent = Array.from({ length: DEFAULT_MAX_LINES + 500 }, (_, i) => `row${i + 1}`).join("\n")
+
+		it("limits output to DEFAULT_MAX_LINES when no end_line given", () => {
+			const result = formatFileContentWithLineNumbers(bigContent)
+			assert.ok(result.includes(`L1: row1`))
+			assert.ok(result.includes(`L${DEFAULT_MAX_LINES}: row${DEFAULT_MAX_LINES}`))
+			assert.ok(!result.includes(`L${DEFAULT_MAX_LINES + 1}:`))
+			assert.ok(result.includes(`start_line=${DEFAULT_MAX_LINES + 1}`))
+		})
+
+		it("allows reading beyond default limit with explicit end_line", () => {
+			const endLine = DEFAULT_MAX_LINES + 200
+			const result = formatFileContentWithLineNumbers(bigContent, 1, endLine)
+			assert.ok(result.includes(`L${endLine}: row${endLine}`))
+		})
+	})
+
+	describe("byte truncation interaction", () => {
+		it("preserves truncation notice without numbering it", () => {
+			const input =
+				"alpha\nbeta\n\n---\n\n[FILE TRUNCATED: This content is 1.0 MB but only the first 400 KB is shown (600 KB truncated).]"
+			const result = formatFileContentWithLineNumbers(input)
+			assert.ok(result.startsWith("L1: alpha\nL2: beta"))
+			assert.ok(
+				result.includes(
+					"[FILE TRUNCATED: This content is 1.0 MB but only the first 400 KB is shown (600 KB truncated).]",
+				),
+			)
+			assert.ok(!result.includes("L3:"))
+		})
+	})
+})

src/services/glob/__tests__/list-files.test.ts

@@ -0,0 +1,35 @@
+import * as fs from "fs/promises"
+import { after, describe, it } from "mocha"
+import * as os from "os"
+import * as path from "path"
+import "should"
+import { listFiles } from "../list-files"
+
+describe("listFiles", () => {
+	const tmpDir = path.join(os.tmpdir(), `cline-list-files-test-${Math.random().toString(36).slice(2)}`)
+
+	after(async () => {
+		await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => undefined)
+	})
+
+	it("returns empty result when cwd points to a file", async () => {
+		await fs.mkdir(tmpDir, { recursive: true })
+		const filePath = path.join(tmpDir, "single-file.ts")
+		await fs.writeFile(filePath, "export const x = 1\n")
+
+		const [files, didHitLimit] = await listFiles(filePath, false, 200)
+
+		files.should.deepEqual([])
+		didHitLimit.should.equal(false)
+	})
+
+	it("still lists files when cwd points to a directory", async () => {
+		await fs.mkdir(tmpDir, { recursive: true })
+		const nestedFile = path.join(tmpDir, "index.ts")
+		await fs.writeFile(nestedFile, "export const ok = true\n")
+
+		const [files] = await listFiles(tmpDir, false, 200)
+
+		files.should.containEql(nestedFile)
+	})
+})

src/services/glob/list-files.ts

@@ -1,4 +1,5 @@
 import { workspaceResolver } from "@core/workspace"
+import { isDirectory } from "@utils/fs"
 import { arePathsEqual } from "@utils/path"
 import { globby, Options } from "globby"
 import * as os from "os"
@@ -67,8 +68,13 @@ export async function listFiles(dirPath: string, recursive: boolean, limit: numb
 		return [[], false]
 	}
 
+	// globby requires cwd to point to a directory
+	if (!(await isDirectory(absolutePath))) {
+		return [[], false]
+	}
+
 	const options: Options = {
-		cwd: dirPath,
+		cwd: absolutePath,
 		dot: true, // do not ignore hidden files/directories
 		absolute: true,
 		markDirectories: true, // Append a / on any directories matched

src/services/tree-sitter/__tests__/index.test.ts

@@ -0,0 +1,31 @@
+import * as fs from "fs/promises"
+import { after, describe, it } from "mocha"
+import * as os from "os"
+import * as path from "path"
+import "should"
+import { parseSourceCodeForDefinitionsTopLevel } from ".."
+
+describe("parseSourceCodeForDefinitionsTopLevel", () => {
+	const tmpDir = path.join(os.tmpdir(), `cline-tree-sitter-test-${Math.random().toString(36).slice(2)}`)
+
+	after(async () => {
+		await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => undefined)
+	})
+
+	it("returns file-specific error when path points to a file", async () => {
+		await fs.mkdir(tmpDir, { recursive: true })
+		const filePath = path.join(tmpDir, "backends.py")
+		await fs.writeFile(filePath, "class Backend:\n    pass\n")
+
+		const result = await parseSourceCodeForDefinitionsTopLevel(filePath)
+
+		result.should.containEql("is a file, not a directory")
+		result.should.containEql("read_file")
+	})
+
+	it("returns directory-not-found error for non-existent path", async () => {
+		const result = await parseSourceCodeForDefinitionsTopLevel(path.join(tmpDir, "nonexistent"))
+
+		result.should.equal("This directory does not exist or you do not have permission to access it.")
+	})
+})

src/services/tree-sitter/index.ts

@@ -1,6 +1,6 @@
 import { ClineIgnoreController } from "@core/ignore/ClineIgnoreController"
 import { listFiles } from "@services/glob/list-files"
-import { fileExistsAtPath } from "@utils/fs"
+import { fileExistsAtPath, isDirectory } from "@utils/fs"
 import * as fs from "fs/promises"
 import * as path from "path"
 import { Logger } from "@/shared/services/Logger"
@@ -11,9 +11,12 @@ export async function parseSourceCodeForDefinitionsTopLevel(
 	dirPath: string,
 	clineIgnoreController?: ClineIgnoreController,
 ): Promise<string> {
-	// check if the path exists
-	const dirExists = await fileExistsAtPath(path.resolve(dirPath))
-	if (!dirExists) {
+	// ensure input is a directory before listing files
+	const resolvedPath = path.resolve(dirPath)
+	if (!(await isDirectory(resolvedPath))) {
+		if (await fileExistsAtPath(resolvedPath)) {
+			return `The provided path is a file, not a directory. To view this file use read_file instead, or pass the parent directory to list_code_definition_names.`
+		}
 		return "This directory does not exist or you do not have permission to access it."
 	}