> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Настройка разрешений
> Контролируйте использование инструментов вашим агентом с помощью режимов разрешений, hooks и декларативных правил allow/deny.
Claude Agent SDK предоставляет элементы управления разрешениями для управления использованием инструментов Claude. Используйте режимы разрешений и правила для определения того, что разрешено автоматически, и callback [`canUseTool`](/ru/agent-sdk/user-input) для обработки всего остального во время выполнения.
На этой странице рассматриваются режимы разрешений и правила. Чтобы создать интерактивные потоки утверждения, где пользователи одобряют или отклоняют запросы инструментов во время выполнения, см. [Обработка утверждений и ввода пользователя](/ru/agent-sdk/user-input).
Как оцениваются разрешения
Когда Claude запрашивает инструмент, SDK проверяет разрешения в следующем порядке:
Сначала запустите [hooks](/ru/agent-sdk/hooks). Hook может отклонить вызов полностью или передать его дальше. Hook, который возвращает `allow`, не пропускает правила deny и ask ниже; они оцениваются независимо от результата hook.
Проверьте правила `deny` (из `disallowed_tools` и [settings.json](/ru/settings#permission-settings)). Если правило deny совпадает, инструмент блокируется, даже в режиме `bypassPermissions`. Записи с простым названием, такие как `Bash`, удаляют инструмент из контекста Claude перед началом этой оценки, поэтому на этом шаге проверяются только правила с областью действия, такие как `Bash(rm *)`.
Проверьте правила `ask` из [settings.json](/ru/settings#permission-settings). Если правило ask совпадает, вызов передаётся вашему callback [`canUseTool`](/ru/agent-sdk/user-input) для подтверждения, даже в режиме `bypassPermissions`.
Инструменты, которые требуют взаимодействия с пользователем, ведут себя так же: `AskUserQuestion` и MCP инструменты, сервер которых устанавливает [`_meta["anthropic/requiresUserInteraction"]`](/ru/mcp#require-approval-for-a-specific-tool), всегда передаются callback, даже когда совпадает правило allow. В режиме `dontAsk` оба случая отклоняются вместо этого, потому что этот режим никогда не запрашивает подтверждение. {/* min-version: 2.1.199 */}Аннотация MCP требует Claude Code v2.1.199 или более поздней версии.
Инструменты [claude.ai connector](/ru/mcp#organization-controls-on-connector-tools), которые ваша организация установила на `ask`, также покидают поток на этом шаге. Каждый вызов передаётся callback, даже в режиме `bypassPermissions` и даже когда совпадает правило allow. Callback получает причину `Your organization requires approval for this tool`. В режиме `dontAsk` вызов отклоняется вместо этого, потому что этот режим никогда не запрашивает подтверждение.
Примените активный [режим разрешений](#permission-modes). `bypassPermissions` одобряет всё, что достигает этого шага. `acceptEdits` одобряет операции с файлами. `plan` маршрутизирует инструменты file-edit и shell-write к вашему callback `canUseTool` независимо от правил allow, поэтому операции записи не могут быть автоматически одобрены во время планирования. Другие режимы проходят дальше.
Проверьте правила `allow` (из `allowed_tools` и settings.json). Если правило совпадает, инструмент одобрен.
Если не разрешено ни одним из вышеперечисленных, вызовите ваш callback [`canUseTool`](/ru/agent-sdk/user-input) для принятия решения. В режиме `dontAsk` этот шаг пропускается и инструмент отклоняется.
Начиная с версии 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`](/ru/agent-sdk/hooks).
На этой странице основное внимание уделяется **правилам allow и deny** и **режимам разрешений**. Для других шагов:
* **Hooks:** запустите пользовательский код для разрешения, отклонения или изменения запросов инструментов. См. [Управление выполнением с помощью hooks](/ru/agent-sdk/hooks).
* **Callback canUseTool:** запросите у пользователей утверждение во время выполнения, когда ни один из предыдущих шагов не разрешит вызов. См. [Обработка утверждений и ввода пользователя](/ru/agent-sdk/user-input).
Правила 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` переходят к режиму разрешений. |
| `disallowed_tools=["*"]` | Каждое определение инструмента удаляется из запроса. Глобы имён инструментов поддерживаются в правилах deny: `"*"` соответствует каждому инструменту и `"mcp__*"` соответствует каждому инструменту MCP на всех серверах. |
Правила allow принимают глобы имён инструментов только после буквального префикса `mcp____`. Сегмент сервера должен быть свободен от глобов, чтобы правило называло конкретный сервер, который вы настроили: `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](/ru/permissions#read-and-edit) для четырёх форм якорей и того, как правила из файлов параметров разрешаются.
**Автоматически одобренные инструменты никогда не достигают `canUseTool`.** Вызов инструмента, одобренный на любом более раннем этапе, с помощью `acceptEdits` или `bypassPermissions`, или по правилу allow, пропускает ваш обратный вызов `canUseTool`, поэтому проверки разрешений, которые вы там поместили, молча обходятся для этого инструмента. `AskUserQuestion`, инструменты MCP, отмеченные [`_meta["anthropic/requiresUserInteraction"]`](/ru/mcp#require-approval-for-a-specific-tool), и инструменты соединителя [которые ваша организация установила на `ask`](/ru/mcp#organization-controls-on-connector-tools) всё ещё достигают обратного вызова, даже когда совпадает правило allow.
Охват зависит от формы записи: простое имя, такое как `Read` или `mcp__github__get_issue`, автоматически одобряет каждый вызов этого инструмента, в то время как правило с областью действия, такое как `Bash(ls *)`, автоматически одобряет только совпадающие вызовы, и другие вызовы `Bash` всё ещё переходят к обратному вызову. Для проверок, которые должны выполняться при каждом вызове инструмента, используйте [`PreToolUse` hook](/ru/agent-sdk/hooks): hooks выполняются перед каждым другим шагом, и отказ hook применяется даже в режиме `bypassPermissions`.
Для заблокированного агента объедините `allowedTools` с `permissionMode: "dontAsk"`. Указанные инструменты одобрены, кроме всегда запрашиваемых инструментов в предупреждении выше; всё остальное отклоняется полностью вместо запроса:
```typescript theme={null}
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"`, чтобы они применялись. См. [Параметры разрешений](/ru/settings#permission-settings) для синтаксиса правил.
Режимы разрешений
Режимы разрешений обеспечивают глобальный контроль над использованием инструментов Claude. Вы можете установить режим разрешений при вызове `query()` или изменить его динамически во время сеансов потоковой передачи.
Доступные режимы
SDK поддерживает эти режимы разрешений:
| Режим | Описание | Поведение инструмента |
| :------------------ | :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | Стандартное поведение разрешений | Без автоматических одобрений; несовпадающие инструменты запускают ваш callback `canUseTool` |
| `dontAsk` | Отклонение вместо запроса | Всё, что не предварительно одобрено `allowed_tools` или правилами, отклоняется; инструменты соединителя [которые ваша организация установила на `ask`](/ru/mcp#organization-controls-on-connector-tools) и инструменты, требующие взаимодействия с пользователем, отклоняются даже если вы их предварительно одобрили. `canUseTool` никогда не вызывается |
| `acceptEdits` | Автоматическое принятие редактирования файлов | Редактирование файлов и [операции с файловой системой](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv` и т. д.) автоматически одобрены |
| `bypassPermissions` | Обход всех проверок разрешений | Инструменты работают без запросов разрешений, кроме инструментов, совпадающих с явным правилом [`ask`](#how-permissions-are-evaluated), инструментов соединителя [которые ваша организация установила на `ask`](/ru/mcp#organization-controls-on-connector-tools) и инструментов, требующих взаимодействия с пользователем (используйте с осторожностью) |
| `plan` | Режим планирования | Claude исследует и планирует без редактирования исходных файлов; редактирование файлов никогда не одобряется автоматически и запрашивается через ваш callback `canUseTool` |
| `auto` | Одобрения, классифицированные моделью | Классификатор модели одобряет или отклоняет каждый вызов инструмента. См. [Режим Auto](/ru/permission-modes#eliminate-prompts-with-auto-mode) для доступности |
**Наследование подагентом:** Когда родитель использует `bypassPermissions`, `acceptEdits` или `auto`, все подагенты наследуют этот режим и он не может быть переопределён для каждого подагента. Подагенты могут иметь различные системные подсказки и менее ограниченное поведение, чем ваш основной агент, поэтому наследование `bypassPermissions` предоставляет им полный автономный доступ к системе. Явные правила [`ask`](#how-permissions-are-evaluated), инструменты соединителя [которые ваша организация установила на `ask`](/ru/mcp#organization-controls-on-connector-tools) и инструменты, требующие взаимодействия с пользователем, по-прежнему вынуждают запрос.
Установка режима разрешений
Вы можете установить режим разрешений один раз при запуске запроса или изменить его динамически во время активного сеанса.
Передайте `permission_mode` (Python) или `permissionMode` (TypeScript) при создании запроса. Этот режим применяется для всего сеанса, если не изменён динамически.
```python Python theme={null}
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())
```
```typescript TypeScript theme={null}
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" // Установите режим здесь
}
})) {
if ("result" in message) {
console.log(message.result);
}
}
}
main();
```
Вызовите `set_permission_mode()` (Python) или `setPermissionMode()` (TypeScript) для изменения режима в середине сеанса. Новый режим вступает в силу немедленно для всех последующих запросов инструментов. Это позволяет вам начать с ограничительного режима и ослабить разрешения по мере развития доверия, например переключиться на `acceptEdits` после проверки первоначального подхода Claude.
```python Python theme={null}
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())
```
```typescript TypeScript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";
async function main() {
const q = query({
prompt: "Help me refactor this code",
options: {
permissionMode: "default" // Начните в режиме по умолчанию
}
});
// Измените режим динамически в середине сеанса
await q.setPermissionMode("acceptEdits");
// Обработайте сообщения с новым режимом разрешений
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`. Пути вне этой области и записи в защищённые пути по-прежнему запрашивают разрешение.
**Используйте, когда:** вы доверяете редактированию Claude и хотите более быстрой итерации, например во время прототипирования или при работе в изолированном каталоге.
Режим без запроса (`dontAsk`)
Преобразует любой запрос разрешения в отклонение. Инструменты, предварительно одобренные `allowed_tools`, правилами allow в `settings.json` или hook, работают нормально. Инструменты соединителя [которые ваша организация установила на `ask`](/ru/mcp#organization-controls-on-connector-tools) и инструменты, требующие взаимодействия с пользователем, отклоняются даже если правило allow совпадает. Всё остальное отклоняется без вызова `canUseTool`.
**Используйте, когда:** вы хотите фиксированную, явную поверхность инструментов для автономного агента и предпочитаете жёсткое отклонение молчаливому полаганию на отсутствие `canUseTool`.
Режим обхода разрешений (`bypassPermissions`)
Автоматически одобряет все использования инструментов без запросов. Hooks всё ещё выполняются и могут блокировать операции при необходимости.
Используйте с крайней осторожностью. Claude имеет полный доступ к системе в этом режиме. Используйте только в контролируемых средах, где вы доверяете всем возможным операциям.
`allowed_tools` не ограничивает этот режим. Каждый инструмент одобрен, а не только те, которые вы указали. Правила deny (`disallowed_tools`), явные правила `ask` и hooks оцениваются перед проверкой режима и всё ещё могут заблокировать инструмент. Инструменты соединителя [которые ваша организация установила на `ask`](/ru/mcp#organization-controls-on-connector-tools) и инструменты, требующие взаимодействия с пользователем, по-прежнему переходят к вашему callback `canUseTool`.
Режим планирования (`plan`)
Claude исследует кодовую базу и создаёт план без редактирования исходных файлов. Инструменты только для чтения работают как в режиме по умолчанию. Редактирование файлов никогда не одобряется автоматически в режиме планирования, даже если правило allow совпадает. Вместо этого они запрашиваются через ваш callback `canUseTool`. Claude может использовать `AskUserQuestion` для уточнения требований перед завершением плана. См. [Обработка утверждений и ввода пользователя](/ru/agent-sdk/user-input#handle-clarifying-questions) для обработки этих запросов.
**Используйте, когда:** вы хотите, чтобы Claude предложил изменения без их выполнения, например при проверке кода или когда вам нужно одобрить изменения перед их внесением.
Для других шагов в потоке оценки разрешений:
* [Обработка утверждений и ввода пользователя](/ru/agent-sdk/user-input): интерактивные запросы утверждения и уточняющие вопросы
* [Руководство по hooks](/ru/agent-sdk/hooks): запуск пользовательского кода в ключевых точках жизненного цикла агента
* [Правила разрешений](/ru/settings#permission-settings): декларативные правила allow/deny в `settings.json`