types/tool

Shared tool types — canonical types, constructors, and helpers. Used across core, services, and plugins.

Types

ApprovalCache

In-memory approval cache. Each entry is a (session_id, command, scope) triple.

pub type ApprovalCache =
  List(#(String, String, guardrails.ApprovalScope))

ApprovalHandler

</>

Gateway-agnostic approval handler. Called when a tool needs user approval.

pub type ApprovalHandler =
  fn(ApprovalRequest) -> ApprovalResponse

ApprovalRequest

</>

pub type ApprovalRequest {
  ApprovalRequest(
    id: String,
    reason: String,
    command: String,
    tool_name: String,
  )
}

Constructors

ApprovalRequest(
  id: String,
  reason: String,
  command: String,
  tool_name: String,
)

ApprovalResponse

</>

pub type ApprovalResponse {
  ApproveOnce
  ApproveSession
  ApproveAlways
  Deny
  Defer
}

Constructors

```
ApproveOnce
```
```
ApproveSession
```
```
ApproveAlways
```
```
Deny
```
```
Defer
```

Tool

</>

pub type Tool {
  Tool(
    name: String,
    description: String,
    schema: json.Json,
    handler: fn(
      String,
      List(#(String, String, guardrails.ApprovalScope)),
      String,
    ) -> #(
      ToolResult,
      List(#(String, String, guardrails.ApprovalScope)),
    ),
    parallel_safe: Bool,
  )
}

Constructors

Tool(
  name: String,
  description: String,
  schema: json.Json,
  handler: fn(
    String,
    List(#(String, String, guardrails.ApprovalScope)),
    String,
  ) -> #(
    ToolResult,
    List(#(String, String, guardrails.ApprovalScope)),
  ),
  parallel_safe: Bool,
)

ToolResult

</>

pub type ToolResult {
  Completed(output: String)
  ToolError(message: String)
  NeedsApproval(request: ApprovalRequest)
}

Constructors

```
Completed(output: String)
```
```
ToolError(message: String)
```
```
NeedsApproval(request: ApprovalRequest)
```

Values

approval_id

</>

pub fn approval_id(tool_name: String, command: String) -> String

Generate a stable approval request ID from tool name and command.

ask_approval

</>

pub fn ask_approval(
  tool_name: String,
  reason: String,
  command: String,
) -> ToolResult

Build an ApprovalRequest with a generated ID.

from_result

</>

pub fn from_result(result: Result(String, String)) -> ToolResult

Convert a Result(String, String) to ToolResult.