package tool // import "github.com/ricardo/anthrogo/pkg/tool"
FUNCTIONS
func MCPToolName(server, tool string) string
MCPToolName composes an MCP tool name from a server and tool name, fitting
the Anthropic 64-char limit. When either piece overflows its per-piece
budget, both are truncated and an 8-char sha256 hex suffix is appended for
collision resistance.
TYPES
type AskUserQuestion struct{ DefaultPermission }
func (AskUserQuestion) Call(_ context.Context, input map[string]any, tcx *Context) (Result, error)
func (AskUserQuestion) Description(context.Context) string
func (AskUserQuestion) IsConcurrencySafe() bool
func (AskUserQuestion) IsReadOnly() bool
func (AskUserQuestion) Name() string
func (AskUserQuestion) Schema() map[string]any
func (AskUserQuestion) UserFacingName(map[string]any) string
type BackgroundCancel struct {
DefaultPermission
Manager *bgtasks.Manager
}
BackgroundCancel cancels a running background task.
func (b *BackgroundCancel) Call(_ context.Context, input map[string]any, _ *Context) (Result, error)
func (*BackgroundCancel) Description(context.Context) string
func (*BackgroundCancel) IsConcurrencySafe() bool
func (*BackgroundCancel) IsReadOnly() bool
func (*BackgroundCancel) Name() string
func (*BackgroundCancel) Schema() map[string]any
func (*BackgroundCancel) UserFacingName(_ map[string]any) string
type BackgroundLaunch struct {
DefaultPermission
Manager *bgtasks.Manager
}
BackgroundLaunch launches a shell command as a background task.
func (b *BackgroundLaunch) Call(_ context.Context, input map[string]any, _ *Context) (Result, error)
func (*BackgroundLaunch) Description(context.Context) string
func (*BackgroundLaunch) IsConcurrencySafe() bool
func (*BackgroundLaunch) IsReadOnly() bool
func (*BackgroundLaunch) Name() string
func (*BackgroundLaunch) Schema() map[string]any
func (*BackgroundLaunch) UserFacingName(input map[string]any) string
type BackgroundOutput struct {
DefaultPermission
Manager *bgtasks.Manager
}
BackgroundOutput fetches captured stdout and stderr for a task.
func (b *BackgroundOutput) Call(_ context.Context, input map[string]any, _ *Context) (Result, error)
func (*BackgroundOutput) Description(context.Context) string
func (*BackgroundOutput) IsConcurrencySafe() bool
func (*BackgroundOutput) IsReadOnly() bool
func (*BackgroundOutput) Name() string
func (*BackgroundOutput) Schema() map[string]any
func (*BackgroundOutput) UserFacingName(_ map[string]any) string
type BackgroundStatus struct {
DefaultPermission
Manager *bgtasks.Manager
}
BackgroundStatus returns status of one task or lists all tasks.
func (b *BackgroundStatus) Call(_ context.Context, input map[string]any, _ *Context) (Result, error)
func (*BackgroundStatus) Description(context.Context) string
func (*BackgroundStatus) IsConcurrencySafe() bool
func (*BackgroundStatus) IsReadOnly() bool
func (*BackgroundStatus) Name() string
func (*BackgroundStatus) Schema() map[string]any
func (*BackgroundStatus) UserFacingName(_ map[string]any) string
type Bash struct{ DefaultPermission }
Bash executes a shell command. M1 has no sandbox, no AST security,
no background tasks — those are deferred to M5 alongside the upstream
bash{Permissions,Security,Sandbox} modules.
M10.2 adds opt-in lightweight sandboxing via sandbox:true (see Schema).
func (Bash) Call(parent context.Context, input map[string]any, tcx *Context) (Result, error)
func (Bash) Description(context.Context) string
func (Bash) IsConcurrencySafe() bool
func (Bash) IsReadOnly() bool
func (Bash) Name() string
func (Bash) Schema() map[string]any
func (Bash) UserFacingName(input map[string]any) string
type ContainerExec struct{ DefaultPermission }
ContainerExec runs a command inside a docker or podman container. M10.7:
provides real OS-level isolation vs M10.2 Bash sandbox's env scrubbing.
M11.7: adds pull_policy, gpu, user, workdir, and separate stdout/stderr
capture.
func (*ContainerExec) Call(ctx context.Context, input map[string]any, tcx *Context) (Result, error)
func (ContainerExec) Description(context.Context) string
func (ContainerExec) IsConcurrencySafe() bool
func (ContainerExec) IsReadOnly() bool
func (ContainerExec) Name() string
func (ContainerExec) Schema() map[string]any
func (ContainerExec) UserFacingName(input map[string]any) string
type Context struct {
Cwd string
Messages []message.Message
Permissions *permissions.Context
AbortContext context.Context
// SubagentPrefixChain carries the outer Task description chain for nested
// subagent runs. Each entry is an ancestor Task's description. The inner
// Task prepends these to build the full "[Task: outer → inner]" prefix.
SubagentPrefixChain []string
// Surface-injected; nil-safe.
RequestPrompt func(source string, req PromptRequest) (PromptResponse, error)
AppendUIMessage func(msg string)
SendOSNotify func(msg, kind string)
SetToolProgress func(toolUseID string, p any)
}
Context flows through a turn — engine builds it once per turn, hands it to
every Tool.Call. Surface (TUI / headless) injects callbacks.
type DefaultPermission struct{}
DefaultPermission satisfies the Permission method by deferring to the gate
(returns BehaviorAsk). Embed it in tools that don't have tool-specific
gating.
func (DefaultPermission) Permission(context.Context, map[string]any) permissions.Decision
type Diff struct{ DefaultPermission }
Diff wraps `git diff` for the working tree or staged area.
func (Diff) Call(_ context.Context, input map[string]any, tcx *Context) (Result, error)
func (Diff) Description(context.Context) string
func (Diff) IsConcurrencySafe() bool
func (Diff) IsReadOnly() bool
func (Diff) Name() string
func (Diff) Schema() map[string]any
func (Diff) UserFacingName(input map[string]any) string
type Edit struct{ DefaultPermission }
func (Edit) Call(_ context.Context, input map[string]any, _ *Context) (Result, error)
func (Edit) Description(context.Context) string
func (Edit) IsConcurrencySafe() bool
func (Edit) IsReadOnly() bool
func (Edit) Name() string
func (Edit) Schema() map[string]any
func (Edit) UserFacingName(input map[string]any) string
type EnterPlanMode struct{ DefaultPermission }
func (EnterPlanMode) Call(_ context.Context, _ map[string]any, tcx *Context) (Result, error)
func (EnterPlanMode) Description(context.Context) string
func (EnterPlanMode) IsConcurrencySafe() bool
func (EnterPlanMode) IsReadOnly() bool
func (EnterPlanMode) Name() string
func (EnterPlanMode) Schema() map[string]any
func (EnterPlanMode) UserFacingName(map[string]any) string
type ExitPlanMode struct{ DefaultPermission }
func (ExitPlanMode) Call(_ context.Context, _ map[string]any, tcx *Context) (Result, error)
func (ExitPlanMode) Description(context.Context) string
func (ExitPlanMode) IsConcurrencySafe() bool
func (ExitPlanMode) IsReadOnly() bool
func (ExitPlanMode) Name() string
func (ExitPlanMode) Schema() map[string]any
func (ExitPlanMode) UserFacingName(map[string]any) string
type Format struct{ DefaultPermission }
Format formats one or more source files using the language-appropriate
formatter.
func (Format) Call(_ context.Context, input map[string]any, tcx *Context) (Result, error)
func (Format) Description(context.Context) string
func (Format) IsConcurrencySafe() bool
func (Format) IsReadOnly() bool
func (Format) Name() string
func (Format) Schema() map[string]any
func (Format) UserFacingName(input map[string]any) string
type Git struct{ DefaultPermission }
Git exposes a read-only subset of git subcommands.
func (Git) Call(_ context.Context, input map[string]any, tcx *Context) (Result, error)
func (Git) Description(context.Context) string
func (Git) IsConcurrencySafe() bool
func (Git) IsReadOnly() bool
func (Git) Name() string
func (Git) Schema() map[string]any
func (Git) UserFacingName(input map[string]any) string
type Glob struct{ DefaultPermission }
func (Glob) Call(_ context.Context, input map[string]any, tcx *Context) (Result, error)
func (Glob) Description(context.Context) string
func (Glob) IsConcurrencySafe() bool
func (Glob) IsReadOnly() bool
func (Glob) Name() string
func (Glob) Schema() map[string]any
func (Glob) UserFacingName(input map[string]any) string
type Grep struct{ DefaultPermission }
func (Grep) Call(ctx context.Context, input map[string]any, tcx *Context) (Result, error)
func (Grep) Description(context.Context) string
func (Grep) IsConcurrencySafe() bool
func (Grep) IsReadOnly() bool
func (Grep) Name() string
func (Grep) Schema() map[string]any
func (Grep) UserFacingName(input map[string]any) string
type HTTPRequest struct{ DefaultPermission }
HTTPRequest is a general-purpose HTTP client tool (curl-like). Unlike
WebFetch (GET-only + HTML→markdown), HTTPRequest supports all common
HTTP verbs, raw body in/out, configurable timeout and response size cap,
and optional file-save of the response body.
func (*HTTPRequest) Call(ctx context.Context, input map[string]any, _ *Context) (Result, error)
func (*HTTPRequest) Description(context.Context) string
func (*HTTPRequest) IsConcurrencySafe() bool
func (*HTTPRequest) IsReadOnly() bool
IsReadOnly returns false conservatively; the engine treats per-call.
func (*HTTPRequest) Name() string
func (*HTTPRequest) Schema() map[string]any
func (*HTTPRequest) UserFacingName(input map[string]any) string
type MCPAdapter struct {
DefaultPermission
// Has unexported fields.
}
MCPAdapter wraps one MCP server's tool descriptor as a tool.Tool.
func NewMCPAdapter(serverName string, descriptor *sdk.Tool, invoker MCPInvoker) *MCPAdapter
func (a *MCPAdapter) Call(ctx context.Context, input map[string]any, _ *Context) (Result, error)
func (a *MCPAdapter) Description(_ context.Context) string
func (a *MCPAdapter) IsConcurrencySafe() bool
func (a *MCPAdapter) IsReadOnly() bool
func (a *MCPAdapter) Name() string
func (a *MCPAdapter) Schema() map[string]any
func (a *MCPAdapter) UserFacingName(map[string]any) string
type MCPInvoker func(ctx context.Context, args map[string]any) (*sdk.CallToolResult, error)
MCPInvoker is the callback the manager hands the adapter so the adapter
doesn't import internal/mcp.
type MCPResource struct {
DefaultPermission
// Has unexported fields.
}
MCPResource is a built-in tool for listing or reading MCP server resources.
func NewMCPResource(m MCPResourceManager) *MCPResource
NewMCPResource constructs an MCPResource tool backed by the given manager.
func (t *MCPResource) Call(ctx context.Context, input map[string]any, _ *Context) (Result, error)
func (*MCPResource) Description(context.Context) string
func (*MCPResource) IsConcurrencySafe() bool
func (*MCPResource) IsReadOnly() bool
func (*MCPResource) Name() string
func (*MCPResource) Schema() map[string]any
func (*MCPResource) UserFacingName(input map[string]any) string
type MCPResourceManager interface {
AllResources(ctx context.Context) map[string][]*sdk.Resource
ReadResource(ctx context.Context, server, uri string) (*sdk.ReadResourceResult, error)
}
MCPResourceManager is the slice of internal/mcp.Manager that this tool
needs. Declared here so pkg/tool doesn't import internal/mcp.
type NotebookEdit struct{ DefaultPermission }
func (NotebookEdit) Call(_ context.Context, input map[string]any, _ *Context) (Result, error)
func (NotebookEdit) Description(context.Context) string
func (NotebookEdit) IsConcurrencySafe() bool
func (NotebookEdit) IsReadOnly() bool
func (NotebookEdit) Name() string
func (NotebookEdit) Schema() map[string]any
func (NotebookEdit) UserFacingName(input map[string]any) string
type PromptKind string
PromptKind discriminates the modal variants.
const (
PromptToolPermission PromptKind = "tool_permission"
PromptQuestion PromptKind = "question"
PromptElicitForm PromptKind = "elicit_form" // M6.3: MCP elicitation form
)
type PromptOption struct {
Label string `json:"label"`
Description string `json:"description,omitempty"`
}
PromptOption is one selectable answer for a PromptQuestion.
type PromptRequest struct {
Kind PromptKind
ToolName string
ToolInput map[string]any
InputSummary string
Question string
Options []PromptOption
// PromptElicitForm fields
Message string // server-supplied prompt text
Schema map[string]any // JSON schema the server provided
}
PromptRequest is what a tool (or the engine) asks the surface to display.
type PromptResponse struct {
Allow bool
Remember bool // upgrade to AlwaysAllow rule
Reason string
SelectedLabel string // set for PromptQuestion
Notes string // optional free-text from user
// PromptElicitForm fields
Action string // "accept" | "decline" | "cancel"
FormData map[string]any // parsed JSON submitted by user (when Action=="accept")
}
PromptResponse is the user's reply.
type Read struct{ DefaultPermission }
Read is the M1 file reader. Mirrors src/tools/FileReadTool but without
notebook/image branches (deferred to M2/M3).
func (Read) Call(ctx context.Context, input map[string]any, _ *Context) (Result, error)
func (Read) Description(context.Context) string
func (Read) IsConcurrencySafe() bool
func (Read) IsReadOnly() bool
func (Read) Name() string
func (Read) Schema() map[string]any
func (Read) UserFacingName(input map[string]any) string
type References struct{ DefaultPermission }
References finds all usages (word-boundary occurrences) of a symbol name
across the directory tree.
func (References) Call(ctx context.Context, input map[string]any, tcx *Context) (Result, error)
func (References) Description(context.Context) string
func (References) IsConcurrencySafe() bool
func (References) IsReadOnly() bool
func (References) Name() string
func (References) Schema() map[string]any
func (References) UserFacingName(input map[string]any) string
type Registry struct {
// Has unexported fields.
}
Registry stores Tools in registration order so the API-side tool list is
stable run-to-run (important for prompt caching).
func NewRegistry() *Registry
func (r *Registry) All() []Tool
func (r *Registry) Get(name string) (Tool, bool)
func (r *Registry) Register(t Tool)
func (r *Registry) RemoveByPrefix(prefix string) int
RemoveByPrefix unregisters every tool whose Name() starts with prefix.
Returns the number removed.
type Result struct {
Type ResultType
Text string // canonical payload
Image *message.ImageSource // for ResultImage
ForLLM string // what the model sees in tool_result
ForUser string // optional user-facing summary
Data map[string]any // structured fields the TUI can read
IsError bool
}
Result is what a Tool.Call returns. The TUI consumes ForUser; the engine
pushes ForLLM (or a fallback to Text) back to the model as a tool_result
block.
func (r Result) ModelText() string
ModelText returns the string to send back to the model. Falls back to Text
when ForLLM is empty.
type ResultType string
ResultType discriminates the payload variant.
const (
ResultText ResultType = "text"
ResultImage ResultType = "image"
ResultStructured ResultType = "structured"
)
type SQLQuery struct{ DefaultPermission }
SQLQuery runs a SQL query against postgres, mysql, or sqlite.
SELECT/EXPLAIN/SHOW/DESCRIBE auto-allow; mutating queries go through the
gate.
func (*SQLQuery) Call(ctx context.Context, input map[string]any, _ *Context) (Result, error)
func (*SQLQuery) Description(context.Context) string
func (*SQLQuery) IsConcurrencySafe() bool
func (*SQLQuery) IsReadOnly() bool
func (*SQLQuery) Name() string
func (*SQLQuery) Permission(_ context.Context, input map[string]any) permissions.Decision
func (*SQLQuery) Schema() map[string]any
func (*SQLQuery) UserFacingName(input map[string]any) string
type Skill struct {
DefaultPermission
// Has unexported fields.
}
Skill is a model-invoked tool that returns the body of a registered skill.
func NewSkill(r *skill.Registry) *Skill
func (s *Skill) Call(ctx context.Context, input map[string]any, _ *Context) (Result, error)
func (*Skill) Description(context.Context) string
func (*Skill) IsConcurrencySafe() bool
func (*Skill) IsReadOnly() bool
func (*Skill) Name() string
func (*Skill) Schema() map[string]any
func (*Skill) UserFacingName(input map[string]any) string
type SpeechToText struct{ DefaultPermission }
SpeechToText transcribes an audio file using the whisper CLI.
func (*SpeechToText) Call(ctx context.Context, input map[string]any, _ *Context) (Result, error)
func (*SpeechToText) Description(context.Context) string
func (*SpeechToText) IsConcurrencySafe() bool
func (*SpeechToText) IsReadOnly() bool
func (*SpeechToText) Name() string
func (*SpeechToText) Schema() map[string]any
func (*SpeechToText) UserFacingName(input map[string]any) string
type SymbolSearch struct{ DefaultPermission }
SymbolSearch finds a symbol's definition site by name. Go files are parsed
via go/parser; other languages use regex heuristics.
func (SymbolSearch) Call(ctx context.Context, input map[string]any, tcx *Context) (Result, error)
func (SymbolSearch) Description(context.Context) string
func (SymbolSearch) IsConcurrencySafe() bool
func (SymbolSearch) IsReadOnly() bool
func (SymbolSearch) Name() string
func (SymbolSearch) Schema() map[string]any
func (SymbolSearch) UserFacingName(input map[string]any) string
type Task struct {
DefaultPermission
// Has unexported fields.
}
Task is a built-in tool that spawns a subagent engine to perform a
self-contained multi-step task and returns its final assistant text.
func NewTask(reg *subagent.Registry, runner func(context.Context, TaskOptions) (string, error)) *Task
NewTask creates a Task tool wired with the given subagent registry and
runner. The runner is typically engine.RunSubagent, injected to avoid an
import cycle.
func (t *Task) Call(ctx context.Context, input map[string]any, tcx *Context) (Result, error)
Call invokes the runner with the parsed inputs.
func (t *Task) Description(_ context.Context) string
Description lists available subagent types so the model knows what to pass.
func (*Task) IsConcurrencySafe() bool
IsConcurrencySafe returns true — multiple Task tool_use blocks in one
assistant turn run concurrently via the engine's parallel dispatch path.
func (*Task) IsReadOnly() bool
IsReadOnly returns false — a subagent can call write tools.
func (*Task) Name() string
Name implements Tool.
func (*Task) Schema() map[string]any
Schema returns the JSON schema for Task inputs.
func (*Task) UserFacingName(input map[string]any) string
UserFacingName returns "Task: <description>" for display in the TUI.
type TaskOptions struct {
Description string
Prompt string
SubagentType string
// OnDelta, if non-nil, is invoked for each text delta from the subagent stream.
// Called from a background goroutine; implementations must be thread-safe.
OnDelta func(string)
// PrefixChain carries ancestor Task descriptions for nested prefix display.
// Passed through to RunSubagent as SubagentOptions.PrefixChain.
PrefixChain []string
}
TaskOptions carries the parsed input for a Task tool call.
type TextToSpeech struct{ DefaultPermission }
TextToSpeech synthesizes speech from text using a platform system
synthesizer.
func (*TextToSpeech) Call(ctx context.Context, input map[string]any, _ *Context) (Result, error)
func (*TextToSpeech) Description(context.Context) string
func (*TextToSpeech) IsConcurrencySafe() bool
func (*TextToSpeech) IsReadOnly() bool
func (*TextToSpeech) Name() string
func (*TextToSpeech) Schema() map[string]any
func (*TextToSpeech) UserFacingName(input map[string]any) string
type Todo struct {
Content string `json:"content"`
Status string `json:"status"` // pending | in_progress | completed
ActiveForm string `json:"activeForm,omitempty"`
}
Todo mirrors the upstream TodoWriteTool item shape.
type TodoWrite struct {
DefaultPermission
// Has unexported fields.
}
TodoWrite replaces the tool's internal list on each call. M1 keeps a single
session-scoped list; M2 will scope per-session-id when sessions persist.
func (t *TodoWrite) Call(_ context.Context, input map[string]any, _ *Context) (Result, error)
func (*TodoWrite) Description(context.Context) string
func (*TodoWrite) IsConcurrencySafe() bool
func (*TodoWrite) IsReadOnly() bool
func (t *TodoWrite) List() []Todo
func (*TodoWrite) Name() string
func (*TodoWrite) Schema() map[string]any
func (*TodoWrite) UserFacingName(map[string]any) string
type Tool interface {
Name() string
Description(ctx context.Context) string
Schema() map[string]any
UserFacingName(input map[string]any) string
IsReadOnly() bool
IsConcurrencySafe() bool
Permission(ctx context.Context, input map[string]any) permissions.Decision
Call(ctx context.Context, input map[string]any, tcx *Context) (Result, error)
}
Tool is the M1 surface. Smaller than upstream's src/Tool.ts; expanded in M3
(MCP), M4 (hooks/skills), M5 (subagents).
type WebFetch struct {
DefaultPermission
// Has unexported fields.
}
func NewWebFetch() *WebFetch
func (w *WebFetch) Call(ctx context.Context, input map[string]any, _ *Context) (Result, error)
func (*WebFetch) Description(context.Context) string
func (*WebFetch) IsConcurrencySafe() bool
func (*WebFetch) IsReadOnly() bool
func (*WebFetch) Name() string
func (*WebFetch) Schema() map[string]any
func (*WebFetch) UserFacingName(input map[string]any) string
type WebSearch struct {
DefaultPermission
// Has unexported fields.
}
WebSearch is the tool that queries a search provider.
func NewWebSearch(cfg WebSearchConfig) *WebSearch
NewWebSearch creates a WebSearch with the given config.
func (w *WebSearch) Call(ctx context.Context, input map[string]any, _ *Context) (Result, error)
Call dispatches to the configured backend and returns JSON results.
func (*WebSearch) Description(context.Context) string
func (*WebSearch) IsConcurrencySafe() bool
func (*WebSearch) IsReadOnly() bool
func (*WebSearch) Name() string
func (*WebSearch) Schema() map[string]any
func (*WebSearch) UserFacingName(i map[string]any) string
type WebSearchConfig struct {
Backend string
APIKey string
Endpoint string // backend-specific: CSE ID for google, base URL for bing/tavily
URL string // optional full URL override (for testing or self-hosted)
}
WebSearchConfig holds configuration for the WebSearch tool.
type Write struct{ DefaultPermission }
func (Write) Call(_ context.Context, input map[string]any, _ *Context) (Result, error)
func (Write) Description(context.Context) string
func (Write) IsConcurrencySafe() bool
func (Write) IsReadOnly() bool
func (Write) Name() string
func (Write) Schema() map[string]any
func (Write) UserFacingName(input map[string]any) string