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