mixdog 0.9.17 → 0.9.19

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

@@ -114,7 +114,7 @@ export async function executeBashTool(args, workDir, options = {}) {
     const requestedCwd = args.cwd ?? args.workdir;
     const cwdResult = resolveOptionalCwd(requestedCwd, workDir);
     if (cwdResult.error) return cwdResult.error;
-    // Session cwd carry-over (Claude Code style, no live shell): when the model
+    // Session cwd carry-over (no live shell): when the model
     // passes an explicit cwd it wins and updates the store on the next probe;
     // otherwise reuse the last stored cwd for this session if it still exists.
     const _hasExplicitCwd = typeof requestedCwd === 'string' && requestedCwd.trim() !== '';
@@ -231,7 +231,15 @@ export async function executeBashTool(args, workDir, options = {}) {
     // run_in_background (already detached) or persistent sessions (handled
     // far above). Capped below the hard timeout so the 600 s upper bound
     // stays a separate, later ceiling.
-    const DEFAULT_AUTO_BACKGROUND_MS = 30_000;
+    // Soft config: reuse the sync task-wait budget (30 s, see waitForShellJob
+    // default in executeTaskTool) as the default promotion threshold. Override
+    // with MIXDOG_SHELL_AUTO_BACKGROUND_MS (positive ms). This is a soft hint,
+    // not a hard cap — the value is clamped below `timeout` so the hard ceiling
+    // stays a separate, later bound.
+    const _autoBgEnvMs = Number(process.env.MIXDOG_SHELL_AUTO_BACKGROUND_MS);
+    const DEFAULT_AUTO_BACKGROUND_MS = Number.isFinite(_autoBgEnvMs) && _autoBgEnvMs > 0
+      ? Math.floor(_autoBgEnvMs)
+      : 30_000;
     const autoBackgroundMs = runInBackground
       ? 0
       : Math.min(DEFAULT_AUTO_BACKGROUND_MS, timeout);

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

@@ -17,7 +17,7 @@ export const BUILTIN_TOOLS = [
         name: 'read',
         title: 'Mixdog Read',
         annotations: { title: 'Mixdog Read', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false },
-        description: 'Read known file path(s). Prefer grep content_with_context or code_graph anchors first. Window with numeric offset+limit. Batch paths/regions as real arrays; adjacent spans in one file = one window, not repeated calls. Dirs use list.',
+        description: 'Read known file path(s) with optional numeric offset+limit windows. Batch paths/regions as real arrays in one call. Not for directory listing.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -53,7 +53,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 to CHANGE state or RUN programs (git/build/test/run). Never to inspect the filesystem — reading, listing, searching, existence checks use the dedicated tools, never shell. Set shell: powershell or bash. ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
+        description: `Run programs or change system state. Set shell: powershell or bash. Not for reading, listing, or searching files. ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -87,7 +87,7 @@ export const BUILTIN_TOOLS = [
         name: 'grep',
         title: 'Mixdog Grep',
         annotations: { title: 'Mixdog Grep', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Search file contents by text/regex in a known scope. files_with_matches/count for broad anchors, content_with_context for narrow answers. One concept → ONE grep: all variants in pattern[], scopes in path[]; parallel single-pattern greps = packing failure.',
+        description: 'Exact text/regex in a KNOWN scope. files_with_matches/count for broad anchors, content_with_context for narrow answers.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -96,30 +96,28 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Text/regex. Put synonyms in pattern[] as OR in ONE grep; no serial rewording or equivalent repeats.',
+                    description: 'Text/regex. Array = variants in one call.',
                 },
                 path: {
                     anyOf: [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Known narrowest file/dir, or path[] to search several scopes in one call; broad scopes return paths first, then refine from returned paths.',
+                    description: 'Known file or dir. Array = several scopes.',
                 },
                 glob: {
                     anyOf: [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Narrow in same grep; no follow-up grep for equivalent scope changes.',
+                    description: 'Glob filter to narrow scope.',
                 },
-                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.' },
-                head_limit: { type: 'number', minimum: 0, description: 'Max output lines; keep small.' },
-                offset: { type: 'number', minimum: 0, description: 'Skip output lines for paging.' },
+                output_mode: { type: 'string', enum: ['content_with_context', 'content', 'files_with_matches', 'count'], description: 'Broad: files_with_matches/count; narrow: content_with_context.' },
+                head_limit: { type: 'number', minimum: 0, description: 'Max results.' },
+                offset: { type: 'number', minimum: 0, description: 'Skip results for paging.' },
                 '-A': { type: 'number', minimum: 0, description: 'Lines after each match.' },
                 '-B': { type: 'number', minimum: 0, description: 'Lines before each match.' },
-                // Description nudges -C 5 on content modes — measured fix for
-                // grep→read same-file re-open round-trips (2026-07 diag).
-                '-C': { type: 'number', minimum: 0, description: 'Lines before/after each match. Content modes: pass -C 5+ so the hit is edit-ready; skipping it forces a follow-up read.' },
+                '-C': { type: 'number', minimum: 0, description: 'Lines before/after each match.' },
             },
             required: [],
         },
@@ -128,7 +126,7 @@ export const BUILTIN_TOOLS = [
         name: 'glob',
         title: 'Mixdog Glob',
         annotations: { title: 'Mixdog Glob', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Find files by exact glob. Unknown path/name uses find. Multiple patterns/dirs = ONE call with pattern[]/path[], never parallel single-pattern calls.',
+        description: 'Find files by exact glob. Batch patterns and roots as arrays in one call.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -156,7 +154,7 @@ export const BUILTIN_TOOLS = [
         name: 'find',
         title: 'Mixdog Find Files',
         annotations: { title: 'Mixdog Find Files', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Find files by partial path/name. Exact structure uses glob. Returns verified paths. Multiple names = ONE call with query[].',
+        description: 'Find files by partial path/name. Returns verified paths. Batch names as query[].',
         inputSchema: {
             type: 'object',
             properties: {
@@ -177,7 +175,7 @@ export const BUILTIN_TOOLS = [
         name: 'list',
         title: 'Mixdog List Directory',
         annotations: { title: 'Mixdog List Directory', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'List known directory entries. Use glob for broad discovery. Multiple dirs = ONE call with path[].',
+        description: 'List known directory entries. Batch dirs as path[].',
         inputSchema: {
             type: 'object',
             properties: {

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

@@ -49,8 +49,13 @@ export function sliceReadBodyByLines(body, origOffset, origLimit) {
             : firstLine));
     const totalPart = haveTotal ? ` of ${totalNum}` : '';
     const moreToRead = haveTotal ? emittedLast < totalNum : finiteLast;
+    // Anti-fragmentation: modest remainders get the exact one-window
+    // continuation (offset+limit) instead of an open-ended "continue".
+    const _remaining = haveTotal ? totalNum - emittedLast : null;
     const continuationPart = moreToRead && Number.isFinite(emittedLast)
-        ? `; pass offset:${emittedLast} to continue`
+        ? (_remaining !== null && _remaining > 0 && _remaining <= 600
+            ? `; ${_remaining} lines left — take the rest in ONE window: offset:${emittedLast}, limit:${_remaining}`
+            : `; pass offset:${emittedLast} to continue`)
         : '';
     const newFooter = `[lines ${firstLine}-${emittedLast}${totalPart}${continuationPart}]`;
     return kept.join('\n') + (kept.length ? '\n' : '') + newFooter;

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

@@ -49,6 +49,20 @@ async function detectReadEncoding(fullPath) {
     }
 }
 
+// Reactive anti-fragmentation merge: per-session (readStateScope) memory of
+// the last requested window per file. When the next windowed read of the
+// same file starts shortly AFTER the previous window (gap <= 200 lines) and
+// the widened result stays modest (<= 400 lines), widen the request to
+// include the gap so the model never needs a third paging call.
+const _readWindowHistoryByScope = new WeakMap();
+function _readWindowHistory(scope) {
+    let m = _readWindowHistoryByScope.get(scope);
+    if (!m) { m = new Map(); _readWindowHistoryByScope.set(scope, m); }
+    return m;
+}
+const _WIDEN_GAP_MAX_LINES = 200;
+const _WIDEN_RESULT_MAX_LINES = 400;
+
 export async function executeSingleReadTool(args, workDir, readStateScope, options = {}, helpers = {}) {
     const {
         appendReadContextAdvisory,
@@ -136,12 +150,13 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
     const hasLimitArg = args.limit !== undefined && args.limit !== null;
     const hasRangeArgs = hasOffsetArg || hasLimitArg;
     const wantFull = args.full === true;
-    const offset = parseOffsetArg(args.offset);
+    let offset = parseOffsetArg(args.offset);
     // full:true bypasses the default 2000-line cap so the whole file
     // can be returned in one call; the byte-cap path below still
     // emits a compact truncation marker when rendered bytes overflow
     // READ_MAX_OUTPUT_BYTES.
-    const limit = parseLineLimitArg(args.limit, wantFull ? Infinity : 2000);
+    let limit = parseLineLimitArg(args.limit, wantFull ? Infinity : 2000);
+    let _widenNote = '';
     let st;
     let _statErr;
     try {
@@ -200,6 +215,23 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
             }
         } catch { /* lstat failure is non-fatal; the original `st` is authoritative */ }
     }
+    // Reactive widen + window-history bookkeeping (ranged text reads only).
+    if (st && readStateScope && typeof readStateScope === 'object'
+        && hasOffsetArg && hasLimitArg && Number.isFinite(limit) && limit > 0) {
+        const _wins = _readWindowHistory(readStateScope);
+        const prev = _wins.get(fullPath);
+        if (prev && offset > prev.end && limit <= _WIDEN_RESULT_MAX_LINES) {
+            const gap = offset - prev.end;              // unread lines between windows
+            const mergedLines = (offset + limit) - prev.end;
+            if (gap <= _WIDEN_GAP_MAX_LINES && mergedLines <= _WIDEN_RESULT_MAX_LINES) {
+                _widenNote = `[widened: included the ${gap}-line gap after your last window (lines ${prev.start}-${prev.end}) — one span instead of another page]`;
+                offset = prev.end;
+                limit = mergedLines;
+            }
+        }
+        _wins.set(fullPath, { start: offset + 1, end: offset + limit });
+        if (_wins.size > 64) _wins.delete(_wins.keys().next().value);
+    }
     if (!st) {
         const err = _statErr;
         const redirected = await tryReadFamilyEnoentRedirect({
@@ -639,8 +671,18 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
             } else if (Buffer.byteLength(rendered, 'utf8') <= READ_MAX_OUTPUT_BYTES) {
                 const emittedStart = offset + 1;
                 const emittedEnd = offset + sliced.length;
-                const footer = `[lines ${emittedStart}-${emittedEnd} of ${lineCount}${emittedEnd < lineCount ? `; pass offset:${emittedEnd} to continue` : ''}]`;
+                // Anti-fragmentation: when the remainder is modest, hand the
+                // model the exact one-window continuation instead of inviting
+                // another small page.
+                const _remaining = lineCount - emittedEnd;
+                const _cont = emittedEnd < lineCount
+                    ? (_remaining <= 600
+                        ? `; ${_remaining} lines left — take the rest in ONE window: offset:${emittedEnd}, limit:${_remaining}`
+                        : `; pass offset:${emittedEnd} to continue`)
+                    : '';
+                const footer = `[lines ${emittedStart}-${emittedEnd} of ${lineCount}${_cont}]`;
                 out += `${out ? '\n' : ''}${footer}`;
+                if (_widenNote) out += `\n${_widenNote}`;
             }
         }
         // Smart cap. Only engages when the caller asked for

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

@@ -163,10 +163,13 @@ export function buildNotFoundHint(workDir, missingPath, actionVerb, errCode = 'E
         const parentRel = nearestExistingParentRel(workDir, missingPath);
         if (parentRel) {
             const resolvedParent = parentRel === '.' ? workDir : resolveAgainstCwd(parentRel, workDir);
-            const siblings = listSiblings(resolvedParent, 5);
+            // Compact hint: drop log/artifact noise, keep at most 3 candidates.
+            const siblings = listSiblings(resolvedParent, 12)
+                .filter((n) => !/\.(log|log\.\d+|tmp|bak)$/i.test(n))
+                .slice(0, 3);
             if (siblings.length) {
                 const shown = parentRel === '.' ? '.' : normalizeOutputPath(parentRel);
-                return ` Not found at this path; under "${shown}" try: ${siblings.map((n) => `"${n}"`).join(', ')}.`;
+                return ` Not found; under "${shown}" try: ${siblings.map((n) => `"${n}"`).join(', ')}.`;
             }
         }
     }

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

@@ -53,6 +53,7 @@ import {
     normalizeGrepLine,
     splitGrepCountPrefix,
     splitGrepLinePrefix,
+    splitGrepLineNumberOnlyPrefix,
 } from './grep-formatting.mjs';
 import {
     cacheGet,
@@ -66,6 +67,8 @@ import { applyGrepContextLeadPolicy, GREP_CONTEXT_MAX, hasUnsupportedRipgrepRege
 // 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.
+// Explicit -A/-B/-C is honored up to the generic GREP_CONTEXT_MAX (no tighter
+// context-mode clamp by policy); only head_limit blocks are context-clamped.
 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 || ''));
@@ -361,12 +364,116 @@ function buildGrepChunkMergePrefix(patternChunkCount, truncated, aggregateBudget
     return `[${parts.join('; ')}]\n`;
 }
 
+// --- context-mode match-block windowing (Parts 2 & 3) ---------------------
+// In context mode (explicit -A/-B/-C or content_with_context auto), head_limit
+// and offset count MATCH BLOCKS, not raw output lines, and truncation keeps a
+// head+tail slice with a middle marker instead of dropping the tail.
+function grepBlockMatchAnchor(line, filenameOmitted) {
+    if (filenameOmitted) {
+        const p = splitGrepLineNumberOnlyPrefix(line);
+        return p && p.delimiter === ':' ? `#${p.lineNo}` : '';
+    }
+    const s = splitGrepLinePrefix(line);
+    return s && s.delimiter === ':' ? `${s.path}\0${s.lineNo}` : '';
+}
+
+function parseGrepContextBlocks(lines, filenameOmitted) {
+    const blocks = [];
+    let pending = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line === '--') { pending = []; i++; continue; }
+        const anchor = grepBlockMatchAnchor(line, filenameOmitted);
+        if (anchor) {
+            const blockLines = pending.concat([line]);
+            pending = [];
+            i++;
+            while (i < lines.length) {
+                const next = lines[i];
+                if (next === '--' || grepBlockMatchAnchor(next, filenameOmitted)) break;
+                blockLines.push(next);
+                i++;
+            }
+            blocks.push({ anchor, lines: blockLines });
+            continue;
+        }
+        pending.push(line);
+        i++;
+    }
+    return blocks;
+}
+
+function formatGrepContextOutput({ allLines, workDir, outputMode, filenameOmitted, headLimit, offset, totalKnown = true }) {
+    const norm = allLines.map((l) => (l === '--' ? '--' : relativeGrepLine(l, workDir, false, outputMode, filenameOmitted)));
+    const blocks = parseGrepContextBlocks(norm, filenameOmitted);
+    const total = blocks.length;
+    if (total === 0) return { text: '', total: 0, shown: 0, omitted: 0 };
+    // Finding 2/3: denominator is the PRE-offset grand total; on a partial rg
+    // read (stdout cap / stream cap) it is a lower bound, so print ">=T".
+    const totalStr = totalKnown ? `${total}` : `>=${total}`;
+    const afterOffset = offset > 0 ? blocks.slice(offset) : blocks;
+    if (afterOffset.length === 0) {
+        // On a partial stream (line cap / timeout) the parsed blocks are a
+        // lower bound — an offset beyond them is NOT proven past the last
+        // match, so steer toward narrowing instead of claiming "past end".
+        const text = totalKnown
+            ? `[Showing 0 of ${totalStr} matches; offset ${offset} past end]`
+            : `[Showing 0 of ${totalStr} matches (results partial); offset ${offset} is beyond the streamed window — matches past it may exist. Narrow path/glob/pattern instead of paging deeper.]`;
+        return { text, total, shown: 0, omitted: 0 };
+    }
+    const shown = headLimit === Infinity ? afterOffset.length : Math.min(headLimit, afterOffset.length);
+    const omitted = afterOffset.length - shown;
+    const render = (arr) => arr.map((b) => b.lines.join('\n'));
+    let segments;
+    let nextOffset = offset + shown;
+    if (omitted > 0 && shown > 0) {
+        // Keep head + tail so both ends of the match range stay visible.
+        const headCount = Math.max(1, Math.ceil(shown / 2));
+        const tailCount = shown - headCount;
+        const head = render(afterOffset.slice(0, headCount));
+        const tail = tailCount > 0 ? render(afterOffset.slice(afterOffset.length - tailCount)) : [];
+        segments = [...head, `…${omitted} matches omitted…`, ...tail];
+        // Paging must resume at the first OMITTED block (right after the head
+        // slice): offset+shown would permanently skip the middle blocks that
+        // the tail slice displaced. Tail blocks re-appear on later pages —
+        // duplication is acceptable, silent loss is not.
+        nextOffset = offset + headCount;
+    } else {
+        segments = render(afterOffset.slice(0, shown));
+    }
+    const notice = (omitted > 0 || !totalKnown)
+        ? `\n[Showing ${shown} of ${totalStr} matches${totalKnown ? '' : ' (results partial)'}; pass offset:${nextOffset} for more]`
+        : '';
+    return { text: segments.join('\n--\n') + notice, total, shown, omitted };
+}
+
+// Part 1: drop path:line match lines already emitted by an earlier pattern in
+// a pattern[] fan-out. Context ('-') lines and non-match lines pass through.
+function dedupeFanoutMatchLines(body, seen) {
+    const text = String(body);
+    if (/^Error:/.test(text)) return text;
+    const out = [];
+    for (const line of text.split('\n')) {
+        const s = splitGrepLinePrefix(line);
+        if (s && s.delimiter === ':') {
+            const key = `${s.path}\0${s.lineNo}`;
+            if (seen.has(key)) continue;
+            seen.add(key);
+        }
+        out.push(line);
+    }
+    return out.join('\n');
+}
+
 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, disableContentGrouping = false }) {
     const lines = headLimit === Infinity ? windowed : windowed.slice(0, headLimit);
     const normalized = lines.map((line) => relativeGrepLine(line, workDir, outputMode === 'files_with_matches', outputMode, filenameOmitted));
     const remaining = Math.max(0, totalWindowed - lines.length);
     const shown = lines.length;
-    const total = totalWindowed;
+    // Finding 3: PRE-offset grand total so the denominator matches the
+    // context-mode notice (offset==0 leaves this unchanged).
+    const total = offset + totalWindowed;
     const scopePath = JSON.stringify(normalizeOutputPath(searchPath));
     const truncated = (remaining > 0 || !totalKnown)
         ? (totalKnown
@@ -604,6 +711,33 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
     if (fileTypes.length > 1) fileType = fileTypes;
     else if (fileTypes.length === 1) fileType = fileTypes[0];
 
+    // Part 1: pattern[] fan-out. Two or more patterns in a content search run
+    // as INDEPENDENT greps (mirroring the path[] batching above): each pattern
+    // keeps its own full head_limit budget and its own truncation notice, and
+    // identical path:line match lines are de-duplicated across patterns. The
+    // single-pattern path and the non-content modes (files_with_matches/count)
+    // keep the combined single-rg behavior. `_grepPatternFanout` guards the
+    // recursive single-pattern calls from re-entering the fan-out; the internal
+    // chunk-merge recursion is likewise skipped.
+    if (patterns.length > 1
+        && outputMode === 'content'
+        && !options._grepChunkMerge
+        && !options._grepPatternFanout) {
+        const seen = new Set();
+        const subOptions = { ...options, _grepPatternFanout: true };
+        const parts = [];
+        for (const p of patterns) {
+            let sub;
+            try {
+                sub = await executeGrepTool({ ...args, pattern: p }, workDir, executeChildBuiltinTool, readStateScope, subOptions);
+            } catch (err) {
+                sub = `Error: ${err && err.message ? err.message : err}`;
+            }
+            parts.push(`# grep pattern:${JSON.stringify(p)}\n${dedupeFanoutMatchLines(sub, seen)}`);
+        }
+        return patternCapNote + parts.join('\n\n');
+    }
+
     const patternChunkCap = multilineMode ? GREP_MULTILINE_PATTERN_CAP : GREP_ARRAY_PATTERN_CAP;
     if (patterns.length > patternChunkCap) {
         const patternChunks = chunkPatternList(patterns, patternChunkCap);
@@ -676,7 +810,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
         });
     }
 
-    const forceGrepFilename = !!options._grepChunkMerge;
+    const forceGrepFilename = !!options._grepChunkMerge || !!options._grepPatternFanout;
     const cacheKey = buildGrepCacheKey({
         patterns,
         searchPath: normalizeOutputPath(grepResolvedPath),
@@ -775,6 +909,64 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
             pcre2: pcre2Mode,
             withFilename: forceGrepFilename,
         });
+        // Parts 2 & 3: context mode windows MATCH BLOCKS (not raw lines); the
+        // total match count and tail blocks come from the streamed (memory-
+        // bounded) collection below.
+        const contextMode = outputMode === 'content' && (beforeN > 0 || afterN > 0 || contextN > 0);
+        if (contextMode) {
+            // Finding 1: stream only enough lines to satisfy the block window
+            // (offset + head_limit + tail reserve), so rg is stopped early and a
+            // broad content_with_context never retains a full 20MB stdout copy.
+            // A cap hit → complete:false → partial (lower-bound) phrasing below.
+            const GREP_CONTEXT_LINE_HARD_CAP = 4000;
+            const perBlock = 2 + (beforeN || 0) + (afterN || 0) + 2 * (contextN || 0);
+            const blockBudget = headLimit === Infinity ? Infinity : offset + headLimit + 4;
+            const lineCap = blockBudget === Infinity
+                ? GREP_CONTEXT_LINE_HARD_CAP
+                : Math.min(GREP_CONTEXT_LINE_HARD_CAP, Math.max(200, blockBudget * Math.max(1, perBlock) + 8));
+            let ctxPartialSuffix = '';
+            const streamed = await runRgWindowedLines(rgArgs, { cwd: rgSpawnCwd }, { offset: 0, limit: lineCap, summaryLimit: 0 });
+            const allLines = streamed.lines;
+            let ctxTotalKnown = streamed.complete;
+            if (streamed.partial) {
+                ctxTotalKnown = false;
+                ctxPartialSuffix = streamed.timeout
+                    ? '\n[warning] rg timed out; partial results shown. Narrow path/glob/pattern for a complete result.'
+                    : streamed.rgStderr
+                    ? `\n[warning] rg exit 2 (partial results): ${String(streamed.rgStderr).trim().slice(0, 300)}`
+                    : '\n[warning] rg exit 2 (partial results)';
+            } else if (!streamed.complete) {
+                ctxPartialSuffix = `\n[warning] context output capped at ${lineCap} lines to bound memory; results partial — narrow path/glob/pattern for the full match set.`;
+            }
+            const ctx = formatGrepContextOutput({
+                allLines,
+                workDir,
+                outputMode,
+                filenameOmitted,
+                headLimit,
+                offset,
+                totalKnown: ctxTotalKnown,
+            });
+            let ctxBody = ctx.text;
+            if (!ctxBody) {
+                const patternStr = patterns.length === 1 ? JSON.stringify(patterns[0]) : JSON.stringify(patterns);
+                const globStr = normalizedGlobPatterns.length > 0 ? ` glob=${JSON.stringify(normalizedGlobPatterns)}` : '';
+                const pathInfo = grepStat.isDirectory() ? 'path exists (dir)' : 'path exists (file)';
+                ctxBody = `(no matches) pattern=${patternStr} path=${searchPath}${globStr}; ${pathInfo}`;
+            }
+            const ctxOut = patternCapNote + ctxBody + ctxPartialSuffix;
+            if (options?.scopedCacheOutcome && (!ctxTotalKnown || ctx.omitted > 0)) {
+                markScopedCacheIncomplete(options.scopedCacheOutcome);
+            }
+            recordGrepReadSnapshot(grepStat);
+            if (ctxTotalKnown && ctx.omitted === 0) {
+                cacheSet(cacheKey, ctxOut, { scopes: [grepResolvedPath] });
+            }
+            if (typeof options?.onProgress === 'function') {
+                try { options.onProgress(`found ${ctx.total} matches`); } catch { /* best-effort */ }
+            }
+            return ctxOut;
+        }
         let windowed;
         let totalWindowed = 0;
         let totalKnown = true;
@@ -832,7 +1024,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
             globPatterns: normalizedGlobPatterns,
             fileType,
             filenameOmitted,
-            disableContentGrouping: !!options._grepChunkMerge,
+            disableContentGrouping: !!options._grepChunkMerge || !!options._grepPatternFanout,
         });
         if (!body) {
             const pathInfo = grepStat.isDirectory() ? 'path exists (dir)' : 'path exists (file)';

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

@@ -297,6 +297,7 @@ const EXTERNAL_TOOL_REDIRECTS = new Map([
     ['codebase_search', 'use the `grep` or `code_graph` tool'],
     ['semanticsearch', 'use the `grep` or `code_graph` tool'],
     ['semantic_search', 'use the `grep` or `code_graph` tool'],
+    ['explore', 'not available in this role — use `grep` or `code_graph` for repo search'],
 ]);
 
 export function canonicalizeBuiltinToolName(name) {
@@ -520,7 +521,22 @@ export async function executeBuiltinTool(name, args, cwd, options = {}) {
     }
     })();
     const _withNudge = _maybeAppendGrepSweepNudge(toolName, args, _toolResult, readStateScope);
-    return capToolOutput(_withNudge, options);
+    return capToolOutput(_appendClampNotices(args, _withNudge), options);
+}
+
+// Surface arg-guard clamp notices (args._clampNotices, see pushClampNotice in
+// arg-guard.mjs) on the result text so the caller learns its request was
+// capped. Delete to consume: prevents double-append when a child-builtin
+// result is embedded in the parent's, and leaves no `_clampNotices` residue
+// on the recorded tool-call args in the transcript.
+function _appendClampNotices(args, result) {
+    let notices = null;
+    if (args && Array.isArray(args._clampNotices)) {
+        notices = args._clampNotices;
+        delete args._clampNotices;
+    }
+    if (!notices || notices.length === 0 || typeof result !== 'string') return result;
+    return `${result}\n\n${notices.map((n) => `[arg-guard] ${n}`).join('\n')}`;
 }
 /**
  * Check if a tool name is a builtin tool.

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

@@ -51,6 +51,36 @@ function _collectGraphSymbolList(args) {
 
 const CODE_GRAPH_FILE_BATCH_CAP = 20;
 
+// Absorb: file/files arriving as a JSON-stringified array
+// (file:"[\"a.mjs\",\"b.mjs\"]") — parse to a real array so the graph lookup
+// batches per file instead of treating the JSON text as one (missing) path.
+function _parseJsonArrayString(v) {
+  if (typeof v !== 'string') return null;
+  const t = v.trim();
+  if (!t.startsWith('[') || !t.endsWith(']')) return null;
+  try {
+    const parsed = JSON.parse(t);
+    if (Array.isArray(parsed)) return parsed.map((x) => String(x || '').trim()).filter(Boolean);
+  } catch { /* not JSON — leave untouched */ }
+  return null;
+}
+
+function _normalizeGraphFileArgs(args) {
+  if (!args || typeof args !== 'object') return args;
+  const fileArr = _parseJsonArrayString(args.file);
+  const filesArr = _parseJsonArrayString(args.files);
+  if (!fileArr && !filesArr) return args;
+  const out = { ...args };
+  if (fileArr) { out.files = Array.isArray(out.files) ? [...fileArr, ...out.files] : fileArr; delete out.file; }
+  if (filesArr) out.files = filesArr;
+  // Collapse a lone entry back to the single-file field for the fast path.
+  if (Array.isArray(out.files) && out.files.length === 1 && !out.file) {
+    out.file = out.files[0];
+    delete out.files;
+  }
+  return out;
+}
+
 function _collectGraphFileList(args) {
   const split = (s) => String(s || '').split(/,+/).map((t) => t.trim()).filter(Boolean);
   const list = [...new Set([
@@ -70,6 +100,13 @@ async function codeGraph(args, cwd, signal = null, options = {}) {
   let mode = String(args?.mode || '').trim();
   if (!mode) throw new Error('code_graph: "mode" is required');
   if (mode === 'search') mode = 'symbol_search';
+  // Name-only "symbols" calls (symbols[]/symbol without a file) are symbol
+  // lookups, not a file outline — absorb into symbol_search instead of
+  // erroring "file not found in graph: (missing file)".
+  if (mode === 'symbols' && !String(args?.file || '').trim()
+      && ((Array.isArray(args?.symbols) && args.symbols.length) || String(args?.symbol || '').trim())) {
+    mode = 'symbol_search';
+  }
 
   if (mode === 'prewarm') {
     const _splitMulti = (s) => String(s || '').split(/[,\s]+/).map((t) => t.trim()).filter(Boolean);
@@ -436,6 +473,7 @@ export async function resolveSymbolReadSpan(cwd, { symbol, path = null, language
 
 export async function executeCodeGraphTool(name, args, cwd, signal = null, options = {}) {
   if (!cwd) throw new Error('find_symbol/code_graph requires cwd — caller did not provide a working directory');
+  args = _normalizeGraphFileArgs(args);
   const fileArg = (args && typeof args.file === 'string' && args.file.trim()) ? args.file.trim() : '';
   const baseCwd = (args && typeof args.cwd === 'string' && args.cwd.trim()) ? args.cwd.trim() : cwd;
   let effectiveCwd = baseCwd;

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

@@ -3,13 +3,13 @@ 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: 'Repo-local code structure/flow lookup, not web: symbols/references/calls/deps before text grep. Multiple targets = ONE call with symbols[]/files[], never parallel single-target calls.',
+    description: 'Repo-local code structure/flow lookup (not web): symbols/references/calls/deps. Batch targets as symbols[]/files[] in one call.',
     inputSchema: {
       type: 'object',
       properties: {
-        mode: { type: 'string', enum: ['overview', 'imports', 'dependents', 'related', 'impact', 'symbols', 'find_symbol', 'symbol_search', 'search', 'references', 'callers'], description: 'Repo-local operation; code flow before text search.' },
-        files: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Source file(s): string or array; one call fans out per file (imports/dependents/related/impact/symbols/overview). `file` singular alias also accepted.' },
-        symbols: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Identifier(s)/keyword(s): string or array; batch in one call. One anchor is enough. `symbol` singular alias also accepted.' },
+        mode: { type: 'string', enum: ['overview', 'imports', 'dependents', 'related', 'impact', 'symbols', 'find_symbol', 'symbol_search', 'search', 'references', 'callers'], description: 'Repo-local graph operation.' },
+        files: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Source file(s); array fans out per file. `file` alias too.' },
+        symbols: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Identifier(s)/keyword(s); array batches in one call. `symbol` alias too.' },
         symbol: { type: 'string', description: 'Singular alias for symbols.' },
         file: { type: 'string', description: 'Singular alias for files.' },
         body: { type: 'boolean', description: 'Include body.' },

package/src/runtime/agent/orchestrator/tools/shell-state.mjs

@@ -1,5 +1,5 @@
 'use strict';
-// Claude Code-style shell state carry-over for the one-shot shell tool.
+// Shell state carry-over for the one-shot shell tool.
 //
 // No live shell process is kept. Instead, after each sync command we chain a
 // trailing cwd probe that writes the final working directory to a per-session

package/src/runtime/channels/backends/discord-attachments.mjs

@@ -5,13 +5,13 @@ import { join, sep } from "path";
 
 const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
 
-async function downloadSingleAttachment(att, inboxDir) {
+async function downloadSingleAttachment(att, inboxDir, { timeoutMs = 180_000 } = {}) {
   if (att.size > MAX_ATTACHMENT_BYTES) {
     throw new Error(
       `attachment too large: ${(att.size / 1024 / 1024).toFixed(1)}MB, max ${MAX_ATTACHMENT_BYTES / 1024 / 1024}MB`
     );
   }
-  const res = await fetch(att.url, { signal: AbortSignal.timeout(180_000) });
+  const res = await fetch(att.url, { signal: AbortSignal.timeout(timeoutMs) });
   if (!res.ok) {
     throw new Error(`attachment download failed: HTTP ${res.status}`);
   }