設定

​

設定スコープ

​

マージルール

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": "Try creating a fresh branch instead."
    },
    "block-sudo": {
      "allowPatterns": ["sudo apt-get"],
      "hint": "Use apt-get directly without sudo."
    },
    "custom/my-policy": {
      "hint": "Ask the user for approval first."
    }
  }
}

​

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 には local スコープがありません
  • GitHub Copilot CLI (beta): ~/.copilot/hooks/failproofai.json（ユーザー）、<cwd>/.github/hooks/failproofai.json（プロジェクト）— Copilot には local スコープがありません。フックエントリは Copilot の OS キー付き bash/powershell コマンドフィールドと timeoutSec を使用し、ファイルにはトップレベルの version: 1 マーカーが付きます。events.jsonl レコードスキーマ（公開ドキュメントに記載なし）を実際の使用環境で検証中のため、Copilot CLI のサポートはベータ版です。
  • Cursor Agent (beta): ~/.cursor/hooks.json（ユーザー）、<cwd>/.cursor/hooks.json（プロジェクト）— Cursor には local スコープがありません。フックエントリは Claude 形式の {type, command, timeout} を使用しますが、Cursor のフックスキーマに従いキャメルケースのイベントキー（preToolUse、beforeSubmitPrompt など）のフラット配列として保存され、ファイルにはトップレベルの version: 1 マーカーが付きます。ハンドラーは CURSOR_EVENT_MAP を通じてキャメルケース → PascalCase に正規化するため、既存の組み込みポリシーはそのまま動作します。Cursor のトランスクリプトのオンディスクフォーマット（公開ドキュメントに未記載）を実際の環境で検証中のため、Cursor Agent のサポートはベータ版です。
  • OpenCode (beta): ~/.config/opencode/opencode.json + ~/.config/opencode/plugins/failproofai.mjs（ユーザー）、<cwd>/.opencode/opencode.json + <cwd>/.opencode/plugins/failproofai.mjs（プロジェクト）— OpenCode には local スコープがありません。他の5つの CLI とは異なり、OpenCode には外部コマンドフックシステムがありません。opencode.json の plugin: [] 配列で明示的に登録された JS/TS プラグインをインプロセスでロードします（.opencode/plugins/ からの自動検出は opencode v1.14.33 でのプラグインロード方法ではありません）。インストール時に小さな生成プラグインシムが配置され、failproofai バイナリをサブプロセスで呼び出し、バイナリの Claude 形式 JSON レスポンスをプラグインセマンティクスに変換します：ツールイベントの deny には throw new Error()（ツール呼び出しをキャンセル）、instruct および Stop / SubagentStop の deny には client.session.prompt(...)（deny の理由を次のユーザーメッセージとして送信 — session.idle が通知専用で例外をスローしても無効なため、強制リトライの唯一のチャネル）、allow には no-op を使用します。シムはツール名（小文字 → OPENCODE_TOOL_MAP を通じた PascalCase）とツール入力引数のキー（OPENCODE_TOOL_INPUT_MAP を通じたキャメルケース → スネークケース：Read / Write / Edit の filePath → file_path、oldString → old_string など）を正規化してからバイナリに転送するため、block-read-outside-cwd、block-env-files、block-secrets-write などのパスチェック組み込みポリシーは OpenCode のツール呼び出しでもそのまま動作します。セッションは ~/.local/share/opencode/opencode.db の OpenCode の SQLite DB に保存され、ダッシュボードのセッションビューアーは opencode db --format json と opencode export <id> を通じて読み取ります。バージョン間の動作や実際の使用環境での検証中のため、OpenCode のサポートはベータ版です。OpenCode プラグインドキュメントを参照してください。
  • Pi (beta): ~/.pi/agent/settings.json（ユーザー）、<cwd>/.pi/settings.json（プロジェクト）— Pi には local スコープがありません。Pi は起動時に TypeScript 拡張パッケージをロードします。設定ファイルはフラットな文字列配列 {"packages": ["./relative/path", …]} です。failproofai はバンドルされた pi-extension/ ディレクトリを指す単一の packages 配列エントリを書き込みます。拡張機能は内部で Pi の tool_call / user_bash / input / session_start イベントを購読し、failproofai --hook <Event> --cli pi をシェルアウトします。ハンドラーは PI_EVENT_MAP を通じてアンダースコア付き小文字スネークケース → PascalCase に正規化するため、既存の組み込みポリシーはそのまま動作します。ツール入力引数も PI_TOOL_INPUT_MAP を通じて正規化されます（Pi の Read / Write / Edit は file_path ではなく path を使用。トップレベルキーのマッピングにより block-env-files と block-secrets-write が動作します — block-read-outside-cwd にはすでに path フォールバックがあります）。Pi の拡張 API とセッションログのレイアウトが安定化するまで Pi のサポートはベータ版です。
  • Hermes (hermes-agent): ~/.hermes/config.yaml（ユーザースコープのみ — Hermes にはプロジェクト/ローカル設定がありません）。Hermes は Slack/Telegram のゲートウェイであるため、1回のインストールでSlack/Telegram/cli/cron など全プラットフォームからのツール呼び出しと内部サブエージェントを傍受します。フックエントリは Hermes のスネークケースイベント（pre_tool_call / post_tool_call / on_session_start / on_session_end / subagent_stop）をキーとする hooks: マップ下の {command, timeout} ペア（タイムアウトは秒単位）です。ハンドラーは HERMES_EVENT_MAP でイベントを、HERMES_TOOL_MAP でツール名を正規化するため、組み込みポリシーはそのまま動作します。設定はコメントを保持する YAML Document のラウンドトリップで編集されるため、オペレーターの他の設定は保持されます。インストール時に hooks_auto_accept: true が設定されるため、ヘッドレスゲートウェイ（TTY なし）は同意プロンプトなしでフックを実行します。評価器は Hermes の {"decision":"block","reason"} stdout 契約を出力します（Hermes は終了コードを無視）。制限事項: Hermes にはターン終了の Stop イベントがないため、require-*-before-stop 組み込みポリシーは動作しません（非適用、バグではありません）。instruct は allow-with-logged-note に降格します（追加コンテキストチャネルなし）。出力シークレットのリダクション（sanitize-*）はシェルフックの契約上ツール出力を書き換えられません。Hermes はオフライン監査ソースでもあり、ダッシュボードはゲートウェイセッションを ~/.hermes/state.db から直接読み取ります。
• 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 hermes --scope user
failproofai policies --install --cli claude codex copilot cursor opencode pi

• CLI が1つ検出された場合 — プロンプトなしでその 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 にインストールします。
• 何も検出されない場合 — エージェントバイナリが PATH に見つからないという警告とともに claude にフォールバックします。フックコマンドは書き込まれるため、インストール後すぐに有効になります。

​

例：チームデフォルトを含むプロジェクトレベルの設定

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