mixdog 0.9.1 → 0.9.2

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

@@ -0,0 +1,143 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { validateBuiltinArgs } from './arg-guard.mjs';
+
+test('read: numeric-string offset/limit coerce losslessly', () => {
+    const a = { path: 'x.js', offset: '850', limit: '850.0' };
+    assert.equal(validateBuiltinArgs('read', a), null);
+    assert.equal(a.offset, 850);
+    assert.equal(a.limit, 850);
+});
+
+test('read: non-integer numeric string still rejected', () => {
+    const a = { path: 'x.js', offset: '3.5' };
+    assert.match(validateBuiltinArgs('read', a), /must be a finite integer/);
+});
+
+test('read: non-numeric string still rejected', () => {
+    const a = { path: 'x.js', offset: 'soon' };
+    assert.match(validateBuiltinArgs('read', a), /must be a finite integer/);
+});
+
+test('read: top-level line/context convert to offset/limit', () => {
+    const a = { path: 'x.js', line: 100, context: 10 };
+    assert.equal(validateBuiltinArgs('read', a), null);
+    assert.equal(a.offset, 89);
+    assert.equal(a.limit, 21);
+    assert.equal('line' in a, false);
+    assert.equal('context' in a, false);
+});
+
+test('read: line without context defaults to a single-line window', () => {
+    const a = { path: 'x.js', line: 1 };
+    assert.equal(validateBuiltinArgs('read', a), null);
+    assert.equal(a.offset, 0);
+    assert.equal(a.limit, 1);
+});
+
+test('read: explicit offset/limit wins over line/context (dropped)', () => {
+    const a = { path: 'x.js', line: 100, context: 10, offset: 5, limit: 20 };
+    assert.equal(validateBuiltinArgs('read', a), null);
+    assert.equal(a.offset, 5);
+    assert.equal(a.limit, 20);
+    assert.equal('line' in a, false);
+    assert.equal('context' in a, false);
+});
+
+test('read: path[] entry object line/context converts the same way', () => {
+    const a = { path: [{ path: 'x.js', line: 50, context: 5 }] };
+    assert.equal(validateBuiltinArgs('read', a), null);
+    assert.equal(a.path[0].offset, 44);
+    assert.equal(a.path[0].limit, 11);
+});
+
+test('read: path[] entry negative numeric-string offset is rejected after coercion', () => {
+    const a = { path: [{ path: 'x.js', offset: '-5' }] };
+    const err = validateBuiltinArgs('read', a);
+    assert.match(err, /path\[0\]\.offset/);
+    assert.match(err, />= 0/);
+});
+
+test('read: path[] entry negative numeric-string limit is rejected after coercion', () => {
+    const a = { path: [{ path: 'x.js', limit: '-1' }] };
+    const err = validateBuiltinArgs('read', a);
+    assert.match(err, /path\[0\]\.limit/);
+    assert.match(err, />= 0/);
+});
+
+test('read: path[] entry valid numeric-string offset/limit still coerces and passes', () => {
+    const a = { path: [{ path: 'x.js', offset: '10', limit: '5' }] };
+    assert.equal(validateBuiltinArgs('read', a), null);
+    assert.equal(a.path[0].offset, 10);
+    assert.equal(a.path[0].limit, 5);
+});
+
+test('read: JSON object string path is accepted as a single-entry batch', () => {
+    const a = { path: '{"path":"x.js","offset":10,"limit":5}' };
+    assert.equal(validateBuiltinArgs('read', a), null);
+    assert.equal(Array.isArray(a.path), true);
+    assert.equal(a.path[0].path, 'x.js');
+    assert.equal(a.path[0].offset, 10);
+});
+
+test('shell: win32 drive path with no shell set defaults to powershell', (t) => {
+    if (process.platform !== 'win32') { t.skip('win32 only'); return; }
+    const a = { command: 'dir C:\\Project\\mixdog' };
+    assert.equal(validateBuiltinArgs('shell', a), null);
+    assert.equal(a.shell, 'powershell');
+});
+
+test('glob: missing pattern with a path defaults pattern to "*"', () => {
+    const a = { path: 'src' };
+    assert.equal(validateBuiltinArgs('glob', a), null);
+    assert.equal(a.pattern, '*');
+});
+
+test('glob: path carrying glob magic is left for the path-magic fallback, not overridden', () => {
+    const a = { path: 'src/**/*.mjs' };
+    assert.equal(validateBuiltinArgs('glob', a), null);
+    assert.equal('pattern' in a, false);
+    assert.equal(a.path, 'src/**/*.mjs');
+});
+
+test('glob: missing pattern and path is still an error surface (guard passes through)', () => {
+    const a = {};
+    assert.equal(validateBuiltinArgs('glob', a), null);
+    assert.equal('pattern' in a, false);
+});
+
+test('grep: output_mode with newline-concatenated debris truncates to valid enum', () => {
+    const a = { pattern: 'foo', output_mode: 'content_with_context\ntrue' };
+    assert.equal(validateBuiltinArgs('grep', a), null);
+    assert.equal(a.output_mode, 'content_with_context');
+});
+
+test('grep: trailing literal \\n artifact stripped from pattern', () => {
+    const a = { pattern: 'foo bar\\n' };
+    assert.equal(validateBuiltinArgs('grep', a), null);
+    assert.equal(a.pattern, 'foo bar');
+});
+
+test('grep: trailing concatenation artifact ">\\n" stripped from pattern', () => {
+    const a = { pattern: 'foo bar">\n' };
+    assert.equal(validateBuiltinArgs('grep', a), null);
+    assert.equal(a.pattern, 'foo bar');
+});
+
+test('grep: mid-pattern \\n is left untouched', () => {
+    const a = { pattern: 'foo\\nbar' };
+    assert.equal(validateBuiltinArgs('grep', a), null);
+    assert.equal(a.pattern, 'foo\\nbar');
+});
+
+test('grep: bare trailing ">" with no newline artifact survives untouched', () => {
+    const a = { pattern: 'class="active">' };
+    assert.equal(validateBuiltinArgs('grep', a), null);
+    assert.equal(a.pattern, 'class="active">');
+});
+
+test('grep: numeric-string -C context coerces losslessly', () => {
+    const a = { pattern: 'foo', '-C': '5' };
+    assert.equal(validateBuiltinArgs('grep', a), null);
+    assert.equal(a['-C'], 5);
+});

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). Use line+context for small windows. Batch paths.',
+        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.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -26,14 +26,26 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         {
                             type: 'array',
-                            items: { type: 'string' },
+                            items: {
+                                anyOf: [
+                                    { type: 'string' },
+                                    {
+                                        type: 'object',
+                                        properties: {
+                                            path: { type: 'string' },
+                                            offset: { type: 'number', minimum: 0 },
+                                            limit: { type: 'number', minimum: 1 },
+                                        },
+                                    },
+                                ],
+                            },
                             minItems: 1,
                         },
                     ],
-                    description: 'File path or array. Dirs use list.',
+                    description: 'File path, path[], or {path,offset,limit}[] region objects. Pass arrays directly; JSON strings are legacy recovery only. Dirs use list.',
                 },
-                line: { type: 'number', minimum: 1, description: 'Anchor line.' },
-                context: { type: 'number', minimum: 0, maximum: 200, description: 'Lines around line; max 200.' },
+                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.' },
             },
         },
     },
@@ -53,7 +65,10 @@ export const BUILTIN_TOOLS = [
     {
         name: 'open_config',
         title: 'Open Config UI',
-        annotations: { title: 'Open Config UI', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        // 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 },
     },
@@ -61,7 +76,7 @@ export const BUILTIN_TOOLS = [
         name: 'shell',
         title: 'Mixdog Shell',
         annotations: { title: 'Mixdog Shell', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, compressible: true },
-        description: `Run shell for git/build/test/run. Not for source browsing; use code_graph/grep/read/list/glob. Set shell: powershell or bash. ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
+        description: `Run shell to CHANGE state or RUN programs (git/build/test/run). Never to inspect the filesystem — reading, listing, searching, or checking existence go through the dedicated tools, never a shell command. Set shell: powershell or bash. ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -101,7 +116,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 text/logs/regex.',
+        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.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -110,19 +125,20 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Text/regex. Array = OR.',
+                    description: 'Text/regex. Put synonyms in pattern[] as OR in ONE grep; no serial rewording or equivalent repeats.',
                 },
-                path: { type: 'string', description: 'File or directory.' },
+                path: { type: 'string', description: 'Known narrowest file/dir; broad scopes return paths first, then refine from returned paths.' },
                 glob: {
                     anyOf: [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Optional narrowing glob(s).',
+                    description: 'Narrow in same grep; no follow-up grep for equivalent scope changes.',
                 },
-                output_mode: { type: 'string', enum: ['files_with_matches', 'content', 'count'], description: 'Output mode.' },
-                head_limit: { type: 'number', description: 'Max lines.' },
-                offset: { type: 'number', description: 'Skip lines.' },
+                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.' },
             },
             required: [],
         },
@@ -131,7 +147,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 glob.',
+        description: 'Find files by exact glob. Unknown path/name uses find.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -140,7 +156,7 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Glob pattern(s).',
+                    description: 'Exact glob pattern(s).',
                 },
                 path: {
                     anyOf: [
@@ -159,11 +175,11 @@ 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: 'Fuzzy-find files by partial path/name. Returns paths.',
+        description: 'Find files by partial path/name. Exact structure uses glob. Returns verified paths.',
         inputSchema: {
             type: 'object',
             properties: {
-                query: { type: 'string', description: 'Partial path/name words.' },
+                query: { type: 'string', description: 'Partial path/name words; not file contents.' },
                 path: { type: 'string', description: 'Base directory.' },
                 head_limit: { type: 'number', description: 'Max paths.' },
             },

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-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

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

@@ -36,6 +36,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 +358,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 +401,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;

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

@@ -1,9 +1,10 @@
 import { countSplitLines } from './path-utils.mjs';
+import { TOOL_OUTPUT_MAX_BYTES } from './tool-output-limit.mjs';
 
-export const SHELL_OUTPUT_MAX_CHARS = 30_000;
+export const SHELL_OUTPUT_MAX_CHARS = TOOL_OUTPUT_MAX_BYTES;
 
 export const SMART_BASH_MAX_LINES = 400;
-export const SMART_BASH_MAX_BYTES = 30_000;
+export const SMART_BASH_MAX_BYTES = TOOL_OUTPUT_MAX_BYTES;
 export const SMART_BASH_HEAD_LINES = 80;
 export const SMART_BASH_TAIL_LINES = 80;
 

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

@@ -0,0 +1,10 @@
+// Single source of truth for the model-facing tool-output byte budget.
+// read / shell / list-tree all truncate their output to this cap so the
+// context cost of any one tool call is bounded and consistent. Override with
+// MIXDOG_TOOL_OUTPUT_MAX_BYTES. Line-based sub-caps (e.g. bash max lines) stay
+// per-tool; this governs only the byte budget.
+function _envInt(name, fallback) {
+    const v = parseInt(process.env[name], 10);
+    return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+export const TOOL_OUTPUT_MAX_BYTES = _envInt('MIXDOG_TOOL_OUTPUT_MAX_BYTES', 50 * 1024);