@agi-cli/sdk 0.1.79 → 0.1.81

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agi-cli/sdk",
-	"version": "0.1.79",
+	"version": "0.1.81",
 	"description": "AI agent SDK for building intelligent assistants - tree-shakable and comprehensive",
 	"author": "ntishxyz",
 	"license": "MIT",
@@ -65,6 +65,10 @@
 			"import": "./src/core/src/tools/builtin/websearch.ts",
 			"types": "./src/core/src/tools/builtin/websearch.ts"
 		},
+		"./tools/error": {
+			"import": "./src/core/src/tools/error.ts",
+			"types": "./src/core/src/tools/error.ts"
+		},
 		"./prompts/*": "./src/prompts/src/*"
 	},
 	"files": [

package/src/core/src/index.ts

@@ -32,6 +32,19 @@ export type { ProviderId, ModelInfo } from '../../types/src/index.ts';
 export { discoverProjectTools } from './tools/loader';
 export type { DiscoveredTool } from './tools/loader';
 
+// Tool error handling utilities
+export {
+	isToolError,
+	extractToolError,
+	createToolError,
+} from './tools/error';
+export type {
+	ToolErrorType,
+	ToolErrorResponse,
+	ToolSuccessResponse,
+	ToolResponse,
+} from './tools/error';
+
 // Re-export builtin tools for direct access
 export { buildFsTools } from './tools/builtin/fs/index';
 export { buildGitTools } from './tools/builtin/git';

package/src/core/src/tools/builtin/bash.ts

@@ -2,6 +2,7 @@ import { tool, type Tool } from 'ai';
 import { z } from 'zod';
 import { spawn } from 'node:child_process';
 import DESCRIPTION from './bash.txt' with { type: 'text' };
+import { createToolError, type ToolResponse } from '../error.ts';
 
 function normalizePath(p: string) {
 	const parts = p.replace(/\\/g, '/').split('/');
@@ -58,11 +59,16 @@ export function buildBashTool(projectRoot: string): {
 			cwd?: string;
 			allowNonZeroExit?: boolean;
 			timeout?: number;
-		}) {
+		}): Promise<
+			ToolResponse<{
+				exitCode: number;
+				stdout: string;
+				stderr: string;
+			}>
+		> {
 			const absCwd = resolveSafePath(projectRoot, cwd || '.');
 
-			return new Promise((resolve, reject) => {
-				// Use spawn with shell: true for cross-platform compatibility
+			return new Promise((resolve) => {
 				const proc = spawn(cmd, {
 					cwd: absCwd,
 					shell: true,
@@ -93,24 +99,50 @@ export function buildBashTool(projectRoot: string): {
 					if (timeoutId) clearTimeout(timeoutId);
 
 					if (didTimeout) {
-						reject(new Error(`Command timed out after ${timeout}ms: ${cmd}`));
+						resolve(
+							createToolError(
+								`Command timed out after ${timeout}ms: ${cmd}`,
+								'timeout',
+								{
+									parameter: 'timeout',
+									value: timeout,
+									suggestion: 'Increase timeout or optimize the command',
+								},
+							),
+						);
 					} else if (exitCode !== 0 && !allowNonZeroExit) {
-						const errorMsg =
-							stderr.trim() ||
-							stdout.trim() ||
-							`Command failed with exit code ${exitCode}`;
-						const msg = `${errorMsg}\n\nCommand: ${cmd}\nExit code: ${exitCode}`;
-						reject(new Error(msg));
+						const errorDetail = stderr.trim() || stdout.trim() || '';
+						const errorMsg = `Command failed with exit code ${exitCode}${errorDetail ? `\n\n${errorDetail}` : ''}`;
+						resolve(
+							createToolError(errorMsg, 'execution', {
+								exitCode,
+								stdout,
+								stderr,
+								cmd,
+								suggestion:
+									'Check command syntax or use allowNonZeroExit: true',
+							}),
+						);
 					} else {
-						resolve({ exitCode: exitCode ?? 0, stdout, stderr });
+						resolve({
+							ok: true,
+							exitCode: exitCode ?? 0,
+							stdout,
+							stderr,
+						});
 					}
 				});
 
 				proc.on('error', (err) => {
 					if (timeoutId) clearTimeout(timeoutId);
-					reject(
-						new Error(
-							`Command execution failed: ${err.message}\n\nCommand: ${cmd}`,
+					resolve(
+						createToolError(
+							`Command execution failed: ${err.message}`,
+							'execution',
+							{
+								cmd,
+								originalError: err.message,
+							},
 						),
 					);
 				});

package/src/core/src/tools/builtin/finish.txt

@@ -1,5 +1,10 @@
-- Signal that the task is complete
-- Agent should stream the summary directly as assistant message not using the finish tool
+Call this tool AFTER you have completed all your work AND streamed your final summary/response to the user.
 
-Usage tips:
-- Ensure all necessary outputs are already saved/emitted before finishing
+This signals the end of your turn and that you are done with the current request.
+
+**CRITICAL**: You MUST always call this tool when you are completely finished. The workflow is:
+1. Perform all necessary tool calls (read files, make changes, etc.)
+2. Stream your final text response/summary to the user
+3. Call the finish tool to signal completion
+
+Do NOT call finish before streaming your response. Do NOT forget to call finish after responding.

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

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { readFile } from 'node:fs/promises';
 import { expandTilde, isAbsoluteLike, resolveSafePath } from './util.ts';
 import DESCRIPTION from './read.txt' with { type: 'text' };
+import { createToolError, type ToolResponse } from '../../error.ts';
 
 const embeddedTextAssets: Record<string, string> = {};
 
@@ -43,7 +44,27 @@ export function buildReadTool(projectRoot: string): {
 			path: string;
 			startLine?: number;
 			endLine?: number;
-		}) {
+		}): Promise<
+			ToolResponse<{
+				path: string;
+				content: string;
+				size: number;
+				lineRange?: string;
+				totalLines?: number;
+			}>
+		> {
+			if (!path || path.trim().length === 0) {
+				return createToolError(
+					'Missing required parameter: path',
+					'validation',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: 'Provide a file path to read',
+					},
+				);
+			}
+
 			const req = expandTilde(path);
 			const abs = isAbsoluteLike(req) ? req : resolveSafePath(projectRoot, req);
 
@@ -57,6 +78,7 @@ export function buildReadTool(projectRoot: string): {
 					const selectedLines = lines.slice(start, end);
 					content = selectedLines.join('\n');
 					return {
+						ok: true,
 						path: req,
 						content,
 						size: content.length,
@@ -65,14 +87,31 @@ export function buildReadTool(projectRoot: string): {
 					};
 				}
 
-				return { path: req, content, size: content.length };
-			} catch (_error: unknown) {
+				return { ok: true, path: req, content, size: content.length };
+			} catch (error: unknown) {
 				const embedded = embeddedTextAssets[req];
 				if (embedded) {
 					const content = await readFile(embedded, 'utf-8');
-					return { path: req, content, size: content.length };
+					return { ok: true, path: req, content, size: content.length };
 				}
-				throw new Error(`File not found: ${req}`);
+				const isEnoent =
+					error &&
+					typeof error === 'object' &&
+					'code' in error &&
+					error.code === 'ENOENT';
+				return createToolError(
+					isEnoent
+						? `File not found: ${req}`
+						: `Failed to read file: ${error instanceof Error ? error.message : String(error)}`,
+					isEnoent ? 'not_found' : 'execution',
+					{
+						parameter: 'path',
+						value: req,
+						suggestion: isEnoent
+							? 'Use ls or tree to find available files'
+							: undefined,
+					},
+				);
 			}
 		},
 	});

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

@@ -8,8 +8,7 @@ import {
 	isAbsoluteLike,
 } from './util.ts';
 import DESCRIPTION from './write.txt' with { type: 'text' };
-
-// description imported above
+import { createToolError, type ToolResponse } from '../../error.ts';
 
 export function buildWriteTool(projectRoot: string): {
 	name: string;
@@ -34,27 +33,73 @@ export function buildWriteTool(projectRoot: string): {
 			path: string;
 			content: string;
 			createDirs?: boolean;
-		}) {
+		}): Promise<
+			ToolResponse<{
+				path: string;
+				bytes: number;
+				artifact: unknown;
+			}>
+		> {
+			if (!path || path.trim().length === 0) {
+				return createToolError(
+					'Missing required parameter: path',
+					'validation',
+					{
+						parameter: 'path',
+						value: path,
+						suggestion: 'Provide a file path to write',
+					},
+				);
+			}
+
 			const req = expandTilde(path);
 			if (isAbsoluteLike(req)) {
-				throw new Error(
+				return createToolError(
 					`Refusing to write outside project root: ${req}. Use a relative path within the project.`,
+					'permission',
+					{
+						parameter: 'path',
+						value: req,
+						suggestion: 'Use a relative path within the project',
+					},
 				);
 			}
 			const abs = resolveSafePath(projectRoot, req);
-			if (createDirs) {
-				const dirPath = abs.slice(0, abs.lastIndexOf('/'));
-				await mkdir(dirPath, { recursive: true });
-			}
-			let existed = false;
-			let oldText = '';
+
 			try {
-				oldText = await readFile(abs, 'utf-8');
-				existed = true;
-			} catch {}
-			await writeFile(abs, content);
-			const artifact = await buildWriteArtifact(req, existed, oldText, content);
-			return { path: req, bytes: content.length, artifact } as const;
+				if (createDirs) {
+					const dirPath = abs.slice(0, abs.lastIndexOf('/'));
+					await mkdir(dirPath, { recursive: true });
+				}
+				let existed = false;
+				let oldText = '';
+				try {
+					oldText = await readFile(abs, 'utf-8');
+					existed = true;
+				} catch {}
+				await writeFile(abs, content);
+				const artifact = await buildWriteArtifact(
+					req,
+					existed,
+					oldText,
+					content,
+				);
+				return {
+					ok: true,
+					path: req,
+					bytes: content.length,
+					artifact,
+				};
+			} catch (error: unknown) {
+				return createToolError(
+					`Failed to write file: ${error instanceof Error ? error.message : String(error)}`,
+					'execution',
+					{
+						parameter: 'path',
+						value: req,
+					},
+				);
+			}
 		},
 	});
 	return { name: 'write', tool: write };

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

@@ -4,7 +4,8 @@
 - Returns a compact patch artifact summarizing the change
 
 Usage tips:
-- Only use for creating new files or completely replacing file content
+- 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 or edit instead
 - 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/core/src/tools/builtin/patch.ts

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
 import { dirname, resolve, relative, isAbsolute } from 'node:path';
 import DESCRIPTION from './patch.txt' with { type: 'text' };
+import { createToolError, type ToolResponse } from '../error.ts';
 
 interface PatchAddOperation {
 	kind: 'add';
@@ -106,6 +107,49 @@ function ensureTrailingNewline(lines: string[]) {
 	}
 }
 
+/**
+ * Normalize whitespace for fuzzy matching.
+ * Converts tabs to spaces and trims leading/trailing whitespace.
+ */
+function normalizeWhitespace(line: string): string {
+	return line.replace(/\t/g, '  ').trim();
+}
+
+/**
+ * Find subsequence with optional whitespace normalization for fuzzy matching.
+ * Falls back to normalized matching if exact match fails.
+ */
+function findSubsequenceWithFuzzy(
+	lines: string[],
+	pattern: string[],
+	startIndex: number,
+	useFuzzy: boolean,
+): number {
+	// Try exact match first
+	const exactMatch = findSubsequence(lines, pattern, startIndex);
+	if (exactMatch !== -1) return exactMatch;
+
+	// If fuzzy matching is enabled and exact match failed, try normalized matching
+	if (useFuzzy && pattern.length > 0) {
+		const normalizedLines = lines.map(normalizeWhitespace);
+		const normalizedPattern = pattern.map(normalizeWhitespace);
+
+		const start = Math.max(0, startIndex);
+		for (let i = start; i <= lines.length - pattern.length; i++) {
+			let matches = true;
+			for (let j = 0; j < pattern.length; j++) {
+				if (normalizedLines[i + j] !== normalizedPattern[j]) {
+					matches = false;
+					break;
+				}
+			}
+			if (matches) return i;
+		}
+	}
+
+	return -1;
+}
+
 function findSubsequence(
 	lines: string[],
 	pattern: string[],
@@ -307,7 +351,9 @@ function parseEnvelopedPatch(patch: string): ParsedPatchOperation[] {
 		} else if (prefix === ' ') {
 			currentHunk.lines.push({ kind: 'context', content: line.slice(1) });
 		} else {
-			throw new Error(`Unrecognized patch line: "${line}"`);
+			// Auto-correct: treat lines without prefix as context (with implicit space)
+			// This makes the parser more forgiving for AI-generated patches
+			currentHunk.lines.push({ kind: 'context', content: line });
 		}
 	}
 
@@ -415,6 +461,7 @@ function applyHunksToLines(
 	originalLines: string[],
 	hunks: PatchHunk[],
 	filePath: string,
+	useFuzzy: boolean = false,
 ): { lines: string[]; applied: AppliedHunkResult[] } {
 	const lines = [...originalLines];
 	let searchIndex = 0;
@@ -445,11 +492,16 @@ function applyHunksToLines(
 				: searchIndex;
 
 		let matchIndex = hasExpected
-			? findSubsequence(lines, expected, Math.max(0, hint - 3))
+			? findSubsequenceWithFuzzy(
+					lines,
+					expected,
+					Math.max(0, hint - 3),
+					useFuzzy,
+				)
 			: -1;
 
 		if (hasExpected && matchIndex === -1) {
-			matchIndex = findSubsequence(lines, expected, 0);
+			matchIndex = findSubsequenceWithFuzzy(lines, expected, 0, useFuzzy);
 		}
 
 		if (matchIndex === -1 && hasExpected && hunk.header.context) {
@@ -471,9 +523,20 @@ function applyHunksToLines(
 			const contextInfo = hunk.header.context
 				? ` near context '${hunk.header.context}'`
 				: '';
-			throw new Error(
-				`Failed to apply patch hunk in ${filePath}${contextInfo}.`,
-			);
+
+			// Provide helpful error with nearby context
+			const nearbyStart = Math.max(0, hint - 2);
+			const nearbyEnd = Math.min(lines.length, hint + 5);
+			const nearbyLines = lines.slice(nearbyStart, nearbyEnd);
+			const lineNumberInfo =
+				nearbyStart > 0 ? ` (around line ${nearbyStart + 1})` : '';
+
+			let errorMsg = `Failed to apply patch hunk in ${filePath}${contextInfo}.\n`;
+			errorMsg += `Expected to find:\n${expected.map((l) => `  ${l}`).join('\n')}\n`;
+			errorMsg += `Nearby context${lineNumberInfo}:\n${nearbyLines.map((l, idx) => `  ${nearbyStart + idx + 1}: ${l}`).join('\n')}\n`;
+			errorMsg += `Hint: Check for whitespace differences (tabs vs spaces). Try enabling fuzzyMatch option.`;
+
+			throw new Error(errorMsg);
 		}
 
 		const deleteCount = hasExpected ? expected.length : 0;
@@ -532,6 +595,7 @@ function computeInsertionIndex(
 async function applyUpdateOperation(
 	projectRoot: string,
 	operation: PatchUpdateOperation,
+	useFuzzy: boolean = false,
 ): Promise<AppliedOperationRecord> {
 	const targetPath = resolveProjectPath(projectRoot, operation.filePath);
 	let originalContent: string;
@@ -549,6 +613,7 @@ async function applyUpdateOperation(
 		originalLines,
 		operation.hunks,
 		operation.filePath,
+		useFuzzy,
 	);
 	ensureTrailingNewline(updatedLines);
 	await writeFile(targetPath, joinLines(updatedLines, newline), 'utf-8');
@@ -665,7 +730,11 @@ function formatNormalizedPatch(operations: AppliedOperationRecord[]): string {
 	return lines.join('\n');
 }
 
-async function applyEnvelopedPatch(projectRoot: string, patch: string) {
+async function applyEnvelopedPatch(
+	projectRoot: string,
+	patch: string,
+	useFuzzy: boolean = false,
+) {
 	const operations = parseEnvelopedPatch(patch);
 	const applied: AppliedOperationRecord[] = [];
 
@@ -675,7 +744,9 @@ async function applyEnvelopedPatch(projectRoot: string, patch: string) {
 		} else if (operation.kind === 'delete') {
 			applied.push(await applyDeleteOperation(projectRoot, operation));
 		} else {
-			applied.push(await applyUpdateOperation(projectRoot, operation));
+			applied.push(
+				await applyUpdateOperation(projectRoot, operation, useFuzzy),
+			);
 		}
 	}
 
@@ -700,46 +771,98 @@ export function buildApplyPatchTool(projectRoot: string): {
 				.describe(
 					'Allow hunks to be rejected without failing the whole operation',
 				),
+			fuzzyMatch: z
+				.boolean()
+				.optional()
+				.default(true)
+				.describe(
+					'Enable fuzzy matching with whitespace normalization (converts tabs to spaces for matching)',
+				),
 		}),
-		async execute({ patch }: { patch: string; allowRejects?: boolean }) {
+		async execute({
+			patch,
+			fuzzyMatch,
+		}: {
+			patch: string;
+			allowRejects?: boolean;
+			fuzzyMatch?: boolean;
+		}): Promise<
+			ToolResponse<{
+				output: string;
+				changes: unknown[];
+				artifact: unknown;
+			}>
+		> {
+			if (!patch || patch.trim().length === 0) {
+				return createToolError(
+					'Missing required parameter: patch',
+					'validation',
+					{
+						parameter: 'patch',
+						value: patch,
+						suggestion: 'Provide patch content in enveloped format',
+					},
+				);
+			}
+
 			if (
 				!patch.includes(PATCH_BEGIN_MARKER) ||
 				!patch.includes(PATCH_END_MARKER)
 			) {
-				throw new Error(
+				return createToolError(
 					'Only enveloped patch format is supported. Patch must start with "*** Begin Patch" and contain "*** Add File:", "*** Update File:", or "*** Delete File:" directives.',
+					'validation',
+					{
+						parameter: 'patch',
+						suggestion:
+							'Use enveloped patch format starting with *** Begin Patch',
+					},
 				);
 			}
 
-			const { operations, normalizedPatch } = await applyEnvelopedPatch(
-				projectRoot,
-				patch,
-			);
-			const summary = summarizeOperations(operations);
-			const changes = operations.map((operation) => ({
-				filePath: operation.filePath,
-				kind: operation.kind,
-				hunks: operation.hunks.map((hunk) => ({
-					oldStart: hunk.oldStart,
-					oldLines: hunk.oldLines,
-					newStart: hunk.newStart,
-					newLines: hunk.newLines,
-					additions: hunk.additions,
-					deletions: hunk.deletions,
-					context: hunk.header.context,
-				})),
-			}));
-
-			return {
-				ok: true,
-				output: 'Applied enveloped patch',
-				changes,
-				artifact: {
-					kind: 'file_diff',
-					patch: normalizedPatch,
-					summary,
-				},
-			} as const;
+			try {
+				const { operations, normalizedPatch } = await applyEnvelopedPatch(
+					projectRoot,
+					patch,
+					fuzzyMatch ?? true,
+				);
+				const summary = summarizeOperations(operations);
+				const changes = operations.map((operation) => ({
+					filePath: operation.filePath,
+					kind: operation.kind,
+					hunks: operation.hunks.map((hunk) => ({
+						oldStart: hunk.oldStart,
+						oldLines: hunk.oldLines,
+						newStart: hunk.newStart,
+						newLines: hunk.newLines,
+						additions: hunk.additions,
+						deletions: hunk.deletions,
+						context: hunk.header.context,
+					})),
+				}));
+
+				return {
+					ok: true,
+					output: 'Applied enveloped patch',
+					changes,
+					artifact: {
+						kind: 'file_diff',
+						patch: normalizedPatch,
+						summary,
+					},
+				};
+			} catch (error: unknown) {
+				const errorMessage =
+					error instanceof Error ? error.message : String(error);
+				return createToolError(
+					`Failed to apply patch: ${errorMessage}`,
+					'execution',
+					{
+						suggestion:
+							'Check that the patch format is correct and target files exist',
+					},
+				);
+			}
 		},
 	});
 	return { name: 'apply_patch', tool: applyPatch };

package/src/core/src/tools/builtin/patch.txt

@@ -2,13 +2,18 @@ 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 and are confident the content hasn't changed
+- You have JUST read the file immediately before (within the same response) and are confident the content hasn't changed
 
-**IMPORTANT: Patches require EXACT line matches. If the file content has changed since you last read it, the patch will fail.**
+**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.**
 
@@ -63,7 +68,33 @@ All patches must be wrapped in markers and use explicit file directives:
 *** End Patch
 ```
 
-The `@@ context line` helps locate the exact position, but the `-` lines must still match exactly.
+**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:
 ```
@@ -89,11 +120,17 @@ The `@@ context line` helps locate the exact position, but the `-` lines must st
 - Lines starting with `+` are added
 - Lines starting with `-` are removed  
 - Lines starting with ` ` (space) are context (kept unchanged)
-- Lines starting with `@@` provide context for finding the location
+- 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. The file may have changed, or you may have mistyped the lines. Solution: Use the `edit` tool instead.
+**"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
 

package/src/core/src/tools/error.ts

@@ -0,0 +1,67 @@
+export type ToolErrorType =
+	| 'validation'
+	| 'not_found'
+	| 'permission'
+	| 'execution'
+	| 'timeout'
+	| 'unsupported';
+
+export type ToolErrorResponse = {
+	ok: false;
+	error: string;
+	errorType?: ToolErrorType;
+	details?: {
+		parameter?: string;
+		value?: unknown;
+		constraint?: string;
+		suggestion?: string;
+		[key: string]: unknown;
+	};
+	stack?: string;
+};
+
+export type ToolSuccessResponse<T = unknown> = {
+	ok: true;
+} & T;
+
+export type ToolResponse<T = unknown> =
+	| ToolSuccessResponse<T>
+	| ToolErrorResponse;
+
+export function isToolError(result: unknown): result is ToolErrorResponse {
+	if (!result || typeof result !== 'object') return false;
+	const obj = result as Record<string, unknown>;
+	return obj.ok === false || 'error' in obj || obj.success === false;
+}
+
+export function extractToolError(
+	result: unknown,
+	topLevelError?: string,
+): string | undefined {
+	if (topLevelError?.trim()) return topLevelError.trim();
+	if (!result || typeof result !== 'object') return undefined;
+
+	const obj = result as Record<string, unknown>;
+	const keys = ['error', 'stderr', 'message', 'detail', 'details', 'reason'];
+	for (const key of keys) {
+		const value = obj[key];
+		if (typeof value === 'string') {
+			const trimmed = value.trim();
+			if (trimmed.length) return trimmed;
+		}
+	}
+	return undefined;
+}
+
+export function createToolError(
+	error: string,
+	errorType?: ToolErrorType,
+	details?: ToolErrorResponse['details'],
+): ToolErrorResponse {
+	return {
+		ok: false,
+		error,
+		errorType,
+		details,
+	};
+}

package/src/prompts/src/base.txt

@@ -1,14 +1,24 @@
 You are a helpful, concise assistant.
-- Stream the final answer as assistant text; call finish when done.
 - CRITICAL: Emit progress updates using the `progress_update` tool at key milestones — at the start (planning), after initial repo discovery (discovering), before file edits (preparing), during edits (writing), and when validating (verifying). Prefer short messages (<= 80 chars).
 - Do not print pseudo tool calls like `call:tool{}`; invoke tools directly.
 - Use sensible default filenames when needed.
 - Prefer minimal, precise outputs and actionable steps.
 
+## Finish Tool - CRITICAL
+
+You MUST call the `finish` tool at the end of every response to signal completion. The correct workflow is:
+
+1. Perform all necessary work (tool calls, file edits, searches, etc.)
+2. Stream your final text response or summary to the user explaining what you did
+3. **Call the `finish` tool** to signal you are done
+
+**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 on it - never patch from memory
 - When making multiple edits to the same file, combine them into a single edit operation with multiple ops
 - Each edit operation re-reads the file, so ops within a single edit call are applied sequentially to the latest content
 - If you need to make edits based on previous edits, ensure they're in the same edit call or re-read the file between calls
 - Never assume file content remains unchanged between separate edit operations
 - When using apply_patch, ensure the patch is based on the current file content, not stale versions
-- If a patch fails, read the file first to understand its current state before generating a new patch
+- If a patch fails, it means you didn't read the file first or the content doesn't match what you expected

package/src/prompts/src/providers/anthropic.txt

@@ -83,12 +83,27 @@ When making changes to files, first understand the file's code conventions. Mimi
 ## File Editing Best Practices
 
 **Using the `apply_patch` Tool** (Recommended):
+- **CRITICAL**: ALWAYS read the target file immediately before creating a patch - never patch from memory
 - Primary choice for targeted file edits - avoids rewriting entire files
 - Only requires the specific lines you want to change
 - Format: `*** Begin Patch` ... `*** Update File: path` ... `-old` / `+new` ... `*** End Patch`
-- Only use when you have a complete unified diff ready
-- Ensure patch is based on current file content (not stale)
-- If patch fails, read the file first to see current state before retrying
+- For multiple changes in one file: use multiple `@@` headers to separate non-consecutive hunks
+- MUST include context lines (space prefix) - the `@@` line is just an optional hint
+- Workflow: 1) Read file, 2) Create patch based on what you just read, 3) Apply patch
+- The `-` lines in your patch MUST match exactly what's in the file character-for-character
+- If patch fails, it means the file content doesn't match - read it again and retry
+- **Best for**: Small, surgical edits to code files (< 50 line changes per file)
+- **Struggles with**: Large restructures (> 50 lines), major section reorganizations
+
+**Patch Format Reminder**:
+```
+*** Update File: path
+@@ optional hint              ← Optional comment/hint (not parsed)
+ actual line from file        ← Context (space prefix) - REQUIRED
+-line to remove               ← Remove this line
++line to add                  ← Add this line
+ more context                 ← More context (space prefix)
+```
 
 **Using the `edit` Tool** (Alternative):
 - Specify the file path and a list of operations
@@ -98,13 +113,14 @@ When making changes to files, first understand the file's code conventions. Mimi
 - When making multiple changes to a file, use ONE `edit` call with multiple ops
 
 **Using the `write` Tool** (Last Resort):
-- Only use when creating new files or completely replacing file content
+- Use for creating NEW files
+- Use when replacing >70% of a file's content (almost complete rewrite)
 - NEVER use for targeted edits - it rewrites the entire file
 - Wastes output tokens and risks hallucinating unchanged parts
 
 **Never**:
 - Use `write` for partial file edits (use `apply_patch` or `edit` instead)
-- Make multiple separate `edit` or `apply_patch` calls for the same file
+- Make multiple separate `edit` or `apply_patch` calls for the same file (use multiple hunks with @@ headers or multiple ops instead)
 - Assume file content remains unchanged between operations
 - Use `bash` with `sed`/`awk` for programmatic file editing (use `edit` instead)
 

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

@@ -47,12 +47,27 @@ You have access to a rich set of specialized tools optimized for coding tasks:
 ## File Editing Best Practices
 
 **Using the `apply_patch` Tool** (Recommended):
+- **CRITICAL**: ALWAYS read the target file immediately before creating a patch - never patch from memory
 - Primary choice for targeted file edits - avoids rewriting entire files
 - Only requires the specific lines you want to change
 - Format: `*** Begin Patch` ... `*** Update File: path` ... `-old` / `+new` ... `*** End Patch`
-- Only use when you have a complete unified diff ready
-- Ensure patch is based on current file content (not stale)
-- If patch fails, read the file first to see current state before retrying
+- For multiple changes in one file: use multiple `@@` headers to separate non-consecutive hunks
+- MUST include context lines (space prefix) - the `@@` line is just an optional hint
+- Workflow: 1) Read file, 2) Create patch based on what you just read, 3) Apply patch
+- The `-` lines in your patch MUST match exactly what's in the file character-for-character
+- If patch fails, it means the file content doesn't match - read it again and retry
+- **Best for**: Small, surgical edits to code files (< 50 line changes per file)
+- **Struggles with**: Large restructures (> 50 lines), major section reorganizations
+
+**Patch Format Reminder**:
+```
+*** Update File: path
+@@ optional hint              ← Optional comment/hint (not parsed)
+ actual line from file        ← Context (space prefix) - REQUIRED
+-line to remove               ← Remove this line
++line to add                  ← Add this line
+ more context                 ← More context (space prefix)
+```
 
 **Using the `edit` Tool** (Alternative):
 - Specify the file path and a list of operations
@@ -62,13 +77,14 @@ You have access to a rich set of specialized tools optimized for coding tasks:
 - When making multiple changes to a file, use ONE `edit` call with multiple ops
 
 **Using the `write` Tool** (Last Resort):
-- Only use when creating new files or completely replacing file content
+- Use for creating NEW files
+- Use when replacing >70% of a file's content (almost complete rewrite)
 - NEVER use for targeted edits - it rewrites the entire file
 - Wastes output tokens and risks hallucinating unchanged parts
 
 **Never**:
 - Use `write` for partial file edits (use `apply_patch` or `edit` instead)
-- Make multiple separate `edit` or `apply_patch` calls for the same file
+- Make multiple separate `edit` or `apply_patch` calls for the same file (use multiple hunks with @@ headers or multiple ops instead)
 - Assume file content remains unchanged between operations
 - Use `bash` with `sed`/`awk` for programmatic file editing (use `edit` instead)
 
@@ -238,7 +254,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"]}
+- 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"]}
 
 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/google.txt

@@ -29,12 +29,27 @@ call with multiple ops. Each separate `edit` operation re-reads the file fresh.
 ## File Editing Best Practices
 
 **Using the `apply_patch` Tool** (Recommended):
+- **CRITICAL**: ALWAYS read the target file immediately before creating a patch - never patch from memory
 - Primary choice for targeted file edits - avoids rewriting entire files
 - Only requires the specific lines you want to change
 - Format: `*** Begin Patch` ... `*** Update File: path` ... `-old` / `+new` ... `*** End Patch`
-- Only use when you have a complete unified diff ready
-- Ensure patch is based on current file content (not stale)
-- If patch fails, read the file first to see current state before retrying
+- For multiple changes in one file: use multiple `@@` headers to separate non-consecutive hunks
+- MUST include context lines (space prefix) - the `@@` line is just an optional hint
+- Workflow: 1) Read file, 2) Create patch based on what you just read, 3) Apply patch
+- The `-` lines in your patch MUST match exactly what's in the file character-for-character
+- If patch fails, it means the file content doesn't match - read it again and retry
+- **Best for**: Small, surgical edits to code files (< 50 line changes per file)
+- **Struggles with**: Large restructures (> 50 lines), major section reorganizations
+
+**Patch Format Reminder**:
+```
+*** Update File: path
+@@ optional hint              ← Optional comment/hint (not parsed)
+ actual line from file        ← Context (space prefix) - REQUIRED
+-line to remove               ← Remove this line
++line to add                  ← Add this line
+ more context                 ← More context (space prefix)
+```
 
 **Using the `edit` Tool** (Alternative):
 - Specify the file path and a list of operations
@@ -44,13 +59,14 @@ call with multiple ops. Each separate `edit` operation re-reads the file fresh.
 - When making multiple changes to a file, use ONE `edit` call with multiple ops
 
 **Using the `write` Tool** (Last Resort):
-- Only use when creating new files or completely replacing file content
+- Use for creating NEW files
+- Use when replacing >70% of a file's content (almost complete rewrite)
 - NEVER use for targeted edits - it rewrites the entire file
 - Wastes output tokens and risks hallucinating unchanged parts
 
 **Never**:
 - Use `write` for partial file edits (use `apply_patch` or `edit` instead)
-- Make multiple separate `edit` or `apply_patch` calls for the same file
+- Make multiple separate `edit` or `apply_patch` calls for the same file (use multiple hunks with @@ headers or multiple ops instead)
 - Assume file content remains unchanged between operations
 - Use `bash` with `sed`/`awk` for programmatic file editing (use `edit` instead)
 

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

@@ -73,12 +73,27 @@ Your toolset includes specialized file editing and search tools. Follow these gu
 ## File Editing Best Practices
 
 **Using the `apply_patch` Tool** (Recommended):
+- **CRITICAL**: ALWAYS read the target file immediately before creating a patch - never patch from memory
 - Primary choice for targeted file edits - avoids rewriting entire files
 - Only requires the specific lines you want to change
 - Format: `*** Begin Patch` ... `*** Update File: path` ... `-old` / `+new` ... `*** End Patch`
-- Only use when you have a complete unified diff ready
-- Ensure patch is based on current file content (not stale)
-- If patch fails, read the file first to see current state before retrying
+- For multiple changes in one file: use multiple `@@` headers to separate non-consecutive hunks
+- MUST include context lines (space prefix) - the `@@` line is just an optional hint
+- Workflow: 1) Read file, 2) Create patch based on what you just read, 3) Apply patch
+- The `-` lines in your patch MUST match exactly what's in the file character-for-character
+- If patch fails, it means the file content doesn't match - read it again and retry
+- **Best for**: Small, surgical edits to code files (< 50 line changes per file)
+- **Struggles with**: Large restructures (> 50 lines), major section reorganizations
+
+**Patch Format Reminder**:
+```
+*** Update File: path
+@@ optional hint              ← Optional comment/hint (not parsed)
+ actual line from file        ← Context (space prefix) - REQUIRED
+-line to remove               ← Remove this line
++line to add                  ← Add this line
+ more context                 ← More context (space prefix)
+```
 
 **Using the `edit` Tool** (Alternative):
 - Specify the file path and a list of operations
@@ -88,13 +103,14 @@ Your toolset includes specialized file editing and search tools. Follow these gu
 - When making multiple changes to a file, use ONE `edit` call with multiple ops
 
 **Using the `write` Tool** (Last Resort):
-- Only use when creating new files or completely replacing file content
+- Use for creating NEW files
+- Use when replacing >70% of a file's content (almost complete rewrite)
 - NEVER use for targeted edits - it rewrites the entire file
 - Wastes output tokens and risks hallucinating unchanged parts
 
 **Never**:
 - Use `write` for partial file edits (use `apply_patch` or `edit` instead)
-- Make multiple separate `edit` or `apply_patch` calls for the same file
+- Make multiple separate `edit` or `apply_patch` calls for the same file (use multiple hunks with @@ headers or multiple ops instead)
 - Assume file content remains unchanged between operations
 - Use `bash` with `sed`/`awk` for programmatic file editing (use `edit` instead)
 
@@ -227,7 +243,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"]}
+- 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"]}
 
 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: