自定义策略

自定义策略将追踪记录或审计中发现的故障模式转化为 Agent 运行时的决策。策略可以允许某个操作、向 Agent 提供指导，或在操作再次引发问题之前予以拒绝。当行为取决于您自己的工具、路径、命令、环境或操作规则时，请使用自定义策略。在创建之前，请先查阅内置策略目录，避免重复已有的控制项。

编写自定义策略

控制台
CLI

前往 Admin → 策略编辑器，选择 新建策略，并描述您希望防止的故障。
添加策略源码，然后在编辑器中测试预期匹配项和安全的非匹配项，解决所有验证错误。
保存草稿并选择 发布版本，创建一个不可变版本。
前往 Admin → 执行，以观察模式将版本部署到测试机器，并在 Observe → policy 下验证其决策，然后再执行强制执行。

创建 .failproofai/policies/checkout-policies.ts，文件名必须以 policies.js、policies.mjs 或 policies.ts 结尾。
使用 customPolicies.add() 注册一个或多个策略。
使用 failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project 验证并安装该文件。
触发一个匹配的操作和一个安全的操作，运行 failproofai policies，然后在 Observe → policy 下检查归因决策。

从精准规则开始

以下策略仅在命令指向生产环境时才阻止破坏性的 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.",
    );
  },
});

好的策略应精准到可以用一句话说清楚。匹配可观察到的操作，而非您期望 Agent 具有的意图——一旦规则不适用，立即返回 allow()。

选择决策类型

辅助函数	结果	使用场景
`allow(reason?)`	操作继续执行。	策略不适用，或操作是安全的。
`instruct(reason)`	在支持的 harness 中，操作继续执行并附带指导。	希望引导 Agent 采用更好的方式，而不强制执行不变量。
`deny(reason)`	在事件和 harness 支持阻止的情况下，操作被拦截。	操作不得继续执行。

原因说明是为需要从中恢复的 Agent 而写的，请解释检测到了什么以及 Agent 应该怎么做。

不要将 instruct() 用于安全边界。指导的传达方式因 Agent harness 而异。当操作必须被阻止时，请使用 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、工作目录、记录路径、权限模式和 harness 元数据。
`cli`	`string \| undefined`	来源 Agent harness，如 `claude`、`codex` 或 `cursor`。
`params`	`Record<string, unknown>`	内置策略参数，自定义策略当前接收空对象。

请将所有可选值视为真正可选的。不同的 Agent 版本和事件类型不一定提供相同的字段。

常见工具输入

Failproof AI 对所有支持 harness 中的常用工具输入进行了规范化，因此策略通常可以使用统一的输入结构。

工具	常见字段
`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`	工具返回之后。	在结果到达 Agent 之前进行检查。deny 会阻止整个结果，不支持选择性编辑字段。
`PermissionRequest`	Agent 请求权限时。	应用组织特定的权限规则。
`UserPromptSubmit`	提交的提示词继续执行之前。	拒绝被禁止的指令或添加工作流指导。
`Stop`	Agent 尝试结束时。	要求满足可达的完成条件，例如本地验证步骤。
`SubagentStop`	子 Agent 尝试结束时。	在委托工作返回父级之前进行把关。
`SessionStart` / `SessionEnd`	会话边界处。	记录或检查会话级状态。

事件的可用性及阻止行为取决于 Agent harness。在混合机群中依赖某个事件之前，请参阅 Agent harnesses。

所有策略事件名称

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 事件可能导致 Agent 重试。请只对 Agent 在当前环境中能够满足的条件进行把关，并为所有子进程或网络调用设置超时限制。

加载策略文件

约定文件

约定文件会自动加载：

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

项目和用户策略目录均会加载。
每个目录内的文件按字母顺序加载。
文件必须以 policies.js、policies.mjs 或 policies.ts 结尾。
支持在一个文件中多次调用 customPolicies.add()。
支持从本地模块进行相对导入。
项目策略可以提交到代码库，使相同规则随仓库一起流转。

显式文件

当验证或配置需要直接指定入口文件时，使用显式路径：

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

显式文件优先加载，其次是项目约定文件，最后是用户约定文件。通过两种路径均发现的文件只加载一次。

验证与测试

验证会通过生产加载器执行模块，并确认其至少注册了一个策略。

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

验证可捕获缺失文件、语法错误、未解析的导入、顶层异常以及模块加载超时。但它无法证明匹配逻辑是否正确。至少测试以下情况：

一个必须匹配并产生预期策略原因的操作。
一个相近但安全的操作，必须返回 allow()。
缺失或格式错误的工具字段。
不同的命令语法、路径、引号、大小写和空白符。
不可用的子进程或网络依赖。

在 Observe → policy 下将结果归因到您的自定义策略。如果是另一个内置策略做出了决策，仅有被阻止的测试是不够的。

运行时行为

内置策略先于自定义策略执行。
第一个 deny 会停止后续所有策略的评估。
当没有策略拒绝事件时，多个 instruct 结果可以合并。
策略函数的执行超时限制为 10 秒。
抛出的异常或超时会被记录，并被视为 allow()。
加载失败的约定文件会被跳过，其他自定义文件和内置策略继续运行。
顶层模块加载同样有 10 秒的超时限制。
云观察模式会运行策略，但记录非 allow 决策而不强制执行。

保持策略模块的确定性和执行速度。避免顶层网络调用或启动服务器。在 fn 内部限制操作范围，捕获依赖失败，并有意识地决定该失败应该 allow 还是 deny 操作。

API 导出

导出	用途
`customPolicies.add(policy)`	在模块加载时注册自定义策略。
`allow(reason?)`	允许操作。
`instruct(reason)`	允许操作并在支持的环境中提供指导。
`deny(reason)`	在支持的环境中阻止操作。
`getCustomHooks()`	返回模块注册表中当前已注册的策略。
`clearCustomHooks()`	清空该注册表，主要用于测试和加载器。

TypeScript 导出 PolicyContext、PolicyResult、CustomHook、PolicyDecision 和 PolicyFunction。

部署自定义策略

发布版本、以观察模式部署、验证决策，然后进入强制执行阶段。

Connect your agents

Reference

编写自定义策略

从精准规则开始

选择决策类型

策略对象

策略上下文

常见工具输入

选择事件

编写常见策略模式

阻止对受保护路径的写入

提供非阻止性指导

把关会话完成

加载策略文件

约定文件

显式文件

验证与测试

运行时行为

API 导出

部署自定义策略

​编写自定义策略

​从精准规则开始

​选择决策类型

​策略对象

​策略上下文

​常见工具输入

​选择事件

​编写常见策略模式

​阻止对受保护路径的写入

​提供非阻止性指导

​把关会话完成

​加载策略文件

​约定文件

​显式文件

​验证与测试

​运行时行为

​API 导出

部署自定义策略

编写自定义策略

从精准规则开始

选择决策类型

策略对象

策略上下文

常见工具输入

选择事件

编写常见策略模式

阻止对受保护路径的写入

提供非阻止性指导

把关会话完成

加载策略文件

约定文件

显式文件

验证与测试

运行时行为

API 导出