設定

​

設定スコープ

​

マージルール

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 マーカーが付きます。Copilot CLI サポートは、公開ドキュメントに仕様が記載されていない events.jsonl レコードスキーマを実際のセッションで検証中のため、ベータ版です。
  • Cursor Agent (beta)：~/.cursor/hooks.json（ユーザー）、<cwd>/.cursor/hooks.json（プロジェクト） — Cursor には local スコープがありません。フックエントリーは Claude 形式の {type, command, timeout} を使用しますが、Cursor の hooks スキーマ に従い、フラット配列内の camelCase イベントキー（preToolUse、beforeSubmitPrompt など）に保存され、ファイルにはトップレベルの version: 1 マーカーが付きます。ハンドラーは CURSOR_EVENT_MAP を介して camelCase → PascalCase に正規化するため、既存の組み込みポリシーはそのまま動作します。Cursor Agent サポートは、公開ドキュメントに記載されていない Cursor のディスク上トランスクリプト形式を実際のインストールで検証中のため、ベータ版です。
  • OpenCode (beta)：~/.config/opencode/opencode.json + ~/.config/opencode/plugins/failproofai.mjs（ユーザー）、<cwd>/.opencode/opencode.json + <cwd>/.opencode/plugins/failproofai.mjs（プロジェクト） — OpenCode には local スコープがありません。他の6つの 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 は通知専用でスローは no-op のため、強制リトライの唯一のチャンネル）、allow には no-op。シムはツール名（小文字 → 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 のツール呼び出しでもそのまま動作します。セッションは ~/.local/share/opencode/opencode.db の OpenCode の SQLite DB に保存され、ダッシュボードのセッションビューアーは opencode db --format json と opencode export <id> を介して読み取ります。OpenCode サポートは、バージョン間の動作と実際のセッションの検証中のため、ベータ版です。OpenCode plugins ドキュメントを参照してください。
  • 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 を介して underscore_lower_snake_case → PascalCase に正規化するため、既存の組み込みポリシーはそのまま動作します。ツール入力引数も PI_TOOL_INPUT_MAP 経由で正規化されます（Pi の Read / Write / Edit は file_path ではなく path を渡します。トップレベルキーのマッピングにより block-env-files と block-secrets-write が動作します — block-read-outside-cwd にはすでに path フォールバックがありました）。Pi サポートは、Pi の拡張 API とセッションログのレイアウトが安定するまでベータ版です。
  • Gemini CLI (beta)：~/.gemini/settings.json（ユーザー）、<cwd>/.gemini/settings.json（プロジェクト） — Gemini には local スコープがありません（failproofai が公開していない /etc/gemini-cli/settings.json の system スコープがドキュメントに記載されています）。フックエントリーは Claude の {type, command, timeout} 形式を Gemini の {matcher, hooks: [...]} マッチャースキーマでラップし、デフォルトで matcher: "*" を使用します。イベントは PascalCase（SessionStart、BeforeAgent、AfterAgent、BeforeModel、AfterModel、BeforeToolSelection、BeforeTool、AfterTool、PreCompress、Notification、SessionEnd）で、ハンドラーは GEMINI_EVENT_MAP を介して Claude の正規名にマッピングします。ツール名は snake_case（run_shell_command、read_file、write_file、replace など）で、ハンドラーは GEMINI_TOOL_MAP を介して正規化するため、既存の組み込みポリシーはそのまま動作します。ポリシーエバリュエーターは Gemini のフラットな {decision: "deny", reason} 形式（Gemini の「Golden Rule」exit-0 コントラクトに従い推奨）、BeforeAgent / AfterTool / SessionStart のコンテキスト注入には {hookSpecificOutput: {hookEventName, additionalContext}}、AfterAgent の強制リトライには {decision: "block", reason} を出力します。Gemini CLI サポートは、実世界のカバレッジを拡大しながらベータ版です。Gemini CLI hooks ドキュメントを参照してください。
• 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

• 1つの CLI を検出 — プロンプトなしでその CLI を自動選択します。
• インタラクティブなターミナルで複数の CLI を検出 — 矢印キーで操作する単一選択プロンプトを表示します。Detected (N) セクション（Install for all N detected の集約行と検出された各 CLI が個別に表示）と、Not installed (M) · install hooks ahead of time セクション（未検出のサポート済み CLI が事前インストールオプションとして表示）に分かれています（↑↓ で移動、Enter で選択、^C で終了）。アンインストールフローでは Detected セクションのみが表示されます。
• 非インタラクティブな実行（CI、TTY なし）で複数の CLI を検出 — プロンプトなしですべての検出済み CLI にインストールします。
• 検出なし — claude にフォールバックし、PATH にエージェントバイナリが見つからなかったという警告を表示します。フックコマンドは引き続き書き込まれるため、CLI をインストールした時点で有効になります。

​

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

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