context-carwash 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.2.5
+
+- After you update, your next session says what's new, once, in Claude Code and in Codex. It waits for a start with nothing else to say, so it never gets in the way of a brief loading. Updating from 0.2.3 or earlier, it tells you about notes on what to keep.
+- The welcome you see after installing now shows how to name what a brief must keep.
+- The README shows notes in the command table, near the top, and in the Codex section.
+
+## 0.2.4
+
+- You can name what a brief must keep: `/wash keep the exact error and the rollback plan`. Claude puts it in a **Kept on request** section right after Core, keeps exact wording for errors, commands and paths, and cuts other sections first when the brief is too long. A note on its own gets a `mid` brief; to pick the level, put it first, as in `/wash detailed keep the test names`. The same works with `$wash` in Codex.
+- A note can start with a word that is also a command: `/wash help me keep the API notes` writes a brief instead of showing help. `help` and `stats` are commands only when nothing follows them, and `load` and `discard` only with at most an id.
+- Likely typos cost nothing: `/wash detaled` or `/wash discrad a3f9c2` asks "Did you mean…?" instead of writing a brief.
+- `/wash help` shows how to add a note.
+- Run `npx context-carwash@latest install` to get the new `/wash` instructions.
+
 ## 0.2.3
 
 - A fresh session can now search the old conversation. When a brief is saved, Carwash keeps a text copy of the conversation in `~/.carwash/recall`, without images, and tells the fresh session where it is, so it can look up an exact error message, path or number the brief left out. The copy is deleted after 7 days, or when you discard the brief. Nothing goes in your project.

package/README.md

@@ -7,7 +7,7 @@
 Context Carwash adds a line to Claude Code in your terminal that:
 
 1. **The Meter:** shows the current conversation's context size.
-2. **/wash:** lets you compress your context and start a new session without losing important details.
+2. **/wash:** lets you compress your context and start a new session without losing important details. You can name anything it must keep: `/wash keep the exact error`.
 
 It works in Codex too: see [Codex](#codex).
 
@@ -23,7 +23,7 @@ npx context-carwash install
 
 It shows you what it's going to change and asks before doing anything. Then start a new Claude Code session and you're set. If you use Codex as well, it sets that up in the same go.
 
-When there's a new version, a line under the meter will tell you. To update, run `npx context-carwash@latest install`.
+When there's a new version, a line under the meter will tell you. To update, run `npx context-carwash@latest install`. Your next session after updating tells you what's new, once.
 
 Under the hood, it adds a status line, three hooks and one read-only permission to `~/.claude/settings.json` (after whatever you already have there) and a `/wash` command in `~/.claude/skills/wash`. The permission lets Claude search `~/.carwash/recall` without asking, and nothing else. For Codex, it adds three hooks to `~/.codex/hooks.json` and a `$wash` command in `~/.codex/skills/wash`.
 
@@ -48,6 +48,7 @@ Your old conversation isn't gone. You can still find it in `/resume`, and the fr
 | `/wash light` | Goal, current state, next step |
 | `/wash mid` | Adds constraints, decisions, state detail, pitfalls |
 | `/wash detailed` | Adds rationale, history, test results, risks, a step checklist |
+| `/wash keep the exact error` | Write a `mid` brief that also keeps what you name, in its own section |
 | `/wash discard` | Drop the brief. `/clear` is a normal clear again |
 | `/wash load [id]` | Make a waiting brief the one your next `/clear` uses |
 | `/wash stats` | How much context your washes have saved |
@@ -55,7 +56,7 @@ Your old conversation isn't gone. You can still find it in `/resume`, and the fr
 
 A few things worth knowing:
 
-- You can tell Claude what to focus on: `/wash mid focus on the failing test`.
+- A note on what to keep goes in its own section near the top of the brief and is never cut to save space. For a level other than `mid`, put the level first: `/wash detailed keep the test names`.
 - If you `/clear` without a brief ready, it's just a normal clear.
 - Writing a brief is a normal Claude reply, so it uses some tokens. `help`, `discard` and `load` are free.
 - Bigger conversations get bigger briefs. `/wash help` shows the size limit for each level.
@@ -66,7 +67,7 @@ A few things worth knowing:
 
 If you have Codex, `install` sets it up too. It works the same way, with a few differences:
 
-- The command is `$wash` (Codex keeps `/` for its own commands). Same options: `$wash light`, `$wash discard`, `$wash help` and so on.
+- The command is `$wash` (Codex keeps `/` for its own commands). Same options: `$wash light`, `$wash keep the exact error`, `$wash discard`, `$wash help` and so on.
 - Codex asks you to approve new hooks before it runs them. The first time you start Codex after installing, choose **Trust all and continue**.
 - After `/clear`, send your next message (even just "continue"). The brief loads with it, because that's when Codex starts the new session.
 - The meter shows up as a line after each reply, because Codex's status line can only show its own items:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-carwash",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "A quiet context meter and deliberate fresh-session handoff for Claude Code and Codex.",
   "license": "MIT",
   "repository": {

package/src/install/install.mjs

@@ -3,9 +3,10 @@ import { homedir } from 'node:os';
 import { delimiter, dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { privateDir, readJson, writeFileAtomic } from '../files.mjs';
-import { RECALL_DAYS, carwashHome, claudeConfigDir, installRecordPath, legacyCommandPath, pendingDir, recallDir, settingsPath, skillDir } from '../paths.mjs';
+import { RECALL_DAYS, carwashHome, claudeConfigDir, installRecordPath, legacyCommandPath, pendingDir, recallDir, settingsPath, skillDir, updatedFromPath } from '../paths.mjs';
 import { applyCodexInstall, applyCodexUninstall, codexDetected, describeCodexInstall, describeCodexUninstall, planCodexInstall, planCodexUninstall } from './codex.mjs';
 import { UserError, readSettings, resolveSettingsFile, serializeSettings, sha256 } from './settings.mjs';
+import { isNewer } from './update.mjs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const APP_ENTRIES = ['bin', 'src', 'package.json', 'LICENSE'];
@@ -316,6 +317,19 @@ export function applyInstall(plan) {
   const extra = { ...(tools.length === 1 && tools[0] === 'claude' ? {} : { tools }), ...(codex ? { codex } : {}) };
   const nextRecord = plan.claude ? { ...base, ...applyClaudeInstall(plan), ...extra } : { ...base, ...extra };
   writeFileSync(installRecordPath({ CARWASH_HOME: home }), JSON.stringify(nextRecord, null, 2) + '\n', { mode: 0o600 });
+
+  // An update notes the version it replaced, so the next session in each tool
+  // can say what is new. Installing again before that session keeps the first
+  // note, which goes back further.
+  if (record?.version && isNewer(base.version, record.version)) {
+    for (const tool of tools) {
+      try {
+        writeFileSync(updatedFromPath({ CARWASH_HOME: home }, tool), `${record.version}\n`, { flag: 'wx', mode: 0o600 });
+      } catch {
+        // already noted
+      }
+    }
+  }
   return nextRecord;
 }
 

package/src/paths.mjs

@@ -57,6 +57,10 @@ export const noticePath = (env = process.env) => join(carwashHome(env), 'notice.
 // Present once the first-run welcome has been shown. Each tool says hello once.
 export const welcomedPath = (env = process.env, tool = 'claude') => join(carwashHome(env), tool === 'claude' ? 'welcomed' : `welcomed-${tool}`);
 
+// Left by an install that updated Carwash: the version it replaced. The next
+// session in each tool says what is new since then, once, and deletes it.
+export const updatedFromPath = (env = process.env, tool = 'claude') => join(carwashHome(env), tool === 'claude' ? 'updated-from' : `updated-from-${tool}`);
+
 // Where the /wash command is installed.
 export const skillDir = (env = process.env) => join(claudeConfigDir(env), 'skills', 'wash');
 export const legacyCommandPath = (env = process.env) => join(claudeConfigDir(env), 'commands', 'wash.md');

package/src/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wash
 description: Context Carwash. Writes a short handoff brief of this session, so that /clear can start a fresh session that carries on from it.
-argument-hint: "[light | mid | detailed | discard | load <id> | stats | help]"
+argument-hint: "[light | mid | detailed] [what to keep] | discard | load <id> | stats | help"
 disable-model-invocation: true
 metadata:
   installed-by: context-carwash
@@ -11,7 +11,7 @@ The user typed /wash. They want to start a fresh session that picks up where thi
 
 Arguments: $ARGUMENTS
 
-The first word is the level: `light`, `mid`, or `detailed`. No arguments means `mid`. Anything after the level is the user's note on what to emphasise. If the first word is something else, Carwash's hooks are not running: write no brief, and tell the user in one sentence to run `carwash install` again.
+Carwash's hooks send a line with this command that starts with "Carwash: level". It gives the level for this brief (`light`, `mid`, or `detailed`), its token ceiling, and the user's note on what the brief must keep, if they wrote one. Go by that line, not by the arguments above. If there is no such line, Carwash's hooks are not running: write no brief, and tell the user in one sentence to run `carwash install` again.
 
 Reply with the brief and nothing else: no preamble, no closing remark, no code fence around it. Do not call tools or read files to prepare. Write from what is already in this conversation.
 
@@ -30,9 +30,11 @@ Start with exactly this heading, then the Core section:
 
 Core must stand on its own in under 1,000 characters. A session that reads only Core should still start in the right place.
 
-After Core, add only the sections for the level, and skip any that would be empty:
+If the user wrote a note, put a **Kept on request** section straight after Core, at every level. It holds everything the note asks for that this conversation has, with the exact wording of error messages, commands, paths, and numbers. If the note asks for something this conversation does not have, say so in one line instead of guessing. Never drop or shorten anything here to save space: cut from the other sections instead. Secrets stay out even when the note asks for them.
 
-- `light`: Core only. Add one line for a critical constraint if breaking it would undo the work.
+After that, add only the sections for the level, and skip any that would be empty:
+
+- `light`: no other sections. Add one line for a critical constraint if breaking it would undo the work.
 - `mid`: **Constraints** (the user's corrections and preferences that still apply), **Decisions** (what was settled, with the reason in a clause), **State** (files and branches changed, commands and tests run with their results, uncommitted work, blockers), **Pitfalls** (what to avoid, and approaches that failed).
 - `detailed`: everything in `mid`, plus **Rationale** for the main decisions, **History** (experiments worth knowing about and what each one showed), **Test results**, **Risks and open assumptions**, and **Steps** (a checklist of what remains).
 

package/src/skill/codex/SKILL.md

@@ -11,7 +11,7 @@ The user typed $wash. Context Carwash saves your reply as a handoff brief, but o
 
 When the message is there: the user wants to start a fresh session that picks up where this one leaves off. Your whole reply to this message is saved as the handoff brief, and it is the first thing the next session reads. That session cannot see this conversation. It can search a saved copy for an exact detail, but only if it knows to look, so the brief has to stand on its own.
 
-The words after $wash in the user's message are the arguments. The first word is the level: `light`, `mid`, or `detailed`. No arguments means `mid`. Anything after the level is the user's note on what to emphasise.
+The "Carwash: level" message gives the level for this brief (`light`, `mid`, or `detailed`), its token ceiling, and the user's note on what the brief must keep, if they wrote one. Go by that message, not by the words after $wash.
 
 Reply with the brief and nothing else: no preamble, no closing remark, no code fence around it. Do not call tools or read files to prepare. Write from what is already in this conversation.
 
@@ -30,9 +30,11 @@ Start with exactly this heading, then the Core section:
 
 Core must stand on its own in under 1,000 characters. A session that reads only Core should still start in the right place.
 
-After Core, add only the sections for the level, and skip any that would be empty:
+If the user wrote a note, put a **Kept on request** section straight after Core, at every level. It holds everything the note asks for that this conversation has, with the exact wording of error messages, commands, paths, and numbers. If the note asks for something this conversation does not have, say so in one line instead of guessing. Never drop or shorten anything here to save space: cut from the other sections instead. Secrets stay out even when the note asks for them.
 
-- `light`: Core only. Add one line for a critical constraint if breaking it would undo the work.
+After that, add only the sections for the level, and skip any that would be empty:
+
+- `light`: no other sections. Add one line for a critical constraint if breaking it would undo the work.
 - `mid`: **Constraints** (the user's corrections and preferences that still apply), **Decisions** (what was settled, with the reason in a clause), **State** (files and branches changed, commands and tests run with their results, uncommitted work, blockers), **Pitfalls** (what to avoid, and approaches that failed).
 - `detailed`: everything in `mid`, plus **Rationale** for the main decisions, **History** (experiments worth knowing about and what each one showed), **Test results**, **Risks and open assumptions**, and **Steps** (a checklist of what remains).
 

package/src/wash/brief.mjs

@@ -1,3 +1,4 @@
+import { isNewer } from '../install/update.mjs';
 import { CHARS_PER_TOKEN, capFor } from '../levels.mjs';
 import { RECALL_DAYS } from '../paths.mjs';
 import { colorAt, paint } from '../statusline/color.mjs';
@@ -6,7 +7,8 @@ import { toolInfo, toolOf } from '../tools.mjs';
 
 // The wording around a brief: what Claude is told when writing one, how its
 // reply is recognised, and what the user and the next session are shown. Also
-// the two places Carwash explains itself: the first-run welcome and /wash help.
+// the places Carwash explains itself: the first-run welcome, what is new after
+// an update, and /wash help.
 // Wording that names the tool or its commands takes the tool's id (see
 // tools.mjs); Claude Code is the default.
 
@@ -55,23 +57,26 @@ const sizeOf = (record) => `${record.level} ~${formatTokens(record.tokens)}`;
 // a3f9c2 "Fix login redirect" (mid ~1.1k, 14h ago)
 export const describe = (record, now) => `${record.id} "${record.title}" (${sizeOf(record)}, ${ageOf(record, now)})`;
 
-// Sent to Claude alongside the /wash prompt: the size limit for this brief.
-export function budgetNote(level, cap, used) {
+// Sent to Claude alongside the /wash prompt: the size limit for this brief,
+// and the user's note on what it must keep, if they wrote one.
+export function budgetNote(level, cap, used, note = '') {
+  const kept = note ? ` The user's note on what this brief must keep: ${note}` : '';
   if (!cap) {
-    return `Carwash: level ${level}. The size of this session is not known yet, so there is no token ceiling for this brief. Keep to the ${level} scope and keep it short.`;
+    return `Carwash: level ${level}. The size of this session is not known yet, so there is no token ceiling for this brief. Keep to the ${level} scope and keep it short.${kept}`;
   }
   const chars = Math.max(100, Math.round((cap * CHARS_PER_TOKEN) / 100) * 100);
   return (
     `Carwash: level ${level}. This session is using about ${formatTokens(used)} tokens, so the ceiling for this brief is ${cap} tokens, ` +
-    `which is roughly ${chars} characters. That is a limit, not a target: stop as soon as the brief is complete.`
+    `which is roughly ${chars} characters. That is a limit, not a target: stop as soon as the brief is complete.${kept}`
   );
 }
 
 // Sent to Claude when its brief came out over the cap.
-export function retryNote(level, cap, tokens) {
+export function retryNote(level, cap, tokens, hasNote = false) {
+  const keep = hasNote ? ', the Core section, and everything in Kept on request' : ' and the Core section';
   return (
     `Carwash: that brief is about ${tokens} tokens, over the ${cap}-token ceiling for ${level}. Send it again shortened to fit. ` +
-    'Keep the "# Carwash brief:" heading and the Core section, cut the least useful detail first, and reply with the brief alone.'
+    `Keep the "# Carwash brief:" heading${keep}, cut the least useful detail first, and reply with the brief alone.`
   );
 }
 
@@ -142,6 +147,7 @@ export function welcomeMessage(tool = 'claude') {
       'Context Carwash installed ✓ (shown once)',
       '  • After each reply: tokens in use, and how full the context is',
       '  • Getting full? $wash, then /clear and send your next message. You start fresh, right where you left off',
+      '  • Something the brief must keep? Name it: $wash keep the exact error',
       '  • Nothing runs on its own · $wash help for options',
     ].join('\n');
   }
@@ -149,10 +155,25 @@ export function welcomeMessage(tool = 'claude') {
     'Context Carwash installed ✓ (shown once)',
     '  • Status line: tokens in use, and how full the context is',
     '  • Getting full? /wash, then /clear. You start fresh, right where you left off',
+    '  • Something the brief must keep? Name it: /wash keep the exact error',
     '  • Nothing runs on its own · /wash help for options',
   ].join('\n');
 }
 
+// What a release brings that someone updating should hear about, in the
+// tool's own command. Most releases add nothing here.
+const WHATS_NEW = [
+  ['0.2.4', (wash) => `Name what a brief must keep: ${wash} keep the exact error. It gets its own section and is never cut to save space.`],
+];
+
+// Shown once, at the first quiet session after an update: what is new since
+// `from`, or null when nothing is worth saying.
+export function whatsNewMessage(from, to, tool = 'claude') {
+  const { wash } = toolInfo(tool);
+  const lines = WHATS_NEW.filter(([version]) => isNewer(version, from) && !isNewer(version, to)).map(([, line]) => `  • ${line(wash)}`);
+  return lines.length ? [`Context Carwash updated to ${to} ✓ (shown once)`, ...lines].join('\n') : null;
+}
+
 // What each level keeps, for /wash help.
 const LEVEL_NOTES = {
   light: 'goal, where things stand, next step',
@@ -181,6 +202,8 @@ export function helpMessage(used, footer = null, tool = 'claude') {
     row('discard', 'drop the brief; /clear is a normal clear again'),
     row('load [id]', 'make a waiting brief the one /clear uses'),
     '',
+    `Add a note to name what the brief must keep: ${wash} keep the exact error, or ${wash} detailed keep the test names.`,
+    '',
     ...(meter ? ["The status line shows how many tokens this conversation is using, and the bar shows how close that is to the model's limit."] : []),
     ...(replyMeter ? ["The line after each reply shows how many tokens this conversation is using, and the bar shows how close that is to the model's limit. It is shown to you only and costs no tokens."] : []),
     `Writing a brief is an ordinary ${model} reply, so it uses tokens. help, discard and load do not.`,

package/src/wash/hooks.mjs

@@ -1,13 +1,13 @@
-import { existsSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
 import { packageVersion } from '../install/install.mjs';
 import { startNotice, versionLine } from '../install/notice.mjs';
 import { isNewer } from '../install/update.mjs';
 import { DEFAULT_LEVEL, capFor, estimateTokens, isLevel } from '../levels.mjs';
-import { installRecordPath, welcomedPath } from '../paths.mjs';
+import { installRecordPath, updatedFromPath, welcomedPath } from '../paths.mjs';
 import { recordDelivery, recordWash, refreshLedger } from '../stats/ledger.mjs';
 import { colorDepth } from '../statusline/color.mjs';
 import { currentTotals, statsReport } from '../stats/report.mjs';
-import { budgetNote, composeContext, describe, helpMessage, loadedMessage, parseReply, pointerMessage, readyMessage, replyMeterMessage, retryNote, stalenessLine, welcomeMessage } from './brief.mjs';
+import { budgetNote, composeContext, describe, helpMessage, loadedMessage, parseReply, pointerMessage, readyMessage, replyMeterMessage, retryNote, stalenessLine, welcomeMessage, whatsNewMessage } from './brief.mjs';
 import { isTool, toolInfo, toolOf } from '../tools.mjs';
 import { repoState, worktreeRoot } from './git.mjs';
 import { codexProcess, codexUnattended, currentProcess, isRunning, sameProcess } from './process.mjs';
@@ -21,9 +21,10 @@ import { AUTO_LOAD_MS, addRecord, claim, findRecords, purge, readyRecords, remov
 //   UserPromptExpansion  /wash was typed (Claude Code). In Codex, where $wash
 //   UserPromptSubmit     is a skill, every prompt comes through
 //                        UserPromptSubmit and only one starting with $wash is
-//                        ours. A level starts a wash and tells the model the
-//                        size limit; discard, load, stats and help are handled
-//                        here and never reach the model.
+//                        ours. A level or a note starts a wash and tells the
+//                        model the size limit and the note; discard, load,
+//                        stats and help are handled here and never reach the
+//                        model.
 //   Stop                 The model finished replying. If that reply is the
 //                        brief, save it. Otherwise, in Codex, show the meter.
 //   SessionStart         A session began. If a brief is meant for it, hand the
@@ -37,7 +38,7 @@ import { AUTO_LOAD_MS, addRecord, claim, findRecords, purge, readyRecords, remov
 
 const usageLine = (tool) => {
   const wash = toolInfo(tool).wash;
-  return `Usage: ${wash} [light | mid | detailed], ${wash} discard [id], ${wash} load [id], ${wash} stats, ${wash} help`;
+  return `Usage: ${wash} [light | mid | detailed] [note on what to keep], ${wash} discard [id], ${wash} load [id], ${wash} stats, ${wash} help`;
 };
 
 // How many times to ask for a shorter brief before keeping an oversized one.
@@ -89,23 +90,59 @@ function onPromptSubmit(payload, ctx) {
   return found ? washCommand(payload, found[1], 'UserPromptSubmit', ctx) : null;
 }
 
+// A first word that is a level, or a command with no more than it takes, is
+// read as one. Anything else of more than a word is the user's note on what
+// the brief must keep, at the default level: "/wash help me keep the API
+// notes" is a note, not help. A lone unknown word, or a near miss of a long
+// name, is taken for a typo and costs nothing.
 function washCommand(payload, args, event, ctx) {
-  const [verb = DEFAULT_LEVEL, ref] = String(args ?? '').trim().toLowerCase().split(/\s+/).filter(Boolean);
-  if (isLevel(verb)) return begin(payload, verb, event, ctx);
-  if (verb === 'discard') return block(discard(payload, ref, ctx));
-  if (verb === 'load') return block(load(payload, ref, ctx));
-  if (verb === 'stats') return block(statsReport(currentTotals(ctx.env, ctx.now), { inClaude: true }));
-  if (verb === 'help') return block(helpMessage(ctx.usage(payload)?.used ?? null, versionLine(ctx.version, ctx.env), ctx.tool));
-  return block(`${toolInfo(ctx.tool).wash} does not know "${verb}". ${usageLine(ctx.tool)}`);
+  const text = String(args ?? '').trim();
+  const words = text.toLowerCase().split(/\s+/).filter(Boolean);
+  const [verb = DEFAULT_LEVEL, ref] = words;
+  if (isLevel(verb)) return begin(payload, verb, text.replace(/^\S+\s*/, ''), event, ctx);
+  if (verb === 'discard' && words.length <= 2) return block(discard(payload, ref, ctx));
+  if (verb === 'load' && words.length <= 2) return block(load(payload, ref, ctx));
+  if (verb === 'stats' && words.length === 1) return block(statsReport(currentTotals(ctx.env, ctx.now), { inClaude: true }));
+  if (verb === 'help' && words.length === 1) return block(helpMessage(ctx.usage(payload)?.used ?? null, versionLine(ctx.version, ctx.env), ctx.tool));
+  const lone = words.length === 1;
+  const guess = meant(verb, lone ? NAMES : LONG_NAMES);
+  if (!lone && !guess) return begin(payload, DEFAULT_LEVEL, text, event, ctx);
+  const { wash } = toolInfo(ctx.tool);
+  const hint = guess ? ` Did you mean ${wash} ${guess}?` : '';
+  return block(`${wash} does not know "${verb}".${hint} For a note on what to keep, put a level first: ${wash} mid <note>. ${usageLine(ctx.tool)}`);
 }
 
-function begin(payload, level, event, ctx) {
+const NAMES = ['light', 'mid', 'detailed', 'discard', 'load', 'stats', 'help'];
+// Short names are a letter away from everyday words ("right", "did", "lead")
+// that may well start a note, so only these are checked there.
+const LONG_NAMES = ['detailed', 'discard'];
+
+// The name a typo was probably meant to be: one slip from a short name, two
+// from a long one, where swapping two letters counts as one.
+function meant(word, names) {
+  return names.find((name) => name !== word && slips(word, name) <= (name.length > 5 ? 2 : 1)) ?? null;
+}
+
+function slips(a, b) {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) d[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+    }
+  }
+  return d[a.length][b.length];
+}
+
+function begin(payload, level, note, event, ctx) {
   const { env, now } = ctx;
   const usage = ctx.usage(payload);
   const used = usage?.used ?? null;
   const cap = capFor(level, used);
-  startWash(env, payload.session_id, { promptId: promptIdOf(payload), level, cap, used, size: usage?.size ?? null, startedAt: now, rewrites: 0 });
-  return { hookSpecificOutput: { hookEventName: event, additionalContext: budgetNote(level, cap, used) } };
+  startWash(env, payload.session_id, { promptId: promptIdOf(payload), level, cap, used, size: usage?.size ?? null, startedAt: now, rewrites: 0, ...(note ? { hasNote: true } : {}) });
+  return { hookSpecificOutput: { hookEventName: event, additionalContext: budgetNote(level, cap, used, note) } };
 }
 
 // Briefs waiting for the folder this session is in, other than its own. Only
@@ -212,7 +249,7 @@ function onStop(payload, ctx) {
   const overCap = Boolean(wash.cap) && tokens > wash.cap;
   if (overCap && wash.rewrites < MAX_REWRITES) {
     startWash(env, sessionId, { ...wash, rewrites: wash.rewrites + 1 });
-    const note = retryNote(wash.level, wash.cap, tokens);
+    const note = retryNote(wash.level, wash.cap, tokens, wash.hasNote);
     // Codex continues the turn with a Stop's block reason as the next prompt.
     if (ctx.tool === 'codex') return { decision: 'block', reason: note };
     return { hookSpecificOutput: { hookEventName: 'Stop', additionalContext: note } };
@@ -277,9 +314,29 @@ function welcome(ctx) {
     // Already shown, or nowhere to note it: better silent than said every time.
     return null;
   }
+  // The welcome already describes this version, so an update note goes with it.
+  rmSync(updatedFromPath(env, tool), { force: true });
   return { systemMessage: welcomeMessage(tool) };
 }
 
+// After an update, the first quiet start in each tool says what is new, once.
+// Deleting the installer's note is the claim, as creating the marker is for
+// the welcome.
+function whatsNew(ctx) {
+  const { env, tool } = ctx;
+  const file = updatedFromPath(env, tool);
+  if (!existsSync(file) || ctx.unattended()) return null;
+  let from;
+  try {
+    from = readFileSync(file, 'utf8').trim();
+    unlinkSync(file);
+  } catch {
+    return null;
+  }
+  const message = whatsNewMessage(from, ctx.version, tool);
+  return message ? { systemMessage: message } : null;
+}
+
 function onSessionStart(payload, ctx) {
   // Only a brand-new conversation gets a brief; a resumed, compacted or
   // forked one already has its own history.
@@ -288,8 +345,9 @@ function onSessionStart(payload, ctx) {
   // be asked through its command line, which on Windows takes a PowerShell
   // run, so it is asked only once a brief or the welcome is at stake.
   if (ctx.tool === 'claude' && ctx.unattended()) return null;
-  // The welcome waits for a start that has nothing else to say.
-  const result = briefAtStart(payload, ctx) ?? welcome(ctx);
+  // The welcome, or what is new since an update, waits for a start that has
+  // nothing else to say.
+  const result = briefAtStart(payload, ctx) ?? welcome(ctx) ?? whatsNew(ctx);
   quietly(ctx, () => ctx.checkUpdates?.());
   let notice = null;
   quietly(ctx, () => (notice = startNotice(ctx.version, ctx.env)));