Руководство по настройке прав

В этом руководстве объясняется, как настроить собственные правила прав для режима «Изучение».

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

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

Обзор

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

Файлы прав находятся по путям:

• workspace: ~/.craft-agent/workspaces/{slug}/permissions.json
• источник: ~/.craft-agent/workspaces/{slug}/sources/{source}/permissions.json

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

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

Если вы записали:

{ "pattern": "list", "comment": "Разрешить операции list" }

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

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

Схема permissions.json

{
  "allowedMcpPatterns": [
    { "pattern": "list", "comment": "Разрешить операции list" },
    { "pattern": "get", "comment": "Разрешить операции get" },
    { "pattern": "search", "comment": "Разрешить операции search" }
  ],
  "allowedApiEndpoints": [
    { "method": "GET", "path": ".*", "comment": "Все GET-запросы" },
    { "method": "POST", "path": "^/search", "comment": "POST для поиска" }
  ],
  "allowedBashPatterns": [
    { "pattern": "^ls\\s", "comment": "Разрешить команды ls" }
  ],
  "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-инструментов, которые разрешены в режиме «Изучение».

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

{
  "allowedMcpPatterns": [
    { "pattern": "list", "comment": "Все операции list для этого источника" },
    { "pattern": "get", "comment": "Все операции get для этого источника" },
    { "pattern": "search", "comment": "Все операции search для этого источника" }
  ]
}

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

{
  "allowedMcpPatterns": [
    { "pattern": "^mcp__.*__list", "comment": "Операции list для всех источников" }
  ]
}

В default.json на уровне приложения обычные слова в нижнем регистре (get, list, search, ...) — это слова-действия чтения, а не регулярные выражения: инструмент считается только для чтения, если одно из слов его имени (часть после mcp__<source>__) входит в этот список и ни одно слово не является словом записи (create, update, delete, send, run, mark, ...). Поэтому get_issue и slack_get_channel_history разрешены, а delete_account (содержит «count»), send_thread_reply (содержит «read») и get_or_create_issue — нет. status, info, count и exists учитываются только как первое слово. Записи с синтаксисом регулярных выражений сохраняют семантику регулярных выражений.

allowedApiEndpoints

Детальные правила для запросов к источникам API.

{
  "allowedApiEndpoints": [
    { "method": "GET", "path": ".*", "comment": "Все GET-запросы" },
    { "method": "POST", "path": "^/search", "comment": "POST для поиска" },
    { "method": "POST", "path": "^/v1/query$", "comment": "Эндпоинт query" }
  ]
}

allowedBashPatterns

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

{
  "allowedBashPatterns": [
    { "pattern": "^ls\\s", "comment": "Команды ls" },
    { "pattern": "^git\\s+status", "comment": "Команда git status" },
    { "pattern": "^pwd$", "comment": "Команда pwd" }
  ]
}

blockedTools

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

{
  "blockedTools": ["risky_tool_name"]
}

allowedWritePaths

Glob-паттерны для каталогов, где разрешена запись. Применяется в режимах «Изучение» и «Спрашивай перед правкой»: запись в совпадающий путь выполняется без запроса подтверждения, запись в другое место блокируется в режиме «Изучение» и вызывает запрос подтверждения в режиме «Спрашивай перед правкой». Используйте, чтобы автоматизации выполнялись в режиме «Спрашивай перед правкой», а не в режиме «Автономно».

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

blockedCommandHints

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

{
  "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 (необязательное): условие регулярного выражения; подсказка применяется только тогда, когда команда не соответствует этому паттерну

Поведение по умолчанию в режиме «Изучение»

Блокируется по умолчанию:

• команды 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)
• запись в папку планов (только планы сессии)

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

Эти команды разрешены в режиме «Изучение» без дополнительной конфигурации:

Примечания:

• echo разрешён для форматирования литерального вывода (например, echo ---), но перенаправления и подстановка команд по-прежнему блокируются.
• Команды семейства awk разрешены для обработки текста только для чтения, но опасные примитивы выполнения (например, system(...), getline с пайпом к команде или print | "cmd") блокируются.
• sed -n разрешён только для скриптов в стиле вывода: блокируются -i/--in-place, -f, команды w/W/e и флаги s///w/s///e.
• sort блокируется с -o/--output и --compress-program.
• gh api разрешён только для GET: -X/--method с любым другим методом блокируется, а также -f/-F/--field/--raw-field/--input без --method GET (они переключают запрос на POST). gh api graphql разрешён, если запрос не является mutation и его можно проверить.

Эти проверки аргументов выполняются в коде, поэтому они применяются даже к более старой версии default.json, где ещё остались более широкие паттерны.

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

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

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

Блокируемые конструкции shell

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

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

Режим «Спрашивай перед правкой»: «Всегда разрешать»

«Всегда разрешать» запоминает до конца сессии именно тот ключ, который проверка прав вычислила для этого запроса подтверждения:

Ничего не запоминается для опасных команд (rm, sudo, git push, git reset, git stash, kubectl delete, terraform apply, npm publish, ...), для разрушительного действия среди первых слов CLI (aws s3 rm, gh repo delete, docker volume rm), для цепочек, пайпов, перенаправлений или подстановок, для обёрток, которые запускают другую команду (env, xargs, pkexec, ...), когда флаг стоит перед подкомандой (git -C dir push), или для gh api (его метод — это флаг). Запоминаемый ключ никогда не разрешает автоматически цепочную команду: одобрение git commit не одобряет git commit -m x && rm -rf ~.

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

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

Правила каскадно применяются от workspace → источник → агент:

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

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

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

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

Примеры

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

{
  "allowedMcpPatterns": [
    { "pattern": "^mcp__linear__(list|get|search)", "comment": "Операции чтения" }
  ]
}

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

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

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

{
  "allowedBashPatterns": [
    { "pattern": "^git\\s+(status|log|diff|branch)", "comment": "Git только для чтения" }
  ]
}

Планирование в режиме «Изучение»

В режиме «Изучение» вы можете создавать планы реализации, которые пользователь может принять, чтобы перейти к выполнению.

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

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

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

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

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

Формат плана

# Plan Title

## Summary
Brief description of what this plan accomplishes.

## Steps
1. **Step description** - Details and approach
2. **Another step** - More details
3. ...

Рабочий процесс «Изучение» → реализация

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

1. Изучение — читайте файлы, ищите код, изучайте кодовую базу
2. План — запишите структурированный план в папку планов
3. Отправка — вызовите SubmitPlan, чтобы показать пользователю
4. Принятие — пользователь нажимает «Принять план», чтобы выйти из режима «Изучение»
5. Автономно — реализуйте план с полными правами

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