Skip to content
claudestream.events
Updated Edit
On this page

Typed event dataclasses for every Claude Code stream output event, including assistant messages, tool use, permissions, and results.

#claudestream.events

claudestream.events
Event TypeDescription
SystemInitFirst event in the stream. Contains session metadata.
ApiRetryEmitted before retrying a failed API call.
CompactBoundaryEmitted when conversation history is compacted.
AssistantMessageComplete assistant response with content blocks.
ToolResultMessageTool execution results returned to the model.
AssistantTextSingle text block from an assistant message.
ToolUseSingle tool call from an assistant message.
ThinkingSingle thinking block from an assistant message.
ToolResultSingle tool result.
FileWriteDerived event emitted when a Write tool succeeds. Contains absolute path and content length.
FileEditDerived event emitted when an Edit or MultiEdit tool succeeds. Contains absolute path.
StreamDeltaPartial streaming token. Wraps a raw API streaming event.
ResultFinal event in a turn. Contains cost and usage summary.
BudgetThresholdFired when a budget threshold is crossed. Informational only -- does not stop the session.
RateLimitRate limit status change.
PermissionRequestPermission request from Claude Code. Surfaced when sandbox doesn't auto-resolve.
UserDialogRequestBlocking user dialog the CLI asks the host to render (e.g. AskUserQuestion). Always surfaced to the consumer; never auto-handled by the sandbox.
McpRequestMCP tool call request from Claude Code.
HookEventHook lifecycle event from Claude Code (emitted when include_hook_events is True).
UnknownEventForward-compatible event for unrecognized event types.
ControlResponseResponse to a control request (e.g. initialize, mcp_set_servers).

#claudestream.events

Typed event dataclasses for every Claude Code stream output event, including assistant messages, tool use, permissions, and results.

#Event

Base class for all stream events.

#SystemInit

First event in the stream. Contains session metadata.

#ApiRetry

Emitted before retrying a failed API call.

#CompactBoundary

Emitted when conversation history is compacted.

#TextBlock

A text content block from an assistant message.

#ToolUseBlock

A tool use content block from an assistant message.

#ThinkingBlock

An extended thinking content block from an assistant message.

#ToolResultBlock

A tool result content block from a tool result message.

#Usage

Token usage statistics. Semantics depend on context: per-call in AssistantMessage, cumulative across the session in Result.

#ContextCategory

One category of the model's context window (e.g. system prompt, messages, tools).

#ContextUsage

Snapshot of the model's context-window usage, returned by get_context_usage().

#AssistantMessage

Complete assistant response with content blocks.

#ToolResultMessage

Tool execution results returned to the model.

#AssistantText

Single text block from an assistant message.

#ToolUse

Single tool call from an assistant message.

#Thinking

Single thinking block from an assistant message.

#ToolResult

Single tool result.

#FileWrite

Derived event emitted when a Write tool succeeds. Contains absolute path and content length.

#FileEdit

Derived event emitted when an Edit or MultiEdit tool succeeds. Contains absolute path.

#StreamDelta

Partial streaming token. Wraps a raw API streaming event.

#delta_type

python
def delta_type(self) -> str | None

Returns 'text_delta', 'input_json_delta', etc.

#text

python
def text(self) -> str | None

Returns text content for text_delta events.

#partial_json

python
def partial_json(self) -> str | None

Returns partial JSON for input_json_delta events.

#event_type

python
def event_type(self) -> str | None

Returns the streaming event type (message_start, content_block_delta, etc.).

#Result

Final event in a turn. Contains cost and usage summary.

#BudgetThreshold

Fired when a budget threshold is crossed. Informational only -- does not stop the session.

#RateLimit

Rate limit status change.

#PermissionRequest

Permission request from Claude Code. Surfaced when sandbox doesn't auto-resolve.

#UserDialogRequest

Blocking user dialog the CLI asks the host to render (e.g. AskUserQuestion). Always surfaced to the consumer; never auto-handled by the sandbox.

#McpRequest

MCP tool call request from Claude Code.

#HookEvent

Hook lifecycle event from Claude Code (emitted when include_hook_events is True).

#UnknownEvent

Forward-compatible event for unrecognized event types.

#ControlResponse

Response to a control request (e.g. initialize, mcp_set_servers).

#AskResult

Complete response from a single ask() call.

#Type Aliases

ContentBlock is a union of the 4 content block types (TextBlock | ToolUseBlock | ThinkingBlock | ToolResultBlock) and serves as the element type of AssistantMessage.content. Each block carries typed data from one segment of an assistant response, and the union lets consumers use isinstance checks or pattern matching to dispatch on block kind without casting.

More tools from this site

  • claudewheel A TUI Claude Code Launcher that lets you have more than one profile, manage sessions lifecycle, pick the exact CC version, model to use (even older unlisted ones), pick which GitHub account to use, etc.
  • dirstat Fast, single-binary directory statistics CLI: every file under a tree grouped by format, with counts, sizes, and lines of code, as a colored terminal table or as JSON
  • fastware A batteries-included ASGI framework: msgspec JSON, a managed Granian server, dependency injection, SSE, WebSockets, auth, and a test client
  • go-toml-edit Zero-dep TOML editing library for Go with comment preservation
  • howmuchleft The fastest Claude Code statusline: context window, 5-hour, and weekly limit usage as three customizable gradient bars, rendering in about 6 ms
  • orxtra
  • pgdesign
  • predraw Declarative rendering pipeline: describe a scene in JSON and get SVG, PNG and WebP out, with light and dark style tokens, reusable components and text converted to path outlines
  • reposummary Turn a git repository's history into a Markdown journal: pick a time window or revision range and get a readable digest of what changed, optionally narrated by an LLM
  • rlsbl Release orchestration and project scaffolding CLI that bumps versions, validates a structured JSONL changelog, tags only the commit CI verified, and publishes to npm, PyPI, Go and more
  • safegit git wrapper CLI that gives each commit its own temporary index and retries ref updates on conflict, so concurrent agents share one repository
  • saferm Command-line replacement for rm that archives every deletion with a mandatory reason and the context it ran in, so deleted files can be listed, inspected and restored
  • selfdoc Static Site Generator that builds a project's documentation site directly from its source code, so the docs can never drift from the code they describe, with SEO/AEO, first-class blog, search, and cross-project linking built in
  • strictcli
  • stricttest An always-on test-isolation floor: a pytest plugin and a Go env-hygiene module that make a test suite structurally unable to reach real credentials, the real HOME, the network, or the development repository.
  • wesktop A Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview
Search