permission

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 7, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package permission decides whether tool calls and hook commands may run. It classifies each call and checks it against the rules, the mode, the filesystem roots and stored approvals, asking the user through interact.UI when none of them decides.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AuditEntry

type AuditEntry struct {
	Time       time.Time     `json:"time"`
	Mode       interact.Mode `json:"mode"`
	Tool       string        `json:"tool"`
	Capability Capability    `json:"capability"`
	Summary    string        `json:"summary"`
	Decision   string        `json:"decision"`
	Reason     string        `json:"reason,omitempty"`
	Allow      bool          `json:"allow"`
}

type Capability

type Capability string
const (
	CapabilityRead     Capability = "read"
	CapabilityWrite    Capability = "write"
	CapabilityExec     Capability = "exec"
	CapabilityNetwork  Capability = "network"
	CapabilityInternal Capability = "internal"
	CapabilityUnknown  Capability = "unknown"
)

type Config

type Config struct {
	Cwd   string
	Mode  interact.Mode
	Rules *RuleSet
	Roots FilesystemRoots
	// Without a UI, anything that needs asking is denied.
	UI      interact.UI
	OnAudit func(AuditEntry)
}

type Decision

type Decision struct {
	Kind         DecisionKind   `json:"kind"`
	Source       DecisionSource `json:"source,omitempty"`
	Reason       string         `json:"reason,omitempty"`
	Capability   Capability     `json:"capability,omitempty"`
	Summary      string         `json:"summary,omitempty"`
	OutsideRoots bool           `json:"outside_roots,omitempty"`
	Prompted     bool           `json:"prompted,omitempty"`
}

func (Decision) Allowed

func (d Decision) Allowed() bool

type DecisionKind

type DecisionKind string
const (
	DecisionAllow       DecisionKind = "allow"
	DecisionAllowOnce   DecisionKind = "allow_once"
	DecisionAllowAlways DecisionKind = "allow_always"
	DecisionDeny        DecisionKind = "deny"
)

type DecisionSource

type DecisionSource string
const (
	DecisionSourceRule     DecisionSource = "rule"
	DecisionSourceGrant    DecisionSource = "grant"
	DecisionSourceMode     DecisionSource = "mode"
	DecisionSourcePrompt   DecisionSource = "prompt"
	DecisionSourceStore    DecisionSource = "store"
	DecisionSourceRoots    DecisionSource = "roots"
	DecisionSourceInternal DecisionSource = "internal"
)

type Engine

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

Engine holds process-wide state: mode, rules, roots and stored approvals. What one conversation allows on top comes with each request; see Middleware.

func NewEngine

func NewEngine(cfg Config) (*Engine, error)

func (*Engine) Configure

func (e *Engine) Configure(rules *RuleSet, roots FilesystemRoots)

func (*Engine) Decide

func (e *Engine) Decide(ctx context.Context, req Request) (*Decision, error)

func (*Engine) Middleware

func (e *Engine) Middleware(grants func() []Rule, meta func(tool string) Metadata) agentcore.ToolMiddleware

Middleware gates one conversation's tool calls. grants is called for each call and returns extra allowances, such as the tools of skills invoked in the run. meta returns the Metadata of self-classifying tools such as MCP tools.

func (*Engine) Mode

func (e *Engine) Mode() interact.Mode

func (*Engine) SetMode

func (e *Engine) SetMode(mode interact.Mode)

type FilesystemRoots

type FilesystemRoots struct {
	ReadRoots        []string
	WriteRoots       []string
	InternalReadable []string
	InternalWritable []string
	// Protected directories hold files that decide what codebot runs, such
	// as local plugins. Every write there is confirmed, in any mode.
	Protected []string
}

FilesystemRoots scope filesystem access.

ReadRoots and WriteRoots come from the user. Access outside them is confirmed each time, so one consent never grants lasting access.

InternalReadable and InternalWritable are paths the harness manages, such as the memory dir. Access there skips the outside-roots and mode prompts; deny rules still apply. An InternalWritable path is also readable.

type Metadata

type Metadata struct {
	Capability  Capability `json:"capability,omitempty"`
	SummaryHint string     `json:"summary_hint,omitempty"`
	Reason      string     `json:"reason,omitempty"`
	Key         string     `json:"key,omitempty"`
	KeyPrefix   string     `json:"key_prefix,omitempty"`
}

type Request

type Request struct {
	ToolID    string          `json:"tool_id,omitempty"`
	ToolName  string          `json:"tool_name"`
	ToolLabel string          `json:"tool_label,omitempty"`
	Summary   string          `json:"summary,omitempty"`
	Reason    string          `json:"reason,omitempty"`
	Args      json.RawMessage `json:"args,omitempty"`
	Metadata  Metadata        `json:"metadata,omitempty"`
	// Workspace resolves relative paths for this request; empty means
	// Config.Cwd. Set it when the tool runs elsewhere, e.g. in a worktree.
	Workspace string `json:"workspace,omitempty"`
	// Grants allow this request on top of stored approvals, e.g. the tools an
	// active skill allows. Deny rules, roots and confirm-each-time paths
	// still come first.
	Grants []Rule `json:"-"`
}

type Rule

type Rule struct {
	Raw     string
	Kind    string
	Pattern string
}

func ParseGrants

func ParseGrants(raw []string) []Rule

ParseGrants skips entries that do not parse.

func ParseRule

func ParseRule(raw string) (Rule, error)

type RuleSet

type RuleSet struct {
	Allow []Rule
	Deny  []Rule
}

func ParseRuleSet

func ParseRuleSet(allow, deny []string) (*RuleSet, error)

type Store

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

func NewStore

func NewStore(path string) (*Store, error)

func (*Store) Add

func (s *Store) Add(entry StoreEntry) error

func (*Store) Has

func (s *Store) Has(key string) bool

type StoreEntry

type StoreEntry struct {
	Key        string     `json:"key"`
	Tool       string     `json:"tool"`
	Capability Capability `json:"capability"`
	Summary    string     `json:"summary"`
	AddedAt    time.Time  `json:"added_at"`
}

Jump to

Keyboard shortcuts

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