[FEATURE] Function hooks: include the status line's prompt_cache figures in $.session.usage() and session.measure

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

A function-hooks plugin (mod) can read the context window, the rate-limit windows and the session cost through $.session.usage() and the session.measure event. It can't read the prompt cache state, which the status line command does receive.

On 2.1.290 the status line JSON carries a prompt_cache object with these keys:

warm, caching_observed, ttl, expires_at, requests, misses, expected_rebuilds,
hit_ratio, cache_write_tokens, miss_recache_tokens, last_miss_at,
last_miss_cause, miss_causes, recache_tokens_if_cold

The plugin API declarations written by the same build (claude-code.d.ts, "Written by Claude Code 2.1.290") give SessionUsage the fields startedAt, context, rateLimits and cost, and SessionMeasureInput the fields context, rateLimits, cost and changed. Neither has anything about the cache.

This matters most where there is no status line. A session started by the VS Code extension runs no status line command, but function hooks do load there: a plugin loaded through CLAUDE_CODE_PLUGIN_DIRS received session.measure in a session whose entrypoint is claude-vscode, with the context fill and both rate-limit windows. So in those sessions a plugin is the only in-process source of these figures, and the cache state is the one status-line figure it cannot get.

Some of it can be rebuilt, but not all:

• turn.step resolves with cache_read_input_tokens and cache_creation_input_tokens per request, so a plugin can count a hit ratio and misses itself.
• expires_at, recache_tokens_if_cold, the miss causes and expected_rebuilds are not derivable from that. The model-switch hooks do carry cache_ttl, prompt_cache_warm and estimated_cache_write_usd, but only at the moment of a switch.

Proposed Solution

Return the same figures the status line gets, under one key, from both places:

• $.session.usage(): add promptCache to SessionUsage.
• session.measure: add promptCache to SessionMeasureInput, and a 'promptCache' unit to changed when it differs from the last measurement.

Absent where the session has made no request yet, so existing plugins are unaffected.

Alternative Solutions

• Count from turn.step usage. Gives the hit ratio only, and repeats bookkeeping the engine already does (which requests count, what a miss is).
• Read the transcript and recompute. Same limits, plus parsing JSONL from a plugin.
• Have the status line command write the object to a file for other tools to read. This is what I do in terminal sessions; it is not available in sessions that run no status line command.

Priority

Low - Nice to have

Feature Category

Developer tools/SDK

Use Case Example

A session status display shows, per session, the cache hit ratio, the time left until the cache expires, and what it would cost to rebuild if it goes cold (recache_tokens_if_cold). That last pair is what tells a user whether to send the next prompt now or accept a full re-cache after a break.

In a terminal session the display reads these from the status line's prompt_cache. In a VS Code extension session it has to estimate them from the transcript. With promptCache on session.measure, a small plugin could write the measured figures in both kinds of session, and the display would show the same numbers the engine has.

Additional Context

• Claude Code 2.1.290, Windows 11. Checked in a CLI session (terminal) and in a VS Code extension session.
• The status line keys above are from the actual stdin of a status line command on 2.1.290.
• Function hooks are marked early access in the declarations, so this is feedback on the surface as it stands. Related: #94424 (an event when usage changes, which session.measure now provides), #91870, and #95783 (asks the desktop app to show the same prompt_cache figures).