Expand description
Wire types for the Claude Code stream-json protocol.
Source: the Claude Code 2.1.329 binary’s zod schemas and the official
Python SDK (claude_agent_sdk 0.1.48); citations are on the types they cover.
Structs§
- Assistant
Message - A complete
assistantframe. - Assistant
Message Body - Body of an
assistantframe. - Background
Task - One entry of a
background_tasks_changedsnapshot. Source: binarybackground_tasks_changedschema - Background
Tasks Request - Body of a
background_taskscontrol request (Ctrl+B equivalent). Send withSession::control(&body). Source: chunk-20bv8pca.js:20970–20978 - CanUse
Tool Request - Source: binary
can_use_toolschema; query.py:244–262 - Control
Cancel Request - Source: binary
control_cancel_requestschema - Control
Request - CLI → host control request envelope:
{"type":"control_request","request_id":"…","request":{"subtype":"…",…}}. Source: query.py:236–240 - Control
Response - Envelope for every host → CLI answer to a CLI-initiated control request. Source: query.py:325–345
- Elicitation
Request - Source: binary elicitation schema
- Elicitation
Response - Answer to an
elicitationrequest. Source: binary elicitation response schema - Hook
Callback Request - Source: binary
hook_callbackschema (callback_id, input,tool_use_id,issued_at) - Hook
Event Payload - Input to a hook handler. Contains all event-specific fields. Source: chunk-0msz7hbn.js:7–323
- Hook
Matcher Config - One hook matcher in the initialize request.
Source: query.py:142–147 (
matcher,hookCallbackIds,timeout) - Hook
Output - Hook result — the same JSON a shell hook prints on stdout. Source: binary hook-output schema (continue, suppressOutput, stopReason, decision, systemMessage, reason, hookSpecificOutput).
- Inbound
Control Response - CLI → host answer to a host-initiated control request. Source: query.py:180–192
- Inbound
Control Response Body - Body of an inbound
control_response. - Inbound
Tool Result - One
tool_resultblock of auserframe. - Inbound
User Body - Body of an inbound
userframe. - Inbound
User Message - A
userframe: the echo of a prompt, tool results, or a message the CLI added itself (is_synthetic). - Initialize
- Body of the
initializecontrol request — the first stdin line. - Keep
Alive Message - Process keepalive with startup marker for readiness probing. Source: chunk-f89nsf5q.query.js:1403–1410
- McpManifest
- An MCP server’s name and tools.
- McpMessage
Request - Body of an
mcp_messagerequest. - Outbound
Control Request - Envelope for every host → CLI control request:
{"type":"control_request","request_id":"…","request":{"subtype":"…",…}}. Source: query.py:368–372 - Result
Message - Turn complete. Source: chunk-20bv8pca.js:14425–14913
- Stream
Event Message - Partial streaming chunk. Source: chunk-20bv8pca.js:15343–15401
- System
Message - Every
type:"system"frame:init(first frame of each turn) plushook_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, … — onlysubtypeandsession_idare common to all; subtype-specific fields are inextra. Source: binary system-message schemas Source: chunk-hp1k7mph.js:194 (WGtfunction), chunk-20bv8pca.js:15125 - Tool
Annotations - MCP tool hints. Source: MCP 2025-06-18
ToolAnnotations - ToolDef
- A tool of an in-process SDK MCP server.
- Usage
Summary - Token usage breakdown. Source: chunk-20bv8pca.js:11526–11530
- User
Dialog Request - Source: binary
request_user_dialogschema - User
Dialog Response - The user’s answer to a
request_user_dialog. Source: binaryrequest_user_dialogresponse schema (behavior, result) - User
Message - A user turn. Source: _internal/client.py:126–131
- User
Message Body - Message body:
roleplus content blocks. - Workspace
Trust - Send
accepted: trueonly after the user accepted a trust dialog fordirectory. Source: binary initialize.workspaceTrust schema
Enums§
- Assistant
Block - Content block of an assistant message.
- Autocompact
--autocompact: when the CLI compacts the context on its own.- Content
Block - Content block of a user message (Anthropic Messages API shape).
- Control
Request Body - Body of a CLI → host control request, tagged by
subtype. - Control
Response Body - Body of a
control_response, tagged bysubtype. - Document
Source - Anthropic Messages API document source.
- Effort
- Effort levels accepted by
--effortandset_effort. Source:claude --help(2.1.329) - Elicitation
Action - What the user did with an elicitation.
- Hook
Decision decisionof a hook result.- Hook
Event Kind - All 33 hook event kinds. Source: chunk-20bv8pca.js:12053–12087 (N2 array)
- Image
Source - Anthropic Messages API image source.
- Inbound
Message - Every stdout line deserializes to this. Source: chunk-20bv8pca.js (various schema locations)
- Permission
Mode - Permission modes accepted by
--permission-modeandset_permission_mode. Source: binary permission-mode enum - Permission
Prompts --permission-prompts: who answers a permission prompt.- Priority
- When a prompt sent during a running turn is taken in.
Source: binary user-message
priorityenum - Thinking
--thinking. Source: binary--thinking <mode>option (hidden)- Thinking
Display - How thinking content appears (
--thinking-display,set_max_thinking_tokens). Source: binary thinking-display enum - Tool
Decision - Answer to a
can_use_toolrequest. Source: binarycan_use_toolresponse schema (behavior,updatedInput,updatedPermissions,message,interrupt) - Turn
Error Kind - Why a turn failed. Source: binary result error-subtype enum
- User
Dialog Behavior - How a
request_user_dialogended.