feat: rename search_and_replace tool to edit and unify edit-family UI (#11296)

Author: hannesrudolph

packages/core/src/custom-tools/__tests__/custom-tool-registry.spec.ts

@@ -281,7 +281,7 @@ describe("CustomToolRegistry", () => {
 			const result = await registry.loadFromDirectory(TEST_FIXTURES_DIR)
 
 			expect(result.loaded).toContain("cached")
-		}, 30000)
+		}, 120_000)
 	})
 
 	describe.sequential("loadFromDirectories", () => {

packages/types/src/tool.ts

@@ -20,6 +20,7 @@ export const toolNames = [
 	"read_command_output",
 	"write_to_file",
 	"apply_diff",
+	"edit",
 	"search_and_replace",
 	"search_replace",
 	"edit_file",

src/core/assistant-message/NativeToolCallParser.ts

@@ -599,11 +599,18 @@ export class NativeToolCallParser {
 				}
 				break
 
+			case "edit":
 			case "search_and_replace":
-				if (partialArgs.path !== undefined || partialArgs.operations !== undefined) {
+				if (
+					partialArgs.file_path !== undefined ||
+					partialArgs.old_string !== undefined ||
+					partialArgs.new_string !== undefined
+				) {
 					nativeArgs = {
-						path: partialArgs.path,
-						operations: partialArgs.operations,
+						file_path: partialArgs.file_path,
+						old_string: partialArgs.old_string,
+						new_string: partialArgs.new_string,
+						replace_all: this.coerceOptionalBoolean(partialArgs.replace_all),
 					}
 				}
 				break
@@ -806,11 +813,18 @@ export class NativeToolCallParser {
 					}
 					break
 
+				case "edit":
 				case "search_and_replace":
-					if (args.path !== undefined && args.operations !== undefined && Array.isArray(args.operations)) {
+					if (
+						args.file_path !== undefined &&
+						args.old_string !== undefined &&
+						args.new_string !== undefined
+					) {
 						nativeArgs = {
-							path: args.path,
-							operations: args.operations,
+							file_path: args.file_path,
+							old_string: args.old_string,
+							new_string: args.new_string,
+							replace_all: this.coerceOptionalBoolean(args.replace_all),
 						} as NativeArgsFor<TName>
 					}
 					break

src/core/assistant-message/__tests__/presentAssistantMessage-custom-tool.spec.ts

@@ -2,6 +2,7 @@
 
 import { describe, it, expect, beforeEach, vi } from "vitest"
 import { presentAssistantMessage } from "../presentAssistantMessage"
+import { validateToolUse } from "../../tools/validateToolUse"
 
 // Mock dependencies
 vi.mock("../../task/Task")
@@ -301,6 +302,44 @@ describe("presentAssistantMessage - Custom Tool Recording", () => {
 		})
 	})
 
+	describe("Validation requirements", () => {
+		it("normalizes disabledTools aliases before validateToolUse", async () => {
+			const toolCallId = "tool_call_validation_alias_123"
+			mockTask.assistantMessageContent = [
+				{
+					type: "tool_use",
+					id: toolCallId,
+					name: "some_unknown_tool",
+					params: {},
+					partial: false,
+				},
+			]
+
+			mockTask.providerRef = {
+				deref: () => ({
+					getState: vi.fn().mockResolvedValue({
+						mode: "code",
+						customModes: [],
+						experiments: {
+							customTools: false,
+						},
+						disabledTools: ["search_and_replace"],
+					}),
+				}),
+			}
+
+			await presentAssistantMessage(mockTask)
+
+			const validateToolUseMock = vi.mocked(validateToolUse)
+			expect(validateToolUseMock).toHaveBeenCalled()
+			const toolRequirements = validateToolUseMock.mock.calls[0][3]
+			expect(toolRequirements).toMatchObject({
+				search_and_replace: false,
+				edit: false,
+			})
+		})
+	})
+
 	describe("Partial blocks", () => {
 		it("should not record usage for partial custom tool blocks", async () => {
 			mockTask.assistantMessageContent = [

src/core/assistant-message/presentAssistantMessage.ts

@@ -18,7 +18,7 @@ import { listFilesTool } from "../tools/ListFilesTool"
 import { readFileTool } from "../tools/ReadFileTool"
 import { readCommandOutputTool } from "../tools/ReadCommandOutputTool"
 import { writeToFileTool } from "../tools/WriteToFileTool"
-import { searchAndReplaceTool } from "../tools/SearchAndReplaceTool"
+import { editTool } from "../tools/EditTool"
 import { searchReplaceTool } from "../tools/SearchReplaceTool"
 import { editFileTool } from "../tools/EditFileTool"
 import { applyPatchTool } from "../tools/ApplyPatchTool"
@@ -291,18 +291,6 @@ export async function presentAssistantMessage(cline: Task) {
 				// Strip any streamed <thinking> tags from text output.
 				content = content.replace(/<thinking>\s?/g, "")
 				content = content.replace(/\s?<\/thinking>/g, "")
-
-				// Tool calling is native-only. If the model emits XML-style tool tags in a text block,
-				// fail fast with a clear error.
-				if (containsXmlToolMarkup(content)) {
-					const errorMessage =
-						"XML tool calls are no longer supported. Remove any XML tool markup (e.g. <read_file>...</read_file>) and use native tool calling instead."
-					cline.consecutiveMistakeCount++
-					await cline.say("error", errorMessage)
-					cline.userMessageContent.push({ type: "text", text: errorMessage })
-					cline.didAlreadyUseTool = true
-					break
-				}
 			}
 
 			await cline.say("text", content, undefined, block.partial)
@@ -357,8 +345,9 @@ export async function presentAssistantMessage(cline: Task) {
 						return `[${block.name} for '${block.params.regex}'${
 							block.params.file_pattern ? ` in '${block.params.file_pattern}'` : ""
 						}]`
+					case "edit":
 					case "search_and_replace":
-						return `[${block.name} for '${block.params.path}']`
+						return `[${block.name} for '${block.params.file_path}']`
 					case "search_replace":
 						return `[${block.name} for '${block.params.file_path}']`
 					case "edit_file":
@@ -629,6 +618,8 @@ export async function presentAssistantMessage(cline: Task) {
 						disabledTools?.reduce(
 							(acc: Record<string, boolean>, tool: string) => {
 								acc[tool] = false
+								const resolvedToolName = resolveToolAlias(tool)
+								acc[resolvedToolName] = false
 								return acc
 							},
 							{} as Record<string, boolean>,
@@ -739,9 +730,10 @@ export async function presentAssistantMessage(cline: Task) {
 						pushToolResult,
 					})
 					break
+				case "edit":
 				case "search_and_replace":
 					await checkpointSaveAndMark(cline)
-					await searchAndReplaceTool.handle(cline, block as ToolUse<"search_and_replace">, {
+					await editTool.handle(cline, block as ToolUse<"edit">, {
 						askApproval,
 						handleError,
 						pushToolResult,
@@ -1040,47 +1032,3 @@ async function checkpointSaveAndMark(task: Task) {
 		console.error(`[Task#presentAssistantMessage] Error saving checkpoint: ${error.message}`, error)
 	}
 }
-
-function containsXmlToolMarkup(text: string): boolean {
-	// Keep this intentionally narrow: only reject XML-style tool tags matching our tool names.
-	// Avoid regex so we don't keep legacy XML parsing artifacts around.
-	// Note: This is a best-effort safeguard; tool_use blocks without an id are rejected elsewhere.
-
-	// First, strip out content inside markdown code fences to avoid false positives
-	// when users paste documentation or examples containing tool tag references.
-	// This handles both fenced code blocks (```) and inline code (`).
-	const textWithoutCodeBlocks = text
-		.replace(/```[\s\S]*?```/g, "") // Remove fenced code blocks
-		.replace(/`[^`]+`/g, "") // Remove inline code
-
-	const lower = textWithoutCodeBlocks.toLowerCase()
-	if (!lower.includes("<") || !lower.includes(">")) {
-		return false
-	}
-
-	const toolNames = [
-		"access_mcp_resource",
-		"apply_diff",
-		"apply_patch",
-		"ask_followup_question",
-		"attempt_completion",
-		"browser_action",
-		"codebase_search",
-		"edit_file",
-		"execute_command",
-		"generate_image",
-		"list_files",
-		"new_task",
-		"read_command_output",
-		"read_file",
-		"search_and_replace",
-		"search_files",
-		"search_replace",
-		"switch_mode",
-		"update_todo_list",
-		"use_mcp_tool",
-		"write_to_file",
-	] as const
-
-	return toolNames.some((name) => lower.includes(`<${name}`) || lower.includes(`</${name}`))
-}

src/core/prompts/tools/__tests__/filter-tools-for-mode.spec.ts

@@ -22,6 +22,7 @@ describe("filterNativeToolsForMode - disabledTools", () => {
 		makeTool("write_to_file"),
 		makeTool("browser_action"),
 		makeTool("apply_diff"),
+		makeTool("edit"),
 	]
 
 	it("removes tools listed in settings.disabledTools", () => {
@@ -77,4 +78,19 @@ describe("filterNativeToolsForMode - disabledTools", () => {
 		expect(resultNames).not.toContain("browser_action")
 		expect(resultNames).toContain("read_file")
 	})
+
+	it("disables canonical tool when disabledTools contains alias name", () => {
+		const settings = {
+			disabledTools: ["search_and_replace"],
+			modelInfo: {
+				includedTools: ["search_and_replace"],
+			},
+		}
+
+		const result = filterNativeToolsForMode(nativeTools, "code", undefined, undefined, undefined, settings)
+
+		const resultNames = result.map((t) => (t as any).function.name)
+		expect(resultNames).not.toContain("search_and_replace")
+		expect(resultNames).not.toContain("edit")
+	})
 })

src/core/prompts/tools/filter-tools-for-mode.ts

@@ -299,7 +299,10 @@ export function filterNativeToolsForMode(
 	// Remove tools that are explicitly disabled via the disabledTools setting
 	if (settings?.disabledTools?.length) {
 		for (const toolName of settings.disabledTools) {
-			allowedToolNames.delete(toolName)
+			// Normalize aliases so disabling a legacy alias (e.g. "search_and_replace")
+			// also disables the canonical tool (e.g. "edit").
+			const resolvedToolName = resolveToolAlias(toolName)
+			allowedToolNames.delete(resolvedToolName)
 		}
 	}
 

src/core/prompts/tools/native-tools/edit.ts

@@ -0,0 +1,48 @@
+import type OpenAI from "openai"
+
+const EDIT_DESCRIPTION = `Performs exact string replacements in files.
+
+Usage:
+- You must use your \`Read\` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
+- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- The edit will FAIL if \`old_string\` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use \`replace_all\` to change every instance of \`old_string\`.
+- Use \`replace_all\` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.`
+
+const edit = {
+	type: "function",
+	function: {
+		name: "edit",
+		description: EDIT_DESCRIPTION,
+		parameters: {
+			type: "object",
+			properties: {
+				file_path: {
+					type: "string",
+					description: "The path of the file to edit (relative to the working directory)",
+				},
+				old_string: {
+					type: "string",
+					description:
+						"The exact text to find in the file. Must match exactly, including all whitespace, indentation, and line endings.",
+				},
+				new_string: {
+					type: "string",
+					description:
+						"The replacement text that will replace old_string. Must include all necessary whitespace and indentation.",
+				},
+				replace_all: {
+					type: "boolean",
+					description:
+						"When true, replaces ALL occurrences of old_string in the file. When false (default), only replaces the first occurrence and errors if multiple matches exist.",
+					default: false,
+				},
+			},
+			required: ["file_path", "old_string", "new_string"],
+			additionalProperties: false,
+		},
+	},
+} satisfies OpenAI.Chat.ChatCompletionTool
+
+export default edit

src/core/prompts/tools/native-tools/index.ts

@@ -6,6 +6,7 @@ import askFollowupQuestion from "./ask_followup_question"
 import attemptCompletion from "./attempt_completion"
 import browserAction from "./browser_action"
 import codebaseSearch from "./codebase_search"
+import editTool from "./edit"
 import executeCommand from "./execute_command"
 import generateImage from "./generate_image"
 import listFiles from "./list_files"
@@ -14,7 +15,6 @@ import readCommandOutput from "./read_command_output"
 import { createReadFileTool, type ReadFileToolOptions } from "./read_file"
 import runSlashCommand from "./run_slash_command"
 import skill from "./skill"
-import searchAndReplace from "./search_and_replace"
 import searchReplace from "./search_replace"
 import edit_file from "./edit_file"
 import searchFiles from "./search_files"
@@ -63,9 +63,9 @@ export function getNativeTools(options: NativeToolsOptions = {}): OpenAI.Chat.Ch
 		createReadFileTool(readFileOptions),
 		runSlashCommand,
 		skill,
-		searchAndReplace,
 		searchReplace,
 		edit_file,
+		editTool,
 		searchFiles,
 		switchMode,
 		updateTodoList,