@cortexkit/aft-opencode 0.3.0 → 0.4.1

package/dist/tools/hoisted.js

@@ -59,63 +59,49 @@ function buildUnifiedDiff(fp, before, after) {
 }
 const z = tool.schema;
 // ---------------------------------------------------------------------------
-// Descriptions — verbose because .describe() on Zod args does NOT reach the agent.
-// The description string is the ONLY documentation the LLM sees.
+// Tool descriptions focus on behavior, modes, and return values.
+// Parameter docs live in Zod .describe() and reach the LLM via JSON Schema.
 // ---------------------------------------------------------------------------
-const READ_DESCRIPTION = `Read files, directories, or inspect code symbols with call-graph annotations.
+const READ_DESCRIPTION = `Read file contents or list directory entries.
 
-**Modes** (determined by which parameters you provide):
-
-1. **Read file** (default) — pass \`filePath\` only
-   Returns line-numbered content. Use \`start_line\`/\`end_line\` to read specific sections.
-   Example: \`{ "filePath": "src/app.ts" }\` or \`{ "filePath": "src/app.ts", "start_line": 50, "end_line": 100 }\`
-
-2. **Inspect symbol** — pass \`filePath\` + \`symbol\`
-   Returns the full source of a named symbol (function, class, type) with call-graph
-   annotations showing what it calls and what calls it. Includes surrounding context lines.
-   Example: \`{ "filePath": "src/app.ts", "symbol": "handleRequest" }\`
-
-3. **Inspect multiple symbols** — pass \`filePath\` + \`symbols\` array
-   Returns multiple symbols in one call. More efficient than separate calls.
-   Example: \`{ "filePath": "src/app.ts", "symbols": ["Config", "createApp"] }\`
+Use either startLine/endLine OR offset/limit to read a section of a file.
 
-4. **List directory** — pass \`filePath\` pointing to a directory
-   Returns sorted entries, directories have trailing \`/\`.
-   Example: \`{ "filePath": "src/" }\`
-
-**Parameters:**
-- \`filePath\` (string, required): Path to file or directory (absolute or relative to project root)
-- \`symbol\` (string): Name of a single symbol to inspect — returns full source + call graph
-- \`symbols\` (string[]): Array of symbol names to inspect in one call
-- \`start_line\` (number): 1-based line to start reading from (default: 1)
-- \`end_line\` (number): 1-based line to stop reading at, inclusive
-- \`limit\` (number): Max lines to return (default: 2000). Ignored when end_line is set.
-- \`context_lines\` (number): Lines of context around symbols (default: 3)
-
-**Behavior:**
+Behavior:
+- Returns line-numbered content (e.g., "1: const x = 1")
 - Lines longer than 2000 characters are truncated
-- Output capped at 50KB — use start_line/end_line to page through large files
+- Output capped at 50KB
 - Binary files are auto-detected and return a size-only message
-- Symbol mode includes \`calls_out\` and \`called_by\` annotations from call-graph analysis
-- For Markdown files, use heading text as symbol name (e.g., symbol: "Architecture")`;
+- Image files (.png, .jpg, .gif, .webp, etc.) and PDFs return a metadata string (format, size, path) — no file content is returned
+- Directories return sorted entries with trailing / for subdirectories
+
+Examples:
+  Read full file: { "filePath": "src/app.ts" }
+  Read lines 50-100: { "filePath": "src/app.ts", "startLine": 50, "endLine": 100 }
+  Read 30 lines from line 200: { "filePath": "src/app.ts", "offset": 200, "limit": 30 }
+  List directory: { "filePath": "src/" }
+
+Returns: Line-numbered file content string. For directories: newline-joined sorted entries. For binary files: size/message string.`;
 /**
- * Creates the unified read tool. Registers as "read" when hoisted, "aft_read" when not.
+ * Creates the simple read tool. Registers as "read" when hoisted, "aft_read" when not.
  */
 export function createReadTool(ctx) {
     return {
         description: READ_DESCRIPTION,
         args: {
-            filePath: z.string(),
-            symbol: z.string().optional(),
-            symbols: z.array(z.string()).optional(),
-            start_line: z.number().optional(),
-            end_line: z.number().optional(),
-            limit: z.number().optional(),
-            context_lines: z.number().optional(),
+            filePath: z
+                .string()
+                .describe("Path to file or directory (absolute or relative to project root)"),
+            startLine: z.number().optional().describe("1-based line to start reading from"),
+            endLine: z.number().optional().describe("1-based line to stop reading at (inclusive)"),
+            limit: z.number().optional().describe("Max lines to return (default: 2000)"),
+            offset: z
+                .number()
+                .optional()
+                .describe("1-based line number to start reading from (use with limit). Ignored if startLine is provided"),
         },
         execute: async (args, context) => {
             const bridge = ctx.pool.getBridge(context.directory);
-            const file = (args.filePath ?? args.file);
+            const file = args.filePath;
             // Resolve relative paths
             const filePath = path.isAbsolute(file) ? file : path.resolve(context.directory, file);
             // Permission check
@@ -174,59 +160,23 @@ export function createReadTool(ctx) {
                 }
                 return `${msg} (${ext.slice(1).toUpperCase()}, ${sizeStr}). File: ${filePath}`;
             }
-            const _relPath = path.relative(context.worktree, filePath);
-            // Route: symbol/symbols → zoom command, everything else → read command
-            const hasSymbol = typeof args.symbol === "string" && args.symbol.length > 0;
-            const hasSymbols = Array.isArray(args.symbols) && args.symbols.length > 0;
-            if (hasSymbol || hasSymbols) {
-                // Symbol mode → zoom command
-                const params = { file: filePath };
-                if (hasSymbol)
-                    params.symbol = args.symbol;
-                if (hasSymbols)
-                    params.symbols = args.symbols;
-                if (args.start_line !== undefined)
-                    params.start_line = args.start_line;
-                if (args.end_line !== undefined)
-                    params.end_line = args.end_line;
-                if (args.context_lines !== undefined)
-                    params.context_lines = args.context_lines;
-                const data = await bridge.send("zoom", params);
-                const callID = getCallID(context);
-                if (callID)
-                    storeToolMetadata(context.sessionID, callID, {
-                        title: relativeToWorktree(filePath, context.worktree),
-                        metadata: { title: relativeToWorktree(filePath, context.worktree) },
-                    });
-                return JSON.stringify(data);
-            }
-            // Line-range mode with start_line + end_line → also zoom (has context_before/after)
-            if (args.start_line !== undefined && args.end_line !== undefined) {
-                const params = {
-                    file: filePath,
-                    start_line: args.start_line,
-                    end_line: args.end_line,
-                };
-                if (args.context_lines !== undefined)
-                    params.context_lines = args.context_lines;
-                const data = await bridge.send("zoom", params);
-                const lineCallID = getCallID(context);
-                if (lineCallID) {
-                    const dp = relativeToWorktree(filePath, context.worktree);
-                    storeToolMetadata(context.sessionID, lineCallID, {
-                        title: `${dp}:${args.start_line}-${args.end_line}`,
-                        metadata: { title: `${dp}:${args.start_line}-${args.end_line}` },
-                    });
+            // Normalize offset/limit to startLine/endLine (backward compat with opencode's read)
+            let startLine = args.startLine;
+            let endLine = args.endLine;
+            if (startLine === undefined && args.offset !== undefined) {
+                startLine = args.offset;
+                if (args.limit !== undefined) {
+                    endLine = Number(args.offset) + Number(args.limit) - 1;
                 }
-                return JSON.stringify(data);
             }
-            // Plain read mode → read command (line-numbered, truncated, binary/dir detection)
+            // Always use Rust read command — simple file reading only
             const params = { file: filePath };
-            if (args.start_line !== undefined)
-                params.start_line = args.start_line;
-            if (args.end_line !== undefined)
-                params.end_line = args.end_line;
-            if (args.limit !== undefined)
+            if (startLine !== undefined)
+                params.start_line = startLine;
+            if (endLine !== undefined)
+                params.end_line = endLine;
+            // Only send limit if we did NOT convert offset to startLine/endLine
+            if (args.limit !== undefined && args.offset === undefined)
                 params.limit = args.limit;
             const data = await bridge.send("read", params);
             const readCallID = getCallID(context);
@@ -254,7 +204,7 @@ export function createReadTool(ctx) {
             let output = data.content;
             // Add navigation hint if truncated
             if (data.truncated) {
-                output += `\n(Showing lines ${data.start_line}-${data.end_line} of ${data.total_lines}. Use start_line/end_line to read other sections.)`;
+                output += `\n(Showing lines ${data.start_line}-${data.end_line} of ${data.total_lines}. Use startLine/endLine to read other sections.)`;
             }
             return output;
         },
@@ -263,33 +213,35 @@ export function createReadTool(ctx) {
 // ---------------------------------------------------------------------------
 // WRITE tool
 // ---------------------------------------------------------------------------
-const WRITE_DESCRIPTION = `Write content to a file, creating it (and parent directories) if needed.
+function getWriteDescription(editToolName) {
+    return `Write content to a file, creating it (and parent directories) if needed.
 
 Automatically creates parent directories. Backs up existing files before overwriting.
 If the project has a formatter configured (biome, prettier, rustfmt, etc.), the file
 is auto-formatted after writing. Returns inline LSP diagnostics when available.
 
-**Parameters:**
-- \`filePath\` (string, required): Path to the file to write (absolute or relative to project root)
-- \`content\` (string, required): The full content to write to the file
-
 **Behavior:**
 - Creates parent directories automatically (no need to mkdir first)
 - Existing files are backed up before overwriting (recoverable via aft_safety undo)
 - Auto-formats using project formatter if configured (biome.json, .prettierrc, etc.)
-- Returns LSP diagnostics inline if type errors are introduced
+- Returns LSP error-level diagnostics inline if type errors are introduced
 - Use this for creating new files or completely replacing file contents
-- For partial edits (find/replace), use the \`edit\` tool instead`;
-function createWriteTool(ctx) {
+- For partial edits (find/replace), use the \`${editToolName}\` tool instead
+
+Returns: Status message string (for example: "Created new file. Auto-formatted.") with optional inline LSP error lines.`;
+}
+function createWriteTool(ctx, editToolName = "edit") {
     return {
-        description: WRITE_DESCRIPTION,
+        description: getWriteDescription(editToolName),
         args: {
-            filePath: z.string(),
-            content: z.string(),
+            filePath: z
+                .string()
+                .describe("Path to the file to write (absolute or relative to project root)"),
+            content: z.string().describe("The full content to write to the file"),
         },
         execute: async (args, context) => {
             const bridge = ctx.pool.getBridge(context.directory);
-            const file = (args.filePath ?? args.file);
+            const file = args.filePath;
             const content = args.content;
             const filePath = path.isAbsolute(file) ? file : path.resolve(context.directory, file);
             const relPath = path.relative(context.worktree, filePath);
@@ -350,77 +302,93 @@ function createWriteTool(ctx) {
 // ---------------------------------------------------------------------------
 // EDIT tool
 // ---------------------------------------------------------------------------
-const EDIT_DESCRIPTION = `Edit a file by finding and replacing text, or by targeting named symbols.
+function getEditDescription(writeToolName) {
+    return `Edit a file by finding and replacing text, or by targeting named symbols.
 
 **Modes** (determined by which parameters you provide):
 
-1. **Find and replace** — pass \`filePath\` + \`match\` + \`replacement\`
-   Finds the exact text in \`match\` and replaces it with \`replacement\`.
-   Returns an error if multiple matches are found (use \`occurrence\` to select one,
-   or \`replace_all: true\` to replace all).
-   Example: \`{ "filePath": "src/app.ts", "match": "const x = 1", "replacement": "const x = 2" }\`
+Mode priority: operations > edits > symbol (without oldString) > oldString (find/replace) > content-only (${writeToolName})
 
-2. **Replace all occurrences** — add \`replace_all: true\`
-   Replaces every occurrence of \`match\` in the file.
-   Example: \`{ "filePath": "src/app.ts", "match": "oldName", "replacement": "newName", "replace_all": true }\`
+1. **Multi-file transaction** — pass \`operations\` array
+   Edits across multiple files with checkpoint-based rollback on failure.
+   Each operation: \`{ "file": "path", "command": "edit_match" | "write", ... }\`.
+   For \`edit_match\`: include \`match\`, \`replacement\`. For \`write\`: include \`content\`.
+   Example: \`{ "operations": [{ "file": "a.ts", "command": "edit_match", "match": "old", "replacement": "new" }, { "file": "b.ts", "command": "write", "content": "..." }] }\`
 
-3. **Select specific occurrence** — add \`occurrence: N\` (0-indexed)
-   When multiple matches exist, select the Nth one (0 = first, 1 = second, etc.).
-   Example: \`{ "filePath": "src/app.ts", "match": "TODO", "replacement": "DONE", "occurrence": 0 }\`
+2. **Batch edits** — pass \`filePath\` + \`edits\` array
+   Multiple edits in one file atomically. Each edit is either:
+   - \`{ "oldString": "old", "newString": "new" }\` — find/replace
+   - \`{ "startLine": 5, "endLine": 7, "content": "new lines" }\` — replace line range (1-based, both inclusive)
+   Set content to empty string to delete lines.
 
-4. **Symbol replace** — pass \`filePath\` + \`symbol\` + \`content\`
+3. **Symbol replace** — pass \`filePath\` + \`symbol\` + \`content\`
    Replaces an entire named symbol (function, class, type) with new content.
    Includes decorators, attributes, and doc comments in the replacement range.
+   **Important:** You must NOT provide \`oldString\` when using symbol mode — if present, the tool silently falls back to find/replace mode.
    Example: \`{ "filePath": "src/app.ts", "symbol": "handleRequest", "content": "function handleRequest() { ... }" }\`
 
-5. **Batch edits** — pass \`filePath\` + \`edits\` array
-   Multiple edits in one file atomically. Each edit is either:
-   - \`{ "match": "old", "replacement": "new" }\` — find/replace
-   - \`{ "line_start": 5, "line_end": 7, "content": "new lines" }\` — replace line range (1-based, inclusive)
-   Set content to empty string to delete lines.
-   Example: \`{ "filePath": "src/app.ts", "edits": [{ "match": "foo", "replacement": "bar" }, { "line_start": 10, "line_end": 12, "content": "" }] }\`
+4. **Find and replace** — pass \`filePath\` + \`oldString\` + \`newString\`
+   Finds the exact text in \`oldString\` and replaces it with \`newString\`.
+   Supports fuzzy matching (handles whitespace differences automatically).
+   If multiple matches exist, specify which one with \`occurrence\` or use \`replaceAll: true\`.
+   Example: \`{ "filePath": "src/app.ts", "oldString": "const x = 1", "newString": "const x = 2" }\`
 
-6. **Multi-file transaction** — pass \`operations\` array
-   Atomic edits across multiple files with rollback on failure.
-   Example: \`{ "operations": [{ "file": "a.ts", "command": "write", "content": "..." }, { "file": "b.ts", "command": "edit_match", "match": "x", "replacement": "y" }] }\`
+5. **Replace all occurrences** — add \`replaceAll: true\`
+   Replaces every occurrence of \`oldString\` in the file.
+   Example: \`{ "filePath": "src/app.ts", "oldString": "oldName", "newString": "newName", "replaceAll": true }\`
 
-7. **Glob replace** — pass \`filePath\` as glob pattern (e.g. \`"src/**/*.ts"\`) + \`match\` + \`replacement\`
-   Replaces across all matching files. Must use \`replace_all: true\`.
-   Example: \`{ "filePath": "src/**/*.ts", "match": "@deprecated", "replacement": "", "replace_all": true }\`
+6. **Select specific occurrence** — add \`occurrence: N\` (0-indexed)
+   When multiple matches exist, select the Nth one (0 = first, 1 = second, etc.).
+   Example: \`{ "filePath": "src/app.ts", "oldString": "TODO", "newString": "DONE", "occurrence": 0 }\`
 
-**Parameters:**
-- \`filePath\` (string): Path to file, or glob pattern for multi-file operations
-- \`match\` (string): Text to find (exact match). For multi-line, use actual newlines.
-- \`replacement\` (string): Text to replace with
-- \`replace_all\` (boolean): Replace all occurrences instead of erroring on ambiguity
-- \`occurrence\` (number): 0-indexed occurrence to replace when multiple matches exist
-- \`symbol\` (string): Named symbol to replace (function, class, type)
-- \`content\` (string): New content for symbol replace or file write
-- \`edits\` (array): Batch edits — array of { match, replacement } or { line_start, line_end, content }
-- \`operations\` (array): Transaction — array of { file, command, ... } for atomic multi-file edits
-- \`dry_run\` (boolean): Preview changes without applying (returns diff)
-- \`diagnostics\` (boolean): Return inline LSP diagnostics after the edit
+Note: Modes 5 and 6 are options on mode 4 (find/replace) — they require \`oldString\`.
 
 **Behavior:**
 - Backs up files before editing (recoverable via aft_safety undo)
 - Auto-formats using project formatter if configured
 - Tree-sitter syntax validation on all edits
-- Symbol replace includes decorators, attributes, and doc comments in range`;
-function createEditTool(ctx) {
+- Symbol replace includes decorators, attributes, and doc comments in range
+- LSP error-level diagnostics are returned automatically after non-dry-run edits
+
+Returns: JSON string for the selected edit mode. Dry runs return diff data; non-dry-run edits may append inline LSP error lines.
+
+Common response fields: success (boolean), diff (object with before/after), backup_id (string), syntax_valid (boolean). Exact fields vary by mode.`;
+    // Note: The Returns section intentionally stays high-level because per-mode JSON shapes
+    // vary by Rust command and documenting each would bloat the description for minimal gain.
+    // Agents can parse the JSON response generically — key fields include 'success' and 'diff'.
+}
+function createEditTool(ctx, writeToolName = "write") {
     return {
-        description: EDIT_DESCRIPTION,
+        description: getEditDescription(writeToolName),
         args: {
-            filePath: z.string().optional(),
-            match: z.string().optional(),
-            replacement: z.string().optional(),
-            replace_all: z.boolean().optional(),
-            occurrence: z.number().optional(),
-            symbol: z.string().optional(),
-            content: z.string().optional(),
-            edits: z.array(z.record(z.string(), z.unknown())).optional(),
-            operations: z.array(z.record(z.string(), z.unknown())).optional(),
-            dry_run: z.boolean().optional(),
-            diagnostics: z.boolean().optional(),
+            filePath: z
+                .string()
+                .optional()
+                .describe("Path to the file to edit (absolute or relative to project root). Required for all modes except 'operations' multi-file transactions"),
+            oldString: z.string().optional().describe("Text to find (exact match, with fuzzy fallback)"),
+            newString: z
+                .string()
+                .optional()
+                .describe("Text to replace with (omit or set to empty string to delete the matched text)"),
+            replaceAll: z.boolean().optional().describe("Replace all occurrences"),
+            occurrence: z
+                .number()
+                .optional()
+                .describe("0-indexed occurrence to replace when multiple matches exist"),
+            symbol: z.string().optional().describe("Named symbol to replace (function, class, type)"),
+            content: z.string().optional().describe("New content for symbol replace or file write"),
+            edits: z
+                .array(z.record(z.string(), z.unknown()))
+                .optional()
+                .describe("Batch edits — array of { oldString: string, newString: string } or { startLine: number (1-based), endLine: number (1-based, inclusive), content: string }"),
+            operations: z
+                .array(z.record(z.string(), z.unknown()))
+                .optional()
+                .describe("Transaction — array of { file: string, command: 'edit_match' | 'write', match?: string, replacement?: string, content?: string } for multi-file edits with rollback. Note: uses 'file'/'match'/'replacement' (not filePath/oldString/newString)"),
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe("Preview changes without applying (returns diff, default: false)"),
         },
         execute: async (args, context) => {
             const bridge = ctx.pool.getBridge(context.directory);
@@ -440,12 +408,14 @@ function createEditTool(ctx) {
                         ? op.file
                         : path.resolve(context.directory, op.file),
                 }));
-                const data = await bridge.send("transaction", { operations: resolvedOps });
+                const params = { operations: resolvedOps };
+                params.dry_run = args.dryRun === true;
+                const data = await bridge.send("transaction", params);
                 return JSON.stringify(data);
             }
-            const file = (args.filePath ?? args.file);
+            const file = args.filePath;
             if (!file)
-                throw new Error("'file' parameter is required");
+                throw new Error("'filePath' parameter is required");
             const filePath = path.isAbsolute(file) ? file : path.resolve(context.directory, file);
             const relPath = path.relative(context.worktree, filePath);
             await context.ask({
@@ -458,48 +428,64 @@ function createEditTool(ctx) {
             // Route to appropriate Rust command
             let command;
             if (Array.isArray(args.edits)) {
-                // Batch mode
+                // Batch mode — translate camelCase to snake_case for Rust
                 command = "batch";
-                params.edits = args.edits;
+                params.edits = args.edits.map((edit) => {
+                    const translated = {};
+                    for (const [key, value] of Object.entries(edit)) {
+                        if (key === "oldString")
+                            translated.match = value;
+                        else if (key === "newString")
+                            translated.replacement = value;
+                        else if (key === "startLine")
+                            translated.line_start = value;
+                        else if (key === "endLine")
+                            translated.line_end = value;
+                        else
+                            translated[key] = value;
+                    }
+                    return translated;
+                });
             }
-            else if (typeof args.symbol === "string") {
-                // Symbol replace
+            else if (typeof args.symbol === "string" &&
+                typeof args.oldString !== "string" &&
+                args.content !== undefined) {
+                // Symbol replace — only when content is provided and oldString is NOT present
+                // (agents often pass symbol as "what to search for", not "replace whole symbol")
                 command = "edit_symbol";
                 params.symbol = args.symbol;
                 params.operation = "replace";
-                if (args.content !== undefined)
-                    params.content = args.content;
+                params.content = args.content;
             }
-            else if (typeof args.match === "string") {
-                // Find/replace mode (including glob)
+            else if (typeof args.oldString === "string") {
+                // Find/replace mode — default newString to "" (deletion) if not provided
                 command = "edit_match";
-                params.match = args.match;
-                if (args.replacement !== undefined)
-                    params.replacement = args.replacement;
-                if (args.replace_all !== undefined)
-                    params.replace_all = args.replace_all;
+                params.match = args.oldString;
+                params.replacement = args.newString ?? "";
+                if (args.replaceAll !== undefined)
+                    params.replace_all = args.replaceAll;
                 if (args.occurrence !== undefined)
                     params.occurrence = args.occurrence;
             }
             else if (typeof args.content === "string") {
-                // Write mode (full file content)
+                // Write mode
                 command = "write";
                 params.content = args.content;
                 params.create_dirs = true;
             }
             else {
-                throw new Error("Provide 'match' + 'replacement', 'symbol' + 'content', 'edits' array, or 'content' for write");
+                throw new Error("Provide 'oldString' + 'newString', 'symbol' + 'content', 'edits' array, or 'content' for write");
             }
-            if (args.dry_run)
+            if (args.dryRun)
                 params.dry_run = true;
-            if (args.diagnostics)
+            if (!args.dryRun)
                 params.diagnostics = true;
             // Request diff from Rust for UI metadata (avoids extra file reads in TS)
-            if (!args.dry_run)
+            if (!args.dryRun)
                 params.include_diff = true;
             const data = await bridge.send(command, params);
             // Store metadata for tool.execute.after hook (fromPlugin overwrites context.metadata)
-            if (!args.dry_run && data.ok && data.diff) {
+            if (!args.dryRun && data.success && data.diff) {
                 const diff = data.diff;
                 const callID = getCallID(context);
                 if (callID) {
@@ -522,7 +508,19 @@ function createEditTool(ctx) {
                     });
                 }
             }
-            return JSON.stringify(data);
+            let result = JSON.stringify(data);
+            // Append inline diagnostics to output (matching write tool pattern)
+            if (!args.dryRun) {
+                const diags = data.lsp_diagnostics;
+                if (diags && diags.length > 0) {
+                    const errors = diags.filter((d) => d.severity === "error");
+                    if (errors.length > 0) {
+                        const diagLines = errors.map((d) => `  Line ${d.line}: ${d.message}`).join("\n");
+                        result += `\n\nLSP errors detected, please fix:\n${diagLines}`;
+                    }
+                }
+            }
+            return result;
         },
     };
 }
@@ -544,6 +542,11 @@ Uses the opencode patch format with \`*** Begin Patch\` / \`*** End Patch\` mark
 -old line to remove
 +new line to add
  context line (unchanged, prefixed with space)
+*** Update File: path/to/old-name.ts
+*** Move to: path/to/new-name.ts
+@@ import { foo }
+-import { foo } from './old'
++import { foo } from './new'
 *** Delete File: path/to/obsolete-file.ts
 *** End Patch
 \`\`\`
@@ -560,23 +563,24 @@ Uses the opencode patch format with \`*** Begin Patch\` / \`*** End Patch\` mark
 - \`+line\` — Add this line
 - \` line\` — Context line (space prefix), appears in both old and new
 
-**Parameters:**
-- \`patch\` (string, required): The full patch text including Begin/End markers
-
 **Behavior:**
-- All file changes are applied atomically — if any file fails, all changes are rolled back
+- All file changes are applied with checkpoint-based rollback — if any file fails, previous changes are rolled back (best-effort)
 - Files are backed up before modification
 - Parent directories are created automatically for new files
-- Fuzzy matching for context anchors (handles whitespace and Unicode differences)`;
+- Fuzzy matching for context anchors (handles whitespace and Unicode differences)
+
+Returns: Status message string listing created, updated, moved, deleted, or failed file operations. May include inline LSP errors if type errors are introduced by the patch.`;
 function createApplyPatchTool(ctx) {
     return {
         description: APPLY_PATCH_DESCRIPTION,
         args: {
-            patch: z.string(),
+            patchText: z.string().describe("The full patch text including Begin/End markers"),
         },
         execute: async (args, context) => {
             const bridge = ctx.pool.getBridge(context.directory);
-            const patchText = args.patch;
+            const patchText = args.patchText;
+            if (!patchText)
+                throw new Error("'patchText' is required");
             // Parse the patch
             let hunks;
             try {
@@ -596,53 +600,138 @@ function createApplyPatchTool(ctx) {
                 always: ["*"],
                 metadata: {},
             });
-            // Process each hunk
+            // Checkpoint all affected files for atomic rollback
+            const checkpointName = `apply_patch_${Date.now()}`;
+            try {
+                await bridge.send("checkpoint", {
+                    name: checkpointName,
+                    files: allPaths.map((p) => path.resolve(context.directory, p)),
+                });
+            }
+            catch {
+                // Checkpoint failure is non-fatal — proceed without rollback protection
+            }
+            // Process each hunk, track diffs for metadata
             const results = [];
+            let combinedBefore = "";
+            let combinedAfter = "";
+            let patchFailed = false;
             for (const hunk of hunks) {
                 const filePath = path.resolve(context.directory, hunk.path);
                 switch (hunk.type) {
                     case "add": {
-                        await bridge.send("write", {
-                            file: filePath,
-                            content: hunk.contents.endsWith("\n") ? hunk.contents : `${hunk.contents}\n`,
-                            create_dirs: true,
-                        });
-                        results.push(`Created ${hunk.path}`);
+                        try {
+                            await bridge.send("write", {
+                                file: filePath,
+                                content: hunk.contents.endsWith("\n") ? hunk.contents : `${hunk.contents}\n`,
+                                create_dirs: true,
+                                diagnostics: true,
+                            });
+                            combinedAfter += hunk.contents;
+                            results.push(`Created ${hunk.path}`);
+                        }
+                        catch (e) {
+                            patchFailed = true;
+                            results.push(`Failed to create ${hunk.path}: ${e instanceof Error ? e.message : e}`);
+                        }
                         break;
                     }
                     case "delete": {
                         try {
-                            await fs.promises.unlink(filePath);
+                            const before = await fs.promises.readFile(filePath, "utf-8").catch(() => "");
+                            await bridge.send("delete_file", { file: filePath });
+                            combinedBefore += before;
                             results.push(`Deleted ${hunk.path}`);
                         }
                         catch (e) {
+                            patchFailed = true;
                             results.push(`Failed to delete ${hunk.path}: ${e instanceof Error ? e.message : e}`);
                         }
                         break;
                     }
                     case "update": {
-                        // Read original, apply chunks, write back
-                        const original = await fs.promises.readFile(filePath, "utf-8");
-                        const newContent = applyUpdateChunks(original, filePath, hunk.chunks);
-                        const targetPath = hunk.move_path
-                            ? path.resolve(context.directory, hunk.move_path)
-                            : filePath;
-                        await bridge.send("write", {
-                            file: targetPath,
-                            content: newContent,
-                            create_dirs: true,
-                        });
-                        if (hunk.move_path) {
-                            await fs.promises.unlink(filePath);
-                            results.push(`Updated and moved ${hunk.path} → ${hunk.move_path}`);
+                        try {
+                            // Read original, apply chunks, write back
+                            const original = await fs.promises.readFile(filePath, "utf-8");
+                            const newContent = applyUpdateChunks(original, filePath, hunk.chunks);
+                            const targetPath = hunk.move_path
+                                ? path.resolve(context.directory, hunk.move_path)
+                                : filePath;
+                            const writeResult = await bridge.send("write", {
+                                file: targetPath,
+                                content: newContent,
+                                create_dirs: true,
+                                diagnostics: true,
+                            });
+                            // Collect diagnostics from this file
+                            const diags = writeResult.lsp_diagnostics;
+                            if (diags && diags.length > 0) {
+                                const errors = diags.filter((d) => d.severity === "error");
+                                if (errors.length > 0) {
+                                    const relPath = path.relative(context.worktree, targetPath);
+                                    const diagLines = errors.map((d) => `  Line ${d.line}: ${d.message}`).join("\n");
+                                    results.push(`\nLSP errors detected in ${relPath}, please fix:\n${diagLines}`);
+                                }
+                            }
+                            // Track diff for metadata
+                            combinedBefore += original;
+                            combinedAfter += newContent;
+                            if (hunk.move_path) {
+                                await bridge.send("delete_file", { file: filePath });
+                                results.push(`Updated and moved ${hunk.path} → ${hunk.move_path}`);
+                            }
+                            else {
+                                results.push(`Updated ${hunk.path}`);
+                            }
                         }
-                        else {
-                            results.push(`Updated ${hunk.path}`);
+                        catch (e) {
+                            patchFailed = true;
+                            results.push(`Failed to update ${hunk.path}: ${e instanceof Error ? e.message : e}`);
+                            break;
                         }
                         break;
                     }
                 }
             }
+            // On failure, restore checkpoint to undo partial changes
+            if (patchFailed) {
+                try {
+                    await bridge.send("restore_checkpoint", { name: checkpointName });
+                    results.push("Patch failed — restored files to pre-patch state.");
+                }
+                catch {
+                    results.push("Patch failed — checkpoint restore also failed, files may be inconsistent.");
+                }
+                return results.join("\n");
+            }
+            // Store metadata for tool.execute.after hook (match opencode built-in format)
+            const callID = getCallID(context);
+            if (callID) {
+                // Build per-file metadata matching opencode's files array
+                const files = hunks.map((h) => {
+                    const relPath = path.relative(context.worktree, path.resolve(context.directory, h.path));
+                    return {
+                        filePath: path.resolve(context.directory, h.path),
+                        relativePath: relPath,
+                        type: h.type,
+                    };
+                });
+                // Build title matching built-in: "Success. Updated the following files:\nM path/to/file.ts"
+                const fileList = files
+                    .map((f) => {
+                    const prefix = f.type === "add" ? "A" : f.type === "delete" ? "D" : "M";
+                    return `${prefix} ${f.relativePath}`;
+                })
+                    .join("\n");
+                const title = `Success. Updated the following files:\n${fileList}`;
+                storeToolMetadata(context.sessionID, callID, {
+                    title,
+                    metadata: {
+                        diff: buildUnifiedDiff(files.length === 1 ? files[0].filePath : "patch", combinedBefore, combinedAfter),
+                        files,
+                    },
+                });
+            }
             return results.join("\n");
         },
     };
@@ -651,21 +740,21 @@ function createApplyPatchTool(ctx) {
 // Delete
 // ---------------------------------------------------------------------------
 const DELETE_DESCRIPTION = "Delete a file with backup (recoverable via aft_safety undo).\n\n" +
-    "Parameters:\n" +
-    "- file (string, required): Path to file to delete. Relative paths resolved from project root.\n\n" +
     "Returns: { file, deleted, backup_id } on success.\n" +
     "The file content is backed up before deletion — use aft_safety undo to recover if needed.";
 function createDeleteTool(ctx) {
     return {
         description: DELETE_DESCRIPTION,
         args: {
-            file: z.string(),
+            filePath: z
+                .string()
+                .describe("Path to file to delete (absolute or relative to project root)"),
         },
         execute: async (args, context) => {
             const bridge = ctx.pool.getBridge(context.directory);
-            const filePath = path.isAbsolute(args.file)
-                ? args.file
-                : path.resolve(context.directory, args.file);
+            const filePath = path.isAbsolute(args.filePath)
+                ? args.filePath
+                : path.resolve(context.directory, args.filePath);
             await context.ask({
                 permission: "edit",
                 patterns: [filePath],
@@ -681,24 +770,26 @@ function createDeleteTool(ctx) {
 // Move / Rename
 // ---------------------------------------------------------------------------
 const MOVE_DESCRIPTION = "Move or rename a file with backup (recoverable via aft_safety undo).\n\n" +
-    "Parameters:\n" +
-    "- file (string, required): Source file path to move.\n" +
-    "- destination (string, required): Destination file path.\n\n" +
     "Creates parent directories for destination automatically.\n" +
     "Falls back to copy+delete for cross-filesystem moves.\n" +
-    "Returns: { file, destination, moved, backup_id } on success.";
+    "Returns: { file, destination, moved, backup_id } on success.\n\n" +
+    "Note: This moves/renames files at the OS level. To move a code symbol (function, class) to another file while updating all imports, use aft_refactor with op='move' instead.";
 function createMoveTool(ctx) {
     return {
         description: MOVE_DESCRIPTION,
         args: {
-            file: z.string(),
-            destination: z.string(),
+            filePath: z
+                .string()
+                .describe("Source file path to move (absolute or relative to project root)"),
+            destination: z
+                .string()
+                .describe("Destination file path (absolute or relative to project root)"),
         },
         execute: async (args, context) => {
             const bridge = ctx.pool.getBridge(context.directory);
-            const filePath = path.isAbsolute(args.file)
-                ? args.file
-                : path.resolve(context.directory, args.file);
+            const filePath = path.isAbsolute(args.filePath)
+                ? args.filePath
+                : path.resolve(context.directory, args.filePath);
             const destPath = path.isAbsolute(args.destination)
                 ? args.destination
                 : path.resolve(context.directory, args.destination);
@@ -726,8 +817,8 @@ function createMoveTool(ctx) {
 export function hoistedTools(ctx) {
     return {
         read: createReadTool(ctx),
-        write: createWriteTool(ctx),
-        edit: createEditTool(ctx),
+        write: createWriteTool(ctx, "edit"),
+        edit: createEditTool(ctx, "write"),
         apply_patch: createApplyPatchTool(ctx),
         aft_delete: createDeleteTool(ctx),
         aft_move: createMoveTool(ctx),
@@ -737,10 +828,22 @@ export function hoistedTools(ctx) {
  * Returns the same tools with aft_ prefix (for when hoisting is disabled).
  */
 export function aftPrefixedTools(ctx) {
+    const aftEditTool = createEditTool(ctx, "aft_write");
     return {
         aft_read: createReadTool(ctx),
-        aft_write: createWriteTool(ctx),
-        aft_edit: createEditTool(ctx),
+        aft_write: createWriteTool(ctx, "aft_edit"),
+        aft_edit: {
+            ...aftEditTool,
+            execute: async (args, context) => {
+                const argRecord = args;
+                const normalizedArgs = argRecord.mode !== undefined &&
+                    argRecord.filePath === undefined &&
+                    typeof argRecord.file === "string"
+                    ? { ...argRecord, filePath: argRecord.file }
+                    : argRecord;
+                return aftEditTool.execute(normalizedArgs, context);
+            },
+        },
         aft_apply_patch: createApplyPatchTool(ctx),
         aft_delete: createDeleteTool(ctx),
         aft_move: createMoveTool(ctx),