ExAthena.Permissions (ExAthena v0.3.0)

Copy Markdown View Source

Decides whether a tool call is allowed.

Every tool call runs through check/4 before execution. The check combines three sources — in this order, first decisive wins:

  1. disallowed_tools — an explicit blocklist. Always denies.
  2. allowed_tools — an explicit allowlist. If non-nil, denies anything not in it.
  3. phase — the current permission mode:
    • :plan — read-only. Writes and shell execution are denied.
    • :default — read + write. can_use_tool callback (if supplied) can ask the user.
    • :bypass_permissions — everything allowed without asking.

The can_use_tool callback is a function (tool_name, arguments, ctx -> :allow | :deny | {:deny, reason}) that the loop calls in :default mode for anything the caller marked as sensitive. See Permissions.Opts below.

Summary

Types

opts()
result()

Functions

check(tool_call, ctx, opts)

Check whether tool_call is allowed under opts. Returns :allow or {:deny, reason}.

readonly_tools()

Static list of read-only tool names the :plan phase permits.

Types

opts()

@type opts() :: %{
  optional(:phase) => ExAthena.ToolContext.phase(),
  optional(:allowed_tools) => [String.t()] | nil,
  optional(:disallowed_tools) => [String.t()] | nil,
  optional(:can_use_tool) => (String.t(), map(), ExAthena.ToolContext.t() ->
                                result())
}

result()

@type result() :: :allow | {:deny, reason :: term()}

Functions

check(tool_call, ctx, opts)

@spec check(ExAthena.Messages.ToolCall.t(), ExAthena.ToolContext.t(), opts()) ::
  result()

Check whether tool_call is allowed under opts. Returns :allow or {:deny, reason}.

readonly_tools()

@spec readonly_tools() :: [String.t()]

Static list of read-only tool names the :plan phase permits.