permissions

type CheckResult ¶

type CheckResult struct {
	// Decision is the final permission decision.
	Decision Decision

	// MatchedRule is the rule that produced this decision, if any.
	// Nil when the decision comes from mode fallthrough.
	MatchedRule *Rule

	// Reason is a human-readable explanation of why this decision was made.
	Reason string
}

CheckResult is the outcome of running an input through the permission checker.

func (cr CheckResult) IsAllowed() bool

func (cr CheckResult) IsDenied() bool

func (cr CheckResult) NeedsPrompt() bool

type Checker ¶

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

Checker evaluates whether a tool execution should be allowed, denied, or requires user approval. It implements a 5-step evaluation chain:

0. protected hook/trust files — best-effort Deny for shell commands
1. alwaysDeny rules — if any match, return Deny immediately
2. alwaysAllow rules — if any match, return Allow immediately, unless the rule is a bare tool name and an argument-scoped pattern deny or ask matches the call (the more specific rule wins)
4. patternRules — if any match, return the rule's decision
5. Mode fallthrough — default allows read-only tools and asks for the rest, strict asks for all, trust allows all

(Step 3, an early read-only allow, is gone: it ran before the pattern rules, so a pattern deny never applied to a read-only tool.)

func NewChecker(config PermissionConfig) *Checker

func (c *Checker) AddPersistentAllow(rule Rule) error

func (c *Checker) AddPersistentDeny(rule Rule) error

func (c *Checker) Check(tool ToolInfo, input map[string]any) CheckResult

func (c *Checker) Mode() PermissionMode

func (c *Checker) SetConfigPath(path string)

func (c *Checker) SetPersistWarn(warn func(error))

func (c *Checker) SetWorkspace(dir string)

type Decision ¶

type Decision int

Decision represents the outcome of a permission check.

const (
	// Allow means the tool execution is permitted without user interaction.
	Allow Decision = iota
	// Deny means the tool execution is blocked.
	Deny
	// Ask means the user must be prompted for approval.
	Ask
)

func (d Decision) String() string

type PermissionConfig ¶

type PermissionConfig struct {
	// Mode is the default permission mode (default, strict, trust).
	Mode PermissionMode `json:"mode"`

	// AlwaysAllow is a list of rules that are always permitted regardless of mode.
	AlwaysAllow []Rule `json:"always_allow,omitempty"`

	// AlwaysDeny is a list of rules that are always blocked regardless of mode.
	AlwaysDeny []Rule `json:"always_deny,omitempty"`

	// PatternRules are evaluated after alwaysDeny and alwaysAllow but before
	// mode fallthrough. They allow fine-grained control over specific tool/input
	// combinations.
	PatternRules []Rule `json:"pattern_rules,omitempty"`
}

PermissionConfig holds the persistent permission configuration. Stored at ~/.celeste/permissions.json.

func DefaultConfig() PermissionConfig

func LoadConfig(path string) (*PermissionConfig, error)

type PermissionMode ¶

type PermissionMode string

PermissionMode controls the default behavior when no explicit rule matches.

const (
	// ModeDefault auto-allows read-only tools, asks for writes.
	ModeDefault PermissionMode = "default"
	// ModeStrict asks the user for every tool invocation.
	ModeStrict PermissionMode = "strict"
	// ModeTrust auto-allows everything (current behavior pre-v1.7).
	ModeTrust PermissionMode = "trust"
)

func ParsePermissionMode(s string) (PermissionMode, error)

func (m PermissionMode) String() string

func (m PermissionMode) Valid() bool

type PrimaryArger ¶

type PrimaryArger interface {
	PrimaryArg() string
}

PrimaryArger is implemented by a ToolInfo that names the input field an argument-scoped rule ("write_file(src/*)") is matched against: the field the tool acts on (bash: command, the file tools: path).

type Rule ¶

type Rule struct {
	// ToolPattern is the pattern to match against tool name and optionally its input.
	ToolPattern string `json:"tool_pattern"`

	// InputPattern is an optional glob matched against JSON-serialized input.
	InputPattern string `json:"input_pattern,omitempty"`

	// Decision is the action to take when this rule matches.
	Decision Decision `json:"decision"`
}

Rule defines a permission rule that matches a tool invocation pattern.

ToolPattern supports:

• Exact tool name match: "read_file"
• Tool name with argument glob: "bash(git *)" — matches tool "bash" when the first string argument (typically "command") matches the glob "git *"
• Wildcard tool: "*" — matches any tool

InputPattern is an optional secondary pattern that matches against the JSON-serialized input. When empty, only ToolPattern is evaluated.

type ToolInfo ¶

type ToolInfo interface {
	ToolName() string
	IsReadOnly() bool
}

ToolInfo is the minimal interface the Checker needs from a tool. This avoids importing the tools package (preventing circular dependencies). The tools.Tool interface satisfies this via its Name() and IsReadOnly() methods.