failproofai 1.0.1-beta.1 → 1.0.1

package/.next/standalone/docs-old/ru/built-in-policies.mdx

@@ -0,0 +1,853 @@
+---
+title: Встроенные политики
+description: "Все 39 встроенных политик, которые перехватывают распространённые режимы отказа агентов"
+icon: shield
+---
+
+failproofai поставляется с 39 встроенными политиками, которые перехватывают распространённые режимы отказа агентов. Каждая политика срабатывает на определённый тип события хука и имя инструмента. Девятнадцать политик принимают параметры, позволяющие настраивать их поведение без написания кода. Пять политик рабочего процесса обеспечивают соблюдение конвейера commit → push → PR → CI перед остановкой Claude.
+
+---
+
+## Обзор
+
+Политики сгруппированы по категориям:
+
+| Категория | Политики | Тип хука |
+|----------|----------|---------|
+| [Опасные команды](#опасные-команды) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse |
+| [Инфраструктурные команды](#инфраструктурные-команды) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse |
+| [Секреты (санитайзеры)](#секреты-санитайзеры) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse |
+| [Окружение](#окружение) | block-env-files, protect-env-vars | PreToolUse |
+| [Доступ к файлам](#доступ-к-файлам) | block-read-outside-cwd, block-secrets-write | PreToolUse |
+| [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse |
+| [База данных](#база-данных) | warn-destructive-sql, warn-schema-alteration | PreToolUse |
+| [Предупреждения](#предупреждения) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse |
+| [Менеджеры пакетов](#менеджеры-пакетов) | prefer-package-manager | PreToolUse |
+| [Рабочий процесс](#рабочий-процесс) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop |
+
+- **`block-`** — остановить агента от продолжения.
+- **`warn-`** — дать агенту дополнительный контекст, чтобы он мог самостоятельно исправиться.
+- **`sanitize-`** — удалить чувствительные данные из вывода инструмента, прежде чем агент их увидит.
+
+### Пространства имён
+
+Каждая политика находится в слоте `<namespace>/<name>`. Встроенные политики принадлежат пространству имён **`failproofai/`** — например, `failproofai/sanitize-jwt`. Пространство имён предотвращает конфликты при загрузке пользовательских или сторонних политик с похожими короткими именами.
+
+В вашей конфигурации вы можете ссылаться на встроенную политику либо по её короткому имени, либо по полному имени; обе формы разрешаются в одну и ту же политику:
+
+```json
+{
+  "enabledPolicies": [
+    "sanitize-jwt",
+    "failproofai/block-rm-rf"
+  ]
+}
+```
+
+Если имя не содержит `/`, failproofai обрабатывает его как принадлежащее пространству имён по умолчанию `failproofai`. Имена, которые уже содержат `/` (например `myorg/foo`, `custom/my-hook`), остаются без изменений.
+- **`require-`** — заблокировать событие Stop до выполнения условий.
+
+---
+
+<Tip>
+Каждая политика поддерживает необязательное поле `hint` в `policyParams`. Подсказка добавляется к сообщению deny или instruct, которое видит Claude, обеспечивая практическое руководство без изменения кода политики. Работает со встроенными, пользовательскими и условными политиками. Подробнее в [Конфигурация → hint](/ru/configuration#hint-cross-cutting).
+</Tip>
+
+---
+
+## Опасные команды
+
+Предотвращают запуск агентами операций, которые сложно отменить или которые могут повредить хост-систему.
+
+### `block-sudo`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет любую команду `sudo` или `doas`.
+
+Блокирует команду, которая запускает бинарный файл повышения привилегий **в позиции команды**. Сопоставление структурное, а не текстовое: команда разбивается на сегменты так, как это делает shell, префиксные присваивания (`FOO=bar`), перенаправления и запускающие программы с их флагами (`env`, `nohup`, `timeout`, `xargs`, `sh -c`, …) отбрасываются, и полученный бинарный файл сравнивается по **базовому имени**. Поэтому `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo` и `bash -c "sudo …"` всё отклоняется, а `doas` рассматривается как та же возможность под другим названием.
+
+Поскольку политика привязана к позиции команды, а не к появлению слова в любом месте, она **не** срабатывает на команды, которые просто его упоминают — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"` или `grep` с альтернацией, содержащей слово, выполняются нормально.
+
+<Warning>
+Это останавливает очевидную попытку; это не закрывает класс. Агент, который может запускать произвольный shell, всё ещё может достичь повышения привилегий косвенно — через переменную (`S=sudo; $S …`), базовый 64-кодированный конвейер или оболочку скрипта на диске — потому что ни одна проверка одной строки команды не может этого отследить. Рассматривайте это как ограду от ошибок и случайного повышения привилегий, а не как граница безопасности против решительного агента. Настоящая граница должна быть реализована ниже уровня shell.
+</Warning>
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `allowPatterns` | `string[]` | `[]` | Точные префиксы команд, которые разрешены. Каждая запись сопоставляется с разобранными токенами argv. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    }
+  }
+}
+```
+
+С этой конфигурацией `sudo systemctl status nginx` разрешается, но `sudo rm /etc/hosts` отклоняется.
+
+<Note>
+Шаблоны сопоставляются с разобранными токенами, а не с исходной строкой команды. Это предотвращает обход путём добавления операторов shell (например `sudo systemctl status x; rm -rf /` не соответствует `sudo systemctl status *`).
+</Note>
+
+---
+
+### `block-rm-rf`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет `rm -rf`, `rm -fr` и похожие формы рекурсивного удаления.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `allowPaths` | `string[]` | `[]` | Пути, которые безопасно рекурсивно удалять (например `/tmp`). |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-rm-rf": {
+      "allowPaths": ["/tmp", "/var/cache"]
+    }
+  }
+}
+```
+
+---
+
+### `block-curl-pipe-sh`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет `curl <url> | bash`, `curl <url> | sh`, `wget <url> | bash` и похожие шаблоны.
+
+Без параметров.
+
+---
+
+### `block-failproofai-commands`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет команды, которые бы удалили или отключили сам failproofai (например `npm uninstall failproofai`, `failproofai policies --uninstall`).
+
+Без параметров.
+
+---
+
+### `block-self-pause`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет `failproofai config --pause`, что приостанавливает исполнение на сеанс. Пауза — это решение человека — агент, который может её запустить, мог бы отключить каждую другую политику одной командой.
+
+Более узкая, чем [`block-failproofai-commands`](#block-failproofai-commands) намеренно и не охватывается ею: та политика привязана к границе команды, поэтому `npx -y failproofai config --pause` её не соответствует, и будучи широкой, её часто отключают, чтобы агенты могли запускать `failproofai audit`. `--resume` и `--status` разрешены — ни один из них не удаляет исполнение.
+
+Это останавливает прямую попытку, а не весь класс: агент всё ещё может достичь того же состояния через алиас или оболочку скрипта. Полное закрытие требует, чтобы пауза была недоступна из вызова инструмента вообще.
+
+Без параметров.
+
+---
+
+## Инфраструктурные команды
+
+Остановить агентов кодирования от запуска инфраструктурных CLI или срабатывания конвейеров CI/CD. Все политики в этой категории **opt-in** (`defaultEnabled: false`) — агенты, которым законно нужно вызывать `kubectl`, `terraform` и т. д., не будут нарушены, если вы не включите политику. При включении каждый вызов сопоставленного CLI отклоняется, если только команда не соответствует записи в `allowPatterns`.
+
+Грамматика шаблонов та же, что в [`block-sudo`](#block-sudo): токены сопоставляются с разобранными argv, `*` — подстановочный знак для одного токена, и любая команда, содержащая автономный оператор shell (`&&`, `||`, `|`, `;`) или токен с встроенными метасимволами shell, отклоняется перед сопоставлением списка разрешений, чтобы предотвратить обход впрыска.
+
+### `block-kubectl`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет любой вызов `kubectl`.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `allowPatterns` | `string[]` | `[]` | Префиксы команд kubectl, которые разрешены. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-kubectl": {
+      "allowPatterns": ["kubectl get *", "kubectl describe *", "kubectl logs *"]
+    }
+  }
+}
+```
+
+С этой конфигурацией `kubectl get pods` разрешается, но `kubectl apply -f deploy.yaml` отклоняется.
+
+---
+
+### `block-terraform`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет любой вызов `terraform` или `tofu` (OpenTofu).
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `allowPatterns` | `string[]` | `[]` | Префиксы команд terraform/tofu, которые разрешены. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-terraform": {
+      "allowPatterns": ["terraform plan", "terraform validate", "terraform show *"]
+    }
+  }
+}
+```
+
+---
+
+### `block-aws-cli`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет любой вызов CLI `aws`.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `allowPatterns` | `string[]` | `[]` | Префиксы команд aws CLI, которые разрешены. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-aws-cli": {
+      "allowPatterns": ["aws s3 ls *", "aws sts get-caller-identity"]
+    }
+  }
+}
+```
+
+---
+
+### `block-gcloud`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет любой вызов CLI `gcloud` (Google Cloud).
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `allowPatterns` | `string[]` | `[]` | Префиксы команд gcloud, которые разрешены. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-gcloud": {
+      "allowPatterns": ["gcloud auth list", "gcloud config list"]
+    }
+  }
+}
+```
+
+---
+
+### `block-az-cli`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет любой вызов CLI `az` (Azure).
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `allowPatterns` | `string[]` | `[]` | Префиксы команд az CLI, которые разрешены. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-az-cli": {
+      "allowPatterns": ["az account show", "az group list"]
+    }
+  }
+}
+```
+
+---
+
+### `block-helm`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет любой вызов `helm`.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `allowPatterns` | `string[]` | `[]` | Префиксы команд helm, которые разрешены. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-helm": {
+      "allowPatterns": ["helm list", "helm status *"]
+    }
+  }
+}
+```
+
+---
+
+### `block-gh-pipeline`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет следующие подкоманды `gh` CLI, которые мутируют состояние или срабатывают конвейеры:
+
+- `gh workflow run`, `gh workflow enable`, `gh workflow disable`
+- `gh run rerun`, `gh run cancel`
+- `gh pr merge`
+- `gh release create`, `gh release delete`
+- `gh cache delete`
+- `gh secret set`, `gh secret delete`
+
+Подкоманды `gh` только для чтения, такие как `gh pr view`, `gh pr list`, `gh run list`, `gh release view` и `gh api repos/.../...` **не** соответствуют этой политике — они регулярно нужны для проверок рабочего процесса (включая собственную `require-ci-green-before-stop` failproofai).
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `allowPatterns` | `string[]` | `[]` | Специфичные привязанные вызовы, которые нужно разрешить, хотя они иначе были бы отклонены. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-gh-pipeline": {
+      "allowPatterns": ["gh run rerun *"]
+    }
+  }
+}
+```
+
+---
+
+## Секреты (санитайзеры)
+
+Остановить агентов от утечки учётных данных в их контекст или вывод. Санитайзерные политики срабатывают на событиях **PostToolUse**. Когда Claude запускает команду Bash, читает файл или вызывает любой инструмент, эти политики проверяют вывод перед его возвращением Claude. Если обнаружена схема секрета, политика возвращает решение deny, которое предотвращает передачу вывода обратно.
+
+### `sanitize-jwt`
+
+**Событие:** PostToolUse (все инструменты)  
+**По умолчанию:** Скрывает JWT токены (три сегмента base64url, разделённые `.`).
+
+Без параметров.
+
+---
+
+### `sanitize-api-keys`
+
+**Событие:** PostToolUse (все инструменты)  
+**По умолчанию:** Скрывает распространённые форматы ключей API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS ключи доступа (`AKIA`), Stripe ключи (`sk_live_`, `sk_test_`), и Google API ключи (`AIza`).
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Дополнительные regex шаблоны для обработки как секреты. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
+        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
+      ]
+    }
+  }
+}
+```
+
+---
+
+### `sanitize-connection-strings`
+
+**Событие:** PostToolUse (все инструменты)  
+**По умолчанию:** Скрывает строки подключения к базе данных, которые содержат встроенные учётные данные (например `postgresql://user:password@host/db`).
+
+Без параметров.
+
+---
+
+### `sanitize-private-key-content`
+
+**Событие:** PostToolUse (все инструменты)  
+**По умолчанию:** Скрывает PEM блоки (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` и т. д.).
+
+Без параметров.
+
+---
+
+### `sanitize-bearer-tokens`
+
+**Событие:** PostToolUse (все инструменты)  
+**По умолчанию:** Скрывает заголовки `Authorization: Bearer <token>`, где токен 20 или более символов.
+
+Без параметров.
+
+---
+
+## Окружение
+
+Защитить чувствительную конфигурацию окружения от чтения или разоблачения агентами.
+
+### `block-env-files`
+
+**Событие:** PreToolUse (Bash, Read)  
+**По умолчанию:** Отклоняет чтение файлов `.env` через `cat .env`, вызовы инструмента Read с `.env` в качестве пути файла и т. д.
+
+Не блокирует `.envrc` или другие файлы, связанные с окружением — только файлы с именем ровно `.env`.
+
+Без параметров.
+
+---
+
+### `protect-env-vars`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет команды, которые выводят переменные окружения: `printenv`, `env`, `echo $VAR`.
+
+Без параметров.
+
+---
+
+## Доступ к файлам
+
+Держать агентов внутри границ проекта и вдалеке от чувствительных файлов.
+
+### `block-read-outside-cwd`
+
+**Событие:** PreToolUse (Read, Bash)  
+**По умолчанию:** Отклоняет чтение файлов вне корня проекта. Границей является `CLAUDE_PROJECT_DIR` (устанавливается один раз за сеанс Claude Code), с возвратом к текущему рабочему каталогу сеанса, когда та переменная не установлена. Использование корня проекта вместо живого `cwd` означает, что граница остаётся стабильной даже после того, как Claude переходит в подкаталог.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `allowPaths` | `string[]` | `[]` | Абсолютные префиксы пути, которые разрешены даже если вне корня проекта. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company/config"]
+    }
+  }
+}
+```
+
+---
+
+### `block-secrets-write`
+
+**Событие:** PreToolUse (Write, Edit)  
+**По умолчанию:** Отклоняет запись в файлы, обычно используемые для приватных ключей и сертификатов: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `additionalPatterns` | `string[]` | `[]` | Дополнительные шаблоны имени файла (в стиле glob) для блокирования. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-secrets-write": {
+      "additionalPatterns": [".token", ".secret"]
+    }
+  }
+}
+```
+
+---
+
+## Git
+
+Предотвратить случайные push, force-push и ошибки ветвей, которые сложно отменить.
+
+### `block-push-master`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет `git push origin main` и `git push origin master`.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | Имена ветвей, которые нельзя напрямую пушить. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "master", "release", "prod"]
+    }
+  }
+}
+```
+
+<Tip>
+Чтобы разрешить пушинг на все ветви (эффективно отключив эту политику без удаления её из `enabledPolicies`), установите `protectedBranches: []`.
+</Tip>
+
+---
+
+### `block-work-on-main`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет `git commit`, `git merge`, `git rebase` и `git cherry-pick`, пока рабочее дерево находится на `main` или `master`. Создание ветвей и переключение (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) не затронуты.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | Имена ветвей, на которых commit/merge/rebase/cherry-pick отклоняются. |
+
+---
+
+### `block-force-push`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отклоняет `git push --force` и `git push -f`.
+
+Нет специфичных параметров политики. Используйте кросс-секционный [`hint`](/ru/configuration#hint-cross-cutting) для предложения альтернатив:
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b <new-branch>`) and push that instead."
+    }
+  }
+}
+```
+
+---
+
+### `warn-git-amend`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude действовать осторожно при запуске `git commit --amend`. Не блокирует команду.
+
+Без параметров.
+
+---
+
+### `warn-git-stash-drop`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude подтвердить перед запуском `git stash drop`. Не блокирует команду.
+
+Без параметров.
+
+---
+
+### `warn-all-files-staged`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude проверить, что он ставит на сцену, при запуске `git add -A` или `git add .`. Не блокирует команду.
+
+Без параметров.
+
+---
+
+## База данных
+
+Перехватить деструктивные SQL операции перед их выполнением против вашей базы данных.
+
+### `warn-destructive-sql`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude подтвердить перед запуском SQL, содержащего `DROP TABLE`, `DROP DATABASE` или `DELETE` без предложения `WHERE`.
+
+Без параметров.
+
+---
+
+### `warn-schema-alteration`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude подтвердить перед запуском выражений `ALTER TABLE`.
+
+Без параметров.
+
+---
+
+## Предупреждения
+
+Дать агентам дополнительный контекст перед потенциально рискованными, но не деструктивными операциями.
+
+### `warn-large-file-write`
+
+**Событие:** PreToolUse (Write)  
+**По умолчанию:** Инструктирует Claude подтвердить перед записью файлов размером больше 1024 KB.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `thresholdKb` | `number` | `1024` | Порог размера файла в килобайтах, выше которого выдаётся предупреждение. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "warn-large-file-write": {
+      "thresholdKb": 256
+    }
+  }
+}
+```
+
+<Note>
+Обработчик хука применяет ограничение stdin 1 MB на полезные нагрузки. Чтобы протестировать эту политику с малым содержимым, установите `thresholdKb` на значение значительно ниже 1024.
+</Note>
+
+---
+
+### `warn-package-publish`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude подтвердить перед запуском `npm publish`.
+
+Без параметров.
+
+---
+
+### `warn-background-process`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude быть осторожным при запуске фоновых процессов через `nohup`, `&`, `disown` или `screen`.
+
+Без параметров.
+
+---
+
+### `warn-global-package-install`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Инструктирует Claude подтвердить перед запуском `npm install -g`, `yarn global add` или `pip install` без виртуального окружения.
+
+Без параметров.
+
+---
+
+## Менеджеры пакетов
+
+Обеспечить, какие менеджеры пакетов агент может использовать.
+
+### `prefer-package-manager`
+
+**Событие:** PreToolUse (Bash)  
+**По умолчанию:** Отключено. При включении блокирует любую команду менеджера пакетов, не входящую в список `allowed`, и сообщает Claude переписать команду, используя разрешённый менеджер.
+
+Обнаруживает: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo.
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `allowed` | string[] | `[]` | Разрешённые имена менеджеров пакетов. Любой обнаруженный менеджер не в этом списке блокируется. Когда пусто, политика неэффективна. |
+| `blocked` | string[] | `[]` | Дополнительные имена менеджеров для блокирования помимо встроенного списка (например `['pdm', 'pipx']`). |
+
+Встроенный список блокирования охватывает: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Используйте `blocked` чтобы добавить менеджеры, не входящие в этот список.
+
+**Пример конфигурации:**
+
+```json
+{
+  "enabledPolicies": ["prefer-package-manager"],
+  "policyParams": {
+    "prefer-package-manager": {
+      "allowed": ["uv", "bun"],
+      "blocked": ["pdm", "pipx"]
+    }
+  }
+}
+```
+
+С этой конфигурацией `pip install flask` и `pdm install flask` оба отклоняются с сообщением, говорящим Claude использовать вместо этого `uv` или `bun`. Команды такие как `uv pip install flask` разрешены, потому что `uv` в списке разрешений и проверяется первым.
+
+---
+
+## Поведение AI
+
+Обнаруживать, когда агенты застревают или ведут себя неожиданно.
+
+### `warn-repeated-tool-calls`
+
+**Событие:** PreToolUse (все инструменты)  
+**По умолчанию:** Инструктирует Claude пересмотреть, когда один и тот же инструмент вызывается 3+ раз с идентичными параметрами — частый признак того, что агент застрял в цикле.
+
+Без параметров.
+
+---
+
+## Рабочий процесс
+
+Обеспечить дисциплинированный рабочий процесс конца сеанса. Эти политики срабатывают на событии **Stop** и отклоняют агента от остановки до выполнения каждого условия. Они следуют естественной цепочке зависимостей: commit → push → PR → CI. Если политика отклоняет, более поздние политики в цепочке пропускаются (deny коротко замыкает).
+
+Все политики рабочего процесса **fail-open**: если требуемый инструмент недоступен (например `gh` не установлен, нет удалённого git), политика разрешает с информационным сообщением, объясняющим, почему проверка была пропущена.
+
+### Семантика Stop для каждого CLI
+
+Исполнение Stop выглядит немного иначе на различных шести поддерживаемых CLI, потому что каждый предоставляет другой контракт хука об окончании работы агента. **Результат** одинаков — агент не уходит от остановки, когда ворота рабочего процесса отказывают — но **механика** отличается. Таблица ниже резюмирует; только Pi имеет видимую пользователю особенность, стоящую понимания, прежде чем вы включите политику `require-*-before-stop`.
+
+| CLI | Когда срабатывают ворота | Что вы видите |
+|---|---|---|
+| Claude Code | Тот же цикл агента, немедленно | Claude продолжает работать — исправляет проблему, затем снова пытается завершить. Для вас нет видимого прерывания. |
+| Codex | Тот же цикл агента, немедленно | То же, что Claude. |
+| GitHub Copilot CLI | Тот же цикл агента, немедленно | То же, что Claude (использует канал повтора `{decision:"block", reason}` Copilot — проверено эмпирически против Copilot CLI 1.0.41). |
+| Cursor Agent | Тот же цикл агента, немедленно | То же, что Claude (использует канал `{followup_message}` Cursor — ограничен `loop_limit`, значение по умолчанию 5 повторов). |
+| OpenCode | Тот же цикл агента, немедленно | То же, что Claude (использует вызов SDK `client.session.prompt(...)` OpenCode, направленный через `hookSpecificOutput.additionalContext`). |
+| **Pi (pi-coding-agent)** | **Следующий ход пользователя** | **Pi видимо останавливается** когда срабатывают ворота — его цикл агента выходит и вы возвращаетесь к приглашению. Ворота затем срабатывают в следующий раз, когда вы отправляете приглашение: failproofai добавляет директиву `MANDATORY ACTION REQUIRED` к системному приглашению этого хода, инструктирующую LLM завершить шаг рабочего процесса (commit, push и т. д.) перед тем, как делать то, что вы попросили. |
+
+<Note>
+**Ограничение Pi.** `AgentEndEvent` Pi (эквивалент потока Claude для хука `Stop`) не имеет типа Result — к тому времени, когда оно срабатывает, цикл агента Pi уже вышел. Pi не может быть вынужден повторять тот же цикл, как это могут Claude / Copilot / Cursor / OpenCode. failproofai перемещает ворота на событие Pi `before_agent_start` (которое срабатывает после следующего приглашения пользователя), поэтому проверка рабочего процесса всё ещё обеспечивается, просто на следующий ход, а не на текущий.
+
+**Что это означает на практике:**
+
+- После остановки Pi причина отказа захватывается в памяти по ключу id сеанса Pi. Самое следующее приглашение, которое вы отправляете в том же процессе Pi, сливает его: LLM видит директиву `MANDATORY ACTION REQUIRED` в верхней части своего системного приглашения, совершает (или пушит / открывает PR / ждёт CI) и только затем продолжает с вашим запросом. Захваченная причина отказа одноразовая — один раз слита, ворота чисты.
+- Ворота ограничены временем жизни процесса Pi. Если вы `Ctrl+C` Pi или выйдете между ходами, запись в памяти отбросится вместе с процессом и ворота будут пропущены. Claude, Copilot, Cursor и OpenCode имеют ту же границу (убить агента и ворота пропущены) — Pi просто делает это более видимым, потому что агент видимо выходит перед срабатыванием ворот.
+- Ожидающий отказ также очищается на `session_shutdown` по любой причине (`new` / `resume` / `fork` / `quit`), поэтому устаревшие ворота из приоритетного сеанса не могут просачиваться в свежий сеанс, запущенный в том же процессе Pi.
+
+Если вам нужен повтор Claude-стиля в том же цикле, запустите ваши политики `Stop` под любым из других пяти поддерживаемых CLI. Мы отслеживаем Pi потоком для будущего типа Result на `AgentEndEvent`, который бы позволил нам закрыть этот разрыв.
+</Note>
+
+### `require-commit-before-stop`
+
+**Событие:** Stop  
+**По умолчанию:** Отклоняет остановку, когда есть незафиксированные изменения (изменённые, поставленные на сцену или неотслеживаемые файлы). Возвращает информационное сообщение, когда рабочий каталог чист.
+
+Без параметров.
+
+---
+
+### `require-push-before-stop`
+
+**Событие:** Stop  
+**По умолчанию:** Отклоняет остановку, когда есть непушенные коммиты или когда текущая ветвь не имеет удалённой отслеживаемой ветви. Предлагает `git push -u` для создания отслеживаемой ветви если нужно. Fails open, если нет настроенного удалённого.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `remote` | `string` | `"origin"` | Имя удалённого для пушинга. |
+
+**Пример:**
+
+```json
+{
+  "policyParams": {
+    "require-push-before-stop": {
+      "remote": "upstream"
+    }
+  }
+}
+```
+
+---
+
+### `require-pr-before-stop`
+
+**Событие:** Stop  
+**По умолчанию:** Отклоняет остановку, когда нет pull request для текущей ветви, или когда существующий PR закрыт без слияния. Инструктирует Claude создать PR с `gh pr create`. Когда PR **объединён**, политика разрешает (работа отправлена) и сообщение намекает переключиться с ветви (`git checkout main && git pull`).
+
+Без параметров.
+
+<Note>
+Эта политика требует [GitHub CLI](https://cli.github.com/) (`gh`) для установки и аутентификации.
+Запустите `gh auth login` с личным токеном доступа, имеющим область `repo` для доступа на чтение к
+pull requests. Если `gh` не установлен или не аутентифицирован, политика fails open и сообщает причину Claude.
+</Note>
+
+---
+
+### `require-no-conflicts-before-stop`
+
+**Событие:** Stop  
+**По умолчанию:** Отклоняет остановку, когда текущая ветвь не может чистко объединиться в базовую ветвь. Политика сначала подтверждает, что есть `OPEN` PR на GitHub для ветви — без одного, нет целевого объединения для обеспечения, поэтому вся политика коротко замыкает на разрешение. Один раз `OPEN` PR подтверждён, два независимых зонда запускаются:
+
+1. **Локально** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`. При конфликте сообщение deny называет конфликтующие файлы, поэтому Claude знает ровно что разрешить.
+2. **GitHub** — повторно использует результат `gh pr view --json mergeable,state`, уже выбранный в предварительной проверке. Перехватывает конфликты, которые устаревший локальный `origin/<baseBranch>` бы пропустил (например кто-то посадил конфликтующий PR на `main` с последнего выборки). Результат `CONFLICTING` отклоняет. Результат `UNKNOWN` также отклоняет и инструктирует Claude подождать ~10 секунд и переповторить перед попыткой остановиться снова — это предотвращает ложные отрицания, пока GitHub пересчитывает.
+
+Пропускает полностью (разрешает), когда: `gh` не установлен, нет PR для ветви, состояние PR не `OPEN` (например `MERGED`, `CLOSED`), или `gh pr view` возвращает непарсируемый вывод. Также fails open, когда `origin/<baseBranch>` отсутствует локально или когда нет коммитов впереди базы — те Layer 1 сквозные проходы всё ещё консультируют кэшированное слияние PR перед разрешением.
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|---------|----------|
+| `baseBranch` | `string` | `"main"` | Базовая ветвь для проверки на конфликты. |
+
+<Note>
+GitHub CLI (`gh`) требуется для этой политики. Политика использует `gh pr view` для подтверждения
+существования `OPEN` PR перед запуском любого зонда конфликта — без `gh`, политика
+коротко замыкает на разрешение. Запустите `gh auth login` с личным токеном доступа, имеющим
+область `repo` для доступа на чтение к pull requests.
+</Note>
+
+---
+
+### `require-ci-green-before-stop`
+
+**Событие:** Stop  
+**По умолчанию:** Отклоняет остановку, когда проверки CI отказывают или всё ещё работают на текущей ветви. Проверяет как GitHub Actions запуски рабочего процесса, так и сторонние проверки ботов (например CodeRabbit, SonarCloud, Codecov). Обрабатывает `skipped`, `cancelled` и `neutral` заключения как неправильные (последнее охватывает например Socket Security предупреждения на PR внешних участников, где приложение намеренно докладывает нейтрально вместо успеха/отказа). Возвращает информационное сообщение, когда все проверки прошли.
+
+Без параметров.
+
+<Note>
+Эта политика требует [GitHub CLI](https://cli.github.com/) (`gh`) для установки и аутентификации.
+Запустите `gh auth login` с личным токеном доступа, имеющим область `repo` для доступа на чтение к
+запускам рабочего процесса Actions и Checks API. Если `gh` не установлен или не аутентифицирован, политика fails open и сообщает причину Claude.
+</Note>
+
+---
+
+---
+
+## Отключение отдельных политик
+
+Удалите определённую политику из `enabledPolicies` в вашей конфигурации, или выключите её в вкладке Policies приборной панели.
+
+```json
+{
+  "enabledPolicies": [
+    "block-rm-rf",
+    "sanitize-api-keys"
+  ]
+}
+```
+
+Политики, не перечисленные в `enabledPolicies`, не запускаются, даже если существуют записи `policyParams` для них.