[DOCS] Prompt-caching docs do not explain mid-conversation system-block caching through gateways

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/prompt-caching

Section/Topic

“Where the cache lives” and the explanation of provider and gateway compatibility.

Current Documentation

The guide currently says:

“Custom ANTHROPIC_BASE_URL or LLM gateway: the cache lives wherever your requests are forwarded, and whether caching works depends on the gateway.”

It separately documents that system context appended mid-conversation is cached on Amazon Bedrock, Google Cloud’s Agent Platform, and Microsoft Foundry, but does not describe the newly supported gateway and custom-base-URL behavior.

What's Wrong or Missing?

Claude Code 2.1.212 improves prompt caching so the mid-conversation system block works behind LLM gateways and custom base URLs, including Bedrock, Vertex, and first-party configurations. The current wording leaves gateway users with a broad “depends on the gateway” warning and does not identify the supported behavior or the conditions a gateway must preserve.

This makes it difficult for operators to determine whether repeated system context should be cacheable in their deployment, whether a gateway is forwarding the required cache controls, and whether an uncached turn indicates a configuration problem.

Suggested Improvement

Update the caching guide to state the 2.1.212 behavior explicitly. Explain which provider and gateway paths support caching of the mid-conversation system block, what request metadata or cache-control behavior a gateway must preserve, and how users can distinguish a normal cache miss from a gateway that strips the relevant fields.

Add a small provider matrix covering the direct Anthropic API, Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, ANTHROPIC_BASE_URL, and LLM gateways, with a link to the underlying Platform prompt-caching reference.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/prompt-caching | Claude Code cache behavior and provider matrix |
| https://code.claude.com/docs/en/llm-gateway-connect | Gateway forwarding and troubleshooting context |
| https://platform.claude.com/docs/en/build-with-claude/prompt-caching | Underlying API prompt-cache semantics |

Total scope: 3 pages should align the Claude Code, gateway, and API explanations.

The compatibility improvement was released in Claude Code 2.1.212; the release notes are listed at https://code.claude.com/docs/en/changelog.