Agent Sessions
An agent session is one queued unit of work. A claim is the active lease that lets one eligible agent execute that session.
Keeping sessions and claims separate prevents duplicate sessions and makes agent progress visible before the underlying initiative, bug, or todo changes state.
Queued work is not running
Creating a session only puts work in the queue. An agent can start only after it claims the queued initiative, bug, or todo.
Monitor sessions in the dashboard
Open Work queue from the main menu or the desktop title bar to see queued, running, and recently finished sessions without leaving the current page. The badge shows how many sessions are queued or active. Select a row to open the session, choose Manage agents in the panel header to open the Agents overview, or choose View all at the bottom of the panel.
The list shows up to ten sessions. Recently finished sessions stay visible for about eight hours before they drop off the list. That cleanup is automatic; archive is a manual action that hides a finished session immediately.
Archive finished sessions
Archive hides a finished session from session lists in Agent queue, agent session tables, and the Agents area. The underlying initiative, bug, or todo and its activity history stay in place.
Archive is available when a session is complete, error, cancelled, or stale. Pending, queued, running, or awaiting-input sessions must finish or be cancelled before you can archive them manually.
Open the session actions menu on a finished session and choose Archive. Confirm when prompted. Archived sessions leave the list immediately and cannot be restored from the dashboard.
Try again queues a replacement run with the same work item, agent, prompt, and target agent when one was set. On stale, error, or cancelled sessions, and on queued or pending sessions, the dashboard archives the previous session after the replacement is created. Queued or pending sources are cancelled with the reason Retried by user before archival. Try again on a complete session leaves the finished session in the list until you archive it or it ages out of Work queue.
Session list APIs exclude archived sessions. Agents cannot claim an archived session.
For Codex local sessions that include a thread ID, Open in Codex appears in Work queue, on session details (including as the primary action), or in the session actions menu. See Codex for deep links and troubleshooting.
For Claude Code local runs with a session ID when the status is complete or error, Open in Claude Code appears in the run menu only—not in Work queue or as a primary button on run details. It resumes the recorded session in the task workspace folder. The action appears only when the session status is complete or error so it does not start a separate interactive session while work is still running. See Claude Code for MCP setup and local agent details.
What a session stores
| Area | What it stores |
|---|---|
| Scope | Workspace, agent, execution mode, and initiating user. |
| Local ownership | The signed-in owner when the session must run on that owner's machine. |
| Target work | The initiative, bug, or todo the agent was asked to handle. |
| Routing | Optional target agent or target group that limits which agents may claim the session. |
| Delegation | Optional parent session ID when one session queued follow-up work for another agent or group. |
| Instructions and context | The prompt, trusted instructions, and untrusted work context. |
| Session state | Active claim ID, plan text, external URL, pending resume input when someone replies to an input request, error message, and timestamps. |
| Provider linkage | Provider thread, turn, and process session IDs when the agent reports them. For Codex local sessions, the thread ID powers Open in Codex. |
| Session metadata | Model, model provider, working directory, worktree path, provider session status, and token usage (input, cached input, output, reasoning output, total, and context window) when the agent reports them during execution. Session details show total, input, and output token counts only after the session reaches a terminal state: complete, error, stale, or cancelled. |
Desktop, CLI agents, and custom agents use the same lifecycle. Starting a local agent from Desktop does not bypass claims; it starts a process that can heartbeat, poll, and claim sessions for the signed-in owner.
Session states
| State | Meaning |
|---|---|
queued | Waiting for an eligible agent to claim it. |
pending | Accepted by the platform but not ready to execute yet. |
active | An agent holds an active claim and is executing. |
awaiting_input | The agent paused and needs a user reply before it can continue. |
complete | Work finished successfully. |
error | Work failed or could not be completed. |
stale | An agent stopped heartbeating or the claim expired. |
cancelled | The user or system cancelled the session. |
Claim rules
A claim is scoped to one workspace, agent, agent, and session. It proves that an agent can run that session right now.
When a agent claims a session, the platform checks the basic boundaries before the agent can run.
Same workspace and agent
The agent must belong to the same workspace and agent as the session.
Matching execution mode
A local agent can claim local sessions. A cloud agent can claim cloud sessions.
Local owner
For local sessions, the signed-in user must own the agent.
Target agent
If the session specifies a target agent, only that agent may claim it. Sessions created through the Send to launcher for a specific agent destination are automatically targeted. Untargeted sessions are claimable by any eligible agent for that agent.
Target group
If the session specifies a target group, only agents whose group ID matches may claim it. Set targetWorkerId or targetGroupId, not both. Agents without a group cannot claim group-targeted sessions.
No active claim
Only one active claim can exist for a session. Stale claims can expire or be released before a new claim starts.
Stale session ownership
When a session is stale, only the agent that made the most recent claim can claim it again. Poll requests that include stale sessions return only sessions last claimed by that agent. Use Try again in the dashboard to queue a new session when you want a different agent or a fresh session.
Pass leaseSeconds in the claim request to control how long the lease is valid. The default is 900 seconds. If the lease expires before the agent completes or fails, the platform can mark the session stale. Only the agent that made the most recent claim can reclaim that stale session.
Every session update must include the active claimId. Activities, metadata updates, completion, failure, and release calls without the active claim ID are rejected.
Agent-to-agent delegation
A running agent can queue follow-up work for another agent or group by creating a child session with delegatingSessionId set to the parent session ID. The child session inherits the parent workspace, agent, execution mode, and local owner.
Set exactly one routing target on the child session:
targetWorkerIdto hand work to one specific agenttargetGroupIdto hand work to any online agent in that group
Delegated sessions are separate queued sessions with their own claims. They do not reuse the parent session's claim, and the platform creates a distinct child session for each delegation even when the same task already has another open session.
The platform emits an agent.session_delegated webhook when a delegated session is created. Agents still poll and claim delegated sessions through the REST API.
Resume when a session awaits input
When an agent marks a session awaiting_input, the session pauses until someone sends a reply. In the dashboard, choose Resume on the session in Work queue, on the session detail page, or in the Agents area. Enter your reply in the Resume session dialog and confirm.
The reply can be up to 20,000 characters. The platform stores it as pending resume input, keeps the active claim, and refreshes the claim lease. The owning agent must be online; if it is offline, resume fails until that agent heartbeats again. Only one pending reply can be queued at a time.
The owning agent consumes pending resume input on its next poll and continues the session. Custom agents should treat an awaiting_input session with pending resume input as a resume activation rather than a new claim. OAuth clients can queue the same input with POST /api/v1/workspaces/{workspaceId}/agents/{agentId}/sessions/{sessionId}/resume.
By default, an awaiting-input pause does not change the linked initiative, bug, or todo status and does not post a task comment. Agent blueprints can configure a different status or comment behavior when they need it.
Activities
Agents emit activities for progress that belongs in the dashboard or audit history:
progressplan_updatedexternal_url_updatedawaiting_inputuser_resume_inputcompletedfailedpolicy_decision
Activities are visible progress events. Heartbeats only show that the agent is alive and should not be used as progress updates.
Use session metadata for plan text, external URLs, input requests, and error messages.
Complete, fail, or release
Complete a session when the work succeeds. Fail it when the agent cannot finish and the session should be marked as errored. Release it when the agent stops before doing useful work or decides another eligible agent should retry. Release puts the session back to queued for any eligible agent; it does not mark the session stale.
Workflow review sessions also carry the route decision. Set reviewVerdict to approve, feedback, or reject before marking the session completed, or the workflow run stalls instead of choosing a route.
If a agent misses heartbeats for 12 seconds, the platform marks the agent stale. After 5 minutes without a heartbeat, the agent is marked offline, active claims are expired, and affected sessions become stale. The agent that last claimed each session can reclaim it when it polls again. Use Try again in the dashboard to queue a new session on a different agent.
Work state updates
Agent blueprints can apply state transitions from session lifecycle events. Agents do not need to write those state changes directly.
| Session event | Default state |
|---|---|
| Session claimed | In Progress |
| Session completed | In Review |
| Session awaiting input | No change by default. Blueprints can set Blocked or another status. |
| Retries exhausted | Blocked |
Agent runtime configuration can narrow allowed updates, but it cannot expand beyond the blueprint permissions.
Human review
Treat completed sessions as delivery evidence, not automatic approval. Check the resulting code, tests, pull request, comments, or linked external URL before marking the underlying work done.
For built-in local execution, read Local Agents. For custom integrations, choose Build a Local Agent or Build a Cloud Agent.