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