Настройка разрешений

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

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

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

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

Hooks

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

Правила deny

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

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

Примените активный режим разрешений. bypassPermissions одобряет всё, что достигает этого шага. acceptEdits одобряет операции с файлами. Другие режимы проходят дальше.

Правила allow

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

Callback canUseTool

Если не разрешено ни одним из вышеперечисленных, вызовите ваш callback canUseTool для принятия решения. В режиме dontAsk этот шаг пропускается и инструмент отклоняется.

На этой странице основное внимание уделяется правилам allow и deny и режимам разрешений. Для других шагов:

Hooks: запустите пользовательский код для разрешения, отклонения или изменения запросов инструментов. См. Управление выполнением с помощью hooks.
Callback canUseTool: запросите у пользователей утверждение во время выполнения. См. Обработка утверждений и ввода пользователя.

Правила allow и deny

allowed_tools и disallowed_tools (TypeScript: allowedTools / disallowedTools) добавляют записи в списки правил allow и deny в потоке оценки выше. Правила allow влияют только на одобрение: инструмент, не указанный в allowed_tools, всё ещё доступен для Claude и переходит к режиму разрешений. Правила deny ведут себя по-разному в зависимости от того, называют ли они инструмент или определяют шаблон в пределах одного.

Опция	Эффект
`allowed_tools=["Read", "Grep"]`	`Read` и `Grep` автоматически одобрены. Инструменты, не указанные здесь, всё ещё существуют и переходят к режиму разрешений и `canUseTool`.
`disallowed_tools=["Bash"]`	Определение инструмента `Bash` удаляется из запроса. Claude не видит инструмент и не может попытаться его использовать.
`disallowed_tools=["Bash(rm *)"]`	`Bash` остаётся доступным. Вызовы, соответствующие `rm *`, отклоняются в каждом режиме разрешений, включая `bypassPermissions`. Другие вызовы `Bash` переходят к режиму разрешений.

Для заблокированного агента объедините allowedTools с permissionMode: "dontAsk". Указанные инструменты одобрены; всё остальное отклоняется полностью вместо запроса:

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  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 поддерживает эти режимы разрешений:

Режим	Описание	Поведение инструмента
`default`	Стандартное поведение разрешений	Без автоматических одобрений; несовпадающие инструменты запускают ваш callback `canUseTool`
`dontAsk`	Отклонение вместо запроса	Всё, что не предварительно одобрено `allowed_tools` или правилами, отклоняется; `canUseTool` никогда не вызывается
`acceptEdits`	Автоматическое принятие редактирования файлов	Редактирование файлов и операции с файловой системой (`mkdir`, `rm`, `mv` и т. д.) автоматически одобрены
`bypassPermissions`	Обход всех проверок разрешений	Все инструменты работают без запросов разрешений (используйте с осторожностью)
`plan`	Режим планирования	Инструменты только для чтения работают; Claude анализирует и планирует без редактирования исходных файлов
`auto` (только TypeScript)	Одобрения, классифицированные моделью	Классификатор модели одобряет или отклоняет каждый вызов инструмента. См. Режим Auto для доступности

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

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

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

При запросе
Во время потоковой передачи

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

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Help me refactor this code",
        options=ClaudeAgentOptions(
            permission_mode="default",  # Установите режим здесь
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

Вызовите set_permission_mode() (Python) или setPermissionMode() (TypeScript) для изменения режима в середине сеанса. Новый режим вступает в силу немедленно для всех последующих запросов инструментов. Это позволяет вам начать с ограничительного режима и ослабить разрешения по мере развития доверия, например переключиться на acceptEdits после проверки первоначального подхода Claude.

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions


async def main():
    async with ClaudeSDKClient(
        options=ClaudeAgentOptions(
            permission_mode="default",  # Начните в режиме по умолчанию
        )
    ) as client:
        await client.query("Help me refactor this code")

        # Измените режим динамически в середине сеанса
        await client.set_permission_mode("acceptEdits")

        # Обработайте сообщения с новым режимом разрешений
        async for message in client.receive_response():
            if hasattr(message, "result"):
                print(message.result)


asyncio.run(main())

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

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

Автоматически одобряет операции с файлами, чтобы Claude мог редактировать код без запроса. Другие инструменты (например, команды Bash, которые не являются операциями с файловой системой) по-прежнему требуют обычных разрешений. Автоматически одобренные операции:

Редактирование файлов (инструменты Edit, Write)
Команды файловой системы: mkdir, touch, rm, rmdir, mv, cp, sed

Оба применяются только к путям внутри рабочего каталога или additionalDirectories. Пути вне этой области и записи в защищённые пути по-прежнему запрашивают разрешение. Используйте, когда: вы доверяете редактированию Claude и хотите более быстрой итерации, например во время прототипирования или при работе в изолированном каталоге.

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

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

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

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

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

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

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

Связанные ресурсы

Для других шагов в потоке оценки разрешений:

Обработка утверждений и ввода пользователя: интерактивные запросы утверждения и уточняющие вопросы
Руководство по hooks: запуск пользовательского кода в ключевых точках жизненного цикла агента
Правила разрешений: декларативные правила allow/deny в settings.json

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

​Правила allow и deny

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

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

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

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

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

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

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

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

​Связанные ресурсы

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

Правила allow и deny

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

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

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

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

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

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

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

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

Связанные ресурсы