Documentation
¶
Overview ¶
Package permission evaluates tool invocation permissions with OpenCode-compatible rules.
Index ¶
- Constants
- func IsOverlyBroadPattern(pattern string) bool
- func MatchGlob(pattern, value string) bool
- func ParentDirPattern(path string) string
- func PermissionKeyForTool(tool string) string
- func SuggestedPattern(key, primary string, bash ParseBashCommand) (string, bool)
- func ValidateUserConfig(cfg Config) error
- type Action
- type Config
- type Evaluator
- type ExtractedInputs
- type FormPatternRow
- type FormValues
- type ParseBashCommand
- type PatternRule
- type Request
- type Result
- type RuleSet
- type SessionState
- func (s *SessionState) AddGrant(key, pattern string) error
- func (s *SessionState) Clear()
- func (s *SessionState) Grants() map[string][]string
- func (s *SessionState) MatchesGrant(key, input string) bool
- func (s *SessionState) RecordDoomLoop(tool string, args map[string]any) (int, bool)
- func (s *SessionState) RestoreGrants(grants map[string][]string)
Constants ¶
const ( ToolRunTerminal = "run_terminal" ToolListDir = "list_dir" ToolGlobFiles = "glob_files" ToolGrepFiles = "grep_files" ToolReadFile = "read_file" ToolWriteFile = "write_file" ToolApplyPatch = "apply_patch" ToolWebSearch = "web_search" ToolWebFetch = "web_fetch" ToolRunCode = "run_code" ToolReadSkill = "read_skill" ToolDelegateSubagent = "delegate_subagent" ToolScheduleTask = "schedule_task" ToolUpdateScheduledTask = "update_scheduled_task" ToolListScheduledTasks = "list_scheduled_tasks" ToolCancelScheduledTask = "cancel_scheduled_task" ToolUpdateMemory = "update_memory" ToolTodoWrite = "todo_write" ToolListTodos = "list_todos" )
Tool names used by the chat agent coding toolkit.
const FormActionInherit = "inherit"
FormActionInherit means the user keeps the system default for one permission key.
const KeyDelegate = "delegate"
KeyDelegate is the permission key for subagent delegation via the delegate_subagent tool.
const KeyDoomLoop = "doom_loop"
KeyDoomLoop is the permission key for repeated identical tool calls.
const KeyExternalDirectory = "external_directory"
KeyExternalDirectory is the permission key for workspace-external path access.
const KeyMemory = "memory"
KeyMemory is the permission key for the update_memory tool.
const KeySchedule = "schedule"
KeySchedule is the permission key for scheduled task write operations.
const KeyScheduleRead = "schedule_read"
KeyScheduleRead is the permission key for listing scheduled tasks.
const KeyTodo = "todo"
KeyTodo is the permission key for session todo checklist tools.
const KeyWildcard = "*"
KeyWildcard applies to all permission keys when no specific rule matches.
Variables ¶
This section is empty.
Functions ¶
func IsOverlyBroadPattern ¶
IsOverlyBroadPattern reports patterns that would grant unrestricted access.
func ParentDirPattern ¶
ParentDirPattern returns a directory wildcard pattern for file paths.
func PermissionKeyForTool ¶
PermissionKeyForTool maps a tool name to its OpenCode permission key.
func SuggestedPattern ¶
func SuggestedPattern(key, primary string, bash ParseBashCommand) (string, bool)
SuggestedPattern builds a safe always-allow pattern for one permission decision. The second return value is false when always should not be offered.
func ValidateUserConfig ¶ added in v0.94.0
ValidateUserConfig rejects overly broad or unsafe user permission overrides.
Types ¶
type Action ¶
type Action string
Action is the permission decision for one tool invocation.
func ParseAction ¶
ParseAction converts raw text into an Action when valid.
type Config ¶
Config maps permission keys to rule sets (OpenCode-compatible shape).
func BuildUserConfigFromForm ¶ added in v0.95.0
BuildUserConfigFromForm builds a user override config from form values and defaults. Matching defaults are omitted. Field errors map form keys to messages.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns OpenCode-style baseline rules used when the user has no overrides.
func EffectiveConfig ¶
EffectiveConfig merges defaults with user overrides for API responses.
func ParseConfig ¶
ParseConfig unmarshals permission JSON (string or pattern map per key).
func ScheduledRunOverlay ¶ added in v0.94.0
func ScheduledRunOverlay() Config
ScheduledRunOverlay returns stricter permission rules for autonomous scheduled task runs.
func (Config) MarshalJSON ¶
MarshalJSON serializes the config for API responses.
type Evaluator ¶
type Evaluator struct {
// contains filtered or unexported fields
}
Evaluator resolves tool permissions from merged config and session state.
func NewEvaluator ¶
NewEvaluator builds an evaluator from merged permission config.
type ExtractedInputs ¶
type ExtractedInputs struct {
PermissionKey string
Primary string
Bash ParseBashCommand
ExternalPaths []string
}
ExtractedInputs holds match strings derived from a tool call.
func ExtractInputs ¶
func ExtractInputs(req Request) ExtractedInputs
ExtractInputs derives permission match inputs from a tool call.
type FormPatternRow ¶ added in v0.95.0
FormPatternRow is one pattern rule submitted from the permissions web form.
type FormValues ¶ added in v0.95.0
type FormValues struct {
Simple map[string]string
Patterns map[string][]FormPatternRow
}
FormValues holds parsed permission form submissions.
func ParseFormPostArgs ¶ added in v0.95.0
func ParseFormPostArgs(args map[string]string) FormValues
ParseFormPostArgs converts flat HTML form keys into structured permission form values.
type ParseBashCommand ¶
type ParseBashCommand struct {
// Prefix is the arity-derived command prefix used for rule matching.
Prefix string
// HasChain is true when pipes or command connectors are present.
HasChain bool
// Complex is true when parsing could not produce a reliable prefix.
Complex bool
}
ParseBashCommand analyzes a shell command for permission matching.
func AnalyzeBashCommand ¶
func AnalyzeBashCommand(command string) ParseBashCommand
AnalyzeBashCommand tokenizes command and extracts the permission prefix.
type PatternRule ¶
PatternRule binds one glob pattern to an action; last match wins during evaluation.
type Result ¶
type Result struct {
Action Action
PermissionKey string
Pattern string
SuggestedPattern string
SuggestAlways bool
DoomLoopTriggered bool
ExternalChecked bool
}
Result is the outcome of one permission evaluation.
type RuleSet ¶
type RuleSet struct {
Default Action
Patterns []PatternRule
}
RuleSet is either one global action or an ordered list of pattern rules.
type SessionState ¶
type SessionState struct {
// contains filtered or unexported fields
}
SessionState holds per-session grants and doom-loop counters across runs.
func NewSessionState ¶
func NewSessionState() *SessionState
NewSessionState creates empty session permission state.
func (*SessionState) AddGrant ¶
func (s *SessionState) AddGrant(key, pattern string) error
AddGrant records an always-allow pattern for one permission key.
func (*SessionState) Clear ¶
func (s *SessionState) Clear()
Clear removes all session grants and doom-loop counters.
func (*SessionState) Grants ¶
func (s *SessionState) Grants() map[string][]string
Grants returns a copy of always-allow patterns grouped by permission key.
func (*SessionState) MatchesGrant ¶
func (s *SessionState) MatchesGrant(key, input string) bool
MatchesGrant reports whether input is covered by a session always grant.
func (*SessionState) RecordDoomLoop ¶
RecordDoomLoop increments the counter for one tool invocation fingerprint. It returns the new count and whether the doom-loop threshold was reached.
func (*SessionState) RestoreGrants ¶ added in v0.94.0
func (s *SessionState) RestoreGrants(grants map[string][]string)
RestoreGrants replaces always-allow patterns from persisted storage.
Source Files