Pi --mode json event cheatsheet

pi --print --mode json writes one JSON object per line (JSONL) with a required type field. These are AgentSessionEvent objects from @mariozechner/pi-agent-core.

Top-level event lines#

session (header, pi >= 0.45.1)#

{"type":"session","id":"ccd569e0-4e1b-4c7d-a981-637ed4107310","version":3,"timestamp":"2026-01-13T00:33:34.702Z","cwd":"/repo"}

agent_start#

{"type":"agent_start"}

agent_end#

{"type":"agent_end","messages":[{"role":"assistant","content":[{"type":"text","text":"Done."}],"stopReason":"stop","timestamp":123}]} 

turn_start / turn_end#

{"type":"turn_start"}

{"type":"turn_end","message":{...},"toolResults":[...]} 

message_start / message_update / message_end#

{"type":"message_start","message":{"role":"assistant","content":[{"type":"text","text":"Working..."}]}}

{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","delta":"...","contentIndex":0}} 

{"type":"message_end","message":{"role":"assistant","content":[{"type":"text","text":"Done."}],"stopReason":"stop"}}

tool_execution_start#

{"type":"tool_execution_start","toolCallId":"tool_1","toolName":"bash","args":{"command":"ls"}}

tool_execution_update#

{"type":"tool_execution_update","toolCallId":"tool_1","toolName":"bash","args":{"command":"ls"},"partialResult":{"content":[{"type":"text","text":"..."}]}} 

tool_execution_end#

{"type":"tool_execution_end","toolCallId":"tool_1","toolName":"bash","result":{"content":[{"type":"text","text":"ok"}],"details":{}},"isError":false}

auto_compaction_start#

{"type":"auto_compaction_start","reason":"context_limit"}

auto_compaction_end#

{"type":"auto_compaction_end","result":{"tokensBefore":42000},"aborted":false}

auto_retry_start / auto_retry_end#

{"type":"auto_retry_start","attempt":2,"maxAttempts":5,"delayMs":1500,"errorMessage":"503"}

{"type":"auto_retry_end","success":true,"attempt":2}

On failure auto_retry_end carries "success":false and finalError.

Notes#

• message_end with role = "assistant" contains the final assistant text.
• assistantMessageEvent in message_update provides streaming deltas.
• tool_execution_* events map cleanly to Untether action events.