[DOCS] `--resume` prompt cache behavior with deferred tools, MCP servers, and custom agents is undocumented

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/common-workflows

Section/Topic

"Resume previous conversations" section

Current Documentation

The current documentation explains how to resume sessions:

When starting Claude Code, you can resume a previous session: - claude --continue continues the most recent conversation in the current directory - claude --resume opens a conversation picker or resumes by name - claude --from-pr 123 resumes sessions linked to a specific pull request

There is no mention of how --resume interacts with prompt caching, nor how configurations involving deferred tools (MCP tool search), MCP servers, or custom agents affect prompt cache behavior when resuming.

What's Wrong or Missing?

The docs do not explain the prompt caching behavior of resumed sessions. Specifically:

1. Users are not told that resuming a session is designed to carry over prompt cache continuity from the previous session, enabling cost savings on the first request.
2. Users who configure deferred tools (via ENABLE_TOOL_SEARCH), MCP servers, or custom agents have no documentation warning that these configurations interact with how prompt cache headers are applied on session resume.
3. There is no documentation indicating that a full prompt-cache miss on the first resumed request is abnormal behavior — users experiencing it have no way to know whether it is expected or a bug.

A regression introduced in v2.1.69 and fixed in v2.1.90 caused --resume to produce a full prompt-cache miss on the first request for users with any of these three configurations. Because the expected behavior was never documented, users had no way to identify this as a regression or understand the cost impact.

Suggested Improvement

Add a note under "Resume previous conversations" in common-workflows that explains prompt cache continuity:

Prompt cache and resumed sessions When you resume a session with --resume or --continue, Claude Code preserves prompt cache continuity so the first request in the resumed session benefits from the previous session's cached context. This reduces cost and latency compared to starting a new session. This cache carryover applies regardless of whether you use MCP servers, deferred tools (tool search), or custom agents configured via plugins or the Agent SDK.

Additionally, the --resume row in the CLI reference (cli-reference.md) could note: "Resumes with prompt cache continuity from the previous session."

Impact

Medium - Makes feature difficult to understand

Additional Context

Related documented features:

• DISABLE_PROMPT_CACHING and per-model variants (DISABLE_PROMPT_CACHING_HAIKU, etc.) in env-vars
• ENABLE_PROMPT_CACHING_1H_BEDROCK for Bedrock 1-hour TTL
• Deferred tools / tool search documented in mcp.md

The cost savings from prompt caching are significant (up to 90% reduction on cache hits). Users adopting --resume for agentic or automation workflows reasonably expect this benefit to apply, but have no documentation confirming it or explaining when it may not.