Skip to main content

Elevator pitch

What are you proposing to change?
Some session operations act at a position in the conversation, not on the whole session. Forking at an earlier message is one. Rewinding a session and replaying part of its history are others. A message ID is not enough to name such a position. The Client can’t tell from an ID whether the Agent can act at that message, or which operations work there. Some positions are also not at a message, such as the point after a tool call. This RFD adds session cursors to ACP v1 and v2, with some differences in v1:
  • A cursor names one position in one session. The Agent identifies it with a cursorId, an opaque string.
  • The Agent announces cursors with a new cursor_update session update. Its capabilities say which methods accept the cursor. Its anchor places the position before or after an entity the Client holds, such as a message or a tool call.
  • A method that acts at a position takes a cursorId as a parameter. This RFD does not change any method. The RFD for each such method adopts cursors, starting with session fork.

Status quo

How do things work today and what problems does this cause? Why would we change things?
The session fork RFD added session/fork, which copies a whole session. It expected a later extension that forks at a specific message. PR #629 proposed that extension with a message ID, and the discussion found three problems:
  • Not every message is a valid position. An Agent may be able to fork before a user message but not in the middle of its own output. A Client that only has message IDs has to try one and handle the error.
  • Not every position is at a message. A position can follow a tool call or a compaction.
  • Validity depends on the operation. A position the Agent can fork from is not always one it can rewind to.
Other operations need positions too:
  • v2 session/resume has a replayFrom parameter, but its only value is { "type": "start" }. The Session Resume Replay RFD leaves room for values that replay from a later position, and the Replay Complete Signal RFD leaves a position on replay_complete to the RFD that adds partial replay.
  • A method that rewinds a session or edits an earlier message has to name where to cut.
  • When several Clients share a session, they have to mean the same position.
ACP has no shared way to name a position. Each of these features would otherwise define its own, with its own rules for which positions are allowed.

What we propose to do about it

What are you proposing to improve the situation?

Cursors

A cursor names one position in the session it was announced on. cursorId is an opaque, Agent-owned string. It is unique within the session and never reused for another position. A position is a point in the session’s timeline: between two neighboring entities, before the first one, or after the last one.
  • Clients MUST NOT parse, change, or construct a cursorId.
  • Two cursors may name the same position.
  • A cursor belongs to the session named by the sessionId of the session/update notification that announced it. Its cursorId has no meaning in any other session, including a fork or a child session of that session.
  • A cursor is not tied to a connection or to a Client. Any Client that has the session active can pass its cursorId.
  • A cursorId is not a credential. It only has meaning in a session the caller can already use.

The cursor_update session update

The Agent announces a cursor with a cursor_update session update:
cursor_update is an upsert keyed by cursorId. Clients initialize a first-seen cursorId with no capabilities, then apply the update:
  • capabilities is a nullable patch. Omitted leaves the stored value unchanged, null clears it, and an object replaces the whole previous value.
  • anchor is fixed. The Agent chooses one anchor when it first announces the cursor and MUST NOT change it afterwards. A later update can omit anchor or repeat the same one, and omitted and null are equivalent. Clients keep the first anchor they receive for a cursor.
A cursor never moves. To offer a different position, the Agent announces a new cursor. Later updates change only capabilities, for example to add a method that became possible at the position or to remove one that no longer is. The Agent can send a cursor_update at any time, like other session updates. It announces a cursor only for a position where at least one method works, so it does not need a cursor for every entity. A Client can’t act at a position that has no cursor.

Cursor capabilities

capabilities says which methods accept the cursor. It has the same shape and rules as the capabilities of tool calls and terminals and of subagents:
  • Each capability is an optional, nullable object. Omitted or null means unsupported, and {} advertises support. It may carry _meta, and a later RFD can add fields to it.
  • The object is replaced as a whole, not patched by key. capabilities: null and capabilities: {} both mean that no method accepts the cursor. So does a cursor whose capabilities was never supplied.
  • This RFD defines no capability. The RFD for each method that accepts cursors adds one, such as fork in the session fork RFD.
  • Clients ignore capabilities they don’t recognize.
One cursor can advertise several capabilities.

Anchors

An anchor says where the position is, relative to an entity the Client already holds: The anchor names the entity type because an entity is identified by its type together with its ID. v1 uses the same shape. An anchor type is an entity that every Client places in the timeline and that is part of the conversation history. Two entity types with a timeline position are left out:
  • Terminals. A Client shows a terminal through the tool call that references it. The Agent anchors to that tool call.
  • Plans. A Client may show a plan outside the timeline, such as in a plan panel, and then has no place for the cursor.
Updates without an entity ID, such as notice and state_update, have no timeline position and can’t be anchored to. A cursor lies between two neighboring entities, so an anchor can name its place from either one. The anchor’s position field says on which side of the entity the cursor is:
  • before: the cursor is immediately before the entity. The history before the cursor does not include the entity.
  • after: the cursor is immediately after the entity. The history before the cursor includes the entity and nothing that follows it in the timeline.
When one entity directly follows another, after the first and before the second are the same position. Both sides exist because each end of the session has only one. before is the only anchor for the position ahead of the first entity, and after is the only anchor for the current end of the session. The Agent chooses one of the two when it announces the cursor. It anchors to the entity where the Client is likely to show the action, for example before a user message for editing it, or after an agent message for branching from it.
  • The entity MUST belong to the same session.
  • The Agent MUST report the entity on that session before it sends a cursor_update anchored to it. In a replay, that means after the replayed entity.
  • An anchor fixes the position no matter when the update arrives. The Agent can announce a cursor for an earlier message later, for example when the position becomes usable for a method.
  • type and position are open in both protocol versions, under the v2 enum extension rules.
Every cursor has an anchor, in both protocol versions:
  • The first cursor_update for a cursorId MUST include anchor.
  • v1 message IDs are optional, but an anchor to a message needs one. A v1 Agent that announces cursors MUST send a messageId on every message it anchors to. See Differences in v1 for a prompt the Agent does not report.
A Client can’t place a cursor in three cases:
  • It holds no anchor for the cursor, for example because it missed the first update.
  • It does not hold the anchored entity, for example because it joined the session after the Agent reported that entity, or resumed without a replay.
  • It doesn’t recognize the anchor’s type or position.
The Client MUST NOT guess a place for such a cursor. A replay delivers each entity before the cursors anchored to it, so a Client that needs to place them resumes with a replay. Clients show actions on entities, and an anchor stays correct when the session continues, when the Agent announces the cursor late, and when a replay delivers updates in a different order. A cursor for the current end of the session is anchored after the last entity, and that anchor still holds once later entities follow it.

Passing a cursor to a method

These rules apply to every method that accepts a cursor:
  • Clients MUST only pass a cursor that the Agent announced on that session and that currently advertises the capability for the method.
  • Clients MUST pass the cursorId. They MUST NOT pass the anchor’s entity ID in its place.
  • The Agent MUST reject the request with -32602 (Invalid params) when it did not issue the cursorId for that session, when it no longer accepts the cursor, or when the cursor does not support that method. It MUST NOT act at a different position, and it MUST NOT handle the request as if the cursorId had been omitted.
  • Proxies and conductors forward cursorId values unchanged in cursor_update notifications and in requests.

What each method defines

This RFD defines how a position is named and the rules above. It does not change any method. The RFD for a method that acts at a position adopts cursors and defines:
  • A capability. The name of its capability in the cursor’s capabilities, and any fields that capability carries.
  • A parameter. The request parameter that carries the cursorId.
  • What the method does at the position. Methods describe this as the history before the position or the history after it. They don’t need to say whether a message is included, because the anchor already says which side of the entity the position is on.
  • Invalidation. Which cursors the method invalidates, if any.
  • Lifetime. Any stronger lifetime rule for cursors that advertise its capability. For example, a method that replays from a cursor would need it to stay usable across connections and Agent restarts.
An Agent advertises a capability on a cursor only where it can meet that method’s rules. An Agent that can’t keep a cursorId usable after a restart can still offer the cursor for session/fork without offering it for replay. The session fork RFD is the first to do this, with a fork capability and a cursorId parameter on session/fork. The methods this RFD has in view use a position as a point in the history. session/fork copies the history before the position, and a rewind would remove the history after it. Partial replay may need something different: a point in what the Client has received. Entities before that point can still change after it, for example when a tool call finishes. Whether a cursor can name such a point is an open question for the RFD that adds partial replay. capabilities keeps the uses apart. A cursor advertises only the capabilities of the methods it works for.

Lifetime

A cursor stays valid until the Agent invalidates it. The end of a connection, session/close, and session/resume do not invalidate a cursor.
  • Agents SHOULD accept a cursor for as long as they retain the history at its position, including across connections and Agent restarts.
  • Clients MAY store cursors with their copy of the session and pass them on a later connection.
An Agent can stop accepting a cursor at any time, for example when it removes, compacts, or no longer retains the history at the position. A Client learns this in one of three ways:
  • The Agent sends a cursor_update that clears the cursor’s capabilities. Agents SHOULD do this when they stop accepting a cursor while the session is active on a connection.
  • A full replay does not announce the cursor. See Replay.
  • A request with the cursorId fails with -32602. The Client SHOULD then stop offering the cursor.
A method that removes history can define that it invalidates every cursor after the cut, so the Agent doesn’t send one update per cursor. A cursorId is not a session/list pagination cursor. A pagination cursor continues one listing, and Clients must not persist it. A cursorId names a position in stored history, and Clients can persist it.

Replay

Cursors are part of the history that v1 session/load and v2 session/resume with replayFrom replay.
  • When an Agent replays history, it SHOULD send a cursor_update for each cursor in that history that it still accepts. A replayed update carries the cursor’s capabilities and anchor, like a first update, and follows the replayed entity it is anchored to.
  • In v2, replayed cursor_update notifications are replayed history and come before replay_complete.
  • Agents SHOULD use the same cursorId for the same position in every replay. An Agent that issues a new cursorId still accepts or rejects the old one as Passing a cursor to a method requires.
  • A full replay rebuilds the session’s cursors, like its other entities. The Client SHOULD discard the cursors it held for the session and build them again from the replayed cursor_update notifications. A replayed cursor can carry a different anchor than it had before, for example when a messageId changed across the replay.
  • A resume without replay announces no cursors for earlier history. The cursors the Client already holds stay usable under the lifetime rules.

Client and Agent capabilities

  • v2. No capability is needed. The v2 SessionUpdate union is open, so a Client that doesn’t know cursor_update ignores it.
  • v1. The v1 SessionUpdate union is closed, and an older Client can fail on an unknown variant. v1 adds an optional cursors object at clientCapabilities.session.cursors. Supplying {} means the Client handles cursor_update. Omitting it or setting it to null means it does not. Agents MUST only send cursor_update to a v1 Client that advertises it, in live delivery and in replay.
  • Agents. There is no Agent capability for cursors in initialize. An Agent that supports them announces them. An Agent that doesn’t never sends a cursor_update, so the Client has no cursorId to pass. A method that accepts a cursorId still requires its own capability, such as session.fork for session/fork.

Differences in v1

Cursors have the same shape in v1 and v2. v1 differs in five ways:
  1. Client capability. A v1 Client opts in with clientCapabilities.session.cursors. v2 needs no capability. See Client and Agent capabilities.
  2. A live prompt may have no user message to anchor to. v1 does not require the Agent to report the user’s prompt as a session update, and the session/prompt response carries no messageId. The Client then holds no user message for that prompt, and the Agent can’t anchor before it. The Agent anchors the same position after the last message, tool call, or compaction before the prompt. The first prompt of a session has nothing before it, so that position has no cursor.
  3. User message anchors appear after session/load. A load replays user messages as user_message_chunk updates. When they carry a messageId, the Agent anchors before or after them as in v2. The same position can therefore have a different anchor live and after a load.
  4. Message IDs need not survive a load. v1 does not require a messageId to stay the same across session/load. A Client uses the cursors of the latest load and does not match their anchors to entities it held before.
  5. Only session/fork adopts cursors. Partial replay builds on replayFrom, which v1 does not have. An RFD that adopts cursors says whether it applies to v1.
For a Client, item 2 means that the cursor for editing a prompt it sent on this connection is the one anchored after the entity that precedes that prompt in its timeline. To edit the first prompt, the Client starts a new session. The v1 and v2 parts of this RFD can stabilize separately, as the Message ID RFD did. The v1 part stays unstable until Clients and Agents have tried the anchoring in item 2.

Shiny future

How will things play out once this feature exists?
A Client renders a conversation and receives cursor_update notifications with it. It shows an edit action on each user message that has a cursor anchored before it with the fork capability, and no action where the Agent announced none. The user edits the third message. The Client forks at that cursor and sends the new text to the new session. The Client never guesses which messages are valid fork points. Each method that acts at a position adopts the same cursors in its own RFD, without defining a new position type:
  • Fork at a position. The session fork RFD adds a fork capability and a cursorId on session/fork.
  • Partial replay. v2 session/resume already has replayFrom for the position to replay from. If cursors suit replay, one could fit there as a new variant, { "type": "cursor", "cursorId": "..." }, with a capability of its own. An Agent could then announce a cursor for the current end of the session, anchored after the last entity, and a Client could store the latest one to catch up after it reconnects. See Open questions.
  • Rewind and edit in place. A rewind method takes a cursorId for the cut and adds its own capability. The update that reports the cut names it by the same cursorId, so every Client on the session converges on the same history.
  • Several Clients on one session. Cursors belong to the session, so every Client receives the same cursors and can use them.
Each of these defines what its method does at the position. None of them needs another way to name one.

Implementation details and plan

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

Adapter validation

The table shows what claude-agent-acp and codex-acp could offer. It comes from reading the two adapters and the runtime APIs they call, not from an implementation. What follows from that:
  • The cursorId has to be opaque. Neither runtime acts at ACP entities. Codex acts at turn boundaries only, and one Claude agent message spans several transcript entries. A reference to an entity would name positions the Agent can’t act at, which is why the Codex extension rounds a message to the end of its turn.
  • The update has to be separate. Both adapters learn most positions after they sent the anchored entity, and neither reports the user’s prompt in v1.
  • before a user message is the position both runtimes share. It is the position a Client needs to edit a message. Claude Code can also act after a tool call’s result, so anchors can’t be limited to messages.
  • Both adapters can derive a cursorId from an ID the runtime stores. Neither needs storage of its own, and the cursorId is the same in every replay and after a restart. The exceptions are older Codex threads and Claude compaction anchors. They are why a full replay rebuilds cursors, and why the rules for a stable cursorId are SHOULD and not MUST.
  • File restore differs between runtimes. A rewind capability needs a field for it.
Not determined: whether Claude Code accepts a fork that ends on a tool use without its result, and whether Codex keeps turn IDs when it restores an older thread.

Plan

  1. Schema. Add the following to v1 and v2, behind an unstable_session_cursors feature:
    • A CursorId string type, like MessageId.
    • CursorUpdate with cursorId, capabilities, anchor, and _meta, and a cursor_update variant in SessionUpdate. capabilities is a three-state patch field. anchor is optional in the schema, because later updates can omit it, and omitted and null are equivalent.
    • CursorCapabilities with _meta, mirroring ToolCallCapabilities. It starts with no capabilities, and each RFD that adopts cursors adds its own. A malformed value falls back to unsupported, so the Client never passes a cursor to a method the Agent did not advertise.
    • CursorAnchor, a union tagged by type with the message, tool call, and compaction variants and a fallback that preserves unknown types. A known type with a malformed payload still fails. In v1, the session_message variant is behind unstable_subagents.
    • ClientSessionCapabilities.cursors in v1.
  2. Docs. Describe cursors in the draft prompt lifecycle and session setup pages for both versions: the cursor_update update, the rules for passing a cursorId, and cursors in replay contents. Add cursor_update to the session update tables. Next to the v2 entity ID table, say that a cursor is updated by ID but takes its place from its anchor, not from receive order.
  3. SDKs. Expose the types. A Client SDK can track the cursors of a session and drop them on a full replay.
  4. Validation. Implement cursors together with the first method that adopts them, in at least one Agent adapter and one Client before Preview. Cover a cursor announced after its entity, a cursor announced again in replay, a cursor whose capabilities were cleared, a cursorId passed to a method the cursor does not advertise, and a cursorId from another session. In v1, also cover a cursor for a live prompt that is anchored after the preceding entity, and the same position after a session/load.
  5. Stabilization. Decide on the v1 part separately from the v2 part, after that validation.

Frequently asked questions

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

Are cursors still valid after session/resume?

Yes. A cursor belongs to the session, not to a connection. A Client that stores a session’s history keeps its cursors with it, and a cursor used for replay would only ever be used after a reconnect. A rule that resume invalidates cursors would make both useless. The Agent can still invalidate any cursor under the lifetime rules, and a full replay tells the Client which cursors remain.

Why not use message IDs?

An ID names a message. It doesn’t say whether the Agent can act there, for which method, or on which side of the message. A cursor is announced only for positions the Agent supports, and its capabilities name the methods.

Why a separate update and not a field on message updates?

A field on the anchored entity’s own update, such as cursors on user_message, would save the Client a lookup. It fits one case: a cursor before a user message in v2, which the Agent knows when it reports the message. It does not fit the others:
  • An Agent often learns that a position is usable after it sent the entity, for example when a turn completes. The field would then need a second, patch-only update for that entity.
  • Agents stream agent messages as chunks. A chunk appends content and has no patch rules for another field.
  • v1 messages are chunk-only, and a v1 Agent may not report the user’s prompt at all.
A separate update handles every anchor type the same way in both versions. A later cursor_update can also change capabilities without another update for the entity.

Why a capabilities object and not a list of method names?

Tool calls, terminals, and subagents already advertise what a Client can do with them in a capabilities object. Cursors follow the same pattern. An object per capability also leaves room for options, for example whether a rewind also restores files. A list of method names has no place for them. Method names also differ between protocol versions, such as session/load and session/resume, and one method could take cursors in more than one parameter.

Why both before and after?

A position is a gap between two entities, and a Client shows the action on one of them. before a user message is where a Client offers to edit it. after an agent message is where it offers to branch from it. With only one side, the Client would have to find the neighboring entity itself, which fails when it doesn’t render that entity. One end of the session could not be anchored at all. Agents also differ. Some keep a checkpoint before each user message, and others resume at a given agent message. An Agent that knows one side can’t always name the other when it announces the cursor, for example because the next message does not exist yet.

Why does every cursor need an anchor?

Without an anchor, a Client could only place a cursor by the order in which updates arrive. That order is not reliable when the Agent announces a cursor late, when several Clients share a session, or when a replay sends an entity’s current state in place of its original updates. An anchor names the position directly. This means a v1 Agent that announces cursors also sends message IDs. v1 already defines messageId as an optional field, so the Agent needs no other protocol change. It does not give a v1 Client a user message for a prompt the Agent never reports. Differences in v1 covers that case.

Why not make cursors v2-only?

Most Clients still use v1, and forking at a position is the feature they ask for. The shape is the same in both versions, so v1 costs one Client capability and the differences listed in Differences in v1. The v1 part can stay unstable, or be dropped, without changing v2.

Why is the anchor fixed when capabilities can change?

What an Agent can do at a position changes over time. A method can become possible later or stop being possible, and the Agent reports that on the same cursor. A Client that missed such an update gets -32602 when it tries the method, which is safe. A position has no such check. A Client can hold a cursor across connections and resume without a replay. If the Agent could move a cursor, a Client that missed the update would show it in one place and act at another, and the Agent could not detect that. So the Agent chooses one anchor when it announces the cursor, and announces a new cursor to offer another position. A full replay rebuilds the session’s cursors, so an ID that changed across a replay does not need an anchor edit either.

Why is there no Agent capability?

A capability in initialize says that an Agent supports a feature. It can’t say which positions are valid, so the Client still has to wait for cursor_update. A Client also can’t pass a cursorId that no Agent announced. That covers Agents that ignore unknown parameters: they never announce a cursor, so they never receive one.

Why does this RFD not change any method?

Each method that acts at a position has its own RFD, and its parameters and behavior belong there. Cursors are then defined once, and each method adopts them when its own design is ready. The session fork RFD already does. Partial replay and rewind still need their own designs.

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

A fork-specific forkPoint update was considered in PR #629. It covered forking, but rewind and replay would each have needed their own way to name a position.

Open questions

  • Partial replay. Can a cursor name the point a replay starts from? That point is a place in what the Client received, not in the history, and neither claude-agent-acp nor codex-acp can replay from a position today. The RFD that adds partial replay has to say what the Agent replays after the cursor, how changes to earlier entities reach the Client, and what the Client does with entities it already holds after the cursor.
  • v1 anchoring for live prompts. Is a cursor anchored after the previous entity workable for v1 Clients? See Differences in v1. If it is not, cursors need v2.
  • Error detail. Should an invalid cursorId get its own error code or a data field, so a Client can tell it from other -32602 errors?

Revision history

  • 2026-11-16: Steps 1 and 2 of the plan landed. The v1 and v2 schemas have cursor_update, CursorId, CursorCapabilities, CursorAnchor, and the v1 session.cursors Client capability, behind unstable_session_cursors. Each anchor variant also accepts _meta. The draft protocol pages describe cursors under v1 Prompt Turn and v2 Prompt Lifecycle.
  • 2026-11-16: Left the use of cursors for partial replay as an open question. Defined when a Client can’t place a cursor.
  • 2026-11-14: Cursors are now identified by cursorId and announced with cursor_update, an upsert that carries per-cursor capabilities in place of validFor. Replaced beforeMessageId and afterMessageId with a typed anchor that also covers tool calls and compactions. Every cursor has an anchor, so a v1 Agent that announces cursors also sends message IDs. Defined lifetime, invalidation, replay, the -32602 rule, the v1 Client capability, and the differences in v1. Added an adapter validation for claude-agent-acp and codex-acp. Moved the method changes out of this RFD. Each method’s RFD adopts cursors, starting with session fork.
  • 2026-09-07: Initial draft