Built-in Tools

Overview

Aleph ships a comprehensive set of built-in tools covering file operations, code execution, web interaction, memory, browser automation, sub-agent delegation, scheduling, and more. All built-in tools implement the AlephTool trait with static dispatch for maximum performance, and are assembled by the executor's builtin registry (src/executor/builtin_registry/) at startup.

Every tool call funnels through the same chokepoint — ScopedToolService (src/tools/scoped/). Exec tier, the command-policy floor, and per-channel permission merging all happen there. Whether a tool "requires confirmation" is decided by its ToolDefinitionMetadata, not its name.

---

Code execution

Both dispatch subprocesses through Arc<dyn Sandbox>. Naked Command::new is not allowed in src/builtin_tools/. They take code / command with optional working_dir and timeout; output is bounded by the sandbox wall-clock (default 60 s) and a 1 MiB output budget.

---

File operations

file_ops is a multiplexer — its destructive sub-operations (delete / move) are argument-recognized under the exec tier (ExecTier::asks_for_arguments). Do not rely on the bare name file_ops as an approval switch; configure explicit entries.

---

Web and search

web_fetch is the single outbound HTTP entry point — webhook delivery, media downloader, MCP HTTP transport, and browser navigation all funnel through the SSRF engine.

---

Memory and retrieval

Three complementary retrieval tools, each searching a different store. Descriptions are tuned to avoid tool-choice confusion:

Rule of thumb: ctx_search = "what did that tool print?"; recall_events = "what did I already do this session?"; session_search = "what happened in past sessions?".

Other memory tools:

---

MCP bridge tools (capability-gated)

These built-in tools appear in the registry only while at least one connected MCP server advertises the matching capability (src/mcp/tool_bridge.rs::reconcile_capability_tools). The model is never offered a tool that every call would reject.

mcp_read_resource and mcp_get_prompt resolve <server>:<rest> ids through resolve_server_qualified with longest-prefix server match — shortest/first match mis-routes a resource on a server literally named gh:sub to a server named gh.

---

Browser tools (per-action)

Browser automation is exposed as a set of focused, single-responsibility tools (not a single browser tool with an action discriminator) — see Browser Automation.

browser_click / browser_navigate / browser_open / browser_snapshot / browser_screenshot / browser_evaluate / browser_fill_form / browser_press_key / browser_hover / browser_scroll / browser_type / browser_select / browser_drag / browser_upload / browser_console / browser_cookies / browser_dialog / browser_emulate / browser_resize / browser_wait_for / browser_pdf / browser_network / browser_tabs / browser_session / browser_profile.

Element targeting prefers ARIA ref_id (from browser_snapshot). CSS selector targeting has been removed; coordinates (x, y) are the fallback.

---

Sub-agent and multi-agent

A delegated sub-agent is its own principal in the signed-ledger model: it holds its own Ed25519 key and signs its own work — it is not a line on its parent's chain. The acting role is injected by AllowlistToolService (the spawner builds this wrapper from the child's AgentDef); the sub-agent runs on its parent's ScopedToolService and inherits the parent's TURN_CONTEXT, but the ledger identity is its own.

---

Sessions and tasks

---

Scheduling

Cron and heartbeat are headless producers — a cron whose approval cannot be routed is stamped unattended (UNATTENDED_KEY); heartbeat and a2a are always stamped unattended. ScopedToolService then immediately denies confirm-gated tools instead of publishing an approval card into the void and blocking for the 120 s timeout.

---

Meta / config / identity

---

Generation

---

Desktop integration

Desktop tools require the Aleph macOS companion to be running. When it is not, calls return a friendly message instead of an error and the agent degrades gracefully. All native API calls go through the AlephBridge stdio helper — the Rust core stays sandbox-friendly.

---

Channels / messages / notes

---

MCP tool naming and registration

Tools discovered from MCP servers are registered as <server>__<tool> (e.g., github__create_issue). McpHandler::qualified_name is the single source of naming truth (src/tools/handlers/mcp.rs): it strips the manager's redundant {server}: prefix, maps any character outside [A-Za-z0-9_-] to _, and truncates to 64 characters. The __ is a namespace separator — the LLM sees it as part of the name.

Schemas whose type is not "object" are quarantined — a schema that every provider would reject would otherwise poison the whole turn with an HTTP 400.

---

Registration summary

Built-in tools are not registered through a builder — they are assembled by src/executor/builtin_registry/ at startup. The registry:

• injects a shared Arc<dyn Sandbox> into every exec-class tool (bash_exec, code_exec);
• injects Arc<ProfileManager> into every browser tool;
• injects Arc<McpManagerHandle> into every MCP-bridge tool;
• injects channel context / ApprovalRequester into the tools that need them.

Every requires_confirmation tool is listed once in CONFIRMATION_REQUIRED_TOOLS (vault_store, agent_delete, team_disband, …) and shares one ApprovalRequester. This is fail-closed by construction — any built-in tool not in READ_ONLY_TOOLS requires approval under the Ask tier.