mixdog 0.9.2 → 0.9.4

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. Dirs use list.',
+        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.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -42,36 +42,13 @@ 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. Dirs use list.',
+                    description: 'File path. To batch spans: path[] or {path,offset,limit}[] region objects. 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',
@@ -81,16 +58,10 @@ export const BUILTIN_TOOLS = [
             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 within 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.' },
             },
             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. Use files_with_matches/count for broad anchors, content_with_context for narrow code 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 several 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/external-tool-adapters.mjs

@@ -0,0 +1,241 @@
+// Native adapters for well-known tool names from OTHER agent CLIs whose
+// argument shapes differ from any mixdog builtin (StrReplace/Write/bash
+// variants). Executed directly against the filesystem via atomicWrite / the
+// existing shell runner — NOT by synthesizing an apply_patch V4A string
+// (that approach was tried and abandoned: building a correct V4A envelope
+// from arbitrary old_string/new_string/contents blew up in edge-case
+// complexity for no benefit over a direct fs edit).
+//
+// Contract: tryExecuteExternalToolAdapter(name, args, workDir, options)
+// returns a result STRING when the call was handled (success or a concrete
+// tool-level error), or `null` when the args shape didn't match what the
+// adapter expects — the caller (builtin.mjs default: case) falls back to
+// the existing EXTERNAL_TOOL_REDIRECTS guidance message in that case.
+import { readFileSync, mkdirSync, existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
+import { dirname, sep } from 'node:path';
+import { atomicWrite } from './atomic-write.mjs';
+import { assertPathsReachable } from './fs-reachability.mjs';
+import { normalizeInputPath, resolveAgainstCwd, normalizeOutputPath } from './path-utils.mjs';
+import { isUncPath, isWindowsDevicePath, hasUnsafeWin32Component, isBlockedDevicePath, isSpecialFileStat } from './device-paths.mjs';
+import { executeBashTool } from './bash-tool.mjs';
+import { invalidateBuiltinResultCache } from './cache-layers.mjs';
+import { markCodeGraphDirtyPaths } from '../code-graph-state.mjs';
+
+const STR_REPLACE_NAMES = new Set(['strreplace', 'str_replace', 'str_replace_editor', 'search_replace']);
+const WRITE_NAMES = new Set(['write', 'create_file', 'createfile']);
+// 'bash'/'Bash' explicitly request the posix/git-bash shell kind; the
+// run/runcommand/terminal/run_terminal_cmd family leaves `shell` unset so
+// executeBashTool's own default-shell resolution applies (mirrors how the
+// native `shell` tool behaves when the caller omits `shell`).
+const BASH_SHELL_KIND_NAMES = new Set(['bash']);
+const BASH_DEFAULT_NAMES = new Set(['run', 'runcommand', 'terminal', 'run_terminal_cmd']);
+
+/**
+ * True when `name` is a foreign-CLI tool this module can adapt natively.
+ * Used by the session loop's dispatch so these names route INTO
+ * executeBuiltinTool (whose default: case invokes the adapter) instead of
+ * short-circuiting to the unknown-tool redirect message.
+ */
+export function isExternalAdapterTool(name) {
+    if (typeof name !== 'string' || !name) return false;
+    const key = name.toLowerCase();
+    return STR_REPLACE_NAMES.has(key) || WRITE_NAMES.has(key)
+        || BASH_SHELL_KIND_NAMES.has(key) || BASH_DEFAULT_NAMES.has(key);
+}
+
+// Same write-target guards the read/list surfaces enforce (UNC → NTLM hash
+// leak, device namespace → raw device access / hang, trailing-dot / ADS →
+// device-guard bypass). Writes are strictly more dangerous than reads, so
+// every adapter write path must run these on both the normalized input and
+// the fully resolved path. Returns an Error string or null.
+function guardWritePath(p) {
+    if (isUncPath(p))
+        return `Error: cannot write UNC / SMB path (network credential leak risk): ${normalizeOutputPath(p)}`;
+    if (isWindowsDevicePath(p))
+        return `Error: cannot write Windows device path (reserved name or raw-device namespace): ${normalizeOutputPath(p)}`;
+    if (hasUnsafeWin32Component(p))
+        return `Error: cannot write Windows path with trailing dot/space or NTFS ADS suffix (bypasses device guard): ${normalizeOutputPath(p)}`;
+    if (isBlockedDevicePath(p))
+        return `Error: cannot write device file (would block or corrupt a device): ${normalizeOutputPath(p)}`;
+    return null;
+}
+
+// Realpath to the nearest existing ancestor (create-mode leaves don't exist
+// yet). Returns { probe, real } or null when nothing on the path exists /
+// realpath itself fails.
+function realpathNearestExisting(fullPath) {
+    let probe = fullPath;
+    while (probe && !existsSync(probe)) {
+        const parent = dirname(probe);
+        if (!parent || parent === probe) return null;
+        probe = parent;
+    }
+    if (!probe || !existsSync(probe)) return null;
+    try { return { probe, real: realpathSync(probe) }; } catch { return null; }
+}
+
+// Realpath-based guard: a symlink/junction in the target (or its nearest
+// existing ancestor, for create-mode paths) can point at a UNC share or a
+// device namespace that the lexical checks above never see. Mirrors the
+// realpath verification apply_patch runs on every header. Returns an Error
+// string or null; never throws.
+function guardRealTarget(fullPath) {
+    const nearest = realpathNearestExisting(fullPath);
+    if (nearest && nearest.real !== nearest.probe) {
+        const guardErr = guardWritePath(nearest.real);
+        if (guardErr) return `${guardErr} (symlink target of ${normalizeOutputPath(nearest.probe)})`;
+    }
+    try {
+        const lst = lstatSync(fullPath);
+        if (lst.isSymbolicLink()) {
+            const realTarget = realpathSync(fullPath);
+            const linkGuardErr = guardWritePath(realTarget);
+            if (linkGuardErr) return `${linkGuardErr} (symlink target of ${normalizeOutputPath(fullPath)})`;
+        }
+        // statSync FOLLOWS a leaf symlink, so a link pointing at a custom
+        // FIFO/socket/char/block inode trips here too (lstat alone only saw
+        // the link inode itself).
+        const st = statSync(fullPath);
+        if (isSpecialFileStat(st))
+            return `Error: cannot write special file (FIFO / character / block device / socket): ${normalizeOutputPath(fullPath)}`;
+    } catch { /* ENOENT (create mode) — nothing to check */ }
+    return null;
+}
+
+// Write containment — mirrors apply_patch's realBase check: the REAL resolved
+// target (symlinks flattened, create-mode suffix re-attached lexically) must
+// stay inside the REAL workDir. A lexically-inside path whose ancestor
+// symlink/junction lands outside the project must not be writable through
+// this adapter surface (apply_patch refuses the same shape).
+function guardBaseContainment(fullPath, workDir) {
+    let realBase;
+    try { realBase = realpathSync(workDir); } catch { return null; }
+    const nearest = realpathNearestExisting(fullPath);
+    if (!nearest) return null;
+    const realResolved = nearest.real + fullPath.slice(nearest.probe.length);
+    const fold = process.platform === 'win32' ? (s) => s.toLowerCase() : (s) => s;
+    const baseWithSep = realBase.endsWith(sep) ? realBase : realBase + sep;
+    if (fold(realResolved) !== fold(realBase) && !fold(realResolved).startsWith(fold(baseWithSep))) {
+        return `Error: cannot write outside the working directory: ${normalizeOutputPath(realResolved)} escapes ${normalizeOutputPath(realBase)}`;
+    }
+    return null;
+}
+
+async function resolveTargetPath(args, workDir) {
+    const raw = args?.path ?? args?.file_path;
+    if (typeof raw !== 'string' || raw.length === 0) return null;
+    const norm = normalizeInputPath(raw);
+    const guardErr = guardWritePath(norm);
+    if (guardErr) return { error: guardErr };
+    const full = resolveAgainstCwd(norm, workDir);
+    const fullGuardErr = guardWritePath(full);
+    if (fullGuardErr) return { error: fullGuardErr };
+    // Reachability preflight BEFORE any sync fs (existsSync/realpathSync/
+    // lstatSync in the guards below): a dead mount would wedge the event loop
+    // on the first sync stat, defeating every downstream timeout. Same
+    // deadline-raced probe the read path runs (_readReachPreflight).
+    try { await assertPathsReachable([full]); }
+    catch (e) { return { error: `Error: ${e?.message || e}` }; }
+    const realGuardErr = guardRealTarget(full);
+    if (realGuardErr) return { error: realGuardErr };
+    const containErr = guardBaseContainment(full, workDir);
+    if (containErr) return { error: containErr };
+    return { full };
+}
+
+function invalidateAfterWrite(fullPath) {
+    try { invalidateBuiltinResultCache([fullPath]); } catch { /* best-effort */ }
+    try { markCodeGraphDirtyPaths([fullPath]); } catch { /* best-effort */ }
+}
+
+function countOccurrences(haystack, needle) {
+    let count = 0;
+    let idx = -1;
+    while ((idx = haystack.indexOf(needle, idx + 1)) !== -1) count += 1;
+    return count;
+}
+
+async function adaptStrReplace(args, workDir, options) {
+    const oldStr = args?.old_string;
+    const newStr = args?.new_string;
+    if (typeof oldStr !== 'string' || typeof newStr !== 'string') return null;
+    // Empty old_string would loop forever in countOccurrences (indexOf('', i)
+    // never returns -1) and has no meaningful replace semantics anyway.
+    if (oldStr.length === 0) return 'Error: old_string must be a non-empty string';
+    const target = await resolveTargetPath(args, workDir);
+    if (!target) return null;
+    if (target.error) return target.error;
+    const fullPath = target.full;
+    let content;
+    let statBefore = null;
+    try {
+        try { statBefore = statSync(fullPath); } catch { /* readFileSync below surfaces the real error */ }
+        content = readFileSync(fullPath, 'utf8');
+    } catch (err) {
+        return `Error: cannot read ${fullPath} (${err?.message || err})`;
+    }
+    const matchCount = countOccurrences(content, oldStr);
+    if (matchCount === 0) return `Error: old_string not found in ${fullPath}`;
+    if (matchCount > 1) return `Error: old_string is ambiguous: ${matchCount} matches in ${fullPath}`;
+    const first = content.indexOf(oldStr);
+    const updated = content.slice(0, first) + newStr + content.slice(first + oldStr.length);
+    // Lost-update guard: hand the pre-read stat to atomicWrite as an expected
+    // target snapshot — it re-stats immediately before EACH rename attempt and
+    // aborts with ESTALE_TARGET when another writer (parallel tool call,
+    // interleaved apply_patch) changed the file after our read. This closes
+    // the check-then-write race a pre-write mtime comparison here would leave.
+    try {
+        await atomicWrite(fullPath, updated, {
+            sessionId: options?.readStateScope || options?.sessionId,
+            expectedTargetSnapshot: statBefore ? {
+                exists: true,
+                size: statBefore.size,
+                mtimeMs: statBefore.mtimeMs,
+                ctimeMs: statBefore.ctimeMs,
+                ino: statBefore.ino,
+            } : undefined,
+        });
+    } catch (err) {
+        if (err?.code === 'ESTALE_TARGET') {
+            return `Error: ${fullPath} changed on disk during the replace; re-read and retry`;
+        }
+        throw err;
+    }
+    invalidateAfterWrite(fullPath);
+    return `Updated ${fullPath} (1 replacement)`;
+}
+
+async function adaptWrite(args, workDir, options) {
+    const contents = args?.contents ?? args?.content ?? args?.file_text;
+    if (typeof contents !== 'string') return null;
+    const target = await resolveTargetPath(args, workDir);
+    if (!target) return null;
+    if (target.error) return target.error;
+    const fullPath = target.full;
+    const existed = existsSync(fullPath);
+    try { mkdirSync(dirname(fullPath), { recursive: true }); } catch { /* best-effort: parent may already exist */ }
+    await atomicWrite(fullPath, contents, { sessionId: options?.readStateScope || options?.sessionId });
+    invalidateAfterWrite(fullPath);
+    return `${existed ? 'Updated' : 'Created'} ${fullPath} (${Buffer.byteLength(contents, 'utf8')} bytes)`;
+}
+
+async function adaptBash(key, args, workDir, options) {
+    if (typeof args?.command !== 'string' || args.command.length === 0) return null;
+    const shellArgs = { ...args };
+    if (BASH_SHELL_KIND_NAMES.has(key) && shellArgs.shell === undefined) shellArgs.shell = 'bash';
+    return executeBashTool(shellArgs, workDir, options);
+}
+
+export async function tryExecuteExternalToolAdapter(name, args, workDir, options) {
+    if (typeof name !== 'string' || !name) return null;
+    if (!args || typeof args !== 'object' || Array.isArray(args)) return null;
+    const key = name.toLowerCase();
+    try {
+        if (STR_REPLACE_NAMES.has(key)) return await adaptStrReplace(args, workDir, options);
+        if (WRITE_NAMES.has(key)) return await adaptWrite(args, workDir, options);
+        if (BASH_SHELL_KIND_NAMES.has(key) || BASH_DEFAULT_NAMES.has(key)) return await adaptBash(key, args, workDir, options);
+    } catch (err) {
+        return `Error: ${name} failed (${err?.message || String(err)})`;
+    }
+    return null;
+}

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

@@ -1,5 +1,5 @@
 // fuzzy-match.mjs — lightweight subsequence fuzzy scorer for filename / path
-// search (codex file-search / nucleo style, in JS). Returns a score where a
+// search. Returns a score where a
 // higher value is a better match, or null when the query is not a subsequence
 // of the candidate.
 //

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/path-diagnostics.mjs

@@ -1,5 +1,5 @@
-import { readdirSync } from 'fs';
-import { basename, dirname, extname, isAbsolute, join, relative } from 'path';
+import { readdirSync, statSync } from 'fs';
+import { basename, dirname, extname, isAbsolute, join, relative, sep } from 'path';
 import { homedir } from 'os';
 import { resolvePluginData, mixdogRoot } from '../../../../shared/plugin-paths.mjs';
 
@@ -80,6 +80,46 @@ export function findFileByBasename(searchRoot, fullPath, { limit = 3, maxDirs =
     } catch { return []; }
 }
 
+// Recover a hallucinated absolute-path PREFIX: models frequently request
+// paths like /Users/foo/Local/Project/ink/src/tui/input-editing.mjs where the
+// TAIL (src/tui/input-editing.mjs) is the real repo-relative path but the
+// leading segments are an invented (or wrong-machine) prefix. findFileByBasename
+// only matches the final basename and walks the whole tree (skipping vendor/
+// noise dirs for performance); this instead peels leading segments off the
+// requested path one at a time and stats the remaining tail directly against
+// searchRoot — no directory walk, no skip-dir filtering, so it finds files
+// under vendor/ or any other normally-skipped directory. Min tail length is 2
+// segments so a bare basename (which would match almost anything) never
+// counts as a hit. Capped iterations; pure best-effort, never throws.
+export function findBySuffixStrip(searchRoot, fullPath, { maxIterations = 12 } = {}) {
+    try {
+        if (typeof searchRoot !== 'string' || !searchRoot) return null;
+        if (typeof fullPath !== 'string' || !fullPath) return null;
+        // Containment guard: drop `.`/`..` and drive/UNC-ish segments outright.
+        // Tails are joined under searchRoot; a `..` segment could stat (and
+        // hint) outside the repo, so no relative-traversal token may survive.
+        const segments = fullPath.replace(/\\/g, '/').split('/')
+            .filter((s) => s && s !== '.' && s !== '..' && !/^[A-Za-z]:$/.test(s));
+        // Peel 0..N leading segments; each peel costs one stat. maxIterations
+        // bounds the number of stats (strict <), and tails shorter than 2
+        // segments never count as a hit.
+        const iterations = Math.min(Math.max(segments.length - 1, 0), Math.max(maxIterations, 0));
+        for (let i = 0; i < iterations; i++) {
+            const tail = segments.slice(i);
+            if (tail.length < 2) break;
+            const candidate = join(searchRoot, ...tail);
+            const rel = relative(searchRoot, candidate);
+            if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) continue;
+            try {
+                if (statSync(candidate).isFile()) {
+                    return rel.replace(/\\/g, '/');
+                }
+            } catch { /* miss this tail length, keep peeling */ }
+        }
+        return null;
+    } catch { return null; }
+}
+
 // Node's native fs errors embed the failing path wrapped in single quotes
 // using OS-native separators ('C:\\Users\\foo\\bar.mjs' on Windows). Without
 // this pass, read error bodies surface backslash paths that

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

@@ -20,7 +20,7 @@ export const SMART_READ_TAIL_LINES = _readEnvInt('MIXDOG_READ_TAIL_LINES', 400);
 // file actually hurts.
 export const READ_CONTEXT_ADVISORY_BYTES = 40 * 1024;
 export const READ_MAX_RENDERED_LINE_CHARS = 2_000;
-// Claude-Code parity: the read line-prefix separator is `→` (the `→`
+// The read line-prefix separator is `→` (the `→`
 // arrow), matching default cat -n format `<n>→<content>`. It
 // MUST be a NON-WHITESPACE glyph: a tab/space separator collides with the
 // content's own leading indentation, so a model hand-reconstructing an edit

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

@@ -3,7 +3,7 @@ import * as fsPromises from 'fs/promises';
 import { readFile } from 'fs/promises';
 import { extname } from 'path';
 import { normalizeInputPath } from './path-utils.mjs';
-import { findFileByBasename } from './path-diagnostics.mjs';
+import { findFileByBasename, findBySuffixStrip } from './path-diagnostics.mjs';
 import { getReadSnapshot } from './read-snapshot-runtime.mjs';
 import { snapshotCoversFullFile, statMatchesSnapshot } from './snapshot-helpers.mjs';
 import { formatBinaryReadPreview } from './binary-file.mjs';
@@ -209,9 +209,16 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
         // path(s) directly — the route a model would otherwise reconstruct with
         // a grep/glob storm.
         if (!similar) {
-            const elsewhere = findFileByBasename(workDir, fullPath);
-            if (elsewhere.length) {
-                hint = ` Not found at this path; the same filename exists at: ${elsewhere.map((p) => `"${normalizeOutputPath(p)}"`).join(', ')}. Read that path directly.`;
+            // Hallucinated absolute-prefix recovery first: no directory walk,
+            // stats directly (finds vendor/ paths the basename BFS skips).
+            const suffixHit = findBySuffixStrip(workDir, fullPath);
+            if (suffixHit) {
+                hint = ` Not found at this path; the same filename exists at: "${normalizeOutputPath(suffixHit)}". Read that path directly.`;
+            } else {
+                const elsewhere = findFileByBasename(workDir, fullPath);
+                if (elsewhere.length) {
+                    hint = ` Not found at this path; the same filename exists at: ${elsewhere.map((p) => `"${normalizeOutputPath(p)}"`).join(', ')}. Read that path directly.`;
+                }
             }
         }
         const _rawMsg = err instanceof Error ? err.message : String(err);

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