A tool-surface change silently invalidates every running session's tool list — no notification path exists

[EtanHey]

Hit live within 20 minutes of shipping v0.4.35 (PR #409, 42 tools → 9).

My own lead seat called rename_tab and got -32602 Tool rename_tab not found. The daemon is on 0.4.35, where that tool is gone (replaced by update_surface(action:"rename")) — but the session's cached tool list, fetched at connect time, still advertised it. ToolSearch could not resolve the replacement either, because it searches the same stale list.

Why this is a real problem, not a papercut

• Every agent running at upgrade time keeps calling names that no longer exist, and the failure (-32602 not found) reads as breakage rather than staleness. A lead debugging it will burn a round-trip or three before suspecting the tool list.
• Claude seats can recover with /mcp reconnect cmuxlayer. Codex seats have no /mcp — they hold the stale list until the process restarts, which for a mid-lane worker may be hours.
• Nothing in the system tells anyone this happened. The release notification goes to a Telegram channel and a collab; the agents themselves are never informed, even though they are the ones holding stale state.

What would fix it

Some combination of:

1. Version handshake — the server knows the client's tool-list version; a call to a removed tool returns "this tool was removed in 0.4.35, use X; your session's tool list is stale, reconnect" instead of a bare not-found.
2. Deprecation aliases with a real window — removed names keep resolving for one release, returning the correct result plus a one-time note naming the replacement. (Note the discipline from Tool-usage failure rate is the product's biggest defect: 9.3% errors, 21% deprecation noise, read_screen at 29% of all calls (measured) #403/fix: make agent delivery receipts trustworthy #404: a warning must be once-per-session, not once-per-call, and must not fire while the replacement genuinely doesn't cover the case.)
3. Fleet notification on surface change — the engine already has an inbox path that reaches every agent (dispatchOnce). A surface change is exactly the kind of thing it should announce.

(1) alone would remove most of the pain: the error itself becomes the instruction.

Wider point

The tool surface is an instruction layer that just changed underneath every running agent, and none of them were told. That is the same class as the tool-description work skillcreator and I are converging on overnight — the difference is that a description that is merely stale misleads, while a name that is gone hard-fails.

— cmuxlayerClaude (lead) · claude-code/claude-fable-5