Skip to Content
ZeroLeaksDocs
Shield SDK

Tool policy

A deterministic policy for an agent's tool calls, covering declared tools, argument schemas, allow and deny lists, call limits, and data flow.

createToolPolicy() decides whether an agent's tool call may run. It runs in your process with no model and no network, and gives the same answer for the same calls.

detect() can miss an injection, so the policy doesn't try to recognize one. It limits what the agent can do after it has read content it can't trust: an agent that read an untrusted email can't then send one, unless you allowed the destination or you approve the call.

import { createToolPolicy } from "@zeroleaks/shield";
import { detect } from "@zeroleaks/shield/local";

const policy = createToolPolicy({
  tools, // the tool definitions you give the model
  deny: ["delete_*"],
  rules: {
    read_inbox: { labels: ["untrusted", "private"] },
    fetch_url: { labels: ["untrusted"] },
    send_email: {
      labels: ["sink"],
      maxCalls: 5,
      destinations: { arguments: ["to", "cc"], allow: ["acme.com"] },
    },
  },
});

for (const call of toolCalls) {
  const decision = await policy.checkAsync({ name: call.name, arguments: call.arguments });
  if (!decision.allowed) {
    results.push({ id: call.id, output: decision.message }); // the model reads why
    continue;
  }
  const output = await runTool(call);
  policy.recordResult(call.name, { flagged: detect(output).detected });
  results.push({ id: call.id, output });
}

Create one policy per agent session or conversation. A policy remembers what the session has read and how many calls it made, so sharing one across users' sessions lets one session's untrusted content block another's sinks.

Methods

function createToolPolicy(options?: ToolPolicyOptions): ToolPolicy
MethodDescription
check(call)Returns a decision for { name, arguments, source? } and counts the call when allowed
checkAsync(call)The same, and waits for an approve that returns a Promise
recordResult(name, { flagged? })Tells the policy that a tool returned, and whether its result was flagged
recordUntrusted(source?)Records untrusted content that didn't come from a tool, such as a retrieved document
recordPrivate(source?)Records private data that didn't come from a tool, such as a customer record
declareTools(tools, source?)Declares tools, replacing those declared before under the same source
state()What the session has seen, as plain data: { untrustedFrom, privateFrom, calls }
reset()Forgets what the session saw and the calls it counted. Declared tools and options stay.

Options

OptionTypeDefaultDescription
toolsToolDefinition[] | Record<string, ToolDefinition>noneThe tools the agent was given
validateArgumentsbooleantrueValidate arguments against the declared tool's JSON Schema
allowstring[]every toolNames or globs that may be called
denystring[]noneNames or globs that may never be called. Checked before allow.
rulesRecord<string, ToolPolicyRule>noneLabels, limits, and destinations, by tool name or glob
maxTotalCallsnumbernoneThe most tool calls in the session, across all tools
flow"untrusted" | "trifecta" | false"untrusted"When sink tools are refused
guessLabelsbooleanfalseLabel tools that no rule labels from their names
approve(call, decision) => boolean | Promise<boolean>noneCalled for a call the flow rule refuses. true lets it run.
stateToolPolicyStateemptyStart from a state saved with state()

A rule (ToolPolicyRule) has three optional fields:

FieldTypeDescription
labels("untrusted" | "private" | "sink")[]What the tool does with data
maxCallsnumberThe most calls to each tool the rule matches, in the session
destinations{ arguments: string[]; allow: string[] }Where a sink may send data after untrusted content

In names and globs, * matches any run of characters, including none. Every rule that matches a tool applies: labels are combined, and the lowest maxCalls counts.

Returns

check() and checkAsync() return a ToolPolicyDecision. It contains no argument values in either message or violations.

FieldTypeDescription
allowedbooleanWhether the call may run
reasonstring"allowed", "approved", or a refusal reason
messagestringA sentence for your logs, or for the model in place of the tool's output
toolstringThe tool's name, as the call gave it
violationsSchemaViolation[]With invalid_arguments: up to five { path, keyword, message }

Declare tools

With tools, a call to any other name is refused as undeclared_tool. tools takes the shapes scanTools() takes, or an object from names to definitions, like the AI SDK's tools. The rule is off until tools are declared, and declaring an empty list refuses every call.

Argument schemas

The policy validates arguments against the declared tool's JSON Schema, read from the same field scanTools() reads. A tool without a schema takes any arguments. The validator ignores keywords it doesn't know.

Limit calls

A rule's maxCalls limits the calls to each tool the rule matches, and maxTotalCalls limits all calls in the session. check() counts a call only when it allows it, so call it right before the tool runs, after any other check that could still stop the call.

Restrict data flow

Label tools by what they do with data:

LabelMeaning
untrustedIts results carry content from outside, such as a web page, search results, email, issues, or tickets
privateIt reads private data, such as files, contacts, customer records, or email
sinkIt can send data out, such as email, chat messages, HTTP requests, or an issue or comment others can read

The session has seen untrusted content once recordResult() is called for a tool labeled untrusted or with flagged: true, or once recordUntrusted() is called. flow then decides when a sink call is refused:

flowA sink call is refused
"untrusted" (default)Once the session has seen untrusted content
"trifecta"Once the session has seen untrusted content and read private data, in either order
falseNever. state() still records what the session saw.

Private data comes from recordResult() for a tool labeled private, or from recordPrivate(). Without labels, the flow rule refuses nothing.

Allow destinations

A rule's destinations lets a refused sink call run when every destination is allowed. arguments names the arguments that hold destinations, as top-level names or dotted paths such as message.to, and allow lists the destinations. There must be at least one destination.

rules: {
  send_email: {
    labels: ["sink"],
    destinations: { arguments: ["to", "cc", "bcc"], allow: ["acme.com", "partner@example.org"] },
  },
  http_post: {
    labels: ["sink"],
    destinations: { arguments: ["url"], allow: ["api.acme.com"] },
  },
}

Approve a refused call

approve(call, decision) is called for a call the flow rule refuses, with the arguments parsed. Return true to let it run, for example after a person confirmed it. The decision's reason is then approved. Other refusals never reach approve.

const policy = createToolPolicy({
  rules,
  approve: async (call, decision) => await askUser(`${decision.message} Run ${call.name} anyway?`),
});

check() throws a TypeError when approve returns a Promise, so use checkAsync(). After an async approve answers, the call limits are checked again.

Guess labels

guessLabels: true labels each tool that no rule labels, from its name, with guessToolLabels(name). Label guessing is deliberately narrow. Review what guessToolLabels() returns for your tools and set labels yourself where a guess is wrong or missing.

Save state

state() returns plain data. Pass it back as the state option to continue a session in another process, such as the next request of a conversation:

const policy = createToolPolicy({ ...policyOptions, state: conversation.policyState });
// run the agent's turn
conversation.policyState = policy.state();

Use with an MCP client

Pass the policy to shieldMcpClient. The wrapper declares each server's tools, checks each callTool() before it reaches the server, throws ToolPolicyError if refused, and records each result. One policy can serve several servers, so content read through one blocks a sink on another.

Use with the OpenAI Agents SDK

shieldToolPolicyGuardrail() checks each call before the tool runs, and shieldToolOutputGuardrail({ policy }) records each output. Give both a function of the run's context, so every run gets its own policy. A refused call doesn't run, and the model gets the decision's message as the tool's output. See OpenAI Agents SDK.

Limitations

  • A call that misuses an allowed tool with arguments that match the schema, such as refunding the wrong account, is allowed.
  • The flow rule never refuses a tool that isn't labeled sink, even if it sends data out.
  • A destination on allow receives whatever the arguments carry.
  • Untrusted text in a user message, a retrieved document, or the system prompt counts only after you call recordUntrusted().
  • Data that leaves in the model's reply is not checked. Use output scanning.
  • When tool calls from one turn run in parallel, a sink call can be refused because of a result recorded in that turn.
  • Unlisted JSON Schema keywords are ignored, $ref only follows pointers into the same schema, and some patterns are not run.
  • A call that reaches a validation limit is refused.
  • The state lives in the policy object. Two processes that act on one session at the same time each count their own calls.

On this page