mixdog 0.9.3 → 0.9.5

package/src/runtime/agent/orchestrator/tools/builtin/arg-guard.mjs

@@ -85,7 +85,7 @@ function isStringOrStringArray(v) {
     return true;
 }
 
-function hasUnsupportedRipgrepRegex(value) {
+export function hasUnsupportedRipgrepRegex(value) {
     const values = Array.isArray(value) ? value : [value];
     return values.some((item) => {
         if (typeof item !== 'string') return false;
@@ -99,6 +99,30 @@ function hasMultipleAbsoluteWindowsPaths(value) {
     return Array.isArray(matches) && matches.length > 1;
 }
 
+// Rescue for hasMultipleAbsoluteWindowsPaths: a single string arg that packs
+// multiple absolute Windows paths together (space/comma/semicolon separated,
+// e.g. "C:\a\b C:\c\d" or "C:\a\b, C:\c\d") is a common model mistake meaning
+// two separate search roots, not one malformed path. Split on each drive-
+// letter boundary and trim separator debris instead of hard-erroring;
+// executeGrepTool's own array fan-out (search-tool.mjs) already knows how to
+// run one grep per path and join the results. Returns null when the value
+// does not cleanly resolve to 2+ non-empty segments.
+function splitMultipleAbsoluteWindowsPaths(value) {
+    if (typeof value !== 'string') return null;
+    const starts = [];
+    const re = /[A-Za-z]:[\\/]/g;
+    let m;
+    while ((m = re.exec(value)) !== null) starts.push(m.index);
+    if (starts.length < 2) return null;
+    const parts = [];
+    for (let i = 0; i < starts.length; i++) {
+        const end = i + 1 < starts.length ? starts[i + 1] : value.length;
+        const part = value.slice(starts[i], end).trim().replace(/[,;]+$/, '').trim();
+        if (part) parts.push(part);
+    }
+    return parts.length > 1 ? parts : null;
+}
+
 function hasWindowsDrivePath(value) {
     return typeof value === 'string' && /[A-Za-z]:[\\/]/.test(value);
 }
@@ -124,9 +148,15 @@ function coerceIntegerString(v) {
     return n;
 }
 
+// Range-shaped strings ("1,40", "1-40", "1:40") are a common model mistake
+// when trying to pass a line range through a single-integer field. They are
+// not coerced (ambiguous which bound is intended); instead the rejection
+// tells the model exactly what to do instead.
+const RANGE_SHAPED_INT_STRING = /^\d+\s*[,\-:]\s*\d+$/;
+
 // Mutates a[field] in place when it is a lossless integer string, then
 // validates the (possibly coerced) value against [min, max].
-function checkIntInRange(a, field, min, max) {
+function checkIntInRange(a, field, min, max, opts = {}) {
     let value = a[field];
     if (value === undefined || value === null) return null;
     if (typeof value === 'string') {
@@ -136,8 +166,20 @@ function checkIntInRange(a, field, min, max) {
             a[field] = coerced;
         }
     }
+    if (typeof value === 'string' && RANGE_SHAPED_INT_STRING.test(value.trim())) {
+        return `Error: builtin arg "${field}" takes a single integer; for a line range use offset+limit as separate integers or "path#L<start>-L<end>" in the path arg (got "${value}")`;
+    }
     if (!isFiniteInt(value)) {
-        return `Error: builtin arg "${field}" must be a finite integer (got ${describeType(value)})`;
+        return `Error: builtin arg "${field}" must be a finite integer (got ${describeType(value)}); expected a single integer like 40`;
+    }
+    // Soft-cap fields (grep -A/-B/-C/context): silently clamp out-of-range
+    // instead of erroring — a model-guessed "300" for a 200-line cap is not
+    // a shape violation worth a retry turn, just clamp to the boundary.
+    if (opts.clamp) {
+        if (value < min) { a[field] = min; return null; }
+        if (value > max) { a[field] = max; return null; }
+        a[field] = value;
+        return null;
     }
     if (value < min) {
         return `Error: builtin arg "${field}" must be >= ${min} (got ${value})`;
@@ -216,10 +258,11 @@ function guardGrep(a) {
         if (hasOwn(a, k) && !isStringOrStringArray(a[k])) {
             return `Error: grep arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
         }
-        if (hasOwn(a, k) && hasUnsupportedRipgrepRegex(a[k])) {
-            return `Error: grep arg "${k}" uses regex syntax ripgrep does not support here (lookaround/backrefs). Use plain pattern arrays or simpler regex.`;
-        }
     }
+    // Lookaround/backreference patterns are no longer hard-rejected here:
+    // executeGrepTool (search-tool.mjs) detects them at runtime and routes to
+    // rg's PCRE2 engine (-P/--pcre2) when the installed rg build supports it,
+    // falling back to this same error text only when PCRE2 is unavailable.
     for (const k of globKeys) {
         if (hasOwn(a, k) && !isStringOrStringArray(a[k])) {
             return `Error: grep arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
@@ -231,7 +274,11 @@ function guardGrep(a) {
             return `Error: grep arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
         }
         if (hasOwn(a, k) && hasMultipleAbsoluteWindowsPaths(a[k])) {
-            return `Error: grep arg "${k}" contains multiple absolute paths in one string. Use one common parent path plus glob, or separate grep calls.`;
+            const split = splitMultipleAbsoluteWindowsPaths(a[k]);
+            if (!split) {
+                return `Error: grep arg "${k}" contains multiple absolute paths in one string. Use one common parent path plus glob, or separate grep calls.`;
+            }
+            a[k] = split;
         }
     }
     for (const k of ['head_limit', 'offset']) {
@@ -239,7 +286,7 @@ function guardGrep(a) {
         if (err) return err;
     }
     for (const k of ['-A', '-B', '-C', 'context']) {
-        const err = checkIntInRange(a, k, 0, GREP_CONTEXT_MAX);
+        const err = checkIntInRange(a, k, 0, GREP_CONTEXT_MAX, { clamp: true });
         if (err) return err;
     }
     // output_mode / mode enum
@@ -291,13 +338,19 @@ function applyLineContextWindow(obj, labelPrefix) {
     if (!hasLine) {
         return `Error: read arg "${labelPrefix}context" requires "${labelPrefix}line" to compute a window`;
     }
+    if (typeof obj.line === 'string' && RANGE_SHAPED_INT_STRING.test(obj.line.trim())) {
+        return `Error: read arg "${labelPrefix}line" takes a single integer; for a line range use offset+limit as separate integers or "path#L<start>-L<end>" in the path arg (got "${obj.line}")`;
+    }
     if (!isFiniteInt(obj.line) || obj.line < 1) {
-        return `Error: read arg "${labelPrefix}line" must be a finite integer >= 1 (got ${describeType(obj.line)})`;
+        return `Error: read arg "${labelPrefix}line" must be a finite integer >= 1 (got ${describeType(obj.line)}); expected a single integer like 40`;
     }
     let ctx = 0;
     if (hasContext) {
+        if (typeof obj.context === 'string' && RANGE_SHAPED_INT_STRING.test(obj.context.trim())) {
+            return `Error: read arg "${labelPrefix}context" takes a single integer; for a line range use offset+limit as separate integers or "path#L<start>-L<end>" in the path arg (got "${obj.context}")`;
+        }
         if (!isFiniteInt(obj.context) || obj.context < 0) {
-            return `Error: read arg "${labelPrefix}context" must be a non-negative finite integer (got ${describeType(obj.context)})`;
+            return `Error: read arg "${labelPrefix}context" must be a non-negative finite integer (got ${describeType(obj.context)}); expected a single integer like 40`;
         }
         ctx = obj.context;
     }
@@ -381,13 +434,6 @@ function guardRead(a) {
     return null;
 }
 
-function guardDiagnostics(a) {
-    if (hasOwn(a, 'path') && a.path !== undefined && a.path !== null && !isNonEmptyString(a.path)) {
-        return `Error: diagnostics arg "path" must be a non-empty string (got ${describeType(a.path)})`;
-    }
-    return null;
-}
-
 function guardShell(a) {
     if (!hasOwn(a, 'command')) {
         return 'Error: shell requires "command"';
@@ -458,8 +504,13 @@ function guardList(a) {
 }
 
 function guardFind(a) {
-    if (!hasOwn(a, 'query') || typeof a.query !== 'string' || a.query.trim().length === 0) {
-        return `Error: find requires non-empty string "query" (got ${describeType(a.query)})`;
+    // query accepts string or string[] (query[] fans out per-lookup downstream).
+    const queryOk = hasOwn(a, 'query') && (
+        (typeof a.query === 'string' && a.query.trim().length > 0)
+        || (Array.isArray(a.query) && a.query.length > 0 && a.query.every((q) => typeof q === 'string' && q.trim().length > 0))
+    );
+    if (!queryOk) {
+        return `Error: find requires non-empty string (or string[]) "query" (got ${describeType(a.query)})`;
     }
     if (hasOwn(a, 'path') && !isString(a.path)) {
         return `Error: find arg "path" must be a string (got ${describeType(a.path)})`;
@@ -541,7 +592,6 @@ function guardCodeGraph(a) {
 const GUARDS = {
     grep: guardGrep,
     read: guardRead,
-    diagnostics: guardDiagnostics,
     shell: guardShell,
     task: guardTask,
     list: guardList,

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

@@ -39,6 +39,7 @@ import { normalizeErrorMessage } from './path-diagnostics.mjs';
 import { invalidateBuiltinResultCache } from './cache-layers.mjs';
 import { resolveOptionalCwd } from './cwd-utils.mjs';
 import { scrubLoaderVars, scrubProviderSecrets } from '../env-scrub.mjs';
+import { resolveSessionCwd, stateFilePath, wrapPowerShellWithCwdProbe, wrapBashWithCwdProbe } from '../shell-state.mjs';
 
 // Post-exec drift detection. After a foreground shell command, compare the
 // live mtime+size of files mixdog has already read this session against their
@@ -113,7 +114,12 @@ export async function executeBashTool(args, workDir, options = {}) {
     const requestedCwd = args.cwd ?? args.workdir;
     const cwdResult = resolveOptionalCwd(requestedCwd, workDir);
     if (cwdResult.error) return cwdResult.error;
-    const bashWorkDir = cwdResult.cwd;
+    // Session cwd carry-over (Claude Code style, no live shell): when the model
+    // passes an explicit cwd it wins and updates the store on the next probe;
+    // otherwise reuse the last stored cwd for this session if it still exists.
+    const _hasExplicitCwd = typeof requestedCwd === 'string' && requestedCwd.trim() !== '';
+    const _sessionCwdKey = options?.sessionId ?? options?.readStateScope ?? options?.callerSessionId ?? null;
+    const bashWorkDir = resolveSessionCwd(_sessionCwdKey, _hasExplicitCwd ? cwdResult.cwd : null, cwdResult.cwd);
     const _readStateScope = options?.readStateScope ?? options?.sessionId ?? null;
     const executionMode = resolveExecutionMode(args || {}, args?.run_in_background === true ? 'async' : 'sync');
     const runInBackground = executionMode === 'async';
@@ -318,8 +324,22 @@ export async function executeBashTool(args, workDir, options = {}) {
         try { bashAbortSignal = (await getAbortSignalForSession(options?.sessionId)) || null; }
         catch { bashAbortSignal = null; }
         const combinedBashAbort = _combineAbortSignals(bashAbortSignal, options?.abortSignal || null);
+        // Sync path only: chain a trailing cwd probe so the session's final
+        // working directory persists to the next shell call. Async jobs run
+        // detached and are intentionally excluded (they never reach here). The
+        // probe captures the command's exit status first and re-exits with it,
+        // so the exit code the model sees is unchanged.
+        let syncCommand = wrappedCommand;
+        try {
+            const _stateFile = stateFilePath(_sessionCwdKey);
+            if (_stateFile) {
+                syncCommand = (process.platform === 'win32' && shellType === 'powershell')
+                    ? wrapPowerShellWithCwdProbe(wrappedCommand, _stateFile)
+                    : wrapBashWithCwdProbe(wrappedCommand, _stateFile);
+            }
+        } catch { syncCommand = wrappedCommand; }
         const result = await execShellCommand({
-            shell, shellArg, shellArgs, command: wrappedCommand,
+            shell, shellArg, shellArgs, command: syncCommand,
             env: spawnEnv,
             cwd: bashWorkDir,
             timeoutMs: timeout,

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

@@ -17,7 +17,7 @@ export const BUILTIN_TOOLS = [
         name: 'read',
         title: 'Mixdog Read',
         annotations: { title: 'Mixdog Read', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false },
-        description: 'Read known file path(s). Prefer grep content_with_context or code_graph anchors first. Window with numeric offset+limit only. Batch paths/regions as real arrays; adjacent spans in one file = one window, not repeated calls. Dirs use list.',
+        description: 'Read known file path(s). Prefer grep content_with_context or code_graph anchors first. Window with numeric offset+limit. Batch paths/regions as real arrays; adjacent spans in one file = one window, not repeated calls. Dirs use list.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -42,56 +42,27 @@ export const BUILTIN_TOOLS = [
                             minItems: 1,
                         },
                     ],
-                    description: 'File path, path[], or {path,offset,limit}[] region objects. Pass arrays directly; JSON strings are legacy recovery only.',
+                    description: 'File path. Batch spans via path[] or {path,offset,limit}[] regions. Pass arrays directly; JSON strings are legacy recovery only.',
                 },
                 offset: { type: 'number', minimum: 0, description: 'Numeric lines to skip before reading; 0 starts at line 1. Continue with offset:N.' },
                 limit: { type: 'number', minimum: 1, description: 'Numeric max lines to return after offset.' },
             },
         },
     },
-    {
-        name: 'diagnostics',
-        title: 'Mixdog Diagnostics',
-        annotations: { title: 'Mixdog Diagnostics', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true, compressible: true },
-        description: 'Run matching type/lint checker. Default cwd; no LSP.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                path: { type: 'string', description: 'File/dir. Default cwd.' },
-            },
-            required: [],
-        },
-    },
-    {
-        name: 'open_config',
-        title: 'Open Config UI',
-        // agentHidden: a worker/reviewer session has no business popping the
-        // settings UI on the user's machine; it also wastes schema bytes on
-        // every agent request. Lead keeps it.
-        annotations: { title: 'Open Config UI', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false, agentHidden: true },
-        description: 'Open settings UI; returns URL. No params.',
-        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
-    },
     {
         name: 'shell',
         title: 'Mixdog Shell',
         annotations: { title: 'Mixdog Shell', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, compressible: true },
-        description: `Run shell to CHANGE state or RUN programs (git/build/test/run). Never to inspect the filesystem — reading, listing, searching, or checking existence go through the dedicated tools, never a shell command. Set shell: powershell or bash. ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
+        description: `Run shell to CHANGE state or RUN programs (git/build/test/run). Never to inspect the filesystem — reading, listing, searching, existence checks use the dedicated tools, never shell. Set shell: powershell or bash. ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
         inputSchema: {
             type: 'object',
             properties: {
                 command: { type: 'string', description: 'Command.' },
-                cwd: { type: 'string', description: 'Working directory.' },
-                workdir: { type: 'string', description: 'Alias for cwd; omit if empty.' },
+                cwd: { type: 'string', description: 'Working directory. Persists across shell calls in a session — omit to reuse the previous command\'s directory (e.g. after cd); pass an absolute path to change it.' },
                 timeout: { type: 'number', description: 'Timeout ms.' },
                 merge_stderr: { type: 'boolean', description: 'Merge stderr.' },
                 mode: { type: 'string', enum: ['sync', 'async'], description: executionModeSchemaDescription('sync') },
-                run_in_background: { type: 'boolean', description: `Legacy alias for mode=async. ${TOOL_ASYNC_EXECUTION_CONTRACT}` },
-                persistent: { type: 'boolean', description: 'Persistent shell mode.' },
-                session_id: { type: 'string', description: 'Persistent shell id.' },
-                create: { type: 'boolean', description: 'Create session_id if missing.' },
-                close: { type: 'boolean', description: 'Close persistent session.' },
-                shell: { type: 'string', enum: ['bash', 'powershell'], description: 'Force shell. Windows default is PowerShell; bash means Git Bash/POSIX.' },
+                shell: { type: 'string', enum: ['bash', 'powershell'], description: 'Force shell. Windows defaults to PowerShell; bash = Git Bash/POSIX.' },
             },
             required: ['command'],
         },
@@ -116,7 +87,7 @@ export const BUILTIN_TOOLS = [
         name: 'grep',
         title: 'Mixdog Grep',
         annotations: { title: 'Mixdog Grep', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Search file contents by text/regex in a known scope. Use files_with_matches/count for broad anchors, content_with_context for narrow code answers. One concept → one grep.',
+        description: 'Search file contents by text/regex in a known scope. files_with_matches/count for broad anchors, content_with_context for narrow answers. One concept → one grep; multiple scopes = ONE call with path[].',
         inputSchema: {
             type: 'object',
             properties: {
@@ -127,7 +98,13 @@ export const BUILTIN_TOOLS = [
                     ],
                     description: 'Text/regex. Put synonyms in pattern[] as OR in ONE grep; no serial rewording or equivalent repeats.',
                 },
-                path: { type: 'string', description: 'Known narrowest file/dir; broad scopes return paths first, then refine from returned paths.' },
+                path: {
+                    anyOf: [
+                        { type: 'string' },
+                        { type: 'array', items: { type: 'string' }, minItems: 1 },
+                    ],
+                    description: 'Known narrowest file/dir, or path[] to search several scopes in one call; broad scopes return paths first, then refine from returned paths.',
+                },
                 glob: {
                     anyOf: [
                         { type: 'string' },
@@ -136,9 +113,11 @@ export const BUILTIN_TOOLS = [
                     description: 'Narrow in same grep; no follow-up grep for equivalent scope changes.',
                 },
                 output_mode: { type: 'string', enum: ['content_with_context', 'content', 'files_with_matches', 'count'], description: 'Broad scope: files_with_matches/count. Narrow scope: content_with_context; answer from it, skip read unless span is not shown.' },
-                context: { type: 'number', minimum: 0, description: 'Lines before/after each match; keep bounded.' },
                 head_limit: { type: 'number', minimum: 0, description: 'Max output lines; keep small.' },
                 offset: { type: 'number', minimum: 0, description: 'Skip output lines for paging.' },
+                '-A': { type: 'number', minimum: 0, description: 'Lines after each match.' },
+                '-B': { type: 'number', minimum: 0, description: 'Lines before each match.' },
+                '-C': { type: 'number', minimum: 0, description: 'Lines before/after each match.' },
             },
             required: [],
         },
@@ -147,7 +126,7 @@ export const BUILTIN_TOOLS = [
         name: 'glob',
         title: 'Mixdog Glob',
         annotations: { title: 'Mixdog Glob', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Find files by exact glob. Unknown path/name uses find.',
+        description: 'Find files by exact glob. Unknown path/name uses find. Multiple patterns/dirs = ONE call with pattern[]/path[], never parallel single-pattern calls.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -156,14 +135,14 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Exact glob pattern(s).',
+                    description: 'Exact glob pattern(s). Batch related patterns as pattern[] in one call.',
                 },
                 path: {
                     anyOf: [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Base directory/directories.',
+                    description: 'Base directory/directories. Batch multiple roots as path[] in one call.',
                 },
                 head_limit: { type: 'number', description: 'Max entries.' },
                 offset: { type: 'number', description: 'Skip entries.' },
@@ -175,11 +154,17 @@ export const BUILTIN_TOOLS = [
         name: 'find',
         title: 'Mixdog Find Files',
         annotations: { title: 'Mixdog Find Files', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Find files by partial path/name. Exact structure uses glob. Returns verified paths.',
+        description: 'Find files by partial path/name. Exact structure uses glob. Returns verified paths. Multiple names = ONE call with query[].',
         inputSchema: {
             type: 'object',
             properties: {
-                query: { type: 'string', description: 'Partial path/name words; not file contents.' },
+                query: {
+                    anyOf: [
+                        { type: 'string' },
+                        { type: 'array', items: { type: 'string' }, minItems: 1 },
+                    ],
+                    description: 'Partial path/name words (not file contents), or query[] to batch lookups in one call.',
+                },
                 path: { type: 'string', description: 'Base directory.' },
                 head_limit: { type: 'number', description: 'Max paths.' },
             },
@@ -190,11 +175,17 @@ export const BUILTIN_TOOLS = [
         name: 'list',
         title: 'Mixdog List Directory',
         annotations: { title: 'Mixdog List Directory', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'List known directory entries. Use glob for broad discovery.',
+        description: 'List known directory entries. Use glob for broad discovery. Multiple dirs = ONE call with path[].',
         inputSchema: {
             type: 'object',
             properties: {
-                path: { type: 'string', description: 'Directory.' },
+                path: {
+                    anyOf: [
+                        { type: 'string' },
+                        { type: 'array', items: { type: 'string' }, minItems: 1 },
+                    ],
+                    description: 'Directory, or path[] to list several directories in one call.',
+                },
                 head_limit: { type: 'number', description: 'Max entries.' },
                 offset: { type: 'number', description: 'Skip N entries for paging.' },
             },

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

@@ -60,6 +60,26 @@ function listGuardPath(p) {
 }
 
 export async function executeListTool(args, workDir, options = {}) {
+    if (Array.isArray(args.path)) {
+        const list = [...new Set(args.path.map((p) => (typeof p === 'string' ? p.trim() : '')).filter((p) => p.length > 0))];
+        const capped = list.length > 10;
+        const targets = capped ? list.slice(0, 10) : list;
+        if (targets.length > 1) {
+            const sections = [];
+            for (const p of targets) {
+                let body;
+                try {
+                    body = await executeListTool({ ...args, path: p }, workDir, options);
+                } catch (err) {
+                    body = `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+                }
+                sections.push(`# list ${p}\n${body}`);
+            }
+            if (capped) sections.push(`... [capped at 10 of ${list.length} paths]`);
+            return sections.join('\n\n');
+        }
+        args.path = targets[0];
+    }
     if (typeof args.fuzzy === 'string' && args.fuzzy.length > 0) {
         return executeFuzzyFindTool({ ...args, query: args.fuzzy }, workDir, options);
     }
@@ -302,6 +322,26 @@ export async function executeTreeTool(args, workDir, options = {}) {
 // routes here for hidden backward compatibility, but the model-facing tool is
 // `find`.
 export async function executeFuzzyFindTool(args, workDir, options = {}) {
+    if (Array.isArray(args.query)) {
+        const list = [...new Set(args.query.map((q) => (typeof q === 'string' ? q.trim() : '')).filter((q) => q.length > 0))];
+        const capped = list.length > 10;
+        const targets = capped ? list.slice(0, 10) : list;
+        if (targets.length > 1) {
+            const sections = [];
+            for (const q of targets) {
+                let body;
+                try {
+                    body = await executeFuzzyFindTool({ ...args, query: q }, workDir, options);
+                } catch (err) {
+                    body = `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+                }
+                sections.push(`# find ${q}\n${body}`);
+            }
+            if (capped) sections.push(`... [capped at 10 of ${list.length} queries]`);
+            return sections.join('\n\n');
+        }
+        args.query = targets[0];
+    }
     const query = String(args.query ?? args.fuzzy ?? '').trim();
     if (!query) return 'Error: find requires query.';
     const inputPath = normalizeInputPath(args.path) || '.';

package/src/runtime/agent/orchestrator/tools/builtin/rg-runner.mjs

@@ -181,6 +181,35 @@ async function assertRgAvailable() {
     throw e;
 }
 
+// ── PCRE2 capability detection ───────────────────────────────────────────
+// ripgrep's default regex engine (Rust `regex` crate) intentionally rejects
+// lookaround/backreferences ("look-around ... is not supported" /
+// "backreferences ... not supported"). Some rg builds are compiled with the
+// optional `pcre2` feature, which adds `-P`/`--pcre2` support for exactly
+// those constructs. Detect capability once via `rg --pcre2-version`: it
+// exits 0 and prints a version when PCRE2 is linked in, and exits non-zero
+// ("PCRE2 is not available...") when it is not. Cached permanently on
+// success; failure is cached briefly so a mid-session rg upgrade/reinstall
+// is picked up without a daemon restart (mirrors rgFallbackUsable's TTL).
+const RG_PCRE2_FAIL_TTL_MS = 30000;
+let _rgPcre2Supported = null;
+let _rgPcre2FailAt = 0;
+export async function rgSupportsPcre2() {
+    if (_rgPcre2Supported === true) return true;
+    if (_rgPcre2Supported === false && (Date.now() - _rgPcre2FailAt) < RG_PCRE2_FAIL_TTL_MS) {
+        return false;
+    }
+    try {
+        await ensureRgResolved();
+        await execFileAsync(rgExecutable(), ['--pcre2-version'], { windowsHide: true, timeout: 3000 });
+        _rgPcre2Supported = true;
+    } catch {
+        _rgPcre2Supported = false;
+        _rgPcre2FailAt = Date.now();
+    }
+    return _rgPcre2Supported;
+}
+
 // Cap rg stdout accumulation so a runaway producer (huge repo, accidental
 // match-all) cannot balloon the JS string heap. Mirrors CC's ripgrep.ts cap.
 const MAX_RG_STDOUT_BYTES = 20 * 1024 * 1024; // 20MB

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

@@ -29,6 +29,7 @@ export function buildGrepCacheKey(parts) {
         multilineMode,
         fileType,
         onlyMatching,
+        pcre2,
     } = parts;
     return [
         'grep',
@@ -46,6 +47,7 @@ export function buildGrepCacheKey(parts) {
         multilineMode ? 'm1' : 'm0',
         onlyMatching ? 'o1' : 'o0',
         Array.isArray(fileType) ? fileType.join('\x01') : (fileType || ''),
+        pcre2 ? 'p1' : 'p0',
     ].join('|');
 }
 
@@ -64,6 +66,7 @@ export function buildGrepRgArgs(parts) {
         fileType,
         onlyMatching,
         fixedStrings = false,
+        pcre2 = false,
     } = parts;
     // `--hidden`: search dotfiles/dot-dirs (.github, .mixdog) that
     // rg skips by default. The DEFAULT_IGNORE_GLOBS below still exclude .git and
@@ -84,6 +87,11 @@ export function buildGrepRgArgs(parts) {
     }
     if (caseInsensitive) rgArgs.push('-i');
     if (fixedStrings) rgArgs.push('-F');
+    // PCRE2 engine: opt-in only when the caller already confirmed (via
+    // rgSupportsPcre2() in search-tool.mjs) that the installed rg binary was
+    // built with PCRE2 support. Enables lookaround/backreference patterns
+    // that the default Rust regex engine rejects outright.
+    if (pcre2) rgArgs.push('-P');
     if (multilineMode) rgArgs.push('-U', '--multiline-dotall');
     if (Array.isArray(fileType)) {
         for (const t of fileType) if (t) rgArgs.push('--type', t);

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

@@ -0,0 +1,126 @@
+/**
+ * Search path diagnostics: ENOENT recovery + path-shape helpers shared by
+ * grep/glob in search-tool.mjs. Extracted verbatim so search-tool.mjs stays a
+ * thin executor; search-tool.mjs re-exports these for unchanged importers.
+ */
+import { statSync } from 'fs';
+import { isAbsolute, resolve } from 'path';
+import { findBySuffixStrip, findFileByBasename } from './path-diagnostics.mjs';
+import { normalizeOutputPath, resolveAgainstCwd } from './path-utils.mjs';
+
+// Deterministic ENOENT recovery: when a grep path does not exist, surface
+// indexed files that share the missing path's basename, turning a guessed or
+// misplaced path (e.g. session/result-compression.mjs vs the real
+// tools/result-compression.mjs) into the actual file in one step. Exact
+// basename only — no stem/token fuzzing — so the hint is high-signal and
+// noise-free. Invariant: every ENOENT runs the same basename lookup; there is
+// no "guessed a lot" branch. Returns '' (appends nothing) when no same-named
+// indexed file exists or the glob child is unavailable.
+export async function _suggestIndexedPaths(missingPath, executeChildBuiltinTool, workDir) {
+    if (typeof executeChildBuiltinTool !== 'function') return '';
+    const base = String(missingPath).replace(/\\/g, '/').split('/').pop();
+    // Skip when there is no usable basename or it carries glob magic (the
+    // pattern, not a literal filename, would not map to a real file).
+    if (!base || /[*?[\]{}]/.test(base)) return '';
+    try {
+        const out = await executeChildBuiltinTool('glob', { pattern: `**/${base}`, head_limit: 6 }, workDir);
+        if (typeof out !== 'string') return '';
+        // Drop ONLY the exact diagnostic forms glob emits: the empty-result line
+        // ("(no files found ...", "(no entries after offset ...") and the
+        // suffix/warning lines ("... [N more entries]", "... [warning] ...").
+        // A broad startsWith('(' / '...' / 'Error') would wrongly drop real
+        // paths like ErrorBoundary.mjs or a "(draft)/x.mjs" leading segment.
+        const hits = out.split('\n')
+            .filter((s) => s && !/^\(no (?:files found|entries\b)/.test(s) && !/^\.\.\. \[/.test(s))
+            .map((s) => s.trim())
+            .filter(Boolean)
+            .slice(0, 5);
+        return hits.length ? `\n[path not found here; same-named indexed file(s): ${hits.join(', ')}]` : '';
+    } catch {
+        return '';
+    }
+}
+
+// Models occasionally glue a quoted segment onto an otherwise-unquoted path
+// (e.g. `C:/Project/mixdog/"src/x.mjs"` — prefix bare, trailing segment
+// wrapped in literal quote chars from a mis-escaped interpolation). But
+// quote chars CAN be legit path content (POSIX `src/Bob's/file.mjs`), so
+// stripping is existence-guarded: keep the original if it stats, only fall
+// back to the stripped variant otherwise. Cost is one statSync and only on
+// the rare quote-containing path.
+export function stripEmbeddedPathQuotes(p) {
+    if (typeof p !== 'string' || !p) return p;
+    if (!p.includes('"') && !p.includes("'")) return p;
+    try { statSync(p); return p; } catch { /* fall through to stripped */ }
+    return p.replace(/['"]/g, '');
+}
+
+// Reuse read's own ENOENT recovery (path-diagnostics findBySuffixStrip /
+// findFileByBasename — the exact fs scans read-single-tool.mjs already runs
+// for its "same filename exists at" hint) so a grep/glob path miss redirects
+// to the real location instead of dead-ending. No new fs scan is added here;
+// this only calls the two helpers read already calls, with a caller-supplied
+// action verb ("Search"/"List") in place of read's "Read". Gated to genuine
+// not-found codes: EACCES/EPERM etc. keep their real failure semantics and
+// must not trigger same-basename guidance or the BFS scan.
+const NOT_FOUND_CODES = new Set(['ENOENT', 'ENOTDIR']);
+export function buildNotFoundHint(workDir, missingPath, actionVerb, errCode = 'ENOENT') {
+    if (!NOT_FOUND_CODES.has(String(errCode || 'ENOENT'))) return '';
+    const suffixHit = findBySuffixStrip(workDir, missingPath);
+    if (suffixHit) {
+        return ` Not found at this path; the same filename exists at: "${normalizeOutputPath(suffixHit)}". ${actionVerb} that path directly.`;
+    }
+    const elsewhere = findFileByBasename(workDir, missingPath);
+    if (elsewhere.length) {
+        return ` Not found at this path; the same filename exists at: ${elsewhere.map((p) => `"${normalizeOutputPath(p)}"`).join(', ')}. ${actionVerb} that path directly.`;
+    }
+    return '';
+}
+
+export function relativePathPrefix(pathPrefix, workDir) {
+    if (!workDir) return pathPrefix;
+    const cwdFwd = workDir.replace(/\\/g, '/').replace(/\/+$/, '');
+    const absFwd = String(pathPrefix || '').replace(/\\/g, '/');
+    const haystack = process.platform === 'win32' ? absFwd.toLocaleLowerCase() : absFwd;
+    const needle = process.platform === 'win32' ? cwdFwd.toLocaleLowerCase() : cwdFwd;
+    if (haystack.startsWith(needle + '/') || haystack === needle) {
+        return absFwd.slice(cwdFwd.length + 1) || '.';
+    }
+    return pathPrefix;
+}
+
+export function relativeSearchResultPath(path, workDir) {
+    const normalizedWorkDir = normalizeOutputPath(workDir);
+    const normalizedAbs = normalizeOutputPath(path);
+    if (normalizedAbs.startsWith(normalizedWorkDir + '/') || normalizedAbs.startsWith(normalizedWorkDir + '\\')) {
+        return normalizedAbs.slice(normalizedWorkDir.length + 1);
+    }
+    return normalizedAbs;
+}
+
+export function resolveSearchScope(root, workDir) {
+    return isAbsolute(root) ? resolve(root) : resolveAgainstCwd(root, workDir);
+}
+
+export function isUncOrSmbPath(path) {
+    if (typeof path !== 'string' || !path) return false;
+    return path.startsWith('\\\\') || path.startsWith('//');
+}
+
+export function uncRefusalMessage(toolName, original, resolved) {
+    const shown = normalizeOutputPath(resolved || original || '');
+    return `Error: ${toolName} refuses UNC/SMB path ${JSON.stringify(shown)}; remote share access is blocked to prevent NTLM credential leaks`;
+}
+
+export function basePathDiagnostic(basePaths, workDir) {
+    return basePaths.map((basePath) => {
+        const resolved = resolveSearchScope(basePath, workDir);
+        try {
+            const st = statSync(resolved);
+            return `${normalizeOutputPath(basePath)}: ${st.isDirectory() ? 'path exists (dir)' : 'path exists (file)'}`;
+        } catch (err) {
+            return `${normalizeOutputPath(basePath)}: path does not exist (${err?.code || 'ENOENT'})`
+                + buildNotFoundHint(workDir, resolved, 'Search', err?.code);
+        }
+    }).join('; ');
+}