カスタムポリシー

カスタムポリシーは、トレースや監査から得られた障害パターンを、エージェントの動作中にリアルタイムで実行される判断に変換します。ポリシーはアクションを許可したり、エージェントにガイダンスを提供したり、別のインシデントを引き起こす前にアクションを拒否したりできます。動作がツール、パス、コマンド、環境、または運用ルールに依存する場合はカスタムポリシーを使用してください。既存のコントロールを再作成しないよう、まず Failproof AI ポリシーパックを確認してください。

カスタムポリシーの作成

ダッシュボード
CLI

Admin → ポリシーエディター に移動し、新しいポリシー を選択して、防止したい障害を説明します。
ポリシーソースを追加し、エディターで期待されるマッチと安全な非マッチをテストします。すべてのバリデーションエラーを解消します。
ドラフトを保存し、バージョンを公開 を選択して不変バージョンを作成します。
Admin → 施行 に移動し、観察モードでテストマシンにバージョンをデプロイし、施行する前に 観察 → ポリシー で決定を確認します。

.failproofai/policies/checkout-policies.ts を作成します。ファイル名は policies.js、policies.mjs、または policies.ts で終わる必要があります。
customPolicies.add() で1つ以上のポリシーを登録します。
failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project でファイルをバリデートしてインストールします。
マッチするアクションと安全なアクションをそれぞれ1回トリガーします。failproofai policies を実行し、観察 → ポリシー で帰属する決定を確認します。

狭いルールから始める

このポリシーは、コマンドがproductionをターゲットにしている場合にのみ、破壊的なKubernetesコマンドをブロックします。この厳密な障害モード以外はすべて allow() を返します。

import { customPolicies, allow, deny } from "failproofai";

const DESTRUCTIVE_KUBECTL = /\bkubectl\s+(delete|replace)\b/i;
const PRODUCTION_TARGET = /(?:--context|--namespace|-n)\s+(prod|production)\b/i;

customPolicies.add({
  name: "block-destructive-production-kubectl",
  description: "Block destructive Kubernetes commands against production",
  match: { events: ["PreToolUse"] },
  fn: async ({ toolName, toolInput }) => {
    if (toolName !== "Bash") return allow();

    const command = String(toolInput?.command ?? "");
    if (!DESTRUCTIVE_KUBECTL.test(command)) return allow();
    if (!PRODUCTION_TARGET.test(command)) return allow();

    return deny(
      "Destructive production Kubernetes commands require the approved deployment workflow.",
    );
  },
});

良いポリシーは1文で説明できるほど狭いものです。エージェントの意図ではなく、観察可能なアクションにマッチさせ、ルールが適用されない場合はすぐに allow() を返します。

決定を選択する

ヘルパー	結果	使用する場面
`allow(reason?)`	操作が続行されます。	ポリシーが適用されないか、アクションが安全な場合。
`instruct(reason)`	ハーネスがサポートしている場合、ガイダンス付きで操作が続行されます。	不変条件を強制せずにエージェントをより良いアプローチに誘導したい場合。
`deny(reason)`	イベントとハーネスがブロックをサポートしている場合、操作がブロックされます。	アクションを進めてはならない場合。

理由は回復しなければならないエージェント向けに書いてください。何が検出されたか、代わりに何をすべきかを説明します。

安全境界に instruct() を使用しないでください。ガイダンスの配信はエージェントハーネスによって異なります。アクションを防止しなければならない場合は deny() を使用してください。

ポリシーオブジェクト

customPolicies.add({
  name: "policy-name",
  description: "What this policy prevents",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => allow(),
});

フィールド	必須	説明
`name`	はい	ポリシーの安定した識別子。ファイル間で名前をユニークに保ちます。
`description`	いいえ	ポリシー一覧や決定に表示される人間が読める目的の説明。
`match.events`	いいえ	ポリシーを呼び出すイベントタイプ。`match` を省略すると、利用可能なすべてのイベントに対して呼び出されます。
`fn`	はい	`allow`、`instruct`、または `deny` の結果を返す同期または非同期関数。

ツールのフィルタリングは fn 内で行ってください。match.toolNames はパブリックなカスタムポリシー型には含まれていません。

ポリシーコンテキスト

すべてのポリシーは PolicyContext を受け取ります。

フィールド	型	内容
`eventType`	`HookEventType`	現在評価中の正規化されたイベント。
`toolName`	`string \| undefined`	`Bash`、`Read`、`Write`、`Edit` などの正規ツール名。
`toolInput`	`Record<string, unknown> \| undefined`	現在のツール呼び出しの正規入力。
`payload`	`Record<string, unknown>`	完全な正規化されたイベントペイロード。
`session`	`SessionMetadata \| undefined`	セッションID、作業ディレクトリ、トランスクリプトパス、パーミッションモード、および利用可能な場合のハーネスメタデータ。
`cli`	`string \| undefined`	`claude`、`codex`、`cursor` などのソースエージェントハーネス。
`params`	`Record<string, unknown>`	組み込みポリシーパラメーター。カスタムポリシーは現在空のオブジェクトを受け取ります。

すべてのオプション値を本当にオプションとして扱ってください。エージェントのバージョンとイベントタイプによって提供されるフィールドは異なります。

共通ツール入力

Failproof AI はサポートされているハーネス間で共通ツールを正規化するため、ポリシーは通常1つの入力形式を使用できます。

ツール	共通フィールド
`Bash`	`command`
`Read`	`file_path`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Grep`	`pattern`, `path`

ツール入力値は unknown 型であるため、防御的な型変換を使用してください：

const command = String(ctx.toolInput?.command ?? "");
const filePath = String(ctx.toolInput?.file_path ?? "");

イベントを選択する

イベント	実行タイミング	主な用途
`PreToolUse`	ツール実行前。	コマンド、書き込み、読み取り、外部アクションのブロックまたは誘導。
`PostToolUse`	ツール返却後。	エージェントに届く前に結果を検査します。denyはすべての結果をブロックします；選択したフィールドのみを削除することはできません。
`PermissionRequest`	エージェントがパーミッションを要求したとき。	組織固有のパーミッションルールを適用します。
`UserPromptSubmit`	送信されたプロンプトが続行される前。	禁止された指示を拒否するか、ワークフローガイダンスを追加します。
`Stop`	エージェントが終了しようとしたとき。	ローカルの検証ステップなど、到達可能な完了条件を要求します。
`SubagentStop`	サブエージェントが終了しようとしたとき。	委任された作業が親に返る前にゲートします。
`SessionStart` / `SessionEnd`	セッション境界で。	セッションレベルの状態を記録または確認します。

イベントの可用性とブロック動作はエージェントハーネスによって異なります。混合フリートでイベントに依存する前にエージェントハーネスを参照してください。

すべてのポリシーイベント名

SessionStart、SessionEnd、UserPromptSubmit、PreToolUse、PermissionRequest、PermissionDenied、PostToolUse、PostToolUseFailure、Notification、SubagentStart、SubagentStop、TaskCreated、TaskCompleted、Stop、StopFailure、TeammateIdle、InstructionsLoaded、ConfigChange、CwdChanged、FileChanged、WorktreeCreate、WorktreeRemove、PreCompact、PostCompact、Elicitation、ElicitationResult、UserPromptExpansion、PostToolBatch、Setup。

一般的なポリシーパターンの作成

保護されたパスへの書き込みをブロックする

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "block-generated-file-edits",
  description: "Require generated files to be changed through their generator",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();

    const filePath = String(ctx.toolInput?.file_path ?? "");
    if (!/(^|\/)(dist|generated)\//.test(filePath)) return allow();

    return deny("Edit the source and run the generator instead of changing generated output.");
  },
});

非ブロッキングのガイダンスを提供する

import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "prefer-reviewed-deploy-command",
  description: "Guide agents toward the reviewed deployment wrapper",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();

    const command = String(ctx.toolInput?.command ?? "");
    if (!/^kubectl\s+apply\b/.test(command.trim())) return allow();

    return instruct("Use ./scripts/deploy-reviewed instead of invoking kubectl directly.");
  },
});

セッション完了をゲートする

import { execFileSync } from "node:child_process";
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "require-clean-typecheck",
  description: "Require the project typecheck to pass before the agent finishes",
  match: { events: ["Stop"] },
  fn: async (ctx) => {
    const cwd = ctx.session?.cwd;
    if (!cwd) return allow();

    try {
      execFileSync("bunx", ["tsc", "--noEmit"], {
        cwd,
        stdio: "ignore",
        timeout: 8_000,
      });
      return allow();
    } catch {
      return deny("Fix the typecheck errors before finishing the task.");
    }
  },
});

Stop イベントが拒否されると、エージェントが再試行する可能性があります。現在の環境でエージェントが満たせる条件のみにゲートし、すべてのサブプロセスやネットワーク呼び出しに制限を設けてください。

ポリシーファイルの読み込み

コンベンションファイル

コンベンションファイルは自動的に読み込まれます：

<project>/.failproofai/policies/security-policies.ts
~/.failproofai/policies/personal-policies.mjs

プロジェクトとユーザーのポリシーディレクトリは両方読み込まれます。
ファイルは各ディレクトリ内でアルファベット順に読み込まれます。
ファイルは policies.js、policies.mjs、または policies.ts で終わる必要があります。
1つのファイル内で複数の customPolicies.add() 呼び出しがサポートされています。
ローカルモジュールからの相対インポートがサポートされています。
プロジェクトポリシーはコミットでき、同じルールがリポジトリに従います。

明示的なファイル

バリデーションや設定でエントリーファイルを直接指定する場合は明示的なパスを使用してください：

failproofai policies --install \
  --custom ./security.policies.ts \
  --custom ./workflow.policies.ts \
  --scope project

明示的なファイルが最初に読み込まれ、次にプロジェクトのコンベンションファイル、その後ユーザーのコンベンションファイルが読み込まれます。両方のパスで見つかったファイルは一度だけ読み込まれます。

バリデートとテスト

バリデーションはプロダクションローダーを通じてモジュールを実行し、少なくとも1つのポリシーが登録されていることを確認します。

failproofai policies --install \
  --custom ./.failproofai/policies/checkout-policies.ts \
  --scope project
failproofai policies

バリデーションは、ファイルの欠落、構文エラー、未解決のインポート、トップレベルの例外、およびモジュール読み込みタイムアウトを検出します。ただし、マッチロジックが正しいかどうかは検証されません。少なくとも以下のケースをテストしてください：

マッチして意図したポリシー理由を生成しなければならないアクション。
allow() を返さなければならない近しいが安全なアクション。
ツールフィールドの欠落または不正な形式。
代替コマンド構文、パス、クォート、大文字小文字、および空白。
利用できないサブプロセスまたはネットワーク依存関係。

観察 → ポリシー でカスタムポリシーに結果を帰属させてください。異なる組み込みポリシーが決定を行った場合、ブロックされたテストは十分ではありません。

ランタイム動作

組み込みポリシーはカスタムポリシーより先に評価されます。
最初の deny でそれ以降のポリシー評価が停止します。
どのポリシーもイベントを拒否しない場合、複数の instruct 結果を組み合わせることができます。
ポリシー関数の実行期限は10秒です。
例外またはタイムアウトはログに記録され、allow() として扱われます。
読み込みに失敗したコンベンションファイルはスキップされ、他のカスタムファイルと組み込みポリシーは続行されます。
トップレベルのモジュール読み込みにも10秒の期限があります。
クラウド観察モードはポリシーを実行しますが、非許可の決定を施行せずに記録します。

ポリシーモジュールは決定論的かつ高速に保ちます。トップレベルのネットワーク呼び出しやサーバー起動は避けてください。fn 内の処理を制限し、依存関係の失敗をキャッチし、その失敗がアクションを許可するか拒否するかを意図的に選択してください。

APIエクスポート

エクスポート	目的
`customPolicies.add(policy)`	モジュール読み込み時にカスタムポリシーを登録します。
`allow(reason?)`	操作を許可します。
`instruct(reason)`	操作を許可し、サポートされている場合はガイダンスを提供します。
`deny(reason)`	サポートされている場所で操作をブロックします。
`getCustomHooks()`	モジュールレジストリに現在登録されているポリシーを返します。
`clearCustomHooks()`	そのレジストリをクリアします。主にテストとローダー向けです。

TypeScriptは PolicyContext、PolicyResult、CustomHook、PolicyDecision、および PolicyFunction をエクスポートします。