Полный справочник — это 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 читайте эти поля, чтобы отличить вызов субагента от вызова основного диалога и узнать, требует ли ваша организация подтверждения для инструмента коннектора:
e.agentId: задано, когда вызов делает субагент или участник команды, работающий в том же процессе, и отсутствует, когда вызов делает основной диалогe.ceiling:askдля инструмента коннектора, для которого ваша организация установилаask, в сессиях, где эта настройка доходит до Claude Code
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иhoverText:size,mono,tabularиhoverButton:hotkey,plain,autoFocus,actionиhover, поэтому там пользователь нажимает кнопку щелчком или клавишей Enter, когда кнопка в фокусе. Расширение также игнорируетvariantиrole.Code:language,path,startLine,formatиwrap, поэтому код рисуется без цветов и номеров строк, а блок сformat: 'diff'показывает необработанный текст diffInputиSelect:autoFocus, а такжеrowsуInputSvg: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. Квадратные скобки обозначают необязательный аргумент.