mixdog 0.8.1 → 0.9.1

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

@@ -30,11 +30,14 @@ import {
 import {
     cacheGet,
     cacheSet,
+    runResultCacheInFlight,
     statPathsForMtime,
 } from './cache-layers.mjs';
 import { recordReadSnapshot } from './read-snapshot-runtime.mjs';
 import { applyGrepContextLeadPolicy, GREP_CONTEXT_MAX } from './arg-guard.mjs';
 
+const MIXDOG_GREP_CASE_HINT_PROBE = /^(1|true|yes|on)$/i.test(String(process.env.MIXDOG_GREP_CASE_HINT_PROBE || ''));
+
 function expandLegacyEscapedAlternationPattern(rawPattern) {
     if (typeof rawPattern !== 'string' || !rawPattern.includes('\\|')) return null;
     const parts = rawPattern.split('\\|').map((part) => part.trim()).filter(Boolean);
@@ -180,6 +183,14 @@ function splitGlobString(value) {
     return out;
 }
 
+function isRedundantAllFilesGlob(value) {
+    const g = canonicalizeGlobSlashes(String(value || '').trim())
+        .replace(/^\.\//, '')
+        .replace(/^\/+/, '')
+        .replace(/\/+$/, '');
+    return g === '**/*' || g === '**';
+}
+
 function resolveSearchScope(root, workDir) {
     return isAbsolute(root) ? resolve(root) : resolveAgainstCwd(root, workDir);
 }
@@ -226,46 +237,6 @@ function parseGrepCountLine(line) {
     return { path, count };
 }
 
-// Per-pattern file-count probe for array grby: runs ONE rg --files-with-matches
-// per pattern (reusing the same scope/glob/type/flags as the merged search) so
-// the summary line can surface patterns that matched zero files — otherwise the
-// merged result hides which member of the array contributed nothing.
-async function _perPatternFileCounts({ patterns, searchPath, globPatterns, caseInsensitive, multilineMode, fileType, workDir }) {
-    const results = await Promise.all(patterns.map(async (pattern) => {
-        try {
-            const rgArgs = buildGrepRgArgs({
-                patterns: [pattern],
-                searchPath,
-                globPatterns,
-                outputMode: 'files_with_matches',
-                caseInsensitive,
-                showLineNumbers: false,
-                beforeN: null,
-                afterN: null,
-                contextN: null,
-                multilineMode,
-                fileType,
-                onlyMatching: false,
-            });
-            const stdout = await runRg(rgArgs, { cwd: workDir });
-            // A boxed partial/truncated stdout means the count is not the true
-            // total — render '?' rather than a misleadingly-low or zero number.
-            if (stdout && typeof stdout === 'object' && (stdout.partial || stdout.truncated)) return null;
-            return String(stdout).split('\n').filter(Boolean).length;
-        } catch {
-            // Probe threw → count unknown, NOT zero.
-            return null;
-        }
-    }));
-    // Quote first (so newline/control chars can't inject footer lines), then
-    // truncate the quoted string to 40 chars — matches the no-match path.
-    const trunc = (p) => {
-        const q = JSON.stringify(p);
-        return q.length > 40 ? `${q.slice(0, 40)}...` : q;
-    };
-    return `\n# per-pattern: ${patterns.map((p, i) => `${trunc(p)}=${results[i] === null ? '?' : `${results[i]} files`}`).join(', ')}`;
-}
-
 function formatGrepOutput({ windowed, totalWindowed, totalKnown, headLimit, offset, outputMode, patterns: _patterns, beforeN, afterN, contextN, searchPath, grepResolvedPath: _grepResolvedPath, workDir, globPatterns: _globPatterns, fileType: _fileType, filenameOmitted = false, prefix = '', broadAdvisory: _broadAdvisory = true }) {
     const lines = headLimit === Infinity ? windowed : windowed.slice(0, headLimit);
     const normalized = lines.map((line) => relativeGrepLine(line, workDir, outputMode === 'files_with_matches', outputMode, filenameOmitted));
@@ -378,7 +349,9 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
     // ripgrep `--glob` uses forward slashes on all platforms; canonicalize
     // `\`→`/` (win32 only) so a `**\*.ts` filter matches instead of being
     // parsed as an escape sequence.
-    const normalizedGlobPatterns = uniqueStrings(globPatterns.map(canonicalizeGlobSlashes));
+    const normalizedGlobPatterns = uniqueStrings(globPatterns
+        .map(canonicalizeGlobSlashes)
+        .filter((g) => !isRedundantAllFilesGlob(g)));
 
     const ALLOWED_OUTPUT_MODES = new Set(['files_with_matches', 'content', 'count']);
     const rawOutputMode = typeof args.output_mode === 'string' ? args.output_mode.trim() : '';
@@ -484,6 +457,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
     // drift detection. So only the fresh-compute path (below) records a read.
     if (cached !== null) return cached;
 
+    return await runResultCacheInFlight(cacheKey, async () => {
     let grepStat;
     try { grepStat = statSync(grepResolvedPath); }
     catch (err) {
@@ -597,7 +571,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
             // pre-offset matches) just means the window skipped past real
             // case-sensitive hits, so the hint would be misleading.
             const trueZeroMatch = offset === 0 && totalWindowed === 0;
-            if (trueZeroMatch && !caseInsensitive && patterns.length === 1 && /[A-Za-z]/.test(patterns[0])) {
+            if (MIXDOG_GREP_CASE_HINT_PROBE && trueZeroMatch && !caseInsensitive && patterns.length === 1 && /[A-Za-z]/.test(patterns[0])) {
                 try {
                     const probeArgs = buildGrepRgArgs({
                         patterns,
@@ -620,21 +594,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
                 } catch { /* best-effort hint */ }
             }
         }
-        // Array-pattern visibility: append a per-pattern file-count summary so
-        // zero-hit members of the merged result are not silently hidden.
-        let perPatternSummary = '';
-        if (patterns.length > 1) {
-            perPatternSummary = await _perPatternFileCounts({
-                patterns,
-                searchPath,
-                globPatterns: normalizedGlobPatterns,
-                caseInsensitive,
-                multilineMode,
-                fileType,
-                workDir: rgSpawnCwd,
-            });
-        }
-        const out = body + rgPartialSuffix + perPatternSummary;
+        const out = body + rgPartialSuffix;
         const shownLines = headLimit === Infinity ? windowed : windowed.slice(0, headLimit);
         const remaining = Math.max(0, totalWindowed - shownLines.length);
         // Mirrors formatGrepOutput truncation / totalKnown semantics.
@@ -749,6 +709,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
         const msg = stderr || err?.message || String(err);
         return `Error: ${msg.slice(0, 500)}`;
     }
+    });
 }
 
 export async function executeGlobTool(args, workDir, options = {}) {
@@ -835,6 +796,8 @@ export async function executeGlobTool(args, workDir, options = {}) {
         return `Error: invalid offset ${JSON.stringify(args.offset)}; expected a non-negative integer`;
     }
     const offset = offsetCoerced === null || offsetCoerced === 0 ? 0 : offsetCoerced;
+    const rawSort = typeof args.sort === 'string' ? args.sort.trim() : '';
+    const sortMode = rawSort === 'mtime' ? 'mtime' : 'natural';
     // Internal-only ignore extension (see normalizeGlobArgs). Caller (e.g.
     // ai-wrapped-dispatch broad-cwd preflight) appends basename ignore globs
     // so head_limit bounds SOURCE entries rather than artifact noise.
@@ -860,10 +823,11 @@ export async function executeGlobTool(args, workDir, options = {}) {
         .map((root) => normalizeOutputPath(resolvedForSearchRoot(root)))
         .sort()
         .join('\x01');
-    const cacheKey = buildGlobCacheKey({ patterns, basePath: cacheBasePath, headLimit, offset, extraIgnore: extraIgnoreGlobs });
+    const cacheKey = buildGlobCacheKey({ patterns, basePath: cacheBasePath, headLimit, offset, extraIgnore: extraIgnoreGlobs, sort: sortMode });
     const cached = cacheGet(cacheKey);
     if (cached !== null) return cached;
 
+    return await runResultCacheInFlight(cacheKey, async () => {
     const globGroups = [...groups.entries()];
 
     const allFiles = [];
@@ -929,23 +893,26 @@ export async function executeGlobTool(args, workDir, options = {}) {
     }
 
     const unique = Array.from(new Set(allFiles));
-    // Bound the post-rg stat phase: a single hung stat (dead mount /
-    // unresponsive network path) must not pin glob until the 600s bridge stall
-    // watchdog. Per-stat 5s deadline → a hung entry is treated as stat-failed
-    // and dropped, while normal local stats (sub-ms) are unaffected.
-    const withStatAll = await statPathsForMtime(unique, workDir, 64, { deadlineMs: 5000 });
-    const withStat = withStatAll.filter((entry) => entry?.stat != null);
-    withStat.sort((a, b) => {
-        const dm = b.mtime - a.mtime;
-        if (dm !== 0) return dm;
-        return globMtimeTiePath(a).localeCompare(globMtimeTiePath(b));
-    });
-    const totalBeforeOffset = withStat.length;
-    const windowed = offset > 0 ? withStat.slice(offset) : withStat;
-    const capped = (headLimit === Infinity ? windowed : windowed.slice(0, headLimit)).map((entry) => {
-        const abs = entry.full || resolveAgainstCwd(entry.path, workDir);
-        return relativeSearchResultPath(abs, workDir);
-    });
+    let orderedPaths;
+    if (sortMode === 'mtime') {
+        // Opt-in mtime sorting is intentionally slower: it stats every match.
+        // Bound the post-rg stat phase so a hung mount cannot pin glob until
+        // the agent stall watchdog fires.
+        const withStatAll = await statPathsForMtime(unique, workDir, 64, { deadlineMs: 5000 });
+        const withStat = withStatAll.filter((entry) => entry?.stat != null);
+        withStat.sort((a, b) => {
+            const dm = b.mtime - a.mtime;
+            if (dm !== 0) return dm;
+            return globMtimeTiePath(a).localeCompare(globMtimeTiePath(b));
+        });
+        orderedPaths = withStat.map((entry) => entry.full || resolveAgainstCwd(entry.path, workDir));
+    } else {
+        orderedPaths = unique.map((entry) => isAbsolute(entry) ? resolve(entry) : resolveAgainstCwd(entry, workDir));
+    }
+    const totalBeforeOffset = orderedPaths.length;
+    const windowed = offset > 0 ? orderedPaths.slice(offset) : orderedPaths;
+    const capped = (headLimit === Infinity ? windowed : windowed.slice(0, headLimit))
+        .map((abs) => relativeSearchResultPath(abs, workDir));
     const remaining = windowed.length - capped.length;
     const truncSuffix = accumTruncated
         ? '\n... [truncated at accumulation cap (50000)]'
@@ -979,4 +946,5 @@ export async function executeGlobTool(args, workDir, options = {}) {
         try { options.onProgress(`found ${totalBeforeOffset} files`); } catch { /* best-effort */ }
     }
     return out;
+    });
 }

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

@@ -1,4 +1,4 @@
-import { spawn } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, watch as fsWatch, writeFileSync } from 'fs';
 import * as fsPromises from 'fs/promises';
 import { basename, join } from 'path';
@@ -15,6 +15,8 @@ import {
 } from '../../../../shared/background-tasks.mjs';
 import { startChildGuardian } from '../../../../shared/child-guardian.mjs';
 
+globalThis.__mixdogShellJobsRuntimeLoaded = true;
+
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -220,29 +222,62 @@ function killProcessTree(pid, signal = 'SIGTERM') {
 // owned children. Async jobs are intentionally CLI-owned; no restart replay or
 // daemon handoff is attempted.
 const _liveJobPids = new Set();
+const _liveJobIdsByPid = new Map();
 let _shellJobsExitHookInstalled = false;
-function _registerLiveJobPid(pid) {
-    if (Number.isFinite(pid) && pid > 0) _liveJobPids.add(pid);
+function _registerLiveJobPid(pid, jobId = null) {
+    if (Number.isFinite(pid) && pid > 0) {
+        _liveJobPids.add(pid);
+        if (jobId) _liveJobIdsByPid.set(pid, jobId);
+    }
 }
 function _unregisterLiveJobPid(pid) {
-    if (Number.isFinite(pid) && pid > 0) _liveJobPids.delete(pid);
+    if (Number.isFinite(pid) && pid > 0) {
+        _liveJobPids.delete(pid);
+        _liveJobIdsByPid.delete(pid);
+    }
 }
-function _sweepLiveJobsSync() {
-    for (const pid of _liveJobPids) {
-        try {
-            if (process.platform === 'win32') {
-                spawn('taskkill', ['/pid', String(pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' });
+function _killLiveJobPid(pid, { sync = false } = {}) {
+    try {
+        if (process.platform === 'win32') {
+            if (sync) {
+                spawnSync('taskkill.exe', ['/pid', String(pid), '/t', '/f'], {
+                    windowsHide: true,
+                    stdio: 'ignore',
+                    timeout: 1500,
+                });
             } else {
-                try { process.kill(-pid, 'SIGKILL'); }
-                catch { try { process.kill(pid, 'SIGKILL'); } catch { /* ignore */ } }
+                spawn('taskkill', ['/pid', String(pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' });
             }
-        } catch { /* ignore */ }
+        } else {
+            try { process.kill(-pid, 'SIGKILL'); }
+            catch { try { process.kill(pid, 'SIGKILL'); } catch { /* ignore */ } }
+        }
+        return true;
+    } catch {
+        return false;
+    }
+}
+function _sweepLiveJobsSync() {
+    for (const pid of _liveJobPids) {
+        _killLiveJobPid(pid, { sync: true });
     }
     _liveJobPids.clear();
+    _liveJobIdsByPid.clear();
+}
+function _ensureProcessListenerHeadroom(events, extra = 1) {
+    try {
+        if (typeof process.getMaxListeners !== 'function' || typeof process.setMaxListeners !== 'function') return;
+        const current = process.getMaxListeners();
+        if (current === 0) return;
+        let needed = current;
+        for (const event of events) needed = Math.max(needed, process.listenerCount(event) + extra);
+        if (needed > current) process.setMaxListeners(needed);
+    } catch { /* ignore */ }
 }
 function _installShellJobsExitHook() {
     if (_shellJobsExitHookInstalled) return;
     _shellJobsExitHookInstalled = true;
+    _ensureProcessListenerHeadroom(['exit', 'SIGTERM', 'SIGINT', 'SIGHUP'], 1);
     try { process.on('exit', _sweepLiveJobsSync); } catch { /* ignore */ }
     try { process.on('SIGTERM', _sweepLiveJobsSync); } catch { /* ignore */ }
     try { process.on('SIGINT', _sweepLiveJobsSync); } catch { /* ignore */ }
@@ -538,8 +573,8 @@ function refreshShellJob(jobId) {
     return detail;
 }
 
-export function startBackgroundShellJob({ command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, shellArg, shellType, clientHostPid }) {
-    return _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, shellArg, shellType, clientHostPid });
+export function startBackgroundShellJob({ command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, shellArg, shellArgs, shellType, clientHostPid }) {
+    return _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, shellArg, shellArgs, shellType, clientHostPid });
 }
 
 // In-process completion watcher. After a background shell task is spawned the
@@ -572,6 +607,20 @@ const jobNotifyCtxByJobId = new Map();
 // consuming the outcome, so the watcher must stay cancelled; the last waiter to
 // leave (count===0) owns the decision to re-arm a still-running job.
 const jobWaitWaiterCountByJobId = new Map();
+function markShellJobCancelledByShutdown(jobId, reason = 'shutdown') {
+    const detail = readShellJobDetail(jobId);
+    if (!detail || detail.status !== 'running') return false;
+    detail.status = 'cancelled';
+    detail.exitCode = 137;
+    detail.killed = true;
+    detail.error = `cancelled by runtime shutdown (${reason})`;
+    detail.finishedAt = new Date().toISOString();
+    try { writeFileSync(detail.exitPath || shellJobExitPath(jobId), '137'); } catch { /* ignore */ }
+    try { writeFileSync(detail.donePath || shellJobDonePath(jobId), ''); } catch { /* ignore */ }
+    writeShellJobDetail(detail);
+    _unregisterLiveJobPid(detail.pid);
+    return true;
+}
 // Register a synchronous task waiter. Paired with endShellJobWait in a
 // finally so the count can't leak on throw.
 export function beginShellJobWait(jobId) {
@@ -590,6 +639,26 @@ export function endShellJobWait(jobId) {
 export function clearShellJobNotifyCtx(jobId) {
     jobNotifyCtxByJobId.delete(jobId);
 }
+export function shutdownShellJobs(reason = 'runtime-close', { sync = false } = {}) {
+    const livePids = [..._liveJobPids];
+    const jobIds = new Set([..._liveJobIdsByPid.values()].filter(Boolean));
+    const watcherJobIds = [...backgroundShellJobWatchers.keys()];
+    for (const jobId of watcherJobIds) {
+        jobIds.add(jobId);
+        try { cancelBackgroundShellJobWatch(jobId); } catch { /* ignore */ }
+    }
+    for (const pid of livePids) _killLiveJobPid(pid, { sync });
+    _liveJobPids.clear();
+    _liveJobIdsByPid.clear();
+    let marked = 0;
+    for (const jobId of jobIds) {
+        try { if (markShellJobCancelledByShutdown(jobId, reason)) marked += 1; } catch { /* ignore */ }
+    }
+    backgroundShellJobWatchers.clear();
+    jobNotifyCtxByJobId.clear();
+    jobWaitWaiterCountByJobId.clear();
+    return { killed: livePids.length, cancelledJobs: marked, cancelledWatchers: watcherJobIds.length };
+}
 // Cancel (and unregister) an armed watcher without notifying. Idempotent: a
 // no-op when no watcher is armed, and the per-watcher cancel respects the
 // `settled` guard so it cannot race a real completion notify. The persistent
@@ -824,12 +893,12 @@ export function adoptForegroundShellJob({ command, cwd, pid, timeoutMs, mergeStd
     writeShellJobDetail(detail);
     if (Number.isFinite(pid) && pid > 0) {
         _installShellJobsExitHook();
-        _registerLiveJobPid(pid);
+        _registerLiveJobPid(pid, jobId);
     }
     return { ...detail, exitPath, donePath };
 }
 
-function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, shellArg, shellType, clientHostPid }) {
+function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, shellArg, shellArgs, shellType, clientHostPid }) {
     // Route ANY PowerShell shell to the PS wrapper, regardless of platform.
     // Gating on win32 sent shell:'powershell' on macOS/Linux down the POSIX
     // path below, which spawns `pwsh <wrapper>.sh` — pwsh then tries to run a
@@ -871,7 +940,8 @@ function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr
     // it trivial to distinguish a timeout (124) from a user-side
     // SIGTERM exit (143).
     const innerShellQ = shellQuoteSingle(shell);
-    const innerArgQ = shellQuoteSingle(shellArg);
+    const innerArgs = Array.isArray(shellArgs) && shellArgs.length > 0 ? shellArgs : [shellArg];
+    const innerArgsQ = innerArgs.filter((arg) => arg != null && String(arg).length > 0).map(shellQuoteSingle).join(' ');
     // Runtime enforcement proof: the wrapper touches <jobId>.enforced right
     // before exec'ing `timeout`, so the marker exists iff the timeout branch
     // actually ran under the wrapper's own env/cwd. A spawn-time probe can't
@@ -885,7 +955,7 @@ function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr
     // status for processes that actually exited 0. `rm -- "$0"` removes
     // the staged wrapper .cmd.sh after donePath is published so a host
     // crash before this point still leaves the file for the sweep to GC.
-    const wrapped = `{ if command -v timeout >/dev/null 2>&1; then _to=timeout; elif command -v gtimeout >/dev/null 2>&1; then _to=gtimeout; else _to=; fi; if [ -n "$_to" ]; then touch ${shellQuoteSingle(enforcedPath)}; "$_to" ${timeoutSeconds} ${innerShellQ} ${innerArgQ} ${userCmdQuoted}; else ${innerShellQ} ${innerArgQ} ${userCmdQuoted}; fi; rc=$?; printf '%s' "$rc" > ${shellQuoteSingle(exitPath)}; touch ${shellQuoteSingle(donePath)}; rm -- "$0" 2>/dev/null; exit $rc; }`;
+    const wrapped = `{ if command -v timeout >/dev/null 2>&1; then _to=timeout; elif command -v gtimeout >/dev/null 2>&1; then _to=gtimeout; else _to=; fi; if [ -n "$_to" ]; then touch ${shellQuoteSingle(enforcedPath)}; "$_to" ${timeoutSeconds} ${innerShellQ} ${innerArgsQ} ${userCmdQuoted}; else ${innerShellQ} ${innerArgsQ} ${userCmdQuoted}; fi; rc=$?; printf '%s' "$rc" > ${shellQuoteSingle(exitPath)}; touch ${shellQuoteSingle(donePath)}; rm -- "$0" 2>/dev/null; exit $rc; }`;
     // Stage the wrapped command to a .sh and let the script open its own
     // output files via `exec > … 2> …`. The parent does NOT pass file
     // descriptors via stdio inheritance (`stdio: 'ignore'` for all three).
@@ -919,7 +989,7 @@ function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr
         label: 'shell-job',
     });
     _installShellJobsExitHook();
-    _registerLiveJobPid(child.pid);
+    _registerLiveJobPid(child.pid, jobId);
     const detail = {
         jobId,
         kind: 'bash',
@@ -1056,7 +1126,7 @@ function startBackgroundPowerShellJob({ command, timeoutMs, workDir, mergeStderr
         return { jobId, kind: 'bash', status: 'failed', error: 'PowerShell background task spawn returned no pid' };
     }
     _installShellJobsExitHook();
-    _registerLiveJobPid(childPid);
+    _registerLiveJobPid(childPid, jobId);
     const detail = {
         jobId,
         kind: 'bash',

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

@@ -19,6 +19,7 @@ import {
 } from './builtin/bash-tool.mjs';
 import {
     executeFindFilesTool,
+    executeFuzzyFindTool,
     executeListTool,
     executeTreeTool,
 } from './builtin/list-tool.mjs';
@@ -129,7 +130,7 @@ export {
 } from './builtin/cache-layers.mjs';
 export { atomicWrite } from './builtin/atomic-write.mjs';
 // ---------------------------------------------------------------------------
-// User-cwd persistence bridge: hook writes user-cwd.txt on SessionStart so
+// User-cwd persistence hook: writes user-cwd.txt on SessionStart so
 // the MCP server (spawned from cache dir) resolves the correct sandbox root.
 // Helper extracted to src/shared/user-cwd.mjs so server-main.mjs can import
 // the same primitive without circular-import risk.
@@ -252,9 +253,54 @@ const BUILTIN_TOOL_ALIASES = new Map([
     ['golb', 'glob'],
 ]);
 
+// Case-insensitive lookup of canonical builtin names, built once from the
+// declarative BUILTIN_TOOLS registry. Models trained on other coding-agent
+// CLIs frequently emit PascalCase tool names ("Read", "Shell", "Grep",
+// "List") for tools mixdog exposes in lowercase. Those calls used to fall
+// through to formatUnknownBuiltinToolMessage and, because the error did not
+// resolve the case mismatch, the model re-issued the SAME capitalised call
+// every iteration until the loop cap. A lowercase→canonical map makes the
+// dispatcher accept the case variant directly.
+const _BUILTIN_LOWER_TO_CANONICAL = new Map(
+    BUILTIN_TOOLS.map((t) => [String(t.name || '').toLowerCase(), t.name]).filter(([k]) => k),
+);
+
+// Well-known tool names from OTHER agent CLIs that have no mixdog builtin.
+// They cannot be silently remapped (their argument shapes differ — e.g.
+// Write{path,contents} vs apply_patch{patch}) so the unknown-tool error
+// surfaces a concrete redirect instead of a bare "unknown tool", which is
+// what kept models looping on a non-existent tool.
+const EXTERNAL_TOOL_REDIRECTS = new Map([
+    ['write', 'use `apply_patch` with an `*** Add File:` V4A section to create a file'],
+    ['edit', 'use `apply_patch` with a `*** Update File:` V4A section'],
+    ['multiedit', 'use a single `apply_patch` call with multiple `*** Update File:` sections'],
+    ['strreplace', 'use `apply_patch` with a `*** Update File:` V4A section'],
+    ['str_replace', 'use `apply_patch` with a `*** Update File:` V4A section'],
+    ['str_replace_editor', 'use `apply_patch` with a `*** Update File:` V4A section'],
+    ['createfile', 'use `apply_patch` with an `*** Add File:` V4A section'],
+    ['create_file', 'use `apply_patch` with an `*** Add File:` V4A section'],
+    ['deletefile', 'use `apply_patch` with a `*** Delete File:` V4A section'],
+    ['delete_file', 'use `apply_patch` with a `*** Delete File:` V4A section'],
+    ['bash', 'use the `shell` tool'],
+    ['run', 'use the `shell` tool'],
+    ['runcommand', 'use the `shell` tool'],
+    ['terminal', 'use the `shell` tool'],
+    ['view', 'use the `read` tool'],
+    ['cat', 'use the `read` tool'],
+    ['ls', 'use the `list` tool'],
+    ['searchfiles', 'use the `grep` tool'],
+    ['codebase_search', 'use the `grep` or `code_graph` tool'],
+]);
+
 export function canonicalizeBuiltinToolName(name) {
     if (typeof name !== 'string') return name;
-    return BUILTIN_TOOL_ALIASES.get(name) || name;
+    const aliased = BUILTIN_TOOL_ALIASES.get(name);
+    if (aliased) return aliased;
+    // Exact match wins (cheapest, most common path).
+    if (_BUILTIN_LOWER_TO_CANONICAL.get(name) === name) return name;
+    // Case-insensitive fall-through: "Read"/"SHELL"/"Grep" → canonical.
+    const lowerCanonical = _BUILTIN_LOWER_TO_CANONICAL.get(name.toLowerCase());
+    return lowerCanonical || name;
 }
 
 function editDistance(a, b) {
@@ -294,6 +340,12 @@ export function suggestBuiltinToolName(name) {
 }
 
 export function formatUnknownBuiltinToolMessage(name, _args = {}, noun = 'builtin tool') {
+    // Concrete redirect for a well-known tool from another agent CLI whose
+    // argument shape differs from any mixdog builtin (so it cannot be
+    // case-normalised into one). Without this, the model re-issues the same
+    // non-existent tool every iteration until the loop cap.
+    const redirect = typeof name === 'string' ? EXTERNAL_TOOL_REDIRECTS.get(name.toLowerCase()) : null;
+    if (redirect) return `Error: unknown ${noun} "${name}" — ${redirect}.`;
     const suggestion = suggestBuiltinToolName(name);
     if (!suggestion) return `Error: unknown ${noun} "${name}"`;
     return `Error: unknown ${noun} "${name}". Did you mean "${suggestion}"?`;
@@ -308,7 +360,7 @@ process.on('exit', flushReadRangeIndexesSync);
 
 configureReadRangeIndexTelemetry({ trace: _ioTrace, hashText: _hashText });
 
-// Uniform tool-output cap (Codex `tool_output_token_limit` analogue): a SINGLE
+// Uniform tool-output cap (`tool_output_token_limit` analogue): a SINGLE
 // optional knob that bounds EVERY builtin string result before it enters the
 // lead context, on top of each tool's own caps. Default 0 = OFF (per-tool caps
 // only, no behaviour change). Set MIXDOG_TOOL_OUTPUT_MAX_BYTES (or pass
@@ -342,7 +394,7 @@ function capToolOutput(result, options = {}) {
     const bytes = Buffer.byteLength(result, 'utf8');
     if (bytes <= cap) return result;
     // Middle-truncate: keep head + tail (byte-accurate), drop the middle. Mirrors
-    // Codex middle truncation so the model still sees both ends of a runaway.
+    // Middle truncation so the model still sees both ends of a runaway.
     const half = Math.max(1, Math.floor(cap / 2) - 64);
     const head = _sliceToBytesFromStart(result, half);
     const tail = _sliceToBytesFromEnd(result, half);
@@ -371,7 +423,7 @@ export async function executeBuiltinTool(name, args, cwd, options = {}) {
     const readStateScope = options?.readStateScope ?? options?.sessionId ?? null;
     const executeChildBuiltinTool = (childName, childArgs, childCwd = workDir, childOptions = null) =>
         executeBuiltinTool(childName, childArgs, childCwd, childOptions ? { ...options, ...childOptions } : options);
-    // Path policy: Claude Code's settings.json permissions (mcp__* allow) are the
+    // Path policy: host settings.json permissions (mcp__* allow) are the
     // sole arbiter for workspace-boundary decisions.
     const _toolResult = await (async () => {
     switch (toolName) {
@@ -389,6 +441,8 @@ export async function executeBuiltinTool(name, args, cwd, options = {}) {
             return executeGrepTool(args, workDir, executeChildBuiltinTool, readStateScope, options);
         case 'glob':
             return executeGlobTool(args, workDir, options);
+        case 'find':
+            return executeFuzzyFindTool(args, workDir, options);
         case 'list':
             return executeListTool(args, workDir, options);
         case 'tree':

package/src/runtime/agent/orchestrator/tools/code-graph-state.mjs

@@ -0,0 +1,86 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve as pathResolve } from 'node:path';
+
+export const codeGraphCache = new Map();
+export const codeGraphDirtyPaths = new Map();
+
+const codeGraphDirtyGen = new Map();
+let drainCodeGraphCacheFn = null;
+
+export function canonicalGraphCwd(cwd) {
+  if (!cwd) throw new Error('code_graph requires cwd - caller did not provide a working directory');
+  const full = pathResolve(cwd);
+  return process.platform === 'win32' ? full.toLowerCase() : full;
+}
+
+export function canonicalGraphPath(p) {
+  const full = pathResolve(String(p || ''));
+  return process.platform === 'win32' ? full.toLowerCase() : full;
+}
+
+export function getCodeGraphGen(graphCwd) {
+  return codeGraphDirtyGen.get(graphCwd) || 0;
+}
+
+export function bumpCodeGraphGen(graphCwd) {
+  codeGraphDirtyGen.set(graphCwd, (codeGraphDirtyGen.get(graphCwd) || 0) + 1);
+}
+
+export function consumeCodeGraphDirtyPaths(cwd) {
+  const key = canonicalGraphCwd(cwd);
+  const set = codeGraphDirtyPaths.get(key);
+  if (!set || set.size === 0) return [];
+  codeGraphDirtyPaths.delete(key);
+  return [...set];
+}
+
+// Accept absolute written paths only; resolve affected indexed roots centrally.
+export function markCodeGraphDirtyPaths(paths) {
+  const values = Array.isArray(paths) ? paths : [paths];
+  const cleaned = values
+    .filter(Boolean)
+    .map((p) => canonicalGraphPath(p));
+  if (cleaned.length === 0) return;
+
+  const knownRoots = new Set([...codeGraphDirtyPaths.keys(), ...codeGraphCache.keys()]);
+  const affectedRoots = new Set();
+  for (const absPath of cleaned) {
+    let matchedThisPath = false;
+    for (const root of knownRoots) {
+      const canonRoot = canonicalGraphPath(root);
+      if (absPath.startsWith(canonRoot + '/') || absPath.startsWith(canonRoot + '\\') || absPath === canonRoot) {
+        affectedRoots.add(root);
+        matchedThisPath = true;
+      }
+    }
+    if (!matchedThisPath) {
+      let dir = dirname(absPath);
+      while (dir && dir !== dirname(dir)) {
+        if (existsSync(join(dir, 'package.json')) || existsSync(join(dir, '.git'))) {
+          affectedRoots.add(canonicalGraphCwd(dir));
+          break;
+        }
+        dir = dirname(dir);
+      }
+    }
+  }
+
+  for (const root of affectedRoots) {
+    if (!codeGraphDirtyPaths.has(root)) codeGraphDirtyPaths.set(root, new Set());
+    const set = codeGraphDirtyPaths.get(root);
+    for (const p of cleaned) set.add(p);
+
+    const canonRoot = canonicalGraphCwd(root);
+    codeGraphCache.delete(canonRoot);
+    bumpCodeGraphGen(canonRoot);
+  }
+}
+
+export function registerCodeGraphDrain(fn) {
+  drainCodeGraphCacheFn = typeof fn === 'function' ? fn : null;
+}
+
+export function drainCodeGraphCache() {
+  if (!drainCodeGraphCacheFn) return;
+  drainCodeGraphCacheFn();
+}

package/src/runtime/agent/orchestrator/tools/code-graph-tool-defs.mjs

@@ -3,20 +3,20 @@ export const CODE_GRAPH_TOOL_DEFS = [
     name: 'code_graph',
     title: 'Code Graph',
     annotations: { title: 'Code Graph', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false, compressibleLossless: true },
-    description: 'Inspect code structure. Top-level entry for code-related questions: symbols, definitions, references, callers, callees, imports, and related files. Use before read when structure can narrow the target; use grep for exact text.',
+    description: 'Code structure: symbols, refs, calls, imports, impact.',
     inputSchema: {
       type: 'object',
       properties: {
-        mode: { type: 'string', enum: ['overview', 'imports', 'dependents', 'related', 'impact', 'symbols', 'find_symbol', 'search', 'references', 'callers', 'callees', 'prewarm'], description: 'Operation: repo/file overview, import graph, symbol lookup/search, references, callers/callees, or cache prewarm.' },
-        file: { type: 'string', description: 'Target source file. Directory scope is only for references/callers; omit for repo-wide overview/search.' },
-        symbol: { type: 'string', description: 'Identifier or search keyword for symbol/search/reference/call modes.' },
-        symbols: { type: 'array', items: { type: 'string' }, description: 'Batch identifiers for find_symbol/callers/callees/references/prewarm.' },
-        body: { type: 'boolean', description: 'Return full symbol body for find_symbol. Default true.' },
-        language: { type: 'string', description: 'Optional language hint.' },
-        limit: { type: 'number', minimum: 1, description: 'Max results to return; clamped per mode.' },
-        depth: { type: 'number', minimum: 1, maximum: 5, description: 'callers only: 1 direct, 2-5 transitive.' },
-        page: { type: 'number', minimum: 1, description: 'callers depth>=2 page.' },
-        cwd: { type: 'string', description: 'Project root override; omit when runtime cwd is already the repo root.' },
+        mode: { type: 'string', enum: ['overview', 'imports', 'dependents', 'related', 'impact', 'symbols', 'find_symbol', 'search', 'references', 'callers', 'callees', 'prewarm'], description: 'Operation.' },
+        file: { type: 'string', description: 'Source file.' },
+        symbol: { type: 'string', description: 'Identifier or symbol keyword.' },
+        symbols: { type: 'array', items: { type: 'string' }, description: 'Batch identifiers.' },
+        body: { type: 'boolean', description: 'Include body.' },
+        language: { type: 'string', description: 'Language hint.' },
+        limit: { type: 'number', minimum: 1, description: 'Max results.' },
+        depth: { type: 'number', minimum: 1, maximum: 5, description: 'Caller depth.' },
+        page: { type: 'number', minimum: 1, description: 'Caller page.' },
+        cwd: { type: 'string', description: 'Project root.' },
       },
       required: ['mode'],
     },