@mario.andreschak/mcp-filesystem 3.45.0 → 3.45.2

package/dist/tools.js

@@ -14,20 +14,18 @@
  *    as a HARD CEILING an operator sets — no path may ever escape it, and
  *  - user-configured roots persisted via the MCP manager UI (issue #170), which
  *    may only narrow WITHIN the env ceiling (never widen it).
- * When neither is set the server has full host access. An optional experimental
- * deny layer (issue #260, see protectedPaths.ts) can additionally block a
- * hardcoded set of sensitive home locations regardless of configured roots. It
- * is disabled by default.
+ * When neither is set the server has full host access.
  *
  * Every tool returns a machine-readable JSON envelope both as MCP
  * `structuredContent` and as a single text content block (for backward-compat
  * clients); errors are returned as `isError: true` results rather than thrown.
  */
 import path from 'node:path';
-import { promises as fs, createReadStream } from 'node:fs';
+import { promises as fs } from 'node:fs';
+import { spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import readline from 'node:readline';
-import { ALLOW_PROTECTED_PATHS_ENV, createLogger, getDataDir, isInside, isProtected, isProtectedPathsEnabled, loadEffectiveRoots, } from './shared.js';
+import { createLogger, getDataDir, isInside, loadEffectiveRoots, } from './shared.js';
 import { recordTouchedFile } from './resources.js';
 import { detectMediaFile, mimeTypeFromExtension, mediaTypeFromMime, looksBinaryHeuristic } from './media.js';
 const FILESYSTEM_SERVER_NAME = 'filesystem';
@@ -79,10 +77,90 @@ const MAX_MEDIA_BYTES = 32 * 1024 * 1024;
 const SEARCH_MAX_FILE_BYTES = 5_000_000;
 /** #287: how many files to scan concurrently during a content search. */
 const SEARCH_CONCURRENCY = 16;
+/** Directory reads are independent I/O; a bounded breadth-first batch avoids
+ * serially walking every directory on large workspaces. */
+const SEARCH_DIRECTORY_CONCURRENCY = 32;
+/** Do not turn a fast filesystem walk into a notification flood. */
+const SEARCH_PROGRESS_INTERVAL_MS = 500;
+/** Silent searches still report liveness so the host can distinguish work from a hang. */
+const SEARCH_PROGRESS_HEARTBEAT_MS = 5_000;
 /** #287: context lines shown around each `read_file` pattern match. */
 const READ_PATTERN_CONTEXT = 2;
 /** #287: cap on matches returned by a single `read_file` pattern grep. */
 const MAX_READ_PATTERN_MATCHES = 200;
+/** #487: bound caller-controlled regular expressions before compiling them. */
+const MAX_READ_PATTERN_LENGTH = 4_096;
+/**
+ * Coalesced MCP progress for search. The numeric field is a notification
+ * sequence (MCP requires it to increase); useful counters live in the message.
+ */
+function createSearchProgressReporter(context) {
+    const report = context?.onProgress;
+    if (!report)
+        return { update: () => undefined, stop: async () => undefined };
+    let snapshot = {
+        phase: 'starting',
+        directories: 0,
+        files: 0,
+        matches: 0,
+    };
+    let sequence = 0;
+    let lastDeliveredAt = 0;
+    let stopped = false;
+    let chain = Promise.resolve();
+    const deliver = () => {
+        if (stopped || context?.signal?.aborted)
+            return;
+        lastDeliveredAt = Date.now();
+        const current = ++sequence;
+        const message = `${snapshot.phase}: ${snapshot.directories} directories, ${snapshot.files} files, ${snapshot.matches} matches`;
+        chain = chain
+            .then(() => report({ progress: current, message }))
+            .catch((error) => log.debug('Could not deliver filesystem search progress', error));
+    };
+    const heartbeat = setInterval(deliver, SEARCH_PROGRESS_HEARTBEAT_MS);
+    heartbeat.unref?.();
+    return {
+        update: (patch, force = false) => {
+            snapshot = { ...snapshot, ...patch };
+            if (force || Date.now() - lastDeliveredAt >= SEARCH_PROGRESS_INTERVAL_MS)
+                deliver();
+        },
+        stop: async () => {
+            if (stopped)
+                return;
+            clearInterval(heartbeat);
+            if (!context?.signal?.aborted && Date.now() - lastDeliveredAt > 0)
+                deliver();
+            stopped = true;
+            await chain;
+        },
+    };
+}
+/**
+ * ripgrep is an installer-provided acceleration, not a runtime requirement.
+ * Cache by PATH value so a process whose environment is refreshed after an
+ * install can discover it without restarting. `undefined` means automatic,
+ * while `null` is a test-only forced fallback.
+ */
+let ripgrepCache;
+let ripgrepExecutableForTests;
+const activeRipgrepChildren = new Set();
+/** Test seam: force a ripgrep executable, force the Node fallback with null, or reset with undefined. */
+export function _setRipgrepExecutableForTests(value) {
+    ripgrepExecutableForTests = value;
+    ripgrepCache = undefined;
+}
+/** Kill external search accelerators before the filesystem MCP process exits. */
+export function shutdownFilesystemSearches() {
+    for (const child of activeRipgrepChildren) {
+        try {
+            child.kill();
+        }
+        catch { /* best-effort shutdown */ }
+    }
+    activeRipgrepChildren.clear();
+}
 /** Return a structured payload as BOTH MCP structuredContent and a text fallback. */
 function dualResult(payload) {
     return {
@@ -104,6 +182,19 @@ function errorResult(message) {
         isError: true,
     };
 }
+/**
+ * Translate the slash-drive form some models emit into a native Windows path.
+ * Keep the platform injectable so the narrow conversion can be verified on any
+ * host; all canonicalization and confinement still happen in resolvePath().
+ */
+export function _normalizeSlashDrivePathForTests(raw, platform = process.platform) {
+    const match = /^\/([A-Za-z])(?:\/|$)/.exec(raw);
+    if (platform !== 'win32' || !match)
+        return raw;
+    const driveRoot = `${match[1].toUpperCase()}:\\`;
+    const remainder = raw.slice(match[0].length).split('/').join(path.win32.sep);
+    return remainder ? `${driveRoot}${remainder}` : driveRoot;
+}
 /**
  * Resolve a user-supplied path against the data dir (for relative paths) and
  * enforce the effective confinement roots. An empty roots array blocks all access.
@@ -113,32 +204,23 @@ async function resolvePath(input, roots) {
     const raw = typeof input === 'string' ? input.trim() : '';
     if (!raw)
         throw new Error('Provide "path".');
+    const normalized = _normalizeSlashDrivePathForTests(raw);
     const dataDir = getDataDir();
-    const resolved = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(dataDir, raw);
-    // Optional defense-in-depth layer (issue #260). Configured roots win by
-    // default; users can opt into this stricter policy under Experimental Features.
-    if (await isProtectedPathsEnabled()) {
-        const prot = isProtected(resolved);
-        if (prot.denied) {
-            throw new Error(`Path "${resolved}" is within a protected location (${prot.matchedRoot}) and is blocked by the FLUJO built-in server protected-path policy. ` +
-                `Disable "Protect sensitive home-directory paths" in Experimental Features or set ${ALLOW_PROTECTED_PATHS_ENV}=1 to override.`);
-        }
-    }
+    const resolved = path.isAbsolute(normalized)
+        ? path.resolve(normalized)
+        : path.resolve(dataDir, normalized);
     if (roots.length === 0 || !roots.some((root) => isInside(root, resolved))) {
         throw new Error(`Path "${resolved}" is outside the configured filesystem roots.`);
     }
     return resolved;
 }
 export function filesystemToolDefinitions() {
-    const pathProp = { type: 'string', description: 'File or directory path. Relative paths resolve against the FLUJO data directory; absolute paths are used as-is.' };
+    const pathProp = { type: 'string', description: 'File or directory path. Relative paths start at the FLUJO data directory.' };
     return [
         {
             name: 'read_file',
             annotations: READ_ONLY_ANNOTATIONS,
-            description: 'Read one text file with "path", or up to 25 files in input order with mutually exclusive "paths". Optional "from"/"to" (1-based, inclusive) and "pattern" settings apply to every target. ' +
-                `Media files (images, audio, video) are detected automatically and returned as MCP media content items; read them with "path" alone ("pattern"/"from"/"to" do not apply to binary media, and the large-file rule below is waived for them, up to ${MAX_MEDIA_BYTES / (1024 * 1024)} MB). FLUJO persists the bytes as a run resource and re-attaches them to the conversation as a real media input, so a model that accepts that modality perceives the file directly; a model that does not receives the run-resource URI and can still pass it to other tools. ` +
-                `For large NON-MEDIA files (> ${LARGE_FILE_BYTES / 1000} KB) read WHOLE (no "from"/"to"), a "pattern" is REQUIRED: the server greps the file and returns only matching lines (with a little surrounding context) so you can follow up with targeted "from"/"to" reads. Pass pattern "*" to force-read the entire large file anyway. ` +
-                'Single text reads return { path, from, to, totalLines, content, truncated, contentHash, matches? } unchanged; media reads return { path, mediaType, mimeType, size, encoding } alongside the media item. Batch reads return { files }, with one ordered success or { requestedPath, path?, error } record per input; individual failures do not discard successful reads. Batch output is limited to 1,000,000 serialized characters. Pass contentHash back as "expectedHash" on a follow-up edit_file/write_file to guard against the file changing in between (TOCTOU).',
+            description: `Read text or media files. Use "path" for one file or "paths" for up to 25; do not use both. For text, "from"/"to" select lines and "pattern" is a case-insensitive regular expression. Regex metacharacters have their usual meaning and must be escaped for literal matching; invalid expressions or expressions over ${MAX_READ_PATTERN_LENGTH} characters return an error. Files over ${LARGE_FILE_BYTES / 1000} KB need a line range or pattern; the exact pattern "*" is a reserved sentinel that reads the whole file. Media limit: ${MAX_MEDIA_BYTES / (1024 * 1024)} MB. Use the returned contentHash as expectedHash when editing.`,
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -152,7 +234,7 @@ export function filesystemToolDefinitions() {
                     },
                     from: { type: 'number', description: 'Optional 1-based first line to return (inclusive).' },
                     to: { type: 'number', description: 'Optional 1-based last line to return (inclusive).' },
-                    pattern: { type: 'string', description: 'Case-insensitive substring to grep for. Required to read a large file whole without a "from"/"to" range; matching lines (plus context) are returned instead of the full body. Use "*" to read the whole large file anyway.' },
+                    pattern: { type: 'string', description: `Case-insensitive regular expression, limited to ${MAX_READ_PATTERN_LENGTH} characters. Regex metacharacters have their usual meaning; escape them for a literal match. Invalid or over-limit expressions return a tool error. Required to read a large file whole without a "from"/"to" range; matching lines plus context are returned instead of the full body. The exact value "*" is reserved to read the whole file.` },
                 },
             },
             outputSchema: {
@@ -184,7 +266,7 @@ export function filesystemToolDefinitions() {
         {
             name: 'write_file',
             annotations: DESTRUCTIVE_WRITE_ANNOTATIONS,
-            description: 'Create or write a text file (parent directories are created). "mode": "overwrite" (default) replaces the whole file, or a line range when "startLine"/"endLine" (1-based inclusive) are given; "append" adds content at the end; "insert" inserts content before "startLine". Optionally pass "expectedHash" (the contentHash from a prior read_file) to reject the write if the file changed on disk since it was read (TOCTOU guard); ignored for a whole-file overwrite. Returns { path, bytesWritten, mode, ... }.',
+            description: 'Write a text file and create missing parent directories. Modes: overwrite (default), append, or insert before startLine. For a range overwrite, give startLine and endLine. Use expectedHash from read_file to reject changes to a stale file; it is ignored for whole-file overwrite.',
             // #216: feed the docked diff canvas (ui://devcanvas/diff) so successive
             // writes update one persistent tab. See internal/filesystemResources.ts.
             _meta: { ui: { resourceUri: 'ui://devcanvas/diff' } },
@@ -217,7 +299,7 @@ export function filesystemToolDefinitions() {
         {
             name: 'edit_file',
             annotations: DESTRUCTIVE_WRITE_ANNOTATIONS,
-            description: 'Edit a text file two ways (mutually exclusive): (1) "edits": [{ oldText, newText, startLine?, endLine? }] literal find/replace — each replaces the unique occurrence of oldText. startLine/endLine are an optional disambiguation HINT (if exactly one match starts in that range it wins); a wrong/missing range still works as long as oldText is unique in the file. Include enough surrounding context to make oldText unique. Or (2) "diff": a unified diff string ("@@ -a,b +c,d @@" hunks) applied atomically — hunks are relocated to where their context actually matches, so slightly-off @@ line numbers still apply, and CRLF files are handled. Fails with no partial write only when text is missing/ambiguous or a hunk context is not found. Optionally pass "expectedHash" (the contentHash from a prior read_file) to reject the edit if the file changed on disk since it was read (TOCTOU guard). Returns { path, editsApplied|applied, diff:{added,removed} }.',
+            description: 'Edit a text file with either "edits" or "diff"; do not use both. Each oldText must match once, so include enough context to make it unique. A unified diff is applied atomically. Use expectedHash from read_file to reject edits to a stale file.',
             // #216: also feed the docked diff canvas so edits show live in the canvas.
             _meta: { ui: { resourceUri: 'ui://devcanvas/diff' } },
             inputSchema: {
@@ -264,7 +346,7 @@ export function filesystemToolDefinitions() {
         {
             name: 'list_dir',
             annotations: READ_ONLY_ANNOTATIONS,
-            description: 'List the entries of a directory. Returns { path, entries: [{ name, type, size }] } where type is "file" | "directory" | "other".',
+            description: 'List a directory. Each entry includes name, type, and size.',
             inputSchema: {
                 type: 'object',
                 properties: { path: pathProp },
@@ -289,7 +371,7 @@ export function filesystemToolDefinitions() {
         {
             name: 'file_browser_ui',
             annotations: READ_ONLY_ANNOTATIONS,
-            description: 'Open an interactive file browser in the chat so the USER can pick a file. This returns IMMEDIATELY without a selection — the browser is shown to the user and the file they choose arrives afterwards as a follow-up user message (e.g. "Selected file: <path>"). After calling this tool you MUST stop and wait for that message; do not guess a path or continue until the user has selected.',
+            description: 'Ask the user to pick a file in an interactive browser. This returns before they choose. After calling it, STOP and wait for a follow-up user message containing the selected path.',
             // MCP Apps (#97): this tool exists solely to surface the file-browser app
             // (ui://filesystem/browser). See internal/filesystemResources.ts.
             _meta: { ui: { resourceUri: 'ui://filesystem/browser' } },
@@ -304,7 +386,7 @@ export function filesystemToolDefinitions() {
         {
             name: 'dir_tree',
             annotations: READ_ONLY_ANNOTATIONS,
-            description: 'Return a recursive, depth-limited directory tree as nested JSON. Returns { path, depth, tree }.',
+            description: 'List a directory tree recursively, limited by depth.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -327,7 +409,7 @@ export function filesystemToolDefinitions() {
         {
             name: 'search',
             annotations: READ_ONLY_ANNOTATIONS,
-            description: 'Search a directory tree. Match file/dir NAMES against "namePattern" (substring, case-insensitive) and/or file CONTENT against "content" (substring, case-insensitive). Content search DOES look inside every text file, returning each matching line with its 1-based line number; likely-binary and very large files are skipped for speed. Returns { matches: [{ path, line?, text? }], truncated }.',
+            description: 'Search a directory tree by namePattern and/or text content. Matching is case-insensitive. Content matches include line numbers. Binary and very large files are skipped.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -356,7 +438,7 @@ export function filesystemToolDefinitions() {
         {
             name: 'get_file_info',
             annotations: READ_ONLY_ANNOTATIONS,
-            description: 'Stat a path. Returns { path, type, size, isFile, isDirectory, createdAt, modifiedAt }.',
+            description: 'Get a path\'s type, size, and creation and modification times.',
             inputSchema: {
                 type: 'object',
                 properties: { path: pathProp },
@@ -379,7 +461,7 @@ export function filesystemToolDefinitions() {
         {
             name: 'create_directory',
             annotations: WRITE_ANNOTATIONS,
-            description: 'Create a directory (recursively). Succeeds if it already exists. Returns { path, created }.',
+            description: 'Create a directory and any missing parents. Succeeds if it exists.',
             inputSchema: {
                 type: 'object',
                 properties: { path: pathProp },
@@ -394,7 +476,7 @@ export function filesystemToolDefinitions() {
         {
             name: 'move',
             annotations: DESTRUCTIVE_WRITE_ANNOTATIONS,
-            description: 'Move or rename a file/directory from "source" to "destination". Returns { source, destination }.',
+            description: 'Move or rename a file or directory.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -412,7 +494,7 @@ export function filesystemToolDefinitions() {
         {
             name: 'delete',
             annotations: DESTRUCTIVE_WRITE_ANNOTATIONS,
-            description: 'Delete a file or directory. Pass "recursive": true to remove a non-empty directory. Returns { path, deleted }.',
+            description: 'Delete a file or directory. Set recursive to true for a non-empty directory.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -430,12 +512,7 @@ export function filesystemToolDefinitions() {
         {
             name: 'get_allowed_directories',
             annotations: READ_ONLY_ANNOTATIONS,
-            description: 'Returns the list of directories that this filesystem MCP server is ' +
-                'currently allowed to access. The list is the merged result of ' +
-                'server-level roots (configured via FLUJO MCP settings), MCP-node-level ' +
-                'roots (set in the FlowBuilder), and the FLUJO_FS_ROOTS environment ' +
-                'variable ceiling. When no roots are configured at all, returns the FLUJO ' +
-                'data directory as the default (so the file browser is usable out of the box).',
+            description: 'List the directories this server is allowed to access.',
             inputSchema: {
                 type: 'object',
                 properties: {},
@@ -526,40 +603,28 @@ function mediaResult(filePath, buf, mediaType, mimeType) {
     };
     return result;
 }
-/**
- * Stream a file line-by-line and collect the lines that contain `needle`
- * (case-insensitive substring). Streaming means a match can be found without
- * buffering the whole file. Stops early once `max` matches are collected.
- */
-async function grepFileLines(filePath, needle, max) {
-    const lower = needle.toLowerCase();
-    const matches = [];
-    let truncated = false;
-    const stream = createReadStream(filePath, { encoding: 'utf8' });
-    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-    let lineNo = 0;
+function compileReadPattern(pattern) {
+    if (!pattern || pattern === '*')
+        return undefined;
+    if (pattern.length > MAX_READ_PATTERN_LENGTH) {
+        throw new Error(`Invalid regular expression: pattern exceeds the ${MAX_READ_PATTERN_LENGTH}-character limit.`);
+    }
     try {
-        for await (const line of rl) {
-            lineNo++;
-            if (line.toLowerCase().includes(lower)) {
-                matches.push({ line: lineNo, text: line.slice(0, 400) });
-                if (matches.length >= max) {
-                    truncated = true;
-                    break;
-                }
-            }
-        }
+        return new RegExp(pattern, 'i');
     }
-    finally {
-        rl.close();
-        stream.destroy();
+    catch (err) {
+        const detail = err instanceof Error
+            ? err.message.replace(/^Invalid regular expression:\s*/i, '')
+            : 'the pattern could not be compiled.';
+        throw new Error(`Invalid regular expression: ${detail}`);
     }
-    return { matches, truncated };
 }
 async function readSingleFileTool(args, roots) {
     const filePath = await resolvePath(args.path, roots);
     const hasRange = typeof args.from === 'number' || typeof args.to === 'number';
-    const pattern = typeof args.pattern === 'string' ? args.pattern.trim() : '';
+    const suppliedPattern = typeof args.pattern === 'string' ? args.pattern : '';
+    const pattern = suppliedPattern.trim() ? suppliedPattern : '';
+    const patternRegex = compileReadPattern(pattern);
     // #287: guard whole-file reads of large files. Stat first so we never buffer a
     // huge file just to reject it. An explicit line range or a `pattern` opts out.
     let stat;
@@ -629,10 +694,12 @@ async function readSingleFileTool(args, roots) {
         const content = buf.toString('utf8');
         const lines = splitLines(content);
         const totalLines = lines.length;
-        const lower = pattern.toLowerCase();
         const matches = [];
         for (let i = 0; i < lines.length; i++) {
-            if (lines[i].toLowerCase().includes(lower)) {
+            // The current expression has no stateful flags, but resetting lastIndex
+            // keeps this safe if flags change later.
+            patternRegex.lastIndex = 0;
+            if (patternRegex.test(lines[i])) {
                 matches.push({ line: i + 1, text: lines[i].slice(0, 400) });
                 if (matches.length >= MAX_READ_PATTERN_MATCHES)
                     break;
@@ -1157,103 +1224,368 @@ async function dirTreeTool(args, roots) {
     const tree = await walk(rootPath, 1);
     return dualResult({ path: rootPath, depth, truncated, tree });
 }
+function pathEnvironmentValue() {
+    const entry = Object.entries(process.env).find(([name]) => name.toLowerCase() === 'path');
+    return entry?.[1] ?? '';
+}
+/** Locate the installer-provided ripgrep without invoking a shell. */
+async function resolveRipgrepExecutable() {
+    if (ripgrepExecutableForTests !== undefined)
+        return ripgrepExecutableForTests;
+    const pathValue = pathEnvironmentValue();
+    if (ripgrepCache?.pathValue === pathValue)
+        return ripgrepCache.executable;
+    const names = process.platform === 'win32' ? ['rg.exe', 'rg'] : ['rg'];
+    let executable = null;
+    for (const rawDir of pathValue.split(path.delimiter)) {
+        const dir = rawDir.trim().replace(/^"(.*)"$/, '$1');
+        if (!dir)
+            continue;
+        for (const name of names) {
+            const candidate = path.join(dir, name);
+            try {
+                if ((await fs.stat(candidate)).isFile()) {
+                    executable = candidate;
+                    break;
+                }
+            }
+            catch {
+                /* not in this PATH directory */
+            }
+        }
+        if (executable)
+            break;
+    }
+    ripgrepCache = { pathValue, executable };
+    return executable;
+}
 /**
- * #287: content-scan one file for `needle`. Skips oversized and likely-binary
- * files up front (a huge perf/robustness win over reading every file whole),
- * then streams it line-by-line so a match is found without buffering the file.
+ * Fast content search using ripgrep's machine-readable stream. Hidden and
+ * ignored paths remain included to preserve the filesystem tool's historical
+ * semantics; callers can still narrow the root path for a smaller search.
+ * Returning null asks the caller to use the portable Node fallback.
  */
-async function scanFileContent(full, needle, remaining) {
-    let st;
+async function searchContentWithRipgrep(executable, rootPath, needle, limit, signal, onProgress) {
+    if (limit <= 0)
+        return { matches: [], truncated: true };
+    const args = [
+        '--json',
+        '--no-config',
+        '--fixed-strings',
+        '--ignore-case',
+        '--hidden',
+        '--no-ignore',
+        '--max-filesize', String(SEARCH_MAX_FILE_BYTES),
+        '--', needle, '.',
+    ];
+    let child;
     try {
-        st = await fs.stat(full);
+        child = spawn(executable, args, {
+            cwd: rootPath,
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
     }
     catch {
-        return [];
+        return null;
     }
-    if (!st.isFile() || st.size > SEARCH_MAX_FILE_BYTES)
-        return [];
-    // Binary sniff on the first chunk without loading the whole file.
+    activeRipgrepChildren.add(child);
+    let spawnError;
+    let cancelled = false;
+    let stderr = '';
+    child.stderr?.on('data', (chunk) => {
+        if (stderr.length < 8_000)
+            stderr += String(chunk).slice(0, 8_000 - stderr.length);
+    });
+    const closed = new Promise((resolve) => {
+        child.once('error', (error) => {
+            spawnError = error;
+            activeRipgrepChildren.delete(child);
+            resolve(null);
+        });
+        child.once('close', (code) => {
+            activeRipgrepChildren.delete(child);
+            resolve(code);
+        });
+    });
+    const onAbort = () => {
+        cancelled = true;
+        child.kill();
+    };
+    if (signal?.aborted)
+        onAbort();
+    else
+        signal?.addEventListener('abort', onAbort, { once: true });
+    if (!child.stdout) {
+        child.kill();
+        await closed;
+        signal?.removeEventListener('abort', onAbort);
+        return null;
+    }
+    const matches = [];
+    let files = 0;
+    let truncated = false;
+    let parseFailed = false;
+    const lines = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
     try {
-        const fh = await fs.open(full, 'r');
-        try {
-            const probe = Buffer.alloc(Math.min(8000, st.size));
-            if (probe.length)
-                await fh.read(probe, 0, probe.length, 0);
-            if (looksBinary(probe))
-                return [];
+        for await (const line of lines) {
+            if (!line)
+                continue;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                parseFailed = true;
+                break;
+            }
+            if (event.type === 'begin') {
+                files++;
+                onProgress?.({ phase: 'searching file contents', files });
+                continue;
+            }
+            if (event.type !== 'match')
+                continue;
+            const relativePath = event.data?.path?.text;
+            const text = event.data?.lines?.text;
+            const lineNumber = event.data?.line_number;
+            if (typeof relativePath !== 'string' || typeof text !== 'string' || typeof lineNumber !== 'number') {
+                continue;
+            }
+            matches.push({
+                path: path.isAbsolute(relativePath) ? path.resolve(relativePath) : path.resolve(rootPath, relativePath),
+                line: lineNumber,
+                text: text.replace(/\r?\n$/, '').slice(0, 400),
+            });
+            onProgress?.({ phase: 'searching file contents', files, matches: matches.length });
+            if (matches.length >= limit) {
+                truncated = true;
+                child.kill();
+                break;
+            }
         }
-        finally {
-            await fh.close();
+    }
+    finally {
+        lines.close();
+    }
+    if (parseFailed)
+        child.kill();
+    const exitCode = await closed;
+    signal?.removeEventListener('abort', onAbort);
+    if (cancelled)
+        throw new Error('Filesystem search cancelled.');
+    // ripgrep uses 0 for matches and 1 for a clean no-match result. A deliberate
+    // limit kill is also successful because the requested result budget is full.
+    if (spawnError || parseFailed || (!truncated && exitCode !== 0 && exitCode !== 1)) {
+        log.debug('ripgrep search failed; using Node fallback', {
+            error: spawnError?.message,
+            exitCode,
+            stderr: stderr.trim(),
+        });
+        return null;
+    }
+    return { matches, truncated };
+}
+/**
+ * Portable one-file scanner. One file descriptor provides the stat, binary
+ * probe, and text stream; the previous implementation opened every candidate
+ * twice in addition to a separate path stat.
+ */
+async function scanFileContent(full, needle, onMatch, shouldStop, signal) {
+    let handle;
+    let stream;
+    let lines;
+    const onAbort = () => {
+        lines?.close();
+        stream?.destroy(new Error('Filesystem search cancelled.'));
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        handle = await fs.open(full, 'r');
+        const st = await handle.stat();
+        if (!st.isFile() || st.size > SEARCH_MAX_FILE_BYTES || shouldStop())
+            return;
+        const probe = Buffer.alloc(Math.min(8_000, st.size));
+        if (probe.length)
+            await handle.read(probe, 0, probe.length, 0);
+        if (looksBinary(probe) || shouldStop())
+            return;
+        const lower = needle.toLowerCase();
+        stream = handle.createReadStream({ encoding: 'utf8', start: 0, autoClose: false });
+        lines = readline.createInterface({ input: stream, crlfDelay: Infinity });
+        let lineNo = 0;
+        for await (const line of lines) {
+            if (shouldStop())
+                break;
+            lineNo++;
+            if (line.toLowerCase().includes(lower)
+                && !onMatch({ path: full, line: lineNo, text: line.slice(0, 400) })) {
+                break;
+            }
         }
     }
     catch {
-        return [];
+        // Unreadable or concurrently removed files are skipped, matching the old search behavior.
     }
-    const { matches } = await grepFileLines(full, needle, Math.max(1, remaining));
-    return matches.map((m) => ({ path: full, line: m.line, text: m.text }));
-}
-async function searchTool(args, roots) {
-    const rootPath = await resolvePath(args.path, roots);
-    const namePattern = typeof args.namePattern === 'string' ? args.namePattern.toLowerCase() : '';
-    const contentPattern = typeof args.content === 'string' ? args.content : '';
-    if (!namePattern && !contentPattern) {
-        return errorResult('Provide "namePattern" and/or "content" to search for.');
+    finally {
+        signal?.removeEventListener('abort', onAbort);
+        lines?.close();
+        stream?.destroy();
+        await handle?.close().catch(() => undefined);
     }
-    const matches = [];
-    let truncated = false;
-    // First pass: walk the tree collecting NAME matches immediately and gathering
-    // the list of candidate files for a (possibly parallel) content scan.
-    const files = [];
-    async function walk(dir) {
-        if (truncated)
+}
+/** Dirent traversal plus a bounded, globally-budgeted content worker pool. */
+async function searchWithNode(rootPath, namePattern, contentPattern, limit, signal, onProgress) {
+    const nameMatches = [];
+    const contentMatches = [];
+    const active = new Set();
+    let nameLimitReached = false;
+    let contentLimitReached = false;
+    let directoriesScanned = 0;
+    let filesScanned = 0;
+    const shouldStopContent = () => signal?.aborted === true || nameLimitReached || contentMatches.length >= limit;
+    const scheduleContentScan = async (full) => {
+        if (!contentPattern || shouldStopContent())
             return;
-        let names;
-        try {
-            names = await fs.readdir(dir);
+        while (active.size >= SEARCH_CONCURRENCY && !shouldStopContent()) {
+            await Promise.race(active);
         }
-        catch {
+        if (shouldStopContent())
             return;
-        }
-        for (const name of names) {
-            if (truncated)
-                return;
-            const full = path.join(dir, name);
-            const type = await entryType(full);
-            if (namePattern && name.toLowerCase().includes(namePattern)) {
-                matches.push({ path: full });
-                if (matches.length >= MAX_SEARCH_RESULTS) {
-                    truncated = true;
-                    return;
-                }
+        const task = scanFileContent(full, contentPattern, (match) => {
+            if (contentMatches.length >= limit)
+                return false;
+            contentMatches.push(match);
+            if (contentMatches.length >= limit) {
+                contentLimitReached = true;
+                return false;
             }
-            if (type === 'directory') {
-                await walk(full);
+            return !nameLimitReached;
+        }, shouldStopContent, signal).finally(() => active.delete(task));
+        active.add(task);
+    };
+    // Bounded breadth-first traversal. The former recursive walk awaited every
+    // directory serially, which made name-only searches crawl on workspaces with
+    // many small folders even though the filesystem can serve independent reads
+    // concurrently.
+    const directories = [rootPath];
+    while (directories.length > 0
+        && !signal?.aborted
+        && !nameLimitReached
+        && (namePattern || !contentLimitReached)) {
+        const batch = directories.splice(0, SEARCH_DIRECTORY_CONCURRENCY);
+        const listings = await Promise.all(batch.map(async (dir) => {
+            try {
+                return { dir, entries: await fs.readdir(dir, { withFileTypes: true }) };
             }
-            else if (type === 'file' && contentPattern) {
-                files.push(full);
+            catch {
+                return { dir, entries: [] };
             }
-        }
-    }
-    await walk(rootPath);
-    // Second pass: scan file contents with bounded concurrency and early stop.
-    if (contentPattern && !truncated) {
-        for (let i = 0; i < files.length && !truncated; i += SEARCH_CONCURRENCY) {
-            const batch = files.slice(i, i + SEARCH_CONCURRENCY);
-            const results = await Promise.all(batch.map((full) => scanFileContent(full, contentPattern, MAX_SEARCH_RESULTS)));
-            for (const fileMatches of results) {
-                for (const m of fileMatches) {
-                    matches.push(m);
-                    if (matches.length >= MAX_SEARCH_RESULTS) {
-                        truncated = true;
+        }));
+        directoriesScanned += listings.length;
+        onProgress?.({
+            phase: contentPattern ? 'walking directories and scanning files' : 'searching names',
+            directories: directoriesScanned,
+            files: filesScanned,
+            matches: nameMatches.length + contentMatches.length,
+        });
+        for (const { dir, entries } of listings) {
+            for (const entry of entries) {
+                if (signal?.aborted || nameLimitReached || (!namePattern && contentLimitReached))
+                    break;
+                const full = path.join(dir, entry.name);
+                if (namePattern && entry.name.toLowerCase().includes(namePattern)) {
+                    nameMatches.push({ path: full });
+                    onProgress?.({ matches: nameMatches.length + contentMatches.length });
+                    if (nameMatches.length >= limit) {
+                        nameLimitReached = true;
                         break;
                     }
                 }
-                if (truncated)
-                    break;
+                let isDirectory = entry.isDirectory();
+                let isFile = entry.isFile();
+                // Dirent normally carries the type on Windows/macOS/Linux. Fall back only
+                // for filesystems that report an unknown type; never follow symlinks.
+                if (!isDirectory && !isFile && !entry.isSymbolicLink()) {
+                    const type = await entryType(full);
+                    isDirectory = type === 'directory';
+                    isFile = type === 'file';
+                }
+                if (isDirectory) {
+                    directories.push(full);
+                }
+                else if (isFile) {
+                    filesScanned++;
+                    if (contentPattern && !contentLimitReached)
+                        await scheduleContentScan(full);
+                }
             }
         }
     }
-    return dualResult({ matches, truncated });
+    await Promise.all(active);
+    onProgress?.({
+        directories: directoriesScanned,
+        files: filesScanned,
+        matches: nameMatches.length + contentMatches.length,
+    }, true);
+    const matches = [...nameMatches, ...contentMatches].slice(0, limit);
+    return {
+        matches,
+        truncated: nameLimitReached || contentLimitReached || nameMatches.length + contentMatches.length >= limit,
+    };
+}
+async function searchTool(args, roots, context) {
+    const signal = context?.signal;
+    if (signal?.aborted)
+        throw new Error('Filesystem search cancelled.');
+    const rootPath = await resolvePath(args.path, roots);
+    const namePattern = typeof args.namePattern === 'string' ? args.namePattern.toLowerCase() : '';
+    const contentPattern = typeof args.content === 'string' ? args.content : '';
+    if (!namePattern && !contentPattern) {
+        return errorResult('Provide "namePattern" and/or "content" to search for.');
+    }
+    const progress = createSearchProgressReporter(context);
+    progress.update({ phase: 'starting filesystem search' }, true);
+    try {
+        const ripgrep = contentPattern ? await resolveRipgrepExecutable() : null;
+        if (!ripgrep) {
+            const result = await searchWithNode(rootPath, namePattern, contentPattern, MAX_SEARCH_RESULTS, signal, progress.update);
+            if (signal?.aborted)
+                throw new Error('Filesystem search cancelled.');
+            progress.update({ phase: 'filesystem search complete', matches: result.matches.length }, true);
+            return dualResult(result);
+        }
+        // Name matches retain their historical priority in the combined response.
+        const names = namePattern
+            ? await searchWithNode(rootPath, namePattern, '', MAX_SEARCH_RESULTS, signal, progress.update)
+            : { matches: [], truncated: false };
+        if (signal?.aborted)
+            throw new Error('Filesystem search cancelled.');
+        if (names.truncated)
+            return dualResult(names);
+        const remaining = MAX_SEARCH_RESULTS - names.matches.length;
+        const content = await searchContentWithRipgrep(ripgrep, rootPath, contentPattern, remaining, signal, progress.update);
+        if (content) {
+            progress.update({
+                phase: 'filesystem search complete',
+                matches: names.matches.length + content.matches.length,
+            }, true);
+            return dualResult({
+                matches: [...names.matches, ...content.matches],
+                truncated: content.truncated || names.matches.length + content.matches.length >= MAX_SEARCH_RESULTS,
+            });
+        }
+        const fallback = await searchWithNode(rootPath, '', contentPattern, remaining, signal, progress.update);
+        if (signal?.aborted)
+            throw new Error('Filesystem search cancelled.');
+        return dualResult({
+            matches: [...names.matches, ...fallback.matches],
+            truncated: fallback.truncated || names.matches.length + fallback.matches.length >= MAX_SEARCH_RESULTS,
+        });
+    }
+    finally {
+        await progress.stop();
+    }
 }
 async function getFileInfoTool(args, roots) {
     const target = await resolvePath(args.path, roots);
@@ -1289,7 +1621,14 @@ async function deleteTool(args, roots) {
 async function getAllowedDirectoriesTool(roots) {
     return dualResult({ directories: roots });
 }
-export async function filesystemCallTool(toolName, args, callerNodeId) {
+export async function filesystemCallTool(toolName, args, callerNodeId, contextOrSignal) {
+    // Backwards-compatible direct-call shape: older callers/tests passed the
+    // AbortSignal itself as argument four.
+    const context = contextOrSignal
+        ? ('aborted' in contextOrSignal
+            ? { signal: contextOrSignal }
+            : contextOrSignal)
+        : undefined;
     try {
         // MCP App launcher (#97): pure UI trigger — returns immediately without
         // touching the filesystem. The app renders in chat; the user's pick returns
@@ -1310,7 +1649,7 @@ export async function filesystemCallTool(toolName, args, callerNodeId) {
             case 'dir_tree':
                 return await dirTreeTool(args, roots);
             case 'search':
-                return await searchTool(args, roots);
+                return await searchTool(args, roots, context);
             case 'get_file_info':
                 return await getFileInfoTool(args, roots);
             case 'create_directory':