invoke

type Call struct {
	Name   string // 工具名，必填；空名按拒绝处理
	Server string // 来源标识（如 MCP server 名），单工具场景可空
	Caller string // 调用者标识（agent 名 / 环节名），供审计定位
	Args   string // 参数原文（通常是 JSON 文本），按次静态可判
}

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

type ChainOption func(*Chain)

type DenyError struct {
	Stage     string // 拒绝的环节名，"precondition" 表示链前校验拒的
	Tool      string
	Reason    string
	Retryable bool
	// Cause 阶段报错/panic 的原始错误。为 nil 表示这是一次正常判定得出的拒绝，
	// 而不是「这一环自己出问题了」——两者对调用方的处置完全不同。
	Cause error
}

type Handler func(ctx context.Context, c Call) (Result, error)

type Outcome struct {
	// Refused 非空 ⇒ 执行体拒绝执行本次动作；值是拒绝原因。
	//
	// 用字符串而非 bool：拒绝原因本身就是审计要留的东西（缺 confirm？
	// 超出配额？），把它压成一个 bool 就等于把原因扔在门外。
	Refused string
	// DryRun 为真 ⇒ 本次是演练：什么都没跑，但这是调用方要的（不是拒绝）。
	DryRun bool
	// WouldExecute 为真 ⇒ 这次演练**若真跑，会执行**；为假 ⇒ 不会
	// （它被风险分类挡住了，差一次确认）。
	//
	// 它把「演练」分成两种：这条命令本来就能跑（只读 / 普通写，或确认本来就
	// 带着），与它差一次确认才会动真格。只记 DryRun 的话，审计答不出
	// 「这次差一步就动真格吗」——那是两个完全不同的结论。
	//
	// 语义边界：**只在 DryRun 为真时有意义**；不是演练时恒为 false。
	// （演练什么都没跑，这一条不因 WouldExecute 而变——见 Acted。）
	WouldExecute bool
}

type Record struct {
	Call   Call
	Stages []StageResult
	// Allowed 是否真的到达了执行体（#73）：**到达即置位，与执行成败无关**——
	// 「已到达但出错」（副作用已施加、回包失败）是审计上最危险的结局，
	// 记成「未放行」会让读者以为门禁拦下了它。成败由 Err 表达：
	// Allowed=true 且 Err!=nil 即「执行体跑过但失败」。
	Allowed bool
	// Outcome 动作层结论：执行体自己声明的「事情做没做」，原样抄自 Result.Outcome。
	//
	// nil ⇒ 执行体未声明 ⇒ 按「执行了」处理。
	// 它与 Allowed 分属两层事实：Allowed 说的是门禁判了什么，Outcome 说的是
	// 事情做没做——执行体确实被到达了、门禁也确实放行了，但它可能自己拒了或只是演练。
	Outcome  *Outcome
	Err      error         // 收口原因，nil 即放行成功
	Duration time.Duration // 整链耗时
	OutBytes int           // 出参字节数（Text + Structured），留痕用
}

type Result struct {
	Text       string
	Structured json.RawMessage
	// Outcome 执行体自己的动作层结论（可选）：「事情做没做」。
	//
	// nil ⇒ 未声明 ⇒ 按「执行了」处理，保持既有调用方行为不变。
	// 声明了就由链原样抄进 Record（见 Record.Outcome），让留痕能回答
	// 「这次到底动了没有」——那是门禁层回答不了的问题（门禁只知道 capability
	// 与 confirm 标志，命令是什么只有工具知道）。
	Outcome *Outcome
}

type Stage interface {
	Name() string
	Check(ctx context.Context, c Call) (Verdict, error)
}

type StageFunc struct {
	// StageName 该环的名字，进审计留痕；空串按 "unnamed" 记录（不留空是因为
	// 「哪一环拒的」正是审计要回答的问题，空名等于这个问题没有答案）。
	StageName string
	Fn        func(ctx context.Context, c Call) (Verdict, error)
}

type StageResult struct {
	Stage    string
	Allow    bool
	Reason   string
	Duration time.Duration
}

type Verdict struct {
	Allow  bool   // 放行进下一环 / 拒绝收口
	Reason string // 结论依据，供审计留痕；拒绝时必填
	// Retryable 该拒绝是否值得重试。默认 false —— 认不出的否定一律不可重试：
	// 不存在的东西不会因为重试而出现，退避只会把一次策略否定变成无穷重试。
	Retryable bool
}