The tool authorizer: who decides whether a tool call may run

From docs/tool-authorizer.md on the 3.0.0-GA branch (updated 2026-11-16, 8bad46e). Code and examples: github.com/ancientcomputing/locallm. Overview: LocalLM SDK.

Contents

A model cannot do anything to your Mac by itself. It can only write text. When it wants something done (read a file, add a calendar event, call a server), it writes a tool call, which is a request, and your app runs the tool. In the SDK, every one of those requests passes through one object before the tool runs: the authorizer, the code that decides whether a call may run. The docs sometimes call it the gate, because nothing gets past without being checked.

For an app that uses tools, this is the main change in SDK 3.0.

↑ Top

What changed in 3.0

What this means for you: if an app worked on 2.x and has a tool that writes, that tool's calls are now denied until you pass an authorizer. The model is told DENIED: <reason> and carries on without the tool. Nothing you compiled stops compiling. The behavior changed. Migrating to 3.0 has the checklist.

↑ Top

The three ready-made authorizers

Authorizer What it does Use it when
FailClosedToolAuthorizer Reads run. Everything that could change data or send it out is refused, with no prompt. It is what you get when you pass none. You haven't decided yet, or your app only reads.
ConfirmingToolAuthorizer Applies your rules on every call: it asks the user, or your own policy function, before calls that change things. Each MCP server has its own trust and approval settings. You are building an app with a user interface. This is the normal choice.
AllowingToolAuthorizer Allows every call. It turns the check off, on purpose. A batch job or a test run where no one is there to ask, and an unasked call can't hurt anyone.

You can also write your own by implementing ToolCallAuthorizer.

↑ Top

Setting one

import LocalLMLabSDKCore
import LocalLMLabSDKComponents          // a separate library in the SDK: it draws the "Allow this?" sheet

let confirmations = ToolConfirmationPresenter()                          // how the user is asked
let authorizer = ConfirmingToolAuthorizer(
    channel: confirmations,
    hostTools: .ask(atOrAbove: .mutate, by: .user))                      // ask before your own tools change anything
let session = try lab.makeSession(route: .chat, tools: tools, authorizer: authorizer)

// In your app's root view, so the sheet can appear:
//   ContentView().toolConfirmationSheet(confirmations)

.chat is a route name that your app declares (extension RouteName { static let chat: RouteName = "chat" }). lab and tools are the lab and tools you already have. To choose differently, pass AllowingToolAuthorizer() for no checks, or ConfirmingToolAuthorizer(channel:policy:hostTools:) with a policy: function when a rule, not the user, should answer.

↑ Top

What it looks at

Three things feed each decision:

↑ Top

What the user and the model see

↑ Top

Every entrance goes through it

The model's own tool calls, the calls an MCP App's interactive view makes, and your own code calling callMCPTool all pass through the session's authorizer. The settings are read on every call, so a change applies to the next call in a running session.

↑ Top

What it does not cover

↑ Top

A record of every decision

Each decision goes to the audit stream (lab.audit.events()) with who made it: a standing approval, the user, your policy, or the fail-closed default. If you write your own authorizer, implement verdict(for:) so the trail records who decided. Without it, the trail says only "authorizer".

↑ Top

If you are upgrading from 2.x

  1. Search your code for makeSession( calls that pass no authorizer:.
  2. For each one, pass a ConfirmingToolAuthorizer if the app has a user interface, or AllowingToolAuthorizer() where no one is there to ask and you accept the risk.
  3. Show the confirmation sheet in your root view (.toolConfirmationSheet(confirmations)), or users will see tools fail.
↑ Top

Where to read more

↑ Top