mixdog 0.7.1

package/src/agent/orchestrator/tools/builtin/advisory-lock.mjs

@@ -0,0 +1,171 @@
+// Cross-process advisory lock for write/edit operations. Uses a sibling
+// lockfile written exclusively (`wx`) and a process.kill(pid, 0) liveness
+// check to clean up after crashed holders. Pair with the in-process
+// withPathLock for the same target: in-process serialises async callers
+// in this Node, advisory lock serialises across Node processes.
+import { openSync, closeSync, writeSync, readFileSync, unlinkSync, mkdirSync } from 'fs';
+import { dirname, basename, join } from 'path';
+import { randomBytes } from 'crypto';
+
+function lockFileFor(targetPath) {
+    return join(dirname(targetPath), `.${basename(targetPath)}.mixdog-lock`);
+}
+
+function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    // Triple-check: process.kill(pid, 0) can return transient ESRCH under
+    // heavy multi-process spawn pressure on Windows even when the target
+    // process is actually alive. Any one of three rapid probes returning
+    // success (or EPERM = exists-but-no-access) classifies as alive. Three
+    // consecutive ESRCH replies classify as dead. Each probe is a single
+    // syscall (microseconds) so total cost is negligible vs the race risk.
+    for (let i = 0; i < 3; i += 1) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        } catch (err) {
+            if (err && err.code === 'EPERM') return true;
+            // ESRCH or other → continue probing.
+        }
+    }
+    return false;
+}
+
+function readLockInfo(lockFile) {
+    try {
+        const raw = readFileSync(lockFile, 'utf-8').trim();
+        // Token format: `${pid}.${hex}`. Fall back to legacy bare-pid contents.
+        const dot = raw.indexOf('.');
+        if (dot > 0) {
+            const pid = parseInt(raw.slice(0, dot), 10);
+            return { pid: Number.isInteger(pid) ? pid : 0, token: raw };
+        }
+        const pid = parseInt(raw, 10);
+        return { pid: Number.isInteger(pid) ? pid : 0, token: raw };
+    } catch {
+        return { pid: 0, token: '' };
+    }
+}
+
+function unlinkIfOwned(lockFile, expectedToken) {
+    try {
+        const { token } = readLockInfo(lockFile);
+        if (token !== expectedToken) return false;
+        unlinkSync(lockFile);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function tryCreateLock(lockFile, token) {
+    let fd;
+    try {
+        fd = openSync(lockFile, 'wx');
+    } catch (err) {
+        if (err && err.code === 'EEXIST') return false;
+        throw err;
+    }
+    // Once the lockfile exists on disk, any failure in writeSync/closeSync
+    // would leak the lockfile if we returned without cleanup.
+    try {
+        writeSync(fd, token);
+        closeSync(fd);
+    } catch (err) {
+        try { closeSync(fd); } catch { /* fd may already be closed */ }
+        try { unlinkSync(lockFile); } catch { /* best-effort cleanup */ }
+        throw err;
+    }
+    return true;
+}
+
+export async function acquireAdvisoryLock(targetPath, { timeoutMs = 5000, pollMs = 25 } = {}) {
+    const lockFile = lockFileFor(targetPath);
+    // Ensure parent directory exists before openSync('wx'); the lockfile lives
+    // next to the target, so writes to new files in missing parent dirs would
+    // otherwise fail with ENOENT here.
+    mkdirSync(dirname(lockFile), { recursive: true });
+    const token = `${process.pid}.${randomBytes(8).toString('hex')}`;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (tryCreateLock(lockFile, token)) {
+            return {
+                lockFile,
+                release() {
+                    // Verify ownership token before unlinking to avoid
+                    // unlinking another process's live lock after a stale
+                    // cleanup race.
+                    unlinkIfOwned(lockFile, token);
+                },
+            };
+        }
+        // Lock exists — check liveness for stale cleanup.
+        const { pid: holderPid, token: holderToken } = readLockInfo(lockFile);
+        if (!isPidAlive(holderPid)) {
+            // DOUBLE-CHECK: under heavy multi-process load, process.kill(pid,0)
+            // can return false-negative (transient ESRCH) for an active
+            // holder, causing this branch to unlink an in-use lock and break
+            // mutual exclusion. Verified empirically by s13 stress test —
+            // two workers were observed holding the same lock for 119ms.
+            //
+            // Mitigation: re-read the lockfile after a short delay; if pid
+            // or token changed, another contender already handled cleanup
+            // and we should re-poll. Otherwise re-test liveness; only when
+            // BOTH checks agree the holder is dead do we cleanup. The
+            // sleep also absorbs the OS-level race window where the
+            // original kill(0) returned ESRCH before the holder fully
+            // exited the spawn/registration window.
+            await new Promise((r) => setTimeout(r, 50));
+            const second = readLockInfo(lockFile);
+            if (second.pid !== holderPid || second.token !== holderToken) {
+                // Another contender already touched the lock; resync.
+                continue;
+            }
+            if (!isPidAlive(holderPid)) {
+                unlinkIfOwned(lockFile, holderToken);
+                // Small jitter to avoid avalanche of contenders racing into
+                // tryCreateLock simultaneously after the unlink.
+                await new Promise((r) => setTimeout(r, Math.floor(Math.random() * 5) + 1));
+            }
+            continue;
+        }
+        if (Date.now() >= deadline) {
+            const err = new Error(`advisory lock timeout: ${lockFile} held by pid ${holderPid}`);
+            err.code = 'EAGAIN';
+            throw err;
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+}
+
+export async function withAdvisoryLocks(paths, fn) {
+    const seen = new Set();
+    const ordered = [];
+    for (const p of Array.isArray(paths) ? paths : [paths]) {
+        if (!p) continue;
+        const key = process.platform === 'win32' ? String(p).toLowerCase() : String(p);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        ordered.push(String(p));
+    }
+    // Acquire in a casing-canonical order so two callers locking the same set
+    // with different path casing on Windows cannot acquire in opposite orders
+    // and deadlock. (The dedup above already keys on the canonical form.)
+    const _lockSortKey = (s) => (process.platform === 'win32' ? s.toLowerCase() : s);
+    ordered.sort((a, b) => {
+        const ka = _lockSortKey(a), kb = _lockSortKey(b);
+        return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+    const acquired = [];
+    try {
+        for (const p of ordered) {
+            acquired.push(await acquireAdvisoryLock(p));
+        }
+        return await fn();
+    } finally {
+        // Release in reverse acquisition order.
+        for (let i = acquired.length - 1; i >= 0; i -= 1) {
+            try { acquired[i].release(); } catch { /* best-effort */ }
+        }
+    }
+}

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

@@ -0,0 +1,455 @@
+// Lightweight argument shape validator for builtin tools.
+//
+// Goal: catch obvious schema violations (wrong types, missing required
+// fields, out-of-range numeric clamps) BEFORE the underlying executor
+// touches them and crashes the MCP child. Returns null on success, or
+// a clean human-readable error string on failure (never throws).
+//
+// Validation operates on the alias family, not the canonical key, so
+// callers may pass either spelling (e.g. `glob` alias for grep, or
+// `file_path` alias for read.path).
+
+const MAX_INT = 100000;
+export const GREP_CONTEXT_MAX = 12;
+
+const GREP_CONTEXT_KEY_GROUPS = [
+    ['-A', ['-A', 'A', 'after', 'after_context', 'afterContext']],
+    ['-B', ['-B', 'B', 'before', 'before_context', 'beforeContext']],
+    ['-C', ['-C', 'C', 'context', 'context_lines', 'contextLines']],
+];
+
+function grepContextKeyPresent(a, k) {
+    return a && Object.prototype.hasOwnProperty.call(a, k)
+        && a[k] !== undefined && a[k] !== null && a[k] !== '';
+}
+
+function firstGrepContextArg(args, keys) {
+    for (const k of keys) {
+        if (grepContextKeyPresent(args, k)) return { key: k, value: args[k] };
+    }
+    return null;
+}
+
+function firstNonZeroGrepContextArg(args, keys) {
+    for (const k of keys) {
+        if (grepContextKeyPresent(args, k) && !isGrepContextZero(args[k])) return { key: k, value: args[k] };
+    }
+    return null;
+}
+
+function isGrepContextZero(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n === 0;
+}
+
+function clearGrepContextKeys(args, keys) {
+    for (const k of keys) delete args[k];
+}
+
+/** Lead-facing grep context: canonicalize aliases and clamp explicit values (overrides still apply). */
+export function applyGrepContextLeadPolicy(args) {
+    if (!args || typeof args !== 'object' || Array.isArray(args)) return;
+    for (const [canonical, keys] of GREP_CONTEXT_KEY_GROUPS) {
+        const found = firstNonZeroGrepContextArg(args, keys) || firstGrepContextArg(args, keys);
+        if (!found) continue;
+        const n = Number(found.value);
+        const shaped = Number.isFinite(n) && n > GREP_CONTEXT_MAX ? GREP_CONTEXT_MAX : found.value;
+        clearGrepContextKeys(args, keys);
+        args[canonical] = shaped;
+    }
+}
+
+function isString(v) {
+    return typeof v === 'string';
+}
+
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.length > 0;
+}
+
+function isStringOrStringArray(v) {
+    if (typeof v === 'string') return true;
+    if (!Array.isArray(v) || v.length === 0) return false;
+    for (const x of v) {
+        if (typeof x !== 'string') return false;
+    }
+    return true;
+}
+
+function isFiniteInt(v) {
+    return typeof v === 'number' && Number.isFinite(v) && Math.floor(v) === v;
+}
+
+function checkIntInRange(field, value, min, max) {
+    if (value === undefined || value === null) return null;
+    if (!isFiniteInt(value)) {
+        return `Error: builtin arg "${field}" must be a finite integer (got ${describeType(value)})`;
+    }
+    if (value < min) {
+        return `Error: builtin arg "${field}" must be >= ${min} (got ${value})`;
+    }
+    if (value > max) {
+        return `Error: builtin arg "${field}" must be <= ${max} (got ${value})`;
+    }
+    return null;
+}
+
+function describeType(v) {
+    if (v === null) return 'null';
+    if (Array.isArray(v)) return 'array';
+    return typeof v;
+}
+
+function hasOwn(o, k) {
+    return o && Object.prototype.hasOwnProperty.call(o, k);
+}
+
+// ---- per-tool guards ----
+
+function guardGrep(a) {
+    // pattern aliases
+    const patternKeys = ['pattern', 'query', 'regex', 'needle'];
+    // glob (file filter) aliases
+    const globKeys = ['glob', 'file_pattern', 'include', 'files'];
+
+    const hasPattern = patternKeys.some((k) => hasOwn(a, k));
+    const hasGlob = globKeys.some((k) => hasOwn(a, k));
+    if (!hasPattern && !hasGlob) {
+        return 'Error: grep requires pattern (or alias query/regex/needle) or glob.';
+    }
+    for (const k of patternKeys) {
+        if (hasOwn(a, k) && !isStringOrStringArray(a[k])) {
+            return `Error: grep arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
+        }
+    }
+    for (const k of globKeys) {
+        if (hasOwn(a, k) && !isStringOrStringArray(a[k])) {
+            return `Error: grep arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
+        }
+    }
+    // path/root (optional, string or string[])
+    for (const k of ['path', 'root']) {
+        if (hasOwn(a, k) && !isStringOrStringArray(a[k])) {
+            return `Error: grep arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
+        }
+    }
+    // numeric clamps (grep context 0..12, mirrors read line-context tightening)
+    for (const k of ['head_limit', 'offset']) {
+        const err = checkIntInRange(k, a[k], 0, MAX_INT);
+        if (err) return err;
+    }
+    for (const k of ['-A', '-B', '-C', 'context']) {
+        const err = checkIntInRange(k, a[k], 0, GREP_CONTEXT_MAX);
+        if (err) return err;
+    }
+    // output_mode / mode enum
+    const modeKeys = ['output_mode', 'mode'];
+    const allowed = new Set(['files_with_matches', 'content', 'count']);
+    for (const k of modeKeys) {
+        if (hasOwn(a, k)) {
+            if (!isString(a[k]) || !allowed.has(a[k])) {
+                return `Error: grep arg "${k}" must be one of files_with_matches|content|count (got ${JSON.stringify(a[k])})`;
+            }
+        }
+    }
+    return null;
+}
+
+function guardRead(a) {
+    // path / file_path alias OR path may itself be array
+    const hasPath = hasOwn(a, 'path') || hasOwn(a, 'file_path');
+    if (!hasPath) {
+        return 'Error: read requires "path" (or alias file_path).';
+    }
+    // path can be string | string[] | object[]; file_path is string
+    if (hasOwn(a, 'path')) {
+        const p = a.path;
+        const ok = typeof p === 'string' || (Array.isArray(p) && p.length > 0);
+        if (!ok) {
+            return `Error: read arg "path" must be string, string[], or object[] (got ${describeType(p)})`;
+        }
+    }
+    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)})`;
+    }
+    // offset >=0
+    {
+        const err = checkIntInRange('offset', a.offset, 0, MAX_INT);
+        if (err) return err;
+    }
+    // limit: >=1 = explicit cap; 0 = unlimited sentinel (read-formatting maps 0 to
+    // Infinity; read-batch coalescing forwards limit:0 for an unbounded union
+    // window). Allow 0 through rather than erroring — deleting/rejecting it would
+    // break that unbounded-batch contract. A placeholder limit:0 from a symbol
+    // read is stripped on the symbol path. Negatives still error.
+    {
+        const err = checkIntInRange('limit', a.limit, 0, MAX_INT);
+        if (err) return err;
+    }
+    // context 0..200
+    {
+        const err = checkIntInRange('context', a.context, 0, 200);
+        if (err) return err;
+    }
+    // n 0..10000 — accept 0 rather than erroring: the read-mode handlers coerce
+    // n<1 to their default (head/tail 20, summary 200), and when a window
+    // (offset/limit/line) is also present the glance mode is dropped entirely, so
+    // n is moot. Rejecting 0 only forced a wasted retry turn (the whole point of
+    // these reads is to land in one shot). Negatives remain a real error.
+    if (hasOwn(a, 'n') && a.n !== undefined && a.n !== null) {
+        const err = checkIntInRange('n', a.n, 0, 10000);
+        if (err) return err;
+    }
+    return null;
+}
+
+function guardEdit(a) {
+    const op = hasOwn(a, 'operation') ? a.operation : 'replace';
+    if (op !== undefined && op !== null) {
+        if (!isString(op) || (op !== 'replace' && op !== 'notebook' && op !== 'rename')) {
+            return `Error: edit arg "operation" must be one of replace|notebook|rename (got ${JSON.stringify(op)})`;
+        }
+    }
+    if (op === 'notebook') {
+        return guardNotebookEdit(a);
+    }
+    if (op === 'rename') {
+        return guardRename(a);
+    }
+    const hasSingle = hasOwn(a, 'old_string') && hasOwn(a, 'new_string');
+    const hasBatch = hasOwn(a, 'edits') && Array.isArray(a.edits) && a.edits.length > 0;
+    if (hasSingle && hasBatch) {
+        return 'Error: edit requires either (old_string + new_string) OR edits[], not both';
+    }
+    if (!hasSingle && !hasBatch) {
+        if (hasOwn(a, 'edits') && !hasBatch) {
+            return 'Error: edit arg "edits" must be a non-empty array';
+        }
+        return 'Error: edit requires either (old_string + new_string) OR a non-empty edits[]';
+    }
+    if (hasSingle) {
+        if (typeof a.old_string !== 'string') {
+            return `Error: edit arg "old_string" must be a string (got ${describeType(a.old_string)})`;
+        }
+        if (typeof a.new_string !== 'string') {
+            return `Error: edit arg "new_string" must be a string (got ${describeType(a.new_string)})`;
+        }
+    }
+    return null;
+}
+
+function guardWrite(a) {
+    const hasSingle = (hasOwn(a, 'path') || hasOwn(a, 'file_path')) && hasOwn(a, 'content');
+    const hasBatch = hasOwn(a, 'writes') && Array.isArray(a.writes) && a.writes.length > 0;
+    if (hasSingle && hasBatch) {
+        return 'Error: write requires either (path + content) OR writes[], not both';
+    }
+    if (!hasSingle && !hasBatch) {
+        if (hasOwn(a, 'writes') && !hasBatch) {
+            return 'Error: write arg "writes" must be a non-empty array';
+        }
+        return 'Error: write requires either (path + content) OR a non-empty writes[]';
+    }
+    if (hasSingle) {
+        const p = hasOwn(a, 'path') ? a.path : a.file_path;
+        if (typeof p !== 'string' || !p) {
+            return `Error: write arg "path" must be a non-empty string (got ${describeType(p)})`;
+        }
+        if (typeof a.content !== 'string') {
+            return `Error: write arg "content" must be a string (got ${describeType(a.content)})`;
+        }
+    }
+    if (hasBatch) {
+        for (let i = 0; i < a.writes.length; i++) {
+            const w = a.writes[i];
+            if (!w || typeof w !== 'object') {
+                return `Error: write writes[${i}] must be an object with path + content`;
+            }
+            if (typeof w.path !== 'string' || !w.path) {
+                return `Error: write writes[${i}].path must be a non-empty string (got ${describeType(w.path)})`;
+            }
+            if (typeof w.content !== 'string') {
+                return `Error: write writes[${i}].content must be a string (got ${describeType(w.content)})`;
+            }
+        }
+    }
+    return null;
+}
+
+function guardNotebookEdit(a) {
+    const hasPath = hasOwn(a, 'notebook_path') || hasOwn(a, 'path') || hasOwn(a, 'file_path');
+    if (!hasPath) {
+        return 'Error: notebook_edit requires "notebook_path" (or alias path/file_path).';
+    }
+    for (const k of ['notebook_path', 'path', 'file_path']) {
+        if (hasOwn(a, k) && !isNonEmptyString(a[k])) {
+            return `Error: notebook_edit arg "${k}" must be a non-empty string (got ${describeType(a[k])})`;
+        }
+    }
+    const editMode = hasOwn(a, 'edit_mode') ? a.edit_mode : 'replace';
+    if (editMode !== undefined && editMode !== null) {
+        const allowedModes = new Set(['replace', 'insert', 'delete']);
+        if (!isString(editMode) || !allowedModes.has(editMode)) {
+            return `Error: notebook_edit arg "edit_mode" must be one of replace|insert|delete (got ${JSON.stringify(editMode)})`;
+        }
+    }
+    if (hasOwn(a, 'cell_type') && a.cell_type !== undefined && a.cell_type !== null) {
+        if (!isString(a.cell_type) || (a.cell_type !== 'code' && a.cell_type !== 'markdown')) {
+            return `Error: notebook_edit arg "cell_type" must be code or markdown (got ${JSON.stringify(a.cell_type)})`;
+        }
+    }
+    if (hasOwn(a, 'cell_id') && a.cell_id !== undefined && a.cell_id !== null && !isString(a.cell_id)) {
+        return `Error: notebook_edit arg "cell_id" must be a string (got ${describeType(a.cell_id)})`;
+    }
+    // new_source is required except for delete; the executor enforces the
+    // mode-specific requirement, but reject a non-string up front when present.
+    if (hasOwn(a, 'new_source') && a.new_source !== undefined && a.new_source !== null && typeof a.new_source !== 'string') {
+        return `Error: notebook_edit arg "new_source" must be a string (got ${describeType(a.new_source)})`;
+    }
+    return null;
+}
+
+function guardDiagnostics(a) {
+    if (hasOwn(a, 'path') && a.path !== undefined && a.path !== null && !isNonEmptyString(a.path)) {
+        return `Error: diagnostics arg "path" must be a non-empty string (got ${describeType(a.path)})`;
+    }
+    return null;
+}
+
+function guardRename(a) {
+    if (!hasOwn(a, 'symbol') || !isNonEmptyString(a.symbol)) {
+        return `Error: rename requires "symbol" (non-empty string) (got ${describeType(a.symbol)})`;
+    }
+    if (!hasOwn(a, 'new_name') || !isNonEmptyString(a.new_name)) {
+        return `Error: rename requires "new_name" (non-empty string) (got ${describeType(a.new_name)})`;
+    }
+    if (hasOwn(a, 'file') && a.file !== undefined && a.file !== null && !isNonEmptyString(a.file)) {
+        return `Error: rename arg "file" must be a non-empty string (got ${describeType(a.file)})`;
+    }
+    if (hasOwn(a, 'apply') && a.apply !== undefined && a.apply !== null && typeof a.apply !== 'boolean') {
+        return `Error: rename arg "apply" must be a boolean (got ${describeType(a.apply)})`;
+    }
+    return null;
+}
+
+function guardBash(a) {
+    if (!hasOwn(a, 'command')) {
+        return 'Error: bash requires "command"';
+    }
+    if (typeof a.command !== 'string') {
+        return `Error: bash arg "command" must be a string (got ${describeType(a.command)})`;
+    }
+    if (a.command.length === 0) {
+        return 'Error: bash arg "command" must be a non-empty string';
+    }
+    return null;
+}
+
+function guardJobWait(a) {
+    if (!hasOwn(a, 'job_id')) {
+        return 'Error: job_wait requires "job_id"';
+    }
+    if (typeof a.job_id !== 'string') {
+        return `Error: job_wait arg "job_id" must be a string (got ${describeType(a.job_id)})`;
+    }
+    return null;
+}
+
+function guardList(a) {
+    if (hasOwn(a, 'path') && !isStringOrStringArray(a.path)) {
+        return `Error: list arg "path" must be string or string[] (got ${describeType(a.path)})`;
+    }
+    if (hasOwn(a, 'pattern') && !isStringOrStringArray(a.pattern)) {
+        return `Error: list arg "pattern" must be string or string[] (got ${describeType(a.pattern)})`;
+    }
+    if (hasOwn(a, 'head_limit') && a.head_limit !== undefined && a.head_limit !== null) {
+        if (!isFiniteInt(a.head_limit)) {
+            return `Error: list arg "head_limit" must be a finite integer (got ${describeType(a.head_limit)})`;
+        }
+        // 0 is the valid "no cap" sentinel; a negative value is nonsensical
+        // and downstream produces a degenerate window (clamps to 0 → empty).
+        if (a.head_limit < 0) {
+            return `Error: list arg "head_limit" must be >= 0 (0 means no cap); got ${a.head_limit}`;
+        }
+    }
+    return null;
+}
+
+function guardGlob(a) {
+    // path alias root; pattern aliases glob/name/file_pattern
+    for (const k of ['path', 'root']) {
+        if (hasOwn(a, k) && !isStringOrStringArray(a[k])) {
+            return `Error: glob arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
+        }
+    }
+    for (const k of ['pattern', 'glob', 'name', 'file_pattern']) {
+        if (hasOwn(a, k) && !isStringOrStringArray(a[k])) {
+            return `Error: glob arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
+        }
+    }
+    if (hasOwn(a, 'head_limit') && a.head_limit !== undefined && a.head_limit !== null) {
+        if (!isFiniteInt(a.head_limit)) {
+            return `Error: glob arg "head_limit" must be a finite integer (got ${describeType(a.head_limit)})`;
+        }
+        // 0 is the valid "no cap" sentinel; a negative value is nonsensical
+        // and downstream produces a degenerate window (clamps to 0 → empty).
+        if (a.head_limit < 0) {
+            return `Error: glob arg "head_limit" must be >= 0 (0 means no cap); got ${a.head_limit}`;
+        }
+    }
+    return null;
+}
+
+// Valid code_graph modes — mirrors the enum in code-graph-tool-defs.mjs.
+// Covers the work the removed standalone find_* tools used to do:
+// find_symbol, references, callers, imports, dependents.
+const CODE_GRAPH_MODES = new Set([
+    'overview', 'imports', 'dependents', 'related', 'impact',
+    'symbols', 'find_symbol', 'search', 'references', 'callers', 'callees', 'prewarm',
+]);
+
+function guardCodeGraph(a) {
+    if (!hasOwn(a, 'mode') || a.mode === undefined || a.mode === null) {
+        return 'Error: code_graph requires "mode"';
+    }
+    if (!isString(a.mode)) {
+        return `Error: code_graph arg "mode" must be a string (got ${describeType(a.mode)})`;
+    }
+    const mode = a.mode.trim();
+    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)})`;
+    }
+    return null;
+}
+
+const GUARDS = {
+    grep: guardGrep,
+    read: guardRead,
+    edit: guardEdit,
+    write: guardWrite,
+    diagnostics: guardDiagnostics,
+    bash: guardBash,
+    job_wait: guardJobWait,
+    list: guardList,
+    glob: guardGlob,
+    code_graph: guardCodeGraph,
+};
+
+export function validateBuiltinArgs(toolName, args) {
+    const guard = GUARDS[toolName];
+    if (!guard) return null;
+    if (args === null || args === undefined) {
+        return `Error: ${toolName} requires arguments object (got ${describeType(args)})`;
+    }
+    if (typeof args !== 'object' || Array.isArray(args)) {
+        return `Error: ${toolName} arguments must be an object (got ${describeType(args)})`;
+    }
+    if (toolName === 'grep') applyGrepContextLeadPolicy(args);
+    try {
+        return guard(args) || null;
+    } catch (err) {
+        return `Error: ${toolName} argument validation failed: ${err && err.message ? err.message : String(err)}`;
+    }
+}
+
+export default validateBuiltinArgs;