pig/hooks

Hooks system for pig agent lifecycle mediation.

Hooks allow library users to intercept agent lifecycle events:

Blocking tool calls
Transforming results
Reacting to events

Hooks are composed as a List(Hooks) — no wrapper type needed. Composition functions run handlers in order with per-event semantics.

Types

AfterInferenceEvent

</>

After the provider responds.

pub type AfterInferenceEvent {
  AfterInferenceEvent(
    model: String,
    message: message.Message,
    duration_ms: Int,
  )
}

Constructors

AfterInferenceEvent(
  model: String,
  message: message.Message,
  duration_ms: Int,
)

BeforeInferenceAction

</>

What a before_inference handler returns.

pub type BeforeInferenceAction {
  KeepMessages
  ReplaceMessages(messages: List(message.Message))
}

Constructors

```
KeepMessages
```

ReplaceMessages(messages: List(message.Message))

BeforeInferenceEvent

</>

Before the provider is called. Handlers can modify the messages sent.

pub type BeforeInferenceEvent {
  BeforeInferenceEvent(
    model: String,
    messages: List(message.Message),
  )
}

Constructors

BeforeInferenceEvent(
  model: String,
  messages: List(message.Message),
)

CompleteEvent

</>

The agent loop completed with a final message.

pub type CompleteEvent {
  CompleteEvent(
    model: String,
    message: message.Message,
    total_iterations: Int,
  )
}

Constructors

CompleteEvent(
  model: String,
  message: message.Message,
  total_iterations: Int,
)

ErrorEvent

</>

An error occurred during inference.

pub type ErrorEvent {
  ErrorEvent(model: String, error: error.AiError)
}

Constructors

ErrorEvent(model: String, error: error.AiError)

A named set of lifecycle callbacks for mediating the agent loop. Construct with new(name) and add handlers with on_* builder functions. Default handlers are no-ops: AllowTool, KeepResult, KeepMessages, fn(_) { Nil }.

pub type Hooks {
  Hooks(
    name: String,
    on_session_start: fn(SessionStartEvent) -> Nil,
    on_session_shutdown: fn(SessionShutdownEvent) -> Nil,
    on_before_inference: fn(BeforeInferenceEvent) -> BeforeInferenceAction,
    on_after_inference: fn(AfterInferenceEvent) -> Nil,
    on_tool_call: fn(ToolCallEvent) -> ToolCallAction,
    on_tool_result: fn(ToolResultEvent) -> ToolResultAction,
    on_error: fn(ErrorEvent) -> Nil,
    on_complete: fn(CompleteEvent) -> Nil,
  )
}

Constructors

Hooks(
  name: String,
  on_session_start: fn(SessionStartEvent) -> Nil,
  on_session_shutdown: fn(SessionShutdownEvent) -> Nil,
  on_before_inference: fn(BeforeInferenceEvent) -> BeforeInferenceAction,
  on_after_inference: fn(AfterInferenceEvent) -> Nil,
  on_tool_call: fn(ToolCallEvent) -> ToolCallAction,
  on_tool_result: fn(ToolResultEvent) -> ToolResultAction,
  on_error: fn(ErrorEvent) -> Nil,
  on_complete: fn(CompleteEvent) -> Nil,
)

MessagesDecision

</>

Decision from before_inference hooks. Carries attribution for observability.

pub type MessagesDecision {
  MessagesUnchanged(original: List(message.Message))
  MessagesReplaced(
    final_messages: List(message.Message),
    transformers: List(String),
  )
}

Constructors

MessagesUnchanged(original: List(message.Message))

MessagesReplaced(
  final_messages: List(message.Message),
  transformers: List(String),
)

SessionShutdownEvent

</>

Fired when a session shuts down (actor stops).

pub type SessionShutdownEvent {
  SessionShutdownEvent(
    history: List(message.Message),
    iterations: Int,
  )
}

Constructors

SessionShutdownEvent(
  history: List(message.Message),
  iterations: Int,
)

SessionStartEvent

</>

Fired when a session starts (after replay if applicable).

pub type SessionStartEvent {
  SessionStartEvent(history: List(message.Message))
}

Constructors

SessionStartEvent(history: List(message.Message))

ToolCallAction

</>

What a tool_call handler returns.

pub type ToolCallAction {
  AllowTool
  BlockTool(reason: String)
}

Constructors

```
AllowTool
```
```
BlockTool(reason: String)
```

ToolCallDecision

</>

Decision from tool_call hooks. Core loop pattern-matches to decide whether to execute or create an error Tool message.

pub type ToolCallDecision {
  ToolAllowed
  ToolBlocked(hook_name: String, reason: String)
}

Constructors

```
ToolAllowed
```

ToolBlocked(hook_name: String, reason: String)

ToolCallEvent

</>

Before a tool executes. Handlers can block it.

pub type ToolCallEvent {
  ToolCallEvent(
    tool_name: String,
    tool_call_id: String,
    arguments_json: String,
  )
}

Constructors

ToolCallEvent(
  tool_name: String,
  tool_call_id: String,
  arguments_json: String,
)

ToolResultAction

</>

What a tool_result handler returns.

pub type ToolResultAction {
  KeepResult
  ReplaceResult(content: String, is_error: Bool)
}

Constructors

```
KeepResult
```

ReplaceResult(content: String, is_error: Bool)

ToolResultDecision

</>

Decision from tool_result hooks. Carries attribution for observability.

pub type ToolResultDecision {
  ResultUnchanged(original_event: ToolResultEvent)
  ResultTransformed(
    final_event: ToolResultEvent,
    transformers: List(String),
  )
}

Constructors

ResultUnchanged(original_event: ToolResultEvent)

ResultTransformed(
  final_event: ToolResultEvent,
  transformers: List(String),
)

ToolResultEvent

</>

After a tool finishes. Handlers can transform the result.

pub type ToolResultEvent {
  ToolResultEvent(
    tool_name: String,
    tool_call_id: String,
    result: String,
    is_error: Bool,
    duration_ms: Int,
  )
}

Constructors

ToolResultEvent(
  tool_name: String,
  tool_call_id: String,
  result: String,
  is_error: Bool,
  duration_ms: Int,
)

Values

allow_tool

</>

pub fn allow_tool() -> ToolCallAction

Returns an action that allows a tool call to proceed.

block_tool

</>

pub fn block_tool(reason: String) -> ToolCallAction

Returns an action that blocks a tool call with the given reason.

decide_messages

</>

pub fn decide_messages(
  hooks_list: List(Hooks),
  event: BeforeInferenceEvent,
) -> MessagesDecision

Decide the final messages for inference. Chains ReplaceMessages. Returns MessagesReplaced with all transformer names for observability.

decide_tool_call

</>

pub fn decide_tool_call(
  hooks_list: List(Hooks),
  event: ToolCallEvent,
) -> ToolCallDecision

Decide whether a tool call is allowed. First BlockTool wins. Returns ToolBlocked with the blocker’s name and reason for attribution.

decide_tool_result

</>

pub fn decide_tool_result(
  hooks_list: List(Hooks),
  event: ToolResultEvent,
) -> ToolResultDecision

Decide the final tool result. Chains ReplaceResult transformations. Returns ResultTransformed with all transformer names for observability.

keep_messages

</>

pub fn keep_messages() -> BeforeInferenceAction

Returns an action that keeps the original messages.

keep_result

</>

pub fn keep_result() -> ToolResultAction

Returns an action that keeps the original tool result.

new

</>

pub fn new(name: String) -> Hooks

Creates hooks with all no-op handlers.

notify_after_inference

</>

pub fn notify_after_inference(
  hooks_list: List(Hooks),
  event: AfterInferenceEvent,
) -> Nil

Run all after_inference handlers (fire-and-forget).

notify_complete

</>

pub fn notify_complete(
  hooks_list: List(Hooks),
  event: CompleteEvent,
) -> Nil

Run all complete handlers (fire-and-forget).

notify_error

</>

pub fn notify_error(
  hooks_list: List(Hooks),
  event: ErrorEvent,
) -> Nil

Run all error handlers (fire-and-forget).

notify_session_shutdown

</>

pub fn notify_session_shutdown(
  hooks_list: List(Hooks),
  event: SessionShutdownEvent,
) -> Nil

Run all session_shutdown handlers (fire-and-forget).

notify_session_start

</>

pub fn notify_session_start(
  hooks_list: List(Hooks),
  event: SessionStartEvent,
) -> Nil

Run all session_start handlers (fire-and-forget).

on_after_inference

</>

pub fn on_after_inference(
  h: Hooks,
  handler: fn(AfterInferenceEvent) -> Nil,
) -> Hooks

Sets the after_inference handler.

on_before_inference

</>

pub fn on_before_inference(
  h: Hooks,
  handler: fn(BeforeInferenceEvent) -> BeforeInferenceAction,
) -> Hooks

Sets the before_inference handler.

on_complete

</>

pub fn on_complete(
  h: Hooks,
  handler: fn(CompleteEvent) -> Nil,
) -> Hooks

Sets the complete handler.

on_error

</>

pub fn on_error(
  h: Hooks,
  handler: fn(ErrorEvent) -> Nil,
) -> Hooks

Sets the error handler.

on_session_shutdown

</>

pub fn on_session_shutdown(
  h: Hooks,
  handler: fn(SessionShutdownEvent) -> Nil,
) -> Hooks

Sets the session_shutdown handler.

on_session_start

</>

pub fn on_session_start(
  h: Hooks,
  handler: fn(SessionStartEvent) -> Nil,
) -> Hooks

Sets the session_start handler.

on_tool_call

</>

pub fn on_tool_call(
  h: Hooks,
  handler: fn(ToolCallEvent) -> ToolCallAction,
) -> Hooks

Sets the tool_call handler.

on_tool_result

</>

pub fn on_tool_result(
  h: Hooks,
  handler: fn(ToolResultEvent) -> ToolResultAction,
) -> Hooks

Sets the tool_result handler.

replace_messages

</>

pub fn replace_messages(
  messages: List(message.Message),
) -> BeforeInferenceAction

Returns an action that replaces the messages.

replace_result

</>

pub fn replace_result(
  content: String,
  is_error: Bool,
) -> ToolResultAction

Returns an action that replaces the tool result.