Claude Code теперь называет вероятную причину промаха кеша промпта

В Claude Code 2.1.260 появилась диагностика, закрывающая давний пробел в отладке расходов: когда кеш промпта промахивается, теперь сообщается почему. Версия 2.1.251 уже добавляла строку Prompt cache (main) в блок Session команды /usage, но эта строка только считала промахи. Знание того, что вы оплатили три полных перечитывания диалога на 300k токенов, не подсказывает, от чего именно стоит отказаться. Начиная с 2.1.260 строка называет вероятную причину, например likely cause: tool definitions changed.

Почему промах дорог и незаметен

Claude Code отправляет весь диалог заново на каждом ходе, поэтому именно кеширование делает длинную сессию доступной по цене. API сопоставляет префикс запроса, и сопоставление точное: изменение в любом месте префикса приводит к пересчету всего, что идет после него. Кеширования по файлам или по сегментам не существует. Именно поэтому документация по prompt caching перечисляет конкретный набор действий, которые сбрасывают кеш: смена модели, подключение или отключение MCP-сервера, когда поиск инструментов не откладывает его инструменты, запрет целого инструмента простым deny-правилом вида Bash, а также обновление самого Claude Code.

Проблема в том, что большинство этих действий незаметны. Stdio-сервер MCP, процесс которого тихо завершился, или истекшая HTTP-сессия меняют определения инструментов посреди сессии без единого сообщения в транскрипте. Вы видите только медленный ход и счет.

Claude Code считает запрос промахом, когда тот заново обработал более 5% и не менее 2000 токенов из того, что мог бы прочитать из кеша, при условии что ни компактизация, ни очистка старых результатов инструментов эту разницу не объясняют. Перестроения из-за компактизации считаются отдельно как expected rebuilds, что сохраняет честность счетчика промахов.

Как прочитать причину из строки состояния

Самое интересное для тех, кто пишет скрипты строки состояния: диагностика структурирована, а не сводится к тексту. В 2.1.260 объект prompt_cache получил поля last_miss_cause и miss_causes. Массив causes содержит имена вроде tools_changed, system_prompt_changed, ttl_expired_5m или likely_server_side, и два из них дополняются счетчиками: tools_changed идет вместе с tools_added и tools_removed, а system_prompt_changed вместе с system_char_delta.

#!/bin/bash
input=$(cat)
cause=$(echo "$input" | jq -r '.prompt_cache.last_miss_cause.causes[0] // empty')
ratio=$(echo "$input" | jq -r '.prompt_cache.hit_ratio // 0')
printf "cache %.0f%%" "$(echo "$ratio * 100" | bc -l)"
[ -n "$cause" ] && printf " | last miss: %s" "$cause"

Поле last_miss_cause равно null до первого промаха в сессии, а также каждый раз, когда Claude Code не смог определить причину, поэтому чтение нужно защищать. miss_causes дает агрегированную картину: сессия, в которой tools_changed встречается пять раз, говорит о нестабильном MCP-сервере, а не о единичном случае.

Счетчики берутся из полей кеш-токенов в ответе API, поэтому все это работает на Bedrock, на Google Cloud’s Agent Platform и через шлюз. Учитывается только основной диалог, но не субагенты, а /clear сбрасывает статистику.

В том же релизе появилась панель /diff, которая открывается рядом с диалогом в полноэкранном режиме и отслеживает незакоммиченные изменения по мере того, как Claude редактирует код. Если вы следите за чередой релизов, в 2.1.261 добавили /skill-doctor на следующий день. Полные заметки лежат в релизе v2.1.260, а справочник по полям находится в документации строки состояния.