Claude Code Mods: события, API и сценарии

Карта событий Claude Code Mods: точки подключения, ограничения, безопасность и сценарии для интерфейса, контекста и контроля действий агента.

Как это устроено

Чтобы в списке было проще ориентироваться, разделю точки подключения на три группы:

Такое разделение есть в справочнике, в разделах Events и Mods API calls. Группы пересекаются: например, ui.close встречается и при закрытии панели пользователем, и при вызове API. Поэтому просто сложить количество строк и получить общее число событий не получится.

Если работали с Express, принцип будет знаком: цепочка middleware. Обработчик получает $ — API среды, e — данные события и next — переход к следующему обработчику. Он может пропустить событие дальше, изменить данные или обработать его самостоятельно. Подробности — в руководстве по событиям.

Но есть нюанс: у каждого события свой формат входных данных и ответа. Вернуть deny в любом обработчике не получится. Я бы начинал с конкретной задачи, находил подходящее событие и уже затем смотрел его типы и ограничения. В корпоративном окружении часть возможностей может быть закрыта политикой организации.

События движка

Начнём с событий, которые возникают в работе самого Claude Code: вызов инструмента, отправка промпта, запуск субагента, отрисовка панели. В таблицах — что можно изменить и где это пригодится.

Инструменты

Источник: Mods reference, группа Tools и Guard or change a tool call.

Тут важно различать сам вызов и разрешение на него. tool.call позволяет вмешаться в выполнение, tool.check — в решение, можно ли его выполнять. Ещё один нюанс: если мод вернул свой результат вместо вызова инструмента, реальная операция могла вообще не произойти.

Промпты и контекст

Источник: справочник, группа Prompts and what Claude reads. Дополнительные поля редактора описаны в типах PromptEditInput и PromptEditResult; перед реализацией их нужно сверить с установленной версией.

Значения origin.kind и типы вложений могут меняться от версии к версии. Если логика мода зависит от конкретного значения, проверьте его в локальных типах.

Отдельно про скрытие данных. Можно убрать email с экрана, но он по-прежнему останется в контексте модели или сохранённой истории. Для записи демо это удобно; для удаления чувствительных данных одной такой правки мало.

Команды и настройки

Источник: справочник, группа Commands and configuration; регистрация собственных команд разобрана в Use the mods API.

Если мод спрятал настройку в интерфейсе, это ещё не значит, что её нельзя поменять другим способом. Обязательные правила нужно проверять там, где они действительно применяются.

Ходы модели

Источник: Follow a turn.

За один ход Claude может несколько раз обратиться к модели и вызвать инструменты. Поэтому на turn.step удобно смотреть отдельные запросы, а на turn.complete — результат всего хода.

У turn.step есть техническая особенность: обработчик работает как async generator. Если хотите подменять ответ модели, придётся разобраться с форматом потока в своей сборке — особенно с thinking- и tool-call-блоками. Совместимость такой подмены с разными моделями нужно проверять отдельно.

Сессия

Источник: справочник, группа Session и обмен сообщениями между сессиями.

Подводный камень: /clear, /resume и /branch сами по себе не запускают session.start повторно. Инициализацию мода и смену разговора стоит обрабатывать отдельно.

У session.compact в типах v2.1.277 описаны дополнительные возможности: менять instructions, набор сообщений и возвращать собственный результат сжатия. Если хотите использовать их в своём моде, сначала сверьтесь с типами установленной версии.

С session.append похожая история про данные: изменение одной сохраняемой строки не убирает её из предыдущих запросов, результатов инструментов или других журналов. На одном этом событии обещать полное удаление секрета я бы не стал.

Субагенты

Источник: справочник, группа Subagents.

В опубликованных типах у agent.spawn можно менять и другие параметры: промпт, тип агента, фоновый режим, рабочую директорию. При этом есть исключения — например, fork наследует модель родителя. Поэтому назначить любую модель любому субагенту не получится.

Интерфейс

Источник: Draw in the interface и таблица событий интерфейса.

ui.close есть и среди событий интерфейса, и среди методов API. Для ui.fault в справочнике указана минимальная версия 2.1.289 — на более старой сборке рассчитывать на него не стоит.

Теперь про то, где именно можно рисовать интерфейс. В Render sites перечислены такие области:

AskUserQuestion — диалог, в котором агент задаёт пользователю вопросы. Запрос разрешения на действие — другой элемент интерфейса. Возможность изменить первый не означает, что можно перерисовать второй.

Другие моды

Источник: справочник, группа Other mods и корпоративные policy-моды.

Здесь всё зависит от порядка загрузки. Мод, который проверяет другие расширения, должен стоять раньше них. Как это настроить, показано в административной документации.

Телеметрия

Источник: справочник, группа Telemetry.

Для установленного мода в таблице указан фильтр { to: 'collector' }. Подписка через * телеметрию не захватит. При этом наличие подписки ещё не гарантирует, что в неё придут нужные отметки — это нужно проверить в своей сессии.

Есть и другая тонкость: слушать телеметрию и отправлять собственные записи через $.telemetry.* — разные возможности. Отправка через эти методы разрешена движку и встроенным модам; это отражено в типах telemetry-мода. Поэтому считать их обычным API для аналитики своего плагина не стоит.

Классические события: `classic.*`

Если уже работали с settings hooks, здесь будут знакомые названия. Эти события доступны с префиксом classic. и именем события, например classic.PostToolUse, с соответствующими данными на входе. Связь описана в Mods reference, а допустимые ответы — в Hooks reference.

Ниже — 33 имени из исходной подборки. Для удобства убрал из таблицы повторяющийся префикс, но при регистрации он нужен: classic.PostToolUseclassic.PostToolUse, а не просто PostToolUse.

Что можно вернуть из обработчика, зависит от события. Например, MessageDisplayMessageDisplay меняет отображение сообщения. Текст, который сохраняется в истории и отправляется модели, остаётся прежним.

И ещё оговорка для корпоративных окружений: при активном sec-default перехват classic.* пользовательским модом может быть недоступен. К этому вернусь в разделе про безопасность.

Mods API: что может делать сам мод

До этого речь шла в основном о действиях агента. Но мод и сам может прочитать файл, запустить процесс или сделать HTTP-запрос. Для этого есть mods API. Например, tool.call позволяет работать с вызовом инструмента, а fs.read — с чтением файла через API самого мода. Ограничения у этих путей различаются.

В справочнике есть общее правило: методы API также доступны как события с именем namespace.method. Часть этих имён уже встречалась выше, поэтому здесь удобнее смотреть на возможности по группам.

Сведения о самом плагине можно получить через $.plugin.name и $.plugin.root. Это свойства; прибавлять их к списку вызываемых методов-событий не нужно.

Ещё два нюанса, на которые я бы обратил внимание:

• session.surface в старых типах помечен deprecated. Для нового кода смотрите session.surfaces — это имя используется и в публичном справочнике.
• Можно ли перехватывать ui.ask через on('ui.ask', ...)? Исходная подборка утверждала, что нельзя. Приведённых материалов недостаточно для уверенного ответа по v2.1.289, поэтому перед реализацией такой проверки нужно испытать свою сборку.

И здесь важен порядок обработчиков: мод видит те вызовы API, которые проходят через него дальше по цепочке. Все процессы и сетевые соединения на машине он таким способом контролировать не начинает.

Подводные камни

Где будет работать интерфейс

С интерфейсом есть ограничения. По таблице сред исполнения, обработчики могут работать в разных типах сессий, если туда загружен плагин. А собственные панели доступны в терминале и поддерживаемых сессиях Desktop.

В панели чата VS Code, claude -p и Agent SDK нельзя рассчитывать на ту же панель. В Remote Control интерфейс мода остаётся в локальном терминале. Для cloud-сессии плагин должен быть доставлен в неё; в WSL-сессиях Desktop плагины не поддерживаются.

Поэтому для важных действий я бы сразу предусмотрел команду или текстовый ответ. Если панель недоступна, пользователь всё равно должен понимать, что произошло и как продолжить.

Время и ошибки

Обработчик не может выполняться бесконечно. В таблице Limits указаны такие ограничения:

Время ожидания внутри next и большинства API-вызовов обычно не расходует собственный бюджет обработчика. Но $.clock.sleep — исключение: его ожидание учитывается.

Теперь неприятный нюанс. Если обработчик упал до next, а обработчика ошибки нет, хук пропускается. Если ошибка произошла после завершения next, сохраняется уже полученный результат. Для мода, который должен блокировать опасную команду, это принципиально: заранее решите, что делать при собственной ошибке. Пример с .catch и запретом операции есть в документации.

Что на самом деле защищает sec-default

Для Team/Enterprise и окружений с управляемыми настройками есть встроенный guard sec-default: по умолчанию он не позволяет пользовательским модам отменять deny-правила для вызовов инструментов Claude. Администратор может изменить это через allowModsToOverrideDenyRules.

В опубликованном коде sec-default есть ещё одно ограничение: пользовательские моды пропускаются при обработке classic.*, prompt.section, prompt.context, prompt.compose, skill.prompt, attribution.text и settings.read. Обычные settings hooks при этом продолжают работать.

Отказ managed PreToolUse имеет окончательный приоритет. С обычным PreToolUse и правилом ask ситуация другая: мод может изменить итоговое решение. Поэтому фраза «sec-default не даёт обходить permission-правила» требует уточнения — какие именно правила и для каких действий.

Про безопасность

Trade-off никуда не делся: чем больше контроля, тем выше цена ошибки. Мод — это код, который работает с правами вашей учётной записи, включая доступ к файлам, процессам и сети.

Но песочницей мод от этого не становится — его собственные обращения к файлам и запуск процессов через $.fs и $.process правилами для инструментов Claude не ограничиваются. Поэтому доверие к автору расширения всё равно имеет значение.

Отсутствие обычного Node.js-доступа здесь легко принять за изоляцию. На деле мод получает доступ к окружению через mods API. Отсутствие require само по себе ничего не гарантирует; при этом речь идёт о правах вашей учётной записи, а не об автоматическом получении root-прав.

Кэш и повторное выполнение

Динамическое изменение контекста и инструкций может снижать эффективность prompt cache — на это указывает руководство по событиям. Я бы не добавлял в стабильные разделы системного промпта текущее время, случайные идентификаторы и показатели, которые постоянно меняются.

С повторными вызовами тоже стоит быть аккуратнее. Инструмент мог записать файл или отправить сообщение, а затем вернуть ошибку. Если просто запустить его ещё раз, можно получить повторный эффект. Перед добавлением retry проверьте идемпотентность — то есть не создаст ли повторное выполнение ещё одну операцию.

Шаблоны подписки

Подписываться можно и по шаблонам. В опубликованных типах описаны *, варианты вроде tool.*, отрицания и фильтры по значениям, спискам и регулярным выражениям. У телеметрии, как уже разобрали выше, свои ограничения.

Для первого мода я бы выбирал точные имена событий. Так проще понять, что вы действительно перехватили, и не получить лишнюю работу на каждом событии.

Что я бы попробовал собрать

Ниже — несколько идей, с которых можно начать. Для каждой указал события и то, что я бы проверил перед использованием.

Для моего dz-harness самый интересный сценарий — вывести состояние харнесса прямо в Claude Code: на каком этапе задача, какие знания попали в контекст и что показали проверки. Начал бы с панели состояния и recall, где видно, что именно память добавила агенту.

Общую логику, память и проверки я бы сохранял переносимыми между средами. А моды использовал как дополнительный слой интеграции — чтобы происходящее внутри харнесса было проще видеть и контролировать.

План такой интеграции вынес в отдельный issue в dz-harness: панель состояния, отдельное описание того, как мод подключается и работает, и проверка совместимости защит. Там же — последовательность работ и критерии, по которым можно будет проверить результат.

А будут ли моды работать с моделями других разработчиков?

Отдельный вопрос, который хочется проверить на практике. Anthropic не поддерживает подключение non-Claude моделей через шлюзы, поэтому официальную совместимость здесь обещать нельзя.

Можно предположить, что часть обработчиков интерфейса и инструментов будет работать и со сторонним адаптером. Но это предположение по архитектуре. Подтвердить его можно только на конкретной связке.

При этом $.model.complete использует учётные данные сессии, а $.model.fork — её модель и системный промпт; это описано в API. Эти методы сами по себе не дают универсального доступа к любому LLM-провайдеру.

Если уже пробовали — расскажите, какая модель, через какой адаптер и какие именно моды заработали.

Как попробовать и проверить свой мод

В руководстве по созданию модов есть команды для запуска и проверки. Я бы прошёл по ним в таком порядке:

➊ Проверьте установленную версию:

claude --version

➋ Посмотрите код плагина, который собираетесь запустить, и выполните статическую проверку:

claude plugin validate ./my-mod

В строке hooks: должны быть ожидаемые подписки, в calls: — обращения к API. Успешная валидация говорит о прохождении этой проверки. Работает ли сам сценарий и можно ли доверять коду, нужно разбирать отдельно.

➌ Загрузите мод в тестовом проекте:

claude --plugin-dir ./my-mod

После загрузки смотрите типы внутри его каталога:

.claude-plugin/types/claude-code/index.d.ts

Если этот файл расходится с веб-документацией, приоритет у локальных типов — документация прямо на это указывает.

➍ Если у мода есть тесты, выполните их из его каталога:

claude plugin test

➎ Проверьте, что произойдёт при нормальном выполнении, отказе пользователя, ошибке обработчика, hot reload и запуске без интерфейса. Если мод отвечает за защиту, добавьте второй мод, который пытается изменить разрешение, и посмотрите на итог. Для экспериментов со сторонней моделью запишите версии Claude Code, адаптера и самой модели.

Если плагин загружается, но ничего не делает, начните с проверки загрузки и доверия к проекту. Совет про IS_DEMO=1 из исходной подборки я бы не давал как универсальный: его актуальная связь с запуском mods в приведённых материалах не подтверждена.

Что уточнил при сверке исходной подборки

При подготовке разбора сравнивались разные версии: публичный Mods reference для v2.1.289 и опубликованные типы, помеченные v2.1.277. Поэтому детали из старого файла типов нельзя автоматически переносить в новую сборку.

Локально claude plugin validate и поведенческие тесты не запускались. Утверждения про «138 подтверждённых событий» и «3 115 отклонённых имён» оставил за рамками: без логов и типов той сборки подтвердить эти числа нельзя.

Мой вывод

Для меня самое интересное здесь — возможность видеть работу агента прямо в процессе: какой контекст он получил, почему остановился, что показали проверки. И там же дать пользователю действие: посмотреть детали, отменить команду или продолжить.

Начал бы с одной понятной задачи. Например, показать, какие знания попали в контекст, или разобрать последствия команды до запуска. Под такую задачу уже проще выбрать событие и понять, приносит ли мод пользу.

С разрешениями, системными инструкциями и потоком ответов работы будет больше: там особенно важны версия API, порядок модов и поведение при ошибках. Эту карту удобно держать под рукой при проектировании. А дальше — собирать небольшой мод и проверять его на своём рабочем сценарии.

Первоисточники

• Mods reference — публичная карта событий, методов, UI и лимитов.
• React to events — middleware, порядок вызовов, ошибки и разрешения.
• Use the mods API — команды, инструменты, модели и обмен сообщениями.
• Draw in the interface — панели и элементы интерфейса.
• Manage mods for your organization — sec-default и корпоративная политика.
• Hooks reference — классические события и их результаты.
• Create a mod — локальные типы, validate и тестирование.
• Mods overview — права и среды исполнения.
• Troubleshoot a mod — диагностика загрузки.
• Типы Anthropic на проверенном коммите — снимок, помеченный v2.1.277.
• Исходник sec-default на том же коммите.

Автор: @llm_notes.