permission

package
v0.34.0 Latest Latest
Warning

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

 Go to latest Published: Dec 29, 2025 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package permission provides enhanced permission system aligned with Claude Agent SDK.

Package permission provides a comprehensive permission system for tool execution. It supports multiple approval modes (auto, smart, always_ask) and integrates with the Control Channel for human-in-the-loop interactions.

This package is inspired by Goose's permission system with smart approval mode.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultInspector = NewInspector(ModeSmartApprove)

DefaultInspector is a global default inspector

Functions

func AddRule 

func AddRule(rule Rule)

AddRule adds a rule to the default inspector

func Check 

func Check(ctx context.Context, call *types.ToolCallSnapshot) (*types.ControlPermissionRequiredEvent, error)

Check is a convenience function using the default inspector

func SetMode 

func SetMode(mode Mode)

SetMode sets the mode on the default inspector

Types

type CheckResult 

type CheckResult struct {
	// Allowed 是否允许
	Allowed bool

	// NeedsApproval 是否需要用户审批
	NeedsApproval bool

	// DecidedBy 决策来源
	DecidedBy string

	// Message 消息
	Message string

	// Interrupt 是否中断执行
	Interrupt bool

	// UpdatedInput 修改后的输入
	UpdatedInput map[string]any

	// ApprovalRequest 审批请求事件
	ApprovalRequest *types.ControlPermissionRequiredEvent
}

CheckResult 权限检查结果

type Condition 

type Condition struct {
	// Field is the parameter field to check
	Field string `json:"field"`

	// Operator is the comparison operator (eq, ne, contains, prefix, suffix, regex)
	Operator string `json:"operator"`

	// Value is the value to compare against
	Value string `json:"value"`
}

Condition defines an additional condition for a rule

type Decision 

type Decision string

Decision represents an approval decision 

const (
	DecisionAllow       Decision = "allow"        // Allow this execution
	DecisionDeny        Decision = "deny"         // Deny this execution
	DecisionAllowAlways Decision = "allow_always" // Allow this and future similar executions
	DecisionDenyAlways  Decision = "deny_always"  // Deny this and future similar executions
)

type EnhancedInspector 

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

EnhancedInspector 增强版权限检查器 (Claude Agent SDK 风格) 支持 CanUseTool 回调、沙箱集成、动态权限更新

func NewEnhancedInspector 

func NewEnhancedInspector(cfg *EnhancedInspectorConfig) *EnhancedInspector

NewEnhancedInspector 创建增强版权限检查器

func (*EnhancedInspector) AddRule 

func (i *EnhancedInspector) AddRule(rule Rule)

AddRule 添加规则

func (*EnhancedInspector) Check 

func (i *EnhancedInspector) Check(ctx context.Context, call *types.ToolCallSnapshot) (*CheckResult, error)

Check 执行权限检查 (Claude Agent SDK 风格)

func (*EnhancedInspector) ClearSessionRules 

func (i *EnhancedInspector) ClearSessionRules()

ClearSessionRules 清除会话级规则

func (*EnhancedInspector) GetMode 

func (i *EnhancedInspector) GetMode() Mode

GetMode 获取模式

func (*EnhancedInspector) GetRules 

func (i *EnhancedInspector) GetRules() []Rule

GetRules 获取所有规则

func (*EnhancedInspector) GetToolRisk 

func (i *EnhancedInspector) GetToolRisk(toolName string) RiskLevel

GetToolRisk 获取工具风险级别

func (*EnhancedInspector) GetViolations 

func (i *EnhancedInspector) GetViolations() []types.SandboxViolation

GetViolations 获取违规记录

func (*EnhancedInspector) RecordDecision 

func (i *EnhancedInspector) RecordDecision(req *Request, decision Decision, note string) *Response

RecordDecision 记录决策

func (*EnhancedInspector) RecordViolation 

func (i *EnhancedInspector) RecordViolation(violation types.SandboxViolation)

RecordViolation 记录沙箱违规

func (*EnhancedInspector) RemoveRule 

func (i *EnhancedInspector) RemoveRule(pattern string) bool

RemoveRule 移除规则

func (*EnhancedInspector) SetCanUseTool 

func (i *EnhancedInspector) SetCanUseTool(fn types.CanUseToolFunc)

SetCanUseTool 设置自定义权限回调

func (*EnhancedInspector) SetMode 

func (i *EnhancedInspector) SetMode(mode Mode)

SetMode 设置模式

func (*EnhancedInspector) SetSandboxConfig 

func (i *EnhancedInspector) SetSandboxConfig(cfg *types.SandboxConfig)

SetSandboxConfig 设置沙箱配置

func (*EnhancedInspector) SetToolRisk 

func (i *EnhancedInspector) SetToolRisk(toolName string, level RiskLevel)

SetToolRisk 设置工具风险级别

type EnhancedInspectorConfig 

type EnhancedInspectorConfig struct {
	Mode          Mode
	SandboxConfig *types.SandboxConfig
	CanUseTool    types.CanUseToolFunc
	PersistPath   string
	AutoLoad      bool
}

EnhancedInspectorConfig 增强检查器配置

type Inspector 

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

Inspector provides permission inspection and approval

func NewInspector 

func NewInspector(mode Mode, opts ...InspectorOption) *Inspector

NewInspector creates a new permission inspector

func (*Inspector) AddRule 

func (i *Inspector) AddRule(rule Rule)

AddRule adds a permission rule

func (*Inspector) Check 

func (i *Inspector) Check(ctx context.Context, call *types.ToolCallSnapshot) (*types.ControlPermissionRequiredEvent, error)

Check evaluates whether a tool call should be allowed Returns nil if auto-approved, or a ControlPermissionRequiredEvent if approval needed

func (*Inspector) GetMode 

func (i *Inspector) GetMode() Mode

GetMode returns the current approval mode

func (*Inspector) GetRules 

func (i *Inspector) GetRules() []Rule

GetRules returns all rules

func (*Inspector) GetToolRisk 

func (i *Inspector) GetToolRisk(toolName string) RiskLevel

GetToolRisk returns the risk level for a tool

func (*Inspector) RecordDecision 

func (i *Inspector) RecordDecision(req *Request, decision Decision, note string) *Response

RecordDecision records a user's decision for future reference

func (*Inspector) RemoveRule 

func (i *Inspector) RemoveRule(pattern string) bool

RemoveRule removes a rule by pattern

func (*Inspector) SetMode 

func (i *Inspector) SetMode(mode Mode)

SetMode sets the approval mode

func (*Inspector) SetToolRisk 

func (i *Inspector) SetToolRisk(toolName string, level RiskLevel)

SetToolRisk sets the risk level for a specific tool

type InspectorOption 

type InspectorOption func(*Inspector)

InspectorOption configures an Inspector

func WithAutoLoad 

func WithAutoLoad(autoLoad bool) InspectorOption

WithAutoLoad enables/disables auto-loading rules from disk

func WithPersistPath 

func WithPersistPath(path string) InspectorOption

WithPersistPath sets the path for rule persistence

type Mode 

type Mode string

Mode defines the approval mode for tool execution 

const (
	// ModeAutoApprove automatically approves all tool executions
	ModeAutoApprove Mode = "auto_approve"

	// ModeSmartApprove uses intelligent rules to determine approval
	// - Low-risk tools (read operations) are auto-approved
	// - Medium-risk tools (write operations) require approval
	// - High-risk tools (system commands) always require approval
	ModeSmartApprove Mode = "smart_approve"

	// ModeAlwaysAsk always prompts for user approval
	ModeAlwaysAsk Mode = "always_ask"
)

type Request 

type Request struct {
	// ToolName is the name of the tool
	ToolName string `json:"tool_name"`

	// Arguments are the tool arguments
	Arguments map[string]any `json:"arguments"`

	// RiskLevel is the assessed risk level
	RiskLevel RiskLevel `json:"risk_level"`

	// Context provides additional context
	Context map[string]any `json:"context,omitempty"`

	// CallID is the unique identifier for this tool call
	CallID string `json:"call_id"`
}

Request represents a permission request

type Response 

type Response struct {
	// Request is the original request
	Request *Request `json:"request"`

	// Decision is the approval decision
	Decision Decision `json:"decision"`

	// DecidedBy indicates who made the decision (system, user, rule)
	DecidedBy string `json:"decided_by"`

	// Note is an optional explanation
	Note string `json:"note,omitempty"`

	// DecidedAt is when the decision was made
	DecidedAt time.Time `json:"decided_at"`
}

Response represents a permission response

type RiskLevel 

type RiskLevel string

RiskLevel defines the risk level of a tool or operation 

const (
	RiskLevelLow    RiskLevel = "low"    // Read-only operations
	RiskLevelMedium RiskLevel = "medium" // Write operations with limited scope
	RiskLevelHigh   RiskLevel = "high"   // System commands, network access, etc.
)

type Rule 

type Rule struct {
	// Pattern is the tool name or glob pattern to match
	Pattern string `json:"pattern"`

	// Decision is the default decision for matching tools
	Decision Decision `json:"decision"`

	// RiskLevel is the assigned risk level
	RiskLevel RiskLevel `json:"risk_level,omitempty"`

	// Conditions are additional conditions for the rule
	Conditions []Condition `json:"conditions,omitempty"`

	// ExpiresAt is when this rule expires (for temporary rules)
	ExpiresAt *time.Time `json:"expires_at,omitempty"`

	// CreatedAt is when this rule was created
	CreatedAt time.Time `json:"created_at"`

	// Note is an optional explanation for this rule
	Note string `json:"note,omitempty"`
}

Rule defines a permission rule for a tool or pattern

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.