> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle hooks

> Observe Ruby agent runs, model turns, tools, pauses, and completion.

Pass `on_event` to receive structured lifecycle events while a run executes.

```ruby theme={null}
result = agent.run(
  input: prompt,
  client: client,
  on_event: ->(event) {
    logger.info(
      "agent event",
      type: event[:type],
      run_id: event[:run_id],
      details: event[:details]
    )
  }
)
```

Useful events cover run start/completion/failure, model attempts, text and reasoning deltas, tool start/progress/completion/failure, and human checkpoints.

Keep handlers fast. Queue slow persistence work and redact sensitive tool inputs before forwarding events externally.