Overview
Session updates are sent from agents to clients viaSessionNotification to provide real-time feedback during prompt processing. Each update type carries different information about the agent’s progress.
See Agent Reports Output in the protocol documentation.
Message Updates
UserMessageChunkSessionUpdate
Streams content that is part of the user’s message (typically when loading a session).A content block from the user’s message (text, image, audio, resource, etc.)
AgentMessageChunkSessionUpdate
Streams content that is part of the agent’s response.A content block from the agent’s message (text, image, audio, resource, etc.)
AgentThoughtChunkSessionUpdate
Streams the agent’s internal thoughts or reasoning process.A content block containing the agent’s internal thoughts (typically text)
Tool Call Updates
ToolCallSessionUpdate
Creates a new tool call. See Tool Calls.Unique identifier for this tool call
Display title for the tool call
The kind of operation:
read, edit, delete, move, search, execute, think, fetch, switch_mode, or otherCurrent status:
pending, in_progress, completed, or failedContent produced by the tool call. Can include:
ContentToolCallContent- Standard content blocks (text, images, etc.)DiffToolCallContent- File diffsTerminalToolCallContent- Terminal output references
File locations being accessed or modified
Raw input parameters for the tool
Raw output from the tool
Optional metadata
ToolCallUpdateSessionUpdate
Updates an existing tool call (identified bytoolCallId).
The ID of the tool call to update
Updated display title
Updated operation kind
Updated status
Additional or updated content
Updated file locations
Updated raw input
Updated raw output
Optional metadata
Plan Updates
PlanSessionUpdate
Updates the agent’s execution plan. See Agent Plan.The complete list of plan entries
Optional metadata
Commands Update
AvailableCommandsUpdateSessionUpdate
Updates the list of commands available to the user.List of available commands
Optional metadata
Mode Update
CurrentModeUpdateSessionUpdate
Notifies about a mode change in the session.The ID of the newly active mode
Optional metadata
Configuration Update
ConfigOptionUpdate
Updates session configuration options.The updated list of configuration options
Optional metadata
Session Info Update
SessionInfoUpdate
Updates metadata about the session itself.Updated session title
When the session was last updated (ISO 8601 timestamp)
Optional metadata
Usage Update
UsageUpdate
Provides information about resource usage (e.g., context window).Total size of the resource (e.g., maximum context window size)
Amount currently used
Associated cost information
Optional metadata
Unknown Updates
UnknownSessionUpdate
A fallback type for session updates that don’t match any known type. This ensures forward compatibility when new update types are added to the protocol.The raw JSON data for the unknown update type
Clients should handle
UnknownSessionUpdate gracefully to maintain compatibility with future protocol versions.