EN 中文

# Hooks — Lifecycle Interception

# Hooks — 生命周期拦截

Decorate or observe agent lifecycle events: prompts, tool use, session boundaries.

在 agent 关键事件插入自定义逻辑——memory 子系统就是通过 hooks 实现的。

## Hook Kinds

## Hook 类型

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

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

### Decorators (can mutate the request)

### 装饰器（可修改请求）

Hook | Hook | When | 触发时机 | Purpose | 作用
--- | --- | --- | --- | --- | ---
`PrePromptHook` | Before user message is appended to history | 用户消息追加到历史之前 | Inject memory, expand slash commands, rewrite user text | 注入记忆、展开斜杠命令、改写用户文本
`PreToolUseHook` | Before tool call execution | 工具调用执行前 | Modify tool arguments, inject context | 修改工具参数、注入上下文

⚠️ Output MUST be deterministic — DeepSeek's prefix cache keys on the exact byte sequence of the prompt history. 输出必须确定——DeepSeek 前缀缓存 key 是 prompt 历史的精确字节序列。

### Observers (read-only)

### 观察器（只读）

Hook | Hook | When | 触发时机
--- | --- | --- | ---
`PreTurn` | Before each turn | 每轮开始前
`PostTurn` | After each turn | 每轮结束后
`PostToolUse` | After each tool call | 每个工具执行后
`SessionStart` | Session begins | 会话开始时
`SessionEnd` | Session ends | 会话结束时

## 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 自动分发