[FEATURE] Better context window handling in SDK headless mode

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

I'm implementing a command-line tool (think bash) that uses the headless mode. I start claude like this:

claude --input-format stream-json --output-format stream-json 

My tool streams input commands into stdin and reads from stdout, displaying them to the user in a custom UX.

Question: Can I track when token usage is getting close to requiring an auto compact? I see token counts in the responses, but I don't know what the max is. I'd like to warn the user when they are getting close.

Related, does claude code do autocompact in the SDK in headless mode? If not then being able to track and report when the max context window will be reached becomes even more important.

Thanks!

Proposed Solution

Claude reports the percentage of tokens used out of the max in assistant and response messages. Current it reports this (no max or percentage):

    "total_cost_usd": 0.2440755,
    "usage": {
      "input_tokens": 4,
      "cache_creation_input_tokens": 12582,
      "cache_read_input_tokens": 4802,
      "output_tokens": 12
    }

I'd like to also see a percentage used, or a max:

    "total_cost_usd": 0.2440755,
    "usage": {
      "input_tokens": 4,
      "cache_creation_input_tokens": 12582,
      "cache_read_input_tokens": 4802,
      "output_tokens": 12,
      "tokens_max": 1000000
    }

That could be broken down into max input / output tokens, or expressed as a percentage or ratio. But some indication of how close we are to the max would be helpful.

Alternative Solutions

_No response_

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

_No response_