​

Разрешения SDK

​

Обзор

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

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

​

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

​

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

​

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

​

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

​

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

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 команд