Skip to main content

rig_agent/agent/
hook.rs

1//! Event-specific hooks for observing and steering an agent run.
2//!
3//! [`AgentHook`] supplies typed lifecycle actions; [`HookStack`] composes them in
4//! registration order. Blocking and streaming runs share lifecycle decisions;
5//! streamed deltas remain provisional until the model turn is accepted.
6//!
7//! ```
8//! use rig_agent::agent::{AgentHook, HookContext, OutcomeAction, OutcomeEvent};
9//!
10//! struct ResponseLogger;
11//!
12//! impl AgentHook for ResponseLogger {
13//!     async fn on_outcome(&self, _ctx: &HookContext, event: OutcomeEvent<'_>) -> OutcomeAction {
14//!         if let Some(response) = event.completion() {
15//!             println!(
16//!                 "response {:?}: {:?} ({:?})",
17//!                 response.response_id(),
18//!                 response.choice,
19//!                 response.usage
20//!             );
21//!         }
22//!         OutcomeAction::proceed()
23//!     }
24//! }
25//! ```
26
27use rig_core::conversation::{Aside, Author};
28use rig_core::message::CallId;
29use rig_core::streaming::Part;
30use std::sync::atomic::{AtomicUsize, Ordering};
31use std::{
32    any::{Any, TypeId},
33    collections::HashMap,
34    future::Future,
35    sync::Arc,
36};
37
38use rig_core::{
39    completion::FinishReason,
40    message::{AssistantContent, Message},
41    wasm_compat::{WasmBoxedFuture, WasmCompatSend, WasmCompatSync},
42};
43
44use rig_core::{
45    completion::ModelRef,
46    effect::{Answered, EffectFamily, EffectId, EffectKind},
47    error::{ErrorKind, ErrorReport},
48};
49
50use crate::{
51    completion::{ResponseIdentity, Usage},
52    handlers::{Handle, Handlers, IndexHandle, ModelHandle, ToolHandle},
53    tool::{ToolContext, ToolOutput, ToolResult},
54};
55
56pub use rig_core::id::RunId;
57
58/// Run-scoped typed storage shared by hooks. Clones share in-process state;
59/// entries are neither serialized nor rewound when a run is forked.
60/// Use [`HookContext::append_entry`] for state that must travel with the run.
61#[derive(Clone, Default)]
62pub struct Scratchpad {
63    inner: Arc<std::sync::Mutex<HashMap<TypeId, Box<dyn Entry>>>>,
64}
65
66/// A scratchpad value: any type, thread-safe where the target has threads.
67trait Entry: Any + WasmCompatSend + WasmCompatSync {}
68
69impl<T: Any + WasmCompatSend + WasmCompatSync> Entry for T {}
70
71fn take<T: 'static>(entry: Box<dyn Entry>) -> Option<T> {
72    (entry as Box<dyn Any>).downcast().ok().map(|value| *value)
73}
74
75impl Scratchpad {
76    fn lock(&self) -> std::sync::MutexGuard<'_, HashMap<TypeId, Box<dyn Entry>>> {
77        self.inner
78            .lock()
79            .unwrap_or_else(std::sync::PoisonError::into_inner)
80    }
81
82    /// Insert a value.
83    pub fn insert<T>(&self, value: T) -> Option<T>
84    where
85        T: Clone + WasmCompatSend + WasmCompatSync + 'static,
86    {
87        self.lock()
88            .insert(TypeId::of::<T>(), Box::new(value))
89            .and_then(take)
90    }
91
92    /// Get a cloned value.
93    pub fn get<T>(&self) -> Option<T>
94    where
95        T: Clone + WasmCompatSend + WasmCompatSync + 'static,
96    {
97        let entries = self.lock();
98        let entry = entries.get(&TypeId::of::<T>())?;
99        (&**entry as &dyn Any).downcast_ref::<T>().cloned()
100    }
101
102    /// Whether a type is present.
103    pub fn contains<T>(&self) -> bool
104    where
105        T: WasmCompatSend + WasmCompatSync + 'static,
106    {
107        self.lock().contains_key(&TypeId::of::<T>())
108    }
109
110    /// Remove a value.
111    pub fn remove<T>(&self) -> Option<T>
112    where
113        T: Clone + WasmCompatSend + WasmCompatSync + 'static,
114    {
115        self.lock().remove(&TypeId::of::<T>()).and_then(take)
116    }
117
118    /// Remove a value or create its default, update it outside the lock, then
119    /// insert it and return the closure's result. Reentrant access is allowed;
120    /// concurrent updates of the same type are last-writer-wins, not serialized.
121    pub fn update<T, R>(&self, update: impl FnOnce(&mut T) -> R) -> R
122    where
123        T: Clone + Default + WasmCompatSend + WasmCompatSync + 'static,
124    {
125        let mut value = self.remove::<T>().unwrap_or_default();
126        let result = update(&mut value);
127        self.insert(value);
128        result
129    }
130}
131
132impl std::fmt::Debug for Scratchpad {
133    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
134        f.debug_struct("Scratchpad")
135            .field("entries", &self.lock().len())
136            .finish()
137    }
138}
139
140/// Run-scoped context supplied to hooks.
141#[derive(Debug)]
142pub struct HookContext {
143    /// The handlers the run dispatches through.
144    handlers: Handlers,
145    run_id: RunId,
146    turn: AtomicUsize,
147    is_streaming: bool,
148    agent_name: Option<String>,
149    scratchpad: Scratchpad,
150    /// A patch a stack accumulated before one of its hooks denied the
151    /// dispatch, keyed by the effect's id. `DispatchAction::Deny` carries only
152    /// the report, so the engine reads the effective effect (the arguments a
153    /// skipped tool result reports) from here; a nested stack records into
154    /// the same slot, so the salvage survives any nesting depth.
155    salvaged_patches: std::sync::Mutex<HashMap<EffectId, EffectKind>>,
156    /// Seeded and newly appended entries, in append order.
157    entries: std::sync::Mutex<Vec<Aside>>,
158    /// Appends not yet flushed into the [`AgentRun`](crate::agent::AgentRun)
159    /// by the driver.
160    pending_entries: std::sync::Mutex<Vec<Aside>>,
161}
162
163impl HookContext {
164    pub(crate) fn new(is_streaming: bool, agent_name: Option<String>, handlers: Handlers) -> Self {
165        Self {
166            handlers,
167            run_id: RunId::new(),
168            turn: AtomicUsize::new(0),
169            is_streaming,
170            agent_name,
171            scratchpad: Scratchpad::default(),
172            salvaged_patches: std::sync::Mutex::new(HashMap::new()),
173            entries: std::sync::Mutex::new(Vec::new()),
174            pending_entries: std::sync::Mutex::new(Vec::new()),
175        }
176    }
177
178    /// Record the patch a stack had accumulated when one of its hooks denied
179    /// the dispatch `id`. The innermost stack records first and wins: an
180    /// enclosing stack's earlier patch was already threaded into what the
181    /// inner stack saw, so the inner accumulation is the last rewrite before
182    /// the terminal action.
183    fn salvage_patch(&self, id: EffectId, kind: EffectKind) {
184        self.salvaged_patches
185            .lock()
186            .unwrap_or_else(std::sync::PoisonError::into_inner)
187            .entry(id)
188            .or_insert(kind);
189    }
190
191    /// The effect as patched before the dispatch `id` was denied, if any.
192    pub(crate) fn take_salvaged_patch(&self, id: EffectId) -> Option<EffectKind> {
193        self.salvaged_patches
194            .lock()
195            .unwrap_or_else(std::sync::PoisonError::into_inner)
196            .remove(&id)
197    }
198
199    /// Seed the entries a resumed run carried; called by the driver at run
200    /// start, before any hook fires.
201    pub(crate) fn seed_entries(&self, entries: &[Aside]) {
202        self.entries
203            .lock()
204            .unwrap_or_else(std::sync::PoisonError::into_inner)
205            .extend_from_slice(entries);
206    }
207
208    /// Drain the appends not yet flushed into the run; called by the driver
209    /// at each step boundary.
210    pub(crate) fn drain_pending_entries(&self) -> Vec<Aside> {
211        std::mem::take(
212            &mut *self
213                .pending_entries
214                .lock()
215                .unwrap_or_else(std::sync::PoisonError::into_inner),
216        )
217    }
218
219    pub(crate) fn set_turn(&self, turn: usize) {
220        self.turn.store(turn, Ordering::Relaxed);
221    }
222
223    /// Bind a typed key in the run's handler table. Fails when the current
224    /// registration has another family. Dispatches are served and recorded
225    /// without re-entering hooks.
226    pub fn bind<F: rig_core::effect::Family>(
227        &self,
228        key: &rig_core::effect::Key<F>,
229    ) -> Result<Handle<F>, ErrorReport> {
230        self.handlers.bind(key)
231    }
232
233    /// Bind the retrieval index under `key`, for a hook that retrieves for
234    /// itself. Fails when `key` serves another family.
235    pub fn index(&self, key: &rig_core::effect::HandlerKey) -> Result<IndexHandle, ErrorReport> {
236        self.handlers.handle(key)
237    }
238
239    /// [`index`](Self::index) for a completion model.
240    pub fn model(&self, key: &rig_core::effect::HandlerKey) -> Result<ModelHandle, ErrorReport> {
241        self.handlers.handle(key)
242    }
243
244    /// [`index`](Self::index) for a tool.
245    pub fn tool(&self, key: &rig_core::effect::HandlerKey) -> Result<ToolHandle, ErrorReport> {
246        self.handlers.handle(key)
247    }
248
249    /// Stable run identifier.
250    pub fn run_id(&self) -> RunId {
251        self.run_id
252    }
253
254    /// Current one-based model-call index.
255    pub fn turn(&self) -> usize {
256        self.turn.load(Ordering::Relaxed)
257    }
258
259    /// Whether the streaming surface is driving this run.
260    pub fn is_streaming(&self) -> bool {
261        self.is_streaming
262    }
263
264    /// Configured agent name.
265    pub fn agent_name(&self) -> Option<&str> {
266        self.agent_name.as_deref()
267    }
268
269    /// Shared run scratchpad.
270    pub fn scratchpad(&self) -> &Scratchpad {
271        &self.scratchpad
272    }
273
274    /// Serialize and append an entry: an [`Aside`] of `kind` by
275    /// [`Author::rig`]. A hook that needs the turn puts it in `value`
276    /// ([`turn`](Self::turn)). Serialization errors leave entries unchanged. The driver transfers pending entries into
277    /// the serializable run at its next step boundary; this is not a disk write.
278    /// Entries appended during `on_run_settled` remain visible locally but are not
279    /// transferred into the finished run.
280    pub fn append_entry<T: serde::Serialize>(
281        &self,
282        kind: impl Into<String>,
283        value: &T,
284    ) -> Result<(), serde_json::Error> {
285        let entry = Aside::new(kind, Author::rig(), serde_json::to_value(value)?);
286        self.entries
287            .lock()
288            .unwrap_or_else(std::sync::PoisonError::into_inner)
289            .push(entry.clone());
290        self.pending_entries
291            .lock()
292            .unwrap_or_else(std::sync::PoisonError::into_inner)
293            .push(entry);
294        Ok(())
295    }
296
297    /// Clone all entries of `kind`, including resumed entries and new appends,
298    /// in append order. Reading does not consume entries.
299    pub fn entries(&self, kind: &str) -> Vec<Aside> {
300        self.entries
301            .lock()
302            .unwrap_or_else(std::sync::PoisonError::into_inner)
303            .iter()
304            .filter(|entry| entry.kind == kind)
305            .cloned()
306            .collect()
307    }
308
309    /// Clone the most recent entry of `kind`, if present.
310    pub fn last_entry(&self, kind: &str) -> Option<Aside> {
311        self.entries
312            .lock()
313            .unwrap_or_else(std::sync::PoisonError::into_inner)
314            .iter()
315            .rev()
316            .find(|entry| entry.kind == kind)
317            .cloned()
318    }
319}
320
321pub use crate::run::policy::{
322    InvalidToolCallAction, InvalidToolCallContext, InvalidToolCallReason, RetryRequest,
323};
324
325/// Completion-call event.
326///
327/// Per `CallModel` step, hook resolution is ordered: completion-call hooks run
328/// **first** and their [`RequestPatch`]es merge in registration order. Only
329/// when every completion-call hook proceeds does [`ModelSelection`] run
330/// (receiving the merged patch), after which request preparation inspects the
331/// selected model's captured
332/// [`ProviderCapabilities`](crate::completion::ProviderCapabilities) and the
333/// attempt is issued. A completion-call stop therefore suppresses model
334/// selection entirely and does not advance
335/// [`ModelSelection::previous_model`].
336#[derive(Clone, Copy)]
337pub struct CompletionCallEvent<'a> {
338    /// Prompt for this turn.
339    pub prompt: &'a Message,
340    /// History preceding the prompt.
341    pub history: &'a [Arc<Message>],
342    /// One-based model-call index.
343    pub turn: usize,
344}
345
346/// Model-selection event after completion-call hooks proceed and before request
347/// preparation inspects the selected model's capabilities. The runner default is
348/// the initial candidate on every attempt, including retries; earlier selections
349/// in a stack update the candidate seen by later hooks.
350///
351/// Selection must be synchronous and non-blocking. Prepared attempts retain their
352/// chosen handle. `previous_model` advances only when an operation is invoked,
353/// including operations that fail, not on hook stops or preparation errors.
354#[derive(Clone, Copy)]
355pub struct ModelSelection<'a> {
356    /// Prompt for the pending model call.
357    pub prompt: &'a Message,
358    /// Canonical history visible to the pending model call.
359    pub history: &'a [Arc<Message>],
360    /// Merged per-turn request patch from this step's completion-call hooks
361    /// (in hook registration order), when any hook patched the request.
362    pub request_patch: Option<&'a RequestPatch>,
363    /// Model that executed the preceding issued attempt in this run, if any.
364    pub previous_model: Option<&'a ModelRef>,
365    /// Runner default used as the initial candidate for this call.
366    pub default_model: &'a ModelRef,
367    /// Candidate after all earlier model-selection hooks.
368    pub selected_model: &'a ModelRef,
369}
370
371impl<'a> ModelSelection<'a> {
372    /// Construct a model-selection event from borrowed request and candidate state.
373    pub fn new(
374        prompt: &'a Message,
375        history: &'a [Arc<Message>],
376        request_patch: Option<&'a RequestPatch>,
377        previous_model: Option<&'a ModelRef>,
378        default_model: &'a ModelRef,
379        selected_model: &'a ModelRef,
380    ) -> Self {
381        Self {
382            prompt,
383            history,
384            request_patch,
385            previous_model,
386            default_model,
387            selected_model,
388        }
389    }
390}
391
392/// Medium-neutral accepted model-turn event.
393///
394/// The turn is canonicalized and parked in the run state, but has not yet been
395/// advanced into tool execution or finalization. A hook may therefore reject a
396/// tool-free turn with [`ModelTurnAction::Retry`].
397#[derive(Clone, Copy)]
398pub struct ModelTurnFinished<'a> {
399    /// One-based model-call index.
400    pub turn: usize,
401    /// Canonical assistant content parked for hook acceptance.
402    pub content: &'a Vec<AssistantContent>,
403    /// Usage reported for the turn.
404    pub usage: Usage,
405    /// This exact attempt's response identity metadata, the same value the
406    /// preceding completion outcome ([`OutcomeEvent`]) carried. On a retry, this is
407    /// the retried attempt's own identity, never a previous attempt's.
408    pub identity: &'a ResponseIdentity,
409    /// This attempt's normalized terminal reason, or `None` when unreported.
410    /// Unknown reasons retain their spelling in [`FinishReason::Other`].
411    /// A reported `Stop` is reconciled to `ToolCalls` when calls are present.
412    pub finish_reason: Option<&'a FinishReason>,
413    /// This attempt's output-token cap after agent configuration, request
414    /// overrides, and completion-call patches. `None` leaves the cap to the provider.
415    pub max_tokens: Option<u64>,
416    /// This attempt's decoded provider response, serialized as JSON on both
417    /// streaming and unary surfaces. Hand-constructed responses may use `Null`.
418    pub raw: &'a serde_json::Value,
419}
420
421/// Action for the medium-neutral [`ModelTurnFinished`] event.
422///
423/// Every retry consumes the run's existing total model-call budget. Rig does
424/// not impose a separate response-retry limit; hooks that need one should keep
425/// run-scoped state in [`HookContext::scratchpad`]. Retrying a turn containing
426/// tool calls is rejected so provider-visible history never contains unanswered
427/// calls. Use tool-call hooks to steer those turns instead.
428#[derive(Debug, Clone, PartialEq, Eq)]
429pub enum ModelTurnAction {
430    /// Accept the turn and continue the run.
431    Continue,
432    /// Reject the turn and request another model call.
433    Retry(RetryRequest),
434    /// Stop the run with a reason.
435    Stop(String),
436}
437
438impl ModelTurnAction {
439    /// Accepts the completed model turn.
440    pub fn continue_run() -> Self {
441        Self::Continue
442    }
443
444    /// Discards the response and reuses the same prompt and preceding history
445    /// with fresh request preparation.
446    pub fn repeat() -> Self {
447        Self::Retry(RetryRequest::Repeat)
448    }
449
450    /// Preserves the response, appends corrective feedback, and retries.
451    pub fn retry_with_feedback(feedback: impl Into<String>) -> Self {
452        Self::Retry(RetryRequest::Feedback(feedback.into()))
453    }
454
455    /// Stops the run with the supplied reason.
456    pub fn stop(reason: impl Into<String>) -> Self {
457        Self::Stop(reason.into())
458    }
459}
460
461/// Streaming text delta.
462#[derive(Clone, Copy)]
463pub struct TextDelta<'a> {
464    /// Newly received text.
465    pub delta: &'a str,
466    /// Text accumulated for the turn.
467    pub aggregated: &'a str,
468}
469
470/// Streaming reasoning delta.
471#[derive(Clone, Copy)]
472pub struct ReasoningDelta<'a> {
473    /// The reasoning part: stable across its deltas and its end.
474    pub part: Part,
475    /// Newly received reasoning fragment.
476    pub delta: &'a str,
477    /// Reasoning text accumulated for this reasoning part through this delta.
478    pub aggregated: &'a str,
479}
480
481/// Streaming tool-call argument delta. Fires per fragment as the provider
482/// streams a call to an allowed tool; the call's id and final arguments
483/// arrive with its end, and nothing executes before it.
484#[derive(Clone, Copy)]
485pub struct ToolCallDelta<'a> {
486    /// The call's part: stable across its deltas and its end.
487    pub part: Part,
488    /// The tool the call names.
489    pub tool_name: &'a str,
490    /// The newly received fragment of argument JSON.
491    pub delta: &'a str,
492    /// The call's argument JSON accumulated through this delta. Read it with
493    /// [`parse_partial_arguments`](rig_core::streaming::parse_partial_arguments).
494    pub aggregated: &'a str,
495}
496
497/// Initial prompt event before the first completion-call hook. In a [`HookStack`],
498/// rewrites reach later hooks in registration order; the first stop prevents
499/// remaining hooks and provider calls.
500#[derive(Clone, Copy)]
501pub struct RunStart<'a> {
502    /// The prompt the run will send on its first model call, including
503    /// earlier hooks' rewrites.
504    pub prompt: &'a Message,
505    /// The input chat history preceding the prompt.
506    pub history: &'a [Arc<Message>],
507}
508
509/// Action for the pre-run [`RunStart`] event.
510#[derive(Debug, Clone, PartialEq)]
511pub enum RunStartAction {
512    /// Start the run with the current prompt.
513    Continue,
514    /// Replace the prompt and pass it to later hooks.
515    Rewrite(Message),
516    /// Stop the run before any model call, with a reason.
517    Stop(String),
518}
519
520impl RunStartAction {
521    /// Starts the run with the current prompt.
522    pub fn continue_run() -> Self {
523        Self::Continue
524    }
525
526    /// Replaces the prompt; later hooks in a [`HookStack`] see the rewrite.
527    pub fn rewrite(prompt: impl Into<Message>) -> Self {
528        Self::Rewrite(prompt.into())
529    }
530
531    /// Stops the run before any provider call.
532    pub fn stop(reason: impl Into<String>) -> Self {
533        Self::Stop(reason.into())
534    }
535}
536
537/// Terminal run event carrying a final response or error. No retry, model call,
538/// or tool execution follows automatically.
539#[derive(Clone, Copy)]
540pub struct RunSettled<'a> {
541    /// How the run ended.
542    pub outcome: SettledOutcome<'a>,
543    /// Messages actually committed by this run, including its prompt and
544    /// excluding input history. Available on error as well as success;
545    /// rejected or truncated answerless turns are not committed.
546    /// `None` means the run failed before its state was constructed.
547    pub messages: Option<&'a [Arc<Message>]>,
548}
549
550/// The outcome carried by [`RunSettled`].
551#[derive(Clone, Copy)]
552pub enum SettledOutcome<'a> {
553    /// The run completed with this final response.
554    Response(&'a crate::run::response::PromptResponse),
555    /// The run terminated with an error, rendered via its `Display` form.
556    Error(&'a str),
557}
558
559/// Hook event kind used only as an observation performance hint.
560#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
561pub enum StepEventKind {
562    /// `on_run_start`.
563    RunStart,
564    /// `on_run_settled`.
565    RunSettled,
566    /// `on_completion_call`.
567    CompletionCall,
568    /// `on_model_turn_finished`.
569    ModelTurnFinished,
570    /// `on_invalid_tool_call`.
571    InvalidToolCall,
572    /// `on_text_delta`.
573    TextDelta,
574    /// `on_reasoning_delta`.
575    ReasoningDelta,
576    /// `on_tool_call_delta`.
577    ToolCallDelta,
578    /// `on_dispatch`/`on_outcome` for a completion effect. Every dispatched
579    /// completion gets one outcome; only an accepted turn's can be replaced.
580    CompletionDispatch,
581    /// `on_dispatch`/`on_outcome` for a tool-call effect.
582    ToolDispatch,
583    /// `on_dispatch`/`on_outcome` for an embedding effect (observe-only by
584    /// default: opt in through `observes`).
585    EmbedDispatch,
586    /// `on_dispatch`/`on_outcome` for a reranking effect (observe-only by
587    /// default).
588    RerankDispatch,
589    /// `on_dispatch`/`on_outcome` for a retrieval effect (observe-only by
590    /// default).
591    RetrieveDispatch,
592    /// `on_dispatch`/`on_outcome` for a custom effect (observe-only by
593    /// default).
594    CustomDispatch,
595}
596
597impl StepEventKind {
598    /// The dispatch-boundary event kind for an effect family.
599    pub const fn for_family(family: EffectFamily) -> Self {
600        match family {
601            EffectFamily::Completion => Self::CompletionDispatch,
602            EffectFamily::Tool => Self::ToolDispatch,
603            EffectFamily::Embed => Self::EmbedDispatch,
604            EffectFamily::Rerank => Self::RerankDispatch,
605            EffectFamily::Retrieve => Self::RetrieveDispatch,
606            EffectFamily::Custom => Self::CustomDispatch,
607        }
608    }
609}
610
611/// An effect about to be dispatched: what `on_dispatch` sees.
612#[derive(Clone, Copy)]
613pub struct DispatchEvent<'a> {
614    /// The dispatch's id, minted before the hook runs so an observation can
615    /// be correlated with its recorded effect.
616    pub id: EffectId,
617    /// The effect, after any earlier hook's patch.
618    pub kind: &'a EffectKind,
619    /// The turn the effect belongs to.
620    pub turn: usize,
621    /// The call the effect answers, for a tool call the model emitted.
622    pub call_id: Option<&'a CallId>,
623    /// Tool invocation context, carried separately from the effect.
624    pub context: Option<&'a ToolContext>,
625}
626
627/// Dispatch-boundary action.
628#[derive(Debug, Clone)]
629pub enum DispatchAction {
630    /// Dispatch as is.
631    Proceed,
632    /// Dispatch this effect instead. A patch must keep the family; the
633    /// stack rejects a family change as an internal error before later hooks
634    /// observe it. Tool calls must also retain their target name; only their
635    /// arguments may be patched.
636    Patch(EffectKind),
637    /// Do not dispatch: the effect resolves failed with this report and
638    /// never reaches a handler. For a tool call a report of kind
639    /// `Cancelled` cancels the run; any other kind becomes the skipped
640    /// result the model sees. For a completion any report fails the turn.
641    Deny(ErrorReport),
642}
643
644/// Validate before a patch becomes visible to policy or execution.
645pub(crate) fn validate_dispatch_patch(
646    current: &EffectKind,
647    next: &EffectKind,
648) -> Result<(), ErrorReport> {
649    if current.family() != next.family() {
650        return Err(ErrorReport::new(
651            ErrorKind::Internal,
652            format!(
653                "a hook patched a {} dispatch into a `{}` effect",
654                current.name(),
655                next.name()
656            ),
657        ));
658    }
659    if let (EffectKind::ToolCall { name: current, .. }, EffectKind::ToolCall { name: next, .. }) =
660        (current, next)
661        && current != next
662    {
663        return Err(ErrorReport::new(
664            ErrorKind::Other,
665            "a dispatch patch cannot change the tool target",
666        ));
667    }
668    Ok(())
669}
670
671impl DispatchAction {
672    /// Dispatch as is.
673    pub fn proceed() -> Self {
674        Self::Proceed
675    }
676
677    /// Dispatch this effect instead.
678    pub fn patch(kind: EffectKind) -> Self {
679        Self::Patch(kind)
680    }
681
682    /// Deny with a report.
683    pub fn deny(report: ErrorReport) -> Self {
684        Self::Deny(report)
685    }
686
687    /// Deny a tool call so the model sees it as skipped with `reason`.
688    pub fn skip(reason: impl Into<String>) -> Self {
689        Self::Deny(ErrorReport::new(ErrorKind::Other, reason))
690    }
691
692    /// Deny and cancel the run with `reason`.
693    pub fn stop(reason: impl Into<String>) -> Self {
694        Self::Deny(ErrorReport::new(ErrorKind::Cancelled, reason))
695    }
696
697    /// Patch a tool call's arguments, keeping its name and context.
698    /// `Proceed` when `kind` is not a tool call.
699    pub fn rewrite_tool_args(kind: &EffectKind, args: impl Into<serde_json::Value>) -> Self {
700        match kind {
701            EffectKind::ToolCall { name, .. } => Self::Patch(EffectKind::ToolCall {
702                name: name.clone(),
703                args: Into::<serde_json::Value>::into(args).to_string(),
704            }),
705            _ => Self::Proceed,
706        }
707    }
708}
709
710impl<'a> DispatchEvent<'a> {
711    /// The tool name, for a tool-call effect.
712    pub fn tool_name(&self) -> Option<&'a str> {
713        match self.kind {
714            EffectKind::ToolCall { name, .. } => Some(name),
715            _ => None,
716        }
717    }
718
719    /// The JSON arguments (after earlier patches), for a tool-call effect.
720    pub fn tool_args(&self) -> Option<&'a str> {
721        match self.kind {
722            EffectKind::ToolCall { args, .. } => Some(args),
723            _ => None,
724        }
725    }
726
727    /// The dispatch context, for a tool-call effect.
728    pub fn tool_context(&self) -> Option<&'a ToolContext> {
729        self.context
730    }
731
732    /// The request about to be sent, for a completion effect.
733    pub fn completion_request(&self) -> Option<&'a rig_core::completion::CompletionRequest> {
734        match self.kind {
735            EffectKind::Completion { request, .. } => Some(request),
736            _ => None,
737        }
738    }
739}
740
741/// An effect's answer: what `on_outcome` sees.
742#[derive(Clone, Copy)]
743pub struct OutcomeEvent<'a> {
744    /// The dispatch's id.
745    pub id: EffectId,
746    /// The effect that was dispatched (after patches).
747    pub kind: &'a EffectKind,
748    /// The answer, after any earlier hook's replacement.
749    pub outcome: &'a Result<Answered, ErrorReport>,
750    /// The turn the effect belongs to.
751    pub turn: usize,
752    /// The call the effect answered, for a tool call the model emitted.
753    pub call_id: Option<&'a CallId>,
754    /// Published tool context, carried separately from the outcome.
755    pub context: Option<&'a ToolContext>,
756}
757
758/// Outcome-boundary action.
759#[derive(Debug, Clone)]
760pub enum OutcomeAction {
761    /// Keep the answer.
762    Proceed,
763    /// Use this answer instead.
764    Replace(Result<Answered, ErrorReport>),
765}
766
767impl OutcomeAction {
768    /// Keep the answer.
769    pub fn proceed() -> Self {
770        Self::Proceed
771    }
772
773    /// Use this answer instead.
774    pub fn replace(outcome: Result<Answered, ErrorReport>) -> Self {
775        Self::Replace(outcome)
776    }
777
778    /// Stop the run with `reason`: a replacement whose error is `Cancelled`
779    /// terminates the run instead of being delivered. This is how a hook
780    /// that observed an answer (a completion, a tool result) ends the run.
781    /// The cancellation short-circuits nested hook stacks; later hooks cannot
782    /// replace it with a successful answer.
783    pub fn stop(reason: impl Into<String>) -> Self {
784        Self::Replace(Err(ErrorReport::new(ErrorKind::Cancelled, reason)))
785    }
786
787    /// Replace the model-visible output of a tool result, keeping the
788    /// result's status and the dispatch context. `Proceed` when `event`
789    /// did not resolve to a tool result.
790    pub fn rewrite_tool_output(event: &OutcomeEvent<'_>, output: ToolOutput) -> Self {
791        match event.outcome {
792            Ok(Answered::ToolResult { result }) => Self::Replace(Ok(Answered::ToolResult {
793                result: result.clone().with_output(output),
794            })),
795            _ => Self::Proceed,
796        }
797    }
798
799    /// [`OutcomeAction::rewrite_tool_output`] with a text output.
800    pub fn rewrite_tool_result(event: &OutcomeEvent<'_>, text: impl Into<String>) -> Self {
801        Self::rewrite_tool_output(event, ToolOutput::text(text))
802    }
803}
804
805impl<'a> OutcomeEvent<'a> {
806    /// The tool result this outcome carries, for a tool-call effect.
807    pub fn tool_result(&self) -> Option<&'a ToolResult> {
808        match self.outcome {
809            Ok(Answered::ToolResult { result, .. }) => Some(result),
810            _ => None,
811        }
812    }
813
814    /// The dispatch context the tool answered with, for a tool-call effect.
815    pub fn tool_context(&self) -> Option<&'a ToolContext> {
816        self.context
817    }
818
819    /// The completion this outcome carries, for a completion effect.
820    pub fn completion(&self) -> Option<&'a rig_core::completion::CompletionResponse> {
821        match self.outcome {
822            Ok(Answered::Completion(response)) => Some(response),
823            _ => None,
824        }
825    }
826
827    /// The tool name, for a tool-call effect.
828    pub fn tool_name(&self) -> Option<&'a str> {
829        match self.kind {
830            EffectKind::ToolCall { name, .. } => Some(name),
831            _ => None,
832        }
833    }
834
835    /// The effective JSON arguments, for a tool-call effect.
836    pub fn tool_args(&self) -> Option<&'a str> {
837        match self.kind {
838            EffectKind::ToolCall { args, .. } => Some(args),
839            _ => None,
840        }
841    }
842}
843
844pub use crate::run::patch::RequestPatch;
845
846/// Action for model-selection hooks.
847#[derive(Debug, Clone)]
848pub enum ModelSelectionAction {
849    /// Keep the candidate supplied to this hook.
850    Continue,
851    /// Replace the candidate and pass it to later hooks: the label of a
852    /// model registered in the agent's handler table.
853    Select(ModelRef),
854    /// Stop the run before request preparation or model execution.
855    Stop(String),
856}
857
858impl ModelSelectionAction {
859    /// Keeps the current model candidate.
860    pub fn continue_run() -> Self {
861        Self::Continue
862    }
863
864    /// Selects `model` and passes it to later hooks.
865    pub fn select(model: impl Into<ModelRef>) -> Self {
866        Self::Select(model.into())
867    }
868
869    /// Stops the run before the pending model attempt.
870    ///
871    /// A selection stop happens before the attempt is issued, so it does not
872    /// advance [`ModelSelection::previous_model`].
873    pub fn stop(reason: impl Into<String>) -> Self {
874        Self::Stop(reason.into())
875    }
876}
877
878/// Action for completion-call hooks.
879#[derive(Debug, Clone, PartialEq)]
880pub enum CompletionCallAction {
881    /// Send the baseline request.
882    Continue,
883    /// Merge this per-turn patch into the request.
884    Patch(RequestPatch),
885    /// Stop the run with a reason.
886    Stop(String),
887}
888
889impl CompletionCallAction {
890    /// Creates an action that sends the request without adding a patch.
891    pub fn continue_run() -> Self {
892        Self::Continue
893    }
894
895    /// Creates an action that applies a per-turn request patch.
896    pub fn patch(patch: RequestPatch) -> Self {
897        Self::Patch(patch)
898    }
899
900    /// Creates an action that stops the run with the supplied reason.
901    pub fn stop(reason: impl Into<String>) -> Self {
902        Self::Stop(reason.into())
903    }
904}
905
906/// Action for observe-only lifecycle events.
907#[derive(Debug, Clone, PartialEq, Eq)]
908pub enum ObservationAction {
909    /// Continue the run.
910    Continue,
911    /// Stop the run.
912    Stop(String),
913}
914
915impl ObservationAction {
916    /// Creates an action that continues the run.
917    pub fn continue_run() -> Self {
918        Self::Continue
919    }
920
921    /// Creates an action that stops the run with the supplied reason.
922    pub fn stop(reason: impl Into<String>) -> Self {
923        Self::Stop(reason.into())
924    }
925}
926
927/// Per-run lifecycle observer and steerer.
928pub trait AgentHook: WasmCompatSend + WasmCompatSync {
929    /// Replay identity recorded by the hook stack. `None` uses the unqualified
930    /// type name; include decision-affecting configuration in an explicit name.
931    fn name(&self) -> Option<String> {
932        None
933    }
934
935    /// Runs once before the run's first model call, seeing the initial prompt.
936    ///
937    /// The hook may rewrite the prompt or stop the run before any provider
938    /// call. In a [`HookStack`], rewrites chain in registration order and the
939    /// first stop wins; see [`RunStart`]. The default action starts the run
940    /// with the current prompt.
941    fn on_run_start(
942        &self,
943        _ctx: &HookContext,
944        _event: RunStart<'_>,
945    ) -> impl Future<Output = RunStartAction> + WasmCompatSend {
946        async { RunStartAction::Continue }
947    }
948
949    /// Observe the final response or terminal error without scheduling more work.
950    /// Existing entries are visible, but entries appended here are not transferred
951    /// into the finished run.
952    fn on_run_settled(
953        &self,
954        _ctx: &HookContext,
955        _event: RunSettled<'_>,
956    ) -> impl Future<Output = ()> + WasmCompatSend {
957        async {}
958    }
959
960    /// Selects the model for the pending model-call boundary.
961    ///
962    /// Selection is synchronous, local, and non-blocking: it operates only on
963    /// already-constructed [`ModelRef`] values and may read or write the
964    /// run [`Scratchpad`], but must not perform blocking I/O. It runs once per
965    /// `CallModel` step whose completion-call hooks proceed, including
966    /// retries and post-tool calls, never after a completion-call stop, and
967    /// in-flight attempts never rebind. In a [`HookStack`], selections are
968    /// passed to later hooks in registration order; the last selection wins
969    /// and a stop is terminal. The default action keeps the current candidate.
970    /// See [`ModelSelection`] for the full ordering contract.
971    fn on_model_select(
972        &self,
973        _ctx: &HookContext,
974        _event: ModelSelection<'_>,
975    ) -> ModelSelectionAction {
976        ModelSelectionAction::Continue
977    }
978
979    /// Runs before a completion request is sent.
980    ///
981    /// Return a per-turn patch, continue without one, or stop the run. Patches
982    /// from a [`HookStack`] are merged in hook registration order.
983    fn on_completion_call(
984        &self,
985        _ctx: &HookContext,
986        _event: CompletionCallEvent<'_>,
987    ) -> impl Future<Output = CompletionCallAction> + WasmCompatSend {
988        async { CompletionCallAction::Continue }
989    }
990
991    /// Observes or rejects the content produced at the end of a model turn.
992    ///
993    /// A retry is valid only for a tool-free turn and consumes the existing
994    /// total model-call budget. The default action accepts the turn.
995    fn on_model_turn_finished(
996        &self,
997        _ctx: &HookContext,
998        _event: ModelTurnFinished<'_>,
999    ) -> impl Future<Output = ModelTurnAction> + WasmCompatSend {
1000        async { ModelTurnAction::Continue }
1001    }
1002
1003    /// Resolves a model-emitted tool call that cannot be dispatched as written.
1004    ///
1005    /// The call may be failed, retried, repaired, skipped, or used to stop the
1006    /// run. Return `None` to leave the decision to a later hook. If every hook
1007    /// in a [`HookStack`] returns `None`, the run's
1008    /// [`UnhandledInvalidToolCall`](crate::run::UnhandledInvalidToolCall)
1009    /// policy applies.
1010    ///
1011    /// A call whose arguments are not a JSON object
1012    /// ([`InvalidToolCallReason::MalformedArguments`]) is offered in the tool
1013    /// step, after its turn committed, and is always answered with a tool
1014    /// result. `None` answers with feedback naming the arguments, `Retry`
1015    /// with its feedback, and `Skip` with its reason. `Stop` and `Fail` end
1016    /// the run, and `Repair` is refused, since renaming the tool cannot fix
1017    /// its arguments.
1018    fn on_invalid_tool_call(
1019        &self,
1020        _ctx: &HookContext,
1021        _event: &InvalidToolCallContext,
1022    ) -> impl Future<Output = Option<InvalidToolCallAction>> + WasmCompatSend {
1023        async { None }
1024    }
1025
1026    /// Observes a text delta from a streaming response.
1027    ///
1028    /// The default action continues the run.
1029    fn on_text_delta(
1030        &self,
1031        _ctx: &HookContext,
1032        _event: TextDelta<'_>,
1033    ) -> impl Future<Output = ObservationAction> + WasmCompatSend {
1034        async { ObservationAction::Continue }
1035    }
1036
1037    /// Observes a reasoning delta from a streaming response.
1038    ///
1039    /// The aggregate is scoped to the reasoning part identified by the event's
1040    /// correlator. Like all streamed deltas, it remains provisional until the
1041    /// model turn is accepted. The default action continues the run.
1042    fn on_reasoning_delta(
1043        &self,
1044        _ctx: &HookContext,
1045        _event: ReasoningDelta<'_>,
1046    ) -> impl Future<Output = ObservationAction> + WasmCompatSend {
1047        async { ObservationAction::Continue }
1048    }
1049
1050    /// Observes an argument fragment of a streaming tool call, before the
1051    /// fragment reaches the stream. A stop cancels the run before the call
1052    /// executes. Like all streamed deltas, it remains provisional until the
1053    /// model turn is accepted.
1054    ///
1055    /// The default action continues the run.
1056    fn on_tool_call_delta(
1057        &self,
1058        _ctx: &HookContext,
1059        _event: ToolCallDelta<'_>,
1060    ) -> impl Future<Output = ObservationAction> + WasmCompatSend {
1061        async { ObservationAction::Continue }
1062    }
1063
1064    /// An effect is about to be dispatched through the agent's handlers. Runs for
1065    /// every family; `Memory`, `Retrieve`, `Embed`, `Rerank` and `Custom` dispatches
1066    /// are observe-only unless the hook opts in through
1067    /// [`AgentHook::observes`] for their [`StepEventKind`].
1068    ///
1069    /// Gated by [`AgentHook::observes`]: a hook whose `observes` answers
1070    /// `false` for [`StepEventKind::CompletionDispatch`] or
1071    /// [`StepEventKind::ToolDispatch`] is **not called** for those
1072    /// dispatches and cannot deny, patch or replace them. A hook that
1073    /// overrides `observes` to trim delta noise must keep the dispatch
1074    /// kinds it means to gate.
1075    fn on_dispatch(
1076        &self,
1077        _ctx: &HookContext,
1078        _event: DispatchEvent<'_>,
1079    ) -> impl Future<Output = DispatchAction> + WasmCompatSend {
1080        async { DispatchAction::Proceed }
1081    }
1082
1083    /// An effect resolved through the agent's handlers. Gated by
1084    /// [`AgentHook::observes`] like [`AgentHook::on_dispatch`]. Each
1085    /// dispatched id gets at most one outcome; a denied one gets none. A
1086    /// completion's outcome fires after the run validated an accepted turn,
1087    /// where a replacement applies. Every other attempt closes observe-only
1088    /// and a replacement is ignored. It is `Err` when no whole answer arrived:
1089    /// the provider call failed, a hook stopped the run mid-reply
1090    /// (`Cancelled`), or the run failed a streamed reply before it ended. It
1091    /// is `Ok` with the provider's response when the answer arrived and the
1092    /// run rejected, retried, recovered, abandoned or failed it, so an `Ok`
1093    /// completion outcome is not proof that the turn was accepted.
1094    fn on_outcome(
1095        &self,
1096        _ctx: &HookContext,
1097        _event: OutcomeEvent<'_>,
1098    ) -> impl Future<Output = OutcomeAction> + WasmCompatSend {
1099        async { OutcomeAction::Proceed }
1100    }
1101
1102    /// Declare event interest. Memory, retrieval, embedding, reranking, and custom
1103    /// dispatches default to false; all other kinds default to true.
1104    /// For dispatch events, false prevents both boundary callbacks and therefore
1105    /// prevents this hook from steering that family.
1106    fn observes(&self, kind: StepEventKind) -> bool {
1107        !matches!(
1108            kind,
1109            StepEventKind::EmbedDispatch
1110                | StepEventKind::RerankDispatch
1111                | StepEventKind::RetrieveDispatch
1112                | StepEventKind::CustomDispatch
1113        )
1114    }
1115}
1116
1117impl AgentHook for () {
1118    fn observes(&self, _kind: StepEventKind) -> bool {
1119        false
1120    }
1121}
1122
1123/// The erased hook events whose dispatch is a plain `Box::pin(self.on_*(..))`.
1124/// `model_select` (sync) and `invalid_tool_call` (borrowed event) are
1125/// hand-written below.
1126macro_rules! for_each_boxed_hook_event {
1127    ($m:ident) => {
1128        $m!(
1129            completion_call,
1130            on_completion_call,
1131            CompletionCallEvent,
1132            CompletionCallAction
1133        );
1134        $m!(
1135            model_turn_finished,
1136            on_model_turn_finished,
1137            ModelTurnFinished,
1138            ModelTurnAction
1139        );
1140        $m!(text_delta, on_text_delta, TextDelta, ObservationAction);
1141        $m!(
1142            reasoning_delta,
1143            on_reasoning_delta,
1144            ReasoningDelta,
1145            ObservationAction
1146        );
1147        $m!(
1148            tool_call_delta,
1149            on_tool_call_delta,
1150            ToolCallDelta,
1151            ObservationAction
1152        );
1153    };
1154}
1155
1156macro_rules! erased_hook_decl {
1157    ($erased:ident, $on:ident, $event:ident, $action:ident) => {
1158        fn $erased<'a>(
1159            &'a self,
1160            ctx: &'a HookContext,
1161            event: $event<'a>,
1162        ) -> WasmBoxedFuture<'a, $action>;
1163    };
1164}
1165
1166macro_rules! erased_hook_forward {
1167    ($erased:ident, $on:ident, $event:ident, $action:ident) => {
1168        fn $erased<'a>(
1169            &'a self,
1170            ctx: &'a HookContext,
1171            event: $event<'a>,
1172        ) -> WasmBoxedFuture<'a, $action> {
1173            Box::pin(self.$on(ctx, event))
1174        }
1175    };
1176}
1177
1178trait DynAgentHook: WasmCompatSend + WasmCompatSync {
1179    fn run_start<'a>(
1180        &'a self,
1181        ctx: &'a HookContext,
1182        event: RunStart<'a>,
1183    ) -> WasmBoxedFuture<'a, RunStartAction>;
1184    fn run_settled<'a>(
1185        &'a self,
1186        ctx: &'a HookContext,
1187        event: RunSettled<'a>,
1188    ) -> WasmBoxedFuture<'a, ()>;
1189    fn model_select(&self, ctx: &HookContext, event: ModelSelection<'_>) -> ModelSelectionAction;
1190    fn invalid_tool_call<'a>(
1191        &'a self,
1192        ctx: &'a HookContext,
1193        event: &'a InvalidToolCallContext,
1194    ) -> WasmBoxedFuture<'a, Option<InvalidToolCallAction>>;
1195    fn dispatch<'a>(
1196        &'a self,
1197        ctx: &'a HookContext,
1198        event: DispatchEvent<'a>,
1199    ) -> WasmBoxedFuture<'a, DispatchAction>;
1200    fn outcome<'a>(
1201        &'a self,
1202        ctx: &'a HookContext,
1203        event: OutcomeEvent<'a>,
1204    ) -> WasmBoxedFuture<'a, OutcomeAction>;
1205    for_each_boxed_hook_event!(erased_hook_decl);
1206    fn observes(&self, kind: StepEventKind) -> bool;
1207}
1208
1209impl<H> DynAgentHook for H
1210where
1211    H: AgentHook,
1212{
1213    fn run_start<'a>(
1214        &'a self,
1215        ctx: &'a HookContext,
1216        event: RunStart<'a>,
1217    ) -> WasmBoxedFuture<'a, RunStartAction> {
1218        Box::pin(self.on_run_start(ctx, event))
1219    }
1220
1221    fn run_settled<'a>(
1222        &'a self,
1223        ctx: &'a HookContext,
1224        event: RunSettled<'a>,
1225    ) -> WasmBoxedFuture<'a, ()> {
1226        Box::pin(self.on_run_settled(ctx, event))
1227    }
1228
1229    fn model_select(&self, ctx: &HookContext, event: ModelSelection<'_>) -> ModelSelectionAction {
1230        self.on_model_select(ctx, event)
1231    }
1232
1233    fn invalid_tool_call<'a>(
1234        &'a self,
1235        ctx: &'a HookContext,
1236        event: &'a InvalidToolCallContext,
1237    ) -> WasmBoxedFuture<'a, Option<InvalidToolCallAction>> {
1238        Box::pin(self.on_invalid_tool_call(ctx, event))
1239    }
1240    fn dispatch<'a>(
1241        &'a self,
1242        ctx: &'a HookContext,
1243        event: DispatchEvent<'a>,
1244    ) -> WasmBoxedFuture<'a, DispatchAction> {
1245        Box::pin(self.on_dispatch(ctx, event))
1246    }
1247    fn outcome<'a>(
1248        &'a self,
1249        ctx: &'a HookContext,
1250        event: OutcomeEvent<'a>,
1251    ) -> WasmBoxedFuture<'a, OutcomeAction> {
1252        Box::pin(self.on_outcome(ctx, event))
1253    }
1254    for_each_boxed_hook_event!(erased_hook_forward);
1255    fn observes(&self, kind: StepEventKind) -> bool {
1256        AgentHook::observes(self, kind)
1257    }
1258}
1259
1260/// Ordered composable hook stack.
1261///
1262/// Model selections chain in registration order: each hook sees the candidate
1263/// selected by earlier hooks, the last selection wins, and a stop is terminal.
1264/// Nested stacks preserve the same composition semantics.
1265#[derive(Clone, Default)]
1266pub struct HookStack {
1267    hooks: Vec<Arc<dyn DynAgentHook>>,
1268    /// The name of every hook ([`AgentHook::name`], else its type name),
1269    /// in registration order, nested stacks flattened: what an effect
1270    /// log's header records as the program.
1271    names: Vec<String>,
1272}
1273
1274impl std::fmt::Debug for HookStack {
1275    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1276        f.debug_struct("HookStack")
1277            .field("len", &self.hooks.len())
1278            .finish()
1279    }
1280}
1281
1282/// `H`'s type name without its module path (generic arguments kept), the
1283/// name a [`HookStack`] records for it.
1284fn short_type_name<H>() -> &'static str {
1285    let full = std::any::type_name::<H>();
1286    let generics = full.find('<').unwrap_or(full.len());
1287    let path = &full[..generics];
1288    match path.rfind("::") {
1289        Some(at) => &full[at + 2..],
1290        None => full,
1291    }
1292}
1293
1294impl HookStack {
1295    /// Creates an empty hook stack.
1296    pub fn new() -> Self {
1297        Self::default()
1298    }
1299
1300    /// Creates a hook stack containing `hook`.
1301    pub fn with<H: AgentHook + 'static>(hook: H) -> Self {
1302        let mut stack = Self::new();
1303        stack.push(hook);
1304        stack
1305    }
1306
1307    /// Append a hook. Its recorded name is [`AgentHook::name`] or its type name
1308    /// without the module path; nested stacks contribute flattened names.
1309    pub fn push<H: AgentHook + 'static>(&mut self, hook: H) {
1310        // A nested stack contributes its members' names, flattened in
1311        // order, so two stacks that run the same hooks name the same program.
1312        match (&hook as &dyn std::any::Any).downcast_ref::<HookStack>() {
1313            Some(nested) => self.names.extend(nested.names.iter().cloned()),
1314            None => self.names.push(
1315                hook.name()
1316                    .unwrap_or_else(|| short_type_name::<H>().to_owned()),
1317            ),
1318        }
1319        self.hooks.push(Arc::new(hook));
1320    }
1321
1322    /// Recorded hook names in registration order, with nested stacks flattened.
1323    pub fn names(&self) -> Vec<String> {
1324        self.names.clone()
1325    }
1326
1327    /// Returns `true` when the stack contains no hooks.
1328    pub fn is_empty(&self) -> bool {
1329        self.hooks.is_empty()
1330    }
1331
1332    /// Returns the number of hooks in the stack.
1333    pub fn len(&self) -> usize {
1334        self.hooks.len()
1335    }
1336}
1337
1338/// An action with a neutral `Continue` state that observe-only and steering
1339/// dispatch short-circuits on: the first non-`Continue` action wins and later
1340/// hooks are not invoked.
1341trait ShortCircuitAction: Sized {
1342    const CONTINUE: Self;
1343    fn is_continue(&self) -> bool;
1344}
1345
1346impl ShortCircuitAction for ObservationAction {
1347    const CONTINUE: Self = ObservationAction::Continue;
1348    fn is_continue(&self) -> bool {
1349        matches!(self, ObservationAction::Continue)
1350    }
1351}
1352
1353impl ShortCircuitAction for ModelTurnAction {
1354    const CONTINUE: Self = ModelTurnAction::Continue;
1355    fn is_continue(&self) -> bool {
1356        matches!(self, ModelTurnAction::Continue)
1357    }
1358}
1359
1360/// Dispatches to each hook in registration order, returning the first action
1361/// that is not `Continue` without invoking the remaining hooks.
1362async fn first_non_continue<'a, A, F>(hooks: &'a [Arc<dyn DynAgentHook>], mut dispatch: F) -> A
1363where
1364    A: ShortCircuitAction,
1365    F: FnMut(&'a dyn DynAgentHook) -> WasmBoxedFuture<'a, A>,
1366{
1367    for hook in hooks {
1368        let action = dispatch(hook.as_ref()).await;
1369        if !action.is_continue() {
1370            return action;
1371        }
1372    }
1373    A::CONTINUE
1374}
1375
1376/// Generate the `HookStack` methods whose dispatch is exactly
1377/// [`first_non_continue`] over the erased hooks: `(on_* name, erased name,
1378/// event type, action type)`, mirroring `for_each_boxed_hook_event!`. The
1379/// genuinely chaining events (`on_model_select`, `on_completion_call`,
1380/// `on_invalid_tool_call`, `on_dispatch`, `on_outcome`) stay hand-written.
1381macro_rules! stack_first_non_continue {
1382    ($($on:ident, $erased:ident, $event:ident, $action:ident;)+) => {
1383        $(
1384            async fn $on(&self, ctx: &HookContext, event: $event<'_>) -> $action {
1385                first_non_continue(&self.hooks, |hook| hook.$erased(ctx, event)).await
1386            }
1387        )+
1388    };
1389}
1390
1391impl AgentHook for HookStack {
1392    async fn on_run_start(&self, ctx: &HookContext, event: RunStart<'_>) -> RunStartAction {
1393        let mut rewritten: Option<Message> = None;
1394        for hook in &self.hooks {
1395            let current = RunStart {
1396                prompt: rewritten.as_ref().unwrap_or(event.prompt),
1397                ..event
1398            };
1399            match hook.run_start(ctx, current).await {
1400                RunStartAction::Continue => {}
1401                RunStartAction::Rewrite(prompt) => rewritten = Some(prompt),
1402                stop @ RunStartAction::Stop(_) => return stop,
1403            }
1404        }
1405        rewritten.map_or(RunStartAction::Continue, RunStartAction::Rewrite)
1406    }
1407
1408    async fn on_run_settled(&self, ctx: &HookContext, event: RunSettled<'_>) {
1409        for hook in &self.hooks {
1410            hook.run_settled(ctx, event).await;
1411        }
1412    }
1413
1414    fn on_model_select(
1415        &self,
1416        ctx: &HookContext,
1417        event: ModelSelection<'_>,
1418    ) -> ModelSelectionAction {
1419        let mut selected = None;
1420        for hook in &self.hooks {
1421            let action = {
1422                let selected_model = selected.as_ref().unwrap_or(event.selected_model);
1423                hook.model_select(
1424                    ctx,
1425                    ModelSelection {
1426                        selected_model,
1427                        ..event
1428                    },
1429                )
1430            };
1431            match action {
1432                ModelSelectionAction::Continue => {}
1433                ModelSelectionAction::Select(model) => selected = Some(model),
1434                stop @ ModelSelectionAction::Stop(_) => return stop,
1435            }
1436        }
1437        selected.map_or(ModelSelectionAction::Continue, ModelSelectionAction::Select)
1438    }
1439
1440    async fn on_completion_call(
1441        &self,
1442        ctx: &HookContext,
1443        event: CompletionCallEvent<'_>,
1444    ) -> CompletionCallAction {
1445        let mut merged: Option<RequestPatch> = None;
1446        for hook in &self.hooks {
1447            match hook.completion_call(ctx, event).await {
1448                CompletionCallAction::Continue => {}
1449                CompletionCallAction::Patch(patch) => {
1450                    merged = Some(match merged {
1451                        None => patch,
1452                        Some(value) => value.merge(patch),
1453                    });
1454                }
1455                stop @ CompletionCallAction::Stop(_) => return stop,
1456            }
1457        }
1458        match merged {
1459            Some(patch) if !patch.is_empty() => CompletionCallAction::Patch(patch),
1460            _ => CompletionCallAction::Continue,
1461        }
1462    }
1463
1464    stack_first_non_continue! {
1465        on_model_turn_finished, model_turn_finished, ModelTurnFinished, ModelTurnAction;
1466        on_text_delta, text_delta, TextDelta, ObservationAction;
1467        on_reasoning_delta, reasoning_delta, ReasoningDelta, ObservationAction;
1468        on_tool_call_delta, tool_call_delta, ToolCallDelta, ObservationAction;
1469    }
1470    async fn on_invalid_tool_call(
1471        &self,
1472        ctx: &HookContext,
1473        event: &InvalidToolCallContext,
1474    ) -> Option<InvalidToolCallAction> {
1475        for hook in &self.hooks {
1476            if let Some(action) = hook.invalid_tool_call(ctx, event).await {
1477                return Some(action);
1478            }
1479        }
1480        None
1481    }
1482    async fn on_dispatch(&self, ctx: &HookContext, event: DispatchEvent<'_>) -> DispatchAction {
1483        let kind = StepEventKind::for_family(event.kind.family());
1484        let mut patched: Option<EffectKind> = None;
1485        for hook in &self.hooks {
1486            if !hook.observes(kind) {
1487                continue;
1488            }
1489            let current = DispatchEvent {
1490                kind: patched.as_ref().unwrap_or(event.kind),
1491                ..event
1492            };
1493            match hook.dispatch(ctx, current).await {
1494                DispatchAction::Proceed => {}
1495                DispatchAction::Patch(next) => {
1496                    if let Err(report) = validate_dispatch_patch(current.kind, &next) {
1497                        if let Some(kind) = patched {
1498                            ctx.salvage_patch(event.id, kind);
1499                        }
1500                        return DispatchAction::Deny(report);
1501                    }
1502                    patched = Some(next);
1503                }
1504                deny @ DispatchAction::Deny(_) => {
1505                    // The denial wins, but an earlier hook's patch is what
1506                    // the skipped result must report: keep it for the engine.
1507                    if let Some(kind) = patched {
1508                        ctx.salvage_patch(event.id, kind);
1509                    }
1510                    return deny;
1511                }
1512            }
1513        }
1514        patched.map_or(DispatchAction::Proceed, DispatchAction::Patch)
1515    }
1516
1517    async fn on_outcome(&self, ctx: &HookContext, event: OutcomeEvent<'_>) -> OutcomeAction {
1518        let kind = StepEventKind::for_family(event.kind.family());
1519        let mut replaced: Option<Result<Answered, ErrorReport>> = None;
1520        for hook in &self.hooks {
1521            if !hook.observes(kind) {
1522                continue;
1523            }
1524            let current = OutcomeEvent {
1525                outcome: replaced.as_ref().unwrap_or(event.outcome),
1526                ..event
1527            };
1528            match hook.outcome(ctx, current).await {
1529                OutcomeAction::Proceed => {}
1530                OutcomeAction::Replace(next) => {
1531                    if matches!(&next, Err(report) if report.kind == ErrorKind::Cancelled) {
1532                        return OutcomeAction::Replace(next);
1533                    }
1534                    replaced = Some(next);
1535                }
1536            }
1537        }
1538        replaced.map_or(OutcomeAction::Proceed, OutcomeAction::Replace)
1539    }
1540
1541    fn observes(&self, kind: StepEventKind) -> bool {
1542        self.hooks.iter().any(|hook| hook.observes(kind))
1543    }
1544}
1545
1546#[cfg(test)]
1547mod tests;