Feature request: Compaction transparency — documented PostCompact hook, pinned facts, retention budget

Feature request: Compaction transparency — documented PostCompact hook, pinned facts, retention budget

Context

Kimi Code CLI's automatic context compaction is effective but opaque. The cost measurements are published in the sibling feature request (06-feature-request-compaction-kv-cache.md) and are not repeated here. The structural facts: the session wire carries a context.apply_compaction marker with tokensBefore/tokensAfter — 55 historical sessions carry it — but nothing is surfaced to the user or to hooks.

After a compaction, nobody can tell what survived the summary: which sections, decisions, or critical facts were dropped. Post-compaction work relies on the hope that the summary kept what mattered.

A local measurement probe (compaction-cost-probe.py) already extracts these markers from historical wires without consuming tokens; the transparency requested here (event, hook, pinning, budget) cannot be replicated locally.

Problem or Gap

1. The context.apply_compaction marker (with tokensBefore/tokensAfter) exists in the wire but is surfaced neither to the user nor to hooks.
2. There is no way to declare facts that must survive compaction — critical context is dropped silently.
3. Retention behavior is not configurable: users cannot reserve budget for a summary plus pinned facts.

Proposal

1. Visible event + documented PostCompact hook: every compaction emits a user-visible event and fires a documented PostCompact hook carrying tokensBefore/tokensAfter and the list of dropped sections.
2. Declarative pinning: a declarative mechanism (e.g. a pin: directive in AGENTS.md or in memory) marking critical facts that are guaranteed to survive compaction — the summary must re-inject pinned facts verbatim.
3. Configurable retention budget: expose in config.toml a retention budget (volume reserved for the summary + pinned facts) instead of an untunable internal behavior.

Impact

• Trust: users can see what compaction removed instead of guessing.
• Continuity: pinned critical facts survive compaction by construction.
• Control: retention becomes a configuration decision, not an internal default.

Acceptance criteria

1. Every compaction emits a visible event and fires a documented PostCompact hook with tokensBefore/tokensAfter and dropped sections.
2. A fact pinned before compaction is found verbatim in the context after compaction.
3. The retention budget is configurable in config.toml and effectively changes behavior.
4. Hook stats are correlatable with the wire's context.apply_compaction marker for the same compaction.
5. A compaction with no identifiable dropped section emits the event with an empty list (no error).
6. Pinned facts exceeding the retention budget are rejected explicitly at pin time — no silent drop.
7. A failing PostCompact hook does not break the compaction; the hook error is logged.

Start with the existing context.apply_compaction wire marker and compaction-cost-probe.py, then review the proposed AGENTS.md pin directive and config.toml retention setting. Trace how compaction events and hooks are exposed; done means meeting the seven acceptance criteria, including correlation, explicit pin rejection, and logged hook failures.