[BUG] Default totalTokensReminder (padded-countdown) shows a number unrelated to context usage — model told the user "plenty left" moments before dying at the 1M context limit

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report
• [x] I am using the latest version of Claude Code

What's Wrong?

Claude Code injects a <total_tokens>N tokens left</total_tokens> block into the model's input (in the system prompt and after tool results). Per the maintainer comment that closed #81259, the stated purpose of this feature is:

"Claude Code sends the model a running "tokens remaining" note after tool results and user turns, so it can reason about context headroom instead of guessing. You can control it with the totalTokensReminder setting in your settings file: "countdown" (remaining model context), "padded-countdown" (the default), or "off"."

The problem: in the default padded-countdown mode, the injected number has no relationship to context usage. Observed behavior (v2.1.237, no totalTokensReminder configured anywhere):

1. The value counts down within a turn, but resets to 15,000,000 on every user prompt, no matter how full the context window actually is.
2. No explanation of the number's meaning is ever given to the model. The block is just <total_tokens>N tokens left</total_tokens>.
3. The model cannot tell which mode is active — countdown (real context remaining) and padded-countdown (unrelated) produce the same format, so even a model that knows about both modes cannot interpret the number safely.

The result is worse than the situation #81259 complained about. Before this feature, the model guessed about its context (see also #85060, open, about context-budget confabulation). Now the model is handed an authoritative-looking wrong number: it reads "14,990,000 tokens left" as abundant headroom, plans long-running work accordingly, and confidently misinforms the user about its own state.

Real incident (2026-08-20): A session doing fleet orchestration was near the end of its 1M context window. The model told the user (translated from Japanese): "The budget display shows 14.99M of 15M left — still no pressure." This happened to land at a moment when the user's own context indicator in the TUI was covered by an update notification, so the human relied on the model's report and was misled about how close the session was to dying. The session hit Context limit reached shortly after. Transcript data from that session:

• Last successful API response usage: input_tokens: 26, cache_creation_input_tokens: 7,282, cache_read_input_tokens: 970,319 → 977,627 tokens ≈ 97.8% of the 1M window consumed (~22k actually left)
• <total_tokens> values injected in the same final stretch: 14,992,750 → 15,000,000 (reset on a user prompt) → 14,992,631

So the display claimed ~99.95% remaining while the real figure was ~2.2% remaining.

Also, the feature appears to be undocumented: the closing comment on #81259 points to the CHANGELOG, but the current CHANGELOG contains no mention of totalTokensReminder (nor "tokens remaining"), and the settings documentation page doesn't list it either. The maintainer comment on #81259 is, as far as I can find, the only public description.

What Should Happen?

Any of the following would fix the harmful part (ordered by preference):

1. Default to countdown — the real remaining-context number, which is what #81259 asked for and what the closing comment describes as the feature's purpose. The harness already computes it.
2. If padded-countdown must stay the default, inject one line of meaning with the number, e.g. <total_tokens>N tokens left (task budget; unrelated to context window)</total_tokens>, so the model doesn't misinterpret it as context headroom and doesn't relay it to users as such.
3. At minimum, document the setting and its modes so users can discover why their model talks about a mysterious 15M budget.

Error Messages/Logs

# Injected into model input near the end of the session that died (from the session transcript):
<total_tokens>14992750 tokens left</total_tokens>
<total_tokens>15000000 tokens left</total_tokens>   # <- reset on user prompt
<total_tokens>14992631 tokens left</total_tokens>

# Actual usage from the last successful API response in the same transcript:
"usage": { "input_tokens": 26, "cache_creation_input_tokens": 7282, "cache_read_input_tokens": 970319 }
# = 977,627 tokens consumed of a 1,000,000 window (~22k left). The session then hit "Context limit reached".

Steps to Reproduce

1. Use default settings (no totalTokensReminder configured). Start a session.
2. Ask the model to read out the current value of its <total_tokens> block. Note it.
3. Send another user message and ask again: the value has reset to 15,000,000, regardless of how much context the conversation has consumed. (Values decrease after tool results within a turn, then re-anchor on the next user prompt.)
4. Let a session grow close to the 1M context limit, then ask the model how much room it has left. It reports ~15M "tokens left" moments before the harness stops with "Context limit reached".

Environment

• Claude Code version: 2.1.237
• Platform: Anthropic API
• Operating System: Ubuntu/Debian Linux (container)
• Terminal: iTerm2
• Model: claude-fable-5 (1M context)

Related

• #81259 — the feature request this implements; the closing comment is the only public description of the setting and states the intent ("reason about context headroom instead of guessing") that the default mode does not deliver
• #85060 — open report about context-budget confabulation; the default mode manufactures the same class of confabulation in the opposite direction (overestimation), now anchored to an official-looking number

✍️ Author: Claude Code with @carrotRakko (AI-written, human-approved)