Перейти к основному содержанию
Мод — это плагин, который выполняет код внутри Claude Code с разрешениями пользователя, который его установил. Моды не изолированы в песочнице. Через управляемые параметры вы решаете, будут ли моды работать на машинах ваших пользователей, какие именно и в каком порядке. Вы также можете установить собственный мод, который отслеживает или отказывает в том, что делают другие моды. Эта страница предназначена для человека, который развертывает управляемые настройки для Claude Code, будь то в виде файла, через MDM или из консоли администратора claude.ai. Моды включены по умолчанию в Claude Code v2.1.286 и более поздних версиях. Начните с раздела, который соответствует тому, что вы хотите сделать:
Эти случаи рассматриваются на других страницах:

Остановить загрузку установленных пользователем модов

Чтобы ни один мод, который приносят ваши пользователи, не запускал свои хуки, установите параметр allowManagedModsOnly для встроенного стража — мода политики, который Claude Code загружает перед каждым модом, установленным пользователем. Параметр задаётся в управляемых настройках в pluginConfigs с ключом cc-plugin-sec-default@builtin:
managed-settings.json
Когда параметр установлен в управляемых настройках:
  • Ни один мод, который приносит пользователь, не запускает свои хуки: это касается мода в плагине, установленном пользователем, мода, загруженного с помощью --plugin-dir, и мода, который Claude написал во время сессии
  • Моды вашей организации по-прежнему работают: мод, который считается модом вашей организации, не проверяется. Все остальные моды считаются модами пользователя и отклоняются. Это включает мод, который ваша организация включает для своих участников на claude.ai. Если ни один мод не считается вашим, ни один установленный мод не запускает свои хуки.
  • Пользователи не могут это отменить: страж читает параметр только из управляемых настроек, поэтому та же запись в файле настроек пользователя, проекта или локальных настроек или в файле, переданном с помощью --settings, ничего не меняет
  • Файл или политика MDM охватывают каждого поставщика: когда вы доставляете параметр в виде файла или через MDM, он работает одинаково на Amazon Bedrock, Google Cloud’s Agent Platform и Microsoft Foundry. Для доставки из консоли администратора claude.ai см. Доступность платформы
  • Другие настройки пользователей продолжают работать: их хуки в файлах настроек и в hooks/hooks.json плагинов, строки состояния и /goal не затрагиваются
  • Встроенные моды продолжают работать: у каждого из модов, встроенных в Claude Code, таких как поддержка AGENTS.md, есть свой собственный переключатель
Чтобы проверить параметр на машине пользователя, запустите там Claude Code с --plugin-dir и путём к каталогу, который содержит мод, например claude --plugin-dir ./first-mod. Хуки мода не запускаются, а транскрипт и отладочный лог содержат сообщение стража, в котором указаны мод и allowManagedModsOnly. Если сообщения нет, см. Проверить, что политика действует и правила, которые определяют, вступает ли параметр в силу. Если вы установили CLAUDE_CODE_ENABLE_FUNCTION_HOOKS в 0 во время раннего доступа, замените его этим параметром. Claude Code v2.1.287 и более поздние версии игнорируют переменную при любом значении, поэтому 0 в ней оставляет моды включёнными.

Узнать, что происходит по умолчанию

Без собственных параметров модов вот что получают ваши пользователи:
  • Моды включены. Пользователь может установить плагин, содержащий мод из любого маркетплейса, который разрешают ваши параметры плагинов, или загрузить его из каталога с помощью --plugin-dir.
  • Встроенный страж запускается первым. Claude Code загружает встроенный мод с именем sec-default@builtin перед каждым модом, установленным пользователем. Пользователи не могут его отключить. /plugin и отладочный лог указывают его как cc-plugin-sec-default. Страж загружается, когда верно одно из следующих условий: Пользователь с API-ключом или работающий через Amazon Bedrock, Google Cloud’s Agent Platform или Microsoft Foundry получает стража только на машине с управляемыми настройками или managed-mcp.json. Сессия, работающая на долгоживущем CLAUDE_CODE_OAUTH_TOKEN, тоже не считается таким входом, даже если на машине сохранён вход с планом Team или Enterprise.
  • Страж защищает то, чем вы управляете. Мод пользователя не может изменить то, что получают или решают ваши управляемые хуки, системный промпт, а также ваш управляемый CLAUDE.md и другие управляемые инструкции. Он также не может изменить то, что любой мод читает как настройки, или инструменты и описания ваших управляемых MCP-серверов после их подключения.
  • В v2.1.323 и новее мод пользователя может помешать подключению управляемого MCP-сервера. В сессии этого пользователя /mcp показывает сервер как удерживаемый этим модом. Чтобы это предотвратить, запретите загрузку модов, установленных пользователями.
  • За пределами того, чем вы управляете, мод пользователя действует от имени этого пользователя. Мод сохраняет разрешения этого пользователя: он по-прежнему может читать и записывать файлы, запускать процессы и выполнять сетевые запросы. Он также может переписывать вызовы инструментов и промпты, отклонять вызов инструмента, добавлять или удалять инструменты и рисовать в интерфейсе.
  • Правила разрешений и хуки PreToolUse имеют приоритет над модом пользователя. Когда страж загружен, по умолчанию мод пользователя не может одобрить вызов, который отклоняет правило deny или для которого правило ask запрашивает подтверждение, независимо от того, в каком файле настроек находится правило. Мод также не может одобрить вызов, заблокированный любым хуком PreToolUse. Правила разрешений и хуки PreToolUse применяются к вызовам инструментов Claude, а не к вызовам $.fs и $.process мода. При запрещённом Read(.env) мод всё ещё может прочитать этот файл с помощью $.fs.read или запустить программу, которая это сделает. Чтобы ограничить собственные вызовы $.fs и $.process мода, запретите загрузку мода или обработайте их в моде политики.
  • Мод пользователя всё ещё может пропускать некоторые запросы разрешения. В авторежиме вызов, одобренный модом, выполняется без проверки классификатора, если только страж не загружен и сессия не запущена с --permission-prompt-tool или обратным вызовом canUseTool Agent SDK. В этом случае классификатор сначала проверяет вызов. О запросах разрешения, которые подтверждение мода не пропускает, см. Расширение разрешений с помощью хуков.
Исходный код защиты является общедоступным в каталоге mods/sec-default репозитория Claude Code.

Узнать, какие элементы управления по-прежнему применяются

Моды не заменяют элементы управления, которые у вас уже есть:
  • Хуки настроек продолжают работать. Хуки команд, HTTP, промптов и агентов в файлах настроек и в hooks/hooks.json плагинов работают как раньше, наряду с модами.
  • Правила отказа имеют приоритет, где загружается защита. Мод пользователя не может одобрить вызов, который правило deny отказывает, если вы не установите allowModsToOverrideDenyRules.
  • Управляемые хуки запускаются первыми. Хук PreToolUse в управляемых настройках запускается перед хуком tool.call любого мода, и когда этот управляемый хук блокирует вызов инструмента, ни один хук tool.call мода для этого вызова не запускается. Если вызов продолжается и мод переписывает его, ваши управляемые хуки запускаются снова на переписанном вызове, поэтому по умолчанию они всё ещё могут его заблокировать. Хуки PreToolUse из других файлов настроек и из плагинов запускаются после последнего мода. Если мод сам отвечает на вызов инструмента, инструмент не запускается, как и эти хуки. См. Порядок, в котором работают моды.
  • Сетевая политика охватывает $.http.fetch.
    • Политика вашей организации не разрешает WebFetch: Claude Code также отклоняет каждый запрос $.http.fetch любого мода. См. Доступность WebFetch.
    • Вы отключаете инструмент WebFetch с помощью CLAUDE_CODE_DISABLE_WEB_FETCH или правила deny для WebFetch в управляемых настройках или любом другом файле настроек: моды по-прежнему могут выполнять запросы $.http.fetch. Чтобы остановить их для каждого мода, который устанавливают ваши пользователи, запретите загрузку модов, установленных пользователями, или добавьте хук на http.fetch в моде политики и отклоняйте запросы от модов пользователей. Дайте этому хуку обработчик .catch, который тоже отклоняет запрос, потому что Claude Code пропускает хук, завершившийся с ошибкой, и тогда запрос выполняется. Если вы только ограничите, какие плагины могут устанавливать пользователи, загрузится меньше модов, но разрешённые вами по-прежнему смогут выполнять эти запросы.
    • Вы установили CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: мод, который устанавливаете вы или ваши пользователи, по-прежнему может выполнять эти запросы. Переменная останавливает только моды, встроенные в Claude Code, а также любой запрос $.http.fetch, который несёт учётные данные Anthropic сессии. До v2.1.288 переменная останавливала каждый запрос $.http.fetch любого мода.
    Ничто из этого не охватывает программу, которую мод запускает с помощью $.process.run: она выходит в сеть с собственным доступом пользователя.
  • Элементы управления плагинами охватывают моды. Мод — это плагин, поэтому параметры, которые ограничивают то, что пользователи могут установить, такие как strictKnownMarketplaces, определяют, может ли он быть установлен вообще.
  • Моды не могут изменить запрос разрешения. Мод может переделать большую часть интерфейса Claude Code, но не запрос разрешения, поэтому он не может изменить то, что показывает запрос. Мод все еще может одобрить или отказать в вызове инструмента перед появлением запроса, как описано в Узнать, что происходит по умолчанию.
  • Запросы доверия идут первыми. В интерактивном сеансе в каталоге, который пользователь еще не доверил, ни один мод не загружается, пока они не ответят на запрос доверия.
  • --safe-mode отключает установленные моды, включая ваши. Запустите сеанс с claude --safe-mode, чтобы проверить, вызвал ли мод проблему.
Ни один из этих элементов управления не изолирует мод в песочнице. Мод, который вы разрешаете, работает как пользователь, с доступом пользователя к файлам, процессам и сети.

Узнать, какие хуки мода пользователя не запускаются

Там, где загружается встроенный страж, хук, который мод пользователя регистрирует на одно из этих событий, никогда не запускается, и /plugin сообщает об этом пользователю в примечании. В строках session.append door — это тип сохраняемой строки, которым отфильтрован хук. Страж также пропускает хуки пользователя в некоторых других случаях, например для описаний инструментов вашей организации в tool.describe и для сохраняемой строки с текстом скилла. Для них /plugin не показывает примечания. Если хук на другое событие ничего не делает, см. Выяснить, почему мод ничего не делает. Примечание отображается в сведениях о плагине и на вкладке Errors в /plugin. Для него требуется Claude Code v2.1.299 или новее. В нём каждый хук из таблицы указан так, как его зарегистрировал мод, как в этом примере:
Чтобы эти хуки запускались, измените управляемые настройки одним из двух способов:
  • Запускать мод как мод вашей организации: установите мод так, чтобы он считался вашим. Тогда его хуки на эти события запускаются, а страж остаётся загруженным для всех остальных модов. Мод включается для всех, кто получает эти настройки. Если вы указываете его в prependPlugins, оставьте sec-default@builtin в списке.
  • Удалить стража: не включайте sec-default@builtin в prependPlugins. Достаточно пустого списка "prependPlugins": []. Вы теряете весь страж, а не только эти события. Тогда мод пользователя может делать то, от чего его иначе удерживает страж, и параметры стража не применяются.
Если вы передаёте список без стража через настройки, управляемые сервером, страж остаётся загруженным, пока сервер не подтвердит настройки для сессии. Чтобы проверить любое из изменений на машине с v2.1.299 или новее, откройте /plugin в сессии на ней и убедитесь, что примечание исчезло. Хук session.append без фильтра door по-прежнему запускается и не получает примечания, но сохраняемые строки из таблицы до него не доходят.

Решить, оставить ли моды включенными

Мод может делать больше, чем другие части плагина, потому что он работает внутри Claude Code. Он видит каждый запрос и вызов инструмента, может их изменять и может разрешить или отказать в вызове инструмента перед появлением запроса разрешения. То, что пользователь может загрузить как мод, зависит от элементов управления плагинами, которые у вас уже есть: Управление плагинами для вашей организации перечисляет способы загрузки плагина и настройку, которая управляет каждым из них. Чтобы проверить моды в маркетплейсе перед тем, как ваши пользователи их установят, см. Просмотреть возможности мода. Чтобы исключить моды пользователей, пока вы это делаете, см. Остановить загрузку установленных пользователем модов.

Просмотреть возможности мода

Вы можете увидеть, что может делать мод, не запуская его. В вашей оболочке запустите claude plugin validate в каталоге плагина:
Строки hooks: и calls: в выводе описывают код мода:
API модов, обозначаемый $ в коде мода, — это способ, которым мод получает доступ к файлам, процессам и сети. Claude Code отказывается загружать мод, который использует API модов способом, который эта команда не может прочитать. Не одобряйте мод, который не проходит эту команду, потому что некоторые ошибки не препятствуют его загрузке. Запускайте команду в Claude Code v2.1.323 или новее, где длинный список продолжается на следующих строках с той же меткой, и прочитайте каждую строку hooks: и calls:. В строках calls: обращайте внимание на следующее: В строке hooks:, tool.call и prompt.submit означают, что мод видит каждый вызов инструмента и каждый промпт и может их изменять. session.append означает, что мод может переписать каждую строку диалога перед ее сохранением, за исключением строк, которые пропускает защита. ui.render{component=AskUserQuestion} означает, что мод может переделать диалоговое окно, которое Claude использует для вопроса пользователю. tool.check означает, что мод может одобрить или отказать в вызове инструмента перед появлением запроса разрешения. Узнать, что происходит по умолчанию перечисляет, какие из ваших правил и хуков имеют приоритет над его ответом.

Выбрать, сколько разрешить

Политики модов варьируются от полного отсутствия установленных модов до любого мода, который выбирает пользователь, при этом ваш собственный мод проверяет остальные, и каждая из них — это несколько управляемых настроек. Найдите нужную политику в первом столбце и задайте то, что указано во втором столбце. В разделе Развертывание управляемых настроек описано, где находятся управляемые настройки. Что делает каждая настройка:
  • allowManagedModsOnly: параметр встроенного стража. Claude Code отклоняет собственные моды пользователей, поэтому ни один из их хуков не выполняется. Хуки настроек пользователей, строки состояния и /goal продолжают работать. В разделе Остановить загрузку установленных пользователем модов перечислено, что он охватывает.
  • allowManagedHooksOnly: более широкая настройка. Загружаются только моды вашей организации и моды, встроенные в Claude Code. Мод, который пользователь установил сам, не загружается. Настройка также блокирует хуки в собственных файлах настроек пользователей. Прочитайте Что выполняется при allowManagedHooksOnly, прежде чем задавать её.
  • disableAllHooks: самая широкая настройка. В управляемых настройках она останавливает моды в каждом установленном плагине, включая ваши, и отключает все хуки в файлах настроек, поэтому хук PreToolUse в ваших управляемых настройках больше ничего не блокирует. Пользовательские строки состояния и /goal также перестают работать. Прочитайте disableAllHooks, прежде чем задавать её.
  • disableSideloadFlags: отклоняет --plugin-dir и --plugin-url при запуске и не позволяет загружаться модам, которые Claude пишет во время сессии. Настройка также отклоняет --agents и --mcp-config. Прочитайте disableSideloadFlags, прежде чем задавать её.
Моды, встроенные в Claude Code, такие как поддержка AGENTS.md, не затрагиваются этими настройками. У каждого из них есть свой собственный переключатель. Пользователь, чей мод был отклонён или не загрузился, найдёт причину в своём логе отладки. В разделе Сообщения об отказе перечислены строки для allowManagedHooksOnly и disableAllHooks, а в разделе Сообщения от встроенного стража приведена строка для allowManagedModsOnly.

Разрешить только моды вашей организации

Чтобы запускать моды вашей организации и блокировать моды, которые приносят пользователи, разверните настройки из строки Только моды вашей организации таблицы политик, а также disableSideloadFlags. С этим полным managed-settings.json Claude Code отклоняет собственные моды пользователей, поэтому ни один из их хуков не выполняется, а ваш мод политики запускается раньше других модов:
managed-settings.json
Каждая группа ключей выполняет одну задачу:
  • extraKnownMarketplaces, enabledPlugins и prependPlugins: устанавливают ваш мод так, чтобы он считался вашим, и запускают его первым, а стража — после него. В разделе Установить моды вашей организации и задать порядок описан каталог, на который указывают эти ключи.
  • pluginConfigs: задаёт параметр стража allowManagedModsOnly, поэтому Claude Code отклоняет собственные моды пользователей. Их хуки настроек, строки состояния и /goal продолжают работать.
  • disableSideloadFlags: см. disableSideloadFlags, чтобы узнать, какие флаги она отклоняет при запуске
Чтобы проверить политику на тестовой машине, запустите в оболочке сессию с claude --debug и прочитайте лог отладки:
  • Ваш мод: его строка hooks module содержит tier prepend
  • Мод, установленный пользователем: есть строка refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly). Более ранняя строка сообщает, что модуль хуков этого мода loaded, поэтому ищите именно отказ.
  • Каталог плагина: claude --plugin-dir ./any-mod завершается с сообщением, которое начинается с --plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)
Чтобы также ограничить, какие маркетплейсы могут добавлять пользователи, объедините этот файл с вашими ограничениями маркетплейсов.

Применить ваши средства управления плагинами к модам

Мод — это плагин, поэтому способы управления плагинами для вашей организации применимы и к плагину, содержащему мод:

Задать параметры встроенного стража

Встроенный страж принимает параметры. Задайте их в управляемых настройках в pluginConfigs под ключом cc-plugin-sec-default@builtin, как это сделано в примере в разделе Остановить загрузку установленных пользователем модов. В таблице показано, что получают ваши пользователи, когда каждый параметр не задан и когда он установлен в true: Эти правила определяют, вступает ли параметр в силу:
  • Здесь id имеет только одну форму: Claude Code читает параметры только под cc-plugin-sec-default@builtin. prependPlugins также принимает sec-default@builtin, а pluginConfigs — нет.
  • Учитываются только управляемые настройки: та же запись в файле настроек пользователя, проекта или локальных настроек либо в файле, переданном с помощью --settings, не задаёт параметр и не ослабляет его
  • Страж должен загружаться: если вы задаёте prependPlugins, укажите стража в списке. Там, где страж не загружается, не применяется ни один из параметров.
  • При сбое страж отказывает: если страж не может прочитать управляемые настройки, он отклоняет все моды пользователей при загрузке. Если он не может проверить правила запрета для вызова, который одобрил мод пользователя, он отклоняет этот вызов.
Сообщения от встроенного стража — это то, что видят ваши пользователи, когда применяется любой из параметров.

Развертывание собственных модов вашей организации

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

Установка модов вашей организации и установка порядка

Моды вашей организации загружаются там, где не загружаются моды пользователей, и могут выполняться перед ними, поэтому Claude Code должен иметь возможность определить, что мод поступил от вас. Чтобы мод из удалённого маркетплейса, например из репозитория GitHub, считался вашим в v2.1.324 или более поздней версии, выполните в управляемых настройках все следующие действия:
  • Установите плагин мода в true в enabledPlugins
  • Объявите маркетплейс в extraKnownMarketplaces. Чтобы контролировать, когда меняется код мода, закрепите маркетплейс и запись мода.
  • Укажите идентификатор мода, например acme-guard@acme-tools, в prependPlugins или appendPlugins. При использовании prependPlugins также укажите sec-default@builtin, чтобы сохранить встроенного стража.
Мод в каталоге на машине пользователя считается вашим только в том случае, если все следующие условия верны:
  • Управляемый enabledPlugins устанавливает плагин мода в true
  • Управляемые настройки называют маркетплейс плагина как каталог на машине пользователя по абсолютному пути. Запись extraKnownMarketplaces делает это и также регистрирует маркетплейс для пользователя.
  • Маркетплейс указывает плагин по относительному пути, поэтому Claude Code загружает его на месте из этого каталога
Чтобы выполнить эти условия, скопируйте каталог маркетплейса на одинаковый путь на каждой машине с помощью управления устройствами. Сделайте каталог и каждый каталог выше него доступными для записи только администратором, как и файл управляемых настроек. Любой, кто может писать туда, может переписать ваш мод. Управляемые настройки, которые вы доставляете из консоли администратора claude.ai, могут содержать ключи, но они не могут поместить каталог на машину. Каталог содержит манифест маркетплейса и плагин:
Манифест указывает плагин по его пути относительно этого каталога:
/opt/acme/claude-plugins/.claude-plugin/marketplace.json
Установленный плагин, который не соответствует ни одному из этих наборов условий, считается плагином пользователя, даже если управляемый enabledPlugins его включает. Его мод выполняется среди модов пользователей, prependPlugins и appendPlugins его пропускают, allowManagedModsOnly отказывает ему, а allowManagedHooksOnly не дает ему загрузиться. Если управляемые настройки его включают, в логе отладки пользователя есть строка, которая начинается с идентификатора плагина и is enabled by managed settings, but. Claude Code вызывает событие каждый раз, когда он собирается действовать, например запустить инструмент, и передает его каждому моду по очереди. Мод, который соответствует условиям для каталога, выполняется перед модами пользователей, даже если вы его нигде не указываете. Чтобы задать его место, укажите его идентификатор в одной из двух настроек. Идентификатор — это имя плагина, @ и имя маркетплейса, например acme-guard@acme-tools.
  • prependPlugins: ваш мод видит событие раньше любого мода пользователя, а результат события — после них. Он может изменить событие, отказать в нем или пропустить моды пользователей. В v2.1.323 или более поздней версии проверьте, что ваши хуки по-прежнему достигают элементов управления и отрисовок других модов.
  • appendPlugins: ваш мод выполняется после каждого мода пользователя, поэтому он видит только события, которые эти моды передают, в форме, в которой они их передают
Этот пример объявляет маркетплейс acme-tools в /opt/acme/claude-plugins, включает acme-guard из него и запускает этот мод первым, со встроенным стражем после него:
managed-settings.json
Каждый ключ выполняет одну работу:
  • extraKnownMarketplaces: называет каталог, который содержит маркетплейс acme-tools. path — это абсолютный путь каталога, который содержит .claude-plugin/marketplace.json.
  • enabledPlugins: включает acme-guard для каждого пользователя, который получает эти управляемые настройки
  • prependPlugins: ставит acme-guard первым и встроенного стража вторым, оба впереди любого мода, который устанавливает пользователь. Claude Code следует порядку, который вы указываете.
Чтобы подтвердить, что машина пользователя получила настройки, см. Проверка того, что политика действует. Чтобы подтвердить, где выполняется мод, запустите сессию на этой машине с claude --debug и найдите в логе отладки идентификатор мода:
  • hooks module acme-guard@acme-tools loaded, с tier prepend: мод считается принадлежащим вашей организации и выполняется первым
  • Та же строка с tier user: Claude Code рассматривает его как мод пользователя. Вторая строка, prependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skipped, говорит, что список его пропустил.
Эти правила определяют, какие идентификаторы в двух списках вступают в силу:
  • Список заменяет значение по умолчанию: когда вы задаете prependPlugins в управляемых настройках, укажите в нем sec-default@builtin, чтобы сохранить встроенного стража. Страж встроен и не требует записи enabledPlugins.
  • Ваши собственные идентификаторы должны считаться вашими: в управляемых настройках Claude Code пропускает идентификатор, чей плагин не соответствует условиям для мода организации
  • Репозитории не могут задавать ни один из списков: Claude Code игнорирует оба в файле настроек репозитория, поэтому задавайте их в управляемых настройках.
  • Пользователь может задать их, чтобы упорядочить свои моды: в ~/.claude/settings.json, только на машине без управляемых настроек или файла managed-mcp.json и только если учётные данные сессии получены не через /login Team или Enterprise. В любом другом месте Claude Code игнорирует оба ключа в пользовательских настройках. Список там не добавляет и не удаляет встроенного стража.

Обеспечение политики с помощью собственного мода

Чтобы не допустить загрузку любого мода пользователя, вам не нужен собственный мод. Установите allowManagedModsOnly. Напишите мод политики, когда вы хотите допустить некоторые моды пользователей и отказать другим или чтобы записывать, что делают моды. Каждый раз, когда другой мод собирается загрузиться, ваш мод получает список, который печатает claude plugin validate, в событии с именем plugin.register. Мод в prependPlugins может прочитать этот список и отказать в загрузке мода. Он также может обработать любой вызов API модов по имени, чтобы записать этот вызов или отказать в нем для каждого другого мода. Имя — это метод без $., поэтому хук на fs.write видит каждый вызов $.fs.write.
В v2.1.323 или более поздней версии хуку ui.focus нужен более широкий matcher, чтобы получать вызовы $.ui.focus других модов. См. Хуки на отрисовки и элементы управления других модов.
Этот мод политики отказывает любому моду пользователя, чей собственный код вызывает $.process.run или $.process.spawn. Он также ведет журнал аудита, записывая каждый вызов инструмента и каждый файл, который мод записывает, в лог отладки. Поскольку он выполняется первым, лог записывает то, что было запрошено, перед тем как любой мод пользователя это изменит. Сохраните его как acme-guard/hooks/register.js:
acme-guard/hooks/register.js
Файл регистрирует три хука:
  • plugin.register: решает, загружается ли другой мод. Он отказывает моду пользователя, который вызывает заблокированный метод, и передает каждый другой мод дальше.
  • tool.call: записывает строку, такую как audit tool.call Bash, в лог отладки для каждого вызова инструмента и ничего не изменяет
  • fs.write: записывает строку, такую как audit fs.write by reader "/tmp/notes.md", для каждого вызова $.fs.write, который делает другой мод, и ничего не изменяет. Имя мода идет первым, а путь заключен в кавычки, поэтому путь, который выбирает мод, не может выдать себя за другое поле строки.
Хук plugin.register читает два поля события:
  • e.tier: где будет выполняться мод, один из prepend, user, append или builtin. Каждый мод, который устанавливает человек, — это user.
  • e.uses.calls: методы API модов, которые вызывает мод, каждый записан как namespace.method, например process.run, без $., который печатает claude plugin validate
Когда пользователь устанавливает мод, который вызывает $.process.run, мод не загружается, и в его логе отладки есть строка, которая заканчивается на refused by acme-guard: и вашу причину. Отказ также попадает в транскрипт в сессии, которая выполняет горячую перезагрузку каталога плагина. Чтобы заблокировать вызов без отказа всему моду, верните { deny: 'your reason' } из хука на имя этого вызова, после того как проверите, кто сделал вызов. Чтобы отправить строки аудита куда-то, кроме лога отладки, вызовите $.http.fetch из тех же хуков. Сессия может выполняться без вашего мода. Если рабочий поток, который запускает установленные моды, падает три раза, Claude Code выгружает каждый мод, который не встроен, включая ваш, пока пользователь не запустит /reload-plugins или не начнет новую сессию. А пользователь, который запускает Claude Code с --safe-mode, работает без установленных модов, включая ваш. Создание мода описывает файлы, которые нужны моду. Тестирование мода политики содержит файл теста для этого мода политики.

Отказ в загрузке модов при сбое вашей проверки

Если ваш хук plugin.register выбросит исключение или превысит лимит времени, Claude Code пропускает хук, поэтому при сбое проверка остается открытой (fail open), и мод, который она проверяла, загружается. Чтобы при сбое закрывать доступ (fail closed) и отказывать в загрузке модов пользователей, переместите проверку в именованную функцию и добавьте обработчик .catch, который возвращает отказ. Эта версия файла показывает только хук plugin.register, поэтому сохраните два хука аудита из первой версии в register:
acme-guard/hooks/register.js
С обработчиком на месте мод, который проверялся, когда проверка выбросила исключение или истекло время, не загружается, и строка отказа содержит вторую причину, как в refused by acme-guard: Acme policy check failed, so this mod was not loaded. Обработчик передает каждый мод вне уровня user в next(e), поэтому неудачная проверка не останавливает моды, которые указывает ваша организация. Обработка хука, завершившегося сбоем описывает .catch для других событий.

Следующие шаги