Prompt cache comments corrected to reflect actual behavior
Documentation for prompt caching logic has been tightened across four files, removing overstated guarantees and adding nuanced context about tradeoffs developers should understand.
The prompt cache comments scattered across the agent runtime contained assertions that didn't hold up under scrutiny. Previously, comments claimed certain operations left cache "intact" or kept arrays "byte-identical" — language that implied stronger guarantees than the code actually provides.
Four files have been updated to reflect reality. Comments no longer claim the tools array is guaranteed stable across turns (it's "usually stable but not guaranteed"). The image pruning logic, once framed as preserving sessions "byte-identical," now accurately describes itself as reducing churn while depending on replay sanitizer idempotency. References to "legacy sessions" have been dropped in favor of behavior that applies to all sessions.
The tradeoff is now documented too: when compacting tool outputs to save context, the model loses recent tool output rather than old — a meaningful distinction for anyone tuning prompt cache efficiency.
In the agent core pipeline.
View Original GitHub Description
Summary
Correct comments that overstated the prompt-cache benefits of #58036, #58037, and #58038. No behavior changes — only comments.
tool-result-context-guard.ts: "prefix stays intact" → "more of the prefix survives"; note the model-quality tradeoff (loses recent tool output instead of old).pi-bundle-mcp-materialize.ts: add "usually stable but not guaranteed" context; note that collision suffixes are iteration-order-dependent and the sort cannot fix name collisions.history-image-prune.ts: drop misleading "legacy sessions" framing (this runs on all sessions); replace overstated "byte-identical" cache claim with accurate "reduces churn" + note dependency on replay sanitizer idempotency; document that text-only turns consume the window; fix "user turns" → "user/toolResult turns".attempt.ts: matching callsite comment update.
Test plan
- Comment-only changes, no behavior change —
pnpm checkpasses.
🤖 Generated with Claude Code