dominds 0.1.0

package/dist/tools/ripgrep.js

@@ -0,0 +1,678 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ripgrepSearchTool = exports.ripgrepFixedTool = exports.ripgrepSnippetsTool = exports.ripgrepCountTool = exports.ripgrepFilesTool = void 0;
+/**
+ * Module: tools/ripgrep
+ *
+ * Workspace search tools backed by `rg` (ripgrep), with low-noise YAML output.
+ */
+const child_process_1 = require("child_process");
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+function yamlQuote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function formatYamlCodeBlock(yaml) {
+    return `\`\`\`yaml\n${yaml}\n\`\`\``;
+}
+function yamlFlowStringArray(values) {
+    if (values.length === 0)
+        return '[]';
+    return `[${values.map(yamlQuote).join(', ')}]`;
+}
+function requireNonEmptyStringArg(args, key) {
+    const value = args[key];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`Invalid arguments: \`${key}\` must be a non-empty string`);
+    }
+    return value;
+}
+function optionalStringArg(args, key) {
+    const value = args[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`Invalid arguments: \`${key}\` must be a string`);
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return undefined;
+    return trimmed;
+}
+function optionalBooleanArg(args, key) {
+    const value = args[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean')
+        throw new Error(`Invalid arguments: \`${key}\` must be a boolean`);
+    return value;
+}
+function optionalPositiveIntegerArg(args, key) {
+    const value = args[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw new Error(`Invalid arguments: \`${key}\` must be an integer`);
+    }
+    if (value < 0)
+        throw new Error(`Invalid arguments: \`${key}\` must be >= 0`);
+    if (value === 0)
+        return undefined; // 0 is a sentinel for "default" under Codex required-all.
+    return value;
+}
+function optionalNonNegativeIntegerArg(args, key) {
+    const value = args[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw new Error(`Invalid arguments: \`${key}\` must be an integer`);
+    }
+    if (value < 0)
+        throw new Error(`Invalid arguments: \`${key}\` must be >= 0`);
+    return value;
+}
+function optionalStringArrayArg(args, key) {
+    const value = args[key];
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || !value.every((v) => typeof v === 'string')) {
+        throw new Error(`Invalid arguments: \`${key}\` must be an array of strings`);
+    }
+    return value;
+}
+function dirPatternToRipgrepGlob(pattern) {
+    const normalized = pattern.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '') || '.';
+    if (normalized === '.' || normalized === '')
+        return undefined;
+    if (normalized.includes('*'))
+        return normalized;
+    if (normalized.endsWith('/**'))
+        return normalized;
+    return `${normalized}/**`;
+}
+function buildAccessControlGlobs(member) {
+    const include = [];
+    const exclude = [];
+    const whitelist = member.read_dirs ?? [];
+    for (const pat of whitelist) {
+        const glob = dirPatternToRipgrepGlob(pat);
+        if (glob)
+            include.push(glob);
+    }
+    const blacklist = member.no_read_dirs ?? [];
+    for (const pat of blacklist) {
+        const glob = dirPatternToRipgrepGlob(pat);
+        if (glob)
+            exclude.push(glob);
+    }
+    // Task Docs are encapsulated and forbidden to all general file tools.
+    exclude.push('**/*.tsk');
+    exclude.push('**/*.tsk/**');
+    return { include, exclude };
+}
+function defaultBaseOptions() {
+    return {
+        globs: [],
+        caseMode: 'smart',
+        fixedStrings: false,
+        includeHidden: false,
+        followSymlinks: false,
+    };
+}
+function parseRipgrepCaseModeArg(args, defaultValue) {
+    const raw = optionalStringArg(args, 'case');
+    if (raw === undefined)
+        return defaultValue;
+    if (raw === 'smart' || raw === 'sensitive' || raw === 'insensitive')
+        return raw;
+    throw new Error("Invalid arguments: `case` must be one of: 'smart', 'sensitive', 'insensitive'");
+}
+function baseRgArgs(options, member) {
+    const args = ['--no-messages', '--color=never'];
+    if (options.includeHidden)
+        args.push('--hidden');
+    if (options.followSymlinks)
+        args.push('--follow');
+    if (options.caseMode === 'smart')
+        args.push('--smart-case');
+    if (options.caseMode === 'sensitive')
+        args.push('--case-sensitive');
+    if (options.caseMode === 'insensitive')
+        args.push('--ignore-case');
+    if (options.fixedStrings)
+        args.push('--fixed-strings');
+    const access = buildAccessControlGlobs(member);
+    for (const inc of access.include) {
+        args.push('--glob', inc);
+    }
+    for (const exc of access.exclude) {
+        args.push('--glob', `!${exc}`);
+    }
+    for (const glob of options.globs) {
+        args.push('--glob', glob);
+    }
+    return args;
+}
+async function runRgLines(args) {
+    return await new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)('rg', args, { cwd: process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout?.on('data', (d) => stdoutChunks.push(d));
+        child.stderr?.on('data', (d) => stderrChunks.push(d));
+        child.on('error', (err) => reject(err));
+        child.on('close', (_code) => {
+            const stdoutText = Buffer.concat(stdoutChunks).toString('utf8');
+            const stderrText = Buffer.concat(stderrChunks).toString('utf8');
+            const stdoutLines = stdoutText.split('\n').filter((l) => l !== '');
+            resolve({ stdoutLines, stderrText });
+        });
+    });
+}
+async function loadFileLines(relPath) {
+    const abs = path_1.default.resolve(process.cwd(), relPath);
+    const text = await promises_1.default.readFile(abs, 'utf8');
+    const parts = text.split('\n');
+    if (parts.length > 0 && parts[parts.length - 1] === '')
+        parts.pop();
+    return parts;
+}
+async function runRipgrepFiles(caller, pattern, searchPath, options) {
+    const args = [...baseRgArgs(options, caller), '--files-with-matches', '--', pattern, searchPath];
+    try {
+        const { stdoutLines } = await runRgLines(args);
+        let totalFiles = 0;
+        const results = [];
+        for (const line of stdoutLines) {
+            totalFiles++;
+            if (results.length < options.maxFiles)
+                results.push({ path: line });
+        }
+        const truncated = totalFiles > options.maxFiles;
+        const summary = totalFiles === 0
+            ? 'No matches.'
+            : truncated
+                ? `Found ${totalFiles} files; showing first ${options.maxFiles} (truncated=true).`
+                : `Found ${totalFiles} files.`;
+        const yaml = [
+            `status: ok`,
+            `pattern: ${yamlQuote(pattern)}`,
+            `mode: files`,
+            `path: ${yamlQuote(searchPath)}`,
+            ...(options.globs.length > 0 ? [`globs: ${yamlFlowStringArray(options.globs)}`] : []),
+            `case: ${options.caseMode}`,
+            `fixed_strings: ${options.fixedStrings}`,
+            `regex: ${!options.fixedStrings}`,
+            `truncated: ${truncated}`,
+            `limits:`,
+            `  max_files: ${options.maxFiles}`,
+            `totals:`,
+            `  files_matched: ${totalFiles}`,
+            `summary: ${yamlQuote(summary)}`,
+            `results:`,
+            ...results.map((r) => `  - path: ${yamlQuote(r.path)}`),
+        ].join('\n');
+        return formatYamlCodeBlock(yaml);
+    }
+    catch (error) {
+        return formatYamlCodeBlock([
+            `status: error`,
+            `pattern: ${yamlQuote(pattern)}`,
+            `mode: files`,
+            `path: ${yamlQuote(searchPath)}`,
+            `error: FAILED`,
+            `summary: ${yamlQuote(error instanceof Error ? error.message : String(error))}`,
+        ].join('\n'));
+    }
+}
+exports.ripgrepFilesTool = {
+    type: 'func',
+    name: 'ripgrep_files',
+    description: 'Search file paths containing a pattern (rg-backed).',
+    parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            pattern: { type: 'string' },
+            path: { type: 'string' },
+            globs: { type: 'array', items: { type: 'string' } },
+            case: { type: 'string' },
+            fixed_strings: { type: 'boolean' },
+            max_files: { type: 'integer' },
+            include_hidden: { type: 'boolean' },
+            follow_symlinks: { type: 'boolean' },
+        },
+        required: ['pattern'],
+    },
+    argsValidation: 'dominds',
+    call: async (_dlg, caller, args) => {
+        const pattern = requireNonEmptyStringArg(args, 'pattern');
+        const searchPath = optionalStringArg(args, 'path') ?? '.';
+        const globs = optionalStringArrayArg(args, 'globs') ?? [];
+        const caseMode = parseRipgrepCaseModeArg(args, 'smart');
+        const fixedStrings = optionalBooleanArg(args, 'fixed_strings') ?? false;
+        const includeHidden = optionalBooleanArg(args, 'include_hidden') ?? false;
+        const followSymlinks = optionalBooleanArg(args, 'follow_symlinks') ?? false;
+        const maxFiles = optionalPositiveIntegerArg(args, 'max_files') ?? 50;
+        const options = {
+            globs,
+            caseMode,
+            fixedStrings,
+            includeHidden,
+            followSymlinks,
+            maxFiles,
+        };
+        return await runRipgrepFiles(caller, pattern, searchPath, options);
+    },
+};
+async function runRipgrepCount(caller, pattern, searchPath, options) {
+    const args = [...baseRgArgs(options, caller), '--count-matches', '--', pattern, searchPath];
+    try {
+        const { stdoutLines } = await runRgLines(args);
+        let totalFiles = 0;
+        let totalMatches = 0;
+        const results = [];
+        for (const line of stdoutLines) {
+            const idx = line.lastIndexOf(':');
+            if (idx <= 0)
+                continue;
+            const p = line.slice(0, idx);
+            const rawCount = line.slice(idx + 1);
+            const count = Number.parseInt(rawCount, 10);
+            if (!Number.isFinite(count))
+                continue;
+            totalFiles++;
+            totalMatches += count;
+            if (results.length < options.maxFiles)
+                results.push({ path: p, count });
+        }
+        const truncated = totalFiles > options.maxFiles;
+        const summary = totalMatches === 0
+            ? 'No matches.'
+            : truncated
+                ? `Counted ${totalMatches} matches in ${totalFiles} files; showing first ${options.maxFiles} files (truncated=true).`
+                : `Counted ${totalMatches} matches in ${totalFiles} files.`;
+        const yaml = [
+            `status: ok`,
+            `pattern: ${yamlQuote(pattern)}`,
+            `mode: count`,
+            `path: ${yamlQuote(searchPath)}`,
+            ...(options.globs.length > 0 ? [`globs: ${yamlFlowStringArray(options.globs)}`] : []),
+            `case: ${options.caseMode}`,
+            `fixed_strings: ${options.fixedStrings}`,
+            `regex: ${!options.fixedStrings}`,
+            `truncated: ${truncated}`,
+            `limits:`,
+            `  max_files: ${options.maxFiles}`,
+            `totals:`,
+            `  files_matched: ${totalFiles}`,
+            `  matches: ${totalMatches}`,
+            `summary: ${yamlQuote(summary)}`,
+            `results:`,
+            ...results.map((r) => `  - path: ${yamlQuote(r.path)}\n    count: ${r.count}`),
+        ].join('\n');
+        return formatYamlCodeBlock(yaml);
+    }
+    catch (error) {
+        return formatYamlCodeBlock([
+            `status: error`,
+            `pattern: ${yamlQuote(pattern)}`,
+            `mode: count`,
+            `path: ${yamlQuote(searchPath)}`,
+            `error: FAILED`,
+            `summary: ${yamlQuote(error instanceof Error ? error.message : String(error))}`,
+        ].join('\n'));
+    }
+}
+exports.ripgrepCountTool = {
+    type: 'func',
+    name: 'ripgrep_count',
+    description: 'Count matches per file (rg-backed).',
+    parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            pattern: { type: 'string' },
+            path: { type: 'string' },
+            globs: { type: 'array', items: { type: 'string' } },
+            case: { type: 'string' },
+            fixed_strings: { type: 'boolean' },
+            max_files: { type: 'integer' },
+            include_hidden: { type: 'boolean' },
+            follow_symlinks: { type: 'boolean' },
+        },
+        required: ['pattern'],
+    },
+    argsValidation: 'dominds',
+    call: async (_dlg, caller, args) => {
+        const pattern = requireNonEmptyStringArg(args, 'pattern');
+        const searchPath = optionalStringArg(args, 'path') ?? '.';
+        const globs = optionalStringArrayArg(args, 'globs') ?? [];
+        const caseMode = parseRipgrepCaseModeArg(args, 'smart');
+        const fixedStrings = optionalBooleanArg(args, 'fixed_strings') ?? false;
+        const includeHidden = optionalBooleanArg(args, 'include_hidden') ?? false;
+        const followSymlinks = optionalBooleanArg(args, 'follow_symlinks') ?? false;
+        const maxFiles = optionalPositiveIntegerArg(args, 'max_files') ?? 200;
+        const options = {
+            globs,
+            caseMode,
+            fixedStrings,
+            includeHidden,
+            followSymlinks,
+            maxFiles,
+        };
+        return await runRipgrepCount(caller, pattern, searchPath, options);
+    },
+};
+async function runRipgrepSnippets(caller, pattern, searchPath, options) {
+    const args = [...baseRgArgs(options, caller), '--vimgrep', '--', pattern, searchPath];
+    try {
+        const { stdoutLines } = await runRgLines(args);
+        let totalMatches = 0;
+        const fileSet = new Set();
+        const results = [];
+        const fileCache = new Map();
+        for (const line of stdoutLines) {
+            totalMatches++;
+            const first = line.indexOf(':');
+            if (first <= 0)
+                continue;
+            const second = line.indexOf(':', first + 1);
+            if (second <= first)
+                continue;
+            const third = line.indexOf(':', second + 1);
+            if (third <= second)
+                continue;
+            const filePath = line.slice(0, first);
+            const lineStr = line.slice(first + 1, second);
+            const colStr = line.slice(second + 1, third);
+            const text = line.slice(third + 1);
+            const ln = Number.parseInt(lineStr, 10);
+            const col = Number.parseInt(colStr, 10);
+            if (!Number.isFinite(ln) || !Number.isFinite(col))
+                continue;
+            fileSet.add(filePath);
+            if (results.length >= options.maxResults)
+                continue;
+            let lines = fileCache.get(filePath);
+            if (!lines) {
+                lines = await loadFileLines(filePath).catch(() => []);
+                fileCache.set(filePath, lines);
+            }
+            const idx0 = ln - 1;
+            const before = lines.slice(Math.max(0, idx0 - options.contextBefore), idx0);
+            const after = lines.slice(idx0 + 1, idx0 + 1 + options.contextAfter);
+            results.push({ path: filePath, line: ln, col, match: text, before, after });
+        }
+        const truncated = totalMatches > options.maxResults;
+        const summary = totalMatches === 0
+            ? 'No matches.'
+            : truncated
+                ? `Showing first ${options.maxResults} of ${totalMatches} matches (truncated=true).`
+                : `Found ${totalMatches} matches.`;
+        const yaml = [
+            `status: ok`,
+            `pattern: ${yamlQuote(pattern)}`,
+            `mode: snippets`,
+            `path: ${yamlQuote(searchPath)}`,
+            ...(options.globs.length > 0 ? [`globs: ${yamlFlowStringArray(options.globs)}`] : []),
+            `case: ${options.caseMode}`,
+            `fixed_strings: ${options.fixedStrings}`,
+            `regex: ${!options.fixedStrings}`,
+            `truncated: ${truncated}`,
+            `limits:`,
+            `  max_results: ${options.maxResults}`,
+            `totals:`,
+            `  files_matched: ${fileSet.size}`,
+            `  matches: ${totalMatches}`,
+            `summary: ${yamlQuote(summary)}`,
+            `results:`,
+            ...results.map((r) => [
+                `  - path: ${yamlQuote(r.path)}`,
+                `    line: ${r.line}`,
+                `    col: ${r.col}`,
+                `    match: ${yamlQuote(r.match)}`,
+                `    before: ${yamlFlowStringArray(r.before)}`,
+                `    after: ${yamlFlowStringArray(r.after)}`,
+            ].join('\n')),
+        ].join('\n');
+        return formatYamlCodeBlock(yaml);
+    }
+    catch (error) {
+        return formatYamlCodeBlock([
+            `status: error`,
+            `pattern: ${yamlQuote(pattern)}`,
+            `mode: snippets`,
+            `path: ${yamlQuote(searchPath)}`,
+            `error: FAILED`,
+            `summary: ${yamlQuote(error instanceof Error ? error.message : String(error))}`,
+        ].join('\n'));
+    }
+}
+exports.ripgrepSnippetsTool = {
+    type: 'func',
+    name: 'ripgrep_snippets',
+    description: 'Search snippets with line/col (rg-backed).',
+    parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            pattern: { type: 'string' },
+            path: { type: 'string' },
+            globs: { type: 'array', items: { type: 'string' } },
+            case: { type: 'string' },
+            fixed_strings: { type: 'boolean' },
+            context_before: { type: 'integer' },
+            context_after: { type: 'integer' },
+            max_results: { type: 'integer' },
+            include_hidden: { type: 'boolean' },
+            follow_symlinks: { type: 'boolean' },
+        },
+        required: ['pattern'],
+    },
+    argsValidation: 'dominds',
+    call: async (_dlg, caller, args) => {
+        const pattern = requireNonEmptyStringArg(args, 'pattern');
+        const searchPath = optionalStringArg(args, 'path') ?? '.';
+        const globs = optionalStringArrayArg(args, 'globs') ?? [];
+        const caseMode = parseRipgrepCaseModeArg(args, 'smart');
+        const fixedStrings = optionalBooleanArg(args, 'fixed_strings') ?? false;
+        const includeHidden = optionalBooleanArg(args, 'include_hidden') ?? false;
+        const followSymlinks = optionalBooleanArg(args, 'follow_symlinks') ?? false;
+        const maxResults = optionalPositiveIntegerArg(args, 'max_results') ?? 50;
+        const contextBefore = optionalNonNegativeIntegerArg(args, 'context_before') ?? 1;
+        const contextAfter = optionalNonNegativeIntegerArg(args, 'context_after') ?? 1;
+        const options = {
+            globs,
+            caseMode,
+            fixedStrings,
+            includeHidden,
+            followSymlinks,
+            maxResults,
+            contextBefore,
+            contextAfter,
+        };
+        return await runRipgrepSnippets(caller, pattern, searchPath, options);
+    },
+};
+exports.ripgrepFixedTool = {
+    type: 'func',
+    name: 'ripgrep_fixed',
+    description: 'Fixed-string ripgrep convenience tool (routes to ripgrep_files/ripgrep_snippets/ripgrep_count with fixed_strings=true).',
+    parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            literal: { type: 'string' },
+            path: { type: 'string' },
+            mode: { type: 'string' },
+            globs: { type: 'array', items: { type: 'string' } },
+            case: { type: 'string' },
+            max_files: { type: 'integer' },
+            max_results: { type: 'integer' },
+            context_before: { type: 'integer' },
+            context_after: { type: 'integer' },
+            include_hidden: { type: 'boolean' },
+            follow_symlinks: { type: 'boolean' },
+        },
+        required: ['literal'],
+    },
+    argsValidation: 'dominds',
+    call: async (_dlg, caller, args) => {
+        const literal = requireNonEmptyStringArg(args, 'literal');
+        const searchPath = optionalStringArg(args, 'path') ?? '.';
+        const modeRaw = optionalStringArg(args, 'mode') ?? 'snippets';
+        if (modeRaw !== 'files' && modeRaw !== 'snippets' && modeRaw !== 'count') {
+            throw new Error("Invalid arguments: `mode` must be one of: 'files', 'snippets', 'count'");
+        }
+        const globs = optionalStringArrayArg(args, 'globs') ?? [];
+        const caseMode = parseRipgrepCaseModeArg(args, 'smart');
+        const includeHidden = optionalBooleanArg(args, 'include_hidden') ?? false;
+        const followSymlinks = optionalBooleanArg(args, 'follow_symlinks') ?? false;
+        const base = {
+            globs,
+            caseMode,
+            fixedStrings: true,
+            includeHidden,
+            followSymlinks,
+        };
+        if (modeRaw === 'files') {
+            const maxFiles = optionalPositiveIntegerArg(args, 'max_files') ?? 50;
+            const options = { ...base, maxFiles };
+            return await runRipgrepFiles(caller, literal, searchPath, options);
+        }
+        if (modeRaw === 'count') {
+            const maxFiles = optionalPositiveIntegerArg(args, 'max_files') ?? 200;
+            const options = { ...base, maxFiles };
+            return await runRipgrepCount(caller, literal, searchPath, options);
+        }
+        const maxResults = optionalPositiveIntegerArg(args, 'max_results') ?? 50;
+        const contextBefore = optionalNonNegativeIntegerArg(args, 'context_before') ?? 1;
+        const contextAfter = optionalNonNegativeIntegerArg(args, 'context_after') ?? 1;
+        const options = { ...base, maxResults, contextBefore, contextAfter };
+        return await runRipgrepSnippets(caller, literal, searchPath, options);
+    },
+};
+const DISALLOWED_RG_ARGS = new Set(['--pre', '--pre-glob']);
+async function runRipgrepSearch(caller, pattern, searchPath, rawRgArgs) {
+    for (const tok of rawRgArgs) {
+        if (DISALLOWED_RG_ARGS.has(tok)) {
+            return formatYamlCodeBlock(`status: error\nerror: DISALLOWED_ARG\nsummary: ${yamlQuote(`Disallowed rg arg: ${tok}`)}`);
+        }
+        if (tok === '--json' ||
+            tok === '--count' ||
+            tok === '--count-matches' ||
+            tok === '--files-with-matches' ||
+            tok === '--files') {
+            return formatYamlCodeBlock(`status: error\nerror: DISALLOWED_ARG\nsummary: ${yamlQuote(`Disallowed rg output arg: ${tok}`)}`);
+        }
+    }
+    const options = {
+        ...defaultBaseOptions(),
+        fixedStrings: false,
+        maxResults: 50,
+        contextBefore: 1,
+        contextAfter: 1,
+    };
+    const rgArgs = [
+        ...baseRgArgs(options, caller),
+        ...rawRgArgs,
+        '--vimgrep',
+        '--',
+        pattern,
+        searchPath,
+    ];
+    try {
+        const { stdoutLines } = await runRgLines(rgArgs);
+        let totalMatches = 0;
+        const fileSet = new Set();
+        const results = [];
+        for (const line of stdoutLines) {
+            totalMatches++;
+            const first = line.indexOf(':');
+            if (first <= 0)
+                continue;
+            const secondColon = line.indexOf(':', first + 1);
+            if (secondColon <= first)
+                continue;
+            const thirdColon = line.indexOf(':', secondColon + 1);
+            if (thirdColon <= secondColon)
+                continue;
+            const filePath = line.slice(0, first);
+            const lineStr = line.slice(first + 1, secondColon);
+            const colStr = line.slice(secondColon + 1, thirdColon);
+            const text = line.slice(thirdColon + 1);
+            const ln = Number.parseInt(lineStr, 10);
+            const col = Number.parseInt(colStr, 10);
+            if (!Number.isFinite(ln) || !Number.isFinite(col))
+                continue;
+            fileSet.add(filePath);
+            if (results.length < options.maxResults)
+                results.push({ path: filePath, line: ln, col, match: text });
+        }
+        const truncated = totalMatches > options.maxResults;
+        const summary = totalMatches === 0
+            ? 'No matches.'
+            : truncated
+                ? `Showing first ${options.maxResults} of ${totalMatches} matches (truncated=true).`
+                : `Found ${totalMatches} matches.`;
+        const yaml = [
+            `status: ok`,
+            `pattern: ${yamlQuote(pattern)}`,
+            `mode: snippets`,
+            `path: ${yamlQuote(searchPath)}`,
+            `case: smart`,
+            `fixed_strings: false`,
+            `regex: true`,
+            `truncated: ${truncated}`,
+            `limits:`,
+            `  max_results: ${options.maxResults}`,
+            `totals:`,
+            `  files_matched: ${fileSet.size}`,
+            `  matches: ${totalMatches}`,
+            `summary: ${yamlQuote(summary)}`,
+            `results:`,
+            ...results.map((r) => [
+                `  - path: ${yamlQuote(r.path)}`,
+                `    line: ${r.line}`,
+                `    col: ${r.col}`,
+                `    match: ${yamlQuote(r.match)}`,
+            ].join('\n')),
+        ].join('\n');
+        return formatYamlCodeBlock(yaml);
+    }
+    catch (error) {
+        return formatYamlCodeBlock([
+            `status: error`,
+            `pattern: ${yamlQuote(pattern)}`,
+            `mode: snippets`,
+            `path: ${yamlQuote(searchPath)}`,
+            `error: FAILED`,
+            `summary: ${yamlQuote(error instanceof Error ? error.message : String(error))}`,
+        ].join('\n'));
+    }
+}
+exports.ripgrepSearchTool = {
+    type: 'func',
+    name: 'ripgrep_search',
+    description: 'Escape hatch: run rg-style search (snippets output, with a limited allowlist). Output is normalized to YAML snippets mode.',
+    parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            pattern: { type: 'string' },
+            path: { type: 'string' },
+            rg_args: { type: 'array', items: { type: 'string' } },
+        },
+        required: ['pattern'],
+    },
+    argsValidation: 'dominds',
+    call: async (_dlg, caller, args) => {
+        const pattern = requireNonEmptyStringArg(args, 'pattern');
+        const searchPath = optionalStringArg(args, 'path') ?? '.';
+        const rgArgs = optionalStringArrayArg(args, 'rg_args') ?? [];
+        return await runRipgrepSearch(caller, pattern, searchPath, rgArgs);
+    },
+};