Tool
Source: core/tool/tool.gleam, core/tool/executor.gleam
The tool subsystem defines the shared types for tool registration and the execution engine that validates, groups, and dispatches tool calls.
Modules
tool.gleam
Shared type definitions used by both the registry and individual tool modules.
Tool record:
| Field | Type | Description |
|---|---|---|
name | String | Unique tool identifier |
description | String | Human-readable description for the LLM |
schema | json.Json | JSON Schema for parameters |
handler | fn(String) -> ToolResult | The actual tool function |
parallel_safe | Bool | Whether this tool can run concurrently with others |
ToolResult type:
| Variant | Description |
|---|---|
Completed(output) | Tool ran successfully |
ToolError(message) | Tool encountered an error |
NeedsApproval(request) | Tool requires user approval before execution |
ApprovalRequest carries id, reason, command, and tool_name.
ApprovalResponse has five variants: ApproveOnce, ApproveSession, ApproveAlways, Deny, Defer.
ApprovalHandler is a function type: fn(ApprovalRequest) -> ApprovalResponse. Gateways provide their own implementations (CLI blocks on stdin; Telegram uses async callbacks).
Helper functions: from_result() converts Result(String, String) to ToolResult; needs_approval() builds an approval request with a generated ID.
executor.gleam
Blessed Violator #6. The tool execution engine. Imports services/guardrails/approval_cache and services/logger/logger for cross-cutting concerns.
Validation: validate_tool_calls() checks each tool call against the available tool list, returning #(ToolCall, Result(Nil, String)) pairs.
Execution: execute_tools() resolves calls to tool definitions, groups consecutive calls by parallel_safe, and executes each group:
- Sequential groups -- calls run one at a time. If any call defers for approval, the entire execution stops.
- Parallel groups -- calls run in spawned OTP processes with a 30-second timeout. Results are collected and processed through approval handling in the parent process.
Approval flow: When a tool returns NeedsApproval, the ApprovalHandler is invoked. Deny returns an error. Defer stops execution. ApproveOnce/ApproveSession/ApproveAlways re-execute the tool and cache the approval scope.
Truncation: Results over 4000 characters are truncated with head and tail preserved, showing the number of omitted characters.
Related Pages
- Registry -- Tool discovery and dispatch
- Loop -- The orchestrator that calls the executor
- Blessed Violators -- Why executor.gleam can import services