bamboo_agent_core/agent/
hooks.rs

1//! Agent lifecycle hook trait.
2//!
3//! Hooks are invoked at well-defined points in the agent loop (see
4//! [`AgentHookPoint`](bamboo_domain::AgentHookPoint)).
5//! They can inspect state, mutate session, and control flow via
6//! [`HookResult`](bamboo_domain::HookResult).
7
8use async_trait::async_trait;
9use bamboo_domain::{AgentHookPoint, HookPayload, HookResult};
10
11use super::types::Session;
12
13/// Trait for agent lifecycle hooks.
14///
15/// Implementations must be `Send + Sync` because hooks may be invoked
16/// from multiple concurrent agent runs.
17#[async_trait]
18pub trait AgentHook: Send + Sync {
19    /// Which hook point this hook subscribes to.
20    fn point(&self) -> AgentHookPoint;
21
22    /// Execute the hook.
23    ///
24    /// Receives immutable access to the session, the current hook point, and a
25    /// point-specific payload.
26    /// Returns a [`HookResult`] to control flow.
27    async fn run(
28        &self,
29        point: AgentHookPoint,
30        payload: &HookPayload,
31        session: &Session,
32    ) -> HookResult;
33
34    /// Whether this hook applies to the point-specific payload.
35    ///
36    /// The default accepts every payload. Configured tool hooks override this
37    /// to apply their tool-name matcher without spawning a process or emitting
38    /// a misleading execution checkpoint for non-matching calls.
39    fn matches(&self, _payload: &HookPayload) -> bool {
40        true
41    }
42
43    /// Optional priority (lower runs first). Default is 100.
44    fn priority(&self) -> u32 {
45        100
46    }
47
48    /// Optional name for logging and debugging.
49    fn name(&self) -> &str {
50        "unnamed_hook"
51    }
52}
bamboo_agent_core/agent/hooks.rs

bamboo_agent_core/agent/
hooks.rs
