Skip to main content

Module protocol

Module protocol 

Source
Expand description

Wire types for the Claude Code stream-json protocol. Source: the Claude Code 2.1.328 binary’s zod schemas and the official Python SDK (claude_agent_sdk 0.1.48); citations are on the types they cover.

Structs§

AssistantMessage
AssistantMessageBody
BackgroundTask
One entry of a background_tasks_changed snapshot. Source: binary background_tasks_changed schema
BackgroundTasksRequest
Body of a background_tasks control request (Ctrl+B equivalent). Send with Session::control(&body). Source: chunk-20bv8pca.js:20970–20978
CanUseToolRequest
Source: binary can_use_tool schema; query.py:244–262
ControlCancelRequest
Source: binary control_cancel_request schema
ControlRequest
CLI → host control request envelope: {"type":"control_request","request_id":"…","request":{"subtype":"…",…}}. Source: query.py:236–240
ControlResponse
Envelope for every host → CLI answer to a CLI-initiated control request. Source: query.py:325–345
ElicitationRequest
Source: binary elicitation schema
ElicitationResponse
Answer to an elicitation request. Source: binary elicitation response schema
HookCallbackRequest
Source: binary hook_callback schema (callback_id, input, tool_use_id, issued_at)
HookEventPayload
Input to a hook handler. Contains all event-specific fields. Source: chunk-0msz7hbn.js:7–323
HookMatcherConfig
One hook matcher in the initialize request. Source: query.py:142–147 (matcher, hookCallbackIds, timeout)
HookOutput
Hook result — the same JSON a shell hook prints on stdout. Source: binary hook-output schema (continue, suppressOutput, stopReason, decision, systemMessage, reason, hookSpecificOutput).
InboundControlResponse
CLI → host answer to a host-initiated control request. Source: query.py:180–192
InboundControlResponseBody
InboundToolResult
One tool_result block of a user frame.
InboundUserBody
InboundUserMessage
A user frame: the echo of a prompt, tool results, or a message the CLI added itself (is_synthetic).
Initialize
Body of the initialize control request — the first stdin line.
KeepAliveMessage
Process keepalive with startup marker for readiness probing. Source: chunk-f89nsf5q.query.js:1403–1410
McpManifest
McpMessageRequest
OutboundControlRequest
Envelope for every host → CLI control request: {"type":"control_request","request_id":"…","request":{"subtype":"…",…}}. Source: query.py:368–372
ResultMessage
Turn complete. Source: chunk-20bv8pca.js:14425–14913
StreamEventMessage
Partial streaming chunk. Source: chunk-20bv8pca.js:15343–15401
SystemMessage
Every type:"system" frame: init (first frame of each turn) plus hook_started, hook_response, compact_boundary, model_fallback, background_tasks_changed, task_started, task_updated, task_notification, thinking_tokens, model_refusal_no_fallback, peer_message_hold, … — only subtype and session_id are common to all; subtype-specific fields are in extra. Source: binary system-message schemas Source: chunk-hp1k7mph.js:194 (WGt function), chunk-20bv8pca.js:15125
ToolAnnotations
MCP tool hints. Source: MCP 2025-06-18 ToolAnnotations
ToolDef
UsageSummary
Token usage breakdown. Source: chunk-20bv8pca.js:11526–11530
UserDialogRequest
Source: binary request_user_dialog schema
UserDialogResponse
The user’s answer to a request_user_dialog. Source: binary request_user_dialog response schema (behavior, result)
UserMessage
A user turn. Source: _internal/client.py:126–131
UserMessageBody
WorkspaceTrust
Send accepted: true only after the user accepted a trust dialog for directory. Source: binary initialize.workspaceTrust schema

Enums§

AssistantBlock
Autocompact
--autocompact: when the CLI compacts the context on its own.
ContentBlock
ControlRequestBody
ControlResponseBody
DocumentSource
Anthropic Messages API document source.
Effort
Effort levels accepted by --effort and set_effort. Source: claude --help (2.1.329)
ElicitationAction
HookDecision
HookEventKind
All 33 hook event kinds. Source: chunk-20bv8pca.js:12053–12087 (N2 array)
ImageSource
Anthropic Messages API image source.
InboundMessage
Every stdout line deserializes to this. Source: chunk-20bv8pca.js (various schema locations)
PermissionMode
Permission modes accepted by --permission-mode and set_permission_mode. Source: binary permission-mode enum
PermissionPrompts
--permission-prompts: who answers a permission prompt.
Priority
When a prompt sent during a running turn is taken in. Source: binary user-message priority enum
Thinking
--thinking. Source: binary --thinking <mode> option (hidden)
ThinkingDisplay
How thinking content appears (--thinking-display, set_max_thinking_tokens). Source: binary thinking-display enum
ToolDecision
Answer to a can_use_tool request. Source: binary can_use_tool response schema (behavior, updatedInput, updatedPermissions, message, interrupt)
TurnErrorKind
Why a turn failed. Source: binary result error-subtype enum
UserDialogBehavior