permission

Documentation

Index

• Variables
• func DecomposeCommand(cmd string) ([]string, error)
• func IsFileTool(toolName string) bool
• func IsSensitivePath(path string) bool
• func SaveLocal(projectsRoot, projectID string, add Rules) error
• func SuggestForSubcommands(command string) [][]Suggestion
• type Decision
  • func Check(local, global Rules, toolName, arg, projectRoot, home, cwd string) Decision
  • func Evaluate(rules Rules, toolName, arg, projectRoot, home, cwd string) Decision
• type Gate
  • func NewGate(onRequest func(ctx context.Context, req Request)) *Gate
  • func (g *Gate) Ask(ctx context.Context, toolName, arg string) bool
  • func (g *Gate) AskRequest(ctx context.Context, req Request) ResponseAction
  • func (g *Gate) CancelAll()
  • func (g *Gate) Respond(id string, allow bool) error
  • func (g *Gate) RespondAction(id string, action string) error
• type Request
• type ResponseAction
• type Rules
  • func LoadLocal(projectsRoot, projectID string) (Rules, error)
• type Suggestion
  • func Suggest(toolName, arg, projectRoot string) []Suggestion

Variables

var ErrUnknownRequest = errors.New("no pending permission request")

Functions

func DecomposeCommand

func DecomposeCommand(cmd string) ([]string, error)

DecomposeCommand splits a shell command on &&, ||, &, ;, |, LF, and CR respecting single and double quotes. Returns an error if $( or backticks are found outside single quotes (command substitution cannot be safely pattern-matched).

func IsFileTool

func IsFileTool(toolName string) bool

func IsSensitivePath

func IsSensitivePath(path string) bool

func SaveLocal

func SaveLocal(projectsRoot, projectID string, add Rules) error

SaveLocal writes to the per-project permissions file, merging new patterns into the existing file (append-only, no duplicates).

func SuggestForSubcommands

func SuggestForSubcommands(command string) [][]Suggestion

SuggestForSubcommands returns suggestions grouped by subcommand. Each inner slice is the suggestions for one subcommand.

Types

type Decision

type Decision int

Decision is the outcome of evaluating rules against a tool call.

const (
	DecisionAsk   Decision = iota // no rule matched — default
	DecisionAllow                 // an allow rule matched
	DecisionDeny                  // a deny rule matched
)

func Check

func Check(local, global Rules, toolName, arg, projectRoot, home, cwd string) Decision

Check evaluates local rules first, then global. Local overrides global: if any rule matches in local, that decision is final. If no local rule matches, global is checked. If neither matches, the default is DecisionAsk.

func Evaluate

func Evaluate(rules Rules, toolName, arg, projectRoot, home, cwd string) Decision

Evaluate checks a tool call against one level of rules. Precedence: deny > ask > allow. No match returns DecisionAsk.

For run_command, the command is decomposed first. Each subcommand is evaluated independently: any deny → deny, any ask → ask, all allow → allow.

type Gate

type Gate struct {

	// OnRequest is called when a new permission request is registered.
	OnRequest func(ctx context.Context, req Request)
	// contains filtered or unexported fields
}

Gate bridges synchronous permission checks to an async request/response round-trip through the Wails frontend.

func NewGate

func NewGate(onRequest func(ctx context.Context, req Request)) *Gate

NewGate returns a Gate that calls onRequest for each new permission request.

func (*Gate) Ask

func (g *Gate) Ask(ctx context.Context, toolName, arg string) bool

Ask registers a pending request and blocks until the user responds or ctx is cancelled. Returns true for allow, false for deny.

func (*Gate) AskRequest

func (g *Gate) AskRequest(ctx context.Context, req Request) ResponseAction

AskRequest registers a pending structured request and blocks until the user responds or ctx is cancelled.

func (*Gate) CancelAll

func (g *Gate) CancelAll()

CancelAll resolves every pending request as denied and clears the pending set.

func (*Gate) Respond

func (g *Gate) Respond(id string, allow bool) error

Respond delivers an answer to the pending request with the given id.

func (*Gate) RespondAction

func (g *Gate) RespondAction(id string, action string) error

RespondAction delivers an action to the pending request with the given id.

type Request

type Request struct {
	ID          string   `json:"id"`
	ToolName    string   `json:"tool"`
	Arg         string   `json:"args"`
	ResolvedArg string   `json:"resolved_arg,omitempty"`
	CanAllowAll bool     `json:"can_allow_all,omitempty"`
	BatchIndex  int      `json:"batch_index,omitempty"`
	BatchTotal  int      `json:"batch_total,omitempty"`
	BatchFiles  []string `json:"batch_files,omitempty"`
}

Request is the structured payload sent to the frontend when the gate needs to ask the user for permission.

type ResponseAction

type ResponseAction string

ResponseAction is the user's answer to a permission prompt.

const (
	ResponseAllow    ResponseAction = "allow"
	ResponseDeny     ResponseAction = "deny"
	ResponseAllowAll ResponseAction = "allow_all"
)

type Rules

type Rules struct {
	Allow []string `json:"allow,omitempty"`
	Deny  []string `json:"deny,omitempty"`
	Ask   []string `json:"ask,omitempty"`
}

Rules is the shape of both global permissions (in config.json) and local permissions (in projects/<id>/permissions.json).

func LoadLocal

func LoadLocal(projectsRoot, projectID string) (Rules, error)

LoadLocal reads the per-project permissions file. Returns empty Rules (not an error) if the file doesn't exist.

type Suggestion

type Suggestion struct {
	Rule  string `json:"rule"`  // full rule string, e.g. "run_command(npm run *)"
	Label string `json:"label"` // human-readable label for the UI
}

Suggestion is a pattern choice shown in the "Allow for project" UI.

func Suggest

func Suggest(toolName, arg, projectRoot string) []Suggestion

Suggest returns pattern suggestions of escalating generality for a tool call. For run_command, compound commands are decomposed and suggestions are returned per unmatched subcommand.