failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/ru/configuration.mdx

@@ -0,0 +1,269 @@
+---
+---
+title: Конфигурация
+description: "Формат файла конфигурации, система трёх уровней и правила слияния"
+icon: gear
+---
+
+failproofai использует JSON-файлы конфигурации для управления активными политиками, их поведением и местом загрузки пользовательских политик. Конфигурация разработана так, чтобы её было легко делить в команде — зафиксируйте её в репозитории, и каждый разработчик получит одну и ту же защиту агента.
+
+---
+
+## Уровни конфигурации
+
+Существует три уровня конфигурации, оцениваемые по приоритету:
+
+| Уровень | Путь файла | Назначение |
+|---------|-----------|-----------|
+| **project** | `.failproofai/policies-config.json` | Параметры для конкретного репозитория, добавлены в контроль версий |
+| **local** | `.failproofai/policies-config.local.json` | Личные переопределения для репозитория, исключены из Git |
+| **global** | `~/.failproofai/policies-config.json` | Пользовательские значения по умолчанию для всех проектов |
+
+Когда failproofai получает событие hook, он загружает и объединяет все три файла, которые существуют для текущей рабочей директории.
+
+### Правила слияния
+
+**`enabledPolicies`** — объединение всех трёх уровней. Политика, включённая на любом уровне, активна.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← дедублицированное объединение
+```
+
+**`policyParams`** — первый уровень, определивший параметры для политики, полностью побеждает. Глубокого слияния значений внутри параметров политики не происходит.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project побеждает, global игнорируется
+```
+
+```text
+project:  (запись block-sudo отсутствует)
+local:    (запись block-sudo отсутствует)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← переходит на global
+```
+
+**`customPoliciesPaths` / `customPoliciesPath`** — первый уровень, определивший любую форму, побеждает.
+
+**`disabledCustomPolicies`** — объединение всех уровней. Панель управления записывает сюда квалифицированный по источнику ID при отключении отдельной политики из явного или конвенционального файла политик. Политики, не указанные в списке, остаются включёнными по умолчанию; ID включают источник файла, поэтому политики с одинаковыми названиями в разных файлах можно управлять независимо.
+
+**`llm`** — первый уровень, определивший его, побеждает.
+
+---
+
+## Формат файла конфигурации
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "sanitize-jwt",
+    "block-env-files",
+    "block-read-outside-cwd"
+  ],
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    },
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "prod"]
+    },
+    "block-rm-rf": {
+      "allowPaths": ["/tmp"]
+    },
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company"]
+    },
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
+      ]
+    },
+    "warn-large-file-write": {
+      "thresholdKb": 512
+    }
+  },
+  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
+}
+```
+
+---
+
+## Справочник полей
+
+### `enabledPolicies`
+
+Тип: `string[]`
+
+Список имён политик для включения. Имена должны точно совпадать с идентификаторами политик, показываемыми `failproofai policies`. Полный список см. в [Встроенные политики](/ru/built-in-policies).
+
+Политики, не указанные в `enabledPolicies`, неактивны, даже если они содержат записи в `policyParams`.
+
+### `policyParams`
+
+Тип: `Record<string, Record<string, unknown>>`
+
+Переопределения параметров для каждой политики. Внешний ключ — это имя политики; внутренние ключи — специфичны для политики. Каждая политика документирует доступные параметры в [Встроенные политики](/ru/built-in-policies).
+
+Если политика имеет параметры, но вы их не указали, используются встроенные по умолчанию значения политики. Пользователи, которые вообще не настраивают `policyParams`, получают поведение, идентичное предыдущим версиям.
+
+Неизвестные ключи внутри блока параметров политики молча игнорируются при срабатывании hook, но отмечаются как предупреждения при запуске `failproofai policies`.
+
+#### `hint` (сквозной параметр)
+
+Тип: `string` (опционально)
+
+Сообщение, добавляемое к причине, когда политика возвращает `deny` или `instruct`. Используйте его, чтобы дать Claude действенное руководство без изменения самой политики.
+
+Работает с любым типом политики — встроенной, пользовательской (`custom/`), проектной конвенции (`.failproofai-project/`) или пользовательской конвенции (`.failproofai-user/`).
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Попробуйте создать свежую ветку вместо этого."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "Используйте apt-get напрямую без sudo."
+    },
+    "custom/my-policy": {
+      "hint": "Сначала попросите одобрение у пользователя."
+    }
+  }
+}
+```
+
+Когда `block-force-push` отклоняет, Claude видит: *«Force-push заблокирован. Попробуйте создать свежую ветку вместо этого.»*
+
+Не-строковые значения и пустые строки молча игнорируются. Если `hint` не установлен, поведение остаётся неизменным (обратная совместимость).
+
+### `customPoliciesPath`
+
+Тип: `string` (абсолютный путь)
+
+Путь к файлу JavaScript, содержащему пользовательские hook-политики. Устанавливается автоматически `failproofai policies --install --custom <path>` (путь разрешается на абсолютный перед сохранением).
+
+Файл загружается заново при каждом событии hook — кэширования нет. Подробности разработки см. в [Пользовательские политики](/ru/custom-policies).
+
+### Политики, основанные на конвенции
+
+Помимо явного `customPoliciesPath`, failproofai автоматически обнаруживает и загружает файлы политик из директорий `.failproofai/policies/`:
+
+| Уровень | Директория | Уровень конфигурации |
+|---------|-----------|-----------|
+| Project | `.failproofai/policies/` | Общее с командой через контроль версий |
+| User | `~/.failproofai/policies/custom-policies/` | Личное, применяется ко всем проектам |
+
+<Note>
+  Директория на уровне пользователя переместилась на уровень ниже при
+  переорганизации домашней директории. Файлы, оставленные в старой
+  `~/.failproofai/policies/`, автоматически перемещаются в `custom-policies/`
+  при первом запуске любой команды `failproofai` после обновления, и команда
+  сообщает вам, какие файлы она переместила.
+</Note>
+
+**Совпадение файлов:** загружаются только файлы, совпадающие с `*policies.{js,mjs,ts}` (например, `security-policies.mjs`, `workflow-policies.js`). Другие файлы в директории игнорируются.
+
+**Конфигурация не требуется:** конвенциональные политики не требуют записей в `policies-config.json`. Просто поместите файлы в директорию, и они будут подхвачены при следующем событии hook.
+
+**Объединённая загрузка:** сканируются обе директории конвенциональных политик — проектная и пользовательская. Все совпадающие файлы с обоих уровней загружаются (в отличие от `customPoliciesPath`, которая использует принцип «первый уровень побеждает»).
+
+Подробности и примеры см. в [Пользовательские политики](/ru/custom-policies).
+
+### `llm`
+
+Тип: `object` (опционально)
+
+Конфигурация LLM-клиента для политик, совершающих вызовы ИИ. Не требуется для большинства установок.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## Управление конфигурацией из CLI
+
+Команды `policies --install` и `policies --uninstall` записывают в файл настроек hook вашего agent CLI (входные точки hook), тогда как `policies-config.json` — это файл, которым вы управляете непосредственно. Они разделены:
+
+- **Параметры Agent CLI** — говорит агенту вызывать `failproofai --hook <event>` при каждом использовании инструмента:
+  - **Claude Code**: `~/.claude/settings.json` (пользователь), `<cwd>/.claude/settings.json` (проект), `<cwd>/.claude/settings.local.json` (локально)
+  - **OpenAI Codex**: `~/.codex/hooks.json` (пользователь), `<cwd>/.codex/hooks.json` (проект) — у Codex нет локального уровня
+  - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (пользователь), `<cwd>/.github/hooks/failproofai.json` (проект) — у Copilot нет локального уровня. Записи hook используют поля команды `bash`/`powershell` Copilot с ключом OS и `timeoutSec`; файл содержит маркер `version: 1` на верхнем уровне. Поддержка Copilot CLI находится в **бета**, пока мы проверяем схему записей `events.jsonl` (которая не указана в публичной документации) против большего количества реальных сессий. **VS Code Copilot Chat режим агента (Preview)** читает конфиги hook из `.github/hooks/*.json`, `~/.copilot/hooks/*.json` и `~/.claude/settings.json` (управляется параметром `chat.hookFilesLocations`) используя ту же Claude-подобную контрактную форму `{hookSpecificOutput:{permissionDecision:"deny",…}}` — точно те пути, которые `copilot`-интеграция и `claude`-интеграция (`~/.claude/settings.json`) уже записывают, поэтому `failproofai policies --install --cli copilot` (или `--cli claude`) **уже реализует в режиме VS Code agent** без отдельной интеграции `vscode` (подтверждено live из логов обнаружения VS Code).
+  - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (пользователь), `<cwd>/.cursor/hooks.json` (проект) — у Cursor нет локального уровня. Записи hook используют Claude-подобную форму `{type, command, timeout}` (без разделения `bash`/`powershell`), но хранятся с ключами в camelCase (`preToolUse`, `beforeSubmitPrompt`, …) в плоском массиве в соответствии со [схемой hooks](https://cursor.com/docs/hooks) Cursor; файл содержит маркер `version: 1` на верхнем уровне. Обработчик канонизирует camelCase → PascalCase через `CURSOR_EVENT_MAP`, поэтому существующие встроенные политики срабатывают без изменений. Поддержка Cursor Agent находится в **бета**, пока мы проверяем формат транскрипта Cursor на диске (не указан в публичной документации) против большего количества реальных установок.
+  - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (пользователь), `<cwd>/.opencode/opencode.json` + `<cwd>/.opencode/plugins/failproofai.mjs` (проект) — у OpenCode нет локального уровня. В отличие от остальных пяти CLI, OpenCode **не имеет системы внешних hook-команд**: он загружает встроенные JS/TS плагины, явно зарегистрированные через массив `plugin: []` в `opencode.json` (автообнаружение из `.opencode/plugins/` **не** является способом загрузки плагинов в opencode v1.14.33). Install размещает небольшой сгенерированный шим плагина, который вызывает binary failproofai через subprocess и переводит JSON-ответ binary обратно в семантику плагина: `throw new Error()` для отклонения tool-события (отменяет вызов инструмента), `client.session.prompt(...)` для `instruct` И для `Stop` / `SubagentStop` отклонения (отправляет причину отклонения как следующее сообщение пользователя — единственный канал force-retry, поскольку `session.idle` является только уведомлением и выброс из неё не имеет эффекта), и no-op для allow. Шим канонизирует имена инструментов (lowercase → PascalCase через `OPENCODE_TOOL_MAP`) и ключи input-аргументов инструмента (camelCase → snake_case через `OPENCODE_TOOL_INPUT_MAP` для `Read` / `Write` / `Edit`, например `filePath` → `file_path`, `oldString` → `old_string`) перед отправкой на binary, поэтому встроенные проверки путей, такие как `block-read-outside-cwd`, `block-env-files` и `block-secrets-write`, срабатывают без изменений на вызовах инструментов OpenCode. Сессии хранятся в SQLite DB OpenCode в `~/.local/share/opencode/opencode.db`; просмотрщик сессий панели управления читает их через `opencode db --format json` и `opencode export <id>`. Поддержка OpenCode находится в **бета**, пока мы проверяем поведение на разных версиях и против большего количества реальных сессий. См. [документацию плагинов OpenCode](https://opencode.ai/docs/plugins/).
+  - **Pi _(beta)_**: `~/.pi/agent/settings.json` (пользователь), `<cwd>/.pi/settings.json` (проект) — у Pi нет локального уровня. Pi загружает пакеты расширений TypeScript при запуске; файл параметров — это плоский массив строк `{"packages": ["./relative/path", …]}`. failproofai записывает одну запись packages-массива, указывающую на его распакованную директорию `pi-extension/`. Расширение внутри подписывается на события Pi `tool_call` / `user_bash` / `input` / `session_start` и вызывает оболочку `failproofai --hook <Event> --cli pi`; обработчик канонизирует underscore_lower_snake_case → PascalCase через `PI_EVENT_MAP`, поэтому существующие встроенные политики срабатывают без изменений. Аргументы input инструмента также канонизируются через `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit предоставляют `path` вместо `file_path`; маппирование ключа верхнего уровня позволяет `block-env-files` и `block-secrets-write` срабатывать — `block-read-outside-cwd` уже имел fallback `path`). Поддержка Pi находится в **бета**, пока API расширений Pi и layout журнала сессии стабилизируются.
+  - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**только пользовательский уровень** — у Hermes нет проектной/локальной конфигурации). Hermes — это **шлюз** Slack/Telegram, поэтому одна установка перехватывает вызовы инструментов со всех платформ (Slack/Telegram/cli/cron) **и** внутренних субагентов. Записи hook — это пара `{command, timeout}` (timeout в **секундах**) под картой `hooks:`, ключи которой — это события Hermes в snake_case (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); обработчик канонизирует события через `HERMES_EVENT_MAP` и имена инструментов через `HERMES_TOOL_MAP`, поэтому встроенные политики срабатывают без изменений. Конфиг редактируется через comment-preserving YAML `Document` round-trip, поэтому другие параметры оператора остаются, и install устанавливает `hooks_auto_accept: true`, поэтому безголовой шлюз (нет TTY) запускает hooks без запроса согласия. Оценивающий выпускает контрактную форму Hermes `{"decision":"block","reason"}` на stdout (Hermes игнорирует exit codes). **Ограничения:** у Hermes нет turn-end события `Stop`, поэтому встроенные `require-*-before-stop` никогда не срабатывают для неё (неприменимо, не сломано); `instruct` снижается до allow-with-logged-note (нет канала дополнительного контекста); и редакция выходных секретов (`sanitize-*`) не может переписать выход инструмента через shell-hook контракт. Hermes — также **offline audit** источник — панель управления читает её сессии шлюза напрямую из `~/.hermes/state.db`.
+  - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**только пользовательский уровень** — у OpenClaw нет проектной/локальной конфигурации). Как Hermes, OpenClaw является self-hosted **шлюзом** с поддержкой нескольких каналов, поэтому одна установка перехватывает вызовы инструментов со всех каналов и внутренних субагентов. Реализация работает через **встроенные plugin hooks** OpenClaw (её file-based internal hooks только для наблюдения и не могут блокировать), поэтому — как OpenCode/Pi — failproofai поставляет статический пакет `openclaw-plugin/`, который async-запускает binary failproofai и переводит вердикт. Install регистрирует поставленную директорию плагина в `openclaw.json`'s `plugins.load.paths[]` и включает её под `plugins.entries.failproofai` (с `hooks.allowConversationAccess: true`, требуется для raw-conversation hooks). Оценивающий выпускает плоский `{permission, reason}` вердикт и шим маппирует его в собственную форму возврата каждого hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), и `before_agent_finalize → {action:"revise", reason}` (**Stop** — real turn-end gate, поэтому встроенные `require-*-before-stop` **реализуют** на OpenClaw, в отличие от Hermes). События и имена инструментов канонизируются на стороне binary через `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …), поэтому встроенные политики срабатывают без изменений; шим fails open при любой ошибке spawn/parse/timeout. OpenClaw — также **offline audit** источник — панель управления читает его JSONL сессии в `~/.openclaw/agents/<agentId>/sessions/<uuid>.jsonl`.
+  - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (пользователь), `<cwd>/.factory/hooks.json` (проект) — у Factory нет локального уровня. droid поставляет систему внешних hook-команд в стиле Claude, но с двумя особенностями, проверенными live против droid v0.171.0: (1) имена событий находятся на **верхнем уровне** `hooks.json` — нет **обёртки `"hooks"`** (droid её отклоняет); инструментальные события (`PreToolUse`/`PostToolUse`) имеют `"matcher": "*"`, non-инструментальные события его пропускают. (2) Deny управляется hook **exit code 2 + stderr**, а не JSON решением — ветвь `factory` оценивающего возвращает exit 2 для tool/prompt событий и `{decision:"block", reason}` только на turn-end событии `Stop` (единственный force-retry канал droid). События уже в PascalCase (нет event map) и payload в Claude snake_case; только имена инструментов канонизируются через `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory — также **offline audit** источник — панель управления читает её on-disk JSONL сессии в `~/.factory/sessions/<encoded-cwd>/<sessionId>.jsonl`.
+  - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (пользователь), `<cwd>/.devin/config.json` (проект) — у Devin нет локального уровня. Devin — это **чистый Claude-клон**, проверенный live против devin v3000.1.27: он использует стандартную Claude схему с обёрткой `"hooks"` (записи merge-preserving, поэтому другие ключи файла конфигурации — `org_id`, `theme_mode`, … — остаются), уже-PascalCase имена событий (нет event map, нет ветви обработчика) и Claude snake_case stdin payload (нет нормализации). Ветвь `devin` оценивающего отклоняет с `{"decision":"block","reason"}` JSON на stdout при exit 0 для **каждого** события (проверено — блокировка переопределила `--permission-mode dangerous`); на turn-end событии `Stop` причина содержит обязательный force-retry текст действия, поэтому встроенные `require-*-before-stop` реализуют. Только имена инструментов канонизируются через `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` уже канонический). Devin — также **offline audit** источник — панель управления читает его SQLite сессии в `~/.local/share/devin/cli/sessions.db` (каждая строка `sessions` содержит реальный `working_directory`, поэтому сессии группируются по проекту cwd, как Claude).
+  - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (пользователь), `<cwd>/.agents/hooks.json` (проект) — у Antigravity нет локального уровня. В отличие от Factory/Devin, Antigravity имеет **собственный** контракт (не Claude-клон), проверенный live против agy v1.1.2. `hooks.json` использует **named-hook** схему: верхнеуровневый ключ — это имя hook'а (*`"failproofai"`*) чьё значение — событие→handlers map — инструментальные события (`PreToolUse`/`PostToolUse`) оборачивают handlers в `{matcher:"*", hooks:[…]}`, тогда как `PreInvocation`/`Stop` — это **плоские** arrays handlers (другие named hooks сохраняются). Stdin payload — это **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai нормализует его в snake_case перед запуском политик и маппирует PascalCase аргументы `run_command` (`CommandLine`/`Cwd`) через `ANTIGRAVITY_TOOL_INPUT_MAP`. Ветвь `antigravity` оценивающего использует собственные формы ответов Antigravity: `{decision:"deny", reason}` блокирует tool/prompt (exit 0), `{decision:"continue", reason}` на turn-end событии `Stop` re-входит в loop (поэтому встроенные `require-*-before-stop` реализуют), и `{injectSteps:[{ephemeralMessage}]}` инжектит инструкцию на `PreInvocation` (→ `UserPromptSubmit`). Имена инструментов канонизируются через `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity — также **offline audit** источник — панель управления читает его plain-JSONL транскрипты в `~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/transcript_full.jsonl` (индекс разговора в `conversation_summaries.db`).
+  - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (пользователь), `<cwd>/.agents/plugins/failproofai/hooks/hooks.json` (проект) — у Goose нет локального уровня. Реализация использует **hooks** систему Goose, кроссагентную **Open Plugins** спецификацию: installer просто размещает `failproofai` plugin dir и Goose auto-открывает его при запуске (self-регистрируя его в `~/.config/goose/config.yaml`). `hooks.json` использует Open Plugins схему **с** верхнеуровневой обёрткой `"hooks"`, и matcher — **опущен** на каждом событии — голая `"*"` — это невалидный regex, который ничего не совпадает (проверено live против goose v1.43.0). Имена событий уже PascalCase (нет event map); stdin payload использует `event`/`working_dir`, которые обработчик нормализует в `hook_event_name`/`cwd`. Ветвь `goose` оценивающего отклоняет с `{"decision":"block","reason"}` JSON на stdout при exit 0, honoured на событии **`PreToolUse`** только (поставляется в goose ≥ v1.37.0) — которое срабатывает для shell tool **и внутри делегированных субагентов**, поэтому это единственная достаточная point отклонения; любая другая ошибка hook fails **open**. У Goose нет события **`Stop`**, поэтому встроенные `require-*-before-stop` не применяются (как с Hermes). Имена инструментов канонизируются через `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) и ключи path через `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose — также **offline audit** источник — панель управления читает его SQLite сессии в `~/.local/share/goose/sessions/sessions.db` (каждая строка `sessions` содержит реальный `working_dir`, поэтому сессии группируются по проекту cwd, как Devin; `--no-session` scratch runs отфильтрованы).
+- **`policies-config.json`** — сообщает failproofai, какие политики оценивать и с какими параметрами (общее для всех agent CLI)
+
+Передайте `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` для выбора конкретного агента (пробелом-разделённый или повторённый для любого подмножества):
+
+```bash
+failproofai policies --install --cli codex --scope project
+failproofai policies --install --cli copilot --scope project
+failproofai policies --install --cli cursor --scope project
+failproofai policies --install --cli opencode --scope project
+failproofai policies --install --cli pi --scope project
+failproofai policies --install --cli hermes --scope user
+failproofai policies --install --cli openclaw --scope user
+failproofai policies --install --cli factory --scope project
+failproofai policies --install --cli devin --scope project
+failproofai policies --install --cli antigravity --scope project
+failproofai policies --install --cli goose --scope project
+failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose
+```
+
+Когда `--cli` опущен, `failproofai` обнаруживает какие agent CLI установлены (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`):
+
+- **Один CLI обнаружен** — автоматически выбирает этот CLI без запроса.
+- **Несколько CLI обнаружено** в интерактивном терминале — показывает prompt одиночного выбора со стрелками, сгруппированный в секцию `Detected (N)` (с aggregate row `Install for all N detected` + каждый обнаруженный CLI отдельно) и секцию `Not installed (M) · install hooks ahead of time`, выводящую каждый необнаруженный поддерживаемый CLI как forward-install опцию (↑↓ для движения, Enter для выбора, ^C для выхода). Flow uninstall показывает только секцию Detected.
+- **Несколько CLI обнаружено** в non-interactive запуске (CI, нет TTY) — устанавливает для всех обнаруженных CLI без запроса.
+- **Ничего не обнаружено** — fallback на `claude`, с предупреждением, что ни один agent binary не найден в PATH; hook команда всё ещё записывается, поэтому она активируется как только вы установите один.
+
+Вы можете редактировать `policies-config.json` напрямую в любое время; изменения вступают в силу немедленно при следующем событии hook, без необходимости перезагрузки.
+
+---
+
+## Пример: конфигурация на уровне проекта с командными значениями по умолчанию
+
+Зафиксируйте `.failproofai/policies-config.json` в вашем репо:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Затем каждый разработчик может создать `.failproofai/policies-config.local.json` (исключённый из Git) для личных переопределений без влияния на товарищей.