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

# Events

> Reference for SDK event surfaces.

The SDK exposes multiple event surfaces.

## AgentRuntimeEvent

Direct `AgentRuntime` usage emits low-level runtime events through `agent.subscribe(listener)`.

```typescript theme={"system"}
const unsubscribe = agent.subscribe((event) => {
  console.log(event.type)
})
```

Common runtime events include model events, tool execution events, run lifecycle events, and failure events. Runtime results use `AgentRunResult.status` rather than `finishReason`.

## AgentEvent

Core/host-facing agent events are emitted through `AgentConfig.onEvent` and core adapters.

| Event             | Description                           |
| ----------------- | ------------------------------------- |
| `content_start`   | Text/reasoning/tool content begins    |
| `content_update`  | Tool progress update                  |
| `content_end`     | Text/reasoning/tool content completes |
| `iteration_start` | Loop iteration begins                 |
| `iteration_end`   | Loop iteration completes              |
| `usage`           | Token/cost usage update               |
| `notice`          | Runtime status/recovery notice        |
| `done`            | Agent completed/aborted/failed        |
| `error`           | Error occurred                        |

## Done Event

```typescript theme={"system"}
interface AgentDoneEvent {
  type: "done"
  reason: "completed" | "max_iterations" | "aborted" | "mistake_limit" | "error"
  text: string
  iterations: number
  usage?: LegacyAgentUsage
}
```

## Usage Event

```typescript theme={"system"}
interface AgentUsageEvent {
  type: "usage"
  inputTokens: number
  outputTokens: number
  cacheReadTokens?: number
  cacheWriteTokens?: number
  cost?: number
  totalInputTokens: number
  totalOutputTokens: number
  totalCacheReadTokens?: number
  totalCacheWriteTokens?: number
  totalCost?: number
}
```

## CoreSessionEvent

`ClineCore.subscribe(listener, options?)` emits session-level events from the runtime host.

```typescript theme={"system"}
const unsubscribe = cline.subscribe((event) => {
  console.log(event.type, event.sessionId)
}, { sessionId })
```