Help us shape the future of Go! Take the 2026 Go Developer Survey

permissions

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package permissions implements the opt-in tool permission policy: a set of allow/ask/deny rules matched on a tool call's name and one primary argument (a shell command, a path, or a URL host). It is a declarative guardrail, not a security boundary; containment stays with --sandbox and containers.

The policy is pure: it matches calls and returns decisions. Answering an "ask" is the caller's job (a terminal prompt, an ACP request_permission, or a headless fallback), which keeps this package free of I/O.

Index

Constants

View Source
const (
	SourceRule           = "rule"
	SourceDefault        = "default"
	SourceUser           = "user"
	SourceSession        = "session"
	SourceNonInteractive = "non_interactive"
)

Sources for a decision's Result.

Variables

This section is empty.

Functions

func HostOf

func HostOf(rawURL string) string

HostOf returns the lowercased hostname of a URL, or "" when it can't be parsed. It is the primary argument a host rule matches against.

func PortOf

func PortOf(rawURL string) int

PortOf returns the port a URL reaches: its explicit port, or the scheme's default. It is unused by hostname matching but kept for symmetry with sandbox_allowed_domains.

Types

type Answer

type Answer struct {
	Decision Decision // allow or deny
	Always   bool     // allow this tool and argument for the rest of the run
	Reason   string   // deny reason shown to the model
	Channel  string   // terminal, acp, or "" for the permission event
}

Answer is a person's (or the non-interactive fallback's) answer to an ask.

type Call

type Call struct {
	Tool    string
	Command string   // bash / start_process / command tool argv joined
	Paths   []string // file tool paths (relative to the working directory)
	Host    string   // web_fetch URL host (lowercased, no port)
}

Call is one tool call to evaluate. The fields hold the call's primary argument(s) by family; a rule only reads the field its matcher names.

func (Call) Argument

func (c Call) Argument() string

Argument returns the primary argument a prompt or event should show: the command, the first path, or the host.

func (Call) Key

func (c Call) Key() string

Key identifies a call for "allow always" session approvals: the tool name and its primary argument.

type Decision

type Decision string

Decision is a permission outcome.

const (
	DecisionAllow Decision = "allow"
	DecisionAsk   Decision = "ask"
	DecisionDeny  Decision = "deny"
)

type Policy

type Policy struct {
	Default        Decision
	NonInteractive Decision
	// contains filtered or unexported fields
}

Policy is a compiled permission policy. A nil *Policy enforces nothing.

func New

func New(cfg config.Permissions) (*Policy, error)

New compiles cfg into a policy. It returns nil when cfg has no rules and no settings, so a config without a permissions key enforces nothing. Errors name the rule index, like config validation.

func (*Policy) Check

func (p *Policy) Check(call Call) Result

Check evaluates the call and returns the decision. A nil policy allows.

func (*Policy) RuleCount

func (p *Policy) RuleCount() int

RuleCount returns the number of rules in the policy.

func (*Policy) Rules

func (p *Policy) Rules() []config.PermissionRule

Rules returns the configured rules (patterns are config data, not secrets).

func (*Policy) Summary

func (p *Policy) Summary() Summary

Summary describes the policy for run.started, trajectories and --check.

type Request

type Request struct {
	Tool       string
	ToolCallID string
	Rule       int
	Argument   string // the primary argument, already secret-redacted
	Subagent   string
}

Request describes an ask the caller must answer.

type Result

type Result struct {
	Decision Decision
	Source   string // SourceRule or SourceDefault
	// Rule is the index of the deciding rule, or -1 for the default.
	Rule    int
	Message string
}

Result is the policy's decision for a call.

type Summary

type Summary struct {
	Default        string `json:"default"`
	NonInteractive string `json:"non_interactive"`
	Rules          int    `json:"rules"`
}

Summary records a policy for run.started, trajectories and --check.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL