permission

Documentation

Index

• type Approver
• type AuditEntry
• type Capability
• type Checker
• type Choice
• type Classification
• type Classifier
• type Decision
  • func (d Decision) Allowed() bool
• type DecisionEngine
• type DecisionKind
• type DecisionSource
• type Engine
  • func NewEngine(cfg EngineConfig) *Engine
  • func (e *Engine) Decide(ctx context.Context, req Request) (*Decision, error)
  • func (e *Engine) FilesystemRoots() FilesystemRoots
  • func (e *Engine) Mode() Mode
  • func (e *Engine) PlanMode() bool
  • func (e *Engine) SetApprover(fn Approver)
  • func (e *Engine) SetFilesystemRoots(roots FilesystemRoots)
  • func (e *Engine) SetMode(mode Mode)
  • func (e *Engine) SetPlanMode(active bool)
  • func (e *Engine) SetSkillAllows(rawTools []string)
• type EngineConfig
• type FilesystemRoots
• type Metadata
• type Mode
  • func ParseMode(raw string) (Mode, error)
• type Prompt
• type Request
• type Rule
  • func ParseRule(raw string) (Rule, error)
• type RuleSet
  • func ParseRuleSet(allow, deny []string) (*RuleSet, error)
  • func (rs *RuleSet) Evaluate(info toolInfo) (ruleAction, bool)
• type Store
  • func NewStore(path string) (*Store, error)
  • func (s *Store) Add(entry StoreEntry) error
  • func (s *Store) Has(key string) bool
• type StoreEntry

Types

type Approver

type Approver func(ctx context.Context, prompt Prompt) (Choice, error)

type AuditEntry

type AuditEntry struct {
	Time       time.Time  `json:"time"`
	Mode       Mode       `json:"mode"`
	PlanMode   bool       `json:"plan_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"
	CapabilityHook     Capability = "hook"
	CapabilityNetwork  Capability = "network"
	CapabilityInternal Capability = "internal"
	CapabilityUnknown  Capability = "unknown"
)

type Checker

type Checker interface {
	CheckPermission(ctx context.Context, req Request) (*Decision, error)
}

type Choice

type Choice string

const (
	ChoiceAllowOnce    Choice = "allow_once"
	ChoiceAllowSession Choice = "allow_session"
	ChoiceAllowAlways  Choice = "allow_always"
	ChoiceDeny         Choice = "deny"
)

type Classification

type Classification struct {
	Capability Capability
	Path       string
	Command    string
	Workdir    string
	URL        string
	Summary    string
	Reason     string
	Key        string
}

Classification describes how the permission engine should treat a tool call. The harness owns the mapping from tool names to capabilities and operand fields, and provides it via EngineConfig.Classifier.

Field semantics by Capability:

• Read : Path is checked against ReadRoots; populates summary.
• Write : Path is checked against WriteRoots; populates summary and contributes to the audit key (write:<path>).
• Exec : Command populates summary; hashed into the audit key (exec:<hash>). Workdir, if set, is checked against WriteRoots.
• Network : URL populates summary; host extracted into audit key (network:<host>). Empty URL falls back to network:<tool>.
• Internal: no operand fields used; key is internal:<tool>.
• Unknown : key is tool:<tool>.

Summary, Reason, and Key are optional overrides — empty fields fall back to engine-derived defaults.

type Classifier

type Classifier func(req Request) Classification

Classifier maps a Request to a Classification. The harness owns the mapping from tool names to capabilities and operand fields. If nil, every request defaults to CapabilityUnknown unless Request.Metadata supplies a Capability override.

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"`
	Key          string          `json:"key,omitempty"`
	OutsideRoots bool            `json:"outside_roots,omitempty"`
	Prompted     bool            `json:"prompted,omitempty"`
	Preview      string          `json:"preview,omitempty"`
	UpdatedArgs  json.RawMessage `json:"updated_args,omitempty"`
	Suggestions  []string        `json:"suggestions,omitempty"`
}

func (Decision) Allowed

func (d Decision) Allowed() bool

type DecisionEngine

type DecisionEngine interface {
	Decide(ctx context.Context, req Request) (*Decision, error)
}

type DecisionKind

type DecisionKind string

const (
	DecisionAllow        DecisionKind = "allow"
	DecisionAllowOnce    DecisionKind = "allow_once"
	DecisionAllowSession DecisionKind = "allow_session"
	DecisionAllowAlways  DecisionKind = "allow_always"
	DecisionDeny         DecisionKind = "deny"
)

type DecisionSource

type DecisionSource string

const (
	DecisionSourceTool     DecisionSource = "tool"
	DecisionSourceRule     DecisionSource = "rule"
	DecisionSourceSkill    DecisionSource = "skill"
	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
}

func NewEngine

func NewEngine(cfg EngineConfig) *Engine

func (*Engine) Decide

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

func (*Engine) FilesystemRoots

func (e *Engine) FilesystemRoots() FilesystemRoots

func (*Engine) Mode

func (e *Engine) Mode() Mode

func (*Engine) PlanMode

func (e *Engine) PlanMode() bool

func (*Engine) SetApprover

func (e *Engine) SetApprover(fn Approver)

func (*Engine) SetFilesystemRoots

func (e *Engine) SetFilesystemRoots(roots FilesystemRoots)

func (*Engine) SetMode

func (e *Engine) SetMode(mode Mode)

func (*Engine) SetPlanMode

func (e *Engine) SetPlanMode(active bool)

func (*Engine) SetSkillAllows

func (e *Engine) SetSkillAllows(rawTools []string)

type EngineConfig

type EngineConfig struct {
	Workspace string
	Mode      Mode
	Rules     *RuleSet
	Roots     FilesystemRoots
	Store     *Store
	Approver  Approver
	OnAudit   func(AuditEntry)
	// Classifier maps tool requests to capabilities + operand fields.
	// See Classification for field semantics.
	Classifier Classifier
	// PlanModeAllowedTools names tools that may run in plan mode despite not
	// having Read capability. Empty by default — plan mode is read-only.
	// Use this for harness-specific control tools (e.g. an "exit_plan_mode"
	// tool that must run while the harness is in plan mode).
	PlanModeAllowedTools []string
	// PlanModeExecAllowed lets the harness opt specific exec calls (typically
	// the bash tool, used for grep/find/git status during plan exploration)
	// through plan-mode's default exec ban. When this returns true, the call
	// is allowed in plan mode without triggering the underlying mode's ask
	// flow — the harness is asserting the exec is safe under plan-mode
	// semantics (typically enforced by the system prompt). Nil = default
	// behavior (all exec denied in plan mode).
	PlanModeExecAllowed func(req Request) bool
	// PlanModeWriteAllowed lets the harness opt specific write calls through
	// plan-mode's default write ban. Typical use: a designated plan file the
	// model edits incrementally during planning. The harness owns the policy
	// (path matching, etc.); agentcore stays generic. Nil = default behavior
	// (all writes denied in plan mode).
	PlanModeWriteAllowed func(req Request) bool
}

type FilesystemRoots

type FilesystemRoots struct {
	ReadRoots        []string
	WriteRoots       []string
	InternalReadable []string
	InternalWritable []string
}

FilesystemRoots scope filesystem access for tool requests. The two pairs serve different audiences:

• ReadRoots / WriteRoots: user-configured. Subject to deny rules and mode-based prompts (e.g. balanced mode asks for any write). Out-of-roots access triggers an OutsideRoots prompt; AllowAlways for that prompt is downgraded to AllowOnce so a one-shot consent does not silently grant persistent access.

• InternalReadable / InternalWritable: harness-declared. Reserved for paths the harness itself manages (auto-memory dir, plan store, scratch space). Matches bypass the OutsideRoots prompt and the mode-based ask so the agent can read/write these locations silently. Deny rules and plan-mode read-only enforcement still apply.

A path matched by InternalWritable is also treated as readable, so callers that want bidirectional access only need to populate the writable list.

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 Mode

type Mode string

const (
	ModeStrict      Mode = "strict"
	ModeBalanced    Mode = "balanced"
	ModeAcceptEdits Mode = "accept_edits"
	ModeTrust       Mode = "trust"
)

func ParseMode

func ParseMode(raw string) (Mode, error)

type Prompt

type Prompt struct {
	Tool         string
	Summary      string
	Reason       string
	Capability   Capability
	Preview      string
	OutsideRoots bool
}

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"`
	Preview   json.RawMessage `json:"preview,omitempty"`
	Metadata  Metadata        `json:"metadata,omitempty"`
}

type Rule

type Rule struct {
	Raw     string
	Kind    string
	Pattern string
}

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)

func (*RuleSet) Evaluate

func (rs *RuleSet) Evaluate(info toolInfo) (ruleAction, bool)

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"`
}