Перейти к основному содержанию
Здесь можно найти любое событие, которое может обрабатывать мод, любой метод API модов, который он может вызвать, и любую точку отрисовки, в которой он может рисовать. Записи охватывают CLI Claude Code и приложение Desktop по состоянию на v2.1.290, а также расширение VS Code по состоянию на v2.1.299. Для каждой записи указаны имя и однострочное описание, а также ссылка на раздел руководства с пояснениями, если такой раздел есть.
Полный справочник — это TypeScript-декларации Claude Code для модов, в которых описаны все события, методы и элементы с примерами. Копия на GitHub может быть старше установленной у вас версии Claude Code. Если они расходятся, доверяйте копии, которую Claude Code записывает для вашей версии.

Файлы

Мод — это каталог плагина со следующими файлами: register получает on и options. options содержит значения полей userConfig, объявленных в манифесте, с подставленными значениями по умолчанию.

Функция хука

Мод регистрирует каждый из своих хуков, то есть обработчиков событий, вызывая on внутри register. on принимает имя события, необязательный matcher, то есть фильтр по полям события, и сам хук, например on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e)). on возвращает регистрацию с одним методом, .catch(handler), который задаёт обработчик ошибок хука.

События

События сгруппированы по тому, к чему они относятся; для каждого указано, когда оно срабатывает и что может вернуть хук на него. Хуки на turn.step и process.spawn — асинхронные генераторы, остальные хуки — асинхронные функции. В последнем столбце каждой таблицы используется сокращённая запись. next(e) передаёт событие дальше без изменений. next({ ...e, text }) передаёт дальше копию с изменённым указанным полем, например next({ ...e, text: e.text.trim() }). Объект отвечает на событие без вызова next, а слово вроде reason обозначает строку, которую вы пишете, например { deny: 'Use the file tools.' }.

Инструменты

События инструментов срабатывают вокруг каждого вызова инструмента, который делает Claude, — от описания, которое читает Claude, до решения о том, будет ли вызов выполнен:

Поля агента и организации в tool.check

В хуке tool.check читайте эти поля, чтобы отличить вызов субагента от вызова основного диалога и узнать, требует ли ваша организация подтверждения для инструмента коннектора: В tool.check поля e.agentId и e.ceiling требуют Claude Code v2.1.290 или новее.

Поле e.isReadOnly в tool.check

В хуке tool.check поле e.isReadOnly равно true, когда инструмент сообщает, что этот вызов выполняется только для чтения. В противном случае поле отсутствует, а не равно false. Значение — это собственное сообщение инструмента, поэтому прочитайте раздел Проверка того, выполняется ли вызов инструмента только для чтения, прежде чем подтверждать вызов только на основании этого поля. В tool.check поле e.isReadOnly требует Claude Code v2.1.304 или новее.

Промпты и то, что читает Claude

События промптов охватывают текст, который вводит пользователь, и текст, который Claude Code отправляет Claude сам, например системный промпт и напоминания:

Поля источника и frontmatter в skill.prompt

В хуке skill.prompt можно читать эти поля наряду с именем скилла в e.skill и текстом, который читает Claude, в e.text: Хук может передать изменённые text или frontmatter в next: хуки после него читают оба поля, а Claude читает итоговый text. Хук, который изменяет любое другое поле, завершается ошибкой. В skill.prompt поля e.source, e.pluginName, e.path, e.frontmatter и e.frontmatterProblem требуют Claude Code v2.1.299 или новее.

Отправка изменённого раздела системного промпта или описания инструмента с помощью breakPromptCache

Чтобы изменить раздел или описание инструмента в текущем диалоге, вызовите $.ui.invalidate('prompt.section') или $.ui.invalidate('tool.describe'), чтобы ваш хук запустился снова. Верните из него { text, breakPromptCache: true } или { description, breakPromptCache: true }. Без этого поля Claude продолжает читать текст, сохранённый вместе с диалогом, для раздела или инструмента, загруженного сразу, до начала нового диалога или сжатия контекста. Изменённый текст доходит до Claude на следующем ходе, а кэш промптов начинается заново, поэтому этот ход выполняется медленнее и обходится дороже. Это поле требует Claude Code v2.1.321 или новее. С v2.1.299 до v2.1.321 текущий диалог получал изменённый текст на следующем ходе.

Команды и конфигурация

e.layers и e.source в settings.read

  • e.layers: по одному объекту { source, settings } для каждого используемого источника, содержащего настройки, начиная с самого низкого приоритета. См. Что получает хук settings.read.
  • e.source: единственный источник, который запросил мод, например $.settings.read({ source: 'policy' }). Отсутствует при собственном чтении Claude Code и при чтении объединённых настроек

Ходы

События ходов отслеживают один ответ от начала до конца, включая каждый запрос к модели в его рамках:

Сессия

События сессии отмечают запуск, завершение и сжатие сессии, а также обмен сообщениями с другими сессиями:

Субагенты

События субагентов срабатывают, когда тип субагента предлагается Claude и когда субагент или участник команды агентов вот-вот запустится: Ваш хук agent.spawn также запускается, когда субагент, который завершил работу или был остановлен, вот-вот снова запустится, например когда Claude отправляет ему сообщение с помощью инструмента SendMessage. В этом событии e.resume равно { agentId }. Если ваш хук подсчитывает субагентов, пропускайте события, в которых задано e.resume, чтобы возобновлённый субагент не учитывался повторно. Верните { deny: reason }, чтобы отклонить возобновлённый запуск. Запуск не начинается, и субагент остаётся в прежнем состоянии. Если запуск запросил вызов SendMessage, Claude читает в качестве результата этого вызова a plugin declined the resume:, за которым следует ваша причина. Если для возобновлённого запуска вы передаёте в next изменённое событие, например с другой model, Claude Code игнорирует это изменение.
Событие для возобновлённого запуска требует Claude Code v2.1.299 или новее. До v2.1.299 ваш хук agent.spawn не запускался при возобновлении субагента. В этих версиях, чтобы отклонять вызовы SendMessage, которые возобновляют субагента, сопоставляйте этот инструмент в хуке tool.call.

Интерфейс

События интерфейса срабатывают, когда Claude Code рисует точку отрисовки и когда пользователь использует элемент управления, нарисованный модом. В разделе Рисование в интерфейсе показано, что возвращает хук ui.render:

Другие моды

Эти события позволяют моду воздействовать на другие моды при их загрузке: отклонить мод или изменить получаемый им API модов: Когда хук другого мода вызывает метод пространства имён, которое вы добавили в engine.create, вызовы $ вашего метода выполняются в контексте этого хука, пока все хуки на этом событии не вернут результат. Например, относительный путь разрешается относительно рабочего каталога этого хука, а $.prompt.submit отклоняется, пока ход ожидает этот хук. Вызовы, которые ваш метод делает после этого, выполняются в собственном контексте вашего мода.

Телеметрия

События телеметрии срабатывают для записей об использовании, которые логирует Claude Code:

События хуков настроек

Каждое событие хука настроек — это событие с именем classic.<Event>, например classic.Stop или classic.PostToolUse. e — это JSON, который хук получает через stdin.

Вызовы API модов

Каждый метод API модов также является событием, названным по его пространству имён и методу, например fs.read, model.complete или ui.open. Хук на такое событие может вернуть next(e), { deny: reason } или { value }. Некоторые из этих событий срабатывают и для собственных действий Claude Code, поэтому, прежде чем отклонять такое событие, проверьте, равно ли next.origin.plugin значению engine.

Поля собственных запросов http.fetch Claude Code

В хуке http.fetch значение next.origin, равное { plugin: 'engine', tier: 'core' }, отмечает один из собственных запросов Claude Code, например запрос к модели, а не вызов $.http.fetch мода. Там, где загружен встроенный страж, ваш хук не получает эти события, за исключением случаев, когда ваш мод считается модом вашей организации. В этих событиях e.init и value, в которое разрешается next(e), могут содержать, среди прочего, следующие поля: Эти события и поля требуют Claude Code v2.1.321 или новее.

Методы API модов

API модов — это аргумент $, который получает каждый хук. Его методы сгруппированы по пространствам имён, например $.ui. В этой таблице методы каждого пространства имён перечислены по имени, поэтому open в строке $.ui — это вызов $.ui.open(...). В руководствах показано использование распространённых методов, а в типах для вашей сборки каждый метод документирован с примером.

Точки отрисовки

Точка отрисовки — это точка расширения в интерфейсе Claude Code. Каждая строка — это значение e.component в хуке ui.render с полями e.props и приложениями, которые её отрисовывают. e.surface указывает приложение, которое выполняет отрисовку, например terminal, desktop или vscode. В разделе Изменение того, что уже рисует Claude Code показано, что хук может делать в точке отрисовки, с примером для каждого варианта. Для отрисовки в расширении VS Code требуется расширение версии 2.1.299 или новее. Сессии, которая не получает флаги функций, требуется версия 2.1.304 или новее. В разделе Рисование в расширении VS Code перечислено, что расширение рисует иначе. e.viewport содержит columns, rows и isFullscreen. В терминале и в приложении Desktop он отсутствует, пока приложение не измерило своё окно. Там его rows — это высота всего окна, а не вашей панели. В расширении VS Code он присутствует всегда. Чтобы подогнать дерево под точку отрисовки, читайте в хуке следующие пропсы:
  • Ширина Pane или полосы: рисуйте по e.props.bodyColumns
  • Высота Pane рядом с транскриптом: когда e.props.placement равно 'dock', e.props.scroll.bodyRows — это число строк, которые панель отводит под ваше дерево
  • Высота Pane над промптом: когда e.props.placement равно 'inline', панель растёт вместе с вашим деревом до предела, а bodyRows — это этот предел. Чтобы запросить другой предел, см. поле rows в $.ui.open.
Дерево, которое выше панели, прокручивается целиком.

Элементы

Элементы — это строительные блоки дерева, которое возвращает хук ui.render, и вы получаете их из $.ui.resolve(e). В разделе Построение дерева из элементов показаны распространённые элементы и то, как их рисует терминал, а в галерее интерфейса есть снимки экрана большинства из них. Галочка означает, что приложение умеет рисовать элемент. Дополнительные правила для Button:
  • action: указывает одно из собственных действий сочетаний клавиш Claude Code, и сочетание, назначенное пользователем для этого действия, нажимает кнопку, если это аккорд или клавиша с модификатором
  • Цифровые горячие клавиши на полосе: цифровой hotkey на кнопке в полосе также срабатывает, когда пользователь вводит только эту цифру в пустой промпт и делает паузу
  • Свёрнутая полоса: пока полоса свёрнута, ни привязка action, ни горячая клавиша не нажимают кнопку в ней
  • Две кнопки с одной горячей клавишей: если две ваши кнопки в одной отрисовке указывают один и тот же hotkey, он достаётся более поздней. О кнопке другого мода с той же клавишей см. Горячие клавиши не работают.
  • variant: primary или secondary, любое другое значение вызывает исключение. В терминале кнопка primary рисуется акцентным цветом, если она не plain.
  • role: dismiss помечает кнопку закрытия, любое другое значение вызывает исключение. Само закрытие выполняйте в своём onPress. В полосе, содержащей текст и ряд кнопок, приложение Desktop может нарисовать первую кнопку dismiss в ряду как собственный элемент управления закрытием. Терминал рисует кнопку так же, как без role.
Button может содержать children вместо label:
  • Чем могут быть дочерние элементы: строки и элементы Text, например имя, за которым следует приглушённая деталь, или цветная плашка. Claude Code отклоняет любые другие элементы внутри Button.
  • Имя кнопки: label задаёт имя кнопки и по умолчанию равен тексту её дочерних элементов. Задайте key или label для кнопки, дочерние элементы которой не являются одной строкой.
  • В терминале: дочерние элементы рисуются на месте метки, а нажатие в любом месте на них считается одним нажатием, поэтому каждую строку списка можно сделать одной кнопкой
  • В приложении Desktop и расширении VS Code: кнопка рисует свой label
Button с дочерними элементами, отличными от одной строки, требует Claude Code v2.1.295 или более поздней версии.
autoFocus на любом элементе управления принимает только true, поэтому, чтобы отключить его, опустите этот проп. Расширение VS Code игнорирует некоторые пропсы элементов и рисует элемент так, как если бы вы их не указали:
  • Box: position вместе с его top, left, right и bottom, alignSelf, borderDimColor и hover
  • Text: size, mono, tabular и hover
  • Button: hotkey, plain, autoFocus, action и hover, поэтому там пользователь нажимает кнопку щелчком или клавишей Enter, когда кнопка в фокусе. Расширение также игнорирует variant и role.
  • Code: language, path, startLine, format и wrap, поэтому код рисуется без цветов и номеров строк, а блок с format: 'diff' показывает необработанный текст diff
  • Input и Select: autoFocus, а также rows у Input
  • Svg: isInteractive

Стили рамки Box

Чтобы нарисовать рамку вокруг Box, задайте для его borderStyle одно из этих имён, например borderStyle: 'round'. В каждой строке указано, что терминал рисует для этого имени, и показан верхний край рамки. Box, у которого borderStyle указывает любое другое имя, например 'rounded', рисуется без рамки.

Шаги отступов Box

Пропсы отступов Box — это gap, columnGap, rowGap, padding, margin, а также формы padding и margin для одной стороны и одной оси, например paddingX и marginTop. Каждый из них принимает число ячеек терминала, например gap: 1, или имя шага, например gap: 'md'. В терминале и расширении VS Code каждый шаг равен следующему числу ячеек: Если задать для gap, padding или margin шаг, он применяется сразу и по горизонтали, и по вертикали. Например, в терминале и расширении VS Code padding: 'md' означает две ячейки с каждой стороны и одну строку сверху и снизу. Имена шагов требуют Claude Code v2.1.299 или более поздней версии. В более ранних выпусках дерево, в котором используется имя шага, не рисуется.

Типографские пропсы Text

Задайте size, weight, mono или tabular для Text, чтобы запросить у приложения, рисующего ваше дерево, размер текста, насыщенность, моноширинный шрифт или цифры одинаковой ширины. Прежде чем полагаться на проп, проверьте, что делают с ним терминал и расширение VS Code. Если приложение игнорирует заданный вами проп, ваше дерево всё равно рисуется там, а текст выглядит так, как если бы вы этот проп не указали. Эти четыре пропса требуют Claude Code v2.1.299 или более поздней версии. В более ранних выпусках дерево, в котором задан size, weight, mono или tabular, не рисуется.

Замена bold на weight

bold для Text объявлен устаревшим в пользу weight, но по-прежнему работает. Чтобы заменить его для Text без weight, измените bold: true на weight: 'semibold' — в Claude Code v2.1.299 или более поздней версии результат будет тем же. В выпусках до v2.1.299 дерево, в котором задан weight, не рисуется. Если задать для Text и bold, и weight, bold не действует.

Ограничения

Хуки и вызовы API модов выполняются с ограничениями по времени и размеру. Claude Code пропускает хук, превысивший ограничение по времени. Дерево, превышающее ограничение по вложенности, числу элементов, ячейкам Raster или байтам Image, не отрисовывается.

Настройки и переменные окружения

Ниже перечислены настройки и переменные окружения, влияющие на моды. В столбце «Где» указано, из какого файла настроек или окружения читается каждая из них: sec-default@builtin — это страж, встроенный в Claude Code, который отображается как cc-plugin-sec-default в /plugin и в отладочном логе. Там, где он загружается, он выполняется перед каждым модом, установленным человеком. Если задан управляемый prependPlugins, страж загружается, только если этот список его называет, на указанной позиции. Его исходный код находится в каталоге mods/sec-default репозитория Claude Code.

Команды

Эти команды и флаги загружают, проверяют и тестируют мод. Команды claude выполняются в вашей оболочке, а команды / — в промпте Claude Code. В таблице <directory> обозначает путь, который вы вводите, например claude plugin validate ./first-mod. Квадратные скобки обозначают необязательный аргумент.