Expose read-only context and cache observations to orchestrator agents

[shrreku]

Problem

An orchestrator agent can choose an exact provider instance and inspect task/thread state, but needs a supported, read-only way to inspect the context and cache observations relevant to its next action. Otherwise it must ask the human or inspect provider files, and can mistake an elapsed-time estimate for proof that a prefix is cached.

This is the agent-facing counterpart to the timer proposals in #7590 and #19469. It complements quota visibility in #15137, safe-boundary compaction in #15106, and the opt-in idle-compaction implementation proposed in #19662. It does not request a second timer UI or an automatic keepalive service.

Evidence and limits

A local metadata-only sample across two Codex accounts covered 10 selected sessions and 1,291 unique responses, with 97.10% weighted cached input. One 324,434-input response had zero cache hits, followed by five responses at 99.00% cached input. Some long-gap responses remained warm. This demonstrates why both observations and unknowns matter, not a measured native Codex TTL or subscription saving.

Claude TTL reporting already has upstream groundwork in merged #17945. Claude Code documents different request buckets and billing-dependent TTLs. A T3-owned child is not automatically a native Claude subagent bucket. OpenAI API retention documentation alone does not establish the retention used by a native Codex subscription session.

Smallest useful proposal

Expose a read-only snapshot, for example t3_thread_context_status, initially for the calling thread. Reuse existing authorization, projected usage and adapter metadata. Suggested information:

• Exact thread, run, provider-instance and model identities, plus the observation timestamp.
• Latest reported context usage and window size, with unavailable values explicit. Keep cumulative usage distinct from the latest request's context.
• Latest request's input/cache-read/cache-write/output counters where reported, preserving missing versus zero.
• Last observed provider request time, separately from UI activity or a task notification. Include a reported TTL with its source, or unknown.
• Any derived expiry estimate labelled as an estimate, with its basis and invalidation after an observed session/model/context change. Neither time remaining nor a previous cache hit guarantees a matching prefix on the next request.
• Known pending/background work and supported compaction capability, so a client can identify a safe checkpoint boundary.

The snapshot should read existing data without launching a model call, refreshing credentials, exporting prompts or touching native sessions. Returning unknown is useful. An idle process timeout must not become a cache TTL.

An agent can combine this with #15137 to recommend continue, checkpoint, compact, a minimal successor, or hold. A recommendation does not itself authorize compaction, account switching or a new writer. No automatic heartbeat, provider probing or subscription-percentage estimate is requested.

Acceptance and scope question

Provider-free fixtures should cover reported/missing TTL, cache-read-only responses, stale observations, mixed accounts, compaction/model changes, missing counters, pending work and denied access. Reading the snapshot must produce no provider invocation. Consumers should not need periodic model wakeups to maintain a countdown.

Would maintainers prefer this as a small extension to an existing thread read result, or a separate read-only tool? This is a request to agree on scope before implementation. No fresh paid reproduction was run.

Prepared with GPT-6.1 Sol through the Codex harness in T3 Code at the user's request.

[kkolodziej7]

Note

Drafted by Claude Opus 5.5 (a coordinating agent running in T3 Code) and posted from the account owner's account with their consent.

+1 for an agent-readable context snapshot of the calling thread, and for limit windows in orchestrator_capabilities (#16187).

Use case. Our coordinator agents follow written thresholds:

• compact their own thread from 200k tokens;
• hand a new wave to a fresh lead thread when the current lead is above 150k;
• move new read-only work off a provider whose usage window is at 90% or more.

T3 already shows these numbers to people (the context meter, Usage → Limits), but agents cannot read them. So we run a local helper that matches each thread to its provider session file to count tokens, and that polls the vendors' usage separately. It is extra coupling, and it breaks when a session format changes.

Smallest set we would use:

• for the calling thread: used tokens and the model's context window. Any thread by id would be a bonus.
• per provider instance: each window's used percentage and reset time, and "unavailable" when unknown.