Module hook 

katu_core::hook

职责

定义 Hook 系统的类型与执行契约 — Agent 生命周期的可拦截节点。

设计

Hook 系统与 AgentEvent 互补：

• AgentEvent（agent_event.rs）= 不可变的已发生事实，消费者只能观察
• Hook（本模块）= 可拦截的执行节点，Hook 可以拦截、修改、阻止

Agent Loop ──节点──► HookRegistry.run() ──决策──► 继续/修改/阻止
                                                       │
                                                       ▼
                                             AgentEvent（记录事实）

对外接口

• HookEvent — 可拦截的生命周期节点（10 种）
• HookInput — 各事件的类型化输入
• HookOutput — Hook 的决策结果
• HookPermission — 权限决策（allow / deny / ask）
• Hook — 执行 trait（async, object-safe）
• HookSource — Hook 来源标识
• HookRegistry — 注册与匹配
• AggregatedHookOutput — 多 Hook 结果聚合

调用者

• katu-agent (future) — Agent loop 在各生命周期节点调用 Hook
• 应用层 — 注册自定义 Hook 实现

Structs

AggregatedHookOutput

多个 Hook 结果的聚合 — 并行执行后合并。

HookOutput

Hook 的执行结果 — 告诉 Agent loop 如何继续。

HookRegistry

Hook 注册中心 — 管理已注册的 Hook 并按事件/matcher 分发。

RegisteredHook

已注册的 Hook 条目 — 包含 Hook 实例、来源和优先级。

Enums

HookEvent

可拦截的 Agent 生命周期节点。

HookInput

Hook 输入 — 每个 HookEvent 携带的上下文数据。

HookPermission

Hook 的权限决策 — 仅对 PreToolUse 事件有意义。

HookSource

Hook 来源 — 用于冲突解决、日志追踪和安全策略。

Constants

ALL_HOOK_EVENTS

所有 Hook 事件的完整列表，按定义顺序。

Traits

Hook

Hook 执行 trait — 所有可注册到 Agent loop 的 Hook 必须实现。

Functions

matches_pattern

模式匹配 — 判断 value 是否匹配 pattern。