Client-Set Session Titles

​

Elevator pitch

What are you proposing to change?

​

Status quo

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

​

What we propose to do about it

What are you proposing to improve the situation?

​

Shiny future

How will things will play out once this feature exists?

​

Implementation details and plan

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

​

Protocol

​

Capability

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "setTitle": {}
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 2,
    "capabilities": {
      "session": {
        "setTitle": {}
      }
    }
  }
}

​

Request and response

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "session/set_title",
  "params": {
    "sessionId": "sess_123",
    "title": "Investigate OAuth timeout"
  }
}

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "title": "Investigate OAuth timeout"
  }
}

​

Validation and normalization

• The Agent MAY normalize the title before persisting it, for example by trimming surrounding whitespace, collapsing line breaks and repeated whitespace, or truncating it to a maximum length. The response reports the normalized title.
• Other validation rules are defined by the Agent. If a title fails validation, including a title that is empty after normalization, the Agent returns InvalidParams (-32602) with a message explaining why it was rejected. For example:
  {
    "jsonrpc": "2.0",
    "id": 42,
    "error": {
      "code": -32602,
      "message": "Title must not be empty."
    }
  }
  
• The Agent returns success only after persisting the title. If it cannot do so, it returns an error.

​

Errors

• If sessionId does not identify a session the Agent knows about, the Agent returns ResourceNotFound (-32002).
• An Agent MAY refuse to retitle a session it cannot safely update, such as an archived session, an ephemeral session that is not persisted, or a session currently held by another process that would overwrite the new title. In that case it returns an error with a message explaining why.

​

Notifications and session/list

• If the session is loaded, the Agent MAY send a session/update notification containing a session_info_update with the persisted title, for example so that other Clients viewing the session see the change. The requesting Client SHOULD NOT depend on this notification; the response already carries the persisted title. The notification uses the existing session_info_update, which has the same shape in v1 and v2:
  {
    "jsonrpc": "2.0",
    "method": "session/update",
    "params": {
      "sessionId": "sess_123",
      "update": {
        "sessionUpdate": "session_info_update",
        "title": "Investigate OAuth timeout"
      }
    }
  }
  
• If the Agent supports session/list, later session/list results return the persisted title for the session. session/set_title does not require session/list support; a successful response is enough for the Client to know the title was persisted.

​

Agent-generated titles

• After session/set_title succeeds, the Agent SHOULD NOT replace the title with one it generates automatically. This is a SHOULD rather than a MUST because some Agents, such as adapters around an existing CLI, do not fully control when the underlying agent generates titles.
• If the Agent is generating a title when session/set_title succeeds, it SHOULD discard the generated title.
• This does not restrict later user-initiated renames through other paths, such as an Agent slash command like /rename or another Client calling session/set_title. Each successful rename replaces the previous title.
• Clients MAY call session/set_title while a prompt turn is in progress. Retitling does not affect the turn.

​

Frequently asked questions

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

​

Why session/set_title instead of session/rename?

​

Why not a general session/set_info that mirrors session_info_update?

​

Why does the response include the title?

​

Why doesn’t the session need to be loaded?

​

Why can’t a Client clear a title or go back to a generated title?

​

Why is there no title on session/new?

​

Revision history

• 2026-08-19: Initial proposal.
• 2026-10-26: Show v1 and v2 capabilities, return the persisted title in the response, allow normalization, allow retitling sessions that are not loaded, make the notification optional, define errors, and add FAQ.