agent

Documentation

Overview

Package agent provides agent loop orchestration and tool approval.

Index

• func AllowlistKey(toolName string, args map[string]any) string
• func FormatApprovalResult(toolName string, args map[string]any, result ApprovalResult) string
• func FormatDeniedResult(command string, pattern string) string
• func FormatDenyResult(toolName string, reason string) string
• func IsAutoAllowed(command string) bool
• func IsDenied(command string) (bool, string)
• func PromptYesNo(question string) (bool, error)
• func ToolDisplayName(toolName string) string
• type ApprovalDecision
• type ApprovalManager
  • func NewApprovalManager() *ApprovalManager
  • func (a *ApprovalManager) AddToAllowlist(toolName string, args map[string]any)
  • func (a *ApprovalManager) AllowedTools() []string
  • func (a *ApprovalManager) IsAllowed(toolName string, args map[string]any) bool
  • func (a *ApprovalManager) RequestApproval(toolName string, args map[string]any) (ApprovalResult, error)
  • func (a *ApprovalManager) Reset()
• type ApprovalResult

Functions

func AllowlistKey

func AllowlistKey(toolName string, args map[string]any) string

AllowlistKey generates the key for exact allowlist lookup.

func FormatApprovalResult

func FormatApprovalResult(toolName string, args map[string]any, result ApprovalResult) string

FormatApprovalResult returns a formatted string showing the approval result.

func FormatDeniedResult

func FormatDeniedResult(command string, pattern string) string

FormatDeniedResult returns the tool result message when a command is blocked.

func FormatDenyResult

func FormatDenyResult(toolName string, reason string) string

FormatDenyResult returns the tool result message when a tool is denied.

func IsAutoAllowed

func IsAutoAllowed(command string) bool

IsAutoAllowed checks if a bash command is auto-allowed (no prompt needed).

func IsDenied

func IsDenied(command string) (bool, string)

IsDenied checks if a bash command matches deny patterns. Returns true and the matched pattern if denied.

func PromptYesNo

func PromptYesNo(question string) (bool, error)

PromptYesNo displays a simple Yes/No prompt and returns the user's choice. Returns true for Yes, false for No.

func ToolDisplayName

func ToolDisplayName(toolName string) string

ToolDisplayName returns the human-readable display name for a tool.

Types

type ApprovalDecision

type ApprovalDecision int

ApprovalDecision represents the user's decision for a tool execution.

const (
	// ApprovalDeny means the user denied execution.
	ApprovalDeny ApprovalDecision = iota
	// ApprovalOnce means execute this one time only.
	ApprovalOnce
	// ApprovalAlways means add to session allowlist.
	ApprovalAlways
)

type ApprovalManager

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

ApprovalManager manages tool execution approvals.

func NewApprovalManager

func NewApprovalManager() *ApprovalManager

NewApprovalManager creates a new approval manager.

func (*ApprovalManager) AddToAllowlist

func (a *ApprovalManager) AddToAllowlist(toolName string, args map[string]any)

AddToAllowlist adds a tool/command to the session allowlist. For bash commands, it adds the prefix pattern instead of exact command.

func (*ApprovalManager) AllowedTools

func (a *ApprovalManager) AllowedTools() []string

AllowedTools returns a list of tools and prefixes in the allowlist.

func (*ApprovalManager) IsAllowed

func (a *ApprovalManager) IsAllowed(toolName string, args map[string]any) bool

IsAllowed checks if a tool/command is allowed (exact match or prefix match). For bash commands, hierarchical path matching is used - if "cat:tools/" is allowed, then "cat:tools/subdir/" is also allowed (subdirectories inherit parent permissions).

func (*ApprovalManager) RequestApproval

func (a *ApprovalManager) RequestApproval(toolName string, args map[string]any) (ApprovalResult, error)

RequestApproval prompts the user for approval to execute a tool. Returns the decision and optional deny reason.

func (*ApprovalManager) Reset

func (a *ApprovalManager) Reset()

Reset clears the session allowlist.

type ApprovalResult

type ApprovalResult struct {
	Decision   ApprovalDecision
	DenyReason string
}

ApprovalResult contains the decision and optional deny reason.