[API Proposal]: Add ReasoningEffort.Max

[AkiKurisu]

Background and motivation

We maintain a .NET agent harness dotcraft that targets multiple providers through one IChatClient
pipeline, with reasoning effort as one provider-neutral user setting. Every level up to
xhigh rides on ChatOptions.Reasoning. max cannot, so supporting it means carrying
that one value outside ChatOptions and re-shaping the request per provider.

ReasoningEffort tops out at ExtraHigh → "xhigh" (#7319), while both providers with
first-party IChatClient adapters now expose a tier above it:

• OpenAI .NET — #1289 added
  ExtraHigh ("xhigh") and Max ("max") to ResponseReasoningEffortLevel. Merged
  2026-08-21, not in a stable release yet (latest 2.13.0).
• Anthropic .NET 12.42.0 — Anthropic.Models.Messages.Effort and its Beta
  counterpart already expose Xhigh and Max.

Two providers, same token — not the single-provider case #7318 declined for Minimal. And
ReasoningOptions is sealed with only Effort and Output, so there is no neutral way
to express it today.

API Proposal

namespace Microsoft.Extensions.AI;

public enum ReasoningEffort
{
    None,
    Low,
    Medium,
    High,
    ExtraHigh,
    Max,
}

With the matching arm next to each existing ExtraHigh case:

// OpenAIResponsesChatClient / OpenAIChatClient
ReasoningEffort.Max => new ResponseReasoningEffortLevel("max"),
ReasoningEffort.Max => new ChatReasoningEffortLevel("max"),

String constructor initially, as "xhigh" does today; switchable to the generated .Max
property once a release containing #1289 is picked up.

API Usage

ChatResponse response = await chatClient.GetResponseAsync("...", new ChatOptions
{
    Reasoning = new ReasoningOptions { Effort = ReasoningEffort.Max },
});

Alternative Designs

RawRepresentationFactory. Works, but requires the caller to know which provider backs
the IChatClient and to build the provider-specific request — for a value that is not
provider-specific. It makes the top tier the only effort level that cannot travel through
ChatOptions, leaving two parallel paths for one user-facing setting.

Remap ExtraHigh to "max". Silent behavior and cost change, and xhigh becomes
unreachable.

Risks

No response