Native Tools

Relevant source files

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

• core/src/tools/README.md
• core/src/tools/native/filesystem.rs
• core/src/tools/native/shell.rs
• core/src/tools/native/web_search.rs
• core/src/tools/native/git.rs
• core/tests/filesystem_tool_test.rs
• loom-py/tests/e2e/test_native_tools.py
• core/src/cognitive/llm/tool_orchestrator.rs

Native Tools are built-in capabilities provided by the Loom Core runtime. They represent the "Hands" in Loom's "Brain/Hand" architecture, offering secure, sandboxed access to system resources like the filesystem, shell commands, and web search. These tools are implemented in Rust for stability and security and are exposed to agents through a unified interface.

All native tools are managed by the ToolRegistry, which handles registration and lookup. They are invoked by agents, typically through the ToolOrchestrator, which processes LLM-generated action requests. This system ensures that potentially destructive or sensitive operations are executed within a controlled environment.

Sources: ARCHITECTURE.md, core/src/tools/README.md, core/src/cognitive/llm/tool_orchestrator.rs:17-21

The Tool Trait

All native tools must implement the Tool trait, which defines a standard interface for execution, metadata, and parameter validation. This ensures that any tool, whether native or from an MCP integration, can be managed and called uniformly by the ToolRegistry.

Sources: core/src/tools/README.md:21-28

#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;
    async fn execute(&self, params: serde_json::Value) -> ToolResult<serde_json::Value>;
}

Sources: core/src/tools/README.md:24-29

This diagram illustrates the flow of a tool call from a Python agent to a native tool in Rust Core.

Available Native Tools

The following table summarizes the native tools available in Loom Core.

Tool Name	Description	Environment Variables
fs:read_file	Read a file from the agent's workspace.	-
fs:write_file	Write content to a file in the agent's workspace.	-
fs:list_dir	List the contents of a directory in the workspace.	-
fs:delete	Delete a file or directory from the workspace.	-
system:shell	Execute a shell command.	-
git:clone	Clone a git repository.	-
git:checkout	Checkout a specific commit or branch.	-
git:apply_patch	Apply a patch to a repository.	-
git:current_commit	Get the current commit hash of a repository.	-
weather:get	Get weather data for a location.	-
web:search	Search the web.	BRAVE_API_KEY, HTTPS_PROXY

Sources: core/src/tools/README.md:33-44

Tool Categories

Filesystem Tools

These tools provide sandboxed access to the filesystem, restricted to the agent's designated workspace root to prevent unauthorized access to other parts of the system.

Security:

• Workspace Isolation: All file operations are confined to the workspace root directory.
• Path Traversal Prevention: The tools explicitly block paths containing .. to prevent directory traversal attacks. Any attempt to access a path outside the workspace will result in an error.

This security feature is validated by unit tests.

Sources: core/src/tools/README.md:100-101, core/tests/filesystem_tool_test.rs:136-147

The following flowchart shows the security check for path traversal.

fs:read_file

Reads the content of a file.

• Parameters: {"path": "string"}
• Returns: {"content": "string"}

fs:write_file

Writes content to a file. It will create parent directories if they do not exist.

• Parameters: {"path": "string", "content": "string"}
• Returns: {"success": true, "bytes_written": number}

fs:list_dir

Lists files and subdirectories in a given path. If no path is provided, it lists the workspace root.

• Parameters: {"path": "string"} (optional)
• Returns: {"entries": [{"name": "string", "is_dir": boolean, "is_file": boolean}]}

fs:delete

Deletes a file or an empty directory.

• Parameters: {"path": "string"}
• Returns: {"success": true, "was_directory": boolean}

Sources: core/src/tools/native/filesystem.rs, core/tests/filesystem_tool_test.rs

Shell Tool

system:shell

Executes a shell command. For security, it's designed to be used with an allowlist of pre-approved commands for automatic execution by an agent. Destructive or un-sandboxed operations should require human-in-the-loop approval.

• Parameters: {"command": "string", "args": ["string"]}
• Returns: {"stdout": "string", "stderr": "string", "exit_code": number}

Example invocation from a Python agent:

result = await agent._ctx.tool(
    "system:shell",
    payload={"command": "echo", "args": ["Hello", "from", "Loom"]},
    timeout_ms=5000,
)

Sources: loom-py/tests/e2e/test_native_tools.py:100-107, core/src/tools/native/shell.rs, core/src/tools/README.md:102-103

Web Search Tool

web:search

Performs a web search using the Brave Search API.

• Parameters: {"query": "string"}
• Returns: A JSON object containing search results.
• Configuration: Requires the BRAVE_API_KEY environment variable. It can also use an HTTPS_PROXY.

Example invocation from a Python agent:

result = await agent._ctx.tool(
    "web:search",
    payload={"query": "AI agents"},
    timeout_ms=15000,
)

Sources: loom-py/tests/e2e/test_native_tools.py:68-75, core/src/tools/native/web_search.rs, core/src/tools/README.md:44

Git Tools

Provides capabilities for interacting with Git repositories.

git:clone

Clones a Git repository into the workspace.

• Parameters: {"repo_url": "string", "path": "string"}
• Returns: {"success": true, "path": "string"}

git:checkout

Checks out a branch or commit in a cloned repository.

• Parameters: {"path": "string", "reference": "string"}
• Returns: {"success": true}

git:apply_patch

Applies a patch file to a repository.

• Parameters: {"path": "string", "patch_content": "string"}
• Returns: {"success": true}

git:current_commit

Retrieves the current commit hash of a repository.

• Parameters: {"path": "string"}
• Returns: {"commit_hash": "string"}

Sources: core/src/tools/native/git.rs, core/src/tools/README.md:39-42

Adding a New Native Tool

To add a new native tool, a developer must:

1. Create a new file in core/src/tools/native/.
2. Implement the Tool trait for a new struct.
3. Define the tool's name, description, and parameter schema.
4. Implement the execute async function containing the tool's logic.
5. Register the new tool in the ToolRegistry during initialization.

Sources: core/src/tools/README.md:83-98

Summary

Native Tools are a cornerstone of the Loom runtime, providing essential, secure, and sandboxed functionalities that bridge the gap between an agent's cognitive processes (the "Brain") and the real-world environment (the "Hands"). By implementing a standardized Tool trait and enforcing strict security measures like workspace isolation, Loom ensures that agents can perform powerful actions without compromising system integrity. The diverse set of tools, from filesystem manipulation to web searching, equips agents with the foundational capabilities needed for a wide range of autonomous tasks.