Tools & Builtins

Tools are capabilities that an LLM agent can invoke during execution. Forge provides a pluggable tool system with built-in tools, adapter tools, development tools, and custom tools.

Tool Categories

Built-in Tools

Register all builtins with builtins.RegisterAll(registry).

File & Search Tools

Every Forge agent gets a file read/write/edit/patch surface plus search, registered by default and confined to the agent's working directory (WorkDir) via a PathValidator. All resolved paths are confined within the working directory, preventing directory-traversal attacks.

file_read / file_write / file_edit / file_patch are registered for general agents by the runtime (#268); previously they were reachable only when a skill wired them up. They give a general agent a real file-editing surface — not just file_create + search.

General file tools vs. the code-agent skill

There are two distinct file surfaces, and they do not collide:

When the code-agent skill is active, the general file_* builtins are skipped — the skill's project-scoped code_agent_* tools are the specialized file surface (skill tools win), so the LLM never sees two overlapping file surfaces. Search tools (grep_search / glob_search / directory_tree) are registered in both cases, scoped to workspace/ under the code-agent skill and to WorkDir otherwise.

Registration Groups

These tools are constructed and registered in layered groups (forge-core/tools/builtins/register.go), so the runtime and skills can request only the capabilities they need:

Path Validation

All file tools use PathValidator (from pathutil.go):

• All resolved paths must stay within the configured workDir
• Directory traversal via .. is caught after symlink resolution
• Standard directories are excluded from search: .git, node_modules, vendor, __pycache__, .venv, dist, build

Adapter Tools

Adapter tools bridge external services into the agent's tool set.

Per-operation API tools (apis.servers)

Instead of one generic openapi_call tool, Forge registers one typed tool per admitted OpenAPI operation (issue #400 — the generic openapi_call stub was removed). Configure them under the top-level apis: block: each operations[] entry of a server registers as a namespaced <name>__<op> tool (e.g. server memberservice op reverse_fee → tool memberservice__reverse_fee) with the operation's own typed input schema, so the LLM (and the PDP) see a distinct, argument-typed tool per endpoint rather than a free-form HTTP call.

apis:
  servers:
    - name: memberservice
      base_url: https://member-service.internal   # host must be on the egress allowlist
      auth:
        token_env: MEMBERSERVICE_TOKEN             # bearer/static only (oauth rejected for apis)
      operations:
        - name: reverse_fee
          method: POST
          path: /accounts/{account_id}/reversals   # {…} segments filled from typed args
          description: Reverse a fee on an account

apis.servers[] entries are typically platform-materialized from admitted OpenAPI specs. Because each operation is its own <name>__<op> tool, the managed PDP keys authorization rules per operation. See the apis: schema.

MCP tools are not listed in this table. Configure MCP servers under the top-level mcp: block in forge.yaml; each server's discovered tools are registered as namespaced <server>__<tool> entries automatically. See docs/mcp/ for the configuration reference. The previous mcp_call adapter tool was removed in v0.12.0 — the new block is strictly more capable.

Web Search Providers

The web_search tool supports two providers:

Provider selection: WEB_SEARCH_PROVIDER env var, or auto-detect from available API keys (Tavily first).

CLI Execute

The cli_execute tool provides security-hardened command execution with 13 security layers:

tools:
  - name: cli_execute
    config:
      allowed_binaries: ["git", "curl", "jq", "python3"]
      env_passthrough: ["GITHUB_TOKEN"]
      timeout: 120
      max_output_bytes: 1048576

KUBECONFIG and NO_PROXY Scoping

When HOME is overridden to workDir, kubectl and helm lose access to ~/.kube/config. For these two binaries only, cli_execute auto-sets:

If KUBECONFIG is explicitly set in the environment (e.g., via docker run -e KUBECONFIG=... or after KUBECONFIG materialization), that value is passed through directly. Otherwise, cli_execute falls back to the real ~/.kube/config. NO_PROXY is extracted from the kubeconfig's clusters[].cluster.server field. Other binaries do not receive these variables.

File Create

The file_create tool generates downloadable files that are both written to disk and uploaded to the user's channel (Slack/Telegram).

Output JSON includes filename, content, mime_type, and path. The path field contains the absolute disk location, allowing other tools (e.g., kubectl apply -f <path>) to reference the file.

File location: Files are written to the agent's .forge/files/ directory (under WorkDir). The runtime injects this path via FilesDir in the executor context. When running outside the full runtime (e.g., tests), falls back to $TMPDIR/forge-files/.

Allowed extensions:

Filenames with path separators (/, \) or traversal patterns (..) are rejected.

Memory Tools

When long-term memory is enabled, two additional tools are registered:

• memory_search — Hybrid vector + keyword search across stored memory files
• memory_get — Read specific memory files by path

These tools allow the agent to recall information from previous sessions.

Context Expansion Tool

When context compression is enabled, the context_expand tool is registered. Compressed tool outputs carry inline <<ctxzip:HASH note>> markers; the model calls context_expand with the hash to retrieve the offloaded original from the local store. The tool tolerates imperfect input — a whole marker pasted as the hash, or a truncated hash that uniquely prefixes a recently emitted one — and a miss (expired/evicted entry) returns guidance to re-run the producing tool rather than an error.

Development Tools

Development tools (local_shell, local_file_browser, debug_console, test_runner) are available during forge run --dev but are automatically filtered out in production builds by the ToolFilterStage.

Tool Interface

All tools implement the tools.Tool interface:

type Tool interface {
    Name() string
    Description() string
    Category() Category
    InputSchema() json.RawMessage
    Execute(ctx context.Context, args json.RawMessage) (string, error)
}

Writing a Custom Tool

Custom tools are discovered from the project directory. Create a Python or TypeScript file with a docstring schema:

"""
Tool: my_custom_tool
Description: Does something useful.

Input:
  query (str): The search query.
  limit (int): Maximum results.

Output:
  results (list): The search results.
"""

import json
import sys

def execute(args: dict) -> str:
    query = args.get("query", "")
    return json.dumps({"results": [f"Result for: {query}"]})

if __name__ == "__main__":
    input_data = json.loads(sys.stdin.read())
    print(execute(input_data))

Custom tools can also be added by placing scripts in a tools/ directory in your project. TypeScript tools run via npx --no-install ts-node to prevent automatic package downloads.

Custom Tool Entrypoint Validation

Custom tool entrypoints are validated at registration time:

• Empty or absolute paths are rejected
• Paths containing .. after filepath.Clean are rejected
• Symlinks are resolved and the target must remain within the project directory
• The entrypoint must be a regular file (not a directory or device)

Tool Commands

# List all registered tools
forge tool list

# Show details for a specific tool
forge tool describe web_search

Build Pipeline

The ToolFilterStage runs during forge build:

1. Annotates each tool with its category (builtin, adapter, dev, custom)
2. Sets tool_interface_version to "1.0" on the AgentSpec
3. In production mode (--prod), removes all dev-category tools
4. Counts tools per category for the build manifest