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;