@graphorin/agent 0.5.0 → 0.6.1

package/dist/factory.js

@@ -11,6 +11,8 @@ import { addModelUsage, createInitialRunState, serializeRunState } from "./run-s
 import { buildMemoryGuard, buildSecretResolver, buildToolTokenCounter, createExecutorEventBridge, createMemoryRegionReader } from "./tooling/adapters.js";
 import { orderPromotedTools } from "./tooling/catalogue.js";
 import { buildDataFlowGuard } from "./tooling/dataflow.js";
+import { PLAN_TOOL_NAME, createPlanTool, renderPlanRecitation } from "./tooling/plan.js";
+import { buildToolArgumentPolicy } from "./tooling/policy.js";
 import { buildToolRegistry } from "./tooling/registry-build.js";
 import { createHash } from "node:crypto";
 import { NOOP_LOGGER, NOOP_TRACER, isStepCount, zeroUsage } from "@graphorin/core";
@@ -19,10 +21,11 @@ import { createReadResultTool, createToolSearchTool } from "@graphorin/tools/bui
 import { createCodeExecuteTool, createCodeSearchTool, projectToolApi } from "@graphorin/tools/code-mode";
 import { createToolExecutor } from "@graphorin/tools/executor";
 import { createDefaultSpillWriter, createFileResultReader } from "@graphorin/tools/result";
+import { projectSchemaToJsonSchema } from "@graphorin/tools/schema";
 
 //#region src/factory.ts
 /**
-* `createAgent({...})` — the agent factory entry point.
+* `createAgent({...})` - the agent factory entry point.
 *
 * Wires the typed `model -> tool calls -> model` loop, the streamed
 * event surface, the steering / followUp queues, durable HITL via
@@ -46,23 +49,26 @@ const HANDOFF_TOOL_PREFIX = "transfer_to_";
 /** The built-in deferred-discovery tool's stable name (WI-05 / P0-3). */
 const TOOL_SEARCH_NAME = "tool_search";
 /**
-* Register the built-in `tool_search` into `registry` when — and only
-* when — the registry holds at least one deferred tool
+* Register the built-in `tool_search` into `registry` when - and only
+* when - the registry holds at least one deferred tool
 * (`defer_loading: true`). `tool_search` is itself eager (so it is
 * always advertised while a deferred pool exists) and resolvable by the
 * executor like any other tool, so a model can both *see* it in the
 * per-step catalogue and *call* it.
 *
-* No-op when nothing defers (zero overhead — the tool never appears) or
+* No-op when nothing defers (zero overhead - the tool never appears) or
 * when a user tool already occupies the name (the user's tool wins; we
 * never clobber it). Because deferral is decided at registration time
 * (`normaliseTool`), the deferred set is fixed for the life of the
-* registry — this runs once per registry, not per step.
+* registry - this runs once per registry, not per step.
 */
-function registerToolSearch(registry) {
+function registerToolSearch(registry, availability) {
 	if (registry.listDeferred().length === 0) return;
 	if (registry.get(TOOL_SEARCH_NAME) !== void 0) return;
-	registry.register(createToolSearchTool({ registry }), {
+	registry.register(createToolSearchTool({
+		registry,
+		...availability !== void 0 ? { availability } : {}
+	}), {
 		kind: "built-in",
 		subsystem: "tool-discovery"
 	});
@@ -72,7 +78,7 @@ const READ_RESULT_NAME = "read_result";
 /**
 * Register the built-in `read_result` into `registry` when at least one
 * registered tool opts into the `'spill-to-file'` truncation strategy
-* (the sole producer of spill handles today) — or when `force` is set,
+* (the sole producer of spill handles today) - or when `force` is set,
 * which the agent passes when an operator wires external result readers
 * (e.g. an MCP `resource_link` reader; WI-13). The tool is eager, so it
 * is advertised alongside the producing tool and the model can fetch a
@@ -109,27 +115,28 @@ function composeResultReaders(readers) {
 /** The code-mode meta-tools' stable names (WI-11 / P1-2). */
 const CODE_EXECUTE_NAME = "code_execute";
 const CODE_SEARCH_NAME = "code_search";
+/** Structural check: is this tool approval-gated (static or predicate form)? */
+const isApprovalGated = (t) => t.needsApproval === true || typeof t.needsApproval === "function";
 /**
 * Wire code-mode (P1-2) into `registry`: register the `code_search` /
 * `code_execute` meta-tools and return them as the tools to advertise in
 * place of the full catalogue. The model reaches every other tool through
 * `code_execute`, whose in-script `tools.<name>(args)` calls route back
 * through `quietExecutor.executeOne(...)` under the calling step's
-* `runContext` — so per-tool ACL / sanitization / truncation still apply,
+* `runContext` - so per-tool ACL / sanitization / truncation still apply,
 * exactly as in direct mode. `quietExecutor` carries no `streamingSink`,
 * so the inner calls do not interleave `tool.execute.*` events into the
 * outer stream.
 *
 * Excluded from the code API (`reservedNames`): the meta-tools, the
 * discovery / handle built-ins, handoff tools (which stay first-class
-* provider tools), and — supplied by the caller — any approval-gated
+* provider tools), and - supplied by the caller - any approval-gated
 * tool, since code-mode has no durable-HITL path to suspend mid-script.
 *
 * Returns `[]` (registering nothing) when no real tool is exposable.
 */
-function registerCodeMode(registry, quietExecutor, reservedNames) {
+function registerCodeMode(registry, quietExecutor, reservedNames, getRunCapability) {
 	if (registry.get(CODE_EXECUTE_NAME) !== void 0) return [];
-	const isApprovalGated = (t) => t.needsApproval === true || typeof t.needsApproval === "function";
 	const codeTools = registry.list().filter((entry) => !reservedNames.has(entry.name) && !isApprovalGated(entry));
 	if (codeTools.length === 0) return [];
 	const approvalGatedTools = registry.list().filter((entry) => !reservedNames.has(entry.name) && isApprovalGated(entry)).map((entry) => entry.name);
@@ -138,7 +145,8 @@ function registerCodeMode(registry, quietExecutor, reservedNames) {
 	const allowedSet = new Set(codeTools.map((entry) => entry.name));
 	const projection = projectToolApi(codeTools.filter((entry) => entry.__effectiveDeferLoading !== true));
 	const executeTool = async (call, ctx) => {
-		if (approvalGatedSet.has(call.name)) throw new Error(`${call.name} requires human approval and cannot run inside code_execute — call it directly as a standalone tool call so the run can suspend for the approval.`);
+		if (approvalGatedSet.has(call.name)) throw new Error(`${call.name} requires human approval and cannot run inside code_execute - call it directly as a standalone tool call so the run can suspend for the approval.`);
+		const runCapability = getRunCapability?.();
 		const { outcome } = await quietExecutor.executeOne({
 			call: {
 				toolCallId: newId("codecall"),
@@ -146,7 +154,8 @@ function registerCodeMode(registry, quietExecutor, reservedNames) {
 				args: call.args
 			},
 			runContext: ctx.runContext,
-			stepNumber: ctx.runContext.stepNumber
+			stepNumber: ctx.runContext.stepNumber,
+			...runCapability !== void 0 ? { capability: runCapability } : {}
 		});
 		if ("kind" in outcome) throw new Error(`${call.name}: ${outcome.message}`);
 		return outcome.output;
@@ -176,7 +185,7 @@ function registerCodeMode(registry, quietExecutor, reservedNames) {
 * Fold a completed `tool_search` result into the per-run promotion set:
 * every matched tool name becomes advertised (and thus callable) on the
 * next step. Tolerant of unexpected shapes (e.g. a user-shadowed
-* `tool_search`) — only string `name`s inside a `matches` array promote.
+* `tool_search`) - only string `name`s inside a `matches` array promote.
 */
 function recordToolSearchPromotions(output, promoted) {
 	if (typeof output !== "object" || output === null) return;
@@ -242,7 +251,7 @@ function stripJsonFence(text) {
 * do not yet consume `ProviderRequest.outputType` natively (PS-24).
 */
 function buildStructuredInstruction(spec) {
-	const parts = ["Respond with a single valid JSON value only — no prose, no Markdown code fences."];
+	const parts = ["Respond with a single valid JSON value only - no prose, no Markdown code fences."];
 	if (spec.description !== void 0 && spec.description.length > 0) parts.push(spec.description);
 	if (spec.jsonSchema !== void 0) parts.push(`The JSON MUST conform to this JSON Schema:\n${JSON.stringify(spec.jsonSchema)}`);
 	return parts.join("\n");
@@ -260,27 +269,53 @@ function lastUserText(messages) {
 /**
 * AG-21: classify a **thrown** provider error into a {@link ProviderErrorKind}
 * so the fallback chain can act on it, instead of flattening every exception to
-* `'unknown'` (which is always fallback-ineligible). Structural — reads the
+* `'unknown'` (which is always fallback-ineligible). Structural - reads the
 * `kind` carried by `@graphorin/provider`'s `GraphorinProviderError` subclasses
 * without importing them, keeping the agent decoupled from the provider package.
 */
+/** Canonical `ProviderErrorKind` values honoured off a thrown error's `errorKind`. */
+const CANONICAL_PROVIDER_ERROR_KINDS = new Set([
+	"rate-limit",
+	"capacity",
+	"context-length",
+	"transient",
+	"invalid-request",
+	"unauthorized",
+	"content-filter"
+]);
 function classifyThrownProviderErrorKind(cause) {
-	if (typeof cause === "object" && cause !== null && "kind" in cause) switch (cause.kind) {
-		case "rate-limit-exceeded": return "rate-limit";
+	if (typeof cause === "object" && cause !== null) {
+		const errorKind = cause.errorKind;
+		if (typeof errorKind === "string" && CANONICAL_PROVIDER_ERROR_KINDS.has(errorKind)) return errorKind;
+		switch (cause.kind) {
+			case "rate-limit-exceeded": return "rate-limit";
+		}
 	}
 	return "unknown";
 }
-/** Resolve a Zod-like schema to a JSON-Schema record (via `toJSON`), else pass an object through. */
-function projectSchema(raw) {
-	if (raw === null || raw === void 0) return void 0;
-	const toJson = raw.toJSON;
-	if (typeof toJson === "function") return toJson.call(raw);
-	if (typeof raw === "object") return raw;
+/** WARN-once keys for schemas the projection cannot read (per process). */
+const unprojectableSchemaWarned = /* @__PURE__ */ new Set();
+/**
+* Resolve a tool's declared schema - plain Zod (v3/v4), `toJSON()`-bearing,
+* or already-JSON-Schema data - to a JSON Schema record via the shared
+* projection (tools-01). Pre-fix this only honoured `toJSON()` and passed
+* everything else through verbatim, so every plain-Zod tool serialised as
+* `{"_def":...}` internals on OpenAI-shaped/Ollama/vercel wire bodies.
+* `undefined` when nothing usable can be projected (caller substitutes a
+* permissive `{}`), with a WARN so the degradation is never silent.
+*/
+function projectSchema(raw, toolName, slot) {
+	return projectSchemaToJsonSchema(raw, { onUnsupported: (detail) => {
+		const key = `${toolName}:${slot}:${detail}`;
+		if (unprojectableSchemaWarned.has(key)) return;
+		unprojectableSchemaWarned.add(key);
+		console.warn(`[graphorin/agent] tool '${toolName}' ${slot} schema: '${detail}' cannot be projected to JSON Schema - that fragment degrades to a permissive {} on the provider wire body.`);
+	} });
 }
 function toolToDefinition(tool) {
 	const ts = tool;
-	const inputSchema = projectSchema(ts.inputSchema) ?? {};
-	const outputSchema = projectSchema(ts.outputSchema);
+	const inputSchema = projectSchema(ts.inputSchema, tool.name, "input") ?? {};
+	const outputSchema = projectSchema(ts.outputSchema, tool.name, "output");
 	const examples = renderToolExamples(tool);
 	return {
 		name: tool.name,
@@ -296,8 +331,8 @@ function toolToDefinition(tool) {
 * renders them: the registry resolves the `defer_loading` auto-rule into
 * `examplesEagerlyRendered`, so a deferred tool resolves to `false` and is
 * skipped (its examples stay out of context even once `tool_search`
-* promotes it). `undefined` — the "runtime decides" case for a plain
-* eager tool — renders, since the tool is already advertised this step.
+* promotes it). `undefined` - the "runtime decides" case for a plain
+* eager tool - renders, since the tool is already advertised this step.
 *
 * Bounded to ≤5 to honour the `ToolExample` `[1,5]` contract even when a
 * tool slipped past the registry's overflow WARN (which does not truncate).
@@ -482,7 +517,7 @@ function stripReasoningFromMessages(messages) {
 }
 /**
 * Count the leading contiguous run of `system` messages in the initial
-* buffer — the trusted, KV-cache-stable instruction prefix. Captured
+* buffer - the trusted, KV-cache-stable instruction prefix. Captured
 * once at run start (WI-09 / P1-1): auto-compaction summarises only the
 * messages after this prefix, so the prefix stays byte-identical across
 * every step (the provider's cache breakpoint is real) and a long run
@@ -491,17 +526,94 @@ function stripReasoningFromMessages(messages) {
 * The length is fixed for the run rather than re-derived per compaction
 * on purpose: each compaction inserts its summary as a `system` message
 * right after the prefix, so re-scanning the leading run would absorb
-* that summary into the prefix and shield it from the next compaction —
+* that summary into the prefix and shield it from the next compaction -
 * summaries would stack unbounded. Pinning the original length keeps
 * each prior summary inside the compactable body, where the next pass
 * folds it into a fresh summary-of-summary.
 */
+/**
+* Marker prefix stamped on every compaction summary (see the memory
+* package's summary template). context-engine-05: the prefix scan must
+* stop at it - after a compact-then-suspend cycle the summary is a
+* SYSTEM message sitting right after the true prefix, and counting it
+* in would pin it (and every later summary) outside the compactable
+* window forever, growing the uncompactable prefix by one summary per
+* cycle.
+*/
+const COMPACTION_SUMMARY_MARKER = "<graphorin_compaction_summary";
 function countLeadingSystemMessages(messages) {
 	let i = 0;
-	while (i < messages.length && messages[i]?.role === "system") i += 1;
+	while (i < messages.length) {
+		const msg = messages[i];
+		if (msg?.role !== "system") break;
+		if (typeof msg.content === "string" && msg.content.startsWith(COMPACTION_SUMMARY_MARKER)) break;
+		i += 1;
+	}
 	return i;
 }
 /**
+* Immutable usage sum. Optional token fields (reasoning + prompt-cache
+* legs, core-provider-02) appear in the result only when at least one
+* side carries them, so pre-cache serialized shapes stay byte-identical.
+*/
+/**
+* D6: assemble the per-step request messages. Trailing, request-only
+* additions ride the LAST prompt-cache anchor and never touch the shared
+* `messages` buffer or the persisted RunState: the structured-output
+* instruction (AG-3) and the attention-recitation plan block are both
+* appended here, in that order, so the stable prompt prefix is unchanged
+* and only the small trailing tail is re-sent each step.
+*/
+function buildStepMessages(messages, structuredInstruction, todos) {
+	const out = [...messages];
+	if (structuredInstruction !== void 0) out.push({
+		role: "system",
+		content: structuredInstruction
+	});
+	const recitation = renderPlanRecitation(todos);
+	if (recitation !== null) out.push({
+		role: "system",
+		content: recitation
+	});
+	return out;
+}
+function addUsage(a, b) {
+	const optional = (x, y) => x === void 0 && y === void 0 ? void 0 : (x ?? 0) + (y ?? 0);
+	const reasoningTokens = optional(a.reasoningTokens, b.reasoningTokens);
+	const cachedReadTokens = optional(a.cachedReadTokens, b.cachedReadTokens);
+	const cacheWriteTokens = optional(a.cacheWriteTokens, b.cacheWriteTokens);
+	return {
+		promptTokens: a.promptTokens + b.promptTokens,
+		completionTokens: a.completionTokens + b.completionTokens,
+		totalTokens: a.totalTokens + b.totalTokens,
+		...reasoningTokens !== void 0 ? { reasoningTokens } : {},
+		...cachedReadTokens !== void 0 ? { cachedReadTokens } : {},
+		...cacheWriteTokens !== void 0 ? { cacheWriteTokens } : {}
+	};
+}
+/**
+* C3: render a ToolError for the model. The first line keeps the
+* long-standing `Error: <message>` shape; a bracketed second line carries
+* the typed kind + the recovery envelope, which is what actually changes
+* model behaviour after a failure (retry vs. fix args vs. give up).
+*/
+function renderToolErrorMessage(error) {
+	const parts = [`kind: ${error.kind}`];
+	if (error.recoverable !== void 0) parts.push(error.recoverable ? "recoverable: yes" : "recoverable: no");
+	if (error.recoveryHint !== void 0) parts.push(`suggested action: ${error.recoveryHint}`);
+	if (error.hint !== void 0) parts.push(error.hint);
+	return `Error: ${error.message}\n[${parts.join("; ")}]`;
+}
+/** In-place variant of {@link addUsage} for mutable accumulators. */
+function accumulateUsage(target, delta) {
+	target.promptTokens += delta.promptTokens;
+	target.completionTokens += delta.completionTokens;
+	target.totalTokens += delta.totalTokens;
+	if (delta.reasoningTokens !== void 0) target.reasoningTokens = (target.reasoningTokens ?? 0) + delta.reasoningTokens;
+	if (delta.cachedReadTokens !== void 0) target.cachedReadTokens = (target.cachedReadTokens ?? 0) + delta.cachedReadTokens;
+	if (delta.cacheWriteTokens !== void 0) target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + delta.cacheWriteTokens;
+}
+/**
 * Build a fresh {@link Agent} from the supplied configuration.
 *
 * @stable
@@ -509,7 +621,7 @@ function countLeadingSystemMessages(messages) {
 function createAgent(config) {
 	if (typeof config.name !== "string" || config.name.length === 0) throw new InvalidAgentConfigError("missing 'name'");
 	if (config.provider === void 0 || config.provider === null) throw new InvalidAgentConfigError("missing 'provider'");
-	if (config.outputType?.kind === "text" && config.outputType.schema !== void 0) throw new InvalidAgentConfigError("outputType.kind 'text' with a schema — did you mean kind: 'structured'?");
+	if (config.outputType?.kind === "text" && config.outputType.schema !== void 0) throw new InvalidAgentConfigError("outputType.kind 'text' with a schema - did you mean kind: 'structured'?");
 	validatePreferredModel(config.preferredModel);
 	if (config.modelTierMap !== void 0) for (const [tier, spec] of Object.entries(config.modelTierMap)) {
 		if (!isModelHintLike(tier)) throw new InvalidPreferredModelError({ tier });
@@ -540,6 +652,7 @@ function createAgent(config) {
 	let abortController;
 	let pendingAbort;
 	let activeRunState;
+	let activeRunCapability;
 	/** AG-11: guards the one-in-flight-run-per-instance invariant. */
 	let runInFlight = false;
 	const externalEventQueue = [];
@@ -560,7 +673,13 @@ function createAgent(config) {
 		...config.tools !== void 0 ? { tools: config.tools } : {},
 		...config.skills !== void 0 ? { skills: config.skills } : {}
 	}).registry;
-	registerToolSearch(toolRegistry);
+	registerToolSearch(toolRegistry, config.toolPromotion === "run-boundary" ? "next-run" : "next-step");
+	if (config.plan === true && toolRegistry.get(PLAN_TOOL_NAME) === void 0) toolRegistry.register(createPlanTool((todos) => {
+		if (activeRunState !== void 0) activeRunState.todos = todos;
+	}), {
+		kind: "built-in",
+		subsystem: "planning"
+	});
 	const spillWriter = createDefaultSpillWriter();
 	const fileResultReader = createFileResultReader({ artifactRoot: spillWriter.artifactRoot });
 	const externalResultReaders = config.resultReaders ?? [];
@@ -588,9 +707,10 @@ function createAgent(config) {
 	const toolMemoryGuardFactory = memoryGuardWiring.memoryGuardFactory;
 	if (memory === void 0) {
 		const guarded = (config.tools ?? []).filter((t) => t.memoryGuardTier !== void 0);
-		if (guarded.length > 0) console.warn(`[graphorin/agent] ${guarded.length} tool(s) declare memoryGuardTier but no memory is wired — the DEC-153 snapshot/verify guard is skipped (SDF-1). Wire \`memory\` to activate it.`);
+		if (guarded.length > 0) console.warn(`[graphorin/agent] ${guarded.length} tool(s) declare memoryGuardTier but no memory is wired - the DEC-153 snapshot/verify guard is skipped (SDF-1). Wire \`memory\` to activate it.`);
 	}
 	const toolDataFlowGuard = config.dataFlowPolicy !== void 0 && config.dataFlowPolicy.mode !== "off" ? buildDataFlowGuard(config.dataFlowPolicy) : void 0;
+	const { guard: toolArgumentPolicyGuard, capabilityFloor: ruleOfTwoCapabilityFloor } = buildToolArgumentPolicy(config.toolPolicy, config.ruleOfTwo);
 	const toolStreamingSink = (event) => activeExecutorBridge?.sink(event);
 	const makeToolExecutor = (registry, opts) => createToolExecutor({
 		registry,
@@ -601,8 +721,10 @@ function createAgent(config) {
 		...memoryGuardWiring.memoryRegionReader !== void 0 ? { memoryRegionReader: memoryGuardWiring.memoryRegionReader } : {},
 		spill: spillWriter,
 		...toolDataFlowGuard !== void 0 ? { dataFlowGuard: toolDataFlowGuard } : {},
+		...toolArgumentPolicyGuard !== void 0 ? { argumentPolicy: toolArgumentPolicyGuard } : {},
 		...opts?.quiet === true ? {} : { streamingSink: toolStreamingSink },
-		...config.maxParallelTools !== void 0 ? { maxParallelTools: config.maxParallelTools } : {}
+		...config.maxParallelTools !== void 0 ? { maxParallelTools: config.maxParallelTools } : {},
+		...config.toolRetry !== void 0 ? { retry: config.toolRetry } : {}
 	});
 	const toolExecutor = makeToolExecutor(toolRegistry);
 	const isCodeMode = config.toolInvocation === "code-mode";
@@ -615,7 +737,7 @@ function createAgent(config) {
 			READ_RESULT_NAME,
 			...handoffMap.keys()
 		]);
-		const metas = registerCodeMode(toolRegistry, makeToolExecutor(toolRegistry, { quiet: true }), reserved);
+		const metas = registerCodeMode(toolRegistry, makeToolExecutor(toolRegistry, { quiet: true }), reserved, () => activeRunCapability);
 		registerReadResult(toolRegistry, resultReader);
 		const readResult = toolRegistry.get(READ_RESULT_NAME);
 		codeModeAdvertised = [...metas, ...readResult !== void 0 ? [readResult] : []];
@@ -624,7 +746,7 @@ function createAgent(config) {
 	/**
 	* AG-11: one in-flight run per Agent instance. `steer` / `followUp` /
 	* `abort` / `compact` address "the run" with no run handle, so
-	* overlapping runs on one instance cannot be expressed safely — they
+	* overlapping runs on one instance cannot be expressed safely - they
 	* would share the abort controller, steer queue, active-run ref and
 	* executor bridge. A second concurrent `run()` / `stream()` rejects
 	* with {@link ConcurrentRunError}; run-scoped state is reset on entry
@@ -637,12 +759,14 @@ function createAgent(config) {
 		runInFlight = true;
 		pendingSteer = [];
 		pendingAbort = void 0;
+		activeRunCapability = options.capability ?? config.capability ?? ruleOfTwoCapabilityFloor;
 		causalityMonitor?.reset();
 		try {
 			return yield* runLoopInner(input, options);
 		} finally {
 			runInFlight = false;
 			activeRunState = void 0;
+			activeRunCapability = void 0;
 			while (pendingManualCompacts.length > 0) pendingManualCompacts.shift()?.resolve(noopCompactionResult("no-active-run"));
 		}
 	}
@@ -667,6 +791,15 @@ function createAgent(config) {
 		});
 		activeRunState = state;
 		if (resumed && state.taintSummary !== void 0) toolDataFlowGuard?.seedLedger(state.id, state.taintSummary);
+		const promotedDeferred = /* @__PURE__ */ new Set();
+		if (resumed && state.promotedTools !== void 0) for (const name of state.promotedTools) promotedDeferred.add(name);
+		const runStartPromotions = config.toolPromotion === "run-boundary" ? new Set(promotedDeferred) : void 0;
+		async function* finishRun(s, snapshot) {
+			const taintSnap = toolDataFlowGuard?.snapshotLedger(s.id);
+			if (taintSnap !== void 0) s.taintSummary = taintSnap;
+			if (promotedDeferred.size > 0) s.promotedTools = [...promotedDeferred];
+			return yield* finishRunBase(s, snapshot);
+		}
 		const messages = resumed ? [...state.messages] : [];
 		if (!resumed) {
 			const instructionsRaw = config.instructions;
@@ -709,6 +842,18 @@ function createAgent(config) {
 			for (const m of messages) state.messages.push(m);
 		}
 		const finalSnapshot = { output: "" };
+		const runSpan = tracer.startSpan({
+			type: "agent.run",
+			attrs: {
+				"gen_ai.operation.name": "invoke_agent",
+				"gen_ai.agent.id": agentId,
+				"gen_ai.agent.name": config.name,
+				"graphorin.run.id": state.id,
+				"graphorin.session.id": sessionId,
+				"graphorin.run.resumed": resumed !== void 0
+			}
+		});
+		let currentStepSpan;
 		yield {
 			type: "agent.start",
 			runId: state.id,
@@ -758,6 +903,7 @@ function createAgent(config) {
 		}
 		const structuredInstruction = config.outputType?.kind === "structured" ? buildStructuredInstruction(config.outputType) : void 0;
 		const resumedApprovedCalls = [];
+		const grantedApprovals = [];
 		const journaledCallIds = /* @__PURE__ */ new Set();
 		for (const step of state.steps) for (const completed of step.toolCalls) journaledCallIds.add(completed.call.toolCallId);
 		if (resumed && options.directive?.approvals !== void 0 && state.pendingApprovals.length > 0) {
@@ -780,6 +926,7 @@ function createAgent(config) {
 						toolName: approval.toolName,
 						args: approval.args
 					});
+					grantedApprovals.push(approval);
 				} else {
 					yield {
 						type: "tool.approval.denied",
@@ -815,8 +962,29 @@ function createAgent(config) {
 			messages,
 			state
 		};
-		if (resumed && (state.status === "awaiting_approval" || state.status === "failed")) return yield* finishRun(state, finalSnapshot);
+		if (resumed && state.status === "failed") return yield* finishRun(state, finalSnapshot);
 		if (resumed && resumedApprovedCalls.length > 0) {
+			if (config.checkpointStore !== void 0) {
+				const prevStatus = state.status;
+				state.status = "awaiting_approval";
+				state.pendingApprovals.unshift(...grantedApprovals);
+				const intentState = serializeRunState(state, { stripTracingApiKey: true });
+				state.pendingApprovals.splice(0, grantedApprovals.length);
+				state.status = prevStatus;
+				await config.checkpointStore.put(state.id, "agent", {
+					id: state.id,
+					threadId: state.id,
+					namespace: "agent",
+					state: intentState,
+					channelVersions: {},
+					stepNumber: 0,
+					createdAt: (/* @__PURE__ */ new Date()).toISOString()
+				}, {
+					source: "sync",
+					status: "suspended",
+					nodeName: "agent.resume.intent"
+				});
+			}
 			state.steps.push({
 				stepNumber: 0,
 				startedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -829,19 +997,31 @@ function createAgent(config) {
 				...runContextBase,
 				stepNumber: 0,
 				messages
-			}, 0);
+			}, 0, { disableRepair: true });
+			if (config.checkpointStore !== void 0) await config.checkpointStore.put(state.id, "agent", {
+				id: state.id,
+				threadId: state.id,
+				namespace: "agent",
+				state: serializeRunState(state, { stripTracingApiKey: true }),
+				channelVersions: {},
+				stepNumber: 0,
+				createdAt: (/* @__PURE__ */ new Date()).toISOString()
+			}, {
+				source: "sync",
+				status: state.status === "awaiting_approval" ? "suspended" : "running",
+				nodeName: "agent.resume.dispatched"
+			});
 		}
-		const promotedDeferred = /* @__PURE__ */ new Set();
-		if (resumed && state.promotedTools !== void 0) for (const name of state.promotedTools) promotedDeferred.add(name);
+		if (resumed && state.status === "awaiting_approval") return yield* finishRun(state, finalSnapshot);
 		/**
 		* Dispatch a batch of (non-handoff) tool calls through the
 		* {@link ToolExecutor} and surface the results as `AgentEvent`s.
 		*
 		* The agent owns the `tool.execute.start` / `.end` / `.error`
 		* lifecycle (derived deterministically from the returned
-		* {@link CompletedToolCall} outcomes) so every outcome kind —
+		* {@link CompletedToolCall} outcomes) so every outcome kind -
 		* success, unknown-tool, invalid-input, sanitization-blocked,
-		* execution error — yields a consistent event and tool message,
+		* execution error - yields a consistent event and tool message,
 		* preserving the pre-WI-03 stream shape (R10). The executor's
 		* genuinely-live streaming events (`tool.execute.progress` /
 		* `.partial`, emitted only by streaming-hint tools) are bridged
@@ -850,13 +1030,13 @@ function createAgent(config) {
 		* Parallelism (WI-04): the executor runs independent calls in this
 		* batch concurrently, bounded by `maxParallelTools`. `tool.execute.start`
 		* is emitted up-front in call order and `.end` / `.error` after the
-		* batch settles, also in call order — so result mapping and tool-message
+		* batch settles, also in call order - so result mapping and tool-message
 		* history are deterministic regardless of which call finishes first,
 		* while `.progress` / `.partial` events for concurrent calls interleave
 		* (keyed by `toolCallId`). Tools declaring `executionMode: 'sequential'`
 		* are serialised by the executor and never overlap.
 		*/
-		async function* dispatchBatch(calls, executor, runContext, stepNum) {
+		async function* dispatchBatch(calls, executor, runContext, stepNum, dispatchOpts = {}) {
 			if (calls.length === 0) return;
 			for (const call of calls) yield {
 				type: "tool.execute.start",
@@ -867,7 +1047,9 @@ function createAgent(config) {
 			const resultsPromise = executor.executeBatch({
 				calls,
 				runContext,
-				stepNumber: stepNum
+				stepNumber: stepNum,
+				...dispatchOpts.disableRepair !== void 0 ? { disableRepair: dispatchOpts.disableRepair } : {},
+				...activeRunCapability !== void 0 ? { capability: activeRunCapability } : {}
 			});
 			const closeOnSettle = resultsPromise.then(() => bridge.close(), () => bridge.close());
 			for await (const event of bridge.drain()) if (event.type === "tool.execute.progress" || event.type === "tool.execute.partial") yield event;
@@ -887,7 +1069,7 @@ function createAgent(config) {
 						toolCallId: call.toolCallId,
 						error: outcome
 					};
-					const text = `Error: ${outcome.message}`;
+					const text = renderToolErrorMessage(outcome);
 					messages.push({
 						role: "tool",
 						toolCallId: call.toolCallId,
@@ -908,7 +1090,8 @@ function createAgent(config) {
 						durationMs: outcome.durationMs
 					};
 					const handle = outcome.resultHandle;
-					const text = handle !== void 0 ? `${handle.preview}\n\n[Full result${handle.bytes !== void 0 ? ` (${handle.bytes} bytes)` : ""} stored behind a handle. Call read_result with handle ${JSON.stringify(handle.uri)} to retrieve it — optionally narrow with offset/length (bytes) or startLine/endLine.]` : typeof output === "string" ? output : JSON.stringify(output);
+					const rendered = handle !== void 0 ? `${handle.preview}\n\n[Full result${handle.bytes !== void 0 ? ` (${handle.bytes} bytes)` : ""} stored behind a handle. Call read_result with handle ${JSON.stringify(handle.uri)} to retrieve it - optionally narrow with offset/length (bytes) or startLine/endLine.]` : typeof output === "string" ? output : JSON.stringify(output);
+					const text = rendered === void 0 || rendered.trim().length === 0 ? "(tool ran successfully with no output)" : rendered;
 					messages.push({
 						role: "tool",
 						toolCallId: call.toolCallId,
@@ -930,20 +1113,20 @@ function createAgent(config) {
 		* in-flight buffer has crossed its per-provider threshold
 		* (`shouldCompact`); when it has, summarise the older turns
 		* (`compactNow`, `source: 'auto-trigger'`), splice the result back in
-		* — preserving the byte-stable system prefix and the most-recent
-		* turns verbatim — and emit `context.compacted`. The compaction is
+		* - preserving the byte-stable system prefix and the most-recent
+		* turns verbatim - and emit `context.compacted`. The compaction is
 		* configured on the memory facade (`createMemory({ contextEngine })`,
 		* RB-46); there is no parallel agent-level knob.
 		*
 		* No-op when no memory is wired, when compaction is disabled or below
 		* threshold (the engine returns `false`), or for `secret`-tier runs
-		* (secret history is never shipped to the summarizer — a less-trusted
+		* (secret history is never shipped to the summarizer - a less-trusted
 		* external sink; per-result handle references land in WI-10). Best
 		* effort: a misconfigured engine (e.g. no summarizer) is swallowed and
 		* the run proceeds uncompacted rather than aborting mid-flight.
 		*
 		* Operator-requested compactions (`agent.compact()`, CE-3/AG-13) are
-		* serviced here too, FIRST — the queue carries the `compact()` promise
+		* serviced here too, FIRST - the queue carries the `compact()` promise
 		* resolvers, and manual requests bypass the trigger evaluation.
 		*/
 		async function* maybeAutoCompact() {
@@ -955,7 +1138,7 @@ function createAgent(config) {
 			if (mem === void 0) return;
 			if (config.sensitivity === "secret") return;
 			const engine = mem.contextEngine;
-			if (!await engine.shouldCompact(messages).catch(() => false)) return;
+			if (!await engine.shouldCompact(messages, { compactableFromIndex: systemPrefixLength }).catch(() => false)) return;
 			const startedAt = Date.now();
 			const envelope = await engine.compactNow({
 				scope: {
@@ -968,6 +1151,7 @@ function createAgent(config) {
 				agentId,
 				source: "auto-trigger",
 				messages: messages.slice(systemPrefixLength),
+				prefixMessages: messages.slice(0, systemPrefixLength),
 				memory: mem
 			}).catch(() => void 0);
 			if (envelope === void 0) return;
@@ -987,6 +1171,51 @@ function createAgent(config) {
 			};
 		}
 		/**
+		* context-engine-06: last-resort tier at hard context overflow. When
+		* a provider rejects the request as over-window, force ONE aggressive
+		* compaction (`preserveRecentTurns: 2`, trigger evaluation bypassed)
+		* and let the caller retry the same provider - the fallback chain's
+		* members usually share the same window, so without this the run just
+		* dies. Returns `true` when the buffer actually shrank (retry is
+		* worthwhile); `false` when memory is not wired, the run is
+		* secret-tier, compaction trimmed nothing, or the engine threw.
+		*/
+		async function* tryEmergencyCompact() {
+			const mem = memory;
+			if (mem === void 0 || config.sensitivity === "secret") return false;
+			const startedAt = Date.now();
+			const envelope = await mem.contextEngine.compactNow({
+				scope: {
+					userId: state.userId ?? agentId,
+					sessionId,
+					agentId
+				},
+				runId: state.id,
+				sessionId,
+				agentId,
+				source: "auto-trigger",
+				messages: messages.slice(systemPrefixLength),
+				prefixMessages: messages.slice(0, systemPrefixLength),
+				memory: mem,
+				preserveRecentTurns: 2
+			}).catch(() => void 0);
+			if (envelope === void 0 || envelope.result.droppedMessageIndices.length === 0) return false;
+			spliceCompacted(envelope);
+			yield {
+				type: "context.compacted",
+				runId: state.id,
+				sessionId,
+				agentId,
+				beforeTokens: envelope.result.beforeTokens,
+				afterTokens: envelope.result.afterTokens,
+				summaryTokens: envelope.result.summaryTokens,
+				durationMs: Date.now() - startedAt,
+				source: "auto-trigger",
+				hooksFiredCount: envelope.result.hooksFiredCount
+			};
+			return true;
+		}
+		/**
 		* Prefix-pinned splice shared by the auto + manual compaction paths
 		* (CE-3): stable system prefix + [summary, ...recent turns], with the
 		* post-compaction hooks' text Context Essentials re-anchored as a
@@ -1032,6 +1261,7 @@ function createAgent(config) {
 					agentId,
 					source,
 					messages: messages.slice(systemPrefixLength),
+					prefixMessages: messages.slice(0, systemPrefixLength),
 					memory: mem,
 					...pending.options?.preserveRecentTurns !== void 0 ? { preserveRecentTurns: pending.options.preserveRecentTurns } : {}
 				});
@@ -1069,6 +1299,7 @@ function createAgent(config) {
 		}
 		const handoffNames = Array.from(handoffMap.keys());
 		let stepNumber = 0;
+		let verifierRoundsUsed = 0;
 		let lastStepCalledToolNames = [];
 		async function* emitCancellation() {
 			yield {
@@ -1126,17 +1357,30 @@ function createAgent(config) {
 					type: "step.start",
 					stepNumber
 				};
+				currentStepSpan?.end();
+				currentStepSpan = tracer.startSpan({
+					type: "agent.step",
+					parent: runSpan,
+					attrs: {
+						"gen_ai.operation.name": "invoke_agent",
+						"gen_ai.agent.id": agentId,
+						"gen_ai.agent.name": config.name,
+						"graphorin.run.id": state.id,
+						"graphorin.step.number": stepNumber
+					}
+				});
 				yield* maybeAutoCompact();
 				const stepCtx = {
 					...runContextBase,
 					stepNumber,
-					messages
+					messages,
+					...currentStepSpan !== void 0 ? { span: currentStepSpan } : {}
 				};
 				const overrides = config.prepareStep ? await config.prepareStep(stepCtx) : {};
 				const useOverrideRegistry = overrides.tools !== void 0 && !isCodeMode;
 				const stepRegistry = useOverrideRegistry ? buildToolRegistry({ tools: overrides.tools }).registry : toolRegistry;
 				if (useOverrideRegistry) {
-					registerToolSearch(stepRegistry);
+					registerToolSearch(stepRegistry, config.toolPromotion === "run-boundary" ? "next-run" : "next-step");
 					registerReadResult(stepRegistry, resultReader);
 				}
 				const stepExecutor = useOverrideRegistry ? makeToolExecutor(stepRegistry) : toolExecutor;
@@ -1145,15 +1389,21 @@ function createAgent(config) {
 					if (h === void 0) throw new ToolNotFoundError(n);
 					return buildHandoffTool(h.agent);
 				});
+				const readOnlyRun = activeRunCapability === "read-only";
+				const keepReadOnly = (t) => {
+					const cls = t.__sideEffectClass ?? t.sideEffectClass;
+					return cls === "pure" || cls === "read-only";
+				};
 				let stepTools;
-				if (isCodeMode) stepTools = [...codeModeAdvertised, ...handoffTools];
+				if (isCodeMode) stepTools = readOnlyRun ? [...codeModeAdvertised.filter(keepReadOnly)] : [...codeModeAdvertised, ...handoffTools];
 				else {
 					const eagerTools = stepRegistry.listEager();
-					const promotedTools = promotedDeferred.size === 0 ? [] : orderPromotedTools(promotedDeferred, stepRegistry.listDeferred());
-					stepTools = [
+					const advertisedPromotions = runStartPromotions ?? promotedDeferred;
+					const promotedTools = advertisedPromotions.size === 0 ? [] : orderPromotedTools(advertisedPromotions, stepRegistry.listDeferred());
+					stepTools = readOnlyRun ? [...eagerTools.filter(keepReadOnly), ...promotedTools.filter(keepReadOnly)] : [
 						...eagerTools,
-						...promotedTools,
-						...handoffTools
+						...handoffTools,
+						...promotedTools
 					];
 				}
 				const calledLastStep = new Set(lastStepCalledToolNames);
@@ -1175,10 +1425,7 @@ function createAgent(config) {
 				}
 				const toolDefs = stepTools.map((t) => toolToDefinition(t));
 				const baseRequest = {
-					messages: structuredInstruction === void 0 ? messages : [...messages, {
-						role: "system",
-						content: structuredInstruction
-					}],
+					messages: buildStepMessages(messages, structuredInstruction, activeRunState?.todos),
 					...config.outputType !== void 0 ? { outputType: {
 						kind: config.outputType.kind,
 						...config.outputType.description !== void 0 ? { description: config.outputType.description } : {},
@@ -1196,6 +1443,8 @@ function createAgent(config) {
 					signal,
 					...overrides.temperature !== void 0 ? { temperature: overrides.temperature } : {},
 					...overrides.maxTokens !== void 0 ? { maxTokens: overrides.maxTokens } : {},
+					...config.cachePolicy !== void 0 ? { cachePolicy: config.cachePolicy } : {},
+					...currentStepSpan !== void 0 ? { parentSpan: currentStepSpan } : {},
 					reasoningRetention: reasoningPolicy
 				};
 				const stepUsage = zeroUsage();
@@ -1207,6 +1456,8 @@ function createAgent(config) {
 				let lastError;
 				let finalCalls = [];
 				let stepReasoningParts = [];
+				let requestForStep = baseRequest;
+				let emergencyCompactTried = false;
 				for (let chainIdx = 0; chainIdx < fallbackChain.length; chainIdx++) {
 					const candidate = fallbackChain[chainIdx];
 					if (candidate === void 0) continue;
@@ -1239,18 +1490,13 @@ function createAgent(config) {
 					let providerCallCompleted = false;
 					let providerStepUsage = zeroUsage();
 					try {
-						const stream$1 = providerForStep.stream(baseRequest);
+						const stream$1 = providerForStep.stream(requestForStep);
 						for await (const ev of stream$1) {
 							if (signal.aborted && pendingAbort?.drain !== true) throw new AgentRuntimeError("run-aborted", "aborted");
 							const out = handleProviderEvent(ev, evState);
 							if (out.emit !== void 0) yield out.emit;
 							if (out.providerError !== void 0) providerError = out.providerError;
-							if (out.usage !== void 0) providerStepUsage = {
-								promptTokens: providerStepUsage.promptTokens + out.usage.promptTokens,
-								completionTokens: providerStepUsage.completionTokens + out.usage.completionTokens,
-								totalTokens: providerStepUsage.totalTokens + out.usage.totalTokens,
-								...out.usage.reasoningTokens !== void 0 || providerStepUsage.reasoningTokens !== void 0 ? { reasoningTokens: (providerStepUsage.reasoningTokens ?? 0) + (out.usage.reasoningTokens ?? 0) } : {}
-							};
+							if (out.usage !== void 0) providerStepUsage = addUsage(providerStepUsage, out.usage);
 							if (out.finished === true) providerCallCompleted = true;
 						}
 					} catch (cause) {
@@ -1264,6 +1510,17 @@ function createAgent(config) {
 					}
 					if (providerError !== void 0) {
 						lastError = providerError;
+						if (providerError.kind === "context-length" && !emergencyCompactTried) {
+							emergencyCompactTried = true;
+							if (yield* tryEmergencyCompact()) {
+								requestForStep = {
+									...baseRequest,
+									messages: buildStepMessages(messages, structuredInstruction, activeRunState?.todos)
+								};
+								chainIdx -= 1;
+								continue;
+							}
+						}
 						if (!isAgentFallbackEligible(providerError, fallbackPolicy).eligible || chainIdx === fallbackChain.length - 1) {
 							yield {
 								type: "agent.error",
@@ -1289,10 +1546,7 @@ function createAgent(config) {
 							type: "reasoning",
 							text: evState.reasoningBuffer
 						}];
-						stepUsage.promptTokens += providerStepUsage.promptTokens;
-						stepUsage.completionTokens += providerStepUsage.completionTokens;
-						stepUsage.totalTokens += providerStepUsage.totalTokens;
-						if (providerStepUsage.reasoningTokens !== void 0) stepUsage.reasoningTokens = (stepUsage.reasoningTokens ?? 0) + providerStepUsage.reasoningTokens;
+						accumulateUsage(stepUsage, providerStepUsage);
 						break;
 					}
 				}
@@ -1317,15 +1571,13 @@ function createAgent(config) {
 				}
 				usageAcc.add(lastModelId, stepUsage);
 				addModelUsage(state, lastModelId, stepUsage);
-				state.usage.promptTokens += stepUsage.promptTokens;
-				state.usage.completionTokens += stepUsage.completionTokens;
-				state.usage.totalTokens += stepUsage.totalTokens;
-				if (stepUsage.reasoningTokens !== void 0) state.usage.reasoningTokens = (state.usage.reasoningTokens ?? 0) + stepUsage.reasoningTokens;
+				accumulateUsage(state.usage, stepUsage);
 				const leakCheck = causalityMonitor !== void 0 && textBuffer.length > 0 ? causalityMonitor.checkMessage(textBuffer) : void 0;
 				const leakBlocked = leakCheck?.leakDetected === true && leakCheck.decision === "block";
 				const assistant = buildAssistantMessage(leakBlocked ? LATERAL_LEAK_BLOCKED_NOTICE : textBuffer, stepReasoningParts, finalCalls, agentId, reasoningPolicy);
 				messages.push(assistant);
 				state.messages.push(assistant);
+				if (toolDataFlowGuard !== void 0 && textBuffer.length > 0 && !leakBlocked) toolDataFlowGuard.recordAssistant(state.id, textBuffer);
 				if (leakCheck?.leakDetected === true) {
 					const sha = sha256Hex(textBuffer);
 					yield {
@@ -1350,7 +1602,12 @@ function createAgent(config) {
 					endedAt: (/* @__PURE__ */ new Date()).toISOString(),
 					usage: stepUsage,
 					toolCalls: [],
-					agentId: state.currentAgentId
+					agentId: state.currentAgentId,
+					...config.recordProviderResponses === true ? { providerResponse: {
+						modelId: lastModelId,
+						...textBuffer.length > 0 ? { text: textBuffer } : {},
+						...finalCalls.length > 0 ? { toolCalls: [...finalCalls] } : {}
+					} } : {}
 				};
 				state.steps.push(stepRecord);
 				lastStepCalledToolNames = finalCalls.map((c) => c.toolName);
@@ -1365,9 +1622,11 @@ function createAgent(config) {
 					const execRunContext = {
 						...runContextBase,
 						stepNumber,
-						messages
+						messages,
+						...currentStepSpan !== void 0 ? { span: currentStepSpan } : {}
 					};
 					let batch = [];
+					let stepApprovalsRequested = 0;
 					for (const call of finalCalls) {
 						const handoff = handoffMap.get(call.toolName);
 						if (handoff !== void 0) {
@@ -1428,7 +1687,7 @@ function createAgent(config) {
 									toolCallId: call.toolCallId,
 									error: toolError
 								};
-								const text = `Error: ${toolError.message}`;
+								const text = renderToolErrorMessage(toolError);
 								messages.push({
 									role: "tool",
 									toolCallId: call.toolCallId,
@@ -1471,7 +1730,48 @@ function createAgent(config) {
 							});
 							continue;
 						}
-						if (await invokeNeedsApproval(stepRegistry.get(call.toolName), call.args, execRunContext, signal)) {
+						const resolvedTool = stepRegistry.get(call.toolName);
+						let gateInput = call.args;
+						if (resolvedTool !== void 0 && isApprovalGated(resolvedTool)) {
+							const parsed = safeParseGatedArgs(resolvedTool, call.args);
+							if (parsed !== void 0 && !parsed.success) {
+								const toolError = {
+									toolCallId: call.toolCallId,
+									toolName: call.toolName,
+									kind: "invalid_input",
+									message: `Invalid arguments for approval-gated tool '${call.toolName}': ${parsed.message}`
+								};
+								const stepEntry = state.steps[state.steps.length - 1];
+								if (stepEntry !== void 0) stepEntry.toolCalls.push({
+									call,
+									outcome: toolError,
+									stepNumber
+								});
+								yield {
+									type: "tool.execute.start",
+									toolCallId: call.toolCallId
+								};
+								yield {
+									type: "tool.execute.error",
+									toolCallId: call.toolCallId,
+									error: toolError
+								};
+								const text = renderToolErrorMessage(toolError);
+								messages.push({
+									role: "tool",
+									toolCallId: call.toolCallId,
+									content: text
+								});
+								state.messages.push({
+									role: "tool",
+									toolCallId: call.toolCallId,
+									content: text
+								});
+								continue;
+							}
+							if (parsed !== void 0) gateInput = parsed.data;
+						}
+						if (await invokeNeedsApproval(resolvedTool, gateInput, execRunContext, signal)) {
 							if (batch.length > 0) {
 								yield* dispatchBatch(batch, stepExecutor, execRunContext, stepNumber);
 								batch = [];
@@ -1487,39 +1787,82 @@ function createAgent(config) {
 								requestedAt: (/* @__PURE__ */ new Date()).toISOString()
 							};
 							state.pendingApprovals.push(approval);
-							state.status = "awaiting_approval";
-							const taintSnap = toolDataFlowGuard?.snapshotLedger(state.id);
-							if (taintSnap !== void 0) state.taintSummary = taintSnap;
-							if (promotedDeferred.size > 0) state.promotedTools = [...promotedDeferred];
+							stepApprovalsRequested += 1;
 							yield {
 								type: "tool.approval.requested",
 								toolCallId: call.toolCallId
 							};
-							if (config.checkpointStore !== void 0) await config.checkpointStore.put(state.id, "agent", {
-								id: state.id,
-								threadId: state.id,
-								namespace: "agent",
-								state: serializeRunState(state, { stripTracingApiKey: true }),
-								channelVersions: {},
-								stepNumber,
-								createdAt: (/* @__PURE__ */ new Date()).toISOString()
-							}, {
-								source: "sync",
-								status: "suspended",
-								nodeName: "agent.run"
-							});
-							return yield* finishRun(state, finalSnapshot);
+							continue;
 						}
 						batch.push(call);
 					}
 					if (batch.length > 0) yield* dispatchBatch(batch, stepExecutor, execRunContext, stepNumber);
+					if (stepApprovalsRequested > 0) {
+						state.status = "awaiting_approval";
+						const taintSnap = toolDataFlowGuard?.snapshotLedger(state.id);
+						if (taintSnap !== void 0) state.taintSummary = taintSnap;
+						if (promotedDeferred.size > 0) state.promotedTools = [...promotedDeferred];
+						if (config.checkpointStore !== void 0) await config.checkpointStore.put(state.id, "agent", {
+							id: state.id,
+							threadId: state.id,
+							namespace: "agent",
+							state: serializeRunState(state, { stripTracingApiKey: true }),
+							channelVersions: {},
+							stepNumber,
+							createdAt: (/* @__PURE__ */ new Date()).toISOString()
+						}, {
+							source: "sync",
+							status: "suspended",
+							nodeName: "agent.run"
+						});
+						return yield* finishRun(state, finalSnapshot);
+					}
 				}
+				currentStepSpan?.setAttributes({
+					"gen_ai.usage.input_tokens": stepUsage.promptTokens,
+					"gen_ai.usage.output_tokens": stepUsage.completionTokens
+				});
+				currentStepSpan?.end();
+				currentStepSpan = void 0;
 				yield {
 					type: "step.end",
 					stepNumber,
 					usage: stepUsage
 				};
 				if (finalCalls.length === 0) {
+					if (config.verifiers !== void 0 && config.verifiers.length > 0) {
+						const feedbacks = [];
+						for (const verifier of config.verifiers) {
+							let result;
+							try {
+								result = await verifier.verify({
+									output: String(finalSnapshot.output ?? ""),
+									state,
+									stepNumber
+								});
+							} catch {
+								result = { ok: true };
+							}
+							yield {
+								type: "verifier.result",
+								verifierId: verifier.id,
+								ok: result.ok,
+								...result.ok ? {} : { feedback: result.feedback },
+								stepNumber
+							};
+							if (!result.ok) feedbacks.push(`[verifier:${verifier.id}] ${result.feedback}`);
+						}
+						if (feedbacks.length > 0 && verifierRoundsUsed < (config.maxVerifierRounds ?? 1)) {
+							verifierRoundsUsed += 1;
+							const feedbackMessage = {
+								role: "user",
+								content: `Your response failed ${feedbacks.length} verification check(s). Address the feedback and answer again:\n${feedbacks.join("\n")}`
+							};
+							messages.push(feedbackMessage);
+							state.messages.push(feedbackMessage);
+							continue;
+						}
+					}
 					state.status = "completed";
 					break;
 				}
@@ -1541,6 +1884,15 @@ function createAgent(config) {
 			};
 			return yield* finishRun(state, finalSnapshot);
 		} finally {
+			currentStepSpan?.end();
+			currentStepSpan = void 0;
+			runSpan.setAttributes({
+				"gen_ai.usage.input_tokens": state.usage.promptTokens,
+				"gen_ai.usage.output_tokens": state.usage.completionTokens,
+				"graphorin.run.status": state.status
+			});
+			runSpan.setStatus(state.status === "failed" ? "error" : "ok");
+			runSpan.end();
 			if (parentSignal !== void 0) parentSignal.removeEventListener("abort", onParentAbort);
 		}
 		if (state.status === "running") {
@@ -1614,10 +1966,10 @@ function createAgent(config) {
 	}
 	/**
 	* Terminal wrapper around {@link finalize}: every exit path of the run
-	* loop — completed, failed, aborted, suspended — ends the stream with
+	* loop - completed, failed, aborted, suspended - ends the stream with
 	* an `agent.end` event carrying the final {@link AgentResult} (AG-20).
 	*/
-	async function* finishRun(state, snapshot) {
+	async function* finishRunBase(state, snapshot) {
 		while (pendingManualCompacts.length > 0) pendingManualCompacts.shift()?.resolve(noopCompactionResult("no-active-run"));
 		const result = finalize(state, snapshot);
 		if (result.status === "completed" || result.status === "failed") await spillWriter.clear?.(result.state.id).catch(() => {});
@@ -1692,8 +2044,26 @@ function createAgent(config) {
 		pendingAbort = options ?? {};
 		abortController?.abort();
 	};
+	const foldRunOutcome = (result, maxChars) => {
+		const steps = result.state.steps;
+		const toolNames = [...new Set(steps.flatMap((step) => step.toolCalls.map((c) => c.call.toolName)))];
+		const header = `[sub-agent '${config.name}' outcome] status=${result.status}; steps=${steps.length}; toolCalls=${steps.reduce((n, st) => n + st.toolCalls.length, 0)}` + (toolNames.length > 0 ? `; tools=${toolNames.join(", ")}` : "");
+		const text = typeof result.output === "string" ? result.output : JSON.stringify(result.output);
+		return `${header}\n${text.length > maxChars ? `${text.slice(0, maxChars)}\n[... ${text.length - maxChars} chars truncated by contextFold]` : text}`;
+	};
+	const taintFromChildState = (state) => {
+		const summary = state.taintSummary;
+		if (summary === void 0 || !summary.untrustedSeen && !summary.sensitiveSeen) return;
+		return {
+			...summary.untrustedSeen ? { untrusted: true } : {},
+			...summary.sensitiveSeen ? { sensitive: true } : {},
+			sourceKind: "sub-agent"
+		};
+	};
 	const toTool = (options = {}) => {
 		const exposeTurns = options.exposeTurns ?? "final";
+		const foldMaxChars = options.contextFold === void 0 || options.contextFold === false ? null : typeof options.contextFold === "object" ? options.contextFold.maxChars ?? 2e3 : 2e3;
+		const propagateTaint = options.propagateTaint !== false;
 		return {
 			name: options.name ?? `subagent_${config.name}`,
 			description: options.description ?? `Invoke sub-agent '${config.name}'.`,
@@ -1714,7 +2084,8 @@ function createAgent(config) {
 				const callOpts = {
 					...ctx?.signal !== void 0 ? { signal: ctx.signal } : {},
 					...ctx?.runContext.deps !== void 0 ? { deps: ctx.runContext.deps } : {},
-					...ctx?.runContext.sessionId !== void 0 ? { sessionId: ctx.runContext.sessionId } : {}
+					...ctx?.runContext.sessionId !== void 0 ? { sessionId: ctx.runContext.sessionId } : {},
+					...options.capability !== void 0 ? { capability: options.capability } : {}
 				};
 				const seed = options.inputFilter !== void 0 && ctx !== void 0 ? [...options.inputFilter(ctx.runContext.messages), {
 					role: "user",
@@ -1726,12 +2097,21 @@ function createAgent(config) {
 					for await (const ev of stream(seed, callOpts)) if (ev.type === "text.complete") turns.push(ev.text);
 					else if (ev.type === "agent.end") endResult = ev.result;
 					if (endResult !== void 0 && endResult.status !== "completed") throw new Error(`sub-agent '${config.name}' ${endResult.status}${endResult.error !== void 0 ? `: ${endResult.error.message}` : ""}`);
-					return turns.join("\n\n");
+					const allOutput = foldMaxChars !== null && endResult !== void 0 ? foldRunOutcome(endResult, foldMaxChars) : turns.join("\n\n");
+					const allTaint = propagateTaint && endResult !== void 0 ? taintFromChildState(endResult.state) : void 0;
+					return allTaint !== void 0 ? {
+						output: allOutput,
+						taint: allTaint
+					} : allOutput;
 				}
 				const result = await run(seed, callOpts);
 				if (result.status !== "completed") throw new Error(`sub-agent '${config.name}' ${result.status}${result.error !== void 0 ? `: ${result.error.message}` : ""}`);
-				if (exposeTurns === "none") return "";
-				return result.output;
+				const taint = propagateTaint ? taintFromChildState(result.state) : void 0;
+				const output = exposeTurns === "none" ? "" : foldMaxChars !== null ? foldRunOutcome(result, foldMaxChars) : result.output;
+				return taint !== void 0 ? {
+					output,
+					taint
+				} : output;
 			}
 		};
 	};
@@ -1847,6 +2227,35 @@ function probeSecretsAccessor() {
 	const rejector = (_key, _options) => Promise.reject(/* @__PURE__ */ new Error("secrets.require is unavailable inside a needsApproval predicate"));
 	return { require: rejector };
 }
+/**
+* tools-02: validate an approval-gated call's args at the pre-screen so
+* the gate decision - and what a human is asked to approve - is the input
+* that will actually execute. Structural + defensive: `undefined` when
+* the tool exposes no callable `safeParse` (nothing to validate here; the
+* executor still validates at dispatch); a throwing schema counts as a
+* validation failure rather than crashing the loop.
+*/
+function safeParseGatedArgs(tool, args) {
+	const schema = tool.inputSchema;
+	const safeParse = schema?.safeParse;
+	if (typeof safeParse !== "function") return void 0;
+	try {
+		const parsed = safeParse.call(schema, args);
+		if (parsed.success === true) return {
+			success: true,
+			data: parsed.data
+		};
+		return {
+			success: false,
+			message: parsed.error?.message ?? "schema validation failed"
+		};
+	} catch (cause) {
+		return {
+			success: false,
+			message: cause instanceof Error ? cause.message : String(cause)
+		};
+	}
+}
 
 //#endregion
 export { createAgent };