zidane/agent

TC39 explicit-resource-management await using sink — alias for Agent.destroy. Lets hosts write:

await using agent = createAgent({ ... })
await agent.run({ prompt: 'go' })
// agent.destroy() runs automatically at scope exit

Requires Node 20+ (or any runtime that ships the TC39 explicit-resource-management proposal). Older runtimes simply ignore the symbol; nothing breaks. Idempotent because destroy() is.

Cancel a single in-flight tool call by id without aborting the rest of the run. The matching call's ctx.signal flips and a tool:cancelled hook fires; the call's wire result becomes the canonical TOOL_USE_CANCELLED_MESSAGE with isError: true, while every other concurrent call keeps running and the assistant turn closes normally on the next batch boundary.

Returns true when a live call with that id was found and the cancel flag was flipped (idempotent — repeated calls return false). false when no such call is currently dispatching. The cancel is then parked and applied if a call with that id registers before the next run starts or the agent is destroyed, so a cancel issued after the call has already produced a tool_result has no effect.

The optional reason is forwarded to the tool:cancelled hook ctx and to the abort signal's reason field — useful for telemetry that wants to distinguish "user clicked cancel" from a host-side policy.

Summarize the session's older turns now, the way auto-compaction does inside a run: same summary, restoration of recently read files, hooks (compact:start / compact:progress / compact:end with reason: 'manual') and persistence. When the history still starts with the last request a run sent, that request is resent with the summary instruction so the provider reads it from its prompt cache.

Needs an idle agent: rejects while a run (or another compaction) is in progress, and isRunning is true while it works, so run() rejects meanwhile. Rejects when the summary call fails.

Categorized context-window usage — system prompt, rules, skills, MCP tools/instructions, searchable-tools catalog, tool definitions, conversation, deferred buckets, autocompact buffer, and free space. Computed on demand (the host opens a panel / popover). Available even before the first run: when no run snapshot exists yet it assembles a skills-only pre-run view (no MCP connect), so it never returns null for a live agent — only after destroy().

Per-category counts are heuristic estimates reconciled so the live categories sum to the real last-turn total; when the provider exposes Provider.countTokens (Anthropic, OpenAI), the system/tools buckets use exact counts and drop their estimated flag. One network round-trip on the exact path; the host decides when to call it.

The host supplies effectiveWindow (the model's rawWindow - outputReserve, resolved via the chat model registry which the agent core deliberately doesn't depend on). When omitted, free-space / fraction are computed against used only (bar still renders, just without spare-space).

The TEXT of every chunk in the session's default context, each tagged with where it came from — the sibling of Agent.getContextBreakdown, which reports the same assembly as token counts. Hosts render it as a "what is actually loaded" list the user can read, with the file-backed segments openable in an editor.

Reads the live run snapshot, falling back to the same pre-run assembly getContextBreakdown uses, so it's populated before the first message and returns null only after destroy(). Cheap: no provider round-trip and no tool serialization — just the already-assembled strings.

Instruction files (AGENTS.md / CLAUDE.md) are HOST-supplied via opts.rulesFiles: the agent receives the rendered rules block as an opaque substring of the host's system prompt and never reads those files itself, so it knows their paths at best and never their text. A host that already called discoverAgentsMd passes its files straight through — the shapes line up — and gets per-file segments with real paths. Omit it and the list covers only the agent-owned segments.

opts.rulesBlock is the rendered instruction block as it appears inside the system string. Pass it so the base-prompt segment can subtract it and the instruction text isn't reported twice (once in the system prompt, once as its own file rows). Falls back to the assembly's copy, which is only present when the host threaded AgentRunOptions.contextSections into run().

opts.systemPath likewise marks the base prompt as backed by a SYSTEM.md override, making that segment openable. Same rationale: the agent receives an already-composed system string with no provenance attached.

true while at least one background-task exit is queued for delivery on the next run() (the push-fed background:exit queue; pending stall signals don't count). Exits already acknowledged by the model (shell_kill, a successful wait_task, reading the output file) never surface here.

This is the host-side "auto-wake" signal: when it flips true while the agent is idle, a drain-only run({ prompt: '' }) delivers the <task-notification> block without waiting for the user's next prompt — prompt-less runs are explicitly legal in that state (see validateAndPrepareResume).

Host-side kill for a background task spawned via shell({ run_in_background: true }). Routes through the execution context's killBackground primitive, which SIGTERMs the whole process group and awaits the output stream's flush.

Returns true when a task was found and killed (or was already exited — the call is idempotent on terminated tasks). Returns false when:

• the task id doesn't exist in the context's registry, OR
• the execution context doesn't support killBackground (some remote sandboxes), OR
• the agent isn't bound to an execution handle yet (no run has ever fired).

Distinct from the model-facing shell_kill tool — that one routes through the model's turn so the kill is visible in the transcript. killBackgroundTask is for the host's UI ("cancel this task" in the TUI's ctrl+k picker); the kill is observational from the model's perspective, surfacing as the usual <task-notification> on the next turn.

Continue the session's run that a process death left unfinished, from its saved turns and the durable runtime's step records: finished steps answer from their records, a pending safe step runs again, a pending unsafe tool call is reported interrupted. Checkpoint runtimes only: in replay mode the platform re-runs the invocation (run with the same prompt) against its journal.

Resolves null when there is no such run, including one that crashed without step checkpoints (never marked resumable): the next run() heals that one, reporting its dangling tool calls as interrupted. Also null when the run's step records no longer match its saved turns (a history rewrite): the run is healed at once and resume:mismatch fires.

The resumed run keeps its id and record, and runs with the options its record kept (SessionRun.options: caps, an explicit model, thinking and model options), under what options.run passes. Per-run options the record does not keep (a spawned child's system prompt, depth and parent) come from options.run; unset, the agent's own apply.

Rejects without a checkpoint-mode durable runtime (also when durable is unset), while a run is in progress, or when the agent has no session (session / sessionId).

Queue a mid-run nudge injected as a user turn at the next tool/turn boundary. Returns false (and queues nothing) when no run is in flight or when the run's AbortController is already tripped — a steer can never revive or confuse a dead run, and a message queued between runs would otherwise leak into the NEXT run and skip its first turn's tool calls. Returns true when queued.

Hosts emulating Stop-hook semantics (queueing a follow-up on turn:after) should rely on this: a guard/user abort can fire mid-turn while turn:after still reports finishReason: 'stop', so an unconditional enqueue would otherwise leak a message into a dead run.

prompt takes the same values as run({ prompt }): text, or parts for text with images and documents. options.id comes back in steer:inject, so a host can tell which message the loop added. options.systemNotes follow the message, as run({ systemNotes }). Returns false for an empty prompt. Throws on a malformed part.

Pre-connect MCP servers without running a turn. Idempotent and concurrency-safe:

• No MCP servers configured → resolves immediately.
• Connection already established → resolves immediately.
• Another warmup() / run() is bootstrapping → awaits the in-flight promise.

Use from host code that wants to hide MCP bootstrap latency behind other startup work (UI init, auth, etc.). Safe to call multiple times and from multiple callers concurrently.

The run was aborted — fires exactly once per aborted run, on every abort exit: a between-turn cancel (the loop's signal.aborted check), a repeat-guard abort, AND a cancel that lands mid-stream (which throws out of the turn and is caught at the run boundary). For a guard abort a repeat-guard:exceeded (action: 'abort') event fired first, so consumers can attribute the cause.

Does NOT fire on graceful non-cancel terminations that still finalize the session run as 'aborted': maxConsecutivePauseTurns exhaustion and the maxCostUsd/maxTotalTokens budget breaker (the latter throws AgentBudgetExceededError). Branch on those via their own signals (finishReason: 'pause', the typed error) rather than agent:abort.

runId — the aborted run, for correlating with turn:after / telemetry spans. reason — the string passed to AbortController.abort(reason) when one was supplied (mirrors signal.reason); absent for a bare abort().

Run finished — fires on all exit paths (completion, maxTurns, abort, error).

The AgentStats carried here is cumulative across the parent agent loop and every recursively-spawned sub-agent (totalIn / totalOut / cost / totalCacheRead / totalCacheCreation). For parent-loop-only counts use ctx.turnUsage (parent-only array); for tree-wide turn counts use flattenTurns(ctx).length.

Fires once per agent.run() invocation, right after session:start (when a session is bound) and before the first turn:before. Symmetric with ['agent:done'].

tracingContext carries opaque parent trace metadata propagated from the spawning agent (typically a W3C { traceparent, tracestate } carrier injected by the parent's tracer on spawn:before). Tracers read it on the child run to continue the parent trace; absent on top-level runs.

Ownership of a background task was transferred from one execution handle to another — typically the spawn tool reassigning a subagent's still-running tasks up to the parent's handle so they outlive the subagent's destroy().

Hosts that listed the task under the source handle should update their view to reflect the new owner. The TUI's backgroundTasks registry drops the childId tag on the matching entry so the ctrl+k picker shows it as parent-level (and killBackgroundTask actually finds it).

Fires on the new owner's hook bus (the parent's, in the spawn case). The old owner is typically already torn down — wiring the event the other way would deliver it to a destroyed hookable.

Fires at the start of an agent.run() that has background exits to deliver, BEFORE they are rendered into <task-notification> blocks (runs with nothing to deliver skip the hook). exits merges the push-fed queue (background:exit arrivals since the last run) with a pull-based reconcile against ExecutionContext.listBackground — so exits land even when the context never calls onExit (remote / durable contexts can't push from a timer into a host journal).

This is the journalable seam for durable-execution hosts: the hook runs inside the run() await chain, so a handler may replace ctx.exits with a recorded copy, making the wall-clock-derived durationMs, and so the whole <task-notification> block, replay-stable. A replay-mode durable runtime already records the listBackground poll as a reconcile step.

Mutable: handlers may reorder, filter, or substitute entries. The post-hook array is what the model sees.

Fires when a background task is spawned via ExecutionContext.execBackground. Observational — telemetry consumers can mint a "task started" span.

outputPath is the file the context is streaming stdout+stderr to; the model reads it via read_file on demand. pid is the OS pid of the spawned shell wrapper (a process-group leader on POSIX, so a process.kill(-pid) on cleanup tears down the whole subtree).

Fires when a turn read back materially less cached prefix than the previous turn established — a prompt-cache break. Emitted by installCacheBreakLogger (zidane's cache-telemetry module), so like compact:* it only fires when that subsystem is installed on this agent's hook bus; the loop itself never emits it.

The payload names the request dimensions that changed (changed) with human-readable diffs (details). An empty changed means the request was byte-stable at this wire and the provider still dropped the prefix — TTL expiry, provider eviction, or (behind a format-casting gateway) churn introduced by the cast itself; see CacheBreakInfo for how to tell them apart. Hosts surface this as UI (TUI footer chip), metrics, or alerts; the text log line remains available for grep-based workflows and, unlike this hook, stays silent on unattributable breaks.

Fires at turn:before when the outgoing request DIVERGES from the previous completed turn's — the predictive counterpart of 'cache:break'. Emitted by installCacheBreakLogger from the request bytes alone, so it works on providers that report no cache usage and on format-casting gateways where this wire is the last observable point before the cast.

Drift + healthy cacheRead afterwards = the provider absorbed the change; drift + a 'cache:break' on the same turn = the break's attribution. Intentional rewrites (compaction cuts, stale-read stubs) drift by design — divergedAt tells them apart; see CacheDriftInfo.

Delivery is fire-and-forget: turn:before rides the loop's PROPAGATING hook timeout, so the emitter does not await consumers. Synchronous handlers complete before the request goes out; async handlers detach and must not assume the turn is still in flight; errors route to the installer's onEmitError, never into the run.

Gate-style child events. Unlike the other child:* events, the bubble passes the same ctx reference the subagent's loop is awaiting on: setting ctx.block / ctx.reason / ctx.result on a parent listener propagates straight back to the child, refusing or substituting the call.

Use these to gate subagent tool calls (native + MCP) from the parent without registering listeners on every child agent. The parent's own tool:gate / mcp:tool:gate listeners are NOT auto-shared with children — that would also share their budgets and dedup state.

Fires when loop-native auto-compaction (behavior.autoCompact) crosses its threshold, or agent.compact() starts (ctx.reason: 'manual'), and the summary call is about to run, BEFORE the provider round-trip. Distinct from context:overflow (the reactive, wire-only context_exceeded net) — this is the heavy compaction that summarizes older turns and mutates the session.

Use it to surface a "Compacting…" banner / footer state. Observational — handlers cannot cancel the compaction. Always paired with exactly one compact:end.

Resolves persisted content refs into provider-bound payload bytes.

Fires only when wire assembly sees a block carrying ref. Handlers set ctx.data to the resolved payload. The bytes are wire-only and are never written back to session.turns.

Fires when the loop catches a context_exceeded provider error and, before giving up, performs an emergency in-loop compaction (aggressive tail elision of older tool_result bodies) and re-issues provider.stream(). Does NOT fire when compaction can't shrink the request any further — that lands on stream:error (the terminal failure).

Runs independently of behavior.compactStrategy: the recovery calls the tail compactor directly, so it protects runs that never opted into client-side compaction. It can only shrink tool-result-heavy histories — a request whose mandatory text alone overflows still surfaces the error.

• attempt — 1-indexed recovery pass (each pass keeps fewer trailing turns intact and elides more; bounded).
• err — the raw context_exceeded error that triggered recovery.

Observational — handlers cannot cancel the recovery.

Fires exactly once per agent, the first time the execution handle is bound — right after the lazy execution.spawn() (or immediately on the first run when a handle was injected via AgentOptions.handle). spawned is true when the agent minted the handle, false for an injected one.

The seam durable hosts use to record the minted handle id (e.g. a sandbox id) for re-attach on replay/resume — journal it here, then re-attach via AgentOptions.handle + the provider's reconnect option on the next invocation. Observational; the handle is not mutable.

Fires when a server's bootstrap was skipped because it requires OAuth login and no tokens are stored. The host (TUI) surfaces this as a "needs-auth" status so the user can opt in to interactive login via loginMcpServer. Pairs with mcp:bootstrap:end ok:false — both fire, since the bootstrap did fail (just for a recoverable reason).

reason:

• 'no-tokens' — config has auth: 'oauth' set (or normalized from Cursor's authMethod: 'mcpOAuth') and the credential store is empty.
• 'auto-promoted' — server returned 401 + RFC 9728 metadata. No static Authorization header was set, so the server is eligible for OAuth login even though the config didn't explicitly request it.

Fires at the end of a per-server bootstrap attempt. durationMs spans from the matching mcp:bootstrap:start. On ok: false carries the originating error so consumers can log / trace without relying on a separate mcp:error.

lazy: true on the success arm signals the server registered its tools without opening a connection (see McpServerConfig.lazyConnect); the connect cost is deferred to the first tools/call. cached: true signals the bootstrap skipped tools/list because the host provided cachedTools — orthogonal to lazy (a server can be cached and eager, cached and lazy, or neither).

warnings (success arm only) collects soft signals that surfaced during bootstrap without aborting it — currently just "server rejected notifications/initialized with 4xx" from the tolerant client. Hosts can render a "connected with caveats" badge from this; consumers that don't care can ignore the field.

MCP-side counterpart of tool:gate. Same shape: set block to refuse, set result to substitute a successful payload and skip the upstream MCP callTool. When both are set across the handler chain, block wins.

Fires INSIDE the MCP wrapper's execute, after the loop's tool:gate already ran. Does not carry runToolCounts — those are loop-level and already exposed on tool:gate for MCP tools (which are registered as agent tools under their namespaced name mcp_<server>_<tool>). Use tool:gate for budget / dedup logic; reserve mcp:tool:gate for MCP-specific concerns (per-server routing, transport-aware refusals).

Fires once per server after listTools() and after the config-side filters (enabledTools / disabledTools / toolFilter) have applied, but BEFORE tools are registered. Handlers may mutate ctx.tools in place — splicing, reordering, or replacing entries — to further narrow what the model sees.

Composes with config-side filters: config drops tools the host's static policy excludes; this hook is the runtime escape hatch for per-user, per- environment, or capability-driven decisions that the config can't express.

Items are upstream tool descriptors (NOT yet namespaced as mcp_<server>_<tool>).

Fires once per successful bootstrap with the raw, pre-filter tool schemas the server advertised via tools/list (or that the host pre-seeded via McpServerConfig.cachedTools). Useful for hosts that want to:

• Persist a per-server tool catalog to disk so a settings UI can show every available tool — including ones currently hidden by disabledTools — without re-bootstrapping.
• Build per-tool toggle UIs that reflect the full server surface.
• Diff successive bootstraps to detect newly-added / removed tools.

Read-only — handlers must NOT mutate tools. Shape the model-facing list via mcp:tools:filter instead (which fires immediately after this hook and IS the mutation surface).

Does NOT fire when the bootstrap fails. Does NOT fire on lazy-connect servers' deferred first-call (the schemas were already known from cachedTools at the agent-construction boundary).

Fires when a stream fails terminally on the active provider+model target and the loop advances to the next entry of the run's fallback chain (AgentRunOptions.model array / multi-provider fan-out) instead of surfacing the error. Fires once per advancement; the terminal failure of the LAST target still lands on stream:error as usual.

Fallback is run-sticky: after this fires, the rest of the run stays on to (no ping-pong back to the primary); the next run() starts from the primary target again.

• from / to — provider name + model id of the exhausted and newly active targets.
• targetIndex — 0-based index of to in the resolved target list.
• err — the classified error that exhausted from (an AgentProviderError whose limit says when it was a rate limit, spent quota or overload); the raw provider error is its cause.
• discardedThinking — true when the failed attempt streamed reasoning before it failed; same meaning as on stream:retry.

Observational — handlers cannot cancel the fallback. To disable fallback, configure a single provider+model target.

Attribution note: agent:start's providerName comes from the PRIMARY target and is not updated when a fallback advances — this hook (and per-turn TurnUsage.modelId) is the source of truth for which target actually served a given stretch of the run.

Fires once per repair performed by the pre-send pairing pass (ensureToolResultPairing). The pass runs immediately before every provider call and patches over the wire-level corruption modes that Anthropic / OpenAI 400 on (orphan tool_use / tool_result, duplicate ids, compaction-stranded blocks).

Observational — handlers can mirror to Sentry/PostHog/etc. for postmortems on new corruption sources but cannot suppress the repair. The companion behavior.strictToolPairing flag is the consumer escape hatch for "throw instead of repair" (training-data collectors).

turnId lets handlers correlate a repair burst with the run-loop turn that observed it. Absent on repairs detected from the synthetic fallback path in agent.run()'s error catch (the orphan-tool_use fallback for crash recovery), where no turn is in flight.

Durable-execution replay finished — the invocation transitioned from journal replay to live execution (the first non-journaled provider stream or tool body just started).

The framework core never fires this: it is emitted by durable-runtime adapters (see createReplayTracker({ hooks }) in zidane/restate) once per handler invocation. Hosts that would otherwise infer liveness from side channels (counting live provider calls, watching stream hooks) should key on this instead. Fires at most once per invocation; never fires when the journal replays to completion without going live (nothing left to execute — and nothing left to abort).

Fires when the provider's stream rejects BEFORE stream:end — provider errors, network blips, malformed tools payloads (400 invalid_request_error).

err is the original thrown value, not the typed AgentProviderError the loop subsequently constructs; subscribe here to capture the native SDK exception (status codes, request ids) for telemetry without having to walk cause chains. Observational — the loop still wraps + throws after this hook resolves, so handlers cannot suppress the failure.

Best-effort convenience fields extracted from common SDK shapes (Anthropic, OpenAI, OpenRouter, Cerebras) when present on err:

• statusCode — HTTP status (e.g. 400, 429, 500, 502, 529)
• requestId — provider request id for grep-the-logs correlation

Both absent when the SDK doesn't expose them (network/early rejects, stream-internal protocol errors). Walk err.cause chains yourself for deeper diagnostics.

Does NOT fire on user-initiated aborts; those land on agent:abort instead. Use err instanceof Error && err.name === 'AbortError' to distinguish if you also subscribe here for raw error logging.

Fires when the loop catches a retryable provider error and is about to sleep before re-issuing provider.stream(). Does NOT fire on the terminal failure (the attempt the loop gives up on) — that lands on stream:error instead.

Use this hook to surface "Anthropic overloaded — retrying in Ns" in the TUI, count retries in observability, or short-circuit further retry logic from an outer harness.

• attempt — 1-indexed number of the attempt that just failed, counted in its retry budget: transport failures (a dropped socket) have their own, longer one, separate from behavior.retry.
• nextAttempt — attempt + 1, the attempt that will run after the sleep.
• delayMs — the wait the loop is about to take. Already accounts for any retry-after / retry-after-ms header the server returned and the configured maxDelayMs cap.
• err — the raw thrown value (same as stream:error.err).
• statusCode / requestId — extracted via the same helper as stream:error when available.

Observational — handlers cannot cancel the retry. To disable provider-classified retries, set behavior.retry.maxAttempts: 1.

Fires mid-stream when a provider that executes a tool server-side (currently: Anthropic's web_search_20250305) closes the server-tool-invocation content block. Symmetric with tool:before for function tools — surface the call into the transcript at the moment the model issued it, without waiting for the assistant message to finalize.

Shape is intentionally generic so future server tools reuse the same hook. id is the block's tool-use id (echoed back to the provider on follow-up turns); pair with stream:server_tool_result via that id.

Observational — handlers cannot block or substitute, since the call has already executed server-side by the time we see it.

Fires immediately before the loop calls provider.stream(). Pairs with stream:end / stream:error; lets observers timestamp the moment the request leaves the client to compute wait-vs-generate split and TTFT relative to provider dispatch (not run start).

startedAt is Date.now() at fire time. Observational — handlers cannot mutate the in-flight StreamOptions (use turn:before / context:transform / system:transform for that).

Fires per request, after context:transform and before the request goes out. Mutating ctx.system updates the system prompt the provider sends for this turn.

Anything written here must be byte-stable across turns

The system prompt sits ABOVE the whole conversation in the provider's cache prefix — Anthropic hashes tools → system → messages, cumulatively — so a one-byte change to ctx.system invalidates every message-level breakpoint and re-bills the entire transcript at the cache-write rate. Only tools and the static half of the system prompt survive, which is what makes this hard to spot: cacheRead stays large and non-zero (it becomes a CONSTANT equal to the scaffold) while cost climbs.

The classic way to get this wrong is a live tally: interpolating something like You have already read ${n} files… re-renders the prompt on most turns and quietly re-bills the transcript on each one.

Constant guidance strings, feature flags and run-stable facts are fine here. Live counters, timestamps, elapsed times, per-turn indices and anything derived from a growing tally are NOT — not even in the dynamic half below SYSTEM_PROMPT_BOUNDARY, which carries no cache_control of its own but is still inside the prefix that every message breakpoint hashes.

Genuinely per-turn state belongs in the transcript, persisted as immutable history so it cannot shift under the prefix on a later turn. A wire-only append to the newest message does NOT work either: that message re-renders without the append next turn and the prefix diverges there instead. Install installCacheBreakLogger while developing anything that writes here.

messages is read-only here; use context:transform for message surgery. session is undefined when the run is sessionless.

Fires when a durable run resumes a tool batch a previous process left unfinished, before any call of it runs again. done calls were rebuilt from their step records (show them finished); resuming calls run again or are reported interrupted. Optional for hosts: one that ignores it shows the run as running and fills in the calls when the batch ends.

Checkpoint runtimes only: in replay mode the loop cannot tell which calls are done before it issues them, and the hook would fire on every replay.

Fires when a per-tool budget configured via behavior.toolBudgets is exceeded for a specific tool. mode reflects how the framework reacted: 'steer' lets the call run and queues a post-turn nudge; 'block' refuses the call outright with Blocked: <message>.

count is the run-cumulative dispatched count just before this call. Use turnId to correlate with turn:after if you need the integer turn index. Distinct from budget:exceeded (byte-level) so consumers can subscribe specifically; both can fire in the same turn.

Fires after a tool-results user turn is pushed onto the conversation, before any byte-budget enforcement or follow-up steering. Symmetric with turn:after but for the user-role tool_result turn that closes the round-trip.

Why it exists: persistence layers must write tool_use/tool_result turn pairs together — if only the assistant turn (carrying tool_use blocks) is durable, a process death between turns leaves the DB with an orphan tool_use that Anthropic rejects on resume. Subscribe here to persist the tool-results turn before the loop continues.

Fires when a settled tool call's durable state (ToolContext.state) could NOT be committed — the backing AgentOptions.toolState store rejected the write.

The call itself is unaffected: the tool body already ran and its result is already on its way to the model, so failing the run over a bookkeeping write would be worse than losing it. But losing it silently is worse still — a dropped one-shot flag re-arms the exact bug durable tool state exists to prevent — so this is the seam for alerting on it. ops is the delta that did NOT land, in the order the tool staged it; replaying it by hand is a legitimate recovery.

Without a handler (or with one that leaves handled unset) the loop logs to stderr. Set handled = true when your handler owns the reporting and you don't want the duplicate log line.

Fires after a tool body produced a result (the execute path) or a tool:gate listener substituted one via ctx.result (the cache-substitute path). Carries the post-tool:transform payload — what the model actually sees on the wire.

Does NOT fire on gate-block / unknown-tool / validation-reject paths: the loop synthesizes their tool_result text inline and sends it back to the model, but no tool body produced output and no tool:transform ran. Consumers wanting symmetric per-call notification across every dispatch path should listen to tool:dispatched instead (which fires once per call regardless of path, with an outcome discriminator).

This narrow contract is deliberate: tracing spans opened in tool:before only get closed where they were opened, byte budgets only count real tool output, and chat-layer transcript renderers keep their tool ↔ tool-result pairing without special-casing the synthesized paths.

Fires when a single in-flight tool call is cancelled mid-flight via agent.cancelTool(callId) — typically the TUI's "cancel this tool" affordance. Distinguished from tool:error (the tool body threw), agent:abort (whole run aborted), and the batch-layer INTERRUPT_MESSAGE_FOR_TOOL_USE shape (sibling drain on full abort) so consumers can split the four causes.

Semantics:

• The tool's body has already received an abort signal (via the combined per-call + run signal); whether it actually unwound is up to the body's signal awareness.
• The framework returns the canonical TOOL_USE_CANCELLED_MESSAGE to the model with isError: true so the assistant turn closes cleanly and the model can continue with the next batch call.
• tool:after and tool:transform do not fire for a cancelled call — there's no real result the loop should account for.

runToolCounts mirrors the tool:gate / tool:before snapshot for this call (frozen, pre-increment) so a single per-call observer can subscribe to either hook without re-walking the run.

Symmetric notification fired ONCE per call the model dispatched, regardless of the path the call ultimately took through the loop. Every call that produces a tool_result closes with exactly one terminal event, so pair tool:dispatched with that terminal to reconstruct message history / close per-call spans:

• outcome: 'execute' → closes with tool:after OR, if the call was cancelled in-flight via agent.cancelTool, with tool:cancelled (NOT tool:after). A span keyed on dispatched(execute)→after will leak on cancel — also listen for tool:cancelled.
• outcome: 'gate-substitute' → closes with tool:after.
• outcome: 'gate-block' | 'invalid-input' → no tool:after (the body never ran); the dispatch event itself carries the result.
• outcome: 'unknown' → no tool:after; closes after tool:unknown (+ optional tool:error). The strict direction always holds: no tool:after fires without a preceding tool:dispatched.

Distinct from tool:before: tool:before fires when a tool's body is about to execute (the "I'm running this tool" notification) OR — as a special case — once with unknown: true for hallucinated tool names, so UI consumers rendering tool cards still see the model's attempt. It still skips gate-block / gate-substitute / validation-reject paths. tool:dispatched fires on all five paths with an outcome discriminator so live consumers never see a tool:after whose matching dispatch event was suppressed.

Strict ordering: tool:dispatched fires AFTER tool:gate / validation:reject / tool:unknown so the resolved outcome is always accurate. Fires BEFORE tool:before on the execute path so consumers binding both events see dispatched-then-before.

reason is set only when outcome === 'gate-block' and carries the gate's refusal text (so consumers can render denied-diff badges, etc. without a side channel).

Fires when a tool throws during execution. Mutate result to substitute a tool-output payload that gets sent back to the model in place of the default Tool error: <msg> string — useful for OSS-model error rewriting (collapse stack traces, hide internal paths, prepend recovery hints).

The post-hook value flows through tool:transform like a normal output, so downstream byte-budgeting and image-stripping still apply.

Fires before validation, tool:before, and execute. Two ways to intercept:

• Set block = true (with a reason) to refuse the call. The model sees a tool_result block with content = Blocked: <reason> and is_error: true. tool:before / tool:after do not fire; tool:dispatched does (with outcome: 'gate-block') so trace / audit consumers see the refusal. The exact wire payload is:

  {
    "type": "tool_result",
    "tool_use_id": "<call id>",
    "content": "Blocked: <reason>",   // verbatim, no wrapping XML
    "is_error": true
  }
  

  The Blocked: prefix is fixed (single space, no colon variations); the <reason> is whatever string the gate handler assigned to ctx.reason (defaults to 'Tool execution was blocked' if no handler set it). Pinned by test/per-run-hooks.test.ts so SDK consumers can safely string-match for telemetry / eval scoring.

• Set result to substitute a successful tool_result and skip execution. The model sees the substitute as a normal tool_result; tool:before does not fire, but tool:after and tool:transform do — so byte budgets, telemetry, and post-mutation hooks see the substitute. Useful for cache hits, dedup, idempotency guards, plan-mode synthetic acks.

If multiple handlers along the chain set both block and result, block wins — refusal beats substitution, so a policy gate (skills allow-list, custom security) can always override an upstream consumer's cache substitute. Mirrors the writable-result shape on tool:unknown and tool:error so consumers learn one pattern.

runToolCounts — frozen pre-call snapshot of per-tool dispatched counts in this run. Use it to self-throttle, drive observability, or implement budget guards. Counts every call that passed gate, including dedup substitutes; excludes blocked calls.

Concurrent fleets see the same pre-batch snapshot on every member's tool:gate; the built-in budget / dedup middleware reserves per-call atomically so behavior.toolBudgets enforces correctly even when multiple tool:gate callbacks fire in the same microtask.

Gate a tool call before it runs. Handlers share ONE mutable ctx and run sequentially in registration order (the order they were hook()-ed). The framework reads the final state once all handlers (including async ones, which are awaited) have run. Built-in behavior gates install during run setup and self-defer when another gate already set block / result.

Precedence across the resolved state:

• block beats result: if any handler left block === true, the call is refused (Blocked: <reason>, isError: true) and any result substitute is dropped. Security/refusal beats convenience/substitution.
• Among handlers, it is effectively last-writer-wins per field (each just mutates the shared ctx). Cooperative built-ins self-defer — e.g. repeat-guard early-returns when ctx.block || ctx.result is already set, so it never double-penalizes a call another guard already broke. Host handlers composing with the built-ins should do the same (check ctx.block/ctx.result before acting) to keep precedence predictable.

Set block = true (+ reason) to refuse, or assign result to short-circuit with a synthetic successful tool_result (the body never runs; tool:after still fires). Mutating ctx.input rewrites the args the body and downstream hooks see. metadata rides the refused tool_result (read only when the call is blocked).

Resumed calls (resumed): a checkpoint run resumed after a process death dispatches again the calls whose step was recorded, which passed the gate in the process that died. Their gate runs again so handlers restore what they keep per call, without asking anyone: the framework ignores result for them, and block too unless the call's body runs again. What a handler writes to resumeState (JSON, under a key of its own) is stored with the call's step record and comes back on a resumed call.

Fires before the generic "Unknown tool" error when the model invokes a tool that isn't registered (hallucinated names, dropped MCP servers, dangling aliases). Mutate result to substitute a friendly response or set suppressError: true to skip the companion tool:error emission.

Fires for any unknown tool name — including hallucinated MCP-style names (mcp_<server>_xxx); branch on name.startsWith('mcp_') to differentiate.

Privacy seam invoked by observability adapters (tracing, metrics, logging, persistence sinks) before attaching potentially-sensitive payloads as span attributes / log lines / external storage.

Handlers mutate ctx.redacted — the field starts equal to value and the final post-hook string is what consumers ship downstream. Default (no handlers) is no redaction. Multiple handlers compose left-to-right; the last writer wins.

kind lets a single handler do shape-aware scrubbing (system prompts vs. tool args vs. tool output have very different secret surfaces). meta carries context-specific identifiers (toolName, server, turnId, callId) the adapter knows at the call site — handlers use it for policy decisions ("skip redaction on internal read_file results"). Adapters that don't fire this hook simply attach raw values.

Synchronous-only by design: observability stays on the hot path. Heavy scrubbing (regex over MB of output) belongs in tool:transform instead.

Fires after each assistant turn (before its tool-result follow-up dispatches; the loop iterates back to a fresh turn:before once the tool results are produced).

toolCounts.turn — calls emitted by the model in this assistant turn, keyed by canonical tool name. Reflects what the model asked for, regardless of downstream gate outcome. Most useful for spotting per-turn spikes ("the model called todowrite 4 times in one turn").

toolCounts.run — cumulative running counter of dispatched calls scoped to this runId, captured at fire time. Excludes calls that were blocked by tool:gate handlers. Includes calls short-circuited via tool:gate result substitution (the model still asked, the framework just answered without the tool running). Resumed sessions start a fresh run with empty counts.

Both fields are frozen snapshots; mutate-safe.

aborted — runtime emissions always include this boolean; it is optional on the type only so tests/adapters that manually synthesize turn:after payloads do not break (treat absent as false). true when the run's AbortController was already tripped at the moment this turn:after fired. This is the case to branch on instead of usage.finishReason when emulating Stop-hook semantics: an aborted turn can still carry finishReason: 'stop' (e.g. a final text turn the user cancelled mid-stream), so finishReason alone cannot distinguish "model finished" from "we killed it".

Covers the streaming-abort path (cancel landed while the turn was streaming) and any abort that landed before this fired. NOTE: a tool:gate / repeat-guard abort trips DURING the tool batch, which runs after this turn:after — so the offending turn reports aborted: false here (its finishReason is 'tool-calls', never 'stop', so a 'stop'-keyed consumer won't misfire). That abort surfaces on the subsequent agent:abort. For the post-completion window (host queues a follow-up after a clean turn:after, then the run is aborted), rely on Agent.steer/Agent.followUp returning false once aborted. false on every normal turn boundary.

Fires when validateToolArgs successfully auto-coerced one or more input fields to satisfy the tool's inputSchema. Only fires when at least one coercion happened — never on perfectly-shaped inputs. Useful for counting model "wrongness rate" without re-running validation downstream.

coercions lists the field names that were coerced. The values landed in the input that the tool actually received; consumers wanting before/after comparison can re-run validateToolArgs(ctx.input, ctx.schema).

Time + UUID source for all journaled metadata (turn ids, createdAt stamps, runIds, hook payloads consumers may persist). Defaults to DEFAULT_AGENT_CLOCK (Date.now() / crypto.randomUUID()).

Override at the run level via AgentRunOptions.clock. Live-only measurements (TTFT, elapsed counters) keep Date.now() regardless.

Ignored on a replay-mode durable runtime (AgentOptions.durable): the run uses the runtime's clock, so replay regenerates byte-identical session metadata across attempts.

Decisions configuration for agent.decide / ctx.decide.

• omitted: use the first provider in provider that implements decisions, with its default decision model.
• an object: pin the provider, default model and/or timeout.
• false: decisions are disabled; every call returns { ok: false, reason: 'unavailable' }.

Pre-connect MCP servers in the background as soon as createAgent returns, instead of deferring the bootstrap to the first agent.run().

Useful when MCP latency is the dominant cost of a cold start: callers that construct the agent early (e.g. at process init) can hide the bootstrap behind other setup work. If bootstrap fails while a run() / warmup() is awaiting the same in-flight promise, that caller sees the error. Otherwise the failure is dropped and the next run() / warmup() retries the connection.

Also starts skills resolution when skills are configured. No-op when there are no MCP servers and no skills. Default: false.

Pre-built ExtensionRegistry to fold into this agent, synchronously.

Build it first (async) via buildExtensionRegistry(defs.map(inlineLoadedExtension)), then pass the RESULT here — createAgent is sync, so it takes the merged registry, not raw definitions. Folded when the agent is created (see foldExtensionRegistry), with explicit AgentOptions winning on collision:

• tools — merged by name; mcpServers — deduped by name (explicit wins on collision).
• skills — last-wins: an explicit skills REPLACES the extension's wholesale (composePresets doesn't per-skill merge).
• hooks — bucketed per event; handlers from BOTH the registry and hooks fire (registry first).
• system fragments — appended AFTER system (blank-line separated).
• subagents — applied to whichever spawn tool survives, via spawn.withSubagents.

Config is NOT folded: ctx.config.get reads at runtime through the registry's own captured readSettings getter (a registry built without one returns declared defaults). themes / agents / providers are host/picker concerns and intentionally stay out of the agent.

Pre-bound execution handle. When set, the agent uses it verbatim and does NOT call execution.spawn() — and does NOT destroy() it on teardown, since the host owns its lifecycle.

The durable-execution use case: a host that needs the spawn to be a recorded, replay-stable side effect drives execution.spawn() itself as a step of its durable runtime and hands the resulting handle here. On replay the recorded handle comes back identical, so the agent re-attaches to the same sandbox/container instead of minting a fresh one (which the internal lazy spawn, being unrecorded, cannot guarantee). Pair with a context that can re-attach by handle id (e.g. createSandboxContext, whose handle id IS the sandbox id) and a provider sandboxId for the underlying backend.

For host-observation without driving spawn yourself, see the execution:ready hook, which fires once with the bound handle.

A function form resolves the host-owned handle lazily, at the moment the agent would otherwise spawn (first run / ensureExecution()) — for hosts that build agents synchronously but keep one handle across rebuilds (chat/execution-cache.ts). Same ownership contract: never spawned, never destroyed by the agent.

Agent-lifetime hook registrations. Registered once when createAgent returns; identical in effect to calling agent.hooks.hook(event, fn) for each entry. Use this to bake observability / policy hooks into a Preset so consumers get them automatically via ...spread.

Handlers may be a single function or an array — the array form is what composePresets() produces when multiple presets register handlers for the same event. Unknown event names throw at agent construction so typos never silently no-op.

For per-run handlers (auto-detached at run end) use AgentRunOptions.hooks.

Override how mcpServers are connected and their tools discovered — see McpConnector. The default connects via connectMcpServers; supply your own to inject a custom transport / auth provider. To journal discovered tools for a durable runtime, use mcpToolWrap instead — it composes with any connector.

Invoked lazily on the first run() / warmup(), with the agent's hooks. A connector that bypasses connectMcpServers also bypasses its config normalization, so prefer delegating to it.

Wrap every discovered MCP tool right after bootstrap, before it's registered into the agent's tool map — see McpToolWrap. This is the seam native tools have (you wrap them before createAgent) that discovered MCP tools lack: the agent owns their discovery, so it applies the wrap on your behalf, for both eager and lazily-connected servers and regardless of which mcpConnector produced them.

Not needed for durable execution: a replay-mode runtime records MCP tool calls as steps like native ones. Discovery, mcp_<server>_<tool> namespacing, per-server instructions, hooks, and OAuth all stay owned by the agent: the wrap only re-shapes execute.

LLM provider(s) driving the agent.

A single Provider is the common case. Passing an array enables run-level fallback chains: AgentRunOptions.model entries reference providers by Provider.name, and bare-string model ids fan out across every provider in array order. Names must be unique within the array. The FIRST provider is the primary — agent-level surfaces (agent.meta, getContextBreakdown, the default model when model is omitted) read it.

Map canonical tool names to LLM-facing (aliased) names.

Aliasing is LLM-boundary-only: the alias is what the provider's tool spec carries and what the model calls the tool; the canonical name is what lives in session.turns and what the agent uses to look up the tool implementation.

Override the LLM-facing description of any tool — native, host-provided, or MCP-discovered — keyed by canonical name (shell, mcp_<server>_<tool>; same keys as toolAliases, so aliases and MCP name sanitization never enter into it).

A string replaces the description; a function receives the current text (after every framework rewrite — e.g. shell's per-run background gate) and returns the new one, which is the form to use for amendments:

toolDescriptions: {
  shell: cur => `${cur}\nNever invoke sudo.`,
  mcp_github_create_pull_request: 'Open a PR. Always target `develop`.',
}

Applied once per run, last, so it reaches every surface that reads spec.description: the wire tool list, the lazy <searchable_tools> catalog, tool_search results, and the context breakdown. Keys that match no registered tool are ignored (an MCP server may be offline for that run). Composes through presets (later wins per key) and is inherited by spawned subagents.

Tune Agent.cancelTool's per-call kill registry.

• defaultMessage — reason stamped on the abort signal (and surfaced to the tool:cancelled hook) when cancelTool(callId) is called without an explicit reason. Defaults to 'user-cancelled-tool'.

The registry also handles the pre-registration race: a cancelTool issued for a call the loop hasn't dispatched yet (the host saw the id in the streamed turn) is parked and applied the moment the call registers, rather than dropped. No configuration needed for that — it's always on.

Durable backing for ToolContext.state — the key/value map tools use for information that must survive a resume (a one-shot payload already delivered, a cursor, a dedup marker).

Runtime-agnostic on purpose: with durable, a session or sessionId, and no store here, the runtime's stores.toolState(<session id>) is used, and any host can implement the same two methods against Redis / Postgres / a file. With no store configured ctx.state is still present and functional, backed by an in-memory map scoped to this agent instance — so tools written against it work identically on the local CLI path, just without durability.

The snapshot is loaded once per agent, before the first tool dispatch; writes are staged per call and committed when the call settles.

NOT inherited by subagents. A child you build yourself can be handed the same store, but createSpawnTool has no shareToolState counterpart to shareReadState, so tools inside a spawned subagent see an isolated in-memory map and their writes never reach this store.

Absolute floor for "this turn missed cache". The logger reports when cacheRead falls below the threshold AND the dimensions differ from the previous turn.

Defaults to 1, which on its own only catches TOTAL cache loss. That is not the common failure: when the system prompt or the message prefix is rewritten, tools + the static system block still match, so cacheRead stays comfortably non-zero — pinned to a CONSTANT equal to that scaffold — while the entire conversation re-bills at the cache-write rate. An absolute-only threshold reports such a run as perfectly healthy.

CacheBreakLoggerOptions.expectedReadRatio is the fix and is on by default; this field remains as the absolute floor beneath it.

Detect PARTIAL-prefix breaks by comparing this turn's cacheRead against the prefix the previous turn established (cacheRead + cacheCreation). The conversation only grows, so a healthy turn reads back at least what the one before it wrote; reading materially less means something at or before the last message changed.

Defaults to 0.8 — the slack absorbs tokenizer jitter and any uncached dynamic system block, which is re-billed by design. Set 0 to disable and detect only total loss through expectedReadAtLeast.

Sink for log lines. Defaults to console.error. Use a Logger or a test buffer here when you want the output to land somewhere other than stderr.

NOT every line is a dimension diff: unless onEmitError is provided, 'cache:break' handler errors are also routed here (prefixed cache-break: 'cache:break' handler threw:). A host that counts log invocations as "dimension changes" — the journal-mode wiring — should either pass onEmitError or count via the 'cache:break' hook instead.

Per-message content hashes, in order. Compared POSITIONALLY against the previous turn so that appending messages — what every healthy turn does — is not mistaken for a rewrite. A single cumulative hash cannot make that distinction: it changes on plain growth too, and would name this dimension on literally every break, drowning the real culprit.

Tracked because the expensive real-world breaks live here, not in the request scaffold: compaction, stale-read elision, media age-out and history trimming all rewrite the transcript mid-conversation, and none of them touch system, tools, or the model id. A run can lose its entire transcript to a cache miss with every other dimension reading perfectly stable.