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

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

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

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

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

Если вы передаете callback canUseTool в конфигурацию, где TypeScript SDK ожидает, что порядок оценки автоматически одобрит вызовы перед консультацией callback, 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 и режимах разрешений. Для других шагов:

• 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, и вызов к нему, требующий одобрения, переходит в режим разрешений. Правила запрета ведут себя по-разному в зависимости от того, называют ли они инструмент или определяют шаблон в пределах одного.

Правила разрешения принимают глобы имен инструментов только после буквального префикса 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 для четырех форм якорей и того, как правила из файлов параметров разрешаются.

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

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

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

Вы также можете настроить правила разрешения, запрета и запроса декларативно в .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",  # 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();

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 и хотите более быструю итерацию, например во время прототипирования или при работе в изолированном каталоге.

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

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

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

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

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

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

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

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

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

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

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

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

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

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