PicoClaw Hook 系统设计（基于 refactor/agent）

背景

本设计围绕两个议题展开：

• #1316：把 agent loop 重构为事件驱动、可中断、可追加、可观测
• #1796：在 EventBus 稳定后，把 hooks 设计为 EventBus 的 consumer，而不是重新发明一套事件模型

当前分支已经完成了第一步里的“事件系统基础”，但还没有真正的 hook 挂载层。因此这里的目标不是重新设计 event，而是在已有实现上补出一层可扩展、可拦截、可外挂的 HookManager。

外部项目对比

OpenClaw

OpenClaw 的扩展能力分成三层：

• Internal hooks：目录发现，运行在 Gateway 进程内
• Plugin hooks：插件在运行时注册 hook，也在进程内
• Webhooks：外部系统通过 HTTP 触发 Gateway 动作，属于进程外

值得借鉴的点：

• 有“项目内挂载”和“项目外挂载”两种路径
• hook 是配置驱动，可启停
• 外部入口有明确的安全边界和映射层

不建议直接照搬的点：

• OpenClaw 的 hooks / plugin hooks / webhooks 是三套路由，PicoClaw 当前体量下会偏重
• HTTP webhook 更适合“事件进入系统”，不适合作为“可同步拦截 agent loop”的基础机制

pi-mono

pi-mono 的核心思路更接近当前分支：

• 扩展统一为 extension API
• 事件分为观察型和可变更型
• 某些阶段允许 transform / block / replace
• 扩展代码主要是进程内执行
• RPC mode 把 UI 交互桥接到进程外客户端

值得借鉴的点：

• 不把“观察”和“拦截”混成一个接口
• 允许返回结构化动作，而不是只有回调
• 进程外通信只暴露必要协议，不把整个内部对象图泄露出去

当前分支现状

已有能力

当前分支已经具备 hook 系统的地基：

• pkg/agent/events.go 定义了稳定的 EventKind、EventMeta 和 payload
• pkg/agent/eventbus.go 提供了非阻塞 fan-out 的 EventBus
• pkg/agent/loop.go 中的 runTurn() 已在 turn、llm、tool、interrupt、follow-up、summary 等节点发射事件
• pkg/agent/steering.go 已支持 steering、graceful interrupt、hard abort
• pkg/agent/turn.go 已维护 turn phase、恢复点、active turn、abort 状态

现有缺口

当前分支还缺四件事：

• 没有 HookManager，只有 EventBus
• 没有 Before/After LLM、Before/After Tool 这种同步拦截点
• 没有审批型 hook
• 子 agent 仍走 pkg/tools/SubagentManager + RunToolLoop，没有接入 pkg/agent 的 turn tree 和事件流

一个关键现实

#1316 文案里提到“只读并行、写入串行”的工具执行策略，但当前 runTurn() 实现已经先收敛成“顺序执行 + 每个工具后检查 steering / interrupt”。因此 hook 设计不应依赖未来的并行模型，而应该先兼容当前顺序执行，再为以后增加 ReadOnlyIndicator 留口子。

设计原则

• Hook 必须建立在 pkg/agent 的 EventBus 和 turn 上下文之上
• EventBus 负责广播，HookManager 负责拦截，两者职责分离
• 项目内挂载要简单，项目外挂载必须走 IPC
• 观察型 hook 不能阻塞 loop；拦截型 hook 必须有超时
• 先覆盖主 turn，不把 sub-turn 一次做满
• 不新增第二套用户事件命名系统，优先复用 EventKind.String()

总体架构

分成三层：

1. EventBus 负责广播只读事件，现有实现直接复用

2. HookManager 负责管理 hook、排序、超时、错误隔离，并在 runTurn() 的明确检查点执行同步拦截

3. HookMount 负责两种挂载方式：

   • 进程内 Go hook
   • 进程外 IPC hook

换句话说：

• EventBus 是“发生了什么”
• HookManager 是“谁能介入”
• HookMount 是“这些 hook 从哪里来”

Hook 分类

不建议把所有 hook 都设计成 OnEvent(evt)。

建议拆成两类。

1. 观察型

只消费事件，不修改流程：

type EventObserver interface {
    OnEvent(ctx context.Context, evt agent.Event) error
}

这类 hook 直接订阅 EventBus 即可。

适用场景：

• 审计日志
• 指标上报
• 调试 trace
• 将事件转发给外部 UI / TUI / Web 面板

2. 拦截型

只在少数明确节点触发，允许返回动作：

type LLMInterceptor interface {
    BeforeLLM(ctx context.Context, req *LLMRequest) HookDecision[*LLMRequest]
    AfterLLM(ctx context.Context, resp *LLMResponse) HookDecision[*LLMResponse]
}

type ToolInterceptor interface {
    BeforeTool(ctx context.Context, call *ToolCall) HookDecision[*ToolCall]
    AfterTool(ctx context.Context, result *ToolResultView) HookDecision[*ToolResultView]
}

type ToolApprover interface {
    ApproveTool(ctx context.Context, req *ToolApprovalRequest) ApprovalDecision
}

这里的 HookDecision 统一支持：

• continue
• modify
• deny_tool
• abort_turn
• hard_abort

对外暴露的最小 hook 面

V1 不需要把所有 EventKind 都变成可拦截点。

建议只开放这些同步 hook：

• before_llm
• after_llm
• before_tool
• after_tool
• approve_tool

其余节点继续作为只读事件暴露：

• turn_start
• turn_end
• llm_request
• llm_response
• tool_exec_start
• tool_exec_end
• tool_exec_skipped
• steering_injected
• follow_up_queued
• interrupt_received
• context_compress
• session_summarize
• error

subturn_* 在 V1 中保留名字，但不承诺一定触发，直到子 turn 迁移完成。

项目内挂载

内部挂载必须尽量低摩擦。

建议提供两种等价方式，底层都走 HookManager。

方式 A：代码显式挂载

al.MountHook(hooks.Named("audit", &AuditHook{}))

适用于：

• 仓内内建 hook
• 单元测试
• feature flag 控制

方式 B：内建 registry

func init() {
    hooks.RegisterBuiltin("audit", func() hooks.Hook {
        return &AuditHook{}
    })
}

启动时根据配置启用：

{
  "hooks": {
    "builtins": {
      "audit": { "enabled": true }
    }
  }
}

这比 OpenClaw 的目录扫描更轻，也更贴合 Go 项目。

项目外挂载

这是本设计的硬要求。

建议 V1 采用：

• JSON-RPC over stdio

原因：

• 跨平台最简单
• 不依赖额外端口
• 非常适合“由 PicoClaw 启动一个外部 hook 进程”
• 比 HTTP webhook 更适合同步拦截

外部 hook 进程模型

PicoClaw 启动外部进程，并在其 stdin/stdout 上跑协议。

配置示例：

{
  "hooks": {
    "processes": {
      "review-gate": {
        "enabled": true,
        "transport": "stdio",
        "command": ["uvx", "picoclaw-hook-reviewer"],
        "observe": ["turn_start", "turn_end", "tool_exec_end"],
        "intercept": ["before_tool", "approve_tool"],
        "timeout_ms": 5000
      }
    }
  }
}

协议边界

不要把内部 Go 结构体直接暴露给 IPC。

建议定义稳定的协议对象：

• HookHandshake
• HookEventNotification
• BeforeLLMRequest
• AfterLLMRequest
• BeforeToolRequest
• AfterToolRequest
• ApproveToolRequest
• HookDecision

其中：

• 观察型事件用 notification，fire-and-forget
• 拦截型事件用 request/response，同步等待

为什么是 stdio，而不是直接用 HTTP webhook

因为两者用途不同：

• HTTP webhook 更适合“外部系统向 PicoClaw 投递事件”
• stdio/RPC 更适合“PicoClaw 在 turn 内同步询问外部 hook 是否改写 / 放行 / 拒绝”

如果未来需要 OpenClaw 式 webhook，可以作为独立入口层，再把外部事件转成 inbound message 或 steering，而不是直接替代 hook IPC。

Hook 执行顺序

建议统一排序规则：

• 先内建 in-process hook
• 再外部 IPC hook
• 同组内按 priority 从小到大执行

原因：

• 内建 hook 延迟更低，适合做基础规范化
• 外部 hook 更适合做审批、审计、组织级策略

超时与错误策略

观察型

• 默认超时：500ms
• 超时或报错：记录日志，继续主流程

拦截型

• before_llm / after_llm / before_tool / after_tool：默认 5s
• approve_tool：默认 60s

超时行为：

• 普通拦截：continue
• 审批：deny

这点应直接沿用 #1316 的安全倾向。

与当前分支的对接点

直接复用

• 事件定义：pkg/agent/events.go
• 事件广播：pkg/agent/eventbus.go
• 活跃 turn / interrupt / rollback：pkg/agent/turn.go
• 事件发射点：pkg/agent/loop.go

需要新增

• pkg/agent/hooks.go

  • Hook 接口
  • HookDecision / ApprovalDecision
  • HookManager

• pkg/agent/hook_mount.go

  • 内建 hook 注册
  • 外部进程 hook 注册

• pkg/agent/hook_ipc.go

  • stdio JSON-RPC bridge

• pkg/agent/hook_types.go

  • IPC 稳定载荷

需要改造

• pkg/agent/loop.go

  • 在 LLM 和 tool 关键路径前后插入 HookManager 调用

• pkg/tools/base.go

  • 可选新增 ReadOnlyIndicator

• pkg/tools/spawn.go

• pkg/tools/subagent.go

  • 先保留现状
  • 等 sub-turn 迁移后再接入 subturn_* hook

一个更贴合当前分支的数据流

观察链路

runTurn() -> emitEvent() -> EventBus -> observers

拦截链路

runTurn()
  -> HookManager.BeforeLLM()
  -> Provider.Chat()
  -> HookManager.AfterLLM()
  -> HookManager.BeforeTool()
  -> HookManager.ApproveTool()
  -> tool.Execute()
  -> HookManager.AfterTool()

也就是说：

• observer 不改变现有 emitEvent()
• interceptor 直接插在 runTurn() 热路径

用户可见配置

建议新增：

{
  "hooks": {
    "enabled": true,
    "builtins": {},
    "processes": {},
    "defaults": {
      "observer_timeout_ms": 500,
      "interceptor_timeout_ms": 5000,
      "approval_timeout_ms": 60000
    }
  }
}

V1 不做复杂自动发现。

原因：

• 当前分支重点是把地基打稳
• 目录扫描、安装器、脚手架可以后置
• 先让仓内和仓外都能挂上去，比“管理体验完整”更重要

推荐的 V1 范围

必做

• HookManager
• in-process 挂载
• stdio IPC 挂载
• observer hooks
• before_tool / after_tool / approve_tool
• before_llm / after_llm

可后置

• hook CLI 管理命令
• hook 自动发现
• Unix socket / named pipe transport
• sub-turn hook 生命周期
• read-only 并行分组
• webhook 到 inbound message 的映射入口

分阶段落地

Phase 1

• 引入 HookManager
• 支持 in-process observer + interceptor
• 先只接主 turn

Phase 2

• 引入 stdio 外部 hook 进程桥
• 支持组织级审批 / 审计 / 参数改写

Phase 3

• 把 SubagentManager 迁移到 runTurn/sub-turn
• 接通 subturn_spawn / subturn_end / subturn_result_delivered

Phase 4

• 视需求补 ReadOnlyIndicator
• 在主 turn 和 sub-turn 上统一只读并行策略

最终结论

最适合 PicoClaw 当前分支的方案，不是直接复制 OpenClaw 的 hooks，也不是完整照搬 pi-mono 的 extension system，而是：

• 以现有 EventBus 为只读观察面
• 以新增 HookManager 为同步拦截面
• 项目内通过 Go 对象直接挂载
• 项目外通过 stdio JSON-RPC 进程通信挂载

这样做有三个好处：

• 和 #1796 一致，hooks 只是 EventBus 之上的消费层
• 和当前 refactor/agent 实现一致，不需要推翻已有事件系统
• 同时满足“仓内简单挂载”和“仓外进程通信挂载”两个硬需求