Lifecycle

A session is a conversation with an agent. It can span multiple executions, each with its own sandbox, and multiple turns of work. Platform events describe those transitions; harness events contain the agent's messages and tool activity.

Start

session_scheduled means the session is queued. message_received records an accepted message, including the initial prompt when one is provided.

session_starting begins an execution. Sandbox events report provisioning and setup, ending with sandbox_ready when the workspace is ready for the harness.

Work

turn_started begins a turn. message_delivered associates an inbox message with that turn.

During the turn, Claude Code publishes assistant records containing text, reasoning, and tool calls, with tool results in user records. Codex publishes item/started and item/completed notifications for messages, tool activity, and other items.

Claude Code can also publish system notifications for Git activity, such as a push. These report activity within the turn without changing its lifecycle state.

turn_completed marks the end of a platform turn. The harness also publishes its own completion event: Claude Code's result or Codex's turn/completed. A completed turn can leave the session open for follow-up messages.

Continue

A follow-up message waits if a turn is already running. When the agent is ready, the next turn delivers the message and continues the conversation.

session_idle means the conversation has been parked after its warm execution ended. A later message starts another execution and session_resumed reports the restored conversation. The session keeps the same ID and transcript across executions.

Finish or recover

session_closed ends the conversation. Read the session's status, session_state, and exit_status for its state and outcome. On the live stream, these arrive in session frames; a done frame ends the stream when the session is terminal.

turn_failed reports a failed turn. Recovery can produce message_requeued and session_retrying. A session cancelled before an execution starts produces session_cancelled. Check the session state before deciding whether work will continue.

Follow the stream

Connect with the Python SDK or TypeScript SDK. A snapshot frame supplies the initial state, and records_append frames deliver the ordered event history. Temporary delta frames provide live text and token updates while complete records are being produced.

Events can repeat, interleave, or be absent depending on the harness and outcome. Order stored records by feed_seq and use it as the reconnect cursor.

See the Session events reference for the complete catalog, example JSON, and expandable field specifications for each event and stream frame.