After a session is created, its execution flow can be controlled via a state machine, tool call approvals, and interruption mechanisms—and archived or deleted upon task completion.
State Machine
The session status appears at the top of the page. The table below outlines the trigger conditions, next states, and available actions for each status:
| Status | Trigger Condition | Next Status | Available Actions |
|---|---|---|---|
idle (interactive: stop_reason is null / end_turn / retries_exhausted) | Session just created (null), one round finished (end_turn), or retries exhausted (retries_exhausted) | On receiving a message → running; On archiving or deletion → terminated | Send message, attach files, archive, delete |
idle (stop_reason=requires_action) | An always_ask tool approval was triggered and is awaiting a decision | Once all decisions are collected → running; interrupt → ends the current approval batch | Submit approvals (tool_approval_response), interrupt (interrupt); a plain message cannot continue the turn |
running | Message received and agent begins processing | On completion → idle; On approval trigger → idle (requires_action); On unrecoverable error → terminated | Interrupt |
terminated | Archived, deleted, or unrecoverable error occurred | Terminal state—no further transitions possible | View event history; create a new session to continue |
idle, the session_status event (and GET /sessions/{session_id}) carries a stop_reason indicating why. stop_reason only determines the interaction state while the session is idle: null when just created with no end reason yet, otherwise end_turn, retries_exhausted, or requires_action. It is null while running; terminated is a terminal state — clients should not depend on or interpret its stop_reason. The client should map the four idle projections to UI actions per the table below, deciding interactivity by whether it is requires_action — not by idle alone:
stop_reason | Meaning | Plain message allowed | Approve / interrupt |
|---|---|---|---|
null | Session just created, not yet processed | Allowed | No pending approval |
end_turn | The model voluntarily ended the turn | Allowed | No pending approval |
retries_exhausted | Retries exhausted, the turn is over | Allowed | No pending approval |
requires_action | Pending always_ask approvals; carries pending_batch_id / pending_call_ids | Forbidden (sending one alone yields pending_tool_approval_unresolved) | Submit approvals / send interrupt |
- Interactive
idle(null/end_turn/retries_exhausted): no approval barrier exists; you may send a plain message to start a new turn. requires_action: you may only submit approvals or sendinterrupt. After partial decisions the state staysrequires_actionandpending_call_idsshrinks to the remaining calls; only once all are collected does it return torunning. Sending a plain message alone here does not continue processing and yieldspending_tool_approval_unresolved; the legalinterrupt+ plainmessagecombination is handled as defined in Session Event Stream.
Tool Calls
The agent autonomously decides when and which tool to invoke based on system prompts and the current message. All tools—built-in, MCP, or skills—are executed within the runtime environment bound to the session, and their invocation process is visible in real time via the event panel.
Invocation Flow
- Agent Decision: The model outputs a tool call instruction. The event panel displays a Tool Call event containing the tool name and parameters.
- Approval Branch:
always_allowtools: proceed directly to execution without blocking.always_asktools: emit atool_approval_request, and the session entersidle(stop_reason=requires_action) awaiting decisions. Approved (allow) calls run only after all decisions for the batch are collected; a partial decision leaves the session inrequires_action, and noalways_asktool in the batch runs until then. Adenycall does not run and returns a tool output withis_errorset totrue, withdeny_messageas the error content sent back to the model. Approval covers only thealways_askset —always_allowtools may execute before approval completes.
- Execution: The tool runs inside a sandbox; its output is sent back to the model.
- Response or Continue: The model decides whether to reply or initiate another tool call, based on the tool’s output.
Archiving and Deletion
Sessions support two distinct operations: archiving and deletion.
- Archiving: Changes the session status to
terminated(a terminal state), while preserving the full event history for future reference. Recommended for completed sessions. - Deletion: Permanently removes all session metadata, event history, and internally copied resources—this action is irreversible. Use archiving instead if you need to retain event history.
Next Steps
- Session Event Stream (SSE): Learn about all event types and how to subscribe via SSE.
- Defining an Agent: Customize your agent’s model, prompts, and toolset.
- Cloud Hosting Environment: Configure the sandbox where tool calls execute.