permission

Documentation

Index

• Variables
• func IsReadOnlyTool(name string) bool
• func IsValidPermissionMode(s string) bool
• type ConfigPolicy
  • func NewConfigPolicy(rules map[string]Decision, allowedDirs []string) *ConfigPolicy
  • func NewConfigPolicyWithMode(rules map[string]Decision, allowedDirs []string, mode PermissionMode) *ConfigPolicy
  • func NewConfigPolicyWithModeAndReadOnlyDirs(rules map[string]Decision, allowedDirs, readOnlyDirs []string, ...) *ConfigPolicy
  • func (p *ConfigPolicy) AllowedPath(path string) bool
  • func (p *ConfigPolicy) AllowedPathForTool(toolName, path string) bool
  • func (p *ConfigPolicy) Check(toolName string, input json.RawMessage) (Decision, error)
  • func (p *ConfigPolicy) ClearOverride(toolName string)
  • func (p *ConfigPolicy) CurrentMode() PermissionMode
  • func (p *ConfigPolicy) GetDecision(toolName string) Decision
  • func (p *ConfigPolicy) IsDangerous(command string) bool
  • func (p *ConfigPolicy) Mode() PermissionMode
  • func (p *ConfigPolicy) SetMode(mode PermissionMode)
  • func (p *ConfigPolicy) SetOverride(toolName string, decision Decision)
• type DangerLevel
  • func (l DangerLevel) String() string
• type DangerousCheck
  • func (c DangerousCheck) Suggestion() string
• type DangerousDetector
  • func NewDangerousDetector() *DangerousDetector
  • func (d *DangerousDetector) Check(command string) DangerousCheck
  • func (d *DangerousDetector) IsDangerous(command string) bool
  • func (d *DangerousDetector) IsExtremelyDangerous(command string) bool
• type Decision
  • func (d Decision) String() string
• type PathSandbox
  • func NewPathSandbox(allowedDirs []string) *PathSandbox
  • func (s *PathSandbox) Allowed(path string) bool
  • func (s *PathSandbox) AllowedDirs() []string
• type PermissionMode
  • func ParsePermissionMode(s string) PermissionMode
  • func (m PermissionMode) Next() PermissionMode
  • func (m PermissionMode) String() string
• type PermissionPolicy
• type ToolRule

Variables

var DefaultMode = SupervisedMode

DefaultMode is the default permission mode if not specified.

var ValidPermissionModes = []PermissionMode{
	SupervisedMode, PlanMode, AutoMode, BypassMode, AutopilotMode,
}

ValidPermissionModes is the set of mode names accepted by ParsePermissionMode.

Functions

func IsReadOnlyTool

func IsReadOnlyTool(name string) bool

IsReadOnlyTool returns true if the tool is safe for Plan mode (read-only).

func IsValidPermissionMode

func IsValidPermissionMode(s string) bool

IsValidPermissionMode returns true if s is a recognized mode name.

Types

type ConfigPolicy

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

ConfigPolicy implements PermissionPolicy based on configuration rules.

func NewConfigPolicy

func NewConfigPolicy(rules map[string]Decision, allowedDirs []string) *ConfigPolicy

NewConfigPolicy creates a policy from tool rules and allowed directories. Default decision is Ask for any tool not explicitly listed.

func NewConfigPolicyWithMode

func NewConfigPolicyWithMode(rules map[string]Decision, allowedDirs []string, mode PermissionMode) *ConfigPolicy

NewConfigPolicyWithMode creates a policy with an explicit permission mode.

func NewConfigPolicyWithModeAndReadOnlyDirs

func NewConfigPolicyWithModeAndReadOnlyDirs(rules map[string]Decision, allowedDirs, readOnlyDirs []string, mode PermissionMode) *ConfigPolicy

NewConfigPolicyWithModeAndReadOnlyDirs creates a policy with optional read-only file access outside the main writable sandbox.

func (*ConfigPolicy) AllowedPath

func (p *ConfigPolicy) AllowedPath(path string) bool

AllowedPath returns true if the path is within the sandbox.

func (*ConfigPolicy) AllowedPathForTool

func (p *ConfigPolicy) AllowedPathForTool(toolName, path string) bool

AllowedPathForTool returns true if the path is allowed for the specific tool. In non-plan modes, if execution reaches here the permission layer has already approved the tool call (either Allow directly or user approved an Ask), so sandbox restrictions are lifted. In PlanMode, strict sandbox enforcement applies since plan mode never writes outside the workspace.

func (*ConfigPolicy) Check

func (p *ConfigPolicy) Check(toolName string, input json.RawMessage) (Decision, error)

Check returns the permission decision for a tool call.

func (*ConfigPolicy) ClearOverride

func (p *ConfigPolicy) ClearOverride(toolName string)

ClearOverride removes a previously set override for the given tool. Used by harness worker agents to exempt themselves from the strict write guard applied to the main agent.

func (*ConfigPolicy) CurrentMode

func (p *ConfigPolicy) CurrentMode() PermissionMode

CurrentMode returns the current permission mode (thread-safe).

func (*ConfigPolicy) GetDecision

func (p *ConfigPolicy) GetDecision(toolName string) Decision

GetDecision returns the current decision for a tool (for TUI display).

func (*ConfigPolicy) IsDangerous

func (p *ConfigPolicy) IsDangerous(command string) bool

IsDangerous returns true if the command is inherently dangerous.

func (*ConfigPolicy) Mode

func (p *ConfigPolicy) Mode() PermissionMode

Mode returns the current permission mode.

func (*ConfigPolicy) SetMode

func (p *ConfigPolicy) SetMode(mode PermissionMode)

SetMode changes the permission mode at runtime.

func (*ConfigPolicy) SetOverride

func (p *ConfigPolicy) SetOverride(toolName string, decision Decision)

SetOverride allows runtime modification of per-tool policy.

type DangerLevel

type DangerLevel int

DangerLevel indicates how dangerous a command is.

const (
	DangerNone DangerLevel = iota
	DangerLow
	DangerMedium
	DangerHigh
	DangerCritical
)

func (DangerLevel) String

func (l DangerLevel) String() string

type DangerousCheck

type DangerousCheck struct {
	Level   DangerLevel
	Pattern string
	Reason  string
}

DangerousCheck represents a single danger pattern match.

func (DangerousCheck) Suggestion

func (c DangerousCheck) Suggestion() string

Suggestion returns a human-readable suggestion for the danger check.

type DangerousDetector

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

DangerousDetector detects dangerous shell commands.

func NewDangerousDetector

func NewDangerousDetector() *DangerousDetector

NewDangerousDetector creates a detector with default dangerous patterns.

func (*DangerousDetector) Check

func (d *DangerousDetector) Check(command string) DangerousCheck

Check returns the most severe danger match for the command.

func (*DangerousDetector) IsDangerous

func (d *DangerousDetector) IsDangerous(command string) bool

IsDangerous returns true if the command matches any dangerous pattern.

func (*DangerousDetector) IsExtremelyDangerous

func (d *DangerousDetector) IsExtremelyDangerous(command string) bool

IsExtremelyDangerous returns true if the command matches critical-level patterns. Used by BypassMode to decide which operations still need confirmation.

type Decision

type Decision int

Decision represents the outcome of a permission check.

const (
	Allow Decision = iota
	Deny
	Ask
)

func (Decision) String

func (d Decision) String() string

type PathSandbox

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

PathSandbox restricts file operations to allowed directories.

func NewPathSandbox

func NewPathSandbox(allowedDirs []string) *PathSandbox

NewPathSandbox creates a sandbox with the given allowed directories. If empty, defaults to the current working directory.

func (*PathSandbox) Allowed

func (s *PathSandbox) Allowed(path string) bool

Allowed returns true if the path is within an allowed directory. It resolves symlinks to prevent sandbox escapes.

func (*PathSandbox) AllowedDirs

func (s *PathSandbox) AllowedDirs() []string

AllowedDirs returns the list of allowed directories.

type PermissionMode

type PermissionMode int

PermissionMode controls how the agent handles tool permissions.

const (
	// SupervisedMode respects explicit per-tool rules and asks for anything unspecified.
	SupervisedMode PermissionMode = iota
	// PlanMode allows a strict read-only subset and denies writes/commands automatically.
	PlanMode
	// AutoMode allows safe operations and denies dangerous ones automatically.
	AutoMode
	// BypassMode allows almost everything automatically and only asks on critical cases.
	BypassMode
	// AutopilotMode uses bypass permissions and keeps going when the model asks the user to decide.
	AutopilotMode
)

func ParsePermissionMode

func ParsePermissionMode(s string) PermissionMode

ParsePermissionMode parses a string to PermissionMode (case-insensitive).

func (PermissionMode) Next

func (m PermissionMode) Next() PermissionMode

Next returns the next mode in the cycle: supervised → plan → auto → bypass → autopilot → supervised.

func (PermissionMode) String

func (m PermissionMode) String() string

type PermissionPolicy

type PermissionPolicy interface {
	// Check returns the decision for a tool call.
	Check(toolName string, input json.RawMessage) (Decision, error)

	// Mode returns the current permission mode.
	Mode() PermissionMode

	// IsDangerous returns true if the command/operation is inherently dangerous,
	// regardless of the tool-level policy. Used for run_command specifically.
	IsDangerous(command string) bool

	// AllowedPath returns true if the given file path is within the sandbox.
	AllowedPath(path string) bool

	// AllowedPathForTool returns true if the given path is within the sandbox
	// for the specific file tool being executed.
	AllowedPathForTool(toolName, path string) bool

	// SetOverride allows runtime modification of per-tool policy (e.g., 'a' key in TUI).
	SetOverride(toolName string, decision Decision)
}

PermissionPolicy determines whether a tool call needs user approval.

type ToolRule

type ToolRule struct {
	Decision Decision `yaml:"decision"`
}

ToolRule defines the permission level for a tool.