feat: add search_and_replace tool for pattern-based file modifications

- Add new search_and_replace tool implementation
- Update core files to support search/replace operations
- Add tool description and documentation
- Initialize cline_docs directory

Author: samhvw8

src/core/Cline.ts

@@ -966,9 +966,10 @@ export class Cline {
 						case "apply_diff":
 							return `[${block.name} for '${block.params.path}']`
 						case "search_files":
-							return `[${block.name} for '${block.params.regex}'${
-								block.params.file_pattern ? ` in '${block.params.file_pattern}'` : ""
-							}]`
+							return `[${block.name} for '${block.params.regex}'${block.params.file_pattern ? ` in '${block.params.file_pattern}'` : ""
+								}]`
+						case "search_and_replace":
+							return `[${block.name} for '${block.params.path}`
 						case "list_files":
 							return `[${block.name} for '${block.params.path}']`
 						case "list_code_definition_names":
@@ -1285,6 +1286,175 @@ export class Cline {
 							break
 						}
 					}
+
+					case "search_and_replace": {
+						const relPath: string | undefined = block.params.path
+						const operations: string | undefined = block.params.operations
+
+						const sharedMessageProps: ClineSayTool = {
+							tool: "appliedDiff",
+							path: getReadablePath(cwd, removeClosingTag("path", relPath)),
+						}
+
+						try {
+							if (block.partial) {
+								const partialMessage = JSON.stringify({
+									path: removeClosingTag("path", relPath),
+									operations: removeClosingTag("operations", operations)
+								})
+								await this.ask("tool", partialMessage, block.partial).catch(() => { })
+								break
+							} else {
+								if (!relPath) {
+									this.consecutiveMistakeCount++
+									pushToolResult(await this.sayAndCreateMissingParamError("search_and_replace", "path"))
+									break
+								}
+								if (!operations) {
+									this.consecutiveMistakeCount++
+									pushToolResult(await this.sayAndCreateMissingParamError("search_and_replace", "operations"))
+									break
+								}
+
+								const absolutePath = path.resolve(cwd, relPath)
+								const fileExists = await fileExistsAtPath(absolutePath)
+
+								if (!fileExists) {
+									this.consecutiveMistakeCount++
+									const formattedError = `File does not exist at path: ${absolutePath}\n\n<error_details>\nThe specified file could not be found. Please verify the file path and try again.\n</error_details>`
+									await this.say("error", formattedError)
+									pushToolResult(formattedError)
+									break
+								}
+
+
+
+								let parsedOperations: Array<{
+									search: string
+									replace: string
+									start_line?: number
+									end_line?: number
+									use_regex?: boolean
+									ignore_case?: boolean
+									regex_flags?: string
+								}>
+
+								try {
+									parsedOperations = JSON.parse(operations)
+									if (!Array.isArray(parsedOperations)) {
+										throw new Error("Operations must be an array")
+									}
+								} catch (error) {
+									this.consecutiveMistakeCount++
+									await this.say(
+										"error",
+										`Failed to parse operations JSON: ${error.message}`
+									)
+									pushToolResult(formatResponse.toolError("Invalid operations JSON format"))
+									break
+								}
+
+								// Read the original file content
+								const fileContent = await fs.readFile(absolutePath, 'utf-8')
+								const lines = fileContent.split('\n')
+								let newContent = fileContent
+
+								// Apply each search/replace operation
+								for (const op of parsedOperations) {
+									const searchPattern = op.use_regex
+										? new RegExp(op.search, op.regex_flags || (op.ignore_case ? 'gi' : 'g'))
+										: new RegExp(escapeRegExp(op.search), op.ignore_case ? 'gi' : 'g')
+
+
+
+									if (op.start_line || op.end_line) {
+										// Line-restricted replacement
+										const startLine = (op.start_line || 1) - 1
+										const endLine = (op.end_line || lines.length) - 1
+
+										const beforeLines = lines.slice(0, startLine)
+										const targetLines = lines.slice(startLine, endLine + 1)
+										const afterLines = lines.slice(endLine + 1)
+
+										const modifiedLines = targetLines.map(line =>
+											line.replace(searchPattern, op.replace)
+										)
+
+										newContent = [
+											...beforeLines,
+											...modifiedLines,
+											...afterLines
+										].join('\n')
+									} else {
+										// Global replacement
+										newContent = newContent.replace(searchPattern, op.replace)
+									}
+								}
+
+								this.consecutiveMistakeCount = 0
+
+								// Show diff preview
+								const diff = formatResponse.createPrettyPatch(
+									relPath,
+									this.diffViewProvider.originalContent,
+									newContent,
+								)
+
+								if (!diff) {
+									pushToolResult(`No changes needed for '${relPath}'`)
+									break
+								}
+
+								await this.diffViewProvider.open(relPath);
+								await this.diffViewProvider.update(newContent, true);
+								this.diffViewProvider.scrollToFirstDiff();
+
+								const completeMessage = JSON.stringify({
+									...sharedMessageProps,
+									diff: diff,
+								} satisfies ClineSayTool)
+
+								const didApprove = await askApproval("tool", completeMessage)
+								if (!didApprove) {
+									await this.diffViewProvider.revertChanges() // This likely handles closing the diff view
+									break
+								}
+
+								const { newProblemsMessage, userEdits, finalContent } =
+									await this.diffViewProvider.saveChanges()
+								this.didEditFile = true // used to determine if we should wait for busy terminal to update before sending api request
+								if (userEdits) {
+									await this.say(
+										"user_feedback_diff",
+										JSON.stringify({
+											tool: fileExists ? "editedExistingFile" : "newFileCreated",
+											path: getReadablePath(cwd, relPath),
+											diff: userEdits,
+										} satisfies ClineSayTool),
+									)
+									pushToolResult(
+										`The user made the following updates to your content:\n\n${userEdits}\n\n` +
+										`The updated content, which includes both your original modifications and the user's edits, has been successfully saved to ${relPath.toPosix()}. Here is the full, updated content of the file, including line numbers:\n\n` +
+										`<final_file_content path="${relPath.toPosix()}">\n${addLineNumbers(finalContent || '')}\n</final_file_content>\n\n` +
+										`Please note:\n` +
+										`1. You do not need to re-write the file with these changes, as they have already been applied.\n` +
+										`2. Proceed with the task using this updated file content as the new baseline.\n` +
+										`3. If the user's edits have addressed part of the task or changed the requirements, adjust your approach accordingly.` +
+										`${newProblemsMessage}`,
+									)
+								} else {
+									pushToolResult(`Changes successfully applied to ${relPath.toPosix()}:\n\n${newProblemsMessage}`)
+								}
+								await this.diffViewProvider.reset()
+								break
+							}
+						} catch (error) {
+							await handleError("applying search and replace", error)
+							await this.diffViewProvider.reset()
+							break
+						}
+					}
+
 					case "apply_diff": {
 						const relPath: string | undefined = block.params.path
 						const diffContent: string | undefined = block.params.diff
@@ -2588,4 +2758,8 @@ export class Cline {
 
 		return `<environment_details>\n${details.trim()}\n</environment_details>`
 	}
+}
+
+function escapeRegExp(string: string): string {
+	return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }

src/core/assistant-message/index.ts

@@ -21,6 +21,7 @@ export const toolUseNames = [
 	"access_mcp_resource",
 	"ask_followup_question",
 	"attempt_completion",
+	"search_and_replace"
 ] as const
 
 // Converts array of tool call names into a union type ("execute_command" | "read_file" | ...)
@@ -47,6 +48,7 @@ export const toolParamNames = [
 	"diff",
 	"start_line",
 	"end_line",
+	"operations"
 ] as const
 
 export type ToolParamName = (typeof toolParamNames)[number]

src/core/prompts/sections/rules.ts

@@ -15,6 +15,7 @@ RULES
 - Before using the execute_command tool, you must first think about the SYSTEM INFORMATION context provided to understand the user's environment and tailor your commands to ensure they are compatible with their system. You must also consider if the command you need to run should be executed in a specific directory outside of the current working directory '${cwd.toPosix()}', and if so prepend with \`cd\`'ing into that directory && then executing the command (as one command since you are stuck operating from '${cwd.toPosix()}'). For example, if you needed to run \`npm install\` in a project outside of '${cwd.toPosix()}', you would need to prepend with a \`cd\` i.e. pseudocode for this would be \`cd (path to project) && (command, in this case npm install)\`.
 - When using the search_files tool, craft your regex patterns carefully to balance specificity and flexibility. Based on the user's task you may use it to find code patterns, TODO comments, function definitions, or any text-based information across the project. The results include context, so analyze the surrounding code to better understand the matches. Leverage the search_files tool in combination with other tools for more comprehensive analysis. For example, use it to find specific code patterns, then use read_file to examine the full context of interesting matches before using write_to_file to make informed changes.
 - When creating a new project (such as an app, website, or any software project), organize all new files within a dedicated project directory unless the user specifies otherwise. Use appropriate file paths when writing files, as the write_to_file tool will automatically create any necessary directories. Structure the project logically, adhering to best practices for the specific type of project being created. Unless otherwise specified, new projects should be easily run without additional setup, for example most projects can be built in HTML, CSS, and JavaScript - which you can open in a browser.
+- You should use search_and_replace when suggesting edits that involve either small individual changes or pattern-based modifications that need to be applied consistently across a file.
 ${diffStrategy ? "- You should use apply_diff instead of write_to_file when making changes to existing files since it is much faster and easier to apply a diff than to write the entire file again. Only use write_to_file to edit files when apply_diff has failed repeatedly to apply the diff." : "- When you want to modify a file, use the write_to_file tool directly with the desired content. You do not need to display the content before using the tool."}
 - Be sure to consider the type of project (e.g. Python, JavaScript, web application) when determining the appropriate structure and files to include. Also consider what files may be most relevant to accomplishing the task, for example looking at a project's manifest file would help you understand the project's dependencies, which you could incorporate into any code you write.
 - When making changes to code, always consider the context in which the code is being used. Ensure that your changes are compatible with the existing codebase and that they follow the project's coding standards and best practices.

src/core/prompts/tools/index.ts

@@ -9,6 +9,7 @@ import { getAskFollowupQuestionDescription } from './ask-followup-question'
 import { getAttemptCompletionDescription } from './attempt-completion'
 import { getUseMcpToolDescription } from './use-mcp-tool'
 import { getAccessMcpResourceDescription } from './access-mcp-resource'
+import { getSearchAndReplaceDescription } from './search-and-replace'
 import { DiffStrategy } from '../../diff/DiffStrategy'
 import { McpHub } from '../../../services/mcp/McpHub'
 import { Mode, codeMode, askMode } from '../modes'
@@ -59,6 +60,9 @@ export function getToolDescriptionsForMode(
     if (hasAllowedTool(allowedTools, 'list_code_definition_names')) {
         descriptions.push(getListCodeDefinitionNamesDescription(cwd));
     }
+    if (hasAllowedTool(allowedTools, 'search_and_replace')) {
+        descriptions.push(getSearchAndReplaceDescription(cwd));
+    }
 
     // Browser actions
     if (supportsComputerUse && hasAllowedTool(allowedTools, 'browser_action')) {
@@ -97,5 +101,6 @@ export {
     getAskFollowupQuestionDescription,
     getAttemptCompletionDescription,
     getUseMcpToolDescription,
-    getAccessMcpResourceDescription
+    getAccessMcpResourceDescription,
+    getSearchAndReplaceDescription
 }

src/core/prompts/tools/search-and-replace.ts

@@ -0,0 +1,53 @@
+export function getSearchAndReplaceDescription(cwd: string): string {
+    return `## search_and_replace
+Description: Request to perform search and replace operations on a file. Each operation can specify a search pattern (string or regex) and replacement text, with optional line range restrictions and regex flags. Shows a diff preview before applying changes.
+Parameters:
+- path: (required) The path of the file to modify (relative to the current working directory ${cwd})
+- operations: (required) A JSON array of search/replace operations. Each operation is an object with:
+    * search: (required) The text or pattern to search for
+    * replace: (required) The text to replace matches with
+    * start_line: (optional) Starting line number for restricted replacement
+    * end_line: (optional) Ending line number for restricted replacement
+    * use_regex: (optional) Whether to treat search as a regex pattern
+    * ignore_case: (optional) Whether to ignore case when matching
+    * regex_flags: (optional) Additional regex flags when use_regex is true
+
+Usage:
+<search_and_replace>
+<path>File path here</path>
+<operations>[
+  {
+    "search": "text to find",
+    "replace": "replacement text",
+    "start_line": 1,
+    "end_line": 10
+  }
+]</operations>
+</search_and_replace>
+
+Example: Replace "foo" with "bar" in lines 1-10 of example.ts
+<search_and_replace>
+<path>example.ts</path>
+<operations>[
+  {
+    "search": "foo",
+    "replace": "bar",
+    "start_line": 1,
+    "end_line": 10
+  }
+]</operations>
+</search_and_replace>
+
+Example: Replace all occurrences of "old" with "new" using regex
+<search_and_replace>
+<path>example.ts</path>
+<operations>[
+  {
+    "search": "old\\w+",
+    "replace": "new$&",
+    "use_regex": true,
+    "ignore_case": true
+  }
+]</operations>
+</search_and_replace>`
+}

src/core/tool-lists.ts

@@ -24,7 +24,8 @@ export const CODE_ALLOWED_TOOLS = [
     'use_mcp_tool',
     'access_mcp_resource',
     'ask_followup_question',
-    'attempt_completion'
+    'attempt_completion',
+    'search_and_replace'
 ] as const;
 
 // Tool name types for type safety