@sema-agent/core 1.451.0 → 2.0.0

package/dist/tools/fs/fs-bash.js

@@ -0,0 +1,672 @@
+import { Type } from "typebox";
+import { defineTool, errorResult } from "../../core/tools.js";
+import { defaultTaskRegistry } from "../../core/task-registry.js";
+import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_ALIASES, TASK_STOP_ALIASES, TASK_OUTPUT_CONTRACT, TASK_STOP_CONTRACT, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, ENV_DIRECT_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "../../core/task-tool-shape.js";
+import { hasBackgroundShell } from "../../core/background-shell.js";
+import { delimitUntrusted } from "../../core/untrusted-text.js";
+import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
+import { imageMagicMatches } from "./safety.js";
+import { ghRateLimitHint } from "./gh-rate-limit.js";
+import { BASH_DEFAULT_TIMEOUT_SEC, BASH_MAX_TIMEOUT_SEC, BASH_DEFAULT_TIMEOUT_MS, BASH_MAX_TIMEOUT_MS, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, shellRecoveryHint, CWD_SENTINEL, msTimeoutToSec, } from "./fs-shared.js";
+import { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyCompoundReadonly } from "./bash-readonly-classifier.js";
+export function bashReversibilityProbe(allow) {
+    const allowSet = new Set(allow ?? BASH_READONLY_DEFAULT_ALLOW);
+    return (args) => {
+        const command = args?.command;
+        if (typeof command !== "string")
+            return { reversible: false };
+        return { reversible: classifyCompoundReadonly(command, allowSet) === undefined };
+    };
+}
+const EXIT1_INTERPRETATION = {
+    grep: "No matches found",
+    rg: "No matches found",
+    egrep: "No matches found",
+    fgrep: "No matches found",
+    find: "Some directories were inaccessible",
+    diff: "Files differ",
+    test: "Condition is false",
+    "[": "Condition is false",
+};
+export function bashExitOneInterpretation(command) {
+    const stmts = command.split(/\n|;|&&|\|\|/);
+    let lastStmt = "";
+    for (let i = stmts.length - 1; i >= 0; i--) {
+        if (stmts[i].trim().length > 0) {
+            lastStmt = stmts[i];
+            break;
+        }
+    }
+    const lastSeg = lastStmt.split("|").at(-1)?.trim() ?? "";
+    const tokens = lastSeg.split(/\s+/).filter(Boolean);
+    let i = 0;
+    while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i]))
+        i++;
+    const name = tokens[i]?.split("/").pop() ?? "";
+    if (name === "git") {
+        for (let j = i + 1; j < tokens.length; j++) {
+            const t = tokens[j];
+            if (t.startsWith("-")) {
+                if (t === "-C" || t === "-c")
+                    j++;
+                continue;
+            }
+            if (t === "grep")
+                return "No matches found";
+            if (t === "diff")
+                return "Files differ";
+            return undefined;
+        }
+        return undefined;
+    }
+    return EXIT1_INTERPRETATION[name];
+}
+function dataUriImageFromStdout(stdout) {
+    const t = stdout.trim();
+    const m = /^data:image\/[a-z0-9.+_-]+;base64,([A-Za-z0-9+/=\s]+)$/i.exec(t);
+    if (!m)
+        return undefined;
+    const data = m[1].replace(/\s/g, "");
+    if (data.length === 0 || data.length > MCP_IMAGE_MAX_BASE64)
+        return undefined;
+    const bytes = Buffer.from(data, "base64");
+    for (const mime of ["image/png", "image/jpeg", "image/gif", "image/webp"]) {
+        if (imageMagicMatches(bytes, mime))
+            return { data, mime };
+    }
+    return undefined;
+}
+async function isDeadCwd(env, dir) {
+    const info = await env.fileInfo(dir);
+    if (!info.ok)
+        return info.error.code === "not_found";
+    if (info.value.kind === "directory")
+        return false;
+    if (info.value.kind === "symlink") {
+        const target = await env.canonicalPath(dir);
+        return !target.ok;
+    }
+    return true;
+}
+async function diagnoseDeadCwd(env, toolName, effectiveCwd, root, cwdRef) {
+    if (!(await isDeadCwd(env, effectiveCwd)))
+        return undefined;
+    if (cwdRef && cwdRef.current !== root) {
+        if (!(await isDeadCwd(env, root))) {
+            cwdRef.current = root;
+            return (`Error (${toolName}): command did not run — the working directory no longer exists (or is no longer a directory): ${effectiveCwd}\n` +
+                `(it was likely deleted or replaced by a previous command). The working directory has been reset to ${root}; ` +
+                `re-run your command (cd first if you need a different directory).`);
+        }
+        return (`Error (${toolName}): command did not run — the working directory ${effectiveCwd} AND the task root ${root} no longer exist. ` +
+            `The shell has no usable directory to run in; this task cannot recover its working tree.`);
+    }
+    return (`Error (${toolName}): command did not run — the task root directory no longer exists (or is no longer a directory): ${effectiveCwd}. ` +
+        `It was likely deleted by a previous command (e.g. rm -rf on the current directory). There is no directory to reset to; ` +
+        `this task cannot recover its working tree.`);
+}
+const AUTO_BACKGROUND_BLOCKED_FIRST_WORDS = new Set(["sleep"]);
+function stripAutoBackgroundWrapperPrefixes(segment) {
+    let s = segment.trim();
+    const wrappers = [
+        /^timeout\s+(?:-[A-Za-z]\S*\s+)*\d+(?:\.\d+)?[smhd]?\s+/,
+        /^time\s+/,
+        /^nice(?:\s+-n?\s*-?\d+)?\s+/,
+        /^nohup\s+/,
+        /^command\s+/,
+        /^builtin\s+/,
+        /^stdbuf(?:\s+-[ioe]\S+)+\s+/,
+        /^noglob\s+/,
+        /^[A-Za-z_][A-Za-z0-9_]*=\S+\s+/,
+    ];
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const re of wrappers) {
+            const stripped = s.replace(re, "");
+            if (stripped !== s) {
+                s = stripped.trim();
+                changed = true;
+            }
+        }
+    }
+    return s;
+}
+function commandBasename(token) {
+    const idx = token.lastIndexOf("/");
+    return idx === -1 ? token : token.slice(idx + 1);
+}
+export function canAutoBackground(command) {
+    const segments = command
+        .split(/&&|\|\||;|\||\r?\n/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (segments.length === 0)
+        return true;
+    for (const seg of segments) {
+        const tokens = stripAutoBackgroundWrapperPrefixes(seg).split(/\s+/);
+        const word = commandBasename(tokens[0] ?? "");
+        if (word === "git")
+            return false;
+        if (word === "xargs" && tokens.slice(1).some((t) => commandBasename(t) === "git"))
+            return false;
+    }
+    const firstWord = commandBasename(stripAutoBackgroundWrapperPrefixes(segments[0]).split(/\s+/)[0] ?? "");
+    if (AUTO_BACKGROUND_BLOCKED_FIRST_WORDS.has(firstWord))
+        return false;
+    return true;
+}
+async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef, detach, execClamp, toolCallId, readOnly) {
+    let timeout = Math.min(BASH_MAX_TIMEOUT_SEC, Math.max(1, Math.floor(timeoutSec ?? BASH_DEFAULT_TIMEOUT_SEC)));
+    const requestedSec = timeout;
+    let clampedByDeadline = false;
+    let deadlineExhausted = false;
+    if (execClamp) {
+        const deadline = execClamp.deadlineMs();
+        if (deadline !== undefined) {
+            const rawRemainSec = Math.floor((deadline - Date.now()) / 1000);
+            const maxSec = Math.max(1, rawRemainSec);
+            if (maxSec < timeout) {
+                execClamp.onClamp?.(timeout, maxSec);
+                timeout = maxSec;
+                clampedByDeadline = true;
+                deadlineExhausted = rawRemainSec < 1;
+            }
+        }
+    }
+    const effectiveCwd = cwdRef ? cwdRef.current : cwd;
+    const toRun = cwdRef
+        ? `${command}\n__cc_rc=$?; printf '%s%s%s' '${CWD_SENTINEL}' "$(pwd)" '${CWD_SENTINEL}' 1>&2; exit $__cc_rc`
+        : command;
+    const execEnv = cwdRef ? { env: { PWD: effectiveCwd } } : undefined;
+    let deregisterKill;
+    const registerKillHandle = execClamp?.registerKillHandle;
+    let res;
+    try {
+        res = await env.exec(toRun, {
+            cwd: effectiveCwd,
+            timeout,
+            abortSignal: signal,
+            ...execEnv,
+            ...(detach
+                ? {
+                    detachSignal: detach.signal,
+                    onDetachAdopted: () => {
+                        deregisterKill?.();
+                        deregisterKill = undefined;
+                    },
+                    autoBackgroundOnTimeout: detach.autoBackgroundEligible === true && !clampedByDeadline,
+                }
+                : {}),
+            ...(registerKillHandle !== undefined && toolCallId !== undefined
+                ? {
+                    onSpawn: (handle) => {
+                        deregisterKill = registerKillHandle(toolCallId, handle);
+                    },
+                }
+                : {}),
+        });
+    }
+    finally {
+        deregisterKill?.();
+    }
+    if (!res.ok) {
+        if (res.error.code === "spawn_error" || res.error.code === "shell_unavailable") {
+            const diagnosis = await diagnoseDeadCwd(env, toolName, effectiveCwd, cwd, cwdRef);
+            throw new Error(diagnosis ?? `Error (${toolName}): command did not run (${res.error.code}): ${res.error.message}`);
+        }
+        if (res.error.code === "transport_lost") {
+            return {
+                content: `Error (${toolName}): connection to the execution environment was lost — the command's outcome is unknown and it may still be running. Verify its effects before retrying; retry only if the command is idempotent. (${res.error.message})`,
+                details: { type: "bash", transportLost: true },
+                isError: true,
+            };
+        }
+        if (res.error.code === "timeout" || res.error.code === "aborted" || res.error.code === "callback_error") {
+            const rawStdout = res.error.partialStdout ?? "";
+            const rawStderr = res.error.partialStderr ?? "";
+            const cutOverflowFile = rawStdout.length > bashMaxOutputChars() || rawStderr.length > bashMaxOutputChars()
+                ? await writeShellOverflowFile(env, rawStdout, rawStderr)
+                : undefined;
+            const pStdout = clipShellOutput(rawStdout);
+            const pStderr = clipShellOutput(rawStderr);
+            const headline = res.error.code === "timeout"
+                ? clampedByDeadline
+                    ? deadlineExhausted
+                        ? `Command was cut off after ${timeout}s — NOT its requested ${requestedSec}s timeout: the task's wall-clock deadline has already been reached, so the command only got a ${timeout}s grace window. The process was killed; output produced before the cutoff is shown below. Do NOT retry this foreground command — there is no time left. Use run_in_background (exempt from this clamp) if the work must continue, or write out your results now.`
+                        : `Command was cut off after ${timeout}s — NOT its requested ${requestedSec}s timeout: the task is near its wall-clock deadline, so the foreground time budget was clamped to the ${timeout}s remaining. The process was killed; output produced before the cutoff is shown below. Do NOT retry this foreground command — the next attempt gets even less time. Use run_in_background (exempt from this clamp) if the work must continue, or write out your results now.`
+                    : `Command timed out after ${timeout}s (timeout limit: ${timeout}s). The process was killed; output produced before the cutoff is shown below. Re-running the same command will likely time out again — consider run_in_background for long commands, a narrower command, or resuming from the partial progress below.`
+                : res.error.code === "aborted"
+                    ? `Command was interrupted (aborted) before completion. Output produced before the interrupt is shown below.`
+                    : `Command started but its completion could not be observed — a host-side output-stream callback failed mid-run and the process was terminated (${res.error.message}). Output captured before the cut is shown below; its effects up to that point may have landed. Verify before assuming it needs a full re-run.`;
+            const captured = (pStdout ? `--- partial stdout ---\n${pStdout}` : "") +
+                (pStderr ? `${pStdout ? "\n" : ""}--- partial stderr ---\n${pStderr}` : "");
+            const body = captured.length > 0
+                ? `\n${delimitUntrusted("partial command output", captured)}`
+                : `\n(no output was produced before the cutoff)`;
+            const overflowNote = cutOverflowFile !== undefined ? shellRecoveryHint(cutOverflowFile, readOnly) : "";
+            return {
+                content: `Error (${toolName}): ${headline}${body}${overflowNote}`,
+                details: {
+                    type: "bash",
+                    stdout: pStdout,
+                    stderr: pStderr,
+                    exitCode: null,
+                    ...(cutOverflowFile !== undefined ? { output_file: cutOverflowFile } : {}),
+                    ...(res.error.code === "timeout"
+                        ? {
+                            timedOut: true,
+                            timeoutSec: timeout,
+                            ...(clampedByDeadline ? { requestedTimeoutSec: requestedSec, clampedByDeadline: true } : {}),
+                        }
+                        : res.error.code === "aborted"
+                            ? { aborted: true }
+                            : { callbackError: true }),
+                },
+            };
+        }
+        return {
+            content: `Error (${toolName}): command execution failed (${res.error.code}): ${res.error.message}. Whether the command started or completed could not be determined — verify its effects before retrying.`,
+            details: { type: "bash" },
+            isError: true,
+        };
+    }
+    if (res.value.detached && detach) {
+        return await detach.onDetached(res.value.detached.shellId, res.value.stdout, res.value.stderr, res.value.detached.cause);
+    }
+    let { stderr } = res.value;
+    const { stdout, exitCode } = res.value;
+    if (cwdRef) {
+        const m = stderr.match(new RegExp(`${CWD_SENTINEL}([\\s\\S]*?)${CWD_SENTINEL}`));
+        if (m) {
+            stderr = stderr.replace(m[0], "");
+            const captured = m[1].trim();
+            const windowsWorld = /^[A-Za-z]:[\\/]/.test(cwdRef.current);
+            const msys = /^\/([A-Za-z])(\/.*)?$/.exec(captured);
+            if (/^[A-Za-z]:[\\/]/.test(captured))
+                cwdRef.current = captured;
+            else if (windowsWorld && msys)
+                cwdRef.current = `${msys[1]}:${msys[2] ?? "/"}`;
+            else if (captured.startsWith("/") && !windowsWorld)
+                cwdRef.current = captured;
+        }
+    }
+    const clippedStdout = clipShellOutput(stdout);
+    const clippedStderr = clipShellOutput(stderr);
+    const stdoutImage = dataUriImageFromStdout(stdout);
+    if (stdoutImage) {
+        const imgOverflowFile = stderr.length > bashMaxOutputChars() ? await writeShellOverflowFile(env, "", stderr) : undefined;
+        const imgOverflowNote = imgOverflowFile !== undefined ? shellRecoveryHint(imgOverflowFile, readOnly) : "";
+        return {
+            content: [
+                { type: "image", data: stdoutImage.data, mimeType: stdoutImage.mime },
+                { type: "text", text: `exit code: ${exitCode}\n[Image data detected in stdout and shown above]${stderr.trim() !== "" ? `\n--- stderr ---\n${clippedStderr}` : ""}${imgOverflowNote}` },
+            ],
+            details: { type: "bash", stdout: "[image data]", stderr: clippedStderr, exitCode, isImage: true, ...(imgOverflowFile !== undefined ? { output_file: imgOverflowFile } : {}) },
+        };
+    }
+    const cleanOverflowFile = stdout.length > bashMaxOutputChars() || stderr.length > bashMaxOutputChars() ? await writeShellOverflowFile(env, stdout, stderr) : undefined;
+    const overflowNote = cleanOverflowFile !== undefined ? shellRecoveryHint(cleanOverflowFile, readOnly) : "";
+    const exit1Note = exitCode === 1 ? bashExitOneInterpretation(command) : undefined;
+    const parts = [`exit code: ${exitCode}${exit1Note ? ` (${exit1Note} — exit 1 from this command is not an error)` : ""}`, `--- stdout ---\n${clippedStdout || "(empty)"}`];
+    if (stderr.trim() !== "")
+        parts.push(`--- stderr ---\n${clippedStderr}`);
+    if (overflowNote)
+        parts.push(overflowNote.trim());
+    return {
+        content: parts.join("\n"),
+        details: {
+            type: "bash",
+            stdout: clippedStdout,
+            stderr: clippedStderr,
+            exitCode,
+            ...(exit1Note ? { returnCodeInterpretation: exit1Note } : {}),
+            ...(cleanOverflowFile !== undefined ? { output_file: cleanOverflowFile } : {}),
+        },
+    };
+}
+function bashDescription(coAuthor, bgNotifies = false, bgRetained = false) {
+    const coAuthorLines = coAuthor === false
+        ? "- Follow the deployment's commit-message conventions."
+        : `- End git commit messages with:\nCo-Authored-By: ${coAuthor}`;
+    return `Executes a bash command and returns its output.
+
+- Working directory persists between calls, but prefer absolute paths — a \`cd\` carries over and moves the base for every later command. Shell state (env vars, functions) does not persist; the shell is re-initialized each call, starting at the configured root.
+- IMPORTANT: Avoid using this tool to run \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user.
+- File search by name: use the Glob tool (NOT \`find\` or \`ls\`); content search: use the Grep tool (NOT \`grep\`/\`rg\` in the shell).
+- \`timeout\` is in milliseconds: default ${BASH_DEFAULT_TIMEOUT_MS}, max ${BASH_MAX_TIMEOUT_MS}.
+- \`run_in_background\` runs the command detached: it keeps running across turns and ${bgNotifies ? "re-invokes you when it exits" : "you read its output later with TaskOutput(task_id)"}. No \`&\` needed.${bgRetained ? "" : " Background processes do NOT survive the session — they are reaped when the task ends. A deliverable that must stay alive afterwards (a server, a daemon) needs a self-detaching FOREGROUND start instead: run `nohup cmd >log 2>&1 &` as a normal foreground command (portable; setsid does not exist on macOS), or use a service manager."}
+
+# Git
+- Interactive flags (\`-i\`, e.g. \`git rebase -i\`, \`git add -i\`) are not supported in this environment.
+- Use the \`gh\` CLI for GitHub operations (PRs, issues, API).
+- Commit or push only when the user asks. If on the default branch, branch first.
+${coAuthorLines}
+
+# Notes
+- The shell is NOT sandboxed by this tool: a command can read or write any reachable path and use the network. Every call is subject to the deployment's approval policy (it may be denied or require confirmation); a denied call should not be retried verbatim.
+- Treat evidence of a deployment restriction — "Operation not permitted", "Read-only file system", a denied path, or a network failure — as a boundary, not a bug: adjust within the allowed scope or report the limit; don't reach for a destructive or privilege-escalating workaround.`;
+}
+export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = { current: rootCanonical }, taskOpts = {}) {
+    const bgNotifies = taskOpts.taskRegistry !== undefined && taskOpts.onTaskNotification !== undefined;
+    const bgRetained = hasBackgroundShell(env) && env.backgroundCapabilities.retainBackgroundProcesses === true;
+    return defineTool({
+        name: "Bash",
+        contract: { contractId: "core.bash@1", implementationRevision: "1" },
+        description: bashDescription(coAuthor, bgNotifies, bgRetained),
+        parameters: Type.Object({
+            command: Type.String({ description: "The command to execute" }),
+            timeout: Type.Optional(Type.Number({ description: `Optional timeout in milliseconds (max ${BASH_MAX_TIMEOUT_MS})` })),
+            description: Type.Optional(Type.String({
+                description: 'Clear, concise description of what this command does in active voice. Never use words like "complex" or "risk" in the description - just describe what it does.\n' +
+                    "\n" +
+                    "For simple commands (git, npm, standard CLI tools), keep it brief (5-10 words):\n" +
+                    '- ls → "List files in current directory"\n' +
+                    '- git status → "Show working tree status"\n' +
+                    '- npm install → "Install package dependencies"\n' +
+                    "\n" +
+                    "For commands that are harder to parse at a glance (piped commands, obscure flags, etc.), add enough context to clarify what it does:\n" +
+                    '- find . -name "*.tmp" -exec rm {} \\; → "Find and delete all .tmp files recursively"\n' +
+                    '- git reset --hard origin/main → "Discard all local changes and match remote main"\n' +
+                    "- curl -s url | jq '.data[]' → \"Fetch JSON from URL and extract data array elements\"",
+            })),
+            run_in_background: Type.Optional(Type.Boolean({
+                description: "Set to true to run this command in the background.",
+            })),
+        }),
+        effect: "write",
+        isConcurrencySafe: (args) => {
+            const cmd = args?.command;
+            if (typeof cmd !== "string")
+                return false;
+            const bg = args.run_in_background;
+            if (bg === true)
+                return false;
+            return coarseReadonlyCheck(cmd, new Set(BASH_READONLY_DEFAULT_ALLOW)) === undefined;
+        },
+        execute: async (args, ctx) => {
+            const { command, timeout, run_in_background, description } = args;
+            if (run_in_background) {
+                if (!hasBackgroundShell(env)) {
+                    return errorResult("Error (Bash): this environment does not support background processes (run_in_background).");
+                }
+                if (cwdRef && (await isDeadCwd(env, cwdRef.current))) {
+                    const diagnosis = await diagnoseDeadCwd(env, "Bash", cwdRef.current, rootCanonical, cwdRef);
+                    if (diagnosis !== undefined)
+                        throw new Error(diagnosis);
+                }
+                const requestedTimeoutSec = timeout !== undefined ? Math.max(1, Math.round(timeout / 1000)) : undefined;
+                const r = await env.spawnBackground(command, {
+                    cwd: cwdRef.current,
+                    ...(requestedTimeoutSec !== undefined ? { timeout: requestedTimeoutSec } : {}),
+                });
+                if (!r.ok)
+                    return errorResult(`Error (Bash): ${r.error.message}`);
+                const bgCaps = env.backgroundCapabilities;
+                const appliedTimeoutSec = typeof bgCaps.defaultBgTimeoutSec === "number" && typeof bgCaps.maxBgTimeoutSec === "number"
+                    ? Math.min(requestedTimeoutSec ?? bgCaps.defaultBgTimeoutSec, bgCaps.maxBgTimeoutSec)
+                    : undefined;
+                const budgetNote = appliedTimeoutSec !== undefined ? ` Time budget: auto-terminates if still running after ${appliedTimeoutSec}s (hard cap ${bgCaps.maxBgTimeoutSec}s).` : "";
+                const lifetimeNote = bgCaps.retainBackgroundProcesses === true
+                    ? ""
+                    : ` NOTE: background processes do NOT survive the session (reaped at task end). If this is a deliverable service that must stay alive afterwards, host it with a FOREGROUND command instead: \`nohup cmd >log 2>&1 &\` (self-detaching — survives the session).`;
+                if (taskOpts.taskRegistry) {
+                    const sessionScoped = taskOpts.sessionId !== undefined;
+                    const owner = sessionScoped ? taskOpts.sessionId : (ctx.taskId ?? taskOpts.taskOwner);
+                    const scope = ctx.principal ?? taskOpts.taskScope;
+                    const onNotify = taskOpts.onTaskNotification;
+                    let outputFile;
+                    if (onNotify !== undefined) {
+                        const tf = await env.createTempFile({ prefix: "bash-task-", suffix: ".output" });
+                        if (tf.ok) {
+                            const tfCanon = await env.canonicalPath(tf.value);
+                            outputFile = tfCanon.ok ? tfCanon.value : tf.value;
+                        }
+                    }
+                    let taskId;
+                    try {
+                        taskId = taskOpts.taskRegistry.registerBackgroundBash({
+                            env,
+                            shellId: r.value.shellId,
+                            description: description ?? command,
+                            toolUseId: ctx.toolCallId,
+                            ...(owner !== undefined ? { owner } : {}),
+                            ...(scope !== undefined ? { scope } : {}),
+                            ...(sessionScoped ? { sessionScoped: true } : {}),
+                            ...(outputFile !== undefined ? { outputFile } : {}),
+                            ...(onNotify !== undefined ? { onTerminal: (n) => onNotify(n, { priority: "next" }) } : {}),
+                        });
+                    }
+                    catch (e) {
+                        const reason = e instanceof Error ? e.message : String(e);
+                        let kill;
+                        try {
+                            kill = await env.killBackground(r.value.shellId);
+                        }
+                        catch {
+                            kill = undefined;
+                        }
+                        if (kill !== undefined && (kill.ok || kill.error.code === "not_found")) {
+                            return errorResult(`Error (Bash): background process was started but could not be registered (${reason}); it has been terminated.`);
+                        }
+                        const killMsg = kill !== undefined && !kill.ok ? kill.error.message : "killBackground threw";
+                        return {
+                            content: `Error (Bash): background process was started but could not be registered (${reason}), and the cleanup kill failed (${killMsg}). ` +
+                                `The process could NOT be terminated — it may still be running, but it has no task_id, so TaskOutput/TaskStop cannot reach it. ` +
+                                `If it must be stopped, kill it manually (e.g. \`pkill -f\` on its command line).`,
+                            details: { type: "bash", registerFailed: true, killFailed: true },
+                            isError: true,
+                        };
+                    }
+                    const interimNote = outputFile !== undefined
+                        ? ` Output file: ${outputFile} (full output is appended there — Read it any time).`
+                        : ` Use TaskOutput("${taskId}") to check interim output.`;
+                    return onNotify !== undefined
+                        ? `Command running in background; task_id=${taskId}.${interimNote} You will be notified when it completes — do not poll; ` +
+                            `end your turn if nothing else is pending. TaskStop("${taskId}") to stop.` +
+                            budgetNote +
+                            lifetimeNote
+                        : `Started in background; task_id=${taskId}. ` +
+                            `Use TaskOutput("${taskId}") to read output (poll until status is no longer "running"); ` +
+                            `TaskStop("${taskId}") to stop. No '&' needed.` +
+                            budgetNote +
+                            lifetimeNote;
+                }
+                return (`Started in background; task_id=${r.value.shellId}. Legacy bash_id=${r.value.shellId}. ` +
+                    `Use TaskOutput("${r.value.shellId}") to read output (poll until status is no longer "running"); ` +
+                    `TaskStop("${r.value.shellId}") to stop. No '&' needed.` +
+                    budgetNote +
+                    lifetimeNote);
+            }
+            const detachChain = taskOpts.detachHub && taskOpts.taskRegistry && hasBackgroundShell(env) && env.backgroundCapabilities.supportsDetach === true
+                ? {
+                    signal: taskOpts.detachHub.signalFor(ctx.toolCallId),
+                    onDetached: async (shellId, stdoutSoFar, stderrSoFar, cause) => {
+                        const sessionScoped = taskOpts.sessionId !== undefined;
+                        const owner = sessionScoped ? taskOpts.sessionId : (ctx.taskId ?? taskOpts.taskOwner);
+                        const scope = ctx.principal ?? taskOpts.taskScope;
+                        const onNotify = taskOpts.onTaskNotification;
+                        let outputFile;
+                        if (onNotify !== undefined) {
+                            const tf = await env.createTempFile({ prefix: "bash-task-", suffix: ".output" });
+                            if (tf.ok) {
+                                const tfCanon = await env.canonicalPath(tf.value);
+                                outputFile = tfCanon.ok ? tfCanon.value : tf.value;
+                            }
+                        }
+                        let taskId;
+                        try {
+                            taskId = taskOpts.taskRegistry.registerBackgroundBash({
+                                env: env,
+                                shellId: shellId,
+                                description: description ?? command,
+                                toolUseId: ctx.toolCallId,
+                                ...(owner !== undefined ? { owner } : {}),
+                                ...(scope !== undefined ? { scope } : {}),
+                                ...(sessionScoped ? { sessionScoped: true } : {}),
+                                ...(outputFile !== undefined ? { outputFile } : {}),
+                                ...(onNotify !== undefined ? { onTerminal: (n) => onNotify(n, { priority: "next" }) } : {}),
+                            });
+                        }
+                        catch (e) {
+                            const reason = e instanceof Error ? e.message : String(e);
+                            let kill;
+                            try {
+                                kill = await env.killBackground(shellId);
+                            }
+                            catch {
+                                kill = undefined;
+                            }
+                            const killed = kill !== undefined && (kill.ok || kill.error.code === "not_found");
+                            const outTail = stdoutSoFar.slice(-1_000);
+                            const errTail = stderrSoFar.slice(-1_000);
+                            const tails = (outTail ? `\n--- output so far (tail) ---\n${outTail}` : "") +
+                                (errTail ? `\n--- stderr so far (tail) ---\n${errTail}` : "");
+                            if (killed) {
+                                return {
+                                    content: `Error (Bash): command was detached to the background but could not be registered (${reason}); ` +
+                                        `it has been terminated (an unregistered background process would have no task_id and could not be read or stopped).` +
+                                        tails,
+                                    details: { type: "bash", detached: true, registerFailed: true },
+                                    isError: true,
+                                };
+                            }
+                            const killMsg = kill !== undefined && !kill.ok ? kill.error.message : "killBackground threw";
+                            return {
+                                content: `Error (Bash): command was detached to the background but could not be registered (${reason}), and the cleanup kill failed (${killMsg}). ` +
+                                    `The process could NOT be terminated — it may still be running, but it has no task_id, so TaskOutput/TaskStop cannot reach it. ` +
+                                    `If it must be stopped, kill it manually (e.g. \`pkill -f\` on its command line).` +
+                                    tails,
+                                details: { type: "bash", detached: true, registerFailed: true, killFailed: true },
+                                isError: true,
+                            };
+                        }
+                        const tail = stdoutSoFar.slice(-1_000);
+                        const adoptCaps = env.backgroundCapabilities;
+                        const adoptBudgetNote = typeof adoptCaps.defaultBgTimeoutSec === "number" && typeof adoptCaps.maxBgTimeoutSec === "number"
+                            ? ` Time budget: auto-terminates if still running after ${Math.min(adoptCaps.defaultBgTimeoutSec, adoptCaps.maxBgTimeoutSec)}s (hard cap ${adoptCaps.maxBgTimeoutSec}s).`
+                            : "";
+                        return {
+                            content: (cause === "timeout"
+                                ? `Command exceeded its timeout but is still running — moved to background instead of being killed (task_id=${taskId}). `
+                                : `Command moved to background; task_id=${taskId}. `) +
+                                (outputFile !== undefined
+                                    ? `Output file: ${outputFile} (full output is appended there — Read it any time). `
+                                    : `Use TaskOutput("${taskId}") to read its output. `) +
+                                `TaskStop("${taskId}") to stop it. ` +
+                                (onNotify !== undefined
+                                    ? `You will be notified when it completes — do not poll.`
+                                    : `Poll TaskOutput until its status is no longer "running".`) +
+                                adoptBudgetNote +
+                                (tail ? `\n--- output so far (tail) ---\n${tail}` : ""),
+                            details: { type: "bash", detached: true, task_id: taskId, ...(description !== undefined ? { description } : {}), ...(outputFile !== undefined ? { output_file: outputFile } : {}), ...(cause === "timeout" ? { autoBackgrounded: true } : {}) },
+                        };
+                    },
+                    autoBackgroundEligible: taskOpts.autoBackgroundOnTimeout === true && canAutoBackground(command),
+                }
+                : undefined;
+            let res;
+            try {
+                res = await runShell(env, rootCanonical, "Bash", command, msTimeoutToSec(timeout), ctx.signal, cwdRef, detachChain, taskOpts.execClamp, ctx.toolCallId, false);
+            }
+            finally {
+                taskOpts.detachHub?.gc(ctx.toolCallId);
+            }
+            const detached = typeof res !== "string" && res.details.detached === true;
+            const resText = typeof res === "string" ? res : typeof res.content === "string" ? res.content : undefined;
+            const hint = detached || resText === undefined ? undefined : ghRateLimitHint(command, resText);
+            const withHint = hint === undefined ? res : typeof res === "string" ? `${res}\n\n${hint}` : { ...res, content: `${resText}\n\n${hint}` };
+            if (typeof withHint === "string" || description === undefined)
+                return withHint;
+            if (withHint.details.detached)
+                return withHint;
+            return { ...withHint, details: { ...withHint.details, description } };
+        },
+    });
+}
+export function createBashReadonlyTool(env, rootCanonical, allow, execClamp) {
+    const sample = [...allow].slice(0, 6).join(", ");
+    return defineTool({
+        name: "Bash",
+        contract: { contractId: "core.bash_readonly@1", implementationRevision: "1" },
+        description: `Run a SINGLE read-only inspection command (e.g. ${sample}, …) and return its output. Shell ` +
+            "operators (pipes, redirects, ;, &&, command substitution, subshells) are rejected and only " +
+            "allowlisted commands run. Still subject to the deployment's approval policy.",
+        parameters: Type.Object({
+            command: Type.String({ description: "A single allowlisted read-only command (no shell operators)." }),
+            timeout: Type.Optional(Type.Number({ description: `Timeout in milliseconds (default ${BASH_DEFAULT_TIMEOUT_MS}, max ${BASH_MAX_TIMEOUT_MS}).` })),
+        }),
+        effect: "read",
+        execute: async (args, ctx) => {
+            const { command, timeout } = args;
+            const reason = coarseReadonlyCheck(command, allow);
+            if (reason)
+                return errorResult(`Error (Bash): ${reason}`);
+            return runShell(env, rootCanonical, "Bash", command, msTimeoutToSec(timeout), ctx.signal, undefined, undefined, execClamp, ctx.toolCallId, true);
+        },
+    });
+}
+export function createEnvTaskOutputTool(env) {
+    return defineTool({
+        name: TASK_OUTPUT_TOOL_NAME,
+        aliases: [...TASK_OUTPUT_ALIASES],
+        contract: TASK_OUTPUT_CONTRACT,
+        description: composeTaskOutputDescription(ENV_DIRECT_TASK_TOOL_CAPS),
+        parameters: composeTaskOutputParams(ENV_DIRECT_TASK_TOOL_CAPS),
+        effect: "read",
+        execute: async (args) => {
+            const { task_id, bash_id, runId, filter } = args;
+            const id = resolveTaskIdArg(task_id, bash_id, runId);
+            if (!id)
+                return errorResult(TASK_OUTPUT_MISSING_ID_MESSAGE);
+            if (!hasBackgroundShell(env)) {
+                return errorResult("Error (TaskOutput): this environment does not support background processes.");
+            }
+            let rx;
+            if (filter !== undefined) {
+                try {
+                    rx = new RegExp(filter);
+                }
+                catch {
+                    return errorResult(`Error (TaskOutput): invalid filter regex: ${filter}`);
+                }
+            }
+            const r = await env.pollBackground(id);
+            if (!r.ok)
+                return errorResult(`Error (TaskOutput): ${r.error.message}`);
+            const shape = (text) => clipShellOutput(rx ? text.split(/\r?\n/).filter((l) => rx.test(l)).join("\n") : text);
+            const status = r.value.status === "exited" ? `exited(code ${r.value.exitCode})` : r.value.status;
+            const dropped = r.value.bytesDroppedBeforeCursor ?? 0;
+            const droppedNote = dropped > 0 ? `[!] ${dropped} earlier byte(s) permanently dropped before this window (8MB buffer evicted)\n` : "";
+            const body = `status: ${status}\n${droppedNote}--- new stdout ---\n${shape(r.value.stdout) || "(none)"}\n` +
+                `--- new stderr ---\n${shape(r.value.stderr) || "(none)"}`;
+            return delimitUntrusted(`TaskOutput ${id}`, body);
+        },
+    });
+}
+export function createEnvTaskStopTool(env, registry = defaultTaskRegistry) {
+    return defineTool({
+        name: TASK_STOP_TOOL_NAME,
+        aliases: [...TASK_STOP_ALIASES],
+        contract: TASK_STOP_CONTRACT,
+        description: composeTaskStopDescription(ENV_DIRECT_TASK_TOOL_CAPS),
+        parameters: TASK_STOP_PARAMS,
+        effect: "write",
+        execute: async (args) => {
+            const { task_id, shell_id, runId } = args;
+            const id = resolveTaskIdArg(task_id, shell_id, runId);
+            if (!id)
+                return errorResult(TASK_STOP_MISSING_ID_MESSAGE);
+            if (!hasBackgroundShell(env)) {
+                return errorResult("Error (TaskStop): this environment does not support background processes.");
+            }
+            registry.markStopSourceByShellId(id, "parent", env);
+            const r = await env.killBackground(id);
+            if (!r.ok) {
+                registry.clearPendingStopSourceByShellId(id, "parent", env);
+                return errorResult(`${id} is unknown or has already ended.`);
+            }
+            return `Terminated ${id}.`;
+        },
+    });
+}