zidane 5.3.1 → 5.4.0

package/dist/{tools-CWEDS2ZT.js → tools-DKdyPoUf.js}

@@ -2,7 +2,7 @@ import { n as createProcessContext } from "./contexts-BwiHIr2w.js";
 import { a as AgentToolPairingError, l as toTypedError, r as AgentProviderError, s as errorMessage, t as AgentAbortedError } from "./errors-Byb0F8B9.js";
 import { t as toolOutputByteLength } from "./types-IcokUOyC.js";
 import { a as detectTurnInterruption, n as SYNTHETIC_TOOL_RESULT_PLACEHOLDER, o as ensureToolResultPairing, s as filterUnresolvedToolUses } from "./messages-D0xT979U.js";
-import { t as connectMcpServers } from "./mcp-ZsSFo4Dp.js";
+import { t as connectMcpServers } from "./mcp-DhmmJfxK.js";
 import { _ as validateResourcePath, b as createSkillActivationState, d as escapeXml, n as resolveSkills, p as installAllowedToolsGate, t as interpolateShellCommands, u as buildCatalog } from "./interpolate-ERgZUxgg.js";
 import { n as formatTokenUsage, t as flattenTurns } from "./stats-DgOvY7wd.js";
 import { createHooks } from "hookable";
@@ -107,8 +107,14 @@ function rewriteMessagesToWire(messages, maps) {
 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.
+* when no session is provided.
+*
+* Most tool callers should prefer {@link resolveReadStateMap}, which
+* additionally honors an explicit `ctx.readState` (the path
+* `spawn`'s `shareReadState: true` uses to forward the parent's map
+* into a sessionless child). Use this helper directly only when the
+* Session-keyed map is exactly what you want and you don't need to
+* accept an override.
 */
 function getReadState(session) {
 	if (!session) return void 0;
@@ -119,19 +125,38 @@ function getReadState(session) {
 	}
 	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".
+* Resolve the active read-state map from a tool context. An explicit
+* `ctx.readState` wins (used by `spawn`'s `shareReadState` opt-in to
+* forward the parent's map into a sessionless child); otherwise the
+* usual `Session`-keyed lookup applies.
+*
+* Tools should call this helper instead of `getReadState(ctx.session)`
+* directly so the `shareReadState` plumbing is honored uniformly.
 */
-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;
+function resolveReadStateMap(ctx) {
+	return ctx.readState ?? getReadState(ctx.session);
+}
+/**
+* Canonical read-state key for a `(cwd, path)` pair.
+*
+* `ctx.execution.readFile(handle, path)` resolves the model-provided
+* path against `handle.cwd` before touching disk — so `src/App.tsx`,
+* `./src/App.tsx`, and `/abs/cwd/src/App.tsx` all read the **same**
+* bytes. The read-state map MUST mirror that resolution: without it,
+* a model that reads `src/App.tsx` and then edits `./src/App.tsx`
+* trips the `requireReadBeforeEdit` gate for a file it demonstrably
+* already saw (the gate's "has not been read in this session" message
+* fires on a stale key).
+*
+* `node:path`'s `resolve(cwd, path)` short-circuits when `path` is
+* already absolute, so absolute and relative shapes converge on the
+* same canonical form. We don't `realpath()` symlinks — the file IS
+* the path the model addressed, not the realpath behind it; the host's
+* execution context decides how to dereference.
+*/
+function readStateKey(cwd, path) {
+	return resolve(cwd, path);
 }
 /**
 * FNV-1a 32-bit hash, hex-encoded. Fast, non-cryptographic — we only need
@@ -147,6 +172,20 @@ function hashContent(text) {
 	}
 	return h.toString(16).padStart(8, "0");
 }
+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;
+}
 //#endregion
 //#region src/dedup-tools.ts
 /**
@@ -766,20 +805,13 @@ const IMAGE_OMITTED_MARKER = "[image omitted — model does not support vision]"
 const INTERRUPT_MESSAGE_FOR_TOOL_USE = "[Request interrupted by user for tool use]";
 /**
 * Canonical tool_result text emitted when a tool call is skipped because a
-* sibling sequential call errored or a steering message arrived between
-* iterations of {@link executeToolsSequential}. Distinguished from
-* {@link INTERRUPT_MESSAGE_FOR_TOOL_USE} so consumers can distinguish "user
+* steering message arrived between dispatches inside
+* {@link executeToolBatch}. Distinguished from
+* {@link INTERRUPT_MESSAGE_FOR_TOOL_USE} so consumers can split "user
 * cancelled" from "framework superseded".
 */
 const TOOL_USE_SKIPPED_MESSAGE = "[Tool use skipped — superseded by user message]";
 /**
-* Canonical tool_result text emitted when the loop catches a sequential
-* sibling that threw and synthesizes follow-up results for the remaining
-* queued calls. Distinct from {@link TOOL_USE_SKIPPED_MESSAGE} so telemetry
-* can split "skipped by user steering" from "skipped after error".
-*/
-const TOOL_USE_AFTER_ERROR_MESSAGE = "[Tool use skipped — previous tool call in batch threw]";
-/**
 * 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.
@@ -1067,19 +1099,21 @@ function applyStaleReadElision(messages) {
 }
 /**
 * Drop read-state entries for paths whose reads got elided. Keys are
-* `${cwd}::${path}` (see `src/tools/read-file.ts`); we don't know the
-* cwd in this context, so we match by `::<path>` suffix. Safe because
-* paths inside the read-state map come from a single session bound to
-* one cwd in practice; an accidental cross-cwd collision would also
-* have to share an identical relative path, in which case force-fresh
-* is the correct behavior anyway.
+* canonical absolute paths produced by `readStateKey(cwd, path)` (see
+* `src/tools/read-state.ts`); the loop has `ctx.handle.cwd` in scope,
+* so we re-derive each elided path's canonical key and delete by
+* direct lookup. No suffix matching, no cross-cwd ambiguity.
+*
+* Resolves the map via `resolveReadStateMap` so a child agent running
+* with a parent's shared map (via `shareReadState`) invalidates the
+* shared entries too — otherwise a child's `read → edit → re-read`
+* would dedup-hit on the now-stale parent entry.
 */
-function invalidateReadStateForElidedPaths(session, elidedPaths) {
-	if (!session || elidedPaths.length === 0) return;
-	const readState = getReadState(session);
+function invalidateReadStateForElidedPaths(ctx, cwd, elidedPaths) {
+	if (elidedPaths.length === 0) return;
+	const readState = resolveReadStateMap(ctx);
 	if (!readState || readState.size === 0) return;
-	const suffixes = elidedPaths.map((p) => `::${p}`);
-	for (const key of [...readState.keys()]) if (suffixes.some((s) => key.endsWith(s))) readState.delete(key);
+	for (const p of elidedPaths) readState.delete(readStateKey(cwd, p));
 }
 /**
 * Run {@link ensureToolResultPairing} with the loop's hook + strict-mode
@@ -1265,7 +1299,7 @@ async function executeTurn(ctx, turn) {
 	if (ctx.elideStaleReads === true) {
 		const elision = applyStaleReadElision(canonicalMessages);
 		canonicalMessages = elision.messages;
-		invalidateReadStateForElidedPaths(ctx.session, elision.elidedPaths);
+		invalidateReadStateForElidedPaths(ctx, ctx.handle.cwd, elision.elidedPaths);
 	}
 	const wireMessages = rewriteMessagesToWire(canonicalMessages, ctx.aliasMaps);
 	let sanitizedMessages = sanitizeStoredToolResults(ctx.provider, wireMessages);
@@ -1477,7 +1511,7 @@ async function executeTurn(ctx, turn) {
 			usage: result.usage
 		};
 	}
-	const toolResults = ctx.toolExecution === "parallel" ? await executeToolsParallel(ctx, canonicalToolCalls, turnId) : await executeToolsSequential(ctx, canonicalToolCalls, turnId);
+	const toolResults = await executeToolBatch(ctx, canonicalToolCalls, turnId);
 	const toolResultMsg = ctx.provider.toolResultsMessage(toolResults);
 	const toolResultsTurn = {
 		id: await ctx.generateTurnId(),
@@ -1539,17 +1573,35 @@ function stripImagesForNonVision(provider, output) {
 	if (provider.meta.capabilities?.vision !== false) return output;
 	return output.map((b) => b.type === "image" ? IMAGE_OMITTED_MARKER : b.text).join("\n");
 }
+/**
+* Build the per-call base for every `tool:*` hook ctx (and the
+* matching shape for `mcp:tool:*`). Centralized so the `runId` /
+* `parentRunId` / `depth` identity fields land uniformly on every
+* event the loop fires — without one helper they drift across ~14
+* inline construction sites. The returned object IS the
+* {@link ToolHookContext} canonical shape; specialized hook payloads
+* (`gateCtx`, `transformCtx`, etc.) spread it and append their own
+* fields.
+*/
+function buildToolHookBase(ctx, turnId, callId, name, displayName, input) {
+	return {
+		turnId,
+		callId,
+		name,
+		displayName,
+		input,
+		...ctx.runId !== void 0 ? { runId: ctx.runId } : {},
+		...ctx.parentRunId !== void 0 ? { parentRunId: ctx.parentRunId } : {},
+		...typeof ctx.depth === "number" ? { depth: ctx.depth } : {}
+	};
+}
 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,
+		...buildToolHookBase(ctx, turnId, callId, call.name, displayName, call.input),
 		block: false,
 		reason: "Tool execution was blocked",
 		runToolCounts
@@ -1602,11 +1654,7 @@ async function executeSingleTool(ctx, call, turnId) {
 	let effectiveInput = gateCtx.input;
 	if (!toolDef) {
 		const unknownCtx = {
-			turnId,
-			callId,
-			name: call.name,
-			displayName,
-			input: effectiveInput,
+			...buildToolHookBase(ctx, turnId, callId, call.name, displayName, effectiveInput),
 			suppressError: false
 		};
 		await ctx.hooks.callHook("tool:unknown", unknownCtx);
@@ -1615,11 +1663,7 @@ async function executeSingleTool(ctx, call, turnId) {
 		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,
+				...buildToolHookBase(ctx, turnId, callId, call.name, displayName, effectiveInput),
 				error: err
 			});
 		}
@@ -1641,11 +1685,7 @@ async function executeSingleTool(ctx, call, turnId) {
 	const validation = validateToolArgs(effectiveInput, toolDef.spec.inputSchema);
 	if (!validation.valid) {
 		await ctx.hooks.callHook("validation:reject", {
-			turnId,
-			callId,
-			name: call.name,
-			displayName,
-			input: effectiveInput,
+			...buildToolHookBase(ctx, turnId, callId, call.name, displayName, effectiveInput),
 			reason: validation.error ?? "invalid input",
 			schema: toolDef.spec.inputSchema
 		});
@@ -1667,11 +1707,7 @@ async function executeSingleTool(ctx, call, turnId) {
 	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,
+		...buildToolHookBase(ctx, turnId, callId, call.name, displayName, effectiveInput),
 		coercions,
 		schema: toolDef.spec.inputSchema
 	});
@@ -1685,11 +1721,7 @@ async function executeSingleTool(ctx, call, turnId) {
 		runToolCounts
 	});
 	await ctx.hooks.callHook("tool:before", {
-		turnId,
-		callId,
-		name: call.name,
-		displayName,
-		input: effectiveInput,
+		...buildToolHookBase(ctx, turnId, callId, call.name, displayName, effectiveInput),
 		runToolCounts,
 		...coercions ? { coercions } : {}
 	});
@@ -1712,18 +1744,16 @@ async function executeSingleTool(ctx, call, turnId) {
 			turnId,
 			callId,
 			runId: ctx.runId,
+			...ctx.parentRunId !== void 0 ? { parentRunId: ctx.parentRunId } : {},
 			...ctx.session ? { session: ctx.session } : {},
+			...ctx.readState ? { readState: ctx.readState } : {},
 			...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,
+			...buildToolHookBase(ctx, turnId, callId, call.name, displayName, effectiveInput),
 			error
 		};
 		await ctx.hooks.callHook("tool:error", errorCtx);
@@ -1761,9 +1791,11 @@ async function executeSingleTool(ctx, call, turnId) {
 * across five call sites.
 */
 async function fireDispatched(ctx, params) {
-	const { reason, ...rest } = params;
+	const { turnId, callId, name, displayName, input, outcome, reason, runToolCounts } = params;
 	await ctx.hooks.callHook("tool:dispatched", {
-		...rest,
+		...buildToolHookBase(ctx, turnId, callId, name, displayName, input),
+		outcome,
+		runToolCounts,
 		...reason !== void 0 ? { reason } : {}
 	});
 }
@@ -1784,11 +1816,7 @@ async function emitToolResult(ctx, params) {
 	let output = params.output;
 	let isError = params.isError;
 	const transformCtx = {
-		turnId,
-		callId,
-		name,
-		displayName,
-		input,
+		...buildToolHookBase(ctx, turnId, callId, name, displayName, input),
 		result: output,
 		isError,
 		outputBytes: toolOutputByteLength(output),
@@ -1813,11 +1841,7 @@ async function emitToolResult(ctx, params) {
 	}
 	output = stripImagesForNonVision(ctx.provider, output);
 	await ctx.hooks.callHook("tool:after", {
-		turnId,
-		callId,
-		name,
-		displayName,
-		input,
+		...buildToolHookBase(ctx, turnId, callId, name, displayName, input),
 		result: output,
 		outputBytes: toolOutputByteLength(output),
 		runToolCounts,
@@ -1828,57 +1852,170 @@ async function emitToolResult(ctx, params) {
 		isError
 	};
 }
-async function executeToolsSequential(ctx, toolCalls, turnId) {
-	const results = [];
-	for (let i = 0; i < toolCalls.length; i++) {
-		const call = toolCalls[i];
-		if (ctx.signal.aborted) {
-			for (let j = i; j < toolCalls.length; j++) results.push({
-				id: toolCalls[j].id,
-				content: INTERRUPT_MESSAGE_FOR_TOOL_USE,
-				isError: true
-			});
-			return results;
-		}
-		if (ctx.steeringQueue.length > 0) {
-			for (let j = i; j < toolCalls.length; j++) results.push({
-				id: toolCalls[j].id,
-				content: TOOL_USE_SKIPPED_MESSAGE,
-				isError: true
-			});
-			return results;
-		}
-		try {
-			const { result } = await executeSingleTool(ctx, call, turnId);
-			results.push(result);
-		} catch (err) {
-			results.push({
-				id: call.id,
-				content: `Error: ${errorMessage(err)}`,
-				isError: true
-			});
-			for (let j = i + 1; j < toolCalls.length; j++) results.push({
-				id: toolCalls[j].id,
-				content: TOOL_USE_AFTER_ERROR_MESSAGE,
-				isError: true
-			});
-			return results;
-		}
+/** Default cap on in-flight tools per turn. Mirrors Claude Code's `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`. */
+const DEFAULT_MAX_CONCURRENT_TOOLS = 10;
+/** Canonical name of the shell tool — referenced for cascade-cancel semantics. */
+const SHELL_TOOL_NAME = "shell";
+/** Reason surfaced on `siblingAbort.signal` when a shell error cancels its fleet. */
+const SHELL_CASCADE_REASON = "sibling-shell-error";
+/**
+* Canonical `tool_result.content` text emitted to siblings that were
+* cancelled by a `shell` error in the same batch. Distinct from
+* {@link INTERRUPT_MESSAGE_FOR_TOOL_USE} (user-issued abort) and
+* {@link TOOL_USE_SKIPPED_MESSAGE} (steered) so consumers can split
+* the three causes by string-match.
+*/
+const SHELL_CASCADE_CANCEL_MESSAGE = "Cancelled: a sibling `shell` call in the same batch errored; re-run independently if still needed.";
+/**
+* Resolve a tool's concurrency-safety verdict for a specific call.
+*
+* - Missing toolDef (unknown tool) → `false`. `executeSingleTool` handles
+*   the unknown-tool path itself; barriering it keeps the unknown-tool
+*   error from racing with siblings.
+* - Static `true` / `false` → use as-is.
+* - Function → invoke; any throw is treated as `false` (fail-closed) so a
+*   buggy predicate can't accidentally widen the safety window.
+*
+* Pure / sync — pre-computed once per call before dispatch begins, so the
+* scheduler's hot path stays branch-light.
+*/
+function resolveConcurrencySafe(def, input) {
+	if (!def) return false;
+	const flag = def.isConcurrencySafe;
+	if (flag === void 0) return false;
+	if (typeof flag === "boolean") return flag;
+	try {
+		return flag(input) === true;
+	} catch {
+		return false;
 	}
-	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;
-		const reason = s.reason;
-		const isAbort = ctx.signal.aborted || reason instanceof Error && reason.name === "AbortError";
-		return {
-			id: toolCalls[i].id,
-			content: isAbort ? INTERRUPT_MESSAGE_FOR_TOOL_USE : `Error: ${reason instanceof Error ? reason.message : String(reason)}`,
+/**
+* Unified per-turn tool dispatcher.
+*
+* Walks `toolCalls` in submission order. For each call:
+*
+* - **Concurrency-safe + fleet is all safe + room under the cap** → fires
+*   asynchronously and the loop advances to the next call. The fleet runs
+*   in parallel up to `behavior.maxConcurrentTools` (default {@link
+*   DEFAULT_MAX_CONCURRENT_TOOLS}).
+* - **Unsafe** (or the in-flight fleet contains anything unsafe) → acts
+*   as a barrier: waits for the fleet to drain, then runs alone, then
+*   unblocks the queue.
+*
+* Results are written into a fixed `results[index]` array on completion
+* and yielded back in submission order, so the model sees deterministic
+* adjacency regardless of which call finished first.
+*
+* **Failure modes:**
+*
+* - **Hook throws / tool body throws** — captured per-call into a
+*   `tool_result` so the assistant turn's `tool_use` IDs always have
+*   matching `tool_result` IDs (providers reject orphan IDs).
+* - **Parent abort** mid-batch — drains the in-flight fleet (their
+*   `AbortError` becomes `INTERRUPT_MESSAGE_FOR_TOOL_USE`), then synthesizes
+*   interrupt results for any unstarted calls so the turn closes cleanly.
+* - **Steering queue populated** between dispatches — same drain + a
+*   `TOOL_USE_SKIPPED_MESSAGE` result for unstarted calls. The outer loop
+*   picks up the steer at the next checkpoint.
+* - **Shell error in a fleet** — `siblingAbort.abort('sibling-shell-error')`
+*   tears down concurrently-running siblings. Mirrors the convention that
+*   shell commands often chain (`mkdir foo && cd foo`); one failing
+*   sibling commonly invalidates the rest. Non-shell errors are isolated.
+*
+* A child `AbortController` (`siblingAbort`) forwards the parent abort
+* AND carries the shell-cascade signal — siblings see one signal source.
+*/
+async function executeToolBatch(ctx, toolCalls, turnId) {
+	if (toolCalls.length === 0) return [];
+	const N = toolCalls.length;
+	const maxConcurrent = Math.max(1, ctx.maxConcurrentTools ?? DEFAULT_MAX_CONCURRENT_TOOLS);
+	const results = Array.from({ length: N });
+	const safe = Array.from({ length: N });
+	for (let i = 0; i < N; i++) safe[i] = resolveConcurrencySafe(ctx.tools[toolCalls[i].name], toolCalls[i].input);
+	const siblingAbort = new AbortController();
+	let parentAbortListener;
+	if (ctx.signal.aborted) siblingAbort.abort(ctx.signal.reason ?? "parent-aborted");
+	else {
+		parentAbortListener = () => siblingAbort.abort(ctx.signal.reason ?? "parent-aborted");
+		ctx.signal.addEventListener("abort", parentAbortListener, { once: true });
+	}
+	const childCtx = {
+		...ctx,
+		signal: siblingAbort.signal
+	};
+	/** Indices currently in flight. Tracked for fleet-safety + cap checks. */
+	const inFlight = /* @__PURE__ */ new Map();
+	/**
+	* Distinguish a shell-cascade kill from a user-issued abort so the
+	* model sees actionable text. When BOTH the parent signal and the
+	* sibling signal are aborted, the parent wins — user-issued aborts
+	* take precedence (the model is being interrupted by the human, not
+	* by a sibling's failure).
+	*/
+	const cancelMessage = () => {
+		if (ctx.signal.aborted) return INTERRUPT_MESSAGE_FOR_TOOL_USE;
+		if (siblingAbort.signal.reason === SHELL_CASCADE_REASON) return SHELL_CASCADE_CANCEL_MESSAGE;
+		return INTERRUPT_MESSAGE_FOR_TOOL_USE;
+	};
+	const dispatch = (index) => {
+		const call = toolCalls[index];
+		return executeSingleTool(childCtx, call, turnId).then(({ result }) => {
+			results[index] = result;
+			if (result.isError && call.name === SHELL_TOOL_NAME && !siblingAbort.signal.aborted) siblingAbort.abort(SHELL_CASCADE_REASON);
+		}, (err) => {
+			const isAbort = siblingAbort.signal.aborted || ctx.signal.aborted || err instanceof Error && err.name === "AbortError";
+			results[index] = {
+				id: call.id,
+				content: isAbort ? cancelMessage() : `Error: ${errorMessage(err)}`,
+				isError: true
+			};
+		}).finally(() => {
+			inFlight.delete(index);
+		});
+	};
+	const drain = async () => {
+		if (inFlight.size > 0) await Promise.all([...inFlight.values()]);
+	};
+	/** Whether every in-flight call is concurrency-safe. */
+	const fleetAllSafe = () => {
+		for (const idx of inFlight.keys()) if (!safe[idx]) return false;
+		return true;
+	};
+	/**
+	* Fill all unstarted slots (`results[j]` still undefined) with the
+	* canonical text + `isError: true`. Used at every short-circuit
+	* branch (abort / steer) so the assistant turn's `tool_use` IDs
+	* always have matching `tool_result` IDs — providers reject orphan
+	* IDs loudly.
+	*/
+	const fillUnstarted = (from, content) => {
+		for (let j = from; j < N; j++) if (!results[j]) results[j] = {
+			id: toolCalls[j].id,
+			content,
 			isError: true
 		};
-	});
+	};
+	try {
+		for (let i = 0; i < N; i++) {
+			if (!safe[i] || !fleetAllSafe() || inFlight.size >= maxConcurrent) await drain();
+			if (ctx.signal.aborted) {
+				await drain();
+				fillUnstarted(i, INTERRUPT_MESSAGE_FOR_TOOL_USE);
+				return results;
+			}
+			if (ctx.steeringQueue.length > 0) {
+				await drain();
+				fillUnstarted(i, TOOL_USE_SKIPPED_MESSAGE);
+				return results;
+			}
+			inFlight.set(i, dispatch(i));
+		}
+		await drain();
+		return results;
+	} finally {
+		if (parentAbortListener) ctx.signal.removeEventListener("abort", parentAbortListener);
+	}
 }
 //#endregion
 //#region src/prompt.ts
@@ -2098,6 +2235,7 @@ function looksBinary(text, sniffBytes = SNIFF_BYTES) {
 function createSkillsReadTool(options) {
 	const byName = new Map(options.catalog.map((s) => [s.name, s]));
 	return {
+		isConcurrencySafe: true,
 		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\").",
@@ -2361,6 +2499,7 @@ function createToolSearchTool(options) {
 	}
 	const maxLimit = Math.max(options.catalog.length, 1);
 	return {
+		isConcurrencySafe: true,
 		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.",
@@ -2576,7 +2715,7 @@ async function synthesizeMissingToolResults(turns, syntheticTurnId, runId, provi
 }
 function resolveBehavior(agentBehavior, runBehavior) {
 	return {
-		toolExecution: runBehavior?.toolExecution ?? agentBehavior?.toolExecution ?? "parallel",
+		maxConcurrentTools: runBehavior?.maxConcurrentTools ?? agentBehavior?.maxConcurrentTools,
 		maxTurns: runBehavior?.maxTurns ?? agentBehavior?.maxTurns,
 		maxTokens: runBehavior?.maxTokens ?? agentBehavior?.maxTokens,
 		thinkingBudget: runBehavior?.thinkingBudget ?? agentBehavior?.thinkingBudget,
@@ -2745,7 +2884,7 @@ function initialRunCounter(session) {
 	for (const t of session.turns) consider(t.runId);
 	return max;
 }
-function createAgent({ provider, name: agentName, system: agentSystem, tools: agentTools, toolAliases, behavior: agentBehavior, execution, mcpServers, session, skills: agentSkills, mcpConnector, eager, hooks: initialHooks }) {
+function createAgent({ provider, name: agentName, system: agentSystem, tools: agentTools, toolAliases, behavior: agentBehavior, execution, mcpServers, session, readState: agentReadState, skills: agentSkills, mcpConnector, eager, hooks: initialHooks }) {
 	const hooks = createHooks();
 	const executionContext = execution ?? createProcessContext();
 	const sourceTools = agentTools ?? {};
@@ -2886,7 +3025,7 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 			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, persistThreshold, persistExcludeTools, persistDir, strictToolPairing } = resolvedBehavior;
+			const { maxConcurrentTools, maxTurns, maxTokens, thinkingBudget, schema, cache, toolOutputBudget, compactStrategy, compactThreshold, compactKeepTurns, thinkingDecay, dedupTools, toolBudgets, elideStaleReads, toolDisclosure, toolSearch, persistThreshold, persistExcludeTools, persistDir, strictToolPairing } = 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 ? {
@@ -3049,7 +3188,7 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 					model,
 					system,
 					thinking,
-					toolExecution,
+					...maxConcurrentTools !== void 0 ? { maxConcurrentTools } : {},
 					signal: abortController.signal,
 					execution: executionContext,
 					handle: executionHandle,
@@ -3061,6 +3200,8 @@ function createAgent({ provider, name: agentName, system: agentSystem, tools: ag
 					maxTurns,
 					maxTokens,
 					...session ? { session } : {},
+					...agentReadState ? { readState: agentReadState } : {},
+					...options.parentRunId ? { parentRunId: options.parentRunId } : {},
 					depth: runDepth,
 					thinkingBudget,
 					schema,
@@ -3624,12 +3765,14 @@ const edit = {
 		} 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.`;
+		if (ctx.behavior?.requireReadBeforeEdit) {
+			const readState = resolveReadStateMap(ctx);
+			if (readState) {
+				const absKey = readStateKey(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. (Reads inside a \`spawn\` subagent with \`persist: false\` and without \`shareReadState: true\` do NOT propagate to the parent — re-read in the calling context.)`;
+				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) {
@@ -3642,11 +3785,11 @@ const edit = {
 		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, {
+		const readState = resolveReadStateMap(ctx);
+		if (readState) {
+			const absKey = readStateKey(ctx.handle.cwd, target);
+			const prior = readState.get(absKey);
+			if (prior) readState.set(absKey, {
 				...prior,
 				contentHash: hashContent(updated),
 				mtimeMs: Date.now()
@@ -3725,6 +3868,7 @@ async function globViaShell(pattern, ctx, limit) {
 	return result.stdout.split("\n").filter((line) => line.length > 0);
 }
 const glob = {
+	isConcurrencySafe: true,
 	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.",
@@ -3790,6 +3934,7 @@ const glob = {
 const DEFAULT_HEAD_LIMIT = 250;
 const DEFAULT_OUTPUT_MODE = "files_with_matches";
 const grep = {
+	isConcurrencySafe: true,
 	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.",
@@ -4025,6 +4170,7 @@ function createInteractionTool(options) {
 //#endregion
 //#region src/tools/list-files.ts
 const listFiles = {
+	isConcurrencySafe: true,
 	spec: {
 		name: "list_files",
 		description: "List files and directories at the given path (relative to project root).",
@@ -4085,12 +4231,14 @@ const multiEdit = {
 		} 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.`;
+		if (ctx.behavior?.requireReadBeforeEdit) {
+			const readState = resolveReadStateMap(ctx);
+			if (readState) {
+				const absKey = readStateKey(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. (Reads inside a \`spawn\` subagent with \`persist: false\` and without \`shareReadState: true\` do NOT propagate to the parent — re-read in the calling context.)`;
+				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 totalReplacements = 0;
 		for (let i = 0; i < steps.length; i++) {
@@ -4110,11 +4258,11 @@ const multiEdit = {
 			totalReplacements += 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, {
+		const readState = resolveReadStateMap(ctx);
+		if (readState) {
+			const absKey = readStateKey(ctx.handle.cwd, target);
+			const prior = readState.get(absKey);
+			if (prior) readState.set(absKey, {
 				...prior,
 				contentHash: hashContent(current),
 				mtimeMs: Date.now()
@@ -4207,6 +4355,7 @@ const DEFAULT_BYTE_CAP = 262144;
 */
 const DEFAULT_IMAGE_BYTE_CAP = 5 * 1024 * 1024;
 const readFile$1 = {
+	isConcurrencySafe: true,
 	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.",
@@ -4264,14 +4413,16 @@ const readFile$1 = {
 			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 dedupEnabled = ctx.behavior?.dedupReads !== false;
+		const gateEnabled = ctx.behavior?.requireReadBeforeEdit === true;
+		const readState = dedupEnabled || gateEnabled ? resolveReadStateMap(ctx) : void 0;
+		const absKey = readStateKey(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) {
+		if (dedupEnabled && 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.`;
 		}
@@ -4399,7 +4550,110 @@ function extractTrailingCommand(command) {
 * context's own default (30 s for in-process).
 */
 const DEFAULT_MAX_OUTPUT_BYTES = 32768;
+/**
+* Best-effort read-only allow-list for the leading command token. Members
+* are commands whose stock behavior cannot mutate the workspace under any
+* argument combination — `ls`, `cat`, `pwd`, etc. Commands that *can*
+* mutate depending on flags (`find -delete`, `git tag <name>`, `tar -x`)
+* are intentionally excluded; the input-aware {@link isReadOnlyShellCommand}
+* predicate falls back to the conservative "not safe" answer for them, so
+* the scheduler barriers them.
+*/
+const SHELL_READ_ONLY_COMMANDS = new Set([
+	"ls",
+	"cat",
+	"head",
+	"tail",
+	"wc",
+	"pwd",
+	"whoami",
+	"id",
+	"date",
+	"uname",
+	"hostname",
+	"tty",
+	"echo",
+	"printf",
+	"env",
+	"printenv",
+	"which",
+	"type",
+	"command",
+	"file",
+	"stat",
+	"grep",
+	"rg",
+	"ag",
+	"true",
+	"false",
+	"test"
+]);
+/**
+* `git` subcommands that are pure reads regardless of arguments. Excludes
+* `branch`/`tag`/`remote` (which can mutate when given a name) and
+* `config` (which writes when given a value).
+*/
+const GIT_READ_ONLY_SUBCOMMANDS = new Set([
+	"status",
+	"log",
+	"diff",
+	"show",
+	"blame",
+	"rev-parse",
+	"ls-files",
+	"ls-tree",
+	"cat-file",
+	"reflog",
+	"shortlog",
+	"describe",
+	"rev-list",
+	"name-rev",
+	"whatchanged",
+	"merge-base",
+	"symbolic-ref"
+]);
+/**
+* Conservative read-only verdict for a shell command — used to opt a
+* `shell` invocation into the scheduler's concurrent fleet. Returns
+* `false` (fail-closed) on anything ambiguous so the scheduler barriers
+* it. Specifically:
+*
+* - Rejects compound commands (`;`, `&&`, `||`, `|`) and redirects (`>`,
+*   `>>`, `<`) — even a pipe to a read-only sink is treated as too
+*   complex to analyze.
+* - Rejects subshell / process substitution (`$(...)`, `` `...` ``,
+*   `<(...)`, `>(...)`).
+* - Skips leading `VAR=value` env assignments to find the real
+*   command token.
+* - Strips a possible absolute path on the command (`/usr/bin/ls` → `ls`).
+* - Allows the command iff its base name is in
+*   {@link SHELL_READ_ONLY_COMMANDS} OR it's `git <subcmd>` where
+*   `<subcmd>` is in {@link GIT_READ_ONLY_SUBCOMMANDS}.
+*
+* Cheap (no spawned process; regex + token scan). Safe to call from the
+* hot scheduler path.
+*/
+function isReadOnlyShellCommand(command) {
+	if (typeof command !== "string") return false;
+	const trimmed = command.trim();
+	if (trimmed === "") return false;
+	if (/[<>;&|`\n]/.test(trimmed)) return false;
+	if (trimmed.includes("$(") || trimmed.includes("<(") || trimmed.includes(">(")) return false;
+	const tokens = trimmed.split(/\s+/);
+	let i = 0;
+	while (i < tokens.length && /^[A-Z_]\w*=/i.test(tokens[i])) i++;
+	const head = tokens[i];
+	if (!head) return false;
+	const base = head.split("/").pop() ?? head;
+	if (SHELL_READ_ONLY_COMMANDS.has(base)) return true;
+	if (base === "git") {
+		const sub = tokens[i + 1];
+		return typeof sub === "string" && GIT_READ_ONLY_SUBCOMMANDS.has(sub);
+	}
+	return false;
+}
 const shell = {
+	isConcurrencySafe: (input) => isReadOnlyShellCommand(input.command),
 	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.",
@@ -4676,6 +4930,7 @@ function createSpawnTool(options = {}) {
 		get totalChildStats() {
 			return { ...localStats };
 		},
+		isConcurrencySafe: true,
 		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.",
@@ -4717,18 +4972,23 @@ function createSpawnTool(options = {}) {
 			let result = "";
 			let unbubble;
 			try {
-				const agent = createAgent({
+				const parentPreset = {
 					...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 } : {},
+					...ctx.behavior !== void 0 ? { behavior: ctx.behavior } : {}
+				};
+				const sharedReadState = options.shareReadState ? resolveReadStateMap(ctx) : void 0;
+				const agent = createAgent({
+					...parentPreset,
 					...options.preset,
 					provider: ctx.provider,
 					execution: ctx.execution,
-					...options.persist && ctx.session ? { session: ctx.session } : {}
+					...options.persist && ctx.session ? { session: ctx.session } : {},
+					...sharedReadState ? { readState: sharedReadState } : {}
 				});
 				if (forwardHooks) {
 					const unregisterEnricher = agent.hooks.hook("tool:before", async (toolCtx) => {
@@ -4903,6 +5163,6 @@ const writeFile$1 = {
 	}
 };
 //#endregion
-export { PERSISTENCE_PREVIEW_BYTES as C, resolvePersistDir as D, maybePersistToolResult as E, getReadState as O, PERSISTED_STUB_PREFIX as S, cleanupPersistedSession as T, createSkillsReadTool as _, multiEdit as a, TOOL_USE_SKIPPED_MESSAGE as b, grep as c, resolveOldString as d, styleReplacementForVia as f, createSkillsRunScriptTool as g, createSkillsUseTool as h, readFile$1 as i, glob as l, createToolSearchTool as m, createSpawnTool as n, listFiles as o, createAgent as p, shell as r, createInteractionTool as s, writeFile$1 as t, edit as u, INTERRUPT_MESSAGE_FOR_TOOL_USE as v, buildPersistedStub as w, validateToolArgs as x, TOOL_USE_AFTER_ERROR_MESSAGE as y };
+export { readStateKey as A, PERSISTENCE_PREVIEW_BYTES as C, resolvePersistDir as D, maybePersistToolResult as E, getReadState as O, PERSISTED_STUB_PREFIX as S, cleanupPersistedSession as T, createSkillsReadTool as _, multiEdit as a, TOOL_USE_SKIPPED_MESSAGE as b, grep as c, resolveOldString as d, styleReplacementForVia as f, createSkillsRunScriptTool as g, createSkillsUseTool as h, readFile$1 as i, resolveReadStateMap as j, hashContent as k, glob as l, createToolSearchTool as m, createSpawnTool as n, listFiles as o, createAgent as p, shell as r, createInteractionTool as s, writeFile$1 as t, edit as u, INTERRUPT_MESSAGE_FOR_TOOL_USE as v, buildPersistedStub as w, validateToolArgs as x, SHELL_CASCADE_CANCEL_MESSAGE as y };
 
-//# sourceMappingURL=tools-CWEDS2ZT.js.map
+//# sourceMappingURL=tools-DKdyPoUf.js.map