tool

package
v0.15.0 Latest Latest
Warning

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

 Go to latest Published: Sep 25, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package tool provides the tool registry with permissions and approval hooks.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EffectGrantFromContext added in v0.15.0 

func EffectGrantFromContext(ctx context.Context) (map[Effect]struct{}, bool)

EffectGrantFromContext returns a detached copy of the execution grant.

func EffectKeyFromContext added in v0.15.0 

func EffectKeyFromContext(ctx context.Context) (string, bool)

func IsScratchWorkspace added in v0.15.0 

func IsScratchWorkspace(ctx context.Context) bool

IsScratchWorkspace reports whether workspace writes are scratch effects.

func RequireEffects added in v0.15.0 

func RequireEffects(ctx context.Context, effects ...Effect) error

RequireEffects verifies that an execution grant contains every requested effect. It is used by non-registry effect boundaries such as executable hooks.

func WithEffectGrant added in v0.15.0 

func WithEffectGrant(ctx context.Context, effects ...Effect) context.Context

WithEffectGrant binds the exact effects authorized for an execution. An explicit empty grant denies every effect-bearing tool.

func WithEffectKey added in v0.15.0 

func WithEffectKey(ctx context.Context, key string) context.Context

WithEffectKey binds a host-issued destination idempotency key to one tool invocation. It is never populated from model-supplied arguments.

func WithScratchWorkspace added in v0.15.0 

func WithScratchWorkspace(ctx context.Context) context.Context

WithScratchWorkspace marks filesystem writes in this invocation as candidate or review output rather than delivery-tree mutation.

Types

type ApprovalFunc 

type ApprovalFunc func(ctx context.Context, toolName string, args map[string]any) (bool, error)

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"`
	ParallelSafe         bool                  `json:"parallel_safe,omitempty"`
	Effects              []Effect              `json:"effects,omitempty"`
	ResolveEffects       EffectResolver        `json:"-"`
	Recovery             EffectRecoveryAdapter `json:"-"`
	Handler              Handler               `json:"-"`
}

Definition describes a callable tool.

type Effect added in v0.15.0 

type Effect string

Effect identifies an authority-bearing operation independently of tool names. 

const (
	EffectRead             Effect = "read"
	EffectScratchWrite     Effect = "scratch_write"
	EffectDeliveryWrite    Effect = "delivery_write"
	EffectProcessExecution Effect = "process_execution"
	EffectNetwork          Effect = "network"
	EffectExternalMutation Effect = "external_mutation"
)

type EffectRecoveryAdapter added in v0.15.0 

type EffectRecoveryAdapter interface {
	Prepare(context.Context, map[string]any, string) (string, error)
	Observe(context.Context, string, string) (any, bool, error)
}

EffectRecoveryAdapter is an opt-in host implementation for one destination. Prepare returns a bounded, non-secret observation descriptor; Observe checks the actual destination state using the same host-issued key. A tool without an adapter remains unsafe to replay after an unknown external outcome.

type EffectResolver added in v0.15.0 

type EffectResolver func(context.Context, map[string]any) ([]Effect, error)

EffectResolver determines call-specific effects, such as distinguishing a scratch write from a delivery write after resolving its destination.

type Handler 

type Handler func(ctx context.Context, args map[string]any) (any, error)

Handler is the function signature for tool execution.

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 NewRegistry 

func NewRegistry() *Registry

NewRegistry creates a new tool registry.

func (*Registry) Execute 

func (r *Registry) Execute(ctx context.Context, name string, args map[string]any) (any, error)

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) List 

func (r *Registry) List() []*Definition

List returns all registered tools.

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) Replace added in v0.15.0 

func (r *Registry) Replace(remove []string, replacements []*Definition) error

Replace atomically removes the named tools and installs replacements. It rejects collisions with tools outside the removal set, leaving the registry unchanged on failure.

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 

func (r *Registry) SetApprover(a Approver)

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 

func NewToolkit(name, description string) *Toolkit

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) Enable added in v0.3.0 

func (tk *Toolkit) Enable()

Enable enables the toolkit.

func (*Toolkit) Register added in v0.3.0 

func (tk *Toolkit) Register(registry *Registry)

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 

func (tk *Toolkit) ToolNames() []string

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.

type UserInputFunc added in v0.3.0 

type UserInputFunc func(ctx context.Context, toolName string, prompt string) (string, error)

UserInputFunc is called when a tool needs user input before executing. It should block until input is provided and return the input string.

Source Files

View all Source files

Directories

Path Synopsis
Package builtins provides ready-to-use tool implementations.
 Package builtins provides ready-to-use tool implementations.

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.