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