docs: clarify prompt cache stability

docs/concepts/session-pruning.md

@@ -10,7 +10,7 @@ read_when:
 
 Session pruning trims **old tool results** from the context before each LLM
 call. It reduces context bloat from accumulated tool outputs (exec results, file
-reads, search results) without touching your conversation messages.
+reads, search results) without rewriting normal conversation text.
 
 <Info>
 Pruning is in-memory only -- it does not modify the on-disk session transcript.
@@ -30,11 +30,23 @@ cache-write size, directly lowering cost.
 ## How it works
 
 1. Wait for the cache TTL to expire (default 5 minutes).
-2. Find old tool results (user and assistant messages are never touched).
+2. Find old tool results for normal pruning (conversation text is left alone).
 3. **Soft-trim** oversized results -- keep the head and tail, insert `...`.
 4. **Hard-clear** the rest -- replace with a placeholder.
 5. Reset the TTL so follow-up requests reuse the fresh cache.
 
+## Legacy image cleanup
+
+OpenClaw also runs a separate idempotent cleanup for older legacy sessions that
+persisted raw image blocks in history.
+
+- It preserves the **3 most recent completed turns** byte-for-byte so prompt
+  cache prefixes for recent follow-ups stay stable.
+- Older already-processed image blocks in `user` or `toolResult` history can be
+  replaced with `[image data removed - already processed by model]`.
+- This is separate from normal cache-TTL pruning. It exists to stop repeated
+  image payloads from busting prompt caches on later turns.
+
 ## Smart defaults
 
 OpenClaw auto-enables pruning for Anthropic profiles:

docs/plugins/bundles.md

@@ -105,6 +105,8 @@ loader. Cursor command markdown works through the same path.
   launching stdio servers or connecting to HTTP servers
 - project-local Pi settings still apply after bundle defaults, so workspace
   settings can override bundle MCP entries when needed
+- bundle MCP tool catalogs are sorted deterministically before registration, so
+  upstream `listTools()` order changes do not thrash prompt-cache tool blocks
 
 ##### Transports
 
@@ -165,6 +167,8 @@ OpenClaw registers bundle MCP tools with provider-safe names in the form
 - full tool names are capped at 64 characters
 - empty server names fall back to `mcp`
 - colliding sanitized names are disambiguated with numeric suffixes
+- final exposed tool order is deterministic by safe name to keep repeated Pi
+  turns cache-stable
 
 #### Embedded Pi settings
 

docs/reference/prompt-caching.md

@@ -120,6 +120,19 @@ For `openrouter/anthropic/*` model refs, OpenClaw injects Anthropic `cache_contr
 
 If the provider does not support this cache mode, `cacheRetention` has no effect.
 
+## OpenClaw cache-stability guards
+
+OpenClaw also keeps several cache-sensitive payload shapes deterministic before
+the request reaches the provider:
+
+- Bundle MCP tool catalogs are sorted deterministically before tool
+  registration, so `listTools()` order changes do not churn the tools block and
+  bust prompt-cache prefixes.
+- Legacy sessions with persisted image blocks keep the **3 most recent
+  completed turns** intact; older already-processed image blocks may be
+  replaced with a marker so image-heavy follow-ups do not keep re-sending large
+  stale payloads.
+
 ## Tuning patterns
 
 ### Mixed traffic (recommended default)