Module hooks 

Lifecycle hooks for the agent loop.

Hooks are callbacks invoked at well-defined points during an agent run. They allow consumers to observe, log, gate, or transform behaviour without modifying the agent loop itself.

Hook points

• SessionStart — at the top of an agent run, before any LLM call.
• PreToolCall — before each tool dispatch (after the permission hook).
• PostToolCall — after each tool returns.
• PreCompact — before compaction fires.
• PostCompact — after compaction completes.
• SessionEnd — at terminal finishes (currently only on the legacy Agent path; the AgentRuntime does not dispatch this yet).

Usage

use recursive::hooks::{Hook, HookEvent, HookAction, HookRegistry};

struct MyHook;
impl Hook for MyHook {
    fn on_event(&self, event: HookEvent) -> HookAction {
        match event {
            HookEvent::PreToolCall { name, .. } => {
                eprintln!("about to call {name}");
                HookAction::Continue
            }
            _ => HookAction::Continue,
        }
    }
}

let mut registry = HookRegistry::new();
registry.register(Arc::new(MyHook));

Re-exports

pub use config::load_hooks_config;

pub use config::HookCommand;

pub use config::HookCommandType;

pub use config::HookMatcher;

pub use config::HooksConfig;

pub use external::ExternalHookRunner;

pub use external::HookResult;

pub use external::PermissionDecision;

Modules

config

Hook configuration schema and loader.

external

External process-based hooks.

Structs

HookRegistry

A registry of hooks that dispatches events to all registered hooks in order.

ToolTimingHook

A hook that prints tool call timing information to stderr.

Enums

HookAction

Action a hook can request in response to an event.

HookEvent

Events emitted at lifecycle points during an agent run.

Traits

Hook

A lifecycle hook that can observe and influence agent behaviour.