From 3a0a8461b8c67c98bae4abca901428c25e4a5955 Mon Sep 17 00:00:00 2001 From: Coden Date: Sun, 6 Sep 2026 21:43:54 +0900 Subject: [PATCH 1/3] =?UTF-8?q?docs:=200.13.0=20=EC=9D=98=2081.5%=20?= =?UTF-8?q?=EC=A3=BC=EC=9E=A5=EC=9D=84=20=EC=A0=95=EC=A0=95=ED=95=98?= =?UTF-8?q?=EA=B3=A0,=20=EC=82=B4=EC=95=84=EB=82=A8=EB=8A=94=20=EA=B7=BC?= =?UTF-8?q?=EA=B1=B0=EB=A5=BC=20=EB=8C=80=EC=8B=A0=20=EC=A0=81=EB=8A=94?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 0.13.0 항목은 Bash escrow 를 기본으로 만든 근거로 "새 토큰의 81.5% 가 Bash 결과 직후에 온다" 를 든다. 그 표에 결함이 둘 있었고 #376 에서 고쳤다. last_result 가 파일 단위로만 초기화돼 새 도구 결과가 없는 턴이 앞 턴의 라벨을 물려받았고, 스냅샷은 accepted 행마다 찍히고 비워지는데 reducer 는 응답 그룹의 마지막 행을 고르므로 여러 행으로 나뉜 응답은 이미 비워진 스냅샷을 읽었다. 교정하면 no_tool_result 약 72%, Bash 약 18% 이고 multi_result_turns 는 약 108 에서 약 2,150 으로 간다. 중요한 것은 escrow 기본값 결정 자체는 다른 근거로 살아남는다는 점이다. 턴은 두 번째 축으로도 갈린다. 캐시 접두사를 다시 썼는가, 이어 붙였는가. 도구가 돌려준 양에 비례해 과금되는 것은 incremental 턴뿐이고, 그 안에서는 Bash 가 여전히 약 69% 를 선행한다. 접두사를 쓴 턴은 cache_creation 의 약 77% 인데 어떤 도구 훅도 줄일 수 없고, 이제 audit 이 cold_start / cache_rewrite / incremental 필드로 따로 보고하며 권고에서도 그 사실을 말한다. 발행된 0.13.0 항목 본문은 고치지 않고 정정을 가리키는 한 줄만 덧붙였다. 이미 나간 릴리스 노트를 조용히 다시 쓰지 않기 위해서다. 수치는 살아 있는 디렉터리에서 나오므로 반올림해 적고 방법은 safety-reference 를 가리킨다. 이 세션 안에서도 같은 스크립트가 76.7 에서 76.9 로 움직였다. audit 스킬 문서도 고쳤다. "가장 많이 선행한 도구를 앞세우라" 는 지시가 접두사 쓰기가 우세한 코퍼스에서 틀린 곳을 가리킨다. 세 필드를 먼저 읽고 incremental 턴이 도구를 가리킬 때만 도구를 앞세우도록 바꿨다. 검증: 인용한 네 수치를 병합된 main 에서 재측정해 확인. tests.test_contextguard_stage2_feasibility + standing_cost 13건 OK, ci_test_gate fast 76건 OK, prepublish_check --skip-tests OK, preflight 경고 없음. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01DE3AupXcyv64SEuQeTckSh --- CHANGELOG.md | 26 +++++++++++++++++++-- plugins/context-guard/skills/audit/SKILL.md | 2 +- 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 27420fc1..bbefc330 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,28 @@ 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`. + + **The escrow default itself survives, on a different figure.** Turns divide on + a second axis: whether the cached prefix was written or extended. Restricted to + the incremental turns — the only ones that bill in proportion to what a tool + returned — Bash still precedes about 69% of new tokens. The prefix-write turns, + about 77% of `cache_creation`, are not something any tool hook can reduce, and the + audit now reports them as their own `cold_start` / `cache_rewrite` / + `incremental` fields and says so in its recommendation. + + Historical entries below are left as they were published. ## [0.14.0] - 2026-09-05 @@ -53,7 +74,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..2b29a965 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. Read the `cold_start` / `cache_rewrite` / `incremental` fields beside it before naming a tool: turns that rewrote the cached prefix track context size, not what a tool returned, and no hook reduces them. Lead with a tool only when the incremental turns point at one; - model distribution; - query_source distribution: main, subagent, auxiliary; - top transcript files and commands observed; From dce51a793a6cdf1e4de182ed3cccac3344727e31 Mon Sep 17 00:00:00 2001 From: Coden Date: Sun, 6 Sep 2026 21:52:49 +0900 Subject: [PATCH 2/3] =?UTF-8?q?docs:=20GLM=20=EB=A6=AC=EB=B7=B0=20blocker?= =?UTF-8?q?=20=E2=80=94=20"=EC=96=B4=EB=96=A4=20=EB=8F=84=EA=B5=AC=20?= =?UTF-8?q?=ED=9B=85=EB=8F=84=20=EC=A4=84=EC=9D=BC=20=EC=88=98=20=EC=97=86?= =?UTF-8?q?=EB=8B=A4"=20=EC=9D=98=20=EB=B2=94=EC=9C=84=EB=A5=BC=20?= =?UTF-8?q?=ED=95=9C=EC=A0=95=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GLM 이 정확히 짚었다. "no tool hook can reduce them" 은 무제한 보편 부정인데 측정된 바 없고 턴 간 효과를 보면 거짓이다. 컨텍스트를 작게 유지하는 훅은 이후 턴의 접두사 크기를 줄이고, 그것이 곧 재작성 비용이다. 이 플러그인의 escrow 가 바로 그런 종류다. 이제 이렇게 적는다. "하나의 도구 결과만 잘라내는 것으로는 그 턴들이 달라지지 않는다. 크기가 그 시점의 컨텍스트 전체를 따라가기 때문이다. 다만 세션 내내 컨텍스트를 작게 유지하는 훅은 나중 재작성이 써야 할 양을 줄인다." 같은 검토에서 나온 나머지도 반영했다. - "the only ones that bill in proportion to what a tool returned" 의 only 를 뺐다. incremental 턴에도 도구 결과가 아닌 텍스트가 붙고, 재작성 턴의 새 접미사에도 도구 반환물이 들어간다. - "escrow default itself survives" 를 순위 서술로 낮췄다. 한 코퍼스에서의 순위이지 측정된 절감이 아니라는 것을 문장 안에 적었다. - SKILL.md 의 지시가 실행 불가능했다. by_preceding_tool 표는 모든 턴을 덮는데 "incremental 턴이 도구를 가리킬 때만" 을 그 표만으로 판단할 수 없다. 표가 전 턴 기준임을 밝히고, 접두사 쓰기가 우세하면 표의 1위를 지목하지 말고 그 사실을 말하라고 바꿨다. 같은 문구가 claude_transcript_cost_audit.py:3365 의 권고 텍스트에도 있다. 그 파일은 Gate-B 동결이라 별도 세대로 고친다. 검증: tests.test_contextguard_stage2_feasibility + standing_cost 13건 OK, ci_test_gate fast 76건 OK, sync_plugin_copies --check 동기화 확인. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01DE3AupXcyv64SEuQeTckSh --- CHANGELOG.md | 20 +++++++++++++------- plugins/context-guard/skills/audit/SKILL.md | 2 +- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bbefc330..30fba133 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,13 +17,19 @@ All notable changes for the ContextGuard plugin are documented here. 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`. - **The escrow default itself survives, on a different figure.** Turns divide on - a second axis: whether the cached prefix was written or extended. Restricted to - the incremental turns — the only ones that bill in proportion to what a tool - returned — Bash still precedes about 69% of new tokens. The prefix-write turns, - about 77% of `cache_creation`, are not something any tool hook can reduce, and the - audit now reports them as their own `cold_start` / `cache_rewrite` / - `incremental` fields and says so in its recommendation. + **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 are left as they were published. diff --git a/plugins/context-guard/skills/audit/SKILL.md b/plugins/context-guard/skills/audit/SKILL.md index 2b29a965..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. Read the `cold_start` / `cache_rewrite` / `incremental` fields beside it before naming a tool: turns that rewrote the cached prefix track context size, not what a tool returned, and no hook reduces them. Lead with a tool only when the incremental turns point at one; +- 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; From 2b4b154e7908a57638783c40b28f963fc8b0d488 Mon Sep 17 00:00:00 2001 From: Coden Date: Sun, 6 Sep 2026 22:25:00 +0900 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20GLM=20=ED=9B=84=EC=86=8D=20non-bloc?= =?UTF-8?q?ker=20=E2=80=94=20=EB=B0=9C=ED=96=89=20=ED=95=AD=EB=AA=A9=20?= =?UTF-8?q?=EC=B2=98=EB=A6=AC=20=EB=B0=A9=EC=8B=9D=EC=9D=84=20=EC=A0=95?= =?UTF-8?q?=ED=99=95=ED=9E=88=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "Historical entries below are left as they were published" 라고 썼는데 실제로는 0.13.0 항목에 정정을 가리키는 괄호 문장을 넣었다. 내부 모순이라 "발행 당시의 본문은 그대로 두되, 영향받은 수치 옆에 이 정정을 가리키는 표시를 덧붙였다" 로 고친다. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01DE3AupXcyv64SEuQeTckSh --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 30fba133..a721437e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,7 +31,8 @@ All notable changes for the ContextGuard plugin are documented here. reports them as their own `cold_start` / `cache_rewrite` / `incremental` fields. - Historical entries below are left as they were published. + 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