tool

package
v0.2.0-alpha.1 Latest Latest
Warning

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

 Go to latest Published: Aug 23, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package tool provides concrete agent tools (Read, Write, Edit, Glob, Grep, Bash, WebFetch, TodoWrite, NoteWrite, Skill, Task, and MCP gateway tools).

Package tools provides concrete agent tools (e.g. read_file, write_file, webfetch, todowrite).

Package tools provides concrete agent tools (e.g. read_file, write_file, webfetch).

Index

Constants

View Source 
const (
	ToolNameLoadMCPTools = "LoadMcpTools"
	ToolNameCallMCPTool  = "CallMcpTool"
)
View Source 
const (
	ToolNameRead      = "Read"
	ToolNameWrite     = "Write"
	ToolNameEdit      = "Edit"
	ToolNameGlob      = "Glob"
	ToolNameGrep      = "Grep"
	ToolNameBash      = "Bash"
	ToolNameWebFetch  = "WebFetch"
	ToolNameTodoWrite = "TodoWrite"
	ToolNameNoteWrite = "NoteWrite"
	ToolNameSkill     = "Skill"
	ToolNameTask      = "Task"
	// ToolNameUploadArtifact is registered only where the surface has an
	// artifact service; a session with none does not offer it at all.
	ToolNameUploadArtifact = "UploadArtifact"
	// The Job tools and Monitor are registered only where local background
	// jobs are enabled (TUI and Desktop), and never inside subagents.
	ToolNameJobList   = "JobList"
	ToolNameJobOutput = "JobOutput"
	ToolNameJobStop   = "JobStop"
	ToolNameMonitor   = "Monitor"
)

Tool name constants — single source of truth for every tool's Name(). Use camelCase for LLM-facing names.

View Source 
const (
	GeneralSubAgentPrompt = `` /* 234-byte string literal not displayed */

	ExploreSubAgentPrompt = `` /* 242-byte string literal not displayed */

	ShellSubAgentPrompt = `` /* 194-byte string literal not displayed */
)

Built-in sub-agent system prompts.

View Source 
const (
	StatusPending    = agent.TodoPending
	StatusInProgress = agent.TodoInProgress
	StatusCompleted  = agent.TodoCompleted
)

Valid todo statuses. The values live in internal/core/agent, which owns durable session state; these names stay for the tool's own schema and messages.

View Source 
const DefaultLimit = 1000

DefaultLimit is the default number of lines returned when limit is not specified.

View Source 
const (
	// MaxContentRunes is the maximum runes of fetched content before truncation.
	MaxContentRunes = 200_000
)

Variables

View Source 
var BuiltinSubAgentDefs = []BuiltinSubAgentDef{
	{
		Name:         "general",
		ToolNames:    nil,
		SystemPrompt: GeneralSubAgentPrompt,
		Description:  "General-purpose agent with all tools for multi-step tasks.",
	},
	{
		Name:         "explore",
		ToolNames:    []string{ToolNameRead, ToolNameGlob, ToolNameGrep},
		SystemPrompt: ExploreSubAgentPrompt,
		Description:  "Read-only agent for fast codebase exploration (Read, Glob, Grep).",
	},
	{
		Name:         "shell",
		ToolNames:    []string{ToolNameBash},
		SystemPrompt: ShellSubAgentPrompt,
		Description:  "Command execution specialist (Bash only).",
	},
}

BuiltinSubAgentDefs defines the built-in sub-agent types in display order.

Functions

func GatewayTools 

func GatewayTools(reg *mcp.Registry) []llm.Tool

GatewayTools returns LoadMcpTools and CallMcpTool bound to reg.

func LoadAgentDefs 

func LoadAgentDefs(dir string) ([]subagent.Def, error)

LoadAgentDefs reads all files from dir, parses each as an agent definition, and returns the valid definitions sorted alphabetically by Name. If dir does not exist, returns (nil, nil) — not an error. Individual files that fail to parse are skipped with a log warning.

func LoadAgentDefsFromPaths 

func LoadAgentDefsFromPaths(dirs []string) ([]subagent.Def, error)

LoadAgentDefsFromPaths loads agent definitions from multiple directories in priority order. Directories are scanned in order; if two directories contain a definition with the same Name, the first one wins (project-level overrides global-level). Missing directories are gracefully skipped. This is the unlabelled form, for a caller with no layering to express.

Types

type AgentDefResolution 

type AgentDefResolution struct {
	Defs     []subagent.Def
	Shadowed []plugin.Shadowed
	Findings []plugin.Finding
}

AgentDefResolution is what scanning every source produced: the definitions that load, what a higher layer shadowed, and the collisions that stopped a name from loading at all.

func ResolveAgentDefs 

func ResolveAgentDefs(sources []plugin.Source) (AgentDefResolution, error)

ResolveAgentDefs scans priority-ordered sources and reduces them to one definition per name. Sources come from internal/config: workspace, then global, then each plugin in name order.

type AgentTypeConfig 

type AgentTypeConfig struct {
	Tools         []llm.Tool // tools available to this agent type
	SystemPrompt  string     // system prompt for the sub-agent
	Description   string     // LLM-readable description of this agent type
	Model         string     // model name to use; "" = runner default
	MaxIterations int        // iteration cap; 0 = defaultSubAgentMaxIter (50)
}

AgentTypeConfig holds the configuration for one agent type (built-in or user-defined).

type ArtifactPublisher 

type ArtifactPublisher interface {
	PublishArtifact(ctx context.Context, in ArtifactUpload) (PublishedArtifact, error)
}

ArtifactPublisher hands one local file to the artifact service.

A port rather than the capability itself: this package must not know whether the file reaches a server over a person's session or over a run token, and must not grow a dependency on the service to find out. A surface that has no implementation does not register the tool — see docs/design/unified-artifacts.md section 7.1.

type ArtifactUpload 

type ArtifactUpload struct {
	// Path is the resolved absolute path of a regular, readable file.
	Path string
	// Filename is the name the artifact carries, already reduced to one element.
	Filename string
	Title    string
}

ArtifactUpload is one file an agent chose to publish.

type Bash 

type Bash struct {
	// contains filtered or unexported fields
}

Bash runs a shell command in the workspace (one command per call).

func NewBash 

func NewBash(workspaceRoot string) *Bash

NewBash creates a Bash tool that runs commands under the given workspace root.

func (*Bash) Access 

func (b *Bash) Access(_ map[string]any) llm.Access

Name returns the tool name for the LLM. Access implements llm.AccessDeclarer.

func (*Bash) CheckArgs 

func (b *Bash) CheckArgs(args map[string]any) llm.ToolAction

CheckArgs implements llm.ArgChecker.

Decision order (each step short-circuits):

  1. Catastrophic patterns (rm -rf /, raw dd, mkfs on device) — always Deny.
  2. Risky patterns (curl, npm, sudo, …) — Ask, unless auto-allow applies.

Auto-allow demotes Ask → Allow when:

  • the sandbox is enabled,
  • its mode is auto_allow (config.auto_allow_bash_if_sandboxed),
  • the command would actually be sandboxed (not in excluded_commands),
  • the caller did not pass dangerously_disable_sandbox=true.

Matches Claude Code's documented behavior in /sandboxing: catastrophic destructive commands still prompt even in auto-allow mode; everything else is contained by the OS sandbox boundary.

func (*Bash) DefaultAction 

func (b *Bash) DefaultAction() llm.ToolAction

DefaultAction overrides the action derived from Access, leaving CheckArgs above as the only authority on shell commands.

The derived tier is a fallback for tools with no judgement of their own. Bash has one, and a sharper one: catastrophic denies, risky asks, the rest runs. Letting the category default apply on top would prompt for every `ls` and `git status`, which is how a permission prompt becomes something people switch off. See docs/design/tool-permissions.md §6.

func (*Bash) Description 

func (b *Bash) Description() string

Description returns a short description so the LLM knows when to use this tool.

func (*Bash) Execute 

func (b *Bash) Execute(ctx context.Context, args map[string]any) (string, error)

Execute runs the command in b.root with the given timeout, captures combined stdout+stderr, and returns the result (truncated if needed). On success (exit 0) returns output and nil error. On non-zero exit or timeout returns a clear message and nil error so the LLM receives a readable result. Returns error only for argument validation (missing or empty command).

func (*Bash) Name 

func (b *Bash) Name() string

func (*Bash) Parameters 

func (b *Bash) Parameters() any

Parameters returns the OpenAI-style JSON schema for the tool arguments.

func (*Bash) WithJobs 

func (b *Bash) WithJobs(m *job.Manager) *Bash

WithJobs returns a copy of b that can detach commands to the given job manager. Nil leaves background execution unavailable.

func (*Bash) WithSandbox 

func (b *Bash) WithSandbox(v agent.SandboxView) *Bash

WithSandbox returns a copy of b that wraps spawned commands through the given SandboxView. Pass agent.NoopSandbox{} (or nil) to disable. Returning a copy keeps Bash safe to share across goroutines.

type BuiltinSubAgentDef 

type BuiltinSubAgentDef struct {
	Name         string
	ToolNames    []string // nil ⇒ all base tools
	SystemPrompt string
	Description  string
}

BuiltinSubAgentDef describes a built-in sub-agent type declaratively. ToolNames lists tool names resolved at runtime; nil means all base tools.

type EditFile 

type EditFile struct {
	// contains filtered or unexported fields
}

EditFile performs exact string replacements in a file under a workspace root.

func NewEditFile 

func NewEditFile(workspaceRoot string) *EditFile

NewEditFile creates an EditFile tool that edits files under the given workspace root.

func (*EditFile) Access 

func (e *EditFile) Access(_ map[string]any) llm.Access

Name returns the tool name for the LLM. Access implements llm.AccessDeclarer.

func (*EditFile) CheckArgs 

func (e *EditFile) CheckArgs(args map[string]any) llm.ToolAction

CheckArgs implements llm.ArgChecker. Editing a sensitive file (credentials, private keys) triggers Ask so the user can confirm intent in interactive sessions.

func (*EditFile) Description 

func (e *EditFile) Description() string

Description returns a short description so the LLM knows when to use this tool.

func (*EditFile) Execute 

func (e *EditFile) Execute(ctx context.Context, args map[string]any) (string, error)

Execute performs string replacement(s) in the file at args["file_path"]. Reads the file, validates old_string uniqueness when replace_all=false, performs replacement(s), and writes back.

func (*EditFile) Name 

func (e *EditFile) Name() string

func (*EditFile) Parameters 

func (e *EditFile) Parameters() any

Parameters returns the OpenAI-style JSON schema for the tool arguments.

type Glob 

type Glob struct {
	// contains filtered or unexported fields
}

Glob lists files matching a glob pattern under a workspace root. Symlinks: doublestar.Glob with WithFilesOnly does not follow symlinks to directories; symlinks to files are included as matches.

func NewGlob 

func NewGlob(workspaceRoot string) *Glob

NewGlob creates a Glob tool that searches for files under the given workspace root.

func (*Glob) Access 

func (g *Glob) Access(_ map[string]any) llm.Access

Name returns the tool name for the LLM. Access implements llm.AccessDeclarer.

func (*Glob) Description 

func (g *Glob) Description() string

Description returns a short description so the LLM knows when to use this tool.

func (*Glob) Execute 

func (g *Glob) Execute(ctx context.Context, args map[string]any) (string, error)

Execute lists files under the search directory that match the pattern, sorted by modification time (newest first). Returns one absolute path per line, or "No files matched the pattern.", or an error for validation/system failures.

func (*Glob) Name 

func (g *Glob) Name() string

func (*Glob) Parameters 

func (g *Glob) Parameters() any

Parameters returns the OpenAI-style JSON schema for the tool arguments.

type Grep 

type Grep struct {
	// contains filtered or unexported fields
}

Grep searches file contents by regex pattern under a workspace root.

func NewGrep 

func NewGrep(workspaceRoot string) *Grep

NewGrep creates a Grep tool that searches file contents under the given workspace root.

func (*Grep) Access 

func (g *Grep) Access(_ map[string]any) llm.Access

Name returns the tool name for the LLM. Access implements llm.AccessDeclarer.

func (*Grep) CheckArgs 

func (g *Grep) CheckArgs(args map[string]any) llm.ToolAction

CheckArgs implements llm.ArgChecker. Grepping inside a sensitive file (credentials, private keys) triggers Ask so the user can confirm intent in interactive sessions.

func (*Grep) Description 

func (g *Grep) Description() string

Description returns a short description so the LLM knows when to use this tool.

func (*Grep) Execute 

func (g *Grep) Execute(ctx context.Context, args map[string]any) (string, error)

Execute searches file contents under the tool's root for the given regex pattern. Returns formatted results based on output_mode, or "No matches found.", or an error.

func (*Grep) Name 

func (g *Grep) Name() string

func (*Grep) Parameters 

func (g *Grep) Parameters() any

Parameters returns the OpenAI-style JSON schema for the tool arguments.

type JobList 

type JobList struct {
	// contains filtered or unexported fields
}

JobList lists this runtime's background jobs.

func NewJobList 

func NewJobList(m *job.Manager) *JobList

func (*JobList) Access 

func (j *JobList) Access(_ map[string]any) llm.Access

func (*JobList) Description 

func (j *JobList) Description() string

func (*JobList) Execute 

func (j *JobList) Execute(_ context.Context, _ map[string]any) (string, error)

func (*JobList) Name 

func (j *JobList) Name() string

func (*JobList) Parameters 

func (j *JobList) Parameters() any

type JobOutput 

type JobOutput struct {
	// contains filtered or unexported fields
}

JobOutput reports one job's status and incremental output.

func NewJobOutput 

func NewJobOutput(m *job.Manager) *JobOutput

func (*JobOutput) Access 

func (j *JobOutput) Access(_ map[string]any) llm.Access

func (*JobOutput) Description 

func (j *JobOutput) Description() string

func (*JobOutput) Execute 

func (j *JobOutput) Execute(_ context.Context, args map[string]any) (string, error)

func (*JobOutput) Name 

func (j *JobOutput) Name() string

func (*JobOutput) Parameters 

func (j *JobOutput) Parameters() any

type JobStop 

type JobStop struct {
	// contains filtered or unexported fields
}

JobStop stops one background job.

func NewJobStop 

func NewJobStop(m *job.Manager) *JobStop

func (*JobStop) Access 

func (j *JobStop) Access(_ map[string]any) llm.Access

Access declares write: stopping changes state. DefaultAction keeps it prompt-free — it only ever terminates jobs this runtime itself started, which the user can equally do from the activity view.

func (*JobStop) DefaultAction 

func (j *JobStop) DefaultAction() llm.ToolAction

func (*JobStop) Description 

func (j *JobStop) Description() string

func (*JobStop) Execute 

func (j *JobStop) Execute(_ context.Context, args map[string]any) (string, error)

func (*JobStop) Name 

func (j *JobStop) Name() string

func (*JobStop) Parameters 

func (j *JobStop) Parameters() any

type Monitor 

type Monitor struct {
	// contains filtered or unexported fields
}

Monitor starts an event watcher: a command expected to stay quiet until something worth delivering happens, whose stdout lines become bounded events. It is a specialized command job, not a second scheduler, and it reuses Bash's argument risk, permission, sandbox, and environment rules — watching is not a way around them.

func NewMonitor 

func NewMonitor(workspaceRoot string) *Monitor

NewMonitor creates a Monitor for the given workspace root.

func (*Monitor) Access 

func (m *Monitor) Access(_ map[string]any) llm.Access

Access declares write: a monitor spawns a process.

func (*Monitor) CheckArgs 

func (m *Monitor) CheckArgs(args map[string]any) llm.ToolAction

CheckArgs applies Bash's command risk classification to the watched command: catastrophic denies, risky asks, the rest runs.

func (*Monitor) DefaultAction 

func (m *Monitor) DefaultAction() llm.ToolAction

DefaultAction defers to CheckArgs, the same authority Bash uses.

func (*Monitor) Description 

func (m *Monitor) Description() string

func (*Monitor) Execute 

func (m *Monitor) Execute(ctx context.Context, args map[string]any) (string, error)

func (*Monitor) Name 

func (m *Monitor) Name() string

func (*Monitor) Parameters 

func (m *Monitor) Parameters() any

func (*Monitor) WithJobs 

func (m *Monitor) WithJobs(j *job.Manager) *Monitor

WithJobs returns a copy that can start monitor jobs. Nil leaves the tool non-functional; surfaces without jobs do not register it at all.

func (*Monitor) WithSandbox 

func (m *Monitor) WithSandbox(v agent.SandboxView) *Monitor

WithSandbox returns a copy whose command resolution wraps through the given SandboxView, exactly as Bash does.

type NoteWrite 

type NoteWrite struct{}

NoteWrite records durable session notes. Unlike a tool result, a note is not a message: it survives history compaction and is re-rendered on every model call, so it is where the agent keeps what the conversation cannot be trusted to hold.

The store is reached through the context rather than held on the tool, because the tool registry is cached per model and shared across sessions.

func NewNoteWrite 

func NewNoteWrite() *NoteWrite

NewNoteWrite creates a NoteWrite tool.

func (*NoteWrite) Access 

func (t *NoteWrite) Access(_ map[string]any) llm.Access

Name returns the tool name for the LLM. Access implements llm.AccessDeclarer. Session notes have no lock, so this is a write and cannot run concurrently with a sibling call.

func (*NoteWrite) DefaultAction 

func (t *NoteWrite) DefaultAction() llm.ToolAction

DefaultAction implements llm.PolicyProvider, overriding the action the permission layer would otherwise derive from Access.

What this writes is the agent's own scratch state, not anything the user owns. Asking a user to approve the agent taking a note would be noise, and the noise would arrive on every run. The write classification above is still the honest one — it is what keeps this tool out of a parallel batch. See docs/design/tool-permissions.md §5.2.

func (*NoteWrite) Description 

func (t *NoteWrite) Description() string

Description tells the LLM what belongs in a note. The behavioural contract matters more than the name here: without a stated rule the list fills with narration and duplicated context.

func (*NoteWrite) Execute 

func (t *NoteWrite) Execute(ctx context.Context, args map[string]any) (string, error)

Execute replaces the session's notes with the given list.

func (*NoteWrite) Name 

func (t *NoteWrite) Name() string

func (*NoteWrite) Parameters 

func (t *NoteWrite) Parameters() any

Parameters returns the OpenAI-style JSON schema for the tool arguments.

type PublishedArtifact 

type PublishedArtifact struct {
	ArtifactID string
	Filename   string
	SizeBytes  int64
	// URL is where an authorized person opens it. Empty when the surface knows
	// the id but not the address to render it at.
	URL string
}

PublishedArtifact is what the artifact service made of it.

type ReadFile 

type ReadFile struct {
	// contains filtered or unexported fields
}

ReadFile reads a local file under a workspace root.

func NewReadFile 

func NewReadFile(workspaceRoot string) *ReadFile

NewReadFile creates a ReadFile tool that reads files under the given workspace root.

func (*ReadFile) Access 

func (r *ReadFile) Access(_ map[string]any) llm.Access

Name returns the tool name for the LLM. Access implements llm.AccessDeclarer.

func (*ReadFile) CheckArgs 

func (r *ReadFile) CheckArgs(args map[string]any) llm.ToolAction

CheckArgs implements llm.ArgChecker. Reading a sensitive file (credentials, private keys) triggers Ask so the user can confirm intent in interactive sessions.

func (*ReadFile) Description 

func (r *ReadFile) Description() string

Description returns a short description so the LLM knows when to use this tool.

func (*ReadFile) Execute 

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

Execute reads the file at args["file_path"] if it is under the tool's root. File contents are returned as UTF-8 text; invalid UTF-8 in the file is passed through as-is.

func (*ReadFile) Name 

func (r *ReadFile) Name() string

func (*ReadFile) Parameters 

func (r *ReadFile) Parameters() any

Parameters returns the OpenAI-style JSON schema for the tool arguments.

type SkillEntry 

type SkillEntry struct {
	Name        string // skill identifier (directory name)
	Description string // short description extracted from SKILL.md
	Path        string // absolute path to the SKILL.md file
	// Origin is the layer this skill was found in. Status surfaces it so a
	// plugin's contribution is visible, and so is anything that shadowed it.
	Origin plugin.Origin
}

SkillEntry holds metadata for one discovered skill.

func DiscoverSkillEntries 

func DiscoverSkillEntries(searchPaths []string) []SkillEntry

DiscoverSkillEntries scans search paths for subdirectories containing SKILL.md. First-path-wins on name conflicts. Returns skills sorted alphabetically by name. This is the unlabelled form, for a caller with no layering to express.

type SkillResolution 

type SkillResolution struct {
	Entries  []SkillEntry
	Shadowed []plugin.Shadowed
	Findings []plugin.Finding
}

SkillResolution is what scanning every source produced: the skills that load, the definitions a higher layer shadowed, and the collisions that stopped a name from loading at all.

func ResolveSkills 

func ResolveSkills(sources []plugin.Source) SkillResolution

ResolveSkills scans priority-ordered sources and reduces them to one skill per name. Sources come from internal/config: workspace, then global, then each plugin in name order.

type SkillTool 

type SkillTool struct {
	// contains filtered or unexported fields
}

SkillTool is an agent tool that discovers and invokes skills from disk. It implements agent.Tool.

func NewSkill 

func NewSkill(searchPaths []string) *SkillTool

NewSkill creates a SkillTool that discovers skills from the given search paths. Each search path is scanned one level deep for subdirectories containing a SKILL.md file. Missing directories are silently skipped. If multiple search paths contain a skill with the same name, the first one found wins (search paths are priority-ordered).

func NewSkillFromEntries 

func NewSkillFromEntries(entries []SkillEntry) *SkillTool

NewSkillFromEntries creates a SkillTool from pre-discovered skill entries. The provided entries are copied so callers can treat the returned tool as immutable.

func (*SkillTool) Access 

func (s *SkillTool) Access(_ map[string]any) llm.Access

Name returns the tool name for the LLM. Access implements llm.AccessDeclarer.

func (*SkillTool) Description 

func (s *SkillTool) Description() string

Description returns a static preamble followed by a dynamic listing of discovered skills.

func (*SkillTool) Execute 

func (s *SkillTool) Execute(ctx context.Context, args map[string]any) (string, error)

Execute looks up the requested skill, reads its SKILL.md file, and returns the content. If args is provided, it is prepended as context.

func (*SkillTool) Name 

func (s *SkillTool) Name() string

func (*SkillTool) Parameters 

func (s *SkillTool) Parameters() any

Parameters returns the OpenAI-style JSON schema for the tool arguments.

type SubAgentRunOpts 

type SubAgentRunOpts struct {
	Tools        []llm.Tool
	SystemPrompt string
	Description  string
	MaxIter      int    // 0 = defaultSubAgentMaxIter
	Model        string // "" = use runner default client
}

SubAgentRunOpts configures one sub-agent invocation.

type SubAgentRunner 

type SubAgentRunner interface {
	RunSubAgent(ctx context.Context, opts SubAgentRunOpts, prompt string) (reply string, err error)
}

SubAgentRunner runs a sub-agent with the given options and prompt. It is implemented by agentapp and injected when building the Task tool so that tools do not depend on a concrete runner; tests can inject a mock.

func NewDefaultSubAgentRunner 

func NewDefaultSubAgentRunner(llmClient llm.LLMClient, policy coreagent.ToolPolicy, modelResolver func(string) (llm.LLMClient, error), opts ...SubAgentRunnerOption) (SubAgentRunner, error)

NewDefaultSubAgentRunner returns a SubAgentRunner backed by the given LLM client. policy is inherited from the parent agent run (nil = AllowAll). modelResolver looks up an LLM client by model name for agent types that specify a model; nil means always use client regardless of the model field.

type SubAgentRunnerOption 

type SubAgentRunnerOption func(*defaultSubAgentRunner)

SubAgentRunnerOption configures a SubAgentRunner.

func WithSubAgentHooks 

func WithSubAgentHooks(h coreagent.HookRunner) SubAgentRunnerOption

WithSubAgentHooks attaches a parent hook runner so subagent runs honor the same PreToolUse / PostToolUse / lifecycle hooks as the parent agent. Nil disables hooks.

func WithSubAgentMaxParallelTools 

func WithSubAgentMaxParallelTools(n int) SubAgentRunnerOption

WithSubAgentMaxParallelTools gives sub-agent runs the same tool-scheduling limit as the parent. Without it a sub-agent runs every call sequentially, which loses the setting exactly where it pays best: an exploration agent batches reads and searches for a living.

func WithSubAgentTraceFactory 

func WithSubAgentTraceFactory(factory SubAgentTraceFactory) SubAgentRunnerOption

WithSubAgentTraceFactory attaches durable trace creation at the assembly layer. A nil factory leaves subagent execution unchanged.

type SubAgentTrace 

type SubAgentTrace interface {
	Record(coreagent.Event)
	Close() error
}

SubAgentTrace receives the event stream for one subagent run. It is kept as a small interface so this package stays below infra: agentapp supplies the durable trace implementation without making the tool layer know where or how traces are stored.

type SubAgentTraceFactory 

type SubAgentTraceFactory func(ctx context.Context, sessionID string, opts SubAgentRunOpts) SubAgentTrace

SubAgentTraceFactory opens a trace for a subagent run. sessionID is the session the trace is filed under — the parent's, because the subagent's own session is discarded when it returns. Returning nil disables only this trace; the subagent must still run.

type TaskTool 

type TaskTool struct {
	// contains filtered or unexported fields
}

TaskTool is an agent tool that spawns sub-agents to handle complex subtasks. It implements llm.Tool.

func NewTask 

func NewTask(runner SubAgentRunner, agentTypes map[string]AgentTypeConfig) (*TaskTool, error)

NewTask creates a TaskTool with the given sub-agent runner and agent type configurations. runner must not be nil; agentTypes must have at least one entry.

func (*TaskTool) Access 

func (t *TaskTool) Access(args map[string]any) llm.Access

Access implements llm.AccessDeclarer. A sub-agent writes whatever its tools write, so the answer is the requested type's tool set rather than the Task tool itself: a type restricted to read-only tools runs a nested loop that cannot write, and may overlap its neighbours.

Everything else is a write — an unknown type, a background run (which mutates the job manager and outlives the call), and a nil-args capability listing, which is asking about the tool and not about a call.

func (*TaskTool) Description 

func (t *TaskTool) Description() string

Description returns a dynamically built description listing all available agent types.

func (*TaskTool) Execute 

func (t *TaskTool) Execute(ctx context.Context, args map[string]any) (string, error)

Execute spawns a sub-agent of the requested type, runs the prompt, and returns the reply.

func (*TaskTool) Name 

func (t *TaskTool) Name() string

func (*TaskTool) Parameters 

func (t *TaskTool) Parameters() any

Parameters returns the OpenAI-style JSON schema with a dynamic enum for subagent_type.

func (*TaskTool) WithJobs 

func (t *TaskTool) WithJobs(m *job.Manager, workspace string) *TaskTool

WithJobs returns a copy of t that can detach subagents to the given job manager. Nil leaves background execution unavailable.

type TodoWrite 

type TodoWrite struct{}

TodoWrite records the task list the LLM uses to trace progress.

The list is durable session state, not a message: it survives history compaction and is re-rendered on every model call. It is stored through the context, because the tool registry is cached per model and shared across sessions. A run with no store — a subagent, for instance — still gets a formatted list back, and is told the list was not kept.

func NewTodoWrite 

func NewTodoWrite() *TodoWrite

NewTodoWrite creates a TodoWrite tool.

func (*TodoWrite) Access 

func (t *TodoWrite) Access(_ map[string]any) llm.Access

Name returns the tool name for the LLM. Access implements llm.AccessDeclarer. Session task list has no lock, so this is a write and cannot run concurrently with a sibling call.

func (*TodoWrite) DefaultAction 

func (t *TodoWrite) DefaultAction() llm.ToolAction

DefaultAction implements llm.PolicyProvider, overriding the action the permission layer would otherwise derive from Access.

What this writes is the agent's own scratch state, not anything the user owns. Asking a user to approve the agent taking a note would be noise, and the noise would arrive on every run. The write classification above is still the honest one — it is what keeps this tool out of a parallel batch. See docs/design/tool-permissions.md §5.2.

func (*TodoWrite) Description 

func (t *TodoWrite) Description() string

Description returns a short description so the LLM knows when to use this tool.

func (*TodoWrite) Execute 

func (t *TodoWrite) Execute(ctx context.Context, args map[string]any) (string, error)

Execute parses and validates todos from args, stores them on the session when the run keeps durable state, and returns a formatted list for the LLM.

func (*TodoWrite) Name 

func (t *TodoWrite) Name() string

func (*TodoWrite) Parameters 

func (t *TodoWrite) Parameters() any

Parameters returns the OpenAI-style JSON schema for the tool arguments.

type UploadArtifact 

type UploadArtifact struct {
	// contains filtered or unexported fields
}

UploadArtifact publishes one file the agent names as a durable artifact.

func NewUploadArtifact 

func NewUploadArtifact(root string, publisher ArtifactPublisher) *UploadArtifact

NewUploadArtifact creates the tool. It is only ever constructed where a publisher exists; see agentapp's tool assembly.

func (*UploadArtifact) Description 

func (t *UploadArtifact) Description() string

Description states the choosing rule, not just the mechanics.

Without it the tool is used as a save button and the team's artifact list fills with intermediate files. What the model has to understand is that this publishes, once, the file a person is meant to receive.

func (*UploadArtifact) Execute 

func (t *UploadArtifact) Execute(ctx context.Context, args map[string]any) (string, error)

Execute validates the file, publishes it, and reports the reference.

func (*UploadArtifact) Name 

func (t *UploadArtifact) Name() string

func (*UploadArtifact) Parameters 

func (t *UploadArtifact) Parameters() any

type WebFetch 

type WebFetch struct {
	// contains filtered or unexported fields
}

WebFetch is a tool that fetches a URL, converts HTML to markdown, optionally processes content with the LLM using a prompt, and returns the result. It implements the llm.Tool interface.

func NewWebFetch 

func NewWebFetch(llmClient llm.LLMClient, cacheTTL time.Duration) *WebFetch

NewWebFetch creates a WebFetch tool with the given LLM client and cache TTL. llmClient may be nil: fetching without a "prompt" argument still works; if "prompt" is set, Execute returns an error until a non-nil client is provided.

func (*WebFetch) Access 

func (w *WebFetch) Access(_ map[string]any) llm.Access

Name returns the tool name for the LLM. Access implements llm.AccessDeclarer. The only thing it writes is its own response cache, which cacheMu guards.

func (*WebFetch) Description 

func (w *WebFetch) Description() string

Description returns a short description so the LLM knows when to use this tool.

func (*WebFetch) Execute 

func (w *WebFetch) Execute(ctx context.Context, args map[string]any) (string, error)

Execute fetches the URL, converts HTML to markdown, optionally calls the LLM with content+prompt, and returns the result.

func (*WebFetch) Name 

func (w *WebFetch) Name() string

func (*WebFetch) Parameters 

func (w *WebFetch) Parameters() any

Parameters returns the OpenAI-style JSON schema for the tool arguments.

func (*WebFetch) WithSandbox 

func (w *WebFetch) WithSandbox(v agent.SandboxView) *WebFetch

WithSandbox installs v as the host filter on w and returns w. Mutates in place because WebFetch holds shared cache state behind a mutex — copying would split the cache. Pass agent.NoopSandbox{} (or nil) to disable enforcement.

type WriteFile 

type WriteFile struct {
	// contains filtered or unexported fields
}

WriteFile writes content to a local file under a workspace root.

func NewWriteFile 

func NewWriteFile(workspaceRoot string) *WriteFile

NewWriteFile creates a WriteFile tool that writes files under the given workspace root.

func (*WriteFile) Access 

func (w *WriteFile) Access(_ map[string]any) llm.Access

Name returns the tool name for the LLM. Access implements llm.AccessDeclarer.

func (*WriteFile) CheckArgs 

func (w *WriteFile) CheckArgs(args map[string]any) llm.ToolAction

CheckArgs implements llm.ArgChecker. Writing to a sensitive file (credentials, private keys) triggers Ask so the user can confirm intent in interactive sessions.

func (*WriteFile) Description 

func (w *WriteFile) Description() string

Description returns a short description so the LLM knows when to use this tool.

func (*WriteFile) Execute 

func (w *WriteFile) Execute(ctx context.Context, args map[string]any) (string, error)

Execute writes args["content"] to the file at args["file_path"] if the path is under the tool's root. Creates parent directories if needed; overwrites if the file exists. Returns a short success message or error.

func (*WriteFile) Name 

func (w *WriteFile) Name() string

func (*WriteFile) Parameters 

func (w *WriteFile) Parameters() any

Parameters returns the OpenAI-style JSON schema for the tool arguments.

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.