Tool Execution Architecture

Relevant source files

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

• src/core/toolManager.ts
• src/core/actionExecutor.ts
• src/core/toolsRegistry.ts
• src/core/toolFilter.ts
• src/core/agent.ts

The Tool Execution Architecture is the core system responsible for managing, filtering, and executing autonomous actions within the Autohand environment. It follows the ReAct (Reason + Act) pattern, allowing the agent to interact with the file system, version control, and external resources through a structured interface. This architecture ensures that the agent's actions are governed by security policies, user approvals, and context-aware relevance filtering.

At its high level, the system bridges the gap between the Large Language Model (LLM) reasoning and practical execution. It translates LLM-generated tool calls into concrete operations while maintaining safety through a multi-layered permission and filtering system.

Sources: src/core/agent.ts:1091-1100, src/core/toolManager.ts:16-30

Core Architectural Components

The architecture is divided into several specialized modules that handle different stages of the tool lifecycle.

Component Overview

Component	Responsibility
ToolManager	Central registry and coordinator for tool execution and approval logic.
ActionExecutor	Implementation layer that performs the actual file, git, and shell operations.
ToolFilter	Security and efficiency layer that restricts tools based on client context (CLI, API, etc.).
ToolsRegistry	Persistence layer for managing built-in and dynamic meta-tools.
AutohandAgent	Orchestrator that manages the ReAct loop and directs tool calls to the Manager.

Sources: src/core/toolManager.ts:474-482, src/core/actionExecutor.ts:101-125, src/core/toolFilter.ts:129-145

Component Relationship Diagram

The following diagram illustrates how these components interact during a typical execution cycle.

This diagram shows the delegation flow from the high-level agent down to the low-level system mutations.
Sources: src/core/agent.ts:198-250, src/core/toolManager.ts:634-640

Execution Lifecycle

The execution of a tool follows a strict sequence to ensure security and reliability.

1. Filtering and Selection

Before the LLM receives the tool definitions, the ToolFilter selects relevant tools based on the current ClientContext (e.g., cli, slack, api, or restricted). This prevents the model from attempting actions that are prohibited in its current environment. Furthermore, filterToolsByRelevance uses conversation history to dynamically reduce the toolset, saving token overhead.

Sources: src/core/toolFilter.ts:153-172, src/core/toolFilter.ts:384-398

2. Validation and Approval

When a tool is invoked, the ToolManager checks if the tool requiresApproval. If so, it triggers the confirmApproval callback. This process may also involve onPermissionRequest hooks, allowing automated security policies to decide if a tool should run.

Sources: src/core/toolManager.ts:646-680, src/core/actionExecutor.ts:133-157

3. Execution Phase

The ActionExecutor receives the validated AgentAction. It resolves workspace paths to ensure the agent cannot escape the project root and performs the specific task, such as read_file, git_commit, or run_command.

Sources: src/core/actionExecutor.ts:165-175, src/core/actionExecutor.ts:1145-1151

Execution Sequence Diagram

This sequence represents the internal logic flow for processing a single tool request within the agent's turn.
Sources: src/core/toolManager.ts:634-706, src/core/agent.ts:1091-1120

Tool Categories and Risk Levels

Tools are categorized to facilitate granular permission management.

Category	Description	Example Tools
read	Read-only file and search operations	read_file, search, list_tree
write	Mutating file operations	write_file, search_replace, apply_patch
git_write	Mutating version control operations	git_commit, git_push, git_merge
shell	Arbitrary command execution	run_command, custom_command
meta	Coordination and agent planning	plan, todo_write, save_memory

Sources: src/core/toolFilter.ts:19-27, src/core/toolFilter.ts:39-115

Dynamic Tooling (Meta-Tools)

The architecture supports the creation of "Meta-Tools"—custom tools created by the agent or user that persist across sessions.

• Registration: Meta-tools are stored as JSON files in ~/.autohand-cli/tools/ and loaded by the ToolsRegistry.
• Security: The ActionExecutor performs a comprehensive security scan on meta-tool handlers, blocking dangerous patterns like rm -rf / or reverse shell indicators.
• Templating: Handlers use {{param}} syntax, which the system safely escapes before execution to prevent command injection.

Sources: src/core/actionExecutor.ts:792-835, src/core/toolsRegistry.ts:40-60, src/core/toolManager.ts:517-525

Security and Safety Rails

The architecture includes several baked-in safety mechanisms:

1. Workspace Isolation: The resolveWorkspacePath function is called for every file operation to prevent directory traversal attacks.
2. Secret Scanning: The ActionExecutor utilizes a SecurityScanner to check staged changes for secrets before a git_commit is allowed to proceed.
3. Destructive Command Detection: Commands like rm, sudo, and dd are flagged and require explicit user confirmation regardless of global settings.
4. Shell Metacharacter Escaping: When executing meta-tools, all parameters are sanitized using shell-escaping logic to prevent interpolation exploits.

Sources: src/core/actionExecutor.ts:1145-1151, src/core/actionExecutor.ts:1085-1110, src/core/actionExecutor.ts:919-930

Conclusion

The Tool Execution Architecture provides a robust and secure framework for agent autonomy. By decoupling the definition of tools from their implementation and wrapping them in a strict permission and filtering layer, the system enables powerful coding capabilities while maintaining high standards for project safety and resource efficiency.

Sources: src/core/agent.ts:1091-1100, src/core/toolFilter.ts:129-145