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

Обзор

Режим Explore — это режим только для чтения, который блокирует потенциально разрушительные операции. Пользовательские правила разрешений позволяют разрешить конкретные операции, которые в противном случае были бы заблокированы.

Рекомендуемый рабочий процесс с приоритетом CLI: используйте команды craft-agent permission ... вместо прямого редактирования JSON.

• craft-agent permission --help
• Справочник по каноническим командам: craft-cli.md

Файлы разрешений находятся в:

• Workspace: ~/.craft-agent/workspaces/{slug}/permissions.json
• Source: ~/.craft-agent/workspaces/{slug}/sources/{source}/permissions.json

Автоматическое ограничение области для разрешений источника

Важно: MCP-шаблоны в permissions.json источника автоматически ограничиваются этим источником.

Когда вы пишете:

{ "pattern": "list", "comment": "Allow list operations" }

Система внутренне преобразует его в mcp__<sourceSlug>__.*list. Это означает:

• Простые шаблоны, такие как list, влияют только на инструменты этого источника
• Нет риска случайно разрешить инструменты list из других источников
• Шаблоны на уровне workspace по-прежнему применяются глобально (для намеренных правил между источниками)

Схема permissions.json

{
  "allowedMcpPatterns": [
    { "pattern": "list", "comment": "Allow list operations" },
    { "pattern": "get", "comment": "Allow get operations" },
    { "pattern": "search", "comment": "Allow search operations" }
  ],
  "allowedApiEndpoints": [
    { "method": "GET", "path": ".*", "comment": "All GET requests" },
    { "method": "POST", "path": "^/search", "comment": "Search POST" }
  ],
  "allowedBashPatterns": [
    { "pattern": "^ls\\s", "comment": "Allow ls commands" }
  ],
  "blockedTools": [
    "dangerous_tool"
  ],
  "allowedWritePaths": [
    "/tmp/**",
    "~/.craft-agent/**"
  ],
  "blockedCommandHints": [
    {
      "command": "printf",
      "reason": "printf is not in the default Explore-mode allowlist.",
      "context": "Explore mode keeps a narrow read-only command set.",
      "tryInstead": [
        "Use echo for simple output",
        "Switch to Ask mode for this command"
      ],
      "example": "echo '--- separator ---'"
    },
    {
      "command": "sed",
      "reason": "Only print-only sed is allowed by default.",
      "whenNotMatching": "^sed\\s+-n\\b"
    }
  ]
}

Типы правил

allowedMcpPatterns

Шаблоны регулярных выражений для имён MCP-инструментов, которые разрешены в режиме Explore.

Для permissions.json на уровне источника используйте простые шаблоны (автоматически ограничиваются источником):

{
  "allowedMcpPatterns": [
    { "pattern": "list", "comment": "All list operations for this source" },
    { "pattern": "get", "comment": "All get operations for this source" },
    { "pattern": "search", "comment": "All search operations for this source" }
  ]
}

Для permissions.json на уровне workspace (глобальные правила) используйте полные шаблоны:

{
  "allowedMcpPatterns": [
    { "pattern": "^mcp__.*__list", "comment": "List operations across all sources" }
  ]
}

allowedApiEndpoints

Тонкие правила для запросов к API-источникам.

{
  "allowedApiEndpoints": [
    { "method": "GET", "path": ".*", "comment": "All GET requests" },
    { "method": "POST", "path": "^/search", "comment": "Search POST" },
    { "method": "POST", "path": "^/v1/query$", "comment": "Query endpoint" }
  ]
}

allowedBashPatterns

Шаблоны регулярных выражений для разрешённых команд bash.

{
  "allowedBashPatterns": [
    { "pattern": "^ls\\s", "comment": "ls commands" },
    { "pattern": "^git\\s+status", "comment": "git status" },
    { "pattern": "^pwd$", "comment": "pwd command" }
  ]
}

blockedTools

Дополнительные инструменты для блокировки (редко требуется).

{
  "blockedTools": ["risky_tool_name"]
}

allowedWritePaths

Glob-шаблоны для каталогов, где разрешены записи.

{
  "allowedWritePaths": [
    "/tmp/**",
    "~/.craft-agent/**",
    "/path/to/project/output/**"
  ]
}

blockedCommandHints

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

{
  "blockedCommandHints": [
    {
      "command": "printf",
      "reason": "printf is not in the default Explore-mode allowlist.",
      "context": "Explore mode keeps a narrow read-only command set.",
      "tryInstead": [
        "Use echo for simple output",
        "Switch to Ask mode for this command"
      ],
      "example": "echo '--- separator ---'"
    },
    {
      "command": "sed",
      "reason": "Only print-only sed is allowed by default.",
      "whenNotMatching": "^sed\\s+-n\\b"
    }
  ]
}

Поля:

• command (обязательное): базовое имя команды (например, printf, sed)
• reason (обязательное): основное объяснение, показываемое пользователю
• context (необязательное): дополнительный контекст политики/риска
• tryInstead (необязательное): рекомендуемые альтернативы
• example (необязательное): пример команды
• whenNotMatching (необязательное): условие регулярного выражения; подсказка применяется только тогда, когда команда не соответствует этому шаблону

Поведение по умолчанию в режиме Explore

Заблокировано по умолчанию:

• Команды Bash (кроме перечисленных ниже команд только для чтения)
• Инструменты Write, Edit, MultiEdit
• MCP-инструменты с семантикой записи (create, update, delete)
• Запросы API POST/PUT/DELETE

Разрешено по умолчанию:

• Read, Glob, Grep
• WebFetch, WebSearch
• TodoWrite
• Инструменты браузера (browser_* и mcp__session__browser_*)
• MCP-инструменты с семантикой чтения (list, get, search)
• Записи в папку Plans (только планы сессии)

Команды Bash только для чтения

Эти команды разрешены в режиме Explore без пользовательской настройки:

Примечания:

• echo разрешён для форматирования литерального вывода (например, echo ---), но перенаправления и подстановка команд по-прежнему блокируются.
• Команды семейства awk разрешены для обработки текста только для чтения, но опасные примитивы выполнения (например, system(...), getline с командным пайпом или print | "cmd") блокируются.

Составные команды

Составные команды с использованием &&, || и | разрешены, когда все части безопасны:

Каждая команда проверяется независимо. Если любая команда отсутствует в списке разрешённых, вся составная команда блокируется.

Заблокированные конструкции оболочки

Эти конструкции всегда блокируются, даже если базовая команда разрешена:

Пример: git status > file.txt блокируется, потому что > может перезаписать файлы.

Каскадные правила

Правила каскадируются от workspace → source → agent:

1. Правила workspace применяются глобально
2. Правила источника расширяют правила workspace для этого источника
3. Правила агента расширяют оба для сессии этого агента

Правила аддитивны — они могут только разрешать больше операций, а не ограничивать дополнительно.

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

1. Будьте конкретны с шаблонами — используйте якоря (^, $), чтобы избежать чрезмерного соответствия
2. Добавляйте комментарии — объясняйте, почему существует каждое правило
3. Тестируйте шаблоны — проверяйте, что регулярные выражения соответствуют ожидаемым именам инструментов
4. Минимальные разрешения — разрешайте только то, что нужно

Примеры

Доступ к Linear только для чтения:

{
  "allowedMcpPatterns": [
    { "pattern": "^mcp__linear__(list|get|search)", "comment": "Read operations" }
  ]
}

API только для поиска:

{
  "allowedApiEndpoints": [
    { "method": "GET", "path": ".*" },
    { "method": "POST", "path": "^/search" }
  ]
}

Безопасные команды git:

{
  "allowedBashPatterns": [
    { "pattern": "^git\\s+(status|log|diff|branch)", "comment": "Read-only git" }
  ]
}

Планирование в режиме Explore

В режиме Explore вы можете создавать планы реализации, которые пользователь может принять для перехода к выполнению.

Когда создавать планы

Создавайте план, когда:

• Задача содержит несколько сложных шагов
• Вы хотите получить одобрение пользователя перед внесением изменений
• Вы собрали достаточно контекста и готовы к реализации

Создание плана

1. Запишите план в markdown-файл в папке plans сессии
2. Вызовите SubmitPlan с путём к файлу
3. Пользователь видит отформатированный план с кнопкой «Accept Plan»
4. Нажатие «Accept Plan» завершает режим Explore и начинает реализацию

Формат плана

# Заголовок плана

## Резюме
Краткое описание того, что этот план обеспечивает.

## Шаги
1. **Описание шага** — детали и подход
2. **Другой шаг** — дополнительные детали
3. ...

Рабочий процесс Explore → реализация

Рекомендуемый рабочий процесс:

1. Explore — читайте файлы, ищите код, изучайте кодовую базу
2. Plan — напишите структурированный план в папку plans
3. Submit — вызовите SubmitPlan, чтобы показать пользователю
4. Accept — пользователь нажимает «Accept Plan», чтобы завершить режим Explore
5. Execute — реализуйте план с полными разрешениями

Это обеспечивает плавный переход от исследования к реализации под контролем пользователя.