Перейти к основному содержанию
Claude Agent SDK предоставляет элементы управления разрешениями для управления использованием инструментов Claude. Используйте режимы разрешений и правила для определения того, что разрешено автоматически, и callback canUseTool для обработки всего остального во время выполнения.
На этой странице рассматриваются режимы разрешений и правила. Чтобы создать интерактивные потоки утверждения, где пользователи одобряют или отклоняют запросы инструментов во время выполнения, см. Обработка утверждений и ввода пользователя.

Как оцениваются разрешения

Когда Claude запрашивает инструмент, SDK проверяет разрешения в следующем порядке:
1

Hooks

Сначала запустите hooks. Hook может отклонить вызов полностью или передать его дальше. Hook, который возвращает allow, не пропускает правила deny и ask ниже; они оцениваются независимо от результата hook.
2

Правила deny

Проверьте правила deny (из disallowed_tools и settings.json). Если правило deny совпадает, инструмент блокируется, даже в режиме bypassPermissions. Записи с простым названием, такие как Bash, удаляют инструмент из контекста Claude перед началом этой оценки, поэтому на этом шаге проверяются только правила с областью действия, такие как Bash(rm *).
3

Правила ask

Проверьте правила ask из settings.json. Если правило ask совпадает, вызов передаётся вашему callback canUseTool для подтверждения, даже в режиме bypassPermissions.Инструменты, которые требуют взаимодействия с пользователем, ведут себя так же: AskUserQuestion и MCP инструменты, сервер которых устанавливает _meta["anthropic/requiresUserInteraction"], всегда передаются callback, даже когда совпадает правило allow. В режиме dontAsk оба случая отклоняются вместо этого, потому что этот режим никогда не запрашивает подтверждение. Аннотация MCP требует Claude Code v2.1.199 или более поздней версии.Инструменты claude.ai connector, которые ваша организация установила на ask, также покидают поток на этом шаге. Каждый вызов передаётся callback, даже в режиме bypassPermissions и даже когда совпадает правило allow. Callback получает причину Your organization requires approval for this tool. В режиме dontAsk вызов отклоняется вместо этого, потому что этот режим никогда не запрашивает подтверждение.
4

Режим разрешений

Примените активный режим разрешений. bypassPermissions одобряет всё, что достигает этого шага. acceptEdits одобряет операции с файлами. plan маршрутизирует инструменты file-edit и shell-write к вашему callback canUseTool независимо от правил allow, поэтому операции записи не могут быть автоматически одобрены во время планирования. Другие режимы проходят дальше.
5

Правила allow

Проверьте правила allow (из allowed_tools и settings.json). Если правило совпадает, инструмент одобрен.
6

Callback canUseTool

Если не разрешено ни одним из вышеперечисленных, вызовите ваш callback canUseTool для принятия решения. В режиме dontAsk этот шаг пропускается и инструмент отклоняется.
Диаграмма потока оценки разрешений из шести шагов, соответствующая шагам выше: запрос инструмента проходит через hooks, правила deny, правила ask, режим разрешений, правила allow и canUseTool. Hooks, правила deny и canUseTool могут маршрутизировать вниз к Blocked; обход режима разрешений, правила allow и canUseTool могут маршрутизировать вверх к Execute; правила ask маршрутизируют к canUseTool. Начиная с версии v2.1.198, если вы передаёте callback canUseTool, который эта последовательность оценки никогда не может достичь, TypeScript SDK выдаёт предупреждение процесса Node.js один раз при построении запроса. Код предупреждения — CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Две конфигурации вызывают его:
  • permissionMode: 'bypassPermissions', который автоматически одобряет каждый вызов, достигающий шага режима разрешений
  • Каждая запись allowedTools с простым названием, такая как "Read", которая автоматически одобряет весь этот инструмент перед консультацией callback
Записи со спецификатором, такие как Bash(ls *), и режим acceptEdits не вызывают его, и правила allow из файлов настроек не видны для проверки. Слушайте с помощью process.on('warning', ...) и сопоставьте код для логирования или подавления его. Чтобы контролировать каждый вызов инструмента независимо от режима и правил, используйте вместо этого hook PreToolUse. На этой странице основное внимание уделяется правилам allow и deny и режимам разрешений. Для других шагов:

Правила allow и deny

allowed_tools и disallowed_tools (TypeScript: allowedTools / disallowedTools) добавляют записи в списки правил allow и deny в потоке оценки выше. Правила allow влияют только на одобрение: инструмент, не указанный в allowed_tools, всё ещё доступен для Claude и переходит к режиму разрешений. Правила deny ведут себя по-разному в зависимости от того, называют ли они инструмент или определяют шаблон в пределах одного. Правила allow принимают глобы имён инструментов только после буквального префикса mcp__<server>__. Сегмент сервера должен быть свободен от глобов, чтобы правило называло конкретный сервер, который вы настроили: mcp__puppeteer__* соответствует каждому инструменту с сервера puppeteer, и mcp__github__get_* соответствует его инструментам get_. Неякорированная запись, такая как allowed_tools=["*"] или allowed_tools=["mcp__*"], игнорируется с предупреждением при запуске и не одобряет ничего автоматически. Правила с областью действия для Read и Edit принимают шаблон пути. Правила Edit(path) управляют всеми встроенными инструментами, которые записывают файлы, включая Write и NotebookEdit; правило Write(path) никогда не совпадает с проверками разрешений файлов. Используйте //path для абсолютного пути файловой системы: правило deny Edit(//secrets/**) блокирует записи в любом месте под /secrets на диске. С одной ведущей косой чертой Edit(/secrets/**) якорируется в источнике правила. Для правил, переданных через allowed_tools или disallowed_tools, это означает рабочий каталог сеанса, поэтому правило не блокирует /secrets на диске. См. Правила Read и Edit для четырёх форм якорей и того, как правила из файлов параметров разрешаются.
Автоматически одобренные инструменты никогда не достигают canUseTool. Вызов инструмента, одобренный на любом более раннем этапе, с помощью acceptEdits или bypassPermissions, или по правилу allow, пропускает ваш обратный вызов canUseTool, поэтому проверки разрешений, которые вы там поместили, молча обходятся для этого инструмента. AskUserQuestion, инструменты MCP, отмеченные _meta["anthropic/requiresUserInteraction"], и инструменты соединителя которые ваша организация установила на ask всё ещё достигают обратного вызова, даже когда совпадает правило allow.Охват зависит от формы записи: простое имя, такое как Read или mcp__github__get_issue, автоматически одобряет каждый вызов этого инструмента, в то время как правило с областью действия, такое как Bash(ls *), автоматически одобряет только совпадающие вызовы, и другие вызовы Bash всё ещё переходят к обратному вызову. Для проверок, которые должны выполняться при каждом вызове инструмента, используйте PreToolUse hook: hooks выполняются перед каждым другим шагом, и отказ hook применяется даже в режиме bypassPermissions.
Для заблокированного агента объедините allowedTools с permissionMode: "dontAsk". Указанные инструменты одобрены, кроме всегда запрашиваемых инструментов в предупреждении выше; всё остальное отклоняется полностью вместо запроса:
allowed_tools не ограничивает bypassPermissions. allowed_tools только предварительно одобряет указанные вами инструменты. Неуказанные инструменты не совпадают ни с одним правилом allow и переходят к режиму разрешений, где bypassPermissions их одобряет. Установка allowed_tools=["Read"] вместе с permission_mode="bypassPermissions" всё ещё одобряет каждый инструмент, включая Bash, Write и Edit. Если вам нужен bypassPermissions, но вы хотите заблокировать определённые инструменты, используйте disallowed_tools.
Вы также можете настроить правила allow, deny и ask декларативно в .claude/settings.json. Эти правила читаются, когда включен источник параметра project, что происходит для параметров query() по умолчанию. Если вы явно установите setting_sources (TypeScript: settingSources), включите "project", чтобы они применялись. См. Параметры разрешений для синтаксиса правил.

Режимы разрешений

Режимы разрешений обеспечивают глобальный контроль над использованием инструментов Claude. Вы можете установить режим разрешений при вызове query() или изменить его динамически во время сеансов потоковой передачи.

Доступные режимы

SDK поддерживает эти режимы разрешений:
Наследование подагентом: Когда родитель использует bypassPermissions, acceptEdits или auto, все подагенты наследуют этот режим и он не может быть переопределён для каждого подагента. Подагенты могут иметь различные системные подсказки и менее ограниченное поведение, чем ваш основной агент, поэтому наследование bypassPermissions предоставляет им полный автономный доступ к системе. Явные правила ask, инструменты соединителя которые ваша организация установила на ask и инструменты, требующие взаимодействия с пользователем, по-прежнему вынуждают запрос.

Установка режима разрешений

Вы можете установить режим разрешений один раз при запуске запроса или изменить его динамически во время активного сеанса.
Передайте permission_mode (Python) или permissionMode (TypeScript) при создании запроса. Этот режим применяется для всего сеанса, если не изменён динамически.

Детали режимов

Режим принятия редактирования (acceptEdits)

Автоматически одобряет операции с файлами, чтобы Claude мог редактировать код без запроса. Другие инструменты (например, команды Bash, которые не являются операциями с файловой системой) по-прежнему требуют обычных разрешений. Автоматически одобренные операции:
  • Редактирование файлов (инструменты Edit, Write)
  • Команды файловой системы: mkdir, touch, rm, rmdir, mv, cp, sed
Оба применяются только к путям внутри рабочего каталога или additionalDirectories. Пути вне этой области и записи в защищённые пути по-прежнему запрашивают разрешение. Используйте, когда: вы доверяете редактированию Claude и хотите более быстрой итерации, например во время прототипирования или при работе в изолированном каталоге.

Режим без запроса (dontAsk)

Преобразует любой запрос разрешения в отклонение. Инструменты, предварительно одобренные allowed_tools, правилами allow в settings.json или hook, работают нормально. Инструменты соединителя которые ваша организация установила на ask и инструменты, требующие взаимодействия с пользователем, отклоняются даже если правило allow совпадает. Всё остальное отклоняется без вызова canUseTool. Используйте, когда: вы хотите фиксированную, явную поверхность инструментов для автономного агента и предпочитаете жёсткое отклонение молчаливому полаганию на отсутствие canUseTool.

Режим обхода разрешений (bypassPermissions)

Автоматически одобряет все использования инструментов без запросов. Hooks всё ещё выполняются и могут блокировать операции при необходимости.
Используйте с крайней осторожностью. Claude имеет полный доступ к системе в этом режиме. Используйте только в контролируемых средах, где вы доверяете всем возможным операциям.allowed_tools не ограничивает этот режим. Каждый инструмент одобрен, а не только те, которые вы указали. Правила deny (disallowed_tools), явные правила ask и hooks оцениваются перед проверкой режима и всё ещё могут заблокировать инструмент. Инструменты соединителя которые ваша организация установила на ask и инструменты, требующие взаимодействия с пользователем, по-прежнему переходят к вашему callback canUseTool.

Режим планирования (plan)

Claude исследует кодовую базу и создаёт план без редактирования исходных файлов. Инструменты только для чтения работают как в режиме по умолчанию. Редактирование файлов никогда не одобряется автоматически в режиме планирования, даже если правило allow совпадает. Вместо этого они запрашиваются через ваш callback canUseTool. Claude может использовать AskUserQuestion для уточнения требований перед завершением плана. См. Обработка утверждений и ввода пользователя для обработки этих запросов. Используйте, когда: вы хотите, чтобы Claude предложил изменения без их выполнения, например при проверке кода или когда вам нужно одобрить изменения перед их внесением. Для других шагов в потоке оценки разрешений: