@sema-agent/core 2.3.0 → 2.4.0

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

@@ -5,9 +5,9 @@ import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_ALIASES, TASK_S
 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 { imageMagicMatches, withinAnyRoot } 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 { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, shellRecoveryHint, CWD_SENTINEL, } 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);
@@ -156,9 +156,15 @@ export function canAutoBackground(command) {
         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;
+function msTimeoutToRequestedSec(timeoutMs) {
+    if (timeoutMs === undefined || !Number.isFinite(timeoutMs))
+        return undefined;
+    return Math.max(1, Math.round(timeoutMs / 1000));
+}
+async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, cwdRef, detach, execClamp, toolCallId, readOnly, containmentRoots) {
+    const requestedSec = Math.max(1, Math.floor(timeoutSec ?? caps.defaultSec));
+    let timeout = Math.min(caps.maxSec, requestedSec);
+    const cappedByMaxTimeout = requestedSec > caps.maxSec;
     let clampedByDeadline = false;
     let deadlineExhausted = false;
     if (execClamp) {
@@ -235,13 +241,16 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
                     ? 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.`
+                    : cappedByMaxTimeout
+                        ? `Command timed out after ${timeout}s — requested ${requestedSec}s, capped at ${caps.maxSec}s (engine ceiling: requests above ${caps.maxSec}s are reduced to it). The process was killed; output produced before the cutoff is shown below. Re-running with a larger timeout gets the same ${caps.maxSec}s ceiling — use run_in_background for work that needs longer, a narrower command, or resume from the partial progress below.`
+                        : `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
+            const zeroOutput = captured.length === 0;
+            const body = !zeroOutput
                 ? `\n${delimitUntrusted("partial command output", captured)}`
                 : `\n(no output was produced before the cutoff)`;
             const overflowNote = cutOverflowFile !== undefined ? shellRecoveryHint(cutOverflowFile, readOnly) : "";
@@ -257,12 +266,15 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
                         ? {
                             timedOut: true,
                             timeoutSec: timeout,
-                            ...(clampedByDeadline ? { requestedTimeoutSec: requestedSec, clampedByDeadline: true } : {}),
+                            ...(clampedByDeadline || cappedByMaxTimeout ? { requestedTimeoutSec: requestedSec } : {}),
+                            ...(clampedByDeadline ? { clampedByDeadline: true } : {}),
+                            ...(cappedByMaxTimeout ? { cappedToMaxTimeoutSec: caps.maxSec } : {}),
                         }
                         : res.error.code === "aborted"
                             ? { aborted: true }
                             : { callbackError: true }),
                 },
+                ...(zeroOutput ? { isError: true } : {}),
             };
         }
         return {
@@ -291,6 +303,13 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
                 cwdRef.current = captured;
         }
     }
+    let cwdOutsideNote = "";
+    if (cwdRef && containmentRoots !== undefined && containmentRoots.length > 0 && !withinAnyRoot(containmentRoots, cwdRef.current)) {
+        const cwdCanon = await env.canonicalPath(cwdRef.current, signal);
+        if (!(cwdCanon.ok && withinAnyRoot(containmentRoots, cwdCanon.value))) {
+            cwdOutsideNote = `NOTE: working directory is now outside the task root(s) (${cwdRef.current}); relative paths in the structured file tools (Read/Edit/Write/Grep/Glob) will resolve there and may be refused. Pass absolute in-root paths, or \`cd\` back inside.`;
+        }
+    }
     const clippedStdout = clipShellOutput(stdout);
     const clippedStderr = clipShellOutput(stderr);
     const stdoutImage = dataUriImageFromStdout(stdout);
@@ -300,7 +319,7 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
         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}` },
+                { type: "text", text: `exit code: ${exitCode}\n[Image data detected in stdout and shown above]${stderr.trim() !== "" ? `\n--- stderr ---\n${clippedStderr}` : ""}${imgOverflowNote}${cwdOutsideNote ? `\n${cwdOutsideNote}` : ""}` },
             ],
             details: { type: "bash", stdout: "[image data]", stderr: clippedStderr, exitCode, isImage: true, ...(imgOverflowFile !== undefined ? { output_file: imgOverflowFile } : {}) },
         };
@@ -313,6 +332,8 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
         parts.push(`--- stderr ---\n${clippedStderr}`);
     if (overflowNote)
         parts.push(overflowNote.trim());
+    if (cwdOutsideNote)
+        parts.push(cwdOutsideNote);
     return {
         content: parts.join("\n"),
         details: {
@@ -325,7 +346,7 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
         },
     };
 }
-function bashDescription(coAuthor, bgNotifies = false, bgRetained = false) {
+function bashDescription(coAuthor, caps, bgNotifies = false, bgRetained = false) {
     const coAuthorLines = coAuthor === false
         ? "- Follow the deployment's commit-message conventions."
         : `- End git commit messages with:\nCo-Authored-By: ${coAuthor}`;
@@ -334,7 +355,7 @@ function bashDescription(coAuthor, bgNotifies = false, bgRetained = false) {
 - 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}.
+- \`timeout\` is in milliseconds: default ${caps.defaultMs}, max ${caps.maxMs}.
 - \`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
@@ -348,15 +369,17 @@ ${coAuthorLines}
 - 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 timeoutCaps = resolveBashTimeoutCaps(taskOpts);
+    const timeoutCapsSecView = bashTimeoutCapsSec(timeoutCaps);
     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),
+        description: bashDescription(coAuthor, timeoutCaps, 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})` })),
+            timeout: Type.Optional(Type.Number({ description: `Optional timeout in milliseconds (max ${timeoutCaps.maxMs})` })),
             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" +
@@ -406,7 +429,12 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                 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 bgCappedByMax = appliedTimeoutSec !== undefined && requestedTimeoutSec !== undefined && typeof bgCaps.maxBgTimeoutSec === "number" && requestedTimeoutSec > bgCaps.maxBgTimeoutSec;
+                const budgetNote = appliedTimeoutSec !== undefined
+                    ? bgCappedByMax
+                        ? ` Time budget: requested ${requestedTimeoutSec}s, capped at ${bgCaps.maxBgTimeoutSec}s (env ceiling: requests above ${bgCaps.maxBgTimeoutSec}s are reduced to it) — auto-terminates if still running after ${appliedTimeoutSec}s.`
+                        : ` 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).`;
@@ -462,7 +490,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                         ? ` Output file: ${outputFile} (full output is appended there — Read it any time).`
                         : ` Use TaskOutput("${taskId}") to check interim output.`;
                     if (taskOpts.oneShot === true && onNotify !== undefined) {
-                        return (`Command running in background; task_id=${taskId}.${interimNote} This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput("${taskId}", { block: true }). If it is still running after the wait, wait again (bounded) rather than ending the turn, or write out your best available answer now if you are near your own time budget. TaskStop("${taskId}") to stop.` +
+                        return (`Command running in background; task_id=${taskId}.${interimNote} This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput({ task_id: "${taskId}", block: true }). If it is still running after the wait, wait again (bounded) rather than ending the turn, or write out your best available answer now if you are near your own time budget. TaskStop("${taskId}") to stop.` +
                             budgetNote +
                             lifetimeNote);
                     }
@@ -560,7 +588,8 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                                     : `Use TaskOutput("${taskId}") to read its output. `) +
                                 `TaskStop("${taskId}") to stop it. ` +
                                 (taskOpts.oneShot === true && onNotify !== undefined
-                                    ? `This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput("${taskId}", { block: true }).`
+                                    ?
+                                        `This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput({ task_id: "${taskId}", block: true }).`
                                     : onNotify !== undefined
                                         ? `You will be notified when it completes — do not poll.`
                                         : `Poll TaskOutput until its status is no longer "running".`) +
@@ -574,7 +603,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
                 : undefined;
             let res;
             try {
-                res = await runShell(env, rootCanonical, "Bash", command, msTimeoutToSec(timeout), ctx.signal, cwdRef, detachChain, taskOpts.execClamp, ctx.toolCallId, false);
+                res = await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, cwdRef, detachChain, taskOpts.execClamp, ctx.toolCallId, false, [rootCanonical, ...(taskOpts.additionalRoots ?? [])]);
             }
             finally {
                 taskOpts.detachHub?.gc(ctx.toolCallId);
@@ -591,7 +620,9 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
         },
     });
 }
-export function createBashReadonlyTool(env, rootCanonical, allow, execClamp) {
+export function createBashReadonlyTool(env, rootCanonical, allow, execClamp, timeoutOpts) {
+    const timeoutCaps = resolveBashTimeoutCaps(timeoutOpts);
+    const timeoutCapsSecView = bashTimeoutCapsSec(timeoutCaps);
     const sample = [...allow].slice(0, 6).join(", ");
     return defineTool({
         name: "Bash",
@@ -601,7 +632,7 @@ export function createBashReadonlyTool(env, rootCanonical, allow, execClamp) {
             "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}).` })),
+            timeout: Type.Optional(Type.Number({ description: `Timeout in milliseconds (default ${timeoutCaps.defaultMs}, max ${timeoutCaps.maxMs}).` })),
         }),
         effect: "read",
         execute: async (args, ctx) => {
@@ -609,7 +640,7 @@ export function createBashReadonlyTool(env, rootCanonical, allow, execClamp) {
             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);
+            return runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, execClamp, ctx.toolCallId, true);
         },
     });
 }

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

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { sha256, resolveKey, violationText, hasBinaryExtension, isBinaryContent, fileArgPath, imageMimeForRead, imageMagicMatches, } from "./safety.js";
+import { sha256, resolveKey, violationText, violationDetails, hasBinaryExtension, isBinaryContent, fileArgPath, imageMimeForRead, imageMagicMatches, } from "./safety.js";
 import { decodeTextBytes } from "./encoding.js";
 import { isNotebookPath, parseNotebookCells, renderNotebookCells, stripNotebookImageData, NOTEBOOK_IMAGE_BASE64_BUDGET } from "./notebook.js";
 import { MCP_IMAGE_MAX_BASE64, IMAGE_TARGET_RAW_SIZE } from "../../core/mcp.js";
@@ -38,8 +38,8 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             "- 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.",
         parameters: Type.Object({
             ...FILE_PATH_PARAMS,
-            offset: Type.Optional(Type.Number({ description: "The line number to start reading from. Only provide if the file is too large to read at once (1-based; default 1)." })),
-            limit: Type.Optional(Type.Number({ description: "The number of lines to read. Only provide if the file is too large to read at once. (Default: the whole file, bounded by the output-token cap.)" })),
+            offset: Type.Optional(Type.Integer({ minimum: 0, description: "The line number to start reading from. Only provide if the file is too large to read at once (1-based; default 1)." })),
+            limit: Type.Optional(Type.Integer({ minimum: 1, description: "The number of lines to read. Only provide if the file is too large to read at once. (Default: the whole file, bounded by the output-token cap.)" })),
             pages: Type.Optional(Type.String({ description: `Page range for PDF files (e.g., "1-5", "3", "10-20"). Only applicable to PDF files. Maximum ${PDF_MAX_PAGES_PER_READ} pages per request.` })),
         }),
         effect: "read",
@@ -48,9 +48,13 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             const path = fileArgPath(args);
             if (path === undefined)
                 return errorResult(`Error (Read): file_path is required.`);
+            const fileUnchangedResult = (text, reason, startLine, endLine, totalLines) => ({
+                content: text,
+                details: { type: "file_unchanged", reason, file: { filePath: path, startLine, endLine, totalLines } },
+            });
             const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, bgOutputReadExemption === undefined ? undefined : (key) => bgOutputReadExemption(key, ctx));
             if (!r.ok)
-                return errorResult(violationText("Read", r.violation));
+                return errorResult(violationText("Read", r.violation), violationDetails(r.violation));
             const isNb = isNotebookPath(r.key);
             const imageMime = imageMimeForRead(r.key);
             if (imageMime !== undefined) {
@@ -116,20 +120,23 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             if (r.key.toLowerCase().endsWith(".pdf")) {
                 return pdfResultToToolReturn(await readPdfFile(env, path, r.key, pages, ctx.signal, imageDownsampler, cwdRef?.current ?? rootCanonical, undefined, pdfCapabilities));
             }
-            if (hasBinaryExtension(r.key)) {
-                return errorResult(`Error (Read): "${path}" appears to be a binary file (by extension); this tool reads UTF-8 text only.`);
-            }
+            const binaryExt = hasBinaryExtension(r.key);
+            const binaryExtRefusal = () => 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 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) {
+                    if (binaryExt)
+                        return binaryExtRefusal();
                     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 (!isNb && info.value.size > MAX_READ_BYTES && limit === undefined) {
+                    if (binaryExt)
+                        return binaryExtRefusal();
                     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.`);
                 }
             }
@@ -143,11 +150,15 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
                 return errorResult(`Error (Read): cannot read "${path}": ${readBin.error.message}`);
             const readSize = readBin.value.byteLength;
             if (readSize > SLICED_READ_MAX_BYTES) {
+                if (binaryExt)
+                    return binaryExtRefusal();
                 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 (!isNb && readSize > MAX_READ_BYTES && limit === undefined) {
+                if (binaryExt)
+                    return binaryExtRefusal();
                 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)) {
@@ -194,10 +205,10 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
                     }
                     const prevNb = state.get(r.key);
                     if (prevNb?.seededFromContext && !prevNb.isPartialView && prevNb.hash === hash) {
-                        return seededFileUnchangedReminder(r.key);
+                        return fileUnchangedResult(seededFileUnchangedReminder(r.key), "already-in-context", 1, total, total);
                     }
                     if (prevNb && !prevNb.isPartialView && 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]`;
+                        return fileUnchangedResult(`[${path}: unchanged since you last read it (lines 1-${total} of ${total}); content omitted to save context]`, "unchanged-since-last-read", 1, total, total);
                     }
                     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]" }];
@@ -251,10 +262,10 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             const truncated = start > 1 || end < total || pageMarker !== undefined;
             const prev = state.get(r.key);
             if (total > 0 && prev?.seededFromContext && !prev.isPartialView && start === 1 && effLimit === undefined && prev.hash === hash) {
-                return seededFileUnchangedReminder(r.key);
+                return fileUnchangedResult(seededFileUnchangedReminder(r.key), "already-in-context", 1, total, total);
             }
             if (total > 0 && prev && !prev.isPartialView && prev.hash === hash && prev.view && prev.view.start === start && prev.view.end === end) {
-                return `[${path}: unchanged since you last read it (lines ${start}-${end} of ${total}); content omitted to save context]`;
+                return fileUnchangedResult(`[${path}: unchanged since you last read it (lines ${start}-${end} of ${total}); content omitted to save context]`, "unchanged-since-last-read", start, end, total);
             }
             state.set(r.key, {
                 hash,

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

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { resolveKey, violationText } from "./safety.js";
+import { resolveKey, violationText, violationDetails } from "./safety.js";
 import { runGrepDetailed, runGlobDetailed, splitAbsoluteGlobPattern, invalidGlobTokens } from "./search.js";
 export function createGrepTool(env, rootCanonical, additionalRoots) {
     return defineTool({
@@ -63,7 +63,7 @@ export function createGrepTool(env, rootCanonical, additionalRoots) {
             if (a.path !== undefined) {
                 const r = await resolveKey(env, rootCanonical, a.path, ctx.signal, rootCanonical, additionalRoots);
                 if (!r.ok)
-                    return errorResult(violationText("Grep", r.violation));
+                    return errorResult(violationText("Grep", r.violation), violationDetails(r.violation));
                 scoped = r.key;
             }
             const grepRun = await runGrepDetailed(env, rootCanonical, {
@@ -182,7 +182,7 @@ export function createGlobTool(env, rootCanonical, additionalRoots) {
             if (path !== undefined) {
                 const r = await resolveKey(env, rootCanonical, path, ctx.signal, rootCanonical, additionalRoots);
                 if (!r.ok)
-                    return errorResult(violationText("Glob", r.violation));
+                    return errorResult(violationText("Glob", r.violation), violationDetails(r.violation));
                 scoped = r.key;
             }
             const r2 = await runGlobDetailed(env, rootCanonical, pattern, { path: scoped, max: max_results }, ctx.signal);

package/dist/tools/fs/fs-shared.d.ts

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 import type { ExecutionEnv } from "../../internal/harness-types.js";
-import { type ReadFileState } from "./safety.js";
+import { type FsViolation, type ReadFileState } from "./safety.js";
 import { type DecodedTextFile } from "./encoding.js";
 import { type ImageDownsampler } from "../../core/mcp.js";
 export declare const MAX_READ_BYTES: number;
@@ -15,11 +15,7 @@ export declare function decodeEditBytes(bytes: Uint8Array, path: string): {
     message: string;
 };
 export declare function persistedTextOf(encoded: string | Uint8Array): string;
-export declare function notReadRefusalText(env: ExecutionEnv, toolName: string, key: string, v: {
-    code: string;
-    message: string;
-    partialView?: boolean;
-}, signal?: AbortSignal, fallbackHint?: string): Promise<string>;
+export declare function notReadRefusalText(env: ExecutionEnv, toolName: string, key: string, v: Pick<FsViolation, "code" | "message" | "partialView">, signal?: AbortSignal, fallbackHint?: string): Promise<string>;
 export declare const MAX_IMAGE_READ_BYTES: number;
 export declare const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES: number;
 export type ReadImageDownsamplerOption = ImageDownsampler | false | undefined;
@@ -30,6 +26,20 @@ export declare const BASH_DEFAULT_TIMEOUT_SEC = 120;
 export declare const BASH_MAX_TIMEOUT_SEC = 600;
 export declare const BASH_DEFAULT_TIMEOUT_MS: number;
 export declare const BASH_MAX_TIMEOUT_MS: number;
+export declare function resolveBashTimeoutCaps(opts?: {
+    bashDefaultTimeoutMs?: number;
+    bashMaxTimeoutMs?: number;
+}): {
+    defaultMs: number;
+    maxMs: number;
+};
+export declare function bashTimeoutCapsSec(caps: {
+    defaultMs: number;
+    maxMs: number;
+}): {
+    defaultSec: number;
+    maxSec: number;
+};
 export declare function bashMaxOutputChars(): number;
 export declare const FILE_PATH_PARAMS: {
     file_path: Type.TOptional<Type.TString>;
@@ -40,7 +50,10 @@ export declare function writeShellOverflowFile(env: ExecutionEnv, stdout: string
 export declare function shellRecoveryHint(path: string, readOnly: boolean | undefined): string;
 export declare const FILE_STATE_TRAILER = " (file state is current in your context \u2014 no need to Read it back)";
 export declare const CWD_SENTINEL = "__cc_cwd_9f2c1b__";
-export declare function msTimeoutToSec(timeoutMs: number | undefined): number;
+export declare function msTimeoutToSec(timeoutMs: number | undefined, caps?: {
+    defaultMs: number;
+    maxMs: number;
+}): number;
 export declare function ipynbRedirect(toolName: string, path: string): string | undefined;
 export declare function countLines(s: string): number;
 export declare function seededFileUnchangedReminder(filePath: string): string;

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

@@ -51,6 +51,19 @@ export const BASH_DEFAULT_TIMEOUT_SEC = 120;
 export const BASH_MAX_TIMEOUT_SEC = 600;
 export const BASH_DEFAULT_TIMEOUT_MS = BASH_DEFAULT_TIMEOUT_SEC * 1000;
 export const BASH_MAX_TIMEOUT_MS = BASH_MAX_TIMEOUT_SEC * 1000;
+function validTimeoutMs(n) {
+    return n !== undefined && Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
+}
+export function resolveBashTimeoutCaps(opts) {
+    const defaultMs = validTimeoutMs(opts?.bashDefaultTimeoutMs) ??
+        validTimeoutMs(Number(process.env.BASH_DEFAULT_TIMEOUT_MS)) ??
+        BASH_DEFAULT_TIMEOUT_MS;
+    const maxMs = Math.max(validTimeoutMs(opts?.bashMaxTimeoutMs) ?? validTimeoutMs(Number(process.env.BASH_MAX_TIMEOUT_MS)) ?? BASH_MAX_TIMEOUT_MS, defaultMs);
+    return { defaultMs, maxMs };
+}
+export function bashTimeoutCapsSec(caps) {
+    return { defaultSec: Math.max(1, Math.round(caps.defaultMs / 1000)), maxSec: Math.max(1, Math.round(caps.maxMs / 1000)) };
+}
 const BASH_DEFAULT_MAX_OUTPUT_CHARS = 30_000;
 const BASH_MAX_OUTPUT_CHARS_CEILING = 150_000;
 export function bashMaxOutputChars() {
@@ -84,10 +97,11 @@ export function shellRecoveryHint(path, readOnly) {
 }
 export const FILE_STATE_TRAILER = " (file state is current in your context — no need to Read it back)";
 export const CWD_SENTINEL = "__cc_cwd_9f2c1b__";
-export function msTimeoutToSec(timeoutMs) {
+export function msTimeoutToSec(timeoutMs, caps = resolveBashTimeoutCaps()) {
+    const { defaultSec, maxSec } = bashTimeoutCapsSec(caps);
     if (timeoutMs === undefined || !Number.isFinite(timeoutMs))
-        return BASH_DEFAULT_TIMEOUT_SEC;
-    return Math.min(BASH_MAX_TIMEOUT_SEC, Math.max(1, Math.round(timeoutMs / 1000)));
+        return defaultSec;
+    return Math.min(maxSec, Math.max(1, Math.round(timeoutMs / 1000)));
 }
 export function ipynbRedirect(toolName, path) {
     if (path.toLowerCase().endsWith(".ipynb")) {

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

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { sha256, resolveKey, violationText, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, WRITE_ENCODING_DEADLOCK_ESCAPE_HINT, } from "./safety.js";
+import { sha256, resolveKey, violationText, violationDetails, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, resolveEscapeMatch, adaptNewStringEscapes, escapeMatchWasAttempted, ESCAPE_MATCH_MISS_NOTE, deletionOldString, countOccurrences, WRITE_ENCODING_DEADLOCK_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
 import { MAX_EDIT_BYTES, formatByteSize, decodeEditBytes, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, ipynbRedirect, countLines, } from "./fs-shared.js";
 async function gateToolWrite(hook, tool, path, key, content) {
@@ -56,7 +56,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                 return errorResult(`Error (Edit): file_path is required.`);
             const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
             if (!r.ok)
-                return errorResult(violationText("Edit", r.violation));
+                return errorResult(violationText("Edit", r.violation), violationDetails(r.violation));
             if (!batch && a.old_string === a.new_string) {
                 return errorResult(violationText("Edit", { code: "invalid", message: "No changes to make: old_string and new_string are exactly the same." }));
             }
@@ -241,7 +241,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
                 return errorResult(ipynb);
             const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots);
             if (!r.ok)
-                return errorResult(violationText("Write", r.violation));
+                return errorResult(violationText("Write", r.violation), violationDetails(r.violation));
             const exists = await env.exists(r.key, ctx.signal);
             if (!exists.ok)
                 return errorResult(`Error (Write): cannot stat "${path}": ${exists.error.message}`);
@@ -331,7 +331,7 @@ export function createNotebookEditTool(env, state, rootCanonical, cwdRef, additi
                 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 errorResult(violationText("NotebookEdit", r.violation));
+                return errorResult(violationText("NotebookEdit", r.violation), violationDetails(r.violation));
             const notRead = requireRead(state, r.key);
             if (notRead)
                 return errorResult(await notReadRefusalText(env, "NotebookEdit", r.key, notRead, ctx.signal));

package/dist/tools/fs/index.d.ts

@@ -29,6 +29,8 @@ export interface HandsToolkitOptions {
     }) => void;
     detachHub?: import("../../core/tool-detach.js").ToolDetachHub;
     execClamp?: ExecClampOption;
+    bashDefaultTimeoutMs?: number;
+    bashMaxTimeoutMs?: number;
     oneShot?: boolean;
     autoBackgroundOnTimeout?: boolean;
     readImageDownsampler?: ReadImageDownsamplerOption;

package/dist/tools/fs/index.js

@@ -35,7 +35,10 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
     tools.push(createGrepTool(env, rootCanonical, additionalRoots), createGlobTool(env, rootCanonical, additionalRoots), createRepoMapTool(env, rootCanonical, additionalRoots));
     if (includeShell) {
         tools.push(readOnly
-            ? createBashReadonlyTool(env, rootCanonical, new Set(bashReadonlyAllow ?? BASH_READONLY_DEFAULT_ALLOW), opts.execClamp)
+            ? createBashReadonlyTool(env, rootCanonical, new Set(bashReadonlyAllow ?? BASH_READONLY_DEFAULT_ALLOW), opts.execClamp, {
+                ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
+                ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
+            })
             : createBashTool(env, rootCanonical, commitCoAuthor, cwdRef, {
                 taskRegistry: opts.taskRegistry,
                 taskOwner: opts.taskOwner,
@@ -46,6 +49,9 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
                 execClamp: opts.execClamp,
                 ...(opts.autoBackgroundOnTimeout !== undefined ? { autoBackgroundOnTimeout: opts.autoBackgroundOnTimeout } : {}),
                 ...(opts.oneShot !== undefined ? { oneShot: opts.oneShot } : {}),
+                ...(additionalRoots !== undefined ? { additionalRoots } : {}),
+                ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
+                ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
             }));
         if (!readOnly && mountBackgroundTaskTools && hasBackgroundShell(env)) {
             const sessionAxis = opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {};

package/dist/tools/fs/repo-map.js

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { resolveKey, violationText } from "./safety.js";
+import { resolveKey, violationText, violationDetails } from "./safety.js";
 import { buildIgnore, walk, walkIsPartial } from "./search.js";
 const DEFAULT_MAX_CHARS = 16_000;
 const DEFAULT_MAX_FILES = 400;
@@ -101,7 +101,7 @@ export function createRepoMapTool(env, rootCanonical, additionalRoots) {
             if (a.path !== undefined) {
                 const r = await resolveKey(env, rootCanonical, a.path, signal, rootCanonical, additionalRoots);
                 if (!r.ok)
-                    return errorResult(violationText("RepoMap", r.violation));
+                    return errorResult(violationText("RepoMap", r.violation), violationDetails(r.violation));
                 start = r.key;
             }
             const maxChars = Math.max(1, Math.floor(a.max_chars ?? DEFAULT_MAX_CHARS));

package/dist/tools/fs/safety.d.ts

@@ -18,6 +18,8 @@ export declare function sha256(content: string): string;
 export interface FsViolation {
     code: "path_not_in_root" | "not_read" | "stale" | "ambiguous_edit" | "invalid";
     partialView?: true;
+    target?: string;
+    roots?: readonly string[];
     message: string;
 }
 export declare function isBlockedDevicePath(key: string): boolean;
@@ -43,6 +45,14 @@ export declare function canonicalizeTarget(env: ExecutionEnv, path: string, sign
     unresolvedSymlink?: true;
 }>;
 export declare function violationText(toolName: string, v: FsViolation): string;
+export declare function violationDetails(v: FsViolation): {
+    type: "path_not_in_root";
+    code: "path_not_in_root";
+    target: string;
+    roots: readonly string[];
+} | undefined;
+export declare function withinAnyRoot(rootsCanonical: readonly string[], p: string): boolean;
+export declare const PATH_NOT_IN_ROOT_ESCAPE_HINT = "(This boundary applies to the structured file tools. If you genuinely need content outside the allowed root(s) and the deployment permits it, use the Bash tool \u2014 it is not confined by this fence, though every call remains subject to the deployment's approval policy. Or ask for the directory to be added to additionalDirectories.)";
 export declare function requireRead(state: ReadFileState, key: string): FsViolation | undefined;
 export declare const OVERSIZE_READ_ESCAPE_HINT = "(This file is over the Read tool's whole-file byte cap, so a default Read is refused \u2014 read it in slices with explicit offset/limit to satisfy the read-first rule, or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
 export declare const PARTIAL_VIEW_READ_ESCAPE_HINT = "(Your last Read of this file returned only a PARTIAL view \u2014 the output token cap paginated it, so a default Read will keep returning the same page. Re-read it with explicit offset/limit (start from the page marker's next-page hint) until you have seen the part you are about to change; an explicit slice that fits satisfies the read-first rule. Or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";

package/dist/tools/fs/safety.js

@@ -175,7 +175,12 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
         const roots = [rootCanonical, ...(additionalRootsCanonical ?? [])];
         return {
             ok: false,
-            violation: { code: "path_not_in_root", message: `path "${path}" resolves outside the allowed root${roots.length > 1 ? "s" : ""} (${roots.join(", ")}); access denied` },
+            violation: {
+                code: "path_not_in_root",
+                message: `path "${path}" ${key !== path ? `(canonical target: "${key}") ` : ""}resolves outside the allowed root${roots.length > 1 ? "s" : ""} (${roots.join(", ")}); access denied. ${PATH_NOT_IN_ROOT_ESCAPE_HINT}`,
+                target: key,
+                roots,
+            },
         };
     }
     return { ok: true, key };
@@ -241,6 +246,15 @@ async function canonicalizeNewPath(env, abs, signal) {
 export function violationText(toolName, v) {
     return `Error (${toolName}): ${v.message}`;
 }
+export function violationDetails(v) {
+    return v.code === "path_not_in_root" && v.target !== undefined
+        ? { type: "path_not_in_root", code: "path_not_in_root", target: v.target, roots: v.roots ?? [] }
+        : undefined;
+}
+export function withinAnyRoot(rootsCanonical, p) {
+    return rootsCanonical.some((r) => within(r, p));
+}
+export const PATH_NOT_IN_ROOT_ESCAPE_HINT = "(This boundary applies to the structured file tools. If you genuinely need content outside the allowed root(s) and the deployment permits it, use the Bash tool — it is not confined by this fence, though every call remains subject to the deployment's approval policy. Or ask for the directory to be added to additionalDirectories.)";
 export function requireRead(state, key) {
     const entry = state.get(key);
     if (entry === undefined || entry.isPartialView) {

package/dist/tools/monitor.js

@@ -91,17 +91,31 @@ export function createMonitorTool(env, opts) {
                 return errorResult(`Error (Monitor): the watch process was started but could not be registered (${e instanceof Error ? e.message : String(e)}); it has been terminated.`);
             }
             const bgTimeout = env.backgroundCapabilities.defaultBgTimeoutSec;
+            const wasClamped = timeout_ms !== undefined && timeout_ms !== timeoutMs;
+            const clampNote = !isPersistent && wasClamped ? ` (clamped to ${timeoutMs}ms from your requested ${timeout_ms}ms)` : "";
+            const timeoutIgnoredNote = isPersistent && timeout_ms !== undefined ? ` (the timeout_ms you passed is ignored because persistent is true)` : "";
             const lifetime = isPersistent
                 ? typeof bgTimeout === "number"
-                    ? `It is persistent: no watch timeout of its own, but the execution environment kills background processes after ${bgTimeout}s; it runs until then, until you stop it, or until the session ends.`
-                    : "It is persistent: no watch timeout of its own, but the execution environment's background time budget still applies; it runs until then, until you stop it, or until the session ends."
-                : `It will be killed after ${timeoutMs}ms if still running.`;
-            return onNotify !== undefined
+                    ? `It is persistent: no watch timeout of its own${timeoutIgnoredNote}, but the execution environment kills background processes after ${bgTimeout}s; it runs until then, until you stop it, or until the session ends.`
+                    : `It is persistent: no watch timeout of its own${timeoutIgnoredNote}, but the execution environment's background time budget still applies; it runs until then, until you stop it, or until the session ends.`
+                : `It will be killed after ${timeoutMs}ms${clampNote} if still running.`;
+            const content = onNotify !== undefined
                 ? `Monitoring in background; task_id=${taskId}. Each stdout line becomes a notification event (lines within ` +
                     `~200ms are batched); you'll get a final notification with the exit code when it ends — do not poll. ` +
                     `${lifetime} TaskOutput("${taskId}") reads the full spool (stdout+stderr); TaskStop("${taskId}") stops the watch.`
                 : `Monitoring in background; task_id=${taskId}. No notification channel is wired in this mount — read output with ` +
                     `TaskOutput("${taskId}") (re-readable spool, stdout+stderr) and stop with TaskStop("${taskId}"). ${lifetime}`;
+            return {
+                content,
+                details: {
+                    type: "monitor-start",
+                    taskId,
+                    persistent: isPersistent,
+                    ...(isPersistent
+                        ? { timeoutIgnored: timeout_ms !== undefined }
+                        : { timeoutMs, ...(timeout_ms !== undefined ? { requestedTimeoutMs: timeout_ms } : {}), wasClamped }),
+                },
+            };
         },
     });
 }