> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent harnesses
> 在支持的 Agent CLI 中捕获会话并执行策略。
Failproof AI 支持 Claude Code、Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi、Hermes、OpenClaw、Factory Droid、Devin CLI、Antigravity CLI 以及 Goose。
| Harness | 支持的 hook 范围 |
| --------------------------------------------- | ------------------ |
| 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 |
每个集成在策略执行前，会将其原生 hook 事件名称、工具名称及工具输入字段进行规范化处理。策略只能对 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` | 工具后置和生命周期事件仅供观察；当前的停止处理是对后续轮次的指导，而非已验证的门控。 |
| Pi | `PreToolUse`、`UserPromptSubmit` | 工具后置和生命周期事件仅供观察；停止指导适用于后续轮次。 |
| Hermes | `PreToolUse` | 工具后置、会话和子代理停止裁决不作为门控。 |
| OpenClaw | `PreToolUse`、`UserPromptSubmit`、`Stop` | 工具后置、会话、子代理停止及压缩事件仅供观察。 |
| Factory Droid | `PreToolUse`、`UserPromptSubmit`、`Stop`、`PreCompact` | 工具后置和子代理停止裁决仅供观察。 |
| Devin CLI | `PreToolUse`、`UserPromptSubmit`、`Stop`、有条件的 `PermissionRequest` | 并非所有权限模式下都会触发权限 hook；工具后置和会话事件仅供观察。 |
| Antigravity CLI | `PreToolUse`、`Stop` | 用户提示和工具后置裁决仅供观察；提示指令仍可注入。 |
| Goose | `PreToolUse` | 用户提示、工具后置和会话事件仅供观察。上游存在原生的阻断停止 hook，但当前适配器未安装。 |
各项能力对版本敏感。升级 Agent CLI 后请重新测试，尤其是当策略依赖提示、停止、权限或工具后置行为而非通用的工具前置门控时。
## 安装捕获与策略 hook
1. 打开 **Administration → Keys**，创建一个具有 `events:add` 和 `policies:pull` 权限的密钥，并以机器或环境命名。
2. 在目标机器上，使用显示的密钥连接本地 CLI 并安装 harness hook。
3. 启动一个新的 Agent 会话，然后在 **Observe → Events** 下确认其 hook 和会话事件。
4. 打开同一时间窗口下的 **Observe → policy**，确认策略决策已归属到该机器。
连接从机器密钥开始。在复制其密钥前，请确认它同时包含摄取和策略下发权限。
安装 hook 后，事件流应显示来自所连接机器和环境的新事件。
最后，验证策略决策已归属到同一台机器。这可以确认 harness 正在上报策略活动以及追踪事件。
为所有检测到的 harness 安装 hook：
```bash theme={null}
failproofai config \
--connect https://app.befailproof.ai \
--token
failproofai policies --install
```
或者指定 harness 名称和配置范围：
```bash theme={null}
failproofai policies --install \
--cli claude codex cursor \
--scope user
```
project 范围将 hook 配置保存在仓库中。user 范围覆盖跨仓库的工作。Claude Code 还支持 local 范围；支持情况因 harness 而异，CLI 会拒绝不支持的组合。
验证机器及其事件：
```bash theme={null}
failproofai config --status
failproofai flush --wait
fp events --since 1h --event-type hook_triggered,hook_completed
```
## 添加非默认会话路径
额外路径注册在机器本地，而非云端。添加后，打开 **Observe → Sessions**，按机器所属环境过滤，确认来自新路径的会话已出现。打开某个会话，在将其用于审计前，检查 Agent、harness 及事件时间戳。
添加带可选标签的路径，然后查看已配置的路径：
```bash theme={null}
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` 移除路径。
安装后运行一次新会话。在扩大部署范围之前，请同时验证实时事件流和实际的策略决策。