Add a message history and prompt cache topic guide to `agent_docs`, with matching `CI Review` checks

Merged
DO
10d ago
+158-4

Adds agent_docs/message-history-and-caching.md, a topic guide with the rules that keep message history byte-stable for the prompt cache and keep content in the channel that matches who wrote it. Each rule has a one-line reason and names the mechanism to use:

  1. History is append-only outside compaction; changed instructions and tools are appended as deltas.
  2. Request-scoped (SystemPromptPart(scope='request') via ctx.enqueue) is not request-only (request_context.messages); links the decision table in docs/capabilities/custom.md instead of copying it.
  3. Trust tiers map to channels and nothing is promoted: no untrusted content in system voice, no framework voice via ctx.enqueue(str).
  4. One voice tag (<system>), and every wrapper escapes its payload.
  5. Framework records are identified by type or metadata, never by visible text.
  6. Every computed instruction block has a stable id.
  7. Projection is deterministic (canonicalize on send, deterministic id remaps).
  8. UI round trips are faithful for everything the model sees, verified with the real JS reducers.

Rules that rely on mechanisms still in review carry a (pending #N) marker (#8188, #9405, #7891 for the framing helper, #8954) so a follow-up can drop it.

Also:

  • links the guide from agent_docs/index.md and adds one-line pointers in the core AGENTS.md, capabilities/, models/, toolsets/, ui/ and harness AGENTS.md files plus the harness agent_docs/index.md;
  • replaces the capabilities/AGENTS.md advice to put per-turn content "in the user message, tool results, or after the last CachePoint", which contradicts rules 2 and 3, and the "during a run" scoping of the no-mutation rule (the cache spans runs);
  • adds a "Message history and prompt cache" targeted check to the CI Review prompt and an Example 6 calibration pair to its review instructions. douwebot reads AGENTS.md and agent_docs/ directly, so it picks the guide up without a prompt change.

No issue: requested by a maintainer as review guardrails.

Checklist

  • No breaking changes in accordance with the version policy.
  • Any permitted compatibility impact has a label, warning, migration, release note, and exact API-check waiver.
  • PR title is fit for the release changelog.

🤖 Generated with Claude Code