[FEATURE]: Expose the remaining context budget to the agent #59531

Problem

In the OpenCode 2.1.4 session below, the session's stored system messages contain no remaining-budget, usage, or token
figure, and no assistant record carries one either. An agent therefore cannot tell "near the limit" from "well inside
the window". That session concluded its budget was exhausted while its per-request context measured about half the
model's window, and then changed how it worked — one step per reply instead of continuing the task.

Measured case

Environment: OpenCode 2.1.4 (opencode --version; Homebrew formula opencode-v2), macOS; model
opencode-go/deepseek-v4.1-flash with limit.context 1,000,000 and limit.output 384,000, from the provider catalog
the CLI ships.

A long build session (289 assistant steps) ended two of its turns with assistant prose stating that its session budget
was exhausted — at 09:32:16 and 09:33:34 local, translated: "the budget of this session is exhausted" — and continued one
work step per user reply instead of stopping. Over the preceding interval the owner sent seven replies, five of them a
bare "continue" (translated). Per-request usage recorded for those turns: input 56–2,594 tokens plus cache.read
527,360–540,032 — roughly 530–540k cached input tokens, about 54 % of the 1,000,000-token window.

The session's record:

• instructions received: the session stores 13 system messages — instruction notices for the Code Mode catalog, the
  date, available skills, and AGENTS.md edits — and none carries a remaining-budget, usage, or token-count field;
• no step limit: opencode debug agents reports steps unset for all 18 agents;
• no compaction: the session's time_compacting is null;
• no truncation: turn finishes are 272 tool-calls and 17 stop, none length, and no turn carries an error;
• no provider quota response: no 429 or usage-limit body appears in the session, and its recorded cost is $0.605.

The owner then invoked a pause command, which persisted the session state, and a new session continued the work.

Proposed solution

Expose the session's remaining context budget to the agent — in the system prompt, a system reminder, or a read-only tool
— or state explicitly that no measurement is available. Either lets an agent distinguish "near the limit" from "well
inside the window" instead of inferring a limit. A small tool schema costs a fixed handful of tokens on every request;
the reading itself costs nothing until it is called, and an explicit "unavailable" is the minimum viable form.

What this case does not establish

• whether the missing visibility caused the assessment — this is one session on one provider;
• whether the statement referred to the context window rather than some other budget the model inferred; the record rules
  out a step limit, compaction, truncation, and a provider quota, not every conceivable budget;
• whether an account or provider limit outside the recorded session was involved; the record shows none;
• whether other models or providers behave the same way.

Related

• [FEATURE]: Expose context budget information to agents #19471 — asked for agent-facing budget exposure; github-actions[bot] closed it not_planned after 60 days of
  inactivity, inviting a new issue if the topic is still relevant. This is that issue, with the measurement it lacked.
• [FEATURE]: Adding a session stat command to allow programmatic access to context size and other info for a specific session #19045 — closed; proposed a stat CLI command reporting session size after the fact, not the remaining budget
  available to the agent during a turn.
• [FEATURE]: Add a per-turn context drift inspector #58459 — open; a per-turn context drift inspector, which diagnoses why the context changed rather than telling the
  agent how much remains.
• compaction: 1M-context sessions never auto-compact before the provider returns HTTP 400, and the 400 is not treated as context overflow #50574 — open; 1M-context sessions not auto-compacting before a provider 400 (a different subject: compaction sizing).
• models: allow model variants to override limit (context/output) #56582 — open; model variants overriding the context/output limit (a different subject: configuration).