mixdog 0.9.93 → 0.9.94

package/src/runtime/agent/orchestrator/tools/builtin/list-tool.mjs

@@ -20,7 +20,6 @@ import {
     getCachedReadOnlyStat,
     statCacheSet,
     statPathsForMtime,
-    lstatPathsForMtime,
     registerCacheInvalidationListener,
 } from './cache-layers.mjs';
 import {
@@ -28,8 +27,11 @@ import {
     NOISE_DIR_NAMES,
     walkDir,
 } from './glob-walk.mjs';
-import { formatMtime, formatListSize } from './list-formatting.mjs';
-import { TOOL_OUTPUT_MAX_BYTES } from './tool-output-limit.mjs';
+import {
+    capLineOrientedToolOutput,
+    LOCATOR_OUTPUT_MAX_BYTES,
+    TOOL_OUTPUT_MAX_BYTES,
+} from './tool-output-limit.mjs';
 import { runRg } from './rg-runner.mjs';
 import { hasSpareCapacity as childSpawnHasSpareCapacity } from '../../../../shared/child-spawn-gate.mjs';
 import { fuzzyRank } from './fuzzy-match.mjs';
@@ -52,6 +54,36 @@ function _findDefaultHeadLimit(fallback) {
     return parsed > 0 ? parsed : fallback;
 }
 
+function _findOutputBudgetBytes(options = {}) {
+    const requested = Number(options?.__findOutputBudgetBytes);
+    const explicit = Number(options?.toolOutputMaxBytes);
+    return Math.max(1, Math.min(
+        LOCATOR_OUTPUT_MAX_BYTES,
+        Number.isFinite(requested) && requested > 0 ? Math.trunc(requested) : LOCATOR_OUTPUT_MAX_BYTES,
+        Number.isFinite(explicit) && explicit > 0 ? Math.trunc(explicit) : LOCATOR_OUTPUT_MAX_BYTES,
+    ));
+}
+
+function _splitFindBudget(total, count, index) {
+    if (!(count > 0)) return 0;
+    const base = Math.floor(total / count);
+    return base + (index < (total % count) ? 1 : 0);
+}
+
+// Entry paths render relative to the listed root — the caller supplied the
+// base via `path`, so repeating the absolute prefix on every row is pure
+// duplication (~2KB per 80 rows). Falls back to the absolute form when the
+// entry escapes the root (drive change / `..`), where a relative form would
+// be ambiguous. Cache-safe: keys already include the absolute root, and the
+// rendered rows no longer depend on the session workDir.
+function displayRelPath(entPath, rootPath) {
+    const rel = relative(rootPath, entPath);
+    if (!rel || rel === '.' || rel.startsWith('..') || /^[A-Za-z]:/.test(rel)) {
+        return normalizeOutputPath(entPath);
+    }
+    return normalizeOutputPath(rel);
+}
+
 export async function executeListTool(args, workDir, options = {}) {
     args.path = coerceReadFamilyPathArg(args.path, workDir);
     if (Array.isArray(args.path)) {
@@ -209,20 +241,10 @@ export async function executeListTool(args, workDir, options = {}) {
 
     const windowed = offset > 0 ? rows.slice(offset) : rows;
     const sliced = headLimit > 0 ? windowed.slice(0, headLimit) : windowed;
-    if (!needsGlobalStat && sliced.length > 0) {
-        // Use lstat so a symlink reports its own size/mtime instead of
-        // the target's. The walker already typed symlinks from Dirent;
-        // following the link here would lie about the listed entry.
-        const stats = await lstatPathsForMtime(sliced.map((row) => row.fullPath), workDir, 64, { deadlineMs: 5000 });
-        for (let i = 0; i < sliced.length; i++) {
-            const item = stats[i];
-            if (!item?.stat) continue;
-            sliced[i].size = item.size;
-            sliced[i].mtimeMs = item.mtimeMs;
-        }
-    }
-    const lines = sliced.map(r =>
-        `${normalizeOutputPath(r.path)}\t${r.type}\t${formatListSize(r.type, r.size)}\t${formatMtime(r.mtimeMs)}`);
+    // Paths and entry types are the list contract. Size/mtime columns were
+    // neither exposed in the model schema nor used by routing, yet consumed
+    // roughly 28–40% of live list output and forced a stat per visible entry.
+    const lines = sliced.map(r => `${displayRelPath(r.path, fullPath)}\t${r.type}`);
     if (windowed.length > sliced.length) lines.push(`... [entries ${offset + 1}-${offset + sliced.length} of ${rows.length}; pass offset:${offset + sliced.length} to continue]`);
     if (truncatedByCap) lines.push(`... walk truncated at ${LIST_ABSOLUTE_CAP} rows or ${LIST_WALK_TIMEOUT_MS}ms timeout; narrow the path or lower depth for a complete listing`);
     let emptyMsg = '(empty directory)';
@@ -563,24 +585,60 @@ export async function executeFuzzyFindTool(args, workDir, options = {}) {
         const capped = list.length > 5;
         const targets = capped ? list.slice(0, 5) : list;
         if (targets.length > 1) {
+            // head_limit is one call-level result budget, not a multiplier per
+            // query. Split it deterministically in caller order; if it cannot
+            // fund one result per query, return the remaining queries exactly.
+            const totalHeadLimit = normalizeListHeadLimit(args.head_limit, _findDefaultHeadLimit(25));
+            const activeCount = totalHeadLimit > 0
+                ? Math.min(targets.length, totalHeadLimit)
+                : targets.length;
+            const activeTargets = targets.slice(0, activeCount);
+            const omittedByHeadLimit = targets.slice(activeCount);
+            const notes = [];
+            if (omittedByHeadLimit.length) {
+                notes.push(
+                    `... [head_limit ${totalHeadLimit} exhausted across query[]; `
+                    + `retry query=${JSON.stringify(omittedByHeadLimit)}]`,
+                );
+            }
+            if (capped) notes.push(`... [capped at 5 of ${list.length} queries]`);
+            const sectionHeaders = activeTargets.map((query) => `# find ${query}\n`);
+            const separatorBytes = Math.max(0, activeTargets.length + notes.length - 1) * 2;
+            const fixedBytes = sectionHeaders.reduce(
+                (sum, header) => sum + Buffer.byteLength(header, 'utf8'),
+                separatorBytes + notes.reduce((sum, note) => sum + Buffer.byteLength(note, 'utf8'), 0),
+            );
+            const bodyBudget = Math.max(activeTargets.length, _findOutputBudgetBytes(options) - fixedBytes);
             // Full parallelism is intentional. All sections share one common
             // broad enumeration and one unioned ignored/truncated targeted pass,
-            // but ranking and output remain isolated per query.
+            // while each query receives a fair share of the call-level count and
+            // byte budgets before any aggregate result is assembled.
             const batchContext = {
-                queries: targets,
+                queries: activeTargets,
                 targetedRuns: new Map(),
                 itemsByFiles: new WeakMap(),
             };
-            const nestedOptions = { ...options, __findBatchContext: batchContext };
-            const bodies = await Promise.all(targets.map(async (query) => {
+            const bodies = await Promise.all(activeTargets.map(async (query, index) => {
+                const queryHeadLimit = totalHeadLimit > 0
+                    ? _splitFindBudget(totalHeadLimit, activeTargets.length, index)
+                    : 0;
+                const nestedOptions = {
+                    ...options,
+                    __findBatchContext: batchContext,
+                    __findOutputBudgetBytes: _splitFindBudget(bodyBudget, activeTargets.length, index),
+                };
                 try {
-                    return await executeFuzzyFindTool({ ...args, query }, workDir, nestedOptions);
+                    return await executeFuzzyFindTool(
+                        { ...args, query, head_limit: queryHeadLimit },
+                        workDir,
+                        nestedOptions,
+                    );
                 } catch (err) {
                     return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
                 }
             }));
-            const sections = targets.map((q, i) => `# find ${q}\n${bodies[i]}`);
-            if (capped) sections.push(`... [capped at 5 of ${list.length} queries]`);
+            const sections = activeTargets.map((q, i) => `${sectionHeaders[i]}${bodies[i]}`);
+            sections.push(...notes);
             return sections.join('\n\n');
         }
         args.query = targets[0];
@@ -616,7 +674,12 @@ export async function executeFuzzyFindTool(args, workDir, options = {}) {
         includeNoise,
     });
     const cached = cacheGet(cacheKey);
-    if (cached !== null) return cached;
+    const capFindResult = (value) => capLineOrientedToolOutput(
+        value,
+        _findOutputBudgetBytes(options),
+        () => `... [find result budget reached for query=${JSON.stringify(query)}; narrow path/head_limit]`,
+    );
+    if (cached !== null) return capFindResult(cached);
     // Common discovery respects .gitignore even outside a Git repository.
     // include_noise deliberately retains the old hardened --no-ignore behavior.
     // Noise dirs stay excluded via DEFAULT_IGNORE_GLOBS below.
@@ -751,7 +814,7 @@ export async function executeFuzzyFindTool(args, workDir, options = {}) {
     if (typeof options?.onProgress === 'function') {
         try { options.onProgress(`${ranked.length} candidates`); } catch { /* best-effort */ }
     }
-    return result;
+    return capFindResult(result);
 }
 
 export async function executeFindFilesTool(args, workDir, options = {}) {
@@ -1014,7 +1077,7 @@ export async function executeFindFilesTool(args, workDir, options = {}) {
     const windowed = offset > 0 ? matches.slice(offset) : matches;
     const sliced = headLimit > 0 ? windowed.slice(0, headLimit) : windowed;
     const lines = sliced.map(m =>
-        `${normalizeOutputPath(m.path)}\t${formatListSize('file', m.size)}\t${formatMtime(m.mtimeMs)}`);
+        `${displayRelPath(m.path, fullPath)}\t${formatListSize('file', m.size)}\t${formatMtime(m.mtimeMs)}`);
     if (windowed.length > sliced.length) lines.push(`... [entries ${offset + 1}-${offset + sliced.length} of ${matches.length}; pass offset:${offset + sliced.length} to continue]`);
     if (rgStdoutTruncated) lines.push('... [warning] rg stdout truncated at 20MB cap; results incomplete');
     if (rgStdoutPartial) lines.push('... [warning] rg exit 2 (partial results); listing may be incomplete');

package/src/runtime/agent/orchestrator/tools/builtin/path-utils.mjs

@@ -103,6 +103,11 @@ function firstPresentArg(args, names) {
     return undefined;
 }
 
+// Shared semantic default for grep calls that omit output_mode/context.
+// Scoped-cache canonicalization imports this so omitted context and an
+// explicit context:25 resolve to the same cache key.
+export const GREP_AUTO_CONTEXT_LINES = 25;
+
 export function normalizeGrepArgs(args) {
     if (!args || typeof args !== 'object') return args;
     if (args.pattern === undefined || args.pattern === null || args.pattern === '') {
@@ -119,7 +124,7 @@ export function normalizeGrepArgs(args) {
     }
     if ((args.output_mode === undefined || args.output_mode === null || args.output_mode === '') && typeof args.mode === 'string') {
         const mode = args.mode.trim();
-        if (['files_with_matches', 'content', 'count'].includes(mode)) args.output_mode = mode;
+        if (['files_with_matches', 'content', 'content_with_context', 'count'].includes(mode)) args.output_mode = mode;
     }
     return args;
 }

package/src/runtime/agent/orchestrator/tools/builtin/read-batch.mjs

@@ -54,7 +54,7 @@ export function sliceReadBodyByLines(body, origOffset, origLimit) {
     const _remaining = haveTotal ? totalNum - emittedLast : null;
     const continuationPart = moreToRead && Number.isFinite(emittedLast)
         ? (_remaining !== null && _remaining > 0 && _remaining <= 600
-            ? `; ${_remaining} lines left — take the rest in ONE window: offset:${emittedLast}, limit:${_remaining}`
+            ? `; ${_remaining} left — ONE window: offset:${emittedLast} limit:${_remaining}`
             : `; pass offset:${emittedLast} to continue`)
         : '';
     const newFooter = `[lines ${firstLine}-${emittedLast}${totalPart}${continuationPart}]`;

package/src/runtime/agent/orchestrator/tools/builtin/read-single-tool.mjs

@@ -99,6 +99,9 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
         _rawContentCacheSet,
         _recordReadSnapshot,
     } = helpers;
+    const _readMaxOutputBytes = Number(options?.readOutputBudgetBytes) > 0
+        ? Math.min(READ_MAX_OUTPUT_BYTES, Math.trunc(Number(options.readOutputBudgetBytes)))
+        : READ_MAX_OUTPUT_BYTES;
     // Normalize path (strip whitespace, expand ~, posix→windows) up front so
     // LLM-injected stray spaces don't trigger an ENOENT retry that pollutes
     // the conversation history and breaks the cache prefix on later turns.
@@ -454,7 +457,10 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
             return withSymbolReadNote(text, args);
         }
         try {
-            const _streamRes = await streamReadRange(fullPath, offset, limit, st, { displayPath: filePath });
+            const _streamRes = await streamReadRange(fullPath, offset, limit, st, {
+                displayPath: filePath,
+                maxOutputBytes: _readMaxOutputBytes,
+            });
             const out = _streamRes.text;
             // W1 H: snapshot only emitted line bounds, not the
             // requested window — byte-cap truncation can stop short.
@@ -547,9 +553,13 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
             // Fall through to the regular read path; it still enforces output caps.
         }
     }
-    if (!_isUtf16 && hasRangeArgs && !wantFull && st.size > READ_STREAM_RANGE_MIN_BYTES) {
+    if (!_isUtf16 && hasRangeArgs && !wantFull
+        && (options?.forceReadRangeStream === true || st.size > READ_STREAM_RANGE_MIN_BYTES)) {
         try {
-            const _streamRes = await streamReadRange(fullPath, offset, limit, st, { displayPath: filePath });
+            const _streamRes = await streamReadRange(fullPath, offset, limit, st, {
+                displayPath: filePath,
+                maxOutputBytes: _readMaxOutputBytes,
+            });
             const out = _streamRes.text;
             const _emittedRanges = (_streamRes.firstEmitted && _streamRes.lastEmitted)
                 ? [{ startLine: _streamRes.firstEmitted, endLine: _streamRes.lastEmitted }]
@@ -649,19 +659,19 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
             _smartTruncated = true;
             _smartVisibleRanges = Array.isArray(smart.ranges) ? smart.ranges : null;
             _renderedLineCount = 0;
-        } else if (Buffer.byteLength(rendered, 'utf8') > READ_MAX_OUTPUT_BYTES) {
+        } else if (Buffer.byteLength(rendered, 'utf8') > _readMaxOutputBytes) {
             let lo = 0;
             let hi = rendered.length;
             while (lo < hi) {
                 const mid = Math.ceil((lo + hi) / 2);
-                if (Buffer.byteLength(rendered.slice(0, mid), 'utf8') <= READ_MAX_OUTPUT_BYTES) lo = mid;
+                if (Buffer.byteLength(rendered.slice(0, mid), 'utf8') <= _readMaxOutputBytes) lo = mid;
                 else hi = mid - 1;
             }
             const slice = rendered.slice(0, lo);
             const completeRenderedLines = Math.max(0, slice.split('\n').length - 1);
             _renderedLineCount = completeRenderedLines;
             _byteCapTruncated = true;
-            out = slice + `\n\n... [output truncated at ${Math.round(READ_MAX_OUTPUT_BYTES/1024)} KB] ...`;
+            out = slice + `\n\n... [output truncated at ${Math.round(_readMaxOutputBytes/1024)} KB] ...`;
         } else {
             out = rendered;
         }
@@ -671,10 +681,10 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
             } else if (_byteCapTruncated) {
                 const emittedStart = offset + 1;
                 const emittedEnd = offset + _renderedLineCount;
-                const capKb = Math.round(READ_MAX_OUTPUT_BYTES / 1024);
+                const capKb = Math.round(_readMaxOutputBytes / 1024);
                 const footer = `[lines ${emittedStart}-${emittedEnd} of ${lineCount}; output truncated at ${capKb} KB${emittedEnd < lineCount ? `; pass offset:${emittedEnd} to continue` : ''}]`;
                 out += `${out ? '\n' : ''}${footer}`;
-            } else if (Buffer.byteLength(rendered, 'utf8') <= READ_MAX_OUTPUT_BYTES) {
+            } else if (Buffer.byteLength(rendered, 'utf8') <= _readMaxOutputBytes) {
                 const emittedStart = offset + 1;
                 const emittedEnd = offset + sliced.length;
                 // Anti-fragmentation: when the remainder is modest, hand the
@@ -683,7 +693,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
                 const _remaining = lineCount - emittedEnd;
                 const _cont = emittedEnd < lineCount
                     ? (_remaining <= 600
-                        ? `; ${_remaining} lines left — take the rest in ONE window: offset:${emittedEnd}, limit:${_remaining}`
+                        ? `; ${_remaining} left — ONE window: offset:${emittedEnd} limit:${_remaining}`
                         : `; pass offset:${emittedEnd} to continue`)
                     : '';
                 const footer = `[lines ${emittedStart}-${emittedEnd} of ${lineCount}${_cont}]`;

package/src/runtime/agent/orchestrator/tools/builtin/read-streaming.mjs

@@ -62,6 +62,10 @@ export async function streamReadRange(fullPath, offset, limit, stHint = null, ho
     let pendingBytes = 0;
     let lineCollectCapped = false;
     let prefixHash = rangeIndex?.prefixHash || '';
+    const maxOutputBytes = Number(hooks.maxOutputBytes) > 0
+        ? Math.min(READ_MAX_OUTPUT_BYTES, Math.trunc(Number(hooks.maxOutputBytes)))
+        : READ_MAX_OUTPUT_BYTES;
+    const bodyOutputBytes = Math.max(1, maxOutputBytes - Math.min(384, Math.floor(maxOutputBytes / 3)));
     const deadline = Date.now() + READ_STREAM_TIMEOUT_MS;
     let bytesScanned = anchor.byteOffset;
 
@@ -85,7 +89,7 @@ export async function streamReadRange(fullPath, offset, limit, stHint = null, ho
         // Truncation drops the entire rendered line (codepoint-safe by
         // construction), so no mid-codepoint cut can occur here.
         collectedBytes += Buffer.byteLength(rendered, 'utf8') + 1;
-        if (collectedBytes > READ_MAX_OUTPUT_BYTES) {
+        if (collectedBytes > bodyOutputBytes) {
             truncated = true;
             return false;
         }
@@ -207,7 +211,8 @@ export async function streamReadRange(fullPath, offset, limit, stHint = null, ho
 
     let out = collected.join('\n');
     if (truncated) {
-        out += `\n\n... [output truncated at ${Math.round(READ_MAX_OUTPUT_BYTES/1024)} KB] ...`;
+        const nextOffset = lastEmitted || offset;
+        out += `\n\n... [output truncated at ${Math.max(1, Math.round(maxOutputBytes/1024))} KB; pass offset:${nextOffset} to continue] ...`;
     } else if (stoppedAtLimit) {
         out += `${out ? '\n' : ''}... [range limit reached; next offset: ${offset + collected.length}]`;
     } else if (!out && offset >= lineIdx) {

package/src/runtime/agent/orchestrator/tools/builtin/read-tool.mjs

@@ -113,6 +113,7 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
         _rangeHashesFromRenderedReadText,
         _readEntryLineWindow,
         _recordReadSnapshot,
+        READ_MAX_OUTPUT_BYTES,
     } = helpers;
     // CC `file_path` alias — official SDK schema uses `file_path`;
     // mixdog has historically used `path`. Honor `file_path` so a
@@ -310,6 +311,21 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
             if (a.offset !== b.offset) return a.offset - b.offset;
             return a.index - b.index;
         });
+        // A path[] Read shares one byte ceiling. Reserve room for headers and
+        // split the remaining body budget across distinct disk windows.
+        const _readCallBudget = Number(options?.readOutputBudgetBytes) > 0
+            ? Math.min(READ_MAX_OUTPUT_BYTES, Math.trunc(Number(options.readOutputBudgetBytes)))
+            : READ_MAX_OUTPUT_BYTES;
+        const _headerReserve = Math.min(
+            Math.max(2_048, entries.reduce((sum, entry) => (
+                sum + Buffer.byteLength(String(normalizeOutputPath(entry?.path || '(missing-path)')), 'utf8') + 128
+            ), 0)),
+            Math.floor(_readCallBudget / 2),
+        );
+        const _perTaskOutputBudget = Math.max(
+            256,
+            Math.floor((_readCallBudget - _headerReserve) / Math.max(1, tasks.length)),
+        );
         const results = new Array(entries.length);
         const readChains = new Map();
         await Promise.all(tasks.map(({ entry, index }) => {
@@ -319,9 +335,15 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
             }
             const run = async () => {
                 const _diskWin = readEntryCoalescedDiskWindow(entry);
-                const readEntry = _diskWin
+                let readEntry = _diskWin
                     ? { ...entry, offset: _diskWin.offset, limit: _diskWin.limit }
                     : entry;
+                if ((!readEntry.mode || readEntry.mode === 'full')
+                    && readEntry.offset == null
+                    && readEntry.limit == null
+                    && readEntry.full !== true) {
+                    readEntry = { ...readEntry, offset: 0, limit: 2000 };
+                }
                 // Full image children retain their rich blocks; the aggregate
                 // assembler below flattens them without stringification.
                 // Other media (PDF/notebook) remains text-only in a batch so
@@ -332,6 +354,9 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
                     suppressReadUnchangedStub: true,
                     mediaTextOnly: !richImage,
                     _skipReachPreflight: true,
+                    forceReadRangeStream: true,
+                    readOutputBudgetBytes: _perTaskOutputBudget,
+                    toolOutputMaxBytes: _perTaskOutputBudget,
                 });
                 results[index] = { path: entry.path, mode: entry.mode || 'full', n: entry.n, body };
             };
@@ -470,11 +495,13 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
                 const r = orderedResults[i];
                 const path = normalizeOutputPath(r.path);
                 const mode = r.n !== undefined ? `${r.mode} n=${r.n}` : r.mode;
+                // Default full mode carries no information — tag only non-default modes.
+                const modeTag = mode && mode !== 'full' ? ` [${mode}]` : '';
                 const status = bodyFailed(r.body) ? 'error' : 'ok';
                 const textBody = bodyTextFor(r.body);
                 const match = /\[TRUNCATED (?:—|-) file is (\d+) lines \/ (\d+) KB\./.exec(textBody);
                 const suffix = match ? ` (truncated ${match[1]}L/${match[2]}KB)` : '';
-                const entryHeader = `${path} [${mode}] [${status}]${suffix}`;
+                const entryHeader = `${path}${modeTag} [${status}]${suffix}`;
                 const richParts = richPartsFor(r.body);
                 let priorIdx;
                 if (richParts) {
@@ -513,16 +540,17 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
         const body = orderedResults.map((r, _i) => {
             const path = normalizeOutputPath(r.path);
             const mode = r.n !== undefined ? `${r.mode} n=${r.n}` : r.mode;
+            const modeTag = mode && mode !== 'full' ? ` [${mode}]` : '';
             const status = classifyResultKind(String(r.body || '')) === 'error' ? 'error' : 'ok';
             const dupKey = JSON.stringify([path, mode, r.body || '']);
             const priorIdx = _seenEntryBody.get(dupKey);
             if (priorIdx !== undefined) {
-                return `${path} [${mode}] [${status}] [= entry #${priorIdx + 1}, identical result omitted]`;
+                return `${path}${modeTag} [${status}] [= entry #${priorIdx + 1}, identical result omitted]`;
             }
             _seenEntryBody.set(dupKey, _i);
             const match = /\[TRUNCATED (?:—|-) file is (\d+) lines \/ (\d+) KB\./.exec(r.body || '');
             const suffix = match ? ` (truncated ${match[1]}L/${match[2]}KB)` : '';
-            return `${path} [${mode}] [${status}]${suffix}\n${r.body}`;
+            return `${path}${modeTag} [${status}]${suffix}\n${r.body}`;
         }).join('\n\n');
         return `${header}\n\n${body}${args._batchCapNote ? `\n\n${args._batchCapNote}` : ''}`;
     }

package/src/runtime/agent/orchestrator/tools/builtin/search-builders.mjs

@@ -31,7 +31,9 @@ export function buildGrepCacheKey(parts) {
         onlyMatching,
         pcre2,
         withFilename,
+        contextCharBudget = 0,
         patternCapTotal = 0,
+        candidatesKey = '',
     } = parts;
     return [
         'grep',
@@ -51,10 +53,15 @@ export function buildGrepCacheKey(parts) {
         Array.isArray(fileType) ? fileType.join('\x01') : (fileType || ''),
         pcre2 ? 'p1' : 'p0',
         withFilename ? 'H1' : 'H0',
+        'cb' + String(contextCharBudget || 0),
         // Cap total keeps a capped request (first-N of M patterns, carrying the
         // "[capped at N of M]" notice) from colliding with an exact N-pattern
         // request or with a differently-capped one (of 15 vs of 20).
         'pc' + String(patternCapTotal || 0),
+        // Candidate-file scoping (fan-out prefilter) changes which files rg
+        // visits and their order; scoped results get their own cache slot so
+        // they never collide with an unscoped run of the same pattern.
+        'cd' + String(candidatesKey || ''),
     ].join('|');
 }
 
@@ -75,6 +82,7 @@ export function buildGrepRgArgs(parts) {
         fixedStrings = false,
         pcre2 = false,
         withFilename = false,
+        candidateFiles = null,
     } = parts;
     // `--hidden`: search dotfiles/dot-dirs (.github, .mixdog) that
     // rg skips by default. The DEFAULT_IGNORE_GLOBS below still exclude .git and
@@ -127,7 +135,14 @@ export function buildGrepRgArgs(parts) {
     // `--type` is treated as a positional path, not parsed as an rg
     // option. Patterns already use `-e`, so the separator only needs to
     // guard the trailing path operand.
-    rgArgs.push('--', searchPath);
+    if (Array.isArray(candidateFiles) && candidateFiles.length > 0) {
+        // Fan-out prefilter scoping: search ONLY the candidate files (paths
+        // relative to the spawn cwd) instead of walking searchPath — explicit
+        // file operands skip the directory walk entirely.
+        rgArgs.push('--', ...candidateFiles);
+    } else {
+        rgArgs.push('--', searchPath);
+    }
     return rgArgs;
 }