@sema-agent/core 1.450.0 → 1.452.0

package/dist/tools/fs/index.js

@@ -1,13 +1,14 @@
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
-import { defineTool } from "../../core/tools.js";
+import { defineTool, errorResult } from "../../core/tools.js";
 import { createTaskOutputTool, createTaskStopTool, defaultTaskRegistry } from "../../core/task-registry.js";
 import { hasBackgroundShell } from "../../core/background-shell.js";
 import { delimitUntrusted } from "../../core/untrusted-text.js";
 import { clipWithFilePointer } from "../../core/tool-errors.js";
 import { sha256, resolveKey, violationText, requireRead, checkStale, checkEditMatch, checkNoChange, hasBinaryExtension, isBinaryContent, fileArgPath, imageMimeForRead, imageMagicMatches, similarNameSuggestion, resolveQuoteMatch, adaptNewStringQuotes, deletionOldString, countOccurrences, OVERSIZE_READ_ESCAPE_HINT, isBlockedDevicePath, normalizeAbsPathLexically, } from "./safety.js";
-import { decodeTextBytes, encodeTextForFile, normalizeEditText } from "./encoding.js";
+import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText, splitLeadingBom } from "./encoding.js";
 import { runGrepDetailed, runGlobDetailed, splitAbsoluteGlobPattern, shellQuote } from "./search.js";
+import { isNotebookPath, parseNotebookCells, renderNotebookCells, stripNotebookImageData, NOTEBOOK_IMAGE_BASE64_BUDGET } from "./notebook.js";
 import { makeRepoMapTool } from "./repo-map.js";
 import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { MCP_IMAGE_MAX_BASE64, IMAGE_TARGET_RAW_SIZE, sharpImageDownsampler } from "../../core/mcp.js";
@@ -35,10 +36,13 @@ function decodeEditBytes(bytes, path) {
         return { ok: false, message: `Error (Edit): "${path}" is too large to edit (${formatByteSize(bytes.byteLength)}). Maximum editable file size is ${formatByteSize(MAX_EDIT_BYTES)}.` };
     }
 }
+function persistedTextOf(encoded) {
+    return decodeTextBytes(typeof encoded === "string" ? Buffer.from(encoded, "utf8") : encoded).text;
+}
 async function notReadRefusalText(env, toolName, key, v, signal) {
     const base = `Error (${toolName}): ${v.message}`;
     const info = await env.fileInfo(key, signal);
-    return info.ok && info.value.kind !== "directory" && info.value.size > MAX_READ_BYTES ? `${base} ${OVERSIZE_READ_ESCAPE_HINT}` : base;
+    return info.ok && info.value.kind !== "directory" && info.value.size > MAX_READ_BYTES && !isNotebookPath(key) ? `${base} ${OVERSIZE_READ_ESCAPE_HINT}` : base;
 }
 const MAX_IMAGE_READ_BYTES = 5 * 1024 * 1024;
 const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES = 64 * 1024 * 1024;
@@ -107,7 +111,7 @@ export function isReadDedupStubResult(resultText) {
         resultText.includes("has not changed on disk. Use that content instead of re-reading"));
 }
 export function seedReadFileStateFromContext(state, key, content) {
-    state.set(key, { hash: sha256(content), totalLines: countLines(content), truncated: false, lastReadAt: Date.now(), seededFromContext: true });
+    state.set(key, { hash: sha256(normalizeFileText(content)), totalLines: countLines(content), truncated: false, lastReadAt: Date.now(), seededFromContext: true });
 }
 export function applyCompactionToReadFileState(state, attachedComplete, preserveKeys = []) {
     const preserve = new Set(preserveKeys);
@@ -371,6 +375,9 @@ async function readPdfFile(env, path, key, pages, signal, downsamplerOpt, cwd, p
         },
     };
 }
+function pdfResultToToolReturn(r) {
+    return typeof r === "string" ? errorResult(r) : r;
+}
 export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRoots, imageDownsampler, pdfCapabilities, bgOutputReadExemption) {
     return defineTool({
         name: "Read",
@@ -381,7 +388,7 @@ export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRo
             "- By default, it reads the whole file (from `offset`, 1-based); a very large file is served as a partial view with an explicit marker and the next-page call.\n" +
             "- When you already know which part of the file you need, only read that part. This can be important for larger files.\n" +
             "- Results are returned using cat -n format, with line numbers starting at 1\n" +
-            "- Reads images (PNG, JPG, …) and presents them visually. Reads PDFs via the `pages` parameter (e.g. \"1-5\", max 20 pages/request; a PDF whose detected page count exceeds 10 requires `pages`). Reads Jupyter notebooks (.ipynb) as JSON text.\n" +
+            "- Reads images (PNG, JPG, …) and presents them visually. Reads PDFs via the `pages` parameter (e.g. \"1-5\", max 20 pages/request; a PDF whose detected page count exceeds 10 requires `pages`). Reads Jupyter notebooks (.ipynb) as cells with outputs (offset/limit do not apply).\n" +
             "- Reading a directory, a missing file, or an empty file returns an error or warning rather than content.\n" +
             "- Other binaries (archives, executables) are refused. A whole-file read of a text file over 256 KB is refused — read it in slices with explicit offset/limit, or Grep it instead.\n" +
             "- You must read a file before editing it.\n" +
@@ -396,6 +403,7 @@ export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRo
             "- This tool can only read files, not directories. To read a directory, use Glob/Grep or an ls command via the Bash tool.\n" +
             "- You must read a file before editing it.\n" +
             "- Reads PDFs (.pdf): the document is provided to the model directly (text layer included). Use the `pages` parameter (e.g., \"1-5\") to read a page range; a PDF whose detected page count exceeds 10 requires `pages`. Maximum 20 pages per request.\n" +
+            "- Reads Jupyter notebooks (.ipynb) as cells with outputs (offset/limit do not apply).\n" +
             "- Other binaries (archives, executables) are refused. A whole-file read of a text file over 256 KB is refused — read it in slices with explicit offset/limit, or Grep it instead.\n" +
             "- If you read a file that exists but has empty contents you will receive a warning in place of file contents.\n" +
             "- Do NOT re-read a file you just edited to verify — Edit/Write would have errored if the change failed, and the harness tracks file state for you.",
@@ -410,35 +418,36 @@ export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRo
             const { offset, limit, pages } = args;
             const path = fileArgPath(args);
             if (path === undefined)
-                return `Error (Read): file_path is required.`;
+                return errorResult(`Error (Read): file_path is required.`);
             const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, bgOutputReadExemption === undefined ? undefined : (key) => bgOutputReadExemption(key, ctx));
             if (!r.ok)
-                return violationText("Read", r.violation);
+                return errorResult(violationText("Read", r.violation));
+            const isNb = isNotebookPath(r.key);
             const imageMime = imageMimeForRead(r.key);
             if (imageMime !== undefined) {
                 const meta = await env.fileInfo(r.key, ctx.signal);
                 if (!meta.ok) {
                     const ex = await env.exists(r.key, ctx.signal);
                     if (ex.ok && !ex.value)
-                        return `Error (Read): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal)}`;
-                    return `Error (Read): cannot stat image "${path}" to verify its size before reading: ${meta.error.message}`;
+                        return errorResult(`Error (Read): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal)}`);
+                    return errorResult(`Error (Read): cannot stat image "${path}" to verify its size before reading: ${meta.error.message}`);
                 }
                 if (meta.value.kind === "directory") {
-                    return `Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`;
+                    return errorResult(`Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`);
                 }
                 const downsampler = imageDownsampler === false ? undefined : (imageDownsampler ?? (await (autoDownsampler ??= sharpImageDownsampler())));
                 const readCap = downsampler ? MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES : MAX_IMAGE_READ_BYTES;
                 if (meta.value.size > readCap) {
-                    return `Error (Read): image "${path}" is too large to read (${meta.value.size} bytes > ${readCap}-byte cap).`;
+                    return errorResult(`Error (Read): image "${path}" is too large to read (${meta.value.size} bytes > ${readCap}-byte cap).`);
                 }
                 const bin = await env.readBinaryFile(r.key, ctx.signal);
                 if (!bin.ok)
-                    return `Error (Read): cannot read image "${path}": ${bin.error.message}`;
+                    return errorResult(`Error (Read): cannot read image "${path}": ${bin.error.message}`);
                 if (bin.value.byteLength > readCap) {
-                    return `Error (Read): image "${path}" is too large to read (${bin.value.byteLength} bytes > ${readCap}-byte cap).`;
+                    return errorResult(`Error (Read): image "${path}" is too large to read (${bin.value.byteLength} bytes > ${readCap}-byte cap).`);
                 }
                 if (!imageMagicMatches(bin.value, imageMime)) {
-                    return `Error (Read): "${path}" has an image extension but its content is not a valid ${imageMime} (empty, truncated, or mis-named).`;
+                    return errorResult(`Error (Read): "${path}" has an image extension but its content is not a valid ${imageMime} (empty, truncated, or mis-named).`);
                 }
                 let base64;
                 let mime = imageMime;
@@ -453,7 +462,7 @@ export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRo
                 }
                 base64 ??= Buffer.from(bin.value).toString("base64");
                 if (base64.length > MCP_IMAGE_MAX_BASE64) {
-                    return (`Error (Read): image "${path}" is too large to send (${bin.value.byteLength} bytes; base64 ${base64.length} chars exceeds the ${MCP_IMAGE_MAX_BASE64}-char / 5MB API image limit` +
+                    return errorResult(`Error (Read): image "${path}" is too large to send (${bin.value.byteLength} bytes; base64 ${base64.length} chars exceeds the ${MCP_IMAGE_MAX_BASE64}-char / 5MB API image limit` +
                         (downsampler
                             ? "; downsampling could not bring it under the limit)."
                             : `; raw images over ${IMAGE_TARGET_RAW_SIZE} bytes always exceed it — shrink it first, e.g. with an image tool via bash).`));
@@ -476,58 +485,62 @@ export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRo
                 };
             }
             if (r.key.toLowerCase().endsWith(".pdf")) {
-                return await readPdfFile(env, path, r.key, pages, ctx.signal, imageDownsampler, cwdRef?.current ?? rootCanonical, undefined, pdfCapabilities);
+                return pdfResultToToolReturn(await readPdfFile(env, path, r.key, pages, ctx.signal, imageDownsampler, cwdRef?.current ?? rootCanonical, undefined, pdfCapabilities));
             }
             if (hasBinaryExtension(r.key)) {
-                return `Error (Read): "${path}" appears to be a binary file (by extension); this tool reads UTF-8 text only.`;
+                return errorResult(`Error (Read): "${path}" appears to be a binary file (by extension); this tool reads UTF-8 text only.`);
             }
             const info = await env.fileInfo(r.key, ctx.signal);
             if (info.ok) {
                 if (info.value.kind === "directory") {
-                    return `Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`;
+                    return errorResult(`Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`);
                 }
                 if (info.value.size > SLICED_READ_MAX_BYTES) {
-                    return (`Error (Read): "${path}" is too large to read with this tool even as an offset/limit slice ` +
+                    return errorResult(`Error (Read): "${path}" is too large to read with this tool even as an offset/limit slice ` +
                         `(${info.value.size} bytes > ${SLICED_READ_MAX_BYTES}-byte cap — the reader loads the whole file into memory before slicing). ` +
                         `Stream a portion with bash instead, e.g. \`sed -n '1,200p' <file>\` for a line range or \`head -c 65536 <file>\` for the leading bytes, or use grep to search it.`);
                 }
-                if (info.value.size > MAX_READ_BYTES && offset === undefined && limit === undefined) {
-                    return `Error (Read): "${path}" is too large to read in full (${info.value.size} bytes > ${MAX_READ_BYTES}-byte cap); pass an explicit offset/limit to read a slice, or use grep to search it instead.`;
+                if (!isNb && info.value.size > MAX_READ_BYTES && offset === undefined && limit === undefined) {
+                    return errorResult(`Error (Read): "${path}" is too large to read in full (${info.value.size} bytes > ${MAX_READ_BYTES}-byte cap); pass an explicit offset/limit to read a slice, or use grep to search it instead.`);
                 }
             }
             else {
                 const ex = await env.exists(r.key, ctx.signal);
                 if (ex.ok && !ex.value)
-                    return `Error (Read): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal)}`;
+                    return errorResult(`Error (Read): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal)}`);
             }
             const readBin = await env.readBinaryFile(r.key, ctx.signal);
             if (!readBin.ok)
-                return `Error (Read): cannot read "${path}": ${readBin.error.message}`;
+                return errorResult(`Error (Read): cannot read "${path}": ${readBin.error.message}`);
             const readSize = readBin.value.byteLength;
             if (readSize > SLICED_READ_MAX_BYTES) {
-                return (`Error (Read): "${path}" is too large to read with this tool even as an offset/limit slice ` +
+                return errorResult(`Error (Read): "${path}" is too large to read with this tool even as an offset/limit slice ` +
                     `(${readSize} bytes > ${SLICED_READ_MAX_BYTES}-byte cap — the reader loads the whole file into memory before slicing). ` +
                     `Stream a portion with bash instead, e.g. \`sed -n '1,200p' <file>\` for a line range or \`head -c 65536 <file>\` for the leading bytes, or use grep to search it.`);
             }
-            if (readSize > MAX_READ_BYTES && offset === undefined && limit === undefined) {
-                return `Error (Read): "${path}" is too large to read in full (${readSize} bytes > ${MAX_READ_BYTES}-byte cap); pass an explicit offset/limit to read a slice, or use grep to search it instead.`;
+            if (!isNb && readSize > MAX_READ_BYTES && offset === undefined && limit === undefined) {
+                return errorResult(`Error (Read): "${path}" is too large to read in full (${readSize} bytes > ${MAX_READ_BYTES}-byte cap); pass an explicit offset/limit to read a slice, or use grep to search it instead.`);
             }
             if (pdfMagicMatches(readBin.value)) {
-                return await readPdfFile(env, path, r.key, pages, ctx.signal, imageDownsampler, cwdRef?.current ?? rootCanonical, readBin.value, pdfCapabilities);
+                return pdfResultToToolReturn(await readPdfFile(env, path, r.key, pages, ctx.signal, imageDownsampler, cwdRef?.current ?? rootCanonical, readBin.value, pdfCapabilities));
             }
             const decoded = decodeTextBytes(readBin.value);
             if (decoded.malformed) {
-                return `Error (Read): "${path}" has a UTF-16 BOM but a truncated (odd-length) body — the file is corrupt or mis-labelled; repair/convert it with bash (e.g. \`iconv\`) first.`;
+                return errorResult(`Error (Read): "${path}" has a UTF-16 BOM but a truncated (odd-length) body — the file is corrupt or mis-labelled; repair/convert it with bash (e.g. \`iconv\`) first.`);
             }
             const content = decoded.text;
             if (isBinaryContent(content.slice(0, 4096))) {
-                return (`Error (Read): "${path}" appears to be a binary file (non-text content); this tool reads UTF-8 and BOM-marked UTF-16LE text only. ` +
+                return errorResult(`Error (Read): "${path}" appears to be a binary file (non-text content); this tool reads UTF-8 and BOM-marked UTF-16LE text only. ` +
                     `If it is UTF-16 without a BOM or a legacy encoding, convert it first (e.g. \`iconv -f UTF-16LE -t UTF-8\`) or inspect/transform it with bash.`);
             }
+            const nbParsed = isNb ? parseNotebookCells(content, path) : undefined;
+            const nbForced = nbParsed !== undefined && nbParsed.ok;
+            const effOffset = nbForced ? undefined : offset;
+            const effLimit = nbForced ? undefined : limit;
             const lines = content.length === 0 ? [] : content.split("\n");
             const total = lines.length;
-            const start = Math.max(1, Math.floor(offset ?? 1));
-            const max = limit !== undefined ? Math.max(1, Math.floor(limit)) : Number.MAX_SAFE_INTEGER;
+            const start = Math.max(1, Math.floor(effOffset ?? 1));
+            const max = effLimit !== undefined ? Math.max(1, Math.floor(effLimit)) : Number.MAX_SAFE_INTEGER;
             if (total > 0 && start > total) {
                 return `<system-reminder>Warning: the file exists but is shorter than the provided offset (${start}). The file has ${total} lines.</system-reminder>`;
             }
@@ -538,13 +551,41 @@ export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRo
                 end = total;
             }
             const hash = sha256(content);
+            let nbFallbackPrefix = "";
+            if (nbParsed !== undefined) {
+                if (nbParsed.ok) {
+                    const parsed = nbParsed;
+                    const rendered = renderNotebookCells(parsed.cells, NOTEBOOK_IMAGE_BASE64_BUDGET);
+                    if (rendered.textChars > MAX_READ_OUTPUT_CHARS) {
+                        return errorResult(`Error (Read): notebook "${path}" projects to ~${Math.round(rendered.textChars / 4)} tokens of cell content, over the 25000-token limit ` +
+                            `(offset/limit do not apply to notebooks — the whole notebook is always projected). Inspect portions with Bash + jq instead, e.g.\n` +
+                            `  cat "${path}" | jq '.cells[:20]' # First 20 cells\n` +
+                            `  cat "${path}" | jq '.cells | length' # Count total cells\n` +
+                            `  cat "${path}" | jq '.cells[] | select(.cell_type=="code") | .source' # All code sources`);
+                    }
+                    const prevNb = state.get(r.key);
+                    if (prevNb?.seededFromContext && prevNb.hash === hash) {
+                        return seededFileUnchangedReminder(r.key);
+                    }
+                    if (prevNb && prevNb.hash === hash && prevNb.view && prevNb.view.start === 1 && prevNb.view.end === total) {
+                        return `[${path}: unchanged since you last read it (lines 1-${total} of ${total}); content omitted to save context]`;
+                    }
+                    state.set(r.key, { hash, totalLines: countLines(content), truncated: false, view: { start: 1, end: total }, lastReadAt: Date.now() });
+                    const bodyBlocks = rendered.blocks.length > 0 ? rendered.blocks : [{ type: "text", text: "[notebook has 0 cells]" }];
+                    return {
+                        content: [...bodyBlocks, { type: "text", text: READ_CYBER_REMINDER }],
+                        details: { type: "notebook", file: { filePath: path, cells: parsed.cells.map(stripNotebookImageData) } },
+                    };
+                }
+                nbFallbackPrefix = "[not a parseable notebook — showing raw file text]\n";
+            }
             const renderBody = (sl) => sl.map((l, i) => `${start + i}\t${l}`).join("\n");
             let body = renderBody(slice);
             let pageMarker;
             if (body.length > MAX_READ_OUTPUT_CHARS) {
-                const defaultFullRead = start <= 1 && limit === undefined;
+                const defaultFullRead = start <= 1 && effLimit === undefined;
                 if (!defaultFullRead) {
-                    return `Error (Read): the requested range of "${path}" is ~${Math.round(body.length / 4)} tokens, over the 25000-token limit. Narrow it with offset/limit, or use grep to search the file.`;
+                    return errorResult(`Error (Read): the requested range of "${path}" is ~${Math.round(body.length / 4)} tokens, over the 25000-token limit. Narrow it with offset/limit, or use grep to search the file.`);
                 }
                 const approxTokens = Math.round(body.length / 4);
                 let n = Math.max(1, Math.min(slice.length, Math.floor(slice.length * (MAX_READ_OUTPUT_CHARS / body.length) * 0.95)));
@@ -580,7 +621,7 @@ export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRo
             }
             const truncated = start > 1 || end < total || pageMarker !== undefined;
             const prev = state.get(r.key);
-            if (total > 0 && prev?.seededFromContext && start === 1 && limit === undefined && prev.hash === hash) {
+            if (total > 0 && prev?.seededFromContext && start === 1 && effLimit === undefined && prev.hash === hash) {
                 return seededFileUnchangedReminder(r.key);
             }
             if (total > 0 && prev && prev.hash === hash && prev.view && prev.view.start === start && prev.view.end === end) {
@@ -598,7 +639,7 @@ export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRo
                 return `<system-reminder>Warning: the file exists but is shorter than the provided offset (${start}). The file has 1 lines.</system-reminder>`;
             const header = pageMarker ?? (truncated ? `[${path}: lines ${start}-${end} of ${total}${end < total ? " — use offset to see more" : ""}]\n` : "");
             return {
-                content: `${header}${body}${READ_CYBER_REMINDER}`,
+                content: `${nbFallbackPrefix}${header}${body}${READ_CYBER_REMINDER}`,
                 details: {
                     type: "text",
                     file: {
@@ -653,107 +694,115 @@ export function makeEditFileTool(env, state, rootCanonical, cwdRef, additionalRo
                 ? a.edits
                 : [{ old_string: a.old_string ?? "", new_string: a.new_string ?? "", ...(a.replace_all !== undefined ? { replace_all: a.replace_all } : {}) }];
             if (!batch && (typeof a.old_string !== "string" || typeof a.new_string !== "string")) {
-                return `Error (Edit): old_string and new_string are required.`;
+                return errorResult(`Error (Edit): old_string and new_string are required.`);
             }
             for (let i = 0; i < edits.length; i++) {
                 const e = edits[i];
                 if (!e || typeof e.old_string !== "string" || typeof e.new_string !== "string") {
-                    return `Error (Edit): edit ${i + 1} of ${edits.length}: old_string and new_string must both be strings (no changes written — the batch is atomic).`;
+                    return errorResult(`Error (Edit): edit ${i + 1} of ${edits.length}: old_string and new_string must both be strings (no changes written — the batch is atomic).`);
                 }
             }
             const path = fileArgPath(args);
             if (path === undefined)
-                return `Error (Edit): file_path is required.`;
+                return errorResult(`Error (Edit): file_path is required.`);
             const ipynb = ipynbRedirect("Edit", path);
             if (ipynb)
-                return ipynb;
+                return errorResult(ipynb);
             const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
             if (!r.ok)
-                return violationText("Edit", r.violation);
+                return errorResult(violationText("Edit", r.violation));
             const singleOld = batch ? undefined : a.old_string;
             const exists = await env.exists(r.key, ctx.signal);
             if (!exists.ok)
-                return `Error (Edit): cannot stat "${path}": ${exists.error.message}`;
+                return errorResult(`Error (Edit): cannot stat "${path}": ${exists.error.message}`);
             if (!exists.value) {
                 if (singleOld === "") {
                     const created = a.new_string ?? "";
                     if (created === "")
-                        return violationText("Edit", { code: "invalid", message: "No changes to make: old_string and new_string are exactly the same." });
+                        return errorResult(violationText("Edit", { code: "invalid", message: "No changes to make: old_string and new_string are exactly the same." }));
                     const gated = await gateToolWrite(beforeWrite, "Edit", path, r.key, created);
                     if (gated !== undefined)
-                        return gated;
+                        return errorResult(gated);
                     const write = env.writeFileExclusive !== undefined
                         ? await env.writeFileExclusive(r.key, created, ctx.signal)
                         : await env.writeFile(r.key, created, ctx.signal);
                     if (!write.ok) {
                         if (write.error.code === "already_exists") {
-                            return `Error (Edit): cannot create "${path}": file already exists (created concurrently since the existence check). Read the file first, then edit it normally (or Write after the Read to overwrite it).`;
+                            return errorResult(`Error (Edit): cannot create "${path}": file already exists (created concurrently since the existence check). Read the file first, then edit it normally (or Write after the Read to overwrite it).`);
                         }
-                        return `Error (Edit): cannot write "${path}": ${write.error.message}`;
+                        return errorResult(`Error (Edit): cannot write "${path}": ${write.error.message}`);
                     }
-                    const createdNorm = normalizeEditText(created);
+                    const createdNorm = normalizeFileText(created);
                     state.set(r.key, { hash: sha256(createdNorm), totalLines: countLines(createdNorm), truncated: false, lastReadAt: Date.now() });
                     return {
                         content: `Created ${path} (${countLines(createdNorm)} lines).`,
                         details: { type: "create", filePath: path, content: created },
                     };
                 }
-                return `Error (Edit): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal)}`;
+                return errorResult(`Error (Edit): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal)}`);
             }
             const editInfo = await env.fileInfo(r.key, ctx.signal);
             if (editInfo.ok && editInfo.value.size > MAX_EDIT_BYTES) {
-                return `Error (Edit): "${path}" is too large to edit (${formatByteSize(editInfo.value.size)}). Maximum editable file size is ${formatByteSize(MAX_EDIT_BYTES)}.`;
+                return errorResult(`Error (Edit): "${path}" is too large to edit (${formatByteSize(editInfo.value.size)}). Maximum editable file size is ${formatByteSize(MAX_EDIT_BYTES)}.`);
             }
             if (singleOld === "") {
                 const preBin = await env.readBinaryFile(r.key, ctx.signal);
                 if (!preBin.ok)
-                    return `Error (Edit): cannot read "${path}": ${preBin.error.message}`;
+                    return errorResult(`Error (Edit): cannot read "${path}": ${preBin.error.message}`);
                 if (preBin.value.byteLength > MAX_EDIT_BYTES) {
-                    return `Error (Edit): "${path}" is too large to edit (${formatByteSize(preBin.value.byteLength)}). Maximum editable file size is ${formatByteSize(MAX_EDIT_BYTES)}.`;
+                    return errorResult(`Error (Edit): "${path}" is too large to edit (${formatByteSize(preBin.value.byteLength)}). Maximum editable file size is ${formatByteSize(MAX_EDIT_BYTES)}.`);
                 }
                 const preDecResult = decodeEditBytes(preBin.value, path);
                 if (!preDecResult.ok)
-                    return preDecResult.message;
+                    return errorResult(preDecResult.message);
                 const preDec = preDecResult.value;
                 if (preDec.malformed)
-                    return `Error (Edit): "${path}" has a truncated UTF-16 body; repair/convert it with bash first.`;
+                    return errorResult(`Error (Edit): "${path}" has a truncated UTF-16 body; repair/convert it with bash first.`);
                 if (preDec.text.trim() !== "")
-                    return `Error (Edit): Cannot create new file - file already exists.`;
+                    return errorResult(`Error (Edit): Cannot create new file - file already exists.`);
+                const priorRead = state.get(r.key);
+                if (priorRead !== undefined) {
+                    const staleCreate = checkStale(priorRead, sha256(preDec.text));
+                    if (staleCreate)
+                        return errorResult(violationText("Edit", staleCreate));
+                }
                 const newContent = normalizeEditText(a.new_string ?? "");
                 if (newContent === preDec.text)
-                    return violationText("Edit", { code: "invalid", message: "No changes to make: old_string and new_string are exactly the same." });
+                    return errorResult(violationText("Edit", { code: "invalid", message: "No changes to make: old_string and new_string are exactly the same." }));
                 const gated = await gateToolWrite(beforeWrite, "Edit", path, r.key, newContent);
                 if (gated !== undefined)
-                    return gated;
-                const write = await env.writeFile(r.key, encodeTextForFile(newContent, preDec.encoding, preDec.endings), ctx.signal);
+                    return errorResult(gated);
+                const encodedOverwrite = encodeTextForFile(newContent, preDec.encoding, preDec.endings);
+                const write = await env.writeFile(r.key, encodedOverwrite, ctx.signal);
                 if (!write.ok)
-                    return `Error (Edit): cannot write "${path}": ${write.error.message}`;
-                state.set(r.key, { hash: sha256(newContent), totalLines: countLines(newContent), truncated: false, lastReadAt: Date.now() });
+                    return errorResult(`Error (Edit): cannot write "${path}": ${write.error.message}`);
+                const persistedOverwrite = persistedTextOf(encodedOverwrite);
+                state.set(r.key, { hash: sha256(persistedOverwrite), totalLines: countLines(persistedOverwrite), truncated: false, lastReadAt: Date.now() });
                 return {
-                    content: `Created ${path} (${countLines(newContent)} lines).`,
+                    content: `The file ${path} has been updated successfully.${FILE_STATE_TRAILER}`,
                     details: { type: "edit", filePath: path, originalFile: preDec.text, oldString: "", newString: newContent, replaceAll: false, edits: [{ oldString: "", newString: newContent, replaceAll: false }] },
                 };
             }
             const notRead = requireRead(state, r.key);
             if (notRead)
-                return await notReadRefusalText(env, "Edit", r.key, notRead, ctx.signal);
+                return errorResult(await notReadRefusalText(env, "Edit", r.key, notRead, ctx.signal));
             const readBin = await env.readBinaryFile(r.key, ctx.signal);
             if (!readBin.ok)
-                return `Error (Edit): cannot read "${path}": ${readBin.error.message}`;
+                return errorResult(`Error (Edit): cannot read "${path}": ${readBin.error.message}`);
             if (readBin.value.byteLength > MAX_EDIT_BYTES) {
-                return `Error (Edit): "${path}" is too large to edit (${formatByteSize(readBin.value.byteLength)}). Maximum editable file size is ${formatByteSize(MAX_EDIT_BYTES)}.`;
+                return errorResult(`Error (Edit): "${path}" is too large to edit (${formatByteSize(readBin.value.byteLength)}). Maximum editable file size is ${formatByteSize(MAX_EDIT_BYTES)}.`);
             }
             const decodedResult = decodeEditBytes(readBin.value, path);
             if (!decodedResult.ok)
-                return decodedResult.message;
+                return errorResult(decodedResult.message);
             const decoded = decodedResult.value;
             if (decoded.malformed)
-                return `Error (Edit): "${path}" has a truncated UTF-16 body; repair/convert it with bash first.`;
+                return errorResult(`Error (Edit): "${path}" has a truncated UTF-16 body; repair/convert it with bash first.`);
             const original = decoded.text;
             const entry = state.get(r.key);
             const stale = checkStale(entry, sha256(original));
             if (stale)
-                return violationText("Edit", stale);
+                return errorResult(violationText("Edit", stale));
             let working = original;
             let replacements = 0;
             const appliedEdits = [];
@@ -764,7 +813,7 @@ export function makeEditFileTool(env, state, rootCanonical, cwdRef, additionalRo
                 let newS = normalizeEditText(e.new_string);
                 const noChange = checkNoChange(oldS, newS);
                 if (noChange)
-                    return batch ? `Error (Edit): ${where}${noChange.message}` : violationText("Edit", noChange);
+                    return errorResult(batch ? `Error (Edit): ${where}${noChange.message}` : violationText("Edit", noChange));
                 if (oldS !== "" && !working.includes(oldS)) {
                     const resolved = resolveQuoteMatch(working, oldS);
                     if (resolved !== undefined && resolved !== oldS) {
@@ -774,7 +823,7 @@ export function makeEditFileTool(env, state, rootCanonical, cwdRef, additionalRo
                 }
                 const match = checkEditMatch(working, oldS, e.replace_all === true, entry.truncated);
                 if (match)
-                    return batch ? `Error (Edit): ${where}${match.message} (no changes written — the batch is atomic).` : violationText("Edit", match);
+                    return errorResult(batch ? `Error (Edit): ${where}${match.message} (no changes written — the batch is atomic).` : violationText("Edit", match));
                 replacements += e.replace_all === true ? countOccurrences(working, oldS) : 1;
                 const effOld = e.replace_all === true ? oldS : deletionOldString(working, oldS, newS);
                 working = e.replace_all === true ? working.split(effOld).join(newS) : working.replace(effOld, () => newS);
@@ -782,11 +831,13 @@ export function makeEditFileTool(env, state, rootCanonical, cwdRef, additionalRo
             }
             const gated = await gateToolWrite(beforeWrite, "Edit", path, r.key, working);
             if (gated !== undefined)
-                return gated;
-            const write = await env.writeFile(r.key, encodeTextForFile(working, decoded.encoding, decoded.endings), ctx.signal);
+                return errorResult(gated);
+            const encodedEdit = encodeTextForFile(working, decoded.encoding, decoded.endings);
+            const write = await env.writeFile(r.key, encodedEdit, ctx.signal);
             if (!write.ok)
-                return `Error (Edit): cannot write "${path}": ${write.error.message}`;
-            state.set(r.key, { hash: sha256(working), totalLines: countLines(working), truncated: false, lastReadAt: Date.now() });
+                return errorResult(`Error (Edit): cannot write "${path}": ${write.error.message}`);
+            const persistedEdit = persistedTextOf(encodedEdit);
+            state.set(r.key, { hash: sha256(persistedEdit), totalLines: countLines(persistedEdit), truncated: false, lastReadAt: Date.now() });
             const a0 = appliedEdits[0];
             return {
                 content: batch
@@ -823,54 +874,56 @@ export function makeWriteFileTool(env, state, rootCanonical, cwdRef, additionalR
             const { content } = args;
             const path = fileArgPath(args);
             if (path === undefined)
-                return `Error (Write): file_path is required.`;
+                return errorResult(`Error (Write): file_path is required.`);
             const ipynb = ipynbRedirect("Write", path);
             if (ipynb)
-                return ipynb;
+                return errorResult(ipynb);
             const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
             if (!r.ok)
-                return violationText("Write", r.violation);
+                return errorResult(violationText("Write", r.violation));
             const exists = await env.exists(r.key, ctx.signal);
             if (!exists.ok)
-                return `Error (Write): cannot stat "${path}": ${exists.error.message}`;
+                return errorResult(`Error (Write): cannot stat "${path}": ${exists.error.message}`);
             let originalFile;
             if (exists.value) {
                 const notRead = requireRead(state, r.key);
                 if (notRead) {
-                    return (`${violationText("Write", notRead)} ` +
+                    return errorResult(`${violationText("Write", notRead)} ` +
                         `(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead — e.g. \`rm\` + rewrite, or \`iconv\`.)`);
                 }
                 const readBin = await env.readBinaryFile(r.key, ctx.signal);
                 if (!readBin.ok)
-                    return `Error (Write): cannot re-read "${path}" to verify it is unchanged: ${readBin.error.message}`;
+                    return errorResult(`Error (Write): cannot re-read "${path}" to verify it is unchanged: ${readBin.error.message}`);
                 const decodedPrev = decodeTextBytes(readBin.value);
                 if (decodedPrev.malformed)
-                    return `Error (Write): "${path}" has a truncated UTF-16 body; repair/convert it with bash first.`;
+                    return errorResult(`Error (Write): "${path}" has a truncated UTF-16 body; repair/convert it with bash first.`);
                 const stale = checkStale(state.get(r.key), sha256(decodedPrev.text));
                 if (stale)
-                    return violationText("Write", stale);
+                    return errorResult(violationText("Write", stale));
                 originalFile = decodedPrev.text;
                 const gated = await gateToolWrite(beforeWrite, "Write", path, r.key, content);
                 if (gated !== undefined)
-                    return gated;
-                const write = await env.writeFile(r.key, encodeTextForFile(content, decodedPrev.encoding, "preserve"), ctx.signal);
+                    return errorResult(gated);
+                const outgoing = splitLeadingBom(content);
+                const writeEncoding = outgoing.hadBom && !decodedPrev.encoding.hadBom ? { ...decodedPrev.encoding, hadBom: true } : decodedPrev.encoding;
+                const write = await env.writeFile(r.key, encodeTextForFile(outgoing.text, writeEncoding, "preserve"), ctx.signal);
                 if (!write.ok)
-                    return `Error (Write): cannot write "${path}": ${write.error.message}`;
-                const totalLines = countLines(content);
-                state.set(r.key, { hash: sha256(normalizeEditText(content)), totalLines, truncated: false, lastReadAt: Date.now() });
+                    return errorResult(`Error (Write): cannot write "${path}": ${write.error.message}`);
+                const totalLines = countLines(outgoing.text);
+                state.set(r.key, { hash: sha256(normalizeFileText(content)), totalLines, truncated: false, lastReadAt: Date.now() });
                 return {
                     content: `The file ${path} has been updated successfully.${FILE_STATE_TRAILER}`,
-                    details: { type: "update", filePath: path, content: normalizeEditText(content), originalFile },
+                    details: { type: "update", filePath: path, content: normalizeFileText(content), originalFile },
                 };
             }
             const gatedCreate = await gateToolWrite(beforeWrite, "Write", path, r.key, content);
             if (gatedCreate !== undefined)
-                return gatedCreate;
+                return errorResult(gatedCreate);
             const write = await env.writeFile(r.key, content, ctx.signal);
             if (!write.ok)
-                return `Error (Write): cannot write "${path}": ${write.error.message}`;
+                return errorResult(`Error (Write): cannot write "${path}": ${write.error.message}`);
             const totalLines = countLines(content);
-            state.set(r.key, { hash: sha256(normalizeEditText(content)), totalLines, truncated: false, lastReadAt: Date.now() });
+            state.set(r.key, { hash: sha256(normalizeFileText(content)), totalLines, truncated: false, lastReadAt: Date.now() });
             void originalFile;
             return {
                 content: `File created successfully at: ${path}${FILE_STATE_TRAILER}`,
@@ -887,7 +940,7 @@ export function makeNotebookEditTool(env, state, rootCanonical, cwdRef, addition
             "\n" +
             "Usage:\n" +
             "- You must use the Read tool on the notebook in this conversation before editing — this tool will fail otherwise.\n" +
-            "- `cell_id` is the cell's `id` field in the notebook JSON shown by Read. It is required for `replace` and `delete`.\n" +
+            "- `cell_id` is the `id` attribute shown in the Read tool's `<cell id=\"...\">` output. It is required for `replace` and `delete`.\n" +
             "- `edit_mode` defaults to `replace`. Use `insert` to add a new cell after the cell with the given `cell_id` " +
             "(or at the beginning of the notebook if `cell_id` is omitted) — `cell_type` is required when inserting. " +
             "Use `delete` to remove the cell.",
@@ -911,37 +964,37 @@ export function makeNotebookEditTool(env, state, rootCanonical, cwdRef, addition
             let cellType = a.cell_type;
             const mode = a.edit_mode ?? "replace";
             if (!notebook_path.toLowerCase().endsWith(".ipynb")) {
-                return `Error (NotebookEdit): "${notebook_path}" is not a .ipynb file; use Edit for other file types.`;
+                return errorResult(`Error (NotebookEdit): "${notebook_path}" is not a .ipynb file; use Edit for other file types.`);
             }
             if (mode === "insert" && !cellType)
-                return `Error (NotebookEdit): Cell type is required when using edit_mode=insert.`;
+                return errorResult(`Error (NotebookEdit): Cell type is required when using edit_mode=insert.`);
             if (mode !== "insert" && !cell_id)
-                return `Error (NotebookEdit): cell_id is required for replace/delete.`;
+                return errorResult(`Error (NotebookEdit): cell_id is required for replace/delete.`);
             const r = await resolveKey(env, rootCanonical, notebook_path, ctx.signal, cwdRef?.current, additionalRoots);
             if (!r.ok)
-                return violationText("NotebookEdit", r.violation);
+                return errorResult(violationText("NotebookEdit", r.violation));
             const notRead = requireRead(state, r.key);
             if (notRead)
-                return await notReadRefusalText(env, "NotebookEdit", r.key, notRead, ctx.signal);
+                return errorResult(await notReadRefusalText(env, "NotebookEdit", r.key, notRead, ctx.signal));
             const readBin = await env.readBinaryFile(r.key, ctx.signal);
             if (!readBin.ok)
-                return `Error (NotebookEdit): cannot read "${notebook_path}": ${readBin.error.message}`;
+                return errorResult(`Error (NotebookEdit): cannot read "${notebook_path}": ${readBin.error.message}`);
             const decodedNb = decodeTextBytes(readBin.value);
             if (decodedNb.malformed)
-                return `Error (NotebookEdit): "${notebook_path}" has a truncated UTF-16 body; repair/convert it with bash first.`;
+                return errorResult(`Error (NotebookEdit): "${notebook_path}" has a truncated UTF-16 body; repair/convert it with bash first.`);
             const nbText = decodedNb.text;
             const stale = checkStale(state.get(r.key), sha256(nbText));
             if (stale)
-                return violationText("NotebookEdit", stale);
+                return errorResult(violationText("NotebookEdit", stale));
             let nb;
             try {
                 nb = JSON.parse(nbText);
             }
             catch {
-                return `Error (NotebookEdit): "${notebook_path}" is not valid JSON.`;
+                return errorResult(`Error (NotebookEdit): "${notebook_path}" is not valid JSON.`);
             }
             if (!nb || typeof nb !== "object" || !Array.isArray(nb.cells)) {
-                return `Error (NotebookEdit): "${notebook_path}" is not a valid notebook (no cells array).`;
+                return errorResult(`Error (NotebookEdit): "${notebook_path}" is not a valid notebook (no cells array).`);
             }
             const cells = nb.cells;
             let h;
@@ -959,7 +1012,7 @@ export function makeNotebookEditTool(env, state, rootCanonical, cwdRef, addition
                     }
                 }
                 if (h === -1)
-                    return `Error (NotebookEdit): Cell with ID "${cell_id}" not found in notebook.`;
+                    return errorResult(`Error (NotebookEdit): Cell with ID "${cell_id}" not found in notebook.`);
                 if (mode === "insert")
                     h += 1;
             }
@@ -996,10 +1049,10 @@ export function makeNotebookEditTool(env, state, rootCanonical, cwdRef, addition
             const updated = JSON.stringify(nb, null, 1);
             const gated = await gateToolWrite(beforeWrite, "NotebookEdit", notebook_path, r.key, updated);
             if (gated !== undefined)
-                return gated;
+                return errorResult(gated);
             const w = await env.writeFile(r.key, encodeTextForFile(updated, decodedNb.encoding, decodedNb.endings), ctx.signal);
             if (!w.ok)
-                return `Error (NotebookEdit): cannot write "${notebook_path}": ${w.error.message}`;
+                return errorResult(`Error (NotebookEdit): cannot write "${notebook_path}": ${w.error.message}`);
             state.set(r.key, { hash: sha256(updated), totalLines: countLines(updated), truncated: false, lastReadAt: Date.now() });
             const nbDetails = {
                 type: "notebook-edit",
@@ -1062,7 +1115,7 @@ export function makeGrepTool(env, rootCanonical, additionalRoots) {
             if (a.path !== undefined) {
                 const r = await resolveKey(env, rootCanonical, a.path, ctx.signal, rootCanonical, additionalRoots);
                 if (!r.ok)
-                    return violationText("Grep", r.violation);
+                    return errorResult(violationText("Grep", r.violation));
                 scoped = r.key;
             }
             const grepRun = await runGrepDetailed(env, rootCanonical, {
@@ -1077,7 +1130,7 @@ export function makeGrepTool(env, rootCanonical, additionalRoots) {
             }, ctx.signal);
             const text = grepRun.text;
             if (text.startsWith("Error (grep)") || text.startsWith("Error (Grep)"))
-                return text;
+                return errorResult(text);
             const mode = a.output_mode ?? "files_with_matches";
             const rows = text.startsWith("No matches.")
                 ? []
@@ -1136,12 +1189,12 @@ export function makeGlobTool(env, rootCanonical, additionalRoots) {
         description: 'Fast file pattern matching. Supports glob patterns like "**/*.js" or "src/**/*.ts". Returns matching file paths sorted by modification time.\n' +
             "\n" +
             "- On environments that do not report modification times, results fall back to alphabetical order\n" +
-            "- Paths are RELATIVE to the root; ignored trees (node_modules/build/.gitignore) are skipped",
+            "- Paths are RELATIVE to the root; ignored trees (node_modules/build/.gitignore) are skipped unless your pattern names them explicitly (e.g. `dist/**`)",
         descriptionClassic: "- Fast file pattern matching tool that works with any codebase size\n" +
             '- Supports glob patterns like "**/*.js" or "src/**/*.ts"\n' +
             "- Returns matching file paths sorted by modification time\n" +
             "- On environments that do not report modification times, results fall back to alphabetical order\n" +
-            "- Paths are RELATIVE to the root; ignored trees (node_modules/build/.gitignore) are skipped\n" +
+            "- Paths are RELATIVE to the root; ignored trees (node_modules/build/.gitignore) are skipped unless your pattern names them explicitly (e.g. `dist/**`)\n" +
             "- Use this tool when you need to find files by name patterns; use `path` to scope to a sub-directory\n" +
             "- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead",
         parameters: Type.Object({
@@ -1164,7 +1217,7 @@ export function makeGlobTool(env, rootCanonical, additionalRoots) {
             if (path !== undefined) {
                 const r = await resolveKey(env, rootCanonical, path, ctx.signal, rootCanonical, additionalRoots);
                 if (!r.ok)
-                    return violationText("Glob", r.violation);
+                    return errorResult(violationText("Glob", r.violation));
                 scoped = r.key;
             }
             const r2 = await runGlobDetailed(env, rootCanonical, pattern, { path: scoped, max: max_results }, ctx.signal);
@@ -1560,7 +1613,11 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
             throw new Error(diagnosis ?? `Error (${toolName}): command did not run (${res.error.code}): ${res.error.message}`);
         }
         if (res.error.code === "transport_lost") {
-            return `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})`;
+            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 ?? "";
@@ -1605,7 +1662,11 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
                 },
             };
         }
-        return `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.`;
+        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);
@@ -1724,7 +1785,7 @@ export function makeBashTool(env, rootCanonical, coAuthor = false, cwdRef = { cu
             const { command, timeout, run_in_background, description } = args;
             if (run_in_background) {
                 if (!hasBackgroundShell(env)) {
-                    return "Error (Bash): this environment does not support background processes (run_in_background).";
+                    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);
@@ -1737,7 +1798,7 @@ export function makeBashTool(env, rootCanonical, coAuthor = false, cwdRef = { cu
                     ...(requestedTimeoutSec !== undefined ? { timeout: requestedTimeoutSec } : {}),
                 });
                 if (!r.ok)
-                    return `Error (Bash): ${r.error.message}`;
+                    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)
@@ -1783,7 +1844,7 @@ export function makeBashTool(env, rootCanonical, coAuthor = false, cwdRef = { cu
                             kill = undefined;
                         }
                         if (kill !== undefined && (kill.ok || kill.error.code === "not_found")) {
-                            return `Error (Bash): background process was started but could not be registered (${reason}); it has been terminated.`;
+                            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 {
@@ -1791,6 +1852,7 @@ export function makeBashTool(env, rootCanonical, coAuthor = false, cwdRef = { cu
                                 `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
@@ -1863,6 +1925,7 @@ export function makeBashTool(env, rootCanonical, coAuthor = false, cwdRef = { cu
                                         `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";
@@ -1872,6 +1935,7 @@ export function makeBashTool(env, rootCanonical, coAuthor = false, cwdRef = { cu
                                     `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);
@@ -1934,7 +1998,7 @@ export function makeBashReadonlyTool(env, rootCanonical, allow, execClamp) {
             const { command, timeout } = args;
             const reason = coarseReadonlyCheck(command, allow);
             if (reason)
-                return `Error (Bash): ${reason}`;
+                return errorResult(`Error (Bash): ${reason}`);
             return runShell(env, rootCanonical, "Bash", command, msTimeoutToSec(timeout), ctx.signal, undefined, undefined, execClamp, ctx.toolCallId, true);
         },
     });
@@ -1958,9 +2022,9 @@ export function makeBashOutputTool(env) {
             const { task_id, bash_id, filter } = args;
             const id = task_id ?? bash_id;
             if (!id)
-                return "Error (TaskOutput): Missing required parameter: task_id";
+                return errorResult("Error (TaskOutput): Missing required parameter: task_id");
             if (!hasBackgroundShell(env)) {
-                return "Error (TaskOutput): this environment does not support background processes.";
+                return errorResult("Error (TaskOutput): this environment does not support background processes.");
             }
             let rx;
             if (filter !== undefined) {
@@ -1968,12 +2032,12 @@ export function makeBashOutputTool(env) {
                     rx = new RegExp(filter);
                 }
                 catch {
-                    return `Error (TaskOutput): invalid filter regex: ${filter}`;
+                    return errorResult(`Error (TaskOutput): invalid filter regex: ${filter}`);
                 }
             }
             const r = await env.pollBackground(id);
             if (!r.ok)
-                return `Error (TaskOutput): ${r.error.message}`;
+                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;
@@ -2002,15 +2066,15 @@ export function makeKillShellTool(env, registry = defaultTaskRegistry) {
             const { task_id, shell_id } = args;
             const id = task_id ?? shell_id;
             if (!id)
-                return "Missing required parameter: task_id";
+                return errorResult("Missing required parameter: task_id");
             if (!hasBackgroundShell(env)) {
-                return "Error (TaskStop): this environment does not support background processes.";
+                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 `${id} is unknown or has already ended.`;
+                return errorResult(`${id} is unknown or has already ended.`);
             }
             return `Terminated ${id}.`;
         },