Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

ToolPermission

A ToolPermission defines what permissions are required to invoke a specific Tool. When an agent attempts to call a tool, the runtime checks the agent's accumulated permissions against the tool's ToolPermission.

Defining a ToolPermission

apiVersion: orloj.dev/v1
kind: ToolPermission
metadata:
  name: web-search-invoke
spec:
  tool_ref: web_search
  action: invoke
  match_mode: all
  apply_mode: global
  required_permissions:
    - tool:web_search:invoke
    - capability:web.read

Key Fields

FieldDescription
tool_refThe tool this permission gate applies to. Defaults to metadata.name.
actionThe action being gated. Defaults to invoke.
match_modeall requires every listed permission. any requires at least one.
apply_modeglobal applies to all agents. scoped applies only to target_agents.
required_permissionsPermission strings the agent must hold (via AgentRoles).

Operation Rules

ToolPermissions can define per-operation-class verdicts using operation_rules:

spec:
  tool_ref: database_tool
  operation_rules:
    - operation_class: read
      verdict: allow
    - operation_class: write
      verdict: approval_required
    - operation_class: delete
      verdict: deny
VerdictBehavior
allowProceed with the tool call (default).
denyBlock the call with a permission_denied error.
approval_requiredPause the task and create a ToolApproval resource.

Operation classes are declared on the Tool resource via spec.operation_classes. When multiple rules match, the most restrictive verdict wins: deny > approval_required > allow.

Related