ExAgent.Permissions (ExAgent v1.1.0)

Per-tool admission control: :allow, :ask or :deny, matched against tool names with glob patterns — the same model opencode uses for tool safety.

Rules are evaluated in order and the last matching rule wins (so put a catch-all * first, then more specific rules after it). Anything that matches no rule falls back to :default (:allow by default).

:allow — run the tool.
:deny — never run it; the model receives a "permission denied" tool return so it can adapt.
:ask — require human approval. In a one-shot ExAgent.run/3 you pass an :approve callback (tool_call -> :approve | :deny); the run calls it (it may block on a PubSub round-trip in a LiveView). With no callback, :ask is treated as :deny (fail closed).

Example

perms =
  ExAgent.Permissions.new!(
    rules: [{"*", :deny}, {"read", :allow}, {"search_*", :allow}, {"bash", :ask}],
    default: :deny
  )

ExAgent.Permissions.decide(perms, "bash")        #=> :ask
ExAgent.Permissions.decide(perms, "search_web")  #=> :allow
ExAgent.Permissions.decide(perms, "write")       #=> :deny

Summary

Types

action()

t()

Functions

decide(permissions, tool_name)

Decide the action for a tool name (last matching rule wins, else default).

new!(opts)

Build a permissions set from rules ([{glob_string, action}]) and a :default action. Globs support * (any run of chars) and ? (single char).

resolve(action, tool_call, approve)

Resolve an :ask decision through an optional approve callback.