Documentation
¶
Overview ¶
Package tool defines the Tool abstraction and a Registry. Built-in tools live in tool/builtin and self-register via init(); plugin-provided tools are added to a runtime Registry alongside the enabled built-ins. The agent sees only a *Registry, never the global built-in set directly.
Index ¶
- Constants
- func PreviewChange(t Tool, args json.RawMessage) (diff.Change, bool)
- func RegisterBuiltin(t Tool)
- func SplitMCPName(name string) (server, tool string, ok bool)
- func WithProgress(ctx context.Context, fn ProgressFunc) context.Context
- type Previewer
- type ProgressFunc
- type ReadOnlyCallChecker
- type Registry
- func (r *Registry) Add(t Tool)
- func (r *Registry) Get(name string) (Tool, bool)
- func (r *Registry) Hide(name string)
- func (r *Registry) IsHidden(name string) bool
- func (r *Registry) Len() int
- func (r *Registry) Names() []string
- func (r *Registry) RemovePrefix(prefix string) int
- func (r *Registry) Schemas() []provider.ToolSchema
- func (r *Registry) VisibleCount() int
- type Tool
Constants ¶
const MCPNamePrefix = "mcp__"
MCPNamePrefix is the namespace every MCP tool name carries: the model-visible name is "mcp__<server>__<tool>".
Variables ¶
This section is empty.
Functions ¶
func PreviewChange ¶
PreviewChange returns the change a writer tool would make for args, or ok=false when there's nothing renderable: t is read-only, doesn't implement Previewer, the preview errored (the edit will likely fail too), or the file is binary.
func RegisterBuiltin ¶
func RegisterBuiltin(t Tool)
RegisterBuiltin registers a compile-time built-in tool. Intended for init(). It panics on a duplicate name, which is a compile-time wiring mistake.
func SplitMCPName ¶
SplitMCPName splits a model-visible MCP tool name "mcp__<server>__<tool>" into its server and tool parts. ok is false for non-MCP (built-in) names and for malformed names missing either part.
func WithProgress ¶
func WithProgress(ctx context.Context, fn ProgressFunc) context.Context
WithProgress stamps ctx with a progress sink the executing tool may call; the agent sets it per call so the chunk reaches the right tool card.
Types ¶
type Previewer ¶
type Previewer interface {
Preview(args json.RawMessage) (diff.Change, error)
}
Previewer is an optional capability a writer Tool may implement: given the same raw JSON args Execute would receive, compute the file change the call *would* make — without touching disk. A front-end uses it to show an approval card or a changed-files panel before the call runs (the permission gate, not Preview, decides whether it may proceed). Type-assert a Tool to Previewer to discover support; the file-writing built-ins implement it, most tools do not.
type ProgressFunc ¶
type ProgressFunc func(chunk string)
ProgressFunc receives a chunk of a tool's combined output as it is produced, so a long-running tool (bash) can stream progress to a frontend before it returns.
func ProgressFrom ¶
func ProgressFrom(ctx context.Context) (ProgressFunc, bool)
ProgressFrom returns the progress sink, if one was stamped (ok is false for a plain context — headless tests or calls outside the run loop).
type ReadOnlyCallChecker ¶
type ReadOnlyCallChecker interface {
ReadOnlyCall(args json.RawMessage) bool
}
ReadOnlyCallChecker is an optional capability a Tool may implement to give a per-call read-only vote, overriding its static ReadOnly()=false. This exists for tools whose side effects depend on the arguments and can't be classified statically — bash is the canonical case: "git log" is read-only, "rm" is not. Under plan mode the agent consults this to let a specific read-only invocation through without unconditionally admitting the tool. Tools that don't implement it fall back to their static ReadOnly() value.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is a per-run set of tools: enabled built-ins plus plugin tools.
func (*Registry) Add ¶
Add inserts (or replaces) a tool, preserving first-seen order. The schema is canonicalized once here — it never changes after registration, so Schemas() (called every turn) reuses the result instead of re-marshaling.
func (*Registry) Hide ¶
Hide marks a registered tool as hidden: it stays callable by name (Get still resolves it, so subagents and explicit calls work) but is omitted from Schemas() so the main-loop model never sees it in its tool list. Used when a tool is meant to be driven only through a subagent skill (e.g. browser tools via run_skill("computer-auto")) rather than advertised to the top-level model. Hiding a name that isn't registered is a no-op.
func (*Registry) IsHidden ¶
IsHidden reports whether a tool has been hidden from the model's schema list.
func (*Registry) RemovePrefix ¶
RemovePrefix unregisters every tool whose name starts with prefix — used to drop an MCP server's "mcp__<server>__" namespace when it's disconnected — and returns the count removed.
func (*Registry) Schemas ¶
func (r *Registry) Schemas() []provider.ToolSchema
Schemas exports tool definitions in stable name order for the provider.
func (*Registry) VisibleCount ¶
VisibleCount returns the number of tools that will be sent to the model (total registered minus hidden). Used for startup logging so the operator can verify the Hide list is taking effect.
type Tool ¶
type Tool interface {
Name() string
Description() string
// Schema returns the JSON Schema for the tool's parameters.
Schema() json.RawMessage
// Execute parses the model-generated raw JSON args and returns result text
// to feed back to the model.
Execute(ctx context.Context, args json.RawMessage) (string, error)
// ReadOnly reports whether the tool has no observable side effects on the
// host. The agent parallelises a batch of tool calls only when every call
// in the batch is ReadOnly; mixed batches stay sequential so write/read
// ordering is preserved. bash and plugin tools must return false because
// their effects can't be inferred statically from args.
ReadOnly() bool
}
Tool is a capability the model can invoke.
func Builtins ¶
func Builtins() []Tool
Builtins returns all registered built-in tools, sorted by name.
func LookupBuiltin ¶
LookupBuiltin returns a registered built-in by name.
Source Files
Directories