// Package hooks implements the hook system: 14 lifecycle event points
// (PreToolUse / PostToolUse / PreCompact / UserPromptSubmit etc.) the engine
// fires callbacks at, with three backend modes (shell command / Go
// callback / planned webhook) so the same HookDef works across CLI / SDK /
// API consumption models.
//
// Consumer integration surfaces fall into three shapes. For the full
// taxonomy see `docs/api-reference.md` section "API 消费形态 / API
// Consumption Patterns".
//
// Synchronous callback — form 3 (the only shape this package exposes):
//   - HookHandler.ExecuteHook: Manager.Execute calls per registered hook
//     for a given HookType, blocks for *HookResult (Decision allow/deny/ask,
//     Message, etc.)
//   - Three concrete backends:
//     - ShellHandler: consumer writes a shell command in HookDef.Command;
//       engine execs, reads stdout/stderr, parses exit code.
//     - CallbackHandler: consumer provides a Go func (for SDK embedding).
//     - WebhookHandler: POSTs to a URL (planned).
//
// Package hooks 实现 hook 系统: 14 个生命周期事件点 (PreToolUse / PostToolUse
// / PreCompact / UserPromptSubmit 等) 引擎触发回调, 支持三种后端 (shell
// 命令 / Go 回调 / 规划中的 webhook), 让同一个 HookDef 在 CLI / SDK / API
// 三种消费模式下都工作.
//
// 消费者接入面分三种形态. 完整分类见 `docs/api-reference.md` "API 消费形态 /
// API Consumption Patterns" 章节.
//
// 同步回调 (callback) —— 形态三 (本包只暴露这一种):
//   - HookHandler.ExecuteHook: Manager.Execute 对每个注册 hook 按 HookType
//     调用, 阻塞等 *HookResult (Decision allow/deny/ask, Message 等)
//   - 三种具体后端:
//     - ShellHandler: 消费者在 HookDef.Command 写 shell 命令; 引擎 exec,
//       读 stdout/stderr, 解析 exit code.
//     - CallbackHandler: 消费者传 Go 函数 (用于 SDK 嵌入).
//     - WebhookHandler: POST 到 URL (规划中).
package hooks