@sema-agent/core 2.3.0 → 2.5.0

package/dist/orchestration/workflow.js

@@ -104,6 +104,21 @@ export function workflowAgentCallKey(ordinal, spec, opts) {
     };
     return `${ordinal}:${boundInputHashOf(identity)}`;
 }
+function resolveChildSessionIdAtSpawn(spec) {
+    if (spec.sessionId)
+        return spec.sessionId;
+    if (spec.requireExistingSession === true || spec.resumeAt !== undefined)
+        return undefined;
+    return randomUUID();
+}
+export function assertSupportedAgentIsolation(isolation) {
+    if (isolation !== undefined && isolation !== "worktree") {
+        const shown = typeof isolation === "string" ? JSON.stringify(isolation) : String(isolation);
+        const e = new Error(`isolation ${shown} is not supported in workflow agents — only "worktree" (omit the option to run in the shared working tree). The agent was not started (fail-closed: an unrecognized isolation value must never silently run in the shared working tree).`);
+        e.code = "isolation.invalid";
+        throw e;
+    }
+}
 function rethrowIfMaxAgents(e) {
     if (e instanceof WorkflowMaxAgentsError)
         throw e;
@@ -626,6 +641,14 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         };
         return { tail, onActivity };
     };
+    const createWorkspaceObserver = (rec) => (workspace) => {
+        if (finalized)
+            return;
+        if (!workspace.isolated || rec.worktreeDir === workspace.cwd)
+            return;
+        rec.worktreeDir = workspace.cwd;
+        void persist("update");
+    };
     let currentPhase;
     let openMarkerPhase;
     let currentGroup;
@@ -700,6 +723,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 if ("error" in compiled)
                     throw new TypeError(`agent({schema}) received an invalid JSON Schema: ${compiled.error}`);
             }
+            assertSupportedAgentIsolation(agentOpts.isolation);
             const label = agentOpts.label ?? `agent-${run.agents.length + 1}`;
             const phase = agentOpts.phase ?? currentPhase?.title;
             const phaseInstance = resolveAgentPhase(agentOpts.phase);
@@ -799,7 +823,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         opts.onForwardEvent(e.type === "task_progress" ? { ...e, workflowRunId: runId, workflowAgentLabel: label } : e);
                     }
                     : undefined;
-                const baseInternals = { ...(agentOpts.isolation ? { isolation: agentOpts.isolation } : {}), ...(opts.parentCwd !== undefined ? { parentCwd: opts.parentCwd } : {}), ...spawnAttribution, ...(enrichedForward !== undefined ? { onForwardEvent: enrichedForward } : {}), agentName: label };
+                const baseInternals = { ...(agentOpts.isolation ? { isolation: agentOpts.isolation } : {}), ...(opts.parentCwd !== undefined ? { parentCwd: opts.parentCwd } : {}), ...spawnAttribution, ...(enrichedForward !== undefined ? { onForwardEvent: enrichedForward } : {}), agentName: label, onWorkspaceResolved: createWorkspaceObserver(rec) };
                 let attempts = 0;
                 let throttleRetried = false;
                 let lastAttemptReason;
@@ -828,7 +852,12 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     const onCallerAbort = () => attemptCtl.abort(new Error("workflow aborted"));
                     effectiveSignal?.addEventListener("abort", onCallerAbort, { once: true });
                     armWatchdog();
-                    const attemptSpec = { ...runSpec, signal: attemptCtl.signal };
+                    const attemptSessionId = resolveChildSessionIdAtSpawn(runSpec);
+                    const attemptSpec = attemptSessionId !== undefined ? { ...runSpec, sessionId: attemptSessionId, signal: attemptCtl.signal } : { ...runSpec, signal: attemptCtl.signal };
+                    if (attemptSessionId !== undefined && !finalized) {
+                        rec.sessionId = attemptSessionId;
+                        void persist("update");
+                    }
                     const attemptInternals = {
                         ...baseInternals,
                         ...(bceSink !== undefined
@@ -1071,6 +1100,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 if ("error" in compiled)
                     throw new TypeError(`agent({schema}) received an invalid JSON Schema: ${compiled.error}`);
             }
+            assertSupportedAgentIsolation(agentOpts.isolation);
             const label = agentOpts.label ?? `agent-${run.agents.length + 1}`;
             const phase = agentOpts.phase ?? currentPhase?.title;
             const phaseInstance = resolveAgentPhase(agentOpts.phase);
@@ -1115,14 +1145,17 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             rec.startedAt = now();
             bceSpawn(callKey, label, agentOpts.agentType, false);
             let stream;
+            let childSessionId;
             try {
                 const typedSpec0 = applyWorkflowAgentType(spec, agentOpts.agentType, agentRegistry);
                 const typedSpec = typedSpec0.model === undefined && inheritedModelSnap !== undefined ? { ...typedSpec0, model: inheritedModelSnap } : typedSpec0;
                 const framedSpec = withWorkflowChildPersona(typedSpec, agentOpts.schema ?? typedSpec.outputSchema);
                 const authInherit = framedSpec.getApiKeyAndHeaders === undefined && opts.defaultGetApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: opts.defaultGetApiKeyAndHeaders } : {};
-                const runSpec = agentOpts.schema
+                const baseRunSpec = agentOpts.schema
                     ? { ...framedSpec, ...authInherit, signal: effectiveSignal, outputSchema: agentOpts.schema }
                     : { ...framedSpec, ...authInherit, signal: effectiveSignal };
+                childSessionId = resolveChildSessionIdAtSpawn(baseRunSpec);
+                const runSpec = childSessionId !== undefined ? { ...baseRunSpec, sessionId: childSessionId } : baseRunSpec;
                 const enrichedForwardS = opts.onForwardEvent !== undefined
                     ? (e) => {
                         opts.onForwardEvent(e.type === "task_progress" ? { ...e, workflowRunId: runId, workflowAgentLabel: label } : e);
@@ -1135,6 +1168,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     ...(enrichedForwardS !== undefined ? { onForwardEvent: enrichedForwardS } : {}),
                     agentName: label,
                     onActivity,
+                    onWorkspaceResolved: createWorkspaceObserver(rec),
                     ...(bceSink !== undefined
                         ? {
                             onForwardEvent: (e) => {
@@ -1157,6 +1191,10 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 bceTerminal(callKey, "failed", err instanceof Error ? err.message : String(err), undefined, undefined);
                 throw err;
             }
+            if (childSessionId !== undefined && !finalized) {
+                rec.sessionId = childSessionId;
+                void persist("update");
+            }
             const steer = async (content) => {
                 const marker = `steer-${++steerMarkerSeq}`;
                 const framed = `[operator steer ${marker}] An operator/leader sent guidance for your task. Take it into account on your NEXT step. ` +

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

@@ -26,7 +26,13 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
     execClamp?: ExecClampOption;
     autoBackgroundOnTimeout?: boolean;
     oneShot?: boolean;
+    additionalRoots?: readonly string[];
+    bashDefaultTimeoutMs?: number;
+    bashMaxTimeoutMs?: number;
+}): AgentTool;
+export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, execClamp?: ExecClampOption, timeoutOpts?: {
+    bashDefaultTimeoutMs?: number;
+    bashMaxTimeoutMs?: number;
 }): AgentTool;
-export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, execClamp?: ExecClampOption): AgentTool;
 export declare function createEnvTaskOutputTool(env: ExecutionEnv): AgentTool;
 export declare function createEnvTaskStopTool(env: ExecutionEnv, registry?: TaskRegistry): AgentTool;

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) {
@@ -167,7 +173,7 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
             const rawRemainSec = Math.floor((deadline - Date.now()) / 1000);
             const maxSec = Math.max(1, rawRemainSec);
             if (maxSec < timeout) {
-                execClamp.onClamp?.(timeout, maxSec);
+                execClamp.onClamp?.(requestedSec, maxSec);
                 timeout = maxSec;
                 clampedByDeadline = true;
                 deadlineExhausted = rawRemainSec < 1;
@@ -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,16 @@ 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 survivedCapNote = cappedByMaxTimeout
+        ? `NOTE: requested timeout ${requestedSec}s was capped to the ${caps.maxSec}s engine ceiling (requests above the max are reduced to it) — no effect on this run (the command completed in time); use run_in_background for work that needs longer.`
+        : "";
     const clippedStdout = clipShellOutput(stdout);
     const clippedStderr = clipShellOutput(stderr);
     const stdoutImage = dataUriImageFromStdout(stdout);
@@ -300,9 +322,9 @@ 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}` : ""}${survivedCapNote ? `\n${survivedCapNote}` : ""}` },
             ],
-            details: { type: "bash", stdout: "[image data]", stderr: clippedStderr, exitCode, isImage: true, ...(imgOverflowFile !== undefined ? { output_file: imgOverflowFile } : {}) },
+            details: { type: "bash", stdout: "[image data]", stderr: clippedStderr, exitCode, isImage: true, ...(imgOverflowFile !== undefined ? { output_file: imgOverflowFile } : {}), ...(cappedByMaxTimeout ? { requestedTimeoutSec: requestedSec, cappedToMaxTimeoutSec: caps.maxSec } : {}) },
         };
     }
     const cleanOverflowFile = stdout.length > bashMaxOutputChars() || stderr.length > bashMaxOutputChars() ? await writeShellOverflowFile(env, stdout, stderr) : undefined;
@@ -313,6 +335,10 @@ 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);
+    if (survivedCapNote)
+        parts.push(survivedCapNote);
     return {
         content: parts.join("\n"),
         details: {
@@ -322,10 +348,11 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
             exitCode,
             ...(exit1Note ? { returnCodeInterpretation: exit1Note } : {}),
             ...(cleanOverflowFile !== undefined ? { output_file: cleanOverflowFile } : {}),
+            ...(cappedByMaxTimeout ? { requestedTimeoutSec: requestedSec, cappedToMaxTimeoutSec: caps.maxSec } : {}),
         },
     };
 }
-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 +361,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 +375,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}; requests above the max are capped to it)` })),
             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 +435,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 +496,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 +594,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 +609,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 +626,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 +638,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}; requests above the max are capped to it).` })),
         }),
         effect: "read",
         execute: async (args, ctx) => {
@@ -609,7 +646,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;