Tool System Architecture

Overview

The Tool System is the core execution layer of the AI Dev Agent.

While the language model is responsible for reasoning and planning, the Tool System is responsible for interacting with the external environment.

This includes operations such as:

• reading and writing files
• executing shell commands
• interacting with Git
• analyzing code
• running tests
• retrieving knowledge

The Tool System provides a deterministic and controlled interface between the LLM and the development environment.

---

Design Goals

The Tool System is designed with the following goals.

Deterministic Execution

Tools must behave deterministically and produce structured outputs.

This ensures that the LLM can reliably reason about tool results.

Security and Isolation

Tools interact with the local system.

Execution must therefore support:

• permission control
• sandboxing
• restricted capabilities

Composability

Tools must be composable.

Complex operations should be constructed from multiple tool calls rather than single monolithic tools.

Explicit Interfaces

Every tool must expose:

• clear input schema
• clear output schema
• predictable side effects

This improves reliability for both humans and AI agents.

---

Architecture Overview

The Tool System consists of five main components.

LLM
│
▼
Tool Invocation
│
▼
Tool Registry
│
▼
Permission System
│
▼
Tool Executor
│
▼
Environment

Each component has a clearly defined responsibility.

---

Tool Interface

Every tool implements a common interface.

Example TypeScript interface:

export interface Tool<Input, Output> {
  name: string
  description: string

  schema: {
    input: JSONSchema
    output: JSONSchema
  }

  execute(input: Input, context: ToolContext): Promise<Output>
}

Key properties include:

name

Unique identifier of the tool.

description

Human-readable description used by the LLM.

schema

Defines the structured input and output types.

execute

The function executed when the tool is invoked.

---

Tool Context

Tools receive contextual information about the current execution environment.

Example:

export interface ToolContext {
  workspaceRoot: string
  workingDirectory: string
  permissions: PermissionSet
  memory: MemoryClient
  logger: Logger
}

This enables tools to:

• access the repository
• retrieve memory
• log execution
• respect permission boundaries

---

Tool Registry

The Tool Registry is responsible for managing available tools.

Responsibilities include:

• tool registration
• tool discovery
• schema retrieval
• version control

Example implementation:

class ToolRegistry {
  private tools = new Map<string, Tool<any, any>>()

  register(tool: Tool<any, any>) {
    this.tools.set(tool.name, tool)
  }

  get(name: string) {
    return this.tools.get(name)
  }

  list() {
    return Array.from(this.tools.values())
  }
}

The registry acts as the central index for tool availability.

---

Tool Invocation Flow

The typical tool execution flow is as follows.

1. LLM generates tool call
2. Tool call validated against schema
3. Tool retrieved from registry
4. Permission check performed
5. Tool executed
6. Structured output returned to LLM

This pipeline ensures safety and reliability.

---

Permission System

Not all tools should be accessible at all times.

The Permission System controls tool access.

Example permission model:

type PermissionSet = {
  filesystemRead: boolean
  filesystemWrite: boolean
  shellExecution: boolean
  gitWrite: boolean
}

Different agent modes may use different permission levels.

Example:

Mode	Permissions
ReadOnly	read files only
Dev	read/write files
CI	run tests
Full	all permissions

This prevents accidental destructive actions.

---

Tool Executor

The Tool Executor is responsible for safely executing tools.

Responsibilities include:

• validating input
• invoking tool execution
• handling errors
• capturing output
• enforcing timeouts

Example:

async function executeTool(
  tool: Tool<any, any>,
  input: unknown,
  context: ToolContext
) {
  validate(tool.schema.input, input)

  const result = await tool.execute(input, context)

  validate(tool.schema.output, result)

  return result
}

This ensures schema compliance for both inputs and outputs.

---

Tool Categories

Tools are grouped into several categories.

Filesystem Tools

Interact with project files.

Examples:

• read_file
• write_file
• list_directory
• search_files

These tools enable the agent to inspect and modify the codebase.

---

Git Tools

Interact with version control.

Examples:

• git_status
• git_diff
• git_commit
• git_branch

These tools allow the agent to manage repository changes.

---

Shell Tools

Execute system commands.

Examples:

• run_command
• run_test_suite
• install_dependencies

Shell tools are powerful and should require explicit permissions.

---

Code Analysis Tools

Analyze code structure and dependencies.

Examples:

• parse_typescript_ast
• find_symbol_definition
• find_references
• dependency_graph

These tools help the agent reason about large codebases.

---

Knowledge Tools

Retrieve internal memory or documentation.

Examples:

• search_memory
• retrieve_spec
• retrieve_design_doc

These tools connect the Tool System with the Memory Architecture.

---

Error Handling

Tool execution must produce structured errors.

Example:

type ToolError = {
  type: "validation" | "runtime" | "permission"
  message: string
}

Structured errors allow the LLM to recover from failures.

Example recovery strategies include:

• retry with different input
• select alternative tool
• request clarification

---

Observability

All tool executions should be logged.

Example metadata:

• tool name
• input parameters
• execution time
• output size
• errors

Logs enable:

• debugging
• auditing
• performance optimization

---

Sandboxing

Some tools may execute untrusted code or shell commands.

These tools should support sandboxed execution environments.

Possible approaches include:

• containerized execution
• restricted shell environments
• temporary working directories

Sandboxing reduces the risk of system damage.

---

Future Extensions

The Tool System is designed to be extensible.

Possible future extensions include:

• remote tool execution
• distributed build tools
• cloud resource management
• deployment tools

Because tools use a unified interface, new capabilities can be added without modifying the core agent logic.

---

Summary

The Tool System is the execution backbone of the AI Dev Agent.

It provides a structured interface between the LLM and the development environment.

Core components include:

• Tool Interface
• Tool Registry
• Permission System
• Tool Executor
• Sandboxed Environment

This architecture enables the AI agent to safely and deterministically perform software engineering tasks.