Hooks reference
Hooks observe execution via events and influence it by returning effects. Subclass Hook,
override the handler for the events you care about, and return a list of effects — returning
effects is the only way a hook influences a run. Every event has a handler named after it
(LLMQueryEnter → on_llm_query_enter); a hook that treats every event alike overrides on_any
instead, which runs in addition to the matched handler.
For an introduction see the Hooks guide. This page is the orientation —
per-symbol detail (fields, composition rules, firing conditions) lives in the generated
jaz.hooks, jaz.hooks.events
and jaz.hooks.effects pages.
from jaz import invokefrom jaz.hooks import Hookfrom jaz.hooks.effects import Abort, Effectfrom jaz.hooks.events import LLMQueryEnter
class StopAfterTenTurns(Hook): def on_llm_query_enter(self, event: LLMQueryEnter) -> list[Effect]: if event.iteration > 10: return [Abort(error=RuntimeError("too many turns"))] return []
with StopAfterTenTurns(): result = invoke(task="...")Activating a hook with with propagates it to nested invokes, to functions called inside the
block, across async code, and into threads. For a list of hooks known only at runtime, use
contextlib.ExitStack.
Events
Section titled “Events”Importable from jaz.hooks.events. Event is the base class. Events fire around three
spans — the whole Invoke, each turn’s LLMQuery, and each turn’s REPLExec — and
every span walks the same four stages (InvokeEnter, LLMQuerySend, REPLExecComplete, …):
| Stage | Observes | Accepts | Fires |
|---|---|---|---|
*Enter |
the proposal | edit effects + Abort |
always |
*Send |
the committed input | supply effects + Abort |
iff the input committed |
*Complete |
the raw result | modify effects + Abort |
iff a raw result exists |
*Exit |
the outcome union (Completed | Aborted | Failed) |
Abort at the per-turn LLMQueryExit / REPLExecExit; InvokeExit observation-only |
whenever the span opened |
Plus LLMQueryRetry, fired once per retry attempt of an LLM call — zero times when the first
attempt succeeds. Every event carries contextual data (e.g. LLMQueryEnter.iteration) and a
timestamp.
Effects
Section titled “Effects”Importable from jaz.hooks.effects. Effect is the base class.
| Effect | Valid at | Influence |
|---|---|---|
Abort |
every Enter / Send / Complete |
Terminate the invoke, surfacing the error out of invoke() |
AddInputs / DropInputs |
InvokeEnter |
Add or un-pass invoke inputs — both the prompt and the REPL binding |
DisableRecursion |
InvokeEnter |
Withhold the recursive invoke tool from this invoke |
AddMessages / DropMessages |
LLMQueryEnter |
Insert or drop messages for this query, transiently or persistently |
AddToNamespace / DropFromNamespace |
REPLExecEnter |
Bind or unbind REPL namespace names, without touching the prompt |
InsertCode / DeleteCode |
REPLExecEnter |
Edit the proposed REPL code by character offset — the code-string twins of AddMessages / DropMessages |
SupplyLLMResponse |
LLMQuerySend |
Supply a pre-computed response, skipping the API call |
ModifyLLMResponse |
LLMQueryComplete |
Transform the LLM response the agent then acts on |
SupplyExecResult |
REPLExecSend |
Supply a result in place of running the turn’s code |
ModifyExecResult |
REPLExecComplete |
Transform a raw REPL result that already exists |
SupplyInvokeResult |
InvokeSend |
Supply the invoke’s terminal result (Return / Raise), skipping the whole agent loop |
ModifyInvokeResult |
InvokeComplete |
Transform the invoke’s terminal result (Return / Raise) |
BlackboardWrite |
every event (including Exit) |
Write to the cross-hook blackboard |
InvokeExit and LLMQueryRetry are observation-only. The per-turn LLMQueryExit /
REPLExecExit additionally accept Abort (on every arm — normal, abort, or unwind); and
BlackboardWrite is valid at every event, including the *Exit stages. An effect returned
at an event that does not accept it raises InvalidEffectError rather than silently
no-op’ing.
Ready-made hooks
Section titled “Ready-made hooks”Importable from jaz.hooks.
| Hook | Purpose |
|---|---|
BudgetPool |
Track LLM cost/calls across an invoke forest and hard-stop at the budget |
IterationLimit |
Hard-stop at a per-level REPL iteration limit |
RecursionLimit |
Cap nested invoke recursion at a given depth |
ContextWindowWarning |
Warn the agent as its prompt approaches the model’s context window |
BudgetForcing |
Refuse an attempted finish (return/raise) a given number of times |
PrintLogger / FileLogger |
Log every event to the terminal or a file |
TrajectoryRecorder / TrajectoryReplay |
Record a run to the ATIF trace format, and replay one |
RolloutRecorder |
Record token-native rollouts of a run |
Governance hooks are opt-in and activated via the propagating channel —
with IterationLimit(max_iterations=50): invoke(...).
Invoke directives
Section titled “Invoke directives”Passed positionally to invoke, where they apply to that call only:
| Directive | Purpose |
|---|---|
ReturnType |
Declare the return type — narrows it statically and enforces it at runtime |
ValidateReturn |
Validate the returned value, rejecting it as recoverable feedback |
ValidateREPLCode |
Validate the proposed REPL code before execution, rejecting it as recoverable feedback |
x: int = invoke(ReturnType(int), task="...")