docs(auto-review): scope the prefix-cache claim and record cache limitations

packages/experimental/auto-review/README.i18n.yaml

@@ -36,14 +36,14 @@
   en: 7ec217b1012cd8fa
   zh: 6188796b4990f2ef
 /deepseek-ai-dsh-experimental-auto-review/model-experience/per-call-reviewer/what-the-model-sees:
-  en: b3e50d879db13221
-  zh: 81f9c8f2793bea0d
+  en: 4c3b4d64a80819c8
+  zh: 628e3b9c080d4a1a
 /deepseek-ai-dsh-experimental-auto-review/model-experience/per-call-reviewer/token-effect:
   en: 9c3e575c061d53fe
   zh: 74db1c5a77b2d2a7
 /deepseek-ai-dsh-experimental-auto-review/model-experience/per-call-reviewer/kv-cache-effect:
-  en: 17d18c4768fc3653
-  zh: 30a5e3b1337e9bd4
+  en: ea01888d6333fafa
+  zh: 77e623e2eeb39ae4
 /deepseek-ai-dsh-experimental-auto-review/model-experience/tool-denial:
   en: f9b4d7b686f14fc5
   zh: a2fac9a8eaf5e2a3
@@ -57,8 +57,8 @@
   en: 8da1089dee147f94
   zh: 87361347bfd10c6c
 /deepseek-ai-dsh-experimental-auto-review/known-limitations-and-deferred-work:
-  en: 5682fe41fcc459ab
-  zh: fa15b23a21d18ff4
+  en: b95137cc8c38abc2
+  zh: c7c993960017e0d5
 /deepseek-ai-dsh-experimental-auto-review/known-limitations-and-deferred-work/dev-note:
   en: e67f633dc6fe7773
   zh: 3bb0c20c93f16f98

packages/experimental/auto-review/README.md

@@ -84,7 +84,7 @@ Unloading closes selection and review admission, migrates live Auto Sessions to
 
 #### What the model sees
 
-The reviewer uses the latest `request/header.config` provider and model with the shipped adapter's default reasoning. Its fixed `REVIEW_POLICY` replaces human approval for exactly one action: allow executes immediately with Full access. The other four sections contain only the retained facts described above. It returns one strict JSON text object with `risk` and `decision`; deny may include a string `reason`. Reasoning blocks may precede that single text block. Only `low + allow`, `medium + allow/deny`, and `high + deny` are valid.
+The reviewer uses the latest `request/header.config` provider and model with the shipped adapter's default reasoning. Its fixed `REVIEW_POLICY` replaces human approval for exactly one action: allow executes immediately with Full access. The other three sections contain only the retained facts described above. It returns one strict JSON text object with `risk` and `decision`; deny may include a string `reason`. Reasoning blocks may precede that single text block. Only `low + allow`, `medium + allow/deny`, and `high + deny` are valid.
 
 #### Token effect
 
@@ -92,7 +92,7 @@ One additional model request per supported call, without caching, retries, trunc
 
 #### KV Cache effect
 
-Each review's text extends the previous review's text through its last history entry, because history keeps surface order and the pending action comes last; a provider's prefix cache therefore reuses the policy and earlier history. Compaction, a cwd change, and an earlier history entry leaving the surface end that reuse. Auto adds no dedicated runtime context or mode-switch prompt to the main agent.
+Each review's text extends the previous review's text through its last history entry, because history keeps surface order and the pending action comes last; a route that caches by prompt prefix therefore reuses the policy and earlier history. Compaction, a cwd change, and an earlier history entry leaving the surface end that reuse. Auto adds no dedicated runtime context or mode-switch prompt to the main agent.
 
 ### Tool denial
 
@@ -117,6 +117,8 @@ The denial appends an ordinary tool result; it does not rewrite earlier context
 - Model classification can be wrong. There are no deterministic tool exemptions, persistent grants, configurable policy, or retry layer.
 - In-process Auto children review their own calls. Out-of-process children retain their native permission systems after the parent delegation call is allowed.
 - The reviewer reads the Session action history through the deprecated synchronous `snapshotEvents()` reader under a line-scoped waiver. Prior calls, PTC starts, and the direct parent's initial prompt have no projection or paged reader yet, so the migration stays deferred by [the synchronous-read decision](../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).
+- Routes that cache only at explicit `cache_control` markers mark the end of the review request, so they reuse the policy but not the history. Reusing history needs a cache-marker option in the LLM request API.
+- Review requests carry no `sessionId`, so OpenAI routes receive no `prompt_cache_key`. Passing it would also attach the DeepSeek session-log upload and session headers to review requests, which first needs a request-purpose decision.
 
 <a id="dev-note"></a>
 ### Dev Note

packages/experimental/auto-review/README.zh.md

@@ -84,7 +84,7 @@ Reviewer 从当前 Session surface 与待执行调用重建四个分区：固定
 
 #### 模型看到什么
 
-Reviewer 使用最新 `request/header.config` 的 provider 与模型，并沿用 shipped adapter 默认 reasoning。固定 `REVIEW_POLICY` 替代恰好一个动作的人工审批：allow 后立即以 Full access 执行。其余四个分区只包含上文列出的保留事实。响应为一个严格 JSON text 对象，包含 `risk` 与 `decision`；deny 可附字符串 `reason`。Reasoning blocks 可以位于这唯一 text block 之前。只有 `low + allow`、`medium + allow/deny` 和 `high + deny` 合法。
+Reviewer 使用最新 `request/header.config` 的 provider 与模型，并沿用 shipped adapter 默认 reasoning。固定 `REVIEW_POLICY` 替代恰好一个动作的人工审批：allow 后立即以 Full access 执行。其余三个分区只包含上文列出的保留事实。响应为一个严格 JSON text 对象，包含 `risk` 与 `decision`；deny 可附字符串 `reason`。Reasoning blocks 可以位于这唯一 text block 之前。只有 `low + allow`、`medium + allow/deny` 和 `high + deny` 合法。
 
 #### Token 影响
 
@@ -92,7 +92,7 @@ Reviewer 使用最新 `request/header.config` 的 provider 与模型，并沿用
 
 #### KV Cache 影响
 
-历史保持 surface 顺序且待审动作位于最后，因此每次评审文本在上一次评审的最后一条历史条目之前都与上一次相同；provider 的前缀缓存可以复用策略与先前历史。Compaction、cwd 变化，以及较早历史条目离开 surface 会终止这种复用。Auto 不向主 agent 增加专门 runtime context 或模式切换提示词。
+历史保持 surface 顺序且待审动作位于最后，因此每次评审文本在上一次评审的最后一条历史条目之前都与上一次相同；按 prompt 前缀缓存的路由因此可以复用策略与先前历史。Compaction、cwd 变化，以及较早历史条目离开 surface 会终止这种复用。Auto 不向主 agent 增加专门 runtime context 或模式切换提示词。
 
 ### 工具拒绝
 
@@ -117,6 +117,8 @@ Reviewer 使用最新 `request/header.config` 的 provider 与模型，并沿用
 - 模型分类可能出错。不提供确定性工具豁免、持久 grant、可配置策略或重试层。
 - 进程内 Auto child 独立审查自身调用。进程外 child 在父委派调用获准后保留原生权限系统。
 - reviewer 在带行级豁免的情况下，通过已废弃的同步 `snapshotEvents()` 读取 Session 动作历史。此前的调用、PTC start 与直接父级的初始 prompt 目前都没有投影或分页读取方，因此迁移按[同步读取决策](../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.zh.md)继续延期。
+- 只在显式 `cache_control` 标记处缓存的路由会把标记放在评审请求末尾，因此只复用策略而不复用历史。复用历史需要 LLM 请求 API 提供缓存标记选项。
+- 评审请求不携带 `sessionId`，因此 OpenAI 路由不会收到 `prompt_cache_key`。传入它还会让评审请求附带 DeepSeek session-log 上传与 session header，需要先做请求用途决策。
 
 <a id="dev-note"></a>
 ### 开发备注