zidane 4.0.2 → 4.1.4

package/dist/tools-DpeWKzP1.js

@@ -0,0 +1,3941 @@
+import { n as createProcessContext } from "./contexts-3Arvn7yR.js";
+import { r as AgentProviderError, s as toTypedError, t as AgentAbortedError } from "./errors-D1lhd6mX.js";
+import { t as toolOutputByteLength } from "./types-Bx_F8jet.js";
+import { t as connectMcpServers } from "./mcp-8wClKY-3.js";
+import { _ as validateResourcePath, b as createSkillActivationState, d as escapeXml, n as resolveSkills, p as installAllowedToolsGate, t as interpolateShellCommands, u as buildCatalog } from "./interpolate-CukJwP2G.js";
+import { t as flattenTurns } from "./stats-DoKUtF5T.js";
+import { createHooks } from "hookable";
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { Buffer } from "node:buffer";
+//#region src/aliasing.ts
+/**
+* Build alias lookup maps from a `toolAliases` record.
+*
+* Validates:
+* - No two canonical names map to the same alias (collision).
+* - No alias collides with another canonical tool name (would shadow).
+*
+* Silently ignores alias entries whose canonical name isn't in `canonicalNames` —
+* preset/agent authors can declare aliases for tools that may be added later via MCP.
+*
+* @param aliases - The `toolAliases` map from the agent options.
+* @param canonicalNames - All tool canonical names currently in scope (agent + MCP).
+*/
+function buildAliasMaps(aliases, canonicalNames) {
+	const aliasByCanonical = /* @__PURE__ */ new Map();
+	const canonicalByAlias = /* @__PURE__ */ new Map();
+	if (!aliases) return {
+		aliasByCanonical,
+		canonicalByAlias
+	};
+	const canonicalSet = new Set(canonicalNames);
+	function isRemappedAway(canonical) {
+		const mapped = aliases[canonical];
+		return typeof mapped === "string" && mapped.length > 0 && mapped !== canonical;
+	}
+	for (const [canonical, alias] of Object.entries(aliases)) {
+		if (typeof alias !== "string" || alias.length === 0) throw new Error(`Tool alias for "${canonical}" must be a non-empty string`);
+		if (alias === canonical) continue;
+		if (!canonicalSet.has(canonical)) continue;
+		if (canonicalSet.has(alias) && !isRemappedAway(alias)) throw new Error(`Tool alias "${canonical}" -> "${alias}" collides with an existing canonical tool name`);
+		const existingCanonical = canonicalByAlias.get(alias);
+		if (existingCanonical && existingCanonical !== canonical) throw new Error(`Tool alias collision: both "${existingCanonical}" and "${canonical}" map to alias "${alias}"`);
+		aliasByCanonical.set(canonical, alias);
+		canonicalByAlias.set(alias, canonical);
+	}
+	return {
+		aliasByCanonical,
+		canonicalByAlias
+	};
+}
+/** Return the alias for a canonical name, falling back to the canonical name itself. */
+function toWireName(canonical, maps) {
+	return maps.aliasByCanonical.get(canonical) ?? canonical;
+}
+/** Return the canonical name for a wire name, falling back to the wire name itself. */
+function toCanonicalName(wire, maps) {
+	return maps.canonicalByAlias.get(wire) ?? wire;
+}
+/**
+* Rewrite `tool_call` block names in a content array from canonical → wire for outbound
+* messages sent to the provider. Mutation is non-destructive (returns a new array).
+*/
+function rewriteContentToWire(content, maps) {
+	if (maps.aliasByCanonical.size === 0) return content;
+	return content.map((block) => {
+		if (block.type !== "tool_call") return block;
+		const wire = maps.aliasByCanonical.get(block.name);
+		if (!wire || wire === block.name) return block;
+		return {
+			...block,
+			name: wire
+		};
+	});
+}
+/**
+* Rewrite `tool_call` block names in a content array from wire → canonical for inbound
+* messages received from the provider. Non-destructive.
+*/
+function rewriteContentToCanonical(content, maps) {
+	if (maps.canonicalByAlias.size === 0) return content;
+	return content.map((block) => {
+		if (block.type !== "tool_call") return block;
+		const canonical = maps.canonicalByAlias.get(block.name);
+		if (!canonical || canonical === block.name) return block;
+		return {
+			...block,
+			name: canonical
+		};
+	});
+}
+/**
+* Rewrite every `SessionMessage.content` in an array from canonical → wire.
+* Returns a new array of new message objects — input messages are not mutated.
+* When the alias map is empty, returns the input by reference (no allocation).
+*/
+function rewriteMessagesToWire(messages, maps) {
+	if (maps.aliasByCanonical.size === 0) return messages;
+	return messages.map((msg) => ({
+		...msg,
+		content: rewriteContentToWire(msg.content, maps)
+	}));
+}
+//#endregion
+//#region src/tools/read-state.ts
+const STATE = /* @__PURE__ */ new WeakMap();
+/**
+* Get or lazily create the per-session read-state map. Returns `undefined`
+* when no session is provided — tools should treat that as "no dedup, no
+* guard": the state has nowhere to live, so every read is fresh.
+*/
+function getReadState(session) {
+	if (!session) return void 0;
+	let map = STATE.get(session);
+	if (!map) {
+		map = /* @__PURE__ */ new Map();
+		STATE.set(session, map);
+	}
+	return map;
+}
+const TOOL_DEDUP_STATE = /* @__PURE__ */ new WeakMap();
+/**
+* Get or lazily create the per-session tool-dedup map. Returns `undefined`
+* when no session is provided — middleware should treat that as "no dedup".
+*/
+function getToolDedupState(session) {
+	if (!session) return void 0;
+	let map = TOOL_DEDUP_STATE.get(session);
+	if (!map) {
+		map = /* @__PURE__ */ new Map();
+		TOOL_DEDUP_STATE.set(session, map);
+	}
+	return map;
+}
+/**
+* FNV-1a 32-bit hash, hex-encoded. Fast, non-cryptographic — we only need
+* collision resistance against accidental matches between different file
+* contents within one session (~1 in 4 billion). Cheaper than allocating
+* a Buffer and pulling in `crypto`.
+*/
+function hashContent(text) {
+	let h = 2166136261;
+	for (let i = 0; i < text.length; i++) {
+		h ^= text.charCodeAt(i);
+		h = h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)) >>> 0;
+	}
+	return h.toString(16).padStart(8, "0");
+}
+//#endregion
+//#region src/dedup-tools.ts
+/**
+* Install the per-tool argument-dedup middleware on a hook bus.
+* `getDedupTools` returns the resolved per-tool hashers (run override merged
+* with agent defaults). `getSession` does the same for the session-bound
+* state. Both are called lazily so handlers attached after install (e.g. via
+* MCP bootstrap completion) can take effect.
+*
+* Returns an `uninstall` fn — the agent calls this in `finally` so handlers
+* never leak across runs.
+*/
+function installDedupToolsGate(hooks, getDedupTools, getSession) {
+	const pending = /* @__PURE__ */ new Map();
+	function pendingKey(callId, name) {
+		return `${callId}::${name}`;
+	}
+	function gateHandler(ctx) {
+		if (ctx.block || ctx.result !== void 0) return;
+		const hasher = getDedupTools()?.[ctx.name];
+		if (!hasher) return;
+		const state = getToolDedupState(getSession());
+		if (!state) return;
+		let hash;
+		try {
+			hash = hasher(ctx.input);
+		} catch {
+			return;
+		}
+		if (typeof hash !== "string" || hash.length === 0) return;
+		const prior = state.get(ctx.name);
+		if (prior && prior.hash === hash) {
+			ctx.result = prior.result;
+			return;
+		}
+		pending.set(pendingKey(ctx.callId, ctx.name), hash);
+	}
+	function afterHandler(ctx) {
+		const key = pendingKey(ctx.callId, ctx.name);
+		const hash = pending.get(key);
+		if (hash === void 0) return;
+		pending.delete(key);
+		const state = getToolDedupState(getSession());
+		if (!state) return;
+		state.set(ctx.name, {
+			hash,
+			result: ctx.result
+		});
+	}
+	const unregisterGate = hooks.hook("tool:gate", gateHandler);
+	const unregisterAfter = hooks.hook("tool:after", afterHandler);
+	return function uninstall() {
+		unregisterGate();
+		unregisterAfter();
+		pending.clear();
+	};
+}
+//#endregion
+//#region src/tools/validation.ts
+const TRUE_STRINGS = new Set([
+	"true",
+	"True",
+	"TRUE",
+	"1",
+	"yes",
+	"Yes",
+	"YES"
+]);
+const FALSE_STRINGS = new Set([
+	"false",
+	"False",
+	"FALSE",
+	"0",
+	"no",
+	"No",
+	"NO"
+]);
+function validateToolArgs(input, schema) {
+	const required = schema.required ?? [];
+	const properties = schema.properties ?? {};
+	for (const field of required) if (!(field in input) || input[field] === void 0 || input[field] === null) return {
+		valid: false,
+		error: `Missing required field: ${field}`
+	};
+	let coerced;
+	const coercions = [];
+	for (const [key, value] of Object.entries(input)) {
+		const propSchema = properties[key];
+		if (!propSchema?.type) continue;
+		if (value === void 0 || value === null) continue;
+		const outcome = coerceValue(value, propSchema);
+		if (outcome.error) return {
+			valid: false,
+			error: `Field "${key}": ${outcome.error}`
+		};
+		if (outcome.changed) {
+			if (!coerced) coerced = { ...input };
+			coerced[key] = outcome.value;
+			coercions.push(key);
+		}
+	}
+	return {
+		valid: true,
+		coercedInput: coerced ?? input,
+		coercions
+	};
+}
+function coerceValue(value, schema) {
+	const declaredTypes = Array.isArray(schema.type) ? schema.type : [schema.type];
+	for (const t of declaredTypes) if (matchesType(value, t)) {
+		if (schema.enum && !schema.enum.includes(value)) return {
+			value,
+			changed: false,
+			error: `must be one of ${JSON.stringify(schema.enum)}, got ${formatValue(value)}`
+		};
+		return {
+			value,
+			changed: false
+		};
+	}
+	for (const t of declaredTypes) {
+		const coerced = tryCoerce(value, t);
+		if (coerced.ok) {
+			if (schema.enum && !schema.enum.includes(coerced.value)) return {
+				value,
+				changed: false,
+				error: `must be one of ${JSON.stringify(schema.enum)}, got ${formatValue(coerced.value)}`
+			};
+			return {
+				value: coerced.value,
+				changed: true
+			};
+		}
+	}
+	return {
+		value,
+		changed: false,
+		error: `expected ${declaredTypes.join(" | ")}, got ${jsonType(value)} ${formatValue(value)}`
+	};
+}
+function matchesType(value, type) {
+	switch (type) {
+		case "string": return typeof value === "string";
+		case "number": return typeof value === "number" && Number.isFinite(value);
+		case "integer": return typeof value === "number" && Number.isInteger(value);
+		case "boolean": return typeof value === "boolean";
+		case "array": return Array.isArray(value);
+		case "object": return value !== null && typeof value === "object" && !Array.isArray(value);
+		case "null": return value === null;
+		default: return true;
+	}
+}
+function tryCoerce(value, type) {
+	if (typeof value === "string") {
+		if (type === "boolean") {
+			const trimmed = value.trim();
+			if (TRUE_STRINGS.has(trimmed)) return {
+				ok: true,
+				value: true
+			};
+			if (FALSE_STRINGS.has(trimmed)) return {
+				ok: true,
+				value: false
+			};
+			return { ok: false };
+		}
+		if (type === "number") {
+			const n = Number(value.trim());
+			return Number.isFinite(n) ? {
+				ok: true,
+				value: n
+			} : { ok: false };
+		}
+		if (type === "integer") {
+			const n = Number(value.trim());
+			return Number.isInteger(n) ? {
+				ok: true,
+				value: n
+			} : { ok: false };
+		}
+		if (type === "array" || type === "object") try {
+			const parsed = JSON.parse(value);
+			if (type === "array" && Array.isArray(parsed)) return {
+				ok: true,
+				value: parsed
+			};
+			if (type === "object" && parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) return {
+				ok: true,
+				value: parsed
+			};
+			return { ok: false };
+		} catch {
+			return { ok: false };
+		}
+		if (type === "null") return value === "" || value === "null" ? {
+			ok: true,
+			value: null
+		} : { ok: false };
+	}
+	if (typeof value === "number" && Number.isFinite(value)) {
+		if (type === "string") return {
+			ok: true,
+			value: String(value)
+		};
+		if (type === "integer" && Number.isInteger(value)) return {
+			ok: true,
+			value
+		};
+	}
+	if (typeof value === "boolean" && type === "string") return {
+		ok: true,
+		value: String(value)
+	};
+	return { ok: false };
+}
+function jsonType(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+function formatValue(value) {
+	let s;
+	try {
+		s = JSON.stringify(value);
+	} catch {
+		s = String(value);
+	}
+	if (s === void 0) s = String(value);
+	return s.length > 80 ? `${s.slice(0, 77)}...` : s;
+}
+//#endregion
+//#region src/loop.ts
+const IMAGE_OMITTED_MARKER = "[image omitted — model does not support vision]";
+/**
+* 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.
+*
+* - No `baseBudget` → returns `undefined`. Decay never invents a budget.
+* - No `decay` → identity (`baseBudget`).
+* - Function form → `decay(turn, baseBudget)`. The return is clamped to
+*   `[0, baseBudget]` so a buggy curve can't request *more* budget than the
+*   caller explicitly opted into.
+* - Struct form `{ afterTurn, factor, floor }` → for `turn <= afterTurn`,
+*   returns `baseBudget`. For `turn > afterTurn`, returns
+*   `max(floor, baseBudget * factor^(turn - afterTurn))` clamped to
+*   `[floor, baseBudget]`.
+*
+* Result is rounded to the nearest integer (token counts are integers).
+*/
+function applyThinkingDecay(baseBudget, decay, turn) {
+	if (typeof baseBudget !== "number" || baseBudget <= 0) return baseBudget;
+	if (!decay) return baseBudget;
+	let raw;
+	if (typeof decay === "function") raw = decay(turn, baseBudget);
+	else {
+		if (turn <= decay.afterTurn) return baseBudget;
+		const k = turn - decay.afterTurn;
+		raw = Math.max(decay.floor, baseBudget * decay.factor ** k);
+	}
+	if (Number.isNaN(raw) || raw <= 0) return 0;
+	return Math.round(Math.min(baseBudget, raw));
+}
+/** Convert turns to the SessionMessage[] format expected by providers */
+function turnsToMessages(turns) {
+	return turns.filter((t) => t.role !== "system").map((t) => ({
+		role: t.role,
+		content: t.content
+	}));
+}
+/**
+* Flatten image blocks inside previously-stored `tool_result` outputs to text
+* markers when the provider reports no vision capability. This handles the
+* session-resume / mid-session-provider-switch case:
+*
+* - A session was produced with a vision-capable provider (e.g. Claude) and
+*   contains structured tool_result content with images.
+* - The agent resumes with a text-only provider (e.g. Cerebras).
+* - Without this pass, the persisted image blocks would re-encode via the
+*   provider's wire format and leak base64 payloads into a non-vision model's
+*   context.
+*
+* Scope: stored tool_result outputs only. User-authored image blocks are left
+* alone — those are consumer-controlled and the consumer is responsible for
+* matching prompt parts to the provider's capabilities.
+*/
+const COMPACTION_STUB = "[…elided by client-side tail compaction; ask the user or re-run the tool to retrieve.]";
+/**
+* Tail-compaction for non-Anthropic providers: when the cumulative byte size
+* of `tool_result` content across the wire-level message list exceeds
+* `threshold`, replace older `tool_result` outputs with a short stub. The
+* newest `keepTurns` messages (user/assistant alike) are left untouched so
+* the model retains the freshest tool context.
+*
+* Only `tool_result` blocks are touched — text and image blocks pass through
+* unchanged. Mutates a shallow-cloned message array; original `messages` is
+* not modified.
+*
+* For Anthropic users, prefer the server-side `context-management-2025-06-27`
+* beta (token-accurate, no client-side approximation). This function is the
+* client-side fallback for OpenAI-compatible / OpenRouter / Cerebras runs
+* against OSS models that lack a server-side equivalent.
+*/
+function applyTailCompaction(messages, threshold, keepTurns) {
+	if (messages.length === 0) return messages;
+	let totalBytes = 0;
+	for (const msg of messages) for (const block of msg.content) if (block.type === "tool_result") totalBytes += toolOutputByteLength(block.output);
+	if (totalBytes <= threshold) return messages;
+	const keep = Math.max(0, keepTurns);
+	const cutoff = messages.length - keep;
+	if (cutoff <= 0) return messages;
+	let changed = false;
+	const out = messages.slice();
+	for (let i = 0; i < cutoff; i++) {
+		const msg = out[i];
+		let msgChanged = false;
+		const newContent = msg.content.map((block) => {
+			if (block.type !== "tool_result") return block;
+			if (toolOutputByteLength(block.output) <= 86) return block;
+			msgChanged = true;
+			changed = true;
+			return {
+				...block,
+				output: COMPACTION_STUB
+			};
+		});
+		if (msgChanged) out[i] = {
+			...msg,
+			content: newContent
+		};
+	}
+	return changed ? out : messages;
+}
+/**
+* Replace `read_file` `tool_result` blocks with a short stub when a later
+* successful `edit` / `multi_edit` / `write_file` modified the same path.
+*
+* Eliminates the common waste pattern where the model carries the pre-edit
+* file body forward across many turns. Operates on the wire-level message
+* list only — the persisted session keeps the original content.
+*
+* Detection is conservative: success is gated on the corresponding
+* tool_result starting with `Edited ` (edit / multi_edit) or `Created ` /
+* `Updated ` (write_file). Failed edits and `No change needed` writes do
+* NOT invalidate prior reads — the file content is still what the read
+* returned.
+*
+* Pure function, exported for tests and so downstream tooling can preview
+* elision without spinning up the loop.
+*/
+const STALE_READ_STUB = "[…elided: file edited later in this run; re-read if still needed.]";
+function applyStaleReadElision(messages) {
+	if (messages.length === 0) return messages;
+	const resultByCallId = /* @__PURE__ */ new Map();
+	for (const msg of messages) for (const block of msg.content) if (block.type === "tool_result" && typeof block.output === "string") resultByCallId.set(block.callId, block.output);
+	const maxMutationIdxByPath = /* @__PURE__ */ new Map();
+	const readCallInfo = /* @__PURE__ */ new Map();
+	for (let i = 0; i < messages.length; i++) for (const block of messages[i].content) {
+		if (block.type !== "tool_call") continue;
+		const path = block.input.path;
+		if (typeof path !== "string") continue;
+		if (block.name === "read_file") {
+			readCallInfo.set(block.id, {
+				path,
+				msgIdx: i
+			});
+			continue;
+		}
+		const isEdit = block.name === "edit" || block.name === "multi_edit";
+		const isWrite = block.name === "write_file";
+		if (!isEdit && !isWrite) continue;
+		const result = resultByCallId.get(block.id);
+		if (typeof result !== "string") continue;
+		if (!(isEdit ? result.startsWith("Edited ") : result.startsWith("Created ") || result.startsWith("Updated "))) continue;
+		const prior = maxMutationIdxByPath.get(path);
+		if (prior === void 0 || i > prior) maxMutationIdxByPath.set(path, i);
+	}
+	if (maxMutationIdxByPath.size === 0) return messages;
+	const staleCallIds = /* @__PURE__ */ new Set();
+	for (const [callId, info] of readCallInfo) {
+		const lastMutationIdx = maxMutationIdxByPath.get(info.path);
+		if (typeof lastMutationIdx === "number" && info.msgIdx < lastMutationIdx) staleCallIds.add(callId);
+	}
+	if (staleCallIds.size === 0) return messages;
+	let changed = false;
+	const out = messages.slice();
+	for (let i = 0; i < out.length; i++) {
+		const msg = out[i];
+		let msgChanged = false;
+		const newContent = msg.content.map((block) => {
+			if (block.type !== "tool_result" || !staleCallIds.has(block.callId)) return block;
+			if (block.output === "[…elided: file edited later in this run; re-read if still needed.]") return block;
+			msgChanged = true;
+			changed = true;
+			return {
+				...block,
+				output: STALE_READ_STUB
+			};
+		});
+		if (msgChanged) out[i] = {
+			...msg,
+			content: newContent
+		};
+	}
+	return changed ? out : messages;
+}
+function sanitizeStoredToolResults(provider, messages) {
+	if (provider.meta.capabilities?.vision !== false) return messages;
+	return messages.map((msg) => {
+		let changed = false;
+		const newContent = msg.content.map((block) => {
+			if (block.type !== "tool_result" || typeof block.output === "string") return block;
+			changed = true;
+			const flattened = block.output.map((b) => b.type === "image" ? IMAGE_OMITTED_MARKER : b.text).join("\n");
+			return {
+				...block,
+				output: flattened
+			};
+		});
+		return changed ? {
+			...msg,
+			content: newContent
+		} : msg;
+	});
+}
+async function runLoop(ctx) {
+	let totalIn = 0;
+	let totalOut = 0;
+	let totalCacheRead = 0;
+	let totalCacheCreation = 0;
+	const turnUsages = [];
+	const startTime = Date.now();
+	const maxTurns = ctx.maxTurns ?? Number.POSITIVE_INFINITY;
+	let turnsCompleted = 0;
+	const ttft = { mark: void 0 };
+	const markTtft = () => {
+		if (ttft.mark === void 0) ttft.mark = Date.now() - ctx.runStartMs;
+	};
+	const unregisterTtftText = ctx.hooks.hook("stream:text", markTtft);
+	const unregisterTtftThinking = ctx.hooks.hook("stream:thinking", markTtft);
+	const unregisterTtftTool = ctx.hooks.hook("tool:before", markTtft);
+	try {
+		for (let turn = 0; turn < maxTurns; turn++) {
+			if (ctx.signal.aborted) {
+				await ctx.hooks.callHook("agent:abort", {});
+				break;
+			}
+			const result = await executeTurn(ctx, turn);
+			turnsCompleted = turn + 1;
+			totalIn += result.usage.input;
+			totalOut += result.usage.output;
+			totalCacheRead += result.usage.cacheRead ?? 0;
+			totalCacheCreation += result.usage.cacheCreation ?? 0;
+			turnUsages.push(result.usage);
+			await ctx.hooks.callHook("usage", {
+				turn,
+				turnId: result.turnId,
+				usage: result.usage,
+				totalIn,
+				totalOut
+			});
+			if (ctx.signal.aborted) {
+				await ctx.hooks.callHook("agent:abort", {});
+				break;
+			}
+			if (ctx.steeringQueue.length > 0) {
+				const steerMsg = ctx.steeringQueue.shift();
+				await ctx.hooks.callHook("steer:inject", { message: steerMsg });
+				const steerUserMsg = ctx.provider.userMessage(steerMsg);
+				ctx.turns.push({
+					id: await ctx.generateTurnId(),
+					runId: ctx.runId,
+					role: steerUserMsg.role,
+					content: steerUserMsg.content,
+					createdAt: Date.now()
+				});
+				continue;
+			}
+			if (result.ended) {
+				if (ctx.followUpQueue.length > 0) {
+					const followUp = ctx.followUpQueue.shift();
+					await ctx.hooks.callHook("steer:inject", { message: followUp });
+					const followUpMsg = ctx.provider.userMessage(followUp);
+					ctx.turns.push({
+						id: await ctx.generateTurnId(),
+						runId: ctx.runId,
+						role: followUpMsg.role,
+						content: followUpMsg.content,
+						createdAt: Date.now()
+					});
+					continue;
+				}
+				return {
+					totalIn,
+					totalOut,
+					totalCacheRead,
+					totalCacheCreation,
+					turns: turn + 1,
+					elapsed: Date.now() - startTime,
+					turnUsage: turnUsages,
+					output: result.output,
+					...ttft.mark !== void 0 ? { timeTillFirstTokenMs: ttft.mark } : {}
+				};
+			}
+		}
+		return {
+			totalIn,
+			totalOut,
+			totalCacheRead,
+			totalCacheCreation,
+			turns: turnsCompleted,
+			elapsed: Date.now() - startTime,
+			turnUsage: turnUsages,
+			...ttft.mark !== void 0 ? { timeTillFirstTokenMs: ttft.mark } : {}
+		};
+	} finally {
+		unregisterTtftText();
+		unregisterTtftThinking();
+		unregisterTtftTool();
+	}
+}
+/**
+* Wrap a caught provider error in the matching typed error class.
+*
+* Uses the provider's `classifyError` seam when implemented; otherwise falls back
+* to wrapping in `AgentProviderError`. Abort signals always produce `AgentAbortedError`
+* regardless of the provider classification.
+*/
+function wrapProviderError(err, ctx) {
+	if (ctx.signal.aborted || err instanceof Error && err.name === "AbortError") return new AgentAbortedError("Agent run aborted", { cause: err });
+	const classification = ctx.provider.classifyError?.(err);
+	if (classification) return toTypedError(classification, ctx.provider.name, err);
+	return new AgentProviderError(err instanceof Error ? err.message : String(err), {
+		provider: ctx.provider.name,
+		cause: err
+	});
+}
+async function executeTurn(ctx, turn) {
+	const turnId = await ctx.generateTurnId();
+	let canonicalMessages = turnsToMessages(ctx.turns);
+	if (ctx.elideStaleReads === true) canonicalMessages = applyStaleReadElision(canonicalMessages);
+	const wireMessages = rewriteMessagesToWire(canonicalMessages, ctx.aliasMaps);
+	let sanitizedMessages = sanitizeStoredToolResults(ctx.provider, wireMessages);
+	if (ctx.compactStrategy === "tail") {
+		const threshold = typeof ctx.compactThreshold === "number" && ctx.compactThreshold > 0 ? ctx.compactThreshold : 131072;
+		const keep = typeof ctx.compactKeepTurns === "number" && ctx.compactKeepTurns >= 0 ? ctx.compactKeepTurns : 4;
+		sanitizedMessages = applyTailCompaction(sanitizedMessages, threshold, keep);
+	}
+	const effectiveThinkingBudget = applyThinkingDecay(ctx.thinkingBudget, ctx.thinkingDecay, turn);
+	const formattedTools = ctx.rebuildFormattedTools ? ctx.rebuildFormattedTools() : ctx.formattedTools;
+	const streamOptions = {
+		model: ctx.model,
+		system: ctx.system,
+		tools: formattedTools,
+		messages: sanitizedMessages,
+		maxTokens: ctx.maxTokens ?? 16384,
+		thinking: ctx.thinking,
+		thinkingBudget: effectiveThinkingBudget,
+		cache: ctx.cache ?? true,
+		signal: ctx.signal
+	};
+	const transformCtx = { messages: streamOptions.messages };
+	await ctx.hooks.callHook("context:transform", transformCtx);
+	streamOptions.messages = transformCtx.messages;
+	const systemCtx = {
+		system: streamOptions.system,
+		messages: streamOptions.messages,
+		turn,
+		turnId,
+		...ctx.session ? { session: ctx.session } : {}
+	};
+	await ctx.hooks.callHook("system:transform", systemCtx);
+	streamOptions.system = systemCtx.system;
+	await ctx.hooks.callHook("turn:before", {
+		turn,
+		turnId,
+		options: streamOptions
+	});
+	let currentText = "";
+	let currentThinking = "";
+	let result;
+	try {
+		result = await ctx.provider.stream(streamOptions, {
+			onText(delta) {
+				currentText += delta;
+				ctx.hooks.callHook("stream:text", {
+					delta,
+					text: currentText,
+					turnId
+				});
+			},
+			onThinking(delta) {
+				currentThinking += delta;
+				ctx.hooks.callHook("stream:thinking", {
+					delta,
+					thinking: currentThinking,
+					turnId
+				});
+			},
+			onOAuthRefresh(refreshCtx) {
+				return ctx.hooks.callHook("oauth:refresh", refreshCtx);
+			}
+		});
+	} catch (err) {
+		const errorUsage = {
+			input: 0,
+			output: 0
+		};
+		const errorContent = currentText ? [{
+			type: "text",
+			text: currentText
+		}] : [{
+			type: "text",
+			text: "[provider error before any output]"
+		}];
+		const errorTurn = {
+			id: turnId,
+			runId: ctx.runId,
+			role: "assistant",
+			content: errorContent,
+			usage: errorUsage,
+			createdAt: Date.now()
+		};
+		ctx.turns.push(errorTurn);
+		await ctx.hooks.callHook("turn:after", {
+			turn,
+			turnId,
+			usage: errorUsage,
+			message: errorTurn,
+			toolCounts: {
+				turn: Object.freeze({}),
+				run: Object.freeze({ ...ctx.runToolCounts })
+			}
+		});
+		throw wrapProviderError(err, ctx);
+	}
+	if (currentText) await ctx.hooks.callHook("stream:end", {
+		text: currentText,
+		turnId
+	});
+	const canonicalToolCalls = result.toolCalls.map((tc) => ({
+		...tc,
+		name: toCanonicalName(tc.name, ctx.aliasMaps)
+	}));
+	const canonicalContent = rewriteContentToCanonical(result.assistantMessage?.content ?? [], ctx.aliasMaps);
+	const assistantTurn = {
+		id: turnId,
+		runId: ctx.runId,
+		role: "assistant",
+		content: result.done ? canonicalContent.length > 0 ? canonicalContent : [{
+			type: "text",
+			text: currentText
+		}] : canonicalContent,
+		usage: result.usage,
+		createdAt: Date.now()
+	};
+	ctx.turns.push(assistantTurn);
+	const turnCounts = {};
+	for (const tc of canonicalToolCalls) turnCounts[tc.name] = (turnCounts[tc.name] ?? 0) + 1;
+	await ctx.hooks.callHook("turn:after", {
+		turn,
+		turnId,
+		usage: result.usage,
+		message: assistantTurn,
+		toolCounts: {
+			turn: Object.freeze(turnCounts),
+			run: Object.freeze({ ...ctx.runToolCounts })
+		}
+	});
+	if (result.done) {
+		if (ctx.schema && !ctx.signal.aborted) {
+			const outputSpec = {
+				name: "__output__",
+				description: "Return the final structured output matching the required schema.",
+				inputSchema: ctx.schema
+			};
+			const schemaMessages = rewriteMessagesToWire(turnsToMessages(ctx.turns), ctx.aliasMaps);
+			let schemaResult;
+			try {
+				schemaResult = await ctx.provider.stream({
+					model: ctx.model,
+					system: ctx.system,
+					tools: ctx.provider.formatTools([outputSpec]),
+					messages: schemaMessages,
+					maxTokens: ctx.maxTokens ?? 16384,
+					signal: ctx.signal,
+					toolChoice: {
+						type: "tool",
+						name: "__output__"
+					}
+				}, {
+					onText: () => {},
+					onOAuthRefresh(refreshCtx) {
+						return ctx.hooks.callHook("oauth:refresh", refreshCtx);
+					}
+				});
+			} catch (err) {
+				throw wrapProviderError(err, ctx);
+			}
+			const output = schemaResult.toolCalls.find((tc) => tc.name === "__output__")?.input;
+			if (output) await ctx.hooks.callHook("output", {
+				output,
+				schema: ctx.schema
+			});
+			const schemaTurn = {
+				id: await ctx.generateTurnId(),
+				runId: ctx.runId,
+				role: "assistant",
+				content: schemaResult.assistantMessage.content,
+				usage: schemaResult.usage,
+				createdAt: Date.now()
+			};
+			ctx.turns.push(schemaTurn);
+			return {
+				ended: true,
+				turnId,
+				usage: {
+					input: result.usage.input + schemaResult.usage.input,
+					output: result.usage.output + schemaResult.usage.output
+				},
+				output
+			};
+		}
+		return {
+			ended: true,
+			turnId,
+			usage: result.usage
+		};
+	}
+	if (canonicalToolCalls.length === 0 && result.usage.finishReason === "pause") {
+		const continueMsg = ctx.provider.userMessage("Please continue.");
+		ctx.turns.push({
+			id: await ctx.generateTurnId(),
+			runId: ctx.runId,
+			role: continueMsg.role,
+			content: continueMsg.content,
+			createdAt: Date.now()
+		});
+		return {
+			ended: false,
+			turnId,
+			usage: result.usage
+		};
+	}
+	const toolResults = ctx.toolExecution === "parallel" ? await executeToolsParallel(ctx, canonicalToolCalls, turnId) : await executeToolsSequential(ctx, canonicalToolCalls, turnId);
+	const toolResultMsg = ctx.provider.toolResultsMessage(toolResults);
+	ctx.turns.push({
+		id: await ctx.generateTurnId(),
+		runId: ctx.runId,
+		role: toolResultMsg.role,
+		content: toolResultMsg.content,
+		createdAt: Date.now()
+	});
+	if (typeof ctx.toolOutputBudget === "number" && ctx.toolOutputBudget > 0) {
+		const totalBytes = toolResults.reduce((sum, r) => sum + toolOutputByteLength(r.content), 0);
+		if (totalBytes > ctx.toolOutputBudget) {
+			const warning = `[Tool output budget exceeded: ${totalBytes} bytes returned in this turn (cap: ${ctx.toolOutputBudget}). Summarize the salient findings before calling more tools.]`;
+			const userMsg = ctx.provider.userMessage(warning);
+			ctx.turns.push({
+				id: await ctx.generateTurnId(),
+				runId: ctx.runId,
+				role: userMsg.role,
+				content: userMsg.content,
+				createdAt: Date.now()
+			});
+			await ctx.hooks.callHook("budget:exceeded", {
+				turn,
+				turnId,
+				bytes: totalBytes,
+				budget: ctx.toolOutputBudget
+			});
+		}
+	}
+	return {
+		ended: false,
+		turnId,
+		usage: result.usage
+	};
+}
+/**
+* Strip image blocks from a tool output when the provider is not vision-capable.
+* Each image is replaced with a short text marker so the model sees an honest
+* "no image" signal instead of JSON-stringified base64 it might confabulate over.
+*
+* Returns the output unchanged when:
+* - The provider reports `capabilities.vision: true` (native routing handles it),
+* - The provider omits `capabilities` entirely (we default to vision-capable
+*   so third-party providers without the field aren't penalized),
+* - The output is a plain string (no image blocks to strip).
+*
+* With the current `text | image` union, replacing every image with a text marker
+* leaves an all-text array — collapse to a plain string to keep the downstream wire
+* shape as narrow as possible.
+*/
+function stripImagesForNonVision(provider, output) {
+	if (typeof output === "string") return output;
+	if (provider.meta.capabilities?.vision !== false) return output;
+	return output.map((b) => b.type === "image" ? IMAGE_OMITTED_MARKER : b.text).join("\n");
+}
+async function executeSingleTool(ctx, call, turnId) {
+	const toolDef = ctx.tools[call.name];
+	const callId = call.id;
+	const displayName = toWireName(call.name, ctx.aliasMaps);
+	const runToolCounts = Object.freeze({ ...ctx.runToolCounts });
+	const gateCtx = {
+		turnId,
+		callId,
+		name: call.name,
+		displayName,
+		input: call.input,
+		block: false,
+		reason: "Tool execution was blocked",
+		runToolCounts
+	};
+	await ctx.hooks.callHook("tool:gate", gateCtx);
+	if (gateCtx.block) return { result: {
+		id: callId,
+		content: `Blocked: ${gateCtx.reason}`
+	} };
+	ctx.runToolCounts[call.name] = (ctx.runToolCounts[call.name] ?? 0) + 1;
+	if (gateCtx.result !== void 0) return { result: {
+		id: callId,
+		content: await emitToolResult(ctx, {
+			turnId,
+			callId,
+			name: call.name,
+			displayName,
+			input: gateCtx.input,
+			output: gateCtx.result,
+			isError: false,
+			runToolCounts
+		})
+	} };
+	let effectiveInput = gateCtx.input;
+	if (!toolDef) {
+		const unknownCtx = {
+			turnId,
+			callId,
+			name: call.name,
+			displayName,
+			input: effectiveInput,
+			suppressError: false
+		};
+		await ctx.hooks.callHook("tool:unknown", unknownCtx);
+		const content = unknownCtx.result ?? `Tool error: Unknown tool: ${call.name}`;
+		if (!unknownCtx.suppressError) {
+			const err = /* @__PURE__ */ new Error(`Unknown tool: ${call.name}`);
+			await ctx.hooks.callHook("tool:error", {
+				turnId,
+				callId,
+				name: call.name,
+				displayName,
+				input: effectiveInput,
+				error: err
+			});
+		}
+		return { result: {
+			id: callId,
+			content
+		} };
+	}
+	const validation = validateToolArgs(effectiveInput, toolDef.spec.inputSchema);
+	if (!validation.valid) {
+		await ctx.hooks.callHook("validation:reject", {
+			turnId,
+			callId,
+			name: call.name,
+			displayName,
+			input: effectiveInput,
+			reason: validation.error ?? "invalid input",
+			schema: toolDef.spec.inputSchema
+		});
+		return { result: {
+			id: callId,
+			content: `Validation error: ${validation.error}`
+		} };
+	}
+	effectiveInput = validation.coercedInput ?? effectiveInput;
+	const coercions = validation.coercions && validation.coercions.length > 0 ? validation.coercions : void 0;
+	if (coercions) await ctx.hooks.callHook("validation:coerce", {
+		turnId,
+		callId,
+		name: call.name,
+		displayName,
+		input: effectiveInput,
+		coercions,
+		schema: toolDef.spec.inputSchema
+	});
+	await ctx.hooks.callHook("tool:before", {
+		turnId,
+		callId,
+		name: call.name,
+		displayName,
+		input: effectiveInput,
+		runToolCounts,
+		...coercions ? { coercions } : {}
+	});
+	let output;
+	let isError = false;
+	try {
+		const toolCtx = {
+			provider: ctx.provider,
+			signal: ctx.signal,
+			execution: ctx.execution,
+			handle: ctx.handle,
+			hooks: ctx.hooks,
+			tools: ctx.agentTools,
+			...ctx.agentName !== void 0 ? { name: ctx.agentName } : {},
+			...ctx.agentSystem !== void 0 ? { system: ctx.agentSystem } : {},
+			...ctx.agentToolAliases !== void 0 ? { toolAliases: ctx.agentToolAliases } : {},
+			...ctx.agentMcpServers !== void 0 ? { mcpServers: ctx.agentMcpServers } : {},
+			...ctx.agentSkills !== void 0 ? { skills: ctx.agentSkills } : {},
+			...ctx.agentBehavior !== void 0 ? { behavior: ctx.agentBehavior } : {},
+			turnId,
+			callId,
+			runId: ctx.runId,
+			...ctx.session ? { session: ctx.session } : {},
+			...typeof ctx.depth === "number" ? { depth: ctx.depth } : {}
+		};
+		output = await toolDef.execute(effectiveInput, toolCtx);
+	} catch (err) {
+		const error = err instanceof Error ? err : new Error(String(err));
+		const errorCtx = {
+			turnId,
+			callId,
+			name: call.name,
+			displayName,
+			input: effectiveInput,
+			error
+		};
+		await ctx.hooks.callHook("tool:error", errorCtx);
+		output = errorCtx.result ?? `Tool error: ${error.message}`;
+		isError = true;
+	}
+	return { result: {
+		id: callId,
+		content: await emitToolResult(ctx, {
+			turnId,
+			callId,
+			name: call.name,
+			displayName,
+			input: effectiveInput,
+			output,
+			isError,
+			runToolCounts,
+			...coercions ? { coercions } : {}
+		})
+	} };
+}
+/**
+* Shared post-output emission: fire `tool:transform` (mutate-allowed), strip
+* images for non-vision providers, fire `tool:after`. Used by both the
+* gate-substitute (Z20) and post-execute paths so they stay byte-for-byte
+* identical from the consumer's perspective.
+*/
+async function emitToolResult(ctx, params) {
+	const { turnId, callId, name, displayName, input, runToolCounts, coercions } = params;
+	let output = params.output;
+	let isError = params.isError;
+	const transformCtx = {
+		turnId,
+		callId,
+		name,
+		displayName,
+		input,
+		result: output,
+		isError,
+		outputBytes: toolOutputByteLength(output),
+		...coercions ? { coercions } : {}
+	};
+	await ctx.hooks.callHook("tool:transform", transformCtx);
+	output = transformCtx.result;
+	isError = transformCtx.isError;
+	output = stripImagesForNonVision(ctx.provider, output);
+	await ctx.hooks.callHook("tool:after", {
+		turnId,
+		callId,
+		name,
+		displayName,
+		input,
+		result: output,
+		outputBytes: toolOutputByteLength(output),
+		runToolCounts,
+		...coercions ? { coercions } : {}
+	});
+	return output;
+}
+async function executeToolsSequential(ctx, toolCalls, turnId) {
+	const results = [];
+	for (const call of toolCalls) {
+		if (ctx.signal.aborted) break;
+		if (ctx.steeringQueue.length > 0) {
+			const fromIdx = toolCalls.indexOf(call);
+			for (let i = fromIdx; i < toolCalls.length; i++) results.push({
+				id: toolCalls[i].id,
+				content: "Skipped: steering message received"
+			});
+			return results;
+		}
+		const { result } = await executeSingleTool(ctx, call, turnId);
+		results.push(result);
+	}
+	return results;
+}
+async function executeToolsParallel(ctx, toolCalls, turnId) {
+	const executions = toolCalls.map((call) => executeSingleTool(ctx, call, turnId));
+	return (await Promise.allSettled(executions)).map((s, i) => {
+		if (s.status === "fulfilled") return s.value.result;
+		return {
+			id: toolCalls[i].id,
+			content: `Error: ${s.reason instanceof Error ? s.reason.message : String(s.reason)}`
+		};
+	});
+}
+//#endregion
+//#region src/prompt.ts
+/**
+* Coerce the run-level prompt into a `PromptPart[]`.
+*
+* - `string` prompt → a single `text` part. Empty string returns `undefined`
+*   so callers skip pushing an empty user turn.
+* - `PromptPart[]` prompt → validated and returned as-is. An empty array, or
+*   an array whose text parts are all empty with no image/document parts,
+*   returns `undefined`.
+* - `undefined` → `undefined` (promptless resume path).
+*/
+function canonicalizePrompt(prompt) {
+	if (prompt === void 0) return void 0;
+	if (typeof prompt === "string") {
+		if (prompt.length === 0) return void 0;
+		return [{
+			type: "text",
+			text: prompt
+		}];
+	}
+	if (prompt.length === 0) return void 0;
+	for (const part of prompt) {
+		if (!part || typeof part !== "object" || typeof part.type !== "string") throw new Error("Invalid PromptPart: each part must be an object with a `type` field.");
+		const type = part.type;
+		if (type !== "text" && type !== "image" && type !== "document") throw new Error(`Invalid PromptPart type "${type}". Expected "text" | "image" | "document".`);
+	}
+	if (!prompt.some((part) => part.type === "text" && part.text.length > 0 || part.type === "image" || part.type === "document")) return void 0;
+	return prompt;
+}
+/**
+* Build a user `SessionMessage` from prompt parts without provider-specific handling.
+*
+* - `text` parts map to `{ type: 'text', text }` blocks.
+* - `image` parts map to `{ type: 'image', mediaType, data }` blocks.
+* - `document` parts with `encoding: 'text'` are inlined as an attachment-tagged
+*   text block so every provider can read them.
+* - `document` parts with `encoding: 'base64'` throw — the caller should switch
+*   to a provider that implements `promptMessage` (e.g. Anthropic for PDFs).
+*/
+function defaultPromptMessage(parts) {
+	const content = [];
+	for (const part of parts) {
+		if (part.type === "text") {
+			if (part.text.length > 0) content.push({
+				type: "text",
+				text: part.text
+			});
+			continue;
+		}
+		if (part.type === "image") {
+			content.push({
+				type: "image",
+				mediaType: part.mediaType,
+				data: part.data
+			});
+			continue;
+		}
+		if (part.encoding === "text") {
+			const header = part.name ? `<attachment name="${part.name}" media_type="${part.mediaType}">` : `<attachment media_type="${part.mediaType}">`;
+			content.push({
+				type: "text",
+				text: `${header}\n${part.data}\n</attachment>`
+			});
+			continue;
+		}
+		throw new Error(`Provider does not support base64 document parts (mediaType: ${part.mediaType}). Use a text-encoded document or a provider that implements promptMessage (e.g. Anthropic).`);
+	}
+	return {
+		role: "user",
+		content
+	};
+}
+/**
+* Build the prompt `SessionMessage` for a given provider.
+*
+* Prefers `provider.promptMessage` when defined, falling back to `defaultPromptMessage`.
+*/
+function buildPromptMessage(provider, parts) {
+	if (provider.promptMessage) return provider.promptMessage(parts);
+	return defaultPromptMessage(parts);
+}
+//#endregion
+//#region src/tool-budgets.ts
+/**
+* Install the per-tool soft-budget middleware on a hook bus.
+* `getToolBudgets` returns the resolved per-tool budgets (run override merged
+* with agent defaults). `enqueueSteer` pushes a synthetic user message into
+* the run's steeringQueue so the loop drains it between turns.
+*
+* The middleware maintains its OWN approval counter (`approvedCounts`),
+* incremented at gate-time — independent of the loop's `runToolCounts`,
+* which is incremented after gate completes. This gives atomic per-call
+* reservation in parallel batches: when a batch of N calls all fire
+* `tool:gate` before any increments propagate, each gate handler still
+* sees the prior approvals and refuses past `max`.
+*
+* Returns an `uninstall` fn.
+*/
+function installToolBudgetsGate(hooks, getToolBudgets, enqueueSteer) {
+	const steeredOnce = /* @__PURE__ */ new Set();
+	const approvedCounts = {};
+	async function gateHandler(ctx) {
+		if (ctx.block || ctx.result !== void 0) return;
+		const budget = getToolBudgets()?.[ctx.name];
+		if (!budget) return;
+		const max = budget.max;
+		if (typeof max !== "number" || max <= 0) return;
+		const count = approvedCounts[ctx.name] ?? 0;
+		if (count < max) {
+			approvedCounts[ctx.name] = count + 1;
+			return;
+		}
+		const onExceed = budget.onExceed ?? "steer";
+		let mode;
+		let message;
+		if (typeof onExceed === "function") try {
+			const out = onExceed({
+				tool: ctx.name,
+				count,
+				max
+			});
+			mode = out.mode;
+			message = out.message;
+		} catch {
+			mode = "steer";
+			message = defaultSteerMessage(ctx.name, count, max);
+		}
+		else if (onExceed === "block") {
+			mode = "block";
+			message = defaultBlockMessage(ctx.name, max);
+		} else {
+			mode = "steer";
+			message = defaultSteerMessage(ctx.name, count, max);
+		}
+		if (mode === "block") {
+			ctx.block = true;
+			ctx.reason = message;
+			await hooks.callHook("tool-budget:exceeded", {
+				tool: ctx.name,
+				count,
+				max,
+				turnId: ctx.turnId,
+				mode: "block"
+			});
+			return;
+		}
+		if (!steeredOnce.has(ctx.name)) {
+			steeredOnce.add(ctx.name);
+			enqueueSteer(message);
+			await hooks.callHook("tool-budget:exceeded", {
+				tool: ctx.name,
+				count,
+				max,
+				turnId: ctx.turnId,
+				mode: "steer"
+			});
+		}
+	}
+	const unregister = hooks.hook("tool:gate", gateHandler);
+	return function uninstall() {
+		unregister();
+		steeredOnce.clear();
+	};
+}
+function defaultSteerMessage(tool, count, max) {
+	return `[Tool budget reached: '${tool}' has been called ${count} times this run (cap: ${max}). Avoid calling it again unless strictly necessary; commit to a result and move on.]`;
+}
+function defaultBlockMessage(tool, max) {
+	return `Tool '${tool}' has reached its per-run budget of ${max} calls; further invocations are refused.`;
+}
+//#endregion
+//#region src/tools/binary-detect.ts
+/**
+* Heuristics for detecting binary content in UTF-8-decoded strings.
+*
+* `ExecutionContext.readFile` always returns text. Invalid bytes survive
+* decoding as U+FFFD (replacement char), and genuinely binary files often
+* contain NUL bytes — UTF-8 text legitimately should not. These helpers
+* give tools a cheap way to bail before drowning the model in mojibake.
+*/
+const SNIFF_BYTES = 8192;
+const REPLACEMENT_RATIO_THRESHOLD = .01;
+const REPLACEMENT_MIN_COUNT = 5;
+/**
+* True if a NUL (`\x00`) appears in the leading sample. Cheap, no false
+* positives on real text — UTF-8 never embeds NUL, so any NUL means the
+* source bytes were binary.
+*/
+function containsNullByte(text, sniffBytes = SNIFF_BYTES) {
+	const sample = text.length > sniffBytes ? text.slice(0, sniffBytes) : text;
+	for (let i = 0; i < sample.length; i++) if (sample.charCodeAt(i) === 0) return true;
+	return false;
+}
+/**
+* Heavier check used by `read_file`:
+*   - NUL byte ⇒ binary,
+*   - or U+FFFD count ≥ minimum AND ratio over threshold ⇒ binary.
+*
+* The replacement-char ratio + minimum guards against tripping on a
+* one-or-two-stray-replacement-char text file (config dumps, editor logs).
+*/
+function looksBinary(text, sniffBytes = SNIFF_BYTES) {
+	const sample = text.length > sniffBytes ? text.slice(0, sniffBytes) : text;
+	if (sample.length === 0) return false;
+	let replacementCount = 0;
+	for (let i = 0; i < sample.length; i++) {
+		const code = sample.charCodeAt(i);
+		if (code === 0) return true;
+		if (code === 65533) replacementCount++;
+	}
+	return replacementCount >= REPLACEMENT_MIN_COUNT && replacementCount / sample.length > REPLACEMENT_RATIO_THRESHOLD;
+}
+//#endregion
+//#region src/tools/skills-read.ts
+function createSkillsReadTool(options) {
+	const byName = new Map(options.catalog.map((s) => [s.name, s]));
+	return {
+		spec: {
+			name: "skills_read",
+			description: "Read a bundled resource file from an active skill. The skill must have been activated via skills_use first. Path is relative to the skill's directory (e.g. \"references/REFERENCE.md\", \"assets/template.txt\").",
+			inputSchema: {
+				type: "object",
+				properties: {
+					name: {
+						type: "string",
+						enum: options.catalog.map((s) => s.name),
+						description: "The name of the active skill."
+					},
+					path: {
+						type: "string",
+						description: "Path to the resource, relative to the skill root. Cannot escape the skill directory."
+					}
+				},
+				required: ["name", "path"],
+				additionalProperties: false
+			}
+		},
+		async execute(input, ctx) {
+			const skillName = input.name;
+			const relPath = input.path;
+			const skill = byName.get(skillName);
+			if (!skill) return `Error: unknown skill "${skillName}".`;
+			if (!options.state.isActive(skillName)) return `Error: skill "${skillName}" is not active. Call skills_use with name: "${skillName}" first.`;
+			if (!skill.baseDir) return `Error: skill "${skillName}" has no base directory (likely an inline skill without bundled resources); cannot read files.`;
+			const validated = validateResourcePath(relPath, skill.baseDir);
+			if (!validated.valid) return `Error: ${validated.error}`;
+			let content;
+			try {
+				content = await ctx.execution.readFile(ctx.handle, validated.absolutePath);
+			} catch (err) {
+				return `Error reading "${relPath}" in skill "${skillName}": ${err instanceof Error ? err.message : String(err)}`;
+			}
+			if (containsNullByte(content)) return JSON.stringify({
+				kind: "binary-unsupported",
+				path: validated.absolutePath,
+				note: "This file appears to be binary. The skills_read tool returns text only; binary files are not delivered through the execution context's text-based readFile API."
+			});
+			return content;
+		}
+	};
+}
+//#endregion
+//#region src/tools/shell-quote.ts
+/**
+* Shared shell-argument quoter for tool implementations.
+*
+* Single source of truth so `grep`, `binary-read`, and `skills-run-script`
+* don't drift on the POSIX `'\''` escape pattern.
+*/
+const SAFE_TOKEN_RE = /^[\w@%+=:,./-]+$/;
+const SINGLE_QUOTE_RE = /'/g;
+/**
+* Wrap an argument in single quotes, escaping embedded single quotes via the
+* standard POSIX `'\''` close-escape-reopen trick. Tokens that are already
+* shell-safe pass through unchanged so command lines stay readable in logs.
+*
+* NOT a sandbox — only safe when the caller controls the surrounding shell
+* context. Use it for arguments only, never for the verb / subcommand.
+*/
+function shellQuote(arg) {
+	if (SAFE_TOKEN_RE.test(arg)) return arg;
+	return `'${arg.replace(SINGLE_QUOTE_RE, "'\\''")}'`;
+}
+/**
+* Variant that always quotes — useful when the caller doesn't want a
+* conditional `unquoted-when-safe` branch (consistent log shape, paranoid
+* inputs that contain whitespace by construction).
+*/
+function alwaysQuote(arg) {
+	return `'${arg.replace(SINGLE_QUOTE_RE, "'\\''")}'`;
+}
+//#endregion
+//#region src/tools/skills-run-script.ts
+const ABS_WINDOWS_RE = /^[a-z]:[\\/]/i;
+const COLLAPSE_SLASHES_RE = /\/+/g;
+function createSkillsRunScriptTool(options) {
+	const byName = new Map(options.catalog.map((s) => [s.name, s]));
+	const timeoutMs = options.scriptTimeoutMs ?? 6e4;
+	return {
+		spec: {
+			name: "skills_run_script",
+			description: "Execute a script bundled with an active skill (from its scripts/ directory). The skill must have been activated via skills_use first. Returns stdout, stderr, and the exit code. Honors the script's shebang.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					name: {
+						type: "string",
+						enum: options.catalog.map((s) => s.name),
+						description: "The name of the active skill."
+					},
+					script: {
+						type: "string",
+						description: "Path to the script relative to the skill's scripts/ directory (e.g. \"extract.py\", \"merge.sh\")."
+					},
+					args: {
+						type: "array",
+						items: { type: "string" },
+						description: "Optional argv array passed to the script."
+					}
+				},
+				required: ["name", "script"],
+				additionalProperties: false
+			}
+		},
+		async execute(input, ctx) {
+			const skillName = input.name;
+			const scriptRel = input.script;
+			const args = input.args ?? [];
+			const skill = byName.get(skillName);
+			if (!skill) return `Error: unknown skill "${skillName}".`;
+			if (!options.state.isActive(skillName)) return `Error: skill "${skillName}" is not active. Call skills_use with name: "${skillName}" first.`;
+			if (!skill.baseDir) return `Error: skill "${skillName}" has no base directory (likely an inline skill); cannot run scripts.`;
+			if (scriptRel.startsWith("/") || ABS_WINDOWS_RE.test(scriptRel)) return `Error: Absolute paths are not allowed ("${scriptRel}").`;
+			const validated = validateResourcePath(`scripts/${scriptRel}`.replace(COLLAPSE_SLASHES_RE, "/"), skill.baseDir);
+			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)) });
+				return JSON.stringify({
+					exitCode: result.exitCode,
+					stdout: result.stdout,
+					stderr: result.stderr
+				});
+			} catch (err) {
+				return `Error running script "${scriptRel}" for skill "${skillName}": ${err instanceof Error ? err.message : String(err)}`;
+			}
+		}
+	};
+}
+//#endregion
+//#region src/tools/skills-use.ts
+const MAX_RESOURCE_LIST = 50;
+function buildSkillContentWrapper(skill, body) {
+	const parts = [];
+	parts.push(`<skill_content name="${escapeXml(skill.name)}" spec_version="0.1">`);
+	parts.push(body);
+	if (skill.baseDir) {
+		parts.push("");
+		parts.push(`Skill directory: ${skill.baseDir}`);
+		parts.push("Relative paths resolve against this directory.");
+	}
+	if (skill.resources?.length) {
+		parts.push("");
+		parts.push("<skill_resources>");
+		const shown = skill.resources.slice(0, MAX_RESOURCE_LIST);
+		for (const res of shown) parts.push(`  <file type="${res.type}">${escapeXml(res.path)}</file>`);
+		if (skill.resources.length > MAX_RESOURCE_LIST) parts.push(`  <!-- …(${skill.resources.length - MAX_RESOURCE_LIST} more) -->`);
+		parts.push("</skill_resources>");
+	}
+	if (skill.compatibility) {
+		parts.push("");
+		parts.push(`Compatibility: ${skill.compatibility}`);
+	}
+	if (skill.allowedTools?.length) parts.push(`Allowed tools: ${skill.allowedTools.join(" ")}`);
+	parts.push("</skill_content>");
+	return parts.join("\n");
+}
+/**
+* Factory for `skills_use`. Auto-injected into the agent's tool set by the
+* agent runtime when a non-empty skills catalog is available (unless
+* `SkillsConfig.tool === false`).
+*
+* The tool schema's `name` property is `enum`-constrained to the resolved
+* catalog so the LLM cannot hallucinate a skill that doesn't exist.
+*/
+function createSkillsUseTool(options) {
+	const byName = new Map(options.catalog.map((s) => [s.name, s]));
+	const interpolatedBodyCache = /* @__PURE__ */ new Map();
+	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.",
+			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)."
+				} },
+				required: ["name"],
+				additionalProperties: false
+			}
+		},
+		async execute(input, ctx) {
+			const skillName = input.name;
+			const skill = byName.get(skillName);
+			if (!skill) return `Error: unknown skill "${skillName}". Available skills: ${[...byName.keys()].join(", ") || "<none>"}.`;
+			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.`;
+				await options.hooks.callHook("skills:activate", {
+					skill,
+					via: "model"
+				});
+			}
+			let body = interpolatedBodyCache.get(skillName);
+			if (body === void 0) {
+				body = skill.instructions.includes("!`") ? await interpolateShellCommands(skill.instructions, ctx.execution, ctx.handle) : skill.instructions;
+				interpolatedBodyCache.set(skillName, body);
+			}
+			return buildSkillContentWrapper(skill, body);
+		}
+	};
+}
+//#endregion
+//#region src/tools/tool-search.ts
+const DEFAULT_LIMIT$1 = 20;
+function rankByQuery(catalog, query) {
+	const q = query.trim().toLowerCase();
+	if (!q) return [...catalog];
+	const nameHits = [];
+	const descHits = [];
+	for (const entry of catalog) if (entry.name.toLowerCase().includes(q)) nameHits.push(entry);
+	else if (entry.description.toLowerCase().includes(q)) descHits.push(entry);
+	return [...nameHits, ...descHits];
+}
+/**
+* Sanitise a JSON-stringified schema for embedding inside a pseudo-XML tag.
+*
+* The schema is inlined verbatim (NOT XML-escaped) so the model can reuse
+* field types directly when constructing arguments. The only transformation
+* we apply is replacing `<` with `\u003c` inside string literals — this
+* keeps the JSON byte-equivalent for the model (JSON parsers decode the
+* escape) while preventing a hostile or buggy `inputSchema` from injecting
+* apparent XML tags (`</input_schema>`, `<evil>…`) that would muddle the
+* model's read of the surrounding result envelope.
+*
+* The substitution is safe because `<` is only meaningful when it appears
+* literally; the `\u003c` form is not a tag character and is identical to
+* `<` after JSON parsing.
+*/
+function sanitiseSchemaForXml(schemaJson) {
+	return schemaJson.replace(/</g, "\\u003c");
+}
+function formatMatch(entry) {
+	const schema = sanitiseSchemaForXml(JSON.stringify(entry.inputSchema));
+	const serverAttr = entry.server ? ` server="${escapeXml(entry.server)}"` : "";
+	return [
+		`  <tool name="${escapeXml(entry.name)}"${serverAttr}>`,
+		`    <description>${escapeXml(entry.description)}</description>`,
+		`    <input_schema>${schema}</input_schema>`,
+		`  </tool>`
+	].join("\n");
+}
+/**
+* Factory for `tool_search`. Auto-injected by the agent when
+* `behavior.toolDisclosure === 'lazy'` and at least one MCP tool is in the
+* registry. Opt out via `behavior.toolSearch.tool === false`.
+*/
+function createToolSearchTool(options) {
+	const defaultLimit = options.defaultLimit ?? DEFAULT_LIMIT$1;
+	const byName = new Map(options.catalog.map((e) => [e.name, e]));
+	const byServer = /* @__PURE__ */ new Map();
+	for (const entry of options.catalog) {
+		if (!entry.server) continue;
+		const list = byServer.get(entry.server) ?? [];
+		list.push(entry);
+		byServer.set(entry.server, list);
+	}
+	const maxLimit = Math.max(options.catalog.length, 1);
+	return {
+		spec: {
+			name: "tool_search",
+			description: "Discover and load schemas for additional tools listed in <searchable_tools>. Tools listed there are advertised by name + description only — their input schemas are not loaded into context until you surface them through this tool. Pass `query` for a substring search, `names` to load specific tools, or `server` to load every tool from one MCP server. Returned tools become callable for the rest of this run.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					query: {
+						type: "string",
+						description: "Substring to match against tool name + description (case-insensitive)."
+					},
+					names: {
+						type: "array",
+						items: { type: "string" },
+						description: "Explicit tool names to load (bypasses ranking). Use the names shown in <searchable_tools>."
+					},
+					server: {
+						type: "string",
+						description: "MCP server name — load every tool from this server."
+					},
+					limit: {
+						type: "integer",
+						minimum: 1,
+						description: `Cap on returned matches. Default: ${defaultLimit}.`
+					}
+				},
+				additionalProperties: false
+			}
+		},
+		async execute(input, ctx) {
+			if (ctx.signal?.aborted) return "<tool_search_results matches=\"0\" aborted=\"true\">Run aborted.</tool_search_results>";
+			const query = (typeof input.query === "string" ? input.query.trim() : void 0) || void 0;
+			const namesIn = Array.isArray(input.names) ? input.names.filter((n) => typeof n === "string" && n.length > 0) : void 0;
+			const server = typeof input.server === "string" && input.server.length > 0 ? input.server : void 0;
+			const limitIn = typeof input.limit === "number" && Number.isFinite(input.limit) && input.limit > 0 ? Math.floor(input.limit) : defaultLimit;
+			const limit = Math.min(limitIn, maxLimit);
+			if (options.catalog.length === 0) return "<tool_search_results matches=\"0\">No lazy tools registered for this run.</tool_search_results>";
+			const matches = [];
+			const seen = /* @__PURE__ */ new Set();
+			const misses = [];
+			if (namesIn && namesIn.length > 0) for (const n of namesIn) {
+				if (seen.has(n)) continue;
+				const entry = byName.get(n);
+				if (entry) {
+					matches.push(entry);
+					seen.add(n);
+				} else misses.push(n);
+			}
+			if (server) {
+				const list = byServer.get(server) ?? [];
+				for (const entry of list) {
+					if (seen.has(entry.name)) continue;
+					matches.push(entry);
+					seen.add(entry.name);
+				}
+			}
+			if (query !== void 0) for (const entry of rankByQuery(options.catalog, query)) {
+				if (seen.has(entry.name)) continue;
+				matches.push(entry);
+				seen.add(entry.name);
+			}
+			if (!namesIn?.length && !server && query === void 0) for (const entry of options.catalog) {
+				matches.push(entry);
+				seen.add(entry.name);
+			}
+			const truncated = matches.length > limit;
+			const shown = truncated ? matches.slice(0, limit) : matches;
+			for (const entry of shown) options.unlocked.add(entry.canonicalName);
+			const parts = [];
+			const queryAttr = query ? ` query="${escapeXml(query)}"` : "";
+			const serverAttr = server ? ` server="${escapeXml(server)}"` : "";
+			parts.push(`<tool_search_results matches="${shown.length}" total="${matches.length}"${queryAttr}${serverAttr}>`);
+			if (shown.length === 0) parts.push("  No matches. Try a broader query, or omit all parameters to list everything.");
+			else {
+				for (const entry of shown) parts.push(formatMatch(entry));
+				parts.push("");
+				parts.push("  These tools are now callable. Invoke them by name in subsequent turns.");
+				if (truncated) parts.push(`  ${matches.length - shown.length} additional matches were truncated — refine the query or raise \`limit\`.`);
+			}
+			if (misses.length > 0) parts.push(`  <misses>${misses.map(escapeXml).join(", ")}</misses>`);
+			parts.push("</tool_search_results>");
+			return parts.join("\n");
+		}
+	};
+}
+//#endregion
+//#region src/agent.ts
+const HOOK_EVENT_SET = new Set([
+	"system:before",
+	"turn:before",
+	"turn:after",
+	"stream:text",
+	"stream:end",
+	"stream:thinking",
+	"oauth:refresh",
+	"tool:gate",
+	"tool:before",
+	"tool:after",
+	"tool:error",
+	"tool:transform",
+	"tool:unknown",
+	"validation:reject",
+	"validation:coerce",
+	"context:transform",
+	"system:transform",
+	"steer:inject",
+	"spawn:before",
+	"spawn:complete",
+	"spawn:error",
+	"child:stream:text",
+	"child:stream:thinking",
+	"child:stream:end",
+	"child:tool:before",
+	"child:tool:after",
+	"child:tool:error",
+	"child:turn:after",
+	"mcp:connect",
+	"mcp:error",
+	"mcp:close",
+	"mcp:bootstrap:start",
+	"mcp:bootstrap:end",
+	"mcp:tools:filter",
+	"mcp:tool:gate",
+	"mcp:tool:before",
+	"mcp:tool:after",
+	"mcp:tool:transform",
+	"mcp:tool:error",
+	"skills:resolve",
+	"skills:catalog",
+	"skills:activate",
+	"skills:deactivate",
+	"usage",
+	"output",
+	"budget:exceeded",
+	"tool-budget:exceeded",
+	"agent:abort",
+	"agent:done",
+	"session:start",
+	"session:end",
+	"session:turns",
+	"session:meta",
+	"session:save"
+]);
+function isKnownHookEvent(event) {
+	return HOOK_EVENT_SET.has(event);
+}
+function resolveBehavior(agentBehavior, runBehavior) {
+	return {
+		toolExecution: runBehavior?.toolExecution ?? agentBehavior?.toolExecution ?? "parallel",
+		maxTurns: runBehavior?.maxTurns ?? agentBehavior?.maxTurns,
+		maxTokens: runBehavior?.maxTokens ?? agentBehavior?.maxTokens,
+		thinkingBudget: runBehavior?.thinkingBudget ?? agentBehavior?.thinkingBudget,
+		schema: runBehavior?.schema ?? agentBehavior?.schema,
+		cache: runBehavior?.cache ?? agentBehavior?.cache ?? true,
+		toolOutputBudget: runBehavior?.toolOutputBudget ?? agentBehavior?.toolOutputBudget,
+		compactStrategy: runBehavior?.compactStrategy ?? agentBehavior?.compactStrategy ?? "off",
+		compactThreshold: runBehavior?.compactThreshold ?? agentBehavior?.compactThreshold,
+		compactKeepTurns: runBehavior?.compactKeepTurns ?? agentBehavior?.compactKeepTurns,
+		thinkingDecay: runBehavior?.thinkingDecay ?? agentBehavior?.thinkingDecay,
+		dedupReads: runBehavior?.dedupReads ?? agentBehavior?.dedupReads,
+		dedupTools: runBehavior?.dedupTools ?? agentBehavior?.dedupTools,
+		requireReadBeforeEdit: runBehavior?.requireReadBeforeEdit ?? agentBehavior?.requireReadBeforeEdit,
+		toolBudgets: runBehavior?.toolBudgets ?? agentBehavior?.toolBudgets,
+		readLineNumbers: runBehavior?.readLineNumbers ?? agentBehavior?.readLineNumbers,
+		elideStaleReads: runBehavior?.elideStaleReads ?? agentBehavior?.elideStaleReads,
+		toolDisclosure: runBehavior?.toolDisclosure ?? agentBehavior?.toolDisclosure ?? "eager",
+		toolSearch: runBehavior?.toolSearch ?? agentBehavior?.toolSearch
+	};
+}
+/**
+* Resolve which configured MCP server a namespaced tool name belongs to.
+*
+* Tools coming through {@link connectMcpServers} are keyed `mcp_<server>_<tool>`.
+* Server names may themselves contain underscores, so a naive `split('_')[1]`
+* would mis-attribute tools — instead, we test each configured server name as
+* a prefix candidate and pick the longest match. This is O(N×M) per lookup
+* but the loop runs once at run start; not on a hot path.
+*/
+function resolveServerForTool(toolName, servers) {
+	if (!servers || servers.length === 0) return void 0;
+	let best;
+	let bestLen = -1;
+	for (const server of servers) {
+		const prefix = `mcp_${server.name}_`;
+		if (toolName.startsWith(prefix) && server.name.length > bestLen) {
+			best = server;
+			bestLen = server.name.length;
+		}
+	}
+	return best;
+}
+/**
+* Partition a tool registry into eager and lazy buckets.
+*
+* Native + skill tools always end up in the eager bucket — only MCP tools
+* are eligible for lazy disclosure. The `tool_search` tool itself, when
+* registered, must be eager (otherwise the model has no way to discover
+* anything).
+*
+* Lazy entries carry both the wire (`name`, alias-rewritten) and the
+* canonical (`canonicalName`) so:
+* - The catalog and `tool_search` results show wire names — the only names
+*   the model ever sees on the provider side.
+* - The unlock set is keyed by canonical names — the loop's `ctx.tools` map
+*   and the dispatch path are alias-stable.
+*/
+function partitionToolDisclosure(toolsBySpecName, mcpToolNames, servers, globalMode, toolAliases) {
+	const eagerCanonicalNames = /* @__PURE__ */ new Set();
+	const lazyCanonicalNames = /* @__PURE__ */ new Set();
+	const lazyEntries = [];
+	function wireFor(canonical) {
+		const aliased = toolAliases?.[canonical];
+		return typeof aliased === "string" && aliased.length > 0 ? aliased : canonical;
+	}
+	for (const [canonicalName, def] of Object.entries(toolsBySpecName)) {
+		if (!mcpToolNames.has(canonicalName)) {
+			eagerCanonicalNames.add(canonicalName);
+			continue;
+		}
+		const server = resolveServerForTool(canonicalName, servers);
+		if ((server?.disclosure ?? globalMode) === "lazy") {
+			lazyCanonicalNames.add(canonicalName);
+			lazyEntries.push({
+				name: wireFor(canonicalName),
+				canonicalName,
+				description: def.spec.description || "",
+				inputSchema: def.spec.inputSchema ?? {
+					type: "object",
+					properties: {}
+				},
+				...server ? { server: server.name } : {}
+			});
+		} else eagerCanonicalNames.add(canonicalName);
+	}
+	return {
+		eagerCanonicalNames,
+		lazyCanonicalNames,
+		lazyEntries
+	};
+}
+function buildSearchableCatalog(entries, options) {
+	const byServer = /* @__PURE__ */ new Map();
+	const ungrouped = [];
+	for (const entry of entries) {
+		if (!entry.server) {
+			ungrouped.push(entry);
+			continue;
+		}
+		const list = byServer.get(entry.server) ?? [];
+		list.push(entry);
+		byServer.set(entry.server, list);
+	}
+	const serverNames = [...byServer.keys()].sort();
+	const parts = [];
+	if (options.discoveryToolName) parts.push("The following tools are available but their input schemas are NOT loaded in your context.", `Call the \`${options.discoveryToolName}\` tool to load schemas before invoking them. Surfaced tools persist for the rest of the run.`, "");
+	parts.push("<searchable_tools>");
+	for (const server of serverNames) {
+		parts.push(`  <server name="${escapeXml(server)}">`);
+		for (const entry of byServer.get(server)) parts.push(`    <tool name="${escapeXml(entry.name)}">${escapeXml(entry.description)}</tool>`);
+		parts.push("  </server>");
+	}
+	for (const entry of ungrouped) parts.push(`  <tool name="${escapeXml(entry.name)}">${escapeXml(entry.description)}</tool>`);
+	parts.push("</searchable_tools>");
+	return parts.join("\n");
+}
+/**
+* Install a `tool:gate` listener that refuses dispatch on lazy tools the
+* model hasn't surfaced via `tool_search` yet. Production providers
+* (Anthropic, OpenAI) already enforce this server-side because the model
+* can only emit `tool_use` for tools in the request's `tools` list — but
+* relying on that alone leaves custom / OSS / mock providers (and any
+* future lenient validator) able to bypass the gate by quoting a name from
+* the catalog. The middleware closes the gap so lazy disclosure is a real
+* boundary, not just an advertisement filter.
+*
+* Returns an uninstall function the run-end teardown calls so handlers
+* never leak across runs.
+*/
+function installLazyDisclosureGate(hooks, lazyCanonicalNames, unlocked, discoveryToolName) {
+	if (lazyCanonicalNames.size === 0) return () => {};
+	return hooks.hook("tool:gate", (ctx) => {
+		if (ctx.block) return;
+		if (!lazyCanonicalNames.has(ctx.name)) return;
+		if (unlocked.has(ctx.name)) return;
+		ctx.block = true;
+		ctx.reason = discoveryToolName ? `Tool "${ctx.name}" is listed in <searchable_tools> but its schema has not been loaded. Call the \`${discoveryToolName}\` tool with names: ["${ctx.name}"] first, then re-issue the call.` : `Tool "${ctx.name}" is listed in <searchable_tools> but its schema has not been loaded.`;
+	});
+}
+function createAgent({ provider, name: agentName, system: agentSystem, tools: agentTools, toolAliases, behavior: agentBehavior, execution, mcpServers, session, skills: agentSkills, mcpConnector, eager }) {
+	const hooks = createHooks();
+	const executionContext = execution ?? createProcessContext();
+	const sourceTools = agentTools ?? {};
+	let abortController;
+	let running = false;
+	let idleResolve;
+	let idlePromise;
+	let executionHandle = null;
+	let mcpConnection = null;
+	let mcpWarmupPromise = null;
+	const allMcpServers = mcpServers ?? [];
+	const steeringQueue = [];
+	const followUpQueue = [];
+	let conversationTurns = session?.turns.slice() ?? [];
+	let runCounter = session?.runs.length ?? 0;
+	const skillsConfig = agentSkills;
+	const skillsEnabledValue = skillsConfig?.enabled;
+	const skillsDisabled = skillsEnabledValue === false || Array.isArray(skillsEnabledValue) && skillsEnabledValue.length === 0;
+	let resolvedSkills = null;
+	let skillsCatalog = null;
+	let skillsCleanup = () => {};
+	const skillActivationState = createSkillActivationState({ maxActive: skillsConfig?.maxActive });
+	async function run(options) {
+		if (running) throw new Error("Agent is already running. Use steer() or followUp() to queue messages, or waitForIdle().");
+		const hasSessionTurns = session && session.turns.length > 0;
+		if (!options.prompt && !hasSessionTurns) throw new Error("prompt is required when no session with existing turns is provided");
+		if (!options.prompt && hasSessionTurns) {
+			const lastTurn = session.turns.at(-1);
+			if (lastTurn && lastTurn.role !== "user") throw new Error("cannot resume without prompt: last session turn must be a user message");
+		}
+		running = true;
+		abortController = new AbortController();
+		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, {
+			...options.parentRunId ? { parentRunId: options.parentRunId } : {},
+			depth: typeof options.depth === "number" ? options.depth : 0
+		});
+		if (session) {
+			await session.updateStatus("running");
+			await hooks.callHook("session:start", {
+				sessionId: session.id,
+				runId,
+				prompt: promptLabel
+			});
+		}
+		if (options.signal) if (options.signal.aborted) abortController.abort();
+		else {
+			const onExternalAbort = () => abortController?.abort();
+			options.signal.addEventListener("abort", onExternalAbort, { once: true });
+		}
+		idlePromise = new Promise((resolve) => {
+			idleResolve = resolve;
+		});
+		const childrenStats = [];
+		const unregisterSpawnHook = hooks.hook("spawn:complete", (ctx) => {
+			childrenStats.push(ctx);
+		});
+		const perRunUnregisters = [];
+		if (options.hooks) for (const [event, handler] of Object.entries(options.hooks)) {
+			if (!isKnownHookEvent(event)) throw new Error(`Unknown hook event "${event}" passed to run(). See AgentHooks for valid events.`);
+			const handlerList = Array.isArray(handler) ? handler : [handler];
+			for (const fn of handlerList) {
+				if (typeof fn !== "function") continue;
+				perRunUnregisters.push(hooks.hook(event, fn));
+			}
+		}
+		if (!executionHandle) executionHandle = await executionContext.spawn();
+		if (allMcpServers.length > 0 && !mcpConnection) await warmup();
+		if (!skillsDisabled && skillsConfig && !resolvedSkills) {
+			const bundle = await resolveSkills(skillsConfig);
+			resolvedSkills = bundle.skills;
+			skillsCleanup = bundle.cleanup;
+			await hooks.callHook("skills:resolve", { skills: resolvedSkills });
+			const skillsToolRegistered = skillsConfig?.tool !== false && resolvedSkills.length > 0;
+			const catalogCtx = {
+				catalog: buildCatalog(resolvedSkills, { skillsToolRegistered }),
+				skills: resolvedSkills
+			};
+			await hooks.callHook("skills:catalog", catalogCtx);
+			skillsCatalog = catalogCtx.catalog;
+		}
+		if (resolvedSkills && session && session.turns.length > 0 && skillActivationState.active().length === 0) {
+			const skillsByName = new Map(resolvedSkills.map((s) => [s.name, s]));
+			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;
+					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 thinking = options.thinking ?? "off";
+		const model = options.model ?? provider.meta.defaultModel;
+		const resolvedBehavior = resolveBehavior(agentBehavior, options.behavior);
+		const { toolExecution, maxTurns, maxTokens, thinkingBudget, schema, cache, toolOutputBudget, compactStrategy, compactThreshold, compactKeepTurns, thinkingDecay, dedupTools, toolBudgets, elideStaleReads, toolDisclosure, toolSearch } = resolvedBehavior;
+		let system = options.system || agentSystem || "You are a helpful assistant.";
+		if (skillsCatalog) system = `${system}\n\n${skillsCatalog}`;
+		const runBaseTools = options.tools !== void 0 ? options.tools : mcpConnection ? {
+			...sourceTools,
+			...mcpConnection.tools
+		} : sourceTools;
+		const mcpToolNames = options.tools === void 0 && mcpConnection ? new Set(Object.keys(mcpConnection.tools)) : /* @__PURE__ */ new Set();
+		const mergedWithSkills = options.tools === void 0 && !!resolvedSkills && resolvedSkills.length > 0 && skillsConfig?.tool !== false ? {
+			skills_use: createSkillsUseTool({
+				catalog: resolvedSkills,
+				state: skillActivationState,
+				hooks
+			}),
+			skills_read: createSkillsReadTool({
+				catalog: resolvedSkills,
+				state: skillActivationState
+			}),
+			skills_run_script: createSkillsRunScriptTool({
+				catalog: resolvedSkills,
+				state: skillActivationState,
+				scriptTimeoutMs: skillsConfig?.scriptTimeoutMs
+			}),
+			...runBaseTools
+		} : runBaseTools;
+		const toolsPreSearch = {};
+		for (const tool of Object.values(mergedWithSkills)) toolsPreSearch[tool.spec.name] = tool;
+		const disclosure = partitionToolDisclosure(toolsPreSearch, mcpToolNames, mcpServers, toolDisclosure, toolAliases);
+		const unlocked = new Set(disclosure.eagerCanonicalNames);
+		const hostDefinedToolSearch = !!toolsPreSearch.tool_search;
+		const shouldInjectToolSearch = disclosure.lazyEntries.length > 0 && toolSearch?.tool !== false && !hostDefinedToolSearch;
+		let tools = toolsPreSearch;
+		if (shouldInjectToolSearch) {
+			const toolSearchTool = createToolSearchTool({
+				catalog: disclosure.lazyEntries,
+				unlocked,
+				...toolSearch?.limit !== void 0 ? { defaultLimit: toolSearch.limit } : {}
+			});
+			tools = {
+				...toolsPreSearch,
+				[toolSearchTool.spec.name]: toolSearchTool
+			};
+			unlocked.add(toolSearchTool.spec.name);
+		}
+		const discoveryToolName = shouldInjectToolSearch ? "tool_search" : hostDefinedToolSearch ? toolAliases?.tool_search ?? "tool_search" : null;
+		if (disclosure.lazyEntries.length > 0) system = `${system}\n\n${buildSearchableCatalog(disclosure.lazyEntries, { discoveryToolName })}`;
+		const aliasMaps = buildAliasMaps(toolAliases, Object.keys(tools));
+		const uninstallLazyDisclosureGate = installLazyDisclosureGate(hooks, disclosure.lazyCanonicalNames, unlocked, discoveryToolName);
+		function buildFormattedTools() {
+			const specs = [];
+			for (const t of Object.values(tools)) {
+				if (!unlocked.has(t.spec.name)) continue;
+				specs.push({
+					name: aliasMaps.aliasByCanonical.get(t.spec.name) ?? t.spec.name,
+					description: t.spec.description || "",
+					inputSchema: t.spec.inputSchema
+				});
+			}
+			return specs.length > 0 ? provider.formatTools(specs) : [];
+		}
+		const formattedTools = buildFormattedTools();
+		const turns = [];
+		const isResume = session && session.turns.length > 0 && (session.runs.length > 0 || !options.prompt);
+		if (isResume) turns.push(...session.turns);
+		const runTurnStart = turns.length;
+		if (options.system) await hooks.callHook("system:before", { system: options.system });
+		const promptParts = canonicalizePrompt(options.prompt);
+		if (promptParts) {
+			const promptMsg = buildPromptMessage(provider, promptParts);
+			turns.push({
+				id: crypto.randomUUID(),
+				runId,
+				role: promptMsg.role,
+				content: promptMsg.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);
+			lastPersistedTurnCount = turns.length;
+			await hooks.callHook("session:turns", {
+				sessionId: session.id,
+				turns: seededTurns,
+				count: turns.length
+			});
+		}
+		const unregisterSessionSync = session ? hooks.hook("turn:after", async () => {
+			const newTurns = turns.slice(lastPersistedTurnCount);
+			if (newTurns.length > 0) {
+				await session.appendTurns(newTurns);
+				lastPersistedTurnCount = turns.length;
+				await hooks.callHook("session:turns", {
+					sessionId: session.id,
+					turns: newTurns,
+					count: turns.length
+				});
+			}
+		}) : void 0;
+		async function flushTurns() {
+			if (!session) return;
+			const remaining = turns.slice(lastPersistedTurnCount);
+			if (remaining.length > 0) {
+				await session.appendTurns(remaining);
+				lastPersistedTurnCount = turns.length;
+				await hooks.callHook("session:turns", {
+					sessionId: session.id,
+					turns: remaining,
+					count: turns.length
+				});
+			}
+		}
+		async function deactivateAllSkills() {
+			for (const record of skillActivationState.clear()) await hooks.callHook("skills:deactivate", {
+				skill: record.skill,
+				reason: "run-end"
+			});
+		}
+		async function finalizeSession(status) {
+			if (!session) return;
+			const run = session.runs.find((r) => r.id === runId);
+			if (run) await session.updateRun(run);
+			await session.updateStatus(status === "aborted" ? "idle" : status);
+			await hooks.callHook("session:end", {
+				sessionId: session.id,
+				runId,
+				status,
+				turnRange: [runTurnStart, turns.length - 1]
+			});
+		}
+		const uninstallAllowedToolsGate = installAllowedToolsGate(hooks, skillActivationState);
+		const uninstallToolBudgets = installToolBudgetsGate(hooks, () => toolBudgets, (msg) => steeringQueue.push(msg));
+		const uninstallDedupTools = installDedupToolsGate(hooks, () => dedupTools, () => session ?? void 0);
+		const runStartMs = Date.now();
+		const runDepth = typeof options.depth === "number" ? options.depth : 0;
+		try {
+			const stats = await runLoop({
+				provider,
+				hooks,
+				agentName,
+				agentSystem,
+				agentTools: sourceTools,
+				agentToolAliases: toolAliases,
+				agentMcpServers: mcpServers,
+				agentSkills,
+				agentBehavior: resolvedBehavior,
+				tools,
+				formattedTools,
+				rebuildFormattedTools: disclosure.lazyEntries.length > 0 ? buildFormattedTools : void 0,
+				aliasMaps,
+				model,
+				system,
+				thinking,
+				toolExecution,
+				signal: abortController.signal,
+				execution: executionContext,
+				handle: executionHandle,
+				steeringQueue,
+				followUpQueue,
+				turns,
+				runId,
+				generateTurnId: () => session?.generateTurnId() ?? crypto.randomUUID(),
+				maxTurns,
+				maxTokens,
+				...session ? { session } : {},
+				depth: runDepth,
+				thinkingBudget,
+				schema,
+				cache,
+				toolOutputBudget,
+				compactStrategy,
+				compactThreshold,
+				compactKeepTurns,
+				...elideStaleReads !== void 0 ? { elideStaleReads } : {},
+				...thinkingDecay !== void 0 ? { thinkingDecay } : {},
+				runStartMs,
+				runToolCounts: {}
+			});
+			const parentTurnCost = stats.turnUsage?.reduce((sum, t) => sum + (t.cost ?? 0), 0) ?? 0;
+			let childrenIn = 0;
+			let childrenOut = 0;
+			let childrenCost = 0;
+			let childrenCacheRead = 0;
+			let childrenCacheCreation = 0;
+			for (const c of childrenStats) {
+				childrenIn += c.stats.totalIn;
+				childrenOut += c.stats.totalOut;
+				childrenCost += c.stats.cost ?? 0;
+				childrenCacheRead += c.stats.totalCacheRead;
+				childrenCacheCreation += c.stats.totalCacheCreation;
+			}
+			const cumulativeCost = parentTurnCost + childrenCost;
+			const finalStats = {
+				...stats,
+				totalIn: stats.totalIn + childrenIn,
+				totalOut: stats.totalOut + childrenOut,
+				totalCacheRead: stats.totalCacheRead + childrenCacheRead,
+				totalCacheCreation: stats.totalCacheCreation + childrenCacheCreation,
+				...cumulativeCost > 0 ? { cost: cumulativeCost } : {},
+				children: childrenStats.length > 0 ? childrenStats : void 0
+			};
+			await flushTurns();
+			if (abortController.signal.aborted) {
+				session?.abortRun(runId);
+				await finalizeSession("aborted");
+				await hooks.callHook("agent:done", finalStats);
+				return finalStats;
+			}
+			session?.completeRun(runId, {
+				turns: stats.turns,
+				tokensIn: stats.totalIn,
+				tokensOut: stats.totalOut,
+				turnUsage: stats.turnUsage,
+				cost: parentTurnCost > 0 ? parentTurnCost : void 0
+			});
+			await finalizeSession("completed");
+			await hooks.callHook("agent:done", finalStats);
+			return finalStats;
+		} catch (err) {
+			await flushTurns();
+			if (abortController.signal.aborted) {
+				session?.abortRun(runId);
+				await finalizeSession("aborted");
+				const stats = {
+					totalIn: 0,
+					totalOut: 0,
+					totalCacheRead: 0,
+					totalCacheCreation: 0,
+					turns: 0,
+					elapsed: 0
+				};
+				await hooks.callHook("agent:done", stats);
+				return stats;
+			}
+			const message = err instanceof Error ? err.message : String(err);
+			session?.errorRun(runId, message);
+			await finalizeSession("error");
+			throw err;
+		} finally {
+			await deactivateAllSkills();
+			uninstallAllowedToolsGate();
+			uninstallDedupTools();
+			uninstallToolBudgets();
+			uninstallLazyDisclosureGate();
+			unregisterSpawnHook();
+			unregisterSessionSync?.();
+			for (const unregister of perRunUnregisters) unregister();
+			running = false;
+			abortController = void 0;
+			steeringQueue.length = 0;
+			followUpQueue.length = 0;
+			idleResolve?.();
+			idlePromise = void 0;
+			idleResolve = void 0;
+		}
+	}
+	function abort() {
+		abortController?.abort();
+	}
+	function steer(message) {
+		steeringQueue.push(message);
+	}
+	function followUpFn(message) {
+		followUpQueue.push(message);
+	}
+	function waitForIdle() {
+		return idlePromise ?? Promise.resolve();
+	}
+	async function reset() {
+		if (running) throw new Error("Cannot reset() while the agent is running. Call `agent.abort()` and `await agent.waitForIdle()` first.");
+		conversationTurns = [];
+		steeringQueue.length = 0;
+		followUpQueue.length = 0;
+		const cleared = skillActivationState.clear();
+		for (const record of cleared) await hooks.callHook("skills:deactivate", {
+			skill: record.skill,
+			reason: "reset"
+		});
+	}
+	async function activateSkill(name) {
+		if (!resolvedSkills) throw new Error(`Cannot activate skill "${name}" — skills have not been resolved yet. Call activateSkill after the first \`run()\`, or pass a skills config that resolves at agent-creation time.`);
+		const skill = resolvedSkills.find((s) => s.name === name);
+		if (!skill) {
+			const available = resolvedSkills.map((s) => s.name).join(", ") || "<none>";
+			throw new Error(`Unknown skill "${name}". Available skills: ${available}.`);
+		}
+		const outcome = skillActivationState.activate(skill, "explicit");
+		if (outcome === "cap-reached") throw new Error(`Cannot activate skill "${name}" — the maxActive cap of ${skillsConfig?.maxActive} has been reached.`);
+		if (outcome === "ok") await hooks.callHook("skills:activate", {
+			skill,
+			via: "explicit"
+		});
+	}
+	async function deactivateSkill(name) {
+		const removed = skillActivationState.deactivate(name);
+		if (removed) await hooks.callHook("skills:deactivate", {
+			skill: removed.skill,
+			reason: "explicit"
+		});
+	}
+	if (session) {
+		const originalSave = session.save.bind(session);
+		const originalSetMeta = session.setMeta.bind(session);
+		session.save = async () => {
+			await originalSave();
+			await hooks.callHook("session:save", { sessionId: session.id });
+		};
+		session.setMeta = (key, value) => {
+			originalSetMeta(key, value);
+			Promise.resolve(hooks.callHook("session:meta", {
+				sessionId: session.id,
+				key,
+				value
+			})).catch((err) => {
+				console.error("[zidane] session:meta listener rejected:", err);
+			});
+		};
+	}
+	let destroyed = false;
+	/**
+	* Pre-connect MCP servers. Returns the shared in-flight promise when a
+	* bootstrap is already running, so concurrent callers converge on one
+	* connection. Clears the cached promise on failure so the next caller can
+	* retry — leaving a rejected promise cached would permanently poison future
+	* runs on the same agent.
+	*/
+	async function warmup() {
+		if (destroyed) return;
+		if (mcpConnection || allMcpServers.length === 0) return;
+		if (mcpWarmupPromise) return mcpWarmupPromise;
+		mcpWarmupPromise = (async () => {
+			const connection = mcpConnector ? await mcpConnector(allMcpServers) : await connectMcpServers(allMcpServers, void 0, hooks);
+			if (destroyed) {
+				await connection.close().catch(() => {});
+				return;
+			}
+			mcpConnection = connection;
+		})();
+		try {
+			await mcpWarmupPromise;
+		} catch (err) {
+			mcpWarmupPromise = null;
+			throw err;
+		}
+	}
+	async function destroy() {
+		if (destroyed) return;
+		destroyed = true;
+		if (mcpWarmupPromise) try {
+			await mcpWarmupPromise;
+		} catch {}
+		if (mcpConnection) {
+			await mcpConnection.close();
+			mcpConnection = null;
+		}
+		if (executionHandle) {
+			await executionContext.destroy(executionHandle);
+			executionHandle = null;
+		}
+		skillsCleanup();
+		skillsCleanup = () => {};
+	}
+	if (eager && allMcpServers.length > 0) warmup().catch(() => {});
+	return {
+		hooks,
+		run,
+		abort,
+		steer,
+		followUp: followUpFn,
+		waitForIdle,
+		reset,
+		destroy,
+		warmup,
+		activateSkill,
+		deactivateSkill,
+		get isRunning() {
+			return running;
+		},
+		get turns() {
+			return conversationTurns;
+		},
+		get execution() {
+			return executionContext;
+		},
+		get handle() {
+			return executionHandle;
+		},
+		get session() {
+			return session ?? null;
+		},
+		get activeSkills() {
+			return skillActivationState.active();
+		},
+		meta: Object.freeze({ ...provider.meta })
+	};
+}
+//#endregion
+//#region src/tools/edit-utils.ts
+/**
+* Internal helpers shared between the `edit` and `multi_edit` tools.
+*
+* Not part of the public API — intentionally not re-exported from `tools/index.ts`
+* or the package barrel.
+*/
+/**
+* Count exact (non-overlapping) occurrences of `needle` in `haystack`.
+* Returns 0 for an empty needle — both edit tools reject empty `old_string`
+* up front, so this branch is defensive rather than semantic.
+*/
+function countExactMatches(haystack, needle) {
+	if (needle.length === 0) return 0;
+	let count = 0;
+	let idx = 0;
+	while (true) {
+		const next = haystack.indexOf(needle, idx);
+		if (next === -1) break;
+		count++;
+		idx = next + needle.length;
+	}
+	return count;
+}
+/** Map curly quotes (any of the four) to their straight ASCII equivalents. */
+function normalizeQuotes(str) {
+	return str.replaceAll("‘", "'").replaceAll("’", "'").replaceAll("“", "\"").replaceAll("”", "\"");
+}
+/**
+* Substitutions Anthropic's API applies to assistant output before the model
+* sees it. The model emits the sanitized form; the file on disk contains the
+* unsanitized form. We undo the substitutions on `old_string` so the search
+* lands on the actual file contents.
+*
+* Verbatim from `claude-code/tools/FileEditTool/utils.ts`.
+*/
+const DESANITIZATIONS = [
+	["<fnr>", "<function_results>"],
+	["<n>", "<name>"],
+	["</n>", "</name>"],
+	["<o>", "<output>"],
+	["</o>", "</output>"],
+	["<e>", "<error>"],
+	["</e>", "</error>"],
+	["<s>", "<system>"],
+	["</s>", "</system>"],
+	["<r>", "<result>"],
+	["</r>", "</result>"],
+	["< META_START >", "<META_START>"],
+	["< META_END >", "<META_END>"],
+	["< EOT >", "<EOT>"],
+	["< META >", "<META>"],
+	["< SOS >", "<SOS>"],
+	["\n\nH:", "\n\nHuman:"],
+	["\n\nA:", "\n\nAssistant:"]
+];
+/**
+* Apply the SDK desanitization table to a string. Exported so the edit tools
+* can apply it to `new_string` whenever `old_string` matched via a
+* desanitize-class fallback — keeps the file's unsanitized form on disk
+* instead of writing the model's abbreviated form back.
+*/
+function desanitize(s) {
+	let out = s;
+	for (const [from, to] of DESANITIZATIONS) out = out.replaceAll(from, to);
+	return out;
+}
+/**
+* Strip line-number prefixes from each line of a needle, used as a recovery
+* fallback when the model pastes a `read_file` chunk verbatim into
+* `old_string` — the on-disk file doesn't carry the metadata prefix.
+*
+* Accepts three separator characters so a model that learned on a different
+* agent stack still works here: `\t` (Claude Code compact, our default),
+* `|`, and `→`. Pattern: optional leading whitespace, 1-9 digits, then one
+* of `\t | →`. The 9-digit ceiling covers files up to ~1B lines without
+* overshooting into legitimate `\d{N}<sep>` content like Markdown table
+* cells with long numeric IDs.
+*/
+const LINE_NUMBER_PREFIX_RE = /^[ \t]*\d{1,9}[\t|\u2192]/gm;
+function stripLineNumberPrefixes(s) {
+	return s.replace(LINE_NUMBER_PREFIX_RE, "");
+}
+/**
+* Search `target` in `normFile` and slice the matching span out of the
+* original `haystack`, counting all non-overlapping occurrences. `normFile`
+* is the haystack with whatever transform (quotes / desanitize / combined)
+* was applied to make the indices align — slicing the original haystack
+* preserves the file's actual typography so `replace_all` writes back the
+* file's form, not the model's.
+*
+* Pre-condition: `normFile.length === haystack.length` (every transform
+* we use is one-to-one). Returns null on miss.
+*/
+function locateAndCount(haystack, normFile, target, via) {
+	const idx = normFile.indexOf(target);
+	if (idx === -1) return null;
+	const actual = haystack.slice(idx, idx + target.length);
+	let occ = 0;
+	let cursor = 0;
+	while (true) {
+		const next = normFile.indexOf(target, cursor);
+		if (next === -1) break;
+		occ++;
+		cursor = next + target.length;
+	}
+	return {
+		actual,
+		occurrences: occ,
+		via
+	};
+}
+function resolveOldString(haystack, needle) {
+	const exact = countExactMatches(haystack, needle);
+	if (exact > 0) return {
+		actual: needle,
+		occurrences: exact,
+		via: "exact"
+	};
+	const normNeedle = normalizeQuotes(needle);
+	const normFile = normalizeQuotes(haystack);
+	if (normNeedle !== needle || normFile !== haystack) {
+		const m = locateAndCount(haystack, normFile, normNeedle, "quotes");
+		if (m) return m;
+	}
+	const desan = desanitize(needle);
+	if (desan !== needle) {
+		const desanCount = countExactMatches(haystack, desan);
+		if (desanCount > 0) return {
+			actual: desan,
+			occurrences: desanCount,
+			via: "desanitize"
+		};
+	}
+	const combo = desanitize(normNeedle);
+	if (combo !== needle) {
+		const m = locateAndCount(haystack, normFile, combo, "quotes+desanitize");
+		if (m) return m;
+	}
+	const stripped = stripLineNumberPrefixes(needle);
+	if (stripped !== needle && stripped.trim().length > 0) {
+		const count = countExactMatches(haystack, stripped);
+		if (count > 0) return {
+			actual: stripped,
+			occurrences: count,
+			via: "line-numbers"
+		};
+		const strippedNorm = normalizeQuotes(stripped);
+		if (strippedNorm !== stripped || normFile !== haystack) {
+			const m = locateAndCount(haystack, normFile, strippedNorm, "quotes+line-numbers");
+			if (m) return m;
+		}
+	}
+	return null;
+}
+/**
+* Apply the same recovery transforms used to find `old_string` to
+* `new_string`, so the file gets back its native form: desanitize when
+* the model emitted `<n>` for `<name>`, strip line-number prefixes when
+* the match required them, then re-curlify when the match required
+* quote normalization. Shared between `edit` and `multi_edit`.
+*/
+function styleReplacementForVia(replacement, via, actual) {
+	let out = replacement;
+	if (via === "desanitize" || via === "quotes+desanitize") out = desanitize(out);
+	if (via === "line-numbers" || via === "quotes+line-numbers") out = stripLineNumberPrefixes(out);
+	if (via === "quotes" || via === "quotes+desanitize" || via === "quotes+line-numbers") out = preserveQuoteStyle(actual, out);
+	return out;
+}
+/**
+* When `old_string` matched via curly-quote normalization, re-style
+* `new_string` so the file's typography is preserved across the edit.
+* Detects whether the matched file region had curly singles, doubles, or
+* both, and applies the matching curlification to the replacement.
+*
+* Apostrophes in contractions (`don't`, `it's`) get the right-single curly
+* quote regardless of opening context — that's the canonical typographer's
+* convention for English. Other quotes use a simple
+* preceded-by-whitespace-or-opening-punctuation heuristic.
+*/
+function preserveQuoteStyle(actual, replacement) {
+	const hasDouble = actual.includes("“") || actual.includes("”");
+	const hasSingle = actual.includes("‘") || actual.includes("’");
+	if (!hasDouble && !hasSingle) return replacement;
+	let out = replacement;
+	if (hasDouble) out = applyCurly(out, "\"", "“", "”", false);
+	if (hasSingle) out = applyCurly(out, "'", "‘", "’", true);
+	return out;
+}
+function applyCurly(s, straight, left, right, contractionAware) {
+	const chars = [...s];
+	const result = [];
+	for (let i = 0; i < chars.length; i++) {
+		if (chars[i] !== straight) {
+			result.push(chars[i]);
+			continue;
+		}
+		if (contractionAware) {
+			const prev = i > 0 ? chars[i - 1] : "";
+			const next = i < chars.length - 1 ? chars[i + 1] : "";
+			if (/\p{L}/u.test(prev) && /\p{L}/u.test(next)) {
+				result.push(right);
+				continue;
+			}
+		}
+		result.push(isOpeningContext(chars, i) ? left : right);
+	}
+	return result.join("");
+}
+function isOpeningContext(chars, i) {
+	if (i === 0) return true;
+	const prev = chars[i - 1];
+	return prev === " " || prev === "	" || prev === "\n" || prev === "\r" || prev === "(" || prev === "[" || prev === "{" || prev === "—" || prev === "–";
+}
+//#endregion
+//#region src/tools/path-suggest.ts
+/**
+* Find a sibling file in the same directory sharing `path`'s basename
+* (sans extension), excluding the missing path itself. Returns just the
+* filename (not the full path) when found, otherwise `null`.
+*
+* Silent on errors — a missing parent directory or a `listFiles` failure
+* means we have no suggestion, not that anything is wrong.
+*/
+async function findSimilarFile(execution, handle, path) {
+	const slash = path.lastIndexOf("/");
+	const dir = slash === -1 ? "." : path.slice(0, slash) || "/";
+	const target = slash === -1 ? path : path.slice(slash + 1);
+	const dot = target.lastIndexOf(".");
+	const targetBase = dot === -1 ? target : target.slice(0, dot);
+	if (targetBase.length === 0) return null;
+	let entries;
+	try {
+		entries = await execution.listFiles(handle, dir);
+	} catch {
+		return null;
+	}
+	for (const entry of entries) {
+		if (entry === target) continue;
+		const entryDot = entry.lastIndexOf(".");
+		if ((entryDot === -1 ? entry : entry.slice(0, entryDot)) === targetBase) return entry;
+	}
+	return null;
+}
+/**
+* Format a `Did you mean X?` suffix for missing-file errors. Returns an empty
+* string when no suggestion is available so callers can string-concat
+* unconditionally.
+*/
+async function suggestionFor(execution, handle, path) {
+	const sibling = await findSimilarFile(execution, handle, path);
+	return sibling ? ` Did you mean ${sibling}?` : "";
+}
+//#endregion
+//#region src/tools/edit.ts
+/**
+* Surgical edit — replace `old_string` with `new_string` in a single file.
+*
+* Mirrors Claude Code's `Edit` semantics so models post-trained on Anthropic's
+* tool surface need no relearning. Fails clearly when `old_string` isn't unique
+* (unless `replace_all: true`) and when not found, with a nearest-match preview
+* so the model can recover without a separate `read_file` round-trip.
+*/
+const edit = {
+	spec: {
+		name: "edit",
+		description: "Replace exact `old_string` with `new_string` in a file. Fails if `old_string` is not unique unless `replace_all: true`. Prefer over `write_file` for surgical changes — preserves the rest of the file. Tolerates `read_file` line-number prefixes (`<N>\\t…`, `<N>|…`, or `<N>→…`) in `old_string` / `new_string` — they are stripped before matching/writing, so you can paste a numbered chunk verbatim.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Relative file path."
+				},
+				old_string: {
+					type: "string",
+					description: "Exact substring to find."
+				},
+				new_string: {
+					type: "string",
+					description: "Replacement substring."
+				},
+				replace_all: {
+					type: "boolean",
+					description: "Replace every occurrence. Default: false."
+				}
+			},
+			required: [
+				"path",
+				"old_string",
+				"new_string"
+			]
+		}
+	},
+	async execute({ path, old_string, new_string, replace_all }, ctx) {
+		const target = path;
+		const find = old_string;
+		const replacement = new_string;
+		const replaceAll = replace_all === true;
+		if (find === replacement) return `Edit error: old_string and new_string are identical — nothing to change in ${target}.`;
+		if (find.length === 0) return `Edit error: old_string is empty. Use write_file to create or fully overwrite a file.`;
+		let original;
+		try {
+			original = await ctx.execution.readFile(ctx.handle, target);
+		} catch {
+			return `Edit error: file not found: ${target}.${await suggestionFor(ctx.execution, ctx.handle, target)}`;
+		}
+		if (ctx.behavior?.requireReadBeforeEdit && ctx.session) {
+			const readState = getReadState(ctx.session);
+			const absKey = `${ctx.handle.cwd}::${target}`;
+			const prior = readState?.get(absKey);
+			if (!prior) return `Edit error: ${target} has not been read in this session. Call read_file first so the edit applies against the current contents.`;
+			if (prior.contentHash !== hashContent(original)) return `Edit error: ${target} has changed on disk since the last read. Re-read the file before editing.`;
+		}
+		const match = resolveOldString(original, find);
+		if (!match) {
+			const preview = nearestMatchPreview(original, find);
+			return preview ? `Edit error: old_string not found in ${target}. Closest match in the file: ${preview}` : `Edit error: old_string not found in ${target}.`;
+		}
+		const { actual, occurrences, via } = match;
+		if (occurrences > 1 && !replaceAll) return `Edit error: old_string appears ${occurrences} times in ${target}. Pass replace_all=true or expand old_string for uniqueness.`;
+		const styledReplacement = styleReplacementForVia(replacement, via, actual);
+		const updated = replaceAll ? original.split(actual).join(styledReplacement) : original.replace(actual, styledReplacement);
+		if (updated === original) return `Edit error: replacement produced no change in ${target}.`;
+		await ctx.execution.writeFile(ctx.handle, target, updated);
+		if (ctx.session) {
+			const readState = getReadState(ctx.session);
+			const absKey = `${ctx.handle.cwd}::${target}`;
+			const prior = readState?.get(absKey);
+			if (readState && prior) readState.set(absKey, {
+				...prior,
+				contentHash: hashContent(updated),
+				mtimeMs: Date.now()
+			});
+		}
+		return `Edited ${target}: replaced ${occurrences} occurrence${occurrences === 1 ? "" : "s"}.`;
+	}
+};
+/**
+* Find the line that shares the longest common prefix with the needle's first
+* line. Cheap heuristic — better than nothing for the common "model has a typo"
+* case (off-by-one indent, trailing whitespace, escape mismatch).
+*
+* Returns a "line N: <preview>" snippet or null when no line shares a useful
+* prefix. Strips line-number prefixes from the needle first so a model that
+* pasted a numbered `read_file` chunk verbatim still gets a useful diagnostic.
+*/
+function nearestMatchPreview(haystack, needle) {
+	const needleFirstLine = stripLineNumberPrefixes(needle).split("\n")[0];
+	if (needleFirstLine.length < 3) return null;
+	const lines = haystack.split("\n");
+	let bestScore = 0;
+	let bestIdx = -1;
+	for (let i = 0; i < lines.length; i++) {
+		const score = sharedPrefixLength(lines[i], needleFirstLine);
+		if (score > bestScore) {
+			bestScore = score;
+			bestIdx = i;
+		}
+	}
+	if (bestIdx < 0 || bestScore < Math.min(8, Math.floor(needleFirstLine.length / 2))) return null;
+	const snippet = lines[bestIdx].slice(0, 80);
+	return `line ${bestIdx + 1}: ${JSON.stringify(snippet)}`;
+}
+function sharedPrefixLength(a, b) {
+	const max = Math.min(a.length, b.length);
+	let i = 0;
+	while (i < max && a.charCodeAt(i) === b.charCodeAt(i)) i++;
+	return i;
+}
+//#endregion
+//#region src/tools/glob.ts
+/**
+* Glob-pattern file matching.
+*
+* Uses Bun's native `Bun.Glob` engine when running in the in-process execution
+* context. For non-process contexts (docker, sandbox), falls back to running
+* the pattern through a shell `find` invocation so the match is executed
+* wherever the context lives.
+*
+* Results are capped at 1000 entries to keep model input bounded.
+*
+* By default each row carries `<path>\t<size>\t<mtime>` metadata so the
+* model can rank "what changed recently" without a follow-up `read_file`.
+* Pass `metadata: false` to fall back to plain newline-separated paths.
+* Metadata is best-effort: in-process contexts use `node:fs/promises stat`
+* (parallelized); non-process contexts fall through to the path-only shape
+* since shelling out per file would dominate the call latency.
+*/
+const DEFAULT_LIMIT = 1e3;
+const SAFE_GLOB_PATTERN_RE = /^[\w./*?[\]{}!,^@+-]+$/;
+async function globInProcess(pattern, cwd, limit) {
+	const glob = new Bun.Glob(pattern);
+	const results = [];
+	for await (const file of glob.scan({ cwd })) {
+		results.push(file);
+		if (results.length >= limit) break;
+	}
+	return results.sort();
+}
+async function globViaShell(pattern, ctx, limit) {
+	if (!SAFE_GLOB_PATTERN_RE.test(pattern)) throw new Error("Glob pattern contains unsupported characters (shell fallback only allows path/glob metacharacters)");
+	const searchCmd = `${!pattern.includes("/") ? `find . -type f -name '${pattern}'` : `find . -type f -path './${pattern}'`} 2>/dev/null | sed 's|^./||' | sort | head -n ${limit}`;
+	const result = await ctx.execution.exec(ctx.handle, searchCmd);
+	if (result.exitCode !== 0 && !result.stdout) return [];
+	return result.stdout.split("\n").filter((line) => line.length > 0);
+}
+const glob = {
+	spec: {
+		name: "glob",
+		description: "Match files by glob pattern (supports **, *, ?). Relative to the execution context cwd. By default each row is `<path>\\t<size-bytes>\\t<mtime-iso>`; set `metadata: false` for a plain newline-separated list of paths. Always sorted.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				pattern: {
+					type: "string",
+					description: "Glob pattern (e.g. \"src/**/*.ts\", \"*.md\", \"test/**/fixtures/*\")."
+				},
+				limit: {
+					type: "number",
+					description: `Maximum number of matches to return. Default: ${DEFAULT_LIMIT}.`
+				},
+				metadata: {
+					type: "boolean",
+					description: "Append size (bytes) and mtime (ISO) per row, tab-separated. Default: true. In-process only — non-process execution contexts always return paths."
+				}
+			},
+			required: ["pattern"]
+		}
+	},
+	async execute({ pattern, limit, metadata }, ctx) {
+		const pat = pattern;
+		const max = typeof limit === "number" && limit > 0 ? limit : DEFAULT_LIMIT;
+		const wantMetadata = metadata !== false;
+		try {
+			const entries = ctx.execution.type === "process" ? await globInProcess(pat, ctx.handle.cwd, max) : await globViaShell(pat, ctx, max);
+			if (entries.length === 0) return "(no matches)";
+			if (!wantMetadata || ctx.execution.type !== "process") return entries.join("\n");
+			return (await Promise.all(entries.map(async (rel) => {
+				try {
+					const s = await stat(resolve(ctx.handle.cwd, rel));
+					return `${rel}\t${s.size}\t${new Date(s.mtimeMs).toISOString()}`;
+				} catch {
+					return `${rel}\t\t`;
+				}
+			}))).join("\n");
+		} catch (err) {
+			return `Glob error: ${err instanceof Error ? err.message : String(err)}`;
+		}
+	}
+};
+//#endregion
+//#region src/tools/grep.ts
+/**
+* Search file contents by regex.
+*
+* Wraps ripgrep (`rg`) when available, falls back to an in-process Bun.Glob +
+* regex implementation when running in the in-process execution context. For
+* non-process contexts without `rg`, returns a clear hint rather than silently
+* doing nothing.
+*
+* The tool surface mirrors Claude Code's `Grep` so models authored against the
+* Anthropic tool surface need no relearning. Output modes:
+*   - `files_with_matches` (default) — newline-separated paths.
+*   - `content` — `path:line:match` (line numbers on by default).
+*   - `count` — `path:N` per matching file.
+*
+* Results are capped via `head_limit` (default 250) to keep model input
+* bounded; `offset` lets the caller page through.
+*/
+const DEFAULT_HEAD_LIMIT = 250;
+const DEFAULT_OUTPUT_MODE = "files_with_matches";
+const grep = {
+	spec: {
+		name: "grep",
+		description: "Search file contents by regex. Returns matching paths (default), match content, or per-file counts. Backed by ripgrep when available with a Bun.Glob fallback for in-process runs.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				"pattern": {
+					type: "string",
+					description: "Regex (PCRE-flavored via ripgrep, JS regex via fallback)."
+				},
+				"path": {
+					type: "string",
+					description: "File or directory to search. Default: \".\"."
+				},
+				"glob": {
+					type: "string",
+					description: "Restrict to files matching this glob, e.g. \"**/*.ts\"."
+				},
+				"type": {
+					type: "string",
+					description: "rg file type filter, e.g. \"ts\", \"py\", \"rust\". Ignored by the fallback."
+				},
+				"output_mode": {
+					type: "string",
+					enum: [
+						"content",
+						"files_with_matches",
+						"count"
+					],
+					description: "Default: \"files_with_matches\"."
+				},
+				"-i": {
+					type: "boolean",
+					description: "Case-insensitive match."
+				},
+				"-n": {
+					type: "boolean",
+					description: "Show line numbers (content mode). Default: true."
+				},
+				"-A": {
+					type: "integer",
+					description: "Lines of trailing context (content mode)."
+				},
+				"-B": {
+					type: "integer",
+					description: "Lines of leading context (content mode)."
+				},
+				"-C": {
+					type: "integer",
+					description: "Lines of surrounding context (content mode). Overridden by -A/-B if set."
+				},
+				"multiline": {
+					type: "boolean",
+					description: "Allow patterns to match across line boundaries."
+				},
+				"head_limit": {
+					type: "integer",
+					description: "Cap output entries. Default: 250. Set 0 for unlimited."
+				},
+				"offset": {
+					type: "integer",
+					description: "Skip first N entries. Default: 0."
+				}
+			},
+			required: ["pattern"]
+		}
+	},
+	async execute(rawInput, ctx) {
+		const input = rawInput;
+		if (await isRipgrepAvailable(ctx)) return runViaRipgrep(input, ctx);
+		if (ctx.execution.type === "process") return runInProcess(input, ctx);
+		return "grep error: ripgrep is not available in the execution context. Install `rg` or use the `shell` tool with grep/awk.";
+	}
+};
+/**
+* Probe ripgrep availability **per call**. The probe is intentionally not
+* cached: caching at module scope would leak across execution contexts (an
+* orchestrator running an in-process agent and a docker agent in the same
+* Node process must be able to differ on whether `rg` exists), and caching
+* per handle adds bookkeeping for negligible savings — `rg --version` is
+* ~5 ms, and grep is invoked at most a few times per turn.
+*/
+async function isRipgrepAvailable(ctx) {
+	return (await ctx.execution.exec(ctx.handle, "rg --version")).exitCode === 0;
+}
+async function runViaRipgrep(input, ctx) {
+	const args = ["rg"];
+	const mode = input.output_mode ?? DEFAULT_OUTPUT_MODE;
+	if (mode === "files_with_matches") args.push("--files-with-matches");
+	else if (mode === "count") args.push("--count");
+	else args.push(input["-n"] ?? true ? "--line-number" : "--no-line-number");
+	if (input["-i"]) args.push("-i");
+	if (mode === "content") {
+		if (typeof input["-A"] === "number") args.push("-A", String(input["-A"]));
+		if (typeof input["-B"] === "number") args.push("-B", String(input["-B"]));
+		if (typeof input["-C"] === "number" && typeof input["-A"] !== "number" && typeof input["-B"] !== "number") args.push("-C", String(input["-C"]));
+	}
+	if (input.multiline) args.push("--multiline", "--multiline-dotall");
+	if (input.glob) args.push("--glob", input.glob);
+	if (input.type) args.push("--type", input.type);
+	args.push("--", input.pattern);
+	args.push(input.path ?? ".");
+	const command = args.map(shellQuote).join(" ");
+	const result = await ctx.execution.exec(ctx.handle, command);
+	if (result.exitCode !== 0 && result.exitCode !== 1) return `grep error: ${result.stderr.trim() || `rg exited with code ${result.exitCode}`}`;
+	return formatPaginated(result.stdout, input);
+}
+async function runInProcess(input, ctx) {
+	const mode = input.output_mode ?? DEFAULT_OUTPUT_MODE;
+	const flags = `${input["-i"] ? "i" : ""}${input.multiline ? "s" : ""}${mode !== "content" ? "" : "g"}`;
+	let regex;
+	try {
+		regex = new RegExp(input.pattern, flags || void 0);
+	} catch (err) {
+		return `grep error: invalid regex: ${err.message}`;
+	}
+	const files = await enumerateFiles(input, ctx);
+	const showLineNumbers = input["-n"] ?? true;
+	const before = input["-B"] ?? input["-C"] ?? 0;
+	const after = input["-A"] ?? input["-C"] ?? 0;
+	const lines = [];
+	for (const path of files) {
+		let content;
+		try {
+			content = await ctx.execution.readFile(ctx.handle, path);
+		} catch {
+			continue;
+		}
+		if (input.multiline) {
+			const allMatches = [...content.matchAll(new RegExp(regex.source, `${flags.replace(/g/, "")}g`))];
+			if (allMatches.length === 0) continue;
+			if (mode === "files_with_matches") {
+				lines.push(path);
+				continue;
+			}
+			if (mode === "count") {
+				lines.push(`${path}:${allMatches.length}`);
+				continue;
+			}
+			for (const m of allMatches) {
+				const lineStart = content.lastIndexOf("\n", m.index - 1) + 1;
+				const lineEnd = content.indexOf("\n", m.index);
+				const snippet = content.slice(lineStart, lineEnd === -1 ? void 0 : lineEnd);
+				const lineNo = content.slice(0, m.index).split("\n").length;
+				lines.push(formatContentLine(path, lineNo, snippet, showLineNumbers));
+			}
+			continue;
+		}
+		const fileLines = content.split("\n");
+		const matched = [];
+		for (let i = 0; i < fileLines.length; i++) {
+			regex.lastIndex = 0;
+			if (regex.test(fileLines[i])) matched.push(i);
+		}
+		if (matched.length === 0) continue;
+		if (mode === "files_with_matches") {
+			lines.push(path);
+			continue;
+		}
+		if (mode === "count") {
+			lines.push(`${path}:${matched.length}`);
+			continue;
+		}
+		const includeLineNos = /* @__PURE__ */ new Set();
+		for (const m of matched) for (let i = Math.max(0, m - before); i <= Math.min(fileLines.length - 1, m + after); i++) includeLineNos.add(i);
+		const sorted = [...includeLineNos].sort((a, b) => a - b);
+		let prev = -2;
+		for (const lineNo of sorted) {
+			if (lineNo > prev + 1 && lines.length > 0) lines.push("--");
+			const snippet = fileLines[lineNo];
+			lines.push(formatContentLine(path, lineNo + 1, snippet, showLineNumbers));
+			prev = lineNo;
+		}
+	}
+	return formatPaginated(lines.join("\n"), input);
+}
+function formatContentLine(path, lineNo, snippet, showLineNumbers) {
+	return showLineNumbers ? `${path}:${lineNo}:${snippet}` : `${path}:${snippet}`;
+}
+async function enumerateFiles(input, ctx) {
+	const cwd = ctx.handle.cwd;
+	const root = input.path ?? ".";
+	if (input.path && !input.path.includes("*") && !input.path.includes("?")) try {
+		if ((await ctx.execution.exec(ctx.handle, `test -f ${shellQuote(input.path)} && echo file || echo dir`)).stdout.trim() === "file") return [input.path];
+	} catch {}
+	const pattern = input.glob ?? "**/*";
+	const glob = new Bun.Glob(pattern);
+	const out = [];
+	const scanRoot = root === "." ? cwd : `${cwd.replace(/\/$/, "")}/${root.replace(/^\.\//, "")}`;
+	for await (const file of glob.scan({
+		cwd: scanRoot,
+		onlyFiles: true
+	})) out.push(root === "." ? file : `${root.replace(/\/$/, "")}/${file}`);
+	return out.sort();
+}
+function formatPaginated(text, input) {
+	const headLimit = typeof input.head_limit === "number" && input.head_limit >= 0 ? input.head_limit : DEFAULT_HEAD_LIMIT;
+	const offset = typeof input.offset === "number" && input.offset > 0 ? Math.floor(input.offset) : 0;
+	if (!text.trim()) return "(no matches)";
+	const lines = text.split("\n").filter((l) => l.length > 0);
+	const total = lines.length;
+	const sliced = headLimit === 0 ? lines.slice(offset) : lines.slice(offset, offset + headLimit);
+	if (sliced.length === 0) return "(no matches in this slice)";
+	const truncatedHead = offset > 0;
+	const truncatedTail = headLimit > 0 && offset + headLimit < total;
+	let out = sliced.join("\n");
+	if (truncatedHead) out = `…(${offset} earlier matches skipped)…\n${out}`;
+	if (truncatedTail) out = `${out}\n…(${total - offset - headLimit} more matches; re-run with offset=${offset + headLimit} or larger head_limit)`;
+	return out;
+}
+//#endregion
+//#region src/tools/interaction.ts
+/**
+* Create an interaction tool that lets the agent request structured input.
+*
+* The model calls this tool with a payload matching the schema.
+* `onRequest` is called with the payload and should return the response
+* (string or object) that gets sent back to the model as the tool result.
+*/
+function createInteractionTool(options) {
+	return {
+		spec: {
+			name: options.name ?? "interaction",
+			description: options.description ?? "Request structured input from the user or external system.",
+			inputSchema: options.schema
+		},
+		async execute(input, ctx) {
+			const result = await options.onRequest(input, ctx);
+			return typeof result === "string" ? result : JSON.stringify(result);
+		}
+	};
+}
+//#endregion
+//#region src/tools/list-files.ts
+const listFiles = {
+	spec: {
+		name: "list_files",
+		description: "List files and directories at the given path (relative to project root).",
+		inputSchema: {
+			type: "object",
+			properties: { path: {
+				type: "string",
+				description: "Relative directory path (default: \".\")"
+			} },
+			required: []
+		}
+	},
+	async execute({ path }, ctx) {
+		try {
+			return (await ctx.execution.listFiles(ctx.handle, path || ".")).join("\n") || "(empty directory)";
+		} catch {
+			return `Directory not found: ${path}`;
+		}
+	}
+};
+//#endregion
+//#region src/tools/multi-edit.ts
+const multiEdit = {
+	spec: {
+		name: "multi_edit",
+		description: "Apply a sequential list of edits to a file atomically. Each edit operates on the result of the previous edit. All edits must succeed for any to be written. Prefer this over multiple `edit` calls when several non-overlapping changes are needed in the same file. Each step tolerates `read_file` line-number prefixes (`<N>\\t…`, `<N>|…`, or `<N>→…`) in `old_string` / `new_string`.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Relative file path."
+				},
+				edits: {
+					type: "array",
+					description: "List of edits applied in order; each operates on the previous edit's output.",
+					items: {
+						type: "object",
+						properties: {
+							old_string: { type: "string" },
+							new_string: { type: "string" },
+							replace_all: { type: "boolean" }
+						},
+						required: ["old_string", "new_string"]
+					}
+				}
+			},
+			required: ["path", "edits"]
+		}
+	},
+	async execute({ path, edits }, ctx) {
+		const target = path;
+		const steps = edits;
+		if (!Array.isArray(steps) || steps.length === 0) return `multi_edit error: edits must be a non-empty array.`;
+		let current;
+		try {
+			current = await ctx.execution.readFile(ctx.handle, target);
+		} catch {
+			return `multi_edit error: file not found: ${target}.${await suggestionFor(ctx.execution, ctx.handle, target)}`;
+		}
+		if (ctx.behavior?.requireReadBeforeEdit && ctx.session) {
+			const readState = getReadState(ctx.session);
+			const absKey = `${ctx.handle.cwd}::${target}`;
+			const prior = readState?.get(absKey);
+			if (!prior) return `multi_edit error: ${target} has not been read in this session. Call read_file first so the edits apply against the current contents.`;
+			if (prior.contentHash !== hashContent(current)) return `multi_edit error: ${target} has changed on disk since the last read. Re-read the file before editing.`;
+		}
+		let applied = 0;
+		for (let i = 0; i < steps.length; i++) {
+			const step = steps[i];
+			const find = step.old_string;
+			const replacement = step.new_string;
+			const replaceAll = step.replace_all === true;
+			if (typeof find !== "string" || typeof replacement !== "string") return `multi_edit error: edit #${i + 1} is missing old_string or new_string.`;
+			if (find.length === 0) return `multi_edit error: edit #${i + 1} has empty old_string. Use write_file to fully replace a file.`;
+			if (find === replacement) return `multi_edit error: edit #${i + 1} old_string and new_string are identical.`;
+			const match = resolveOldString(current, find);
+			if (!match) return `multi_edit error: edit #${i + 1} old_string not found in ${target}.`;
+			const { actual, occurrences, via } = match;
+			if (occurrences > 1 && !replaceAll) return `multi_edit error: edit #${i + 1} old_string appears ${occurrences} times. Pass replace_all=true on this edit or expand old_string for uniqueness.`;
+			const styledReplacement = styleReplacementForVia(replacement, via, actual);
+			current = replaceAll ? current.split(actual).join(styledReplacement) : current.replace(actual, styledReplacement);
+			applied += occurrences;
+		}
+		await ctx.execution.writeFile(ctx.handle, target, current);
+		if (ctx.session) {
+			const readState = getReadState(ctx.session);
+			const absKey = `${ctx.handle.cwd}::${target}`;
+			const prior = readState?.get(absKey);
+			if (readState && prior) readState.set(absKey, {
+				...prior,
+				contentHash: hashContent(current),
+				mtimeMs: Date.now()
+			});
+		}
+		return `Edited ${target}: applied ${steps.length} edit${steps.length === 1 ? "" : "s"} (${applied} replacement${applied === 1 ? "" : "s"}).`;
+	}
+};
+//#endregion
+//#region src/tools/binary-read.ts
+/**
+* Best-effort guess at IANA media type from a file extension. Covers the
+* extensions Zidane's `read_file` actually dispatches to image blocks
+* (png/jpg/jpeg/gif/webp). Other extensions return `undefined` and the
+* caller short-circuits the binary route.
+*/
+function imageMediaTypeFor(path) {
+	const dot = path.lastIndexOf(".");
+	if (dot === -1) return void 0;
+	switch (path.slice(dot + 1).toLowerCase()) {
+		case "png": return "image/png";
+		case "jpg":
+		case "jpeg": return "image/jpeg";
+		case "gif": return "image/gif";
+		case "webp": return "image/webp";
+		default: return;
+	}
+}
+/**
+* Read a file as base64. Prefers `ExecutionContext.readFileBinary` (zero
+* subprocess overhead in-process) and falls back to `base64 < path` via
+* the shell seam — works on docker / sandbox without an interface change.
+*
+* Returns `{ base64, byteLength }`. `byteLength` is the *decoded* byte count
+* so callers can size-budget against the original file, not the inflated
+* base64 representation (which is ~4/3× larger).
+*/
+async function readFileAsBase64(execution, handle, path) {
+	if (execution.readFileBinary) {
+		const bytes = await execution.readFileBinary(handle, path);
+		return {
+			base64: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64"),
+			byteLength: bytes.byteLength
+		};
+	}
+	const cmd = `base64 < ${alwaysQuote(path)}`;
+	const result = await execution.exec(handle, cmd);
+	if (result.exitCode !== 0) throw new Error(`base64 read failed: ${result.stderr || `exit ${result.exitCode}`}`);
+	const b64 = result.stdout.replace(/\s+/g, "");
+	return {
+		base64: b64,
+		byteLength: decodedBase64ByteLength(b64)
+	};
+}
+/**
+* Decoded byte length of a (whitespace-stripped) base64 string. Accounts for
+* `=` padding so the value matches the original file size to the byte —
+* `Math.floor(len * 3 / 4)` over-reports by 1–2 bytes on padded payloads.
+*/
+function decodedBase64ByteLength(b64) {
+	if (b64.length === 0) return 0;
+	let pad = 0;
+	if (b64.endsWith("==")) pad = 2;
+	else if (b64.endsWith("=")) pad = 1;
+	return Math.max(0, b64.length * 3 / 4 - pad);
+}
+//#endregion
+//#region src/tools/read-file.ts
+/**
+* Read a file with line-based offset/limit and a hard byte cap.
+*
+* Defaults are tuned for source code: 2000 lines / 256 KiB. A typical source
+* file, lockfile, or large config fits in one read; logs and very large
+* fixtures get truncated with a footer that documents how to fetch the
+* remainder.
+*
+* Binary files are detected on the leading bytes — if the buffer contains a
+* NUL or has an unreasonable proportion of non-printable bytes, we skip text
+* decoding and return a marker so the model doesn't drown in mojibake.
+*/
+const DEFAULT_LINE_LIMIT = 2e3;
+const DEFAULT_BYTE_CAP = 262144;
+/**
+* Hard upper bound on raw image bytes we'll inline as a base64 image block.
+* Above this, we return a marker instead — the model won't get useful
+* information from a 10 MB+ screenshot rendered as one tool result, and
+* the wire bill gets ugly. Override via the `maxBytes` parameter on the
+* tool call.
+*/
+const DEFAULT_IMAGE_BYTE_CAP = 5 * 1024 * 1024;
+const readFile$1 = {
+	spec: {
+		name: "read_file",
+		description: "Read a file by path. Returns lines [offset..offset+limit). Default offset=1, limit=2000. Each line is prefixed with its 1-indexed line number followed by a tab (e.g. `42\\tconst foo = bar`); the prefix is metadata, not part of the file. Mirrors Claude Code's `cat -n`-style compact output for token efficiency. A trailing footer explains how to read the rest when truncated. Binary files return a short marker rather than mojibake.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Relative file path."
+				},
+				offset: {
+					type: "integer",
+					description: "1-indexed line number to start from. Default: 1."
+				},
+				limit: {
+					type: "integer",
+					description: "Max lines to return. Default: 2000. Set 0 for unlimited."
+				},
+				maxBytes: {
+					type: "integer",
+					description: "Hard byte cap on file content read, regardless of line count. Default: 262144. Set 0 for unlimited. The rendered output may be slightly larger than this cap when `lineNumbers` is on (each line carries a `<N>\\t` prefix)."
+				},
+				lineNumbers: {
+					type: "boolean",
+					description: "Prefix each line with its 1-indexed line number. Default: true. Override the agent-wide `behavior.readLineNumbers` for this call."
+				}
+			},
+			required: ["path"]
+		}
+	},
+	async execute({ path, offset, limit, maxBytes, lineNumbers }, ctx) {
+		const imgMedia = imageMediaTypeFor(path);
+		if (imgMedia) {
+			const sizeCap = maxBytes !== void 0 ? normalizeInteger(maxBytes, DEFAULT_IMAGE_BYTE_CAP) : DEFAULT_IMAGE_BYTE_CAP;
+			try {
+				const { base64, byteLength } = await readFileAsBase64(ctx.execution, ctx.handle, path);
+				if (sizeCap > 0 && byteLength > sizeCap) return `[image too large to inline: ${path}, ${byteLength} bytes (cap ${sizeCap}). Raise maxBytes, or use shell to inspect.]`;
+				return [{
+					type: "text",
+					text: `Image: ${path} (${byteLength} bytes, ${imgMedia})`
+				}, {
+					type: "image",
+					mediaType: imgMedia,
+					data: base64
+				}];
+			} catch (err) {
+				return `Image read failed: ${path} — ${err instanceof Error ? err.message : String(err)}.${await suggestionFor(ctx.execution, ctx.handle, path)}`;
+			}
+		}
+		let raw;
+		try {
+			raw = await ctx.execution.readFile(ctx.handle, path);
+		} catch {
+			return `File not found: ${path}.${await suggestionFor(ctx.execution, ctx.handle, path)}`;
+		}
+		const totalBytes = Buffer.byteLength(raw);
+		const readState = ctx.behavior?.dedupReads !== false ? getReadState(ctx.session) : void 0;
+		const absKey = `${ctx.handle.cwd}::${path}`;
+		const offsetForKey = normalizeInteger(offset, 1);
+		const limitForKey = normalizeInteger(limit, DEFAULT_LINE_LIMIT);
+		const maxBytesForKey = normalizeInteger(maxBytes, DEFAULT_BYTE_CAP);
+		const showLineNumbers = typeof lineNumbers === "boolean" ? lineNumbers : ctx.behavior?.readLineNumbers ?? true;
+		const currentHash = readState ? hashContent(raw) : "";
+		if (readState) {
+			const prior = readState.get(absKey);
+			if (prior && prior.contentHash === currentHash && prior.offset === offsetForKey && prior.limit === limitForKey && prior.maxBytes === maxBytesForKey && prior.lineNumbers === showLineNumbers) return `File ${path} unchanged since the previous read in this session — the prior result is still current.`;
+		}
+		if (looksBinary(raw)) return `[binary file: ${path}, ${totalBytes} bytes; use shell with hexdump | xxd | od to inspect]`;
+		const offsetN = offsetForKey;
+		const limitN = limitForKey;
+		const maxBytesN = maxBytesForKey;
+		const lines = raw.split("\n");
+		const totalLines = lines.length;
+		const startIdx = Math.max(0, offsetN - 1);
+		const endIdx = limitN > 0 ? Math.min(totalLines, startIdx + limitN) : totalLines;
+		let slice = lines.slice(startIdx, endIdx);
+		let bytesCut = false;
+		if (maxBytesN > 0) {
+			const truncatedSlice = [];
+			let bytesUsed = 0;
+			for (const line of slice) {
+				const lineBytes = Buffer.byteLength(line) + 1;
+				if (bytesUsed + lineBytes > maxBytesN && truncatedSlice.length > 0) {
+					bytesCut = true;
+					break;
+				}
+				truncatedSlice.push(line);
+				bytesUsed += lineBytes;
+				if (bytesUsed >= maxBytesN) break;
+			}
+			if (truncatedSlice.length < slice.length) bytesCut = true;
+			slice = truncatedSlice;
+		}
+		let midLineCut = false;
+		if (maxBytesN > 0 && slice.length > 0) {
+			if (Buffer.byteLength(slice.join("\n")) > maxBytesN) {
+				const lastIdx = slice.length - 1;
+				const lastLine = slice[lastIdx];
+				const otherBytes = lastIdx > 0 ? Buffer.byteLength(slice.slice(0, lastIdx).join("\n")) + 1 : 0;
+				const budgetForLast = Math.max(0, maxBytesN - otherBytes);
+				let cut = Math.min(lastLine.length, budgetForLast);
+				while (cut > 0 && Buffer.byteLength(lastLine.slice(0, cut)) > budgetForLast) cut--;
+				slice[lastIdx] = lastLine.slice(0, cut);
+				midLineCut = true;
+				bytesCut = true;
+			}
+		}
+		const lastLineRead = startIdx + slice.length;
+		const body = showLineNumbers ? slice.map((line, i) => `${startIdx + i + 1}\t${line}`).join("\n") : slice.join("\n");
+		if (readState) readState.set(absKey, {
+			contentHash: currentHash,
+			offset: offsetN,
+			limit: limitN,
+			maxBytes: maxBytesN,
+			lineNumbers: showLineNumbers,
+			mtimeMs: Date.now()
+		});
+		const linesTruncated = endIdx < totalLines || bytesCut;
+		if (!linesTruncated && offsetN === 1) return body;
+		if (!linesTruncated) return `${body}\n\n…read lines ${offsetN}-${lastLineRead} of ${totalLines}.`;
+		if (midLineCut) return `${body}\n\n…truncated mid-line at line ${lastLineRead} (byte cap ${maxBytesN} reached). File has ${totalLines} lines, ${totalBytes} bytes total. Raise maxBytes to read the full line.`;
+		return `${body}\n\n…truncated at line ${lastLineRead} (${bytesCut ? `byte cap (${maxBytesN}) reached` : `line limit (${limitN}) reached`}). File has ${totalLines} lines, ${totalBytes} bytes total — re-read with offset=${lastLineRead + 1} to continue.`;
+	}
+};
+function normalizeInteger(value, fallback) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+	if (value < 0) return 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;
+const shell = {
+	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.",
+		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"]
+		}
+	},
+	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)}`;
+	}
+};
+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 = [
+	"stream:text",
+	"stream:thinking",
+	"stream:end",
+	"tool:before",
+	"tool:after",
+	"tool:error",
+	"turn:after"
+];
+const CHILD_EVENT_NAME = {
+	"stream:text": "child:stream:text",
+	"stream:thinking": "child:stream:thinking",
+	"stream:end": "child:stream:end",
+	"tool:before": "child:tool:before",
+	"tool:after": "child:tool:after",
+	"tool:error": "child:tool:error",
+	"turn:after": "child:turn:after"
+};
+function extractText(message) {
+	if (!message || typeof message !== "object") return "";
+	const msg = message;
+	if (typeof msg.content === "string") return msg.content;
+	if (Array.isArray(msg.content)) return msg.content.filter((block) => !!block && typeof block === "object" && block.type === "text").map((block) => block.text).join("\n");
+	return "";
+}
+/**
+* Race `task` (an already-running child `agent.run()` promise) against a
+* timer. Does NOT race against the parent abort signal — the child agent
+* already observes the same signal internally and handles its own aborted
+* bookkeeping, so racing here would detach the spawn from the child's
+* session-persisting finally block.
+*
+* On timeout: rejects with `SpawnTimeoutError`; caller is expected to call
+* `agent.abort()` and subsequently `await` the original `task` so the
+* child's session state (runs, turns, status) gets flushed before the
+* parent moves on.
+*/
+async function raceWithTimeout(task, timeoutMs) {
+	if (!timeoutMs || timeoutMs <= 0) return task;
+	let timer;
+	try {
+		return await new Promise((resolve, reject) => {
+			timer = setTimeout(() => reject(new SpawnTimeoutError(timeoutMs)), timeoutMs);
+			task.then(resolve, reject);
+		});
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+var SpawnTimeoutError = class extends Error {
+	timeoutMs;
+	constructor(timeoutMs) {
+		super(`Child agent timed out after ${timeoutMs}ms`);
+		this.name = "SpawnTimeoutError";
+		this.timeoutMs = timeoutMs;
+	}
+};
+/**
+* Wire child's hooks to bubble into `parentHooks` as `child:*` events.
+*
+* Two kinds of forwarding:
+*
+* 1. **Originating events** (`stream:text`, `tool:before`, …) → rewrite to
+*    the matching `child:*` event, inject `{ childId, depth }` from this
+*    spawn, then fire on the parent's hook bus.
+* 2. **Re-bubbled events** (`child:stream:text`, `child:tool:before`, …)
+*    from a grandchild already carry `childId` + `depth` pointing at the
+*    originating subagent. Forward them verbatim so the top-level listener
+*    sees the correct ancestry, not the immediate parent's.
+*
+* Returns a function that unregisters every listener registered here.
+* Called before `agent.run()` starts, torn down in a finally block — so
+* nothing leaks even if the child throws mid-run.
+*/
+function bubbleHooks(childHooks, parentHooks, childId, depth) {
+	const unregisters = [];
+	const fire = parentHooks.callHook;
+	for (const evt of BUBBLED_EVENTS) {
+		const parentEvt = CHILD_EVENT_NAME[evt];
+		const unregister = childHooks.hook(evt, (ctx) => {
+			fire(parentEvt, {
+				...ctx,
+				childId,
+				depth
+			});
+		});
+		unregisters.push(unregister);
+	}
+	for (const evt of BUBBLED_EVENTS) {
+		const parentEvt = CHILD_EVENT_NAME[evt];
+		const unregister = childHooks.hook(parentEvt, (ctx) => {
+			fire(parentEvt, ctx);
+		});
+		unregisters.push(unregister);
+	}
+	return () => {
+		for (const u of unregisters) u();
+	};
+}
+/**
+* Create a configured spawn tool.
+*
+* State (`children`, `totalChildStats`, counters, active count) is scoped to
+* the returned instance. Multiple parent agents using the same instance will
+* share counters + stats + concurrency slots — call `createSpawnTool()` per
+* agent (or use the stateless default `spawn`) to keep them isolated.
+*/
+function createSpawnTool(options = {}) {
+	const localChildren = /* @__PURE__ */ new Map();
+	let localCounter = 0;
+	let localActiveCount = 0;
+	const maxConcurrent = options.maxConcurrent ?? 3;
+	const maxDepth = options.maxDepth ?? 3;
+	const forwardHooks = options.forwardHooks ?? true;
+	const localStats = {
+		totalIn: 0,
+		totalOut: 0,
+		totalCacheRead: 0,
+		totalCacheCreation: 0,
+		turns: 0,
+		elapsed: 0
+	};
+	return {
+		get children() {
+			return localChildren;
+		},
+		get totalChildStats() {
+			return { ...localStats };
+		},
+		spec: {
+			name: "spawn",
+			description: "Spawn a sub-agent for a self-contained task that benefits from isolation (separate context window, separate retries) — for example, a deep research dive or a long codegen pass on a specific file. The sub-agent runs independently with its own tool access and returns its final response. Do NOT spawn for sequential steps you could do yourself.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					task: {
+						type: "string",
+						description: "The task prompt for the sub-agent. Be specific about what you want it to accomplish."
+					},
+					system: {
+						type: "string",
+						description: "Optional system prompt override for this specific sub-agent."
+					}
+				},
+				required: ["task"]
+			}
+		},
+		async execute(input, ctx) {
+			const task = input.task;
+			const systemOverride = input.system;
+			const parentDepth = ctx.depth ?? 0;
+			const childDepth = parentDepth + 1;
+			if (childDepth > maxDepth) return `Cannot spawn: maxDepth=${maxDepth} reached (parent depth=${parentDepth}). Deepen the cap with createSpawnTool({ maxDepth }).`;
+			if (localActiveCount >= maxConcurrent) return `Cannot spawn: ${localActiveCount}/${maxConcurrent} sub-agents already running. Wait for one to complete.`;
+			if (ctx.signal.aborted) return `[sub-agent pre-aborted] Parent signal was already aborted — skipped "${task.slice(0, 80)}"`;
+			const id = `child-${++localCounter}`;
+			localActiveCount++;
+			const child = {
+				id,
+				task,
+				startedAt: Date.now(),
+				depth: childDepth
+			};
+			localChildren.set(id, child);
+			let destroyError;
+			let childRunStatus = "completed";
+			let finalStats;
+			let result = "";
+			let unbubble;
+			try {
+				const agent = createAgent({
+					...ctx.name !== void 0 ? { name: ctx.name } : {},
+					...ctx.system !== void 0 ? { system: ctx.system } : {},
+					tools: ctx.tools,
+					...ctx.toolAliases !== void 0 ? { toolAliases: ctx.toolAliases } : {},
+					...ctx.mcpServers !== void 0 ? { mcpServers: ctx.mcpServers } : {},
+					...ctx.skills !== void 0 ? { skills: ctx.skills } : {},
+					...ctx.behavior !== void 0 ? { behavior: ctx.behavior } : {},
+					...options.preset,
+					provider: ctx.provider,
+					execution: ctx.execution,
+					...options.persist && ctx.session ? { session: ctx.session } : {}
+				});
+				if (forwardHooks) unbubble = bubbleHooks(agent.hooks, ctx.hooks, id, childDepth);
+				options.onSpawn?.(child);
+				await ctx.hooks.callHook("spawn:before", {
+					id,
+					task,
+					depth: childDepth
+				});
+				const runPromise = agent.run({
+					prompt: task,
+					model: options.model,
+					system: systemOverride ?? options.system,
+					thinking: options.thinking,
+					signal: ctx.signal,
+					depth: childDepth,
+					...options.persist && ctx.runId ? { parentRunId: ctx.runId } : {}
+				});
+				try {
+					finalStats = await raceWithTimeout(runPromise, options.timeoutMs);
+					const treeTurns = flattenTurns(finalStats).length;
+					if (ctx.signal.aborted) {
+						childRunStatus = "aborted";
+						result = [`[sub-agent ${id}] Aborted after ${treeTurns} turns (${finalStats.elapsed}ms)`, `Tokens: ${finalStats.totalIn} in / ${finalStats.totalOut} out`].join("\n");
+					} else {
+						const response = extractText(agent.turns.at(-1));
+						result = [
+							`[sub-agent ${id}] Completed in ${treeTurns} turns (${finalStats.elapsed}ms)`,
+							`Tokens: ${finalStats.totalIn} in / ${finalStats.totalOut} out`,
+							"",
+							response || "(no text response)"
+						].join("\n");
+					}
+				} catch (err) {
+					if (err instanceof SpawnTimeoutError) {
+						childRunStatus = "timeout";
+						agent.abort();
+						try {
+							finalStats = await runPromise;
+						} catch {
+							finalStats = {
+								totalIn: 0,
+								totalOut: 0,
+								totalCacheRead: 0,
+								totalCacheCreation: 0,
+								turns: 0,
+								elapsed: err.timeoutMs
+							};
+						}
+						result = `[sub-agent ${id}] Timed out after ${err.timeoutMs}ms`;
+					} else {
+						const error = err instanceof Error ? err : new Error(String(err));
+						childRunStatus = "error";
+						finalStats = {
+							totalIn: 0,
+							totalOut: 0,
+							totalCacheRead: 0,
+							totalCacheCreation: 0,
+							turns: 0,
+							elapsed: 0
+						};
+						result = `[sub-agent ${id}] Error: ${error.message}`;
+						await ctx.hooks.callHook("spawn:error", {
+							id,
+							task,
+							depth: childDepth,
+							error
+						});
+					}
+				} finally {
+					try {
+						await agent.destroy();
+					} catch (err) {
+						destroyError = err instanceof Error ? err : new Error(String(err));
+					}
+				}
+				if (finalStats) {
+					localStats.totalIn += finalStats.totalIn;
+					localStats.totalOut += finalStats.totalOut;
+					localStats.totalCacheRead += finalStats.totalCacheRead;
+					localStats.totalCacheCreation += finalStats.totalCacheCreation;
+					localStats.turns += finalStats.turns;
+					localStats.elapsed += finalStats.elapsed;
+				}
+				const childRunStats = {
+					id,
+					task,
+					stats: finalStats,
+					depth: childDepth,
+					status: childRunStatus,
+					...finalStats.output ? { output: finalStats.output } : {}
+				};
+				options.onComplete?.(child, finalStats, childRunStatus);
+				await ctx.hooks.callHook("spawn:complete", childRunStats);
+				if (destroyError) await ctx.hooks.callHook("spawn:error", {
+					id,
+					task,
+					depth: childDepth,
+					error: destroyError
+				});
+				return result;
+			} finally {
+				unbubble?.();
+				localActiveCount--;
+				localChildren.delete(id);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/tools/write-file.ts
+/**
+* Write a file, with an idempotency signal when the content is unchanged.
+*
+* Three return shapes — chosen so the model can recognize a no-op without a
+* separate read:
+*   - `Created path (N bytes)` — file did not exist
+*   - `Updated path (N bytes)` — content differed from on-disk
+*   - `No change needed: path already at target state (N bytes)` — equal
+*
+* Race window: in non-process execution contexts (docker, sandbox) shared by
+* multiple agents, another writer can mutate the file between our read and
+* our write. Local process context is single-writer per agent so the race is
+* a non-issue there. Documented rather than locked because the cost of
+* cross-context locking outweighs the cost of a stale "No change" message.
+*/
+const writeFile$1 = {
+	spec: {
+		name: "write_file",
+		description: "Write content to a file (creates parent directories). Returns Created / Updated / \"No change needed\" so the model can detect no-ops without a separate read.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Relative file path."
+				},
+				content: {
+					type: "string",
+					description: "File content."
+				}
+			},
+			required: ["path", "content"]
+		}
+	},
+	async execute({ path, content }, ctx) {
+		const targetPath = path;
+		const targetContent = content;
+		let existing;
+		try {
+			existing = await ctx.execution.readFile(ctx.handle, targetPath);
+		} catch {}
+		const bytes = Buffer.byteLength(targetContent);
+		if (existing === targetContent) return `No change needed: ${targetPath} already at target state (${bytes} bytes).`;
+		await ctx.execution.writeFile(ctx.handle, targetPath, targetContent);
+		return existing === void 0 ? `Created ${targetPath} (${bytes} bytes).` : `Updated ${targetPath} (${bytes} bytes).`;
+	}
+};
+//#endregion
+export { multiEdit as a, grep as c, createAgent as d, createToolSearchTool as f, validateToolArgs as g, createSkillsReadTool as h, readFile$1 as i, glob as l, createSkillsRunScriptTool as m, createSpawnTool as n, listFiles as o, createSkillsUseTool as p, shell as r, createInteractionTool as s, writeFile$1 as t, edit as u };
+
+//# sourceMappingURL=tools-DpeWKzP1.js.map