failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,264 @@
+---
+title: 設定
+description: "設定ファイルの形式、3段階スコープシステム、マージルール"
+icon: gear
+---
+
+failproofai はJSON設定ファイルを使用して、どのポリシーを有効にするか、その動作方法、カスタムポリシーの読み込み元を制御します。設定はチームと共有しやすい設計になっています。リポジトリにコミットすれば、全開発者が同じエージェント安全ネットを利用できます。
+
+---
+
+## 設定スコープ
+
+優先順位の高い順に評価される3つの設定スコープがあります。
+
+| スコープ | ファイルパス | 目的 |
+|-------|-----------|---------|
+| **project** | `.failproofai/policies-config.json` | リポジトリ単位の設定。バージョン管理にコミット |
+| **local** | `.failproofai/policies-config.local.json` | 個人用リポジトリ単位のオーバーライド。gitignore対象 |
+| **global** | `~/.failproofai/policies-config.json` | 全プロジェクト共通のユーザーレベルデフォルト |
+
+failproofai がフックイベントを受け取ると、現在の作業ディレクトリに存在する3つのファイルをすべて読み込んでマージします。
+
+### マージルール
+
+**`enabledPolicies`** — 3つのスコープの和集合。いずれかのレベルで有効になっているポリシーはアクティブになります。
+
+```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` で表示されるポリシー識別子と完全に一致している必要があります。全リストは[組み込みポリシー](/ja/built-in-policies)を参照してください。
+
+`enabledPolicies` に含まれていないポリシーは、`policyParams` にエントリがあっても無効になります。
+
+### `policyParams`
+
+型: `Record<string, Record<string, unknown>>`
+
+ポリシーごとのパラメータオーバーライド。外側のキーがポリシー名、内側のキーはポリシー固有のものです。各ポリシーで使用可能なパラメータは[組み込みポリシー](/ja/built-in-policies)に記載されています。
+
+パラメータを持つポリシーで指定がない場合、ポリシーの組み込みデフォルト値が使用されます。`policyParams` を設定しないユーザーは以前のバージョンと同じ動作になります。
+
+ポリシーのパラメータブロック内の未知のキーは、フック発火時には静かに無視されますが、`failproofai policies` 実行時に警告として表示されます。
+
+#### `hint`（共通オプション）
+
+型: `string`（任意）
+
+ポリシーが `deny` または `instruct` を返したときに、理由に付加されるメッセージです。ポリシー自体を変更せずに Claude に具体的なガイダンスを提供するために使用します。
+
+組み込み、カスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）など、あらゆるポリシータイプで動作します。
+
+```json
+{
+  "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."
+    }
+  }
+}
+```
+
+`block-force-push` が拒否すると、Claude には次のように表示されます: *「Force-pushing is blocked. Try creating a fresh branch instead.」*
+
+文字列以外の値や空文字列は静かに無視されます。`hint` が設定されていない場合は動作が変わらず（後方互換性あり）。
+
+### `customPoliciesPath`
+
+型: `string`（絶対パス）
+
+カスタムフックポリシーを含むJavaScriptファイルへのパス。`failproofai policies --install --custom <path>` により自動設定されます（パスは格納前に絶対パスに解決されます）。
+
+ファイルはフックイベントのたびに新たに読み込まれます。キャッシュはありません。作成方法の詳細は[カスタムポリシー](/ja/custom-policies)を参照してください。
+
+### 規約ベースのポリシー
+
+明示的な `customPoliciesPath` に加えて、failproofai は `.failproofai/policies/` ディレクトリからポリシーファイルを自動検出して読み込みます。
+
+| レベル | ディレクトリ | スコープ |
+|-------|-----------|-------|
+| プロジェクト | `.failproofai/policies/` | バージョン管理でチームと共有 |
+| ユーザー | `~/.failproofai/policies/custom-policies/` | 個人用。全プロジェクトに適用 |
+
+<Note>
+  ユーザーレベルのディレクトリは、ホームディレクトリの再編成により1階層下に移動しました。古い `~/.failproofai/policies/` に残っているファイルは、アップグレード後に初めて `failproofai` コマンドを実行すると `custom-policies/` に自動移動され、移動されたファイルがコマンド出力に表示されます。
+</Note>
+
+**ファイルのマッチング:** `*policies.{js,mjs,ts}` にマッチするファイルのみ読み込まれます（例: `security-policies.mjs`、`workflow-policies.js`）。ディレクトリ内のその他のファイルは無視されます。
+
+**設定不要:** 規約ポリシーは `policies-config.json` へのエントリが不要です。ディレクトリにファイルを置くだけで、次のフックイベント時に自動的に読み込まれます。
+
+**ユニオン読み込み:** プロジェクトとユーザーの両方の規約ディレクトリがスキャンされます。両レベルのマッチするファイルがすべて読み込まれます（`customPoliciesPath` の先着スコープ優先とは異なります）。
+
+詳細と例については[カスタムポリシー](/ja/custom-policies)を参照してください。
+
+### `llm`
+
+型: `object`（任意）
+
+AI呼び出しを行うポリシー向けのLLMクライアント設定。多くのセットアップでは不要です。
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## CLIからの設定管理
+
+`policies --install` および `policies --uninstall` コマンドはエージェントCLIのフック設定ファイル（フックエントリポイント）に書き込みますが、`policies-config.json` は直接管理するファイルです。この2つは別物です:
+
+- **エージェント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 _(ベータ版)_**: `~/.copilot/hooks/failproofai.json`（ユーザー）、`<cwd>/.github/hooks/failproofai.json`（プロジェクト）— Copilot には `local` スコープがありません。フックエントリはCopilotのOS別 `bash`/`powershell` コマンドフィールドと `timeoutSec` を使用し、ファイルはトップレベルに `version: 1` マーカーを持ちます。Copilot CLIのサポートは**ベータ版**です。公開ドキュメントに記載のない `events.jsonl` レコードスキーマを実際のセッションで検証中です。**VS Code Copilot Chat エージェントモード（Preview）** は、`.github/hooks/*.json`、`~/.copilot/hooks/*.json`、`~/.claude/settings.json`（`chat.hookFilesLocations` 設定で制御）からフック設定を読み込み、`{hookSpecificOutput:{permissionDecision:"deny",…}}` の同じClaude形式コントラクトを使用します。`failproofai policies --install --cli copilot`（または `--cli claude`）が書き込む正確なパスと一致するため、**VS Codeエージェントモードでも別途 `vscode` インテグレーションは不要**です（VS Codeのディスカバリーログで確認済み）。
+  - **Cursor Agent _(ベータ版)_**: `~/.cursor/hooks.json`（ユーザー）、`<cwd>/.cursor/hooks.json`（プロジェクト）— Cursor には `local` スコープがありません。フックエントリはClaude形式の `{type, command, timeout}` を使用しますが（`bash`/`powershell` の分割なし）、Cursorの[フックスキーマ](https://cursor.com/docs/hooks)に従いキャメルケースのイベントキー（`preToolUse`、`beforeSubmitPrompt` など）の下にフラット配列として格納されます。ファイルはトップレベルに `version: 1` マーカーを持ちます。ハンドラーは `CURSOR_EVENT_MAP` でキャメルケース → パスカルケースに正規化するため、既存の組み込みポリシーはそのまま動作します。Cursor Agentのサポートは**ベータ版**です。公開ドキュメントに記載のないCursorのトランスクリプトのオンディスク形式を実際のインストールで検証中です。
+  - **OpenCode _(ベータ版)_**: `~/.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レスポンスをプラグインセマンティクスに変換します: ツールイベント拒否に `throw new Error()`（ツール呼び出しをキャンセル）、instruct および `Stop` / `SubagentStop` 拒否に `client.session.prompt(...)`（拒否理由を次のユーザーメッセージとして送信 — `session.idle` は通知のみでスローしても無効なため、唯一の強制再試行チャンネル）、allow には何もしない。シムはツール名（小文字 → `OPENCODE_TOOL_MAP` でパスカルケース）とツール入力の引数キー（`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データベースに保存されます。ダッシュボードのセッションビューアーは `opencode db --format json` と `opencode export <id>` を通じて読み込みます。OpenCodeのサポートは**ベータ版**です。複数バージョンおよび実際のセッションでの動作を検証中です。[OpenCode pluginsドキュメント](https://opencode.ai/docs/plugins/)を参照してください。
+  - **Pi _(ベータ版)_**: `~/.pi/agent/settings.json`（ユーザー）、`<cwd>/.pi/settings.json`（プロジェクト）— Pi には `local` スコープがありません。Piは起動時にTypeScript拡張パッケージを読み込みます。設定ファイルはフラットな文字列配列 `{"packages": ["./relative/path", …]}` です。failproofai はバンドルされた `pi-extension/` ディレクトリを指すパッケージ配列エントリを1つ書き込みます。拡張機能はPiの `tool_call` / `user_bash` / `input` / `session_start` イベントを内部でサブスクライブし、`failproofai --hook <Event> --cli pi` をシェルアウトで呼び出します。ハンドラーは `PI_EVENT_MAP` でアンダースコア小文字スネークケース → パスカルケースに正規化するため、既存の組み込みポリシーはそのまま動作します。ツール入力引数も `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とセッションログレイアウトが安定するまで**ベータ版**です。
+  - **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（ログ記録あり）に降格されます（追加コンテキストチャンネルなし）。出力シークレットの編集（`sanitize-*`）はシェルフックコントラクト上でツール出力を書き換えることができません。Hermesは**オフライン監査**ソースでもあります — ダッシュボードは `~/.hermes/state.db` からゲートウェイセッションを直接読み込みます。
+  - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json`（**ユーザースコープのみ** — OpenClawにはプロジェクト/ローカル設定がありません）。Hermesと同様に、OpenClawはセルフホスト型マルチチャンネル**ゲートウェイ**であるため、1回のインストールで全チャンネルと内部サブエージェントからのツール呼び出しを傍受します。エンフォースメントはOpenClawの**インプロセスプラグインフック**を通じて実行されます（ファイルベースの内部フックは観察のみで、ブロックできません）。そのためOpenCode/Piと同様に、failproofaiは静的な `openclaw-plugin/` パッケージを提供し、failproofaiバイナリを非同期でスポーンして判定を変換します。インストール時に `openclaw.json` の `plugins.load.paths[]` にプラグインディレクトリが登録され、`plugins.entries.failproofai`（`hooks.allowConversationAccess: true`、生のConversationフックに必要）で有効化されます。評価器はフラットな `{permission, reason}` 判定を出力し、シムはそれを各フックのネイティブ返却形式にマッピングします: `before_tool_call → {block:true, blockReason}`（**PreToolUse**）、`before_agent_run → {outcome:"block", reason}`（**UserPromptSubmit**）、`before_agent_finalize → {action:"revise", reason}`（**Stop** — 実際のターン終了ゲートであるため、Hermesとは異なり `require-*-before-stop` 組み込みポリシーが**有効**です）。イベントとツール名はバイナリ側で `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP`（`exec→Bash`、`read→Read` など）を通じて正規化されるため、組み込みポリシーはそのまま動作します。シムはスポーン/パース/タイムアウトエラーが発生した場合はフェイルオープンします。OpenClawは**オフライン監査**ソースでもあります — ダッシュボードは `~/.openclaw/agents/<agentId>/sessions/<uuid>.jsonl` のJSONLセッションを読み込みます。
+  - **Factory Droid (`droid`)**: `~/.factory/hooks.json`（ユーザー）、`<cwd>/.factory/hooks.json`（プロジェクト）— Factory には `local` スコープがありません。droid は Claude スタイルの外部コマンドフックシステムを搭載していますが、droid v0.171.0 で実際に確認された2つの固有の仕様があります: (1) イベント名は `hooks.json` の**トップレベル**に存在します — **`"hooks"` ラッパーはありません**（droid はラッパーがあると拒否します）。ツールイベント（`PreToolUse`/`PostToolUse`）は `"matcher": "*"` を持ち、非ツールイベントはそれを省略します。(2) 拒否はフック**終了コード2 + stderr**で駆動されます（JSONの決定ではありません）。評価器の `factory` ブランチはツール/プロンプトイベントに終了コード2を返し、ターン終了の `Stop` イベント（droidの唯一の強制再試行チャンネル）のみ `{decision:"block", reason}` を返します。イベントはすでにパスカルケースです（イベントマップなし）。ペイロードはClaude スネークケースです。ツール名のみ `FACTORY_TOOL_MAP`（`Execute→Bash`、`Create→Write`、`FetchUrl→WebFetch` など）で正規化されます。Factory は**オフライン監査**ソースでもあります — ダッシュボードは `~/.factory/sessions/<encoded-cwd>/<sessionId>.jsonl` のオンディスクJSONLセッションを読み込みます。
+  - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json`（ユーザー）、`<cwd>/.devin/config.json`（プロジェクト）— Devin には `local` スコープがありません。Devin は devin v3000.1.27 で実際に確認された**純粋なClaude クローン**です: 標準のClaude `"hooks"` ラッパースキーマ（書き込みはマージ保持方式のため、設定ファイルの他のキー — `org_id`、`theme_mode` など — が保持されます）、すでにパスカルケースのイベント名（イベントマップなし、ハンドラーブランチなし）、Claude スネークケースの stdin ペイロード（正規化なし）を使用します。評価器の `devin` ブランチは**全**イベントに対して終了コード0で `{"decision":"block","reason"}` JSONを stdout に出力して拒否します（確認済み — ブロックは `--permission-mode dangerous` をオーバーライドしました）。ターン終了の `Stop` イベントでは、`require-*-before-stop` 組み込みポリシーが有効になるよう理由に MANDATORY-ACTION 強制再試行の文言が含まれます。ツール名のみ `DEVIN_TOOL_MAP`（`exec→Bash`; `tool_input.command` はすでに標準形式）で正規化されます。Devin は**オフライン監査**ソースでもあります — ダッシュボードは `~/.local/share/devin/cli/sessions.db` のSQLiteセッションを読み込みます（各 `sessions` 行には実際の `working_directory` が含まれるため、セッションはClaude と同様にプロジェクトの作業ディレクトリでグループ化されます）。
+  - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json`（ユーザー）、`<cwd>/.agents/hooks.json`（プロジェクト）— Antigravity には `local` スコープがありません。Factory/Devin とは異なり、Antigravity は agy v1.1.2 で実際に確認された**独自のコントラクト**（Claude クローンではない）を持ちます。`hooks.json` は**名前付きフック**スキーマを使用します: トップレベルキーはフック*名*（`"failproofai"`）で、その値はイベント→ハンドラーマップです — ツールイベント（`PreToolUse`/`PostToolUse`）はハンドラーを `{matcher:"*", hooks:[…]}` にラップし、`PreInvocation`/`Stop` は**フラット**なハンドラー配列です（他の名前付きフックは保持されます）。stdin ペイロードは**キャメルケース protojson**（`toolCall:{name,args}`、`conversationId`、`workspacePaths`、`transcriptPath`）です — failproofai はポリシー実行前にスネークケースに正規化し、`run_command` のパスカルケース引数（`CommandLine`/`Cwd`）を `ANTIGRAVITY_TOOL_INPUT_MAP` でマッピングします。評価器の `antigravity` ブランチはAntigravity**独自**のレスポンス形式を使用します: `{decision:"deny", reason}` でツール/プロンプトをブロック（終了コード0）、`{decision:"continue", reason}` でターン終了の `Stop` にループを再開（そのため `require-*-before-stop` 組み込みポリシーが有効）、`{injectSteps:[{ephemeralMessage}]}` で `PreInvocation`（→ `UserPromptSubmit`）に命令を注入。ツール名は `ANTIGRAVITY_TOOL_MAP`（`run_command→Bash`、`view_file→Read` など）で正規化されます。Antigravity は**オフライン監査**ソースでもあります — ダッシュボードは `~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/transcript_full.jsonl` のプレーンJSONLトランスクリプトを読み込みます（会話インデックスは `conversation_summaries.db` に格納）。
+  - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json`（ユーザー）、`<cwd>/.agents/plugins/failproofai/hooks/hooks.json`（プロジェクト）— Goose には `local` スコープがありません。エンフォースメントはGooseの**フック**システム（クロスエージェントの**Open Plugins**仕様）を使用します: インストーラーは `failproofai` プラグインディレクトリを配置するだけで、Gooseは起動時に自動検出します（`~/.config/goose/config.yaml` に自己登録）。`hooks.json` はトップレベルに `"hooks"` ラッパーを持つOpen Pluginsスキーマを使用し、マッチャーは全イベントで**省略**されています — 裸の `"*"` は何にもマッチしない無効な正規表現です（goose v1.43.0 で実際に確認）。イベント名はすでにパスカルケースです（イベントマップなし）。stdin ペイロードは `event`/`working_dir` を使用し、ハンドラーが `hook_event_name`/`cwd` に正規化します。評価器の `goose` ブランチは終了コード0で `{"decision":"block","reason"}` JSONを stdout に出力して拒否し、**`PreToolUse`** イベントのみで有効です（goose ≥ v1.37.0 で搭載）— シェルツール**および委任されたサブエージェント内**で発火するため、単一の十分な拒否ポイントです。その他のフックエラーはフェイルオープンします。Gooseには**`Stop` イベントがない**ため、`require-*-before-stop` 組み込みポリシーは適用されません（Hermesと同様）。ツール名は `GOOSE_TOOL_MAP`（`shell→Bash`、`write→Write`、`todo__todo_write→TodoWrite` など）で、パスキーは `GOOSE_TOOL_INPUT_MAP`（`path`/`source` → `file_path`）で正規化されます。Goose は**オフライン監査**ソースでもあります — ダッシュボードは `~/.local/share/goose/sessions/sessions.db` のSQLiteセッションを読み込みます（各 `sessions` 行には実際の `working_dir` が含まれるため、セッションはDevin と同様にプロジェクトの作業ディレクトリでグループ化されます。`--no-session` のスクラッチ実行はフィルタリングされます）。
+- **`policies-config.json`** — どのポリシーを評価するか、どのパラメータで評価するかをfailproofaiに指示します（全エージェント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` はインストールされているエージェント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`）:
+
+- **1つのCLIを検出** — プロンプトなしでそのCLIを自動選択します。
+- **複数のCLIを検出**（インタラクティブターミナル） — 矢印キーで操作するシングルセレクトプロンプトを表示します。`Detected (N)` セクション（`Install for all N detected` の集約行 + 検出された各CLI）と、未検出のサポート済みCLIをすべて前倒しインストールオプションとして一覧表示する `Not installed (M) · install hooks ahead of time` セクションにグループ化されます（↑↓で移動、Enterで選択、^Cで終了）。アンインストールフローはDetectedセクションのみ表示します。
+- **複数のCLIを検出**（非インタラクティブ実行 — CI、TTYなし） — プロンプトなしで検出された全CLIにインストールします。
+- **何も検出されない** — `claude` にフォールバックし、PATHにエージェントバイナリが見つからなかった旨の警告を表示します。フックコマンドは書き込まれるため、インストール後すぐに有効になります。
+
+`policies-config.json` はいつでも直接編集できます。変更は次のフックイベント時に即座に反映されます（再起動不要）。
+
+---
+
+## 例: チームデフォルトを含むプロジェクトレベルの設定
+
+`.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`（gitignore対象）を作成して、チームメンバーに影響を与えることなく個人用オーバーライドを設定できます。

package/.next/standalone/docs-old/ja/custom-policies.mdx

@@ -0,0 +1,358 @@
+---
+title: カスタムポリシー
+description: "JavaScriptで独自のポリシーを作成する - 規約の適用、ドリフトの防止、障害の検出、外部システムとの統合"
+icon: code
+---
+
+カスタムポリシーを使用すると、任意のエージェント動作に対するルールを記述できます。プロジェクトの規約の適用、ドリフトの防止、破壊的な操作のゲート処理、スタックしたエージェントの検出、Slackや承認ワークフローとの統合などが可能です。組み込みポリシーと同じフックイベントシステムと `allow`、`deny`、`instruct` の決定機構を使用します。
+
+---
+
+## クイックサンプル
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  description: "Block writes to paths containing 'production'",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) {
+      return deny("Writes to production paths are blocked");
+    }
+    return allow();
+  },
+});
+```
+
+インストール:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## カスタムポリシーの読み込み方法
+
+### オプション1: 規約ベース（推奨）
+
+`.failproofai/policies/` に `*policies.{js,mjs,ts}` ファイルを配置するだけで自動的に読み込まれます。フラグや設定変更は不要です。gitフックと同様に、ファイルを置くだけで機能します。
+
+```
+# プロジェクトレベル — gitにコミットされ、チームで共有される
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# ユーザーレベル — 個人用、すべてのプロジェクトに適用される
+~/.failproofai/policies/my-policies.mjs
+```
+
+**動作の仕組み:**
+- プロジェクトディレクトリとユーザーディレクトリの両方がスキャンされます（ユニオン — スコープ優先ではありません）
+- ファイルは各ディレクトリ内でアルファベット順に読み込まれます。順序を制御するには `01-`、`02-` などのプレフィックスを付けてください
+- `*policies.{js,mjs,ts}` にマッチするファイルのみ読み込まれ、それ以外は無視されます
+- 各ファイルは独立して読み込まれます（ファイル単位でフェイルオープン）
+- 明示的な `--custom` および組み込みポリシーと併用できます
+
+<Tip>
+規約ポリシーは、組織の品質基準を構築する最も簡単な方法です。`.failproofai/policies/` をgitにコミットすれば、すべてのチームメンバーが同じルールを自動的に取得できます。開発者ごとのセットアップは不要です。チームが新しい障害パターンを発見したらポリシーを追加してプッシュするだけで、時間とともにこれらは貢献のたびに改善される生きた品質基準になります。
+</Tip>
+
+### オプション2: 明示的なファイルパス
+
+```bash
+# カスタムポリシーファイルをインストール
+failproofai policies --install --custom ./my-policies.js
+
+# カスタムポリシーパスを置き換える
+failproofai policies --install --custom ./new-policies.js
+
+# 複数の明示的なファイルを設定する（フラグの順序で読み込まれる）
+failproofai policies --install --custom ./security.js --custom ./workflow.js
+
+# すべての明示的なカスタムポリシーパスを設定から削除する
+failproofai policies --uninstall --custom
+```
+
+解決された絶対パスは `policies-config.json` に `customPoliciesPaths` として保存されます。複数のファイルを設定するには `--custom` を繰り返してください。レガシーの `customPoliciesPath` フィールドを使用した既存の設定も引き続き動作します。ファイルはフックイベントごとに新たに読み込まれ、イベント間のキャッシュはありません。
+
+登録された各ポリシーはダッシュボードに個別のトグルとして表示されます。ポリシーをオフにすると、そのソース修飾IDが `disabledCustomPolicies` に記録されます。ファイルとその他のポリシーは引き続き読み込まれますが、無効化されたポリシーはイベントマッチング前に除外されます。ファイル間で重複するポリシー名は独立したトグルを持ちます。
+
+### 両方を組み合わせて使用する
+
+規約ポリシーと明示的な `--custom` ファイルは共存できます。読み込み順序:
+
+1. 明示的な `customPoliciesPaths` ファイル（設定された順序）
+2. プロジェクト規約ファイル（`{cwd}/.failproofai/policies/`、アルファベット順）
+3. ユーザー規約ファイル（`~/.failproofai/policies/`、アルファベット順）
+
+---
+
+## API
+
+### インポート
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+ポリシーを登録します。同じファイル内で複数のポリシーを追加するために何度でも呼び出せます。
+
+```ts
+customPolicies.add({
+  name: string;                         // 必須 - 一意の識別子
+  description?: string;                 // `failproofai policies` の出力に表示される
+  match?: { events?: HookEventType[] }; // イベントタイプでフィルタリング; 省略するとすべてにマッチ
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### 決定ヘルパー
+
+| 関数 | 効果 | 使用場面 |
+|----------|--------|----------|
+| `allow()` | 操作を暗黙的に許可する | アクションが安全で、メッセージが不要な場合 |
+| `deny(message)` | 操作をブロックする | エージェントがこのアクションを実行すべきでない場合 |
+| `instruct(message)` | ブロックせずにコンテキストを追加する | エージェントに軌道を維持するための追加コンテキストを提供する場合 |
+
+`deny(message)` — メッセージは `"Blocked by failproofai:"` というプレフィックスが付いてClaudeに表示されます。単一の `deny` により、以降のすべての評価がショートサーキットされます。
+
+`instruct(message)` — メッセージは現在のツール呼び出しに対するClaudeのコンテキストに追記されます。すべての `instruct` メッセージは蓄積されてまとめて配信されます。
+
+<Tip>
+`policyParams` の `hint` フィールドを追加することで、コードを変更せずに `deny` または `instruct` メッセージに追加のガイダンスを付け加えられます。これはカスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）のポリシーでも機能します。詳細は[設定 → hint](/ja/configuration#hint-cross-cutting)を参照してください。
+</Tip>
+
+### 情報提供のallowメッセージ
+
+`allow(message)` は操作を許可し**つつ**、情報提供のメッセージをClaudeに送信します。メッセージはフックハンドラーのstdoutレスポンスに `additionalContext` として配信されます。これは `instruct` と同じメカニズムを使用しますが、意味的には異なります。警告ではなく、ステータスの更新です。
+
+| 関数 | 効果 | 使用場面 |
+|----------|--------|----------|
+| `allow(message)` | 許可してClaudeにコンテキストを送信する | チェックが通過したことを確認する、またはチェックがスキップされた理由を説明する場合 |
+
+ユースケース:
+- **ステータス確認:** `allow("All CI checks passed.")` — すべてが正常であることをClaudeに伝える
+- **フェイルオープンの説明:** `allow("GitHub CLI not installed, skipping CI check.")` — チェックがスキップされた理由をClaudeに伝え、完全なコンテキストを提供する
+- **複数メッセージの蓄積:** 複数のポリシーがそれぞれ `allow(message)` を返した場合、すべてのメッセージが改行で結合されてまとめて配信される
+
+```js
+customPolicies.add({
+  name: "confirm-branch-status",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    const cwd = ctx.session?.cwd;
+    if (!cwd) return allow("No working directory, skipping branch check.");
+
+    // ... check branch status ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### `PolicyContext` フィールド
+
+| フィールド | 型 | 説明 |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`、`"PostToolUse"`、`"Notification"`、`"Stop"` |
+| `toolName` | `string \| undefined` | 呼び出されるツール（例: `"Bash"`、`"Write"`、`"Read"`） |
+| `toolInput` | `Record<string, unknown> \| undefined` | ツールの入力パラメータ |
+| `payload` | `Record<string, unknown>` | Claude Code からの生のイベントペイロード全体 |
+| `session` | `SessionMetadata \| undefined` | セッションコンテキスト（以下参照） |
+
+### `SessionMetadata` フィールド
+
+| フィールド | 型 | 説明 |
+|-------|------|-------------|
+| `sessionId` | `string` | Claude Code セッション識別子 |
+| `cwd` | `string` | Claude Code セッションの作業ディレクトリ |
+| `transcriptPath` | `string` | セッションのJSONLトランスクリプトファイルへのパス |
+
+### イベントタイプ
+
+| イベント | 発火タイミング | `toolInput` の内容 |
+|-------|--------------|----------------------|
+| `PreToolUse` | Claudeがツールを実行する前 | ツールの入力（例: Bashの場合は `{ command: "..." }`） |
+| `PostToolUse` | ツールが完了した後 | ツールの入力 + `tool_result`（出力） |
+| `Notification` | Claudeが通知を送信するとき | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - フックは常に `allow()` を返す必要があり、通知をブロックすることはできません |
+| `Stop` | Claudeセッションが終了するとき | 空 |
+
+---
+
+## 評価順序
+
+ポリシーは次の順序で評価されます:
+
+1. 組み込みポリシー（定義順）
+2. `customPoliciesPath` からの明示的なカスタムポリシー（`.add()` の順序）
+3. プロジェクト `.failproofai/policies/` からの規約ポリシー（ファイルはアルファベット順、ファイル内は `.add()` の順序）
+4. ユーザー `~/.failproofai/policies/` からの規約ポリシー（ファイルはアルファベット順、ファイル内は `.add()` の順序）
+
+<Note>
+最初の `deny` により以降のすべてのポリシーがショートサーキットされます。すべての `instruct` メッセージは蓄積されてまとめて配信されます。
+</Note>
+
+---
+
+## 推移的インポート
+
+カスタムポリシーファイルは相対パスを使用してローカルモジュールをインポートできます:
+
+```js
+// my-policies.js
+import { isBlockedPath } from "./utils.js";
+import { checkApproval } from "./approval-client.js";
+
+customPolicies.add({
+  name: "approval-gate",
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
+    return approved ? allow() : deny("Approval required for this command");
+  },
+});
+```
+
+エントリファイルから到達可能なすべての相対インポートが解決されます。これは `from "failproofai"` のインポートを実際のdistパスに書き換え、ESM互換性を確保するために一時的な `.mjs` ファイルを作成することで実装されています。
+
+---
+
+## イベントタイプのフィルタリング
+
+`match.events` を使用してポリシーが発火するタイミングを限定できます:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // セッションが終了したときのみ発火する
+    // ctx.session.transcriptPath にはセッションの完全なログが含まれる
+    return allow();
+  },
+});
+```
+
+`match` を完全に省略すると、すべてのイベントタイプで発火します。
+
+---
+
+## エラー処理と障害モード
+
+カスタムポリシーは**フェイルオープン**です。エラーが発生しても組み込みポリシーをブロックしたり、フックハンドラーをクラッシュさせたりすることはありません。
+
+| 障害 | 動作 |
+|---------|----------|
+| `customPoliciesPath` が未設定 | 明示的なカスタムポリシーは実行されない。規約ポリシーと組み込みポリシーは通常通り継続する |
+| ファイルが見つからない | `~/.failproofai/hook.log` に警告が記録される。組み込みポリシーは継続する |
+| 構文/インポートエラー（明示的） | `~/.failproofai/hook.log` にエラーが記録される。明示的なカスタムポリシーはスキップされる |
+| 構文/インポートエラー（規約） | エラーが記録される。そのファイルはスキップされ、他の規約ファイルは引き続き読み込まれる |
+| `fn` が実行時に例外をスロー | エラーが記録される。そのフックは `allow` として処理される。他のフックは継続する |
+| `fn` が10秒以上かかる | タイムアウトが記録される。`allow` として処理される |
+| 規約ディレクトリが存在しない | 規約ポリシーは実行されない。エラーなし |
+
+<Tip>
+カスタムポリシーのエラーをデバッグするには、ログファイルを監視してください:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## 完全な例: 複数のポリシー
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// エージェントが secrets/ ディレクトリに書き込むのを防ぐ
+customPolicies.add({
+  name: "block-secrets-dir",
+  description: "Prevent agent from writing to secrets/ directory",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
+    return allow();
+  },
+});
+
+// エージェントを軌道に乗せる: コミット前にテストを確認する
+customPolicies.add({
+  name: "remind-test-before-commit",
+  description: "Keep the agent on track: verify tests pass before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
+    }
+    return allow();
+  },
+});
+
+// フリーズ期間中の計画外の依存関係変更を防ぐ
+customPolicies.add({
+  name: "dependency-freeze",
+  description: "Prevent unplanned dependency changes during freeze period",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
+    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
+      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
+    }
+    return allow();
+  },
+});
+
+export { customPolicies };
+```
+
+---
+
+## サンプル
+
+`examples/` ディレクトリにはすぐに実行できるポリシーファイルが含まれています:
+
+| ファイル | 内容 |
+|------|----------|
+| `examples/policies-basic.js` | 一般的なエージェント障害モードをカバーする5つのスターターポリシー |
+| `examples/policies-advanced/index.js` | 高度なパターン: 推移的インポート、非同期呼び出し、出力スクラビング、セッション終了フック |
+| `examples/convention-policies/security-policies.mjs` | 規約ベースのセキュリティポリシー（.envへの書き込みをブロック、gitヒストリーの書き換えを防止） |
+| `examples/convention-policies/workflow-policies.mjs` | 規約ベースのワークフローポリシー（テストリマインダー、監査ファイル書き込み） |
+
+### 明示的なファイルサンプルの使用方法
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### 規約ベースのサンプルの使用方法
+
+```bash
+# プロジェクトレベルにコピーする
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# またはユーザーレベルにコピーする
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+インストールコマンドは不要です。次のフックイベント時にファイルが自動的に検出されます。