Разрешения SDK

Claude Agent SDK предоставляет мощные элементы управления разрешениями, которые позволяют вам управлять тем, как Claude использует инструменты в вашем приложении.

Это руководство охватывает, как реализовать системы разрешений, используя обратный вызов canUseTool, хуки и правила разрешений settings.json. Для полной документации API см. справочник TypeScript SDK.

Обзор

Claude Agent SDK предоставляет четыре дополняющих способа контроля использования инструментов:

1. Режимы разрешений - Глобальные настройки поведения разрешений, которые влияют на все инструменты
2. обратный вызов canUseTool - Обработчик разрешений времени выполнения для случаев, не покрытых другими правилами
3. Хуки - Детальный контроль над каждым выполнением инструмента с пользовательской логикой
4. Правила разрешений (settings.json) - Декларативные правила разрешения/запрета с интегрированным парсингом bash команд

Случаи использования для каждого подхода:

• Режимы разрешений - Установка общего поведения разрешений (планирование, автоматическое принятие правок, обход проверок)
• canUseTool - Динамическое одобрение для непокрытых случаев, запрашивает разрешение у пользователя
• Хуки - Программный контроль над всеми выполнениями инструментов
• Правила разрешений - Статические политики с интеллектуальным парсингом bash команд

Диаграмма потока разрешений

Порядок обработки: PreToolUse Hook → Правила запрета → Правила разрешения → Правила запроса → Проверка режима разрешений → обратный вызов canUseTool → PostToolUse Hook

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

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

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

SDK поддерживает четыре режима разрешений, каждый с разным поведением:

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

Вы можете установить режим разрешений двумя способами:

1. Начальная конфигурация

Установите режим при создании запроса:

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

const result = await query({
  prompt: "Помоги мне рефакторить этот код",
  options: {
    permissionMode: 'default'  // Стандартный режим разрешений
  }
});

2. Динамические изменения режима (только потоковая передача)

Измените режим во время потоковой сессии:

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

// Создайте асинхронный генератор для потокового ввода
async function* streamInput() {
  yield { 
    type: 'user',
    message: { 
      role: 'user', 
      content: "Давайте начнем с разрешениями по умолчанию" 
    }
  };
  
  // Позже в разговоре...
  yield {
    type: 'user',
    message: {
      role: 'user',
      content: "Теперь давайте ускорим разработку"
    }
  };
}

const q = query({
  prompt: streamInput(),
  options: {
    permissionMode: 'default'  // Начать в режиме по умолчанию
  }
});

// Изменить режим динамически
await q.setPermissionMode('acceptEdits');

// Обработать сообщения
for await (const message of q) {
  console.log(message);
}

Поведения, специфичные для режимов

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

В режиме принятия правок:

• Все правки файлов автоматически одобряются
• Операции файловой системы (mkdir, touch, rm и т.д.) автоматически одобряются
• Другие инструменты все еще требуют обычных разрешений
• Ускоряет разработку, когда вы доверяете правкам Claude
• Полезно для быстрого прототипирования и итераций

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

• Правки файлов (инструменты Edit, Write)
• Bash-команды файловой системы (mkdir, touch, rm, mv, cp)
• Создание и удаление файлов

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

В режиме обхода разрешений:

• ВСЕ использования инструментов автоматически одобряются
• Не появляются запросы разрешений
• Хуки все еще выполняются (все еще могут блокировать операции)
• Используйте с крайней осторожностью - Claude имеет полный доступ к системе
• Рекомендуется только для контролируемых сред

Приоритет режима в потоке разрешений

Режимы разрешений оцениваются в определенной точке потока разрешений:

1. Хуки выполняются первыми - Могут разрешить, запретить, спросить или продолжить
2. Правила запрета проверяются - Блокируют инструменты независимо от режима
3. Правила разрешения проверяются - Разрешают инструменты при совпадении
4. Правила запроса проверяются - Запрашивают разрешение при совпадении
5. Режим разрешений оценивается:
   • Режим bypassPermissions - Если активен, разрешает все оставшиеся инструменты
   • Другие режимы - Передают обратному вызову canUseTool
6. Обратный вызов canUseTool - Обрабатывает оставшиеся случаи

Это означает:

• Хуки всегда могут контролировать использование инструментов, даже в режиме bypassPermissions
• Явные правила запрета переопределяют все режимы разрешений
• Правила запроса оцениваются перед режимами разрешений
• Режим bypassPermissions переопределяет обратный вызов canUseTool для несовпавших инструментов

Лучшие практики

1. Используйте режим по умолчанию для контролируемого выполнения с обычными проверками разрешений
2. Используйте режим acceptEdits при работе с изолированными файлами или каталогами
3. Избегайте bypassPermissions в продакшене или на системах с чувствительными данными
4. Комбинируйте режимы с хуками для детального контроля
5. Переключайте режимы динамически в зависимости от прогресса задачи и уверенности

Пример прогрессии режимов:

// Начать в режиме по умолчанию для контролируемого выполнения
permissionMode: 'default'

// Переключиться на acceptEdits для быстрой итерации
await q.setPermissionMode('acceptEdits')

canUseTool

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

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

Вот полный пример, показывающий, как реализовать интерактивное одобрение инструментов:

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

async function promptForToolApproval(toolName: string, input: any) {
  console.log("\n🔧 Запрос инструмента:");
  console.log(`   Инструмент: ${toolName}`);
  
  // Отобразить параметры инструмента
  if (input && Object.keys(input).length > 0) {
    console.log("   Параметры:");
    for (const [key, value] of Object.entries(input)) {
      let displayValue = value;
      if (typeof value === 'string' && value.length > 100) {
        displayValue = value.substring(0, 100) + "...";
      } else if (typeof value === 'object') {
        displayValue = JSON.stringify(value, null, 2);
      }
      console.log(`     ${key}: ${displayValue}`);
    }
  }
  
  // Получить одобрение пользователя (замените на вашу логику UI)
  const approved = await getUserApproval();
  
  if (approved) {
    console.log("   ✅ Одобрено\n");
    return {
      behavior: "allow",
      updatedInput: input
    };
  } else {
    console.log("   ❌ Отклонено\n");
    return {
      behavior: "deny",
      message: "Пользователь отклонил разрешение для этого инструмента"
    };
  }
}

// Использовать обратный вызов разрешений
const result = await query({
  prompt: "Помоги мне проанализировать эту кодовую базу",
  options: {
    canUseTool: async (toolName, input) => {
      return promptForToolApproval(toolName, input);
    }
  }
});

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

• Руководство по хукам - Узнайте, как реализовать хуки для детального контроля над выполнением инструментов
• Настройки: Правила разрешений - Настройте декларативные правила разрешения/запрета с парсингом bash команд