Summary / 概要

Builds on #2801 / 基于 #2801（merged / 已合并）

#2801 moved mode/approval policy descriptions out of the byte-stable system prompt into a per-turn <runtime_prompt> transient message. While it solved the prefix-cache invalidation problem, it introduced a recurring cost: the full policy text (~500 tokens) was repeated on every API request — including tool-call continuations within the same turn.

This PR restructures the information architecture: static policy descriptions now live in the frozen system-prompt prefix (sent once per session, cache-hit thereafter), and only a minimal tag is sent per turn.

#2801 将 mode/approval 策略描述从稳定的 system prompt 中移出，改为 per-turn transient message。虽然解决了 prefix-cache 失效问题，但引入了新成本：完整策略文本（~500 tokens）在每个 API 请求都重复发送，包括同一 turn 内的 tool-call 续轮。

本 PR 重构信息架构：静态策略描述放入 frozen system-prompt prefix（每 session 发送一次，后续请求全部 cache hit），每 turn 只发送最小 tag。

Scope / 范围

• Add render_runtime_policy_reference() — a static reference block containing all mode + approval policy descriptions, plus a tag-interpretation protocol. / 新增 render_runtime_policy_reference()，生成包含所有 mode + approval 策略描述的静态参考块，附带 tag 解释协议。
• Insert the reference into the system prompt above the volatile-content boundary (frozen prefix region). / 将 reference 插入 system prompt 的 volatile-content boundary 之上（frozen prefix 区域）。
• Simplify runtime_prompt_text() from ~500-token XML block to ~16-token self-closing tag: <runtime_prompt visibility="internal" mode="yolo" approval="auto"/>. / 将 runtime_prompt_text() 从 ~500-token XML 块简化为 ~16-token 自闭合标签。
• Fix markdown heading hierarchy in 6 .md files (## → #####) so they nest correctly under #### in the reference section. / 修正 6 个 .md 文件的标题层次 (## → #####)，确保在 reference 章节中正确嵌套。
• Remove unused legacy functions: mode_prompt(), approval_prompt_for_mode(), mode_change_runtime_message(). / 删除不再使用的遗留函数。
• Simplify Op::ChangeMode — no longer persists a separate mode_change event; the next turn tag carries the current mode. / 简化 Op::ChangeMode，不再持久化额外的 mode_change 事件，下一轮 tag 即携带当前 mode。
• Update & rename affected tests (2 tests rewritten, 5 assertions updated). / 更新并重命名受影响的测试（2 个测试重写，5 处断言更新）。

Not in this slice / 不涉及

• Policy content is byte-identical; only heading levels changed. / 策略内容本身未修改，仅标题层次变更。
• Tag-interpretation protocol unchanged — already established in the system prompt reference section. / 不修改 tag 解释协议，已通过 system prompt 中的参考章节确立。
• A/B testing model behavior with the new tag format — follow-up work. / 新 tag 格式的 A/B 测试属于后续工作。

Tradeoff / 权衡

Core tradeoff: system prompt grows by 1,325 tokens (one-time miss) in exchange for saving 471 tokens per API call. Net positive after 3 API calls. The model shifts from receiving explicit policy text every turn to looking up rules by tag — the reference section includes an explicit protocol instruction. Structural correctness is verified by tests; production behavioral stability needs follow-up observation.

核心权衡：system prompt 膨胀 1,325 tokens（仅首次 miss），换取每轮节省 471 tokens。3 次 API 调用后净正收益。模型从"每轮显式接收策略描述"改为"按 tag 查表"——参考章节中有明确的协议指引。结构性正确性已由测试验证；生产行为稳定性需要后续观测。

Builds on / 基于

• feat(engine): project mode prompts per request #2687 — first prototype, closed / 第一个原型，已关闭
• feat(cache): project mode prompts per request #2801 (feat(cache): project mode prompts per request) — merged predecessor that established the per-turn <runtime_prompt> architecture / 已合并的前置 PR，确立了 per-turn <runtime_prompt> 架构

Validation / 验证

cargo fmt --all                                   # ✅ passed / 通过
cargo clippy -p codewhale-tui -- -D warnings       # ✅ passed (0 warnings)
cargo test -p codewhale-tui -- runtime_prompt mode_change  # ✅ 9 passed, 0 failed
cargo check -p codewhale-tui                       # ✅ passed / 通过

Files changed / 改动文件: 9 files, +143 / −170 lines

sequenceDiagram
    participant Engine
    participant SP as "System Prompt (frozen prefix)"
    participant API as "LLM API"
    participant Model

    Note over SP: render_runtime_policy_reference() contains all mode and approval descriptions. Sent once per session.

    Engine->>API: Request (system_prompt + session_messages + runtime_tag)
    Note over API: system_prompt is byte-stable, cache hits after first call
    API->>Model: system_prompt cached ~9325 tokens
    API->>Model: session_messages history
    API->>Model: runtime_prompt_message() ~16 tokens misses every time
    Model->>Model: Looks up mode and approval rules from system prompt reference
    Model->>API: Response or tool calls
    API->>Engine: Response

    Note over Engine: Op::ChangeMode received
    Engine->>Engine: "self.current_mode = NewMode"
    Engine->>Engine: emit_session_updated()
    Note over Engine: Next request tag carries new mode value automatically

_{Reviews (3): Last reviewed commit: "test: add runtime_policy_reference compo..." | Re-trigger Greptile}