ysagc-agent 0.4.0 → 0.6.0

package/dist/tools.js

@@ -34,11 +34,16 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolError = void 0;
+exports.walkTree = walkTree;
+exports.globToRegex = globToRegex;
+exports.preExecute = preExecute;
+exports.postExecute = postExecute;
 exports.createToolRegistry = createToolRegistry;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const path_utils_1 = require("./path-utils");
 const security_1 = require("./security");
+const skills_1 = require("./skills");
 const executor_1 = require("./executor");
 /** Thrown when a tool invocation is invalid or unsafe. */
 class ToolError extends Error {
@@ -92,6 +97,15 @@ function requiredArray(args, key) {
     }
     return v;
 }
+function optionalBool(args, key, fallback) {
+    const v = args[key];
+    if (v === undefined || v === null)
+        return fallback;
+    if (typeof v !== 'boolean') {
+        throw new ToolError('INVALID_ARG', `"${key}" must be a boolean.`);
+    }
+    return v;
+}
 function abortIfRequested(signal) {
     if (signal?.aborted) {
         throw new ToolError('ABORTED', 'Operation was cancelled.');
@@ -116,11 +130,11 @@ function isUtf8(buf) {
         return false;
     }
 }
-function readUpTo(target, length) {
+function readUpTo(target, length, offset = 0) {
     const fd = fs.openSync(target, 'r');
     try {
         const buf = Buffer.alloc(length);
-        const bytesRead = fs.readSync(fd, buf, 0, length, 0);
+        const bytesRead = fs.readSync(fd, buf, 0, length, offset);
         return buf.subarray(0, Math.max(0, bytesRead));
     }
     finally {
@@ -143,6 +157,283 @@ function shellQuote(arg) {
     return arg;
 }
 // ---------------------------------------------------------------------------
+// directory walking / glob helpers
+// ---------------------------------------------------------------------------
+/** Heavy / generated directories that file walkers skip by default so a large
+ * dependency tree does not flood a search or glob result. */
+const DEFAULT_WALK_EXCLUDE = new Set([
+    '.git',
+    '.hg',
+    '.svn',
+    'node_modules',
+    'dist',
+    'build',
+    'out',
+    '.cache',
+    '.npm',
+    '.venv',
+    'venv',
+    'env',
+    '__pycache__',
+    '.next',
+    '.nuxt',
+    '.turbo',
+    'coverage',
+    '.idea',
+    '.vs',
+    'target',
+    '.docusaurus',
+]);
+/**
+ * Walk a directory tree depth-first, returning every file and directory as a
+ * flat list. Never follows symbolic links (which defends against root escape
+ * and symlink cycles), skips the default heavy directories, and bounds the
+ * total number of entries returned. Directory entries are guaranteed to be
+ * returned before their children.
+ */
+function walkTree(base, opts = {}) {
+    const max = opts.maxEntries ?? 5000;
+    const exclude = opts.exclude ?? DEFAULT_WALK_EXCLUDE;
+    const includeHidden = opts.includeHidden ?? false;
+    const out = [];
+    const stack = [{ rel: '', abs: base }];
+    while (stack.length) {
+        const cur = stack.pop();
+        let names;
+        try {
+            names = fs.readdirSync(cur.abs);
+        }
+        catch {
+            continue;
+        }
+        names.sort();
+        for (const name of names) {
+            if (!includeHidden && name.startsWith('.'))
+                continue;
+            if (exclude.has(name))
+                continue;
+            const rel = cur.rel ? `${cur.rel}/${name}` : name;
+            const abs = path.join(cur.abs, name);
+            let st;
+            try {
+                st = fs.lstatSync(abs);
+            }
+            catch {
+                continue;
+            }
+            if (st.isSymbolicLink())
+                continue;
+            const type = st.isDirectory() ? 'dir' : st.isFile() ? 'file' : 'other';
+            if (type === 'other')
+                continue;
+            out.push({ rel, abs, type });
+            if (out.length >= max)
+                return out;
+            if (type === 'dir')
+                stack.push({ rel, abs });
+        }
+    }
+    return out;
+}
+/** Whether a file buffer is binary (contains a NUL byte). */
+function isBinary(buf) {
+    return buf.includes(0);
+}
+/** Convert a glob pattern (`*`, `?`, `**`, and literals — no char classes)
+ * into an anchored regular expression. `**` matches zero or more path
+ * segments; `*`/`?` match within a single segment. On Windows the match is
+ * case-insensitive to mirror the filesystem. */
+function globToRegex(glob) {
+    let out = '^';
+    let i = 0;
+    const n = glob.length;
+    while (i < n) {
+        const ch = glob[i];
+        if (ch === '*') {
+            if (glob[i + 1] === '*') {
+                i += 2;
+                if (glob[i] === '/') {
+                    out += '(?:.*/)?';
+                    i += 1;
+                }
+                else {
+                    out += '.*';
+                }
+                continue;
+            }
+            out += '[^/]*';
+            i += 1;
+            continue;
+        }
+        if (ch === '?') {
+            out += '[^/]';
+            i += 1;
+            continue;
+        }
+        if ('\\.^$|()[]{}'.includes(ch)) {
+            out += '\\' + ch;
+        }
+        else {
+            out += ch;
+        }
+        i += 1;
+    }
+    out += '$';
+    return new RegExp(out, process.platform === 'win32' ? 'i' : '');
+}
+/** Tools that mutate the workspace or execute commands (blocked by read-only). */
+const WRITE_OR_COMMAND_TOOLS = new Set([
+    'write_file',
+    'edit_file',
+    'str_replace_editor',
+    'generate',
+    'run_command',
+    'git',
+    'mv',
+    'cp',
+    'delete_file',
+]);
+/** Reconstruct the shell command a command-tool intends to run, if any. */
+function commandForTool(tool, args) {
+    if (tool === 'run_command') {
+        return typeof args.cmd === 'string' ? args.cmd : undefined;
+    }
+    if (tool === 'git') {
+        if (typeof args.command === 'string' && args.command.trim() !== '') {
+            return `git ${args.command.trim()}`;
+        }
+        if (Array.isArray(args.args)) {
+            return ['git', ...args.args.map((a) => String(a))].join(' ');
+        }
+    }
+    return undefined;
+}
+/** Collect the path-bearing argument values for a tool, if any. */
+function pathArgsForTool(tool, args) {
+    const keys = ['path', 'cwd'];
+    if (tool === 'generate')
+        keys.push('name');
+    if (tool === 'mv' || tool === 'cp')
+        keys.push('source', 'destination');
+    const out = [];
+    for (const key of keys) {
+        const v = args[key];
+        if (typeof v === 'string' && v.trim() !== '')
+            out.push(v);
+    }
+    return out;
+}
+/** Default preset used when the caller did not specify one on the context. */
+const DEFAULT_PRESET = 'workspace-write';
+/** Whether the active preset permits a danger-flagged command without an
+ * approval prompt. Only the most-permissive mode allows non-critical danger
+ * commands; every other mode blocks them at the gate. */
+function permitsDangerCommand(preset, severity) {
+    return preset === 'danger-full-access' && severity !== 'critical';
+}
+/**
+ * The guarded pre-execution hook. Runs before every tool:
+ *  1. enforces the permission preset (read-only blocks writes/commands);
+ *  2. flags dangerous commands (workspace-write asks for approval, most
+ *     permissive mode only blocks critical commands, read-only blocks all);
+ *  3. canonicalises and validates every path argument (inside-root + sensitive
+ *     path check).
+ * Returns `{ ok: true }` when execution may proceed, otherwise a structured
+ * block with an error and optional `needsApproval`.
+ */
+function preExecute(ctx, tool, args) {
+    const preset = ctx.permissionPreset ?? DEFAULT_PRESET;
+    // 1) Permission preset: read-only denies anything that writes or executes.
+    if (preset === 'read-only') {
+        if (WRITE_OR_COMMAND_TOOLS.has(tool)) {
+            return {
+                ok: false,
+                error: `Tool "${tool}" is blocked in read-only mode (preset: read-only).`,
+                reason: 'read-only preset denies writes and commands',
+            };
+        }
+    }
+    // 2) Dangerous-command gate for shell tools.
+    const cmd = commandForTool(tool, args);
+    if (cmd !== undefined) {
+        const assessment = (0, security_1.isDangerCommand)(cmd);
+        if (assessment.danger) {
+            if (preset === 'danger-full-access' && assessment.severity === 'danger') {
+                // Most permissive: allow non-critical danger commands but record why.
+                // (critical severity falls through and is blocked below.)
+            }
+            else if (preset === 'workspace-write') {
+                return {
+                    ok: false,
+                    needsApproval: true,
+                    error: `Dangerous command requires approval (${assessment.severity}): ${assessment.reason}`,
+                    reason: assessment.reason,
+                };
+            }
+            else {
+                return {
+                    ok: false,
+                    error: `Blocked dangerous command (${assessment.severity}): ${assessment.reason}`,
+                    reason: assessment.reason,
+                };
+            }
+        }
+    }
+    // 3) Canonicalise + sensitive-path check for every path argument.
+    let realRoot;
+    for (const p of pathArgsForTool(tool, args)) {
+        try {
+            realRoot = realRoot ?? (0, path_utils_1.canonicalize)(ctx.root);
+            const target = (0, path_utils_1.safeResolve)(ctx.root, p, realRoot, { allowEqual: true });
+            if ((0, security_1.isSensitivePath)(target)) {
+                return {
+                    ok: false,
+                    error: `Sensitive path is blocked: ${p}`,
+                    reason: 'sensitive path',
+                };
+            }
+        }
+        catch (err) {
+            if (err instanceof path_utils_1.PathError) {
+                return { ok: false, error: err.message, reason: 'path validation failed' };
+            }
+            throw err;
+        }
+    }
+    return { ok: true };
+}
+/** Deep-mask secrets in a tool result so internal keys never leak out. */
+function maskSecretsDeep(value) {
+    if (typeof value === 'string')
+        return (0, security_1.maskSecrets)(value);
+    if (Array.isArray(value))
+        return value.map((v) => maskSecretsDeep(v));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = maskSecretsDeep(v);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * The guarded post-execution hook. Runs after every tool: masks secrets in the
+ * result and records the reason the invocation ended up here.
+ */
+function postExecute(_ctx, tool, result) {
+    if (result.result !== undefined) {
+        result.result = maskSecretsDeep(result.result);
+    }
+    if (typeof result.error === 'string') {
+        result.error = (0, security_1.maskSecrets)(result.error);
+    }
+    return {
+        ok: true,
+        reason: `tool ${tool} completed; secrets masked`,
+    };
+}
+// ---------------------------------------------------------------------------
 // executors
 // ---------------------------------------------------------------------------
 const listDir = async (ctx, args) => {
@@ -201,7 +492,11 @@ const listDir = async (ctx, args) => {
 const readFile = async (ctx, args, signal) => {
     abortIfRequested(signal);
     const targetStr = requireString(args, 'path');
-    const maxBytes = optionalInt(args, 'maxBytes', ctx.maxBytes, { min: 1, max: MAX_WRITE_BYTES });
+    const offset = optionalInt(args, 'offset', 0, { min: 0 });
+    // `length` takes precedence over the legacy `maxBytes`; if neither is given,
+    // fall back to the configured output cap.
+    const hasLength = args.length !== undefined && args.length !== null;
+    const length = optionalInt(args, hasLength ? 'length' : 'maxBytes', ctx.maxBytes, { min: 1, max: MAX_WRITE_BYTES });
     const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
     const target = (0, path_utils_1.safeResolve)(ctx.root, targetStr, realRoot);
     assertNotSensitive(target);
@@ -216,9 +511,12 @@ const readFile = async (ctx, args, signal) => {
         throw new ToolError('IS_DIR', `Path is a directory, not a file: ${targetStr}`);
     }
     const totalBytes = stat.size;
-    const readLen = Math.min(maxBytes + 1, totalBytes);
-    const buf = readUpTo(target, readLen);
-    const truncated = totalBytes > maxBytes;
+    const available = Math.max(0, totalBytes - offset);
+    // Return exactly the requested window (capped at what is available) and
+    // report `truncated` when more bytes remain beyond that window.
+    const readLen = Math.min(length, available);
+    const buf = readUpTo(target, readLen, offset);
+    const truncated = available > length;
     const bytesRead = buf.length;
     const utf8 = isUtf8(buf);
     const content = utf8 ? buf.toString('utf8') : buf.toString('hex');
@@ -228,6 +526,7 @@ const readFile = async (ctx, args, signal) => {
             path: rel(realRoot, target),
             bytesRead,
             totalBytes,
+            offset,
             truncated,
             encoding: utf8 ? 'utf8' : 'hex',
             content,
@@ -296,7 +595,7 @@ const runCommandTool = async (ctx, args, signal) => {
     const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
     const cwd = (0, path_utils_1.safeResolve)(ctx.root, cwdArg, realRoot, { allowEqual: true });
     const assessment = (0, security_1.isDangerCommand)(cmd);
-    if (assessment.danger) {
+    if (assessment.danger && !permitsDangerCommand(ctx.permissionPreset, assessment.severity)) {
         return {
             ok: false,
             error: `Blocked dangerous command (${assessment.severity}): ${assessment.reason}`,
@@ -368,7 +667,7 @@ const git = async (ctx, args, signal) => {
         throw new ToolError('INVALID_ARG', '"git" requires either "args" (array) or "command" (string).');
     }
     const assessment = (0, security_1.isDangerCommand)(cmdStr);
-    if (assessment.danger) {
+    if (assessment.danger && !permitsDangerCommand(ctx.permissionPreset, assessment.severity)) {
         return { ok: false, error: `Blocked dangerous git command (${assessment.severity}): ${assessment.reason}` };
     }
     if (ctx.mode === 'supervise') {
@@ -453,15 +752,635 @@ const generate = async (ctx, args, signal) => {
         result: { template, name, root: rel(realRoot, targetDir), files: written },
     };
 };
+// --- search (grep) ---------------------------------------------------------
+const search = async (ctx, args, signal) => {
+    abortIfRequested(signal);
+    const patternStr = requireString(args, 'pattern');
+    const targetStr = optionalString(args, 'path', '.') ?? '.';
+    const maxResults = optionalInt(args, 'maxResults', 100, { min: 1, max: 5000 });
+    const maxFileBytes = optionalInt(args, 'maxBytes', 256 * 1024, { min: 1, max: MAX_WRITE_BYTES });
+    const caseSensitive = optionalBool(args, 'caseSensitive', false);
+    const recursive = optionalBool(args, 'recursive', true);
+    let re;
+    try {
+        re = new RegExp(patternStr, caseSensitive ? 'gm' : 'gim');
+    }
+    catch {
+        throw new ToolError('INVALID_REGEX', `Invalid search pattern: ${patternStr}`);
+    }
+    const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+    const target = (0, path_utils_1.safeResolve)(ctx.root, targetStr, realRoot, { allowEqual: true });
+    assertNotSensitive(target);
+    let st;
+    try {
+        st = fs.statSync(target);
+    }
+    catch {
+        throw new ToolError('NOT_FOUND', `Path does not exist: ${targetStr}`);
+    }
+    const matches = [];
+    let count = 0;
+    const scanFile = (abs) => {
+        let mbuf;
+        try {
+            const fst = fs.statSync(abs);
+            if (fst.size > maxFileBytes)
+                return;
+            mbuf = fs.readFileSync(abs);
+        }
+        catch {
+            return;
+        }
+        if (isBinary(mbuf))
+            return;
+        const lines = mbuf.toString('utf8').split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const lineText = lines[i];
+            re.lastIndex = 0;
+            // While loop with a zero-length-match guard to avoid infinite loops.
+            for (;;) {
+                const m = re.exec(lineText);
+                if (!m)
+                    break;
+                count += 1;
+                if (matches.length < maxResults) {
+                    matches.push({ path: rel(realRoot, abs), line: i + 1, text: lineText });
+                }
+                if (m[0] === '')
+                    re.lastIndex = (m.index ?? 0) + 1;
+            }
+        }
+    };
+    if (st.isFile()) {
+        scanFile(target);
+    }
+    else if (st.isDirectory()) {
+        if (recursive) {
+            const entries = walkTree(target, { maxEntries: Math.max(maxResults * 8, 500), includeHidden: false });
+            for (const e of entries) {
+                if (e.type !== 'file')
+                    continue;
+                scanFile(e.abs);
+                if (matches.length >= maxResults && count > maxResults)
+                    break;
+            }
+        }
+        else {
+            let names = [];
+            try {
+                names = fs.readdirSync(target).sort();
+            }
+            catch {
+                /* ignore */
+            }
+            for (const name of names) {
+                if (name.startsWith('.'))
+                    continue;
+                const full = path.join(target, name);
+                let s;
+                try {
+                    s = fs.lstatSync(full);
+                }
+                catch {
+                    continue;
+                }
+                if (s.isSymbolicLink() || !s.isFile())
+                    continue;
+                scanFile(full);
+                if (matches.length >= maxResults && count > maxResults)
+                    break;
+            }
+        }
+    }
+    else {
+        throw new ToolError('NOT_A_FILE_OR_DIR', `Path is not a file or directory: ${targetStr}`);
+    }
+    return {
+        ok: true,
+        result: {
+            pattern: patternStr,
+            path: rel(realRoot, target),
+            matches,
+            count,
+            truncated: count > matches.length,
+        },
+    };
+};
+// --- glob ------------------------------------------------------------------
+const glob = async (ctx, args, signal) => {
+    abortIfRequested(signal);
+    const pattern = requireString(args, 'pattern');
+    const baseStr = optionalString(args, 'path', '.') ?? '.';
+    const maxResults = optionalInt(args, 'maxResults', 1000, { min: 1, max: 5000 });
+    const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+    const base = (0, path_utils_1.safeResolve)(ctx.root, baseStr, realRoot, { allowEqual: true });
+    assertNotSensitive(base);
+    let st;
+    try {
+        st = fs.statSync(base);
+    }
+    catch {
+        throw new ToolError('NOT_FOUND', `Path does not exist: ${baseStr}`);
+    }
+    if (!st.isDirectory()) {
+        throw new ToolError('NOT_A_DIR', `Path is not a directory: ${baseStr}`);
+    }
+    const re = globToRegex(pattern);
+    const entries = walkTree(base, { maxEntries: Math.max(maxResults * 4, 500), includeHidden: false });
+    const matches = [];
+    for (const e of entries) {
+        if (e.type && re.test(e.rel)) {
+            matches.push({ path: rel(realRoot, e.abs), type: e.type });
+            if (matches.length >= maxResults)
+                break;
+        }
+    }
+    return {
+        ok: true,
+        result: {
+            pattern,
+            path: rel(realRoot, base),
+            matches,
+            count: matches.length,
+            truncated: matches.length >= maxResults,
+        },
+    };
+};
+const tree = async (ctx, args, signal) => {
+    abortIfRequested(signal);
+    const targetStr = optionalString(args, 'path', '.') ?? '.';
+    const depth = optionalInt(args, 'depth', 2, { min: 0, max: 12 });
+    const maxEntries = optionalInt(args, 'maxEntries', 500, { min: 1, max: 5000 });
+    const includeHidden = optionalBool(args, 'showHidden', false);
+    const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+    const target = (0, path_utils_1.safeResolve)(ctx.root, targetStr, realRoot, { allowEqual: true });
+    assertNotSensitive(target);
+    let st;
+    try {
+        st = fs.statSync(target);
+    }
+    catch {
+        throw new ToolError('NOT_FOUND', `Path does not exist: ${targetStr}`);
+    }
+    if (!st.isDirectory()) {
+        throw new ToolError('NOT_A_DIR', `Path is not a directory: ${targetStr}`);
+    }
+    let count = 0;
+    let truncated = false;
+    const build = (absDir, cur) => {
+        if (cur > depth)
+            return [];
+        let names = [];
+        try {
+            names = fs.readdirSync(absDir).sort();
+        }
+        catch {
+            return [];
+        }
+        const nodes = [];
+        for (const name of names) {
+            if (!includeHidden && name.startsWith('.'))
+                continue;
+            const full = path.join(absDir, name);
+            let cst;
+            try {
+                cst = fs.lstatSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (cst.isSymbolicLink())
+                continue;
+            const type = cst.isDirectory() ? 'dir' : cst.isFile() ? 'file' : '';
+            if (!type)
+                continue;
+            count += 1;
+            const node = {
+                name,
+                path: rel(realRoot, full),
+                type,
+                ...(cst.isFile() ? { size: cst.size } : {}),
+            };
+            if (type === 'dir' && cur + 1 <= depth) {
+                const children = build(full, cur + 1);
+                if (children.length)
+                    node.children = children;
+            }
+            nodes.push(node);
+            if (count >= maxEntries) {
+                truncated = true;
+                break;
+            }
+        }
+        return nodes;
+    };
+    const treeNodes = build(target, 0);
+    const lines = [rel(realRoot, target) || '.'];
+    const render = (nodes, prefix) => {
+        nodes.forEach((node, idx) => {
+            const last = idx === nodes.length - 1;
+            lines.push(`${prefix}${last ? '└── ' : '├── '}${node.name}${node.type === 'dir' ? '/' : ''}`);
+            if (node.children && node.children.length) {
+                render(node.children, `${prefix}${last ? '    ' : '│   '}`);
+            }
+        });
+    };
+    render(treeNodes, '');
+    return {
+        ok: true,
+        result: {
+            path: rel(realRoot, target),
+            depth,
+            truncated,
+            count,
+            tree: treeNodes,
+            text: lines.join('\n'),
+        },
+    };
+};
+// --- str_replace_editor ----------------------------------------------------
+function readLineRange(args) {
+    const v = args.view_range;
+    if (v === undefined || v === null)
+        return null;
+    if (!Array.isArray(v) || v.length !== 2) {
+        throw new ToolError('INVALID_ARG', '"view_range" must be a [start, end] array.');
+    }
+    const start = Number(v[0]);
+    const end = Number(v[1]);
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start < 1 || end < start) {
+        throw new ToolError('INVALID_ARG', '"view_range" must be [start, end] with 1 <= start <= end.');
+    }
+    return [start, end];
+}
+const strReplaceEditor = async (ctx, args, signal) => {
+    abortIfRequested(signal);
+    const command = requireString(args, 'command').toLowerCase();
+    const pathStr = requireString(args, 'path');
+    const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+    const target = (0, path_utils_1.safeResolve)(ctx.root, pathStr, realRoot);
+    assertNotSensitive(target);
+    const assertNotRootTarget = () => {
+        if (path.relative(realRoot, target) === '') {
+            throw new ToolError('ROOT_PATH', 'The authorisation root itself cannot be edited.');
+        }
+    };
+    const ensureFile = () => {
+        let st;
+        try {
+            st = fs.statSync(target);
+        }
+        catch {
+            throw new ToolError('NOT_FOUND', `Path does not exist: ${pathStr}`);
+        }
+        if (st.isDirectory()) {
+            throw new ToolError('IS_DIR', `Path is a directory, not a file: ${pathStr}`);
+        }
+        const buf = fs.readFileSync(target);
+        if (!isUtf8(buf)) {
+            throw new ToolError('BINARY_FILE', 'str_replace_editor only supports UTF-8 text files.');
+        }
+        return buf.toString('utf8');
+    };
+    switch (command) {
+        case 'create': {
+            assertNotRootTarget();
+            const fileText = requireString(args, 'file_text');
+            const allowOverwrite = optionalBool(args, 'allowOverwrite', false);
+            if (fs.existsSync(target) && !allowOverwrite) {
+                throw new ToolError('EXISTS', `File already exists: ${pathStr} (pass allowOverwrite:true to replace it).`);
+            }
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, fileText, 'utf8');
+            return { ok: true, result: { path: rel(realRoot, target), bytesWritten: Buffer.byteLength(fileText) } };
+        }
+        case 'view': {
+            const text = ensureFile();
+            const allLines = text === '' ? [] : text.split('\n');
+            const range = readLineRange(args);
+            const selected = range ? allLines.slice(range[0] - 1, range[1]) : allLines;
+            const joined = selected.join('\n');
+            const content = joined.length > ctx.maxBytes ? joined.slice(0, ctx.maxBytes) : joined;
+            return {
+                ok: true,
+                result: {
+                    path: rel(realRoot, target),
+                    totalLines: allLines.length,
+                    lineStart: range ? range[0] : 1,
+                    lineCount: selected.length,
+                    truncated: joined.length > content.length,
+                    content,
+                },
+            };
+        }
+        case 'str_replace': {
+            assertNotRootTarget();
+            const text = ensureFile();
+            const oldStr = requireString(args, 'old_str');
+            const newStr = typeof args.new_str === 'string' ? args.new_str : '';
+            const replaceAll = optionalBool(args, 'replace_all', false);
+            const count = text.split(oldStr).length - 1;
+            if (count === 0) {
+                throw new ToolError('NO_MATCH', 'old_str was not found in the file.');
+            }
+            if (!replaceAll && count !== 1) {
+                throw new ToolError('MULTIPLE_MATCHES', `old_str matched ${count} times; pass replace_all:true to replace all of them.`);
+            }
+            const updated = replaceAll ? text.split(oldStr).join(newStr) : text.replace(oldStr, newStr);
+            fs.writeFileSync(target, updated, 'utf8');
+            return { ok: true, result: { path: rel(realRoot, target), replacements: count } };
+        }
+        case 'insert': {
+            assertNotRootTarget();
+            const text = ensureFile();
+            const newStr = requireString(args, 'new_str');
+            const insertLine = optionalInt(args, 'insert_line', 0, { min: 0 });
+            const lines = text === '' ? [] : text.split('\n');
+            // insert_line is 1-based; 0 or out-of-range appends.
+            const pos = insertLine >= 1 && insertLine <= lines.length + 1 ? insertLine - 1 : lines.length;
+            lines.splice(pos, 0, newStr);
+            fs.writeFileSync(target, lines.join('\n'), 'utf8');
+            return { ok: true, result: { path: rel(realRoot, target), line: pos + 1, inserted: newStr } };
+        }
+        case 'delete': {
+            assertNotRootTarget();
+            const text = ensureFile();
+            const range = readLineRange(args);
+            if (!range) {
+                throw new ToolError('INVALID_ARG', '"delete" requires a "view_range" [start, end].');
+            }
+            const lines = text === '' ? [] : text.split('\n');
+            const [start, end] = range;
+            if (start > lines.length) {
+                throw new ToolError('RANGE_OUT_OF_BOUNDS', `Line ${start} is out of range (file has ${lines.length} lines).`);
+            }
+            const removed = lines.slice(start - 1, Math.min(end, lines.length));
+            lines.splice(start - 1, Math.min(end, lines.length) - (start - 1));
+            fs.writeFileSync(target, lines.join('\n'), 'utf8');
+            return { ok: true, result: { path: rel(realRoot, target), lineStart: start, lineEnd: Math.min(end, start + removed.length - 1), removed: removed.length } };
+        }
+        default:
+            throw new ToolError('INVALID_ARG', `Unknown str_replace_editor command "${command}". Expected: create | view | str_replace | insert | delete.`);
+    }
+};
+// --- mv / cp / delete ------------------------------------------------------
+/** Recursively copy a file or directory within the authorisation root. Never
+ * follows symlinks so a copy cannot escape the root. */
+function copyWithinRoot(src, dst) {
+    const sst = fs.statSync(src);
+    if (sst.isDirectory()) {
+        fs.mkdirSync(dst, { recursive: true });
+        for (const name of fs.readdirSync(src)) {
+            const childSrc = path.join(src, name);
+            let cst;
+            try {
+                cst = fs.lstatSync(childSrc);
+            }
+            catch {
+                continue;
+            }
+            if (cst.isSymbolicLink())
+                continue;
+            copyWithinRoot(childSrc, path.join(dst, name));
+        }
+    }
+    else {
+        fs.copyFileSync(src, dst);
+        try {
+            fs.chmodSync(dst, sst.mode & 0o777);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+const mv = async (ctx, args, signal) => {
+    abortIfRequested(signal);
+    const srcArg = requireString(args, 'source');
+    const dstArg = requireString(args, 'destination');
+    const overwrite = optionalBool(args, 'overwrite', false);
+    const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+    const src = (0, path_utils_1.safeResolve)(ctx.root, srcArg, realRoot);
+    const dst = (0, path_utils_1.safeResolve)(ctx.root, dstArg, realRoot);
+    assertNotSensitive(src);
+    assertNotSensitive(dst);
+    if (path.relative(realRoot, dst) === '') {
+        throw new ToolError('ROOT_PATH', 'The authorisation root itself cannot be a move destination.');
+    }
+    let ss;
+    try {
+        ss = fs.statSync(src);
+    }
+    catch {
+        throw new ToolError('NOT_FOUND', `Source does not exist: ${srcArg}`);
+    }
+    if (fs.existsSync(dst)) {
+        if (!overwrite) {
+            return { ok: false, error: `Destination already exists: ${dstArg} (pass overwrite:true to replace).` };
+        }
+        if (!permitsDangerCommand(ctx.permissionPreset, 'danger')) {
+            return { ok: false, needsApproval: true, error: `Overwrites existing path ${dstArg}; requires approval.` };
+        }
+    }
+    try {
+        fs.mkdirSync(path.dirname(dst), { recursive: true });
+        try {
+            fs.renameSync(src, dst);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'EXDEV' || code === 'EPERM') {
+                copyWithinRoot(src, dst);
+                fs.rmSync(src, { recursive: true, force: true });
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `move failed: ${msg}` };
+    }
+    return { ok: true, result: { from: rel(realRoot, src), to: rel(realRoot, dst) } };
+};
+const cp = async (ctx, args, signal) => {
+    abortIfRequested(signal);
+    const srcArg = requireString(args, 'source');
+    const dstArg = requireString(args, 'destination');
+    const overwrite = optionalBool(args, 'overwrite', false);
+    const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+    const src = (0, path_utils_1.safeResolve)(ctx.root, srcArg, realRoot);
+    const dst = (0, path_utils_1.safeResolve)(ctx.root, dstArg, realRoot);
+    assertNotSensitive(src);
+    assertNotSensitive(dst);
+    if (path.relative(realRoot, dst) === '') {
+        throw new ToolError('ROOT_PATH', 'The authorisation root itself cannot be a copy destination.');
+    }
+    let ss;
+    try {
+        ss = fs.statSync(src);
+    }
+    catch {
+        throw new ToolError('NOT_FOUND', `Source does not exist: ${srcArg}`);
+    }
+    if (fs.existsSync(dst)) {
+        if (!overwrite) {
+            return { ok: false, error: `Destination already exists: ${dstArg} (pass overwrite:true to replace).` };
+        }
+        if (!permitsDangerCommand(ctx.permissionPreset, 'danger')) {
+            return { ok: false, needsApproval: true, error: `Overwrites existing path ${dstArg}; requires approval.` };
+        }
+    }
+    try {
+        fs.mkdirSync(path.dirname(dst), { recursive: true });
+        if (path.relative(src, dst) === '') {
+            throw new ToolError('INVALID_ARG', 'Source and destination cannot be the same.');
+        }
+        copyWithinRoot(src, dst);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `copy failed: ${msg}` };
+    }
+    return { ok: true, result: { from: rel(realRoot, src), to: rel(realRoot, dst) } };
+};
+const deleteFile = async (ctx, args, signal) => {
+    abortIfRequested(signal);
+    const pathStr = requireString(args, 'path');
+    const recursive = optionalBool(args, 'recursive', false);
+    const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+    const target = (0, path_utils_1.safeResolve)(ctx.root, pathStr, realRoot);
+    assertNotSensitive(target);
+    if (path.relative(realRoot, target) === '') {
+        throw new ToolError('ROOT_PATH', 'Refusing to delete the authorisation root.');
+    }
+    let st;
+    try {
+        st = fs.statSync(target);
+    }
+    catch {
+        throw new ToolError('NOT_FOUND', `Path does not exist: ${pathStr}`);
+    }
+    // Delete is destructive: always require human confirmation unless the most
+    // permissive preset is active.
+    if (!permitsDangerCommand(ctx.permissionPreset, 'danger')) {
+        return { ok: false, needsApproval: true, error: `Deleting ${pathStr} requires approval.` };
+    }
+    try {
+        if (st.isDirectory() && !recursive) {
+            if (fs.readdirSync(target).length !== 0) {
+                throw new ToolError('DIR_NOT_EMPTY', `Directory is not empty: ${pathStr} (pass recursive:true).`);
+            }
+        }
+        fs.rmSync(target, { recursive, force: false });
+    }
+    catch (err) {
+        if (err instanceof ToolError)
+            throw err;
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `delete failed: ${msg}` };
+    }
+    return { ok: true, result: { path: rel(realRoot, target) } };
+};
+// --- json pretty-print -----------------------------------------------------
+function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const k of Object.keys(value).sort()) {
+            out[k] = sortKeysDeep(value[k]);
+        }
+        return out;
+    }
+    return value;
+}
+const jsonTool = async (ctx, args, signal) => {
+    abortIfRequested(signal);
+    const pathStr = optionalString(args, 'path');
+    const indent = optionalInt(args, 'indent', 2, { min: 0, max: 16 });
+    const sortKeys = optionalBool(args, 'sortKeys', false);
+    let raw;
+    let outPath;
+    if (pathStr) {
+        const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
+        const target = (0, path_utils_1.safeResolve)(ctx.root, pathStr, realRoot);
+        assertNotSensitive(target);
+        let st;
+        try {
+            st = fs.statSync(target);
+        }
+        catch {
+            throw new ToolError('NOT_FOUND', `Path does not exist: ${pathStr}`);
+        }
+        if (st.size > MAX_WRITE_BYTES) {
+            throw new ToolError('TOO_LARGE', `File exceeds ${MAX_WRITE_BYTES} bytes.`);
+        }
+        const buf = fs.readFileSync(target);
+        if (!isUtf8(buf)) {
+            throw new ToolError('BINARY_FILE', 'json only supports UTF-8 text files.');
+        }
+        raw = buf.toString('utf8');
+        outPath = rel(realRoot, target);
+    }
+    else {
+        const v = args.value;
+        if (typeof v === 'string') {
+            raw = v;
+        }
+        else if (v !== undefined && v !== null) {
+            raw = JSON.stringify(v);
+        }
+        else {
+            throw new ToolError('INVALID_ARG', '"json" requires either "value" (string) or "path".');
+        }
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ToolError('INVALID_JSON', `Invalid JSON: ${msg}`);
+    }
+    const pretty = JSON.stringify(sortKeys ? sortKeysDeep(parsed) : parsed, null, indent);
+    return { ok: true, result: { json: pretty.length > ctx.maxBytes ? `${pretty.slice(0, ctx.maxBytes)}\n…(truncated)` : pretty, ...(outPath ? { path: outPath } : {}) } };
+};
+// --- skills ----------------------------------------------------------------
+/** Load a skill (`.dsh/skills/<name>.md` under the workspace root). No-op when
+ * no skills directory or no matching skill exists. */
+const skillTool = async (ctx, args, signal) => {
+    abortIfRequested(signal);
+    const name = optionalString(args, 'name', '') ?? '';
+    if (name === '') {
+        const available = (0, skills_1.listSkills)(ctx.root);
+        const note = available.length === 0
+            ? 'No skills are configured.'
+            : `Name required; available skills: ${available.join(', ')}.`;
+        return { ok: true, result: { loaded: false, available, note } };
+    }
+    const record = (0, skills_1.loadSkillRecord)(ctx.root, name);
+    return { ok: true, result: record };
+};
 const TOOLS = {
     list_dir: listDir,
     read_file: readFile,
     write_file: writeFile,
     edit_file: editFile,
+    str_replace_editor: strReplaceEditor,
     run_command: runCommandTool,
     web_search: webSearch,
     git,
     generate,
+    search,
+    glob,
+    tree,
+    mv,
+    cp,
+    delete_file: deleteFile,
+    json: jsonTool,
+    skill: skillTool,
 };
 /** Build a tool registry bound to a single execution context. */
 function createToolRegistry(ctx) {
@@ -479,9 +1398,39 @@ function createToolRegistry(ctx) {
                 return { ok: false, error: `Unknown tool: ${name}`, durationMs: 0 };
             }
             try {
+                // Guarded gate: pre-execution check (permission preset, danger
+                // commands, canonicalise + sensitive-path).
+                const pre = preExecute(ctx, name, args ?? {});
+                if (!pre.ok) {
+                    const durationMs = Date.now() - started;
+                    return {
+                        ok: false,
+                        error: pre.error,
+                        durationMs,
+                        ...(pre.needsApproval ? { needsApproval: true } : {}),
+                    };
+                }
+                // A cancel message may arrive while pre-checking; honour it.
+                abortIfRequested(signal);
                 const outcome = await executor(ctx, args ?? {}, signal);
-                const durationMs = Date.now() - started;
-                return { ok: outcome.ok, result: outcome.result, error: outcome.error, durationMs };
+                const result = {
+                    ok: outcome.ok,
+                    result: outcome.result,
+                    error: outcome.error,
+                    durationMs: Date.now() - started,
+                    ...(outcome.needsApproval ? { needsApproval: true } : {}),
+                };
+                // Guarded gate: post-execution check (mask secrets + record reason).
+                const post = postExecute(ctx, name, result);
+                if (!post.ok) {
+                    const durationMs = Date.now() - started;
+                    return {
+                        ok: false,
+                        error: post.error ?? 'post-execution check failed',
+                        durationMs,
+                    };
+                }
+                return result;
             }
             catch (err) {
                 const durationMs = Date.now() - started;