From 624f5edabc3d18be927913d25ed981a19ee34bc4 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Thu, 18 Jun 2026 13:35:00 +0200 Subject: [PATCH] docs(knowledge): refresh corpus to Opus 4.8 era (CC 2.1.114->181 Batch 3) The knowledge base was frozen at ~v2.1.111, describing an Opus-4.7 world after CC shipped Opus 4.8 and Fable 5. Refreshed three agent-facing knowledge files; every fact re-verified against the official changelog (~/.claude/cache/changelog.md, CC 2.1.181) on 2026-06-18. - feature-evolution.md: new Opus-4.8-era rows above the v2.1.111 freeze -- Opus 4.8 default + /effort xhigh (2.1.154), Fable 5 Mythos-class (2.1.170), post-session hook (2.1.169), MessageDisplay (2.1.152), /simplify -> /code-review (2.1.147), /config key=value (2.1.181). - hook-events-reference.md: 26 -> 28 events (+MessageDisplay, +post-session); documented Stop/SubagentStop additionalContext output field. - claude-code-capabilities.md: 2026-06 model/effort lineup table; bundled skills /simplify -> /code-review; documented /config key=value. - cc-2.1.x-changelog-delta.md: marked SUPERSEDED by the gap-matrix. Verification caught two version errors in STATE/matrix, corrected to the changelog: - Stop/SubagentStop additionalContext is 2.1.163, not 2.1.165 (2.1.165 was "Bug fixes" only; matrix row 109 already said 2.1.163). - settings `agent` field introduced 2.0.59; 2.1.157 = honored for dispatched `claude agents` sessions, not the introduction. New tests/knowledge/knowledge-staleness.test.mjs (8 tests) encodes the verified facts as a re-freeze guard (RED before edits, GREEN after). Full suite: 850/850 green (+8). self-audit PASS, A(100)/A(97). --- docs/cc-2.1.x-changelog-delta.md | 22 ++++-- knowledge/claude-code-capabilities.md | 15 +++- knowledge/feature-evolution.md | 7 ++ knowledge/hook-events-reference.md | 8 ++- tests/knowledge/knowledge-staleness.test.mjs | 75 ++++++++++++++++++++ 5 files changed, 119 insertions(+), 8 deletions(-) create mode 100644 tests/knowledge/knowledge-staleness.test.mjs diff --git a/docs/cc-2.1.x-changelog-delta.md b/docs/cc-2.1.x-changelog-delta.md index 0eb7fec..bc49e0a 100644 --- a/docs/cc-2.1.x-changelog-delta.md +++ b/docs/cc-2.1.x-changelog-delta.md @@ -1,10 +1,20 @@ -# Claude Code config-surface delta — v2.1.114 → v2.1.181 (DRAFT) +# Claude Code config-surface delta — v2.1.114 → v2.1.181 (SUPERSEDED) -> **Status: DRAFT.** Produced by claude-code-guide research agent 2026-06-18 from the official -> changelog. Treated as a checklist — **each row is independently re-verified per-surface in Fase 2** -> (workflow `config-audit-cc-gap`) against https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md -> before any action. Items below the 2.1.114 floor (e.g. 2.1.105) are kept for the token-management -> thread (Fase 4) but are out of the primary window. +> **Status: SUPERSEDED** by `docs/cc-2.1.x-gap-matrix.md` (the verified truth source). This draft is +> kept only as the historical research artifact. Do not action rows from here — the matrix re-verified +> every row per-surface. Two version errors that propagated into both this draft and the matrix's +> draft-correction note were re-checked against the official changelog on 2026-06-18 (Batch 3) and +> corrected at the knowledge layer: +> +> - **Stop/SubagentStop `additionalContext`: v2.1.163** (not v2.1.165 — that release was "Bug fixes +> and reliability improvements" only). The gap-matrix even self-contradicts here: row 109 already +> said 2.1.163. +> - **settings `agent` field: introduced v2.0.59**; v2.1.157 is when it became "honored for dispatched +> `claude agents` sessions" — this draft's "2.1.154" and the matrix's "2.1.157-as-introduction" are +> both imprecise. +> +> Original draft note: produced by the claude-code-guide research agent 2026-06-18 from the official +> changelog. Items below the 2.1.114 floor (e.g. 2.1.105) belong to the token-management thread (Fase 4). **Current latest:** v2.1.181 · **Window:** 2.1.114 → 2.1.181 diff --git a/knowledge/claude-code-capabilities.md b/knowledge/claude-code-capabilities.md index 5664893..03fad1d 100644 --- a/knowledge/claude-code-capabilities.md +++ b/knowledge/claude-code-capabilities.md @@ -2,6 +2,7 @@ > Source: Official Claude Code documentation (code.claude.com/docs), 75 pages, verified 2026-04-03. > Delta layer: research/03-claude-code-changes-config-surfaces.md (verified 2026-04-19) — sandbox/managed-only/prompt-cache surfaces added between v2.1.14 and v2.1.114. +> 2026-06 model/effort lineup (below) re-verified against the official changelog on 2026-06-18 (window v2.1.114–v2.1.181). ## 2026-04 deltas (research/03) @@ -18,6 +19,18 @@ | Env: `ENABLE_PROMPT_CACHING_1H`, `FORCE_PROMPT_CACHING_5M` | v2.1.108 | Explicit prompt-cache TTL control. | | Env: `CLAUDE_CODE_DISABLE_1M_CONTEXT`, `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 2026-04 | Behavior opt-outs for new defaults. | +## 2026-06 model & effort lineup (changelog, verified 2026-06-18) + +> Window v2.1.114–v2.1.181. The Opus-4.7 framing elsewhere in the corpus predates these. + +| Item | Added in | Notes | +|------|---------|-------| +| **Opus 4.8 — new default** | v2.1.154 | Defaults to high effort. `/effort xhigh` (`effortLevel: "xhigh"`) is the new top tier for the hardest tasks. | +| Lean system prompt now default | v2.1.154 | Default for all models except Haiku, Sonnet, and Opus 4.7 and earlier — lowers baseline system-prompt token cost. | +| **Claude Fable 5** (Mythos-class) | v2.1.170 | New top-capability model family; 1M context by default (a `[1m]` id suffix is normalised away). Auto mode falls back to the best available Opus for orgs without Opus 4.8. | +| `/code-review` bundled review skill | v2.1.147 | Renamed from the former cleanup skill; reports correctness bugs at a chosen effort (`/code-review high`), `--comment` posts inline PR comments. | +| `/config key=value` | v2.1.181 | Apply any setting from the prompt (e.g. `/config thinking=false`) — interactive, `-p`, and Remote Control. Lets `/config-audit` settings recommendations be applied without hand-editing settings.json. | + ## Official Configuration Guidance (Anthropic) These principles are backed by official docs and verified community reports. Use them to ground recommendations. @@ -291,7 +304,7 @@ paths: ["src/**/*.ts"] **Dynamic context:** `` !`command` `` executes shell command and inlines output. -**Bundled skills:** `/batch`, `/claude-api`, `/debug`, `/loop`, `/simplify` +**Bundled skills:** `/batch`, `/claude-api`, `/debug`, `/loop`, `/code-review` (renamed from the former cleanup skill, v2.1.147) **Fully utilizing:** Custom deploy/review workflows; `disable-model-invocation: true` on side-effect skills; `context: fork` for isolated research; `!`git diff HEAD`` for dynamic context; `argument-hint` for UX. diff --git a/knowledge/feature-evolution.md b/knowledge/feature-evolution.md index fe9ae13..5c315ba 100644 --- a/knowledge/feature-evolution.md +++ b/knowledge/feature-evolution.md @@ -2,6 +2,7 @@ > Timeline of major features, most recent first. Covers features with configuration impact. > Source: Official Claude Code documentation, verified 2026-04-03; 2026-04 entries verified via research/03-claude-code-changes-config-surfaces.md (2026-04-19). +> 2026-06 entries (window v2.1.114–v2.1.181) re-verified against the official Claude Code changelog on 2026-06-18. --- @@ -9,6 +10,12 @@ | Approx. Date | Feature | Config Impact | |-------------|---------|---------------| +| 2026-06 (v2.1.181) | **`/config key=value` in-session settings** | Set any setting from the prompt — `/config thinking=false` — in interactive, `-p`, and Remote Control. Lets `/config-audit` settings recommendations be applied without hand-editing settings.json. | +| 2026-05 (v2.1.170) | **Claude Fable 5 (Mythos-class)** | New top-capability model family; 1M context by default (a `[1m]` id suffix is normalised away). Auto mode falls back to the best available Opus for orgs without Opus 4.8 enabled. | +| 2026-05 (v2.1.169) | **`post-session` lifecycle hook** | Runs after the session ends and before the workspace is deleted — snapshot uncommitted work or export logs (self-hosted runner). Kebab-case, distinct from `SessionEnd`. | +| 2026-04 (v2.1.154) | **Opus 4.8 — new default model** | Defaults to high effort; `/effort xhigh` (`effortLevel: "xhigh"`) is the new top tier for the hardest tasks. The lean system prompt is now the default for all models except Haiku, Sonnet, and Opus 4.7 and earlier. The settings `agent` field is honored for dispatched `claude agents` sessions (v2.1.157). | +| 2026-04 (v2.1.152) | **`MessageDisplay` hook event** | Hooks can transform or hide assistant message text as it is displayed. | +| 2026-04 (v2.1.147) | **`/simplify` renamed to `/code-review`** | Reports correctness bugs at a chosen effort (`/code-review high`); `--comment` posts inline PR comments. The old cleanup-and-fix behaviour was removed. | | 2026-04 (v2.1.111) | **Opus 4.7 + token-efficiency surfaces** | New env vars `ENABLE_PROMPT_CACHING_1H`, `FORCE_PROMPT_CACHING_5M`, `CLAUDE_CODE_DISABLE_1M_CONTEXT`. New settings keys around `tui` / `autoScrollEnabled`. Granular commit attribution via `attribution.commit` / `attribution.pr` (replaces `includeCoAuthoredBy`). | | 2026-04 (v2.1.83+) | **Sandbox + managed-only enterprise lockdown** | Added settings keys: `sandbox.enabled`, `sandbox.failIfUnavailable`, `sandbox.allowUnsandboxedCommands`, `sandbox.filesystem.allowRead/denyRead`, `sandbox.network.deniedDomains/allowedDomains`, `sandbox.enableWeakerNetworkIsolation`. Managed-only flags: `allowManagedHooksOnly`, `allowManagedMcpServersOnly`, `allowManagedPermissionRulesOnly`. | | 2026-03 (v2.1.91) | **`disableSkillShellExecution`** | Blocks inline `!command` shell expansion in skills. Mitigates skill-side prompt-injection vector. | diff --git a/knowledge/hook-events-reference.md b/knowledge/hook-events-reference.md index d20093a..ca94053 100644 --- a/knowledge/hook-events-reference.md +++ b/knowledge/hook-events-reference.md @@ -1,7 +1,8 @@ # Hook Events Reference -> All 26 hook events as of April 2026. Source: code.claude.com/docs/en/hooks.md +> All 28 hook events as of June 2026. Source: code.claude.com/docs/en/hooks.md > Verified 2026-04-19 against research/03-claude-code-changes-config-surfaces.md — no new hook events introduced in v2.1.83–v2.1.111. Sandbox + managed-only flags (2026-04) operate at the settings layer, not as new hook events. +> Re-verified 2026-06-18 against the official changelog (window v2.1.114–v2.1.181): added `MessageDisplay` (v2.1.152) and `post-session` (v2.1.169), bringing the count from 26 to 28. --- @@ -25,6 +26,7 @@ | `StopFailure` | Turn ends in an API error | No | Error type | Alert on API errors; retry logic; log error context | | `TeammateIdle` | An agent team member has no tasks | Yes | No matcher | Assign next task (exit 2 to keep working); log team status; rebalance work | | `Notification` | A notification is sent (permission prompt, idle, auth) | No | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog` | Desktop notifications; Slack/webhook alerts; mobile push; audio cues | +| `MessageDisplay` | Assistant message text is about to be displayed (v2.1.152) | Yes (transforms) | No matcher | Transform or hide assistant output before it reaches the terminal — redact secrets, rewrite text | | `ConfigChange` | A config file changes on disk | Yes | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` | Validate config changes; block invalid edits; reload dependent processes | | `CwdChanged` | Working directory changes | No | No matcher | Inject new directory context; update env vars via `$CLAUDE_ENV_FILE`; log navigation | | `FileChanged` | A watched file changes | No | Filename pattern | Auto-reload when config changes; trigger builds on source change; sync state | @@ -35,6 +37,7 @@ | `Elicitation` | An MCP server requests user input | Yes | MCP server name | Control which servers can request input; log elicitations; pre-fill responses | | `ElicitationResult` | User responds to MCP elicitation | Yes | MCP server name | Validate responses; log user input; transform before sending to MCP | | `SessionEnd` | Session terminates | No | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` | Final session summary; save state; cleanup temp files; send end-of-session report | +| `post-session` | Session has ended, before the workspace is deleted (v2.1.169) | No | No matcher | Snapshot uncommitted work; export logs; cleanup (self-hosted runner). Kebab-case, distinct from `SessionEnd`. | --- @@ -94,6 +97,9 @@ - `additionalContext`: string injected into context - Or: write env vars to `$CLAUDE_ENV_FILE` +**Stop / SubagentStop** (exit 0, since v2.1.163): +- `hookSpecificOutput.additionalContext`: feedback string that keeps the turn going without being treated as a hook error + --- ## Environment Variables Available in Hooks diff --git a/tests/knowledge/knowledge-staleness.test.mjs b/tests/knowledge/knowledge-staleness.test.mjs new file mode 100644 index 0000000..cf7da42 --- /dev/null +++ b/tests/knowledge/knowledge-staleness.test.mjs @@ -0,0 +1,75 @@ +// Knowledge-base staleness guard. +// +// The gap-review (CC 2.1.114->181) found config-audit's knowledge corpus frozen +// at ~v2.1.111, so it described an Opus-4.7 world after CC had shipped Opus 4.8 +// and Fable 5. These assertions encode facts re-verified against the official +// Claude Code changelog (~/.claude/cache/changelog.md) on 2026-06-18 so the +// corpus cannot silently re-freeze. Each fact carries its verified version. +// +// Verified facts (official changelog, CC 2.1.181): +// Opus 4.8 default + high effort + /effort xhigh ... 2.1.154 +// lean system prompt now default (except Haiku/Sonnet/4.7-) 2.1.154 +// Claude Fable 5 (Mythos-class) .................... 2.1.170 +// /simplify renamed to /code-review ............... 2.1.147 +// /config key=value in-session settings ........... 2.1.181 +// MessageDisplay hook event ....................... 2.1.152 +// post-session lifecycle hook ..................... 2.1.169 +// Stop/SubagentStop return additionalContext ...... 2.1.163 (NOT 2.1.165) + +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; + +const read = (rel) => + readFileSync(fileURLToPath(new URL(`../../knowledge/${rel}`, import.meta.url)), 'utf8'); + +test('feature-evolution.md records the Opus 4.8 era (not frozen at v2.1.111)', () => { + const md = read('feature-evolution.md'); + assert.match(md, /Opus 4\.8/, 'must record Opus 4.8 as the new default'); + assert.match(md, /Fable 5/, 'must record Claude Fable 5'); + assert.match(md, /2\.1\.170/, 'Fable 5 verified at v2.1.170'); + assert.match(md, /2\.1\.154/, 'Opus 4.8 / xhigh / lean prompt verified at v2.1.154'); + assert.match(md, /xhigh/, 'must record the /effort xhigh tier'); +}); + +test('feature-evolution.md records the /simplify -> /code-review rename', () => { + const md = read('feature-evolution.md'); + assert.match(md, /\/code-review/, 'bundled skill renamed to /code-review (2.1.147)'); +}); + +test('feature-evolution.md records /config key=value', () => { + const md = read('feature-evolution.md'); + assert.match(md, /\/config/, '/config key=value in-session settings (2.1.181)'); +}); + +test('hook-events-reference.md header reflects 28 events, not 26', () => { + const md = read('hook-events-reference.md'); + assert.match(md, /28 hook events/, 'count must be 28 after MessageDisplay + post-session'); + assert.doesNotMatch(md, /26 hook events/, 'stale "26 hook events" must be gone'); +}); + +test('hook-events-reference.md lists MessageDisplay and post-session events', () => { + const md = read('hook-events-reference.md'); + assert.match(md, /MessageDisplay/, 'MessageDisplay hook event (2.1.152)'); + assert.match(md, /post-session/, 'post-session lifecycle hook (2.1.169)'); +}); + +test('hook-events-reference.md documents Stop/SubagentStop additionalContext at 2.1.163', () => { + const md = read('hook-events-reference.md'); + // The feature shipped in 2.1.163 (NOT 2.1.165 — that release was bug fixes only). + assert.match(md, /SubagentStop[\s\S]*additionalContext|additionalContext[\s\S]*SubagentStop/, + 'Stop/SubagentStop additionalContext output field must be documented'); + assert.match(md, /2\.1\.163/, 'additionalContext for Stop/SubagentStop verified at v2.1.163'); +}); + +test('claude-code-capabilities.md bundled skills use /code-review, not stale /simplify', () => { + const md = read('claude-code-capabilities.md'); + assert.match(md, /\/code-review/, 'bundled-skill list must list /code-review'); + assert.doesNotMatch(md, /\/simplify/, '/simplify was renamed to /code-review (2.1.147)'); +}); + +test('claude-code-capabilities.md documents /config key=value', () => { + const md = read('claude-code-capabilities.md'); + assert.match(md, /\/config/, '/config key=value in-session settings (2.1.181)'); +});