Skip to content

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 invoke
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:
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.

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.

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.

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(...).

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="...")