Разрешения
Режимы разрешений, правила разрешений, защищённые пути, режим auto и журнал аудита.
Прежде чем запустить любой инструмент, Cusp решает, можно ли сделать это, не спрашивая вас. Решение принимают по порядку: хуки, ваши правила, защищённые пути, режим разрешений сессии и, в режиме auto, модель-классификатор. Если ни один из них не разрешает вызов, Cusp спрашивает вас.
Режимы разрешений
| Режим | Что выполняется без вопросов | Как включить |
|---|---|---|
default | Действия только для чтения внутри рабочей области: чтение и поиск файлов, команды оболочки только для чтения, например ls или git status | Используется по умолчанию |
acceptEdits | Всё перечисленное выше плюс правки файлов внутри рабочей области | Shift+Tab, /mode acceptEdits |
plan | Только исследование без изменений. Правки и изменяющие команды запрещены, пока вы не одобрите план | Shift+Tab, /plan |
auto | Действия с низким риском по оценке быстрой модели-классификатора. О рискованных по-прежнему спрашивает | Shift+Tab, /mode auto |
bypass | Всё, кроме запрещающих правил и защищённых путей | --permission-mode bypassPermissions при запуске |
В CLI Shift+Tab переключает по кругу default, acceptEdits, plan и auto. Режим bypass входит в этот круг, только если сессия в нём началась.
Есть ещё dontAsk для запусков без присмотра: всё, что потребовало бы вопроса, вместо этого запрещается. Неинтерактивные запуски cusp -p ведут себя так же, если вы не разрешили инструменты заранее.
Режим планирования
В режиме планирования агент изучает код, а затем вызывает ExitPlanMode с планом. Вы одобряете его (и выбираете режим, в котором продолжить) или возвращаете с замечаниями. Во время планирования агент может писать только в собственный файл плана. Агент также может сам перейти в режим планирования через EnterPlanMode, если задача настолько большая, что сначала нужен проект.
Режим auto
В режиме auto вопрос «нужно ли спросить?» решает отдельная быстрая модель (малая модель провайдера). Классификатор видит только ваши собственные недавние сообщения и предлагаемое действие. Он никогда не видит рассуждений агента или вывода инструментов, поэтому текст, внедрённый в веб-страницу или файл, не сможет уговорить его что-то одобрить.
Классификатор при сбое запрещает. Если он недоступен, выдаёт ошибку или отвечает неоднозначно, Cusp спрашивает вас. После 3 блокировок подряд или 20 за одну сессию режим auto приостанавливается и переходит к вопросам, чтобы запутавшийся агент не долбился в него без конца. Широкие разрешающие правила вроде Bash(*) в режиме auto игнорируются, потому что они полностью обходили бы классификатор.
Режим auto доступен, только если его разрешают ваши пользовательские настройки. Настройки проекта не могут его включить.
Правила
Правила позволяют заранее разрешить, всегда спрашивать или всегда запрещать определённые действия. Синтаксис — Tool или Tool(specifier), тот же формат, что у правил в существующих settings.json.
{
"permissions": {
"allow": [
"Bash(npm run test:*)",
"Bash(git log *)",
"Edit(src/**)",
"WebFetch(domain:docs.python.org)",
"mcp__github__get_issue"
],
"ask": ["Bash(git push *)"],
"deny": ["Read(.env)", "Read(**/*.pem)", "Bash(curl *)", "WebSearch"]
}
}Порядок проверки
- Правила deny важнее всего. Запрет срабатывает в любом режиме, включая bypass.
- Затем правила ask. Они заставляют спросить, даже если подходит и разрешающее правило.
- Правила allow одобряют вызов.
- Если ни одно правило не подошло, решает режим.
Правила из всех файлов настроек объединяются: управляемых, из командной строки, локальных, проектных и пользовательских. Где они находятся, описано в разделе Конфигурация.
Справочник правил
| Правило | К чему применяется | Спецификатор |
|---|---|---|
Bash(…) | Bash, а также команды оболочки, запущенные через Terminal и Process | Шаблон команды |
Read(…) | Read, Grep, Glob, LS | Шаблон пути |
Edit(…) | Edit, Write, MultiEdit, ApplyPatch, EditLines, NotebookEdit | Шаблон пути |
WebFetch(domain:…) | WebFetch | Имя хоста |
WebSearch(…) | WebSearch | Glob-шаблон запроса |
Agent(…) (псевдоним Task) | Agent | Тип субагента, например Agent(Explore) |
Skill(…) | Skill | Имя навыка: Skill(deploy), Skill(deploy *), Skill(ops:*) |
mcp__server, mcp__server__tool, mcp__server__* | Инструменты MCP | — |
| Любое другое имя инструмента | Этот инструмент | — |
Разрешающее правило Edit(…) также даёт доступ на чтение к тем же путям. Запрещающее правило Read(…) также блокирует там правки.
Шаблоны команд
| Шаблон | Что подходит |
|---|---|
Bash(npm test) | Только npm test |
Bash(npm run test:*) | npm run test и что угодно после него (завершающее :* — маркер префикса) |
Bash(git log *) | git log и git log --oneline, но не git logx |
Bash(ls*) | ls, lsof и всё, что начинается с ls |
Перед сопоставлением Cusp полноценно разбирает команды оболочки. Составная команда вроде npm test && git push разбивается на части, и каждая часть должна быть разрешена отдельно. Подстановки команд, heredoc, конвейеры и обёртки вроде env, timeout или xargs распознаются, поэтому timeout 60 rm -rf build рассматривается как rm -rf build.
Если вы напишете Bash(git * main), Cusp предупредит, что подстановочный знак перед подкомандой подходит под гораздо большее, чем вы, скорее всего, имели в виду.
Шаблоны путей
Шаблоны путей следуют соглашениям gitignore:
| Шаблон | Значение |
|---|---|
src/** или ./src/** | Относительно рабочего каталога |
/docs/** | Относительно корня проекта, которому принадлежит файл настроек (для пользовательских настроек — ~/.cusp) |
~/notes/** | Относительно домашнего каталога |
//etc/hosts | Абсолютный путь |
.env, *.pem | Имя без пути подходит на любой глубине |
!pattern | Делает исключение из предыдущего правила в том же файле |
* подходит в пределах одного сегмента пути, ** — через несколько сегментов, а шаблон, указывающий на каталог, охватывает всё, что в нём находится.
Защищённые пути
Через некоторые файлы внедрение в промпт может закрепиться или расширить свои возможности: конфигурация агентов, внутренние файлы git, файлы запуска оболочки и конфигурации инструментов, которые выполняют код. Запись в них всегда требует участия человека, в любом режиме, включая bypass. В режиме dontAsk и в неинтерактивных запусках она запрещена.
Защищённые каталоги на любой глубине: .git, .cusp, .claude, .codex, .cursor, .gemini, .vscode, .idea, .husky, .cargo, .devcontainer, .yarn, .mvn, .ssh, .gnupg, .aws.
Защищённые файлы на любой глубине включают .gitconfig, .gitmodules, файлы запуска оболочки (.bashrc, .zshrc, .profile и подобные), .envrc, .npmrc, .yarnrc, bunfig.toml, .pre-commit-config.yaml, конфигурации lefthook, .mcp.json, .claude.json и .cusp.json.
Несколько мест внутри защищённых каталогов исключены, потому что агенты пишут туда на законных основаниях, например .cusp/worktrees и .cusp/agent-memory.
Cusp также отказывается без явного подтверждения выполнять заведомо разрушительные команды оболочки для критичных путей, например удаление домашнего каталога или корня файловой системы.
Ответ на запрос разрешения
Когда Cusp спрашивает, можно выбрать:
| Вариант | Результат |
|---|---|
| Разрешить один раз | Только этот вызов |
| Разрешить на сессию | Добавляет правило сессии, и похожие вызовы выполняются без вопросов до конца сессии |
| Разрешать всегда | Записывает правило в .cusp/settings.local.json, который не предназначен для коммита |
| Запретить | Вызов не выполняется, а агент узнаёт, что он запрещён |
| Запретить с пояснением | Вызов не выполняется, а агент получает ваше пояснение и может сменить курс |
Для «всегда» Cusp предлагает правило настолько узкое, насколько это имеет смысл, например Bash(npm run lint:*), а не Bash(npm *).
Хуки и разрешения
Хуки PreToolUse выполняются до движка разрешений и могут вернуть allow, deny, ask или defer. Запрет от хука действует в любом режиме. Хук PermissionRequest выполняется, когда должен появиться запрос разрешения, и может ответить на него за вас. См. Хуки.
Доверие к рабочей области
Когда вы впервые открываете папку, Cusp спрашивает, доверяете ли вы ей. Пока вы не подтвердите доверие, собственные файлы настроек проекта могут только сужать разрешения. Они не могут добавлять разрешающие правила, хуки, переменные окружения, MCP-серверы, дополнительные каталоги, помощник для API-ключа или команду строки состояния.
Независимо от доверия, настройки проекта и локальные настройки никогда не могут сделать режимом по умолчанию auto или bypass и не могут переопределять чувствительные переменные окружения, такие как HOME, TMPDIR или XDG_*.
Аудит
Каждое решение записывается в журнал сессии как событие permission.decision: инструмент, режим, результат, что приняло решение (правило, режим, классификатор, защищённый путь, хук или вы) и подошедшее правило. Решения любой сессии можно просмотреть задним числом.
Флаги командной строки
cusp --permission-mode acceptEdits
cusp --allowedTools "Bash(git log *)" Edit
cusp --disallowedTools "Bash(rm *)" WebFetch
cusp --dangerously-skip-permissions # same as --permission-mode bypassPermissions--allowedTools и --disallowedTools принимают списки через запятую или пробел и никогда не разбивают их внутри скобок. Они действуют только в пределах сессии.
Сессии
Сессия — это журнал событий, в который можно только дописывать; именно он позволяет возобновлять, ветвить и откатывать сессии и изолировать их в worktree.
Песочница
Команды оболочки, которые запускает агент, ограничены песочницей операционной системы — Seatbelt в macOS, bubblewrap в Linux: запись только в рабочую область, без чтения учётных данных и без сети, если вы её не разрешили.