mixdog 0.9.1 → 0.9.3

package/src/runtime/agent/orchestrator/tools/builtin/external-tool-adapters.test.mjs

@@ -0,0 +1,162 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { tryExecuteExternalToolAdapter, isExternalAdapterTool } from './external-tool-adapters.mjs';
+
+function makeDir() {
+    return mkdtempSync(join(tmpdir(), 'ext-adapter-test-'));
+}
+
+test('isExternalAdapterTool recognizes adapted names only', () => {
+    assert.equal(isExternalAdapterTool('StrReplace'), true);
+    assert.equal(isExternalAdapterTool('str_replace'), true);
+    assert.equal(isExternalAdapterTool('str_replace_editor'), true);
+    assert.equal(isExternalAdapterTool('search_replace'), true);
+    assert.equal(isExternalAdapterTool('Write'), true);
+    assert.equal(isExternalAdapterTool('create_file'), true);
+    assert.equal(isExternalAdapterTool('Bash'), true);
+    assert.equal(isExternalAdapterTool('run_terminal_cmd'), true);
+    // Destructive / different-shape names stay on the redirect path.
+    assert.equal(isExternalAdapterTool('Delete'), false);
+    assert.equal(isExternalAdapterTool('delete_file'), false);
+    assert.equal(isExternalAdapterTool('edit'), false);
+    assert.equal(isExternalAdapterTool('multiedit'), false);
+    assert.equal(isExternalAdapterTool(''), false);
+    assert.equal(isExternalAdapterTool(null), false);
+});
+
+test('StrReplace: unique match replaces content', async () => {
+    const dir = makeDir();
+    const file = join(dir, 'a.txt');
+    writeFileSync(file, 'alpha\nbeta\ngamma\n');
+    const out = await tryExecuteExternalToolAdapter('StrReplace', {
+        path: file, old_string: 'beta', new_string: 'BETA',
+    }, dir, {});
+    assert.match(out, /^Updated .*\(1 replacement\)$/);
+    assert.equal(readFileSync(file, 'utf8'), 'alpha\nBETA\ngamma\n');
+});
+
+test('StrReplace: zero matches errors without writing', async () => {
+    const dir = makeDir();
+    const file = join(dir, 'a.txt');
+    writeFileSync(file, 'alpha\n');
+    const out = await tryExecuteExternalToolAdapter('str_replace', {
+        path: file, old_string: 'missing', new_string: 'x',
+    }, dir, {});
+    assert.match(out, /old_string not found/);
+    assert.equal(readFileSync(file, 'utf8'), 'alpha\n');
+});
+
+test('StrReplace: ambiguous matches error with count', async () => {
+    const dir = makeDir();
+    const file = join(dir, 'a.txt');
+    writeFileSync(file, 'dup\ndup\n');
+    const out = await tryExecuteExternalToolAdapter('search_replace', {
+        path: file, old_string: 'dup', new_string: 'x',
+    }, dir, {});
+    assert.match(out, /ambiguous: 2 matches/);
+    assert.equal(readFileSync(file, 'utf8'), 'dup\ndup\n');
+});
+
+test('StrReplace: missing old_string falls back (null)', async () => {
+    const dir = makeDir();
+    const out = await tryExecuteExternalToolAdapter('StrReplace', {
+        path: join(dir, 'a.txt'), new_string: 'x',
+    }, dir, {});
+    assert.equal(out, null);
+});
+
+test('StrReplace: unreadable target is a concrete error', async () => {
+    const dir = makeDir();
+    const out = await tryExecuteExternalToolAdapter('StrReplace', {
+        path: join(dir, 'nope.txt'), old_string: 'a', new_string: 'b',
+    }, dir, {});
+    assert.match(out, /^Error: cannot read /);
+});
+
+test('Write: creates a new file with contents', async () => {
+    const dir = makeDir();
+    const file = join(dir, 'new', 'nested.txt');
+    const out = await tryExecuteExternalToolAdapter('Write', {
+        path: file, contents: 'created body',
+    }, dir, {});
+    assert.match(out, /^Created .*nested\.txt \(12 bytes\)$/);
+    assert.equal(readFileSync(file, 'utf8'), 'created body');
+});
+
+test('Write: overwrites an existing file and says Updated', async () => {
+    const dir = makeDir();
+    const file = join(dir, 'exists.txt');
+    writeFileSync(file, 'old');
+    const out = await tryExecuteExternalToolAdapter('write', {
+        file_path: file, content: 'new body',
+    }, dir, {});
+    assert.match(out, /^Updated /);
+    assert.equal(readFileSync(file, 'utf8'), 'new body');
+});
+
+test('Write: missing contents falls back to redirect (null)', async () => {
+    const dir = makeDir();
+    const out = await tryExecuteExternalToolAdapter('Write', {
+        path: join(dir, 'x.txt'),
+    }, dir, {});
+    assert.equal(out, null);
+    assert.equal(existsSync(join(dir, 'x.txt')), false);
+});
+
+test('StrReplace: missing old_string/new_string falls back (null)', async () => {
+    const dir = makeDir();
+    const file = join(dir, 'a.txt');
+    writeFileSync(file, 'body');
+    const out = await tryExecuteExternalToolAdapter('StrReplace', {
+        path: file, old_string: 'body',
+    }, dir, {});
+    assert.equal(out, null);
+});
+
+test('StrReplace: empty old_string is a concrete error (no hang)', async () => {
+    const dir = makeDir();
+    const file = join(dir, 'a.txt');
+    writeFileSync(file, 'body');
+    const out = await tryExecuteExternalToolAdapter('StrReplace', {
+        path: file, old_string: '', new_string: 'x',
+    }, dir, {});
+    assert.match(out, /old_string must be a non-empty string/);
+    assert.equal(readFileSync(file, 'utf8'), 'body');
+});
+
+test('bash family: missing command falls back (null)', async () => {
+    const dir = makeDir();
+    const out = await tryExecuteExternalToolAdapter('Bash', {}, dir, {});
+    assert.equal(out, null);
+});
+
+test('Write: target outside workDir is refused (base containment)', async () => {
+    const workDir = makeDir();
+    const outsideDir = makeDir();
+    const outside = join(outsideDir, 'escape.txt');
+    const out = await tryExecuteExternalToolAdapter('Write', {
+        path: outside, contents: 'should not land',
+    }, workDir, {});
+    assert.match(out, /cannot write outside the working directory/);
+    assert.equal(existsSync(outside), false);
+});
+
+test('non-adapted names return null without touching fs', async () => {
+    const dir = makeDir();
+    const out = await tryExecuteExternalToolAdapter('Delete', {
+        path: join(dir, 'x.txt'),
+    }, dir, {});
+    assert.equal(out, null);
+});
+
+test('bash family: executes a command via the shell runner', async () => {
+    const dir = makeDir();
+    const out = await tryExecuteExternalToolAdapter('run_terminal_cmd', {
+        command: 'node -e "console.log(\'adapter-ok\')"',
+    }, dir, {});
+    assert.equal(typeof out, 'string');
+    assert.match(out, /adapter-ok/);
+});

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-formatting.mjs

@@ -5,3 +5,13 @@ export function formatMtime(mtimeMs) {
     if (!mtimeMs) return '-';
     return new Date(mtimeMs).toISOString().slice(0, 19).replace('T', ' ');
 }
+
+// Human-readable size column for list/find. Directories have no meaningful
+// byte size (render '-'); files show KB so the model can spot a large file
+// before reading it. Sub-1KB files round up to 1KB.
+export function formatListSize(type, bytes) {
+    if (type !== 'file') return '-';
+    const n = Number(bytes) || 0;
+    if (n >= 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)}MB`;
+    return `${Math.max(1, Math.round(n / 1024))}KB`;
+}

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

@@ -26,7 +26,8 @@ import {
     NOISE_DIR_NAMES,
     walkDir,
 } from './glob-walk.mjs';
-import { formatMtime } from './list-formatting.mjs';
+import { formatMtime, formatListSize } from './list-formatting.mjs';
+import { TOOL_OUTPUT_MAX_BYTES } from './tool-output-limit.mjs';
 import { runRg } from './rg-runner.mjs';
 import { fuzzyRank } from './fuzzy-match.mjs';
 import { assertPathReachable } from './fs-reachability.mjs';
@@ -169,7 +170,7 @@ export async function executeListTool(args, workDir, options = {}) {
         }
     }
     const lines = sliced.map(r =>
-        `${normalizeOutputPath(r.path)}\t${r.type}\t${r.size}\t${formatMtime(r.mtimeMs)}`);
+        `${normalizeOutputPath(r.path)}\t${r.type}\t${formatListSize(r.type, r.size)}\t${formatMtime(r.mtimeMs)}`);
     if (windowed.length > sliced.length) lines.push(`... [entries ${offset + 1}-${offset + sliced.length} of ${rows.length}; pass offset:${offset + sliced.length} to continue]`);
     if (truncatedByCap) lines.push(`... walk truncated at ${LIST_ABSOLUTE_CAP} rows or ${LIST_WALK_TIMEOUT_MS}ms timeout; narrow the path or lower depth for a complete listing`);
     let emptyMsg = '(empty directory)';
@@ -282,7 +283,7 @@ export async function executeTreeTool(args, workDir, options = {}) {
         const totalLabel = body.length >= gatherCap ? `${body.length}+` : `${body.length}`;
         outLines.push(`... [entries ${offset + 1}-${offset + sliced.length} of ${totalLabel}; pass offset:${offset + sliced.length} to continue]`);
     }
-    const TREE_OUTPUT_CHAR_CAP = 50_000;
+    const TREE_OUTPUT_CHAR_CAP = TOOL_OUTPUT_MAX_BYTES;
     let out = outLines.join('\n');
     let outputCharTruncated = false;
     if (out.length > TREE_OUTPUT_CHAR_CAP) {
@@ -603,7 +604,7 @@ export async function executeFindFilesTool(args, workDir, options = {}) {
     const windowed = offset > 0 ? matches.slice(offset) : matches;
     const sliced = headLimit > 0 ? windowed.slice(0, headLimit) : windowed;
     const lines = sliced.map(m =>
-        `${normalizeOutputPath(m.path)}\t${m.size}\t${formatMtime(m.mtimeMs)}`);
+        `${normalizeOutputPath(m.path)}\t${formatListSize('file', m.size)}\t${formatMtime(m.mtimeMs)}`);
     if (windowed.length > sliced.length) lines.push(`... [entries ${offset + 1}-${offset + sliced.length} of ${matches.length}; pass offset:${offset + sliced.length} to continue]`);
     if (rgStdoutTruncated) lines.push('... [warning] rg stdout truncated at 20MB cap; results incomplete');
     if (rgStdoutPartial) lines.push('... [warning] rg exit 2 (partial results); listing may be incomplete');

package/src/runtime/agent/orchestrator/tools/builtin/path-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/path-utils.mjs

@@ -220,5 +220,20 @@ export function coerceShapeFlex(value) {
             if (typeof parsed === 'string') return parsed;
         } catch {}
     }
+    // A single {path,offset,limit}-shaped object JSON string (e.g. a model
+    // emitting `path: "{\"path\":\"x\",\"offset\":10}"` instead of a real
+    // object) is a lossless single-entry batch. Wrap it in an array so the
+    // downstream object-array batch path (read-tool.mjs) picks it up instead
+    // of falling through to the plain-string path guard, which would
+    // misdetect the raw JSON text as a literal (and often invalid) filename.
+    if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+                && typeof (parsed.path ?? parsed.file_path) === 'string') {
+                return [parsed];
+            }
+        } catch {}
+    }
     return value;
 }

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

@@ -1,21 +1,11 @@
 import { existsSync } from 'fs';
 import { normalizeInputPath, resolveAgainstCwd } from './path-utils.mjs';
-import { parseLineLimitArg } from './read-formatting.mjs';
-
-const READ_LINE_CONTEXT_DEFAULT = 20;
-const READ_LINE_CONTEXT_MAX = 200;
 
 export function parseReadLineNumberArg(value) {
     const n = Number(value);
     return Number.isFinite(n) && n > 0 ? Math.trunc(n) : null;
 }
 
-export function parseReadLineContextArg(value) {
-    const n = Number(value);
-    if (!Number.isFinite(n)) return READ_LINE_CONTEXT_DEFAULT;
-    return Math.min(READ_LINE_CONTEXT_MAX, Math.max(0, Math.trunc(n)));
-}
-
 export function parseReadPathLineSpec(rawPath) {
     if (typeof rawPath !== 'string' || rawPath.length === 0) return null;
     const text = rawPath.trim();
@@ -51,7 +41,6 @@ export function normalizePathAndStripLineCoordinate(rawPath, workDir) {
 
 export function normaliseReadLineWindowArgs(inputArgs, workDir) {
     const args = { ...inputArgs };
-    let lineNo = parseReadLineNumberArg(args.line);
     let pathLineRange = null;
     if (typeof args.path === 'string' && args.path) {
         const spec = resolveExistingPathLineCoordinate(args.path, workDir);
@@ -61,45 +50,21 @@ export function normaliseReadLineWindowArgs(inputArgs, workDir) {
                 return args;
             }
             args.path = spec.path;
-            if (!lineNo) lineNo = spec.lineNo;
             if (spec.endLine) pathLineRange = { startLine: spec.lineNo, endLine: spec.endLine };
+            else pathLineRange = { startLine: spec.lineNo, endLine: spec.lineNo };
         }
     }
     const isFullMode = !args.mode || args.mode === 'full';
-    // line= and offset= are ALTERNATIVE window anchors. Silently preferring
-    // offset used to discard line/context and (with a bare low offset) fall
-    // through to a whole-file smart-truncate dump — the exact read explosion
-    // a 7-line `line+context` request was trying to avoid. Make it a hard
-    // conflict instead.
-    if (isFullMode && lineNo && args.offset !== undefined && args.offset !== null) {
-        args._invertedRangeError = `Error: conflicting window args — both line (${lineNo}) and offset (${args.offset}) were given; line/context and offset/limit are alternative window forms, pass only one`;
-        return args;
-    }
-    if (isFullMode && lineNo) {
-        if (pathLineRange && args.context === undefined && (args.limit === undefined || args.limit === null)) {
-            args.offset = Math.max(0, pathLineRange.startLine - 1);
+    // Public Read args are offset/limit only. Keep a narrow private
+    // compatibility path for file#Lx/file:line strings by converting them into
+    // offset/limit; do not interpret line/context fields here.
+    if (isFullMode && pathLineRange && args.offset === undefined) {
+        args.offset = Math.max(0, pathLineRange.startLine - 1);
+        if (args.limit === undefined) {
             args.limit = Math.max(1, pathLineRange.endLine - pathLineRange.startLine + 1);
-        } else {
-            const contextExplicit = args.context !== undefined && args.context !== null;
-            const limitExplicit = args.limit !== undefined && args.limit !== null;
-            const context = parseReadLineContextArg(args.context);
-            if (limitExplicit && !contextExplicit) {
-                // Explicit limit, no explicit context: anchor the window AT the
-                // requested line so it is always included. (Was: offset centered
-                // by the default context, which a small limit then truncated to
-                // exclude the very line the caller asked for.)
-                args.offset = Math.max(0, lineNo - 1);
-                args.limit = parseLineLimitArg(args.limit, (context * 2) + 1);
-            } else {
-                const limit = limitExplicit
-                    ? parseLineLimitArg(args.limit, (context * 2) + 1)
-                    : (context * 2) + 1;
-                args.offset = Math.max(0, lineNo - context - 1);
-                args.limit = limit;
-            }
         }
-        delete args.line;
-        delete args.context;
     }
+    delete args.line;
+    delete args.context;
     return args;
 }

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

@@ -1,4 +1,5 @@
 import { SMART_READ_MAX_BYTES } from './read-formatting.mjs';
+import { TOOL_OUTPUT_MAX_BYTES } from './tool-output-limit.mjs';
 
 // Read tool caps.
 //
@@ -28,7 +29,7 @@ import { SMART_READ_MAX_BYTES } from './read-formatting.mjs';
 // cleanly without a tokenizer.
 export const READ_MAX_SIZE_BYTES = 10 * 1024 * 1024;
 export const READ_WHOLE_FILE_MAX_BYTES = 256 * 1024;
-export const READ_MAX_OUTPUT_BYTES = 30_000;
+export const READ_MAX_OUTPUT_BYTES = TOOL_OUTPUT_MAX_BYTES;
 export const READ_STREAM_RANGE_MIN_BYTES = 128 * 1024;
 export const READ_SMART_STREAM_MIN_BYTES = SMART_READ_MAX_BYTES;
 export const READ_BATCH_RANGE_COALESCE_GAP_LINES = 256;

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

@@ -1,9 +1,18 @@
 import { mergeReadRanges } from './read-ranges.mjs';
+import { TOOL_OUTPUT_MAX_BYTES } from './tool-output-limit.mjs';
 
-export const SMART_READ_MAX_BYTES = 30 * 1024;
-export const SMART_READ_MAX_LINES = 600;
-export const SMART_READ_HEAD_LINES = 200;
-export const SMART_READ_TAIL_LINES = 100;
+// Smart-truncate cap: a no-window read returns the file until this cap, past
+// which head+tail are shown and the model pages the rest with offset (footer
+// says how). Byte budget is the shared TOOL_OUTPUT_MAX_BYTES; line/head/tail
+// stay read-specific. Env-overridable for bench: MIXDOG_READ_MAX_LINES/_HEAD/_TAIL.
+function _readEnvInt(name, fallback) {
+    const v = parseInt(process.env[name], 10);
+    return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+export const SMART_READ_MAX_BYTES = TOOL_OUTPUT_MAX_BYTES;
+export const SMART_READ_MAX_LINES = _readEnvInt('MIXDOG_READ_MAX_LINES', 2000);
+export const SMART_READ_HEAD_LINES = _readEnvInt('MIXDOG_READ_HEAD_LINES', 1200);
+export const SMART_READ_TAIL_LINES = _readEnvInt('MIXDOG_READ_TAIL_LINES', 400);
 // Only the genuinely large full reads warrant the anti-re-read advisory; below
 // this the smart-truncate path (30 KB) already caps normal reads, so a 16 KB
 // floor mostly fired on full:true mid-size reads where the advisory was pure
@@ -11,7 +20,7 @@ export const SMART_READ_TAIL_LINES = 100;
 // 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/read-tool.mjs

@@ -49,8 +49,7 @@ function _guardedReadError(p, helpers) {
 }
 
 // Reachability preflight for EVERY read shape (scalar / array / reads[]). MUST
-// run before any sync FS — including line-coordinate disambiguation (existsSync
-// in readPathStringGuardError / normaliseReadLineWindowArgs) and the image
+// run before any sync FS — including path normalization and the image
 // stat/read. A dead mount would otherwise freeze the event loop, defeating even
 // the 630s dispatch ceiling.
 async function _readReachPreflight(rawPath, workDir, helpers) {
@@ -58,10 +57,9 @@ async function _readReachPreflight(rawPath, workDir, helpers) {
         normalizeInputPath, resolveAgainstCwd,
     } = helpers;
     // A guarded path (UNC/SMB, Windows device, ADS, /dev/* block) must be
-    // REJECTED here, not skipped: skipping would let the later sync existsSync
-    // line-coordinate disambiguation (normaliseReadLineWindowArgs /
-    // readPathStringGuardError) touch it and trigger NTLM/raw-device access or
-    // hang. Reject up front with the same message the inline guards emit.
+    // REJECTED here, not skipped: skipping would let the later sync guard/open
+    // path touch it and trigger NTLM/raw-device access or hang. Reject up front
+    // with the same message the inline guards emit.
     // normalizeInputPath FIRST (FS-pure) so we stat the same path the real read
     // opens (e.g. /mnt/z/... -> Z:\...). Reachability is per-mount/dir, so the
     // line-coordinate strip only needs to land in the right directory — exact
@@ -113,7 +111,7 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
     }
     args.path = coerceShapeFlex(args.path);
     // Reachability preflight up front (all shapes) — before readPathStringGuardError /
-    // normaliseReadLineWindowArgs / image stat, all of which can touch sync FS.
+    // image stat, all of which can touch sync FS.
     {
         const _reErr = await _readReachPreflight(args.path, workDir, helpers);
         if (_reErr) return _reErr;
@@ -186,8 +184,6 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
                 }
             }
             if (r?.limit !== undefined) entry.limit = r.limit;
-            if (r?.line !== undefined) entry.line = r.line;
-            if (r?.context !== undefined) entry.context = r.context;
             if (r?.full !== undefined) entry.full = r.full;
             entry = normaliseReadLineWindowArgs(entry, workDir);
             return entry;
@@ -235,8 +231,6 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
             if (args.n !== undefined) entry.n = args.n;
             if (args.offset !== undefined) entry.offset = args.offset;
             if (args.limit !== undefined) entry.limit = args.limit;
-            if (args.line !== undefined) entry.line = args.line;
-            if (args.context !== undefined) entry.context = args.context;
             if (args.full !== undefined) entry.full = args.full;
             entry = normaliseReadLineWindowArgs(entry, workDir);
             return entry;
@@ -464,14 +458,13 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
                 if (span.note) args._symbolReadNote = `symbol ${sym}: ${span.note}`;
             }
         }
-        // A window (offset/limit/line or a path:line coordinate) beats a glance
+        // A window (offset/limit or a path:line coordinate) beats a glance
         // mode (head/tail/summary), which would otherwise read from a file end and
-        // silently drop the window. Drop the glance mode BEFORE line-window
-        // normalization so a line / path:line coordinate is actually converted to
-        // offset/limit (normaliseReadLineWindowArgs only converts when no mode is
-        // set). count/hex are not text-window ops and keep their mode.
+        // silently drop the window. Drop the glance mode BEFORE path:line
+        // compatibility normalization so any path coordinate is converted to
+        // offset/limit. count/hex are not text-window ops and keep their mode.
         {
-            const _win = args.offset != null || args.limit != null || args.line != null || hasLineCoordinate(args.path);
+            const _win = args.offset != null || args.limit != null || hasLineCoordinate(args.path);
             if (_win && (args.mode === 'head' || args.mode === 'tail' || args.mode === 'summary')) {
                 args = { ...args, mode: undefined };
             }

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

@@ -1,6 +1,7 @@
 import { statSync } from 'fs';
 import { isAbsolute, resolve } from 'path';
 import { trueCasePath } from './path-utils.mjs';
+import { findBySuffixStrip } from './path-diagnostics.mjs';
 import {
     canonicalizeGlobSlashes,
     coerceShapeFlex,
@@ -36,6 +37,11 @@ import {
 import { recordReadSnapshot } from './read-snapshot-runtime.mjs';
 import { applyGrepContextLeadPolicy, GREP_CONTEXT_MAX } from './arg-guard.mjs';
 
+// Default surrounding-lines window applied by output_mode:'content_with_context'
+// when the caller does not pass an explicit -A/-B/-C/context. Sized to cover a
+// typical function/block so a match arrives readable without a follow-up read.
+const GREP_AUTO_CONTEXT_LINES = 25;
+
 const MIXDOG_GREP_CASE_HINT_PROBE = /^(1|true|yes|on)$/i.test(String(process.env.MIXDOG_GREP_CASE_HINT_PROBE || ''));
 
 function expandLegacyEscapedAlternationPattern(rawPattern) {
@@ -353,18 +359,23 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
         .map(canonicalizeGlobSlashes)
         .filter((g) => !isRedundantAllFilesGlob(g)));
 
-    const ALLOWED_OUTPUT_MODES = new Set(['files_with_matches', 'content', 'count']);
+    const ALLOWED_OUTPUT_MODES = new Set(['files_with_matches', 'content', 'content_with_context', 'count']);
     const rawOutputMode = typeof args.output_mode === 'string' ? args.output_mode.trim() : '';
     if (rawOutputMode && !ALLOWED_OUTPUT_MODES.has(rawOutputMode)) {
         return `Error: invalid output_mode ${JSON.stringify(args.output_mode)}; expected one of ${[...ALLOWED_OUTPUT_MODES].join(', ')}`;
     }
+    // `content_with_context` is a convenience alias for `content` that auto-applies
+    // a generous surrounding-lines window, so the model can read a match in place
+    // without following up with `read`. It maps to content mode; the default
+    // context is applied below unless the caller passed an explicit -A/-B/-C/context.
+    const wantAutoContext = rawOutputMode === 'content_with_context';
     // Default to `content` when output_mode is omitted. A pattern is always
     // present here (the no-pattern case returned above), so this is a content
     // search — it should return the matching lines WITH line numbers, not just
     // filenames. Filename-only was forcing callers to re-grep for the actual
     // coordinates (the explorer over-iteration root cause). `files_with_matches`
     // is now opt-in; pure filename discovery belongs to `glob`.
-    const outputMode = rawOutputMode || 'content';
+    const outputMode = (rawOutputMode === 'content_with_context') ? 'content' : (rawOutputMode || 'content');
     const headLimitRaw = args.head_limit;
     const headLimitCoerced = coerceNonNegInt(headLimitRaw);
     if (Number.isNaN(headLimitCoerced)) {
@@ -391,6 +402,12 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
     let contextN = args['-C'] !== undefined && args['-C'] !== null && args['-C'] !== ''
         ? coerceContext(args['-C'])
         : coerceContext(args.context);
+    // content_with_context: if no explicit context flag was supplied, apply a
+    // generous default so the match arrives with enough surrounding code to
+    // understand it (function-sized) without a separate read.
+    if (wantAutoContext && afterN === null && beforeN === null && contextN === null) {
+        contextN = GREP_AUTO_CONTEXT_LINES;
+    }
     if (contextN !== null && contextN > 0) {
         if (afterN === 0) afterN = null;
         if (beforeN === 0) beforeN = null;
@@ -462,6 +479,10 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
     try { grepStat = statSync(grepResolvedPath); }
     catch (err) {
         const msg = `Error: path does not exist: ${normalizeOutputPath(grepResolvedPath)} (${err?.code || 'ENOENT'})`;
+        const suffixHit = findBySuffixStrip(workDir, grepResolvedPath);
+        if (suffixHit) {
+            return msg + ` Not found at this path; the same filename exists at: "${normalizeOutputPath(suffixHit)}". Search that path directly.`;
+        }
         return msg + await _suggestIndexedPaths(grepResolvedPath, executeChildBuiltinTool, workDir);
     }
     const filenameOmitted = grepStat.isFile();