@ottocode/sdk 0.1.235 → 0.1.237

package/src/core/src/utils/logger.ts

@@ -1,9 +1,22 @@
 import { appendFileSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { isDebugEnabled, isTraceEnabled } from './debug.ts';
+import { isDebugEnabled, isTraceEnabled, getDebugScopes } from './debug.ts';
+import {
+	getGlobalDebugLogPath,
+	getSessionDebugDetailsLogPath,
+	getSessionDebugLogPath,
+} from '../../../config/src/paths.ts';
 
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 
+const ANSI_RESET = '\x1b[0m';
+const ANSI_DIM = '\x1b[2m';
+const ANSI_CYAN = '\x1b[36m';
+const ANSI_BLUE = '\x1b[34m';
+const ANSI_GREEN = '\x1b[32m';
+const ANSI_YELLOW = '\x1b[33m';
+const ANSI_RED = '\x1b[31m';
+
 function safeHasMeta(
 	meta?: Record<string, unknown>,
 ): meta is Record<string, unknown> {
@@ -11,18 +24,90 @@ function safeHasMeta(
 }
 
 function getDebugLogFilePath(): string | undefined {
-	return undefined;
+	if (!isDebugEnabled()) return undefined;
+	return getGlobalDebugLogPath();
+}
+
+function getSessionLogFilePath(
+	meta?: Record<string, unknown>,
+): string | undefined {
+	if (!isDebugEnabled()) return undefined;
+	if (meta?.debugDetail === true) return undefined;
+	const sessionId = meta?.sessionId;
+	if (typeof sessionId !== 'string' || !sessionId.trim()) return undefined;
+	return getSessionDebugLogPath(sessionId);
+}
+
+function getSessionDetailsLogFilePath(
+	meta?: Record<string, unknown>,
+): string | undefined {
+	if (!isDebugEnabled()) return undefined;
+	const sessionId = meta?.sessionId;
+	if (typeof sessionId !== 'string' || !sessionId.trim()) return undefined;
+	return getSessionDebugDetailsLogPath(sessionId);
+}
+
+function shouldWriteDebugLog(message: string): boolean {
+	if (!isDebugEnabled()) return false;
+	const scopes = getDebugScopes();
+	if (!scopes.length) return true;
+	const match = message.match(/^\[([^\]]+)\]/);
+	if (!match?.[1]) return true;
+	return scopes.includes(match[1]);
 }
 
 function serializeLogMeta(meta?: Record<string, unknown>): string {
 	if (!safeHasMeta(meta)) return '';
 	try {
-		return ` ${JSON.stringify(meta)}`;
+		const sanitized = { ...meta };
+		delete sanitized.debugDetail;
+		return Object.keys(sanitized).length ? ` ${JSON.stringify(sanitized)}` : '';
 	} catch {
 		return ' [unserializable-meta]';
 	}
 }
 
+function colorizeLine(line: string, level: LogLevel): string {
+	const levelColor =
+		level === 'debug'
+			? ANSI_CYAN
+			: level === 'info'
+				? ANSI_BLUE
+				: level === 'warn'
+					? ANSI_YELLOW
+					: ANSI_RED;
+	const scopeMatch = line.match(
+		/\[(debug|info|warn|error|timing)\]\s+\[([^\]]+)\]/i,
+	);
+	if (!scopeMatch) {
+		return `${levelColor}${line}${ANSI_RESET}`;
+	}
+	const rest = line.slice(24);
+	return `${ANSI_DIM}${line.slice(0, 24)}${ANSI_RESET}${rest
+		.replace(scopeMatch[1], `${levelColor}${scopeMatch[1]}${ANSI_RESET}`)
+		.replace(
+			`[${scopeMatch[2]}]`,
+			`${ANSI_GREEN}[${scopeMatch[2]}]${ANSI_RESET}`,
+		)}`;
+}
+
+function printLine(
+	level: LogLevel,
+	line: string,
+	meta?: Record<string, unknown>,
+) {
+	const colored = colorizeLine(line, level);
+	if (safeHasMeta(meta)) {
+		if (level === 'warn') console.warn(colored, meta);
+		else if (level === 'error') console.error(colored, meta);
+		else console.log(colored, meta);
+		return;
+	}
+	if (level === 'warn') console.warn(colored);
+	else if (level === 'error') console.error(colored);
+	else console.log(colored);
+}
+
 function writeLogLine(line: string, meta?: Record<string, unknown>) {
 	const suffix = serializeLogMeta(meta);
 	const fullLine = `${new Date().toISOString()} ${line}${suffix}`;
@@ -37,32 +122,44 @@ function writeLogLine(line: string, meta?: Record<string, unknown>) {
 		}
 	}
 
+	const sessionLogFile = getSessionLogFilePath(meta);
+	if (sessionLogFile) {
+		try {
+			mkdirSync(dirname(sessionLogFile), { recursive: true });
+			appendFileSync(sessionLogFile, `${fullLine}\n`, 'utf-8');
+		} catch {
+			// ignore file logging errors
+		}
+	}
+
+	const sessionDetailsLogFile = getSessionDetailsLogFilePath(meta);
+	if (sessionDetailsLogFile) {
+		try {
+			mkdirSync(dirname(sessionDetailsLogFile), { recursive: true });
+			appendFileSync(sessionDetailsLogFile, `${fullLine}\n`, 'utf-8');
+		} catch {
+			// ignore file logging errors
+		}
+	}
+
 	return fullLine;
 }
 
 export function debug(message: string, meta?: Record<string, unknown>): void {
-	if (!isDebugEnabled()) return;
+	if (!shouldWriteDebugLog(message)) return;
 	try {
 		const line = writeLogLine(`[debug] ${message}`, meta);
-		if (safeHasMeta(meta)) {
-			console.log(line, meta);
-		} else {
-			console.log(line);
-		}
+		printLine('debug', line, meta);
 	} catch {
 		// ignore logging errors
 	}
 }
 
 export function info(message: string, meta?: Record<string, unknown>): void {
-	if (!isDebugEnabled() && !isTraceEnabled()) return;
+	if (!shouldWriteDebugLog(message) && !isTraceEnabled()) return;
 	try {
 		const line = writeLogLine(`[info] ${message}`, meta);
-		if (safeHasMeta(meta)) {
-			console.log(line, meta);
-		} else {
-			console.log(line);
-		}
+		printLine('info', line, meta);
 	} catch {
 		// ignore logging errors
 	}
@@ -71,11 +168,7 @@ export function info(message: string, meta?: Record<string, unknown>): void {
 export function warn(message: string, meta?: Record<string, unknown>): void {
 	try {
 		const line = writeLogLine(`[warn] ${message}`, meta);
-		if (safeHasMeta(meta)) {
-			console.warn(line, meta);
-		} else {
-			console.warn(line);
-		}
+		printLine('warn', line, meta);
 	} catch {
 		// ignore logging errors
 	}
@@ -127,10 +220,10 @@ export function error(
 
 		if (safeHasMeta(logMeta)) {
 			const line = writeLogLine(`[error] ${message}`, logMeta);
-			console.error(line, logMeta);
+			printLine('error', line, logMeta);
 		} else {
 			const line = writeLogLine(`[error] ${message}`);
-			console.error(line);
+			printLine('error', line);
 		}
 	} catch (logErr) {
 		try {
@@ -177,11 +270,7 @@ export function time(label: string): Timer {
 					`[timing] ${label} ${duration.toFixed(1)}ms`,
 					meta,
 				);
-				if (safeHasMeta(meta)) {
-					console.log(base, meta);
-				} else {
-					console.log(base);
-				}
+				printLine('info', base, meta);
 			} catch {
 				// ignore timing log errors
 			}

package/src/index.ts

@@ -177,6 +177,12 @@ export {
 	getGlobalAgentsDir,
 	getGlobalToolsDir,
 	getGlobalCommandsDir,
+	getGlobalDebugDir,
+	getGlobalDebugLogPath,
+	getGlobalDebugSessionsDir,
+	getSessionDebugLogPath,
+	getSessionDebugDetailsLogPath,
+	getSessionSystemPromptPath,
 	getSecureAuthPath,
 	getSecureBaseDir,
 	getSecureOAuthDir,
@@ -187,12 +193,14 @@ export {
 	isAuthorized,
 	ensureEnv,
 	writeDefaults as setConfig,
+	readDebugConfig,
+	writeDebugConfig,
 	writeAuth,
 	removeAuth as removeConfig,
 	getOnboardingComplete,
 	setOnboardingComplete,
 } from './config/src/manager.ts';
-export type { Scope } from './config/src/manager.ts';
+export type { Scope, DebugConfig } from './config/src/manager.ts';
 
 // =======================
 // Prompts (from internal prompts module)

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/debug.ts

@@ -3,13 +3,6 @@ export function isDebugEnabled(flag?: string): boolean {
 	return false;
 }
 
-function nowMs(): number {
-	const perf = (globalThis as { performance?: { now?: () => number } })
-		.performance;
-	if (perf && typeof perf.now === 'function') return perf.now();
-	return Date.now();
-}
-
 type Timer = { end(meta?: Record<string, unknown>): void };
 
 export function time(label: string): Timer {

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:
 

package/src/prompts/src/providers/glm.txt

@@ -36,7 +36,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`
@@ -50,12 +52,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
 
@@ -65,10 +68,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`
@@ -79,8 +90,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 — Complete Reference**:
 
@@ -172,10 +183,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
 
@@ -231,7 +242,7 @@ read package.json
 
 You are a coding agent. Keep going until the query is completely resolved before yielding back to the user. Only terminate your turn when you are sure that the problem is solved. Autonomously resolve the query using the tools available to you. Do NOT guess or make up an answer.
 
-- Use the `apply_patch` tool to edit files (NEVER try `applypatch` or `apply-patch`, only `apply_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`.
 - Fix the problem at the root cause rather than applying surface-level patches
 - Avoid unneeded complexity in your solution
 - Keep changes consistent with the style of the existing codebase

package/src/prompts/src/providers/google.txt

@@ -89,13 +89,13 @@ Examples of operations to batch:
 When requested to perform tasks like fixing bugs, adding features, refactoring, or explaining code, follow this sequence:
 1. **Understand:** Think about the user's request and the relevant codebase context. Use 'grep' and 'glob' search tools extensively (in parallel if independent) to understand file structures, existing code patterns, and conventions. Use 'read' to understand context and validate any assumptions you may have.
 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. Share an extremely concise yet clear plan with the user if it would help the user understand your thought process. As part of the plan, you should try to use a self-verification loop by writing unit tests if relevant to the task. Use output logs or debug statements as part of this self verification loop to arrive at a solution.
-3. **Implement:** Use the available tools (e.g., 'apply_patch', 'write', 'bash' ...) to act on the plan, strictly adhering to the project's established conventions (detailed under 'Core Mandates').
+3. **Implement:** Use the available tools (e.g., 'edit', 'multiedit', 'apply_patch', 'write', 'bash' ...) to act on the plan, strictly adhering to the project's established conventions (detailed under 'Core Mandates').
 4. **Verify (Tests):** If applicable and feasible, verify the changes using the project's testing procedures. Identify the correct test commands and frameworks by examining 'README' files, build/package configuration (e.g., 'package.json'), or existing test execution patterns. NEVER assume standard test commands.
 5. **Verify (Standards):** VERY IMPORTANT: After making code changes, execute the project-specific build, linting and type-checking commands (e.g., 'tsc', 'npm run lint', 'ruff check .') that you have identified for this project (or obtained from the user). This ensures code quality and adherence to standards. If unsure about these commands, you can ask the user if they'd like you to run them and if so how to.
 
 ## New Applications
 
-**Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype. Utilize all tools at your disposal to implement the application. Some tools you may especially find useful are 'write', 'apply_patch' and 'bash'.
+**Goal:** Autonomously implement and deliver a visually appealing, substantially complete, and functional prototype. Utilize all tools at your disposal to implement the application. Some tools you may especially find useful are 'edit', 'multiedit', 'write', 'apply_patch' and 'bash'.
 
 1. **Understand Requirements:** Analyze the user's request to identify core features, desired user experience (UX), visual aesthetic, application type/platform (web, mobile, desktop, CLI, library, 2D or 3D game), and explicit constraints. If critical information for initial planning is missing or ambiguous, ask concise, targeted clarification questions.
 2. **Propose Plan:** Formulate an internal development plan. Present a clear, concise, high-level summary to the user. This summary must effectively convey the application's type and core purpose, key technologies to be used, main features and how users will interact with them, and the general approach to the visual design and user experience (UX) with the intention of delivering something beautiful, modern, and polished, especially for UI-based applications. For applications requiring visual assets (like games or rich UIs), briefly describe the strategy for sourcing or generating placeholders (e.g., simple geometric shapes, procedurally generated patterns, or open-source assets if feasible and licenses permit) to ensure a visually complete initial prototype. Ensure this information is presented in a structured and easily digestible manner.
@@ -189,7 +189,7 @@ Here's the plan:
 Should I proceed?
 user: Yes
 model:
-[tool_call: write or apply_patch to apply the refactoring to 'src/auth.py']
+[tool_call: edit, multiedit, write, or apply_patch to apply the refactoring to 'src/auth.py']
 Refactoring complete. Running verification...
 [tool_call: bash for 'ruff check src/auth.py && pytest']
 (After verification passes)

package/src/prompts/src/providers/moonshot.txt

@@ -36,7 +36,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`
@@ -50,12 +52,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
 
@@ -65,10 +68,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`
@@ -79,8 +90,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 — Complete Reference**:
 
@@ -172,10 +183,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
 
@@ -231,7 +242,7 @@ read package.json
 
 You are a coding agent. Keep going until the query is completely resolved before yielding back to the user. Only terminate your turn when you are sure that the problem is solved. Autonomously resolve the query using the tools available to you. Do NOT guess or make up an answer.
 
-- Use the `apply_patch` tool to edit files (NEVER try `applypatch` or `apply-patch`, only `apply_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`.
 - Fix the problem at the root cause rather than applying surface-level patches
 - Avoid unneeded complexity in your solution
 - Keep changes consistent with the style of the existing codebase

package/src/prompts/src/providers/openai.txt

@@ -208,7 +208,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: