nodrail

All guides

What to do when an AI agent requests an unknown permission

By Nodrail · 5 min read · Published

On this page
  1. Work out what is actually unknown
  2. Fail closed first, classify second
  3. Define who may resolve it
  4. Show the reviewer what is new
  5. Notice when capabilities change
  6. Make the outcome explicit
  7. Test the first occurrence
  8. What this does not cover

When an AI agent requests a permission your policy does not cover, treat the request as not authorized. Stop before the tool runs, work out why the request is unknown, and only then deny it or send it to a person who has authority over that scope. No answer is not an approval, and neither is the agent's own explanation.

Unknown requests are normal. Agents get new tools, tools gain operations, and a task can reach a resource nobody anticipated. What matters is that the first occurrence produces a decision rather than a silent default.

The policy, states and pseudocode below are illustrative. They are design examples, not an available Nodrail SDK or evidence of a deployed integration.

Work out what is actually unknown

"Unknown" covers several different situations, and they do not deserve the same response:

What is newExampleReasonable starting point
CallerAn agent identity that was never registeredDeny
Toolbilling appears in a support agent's tool listReview, if the tool is in a reviewable set
Operationticket.merge on a known ticketing toolReview
ResourceThe same ticket.read on project FinanceDeny if outside the allowed boundary, otherwise review
ParametersA reply to a customer instead of an internal noteReview, as a distinct request
DefinitionA known tool changes its description or input schemaReview again before relying on earlier decisions

The right-hand column is a starting point for this example. Your own boundary may be stricter.

Fail closed first, classify second

The OWASP AI Agent Security Cheat Sheet recommends failing closed for unknown tools or missing approval requirements. In practice, the check needs a fourth outcome besides allow, deny and review: "no rule matched".

That outcome should never reach the tool. It should lead to a classification step that ends in a denial or a pending review. If the classification itself fails, the call stops. A default that allows unmatched calls turns every gap in the policy into a grant.

Define who may resolve it

Sending everything unknown to a reviewer sounds safe, but it hands out authority that may not exist. Before building the review screen, decide:

  • Which tools, organizations and environments are eligible for review at all.
  • Who can approve each of them. Someone able to approve staging releases may have no authority over production.
  • Which requests are denied without review, such as an unauthenticated caller or anything covered by an explicit prohibition.

An explicit prohibition should keep its priority. Asking a second reviewer must not become a way around it.

Show the reviewer what is new

A reviewer needs to see why this request is here, not only what it does. Include the agent, tool, operation, resolved resource, exact parameters and the reason no rule matched, such as "first use of this operation by this agent".

Do not rely on what the tool says about itself. The Model Context Protocol tools specification states that clients must consider tool annotations untrusted unless they come from trusted servers. A label claiming an operation is read-only is useful context for a reviewer, but it is not evidence. Treat agent-supplied text the same way: display it as data and never let it instruct the reviewer.

Notice when capabilities change

An unknown permission can appear without anyone changing your policy. The MCP specification says a server's tool set may change over time and defines a notification for changes to the list. Any integration that caches tools needs a position on this:

  • Compare what is offered now with what was reviewed. A new name is a new tool.
  • Track a version or digest of each tool definition, so a changed schema or description is detected.
  • Decide what a change does to existing rules. In this example, a rule tied to the previous definition stops matching until someone reviews it.

Make the outcome explicit

A review of an unknown request can end in three ways:

DecisionEffect on this requestEffect on later requests
Approve onceAuthorizes this exact requestNone; the next one is still unknown
Create a ruleAuthorized through the new ruleMatching requests no longer need review
DenyStops the requestNone, unless the reviewer also adds a prohibition

Nothing should be learned implicitly. Repeated one-time approvals do not become a rule on their own, and a person should see the full scope before saving one.

The following is architectural pseudocode, not executable SDK code:

request = resolve_from_trusted_context(proposed_call)
result = evaluate_current_policy(request)

if result is unavailable or invalid:
    stop_without_invoking_tool()
else if result is NO_MATCH:
    if request is outside_reviewable_boundary:
        record_denial_and_stop()
    else:
        store_pending_review(request, reason_no_rule_matched)
        pause_without_invoking_tool()

Requests that do match a rule continue through the normal allow, deny and review paths described in the guide to managing agent permissions. The pending request then follows the lifecycle in the human approval guide.

Test the first occurrence

Use a simulated tool and count how many times it is really called:

ScenarioExpected result in this model
Tool absent from the policyNo invocation; a review or denial is recorded
Known tool, new operationNo invocation until a valid decision exists
Resource outside the boundaryNo invocation and no review offered
Policy lookup fails while classifyingNo invocation
Tool definition changes after reviewThe earlier decision no longer applies
Reviewer lacks authority for the scopeThe request stays unapproved

These are acceptance criteria for the example, not results from a test we have already run.

What this does not cover

Detecting an unknown permission only works for calls that reach the check. A tool invoked through another route or with direct credentials never appears as unknown, because it never appears at all. Decide which paths you control and say so plainly.

Add an unmatched case to your policy tests. Confirm the engine returns none, then confirm the integration holds or blocks the tool. Test APF decisions and check the integration boundary.