> ## Documentation Index
> Fetch the complete documentation index at: https://exosphere-auto-translate-docs-20260624-1149.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 組み込みポリシー

> エージェントの一般的な失敗パターンを検出する39個の組み込みポリシー

failproofai には、エージェントの一般的な失敗パターンを検出する39個の組み込みポリシーが含まれています。各ポリシーは特定のフックイベントタイプとツール名に対して発火します。19個のポリシーはパラメーターを受け付け、コードを書かずに動作を調整できます。5つのワークフローポリシーは、Claude が停止する前にコミット → プッシュ → PR → CI のパイプラインを強制します。

***

## 概要

ポリシーはカテゴリごとにグループ化されています：

| カテゴリ                                  | ポリシー                                                                                                                                         | フックタイプ      |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| [危険なコマンド](#dangerous-commands)        | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands                                                                      | PreToolUse  |
| [インフラコマンド](#infra-commands)           | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline                                     | PreToolUse  |
| [シークレット（サニタイザー）](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens                           | PostToolUse |
| [環境](#environment)                    | block-env-files, protect-env-vars                                                                                                            | PreToolUse  |
| [ファイルアクセス](#file-access)              | block-read-outside-cwd, block-secrets-write                                                                                                  | PreToolUse  |
| [Git](#git)                           | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged                          | PreToolUse  |
| [データベース](#database)                   | warn-destructive-sql, warn-schema-alteration                                                                                                 | PreToolUse  |
| [警告](#warnings)                       | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install                                            | PreToolUse  |
| [パッケージマネージャー](#package-managers)      | prefer-package-manager                                                                                                                       | PreToolUse  |
| [ワークフロー](#workflow)                   | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop        |

* **`block-`** — エージェントの処理を停止します。
* **`warn-`** — エージェントが自己修正できるよう追加のコンテキストを提供します。
* **`sanitize-`** — エージェントが参照する前にツール出力から機密データを除去します。

### 名前空間

すべてのポリシーは `<namespace>/<name>` のスロットに存在します。組み込みポリシーは **`failproofai/`** 名前空間に属します。例：`failproofai/sanitize-jwt`。名前空間により、短い名前が似ているカスタムポリシーやサードパーティポリシーを同時に読み込んでも衝突を防ぎます。

設定ファイルでは、短い名前または完全修飾名のどちらでも組み込みポリシーを参照できます。どちらの形式も同じポリシーに解決されます：

```json theme={null}
{
  "enabledPolicies": [
    "sanitize-jwt",
    "failproofai/block-rm-rf"
  ]
}
```

名前に `/` が含まれない場合、failproofai はデフォルト名前空間 `failproofai` に属するものとして扱います。すでに `/` を含む名前（例：`myorg/foo`、`custom/my-hook`）はそのまま保持されます。

* **`require-`** — 条件が満たされるまで Stop イベントをブロックします。

***

<Tip>
  すべてのポリシーは `policyParams` でオプションの `hint` フィールドをサポートしています。hint は Claude が受け取る deny または instruct メッセージに追記され、ポリシーコードを変更せずに実行可能なガイダンスを提供します。組み込み、カスタム、コンベンションポリシーのいずれでも動作します。詳細は [設定 → hint](/ja/configuration#hint-cross-cutting) を参照してください。
</Tip>

***

## 危険なコマンド

元に戻しにくい操作やホストシステムに損害を与えかねない操作をエージェントが実行するのを防ぎます。

### `block-sudo`

**イベント:** PreToolUse (Bash)\
**デフォルト:** `sudo` コマンドを含むすべての実行を拒否します。

`sudo` キーワードを含む実行をブロックします。パターンマッチングは生の文字列ではなく、解析済みのコマンドトークンに対して行われるため、シェルオペレーターインジェクションによる回避を防ぎます。

**パラメーター:**

| パラメーター          | 型          | デフォルト | 説明                                                     |
| --------------- | ---------- | ----- | ------------------------------------------------------ |
| `allowPatterns` | `string[]` | `[]`  | 許可する正確なコマンドプレフィックス。各エントリは解析済みの argv トークンに対してマッチングされます。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    }
  }
}
```

この設定では `sudo systemctl status nginx` は許可されますが、`sudo rm /etc/hosts` は拒否されます。

<Note>
  パターンは生のコマンド文字列ではなく、解析済みトークンに対してマッチングされます。これにより、末尾に追加されたシェルオペレーターを使った回避を防ぎます（例：`sudo systemctl status x; rm -rf /` は `sudo systemctl status *` にマッチしません）。
</Note>

***

### `block-rm-rf`

**イベント:** PreToolUse (Bash)\
**デフォルト:** `rm -rf`、`rm -fr`、および同様の再帰的削除の形式を拒否します。

**パラメーター:**

| パラメーター       | 型          | デフォルト | 説明                     |
| ------------ | ---------- | ----- | ---------------------- |
| `allowPaths` | `string[]` | `[]`  | 再帰的削除が安全なパス（例：`/tmp`）。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "block-rm-rf": {
      "allowPaths": ["/tmp", "/var/cache"]
    }
  }
}
```

***

### `block-curl-pipe-sh`

**イベント:** PreToolUse (Bash)\
**デフォルト:** `curl <url> | bash`、`curl <url> | sh`、`wget <url> | bash`、および同様のパターンを拒否します。

パラメーターなし。

***

### `block-failproofai-commands`

**イベント:** PreToolUse (Bash)\
**デフォルト:** failproofai 自体をアンインストールまたは無効化するコマンドを拒否します（例：`npm uninstall failproofai`、`failproofai policies --uninstall`）。

パラメーターなし。

***

## インフラコマンド

コーディングエージェントがインフラ CLI を実行したり CI/CD パイプラインをトリガーしたりするのを防ぎます。このカテゴリのすべてのポリシーは **オプトイン**（`defaultEnabled: false`）です。`kubectl`、`terraform` などを正当に呼び出す必要があるエージェントは、ポリシーを有効化しない限り影響を受けません。有効化すると、`allowPatterns` のエントリとマッチしない限り、マッチした CLI のすべての呼び出しが拒否されます。

パターン文法は [`block-sudo`](#block-sudo) と同じです：トークンは解析済みの argv に対してマッチングされ、`*` は1トークンのワイルドカードです。スタンドアロンのシェルオペレーター（`&&`、`||`、`|`、`;`）を含むコマンドや、シェルメタキャラクターが埋め込まれたトークンを含むコマンドは、インジェクション回避を防ぐためにアローリストマッチングの前に拒否されます。

### `block-kubectl`

**イベント:** PreToolUse (Bash)\
**デフォルト:** すべての `kubectl` 呼び出しを拒否します。

**パラメーター:**

| パラメーター          | 型          | デフォルト | 説明                        |
| --------------- | ---------- | ----- | ------------------------- |
| `allowPatterns` | `string[]` | `[]`  | 許可する kubectl コマンドプレフィックス。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "block-kubectl": {
      "allowPatterns": ["kubectl get *", "kubectl describe *", "kubectl logs *"]
    }
  }
}
```

この設定では `kubectl get pods` は許可されますが、`kubectl apply -f deploy.yaml` は拒否されます。

***

### `block-terraform`

**イベント:** PreToolUse (Bash)\
**デフォルト:** すべての `terraform` または `tofu`（OpenTofu）呼び出しを拒否します。

**パラメーター:**

| パラメーター          | 型          | デフォルト | 説明                               |
| --------------- | ---------- | ----- | -------------------------------- |
| `allowPatterns` | `string[]` | `[]`  | 許可する terraform/tofu コマンドプレフィックス。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "block-terraform": {
      "allowPatterns": ["terraform plan", "terraform validate", "terraform show *"]
    }
  }
}
```

***

### `block-aws-cli`

**イベント:** PreToolUse (Bash)\
**デフォルト:** すべての `aws` CLI 呼び出しを拒否します。

**パラメーター:**

| パラメーター          | 型          | デフォルト | 説明                        |
| --------------- | ---------- | ----- | ------------------------- |
| `allowPatterns` | `string[]` | `[]`  | 許可する aws CLI コマンドプレフィックス。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "block-aws-cli": {
      "allowPatterns": ["aws s3 ls *", "aws sts get-caller-identity"]
    }
  }
}
```

***

### `block-gcloud`

**イベント:** PreToolUse (Bash)\
**デフォルト:** すべての `gcloud`（Google Cloud）CLI 呼び出しを拒否します。

**パラメーター:**

| パラメーター          | 型          | デフォルト | 説明                       |
| --------------- | ---------- | ----- | ------------------------ |
| `allowPatterns` | `string[]` | `[]`  | 許可する gcloud コマンドプレフィックス。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "block-gcloud": {
      "allowPatterns": ["gcloud auth list", "gcloud config list"]
    }
  }
}
```

***

### `block-az-cli`

**イベント:** PreToolUse (Bash)\
**デフォルト:** すべての `az`（Azure）CLI 呼び出しを拒否します。

**パラメーター:**

| パラメーター          | 型          | デフォルト | 説明                       |
| --------------- | ---------- | ----- | ------------------------ |
| `allowPatterns` | `string[]` | `[]`  | 許可する az CLI コマンドプレフィックス。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "block-az-cli": {
      "allowPatterns": ["az account show", "az group list"]
    }
  }
}
```

***

### `block-helm`

**イベント:** PreToolUse (Bash)\
**デフォルト:** すべての `helm` 呼び出しを拒否します。

**パラメーター:**

| パラメーター          | 型          | デフォルト | 説明                     |
| --------------- | ---------- | ----- | ---------------------- |
| `allowPatterns` | `string[]` | `[]`  | 許可する helm コマンドプレフィックス。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "block-helm": {
      "allowPatterns": ["helm list", "helm status *"]
    }
  }
}
```

***

### `block-gh-pipeline`

**イベント:** PreToolUse (Bash)\
**デフォルト:** 状態を変更するかパイプラインをトリガーする以下の `gh` CLI サブコマンドを拒否します：

* `gh workflow run`、`gh workflow enable`、`gh workflow disable`
* `gh run rerun`、`gh run cancel`
* `gh pr merge`
* `gh release create`、`gh release delete`
* `gh cache delete`
* `gh secret set`、`gh secret delete`

`gh pr view`、`gh pr list`、`gh run list`、`gh release view`、`gh api repos/.../...` などの読み取り専用 `gh` サブコマンドは、このポリシーにマッチ**しません**。これらは failproofai 自身の `require-ci-green-before-stop` を含むワークフローチェックで日常的に必要とされます。

**パラメーター:**

| パラメーター          | 型          | デフォルト | 説明                                |
| --------------- | ---------- | ----- | --------------------------------- |
| `allowPatterns` | `string[]` | `[]`  | 通常は拒否される場合でも許可する特定のスクリプト化された呼び出し。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "block-gh-pipeline": {
      "allowPatterns": ["gh run rerun *"]
    }
  }
}
```

***

## シークレット（サニタイザー）

エージェントが認証情報をコンテキストや出力に漏洩させるのを防ぎます。サニタイザーポリシーは **PostToolUse** イベントで発火します。Claude が Bash コマンドを実行したり、ファイルを読んだり、ツールを呼び出したりすると、これらのポリシーは Claude に返される前に出力を検査します。シークレットパターンが検出された場合、ポリシーは出力が返されるのを防ぐ deny 決定を返します。

### `sanitize-jwt`

**イベント:** PostToolUse（すべてのツール）\
**デフォルト:** JWT トークン（`.` で区切られた3つの base64url セグメント）を削除します。

パラメーターなし。

***

### `sanitize-api-keys`

**イベント:** PostToolUse（すべてのツール）\
**デフォルト:** 一般的な API キー形式を削除します：Anthropic（`sk-ant-`）、OpenAI（`sk-`）、GitHub PAT（`ghp_`）、AWS アクセスキー（`AKIA`）、Stripe キー（`sk_live_`、`sk_test_`）、Google API キー（`AIza`）。

**パラメーター:**

| パラメーター               | 型                                    | デフォルト | 説明                      |
| -------------------- | ------------------------------------ | ----- | ----------------------- |
| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]`  | シークレットとして扱う追加の正規表現パターン。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
      ]
    }
  }
}
```

***

### `sanitize-connection-strings`

**イベント:** PostToolUse（すべてのツール）\
**デフォルト:** 認証情報が埋め込まれたデータベース接続文字列を削除します（例：`postgresql://user:password@host/db`）。

パラメーターなし。

***

### `sanitize-private-key-content`

**イベント:** PostToolUse（すべてのツール）\
**デフォルト:** PEM ブロック（`-----BEGIN PRIVATE KEY-----`、`-----BEGIN RSA PRIVATE KEY-----` など）を削除します。

パラメーターなし。

***

### `sanitize-bearer-tokens`

**イベント:** PostToolUse（すべてのツール）\
**デフォルト:** トークンが20文字以上の `Authorization: Bearer <token>` ヘッダーを削除します。

パラメーターなし。

***

## 環境

機密性の高い環境設定がエージェントによって読み取られたり公開されたりするのを防ぎます。

### `block-env-files`

**イベント:** PreToolUse (Bash, Read)\
**デフォルト:** `cat .env` や、`.env` をファイルパスとして指定した `Read` ツール呼び出しなどによる `.env` ファイルの読み取りを拒否します。

`.envrc` やその他の環境関連ファイルはブロックしません。正確に `.env` という名前のファイルのみが対象です。

パラメーターなし。

***

### `protect-env-vars`

**イベント:** PreToolUse (Bash)\
**デフォルト:** 環境変数を表示するコマンドを拒否します：`printenv`、`env`、`echo $VAR`。

パラメーターなし。

***

## ファイルアクセス

エージェントをプロジェクト境界内で作業させ、機密ファイルへのアクセスを防ぎます。

### `block-read-outside-cwd`

**イベント:** PreToolUse (Read, Bash)\
**デフォルト:** プロジェクトルート外のファイルの読み取りを拒否します。境界は `CLAUDE_PROJECT_DIR`（Claude Code がセッションごとに1回設定）で、この変数が未設定の場合はセッションの現在の作業ディレクトリにフォールバックします。ライブの `cwd` ではなくプロジェクトルートを使用することで、Claude がサブディレクトリに `cd` した後も境界が安定したままになります。

**パラメーター:**

| パラメーター       | 型          | デフォルト | 説明                              |
| ------------ | ---------- | ----- | ------------------------------- |
| `allowPaths` | `string[]` | `[]`  | プロジェクトルート外であっても許可する絶対パスプレフィックス。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "block-read-outside-cwd": {
      "allowPaths": ["/shared/data", "/opt/company/config"]
    }
  }
}
```

***

### `block-secrets-write`

**イベント:** PreToolUse (Write, Edit)\
**デフォルト:** 秘密鍵と証明書に一般的に使用されるファイルへの書き込みを拒否します：`id_rsa`、`id_ed25519`、`*.key`、`*.pem`、`*.p12`、`*.pfx`。

**パラメーター:**

| パラメーター               | 型          | デフォルト | 説明                         |
| -------------------- | ---------- | ----- | -------------------------- |
| `additionalPatterns` | `string[]` | `[]`  | ブロックする追加のファイル名パターン（グロブ形式）。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "block-secrets-write": {
      "additionalPatterns": [".token", ".secret"]
    }
  }
}
```

***

## Git

元に戻しにくい誤ったプッシュ、強制プッシュ、ブランチ操作ミスを防ぎます。

### `block-push-master`

**イベント:** PreToolUse (Bash)\
**デフォルト:** `git push origin main` および `git push origin master` を拒否します。

**パラメーター:**

| パラメーター              | 型          | デフォルト                | 説明               |
| ------------------- | ---------- | -------------------- | ---------------- |
| `protectedBranches` | `string[]` | `["main", "master"]` | 直接プッシュできないブランチ名。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "master", "release", "prod"]
    }
  }
}
```

<Tip>
  すべてのブランチへのプッシュを許可する場合（`enabledPolicies` からポリシーを削除せずに実質的に無効化する）、`protectedBranches: []` を設定してください。
</Tip>

***

### `block-work-on-main`

**イベント:** PreToolUse (Bash)\
**デフォルト:** 作業ツリーが `main` または `master` にある状態での `git commit`、`git merge`、`git rebase`、`git cherry-pick` を拒否します。ブランチの作成と切り替え（`git checkout`、`git checkout -b`、`git switch`、`git switch -c`）は影響を受けません。

**パラメーター:**

| パラメーター              | 型          | デフォルト                | 説明                                          |
| ------------------- | ---------- | -------------------- | ------------------------------------------- |
| `protectedBranches` | `string[]` | `["main", "master"]` | commit/merge/rebase/cherry-pick を拒否するブランチ名。 |

***

### `block-force-push`

**イベント:** PreToolUse (Bash)\
**デフォルト:** `git push --force` および `git push -f` を拒否します。

ポリシー固有のパラメーターはありません。代替手段を提示するには、汎用の [`hint`](/ja/configuration#hint-cross-cutting) を使用してください：

```json theme={null}
{
  "policyParams": {
    "block-force-push": {
      "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b <new-branch>`) and push that instead."
    }
  }
}
```

***

### `warn-git-amend`

**イベント:** PreToolUse (Bash)\
**デフォルト:** `git commit --amend` を実行する際に、慎重に進むよう Claude に指示します。コマンドはブロックしません。

パラメーターなし。

***

### `warn-git-stash-drop`

**イベント:** PreToolUse (Bash)\
**デフォルト:** `git stash drop` を実行する前に確認するよう Claude に指示します。コマンドはブロックしません。

パラメーターなし。

***

### `warn-all-files-staged`

**イベント:** PreToolUse (Bash)\
**デフォルト:** `git add -A` または `git add .` を実行する際に、ステージングする内容を確認するよう Claude に指示します。コマンドはブロックしません。

パラメーターなし。

***

## データベース

データベースに対して実行される前に、破壊的な SQL 操作を検出します。

### `warn-destructive-sql`

**イベント:** PreToolUse (Bash)\
**デフォルト:** `DROP TABLE`、`DROP DATABASE`、または `WHERE` 句なしの `DELETE` を含む SQL を実行する前に確認するよう Claude に指示します。

パラメーターなし。

***

### `warn-schema-alteration`

**イベント:** PreToolUse (Bash)\
**デフォルト:** `ALTER TABLE` ステートメントを実行する前に確認するよう Claude に指示します。

パラメーターなし。

***

## 警告

リスクはあるものの破壊的ではない操作の前に、エージェントに追加のコンテキストを提供します。

### `warn-large-file-write`

**イベント:** PreToolUse (Write)\
**デフォルト:** 1024 KB を超えるファイルを書き込む前に確認するよう Claude に指示します。

**パラメーター:**

| パラメーター        | 型        | デフォルト  | 説明                            |
| ------------- | -------- | ------ | ----------------------------- |
| `thresholdKb` | `number` | `1024` | 警告が発生するファイルサイズのしきい値（キロバイト単位）。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "warn-large-file-write": {
      "thresholdKb": 256
    }
  }
}
```

<Note>
  フックハンドラーはペイロードに対して 1 MB の stdin 制限を適用します。小さなコンテンツでこのポリシーをテストするには、`thresholdKb` を 1024 より十分小さい値に設定してください。
</Note>

***

### `warn-package-publish`

**イベント:** PreToolUse (Bash)\
**デフォルト:** `npm publish` を実行する前に確認するよう Claude に指示します。

パラメーターなし。

***

### `warn-background-process`

**イベント:** PreToolUse (Bash)\
**デフォルト:** `nohup`、`&`、`disown`、`screen` を使ってバックグラウンドプロセスを起動する際に注意するよう Claude に指示します。

パラメーターなし。

***

### `warn-global-package-install`

**イベント:** PreToolUse (Bash)\
**デフォルト:** `npm install -g`、`yarn global add`、または仮想環境なしの `pip install` を実行する前に確認するよう Claude に指示します。

パラメーターなし。

***

## パッケージマネージャー

エージェントが使用できるパッケージマネージャーを制限します。

### `prefer-package-manager`

**イベント:** PreToolUse (Bash)\
**デフォルト:** 無効。有効化すると、`allowed` リストにないパッケージマネージャーのコマンドをブロックし、許可されたマネージャーを使用してコマンドを書き直すよう Claude に指示します。

検出対象：pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo。

| パラメーター    | 型         | デフォルト | 説明                                                            |
| --------- | --------- | ----- | ------------------------------------------------------------- |
| `allowed` | string\[] | `[]`  | 許可するパッケージマネージャー名。リストにない検出されたマネージャーはブロックされます。空の場合、ポリシーは何もしません。 |
| `blocked` | string\[] | `[]`  | 組み込みリストに加えてブロックする追加のマネージャー名（例：`['pdm', 'pipx']`）。             |

組み込みのブロックリストには以下が含まれます：pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo。このリストにないマネージャーを追加するには `blocked` を使用してください。

**設定例:**

```json theme={null}
{
  "enabledPolicies": ["prefer-package-manager"],
  "policyParams": {
    "prefer-package-manager": {
      "allowed": ["uv", "bun"],
      "blocked": ["pdm", "pipx"]
    }
  }
}
```

この設定では、`pip install flask` と `pdm install flask` はどちらも拒否され、`uv` または `bun` を使用するよう指示するメッセージが表示されます。`uv pip install flask` のようなコマンドは、`uv` がアローリストに含まれており最初にチェックされるため、許可されます。

***

## AI の動作

エージェントが行き詰まったり予期しない動作をしたりするのを検出します。

### `warn-repeated-tool-calls`

**イベント:** PreToolUse（すべてのツール）\
**デフォルト:** 同じツールが同一パラメーターで3回以上呼び出された場合に、再考するよう Claude に指示します。これはエージェントがループに陥っている一般的なサインです。

パラメーターなし。

***

## ワークフロー

セッション終了時に規律あるワークフローを強制します。これらのポリシーは **Stop** イベントで発火し、各条件が満たされるまでエージェントの停止を拒否します。自然な依存チェーン（コミット → プッシュ → PR → CI）に従います。ポリシーが拒否した場合、チェーン内の後続ポリシーはスキップされます（deny はショートサーキットします）。

すべてのワークフローポリシーは **フェイルオープン**です：必要なツールが利用できない場合（例：`gh` がインストールされていない、git リモートがない）、ポリシーはチェックがスキップされた理由を説明する情報メッセージとともに許可します。

### CLI ごとの Stop セマンティクス

Stop の強制は、7つのサポートされている CLI によって若干異なります。各 CLI が異なる「エージェント終了」フックコントラクトを公開しているためです。**結果**は同じ（ワークフローゲートが失敗している状態でエージェントが停止することを防ぐ）ですが、**仕組み**は異なります。以下の表に要約します。`require-*-before-stop` ポリシーを有効化する前に理解しておく価値のあるユーザー向けの注意点があるのは Pi のみです。

| CLI                      | ゲートが発火するタイミング  | ユーザーが見るもの                                                                                                                                                                                                      |
| ------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Code              | 同じエージェントループ、即座 | Claude は作業を継続し、問題を修正してから再度終了を試みます。ユーザーには中断は見えません。                                                                                                                                                              |
| Codex                    | 同じエージェントループ、即座 | Claude と同じ。                                                                                                                                                                                                    |
| GitHub Copilot CLI       | 同じエージェントループ、即座 | Claude と同じ（Copilot の `{decision:"block", reason}` リトライチャネルを使用 — Copilot CLI 1.0.41 に対して実証的に検証済み）。                                                                                                              |
| Cursor Agent             | 同じエージェントループ、即座 | Claude と同じ（Cursor の `{followup_message}` チャネルを使用 — `loop_limit`、デフォルト5回のリトライまで）。                                                                                                                               |
| Gemini CLI               | 同じエージェントループ、即座 | Claude と同じ（`AfterAgent` の `{decision:"block", reason}` チャネルを使用）。                                                                                                                                               |
| OpenCode                 | 同じエージェントループ、即座 | Claude と同じ（`hookSpecificOutput.additionalContext` を通じてルーティングされた OpenCode の `client.session.prompt(...)` SDK 呼び出しを使用）。                                                                                          |
| **Pi (pi-coding-agent)** | **次のユーザーターン**  | **Pi はゲートが発火すると見えた形で停止します** — エージェントループが終了し、プロンプトに戻ります。次にプロンプトを送信したときにゲートが発火します：failproofai はそのターンのシステムプロンプトに `MANDATORY ACTION REQUIRED` ディレクティブを先頭に追加し、LLM にリクエストを実行する前にワークフローステップ（コミット、プッシュなど）を完了するよう指示します。 |

<Note>
  **Pi の制限。** Pi の `AgentEndEvent`（Claude の `Stop` フックに相当するアップストリーム）には Result 型がありません。発火するときには Pi のエージェントループはすでに終了しています。Pi は Claude / Copilot / Cursor / Gemini / OpenCode のように同じループを強制的に再試行させることができません。failproofai はゲートを Pi の `before_agent_start` イベント（次のユーザープロンプト後に発火）にシフトすることで、現在のターンではなく次のターンでワークフローチェックを強制します。

  **実際の動作：**

  * Pi が停止した後、deny の理由は Pi のセッション ID をキーとしてメモリ内にキャプチャされます。同じ Pi プロセスで次に送信するプロンプトがそれを消費します：LLM はシステムプロンプトの先頭に `MANDATORY ACTION REQUIRED` ディレクティブが表示され、コミット（またはプッシュ / PR 作成 / CI 待機）してからリクエストを続行します。キャプチャされた deny の理由はワンショットです — 一度消費されるとゲートはクリアされます。
  * ゲートは Pi のプロセスライフタイムに束縛されます。ターン間で Pi を `Ctrl+C` で終了したりキルしたりすると、メモリ内のエントリはプロセスとともにドロップされ、ゲートは見逃されます。Claude、Copilot、Cursor、Gemini、OpenCode も同じ制約があります（エージェントをキルするとゲートが見逃されます）— Pi はエージェントがゲートの前に見えた形で終了するため、より目立つだけです。
  * 保留中の deny は、何らかの理由（`new` / `resume` / `fork` / `quit`）による `session_shutdown` でもクリアされます。そのため、以前のセッションの古いゲートが同じ Pi プロセスで開始された新しいセッションに漏れることはありません。

  Claude スタイルの同一ループリトライが必要な場合は、他の6つのサポートされている CLI のいずれかで `Stop` ポリシーを実行してください。このギャップを埋めるための `AgentEndEvent` への将来の Result 型追加について、Pi のアップストリームを追跡しています。
</Note>

### `require-commit-before-stop`

**イベント:** Stop\
**デフォルト:** コミットされていない変更（変更済み、ステージ済み、または追跡されていないファイル）がある場合に停止を拒否します。作業ディレクトリがクリーンな場合は情報メッセージを返します。

パラメーターなし。

***

### `require-push-before-stop`

**イベント:** Stop\
**デフォルト:** プッシュされていないコミットがある場合、または現在のブランチにリモートトラッキングブランチがない場合に停止を拒否します。必要に応じてトラッキングブランチを作成するために `git push -u` を提案します。リモートが設定されていない場合はフェイルオープンします。

**パラメーター:**

| パラメーター   | 型        | デフォルト      | 説明           |
| -------- | -------- | ---------- | ------------ |
| `remote` | `string` | `"origin"` | プッシュ先のリモート名。 |

**例:**

```json theme={null}
{
  "policyParams": {
    "require-push-before-stop": {
      "remote": "upstream"
    }
  }
}
```

***

### `require-pr-before-stop`

**イベント:** Stop\
**デフォルト:** 現在のブランチに対してプルリクエストが存在しない場合、またはマージされずにクローズされた PR がある場合に停止を拒否します。`gh pr create` で PR を作成するよう Claude に指示します。PR が **マージ済み**の場合、ポリシーは許可します（作業が公開されています）。メッセージはブランチを切り替えるよう示唆します（`git checkout main && git pull`）。

パラメーターなし。

<Note>
  このポリシーには [GitHub CLI](https://cli.github.com/)（`gh`）がインストールされ認証されている必要があります。
  プルリクエストへの読み取りアクセスのために `repo` スコープを持つ個人アクセストークンで `gh auth login` を実行してください。`gh` がインストールされていないか認証されていない場合、ポリシーはフェイルオープンし、理由を Claude に報告します。
</Note>

***

### `require-no-conflicts-before-stop`

**イベント:** Stop\
**デフォルト:** 現在のブランチがベースブランチにクリーンにマージできない場合に停止を拒否します。ポリシーはまず GitHub 上のブランチに `OPEN` な PR があることを確認します — PR がない場合、強制するマージターゲットがないため、ポリシー全体がショートサーキットして許可します。`OPEN` な PR が確認されると、2つの独立したプローブが実行されます：

1. **ローカル** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`。コンフリクトが発生した場合、deny メッセージは競合するファイルを名前で示し、Claude が何を解決すべきかを正確に把握できるようにします。
2. **GitHub** — 事前チェックですでに取得した `gh pr view --json mergeable,state` の結果を再利用します。ローカルの `origin/<baseBranch>` が古い場合に見逃してしまうコンフリクトを検出します（例：最後のフェッチ以降に誰かが `main` に競合する PR をマージした場合）。`CONFLICTING` の結果は拒否されます。`UNKNOWN` の結果も拒否され、Claude は再度停止を試みる前に約10秒待って再チェックするよう指示されます — これにより、GitHub が再計算中の偽陰性を防ぎます。

以下の場合はスキップします（許可します）：`gh` がインストールされていない、ブランチに PR が存在しない、PR の状態が `OPEN` でない（例：`MERGED`、`CLOSED`）、または `gh pr view` が解析不能な出力を返す。また、`origin/<baseBranch>` がローカルに存在しない場合や、ベースより先のコミットがない場合もフェイルオープンします — これらのレイヤー1フォールスルーは、許可する前にキャッシュされた PR のマージ可能性を参照します。

**パラメーター:**

| パラメーター       | 型        | デフォルト    | 説明                    |
| ------------ | -------- | -------- | --------------------- |
| `baseBranch` | `string` | `"main"` | コンフリクトをチェックするベースブランチ。 |

<Note>
  このポリシーには GitHub CLI（`gh`）が必要です。ポリシーは競合プローブを実行する前に `gh pr view` を使用して `OPEN` な PR が存在することを確認します — `gh` がない場合、ポリシーはショートサーキットして許可します。プルリクエストへの読み取りアクセスのために `repo` スコープを持つ個人アクセストークンで `gh auth login` を実行してください。
</Note>

***

### `require-ci-green-before-stop`

**イベント:** Stop\
**デフォルト:** 現在のブランチで CI チェックが失敗しているかまだ実行中の場合に停止を拒否します。GitHub Actions ワークフローの実行とサードパーティのボットチェック（例：CodeRabbit、SonarCloud、Codecov）の両方をチェックします。`skipped`、`cancelled`、`neutral` の結論は失敗として扱いません（後者は例えば、Socket Security が外部コントリビューターの PR に対して success/failure ではなく intentionally neutral を報告する場合をカバーします）。すべてのチェックが通過すると情報メッセージを返します。

パラメーターなし。

<Note>
  このポリシーには [GitHub CLI](https://cli.github.com/)（`gh`）がインストールされ認証されている必要があります。
  Actions ワークフローの実行と Checks API への読み取りアクセスのために `repo` スコープを持つ個人アクセストークンで `gh auth login` を実行してください。`gh` がインストールされていないか認証されていない場合、ポリシーはフェイルオープンし、理由を Claude に報告します。
</Note>

***

***

## 個別ポリシーの無効化

設定の `enabledPolicies` から特定のポリシーを削除するか、ダッシュボードの「ポリシー」タブでオフに切り替えてください。

```json theme={null}
{
  "enabledPolicies": [
    "block-rm-rf",
    "sanitize-api-keys"
  ]
}
```

`enabledPolicies` にリストされていないポリシーは、`policyParams` にエントリが存在しても実行されません。