Skip to contents

Define authorization and limits for model tools

Source: R/tool_policy.R
tool_policy.Rd

Tool policy combines a default-deny allowlist with per-tool argument schemas, subject authorization, custom validators, and call, side-effect, and spend limits. Custom validators receive (arguments, subject, tool_name) and must return TRUE, FALSE, a message, or list(valid, message). Tools listed in approval_required are dispatched only when the approve hook explicitly returns TRUE or list(approved = TRUE, id = ...).

Usage

tool_policy(
  allowed_tools = character(),
  schemas = list(),
  authorize = NULL,
  validators = list(),
  side_effect_tools = character(),
  max_calls = Inf,
  max_side_effects = 0L,
  spend_limits = numeric(),
  spend_argument = "amount",
  approval_required = character(),
  approve = NULL,
  show_stats = FALSE
)

Arguments

allowed_tools

Explicit tool allowlist.

schemas

Named list of compact JSON-Schema-like lists or validator functions. Supported schema fields are required, properties, and additionalProperties; property fields include type, enum, pattern, minimum, and maximum.

authorize

Optional function receiving (subject, tool_name, arguments).

validators

Named list of additional per-tool validator functions.

side_effect_tools

Tools counted against max_side_effects.

max_calls

Maximum tool requests in one guarded chat.

max_side_effects

Maximum side-effecting requests in one guarded chat.

spend_limits

Named numeric vector of maximum spend per tool.

spend_argument

Name of the numeric argument carrying spend.

approval_required

Tools that require an explicit approval decision.

approve

Optional approval function receiving (subject, tool_name, arguments). The application is responsible for authenticating the human approver and preventing approval replay.

show_stats

Show construction time and available usage metrics.

Value

A shieldr_tool_policy object.

Examples

tools <- tool_policy(
  allowed_tools = "search_docs",
  schemas = list(search_docs = list(
    required = "query",
    properties = list(query = list(type = "string")),
    additionalProperties = FALSE
  )),
  max_calls = 3
)