按智能体划分的集成模型
Stdin hook 子进程智能体
这七种智能体使用运行时hook <flag> 命令，并从 stdin 读取 JSON。各智能体对执行前事件和命令工具有不同名称，也要求不同的 stdout deny 形式：
由于事件和 deny 格式不同，CC Safety Net 会按智能体发出正确形式。例如，Gemini CLI 要求以 0 退出并返回
decision/systemMessage 对象，而不是 Claude Code 的 hookSpecificOutput。无需配置输出格式，传入的标志会选择格式。使用共享 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。
Hook 配置位置
七种智能体中有四种由 CC Safety Net 直接写入文件：三种写 hook 配置条目，Hermes Agent 写托管插件。另外三种通过自己的插件或扩展分发渠道连接，再调用 stdin hook：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 后才生效。命令见安装。
与 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 不生效。步骤见安装。
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 不会读取更改。命令见安装。
OpenCode
OpenCode 把 CC Safety Net 作为实现自身@opencode-ai/plugin 约定的插件对象进程内加载。插件在 ~/.config/opencode/opencode.json（或 .jsonc）的 plugin 数组中声明，并执行两项工作：
- 实现
tool.execute.before。OpenCode 在每次工具执行前调用它。CC Safety Net 分析调用，并在命令具有破坏性时抛出拒绝。没有 JSON-over-stdio。 - 实现
confighook，把 CC Safety Net 内置命令注入 OpenCode 命令集，但不覆盖用户已定义命令。
Pi 扩展
Pi 把 CC Safety Net 作为进程内扩展加载。扩展由软件包pi.extensions 字段声明，并在 ~/.pi/agent/settings.json 中记录为软件包来源 npm:cc-safety-net。它执行两项工作：
- 注册
tool_call事件 handler（pi.on('tool_call')），在 shell 工具运行前拦截并使用共享引擎分析命令。破坏性命令返回阻止结果，不跨进程边界。 - 注册
/cc-safety-net内置命令，用于在 Pi 内交互管理 rulebook。
Pi 保护的工具
扩展拦截内置bash 工具和自定义 Shell 工具（例如 pi-grok-cli 提供的工具）。对 Shell，它相对会话 cwd 解析调用的 working_directory，再分析命令，因此 worktree 放宽和 rm -rf 目标分类等 cwd 感知规则正常适用。工具调用格式错误时 fail closed。
检测 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 若残留托管副本会被删除，因为本地插件会遮蔽个人插件；那里存在非托管本地文件同样会使安装失败。设置和删除命令见安装。
嵌入的策略快照
发布的 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 报告每个智能体检测到的集成和配置路径，并在保护活动时运行自检。选项和退出行为见CLI 命令。
特定智能体的 hook 未触发时，请按故障排除中的智能体步骤处理。
后续阅读
技术指南从面向用户的生命周期逐步深入设计依据。本页是第 2 步。- 上一页：工作原理从头到尾说明一次工具调用的相同拦截过程。
- 下一页：架构说明本页各集成进入的防护，包括有序阶段表。
- 然后：分析引擎说明命令到达分类器后的准确分类方式。
- 最后：设计原则说明集成模型和防护顺序的设计依据。