Apply a patch to modify one or more files using the enveloped patch format.

**RECOMMENDED: Use apply_patch for targeted file edits to avoid rewriting entire files and wasting tokens.**

**FUZZY MATCHING**: By default, fuzzy matching is enabled to handle whitespace differences (tabs vs spaces).
Exact matching is tried first, then normalized matching if exact fails. Disable with `fuzzyMatch: false` if needed.

Use `apply_patch` only when:
- You want to make targeted edits to specific lines (primary use case)
- You want to make multiple related changes across different files in a single operation
- You need to add/delete entire files along with modifications
- You have JUST read the file immediately before (within the same response) and are confident the content hasn't changed

**CRITICAL - ALWAYS READ BEFORE PATCHING**: You MUST read the file content immediately before creating a patch.
Never rely on memory or previous reads. Even with fuzzy matching enabled (tolerates tabs vs spaces),
If the file content has changed significantly since you last read it, the patch may still fail.

**Alternative: Use the `edit` tool if you need fuzzy matching or structured operations.**

## Patch Format

All patches must be wrapped in markers and use explicit file directives:

```
*** Begin Patch
*** Add File: path/to/file.txt
+line 1
+line 2
*** Update File: path/to/other.txt
-old line
+new line
*** Delete File: path/to/delete.txt
*** End Patch
```

## File Operations

### Add a new file:
```
*** Begin Patch
*** Add File: src/hello.ts
+export function hello() {
+  console.log("Hello!");
+}
*** End Patch
```

### Update an existing file (simple replacement):
```
*** Begin Patch
*** Update File: src/config.ts
-const PORT = 3000;
+const PORT = 8080;
*** End Patch
```

**CRITICAL**: The `-` lines must match EXACTLY what's in the file, character-for-character. If you're not 100% certain, use the `edit` tool instead.

### Update with context (recommended for precision):
```
*** Begin Patch
*** Update File: src/app.ts
@@ function main()
 function main() {
-  console.log("old");
+  console.log("new");
 }
*** End Patch
```

**IMPORTANT**: 
- The `@@` line is an OPTIONAL hint to help locate the change - it's a comment, not parsed as context
- REQUIRED: Actual context lines (starting with space ` `) that match the file exactly
- The context lines with space prefix are what the tool uses to find the location
- The `@@` line just helps humans/AI understand what section you're editing


### Update multiple locations in the same file:
```
*** Begin Patch
*** Update File: src/app.ts
@@ first section - near line 10
 function init() {
-  const port = 3000;
+  const port = 8080;
   return port;
 }
@@ second section - near line 25
 function start() {
-  console.log("Starting...");
+  console.log("Server starting...");
   init();
 }
*** End Patch
```

**IMPORTANT**: Use separate `@@` headers for each non-consecutive change location. This allows multiple edits to the same file in one patch, saving tokens and reducing tool calls.

### Delete a file:
```
*** Begin Patch
*** Delete File: old/unused.ts
*** End Patch
```

### Multiple operations in one patch:
```
*** Begin Patch
*** Add File: new.txt
+New content
*** Update File: existing.txt
-old
+new
*** Delete File: obsolete.txt
*** End Patch
```

## Line Prefixes

- Lines starting with `+` are added
- Lines starting with `-` are removed  
- Lines starting with ` ` (space) are context (kept unchanged)
- Lines starting with `@@` are optional hints/comments (not parsed as context)

## Common Errors

**"Failed to find expected lines"**: The file content doesn't match your patch. Common causes:
- Missing context lines (lines with space prefix)
- Using `@@` line as context instead of real context lines
- The file content has changed since you read it
- Whitespace/indentation mismatch

**Solution**: Always read the file immediately before patching and include actual context lines with space prefix.

## Important Notes

- **Patches are fragile**: Any mismatch in whitespace, indentation, or content will cause failure
- **Use `edit` for reliability**: The `edit` tool can make targeted changes without requiring exact matches
- All file paths are relative to the project root
- The patch format does NOT support standard unified diff format (no `---`/`+++` headers)
- Always wrap patches with `*** Begin Patch` and `*** End Patch`
