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.
validate.go — upgrade spec 3-2: the single place every tool call's args pass through before dispatch. It enforces the schema's required-field list (presence, non-null) so a missing argument fails fast with one uniform message instead of each tool re-implementing the check — or worse, a tool acting on a zero-valued field. Deeper type validation stays with the tools: they own their shapes and already report precise errors there.
Index ¶
- Constants
- func PreviewChange(t Tool, args json.RawMessage) (diff.Change, bool)
- func PreviewChanges(t Tool, args json.RawMessage) ([]diff.Change, bool)
- func RegisterBuiltin(t Tool)
- func SplitMCPName(name string) (server, tool string, ok bool)
- func ValidateArgs(t Tool, args json.RawMessage) error
- func WithProgress(ctx context.Context, fn ProgressFunc) context.Context
- type MultiPreviewer
- 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 PreviewChanges ¶ added in v0.2.0
PreviewChanges returns the per-file changes a writer tool would make for args, or ok=false under the same conditions as PreviewChange. MultiPreviewer tools return their per-file list (binary entries dropped); plain Previewer tools are wrapped into a one-element slice. One computation serves both the dispatch event's diff preview and the checkpoint hook — the caller computes once and passes the result through instead of re-previewing.
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 ValidateArgs ¶ added in v0.2.0
func ValidateArgs(t Tool, args json.RawMessage) error
ValidateArgs returns an error when args is not valid JSON or is missing any field the tool's schema marks required. Tools without a schema or without a required list always pass — validation is additive, never a new gate.
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 MultiPreviewer ¶ added in v0.2.0
type MultiPreviewer interface {
PreviewFiles(args json.RawMessage) ([]diff.Change, error)
}
MultiPreviewer is the multi-file form of Previewer, for writer tools whose single call touches several files (apply_patch). It returns one Change per file so the checkpoint hook can snapshot each and an approval card can list them individually; a move is expressed as a delete of the source plus a create of the destination. Tools implementing only Previewer are wrapped into a one-element slice by PreviewChanges.
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 it 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("desktop-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