fix: honor MEAI instructions and reject unsupported generation options

Author: KSemenenko

ClaudeCodeSharpSDK.Extensions.AI/ClaudeChatClient.cs

@@ -25,8 +25,9 @@ public async Task<ChatResponse> GetResponseAsync(
     {
         ArgumentNullException.ThrowIfNull(messages);
         ChatOptionsMapper.ValidateFunctionCallingOptions(options);
+        ChatOptionsMapper.ValidateGenerationOptions(options);
 
-        var prompt = ChatMessageMapper.ToClaudeInput(messages);
+        var prompt = ChatMessageMapper.ToClaudeInput(messages, options?.Instructions);
         var threadOptions = ChatOptionsMapper.ToThreadOptions(options, _options);
         var turnOptions = ChatOptionsMapper.ToTurnOptions(options, cancellationToken);
 
@@ -48,8 +49,9 @@ public async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
     {
         ArgumentNullException.ThrowIfNull(messages);
         ChatOptionsMapper.ValidateFunctionCallingOptions(options);
+        ChatOptionsMapper.ValidateGenerationOptions(options);
 
-        var prompt = ChatMessageMapper.ToClaudeInput(messages);
+        var prompt = ChatMessageMapper.ToClaudeInput(messages, options?.Instructions);
         var threadOptions = ChatOptionsMapper.ToThreadOptions(options, _options);
         var turnOptions = ChatOptionsMapper.ToTurnOptions(options, cancellationToken);
 

ClaudeCodeSharpSDK.Extensions.AI/Internal/ChatMessageMapper.cs

@@ -9,9 +9,13 @@ internal static class ChatMessageMapper
     private const string ParagraphSeparator = "\n\n";
     private const string ImageUnsupportedMessage = "Claude Code chat adapter currently supports text-only prompts.";
 
-    internal static string ToClaudeInput(IEnumerable<ChatMessage> messages)
+    internal static string ToClaudeInput(IEnumerable<ChatMessage> messages, string? instructions = null)
     {
         var promptParts = new List<string>();
+        if (!string.IsNullOrWhiteSpace(instructions))
+        {
+            promptParts.Add(string.Concat(SystemPrefix, instructions));
+        }
 
         foreach (var message in messages)
         {

ClaudeCodeSharpSDK.Extensions.AI/Internal/ChatOptionsMapper.cs

@@ -7,6 +7,7 @@ namespace ManagedCode.ClaudeCodeSharpSDK.Extensions.AI.Internal;
 
 internal static class ChatOptionsMapper
 {
+    private const string GenerationOptionsUnsupportedMessage = "The Claude CLI adapter does not support the requested MEAI generation options.";
     private const string FunctionToolsUnsupportedMessage = "MEAI function tools are not supported by the Claude CLI adapter.";
     private const string ToolModeUnsupportedMessage = "Only automatic MEAI tool mode is supported by the Claude CLI adapter.";
     private const string InvalidValueMessagePrefix = "Invalid value for Claude chat option";
@@ -22,6 +23,17 @@ internal static class ChatOptionsMapper
     internal const string AppendSystemPromptKey = "claude:append_system_prompt";
     internal const string MaxBudgetUsdKey = "claude:max_budget_usd";
 
+    internal static void ValidateGenerationOptions(ChatOptions? options)
+    {
+        if (options is { Temperature: not null } or { TopP: not null } or { TopK: not null } or
+            { MaxOutputTokens: not null } or { Seed: not null } or { FrequencyPenalty: not null } or
+            { PresencePenalty: not null } || options?.StopSequences is { Count: > 0 } ||
+            options?.ResponseFormat is { } format && format is not ChatResponseFormatText)
+        {
+            throw new NotSupportedException(GenerationOptionsUnsupportedMessage);
+        }
+    }
+
     internal static void ValidateFunctionCallingOptions(ChatOptions? chatOptions)
     {
         if (chatOptions?.Tools is { Count: > 0 })

ClaudeCodeSharpSDK.Tests/MEAI/ChatMessageMapperTests.cs

@@ -15,6 +15,19 @@ public class ChatMessageMapperTests
     private const string PngMimeType = "image/png";
     private const string TextOnlyPromptsMessage = "text-only prompts";
 
+    private const string StandardInstructions = "Follow the standard MEAI instructions.";
+    private const string ExistingSystemText = "Existing system message.";
+    private const string UserQuestion = "User question.";
+    private const string ExpectedInstructionPrompt = "[System] Follow the standard MEAI instructions.\n\n[System] Existing system message.\n\nUser question.";
+
+    [Test]
+    public async Task StandardInstructionsPrecedeSystemAndUserMessages()
+    {
+        var messages = new[] { new ChatMessage(ChatRole.System, ExistingSystemText), new ChatMessage(ChatRole.User, UserQuestion) };
+        var prompt = ChatMessageMapper.ToClaudeInput(messages, StandardInstructions);
+        await Assert.That(prompt).IsEqualTo(ExpectedInstructionPrompt);
+    }
+
     [Test]
     public async Task ToClaudeInput_MixedConversation_PreservesChronology()
     {

ClaudeCodeSharpSDK.Tests/MEAI/UnsupportedToolOptionsTests.cs

@@ -25,6 +25,35 @@ public sealed class UnsupportedToolOptionsTests
     private const string NodeEvalArgument = "-e";
     private const string NodeMarkerScript = "require('node:fs').writeFileSync(process.argv[1], 'started');";
 
+    private const string GenerationStopSequence = "fixture stop";
+
+    [Test]
+    [Arguments(0)]
+    [Arguments(1)]
+    [Arguments(2)]
+    [Arguments(3)]
+    [Arguments(4)]
+    [Arguments(5)]
+    [Arguments(6)]
+    [Arguments(7)]
+    [Arguments(8)]
+    public async Task ExplicitUnsupportedGenerationOptionsFailBeforeNativeExecution(int vector)
+    {
+        var options = vector switch
+        {
+            0 => new ChatOptions { Temperature = 0.5f },
+            1 => new ChatOptions { TopP = 0.5f },
+            2 => new ChatOptions { TopK = 1 },
+            3 => new ChatOptions { MaxOutputTokens = 1 },
+            4 => new ChatOptions { Seed = 1 },
+            5 => new ChatOptions { FrequencyPenalty = 0.5f },
+            6 => new ChatOptions { PresencePenalty = 0.5f },
+            7 => new ChatOptions { StopSequences = [GenerationStopSequence] },
+            _ => new ChatOptions { ResponseFormat = ChatResponseFormat.Json }
+        };
+        await AssertRejectedWithoutLaunchingAsync(options);
+    }
+
     [Test]
     public async Task NonemptyMeaiToolsAreRejectedBeforeLaunchingOrCreatingAThread()
     {
@@ -78,12 +107,8 @@ private static async Task AssertRejectedWithoutLaunchingAsync(ChatOptions option
             await Assert.That(streamError).IsTypeOf<NotSupportedException>();
             await Assert.That(File.Exists(markerPath)).IsFalse();
 
-            var resumeOptions = new ChatOptions
-            {
-                ConversationId = EmptyConversationId,
-                Tools = options.Tools,
-                ToolMode = options.ToolMode,
-            };
+            var resumeOptions = options.Clone();
+            resumeOptions.ConversationId = EmptyConversationId;
             var resumeError = await Assert.That(async () =>
             {
                 _ = await client.GetResponseAsync(CreateMessages(), resumeOptions);

Directory.Build.props

@@ -13,7 +13,7 @@
     <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
     <AnalysisLevel>latest-recommended</AnalysisLevel>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
-    <Version>2.1.292.4</Version>
+    <Version>2.1.292.5</Version>
     <PackageVersion>$(Version)</PackageVersion>
 
   </PropertyGroup>

docs/Features/meai-integration.md

@@ -171,3 +171,7 @@ Native provider failures stop producing response updates, but the adapter contin
 - DI extensions register the client correctly.
 - All mapper and DI tests pass.
 - ADR and feature docs stay aligned with the adapter surface.
+
+## Standard MEAI request options
+
+`ChatOptions.Instructions` is included before the supplied messages using the adapter’s existing system-message mapping in both response modes. Existing system and user messages retain their order. Model selection remains supported through `ModelId`. Explicit temperature, nucleus/top-k sampling, maximum output tokens, seed, penalties, stop sequences and non-text response formats are rejected before any native thread/process starts because this adapter does not implement those generation controls. The core typed `OutputSchema` API remains separate; arbitrary MEAI JSON schemas are not silently approximated.