​

Разрешения 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, 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

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

​

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

​

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

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

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)

​

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

{
  "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

​

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

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

​

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

• Обрабатывает каналы, перенаправления и подстановку команд
• Распознает опасные шаблоны, такие как rm -rf или curl | sh
• Поддерживает подстановочные знаки и сопоставление префиксов

• Bash(git:*) - Соответствует любой git-команде
• Bash(npm run test) - Соответствует точной команде
• Bash(npm run test:*) - Соответствует Bash-командам, начинающимся с npm run test, таким как npm run test anyFile.test.ts

​

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

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