session/list method returns the sessions an Agent knows about. Clients use it to show session history and let users switch between sessions.
Agents can also send a session_info_update notification when a session’s title or metadata changes, so Clients don’t have to poll.
Before listing sessions, Clients MUST first complete the initialization phase to verify the Agent supports this capability.
Checking support
Before attempting to list sessions, Clients MUST verify that the Agent supports this capability by checking thesessionCapabilities.list field in the initialize response:
sessionCapabilities.list is not present, the Agent does not support listing sessions and Clients MUST NOT attempt to call session/list.
Agents that also advertise sessionCapabilities.additionalDirectories may
include additionalDirectories in returned SessionInfo objects to report
additional workspace roots for listed sessions.
If the Agent advertises the
sessionCapabilities.delete capability, Clients
can remove sessions from future session/list results with
session/delete.Listing sessions
Clients discover existing sessions by calling thesession/list method with optional filtering and pagination parameters:
params object returns the first page of sessions.
Filter sessions by working directory. Must be an absolute path. Only sessions
with a matching
cwd are returned.Opaque cursor token from a previous response’s
nextCursor field for
cursor-based pagination. See Pagination.Opaque cursor token. If present, pass this in the next request’s
cursor
parameter to fetch the next page. If absent, there are no more results.sessions array.
Pagination
session/list uses cursor-based pagination. The request includes an optional cursor, and the response includes nextCursor when more results are available.
- Clients MUST treat a missing
nextCursoras the end of results - Clients MUST treat cursors as opaque tokens, which means not parsing, modifying, or persisting them
- Agents SHOULD return
-32602if the cursor is invalid - Agents SHOULD enforce reasonable page sizes internally
Updating session metadata
Agents can update session metadata in real-time by sending asession_info_update notification via session/update. This follows the same pattern as other session notifications like available_commands_update and current_mode_update.
Agent-specific metadata. See Extensibility.
sessionId, cwd, and additionalDirectories fields are not included
in the update. sessionId is already in the notification’s params, cwd is
immutable after session setup, and ACP does not currently define mid-session
mutation for additionalDirectories. Agents typically send this notification
after the first meaningful exchange to auto-generate a title.
Interaction with other session methods
session/list only discovers sessions. It does not restore or modify them:
- Client calls
session/listto discover available sessions - User selects a session from the list
- Client calls
session/loadwith the chosensessionIdto resume the conversation
Archived sessions (unstable)
Agents that advertisesessionCapabilities.archive support session/archive, session/unarchive, the archived filter on session/list, and archived on each listed session. Agents that advertise it MUST also advertise sessionCapabilities.list. Clients MUST NOT use any of them unless the Agent advertises the capability. See the RFD.
Archiving hides a session from default session/list results. Unarchiving returns it. Both keep the session ID and saved history, and both take only a sessionId and return an empty result:
archived filter on session/list selects sessions by archive state:
Agents MUST reject a value they don’t support with
-32602 rather than falling back to exclude. The filter combines with cwd and applies before pagination. Clients keep the same cwd and archived values when following nextCursor.
Agents that advertise the capability MUST include a boolean archived on every listed session.
- If the session is loaded,
session/archivecancels any ongoing work and frees the session’s resources as ifsession/closehad been called, then archives it. This does not require theclosecapability. session/unarchivenever loads or resumes a session. Clients that want to continue an archived session SHOULD unarchive it before callingsession/loadorsession/resume. Agents MAY rejectsession/loadorsession/resumefor an archived session.- Archive state persists across connections and restarts. Closing, loading, or resuming a session does not change it.
- Because archiving closes the session,
session/statusreports an archived session assaved. - Archiving an archived session, or unarchiving one that isn’t archived, succeeds. A session that does not exist gets
-32002. - Deleted sessions are excluded from every filter value, and unarchiving does not restore them.