@mario.andreschak/mcp-bash 3.45.0 → 3.45.2

package/dist/tools.js

@@ -12,16 +12,14 @@
  *   - orphan cleanup: every live session is force-killed on FLUJO process exit,
  *     and idle finished sessions are swept after a TTL.
  *
- * Confinement + env hygiene (issue #175): the `cwd` is confined to the same
+ * Confinement (issue #175): the `cwd` is confined to the same
  * effective roots as the built-in `filesystem` server (a HARD CEILING from
  * `FLUJO_BASH_ROOTS`, falling back to `FLUJO_FS_ROOTS`, plus UI-persisted roots
  * that may only narrow within it). This is a best-effort guardrail — a shell can
  * `cd` elsewhere or use absolute paths, so `FLUJO_FS_ROOTS`/`FLUJO_BASH_ROOTS`
- * and OS permissions remain the real boundary. Spawned commands also DO NOT
- * inherit the full backend `process.env` by default (which would leak secrets);
- * only a minimal allow-list is passed. Set `FLUJO_BASH_INHERIT_ENV=1` to restore
- * full inheritance. Individual calls may pass explicit `env` overrides without
- * enabling full inheritance.
+ * and OS permissions remain the real boundary. Spawned commands inherit the
+ * Bash server's complete host environment, just like a terminal opened by the
+ * same FLUJO process. Individual calls may still pass explicit `env` overrides.
  *
  * Every tool returns a machine-readable JSON envelope in a single text content
  * block; failures come back as `isError: true` rather than thrown.
@@ -33,9 +31,9 @@
  */
 import path from 'node:path';
 import fs from 'node:fs';
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { spawn as spawnPty } from '@lydell/node-pty';
-import { ALLOW_PROTECTED_PATHS_ENV, createLogger, getDataDir, getHomeDir, isInside, isProtected, isProtectedPathsEnabled, killProcessTree, loadEffectiveRoots, } from './shared.js';
+import { createLogger, getDataDir, isInside, killProcessTree, loadEffectiveRoots, } from './shared.js';
 const BASH_SERVER_NAME = 'bash';
 export const BASH_TERMINAL_APP_URI = 'ui://bash/terminal';
 const log = createLogger('backend/services/mcp/internal/bashTools');
@@ -226,12 +224,56 @@ function resolveBashExecutable() {
     cachedBashPath = firstExistingFile(candidates);
     return cachedBashPath;
 }
+function windowsStorePwshCandidates(programFiles) {
+    const windowsApps = path.join(programFiles, 'WindowsApps');
+    const packagePattern = /^Microsoft\.PowerShell_[^_]+_[^_]+__8wekyb3d8bbwe$/i;
+    const packageNames = [];
+    try {
+        packageNames.push(...fs.readdirSync(windowsApps, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && packagePattern.test(entry.name))
+            .map((entry) => entry.name));
+    }
+    catch {
+        // WindowsApps is normally protected, even though executables in a known
+        // package directory remain runnable. Discover per-user packages below.
+    }
+    try {
+        const systemRoot = getEnvCaseInsensitive('SystemRoot') ?? getEnvCaseInsensitive('windir');
+        const regExe = systemRoot ? path.join(systemRoot, 'System32', 'reg.exe') : 'reg.exe';
+        const packageRepository = String.raw `HKCU\Software\Classes\Local Settings\Software\Microsoft\Windows\CurrentVersion\AppModel\Repository\Packages`;
+        const result = spawnSync(regExe, [
+            'query', packageRepository,
+            '/f', 'Microsoft.PowerShell_*__8wekyb3d8bbwe',
+            '/k', '/s',
+        ], {
+            encoding: 'utf8',
+            windowsHide: true,
+            timeout: 3_000,
+        });
+        if (result.status === 0 && result.stdout) {
+            const matches = result.stdout.match(/Microsoft\.PowerShell_[^_\\\s]+_[^_\\\s]+__8wekyb3d8bbwe/gi);
+            if (matches)
+                packageNames.push(...matches);
+        }
+    }
+    catch {
+        // Registry discovery is best-effort; MSI locations below remain available.
+    }
+    return [...new Set(packageNames)]
+        .sort((a, b) => {
+        const aVersion = a.split('_')[1] ?? '';
+        const bVersion = b.split('_')[1] ?? '';
+        return bVersion.localeCompare(aVersion, undefined, { numeric: true, sensitivity: 'base' });
+    })
+        .map((packageName) => path.join(windowsApps, packageName, 'pwsh.exe'));
+}
 function windowsPwshCandidates() {
     const localAppData = getEnvCaseInsensitive('LocalAppData');
     const programFiles = getEnvCaseInsensitive('ProgramFiles');
     return [
         ...(localAppData ? [path.join(localAppData, 'Microsoft', 'WindowsApps', 'pwsh.exe')] : []),
         ...(programFiles ? [
+            ...windowsStorePwshCandidates(programFiles),
             path.join(programFiles, 'PowerShell', '7', 'pwsh.exe'),
             path.join(programFiles, 'PowerShell', '7-preview', 'pwsh.exe'),
         ] : []),
@@ -307,7 +349,7 @@ let cachedShellInfo;
 export function collectShellInfo() {
     if (cachedShellInfo)
         return cachedShellInfo;
-    const defaultPlan = buildSpawn('', 'default');
+    const defaultPlan = resolveShellPlan('', 'default', 'command');
     const shells = [
         shellEntry('pwsh', resolvePwshExecutable()),
         shellEntry('powershell', resolveWindowsPowerShellExecutable()),
@@ -325,7 +367,9 @@ export function collectShellInfo() {
     const notes = [
         'Tool output merges stdout and stderr into one "output" field; "isError" reflects the process exit code only.',
         `The "default" shell on this machine is "${defaultPlan.effectiveShell}".`,
-        'Pass shell:"bash" for POSIX syntax (&&, pipes into head/grep, $(…)); an unavailable explicit shell fails fast.',
+        'Pass shell:"bash" for POSIX syntax; on Windows it launches the absolute Git Bash path reported above, never a bare bash lookup inside PowerShell.',
+        'A specific default-shell command may auto-select PowerShell 7 or Git Bash only for unquoted POSIX &&/|| chaining.',
+        'PowerShell programs use BOM-free encoded transport; write_stdin preserves a leading BOM unless bomPolicy:"strip-leading" is requested.',
     ];
     if (!shells.find((entry) => entry.shell === 'pwsh')?.available
         && shells.find((entry) => entry.shell === 'powershell')?.available) {
@@ -663,15 +707,6 @@ async function resolveCwd(input, roots) {
     const dataDir = getDataDir();
     const raw = typeof input === 'string' ? input.trim() : '';
     const resolved = raw ? (path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(dataDir, raw)) : dataDir;
-    // Optional defense-in-depth layer (issue #260). Configured roots win by
-    // default; users can opt into this stricter policy under Experimental Features.
-    if (await isProtectedPathsEnabled()) {
-        const prot = isProtected(resolved);
-        if (prot.denied) {
-            throw new Error(`cwd "${resolved}" is within a protected location (${prot.matchedRoot}) and is blocked by the FLUJO built-in server protected-path policy. ` +
-                `Disable "Protect sensitive home-directory paths" in Experimental Features or set ${ALLOW_PROTECTED_PATHS_ENV}=1 to override.`);
-        }
-    }
     if (roots.length === 0 || !roots.some((root) => isInside(root, resolved))) {
         throw new Error(`cwd "${resolved}" is outside the configured bash roots.`);
     }
@@ -686,174 +721,12 @@ async function resolveOutputFile(input, cwd, roots) {
     if (!raw)
         throw new Error('"outputFile" must be a non-empty path.');
     const resolved = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(cwd, raw);
-    if (await isProtectedPathsEnabled()) {
-        const prot = isProtected(resolved);
-        if (prot.denied) {
-            throw new Error(`outputFile "${resolved}" is within a protected location (${prot.matchedRoot}).`);
-        }
-    }
     if (roots.length === 0 || !roots.some((root) => isInside(root, resolved))) {
         throw new Error(`outputFile "${resolved}" is outside the configured bash roots.`);
     }
     await fs.promises.mkdir(path.dirname(resolved), { recursive: true });
     return resolved;
 }
-/**
- * Best-effort advisory scan (issue #260, item 4) of a command string for
- * absolute-looking paths that point OUTSIDE the configured roots or INTO a
- * protected location. Returns human-readable warning strings; it NEVER blocks —
- * a shell can reach anywhere regardless, so this is honest advice, not a
- * boundary. Known limitation: shell variable expansions (e.g. `$HOME/AppData`)
- * are not resolved.
- */
-function maskGlobOptionValues(command) {
-    const chars = [...command];
-    const tokens = [...command.matchAll(/"(?:\\.|[^"\\])*"|'[^']*'|[^\s]+/g)];
-    let maskNext = false;
-    for (const match of tokens) {
-        const raw = match[0];
-        const start = match.index ?? 0;
-        const unquoted = raw.length >= 2 && ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'")))
-            ? raw.slice(1, -1)
-            : raw;
-        let valueOffset = 0;
-        if (maskNext) {
-            maskNext = false;
-        }
-        else if (unquoted === '-g' || unquoted === '--glob' || unquoted === '--iglob') {
-            maskNext = true;
-            continue;
-        }
-        else {
-            if (!/^(?:--glob|--iglob)=/.test(unquoted))
-                continue;
-            valueOffset = raw.indexOf('=') + 1;
-        }
-        for (let i = start + valueOffset; i < start + raw.length; i += 1)
-            chars[i] = ' ';
-    }
-    return chars.join('');
-}
-/**
- * Windows utilities that take `/x`-style switches (issue #314, item D). A slash
- * token is only demoted from "absolute path" to "switch" when one of these
- * appears EARLIER IN THE SAME command segment, so `cd … && dir /b && rg …` and
- * `echo dir /b` stay quiet while `echo /.git/config` keeps its advisory.
- * Deliberately excludes names that are also common POSIX utilities (`find`,
- * `sort`, `type`, `more`, `mkdir`, `rmdir`) — suppressing their arguments would
- * silence genuine path advisories such as `find /etc -name passwd`.
- */
-const WINDOWS_SWITCH_UTILITIES = new Set([
-    'dir', 'xcopy', 'robocopy', 'copy', 'move', 'del', 'erase', 'attrib', 'icacls', 'takeown',
-    'findstr', 'tasklist', 'taskkill', 'sc', 'reg', 'net', 'subst', 'where', 'ren', 'rename',
-    'md', 'rd', 'tree', 'fc', 'comp', 'cacls', 'schtasks', 'chkdsk', 'sfc', 'shutdown',
-    'wmic', 'diskpart', 'label', 'vol', 'mklink', 'assoc', 'ftype', 'gpupdate', 'powercfg',
-]);
-/**
- * A cmd-style switch: `/b`, `/ad`, `/mir`, `/e:on`. Never matches a nested path
- * (no interior separator), so `/etc/passwd` is untouched.
- */
-const WINDOWS_SWITCH_RE = /^\/[A-Za-z][A-Za-z0-9?*-]{0,15}(?::[^\s"']*)?$/;
-/** Text of the command segment (split on shell separators) preceding `index`. */
-function segmentTextBefore(command, index) {
-    const separators = /&&|\|\||[|;&\n]/g;
-    let start = 0;
-    let match;
-    while ((match = separators.exec(command)) !== null) {
-        if (match.index >= index)
-            break;
-        start = match.index + match[0].length;
-    }
-    return command.slice(start, index);
-}
-/** True when a slash-switch utility heads the segment containing `index`. */
-function windowsSwitchUtilityPrecedes(command, index) {
-    for (const word of segmentTextBefore(command, index).match(/[^\s"'<>()]+/g) ?? []) {
-        const name = word.replace(/^.*[\\/]/, '').toLowerCase().replace(/\.(?:exe|com|bat|cmd)$/, '');
-        if (WINDOWS_SWITCH_UTILITIES.has(name))
-            return true;
-    }
-    return false;
-}
-async function scanCommandForExternalPaths(command, cwd, roots) {
-    const warnings = [];
-    const protectedPathsEnabled = await isProtectedPathsEnabled();
-    const seen = new Set();
-    // Ripgrep glob values are patterns, not filesystem paths. Mask only option
-    // values so a real path elsewhere in the same command is still inspected.
-    const commandForPathScan = maskGlobOptionValues(command);
-    // Absolute-looking tokens: Windows drive (X:\ or X:/), UNC (\\host\share),
-    // POSIX (/foo), and ~-prefixed home paths.
-    const tokenRe = /(?:[A-Za-z]:[\\/][^\s"']*|\\\\[^\s"']+|~\/[^\s"']*|(?<![\w.])\/[^\s"']+)/g;
-    const matches = [...commandForPathScan.matchAll(tokenRe)]
-        .filter((match) => {
-        if (process.platform !== 'win32')
-            return true;
-        // Two independent conditions must hold before a token is dropped: it must
-        // LOOK like a cmd switch, and a slash-switch utility must appear earlier
-        // in the SAME segment (`… && dir /b && …`). This keeps `/etc/passwd` and
-        // other genuine POSIX paths advisory.
-        if (!WINDOWS_SWITCH_RE.test(match[0]))
-            return true;
-        return !windowsSwitchUtilityPrecedes(commandForPathScan, match.index ?? 0);
-    })
-        .map((match) => match[0]);
-    const home = (() => {
-        try {
-            return getHomeDir();
-        }
-        catch {
-            return '';
-        }
-    })();
-    for (const rawToken of matches) {
-        let token = rawToken;
-        if (token.startsWith('~/') && home)
-            token = path.join(home, token.slice(2));
-        let resolved;
-        try {
-            resolved = path.isAbsolute(token) ? path.resolve(token) : path.resolve(cwd, token);
-        }
-        catch {
-            continue;
-        }
-        if (seen.has(resolved))
-            continue;
-        seen.add(resolved);
-        const prot = protectedPathsEnabled ? isProtected(resolved) : { denied: false };
-        if (prot.denied) {
-            warnings.push(`Command references "${rawToken}", which is inside a protected location (${prot.matchedRoot}).`);
-        }
-        else if (roots.length > 0 && !roots.some((root) => isInside(root, resolved))) {
-            warnings.push(`Command references "${rawToken}", which is outside the configured working roots.`);
-        }
-    }
-    return warnings;
-}
-/**
- * A truthy env flag: "1", "true", "yes", "on" (case-insensitive).
- */
-function isTruthyEnv(value) {
-    return typeof value === 'string' && /^(1|true|yes|on)$/i.test(value.trim());
-}
-/**
- * Names of environment variables that are safe (and often necessary) to pass to
- * a spawned shell. Anything not on this list — notably API keys / secrets — is
- * withheld by default so a command like `env` / `printenv` / `Get-ChildItem Env:`
- * cannot read them back (issue #175). `LC_*` locale vars are allowed by prefix.
- */
-const ENV_ALLOWLIST = new Set([
-    'path',
-    'home', 'userprofile', 'homedrive', 'homepath',
-    'appdata', 'localappdata', 'programdata',
-    'tmp', 'temp', 'tmpdir',
-    'lang', 'lc_all', 'term', 'colorterm', 'no_color',
-    'shell', 'user', 'username', 'logname',
-    // Windows essentials so the default shell can even start.
-    'systemroot', 'windir', 'comspec', 'pathext', 'systemdrive',
-    'programfiles', 'programfiles(x86)',
-    'number_of_processors', 'processor_architecture',
-]);
 /**
  * Returns the managed utilities directory path where Unix-like utilities
  * (BusyBox applets on Windows) are installed. This directory is prepended to
@@ -892,15 +765,38 @@ function getBundledRipgrepDir() {
     }
 }
 /**
- * Build the child process environment. By default only the minimal allow-list is
- * inherited (secrets never leave the backend). Explicit per-command overrides
- * are then applied. Setting `FLUJO_BASH_INHERIT_ENV` to a truthy value restores
- * full `process.env` inheritance for power users.
+ * Read an env var case-insensitively, treating a blank value as absent. FLUJO
+ * launches this server with an explicit `env`, so vars can arrive defined but
+ * empty; an empty `ComSpec` is just as fatal as a missing one.
+ */
+function getNonEmptyEnv(name) {
+    const value = getEnvCaseInsensitive(name);
+    return value && value.trim() !== '' ? value : undefined;
+}
+/**
+ * Ensure a Windows env var the child toolchain needs is present exactly once.
+ * A spelling that already carries a value wins, so a script reading `%windir%`
+ * or `$SYSTEMROOT` keeps seeing the name it was given; blank spellings are
+ * deleted first, because Node de-duplicates Windows env keys case-insensitively
+ * and must not settle on the empty one.
+ */
+function ensureWindowsEnvDefault(target, key, value) {
+    if (!value)
+        return;
+    const spellings = Object.keys(target).filter((candidate) => candidate.toLowerCase() === key.toLowerCase());
+    if (spellings.some((candidate) => (target[candidate] ?? '').trim() !== ''))
+        return;
+    for (const candidate of spellings)
+        delete target[candidate];
+    target[key] = value;
+}
+/**
+ * Build the child process environment. A terminal is expected to behave like
+ * the host account that launched FLUJO, so inherit the complete server process
+ * environment and then apply explicit per-command overrides.
  */
 function buildChildEnv(overrides = {}) {
-    const out = isTruthyEnv(process.env.FLUJO_BASH_INHERIT_ENV)
-        ? { ...process.env }
-        : Object.fromEntries(Object.entries(process.env).filter(([key]) => ENV_ALLOWLIST.has(key.toLowerCase()) || /^LC_/i.test(key)));
+    const out = { ...process.env };
     const currentPath = getEnvCaseInsensitive('PATH') ?? '';
     const utilityDirs = [getManagedUtilsDir(), getBundledRipgrepDir()]
         .filter((dir) => Boolean(dir))
@@ -923,6 +819,20 @@ function buildChildEnv(overrides = {}) {
                 delete out[key];
         }
         out.PATHEXT = windowsExecutableExtensions().join(';');
+        // Windows essentials that must exist for the child to launch anything of
+        // its own. FLUJO passes stdio servers an explicit `env` and the MCP SDK's
+        // default Windows inherit list carries neither ComSpec nor windir, so these
+        // are absent here even though ENV_ALLOWLIST would have kept them.
+        // `npm run <script>` is the casualty: npm resolves its script shell from
+        // `process.env.ComSpec` with no fallback of its own, so a blank one makes it
+        // ask Node to spawn `undefined` and die with ERR_INVALID_ARG_TYPE — after
+        // printing its banner but before emitting one line of diagnostics, which is
+        // why `npm run test:mcp` looked like a silent, empty failure.
+        const systemRoot = getNonEmptyEnv('SystemRoot') ?? getNonEmptyEnv('windir') ?? 'C:\\Windows';
+        ensureWindowsEnvDefault(out, 'SystemRoot', systemRoot);
+        ensureWindowsEnvDefault(out, 'windir', systemRoot);
+        ensureWindowsEnvDefault(out, 'SystemDrive', getNonEmptyEnv('SystemDrive') ?? path.parse(systemRoot).root.replace(/[\\/]$/, ''));
+        ensureWindowsEnvDefault(out, 'ComSpec', resolveCmdExecutable() ?? path.join(systemRoot, 'System32', 'cmd.exe'));
     }
     // Deterministic text encoding and number formatting for children (issue #364):
     // without this, interpreters emit locale-dependent decimal commas and non-UTF-8
@@ -983,100 +893,156 @@ const POWERSHELL_PRELUDE = [
         + ' [Threading.Thread]::CurrentThread.CurrentUICulture=[Globalization.CultureInfo]::InvariantCulture } catch {}',
 ].join('; ');
 const POWERSHELL_EPILOGUE = 'exit $(if ($null -ne $LASTEXITCODE) { $LASTEXITCODE } elseif ($?) { 0 } else { 1 })';
+/** Remove exactly one caller-supplied leading U+FEFF from PowerShell source. */
+export function normalizePowerShellSource(command) {
+    return command.charCodeAt(0) === 0xfeff ? command.slice(1) : command;
+}
 export function wrapPowerShellCommand(command) {
-    return `${POWERSHELL_PRELUDE}\n${command}\n${POWERSHELL_EPILOGUE}`;
+    const normalized = normalizePowerShellSource(command);
+    return `${POWERSHELL_PRELUDE}\n${normalized}\n${POWERSHELL_EPILOGUE}`;
+}
+/**
+ * PowerShell's encoded-command transport is UTF-16LE without a BOM. Keeping the
+ * complete program in one base64 argv value avoids Windows command-line quoting
+ * ambiguities around nested quotes and literal `-c` arguments.
+ */
+export function encodePowerShellCommand(command) {
+    return Buffer.from(wrapPowerShellCommand(command), 'utf16le').toString('base64');
 }
 /** `chcp 65001` forces UTF-8 output for cmd.exe children (issue #364). */
 export function wrapCmdCommand(command) {
     return `chcp 65001>nul & ${command}`;
 }
 function powerShellArgs(command) {
-    return ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', wrapPowerShellCommand(command)];
+    return ['-NoLogo', '-NoProfile', '-NonInteractive', '-EncodedCommand', encodePowerShellCommand(command)];
 }
-/**
- * Build the spawn arguments for the requested shell. Returns the command, argv
- * and whether Node's `shell:true` wrapping applies. Shells are resolved
- * to a concrete executable path up front (checking Git for Windows' well-known
- * install locations for `bash` when it isn't on `PATH`). An unavailable
- * explicitly requested shell is reported before any user command is executed.
- */
-function buildSpawn(command, shell) {
+/** Resolve one shell request to the exact executable shared by every entry point. */
+function resolveShellExecutable(shell, mode) {
+    if (shell === 'powershell') {
+        const file = resolveWindowsPowerShellExecutable();
+        return file
+            ? { file, effectiveShell: 'powershell' }
+            : { file: '', effectiveShell: 'powershell', unavailableShell: 'powershell' };
+    }
     if (shell === 'pwsh') {
-        const resolved = resolvePwshExecutable();
-        if (resolved) {
-            return { file: resolved, args: powerShellArgs(command), useShell: false, effectiveShell: 'pwsh' };
-        }
+        const file = resolvePwshExecutable();
+        if (file)
+            return { file, effectiveShell: 'pwsh' };
         const windowsPowerShell = resolveWindowsPowerShellExecutable();
         if (windowsPowerShell) {
             return {
                 file: windowsPowerShell,
-                args: powerShellArgs(command),
-                useShell: false,
                 effectiveShell: 'powershell',
                 shellSubstitution: {
-                    requested: 'pwsh', used: 'powershell',
+                    requested: 'pwsh',
+                    used: 'powershell',
                     reason: 'PowerShell 7 (pwsh) is not installed on this machine.',
                 },
             };
         }
-        return { file: '', args: [], useShell: false, effectiveShell: 'pwsh', unavailableShell: 'pwsh' };
+        return { file: '', effectiveShell: 'pwsh', unavailableShell: 'pwsh' };
     }
     if (shell === 'bash') {
-        const resolved = resolveBashExecutable();
-        if (resolved) {
-            return { file: resolved, args: ['-c', command], useShell: false, effectiveShell: 'bash' };
-        }
-        return { file: '', args: [], useShell: false, effectiveShell: 'bash', unavailableShell: 'bash' };
+        const file = resolveBashExecutable();
+        return file
+            ? { file, effectiveShell: 'bash' }
+            : { file: '', effectiveShell: 'bash', unavailableShell: 'bash' };
     }
     if (shell === 'cmd') {
-        const resolved = resolveCmdExecutable();
-        if (resolved) {
-            return {
-                file: resolved,
-                args: ['/d', '/s', '/c', wrapCmdCommand(command)],
-                useShell: false,
-                effectiveShell: 'cmd',
-                windowsVerbatimArguments: true,
-            };
-        }
-        return { file: '', args: [], useShell: false, effectiveShell: 'cmd', unavailableShell: 'cmd' };
+        const file = resolveCmdExecutable();
+        return file
+            ? { file, effectiveShell: 'cmd' }
+            : { file: '', effectiveShell: 'cmd', unavailableShell: 'cmd' };
     }
     if (process.platform === 'win32') {
         const pwsh = resolvePwshExecutable();
-        if (pwsh) {
-            return { file: pwsh, args: powerShellArgs(command), useShell: false, effectiveShell: 'pwsh' };
-        }
+        if (pwsh)
+            return { file: pwsh, effectiveShell: 'pwsh' };
         const windowsPowerShell = resolveWindowsPowerShellExecutable();
-        if (windowsPowerShell) {
-            return { file: windowsPowerShell, args: powerShellArgs(command), useShell: false, effectiveShell: 'powershell' };
-        }
+        if (windowsPowerShell)
+            return { file: windowsPowerShell, effectiveShell: 'powershell' };
         const cmd = resolveCmdExecutable();
-        if (cmd) {
-            return {
-                file: cmd,
-                args: ['/d', '/s', '/c', wrapCmdCommand(command)],
-                useShell: false,
-                effectiveShell: 'cmd',
-                windowsVerbatimArguments: true,
-            };
-        }
+        if (cmd)
+            return { file: cmd, effectiveShell: 'cmd' };
         return {
             file: '',
-            args: [],
-            useShell: false,
             effectiveShell: 'cmd',
             startError: 'No usable PowerShell or cmd executable was found.',
         };
     }
+    if (mode === 'pty') {
+        const loginShell = getEnvCaseInsensitive('SHELL');
+        const bash = resolveBashExecutable();
+        const file = firstExistingFile([loginShell, bash, '/bin/sh', findExecutableOnPath('sh')]);
+        if (!file) {
+            return {
+                file: '',
+                effectiveShell: 'sh',
+                startError: 'No interactive POSIX shell was found.',
+            };
+        }
+        return {
+            file,
+            effectiveShell: path.basename(file).toLowerCase().startsWith('bash') ? 'bash' : 'sh',
+        };
+    }
     const sh = firstExistingFile(['/bin/sh', findExecutableOnPath('sh')]);
-    if (sh)
-        return { file: sh, args: ['-c', command], useShell: false, effectiveShell: 'sh' };
+    return sh
+        ? { file: sh, effectiveShell: 'sh' }
+        : { file: '', effectiveShell: 'sh', startError: 'No POSIX /bin/sh executable was found.' };
+}
+/**
+ * Resolve executable identity once, including the narrow default-shell
+ * auto-selection for unquoted POSIX chaining on Windows PowerShell 5.1.
+ */
+function resolveShellPlan(command, requestedShell, mode) {
+    let selectedShell = requestedShell;
+    let autoSelected = false;
+    let resolved = resolveShellExecutable(selectedShell, mode);
+    if (mode === 'command'
+        && requestedShell === 'default'
+        && resolved.effectiveShell === 'powershell'
+        && commandUsesPosixChaining(command)) {
+        if (resolvePwshExecutable())
+            selectedShell = 'pwsh';
+        else if (resolveBashExecutable())
+            selectedShell = 'bash';
+        if (selectedShell !== 'default') {
+            autoSelected = true;
+            resolved = resolveShellExecutable(selectedShell, mode);
+        }
+    }
+    return { requestedShell, selectedShell, autoSelected, ...resolved };
+}
+/** Test seam proving command and PTY entry points consume the same resolver. */
+export function _resolveShellPlanForTests(command, shell, mode = 'command') {
+    return resolveShellPlan(command, shell, mode);
+}
+/**
+ * Build command-specific argv around a resolved executable. Child spawning
+ * remains direct with `shell:false`.
+ */
+function buildSpawn(command, shell) {
+    const plan = resolveShellPlan(command, shell, 'command');
+    let args = [];
+    let windowsVerbatimArguments;
+    if (plan.file) {
+        if (plan.effectiveShell === 'pwsh' || plan.effectiveShell === 'powershell') {
+            args = powerShellArgs(command);
+        }
+        else if (plan.effectiveShell === 'bash' || plan.effectiveShell === 'sh') {
+            args = ['-c', command];
+        }
+        else {
+            args = ['/d', '/s', '/c', wrapCmdCommand(command)];
+            windowsVerbatimArguments = true;
+        }
+    }
     return {
-        file: '',
-        args: [],
+        ...plan,
+        args,
         useShell: false,
-        effectiveShell: 'sh',
-        startError: 'No POSIX /bin/sh executable was found.',
+        ...(windowsVerbatimArguments ? { windowsVerbatimArguments } : {}),
     };
 }
 function safeRequestedShellValue(input) {
@@ -1098,23 +1064,29 @@ function safeRequestedShellValue(input) {
 function validateShell(input) {
     if (input === undefined)
         return { valid: true, shell: 'default' };
-    if (input === 'default' || input === 'pwsh' || input === 'bash' || input === 'cmd') {
+    if (input === 'default' || input === 'pwsh' || input === 'powershell' || input === 'bash' || input === 'cmd') {
         return { valid: true, shell: input };
     }
     return { valid: false, requestedShell: safeRequestedShellValue(input) };
 }
 function invalidShellResult(requestedShell) {
     return textResult({
-        error: 'Invalid shell request. Expected one of: "default", "pwsh", "bash", or "cmd".',
+        error: 'Invalid shell request. Expected one of: "default", "pwsh", "powershell", "bash", or "cmd".',
         requestedShell,
     }, true);
 }
 function startChild(command, cwd, shell, env) {
-    const { file, args, useShell, effectiveShell, unavailableShell, startError, windowsVerbatimArguments, shellSubstitution, } = buildSpawn(command, shell);
+    const { file, args, useShell, effectiveShell, unavailableShell, startError, windowsVerbatimArguments, shellSubstitution, autoSelected, } = buildSpawn(command, shell);
+    const metadata = {
+        effectiveShell,
+        shellPath: file,
+        shellSubstitution,
+        shellAutoSelected: autoSelected,
+    };
     if (unavailableShell)
-        return { effectiveShell, unavailableShell };
+        return { ...metadata, unavailableShell };
     if (startError)
-        return { effectiveShell, startError };
+        return { ...metadata, startError };
     // POSIX: detached so killProcessTree can signal the whole group (see killProcessTree).
     const detached = process.platform !== 'win32';
     try {
@@ -1125,12 +1097,12 @@ function startChild(command, cwd, shell, env) {
             detached,
             ...(windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
         });
-        return { child, effectiveShell, shellSubstitution };
+        return { child, ...metadata };
     }
     catch (err) {
         return {
             startError: err instanceof Error ? err.message : String(err),
-            effectiveShell,
+            ...metadata,
         };
     }
 }
@@ -1192,8 +1164,14 @@ const SHELL_BUILTINS = new Set([
     'true', 'false', 'test', 'type', 'alias', 'function', 'return', 'shift', 'source', '.', 'dir', 'cls',
     'copy', 'del', 'erase', 'md', 'mkdir', 'rd', 'rmdir', 'move', 'ren', 'rename', 'pushd', 'popd',
 ]);
+function commandAvailabilityName(head, shell) {
+    const name = path.basename(head).toLowerCase();
+    return shell === 'pwsh' || shell === 'powershell' || shell === 'cmd'
+        ? name.replace(/\.(?:com|exe|bat|cmd)$/i, '')
+        : name;
+}
 function isMissingCommandCandidate(head, shell) {
-    const name = path.basename(head).toLowerCase().replace(/\.exe$/, '');
+    const name = commandAvailabilityName(head, shell);
     if (!name || SHELL_BUILTINS.has(name) || /^[-/$]/.test(head) || /^[A-Za-z_][\w-]*=/.test(head))
         return false;
     if (/^[A-Za-z]+-[A-Za-z][A-Za-z-]*$/.test(head) && (shell === 'pwsh' || shell === 'powershell'))
@@ -1222,7 +1200,7 @@ export function detectDialectMismatch(command, shell, isAvailable = (name) => Bo
     const posixShell = shell === 'bash' || shell === 'sh';
     if (!posixShell) {
         for (const head of new Set(heads)) {
-            const name = path.basename(head).toLowerCase().replace(/\.exe$/, '');
+            const name = commandAvailabilityName(head, shell);
             if (!isMissingCommandCandidate(head, shell) || isAvailable(name))
                 continue;
             if (POSIX_ONLY_BINARIES.has(name)) {
@@ -1342,51 +1320,27 @@ export function createStreamDecoder(mode = 'auto') {
         return text;
     };
 }
-/** Resolve an interactive shell executable without wrapping a command string. */
+/** Build PTY-specific argv around the same resolved executable used elsewhere. */
 function buildPtySpawn(shell) {
-    if (shell === 'pwsh') {
-        const file = resolvePwshExecutable();
-        return file
-            ? { file, args: ['-NoLogo'], effectiveShell: 'pwsh' }
-            : { file: '', args: [], effectiveShell: 'pwsh', unavailableShell: 'pwsh' };
-    }
-    if (shell === 'bash') {
-        const file = resolveBashExecutable();
-        return file
-            ? { file, args: ['--noprofile', '--norc', '-i'], effectiveShell: 'bash' }
-            : { file: '', args: [], effectiveShell: 'bash', unavailableShell: 'bash' };
-    }
-    if (shell === 'cmd') {
-        const file = resolveCmdExecutable();
-        return file
-            ? { file, args: ['/d', '/q'], effectiveShell: 'cmd' }
-            : { file: '', args: [], effectiveShell: 'cmd', unavailableShell: 'cmd' };
-    }
-    if (process.platform === 'win32') {
-        const pwsh = resolvePwshExecutable();
-        if (pwsh)
-            return { file: pwsh, args: ['-NoLogo'], effectiveShell: 'pwsh' };
-        const powershell = resolveWindowsPowerShellExecutable();
-        if (powershell)
-            return { file: powershell, args: ['-NoLogo'], effectiveShell: 'powershell' };
-        const cmd = resolveCmdExecutable();
-        if (cmd)
-            return { file: cmd, args: ['/d', '/q'], effectiveShell: 'cmd' };
-        return { file: '', args: [], effectiveShell: 'cmd', startError: 'No usable PowerShell or cmd executable was found.' };
+    const plan = resolveShellPlan('', shell, 'pty');
+    let args = [];
+    if (plan.file) {
+        if (plan.effectiveShell === 'pwsh' || plan.effectiveShell === 'powershell') {
+            args = ['-NoLogo'];
+        }
+        else if (plan.effectiveShell === 'bash') {
+            args = ['--noprofile', '--norc', '-i'];
+        }
+        else if (plan.effectiveShell === 'cmd') {
+            args = ['/d', '/q'];
+        }
+        else {
+            args = ['-i'];
+        }
     }
-    const loginShell = getEnvCaseInsensitive('SHELL');
-    const bash = resolveBashExecutable();
-    const file = firstExistingFile([loginShell, bash, '/bin/sh', findExecutableOnPath('sh')]);
-    if (!file)
-        return { file: '', args: [], effectiveShell: 'sh', startError: 'No interactive POSIX shell was found.' };
-    const isBash = path.basename(file).toLowerCase().startsWith('bash');
-    return {
-        file,
-        args: isBash ? ['--noprofile', '--norc', '-i'] : ['-i'],
-        effectiveShell: isBash ? 'bash' : 'sh',
-    };
+    return { ...plan, args };
 }
-function createCommandProgressReporter(context) {
+function createCommandProgressReporter(context, heartbeatMs = 10_000) {
     const report = context?.onProgress;
     if (!report)
         return { push: () => undefined, stop: async () => undefined };
@@ -1429,7 +1383,7 @@ function createCommandProgressReporter(context) {
             flush();
         else
             deliver(`[command still running: ${Math.max(1, Math.round((Date.now() - startedAt) / 1000))}s]`);
-    }, 10_000);
+    }, heartbeatMs);
     heartbeat.unref?.();
     return {
         push: (chunk) => {
@@ -1460,27 +1414,20 @@ function createCommandProgressReporter(context) {
             stopped = true;
             clearInterval(heartbeat);
             flush();
-            let timer;
-            try {
-                await Promise.race([
-                    chain,
-                    new Promise((resolve) => {
-                        timer = setTimeout(resolve, 1_000);
-                    }),
-                ]);
-            }
-            finally {
-                if (timer)
-                    clearTimeout(timer);
-            }
+            // The tool result must not overtake its final progress notification.
+            // `chain` already catches reporter failures, so awaiting it cannot turn a
+            // notification failure into a hung command. The previous one-second
+            // escape hatch let the client tear down its progress handler first,
+            // intermittently dropping the final output chunk (issue #457).
+            await chain;
         },
     };
 }
 export function bashToolDefinitions() {
     const shellProp = {
         type: 'string',
-        enum: ['default', 'pwsh', 'bash', 'cmd'],
-        description: 'Command parser. "default" uses PowerShell on Windows and /bin/sh elsewhere. Use "pwsh", "bash", or "cmd" for explicit syntax; unavailable explicit shells return an error.',
+        enum: ['default', 'pwsh', 'powershell', 'bash', 'cmd'],
+        description: 'Command parser. "default" uses PowerShell on Windows and /bin/sh elsewhere. Explicit "bash" launches FLUJO\'s absolute resolved Git Bash path on Windows (WSL relay launchers are rejected). Explicit "pwsh" may report a compatibility substitution to Windows PowerShell 5.1; other unavailable explicit shells return an error.',
     };
     const cwdProp = { type: 'string', description: 'Working directory. Relative paths resolve from the FLUJO data directory; configured roots still apply.' };
     const envProp = {
@@ -1504,7 +1451,7 @@ export function bashToolDefinitions() {
     return [
         {
             name: 'shell_info',
-            description: 'Describe this machine before running anything: platform, which shell "default" resolves to, which of pwsh/powershell/bash/cmd/sh are available, and whether common interpreters (python, node, git, ffmpeg, …) are on PATH. Call this instead of discovering the environment through failed commands.',
+            description: 'Describe this machine before running anything: platform, the effective "default" shell and absolute path, resolved paths for pwsh/powershell/bash/cmd/sh, and common interpreters. Explicit Bash execution uses the reported Git Bash path; call this instead of invoking a bare "bash" from PowerShell.',
             inputSchema: { type: 'object', properties: {} },
         },
         {
@@ -1578,7 +1525,7 @@ export function bashToolDefinitions() {
         {
             name: 'run',
             description: 'Run one command to completion. "output" is stdout and stderr MERGED (no 2>&1 needed) and "isError" reflects the process exit code only — text on stderr is not a failure. '
-                + 'On an unknown machine call "shell_info" first; prefer shell:"bash" for POSIX syntax (&&, pipes into head/grep). Output is UTF-8 decoded and PowerShell runs with invariant culture, so numbers and text are stable. '
+                + 'On an unknown machine call "shell_info" first; prefer shell:"bash" for POSIX syntax (&&, pipes into head/grep). Results include the absolute shellPath used. PowerShell programs use BOM-free encoded transport and invariant culture. '
                 + 'Use start/status for a persistent background session.',
             inputSchema: {
                 type: 'object',
@@ -1602,7 +1549,7 @@ export function bashToolDefinitions() {
         },
         {
             name: 'start',
-            description: 'Start an independent background command and return its sessionId. Output is stdout and stderr merged, decoded as UTF-8. Multiple sessions may run in parallel; use status/wait, write_stdin, or kill.',
+            description: 'Start an independent background command and return its sessionId plus the effective shell and absolute shellPath. Output is stdout and stderr merged, decoded as UTF-8. Multiple sessions may run in parallel; use status/wait, write_stdin, or kill.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1632,7 +1579,8 @@ export function bashToolDefinitions() {
         },
         {
             name: 'wait',
-            description: 'Wait for a background session, sending new output as live progress when supported. The wait timeout does not kill the session.',
+            description: 'Wait until a background session completes or the maximum timeout elapses, sending new output as live progress when supported. '
+                + 'The timeout does not kill the session. A finite wait that completes early reports the remaining duration and points to sleep for fixed delays.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1641,19 +1589,44 @@ export function bashToolDefinitions() {
                         type: 'number',
                         description: 'Max seconds to wait (default 60; -1 waits until completion or cancellation; positive values are capped at 12 hours by default).',
                     },
+                    output: {
+                        type: 'string',
+                        enum: ['delta', 'full', 'none'],
+                        description: 'Output returned in the result: "delta" includes only output since the previous wait result, "full" includes all retained output (default), and "none" omits the output field. Every wait advances the delta boundary.',
+                    },
                 },
                 required: ['sessionId'],
             },
         },
+        {
+            name: 'sleep',
+            description: 'Wait for a fixed duration independent of background-session state. Use this instead of wait when the full delay must elapse even if a command finishes early.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    seconds: {
+                        type: 'number',
+                        exclusiveMinimum: 0,
+                        description: 'Fixed positive number of seconds to sleep. Values above the configured Bash timeout ceiling are rejected rather than shortened.',
+                    },
+                },
+                required: ['seconds'],
+            },
+        },
         {
             name: 'write_stdin',
-            description: 'Write a string to a running background session\'s stdin. Pass "newline": false to omit the trailing newline. Returns { sessionId, written }.',
+            description: 'Write UTF-8 text to a running background session\'s stdin. Pass "newline": false to omit the trailing newline. Leading-BOM stripping is opt-in; raw input is preserved by default. Returns { sessionId, written }.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     sessionId: { type: 'string', description: 'The id returned by start.' },
-                    data: { type: 'string', description: 'Text to write to stdin.' },
+                    data: { type: 'string', description: 'Text to encode as UTF-8 and write to stdin.' },
                     newline: { type: 'boolean', description: 'Append a trailing newline (default true).' },
+                    bomPolicy: {
+                        type: 'string',
+                        enum: ['preserve', 'strip-leading'],
+                        description: 'Leading UTF-8 BOM policy. "preserve" is the default; "strip-leading" removes exactly one initial U+FEFF from this write.',
+                    },
                 },
                 required: ['sessionId', 'data'],
             },
@@ -1682,24 +1655,6 @@ export function bashToolDefinitions() {
 function maybeNormalize(text, normalize) {
     return normalize ? text.replace(/\r\n?/g, '\n') : text;
 }
-/**
- * Only when the caller said `shell: "default"` may we pick a different shell
- * (issue #364): a command chained with POSIX `&&`/`||` cannot even parse under
- * Windows PowerShell 5.1, so prefer a shell that can run it. An explicitly
- * requested shell is never overridden.
- */
-function selectShell(command, requested) {
-    if (requested !== 'default')
-        return { shell: requested, autoSelected: false };
-    const plan = buildSpawn(command, 'default');
-    if (plan.effectiveShell === 'powershell' && commandUsesPosixChaining(command)) {
-        if (resolvePwshExecutable())
-            return { shell: 'pwsh', autoSelected: true };
-        if (resolveBashExecutable())
-            return { shell: 'bash', autoSelected: true };
-    }
-    return { shell: 'default', autoSelected: false };
-}
 /** Optional per-call output limits shared by `run` and `start`. */
 function resolveMaxOutputChars(input) {
     return typeof input === 'number' && input > 0
@@ -1745,8 +1700,8 @@ function createOutputSpool(file) {
     };
 }
 async function runTool(args, roots, context) {
-    const command = String(args?.command ?? '').trim();
-    if (!command)
+    const command = String(args?.command ?? '');
+    if (!command.trim())
         return textResult({ error: 'Provide "command": a shell command line to run.' }, true);
     const shellValidation = validateShell(args.shell);
     if (!shellValidation.valid)
@@ -1763,8 +1718,6 @@ async function runTool(args, roots, context) {
         return textResult({ error: '"encoding" must be one of "utf8", "utf16le", or "auto".' }, true);
     }
     const cwd = await resolveCwd(args.cwd, roots);
-    const warnings = await scanCommandForExternalPaths(command, cwd, roots);
-    const warn = warnings.length ? { warnings } : {};
     const normalize = args.normalizeNewlines === true;
     const timeoutMs = resolveCommandTimeoutMs(args.timeout);
     const maxOutputChars = resolveMaxOutputChars(args.maxOutputChars);
@@ -1777,7 +1730,6 @@ async function runTool(args, roots, context) {
             return textResult({ error: err instanceof Error ? err.message : String(err), cwd }, true);
         }
     }
-    const selection = selectShell(command, requestedShell);
     registerExitCleanup();
     const startedAt = Date.now();
     return await new Promise((resolve) => {
@@ -1790,10 +1742,10 @@ async function runTool(args, roots, context) {
         const decodeStdout = createStreamDecoder(encodingMode);
         const decodeStderr = createStreamDecoder(encodingMode);
         const progress = createCommandProgressReporter(context);
-        const { child, startError, effectiveShell, unavailableShell, shellSubstitution } = startChild(command, cwd, selection.shell, envValidation.env);
+        const { child, startError, effectiveShell, shellPath, unavailableShell, shellSubstitution, shellAutoSelected, } = startChild(command, cwd, requestedShell, envValidation.env);
         const dialectWarnings = detectDialectMismatch(command, effectiveShell);
         const dialect = dialectWarnings.length ? { dialectWarnings } : {};
-        const auto = selection.autoSelected ? { shellAutoSelected: true } : {};
+        const auto = shellAutoSelected ? { shellAutoSelected: true } : {};
         const substitution = shellSubstitution ? { shellSubstitution } : {};
         const spoolInfo = () => (outputFilePath
             ? { outputFile: outputFilePath, outputBytes: spool.bytes(), ...(spool.error() ? { outputFileError: spool.error() } : {}) }
@@ -1821,7 +1773,7 @@ async function runTool(args, roots, context) {
         if (startError || !child) {
             spool.close();
             void progress.stop().then(() => {
-                resolve(textResult({ error: `Failed to start command (${effectiveShell}): ${startError ?? 'unknown error'}`, cwd, shell: effectiveShell }, true));
+                resolve(textResult({ error: `Failed to start command (${effectiveShell}): ${startError ?? 'unknown error'}`, cwd, shell: effectiveShell, shellPath }, true));
             });
             return;
         }
@@ -1837,6 +1789,7 @@ async function runTool(args, roots, context) {
                 cwd,
                 requestedShell,
                 shell: effectiveShell,
+                shellPath,
                 exitCode: null,
                 output: finalOut,
                 ...outputStats(),
@@ -1844,7 +1797,6 @@ async function runTool(args, roots, context) {
                 ...dialect,
                 ...substitution,
                 ...auto,
-                ...warn,
             }, true), true);
         };
         const finish = async (result, keepKillEscalation = false) => {
@@ -1870,6 +1822,7 @@ async function runTool(args, roots, context) {
                     cwd,
                     requestedShell,
                     shell: effectiveShell,
+                    shellPath,
                     exitCode: null,
                     timeoutMs,
                     elapsedMs: Date.now() - startedAt,
@@ -1883,7 +1836,6 @@ async function runTool(args, roots, context) {
                     ...dialect,
                     ...substitution,
                     ...auto,
-                    ...warn,
                 }, true), true);
             }, timeoutMs);
         }
@@ -1904,7 +1856,7 @@ async function runTool(args, roots, context) {
             // ENOENT here means the resolved executable vanished between resolution and spawn.
             foregroundChildren().delete(child);
             append(`\n${err.message}`);
-            void finish(textResult({ error: `Command failed to start (${effectiveShell}): ${err.message}`, cwd, shell: effectiveShell, output: maybeNormalize(output, normalize) }, true));
+            void finish(textResult({ error: `Command failed to start (${effectiveShell}): ${err.message}`, cwd, shell: effectiveShell, shellPath, output: maybeNormalize(output, normalize) }, true));
         });
         child.on('close', (code) => {
             foregroundChildren().delete(child);
@@ -1917,6 +1869,7 @@ async function runTool(args, roots, context) {
                 cwd,
                 requestedShell,
                 shell: effectiveShell,
+                shellPath,
                 output: finalOut,
                 ...outputStats(),
                 ...spoolInfo(),
@@ -1924,7 +1877,6 @@ async function runTool(args, roots, context) {
                 ...missingExecutableHint(code, dialectWarnings),
                 ...substitution,
                 ...auto,
-                ...warn,
             }, code !== 0));
         });
         if (context?.signal?.aborted)
@@ -1941,8 +1893,8 @@ function scheduleReap(session) {
     session.reapTimer.unref?.();
 }
 async function startTool(args, roots, ownerScope, context) {
-    const command = String(args?.command ?? '').trim();
-    if (!command)
+    const command = String(args?.command ?? '');
+    if (!command.trim())
         return textResult({ error: 'Provide "command": a shell command line to run.' }, true);
     const shellValidation = validateShell(args.shell);
     if (!shellValidation.valid)
@@ -1989,8 +1941,6 @@ async function startTool(args, roots, ownerScope, context) {
         return textResult({ error: '"encoding" must be one of "utf8", "utf16le", or "auto".' }, true);
     }
     const cwd = await resolveCwd(args.cwd, roots);
-    const warnings = await scanCommandForExternalPaths(command, cwd, roots);
-    const warn = warnings.length ? { warnings } : {};
     const maxOutputChars = resolveMaxOutputChars(args.maxOutputChars);
     let outputFilePath;
     if (args.outputFile !== undefined) {
@@ -2001,8 +1951,7 @@ async function startTool(args, roots, ownerScope, context) {
             return textResult({ error: err instanceof Error ? err.message : String(err), cwd }, true);
         }
     }
-    const selection = selectShell(command, requestedShell);
-    const { child, startError, effectiveShell, unavailableShell, shellSubstitution } = startChild(command, cwd, selection.shell, envValidation.env);
+    const { child, startError, effectiveShell, shellPath, unavailableShell, shellSubstitution, shellAutoSelected, } = startChild(command, cwd, requestedShell, envValidation.env);
     if (unavailableShell) {
         return textResult({
             error: `Requested shell "${unavailableShell}" is unavailable or could not be resolved.`,
@@ -2014,7 +1963,7 @@ async function startTool(args, roots, ownerScope, context) {
         }, true);
     }
     if (startError || !child) {
-        return textResult({ error: `Failed to start command (${effectiveShell}): ${startError ?? 'unknown error'}`, cwd, shell: effectiveShell }, true);
+        return textResult({ error: `Failed to start command (${effectiveShell}): ${startError ?? 'unknown error'}`, cwd, shell: effectiveShell, shellPath }, true);
     }
     const id = `bash-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     const session = {
@@ -2022,9 +1971,16 @@ async function startTool(args, roots, ownerScope, context) {
         ownerScope,
         command,
         cwd,
+        requestedShell,
+        shell: effectiveShell,
+        shellPath,
+        ...(shellSubstitution ? { shellSubstitution } : {}),
         child,
         output: '',
         truncated: false,
+        waitOutput: '',
+        waitOutputTruncated: false,
+        waitOutputLimit: maxOutputChars,
         running: true,
         exitCode: null,
         startedAt: Date.now(),
@@ -2033,24 +1989,34 @@ async function startTool(args, roots, ownerScope, context) {
     };
     table.set(id, session);
     const append = makeAppender(() => session.output, (v, t) => { session.output = v; session.truncated = t || session.truncated; }, maxOutputChars);
+    const appendSessionOutput = (chunk) => {
+        append(chunk);
+        if (!chunk)
+            return;
+        session.waitOutput += chunk;
+        if (session.waitOutput.length > session.waitOutputLimit) {
+            session.waitOutput = session.waitOutput.slice(-session.waitOutputLimit);
+            session.waitOutputTruncated = true;
+        }
+    };
     const spool = createOutputSpool(outputFilePath);
     const decodeStdout = createStreamDecoder(encodingMode);
     const decodeStderr = createStreamDecoder(encodingMode);
     child.stdout?.on('data', (d) => {
         const chunk = decodeStdout(d);
         touchSession(session);
-        append(chunk);
+        appendSessionOutput(chunk);
         spool.write(chunk);
     });
     child.stderr?.on('data', (d) => {
         const chunk = decodeStderr(d);
         session.stderrChars = (session.stderrChars ?? 0) + chunk.length;
         touchSession(session);
-        append(chunk);
+        appendSessionOutput(chunk);
         spool.write(chunk);
     });
     child.on('error', (err) => {
-        append(`\n${err.message}`);
+        appendSessionOutput(`\n${err.message}`);
         session.running = false;
         session.endedAt = Date.now();
         scheduleReap(session);
@@ -2069,17 +2035,21 @@ async function startTool(args, roots, ownerScope, context) {
         cwd,
         requestedShell,
         shell: effectiveShell,
+        shellPath,
         ...(detached ? { detached: true } : {}),
         ...(shellSubstitution ? { shellSubstitution } : {}),
-        ...(selection.autoSelected ? { shellAutoSelected: true } : {}),
+        ...(shellAutoSelected ? { shellAutoSelected: true } : {}),
         ...(dialectWarnings.length ? { dialectWarnings } : {}),
         ...(outputFilePath ? { outputFile: outputFilePath } : {}),
-        ...warn,
     });
 }
 function snapshot(session, extra = {}) {
     return {
         sessionId: session.id,
+        requestedShell: session.requestedShell,
+        shell: session.shell,
+        shellPath: session.shellPath,
+        ...(session.shellSubstitution ? { shellSubstitution: session.shellSubstitution } : {}),
         running: session.running,
         exitCode: session.exitCode,
         output: session.output,
@@ -2102,12 +2072,55 @@ async function waitTool(args, ownerScope, context) {
     const session = ownedSession(id, ownerScope);
     if (!session)
         return textResult({ error: `No background session with id "${id}".` }, true);
+    const outputMode = args.output === undefined ? 'full' : args.output;
+    if (outputMode !== 'delta' && outputMode !== 'full' && outputMode !== 'none') {
+        return textResult({
+            error: 'Invalid wait output mode. Expected one of: "delta", "full", or "none".',
+            requestedOutput: args.output,
+        }, true);
+    }
+    const timeoutMs = resolveCommandTimeoutMs(args.timeout);
+    const waitSnapshot = (extra) => {
+        const delta = session.waitOutput;
+        const deltaTruncated = session.waitOutputTruncated;
+        session.waitOutput = '';
+        session.waitOutputTruncated = false;
+        const base = snapshot(session, extra);
+        if (outputMode === 'none') {
+            delete base.output;
+            return { ...base, outputMode };
+        }
+        if (outputMode === 'delta') {
+            return { ...base, output: delta, outputMode, deltaTruncated };
+        }
+        return { ...base, outputMode };
+    };
+    const timing = (outcome, waitedMs) => {
+        const finite = timeoutMs !== undefined;
+        const returnedEarly = finite && outcome === 'completed' && waitedMs < timeoutMs;
+        const remainingSeconds = returnedEarly
+            ? Math.ceil(Math.max(0, timeoutMs - waitedMs)) / 1_000
+            : 0;
+        return {
+            timedOut: outcome === 'timedOut',
+            waitedMs,
+            ...(finite ? { requestedTimeoutMs: timeoutMs, returnedEarly } : {}),
+            ...(returnedEarly
+                ? {
+                    remainingSeconds,
+                    hint: '`wait.timeout` is a maximum, so wait returned when the background session completed. '
+                        + `To wait the full requested duration, call sleep with {"seconds": ${remainingSeconds}}.`,
+                }
+                : {}),
+            ...(outcome === 'cancelled' ? { cancelled: true } : {}),
+        };
+    };
     if (!session.running)
-        return textResult(snapshot(session, { timedOut: false }));
+        return textResult(waitSnapshot(timing('completed', 0)));
     if (context?.signal?.aborted) {
-        return textResult(snapshot(session, { timedOut: false, cancelled: true }), true);
+        return textResult(waitSnapshot(timing('cancelled', 0)), true);
     }
-    const timeoutMs = resolveCommandTimeoutMs(args.timeout);
+    const startedAt = Date.now();
     const progress = createCommandProgressReporter(context);
     const outcome = await new Promise((resolve) => {
         let settled = false;
@@ -2125,8 +2138,9 @@ async function waitTool(args, ownerScope, context) {
             context?.signal?.removeEventListener('abort', onAbort);
             if (session.output.length > outputOffset)
                 progress.push(session.output.slice(outputOffset));
+            const waitedMs = Date.now() - startedAt;
             await progress.stop();
-            resolve(value);
+            resolve({ kind: value, waitedMs });
         };
         const onAbort = () => void finish('cancelled');
         const poll = () => {
@@ -2146,10 +2160,54 @@ async function waitTool(args, ownerScope, context) {
         context?.signal?.addEventListener('abort', onAbort, { once: true });
         poll();
     });
-    return textResult(snapshot(session, {
-        timedOut: outcome === 'timedOut',
-        ...(outcome === 'cancelled' ? { cancelled: true } : {}),
-    }), outcome === 'cancelled');
+    return textResult(waitSnapshot(timing(outcome.kind, outcome.waitedMs)), outcome.kind === 'cancelled');
+}
+async function sleepTool(args, context) {
+    const seconds = args.seconds;
+    if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0) {
+        return textResult({ error: 'Provide "seconds" as a finite number greater than 0.' }, true);
+    }
+    const requestedMs = seconds * 1_000;
+    const ceilingMs = Math.min(commandMaxTimeoutMs(), 2 ** 31 - 1);
+    if (requestedMs > ceilingMs) {
+        return textResult({
+            error: `Requested sleep exceeds the configured maximum of ${ceilingMs / 1_000} seconds.`,
+            requestedSeconds: seconds,
+            maxSeconds: ceilingMs / 1_000,
+        }, true);
+    }
+    if (context?.signal?.aborted) {
+        return textResult({ slept: false, cancelled: true, requestedSeconds: seconds, elapsedMs: 0 }, true);
+    }
+    const startedAt = Date.now();
+    // A one-second heartbeat keeps finite MCP request timers alive even when the
+    // requested fixed delay is longer than the caller's ordinary silent window.
+    const progress = createCommandProgressReporter(context, 1_000);
+    progress.push(`[sleeping for ${seconds}s]`);
+    const outcome = await new Promise((resolve) => {
+        let settled = false;
+        const finish = (slept) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            context?.signal?.removeEventListener('abort', onAbort);
+            resolve({ slept, elapsedMs: Date.now() - startedAt });
+        };
+        const onAbort = () => finish(false);
+        const timer = setTimeout(() => finish(true), requestedMs);
+        if (context?.signal?.aborted)
+            onAbort();
+        else
+            context?.signal?.addEventListener('abort', onAbort, { once: true });
+    });
+    await progress.stop();
+    return textResult({
+        slept: outcome.slept,
+        requestedSeconds: seconds,
+        elapsedMs: outcome.elapsedMs,
+        ...(!outcome.slept ? { cancelled: true } : {}),
+    }, !outcome.slept);
 }
 function writeStdinTool(args, ownerScope) {
     const id = String(args?.sessionId ?? '');
@@ -2158,15 +2216,31 @@ function writeStdinTool(args, ownerScope) {
         return textResult({ error: `No background session with id "${id}".` }, true);
     if (!session.running)
         return textResult({ error: `Session "${id}" has already exited.` }, true);
+    const bomPolicy = args.bomPolicy === undefined ? 'preserve' : args.bomPolicy;
+    if (bomPolicy !== 'preserve' && bomPolicy !== 'strip-leading') {
+        return textResult({
+            error: '"bomPolicy" must be one of "preserve" or "strip-leading".',
+            requestedBomPolicy: args.bomPolicy,
+        }, true);
+    }
     const data = typeof args.data === 'string' ? args.data : '';
     const withNewline = args.newline === false ? data : `${data}\n`;
+    let payload = Buffer.from(withNewline, 'utf8');
+    if (bomPolicy === 'strip-leading'
+        && payload.length >= 3
+        && payload[0] === 0xef
+        && payload[1] === 0xbb
+        && payload[2] === 0xbf) {
+        payload = payload.subarray(3);
+    }
     try {
-        session.child.stdin?.write(withNewline);
+        session.child.stdin?.write(payload);
+        touchSession(session);
     }
     catch (err) {
         return textResult({ error: `Failed to write to stdin: ${err instanceof Error ? err.message : String(err)}` }, true);
     }
-    return textResult({ sessionId: id, written: Buffer.byteLength(withNewline, 'utf8') });
+    return textResult({ sessionId: id, written: payload.length, bomPolicy });
 }
 function killTool(args, ownerScope) {
     const id = String(args?.sessionId ?? '');
@@ -2185,6 +2259,9 @@ function listSessionsTool(ownerScope) {
         .map((s) => ({
         sessionId: s.id,
         command: s.command,
+        requestedShell: s.requestedShell,
+        shell: s.shell,
+        shellPath: s.shellPath,
         running: s.running,
         exitCode: s.exitCode,
         detached: s.detached === true,
@@ -2212,7 +2289,10 @@ function releaseOwnerTool(ownerScope) {
 function terminalSnapshot(session) {
     return {
         sessionId: session.id,
+        requestedShell: session.requestedShell,
         shell: session.shell,
+        shellPath: session.shellPath,
+        ...(session.shellSubstitution ? { shellSubstitution: session.shellSubstitution } : {}),
         cwd: session.cwd,
         running: session.running,
         exitCode: session.exitCode,
@@ -2292,6 +2372,7 @@ async function openTerminalTool(args, roots, ownerScope) {
             error: `Failed to open pseudoterminal (${plan.effectiveShell}): ${error instanceof Error ? error.message : String(error)}`,
             cwd,
             shell: plan.effectiveShell,
+            shellPath: plan.file,
         }, true);
     }
     registerExitCleanup();
@@ -2299,7 +2380,10 @@ async function openTerminalTool(args, roots, ownerScope) {
     const session = {
         id,
         ownerScope,
+        requestedShell: shellValidation.shell,
         shell: plan.effectiveShell,
+        shellPath: plan.file,
+        ...(plan.shellSubstitution ? { shellSubstitution: plan.shellSubstitution } : {}),
         cwd,
         pty,
         output: '',
@@ -2440,6 +2524,8 @@ export async function bashCallTool(toolName, args, callerNodeId, ownerScope, con
                 return statusTool(args, scope);
             case 'wait':
                 return await waitTool(args, scope, context);
+            case 'sleep':
+                return await sleepTool(args, context);
             case 'write_stdin':
                 return writeStdinTool(args, scope);
             case 'kill':