prompt-caching

Use provider-reported cache reads and writes as evidence. Continuation IDs, prewarm readiness, predictions, keys, and latency do not prove a hit. Verify the active endpoint and usage mapping rather than assuming public-API parity.

Design for a small, stable static prefix before adding capabilities. Prefer code-mode or deferred tool discovery over loading every schema upfront. Keep available capabilities discoverable while revealing their current arguments on demand. Supply tool-specific instructions through supported mid-session system or developer messages, help, or tool results instead of rewriting the prefix. Do not preload instructions merely because a tool may become relevant later.

Locate the first unexplained miss

• For a reported miss, start with the transition and adjacent provider calls, not an aggregate hit ratio. Expand lifecycle coverage when shared state or an explicit audit requires it. An agent turn may contain several requests. Mark deliberate model, reasoning, mode, prompt, tool, compaction, and history boundaries first.
• Compare final provider requests in order: system and developer instructions, ordered tool contracts, ordered input items and their identities, structured-output definitions, then lane and continuation properties. Session logs and source strings are not the wire payload.
• Trace the first divergence backwards through the actual preparation and rewrite chain. Identify the owner and capture event of each consumed snapshot, its completed hooks, lane, consumers, and invalidators. Correct bytes captured before authoritative preparation are stale. Use the latest completed final request in the same lane, not session-start state. Guard against late asynchronous work overwriting a newer lane.
• Adding context and starting a prepared run are different operations. Verify hook coverage for the implicated kickoff and queued paths. An idle check is not a reservation. Use an atomic route or revalidate at invocation.
• Prove the local mechanism in isolation, then exercise the affected multi-turn boundary in the user's complete extension setup. A later extension may change the same prompt, tools, or history.