mixdog 0.9.17 → 0.9.19

package/src/runtime/agent/orchestrator/session/loop/steering-ladder.mjs

@@ -8,6 +8,91 @@ import { appendAgentTrace } from '../../agent-trace.mjs';
 import { level2SteerMessage } from './completion-guards.mjs';
 import { isEagerDispatchable } from './tool-helpers.mjs';
 
+// --- Steering detector helpers (pure) ---
+const _WORD_RE = /[A-Za-z_$][\w$]*/g;
+const _IDENT_RE = /^[A-Za-z_$][\w$]{2,}$/;
+const _SRC_DIR_RE = /(^|[\\/])(src|lib|app|packages|components|pages)([\\/]|$)/i;
+function _grepPatterns(c) {
+    const p = c?.arguments?.pattern;
+    if (typeof p === 'string') return [p];
+    if (Array.isArray(p)) return p.filter((x) => typeof x === 'string');
+    return [];
+}
+function _patternTokens(c) {
+    const out = new Set();
+    for (const pat of _grepPatterns(c)) {
+        for (const t of (String(pat).match(_WORD_RE) || [])) {
+            if (t.length >= 3) out.add(t.toLowerCase());
+        }
+    }
+    return out;
+}
+function _pathsOf(arg) {
+    const out = [];
+    const push = (v) => {
+        if (typeof v === 'string' && v) out.push(v);
+        else if (v && typeof v === 'object' && typeof v.path === 'string' && v.path) out.push(v.path);
+    };
+    if (Array.isArray(arg)) arg.forEach(push); else push(arg);
+    return out;
+}
+// Case-insensitive (win32 paths) forward-slash normalization for all path compares.
+function _normPath(p) { return String(p).replace(/\\/g, '/').toLowerCase(); }
+function _baseName(p) { const s = _normPath(p); const i = s.lastIndexOf('/'); return i >= 0 ? s.slice(i + 1) : s; }
+function _dirName(p) { const s = _normPath(p); const i = s.lastIndexOf('/'); return i >= 0 ? s.slice(0, i) : ''; }
+// Exact (normalized) same-file test — used where "related" is too loose.
+function _samePath(a, b) { return !!a && !!b && _normPath(a) === _normPath(b); }
+// Loose sibling/variant relation — cluster detector pairs this WITH token overlap.
+function _pathsRelated(a, b) {
+    if (!a || !b) return false;
+    const na = _normPath(a); const nb = _normPath(b);
+    if (na === nb) return true;                                 // identical
+    if (na.includes(nb) || nb.includes(na)) return true;        // normalized variant
+    if (_dirName(na) && _dirName(na) === _dirName(nb)) return true; // siblings
+    const ba = _baseName(na); const bb = _baseName(nb);
+    return !!ba && ba === bb;                                    // same file name
+}
+function _setsOverlap(a, b) { for (const x of a) { if (b.has(x)) return true; } return false; }
+// A single chained segment is read-only only if it STARTS with a read-only verb.
+function _isReadOnlyShellSegment(seg) {
+    const s = seg.trim();
+    if (!s) return null;                                        // empty (trailing operator)
+    if (/^git\s+(status|log)\b/.test(s)) return true;
+    if (/^git\s+diff\b[^\n]*--stat\b/.test(s)) return true;
+    if (/^get-childitem\b/.test(s)) return true;
+    return /^(cat|ls|dir|type)\b/.test(s);
+}
+// Read-only only when EVERY chained segment is read-only — a single mutating
+// segment (e.g. `git status && npm test`) disqualifies the whole command.
+function _isReadOnlyShellCmd(cmd) {
+    const s = String(cmd || '').toLowerCase().trim();
+    if (!s) return false;
+    let sawCmd = false;
+    for (const seg of s.split(/&&|\|\||[;&|]/)) {
+        const verdict = _isReadOnlyShellSegment(seg);
+        if (verdict === null) continue;                         // blank segment
+        if (verdict === false) return false;                    // a mutating segment
+        sawCmd = true;
+    }
+    return sawCmd;
+}
+// Extract (path, offset) windows from a read call: path may be a string, an
+// array of strings, or an array of {path,offset,limit} regions; a top-level
+// offset applies to string entries.
+function _readWindows(c) {
+    const a = c?.arguments || {};
+    const out = [];
+    const push = (p, off) => { if (typeof p === 'string' && p) out.push({ path: p, offset: Number(off) }); };
+    const v = a.path;
+    if (Array.isArray(v)) {
+        for (const e of v) {
+            if (typeof e === 'string') push(e, a.offset);
+            else if (e && typeof e === 'object') push(e.path, e.offset ?? a.offset);
+        }
+    } else if (typeof v === 'string') push(v, a.offset);
+    return out;
+}
+
 // Build the completion-first steering-ladder controller. `ctx` supplies live
 // accessors so every read reflects the loop's current mutable state:
 //   - messages, sessionId, sessionAgent, tools           (stable refs/values)
@@ -43,13 +128,26 @@ export function createSteeringLadder(ctx) {
     // call (missed parallelism). Not reset per-iteration — only by the
     // steering-hint fire below or by a turn that batches/edits.
     let _serialReadOnlyStreak = 0;
-    // Tracks consecutive grep calls scoped to the SAME path (any patterns) —
-    // the "serial rewording" spiral: re-grepping one file with reworded
-    // patterns instead of reading it. Only counts turns whose every call is a
-    // grep on that path; any other tool/path resets it.
-    let _sameFileGrepStreak = 0;
-    let _sameFileGrepPath = null;
+    // Same-concept grep cluster (broadened serial-rewording spiral): counts
+    // consecutive grep-only turns that stay on ONE concept — related by
+    // identical/normalized/sibling paths OR pattern-token overlap, not just an
+    // identical path. `_sameGrepPrev` holds the prior turn's {paths,tokens}.
+    let _sameGrepStreak = 0;
+    let _sameGrepPrev = null;
+    // Prior turn's uncapped content/context grep paths — seeds the
+    // grep-context-then-read detector (a read of the same file next turn).
+    let _lastGrepContentPaths = null;
+    // Consecutive turns grepping the SAME identifier-like token in source dirs
+    // (symbol lookups that belong in code_graph).
+    let _identGrepStreak = 0;
+    let _identGrepToken = null;
     let _level2FireCount = 0;
+    // Read-fragmentation detector state: normalized path -> cumulative
+    // single-window offset reads. Mirrors session-bench read_fragmentation
+    // (3+ windowed reads of one file within an 800-line span). Multi-window
+    // same-path regions in ONE call are the recommended batched form and are
+    // never counted. Fires once per path per session.
+    const _readWindowsByPath = new Map();
 
     // Level-2 steering emitter shared by both ladder paths (single-call
     // level-1 streak and the independent all-read-only streak). Sets the latch
@@ -78,14 +176,14 @@ export function createSteeringLadder(ctx) {
             const iterations = getIterations();
             const editCount = getEditCount();
             // Steering hint gate: at most ONE hint per turn (priority:
-            // level-2 > same-file grep > level-1).
+            // level-2 > grep/shell detectors > level-1).
             let _hintFiredThisTurn = hintAlreadyFired;
-            // Missed-parallelism steering: 3+ consecutive turns of a single
+            // Missed-parallelism steering: 2+ consecutive turns of a single
             // read-only tool call suggest the model isn't batching independent
-            // lookups. Nudge once, then reset (fires again after 3 more).
+            // lookups. Nudge once, then reset (fires again after 2 more).
             if (calls.length === 1 && isEagerDispatchable(calls[0].name, tools)) {
                 _serialReadOnlyStreak += 1;
-                if (_serialReadOnlyStreak >= 3 && !_hintFiredThisTurn) {
+                if (_serialReadOnlyStreak >= 2 && !_hintFiredThisTurn) {
                     _serialReadOnlyStreak = 0;
                     // Escalation ladder (Step 1). Cumulative level-1 fires are
                     // tracked and NEVER reset. Once level-1 has fired >=3 times with
@@ -96,7 +194,7 @@ export function createSteeringLadder(ctx) {
                     if (_level1FireCount >= 3 && editCount === 0 && (iterations - _level2LatchAtIteration) >= 5) {
                         _emitLevel2Steer();
                     } else {
-                        pushSystemReminder('Last 3 turns each ran a single read-only tool. Batch independent lookups (read/grep/glob/code_graph) into ONE turn, or start editing if you have enough context.');
+                        pushSystemReminder('Last 2 turns each ran a single read-only tool. Batch independent lookups (read/grep/glob/code_graph) into ONE turn, or start editing if you have enough context.');
                     }
                     _hintFiredThisTurn = true;
                 }
@@ -121,36 +219,153 @@ export function createSteeringLadder(ctx) {
                     _allReadOnlyStreak = 0;
                 }
             }
-            // Serial-rewording steering: 4+ consecutive turns grepping the SAME
-            // path with reworded patterns = a search spiral that single-call
-            // batching cannot catch. Crisis-only: fires once per spiral, then
-            // resets. Read-the-file is almost always the answer at that point.
+            const _grepCalls = calls.filter((c) => c?.name === 'grep');
+            const _allGrep = calls.length > 0 && _grepCalls.length === calls.length;
+            // Detector: repeated identifier-like grep in source dirs → code_graph.
+            // Symbol lookups (a bare \w+ token scoped to src/) belong in
+            // code_graph (find_symbol/references/callers), not text grep. Fires
+            // when the same token is grepped on 2+ consecutive qualifying turns.
             {
-                const _grepPathOf = (c) => {
-                    if (c?.name !== 'grep') return null;
-                    const p = c?.arguments?.path;
-                    return typeof p === 'string' && p ? p : null;
-                };
-                const _turnPaths = calls.map(_grepPathOf);
-                const _uniq = [...new Set(_turnPaths)];
-                if (_uniq.length === 1 && _uniq[0] !== null) {
-                    if (_uniq[0] === _sameFileGrepPath) _sameFileGrepStreak += 1;
-                    else { _sameFileGrepPath = _uniq[0]; _sameFileGrepStreak = 1; }
-                    if (_sameFileGrepStreak >= 4 && !_hintFiredThisTurn) {
-                        pushSystemReminder(`4+ consecutive grep turns on the same path (${_sameFileGrepPath}). Rewording patterns is not converging — read the relevant span directly (read with offset/limit) or act on what you have.`);
-                        _sameFileGrepStreak = 0;
-                        _sameFileGrepPath = null;
+                let _identTok = null;
+                for (const c of _grepCalls) {
+                    const _srcScoped = _pathsOf(c?.arguments?.path).some((p) => _SRC_DIR_RE.test(p));
+                    if (!_srcScoped) continue;
+                    const _hit = _grepPatterns(c).map((p) => p.trim()).find((p) => _IDENT_RE.test(p));
+                    if (_hit) { _identTok = _hit.toLowerCase(); break; }
+                }
+                if (_identTok) {
+                    if (_identTok === _identGrepToken) _identGrepStreak += 1;
+                    else { _identGrepToken = _identTok; _identGrepStreak = 1; }
+                    if (_identGrepStreak >= 2 && !_hintFiredThisTurn) {
+                        pushSystemReminder(`Grepping the symbol "${_identGrepToken}" across source dirs again — use code_graph (find_symbol/references/callers) for symbol lookups instead of text grep.`);
+                        _identGrepStreak = 0;
+                        _identGrepToken = null;
+                        _hintFiredThisTurn = true;
+                    }
+                } else {
+                    _identGrepStreak = 0;
+                    _identGrepToken = null;
+                }
+            }
+            // Same-concept grep cluster (broadened serial-rewording): 3+
+            // consecutive grep-only turns on one concept — related by
+            // an exact-same path, OR a sibling/variant path that ALSO shares a
+            // pattern token (sibling alone is too loose to count).
+            // Fires once per spiral, then resets; read-the-span is the answer.
+            {
+                if (_allGrep) {
+                    const _paths = [];
+                    const _tokens = new Set();
+                    for (const c of _grepCalls) {
+                        for (const p of _pathsOf(c?.arguments?.path)) _paths.push(p);
+                        for (const t of _patternTokens(c)) _tokens.add(t);
+                    }
+                    let _related = false;
+                    if (_sameGrepPrev) {
+                        // Exact same-path spiral fires alone; a merely sibling/
+                        // variant path must ALSO share a pattern token to count.
+                        const _pathExact = _paths.some((a) => _sameGrepPrev.paths.some((b) => _samePath(a, b)));
+                        const _pathRel = _paths.some((a) => _sameGrepPrev.paths.some((b) => _pathsRelated(a, b)));
+                        const _tokRel = _setsOverlap(_tokens, _sameGrepPrev.tokens);
+                        _related = _pathExact || (_pathRel && _tokRel);
+                    }
+                    _sameGrepStreak = _related ? _sameGrepStreak + 1 : 1;
+                    const _label = _paths[0] || [..._tokens][0] || 'same concept';
+                    _sameGrepPrev = { paths: _paths, tokens: _tokens };
+                    if (_sameGrepStreak >= 3 && !_hintFiredThisTurn) {
+                        pushSystemReminder(`3+ consecutive grep turns on the same concept (${_label}) — reworded patterns / sibling paths are not converging. Read the relevant span (read with offset/limit) or act on what you have.`);
+                        _sameGrepStreak = 0;
+                        _sameGrepPrev = null;
                         _hintFiredThisTurn = true;
                     }
                 } else {
-                    _sameFileGrepStreak = 0;
-                    _sameFileGrepPath = null;
+                    _sameGrepStreak = 0;
+                    _sameGrepPrev = null;
                 }
             }
+            // Detector: content/context grep on X then read of X next turn — the
+            // grep context should have sufficed. Fire off the PRIOR turn's
+            // uncapped content grep, then recompute for the next turn (skip when
+            // the grep was capped via head_limit or paths-only mode).
+            {
+                if (_lastGrepContentPaths && !_hintFiredThisTurn) {
+                    const _readCall = calls.find((c) => c?.name === 'read');
+                    if (_readCall) {
+                        const _rp = _pathsOf(_readCall?.arguments?.path);
+                        // Same-file only — a sibling read is a new lookup, not a re-read.
+                        const _hit = _rp.find((p) => [..._lastGrepContentPaths].some((g) => _samePath(p, g)));
+                        if (_hit) {
+                            pushSystemReminder(`Reading ${_baseName(_hit)} right after a content grep on it — the grep context should have sufficed; answer from grep output or widen -C instead of re-reading.`);
+                            _hintFiredThisTurn = true;
+                        }
+                    }
+                }
+                const _next = new Set();
+                for (const c of _grepCalls) {
+                    const a = c?.arguments || {};
+                    const _hasCtx = a['-A'] != null || a['-B'] != null || a['-C'] != null;
+                    const _isContent = a.output_mode === 'content' || a.output_mode === 'content_with_context' || _hasCtx;
+                    const _pathsOnly = a.output_mode === 'files_with_matches' || a.output_mode === 'count';
+                    const _capped = a.head_limit != null;
+                    if (_isContent && !_pathsOnly && !_capped) {
+                        for (const p of _pathsOf(a.path)) _next.add(p);
+                    }
+                }
+                _lastGrepContentPaths = _next.size ? _next : null;
+            }
+            // Detector: read fragmentation — 2nd+ single-window read into the
+            // SAME file with offsets inside an 800-line span means the model is
+            // paging small windows across turns instead of reading one wider
+            // span (or batching {path,offset,limit}[] regions in one call).
+            {
+                for (const c of calls.filter((x) => x?.name === 'read')) {
+                    const _byPath = new Map();
+                    for (const w of _readWindows(c)) {
+                        const k = _normPath(w.path);
+                        if (!_byPath.has(k)) _byPath.set(k, []);
+                        _byPath.get(k).push(w);
+                    }
+                    for (const [k, ws] of _byPath) {
+                        if (ws.length !== 1) continue; // batched regions on one path — the good form
+                        const off = ws[0].offset;
+                        if (!Number.isFinite(off) || off <= 0) continue;
+                        let rec = _readWindowsByPath.get(k);
+                        if (!rec) {
+                            rec = { offsets: [], fired: false };
+                            _readWindowsByPath.set(k, rec);
+                            if (_readWindowsByPath.size > 32) _readWindowsByPath.delete(_readWindowsByPath.keys().next().value);
+                        }
+                        rec.offsets.push(off);
+                        if (!rec.fired && !_hintFiredThisTurn && rec.offsets.length >= 2
+                            && (Math.max(...rec.offsets) - Math.min(...rec.offsets)) <= 800) {
+                            pushSystemReminder(`Windowed reads are fragmenting ${_baseName(k)} — stop paging small windows; read ONE wider span, or batch all needed spans as {path,offset,limit}[] regions in a single call.`);
+                            rec.fired = true;
+                            _hintFiredThisTurn = true;
+                        }
+                    }
+                }
+            }
+            // Detector: read-only shell (git status/log/diff --stat, ls/dir/cat/
+            // type/Get-ChildItem) inspects state the dedicated tools cover.
+            // Nudge toward them; never blocks execution.
+            {
+                if (!_hintFiredThisTurn && calls.some((c) => c?.name === 'shell' && _isReadOnlyShellCmd(c?.arguments?.command))) {
+                    pushSystemReminder('Read-only shell (git status/log/diff --stat, ls/dir/cat/type/Get-ChildItem) inspects state the dedicated tools cover — use grep/read/list/find/code_graph; shell is for changing state or running programs.');
+                    _hintFiredThisTurn = true;
+                }
+            }
+        },
+        // Reviewer fix: a zero-tool turn must not bridge ANY cross-turn streak
+        // across non-tool turns — that would fire level-2 (or the grep/read
+        // detectors) early on a worker that paused to synthesize text mid-run.
+        resetAllReadOnlyStreak() {
+            _allReadOnlyStreak = 0;
+            _serialReadOnlyStreak = 0;
+            _sameGrepStreak = 0;
+            _sameGrepPrev = null;
+            _lastGrepContentPaths = null;
+            _identGrepStreak = 0;
+            _identGrepToken = null;
         },
-        // Reviewer fix: a zero-tool turn must not bridge the all-read-only
-        // streak across non-tool turns — that would fire level-2 early on a
-        // worker that paused to synthesize text mid-run.
-        resetAllReadOnlyStreak() { _allReadOnlyStreak = 0; },
     };
 }

package/src/runtime/agent/orchestrator/session/manager/tool-resolution.mjs

@@ -87,10 +87,10 @@ function stringToolPermissionAllowList(toolPermission) {
     return null;
 }
 
-// Read-write agent bundle: edit surface (apply_patch) WITHOUT shell/task.
-// Repo-local shell work (git/build/test/verification) is Lead-owned by
-// workflow contract; write-role agents patch files and hand verification
-// back. Only permission 'full' (no narrowing) retains shell.
+// Read-write agent bundle: full edit surface INCLUDING shell/task so
+// write-role agents can run their own verification (build/test) without
+// bouncing it back to Lead. Deploy/ship remains a workflow-level rule,
+// not a tool-surface restriction.
 const AGENT_STRING_PERMISSION_READ_WRITE_ALLOW = Object.freeze([
     'code_graph',
     'find',
@@ -99,6 +99,8 @@ const AGENT_STRING_PERMISSION_READ_WRITE_ALLOW = Object.freeze([
     'grep',
     'read',
     'apply_patch',
+    'shell',
+    'task',
     'explore',
     'search',
     'web_fetch',

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

@@ -17,6 +17,27 @@ const MAX_INT = 100000;
 // defaults to 25 lines; this is only the upper bound for caller-supplied -A/-B/-C.
 export const GREP_CONTEXT_MAX = 200;
 
+// Tighter cap for CONTEXT-MODE grep (content_with_context or explicit -A/-B/-C):
+// head_limit counts MATCH BLOCKS in that mode, so ~40 blocks is already a large
+// read. Context width itself (-A/-B/-C) is deliberately NOT special-cased —
+// explicit requests are honored up to the generic GREP_CONTEXT_MAX; total
+// output stays bounded by the block clamp, the stream line cap, and the
+// tool-output byte cap.
+export const GREP_CTX_HEAD_LIMIT_MAX = 40;
+
+// Unbounded (no offset/limit) plain full reads default to this window instead of
+// pulling the whole file; the read tool's ranged-read footer then hands the
+// caller the next offset to page with.
+export const READ_GUARD_DEFAULT_LIMIT = 800;
+
+// Best-effort clamp notice channel: stash a one-line note on the args so a
+// surfacing consumer can echo it. Underscore-prefixed; ignored by executors.
+function pushClampNotice(a, msg) {
+    if (!a || typeof a !== 'object') return;
+    if (!Array.isArray(a._clampNotices)) a._clampNotices = [];
+    a._clampNotices.push(msg);
+}
+
 // ripgrep-flavored aliases: models trained on `rg` emit short flags (-A/-B/-C),
 // long flags (--after-context / --before-context / --context), or snake/camel
 // spellings. All fold onto the canonical -A/-B/-C so a caller can write grep
@@ -154,6 +175,73 @@ function coerceIntegerString(v) {
 // tells the model exactly what to do instead.
 const RANGE_SHAPED_INT_STRING = /^\d+\s*[,\-:]\s*\d+$/;
 
+// Coerce a window arg that may arrive as a real array or a JSON-stringified
+// array ("[0, 0]") into a real array; returns null when it is neither.
+function coerceWindowArray(v) {
+    if (Array.isArray(v)) return v;
+    if (typeof v === 'string') {
+        let c = coerceShapeFlex(v);
+        // Double-encoded window strings ('"[0, 0]"') unwrap to the inner
+        // string '[0, 0]' on the first flex pass — re-run once to reach the
+        // array. Lossless: only applies when the outer layer was a JSON
+        // string wrapper.
+        if (typeof c === 'string' && c !== v) c = coerceShapeFlex(c);
+        if (Array.isArray(c)) return c;
+    }
+    return null;
+}
+
+// Absorb: offset/limit arriving as parallel arrays (or JSON-stringified
+// arrays) alongside a path[] batch — zip each window onto its file as a
+// {path,offset,limit} region object, mirroring the lossless path JSON-string
+// recovery. A length-1 window array applies to every file. Per-entry integer
+// coercion/validation then runs on the resulting region objects. Length
+// mismatches zip positionally (absorb, don't hard-error); a single path with
+// multiple windows expands into regions of that path.
+function maybeZipPathWindowArrays(a) {
+    // A single-string path also zips when the windows are ARRAYS (e.g.
+    // path:'x.mjs', offset:'[0, 100]') — coerceReadFamilyPathArg unwraps
+    // one-element path[] to a string before this runs, so without this the
+    // window string would survive to the integer guard and hard-error.
+    if (typeof a.path === 'string' && a.path
+        && (coerceWindowArray(a.offset) || coerceWindowArray(a.limit))) {
+        a.path = [a.path];
+    }
+    if (!Array.isArray(a.path) || a.path.length < 1) return;
+    if (!a.path.every((e) => typeof e === 'string')) return;
+    const offs = coerceWindowArray(a.offset);
+    const lims = coerceWindowArray(a.limit);
+    if (!offs && !lims) return;
+    const n = a.path.length;
+    const pick = (arr, i) => (arr ? (arr.length === 1 ? arr[0] : arr[i]) : undefined);
+    // Single path + multiple windows -> regions of the SAME path (the model
+    // asked for several spans of one file).
+    const k = Math.max(offs?.length || 0, lims?.length || 0);
+    if (n === 1 && k > 1) {
+        const p = a.path[0];
+        a.path = Array.from({ length: k }, (_, i) => {
+            const r = { path: p };
+            const o = pick(offs, i); if (o !== undefined && o !== null) r.offset = o;
+            const l = pick(lims, i); if (l !== undefined && l !== null) r.limit = l;
+            return r;
+        });
+        delete a.offset;
+        delete a.limit;
+        return;
+    }
+    // Positional zip. Length mismatches absorb instead of hard-erroring
+    // (seen live: 3 paths + offset "[350, 1]"): missing entries mean
+    // full-file read for that path; extra window entries are dropped.
+    a.path = a.path.map((p, i) => {
+        const r = { path: p };
+        const o = pick(offs, i); if (o !== undefined && o !== null) r.offset = o;
+        const l = pick(lims, i); if (l !== undefined && l !== null) r.limit = l;
+        return r;
+    });
+    delete a.offset;
+    delete a.limit;
+}
+
 // Mutates a[field] in place when it is a lossless integer string, then
 // validates the (possibly coerced) value against [min, max].
 function checkIntInRange(a, field, min, max, opts = {}) {
@@ -167,10 +255,16 @@ function checkIntInRange(a, field, min, max, opts = {}) {
         }
     }
     if (typeof value === 'string' && RANGE_SHAPED_INT_STRING.test(value.trim())) {
-        return `Error: builtin arg "${field}" takes a single integer; for a line range use offset+limit as separate integers or "path#L<start>-L<end>" in the path arg (got "${value}")`;
+        return `Error: "${field}" takes one integer, not a range "${value}" — use offset+limit (e.g. offset:0, limit:40)`;
+    }
+    // Soft-cap fields only: floor a fractional number (e.g. -B: 2.5) instead
+    // of erroring — intent is unambiguous for a context-line count.
+    if (opts.clamp && typeof value === 'number' && Number.isFinite(value) && !Number.isInteger(value)) {
+        value = Math.floor(value);
+        a[field] = value;
     }
     if (!isFiniteInt(value)) {
-        return `Error: builtin arg "${field}" must be a finite integer (got ${describeType(value)}); expected a single integer like 40`;
+        return `Error: "${field}" must be an integer (got ${describeType(value)}) — e.g. ${field}:40`;
     }
     // Soft-cap fields (grep -A/-B/-C/context): silently clamp out-of-range
     // instead of erroring — a model-guessed "300" for a 200-line cap is not
@@ -270,6 +364,18 @@ function guardGrep(a) {
     }
     // path/root (optional, string or string[])
     for (const k of ['path', 'root']) {
+        // Absorb JSON-stringified arrays ('["src","docs"]') like the read
+        // family does; an empty array ('[]' or []) means "no path filter" —
+        // drop the key so the search defaults to cwd instead of handing rg a
+        // literal "[]" path (parsed as an unclosed character class).
+        if (hasOwn(a, k) && typeof a[k] === 'string') {
+            const c = coerceShapeFlex(a[k].trim());
+            if (Array.isArray(c)) a[k] = c;
+        }
+        if (hasOwn(a, k) && Array.isArray(a[k]) && a[k].length === 0) {
+            delete a[k];
+            continue;
+        }
         if (hasOwn(a, k) && !isStringOrStringArray(a[k])) {
             return `Error: grep arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
         }
@@ -309,6 +415,22 @@ function guardGrep(a) {
             }
         }
     }
+    // Context-mode tightening: clamp head_limit (which counts MATCH BLOCKS)
+    // harder than the generic caps above, and note the clamp for surfacing.
+    // Only applies where the executor actually honors context flags — i.e.
+    // content_with_context, or content mode with explicit -A/-B/-C. In
+    // files_with_matches/count the context flags are ignored, so head_limit
+    // there means output lines/paths, not blocks — never clamp it.
+    const grepMode = a.output_mode || a.mode;
+    const hasExplicitCtx = ['-A', '-B', '-C', 'context'].some((k) => grepContextKeyPresent(a, k));
+    const isCountOrFiles = grepMode === 'files_with_matches' || grepMode === 'count';
+    if (!isCountOrFiles && (grepMode === 'content_with_context' || hasExplicitCtx)) {
+        const hl = Number(a.head_limit);
+        if (grepContextKeyPresent(a, 'head_limit') && Number.isFinite(hl) && hl > GREP_CTX_HEAD_LIMIT_MAX) {
+            a.head_limit = GREP_CTX_HEAD_LIMIT_MAX;
+            pushClampNotice(a, `notice: grep head_limit clamped to ${GREP_CTX_HEAD_LIMIT_MAX} match blocks (context mode)`);
+        }
+    }
     return null;
 }
 
@@ -339,18 +461,18 @@ function applyLineContextWindow(obj, labelPrefix) {
         return `Error: read arg "${labelPrefix}context" requires "${labelPrefix}line" to compute a window`;
     }
     if (typeof obj.line === 'string' && RANGE_SHAPED_INT_STRING.test(obj.line.trim())) {
-        return `Error: read arg "${labelPrefix}line" takes a single integer; for a line range use offset+limit as separate integers or "path#L<start>-L<end>" in the path arg (got "${obj.line}")`;
+        return `Error: "${labelPrefix}line" takes one integer, not a range "${obj.line}" — use offset+limit (e.g. offset:0, limit:40)`;
     }
     if (!isFiniteInt(obj.line) || obj.line < 1) {
-        return `Error: read arg "${labelPrefix}line" must be a finite integer >= 1 (got ${describeType(obj.line)}); expected a single integer like 40`;
+        return `Error: "${labelPrefix}line" must be an integer >= 1 (got ${describeType(obj.line)}) — e.g. line:40`;
     }
     let ctx = 0;
     if (hasContext) {
         if (typeof obj.context === 'string' && RANGE_SHAPED_INT_STRING.test(obj.context.trim())) {
-            return `Error: read arg "${labelPrefix}context" takes a single integer; for a line range use offset+limit as separate integers or "path#L<start>-L<end>" in the path arg (got "${obj.context}")`;
+            return `Error: "${labelPrefix}context" takes one integer, not a range "${obj.context}" — e.g. context:5`;
         }
         if (!isFiniteInt(obj.context) || obj.context < 0) {
-            return `Error: read arg "${labelPrefix}context" must be a non-negative finite integer (got ${describeType(obj.context)}); expected a single integer like 40`;
+            return `Error: "${labelPrefix}context" must be an integer >= 0 (got ${describeType(obj.context)}) — e.g. context:5`;
         }
         ctx = obj.context;
     }
@@ -361,6 +483,43 @@ function applyLineContextWindow(obj, labelPrefix) {
     return null;
 }
 
+// Item 3: an unbounded plain full read (no offset/limit/line/context/mode/n/
+// full, and a bare path with no #Lx / :line coordinate) pulls the whole file.
+// Inject a default window so large files come back capped with a next-offset
+// footer instead. Small files still return in full (limit exceeds line count);
+// explicit windows, modes, and line-spec paths are left untouched.
+function maybeCapUnboundedRead(a) {
+    // Effective path may arrive via the file_path alias; cap those the same way.
+    let pathStrs = null;
+    if (typeof a.path === 'string' && a.path.trim() !== '') {
+        pathStrs = [a.path];
+    } else if (typeof a.file_path === 'string' && a.file_path.trim() !== '') {
+        pathStrs = [a.file_path];
+    } else if (Array.isArray(a.path) && a.path.length > 0
+        && a.path.every((e) => typeof e === 'string' && e.trim() !== '')) {
+        // string[] batch: read-tool expands top-level limit uniformly onto
+        // every entry, so bare-path batches take the same default window.
+        // Region-object arrays never reach here (they carry their own
+        // windows and are rejected above when mixed with top-level limit).
+        pathStrs = a.path;
+    }
+    if (pathStrs === null) return;
+    if (a.full === true) return;
+    // symbol (and any similar body-selector) composes its own window inside the
+    // matched body — a read({path,symbol}) must never be window-truncated.
+    for (const k of ['offset', 'limit', 'line', 'context', 'n', 'mode', 'pages', 'symbol']) {
+        if (isPresent(a, k)) return;
+    }
+    // Any #Lx / :line coordinate opts the whole call out: the injected limit
+    // would override that entry's own line-spec window during per-entry
+    // normalization.
+    for (const p of pathStrs) {
+        if (p.includes('#')) return;
+        if (/:\d+(?:-\d+)?\s*$/.test(p)) return;
+    }
+    a.limit = READ_GUARD_DEFAULT_LIMIT;
+}
+
 function guardRead(a) {
     // path / file_path alias OR path may itself be array
     const hasPath = hasOwn(a, 'path') || hasOwn(a, 'file_path');
@@ -374,6 +533,9 @@ function guardRead(a) {
     if (hasOwn(a, 'path')) {
         a.path = coerceReadFamilyPathArg(a.path);
     }
+    // Absorb: parallel/JSON-stringified offset+limit arrays paired with a
+    // path[] batch — zip them into per-file region objects before validation.
+    maybeZipPathWindowArrays(a);
     // path can be string | string[] | object[]; file_path is string
     if (hasOwn(a, 'path')) {
         const p = a.path;
@@ -382,6 +544,20 @@ function guardRead(a) {
             return `Error: read arg "path" must be string, string[], or object[] (got ${describeType(p)})`;
         }
         if (Array.isArray(p)) {
+            // Absorb: a region array ({path,offset,limit}[]) carries its window
+            // per-entry; a top-level offset/limit becomes the default for any
+            // region missing its own window, then the top-level keys are dropped
+            // so they don't double-apply in the plain-read checks below.
+            const hasRegionObj = p.some((e) => e && typeof e === 'object' && !Array.isArray(e));
+            if (hasRegionObj && (isPresent(a, 'offset') || isPresent(a, 'limit'))) {
+                for (const e of p) {
+                    if (!e || typeof e !== 'object' || Array.isArray(e)) continue;
+                    if (isPresent(a, 'offset') && !isPresent(e, 'offset')) e.offset = a.offset;
+                    if (isPresent(a, 'limit') && !isPresent(e, 'limit')) e.limit = a.limit;
+                }
+                delete a.offset;
+                delete a.limit;
+            }
             for (let i = 0; i < p.length; i++) {
                 const entry = p[i];
                 if (typeof entry === 'string') continue;
@@ -400,6 +576,9 @@ function guardRead(a) {
     if (hasOwn(a, 'file_path') && !isNonEmptyString(a.file_path)) {
         return `Error: read arg "file_path" must be a non-empty string (got ${describeType(a.file_path)})`;
     }
+    // Item 3: cap unbounded full reads to a paging window (after array/region
+    // handling so batched region reads are never touched).
+    maybeCapUnboundedRead(a);
     // Read's public surface is offset/limit, but a top-level line/context pair
     // is a deterministic, lossless spelling of the same window (matching
     // read-args.mjs's internal file:line normalizer semantics); convert it
@@ -586,6 +765,19 @@ function guardCodeGraph(a) {
     if (!CODE_GRAPH_MODES.has(mode)) {
         return `Error: code_graph arg "mode" must be one of ${[...CODE_GRAPH_MODES].join('|')} (got ${JSON.stringify(a.mode)})`;
     }
+    // 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 path.
+    for (const k of ['file', 'files']) {
+        if (hasOwn(a, k) && typeof a[k] === 'string') {
+            const c = coerceShapeFlex(a[k]);
+            if (Array.isArray(c)) a[k] = c;
+        }
+    }
+    if (Array.isArray(a.file)) {
+        a.files = Array.isArray(a.files) ? [...a.file, ...a.files] : a.file;
+        delete a.file;
+    }
     return null;
 }