Action policies and observers

The tool gate is the part of MentorAgent that decides whether a call to one of your actions may run: the roles, the confirmation, then the action. This page lists the types that let your code take part in it. An action policy decides, in your code, whether a user may use an action and whether a call may run. An observer receives every decision of the gate. MentorActionConfirmation tells an action who confirmed it. IMentorActionCatalog lists your actions as MentorAgent sees them.

Roles, confirmation and governance explains when to use them, with an example of a policy. The types are in the Novior.MentorAgent.Abstractions.Interfaces and Novior.MentorAgent.Abstractions.Models namespaces. The registration methods are in Novior.MentorAgent.Extensions. All of them are new in 1.2.0.

A call to one of your actions is decided in this order:

1. the roles of the action, RequiredRoles;
2. IsAllowedAsync of every policy;
3. BeforeActionAsync of every policy;
4. the confirmation: the action's own, or the one that a policy asked for;
5. the action.

A call refused or stopped before step 4 shows no confirmation box. After the user confirms, MentorAgent asks the roles and IsAllowedAsync again, so a permission taken away while the box was open stops the action.

A class of yours that decides on the application's actions. Register it with AddMentorActionPolicy<T>(), or an instance with AddMentorActionPolicy(policy). A policy is a singleton. Every policy registered is asked, in the order of registration. Both methods have a default body, so a policy writes only the one it needs.

Where policies are asked.

Policies decide on your actions and on the tools of the MCP servers that you consume. They never decide on MentorAgent's own tools, such as navigate_to, remember, load_skill, route_to_specialist, a team's tool or invoke_ui_action, so not on the UI actions of a page either. The A2A agent card is not filtered: it is one card for every caller.

A policy that fails stops the call. Each call to a policy may take ActionPolicyTimeout, 5 seconds by default. A policy that throws, returns null or does not answer in time stops the call, and the model reads that the check could not be completed. When MentorAgent decides what to offer, such a policy leaves the action out. The log names the type of the exception, never its message.

IsAllowedAsync is asked for every action offered, by every policy, on every turn: keep it fast, for example with a cache per user.

What a policy is asked about.

What BeforeActionAsync answers for one call. Its Kind is a MentorActionVerdictKind, and its Reason is your text.

The reason reaches the model and the observers. Never put a secret in it.

Receives every decision of the gate, for every session and every surface of the process, and for every agent that calls a tool. Use it for an audit trail: who asked for which action, and why the gate decided as it did. Register it with AddMentorActionObserver<T>(), or an instance with AddMentorActionObserver(observer).

public class ActionAuditLog(ILogger<ActionAuditLog> logger) : IMentorActionObserver
{
    public ValueTask OnDecisionAsync(
        MentorActionDecision decision, CancellationToken cancellationToken)
    {
        logger.LogInformation(
            "{Tool}: {Outcome} ({Reason}) for {User}, confirmed by {ConfirmedBy}",
            decision.ToolName, decision.Outcome, decision.ReasonCode,
            decision.User?.Identity?.Name ?? "anonymous",
            decision.ConfirmedBy?.Identity?.Name ?? "nobody");
        return ValueTask.CompletedTask;
    }
}

• One method. OnDecisionAsync(MentorActionDecision, CancellationToken) receives one decision.
• Never in the way. An observer never runs on the path of the action. Each observer has a queue of its own and receives the decisions in the order they were taken. A slow observer, or one that throws, delays and stops nothing, and its failure is logged.
• Five seconds a call. A call that has not finished in 5 seconds is no longer awaited, and its token is cancelled. The next decision can then arrive while that call still runs, so an observer must be thread-safe.
• A singleton. It is resolved once, from the root services of the application. An observer that needs scoped services creates a scope with IServiceScopeFactory.
• No record of its own. MentorAgent keeps no copy of the decisions. A record of who confirmed what, built on an observer, and what it can miss: see Audit: who confirmed what.

One decision of the gate. It never carries the arguments of the call.

A call goes through the outcomes in one of these orders, the same in Blocking and in Native mode:

• Allowed, then Executed, Failed or Stopped;
• Allowed, ConfirmationRequested, then Rejected, Stopped or Confirmed. After Confirmed comes the outcome of the run, or Denied when a role or a permission was taken away while the box was open;
• Denied, Blocked or PolicyFailed alone.

The reason codes, as string constants. They stay the same across versions: a new code comes only in a minor version, and the release notes of that version say so.

Inside the method of an action, MentorActionConfirmation.Current says who confirmed this call, and when. It works in Blocking and in Native mode, and it is null for a call that nobody confirmed. So a ledger of your writes can record who approved each one.

public class CaseEscalation(ILogger<CaseEscalation> logger)
{
    [MentorAction(
        Description = "Escalates a support case to the second line",
        RequiresConfirmation = true)]
    public string EscalateCase(string caseNumber)
    {
        // Who confirmed this call, and when: null when nobody confirmed it
        var confirmation = MentorActionConfirmation.Current;
        logger.LogInformation(
            "Case {Case} escalated, confirmed by {User} at {Time}",
            caseNumber,
            confirmation?.ConfirmedBy?.Identity?.Name,
            confirmation?.ConfirmedAt);
        return $"Case {caseNumber} escalated.";
    }
}

Registered by AddMentorAgent(). Its GetActions() lists every [MentorAction] of the coordinator, of the specialists and of the team members, one MentorActionInfo each, decided again at every call. Use it for an administration page, or for a test that fails when an action is published by mistake:

// The writes that the MCP server publishes to every caller, for example
// to fail a test when one appears
public static IEnumerable<string> WritesPublishedToEveryone(
    IServiceProvider services) =>
    services.GetRequiredService<IMentorActionCatalog>().GetActions()
        .Where(action => !action.ReadOnly
            && action.McpExposure == MentorMcpExposure.Published)
        .Select(action => action.ToolName);

The catalog says what MentorAgent's own rules decide. A policy can still leave an action out for one user. The tools of the MCP servers that you consume, and those of an agent source, are not in it.