zidane 5.4.2 → 5.5.0

package/dist/{tools-BNfyY14s.js → tools-D_icxa-V.js}

@@ -1,13 +1,14 @@
-import { n as createProcessContext } from "./contexts-BwiHIr2w.js";
-import { a as AgentToolPairingError, l as toTypedError, r as AgentProviderError, s as errorMessage, t as AgentAbortedError } from "./errors-Byb0F8B9.js";
+import { n as createProcessContext } from "./contexts-DhmMlT2W.js";
+import { a as AgentToolPairingError, l as toTypedError, r as AgentProviderError, s as errorMessage, t as AgentAbortedError } from "./errors-CDwtPIMX.js";
 import { t as toolOutputByteLength } from "./types-IcokUOyC.js";
-import { a as detectTurnInterruption, n as SYNTHETIC_TOOL_RESULT_PLACEHOLDER, o as ensureToolResultPairing, s as filterUnresolvedToolUses } from "./messages-D0xT979U.js";
-import { t as connectMcpServers } from "./mcp-DhmmJfxK.js";
-import { _ as validateResourcePath, b as createSkillActivationState, d as escapeXml, n as resolveSkills, p as installAllowedToolsGate, t as interpolateShellCommands, u as buildCatalog } from "./interpolate-ERgZUxgg.js";
+import { a as detectTurnInterruption, n as SYNTHETIC_TOOL_RESULT_PLACEHOLDER, o as ensureToolResultPairing, s as filterUnresolvedToolUses } from "./messages-fTR19Ga6.js";
+import { t as connectMcpServers } from "./mcp-CNUbvbsy.js";
+import { _ as validateResourcePath, b as createSkillActivationState, d as escapeXml, n as resolveSkills, p as installAllowedToolsGate, t as interpolateShellCommands, u as buildCatalog } from "./interpolate-BaaKaKzN.js";
 import { n as formatTokenUsage, t as flattenTurns } from "./stats-DgOvY7wd.js";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { createHooks } from "hookable";
+import { homedir } from "node:os";
 import { mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { dirname, isAbsolute, join, resolve } from "node:path";
 import { Buffer } from "node:buffer";
 //#region src/aliasing.ts
 /**
@@ -103,6 +104,128 @@ function rewriteMessagesToWire(messages, maps) {
 	}));
 }
 //#endregion
+//#region src/chat/format.ts
+/** Compact token formatter — 12_415 → "12.4k", 1_234_567 → "1.23M". */
+function fmtTokens(n) {
+	if (n < 1e3) return String(n);
+	if (n < 1e6) return `${(n / 1e3).toFixed(n < 1e4 ? 2 : 1)}k`;
+	return `${(n / 1e6).toFixed(2)}M`;
+}
+/** Compact relative-time formatter — "just now / 5m / 3h / 2d". */
+function ageString(ts, now = Date.now()) {
+	const m = Math.floor((now - ts) / 6e4);
+	if (m < 1) return "just now";
+	if (m < 60) return `${m}m ago`;
+	const h = Math.floor(m / 60);
+	if (h < 24) return `${h}h ago`;
+	return `${Math.floor(h / 24)}d ago`;
+}
+/** Six-char short form of a session id for headers and lists. */
+function shortId(id) {
+	return id.replace(/-/g, "").slice(0, 6);
+}
+/**
+* Single-line preview of a multi-line string, capped at `max` chars and
+* ellipsis-terminated when truncated.
+*
+* Whitespace runs (newlines, tabs, multiple spaces) collapse into one
+* space so the rendered output stays on a single visual row no matter
+* how the input was shaped. Used by every transcript "preview" surface
+* (spawn-start task, `tool: shell (background): <command>`,
+* `<task-notification>` summary line, etc.) — without the whitespace
+* collapse, a 60-char `slice` on a string with an inline `\n\n` paints
+* the second paragraph below the first, producing the visible
+* "preview text spills onto multiple lines" bug (and, downstream,
+* misaligned spawn markers when the wrapped lines collide with
+* other events).
+*
+* Reserves one slot for the `…` so the displayed width is exactly
+* `max` when truncation kicks in.
+*/
+function previewLine(s, max) {
+	const single = s.replace(/\s+/g, " ").trim();
+	if (single.length <= max) return single;
+	return `${single.slice(0, max - 1)}…`;
+}
+/**
+* Compact human-readable duration formatter shared by background-task
+* surfaces (the `<task-notification>` summary, the TUI banner, the
+* `shell_kill` tool result, etc.).
+*
+* Format ladder:
+*   - `< 1s`   →  `"Nms"`
+*   - `< 10s`  →  `"N.Ns"` (one decimal)
+*   - `< 1m`   →  `"Ns"`   (whole seconds)
+*   - `< 1h`   →  `"NmNs"` / `"Nm"` when seconds round to 0
+*   - `≥ 1h`   →  `"NhNm"` / `"Nh"` when minutes round to 0
+*
+* Single source of truth so a 60s task renders the same across the
+* model-facing XML summary and the user-facing banner. Earlier
+* separate formatters disagreed (XML said `"60.0s"`, banner said `"1m"`)
+* which was confusing to the user reading both side by side.
+*/
+function formatDuration(ms) {
+	if (ms < 0) ms = 0;
+	if (ms < 1e3) return `${ms}ms`;
+	if (ms < 6e4) return `${(ms / 1e3).toFixed(ms < 1e4 ? 1 : 0)}s`;
+	const minutes = Math.floor(ms / 6e4);
+	const seconds = Math.floor(ms % 6e4 / 1e3);
+	if (minutes < 60) return seconds > 0 ? `${minutes}m${seconds}s` : `${minutes}m`;
+	const hours = Math.floor(minutes / 60);
+	const remMinutes = minutes % 60;
+	return remMinutes > 0 ? `${hours}h${remMinutes}m` : `${hours}h`;
+}
+/**
+* Status label for a terminated background task — `"exited <code>"`
+* for natural exits, `"killed"` (with the signal name when known)
+* for our-issued SIGTERMs.
+*
+* Pulled out as its own function so the `<task-notification>` XML
+* summary, the TUI banner header, the `shell_kill` tool result, and
+* future surfaces all read the same string.
+*/
+function formatTaskStatus(info) {
+	return info.status === "killed" ? `killed${info.signal ? ` (${info.signal})` : ""}` : `exited ${info.exitCode}`;
+}
+/**
+* One-line summary of a terminated background task — the shape used by
+* the `<task-notification>` XML's `<summary>` tag AND the TUI banner's
+* `event.text` fallback string. Three dot-separated segments:
+*
+*   `<command preview · status · duration>`
+*
+* Centralizes the format so live + replay + wire all agree, and so a
+* future cosmetic tweak (separator glyph, segment ordering) lands in
+* exactly one place.
+*/
+function formatTaskSummary(info, maxCommandChars = 80) {
+	return `${previewLine(info.command, maxCommandChars)} · ${formatTaskStatus(info)} · ${formatDuration(info.durationMs)}`;
+}
+/**
+* Compact an absolute path for display: replace the user's `$HOME`
+* prefix with `~` (so `/Users/yael/Code/zidane` → `~/Code/zidane`),
+* and optionally left-truncate with an ellipsis when the result
+* still exceeds `maxWidth` (so the path's *tail* — the part the user
+* recognizes — stays visible: `…/zidane` rather than `/Users/yaeluil…`).
+*
+* `maxWidth` is the maximum *display width* in cells. Omit to skip
+* truncation. Paths outside `$HOME` are returned verbatim modulo
+* truncation. The ellipsis (`…`) counts as one cell.
+*
+* `home` overrides `os.homedir()` for tests; production callers leave
+* it undefined and pay the cheap one-syscall lookup per call.
+*/
+function compactPath(path, maxWidth, home) {
+	const h = home ?? homedir();
+	let display = path;
+	if (h) {
+		if (path === h) display = "~";
+		else if (path.startsWith(`${h}/`)) display = `~${path.slice(h.length)}`;
+	}
+	if (maxWidth !== void 0 && maxWidth > 1 && display.length > maxWidth) return `…${display.slice(display.length - maxWidth + 1)}`;
+	return display;
+}
+//#endregion
 //#region src/tools/read-state.ts
 const STATE = /* @__PURE__ */ new WeakMap();
 /**
@@ -293,6 +416,20 @@ function resolvePersistDir(opts) {
 	return join(opts.userDir, "tool-results", opts.sessionId);
 }
 /**
+* Resolve the per-session background-tasks directory under
+* `<userDir>/<sessionId>/tasks/`.
+*
+* The chat layer calls this at session activation and forwards the result
+* via `behavior.tasksDir`. Same shape as {@link resolvePersistDir}: hosts
+* get a single source of truth for "where do task log files live".
+* Created on first write; cleanup is the session-delete path's job.
+*/
+function resolveTasksDir(opts) {
+	if (!isAbsolute(opts.userDir)) throw new Error(`resolveTasksDir: userDir must be absolute, got "${opts.userDir}"`);
+	if (!opts.sessionId) throw new Error("resolveTasksDir: sessionId must be a non-empty string");
+	return join(opts.userDir, opts.sessionId, "tasks");
+}
+/**
 * Decide-and-persist for a single tool result. Pure decision + filesystem
 * side-effect; returns the new wire-level `output` string when substitution
 * happened, otherwise tells the caller to leave the result alone.
@@ -812,6 +949,27 @@ const INTERRUPT_MESSAGE_FOR_TOOL_USE = "[Request interrupted by user for tool us
 */
 const TOOL_USE_SKIPPED_MESSAGE = "[Tool use skipped — superseded by user message]";
 /**
+* Canonical tool_result text emitted when a single tool call is cancelled
+* mid-flight via `agent.cancelTool(callId)` (typically the TUI's
+* "cancel this tool" affordance). Distinguished from
+* {@link INTERRUPT_MESSAGE_FOR_TOOL_USE} (run-wide user abort) and
+* {@link TOOL_USE_SKIPPED_MESSAGE} (steered) so the model — and downstream
+* consumers — can tell the three apart by string match.
+*
+* Always paired with `isError: true` on the wire so the model treats the
+* call as failed rather than as a successful response. The remaining tool
+* calls in the batch continue running, in contrast with a full-run abort.
+*/
+const TOOL_USE_CANCELLED_MESSAGE = "[Tool call cancelled by user]";
+/**
+* Sentinel message rejected from the per-call cancellation promise inside
+* {@link executeSingleTool}'s race. Plain-string and module-private — only
+* the surrounding code reads it (via the `perCallAbort.signal.aborted`
+* guard, NOT the message itself), so it just needs to be a stable
+* non-empty identifier the rejection can carry.
+*/
+const CANCELLED_BY_USER_SENTINEL = "zidane:tool:cancelled-by-user";
+/**
 * Compute the effective thinking budget for a given run-relative turn, given
 * the configured decay schedule. Pure helper — exported for tests and so
 * downstream tooling can preview decay curves without spinning up the loop.
@@ -1670,6 +1828,29 @@ async function executeSingleTool(ctx, call, turnId) {
 	const callId = call.id;
 	const displayName = toWireName(call.name, ctx.aliasMaps);
 	const runToolCounts = Object.freeze({ ...ctx.runToolCounts });
+	const perCallAbort = new AbortController();
+	ctx.pendingToolCancels?.set(callId, perCallAbort);
+	try {
+		return await runSingleToolDispatch(ctx, call, turnId, {
+			toolDef,
+			callId,
+			displayName,
+			runToolCounts,
+			perCallAbort
+		});
+	} finally {
+		ctx.pendingToolCancels?.delete(callId);
+	}
+}
+/**
+* Body of {@link executeSingleTool}. Hoisted into its own function purely so
+* the per-call cancel registration (which spans every exit path) can sit in
+* a tight `try / finally` at the call site. Behavior is unchanged from the
+* pre-cancel implementation aside from the user-cancel branch in the
+* execute body — see {@link TOOL_USE_CANCELLED_MESSAGE}.
+*/
+async function runSingleToolDispatch(ctx, call, turnId, fixed) {
+	const { toolDef, callId, displayName, runToolCounts, perCallAbort } = fixed;
 	const gateCtx = {
 		...buildToolHookBase(ctx, turnId, callId, call.name, displayName, call.input),
 		block: false,
@@ -1795,12 +1976,14 @@ async function executeSingleTool(ctx, call, turnId) {
 		runToolCounts,
 		...coercions ? { coercions } : {}
 	});
-	let output;
+	let output = "";
 	let isError = false;
+	let cancelledByUser = false;
+	const childSignal = typeof AbortSignal.any === "function" ? AbortSignal.any([ctx.signal, perCallAbort.signal]) : ctx.signal;
 	try {
 		const toolCtx = {
 			provider: ctx.provider,
-			signal: ctx.signal,
+			signal: childSignal,
 			execution: ctx.execution,
 			handle: ctx.handle,
 			hooks: ctx.hooks,
@@ -1819,16 +2002,50 @@ async function executeSingleTool(ctx, call, turnId) {
 			...ctx.readState ? { readState: ctx.readState } : {},
 			...typeof ctx.depth === "number" ? { depth: ctx.depth } : {}
 		};
-		output = await toolDef.execute(effectiveInput, toolCtx);
+		const bodyPromise = toolDef.execute(effectiveInput, toolCtx);
+		bodyPromise.catch(() => {});
+		let removeAbortListener;
+		const cancellationPromise = new Promise((_, reject) => {
+			if (perCallAbort.signal.aborted) {
+				reject(new Error(CANCELLED_BY_USER_SENTINEL));
+				return;
+			}
+			const onAbort = () => reject(new Error(CANCELLED_BY_USER_SENTINEL));
+			perCallAbort.signal.addEventListener("abort", onAbort, { once: true });
+			removeAbortListener = () => perCallAbort.signal.removeEventListener("abort", onAbort);
+		});
+		try {
+			output = await Promise.race([bodyPromise, cancellationPromise]);
+		} finally {
+			removeAbortListener?.();
+		}
 	} catch (err) {
-		const error = err instanceof Error ? err : new Error(String(err));
-		const errorCtx = {
+		const isOurSentinel = err instanceof Error && err.message === CANCELLED_BY_USER_SENTINEL;
+		const isAbortError = err instanceof Error && err.name === "AbortError";
+		if (isOurSentinel || isAbortError && perCallAbort.signal.aborted) cancelledByUser = true;
+		else {
+			const error = err instanceof Error ? err : new Error(String(err));
+			const errorCtx = {
+				...buildToolHookBase(ctx, turnId, callId, call.name, displayName, effectiveInput),
+				error
+			};
+			await ctx.hooks.callHook("tool:error", errorCtx);
+			output = errorCtx.result ?? `Tool error: ${error.message}`;
+			isError = true;
+		}
+	}
+	if (cancelledByUser) {
+		const reason = typeof perCallAbort.signal.reason === "string" ? perCallAbort.signal.reason : "cancelled-by-user";
+		await ctx.hooks.callHook("tool:cancelled", {
 			...buildToolHookBase(ctx, turnId, callId, call.name, displayName, effectiveInput),
-			error
-		};
-		await ctx.hooks.callHook("tool:error", errorCtx);
-		output = errorCtx.result ?? `Tool error: ${error.message}`;
-		isError = true;
+			reason,
+			runToolCounts
+		});
+		return { result: {
+			id: callId,
+			content: TOOL_USE_CANCELLED_MESSAGE,
+			isError: true
+		} };
 	}
 	const emitted = await emitToolResult(ctx, {
 		turnId,
@@ -2032,7 +2249,8 @@ async function executeToolBatch(ctx, toolCalls, turnId) {
 		const call = toolCalls[index];
 		return executeSingleTool(childCtx, call, turnId).then(({ result }) => {
 			results[index] = result;
-			if (result.isError && call.name === SHELL_TOOL_NAME && !siblingAbort.signal.aborted) siblingAbort.abort(SHELL_CASCADE_REASON);
+			const isUserCancel = typeof result.content === "string" && result.content === "[Tool call cancelled by user]";
+			if (result.isError && !isUserCancel && call.name === SHELL_TOOL_NAME && !siblingAbort.signal.aborted) siblingAbort.abort(SHELL_CASCADE_REASON);
 		}, (err) => {
 			const isAbort = siblingAbort.signal.aborted || ctx.signal.aborted || err instanceof Error && err.name === "AbortError";
 			results[index] = {
@@ -2259,6 +2477,376 @@ function defaultBlockMessage(tool, max) {
 	return `Tool '${tool}' has reached its per-run budget of ${max} calls; further invocations are refused.`;
 }
 //#endregion
+//#region src/tools/shell-semantics.ts
+const DEFAULT_SEMANTIC = (exitCode) => ({
+	isError: exitCode !== 0,
+	message: exitCode !== 0 ? `Command failed with exit code ${exitCode}` : void 0
+});
+const COMMAND_SEMANTICS = new Map([
+	["grep", (exit) => ({
+		isError: exit >= 2,
+		message: exit === 1 ? "No matches found" : void 0
+	})],
+	["rg", (exit) => ({
+		isError: exit >= 2,
+		message: exit === 1 ? "No matches found" : void 0
+	})],
+	["diff", (exit) => ({
+		isError: exit >= 2,
+		message: exit === 1 ? "Files differ" : void 0
+	})],
+	["find", (exit) => ({
+		isError: exit >= 2,
+		message: exit === 1 ? "Some directories were inaccessible" : void 0
+	})],
+	["test", (exit) => ({
+		isError: exit >= 2,
+		message: exit === 1 ? "Condition is false" : void 0
+	})],
+	["[", (exit) => ({
+		isError: exit >= 2,
+		message: exit === 1 ? "Condition is false" : void 0
+	})]
+]);
+/**
+* Pick the semantic for a command line. Best-effort: walks the command from
+* right to left, taking the last segment after `|` / `&&` / `||` / `;` —
+* that's the segment whose exit code propagates. Don't depend on this for
+* security; it's a heuristic, not a parser.
+*/
+function interpretShellResult(command, exitCode) {
+	const base = extractTrailingCommand(command);
+	return (COMMAND_SEMANTICS.get(base) ?? DEFAULT_SEMANTIC)(exitCode);
+}
+function extractTrailingCommand(command) {
+	const segments = command.split(/\|\||&&|[;|\n]/);
+	return (segments[segments.length - 1]?.trim() ?? command).split(/\s+/).filter((t) => !/^[A-Z_]\w*=/i.test(t))[0] ?? "";
+}
+//#endregion
+//#region src/tools/shell.ts
+/**
+* Execute a shell command in the agent's execution context.
+*
+* Truncation is **tail-priority**: when stdout+stderr combined exceeds
+* `maxOutputBytes`, the head is dropped and a marker `…(N bytes truncated
+* from head)…` is inserted before the tail. Errors and exit summaries
+* usually live at the end of output, so keeping the tail preserves the
+* model's most useful signal.
+*
+* Defaults are tuned for typical commands (build output, test runs): the
+* combined cap is 32 KiB and the per-call timeout follows the execution
+* context's own default (30 s for in-process).
+*/
+const DEFAULT_MAX_OUTPUT_BYTES = 32768;
+/**
+* Best-effort read-only allow-list for the leading command token. Members
+* are commands whose stock behavior cannot mutate the workspace under any
+* argument combination — `ls`, `cat`, `pwd`, etc. Commands that *can*
+* mutate depending on flags (`find -delete`, `git tag <name>`, `tar -x`)
+* are intentionally excluded; the input-aware {@link isReadOnlyShellCommand}
+* predicate falls back to the conservative "not safe" answer for them, so
+* the scheduler barriers them.
+*/
+const SHELL_READ_ONLY_COMMANDS = new Set([
+	"ls",
+	"cat",
+	"head",
+	"tail",
+	"wc",
+	"pwd",
+	"whoami",
+	"id",
+	"date",
+	"uname",
+	"hostname",
+	"tty",
+	"echo",
+	"printf",
+	"env",
+	"printenv",
+	"which",
+	"type",
+	"command",
+	"file",
+	"stat",
+	"grep",
+	"rg",
+	"ag",
+	"true",
+	"false",
+	"test"
+]);
+/**
+* `git` subcommands that are pure reads regardless of arguments. Excludes
+* `branch`/`tag`/`remote` (which can mutate when given a name) and
+* `config` (which writes when given a value).
+*/
+const GIT_READ_ONLY_SUBCOMMANDS = new Set([
+	"status",
+	"log",
+	"diff",
+	"show",
+	"blame",
+	"rev-parse",
+	"ls-files",
+	"ls-tree",
+	"cat-file",
+	"reflog",
+	"shortlog",
+	"describe",
+	"rev-list",
+	"name-rev",
+	"whatchanged",
+	"merge-base",
+	"symbolic-ref"
+]);
+/**
+* Conservative read-only verdict for a shell command — used to opt a
+* `shell` invocation into the scheduler's concurrent fleet. Returns
+* `false` (fail-closed) on anything ambiguous so the scheduler barriers
+* it. Specifically:
+*
+* - Rejects compound commands (`;`, `&&`, `||`, `|`) and redirects (`>`,
+*   `>>`, `<`) — even a pipe to a read-only sink is treated as too
+*   complex to analyze.
+* - Rejects subshell / process substitution (`$(...)`, `` `...` ``,
+*   `<(...)`, `>(...)`).
+* - Skips leading `VAR=value` env assignments to find the real
+*   command token.
+* - Strips a possible absolute path on the command (`/usr/bin/ls` → `ls`).
+* - Allows the command iff its base name is in
+*   {@link SHELL_READ_ONLY_COMMANDS} OR it's `git <subcmd>` where
+*   `<subcmd>` is in {@link GIT_READ_ONLY_SUBCOMMANDS}.
+*
+* Cheap (no spawned process; regex + token scan). Safe to call from the
+* hot scheduler path.
+*/
+function isReadOnlyShellCommand(command) {
+	if (typeof command !== "string") return false;
+	const trimmed = command.trim();
+	if (trimmed === "") return false;
+	if (/[<>;&|`\n]/.test(trimmed)) return false;
+	if (trimmed.includes("$(") || trimmed.includes("<(") || trimmed.includes(">(")) return false;
+	const tokens = trimmed.split(/\s+/);
+	let i = 0;
+	while (i < tokens.length && /^[A-Z_]\w*=/i.test(tokens[i])) i++;
+	const head = tokens[i];
+	if (!head) return false;
+	const base = head.split("/").pop() ?? head;
+	if (SHELL_READ_ONLY_COMMANDS.has(base)) return true;
+	if (base === "git") {
+		const sub = tokens[i + 1];
+		return typeof sub === "string" && GIT_READ_ONLY_SUBCOMMANDS.has(sub);
+	}
+	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.
+*/
+function buildShellDescription({ allowBackground }) {
+	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 (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");
+}
+/**
+* Build the `shell` tool's JSON-schema. The `run_in_background` field
+* is included only when `allowBackground` is true; the `timeout` /
+* `maxOutputBytes` / `metadata` field descriptions also drop their
+* "Ignored in background mode" qualifier when there's no background
+* mode to ignore.
+*/
+function buildShellInputSchema({ allowBackground }) {
+	const bgQualifier = allowBackground ? " Ignored in background mode." : "";
+	const bgQualifierOutput = allowBackground ? " Ignored in background mode (output streams to disk)." : "";
+	const properties = {
+		command: {
+			type: "string",
+			description: "Shell command to run."
+		},
+		timeout: {
+			type: "integer",
+			description: `Per-call timeout in milliseconds.${bgQualifier}`
+		},
+		maxOutputBytes: {
+			type: "integer",
+			description: `Truncate combined stdout+stderr beyond this many bytes. Default: 32768. Set 0 for unlimited.${bgQualifierOutput}`
+		},
+		metadata: {
+			type: "boolean",
+			description: `Append \`(exit N, Nms)\` footer and surface non-empty stderr on success. Default: true.${bgQualifier}`
+		}
+	};
+	if (allowBackground) properties.run_in_background = {
+		type: "boolean",
+		description: "Start the command in the background, returning a task handle. See the tool description for the full flow."
+	};
+	return {
+		type: "object",
+		properties,
+		required: ["command"]
+	};
+}
+/**
+* Factory for the `shell` tool. The default exported `shell` is
+* equivalent to `createShellTool({ allowBackground: true })`. The
+* factory is the entry point hosts use when they want to override the
+* default — e.g. to ship a preset that always disables background mode
+* regardless of `behavior.tasksDir`.
+*
+* Hosts that use the framework's `createAgent` typically don't need to
+* call this directly: when `behavior.tasksDir` is unset or
+* `behavior.disableBackgroundTasks: true` is set, the agent
+* automatically rewrites the registered `shell` (if it's the
+* framework's built-in) using this factory.
+*/
+function createShellTool(opts = {}) {
+	const allowBackground = opts.allowBackground !== false;
+	return {
+		isConcurrencySafe: (input) => isReadOnlyShellCommand(input.command),
+		spec: {
+			name: "shell",
+			description: buildShellDescription({ allowBackground }),
+			inputSchema: buildShellInputSchema({ allowBackground })
+		},
+		async execute({ command, timeout, maxOutputBytes, metadata, run_in_background }, ctx) {
+			const cmd = command;
+			if (run_in_background === true) {
+				if (!allowBackground) return "shell error: background mode is disabled for this agent (no `behavior.tasksDir` set, or `behavior.disableBackgroundTasks: true`). Fall back to foreground (drop `run_in_background`).";
+				return runBackground(cmd, ctx);
+			}
+			const execOpts = { signal: ctx.signal };
+			if (typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0) execOpts.timeout = Math.max(1, Math.ceil(timeout / 1e3));
+			const wantMetadata = metadata !== false;
+			const startedAt = Date.now();
+			const result = await ctx.execution.exec(ctx.handle, cmd, execOpts);
+			const durationMs = Date.now() - startedAt;
+			const cap = normalizeCap(maxOutputBytes);
+			const semantic = interpretShellResult(cmd, result.exitCode);
+			if (result.exitCode === 0) {
+				const stdoutTail = truncateTail(result.stdout || "(no output)", cap);
+				if (!wantMetadata) return stdoutTail;
+				const stderrTrimmed = result.stderr.trim();
+				return `${stdoutTail}${stderrTrimmed ? `\n[stderr]\n${truncateTail(stderrTrimmed, Math.min(cap, 2048))}` : ""}\n(exit 0, ${durationMs}ms)`;
+			}
+			if (!semantic.isError) {
+				const tail = truncateTail((result.stdout || result.stderr || "").trim(), cap);
+				const semanticFooter = semantic.message ? `\n(${semantic.message})` : "";
+				const timingFooter = wantMetadata ? `\n(exit ${result.exitCode}, ${durationMs}ms)` : "";
+				return `${tail.length > 0 ? tail : semantic.message ?? "(no output)"}${semanticFooter}${timingFooter}`;
+			}
+			const combined = `${result.stdout}\n${result.stderr}`.trim();
+			return `${wantMetadata ? `Exit code ${result.exitCode} (${durationMs}ms)` : `Exit code ${result.exitCode}`}\n${truncateTail(combined, cap)}`;
+		}
+	};
+}
+/**
+* Default `shell` tool with background mode enabled.
+*
+* Most hosts use this directly via `basicTools`. When the agent's
+* `behavior.tasksDir` is unset OR `behavior.disableBackgroundTasks:
+* true` is set, `createAgent` auto-rewrites this identity to a
+* `createShellTool({ allowBackground: false })` variant so the model
+* never sees a flag it can't use. Hosts who want to bypass that
+* auto-rewrite can register a `createShellTool({ allowBackground })`
+* directly — the rewrite only fires on identity-equal references to
+* this constant.
+*/
+const shell = createShellTool({ allowBackground: true });
+/**
+* Background-mode entry point for the `shell` tool. Settles fast,
+* registers an `onExit` callback that fires `background:exit` on the
+* agent's hook bus, and returns a structured one-liner to the model.
+*
+* Reachable only via the `allowBackground: true` variant; the
+* `allowBackground: false` variant short-circuits before this is
+* called and `createAgent` auto-rewrites the built-in to the
+* `false` variant when `behavior.tasksDir` is unset or
+* `behavior.disableBackgroundTasks: true` is set. The runtime checks
+* below are defense-in-depth for hosts who skip the auto-rewrite
+* (custom shell tool, run-level tools override, etc.):
+*
+*   - `behavior.tasksDir` unset → host opted into the schema but
+*     forgot to wire the log dir. Clean error, model can fall back to
+*     foreground.
+*   - `ctx.execution.execBackground` undefined → the context doesn't
+*     support it (some remote sandboxes).
+*   - `mkdir` on the output dir fails → the underlying filesystem
+*     can't accommodate. Surface the error verbatim.
+*/
+async function runBackground(command, ctx) {
+	const tasksDir = ctx.behavior?.tasksDir;
+	if (typeof tasksDir !== "string" || tasksDir.length === 0) return "shell error: background mode requires `behavior.tasksDir` to be set on the agent. The host has not opted into background tasks — either fall back to foreground (drop `run_in_background`) or ask the user to enable it.";
+	if (!ctx.execution.execBackground) return `shell error: the active execution context (${ctx.execution.type}) does not support background tasks. Fall back to foreground (drop \`run_in_background\`).`;
+	try {
+		const handle = await ctx.execution.execBackground(ctx.handle, command, {
+			outputDir: tasksDir,
+			onExit: (info) => {
+				Promise.resolve(ctx.hooks.callHook("background:exit", info)).catch((err) => {
+					if (process.env.ZIDANE_DEBUG) process.stderr.write(`[zidane/shell] background:exit hook rejected: ${err instanceof Error ? err.message : String(err)}\n`);
+				});
+			}
+		});
+		Promise.resolve(ctx.hooks.callHook("background:start", {
+			taskId: handle.taskId,
+			pid: handle.pid,
+			command,
+			cwd: ctx.handle.cwd,
+			outputPath: handle.outputPath,
+			startedAt: Date.now()
+		})).catch((err) => {
+			if (process.env.ZIDANE_DEBUG) process.stderr.write(`[zidane/shell] background:start hook rejected: ${err instanceof Error ? err.message : String(err)}\n`);
+		});
+		const cmdPreview = previewLine(command, 60);
+		const wakeupHint = (ctx.depth ?? 0) > 0 ? "You are inside a `spawn`'d subagent — you have NO next user-turn to receive the notification on. Return a brief summary INCLUDING this task_id and end your turn now. Ownership of the task transfers to the parent agent when your run completes; the parent will see the `<task-notification>` on its next user-turn." : "The task is running in the background. You'll receive a <task-notification> on your NEXT user-turn with the final status. End your current turn now — do NOT poll the output file in a loop, the notification IS the wake-up. To inspect progress, call `read_file({ path: <output> })` once. To terminate, use `shell_kill({ task_id })`.";
+		return [
+			`Started ${handle.taskId} (pid ${handle.pid}).`,
+			`  command: ${cmdPreview}`,
+			`  output:  ${handle.outputPath}`,
+			"",
+			wakeupHint
+		].join("\n");
+	} catch (err) {
+		return `shell error: failed to start background task: ${err instanceof Error ? err.message : String(err)}`;
+	}
+}
+function normalizeCap(value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_MAX_OUTPUT_BYTES;
+	if (value < 0) return DEFAULT_MAX_OUTPUT_BYTES;
+	return Math.floor(value);
+}
+/**
+* Tail-priority byte truncation. When `text` exceeds `cap` bytes, the head is
+* dropped and replaced with a marker. Always cuts on character boundaries (no
+* mid-codepoint splits) by walking from the end with `Buffer.byteLength`.
+*
+* `cap === 0` disables truncation. `cap` is interpreted as a UTF-8 byte budget
+* for the tail itself — the marker is added on top and may push the visible
+* length slightly past `cap`. That tradeoff is intentional: a marker that
+* always fits inside the budget would shrink the actual content displayed.
+*/
+function truncateTail(text, cap) {
+	if (cap === 0) return text;
+	const totalBytes = Buffer.byteLength(text);
+	if (totalBytes <= cap) return text;
+	let bytes = 0;
+	let charIdx = text.length;
+	while (charIdx > 0) {
+		const ch = text[charIdx - 1];
+		const chBytes = Buffer.byteLength(ch);
+		if (bytes + chBytes > cap) break;
+		bytes += chBytes;
+		charIdx--;
+	}
+	const tail = text.slice(charIdx);
+	return `…(${totalBytes - Buffer.byteLength(tail)} bytes truncated from head)…\n${tail}`;
+}
+//#endregion
 //#region src/tools/binary-detect.ts
 /**
 * Heuristics for detecting binary content in UTF-8-decoded strings.
@@ -2426,7 +3014,10 @@ function createSkillsRunScriptTool(options) {
 			if (!validated.valid) return `Error: ${validated.error}`;
 			const cmd = [validated.absolutePath, ...args].map(alwaysQuote).join(" ");
 			try {
-				const result = await ctx.execution.exec(ctx.handle, cmd, { timeout: Math.max(1, Math.round(timeoutMs / 1e3)) });
+				const result = await ctx.execution.exec(ctx.handle, cmd, {
+					timeout: Math.max(1, Math.round(timeoutMs / 1e3)),
+					signal: ctx.signal
+				});
 				return JSON.stringify({
 					exitCode: result.exitCode,
 					stdout: result.stdout,
@@ -2480,14 +3071,21 @@ function createSkillsUseTool(options) {
 	return {
 		spec: {
 			name: "skills_use",
-			description: "Activate a specialized skill and load its full instructions. Call this when a task matches a skill's description from the catalog. After calling, follow the returned instructions; use skills_read to load referenced files and skills_run_script to execute bundled scripts.",
+			description: "Activate or deactivate a specialized skill. Call with `mode: \"activate\"` (default) to load a skill's full instructions when a task matches its catalog description. Call with `mode: \"deactivate\"` to release a skill whose allowed-tools restrictions are now in the way — e.g. when the skill's work is done or the active skill is blocking unrelated tool calls. After activating, follow the returned instructions; use skills_read to load referenced files and skills_run_script to execute bundled scripts.",
 			inputSchema: {
 				type: "object",
-				properties: { name: {
-					type: "string",
-					enum: options.catalog.map((s) => s.name),
-					description: "The name of the skill to activate (must be in the available skills catalog)."
-				} },
+				properties: {
+					name: {
+						type: "string",
+						enum: options.catalog.map((s) => s.name),
+						description: "The name of the skill to activate or deactivate (must be in the available skills catalog)."
+					},
+					mode: {
+						type: "string",
+						enum: ["activate", "deactivate"],
+						description: "Whether to activate (load + apply the skill) or deactivate (release an active skill). Default: \"activate\"."
+					}
+				},
 				required: ["name"],
 				additionalProperties: false
 			}
@@ -2496,8 +3094,18 @@ function createSkillsUseTool(options) {
 			const skillName = input.name;
 			const skill = byName.get(skillName);
 			if (!skill) return `Error: unknown skill "${skillName}". Available skills: ${[...byName.keys()].join(", ") || "<none>"}.`;
+			if ((input.mode ?? "activate") === "deactivate") {
+				const removed = options.state.deactivate(skillName);
+				if (!removed) return `Skill "${skillName}" was not active — nothing to deactivate.`;
+				await options.hooks.callHook("skills:deactivate", {
+					skill: removed.skill,
+					reason: "model"
+				});
+				const remaining = options.state.active().map((a) => a.skill.name);
+				return `Skill "${skillName}" deactivated — its allowed-tools restrictions no longer apply.${remaining.length > 0 ? ` Remaining active skills: ${remaining.join(", ")}.` : " No skills are currently active."}`;
+			}
 			if (!options.state.isActive(skillName)) {
-				if (options.state.activate(skill, "model") === "cap-reached") return `Error: cannot activate "${skillName}" — the maxActive skill cap has been reached. Currently active: ${options.state.active().map((a) => a.skill.name).join(", ")}. Deactivate an existing skill first.`;
+				if (options.state.activate(skill, "model") === "cap-reached") return `Error: cannot activate "${skillName}" — the maxActive skill cap has been reached. Currently active: ${options.state.active().map((a) => a.skill.name).join(", ")}. Call \`skills_use\` with \`mode: "deactivate"\` and one of those names first.`;
 				await options.hooks.callHook("skills:activate", {
 					skill,
 					via: "model"
@@ -2656,6 +3264,39 @@ function createToolSearchTool(options) {
 }
 //#endregion
 //#region src/agent.ts
+/**
+* Authoritative list of hook event names. Kept in sync with `AgentHooks` at
+* compile time: the `satisfies` assertion below rejects any drift.
+*/
+/**
+* Canonical XML wire format for a background-task completion notification.
+*
+* Rendered as a leading `text` content block in the next user-turn so
+* the model can pattern-match on the outer tag. The shape uses kebab-case
+* tags (matching zidane's other XML conventions). Every field is
+* structured — `<summary>` is a derived display string, NOT the source
+* of truth for the underlying data (replay reads `<command>` /
+* `<duration-ms>` / etc. directly, never the summary, so changing the
+* summary format can't break replay).
+*
+* Field-level escaping uses {@link escapeXml} so commands containing
+* `<` / `>` / `&` round-trip cleanly through persistence + replay.
+*/
+function renderTaskNotificationXml(info) {
+	const summary = formatTaskSummary(info);
+	return [
+		"<task-notification>",
+		`  <task-id>${escapeXml(info.taskId)}</task-id>`,
+		`  <status>${info.status}</status>`,
+		`  <exit-code>${info.exitCode}</exit-code>`,
+		...info.signal ? [`  <signal>${escapeXml(info.signal)}</signal>`] : [],
+		`  <command>${escapeXml(info.command)}</command>`,
+		`  <output-file>${escapeXml(info.outputPath)}</output-file>`,
+		`  <duration-ms>${info.durationMs}</duration-ms>`,
+		`  <summary>${escapeXml(summary)}</summary>`,
+		"</task-notification>"
+	].join("\n");
+}
 const HOOK_EVENT_SET = new Set([
 	"system:before",
 	"agent:start",
@@ -2673,6 +3314,7 @@ const HOOK_EVENT_SET = new Set([
 	"tool:before",
 	"tool:after",
 	"tool:error",
+	"tool:cancelled",
 	"tool:transform",
 	"tool:unknown",
 	"validation:reject",
@@ -2694,6 +3336,10 @@ const HOOK_EVENT_SET = new Set([
 	"child:tool:after",
 	"child:tool:transform",
 	"child:tool:error",
+	"child:tool:cancelled",
+	"child:background:start",
+	"child:background:exit",
+	"child:background:reassign",
 	"child:turn:after",
 	"mcp:connect",
 	"mcp:error",
@@ -2710,6 +3356,9 @@ const HOOK_EVENT_SET = new Set([
 	"mcp:tool:after",
 	"mcp:tool:transform",
 	"mcp:tool:error",
+	"background:start",
+	"background:exit",
+	"background:reassign",
 	"skills:resolve",
 	"skills:catalog",
 	"skills:activate",
@@ -2810,6 +3459,8 @@ function resolveBehavior(agentBehavior, runBehavior) {
 		persistThreshold: runBehavior?.persistThreshold ?? agentBehavior?.persistThreshold,
 		persistExcludeTools: runBehavior?.persistExcludeTools ?? agentBehavior?.persistExcludeTools,
 		persistDir: runBehavior?.persistDir ?? agentBehavior?.persistDir,
+		tasksDir: runBehavior?.tasksDir ?? agentBehavior?.tasksDir,
+		disableBackgroundTasks: runBehavior?.disableBackgroundTasks ?? agentBehavior?.disableBackgroundTasks,
 		strictToolPairing: runBehavior?.strictToolPairing ?? agentBehavior?.strictToolPairing ?? false
 	};
 }
@@ -2973,6 +3624,8 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 	let running = false;
 	let idleResolve;
 	let idlePromise;
+	const pendingTaskNotifications = /* @__PURE__ */ new Map();
+	const pendingToolCancels = /* @__PURE__ */ new Map();
 	let executionHandle = null;
 	let mcpConnection = null;
 	let mcpWarmupPromise = null;
@@ -3040,6 +3693,7 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 		running = true;
 		try {
 			abortController = new AbortController();
+			runCounter = Math.max(runCounter, initialRunCounter(session));
 			const runId = `run_${++runCounter}`;
 			const promptLabel = typeof options.prompt === "string" ? options.prompt : Array.isArray(options.prompt) ? options.prompt.filter((p) => p.type === "text").map((p) => p.text).join("\n") : "";
 			session?.startRun(runId, promptLabel, {
@@ -3090,20 +3744,27 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 			await ensureSkillsResolved();
 			if (resolvedSkills && session && session.turns.length > 0 && skillActivationState.active().length === 0) {
 				const skillsByName = new Map(resolvedSkills.map((s) => [s.name, s]));
+				const lastModeBySkill = /* @__PURE__ */ new Map();
 				for (const turn of session.turns) {
 					if (turn.role !== "assistant") continue;
 					for (const block of turn.content) {
 						if (block.type !== "tool_call" || block.name !== "skills_use") continue;
-						const skillName = block.input?.name;
+						const input = block.input;
+						const skillName = input?.name;
 						if (!skillName) continue;
-						const skill = skillsByName.get(skillName);
-						if (!skill) continue;
-						if (skillActivationState.activate(skill, "resume") === "ok") await hooks.callHook("skills:activate", {
-							skill,
-							via: "resume"
-						});
+						const mode = input?.mode === "deactivate" ? "deactivate" : "activate";
+						lastModeBySkill.set(skillName, mode);
 					}
 				}
+				for (const [skillName, mode] of lastModeBySkill) {
+					if (mode !== "activate") continue;
+					const skill = skillsByName.get(skillName);
+					if (!skill) continue;
+					if (skillActivationState.activate(skill, "resume") === "ok") await hooks.callHook("skills:activate", {
+						skill,
+						via: "resume"
+					});
+				}
 			}
 			const thinking = options.thinking ?? "off";
 			const model = options.model ?? provider.meta.defaultModel;
@@ -3135,6 +3796,9 @@ 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 });
+			}
 			const disclosure = partitionToolDisclosure(toolsPreSearch, mcpToolNames, mcpServers, toolDisclosure, toolAliases);
 			const unlocked = new Set(disclosure.eagerCanonicalNames);
 			const hostDefinedToolSearch = !!toolsPreSearch.tool_search;
@@ -3169,8 +3833,7 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 			}
 			const formattedTools = buildFormattedTools();
 			const turns = [];
-			const isResume = session && session.turns.length > 0 && (session.runs.length > 0 || !options.prompt) && !options.parentRunId;
-			if (isResume) {
+			if (session && session.turns.length > 0 && (session.runs.length > 0 || !options.prompt) && !options.parentRunId) {
 				const childRunIds = new Set(session.runs.filter((r) => (r.depth ?? 0) > 0).map((r) => r.id));
 				const resumed = childRunIds.size === 0 ? session.turns : session.turns.filter((t) => !t.runId || !childRunIds.has(t.runId));
 				const filteredForRuntime = resumeFilteredTurns && resumed === session.turns ? resumeFilteredTurns : filterUnresolvedToolUses(resumed);
@@ -3178,19 +3841,28 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 			}
 			const runTurnStart = turns.length;
 			if (options.system) await hooks.callHook("system:before", { system: options.system });
+			const drainedNotifications = [];
+			if (pendingTaskNotifications.size > 0) {
+				for (const notif of pendingTaskNotifications.values()) drainedNotifications.push({
+					type: "text",
+					text: renderTaskNotificationXml(notif)
+				});
+				pendingTaskNotifications.clear();
+			}
+			let lastPersistedTurnCount = turns.length;
 			const promptParts = canonicalizePrompt(options.prompt);
-			if (promptParts) {
-				const promptMsg = buildPromptMessage(provider, promptParts);
+			if (promptParts || drainedNotifications.length > 0) {
+				const promptMsg = promptParts ? buildPromptMessage(provider, promptParts) : null;
+				const content = [...drainedNotifications, ...promptMsg ? promptMsg.content : []];
 				turns.push({
 					id: crypto.randomUUID(),
 					runId,
-					role: promptMsg.role,
-					content: promptMsg.content,
+					role: promptMsg ? promptMsg.role : "user",
+					content,
 					createdAt: Date.now()
 				});
 			}
 			conversationTurns = turns;
-			let lastPersistedTurnCount = isResume ? session.turns.length : 0;
 			if (session && turns.length > lastPersistedTurnCount) {
 				const seededTurns = turns.slice(lastPersistedTurnCount);
 				await session.appendTurns(seededTurns);
@@ -3301,7 +3973,8 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 					...strictToolPairing ? { strictToolPairing: true } : {},
 					providerName: provider.name,
 					runStartMs,
-					runToolCounts: {}
+					runToolCounts: {},
+					pendingToolCancels
 				});
 				const parentTurnCost = stats.turnUsage?.reduce((sum, t) => sum + (t.cost ?? 0), 0) ?? 0;
 				let childrenIn = 0;
@@ -3398,6 +4071,17 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 	function abort() {
 		abortController?.abort();
 	}
+	function cancelTool(callId, reason) {
+		const controller = pendingToolCancels.get(callId);
+		if (!controller || controller.signal.aborted) return false;
+		controller.abort(reason ?? "user-cancelled-tool");
+		return true;
+	}
+	async function killBackgroundTask(taskId) {
+		if (!executionHandle) return false;
+		if (!executionContext.killBackground) return false;
+		return await executionContext.killBackground(executionHandle, taskId) !== null;
+	}
 	function steer(message) {
 		steeringQueue.push(message);
 	}
@@ -3412,6 +4096,7 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 		conversationTurns = [];
 		steeringQueue.length = 0;
 		followUpQueue.length = 0;
+		pendingTaskNotifications.clear();
 		const cleared = skillActivationState.clear();
 		for (const record of cleared) await hooks.callHook("skills:deactivate", {
 			skill: record.skill,
@@ -3440,6 +4125,33 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 			reason: "explicit"
 		});
 	}
+	hooks.hook("background:exit", (ctx) => {
+		pendingTaskNotifications.set(ctx.taskId, {
+			taskId: ctx.taskId,
+			status: ctx.status,
+			exitCode: ctx.exitCode,
+			...ctx.signal ? { signal: ctx.signal } : {},
+			outputPath: ctx.outputPath,
+			durationMs: ctx.durationMs,
+			command: ctx.command
+		});
+	});
+	hooks.hook("tool:after", (ctx) => {
+		if (ctx.name === "shell_kill") {
+			const taskId = ctx.input?.task_id;
+			if (typeof taskId === "string") pendingTaskNotifications.delete(taskId);
+			return;
+		}
+		if (ctx.name === "read_file" || ctx.name === "read") {
+			const rawPath = ctx.input?.path;
+			if (typeof rawPath !== "string" || rawPath.length === 0) return;
+			const requested = resolve(rawPath);
+			for (const notif of pendingTaskNotifications.values()) if (resolve(notif.outputPath) === requested) {
+				pendingTaskNotifications.delete(notif.taskId);
+				return;
+			}
+		}
+	});
 	if (session) {
 		const originalSave = session.save.bind(session);
 		const originalSetMeta = session.setMeta.bind(session);
@@ -3491,6 +4203,9 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 	async function destroy() {
 		if (destroyed) return;
 		destroyed = true;
+		pendingTaskNotifications.clear();
+		for (const controller of pendingToolCancels.values()) if (!controller.signal.aborted) controller.abort("agent-destroyed");
+		pendingToolCancels.clear();
 		if (mcpWarmupPromise) try {
 			await mcpWarmupPromise;
 		} catch {}
@@ -3502,6 +4217,7 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 			await executionContext.destroy(executionHandle);
 			executionHandle = null;
 		}
+		pendingTaskNotifications.clear();
 		skillsCleanup();
 		skillsCleanup = () => {};
 	}
@@ -3511,6 +4227,8 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 		hooks,
 		run,
 		abort,
+		cancelTool,
+		killBackgroundTask,
 		steer,
 		followUp: followUpFn,
 		waitForIdle,
@@ -4643,254 +5361,39 @@ function normalizeInteger(value, fallback) {
 	return Math.floor(value);
 }
 //#endregion
-//#region src/tools/shell-semantics.ts
-const DEFAULT_SEMANTIC = (exitCode) => ({
-	isError: exitCode !== 0,
-	message: exitCode !== 0 ? `Command failed with exit code ${exitCode}` : void 0
-});
-const COMMAND_SEMANTICS = new Map([
-	["grep", (exit) => ({
-		isError: exit >= 2,
-		message: exit === 1 ? "No matches found" : void 0
-	})],
-	["rg", (exit) => ({
-		isError: exit >= 2,
-		message: exit === 1 ? "No matches found" : void 0
-	})],
-	["diff", (exit) => ({
-		isError: exit >= 2,
-		message: exit === 1 ? "Files differ" : void 0
-	})],
-	["find", (exit) => ({
-		isError: exit >= 2,
-		message: exit === 1 ? "Some directories were inaccessible" : void 0
-	})],
-	["test", (exit) => ({
-		isError: exit >= 2,
-		message: exit === 1 ? "Condition is false" : void 0
-	})],
-	["[", (exit) => ({
-		isError: exit >= 2,
-		message: exit === 1 ? "Condition is false" : void 0
-	})]
-]);
-/**
-* Pick the semantic for a command line. Best-effort: walks the command from
-* right to left, taking the last segment after `|` / `&&` / `||` / `;` —
-* that's the segment whose exit code propagates. Don't depend on this for
-* security; it's a heuristic, not a parser.
-*/
-function interpretShellResult(command, exitCode) {
-	const base = extractTrailingCommand(command);
-	return (COMMAND_SEMANTICS.get(base) ?? DEFAULT_SEMANTIC)(exitCode);
-}
-function extractTrailingCommand(command) {
-	const segments = command.split(/\|\||&&|[;|\n]/);
-	return (segments[segments.length - 1]?.trim() ?? command).split(/\s+/).filter((t) => !/^[A-Z_]\w*=/i.test(t))[0] ?? "";
-}
-//#endregion
-//#region src/tools/shell.ts
-/**
-* Execute a shell command in the agent's execution context.
-*
-* Truncation is **tail-priority**: when stdout+stderr combined exceeds
-* `maxOutputBytes`, the head is dropped and a marker `…(N bytes truncated
-* from head)…` is inserted before the tail. Errors and exit summaries
-* usually live at the end of output, so keeping the tail preserves the
-* model's most useful signal.
-*
-* Defaults are tuned for typical commands (build output, test runs): the
-* combined cap is 32 KiB and the per-call timeout follows the execution
-* context's own default (30 s for in-process).
-*/
-const DEFAULT_MAX_OUTPUT_BYTES = 32768;
-/**
-* Best-effort read-only allow-list for the leading command token. Members
-* are commands whose stock behavior cannot mutate the workspace under any
-* argument combination — `ls`, `cat`, `pwd`, etc. Commands that *can*
-* mutate depending on flags (`find -delete`, `git tag <name>`, `tar -x`)
-* are intentionally excluded; the input-aware {@link isReadOnlyShellCommand}
-* predicate falls back to the conservative "not safe" answer for them, so
-* the scheduler barriers them.
-*/
-const SHELL_READ_ONLY_COMMANDS = new Set([
-	"ls",
-	"cat",
-	"head",
-	"tail",
-	"wc",
-	"pwd",
-	"whoami",
-	"id",
-	"date",
-	"uname",
-	"hostname",
-	"tty",
-	"echo",
-	"printf",
-	"env",
-	"printenv",
-	"which",
-	"type",
-	"command",
-	"file",
-	"stat",
-	"grep",
-	"rg",
-	"ag",
-	"true",
-	"false",
-	"test"
-]);
-/**
-* `git` subcommands that are pure reads regardless of arguments. Excludes
-* `branch`/`tag`/`remote` (which can mutate when given a name) and
-* `config` (which writes when given a value).
-*/
-const GIT_READ_ONLY_SUBCOMMANDS = new Set([
-	"status",
-	"log",
-	"diff",
-	"show",
-	"blame",
-	"rev-parse",
-	"ls-files",
-	"ls-tree",
-	"cat-file",
-	"reflog",
-	"shortlog",
-	"describe",
-	"rev-list",
-	"name-rev",
-	"whatchanged",
-	"merge-base",
-	"symbolic-ref"
-]);
-/**
-* Conservative read-only verdict for a shell command — used to opt a
-* `shell` invocation into the scheduler's concurrent fleet. Returns
-* `false` (fail-closed) on anything ambiguous so the scheduler barriers
-* it. Specifically:
-*
-* - Rejects compound commands (`;`, `&&`, `||`, `|`) and redirects (`>`,
-*   `>>`, `<`) — even a pipe to a read-only sink is treated as too
-*   complex to analyze.
-* - Rejects subshell / process substitution (`$(...)`, `` `...` ``,
-*   `<(...)`, `>(...)`).
-* - Skips leading `VAR=value` env assignments to find the real
-*   command token.
-* - Strips a possible absolute path on the command (`/usr/bin/ls` → `ls`).
-* - Allows the command iff its base name is in
-*   {@link SHELL_READ_ONLY_COMMANDS} OR it's `git <subcmd>` where
-*   `<subcmd>` is in {@link GIT_READ_ONLY_SUBCOMMANDS}.
-*
-* Cheap (no spawned process; regex + token scan). Safe to call from the
-* hot scheduler path.
-*/
-function isReadOnlyShellCommand(command) {
-	if (typeof command !== "string") return false;
-	const trimmed = command.trim();
-	if (trimmed === "") return false;
-	if (/[<>;&|`\n]/.test(trimmed)) return false;
-	if (trimmed.includes("$(") || trimmed.includes("<(") || trimmed.includes(">(")) return false;
-	const tokens = trimmed.split(/\s+/);
-	let i = 0;
-	while (i < tokens.length && /^[A-Z_]\w*=/i.test(tokens[i])) i++;
-	const head = tokens[i];
-	if (!head) return false;
-	const base = head.split("/").pop() ?? head;
-	if (SHELL_READ_ONLY_COMMANDS.has(base)) return true;
-	if (base === "git") {
-		const sub = tokens[i + 1];
-		return typeof sub === "string" && GIT_READ_ONLY_SUBCOMMANDS.has(sub);
-	}
-	return false;
-}
-const shell = {
-	isConcurrencySafe: (input) => isReadOnlyShellCommand(input.command),
+//#region src/tools/shell-kill.ts
+const shellKill = {
+	isConcurrencySafe: true,
 	spec: {
-		name: "shell",
-		description: "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.",
+		name: "shell_kill",
+		description: [
+			"Terminate a running background task started by `shell({ run_in_background: true })`.",
+			"Sends SIGTERM to the whole process group so the shell wrapper AND its child commands die together.",
+			"Returns the final exit info (status, exit code, output path) or a \"no such task\" message when the id is unknown / already cleaned up.",
+			"Idempotent — calling on a task that has already terminated returns the cached exit info without re-killing."
+		].join("\n"),
 		inputSchema: {
 			type: "object",
-			properties: {
-				command: {
-					type: "string",
-					description: "Shell command to run."
-				},
-				timeout: {
-					type: "integer",
-					description: "Per-call timeout in milliseconds."
-				},
-				maxOutputBytes: {
-					type: "integer",
-					description: "Truncate combined stdout+stderr beyond this many bytes. Default: 32768. Set 0 for unlimited."
-				},
-				metadata: {
-					type: "boolean",
-					description: "Append `(exit N, Nms)` footer and surface non-empty stderr on success. Default: true."
-				}
-			},
-			required: ["command"]
+			properties: { task_id: {
+				type: "string",
+				description: "The task id returned by a prior `shell({ run_in_background: true })` call."
+			} },
+			required: ["task_id"],
+			additionalProperties: false
 		}
 	},
-	async execute({ command, timeout, maxOutputBytes, metadata }, ctx) {
-		const execOpts = {};
-		if (typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0) execOpts.timeout = Math.max(1, Math.ceil(timeout / 1e3));
-		const cmd = command;
-		const wantMetadata = metadata !== false;
-		const startedAt = Date.now();
-		const result = await ctx.execution.exec(ctx.handle, cmd, execOpts);
-		const durationMs = Date.now() - startedAt;
-		const cap = normalizeCap(maxOutputBytes);
-		const semantic = interpretShellResult(cmd, result.exitCode);
-		if (result.exitCode === 0) {
-			const stdoutTail = truncateTail(result.stdout || "(no output)", cap);
-			if (!wantMetadata) return stdoutTail;
-			const stderrTrimmed = result.stderr.trim();
-			return `${stdoutTail}${stderrTrimmed ? `\n[stderr]\n${truncateTail(stderrTrimmed, Math.min(cap, 2048))}` : ""}\n(exit 0, ${durationMs}ms)`;
-		}
-		if (!semantic.isError) {
-			const tail = truncateTail((result.stdout || result.stderr || "").trim(), cap);
-			const semanticFooter = semantic.message ? `\n(${semantic.message})` : "";
-			const timingFooter = wantMetadata ? `\n(exit ${result.exitCode}, ${durationMs}ms)` : "";
-			return `${tail.length > 0 ? tail : semantic.message ?? "(no output)"}${semanticFooter}${timingFooter}`;
-		}
-		const combined = `${result.stdout}\n${result.stderr}`.trim();
-		return `${wantMetadata ? `Exit code ${result.exitCode} (${durationMs}ms)` : `Exit code ${result.exitCode}`}\n${truncateTail(combined, cap)}`;
+	async execute(input, ctx) {
+		const taskId = input.task_id;
+		if (!ctx.execution.killBackground) return `shell_kill error: the active execution context (${ctx.execution.type}) does not support background tasks.`;
+		const info = await ctx.execution.killBackground(ctx.handle, taskId);
+		if (!info) return `shell_kill: no such task "${taskId}". It may have already exited and been cleaned up, or it was never started in this session.`;
+		return [
+			`Killed ${info.taskId} — ${formatTaskStatus(info)} after ${formatDuration(info.durationMs)}.`,
+			`  command: ${previewLine(info.command, 60)}`,
+			`  output:  ${info.outputPath}`
+		].join("\n");
 	}
 };
-function normalizeCap(value) {
-	if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_MAX_OUTPUT_BYTES;
-	if (value < 0) return DEFAULT_MAX_OUTPUT_BYTES;
-	return Math.floor(value);
-}
-/**
-* Tail-priority byte truncation. When `text` exceeds `cap` bytes, the head is
-* dropped and replaced with a marker. Always cuts on character boundaries (no
-* mid-codepoint splits) by walking from the end with `Buffer.byteLength`.
-*
-* `cap === 0` disables truncation. `cap` is interpreted as a UTF-8 byte budget
-* for the tail itself — the marker is added on top and may push the visible
-* length slightly past `cap`. That tradeoff is intentional: a marker that
-* always fits inside the budget would shrink the actual content displayed.
-*/
-function truncateTail(text, cap) {
-	if (cap === 0) return text;
-	const totalBytes = Buffer.byteLength(text);
-	if (totalBytes <= cap) return text;
-	let bytes = 0;
-	let charIdx = text.length;
-	while (charIdx > 0) {
-		const ch = text[charIdx - 1];
-		const chBytes = Buffer.byteLength(ch);
-		if (bytes + chBytes > cap) break;
-		bytes += chBytes;
-		charIdx--;
-	}
-	const tail = text.slice(charIdx);
-	return `…(${totalBytes - Buffer.byteLength(tail)} bytes truncated from head)…\n${tail}`;
-}
 //#endregion
 //#region src/tools/spawn.ts
 const BUBBLED_EVENTS = [
@@ -4902,6 +5405,10 @@ const BUBBLED_EVENTS = [
 	"tool:before",
 	"tool:after",
 	"tool:error",
+	"tool:cancelled",
+	"background:start",
+	"background:exit",
+	"background:reassign",
 	"turn:after"
 ];
 const BUBBLED_MUTABLE_EVENTS = [
@@ -4918,6 +5425,10 @@ const CHILD_EVENT_NAME = {
 	"tool:before": "child:tool:before",
 	"tool:after": "child:tool:after",
 	"tool:error": "child:tool:error",
+	"tool:cancelled": "child:tool:cancelled",
+	"background:start": "child:background:start",
+	"background:exit": "child:background:exit",
+	"background:reassign": "child:background:reassign",
 	"turn:after": "child:turn:after"
 };
 const CHILD_MUTABLE_EVENT_NAME = {
@@ -5146,7 +5657,7 @@ function createSpawnTool(options = {}) {
 				});
 				if (forwardHooks) {
 					const unregisterEnricher = agent.hooks.hook("tool:before", async (toolCtx) => {
-						if (toolCtx.name !== "write_file") return;
+						if (toolCtx.name !== "write_file" && toolCtx.name !== "edit" && toolCtx.name !== "multi_edit") return;
 						if (!agent.handle) return;
 						const inputPath = toolCtx.input?.path;
 						if (typeof inputPath !== "string") return;
@@ -5232,6 +5743,24 @@ function createSpawnTool(options = {}) {
 						});
 					}
 				} finally {
+					const childHandle = agent.handle;
+					if (childHandle && ctx.execution.reassignBackgroundTasks) try {
+						const reassigned = await ctx.execution.reassignBackgroundTasks(childHandle, ctx.handle, (info) => {
+							ctx.hooks.callHook("background:exit", info);
+						});
+						for (const entry of reassigned) await ctx.hooks.callHook("background:reassign", {
+							taskId: entry.taskId,
+							fromHandleId: childHandle.id,
+							toHandleId: ctx.handle.id,
+							childId: id,
+							pid: entry.pid,
+							command: entry.command,
+							outputPath: entry.outputPath,
+							startedAt: entry.startedAt
+						});
+					} catch (err) {
+						if (process.env.ZIDANE_DEBUG) process.stderr.write(`[zidane/spawn] reassignBackgroundTasks failed: ${err instanceof Error ? err.message : String(err)}\n`);
+					}
 					try {
 						await agent.destroy();
 					} catch (err) {
@@ -5321,6 +5850,6 @@ const writeFile$1 = {
 	}
 };
 //#endregion
-export { readStateKey as A, PERSISTENCE_PREVIEW_BYTES as C, resolvePersistDir as D, maybePersistToolResult as E, getReadState as O, PERSISTED_STUB_PREFIX as S, cleanupPersistedSession as T, createSkillsReadTool as _, multiEdit as a, TOOL_USE_SKIPPED_MESSAGE as b, grep as c, resolveOldString as d, styleReplacementForVia as f, createSkillsRunScriptTool as g, createSkillsUseTool as h, readFile$1 as i, resolveReadStateMap as j, hashContent as k, glob as l, createToolSearchTool as m, createSpawnTool as n, listFiles as o, createAgent as p, shell as r, createInteractionTool as s, writeFile$1 as t, edit as u, INTERRUPT_MESSAGE_FOR_TOOL_USE as v, buildPersistedStub as w, validateToolArgs as x, SHELL_CASCADE_CANCEL_MESSAGE as y };
+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-BNfyY14s.js.map
+//# sourceMappingURL=tools-D_icxa-V.js.map