@livx.cc/agentx 0.99.39 → 0.99.41

package/dist/cli.js

@@ -258,13 +258,17 @@ function stripContent(content, stub) {
   });
   return changed ? out : content;
 }
+function clauses(sentence) {
+  return sentence.split(/[,;:]\s*|\s+(?:so|but|and|then|because|however|therefore|thus|although|though)\s+/i).map((c) => c.trim()).filter(Boolean);
+}
 function endsOnAnnouncedAction(text) {
   const sentences = text.split(/(?<=[.!?])\s+|\n+/).map((s) => s.trim()).filter(Boolean);
   const last = sentences[sentences.length - 1];
   if (!last || NEXT_STEP.test(last) || SIGN_OFF.test(last)) return false;
-  return ANNOUNCED_ACTION.test(last);
+  if (PROGRESSIVE.test(last)) return true;
+  return clauses(last).some((c) => !NEXT_STEP.test(c) && !SIGN_OFF.test(c) && COMMITMENT.test(c));
 }
-var log2, p_sep, IMAGE_ELIDE_STUB, IMAGE_REF_SCHEME, REF_REGISTRY_MAX, refRegistry, isImageRefUrl, bearsImage, ANNOUNCED_ACTION, NEXT_STEP, SIGN_OFF;
+var log2, p_sep, IMAGE_ELIDE_STUB, IMAGE_REF_SCHEME, REF_REGISTRY_MAX, refRegistry, isImageRefUrl, bearsImage, COMMITMENT, PROGRESSIVE, NEXT_STEP, SIGN_OFF;
 var init_llm = __esm({
   "src/llm.ts"() {
     "use strict";
@@ -277,7 +281,8 @@ var init_llm = __esm({
     refRegistry = /* @__PURE__ */ new Map();
     isImageRefUrl = (url) => !!url && url.startsWith(IMAGE_REF_SCHEME);
     bearsImage = (m) => messageHasImage(m.content) || toolImageRef(m.content) != null;
-    ANNOUNCED_ACTION = /^(?:also\s+|now\s+|then\s+)*(?:let me\b|i'?ll\b|i will\b|i'?m going to\b|(?:re-?)?(?:check|search|scan|read|verify|run|inspect|expand|look|examin|continu|proceed|try|fetch|load|open|test|build|grep|find|review|trac|dig|explor)\w*ing\b)/i;
+    COMMITMENT = /^(?:also\s+|now\s+|then\s+|so\s+)*(?:let me\b(?!\s+know\b)|i'?ll\b|i will\b|i'?m going to\b|i\s+(?:still\s+|now\s+|first\s+)*need to\b)/i;
+    PROGRESSIVE = /^(?:also\s+|now\s+|then\s+)*(?:re-?)?(?:check|search|scan|read|verify|run|inspect|expand|look|examin|continu|proceed|try|fetch|load|open|test|build|grep|find|review|trac|dig|explor)\w*ing\b/i;
     NEXT_STEP = /^next (?:step|run|up)\b/i;
     SIGN_OFF = /^let me know\b/i;
   }
@@ -902,6 +907,8 @@ function makeWebFetchTool(options = {}) {
   return {
     name: "WebFetch",
     description: "Fetch an http/https URL and return its readable text (HTML is stripped to text). Use to read docs or web pages. Returns the status line then up to ~100k chars of content.",
+    // Declared so a transport above the loop sizes its deadline around this one (see AgentTool.maxDurationMs).
+    maxDurationMs: timeoutMs,
     parameters: { type: "object", required: ["url"], properties: { url: { type: "string", description: "absolute http(s) URL" } } },
     async run({ url }) {
       const doFetch = options.fetch ?? globalThis.fetch;
@@ -1354,11 +1361,12 @@ function toolRegistry() {
   const all = [bashTool, readTool, editTool, grepTool, globTool, writeTool, multiEditTool, applyEditsTool, repoMapTool, reviewTool(), todoWriteTool, webFetchTool, webSearchTool, webSearchAnthropicTool];
   return Object.fromEntries(all.map((t) => [t.name, t]));
 }
-function toolsByName(names) {
+function toolsByName(names, available) {
   const reg = toolRegistry();
+  const extra = Object.fromEntries((available ?? []).map((t) => [t.name, t]));
   return names.map((n) => {
-    const t = reg[n];
-    if (!t) throw new Error(`unknown tool '${n}'. Known: ${Object.keys(reg).join(", ")}`);
+    const t = extra[n] ?? reg[n];
+    if (!t) throw new Error(`unknown tool '${n}'. Known: ${[.../* @__PURE__ */ new Set([...Object.keys(extra), ...Object.keys(reg)])].join(", ")}`);
     return t;
   });
 }
@@ -2105,6 +2113,7 @@ var init_shell_sandbox = __esm({
 var tools_shell_exports = {};
 __export(tools_shell_exports, {
   ShellJobRegistry: () => ShellJobRegistry,
+  formatJobExit: () => formatJobExit,
   makeRealShellTool: () => makeRealShellTool,
   makeShellJobTools: () => makeShellJobTools
 });
@@ -2135,12 +2144,45 @@ async function nodeSpawn() {
   if (!_spawn) _spawn = (await import("child_process")).spawn;
   return _spawn;
 }
+function formatJobExit(n) {
+  return `[background job ${n.id} ${n.status}${n.exitCode != null ? ` exit ${n.exitCode}` : ""}] \`${n.command}\`
+` + (n.tail ? `${n.tail}
+` : "(no output)\n") + `Read the full output with ShellOutput({id:"${n.id}"}).`;
+}
 function makeRealShellTool(options) {
   const defaultTimeoutMs = options.timeoutMs ?? 12e4;
   const maxTimeoutMs = Math.max(options.maxTimeoutMs ?? 6e5, defaultTimeoutMs);
+  const backgroundDoc = () => {
+    const base = "Set `background:true` for long-running processes (servers, watchers) and for anything that already timed out in the foreground \u2014 returns a job id immediately; poll with ShellOutput/ShellStatus, stop with ShellKill. ";
+    const notify = options.registry?.notifiesOnExit ? "Its completion is reported back to you when it finishes." : "NOTE: nothing will tell you when it finishes \u2014 poll ShellOutput/ShellStatus yourself, or you will never see its result.";
+    const survival = options.jobsSurviveRun === false ? "The job does NOT survive the end of this run, so do not stop while you still need its result." : "It keeps running across turns.";
+    return `${base}${notify} ${survival}`;
+  };
   return {
     name: "Shell",
-    description: `Run a shell command via /bin/sh in the working directory. Executes any installed binary \u2014 ls, cat, grep, git, bun, node, curl, scripts, etc. Returns combined stdout+stderr; non-zero exits are prefixed \`[exit N]\`. Runs non-interactively with no terminal (stdin is /dev/null): commands that prompt for input fail fast rather than hang \u2014 for privileged actions use a non-interactive flag (e.g. \`sudo -n\`), or ask the user to run the command themselves. Each command is killed after ${defaultTimeoutMs}ms (result \`[exit 124]\` with whatever output it produced) \u2014 pass \`timeoutMs\` (max ${maxTimeoutMs}) for a legitimately slower command, and always bound network commands yourself (e.g. \`curl -m 10\`). Set \`background:true\` for long-running processes (servers, watchers) \u2014 returns a job id immediately; poll with ShellOutput, stop with ShellKill.`,
+    // Rebind for an isolated child agent (git worktree): same policy/env/timeouts, new cwd. The
+    // `registry` is deliberately dropped — it is bound to the PARENT's cwd (and, in hosts like
+    // shraga-ee, to the parent's session), so a background job started from the child would run
+    // outside the child's isolation and report into the parent. Background stays a parent capability
+    // (`makeShellJobTools`' companions drop out of an isolated child entirely — see their `withCwd`).
+    // Only `run` is rebuilt: everything else is carried over from THIS instance, because a host may
+    // have mutated the tool AFTER construction (shraga-ee renames `Shell` -> `Bash` and its system
+    // prompt says `Bash` everywhere). Rebuilding from `options` alone silently dropped that rename,
+    // so a worktree child advertised `Shell` while being told to call `Bash` — an unknown-tool error
+    // on its first call, and a hard failure for an agentType def whose allowlist names `Bash`.
+    // `description` is the ONE thing taken from the rebound tool instead: it is derived from the
+    // options and states whether `background:true` works — the rebind drops the registry, so carrying
+    // the parent's text over would advertise a background capability the child does not have. (The
+    // spread also collapses the getter below to a plain value, which is why this override is explicit.)
+    withCwd(cwd) {
+      const rebound = makeRealShellTool({ ...options, cwd, registry: void 0 });
+      return { ...this, description: rebound.description, run: rebound.run, withCwd: rebound.withCwd };
+    },
+    get description() {
+      return `Run a shell command via /bin/sh in the working directory. Executes any installed binary \u2014 ls, cat, grep, git, bun, node, curl, scripts, etc. Returns combined stdout+stderr; non-zero exits are prefixed \`[exit N]\`. Runs non-interactively with no terminal (stdin is /dev/null): commands that prompt for input fail fast rather than hang \u2014 for privileged actions use a non-interactive flag (e.g. \`sudo -n\`), or ask the user to run the command themselves. Each command is killed after ${defaultTimeoutMs}ms (result \`[exit 124]\` with whatever output it produced) \u2014 pass \`timeoutMs\` (max ${maxTimeoutMs}) for a legitimately slower command, and always bound network commands yourself (e.g. \`curl -m 10\`). ` + backgroundDoc();
+    },
+    // Declared so transports above the agent loop can size their own deadline with headroom (see AgentTool.maxDurationMs).
+    maxDurationMs: maxTimeoutMs,
     parameters: {
       type: "object",
       required: ["command"],
@@ -2242,14 +2284,17 @@ function makeRealShellTool(options) {
   };
 }
 function reasonFor(timedOut, timeoutMs, body) {
-  const head = timedOut ? `[exit 124] timed out after ${timeoutMs}ms (killed)` : "[exit 130] cancelled (killed)";
+  const head = timedOut ? `[exit 124] timed out after ${timeoutMs}ms (killed). Re-running this command unchanged will time out again. Either re-run it with background:true (returns a job id immediately; poll with ShellOutput/ShellStatus, stop with ShellKill) or narrow it so it can finish \u2014 bound it, scope it, or ask for less.` : "[exit 130] cancelled (killed)";
   return body ? `${head}
+Partial output before the kill:
 ${body}` : head;
 }
 function makeShellJobTools(registry) {
   const idParam = { type: "object", properties: { id: { type: "string", description: "the job id from Shell({background:true})" } } };
+  const dropOnRebind = { withCwd: () => void 0 };
   return [
     {
+      ...dropOnRebind,
       name: "ShellOutput",
       description: "Read the accumulated output (tail) of a background Shell job by id.",
       parameters: { type: "object", required: ["id"], properties: { id: { type: "string" } } },
@@ -2262,6 +2307,7 @@ ${clean(out) || "(no output yet)"}`;
       }
     },
     {
+      ...dropOnRebind,
       name: "ShellStatus",
       description: "Status of a background Shell job (running/exited/killed + exit code). Omit `id` to list all jobs.",
       parameters: idParam,
@@ -2275,6 +2321,7 @@ ${clean(out) || "(no output yet)"}`;
       }
     },
     {
+      ...dropOnRebind,
       name: "ShellKill",
       description: "Stop a running background Shell job by id (SIGTERM).",
       parameters: { type: "object", required: ["id"], properties: { id: { type: "string" } } },
@@ -2324,12 +2371,14 @@ var init_tools_shell = __esm({
               job.status = "error";
               append(`
 [error] ${err2?.message ?? err2}`);
+              this.notifyExit(id, job);
             }
           });
           proc.on("close", (code) => {
             if (job.status === "running") {
               job.status = "exited";
               job.exitCode = code ?? void 0;
+              this.notifyExit(id, job);
             }
           });
         } catch (e) {
@@ -2339,6 +2388,29 @@ var init_tools_shell = __esm({
         this.jobs.set(id, job);
         return id;
       }
+      /** Fire `onExit` at most once per job, with the tail so the model can act without a second round-trip. */
+      notified = /* @__PURE__ */ new Set();
+      notifyExit(id, job) {
+        if (this.notified.has(id) || !this.cfg.onExit) return;
+        this.notified.add(id);
+        try {
+          this.cfg.onExit({ id, command: job.command, status: job.status, exitCode: job.exitCode, tail: clean(job.buf).slice(-4e3) });
+        } catch {
+        }
+      }
+      /**
+       * Wire (or rewire) the completion callback AFTER construction. A host that only gets its agent handle
+       * once the Agent is constructed (the library's own `fullAgentOptions` preset, any embedder) could not
+       * pass `onExit` up front, so background completions were silently REPL-only. Set it here instead.
+       */
+      setOnExit(fn) {
+        this.cfg.onExit = fn;
+      }
+      /** Whether a finished job will actually be reported to the model. The Shell tool's description reads
+       *  this so it can't promise a completion notice on a host that discards it. */
+      get notifiesOnExit() {
+        return !!this.cfg.onExit;
+      }
       /** Current tail output for a job (null = no such job). */
       output(id) {
         return this.jobs.get(id)?.buf ?? (this.jobs.has(id) ? "" : null);
@@ -3082,6 +3154,32 @@ ${sections.join("\n\n---\n\n")}`;
 init_tools();
 import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
 import { join as join4 } from "path";
+
+// src/models.ts
+var MODEL_ALIASES = {
+  fable: "claude-fable-5",
+  "fable-5": "claude-fable-5",
+  opus: "claude-opus-4-8",
+  "opus-4-8": "claude-opus-4-8",
+  "opus-4-7": "claude-opus-4-7",
+  "opus-4-6": "claude-opus-4-6",
+  sonnet: "claude-sonnet-4-6",
+  haiku: "claude-haiku-4-5-20251001"
+};
+function resolveModelAlias(input) {
+  const slash = input.indexOf("/");
+  const prefix = slash === -1 ? "" : input.slice(0, slash + 1);
+  const rest = slash === -1 ? input : input.slice(slash + 1);
+  return prefix + (MODEL_ALIASES[rest.toLowerCase()] ?? rest);
+}
+function modelProvider(model) {
+  const i = model.indexOf("/");
+  if (i !== -1) return model.slice(0, i);
+  if (/^claude-/i.test(model)) return "anthropic";
+  return `?${model}`;
+}
+
+// src/subagent.ts
 init_OverlayFilesystem();
 init_worktree();
 init_NodeDiskFilesystem();
@@ -3099,6 +3197,30 @@ async function boundedPool(items, limit, fn) {
   await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
   return out;
 }
+var SUBAGENT_MAX_DURATION_MS = 18e5;
+function wallClock(parent, ms) {
+  const ac = new AbortController();
+  let fired = false;
+  const onParent = () => ac.abort();
+  const timer = setTimeout(() => {
+    fired = true;
+    ac.abort();
+  }, ms);
+  if (parent) {
+    if (parent.aborted) ac.abort();
+    else parent.addEventListener("abort", onParent, { once: true });
+  }
+  return {
+    signal: ac.signal,
+    timedOut: () => fired,
+    dispose: () => {
+      clearTimeout(timer);
+      parent?.removeEventListener("abort", onParent);
+    }
+  };
+}
+var deadlineNote = (ms) => `
+[It was stopped by the sub-task wall-clock deadline of ${Math.round(ms / 1e3)}s \u2014 not by the user. Re-delegate a NARROWER sub-task (or continue from the trace); the same prompt will hit the same deadline again.]`;
 function sanitizeSlug(raw) {
   return raw.replace(/[^a-zA-Z0-9._-]/g, "-").replace(/-+/g, "-").slice(0, 40);
 }
@@ -3116,6 +3238,14 @@ function createWorktreeFs(cwd, label, index) {
 function releaseWorktree(handle) {
   return cleanupWorktree(handle.repoRoot, handle.slug, { force: true });
 }
+function rebindTools(tools, root) {
+  if (!tools || !root) return tools;
+  return tools.flatMap((t) => {
+    if (!t.withCwd) return [t];
+    const rebound = t.withCwd(root);
+    return rebound ? [rebound] : [];
+  });
+}
 function worktreePromptPrefix(branch) {
   return `You are running in an isolated git worktree on branch "${branch}". When you finish making changes, commit them with a clear message before replying with your summary. Your worktree will be removed after you finish \u2014 only committed work survives (on the branch).
 
@@ -3161,33 +3291,52 @@ function abortHint(label, res, file) {
 }
 async function runChildTraced(args) {
   const { opts, label, agentType, prompt } = args;
-  if (args.signal) args.childOpts.signal = args.signal;
+  const deadlineMs = opts.maxDurationMs ?? SUBAGENT_MAX_DURATION_MS;
+  const wc = wallClock(args.signal, deadlineMs);
+  args.childOpts.signal = wc.signal;
   const file = opts.traceDir ? traceFileFor(opts.traceDir, label, args.childDepth) : void 0;
   const meta = { label, agentType, prompt };
   const child = new Agent(args.childOpts);
   if (file) installTrace(child, file, meta);
-  const res = await child.run(prompt);
-  if (file) flushTrace(file, meta, child.transcript, res.finishReason);
-  const result = res.finishReason === "stop" ? res.text || `(child '${label}' finished with no summary; finishReason=${res.finishReason})` : abortHint(label, res, file);
+  let res;
+  try {
+    res = await child.run(prompt);
+  } finally {
+    wc.dispose();
+  }
+  if (file) flushTrace(file, meta, child.transcript, wc.timedOut() ? "deadline" : res.finishReason);
+  let result = res.finishReason === "stop" ? res.text || `(child '${label}' finished with no summary; finishReason=${res.finishReason})` : abortHint(label, res, file);
+  if (wc.timedOut()) {
+    log5.warn(`sub-task '${label}' hit its ${deadlineMs}ms wall-clock deadline (steps=${res.steps})`);
+    result += deadlineNote(deadlineMs);
+  }
   await opts.hooks?.onSubagentStop?.(result, { label, agentType });
   return { res, result };
 }
-function childOptionsFor(opts, fs, depth, maxDepth, agentType) {
+function childOptionsFor(opts, fs, depth, maxDepth, agentType, model, root) {
   let def;
   if (agentType) {
     def = (opts.agents ?? []).find((a) => a.name === agentType);
     if (!def) return `no subagent type '${agentType}'. Available: ${(opts.agents ?? []).map((a) => a.name).join(", ") || "(none defined)"}`;
   }
-  const childOpts = { ai: opts.ai, fs, model: def?.model ?? opts.model, subagents: true, depth: depth + 1, maxDepth, traceDir: opts.traceDir };
+  const childModel = resolveModelAlias(model || def?.model || opts.model);
+  const childOpts = { ai: opts.ai, fs, model: childModel, subagents: true, depth: depth + 1, maxDepth, traceDir: opts.traceDir };
   if (opts.maxSteps != null) childOpts.maxSteps = opts.maxSteps;
-  if (def?.systemPrompt) childOpts.systemPrompt = def.systemPrompt;
+  const childPrompt = def?.systemPrompt ?? opts.systemPrompt;
+  if (childPrompt) childOpts.systemPrompt = childPrompt;
+  const inherited = rebindTools(opts.tools, root);
   if (def?.tools?.length) {
     try {
-      childOpts.tools = toolsByName(def.tools);
+      childOpts.tools = toolsByName(def.tools, inherited);
     } catch (e) {
       return `subagent '${agentType}' declares an unknown tool \u2014 ${e.message}`;
     }
+  } else if (inherited?.length) {
+    childOpts.tools = inherited;
   }
+  const po = opts.providerOptionsFor?.(childModel);
+  if (po) childOpts.providerOptions = po;
+  if (opts.hooks?.preToolUse) childOpts.hooks = { preToolUse: opts.hooks.preToolUse.bind(opts.hooks) };
   return childOpts;
 }
 function makeTaskTool(opts) {
@@ -3195,7 +3344,7 @@ function makeTaskTool(opts) {
   const maxDepth = opts.maxDepth ?? 2;
   return {
     name: "Task",
-    description: 'Delegate a self-contained sub-task to a child agent over the same filesystem. It runs autonomously with its own step budget and returns a concise summary \u2014 use to isolate context-heavy work (broad search, a scoped refactor). Provide a short `description` and a full `prompt`. If it is interrupted or fails, the result is a STATUS HINT with a pointer to its full transcript (Read it to recover what it did, then decide whether to continue or restart) \u2014 do not assume an incomplete sub-task succeeded. Set `background: true` to run it detached (returns a job id to poll with JobOutput while you keep working); its file edits are overlay-isolated and commit when it finishes. Set `isolation: "worktree"` to run in a real git worktree (needed when the child uses real shell commands that must see/modify actual files) \u2014 slower (~200ms setup), auto-cleaned if no changes.',
+    description: 'Delegate a self-contained sub-task to a child agent over the same filesystem. It runs autonomously with its own step budget and a wall-clock deadline, and returns a concise summary \u2014 use to isolate context-heavy work (broad search, a scoped refactor). Provide a short `description` and a full `prompt`. If it is interrupted or fails, the result is a STATUS HINT with a pointer to its full transcript (Read it to recover what it did, then decide whether to continue or restart) \u2014 do not assume an incomplete sub-task succeeded. Set `background: true` to run it detached (returns a job id to poll with JobOutput while you keep working); its VFS file edits are overlay-isolated and commit when it finishes \u2014 but a child that uses the real `Shell` writes straight to the working tree (an overlay cannot isolate a real process), so pair shell-heavy work with `isolation: "worktree"`. Set `isolation: "worktree"` to run in a real git worktree (needed when the child uses real shell commands that must see/modify actual files \u2014 its shell is re-bound to the worktree \u2014 keeping any name your host gave it \u2014 and background shell jobs, including inspecting or killing MINE, are unavailable there) \u2014 slower (~200ms setup), auto-cleaned if no changes. The child inherits YOUR tools and system prompt by default (and is subject to the same tool-use gate); pass `model` to run this one sub-task on a different model (e.g. a cheap one for bulk search, a stronger one for hard reasoning) \u2014 it overrides the agentType default.',
     parameters: {
       type: "object",
       required: ["description", "prompt"],
@@ -3203,11 +3352,18 @@ function makeTaskTool(opts) {
         description: { type: "string", description: "a short (3-5 word) label for the sub-task" },
         prompt: { type: "string", description: "the full instructions the child agent should carry out" },
         agentType: { type: "string", description: "optional named subagent type (its persona, model, and scoped tools) \u2014 see the catalog" },
+        model: { type: "string", description: 'optional model for THIS sub-task (alias like "haiku"/"opus"/"sonnet", or a full id). Overrides the agentType default; otherwise the child runs on your model.' },
         background: { type: "boolean", description: "run detached (overlay-isolated, commits on finish); returns a job id to poll with JobOutput instead of blocking" },
         isolation: { type: "string", enum: ["overlay", "worktree"], description: 'isolation mode: "overlay" (default, VFS layer) or "worktree" (real git worktree for shell-heavy work)' }
       }
     },
-    async run({ description, prompt, agentType, background, isolation }, ctx) {
+    // Declared because it is ENFORCED (see runChildTraced) — a transport above the loop sizes its own
+    // deadline around this one (AgentTool.maxDurationMs). Declaring an unenforced number would be a lie;
+    // declaring nothing left `Task` invisible to toolTimeoutViolations, which is the same hole.
+    maxDurationMs: opts.maxDurationMs ?? SUBAGENT_MAX_DURATION_MS,
+    maxDurationEnforced: true,
+    // the wall clock below ABORTS the child at this bound — it cannot be overrun, so the transport needs slack, not a doubling
+    async run({ description, prompt, agentType, model, background, isolation }, ctx) {
       if (depth >= maxDepth) {
         return `Error: Task depth limit reached (maxDepth ${maxDepth}). Cannot spawn another child agent \u2014 do this work directly instead.`;
       }
@@ -3230,7 +3386,7 @@ function makeTaskTool(opts) {
             fs2 = overlay;
             commit = () => overlay.commit();
           }
-          const childOpts2 = childOptionsFor(opts, fs2, depth, maxDepth, agentType);
+          const childOpts2 = childOptionsFor(opts, fs2, depth, maxDepth, agentType, model, wtHandle2?.worktreePath);
           if (typeof childOpts2 === "string") throw new Error(childOpts2);
           const childPrompt = wtHandle2 ? worktreePromptPrefix(wtHandle2.branch) + String(prompt ?? "") : String(prompt ?? "");
           const { res, result } = await runChildTraced({ opts, childOpts: childOpts2, prompt: childPrompt, label, agentType, childDepth: depth + 1, signal });
@@ -3260,7 +3416,7 @@ function makeTaskTool(opts) {
       } else {
         fs = opts.fs;
       }
-      const childOpts = childOptionsFor(opts, fs, depth, maxDepth, agentType);
+      const childOpts = childOptionsFor(opts, fs, depth, maxDepth, agentType, model, wtHandle?.worktreePath);
       if (typeof childOpts === "string") {
         wtHandle && releaseWorktree(wtHandle);
         return `Error: ${childOpts}`;
@@ -3289,7 +3445,7 @@ function makeTaskBatchTool(opts) {
   const maxParallel = opts.maxParallel ?? 4;
   return {
     name: "TaskBatch",
-    description: 'Delegate SEVERAL independent sub-tasks to child agents that run concurrently; returns all their summaries. Each child is write-isolated (its file edits are merged back in array order). Use for parallel fan-out (review/search/scoped refactors across files). Provide `tasks: [{ description, prompt, agentType? }]`. Set `isolation: "worktree"` to run each child in its own git worktree (needed for real shell commands) \u2014 slower, auto-cleaned if no changes.',
+    description: 'Delegate SEVERAL independent sub-tasks to child agents that run concurrently; returns all their summaries. Each child is write-isolated at the VFS level (its file edits are merged back in array order); real `Shell` commands are NOT \u2014 use `isolation: "worktree"` for those. Use for parallel fan-out (review/search/scoped refactors across files). Provide `tasks: [{ description, prompt, agentType?, model? }]` \u2014 each child inherits your tools and system prompt, and `model` runs that one child on a different model. Set `isolation: "worktree"` to run each child in its own git worktree (needed for real shell commands) \u2014 slower, auto-cleaned if no changes.',
     parameters: {
       type: "object",
       required: ["tasks"],
@@ -3303,18 +3459,26 @@ function makeTaskBatchTool(opts) {
             properties: {
               description: { type: "string", description: "a short (3-5 word) label" },
               prompt: { type: "string", description: "the full instructions for this child" },
-              agentType: { type: "string", description: "optional named subagent type" }
+              agentType: { type: "string", description: "optional named subagent type" },
+              model: { type: "string", description: "optional model for this child (alias or full id); overrides the agentType default" }
             }
           }
         },
         isolation: { type: "string", enum: ["overlay", "worktree"], description: 'isolation mode for ALL children: "overlay" (default) or "worktree" (real git worktree each)' }
       }
     },
+    // Same enforced bound as `Task`, applied to the WHOLE batch (below), not per child — otherwise the
+    // honest ceiling would be ceil(n/maxParallel) x the per-child deadline, i.e. unbounded in `tasks`.
+    maxDurationMs: opts.maxDurationMs ?? SUBAGENT_MAX_DURATION_MS,
+    maxDurationEnforced: true,
+    // the wall clock below ABORTS the child at this bound — it cannot be overrun, so the transport needs slack, not a doubling
     async run({ tasks, isolation }, ctx) {
       if (depth >= maxDepth) return `Error: Task depth limit reached (maxDepth ${maxDepth}). Cannot spawn child agents \u2014 do this work directly instead.`;
       const list = Array.isArray(tasks) ? tasks : [];
       if (!list.length) return "Error: TaskBatch needs a non-empty `tasks` array.";
       const useWorktree = isolation === "worktree";
+      const batchDeadlineMs = opts.maxDurationMs ?? SUBAGENT_MAX_DURATION_MS;
+      const batchClock = wallClock(ctx.signal, batchDeadlineMs);
       const results = await boundedPool(list, maxParallel, async (t, i) => {
         const label = String(t?.description ?? t?.agentType ?? `task ${i + 1}`);
         let fs;
@@ -3329,16 +3493,16 @@ function makeTaskBatchTool(opts) {
           overlay = new OverlayFilesystem(opts.fs);
           fs = overlay;
         }
-        const childOpts = childOptionsFor(opts, fs, depth, maxDepth, t?.agentType);
+        const childOpts = childOptionsFor(opts, fs, depth, maxDepth, t?.agentType, t?.model, wtHandle?.worktreePath);
         if (typeof childOpts === "string") return { label, error: childOpts, ok: false };
         try {
           const childPrompt = wtHandle ? worktreePromptPrefix(wtHandle.branch) + String(t?.prompt ?? "") : String(t?.prompt ?? "");
-          const { res, result } = await runChildTraced({ opts, childOpts, prompt: childPrompt, label, agentType: t?.agentType, childDepth: depth + 1, signal: ctx.signal });
+          const { res, result } = await runChildTraced({ opts, childOpts, prompt: childPrompt, label, agentType: t?.agentType, childDepth: depth + 1, signal: batchClock.signal });
           return { label, text: result, overlay, wtHandle, ok: res.finishReason !== "error" && res.finishReason !== "aborted" };
         } catch (e) {
           return { label, error: e instanceof Error ? e.message : String(e), wtHandle, ok: false };
         }
-      });
+      }).finally(() => batchClock.dispose());
       const lines = [];
       for (const r of results) {
         if (r.ok && r.overlay) await r.overlay.commit().catch(() => {
@@ -3352,7 +3516,7 @@ function makeTaskBatchTool(opts) {
         lines.push(`### ${lines.length + 1}. ${r.label}
 ${r.error ? `ERROR: ${r.error}` : r.text || "(no summary)"}${extra}`);
       }
-      return lines.join("\n\n");
+      return lines.join("\n\n") + (batchClock.timedOut() ? deadlineNote(batchDeadlineMs) : "");
     }
   };
 }
@@ -3756,6 +3920,10 @@ var AgentOptions = class {
   autoTest;
   /** Provider-specific options forwarded to ai.chat() (e.g. cursor mcpServers, cwd). */
   providerOptions;
+  /** Derive `providerOptions` for a DELEGATED child whose model may differ from this agent's
+   *  (`Task({ model })` / an agentType def). Default: inherit `providerOptions` only when the child's
+   *  model is on the SAME provider — cursor's `cwd`/`cursorSession` on an anthropic child is a 400. */
+  providerOptionsFor;
   /** Prompt caching (providers that support it, e.g. Anthropic): cache tools/system/conversation
    *  prefix across the loop's steps — reads cost 0.1x, writes 1.25x. A multi-step agent loop
    *  re-sends its whole prefix every step, so this is a large net cost cut. Default on. */
@@ -3979,7 +4147,19 @@ var Agent = class _Agent {
         agents = loaded.agents;
         if (loaded.catalog) systemPrompt += "\n\n" + loaded.catalog;
       }
-      const taskOpts = { ai: o.ai, model: o.model, fs, depth: o.depth, maxDepth: o.maxDepth, agents, hooks: o.hooks, traceDir: o.traceDir };
+      const taskOpts = {
+        ai: o.ai,
+        model: o.model,
+        fs,
+        depth: o.depth,
+        maxDepth: o.maxDepth,
+        agents,
+        hooks: o.hooks,
+        traceDir: o.traceDir,
+        tools: [...o.tools, ...this.injectedTools],
+        systemPrompt: o.systemPrompt,
+        providerOptionsFor: o.providerOptionsFor ?? ((m) => modelProvider(m) === modelProvider(o.model) ? o.providerOptions : void 0)
+      };
       tools = [...tools, makeTaskTool(taskOpts), makeTaskBatchTool(taskOpts)];
     }
     if (o.checkpoints) tools = [...tools, ...checkpointTools()];
@@ -4116,7 +4296,17 @@ var Agent = class _Agent {
       const frag = reasoningToChatFragment(o.model, o.reasoning);
       const sentTools = o.model.startsWith("claude-code/") ? [] : wireTools;
       const isCursorWithTools = o.model.startsWith("cursor/") && wireTools.length > 0;
+      const hostToolTimeoutMs = o.providerOptions?.toolTimeoutMs;
+      const derivedToolTimeoutMs = Math.max(TRANSPORT_TOOL_TIMEOUT_FLOOR_MS, ...this.activeTools.map(transportHeadroomMs));
+      const effectiveToolTimeoutMs = typeof hostToolTimeoutMs === "number" ? Math.max(hostToolTimeoutMs, derivedToolTimeoutMs) : derivedToolTimeoutMs;
+      if (isCursorWithTools) {
+        if (typeof hostToolTimeoutMs === "number" && effectiveToolTimeoutMs !== hostToolTimeoutMs) {
+          log6.warn(`providerOptions.toolTimeoutMs=${hostToolTimeoutMs}ms is below what the registered tools need \u2014 RAISED to ${effectiveToolTimeoutMs}ms. ${toolTimeoutViolations(this.activeTools, hostToolTimeoutMs).length} tool(s) could outlive it, and the transport would have destroyed their results. To lower it, lower the tools' own maxDurationMs (e.g. the Shell tool's maxTimeoutMs) instead.`);
+        }
+        for (const v of toolTimeoutViolations(this.activeTools, effectiveToolTimeoutMs)) log6.warn(v);
+      }
       const cursorPo = isCursorWithTools ? {
+        toolTimeoutMs: effectiveToolTimeoutMs,
         toolExecutor: async (name, args) => {
           const tc = { id: `cursor-${Date.now()}`, type: "function", function: { name, arguments: JSON.stringify(args) } };
           return await this.dispatch(tc);
@@ -4218,14 +4408,12 @@ var Agent = class _Agent {
           })() } }))
         });
         for (const a of delegatedTools) {
-          const out = typeof a.output === "string" ? a.output : a.output == null ? "" : (() => {
-            try {
-              return JSON.stringify(a.output);
-            } catch {
-              return String(a.output);
-            }
-          })();
-          this.transcript.push({ role: "tool", tool_call_id: a.id, content: cap > 0 && out.length > cap ? cropResult(out, cap) : out });
+          const name = a.name || "tool";
+          const r = delegatedResult(a.output);
+          const text = r.images.length ? r.text : nonEmptyResult(isVacuous(a.output) ? "" : r.text, name, deliveryOf(a.output, a.status));
+          const body = cap > 0 && text.length > cap ? cropResult(text, cap) : text;
+          const content = r.images.length ? [{ type: "text", text: body }, ...r.images.map((i) => imagePart(`data:${i.mimeType};base64,${i.data}`))] : body;
+          this.transcript.push({ role: "tool", tool_call_id: a.id, content });
         }
       }
       const toolCalls = res.toolCalls ?? [];
@@ -4278,9 +4466,10 @@ var Agent = class _Agent {
         const raw = await this.dispatch(tc);
         let content;
         if (typeof raw === "string") {
-          content = raw;
+          content = nonEmptyResult(raw, tc.function.name);
         } else {
-          const parts = [{ type: "text", text: raw.text }];
+          const hasImages = !!raw.images?.length;
+          const parts = [{ type: "text", text: hasImages ? raw.text : nonEmptyResult(raw.text ?? "", tc.function.name) }];
           for (const img of raw.images ?? []) parts.push(imagePart(`data:${img.mimeType};base64,${img.data}`));
           content = parts;
         }
@@ -4589,6 +4778,76 @@ var isAnthropicModel = (m) => !!m && (m.startsWith("anthropic/") || /(^|\/)claud
 function estimateTokens(m, keepRecentImages = 1) {
   return Math.ceil(sendBytes(m, keepRecentImages) / 4);
 }
+var TRANSPORT_TOOL_TIMEOUT_FLOOR_MS = 18e5;
+function transportHeadroomMs(t) {
+  const d = Number(t.maxDurationMs) || 0;
+  if (!d) return 0;
+  return t.maxDurationEnforced ? d + 6e4 : d * 2 + 6e4;
+}
+function toolTimeoutViolations(tools, transportMs) {
+  const out = [];
+  for (const t of tools) {
+    const d = Number(t.maxDurationMs) || 0;
+    if (d && d >= transportMs) {
+      out.push(`tool-timeout layering VIOLATED: '${t.name}' may run up to ${d}ms but the transport deadline is ${transportMs}ms \u2014 the transport wins the race and the tool's real result is destroyed. Raise providerOptions.toolTimeoutMs above ${d}ms.`);
+    }
+  }
+  return out;
+}
+function nonEmptyResult(out, name = "tool", delivery = "ran") {
+  if (out.trim()) return out;
+  if (delivery === "error") return `[${name}] failed with no error message \u2014 the tool reported an error but produced no detail. Its effect is UNKNOWN: verify the state before assuming it did or did not happen.`;
+  if (delivery === "missing") {
+    const base = `[${name}] returned no result. This is a transport failure, not an empty answer \u2014 the call's outcome is UNKNOWN, so do not assume it succeeded or failed.`;
+    return name === "Shell" ? `${base} Do NOT re-issue the same long-running command: run it with background:true and poll ShellOutput/ShellStatus, or narrow it so it can finish.` : `${base} Retry it, or verify the state another way before continuing.`;
+  }
+  return `[${name}] ran and returned no output. The call completed \u2014 this is an empty answer, not a failure.`;
+}
+function isVacuous(v, seen = /* @__PURE__ */ new Set(), depth = 0) {
+  if (v == null) return true;
+  if (typeof v === "string") return v.trim() === "";
+  if (typeof v !== "object") return false;
+  if (seen.has(v) || depth >= 64) return false;
+  seen.add(v);
+  try {
+    if (Array.isArray(v)) return v.every((x) => isVacuous(x, seen, depth + 1));
+    const proto = Object.getPrototypeOf(v);
+    if (proto !== Object.prototype && proto !== null) return false;
+    const vals = Object.values(v);
+    return vals.length === 0 || vals.every((x) => isVacuous(x, seen, depth + 1));
+  } finally {
+    seen.delete(v);
+  }
+}
+function delegatedResult(output) {
+  if (typeof output === "string") return { text: output, images: [] };
+  if (output == null) return { text: "", images: [] };
+  const isImg = (i) => i && typeof i.data === "string" && typeof i.mimeType === "string";
+  const o = output;
+  if (Array.isArray(o.images)) {
+    const images = o.images.filter(isImg);
+    if (images.length) return { text: typeof o.text === "string" ? o.text : "", images };
+  }
+  const blocks = Array.isArray(output) ? output : Array.isArray(o.content) ? o.content : void 0;
+  if (blocks) {
+    const images = blocks.filter((b) => b?.type === "image" && isImg(b)).map((b) => ({ mimeType: b.mimeType, data: b.data }));
+    if (images.length) {
+      const text = blocks.filter((b) => b?.type === "text" && typeof b.text === "string").map((b) => b.text).join("\n");
+      return { text, images };
+    }
+  }
+  try {
+    return { text: JSON.stringify(output), images: [] };
+  } catch {
+    return { text: String(output), images: [] };
+  }
+}
+function deliveryOf(output, status) {
+  if (status === "error") return "error";
+  if (output == null) return "missing";
+  if (status != null && status !== "completed") return "missing";
+  return "ran";
+}
 function cropResult(result, cap) {
   const head = result.slice(0, cap);
   const nl = head.lastIndexOf("\n");
@@ -8334,13 +8593,29 @@ function toResult(result) {
   }
   return { text: JSON.stringify(result) };
 }
-function mcpToolToAgentTool(spec, callTool, prefix = "mcp__") {
+var MCP_CALL_TIMEOUT_MS = 3e5;
+var TIMED_OUT = /* @__PURE__ */ Symbol("mcp-timeout");
+async function withDeadline(p, ms) {
+  let t;
+  try {
+    return await Promise.race([p, new Promise((res) => {
+      t = setTimeout(() => res(TIMED_OUT), ms);
+    })]);
+  } finally {
+    clearTimeout(t);
+  }
+}
+var mcpTimedOut = (name, ms = MCP_CALL_TIMEOUT_MS) => `[${name}] no response after ${ms / 1e3}s \u2014 the MCP server never answered. The call's outcome is UNKNOWN: do not assume it ran or that it failed. Verify the state (or pick a bounded/narrower call) before retrying.`;
+function mcpToolToAgentTool(spec, callTool, prefix = "mcp__", timeoutMs = MCP_CALL_TIMEOUT_MS) {
   return {
     name: `${prefix}${spec.name}`,
     description: spec.description ?? `MCP tool ${spec.name}`,
     parameters: spec.inputSchema ?? { type: "object", properties: {} },
+    maxDurationMs: timeoutMs,
     async run(args, _ctx) {
-      const r = toResult(await callTool(spec.name, args ?? {}));
+      const raw = await withDeadline(callTool(spec.name, args ?? {}), timeoutMs);
+      if (raw === TIMED_OUT) return mcpTimedOut(spec.name, timeoutMs);
+      const r = toResult(raw);
       return r.images?.length ? r : r.text;
     }
   };
@@ -8355,6 +8630,7 @@ function describeSpec(s) {
 }
 function makeMcpToolSearch(specs, callTool, options = {}) {
   const maxResults = options.maxResults ?? 10;
+  const callTimeoutMs = options.timeoutMs ?? MCP_CALL_TIMEOUT_MS;
   const byName = new Map(specs.map((s) => [s.name, s]));
   const catalogLine = `${specs.length} MCP tool(s) available \u2014 search by keyword, then call by exact name.`;
   const searchTool = {
@@ -8380,10 +8656,13 @@ function makeMcpToolSearch(specs, callTool, options = {}) {
         args: { type: "object", description: "arguments object for the tool (per its schema)" }
       }
     },
+    maxDurationMs: callTimeoutMs,
     async run({ name, args }) {
       const n = String(name ?? "");
       if (!byName.has(n)) return `Error: unknown MCP tool '${n}'. Use ToolSearch to find valid names.`;
-      const r = toResult(await callTool(n, args ?? {}));
+      const raw = await withDeadline(callTool(n, args ?? {}), callTimeoutMs);
+      if (raw === TIMED_OUT) return mcpTimedOut(n, callTimeoutMs);
+      const r = toResult(raw);
       return r.images?.length ? r : r.text;
     }
   };
@@ -9186,14 +9465,20 @@ Reference files in them by their mount path (the left side).`;
   const memoryWriteDir = memoryDir[0];
   const hooks = o.learnFromMistakes && memoryWriteDir ? composeHooks(o.hooks, lessonCapture({ fs, dir: memoryWriteDir, minRepeats: 2 })) : o.hooks;
   let realShell = [];
+  const agentRef = {};
   const useRealShell = o.realShell ?? !virtual;
   if (useRealShell && !virtual && !isClaudeCode) {
-    const jobs = new ShellJobRegistry({ cwd, killOnExit: true, osSandbox: o.osSandbox });
-    realShell = [makeRealShellTool({ cwd, registry: jobs, osSandbox: o.osSandbox }), ...makeShellJobTools(jobs)];
+    const jobs = new ShellJobRegistry({
+      cwd,
+      killOnExit: true,
+      osSandbox: o.osSandbox,
+      onExit: (n) => agentRef.agent?.inject(formatJobExit(n))
+    });
+    realShell = [makeRealShellTool({ cwd, registry: jobs, osSandbox: o.osSandbox, jobsSurviveRun: o.singleRun !== true }), ...makeShellJobTools(jobs)];
   }
   const scratchDir = o.scratch ? o.scratchDir ?? (virtual ? `${cwd}/.agent/scratch` : `${tmpdir()}/agentx-scratch-${process.pid}`) : void 0;
   const scratch = scratchDir ? new Scratch(fs, { dir: scratchDir }) : void 0;
-  return new Agent({
+  return agentRef.agent = new Agent({
     ai: o.ai,
     fs,
     model: o.model ?? "anthropic/claude-sonnet-4-6",