Documentation
¶
Overview ¶
Package tool provides the tool registry with permissions and approval hooks.
Index ¶
- type ApprovalFunc
- type Approver
- type Definition
- type Handler
- type Permission
- type PermissionMode
- type Registry
- func (r *Registry) Execute(ctx context.Context, name string, args map[string]any) (any, error)
- func (r *Registry) Get(name string) (*Definition, bool)
- func (r *Registry) List() []*Definition
- func (r *Registry) PermissionMode() PermissionMode
- func (r *Registry) Register(def *Definition)
- func (r *Registry) SetApprovalHandler(fn ApprovalFunc)
- func (r *Registry) SetApprover(a Approver)
- func (r *Registry) SetPermissionMode(mode PermissionMode) error
- func (r *Registry) SetUserInputHandler(fn UserInputFunc)
- type Toolkit
- type UserInputFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ApprovalFunc ¶
ApprovalFunc is called when a tool requires human approval. It should block until approved/denied and return true if approved.
type Approver ¶ added in v0.4.0
type Approver interface {
RequestApproval(ctx context.Context, toolName string, args map[string]any) (bool, error)
}
Approver is the integration seam a human-in-the-loop approval service (e.g. os/approval) plugs into. An implementation blocks until a tool call is approved or denied — honoring ctx cancellation — and returns true if approved. It is intentionally identical in shape to ApprovalFunc so the control-plane approval service can be wired into the tool path without an adapter.
type Definition ¶
type Definition struct {
Name string `json:"name"`
Description string `json:"description"`
Parameters map[string]any `json:"parameters"` // JSON Schema
Permission Permission `json:"permission"`
RequiresConfirmation bool `json:"requires_confirmation,omitempty"`
RequiresUserInput bool `json:"requires_user_input,omitempty"`
Handler Handler `json:"-"`
}
Definition describes a callable tool.
type Permission ¶
type Permission string
Permission levels for tool execution.
const ( PermAllow Permission = "allow" // auto-approved PermRequireApproval Permission = "require_approval" // needs human approval PermDeny Permission = "deny" // blocked )
type PermissionMode ¶ added in v0.11.0
type PermissionMode string
PermissionMode controls how approval-gated tools are handled by a registry. Explicitly denied tools are never bypassed, including in auto-approve mode.
const ( PermissionModePrompt PermissionMode = "prompt" PermissionModeAutoApprove PermissionMode = "auto_approve" PermissionModeDeny PermissionMode = "deny" )
func ParsePermissionMode ¶ added in v0.11.0
func ParsePermissionMode(value string) (PermissionMode, error)
ParsePermissionMode normalizes CLI/YAML aliases and rejects unknown modes.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry manages tool definitions, permissions, and execution.
func (*Registry) Execute ¶
Execute runs a tool by name, enforcing permissions, confirmation, and user input.
func (*Registry) Get ¶ added in v0.3.0
func (r *Registry) Get(name string) (*Definition, bool)
Get returns a tool definition by name.
func (*Registry) PermissionMode ¶ added in v0.11.0
func (r *Registry) PermissionMode() PermissionMode
PermissionMode returns the registry's current approval handling mode.
func (*Registry) Register ¶
func (r *Registry) Register(def *Definition)
Register adds a tool definition.
func (*Registry) SetApprovalHandler ¶
func (r *Registry) SetApprovalHandler(fn ApprovalFunc)
SetApprovalHandler sets the function called for tools requiring approval.
func (*Registry) SetApprover ¶ added in v0.4.0
SetApprover installs an Approver as the approval handler for tools whose Permission is PermRequireApproval (and for RequiresConfirmation tools). It is a convenience over SetApprovalHandler for the common case of connecting the control-plane approval service (os/approval) into the tool execution path. A nil approver clears any installed handler.
func (*Registry) SetPermissionMode ¶ added in v0.11.0
func (r *Registry) SetPermissionMode(mode PermissionMode) error
SetPermissionMode configures registry-wide handling for tools that require approval. Auto-approve skips approval and confirmation prompts but still respects PermDeny. Deny rejects every approval-gated tool without prompting.
func (*Registry) SetUserInputHandler ¶ added in v0.3.0
func (r *Registry) SetUserInputHandler(fn UserInputFunc)
SetUserInputHandler sets the function called for tools requiring user input.
type Toolkit ¶ added in v0.3.0
type Toolkit struct {
Name string `json:"name"`
Description string `json:"description"`
Permission Permission `json:"permission"`
Tools []*Definition `json:"tools"`
Enabled bool `json:"enabled"`
}
Toolkit groups related tool definitions with shared metadata.
func NewToolkit ¶ added in v0.3.0
NewToolkit creates a new toolkit with the given name.
func (*Toolkit) Add ¶ added in v0.3.0
func (tk *Toolkit) Add(def *Definition) *Toolkit
Add adds a tool definition to the toolkit.
func (*Toolkit) Disable ¶ added in v0.3.0
func (tk *Toolkit) Disable()
Disable disables the toolkit.
func (*Toolkit) Register ¶ added in v0.3.0
Register registers all tools from this toolkit into the given registry. If the toolkit is disabled, no tools are registered.
func (*Toolkit) ToolNames ¶ added in v0.3.0
ToolNames returns the names of all tools in the toolkit.
func (*Toolkit) WithPermission ¶ added in v0.3.0
func (tk *Toolkit) WithPermission(p Permission) *Toolkit
WithPermission sets the default permission for all tools in the toolkit.
Source Files
Directories