mixdog 0.9.1 → 0.9.3

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

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

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

@@ -17,7 +17,7 @@ export const BUILTIN_TOOLS = [
         name: 'read',
         title: 'Mixdog Read',
         annotations: { title: 'Mixdog Read', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false },
-        description: 'Read known file path(s). Use line+context for small windows. Batch paths.',
+        description: 'Read known file path(s). Prefer grep content_with_context or code_graph anchors first. Window with numeric offset+limit only. Batch paths/regions as real arrays; adjacent spans in one file = one window, not repeated calls. Dirs use list.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -26,14 +26,26 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         {
                             type: 'array',
-                            items: { type: 'string' },
+                            items: {
+                                anyOf: [
+                                    { type: 'string' },
+                                    {
+                                        type: 'object',
+                                        properties: {
+                                            path: { type: 'string' },
+                                            offset: { type: 'number', minimum: 0 },
+                                            limit: { type: 'number', minimum: 1 },
+                                        },
+                                    },
+                                ],
+                            },
                             minItems: 1,
                         },
                     ],
-                    description: 'File path or array. Dirs use list.',
+                    description: 'File path, path[], or {path,offset,limit}[] region objects. Pass arrays directly; JSON strings are legacy recovery only.',
                 },
-                line: { type: 'number', minimum: 1, description: 'Anchor line.' },
-                context: { type: 'number', minimum: 0, maximum: 200, description: 'Lines around line; max 200.' },
+                offset: { type: 'number', minimum: 0, description: 'Numeric lines to skip before reading; 0 starts at line 1. Continue with offset:N.' },
+                limit: { type: 'number', minimum: 1, description: 'Numeric max lines to return after offset.' },
             },
         },
     },
@@ -53,7 +65,10 @@ export const BUILTIN_TOOLS = [
     {
         name: 'open_config',
         title: 'Open Config UI',
-        annotations: { title: 'Open Config UI', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        // agentHidden: a worker/reviewer session has no business popping the
+        // settings UI on the user's machine; it also wastes schema bytes on
+        // every agent request. Lead keeps it.
+        annotations: { title: 'Open Config UI', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false, agentHidden: true },
         description: 'Open settings UI; returns URL. No params.',
         inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     },
@@ -61,7 +76,7 @@ export const BUILTIN_TOOLS = [
         name: 'shell',
         title: 'Mixdog Shell',
         annotations: { title: 'Mixdog Shell', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, compressible: true },
-        description: `Run shell for git/build/test/run. Not for source browsing; use code_graph/grep/read/list/glob. Set shell: powershell or bash. ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
+        description: `Run shell to CHANGE state or RUN programs (git/build/test/run). Never to inspect the filesystem — reading, listing, searching, or checking existence go through the dedicated tools, never a shell command. Set shell: powershell or bash. ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -101,7 +116,7 @@ export const BUILTIN_TOOLS = [
         name: 'grep',
         title: 'Mixdog Grep',
         annotations: { title: 'Mixdog Grep', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Search text/logs/regex.',
+        description: 'Search file contents by text/regex in a known scope. Use files_with_matches/count for broad anchors, content_with_context for narrow code answers. One concept → one grep.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -110,19 +125,20 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Text/regex. Array = OR.',
+                    description: 'Text/regex. Put synonyms in pattern[] as OR in ONE grep; no serial rewording or equivalent repeats.',
                 },
-                path: { type: 'string', description: 'File or directory.' },
+                path: { type: 'string', description: 'Known narrowest file/dir; broad scopes return paths first, then refine from returned paths.' },
                 glob: {
                     anyOf: [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Optional narrowing glob(s).',
+                    description: 'Narrow in same grep; no follow-up grep for equivalent scope changes.',
                 },
-                output_mode: { type: 'string', enum: ['files_with_matches', 'content', 'count'], description: 'Output mode.' },
-                head_limit: { type: 'number', description: 'Max lines.' },
-                offset: { type: 'number', description: 'Skip lines.' },
+                output_mode: { type: 'string', enum: ['content_with_context', 'content', 'files_with_matches', 'count'], description: 'Broad scope: files_with_matches/count. Narrow scope: content_with_context; answer from it, skip read unless span is not shown.' },
+                context: { type: 'number', minimum: 0, description: 'Lines before/after each match; keep bounded.' },
+                head_limit: { type: 'number', minimum: 0, description: 'Max output lines; keep small.' },
+                offset: { type: 'number', minimum: 0, description: 'Skip output lines for paging.' },
             },
             required: [],
         },
@@ -131,7 +147,7 @@ export const BUILTIN_TOOLS = [
         name: 'glob',
         title: 'Mixdog Glob',
         annotations: { title: 'Mixdog Glob', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Find files by glob.',
+        description: 'Find files by exact glob. Unknown path/name uses find.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -140,7 +156,7 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Glob pattern(s).',
+                    description: 'Exact glob pattern(s).',
                 },
                 path: {
                     anyOf: [
@@ -159,11 +175,11 @@ export const BUILTIN_TOOLS = [
         name: 'find',
         title: 'Mixdog Find Files',
         annotations: { title: 'Mixdog Find Files', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Fuzzy-find files by partial path/name. Returns paths.',
+        description: 'Find files by partial path/name. Exact structure uses glob. Returns verified paths.',
         inputSchema: {
             type: 'object',
             properties: {
-                query: { type: 'string', description: 'Partial path/name words.' },
+                query: { type: 'string', description: 'Partial path/name words; not file contents.' },
                 path: { type: 'string', description: 'Base directory.' },
                 head_limit: { type: 'number', description: 'Max paths.' },
             },

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

@@ -0,0 +1,241 @@
+// Native adapters for well-known tool names from OTHER agent CLIs whose
+// argument shapes differ from any mixdog builtin (StrReplace/Write/bash
+// variants). Executed directly against the filesystem via atomicWrite / the
+// existing shell runner — NOT by synthesizing an apply_patch V4A string
+// (that approach was tried and abandoned: building a correct V4A envelope
+// from arbitrary old_string/new_string/contents blew up in edge-case
+// complexity for no benefit over a direct fs edit).
+//
+// Contract: tryExecuteExternalToolAdapter(name, args, workDir, options)
+// returns a result STRING when the call was handled (success or a concrete
+// tool-level error), or `null` when the args shape didn't match what the
+// adapter expects — the caller (builtin.mjs default: case) falls back to
+// the existing EXTERNAL_TOOL_REDIRECTS guidance message in that case.
+import { readFileSync, mkdirSync, existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
+import { dirname, sep } from 'node:path';
+import { atomicWrite } from './atomic-write.mjs';
+import { assertPathsReachable } from './fs-reachability.mjs';
+import { normalizeInputPath, resolveAgainstCwd, normalizeOutputPath } from './path-utils.mjs';
+import { isUncPath, isWindowsDevicePath, hasUnsafeWin32Component, isBlockedDevicePath, isSpecialFileStat } from './device-paths.mjs';
+import { executeBashTool } from './bash-tool.mjs';
+import { invalidateBuiltinResultCache } from './cache-layers.mjs';
+import { markCodeGraphDirtyPaths } from '../code-graph-state.mjs';
+
+const STR_REPLACE_NAMES = new Set(['strreplace', 'str_replace', 'str_replace_editor', 'search_replace']);
+const WRITE_NAMES = new Set(['write', 'create_file', 'createfile']);
+// 'bash'/'Bash' explicitly request the posix/git-bash shell kind; the
+// run/runcommand/terminal/run_terminal_cmd family leaves `shell` unset so
+// executeBashTool's own default-shell resolution applies (mirrors how the
+// native `shell` tool behaves when the caller omits `shell`).
+const BASH_SHELL_KIND_NAMES = new Set(['bash']);
+const BASH_DEFAULT_NAMES = new Set(['run', 'runcommand', 'terminal', 'run_terminal_cmd']);
+
+/**
+ * True when `name` is a foreign-CLI tool this module can adapt natively.
+ * Used by the session loop's dispatch so these names route INTO
+ * executeBuiltinTool (whose default: case invokes the adapter) instead of
+ * short-circuiting to the unknown-tool redirect message.
+ */
+export function isExternalAdapterTool(name) {
+    if (typeof name !== 'string' || !name) return false;
+    const key = name.toLowerCase();
+    return STR_REPLACE_NAMES.has(key) || WRITE_NAMES.has(key)
+        || BASH_SHELL_KIND_NAMES.has(key) || BASH_DEFAULT_NAMES.has(key);
+}
+
+// Same write-target guards the read/list surfaces enforce (UNC → NTLM hash
+// leak, device namespace → raw device access / hang, trailing-dot / ADS →
+// device-guard bypass). Writes are strictly more dangerous than reads, so
+// every adapter write path must run these on both the normalized input and
+// the fully resolved path. Returns an Error string or null.
+function guardWritePath(p) {
+    if (isUncPath(p))
+        return `Error: cannot write UNC / SMB path (network credential leak risk): ${normalizeOutputPath(p)}`;
+    if (isWindowsDevicePath(p))
+        return `Error: cannot write Windows device path (reserved name or raw-device namespace): ${normalizeOutputPath(p)}`;
+    if (hasUnsafeWin32Component(p))
+        return `Error: cannot write Windows path with trailing dot/space or NTFS ADS suffix (bypasses device guard): ${normalizeOutputPath(p)}`;
+    if (isBlockedDevicePath(p))
+        return `Error: cannot write device file (would block or corrupt a device): ${normalizeOutputPath(p)}`;
+    return null;
+}
+
+// Realpath to the nearest existing ancestor (create-mode leaves don't exist
+// yet). Returns { probe, real } or null when nothing on the path exists /
+// realpath itself fails.
+function realpathNearestExisting(fullPath) {
+    let probe = fullPath;
+    while (probe && !existsSync(probe)) {
+        const parent = dirname(probe);
+        if (!parent || parent === probe) return null;
+        probe = parent;
+    }
+    if (!probe || !existsSync(probe)) return null;
+    try { return { probe, real: realpathSync(probe) }; } catch { return null; }
+}
+
+// Realpath-based guard: a symlink/junction in the target (or its nearest
+// existing ancestor, for create-mode paths) can point at a UNC share or a
+// device namespace that the lexical checks above never see. Mirrors the
+// realpath verification apply_patch runs on every header. Returns an Error
+// string or null; never throws.
+function guardRealTarget(fullPath) {
+    const nearest = realpathNearestExisting(fullPath);
+    if (nearest && nearest.real !== nearest.probe) {
+        const guardErr = guardWritePath(nearest.real);
+        if (guardErr) return `${guardErr} (symlink target of ${normalizeOutputPath(nearest.probe)})`;
+    }
+    try {
+        const lst = lstatSync(fullPath);
+        if (lst.isSymbolicLink()) {
+            const realTarget = realpathSync(fullPath);
+            const linkGuardErr = guardWritePath(realTarget);
+            if (linkGuardErr) return `${linkGuardErr} (symlink target of ${normalizeOutputPath(fullPath)})`;
+        }
+        // statSync FOLLOWS a leaf symlink, so a link pointing at a custom
+        // FIFO/socket/char/block inode trips here too (lstat alone only saw
+        // the link inode itself).
+        const st = statSync(fullPath);
+        if (isSpecialFileStat(st))
+            return `Error: cannot write special file (FIFO / character / block device / socket): ${normalizeOutputPath(fullPath)}`;
+    } catch { /* ENOENT (create mode) — nothing to check */ }
+    return null;
+}
+
+// Write containment — mirrors apply_patch's realBase check: the REAL resolved
+// target (symlinks flattened, create-mode suffix re-attached lexically) must
+// stay inside the REAL workDir. A lexically-inside path whose ancestor
+// symlink/junction lands outside the project must not be writable through
+// this adapter surface (apply_patch refuses the same shape).
+function guardBaseContainment(fullPath, workDir) {
+    let realBase;
+    try { realBase = realpathSync(workDir); } catch { return null; }
+    const nearest = realpathNearestExisting(fullPath);
+    if (!nearest) return null;
+    const realResolved = nearest.real + fullPath.slice(nearest.probe.length);
+    const fold = process.platform === 'win32' ? (s) => s.toLowerCase() : (s) => s;
+    const baseWithSep = realBase.endsWith(sep) ? realBase : realBase + sep;
+    if (fold(realResolved) !== fold(realBase) && !fold(realResolved).startsWith(fold(baseWithSep))) {
+        return `Error: cannot write outside the working directory: ${normalizeOutputPath(realResolved)} escapes ${normalizeOutputPath(realBase)}`;
+    }
+    return null;
+}
+
+async function resolveTargetPath(args, workDir) {
+    const raw = args?.path ?? args?.file_path;
+    if (typeof raw !== 'string' || raw.length === 0) return null;
+    const norm = normalizeInputPath(raw);
+    const guardErr = guardWritePath(norm);
+    if (guardErr) return { error: guardErr };
+    const full = resolveAgainstCwd(norm, workDir);
+    const fullGuardErr = guardWritePath(full);
+    if (fullGuardErr) return { error: fullGuardErr };
+    // Reachability preflight BEFORE any sync fs (existsSync/realpathSync/
+    // lstatSync in the guards below): a dead mount would wedge the event loop
+    // on the first sync stat, defeating every downstream timeout. Same
+    // deadline-raced probe the read path runs (_readReachPreflight).
+    try { await assertPathsReachable([full]); }
+    catch (e) { return { error: `Error: ${e?.message || e}` }; }
+    const realGuardErr = guardRealTarget(full);
+    if (realGuardErr) return { error: realGuardErr };
+    const containErr = guardBaseContainment(full, workDir);
+    if (containErr) return { error: containErr };
+    return { full };
+}
+
+function invalidateAfterWrite(fullPath) {
+    try { invalidateBuiltinResultCache([fullPath]); } catch { /* best-effort */ }
+    try { markCodeGraphDirtyPaths([fullPath]); } catch { /* best-effort */ }
+}
+
+function countOccurrences(haystack, needle) {
+    let count = 0;
+    let idx = -1;
+    while ((idx = haystack.indexOf(needle, idx + 1)) !== -1) count += 1;
+    return count;
+}
+
+async function adaptStrReplace(args, workDir, options) {
+    const oldStr = args?.old_string;
+    const newStr = args?.new_string;
+    if (typeof oldStr !== 'string' || typeof newStr !== 'string') return null;
+    // Empty old_string would loop forever in countOccurrences (indexOf('', i)
+    // never returns -1) and has no meaningful replace semantics anyway.
+    if (oldStr.length === 0) return 'Error: old_string must be a non-empty string';
+    const target = await resolveTargetPath(args, workDir);
+    if (!target) return null;
+    if (target.error) return target.error;
+    const fullPath = target.full;
+    let content;
+    let statBefore = null;
+    try {
+        try { statBefore = statSync(fullPath); } catch { /* readFileSync below surfaces the real error */ }
+        content = readFileSync(fullPath, 'utf8');
+    } catch (err) {
+        return `Error: cannot read ${fullPath} (${err?.message || err})`;
+    }
+    const matchCount = countOccurrences(content, oldStr);
+    if (matchCount === 0) return `Error: old_string not found in ${fullPath}`;
+    if (matchCount > 1) return `Error: old_string is ambiguous: ${matchCount} matches in ${fullPath}`;
+    const first = content.indexOf(oldStr);
+    const updated = content.slice(0, first) + newStr + content.slice(first + oldStr.length);
+    // Lost-update guard: hand the pre-read stat to atomicWrite as an expected
+    // target snapshot — it re-stats immediately before EACH rename attempt and
+    // aborts with ESTALE_TARGET when another writer (parallel tool call,
+    // interleaved apply_patch) changed the file after our read. This closes
+    // the check-then-write race a pre-write mtime comparison here would leave.
+    try {
+        await atomicWrite(fullPath, updated, {
+            sessionId: options?.readStateScope || options?.sessionId,
+            expectedTargetSnapshot: statBefore ? {
+                exists: true,
+                size: statBefore.size,
+                mtimeMs: statBefore.mtimeMs,
+                ctimeMs: statBefore.ctimeMs,
+                ino: statBefore.ino,
+            } : undefined,
+        });
+    } catch (err) {
+        if (err?.code === 'ESTALE_TARGET') {
+            return `Error: ${fullPath} changed on disk during the replace; re-read and retry`;
+        }
+        throw err;
+    }
+    invalidateAfterWrite(fullPath);
+    return `Updated ${fullPath} (1 replacement)`;
+}
+
+async function adaptWrite(args, workDir, options) {
+    const contents = args?.contents ?? args?.content ?? args?.file_text;
+    if (typeof contents !== 'string') return null;
+    const target = await resolveTargetPath(args, workDir);
+    if (!target) return null;
+    if (target.error) return target.error;
+    const fullPath = target.full;
+    const existed = existsSync(fullPath);
+    try { mkdirSync(dirname(fullPath), { recursive: true }); } catch { /* best-effort: parent may already exist */ }
+    await atomicWrite(fullPath, contents, { sessionId: options?.readStateScope || options?.sessionId });
+    invalidateAfterWrite(fullPath);
+    return `${existed ? 'Updated' : 'Created'} ${fullPath} (${Buffer.byteLength(contents, 'utf8')} bytes)`;
+}
+
+async function adaptBash(key, args, workDir, options) {
+    if (typeof args?.command !== 'string' || args.command.length === 0) return null;
+    const shellArgs = { ...args };
+    if (BASH_SHELL_KIND_NAMES.has(key) && shellArgs.shell === undefined) shellArgs.shell = 'bash';
+    return executeBashTool(shellArgs, workDir, options);
+}
+
+export async function tryExecuteExternalToolAdapter(name, args, workDir, options) {
+    if (typeof name !== 'string' || !name) return null;
+    if (!args || typeof args !== 'object' || Array.isArray(args)) return null;
+    const key = name.toLowerCase();
+    try {
+        if (STR_REPLACE_NAMES.has(key)) return await adaptStrReplace(args, workDir, options);
+        if (WRITE_NAMES.has(key)) return await adaptWrite(args, workDir, options);
+        if (BASH_SHELL_KIND_NAMES.has(key) || BASH_DEFAULT_NAMES.has(key)) return await adaptBash(key, args, workDir, options);
+    } catch (err) {
+        return `Error: ${name} failed (${err?.message || String(err)})`;
+    }
+    return null;
+}