Documentation
¶
Overview ¶
Package rules contains the approval-rule model and matcher.
Rule decisions are deterministic; path matching only examines the target's filesystem metadata and never reads configuration.
Index ¶
Constants ¶
const ( // Shell names mirror the executable categories selected by native.resolveShell. // They are untyped so callers can pass native.ShellName results directly. ShellSh = "sh" ShellBash = "bash" ShellPowerShell = "powershell" ShellCmd = "cmd" )
Variables ¶
This section is empty.
Functions ¶
func IsProtectedPath ¶
IsProtectedPath reports whether a file target is inside an internal control path. This is intentionally owned by the rules package so every entry point applies the same protection list instead of maintaining local copies.
Types ¶
type Action ¶
type Action string
Action is the result of an approval decision.
func ClampAllow ¶
func ClampAllow(action Action, target Target, workspace, sugaHome string, ruleFiles ...string) (clamped Action, protected bool)
ClampAllow prevents an approval rule from granting access to suga's own control-plane files. The entry point still decides whether a protected path is askable: chat and ACP can ask, while non-interactive run/sub-agents deny. protected reports that an Allow was downgraded because of the protected path, so later layers can tell this Ask from an ordinary one.
type Mode ¶
type Mode string
Mode limits a rule to one entry point. An empty Modes list means all modes.
type Policy ¶
Policy is an ordered set of rules and the action used when none matches. Rules are evaluated together: deny is stronger than ask, which is stronger than allow. Order is used only to choose a representative among equal strength matches, so adding a later deny cannot be hidden by an earlier allow.
func (Policy) Decide ¶
Decide returns the strongest matching action and its representative rule. When no rule matches, the policy default is returned and the rule is nil. An unset default is deliberately fail-closed as deny.
protected is true when a matched allow rule was downgraded because the target is a protected control-plane path (see ClampAllow); the default action is not clamped here, callers that clamp it report their own flag.
type Rule ¶
type Rule struct {
Source Source
Index int
Tool string
Command []string
Path []string
Root string
Modes []Mode
Action Action
}
Rule is one declarative approval rule. Command and Path are slices because the configuration format permits either one pattern or a list; the loader normalizes both forms before constructing a Rule.
func (Rule) MatchesCommand ¶
MatchesCommand reports whether one of the rule's command patterns applies to target. Command rules are restricted to the native shell_exec identity. An allow additionally requires the command to pass the selected shell's conservative ASCII whitelist; ask and deny can still match an unsafe command so a rule can deliberately make it more restrictive.
func (Rule) MatchesPath ¶
MatchesPath applies a file rule to a resolved tool target. Allow rules are deliberately stricter than deny rules: the lexical path and the path after resolving its existing ancestors must both match, and the target must not be a link, hard link, or special file. A deny rule is conservative in the other direction and matches either spelling, including a failed resolution.
func (Rule) MatchesTool ¶
MatchesTool reports whether the rule's tool glob applies to target. It is exported separately because later specialized matchers need to retain this identity check before inspecting commands or paths.
func (Rule) Validate ¶
Validate checks the schema-level invariants that are independent of a host's configuration or filesystem. Detailed command and path semantics belong to the command/path matcher tasks, but malformed rule shapes fail here so the wiring layer can return an actionable startup error.
type Source ¶
type Source string
Source identifies where a rule came from. The values are kept as strings so they can be written directly to reports and trace attributes.
type Target ¶
type Target struct {
Tool string
MCP bool
MCPServer string
Mode Mode
// Shell is the resolved shell name used by shell_exec (for example sh,
// bash, pwsh, powershell, or cmd). An unknown name is fail-closed for
// command allows. Windows controls case and .exe normalization explicitly
// because the rules package is also used by non-Windows hosts.
Shell string
Windows bool
Command string
Path string
Root string
// Protected roots are supplied by wiring; keeping them on the target lets
// Policy.Decide apply the same allow clamp for every entry point.
Workspace string
SugaHome string
RuleFiles []string
}
Target is the identity and optional call data used by Policy.Decide.
MCP targets must set MCP and use the server/tool form in Tool. MCPServer is accepted as a convenience for callers that keep the server and tool name separately; Tool is still the canonical identity used by glob matching. Command and Path are intentionally part of the value now so command and filesystem matchers can be added without changing the Policy API.