permgate

type Behavior string

type Capability struct {
	// ReadOnly 只读工具（读后无副作用）。
	ReadOnly bool
	// AlwaysAsk 工具自报必须逐次确认（不可被模式/白名单绕过，只可被硬阻断
	// 与会话授权短路）。
	AlwaysAsk bool
	// RequiresUserInteraction 用户交互型工具（AskUserQuestion 类）。
	RequiresUserInteraction bool
}

type Decision struct {
	Behavior Behavior
	RuleID   string
	Reason   string
}

type Mode string

type Rule struct {
	// ToolName 工具名；等价工具名按 Service.ToolEquivalence 判定（nil =
	// DefaultToolEquivalence：Edit 规则匹配 Write 的写面等价，ZCode 特例）。
	ToolName string
	// Content 输入内容模式（command/url/路径）：空 = 该工具全部调用；
	// "git status:*" 前缀（空白边界，命令形态专用）；含 * 通配；否则精确等值。
	// ⚠ 路径规则用 wildcard 形态（"/repo/data/*"）而非前缀形态——前缀边界是
	// 空白/制表符，对路径子树形同虚设；路径 subject 匹配前会 filepath.Clean
	//（`..` 穿越不命中），符号链接围栏归执行器。
	Content string
}

type Ruleset struct {
	Allow []Rule
	Ask   []Rule
	Deny  []Rule
}

type Service struct {
	// AllowedTools 配置级白名单（工具名集合）。break-glass 位次（#58）：
	// 运维显式加白压过只读档与 project ask，但压不过 disallowed/project deny。
	AllowedTools map[string]bool
	// DisallowedTools 配置级黑名单（压过 yolo、alwaysAsk 的确认段与白名单）。
	DisallowedTools map[string]bool
	// ProjectRules 项目/产品级规则集。
	ProjectRules Ruleset
	// Preapprove 预批钩子（WebFetch URL 白名单类）：返回非空 ruleID 即放行。
	// 判定位次在项目 allow 之后、配置白名单之后（plan 拦截压得过预批）。
	Preapprove func(ctx context.Context, tool string, input any) (ruleID string, ok bool)
	// SubjectKeys 工具输入里参与内容匹配的字段名清单（#86）。零值/空 = 内置
	// 6 键 command/url/file_path/path/pattern/patch_text（ZCode 领域词汇惯例，
	// 向后兼容）。⚠️ 工具输入 schema 用其他字段名（cmd/script/target …）的
	// 宿主**必须**配置本清单：清单外字段是匹配盲区，内容级规则对它们静默
	// 失配；deny 规则的这类失配经 OnConfigWarn fail-loud。清单按声明顺序
	// 提取；形态特判跟随键名本身——名为 command 的键仍按复合命令拆段、
	// file_path/path 仍先 filepath.Clean，清单里的自定义键按单段原样匹配
	// （命令形态的字段建议沿用内置名 command，或由宿主拆段后匹配）。
	SubjectKeys []string
	// ToolEquivalence 工具名等价钩子（#86）：a 为规则声明的工具名、b 为实际
	// 调用的工具名，等价（规则应覆盖该调用）返回 true——精确相等无需钩子。
	// nil = DefaultToolEquivalence（Edit 规则匹配 Write 的写面等价，ZCode
	// 特例降级为缺省实现）。宿主工具命名不同（EditFile/ApplyPatch …）时
	// 声明自己的写面等价，不必为每个变体名重复配规则。钩子是**替换**不是
	// 叠加：配置后 ZCode 特例不再自动生效，需要就写进自己的实现里。
	ToolEquivalence func(a, b string) bool
	// OnConfigWarn 配置疑点告警回调（#86 fail-loud）：本包无日志依赖，宿主
	// 经它接自己的日志/计数面。当前唯一告警点——deny 内容规则在「输入是
	// map/struct 形态但提取不出清单内任何 subject 字段」的调用上无法评估：
	// 该规则对此调用形同虚设，而后续档位可能放行。默认 no-op（零值可用）。
	// 回调在 Check 路径上同步触发且可能并发，必须轻量并自行保证并发安全；
	// 告警频度（同一规则反复触发）由宿主去重。allow/ask 失配落 ask 兜底
	// 本就保守，不告警。
	OnConfigWarn func(msg string)
	// contains filtered or unexported fields
}