@cortexkit/aft-opencode 0.3.0 → 0.4.1

package/dist/tools/reading.js

@@ -1,40 +1,219 @@
+import { readdir } from "node:fs/promises";
+import { extname, join, resolve } from "node:path";
 import { tool } from "@opencode-ai/plugin";
+/** File extensions that aft_outline supports via tree-sitter or markdown parser */
+const OUTLINE_EXTENSIONS = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".rs",
+    ".go",
+    ".py",
+    ".rb",
+    ".c",
+    ".cpp",
+    ".h",
+    ".hpp",
+    ".cs",
+    ".java",
+    ".kt",
+    ".scala",
+    ".swift",
+    ".lua",
+    ".ex",
+    ".exs",
+    ".hs",
+    ".sol",
+    ".nix",
+    ".md",
+    ".mdx",
+    ".css",
+    ".html",
+    ".json",
+    ".yaml",
+    ".yml",
+    ".sh",
+    ".bash",
+]);
 const z = tool.schema;
 /**
- * Tool definitions for code reading commands: outline only.
- * The zoom/read functionality has been merged into the hoisted `read` tool.
+ * Tool definitions for code reading commands: outline + zoom.
  */
 export function readingTools(ctx) {
     return {
         aft_outline: {
-            description: "Get a structural outline of a source file — lists all top-level symbols with their kind, name, line range, and visibility. Use this to understand file structure before editing. " +
-                "Supports single file (via 'file') or multiple files in one call (via 'files' array).\n" +
+            description: "Get a structural outline of a source file, multiple files, or an entire directory — lists all top-level symbols with their kind, name, line range, and visibility. Use this to understand file structure before editing.\n" +
                 "Each entry includes 'name', 'kind' (function/class/struct/heading/etc), 'range', 'signature', and 'members' (nested children like methods in classes or sub-headings in markdown).\n" +
                 "For Markdown files (.md, .mdx): returns heading hierarchy — h1/h2/h3 as nested symbols with section ranges covering all content until the next same-level heading.\n\n" +
-                "Parameters:\n" +
-                "- file (string, optional): Path to a single file to outline (relative to project root or absolute)\n" +
-                "- files (string[], optional): Array of file paths to outline in one call — returns per-file results\n\n" +
-                "Provide either 'file' or 'files', not both. Use 'files' to batch multiple outlines in one tool call.",
+                "Provide 'filePath', 'files', or 'directory'. Priority: directory > files > filePath. If multiple provided, highest-priority wins.\n" +
+                "Supported languages: TypeScript, JavaScript, TSX, Python, Rust, Go, Ruby, C, C++, C#, Java, Kotlin, Scala, Swift, Lua, Elixir, Haskell, Solidity, Nix, Markdown, CSS, HTML, JSON, YAML, Bash.\n" +
+                "Directory mode skips commonly ignored directories (node_modules, .git, dist, build, target, __pycache__, venv, vendor, coverage, etc.) and dot-prefixed directories.\n\n" +
+                "Returns: Single file { entries: [{ name, kind, range, signature?, exported, members }] }. Multi-file/directory { results: [{ file, ok, entries? }] }.",
             args: {
-                file: z
+                filePath: z
                     .string()
                     .optional()
-                    .describe("Path to a single source file to outline (relative to project root or absolute)"),
+                    .describe("Path to a single file to outline (ignored if 'files' or 'directory' is also provided)"),
                 files: z
                     .array(z.string())
                     .optional()
-                    .describe("Array of file paths to outline in one call — returns per-file results"),
+                    .describe("Array of file paths to outline in one call (ignored if 'directory' is also provided)"),
+                // The 200-file cap is intentionally only in .describe() — not in the main description —
+                // because it's a parameter-level detail. The cap is silent (no warning on truncation).
+                directory: z
+                    .string()
+                    .optional()
+                    .describe("Path to a directory — outlines all source files under it recursively (capped at 200 files, takes priority over 'filePath' and 'files')"),
             },
             execute: async (args, context) => {
                 const bridge = ctx.pool.getBridge(context.directory);
+                const filesArg = Array.isArray(args.files) ? args.files : undefined;
+                if (!args.filePath && !filesArg?.length && !args.directory) {
+                    throw new Error("Provide exactly one of 'filePath', 'files', or 'directory'");
+                }
+                // Directory mode: discover source files recursively and batch outline
+                if (typeof args.directory === "string") {
+                    const dirPath = resolve(context.directory, args.directory);
+                    const files = await discoverSourceFiles(dirPath);
+                    if (files.length === 0) {
+                        return JSON.stringify({
+                            success: false,
+                            message: `No source files found under ${args.directory}`,
+                        });
+                    }
+                    const response = await bridge.send("outline", { files });
+                    return JSON.stringify(response);
+                }
                 if (Array.isArray(args.files) && args.files.length > 0) {
                     const response = await bridge.send("outline", { files: args.files });
                     return JSON.stringify(response);
                 }
-                const response = await bridge.send("outline", { file: args.file });
+                const response = await bridge.send("outline", { file: args.filePath });
                 return JSON.stringify(response);
             },
         },
+        aft_zoom: {
+            description: `Inspect code symbols with call-graph annotations. Returns the full source of named symbols with what they call and what calls them.
+
+Use this when you need to understand a specific function, class, or type in detail — not for reading entire files (use read for that).
+
+**Modes:**
+
+1. **Inspect symbol** — pass filePath + symbol
+   Returns full source + call graph annotations.
+   Example: { "filePath": "src/app.ts", "symbol": "handleRequest" }
+
+2. **Inspect multiple symbols** — pass filePath + symbols array
+   Returns multiple symbols in one call.
+   Example: { "filePath": "src/app.ts", "symbols": ["Config", "createApp"] }
+
+3. **Read line range with context** — pass filePath + startLine + endLine
+   Returns lines with context_before and context_after.
+   Example: { "filePath": "src/app.ts", "startLine": 50, "endLine": 100 }
+
+For Markdown files, use heading text as symbol name (e.g., symbol: "Architecture").
+
+Mode priority: symbols array > single symbol > line range.
+
+Returns: Symbol mode { name, kind, range, content, context_before, context_after, annotations: { calls_out, called_by } }. Multi-symbol mode returns an array of these. Line-range mode returns { content, context_before, context_after, start_line, end_line }.`,
+            args: {
+                filePath: z.string().describe("Path to file (absolute or relative to project root)"),
+                symbol: z.string().optional().describe("Name of a single symbol to inspect"),
+                symbols: z
+                    .array(z.string())
+                    .optional()
+                    .describe("Array of symbol names to inspect in one call"),
+                startLine: z.number().optional().describe("1-based start line for line-range mode"),
+                endLine: z
+                    .number()
+                    .optional()
+                    .describe("1-based end line for line-range mode (inclusive, required with startLine)"),
+                contextLines: z
+                    .number()
+                    .optional()
+                    .describe("Lines of context before/after the requested range or symbol (default: 3)"),
+            },
+            execute: async (args, context) => {
+                const bridge = ctx.pool.getBridge(context.directory);
+                const file = args.filePath;
+                // Multi-symbol mode: make separate zoom calls in parallel and combine results
+                if (Array.isArray(args.symbols) && args.symbols.length > 0) {
+                    const results = await Promise.all(args.symbols.map((sym) => {
+                        const params = { file, symbol: sym };
+                        if (args.contextLines !== undefined)
+                            params.context_lines = args.contextLines;
+                        return bridge.send("zoom", params);
+                    }));
+                    return JSON.stringify(results);
+                }
+                // Single symbol or line-range mode
+                const params = { file };
+                if (typeof args.symbol === "string")
+                    params.symbol = args.symbol;
+                if (args.startLine !== undefined)
+                    params.start_line = args.startLine;
+                if (args.endLine !== undefined)
+                    params.end_line = args.endLine;
+                if (args.contextLines !== undefined)
+                    params.context_lines = args.contextLines;
+                const data = await bridge.send("zoom", params);
+                return JSON.stringify(data);
+            },
+        },
     };
 }
+/** Recursively discover source files under a directory, skipping common noise directories */
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "out",
+    ".next",
+    ".nuxt",
+    "target",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "vendor",
+    ".turbo",
+    "coverage",
+    ".nyc_output",
+    ".cache",
+]);
+async function discoverSourceFiles(dir, maxFiles = 200) {
+    const files = [];
+    async function walk(current) {
+        if (files.length >= maxFiles)
+            return;
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            return; // permission denied, not a directory, etc.
+        }
+        for (const entry of entries) {
+            if (files.length >= maxFiles)
+                return;
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) {
+                    await walk(join(current, entry.name));
+                }
+            }
+            else if (entry.isFile()) {
+                const ext = extname(entry.name).toLowerCase();
+                if (OUTLINE_EXTENSIONS.has(ext)) {
+                    files.push(join(current, entry.name));
+                }
+            }
+        }
+    }
+    await walk(dir);
+    files.sort();
+    return files;
+}
 //# sourceMappingURL=reading.js.map

package/dist/tools/reading.js.map

@@ -1 +1 @@
-{"version":3,"file":"reading.js","sourceRoot":"","sources":["../../src/tools/reading.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAG3C,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;AAEtB;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAkB;IAC7C,OAAO;QACL,WAAW,EAAE;YACX,WAAW,EACT,mLAAmL;gBACnL,wFAAwF;gBACxF,sLAAsL;gBACtL,wKAAwK;gBACxK,eAAe;gBACf,sGAAsG;gBACtG,yGAAyG;gBACzG,sGAAsG;YACxG,IAAI,EAAE;gBACJ,IAAI,EAAE,CAAC;qBACJ,MAAM,EAAE;qBACR,QAAQ,EAAE;qBACV,QAAQ,CACP,gFAAgF,CACjF;gBACH,KAAK,EAAE,CAAC;qBACL,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;qBACjB,QAAQ,EAAE;qBACV,QAAQ,CAAC,uEAAuE,CAAC;aACrF;YACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAmB,EAAE;gBAChD,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;gBACrD,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACvD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;oBACrE,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;gBAClC,CAAC;gBACD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;gBACnE,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YAClC,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"reading.js","sourceRoot":"","sources":["../../src/tools/reading.ts"],"names":[],"mappings":"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"}

package/dist/tools/refactoring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"refactoring.d.ts","sourceRoot":"","sources":["../../src/tools/refactoring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAoFnF"}
+{"version":3,"file":"refactoring.d.ts","sourceRoot":"","sources":["../../src/tools/refactoring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAYjD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CA4HnF"}

package/dist/tools/refactoring.js

@@ -1,5 +1,6 @@
 import { tool } from "@opencode-ai/plugin";
 import { queryLspHints } from "../lsp.js";
+import { askEditPermission, permissionDeniedResponse, resolveAbsolutePath, resolveRelativePattern, resolveRelativePatterns, workspacePattern, } from "./permissions.js";
 const z = tool.schema;
 /**
  * Tool definitions for refactoring commands: move_symbol, extract_function, inline_symbol.
@@ -9,59 +10,96 @@ export function refactoringTools(ctx) {
         aft_refactor: {
             description: "Workspace-wide refactoring operations that update imports and references across files.\n\n" +
                 "Ops:\n" +
-                "- 'move': Move a symbol to another file, updating all imports workspace-wide. Requires 'symbol', 'destination'. Creates a checkpoint before mutating.\n" +
-                "- 'extract': Extract a line range into a new function with auto-detected parameters. Requires 'name', 'start_line', 'end_line' (all 1-based). Supports TS/JS/TSX and Python.\n" +
-                "- 'inline': Replace a function call with the function's body, substituting args for params. Requires 'symbol', 'call_site_line' (1-based). Validates single-return constraint.\n\n" +
-                "Parameters:\n" +
-                "- op (enum, required): 'move' | 'extract' | 'inline'\n" +
-                "- file (string, required): Path to the source file\n" +
-                "- symbol (string, optional): Symbol name — required for 'move' (symbol to move) and 'inline' (function to inline)\n" +
-                "- destination (string, optional): Target file path for 'move' op — created if it doesn't exist\n" +
-                "- scope (string, optional): Disambiguation scope for 'move' when multiple symbols share the same name\n" +
-                "- name (string, optional): New function name for 'extract' op\n" +
-                "- start_line (number, optional): 1-based start line of the range to extract ('extract' op)\n" +
-                "- end_line (number, optional): 1-based end line of the range to extract, exclusive ('extract' op)\n" +
-                "- call_site_line (number, optional): 1-based line where the call expression is located ('inline' op)\n" +
-                "- dry_run (boolean, optional): Preview changes as diff without modifying files\n\n" +
-                "All ops need 'file'. Use dry_run to preview before applying.",
+                "- 'move': Move a top-level symbol to another file, updating all imports workspace-wide. Requires 'symbol', 'destination'. Creates a checkpoint before mutating. Only works on top-level exports (not nested functions or class methods).\n" +
+                "   Note: This moves code symbols between files. To rename/move an entire file, use aft_move instead.\n" +
+                "- 'extract': Extract a line range into a new function with auto-detected parameters. Requires 'name', 'startLine', 'endLine' (1-based, both inclusive). Supports TS/JS/TSX and Python.\n" +
+                "- 'inline': Replace a function call with the function's body, substituting args for params. Requires 'symbol', 'callSiteLine' (1-based). Validates single-return constraint.\n\n" +
+                "Each op requires specific parameters — see parameter descriptions for requirements.\n\n" +
+                "All ops need 'filePath'. Use dryRun to preview before applying.\n\n" +
+                "Returns: move dry-run { ok, dry_run, diffs }; move apply { ok, files_modified, consumers_updated, checkpoint_name, results }. extract returns { file, name, parameters, return_type, syntax_valid, formatted, ... }. inline returns { file, symbol, call_context, substitutions, conflicts, syntax_valid, formatted, ... }.",
+            // Parameters are Zod-optional because different ops need different subsets.
+            // Runtime guards below validate per-op requirements and give clear errors.
             args: {
                 op: z.enum(["move", "extract", "inline"]).describe("Refactoring operation"),
-                file: z.string().describe("Path to the source file"),
+                filePath: z
+                    .string()
+                    .describe("Path to the source file (absolute or relative to project root)"),
                 symbol: z
                     .string()
                     .optional()
-                    .describe("Symbol name (move: symbol to move, inline: function to inline)"),
+                    .describe("Symbol name — required for 'move' and 'inline' ops"),
                 // move
-                destination: z
-                    .string()
-                    .optional()
-                    .describe("Destination file path (move op — will be created if needed)"),
+                destination: z.string().optional().describe("Target file path — required for 'move' op"),
+                // scope disambiguates overloaded top-level names, NOT nested symbols.
+                // "Only works on top-level exports" in the description is correct — scope selects
+                // among multiple top-level symbols that share a name, not class methods.
                 scope: z
                     .string()
                     .optional()
-                    .describe("Disambiguation scope when multiple symbols share the same name (move op)"),
+                    .describe("Disambiguation scope for 'move' op — when multiple top-level symbols share the same name, specify the containing scope to disambiguate (e.g. 'MyClass'). Does NOT enable access to nested symbols or class methods."),
                 // extract
-                name: z.string().optional().describe("Name for the new extracted function (extract op)"),
-                start_line: z.number().describe("First line of range to extract, 1-based (extract op)"),
-                end_line: z.number().describe("Last line of range, exclusive, 1-based (extract op)"),
+                name: z.string().optional().describe("New function name — required for 'extract' op"),
+                startLine: z.number().optional().describe("1-based start line — required for 'extract' op"),
+                // endLine is inclusive from the agent's perspective; the execute function adds +1
+                // because the Rust backend expects exclusive end. This is intentional — do not document.
+                endLine: z
+                    .number()
+                    .optional()
+                    .describe("1-based end line (inclusive) — required for 'extract' op"),
                 // inline
-                call_site_line: z
+                callSiteLine: z
                     .number()
-                    .describe("Line where the call expression is located, 1-based (inline op)"),
+                    .optional()
+                    .describe("1-based call site line — required for 'inline' op"),
                 // common
-                dry_run: z.boolean().optional().describe("Preview as diff without modifying files"),
+                dryRun: z
+                    .boolean()
+                    .optional()
+                    .describe("Preview changes as diff without modifying files (default: false)"),
             },
             execute: async (args, context) => {
                 const bridge = ctx.pool.getBridge(context.directory);
                 const op = args.op;
+                const isDryRun = args.dryRun === true;
+                if ((op === "move" || op === "inline") && typeof args.symbol !== "string") {
+                    throw new Error(`'symbol' is required for '${op}' op`);
+                }
+                if (op === "move" && typeof args.destination !== "string") {
+                    throw new Error("'destination' is required for 'move' op");
+                }
+                if (op === "extract") {
+                    if (typeof args.name !== "string")
+                        throw new Error("'name' is required for 'extract' op");
+                    if (args.startLine === undefined)
+                        throw new Error("'startLine' is required for 'extract' op");
+                    if (args.endLine === undefined)
+                        throw new Error("'endLine' is required for 'extract' op");
+                }
+                if (op === "inline" && args.callSiteLine === undefined) {
+                    throw new Error("'callSiteLine' is required for 'inline' op");
+                }
+                if (!isDryRun) {
+                    const filePath = resolveAbsolutePath(context, args.filePath);
+                    const patterns = op === "move"
+                        ? resolveRelativePatterns(context, [
+                            workspacePattern(context),
+                            args.filePath,
+                            ...(typeof args.destination === "string" ? [args.destination] : []),
+                        ])
+                        : [resolveRelativePattern(context, args.filePath)];
+                    const metadata = patterns.length === 1 ? { filepath: filePath } : {};
+                    const permissionError = await askEditPermission(context, patterns, metadata);
+                    if (permissionError)
+                        return permissionDeniedResponse(permissionError);
+                }
                 const commandMap = {
                     move: "move_symbol",
                     extract: "extract_function",
                     inline: "inline_symbol",
                 };
-                const params = { file: args.file };
-                if (args.dry_run !== undefined)
-                    params.dry_run = args.dry_run;
+                const params = { file: args.filePath };
+                if (args.dryRun !== undefined)
+                    params.dry_run = args.dryRun;
                 switch (op) {
                     case "move":
                         params.symbol = args.symbol;
@@ -71,12 +109,12 @@ export function refactoringTools(ctx) {
                         break;
                     case "extract":
                         params.name = args.name;
-                        params.start_line = Number(args.start_line);
-                        params.end_line = Number(args.end_line);
+                        params.start_line = Number(args.startLine);
+                        params.end_line = Number(args.endLine) + 1; // Agent uses inclusive, Rust expects exclusive
                         break;
                     case "inline":
                         params.symbol = args.symbol;
-                        params.call_site_line = Number(args.call_site_line);
+                        params.call_site_line = Number(args.callSiteLine);
                         break;
                 }
                 const hints = await queryLspHints(ctx.client, (args.symbol ?? args.name));

package/dist/tools/refactoring.js.map

@@ -1 +1 @@
-{"version":3,"file":"refactoring.js","sourceRoot":"","sources":["../../src/tools/refactoring.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"refactoring.js","sourceRoot":"","sources":["../../src/tools/refactoring.ts"],"names":[],"mappings":"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"}

package/dist/tools/safety.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"safety.d.ts","sourceRoot":"","sources":["../../src/tools/safety.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAkD9E"}
+{"version":3,"file":"safety.d.ts","sourceRoot":"","sources":["../../src/tools/safety.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAWjD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CA6E9E"}

package/dist/tools/safety.js

@@ -1,4 +1,5 @@
 import { tool } from "@opencode-ai/plugin";
+import { askEditPermission, permissionDeniedResponse, resolveAbsolutePath, resolveRelativePattern, workspacePattern, } from "./permissions.js";
 const z = tool.schema;
 /**
  * Tool definitions for safety & recovery commands: undo, edit_history,
@@ -8,24 +9,26 @@ export function safetyTools(ctx) {
     return {
         aft_safety: {
             description: "File safety and recovery operations.\n\n" +
+                "IMPORTANT: All backups are in-memory only — lost if the AFT process restarts. Per-file undo stack is capped at 20 entries (oldest evicted).\n\n" +
                 "Ops:\n" +
-                "- 'undo': Undo the last edit to a file. Requires 'file'.\n" +
-                "- 'history': List all edit snapshots for a file. Requires 'file'.\n" +
+                "- 'undo': Undo the last edit to a file. Requires 'filePath'. Note: pops from the undo stack (irreversible, no redo). Use 'history' to inspect before undoing.\n" +
+                "- 'history': List all edit snapshots for a file. Requires 'filePath'.\n" +
                 "- 'checkpoint': Save a named snapshot of tracked files. Requires 'name'. Optional 'files' to snapshot specific files only.\n" +
                 "- 'restore': Restore files to a previously saved checkpoint. Requires 'name'.\n" +
                 "- 'list': List all available named checkpoints. No extra params needed.\n\n" +
-                "Parameters:\n" +
-                "- op (enum, required): 'undo' | 'history' | 'checkpoint' | 'restore' | 'list'\n" +
-                "- file (string, optional): File path — required for 'undo' and 'history' ops\n" +
-                "- name (string, optional): Checkpoint name — required for 'checkpoint' and 'restore' ops\n" +
-                "- files (string[], optional): Specific files to include in checkpoint (defaults to all tracked files)\n\n" +
-                "Use checkpoint before risky multi-file changes. Use undo for quick single-file rollback.\n" +
-                "Note: backups are in-memory (lost on restart). Per-file undo stack is capped at 20 entries (oldest evicted).",
+                "Each op requires specific parameters — see parameter descriptions for requirements.\n\n" +
+                "Use checkpoint before risky multi-file changes. Use undo for quick single-file rollback.\n\n" +
+                "Returns: undo { path, backup_id }. history { file, entries }. checkpoint { ok, name }. restore { ok, name }. list { checkpoints }.",
+            // Parameters are Zod-optional because different ops need different subsets.
+            // Runtime guards below validate per-op requirements and give clear errors.
             args: {
                 op: z
                     .enum(["undo", "history", "checkpoint", "restore", "list"])
                     .describe("Safety operation"),
-                file: z.string().optional().describe("File path (required for undo, history)"),
+                filePath: z
+                    .string()
+                    .optional()
+                    .describe("File path (required for undo, history). Absolute or relative to project root"),
                 name: z.string().optional().describe("Checkpoint name (required for checkpoint, restore)"),
                 files: z
                     .array(z.string())
@@ -35,6 +38,25 @@ export function safetyTools(ctx) {
             execute: async (args, context) => {
                 const bridge = ctx.pool.getBridge(context.directory);
                 const op = args.op;
+                if ((op === "undo" || op === "history") && typeof args.filePath !== "string") {
+                    throw new Error(`'filePath' is required for '${op}' op`);
+                }
+                if ((op === "checkpoint" || op === "restore") && typeof args.name !== "string") {
+                    throw new Error(`'name' is required for '${op}' op`);
+                }
+                if (op === "undo" && typeof args.filePath === "string") {
+                    const filePath = resolveAbsolutePath(context, args.filePath);
+                    const permissionError = await askEditPermission(context, [resolveRelativePattern(context, args.filePath)], { filepath: filePath });
+                    if (permissionError)
+                        return permissionDeniedResponse(permissionError);
+                }
+                if (op === "restore") {
+                    const permissionError = await askEditPermission(context, [workspacePattern(context)], {
+                        checkpoint: args.name,
+                    });
+                    if (permissionError)
+                        return permissionDeniedResponse(permissionError);
+                }
                 const commandMap = {
                     undo: "undo",
                     history: "edit_history",
@@ -43,8 +65,8 @@ export function safetyTools(ctx) {
                     list: "list_checkpoints",
                 };
                 const params = {};
-                if (args.file !== undefined)
-                    params.file = args.file;
+                if (args.filePath !== undefined)
+                    params.file = args.filePath;
                 if (args.name !== undefined)
                     params.name = args.name;
                 if (args.files !== undefined)

package/dist/tools/safety.js.map

@@ -1 +1 @@
-{"version":3,"file":"safety.js","sourceRoot":"","sources":["../../src/tools/safety.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAG3C,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;AAEtB;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAkB;IAC5C,OAAO;QACL,UAAU,EAAE;YACV,WAAW,EACT,0CAA0C;gBAC1C,QAAQ;gBACR,4DAA4D;gBAC5D,qEAAqE;gBACrE,8HAA8H;gBAC9H,iFAAiF;gBACjF,6EAA6E;gBAC7E,eAAe;gBACf,iFAAiF;gBACjF,gFAAgF;gBAChF,4FAA4F;gBAC5F,2GAA2G;gBAC3G,4FAA4F;gBAC5F,8GAA8G;YAChH,IAAI,EAAE;gBACJ,EAAE,EAAE,CAAC;qBACF,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;qBAC1D,QAAQ,CAAC,kBAAkB,CAAC;gBAC/B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;gBAC9E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC;gBAC1F,KAAK,EAAE,CAAC;qBACL,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;qBACjB,QAAQ,EAAE;qBACV,QAAQ,CACP,mFAAmF,CACpF;aACJ;YACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAmB,EAAE;gBAChD,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;gBACrD,MAAM,EAAE,GAAG,IAAI,CAAC,EAAY,CAAC;gBAC7B,MAAM,UAAU,GAA2B;oBACzC,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE,cAAc;oBACvB,UAAU,EAAE,YAAY;oBACxB,OAAO,EAAE,oBAAoB;oBAC7B,IAAI,EAAE,kBAAkB;iBACzB,CAAC;gBACF,MAAM,MAAM,GAA4B,EAAE,CAAC;gBAC3C,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;oBAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;gBACrD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;oBAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;gBACrD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;oBAAE,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;gBACxD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;gBAC3D,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YAClC,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"safety.js","sourceRoot":"","sources":["../../src/tools/safety.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAE3C,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;AAEtB;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAkB;IAC5C,OAAO;QACL,UAAU,EAAE;YACV,WAAW,EACT,0CAA0C;gBAC1C,iJAAiJ;gBACjJ,QAAQ;gBACR,iKAAiK;gBACjK,yEAAyE;gBACzE,8HAA8H;gBAC9H,iFAAiF;gBACjF,6EAA6E;gBAC7E,yFAAyF;gBACzF,8FAA8F;gBAC9F,oIAAoI;YACtI,4EAA4E;YAC5E,2EAA2E;YAC3E,IAAI,EAAE;gBACJ,EAAE,EAAE,CAAC;qBACF,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;qBAC1D,QAAQ,CAAC,kBAAkB,CAAC;gBAC/B,QAAQ,EAAE,CAAC;qBACR,MAAM,EAAE;qBACR,QAAQ,EAAE;qBACV,QAAQ,CAAC,8EAA8E,CAAC;gBAC3F,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC;gBAC1F,KAAK,EAAE,CAAC;qBACL,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;qBACjB,QAAQ,EAAE;qBACV,QAAQ,CACP,mFAAmF,CACpF;aACJ;YACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAmB,EAAE;gBAChD,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;gBACrD,MAAM,EAAE,GAAG,IAAI,CAAC,EAAY,CAAC;gBAE7B,IAAI,CAAC,EAAE,KAAK,MAAM,IAAI,EAAE,KAAK,SAAS,CAAC,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;oBAC7E,MAAM,IAAI,KAAK,CAAC,+BAA+B,EAAE,MAAM,CAAC,CAAC;gBAC3D,CAAC;gBACD,IAAI,CAAC,EAAE,KAAK,YAAY,IAAI,EAAE,KAAK,SAAS,CAAC,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAC/E,MAAM,IAAI,KAAK,CAAC,2BAA2B,EAAE,MAAM,CAAC,CAAC;gBACvD,CAAC;gBAED,IAAI,EAAE,KAAK,MAAM,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;oBACvD,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;oBAC7D,MAAM,eAAe,GAAG,MAAM,iBAAiB,CAC7C,OAAO,EACP,CAAC,sBAAsB,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,EAChD,EAAE,QAAQ,EAAE,QAAQ,EAAE,CACvB,CAAC;oBACF,IAAI,eAAe;wBAAE,OAAO,wBAAwB,CAAC,eAAe,CAAC,CAAC;gBACxE,CAAC;gBAED,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;oBACrB,MAAM,eAAe,GAAG,MAAM,iBAAiB,CAAC,OAAO,EAAE,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,EAAE;wBACpF,UAAU,EAAE,IAAI,CAAC,IAAI;qBACtB,CAAC,CAAC;oBACH,IAAI,eAAe;wBAAE,OAAO,wBAAwB,CAAC,eAAe,CAAC,CAAC;gBACxE,CAAC;gBAED,MAAM,UAAU,GAA2B;oBACzC,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE,cAAc;oBACvB,UAAU,EAAE,YAAY;oBACxB,OAAO,EAAE,oBAAoB;oBAC7B,IAAI,EAAE,kBAAkB;iBACzB,CAAC;gBACF,MAAM,MAAM,GAA4B,EAAE,CAAC;gBAC3C,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;oBAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC;gBAC7D,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;oBAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;gBACrD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;oBAAE,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;gBACxD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;gBAC3D,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YAClC,CAAC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/structure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"structure.d.ts","sourceRoot":"","sources":["../../src/tools/structure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAoHjF"}
+{"version":3,"file":"structure.d.ts","sourceRoot":"","sources":["../../src/tools/structure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAUjD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAkKjF"}