Agent harnesses - Failproof AI

Harness 是 agent 实际运行的环境。Failproof AI 支持十二种 harness，分为两类：

编码 CLI（10 种）—— Claude Code、Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi、Factory Droid、Devin CLI、Antigravity CLI、Goose
对话与助手网关（2 种）—— Hermes（Slack、Telegram、cron）、OpenClaw（自托管助手）

无论 agent 在哪个 harness 中运行，相同的策略和相同的会话历史均适用。一个适配器层会在任何策略执行之前，将每个 harness 的原生事件名称、工具名称和工具输入字段映射到 29 个规范事件。对于不在上述十二种 harness 中运行的 agent，可以直接通过 Python SDK 进行插桩。这是一种不同的契约，值得明确说明：SDK 提供追踪、会话、评估和审计功能，但它本身不执行策略。 若要在不安全操作执行之前将其阻止，需要在运行时的工具边界处设置执行钩子；请联系我们，我们将为您进行映射。

Harness	支持的钩子范围
Claude Code	User、project、local
Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi	User、project
Factory Droid、Devin CLI、Antigravity CLI、Goose	User、project
Hermes、OpenClaw	User

每个集成在策略执行前会对其原生钩子事件名称、工具名称和工具输入字段进行规范化。策略只能作用于 harness 所暴露的事件；请在实际部署的 harness 及其版本上测试回合结束和指令行为。

执行能力

“阻止”意味着当前适配器返回的裁决由指定 harness 消费。工具执行后的阻止可能会替换展示给模型的结果，但无法撤销已发生的工具副作用。

Harness	已验证的阻止事件	仅观测或非阻止说明
Claude Code	`PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PreCompact` 及若干任务/配置事件	`PostToolUse`、会话生命周期、通知及失败后事件仅供观测。
Codex	`PreToolUse`、`PermissionRequest`、`UserPromptSubmit`、`Stop`、`SubagentStop`、`PostToolUse`	工具执行后阻止会在执行后替换结果；会话启动和压缩事件在当前适配器中仅供观测。
GitHub Copilot CLI	`PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PostToolUse`	工具执行后阻止会在执行后替换结果；会话和通知事件仅供观测。
Cursor	`PreToolUse`、`UserPromptSubmit`、`Stop`	`PostToolUse` 和会话事件仅供观测。
OpenCode	`PreToolUse`	工具执行后和生命周期事件仅供观测；当前的 stop 处理是对后续回合的引导，而非已验证的门控。
Pi	`PreToolUse`、`UserPromptSubmit`	工具执行后和生命周期事件仅供观测；stop 引导适用于后续回合。
Hermes	`PreToolUse`	工具执行后、会话和子 agent stop 的裁决不作为门控。
OpenClaw	`PreToolUse`、`UserPromptSubmit`、`Stop`	工具执行后、会话、子 agent stop 和压缩事件仅供观测。
Factory Droid	`PreToolUse`、`UserPromptSubmit`、`Stop`、`PreCompact`	工具执行后和子 agent stop 裁决仅供观测。
Devin CLI	`PreToolUse`、`UserPromptSubmit`、`Stop`、条件性 `PermissionRequest`	权限钩子并非在所有权限模式下都会运行；工具执行后和会话事件仅供观测。
Antigravity CLI	`PreToolUse`、`Stop`	用户提示和工具执行后裁决仅供观测；提示指令仍可被注入。
Goose	`PreToolUse`	用户提示、工具执行后和会话事件仅供观测。上游存在原生阻止 stop 钩子，但当前适配器未安装。

功能因版本而异。升级 agent CLI 后请重新测试，尤其是当策略依赖提示、stop、权限或工具执行后行为，而非通用的工具执行前门控时。

安装捕获与策略钩子

控制台
CLI

打开 Administration → Keys，创建一个具有 events:add 和 policies:pull 权限的密钥，并以机器或环境命名。
在目标机器上，使用显示的密钥连接本地 CLI 并安装 harness 钩子。
启动一个新的 agent 会话，然后在 Observe → Events 下确认其钩子和会话事件。
打开相同时间窗口的 Observe → policy，确认策略决策已归因到该机器。

连接从机器密钥开始。在复制其密钥之前，请确认它同时包含数据采集和策略下发权限。

安装钩子后，事件流应显示来自所连接机器和环境的新事件。

最后，验证策略决策是否归因到同一台机器。这可以确认 harness 在上报追踪事件的同时，也在上报策略活动。

为所有检测到的 harness 安装钩子：

failproofai config \
  --connect https://app.befailproof.ai \
  --token <machine-key>
failproofai policies --install

或指定 harness 名称和配置范围：

failproofai policies --install \
  --cli claude codex cursor \
  --scope user

Project 范围将钩子配置与代码仓库绑定。User 范围覆盖跨仓库的工作。Claude Code 还支持 local 范围；支持情况因 harness 而异，CLI 会拒绝不受支持的组合。验证机器及其事件：

failproofai config --status
failproofai flush --wait
fp events --since 1h --event-type hook_triggered,hook_completed

添加非默认会话路径

控制台
CLI

额外路径在机器上注册，而非在云端。添加路径后，打开 Observe → Sessions，筛选到该机器的环境，并确认来自新路径的会话已显示。打开一个会话，在将其用于审计之前，检查 agent、harness 和事件时间戳。

添加带有可选标签的路径，然后查看已配置的路径：

failproofai harness add-path claude checkout=/srv/checkout/.claude
failproofai harness list claude
failproofai backfill --since 7d --dry-run
failproofai backfill --since 7d

使用 failproofai harness remove-path claude checkout 删除路径。

安装后运行一个新会话。在扩大部署范围之前，请同时验证实时事件流和实际的策略决策。

​执行能力

​安装捕获与策略钩子

​添加非默认会话路径

执行能力

安装捕获与策略钩子

添加非默认会话路径