Claude Code 2.1.251: хук PreModelSwitch превращает переключение модели в управляемое решение

Система хуков Claude Code давала операторам детальный контроль над вызовами инструментов — заблокировать bash-команду, перехватить запись файла, логировать MCP-активность. Выбор модели при этом оставался вне контроля: запрос на переключение от пользователя или sub-agent просто выполнялся. Никакой точки вмешательства не было: модель менялась без подтверждения. Релиз 2.1.251 закрывает этот пробел.

Что изменилось в 2.1.251

В релизе появились два новых hook-события и несколько функций видимости затрат, превращающих клиент в полезный уровень операционного управления.

PreModelSwitch срабатывает до того, как Claude Code применяет переключение модели, запрошенное пользователем или клиентом. Хук выполняется синхронно — Claude Code ждёт результата перед продолжением. Поведение по умолчанию, если хук зарегистрирован, но не вернул решение: блокировка, переключение отменяется. Чтобы разрешить — хук должен явно вернуть allow. Чтобы отклонить с пояснением — deny с полем permissionDecisionReason. Хук получает from_model и to_model во входных данных, поэтому скрипт политики может проверить по allowlist, не разбирая контекст сессии.

PostModelSwitch срабатывает после смены модели, в том числе при восстановлении модели при возобновлении сессии. Он асинхронный — подходит для логирования переключений, корректировки downstream-конфигурации или отправки в аудит-трейл.

Контекст возобновления SessionStart теперь включает «устарелость» сессии и оценочную стоимость повторного кэширования. Команды, прогревающие контекстное окно при старте, могут сначала проверить, остался ли кэш тёплым, и только потом запускать полный прогрев. Это снижает затраты на повторное кэширование контекста, который всё равно остаётся тёплым с прошлой сессии.

Видимость лимита расходов появляется для команд, работающих через Claude apps gateway с ежемесячным ограничением бюджета. В /usage появилась панель с прогрессом расходов, а в строку статуса добавлено поле rate_limits.spend_limit — доступное для shell-скриптов, парсящих машиночитаемый статус Claude Code. Раньше лимит был виден только в биллинговом дашборде gateway, теперь он доступен прямо внутри клиентской сессии.

Метрики prompt cache на сессию появились в /cost: коэффициент попаданий, промахи кэша, повторно закэшированные токены и индикатор тёплый/холодный. Для команд с длительными agent-прогонами это превращает утилизацию кэша из догадки в измеримый показатель на сессию.

Что операторам не хватало раньше

Пробел с переключением модели критичен в двух операционных сценариях.

Первый — ограничение корпоративной лицензии. Многие команды разворачивают Claude Code с enterprise-контрактом, покрывающим Sonnet, но не Opus. До 2.1.251 пользователь, вручную переключившийся на Opus в середине сессии, или sub-agent, настроенный на Opus, отправлял запрос, и успех зависел от того, блокирует ли gateway запрос на уровне API. Такая блокировка даёт непрозрачную ошибку — сессия падает без объяснения причины. Хук PreModelSwitch может вернуть deny с понятным объяснением.

Второй — исполнение ценовой политики. Некоторые конфигурации gateway маршрутизируют запросы к разным provider в зависимости от имени модели. Переключение на более дорогую модель в середине сессии может обойти логику роутинга, которая применялась бы при старте сессии. Хук, проверяющий to_model по пороговой стоимости и блокирующий или запрашивающий подтверждение, закрывает эту лазейку.

Хук и enforceAvailableModels: в чём разница

С версии 2.1.176 в managed settings есть enforceAvailableModels. Оба контрола не дублируют друг друга — они работают на разных уровнях.

enforceAvailableModels — статическая блокировка через managed settings, обычно деплоится организационным файлом managed settings. Любой model ID, которого нет в списке, отклоняется на этапе проверки managed settings. Обновление требует публикации нового файла managed settings.

PreModelSwitch — runtime-хук. Он срабатывает в момент запроса переключения и принимает динамические решения: запросить лимит бюджета пользователя из внешнего API, сравнить с текущей квотой проекта, залогировать переключение и разрешить его с аннотацией. Хук можно задеплоить на уровне проекта через .claude/settings.json, не публикуя организационный managed settings.

Для строгого allowlist-контроля подходит enforceAvailableModels. Для динамической политики, учитывающей runtime-состояние, нужен PreModelSwitch.

Исправления безопасности: что нужно проверить

Три исправления безопасности в 2.1.251 стоит сопоставить с собственным развёртыванием.

Symlink traversal в файловых инструментах: Read, Write и Edit следовали за symlink, подменённым внутри рабочей директории после проверки прав. Атакующий с доступом на запись мог создать symlink на путь за пределами разрешённой директории и вызвать чтение или запись файла. Исправлено — проверка прав теперь охватывает разрешённый путь.

Path traversal в плагинах: команды плагинов, объявленные в записи marketplace, могли ссылаться на пути за пределами директории плагина. Теперь такие пути отклоняются при загрузке с ошибкой path traversal.

OTEL bypass через project settings: project settings могли включить логирование тела API-запросов или детальный beta-трейсинг в обход OTLP-коллектора, закреплённого managed settings или host app. Исправлено. Команды, использующие managed settings для фиксации OTLP-эндпоинта, должны убедиться, что коллектор получает все трейсы, а не только те сессии, где project settings не переопределяли уровень трейсинга.

Для операторов gateway: если организация использует managed settings для управления адресатами трейсов и политикой хранения данных, исправление в 2.1.251 закрывает путь утечки. Если фиксация OTLP — часть compliance-конфигурации, обновление обязательно.

Что настроить или проверить

Минимальная политика для хука PreModelSwitch, блокирующая любое переключение на модель вне одобренного списка, в .claude/settings.json выглядит так:

{
  "hooks": {
    "PreModelSwitch": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/check-model-policy.sh"
          }
        ]
      }
    ]
  }
}

Shell-скрипт читает from_model и to_model из stdin как JSON и либо ничего не возвращает (блокировка), либо явно возвращает allow. Поскольку PreModelSwitch синхронный, переключение будет ждать завершения скрипта. При необходимости скрипт может запрашивать внешние сервисы — например, API управления бюджетом — и принимать решение на основе актуального остатка пользовательской квоты, а не только на основе статического аллулиста.

Для поля лимита расходов: если в развёртывании есть shell-скрипты, отправляющие данные о стоимости в дашборд, добавьте rate_limits.spend_limit к полям для парсинга. Его наличие означает, что сессия работает за gateway с активным лимитом; значение показывает остаток бюджета. Таким образом, команда может прервать работу задолго до исчерпания лимита, а не обнаруживать исчерпание после факта.

Для исправления OTEL: запустите claude --version, убедитесь в 2.1.251, затем проверьте коллектор трейсов на наличие всех логов без пропусков.

Что стоит сделать пользователям TheRouter

Командам, маршрутизирующим Claude Code через шлюз разработчика TheRouter, хук PreModelSwitch — самый чистый способ применить политику роутинга на стороне клиента до того, как запрос достигнет уровня API. Хук, сравнивающий to_model с моделями, поддерживаемыми вашим configured provider, предотвращает запросы к модели, которую gateway всё равно отклонит, и даёт куда более понятный результат, чем downstream-ошибка 404.

Метрики кэша на сессию в /cost тоже стоит мониторить: стабильно низкий коэффициент попаданий означает избыточные расходы на повторное кодирование контекста, что сказывается на стоимости на уровне роутинга даже при неизменных ценах на модели.