> ## Documentation Index
> Fetch the complete documentation index at: https://ccsafetynet.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CC Safety Net 如何与各智能体集成

> CC Safety Net 的十二种智能体使用的四种集成模型：stdin hook 子进程、智能体加载的插件、进程内 Pi 扩展和 Amp Code 事件插件。

配置或调试集成时请使用本页。它说明各智能体如何调用 CC Safety Net 并接收判定。面向用户的生命周期见<a href="/docs/zh-Hans/guides/how-it-works">工作原理</a>。

CC Safety Net 支持十二种编码智能体，但集成方式并不完全相同。共有四种集成模型。了解智能体使用的模型有助于调试未触发的 hook，并确定配置位置。

各集成的安装或删除命令见<a href="/docs/zh-Hans/installation">安装</a>。本页每种模型都进入<a href="/docs/zh-Hans/guides/architecture">架构</a>中统一定义的防护。

## 按智能体划分的集成模型

| 模型                 | 智能体                                                                                     | 工作方式                                                                                                                       |
| ------------------ | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Stdin hook 子进程** | Antigravity CLI、Claude Code、Cursor、Gemini CLI、GitHub Copilot CLI、Hermes Agent、Kimi Code | 每次工具调用时，智能体把调用作为 JSON 写入 stdin，并运行短生命周期进程 `cc-safety-net hook <flag>`。CC Safety Net 分析调用，在 stdout 打印智能体专用 deny 对象，并以 0 退出。 |
| **智能体加载的插件**       | Codex、OpenClaw、OpenCode                                                                 | 智能体按自己的软件包格式加载 CC Safety Net 插件。这些智能体没有 `hook` 标志。                                                                         |
| **进程内扩展**          | Pi                                                                                      | Pi 直接在 Pi 进程中加载 CC Safety Net 扩展并在内存中调用，无子进程、stdin 或 stdout。                                                               |
| **事件插件**           | Amp Code                                                                                | Amp 从账户的 Personal Plugins 仓库加载托管的个人插件，并在进程内向其发送每个 `tool.call` 事件。                                                          |

## Stdin hook 子进程智能体

这七种智能体使用运行时 `hook <flag>` 命令，并从 stdin 读取 JSON。各智能体对执行前事件和命令工具有不同名称，也要求不同的 stdout deny 形式：

| 智能体                | 运行时标志                    | Hook 事件         | 命令工具                 | Deny 输出形式                                                         |
| ------------------ | ------------------------ | --------------- | -------------------- | ----------------------------------------------------------------- |
| Antigravity CLI    | `-ac` / `--agy-cli`      | `PreToolUse`    | `run_command`        | `{ "decision": "deny", "reason": … }`                             |
| Claude Code        | `-cc` / `--coding-cli`   | `PreToolUse`    | `Bash`, `PowerShell` | `hookSpecificOutput.permissionDecision: "deny"`                   |
| Cursor             | `-cu` / `--cursor`       | `preToolUse`    | `Shell`              | `{ "permission": "deny", "user_message": …, "agent_message": … }` |
| Gemini CLI         | `-gc` / `--gemini-cli`   | `BeforeTool`    | `run_shell_command`  | `{ "decision": "deny", "reason": …, "systemMessage": … }`         |
| GitHub Copilot CLI | `-cp` / `--copilot-cli`  | `PreToolUse`    | `bash`, `Bash`       | `{ "permissionDecision": "deny", "permissionDecisionReason": … }` |
| Hermes Agent       | `-ha` / `--hermes-agent` | `pre_tool_call` | `terminal`           | `{ "action": "block", "message": … }`                             |
| Kimi Code          | `-kc` / `--kimi-code`    | `PreToolUse`    | `Bash`               | `hookSpecificOutput.permissionDecision: "deny"`                   |

<Note>由于事件和 deny 格式不同，CC Safety Net 会按智能体发出正确形式。例如，Gemini CLI 要求以 0 退出并返回 `decision`/`systemMessage` 对象，而不是 Claude Code 的 `hookSpecificOutput`。无需配置输出格式，传入的标志会选择格式。</Note>

### 使用共享 Coding CLI hook

`hook --coding-cli`（短标志 `-cc`）是 Claude 形式 hook 的规范名称。它称为“Coding CLI”而不是“Claude Code”，因为 Claude Code 插件和 Codex 插件都调用此二进制入口点。

`hook --claude-code` 是保留的旧别名，不在 `hook --help` 中宣传。不要在新配置中使用。

另有三个智能体保留省略 `hook` word 的旧**顶层**形式：`cc-safety-net -cc` / `--claude-code`、`-gc` / `--gemini-cli` 和 `-cp` / `--copilot-cli`。规范 `--coding-cli` 有意不是顶层标志，单独运行 `cc-safety-net --coding-cli` 会报 `Unknown option: --coding-cli`。

<Note>`statusline` 命令与 hook 无关，仍要求 `--claude-code` 或 `-cc`。见<a href="/docs/zh-Hans/configuration/status-line">状态行</a>。</Note>

### Hook 配置位置

七种智能体中有四种由 CC Safety Net 直接写入文件：三种写 hook 配置条目，Hermes Agent 写托管插件。另外三种通过自己的插件或扩展分发渠道连接，再调用 stdin hook：

| 智能体                | 配置位置和加载机制                                                                                                                                                                                                                                                                                                                                          |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Antigravity CLI    | 直接写入：`~/.gemini/config/hooks.json` 中运行 `npx -y cc-safety-net hook --agy-cli` 的托管 `PreToolUse` 条目                                                                                                                                                                                                                                                   |
| Claude Code        | 插件 `cc-safety-net@cc-marketplace`；插件状态位于 `~/.claude/settings.json` 的 `enabledPlugins`                                                                                                                                                                                                                                                              |
| Cursor             | 直接写入：`~/.cursor/hooks.json` 中运行 `npx -y cc-safety-net hook --cursor` 的托管 `preToolUse` 条目，含 `timeout: 30` 和 `failClosed: true`。配置全局有效，覆盖所有项目中的 Cursor IDE 和 Cursor CLI                                                                                                                                                                              |
| Gemini CLI         | 从 `gemini-safety-net` 仓库加载的扩展 `gemini-safety-net`，不是 `cc-marketplace` 插件                                                                                                                                                                                                                                                                           |
| GitHub Copilot CLI | 插件 `cc-safety-net@cc-marketplace`，或 `~/.copilot/hooks` 下的 hook 文件/ Copilot 配置中的内联 hook。Hook 支持受版本限制，详情见<a href="/docs/zh-Hans/installation">安装</a>。`disableAllHooks: true` 会禁用所有 hook                                                                                                                                                                   |
| Hermes Agent       | 直接写入：`~/.hermes/plugins/cc-safety-net/` 下的托管 Python 插件（`__init__.py` 和 `plugin.yaml`；设置时 Hermes home 为 `$HERMES_HOME`），再运行 `hermes plugins enable cc-safety-net --no-allow-tool-override`。启用状态记录在 Hermes `config.yaml` 的 `plugins.enabled`                                                                                                         |
| Kimi Code          | 直接写入：`~/.kimi-code/config.toml`（或 `$KIMI_CODE_HOME/config.toml`）中的 `[[hooks]]` 块，运行 `npx -y cc-safety-net hook --kimi-code`。另一种方式是在 Kimi Code 内运行 `/plugins install https://github.com/kenryu42/cc-safety-net` 安装原生 Kimi Code 插件；manifest 运行相同的 hook 入口（`node ./dist/bin/cc-safety-net.js hook --kimi-code`、`PreToolUse` 事件、`Bash` matcher、30 秒超时） |

### Hermes Agent 如何到达 hook

Hermes 不从 hook 配置运行命令。CC Safety Net 安装由 Hermes 在进程内加载的托管 Python 插件，并注册 `pre_tool_call` handler。每次受支持调用时，handler 运行 `npx -y cc-safety-net hook --hermes-agent`，并把调用作为 JSON 写入 stdin。空 stdout 表示允许；`{ "action": "block", "message": … }` 表示阻止，Hermes 把消息作为工具结果显示给模型。

插件转发四个工具：用于命令分析的 `terminal`、用于受保护写入的 `write_file` 和 `patch`，以及用于受保护读取的 `read_file`。其他 Hermes 工具不转发，也不获得判定。

Hermes 会忽略抛出异常的插件 callback，因此插件把每种失败显式转为阻止：PATH 中缺少 `npx`、spawn 失败、超时（30 秒，并终止分析器整个 process group）、非零退出码，或无法读取/意外输出。无法读取 Hermes 会话目录也会阻止，因为分析错误目录会取消所有路径范围保护。

两个目录细节很重要。对 `terminal` 调用，插件使用 Hermes 自己的每会话 cwd 记录，即会话 `cd` 状态，因此分析目录就是命令实际运行目录；只有 `terminal` 调用带有不可用的 `workdir` 时才会 fail closed。分析器子进程从主目录启动，而不是 Hermes 工作目录，因此 `npx` 绝不会用仓库本地 `cc-safety-net` 替代真实软件包。

每个托管文件首行都有 CC Safety Net 标记，安装程序拒绝覆盖没有标记的文件。卸载会先运行 `hermes plugins disable cc-safety-net` 再删除文件，因为 Hermes 只能解析仍在磁盘上的插件。安装和卸载都要重启 Hermes 后才生效。命令见<a href="/docs/zh-Hans/installation">安装</a>。

与 Pi 不同，`doctor` 完全从磁盘检测 Hermes Agent：检查托管插件目录和 Hermes `config.yaml` 中的 `plugins.enabled` 列表，不做 runtime probe。

## 智能体加载的插件

### Codex

Codex 从 `cc-marketplace` marketplace 加载 `cc-safety-net@cc-marketplace` 插件。插件注册运行共享 `hook --coding-cli` 入口点的 `PreToolUse` hook，因此 Codex 没有自己的 `hook` 标志。

Codex 不运行未信任 hook，所以在 Codex 中标为可信前，插件 hook 不生效。步骤见<a href="/docs/zh-Hans/installation">安装</a>。

### OpenClaw

OpenClaw 把 CC Safety Net 作为原生插件**进程内**加载。插件目录有三个文件：运行时入口 `index.js`（所有依赖内联的自包含 bundle，因为本地目录安装没有 `node_modules`）、OpenClaw 在加载代码前验证的 `openclaw.plugin.json` manifest，以及 `openclaw.extensions` 指向入口的 `package.json`。没有 `hook` 标志或 JSON-over-stdio。

插件为 `exec` 工具注册 `before_tool_call` handler。只覆盖 `exec`，不转发其他 OpenClaw 工具。Handler 返回无判定（允许）或 `{ block: true, blockReason }`，绝不改写工具参数。

插件通过 OpenClaw runtime API 解析智能体 workspace，并把它同时用作策略和执行目录；调用中的 `workdir` 必须解析在 workspace 内。格式错误事件、缺失或空命令、无法解析 workspace、workspace 外的 `workdir` 或已取消调用都会 fail closed。`host` 不是 `auto` 或 `gateway` 的 `exec` 也会阻止，因为只有这两个值被证明在 workspace 描述的本地 Gateway 文件系统执行。`host: "auto"` 或无 `host` 的调用按本地 Gateway 调用分析；插件不检查 OpenClaw 实际路由位置。

OpenClaw 管理插件状态，因此安装使用它自己的 CLI：`openclaw plugins install <packaged dir> --force`，然后 `openclaw plugins enable cc-safety-net`。任何 `--force` 前，CC Safety Net 验证目标扩展目录只含自有托管文件，绝不覆盖或删除无法证明属于自己的插件。安装后运行 `openclaw plugins inspect cc-safety-net --runtime --json`，只有 `loaded` 状态视为成功，避免已启用但 bundle 损坏的插件静默失去保护。

安装副本位于 `<state dir>/extensions/cc-safety-net/`。State dir 在设置时使用 `OPENCLAW_STATE_DIR`；否则使用 `OPENCLAW_CONFIG_PATH` 所指文件的所在目录；两者都未设置时使用 `~/.openclaw`。启用状态位于 state dir 中的 `openclaw.json`，或位于 `OPENCLAW_CONFIG_PATH` 指向的文件中：全局 `plugins.enabled`、`plugins.allow` 和 `plugins.deny` 列表，以及 `plugins.entries.cc-safety-net.enabled` 都会参与判定。设置 `plugins.allow` 时必须包含 `cc-safety-net`。

安装或卸载后重启 OpenClaw Gateway。Manifest 在启动时激活插件（`activation: { onStartup: true }`），运行中的 Gateway 不会读取更改。命令见<a href="/docs/zh-Hans/installation">安装</a>。

### OpenCode

OpenCode 把 CC Safety Net 作为实现自身 `@opencode-ai/plugin` 约定的插件对象**进程内**加载。插件在 `~/.config/opencode/opencode.json`（或 `.jsonc`）的 `plugin` 数组中声明，并执行两项工作：

1. 实现 `tool.execute.before`。OpenCode 在每次工具执行前调用它。CC Safety Net 分析调用，并在命令具有破坏性时抛出拒绝。没有 JSON-over-stdio。
2. 实现 `config` hook，把 CC Safety Net 内置命令注入 OpenCode 命令集，但不覆盖用户已定义命令。

OpenCode 可能提供过期插件缓存，因此 wiring 更改可能要清缓存后才生效。见<a href="/docs/zh-Hans/installation">安装</a>。

## Pi 扩展

Pi 把 CC Safety Net 作为进程内扩展加载。扩展由软件包 `pi.extensions` 字段声明，并在 `~/.pi/agent/settings.json` 中记录为软件包来源 `npm:cc-safety-net`。它执行两项工作：

1. **注册 `tool_call` 事件 handler**（`pi.on('tool_call')`），在 shell 工具运行前拦截并使用共享引擎分析命令。破坏性命令返回阻止结果，不跨进程边界。
2. **注册 `/cc-safety-net` 内置命令**，用于在 Pi 内交互管理 rulebook。

### Pi 保护的工具

扩展拦截内置 **`bash`** 工具和自定义 **`Shell`** 工具（例如 pi-grok-cli 提供的工具）。对 `Shell`，它相对会话 cwd 解析调用的 `working_directory`，再分析命令，因此 worktree 放宽和 `rm -rf` 目标分类等 cwd 感知规则正常适用。工具调用格式错误时 fail closed。

| 工具      | 命令字段      | 工作目录                             |
| ------- | --------- | -------------------------------- |
| `bash`  | `command` | 会话 cwd                           |
| `Shell` | `command` | `working_directory`（相对会话 cwd 解析） |

### 检测 Pi

没有可检查的 hook 配置文件，因此 `doctor` 通过 runtime probe 检测 Pi：启动 `pi` 并询问扩展是否已加载和启用。这就是 Pi 已安装但 probe 无法运行时，`doctor` 中 Pi 状态可能为 `n/a` 的原因。

## Amp Code 事件插件

Amp Code 把 CC Safety Net 作为**个人插件**加载：Amp 账户托管的 Personal Plugins 仓库中一个名为 `cc-safety-net.ts` 的自包含文件。插件通过 `@ampcode/plugin` API 订阅 Amp `tool.call` 事件，返回 `allow` 或带消息的 `reject-and-continue`。它和 Pi、OpenClaw、OpenCode 一样在进程内运行。个人插件跟随账户而不是单台机器，因此也覆盖在 Amp Orb 等远程执行器上运行的线程。

`install --amp` 把 artifact 发布到该仓库：确认账户有可写的 Personal Plugins 仓库（`amp plugins repositories --json`），把仓库克隆到一次性 checkout（`amp clone user-plugins`），写入文件，然后提交并推送。文件含 CC Safety Net 托管 header，用于证明 CC Safety Net 可以安全替换它；该 header 在个人仓库内强制执行，仓库里出现非托管的 `cc-safety-net.ts` 会使安装失败。旧的本地系统插件 `~/.config/amp/plugins/cc-safety-net.ts` 若残留托管副本会被删除，因为本地插件会遮蔽个人插件；那里存在非托管本地文件同样会使安装失败。设置和删除命令见<a href="/docs/zh-Hans/installation">安装</a>。

### 嵌入的策略快照

发布的 artifact 携带用户策略的快照：文件末尾追加一条 `globalThis.__CC_SAFETY_NET_EMBEDDED_POLICY__ = …` 赋值，策略在写入前先归一化。运行时只有在自身没有策略文件的机器上（Orb 的空 home 目录）快照才生效；有策略文件的机器即使文件无效，也保持自身行为。审计保留、用户 rulebook 和项目范围策略不会嵌入，策略修改要在下一次 `install` 或 `update` 时才发布。

Amp 启动时读取插件，因此新发布或删除的插件要重新加载 Amp 才会影响当前会话。

### 检测 Amp Code

`doctor` 通过解析 `amp plugins list` 输出检测插件；个人范围插件显示为 `✓ cc-safety-net (User Plugins) <status>`。该输出不含版本号，因此 `doctor` 不会报告 Amp 的版本偏差——`cc-safety-net update` 始终重新发布当前 artifact。

### Amp Code 覆盖限制

* Amp 不定义订阅同一 `tool.call` 事件的多个插件的执行顺序。CC Safety Net 评估它收到的输入。如果另一插件在 CC Safety Net 已允许后改写输入，CC Safety Net 不能重新评估。

## 验证集成

`npx cc-safety-net doctor` 报告每个智能体检测到的集成和配置路径，并在保护活动时运行自检。选项和退出行为见<a href="/docs/zh-Hans/reference/cli-commands">CLI 命令</a>。

特定智能体的 hook 未触发时，请按<a href="/docs/zh-Hans/guides/troubleshooting">故障排除</a>中的智能体步骤处理。

## 后续阅读

技术指南从面向用户的生命周期逐步深入设计依据。本页是第 2 步。

* 上一页：<a href="/docs/zh-Hans/guides/how-it-works">工作原理</a>从头到尾说明一次工具调用的相同拦截过程。
* 下一页：<a href="/docs/zh-Hans/guides/architecture">架构</a>说明本页各集成进入的防护，包括有序阶段表。
* 然后：<a href="/docs/zh-Hans/guides/analysis-engine">分析引擎</a>说明命令到达分类器后的准确分类方式。
* 最后：<a href="/docs/zh-Hans/guides/design-principles">设计原则</a>说明集成模型和防护顺序的设计依据。

相关页面：<a href="/docs/zh-Hans/installation">安装</a>提供设置和删除命令，<a href="/docs/zh-Hans/guides/troubleshooting">故障排除</a>提供按智能体的诊断方法。