hook

type HookDefinition struct {
	// Key 标识配置中的 hook：文件项为 <文件名>:<事件>:<序号>，插件项以 plugin:<插件名>: 开头。
	Key   string
	Event defs.HookEventName
	// Matcher 按事件挑选命中的 hook，见 HookMatcher。
	Matcher *HookMatcher
	// Command 与 ScriptPath 二选一；ScriptPath 是 serve 本机的绝对路径。
	Command    string
	ScriptPath string
	// Args 是跟在 script 路径后面的参数。
	Args []string
	// Timeout 是最多运行多久。
	Timeout time.Duration
	// IsBlockedOnFailure 出错时是否按拦下处理？只用于 PreToolUse 和 UserPromptSubmit；本轮被中断不算出错。
	IsBlockedOnFailure bool
	// SourcePath 是声明这个 hook 的文件：hooks/ 下的 yaml 或插件的 manifest。
	SourcePath string
	// Plugin 是 hook 所属的插件；hooks/*.yaml 里的为 nil。插件的 script 在插件根目录内。
	Plugin *defs.Plugin
	// DisplayOrder 是展示顺序，也是运行结果的合并顺序：文件 hook 在插件 hook 前，各自按名字排序，内部按固定事件、matcher 组和 hook 顺序。
	DisplayOrder int
}

type HookEvent struct {
	Name    defs.HookEventName
	Session defs.Session
	TurnID  defs.TurnID
	// Source 是 SessionStart 的来源：startup 或 resume。
	Source string
	// Prompt 是 UserPromptSubmit 这组输入里的文本。
	Prompt string
	// ToolCall 是 PreToolUse、PostToolUse 的调用，已经过路由，参数不含 executor。
	ToolCall *defs.ToolCall
	// ToolResult 是 PostToolUse 的工具结果。
	ToolResult *defs.ToolResult
	// LastAssistantMessage 是 Stop、SubagentStop 时模型最后一条回复的文本。
	LastAssistantMessage string
	// IsStopHookActive 这一轮是不是已经被 Stop hook 续过？只用于 Stop、SubagentStop。
	IsStopHookActive bool
}

type HookEventRequest struct {
	Event *HookEvent
	// ExecutorID 是运行 hook 的 Executor。
	ExecutorID string
	// Workspace 是这个 Executor 的工作区，命令在它的根目录里运行。
	Workspace workspace.Workspace
}

type HookInfo struct {
	// Key 是 HookDefinition.Key。
	Key   string             `json:"key"`
	Event defs.HookEventName `json:"event"`
	// Matcher 是配置里 matcher 的原文，没写时为空。
	Matcher string `json:"matcher,omitempty"`
	// Handler 是显示用的命令：command 原文，或 script 路径加 args。
	Handler        string `json:"handler"`
	TimeoutSeconds int    `json:"timeout_seconds"`
	SourcePath     string `json:"source_path"`
	DisplayOrder   int    `json:"display_order"`
	// CurrentHash 是这个 hook 定义的哈希：定义不变则不变，改了事件、matcher、命令、脚本、参数、超时或 on_failure 就变。
	CurrentHash string `json:"current_hash"`
	// PluginName 是 hook 所属插件的名字；用户自己的 hook 为空。
	PluginName string `json:"plugin_name,omitempty"`
}

type HookMatcher struct {
	// contains filtered or unexported fields
}

type HookOutcome struct {
	// IsBlocked 是否有 hook 拦下了这个事件？
	IsBlocked bool
	// BlockReason 是拦下原因，多个时按配置顺序用空行拼接。
	BlockReason string
	// UpdatedToolArguments 只有 PreToolUse 会填，替换 defs.ToolCall.Arguments；多个 hook 都改写时取配置顺序最后的。
	UpdatedToolArguments string
	// IsTurnStopped 是否有 hook 要求结束本轮？
	IsTurnStopped bool
	// StopReason 是结束本轮的原因，只给用户看；多个时按配置顺序用空行拼接。
	StopReason string
	// SavedRuns 是要保存进历史的运行记录，按配置顺序；正常完成且没有任何输出的不在其中。
	SavedRuns []*defs.HookRun
}

type Hooks interface {
	// RunEvent 运行命中 request.Event 的全部 hook 并返回合并后的决定，没有命中时返回空决定。
	// 每个命中的 hook 先发一次 running 记录，结束时再发一次最终记录（同一个 ID）；RunEvent 返回后不再发送。
	// runUpdates 由调用方创建和关闭，接收方须在 RunEvent 运行期间持续接收；ctx 取消时运行中的命令被结束，记为 failed。
	RunEvent(ctx context.Context, request *HookEventRequest, runUpdates chan<- *defs.HookRun) *HookOutcome
	// GetHookInfos 返回配置的全部 hook，按 DisplayOrder 排列，供 hooks/list 显示。
	GetHookInfos() []*HookInfo
}

type HooksOpt struct {
	Definitions []*HookDefinition
}