Сигнал из хука Клауд дев: по умолчанию кеш субагентов в Claude Code живёт всего 5 минут. Если субагент простаивает дольше, дешёвое чтение из кеша пропадает, и следующий запрос снова пишет весь контекст. Лечится одной строкой "subagentPromptCacheTtl": "1h", но Борис Черный из команды Claude Code отмечает, что настройки по умолчанию подходят большинству, и менять их стоит только после замера. Ниже — как это устроено по документации Claude Code про кеширование и как принять решение по своим логам. Витрина — vibe-studio.uk.
Соседи: Cache Control: полоска 5-минутного кеша, Haiku 5.5 как субагент, лимиты Claude Code и экономия токенов, уборка AGENTS.md.
Как кеш работает в Claude Code
Каждый запрос к модели несёт системный промпт, инструменты и всю историю диалога. Кеш позволяет не пересчитывать этот префикс: если он совпал с прошлым запросом, токены читаются из кеша по сниженной цене. Каждое попадание в кеш продлевает его жизнь, поэтому пока вы работаете без пауз, кеш тёплый. Время жизни (TTL) у API два: 5 минут и 1 час.
Claude Code делит запросы на две корзины:
- Основной диалог — ваши ходы в сессии, запуски -p и ходы Agent SDK.
- Всё остальное — субагенты, воркфлоу, тиммейты, форки, сжатие контекста и заголовки сессий.
Значения по умолчанию из документации:
- Подписка Claude в пределах лимита плана: основной диалог — 1 час, всё остальное — 5 минут (кроме небольшой группы служебных запросов, которыми Anthropic управляет на сервере).
- Usage credits, API-ключ или облачный провайдер: обе корзины — 5 минут.
- Когда вы вышли за лимит подписки и Claude Code списывает usage credits, основной диалог тоже падает до 5 минут.
Отсюда и эффект из хука: субагент, который ждёт прогона тестов, сборки или ответа основного агента дольше 5 минут, на следующем шаге платит за запись всего своего контекста заново.
Почему час — не бесплатно
Запись в кеш дороже обычного входа, а чтение — намного дешевле. По прайсу API Anthropic запись 5-минутного кеша стоит 1,25× от цены входных токенов, часового — 2×, чтение — около 0,1× (у части новых моделей ниже). Это те же множители, на которых построен скрипт проверки ниже.
- Час выигрывает, когда субагент простаивает от 5 до 60 минут и потом продолжает работу: вместо полной перезаписи контекста — дешёвое чтение.
- Час проигрывает на коротких рывках: если субагент отрабатывает за пару минут и больше не нужен, каждая запись стоит 2× вместо 1,25×, а длинная жизнь кеша не пригождается.
- После паузы больше часа разницы почти нет: кеш истечёт в обоих режимах.
Борис Черный объяснил логику дефолтов в ответах в X: API обычно используют для нагрузок в духе Agent SDK, где час в среднем дороже, поэтому там 5 минут. Интерактивной работе по умолчанию дан час, потому что людям это в среднем дешевле.
Как включить
Две настройки, каждая принимает только 5m или 1h, любое другое значение Claude Code игнорирует. Нужна версия v2.1.242 или новее.
- promptCacheTtl или переменная CLAUDE_CODE_PROMPT_CACHE_TTL — основной диалог.
- subagentPromptCacheTtl или переменная CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL — субагенты и всё остальное.
Пример: в файле ~/.claude/settings.json добавьте строку "subagentPromptCacheTtl": "1h" внутрь фигурных скобок рядом с остальными настройками.
Если вы работаете через API-ключ или облачного провайдера, основному диалогу час тоже нужно включать явно через promptCacheTtl. Для отдельного субагента есть поле cacheTtl в экспериментальном frontmatter файла агента (с v2.1.248). Порядок приоритета такой: FORCE_PROMPT_CACHING_5M=1 принудительно ставит 5 минут обеим корзинам, дальше переменная окружения корзины, потом настройка, потом frontmatter субагента, потом ENABLE_PROMPT_CACHING_1H=1 и только затем значение по умолчанию.
Сначала замер: скрипт по своим логам
В хуке приложен скрипт cache_gap_check.py. Что он делает по своему описанию:
- Только читает: ничего не пишет и не ходит в сеть, нужен только Python 3 без зависимостей.
- Сканирует транскрипты Claude Code в ~/.claude/projects, выбирает запросы субагентов и меряет паузы между их соседними запросами за последние 14 дней (флаг --days).
- Считает стоимость кеша при текущих 5 минутах и при гипотетическом часе в единицах цены входного токена.
- Выдаёт вердикт: «скорее стоит» при экономии больше 5%, «не стоит» при удорожании больше 5%, «на грани» в промежутке.
Запуск: python3 cache_gap_check.py, для машинного вывода — --json. Если у вашей модели чтение кеша дешевле 0,1×, передайте --read-mult. Смотрите на долю запросов с паузой 5–60 минут: именно там час окупается.
Как проверить, что кеш работает
- /usage (с v2.1.251) показывает строку Prompt cache (main): доля попаданий, промахи и тёплый ли кеш сейчас. С v2.1.260 там же — вероятная причина последнего промаха.
- claude -p "hello" --output-format json — в usage.cache_creation видно, какой TTL получили записи: ephemeral_1h_input_tokens или ephemeral_5m_input_tokens.
- Высокое отношение чтений к записям — кеш работает. Если записи высокие ход за ходом, что-то меняет префикс. Документация называет типичные причины: смена модели, смена effort, включение fast mode, подключение или удаление MCP-сервера, включение плагина, сжатие контекста, обновление Claude Code.
Соседний рычаг: /autocompact 400k
В том же треде Лидия Халли разобрала автосжатие. Автокомпакт действительно заменяет диалог коротким саммари, но на моделях с контекстом 1M он срабатывает около 967K токенов. До этого момента каждое сообщение несёт всю историю: большая часть читается из кеша, но всё равно идёт в расход и растёт вместе с диалогом. Команда /autocompact 400k заставляет сжимать на 400K, и сообщения не разрастаются до предела. Для длинных сессий вайб-кодинга это часто важнее TTL субагентов.
Практическое правило для вайб-кодера
- Субагенты короткие и одноразовые (поиск по коду, ревью файла) — оставьте 5 минут.
- Субагенты долгие и ждут внешних событий (тесты, сборка, деплой, ответ основного агента) — прогоните скрипт и включайте час, если вердикт «стоит».
- Не меняйте модель и набор MCP посреди задачи: каждый такой шаг — полная перезапись кеша.
- Длинные сессии ограничьте /autocompact 400k, а инструкции агенту держите короткими — подробно в разборе уборки AGENTS.md.
- Через неделю повторите замер: структура работы меняется, и настройка, которая окупалась, может перестать.
Если вы собираете продукт с трафиком — лендинг, бота или панель вроде TG Lead Finder — субагенты обычно гоняют тесты и сборки, то есть как раз ждут. Это первый кандидат на замер.
Коротко
В Claude Code основной диалог на подписке кешируется на час, а субагенты — на 5 минут. Настройка "subagentPromptCacheTtl": "1h" (v2.1.242+) убирает перезапись контекста после пауз 5–60 минут, но делает каждую запись дороже: 2× вместо 1,25×. Решайте по своим логам скриптом cache_gap_check.py, проверяйте кеш через /usage и не забывайте про /autocompact 400k. Источник — документация Claude Code: prompt caching.