zidane 5.6.3 → 5.6.7

package/dist/{presets-ZT3TJDEb.js.map → presets-BXmWG3kd.js.map}

@@ -1 +1 @@
-{"version":3,"file":"presets-ZT3TJDEb.js","names":[],"sources":["../src/presets/basic.ts","../src/presets/index.ts"],"sourcesContent":["import { definePreset } from '.'\nimport { edit, listFiles, multiEdit, readFile, shell, shellKill, writeFile } from '../tools'\nimport { createSpawnTool } from '../tools/spawn'\n\n/**\n * Core tools available in every basic preset (without spawn).\n *\n * `edit` and `multi_edit` ship in the basic set because surgical edits are the\n * default modality for production agents — `write_file` is for full overwrites.\n * `glob` and `grep` are exported but opt-in: not every agent needs codebase\n * search, and shipping them by default would force `tool:gate` work onto\n * consumers that prefer the model to use `shell` + classic Unix tools.\n */\nexport const basicTools = { shell, shellKill, readFile, writeFile, listFiles, edit, multiEdit }\n\nexport default definePreset({\n  name: 'basic',\n  system: 'You are a helpful assistant with access to shell, file reading, file writing, surgical and multi-edit tools, directory listing, and sub-agent spawning. Prefer `edit` / `multi_edit` for in-place changes and `write_file` for full file overwrites. Use them to accomplish tasks in the project directory.',\n  // `persist: true` shares the parent's session with every child agent — child\n  // turns land in `session.turns` tagged with their own `runId`, and the run\n  // itself is recorded in `session.runs` with `parentRunId` + `depth`. That's\n  // what lets a reloaded TUI session reconstruct the full subagent tree (see\n  // `eventsFromTurns` in `tui/store.ts`). Hosts that want children in-memory\n  // only can construct their own preset with `createSpawnTool()`.\n  tools: { ...basicTools, spawn: createSpawnTool({ persist: true }) },\n})\n","import type { AgentHooks, AgentOptions } from '../agent'\n\nexport type { AgentHookMap } from '../agent'\n\n/**\n * A preset is a reusable slice of `AgentOptions` — spread it into `createAgent()`\n * to configure tools, a default system prompt, aliases, behavior defaults, and\n * agent-lifetime hooks.\n *\n * `provider`, `execution`, `session`, and internal fields are excluded so presets\n * remain shareable and composable.\n *\n * ```ts\n * import { basic } from 'zidane/presets'\n * createAgent({ ...basic, provider })\n * ```\n *\n * ### Composing multiple presets\n *\n * Bare `...spread` is shallow — `{ ...a, ...b }` overwrites every key `b`\n * defines, including `hooks`. Use {@link composePresets} when you want\n * field-aware merging (per-event hook concat, tools shallow-merge, etc.):\n *\n * ```ts\n * createAgent({ ...composePresets(basic, telemetry, mine), provider })\n * ```\n */\nexport type Preset = Omit<Partial<AgentOptions>, 'provider' | 'execution' | 'session' | 'mcpConnector'>\n\n/**\n * Identity helper for type inference when defining a preset.\n */\nexport function definePreset(config: Preset): Preset {\n  return config\n}\n\n/**\n * Field-aware composition of presets. Right-most preset wins for scalar fields;\n * objects shallow-merge; arrays and hook handler lists concatenate. Designed so\n * stacking presets does the obvious thing without the spread-collision footgun:\n *\n * - `name`, `system`, `eager`, `skills`              → last-defined wins\n * - `tools`, `toolAliases`, `behavior`               → shallow-merge (later keys override)\n * - `behavior.dedupTools`, `behavior.toolBudgets`    → **deep-merge** (per-tool-name; later wins on collision)\n * - `mcpServers`                                     → concat with last-wins on `name` collision\n * - `hooks`                                          → per-event concat; every handler fires\n *\n * `hooks` always emerges as `event → handler[]` so downstream registration\n * (in `createAgent`) sees a uniform shape. Order of handlers within an event\n * follows preset order: earlier presets register first.\n *\n * `mcpServers` is deduped by `name` because shipping two servers with the same\n * name would trip the connector at runtime — a later preset overriding an\n * earlier preset's `github` server is the practical intent.\n *\n * `behavior.dedupTools` and `behavior.toolBudgets` get the same per-key deep-merge\n * because they are tool-name-keyed records — a preset that ships a dedup hasher\n * for one tool should not erase a hasher another preset ships for a different\n * tool. Last-wins still applies on a per-tool collision so a downstream preset\n * can override an upstream preset's policy for one specific tool. Other\n * `behavior` fields keep last-wins semantics.\n */\nexport function composePresets(...presets: Preset[]): Preset {\n  const out: Preset = {}\n  const hooksByEvent: { [K in keyof AgentHooks]?: AgentHooks[K][] } = {}\n  // Keep mcpServers in source-order on first sight, but allow later\n  // declarations to override earlier ones with the same `name`. A `Map`\n  // keyed by name gives O(1) override + stable iteration.\n  const mcpByName = new Map<string, NonNullable<Preset['mcpServers']>[number]>()\n\n  for (const p of presets) {\n    if (p.name !== undefined)\n      out.name = p.name\n    if (p.system !== undefined)\n      out.system = p.system\n    if (p.eager !== undefined)\n      out.eager = p.eager\n    if (p.skills !== undefined)\n      out.skills = p.skills\n    if (p.tools)\n      out.tools = { ...out.tools, ...p.tools }\n    if (p.toolAliases)\n      out.toolAliases = { ...out.toolAliases, ...p.toolAliases }\n    if (p.behavior) {\n      // Top-level shallow-merge first; then deep-merge the two tool-name-keyed\n      // sub-records so per-tool entries from earlier presets aren't clobbered.\n      const merged: NonNullable<Preset['behavior']> = { ...out.behavior, ...p.behavior }\n      if (out.behavior?.dedupTools || p.behavior.dedupTools) {\n        merged.dedupTools = { ...out.behavior?.dedupTools, ...p.behavior.dedupTools }\n      }\n      if (out.behavior?.toolBudgets || p.behavior.toolBudgets) {\n        merged.toolBudgets = { ...out.behavior?.toolBudgets, ...p.behavior.toolBudgets }\n      }\n      out.behavior = merged\n    }\n    if (p.mcpServers) {\n      for (const server of p.mcpServers)\n        mcpByName.set(server.name, server)\n    }\n    if (p.hooks) {\n      for (const [event, handler] of Object.entries(p.hooks)) {\n        if (handler === undefined)\n          continue\n        const list = Array.isArray(handler) ? handler : [handler]\n        const key = event as keyof AgentHooks\n        // Safe cast: we read the loose `AgentHookMap` shape (handler-or-array)\n        // and re-emit only as arrays. Each `list` element matches the event's\n        // handler signature by construction (the input was typed `AgentHookMap`).\n        const bucket = (hooksByEvent[key] ??= []) as unknown[]\n        bucket.push(...(list as unknown[]))\n      }\n    }\n  }\n\n  if (mcpByName.size > 0)\n    out.mcpServers = [...mcpByName.values()]\n\n  if (Object.keys(hooksByEvent).length > 0)\n    out.hooks = hooksByEvent\n\n  return out\n}\n\nexport { default as basic, basicTools } from './basic'\n"],"mappings":";;;;;;;;;;;AAaA,MAAa,aAAa;CAAE;CAAO;CAAW;CAAU;CAAW;CAAW;CAAM;CAAW;AAE/F,IAAA,gBAAe,aAAa;CAC1B,MAAM;CACN,QAAQ;CAOR,OAAO;EAAE,GAAG;EAAY,OAAO,gBAAgB,EAAE,SAAS,MAAM,CAAC;EAAE;CACpE,CAAC;;;;;;ACOF,SAAgB,aAAa,QAAwB;CACnD,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BT,SAAgB,eAAe,GAAG,SAA2B;CAC3D,MAAM,MAAc,EAAE;CACtB,MAAM,eAA8D,EAAE;CAItE,MAAM,4BAAY,IAAI,KAAwD;CAE9E,KAAK,MAAM,KAAK,SAAS;EACvB,IAAI,EAAE,SAAS,KAAA,GACb,IAAI,OAAO,EAAE;EACf,IAAI,EAAE,WAAW,KAAA,GACf,IAAI,SAAS,EAAE;EACjB,IAAI,EAAE,UAAU,KAAA,GACd,IAAI,QAAQ,EAAE;EAChB,IAAI,EAAE,WAAW,KAAA,GACf,IAAI,SAAS,EAAE;EACjB,IAAI,EAAE,OACJ,IAAI,QAAQ;GAAE,GAAG,IAAI;GAAO,GAAG,EAAE;GAAO;EAC1C,IAAI,EAAE,aACJ,IAAI,cAAc;GAAE,GAAG,IAAI;GAAa,GAAG,EAAE;GAAa;EAC5D,IAAI,EAAE,UAAU;GAGd,MAAM,SAA0C;IAAE,GAAG,IAAI;IAAU,GAAG,EAAE;IAAU;GAClF,IAAI,IAAI,UAAU,cAAc,EAAE,SAAS,YACzC,OAAO,aAAa;IAAE,GAAG,IAAI,UAAU;IAAY,GAAG,EAAE,SAAS;IAAY;GAE/E,IAAI,IAAI,UAAU,eAAe,EAAE,SAAS,aAC1C,OAAO,cAAc;IAAE,GAAG,IAAI,UAAU;IAAa,GAAG,EAAE,SAAS;IAAa;GAElF,IAAI,WAAW;;EAEjB,IAAI,EAAE,YACJ,KAAK,MAAM,UAAU,EAAE,YACrB,UAAU,IAAI,OAAO,MAAM,OAAO;EAEtC,IAAI,EAAE,OACJ,KAAK,MAAM,CAAC,OAAO,YAAY,OAAO,QAAQ,EAAE,MAAM,EAAE;GACtD,IAAI,YAAY,KAAA,GACd;GACF,MAAM,OAAO,MAAM,QAAQ,QAAQ,GAAG,UAAU,CAAC,QAAQ;GACzD,MAAM,MAAM;GAKZ,CADgB,aAAa,SAAS,EAAE,EACjC,KAAK,GAAI,KAAmB;;;CAKzC,IAAI,UAAU,OAAO,GACnB,IAAI,aAAa,CAAC,GAAG,UAAU,QAAQ,CAAC;CAE1C,IAAI,OAAO,KAAK,aAAa,CAAC,SAAS,GACrC,IAAI,QAAQ;CAEd,OAAO"}
+{"version":3,"file":"presets-BXmWG3kd.js","names":[],"sources":["../src/presets/basic.ts","../src/presets/index.ts"],"sourcesContent":["import { definePreset } from '.'\nimport { edit, listFiles, multiEdit, readFile, shell, shellKill, writeFile } from '../tools'\nimport { createSpawnTool } from '../tools/spawn'\n\n/**\n * Core tools available in every basic preset (without spawn).\n *\n * `edit` and `multi_edit` ship in the basic set because surgical edits are the\n * default modality for production agents — `write_file` is for full overwrites.\n * `glob` and `grep` are exported but opt-in: not every agent needs codebase\n * search, and shipping them by default would force `tool:gate` work onto\n * consumers that prefer the model to use `shell` + classic Unix tools.\n */\nexport const basicTools = { shell, shellKill, readFile, writeFile, listFiles, edit, multiEdit }\n\nexport default definePreset({\n  name: 'basic',\n  system: 'You are a helpful assistant with access to shell, file reading, file writing, surgical and multi-edit tools, directory listing, and sub-agent spawning. Prefer `edit` / `multi_edit` for in-place changes and `write_file` for full file overwrites. Use them to accomplish tasks in the project directory.',\n  // `persist: true` shares the parent's session with every child agent — child\n  // turns land in `session.turns` tagged with their own `runId`, and the run\n  // itself is recorded in `session.runs` with `parentRunId` + `depth`. That's\n  // what lets a reloaded TUI session reconstruct the full subagent tree (see\n  // `eventsFromTurns` in `tui/store.ts`). Hosts that want children in-memory\n  // only can construct their own preset with `createSpawnTool()`.\n  tools: { ...basicTools, spawn: createSpawnTool({ persist: true }) },\n})\n","import type { AgentHooks, AgentOptions } from '../agent'\n\nexport type { AgentHookMap } from '../agent'\n\n/**\n * A preset is a reusable slice of `AgentOptions` — spread it into `createAgent()`\n * to configure tools, a default system prompt, aliases, behavior defaults, and\n * agent-lifetime hooks.\n *\n * `provider`, `execution`, `session`, and internal fields are excluded so presets\n * remain shareable and composable.\n *\n * ```ts\n * import { basic } from 'zidane/presets'\n * createAgent({ ...basic, provider })\n * ```\n *\n * ### Composing multiple presets\n *\n * Bare `...spread` is shallow — `{ ...a, ...b }` overwrites every key `b`\n * defines, including `hooks`. Use {@link composePresets} when you want\n * field-aware merging (per-event hook concat, tools shallow-merge, etc.):\n *\n * ```ts\n * createAgent({ ...composePresets(basic, telemetry, mine), provider })\n * ```\n */\nexport type Preset = Omit<Partial<AgentOptions>, 'provider' | 'execution' | 'session' | 'mcpConnector'>\n\n/**\n * Identity helper for type inference when defining a preset.\n */\nexport function definePreset(config: Preset): Preset {\n  return config\n}\n\n/**\n * Field-aware composition of presets. Right-most preset wins for scalar fields;\n * objects shallow-merge; arrays and hook handler lists concatenate. Designed so\n * stacking presets does the obvious thing without the spread-collision footgun:\n *\n * - `name`, `system`, `eager`, `skills`              → last-defined wins\n * - `tools`, `toolAliases`, `behavior`               → shallow-merge (later keys override)\n * - `behavior.dedupTools`, `behavior.toolBudgets`    → **deep-merge** (per-tool-name; later wins on collision)\n * - `mcpServers`                                     → concat with last-wins on `name` collision\n * - `hooks`                                          → per-event concat; every handler fires\n *\n * `hooks` always emerges as `event → handler[]` so downstream registration\n * (in `createAgent`) sees a uniform shape. Order of handlers within an event\n * follows preset order: earlier presets register first.\n *\n * `mcpServers` is deduped by `name` because shipping two servers with the same\n * name would trip the connector at runtime — a later preset overriding an\n * earlier preset's `github` server is the practical intent.\n *\n * `behavior.dedupTools` and `behavior.toolBudgets` get the same per-key deep-merge\n * because they are tool-name-keyed records — a preset that ships a dedup hasher\n * for one tool should not erase a hasher another preset ships for a different\n * tool. Last-wins still applies on a per-tool collision so a downstream preset\n * can override an upstream preset's policy for one specific tool. Other\n * `behavior` fields keep last-wins semantics.\n */\nexport function composePresets(...presets: Preset[]): Preset {\n  const out: Preset = {}\n  const hooksByEvent: { [K in keyof AgentHooks]?: AgentHooks[K][] } = {}\n  // Keep mcpServers in source-order on first sight, but allow later\n  // declarations to override earlier ones with the same `name`. A `Map`\n  // keyed by name gives O(1) override + stable iteration.\n  const mcpByName = new Map<string, NonNullable<Preset['mcpServers']>[number]>()\n\n  for (const p of presets) {\n    if (p.name !== undefined)\n      out.name = p.name\n    if (p.system !== undefined)\n      out.system = p.system\n    if (p.eager !== undefined)\n      out.eager = p.eager\n    if (p.skills !== undefined)\n      out.skills = p.skills\n    if (p.tools)\n      out.tools = { ...out.tools, ...p.tools }\n    if (p.toolAliases)\n      out.toolAliases = { ...out.toolAliases, ...p.toolAliases }\n    if (p.behavior) {\n      // Top-level shallow-merge first; then deep-merge the two tool-name-keyed\n      // sub-records so per-tool entries from earlier presets aren't clobbered.\n      const merged: NonNullable<Preset['behavior']> = { ...out.behavior, ...p.behavior }\n      if (out.behavior?.dedupTools || p.behavior.dedupTools) {\n        merged.dedupTools = { ...out.behavior?.dedupTools, ...p.behavior.dedupTools }\n      }\n      if (out.behavior?.toolBudgets || p.behavior.toolBudgets) {\n        merged.toolBudgets = { ...out.behavior?.toolBudgets, ...p.behavior.toolBudgets }\n      }\n      out.behavior = merged\n    }\n    if (p.mcpServers) {\n      for (const server of p.mcpServers)\n        mcpByName.set(server.name, server)\n    }\n    if (p.hooks) {\n      for (const [event, handler] of Object.entries(p.hooks)) {\n        if (handler === undefined)\n          continue\n        const list = Array.isArray(handler) ? handler : [handler]\n        const key = event as keyof AgentHooks\n        // Safe cast: we read the loose `AgentHookMap` shape (handler-or-array)\n        // and re-emit only as arrays. Each `list` element matches the event's\n        // handler signature by construction (the input was typed `AgentHookMap`).\n        const bucket = (hooksByEvent[key] ??= []) as unknown[]\n        bucket.push(...(list as unknown[]))\n      }\n    }\n  }\n\n  if (mcpByName.size > 0)\n    out.mcpServers = [...mcpByName.values()]\n\n  if (Object.keys(hooksByEvent).length > 0)\n    out.hooks = hooksByEvent\n\n  return out\n}\n\nexport { default as basic, basicTools } from './basic'\n"],"mappings":";;;;;;;;;;;AAaA,MAAa,aAAa;CAAE;CAAO;CAAW;CAAU;CAAW;CAAW;CAAM;CAAW;AAE/F,IAAA,gBAAe,aAAa;CAC1B,MAAM;CACN,QAAQ;CAOR,OAAO;EAAE,GAAG;EAAY,OAAO,gBAAgB,EAAE,SAAS,MAAM,CAAC;EAAE;CACpE,CAAC;;;;;;ACOF,SAAgB,aAAa,QAAwB;CACnD,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BT,SAAgB,eAAe,GAAG,SAA2B;CAC3D,MAAM,MAAc,EAAE;CACtB,MAAM,eAA8D,EAAE;CAItE,MAAM,4BAAY,IAAI,KAAwD;CAE9E,KAAK,MAAM,KAAK,SAAS;EACvB,IAAI,EAAE,SAAS,KAAA,GACb,IAAI,OAAO,EAAE;EACf,IAAI,EAAE,WAAW,KAAA,GACf,IAAI,SAAS,EAAE;EACjB,IAAI,EAAE,UAAU,KAAA,GACd,IAAI,QAAQ,EAAE;EAChB,IAAI,EAAE,WAAW,KAAA,GACf,IAAI,SAAS,EAAE;EACjB,IAAI,EAAE,OACJ,IAAI,QAAQ;GAAE,GAAG,IAAI;GAAO,GAAG,EAAE;GAAO;EAC1C,IAAI,EAAE,aACJ,IAAI,cAAc;GAAE,GAAG,IAAI;GAAa,GAAG,EAAE;GAAa;EAC5D,IAAI,EAAE,UAAU;GAGd,MAAM,SAA0C;IAAE,GAAG,IAAI;IAAU,GAAG,EAAE;IAAU;GAClF,IAAI,IAAI,UAAU,cAAc,EAAE,SAAS,YACzC,OAAO,aAAa;IAAE,GAAG,IAAI,UAAU;IAAY,GAAG,EAAE,SAAS;IAAY;GAE/E,IAAI,IAAI,UAAU,eAAe,EAAE,SAAS,aAC1C,OAAO,cAAc;IAAE,GAAG,IAAI,UAAU;IAAa,GAAG,EAAE,SAAS;IAAa;GAElF,IAAI,WAAW;;EAEjB,IAAI,EAAE,YACJ,KAAK,MAAM,UAAU,EAAE,YACrB,UAAU,IAAI,OAAO,MAAM,OAAO;EAEtC,IAAI,EAAE,OACJ,KAAK,MAAM,CAAC,OAAO,YAAY,OAAO,QAAQ,EAAE,MAAM,EAAE;GACtD,IAAI,YAAY,KAAA,GACd;GACF,MAAM,OAAO,MAAM,QAAQ,QAAQ,GAAG,UAAU,CAAC,QAAQ;GACzD,MAAM,MAAM;GAKZ,CADgB,aAAa,SAAS,EAAE,EACjC,KAAK,GAAI,KAAmB;;;CAKzC,IAAI,UAAU,OAAO,GACnB,IAAI,aAAa,CAAC,GAAG,UAAU,QAAQ,CAAC;CAE1C,IAAI,OAAO,KAAK,aAAa,CAAC,SAAS,GACrC,IAAI,QAAQ;CAEd,OAAO"}

package/dist/presets.d.ts

@@ -1,3 +1,3 @@
 import { n as AgentHookMap } from "./agent-D70rr6Uk.js";
-import { a as basicTools, i as _default, n as composePresets, r as definePreset, t as Preset } from "./index-DKpXHp1c.js";
+import { a as basicTools, i as _default, n as composePresets, r as definePreset, t as Preset } from "./index-8mn3PIaa.js";
 export { AgentHookMap, Preset, _default as basic, basicTools, composePresets, definePreset };

package/dist/presets.js

@@ -1,2 +1,2 @@
-import { i as basic_default, n as definePreset, r as basicTools, t as composePresets } from "./presets-ZT3TJDEb.js";
+import { i as basic_default, n as definePreset, r as basicTools, t as composePresets } from "./presets-BXmWG3kd.js";
 export { basic_default as basic, basicTools, composePresets, definePreset };

package/dist/{tools-Bgx8OBqK.js → tools-FerA0zSl.js}

@@ -2771,16 +2771,72 @@ function isReadOnlyShellCommand(command) {
 	return false;
 }
 /**
-* Build the `shell` tool's description text. The background-mode
-* paragraphs are appended only when `allowBackground` is true so the
-* model isn't pointed at a feature the agent has disabled.
+* Canonical sibling tools that, when registered alongside `shell`, are worth
+* nudging the model toward — re-running `ls`/`cat` to "verify" a path the
+* model already inspected through a dedicated tool is a measurable Kimi/Sonnet
+* failure mode. Each entry maps the canonical tool name to the line rendered
+* in the description; the rendered tool name itself is alias-resolved at
+* render time so deployments that wire-rename (e.g. `read_file` → `Read`)
+* still point at a name the model recognizes from the tool spec.
 */
-function buildShellDescription({ allowBackground }) {
+const SHELL_SWAP_HINTS = [
+	{
+		canonical: "read_file",
+		label: "Read files",
+		instead: "cat/head/tail"
+	},
+	{
+		canonical: "glob",
+		label: "File search",
+		instead: "find/ls"
+	},
+	{
+		canonical: "grep",
+		label: "Content search",
+		instead: "grep/rg"
+	},
+	{
+		canonical: "list_files",
+		label: "Directory listings",
+		instead: "ls"
+	},
+	{
+		canonical: "edit",
+		label: "Edit files",
+		instead: "sed/awk"
+	},
+	{
+		canonical: "write_file",
+		label: "Write files",
+		instead: "echo>/heredoc"
+	}
+];
+/**
+* Build the `shell` tool's description text.
+*
+* - The background-mode paragraphs are appended only when `allowBackground`
+*   is true so the model isn't pointed at a feature the agent has disabled.
+* - The "prefer the dedicated tool" swap block is appended only for siblings
+*   actually present in `registeredCanonicals`. Hosts that ship `shell`
+*   without `read_file`/`glob`/etc. don't see misleading nudges. Aliased
+*   names are rendered via `toolAliases` so the printed name matches what
+*   the model sees in the tool spec.
+*/
+function buildShellDescription({ allowBackground, registeredCanonicals, toolAliases }) {
 	const lines = [
 		"Execute a shell command in the project root and return its combined stdout/stderr.",
 		"Output is tail-priority truncated at 32 KiB by default; errors and exit-code summaries live in the tail.",
 		"By default each call appends a `(exit N, Nms)` footer and surfaces non-empty stderr in a separate section even on success — set `metadata: false` to return only stdout. Set maxOutputBytes=0 to disable truncation."
 	];
+	if (registeredCanonicals && registeredCanonicals.size > 0) {
+		const swaps = [];
+		for (const { canonical, label, instead } of SHELL_SWAP_HINTS) {
+			if (!registeredCanonicals.has(canonical)) continue;
+			const wireName = toolAliases?.[canonical] ?? canonical;
+			swaps.push(`- ${label}: use \`${wireName}\` (not ${instead})`);
+		}
+		if (swaps.length > 0) lines.push("", "When a dedicated tool fits, prefer it over shell:", ...swaps, "", "Re-running `ls`/`cat` on the same path is not useful — the prior result is still current unless you wrote to that path since.");
+	}
 	if (allowBackground) lines.push("", "Long-running commands (`npm run dev`, `python train.py`, anything that would otherwise block your turn for minutes) → `run_in_background: true`. The call returns immediately with `{ task_id, output_path, pid }`; stdout + stderr stream to the log file at `output_path`.", "", "After spawning a background task: end your current turn (do NOT keep iterating). A `<task-notification>` arrives on the agent's NEXT user-turn with the final status. Polling the log file in a loop wastes tokens and blocks your turn — the notification IS the wake-up. If you NEED to check progress immediately (rare), call `read_file({ path: output_path, ... })` exactly once and decide. To terminate, use `shell_kill({ task_id })`.", "", "When called from inside a `spawn`'d subagent: you have NO next user-turn — your `agent.run` ends as soon as you finish responding. Start the background task, return a brief summary including the `task_id`, and end your turn. Ownership of the task is transferred to the parent agent when your run finishes; the parent will see the notification on ITS next user-turn.");
 	return lines.join("\n");
 }
@@ -2837,11 +2893,16 @@ function buildShellInputSchema({ allowBackground }) {
 */
 function createShellTool(opts = {}) {
 	const allowBackground = opts.allowBackground !== false;
+	const { registeredCanonicals, toolAliases } = opts;
 	return {
 		isConcurrencySafe: (input) => isReadOnlyShellCommand(input.command),
 		spec: {
 			name: "shell",
-			description: buildShellDescription({ allowBackground }),
+			description: buildShellDescription({
+				allowBackground,
+				registeredCanonicals,
+				toolAliases
+			}),
 			inputSchema: buildShellInputSchema({ allowBackground })
 		},
 		async execute({ command, timeout, maxOutputBytes, metadata, run_in_background }, ctx) {
@@ -3971,9 +4032,11 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 			} : runBaseTools;
 			const toolsPreSearch = {};
 			for (const tool of Object.values(mergedWithSkills)) toolsPreSearch[tool.spec.name] = tool;
-			if (toolsPreSearch.shell === shell) {
-				if (!(typeof resolvedBehavior?.tasksDir === "string" && resolvedBehavior.tasksDir.length > 0 && resolvedBehavior.disableBackgroundTasks !== true)) toolsPreSearch.shell = createShellTool({ allowBackground: false });
-			}
+			if (toolsPreSearch.shell === shell) toolsPreSearch.shell = createShellTool({
+				allowBackground: typeof resolvedBehavior?.tasksDir === "string" && resolvedBehavior.tasksDir.length > 0 && resolvedBehavior.disableBackgroundTasks !== true,
+				registeredCanonicals: new Set(Object.keys(toolsPreSearch)),
+				...toolAliases ? { toolAliases } : {}
+			});
 			const disclosure = partitionToolDisclosure(toolsPreSearch, mcpToolNames, mcpServers, toolDisclosure, toolAliases);
 			const unlocked = new Set(disclosure.eagerCanonicalNames);
 			const hostDefinedToolSearch = !!toolsPreSearch.tool_search;
@@ -6055,4 +6118,4 @@ const writeFile$1 = {
 //#endregion
 export { resolvePersistDir as A, formatTaskStatus as B, TOOL_USE_SKIPPED_MESSAGE as C, buildPersistedStub as D, PERSISTENCE_PREVIEW_BYTES as E, resolveReadStateMap as F, previewLine as H, ageString as I, compactPath as L, getReadState as M, hashContent as N, cleanupPersistedSession as O, readStateKey as P, fmtTokens as R, TOOL_USE_CANCELLED_MESSAGE as S, PERSISTED_STUB_PREFIX as T, shortId as U, formatTaskSummary as V, createSkillsReadTool as _, multiEdit as a, INTERRUPT_MESSAGE_FOR_TOOL_USE as b, grep as c, resolveOldString as d, styleReplacementForVia as f, createSkillsRunScriptTool as g, createSkillsUseTool as h, readFile$1 as i, resolveTasksDir as j, maybePersistToolResult as k, glob as l, createToolSearchTool as m, createSpawnTool as n, listFiles as o, createAgent as p, shellKill as r, createInteractionTool as s, writeFile$1 as t, edit as u, createShellTool as v, validateToolArgs as w, SHELL_CASCADE_CANCEL_MESSAGE as x, shell as y, formatDuration as z };
 
-//# sourceMappingURL=tools-Bgx8OBqK.js.map
+//# sourceMappingURL=tools-FerA0zSl.js.map