Raxol.Agent.Authorization.Policy (Raxol Agent v2.6.0)

Copy Markdown View Source

A single policy in the ALLOW/ASK/DENY authorization engine.

Distinct from Raxol.Agent.Policy (operational resilience: retry/cache/timeout) and from the deny-only Raxol.Agent.PermissionHook -- this is the authorization trichotomy with label state and human-in-the-loop ASK.

A policy is data: when it applies (phase + condition gate), what labels it may write, how its ASK approvals are remembered, and an evaluate function that returns a Raxol.Agent.Authorization.Verdict.

Applicability gates (cheap-first)

  1. Phase -- phases is :all or a list (:input | :tool_call | :tool_result | :output).

  2. Conditions -- a label gate %{key => value | [values]}: AND across keys, OR within a key's list, against the current label snapshot.

Writable labels

writable_labels is :all or a whitelist; a verdict's writes are filtered to keys the policy may write before they touch label state.

ASK scope (approval memory)

  • :once -- not remembered; ask again next time.
  • :session -- remembered for the engine's lifetime.
  • :root -- remembered per evaluation route (e.g. the root of a spawn tree), so approving once covers the whole tree.

Summary

Types

phase()
scope()
t()

Functions

applies?(policy, phase, labels)

Does this policy apply at phase given the current labels?

new(attrs)

Build a policy. Requires :name and :evaluate.

run(policy, context)

Run the policy's evaluate against context, filtering its writes.

Types

phase()

@type phase() :: :input | :tool_call | :tool_result | :output | atom()

scope()

@type scope() :: :once | :session | :root

t()

@type t() :: %Raxol.Agent.Authorization.Policy{
  conditions: map(),
  evaluate: (map() -> Raxol.Agent.Authorization.Verdict.t()),
  name: atom() | binary(),
  phases: :all | [phase()],
  scope: scope(),
  writable_labels: :all | [term()]
}

Functions

applies?(policy, phase, labels)

@spec applies?(t(), phase(), map()) :: boolean()

Does this policy apply at phase given the current labels?

new(attrs)

@spec new(keyword() | map()) :: t()

Build a policy. Requires :name and :evaluate.

run(policy, context)

@spec run(t(), map()) :: Raxol.Agent.Authorization.Verdict.t()

Run the policy's evaluate against context, filtering its writes.