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).

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

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

Usage Event

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.

const unsubscribe = cline.subscribe((event) => {
  console.log(event.type, event.sessionId)
}, { sessionId })