Конфигурация

​

Области действия конфигурации

​

Правила слияния

project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← дедублицированное объединение

project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← побеждает project, global игнорируется

project:  (нет записи block-sudo)
local:    (нет записи block-sudo)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← переходит на global

​

Формат файла конфигурации

{
  "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

​

policyParams

​

hint (сквозной)

{
  "policyParams": {
    "block-force-push": {
      "hint": "Попробуйте создать новую ветку вместо этого."
    },
    "block-sudo": {
      "allowPatterns": ["sudo apt-get"],
      "hint": "Используйте apt-get непосредственно без sudo."
    },
    "custom/my-policy": {
      "hint": "Сначала попросите одобрение у пользователя."
    }
  }
}

​

customPoliciesPath

​

Политики на основе конвенций

​

llm

{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​

Управление конфигурацией из CLI

• Параметры 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 не имеет локальной области. Записи хука используют поля команды bash/powershell Copilot с ключом timeoutSec; файл содержит маркер уровня верхнего уровня version: 1. Поддержка Copilot CLI находится в beta, пока мы проверяем схему записи events.jsonl (которую не указывает официальная документация) против более реальных сессий.
  • Cursor Agent (beta): ~/.cursor/hooks.json (пользователь), <cwd>/.cursor/hooks.json (проект) — Cursor не имеет локальной области. Записи хука используют форму в стиле Claude {type, command, timeout} (без разделения bash/powershell), но сохраняются под ключами событий в camelCase (preToolUse, beforeSubmitPrompt, …) в плоском массиве согласно схеме хуков Cursor; файл содержит маркер уровня верхнего уровня version: 1. Обработчик канонизирует camelCase → PascalCase через CURSOR_EVENT_MAP, поэтому существующие встроенные политики срабатывают без изменений. Поддержка Cursor Agent находится в beta, пока мы проверяем формат записи записей Cursor на диске (не указан в официальной документации) против более реальных установок.
  • OpenCode (beta): ~/.config/opencode/opencode.json + ~/.config/opencode/plugins/failproofai.mjs (пользователь), <cwd>/.opencode/opencode.json + <cwd>/.opencode/plugins/failproofai.mjs (проект) — OpenCode не имеет локальной области. В отличие от других шести CLI, OpenCode имеет отсутствие системы внешних командных хуков: он загружает встроенные плагины JS/TS, явно зарегистрированные через массив plugin: [] в opencode.json (автообнаружение из .opencode/plugins/ не является способом загрузки плагинов в opencode v1.14.33). Установка помещает небольшой созданный шим плагина, который вызывает двоичный файл failproofai в подпроцессе и переводит ответ JSON двоичного файла в семантику плагина: throw new Error() для отклонения события инструмента (отменяет вызов инструмента), client.session.prompt(...) для instruct И для отклонения Stop / SubagentStop (отправляет причину отклонения в качестве следующего сообщения пользователя — единственный канал принудительного повторного попытки, так как session.idle доступна только для уведомлений и выброс из неё не работает), и no-op для allow. Шим канонизирует как имена инструментов (нижний регистр → PascalCase через OPENCODE_TOOL_MAP), так и ключи аргументов инструмента (camelCase → snake_case через OPENCODE_TOOL_INPUT_MAP для Read / Write / Edit, например filePath → file_path, oldString → old_string) перед передачей двоичному файлу, поэтому встроенные функции проверки пути, такие как block-read-outside-cwd, block-env-files и block-secrets-write, срабатывают без изменений на вызовах инструментов OpenCode. Сессии живут в БД SQLite OpenCode в ~/.local/share/opencode/opencode.db; средство просмотра сессий панели управления читает их через opencode db --format json и opencode export <id>. Поддержка OpenCode находится в beta, пока мы проверяем поведение в разных версиях и против более реальных сессий. См. документацию плагинов OpenCode.
  • Pi (beta): ~/.pi/agent/settings.json (пользователь), <cwd>/.pi/settings.json (проект) — Pi не имеет локальной области. Pi загружает пакеты расширений TypeScript при запуске; файл параметров — это плоский массив строк {"packages": ["./relative/path", …]}. failproofai записывает единственную запись массива пакетов, указывающую на свой встроенный каталог pi-extension/. Расширение внутри подписывается на события tool_call / user_bash / input / session_start Pi и запускает failproofai --hook <Event> --cli pi; обработчик канонизирует underscore_lower_snake_case → PascalCase через PI_EVENT_MAP, поэтому существующие встроенные политики срабатывают без изменений. Аргументы входа инструмента также канонизируются через PI_TOOL_INPUT_MAP (Read / Write / Edit Pi доставляют path вместо file_path; отображение верхнего уровня ключа позволяет block-env-files и block-secrets-write срабатывать — block-read-outside-cwd уже имел fallback path). Поддержка Pi находится в beta, пока стабилизируются API расширений Pi и макет журнала сессий.
  • Gemini CLI (beta): ~/.gemini/settings.json (пользователь), <cwd>/.gemini/settings.json (проект) — Gemini не имеет локальной области (документирует область system в /etc/gemini-cli/settings.json, которую failproofai не предоставляет). Записи хука используют форму Claude {type, command, timeout}, завёрнутую в схему сопоставителя Gemini {matcher, hooks: [...]} с matcher: "*" по умолчанию. События — PascalCase (SessionStart, BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection, BeforeTool, AfterTool, PreCompress, Notification, SessionEnd); обработчик отображает на канонические имена Claude через GEMINI_EVENT_MAP. Имена инструментов — snake_case (run_shell_command, read_file, write_file, replace, …) — обработчик канонизирует через GEMINI_TOOL_MAP, поэтому существующие встроенные политики срабатывают без изменений. Оценка политики выдаёт плоскую форму Gemini {decision: "deny", reason} (предпочтительно согласно “Golden Rule” Gemini контракт exit-0), {hookSpecificOutput: {hookEventName, additionalContext}} для внедрения контекста на BeforeAgent / AfterTool / SessionStart и {decision: "block", reason} на AfterAgent для семантики принудительного повторного попытки. Поддержка Gemini CLI находится в beta, пока мы расширяем реальное покрытие. См. документацию хуков Gemini CLI.
• policies-config.json — указывает failproofai, какие политики оценивать и с какими параметрами (общее для всех CLI агентов)

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 gemini --scope project
failproofai policies --install --cli claude codex copilot cursor opencode pi gemini

• Один CLI обнаружен — автоматически выбирает этот CLI без запроса.
• Несколько CLI обнаружены в интерактивном терминале — показывает запрос одиночного выбора со стрелками, сгруппированный в раздел Detected (N) (с агрегированной строкой Install for all N detected + каждый обнаруженный CLI отдельно) и раздел Not installed (M) · install hooks ahead of time, перечисляющий каждый необнаруженный поддерживаемый CLI как опцию предварительной установки (↑↓ для перемещения, Enter для выбора, ^C для выхода). Поток удаления показывает только раздел Detected.
• Несколько CLI обнаружены в неинтерактивном запуске (CI, нет TTY) — устанавливает для всех обнаруженных CLI без запроса.
• Ничего не обнаружено — возвращается к claude, с предупреждением, что двоичный файл агента не найден в PATH; команда хука всё ещё записывается, поэтому она активируется, как только вы установите один.

​

Пример: конфигурация уровня проекта с командными значениями по умолчанию

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}