Hook 与拦截器链：可改写的拦截 + 只读观察

Hook 与拦截器链：可改写的拦截 + 只读观察 由 Archify 生成的架构图。 用户输入 · raw input · 架构组件 用户输入 raw input PromptInterceptor · beforePrompt → 决策 · 拦截链（决策能改变行为） · intercept PromptInterceptor beforePrompt → 决策 intercept AgentRuntime · ReAct 步循环 · 架构组件 AgentRuntime ReAct 步循环 ToolInterceptor · before/afterToolCall · 拦截链（决策能改变行为） · intercept ToolInterceptor before/afterToolCall intercept ToolExecutor · 工具/MCP 实执行 · 架构组件 ToolExecutor 工具/MCP 实执行 ModelRequestHook · beforeModelRequest · 拦截链（决策能改变行为） · intercept ModelRequestHook beforeModelRequest intercept LLM · AgentModelClient · 架构组件 LLM AgentModelClient 沙箱执行 · routeTo → Sandbox SPI · 拦截链（决策能改变行为） · intercept 沙箱执行 routeTo → Sandbox SPI intercept LifecycleDispatcher · 按事件类型广播 · 观察链（fire-and-forget） · observe LifecycleDispatcher 按事件类型广播 observe AgentLifecycleHook · observe-only 列表 · 观察链（fire-and-forget） · observe AgentLifecycleHook observe-only 列表 observe AgentHooks · 命名式门面 · applyTo · 架构组件 AgentHooks 命名式门面 · applyTo ① beforePrompt ② 放行/改写 ③ beforeModelRequest ④ 改写后 prompt ⑤ tool_call ⑥ allow/modify→执行 ⑦ routeTo→沙箱 ⑧ output→afterToolCall ⑨ 生命周期事件 dispatch applyTo 装配 拦截链（决策能改变行为） 观察链（fire-and-forget） 图例 前端 后端 云服务 安全 消息总线

ToolCallDecision 四种裁决

  • • allow() 放行 / block(reason) 否决——原因作为工具结果回喂模型（Claude Code 式 exit-code-2 语义）
  • • modify(call) 改写名称/参数后执行 / routeTo(sandbox) 把这次调用改派到 Daytona/E2B 沙箱执行

拦截 vs 观察

  • • 拦截器（Tool/Prompt/ModelRequest）返回决策：首个非 allow 生效，能改写输入、prompt 或工具调用
  • • AgentLifecycleHook.onEvent 只读：dispatcher 按 AgentLifecycleEventType 广播，所有 handler 都会跑，异常记为 AgentLifecycleHookError

AgentHooks 门面

  • • preToolUse/postToolUse/userPromptSubmit/beforeModelRequest + 按事件类型的 observe——命名注册、编译期安全
  • • applyTo 把各槽位组合进 builder 的单拦截器位；pre/post 合成同一个 ToolInterceptor，两者可并存