Add stringent search_replace tool for local agent (#2367)

e2e-tests/fixtures/engine/local-agent/search-replace.ts

+import type { LocalAgentFixture } from "../../../../testing/fake-llm-server/localAgentTypes";
+
+export const fixture: LocalAgentFixture = {
+  description: "Use search_replace to make a targeted edit to a file",
+  turns: [
+    {
+      text: "Let me first read the file to see its contents.",
+      toolCalls: [
+        {
+          name: "read_file",
+          args: {
+            path: "src/App.tsx",
+          },
+        },
+      ],
+    },
+    {
+      text: "Now I'll use search_replace to update the text with proper context.",
+      toolCalls: [
+        {
+          name: "search_replace",
+          args: {
+            file_path: "src/App.tsx",
+            // NOTE: This old_string must exactly match the content of the 'minimal' template's src/App.tsx
+            // If the minimal template changes, this fixture must be updated accordingly
+            old_string: `const App = () => <div>Minimal imported app</div>;
+
+export default App;`,
+            new_string: `const App = () => <div>Updated via search_replace</div>;
+
+export default App;`,
+          },
+        },
+      ],
+    },
+    {
+      text: "Done! I've updated the message using search_replace. The edit was applied successfully.",
+    },
+  ],
+};

e2e-tests/local_agent_search_replace.spec.ts

+import { expect } from "@playwright/test";
+import { testSkipIfWindows } from "./helpers/test_helper";
+
+/**
+ * E2E tests for the search_replace agent tool
+ * Tests targeted file editing with the strict search_replace tool
+ */
+
+testSkipIfWindows("local-agent - search_replace edit", async ({ po }) => {
+  await po.setUpDyadPro({ localAgent: true });
+  await po.importApp("minimal");
+  await po.selectLocalAgentMode();
+
+  await po.sendPrompt("tc=local-agent/search-replace");
+
+  // Verify the search_replace output is shown
+  await expect(po.page.getByTestId("dyad-search-replace")).toBeVisible();
+
+  await po.snapshotMessages();
+  await po.snapshotAppFiles({
+    name: "after-search-replace",
+    files: ["src/App.tsx"],
+  });
+});

e2e-tests/snapshots/local_agent_auto.spec.ts_local-agent---auto-model-1.txt

@@ -4,7 +4,7 @@
     "input": [
       {
         "role": "developer",
-        "content": "\n<role>\nYou are Dyad, an AI assistant that creates and modifies web applications. You assist users by chatting with them and making changes to their code in real-time. You understand that users can see a live preview of their application in an iframe on the right side of the screen while you make code changes.\nYou make efficient and effective changes to codebases while following best practices for maintainability and readability. You take pride in keeping things simple and elegant. You are friendly and helpful, always aiming to provide clear explanations. \n</role>\n\n<app_commands>\nDo *not* tell the user to run shell commands. Instead, they can do one of the following commands in the UI:\n\n- **Rebuild**: This will rebuild the app from scratch. First it deletes the node_modules folder and then it re-installs the npm packages and then starts the app server.\n- **Restart**: This will restart the app server.\n- **Refresh**: This will refresh the app preview page.\n\nYou can suggest one of these commands by using the <dyad-command> tag like this:\n<dyad-command type=\"rebuild\"></dyad-command>\n<dyad-command type=\"restart\"></dyad-command>\n<dyad-command type=\"refresh\"></dyad-command>\n\nIf you output one of these commands, tell the user to look for the action button above the chat input.\n</app_commands>\n\n<general_guidelines>\n- Always reply to the user in the same language they are using.\n- Before proceeding with any code edits, check whether the user's request has already been implemented. If the requested change has already been made in the codebase, point this out to the user, e.g., \"This feature is already implemented as described.\"\n- Only edit files that are related to the user's request and leave all other files alone.\n- All edits you make on the codebase will directly be built and rendered, therefore you should NEVER make partial changes like letting the user know that they should implement some components or partially implementing features.\n- If a user asks for many features at once, implement as many as possible within a reasonable response. Each feature you implement must be FULLY FUNCTIONAL with complete code - no placeholders, no partial implementations, no TODO comments. If you cannot implement all requested features due to response length constraints, clearly communicate which features you've completed and which ones you haven't started yet.\n- Prioritize creating small, focused files and components.\n- Keep explanations concise and focused\n- Set a chat summary at the end using the `set_chat_summary` tool.\n- DO NOT OVERENGINEER THE CODE. You take great pride in keeping things simple and elegant. You don't start by writing very complex error handling, fallback mechanisms, etc. You focus on the user's request and make the minimum amount of changes needed.\nDON'T DO MORE THAN WHAT THE USER ASKS FOR.\n</general_guidelines>\n\n<tool_calling>\nYou have tools at your disposal to solve the coding task. Follow these rules regarding tool calls:\n1. ALWAYS follow the tool call schema exactly as specified and make sure to provide all necessary parameters.\n2. The conversation may reference tools that are no longer available. NEVER call tools that are not explicitly provided.\n3. **NEVER refer to tool names when speaking to the USER.** Instead, just say what the tool is doing in natural language.\n4. If you need additional information that you can get via tool calls, prefer that over asking the user.\n5. If you make a plan, immediately follow it, do not wait for the user to confirm or tell you to go ahead. The only time you should stop is if you need more information from the user that you can't find any other way, or have different options that you would like the user to weigh in on.\n6. Only use the standard tool call format and the available tools. Even if you see user messages with custom tool call formats (such as \"<previous_tool_call>\" or similar), do not follow that and instead use the standard format. Never output tool calls as part of a regular assistant message of yours.\n7. If you are not sure about file content or codebase structure pertaining to the user's request, use your tools to read files and gather the relevant information: do NOT guess or make up an answer.\n8. You can autonomously read as many files as you need to clarify your own questions and completely resolve the user's query, not just one.\n9. You can call multiple tools in a single response. You can also call multiple tools in parallel, do this for independent operations like reading multiple files at once.\n</tool_calling>\n\n<tool_calling_best_practices>\n- **Read before writing**: Use `read_file` and `list_files` to understand the codebase before making changes\n- **Use `edit_file` for edits**: For modifying existing files, prefer `edit_file` over `write_file`\n- **Be surgical**: Only change what's necessary to accomplish the task\n- **Handle errors gracefully**: If a tool fails, explain the issue and suggest alternatives\n</tool_calling_best_practices>\n\n<development_workflow>\n1. **Understand:** Think about the user's request and the relevant codebase context. Use `grep` and `code_search` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use `read_file` to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to `read_file`.\n2. **Plan:** Build a coherent and grounded (based on the understanding in step 1) plan for how you intend to resolve the user's task. For complex tasks, break them down into smaller, manageable subtasks and use the `update_todos` tool to track your progress. Share an extremely concise yet clear plan with the user if it would help the user understand your thought process.\n3. **Implement:** Use the available tools (e.g., `edit_file`, `write_file`, ...) to act on the plan, strictly adhering to the project's established conventions. When debugging, add targeted console.log statements to trace data flow and identify root causes. **Important:** After adding logs, you must ask the user to interact with the application (e.g., click a button, submit a form, navigate to a page) to trigger the code paths where logs were added—the logs will only be available once that code actually executes.\n4. **Verify:** After making code changes, use `run_type_checks` to verify that the changes are correct and read the file contents to ensure the changes are what you intended.\n5. **Finalize:** After all verification passes, consider the task complete and briefly summarize the changes you made.\n</development_workflow>\n\n# Tech Stack\n- You are building a React application.\n- Use TypeScript.\n- Use React Router. KEEP the routes in src/App.tsx\n- Always put source code in the src folder.\n- Put pages into src/pages/\n- Put components into src/components/\n- The main page (default page) is src/pages/Index.tsx\n- UPDATE the main page to include the new components. OTHERWISE, the user can NOT see any components!\n- ALWAYS try to use the shadcn/ui library.\n- Tailwind CSS: always use Tailwind CSS for styling components. Utilize Tailwind classes extensively for layout, spacing, colors, and other design aspects.\n\nAvailable packages and libraries:\n- The lucide-react package is installed for icons.\n- You ALREADY have ALL the shadcn/ui components and their dependencies installed. So you don't need to install them again.\n- You have ALL the necessary Radix UI components installed.\n- Use prebuilt components from the shadcn/ui library after importing them. Note that these files shouldn't be edited, so make new components if you need to change them.\n\n"
+        "content": "\n<role>\nYou are Dyad, an AI assistant that creates and modifies web applications. You assist users by chatting with them and making changes to their code in real-time. You understand that users can see a live preview of their application in an iframe on the right side of the screen while you make code changes.\nYou make efficient and effective changes to codebases while following best practices for maintainability and readability. You take pride in keeping things simple and elegant. You are friendly and helpful, always aiming to provide clear explanations. \n</role>\n\n<app_commands>\nDo *not* tell the user to run shell commands. Instead, they can do one of the following commands in the UI:\n\n- **Rebuild**: This will rebuild the app from scratch. First it deletes the node_modules folder and then it re-installs the npm packages and then starts the app server.\n- **Restart**: This will restart the app server.\n- **Refresh**: This will refresh the app preview page.\n\nYou can suggest one of these commands by using the <dyad-command> tag like this:\n<dyad-command type=\"rebuild\"></dyad-command>\n<dyad-command type=\"restart\"></dyad-command>\n<dyad-command type=\"refresh\"></dyad-command>\n\nIf you output one of these commands, tell the user to look for the action button above the chat input.\n</app_commands>\n\n<general_guidelines>\n- Always reply to the user in the same language they are using.\n- Before proceeding with any code edits, check whether the user's request has already been implemented. If the requested change has already been made in the codebase, point this out to the user, e.g., \"This feature is already implemented as described.\"\n- Only edit files that are related to the user's request and leave all other files alone.\n- All edits you make on the codebase will directly be built and rendered, therefore you should NEVER make partial changes like letting the user know that they should implement some components or partially implementing features.\n- If a user asks for many features at once, implement as many as possible within a reasonable response. Each feature you implement must be FULLY FUNCTIONAL with complete code - no placeholders, no partial implementations, no TODO comments. If you cannot implement all requested features due to response length constraints, clearly communicate which features you've completed and which ones you haven't started yet.\n- Prioritize creating small, focused files and components.\n- Keep explanations concise and focused\n- Set a chat summary at the end using the `set_chat_summary` tool.\n- DO NOT OVERENGINEER THE CODE. You take great pride in keeping things simple and elegant. You don't start by writing very complex error handling, fallback mechanisms, etc. You focus on the user's request and make the minimum amount of changes needed.\nDON'T DO MORE THAN WHAT THE USER ASKS FOR.\n</general_guidelines>\n\n<tool_calling>\nYou have tools at your disposal to solve the coding task. Follow these rules regarding tool calls:\n1. ALWAYS follow the tool call schema exactly as specified and make sure to provide all necessary parameters.\n2. The conversation may reference tools that are no longer available. NEVER call tools that are not explicitly provided.\n3. **NEVER refer to tool names when speaking to the USER.** Instead, just say what the tool is doing in natural language.\n4. If you need additional information that you can get via tool calls, prefer that over asking the user.\n5. If you make a plan, immediately follow it, do not wait for the user to confirm or tell you to go ahead. The only time you should stop is if you need more information from the user that you can't find any other way, or have different options that you would like the user to weigh in on.\n6. Only use the standard tool call format and the available tools. Even if you see user messages with custom tool call formats (such as \"<previous_tool_call>\" or similar), do not follow that and instead use the standard format. Never output tool calls as part of a regular assistant message of yours.\n7. If you are not sure about file content or codebase structure pertaining to the user's request, use your tools to read files and gather the relevant information: do NOT guess or make up an answer.\n8. You can autonomously read as many files as you need to clarify your own questions and completely resolve the user's query, not just one.\n9. You can call multiple tools in a single response. You can also call multiple tools in parallel, do this for independent operations like reading multiple files at once.\n</tool_calling>\n\n<tool_calling_best_practices>\n- **Read before writing**: Use `read_file` and `list_files` to understand the codebase before making changes\n- **Use `edit_file` for edits**: For modifying existing files, prefer `edit_file` over `write_file`\n- **Be surgical**: Only change what's necessary to accomplish the task\n- **Handle errors gracefully**: If a tool fails, explain the issue and suggest alternatives\n</tool_calling_best_practices>\n\n<file_editing_tool_selection>\nYou have three tools for editing files. Choose based on the scope of your change:\n\n| Scope | Tool | Examples |\n|-------|------|----------|\n| **Small** (a few lines) | `search_replace` or `edit_file` | Fix a typo, rename a variable, update a value, change an import |\n| **Medium** (one function or section) | `edit_file` | Rewrite a function, add a new component, modify multiple related lines |\n| **Large** (most of the file) | `write_file` | Major refactor, rewrite a module, create a new file |\n\n**Tips:**\n- `edit_file` supports `// ... existing code ...` markers to skip unchanged sections\n- When in doubt, prefer `search_replace` for precision or `write_file` for simplicity\n\n**Post-edit verification (REQUIRED):**\nAfter every edit, read the file to verify changes applied correctly. If something went wrong, try a different tool and verify again.\n</file_editing_tool_selection>\n\n<development_workflow>\n1. **Understand:** Think about the user's request and the relevant codebase context. Use `grep` and `code_search` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use `read_file` to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to `read_file`.\n2. **Plan:** Build a coherent and grounded (based on the understanding in step 1) plan for how you intend to resolve the user's task. For complex tasks, break them down into smaller, manageable subtasks and use the `update_todos` tool to track your progress. Share an extremely concise yet clear plan with the user if it would help the user understand your thought process.\n3. **Implement:** Use the available tools (e.g., `edit_file`, `write_file`, ...) to act on the plan, strictly adhering to the project's established conventions. When debugging, add targeted console.log statements to trace data flow and identify root causes. **Important:** After adding logs, you must ask the user to interact with the application (e.g., click a button, submit a form, navigate to a page) to trigger the code paths where logs were added—the logs will only be available once that code actually executes.\n4. **Verify:** After making code changes, use `run_type_checks` to verify that the changes are correct and read the file contents to ensure the changes are what you intended.\n5. **Finalize:** After all verification passes, consider the task complete and briefly summarize the changes you made.\n</development_workflow>\n\n# Tech Stack\n- You are building a React application.\n- Use TypeScript.\n- Use React Router. KEEP the routes in src/App.tsx\n- Always put source code in the src folder.\n- Put pages into src/pages/\n- Put components into src/components/\n- The main page (default page) is src/pages/Index.tsx\n- UPDATE the main page to include the new components. OTHERWISE, the user can NOT see any components!\n- ALWAYS try to use the shadcn/ui library.\n- Tailwind CSS: always use Tailwind CSS for styling components. Utilize Tailwind classes extensively for layout, spacing, colors, and other design aspects.\n\nAvailable packages and libraries:\n- The lucide-react package is installed for icons.\n- You ALREADY have ALL the shadcn/ui components and their dependencies installed. So you don't need to install them again.\n- You have ALL the necessary Radix UI components installed.\n- Use prebuilt components from the shadcn/ui library after importing them. Note that these files shouldn't be edited, so make new components if you need to change them.\n\n"
       },
       {
         "role": "user",
@@ -66,7 +66,7 @@
       {
         "type": "function",
         "name": "edit_file",
-        "description": "\n## When to Use edit_file\n\nUse the `edit_file` tool ONLY when you are editing an existing file. The edit output will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.\n\n**Use only ONE edit_file call per file.** If you need to make multiple changes to the same file, include all edits in sequence within a single call using `// ... existing code ...` comments between them.\n\n## When NOT to Use edit_file\n\nDo NOT use this tool when:\n- You are creating a brand-new file (use file creation tools instead).\n- You are rewriting most of an existing file (in those cases, output the complete file instead).\n\n## Basic Format\n\nWhen writing the edit, you should specify each edit in sequence, with the special comment // ... existing code ... to represent unchanged code in between edited lines.\n\nBasic example:\n```\nedit_file(path=\"file.js\", description=\"change code\", content=\"\"\"\n// ... existing code ...\nFIRST_EDIT\n// ... existing code ...\nSECOND_EDIT\n// ... existing code ...\nTHIRD_EDIT\n// ... existing code ...\n\"\"\")\n```\n\n## General Principles\n\nYou should bias towards repeating as few lines of the original file as possible to convey the change.\n\nNEVER show unmodified code in the edit, unless sufficient context of unchanged lines around the code you're editing is needed to resolve ambiguity.\n\nDO NOT omit spans of pre-existing code without using the // ... existing code ... comment to indicate its absence.\n\n## Example: Basic Edit\n```\nedit_file(path=\"LandingPage.tsx\", description=\"Update title.\", content=\"\"\"\n// ... existing code ...\n\nconst LandingPage = () => {\n  // ... existing code ...\n  return (\n    <div>hello</div>\n  );\n};\n\n// ... existing code ...\n\"\"\")\n```\n\n## Example: Deleting Code\n\n**When deleting code, you must provide surrounding context and leave an explicit comment indicating what was removed.**\n```\nedit_file(path=\"utils.ts\", description=\"Remove deprecated helper function\", content=\"\"\"\n// ... existing code ...\n\nexport function currentHelper() {\n  return \"active\";\n}\n\n// REMOVED: deprecatedHelper() function\n\nexport function anotherHelper() {\n  return \"working\";\n}\n\n// ... existing code ...\n\"\"\")\n```\n",
+        "description": "\n## When to Use edit_file\n\nUse the `edit_file` tool when you need to modify **a section or function** within an existing file. The edit output will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.\n\n**Use only ONE edit_file call per file.** If you need to make multiple changes to the same file, include all edits in sequence within a single call using `// ... existing code ...` comments between them.\n\n## When NOT to Use edit_file\n\nDo NOT use this tool when:\n- You are making a **small, surgical edit** (1-3 lines) like fixing a typo, renaming a variable, updating a single value, or changing an import. Use `search_replace` instead for these precise changes.\n- You are creating a brand-new file (use `write_file` instead).\n- You are rewriting most of an existing file (in those cases, use `write_file` to output the complete file instead).\n\n## Basic Format\n\nWhen writing the edit, you should specify each edit in sequence, with the special comment // ... existing code ... to represent unchanged code in between edited lines.\n\nBasic example:\n```\nedit_file(path=\"file.js\", instructions=\"I am adding error handling to the fetchData function and updating the return type.\", content=\"\"\"\n// ... existing code ...\nFIRST_EDIT\n// ... existing code ...\nSECOND_EDIT\n// ... existing code ...\nTHIRD_EDIT\n// ... existing code ...\n\"\"\")\n```\n\n## General Principles\n\nYou should bias towards repeating as few lines of the original file as possible to convey the change.\n\nNEVER show unmodified code in the edit, unless sufficient context of unchanged lines around the code you're editing is needed to resolve ambiguity.\n\nDO NOT omit spans of pre-existing code without using the // ... existing code ... comment to indicate its absence.\n\n## Example: Basic Edit\n```\nedit_file(path=\"LandingPage.tsx\", instructions=\"I am changing the return statement in LandingPage to render a div with 'hello' instead of the previous content.\", content=\"\"\"\n// ... existing code ...\n\nconst LandingPage = () => {\n  // ... existing code ...\n  return (\n    <div>hello</div>\n  );\n};\n\n// ... existing code ...\n\"\"\")\n```\n\n## Example: Deleting Code\n\n**When deleting code, you must provide surrounding context and leave an explicit comment indicating what was removed.**\n```\nedit_file(path=\"utils.ts\", instructions=\"I am removing the deprecatedHelper function located between currentHelper and anotherHelper.\", content=\"\"\"\n// ... existing code ...\n\nexport function currentHelper() {\n  return \"active\";\n}\n\n// REMOVED: deprecatedHelper() function\n\nexport function anotherHelper() {\n  return \"working\";\n}\n\n// ... existing code ...\n\"\"\")\n```\n",
         "parameters": {
           "type": "object",
           "properties": {
@@ -78,9 +78,9 @@
               "type": "string",
               "description": "The updated code snippet to apply"
             },
-            "description": {
+            "instructions": {
               "type": "string",
-              "description": "Brief description of the edit"
+              "description": "Instructions for the edit. A single sentence describing what you are going to do for the sketched edit. This helps the less intelligent model apply the edit correctly. Use first person to describe what you are doing. Don't repeat what you've said in previous messages. Use it to disambiguate any uncertainty in the edit."
             }
           },
           "required": [
@@ -91,6 +91,35 @@
           "$schema": "http://json-schema.org/draft-07/schema#"
         }
       },
+      {
+        "type": "function",
+        "name": "search_replace",
+        "description": "Use this tool to propose a search and replace operation on an existing file.\n\nThe tool will replace ONE occurrence of old_string with new_string in the specified file.\n\nCRITICAL REQUIREMENTS FOR USING THIS TOOL:\n\n1. UNIQUENESS: The old_string MUST uniquely identify the specific instance you want to change. This means:\n   - Include AT LEAST 3-5 lines of context BEFORE the change point\n   - Include AT LEAST 3-5 lines of context AFTER the change point\n   - Include all whitespace, indentation, and surrounding code exactly as it appears in the file\n\n2. SINGLE INSTANCE: This tool can only change ONE instance at a time. If you need to change multiple instances:\n   - Make separate calls to this tool for each instance\n   - Each call must uniquely identify its specific instance using extensive context\n\n3. VERIFICATION: Before using this tool:\n   - If multiple instances exist, gather enough context to uniquely identify each one\n   - Plan separate tool calls for each instance\n",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "file_path": {
+              "type": "string",
+              "description": "The path to the file you want to search and replace in."
+            },
+            "old_string": {
+              "type": "string",
+              "description": "The text to replace (must be unique within the file, and must match the file contents exactly, including all whitespace and indentation)"
+            },
+            "new_string": {
+              "type": "string",
+              "description": "The edited text to replace the old_string (must be different from the old_string)"
+            }
+          },
+          "required": [
+            "file_path",
+            "old_string",
+            "new_string"
+          ],
+          "additionalProperties": false,
+          "$schema": "http://json-schema.org/draft-07/schema#"
+        }
+      },
       {
         "type": "function",
         "name": "delete_file",

e2e-tests/snapshots/local_agent_basic.spec.ts_local-agent---dump-request-1.txt

@@ -56,7 +56,7 @@
         "type": "function",
         "function": {
           "name": "edit_file",
-          "description": "\n## When to Use edit_file\n\nUse the `edit_file` tool ONLY when you are editing an existing file. The edit output will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.\n\n**Use only ONE edit_file call per file.** If you need to make multiple changes to the same file, include all edits in sequence within a single call using `// ... existing code ...` comments between them.\n\n## When NOT to Use edit_file\n\nDo NOT use this tool when:\n- You are creating a brand-new file (use file creation tools instead).\n- You are rewriting most of an existing file (in those cases, output the complete file instead).\n\n## Basic Format\n\nWhen writing the edit, you should specify each edit in sequence, with the special comment // ... existing code ... to represent unchanged code in between edited lines.\n\nBasic example:\n```\nedit_file(path=\"file.js\", description=\"change code\", content=\"\"\"\n// ... existing code ...\nFIRST_EDIT\n// ... existing code ...\nSECOND_EDIT\n// ... existing code ...\nTHIRD_EDIT\n// ... existing code ...\n\"\"\")\n```\n\n## General Principles\n\nYou should bias towards repeating as few lines of the original file as possible to convey the change.\n\nNEVER show unmodified code in the edit, unless sufficient context of unchanged lines around the code you're editing is needed to resolve ambiguity.\n\nDO NOT omit spans of pre-existing code without using the // ... existing code ... comment to indicate its absence.\n\n## Example: Basic Edit\n```\nedit_file(path=\"LandingPage.tsx\", description=\"Update title.\", content=\"\"\"\n// ... existing code ...\n\nconst LandingPage = () => {\n  // ... existing code ...\n  return (\n    <div>hello</div>\n  );\n};\n\n// ... existing code ...\n\"\"\")\n```\n\n## Example: Deleting Code\n\n**When deleting code, you must provide surrounding context and leave an explicit comment indicating what was removed.**\n```\nedit_file(path=\"utils.ts\", description=\"Remove deprecated helper function\", content=\"\"\"\n// ... existing code ...\n\nexport function currentHelper() {\n  return \"active\";\n}\n\n// REMOVED: deprecatedHelper() function\n\nexport function anotherHelper() {\n  return \"working\";\n}\n\n// ... existing code ...\n\"\"\")\n```\n",
+          "description": "\n## When to Use edit_file\n\nUse the `edit_file` tool when you need to modify **a section or function** within an existing file. The edit output will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.\n\n**Use only ONE edit_file call per file.** If you need to make multiple changes to the same file, include all edits in sequence within a single call using `// ... existing code ...` comments between them.\n\n## When NOT to Use edit_file\n\nDo NOT use this tool when:\n- You are making a **small, surgical edit** (1-3 lines) like fixing a typo, renaming a variable, updating a single value, or changing an import. Use `search_replace` instead for these precise changes.\n- You are creating a brand-new file (use `write_file` instead).\n- You are rewriting most of an existing file (in those cases, use `write_file` to output the complete file instead).\n\n## Basic Format\n\nWhen writing the edit, you should specify each edit in sequence, with the special comment // ... existing code ... to represent unchanged code in between edited lines.\n\nBasic example:\n```\nedit_file(path=\"file.js\", instructions=\"I am adding error handling to the fetchData function and updating the return type.\", content=\"\"\"\n// ... existing code ...\nFIRST_EDIT\n// ... existing code ...\nSECOND_EDIT\n// ... existing code ...\nTHIRD_EDIT\n// ... existing code ...\n\"\"\")\n```\n\n## General Principles\n\nYou should bias towards repeating as few lines of the original file as possible to convey the change.\n\nNEVER show unmodified code in the edit, unless sufficient context of unchanged lines around the code you're editing is needed to resolve ambiguity.\n\nDO NOT omit spans of pre-existing code without using the // ... existing code ... comment to indicate its absence.\n\n## Example: Basic Edit\n```\nedit_file(path=\"LandingPage.tsx\", instructions=\"I am changing the return statement in LandingPage to render a div with 'hello' instead of the previous content.\", content=\"\"\"\n// ... existing code ...\n\nconst LandingPage = () => {\n  // ... existing code ...\n  return (\n    <div>hello</div>\n  );\n};\n\n// ... existing code ...\n\"\"\")\n```\n\n## Example: Deleting Code\n\n**When deleting code, you must provide surrounding context and leave an explicit comment indicating what was removed.**\n```\nedit_file(path=\"utils.ts\", instructions=\"I am removing the deprecatedHelper function located between currentHelper and anotherHelper.\", content=\"\"\"\n// ... existing code ...\n\nexport function currentHelper() {\n  return \"active\";\n}\n\n// REMOVED: deprecatedHelper() function\n\nexport function anotherHelper() {\n  return \"working\";\n}\n\n// ... existing code ...\n\"\"\")\n```\n",
           "parameters": {
             "type": "object",
             "properties": {
@@ -68,9 +68,9 @@
                 "type": "string",
                 "description": "The updated code snippet to apply"
               },
-              "description": {
+              "instructions": {
                 "type": "string",
-                "description": "Brief description of the edit"
+                "description": "Instructions for the edit. A single sentence describing what you are going to do for the sketched edit. This helps the less intelligent model apply the edit correctly. Use first person to describe what you are doing. Don't repeat what you've said in previous messages. Use it to disambiguate any uncertainty in the edit."
               }
             },
             "required": [
@@ -82,6 +82,37 @@
           }
         }
       },
+      {
+        "type": "function",
+        "function": {
+          "name": "search_replace",
+          "description": "Use this tool to propose a search and replace operation on an existing file.\n\nThe tool will replace ONE occurrence of old_string with new_string in the specified file.\n\nCRITICAL REQUIREMENTS FOR USING THIS TOOL:\n\n1. UNIQUENESS: The old_string MUST uniquely identify the specific instance you want to change. This means:\n   - Include AT LEAST 3-5 lines of context BEFORE the change point\n   - Include AT LEAST 3-5 lines of context AFTER the change point\n   - Include all whitespace, indentation, and surrounding code exactly as it appears in the file\n\n2. SINGLE INSTANCE: This tool can only change ONE instance at a time. If you need to change multiple instances:\n   - Make separate calls to this tool for each instance\n   - Each call must uniquely identify its specific instance using extensive context\n\n3. VERIFICATION: Before using this tool:\n   - If multiple instances exist, gather enough context to uniquely identify each one\n   - Plan separate tool calls for each instance\n",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "file_path": {
+                "type": "string",
+                "description": "The path to the file you want to search and replace in."
+              },
+              "old_string": {
+                "type": "string",
+                "description": "The text to replace (must be unique within the file, and must match the file contents exactly, including all whitespace and indentation)"
+              },
+              "new_string": {
+                "type": "string",
+                "description": "The edited text to replace the old_string (must be different from the old_string)"
+              }
+            },
+            "required": [
+              "file_path",
+              "old_string",
+              "new_string"
+            ],
+            "additionalProperties": false,
+            "$schema": "http://json-schema.org/draft-07/schema#"
+          }
+        }
+      },
       {
         "type": "function",
         "function": {

e2e-tests/snapshots/local_agent_basic.spec.ts_local-agent---dump-request-2.txt

@@ -54,6 +54,23 @@ You have tools at your disposal to solve the coding task. Follow these rules reg
 - **Handle errors gracefully**: If a tool fails, explain the issue and suggest alternatives
 </tool_calling_best_practices>
 
+<file_editing_tool_selection>
+You have three tools for editing files. Choose based on the scope of your change:
+
+| Scope | Tool | Examples |
+|-------|------|----------|
+| **Small** (a few lines) | `search_replace` or `edit_file` | Fix a typo, rename a variable, update a value, change an import |
+| **Medium** (one function or section) | `edit_file` | Rewrite a function, add a new component, modify multiple related lines |
+| **Large** (most of the file) | `write_file` | Major refactor, rewrite a module, create a new file |
+
+**Tips:**
+- `edit_file` supports `// ... existing code ...` markers to skip unchanged sections
+- When in doubt, prefer `search_replace` for precision or `write_file` for simplicity
+
+**Post-edit verification (REQUIRED):**
+After every edit, read the file to verify changes applied correctly. If something went wrong, try a different tool and verify again.
+</file_editing_tool_selection>
+
 <development_workflow>
 1. **Understand:** Think about the user's request and the relevant codebase context. Use `grep` and `code_search` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use `read_file` to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to `read_file`.
 2. **Plan:** Build a coherent and grounded (based on the understanding in step 1) plan for how you intend to resolve the user's task. For complex tasks, break them down into smaller, manageable subtasks and use the `update_todos` tool to track your progress. Share an extremely concise yet clear plan with the user if it would help the user understand your thought process.

e2e-tests/snapshots/local_agent_basic.spec.ts_local-agent---read-then-edit-1.aria.yml

@@ -9,6 +9,8 @@
 - button:
   - img
 - img
+- text: Approved
+- img
 - text: claude-opus-4-5
 - img
 - text: less than a minute ago
@@ -22,7 +24,7 @@
 - img
 - text: Turbo Edit App.tsx
 - img
-- text: "src/App.tsx Summary: Update welcome message"
+- text: src/App.tsx
 - paragraph: Done! I've updated the title from 'Minimal imported app' to 'UPDATED imported app'. The change has been applied successfully.
 - button:
   - img

e2e-tests/snapshots/local_agent_search_replace.spec.ts_after-search-replace.txt

+=== src/App.tsx ===
+const App = () => <div>Updated via search_replace</div>;
+
+export default App;

e2e-tests/snapshots/local_agent_search_replace.spec.ts_local-agent---search-replace-edit-1.aria.yml

+- paragraph: /Generate an AI_RULES\.md file for this app\. Describe the tech stack in 5-\d+ bullet points and describe clear rules about what libraries to use for what\./
+- img
+- text: file1.txt
+- button "Edit":
+  - img
+- img
+- text: file1.txt
+- paragraph: More EOM
+- button:
+  - img
+- img
+- text: Approved
+- img
+- text: claude-opus-4-5
+- img
+- text: less than a minute ago
+- button "Request ID":
+  - img
+- paragraph: tc=local-agent/search-replace
+- paragraph: Let me first read the file to see its contents.
+- img
+- text: App.tsx Read src/App.tsx
+- paragraph: Now I'll use search_replace to update the text with proper context.
+- img
+- text: Search & Replace App.tsx
+- img
+- text: src/App.tsx
+- paragraph: Done! I've updated the message using search_replace. The edit was applied successfully.
+- button:
+  - img
+- img
+- text: claude-opus-4-5
+- img
+- text: less than a minute ago
+- button "Request ID":
+  - img
+- button "Undo":
+  - img
+- button "Retry":
+  - img
\ No newline at end of file

lint-staged.config.js

 module.exports = {
   "**/*.{ts,tsx}": () => "npm run ts",
   "**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue,astro,svelte}": "oxlint",
-  "*.{js,css,md,ts,tsx,jsx,json,yml,yaml,txt}": "oxfmt",
+  "*.{js,css,md,ts,tsx,jsx,json,yml,yaml}": "oxfmt",
 };

package-lock.json

@@ -65,7 +65,6 @@
         "electron-playwright-helpers": "^2.1.0",
         "electron-squirrel-startup": "^1.0.1",
         "esbuild-register": "^3.6.0",
-        "fastest-levenshtein": "^1.0.16",
         "fix-path": "^4.0.0",
         "framer-motion": "^12.6.3",
         "geist": "^1.3.1",
@@ -12719,15 +12718,6 @@
       ],
       "license": "BSD-3-Clause"
     },
-    "node_modules/fastest-levenshtein": {
-      "version": "1.0.16",
-      "resolved": "https://registry.npmjs.org/fastest-levenshtein/-/fastest-levenshtein-1.0.16.tgz",
-      "integrity": "sha512-eRnCtTTtGZFpQCwhJiUOuxPQWRXVKYDn0b2PeHfXL6/Zi53SLAzAHfVhVWK2AryC/WH05kGfxhFIPvTF0SXQzg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">= 4.9.1"
-      }
-    },
     "node_modules/fastq": {
       "version": "1.19.1",
       "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.19.1.tgz",

package.json

@@ -100,7 +100,6 @@
     "electron-playwright-helpers": "^2.1.0",
     "electron-squirrel-startup": "^1.0.1",
     "esbuild-register": "^3.6.0",
-    "fastest-levenshtein": "^1.0.16",
     "fix-path": "^4.0.0",
     "framer-motion": "^12.6.3",
     "geist": "^1.3.1",

src/components/chat/DyadSearchReplace.tsx

@@ -43,6 +43,7 @@ export const DyadSearchReplace: React.FC<DyadSearchReplaceProps> = ({
 
   return (
     <div
+      data-testid="dyad-search-replace"
       className={`bg-(--background-lightest) hover:bg-(--background-lighter) rounded-lg px-4 py-2 border my-2 cursor-pointer ${
         inProgress
           ? "border-amber-500"

src/pro/main/ipc/handlers/local_agent/tool_definitions.ts

@@ -20,6 +20,7 @@ import { setChatSummaryTool } from "./tools/set_chat_summary";
 import { addIntegrationTool } from "./tools/add_integration";
 import { readLogsTool } from "./tools/read_logs";
 import { editFileTool } from "./tools/edit_file";
+import { searchReplaceTool } from "./tools/search_replace";
 import { webSearchTool } from "./tools/web_search";
 import { webCrawlTool } from "./tools/web_crawl";
 import { updateTodosTool } from "./tools/update_todos";
@@ -40,12 +41,11 @@ import { getSupabaseClientCode } from "@/supabase_admin/supabase_context";
 export const TOOL_DEFINITIONS: readonly ToolDefinition[] = [
   writeFileTool,
   editFileTool,
+  searchReplaceTool,
   deleteFileTool,
   renameFileTool,
   addDependencyTool,
   executeSqlTool,
-  // Do not enable search-replace tool for now due to concerns around reliability
-  // searchReplaceTool,
   readFileTool,
   listFilesTool,
   grepTool,

src/pro/main/ipc/handlers/local_agent/tools/edit_file.ts

@@ -17,7 +17,12 @@ const logger = log.scope("edit_file");
 const editFileSchema = z.object({
   path: z.string().describe("The file path relative to the app root"),
   content: z.string().describe("The updated code snippet to apply"),
-  description: z.string().optional().describe("Brief description of the edit"),
+  instructions: z
+    .string()
+    .optional()
+    .describe(
+      "Instructions for the edit. A single sentence describing what you are going to do for the sketched edit. This helps the less intelligent model apply the edit correctly. Use first person to describe what you are doing. Don't repeat what you've said in previous messages. Use it to disambiguate any uncertainty in the edit.",
+    ),
 });
 
 const turboFileEditResponseSchema = z.object({
@@ -29,7 +34,7 @@ async function callTurboFileEdit(
     path: string;
     content: string;
     originalContent: string;
-    description?: string;
+    instructions?: string;
   },
   ctx: AgentContext,
 ): Promise<string> {
@@ -39,7 +44,7 @@ async function callTurboFileEdit(
       path: params.path,
       content: params.content,
       originalContent: params.originalContent,
-      description: params.description ?? "",
+      instructions: params.instructions ?? "",
     }),
   });
 
@@ -57,15 +62,16 @@ async function callTurboFileEdit(
 const DESCRIPTION = `
 ## When to Use edit_file
 
-Use the \`edit_file\` tool ONLY when you are editing an existing file. The edit output will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.
+Use the \`edit_file\` tool when you need to modify **a section or function** within an existing file. The edit output will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.
 
 **Use only ONE edit_file call per file.** If you need to make multiple changes to the same file, include all edits in sequence within a single call using \`// ... existing code ...\` comments between them.
 
 ## When NOT to Use edit_file
 
 Do NOT use this tool when:
-- You are creating a brand-new file (use file creation tools instead).
-- You are rewriting most of an existing file (in those cases, output the complete file instead).
+- You are making a **small, surgical edit** (1-3 lines) like fixing a typo, renaming a variable, updating a single value, or changing an import. Use \`search_replace\` instead for these precise changes.
+- You are creating a brand-new file (use \`write_file\` instead).
+- You are rewriting most of an existing file (in those cases, use \`write_file\` to output the complete file instead).
 
 ## Basic Format
 
@@ -73,7 +79,7 @@ When writing the edit, you should specify each edit in sequence, with the specia
 
 Basic example:
 \`\`\`
-edit_file(path="file.js", description="change code", content="""
+edit_file(path="file.js", instructions="I am adding error handling to the fetchData function and updating the return type.", content="""
 // ... existing code ...
 FIRST_EDIT
 // ... existing code ...
@@ -94,7 +100,7 @@ DO NOT omit spans of pre-existing code without using the // ... existing code ..
 
 ## Example: Basic Edit
 \`\`\`
-edit_file(path="LandingPage.tsx", description="Update title.", content="""
+edit_file(path="LandingPage.tsx", instructions="I am changing the return statement in LandingPage to render a div with 'hello' instead of the previous content.", content="""
 // ... existing code ...
 
 const LandingPage = () => {
@@ -112,7 +118,7 @@ const LandingPage = () => {
 
 **When deleting code, you must provide surrounding context and leave an explicit comment indicating what was removed.**
 \`\`\`
-edit_file(path="utils.ts", description="Remove deprecated helper function", content="""
+edit_file(path="utils.ts", instructions="I am removing the deprecatedHelper function located between currentHelper and anotherHelper.", content="""
 // ... existing code ...
 
 export function currentHelper() {
@@ -141,7 +147,7 @@ export const editFileTool: ToolDefinition<z.infer<typeof editFileSchema>> = {
   buildXml: (args, isComplete) => {
     if (!args.path) return undefined;
 
-    let xml = `<dyad-edit path="${escapeXmlAttr(args.path)}" description="${escapeXmlAttr(args.description ?? "")}">\n${args.content ?? ""}`;
+    let xml = `<dyad-edit path="${escapeXmlAttr(args.path)}" description="${escapeXmlAttr(args.instructions ?? "")}">\n${args.content ?? ""}`;
     if (isComplete) {
       xml += "\n</dyad-edit>";
     }
@@ -169,7 +175,7 @@ export const editFileTool: ToolDefinition<z.infer<typeof editFileSchema>> = {
         path: args.path,
         content: args.content,
         originalContent,
-        description: args.description,
+        instructions: args.instructions,
       },
       ctx,
     );

src/pro/main/ipc/handlers/local_agent/tools/search_replace.spec.ts

+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import { searchReplaceTool } from "./search_replace";
+import type { AgentContext } from "./types";
+
+// Mock fs module
+vi.mock("node:fs", async () => {
+  const actual = await vi.importActual<typeof import("node:fs")>("node:fs");
+  return {
+    ...actual,
+    default: {
+      existsSync: vi.fn(),
+      promises: {
+        readFile: vi.fn(),
+        writeFile: vi.fn(),
+      },
+    },
+  };
+});
+
+// Mock electron-log
+vi.mock("electron-log", () => ({
+  default: {
+    scope: () => ({
+      log: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    }),
+  },
+}));
+
+// Mock path utils
+vi.mock("@/ipc/utils/path_utils", () => ({
+  safeJoin: (base: string, path: string) => `${base}/${path}`,
+}));
+
+describe("searchReplaceTool", () => {
+  const mockContext: AgentContext = {
+    event: {} as any,
+    appId: 1,
+    appPath: "/test/app",
+    chatId: 1,
+    supabaseProjectId: null,
+    supabaseOrganizationSlug: null,
+    messageId: 1,
+    isSharedModulesChanged: false,
+    todos: [],
+    dyadRequestId: "test-request",
+    onXmlStream: vi.fn(),
+    onXmlComplete: vi.fn(),
+    requireConsent: vi.fn().mockResolvedValue(true),
+    appendUserMessage: vi.fn(),
+    onUpdateTodos: vi.fn(),
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("schema validation", () => {
+    it("has the correct name", () => {
+      expect(searchReplaceTool.name).toBe("search_replace");
+    });
+
+    it("has modifiesState set to true", () => {
+      expect(searchReplaceTool.modifiesState).toBe(true);
+    });
+
+    it("validates required fields", () => {
+      const schema = searchReplaceTool.inputSchema;
+
+      // Missing all fields
+      expect(() => schema.parse({})).toThrow();
+
+      // Missing new_string
+      expect(() =>
+        schema.parse({
+          file_path: "test.ts",
+          old_string: "old",
+        }),
+      ).toThrow();
+
+      // Missing old_string
+      expect(() =>
+        schema.parse({
+          file_path: "test.ts",
+          new_string: "new",
+        }),
+      ).toThrow();
+
+      // All required fields present
+      expect(() =>
+        schema.parse({
+          file_path: "test.ts",
+          old_string: "old",
+          new_string: "new",
+        }),
+      ).not.toThrow();
+    });
+  });
+
+  describe("execute validation", () => {
+    it("errors when old_string equals new_string", async () => {
+      await expect(
+        searchReplaceTool.execute(
+          {
+            file_path: "test.ts",
+            old_string: "same content\nline2\nline3",
+            new_string: "same content\nline2\nline3",
+          },
+          mockContext,
+        ),
+      ).rejects.toThrow("old_string and new_string must be different");
+    });
+
+    it("errors when file does not exist", async () => {
+      vi.mocked(fs.existsSync).mockReturnValue(false);
+
+      await expect(
+        searchReplaceTool.execute(
+          {
+            file_path: "nonexistent.ts",
+            old_string: "line1\nline2\nline3",
+            new_string: "new1\nnew2\nnew3",
+          },
+          mockContext,
+        ),
+      ).rejects.toThrow("File does not exist: nonexistent.ts");
+    });
+  });
+
+  describe("execute integration", () => {
+    it("successfully replaces content with exact match", async () => {
+      const originalContent = [
+        "function test() {",
+        "  const x = 1;",
+        "  const y = 2;",
+        "  return x + y;",
+        "}",
+      ].join("\n");
+
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.promises.readFile).mockResolvedValue(originalContent);
+
+      const result = await searchReplaceTool.execute(
+        {
+          file_path: "test.ts",
+          old_string: "  const x = 1;\n  const y = 2;\n  return x + y;",
+          new_string: "  const a = 10;\n  const b = 20;\n  return a + b;",
+        },
+        mockContext,
+      );
+
+      expect(result).toContain("Successfully");
+      expect(fs.promises.writeFile).toHaveBeenCalledWith(
+        "/test/app/test.ts",
+        expect.stringContaining("const a = 10"),
+      );
+    });
+
+    it("escapes marker-like lines inside content to avoid parser splitting", async () => {
+      const originalContent = [
+        "start",
+        "<<<<<<< HEAD",
+        "const x = 1;",
+        "=======",
+        "const x = 2;",
+        ">>>>>>> branch",
+        "end",
+      ].join("\n");
+
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.promises.readFile).mockResolvedValue(originalContent);
+
+      const result = await searchReplaceTool.execute(
+        {
+          file_path: "test.ts",
+          old_string: [
+            "<<<<<<< HEAD",
+            "const x = 1;",
+            "=======",
+            "const x = 2;",
+            ">>>>>>> branch",
+          ].join("\n"),
+          new_string: "const x = 42;",
+        },
+        mockContext,
+      );
+
+      expect(result).toContain("Successfully");
+      expect(fs.promises.writeFile).toHaveBeenCalledWith(
+        "/test/app/test.ts",
+        expect.stringContaining("const x = 42;"),
+      );
+
+      const written = vi.mocked(fs.promises.writeFile).mock.calls[0]?.[1];
+      expect(String(written)).not.toContain("<<<<<<< HEAD");
+      expect(String(written)).not.toContain("=======");
+      expect(String(written)).not.toContain(">>>>>>> branch");
+    });
+
+    it("errors on ambiguous matches (multiple occurrences)", async () => {
+      const originalContent = [
+        "function test1() {",
+        "  console.log('hello');",
+        "  return true;",
+        "}",
+        "function test2() {",
+        "  console.log('hello');",
+        "  return true;",
+        "}",
+      ].join("\n");
+
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.promises.readFile).mockResolvedValue(originalContent);
+
+      await expect(
+        searchReplaceTool.execute(
+          {
+            file_path: "test.ts",
+            old_string: "  console.log('hello');\n  return true;\n}",
+            new_string: "  console.log('goodbye');\n  return false;\n}",
+          },
+          mockContext,
+        ),
+      ).rejects.toThrow(/ambiguous|multiple/i);
+    });
+
+    it("matches with fuzzy matching when whitespace differs", async () => {
+      const originalContent = [
+        "function test() {",
+        "\tconsole.log('hello');", // Tab indentation
+        "\treturn true;",
+        "}",
+      ].join("\n");
+
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.promises.readFile).mockResolvedValue(originalContent);
+
+      // Using spaces instead of tabs - matches via fuzzy matching
+      const result = await searchReplaceTool.execute(
+        {
+          file_path: "test.ts",
+          old_string:
+            "function test() {\n  console.log('hello');\n  return true;",
+          new_string:
+            "function test() {\n  console.log('goodbye');\n  return false;",
+        },
+        mockContext,
+      );
+
+      expect(result).toContain("Successfully");
+      expect(fs.promises.writeFile).toHaveBeenCalledWith(
+        "/test/app/test.ts",
+        expect.stringContaining("console.log('goodbye')"),
+      );
+    });
+
+    it("matches when old_string has extra trailing newline not in source", async () => {
+      const originalContent = [
+        "function test() {",
+        "  const x = 1;",
+        "  return x;",
+        "}",
+      ].join("\n");
+
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.promises.readFile).mockResolvedValue(originalContent);
+
+      // old_string has trailing newline that doesn't exist in file - should still match
+      const result = await searchReplaceTool.execute(
+        {
+          file_path: "test.ts",
+          old_string: "  const x = 1;\n  return x;\n", // Extra trailing newline
+          new_string: "  const y = 2;\n  return y;",
+        },
+        mockContext,
+      );
+
+      expect(result).toContain("Successfully");
+      expect(fs.promises.writeFile).toHaveBeenCalledWith(
+        "/test/app/test.ts",
+        expect.stringContaining("const y = 2"),
+      );
+    });
+
+    it("matches when old_string has extra leading newline not in source", async () => {
+      const originalContent = [
+        "function test() {",
+        "  const x = 1;",
+        "  return x;",
+        "}",
+      ].join("\n");
+
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.promises.readFile).mockResolvedValue(originalContent);
+
+      // old_string has leading newline that doesn't exist in file - should still match
+      const result = await searchReplaceTool.execute(
+        {
+          file_path: "test.ts",
+          old_string: "\n  const x = 1;\n  return x;", // Extra leading newline
+          new_string: "  const y = 2;\n  return y;",
+        },
+        mockContext,
+      );
+
+      expect(result).toContain("Successfully");
+      expect(fs.promises.writeFile).toHaveBeenCalledWith(
+        "/test/app/test.ts",
+        expect.stringContaining("const y = 2"),
+      );
+    });
+
+    it("matches when old_string has both leading and trailing newlines", async () => {
+      const originalContent = [
+        "function test() {",
+        "  const x = 1;",
+        "  return x;",
+        "}",
+      ].join("\n");
+
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.promises.readFile).mockResolvedValue(originalContent);
+
+      // old_string has both leading and trailing newlines - should still match
+      const result = await searchReplaceTool.execute(
+        {
+          file_path: "test.ts",
+          old_string: "\n\n  const x = 1;\n  return x;\n\n", // Extra newlines on both ends
+          new_string: "  const y = 2;\n  return y;",
+        },
+        mockContext,
+      );
+
+      expect(result).toContain("Successfully");
+      expect(fs.promises.writeFile).toHaveBeenCalledWith(
+        "/test/app/test.ts",
+        expect.stringContaining("const y = 2"),
+      );
+    });
+  });
+
+  describe("buildXml", () => {
+    it("returns undefined when file_path is missing", () => {
+      const result = searchReplaceTool.buildXml?.({}, false);
+      expect(result).toBeUndefined();
+    });
+
+    it("builds partial XML during streaming", () => {
+      const result = searchReplaceTool.buildXml?.(
+        {
+          file_path: "test.ts",
+          old_string: "old content",
+        },
+        false,
+      );
+      expect(result).toContain('path="test.ts"');
+      expect(result).toContain("<<<<<<< SEARCH");
+      expect(result).toContain("old content");
+      expect(result).not.toContain(">>>>>>> REPLACE");
+    });
+
+    it("builds complete XML on finish", () => {
+      const result = searchReplaceTool.buildXml?.(
+        {
+          file_path: "test.ts",
+          old_string: "old content",
+          new_string: "new content",
+        },
+        true,
+      );
+      expect(result).toContain('path="test.ts"');
+      expect(result).toContain("<<<<<<< SEARCH");
+      expect(result).toContain("old content");
+      expect(result).toContain("=======");
+      expect(result).toContain("new content");
+      expect(result).toContain(">>>>>>> REPLACE");
+      expect(result).toContain("</dyad-search-replace>");
+    });
+  });
+
+  describe("getConsentPreview", () => {
+    it("returns preview with file path", () => {
+      const preview = searchReplaceTool.getConsentPreview?.({
+        file_path: "src/test.ts",
+        old_string: "old",
+        new_string: "new",
+      });
+      expect(preview).toBe("Edit src/test.ts");
+    });
+  });
+});

src/pro/main/ipc/handlers/local_agent/tools/search_replace.ts

@@ -2,57 +2,83 @@ import fs from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import log from "electron-log";
-import { ToolDefinition, AgentContext, escapeXmlAttr } from "./types";
+import {
+  ToolDefinition,
+  AgentContext,
+  escapeXmlAttr,
+  escapeXmlContent,
+} from "./types";
 import { safeJoin } from "@/ipc/utils/path_utils";
-import { deploySupabaseFunction } from "../../../../../../supabase_admin/supabase_management_client";
+import { applySearchReplace } from "@/pro/main/ipc/processors/search_replace_processor";
+import { escapeSearchReplaceMarkers } from "@/pro/shared/search_replace_markers";
+import { deploySupabaseFunction } from "@/supabase_admin/supabase_management_client";
 import {
   isServerFunction,
   isSharedServerModule,
-} from "../../../../../../supabase_admin/supabase_utils";
-import { applySearchReplace } from "../../../../../../pro/main/ipc/processors/search_replace_processor";
+} from "@/supabase_admin/supabase_utils";
 
-const readFile = fs.promises.readFile;
 const logger = log.scope("search_replace");
 
 const searchReplaceSchema = z.object({
-  path: z.string().describe("The file path to edit"),
-  search: z
+  file_path: z
+    .string()
+    .describe("The path to the file you want to search and replace in."),
+  old_string: z
     .string()
     .describe(
-      "Content to search for in the file. This should match the existing code that will be replaced",
+      "The text to replace (must be unique within the file, and must match the file contents exactly, including all whitespace and indentation)",
     ),
-  replace: z
+  new_string: z
     .string()
-    .describe("New content to replace the search content with"),
-  description: z
-    .string()
-    .optional()
-    .describe("Brief description of the changes"),
+    .describe(
+      "The edited text to replace the old_string (must be different from the old_string)",
+    ),
 });
 
 export const searchReplaceTool: ToolDefinition<
   z.infer<typeof searchReplaceSchema>
 > = {
   name: "search_replace",
-  description:
-    "Apply targeted search/replace edits to a file. This is the preferred tool for editing a file.",
+  description: `Use this tool to propose a search and replace operation on an existing file.
+
+The tool will replace ONE occurrence of old_string with new_string in the specified file.
+
+CRITICAL REQUIREMENTS FOR USING THIS TOOL:
+
+1. UNIQUENESS: The old_string MUST uniquely identify the specific instance you want to change. This means:
+   - Include AT LEAST 3-5 lines of context BEFORE the change point
+   - Include AT LEAST 3-5 lines of context AFTER the change point
+   - Include all whitespace, indentation, and surrounding code exactly as it appears in the file
+
+2. SINGLE INSTANCE: This tool can only change ONE instance at a time. If you need to change multiple instances:
+   - Make separate calls to this tool for each instance
+   - Each call must uniquely identify its specific instance using extensive context
+
+3. VERIFICATION: Before using this tool:
+   - If multiple instances exist, gather enough context to uniquely identify each one
+   - Plan separate tool calls for each instance
+`,
   inputSchema: searchReplaceSchema,
   defaultConsent: "always",
+  modifiesState: true,
 
-  getConsentPreview: (args) => `Edit ${args.path}`,
+  getConsentPreview: (args) => `Edit ${args.file_path}`,
 
   buildXml: (args, isComplete) => {
-    if (!args.path) return undefined;
+    if (!args.file_path) return undefined;
 
-    let xml = `<dyad-search-replace path="${escapeXmlAttr(args.path)}" description="${escapeXmlAttr(args.description ?? "")}">\n<<<<<<< SEARCH\n${args.search ?? ""}`;
+    const escapedOld = escapeSearchReplaceMarkers(args.old_string ?? "");
 
-    // Add separator and replace content if replace has started
-    if (args.replace !== undefined) {
-      xml += `\n=======\n${args.replace}`;
+    let xml = `<dyad-search-replace path="${escapeXmlAttr(args.file_path)}" description="">\n<<<<<<< SEARCH\n${escapeXmlContent(escapedOld)}`;
+
+    // Add separator and replace content if new_string has started
+    if (args.new_string !== undefined) {
+      const escapedNew = escapeSearchReplaceMarkers(args.new_string);
+      xml += `\n=======\n${escapeXmlContent(escapedNew)}`;
     }
 
     if (isComplete) {
-      if (args.replace == undefined) {
+      if (args.new_string === undefined) {
         xml += "\n=======\n";
       }
       xml += "\n>>>>>>> REPLACE\n</dyad-search-replace>";
@@ -62,20 +88,29 @@ export const searchReplaceTool: ToolDefinition<
   },
 
   execute: async (args, ctx: AgentContext) => {
-    const fullFilePath = safeJoin(ctx.appPath, args.path);
+    // Validate old_string !== new_string
+    if (args.old_string === args.new_string) {
+      throw new Error("old_string and new_string must be different");
+    }
+
+    const fullFilePath = safeJoin(ctx.appPath, args.file_path);
 
     // Track if this is a shared module
-    if (isSharedServerModule(args.path)) {
+    if (isSharedServerModule(args.file_path)) {
       ctx.isSharedModulesChanged = true;
     }
 
     if (!fs.existsSync(fullFilePath)) {
-      throw new Error(`File does not exist: ${args.path}`);
+      throw new Error(`File does not exist: ${args.file_path}`);
     }
 
-    const original = await readFile(fullFilePath, "utf8");
+    const original = await fs.promises.readFile(fullFilePath, "utf8");
+
     // Construct the operations string in the expected format
-    const operations = `<<<<<<< SEARCH\n${args.search}\n=======\n${args.replace}\n>>>>>>> REPLACE`;
+    const escapedOld = escapeSearchReplaceMarkers(args.old_string);
+    const escapedNew = escapeSearchReplaceMarkers(args.new_string);
+    const operations = `<<<<<<< SEARCH\n${escapedOld}\n=======\n${escapedNew}\n>>>>>>> REPLACE`;
+
     const result = applySearchReplace(original, operations);
 
     if (!result.success || typeof result.content !== "string") {
@@ -84,19 +119,19 @@ export const searchReplaceTool: ToolDefinition<
       );
     }
 
-    fs.writeFileSync(fullFilePath, result.content);
+    await fs.promises.writeFile(fullFilePath, result.content);
     logger.log(`Successfully applied search-replace to: ${fullFilePath}`);
 
     // Deploy Supabase function if applicable
     if (
       ctx.supabaseProjectId &&
-      isServerFunction(args.path) &&
+      isServerFunction(args.file_path) &&
       !ctx.isSharedModulesChanged
     ) {
       try {
         await deploySupabaseFunction({
           supabaseProjectId: ctx.supabaseProjectId,
-          functionName: path.basename(path.dirname(args.path)),
+          functionName: path.basename(path.dirname(args.file_path)),
           appPath: ctx.appPath,
           organizationSlug: ctx.supabaseOrganizationSlug ?? null,
         });
@@ -105,6 +140,6 @@ export const searchReplaceTool: ToolDefinition<
       }
     }
 
-    return `Successfully applied edits to ${args.path}`;
+    return `Successfully applied edits to ${args.file_path}`;
   },
 };

src/pro/main/ipc/processors/search_replace_dsl.spec.ts

+import { describe, it, expect } from "vitest";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { applySearchReplace } from "@/pro/main/ipc/processors/search_replace_processor";
+import {
+  parseDslTestCases,
+  isPassingTestCase,
+  isFailingTestCase,
+} from "@/pro/main/ipc/processors/search_replace_dsl_test_runner";
+
+// Load test case files
+const passesContent = readFileSync(
+  join(__dirname, "search_replace_passes.txt"),
+  "utf-8",
+);
+const failsContent = readFileSync(
+  join(__dirname, "search_replace_fails.txt"),
+  "utf-8",
+);
+
+const passingTestCases =
+  parseDslTestCases(passesContent).filter(isPassingTestCase);
+const failingTestCases =
+  parseDslTestCases(failsContent).filter(isFailingTestCase);
+
+describe("search_replace_processor - DSL passing tests", () => {
+  it.each(passingTestCases.map((tc) => [tc.name, tc]))(
+    "%s",
+    (_name, testCase) => {
+      if (!isPassingTestCase(testCase)) {
+        throw new Error("Expected passing test case");
+      }
+      const { success, content, error } = applySearchReplace(
+        testCase.original,
+        testCase.diff,
+      );
+      expect(success).toBe(true);
+      if (error) {
+        throw new Error(`Unexpected error: ${error}`);
+      }
+      expect(content).toBe(testCase.expectedOutput);
+    },
+  );
+});
+
+describe("search_replace_processor - DSL failing tests", () => {
+  it.each(failingTestCases.map((tc) => [tc.name, tc]))(
+    "%s",
+    (_name, testCase) => {
+      if (!isFailingTestCase(testCase)) {
+        throw new Error("Expected failing test case");
+      }
+      const { success, error } = applySearchReplace(
+        testCase.original,
+        testCase.diff,
+      );
+      expect(success).toBe(false);
+      expect(error).toBeDefined();
+      expect(error).toMatch(testCase.errorPattern);
+    },
+  );
+});

src/pro/main/ipc/processors/search_replace_dsl_test_runner.ts

+/**
+ * DSL Test Runner for Search/Replace Processor
+ *
+ * Parses test cases from .txt files with the following format:
+ *
+ * --- Test case name: descriptive name ---
+ * <original_file>
+ * ... original content ...
+ * </original_file>
+ * <<<<<<< SEARCH
+ * ... search content ...
+ * =======
+ * ... replace content ...
+ * >>>>>>> REPLACE
+ * <output_file>
+ * ... expected output ...
+ * </output_file>
+ *
+ * For failing tests, use <error_pattern> instead of <output_file>:
+ * <error_pattern>
+ * regex pattern to match error message
+ * </error_pattern>
+ */
+
+export interface PassingTestCase {
+  name: string;
+  original: string;
+  diff: string;
+  expectedOutput: string;
+}
+
+export interface FailingTestCase {
+  name: string;
+  original: string;
+  diff: string;
+  errorPattern: RegExp;
+}
+
+export type TestCase = PassingTestCase | FailingTestCase;
+
+export function isPassingTestCase(tc: TestCase): tc is PassingTestCase {
+  return "expectedOutput" in tc;
+}
+
+export function isFailingTestCase(tc: TestCase): tc is FailingTestCase {
+  return "errorPattern" in tc;
+}
+
+/**
+ * Parse a DSL test file into test cases.
+ * Handles both passing tests (with <output_file>) and failing tests (with <error_pattern>).
+ */
+export function parseDslTestCases(content: string): TestCase[] {
+  const testCases: TestCase[] = [];
+
+  // Split by test case delimiter
+  const testCasePattern = /---\s*Test case name:\s*(.+?)\s*---/g;
+  const matches = [...content.matchAll(testCasePattern)];
+
+  if (matches.length === 0) {
+    return testCases;
+  }
+
+  for (let i = 0; i < matches.length; i++) {
+    const match = matches[i];
+    const testName = match[1].trim();
+    const startIndex = match.index! + match[0].length;
+    const endIndex =
+      i + 1 < matches.length ? matches[i + 1].index! : content.length;
+    const testContent = content.slice(startIndex, endIndex);
+
+    const testCase = parseTestCase(testName, testContent);
+    if (testCase) {
+      testCases.push(testCase);
+    }
+  }
+
+  return testCases;
+}
+
+function parseTestCase(name: string, content: string): TestCase | null {
+  // Extract original file content
+  const originalMatch = content.match(
+    /<original_file>\r?\n([\s\S]*?)<\/original_file>/,
+  );
+  if (!originalMatch) {
+    console.warn(`Test case "${name}": missing <original_file> tag`);
+    return null;
+  }
+  const original = originalMatch[1];
+
+  // Extract diff content (everything between </original_file> and <output_file> or <error_pattern>)
+  const afterOriginal = content.slice(
+    content.indexOf("</original_file>") + "</original_file>".length,
+  );
+
+  // Find the diff block - it should contain the search/replace markers
+  let diff: string;
+  const outputFileIndex = afterOriginal.indexOf("<output_file>");
+  const errorPatternIndex = afterOriginal.indexOf("<error_pattern>");
+
+  if (outputFileIndex !== -1 && errorPatternIndex !== -1) {
+    // Both present - use whichever comes first
+    diff = afterOriginal.slice(0, Math.min(outputFileIndex, errorPatternIndex));
+  } else if (outputFileIndex !== -1) {
+    diff = afterOriginal.slice(0, outputFileIndex);
+  } else if (errorPatternIndex !== -1) {
+    diff = afterOriginal.slice(0, errorPatternIndex);
+  } else {
+    console.warn(
+      `Test case "${name}": missing <output_file> or <error_pattern> tag`,
+    );
+    return null;
+  }
+
+  // Trim leading/trailing whitespace but preserve internal structure
+  diff = diff.trim();
+
+  // Check for output_file (passing test)
+  const outputMatch = content.match(
+    /<output_file>\r?\n([\s\S]*?)<\/output_file>/,
+  );
+  if (outputMatch) {
+    return {
+      name,
+      original,
+      diff,
+      expectedOutput: outputMatch[1],
+    };
+  }
+
+  // Check for error_pattern (failing test)
+  const errorMatch = content.match(
+    /<error_pattern>\r?\n([\s\S]*?)<\/error_pattern>/,
+  );
+  if (errorMatch) {
+    const patternStr = errorMatch[1].trim();
+    try {
+      return {
+        name,
+        original,
+        diff,
+        errorPattern: new RegExp(patternStr, "i"),
+      };
+    } catch {
+      console.warn(
+        `Test case "${name}": invalid regex pattern "${patternStr}"`,
+      );
+      return null;
+    }
+  }
+
+  console.warn(
+    `Test case "${name}": missing <output_file> or <error_pattern> tag`,
+  );
+  return null;
+}

src/pro/main/ipc/processors/search_replace_fails.txt

+--- Test case name: empty search block not allowed ---
+<original_file>
+a
+b
+</original_file>
+<<<<<<< SEARCH
+=======
+REPLACEMENT
+>>>>>>> REPLACE
+<error_pattern>
+empty SEARCH block is not allowed
+</error_pattern>
+
+--- Test case name: search block does not match any content ---
+<original_file>
+foo
+bar
+baz
+</original_file>
+<<<<<<< SEARCH
+NOT IN FILE
+=======
+STILL NOT
+>>>>>>> REPLACE
+<error_pattern>
+Search block did not match any content
+</error_pattern>
+
+--- Test case name: ambiguous match multiple locations ---
+<original_file>
+foo
+bar
+baz
+bar
+qux
+</original_file>
+<<<<<<< SEARCH
+bar
+=======
+BAR
+>>>>>>> REPLACE
+<error_pattern>
+ambiguous|multiple
+</error_pattern>
+
+--- Test case name: ambiguous match with whitespace normalization ---
+<original_file>
+	if (ready) {
+		start();   
+	}
+  if (ready) {
+    start();   
+  }
+</original_file>
+<<<<<<< SEARCH
+if (ready) {
+  start();
+}
+=======
+if (ready) {
+  launch();
+}
+>>>>>>> REPLACE
+<error_pattern>
+ambiguous
+</error_pattern>
+
+--- Test case name: invalid diff format missing markers ---
+<original_file>
+some content
+</original_file>
+this is not a valid diff format
+<error_pattern>
+Invalid diff format.*missing required sections
+</error_pattern>
+
+--- Test case name: case mismatch is case sensitive ---
+<original_file>
+Hello World
+goodbye
+</original_file>
+<<<<<<< SEARCH
+hello world
+=======
+hi world
+>>>>>>> REPLACE
+<error_pattern>
+Search block did not match any content
+</error_pattern>
+
+--- Test case name: partial line does not match ---
+<original_file>
+the quick brown fox jumps
+over the lazy dog
+</original_file>
+<<<<<<< SEARCH
+brown fox
+=======
+red fox
+>>>>>>> REPLACE
+<error_pattern>
+Search block did not match any content
+</error_pattern>
+
+--- Test case name: search with extra context that does not exist ---
+<original_file>
+line one
+line two
+line three
+</original_file>
+<<<<<<< SEARCH
+line zero
+line one
+line two
+=======
+replaced
+>>>>>>> REPLACE
+<error_pattern>
+Search block did not match any content
+</error_pattern>
+
+--- Test case name: three or more identical matches ---
+<original_file>
+item
+---
+item
+---
+item
+</original_file>
+<<<<<<< SEARCH
+item
+=======
+ITEM
+>>>>>>> REPLACE
+<error_pattern>
+ambiguous|multiple
+</error_pattern>
+
+--- Test case name: only search marker no replace ---
+<original_file>
+content here
+</original_file>
+<<<<<<< SEARCH
+content here
+<error_pattern>
+Invalid diff format.*missing required sections
+</error_pattern>
+
+--- Test case name: only separator no markers ---
+<original_file>
+content here
+</original_file>
+=======
+replacement
+<error_pattern>
+Invalid diff format.*missing required sections
+</error_pattern>
+
+--- Test case name: search content is just empty lines ---
+<original_file>
+line one
+
+line three
+</original_file>
+<<<<<<< SEARCH
+
+
+=======
+replaced
+>>>>>>> REPLACE
+<error_pattern>
+empty SEARCH block is not allowed
+</error_pattern>
+
+--- Test case name: multiline search partial match fails ---
+<original_file>
+alpha
+beta
+gamma
+delta
+</original_file>
+<<<<<<< SEARCH
+beta
+gamma
+epsilon
+=======
+replaced
+>>>>>>> REPLACE
+<error_pattern>
+Search block did not match any content
+</error_pattern>
+
+--- Test case name: search matches but wrong line count ---
+<original_file>
+function foo() {
+  return 1;
+}
+</original_file>
+<<<<<<< SEARCH
+function foo() {
+  return 1;
+}
+extra line that does not exist
+=======
+replaced
+>>>>>>> REPLACE
+<error_pattern>
+Search block did not match any content
+</error_pattern>
+
+--- Test case name: empty original file cannot match search ---
+<original_file>
+</original_file>
+<<<<<<< SEARCH
+some content
+=======
+replacement
+>>>>>>> REPLACE
+<error_pattern>
+Search block did not match any content
+</error_pattern>

src/pro/main/ipc/processors/search_replace_passes.txt

+--- Test case name: simple single line replacement ---
+<original_file>
+hello world
+goodbye world
+</original_file>
+<<<<<<< SEARCH
+hello world
+=======
+hi world
+>>>>>>> REPLACE
+<output_file>
+hi world
+goodbye world
+</output_file>
+
+--- Test case name: multi-line search and replace ---
+<original_file>
+function calculate_total(items):
+    total = 0
+    for item in items:
+        total += item
+    return total
+</original_file>
+<<<<<<< SEARCH
+function calculate_total(items):
+    total = 0
+=======
+function calculate_sum(items):
+    total = 0
+>>>>>>> REPLACE
+<output_file>
+function calculate_sum(items):
+    total = 0
+    for item in items:
+        total += item
+    return total
+</output_file>
+
+--- Test case name: delete lines (empty replace) ---
+<original_file>
+line one
+line two
+line three
+</original_file>
+<<<<<<< SEARCH
+line two
+=======
+>>>>>>> REPLACE
+<output_file>
+line one
+line three
+</output_file>
+
+--- Test case name: preserve indentation ---
+<original_file>
+function test() {
+  if (x) {
+    doThing();
+  }
+}
+</original_file>
+<<<<<<< SEARCH
+  if (x) {
+    doThing();
+=======
+  if (x) {
+    doOther();
+>>>>>>> REPLACE
+<output_file>
+function test() {
+  if (x) {
+    doOther();
+  }
+}
+</output_file>
+
+--- Test case name: multiple blocks applied in sequence ---
+<original_file>
+1
+2
+3
+4
+5
+</original_file>
+<<<<<<< SEARCH
+1
+=======
+ONE
+>>>>>>> REPLACE
+
+<<<<<<< SEARCH
+4
+=======
+FOUR
+>>>>>>> REPLACE
+<output_file>
+ONE
+2
+3
+FOUR
+5
+</output_file>
+
+--- Test case name: trailing whitespace ignored ---
+<original_file>
+hello world   
+goodbye
+</original_file>
+<<<<<<< SEARCH
+hello world
+=======
+hi world
+>>>>>>> REPLACE
+<output_file>
+hi world
+goodbye
+</output_file>
+
+--- Test case name: leading and trailing whitespace ignored ---
+<original_file>
+  hello world  
+goodbye
+</original_file>
+<<<<<<< SEARCH
+hello world
+=======
+hi world
+>>>>>>> REPLACE
+<output_file>
+  hi world
+goodbye
+</output_file>
+
+--- Test case name: unicode smart quotes normalized ---
+<original_file>
+console.log("hello")
+other line
+</original_file>
+<<<<<<< SEARCH
+console.log("hello")
+=======
+console.log("goodbye")
+>>>>>>> REPLACE
+<output_file>
+console.log("goodbye")
+other line
+</output_file>
+
+--- Test case name: preserves CRLF line endings ---
+<original_file>
+a
+b
+c
+</original_file>
+<<<<<<< SEARCH
+b
+=======
+B
+>>>>>>> REPLACE
+<output_file>
+a
+B
+c
+</output_file>
+
+--- Test case name: escaped markers in search content ---
+<original_file>
+begin
+>>>>>>> REPLACE
+end
+</original_file>
+<<<<<<< SEARCH
+\>>>>>>> REPLACE
+=======
+LITERAL MARKER
+>>>>>>> REPLACE
+<output_file>
+begin
+LITERAL MARKER
+end
+</output_file>
+
+--- Test case name: search and replace identical is no-op ---
+<original_file>
+x
+middle
+z
+</original_file>
+<<<<<<< SEARCH
+middle
+=======
+middle
+>>>>>>> REPLACE
+<output_file>
+x
+middle
+z
+</output_file>
+
+--- Test case name: tabs vs spaces whitespace normalization ---
+<original_file>
+	if (ready) {
+		start();
+	}
+</original_file>
+<<<<<<< SEARCH
+  if (ready) {
+    start();
+  }
+=======
+  if (ready) {
+    launch();
+  }
+>>>>>>> REPLACE
+<output_file>
+	if (ready) {
+	  launch();
+	}
+</output_file>
+
+--- Test case name: extra leading newline in search trimmed ---
+<original_file>
+function test() {
+  return 1;
+}
+</original_file>
+<<<<<<< SEARCH
+
+  return 1;
+=======
+  return 2;
+>>>>>>> REPLACE
+<output_file>
+function test() {
+  return 2;
+}
+</output_file>
+
+--- Test case name: extra trailing newline in search trimmed ---
+<original_file>
+function test() {
+  return 1;
+}
+</original_file>
+<<<<<<< SEARCH
+  return 1;
+
+=======
+  return 2;
+>>>>>>> REPLACE
+<output_file>
+function test() {
+  return 2;
+}
+</output_file>
+
+--- Test case name: both leading and trailing empty lines in search trimmed ---
+<original_file>
+function test() {
+  return 1;
+}
+</original_file>
+<<<<<<< SEARCH
+
+
+  return 1;
+
+
+=======
+  return 2;
+>>>>>>> REPLACE
+<output_file>
+function test() {
+  return 2;
+}
+</output_file>
+
+--- Test case name: replace at beginning of file ---
+<original_file>
+first line
+second line
+third line
+</original_file>
+<<<<<<< SEARCH
+first line
+=======
+FIRST LINE
+>>>>>>> REPLACE
+<output_file>
+FIRST LINE
+second line
+third line
+</output_file>
+
+--- Test case name: replace at end of file ---
+<original_file>
+first line
+second line
+last line
+</original_file>
+<<<<<<< SEARCH
+last line
+=======
+LAST LINE
+>>>>>>> REPLACE
+<output_file>
+first line
+second line
+LAST LINE
+</output_file>
+
+--- Test case name: replace entire file content ---
+<original_file>
+old content
+</original_file>
+<<<<<<< SEARCH
+old content
+=======
+completely new content
+>>>>>>> REPLACE
+<output_file>
+completely new content
+</output_file>
+
+--- Test case name: multi-line to single-line replacement ---
+<original_file>
+before
+line one
+line two
+line three
+after
+</original_file>
+<<<<<<< SEARCH
+line one
+line two
+line three
+=======
+single line
+>>>>>>> REPLACE
+<output_file>
+before
+single line
+after
+</output_file>
+
+--- Test case name: single-line to multi-line replacement ---
+<original_file>
+before
+single line
+after
+</original_file>
+<<<<<<< SEARCH
+single line
+=======
+expanded line one
+expanded line two
+expanded line three
+>>>>>>> REPLACE
+<output_file>
+before
+expanded line one
+expanded line two
+expanded line three
+after
+</output_file>
+
+--- Test case name: deeply nested code indentation ---
+<original_file>
+class MyClass {
+  constructor() {
+    if (condition) {
+      while (true) {
+        doSomething();
+      }
+    }
+  }
+}
+</original_file>
+<<<<<<< SEARCH
+      while (true) {
+        doSomething();
+      }
+=======
+      for (let i = 0; i < 10; i++) {
+        doSomethingElse(i);
+      }
+>>>>>>> REPLACE
+<output_file>
+class MyClass {
+  constructor() {
+    if (condition) {
+      for (let i = 0; i < 10; i++) {
+        doSomethingElse(i);
+      }
+    }
+  }
+}
+</output_file>
+
+--- Test case name: search without indentation matches deeply indented code ---
+<original_file>
+class Outer {
+  constructor() {
+    if (condition) {
+      while (true) {
+        for (let i = 0; i < 10; i++) {
+          doSomething(i);
+        }
+      }
+    }
+  }
+}
+</original_file>
+<<<<<<< SEARCH
+for (let i = 0; i < 10; i++) {
+  doSomething(i);
+}
+=======
+for (let i = 0; i < 10; i++) {
+  doSomethingElse(i);
+  logProgress(i);
+}
+>>>>>>> REPLACE
+<output_file>
+class Outer {
+  constructor() {
+    if (condition) {
+      while (true) {
+        for (let i = 0; i < 10; i++) {
+          doSomethingElse(i);
+          logProgress(i);
+        }
+      }
+    }
+  }
+}
+</output_file>
+
+--- Test case name: search with extra indentation normalized to original ---
+<original_file>
+function test() {
+  if (x) {
+    doThing();
+  }
+}
+</original_file>
+<<<<<<< SEARCH
+        if (x) {
+          doThing();
+        }
+=======
+        if (x) {
+          doOther();
+          doMore();
+        }
+>>>>>>> REPLACE
+<output_file>
+function test() {
+  if (x) {
+    doOther();
+    doMore();
+  }
+}
+</output_file>
+
+--- Test case name: regex special characters treated as literal ---
+<original_file>
+const pattern = /.*[](){}^$/;
+const result = text.match(pattern);
+</original_file>
+<<<<<<< SEARCH
+const pattern = /.*[](){}^$/;
+=======
+const pattern = /[a-z]+/;
+>>>>>>> REPLACE
+<output_file>
+const pattern = /[a-z]+/;
+const result = text.match(pattern);
+</output_file>
+
+--- Test case name: code with brackets parentheses braces ---
+<original_file>
+function foo(a, b) {
+  return { x: [1, 2, 3], y: (a + b) };
+}
+</original_file>
+<<<<<<< SEARCH
+  return { x: [1, 2, 3], y: (a + b) };
+=======
+  return { x: [4, 5, 6], y: (a * b) };
+>>>>>>> REPLACE
+<output_file>
+function foo(a, b) {
+  return { x: [4, 5, 6], y: (a * b) };
+}
+</output_file>
+
+--- Test case name: string literals with various quotes ---
+<original_file>
+const single = 'hello';
+const double = "world";
+const template = `foo ${bar}`;
+</original_file>
+<<<<<<< SEARCH
+const single = 'hello';
+const double = "world";
+=======
+const single = 'goodbye';
+const double = "universe";
+>>>>>>> REPLACE
+<output_file>
+const single = 'goodbye';
+const double = "universe";
+const template = `foo ${bar}`;
+</output_file>
+
+--- Test case name: em-dash to regular dash normalization ---
+<original_file>
+const range = 10—20;
+</original_file>
+<<<<<<< SEARCH
+const range = 10-20;
+=======
+const range = 5-15;
+>>>>>>> REPLACE
+<output_file>
+const range = 5-15;
+</output_file>
+
+--- Test case name: ellipsis character normalization ---
+<original_file>
+console.log("Loading…");
+</original_file>
+<<<<<<< SEARCH
+console.log("Loading...");
+=======
+console.log("Done!");
+>>>>>>> REPLACE
+<output_file>
+console.log("Done!");
+</output_file>
+
+--- Test case name: non-breaking space normalization ---
+<original_file>
+const value = 100 units;
+</original_file>
+<<<<<<< SEARCH
+const value = 100 units;
+=======
+const value = 200 units;
+>>>>>>> REPLACE
+<output_file>
+const value = 200 units;
+</output_file>
+
+--- Test case name: very long line replacement ---
+<original_file>
+const longString = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+</original_file>
+<<<<<<< SEARCH
+const longString = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+=======
+const longString = "short";
+>>>>>>> REPLACE
+<output_file>
+const longString = "short";
+</output_file>
+
+--- Test case name: file with single line no trailing newline ---
+<original_file>
+single line content</original_file>
+<<<<<<< SEARCH
+single line content
+=======
+replaced content
+>>>>>>> REPLACE
+<output_file>
+replaced content</output_file>
+
+--- Test case name: replacement adds content to empty lines area ---
+<original_file>
+header
+
+footer
+</original_file>
+<<<<<<< SEARCH
+header
+=======
+header
+new middle content
+>>>>>>> REPLACE
+<output_file>
+header
+new middle content
+
+footer
+</output_file>
+
+--- Test case name: multiple sequential blocks non-overlapping ---
+<original_file>
+aaa
+bbb
+ccc
+ddd
+eee
+</original_file>
+<<<<<<< SEARCH
+aaa
+=======
+AAA
+>>>>>>> REPLACE
+
+<<<<<<< SEARCH
+ccc
+=======
+CCC
+>>>>>>> REPLACE
+
+<<<<<<< SEARCH
+eee
+=======
+EEE
+>>>>>>> REPLACE
+<output_file>
+AAA
+bbb
+CCC
+ddd
+EEE
+</output_file>
+
+--- Test case name: preserve blank lines in replacement ---
+<original_file>
+function foo() {
+  // old comment
+  return 1;
+}
+</original_file>
+<<<<<<< SEARCH
+  // old comment
+  return 1;
+=======
+  // new comment
+
+  return 2;
+>>>>>>> REPLACE
+<output_file>
+function foo() {
+  // new comment
+
+  return 2;
+}
+</output_file>
+
+--- Test case name: match with mixed indent styles in file ---
+<original_file>
+function mixed() {
+	tabIndent();
+  spaceIndent();
+}
+</original_file>
+<<<<<<< SEARCH
+  spaceIndent();
+=======
+  newSpaceIndent();
+>>>>>>> REPLACE
+<output_file>
+function mixed() {
+	tabIndent();
+  newSpaceIndent();
+}
+</output_file>
+
+--- Test case name: python style indentation ---
+<original_file>
+def greet(name):
+    if name:
+        print(f"Hello, {name}")
+    else:
+        print("Hello, stranger")
+</original_file>
+<<<<<<< SEARCH
+    if name:
+        print(f"Hello, {name}")
+    else:
+        print("Hello, stranger")
+=======
+    greeting = f"Hello, {name}" if name else "Hello, stranger"
+    print(greeting)
+>>>>>>> REPLACE
+<output_file>
+def greet(name):
+    greeting = f"Hello, {name}" if name else "Hello, stranger"
+    print(greeting)
+</output_file>
+
+--- Test case name: jsx component replacement ---
+<original_file>
+function App() {
+  return (
+    <div className="container">
+      <OldComponent prop="value" />
+    </div>
+  );
+}
+</original_file>
+<<<<<<< SEARCH
+      <OldComponent prop="value" />
+=======
+      <NewComponent prop="newValue" />
+>>>>>>> REPLACE
+<output_file>
+function App() {
+  return (
+    <div className="container">
+      <NewComponent prop="newValue" />
+    </div>
+  );
+}
+</output_file>
+
+--- Test case name: sql query replacement ---
+<original_file>
+SELECT id, name
+FROM users
+WHERE active = true
+ORDER BY name;
+</original_file>
+<<<<<<< SEARCH
+WHERE active = true
+=======
+WHERE active = true AND role = 'admin'
+>>>>>>> REPLACE
+<output_file>
+SELECT id, name
+FROM users
+WHERE active = true AND role = 'admin'
+ORDER BY name;
+</output_file>
+
+--- Test case name: json structure replacement ---
+<original_file>
+{
+  "name": "old-name",
+  "version": "1.0.0",
+  "description": "Old description"
+}
+</original_file>
+<<<<<<< SEARCH
+  "name": "old-name",
+=======
+  "name": "new-name",
+>>>>>>> REPLACE
+<output_file>
+{
+  "name": "new-name",
+  "version": "1.0.0",
+  "description": "Old description"
+}
+</output_file>
+
+--- Test case name: yaml indentation preservation ---
+<original_file>
+services:
+  web:
+    image: nginx
+    ports:
+      - "80:80"
+</original_file>
+<<<<<<< SEARCH
+    image: nginx
+=======
+    image: apache
+>>>>>>> REPLACE
+<output_file>
+services:
+  web:
+    image: apache
+    ports:
+      - "80:80"
+</output_file>
+
+--- Test case name: markdown code block replacement ---
+<original_file>
+# Example
+
+```javascript
+const old = true;
+```
+
+More text.
+</original_file>
+<<<<<<< SEARCH
+```javascript
+const old = true;
+```
+=======
+```typescript
+const updated: boolean = true;
+```
+>>>>>>> REPLACE
+<output_file>
+# Example
+
+```typescript
+const updated: boolean = true;
+```
+
+More text.
+</output_file>
+
+--- Test case name: single character search ---
+<original_file>
+a
+b
+c
+</original_file>
+<<<<<<< SEARCH
+b
+=======
+X
+>>>>>>> REPLACE
+<output_file>
+a
+X
+c
+</output_file>
+
+--- Test case name: emoji unicode characters ---
+<original_file>
+const status = "🚀 launching";
+console.log(status);
+</original_file>
+<<<<<<< SEARCH
+const status = "🚀 launching";
+=======
+const status = "✅ complete";
+>>>>>>> REPLACE
+<output_file>
+const status = "✅ complete";
+console.log(status);
+</output_file>
+
+--- Test case name: CJK unicode characters ---
+<original_file>
+const greeting = "你好世界";
+print(greeting);
+</original_file>
+<<<<<<< SEARCH
+const greeting = "你好世界";
+=======
+const greeting = "こんにちは";
+>>>>>>> REPLACE
+<output_file>
+const greeting = "こんにちは";
+print(greeting);
+</output_file>
+
+--- Test case name: URL strings in code ---
+<original_file>
+const apiUrl = "https://api.example.com/v1/users?id=123&format=json";
+fetch(apiUrl);
+</original_file>
+<<<<<<< SEARCH
+const apiUrl = "https://api.example.com/v1/users?id=123&format=json";
+=======
+const apiUrl = "https://api.example.com/v2/users?id=123&format=json";
+>>>>>>> REPLACE
+<output_file>
+const apiUrl = "https://api.example.com/v2/users?id=123&format=json";
+fetch(apiUrl);
+</output_file>
+
+--- Test case name: backslash escape sequences ---
+<original_file>
+const pattern = "line1\nline2\ttabbed";
+const path = "C:\\Users\\name";
+</original_file>
+<<<<<<< SEARCH
+const pattern = "line1\nline2\ttabbed";
+=======
+const pattern = "line1\n\nline2";
+>>>>>>> REPLACE
+<output_file>
+const pattern = "line1\n\nline2";
+const path = "C:\\Users\\name";
+</output_file>
+
+--- Test case name: windows paths with backslashes ---
+<original_file>
+const configPath = "C:\\Program Files\\App\\config.json";
+loadConfig(configPath);
+</original_file>
+<<<<<<< SEARCH
+const configPath = "C:\\Program Files\\App\\config.json";
+=======
+const configPath = "D:\\Data\\App\\config.json";
+>>>>>>> REPLACE
+<output_file>
+const configPath = "D:\\Data\\App\\config.json";
+loadConfig(configPath);
+</output_file>
+
+--- Test case name: HTML angle brackets ---
+<original_file>
+const template = "<div class=\"container\"><span>Hello</span></div>";
+render(template);
+</original_file>
+<<<<<<< SEARCH
+const template = "<div class=\"container\"><span>Hello</span></div>";
+=======
+const template = "<section class=\"wrapper\"><p>Hello</p></section>";
+>>>>>>> REPLACE
+<output_file>
+const template = "<section class=\"wrapper\"><p>Hello</p></section>";
+render(template);
+</output_file>
+
+--- Test case name: XML content ---
+<original_file>
+<?xml version="1.0"?>
+<root>
+  <item id="1">Value</item>
+</root>
+</original_file>
+<<<<<<< SEARCH
+  <item id="1">Value</item>
+=======
+  <item id="2">New Value</item>
+>>>>>>> REPLACE
+<output_file>
+<?xml version="1.0"?>
+<root>
+  <item id="2">New Value</item>
+</root>
+</output_file>
+
+--- Test case name: C style block comments ---
+<original_file>
+/* This is a comment
+   spanning multiple lines */
+int main() {
+  return 0;
+}
+</original_file>
+<<<<<<< SEARCH
+/* This is a comment
+   spanning multiple lines */
+=======
+/* Updated comment */
+>>>>>>> REPLACE
+<output_file>
+/* Updated comment */
+int main() {
+  return 0;
+}
+</output_file>
+
+--- Test case name: shell style comments ---
+<original_file>
+#!/bin/bash
+# This is a comment
+echo "Hello"
+# Another comment
+</original_file>
+<<<<<<< SEARCH
+# This is a comment
+=======
+# Updated comment
+>>>>>>> REPLACE
+<output_file>
+#!/bin/bash
+# Updated comment
+echo "Hello"
+# Another comment
+</output_file>
+
+--- Test case name: consecutive blank lines in middle of search ---
+<original_file>
+header
+
+content
+
+footer
+</original_file>
+<<<<<<< SEARCH
+header
+
+content
+=======
+HEADER
+
+CONTENT
+>>>>>>> REPLACE
+<output_file>
+HEADER
+
+CONTENT
+
+footer
+</output_file>
+
+--- Test case name: cascading edits second block targets first output ---
+<original_file>
+original
+</original_file>
+<<<<<<< SEARCH
+original
+=======
+intermediate
+>>>>>>> REPLACE
+
+<<<<<<< SEARCH
+intermediate
+=======
+final
+>>>>>>> REPLACE
+<output_file>
+final
+</output_file>
+
+--- Test case name: cascading edits three blocks ---
+<original_file>
+step1
+</original_file>
+<<<<<<< SEARCH
+step1
+=======
+step2
+>>>>>>> REPLACE
+
+<<<<<<< SEARCH
+step2
+=======
+step3
+>>>>>>> REPLACE
+
+<<<<<<< SEARCH
+step3
+=======
+step4
+>>>>>>> REPLACE
+<output_file>
+step4
+</output_file>

src/pro/main/ipc/processors/search_replace_processor.spec.ts

-import { describe, it, expect } from "vitest";
-import { applySearchReplace } from "@/pro/main/ipc/processors/search_replace_processor";
+import { describe, it, expect, vi, beforeEach } from "vitest";
 import { parseSearchReplaceBlocks } from "@/pro/shared/search_replace_parser";
 
+// Create mock logger functions that we can spy on
+const mockError = vi.fn();
+const mockWarn = vi.fn();
+const mockDebug = vi.fn();
+
+// Mock electron-log - must be before importing the module that uses it
+vi.mock("electron-log", () => {
+  return {
+    default: {
+      scope: () => ({
+        log: vi.fn(),
+        warn: (...args: unknown[]) => mockWarn(...args),
+        error: (...args: unknown[]) => mockError(...args),
+        debug: (...args: unknown[]) => mockDebug(...args),
+      }),
+    },
+  };
+});
+
+// Import after mock is set up
+import { applySearchReplace } from "@/pro/main/ipc/processors/search_replace_processor";
+
 describe("search_replace_processor - parseSearchReplaceBlocks", () => {
   it("parses multiple blocks with start_line in ascending order", () => {
     const diff = `
@@ -259,7 +280,7 @@ BAR
     expect(error).toMatch(/(ambiguous|multiple)/i);
   });
 
-  it("errors when SEARCH block fuzzy matches multiple locations (ambiguous)", () => {
+  it("errors when SEARCH block matches multiple locations with whitespace normalization (ambiguous)", () => {
     const original = [
       "\tif (ready) {",
       "\t\tstart();   ",
@@ -283,7 +304,7 @@ if (ready) {
 
     const { success, error } = applySearchReplace(original, diff);
     expect(success).toBe(false);
-    expect(error).toMatch(/fuzzy matched/i);
+    expect(error).toMatch(/ambiguous/i);
   });
 
   it("errors when SEARCH block is empty", () => {
@@ -299,3 +320,361 @@ REPLACEMENT
     expect(error).toMatch(/empty SEARCH block is not allowed/i);
   });
 });
+
+describe("search_replace_processor - cascading matching passes", () => {
+  it("Pass 1: matches exactly when content is identical", () => {
+    const original = ["  hello world", "  goodbye"].join("\n");
+    const diff = `
+<<<<<<< SEARCH
+  hello world
+=======
+  hi world
+>>>>>>> REPLACE
+`;
+    const { success, content } = applySearchReplace(original, diff);
+    expect(success).toBe(true);
+    expect(content).toContain("hi world");
+  });
+
+  it("Pass 2: matches when only trailing whitespace differs", () => {
+    const original = ["hello world   ", "goodbye"].join("\n"); // trailing spaces in file
+    const diff = `
+<<<<<<< SEARCH
+hello world
+=======
+hi world
+>>>>>>> REPLACE
+`;
+    const { success, content } = applySearchReplace(original, diff);
+    expect(success).toBe(true);
+    expect(content).toContain("hi world");
+  });
+
+  it("Pass 3: matches when leading/trailing whitespace differs", () => {
+    const original = ["  hello world  ", "goodbye"].join("\n"); // spaces on both ends
+    const diff = `
+<<<<<<< SEARCH
+hello world
+=======
+hi world
+>>>>>>> REPLACE
+`;
+    const { success, content } = applySearchReplace(original, diff);
+    expect(success).toBe(true);
+    expect(content).toContain("hi world");
+  });
+
+  it("Pass 4: matches with unicode normalization (smart quotes)", () => {
+    const original = ['console.log("hello")', "other line"].join("\n"); // smart quotes
+    const diff = `
+<<<<<<< SEARCH
+console.log("hello")
+=======
+console.log("goodbye")
+>>>>>>> REPLACE
+`;
+    const { success, content } = applySearchReplace(original, diff);
+    expect(success).toBe(true);
+    expect(content).toContain('console.log("goodbye")');
+  });
+
+  it("Pass 4: matches with unicode normalization (en-dash/em-dash)", () => {
+    const original = ["value = 10–20", "other line"].join("\n"); // en-dash
+    const diff = `
+<<<<<<< SEARCH
+value = 10-20
+=======
+value = 5-15
+>>>>>>> REPLACE
+`;
+    const { success, content } = applySearchReplace(original, diff);
+    expect(success).toBe(true);
+    expect(content).toContain("value = 5-15");
+  });
+
+  it("Pass 4: matches with unicode normalization (non-breaking space)", () => {
+    const original = ["hello\u00A0world", "other line"].join("\n"); // non-breaking space
+    const diff = `
+<<<<<<< SEARCH
+hello world
+=======
+hi world
+>>>>>>> REPLACE
+`;
+    const { success, content } = applySearchReplace(original, diff);
+    expect(success).toBe(true);
+    expect(content).toContain("hi world");
+  });
+
+  it("fails when no pass matches", () => {
+    const original = ["completely different content", "more lines"].join("\n");
+    const diff = `
+<<<<<<< SEARCH
+this does not exist
+=======
+replacement
+>>>>>>> REPLACE
+`;
+    const { success, error } = applySearchReplace(original, diff);
+    expect(success).toBe(false);
+    expect(error).toMatch(/did not match any content/i);
+  });
+});
+
+describe("search_replace_processor - options", () => {
+  describe("leading/trailing empty line trimming", () => {
+    it("matches when search has extra trailing newline", () => {
+      const original = ["function test() {", "  return 1;", "}"].join("\n");
+      const diff = `
+<<<<<<< SEARCH
+  return 1;
+
+=======
+  return 2;
+>>>>>>> REPLACE
+`;
+      const { success, content } = applySearchReplace(original, diff);
+      expect(success).toBe(true);
+      expect(content).toContain("return 2");
+    });
+
+    it("matches when search has extra leading newline", () => {
+      const original = ["function test() {", "  return 1;", "}"].join("\n");
+      const diff = `
+<<<<<<< SEARCH
+
+  return 1;
+=======
+  return 2;
+>>>>>>> REPLACE
+`;
+      const { success, content } = applySearchReplace(original, diff);
+      expect(success).toBe(true);
+      expect(content).toContain("return 2");
+    });
+
+    it("matches when search has both leading and trailing empty lines", () => {
+      const original = ["function test() {", "  return 1;", "}"].join("\n");
+      const diff = `
+<<<<<<< SEARCH
+
+
+  return 1;
+
+
+=======
+  return 2;
+>>>>>>> REPLACE
+`;
+      const { success, content } = applySearchReplace(original, diff);
+      expect(success).toBe(true);
+      expect(content).toContain("return 2");
+    });
+
+    it("uses trimmed match only when exact match fails", () => {
+      // File does NOT have a leading empty line before the target
+      const original = ["function test() {", "  return 1;", "}"].join("\n");
+      // Search has leading empty line that doesn't exist in file
+      const diff = `
+<<<<<<< SEARCH
+
+  return 1;
+=======
+  return 2;
+>>>>>>> REPLACE
+`;
+      const { success, content } = applySearchReplace(original, diff);
+      expect(success).toBe(true);
+      // Should match via trimming since exact match with empty line fails
+      expect(content).toContain("return 2");
+      // Original structure preserved (no extra empty lines added)
+      expect(content).toBe(
+        ["function test() {", "  return 2;", "}"].join("\n"),
+      );
+    });
+
+    it("does not trim if exact match succeeds", () => {
+      const original = ["line1", "line2", "line3"].join("\n");
+      const diff = `
+<<<<<<< SEARCH
+line2
+=======
+REPLACED
+>>>>>>> REPLACE
+`;
+      const { success, content } = applySearchReplace(original, diff);
+      expect(success).toBe(true);
+      expect(content).toBe(["line1", "REPLACED", "line3"].join("\n"));
+    });
+  });
+});
+
+describe("search_replace_processor - detailed failure logging", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("logs detailed diagnostic information when search block does not match", () => {
+    const original = [
+      "function greet() {",
+      "  console.log('Hello');",
+      "  return true;",
+      "}",
+      "",
+      "function farewell() {",
+      "  console.log('Goodbye');",
+      "  return false;",
+      "}",
+    ].join("\n");
+
+    const diff = `
+<<<<<<< SEARCH
+function greet() {
+  console.log('Hi there');
+  return true;
+}
+=======
+function greet() {
+  console.log('Hello World');
+  return true;
+}
+>>>>>>> REPLACE
+`;
+
+    const { success, error } = applySearchReplace(original, diff);
+    expect(success).toBe(false);
+    expect(error).toContain("did not match");
+
+    // Verify detailed logging was called with expected diagnostic information
+    const allErrorCalls = mockError.mock.calls
+      .map((call) => call[0])
+      .join("\n");
+    expect(allErrorCalls).toMatchInlineSnapshot(`
+      "=== SEARCH/REPLACE MATCH FAILURE (Block 1) ===
+
+      --- SEARCH CONTENT (4 lines) ---
+          1: "function greet() {"
+          2: "  console.log('Hi there');"
+          3: "  return true;"
+          4: "}"
+
+      --- BEST PARTIAL MATCH: 3/4 lines match ---
+          Location: lines 1-4 of original file
+          First mismatch at search line: 2
+
+      --- ORIGINAL FILE (lines 1-9, match region marked with >) ---
+        >    1: "function greet() {"
+        X    2: "  console.log('Hello');"
+        >    3: "  return true;"
+        >    4: "}"
+             5: ""
+             6: "function farewell() {"
+             7: "  console.log('Goodbye');"
+             8: "  return false;"
+             9: "}"
+
+      --- FIRST MISMATCH DETAILS ---
+        Search line 2: "  console.log('Hi there');"
+        File line 2:   "  console.log('Hello');"
+
+      === END MATCH FAILURE ===
+      "
+    `);
+  });
+
+  it("logs the correct number of matching lines in partial match", () => {
+    const original = [
+      "line one",
+      "line two",
+      "line three",
+      "line four",
+      "line five",
+    ].join("\n");
+
+    // Search for content where 2 out of 3 lines match
+    const diff = `
+<<<<<<< SEARCH
+line two
+WRONG LINE
+line four
+=======
+replaced
+>>>>>>> REPLACE
+`;
+
+    const { success } = applySearchReplace(original, diff);
+    expect(success).toBe(false);
+
+    // Verify logging shows partial match info
+    const allErrorCalls = mockError.mock.calls
+      .map((call) => call[0])
+      .join("\n");
+    expect(allErrorCalls).toMatchInlineSnapshot(`
+      "=== SEARCH/REPLACE MATCH FAILURE (Block 1) ===
+
+      --- SEARCH CONTENT (3 lines) ---
+          1: "line two"
+          2: "WRONG LINE"
+          3: "line four"
+
+      --- BEST PARTIAL MATCH: 2/3 lines match ---
+          Location: lines 2-4 of original file
+          First mismatch at search line: 2
+
+      --- ORIGINAL FILE (lines 1-5, match region marked with >) ---
+             1: "line one"
+        >    2: "line two"
+        X    3: "line three"
+        >    4: "line four"
+             5: "line five"
+
+      --- FIRST MISMATCH DETAILS ---
+        Search line 2: "WRONG LINE"
+        File line 3:   "line three"
+
+      === END MATCH FAILURE ===
+      "
+    `);
+  });
+
+  it("logs with JSON escaping to show invisible characters", () => {
+    const original = "hello\tworld\ntest";
+
+    const diff = `
+<<<<<<< SEARCH
+hello world
+=======
+replaced
+>>>>>>> REPLACE
+`;
+
+    const { success } = applySearchReplace(original, diff);
+    expect(success).toBe(false);
+
+    // Verify JSON.stringify is used (shows \t as escaped in the output)
+    const allErrorCalls = mockError.mock.calls
+      .map((call) => call[0])
+      .join("\n");
+    expect(allErrorCalls).toMatchInlineSnapshot(`
+      "=== SEARCH/REPLACE MATCH FAILURE (Block 1) ===
+
+      --- SEARCH CONTENT (1 lines) ---
+          1: "hello world"
+
+      --- BEST PARTIAL MATCH: 0/1 lines match ---
+          Location: lines 1-1 of original file
+          First mismatch at search line: 1
+
+      --- ORIGINAL FILE (lines 1-2, match region marked with >) ---
+        X    1: "hello\\tworld"
+             2: "test"
+
+      --- FIRST MISMATCH DETAILS ---
+        Search line 1: "hello world"
+        File line 1:   "hello\\tworld"
+
+      === END MATCH FAILURE ===
+      "
+    `);
+  });
+});

src/pro/main/ipc/processors/search_replace_processor.test.ts

@@ -2,32 +2,8 @@ import { describe, it, expect } from "vitest";
 import { applySearchReplace } from "./search_replace_processor";
 
 describe("applySearchReplace", () => {
-  describe("fuzzy matching with Levenshtein distance", () => {
-    it("should match content with minor typos", () => {
-      const originalContent = `function hello() {
-  console.log("Hello, World!");
-  return true;
-}`;
-
-      // Search block has a typo: "consle" instead of "console"
-      const diffContent = `<<<<<<< SEARCH
-function hello() {
-  consle.log("Hello, World!");
-  return true;
-}
-=======
-function hello() {
-  console.log("Hello, Universe!");
-  return true;
-}
->>>>>>> REPLACE`;
-
-      const result = applySearchReplace(originalContent, diffContent);
-      expect(result.success).toBe(true);
-      expect(result.content).toContain("Hello, Universe!");
-    });
-
-    it("should match content with smart quotes normalized", () => {
+  describe("cascading fuzzy matching", () => {
+    it("should match content with smart quotes normalized (Pass 4)", () => {
       const originalContent = `function greet() {
   console.log("Hello");
 }`;
@@ -48,16 +24,16 @@ function greet() {
       expect(result.content).toContain("Goodbye");
     });
 
-    it("should fail when similarity is below threshold", () => {
+    it("should fail when content does not match in any pass", () => {
       const originalContent = `function hello() {
   console.log("Hello, World!");
   return true;
 }`;
 
-      // Search block is too different (multiple typos and changes)
+      // Search block is completely different
       const diffContent = `<<<<<<< SEARCH
 function goodbye() {
-  consle.error("Bye, Earth!");
+  console.error("Bye, Earth!");
   return false;
 }
 =======
@@ -69,19 +45,19 @@ function hello() {
 
       const result = applySearchReplace(originalContent, diffContent);
       expect(result.success).toBe(false);
-      expect(result.error).toContain("Best fuzzy match had similarity");
+      expect(result.error).toContain("did not match any content");
     });
 
-    it("should prefer exact match over fuzzy match", () => {
+    it("should prefer exact match when available", () => {
       const originalContent = `function hello() {
   console.log("Hello");
 }
 
 function hello() {
-  consle.log("Hello");
+  console.log("Hello");
 }`;
 
-      // Should match the first exact occurrence, not the fuzzy one
+      // Both occurrences are exact matches - should be ambiguous
       const diffContent = `<<<<<<< SEARCH
 function hello() {
   console.log("Hello");
@@ -93,13 +69,11 @@ function hello() {
 >>>>>>> REPLACE`;
 
       const result = applySearchReplace(originalContent, diffContent);
-      expect(result.success).toBe(true);
-      // Should only replace the first exact match
-      expect(result.content).toContain('console.log("Goodbye")');
-      expect(result.content).toContain('consle.log("Hello")');
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("ambiguous");
     });
 
-    it("should handle whitespace differences with lenient matching before fuzzy", () => {
+    it("should handle whitespace differences with edge whitespace normalization (Pass 3)", () => {
       const originalContent = `function test() {
     console.log("test");
 }`;

src/pro/main/ipc/processors/search_replace_processor.ts

 /* eslint-disable no-irregular-whitespace */
 
 import { parseSearchReplaceBlocks } from "@/pro/shared/search_replace_parser";
-import { distance } from "fastest-levenshtein";
 import { normalizeString } from "@/utils/text_normalization";
 import log from "electron-log";
 
 const logger = log.scope("search_replace_processor");
 
-// Minimum similarity threshold for fuzzy matching (0 to 1, where 1 is exact match)
-const FUZZY_MATCH_THRESHOLD = 0.9;
-
-// Early termination threshold - stop searching if we find a match this good
-const EARLY_STOP_THRESHOLD = 0.95;
-
-// Maximum time to spend on fuzzy matching (in milliseconds)
-const MAX_FUZZY_SEARCH_TIME_MS = 10_000; // 10 seconds
+// ============================================================================
+// Options Interface
+// ============================================================================
 
 function unescapeMarkers(content: string): string {
   return content
@@ -23,146 +17,257 @@ function unescapeMarkers(content: string): string {
     .replace(/^\\>>>>>>>/gm, ">>>>>>>");
 }
 
+// ============================================================================
+// Cascading Fuzzy Matching
+// ============================================================================
+// The tool locates where to apply changes by matching context lines against the file.
+// Implements cascading fuzzy matching with decreasing strictness:
+//
+// Pass 1: Exact Match
+// Pass 2: Trailing Whitespace Ignored
+// Pass 3: All Edge Whitespace Ignored
+// Pass 4: Unicode Normalization
+// ============================================================================
+
+type LineComparator = (fileLine: string, patternLine: string) => boolean;
+
 /**
- * Calculate similarity between two strings using Levenshtein distance
- * Returns a value between 0 and 1, where 1 is an exact match
+ * Pass 1: Exact Match
+ * file_line == pattern_line
  */
-function getSimilarity(original: string, search: string): number {
-  // Empty searches are no longer supported
-  if (search === "") {
-    return 0;
-  }
+const exactMatch: LineComparator = (fileLine, patternLine) =>
+  fileLine === patternLine;
 
-  // Use the normalizeString utility to handle smart quotes and other special characters
-  const normalizedOriginal = normalizeString(original);
-  const normalizedSearch = normalizeString(search);
+/**
+ * Pass 2: Trailing Whitespace Ignored
+ * file_line.trimEnd() == pattern_line.trimEnd()
+ */
+const trailingWhitespaceIgnored: LineComparator = (fileLine, patternLine) =>
+  fileLine.trimEnd() === patternLine.trimEnd();
 
-  if (normalizedOriginal === normalizedSearch) {
-    return 1;
-  }
+/**
+ * Pass 3: All Edge Whitespace Ignored
+ * file_line.trim() == pattern_line.trim()
+ */
+const allEdgeWhitespaceIgnored: LineComparator = (fileLine, patternLine) =>
+  fileLine.trim() === patternLine.trim();
 
-  // Calculate Levenshtein distance using fastest-levenshtein's distance function
-  const dist = distance(normalizedOriginal, normalizedSearch);
+/**
+ * Pass 4: Unicode Normalization
+ * Normalize common Unicode variants to ASCII before comparing:
+ * - En-dash, em-dash, etc. → -
+ * - Smart quotes → " '
+ * - Non-breaking space → regular space
+ */
+const unicodeNormalized: LineComparator = (fileLine, patternLine) =>
+  normalizeString(fileLine.trim()) === normalizeString(patternLine.trim());
 
-  // Calculate similarity ratio (0 to 1, where 1 is an exact match)
-  const maxLength = Math.max(
-    normalizedOriginal.length,
-    normalizedSearch.length,
-  );
-  return 1 - dist / maxLength;
+/**
+ * All matching passes in order of decreasing strictness
+ */
+const MATCHING_PASSES: Array<{ name: string; comparator: LineComparator }> = [
+  { name: "exact", comparator: exactMatch },
+  {
+    name: "trailing-whitespace-ignored",
+    comparator: trailingWhitespaceIgnored,
+  },
+  { name: "all-edge-whitespace-ignored", comparator: allEdgeWhitespaceIgnored },
+  { name: "unicode-normalized", comparator: unicodeNormalized },
+];
+
+/**
+ * Trim leading and trailing empty lines from an array of lines
+ */
+function trimEmptyLines(lines: string[]): string[] {
+  const result = [...lines];
+  while (result.length > 0 && result[0] === "") {
+    result.shift();
+  }
+  while (result.length > 0 && result[result.length - 1] === "") {
+    result.pop();
+  }
+  return result;
 }
 
 /**
- * Quick scoring function that counts how many lines exactly match.
- * This is much faster than Levenshtein and serves as a good pre-filter.
+ * Find all positions where searchLines match against resultLines using the given comparator
  */
-function quickScoreByExactLines(
-  targetLines: string[],
+function findMatchPositions(
+  resultLines: string[],
   searchLines: string[],
-  startIdx: number,
-): number {
-  let exactMatches = 0;
-
-  for (let i = 0; i < searchLines.length; i++) {
-    if (startIdx + i >= targetLines.length) break;
-
-    if (
-      normalizeString(targetLines[startIdx + i]) ===
-      normalizeString(searchLines[i])
-    ) {
-      exactMatches++;
+  comparator: LineComparator,
+): number[] {
+  const positions: number[] = [];
+
+  for (let i = 0; i <= resultLines.length - searchLines.length; i++) {
+    let allMatch = true;
+    for (let j = 0; j < searchLines.length; j++) {
+      if (!comparator(resultLines[i + j], searchLines[j])) {
+        allMatch = false;
+        break;
+      }
+    }
+    if (allMatch) {
+      positions.push(i);
+      // For ambiguity detection, we only need to know if there's more than one
+      if (positions.length > 1) break;
     }
   }
 
-  return exactMatches / searchLines.length;
+  return positions;
 }
 
 /**
- * Fast fuzzy search using a two-pass approach:
- * 1. Quick pre-filter pass: Count exact line matches (fast)
- * 2. Detailed pass: Only compute Levenshtein on promising candidates (expensive)
- *
- * The key insight: If two blocks are similar enough for fuzzy matching (e.g., 90%),
- * then likely at least 60% of their lines will match exactly.
+ * Find the best partial match - the position in resultLines where the most
+ * consecutive lines from searchLines match (using unicode-normalized comparison)
  */
-function fastFuzzySearch(
-  lines: string[],
-  searchChunk: string,
-  startIndex: number,
-  endIndex: number,
-) {
-  const searchLines = searchChunk.split(/\r?\n/);
-  const searchLen = searchLines.length;
-
-  // Track start time for timeout
-  const startTime = performance.now();
-
-  // Quick threshold: require at least 60% exact line matches to be a candidate
-  const QUICK_THRESHOLD = 0.6;
-
-  // First pass: find candidates with high exact line match ratio (very fast)
-  const candidates: Array<{ index: number; quickScore: number }> = [];
-
-  for (let i = startIndex; i <= endIndex - searchLen; i++) {
-    // Check time limit
-    const elapsed = performance.now() - startTime;
-    if (elapsed > MAX_FUZZY_SEARCH_TIME_MS) {
-      console.warn(
-        `Fast fuzzy search timed out during pre-filter after ${(elapsed / 1000).toFixed(1)}s`,
-      );
-      break;
+function findBestPartialMatch(
+  resultLines: string[],
+  searchLines: string[],
+): { startIndex: number; matchingLines: number; firstMismatchIndex: number } {
+  let bestStartIndex = 0;
+  let bestMatchingLines = 0;
+  let bestFirstMismatchIndex = 0;
+
+  for (let i = 0; i < resultLines.length; i++) {
+    let matchingLines = 0;
+    let firstMismatchIndex = -1;
+
+    for (let j = 0; j < searchLines.length && i + j < resultLines.length; j++) {
+      if (unicodeNormalized(resultLines[i + j], searchLines[j])) {
+        matchingLines++;
+      } else {
+        if (firstMismatchIndex === -1) {
+          firstMismatchIndex = j;
+        }
+        // Continue counting to find total matching lines, not just consecutive
+      }
     }
 
-    const quickScore = quickScoreByExactLines(lines, searchLines, i);
-
-    if (quickScore >= QUICK_THRESHOLD) {
-      candidates.push({ index: i, quickScore });
+    if (matchingLines > bestMatchingLines) {
+      bestMatchingLines = matchingLines;
+      bestStartIndex = i;
+      bestFirstMismatchIndex =
+        firstMismatchIndex === -1 ? searchLines.length : firstMismatchIndex;
     }
   }
 
-  // Sort candidates by quick score (best first)
-  candidates.sort((a, b) => b.quickScore - a.quickScore);
+  return {
+    startIndex: bestStartIndex,
+    matchingLines: bestMatchingLines,
+    firstMismatchIndex: bestFirstMismatchIndex,
+  };
+}
+
+/**
+ * Log detailed information about a failed match to help diagnose issues
+ */
+function logMatchFailure(
+  resultLines: string[],
+  searchLines: string[],
+  blockIndex: number,
+): void {
+  logger.error(
+    `=== SEARCH/REPLACE MATCH FAILURE (Block ${blockIndex + 1}) ===`,
+  );
 
-  // Second pass: only compute expensive Levenshtein on top candidates
-  let bestScore = 0;
-  let bestMatchIndex = -1;
+  // Log search content
+  logger.error(`\n--- SEARCH CONTENT (${searchLines.length} lines) ---`);
+  searchLines.forEach((line, i) => {
+    logger.error(`  ${String(i + 1).padStart(3)}: ${JSON.stringify(line)}`);
+  });
 
-  const MAX_CANDIDATES_TO_CHECK = 10; // Only check top 10 candidates
+  // Find best partial match
+  const bestMatch = findBestPartialMatch(resultLines, searchLines);
 
-  for (
-    let i = 0;
-    i < Math.min(candidates.length, MAX_CANDIDATES_TO_CHECK);
-    i++
-  ) {
-    const candidate = candidates[i];
+  logger.error(
+    `\n--- BEST PARTIAL MATCH: ${bestMatch.matchingLines}/${searchLines.length} lines match ---`,
+  );
+  logger.error(
+    `    Location: lines ${bestMatch.startIndex + 1}-${bestMatch.startIndex + searchLines.length} of original file`,
+  );
+  logger.error(
+    `    First mismatch at search line: ${bestMatch.firstMismatchIndex + 1}`,
+  );
 
-    // Check time limit
-    const elapsed = performance.now() - startTime;
-    if (elapsed > MAX_FUZZY_SEARCH_TIME_MS) {
-      console.warn(
-        `Fast fuzzy search timed out during detailed pass after ${(elapsed / 1000).toFixed(1)}s. Best match: ${(bestScore * 100).toFixed(1)}%`,
+  // Show the relevant section of the original file with context
+  const contextLines = 5;
+  const startLine = Math.max(0, bestMatch.startIndex - contextLines);
+  const endLine = Math.min(
+    resultLines.length,
+    bestMatch.startIndex + searchLines.length + contextLines,
+  );
+
+  logger.error(
+    `\n--- ORIGINAL FILE (lines ${startLine + 1}-${endLine}, match region marked with >) ---`,
+  );
+  for (let i = startLine; i < endLine; i++) {
+    const isInMatchRegion =
+      i >= bestMatch.startIndex &&
+      i < bestMatch.startIndex + searchLines.length;
+    const searchLineIndex = i - bestMatch.startIndex;
+    const matchesSearch =
+      isInMatchRegion &&
+      searchLineIndex < searchLines.length &&
+      unicodeNormalized(resultLines[i], searchLines[searchLineIndex]);
+
+    const marker = isInMatchRegion ? (matchesSearch ? ">" : "X") : " ";
+    logger.error(
+      `  ${marker} ${String(i + 1).padStart(4)}: ${JSON.stringify(resultLines[i])}`,
     );
-      break;
   }
 
-    const originalChunk = lines
-      .slice(candidate.index, candidate.index + searchLen)
-      .join("\n");
+  // If there's a mismatch, show the specific comparison
+  if (bestMatch.firstMismatchIndex < searchLines.length) {
+    const mismatchFileIndex =
+      bestMatch.startIndex + bestMatch.firstMismatchIndex;
+    if (mismatchFileIndex < resultLines.length) {
+      logger.error(`\n--- FIRST MISMATCH DETAILS ---`);
+      logger.error(
+        `  Search line ${bestMatch.firstMismatchIndex + 1}: ${JSON.stringify(searchLines[bestMatch.firstMismatchIndex])}`,
+      );
+      logger.error(
+        `  File line ${mismatchFileIndex + 1}:   ${JSON.stringify(resultLines[mismatchFileIndex])}`,
+      );
+    }
+  }
 
-    const similarity = getSimilarity(originalChunk, searchChunk);
+  logger.error(`\n=== END MATCH FAILURE ===\n`);
+}
 
-    if (similarity > bestScore) {
-      bestScore = similarity;
-      bestMatchIndex = candidate.index;
+/**
+ * Cascading fuzzy matching: try each pass in order until we find a match
+ * Returns the match index or -1 if no match found, along with any error
+ */
+function cascadingMatch(
+  resultLines: string[],
+  searchLines: string[],
+): { matchIndex: number; error?: string; passName?: string } {
+  const passesToTry = MATCHING_PASSES;
+
+  for (const pass of passesToTry) {
+    const positions = findMatchPositions(
+      resultLines,
+      searchLines,
+      pass.comparator,
+    );
 
-      // Early exit if we found a very good match
-      if (bestScore >= EARLY_STOP_THRESHOLD) {
-        return { bestScore, bestMatchIndex };
+    if (positions.length > 1) {
+      return {
+        matchIndex: -1,
+        error: `Search block matched multiple locations in the target file (ambiguous, detected in ${pass.name} pass)`,
+      };
     }
+
+    if (positions.length === 1) {
+      return { matchIndex: positions[0], passName: pass.name };
     }
   }
 
-  return { bestScore, bestMatchIndex };
+  return {
+    matchIndex: -1,
+    error: "Search block did not match any content in the target file.",
+  };
 }
 
 export function applySearchReplace(
@@ -204,92 +309,39 @@ export function applySearchReplace(
       };
     }
 
-    // If search and replace are identical, it's a no-op and is just treated as a warning
+    // If search and replace are identical, it's either an error or a no-op warning
     if (searchLines.join("\n") === replaceLines.join("\n")) {
       logger.warn("Search and replace blocks are identical");
     }
 
-    let matchIndex = -1;
-
-    const target = searchLines.join("\n");
-    const hay = resultLines.join("\n");
-
-    // Try exact string matching first and detect ambiguity
-    const exactPositions: number[] = [];
-    let fromIndex = 0;
-    while (true) {
-      const found = hay.indexOf(target, fromIndex);
-      if (found === -1) break;
-      exactPositions.push(found);
-      fromIndex = found + 1;
-    }
-
-    if (exactPositions.length > 1) {
-      return {
-        success: false,
-        error:
-          "Search block matched multiple locations in the target file (ambiguous)",
-      };
-    }
-    if (exactPositions.length === 1) {
-      const pos = exactPositions[0];
-      matchIndex = hay.substring(0, pos).split("\n").length - 1;
-    }
-
-    if (matchIndex === -1) {
-      // Lenient fallback: ignore leading indentation and trailing whitespace
-      const normalizeForMatch = (line: string) =>
-        line.replace(/^[\t ]*/, "").replace(/[\t ]+$/, "");
-
-      const normalizedSearch = searchLines.map(normalizeForMatch);
-
-      const candidates: number[] = [];
-      for (let i = 0; i <= resultLines.length - searchLines.length; i++) {
-        let allMatch = true;
-        for (let j = 0; j < searchLines.length; j++) {
-          if (normalizeForMatch(resultLines[i + j]) !== normalizedSearch[j]) {
-            allMatch = false;
-            break;
-          }
+    // Use cascading fuzzy matching to find the match
+    let matchResult = cascadingMatch(resultLines, searchLines);
+
+    // If no match found, try with trimmed leading/trailing empty lines as a fallback
+    if (matchResult.error && !matchResult.error.includes("ambiguous")) {
+      const trimmedSearchLines = trimEmptyLines(searchLines);
+      if (trimmedSearchLines.length !== searchLines.length) {
+        const trimmedResult = cascadingMatch(resultLines, trimmedSearchLines);
+        if (!trimmedResult.error) {
+          matchResult = trimmedResult;
+          searchLines = trimmedSearchLines;
+          logger.debug(
+            "Matched after trimming leading/trailing empty lines from search content",
+          );
         }
-        if (allMatch) {
-          candidates.push(i);
-          if (candidates.length > 1) break; // we only care if >1 for ambiguity
       }
     }
 
-      if (candidates.length > 1) {
+    if (matchResult.error) {
+      // Log detailed diagnostic information for debugging
+      logMatchFailure(resultLines, searchLines, appliedCount);
       return {
         success: false,
-          error:
-            "Search block fuzzy matched multiple locations in the target file (ambiguous)",
+        error: matchResult.error,
       };
     }
 
-      if (candidates.length === 1) {
-        matchIndex = candidates[0];
-      }
-    }
-
-    // If still no match, try fuzzy matching with Levenshtein distance
-    if (matchIndex === -1) {
-      const searchChunk = searchLines.join("\n");
-      const { bestScore, bestMatchIndex } = fastFuzzySearch(
-        resultLines,
-        searchChunk,
-        0,
-        resultLines.length,
-      );
-
-      if (bestScore >= FUZZY_MATCH_THRESHOLD) {
-        matchIndex = bestMatchIndex;
-      } else {
-        return {
-          success: false,
-          error: `Search block did not match any content in the target file. Best fuzzy match had similarity of ${(bestScore * 100).toFixed(1)}% (threshold: ${(FUZZY_MATCH_THRESHOLD * 100).toFixed(1)}%)`,
-        };
-      }
-    }
+    const matchIndex = matchResult.matchIndex;
 
     const matchedLines = resultLines.slice(
       matchIndex,

src/pro/shared/search_replace_markers.ts

+/**
+ * Escapes marker-like lines inside SEARCH/REPLACE content so that
+ * `parseSearchReplaceBlocks` doesn't treat them as block separators.
+ *
+ * The parser treats lines that start with:
+ * - `<<<<<<<` (SEARCH/open marker)
+ * - `=======` (separator)
+ * - `>>>>>>>` (REPLACE/close marker)
+ *
+ * as structural markers unless they are prefixed with `\`.
+ *
+ * The corresponding unescape step lives in the processor (`unescapeMarkers`).
+ */
+export function escapeSearchReplaceMarkers(content: string | null): string {
+  if (!content) return "";
+  return content.replace(
+    /^(\\)?(<<<<<<<|=======|>>>>>>>)/gm,
+    (full, maybeSlash: string | undefined, marker: string) =>
+      maybeSlash ? full : `\\${marker}`,
+  );
+}

src/prompts/local_agent_prompt.ts

@@ -104,6 +104,23 @@ You have tools at your disposal to solve the coding task. Follow these rules reg
 - **Handle errors gracefully**: If a tool fails, explain the issue and suggest alternatives
 </tool_calling_best_practices>
 
+<file_editing_tool_selection>
+You have three tools for editing files. Choose based on the scope of your change:
+
+| Scope | Tool | Examples |
+|-------|------|----------|
+| **Small** (a few lines) | \`search_replace\` or \`edit_file\` | Fix a typo, rename a variable, update a value, change an import |
+| **Medium** (one function or section) | \`edit_file\` | Rewrite a function, add a new component, modify multiple related lines |
+| **Large** (most of the file) | \`write_file\` | Major refactor, rewrite a module, create a new file |
+
+**Tips:**
+- \`edit_file\` supports \`// ... existing code ...\` markers to skip unchanged sections
+- When in doubt, prefer \`search_replace\` for precision or \`write_file\` for simplicity
+
+**Post-edit verification (REQUIRED):**
+After every edit, read the file to verify changes applied correctly. If something went wrong, try a different tool and verify again.
+</file_editing_tool_selection>
+
 <development_workflow>
 1. **Understand:** Think about the user's request and the relevant codebase context. Use \`grep\` and \`code_search\` search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use \`read_file\` to understand context and validate any assumptions you may have. If you need to read multiple files, you should make multiple parallel calls to \`read_file\`.
 2. **Plan:** Build a coherent and grounded (based on the understanding in step 1) plan for how you intend to resolve the user's task. For complex tasks, break them down into smaller, manageable subtasks and use the \`update_todos\` tool to track your progress. Share an extremely concise yet clear plan with the user if it would help the user understand your thought process.