agent-world 0.13.0 → 0.15.0

package/dist/core/feature-path-logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-path-logging.js","sourceRoot":"","sources":["../../core/feature-path-logging.ts"],"names":[],"mappings":"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"}

package/dist/core/file-tools.d.ts

@@ -2,7 +2,7 @@
  * File Tools Module - Built-in workspace inspection tools for LLM workflows.
  *
  * Features:
- * - Exposes built-in `read_file`, `list_files`, and `grep` tool definitions
+ * - Exposes built-in `read_file`, `write_file`, `list_files`, and `grep` tool definitions
  * - Supports bounded line-based file reads with offset and limit
  * - Provides deterministic directory listing with optional hidden-file support
  * - Performs recursive text search with plain-text or regex matching
@@ -15,6 +15,13 @@
  * - Errors are returned as tool-friendly `Error:` strings
  *
  * Recent Changes:
+ * - 2026-03-12: Added `read` permission level guard to `write_file` — returns a blocked-tool error when world toolPermission is 'read'.
+ * - 2026-03-03: Tightened tool output limits: read_file hard-capped at 200 lines, list_files capped at depth 2 and 200 entries, grep capped at 50 hits with configurable context_lines (2–5).
+ * - 2026-03-01: Hardened `read_file` against undefined read payloads from mocked fs implementations by coercing to empty content instead of hard-failing.
+ * - 2026-03-01: Added read_file fallback that resolves missing relative paths against loaded skill roots (for skill script paths like `scripts/convert.py`).
+ * - 2026-03-01: Allowed read-only file tools to traverse lexically in-scope `.agents/skills/*` paths even when symlinks resolve outside the world directory (skill workspace compatibility).
+ * - 2026-02-28: Added built-in `write_file` tool with explicit `create`/`overwrite` modes and trusted-scope path enforcement.
+ * - 2026-02-21: Added `list_files` output bounding (`maxEntries`) and optional `includePattern` filtering with truncation metadata to reduce continuation token spikes and tool-hop churn on large workspaces.
  * - 2026-02-19: Aligned file-tool path behavior with `shell_cmd`: `list_files` now defaults to trusted working directory when `path` is omitted, and `read_file` accepts `path` alias.
  * - 2026-02-16: Switched `list_files` scanning to `fast-glob` with depth control and default ignore rules.
  * - 2026-02-16: Added optional `recursive` mode to `list_files` for nested directory traversal in a single call.
@@ -27,7 +34,12 @@ type ToolContext = {
     workingDirectory?: string;
     world?: {
         variables?: string;
+        [key: string]: unknown;
     };
+    chatId?: string | null;
+    toolCallId?: string;
+    agentName?: string;
+    messages?: Array<Record<string, any>>;
 };
 export declare function createReadFileToolDefinition(): {
     description: string;
@@ -56,6 +68,34 @@ export declare function createReadFileToolDefinition(): {
     };
     execute: (args: any, _sequenceId?: string, _parentToolCall?: string, context?: ToolContext) => Promise<string>;
 };
+export declare function createWriteFileToolDefinition(): {
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            filePath: {
+                type: string;
+                description: string;
+            };
+            path: {
+                type: string;
+                description: string;
+            };
+            content: {
+                type: string;
+                description: string;
+            };
+            mode: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    execute: (args: any, _sequenceId?: string, _parentToolCall?: string, context?: ToolContext) => Promise<string>;
+};
 export declare function createListFilesToolDefinition(): {
     description: string;
     parameters: {
@@ -73,6 +113,18 @@ export declare function createListFilesToolDefinition(): {
                 type: string;
                 description: string;
             };
+            maxDepth: {
+                type: string;
+                description: string;
+            };
+            includePattern: {
+                type: string;
+                description: string;
+            };
+            maxEntries: {
+                type: string;
+                description: string;
+            };
         };
         required: never[];
         additionalProperties: boolean;
@@ -104,6 +156,10 @@ export declare function createGrepToolDefinition(): {
                 type: string;
                 description: string;
             };
+            contextLines: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
         additionalProperties: boolean;

package/dist/core/file-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-tools.d.ts","sourceRoot":"","sources":["../../core/file-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAUH,KAAK,WAAW,GAAG;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE;QACN,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH,CAAC;AAoLF,wBAAgB,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;oBA2BlB,GAAG,gBAAgB,MAAM,oBAAoB,MAAM,YAAY,WAAW;EAmCnG;AAED,wBAAgB,6BAA6B;;;;;;;;;;;;;;;;;;;;;oBAuBnB,GAAG,gBAAgB,MAAM,oBAAoB,MAAM,YAAY,WAAW;EA4CnG;AAED,wBAAgB,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+Bd,GAAG,gBAAgB,MAAM,oBAAoB,MAAM,YAAY,WAAW;EA0DnG"}
+{"version":3,"file":"file-tools.d.ts","sourceRoot":"","sources":["../../core/file-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAaH,KAAK,WAAW,GAAG;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE;QACN,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;CACvC,CAAC;AAmSF,wBAAgB,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;oBA2BlB,GAAG,gBAAgB,MAAM,oBAAoB,MAAM,YAAY,WAAW;EA+EnG;AAeD,wBAAgB,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;oBA4BnB,GAAG,gBAAgB,MAAM,oBAAoB,MAAM,YAAY,WAAW;EAuGnG;AAED,wBAAgB,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAmCnB,GAAG,gBAAgB,MAAM,oBAAoB,MAAM,YAAY,WAAW;EAsEnG;AAED,wBAAgB,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAmCd,GAAG,gBAAgB,MAAM,oBAAoB,MAAM,YAAY,WAAW;EA4DnG"}

package/dist/core/file-tools.js

@@ -2,7 +2,7 @@
  * File Tools Module - Built-in workspace inspection tools for LLM workflows.
  *
  * Features:
- * - Exposes built-in `read_file`, `list_files`, and `grep` tool definitions
+ * - Exposes built-in `read_file`, `write_file`, `list_files`, and `grep` tool definitions
  * - Supports bounded line-based file reads with offset and limit
  * - Provides deterministic directory listing with optional hidden-file support
  * - Performs recursive text search with plain-text or regex matching
@@ -15,6 +15,13 @@
  * - Errors are returned as tool-friendly `Error:` strings
  *
  * Recent Changes:
+ * - 2026-03-12: Added `read` permission level guard to `write_file` — returns a blocked-tool error when world toolPermission is 'read'.
+ * - 2026-03-03: Tightened tool output limits: read_file hard-capped at 200 lines, list_files capped at depth 2 and 200 entries, grep capped at 50 hits with configurable context_lines (2–5).
+ * - 2026-03-01: Hardened `read_file` against undefined read payloads from mocked fs implementations by coercing to empty content instead of hard-failing.
+ * - 2026-03-01: Added read_file fallback that resolves missing relative paths against loaded skill roots (for skill script paths like `scripts/convert.py`).
+ * - 2026-03-01: Allowed read-only file tools to traverse lexically in-scope `.agents/skills/*` paths even when symlinks resolve outside the world directory (skill workspace compatibility).
+ * - 2026-02-28: Added built-in `write_file` tool with explicit `create`/`overwrite` modes and trusted-scope path enforcement.
+ * - 2026-02-21: Added `list_files` output bounding (`maxEntries`) and optional `includePattern` filtering with truncation metadata to reduce continuation token spikes and tool-hop churn on large workspaces.
  * - 2026-02-19: Aligned file-tool path behavior with `shell_cmd`: `list_files` now defaults to trusted working directory when `path` is omitted, and `read_file` accepts `path` alias.
  * - 2026-02-16: Switched `list_files` scanning to `fast-glob` with depth control and default ignore rules.
  * - 2026-02-16: Added optional `recursive` mode to `list_files` for nested directory traversal in a single call.
@@ -27,10 +34,19 @@ import { promises as fs } from 'fs';
 import * as path from 'path';
 import fg from 'fast-glob';
 import { resolveTrustedShellWorkingDirectory, validateShellDirectoryRequest, } from './shell-cmd-tool.js';
+import { getSkillSourcePath, getSkills } from './skill-registry.js';
+import { getEnvValueFromText } from './utils.js';
+import { requestToolApproval } from './tool-approval.js';
 const DEFAULT_READ_LIMIT = 200;
-const MAX_READ_LIMIT = 2000;
-const DEFAULT_GREP_MAX_RESULTS = 200;
-const MAX_GREP_MAX_RESULTS = 2000;
+const MAX_READ_LIMIT = 200;
+const DEFAULT_LIST_MAX_ENTRIES = 200;
+const MAX_LIST_MAX_ENTRIES = 200;
+const DEFAULT_LIST_MAX_DEPTH = 2;
+const MAX_LIST_MAX_DEPTH = 2;
+const DEFAULT_GREP_MAX_RESULTS = 50;
+const MAX_GREP_MAX_RESULTS = 50;
+const DEFAULT_GREP_CONTEXT_LINES = 2;
+const MAX_GREP_CONTEXT_LINES = 5;
 const MAX_GREP_FILE_BYTES = 1024 * 1024;
 function clamp(value, min, max) {
     return Math.max(min, Math.min(max, value));
@@ -48,12 +64,73 @@ function resolveTargetPath(inputPath, trustedWorkingDirectory) {
     const baseDirectory = trustedWorkingDirectory;
     return path.resolve(baseDirectory, inputPath);
 }
-function ensurePathWithinTrustedDirectory(resolvedPath, trustedWorkingDirectory) {
+function isPathWithinRoot(candidatePath, rootPath) {
+    const normalizeForComparison = (value) => normalizePath(path.resolve(value)).replace(/\/+/g, '/');
+    const normalizedCandidate = normalizeForComparison(candidatePath);
+    const normalizedRoot = normalizeForComparison(rootPath);
+    return normalizedCandidate === normalizedRoot
+        || normalizedCandidate.startsWith(`${normalizedRoot}/`);
+}
+function isMissingFileError(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const errno = error.code;
+    if (errno === 'ENOENT') {
+        return true;
+    }
+    const message = String(error.message ?? '').toLowerCase();
+    return message.includes('enoent') || message.includes('no such file or directory');
+}
+function resolveSkillRelativeReadCandidates(requestedFilePath) {
+    const normalizedRequestedPath = normalizePath(String(requestedFilePath || '').trim());
+    if (!normalizedRequestedPath || path.isAbsolute(normalizedRequestedPath)) {
+        return [];
+    }
+    const candidates = [];
+    const availableSkills = getSkills();
+    for (const skill of availableSkills) {
+        const sourcePath = getSkillSourcePath(skill.skill_id);
+        if (!sourcePath) {
+            continue;
+        }
+        const skillRoot = path.dirname(sourcePath);
+        const candidatePaths = new Set([
+            path.resolve(skillRoot, normalizedRequestedPath),
+        ]);
+        const skillPrefix = `${skill.skill_id}/`;
+        if (normalizedRequestedPath.startsWith(skillPrefix)) {
+            const withoutSkillPrefix = normalizedRequestedPath.slice(skillPrefix.length);
+            if (withoutSkillPrefix) {
+                candidatePaths.add(path.resolve(skillRoot, withoutSkillPrefix));
+            }
+        }
+        for (const candidatePath of candidatePaths) {
+            if (isPathWithinRoot(candidatePath, skillRoot)) {
+                candidates.push(candidatePath);
+            }
+        }
+    }
+    return [...new Set(candidates)];
+}
+function ensurePathWithinTrustedDirectory(resolvedPath, trustedWorkingDirectory, options) {
     const validation = validateShellDirectoryRequest(resolvedPath, trustedWorkingDirectory);
+    if (!validation.valid && options?.allowSkillPathAlias && isWithinSkillAliasPath(resolvedPath, trustedWorkingDirectory)) {
+        return;
+    }
     if (!validation.valid) {
         throw new Error(validation.error);
     }
 }
+function isWithinSkillAliasPath(resolvedPath, trustedWorkingDirectory) {
+    const candidate = path.resolve(String(resolvedPath || '').trim());
+    const trusted = path.resolve(String(trustedWorkingDirectory || '').trim());
+    const skillRoot = path.resolve(trusted, '.agents', 'skills');
+    const normalizedCandidate = normalizePath(candidate).replace(/\/+/g, '/');
+    const normalizedSkillRoot = normalizePath(skillRoot).replace(/\/+/g, '/');
+    return normalizedCandidate === normalizedSkillRoot
+        || normalizedCandidate.startsWith(`${normalizedSkillRoot}/`);
+}
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -112,10 +189,19 @@ function shouldIncludeFile(relativePath, includePattern) {
         return true;
     }
     return patterns.some((pattern) => {
-        if (!pattern.includes('*') && !pattern.includes('?')) {
-            return normalizedRelativePath.includes(normalizePath(pattern));
-        }
-        return globToRegExp(pattern).test(normalizedRelativePath);
+        const normalizedPattern = normalizePath(pattern);
+        const candidatePatterns = normalizedPattern.startsWith('**/')
+            ? [normalizedPattern, normalizedPattern.slice(3)]
+            : [normalizedPattern];
+        return candidatePatterns.some((candidatePattern) => {
+            if (!candidatePattern) {
+                return false;
+            }
+            if (!candidatePattern.includes('*') && !candidatePattern.includes('?')) {
+                return normalizedRelativePath.includes(candidatePattern);
+            }
+            return globToRegExp(candidatePattern).test(normalizedRelativePath);
+        });
     });
 }
 async function collectFilesRecursively(directoryPath) {
@@ -141,7 +227,7 @@ async function collectFilesRecursively(directoryPath) {
     return files;
 }
 async function searchInFile(options) {
-    const { filePath, relativePath, matcher, matches, maxResults } = options;
+    const { filePath, relativePath, matcher, matches, maxResults, contextLines } = options;
     const stat = await fs.stat(filePath);
     if (stat.size > MAX_GREP_FILE_BYTES) {
         return;
@@ -158,11 +244,23 @@ async function searchInFile(options) {
         if (!matcher.test(lineContent)) {
             continue;
         }
-        matches.push({
+        const entry = {
             path: normalizePath(relativePath),
             line: index + 1,
             content: lineContent,
-        });
+        };
+        if (contextLines > 0) {
+            const start = Math.max(0, index - contextLines);
+            const end = Math.min(lines.length - 1, index + contextLines);
+            const surrounding = [];
+            for (let ci = start; ci <= end; ci += 1) {
+                if (ci !== index) {
+                    surrounding.push(`${ci + 1}: ${lines[ci] ?? ''}`);
+                }
+            }
+            entry.context = surrounding;
+        }
+        matches.push(entry);
         if (matches.length >= maxResults) {
             return;
         }
@@ -188,7 +286,7 @@ export function createReadFileToolDefinition() {
                 },
                 limit: {
                     type: 'number',
-                    description: `Maximum number of lines to return (default: ${DEFAULT_READ_LIMIT}, max: ${MAX_READ_LIMIT}).`,
+                    description: `Maximum number of lines to return (default and cap: ${MAX_READ_LIMIT}).`,
                 },
             },
             required: [],
@@ -201,10 +299,50 @@ export function createReadFileToolDefinition() {
                 if (!requestedFilePath) {
                     return 'Error: read_file failed - filePath is required';
                 }
-                const resolvedPath = resolveTargetPath(requestedFilePath, trustedWorkingDirectory);
-                ensurePathWithinTrustedDirectory(resolvedPath, trustedWorkingDirectory);
-                const rawContent = await fs.readFile(resolvedPath, 'utf8');
-                const fileContent = toUtf8String(rawContent);
+                let resolvedPath = resolveTargetPath(requestedFilePath, trustedWorkingDirectory);
+                ensurePathWithinTrustedDirectory(resolvedPath, trustedWorkingDirectory, { allowSkillPathAlias: true });
+                let rawContent;
+                try {
+                    rawContent = await fs.readFile(resolvedPath, 'utf8');
+                }
+                catch (readError) {
+                    if (!isMissingFileError(readError)) {
+                        throw readError;
+                    }
+                    const skillReadCandidates = new Set(resolveSkillRelativeReadCandidates(requestedFilePath));
+                    if (skillReadCandidates.size === 0) {
+                        const relativeFromTrustedDirectory = normalizePath(path.relative(trustedWorkingDirectory, resolvedPath));
+                        const isRelativeToTrusted = relativeFromTrustedDirectory
+                            && relativeFromTrustedDirectory !== '.'
+                            && !relativeFromTrustedDirectory.startsWith('..')
+                            && !path.isAbsolute(relativeFromTrustedDirectory);
+                        if (isRelativeToTrusted) {
+                            for (const candidatePath of resolveSkillRelativeReadCandidates(relativeFromTrustedDirectory)) {
+                                skillReadCandidates.add(candidatePath);
+                            }
+                        }
+                    }
+                    let fallbackReadError = null;
+                    for (const candidatePath of skillReadCandidates) {
+                        try {
+                            ensurePathWithinTrustedDirectory(candidatePath, trustedWorkingDirectory, { allowSkillPathAlias: true });
+                            rawContent = await fs.readFile(candidatePath, 'utf8');
+                            resolvedPath = candidatePath;
+                            fallbackReadError = null;
+                            break;
+                        }
+                        catch (candidateError) {
+                            fallbackReadError = candidateError;
+                            if (!isMissingFileError(candidateError)) {
+                                throw candidateError;
+                            }
+                        }
+                    }
+                    if (fallbackReadError || rawContent === undefined) {
+                        throw readError;
+                    }
+                }
+                const fileContent = toUtf8String(rawContent ?? '');
                 const lines = fileContent.split(/\r?\n/);
                 const offset = clamp(Number(args.offset ?? 1), 1, Number.MAX_SAFE_INTEGER);
                 const limit = clamp(Number(args.limit ?? DEFAULT_READ_LIMIT), 1, MAX_READ_LIMIT);
@@ -226,9 +364,137 @@ export function createReadFileToolDefinition() {
         },
     };
 }
+function normalizeWriteMode(mode) {
+    if (mode === undefined || mode === null || mode === '') {
+        return 'overwrite';
+    }
+    const normalizedMode = String(mode).trim().toLowerCase();
+    if (normalizedMode === 'create' || normalizedMode === 'overwrite') {
+        return normalizedMode;
+    }
+    throw new Error(`Invalid mode '${String(mode)}'. Expected 'create' or 'overwrite'.`);
+}
+export function createWriteFileToolDefinition() {
+    return {
+        description: 'Write text content to a file inside the trusted working-directory scope. Supports explicit create-only and overwrite modes.',
+        parameters: {
+            type: 'object',
+            properties: {
+                filePath: {
+                    type: 'string',
+                    description: 'Target file path. Relative paths resolve from runtime working directory.',
+                },
+                path: {
+                    type: 'string',
+                    description: 'Alias for filePath.',
+                },
+                content: {
+                    type: 'string',
+                    description: 'UTF-8 text content to write.',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['create', 'overwrite'],
+                    description: "Write mode. 'create' fails if the file exists. 'overwrite' replaces existing content (default).",
+                },
+            },
+            required: ['content'],
+            additionalProperties: false,
+        },
+        execute: async (args, _sequenceId, _parentToolCall, context) => {
+            try {
+                // Check world-level tool permission
+                const toolPermission = getEnvValueFromText(context?.world?.variables, 'tool_permission') ?? 'auto';
+                if (toolPermission === 'read') {
+                    return 'Error: write_file is blocked by the current permission level (read).';
+                }
+                if (toolPermission === 'ask' && context?.world) {
+                    const approval = await requestToolApproval({
+                        world: context.world,
+                        chatId: typeof context.chatId === 'string' ? context.chatId : null,
+                        toolCallId: context.toolCallId,
+                        title: 'Approve file write?',
+                        message: `write_file wants to write to: ${String(args.filePath ?? args.path ?? '').trim() || '(unknown)'}`,
+                        defaultOptionId: 'deny',
+                        options: [
+                            { id: 'approve', label: 'Approve', description: 'Allow this file write.' },
+                            { id: 'deny', label: 'Deny', description: 'Block this file write.' },
+                        ],
+                        approvedOptionIds: ['approve'],
+                        metadata: { tool: 'write_file', filePath: String(args.filePath ?? args.path ?? '').trim() },
+                        agentName: context.agentName || null,
+                        messages: context.messages,
+                    });
+                    if (!approval.approved) {
+                        return `Error: write_file was denied by the user (${approval.reason}).`;
+                    }
+                }
+                const trustedWorkingDirectory = getTrustedWorkingDirectory(context);
+                const requestedFilePath = String(args.filePath ?? args.path ?? '').trim();
+                if (!requestedFilePath) {
+                    return 'Error: write_file failed - filePath is required';
+                }
+                if (typeof args.content !== 'string') {
+                    return 'Error: write_file failed - content must be a string';
+                }
+                const mode = normalizeWriteMode(args.mode);
+                const resolvedPath = resolveTargetPath(requestedFilePath, trustedWorkingDirectory);
+                ensurePathWithinTrustedDirectory(resolvedPath, trustedWorkingDirectory);
+                let fileExists = false;
+                try {
+                    const stat = await fs.stat(resolvedPath);
+                    if (stat.isDirectory()) {
+                        return 'Error: write_file failed - target path is a directory';
+                    }
+                    fileExists = true;
+                }
+                catch (error) {
+                    const code = error?.code;
+                    if (code !== 'ENOENT') {
+                        throw error;
+                    }
+                }
+                if (mode === 'create' && fileExists) {
+                    return `Error: write_file failed - file already exists: ${resolvedPath}`;
+                }
+                const parentDirectory = path.dirname(resolvedPath);
+                ensurePathWithinTrustedDirectory(parentDirectory, trustedWorkingDirectory);
+                await fs.mkdir(parentDirectory, { recursive: true });
+                try {
+                    await fs.writeFile(resolvedPath, args.content, mode === 'create'
+                        ? { encoding: 'utf8', flag: 'wx' }
+                        : { encoding: 'utf8', flag: 'w' });
+                }
+                catch (error) {
+                    const code = error?.code;
+                    if (code === 'EEXIST' && mode === 'create') {
+                        return `Error: write_file failed - file already exists: ${resolvedPath}`;
+                    }
+                    throw error;
+                }
+                const created = !fileExists;
+                const bytesWritten = Buffer.byteLength(args.content, 'utf8');
+                return JSON.stringify({
+                    ok: true,
+                    status: 'success',
+                    filePath: resolvedPath,
+                    mode,
+                    operation: created ? 'created' : 'updated',
+                    created,
+                    updated: !created,
+                    bytesWritten,
+                }, null, 2);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return `Error: write_file failed - ${message}`;
+            }
+        },
+    };
+}
 export function createListFilesToolDefinition() {
     return {
-        description: 'List files and directories available in a directory path for quick workspace exploration. Defaults to trusted working directory when path is omitted. Use recursive=true to include nested entries.',
+        description: 'List file and directory names in a directory path for quick workspace exploration. Defaults to trusted working directory when path is omitted. Returns names only. Use maxDepth/includePattern/maxEntries to keep results bounded.',
         parameters: {
             type: 'object',
             properties: {
@@ -242,7 +508,19 @@ export function createListFilesToolDefinition() {
                 },
                 recursive: {
                     type: 'boolean',
-                    description: 'When true, include nested entries recursively (default: false).',
+                    description: 'When true, include nested entries up to maxDepth (default: false, depth 1).',
+                },
+                maxDepth: {
+                    type: 'number',
+                    description: `Maximum directory depth when recursive (default and cap: ${MAX_LIST_MAX_DEPTH}).`,
+                },
+                includePattern: {
+                    type: 'string',
+                    description: 'Optional glob-like filter (supports comma-separated patterns), for example: **/*.md',
+                },
+                maxEntries: {
+                    type: 'number',
+                    description: `Maximum number of returned entries (default and cap: ${MAX_LIST_MAX_ENTRIES}).`,
                 },
             },
             required: [],
@@ -253,28 +531,44 @@ export function createListFilesToolDefinition() {
                 const trustedWorkingDirectory = getTrustedWorkingDirectory(context);
                 const requestedPath = String(args.path ?? '.');
                 const resolvedPath = resolveTargetPath(requestedPath, trustedWorkingDirectory);
-                ensurePathWithinTrustedDirectory(resolvedPath, trustedWorkingDirectory);
+                ensurePathWithinTrustedDirectory(resolvedPath, trustedWorkingDirectory, { allowSkillPathAlias: true });
                 const includeHidden = Boolean(args.includeHidden ?? true);
                 const recursive = Boolean(args.recursive ?? false);
+                const includePattern = String(args.includePattern ?? '').trim();
+                const maxDepth = clamp(Number(args.maxDepth ?? (recursive ? DEFAULT_LIST_MAX_DEPTH : 1)), 1, MAX_LIST_MAX_DEPTH);
+                const maxEntries = clamp(Number(args.maxEntries ?? DEFAULT_LIST_MAX_ENTRIES), 1, MAX_LIST_MAX_ENTRIES);
                 const items = await fg(['**/*'], {
                     cwd: resolvedPath,
-                    deep: recursive ? Infinity : 1,
+                    deep: maxDepth,
                     ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**'],
                     onlyFiles: false,
                     markDirectories: true,
                     dot: includeHidden,
                 });
-                const normalizedItems = items
+                const filteredItems = items
                     .map((entry) => normalizePath(entry))
+                    .filter((entry) => shouldIncludeFile(entry, includePattern))
                     .sort((left, right) => left.localeCompare(right));
+                const totalMatchedEntries = filteredItems.length;
+                const truncated = totalMatchedEntries > maxEntries;
+                const returnedEntries = truncated ? filteredItems.slice(0, maxEntries) : filteredItems;
+                const message = totalMatchedEntries === 0
+                    ? 'No files or directories found in the requested path.'
+                    : (truncated
+                        ? `Result truncated to ${maxEntries} entries out of ${totalMatchedEntries}. Narrow with includePattern or path.`
+                        : undefined);
                 return JSON.stringify({
                     requestedPath,
                     path: resolvedPath,
                     recursive,
-                    total: normalizedItems.length,
-                    entries: normalizedItems,
-                    found: normalizedItems.length > 0,
-                    message: normalizedItems.length > 0 ? undefined : 'No files or directories found in the requested path.',
+                    includePattern: includePattern || undefined,
+                    maxEntries,
+                    total: totalMatchedEntries,
+                    returned: returnedEntries.length,
+                    truncated,
+                    entries: returnedEntries,
+                    found: totalMatchedEntries > 0,
+                    message,
                 }, null, 2);
             }
             catch (error) {
@@ -289,7 +583,7 @@ export function createListFilesToolDefinition() {
 }
 export function createGrepToolDefinition() {
     return {
-        description: 'Search text across files to find destinations. Supports plain text or regex queries with optional include filtering.',
+        description: 'Search text across files to find destinations. Supports plain text or regex queries with optional include filtering and surrounding context lines.',
         parameters: {
             type: 'object',
             properties: {
@@ -311,7 +605,11 @@ export function createGrepToolDefinition() {
                 },
                 maxResults: {
                     type: 'number',
-                    description: `Maximum matches to return (default: ${DEFAULT_GREP_MAX_RESULTS}, max: ${MAX_GREP_MAX_RESULTS}).`,
+                    description: `Maximum matches to return (default and cap: ${MAX_GREP_MAX_RESULTS}).`,
+                },
+                contextLines: {
+                    type: 'number',
+                    description: `Number of surrounding context lines per match (default: ${DEFAULT_GREP_CONTEXT_LINES}, range: 0\u2013${MAX_GREP_CONTEXT_LINES}).`,
                 },
             },
             required: ['query'],
@@ -328,9 +626,10 @@ export function createGrepToolDefinition() {
                 const directoryPath = args.directoryPath
                     ? resolveTargetPath(String(args.directoryPath), trustedWorkingDirectory)
                     : trustedWorkingDirectory;
-                ensurePathWithinTrustedDirectory(directoryPath, trustedWorkingDirectory);
+                ensurePathWithinTrustedDirectory(directoryPath, trustedWorkingDirectory, { allowSkillPathAlias: true });
                 const includePattern = typeof args.includePattern === 'string' ? args.includePattern : undefined;
                 const maxResults = clamp(Number(args.maxResults ?? DEFAULT_GREP_MAX_RESULTS), 1, MAX_GREP_MAX_RESULTS);
+                const contextLines = clamp(Number(args.contextLines ?? DEFAULT_GREP_CONTEXT_LINES), 0, MAX_GREP_CONTEXT_LINES);
                 const matcher = isRegexp ? new RegExp(query, 'i') : new RegExp(escapeRegExp(query), 'i');
                 const allFiles = await collectFilesRecursively(directoryPath);
                 const matches = [];
@@ -345,6 +644,7 @@ export function createGrepToolDefinition() {
                         matcher,
                         matches,
                         maxResults,
+                        contextLines,
                     });
                     if (matches.length >= maxResults) {
                         break;