Skip to content

jaz.hooks.events

New to JAZ? This is generated API reference. Start with the docs and the concepts overview.

Public API of the jaz.hooks.events submodule (import from jaz.hooks.events, e.g. from jaz.hooks.events import ...).

Every event has a matching handler on jaz.hooks.Hook, named after it (LLMQueryEnter → on_llm_query_enter). A handler observes the event and returns a list of effects; returning effects is the only way a hook influences the run. Which effects are accepted depends on the event — each event class documents its own allowed set, and an effect returned at an event outside that set raises InvalidEffectError (out-of-stage effects are hook bugs and fail loudly, never silently no-op). A hook that treats every event alike overrides on_any instead:

from jaz.hooks import Hook
from jaz.hooks.effects import Abort, Effect
from jaz.hooks.events import LLMQueryEnter
class StopAfterTenTurns(Hook):
def on_llm_query_enter(self, event: LLMQueryEnter) -> list[Effect]:
if event.iteration >= 10: # iterations are 0-based
return [Abort(error=RuntimeError("too many turns"))]
return []

Each span’s events follow one pipeline of value states:

proposal ──[edits]──▸ committed input ──[work or supply]──▸ raw result ──[modify]──▸ outcome
*Enter observes the proposal controls edits + abort fires always
*Send observes the committed input controls supply + abort fires iff the input committed
*Complete observes the raw result controls modify + abort fires iff a raw result exists
*Exit observes the outcome union controls abort (per-turn) fires whenever the span opened

Events mark value states becoming fixed, not phases of the machinery: an event’s payload is the commit of the previous stage’s effects, so no event can observe its own composition’s output — only the next event can carry it. *Send therefore fires on the supplied/replayed path too (the input commit is real even when no provider is called), and *Exit carries a tagged outcome union (Completed[...] | Aborted | Failed — the variant IS the span status, its payload the post-transform result or the terminating exception), so an interval that opened always closes, with the true outcome. A BlackboardWrite is valid at every event, these included; beyond it the per-turn LLMQueryExit / REPLExecExit accept an Abort on every arm, and InvokeExit accepts nothing.

The events, by span:

  • InvokeEnter / InvokeSend / InvokeComplete / InvokeExit — one quadruple per invoke.
  • LLMQueryEnter / LLMQuerySend / LLMQueryComplete / LLMQueryExit — the per-turn LLM call.
  • LLMQueryRetry — fired per retry attempt of that call.
  • REPLExecEnter / REPLExecSend / REPLExecComplete / REPLExecExit — the turn’s REPL execution. This is the one conditional span: it opens only on a turn that reaches execution, so it is skipped when the query span ended without getting there — the call errored, or a hook aborted at any of the LLMQuery events, LLMQueryComplete and LLMQueryExit included, which abort after a response exists. What does not skip it is the response’s content: BaseProtocol.parse is contracted to return the code and never raise, and an empty parse is empty code, so an empty, blank or prose-only response opens the span like any other. (A protocol that raises anyway is terminal — nothing catches it — and ends the invoke rather than skipping the span.)

The shape of every event follows from four principles:

  1. Ambient invoke context rides every event. What belongs to the invoke rather than to any one span — config, scope, hooks, blackboard, plus the identity invoke_id/depth — is a base Event field, stamped on every event by the dispatcher. None of it is a proposal: no *Enter effect edits it and no *Send carries an edit record for it. (blackboard still advances between events, by BlackboardWrite, and hooks is the live active set.)
  2. An *Enter carries what its effects can edit, as the proposal. Under the field’s own name: inputs, messages, code and namespace.
  3. A *Send carries the same fields committed, plus one <thing>_edits per field. input_edits, message_edits, code_edits, namespace_edits — each a Resolved<Thing>Edits of self-contained records of what every enter-time effect did, one sequence per effect named by its verb (adds/drops, inserts/deletes), ordered by the coordinate a record names (name, position, offset) and, where a coordinate can repeat, by the order the fold applied them within it — a drop record carrying the value it removed, read off the Enter snapshot. Only same-slot message adds and same-offset code inserts can share a coordinate; each sequence’s own docstring says what its order resolves to there.
  4. An effect edits the field it is named for, and only that. DropInputs edits inputs (a jaz.scope value is not an input); AddToNamespace edits namespace.

Which gives, per span:

┌─────────────────────┬──────────────────────┬──────────────────────┬──────────────────────────────────┐
│ │ Invoke │ LLMQuery │ REPLExec │
├─────────────────────┼──────────────────────┼──────────────────────┼──────────────────────────────────┤
│ Enter: the proposal │ inputs │ messages │ code, namespace │
│ Send: committed │ inputs │ messages │ code, namespace │
│ Send: the edits │ input_edits │ message_edits │ code_edits, namespace_edits │
│ ← effects │ AddInputs/DropInputs │ AddMessages/ │ InsertCode/DeleteCode, │
│ │ │ DropMessages │ AddToNamespace/DropFromNamespace │
│ record sequences │ adds, drops │ adds, drops │ inserts, deletes; adds, drops │
│ Enter → Send shape │ same │ same (stamped) │ same │
│ Loop → span handoff │ send(inputs) │ send(shown_messages) │ send(namespace) │
└─────────────────────┴──────────────────────┴──────────────────────┴──────────────────────────────────┘

Outside that shape, and each deliberate:

  • DisableRecursion and WithholdREPLHistory are InvokeEnter effects that edit no field (they withhold invoke and __history__, which are not inputs), so they are recorded as InvokeSend.recursion_disabled and InvokeSend.repl_history_withheld rather than inside any <thing>_edits; their result shows one span later, as the absence of invoke or __history__ from namespace["__builtins__"] in REPLExecEnter.namespace.
  • LLMQueryRetry is not a value-state event, so the stage table above does not describe it: it fires per retry rather than at a commit, only on this span, and accepts no effects. It rides the retry policy’s before-sleep, so it counts the attempts that are followed by another one: a turn whose first attempt succeeds never fires it, and the final failure — the one that exhausts the policy and propagates — fires nothing either. It has no *Enter/*Send counterpart because a retry commits nothing, and no counterpart on the other spans because only the provider call is retried.
  • *Exit is terminal on every span, but the two per-turn spans accept Abort there, on every arm, while InvokeExit stays observation-only. The per-turn opening buys aborting on the post-transform result — a re-priced cost, say. An invoke aborting at its own terminal Exit would instead make that event’s payload diverge from what the caller receives, and InvokeComplete already governs the final result.

Events also carry coordinates that place them, which the table does not show because they are neither proposal nor edit and no effect touches them: which turn (iteration, on every per-turn event), which invoke and how deep (invoke_id, depth), when (timestamp, a base field like the ambient context but varying per event rather than per invoke), and on InvokeEnter which invoke and which of its turns spawned this one (parent_invoke_id, parent_repl_iteration). The payload a *Complete or *Exit carries is not in the table either; those stages are the pipeline’s, described above it.

Two deliberate non-uniformities in the records: only the message records carry persistent (only the message buffer has a per-query vs carried-forward distinction), and REPLExecEnter.namespace/REPLExecSend.namespace are exact for PythonREPL and best-effort for a REPL whose namespace it cannot read (see BaseREPL.get_namespace). An observer written against one Send reads the others the same way.

Base class for all events.

Events represent discrete points in the agent’s execution lifecycle where hooks can observe and influence behavior.

Every event carries invoke_id (the invoke it belongs to), depth (that invoke’s nesting depth — 1 for a top-level invoke, one more per sub-invoke), config (the effective configuration the invoke runs under, overrides applied), scope (the resolved jaz.scope values in effect for it, as a read-only mapping) and hooks (the hook instances in effect for it).

Every event carries timestamp — the moment it was emitted to hooks, as a timezone-aware UTC datetime. Durations are consumer arithmetic over two events’ timestamps: Exit.timestamp - Enter.timestamp is a span’s boundary-to-boundary interval, and the Send/Complete stamps give the per-stage breakdown. There are no interval fields on any event.

Every event also carries blackboard — the per-invoke key-value store hooks use to receive caller data and to coordinate with one another, as a read-only Mapping. Read it like a dict (event.blackboard.get("label")); the only way to write is to return a BlackboardWrite effect, which the dispatcher applies after every hook for the event has run. A write is therefore invisible to the event that produced it and visible from the next event onward, so producer and consumer hooks coordinate without depending on dispatch order.

One board per invoke, and a nested invoke gets its own. “Per-invoke” means one board each, not one shared down the tree: a sub-invoke seeds a fresh board before its own InvokeEnter, so no board write crosses the boundary in either direction — the child does not see what the parent wrote, and the parent’s board is unchanged by the child.

Values still cross, just not on the board. Downward, seed them: Hook.blackboard_seed runs again for every invoke the hook is active in, which is what an ambient with MyHook(): gives you and a per-call invoke(MyHook(), ...) deliberately does not. Upward, or across siblings, the carrier is the hook instance’s own attributes — a hook that stores something while the child runs can write it to the parent’s board at the parent’s next event. That is the supported way to accumulate across invokes; the board is not.

A key that has not been produced is simply absent: board[key] raises KeyError and board.get(key) returns None (or the supplied default). “Not produced yet” and “never produced” read identically on purpose — a consumer must not be able to tell whether a producer hook has not run yet or is not active at all. Read defensively: prefer .get(key, default) and treat absence as “no value this generation.”

Event objects must be treated as immutable and should never be mutated. Side effects are emitted by returning effects from the event handler (see Hook).

That rule is wider than what the framework enforces, so treat it as absolute rather than as “whatever raises”. Enforcement stops at the container: rebinding a field raises, and the mappings and sequences an event carries are copies that reject writes. Past that line nothing is promised — what those containers hold is the framework’s own state. Some of it happens to be immutable (an exec result is a NamedTuple, a Config is frozen), and the rest is live: input and scope values, message dicts, namespace bindings, the components inside config, the peer instances in hooks, the LLMResponse on an LLMQueryComplete, the value on an edit record. Mutating one of those changes the run, with none of the ordering guarantees that make effects safe. Read through an event; write by returning effects.

__init__(*, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None

The span produced its normal result, carried as result.

One of the three outcome variants every *Exit event’s outcome field holds (Completed[...] | Aborted | Failed). The variant is the span status: match on the type to branch on how the span ended, and read the payload off the matched variant — there is no parallel status enum to keep in sync.

T is the span’s payload type: LLMResponse for the LLM query, ExecResult for the REPL execution, Return | Raise for the invoke.

__init__(result: T) -> None

The span was deliberately stopped by an Abort; exception carries the abort’s error.

See Completed for the outcome-union contract.

__init__(exception: BaseException) -> None

The span’s machinery unwound on an in-flight exception before a result existed; exception carries the propagating error (which still propagates after the exit event fires).

See Completed for the outcome-union contract.

__init__(exception: BaseException) -> None

Bases: Event

Fired before executing parsed REPL code.

Not every turn. It fires only on a turn that reaches execution, so a turn is skipped entirely when the LLM call itself errors, or when a hook emits an Abort at any of the LLMQuery events — including LLMQueryComplete and LLMQueryExit, which abort after a response exists. The response’s content never skips it: an empty or unparseable response is empty or nonsense code, which the REPL judges.

Allowed effects:

  • Abort — abort the invoke.
  • AddToNamespace — bind names into the REPL namespace before the code runs.
  • DropFromNamespace — unbind names from the REPL namespace before the code runs.
  • InsertCode — insert source into the proposed code before it runs.
  • DeleteCode — delete a character range from the proposed code before it runs.

InsertCode / DeleteCode edit the code (the LLM-message twins are AddMessages / DropMessages); AddToNamespace / DropFromNamespace edit the namespace. Both edit this event’s proposal — code here is the LLM’s original, and the composed edits produce the committed code that REPLExecSend carries and the REPL runs.

Suppliers do not compose here: SupplyExecResult is a REPLExecSend effect — a supplier decides on the basis of the committed code, which at this event composition may still rewrite.

Attributes

  • iteration (int) — The agent-loop iteration this execution belongs to.
  • code (str) — The REPL source proposed by the LLM, before any enter-time InsertCode / DeleteCode edits (which produce the committed code carried by REPLExecSend).
  • namespace (Mapping[str, object]) — The REPL namespace as it stands before this turn’s AddToNamespace / DropFromNamespace edits — the agent’s globals() (inputs, hook bindings, the agent’s own assignments from earlier turns, and __builtins__ as a read-only copy, which holds the allowed builtins and the framework’s invoke and __history__), as a read-only snapshot whose variables’ values are the live objects. What the REPL reports via BaseREPL.get_namespace, so a REPL whose namespace it cannot read may report less. The edited-then-committed namespace rides REPLExecSend.namespace.
__init__(iteration: int, code: str, namespace: Mapping[str, object], *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None

Bases: Event

Fired when an execution’s code has committed — code + namespace deltas are final.

Fires after REPLExecEnter’s AddToNamespace / DropFromNamespace have been applied to the REPL namespace, before the code runs — including when a supply then short-circuits the execution (the namespace deltas committed either way).

Allowed effects:

  • SupplyExecResult — supply a result in place of running the code; the code is not executed and the supplied result becomes the turn’s raw result.
  • Abort — abort the invoke, declining the committed code.

Attributes

  • iteration (int) — The agent-loop iteration this execution belongs to.
  • code (str) — The REPL source about to be executed (or short-circuited) — the enter-time proposal after any InsertCode / DeleteCode edits were folded in.
  • code_edits (ResolvedCodeEdits) — The enter-time edits that produced code, as self-contained records (see ResolvedCodeEdits).
  • namespace_edits (ResolvedNamespaceEdits) — The enter-time edits that produced namespace from REPLExecEnter.namespace, as self-contained records (see ResolvedNamespaceEdits).
  • namespace (Mapping[str, object]) — The REPL namespace the committed code runs against — the agent’s globals() (inputs, hook bindings, the agent’s own assignments, and __builtins__ as a read-only copy, which holds the allowed builtins and the framework’s invoke and __history__) after this turn’s deltas. The mapping is read-only; the variables’ values are the live objects. What the REPL reports via BaseREPL.get_namespace, so a REPL whose namespace it cannot read may report less.
__init__(iteration: int, code: str, namespace: Mapping[str, object], code_edits: ResolvedCodeEdits = ResolvedCodeEdits(), namespace_edits: ResolvedNamespaceEdits = ResolvedNamespaceEdits(), *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None

This execution’s enter-time code edits as self-contained, pre-resolved records.

inserts records InsertCode, deletes records DeleteCode — each sequence named by the verb of the effect it records, the rule every <thing>_edits field follows. A record carries what the edit did, including what it removed: a delete record is one run of removed source after the DeleteCode ranges are unioned, so the delete records never overlap (see CodeDeleteRecord).

Ordering: inserts in application order (by resolved offset, hook order within one); deletes by resolved start (disjoint, so that is a total order).

__init__(inserts: Sequence[CodeInsertRecord] = (), deletes: Sequence[CodeDeleteRecord] = ()) -> None

This execution’s enter-time namespace edits as self-contained records.

adds records AddToNamespace, drops records DropFromNamespace — each sequence named by the verb of the effect it records. A drop record carries the value it unbound, read off REPLExecEnter.namespace (the namespace before the drops).

Ordering: both sequences sorted by name — a record’s coordinate, the rule every <thing>_edits sequence follows.

__init__(adds: Sequence[NamespaceAddRecord] = (), drops: Sequence[NamespaceDropRecord] = ()) -> None

One InsertCode edit folded into this execution’s committed code.

Attributes

  • text (str) — The inserted source.
  • position (int) — The resolved offset into the enter-time code the text was inserted at (a negative at counts from the end; this is the absolute result).
__init__(text: str, position: int) -> None

One run of source the DeleteCode edits removed from this execution’s enter-time code.

A record is what was removed, not which effect asked: overlapping and adjacent DeleteCode ranges are unioned into disjoint runs, one record each, so the records never overlap and their text sums to exactly what the committed code lost; an empty range removes nothing and leaves no record.

Attributes

  • start (int) — The resolved start offset of the run into the enter-time code.
  • end (int) — The resolved end offset (exclusive).
  • text (str) — The deleted source — code[start:end] of the enter-time code.
__init__(start: int, end: int, text: str) -> None

One name an AddToNamespace bound into the namespace before this execution.

Attributes

  • name (str) — The bound name.
  • value (object) — The bound object, verbatim.
__init__(name: str, value: object) -> None

One name a DropFromNamespace unbound from the namespace before this execution.

Attributes

  • name (str) — The dropped name.
  • value (object | UnsetType) — The object that was unbound, or UNSET when nothing was — the name was absent (an allow_missing drop) or the REPL cannot report values (see BaseREPL.get_namespace).
__init__(name: str, value: object | UnsetType) -> None

Bases: Event

Fired when an execution’s raw result exists — the transform boundary.

Fires with the result the producer made: the value repl.exec returned, or the result a SupplyExecResult supplied at REPLExecSend (a supplied result is a result; only aborts divert). It does not fire when the span unwinds on an in-flight exception (no raw result exists — transformers never run during unwind).

Allowed effects:

Attributes

  • iteration (int) — The agent-loop iteration this execution belongs to.
  • exec_result (ExecResult) — The raw result the producer made — a Continue, Return, or Raise — before any transform composes.
__init__(iteration: int, exec_result: ExecResult, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None

Bases: Event

Fired when the execution span closes, with the turn’s final outcome.

Fires on the turns REPLExecEnter did. outcome is the tagged union REPLExecOutcome: Completed carries the turn’s final, post-transform result (outcome.result — any ModifyExecResult composed at REPLExecComplete already applied); Aborted means a hook’s Abort at one of this execution’s control stages ended the invoke (outcome.exception carries the abort’s error, which propagates after the event fires); Failed carries every other error that escaped before a result existed (outcome.exception; it still propagates after the event fires).

Allowed effects — narrow: a hook may return Abort (and only Abort), on every arm. On the Completed arm this stops the run on the basis of the final, post-transform result (the thing REPLExecComplete can’t see, since a ModifyExecResult there composes after every Complete hook has run). On the Aborted / Failed arms a terminating exception is already unwinding, so an abort here cannot replace it: it is folded into it via an ExceptionGroup (the in-flight exception stays present, so is_fatal still governs how far the combined error travels). Any effect other than Abort raises InvalidEffectError on the Completed arm and is dropped with an error log on the abnormal arms (a loud raise there would replace the exception that must win). To transform a result rather than abort on it, use ModifyExecResult at REPLExecComplete.

Timing: like every event, this exit carries only timestamp (its emission time); the span’s duration is Exit.timestamp - Enter.timestamp.

Attributes

  • iteration (int) — The agent-loop iteration this execution belongs to.
  • outcome (REPLExecOutcome) — How the span ended, with its payload — match on the variant (Completed[ExecResult] | Aborted | Failed).
__init__(iteration: int, outcome: REPLExecOutcome, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None

Bases: Event

Fired once per turn, before making an LLM API call.

Fires on every turn — it is the always-present per-turn boundary, unlike the conditional REPL execution events (skipped when the response fails to parse). That makes it the home of per-turn loop and budget control.

Allowed effects:

  • Abort — abort the invoke; this is where the iteration and budget hard-stops fire.
  • AddMessages — add a message to the prompt for this query.
  • DropMessages — remove messages from the prompt for this query.

Suppliers do not compose here: SupplyLLMResponse is a LLMQuerySend effect — a supplier decides on the basis of the message list, and the list it must see is the committed post-edit one, which at this event composition may still rewrite.

Attributes

  • messages (Sequence[dict[str, Any]]) — The message buffer as it stands before this query’s edits are folded in.
  • iteration (int) — The agent-loop iteration this query belongs to.
__init__(messages: Sequence[dict[str, Any]], iteration: int, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None

Bases: Event

Fired when a query’s input has committed — the post-edit message list is final.

Fires after LLMQueryEnter’s edits have composed, once per query, on every path where the input commits: before a live provider call, and equally when a SupplyLLMResponse (e.g. TrajectoryReplay) answers here and skips the call — the commitment of the input is real on both. It does not fire when the query is aborted at LLMQueryEnter (the input never commits).

Allowed effects:

  • SupplyLLMResponse — supply a response, overriding the default producer (the provider call); the query still completes normally with it.
  • Abort — abort the invoke, declining the committed input.

Attributes

  • messages (Sequence[dict[str, Any]]) — The committed message list — the post-edit buffer view, the same shape as LLMQueryEnter.messages (provenance stamps intact). This turn’s own AddMessages additions carry no stamp yet — a persistent one is stamped after the query — so only the buffer’s messages have a stable id here. The provider receives its wire projection, so a hook that forwards event.messages to a provider itself must project them with jaz._provenance.to_wire_messages first. The dicts are the buffer’s own: rewriting one in place here changes the conversation for every later turn, exactly as at LLMQueryEnter.
  • iteration (int) — The agent-loop iteration this query belongs to.
  • message_edits (ResolvedMessageEdits) — The enter-time edits that produced messages, as self-contained records (dropped message content + persistence; added messages + resolved position).
__init__(messages: Sequence[dict[str, Any]], iteration: int, message_edits: ResolvedMessageEdits = ResolvedMessageEdits(), *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None

Bases: Event

Fired when the query’s raw response exists — the response control boundary.

Fires once per completed query, with the response the producer made: the provider’s return, or the response a SupplyLLMResponse supplied at LLMQuerySend. It does not fire when the query was aborted before a response existed, or when the call raised (no raw response — only LLMQueryExit fires then, with the failure).

This is the earliest point a hook can decide “this run must not continue” on the basis of what came back — an unpriceable cost, a policy-violating completion, a provider degradation. The query itself is already finished and is never un-done: an abort here stops the turn after the response, before the agent acts on it, so the code the model just proposed is never executed.

Allowed effects:

  • ModifyLLMResponse — transform the response (content and/or token/cost fields) the agent then acts on. The transform is authoritative: the modified response is what the agent parses into its next turn and what LLMQueryExit observers + cost accounting see.
  • Abort — abort the invoke on the basis of the response.

Attributes

  • response (LLMResponse) — The raw LLMResponse the producer returned (pre-transform) — content, token counts, and cost. A ModifyLLMResponse composed here transforms it; the post-transform response is what LLMQueryExit carries.
  • iteration (int) — The agent-loop iteration this query belongs to.
__init__(response: LLMResponse, iteration: int, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None

Bases: Event

Fired when the LLM-query span closes, with the query’s outcome.

outcome is the tagged union LLMQueryOutcome: Completed carries the LLMResponse the query produced (outcome.result) — including a response supplied by SupplyLLMResponse (no call is made, but the query completes normally); Aborted means a hook’s Abort at one of this query’s control stages ended the invoke (outcome.exception carries the abort’s error, which propagates after the event fires); Failed carries the exception the call (or the span’s own machinery) raised (outcome.exception; it still propagates after the event fires). The event fires on every path once the query span opened — an aborted query closes Aborted, it no longer skips the exit.

Allowed effects — narrow: a hook may return Abort (and only Abort), on every arm. On the Completed arm this stops the run on the basis of the final, post-transform response — the thing LLMQueryComplete can’t see, since a ModifyLLMResponse there composes after every Complete hook has run — firing before the agent acts on the response. On the Aborted / Failed arms a terminating exception is already unwinding, so an abort here cannot replace it: it is folded into it via an ExceptionGroup (the in-flight exception stays present, so is_fatal still governs how far the combined error travels). Any effect other than Abort raises InvalidEffectError on the Completed arm and is dropped with an error log on the abnormal arms (a loud raise there would replace the exception that must win). To transform the response (rather than abort on it), use ModifyLLMResponse at LLMQueryComplete.

Timing: like every event, this exit carries only timestamp (its emission time); a span’s duration is Exit.timestamp - Enter.timestamp.

Attributes

  • outcome (LLMQueryOutcome) — How the span ended, with its payload — match on the variant (Completed[LLMResponse] | Aborted | Failed).
  • iteration (int) — The agent-loop iteration this query belongs to.
__init__(outcome: LLMQueryOutcome, iteration: int, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None

This query’s composed message edits as self-contained, pre-resolved records.

drops records DropMessages, adds records AddMessages — each sequence named by the verb of the effect it records.

Ordering: drops by resolved position (one record per position, so that is a total order); adds in application order — by resolved slot, and within one slot as the fold applied them (persistent adds first, then transient, each in hook order).

__init__(drops: Sequence[MessageDropRecord] = (), adds: Sequence[MessageAddRecord] = ()) -> None

One message dropped from this query’s committed input.

Attributes

  • message (dict[str, Any]) — The dropped message itself (with its provenance stamp, so its stable per-message id is readable via jaz._provenance.provenance_of).
  • position (int) — The resolved slot the message occupied in the enter-time snapshot when it was dropped – the drop’s input coordinate, mirroring MessageAddRecord.position. A live buffer index, so it drifts across turns; the message’s id and iteration (via its provenance) are the stable identity.
  • persistent (bool) — Whether the drop also removed the message from the carried-forward buffer (True) or applied to this query’s view only (False).
__init__(message: dict[str, Any], position: int, persistent: bool) -> None

One AddMessages edit folded into this query’s committed input.

Attributes

  • messages (Sequence[dict[str, Any]]) — The inserted messages.
  • position (int) — The resolved slot in the enter-time snapshot the messages were inserted before (len(snapshot) for an append).
  • persistent (bool) — Whether the add also survives into later turns’ buffers.
__init__(messages: Sequence[dict[str, Any]], position: int, persistent: bool) -> None

Bases: Event

Fired when Agent.invoke is called, before any execution begins.

Fires once per invoke, not per turn — one of these opens every invoke, including each nested sub-invoke, before the first LLM query.

Allowed effects:

  • Abort — abort the invoke before its first turn.
  • AddInputs — add an input, visible in the prompt and bound in the REPL.
  • DropInputs — remove an input from both the prompt and the REPL.
  • DisableRecursion — withhold the recursive invoke tool from this invoke.
  • WithholdREPLHistory — withhold __history__ from this invoke.

Attributes

  • parent_invoke_id (str | None) — The enclosing invoke’s id, or None at the top level.
  • parent_repl_iteration (int | None) — The enclosing invoke’s iteration that spawned this one, or None at the top level.
  • inputs (Mapping[str, object]) — The explicit **inputs passed to jaz.invoke, as a read-only mapping. Disjoint from the ambient scope every event carries.
__init__(parent_invoke_id: str | None, parent_repl_iteration: int | None, inputs: Mapping[str, object], *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None

Bases: Event

Fired when an invoke’s input set has committed — post AddInputs / DropInputs.

Fires once per invoke, after InvokeEnter’s input effects have been folded into the inputs the prompt renders and the REPL binds, before the first turn. It does not fire when a hook aborts the invoke at InvokeEnter (the input never commits).

Allowed effects:

Attributes

  • inputs (Mapping[str, object]) — The invoke’s committed explicit inputs (post add/drop), as a read-only mapping — the counterpart of InvokeEnter’s pre-commit inputs.
  • input_edits (ResolvedInputEdits) — The enter-time edits that produced inputs from InvokeEnter.inputs, as self-contained records (see ResolvedInputEdits).
  • recursion_disabled (bool) — Whether a hook emitted DisableRecursion — the invoke then binds no recursive subinvoke tool. The one enter-time edit that applies to no field of this event (subinvoke is not an input), so it rides the event itself rather than input_edits; its result shows one span later as the absence of invoke from namespace["__builtins__"] in REPLExecEnter.namespace.
  • repl_history_withheld (bool) — Whether a hook emitted WithholdREPLHistory — the invoke then binds no __history__ and its prompt does not describe one. Recorded here for the same reason as recursion_disabled.
__init__(inputs: Mapping[str, object], input_edits: ResolvedInputEdits = ResolvedInputEdits(), recursion_disabled: bool = False, repl_history_withheld: bool = False, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None

This invoke’s enter-time input edits as self-contained records.

adds records AddInputs, drops records DropInputs — each sequence named by the verb of the effect it records, the rule every <thing>_edits field follows. A record carries what the edit did, including what it removed: a drop record’s value is read off InvokeEnter.inputs, the proposal the drop applied to.

Ordering: both sequences sorted by name — a record’s coordinate, the rule every <thing>_edits sequence follows.

__init__(adds: Sequence[InputAddRecord] = (), drops: Sequence[InputDropRecord] = ()) -> None

One name an AddInputs added to this invoke’s inputs.

Attributes

  • name (str) — The added input’s name.
  • value (object) — The bound object, verbatim.
__init__(name: str, value: object) -> None

One name a DropInputs un-passed from this invoke’s inputs.

Attributes

  • name (str) — The dropped name.
  • value (object | UnsetType) — The object that was un-passed, or UNSET when nothing was — the name was absent (an allow_missing drop).
__init__(name: str, value: object | UnsetType) -> None

Bases: Event

Fired when the invoke’s raw terminal result exists — the transform boundary.

Fires once per invoke, with the terminal result the loop produced. It does not fire when the invoke unwinds on an in-flight exception before a terminal result exists (transformers never run during unwind), nor when a hook’s Abort ended the invoke at an earlier stage (an abort skips the pipeline’s remaining stages — its stickiness is structural).

Allowed effects:

Attributes

  • result (TerminalExecResult) — The invoke’s raw terminal result — a Return or a Raise — before any transform composes.
__init__(result: TerminalExecResult, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None

Bases: Event

Fired when the invoke span closes, with the invoke’s final outcome.

Fires once per invoke, not per turn. outcome is the tagged union InvokeOutcome: Completed carries the invoke’s final, post-transform terminal result (outcome.result — any ModifyInvokeResult composed at InvokeComplete already applied), exactly what the invoke returns or raises to its caller. Aborted means this invoke’s own hook control plane ended it via Abort — at whichever stage the effect composed (outcome.exception carries the abort’s error, which the invoke raises to its caller). Failed carries every other error that escaped before the invoke produced a result — a REPL that fails to initialize, a FatalError propagating from below, a child invoke’s abort passing through; the error still propagates after the event fires.

Observation-only: no effect other than BlackboardWrite is valid here — the outcome is already final (any other effect returned here raises InvalidEffectError on the Completed arm and is dropped with an error log on the abnormal arms, where the in-flight exception wins). To change the terminal result, transform it at InvokeComplete. (Unlike the per-turn *Exit events — LLMQueryExit / REPLExecExit, which accept an Abort on every arm — InvokeExit stays fully observation-only: an invoke aborting at its own terminal Exit would make this event’s Completed payload diverge from the exception the caller then receives, with no enclosing span to record the abort, and InvokeComplete already gives full control over the final result.)

Timing: like every event, this exit carries only timestamp (its emission time); the span’s duration is Exit.timestamp - Enter.timestamp.

Attributes

  • outcome (InvokeOutcome) — How the span ended, with its payload — match on the variant (Completed[Return | Raise] | Aborted | Failed).
__init__(outcome: InvokeOutcome, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None

Bases: Event

Fired when an LLM call fails and is about to be retried.

Not a per-turn event. It fires once per retry attempt, so a turn whose first attempt succeeds never fires it, and a turn that retries three times fires it three times.

This event is purely observational: no effect other than BlackboardWrite is valid here.

Attributes

  • attempt_number (int) — Which attempt just failed, counting from 1.
  • exception (Exception) — The error that caused the retry.
  • wait_seconds (float) — How long the retry will wait before the next attempt.
  • iteration (int) — The agent-loop iteration the call belongs to.
__init__(attempt_number: int, exception: Exception, wait_seconds: float, iteration: int, *, config: Config, blackboard: Mapping[str, object] = MappingProxyType({}), scope: Mapping[str, object] = MappingProxyType({}), invoke_id: str, depth: int, hooks: tuple[Hook, ...] = tuple(), timestamp: datetime = (lambda: datetime.now(UTC))()) -> None