Document read_file compact trade-off

s08_context_compact/README.en.md

@@ -252,6 +252,12 @@ The real order in CC source `query.ts`:
 
 The teaching version's budget → snip → micro order matches this. The teaching version does not have the contextCollapse mechanism.
 
+### read_file Trade-off
+
+The teaching version's `micro_compact` replaces old `tool_result` blocks with placeholders uniformly, including `read_file`. This usually does not affect functional correctness: if the model needs the file contents later, it can read the file again. The cost is an extra tool call and potentially lower prompt cache hit rates.
+
+Claude Code does not solve this with the teaching version's simple rule. It also puts `Read` in the microcompactable tool set, but maintains a separate `readFileState`: repeated reads of unchanged files return `FILE_UNCHANGED_STUB`, and after compaction it restores recently read file contents within a budget (for example, up to 5 files, 5K tokens per file, 50K tokens total). That is a production-level cache and recovery mechanism. The teaching version does not expand into that machinery; it keeps the simpler trade-off of compacting old results and re-reading when needed.
+
 ### Full Constant Reference
 
 | Constant | Value | Source File |
@@ -282,6 +288,7 @@ CC's compression prompt has two hard requirements:
 ### Teaching Version Simplifications Are Intentional
 
 - micro_compact uses text placeholders → we don't have API-level `cache_edits` access
+- read_file is not special-cased → the teaching version accepts re-reading when needed instead of introducing readFileState and post-compaction recovery
 - Tokens estimated via character count → precise tokenizers are out of scope
 - Post-compaction recovery omitted → teaching version only keeps summary, does not auto re-attach files
 - Two auxiliary mechanisms not covered → they fall in the 10% detail category
@@ -290,4 +297,4 @@ The core design principle, cheap first, expensive last, is fully preserved.
 
 </details>
 
-<!-- translation-sync: zh@v1, en@v1, ja@v1 -->
+<!-- translation-sync: zh@v2, en@v2, ja@v2 -->

s08_context_compact/README.ja.md

@@ -252,6 +252,12 @@ CC ソース `query.ts` での実際の順序：
 
 教学版の budget → snip → micro の順序はこれと一致する。教学版には contextCollapse メカニズムがない。
 
+### read_file のトレードオフ
+
+教学版の `micro_compact` は、古い `tool_result` を一律にプレースホルダへ置き換える。`read_file` も例外ではない。これは通常、機能的な正しさには影響しない。後でファイル内容が必要になれば、モデルはもう一度そのファイルを読めばよい。代償は、追加のツール呼び出しが発生し得ることと、prompt cache のヒット率が下がり得ること。
+
+Claude Code は、この問題を教学版のような単純なルールでは処理していない。`Read` も microcompact 可能なツール集合に入れる一方で、別途 `readFileState` を維持している。変更されていないファイルの再読込では `FILE_UNCHANGED_STUB` を返し、compact 後には予算内で直近に読んだファイル内容を復元する（例：最大 5 ファイル、1 ファイル 5K token、合計 50K token）。これは本番実装向けのキャッシュと復元メカニズムである。教学版ではそこまで展開せず、「古い結果を圧縮し、必要なら再読込する」という単純な trade-off を残している。
+
 ### 完全な定数リファレンス
 
 | 定数 | 値 | ソースファイル |
@@ -282,6 +288,7 @@ CC の圧縮プロンプトには 2 つの厳格な要件がある：
 ### 教学版の簡略化は意図的
 
 - micro_compact でテキストプレースホルダを使用 → API 層の `cache_edits` 権限がないため
+- read_file は特別扱いしない → 教学版では必要時の再読込を受け入れ、readFileState と圧縮後復元の仕組みを導入しない
 - token を文字数で推定 → 精密な tokenizer は教学の対象外
 - 圧縮後のリカバリを省略 → 教学版は要約のみを保持し、ファイルの自動再付加を行わない
 - 2 つの補助メカニズムを展開しない → 10% の細部に属する
@@ -290,4 +297,4 @@ CC の圧縮プロンプトには 2 つの厳格な要件がある：
 
 </details>
 
-<!-- translation-sync: zh@v1, en@v1, ja@v1 -->
+<!-- translation-sync: zh@v2, en@v2, ja@v2 -->

s08_context_compact/README.md

@@ -252,6 +252,12 @@ CC 源码 `query.ts` 中的真实顺序：
 
 教学版的 budget → snip → micro 顺序与此一致。教学版没有 contextCollapse 机制。
 
+### read_file 的取舍
+
+教学版的 `micro_compact` 会把旧 `tool_result` 统一替换成占位符，包括 `read_file`。这通常不影响功能正确性：如果后续还需要文件内容，模型可以重新读一次。代价是可能多一次工具调用，也可能降低 prompt cache 命中率。
+
+Claude Code 没有用教学版这种简单规则解决这个问题。它把 `Read` 也放进可 microcompact 的工具集合，但同时维护 `readFileState`：重复读取未变化文件时返回 `FILE_UNCHANGED_STUB`，compact 后再按预算恢复最近读过的文件内容（例如最多 5 个文件、每个 5K token、总预算 50K token）。这是生产级实现里的缓存和恢复机制，教学版不展开，保留“压缩旧结果，必要时重新读取”的简单 trade-off。
+
 ### 完整常量参考
 
 | 常量 | 值 | 源文件 |
@@ -282,6 +288,7 @@ CC 的压缩 prompt 有两个硬性要求：
 ### 教学版的简化是刻意的
 
 - micro_compact 用文本占位 → 我们没有 API 层的 `cache_edits` 权限
+- read_file 不特殊处理 → 教学版接受必要时重新读取，避免引入 readFileState 和后压缩恢复机制
 - token 用字符数估算 → 精确 tokenizer 不在教学范围内
 - 后压缩恢复省略 → 教学版只保留摘要，不自动重新附加文件
 - 两个辅助机制不展开 → 属于 10% 的细节
@@ -290,4 +297,4 @@ CC 的压缩 prompt 有两个硬性要求：
 
 </details>
 
-<!-- translation-sync: zh@v1, en@v1, ja@v1 -->
+<!-- translation-sync: zh@v2, en@v2, ja@v2 -->