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 execution and makes progress durable before the linked 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.

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.

The state machine returns released work to the queue without marking it failed.

stateDiagram-v2
  [*] --> queued
  queued --> active: claim
  active --> awaiting_input: request input
  awaiting_input --> active: resume
  active --> complete: complete
  active --> error: fail
  active --> stale: heartbeat or claim expires
  active --> cancelled: cancel
  active --> queued: release
  stale --> active: previous agent reclaims
  complete --> [*]
  error --> [*]
  cancelled --> [*]

Graph

Claim rules

A claim is scoped to one workspace, agent profile, runtime, and session. It proves that one runtime can execute that session now.

When an agent claims a session, the platform checks the basic boundaries before the agent can run.

Targeting rule	Eligibility
Workspace and agent profile	Runtime and session must share both.
Execution mode	Local runtimes claim local sessions; cloud runtimes claim cloud sessions.
Local owner	The authenticated user must own the local runtime and session.
`targetWorkerId`	Only that runtime can claim the session.
`targetGroupId`	Any eligible runtime in that group can claim the session.
Stale ownership	Only the runtime with the most recent claim can reclaim a stale session.

Set targetWorkerId or targetGroupId, not both. Choosing a specific agent in Send to sets the agent target automatically; an untargeted session can be claimed by any otherwise eligible agent for the agent profile.

Only one active claim can exist for a session. A stale claim must expire or be released before another claim starts. To move stale work to a different agent, use Try again in the dashboard to create a new 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.

The claim ID is the mutation boundary after execution starts.

Every mutation after claim must include the active claimId. Stop execution and reload the session when the platform rejects it; another runtime may own the current claim.

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:

targetWorkerId to hand work to one specific agent
targetGroupId to 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:

Activity	Meaning
`progress`	Reports a user-visible execution update.
`plan_updated`	Records a new or revised plan.
`external_url_updated`	Records an external resource such as a pull request.
`awaiting_input`	Records that execution paused for a user reply.
`user_resume_input`	Records the reply used to resume execution.
`completed`	Records successful execution.
`failed`	Records failed execution.
`policy_decision`	Records a policy restriction enforced by the runtime.

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

Action	When to use it	Result
`complete`	The work succeeded.	Marks the session `complete`.
`fail`	The agent cannot finish the work.	Marks the session `error`.
`release`	The agent stops before useful work or another eligible agent should retry.	Returns the session to `queued` without marking it `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 an agent misses heartbeats for 30 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.

Dashboard recovery actions belong in Monitoring. For custom execution, choose Build your own agent or Build a cloud agent.

Frequently asked questions

Monitoring

Inspect workflow runs, queued sessions, review gates, recovery actions, and agent health.

Build cloud agent

Implement an always-on runtime with webhook notification, polling recovery, claims, and terminal outcomes.

Limits & security

Enforced restrictions on what a custom agent can send into One Horizon, what it receives back, uploads, authentication scope, and rate limits.

MCP tools

Every MCP tool the worker runtime can register for a turn, generated straight from the runtime tool catalog.