Pre-execution token/cost estimate before approving plan-mode tasks

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

When working with large or complex tasks in plan mode, there is currently no way to know — before approving — how many tokens the plan execution will consume.

This creates a critical gap for professional and agency users:

Budget accountability: Agencies and freelancers bill AI costs to clients. Before approving a plan, they need an estimate to determine if the work is within authorized budget. Starting without a cost estimate means potentially running up charges that cannot be justified, recovered, or pre-approved by the client.

Quota management: Users on rate-limited plans (5-hour and 7-day windows) cannot make informed decisions about which tasks to prioritize when quota is limited. A large plan that consumes the remaining 5-hour window may block more urgent, time-sensitive work.

Professional risk: In a professional context, "run first, see cost later" is not acceptable. A contractor quotes before starting work. Claude Code should enable the same discipline. Professionals cannot act without facts — and right now, token cost before plan approval is a complete unknown.

Proposed Solution

Before the user confirms a plan in plan mode, display an estimated token range alongside current quota remaining:

Plan ready — estimated execution: ~8,000–12,000 tokens
5h quota remaining: 63%  |  7d quota remaining: 41%
Approve? [y/n]

Implementation options (in order of preference):

1. API-based: Use the Anthropic count_tokens endpoint on the plan content before execution begins — accurate, fast, minimal overhead
2. Heuristic range: Show a conservative min/max based on plan complexity (number of steps, tool calls, file operations implied) — no extra API call needed
3. Token budget flag: Allow --max-tokens <n> at plan approval; abort if estimate exceeds the budget

Even a rough range is significantly more useful than no estimate. The goal is not perfection — it is informed consent before commitment.

Alternative Solutions

There is currently no workaround. Once a plan is approved, execution begins and token consumption is uncontrollable. The only option is to cancel mid-execution, which may leave the codebase or system in a partial, inconsistent state.

The status line (added in recent versions) shows 5h/7d quota consumption in real time — useful, but reactive. A professional needs proactive information before the y keypress, not after.

Other AI coding tools also lack this, but that is not a reason to accept it — it is a gap across the industry that Claude Code has an opportunity to close first.

Priority

Critical - Blocking my work

Feature Category

Interactive mode (TUI)

Use Case Example

Real scenario from production infrastructure work:

1. Engineer opens plan mode and asks Claude to build a new Grafana dashboard from scratch — 20+ panels reading from InfluxDB, covering recorders, switches, UPS, and power monitoring.
2. Claude presents a plan: read existing dashboards, query InfluxDB for measurement names, generate panel JSON, deploy via Grafana HTTP API.
3. The engineer cannot know if this will cost $0.10 or $2.00, or whether it will exhaust the remaining 5-hour quota window.
4. If quota runs out mid-execution, the dashboard is in a partial state — some panels exist, some don't, no clean rollback.
5. The engineer's client needs to pre-authorize any AI tooling spend above a threshold. Without an estimate, the engineer either has to refuse to start ("I can't give you a number") or proceed on faith and reconcile after the fact.

With pre-execution estimation:

• Engineer sees "~45,000 tokens — 5h quota: 71% remaining" before approving
• Makes an informed decision: proceed now, defer to a fresh quota window, or split the plan into smaller approved chunks
• Client gets a defensible estimate before spend is committed

Additional Context

The Anthropic Messages API already exposes count_tokens which could power this with minimal overhead. The token count for a plan's expected execution can be approximated from the plan text itself plus estimated tool call overhead per step — no exotic engineering required.

The Claude Code status line already shows 5h/7d quota in real time (reactive). Pre-execution estimation completes the picture: reactive awareness (status line) + proactive awareness (plan approval) = professionals have what they need to manage costs responsibly.

This matters most in LIVE/production environments where quota exhaustion mid-task can leave systems in a partial or inconsistent state with no clean rollback path.

Acceptance criteria:

• Plan mode shows estimated token count (or range) before the user confirms
• Estimate is visible alongside current quota remaining
• Works for both Claude.ai subscribers (rate limits) and API users (cost-per-token billing)