[FEATURE] Tell the model its own context-window usage, the way it's already told the date

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

Claude Code already injects a fair amount of session state into the model's context on every turn: the current date, the working directory, the platform and OS version, whether it's a git repo, the model name and ID, the scratchpad path, which MCP servers are still connecting. The model is told all of that so its answers are grounded instead of guessed.

The one piece of session state it is not told is the one that most directly governs its own planning: how full the context window is.

That number already exists and is already computed. /context prints it. The statusline API receives tokens, max, and a percentage. Auto-compact fires off it. The model is the only participant in the session that can't see it.

Three concrete consequences:

1. The model's own scoping advice is made blind. "Let's do that in a fresh session", "let me delegate this to a subagent", "let's split this into two passes", "I'll summarise instead of pasting the whole file" — every one of those is a context-budget decision. Right now the model makes them with no idea whether there's 600k tokens of headroom or 30k. So it either never raises it, or raises it on vibes.

2. When it does raise it, it hallucinates. #36281 documented this precisely: the model announced "context is getting tight, let's wrap up", and when challenged admitted it has no such perception and was extrapolating from "this conversation feels long". That issue was closed as a duplicate of #34238 (users irritated by unprompted "let's stop here" suggestions), which was then closed NOT_PLANNED as stale. But the root cause was never addressed: if you don't give the model the number, its only options are silence or guessing — and the guessing is what gets filed as a model-behaviour bug.

3. Large reads are unpriced. The model decides to read a 4,000-line file, or dump a wide grep, or pull in a big API response, without knowing whether that costs 3% or 30% of what's left. A number it can see turns that from a gamble into arithmetic.

Explicit scope limit: I am not asking for the model to be allowed to compact, end sessions, refuse work, or otherwise manage the session on its own. That's a bigger and more debatable change. This is read-only awareness. Every decision stays with the user — the model just stops being the only party in the room that's blindfolded.

Proposed Solution

Inject context usage into the model's context the same way the date already is. One line, refreshed per turn:

# contextUsage
Approximately 62% of the context window used (~124k of 200k tokens). Auto-compact triggers at 80%.

Details that would make it work well:

• Coarse is fine. If exact per-turn token counts are awkward (prompt-cache churn, mid-turn drift), buckets work: under half / over 60% / over 80%. Precision isn't the point — not being blind is.
• Only inject past a threshold. Nothing below ~50%; there's no decision to inform when the window is mostly empty, and it keeps the early-session prompt clean.
• Pair it with anti-nag guidance. The lesson from #34238 is real: nobody wants "shall we wrap up?" every third turn. The system prompt should frame the number as an input to sizing work (delegate this to a subagent, propose a fresh session at a clean boundary, summarise rather than paste) — explicitly not as a cue to interrupt the user or editorialise about session length. Grounded silence is the default; the number just makes the occasional suggestion correct instead of invented.
• Lesser alternative: a read-only GetContextUsage tool. Workable, but it costs a round trip and depends on the model knowing to ask — which is the same guessing problem one level up. Passive injection is strictly better.

Alternative Solutions

• The statusline hack (described in #18027): have the statusline script write {"ctx_pct":68,"tokens":136029,"max":200000} to a file, then have the model cat it. Requires manual setup, depends on undocumented behaviour, is stale by the time it's read, and the model has to remember the file exists.
• A custom statusline — which I run. It shows the number to me. But I'm not the one deciding whether to read a 5,000-line file into context; the model is, and it can't see the statusline.
• /context — manual, human-facing, and by the time I think to run it the expensive decision has usually already been made.
• Manual /compact — purely reactive. You reach for it after quality has already degraded.
• Existing related requests are all human-facing: #46897, #18456, #7111 (show a % in the UI), #11535, #11008 (expose usage to statusline/hooks). All good, none of them help the model. That's the gap here.

Priority

High - Significant impact on productivity

Feature Category

API and model interactions

Use Case Example

Long working session on an e-commerce ops project — a lot of files read, several MCP tool results, a couple of subagent runs. Deep into it I ask: "also audit the checkout flow for me."

The model has three sane options: do it inline, delegate it to a subagent and take back a summary, or tell me it's better as a fresh session. Which one is correct depends entirely on remaining headroom.

• Today: it picks one blind. Usually inline, because that's the default. If headroom was thin, the audit runs straight into a compact and I lose the fidelity of everything before it.
• With this feature: it sees ~78% used, says "this'll blow the window — let me run it as a subagent and bring back findings", or "start a fresh session for this one, here's the handoff." Same model, same task, decision now grounded in a number instead of a hunch.

That's the whole ask. It knows the date, the OS, the working directory, and which model it is. It should know how much room it has left.

Additional Context

Observed on v2.1.220 (Claude Code desktop app, Windows 11). Nothing in the model-visible context reports usage: the system prompt's context-management section only states that older context will be summarised as limits approach — no figure, no threshold, and no per-turn reminder carrying one.

Related, but not duplicates:

• #18027 (open) — closest existing request. Asks for context visibility plus orchestrator-pattern prompt guidance plus plan-continuation tooling. This issue is only the first third of that, and I'd argue it's the third that can ship on its own and that the other two depend on. Happy for this to be folded in there if maintainers prefer.
• #36281 (closed as duplicate) — the hallucination symptom of exactly this gap.
• #34238 (closed NOT_PLANNED) — the nagging symptom. Worth noting the two symptoms point in opposite directions and the same fix addresses both: with a real number, the model neither invents a limit nor nags about an imaginary one.
• #27914 (closed as stale) — asked for warnings and handoff-file generation on top of awareness. Also broader than this.

✍️ Filed by @afram123, drafted with Claude Code.