~/blog/claude-code-mods-events

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

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

Поделиться
Содержание · 26 разделов

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

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

ГруппаЧто происходитПример
События движкаClaude Code собирается выполнить действиеtool.call, prompt.submit, ui.render
Классические событияНаступает событие, знакомое по settings hooksclassic.PostToolUse, classic.Stop
Вызовы mods APIМод обращается к API средыfs.read, process.run, model.complete

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

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

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

Где мод включается в работу Claude Code

Событие Claude Code

Данные о конкретном действии движка или доступном классическом событии.

Обработчик мода

Получает данные события e, API среды $ и функцию next для передачи дальше.

Передать дальше

Вызвать next и продолжить цепочку обработчиков; при необходимости изменить данные события.

или

Ответить самому

Вернуть собственный результат, если это допускает контракт конкретного события.

Отдельная возможность обработчика

API среды

При необходимости обработчик делает собственный вызов через $. Это отдельная возможность, а не обязательный шаг каждого события.

Возможности среды

Файлы, процессы, сеть, модели и интерфейс — через соответствующие методы API.

Упрощённая карта связей. Возможности зависят от события, версии, среды выполнения и политики организации. Методы API также имеют события; их перехват зависит от порядка модов. Мод работает с правами пользователя и не является песочницей.

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

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

Инструменты

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

СобытиеЧто можно сделатьВозможный сценарий
tool.callПерехватить вызов, изменить аргументы, отказать, вернуть свой результат или дождаться решения пользователяПредварительный просмотр рискованной команды; проверка пути перед записью; журнал вызовов
tool.checkУчаствовать в решении allow, ask или deny после остальных проверок, с учётом политик организацииДополнительное согласование операции в зависимости от ветки Git или состояния задачи
tool.describeИзменить описание инструмента; управлять его отложенной загрузкой через tool searchУточнить назначение похожих инструментов; убрать редко используемый инструмент из начального набора

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

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

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

СобытиеКогда срабатывает и что позволяетВозможный сценарий
prompt.submitПромпт отправлен: изменить текст, добавить контекст для модели или остановить отправкуДобавить подходящие знания из памяти; добавить сведения о проекте
prompt.fillТекст помещается в поле ввода как черновикПодготовить шаблон запроса на ревью
prompt.suggestПоявляется подсказка в поле вводаПредложить следующий шаг по текущему этапу работы
prompt.editПользователь редактирует ввод; подробный контракт допускает преобразование вставляемого текстаПривести вставленный текст к нужному виду; проверить формат без сетевого запроса на каждое нажатие
prompt.composeСобираются разделы системного промптаСформировать профиль инструкций для определённого процесса
prompt.sectionОбрабатывается отдельный именованный раздел системного промптаЗаменить раздел либо исключить его, если это разрешено политикой
prompt.contextФормируется начальный контекст разговораДобавить сведения о репозитории или согласованной задаче
prompt.attachmentClaude Code добавляет собственное сообщение, например напоминаниеАдаптировать служебную подсказку к рабочему процессу
skill.promptРазворачивается текст навыкаПодставить проектные параметры в инструкцию навыка
attribution.textФормируется атрибуция коммита или pull requestПривести подпись к принятому в команде формату

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

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

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

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

СобытиеЧто происходитВозможный сценарий
command.runВыполняется slash-команда; мод может обработать её и вернуть результат/harness-status, /review-summary, открытие панели
command.describeФормируется описание команды в спискеПонятные описания команд проекта; скрытие ненужной позиции
config.setМеняется строка /config; значение можно скорректировать или отклонитьПроверить допустимый диапазон настройки
config.describeОтображается строка /configДобавить понятное название и пояснение

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

Ходы модели

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

СобытиеЧто происходитВозможный сценарий
turn.startНачинается ходЗафиксировать время и состояние задачи
turn.stepОтправляется очередной запрос модели внутри ходаВыбрать доступную модель или effort для этого запроса; собрать статистику токенов и кэша
turn.completeХод завершился, в том числе после прерыванияОбновить панель, записать длительность и расход, добавить краткую строку результата

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

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

Сессия

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

СобытиеЧто происходитВозможный сценарий
session.startМод начинает работу перед первым промптом и после своей перезагрузкиЗарегистрировать команды и инструменты; запустить таймер обновления панели
session.endЗавершается сессия либо выполняется переход вроде /clear, /resume, /branchКороткая финальная запись состояния
session.compactГотовится сжатие контекстаОтложить compaction с объяснением; при поддержке контракта уточнить, что сохранить в сводке
session.receiveПриходит сообщение от другого агента или сессииУбрать повторные сообщения; отметить входящее сообщение
session.sendОтправляется сообщение другому агенту или сессииПроверить адресата; запретить отправку по правилам процесса
session.appendСтрока разговора готовится к сохранениюПреобразовать сохраняемое содержимое в пределах контракта
session.attachК сессии подключается другой клиентОтметить подключение в панели состояния
session.detachКлиент отключаетсяОбновить сведения о подключениях
session.measureОбновляются измерения после хода или доля использованного лимита планаОбновить показатели контекста, лимитов и стоимости

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

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

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

Субагенты

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

СобытиеЧто можно сделатьВозможный сценарий
agent.offerНе предлагать определённый тип субагентаУбрать агента, который не подходит текущему этапу
agent.spawnВыбрать модель запускаемого субагента или отклонить запускПроверить условия запуска; назначить доступную модель по роли

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

Интерфейс

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

СобытиеЧто происходитВозможный сценарий
ui.renderОтрисовывается область интерфейсаПанель процесса, индикатор контекста, оформление результата инструмента
ui.resolveФормируется таблица доступных UI-элементовНастройка элементов для последующих модов, если позволяет политика
ui.pressНажата кнопка модаОткрыть детали проверки или запустить явно выбранное действие
ui.inputИзменено поле ввода модаФильтрация списка задач
ui.selectВыбран пункт спискаПереключить представление или профиль
ui.focusМеняется фокус внутри панели или полосы над промптомУправление клавиатурной навигацией
ui.scrollМеняется положение прокруткиНавигация в журнале событий
ui.closeЗакрывается панельОбработать закрытие пользователем, модом или при выгрузке
ui.messageЭлемент Client отправляет данные своему модуОбмен сообщениями с собственным интерактивным компонентом
ui.faultКомпонент Client не загрузился, не отрисовался или завершился ошибкой исполненияПоказать упрощённый вариант интерфейса и сведения об ошибке

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

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

Где рисуемИмена областей
Собственные панели и полоса над промптомPane, AbovePrompt
Сообщения и инструментыUserMessage, AssistantMessage, ToolUse, ToolResult, ToolGroup, CommandOutput
Другие элементыAskUserQuestion, Spinner, SessionMode, PromptHint
Только терминалToolProgress, TurnDuration, InfoNotice

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

Другие моды

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

СобытиеЧто можно сделатьВозможный сценарий
plugin.registerПроверить декларацию загружаемого мода и отказаться от его загрузкиНе допускать расширения, которые запускают процессы или читают определённые переменные окружения
engine.createИзменить создаваемый объект mods APIДобавить собственную группу методов или ограничить доступные возможности

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

Телеметрия

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

СобытиеНазначениеВозможный сценарий
telemetry.logПерехват записи телеметрииФильтрация потока в собственный collector
telemetry.markСобытие отметки использования функцииРабота с доступным потоком отметок; наличие фактических событий требует проверки

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

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

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

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

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

СобытияВозможный сценарий
PreToolUseПроверка вызова до выполнения
PostToolUse, PostToolUseFailureЗапись результата либо разбор ошибки инструмента
PostToolBatchСводка после завершения всей группы вызовов, включая параллельные
PermissionRequest, PermissionDeniedОбработка запроса разрешения или отказа в формате, который поддерживает событие
Stop, StopFailureПроверка завершения работы или обработка нештатного окончания
SubagentStart, SubagentStop, TeammateIdleНаблюдение за жизненным циклом исполнителей
TaskCreated, TaskCompletedОбновление панели задач
FileChanged, CwdChanged, DirectoryAddedОбновление контекста проекта при изменении файлов и рабочей области
WorktreeCreate, WorktreeRemoveПодготовка и учёт изолированных рабочих деревьев
InstructionsLoaded, ConfigChangeУчёт загруженных инструкций и изменений конфигурации
PreModelSwitch, PostModelSwitchПроверка или фиксация переключения модели
PreCompact, PostCompactСохранение важных фактов вокруг сжатия контекста
Elicitation, ElicitationResultОбработка запроса дополнительного ввода от MCP-сервера и его результата
MessageDisplay, NotificationИзменение отображения или обработка уведомлений
SessionStart, Setup, SessionEndИнициализация, настройка и завершение
UserPromptSubmit, UserPromptExpansionРабота с отправленным запросом и разворачиванием команды в промпт

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

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

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

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

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

ПространствоМетоды из текущей публичной таблицыЧто на этом можно построить
fsread, write, list, exists, stat, ancestorsЖурнал обращений к файлам; ограничение записи
processrun, spawnУчёт и контроль запуска внешних программ
httpfetchКонтроль запросов, проходящих через этот API
mcpcall, connectРабота с MCP-инструментами и серверами
modelcomplete, fork, classifyВспомогательные модельные задачи, проверка параметров вызова
storeget, set, delete, keysОбщее хранилище значений между сессиями на машине
stateget, setРеактивное состояние интерфейса и мода
envget, setУчёт чтения и изменения переменных окружения
settingsreadЧтение настроек в пределах разрешённого контракта
clocknow, sleep, after, everyТаймеры и фоновое обновление состояния
audioplay, speakЗвуковой сигнал или озвучивание статуса
uiresolve, invalidate, open, close, panes, focus, scroll, toast, status, log, notice, ask, copy, selection, blitПанели, навигация, вопросы, уведомления, работа с выделением
commandregister, run, listСобственные команды и их вызов
toolregister, call, check, listРегистрация инструментов, вызовы и проверка разрешений
agentregister, spawn, listРегистрация и запуск субагентов
configlist, setДоступ к конфигурации
promptsubmit, read, fill, suggest, composeРабота с вводом и запуск следующего хода
turnabortПрерывание текущего хода
sessionmessages, cwd, root, model, turns, id, repo, surfaces, usage, version, compact, send, append, authorizeДанные сессии, сообщения, статистика и операции с разговором
telemetrylog, markОграниченный служебный API; не универсальная отправка аналитики из пользовательского мода

Сведения о самом плагине можно получить через $.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 указаны такие ограничения:

ОграничениеЗначение
Собственное время обработчикаОбычно 10 секунд
prompt.edit50 мс
Обработчик .catch1 секунда
Все session.end вместеПо умолчанию 1,5 секунды; бюджет настраивается

Время ожидания внутри 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.*, отрицания и фильтры по значениям, спискам и регулярным выражениям. У телеметрии, как уже разобрали выше, свои ограничения.

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

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

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

СценарийОсновные события и методыЧто проверить до использования
Панель harness-hubsession.measure, turn.complete, ui.render, $.process.runАктуальность данных; не выполняется ли долгая работа во время отрисовки
Панель recallprompt.submit, ui.render, $.http.fetch или MCPЧто именно добавлено в контекст; не добавляются ли одни и те же знания повторно
Предпросмотр опасной командыtool.call, $.ui.askОтказ пользователя, закрытие диалога, тайм-аут, запуск без UI
Проверка разрешения по состоянию задачиtool.checkПриоритет managed-политик и взаимодействие с другими модами
Выбор модели для отдельного шагаturn.step, agent.spawnДоступность модели, стоимость, правила наследования
Наблюдение за исполнителямиagent.spawn, turn.complete, session.receive, session.sendРазличие главного агента и субагентов; повторные доставки
Учёт стоимости и задержекturn.step, turn.complete, session.measureНе учитывается ли один запрос дважды — отдельно и в сумме за ход
Просмотр измененийclassic.PostToolUse, ui.render, command.runКакие правки действительно выполнены; доступен ли classic-перехват
Режим демонстрацииui.render или classic.MessageDisplayЧто скрыто только на экране и где данные остаются доступны
Политика установки модовplugin.register, перехват API-вызововПорядок загрузки и область действия проверки

В моём dz-harness часть этой задачи уже закрывает statusline: этап активной задачи, прогресс и общие счётчики памяти. Поэтому повторять эти показатели в отдельной панели я бы не стал. Мод интересен как подробный просмотр recall: раскрыть конкретную запись, прочитать её текст и отфильтровать список прямо в Claude Code. Сведения о том, что действительно добавлено в контекст и что показали проверки, ещё потребуется передать из харнесса и проверить — сама панель этого не доказывает.

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

План такой интеграции вынес в отдельный 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 отклонённых имён» оставил за рамками: без логов и типов той сборки подтвердить эти числа нельзя.

Что было в исходникеЧто уточнил
«138 событий; проверено 3 115 других имён»Убрал неподтверждённые результаты локального эксперимента
Разбиение 44 + 33 + 61Не использую как общий итог: группы пересекаются, API зависит от версии
ui.close только в разделе APIВключил и в события интерфейса
В документации нет ui.fault и ui.selectionВ reference v2.1.289 оба имени уже есть
ui.fault только про загрузку и отрисовкуДобавил ошибку исполнения — фазу run
session.surface как обычный методУказал deprecated; для нового кода ориентир — session.surfaces
telemetry.mark практически недоступенРазделил подписку, наличие событий и право отправлять записи
ui.ask точно нельзя перехватыватьОставил вопрос для проверки на конкретной сборке
У всех обработчиков 10 секундДобавил исключения: prompt.edit, .catch и общий бюджет session.end
Любое ожидание API не расходует бюджетУточнил исключение для $.clock.sleep
Хуки работают во всех средахДобавил условия загрузки плагина и ограничение Desktop/WSL
Любой classic-хук может блокировать или менять результатУточнил, что допустимый ответ зависит от события
sec-default защищает все операцииУточнил, какие правила он сохраняет и почему собственные вызовы API мода ими не изолированы
Поля из старых типов автоматически актуальны для v2.1.289Отделил опубликованный снимок от типов установленной сборки

Мой вывод

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

Для первого мода я бы выбрал просмотр записей памяти, переданных агенту в контекст. Это конкретный сценарий: можно выбрать подходящее событие API, показать сами записи и проверить, помогает ли такая панель понимать работу агента.

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

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

Автор: @llm_notes.

Поделиться
Продолжение

Обсудить разбор

Напишите, если хотите разобрать свою задачу в таком же формате
написать
Следить за новыми записями
aicoding.spaceКурсы, инструменты и мастерская по Agentic Engineering. Код инструментов открыт.
Считаем посещения обезличенно, на своём сервере. Данные не передаются третьим лицам и не используются для рекламы. На время демонстрации подключён виджет-помощник с sufler.aicoding.space: ему уходит только то, что вы ему пишете.