Tool policy

import { createAdmin } from "@nylorun/admin";

const admin = createAdmin();

await admin.toolPolicy.put({
  rules: [
    { effect: "ask", agent: "support", tool: "refund_order", reason: "Refunds need a person" },
    {
      effect: "deny",
      kind: "http",
      tool: "refund_*",
      when: { amount: { gt: 10000 } },
      reason: "Refunds over 10000 are refused",
    },
    { effect: "ask", server: "github", tool: "create_*" },
  ],
});

The tool policy decides which MCP and HTTP tool calls run, wait for a person, or are refused. It is the Tenant's, set with a management key, and applies to every agent, every session, and every harness at once. An agent does not declare approvals.

put replaces every rule, and an empty list allows every call. To change one rule, read the policy with admin.toolPolicy.get() ({ rules, updatedAt }), edit the list, and write it back. A policy holds at most the Runtime limit toolRules (200 by default). A selector or when path is at most toolRuleFieldChars (200) characters, and a reason or matches expression at most toolRuleTextChars (500); past any of them, put is 400. See Runtime limits.

In Studio, the Tool policy tab of the Tenant page lists the rules, strictest first, edits one in a panel, and adds one with Add rule; it saves the policy whole, as put does.

From a terminal, nylorun tenant tool-policy get prints the policy as JSON, and put <file> (or put - for standard input) replaces it with the file's rules. What get prints, put takes back, so the policy can live in a repository and be applied from CI:

npx nylorun tenant tool-policy get > tool-policy.json
npx nylorun tenant tool-policy put tool-policy.json

RulesCopy Anchor Link

A pattern matches the whole name: refund_* matches refund_order, not partial_refund. matches is a regular expression searched in a string value; anchor it with ^ and $ to match the whole value. gt, gte, lt, and lte hold only for numbers. A when field the input does not have never matches.

MatchingCopy Anchor Link

• A rule matches a call when every field it sets matches. A rule that sets only effect matches every MCP and HTTP call.
• The strictest matching rule decides, whatever the order: deny, then ask, then allow.
• A call no rule matches runs.
• A policy the Runtime cannot read refuses every call.

An MCP tool is named by server and tool, never by the server__tool name the model sees. A policy stored with such a rule, written before the Runtime refused them, cannot be read: every MCP and HTTP call is denied with a reason naming the rule, and admin.toolPolicy.get() (GET /v1/tenant/tool-policy) answers 409 request_rejected, until you put the policy again. Rewrite each such rule:

{ "effect": "ask", "tool": "github__create_issue" }

becomes

{ "effect": "ask", "server": "github", "tool": "create_issue" }

Through an MCP gateway that puts a prefix before each tool name it lists, such as LiteLLM's github-create_issue, a rule still names the server's own tool (create_issue) once the Agent's credential sets the gateway's toolPrefix. See Gateway tool prefix.

What each effect doesCopy Anchor Link

A held call shows as held in session.toolCalls(). The turn pauses with turn.paused, which carries one approval interaction per held call:

The event's toolName stays the name the model called the tool by.

The Runtime decides as it records the call, before anything is sent, and the gateway runs only calls the record holds running. A harness of your own cannot skip the policy.

Approve a held callCopy Anchor Link

await session.approve(interactionId, true);

session.approve(interactionId, approved, { idempotencyKey? }) answers one held call. Without an idempotencyKey, each call makes its own; pass one to retry the same answer safely. The interactionId is the interaction's id in turn.paused (interactions[].interaction.id); session.pending() lists the same open interactions. Approved, the Runtime sends that exact call, with the input the person saw. Denied (false), the call fails to the model as tool.denied and is never sent. When every held call of the turn is answered, the turn goes on.

Nothing holds a process while a call waits: an approval can come a day later, or after the Runtime restarts. Cancelling the turn ends each held call as cancelled. See Pauses and control.

In Studio, a paused session shows an approval card for each held call, with its tool as server / tool (and "as <toolName>", the model's name), why it is held, and its input, and Approve and Deny.

Where it appliesCopy Anchor Link

A call a subagent makes is decided like any other, with agent set to the subagent's id. deny fails it to the subagent's model. ask holds it and pauses the parent's turn; approve it on the parent's session. A flow agent used as a subagent runs in its own session, and a call held there waits on that session.

ReferenceCopy Anchor Link

Next stepCopy Anchor Link