approval

package
v2.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package approval is the one policy that decides each tool call: whether it runs, waits for an approval, is refused, or whether the tool is not offered to the agent at all. The policy is tools.approval: rules, the first that matches a call deciding it, and a default for the calls no rule matches.

Index

Constants

View Source 
const (
	HintReadOnly       = "read_only"
	HintDestructive    = "destructive"
	HintIdempotent     = "idempotent"
	HintOpenWorld      = "open_world"
	HintCostUnknown    = "cost_unknown"
	HintNetwork        = "network"
	HintExternalWrites = "external_writes"
)

The hints a rule can match. MCP servers declare the first four as tool annotations, which count only from trusted servers (MCPHints); modules declare the last three as effects of a capability (ModuleHints).

View Source 
const SourceBuiltin = "builtin"

SourceBuiltin is the source of Compa's own tools. MCP and module tools have the sources MCPSource and ModuleSource return.

Variables

This section is empty.

Functions

func Approved 

func Approved(ctx context.Context) bool

Approved reports whether ctx is that of a call the operator approved (WithApproved).

func Describe 

func Describe(name string, tool any) (Tool, Info)

Describe returns the policy's view of the tool the agent sees as name, and its Info. A tool that does not implement Described is a builtin.

func MCPHints 

func MCPHints(a MCPAnnotations, trusted bool) []string

MCPHints returns the hints of an MCP tool whose server declares a for it. Left-out annotations take the MCP defaults: not read-only, destructive (unless read-only), not idempotent, open world. A server that is not trusted is not believed: its tools get the defaults whatever it declares.

func MCPSource 

func MCPSource(server string) string

MCPSource returns the source of the tools of the MCP server named server.

func ModuleHints 

func ModuleHints(network, externalWrites, costKnown bool) []string

ModuleHints returns the hints of a module capability that declares these effects.

func ModuleSource 

func ModuleSource(id string) string

ModuleSource returns the source of the capabilities of the module id.

func WithApproved 

func WithApproved(ctx context.Context) context.Context

WithApproved returns ctx for a call that the operator approved, by a rule that allows it (Decision.Approved) or by answering an ask. A module capability run with it may publish.

Types

type Action 

type Action string

Action is what the policy does with a call. 

const (
	// Allow runs the call.
	Allow Action = "allow"
	// Ask runs the call once it is approved: by a registered approver, or
	// else by the owner in chat. No answer denies it.
	Ask Action = "ask"
	// Deny refuses the call.
	Deny Action = "deny"
	// Hide does not offer the tool to the agent; a call of it is refused.
	Hide Action = "hide"
)

type Call 

type Call struct {
	Tool      string
	Arguments map[string]any
	Origin    Origin
	// Job is the scheduled job the call runs for, named in the request.
	Job string
	// Channel and ChatID are the chat the call reports to.
	Channel string
	ChatID  string
}

Call is a tool call made outside an agent turn, such as a scheduled command.

type Decision 

type Decision struct {
	Action Action `json:"action"`
	// Index is the position of the rule that decided in Policy.Rules, or -1
	// when the default did.
	Index int `json:"index"`
	// Rule is the rule that decided; nil when the default did.
	Rule *Rule `json:"rule,omitempty"`
}

Decision is the action for a call and the rule that chose it.

func (Decision) Approved 

func (d Decision) Approved() bool

Approved reports whether a rule, rather than the default, allows the call: a standing approval by the operator, as an approved ask is a single one.

type Described 

type Described interface {
	ApprovalInfo() Info
}

Described is implemented by the tools that are not Compa's own.

type Gate 

type Gate interface {
	Check(ctx context.Context, call Call) error
}

Gate decides the calls made outside an agent turn by the policy, asking when it says to. A nil error lets the call run; the error of a call that may not run says why.

type Info 

type Info struct {
	// Source is MCPSource(server) or ModuleSource(id).
	Source string `json:"source"`
	// Name is the tool's own name at its source: the MCP tool's name, or the
	// module capability's ID.
	Name string `json:"name,omitempty"`
	// Hints are what rules match: MCPHints or ModuleHints.
	Hints []string `json:"hints,omitempty"`
	// Trusted reports, for an MCP tool, whether its server is trusted.
	Trusted bool `json:"trusted,omitempty"`
	// Annotations are an MCP tool's annotations as its server declares them,
	// trusted or not.
	Annotations any `json:"annotations,omitempty"`
	// Meta is an MCP tool's _meta.
	Meta map[string]any `json:"meta,omitempty"`
	// Effects are a module capability's declared effects.
	Effects any `json:"effects,omitempty"`
}

Info is what a tool that is not Compa's own tells the policy and the approvers about itself.

type MCPAnnotations 

type MCPAnnotations struct {
	ReadOnly    bool
	Destructive *bool
	Idempotent  bool
	OpenWorld   *bool
}

MCPAnnotations are the annotations an MCP server declares for a tool. A nil pointer is an annotation the server left out.

type Origin 

type Origin string

Origin is where the turn that makes a call came from. 

const (
	OriginWeb  Origin = "web"  // the web UI
	OriginCLI  Origin = "cli"  // the terminal
	OriginChat Origin = "chat" // a chat app
	OriginCron Origin = "cron" // a scheduled job or the heartbeat
)

type Policy 

type Policy struct {
	// Default decides the calls no rule matches; empty means allow.
	Default Action `json:"default,omitempty"`
	Rules   []Rule `json:"rules"`
}

Policy is tools.approval.

func DefaultPolicy 

func DefaultPolicy() Policy

DefaultPolicy asks before a module capability that may cost money, reaches the network or writes outside the host runs, and before a skill is installed. Everything else is allowed.

func (Policy) Decide 

func (p Policy) Decide(tool Tool, origin Origin) Decision

Decide returns the action for a call of tool from origin: that of the first rule matching it, or the default.

func (*Policy) UnmarshalJSON 

func (p *Policy) UnmarshalJSON(data []byte) error

UnmarshalJSON sets the fields data holds and keeps the others, as config loading over the defaults needs. Rules that data holds replace p's rules: decoding them into p's would mix the fields of both.

func (Policy) Validate 

func (p Policy) Validate() error

Validate returns an error naming the first setting of p that is not valid.

type Rule 

type Rule struct {
	// Tool matches the name the agent sees, such as "exec" or "mcp_github_*".
	Tool string `json:"tool,omitempty"`
	// Source matches the tool's source: "builtin", "mcp:<server>" or
	// "module:<id>".
	Source string `json:"source,omitempty"`
	// Origin matches calls from any of these origins.
	Origin []Origin `json:"origin,omitempty"`
	// Hints matches tools that have any of these hints.
	Hints  []string `json:"hints,omitempty"`
	Action Action   `json:"action"`
}

Rule decides the calls that match every field it sets. In Tool and Source, '*' matches any run of characters and '?' any one character.

type Tool 

type Tool struct {
	// Name is the name the agent sees.
	Name string
	// Source is SourceBuiltin, MCPSource(server) or ModuleSource(id).
	Source string
	Hints  []string
}

Tool is what the policy knows of a tool.

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.