Session status

​

Elevator pitch

What are you proposing to change?

• Active: the Agent has this session in memory right now.
• Inactive: the Agent knows this session and it can be resumed, but it is not in memory.
• Unknown: the Agent does not know this session. This is returned as a -32002 error.

​

Status quo

How do things work today and what problems does this cause? Why would we change things?

• session/new creates a session.
• session/load and session/resume make the Agent start handling a session for the connection that sent them. In v2, session/load is gone and replay is a replayFrom option on session/resume.
• session/close cancels a session’s work and frees its resources.

• A routing layer runs several Agent instances. It needs to find which instance has a session before it forwards a session/resume. Sending session/resume to an instance just to find out loads the session there, so two instances could end up running the same session.
• A Client reconnects over a long-lived transport. After a network drop, it wants to know whether the session is still in memory or the Agent restarted, before deciding how to recover and what to show the user.
• A Client checks a session ID before using it. Today an unknown ID only shows up as an error from whichever method it used first, and there is no shared error code for it.

​

What we propose to do about it

What are you proposing to improve the situation?

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/status",
  "params": {
    "sessionId": "sess_abc123"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "active"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "inactive"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32002,
    "message": "Resource not found",
    "data": {
      "sessionId": "sess_abc123"
    }
  }
}

​

Status values

• active: The Agent has this session in memory, for any connection. This does not mean the requesting connection is attached to it. A Client that did not create or resume the session on its own connection MUST still call session/resume (or session/load in v1) before sending session/prompt or expecting session/update notifications.
• inactive: The Agent knows the session and can resume it, but it is not in memory. The Client can call session/resume (or session/load in v1) to start it.

​

Foreground state (v2)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "active",
    "state": {
      "state": "requires_action"
    }
  }
}

• state is optional. If it is omitted, null, or malformed, the Agent is not reporting foreground state. Clients MUST NOT read that as idle.
• Like the snapshot session/resume sends, this is a snapshot. It is not a new transition, completion, or usage report. An idle snapshot may carry the last stopReason for context, and Clients MUST NOT count it as a new completion.
• v1 has no foreground state model, so the v1 response has no state field.

​

Errors

​

Contract

• session/status MUST NOT have side effects. It must not load, resume, create, close, or change the session, and it must not attach the requesting connection to it.
• Checking whether a session is active SHOULD be cheap (an in-memory lookup), and Clients may call it often, for example as a routing probe.
• Telling inactive apart from unknown may require a storage lookup. If an Agent cannot do that cheaply, it MAY return inactive for any session it does not have in memory. A later session/resume will then fail with -32002 if the session does not exist.
• The result is a snapshot. A session reported active may be closed or evicted before the Client’s next request, so Clients MUST still handle errors from later session methods.

​

Shiny future

How will things will play out once this feature exists?

• Routing layers ask each Agent instance for session/status to find the one with the session active, and send session/resume there instead of loading it on the wrong instance.
• Clients reconnecting over a long-lived transport can tell “the Agent still has my session” from “the Agent restarted and the session needs resuming”, and show the right thing right away.
• v2 Clients and dashboards can show whether a session is working, idle, or waiting on the user without attaching to it. For example, they can surface a session blocked on a permission request elsewhere.
• Agents report unknown session IDs with one error code, which other session methods can adopt too.

​

Implementation details and plan

Tell me more about your implementation. What is your detailed implementation plan?

​

Capability

{
  "agentCapabilities": {
    "sessionCapabilities": {
      "status": {}
    }
  }
}

{
  "capabilities": {
    "session": {
      "status": {}
    }
  }
}

​

Schema

• SessionStatusRequest: sessionId (required), _meta (optional).
• SessionStatusResponse: status (required), _meta (optional). In v2 only, it also has state (optional StateUpdate, deserialized with DefaultOnError, since a fallback just means no foreground state was reported).
• SessionStatus: string enum, active | inactive, open to future values (see the unrecognized-value rule above).
• SessionStatusCapabilities: empty object with optional _meta, added as status on the v1 SessionCapabilities and the v2 session capabilities.

​

Plan

1. Add the method behind an unstable_session_status feature flag in the v1 and v2 schemas.
2. Document it in the session setup docs, including the -32002 error.
3. Implement it in at least one Agent and one routing layer or Client before stabilizing.

​

Frequently asked questions

What questions have arisen over the course of authoring this document or during subsequent discussions?

​

Why not just call session/resume?

​

Why is an unknown session an error instead of a not_found status?

​

Does active mean I can send session/prompt right away?

​

Why not add this to session/list?

​

Why is foreground state v2-only?

​

Should the response include the session’s current position?

​

What alternative approaches did you consider, and why did you settle on this one?

• Transport-level heartbeats: these only show the connection is alive, not that the Agent still has a particular session.
• Probing with session/resume: this has side effects (see above).
• Two states, with unknown sessions as a not_found status: this merges “can be resumed” with “never existed”, which a reconnecting Client needs to tell apart. It also reports unknown IDs differently from other session methods.

​

Revision history

• 2026-10-26: Reworked to three states (active / inactive / -32002 error), dropped the live naming so it isn’t confused with v2 turn state, pointed recovery at session/resume, added v2 capability and connection semantics, added a v2-only state foreground snapshot on active responses, and made the contract a snapshot rather than a guarantee.
• 2026-04-15: Initial draft.