@ottocode/sdk 0.1.236 → 0.1.237

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ottocode/sdk",
-	"version": "0.1.236",
+	"version": "0.1.237",
 	"description": "AI agent SDK for building intelligent assistants - tree-shakable and comprehensive",
 	"author": "nitishxyz",
 	"license": "MIT",

package/src/core/src/tools/builtin/fs/edit-shared.ts

@@ -0,0 +1,83 @@
+export function normalizeLineEndings(text: string): string {
+	return text.replace(/\r\n/g, '\n');
+}
+
+export function detectLineEnding(text: string): '\n' | '\r\n' {
+	return text.includes('\r\n') ? '\r\n' : '\n';
+}
+
+export function convertToLineEnding(
+	text: string,
+	lineEnding: '\n' | '\r\n',
+): string {
+	if (lineEnding === '\n') return text;
+	return text.replace(/\n/g, '\r\n');
+}
+
+function countOccurrences(content: string, search: string): number {
+	if (!search) return 0;
+	let count = 0;
+	let start = 0;
+	while (true) {
+		const index = content.indexOf(search, start);
+		if (index === -1) return count;
+		count += 1;
+		start = index + search.length;
+	}
+}
+
+export function applyStringEdit(
+	content: string,
+	oldString: string,
+	newString: string,
+	replaceAll = false,
+): { content: string; occurrences: number } {
+	if (oldString.length === 0) {
+		throw new Error(
+			'oldString must not be empty. Use write to create files or apply_patch for structural insertions.',
+		);
+	}
+	if (oldString === newString) {
+		throw new Error(
+			'No changes to apply: oldString and newString are identical.',
+		);
+	}
+
+	const lineEnding = detectLineEnding(content);
+	const normalizedOld = convertToLineEnding(
+		normalizeLineEndings(oldString),
+		lineEnding,
+	);
+	const normalizedNew = convertToLineEnding(
+		normalizeLineEndings(newString),
+		lineEnding,
+	);
+
+	const occurrences = countOccurrences(content, normalizedOld);
+	if (occurrences === 0) {
+		throw new Error(
+			'oldString not found in content. Read the file again and copy the exact text, including whitespace.',
+		);
+	}
+	if (occurrences > 1 && !replaceAll) {
+		throw new Error(
+			'Found multiple matches for oldString. Provide more surrounding lines to make it unique or set replaceAll to true.',
+		);
+	}
+
+	if (replaceAll) {
+		return {
+			content: content.split(normalizedOld).join(normalizedNew),
+			occurrences,
+		};
+	}
+
+	const index = content.indexOf(normalizedOld);
+	return {
+		content:
+			content.slice(0, index) +
+			normalizedNew +
+			content.slice(index + normalizedOld.length),
+		occurrences,
+	};
+}

package/src/core/src/tools/builtin/fs/edit.ts

@@ -0,0 +1,129 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import DESCRIPTION from './edit.txt' with { type: 'text' };
+import { buildWriteArtifact, isAbsoluteLike, resolveSafePath } from './util.ts';
+import { applyStringEdit } from './edit-shared.ts';
+import { assertFreshRead, rememberFileWrite } from './read-tracker.ts';
+import { createToolError, type ToolResponse } from '../../error.ts';
+
+export function buildEditTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const edit = tool({
+		description: DESCRIPTION,
+		inputSchema: z.object({
+			path: z
+				.string()
+				.describe(
+					'Relative file path within the project. Absolute paths are not allowed.',
+				),
+			oldString: z.string().describe('Exact text to replace'),
+			newString: z.string().describe('Replacement text'),
+			replaceAll: z
+				.boolean()
+				.optional()
+				.default(false)
+				.describe(
+					'Replace every matching occurrence instead of requiring a unique match',
+				),
+		}),
+		async execute({
+			path,
+			oldString,
+			newString,
+			replaceAll = false,
+		}: {
+			path: string;
+			oldString: string;
+			newString: string;
+			replaceAll?: boolean;
+		}): Promise<
+			ToolResponse<{
+				path: string;
+				occurrences: number;
+				bytes: number;
+				artifact: unknown;
+			}>
+		> {
+			if (!path || path.trim().length === 0) {
+				return createToolError(
+					'Missing required parameter: path',
+					'validation',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: 'Provide a relative file path to edit',
+					},
+				);
+			}
+			if (isAbsoluteLike(path)) {
+				return createToolError(
+					`Refusing to edit outside project root: ${path}`,
+					'permission',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: 'Use a relative path within the project',
+					},
+				);
+			}
+
+			const abs = resolveSafePath(projectRoot, path);
+			try {
+				await assertFreshRead(projectRoot, abs, path);
+				const original = await readFile(abs, 'utf-8');
+				const updated = applyStringEdit(
+					original,
+					oldString,
+					newString,
+					replaceAll,
+				);
+				if (updated.content === original) {
+					return createToolError('No changes applied.', 'validation', {
+						suggestion:
+							'Adjust oldString/newString so the file content actually changes',
+					});
+				}
+
+				await writeFile(abs, updated.content, 'utf-8');
+				await rememberFileWrite(projectRoot, abs);
+				const artifact = await buildWriteArtifact(
+					path,
+					true,
+					original,
+					updated.content,
+				);
+				return {
+					ok: true,
+					path,
+					occurrences: updated.occurrences,
+					bytes: updated.content.length,
+					artifact,
+				};
+			} catch (error: unknown) {
+				const isEnoent =
+					error &&
+					typeof error === 'object' &&
+					'code' in error &&
+					error.code === 'ENOENT';
+				return createToolError(
+					isEnoent
+						? `File not found: ${path}`
+						: `Failed to edit file: ${error instanceof Error ? error.message : String(error)}`,
+					isEnoent ? 'not_found' : 'execution',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: isEnoent
+							? 'Use read or ls to confirm the file path first'
+							: undefined,
+					},
+				);
+			}
+		},
+	});
+
+	return { name: 'edit', tool: edit };
+}

package/src/core/src/tools/builtin/fs/edit.txt

@@ -0,0 +1,9 @@
+Replace an exact text block in an existing file.
+
+Use this for targeted edits instead of apply_patch whenever possible.
+
+Rules:
+- You must read the file first in the current session before editing it.
+- `oldString` must match the file exactly, including whitespace.
+- If `oldString` appears multiple times, provide more context or set `replaceAll: true`.
+- Use `write` for new files and `apply_patch` for structural multi-file diffs.

package/src/core/src/tools/builtin/fs/index.ts

@@ -1,5 +1,7 @@
 import type { Tool } from 'ai';
+import { buildEditTool } from './edit.ts';
 import { buildReadTool } from './read.ts';
+import { buildMultiEditTool } from './multiedit.ts';
 import { buildWriteTool } from './write.ts';
 import { buildLsTool } from './ls.ts';
 import { buildTreeTool } from './tree.ts';
@@ -11,6 +13,8 @@ export function buildFsTools(
 ): Array<{ name: string; tool: Tool }> {
 	const out: Array<{ name: string; tool: Tool }> = [];
 	out.push(buildReadTool(projectRoot));
+	out.push(buildEditTool(projectRoot));
+	out.push(buildMultiEditTool(projectRoot));
 	out.push(buildWriteTool(projectRoot));
 	out.push(buildLsTool(projectRoot));
 	out.push(buildTreeTool(projectRoot));

package/src/core/src/tools/builtin/fs/multiedit.ts

@@ -0,0 +1,137 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { tool, type Tool } from 'ai';
+import { z } from 'zod/v3';
+import DESCRIPTION from './multiedit.txt' with { type: 'text' };
+import { buildWriteArtifact, isAbsoluteLike, resolveSafePath } from './util.ts';
+import { applyStringEdit } from './edit-shared.ts';
+import { assertFreshRead, rememberFileWrite } from './read-tracker.ts';
+import { createToolError, type ToolResponse } from '../../error.ts';
+
+const multiEditSchema = z.object({
+	path: z
+		.string()
+		.describe(
+			'Relative file path within the project. Absolute paths are not allowed.',
+		),
+	edits: z
+		.array(
+			z.object({
+				oldString: z.string().describe('Exact text to replace'),
+				newString: z.string().describe('Replacement text'),
+				replaceAll: z
+					.boolean()
+					.optional()
+					.default(false)
+					.describe('Replace every matching occurrence for this edit'),
+			}),
+		)
+		.min(1)
+		.describe('Edits to apply sequentially to the same file'),
+});
+
+export function buildMultiEditTool(projectRoot: string): {
+	name: string;
+	tool: Tool;
+} {
+	const multiedit = tool({
+		description: DESCRIPTION,
+		inputSchema: multiEditSchema,
+		async execute({ path, edits }: z.infer<typeof multiEditSchema>): Promise<
+			ToolResponse<{
+				path: string;
+				editsApplied: number;
+				bytes: number;
+				artifact: unknown;
+			}>
+		> {
+			if (!path || path.trim().length === 0) {
+				return createToolError(
+					'Missing required parameter: path',
+					'validation',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: 'Provide a relative file path to edit',
+					},
+				);
+			}
+			if (isAbsoluteLike(path)) {
+				return createToolError(
+					`Refusing to edit outside project root: ${path}`,
+					'permission',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: 'Use a relative path within the project',
+					},
+				);
+			}
+
+			const abs = resolveSafePath(projectRoot, path);
+			try {
+				await assertFreshRead(projectRoot, abs, path);
+				const original = await readFile(abs, 'utf-8');
+				let nextContent = original;
+				for (let i = 0; i < edits.length; i++) {
+					const edit = edits[i];
+					try {
+						nextContent = applyStringEdit(
+							nextContent,
+							edit.oldString,
+							edit.newString,
+							edit.replaceAll,
+						).content;
+					} catch (error: unknown) {
+						throw new Error(
+							`Edit ${i + 1} failed: ${error instanceof Error ? error.message : String(error)}`,
+						);
+					}
+				}
+
+				if (nextContent === original) {
+					return createToolError('No changes applied.', 'validation', {
+						suggestion:
+							'Adjust your edits so the file content actually changes',
+					});
+				}
+
+				await writeFile(abs, nextContent, 'utf-8');
+				await rememberFileWrite(projectRoot, abs);
+				const artifact = await buildWriteArtifact(
+					path,
+					true,
+					original,
+					nextContent,
+				);
+				return {
+					ok: true,
+					path,
+					editsApplied: edits.length,
+					bytes: nextContent.length,
+					artifact,
+				};
+			} catch (error: unknown) {
+				const isEnoent =
+					error &&
+					typeof error === 'object' &&
+					'code' in error &&
+					error.code === 'ENOENT';
+				return createToolError(
+					isEnoent
+						? `File not found: ${path}`
+						: `Failed to edit file: ${error instanceof Error ? error.message : String(error)}`,
+					isEnoent ? 'not_found' : 'execution',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: isEnoent
+							? 'Use read or ls to confirm the file path first'
+							: undefined,
+					},
+				);
+			}
+		},
+	});
+
+	return { name: 'multiedit', tool: multiedit };
+}

package/src/core/src/tools/builtin/fs/multiedit.txt

@@ -0,0 +1,9 @@
+Apply multiple exact text replacements to a single existing file atomically.
+
+Use this when you need several edits in one file.
+
+Rules:
+- Read the file first before editing.
+- Each edit uses exact `oldString` -> `newString` replacement.
+- All edits must succeed or none are written.
+- Use `replaceAll: true` only when every occurrence should change.

package/src/core/src/tools/builtin/fs/read-tracker.ts

@@ -0,0 +1,72 @@
+import { stat } from 'node:fs/promises';
+import { resolve as resolvePath } from 'node:path';
+
+type FileStamp = {
+	readAt: number;
+	mtimeMs?: number;
+	ctimeMs?: number;
+	size?: number;
+};
+
+const readState = new Map<string, Map<string, FileStamp>>();
+
+function getProjectState(projectRoot: string): Map<string, FileStamp> {
+	const key = resolvePath(projectRoot);
+	let state = readState.get(key);
+	if (!state) {
+		state = new Map<string, FileStamp>();
+		readState.set(key, state);
+	}
+	return state;
+}
+
+async function captureFileStamp(absPath: string): Promise<FileStamp> {
+	const stats = await stat(absPath);
+	return {
+		readAt: Date.now(),
+		mtimeMs: Number.isFinite(stats.mtimeMs) ? stats.mtimeMs : undefined,
+		ctimeMs: Number.isFinite(stats.ctimeMs) ? stats.ctimeMs : undefined,
+		size: typeof stats.size === 'number' ? stats.size : undefined,
+	};
+}
+
+export async function rememberFileRead(
+	projectRoot: string,
+	absPath: string,
+): Promise<void> {
+	const state = getProjectState(projectRoot);
+	state.set(absPath, await captureFileStamp(absPath));
+}
+
+export async function rememberFileWrite(
+	projectRoot: string,
+	absPath: string,
+): Promise<void> {
+	const state = getProjectState(projectRoot);
+	state.set(absPath, await captureFileStamp(absPath));
+}
+
+export async function assertFreshRead(
+	projectRoot: string,
+	absPath: string,
+	displayPath: string,
+): Promise<void> {
+	const state = getProjectState(projectRoot);
+	const previous = state.get(absPath);
+	if (!previous) {
+		throw new Error(
+			`You must read file ${displayPath} before editing it. Use the read tool first.`,
+		);
+	}
+
+	const current = await captureFileStamp(absPath);
+	const changed =
+		current.mtimeMs !== previous.mtimeMs ||
+		current.ctimeMs !== previous.ctimeMs ||
+		current.size !== previous.size;
+	if (!changed) return;
+
+	throw new Error(
+		`File ${displayPath} has changed since it was last read. Read it again before editing.`,
+	);
+}

package/src/core/src/tools/builtin/fs/read.ts

@@ -2,6 +2,7 @@ import { tool, type Tool } from 'ai';
 import { z } from 'zod/v3';
 import { readFile } from 'node:fs/promises';
 import { expandTilde, isAbsoluteLike, resolveSafePath } from './util.ts';
+import { rememberFileRead } from './read-tracker.ts';
 import DESCRIPTION from './read.txt' with { type: 'text' };
 import { createToolError, type ToolResponse } from '../../error.ts';
 
@@ -108,6 +109,7 @@ export function buildReadTool(projectRoot: string): {
 			try {
 				let content = await readFile(abs, 'utf-8');
 				const indent = detectIndentation(content);
+				await rememberFileRead(projectRoot, abs);
 
 				if (startLine !== undefined && endLine !== undefined) {
 					const lines = content.split('\n');

package/src/core/src/tools/builtin/fs/write.ts

@@ -8,6 +8,7 @@ import {
 	expandTilde,
 	isAbsoluteLike,
 } from './util.ts';
+import { rememberFileWrite } from './read-tracker.ts';
 import DESCRIPTION from './write.txt' with { type: 'text' };
 import { createToolError, type ToolResponse } from '../../error.ts';
 
@@ -79,6 +80,7 @@ export function buildWriteTool(projectRoot: string): {
 					existed = true;
 				} catch {}
 				await writeFile(abs, content);
+				await rememberFileWrite(projectRoot, abs);
 				const artifact = await buildWriteArtifact(
 					req,
 					existed,

package/src/core/src/tools/builtin/fs/write.txt

@@ -6,6 +6,6 @@
 Usage tips:
 - Use for creating NEW files
 - Use when replacing >70% of a file's content (almost complete rewrite)
-- NEVER use for partial/targeted edits - use apply_patch instead
+- NEVER use for partial/targeted edits - use edit/multiedit first, or apply_patch for structural changes
 - Using write for partial edits wastes output tokens and risks hallucinating unchanged parts
 - Prefer idempotent writes by providing the full intended content when you do use write

package/src/prompts/src/agents/build.txt

@@ -12,6 +12,13 @@ You help with coding and build tasks.
 - Use `terminal(operation: "write", input: "\u0003")` or `terminal(operation: "interrupt")` to stop a process before resorting to `kill`.
 - Summarize active terminals (purpose, key command, port) in your updates so collaborators know what's running.
 
+## Preferred Editing Order
+
+- Use `edit` for one exact replacement in an existing file.
+- Use `multiedit` for several exact replacements in the same file.
+- Use `apply_patch` for structural or multi-file changes, file add/delete/rename, or edits that are awkward as exact replacements.
+- Use `write` for new files or near-total rewrites.
+
 ## apply_patch — Mandatory Rules
 
 These rules apply EVERY time you use the `apply_patch` tool. Violations cause patch failures.
@@ -211,7 +218,7 @@ Key points:
 - Wastes output tokens and risks hallucinating unchanged parts
 
 ## Never
-- Use `write` for partial file edits (use `apply_patch` instead)
+- Use `write` for partial file edits (use `edit`/`multiedit` first, or `apply_patch` for structural diffs)
 - Make multiple separate `apply_patch` calls for the same file (use multiple hunks with @@ headers instead)
 - Assume file content remains unchanged between operations
-- Use `bash` with `sed`/`awk` for programmatic file editing (use `apply_patch` instead)
+- Use `bash` with `sed`/`awk` for programmatic file editing (use `edit`, `multiedit`, or `apply_patch` instead)

package/src/prompts/src/base.txt

@@ -21,10 +21,13 @@ You MUST call the `finish` tool at the end of every response to signal completio
 **IMPORTANT**: Do NOT call `finish` before streaming your response. Always stream your message first, then call `finish`. If you forget to call `finish`, the system will hang and not complete properly.
 
 File Editing Best Practices:
-- ALWAYS read a file immediately before using apply_patch — never patch from memory
-- The `read` tool returns an `indentation` field (e.g., "tabs", "2 spaces") — use it to match the file's indentation style in your patch
-- Copy context lines CHARACTER-FOR-CHARACTER from the read output — never reconstruct from memory
-- When making multiple edits to the same file, use multiple `@@` hunks in a single `apply_patch` call
-- Never assume file content remains unchanged between separate apply_patch operations
-- If a patch fails, read the file AGAIN and copy the exact lines
-- If `apply_patch` fails repeatedly on the same file, fall back to `write` only when a full-file rewrite is appropriate
+- Prefer `edit` for one exact replacement in an existing file
+- Prefer `multiedit` for several exact replacements in the same file
+- Use `apply_patch` for structural diffs, file add/delete/rename, or changes that are awkward as exact replacements
+- ALWAYS read a file immediately before using `edit`, `multiedit`, or `apply_patch`
+- For `edit` / `multiedit`, copy the exact text including whitespace from the latest `read` output
+- For `apply_patch`, use the `indentation` field from `read` and copy context lines CHARACTER-FOR-CHARACTER
+- When making multiple edits to the same file with `apply_patch`, use multiple `@@` hunks in a single call
+- Never assume file content remains unchanged between separate edit operations
+- If an edit tool fails, read the file AGAIN and copy the exact lines
+- If `apply_patch` fails repeatedly on the same file, prefer `edit` / `multiedit` when possible and fall back to `write` only for a full-file rewrite

package/src/prompts/src/providers/default.txt

@@ -20,7 +20,9 @@ You have access to a rich set of specialized tools optimized for coding tasks:
 **File Reading & Editing**:
 - `read`: Read file contents (supports line ranges)
 - `write`: Write complete file contents
-- `apply_patch`: Apply unified diff patches (RECOMMENDED for targeted edits)
+- `edit`: Exact text replacement in one file
+- `multiedit`: Multiple exact replacements in one file
+- `apply_patch`: Apply diff/enveloped patches (best for structural or multi-file changes)
 
 **Version Control**:
 - `git_status`, `git_diff`
@@ -34,12 +36,13 @@ You have access to a rich set of specialized tools optimized for coding tasks:
 ### Tool Usage Best Practices:
 
 1. **Batch Independent Operations**: Make all independent tool calls in one turn
-2. **File Editing**: Prefer `apply_patch` for targeted edits to avoid rewriting entire files
-3. **Combine Edits**: When editing the same file multiple times, use multiple `@@` hunks in ONE `apply_patch` call
-4. **Search First**: Use `glob` to find files before reading them
-5. **Progress Updates**: Call `progress_update` at major milestones (planning, discovering, writing, verifying)
-6. **Plan Tracking**: Use `update_todos` to show task breakdown and progress
-7. **Finish Required**: Always call `finish` tool when complete
+2. **File Editing**: Prefer `edit` for one targeted replacement and `multiedit` for several exact replacements in the same file
+3. **Structural Changes**: Use `apply_patch` for multi-file diffs, file add/delete/rename, or edits that are awkward as exact replacements
+4. **Patch Consolidation**: When you do use `apply_patch` multiple times on the same file, use multiple `@@` hunks in ONE `apply_patch` call
+5. **Search First**: Use `glob` to find files before reading them
+6. **Progress Updates**: Call `progress_update` at major milestones (planning, discovering, writing, verifying)
+7. **Plan Tracking**: Use `update_todos` to show task breakdown and progress
+8. **Finish Required**: Always call `finish` tool when complete
 
 ### Tool Failure Handling
 
@@ -49,10 +52,18 @@ You have access to a rich set of specialized tools optimized for coding tasks:
 
 ## File Editing Best Practices
 
-**Using the `apply_patch` Tool** (Recommended):
+**Using the `edit` / `multiedit` Tools** (Recommended):
+- Use `edit` for one exact replacement in an existing file
+- Use `multiedit` for several exact replacements in the same file
+- These tools are the default choice for targeted edits because they avoid patch-formatting mistakes
+- Read the file first, then copy the exact text including whitespace
+- If the text appears multiple times, include more surrounding context or use `replaceAll: true`
+- Use `apply_patch` only when the change is structural, spans multiple files, or cannot be expressed as an exact replacement
+
+**Using the `apply_patch` Tool** (Structural / Advanced):
 - **CRITICAL**: ALWAYS read the target file immediately before creating a patch - never patch from memory
 - The `read` tool returns an `indentation` field (e.g., "tabs", "2 spaces") — use it to match the file's indent style in your patch
-- Primary choice for targeted file edits - avoids rewriting entire files
+- Use when the change is structural, multi-file, or awkward as an exact replacement
 - Preferred format is the enveloped patch (`*** Begin Patch` ...); standard unified diffs (`---/+++`) are also accepted and auto-converted if provided
 - Only requires the specific lines you want to change
 - Format: `*** Begin Patch` ... `*** Update File: path` ... `-old` / `+new` ... `*** End Patch`
@@ -63,8 +74,8 @@ You have access to a rich set of specialized tools optimized for coding tasks:
 - If patch fails, it means the file content doesn't match - read it again and retry
 - If you suspect parts of the patch might be stale, set `allowRejects: true` so the tool applies what it can and reports the skipped hunks with reasons
 - The tool quietly skips removal lines that are already gone and additions that already exist, so you don't need to resend the same change
-- **Best for**: Small, surgical edits to code files (< 50 line changes per file)
-- **Struggles with**: Large restructures (> 50 lines), major section reorganizations
+- **Best for**: Structural diffs, file add/delete/rename, or edits that don't fit exact string replacement cleanly
+- **Struggles with**: Small targeted edits where `edit` or `multiedit` would be simpler and less error-prone
 
 **Patch Format Reminder**:
 ```
@@ -83,10 +94,10 @@ You have access to a rich set of specialized tools optimized for coding tasks:
 - Wastes output tokens and risks hallucinating unchanged parts
 
 **Never**:
-- Use `write` for partial file edits (use `apply_patch` instead)
+- Use `write` for partial file edits (use `edit`/`multiedit` first, or `apply_patch` for structural diffs)
 - Make multiple separate `apply_patch` calls for the same file (use multiple hunks with @@ headers instead)
 - Assume file content remains unchanged between operations
-- Use `bash` with `sed`/`awk` for programmatic file editing (use `apply_patch` instead)
+- Use `bash` with `sed`/`awk` for programmatic file editing (use `edit`, `multiedit`, or `apply_patch` instead)
 
 ## Direct File References
 
@@ -264,7 +275,7 @@ You MUST adhere to the following criteria when solving queries:
 - Working on the repo(s) in the current environment is allowed, even if they are proprietary.
 - Analyzing code for vulnerabilities is allowed.
 - Showing user code and tool call details is allowed.
-- Use the `apply_patch` tool to edit files (NEVER try `applypatch` or `apply-patch`, only `apply_patch`): {"command":["apply_patch","*** Begin Patch\\n*** Update File: path/to/file.py\\n def example():\\n- pass\\n+ return 123\\n*** End Patch"]}
+- Prefer `edit` and `multiedit` for targeted changes in existing files. Use `apply_patch` for structural diffs or file add/delete/rename. When using patches, NEVER try `applypatch` or `apply-patch`, only `apply_patch`.
 
 If completing the user's task requires writing or modifying files, your code and final answer should follow these coding guidelines, though user instructions (i.e. AGENTS.md) may override these guidelines: