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

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

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

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

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

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

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

Правила 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__*"], игнорируется с предупреждением при запуске и не одобряет ничего автоматически.

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

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

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

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

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

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

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

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

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

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())

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();

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())

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, работают нормально. Всё остальное отклоняется без вызова canUseTool.

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

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

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

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

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

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

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

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

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