shapes

Hook shape — lifecycle interceptors for the conversation loop. Built-in and user-provided hooks follow the same shape.

Hook types are function signatures for now. A future phase can introduce a generic dispatch system with HookEvent types.

Types

PostToolExecutionHook

</>

Post-tool-execution hook: runs after tools execute, may inject warnings or halt. Returns updated history, updated guardrail state, and a halt flag.

pub type PostToolExecutionHook =
  fn(
    List(completions.Message),
    List(completions.ToolCall),
    List(tool.Tool),
    String,
  ) -> #(List(completions.Message), String, Bool)

PreApiCallHook

</>

Pre-API-call hook: may modify messages before they are sent to the model. Used by: compression, token warning injection.

pub type PreApiCallHook =
  fn(
    List(completions.Message),
    List(completions.ToolDefinition),
    String,
    fn(
      completions.Client,
      List(completions.Message),
      List(completions.ToolDefinition),
    ) -> Result(completions.ChatResponse, completions.ClientError),
    completions.Client,
  ) -> List(completions.Message)