> ## Documentation Index
> Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Context Size and Cost

* Author(s): [@ahmedhesham6](https://github.com/ahmedhesham6)
* Champion: [@benbrandt](https://github.com/benbrandt)

## Elevator pitch

> What are you proposing to change?

Add a standardized `usage_update` session notification that lets agents report the current context window utilization and optional cumulative session cost.

This RFD is intentionally scoped to session-level context size and cost. End-turn token accounting is covered separately in the [End-Turn Token Usage RFD](/rfds/end-turn-token-usage).

## Status quo

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

ACP currently has no standardized way for agents to communicate:

1. **Context window status** - How much of the model's context window is being used
2. **Cost information** - Estimated cumulative cost for API usage

This creates several problems:

* **No context management** - Clients cannot warn users when a session is approaching context limits or suggest compaction
* **No cost transparency** - Users cannot track spending or estimate whether a long-running session should continue
* **Inconsistent implementations** - Each agent reports context and cost differently, if it reports them at all

Common AI coding tool behavior suggests users benefit from:

* Context percentage indicators such as "19%"
* Absolute token details such as "31.4K of 200K tokens"
* Warning thresholds around high context utilization
* Auto-compaction or handoff suggestions near context limits
* Cumulative session cost tracking rather than only per-turn cost breakdowns

## What we propose to do about it

> What are you proposing to improve the situation?

Agents send context window and cost information via `session/update` notifications with `sessionUpdate: "usage_update"`:

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123",
    "update": {
      "sessionUpdate": "usage_update",
      "used": 53000,
      "size": 200000
    }
  }
}
```

### Context Window Fields

* `used` (number, required) - Tokens currently in context
* `size` (number, required) - Total context window size in tokens

Clients can compute `remaining` as `size - used` and `percentage` as `used / size * 100`.

If a model has a dynamic context window, agents should report the current effective limit and send another `usage_update` if that limit changes. If an agent cannot provide a meaningful context window size, it should not send `usage_update`; this RFD does not define a `null` or omitted `size` state.

### Cost Field

* `cost` (object, optional, nullable) - Cumulative session cost
  * `amount` (number, required) - Total cumulative cost for the session
  * `currency` (string, required) - ISO 4217 currency code, such as `"USD"` or `"EUR"`

Example with optional cost:

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123",
    "update": {
      "sessionUpdate": "usage_update",
      "used": 53000,
      "size": 200000,
      "cost": {
        "amount": 0.045,
        "currency": "USD"
      }
    }
  }
}
```

Agents send updates when they have current data available:

* After `session/new`, once the session ID exists
* After `session/load`, `session/resume`, or `session/fork` for restored sessions
* After `session/prompt`, when usage data becomes available
* Anytime context window state or cumulative cost changes significantly

This approach provides flexibility for different agent implementations:

* Agents that can query current usage without a prompt can send updates immediately after session setup
* Agents that only receive usage data while prompting can send updates after prompt completion
* Agents that cannot calculate cost can still report context window status

### Design Principles

1. **Session state** - Context size and cumulative cost describe the session, not one prompt response
2. **Agent-pushed notifications** - Agents proactively send updates when data becomes available, following the same pattern as dynamic session properties such as `available_commands_update`, `current_mode_update`, and `session_info_update`
3. **Agent calculates, client can verify** - Agents know their model and tokenizer best, but expose raw values so clients can compute derived display values
4. **Flexible cost reporting** - Cost is optional because not all agents track it, and the currency is explicit because agents may bill in different currencies
5. **Optional but recommended** - Context and cost reporting remains optional to preserve compatibility

## Shiny future

> How will things will play out once this feature exists?

**For Users:**

* **Visibility**: Users see current context window usage with percentage indicators
* **Cost awareness**: Users can track cumulative spending at any time
* **Better planning**: Users know when to start a new session, compact context, or hand off work
* **Transparency**: Users get a consistent view of resource consumption across agents

**For Client Implementations:**

* **Consistent UI**: Clients can show usage through standard progress indicators, detail hovers, and warning states
* **Smart warnings**: Clients can warn users as sessions approach high context utilization
* **Cost controls**: Clients can implement budget alerts and session-level spend displays
* **Reactive updates**: Clients update UI immediately when agents push new data
* **No polling needed**: Clients do not need a separate status request to keep context displays current

**For Agent Implementations:**

* **Standard reporting**: Agents get a clear contract for reporting context window and cost state
* **Flexibility**: Agents can report only the cost information they can calculate
* **Model diversity**: The shape works across providers and local models

## Implementation details and plan

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

1. Add a `UsageUpdate` variant to `SessionUpdate` with discriminator `sessionUpdate: "usage_update"`.
2. Add a `Cost` type with `amount` and `currency` fields.
3. Gate this Rust crate surface behind the `unstable_session_usage` feature.
4. Document the `session/update` notification variant in the protocol docs.
5. Add examples showing when agents should send context window and cost updates.

This RFD does not add end-turn token usage to the turn-completion signal. That proposal remains in draft in the [End-Turn Token Usage RFD](/rfds/end-turn-token-usage).

## Frequently asked questions

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

### Why split this from end-turn token usage?

Context window size and cumulative cost are session-level state that clients may need before, during, or after a prompt. Token accounting for a completed turn has different open questions, including whether values should be per-turn or cumulative and how cache metrics should map across providers.

### How do users know when to hand off or compact context?

The `usage_update` notification provides the raw values clients need:

* `used` and `size` give absolute numbers for precise tracking
* Clients can compute `remaining` as `size - used`
* Clients can compute `percentage` as `used / size * 100`

**Recommended client behavior:**

| Percentage | Action                                                           |
| ---------- | ---------------------------------------------------------------- |
| \< 75%     | Normal operation                                                 |
| 75-90%     | Yellow indicator, suggest "Context filling up"                   |
| 90-95%     | Orange indicator, recommend "Start new session or summarize"     |
| > 95%      | Red indicator, warn "Next prompt may fail - handoff recommended" |

### Why is cost in `session/update` instead of the turn-completion signal?

Cost is cumulative session state, similar to context window utilization:

* Users usually want total spending, not only per-turn costs
* Both cost and context window are session-level metrics that can change when agents compact, switch models, or restore sessions
* Cost is optional because not all agents track it

### Why not assume USD for cost?

Agents may bill in different currencies:

* European agents might bill in EUR
* Asian agents might bill in JPY or CNY
* Currency conversion rates change

Agents should report the actual billing currency and let clients convert if needed.

### How does this work with streaming responses?

Agents may send `usage_update` notifications during streaming if context state changes and they have reliable current data. They should also send an update after prompt completion when final context size or cost data becomes available.

### What about models without fixed context windows?

Agents should report the current effective context window size. For models with dynamic windows, agents should report the current limit and send another update if it changes.

If there is no meaningful context window size, agents should not send `usage_update`; `size` is required and non-null.

### What about rate limits and quotas?

This RFD focuses on context window utilization and cumulative cost. Rate limits and quotas are separate concerns that could be addressed in a future RFD.

### Should cached tokens count toward context window usage?

Yes. Cached tokens still occupy context window space even when they are cheaper to process. Context window usage should include all tokens currently in context.

### Why a notification instead of a request?

Using `session/update` notifications instead of a `session/status` request provides several benefits:

1. **Consistency**: Follows the same pattern as other dynamic session properties
2. **Agent flexibility**: Agents can send updates when they have data available
3. **No polling**: Clients receive updates reactively
4. **Real-time updates**: Updates flow naturally as part of the session lifecycle

### What if the client connects mid-session?

When a client connects to an existing session through `session/load` or `session/resume`, agents should send a `usage_update` notification if they have current context window data available. This lets the client UI immediately display accurate context and cost information.

For agents that only provide usage during active prompting, the client UI may not show usage until after the first prompt is sent.

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

**Everything in the turn-completion signal** - Simpler, but context window and cost are session state that users may want independently of prompt turns.

**Request/response with `session/status`** - Requires clients to poll, and some agents do not have APIs to query current status without a prompt.

**Client calculates everything** - Rejected because clients do not know the agent's tokenizer, exact context window size, model routing, or pricing.

**Only percentage, no raw tokens** - Rejected because users want absolute numbers, clients cannot verify calculations, and it is less transparent.

## Revision history

* 2025-12-07: Initial draft
* 2025-12-13: Changed from `session/status` request method to `session/update` notification with `sessionUpdate: "context_update"`. Made `cost` optional and removed `remaining` field (clients can compute as `size - used`). This approach provides more flexibility for agents and follows the same pattern as other dynamic session properties.
* 2025-12-17: Renamed `reasoning_tokens` to `thought_tokens` for consistency with ACP terminology. Removed `percentage` field (clients can compute as `used / size * 100`).
* 2025-12-19: Renamed `sessionUpdate: "context_update"` to `sessionUpdate: "usage_update"` to better reflect the payload semantics (includes both context window info and cumulative cost).
* 2026-06-02: Split end-turn token accounting into a separate draft RFD.
* 2026-06-03: Moved to Preview.
* 2026-06-05: Moved to Completed.