docs(rfd): Add session usage and context status RFD

[ahmedhesham6]

Proposes standardized tracking of token usage, cost estimation, and context window status across ACP implementations.

• Token usage reported in PromptResponse (per-turn data)
• Context window and cost reported in session/status (session state)

[versecafe]

are these two fields needed, they are fully derivable from size and used

[ahmedhesham6]

They’re redundant mathematically, but they carry the agent’s own calculation/rounding and simplify client work

[versecafe]

ditto on the derived fields from size and used are these fields needed

[versecafe]

how will this work with subagent "tools" that aren't performing full turns but are actively updating token usage frequently

[benbrandt]

@josevalim @SteffenDE I'd love to get your input on this one since you were looking into this a bit

[SteffenDE]

We like the idea and we definitely want to have a way to do this in ACP! For us, the most important part is the current usage (in percent). Including a usage in prompt responses feels like a no-brainer, but since an ACP prompt often consists of multiple agent turns, wrappers like Claude-Code-ACP would need to accumulate the different tokens from the turns. I think that's alright though. As mentioned in #316 (comment), one needs to be careful about usage data from subagents, as those should not be included, or optionally provided separately.

The PR proposes a new session/status method. I'm not sure if agents like Claude Code have proper APIs to query the current status at any time, so a different idea would be to only send the current usage information (current tokens, max tokens, percent) as part of session/update notifications only. An agent that supports getting the current usage without a prompt may then immediately send the update when creating a new chat, resuming a chat, forking a chat, etc., similar to how the available command updates are sent. An agent that only provides usage when actively prompting could only start sending the updates after sending a new prompt. That might mean that when resuming a chat, the client UI cannot immediately show the usage, but it allows more flexibility for agents.

[ahmedhesham6]

@SteffenDE Thanks a lot for the detailed explanation and context 🙏
Just to confirm I understood you correctly — is this roughly what you’re suggesting for the session/update approach?

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123",
    "update": {
      "sessionUpdate": "context",
      "used": 53000,
      "size": 200000,
      "percentage": 26.5
    }
  }
}

If this matches what you had in mind, I can adjust the RFD in that direction.

[SteffenDE]

@ahmedhesham6 yes! I'd wait before changing things though, since I'm not a maintainer here and basically just stating my opinion :D

[ahmedhesham6]

What do you think @benbrandt?

[benbrandt]

Yeah I think something simple to start would be great. As @SteffenDE mentioned, support for this will likely vary wildly (and we've also seen mixed support of even these basic metrics within the same agent lol)

I think we should let this be driven by the agent, as they will likely get the information from the provider and may forward it, but might not hold on to it. Requiring them to have the data at all points might be too much... So I'd opt for a simple way to report the basic information we feel we need, and go from there