IToolAuthorizationHandler

Namespace Tracon · Assembly Tracon.Abstractions.dll

Decides whether a tenant/user may call a specific tool.

public interface IToolAuthorizationHandler

Remarks

This is separate from approval (ToolDescriptor.RequiresApproval). Approval asks a human “is this call okay this time”; this interface asks the installation’s own policy “can this caller call this tool at all”. Both can apply to the same tool; when they do, authorization runs first — asking a human to approve a call the caller could never make anyway is backwards.

The default implementation (AllowAllToolAuthorizationHandler, registered with TryAdd) allows every call, so an installation that registers nothing keeps today’s behavior exactly. A consumer replaces the registration to enforce its own rule.

If this handler throws, the call is denied (fail-closed). A gate that fails open on an exception is not a gate.

The handler is asked for every call that runs through Tracon’s tool chain: a tool registered in code, a tool of an MCP server, the file_access_* tools of a session workspace (ToolEffect.Read, ToolEffect.Write or ToolEffect.Destructive), search_knowledge and the search_conversation_memory tool of an on-demand conversation memory (both ToolEffect.External: the text of the query leaves the process). The last three are not in IToolRegistry, so their names are not listed by GET /api/tools. The handler is not asked for a hosted tool (it runs at the model provider), an agent called as a tool, a skill tool, the file memory, todo and harness tools, or a tool that a provider added by an agent extension brings.

Methods

AuthorizeAsync(ToolAuthorizationRequest, CancellationToken)

Decides whether the call described by request may proceed.

ValueTask<ToolAuthorizationResult> AuthorizeAsync(ToolAuthorizationRequest request, CancellationToken cancellationToken = default)

Parameters

request ToolAuthorizationRequest

The call being authorized.

cancellationToken CancellationToken

The cancellation token.

Returns

ValueTask<ToolAuthorizationResult>

The decision.