hookengine

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

type Hook struct {
	// Name 唯一标识（留痕与顺序用）。
	Name string
	// Event 触发事件（宿主自定词表——本包不预设事件名，那是宿主的编排语义）。
	Event string
	// ToolPrefix 只对该前缀的工具生效（空 = 全部）。
	ToolPrefix string
	// Command 交给 Runner 的命令（语义由 Runner 解释）。
	Command string
	// Args 命令参数。
	Args []string
	// Blocking 是否参与裁决。
	//
	// 阻塞 hook 在**每一次**匹配调用上都跑 ⇒ 它的成本直接落在热路径上。
	Blocking bool
	// Timeout 阻塞 hook 的墙钟上限（阻塞 hook 必填：没有上限的阻塞 hook
	// 等于把宿主挂在一个可能永不返回的进程上）。
	Timeout time.Duration
	// OnTimeout 阻塞 hook 超时时的裁决（缺省 deny）。
	OnTimeout Verdict
}

type Outcome struct {
	// ExitCode 进程/插件退出码（0 = 成功）。
	ExitCode int
	// Stdout 标准输出（拒绝理由通常在这里）。
	Stdout string
	// Stderr 标准错误。
	Stderr string
}

type Payload struct {
	// Event 事件名。
	Event string
	// Tool 当前工具名（可空）。
	Tool string
	// Args 调用参数（原样带给 Runner；本包不解释）。
	Args []string
}

type Result struct {
	// Verdict 最终裁决。
	Verdict Verdict
	// Reasons 拒绝理由（保持触发顺序）。
	Reasons []string
	// Notes 旁路留痕（非阻塞 hook 的结果与失败、无匹配的说明）。
	Notes []string
	// Ran 实际执行过的 hook 名（留痕：没跑到的也算信息）。
	Ran []string
}

type Runner interface {
	Run(ctx context.Context, h Hook, p Payload) (Outcome, error)
}

type Verdict string