# IMentorActionGovernor interface

> The IMentorActionGovernor interface of Novior.MentorAgent.Abstractions.Interfaces: Governs the application's catalogue of actions from outside its code…

- URL: https://docs.mentoragent.net/api/novior-mentoragent-abstractions-interfaces/imentoractiongovernor
- Verified with: MentorAgent 1.4.0
- Last updated: 2026-11-18
- Packages: Novior.MentorAgent.Abstractions

Governs the application's catalogue of actions from outside its code: whether each action is on, the roles it requires, whether the user confirms it, and the description the model reads. The code says what it says — `[MentorAction(Enabled = false)]` ships an action off, `RequiredRoles` names who may run it, `RequiresConfirmation` asks first, `Description` tells the model what it does — and the governor may answer otherwise, for every session. For the application's own actions only, those `IMentorActionCatalog` lists: not the tools of the MCP servers the application consumes, not an agent source's own, never MentorAgent's.

**Registering a governor gives whoever implements it the power to widen what the code allows**: an action the code ships off runs once the governor turns it on, one that requires a role runs for anybody once the governor requires none, and one the code confirms runs without asking once the governor takes its confirmation away. What may be widened, when and with whose approval is the governor's to check; MentorAgent applies its answer.

Register it with `AddMentorActionGovernor<T>()`. There is one per application: a second registration throws. It is a singleton: what it needs from the conversation's scope it resolves from [`MentorActionRequest.Services`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentoractionrequest#services).

It is asked with [`MentorActionStage.Offer`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentoractionstage) when a session builds its tools — for the coordinator, the specialists and the team members, once for the session — and on every `tools/list` of the MCP server; and with [`MentorActionStage.Call`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentoractionstage) before every call, ahead of the roles, the policies and the confirmation. [`MentorActionRequest.SessionId`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentoractionrequest#sessionid) names the session every time, so an answer can stay the same for a whole session; on the MCP server without a session it is `null`: answer with what applies now. The tools a session was built with stay for that session; an action turned off meanwhile is refused at the call.

A governor that does not answer within `MentorOptions.ActionPolicyTimeout`, or throws, stops the action: it is not offered and the call does not run, with the reason [`MentorActionReasons.GovernorFailed`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentoractionreasons#governorfailed). Going back to the code instead would undo what the governor narrowed. Its exception's message is never logged, only its type. The A2A agent card is built once for every caller and follows the code only.

Every member has a default body that leaves the code's value, so a governor writes only what it governs. A member added to this interface in a later version comes with a default implementation.

## Definition

Namespace: `Novior.MentorAgent.Abstractions.Interfaces`. Package: `Novior.MentorAgent.Abstractions`.

`public interface IMentorActionGovernor`

```shell
dotnet add package Novior.MentorAgent.Abstractions
```

## Methods

### `GetConfirmationAsync`

`ValueTask<MentorConfirmationChoice> GetConfirmationAsync(MentorActionRequest request, CancellationToken cancellationToken)`

Whether the user confirms the action before it runs, in place of the code's confirmation, which [`MentorActionRequest.RequiresConfirmation`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentoractionrequest#requiresconfirmation) carries. [`MentorConfirmationChoice.Code`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentorconfirmationchoice): what the code says. [`MentorConfirmationChoice.Required`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentorconfirmationchoice): the user is asked, even if the code does not ask. [`MentorConfirmationChoice.None`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentorconfirmationchoice): the user is not asked, even if the code asks — declared, by default for writes, or by the `RequiresApproval` predicate. Asked only for an action that is on, after its roles.

Only the code's confirmation is the governor's to decide: an [`IMentorActionPolicy`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-interfaces/imentoractionpolicy) that answers [`MentorActionVerdict.Confirm`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentoractionverdict#confirm) still asks, a hosted MCP server's approval still comes from its provider, and with `RequireConfirmation` off nobody is asked. In Native mode [`MentorConfirmationChoice.Required`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentorconfirmationchoice) is asked even when an auto-approval rule would let the call through: those rules are the code's. An action whose confirmation is taken away still counts as one that changes data: tool filtering never offers it alone, and a model is never made to call it.

Narrowing takes effect at once: a confirmation added counts from the call, as an action turned off does. Widening counts from the next session: a confirmation taken away, as an action turned on. A call is confirmed when the session's answer or the call's asks for it. On the MCP server, where nobody can confirm, an action that asks is not published, and one whose confirmation the governor takes away is. The decisions say when the governor changed whether a call is confirmed ([`MentorActionDecision.ConfirmationFromOutside`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentoractiondecision#confirmationfromoutside)). The A2A agent card and `IMentorActionCatalog` say what the code says.

**Parameters**

- `request`: The action, with the code's confirmation, the user, the session, and where it is offered or called.
- `cancellationToken`: Cancelled when the governor takes longer than `ActionPolicyTimeout`, and with the turn.

### `GetDescriptionAsync`

`ValueTask<string?> GetDescriptionAsync(MentorActionRequest request, CancellationToken cancellationToken)`

The description the model reads for the action, in place of the code's (`[MentorAction(Description = …)]` or `[Description]`), which [`MentorActionRequest.Description`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentoractionrequest#description) carries. `null`, or a blank text: the code's. The action's name and the schema of its arguments never change, and the code's `ProactiveHint` still follows the description. Asked only for an action that is on, after its confirmation, as a session builds its tools and on every `tools/list` of the MCP server — never at a call.

The answer is what the model reads: the tools of the coordinator, the specialists and the team members, the texts tool filtering ranks, the classifiers, and the MCP server's `tools/list`. What the user sees stays the programmer's: the confirmation banner, the bar of the running action and the decisions' [`MentorActionDecision.DisplayName`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentoractiondecision#displayname) keep the code's description, so a description written outside the code, for example proposed by a console, speaks to the model and never changes what a user is asked to confirm. The policies are asked with the description the model reads, except on a call to the MCP server, which has no session and is asked with the code's. The A2A agent card, `IMentorActionCatalog` and the onboarding tour say what the code says.

The text reaches the model as the code's does: whoever writes it writes part of the model's instructions about the action.

**Parameters**

- `request`: The action, with the code's description, the user, the session, and where it is offered.
- `cancellationToken`: Cancelled when the governor takes longer than `ActionPolicyTimeout`, and with the turn.

### `GetRequiredRolesAsync`

`ValueTask<IReadOnlyList<string>?> GetRequiredRolesAsync(MentorActionRequest request, CancellationToken cancellationToken)`

The roles the action requires, in place of the code's (`[MentorAction(RequiredRoles = …)]`), which [`MentorActionRequest.RequiredRoles`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentoractionrequest#requiredroles) carries. `null`: the code's roles. An empty list: no role is required, so anybody may run the action, signed in or not. A list: the user needs any one of these roles, tested as the code's are. Asked only for an action that is on.

The answer decides everything the roles decide: whom the action is offered to on each turn, the check before a confirmation and again after it, and which MCP callers see it — on the MCP server an action that requires roles is published only with `McpCallerPrincipal`. The decisions say where the roles came from ([`MentorActionDecision.RolesFromOutside`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentoractiondecision#rolesfromoutside)). As for [`IMentorActionGovernor.IsEnabledAsync`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-interfaces/imentoractiongovernor#isenabledasync), the roles a session offers by are decided as it builds its tools, and every call is checked against the answer at the call. The A2A agent card and `IMentorActionCatalog` say what the code says.

**Parameters**

- `request`: The action, with the code's roles, the user, the session, and where it is offered or called.
- `cancellationToken`: Cancelled when the governor takes longer than `ActionPolicyTimeout`, and with the turn.

### `IsEnabledAsync`

`ValueTask<bool?> IsEnabledAsync(MentorActionRequest request, CancellationToken cancellationToken)`

Whether the action is on. `null`: what the code says — on, unless the action is declared off (`[MentorAction(Enabled = false)]`). `false`: not offered on any surface, and a call to it does not run ([`MentorActionReasons.Disabled`](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-models/mentoractionreasons#disabled)). `true`: on, even if the code ships it off.

Turning an action off takes effect at once for its calls; turning one on counts from the next session, which builds its tools with it. On `/mentor/chat` the session is the request.

**Parameters**

- `request`: The action, the user, the session, and where it is offered or called.
- `cancellationToken`: Cancelled when the governor takes longer than `ActionPolicyTimeout`, and with the turn.

---

- Previous: [IMentorActionCatalog interface](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-interfaces/imentoractioncatalog.md)
- Next: [IMentorActionObserver interface](https://docs.mentoragent.net/api/novior-mentoragent-abstractions-interfaces/imentoractionobserver.md)
