diff --git a/CHANGELOG.md b/CHANGELOG.md index 27420fc1..a721437e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,35 @@ All notable changes for the ContextGuard plugin are documented here. ## [Unreleased] -_No unreleased changes._ +- **Corrected: the 81.5% figure below is wrong, and the fix that revealed it has + landed.** The 0.13.0 entry justifies making the Bash escrow the default with + "81.5% of new tokens per turn landing right after a Bash result". That table + had two defects. `last_result` was reset only per file, so a turn with no new + tool result inherited the previous turn's label; and the per-turn snapshot was + taken on every accepted row and cleared each time, while the usage reducer + selects the last row of a response group, so a multi-row response read an + already-cleared snapshot. Both are fixed. On the same kind of local corpus the + corrected table reads `no_tool_result` about 72% and Bash about 18%, and + `multi_result_turns` goes from roughly 108 to roughly 2,150. A local transcript + directory grows while you use it, so these are the shape of the correction + rather than fixed figures; the method is in `docs/safety-reference.md`. + + **What the corrected table does and does not say about the escrow default.** + Turns divide on a second axis: whether the cached prefix was written or + extended. Among the incremental turns, where `cache_creation` grows roughly + with what just entered the context, Bash still ranks first at about 69%. That + is a ranking on one corpus, not a measured saving, and it is the narrower claim + the default now rests on. + + The prefix-write turns are about 77% of `cache_creation`. Nothing that only + trims a single tool result changes those turns, because their size tracks the + whole context at that moment — though a hook that keeps the context smaller + over a session does reduce what a later rewrite has to write. The audit now + reports them as their own `cold_start` / `cache_rewrite` / `incremental` + fields. + + Historical entries below keep the text they were published with; where an + affected figure appears, a pointer to this correction was added beside it. ## [0.14.0] - 2026-09-05 @@ -53,7 +81,8 @@ savings figure; the new audit sections exist so you can measure your own. command; in-budget output passes through untouched whether the command succeeded or failed. Local transcripts showed 81.5% of new tokens per turn landing right after a Bash result, so this is the surface the default now - covers. `--artifact-receipt` therefore means escrow-on-overflow; use + covers. (That figure was later found to be an artifact of two attribution + defects; see the correction under Unreleased.) `--artifact-receipt` therefore means escrow-on-overflow; use `--digest-always` to force a receipt for small output. - **Audit attributes new tokens to the preceding tool.** `new_tokens_per_turn` gains `by_preceding_tool` (which tool's result preceded each turn's diff --git a/plugins/context-guard/skills/audit/SKILL.md b/plugins/context-guard/skills/audit/SKILL.md index 3f2367fd..e9281cb3 100644 --- a/plugins/context-guard/skills/audit/SKILL.md +++ b/plugins/context-guard/skills/audit/SKILL.md @@ -27,7 +27,7 @@ fi Report: - observed token buckets: input, output, cache_read, cache_creation; -- new tokens per turn (cache_creation distribution) and the "by preceding tool_result" table: this is the quantity billed under prompt caching, so lead with the tool that precedes most of it; +- new tokens per turn (cache_creation distribution) and the "by preceding tool_result" table: this is the quantity billed under prompt caching. The table covers every counted turn, so read the `cold_start` / `cache_rewrite` / `incremental` fields beside it before naming a tool. Turns that wrote the cached prefix track context size at that moment rather than what a tool just returned, so trimming one result does not change them. When those turns dominate, say so instead of naming the table's top tool; - model distribution; - query_source distribution: main, subagent, auxiliary; - top transcript files and commands observed;