​
Разрешения SDK

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

​
Обзор

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

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

Порядок обработки: Хук PreToolUse → Правила Ask → Правила Deny → Проверка режима разрешений → Правила Allow → Обратный вызов canUseTool → Хук PostToolUse

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

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

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

SDK поддерживает четыре режима разрешений, каждый с разным поведением:
РежимОписаниеПоведение инструмента
defaultСтандартное поведение разрешенийПрименяются обычные проверки разрешений
planРежим планирования - без выполненияClaude может использовать только инструменты только для чтения; представляет план перед выполнением (В настоящее время не поддерживается в SDK)
acceptEditsАвтоматическое принятие правок файловПравки файлов и операции файловой системы автоматически одобряются
bypassPermissionsОбход всех проверок разрешенийВсе инструменты выполняются без запросов разрешений (используйте с осторожностью)

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

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

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

Установите режим при создании запроса: 
import { query } from "@anthropic-ai/claude-code";

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

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

Измените режим во время потоковой сессии: 
import { query } from "@anthropic-ai/claude-code";

// Создайте асинхронный генератор для потокового ввода
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, MultiEdit, Write)
  • Bash-команды файловой системы (mkdir, touch, rm, mv, cp)
  • Создание и удаление файлов

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

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

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

Режимы разрешений оцениваются в определенной точке потока разрешений:
  1. Хуки выполняются первыми - Могут переопределить любой режим
  2. Правила запрета проверяются - Блокируют инструменты независимо от режима
  3. Режим bypassPermissions - Если активен, разрешает все оставшиеся инструменты
  4. Правила разрешения проверяются
  5. Другие режимы влияют на поведение конкретных инструментов
  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 показал бы запрос разрешения пользователю, например, хуки и правила разрешений не покрывают это, и это не в режиме автоматического принятия. Вот полный пример, показывающий, как реализовать интерактивное одобрение инструментов: 
import { query } from "@anthropic-ai/claude-code";

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

​
Использование хуков для контроля инструментов

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

​
Реализация хуков

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

const result = await query({
  prompt: "Помоги мне рефакторить этот код",
  options: {
    hooks: {
      PreToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`Запрос инструмента: ${input.tool_name}`);
          
          // Парсить и валидировать ввод инструмента самостоятельно
          if (input.tool_name === "Bash") {
            const command = input.tool_input.command;
            if (command.startsWith("rm -rf")) {
              return {
                decision: "block",
                reason: "Опасная команда заблокирована"
              };
            }
          }
          
          return { continue: true };
        }]
      }],
      PostToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`Инструмент завершен: ${input.tool_name}`);
          // Логировать или аудировать результаты инструментов
          return { continue: true };
        }]
      }]
    }
  }
});

​
Ключевые отличия от canUseTool

  • Область действия: Хуки вызываются для всех использований инструментов; canUseTool обрабатывает случаи, не покрытые правилами разрешений
  • Контроль: Хуки требуют самостоятельного парсинга и валидации входных данных
  • События: Хуки поддерживают множественные события (PreToolUse, PostToolUse и т.д.) для разных этапов

​
Использование правил разрешений (settings.json)

Правила разрешений в settings.json обеспечивают декларативный контроль со встроенным парсингом bash-команд. Эти правила оцениваются до вызова canUseTool. Для более подробной информации о конфигурации настроек см. документацию по настройкам Claude Code.

​
Структура конфигурации

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./secrets/**)",
      "WebFetch"
    ],
    "ask": [
      "Bash(git push:*)",
      "Write(./production/**)"
    ]
  }
}

​
Синтаксис правил

Правила разрешений следуют шаблону: ИмяИнструмента(шаблон)
  • Правила Bash: Используют сопоставление префиксов (не регулярные выражения). Пример: Bash(npm:*) соответствует любой команде, начинающейся с “npm”
  • Правила файлов: Поддерживают glob-шаблоны. Пример: Read(./src/**/*.ts) соответствует файлам TypeScript в src
  • Правила только для инструментов: Опускают скобки для контроля целых инструментов. Пример: WebFetch блокирует все веб-запросы

​
Использование с SDK

Хотя правила еще нельзя установить программно в SDK, они будут считываться из файла settings.json в пути, где загружается SDK.

​
Порядок оценки разрешений

  1. Правила запрета проверяются первыми - если совпадают, использование инструмента блокируется
  2. Правила разрешения проверяются далее - если совпадают, использование инструмента разрешается
  3. Правила запроса проверяются - если совпадают, пользователю выводится запрос
  4. Обратный вызов canUseTool вызывается для любых оставшихся случаев

​
Парсинг bash-команд

SDK включает интегрированный bash-парсер, который понимает структуру команд:
  • Обрабатывает пайпы, перенаправления и подстановку команд
  • Распознает опасные шаблоны, такие как rm -rf или curl | sh
  • Поддерживает подстановочные знаки и сопоставление префиксов
Пример того, как работают bash-шаблоны:
  • Bash(git:*) - Соответствует любой git-команде
  • Bash(npm run test) - Соответствует точной команде
  • Bash(npm run test:*) - Соответствует npm run test:unit, test:integration и т.д.

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

  1. Начинайте с режима по умолчанию для стандартных проверок разрешений
  2. Используйте правила разрешений для статических политик, особенно bash-команд (см. настройки разрешений)
  3. Используйте хуки для логирования, аудита или преобразования всех использований инструментов (см. типы хуков)
  4. Используйте canUseTool для динамических решений по непокрытым случаям (см. тип CanUseTool)
  5. Создавайте многоуровневую защиту, комбинируя режимы, правила, хуки и обратные вызовы для критических приложений