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)

[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

[benbrandt]

naming nitpick: it seems weird that this is part of a "context" update.
I wonder if all of this is just usage from a conceptual point of view?
And roughly the same data can be sent at the end of the turn, with mid-turn updates? So kind of merge these?

It seems you want to distinguish between turn usage vs total usage. Which makes sense, but I wonder if we can distinguish then between turn vs session usage?

[ahmedhesham6]

@benbrandt Great point on the naming! You're right that "context" is a bit awkward here.

I think we're aligned on the core idea - distinguishing between turn usage vs session usage:

• Turn usage (in PromptResponse): Token breakdown for that specific turn - input, output, thought, cached tokens. This is the "what just happened" data.

• Session usage (via session/update): Cumulative state - total tokens consumed, context window utilization, cost. This is the "where are we now" data that agents push when available.

The session/update notification could use sessionUpdate: "usage_update" instead of "context_update" to better reflect this. The payload would still include context window info (used, size) alongside cumulative cost, but framing it as "usage" makes more conceptual sense.

Would renaming to sessionUpdate: "usage_update" address the naming concern? Happy to update the RFD if that direction works.

[benbrandt]

Yeah I think we're on the same page here 👍🏻 thanks!