SpyBara
Go Premium

agent-sdk/permissions.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 48 additions and 46 deletions.

2026
Thu 1 23:59 Fri 9 23:02 Sat 10 23:01 Sat 17 23:57 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58 Mon 26 22:57 Tue 27 22:59 Fri 30 23:01

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

Контролируйте, как ваш агент использует инструменты, с помощью режимов разрешений, hooks и декларативных правил разрешения/запрета.

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

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

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

1. Hooks

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

Хук PreToolUse, который возвращает allow, также не может одобрить команду rm или rmdir, цель которой Claude Code распознает как критический путь, например rm -rf ~. О том, что делает такой allow в режиме планирования, см. Подтверждения хуков в режиме планирования.

2. Deny rules

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

3. Ask rules

Проверьте правила 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. Permission mode

Примените активный режим разрешений:

  • В режиме bypassPermissions Claude Code одобряет все, что достигает этого шага, кроме распознанных удалений по критическим путям, которые вместо этого передаются дальше.
  • В режиме acceptEdits Claude Code одобряет операции с файлами, перечисленные в разделе Accept edits mode.
  • В режиме plan Claude Code отправляет инструменты редактирования файлов и записи в shell в ваш callback canUseTool независимо от правил allow, поэтому операции записи не могут быть автоматически одобрены при планировании.
  • В других режимах запрос передается дальше.

5. Allow rules

Проверьте правила allow (из allowed_tools и settings.json). Если правило совпадает, инструмент одобряется. Вызов, который инструмент одобряет самостоятельно, также разрешается на этом шаге без необходимости в правиле: например, чтение файла в ваших рабочих каталогах или команда Bash только для чтения.

Распознанные удаления по критическим путям не одобряются правилом allow. Достигают ли они затем вашего callback, зависит от режима разрешений: например, в сессии Agent SDK в режиме auto Claude Code по умолчанию отклоняет их, не вызывая его. Таблица режимов для критических путей перечисляет, что каждый режим с ними делает.

Правило allow не одобряет чтение из сетевого пути.

6. canUseTool callback

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

В TypeScript SDK, если вы установите permissionPrompts: 'none', ваш callback не вызывается на этом шаге. Hook PermissionRequest все еще получает возможность принять решение, и если он этого не делает, Claude Code отклоняет вызов. Опция требует Claude Code v2.1.259 или позже.

Диаграмма шестиэтапного потока оценки разрешений, соответствующая шагам выше: запрос инструмента проходит через hooks, правила deny, правила ask, режим разрешений, правила allow и canUseTool. Hooks, правила deny и canUseTool могут маршрутизировать вниз к Blocked; обход режима разрешений, правила allow и canUseTool могут маршрутизировать вверх к Execute; правила ask маршрутизируют к canUseTool.

Если вы передаете callback canUseTool в конфигурацию, где TypeScript SDK ожидает, что порядок оценки автоматически одобрит вызовы перед консультацией callback, SDK выдает предупреждение процесса Node.js один раз при построении запроса. Код предупреждения — CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Две конфигурации вызывают его:

Записи со спецификатором, такие как Bash(ls *), и режим acceptEdits не вызывают его, и правила allow из файлов настроек не видны для проверки.

Слушайте с помощью process.on('warning', ...) и сопоставьте код для логирования или подавления его. Чтобы контролировать каждый вызов инструмента независимо от режима и правил, используйте вместо этого hook PreToolUse.

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

  • Hooks: запустите пользовательский код для разрешения, отклонения или изменения запросов инструментов. См. Control execution with hooks.
  • canUseTool callback: запросите у пользователей одобрение во время выполнения, когда ни один более ранний шаг не разрешит вызов. См. Handle approvals and user input.

Правила разрешения и запрета

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

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

Правила разрешения принимают глобы имен инструментов только после буквального префикса mcp__<server>__. Сегмент сервера должен быть свободен от глобов, чтобы правило называло конкретный сервер, который вы настроили: mcp__puppeteer__* соответствует каждому инструменту с сервера puppeteer, а mcp__github__get_* соответствует его инструментам get_. Неякорированная запись, такая как allowed_tools=["*"] или allowed_tools=["mcp__*"], игнорируется и не одобряет ничего автоматически.

Правила с областью действия для Read и Edit принимают шаблон пути. Правила Edit(path) управляют всеми встроенными инструментами, которые записывают файлы, включая Write и NotebookEdit; правило Write(path) никогда не совпадает с проверками разрешений файлов.

Используйте //path для абсолютного пути файловой системы: правило запрета Edit(//secrets/**) блокирует записи в любом месте под /secrets на диске. С одной ведущей косой чертой Edit(/secrets/**) якорируется в источнике правила. Для правил, переданных через allowed_tools или disallowed_tools, это означает рабочий каталог сеанса, поэтому правило не блокирует /secrets на диске. См. Правила Read и Edit для четырех форм якорей и того, как правила из файлов параметров разрешаются.

[!WARNING]

Автоматически одобренные инструменты никогда не достигают canUseTool. Вызов инструмента, одобренный на любом более раннем этапе, по acceptEdits или bypassPermissions, или по правилу разрешения, пропускает ваш обратный вызов canUseTool, поэтому проверки разрешений, которые вы там поместили, молча обходятся для этого инструмента.

Ни одно правило разрешения не одобряет автоматически AskUserQuestion, инструменты MCP, отмеченные _meta["anthropic/requiresUserInteraction"], инструменты коннекторов, для которых ваша организация установила ask, или распознанные удаления rm и rmdir по критическим путям. В режиме dontAsk Claude Code отклоняет эти вызовы без вызова обратного вызова. В других режимах первые три достигают обратного вызова. В таблице режимов для критических путей указано, что каждый режим делает с удалением по критическому пути. Проверка, которая распознает такие удаления, может пропускать некоторые команды.

Охват зависит от формы записи: простое имя, такое как Read или mcp__github__get_issue, автоматически одобряет каждый вызов этого инструмента, кроме указанных исключений и чтения из сетевых путей, в то время как правило с областью действия, такое как Bash(npm test *), автоматически одобряет только совпадающие вызовы, и другие вызовы Bash, требующие одобрения, по-прежнему переходят в обратный вызов. Для проверок, которые должны выполняться при каждом вызове инструмента, используйте хук PreToolUse: хуки выполняются перед каждым другим шагом, и отказ хука применяется даже в режиме bypassPermissions.

Для заблокированного агента объедините allowedTools с permissionMode: "dontAsk":

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk"
};

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

Вызовы, которые не требуют одобрения в режиме default, выполняются независимо от того, указаны ли они в списке. К ним относятся команды Bash только для чтения, инструменты, такие как Agent, которые не спрашивают перед запуском, и чтение файлов в ваших рабочих каталогах. Чтобы полностью удалить инструмент из запроса, добавьте его простое имя в disallowedTools.

[!WARNING]

allowed_tools не ограничивает bypassPermissions. allowed_tools предварительно одобряет инструменты, которые вы указали. Другие неуказанные инструменты не совпадают ни с одним правилом разрешения и переходят в режим разрешений, где bypassPermissions их одобряет. Установка allowed_tools=["Read"] наряду с permission_mode="bypassPermissions" по-прежнему одобряет каждый инструмент, включая Bash, Write и Edit. Если вам нужен bypassPermissions, но вы хотите заблокировать определенные инструменты, используйте disallowed_tools.

Вы также можете настроить правила разрешения, запрета и запроса декларативно в .claude/settings.json. Эти правила читаются, когда источник параметра project включен, что он есть для параметров query() по умолчанию. Если вы явно установите setting_sources (TypeScript: settingSources), включите "project", чтобы они применялись. См. Параметры разрешений для синтаксиса правил.

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

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

В Claude Code v2.1.302 или более поздней версии ваше приложение запускается в режиме default, если вы не установите режим разрешений или приложение не получит его из permissions.defaultMode в своих файлах настроек. В режиме default Claude Code отклоняет любой вызов инструмента, требующий подтверждения, если вы не подтвердите его с помощью правила разрешения, хука, обратного вызова canUseTool или инструмента запроса разрешений. Если вызовы инструментов отклоняются, см. Вызовы инструментов отклоняются в claude -p и запусках Agent SDK.

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

SDK поддерживает эти режимы разрешений:

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

[!WARNING]

Наследование субагентом: Если ваша основная сессия находится в режиме планирования, субагент, в AgentDefinition которого задано permissionMode: "acceptEdits", всё равно выполняется в режиме планирования. Вызовы Edit и Write этого субагента для ваших исходных файлов по-прежнему поступают в ваш обратный вызов canUseTool. Режим планирования действует и для определённых вами субагентов, чтобы передача работы одному из них не позволяла обойти предварительную проверку плана.

Субагент наследует plan, acceptEdits, auto или bypassPermissions от основной сессии, а при основной сессии в режиме default или dontAsk он выполняется в заданном вами режиме. Даже в этом случае Claude Code никогда не применяет значение "bypassPermissions", а значение "auto" применяет только тогда, когда авторежим доступен этому субагенту. Исключение bypassPermissions требует Claude Code v2.1.267 или более поздней версии.

Подагенты могут иметь различные системные подсказки и менее ограниченное поведение, чем ваш основной агент, поэтому наследование 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",  # Set the mode here
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  for await (const message of query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Set the mode here
    }
  })) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

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",  # Start in default mode
        )
    ) as client:
        await client.query("Help me refactor this code")

        # Change mode dynamically mid-session
        await client.set_permission_mode("acceptEdits")

        # Process messages with the new permission mode
        async for message in client.receive_response():
            if hasattr(message, "result"):
                print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  const q = query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Start in default mode
    }
  });

  // Change mode dynamically mid-session
  await q.setPermissionMode("acceptEdits");

  // Process messages with the new permission mode
  for await (const message of q) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

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

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

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

Автоматически одобренные операции:

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

Оба применяются только к путям внутри рабочего каталога или additionalDirectories. В режиме acceptEdits Claude Code не одобряет запрос автоматически, когда Claude:

  • Работает с путем вне этой области
  • Записывает в защищенный путь
  • Удаляет с помощью rm или rmdir путь, который Claude Code распознает как критический путь

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

Режим не спрашивать (dontAsk)

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

Инструменты коннектора, установленные вашей организацией на ask, инструменты, требующие взаимодействия с пользователем, чтение из сетевых путей и распознанные удаления критических путей отклоняются, даже когда правило разрешения совпадает. Разрешение хука PreToolUse также не снимает запрет ни на распознанное удаление критического пути, ни на чтение из сетевого пути. Проверка, которая распознает такие удаления, может пропустить некоторые команды.

Используйте когда: вы хотите фиксированную, явную поверхность инструментов для headless агента и предпочитаете жесткое отклонение молчаливому полаганию на отсутствие canUseTool.

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

Автоматически одобряет использование инструментов без запроса, за исключением случаев, перечисленных в предупреждении ниже. Hooks по-прежнему выполняются и могут блокировать операции при необходимости. На Linux и macOS Claude Code отказывается запускаться в этом режиме от имени root или под sudo вне признанной песочницы, и запрос завершается ошибкой перед первым ходом.

[!WARNING]

Используйте с крайней осторожностью. Claude имеет полный доступ к системе в этом режиме. Используйте только в контролируемых средах, где вы доверяете всем возможным операциям.

allowed_tools не ограничивает этот режим. Каждый инструмент одобрен, а не только те, которые вы указали. Эти элементы управления по-прежнему применяются:

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

Claude исследует кодовую базу и создает план без редактирования исходных файлов. Инструменты только для чтения выполняются так же, как в режиме разрешений default.

Редактирование файлов никогда не одобряется автоматически в режиме планирования, даже когда правило разрешения совпадает или хук PreToolUse возвращает allow. Вместо этого они запрашиваются через ваш обратный вызов canUseTool. В Claude Code v2.1.212 или более поздней версии команды оболочки, которые изменяют файлы, такие как touch и rm, достигают вашего обратного вызова canUseTool таким же образом.

В TypeScript SDK, если вы установите allowDangerouslySkipPermissions: true вместе с permissionMode: 'plan', редактирование файлов и команды оболочки, которые изменяют файлы, по-прежнему достигают вашего обратного вызова canUseTool. Опция позволяет вам позже переключиться на bypassPermissions с помощью setPermissionMode().

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

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

Авторежим (auto)

Модель-классификатор проверяет действия, такие как команды оболочки и сетевые запросы, перед их выполнением и разрешает или блокирует каждое проверяемое действие. О моделях и провайдерах, которые требуются для авторежима, и о порядке, в котором он оценивает действия, см. Устранение запросов разрешений с помощью авторежима.

Если вы переключаете сессию, находящуюся в авторежиме, на модель, которую авторежим не поддерживает, с помощью set_model(), setModel() или applyFlagSettings(), сессия переходит в режим default:

  • Что вы увидите: сообщение system с подтипом status и permissionMode, установленным в "default", которое TypeScript SDK типизирует как SDKStatusMessage. С этого момента вызовы, требующие подтверждения и не соответствующие никакому правилу разрешения, достигают вашего обратного вызова canUseTool.
  • Чтобы вернуться в авторежим: переключитесь на поддерживаемую модель, затем вызовите set_permission_mode("auto") или setPermissionMode("auto"). Если вы переключите модель обратно без этого вызова, сессия останется в режиме default. Пока активна неподдерживаемая модель, вызов завершается ошибкой Cannot set permission mode to auto: auto mode unavailable for this model.

Переход в режим default после вызова set_model(), setModel() или applyFlagSettings() требует Claude Code v2.1.299 или более поздней версии.

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

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