AI Agent Tools

Relevant source files

The following files were used as context for generating this wiki page:

• internal/agent/executor.go
• internal/agent/agent.go
• internal/agent/README.md
• internal/agent/types.go
• internal/agent/phases.go
• internal/agent/prompts/system.md
• internal/agent/tui.go
• internal/agent/ui_headless.go

The AI Agent Tools are a set of functions that the AI model (Claude) can invoke to interact with the user's local environment. These tools are the agent's "hands and eyes," allowing it to read files, run commands, make HTTP requests, and ask the user for information. They are fundamental to the agent's ability to guide a user through setting up Tusk Drift for their service.

The agent is designed to be thorough but efficient, using tools to verify information rather than making assumptions. It operates within a structured, phase-based workflow, where each phase has a specific set of available tools to accomplish its goal. The agent must use the transition_phase tool to progress through the setup.

Sources: internal/agent/README.md, internal/agent/prompts/system.md

Architecture and Registration

The tool system is built around a central registry that maps tool names to their definitions and executor functions. This architecture provides a single source of truth for tool metadata and implementation.

Sources: internal/agent/executor.go

Core Components

Component	File	Description
ToolName	executor.go	A type-safe string constant for identifying tools (e.g., ToolReadFile).
ToolDefinition	executor.go	A struct containing a tool's name, description, input schema, and executor function.
ToolExecutor	types.go	A function type func(input json.RawMessage) (string, error) that implements the tool's logic.
ToolRegistry	executor.go	A global registry holding all ToolDefinitions, populated at runtime.
RegisterTools()	executor.go	The function that initializes all tool definitions, maps them to their executor functions, and populates the global registry.

Sources: internal/agent/executor.go:11-59, 70-76, internal/agent/types.go:21-22

Tool Registration Flow

The following diagram illustrates how tools are registered when the agent starts.

This diagram shows the RegisterTools function combining static definitions with their corresponding executor implementations to create a complete, runnable set of tools for the agent.

Sources: internal/agent/executor.go:616-679

Tool Execution Flow

When the AI model decides to use a tool, it returns a tool_use block. The agent then orchestrates the execution and returns the result to the model.

This sequence shows the agent mediating between the AI model and the tool executors, handling permissions, and feeding results back into the conversation.

Sources: internal/agent/agent.go:520-698, internal/agent/tui.go:1017-1029

Tool Categories

Tools are grouped by functionality, primarily corresponding to files in the internal/agent/tools/ directory.

Filesystem Tools

These tools allow the agent to read, write, and search files in the user's project directory.

Tool Name	Description	Key Parameters
read_file	Reads the contents of a file.	path
write_file	Writes content to a file, creating it if necessary.	path, content
list_directory	Lists files and directories in a given path.	path
grep	Searches for a regex pattern in files.	pattern, path, include
patch_file	Applies a targeted search-and-replace edit to a file.	path, search, replace

Sources: internal/agent/executor.go:108-193

Process Management Tools

These tools are used to run shell commands and manage long-running background processes, such as starting the user's web service. Commands are sandboxed for security.

Tool Name	Description	Key Parameters
run_command	Runs a one-shot shell command and waits for it to complete.	command, timeout_seconds
start_background_process	Starts a long-running process (e.g., a server) in the background.	command, env
stop_background_process	Stops a background process started with start_background_process.	handle
get_process_logs	Retrieves recent stdout/stderr from a background process.	handle, lines
wait_for_ready	Polls an HTTP endpoint to wait for a service to become ready.	url, timeout_seconds

Sources: internal/agent/executor.go:194-279, internal/agent/README.md:129-130

HTTP Tools

This category contains a single tool for making arbitrary HTTP requests, which is essential for testing service endpoints during setup.

Tool Name	Description	Key Parameters
http_request	Makes an HTTP request and returns the response.	method, url, headers, body

Sources: internal/agent/executor.go:280-307

User Interaction Tools

When the agent cannot find information or needs clarification, it uses these tools to communicate directly with the user. The AgentUI interface abstracts the interaction for both TUI and headless modes.

Tool Name	Description	Key Parameters
ask_user	Asks the user a free-text question and waits for a response.	question
ask_user_select	Presents the user with a list of options to choose from.	question, options

Sources: internal/agent/executor.go:308-360, internal/agent/agent.go:701-768, internal/agent/ui_tui.go, internal/agent/ui_headless.go

Tusk CLI Tools

These tools wrap the tusk CLI itself, allowing the agent to verify that trace recording and replay are functioning correctly.

Tool Name	Description	Key Parameters
tusk_list	Runs tusk list to show available recorded traces.	(none)
tusk_run	Runs tusk run to replay traces and report results.	filter, debug

Sources: internal/agent/executor.go:361-389

Cloud Setup Tools

This extensive set of tools is dedicated to the Tusk Drift Cloud setup, handling authentication, repository management, and configuration.

Tool Name	Description
cloud_check_auth	Checks if the user is authenticated with Tusk Cloud.
cloud_login	Initiates the device code login flow.
cloud_wait_for_login	Waits for the device code authentication to complete.
cloud_get_clients	Gets the list of organizations the user belongs to.
cloud_select_client	Selects the organization to use for cloud operations.
cloud_detect_git_repo	Detects Git repository info from the current directory.
cloud_verify_repo_access	Verifies Tusk has access to the user's repository.
cloud_get_auth_url	Gets the URL for GitHub/GitLab app installation.
cloud_open_browser	Opens a URL in the user's default browser.
cloud_create_service	Creates an observable service in Tusk Cloud.
cloud_create_api_key	Creates a new API key for CI/CD.
cloud_check_api_key_exists	Checks for an existing TUSK_API_KEY environment variable.
cloud_save_config	Saves cloud configuration to .tusk/config.yaml.

Sources: internal/agent/executor.go:431-614

Control Flow Tools

These meta-tools manage the agent's state and progression through the setup phases.

Tool Name	Description	Key Parameters
transition_phase	Completes the current phase and moves to the next one.	results, notes
abort_setup	Aborts the setup process gracefully if the project is unsupported.	reason, project_type

Sources: internal/agent/executor.go:390-430

Permissions and Confirmation

To prevent unintended changes, tools that perform consequential actions (like writing files or running commands) require user confirmation by default.

• The ToolDefinition struct has a RequiresConfirmation boolean flag.
• When the agent attempts to use such a tool, the AgentUI prompts the user for permission.
• The user can choose to:
  • Approve (y): Execute the action once.
  • Approve All (a): Execute this and all future actions without prompts.
  • Deny (n): Deny the action and suggest an alternative.
  • Cancel (Ctrl+C): Stop the agent.

This flow is managed within the executeToolCalls function in agent.go.

Sources: internal/agent/executor.go:127, 182, 220, internal/agent/agent.go:595-638, internal/agent/tui.go:1017-1029

Adding a New Tool

Adding a new tool follows a structured process outlined in the agent's documentation and implemented in executor.go and phases.go.

1. Implement the Executor: Create the tool's logic as a ToolExecutor function in a relevant tools/ file (e.g., tools/mytool.go).
2. Define the Tool:
   a. Add a ToolName constant in executor.go.
   b. Add a ToolDefinition to the toolDefinitions() map in executor.go, specifying its name, description, and JSON input schema.
3. Register the Executor: In RegisterTools() within executor.go, map the new ToolName to its executor function in the executorMap.
4. Enable in Phases: In phases.go, add the new ToolName to the Tools list of any phase that should have access to it.

Sources: internal/agent/README.md:83-127, internal/agent/executor.go:11-60, 99-614, 626-659, internal/agent/phases.go:323-334