centaurus-cli 2.9.3 → 2.9.5

package/dist/tools/grep-search.js

@@ -1,87 +1,164 @@
+import { spawn } from 'child_process';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import * as path from 'path';
 import * as fs from 'fs';
+import * as readline from 'readline';
 const execFileAsync = promisify(execFile);
+// ============================================================================
+// GREP SEARCH TOOL CLASS - CROSS-PLATFORM ROBUST IMPLEMENTATION
+// ============================================================================
 /**
- * GrepSearchTool - Search for text patterns across files in the codebase
+ * GrepSearchTool - Cross-platform text search with multiple backends
  *
- * Improvements over basic implementation:
- * 1. Security: Uses execFile to prevent shell injection
- * 2. Robustness: Handles binary files and encoding issues (via rg/grep)
- * 3. AI-Friendly Output: Formats results for easy parsing
- * 4. Fallback: Gracefully degrades from ripgrep -> grep -> findstr
+ * Backend priority:
+ * 1. ripgrep (fastest, cross-platform)
+ * 2. grep (Linux/macOS native)
+ * 3. PowerShell Select-String (Windows, good Unicode support)
+ * 4. Pure Node.js (universal fallback, no dependencies)
+ *
+ * Features:
+ * - Streaming output to handle large repos
+ * - Early abort when MAX_MATCHES reached
+ * - Proper encoding handling (UTF-8 with fallback)
+ * - CRLF normalization
+ * - Windows path support (drive letters, UNC)
  */
 export class GrepSearchTool {
-    static MAX_MATCHES = 50;
+    static DEFAULT_MAX_MATCHES = 50;
     static MAX_LINE_LENGTH = 300;
     static CONTEXT_LINES = 2;
+    static SEARCH_TIMEOUT = 30000;
+    // Cache tool availability to avoid repeated checks
+    static toolCache = new Map();
     /**
-     * Check if ripgrep is available
+     * Check if a command is available
      */
-    async hasRipgrep() {
+    async hasCommand(cmd, args = ['--version']) {
+        const cacheKey = `${cmd}:${args.join(',')}`;
+        if (GrepSearchTool.toolCache.has(cacheKey)) {
+            return GrepSearchTool.toolCache.get(cacheKey);
+        }
         try {
-            // Add timeout to prevent hanging
-            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), 2000));
             await Promise.race([
-                execFileAsync('rg', ['--version']),
-                timeoutPromise
+                execFileAsync(cmd, args, { timeout: 2000 }),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), 2000))
             ]);
+            GrepSearchTool.toolCache.set(cacheKey, true);
             return true;
         }
         catch {
+            GrepSearchTool.toolCache.set(cacheKey, false);
             return false;
         }
     }
-    /**
-     * Check if native grep is available (Linux/Mac)
-     */
+    async hasRipgrep() {
+        return this.hasCommand('rg', ['--version']);
+    }
     async hasGrep() {
-        try {
-            // Add timeout to prevent hanging
-            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), 2000));
-            await Promise.race([
-                execFileAsync('grep', ['--version']),
-                timeoutPromise
-            ]);
+        return this.hasCommand('grep', ['--version']);
+    }
+    async hasPowerShell() {
+        // Try pwsh first (PowerShell Core), then powershell (Windows PowerShell)
+        if (await this.hasCommand('pwsh', ['-Version']))
             return true;
+        if (process.platform === 'win32') {
+            return this.hasCommand('powershell', ['-Version']);
         }
-        catch {
-            return false;
-        }
+        return false;
+    }
+    /**
+     * Get the PowerShell executable name
+     */
+    async getPowerShellExe() {
+        if (await this.hasCommand('pwsh', ['-Version']))
+            return 'pwsh';
+        return 'powershell';
     }
     /**
-     * Normalize file path to use forward slashes
+     * Normalize file path to forward slashes
      */
     normalizePath(filePath) {
         return filePath.replace(/\\/g, '/');
     }
     /**
-     * Check if a file path matches the Includes patterns
-     * Returns true if there are no patterns or if the file matches at least one pattern
+     * Truncate long lines
+     */
+    truncateLine(line) {
+        if (line.length <= GrepSearchTool.MAX_LINE_LENGTH) {
+            return line;
+        }
+        return line.substring(0, GrepSearchTool.MAX_LINE_LENGTH) + ' [truncated]';
+    }
+    /**
+     * Normalize line endings (CRLF -> LF)
+     */
+    normalizeLineEndings(text) {
+        return text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    }
+    /**
+     * Parse file:line:content format robustly, handling Windows paths
+     * E.g., "C:\foo\bar.ts:42:content" or "/foo/bar.ts:42:content"
+     */
+    parseGrepLine(line) {
+        // Windows absolute path: C:\path\to\file:line:content
+        const m1 = line.match(/^([A-Za-z]:\\.+?):(\d+):(.*)$/);
+        if (m1)
+            return { file: m1[1], lineNum: +m1[2], content: m1[3] };
+        // UNC path: \\server\share\path:line:content
+        const m2 = line.match(/^(\\\\.+?):(\d+):(.*)$/);
+        if (m2)
+            return { file: m2[1], lineNum: +m2[2], content: m2[3] };
+        // Unix / relative path: /path/to/file:line:content or path/to/file:line:content
+        const m3 = line.match(/^(.+?):(\d+):(.*)$/);
+        if (m3)
+            return { file: m3[1], lineNum: +m3[2], content: m3[3] };
+        return null;
+    }
+    /**
+     * Create regex from pattern
+     */
+    createSearchRegex(pattern, isRegex, caseInsensitive) {
+        const flags = caseInsensitive ? 'gi' : 'g';
+        if (isRegex) {
+            try {
+                return new RegExp(pattern, flags);
+            }
+            catch {
+                // Invalid regex, escape and use as literal
+                return new RegExp(this.escapeRegex(pattern), flags);
+            }
+        }
+        return new RegExp(this.escapeRegex(pattern), flags);
+    }
+    /**
+     * Escape regex special characters
+     */
+    escapeRegex(str) {
+        return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    /**
+     * Check if file matches include patterns
      */
     matchesIncludesFilter(filePath, includes) {
         if (!includes || includes.length === 0) {
-            return true; // No filter, all files match
+            return true;
         }
         const fileName = path.basename(filePath);
         const normalizedPath = this.normalizePath(filePath);
         for (const pattern of includes) {
-            // Handle simple extension patterns like *.ts
             if (pattern.startsWith('*.')) {
-                const ext = pattern.substring(1); // Get ".ts" from "*.ts"
+                const ext = pattern.substring(1);
                 if (fileName.endsWith(ext)) {
                     return true;
                 }
             }
-            // Handle patterns like **/*.ts
             else if (pattern.includes('**')) {
                 const ext = pattern.replace('**/', '').replace('*', '');
                 if (fileName.endsWith(ext) || normalizedPath.includes(ext)) {
                     return true;
                 }
             }
-            // Handle direct matches
             else if (fileName === pattern || normalizedPath.includes(pattern)) {
                 return true;
             }
@@ -89,418 +166,591 @@ export class GrepSearchTool {
         return false;
     }
     /**
-     * Truncate long lines
+     * Check if file is likely binary
      */
-    truncateLine(line) {
-        if (line.length <= GrepSearchTool.MAX_LINE_LENGTH) {
-            return line;
-        }
-        return line.substring(0, GrepSearchTool.MAX_LINE_LENGTH) + ' [truncated]';
-    }
-    /**
-     * Execute search using ripgrep
-     */
-    async searchWithRipgrep(params, cwd) {
-        const args = [
-            '--json',
-            `--context=${GrepSearchTool.CONTEXT_LINES}`,
-            `--max-count=${GrepSearchTool.MAX_MATCHES}`,
-        ];
-        // Case sensitivity
-        if (!params.CaseInsensitive) {
-            // rg is case-sensitive by default, smart-case is default in CLI but maybe not here
-            // We want explicit case sensitivity unless CaseInsensitive is true
-            // Actually, rg is case-sensitive by default.
-        }
-        else {
-            args.push('--ignore-case');
-        }
-        // Fixed string vs Regex
-        if (!params.IsRegex) {
-            args.push('--fixed-strings');
-        }
-        // File pattern (Includes)
-        if (params.Includes && params.Includes.length > 0) {
-            params.Includes.forEach(pattern => {
-                args.push('--glob', pattern);
-            });
-        }
-        // Search Path (file or directory)
-        // rg takes the path as the last argument usually, or we can use it as root
-        // We'll pass it as an argument.
-        // Pattern
-        // We pass pattern after flags
-        args.push('--', params.Query);
-        // Path
-        args.push(params.SearchPath);
+    async isBinaryFile(filePath) {
         try {
-            const { stdout } = await execFileAsync('rg', args, { cwd, maxBuffer: 10 * 1024 * 1024 });
-            return this.parseRipgrepOutput(stdout, params.Query);
-        }
-        catch (error) {
-            // ripgrep returns exit code 1 when no matches found
-            if (error.code === 1) {
-                return {
-                    matches: [],
-                    totalMatches: 0,
-                    truncated: false,
-                    searchPattern: params.Query,
-                };
+            const fd = await fs.promises.open(filePath, 'r');
+            const buffer = Buffer.alloc(8192);
+            const { bytesRead } = await fd.read(buffer, 0, 8192, 0);
+            await fd.close();
+            // Check for null bytes (common in binary files)
+            for (let i = 0; i < bytesRead; i++) {
+                if (buffer[i] === 0)
+                    return true;
             }
-            throw error;
+            return false;
+        }
+        catch {
+            return true; // Assume binary on error
         }
     }
-    /**
-     * Parse ripgrep JSON output
-     */
-    parseRipgrepOutput(output, searchPattern) {
-        const lines = output.trim().split('\n').filter(line => line);
-        const matches = [];
-        let currentMatch = null;
-        let contextBefore = [];
-        let contextAfter = [];
-        let totalMatches = 0;
-        // Helper to finalize a match
-        const pushMatch = () => {
-            if (currentMatch && currentMatch.file && currentMatch.line !== undefined) {
-                matches.push({
-                    file: this.normalizePath(currentMatch.file),
-                    line: currentMatch.line,
-                    match: this.truncateLine(currentMatch.match || ''),
-                    contextBefore: contextBefore.map(l => this.truncateLine(l)),
-                    contextAfter: contextAfter.map(l => this.truncateLine(l)),
+    // ========================================================================
+    // RIPGREP BACKEND (Streaming)
+    // ========================================================================
+    async searchWithRipgrepStreaming(params, cwd) {
+        return new Promise((resolve, reject) => {
+            const args = [
+                '--json',
+                `--context=${GrepSearchTool.CONTEXT_LINES}`,
+            ];
+            if (params.CaseInsensitive) {
+                args.push('--ignore-case');
+            }
+            if (!params.IsRegex) {
+                args.push('--fixed-strings');
+            }
+            if (params.Includes && params.Includes.length > 0) {
+                params.Includes.forEach(pattern => {
+                    args.push('--glob', pattern);
                 });
-                currentMatch = null;
-                contextBefore = [];
-                contextAfter = [];
             }
-        };
-        for (const line of lines) {
-            try {
-                const data = JSON.parse(line);
-                if (data.type === 'match') {
-                    pushMatch(); // Push previous match if any
-                    totalMatches++;
-                    if (matches.length < GrepSearchTool.MAX_MATCHES) {
-                        const matchData = data.data;
-                        currentMatch = {
-                            file: matchData.path.text,
-                            line: matchData.line_number,
-                            match: matchData.lines.text.trimEnd(),
-                        };
-                    }
+            args.push('--', params.Query, params.SearchPath);
+            const matches = [];
+            let truncated = false;
+            let currentFile = null;
+            let contextQueue = [];
+            let pendingMatch = null;
+            let contextAfterCount = 0;
+            // RACECONDITION FIX: Guard against double-resolution
+            let finished = false;
+            const child = spawn('rg', args, {
+                cwd,
+                env: { ...process.env, LANG: 'en_US.UTF-8' }
+            });
+            const rl = readline.createInterface({ input: child.stdout });
+            // Robust cleanup function
+            const done = (result) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timer);
+                // TERMINATION FIX: Use simple kill() for Windows compatibility
+                child.kill();
+                rl.close();
+                resolve(result);
+            };
+            const fail = (err) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timer);
+                child.kill();
+                rl.close();
+                reject(err);
+            };
+            const timer = setTimeout(() => {
+                done({
+                    matches,
+                    totalMatches: matches.length,
+                    truncated: true,
+                    truncationReason: 'timeout',
+                    searchPattern: params.Query
+                });
+            }, GrepSearchTool.SEARCH_TIMEOUT);
+            rl.on('line', (line) => {
+                if (finished)
+                    return;
+                const maxMatches = params.MaxResults || GrepSearchTool.DEFAULT_MAX_MATCHES;
+                if (matches.length >= maxMatches) {
+                    truncated = true;
+                    // ABORT FIX: Immediately stop and resolve
+                    done({
+                        matches,
+                        totalMatches: matches.length,
+                        truncated,
+                        truncationReason: 'max_matches',
+                        searchPattern: params.Query
+                    });
+                    return;
                 }
-                else if (data.type === 'context') {
-                    const contextData = data.data;
-                    const contextLine = contextData.lines.text.trimEnd();
-                    if (currentMatch && currentMatch.line !== undefined) {
-                        // This is context AFTER the current match
-                        contextAfter.push(contextLine);
+                try {
+                    const event = JSON.parse(line);
+                    if (event.type === 'begin' && event.data?.path?.text) {
+                        currentFile = this.normalizePath(event.data.path.text);
+                        contextQueue = [];
+                        pendingMatch = null;
+                        contextAfterCount = 0;
                     }
-                    else {
-                        // This is context BEFORE the next match (or we are between matches)
-                        // Since rg --json streams, context before a match usually comes before the match event.
-                        // But wait, if we just finished a match, 'context' could be after.
-                        // Actually, rg JSON output structure:
-                        // context (before) -> match -> context (after)
-                        // But if matches are close, context after match 1 might be context before match 2.
-                        // For simplicity in this parser: 
-                        // If we have a currentMatch, this is context AFTER.
-                        // If we don't, this is context BEFORE.
-                        contextBefore.push(contextLine);
-                        // Keep only last N lines for 'before' context
-                        if (contextBefore.length > GrepSearchTool.CONTEXT_LINES) {
-                            contextBefore.shift();
+                    else if (event.type === 'context' && event.data?.lines?.text) {
+                        const ctxLine = {
+                            lineNumber: event.data.line_number,
+                            text: this.truncateLine(this.normalizeLineEndings(event.data.lines.text).trimEnd())
+                        };
+                        if (pendingMatch && contextAfterCount < GrepSearchTool.CONTEXT_LINES) {
+                            pendingMatch.contextAfter.push(ctxLine);
+                            contextAfterCount++;
                         }
+                        else {
+                            contextQueue.push(ctxLine);
+                            if (contextQueue.length > GrepSearchTool.CONTEXT_LINES) {
+                                contextQueue.shift();
+                            }
+                        }
+                    }
+                    else if (event.type === 'match' && event.data) {
+                        // Finalize previous match
+                        if (pendingMatch) {
+                            matches.push(pendingMatch);
+                        }
+                        const lineText = event.data.lines?.text || '';
+                        const submatches = event.data.submatches || [];
+                        pendingMatch = {
+                            file: currentFile || this.normalizePath(event.data.path?.text || ''),
+                            line: event.data.line_number,
+                            column: submatches.length > 0 ? submatches[0].start + 1 : undefined,
+                            byteOffset: event.data.absolute_offset,
+                            match: this.truncateLine(this.normalizeLineEndings(lineText).trimEnd()),
+                            matchIndices: submatches.map((s) => [s.start, s.end]),
+                            contextBefore: [...contextQueue],
+                            contextAfter: []
+                        };
+                        contextQueue = [];
+                        contextAfterCount = 0;
                     }
                 }
-                else if (data.type === 'end') {
-                    // End of a search result for a file?
-                    // rg emits 'end' stats.
-                    // We might need to flush the last match if context came after it.
-                    pushMatch();
+                catch {
+                    // Ignore parse errors
                 }
+            });
+            child.on('close', (code) => {
+                if (finished)
+                    return;
+                // Finalize last match
+                const maxMatches = params.MaxResults || GrepSearchTool.DEFAULT_MAX_MATCHES;
+                if (pendingMatch && matches.length < maxMatches) {
+                    matches.push(pendingMatch);
+                }
+                done({
+                    matches,
+                    totalMatches: matches.length,
+                    truncated,
+                    truncationReason: truncated ? 'max_matches' : undefined,
+                    searchPattern: params.Query
+                });
+            });
+            child.on('error', (err) => {
+                fail(err);
+            });
+        });
+    }
+    // ========================================================================
+    // GREP BACKEND (Streaming)
+    // ========================================================================
+    async searchWithGrepStreaming(params, cwd) {
+        return new Promise((resolve, reject) => {
+            const args = [
+                '-n', // line numbers
+                '-r', // recursive
+                `--context=${GrepSearchTool.CONTEXT_LINES}`,
+            ];
+            if (params.CaseInsensitive) {
+                args.push('-i');
             }
-            catch (parseError) {
-                continue;
+            if (!params.IsRegex) {
+                args.push('-F'); // fixed strings
             }
-        }
-        pushMatch(); // Ensure flush
-        return {
-            matches,
-            totalMatches,
-            truncated: totalMatches > matches.length,
-            searchPattern,
-        };
+            else {
+                args.push('-E'); // extended regex (supports |)
+            }
+            if (params.Includes && params.Includes.length > 0) {
+                params.Includes.forEach(pattern => {
+                    args.push('--include', pattern);
+                });
+            }
+            args.push(params.Query, params.SearchPath);
+            const matches = [];
+            let truncated = false;
+            let finished = false;
+            const child = spawn('grep', args, {
+                cwd,
+                env: { ...process.env, LANG: 'en_US.UTF-8' }
+            });
+            const rl = readline.createInterface({ input: child.stdout });
+            const done = (result) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timer);
+                child.kill();
+                rl.close();
+                resolve(result);
+            };
+            const fail = (err) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timer);
+                child.kill();
+                rl.close();
+                reject(err);
+            };
+            const timer = setTimeout(() => {
+                done({
+                    matches,
+                    totalMatches: matches.length,
+                    truncated: true,
+                    truncationReason: 'timeout',
+                    searchPattern: params.Query
+                });
+            }, GrepSearchTool.SEARCH_TIMEOUT);
+            rl.on('line', (line) => {
+                if (finished)
+                    return;
+                const maxMatches = params.MaxResults || GrepSearchTool.DEFAULT_MAX_MATCHES;
+                if (matches.length >= maxMatches) {
+                    truncated = true;
+                    done({
+                        matches,
+                        totalMatches: matches.length,
+                        truncated,
+                        truncationReason: 'max_matches',
+                        searchPattern: params.Query
+                    });
+                    return;
+                }
+                const normalizedLine = this.normalizeLineEndings(line);
+                // Skip separator lines
+                if (normalizedLine === '--')
+                    return;
+                const parsed = this.parseGrepLine(normalizedLine);
+                if (parsed) {
+                    // For grep, we treat each line as a match (context handling is simpler)
+                    matches.push({
+                        file: this.normalizePath(parsed.file),
+                        line: parsed.lineNum,
+                        match: this.truncateLine(parsed.content),
+                        contextBefore: [],
+                        contextAfter: []
+                    });
+                }
+            });
+            child.on('close', () => {
+                if (finished)
+                    return;
+                done({
+                    matches,
+                    totalMatches: matches.length,
+                    truncated,
+                    truncationReason: truncated ? 'max_matches' : undefined,
+                    searchPattern: params.Query
+                });
+            });
+            child.on('error', (err) => fail(err));
+        });
     }
-    /**
-     * Execute search using native grep (Linux/Mac)
-     */
-    async searchWithGrep(params, cwd) {
-        const args = ['-rn'];
-        // Case sensitivity
-        if (params.CaseInsensitive) {
-            args.push('-i');
+    // ========================================================================
+    // POWERSHELL BACKEND (Windows)
+    // ========================================================================
+    async searchWithPowerShell(params, cwd) {
+        const psExe = await this.getPowerShellExe();
+        // Build the PowerShell command
+        // Select-String supports regex by default, -SimpleMatch for literal
+        const patternArg = params.IsRegex ? params.Query : params.Query.replace(/'/g, "''");
+        const searchPath = path.resolve(cwd, params.SearchPath);
+        let psCommand;
+        // Check if searching a file or directory
+        const stats = await fs.promises.stat(searchPath).catch(() => null);
+        const isDirectory = stats?.isDirectory() ?? false;
+        // PATH FIX: Use $_.Path instead of $_.Filename for absolute paths
+        if (isDirectory) {
+            // Search directory recursively
+            const includePattern = params.Includes && params.Includes.length > 0
+                ? params.Includes.map(p => `'${p}'`).join(',')
+                : "'*'";
+            const max = params.MaxResults || GrepSearchTool.DEFAULT_MAX_MATCHES;
+            psCommand = params.IsRegex
+                ? `Get-ChildItem -Path '${searchPath}' -Recurse -File -Include ${includePattern} -ErrorAction SilentlyContinue | Select-String -Pattern '${patternArg}'${params.CaseInsensitive ? '' : ' -CaseSensitive'} -Context ${GrepSearchTool.CONTEXT_LINES} | Select-Object -First ${max} | ForEach-Object { $_.Path + ':' + $_.LineNumber + ':' + $_.Line }`
+                : `Get-ChildItem -Path '${searchPath}' -Recurse -File -Include ${includePattern} -ErrorAction SilentlyContinue | Select-String -Pattern '${patternArg}' -SimpleMatch${params.CaseInsensitive ? '' : ' -CaseSensitive'} -Context ${GrepSearchTool.CONTEXT_LINES} | Select-Object -First ${max} | ForEach-Object { $_.Path + ':' + $_.LineNumber + ':' + $_.Line }`;
         }
-        // Context lines
-        args.push(`--context=${GrepSearchTool.CONTEXT_LINES}`);
-        // Includes
-        if (params.Includes && params.Includes.length > 0) {
-            params.Includes.forEach(pattern => {
-                args.push(`--include=${pattern}`);
+        else {
+            // Search single file
+            const max = params.MaxResults || GrepSearchTool.DEFAULT_MAX_MATCHES;
+            psCommand = params.IsRegex
+                ? `Select-String -Path '${searchPath}' -Pattern '${patternArg}'${params.CaseInsensitive ? '' : ' -CaseSensitive'} -Context ${GrepSearchTool.CONTEXT_LINES} | Select-Object -First ${max} | ForEach-Object { $_.Path + ':' + $_.LineNumber + ':' + $_.Line }`
+                : `Select-String -Path '${searchPath}' -Pattern '${patternArg}' -SimpleMatch${params.CaseInsensitive ? '' : ' -CaseSensitive'} -Context ${GrepSearchTool.CONTEXT_LINES} | Select-Object -First ${max} | ForEach-Object { $_.Path + ':' + $_.LineNumber + ':' + $_.Line }`;
+        }
+        return new Promise((resolve, reject) => {
+            const matches = [];
+            let truncated = false;
+            let finished = false;
+            const child = spawn(psExe, ['-NoProfile', '-Command', psCommand], {
+                cwd,
+                env: { ...process.env }
             });
-        }
-        // Fixed string vs Regex
-        if (!params.IsRegex) {
-            args.push('-F');
-        }
-        // Pattern
-        args.push(params.Query);
-        // Path
-        args.push(params.SearchPath);
-        try {
-            const { stdout } = await execFileAsync('grep', args, { cwd, maxBuffer: 10 * 1024 * 1024 });
-            return this.parseGrepOutput(stdout, params.Query);
-        }
-        catch (error) {
-            if (error.code === 1) {
-                return {
-                    matches: [],
-                    totalMatches: 0,
-                    truncated: false,
-                    searchPattern: params.Query,
-                };
-            }
-            throw error;
-        }
+            // Robust cleanup function
+            const done = (result) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timer);
+                child.kill();
+                resolve(result);
+            };
+            const fail = (err) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timer);
+                child.kill();
+                reject(err);
+            };
+            const timer = setTimeout(() => {
+                done({
+                    matches,
+                    totalMatches: matches.length,
+                    truncated: true,
+                    truncationReason: 'timeout',
+                    searchPattern: params.Query
+                });
+            }, GrepSearchTool.SEARCH_TIMEOUT);
+            let stdout = '';
+            let stderr = '';
+            child.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+            child.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+            child.on('close', (code) => {
+                if (finished)
+                    return;
+                const lines = this.normalizeLineEndings(stdout).split('\n').filter(l => l.trim());
+                for (const line of lines) {
+                    const maxMatches = params.MaxResults || GrepSearchTool.DEFAULT_MAX_MATCHES;
+                    if (matches.length >= maxMatches) {
+                        truncated = true;
+                        break;
+                    }
+                    const parsed = this.parseGrepLine(line);
+                    if (parsed) {
+                        matches.push({
+                            file: this.normalizePath(parsed.file),
+                            line: parsed.lineNum,
+                            match: this.truncateLine(parsed.content),
+                            contextBefore: [],
+                            contextAfter: []
+                        });
+                    }
+                }
+                done({
+                    matches,
+                    totalMatches: matches.length,
+                    truncated,
+                    truncationReason: truncated ? 'max_matches' : undefined,
+                    searchPattern: params.Query
+                });
+            });
+            child.on('error', (err) => fail(err));
+        });
     }
-    parseGrepOutput(output, searchPattern) {
-        // Grep output with context:
-        // file:line:match
-        // file-line-context
-        // -- (separator)
-        const lines = output.trim().split('\n');
+    // ========================================================================
+    // PURE NODE.JS BACKEND (Universal Fallback)
+    // ========================================================================
+    async searchWithNodeJS(params, cwd) {
         const matches = [];
-        // Simple parsing strategy: group by file and proximity
-        // For robust parsing similar to rg, we'd need more complex logic.
-        // Given the constraints, we'll do a best-effort parse.
-        let currentMatch = null;
-        let contextBefore = [];
-        let contextAfter = [];
-        const pushMatch = () => {
-            if (currentMatch && currentMatch.file && currentMatch.line !== undefined) {
-                matches.push({
-                    file: this.normalizePath(currentMatch.file),
-                    line: currentMatch.line,
-                    match: this.truncateLine(currentMatch.match || ''),
-                    contextBefore: contextBefore.map(l => this.truncateLine(l)),
-                    contextAfter: contextAfter.map(l => this.truncateLine(l)),
-                });
-                currentMatch = null;
-                contextBefore = [];
-                contextAfter = [];
+        let truncated = false;
+        let filesSearched = 0;
+        let encodingFallback = false;
+        const searchPath = path.resolve(cwd, params.SearchPath);
+        const regex = this.createSearchRegex(params.Query, params.IsRegex ?? false, params.CaseInsensitive ?? false);
+        // Collect files to search
+        const filesToSearch = [];
+        const stats = await fs.promises.stat(searchPath).catch(() => null);
+        if (!stats) {
+            return { matches: [], totalMatches: 0, truncated: false, searchPattern: params.Query };
+        }
+        if (stats.isFile()) {
+            filesToSearch.push(searchPath);
+        }
+        else if (stats.isDirectory()) {
+            await this.collectFiles(searchPath, filesToSearch, params.Includes);
+        }
+        // Search each file
+        const maxMatches = params.MaxResults || GrepSearchTool.DEFAULT_MAX_MATCHES;
+        for (const filePath of filesToSearch) {
+            if (matches.length >= maxMatches) {
+                truncated = true;
+                break;
             }
-        };
-        for (const line of lines) {
-            if (line === '--') {
-                pushMatch();
+            // Skip binary files
+            if (await this.isBinaryFile(filePath)) {
                 continue;
             }
-            // Match: file:line:content
-            const matchRegex = /^([^:]+):(\d+):(.*)$/;
-            // Context: file-line-content
-            const contextRegex = /^([^:]+)-(\d+)-(.*)$/;
-            const matchM = line.match(matchRegex);
-            const contextM = line.match(contextRegex);
-            if (matchM) {
-                pushMatch(); // Flush previous
-                currentMatch = {
-                    file: matchM[1],
-                    line: parseInt(matchM[2], 10),
-                    match: matchM[3]
-                };
-            }
-            else if (contextM) {
-                if (currentMatch) {
-                    contextAfter.push(contextM[3]);
+            filesSearched++;
+            try {
+                let content;
+                const buffer = await fs.promises.readFile(filePath);
+                // Try UTF-8 first
+                try {
+                    content = buffer.toString('utf8');
+                    // Check for replacement characters indicating decode failure
+                    if (content.includes('\uFFFD')) {
+                        content = buffer.toString('latin1');
+                        encodingFallback = true;
+                    }
+                }
+                catch {
+                    content = buffer.toString('latin1');
+                    encodingFallback = true;
                 }
-                else {
-                    contextBefore.push(contextM[3]);
-                    if (contextBefore.length > GrepSearchTool.CONTEXT_LINES)
-                        contextBefore.shift();
+                const lines = this.normalizeLineEndings(content).split('\n');
+                for (let i = 0; i < lines.length; i++) {
+                    if (matches.length >= maxMatches) {
+                        truncated = true;
+                        break;
+                    }
+                    const line = lines[i];
+                    regex.lastIndex = 0; // Reset regex state
+                    // LOOP FIX: Capture all matches in the line, not just the first
+                    let matchResult;
+                    while ((matchResult = regex.exec(line)) !== null) {
+                        // Prevent infinite loops with zero-width matches
+                        if (matchResult.index === regex.lastIndex) {
+                            regex.lastIndex++;
+                        }
+                        const relativePath = path.relative(cwd, filePath);
+                        // Collect context
+                        const contextBefore = [];
+                        const contextAfter = [];
+                        for (let j = Math.max(0, i - GrepSearchTool.CONTEXT_LINES); j < i; j++) {
+                            contextBefore.push({
+                                lineNumber: j + 1,
+                                text: this.truncateLine(lines[j])
+                            });
+                        }
+                        for (let j = i + 1; j <= Math.min(lines.length - 1, i + GrepSearchTool.CONTEXT_LINES); j++) {
+                            contextAfter.push({
+                                lineNumber: j + 1,
+                                text: this.truncateLine(lines[j])
+                            });
+                        }
+                        matches.push({
+                            file: this.normalizePath(relativePath),
+                            line: i + 1,
+                            column: matchResult.index + 1,
+                            match: this.truncateLine(line),
+                            contextBefore,
+                            contextAfter
+                        });
+                        if (matches.length >= maxMatches) {
+                            truncated = true;
+                            break;
+                        }
+                    }
+                    if (truncated)
+                        break;
                 }
             }
+            catch {
+                // Skip files that can't be read
+            }
         }
-        pushMatch();
         return {
-            matches: matches.slice(0, GrepSearchTool.MAX_MATCHES),
-            totalMatches: matches.length, // grep doesn't give total easily without another run
-            truncated: matches.length >= GrepSearchTool.MAX_MATCHES,
-            searchPattern
+            matches,
+            totalMatches: matches.length,
+            truncated,
+            truncationReason: truncated ? 'max_matches' : undefined,
+            searchPattern: params.Query,
+            filesSearched,
+            encodingFallback
         };
     }
     /**
-     * Execute search using findstr (Windows)
-     * NOTE: Context is DISABLED for findstr to avoid performance/encoding issues.
+     * Recursively collect files from directory
      */
-    async searchWithFindstr(params, cwd) {
-        const args = [
-            '/N', // Print line numbers
-            '/S', // Recursive
-        ];
-        if (params.CaseInsensitive) {
-            args.push('/I');
-        }
-        // findstr doesn't support full regex, only limited.
-        // If IsRegex is true, we might be limited.
-        if (!params.IsRegex) {
-            args.push('/L'); // Literal search
-        }
-        else {
-            args.push('/R'); // Regex search
-        }
-        // Pattern
-        args.push('/C:' + params.Query);
-        // File mask
-        // findstr [options] strings [drive:][path]filename[...]
-        // We can pass the path/mask at the end.
-        // If Includes is set, we can try to use it, but findstr is limited.
-        // We'll just use SearchPath and optional Includes if it's a simple extension.
-        let searchMask = '*.*';
-        if (params.Includes && params.Includes.length === 1 && params.Includes[0].startsWith('*.')) {
-            searchMask = params.Includes[0];
-        }
-        // If SearchPath is a directory, append mask. If file, use it.
-        let target = params.SearchPath;
+    async collectFiles(dir, files, includes, maxFiles = 10000) {
+        if (files.length >= maxFiles)
+            return;
         try {
-            const stats = await fs.promises.stat(path.resolve(cwd, params.SearchPath));
-            if (stats.isDirectory()) {
-                target = path.join(params.SearchPath, searchMask);
+            const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (files.length >= maxFiles)
+                    break;
+                const fullPath = path.join(dir, entry.name);
+                // Skip common non-code directories
+                if (entry.isDirectory()) {
+                    if (['node_modules', '.git', 'dist', 'build', '__pycache__', '.vscode', '.idea'].includes(entry.name)) {
+                        continue;
+                    }
+                    await this.collectFiles(fullPath, files, includes, maxFiles);
+                }
+                else if (entry.isFile()) {
+                    if (this.matchesIncludesFilter(fullPath, includes)) {
+                        files.push(fullPath);
+                    }
+                }
             }
         }
         catch {
-            // Assume it's a pattern or file that doesn't exist yet? 
-            // Just pass it as is.
+            // Ignore directories that can't be read
         }
-        args.push(target);
-        try {
-            // Use execFile with 'findstr'
-            const { stdout } = await execFileAsync('findstr', args, { cwd, maxBuffer: 10 * 1024 * 1024 });
-            return this.parseFindstrOutput(stdout, params.Query);
-        }
-        catch (error) {
-            if (error.code === 1) {
-                return { matches: [], totalMatches: 0, truncated: false, searchPattern: params.Query };
-            }
-            throw error;
-        }
-    }
-    parseFindstrOutput(output, searchPattern) {
-        const lines = output.trim().split('\r\n'); // Windows line endings
-        const matches = [];
-        for (const line of lines) {
-            if (!line)
-                continue;
-            // findstr output format with /N /S flags:
-            // C:\path\to\file.ts:1:content
-            // 
-            // Windows paths start with drive letter like "C:" so we need to be careful
-            // about finding the line number delimiter
-            // Strategy: Find the pattern ":digits:" after the path
-            // On Windows, paths have \ not : except for drive letter
-            // So we look for the last occurrence of ":\d+:" pattern
-            const lineNumMatch = line.match(/:(\d+):/);
-            if (lineNumMatch && lineNumMatch.index !== undefined) {
-                // Everything before the match is the file path
-                const file = line.substring(0, lineNumMatch.index);
-                const lineNum = parseInt(lineNumMatch[1], 10);
-                // Everything after the ":linenum:" is the content
-                const colonAfterLineNum = lineNumMatch.index + lineNumMatch[0].length;
-                const content = line.substring(colonAfterLineNum);
-                matches.push({
-                    file: this.normalizePath(file),
-                    line: lineNum,
-                    match: this.truncateLine(content),
-                    contextBefore: [], // No context for findstr
-                    contextAfter: []
-                });
-            }
-        }
-        return {
-            matches: matches.slice(0, GrepSearchTool.MAX_MATCHES),
-            totalMatches: matches.length,
-            truncated: matches.length >= GrepSearchTool.MAX_MATCHES,
-            searchPattern
-        };
     }
-    /**
-     * Execute the grep search
-     */
+    // ========================================================================
+    // MAIN EXECUTE METHOD
+    // ========================================================================
     async execute(params, cwd) {
         let result;
-        // Add overall timeout for the search operation (30 seconds)
-        const searchTimeout = 30000;
-        const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Search operation timed out after 30 seconds')), searchTimeout));
+        let backend;
         try {
-            result = await Promise.race([
-                (async () => {
-                    // Try ripgrep first
-                    if (await this.hasRipgrep()) {
-                        return await this.searchWithRipgrep(params, cwd);
-                    }
-                    // Try native grep (Linux/Mac)
-                    else if (await this.hasGrep()) {
-                        return await this.searchWithGrep(params, cwd);
-                    }
-                    // Fall back to findstr (Windows)
-                    else if (process.platform === 'win32') {
-                        return await this.searchWithFindstr(params, cwd);
-                    }
-                    else {
-                        throw new Error('No search tool available. Please install ripgrep for better performance: https://github.com/BurntSushi/ripgrep');
-                    }
-                })(),
-                timeoutPromise
-            ]);
+            // Try backends in order of preference
+            if (await this.hasRipgrep()) {
+                backend = 'ripgrep';
+                result = await this.searchWithRipgrepStreaming(params, cwd);
+            }
+            else if (await this.hasGrep()) {
+                backend = 'grep';
+                result = await this.searchWithGrepStreaming(params, cwd);
+            }
+            else if (process.platform === 'win32' && await this.hasPowerShell()) {
+                backend = 'powershell';
+                result = await this.searchWithPowerShell(params, cwd);
+            }
+            else {
+                // Universal Node.js fallback
+                backend = 'nodejs';
+                result = await this.searchWithNodeJS(params, cwd);
+            }
         }
         catch (error) {
-            if (error.message.includes('timed out')) {
-                throw new Error('Search operation timed out. Try narrowing your search path or using more specific patterns.');
+            // If primary backend fails, try fallback
+            try {
+                backend = 'nodejs';
+                result = await this.searchWithNodeJS(params, cwd);
+            }
+            catch (fallbackError) {
+                throw new Error(`Search failed: ${error.message}. Fallback also failed: ${fallbackError.message}`);
             }
-            throw error;
         }
-        // Apply post-filtering for Includes patterns (ensures robust filtering across all backends)
-        if (params.Includes && params.Includes.length > 0) {
+        // Apply post-filtering for Includes if backend didn't support it
+        if (params.Includes && params.Includes.length > 0 && backend === 'nodejs') {
             const filteredMatches = result.matches.filter(match => this.matchesIncludesFilter(match.file, params.Includes));
             return {
+                ...result,
                 matches: filteredMatches,
                 totalMatches: filteredMatches.length,
-                truncated: result.truncated && filteredMatches.length >= GrepSearchTool.MAX_MATCHES,
-                searchPattern: result.searchPattern,
+                backend
             };
         }
-        return result;
+        return { ...result, backend };
     }
 }
-/**
- * Format grep search results for AI consumption
- *
- * Format:
- * filename
- * line:   context
- * line:>  match
- * line:   context
- */
+// ============================================================================
+// FORMATTING FUNCTION
+// ============================================================================
 function formatGrepResults(result) {
     if (result.matches.length === 0) {
         return `No matches found for pattern "${result.searchPattern}"`;
     }
+    const uniqueFiles = new Set();
+    result.matches.forEach(match => uniqueFiles.add(match.file));
+    const fileCount = uniqueFiles.size;
     const output = [];
-    output.push(`Found ${result.totalMatches} match${result.totalMatches === 1 ? '' : 'es'} for pattern "${result.searchPattern}"`);
+    output.push(`Found ${result.uniqueMatchesCount} match${result.uniqueMatchesCount === 1 ? '' : 'es'} in ${fileCount} file${fileCount === 1 ? '' : 's'} for pattern "${result.searchPattern}"`);
     if (result.truncated) {
-        output.push(`(showing first ${result.matches.length} matches)`);
+        const reason = result.truncationReason === 'timeout' ? '(timed out)' : '';
+        output.push(`(showing first ${result.matches.length} matches${reason ? ' ' + reason : ''})`);
     }
-    // Group by file
     const matchesByFile = new Map();
     result.matches.forEach(match => {
         if (!matchesByFile.has(match.file)) {
@@ -511,35 +761,93 @@ function formatGrepResults(result) {
     matchesByFile.forEach((matches, file) => {
         output.push(`\n${file}`);
         matches.forEach(match => {
-            // Context Before
-            match.contextBefore.forEach((ctx, idx) => {
-                // Calculate line number for context if possible?
-                // rg json gives line numbers for context, but our interface simplified it.
-                // We'll just print it without line number or with a placeholder if we don't have it.
-                // Actually, for AI parsing, it's better to have line numbers.
-                // But if we don't have them (grep/findstr), we shouldn't fake them incorrectly.
-                // However, rg gives them. 
-                // Let's just indent context.
-                // Wait, user requested: "48:   function..."
-                // If we don't have line numbers for context, maybe we should skip context or just indent?
-                // "Use line numbers explicitly for every line."
-                // Since we might not have them for context in all cases, let's try to infer or just use indentation.
-                // For the match, we definitely have the line number.
-                // Let's assume context lines are immediately preceding.
-                const startLine = match.line - match.contextBefore.length;
-                output.push(`${startLine + idx}:   ${ctx}`);
+            match.contextBefore.forEach(ctx => {
+                output.push(`${ctx.lineNumber}:   ${ctx.text}`);
             });
-            // Match
-            output.push(`${match.line}:>  ${match.match}`);
-            // Context After
-            match.contextAfter.forEach((ctx, idx) => {
-                output.push(`${match.line + 1 + idx}:   ${ctx}`);
+            const columnInfo = match.column ? ` (col ${match.column})` : '';
+            output.push(`${match.line}:>  ${match.match}${columnInfo}`);
+            match.contextAfter.forEach(ctx => {
+                output.push(`${ctx.lineNumber}:   ${ctx.text}`);
             });
-            // Separator if needed? AI usually handles blocks well.
         });
     });
     return output.join('\n');
 }
+// ============================================================================
+// REMOTE SEARCH HELPER
+// ============================================================================
+/**
+ * Execute grep search on a remote system via ContextManager
+ * Used for SSH/Docker/WSL environments
+ */
+async function searchRemote(params, contextManager) {
+    const maxMatches = params.MaxResults || GrepSearchTool.DEFAULT_MAX_MATCHES;
+    // Escape the query for shell usage
+    const escapedQuery = params.Query.replace(/'/g, "'\\''");
+    // First, check if the path is a file or directory to use correct grep flags
+    // Use test -d to check if it's a directory
+    const checkResult = await contextManager.executeCommand(`test -d "${params.SearchPath}" && echo "dir" || echo "file"`, 5000);
+    const isDirectory = checkResult.stdout.trim() === 'dir';
+    // Build grep command - use -r only for directories, -H to always show filename
+    let grepArgs = isDirectory ? '-rn' : '-Hn'; // -H for filename, -n for line numbers, -r for recursive
+    if (params.CaseInsensitive) {
+        grepArgs += 'i';
+    }
+    if (!params.IsRegex) {
+        grepArgs += 'F'; // fixed strings (literal)
+    }
+    // Add include patterns if specified (only useful for directories)
+    let includeArgs = '';
+    if (isDirectory && params.Includes && params.Includes.length > 0) {
+        includeArgs = params.Includes.map(p => `--include='${p}'`).join(' ');
+    }
+    // Build the full command with result limit
+    const command = `grep ${grepArgs} ${includeArgs} '${escapedQuery}' "${params.SearchPath}" 2>/dev/null | head -n ${maxMatches}`;
+    try {
+        const result = await contextManager.executeCommand(command, 30000);
+        const matches = [];
+        const lines = result.stdout.split('\n').filter(line => line.trim());
+        for (const line of lines) {
+            // Parse grep output: file:line:content
+            const match = line.match(/^(.+?):(\d+):(.+)$/);
+            if (match) {
+                // Truncate long lines
+                let content = match[3];
+                if (content.length > 300) {
+                    content = content.substring(0, 300) + ' [truncated]';
+                }
+                matches.push({
+                    file: match[1],
+                    line: parseInt(match[2], 10),
+                    match: content,
+                    contextBefore: [],
+                    contextAfter: [],
+                });
+            }
+        }
+        return {
+            matches,
+            totalMatches: matches.length,
+            truncated: matches.length >= maxMatches,
+            truncationReason: matches.length >= maxMatches ? 'max_matches' : undefined,
+            searchPattern: params.Query,
+            backend: 'remote',
+        };
+    }
+    catch (error) {
+        // If grep fails (command not found, permission denied, etc.), return empty result
+        return {
+            matches: [],
+            totalMatches: 0,
+            truncated: false,
+            searchPattern: params.Query,
+            backend: 'remote',
+        };
+    }
+}
+// ============================================================================
+// TOOL EXPORT
+// ============================================================================
 export const grepSearchTool = {
     schema: {
         name: 'grep_search',
@@ -558,7 +866,7 @@ MULTI-WORD SEARCH: When you search for "control system", this tool will automati
 Results are returned with file paths and line numbers:
 filename
 line:   context
-line:>  match
+line:>  match (col X)
 line:   context
 
 NOT for: Finding files/folders by NAME. Use find_files for that instead.
@@ -583,9 +891,13 @@ Total results are capped at 50 matches. Use Includes to filter by file type.`,
                     description: 'Glob patterns to filter files (e.g. ["*.ts"]).',
                     items: { type: 'string' }
                 },
+                MaxResults: {
+                    type: 'number',
+                    description: 'Optional: Maximum number of results to return. Default is 50. Increase this if you need to see more matches.',
+                },
                 CaseInsensitive: {
                     type: 'boolean',
-                    description: 'If true, performs a case-insensitive search. Default: false',
+                    description: 'If true, performs a case-insensitive search. Default: false (case-sensitive)',
                 },
                 IsRegex: {
                     type: 'boolean',
@@ -597,57 +909,93 @@ Total results are capped at 50 matches. Use Includes to filter by file type.`,
     },
     async execute(args, context) {
         const tool = new GrepSearchTool();
-        // Check if query has multiple words for multi-term search
+        const startTime = Date.now();
         const query = args.Query;
         const words = query.trim().split(/\s+/).filter(w => w.length > 2);
-        // If query has multiple words, search for combined AND individual terms
         const allMatches = [];
-        const seenMatches = new Set(); // Deduplicate by file:line
-        let totalMatches = 0;
-        // Build list of queries to run
-        const queries = [query]; // Always search for the full query first
+        const seenMatches = new Set();
+        const matchesPerQuery = {};
+        const queriesExecuted = [];
+        let rawTotalMatches = 0;
+        let backend = 'ripgrep';
+        let truncated = false;
+        let truncationReason;
+        let encodingFallback = false;
+        const queries = [query];
         if (words.length > 1 && !args.IsRegex) {
-            // Add individual words as additional searches
             for (const word of words) {
                 if (word !== query) {
                     queries.push(word);
                 }
             }
         }
+        // Check if we're in a remote context (SSH, Docker, WSL)
+        const contextManager = context.contextManager;
+        const currentContext = contextManager?.getCurrentContext();
+        const isRemote = currentContext && currentContext.type !== 'local';
         try {
             for (const searchQuery of queries) {
+                queriesExecuted.push(searchQuery);
                 const params = {
                     Query: searchQuery,
                     SearchPath: args.SearchPath,
                     Includes: args.Includes,
-                    CaseInsensitive: args.CaseInsensitive ?? true, // Default to case-insensitive for better results
+                    MaxResults: args.MaxResults,
+                    CaseInsensitive: args.CaseInsensitive ?? false,
                     IsRegex: args.IsRegex,
                 };
                 try {
-                    const result = await tool.execute(params, context.cwd);
-                    totalMatches += result.totalMatches;
-                    // Add unique matches only
+                    // Use remote search for SSH/Docker/WSL, local search otherwise
+                    const result = isRemote
+                        ? await searchRemote(params, contextManager)
+                        : await tool.execute(params, context.cwd);
+                    backend = result.backend;
+                    matchesPerQuery[searchQuery] = result.totalMatches;
+                    rawTotalMatches += result.totalMatches;
+                    if (result.truncated) {
+                        truncated = true;
+                        truncationReason = result.truncationReason;
+                    }
+                    if (result.encodingFallback) {
+                        encodingFallback = true;
+                    }
+                    // Add unique matches with improved dedupe key
                     for (const match of result.matches) {
-                        const key = `${match.file}:${match.line}`;
-                        if (!seenMatches.has(key) && allMatches.length < 50) {
+                        // Use file:line:column:matchText for more accurate deduplication
+                        const key = `${match.file}:${match.line}:${match.column ?? 0}:${match.match.substring(0, 50)}`;
+                        const maxMatches = args.MaxResults || GrepSearchTool.DEFAULT_MAX_MATCHES;
+                        if (!seenMatches.has(key) && allMatches.length < maxMatches) {
                             seenMatches.add(key);
                             allMatches.push(match);
                         }
                     }
                 }
-                catch (e) {
-                    // Skip individual query errors
+                catch {
+                    matchesPerQuery[searchQuery] = 0;
                     continue;
                 }
             }
-            // Format merged results
-            const mergedResult = {
+            const endTime = Date.now();
+            const uniqueMatchesCount = allMatches.length;
+            const max = args.MaxResults || GrepSearchTool.DEFAULT_MAX_MATCHES;
+            const finalResult = {
                 matches: allMatches,
-                totalMatches: totalMatches,
-                truncated: allMatches.length >= 50,
+                totalMatches: rawTotalMatches,
+                uniqueMatchesCount,
+                truncated: truncated || allMatches.length >= max,
+                truncationReason: allMatches.length >= max ? 'max_matches' : truncationReason,
                 searchPattern: queries.length > 1 ? `"${query}" (+ individual words)` : query,
+                metadata: {
+                    backend,
+                    searchDurationMs: endTime - startTime,
+                    queriesExecuted,
+                    matchesPerQuery,
+                    encodingFallback
+                },
+                formattedOutput: '',
             };
-            return formatGrepResults(mergedResult);
+            finalResult.formattedOutput = formatGrepResults(finalResult);
+            return finalResult.formattedOutput;
         }
         catch (error) {
             throw new Error(`Grep search failed: ${error.message}`);