Skip to main content

SessionHooks

github_copilot_sdk::hooks

Trait SessionHooks 

Source 
pub trait SessionHooks:
    Send
    + Sync
    + 'static {
    // Provided methods
    fn on_hook<'life0, 'async_trait>(
        &'life0 self,
        event: HookEvent,
    ) -> Pin<Box<dyn Future<Output = HookOutput> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn on_pre_tool_use<'life0, 'async_trait>(
        &'life0 self,
        _input: PreToolUseInput,
        _ctx: HookContext,
    ) -> Pin<Box<dyn Future<Output = Option<PreToolUseOutput>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn on_post_tool_use<'life0, 'async_trait>(
        &'life0 self,
        _input: PostToolUseInput,
        _ctx: HookContext,
    ) -> Pin<Box<dyn Future<Output = Option<PostToolUseOutput>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn on_user_prompt_submitted<'life0, 'async_trait>(
        &'life0 self,
        _input: UserPromptSubmittedInput,
        _ctx: HookContext,
    ) -> Pin<Box<dyn Future<Output = Option<UserPromptSubmittedOutput>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn on_session_start<'life0, 'async_trait>(
        &'life0 self,
        _input: SessionStartInput,
        _ctx: HookContext,
    ) -> Pin<Box<dyn Future<Output = Option<SessionStartOutput>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn on_session_end<'life0, 'async_trait>(
        &'life0 self,
        _input: SessionEndInput,
        _ctx: HookContext,
    ) -> Pin<Box<dyn Future<Output = Option<SessionEndOutput>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn on_error_occurred<'life0, 'async_trait>(
        &'life0 self,
        _input: ErrorOccurredInput,
        _ctx: HookContext,
    ) -> Pin<Box<dyn Future<Output = Option<ErrorOccurredOutput>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
}
Expand description

Callback trait for session hooks — invoked by the CLI at key lifecycle points (tool use, prompt submission, session start/end, errors).

Implement this trait to intercept and modify CLI behavior at hook points. There are two styles of implementation — pick whichever fits:

  1. Per-hook methods (recommended). Override the specific on_* hook methods you care about; every hook has a default that returns None (meaning “no hook registered, use CLI default behavior”).
  2. Single on_hook method. Override this one and match on HookEvent yourself — useful for logging middleware or shared dispatch logic.

Hooks only fire when hooks are enabled on the session (via SessionConfig::hooks = Some(true), which SessionConfig::with_hooks sets automatically).

Provided Methods§

Source

fn on_hook<'life0, 'async_trait>( &'life0 self, event: HookEvent, ) -> Pin<Box<dyn Future<Output = HookOutput> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Top-level dispatch. The default implementation fans out to the per-hook methods below; override this only if you want a single matching point across all hook types.

Source

fn on_pre_tool_use<'life0, 'async_trait>( &'life0 self, _input: PreToolUseInput, _ctx: HookContext, ) -> Pin<Box<dyn Future<Output = Option<PreToolUseOutput>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Called before a tool executes. Return Some(output) to approve/deny or modify the call, or None (default) to pass through unchanged.

Source

fn on_post_tool_use<'life0, 'async_trait>( &'life0 self, _input: PostToolUseInput, _ctx: HookContext, ) -> Pin<Box<dyn Future<Output = Option<PostToolUseOutput>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Called after a tool executes. Return Some(output) to inject additional context or signal post-processing decisions; None (default) means no follow-up.

Source

fn on_user_prompt_submitted<'life0, 'async_trait>( &'life0 self, _input: UserPromptSubmittedInput, _ctx: HookContext, ) -> Pin<Box<dyn Future<Output = Option<UserPromptSubmittedOutput>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Called when the user submits a prompt. Return Some(output) to rewrite the prompt or inject extra context; None (default) passes through unchanged.

Source

fn on_session_start<'life0, 'async_trait>( &'life0 self, _input: SessionStartInput, _ctx: HookContext, ) -> Pin<Box<dyn Future<Output = Option<SessionStartOutput>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Called at session creation or resume. Return Some(output) to inject startup context.

Source

fn on_session_end<'life0, 'async_trait>( &'life0 self, _input: SessionEndInput, _ctx: HookContext, ) -> Pin<Box<dyn Future<Output = Option<SessionEndOutput>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Called when the session ends. Return Some(output) if your hook needs to signal cleanup behavior.

Source

fn on_error_occurred<'life0, 'async_trait>( &'life0 self, _input: ErrorOccurredInput, _ctx: HookContext, ) -> Pin<Box<dyn Future<Output = Option<ErrorOccurredOutput>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Called when the CLI reports an error. Return Some(output) to influence retry behavior or surface a user-facing notification.

Implementors§