@livx.cc/agentx 0.99.40 → 0.99.42

package/dist/{mcp-aONOXRNk.d.ts → mcp-D5eN0JyQ.d.ts}

@@ -1,4 +1,4 @@
-import { A as AgentTool } from './tools-BWzPQVy0.js';
+import { A as AgentTool } from './tools-S-ArIR3o.js';
 
 /**
  * MCP bridge — adapt a Model Context Protocol tool list into the agent's AgentTool[],

package/dist/mcp.client.d.ts

@@ -1,5 +1,5 @@
-import { e as McpToolSearchOptions, f as McpToolSpec } from './mcp-aONOXRNk.js';
-import { A as AgentTool } from './tools-BWzPQVy0.js';
+import { e as McpToolSearchOptions, f as McpToolSpec } from './mcp-D5eN0JyQ.js';
+import { A as AgentTool } from './tools-S-ArIR3o.js';
 import '@livx.cc/wcli/core';
 
 /** A JSON-RPC 2.0 transport: request (awaits a result), notify (fire-and-forget), close. */

package/dist/models.d.ts

@@ -10,6 +10,20 @@
 declare const MODEL_ALIASES: Record<string, string>;
 /** Resolve an alias to a concrete id. A provider prefix ("anthropic/") is preserved; unknown ids pass through. */
 declare function resolveModelAlias(input: string): string;
+/** The provider of a model id ("cursor/x" -> "cursor"). Provider-specific `providerOptions` are only
+ *  portable within the same provider — leaking them across is a hard 400.
+ *
+ *  A BARE id is the common case, not the exception: `resolveModelAlias('haiku')` yields
+ *  `claude-haiku-4-5-20251001` with no prefix (ai.libx.js resolves it fuzzily downstream), so reading
+ *  only the literal "/" made every aliased child look like a provider switch and silently dropped the
+ *  parent's options. The fix belongs HERE — the alias table must keep emitting the ids ai.libx.js
+ *  expects, and the comparison is provider identity, not string identity.
+ *
+ *  A bare id we can't attribute is UNKNOWN, not a shared provider: it gets a per-id marker so two
+ *  different unknown ids never compare equal (returning "" for both made them look like one provider
+ *  and would have leaked one host's options onto the other's model). An unknown id still compares
+ *  equal to ITSELF, so a child staying on the parent's exact model keeps the parent's options. */
+declare function modelProvider(model: string): string;
 /** Short, human-friendly name for a resolved model id (e.g. "anthropic/claude-opus-4-8" → "opus"). */
 declare function modelShortLabel(model?: string): string;
 interface ResolveModelSwitchOpts {
@@ -39,4 +53,4 @@ interface ModelSwitch {
  */
 declare function resolveModelSwitch(opts: ResolveModelSwitchOpts): ModelSwitch;
 
-export { MODEL_ALIASES, type ModelSwitch, type ResolveModelSwitchOpts, modelShortLabel, resolveModelAlias, resolveModelSwitch };
+export { MODEL_ALIASES, type ModelSwitch, type ResolveModelSwitchOpts, modelProvider, modelShortLabel, resolveModelAlias, resolveModelSwitch };

package/dist/models.js

@@ -15,6 +15,12 @@ function resolveModelAlias(input) {
   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}`;
+}
 function modelShortLabel(model) {
   if (!model) return "default";
   const id = model.split("/").pop();
@@ -38,6 +44,7 @@ function resolveModelSwitch(opts) {
 }
 export {
   MODEL_ALIASES,
+  modelProvider,
   modelShortLabel,
   resolveModelAlias,
   resolveModelSwitch

package/dist/models.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/models.ts"],"sourcesContent":["/**\n * Model aliasing + mid-conversation switch resolution — pure, dependency-free.\n *\n * Harness-level so every agentx consumer (unclaw, para-chat, …) resolves `[opus]`-style\n * aliases, gates by an allow-list, and announces a switch the same way. Policy (which models\n * a caller may use) and session state (the prior model) stay with the consumer; this module\n * is the shared mechanism.\n */\n\n/** Canonical short aliases → concrete Anthropic model ids. */\nexport const MODEL_ALIASES: Record<string, string> = {\n  fable: 'claude-fable-5',\n  'fable-5': 'claude-fable-5',\n  opus: 'claude-opus-4-8',\n  'opus-4-8': 'claude-opus-4-8',\n  'opus-4-7': 'claude-opus-4-7',\n  'opus-4-6': 'claude-opus-4-6',\n  sonnet: 'claude-sonnet-4-6',\n  haiku: 'claude-haiku-4-5-20251001',\n};\n\n/** Resolve an alias to a concrete id. A provider prefix (\"anthropic/\") is preserved; unknown ids pass through. */\nexport function resolveModelAlias(input: string): string {\n  const slash = input.indexOf('/');\n  const prefix = slash === -1 ? '' : input.slice(0, slash + 1);\n  const rest = slash === -1 ? input : input.slice(slash + 1);\n  return prefix + (MODEL_ALIASES[rest.toLowerCase()] ?? rest);\n}\n\n/** Short, human-friendly name for a resolved model id (e.g. \"anthropic/claude-opus-4-8\" → \"opus\"). */\nexport function modelShortLabel(model?: string): string {\n  if (!model) return 'default';\n  const id = model.split('/').pop()!;\n  return id.replace(/^claude-/, '').replace(/-\\d.*$/, '');\n}\n\nexport interface ResolveModelSwitchOpts {\n  /** Model requested for this turn (e.g. from an inline directive). Undefined = keep `current`. */\n  requested?: string;\n  /** The turn's default/current model when nothing is requested. */\n  current: string;\n  /** The session's prior resolved model — drives change detection + the notice. */\n  prior?: string;\n  /** If set, `requested` must match one of these (by short label) or it's denied and `current` is kept. */\n  allowed?: string[];\n  /** Announcement formatter. Default: `_[switching from x to y]_\\n\\n`. */\n  format?: (from: string, to: string) => string;\n}\n\nexport interface ModelSwitch {\n  /** The model to run this turn. */\n  model: string;\n  /** True when `requested` was rejected by `allowed` and `model` fell back to `current`. */\n  denied: boolean;\n  /** Inline notice to surface when the model actually changed vs `prior`, else undefined. */\n  notice?: string;\n}\n\n/**\n * Resolve which model a turn runs, given an optional request, an allow-list, and the prior model.\n * Comparisons are by short label so provider-prefixed and dated ids unify\n * (\"anthropic/claude-opus-4-8\" ≡ \"claude-opus-4-8\" ≡ \"opus\").\n */\nexport function resolveModelSwitch(opts: ResolveModelSwitchOpts): ModelSwitch {\n  const { requested, current, prior, allowed } = opts;\n  if (!requested) return { model: current, denied: false };\n  if (allowed && !allowed.some((a) => modelShortLabel(a) === modelShortLabel(requested))) {\n    return { model: current, denied: true };\n  }\n  const fmt = opts.format ?? ((from: string, to: string) => `_[switching from ${from} to ${to}]_\\n\\n`);\n  const changed = prior !== undefined && modelShortLabel(prior) !== modelShortLabel(requested);\n  return {\n    model: requested,\n    denied: false,\n    notice: changed ? fmt(modelShortLabel(prior!), modelShortLabel(requested)) : undefined,\n  };\n}\n"],"mappings":";AAUO,IAAM,gBAAwC;AAAA,EACnD,OAAO;AAAA,EACP,WAAW;AAAA,EACX,MAAM;AAAA,EACN,YAAY;AAAA,EACZ,YAAY;AAAA,EACZ,YAAY;AAAA,EACZ,QAAQ;AAAA,EACR,OAAO;AACT;AAGO,SAAS,kBAAkB,OAAuB;AACvD,QAAM,QAAQ,MAAM,QAAQ,GAAG;AAC/B,QAAM,SAAS,UAAU,KAAK,KAAK,MAAM,MAAM,GAAG,QAAQ,CAAC;AAC3D,QAAM,OAAO,UAAU,KAAK,QAAQ,MAAM,MAAM,QAAQ,CAAC;AACzD,SAAO,UAAU,cAAc,KAAK,YAAY,CAAC,KAAK;AACxD;AAGO,SAAS,gBAAgB,OAAwB;AACtD,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,KAAK,MAAM,MAAM,GAAG,EAAE,IAAI;AAChC,SAAO,GAAG,QAAQ,YAAY,EAAE,EAAE,QAAQ,UAAU,EAAE;AACxD;AA6BO,SAAS,mBAAmB,MAA2C;AAC5E,QAAM,EAAE,WAAW,SAAS,OAAO,QAAQ,IAAI;AAC/C,MAAI,CAAC,UAAW,QAAO,EAAE,OAAO,SAAS,QAAQ,MAAM;AACvD,MAAI,WAAW,CAAC,QAAQ,KAAK,CAAC,MAAM,gBAAgB,CAAC,MAAM,gBAAgB,SAAS,CAAC,GAAG;AACtF,WAAO,EAAE,OAAO,SAAS,QAAQ,KAAK;AAAA,EACxC;AACA,QAAM,MAAM,KAAK,WAAW,CAAC,MAAc,OAAe,oBAAoB,IAAI,OAAO,EAAE;AAAA;AAAA;AAC3F,QAAM,UAAU,UAAU,UAAa,gBAAgB,KAAK,MAAM,gBAAgB,SAAS;AAC3F,SAAO;AAAA,IACL,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,QAAQ,UAAU,IAAI,gBAAgB,KAAM,GAAG,gBAAgB,SAAS,CAAC,IAAI;AAAA,EAC/E;AACF;","names":[]}
+{"version":3,"sources":["../src/models.ts"],"sourcesContent":["/**\n * Model aliasing + mid-conversation switch resolution — pure, dependency-free.\n *\n * Harness-level so every agentx consumer (unclaw, para-chat, …) resolves `[opus]`-style\n * aliases, gates by an allow-list, and announces a switch the same way. Policy (which models\n * a caller may use) and session state (the prior model) stay with the consumer; this module\n * is the shared mechanism.\n */\n\n/** Canonical short aliases → concrete Anthropic model ids. */\nexport const MODEL_ALIASES: Record<string, string> = {\n  fable: 'claude-fable-5',\n  'fable-5': 'claude-fable-5',\n  opus: 'claude-opus-4-8',\n  'opus-4-8': 'claude-opus-4-8',\n  'opus-4-7': 'claude-opus-4-7',\n  'opus-4-6': 'claude-opus-4-6',\n  sonnet: 'claude-sonnet-4-6',\n  haiku: 'claude-haiku-4-5-20251001',\n};\n\n/** Resolve an alias to a concrete id. A provider prefix (\"anthropic/\") is preserved; unknown ids pass through. */\nexport function resolveModelAlias(input: string): string {\n  const slash = input.indexOf('/');\n  const prefix = slash === -1 ? '' : input.slice(0, slash + 1);\n  const rest = slash === -1 ? input : input.slice(slash + 1);\n  return prefix + (MODEL_ALIASES[rest.toLowerCase()] ?? rest);\n}\n\n/** The provider of a model id (\"cursor/x\" -> \"cursor\"). Provider-specific `providerOptions` are only\n *  portable within the same provider — leaking them across is a hard 400.\n *\n *  A BARE id is the common case, not the exception: `resolveModelAlias('haiku')` yields\n *  `claude-haiku-4-5-20251001` with no prefix (ai.libx.js resolves it fuzzily downstream), so reading\n *  only the literal \"/\" made every aliased child look like a provider switch and silently dropped the\n *  parent's options. The fix belongs HERE — the alias table must keep emitting the ids ai.libx.js\n *  expects, and the comparison is provider identity, not string identity.\n *\n *  A bare id we can't attribute is UNKNOWN, not a shared provider: it gets a per-id marker so two\n *  different unknown ids never compare equal (returning \"\" for both made them look like one provider\n *  and would have leaked one host's options onto the other's model). An unknown id still compares\n *  equal to ITSELF, so a child staying on the parent's exact model keeps the parent's options. */\nexport function modelProvider(model: string): string {\n  const i = model.indexOf('/');\n  if (i !== -1) return model.slice(0, i);\n  if (/^claude-/i.test(model)) return 'anthropic';\n  return `?${model}`; // unknown: identity-scoped, never equal to a different unknown id\n}\n\n/** Short, human-friendly name for a resolved model id (e.g. \"anthropic/claude-opus-4-8\" → \"opus\"). */\nexport function modelShortLabel(model?: string): string {\n  if (!model) return 'default';\n  const id = model.split('/').pop()!;\n  return id.replace(/^claude-/, '').replace(/-\\d.*$/, '');\n}\n\nexport interface ResolveModelSwitchOpts {\n  /** Model requested for this turn (e.g. from an inline directive). Undefined = keep `current`. */\n  requested?: string;\n  /** The turn's default/current model when nothing is requested. */\n  current: string;\n  /** The session's prior resolved model — drives change detection + the notice. */\n  prior?: string;\n  /** If set, `requested` must match one of these (by short label) or it's denied and `current` is kept. */\n  allowed?: string[];\n  /** Announcement formatter. Default: `_[switching from x to y]_\\n\\n`. */\n  format?: (from: string, to: string) => string;\n}\n\nexport interface ModelSwitch {\n  /** The model to run this turn. */\n  model: string;\n  /** True when `requested` was rejected by `allowed` and `model` fell back to `current`. */\n  denied: boolean;\n  /** Inline notice to surface when the model actually changed vs `prior`, else undefined. */\n  notice?: string;\n}\n\n/**\n * Resolve which model a turn runs, given an optional request, an allow-list, and the prior model.\n * Comparisons are by short label so provider-prefixed and dated ids unify\n * (\"anthropic/claude-opus-4-8\" ≡ \"claude-opus-4-8\" ≡ \"opus\").\n */\nexport function resolveModelSwitch(opts: ResolveModelSwitchOpts): ModelSwitch {\n  const { requested, current, prior, allowed } = opts;\n  if (!requested) return { model: current, denied: false };\n  if (allowed && !allowed.some((a) => modelShortLabel(a) === modelShortLabel(requested))) {\n    return { model: current, denied: true };\n  }\n  const fmt = opts.format ?? ((from: string, to: string) => `_[switching from ${from} to ${to}]_\\n\\n`);\n  const changed = prior !== undefined && modelShortLabel(prior) !== modelShortLabel(requested);\n  return {\n    model: requested,\n    denied: false,\n    notice: changed ? fmt(modelShortLabel(prior!), modelShortLabel(requested)) : undefined,\n  };\n}\n"],"mappings":";AAUO,IAAM,gBAAwC;AAAA,EACnD,OAAO;AAAA,EACP,WAAW;AAAA,EACX,MAAM;AAAA,EACN,YAAY;AAAA,EACZ,YAAY;AAAA,EACZ,YAAY;AAAA,EACZ,QAAQ;AAAA,EACR,OAAO;AACT;AAGO,SAAS,kBAAkB,OAAuB;AACvD,QAAM,QAAQ,MAAM,QAAQ,GAAG;AAC/B,QAAM,SAAS,UAAU,KAAK,KAAK,MAAM,MAAM,GAAG,QAAQ,CAAC;AAC3D,QAAM,OAAO,UAAU,KAAK,QAAQ,MAAM,MAAM,QAAQ,CAAC;AACzD,SAAO,UAAU,cAAc,KAAK,YAAY,CAAC,KAAK;AACxD;AAeO,SAAS,cAAc,OAAuB;AACnD,QAAM,IAAI,MAAM,QAAQ,GAAG;AAC3B,MAAI,MAAM,GAAI,QAAO,MAAM,MAAM,GAAG,CAAC;AACrC,MAAI,YAAY,KAAK,KAAK,EAAG,QAAO;AACpC,SAAO,IAAI,KAAK;AAClB;AAGO,SAAS,gBAAgB,OAAwB;AACtD,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,KAAK,MAAM,MAAM,GAAG,EAAE,IAAI;AAChC,SAAO,GAAG,QAAQ,YAAY,EAAE,EAAE,QAAQ,UAAU,EAAE;AACxD;AA6BO,SAAS,mBAAmB,MAA2C;AAC5E,QAAM,EAAE,WAAW,SAAS,OAAO,QAAQ,IAAI;AAC/C,MAAI,CAAC,UAAW,QAAO,EAAE,OAAO,SAAS,QAAQ,MAAM;AACvD,MAAI,WAAW,CAAC,QAAQ,KAAK,CAAC,MAAM,gBAAgB,CAAC,MAAM,gBAAgB,SAAS,CAAC,GAAG;AACtF,WAAO,EAAE,OAAO,SAAS,QAAQ,KAAK;AAAA,EACxC;AACA,QAAM,MAAM,KAAK,WAAW,CAAC,MAAc,OAAe,oBAAoB,IAAI,OAAO,EAAE;AAAA;AAAA;AAC3F,QAAM,UAAU,UAAU,UAAa,gBAAgB,KAAK,MAAM,gBAAgB,SAAS;AAC3F,SAAO;AAAA,IACL,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,QAAQ,UAAU,IAAI,gBAAgB,KAAM,GAAG,gBAAgB,SAAS,CAAC,IAAI;AAAA,EAC/E;AACF;","names":[]}

package/dist/{tools-BWzPQVy0.d.ts → tools-S-ArIR3o.d.ts}

@@ -407,6 +407,15 @@ interface AgentTool {
             data: string;
         }[];
     }>;
+    /** Optional: return a copy of this tool bound to a different real-disk working directory.
+     *  Implemented by tools that escape the VFS (the real `Shell`), which are cwd-bound at construction
+     *  and would otherwise keep pointing at the PARENT's tree when the tool instance is inherited by an
+     *  isolated child agent. `subagent.ts` calls this for a worktree child; tools without it pass through.
+     *  Return `undefined` for a capability that CANNOT follow the child (the background-job companions,
+     *  bound to the parent's job registry) — the tool is then dropped from the child's toolbelt.
+     *  An implementation must carry over any post-construction mutation the host made to the instance
+     *  (a renamed `name`/`description`) — rebuilding from the factory's options alone loses it. */
+    withCwd?(cwd: string): AgentTool | undefined;
 }
 /** Build a tool context bound to a filesystem backend (Mem / Disk / …) and an optional host. */
 declare function makeContext(fs: IFilesystem, host?: HostBridge): ToolContext;
@@ -427,7 +436,10 @@ declare function defaultTools(): AgentTool[];
  * surface picks from this registry; embedders can build a custom tool set by name.
  */
 declare function toolRegistry(): Record<string, AgentTool>;
-/** Resolve a list of tool names against the registry (unknown names throw). */
-declare function toolsByName(names: string[]): AgentTool[];
+/** Resolve a list of tool names against `available` (host-supplied tools, e.g. a parent agent's
+ *  toolbelt or mounted MCP tools) first, then the built-in registry. Unknown names throw.
+ *  Without `available` an allowlist could only ever name a built-in — so a def could not scope a
+ *  child to a tool its parent injected (`Bash`, `ToolSearch`, …). */
+declare function toolsByName(names: string[], available?: AgentTool[]): AgentTool[];
 
 export { type AgentTool as A, makeJobTools as B, type ChatLike as C, messageHasImage as D, messageHasImageRef as E, messageHasInlineImage as F, mintImageRef as G, type HostBridge as H, IMAGE_ELIDE_STUB as I, parseImageRef as J, readTool as K, remintImageRefs as L, type Message as M, sendBytes as N, sendBytesPer as O, toWireTools as P, todoWriteTool as Q, type Role as R, SandboxJobRegistry as S, type TodoItem as T, type UserQuestion as U, toolImageRef as V, toolRegistry as W, toolsByName as X, type ChatOptions as a, type ChatResponse as b, type ContentPart as c, type HostEvent as d, IMAGE_REF_SCHEME as e, type ImageRef as f, type MessageContent as g, type StreamChunk as h, type Tool as i, type ToolCall as j, type ToolContext as k, bashTool as l, clearImageRefs as m, contentBytes as n, contentText as o, defaultTools as p, editTool as q, elideImages as r, elideInlineImages as s, elideStaleImages as t, exitSessionTool as u, expandImagesForSend as v, imagePart as w, imageRefPart as x, imageRefResult as y, makeContext as z };

package/dist/tools.shell.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentTool } from './tools-BWzPQVy0.js';
+import { A as AgentTool } from './tools-S-ArIR3o.js';
 import '@livx.cc/wcli/core';
 
 /**
@@ -141,12 +141,24 @@ declare class ShellJobRegistry {
         command: string;
         status: JobStatus;
     }>;
+    /**
+     * Take over an ALREADY-RUNNING child as a background job. A foreground command that outruns its
+     * timeout is not necessarily a hung command — killing it throws away work that was nearly done and,
+     * worse, a launcher that spawned its own detached worker leaves that worker running with nothing
+     * tracking it. Adopting hands the model a handle instead: the command keeps going, its completion
+     * is reported like any other job, and `seed` carries the output produced before the handoff.
+     */
+    adopt(command: string, proc: SpawnedProcess, seed?: string): string;
     kill(id: string): boolean;
     killAll(): void;
 }
 /** Build an opt-in real-shell tool bound to `options.cwd`. */
 declare function makeRealShellTool(options: RealShellOptions): AgentTool;
-/** Build the background-job companion tools (ShellOutput / ShellStatus / ShellKill) over a registry. */
+/** Build the background-job companion tools (ShellOutput / ShellStatus / ShellKill) over a registry.
+ *  Each closes over THIS registry, i.e. this agent's jobs in this agent's cwd, so none of them can be
+ *  rebound to an isolated child's root: `withCwd` returns `undefined` and they are dropped from the
+ *  child's toolbelt. That keeps the capability coherent — the child's `Shell` cannot START a background
+ *  job (its registry is dropped), so it must not be able to inspect or SIGTERM the parent's either. */
 declare function makeShellJobTools(registry: ShellJobRegistry): AgentTool[];
 
 export { type JobExitHandler, type JobExitNotice, type JobStatus, type RealShellOptions, type ShellJobConfig, ShellJobRegistry, type SpawnFn, type SpawnedProcess, formatJobExit, makeRealShellTool, makeShellJobTools };

package/dist/tools.shell.js

@@ -650,6 +650,41 @@ var ShellJobRegistry = class {
   list() {
     return [...this.jobs].map(([id, j]) => ({ id, command: j.command, status: j.status }));
   }
+  /**
+   * Take over an ALREADY-RUNNING child as a background job. A foreground command that outruns its
+   * timeout is not necessarily a hung command — killing it throws away work that was nearly done and,
+   * worse, a launcher that spawned its own detached worker leaves that worker running with nothing
+   * tracking it. Adopting hands the model a handle instead: the command keeps going, its completion
+   * is reported like any other job, and `seed` carries the output produced before the handoff.
+   */
+  adopt(command, proc, seed = "") {
+    const id = `job-${++this.seq}`;
+    const max = this.cfg.maxBuffer ?? 256 * 1024;
+    const job = { command, buf: seed.slice(-max), status: "running", proc };
+    const append = (chunk) => {
+      const s = typeof chunk === "string" ? chunk : chunk?.toString?.("utf8") ?? "";
+      job.buf = (job.buf + s).slice(-max);
+    };
+    proc.stdout?.on("data", append);
+    proc.stderr?.on("data", append);
+    proc.on("error", (err) => {
+      if (job.status === "running") {
+        job.status = "error";
+        append(`
+[error] ${err?.message ?? err}`);
+        this.notifyExit(id, job);
+      }
+    });
+    proc.on("close", (code) => {
+      if (job.status === "running") {
+        job.status = "exited";
+        job.exitCode = code ?? void 0;
+        this.notifyExit(id, job);
+      }
+    });
+    this.jobs.set(id, job);
+    return id;
+  }
   kill(id) {
     const j = this.jobs.get(id);
     if (!j) return false;
@@ -679,8 +714,26 @@ function makeRealShellTool(options) {
   };
   return {
     name: "Shell",
+    // 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();
+      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. " + (options.registry?.adopt ? `A command still running after ${defaultTimeoutMs}ms is NOT killed \u2014 it is handed to a background job and you get its id, so you can keep checking on it (\`[still running]\`). Pass \`timeoutMs\` (max ${maxTimeoutMs}) to wait longer in the foreground, and always bound network commands yourself (e.g. \`curl -m 10\`). ` : `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,
@@ -719,9 +772,12 @@ function makeRealShellTool(options) {
         else ctx.signal.addEventListener("abort", onAbort, { once: true });
       }
       let timedOut = false;
-      const timer = setTimeout(() => {
+      let onDeadline = () => {
         timedOut = true;
         ctl.abort();
+      };
+      const timer = setTimeout(() => {
+        onDeadline();
       }, timeoutMs);
       let pend = "";
       let flushTimer = null;
@@ -752,6 +808,18 @@ function makeRealShellTool(options) {
           }
           if (ctl.signal.aborted) killGroup(proc, "SIGKILL");
           else ctl.signal.addEventListener("abort", () => killGroup(proc, "SIGKILL"), { once: true });
+          const registry = options.registry;
+          if (registry?.adopt) {
+            onDeadline = () => {
+              timedOut = true;
+              if (settled) return;
+              flushEmit(ctx);
+              proc.stdout?.off?.("data", collect);
+              proc.stderr?.off?.("data", collect);
+              const id = registry.adopt(cmd, proc, out);
+              finish(handoffFor(timeoutMs, id, clean(out), !!registry.notifiesOnExit));
+            };
+          }
           const collect = (chunk) => {
             const s = typeof chunk === "string" ? chunk : chunk?.toString?.("utf8") ?? "";
             out += s;
@@ -784,6 +852,12 @@ function makeRealShellTool(options) {
     }
   };
 }
+function handoffFor(timeoutMs, id, body, notifies) {
+  const head = `[still running] exceeded ${timeoutMs}ms, so it was handed to background job ${id} \u2014 NOT killed, it is still going. Check on it with ShellOutput({id:"${id}"}) / ShellStatus({id:"${id}"}), stop it with ShellKill({id:"${id}"}). ` + (notifies ? "Its completion will be reported to you, so you may continue with other work meanwhile." : "Nothing will tell you when it finishes \u2014 poll it yourself before you rely on its result.");
+  return body ? `${head}
+Output so far:
+${body}` : head;
+}
 function reasonFor(timedOut, timeoutMs, body) {
   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}
@@ -793,8 +867,10 @@ ${body}` : head;
 var NO_JOB = (id) => `Error: no background job '${id}'. Use ShellStatus with no id to list jobs, or start one with Shell({background:true}).`;
 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" } } },
@@ -807,6 +883,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,
@@ -820,6 +897,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" } } },