Hook Kinds

Hook 类型

Two categories, separated at the type level — prefix-cache safety is a compile-time property:

两类 hooks，在类型层面区分，前缀缓存安全性在编译时保证：

Decorators (can mutate the request)

装饰器（可修改请求）

Observers (read-only)

观察器（只读）

Built-in Hooks

内置 Hook

• Checkpoint (checkpointHook) — PreTurn + SessionEnd to manage checkpoint state
• Checkpoint 安全网——通过 PreTurn + SessionEnd 管理 checkpoint 状态
• Memory system (internal/memory) — PrePrompt + PostToolUse + SessionStart + SessionEnd for L/M/S three-tier memory
• 记忆系统（internal/memory）——通过 PrePrompt + PostToolUse + SessionStart + SessionEnd 实现 L/M/S 三层记忆

CLI: seek hooks

CLI：seek hooks

$ seek hooks list     # List trusted hook scripts
$ seek hooks check --event <event> [--tool <tool>]    # Dry-run: which hooks fire for this event/tool?
$ seek hooks trust [--reset[=<path>]]    # List trusted projects; --reset removes trust
$ seek hooks audit    # Audit hook call records

Writing Custom Hooks (Go)

编写自定义 Hook

A single struct may implement multiple hook interfaces. Registry.Register dispatches it into every slot it satisfies.

一个结构体可以实现多个 hook 接口。Registry.Register 自动分发：

// A struct implementing both PrePrompt + PostTurn
type myHook struct{}

func (h *myHook) OnPrePrompt(ctx context.Context, in hooks.PrePromptIn) (hooks.PrePromptOut, error) {
    return hooks.PrePromptOut{UserText: in.UserText + "\n[injected context]"}, nil
}

func (h *myHook) OnPostTurn(ctx context.Context, ev hooks.PostTurnEvent) {
    // analyse, distil, persist...
}

// Register
registry := hooks.NewRegistry()
registry.Register(&myHook{})

Design Notes

设计要点

• Determinism first — Decorators must be deterministic to preserve prefix cache
• 确定性优先——装饰器的输出必须确定，否则破坏前缀缓存
• Zero-intrusion observers — Observer signatures enforce they cannot modify conversation, request, or control flow
• 零侵入观察器——Observer 接口强制不能修改对话、请求或控制流
• Single struct, multiple interfaces — Registry auto-detects and dispatches
• 单一结构多接口——一个结构体实现多个 hook 接口，Registry 自动分发