@sema-agent/core 1.427.0 → 1.429.0

package/dist/agents/subagent-steps.d.ts

@@ -18,6 +18,8 @@ export declare class SubagentStepRecorder {
     private readonly pending;
     private readonly edits;
     private action;
+    private actionTool;
+    private actionTarget;
     constructor(parentToolCallId?: string);
     lockTo(taskId: string): void;
     private resetRecorded;
@@ -26,5 +28,9 @@ export declare class SubagentStepRecorder {
     recentSteps(): SubagentStep[] | undefined;
     editedFiles(): SubagentEditedFile[] | undefined;
     currentAction(): string | undefined;
+    currentActionStructured(): {
+        toolName: string;
+        target?: string;
+    } | undefined;
 }
 export declare function stepsFromMessages(messages: readonly unknown[], lastN: number): SubagentStep[];

package/dist/agents/subagent-steps.js

@@ -58,6 +58,8 @@ export class SubagentStepRecorder {
     pending = new Map();
     edits = new Map();
     action;
+    actionTool;
+    actionTarget;
     constructor(parentToolCallId) {
         this.parentToolCallId = parentToolCallId;
     }
@@ -72,6 +74,8 @@ export class SubagentStepRecorder {
         this.pending.clear();
         this.edits.clear();
         this.action = undefined;
+        this.actionTool = undefined;
+        this.actionTarget = undefined;
     }
     inScope(e) {
         const { sourceTaskId: src, parentToolCallId: ptc } = e;
@@ -94,6 +98,8 @@ export class SubagentStepRecorder {
                 const target = extractTarget(e.args);
                 this.pending.set(e.toolCallId, { tool, target, ...(editTargetPath(e.toolName, e.args) ? { edit: editTargetPath(e.toolName, e.args) } : {}) });
                 this.action = target ? `${tool} ${target}`.slice(0, FIELD_MAX + tool.length + 1) : tool;
+                this.actionTool = tool;
+                this.actionTarget = target || undefined;
             }
             else if (e.type === "tool_end") {
                 if (!this.inScope(e))
@@ -128,6 +134,9 @@ export class SubagentStepRecorder {
     currentAction() {
         return this.action;
     }
+    currentActionStructured() {
+        return this.actionTool === undefined ? undefined : { toolName: this.actionTool, ...(this.actionTarget !== undefined ? { target: this.actionTarget } : {}) };
+    }
 }
 export function stepsFromMessages(messages, lastN) {
     const results = new Map();

package/dist/agents/subagent.js

@@ -528,6 +528,7 @@ function makeSubagentResume(deps) {
                         ...(deps.rowAgentType !== undefined ? { agentType: deps.rowAgentType } : {}),
                         ...(deps.rowName !== undefined ? { name: deps.rowName } : {}),
                         sessionId: entry.childSessionId,
+                        transcriptId: entry.childSessionId,
                         ...(deps.rowParentTaskId !== undefined ? { parentTaskId: deps.rowParentTaskId } : {}),
                         ...(deps.rowParentSessionId !== undefined ? { parentSessionId: deps.rowParentSessionId } : {}),
                         ...(deps.rowRootSessionId !== undefined ? { rootSessionId: deps.rowRootSessionId } : {}),
@@ -553,6 +554,7 @@ function makeSubagentResume(deps) {
                                     taskId: deps.taskId,
                                     sessionScoped: deps.sessionScoped === true,
                                     ...(deps.rowAgentType !== undefined ? { agentType: deps.rowAgentType } : {}),
+                                    transcriptId: entry.childSessionId,
                                     progressTaskId: e.taskId,
                                     ...(e.parentTaskId !== undefined ? { progressParentTaskId: e.parentTaskId } : {}),
                                     ...(e.name !== undefined ? { name: e.name } : {}),
@@ -685,6 +687,7 @@ function makeSubagentResume(deps) {
                     taskId: deps.taskId,
                     sessionScoped: deps.sessionScoped === true,
                     sessionId: entry.childSessionId,
+                    transcriptId: entry.childSessionId,
                     status: abort.signal.aborted ? "killed" : "failed",
                     seq: entry.cycleSeq,
                     ...(stoppedByReject !== undefined ? { stoppedBy: stoppedByReject } : {}),
@@ -1657,6 +1660,7 @@ function makeSubagentTool(opts, depth, excluded, extraToolsBudget) {
                         agentType: spawnAgentType,
                         ...(agentName !== undefined ? { name: agentName } : {}),
                         sessionId: forkedId,
+                        transcriptId: forkedId,
                         ...(ctx.taskId !== undefined && ctx.taskId !== ctx.sessionId ? { parentTaskId: ctx.taskId } : {}),
                         ...(ctx.sessionId !== undefined ? { parentSessionId: ctx.sessionId } : {}),
                         ...((ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}),
@@ -1682,15 +1686,18 @@ function makeSubagentTool(opts, depth, excluded, extraToolsBudget) {
                                 }
                                 if (e.type === "task_progress") {
                                     const currentAction = stepRecorder.currentAction();
+                                    const currentTool = stepRecorder.currentActionStructured();
                                     sinkEmit({
                                         kind: "tick",
                                         taskId,
                                         sessionScoped: sessionScopedBg === true,
+                                        transcriptId: forkedId,
                                         progressTaskId: e.taskId,
                                         ...(e.parentTaskId !== undefined ? { progressParentTaskId: e.parentTaskId } : {}),
                                         agentType: spawnAgentType,
                                         ...(e.name !== undefined ? { name: e.name } : {}),
                                         ...(currentAction !== undefined ? { currentAction } : {}),
+                                        ...(currentTool !== undefined ? { currentTool } : {}),
                                         usage: e.usage,
                                     });
                                 }
@@ -1790,6 +1797,7 @@ function makeSubagentTool(opts, depth, excluded, extraToolsBudget) {
                             taskId,
                             sessionScoped: sessionScopedBg === true,
                             sessionId: forkedId,
+                            transcriptId: forkedId,
                             status: settledBg,
                             ...(stoppedByBg !== undefined ? { stoppedBy: stoppedByBg } : {}),
                             summary: summaryBg,
@@ -2006,6 +2014,7 @@ task_id: ${taskId}
                     agentType: spawnAgentType,
                     ...(agentName !== undefined ? { name: agentName } : {}),
                     sessionId: bgChildSessionId,
+                    transcriptId: bgChildSessionId,
                     ...(reviveRow !== undefined
                         ? {
                             ...(reviveRow.parentTaskId !== undefined ? { parentTaskId: reviveRow.parentTaskId } : {}),
@@ -2071,15 +2080,18 @@ task_id: ${taskId}
                             }
                             if (e.type === "task_progress") {
                                 const currentAction = stepRecorder.currentAction();
+                                const currentTool = stepRecorder.currentActionStructured();
                                 sinkEmit({
                                     kind: "tick",
                                     taskId,
                                     sessionScoped: sessionScopedBg === true,
+                                    transcriptId: bgChildSessionId,
                                     progressTaskId: e.taskId,
                                     ...(e.parentTaskId !== undefined ? { progressParentTaskId: e.parentTaskId } : {}),
                                     agentType: spawnAgentType,
                                     ...(e.name !== undefined ? { name: e.name } : {}),
                                     ...(currentAction !== undefined ? { currentAction } : {}),
+                                    ...(currentTool !== undefined ? { currentTool } : {}),
                                     usage: e.usage,
                                 });
                             }
@@ -2388,6 +2400,7 @@ task_id: ${taskId}
                         taskId,
                         sessionScoped: sessionScopedBg === true,
                         sessionId: bgChildSessionId,
+                        transcriptId: bgChildSessionId,
                         status: settled,
                         ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : {}),
                         ...(stoppedBy !== undefined ? { stoppedBy } : {}),

package/dist/core/runner/prepare-task.js

@@ -1164,6 +1164,7 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
                 ...(deps.hands?.bashReadonlyAllow !== undefined ? { bashReadonlyAllow: deps.hands.bashReadonlyAllow } : {}),
                 ...(deps.hands?.commitCoAuthor !== undefined ? { commitCoAuthor: deps.hands.commitCoAuthor } : {}),
                 ...(deps.hands?.readImageDownsampler !== undefined ? { readImageDownsampler: deps.hands.readImageDownsampler } : {}),
+                ...(deps.hands?.autoBackgroundOnTimeout !== undefined ? { autoBackgroundOnTimeout: deps.hands.autoBackgroundOnTimeout } : {}),
                 beforeWrite: async (w) => {
                     const deploymentGate = deps.hands?.beforeWrite;
                     if (deploymentGate) {
@@ -2320,6 +2321,7 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
                     args: editArgs,
                     message: re.message ?? re.reason ?? `approval required for "${creq.toolName}" (inherited parent policy)`,
                     ...askSourceIdentity(),
+                    ...(re.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
                 }, onAskOf, csignal ?? abortController.signal);
                 if (rr.action !== "allow")
                     return rr;
@@ -2365,6 +2367,7 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
                         args: presentedArgs,
                         message: first.message ?? first.reason ?? `approval required for "${creq.toolName}" (inherited parent policy)`,
                         ...askSourceIdentity(),
+                        ...(first.action === "ask" && first.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
                     }, pc.onAsk, csignal ?? abortController.signal);
                     const askWaitMs = Math.max(0, now() - askT0);
                     if (resolved.action === "deny" && resolved.approverUnavailable === true) {
@@ -2420,6 +2423,7 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
                         args: presentedArgs,
                         message: decision.message ?? decision.reason ?? `approval required for "${creq.toolName}" (inherited parent policy)`,
                         ...askSourceIdentity(),
+                        ...(decision.action === "ask" && decision.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
                     }, pc.onAsk, csignal ?? abortController.signal);
                     const askWaitMs = Math.max(0, now() - askT0);
                     if (resolved.action === "deny" && resolved.approverUnavailable === true) {
@@ -2654,6 +2658,7 @@ export async function prepareTask(spec, deps, sessions, resume, _memorySelector,
                     })(),
                     message: decision.message ?? decision.reason ?? `approval required for "${req.toolName}"`,
                     ...askSourceIdentity(),
+                    ...(decision.action === "ask" && decision.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
                 }, onAsk, abortController.signal);
                 const waitMs = Math.max(0, now() - t0);
                 if (resolved.approverUnavailable !== true) {

package/dist/core/tool-policy.d.ts

@@ -21,6 +21,7 @@ export type PermissionResult = {
     message?: string;
     reason?: string;
     decisionReason?: DecisionReason;
+    requiresRealApproval?: boolean;
 } | {
     action: "deny";
     updatedInput?: unknown;
@@ -82,6 +83,7 @@ export interface AskRequest {
     readonly sourceTaskId?: string;
     readonly fromSubagent?: true;
     readonly sourceAgentName?: string;
+    readonly requiresRealApproval?: boolean;
 }
 export type OnAsk = "deny" | "allow" | ((req: AskRequest, signal?: AbortSignal) => AskOutcome | Promise<AskOutcome>);
 export type AskOutcome = boolean | "unavailable" | {

package/dist/core/tool-policy.js

@@ -380,9 +380,10 @@ export function createUnverifiableDeletePolicy(opts) {
             if (finding === undefined)
                 return ALLOW;
             return {
-                action: "deny",
+                action: "ask",
                 decisionReason: "safety",
-                reason: `Unverifiable recursive delete blocked (fail-closed): ${finding}. ` +
+                requiresRealApproval: true,
+                reason: `Unverifiable recursive delete (fail-closed unless cleared): ${finding}. ` +
                     `Re-run the delete with the resolved literal path written into the command itself ` +
                     `(or assign the variable in the same command, e.g. \`DIR=/exact/path; rm -rf "$DIR"\`) so the target can be verified.`,
             };
@@ -410,13 +411,14 @@ export function createTranscriptIntegrityPolicy(opts) {
             return false;
         return dirs.some((d) => abs === d || abs.startsWith(d + sep));
     };
-    const denyReason = (what) => ({
-        action: "deny",
+    const askReason = (what) => ({
+        action: "ask",
         decisionReason: "safety",
-        reason: `Session-transcript write blocked: ${what}. Session transcripts (the .jsonl files under the agent data ` +
-            `dir's sessions/ directory) are harness-written session state, not agent working files — modifying or ` +
-            `deleting them tampers with the run's own audit trail. Reading them (ls/cat/grep as a single simple ` +
-            `command) is fine.`,
+        requiresRealApproval: true,
+        reason: `Session-transcript write (fail-closed unless cleared): ${what}. Session transcripts (the .jsonl files ` +
+            `under the agent data dir's sessions/ directory) are harness-written session state, not agent working ` +
+            `files — modifying or deleting them tampers with the run's own audit trail. Reading them (ls/cat/grep ` +
+            `as a single simple command) is fine.`,
     });
     return {
         check(req) {
@@ -431,7 +433,7 @@ export function createTranscriptIntegrityPolicy(opts) {
                 const parsed = parseLeadingCommandName(command);
                 if ("name" in parsed && readAllow.has(parsed.name))
                     return ALLOW;
-                return denyReason("name" in parsed
+                return askReason("name" in parsed
                     ? `\`${parsed.name}\` is not a read-only command`
                     : "the command references the transcript directory and is not a single read-only command (fail-closed)");
             }
@@ -439,7 +441,7 @@ export function createTranscriptIntegrityPolicy(opts) {
                 const a = req.args;
                 const p = a?.file_path ?? a?.notebook_path;
                 if (typeof p === "string" && inProtectedDir(p)) {
-                    return denyReason(`"${p}" is inside the session-transcript directory`);
+                    return askReason(`"${p}" is inside the session-transcript directory`);
                 }
             }
             return ALLOW;
@@ -486,6 +488,15 @@ function containsSharedMemory(v, seen = new Set()) {
 }
 export async function resolveAsk(req, onAsk, signal) {
     if (onAsk === "allow") {
+        if (req.requiresRealApproval === true) {
+            return {
+                action: "deny",
+                message: `approval required for "${req.toolName}" but the wired approver is a blanket "allow" (no ` +
+                    `judgment was applied) — this decision requires an actual auto-mode classifier verdict or a ` +
+                    `real approval callback, neither of which a blanket bypass can provide: ${req.message}`,
+                decisionReason: "mode",
+            };
+        }
         return { action: "allow", decisionReason: "mode" };
     }
     if (onAsk === undefined || onAsk === "deny") {

package/dist/core/types.d.ts

@@ -146,6 +146,7 @@ export interface HandsBandOptions {
     commitCoAuthor?: string | false;
     readImageDownsampler?: ((input: Buffer, mimeType: string) => Promise<import("./mcp.js").DownsampledImage | undefined>) | false;
     beforeWrite?: BeforeWriteHook;
+    autoBackgroundOnTimeout?: boolean;
 }
 export interface AgentDefinition {
     name: string;
@@ -645,6 +646,10 @@ export interface BackgroundChildEvent {
     progressParentTaskId?: string;
     name?: string;
     currentAction?: string;
+    currentTool?: {
+        toolName: string;
+        target?: string;
+    };
     sessionId?: string;
     transcriptId?: string;
     recentSteps?: import("../agents/subagent-steps.js").SubagentStep[];

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -54,12 +54,14 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
             kill: () => void;
         }) => void;
         onDetachAdopted?: () => void;
+        autoBackgroundOnTimeout?: boolean;
     }): Promise<Result<{
         stdout: string;
         stderr: string;
         exitCode: number;
         detached?: {
             shellId: string;
+            cause?: "timeout";
         };
     }, ExecutionError>>;
     readTextFile(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;

package/dist/engine/execution-env/node-execution-env.js

@@ -298,12 +298,14 @@ export class NodeExecutionEnv {
             const stderrTail = new RollingTailBuffer();
             let settled = false;
             let timedOut = false;
+            let abortKillInFlight = false;
             let callbackError;
             let child;
             const timeoutRef = {};
             const forceSettleRef = {};
             const spoolPumpRef = {};
             const execSpoolRef = {};
+            const adoptOnTimeoutRef = {};
             const pumpSpoolRef = {};
             const drainSpoolRef = {};
             const armForceSettle = (result) => {
@@ -327,6 +329,7 @@ export class NodeExecutionEnv {
                 return { stdout: markTruncated(so.text, so.droppedBytes), stderr: markTruncated(se.text, se.droppedBytes) };
             };
             const onAbort = () => {
+                abortKillInFlight = true;
                 if (child?.pid) {
                     killProcessTree(child.pid, { force: true });
                 }
@@ -415,9 +418,12 @@ export class NodeExecutionEnv {
                 try {
                     options.onSpawn({
                         pid: spawnedPid,
-                        kill: () => killProcessTree(spawnedPid, {
-                            stillRunning: () => spawnedChild.exitCode === null && spawnedChild.signalCode === null,
-                        }),
+                        kill: () => {
+                            abortKillInFlight = true;
+                            killProcessTree(spawnedPid, {
+                                stillRunning: () => spawnedChild.exitCode === null && spawnedChild.signalCode === null,
+                            });
+                        },
                     });
                 }
                 catch {
@@ -428,6 +434,10 @@ export class NodeExecutionEnv {
                 timeoutMs === undefined
                     ? undefined
                     : setTimeout(() => {
+                        if (options?.autoBackgroundOnTimeout && !abortKillInFlight && adoptOnTimeoutRef.current) {
+                            adoptOnTimeoutRef.current();
+                            return;
+                        }
                         timedOut = true;
                         if (child?.pid) {
                             killProcessTree(child.pid, { force: true });
@@ -543,13 +553,13 @@ export class NodeExecutionEnv {
                 spoolPumpRef.current = setInterval(pumpSpool, EXEC_SPOOL_PUMP_MS);
                 spoolPumpRef.current.unref?.();
             }
-            const onDetach = () => {
+            const onDetach = (cause) => {
                 if (settled || !child)
-                    return;
+                    return false;
                 pumpSpoolRef.current?.();
                 const shellId = this.adoptRunningChild(child, stdoutTail.result(), stderrTail.result(), execSpoolRef.current !== undefined ? { spool: execSpoolRef.current, cursors: { out: spoolCursor.out, err: spoolCursor.err } } : undefined);
                 if (shellId === undefined)
-                    return;
+                    return false;
                 if (spoolPumpRef.current)
                     clearInterval(spoolPumpRef.current);
                 try {
@@ -561,7 +571,16 @@ export class NodeExecutionEnv {
                     clearTimeout(timeoutRef.current);
                 const dso = stdoutTail.result();
                 const dse = stderrTail.result();
-                settle(ok({ stdout: markTruncated(dso.text, dso.droppedBytes), stderr: markTruncated(dse.text, dse.droppedBytes), exitCode: 0, detached: { shellId } }));
+                settle(ok({ stdout: markTruncated(dso.text, dso.droppedBytes), stderr: markTruncated(dse.text, dse.droppedBytes), exitCode: 0, detached: { shellId, ...(cause !== undefined ? { cause } : {}) } }));
+                return true;
+            };
+            adoptOnTimeoutRef.current = () => {
+                if (onDetach("timeout"))
+                    return;
+                timedOut = true;
+                if (child?.pid)
+                    killProcessTree(child.pid, { force: true });
+                armForceSettle(err(new ExecutionError("timeout", `timeout:${options?.timeout}`, undefined, partialOutput())));
             };
             if (options?.detachSignal) {
                 if (options.detachSignal.aborted)

package/dist/engine/harness/types.d.ts

@@ -92,6 +92,7 @@ export interface ExecutionEnvExecOptions {
         kill: () => void;
     }) => void;
     onDetachAdopted?: () => void;
+    autoBackgroundOnTimeout?: boolean;
 }
 export interface FileSystem {
     cwd: string;
@@ -135,6 +136,7 @@ export interface Shell {
         exitCode: number;
         detached?: {
             shellId: string;
+            cause?: "timeout";
         };
     }, ExecutionError>>;
     cleanup(): Promise<void>;

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

@@ -47,6 +47,7 @@ export interface ExecClampOption {
     }) => () => void;
 }
 export declare function bashExitOneInterpretation(command: string): string | undefined;
+export declare function canAutoBackground(command: string): boolean;
 export declare function makeBashTool(env: ExecutionEnv, rootCanonical: string, coAuthor?: string | false, cwdRef?: CwdRef, taskOpts?: {
     taskRegistry?: TaskRegistry;
     taskOwner?: string;
@@ -57,6 +58,7 @@ export declare function makeBashTool(env: ExecutionEnv, rootCanonical: string, c
     }) => void;
     detachHub?: import("../../core/tool-detach.js").ToolDetachHub;
     execClamp?: ExecClampOption;
+    autoBackgroundOnTimeout?: boolean;
 }): AgentTool;
 export declare function makeBashReadonlyTool(env: ExecutionEnv, rootCanonical: string, allow: ReadonlySet<string>, execClamp?: ExecClampOption): AgentTool;
 export declare function makeBashOutputTool(env: ExecutionEnv): AgentTool;
@@ -78,6 +80,7 @@ export interface HandsToolkitOptions {
     }) => void;
     detachHub?: import("../../core/tool-detach.js").ToolDetachHub;
     execClamp?: ExecClampOption;
+    autoBackgroundOnTimeout?: boolean;
     readImageDownsampler?: ReadImageDownsamplerOption;
     pdfModelCapabilities?: PdfModelCapabilities;
     beforeWrite?: BeforeWriteHook;

package/dist/tools/fs/index.js

@@ -1359,6 +1359,57 @@ async function diagnoseDeadCwd(env, toolName, effectiveCwd, root, cwdRef) {
         `It was likely deleted by a previous command (e.g. rm -rf on the current directory). There is no directory to reset to; ` +
         `this task cannot recover its working tree.`);
 }
+const AUTO_BACKGROUND_BLOCKED_FIRST_WORDS = new Set(["sleep"]);
+function stripAutoBackgroundWrapperPrefixes(segment) {
+    let s = segment.trim();
+    const wrappers = [
+        /^timeout\s+(?:-[A-Za-z]\S*\s+)*\d+(?:\.\d+)?[smhd]?\s+/,
+        /^time\s+/,
+        /^nice(?:\s+-n?\s*-?\d+)?\s+/,
+        /^nohup\s+/,
+        /^command\s+/,
+        /^builtin\s+/,
+        /^stdbuf(?:\s+-[ioe]\S+)+\s+/,
+        /^noglob\s+/,
+        /^[A-Za-z_][A-Za-z0-9_]*=\S+\s+/,
+    ];
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const re of wrappers) {
+            const stripped = s.replace(re, "");
+            if (stripped !== s) {
+                s = stripped.trim();
+                changed = true;
+            }
+        }
+    }
+    return s;
+}
+function commandBasename(token) {
+    const idx = token.lastIndexOf("/");
+    return idx === -1 ? token : token.slice(idx + 1);
+}
+export function canAutoBackground(command) {
+    const segments = command
+        .split(/&&|\|\||;|\||\r?\n/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (segments.length === 0)
+        return true;
+    for (const seg of segments) {
+        const tokens = stripAutoBackgroundWrapperPrefixes(seg).split(/\s+/);
+        const word = commandBasename(tokens[0] ?? "");
+        if (word === "git")
+            return false;
+        if (word === "xargs" && tokens.slice(1).some((t) => commandBasename(t) === "git"))
+            return false;
+    }
+    const firstWord = commandBasename(stripAutoBackgroundWrapperPrefixes(segments[0]).split(/\s+/)[0] ?? "");
+    if (AUTO_BACKGROUND_BLOCKED_FIRST_WORDS.has(firstWord))
+        return false;
+    return true;
+}
 async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef, detach, execClamp, toolCallId) {
     let timeout = Math.min(BASH_MAX_TIMEOUT_SEC, Math.max(1, Math.floor(timeoutSec ?? BASH_DEFAULT_TIMEOUT_SEC)));
     const requestedSec = timeout;
@@ -1398,6 +1449,7 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
                         deregisterKill?.();
                         deregisterKill = undefined;
                     },
+                    autoBackgroundOnTimeout: detach.autoBackgroundEligible === true && !clampedByDeadline,
                 }
                 : {}),
             ...(registerKillHandle !== undefined && toolCallId !== undefined
@@ -1460,7 +1512,7 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
         return `Error (${toolName}): command execution failed (${res.error.code}): ${res.error.message}. Whether the command started or completed could not be determined — verify its effects before retrying.`;
     }
     if (res.value.detached && detach) {
-        return await detach.onDetached(res.value.detached.shellId, res.value.stdout, res.value.stderr);
+        return await detach.onDetached(res.value.detached.shellId, res.value.stdout, res.value.stderr, res.value.detached.cause);
     }
     let { stderr } = res.value;
     const { stdout, exitCode } = res.value;
@@ -1656,7 +1708,7 @@ export function makeBashTool(env, rootCanonical, coAuthor = false, cwdRef = { cu
             const detachChain = taskOpts.detachHub && taskOpts.taskRegistry && hasBackgroundShell(env) && env.backgroundCapabilities.supportsDetach === true
                 ? {
                     signal: taskOpts.detachHub.signalFor(ctx.toolCallId),
-                    onDetached: async (shellId, stdoutSoFar, stderrSoFar) => {
+                    onDetached: async (shellId, stdoutSoFar, stderrSoFar, cause) => {
                         const sessionScoped = taskOpts.sessionId !== undefined;
                         const owner = sessionScoped ? taskOpts.sessionId : (ctx.taskId ?? taskOpts.taskOwner);
                         const scope = ctx.principal ?? taskOpts.taskScope;
@@ -1720,7 +1772,9 @@ export function makeBashTool(env, rootCanonical, coAuthor = false, cwdRef = { cu
                             ? ` Time budget: auto-terminates if still running after ${Math.min(adoptCaps.defaultBgTimeoutSec, adoptCaps.maxBgTimeoutSec)}s (hard cap ${adoptCaps.maxBgTimeoutSec}s).`
                             : "";
                         return {
-                            content: `Command moved to background; task_id=${taskId}. ` +
+                            content: (cause === "timeout"
+                                ? `Command exceeded its timeout but is still running — moved to background instead of being killed (task_id=${taskId}). `
+                                : `Command moved to background; task_id=${taskId}. `) +
                                 (outputFile !== undefined
                                     ? `Output file: ${outputFile} (full output is appended there — Read it any time). `
                                     : `Use TaskOutput("${taskId}") to read its output. `) +
@@ -1730,9 +1784,10 @@ export function makeBashTool(env, rootCanonical, coAuthor = false, cwdRef = { cu
                                     : `Poll TaskOutput until its status is no longer "running".`) +
                                 adoptBudgetNote +
                                 (tail ? `\n--- output so far (tail) ---\n${tail}` : ""),
-                            details: { type: "bash", detached: true, task_id: taskId, ...(description !== undefined ? { description } : {}), ...(outputFile !== undefined ? { output_file: outputFile } : {}) },
+                            details: { type: "bash", detached: true, task_id: taskId, ...(description !== undefined ? { description } : {}), ...(outputFile !== undefined ? { output_file: outputFile } : {}), ...(cause === "timeout" ? { autoBackgrounded: true } : {}) },
                         };
                     },
+                    autoBackgroundEligible: taskOpts.autoBackgroundOnTimeout === true && canAutoBackground(command),
                 }
                 : undefined;
             let res;
@@ -1882,6 +1937,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
                 onTaskNotification: opts.taskNotification,
                 detachHub: opts.detachHub,
                 execClamp: opts.execClamp,
+                ...(opts.autoBackgroundOnTimeout !== undefined ? { autoBackgroundOnTimeout: opts.autoBackgroundOnTimeout } : {}),
             }));
         if (!readOnly && mountBackgroundTaskTools && hasBackgroundShell(env)) {
             tools.push(opts.taskRegistry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "1.427.0",
+  "version": "1.429.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",