mixdog 0.9.2 → 0.9.4

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

@@ -0,0 +1,108 @@
+import { spawn, spawnSync } from 'child_process';
+
+// Process/pid lifecycle helpers for background shell jobs: liveness probing,
+// tree-kill, the module-level live-job pid registry, and the CLI-shutdown exit
+// hook that reaps owned children. Async jobs are intentionally CLI-owned; no
+// restart replay or daemon handoff is attempted.
+
+export function isPidAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0) return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export function killProcessTree(pid, signal = 'SIGTERM') {
+    if (!Number.isFinite(pid) || pid <= 0) return false;
+    try {
+        if (process.platform === 'win32') {
+            spawn('taskkill', ['/pid', String(pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' });
+        } else {
+            try { process.kill(-pid, signal); }
+            catch { process.kill(pid, signal); }
+            // SIGKILL escalation: a background child that ignores SIGTERM must
+            // not survive (foreground treeKill / persistent _killProcessTree
+            // already do this). After a 3s grace, force-kill the group/pid.
+            // unref so this backstop never holds the host process open.
+            if (signal === 'SIGTERM') {
+                const t = setTimeout(() => {
+                    try { process.kill(-pid, 'SIGKILL'); }
+                    catch { try { process.kill(pid, 'SIGKILL'); } catch { /* already gone */ } }
+                }, 3000);
+                if (t.unref) t.unref();
+            }
+        }
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+// Module-level tracking of live background-job pids so CLI shutdown can reap
+// owned children. Async jobs are intentionally CLI-owned; no restart replay or
+// daemon handoff is attempted.
+export const _liveJobPids = new Set();
+export const _liveJobIdsByPid = new Map();
+let _shellJobsExitHookInstalled = false;
+export function _registerLiveJobPid(pid, jobId = null) {
+    if (Number.isFinite(pid) && pid > 0) {
+        _liveJobPids.add(pid);
+        if (jobId) _liveJobIdsByPid.set(pid, jobId);
+    }
+}
+export function _unregisterLiveJobPid(pid) {
+    if (Number.isFinite(pid) && pid > 0) {
+        _liveJobPids.delete(pid);
+        _liveJobIdsByPid.delete(pid);
+    }
+}
+export function _killLiveJobPid(pid, { sync = false } = {}) {
+    try {
+        if (process.platform === 'win32') {
+            if (sync) {
+                spawnSync('taskkill.exe', ['/pid', String(pid), '/t', '/f'], {
+                    windowsHide: true,
+                    stdio: 'ignore',
+                    timeout: 1500,
+                });
+            } else {
+                spawn('taskkill', ['/pid', String(pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' });
+            }
+        } else {
+            try { process.kill(-pid, 'SIGKILL'); }
+            catch { try { process.kill(pid, 'SIGKILL'); } catch { /* ignore */ } }
+        }
+        return true;
+    } catch {
+        return false;
+    }
+}
+export function _sweepLiveJobsSync() {
+    for (const pid of _liveJobPids) {
+        _killLiveJobPid(pid, { sync: true });
+    }
+    _liveJobPids.clear();
+    _liveJobIdsByPid.clear();
+}
+function _ensureProcessListenerHeadroom(events, extra = 1) {
+    try {
+        if (typeof process.getMaxListeners !== 'function' || typeof process.setMaxListeners !== 'function') return;
+        const current = process.getMaxListeners();
+        if (current === 0) return;
+        let needed = current;
+        for (const event of events) needed = Math.max(needed, process.listenerCount(event) + extra);
+        if (needed > current) process.setMaxListeners(needed);
+    } catch { /* ignore */ }
+}
+export function _installShellJobsExitHook() {
+    if (_shellJobsExitHookInstalled) return;
+    _shellJobsExitHookInstalled = true;
+    _ensureProcessListenerHeadroom(['exit', 'SIGTERM', 'SIGINT', 'SIGHUP'], 1);
+    try { process.on('exit', _sweepLiveJobsSync); } catch { /* ignore */ }
+    try { process.on('SIGTERM', _sweepLiveJobsSync); } catch { /* ignore */ }
+    try { process.on('SIGINT', _sweepLiveJobsSync); } catch { /* ignore */ }
+    try { process.on('SIGHUP', _sweepLiveJobsSync); } catch { /* ignore */ }
+}

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

@@ -1,19 +1,49 @@
-import { spawn, spawnSync } from 'child_process';
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, watch as fsWatch, writeFileSync } from 'fs';
-import * as fsPromises from 'fs/promises';
-import { basename, join } from 'path';
-import { getPluginData } from '../../config.mjs';
+import { spawn } from 'child_process';
+import { closeSync, existsSync, openSync, readFileSync, readSync, statSync, watch as fsWatch, writeFileSync } from 'fs';
+import { basename } from 'path';
 import { stripAnsi } from '../shell-command.mjs';
 import { scrubLoaderVars, scrubProviderSecrets } from '../env-scrub.mjs';
 import {
     normalizeToolNotifyContext,
     notifyToolCompletion,
 } from '../../../../shared/tool-execution-contract.mjs';
+import {
+    renderShellCompletionEnvelope,
+    shellCompletionInstruction,
+    renderShellPromptStallEnvelope,
+    shellPromptStallInstruction,
+} from '../../../../shared/task-notification-envelope.mjs';
 import {
     completeBackgroundTask,
     notifyBackgroundTaskProgress,
+    getBackgroundTask,
 } from '../../../../shared/background-tasks.mjs';
 import { startChildGuardian } from '../../../../shared/child-guardian.mjs';
+import {
+    getShellJobsDir,
+    shellJobStdoutPath,
+    shellJobStderrPath,
+    shellJobExitPath,
+    shellJobDonePath,
+    shellJobEnforcedPath,
+    resolveJobOwnerHostPid,
+    writeShellJobDetail,
+    readShellJobDetail,
+} from './shell-job-paths.mjs';
+import {
+    isPidAlive,
+    killProcessTree,
+    _unregisterLiveJobPid,
+    _installShellJobsExitHook,
+    _registerLiveJobPid,
+    _liveJobPids,
+    _liveJobIdsByPid,
+    _killLiveJobPid,
+} from './shell-job-process.mjs';
+
+// Facade re-exports: path/detail helpers and the job-not-found message moved
+// to sibling modules; keep existing importers of shell-jobs.mjs resolving.
+export { buildJobNotFoundMessage } from './shell-job-paths.mjs';
 
 globalThis.__mixdogShellJobsRuntimeLoaded = true;
 
@@ -21,269 +51,9 @@ function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-// One-shot sweep of stale shell-job artefacts. Each backgrounded `bash`
-// emits five files (.json/.done/.exit/.stdout.log/.stderr.log); the .done
-// flag is written when the job exits, so a .done file older than
-// SHELL_JOB_STALE_MS is the invariant proof its sibling files are also
-// safe to remove. Active and recently-completed jobs are kept so
-// `task` status/read/wait readers still find them. Runs once per mcp child
-// lifetime on first getShellJobsDir() call. Async dirent walk + parallel
-// stat/unlink keeps the main event loop free; fire-and-forget so the
-// synchronous caller receives `dir` immediately.
-const SHELL_JOB_STALE_MS = 24 * 60 * 60 * 1000;
-let shellJobsSwept = false;
-async function sweepStaleShellJobs(dir) {
-    if (shellJobsSwept) return;
-    shellJobsSwept = true;
-    const cutoff = Date.now() - SHELL_JOB_STALE_MS;
-    let names;
-    try { names = await fsPromises.readdir(dir); } catch { return; }
-    const expired = [];
-    await Promise.all(names.map(async (name) => {
-        if (!name.endsWith('.done')) return;
-        const p = join(dir, name);
-        try {
-            const st = await fsPromises.stat(p);
-            if (st.mtimeMs < cutoff) expired.push(name.slice(0, -5));
-        } catch {}
-    }));
-    // Orphan reclaim: a crashed wrapper leaves <id>.json with no .done —
-    // forever. Invariant proofs of death (either suffices, both gated on the
-    // stale cutoff so a young orphan can't race its own spawn):
-    //   a) deadline: the wrapper enforces timeoutMs, so an entry older than
-    //      timeoutMs + grace cannot still be running — pid-reuse-proof. Only
-    //      trusted on runtime proof: detail.timeoutEnforced:true (PS wrapper,
-    //      unconditional) or the <id>.enforced marker the posix wrapper
-    //      touches when its `timeout` branch actually runs.
-    //   b) ESRCH: the recorded pid no longer exists. Alone this misses pids
-    //      recycled by unrelated live processes, hence (a).
-    const ORPHAN_DEADLINE_GRACE_MS = 30 * 60_000;
-    const doneSet = new Set(names.filter(n => n.endsWith('.done')).map(n => n.slice(0, -5)));
-    await Promise.all(names.map(async (name) => {
-        if (!name.endsWith('.json')) return;
-        const jobId = name.slice(0, -5);
-        if (doneSet.has(jobId)) return;
-        const p = join(dir, name);
-        try {
-            const st = await fsPromises.stat(p);
-            if (st.mtimeMs >= cutoff) return;
-            const detail = JSON.parse(await fsPromises.readFile(p, 'utf-8'));
-            const tmo = Number(detail?.timeoutMs);
-            const enforced = detail?.timeoutEnforced === true
-                || existsSync(join(dir, `${jobId}.enforced`));
-            const deadlinePassed = enforced
-                && Number.isFinite(tmo) && tmo > 0
-                && (Date.now() - st.mtimeMs) > tmo + ORPHAN_DEADLINE_GRACE_MS;
-            if (!deadlinePassed) {
-                const pid = Number(detail?.pid);
-                if (Number.isFinite(pid) && pid > 0) {
-                    try { process.kill(pid, 0); return; } // alive (or EPERM → treated dead only via ESRCH below)
-                    catch (e) { if (e?.code !== 'ESRCH') return; }
-                }
-            }
-            expired.push(jobId);
-        } catch {}
-    }));
-    // Owner sidecar markers carry a dynamic `.owner-<pid>` suffix, so they
-    // can't sit in the fixed-extension list — map each expired jobId to the
-    // marker name(s) actually present in this listing and unlink those too.
-    const expiredSet = new Set(expired);
-    const ownerMarkers = names.filter((n) => {
-        const i = n.lastIndexOf('.owner-');
-        return i > 0 && expiredSet.has(n.slice(0, i));
-    });
-    await Promise.all([
-        ...expired.flatMap((jobId) =>
-            ['.json', '.done', '.exit', '.enforced', '.exit.cmd.sh', '.exit.cmd.ps1', '.stdout.log', '.stderr.log'].map((ext) =>
-                fsPromises.unlink(join(dir, jobId + ext)).catch(() => {}),
-            ),
-        ),
-        ...ownerMarkers.map((n) => fsPromises.unlink(join(dir, n)).catch(() => {})),
-    ]);
-}
-
-function getShellJobsDir() {
-    const dir = join(getPluginData(), 'shell-jobs');
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    sweepStaleShellJobs(dir);
-    return dir;
-}
-
-function shellJobDetailPath(jobId) { return join(getShellJobsDir(), `${jobId}.json`); }
-function shellJobStdoutPath(jobId) { return join(getShellJobsDir(), `${jobId}.stdout.log`); }
-function shellJobStderrPath(jobId) { return join(getShellJobsDir(), `${jobId}.stderr.log`); }
-function shellJobExitPath(jobId) { return join(getShellJobsDir(), `${jobId}.exit`); }
-function shellJobDonePath(jobId) { return join(getShellJobsDir(), `${jobId}.done`); }
-// Runtime proof that the posix wrapper's `timeout` branch actually ran: the
-// wrapper touches this marker immediately before exec'ing `timeout`, so its
-// existence is never optimistic (no spawn-time probe can guarantee the
-// wrapper's own env/cwd resolution). PS jobs don't need it — their wrapper
-// enforces unconditionally and records detail.timeoutEnforced:true.
-function shellJobEnforcedPath(jobId) { return join(getShellJobsDir(), `${jobId}.enforced`); }
-// Owner sidecar marker: a zero-byte file whose NAME encodes the owning CC host
-// (claude.exe) pid — `<jobId>.owner-<pid>`. It lets the statusline owner-filter
-// jobs from a SINGLE directory listing (no per-job JSON read) so the filter can
-// precede its per-tick scan cap — otherwise other sessions' newer jobs evict
-// this session's live jobs before filtering. Swept alongside the other
-// artefacts.
-function shellJobOwnerPath(jobId, pid) { return join(getShellJobsDir(), `${jobId}.owner-${pid}`); }
-
 const JOB_STATUS_PREVIEW_MAX_BYTES = 4096;
 const JOB_STATUS_PREVIEW_MAX_LINES = 20;
 const JOB_STATUS_PREVIEW_MAX_CHARS = 1200;
-
-// Resolve the CLI host pid that owns a freshly-spawned job. Standalone CLI
-// execution is process-owned: background tasks are scoped to this CLI lifetime,
-// and the pid stamp is only for statusline filtering / legacy sidecars.
-function resolveJobOwnerHostPid(clientHostPid) {
-    const explicit = Number(clientHostPid);
-    if (Number.isInteger(explicit) && explicit > 0) return explicit;
-    const envPid = Number(process.env.MIXDOG_OWNER_HOST_PID);
-    if (Number.isInteger(envPid) && envPid > 0) return envPid;
-    return null;
-}
-
-function writeShellJobDetail(detail) {
-    // Session scope stamp: every job record is tagged with the CC host pid
-    // that owns it (the claude.exe pid). This is the SAME physical pid the
-    // statusline shim passes as --client-host-pid, so the statusline can count
-    // only its own session's jobs by exact pid equality (no heuristic). The
-    // spawn sites set detail.ownerHostPid from the per-request threaded
-    // clientHostPid (resolveJobOwnerHostPid); this fallback only stamps the
-    // single-client env value when no spawn-site pid was set, and NEVER
-    // overwrites an existing stamp — so the field round-trips through disk on
-    // refresh/kill and a correct per-terminal stamp is preserved across rewrites.
-    if (detail && detail.ownerHostPid == null) {
-        const hostPid = Number(process.env.MIXDOG_OWNER_HOST_PID);
-        if (Number.isInteger(hostPid) && hostPid > 0) detail.ownerHostPid = hostPid;
-    }
-    writeFileSync(shellJobDetailPath(detail.jobId), JSON.stringify(detail, null, 2), 'utf-8');
-    // Owner sidecar: encode the resolved owner pid in the marker filename so the
-    // statusline can owner-filter from the directory listing alone (before its
-    // scan cap). Idempotent zero-byte write — safe to repeat on refresh/kill
-    // rewrites. Skipped when no owner is known (legacy/unattributed jobs).
-    if (detail && Number.isInteger(detail.ownerHostPid) && detail.ownerHostPid > 0) {
-        try { writeFileSync(shellJobOwnerPath(detail.jobId, detail.ownerHostPid), '', 'utf-8'); }
-        catch { /* best-effort marker */ }
-    }
-}
-
-function readShellJobDetail(jobId) {
-    try {
-        const p = shellJobDetailPath(jobId);
-        if (!existsSync(p)) return null;
-        return JSON.parse(readFileSync(p, 'utf-8'));
-    } catch {
-        return null;
-    }
-}
-
-export function buildJobNotFoundMessage(jobId) {
-    return `Error: task not found: ${jobId}`;
-}
-
-function isPidAlive(pid) {
-    if (!Number.isFinite(pid) || pid <= 0) return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    } catch {
-        return false;
-    }
-}
-
-function killProcessTree(pid, signal = 'SIGTERM') {
-    if (!Number.isFinite(pid) || pid <= 0) return false;
-    try {
-        if (process.platform === 'win32') {
-            spawn('taskkill', ['/pid', String(pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' });
-        } else {
-            try { process.kill(-pid, signal); }
-            catch { process.kill(pid, signal); }
-            // SIGKILL escalation: a background child that ignores SIGTERM must
-            // not survive (foreground treeKill / persistent _killProcessTree
-            // already do this). After a 3s grace, force-kill the group/pid.
-            // unref so this backstop never holds the host process open.
-            if (signal === 'SIGTERM') {
-                const t = setTimeout(() => {
-                    try { process.kill(-pid, 'SIGKILL'); }
-                    catch { try { process.kill(pid, 'SIGKILL'); } catch { /* already gone */ } }
-                }, 3000);
-                if (t.unref) t.unref();
-            }
-        }
-        return true;
-    } catch {
-        return false;
-    }
-}
-
-// Module-level tracking of live background-job pids so CLI shutdown can reap
-// owned children. Async jobs are intentionally CLI-owned; no restart replay or
-// daemon handoff is attempted.
-const _liveJobPids = new Set();
-const _liveJobIdsByPid = new Map();
-let _shellJobsExitHookInstalled = false;
-function _registerLiveJobPid(pid, jobId = null) {
-    if (Number.isFinite(pid) && pid > 0) {
-        _liveJobPids.add(pid);
-        if (jobId) _liveJobIdsByPid.set(pid, jobId);
-    }
-}
-function _unregisterLiveJobPid(pid) {
-    if (Number.isFinite(pid) && pid > 0) {
-        _liveJobPids.delete(pid);
-        _liveJobIdsByPid.delete(pid);
-    }
-}
-function _killLiveJobPid(pid, { sync = false } = {}) {
-    try {
-        if (process.platform === 'win32') {
-            if (sync) {
-                spawnSync('taskkill.exe', ['/pid', String(pid), '/t', '/f'], {
-                    windowsHide: true,
-                    stdio: 'ignore',
-                    timeout: 1500,
-                });
-            } else {
-                spawn('taskkill', ['/pid', String(pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' });
-            }
-        } else {
-            try { process.kill(-pid, 'SIGKILL'); }
-            catch { try { process.kill(pid, 'SIGKILL'); } catch { /* ignore */ } }
-        }
-        return true;
-    } catch {
-        return false;
-    }
-}
-function _sweepLiveJobsSync() {
-    for (const pid of _liveJobPids) {
-        _killLiveJobPid(pid, { sync: true });
-    }
-    _liveJobPids.clear();
-    _liveJobIdsByPid.clear();
-}
-function _ensureProcessListenerHeadroom(events, extra = 1) {
-    try {
-        if (typeof process.getMaxListeners !== 'function' || typeof process.setMaxListeners !== 'function') return;
-        const current = process.getMaxListeners();
-        if (current === 0) return;
-        let needed = current;
-        for (const event of events) needed = Math.max(needed, process.listenerCount(event) + extra);
-        if (needed > current) process.setMaxListeners(needed);
-    } catch { /* ignore */ }
-}
-function _installShellJobsExitHook() {
-    if (_shellJobsExitHookInstalled) return;
-    _shellJobsExitHookInstalled = true;
-    _ensureProcessListenerHeadroom(['exit', 'SIGTERM', 'SIGINT', 'SIGHUP'], 1);
-    try { process.on('exit', _sweepLiveJobsSync); } catch { /* ignore */ }
-    try { process.on('SIGTERM', _sweepLiveJobsSync); } catch { /* ignore */ }
-    try { process.on('SIGINT', _sweepLiveJobsSync); } catch { /* ignore */ }
-    try { process.on('SIGHUP', _sweepLiveJobsSync); } catch { /* ignore */ }
-}
-
 function shellQuoteSingle(s) {
     return `'${String(s).replace(/'/g, `'\"'\"'`)}'`;
 }
@@ -729,22 +499,21 @@ export function watchBackgroundShellJob(jobId, notifyCtx) {
             const elapsedMs = Number.isFinite(startedAtMs) ? Math.max(0, finishedAtMs - startedAtMs) : null;
             const exitCode = (typeof detail.exitCode === 'number') ? detail.exitCode : null;
             const status = detail.status || (reason === 'timeout' ? 'running' : 'unknown');
-            const lines = [
-                `[task_id: ${jobId}]`,
-                `[status: ${status}]`,
-                `[exit: ${exitCode === null ? 'n/a' : exitCode}]`,
-                elapsedMs !== null ? `[elapsed: ${elapsedMs} ms]` : null,
-                detail.command ? `[command: ${detail.command}]` : null,
-                '',
-                detail.summary ? `Summary: ${detail.summary}` : null,
-                detail.stdoutPreview ? `\n[stdout preview]\n${detail.stdoutPreview}` : null,
-                (detail.mergeStderr !== true && detail.stderrPreview) ? `\n[stderr preview]\n${detail.stderrPreview}` : null,
-            ].filter((l) => l !== null && l !== '');
-            const body = lines.join('\n');
+            const body = renderShellCompletionEnvelope({
+                jobId,
+                status,
+                exitCode,
+                elapsedMs,
+                command: detail.command,
+                summary: detail.summary,
+                stdoutPreview: detail.stdoutPreview,
+                stderrPreview: detail.stderrPreview,
+                mergeStderr: detail.mergeStderr,
+            });
             const taskStatus = status === 'completed'
                 ? 'completed'
                 : (status === 'cancelled' ? 'cancelled' : 'failed');
-            const instruction = `The background shell task ${jobId} you started earlier has finished (${status}, exit ${exitCode === null ? 'n/a' : exitCode}) - review this result in your next step.`;
+            const instruction = shellCompletionInstruction({ jobId, status, exitCode });
             const completedTask = completeBackgroundTask(jobId, {
                 status: taskStatus,
                 result: shellJobPublicTaskResult(detail),
@@ -780,33 +549,38 @@ export function watchBackgroundShellJob(jobId, notifyCtx) {
         if (now - lastOutputAtMs < SHELL_JOB_PROMPT_STALL_MS) return;
         if (!looksLikeInteractivePrompt(tail.text)) return;
         const elapsedMs = now - (Date.parse(detail.startedAt || '') || now);
-        const body = [
-            `[task_id: ${jobId}]`,
-            '[status: running]',
-            `[stalled: no output growth for ${now - lastOutputAtMs} ms]`,
-            elapsedMs >= 0 ? `[elapsed: ${elapsedMs} ms]` : null,
-            detail.command ? `[command: ${detail.command}]` : null,
-            '',
-            'This background shell task appears to be waiting for interactive input. Background tasks cannot answer prompts automatically; cancel it or rerun with non-interactive flags/input.',
-            tail.text ? `\n${tail.text}` : null,
-        ].filter((line) => line !== null && line !== '').join('\n');
-        const instruction = `The background shell task ${jobId} appears to be waiting for interactive input; inspect the prompt, then cancel or rerun it non-interactively.`;
-        const sent = notifyBackgroundTaskProgress(jobId, {
-            text: body,
-            resultType: 'shell_task_progress',
-            instruction,
-            key: 'interactive-prompt-stall',
-            status: null,
-        }) || notifyToolCompletion({
-            surface: 'shell',
-            id: jobId,
-            status: null,
-            text: body,
-            resultType: 'shell_task_progress',
-            instruction,
-            context: ctx,
-            logPrefix: 'shell-jobs',
+        const body = renderShellPromptStallEnvelope({
+            jobId,
+            stalledMs: now - lastOutputAtMs,
+            elapsedMs,
+            command: detail.command,
+            tailText: tail.text,
         });
+        const instruction = shellPromptStallInstruction({ jobId });
+        // Prefer the progress-notify path when a background task row exists.
+        // Its once-key ('interactive-prompt-stall') dedupe returns false after
+        // a re-arm even though the row is present — do NOT fall back to
+        // notifyToolCompletion in that case (it would fire a duplicate). Only
+        // use the completion fallback when the task row is absent (progress
+        // path unavailable).
+        const sent = getBackgroundTask(jobId)
+            ? notifyBackgroundTaskProgress(jobId, {
+                text: body,
+                resultType: 'shell_task_progress',
+                instruction,
+                key: 'interactive-prompt-stall',
+                status: null,
+            })
+            : notifyToolCompletion({
+                surface: 'shell',
+                id: jobId,
+                status: null,
+                text: body,
+                resultType: 'shell_task_progress',
+                instruction,
+                context: ctx,
+                logPrefix: 'shell-jobs',
+            });
         if (sent) promptStallNotified = true;
     };
     const checkDone = (reason) => {

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

@@ -35,8 +35,6 @@ import {
     executeGlobTool,
     executeGrepTool,
 } from './builtin/search-tool.mjs';
-import { executeDiagnosticsTool } from './builtin/diagnostics-tool.mjs';
-import { executeOpenConfigTool } from './builtin/open-config-tool.mjs';
 import {
     configureReadRangeIndexTelemetry,
     flushReadRangeIndexesSync,
@@ -46,6 +44,7 @@ import {
     extractPdfText,
 } from './builtin/read-special-files.mjs';
 import { computeUnifiedDiff } from './builtin/diff-utils.mjs';
+import { tryExecuteExternalToolAdapter, isExternalAdapterTool } from './builtin/external-tool-adapters.mjs';
 import { formatToolStartProgress } from './progress-message.mjs';
 import { BUILTIN_TOOLS } from './builtin/builtin-tools.mjs';
 import { validateBuiltinArgs } from './builtin/arg-guard.mjs';
@@ -490,10 +489,6 @@ export async function executeBuiltinTool(name, args, cwd, options = {}) {
             return executeTaskTool(args, options);
         case 'read':
             return executeReadTool(args, workDir, readStateScope, executeChildBuiltinTool, options, _readToolHelpers);
-        case 'diagnostics':
-            return executeDiagnosticsTool(args, workDir, options);
-        case 'open_config':
-            return executeOpenConfigTool();
         case 'grep':
             return executeGrepTool(args, workDir, executeChildBuiltinTool, readStateScope, options);
         case 'glob':
@@ -517,6 +512,10 @@ export async function executeBuiltinTool(name, args, cwd, options = {}) {
         case 'hex':
             return executeHexTool(args, workDir, readStateScope, _readModeHelpers);
         default:
+            {
+                const adapted = await tryExecuteExternalToolAdapter(name, args, workDir, options);
+                if (adapted !== null) return adapted;
+            }
             return formatUnknownBuiltinToolMessage(name, args);
     }
     })();
@@ -531,6 +530,12 @@ export function isBuiltinTool(name) {
     return BUILTIN_TOOLS.some(t => t.name === toolName);
 }
 
+// Re-export so the session loop can route foreign-CLI tool names
+// (StrReplace/Write/bash variants) into executeBuiltinTool — whose default:
+// case runs the native adapter — instead of short-circuiting to the
+// unknown-tool redirect message at the dispatch layer.
+export { isExternalAdapterTool };
+
 // Test-only exports for smart truncation helpers (see
 // scripts/test-smart-truncation.mjs). Runtime callers inside this module
 // use the local bindings unchanged; these named exports just make the