カスタムポリシー

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

カスタムポリシーを作成する

ダッシュボード
CLI

Admin → policy editor に移動し、New policy を選択して、防止したい障害を説明します。
ポリシーソースを追加し、エディターで期待される一致ケースと安全な非一致ケースをテストします。すべてのバリデーションエラーを解消してください。
ドラフトを保存し、Publish version を選択してイミュータブルなバージョンを作成します。
Admin → enforcement に移動し、テストマシンに observe モードでバージョンをデプロイし、適用前に Observe → policy で判断内容を確認します。

.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 を実行し、Observe → policy で帰属する判断内容を確認します。

狭いルールから始める

このポリシーは、コマンドが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.",
    );
  },
});

良いポリシーは、一文で説明できるほど狭いものです。エージェントの意図ではなく、観測可能なアクションにマッチさせ、ルールが適用されない場合はすぐに 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

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

一致して意図したポリシー理由を生成するアクションを1つ。
allow() を返す必要のある近いが安全なアクションを1つ。
欠落または不正なツールフィールド。
代替コマンド構文、パス、引用符、大文字小文字、空白。
利用不可能なサブプロセスまたはネットワーク依存関係。

Observe → policy で結果をカスタムポリシーに帰属させてください。異なる組み込みポリシーが判断を行った場合、ブロックされたテストだけでは不十分です。

ランタイムの動作

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

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

APIエクスポート

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

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