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| Method | Description |
|---|---|
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
| Option | Type | Default | Description |
|---|---|---|---|
tools | ToolDefinition[] | Record<string, ToolDefinition> | none | The tools the agent was given |
validateArguments | boolean | true | Validate arguments against the declared tool's JSON Schema |
allow | string[] | every tool | Names or globs that may be called |
deny | string[] | none | Names or globs that may never be called. Checked before allow. |
rules | Record<string, ToolPolicyRule> | none | Labels, limits, and destinations, by tool name or glob |
maxTotalCalls | number | none | The most tool calls in the session, across all tools |
flow | "untrusted" | "trifecta" | false | "untrusted" | When sink tools are refused |
guessLabels | boolean | false | Label tools that no rule labels from their names |
approve | (call, decision) => boolean | Promise<boolean> | none | Called for a call the flow rule refuses. true lets it run. |
state | ToolPolicyState | empty | Start from a state saved with state() |
A rule (ToolPolicyRule) has three optional fields:
| Field | Type | Description |
|---|---|---|
labels | ("untrusted" | "private" | "sink")[] | What the tool does with data |
maxCalls | number | The 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.
| Field | Type | Description |
|---|---|---|
allowed | boolean | Whether the call may run |
reason | string | "allowed", "approved", or a refusal reason |
message | string | A sentence for your logs, or for the model in place of the tool's output |
tool | string | The tool's name, as the call gave it |
violations | SchemaViolation[] | 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:
| Label | Meaning |
|---|---|
untrusted | Its results carry content from outside, such as a web page, search results, email, issues, or tickets |
private | It reads private data, such as files, contacts, customer records, or email |
sink | It 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:
flow | A 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 |
false | Never. 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
allowreceives 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,
$refonly 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.