Add transform operation for system prompt section customization

Adds a new 'transform' action to SectionOverride that enables read-then-write
mutation of system prompt sections via callbacks. The SDK intercepts function-
valued actions before serialization, stores the callbacks locally, and handles
the batched systemMessage.transform JSON-RPC callback from the runtime.

Changes across all 4 SDKs (TypeScript, Python, Go, .NET):
- Types: SectionTransformFn, SectionOverrideAction (TS/Python), Transform
  field (Go/.NET), SectionOverrideAction constants (Go)
- Client: extractTransformCallbacks helper, transform callback registration,
  systemMessage.transform RPC handler
- Session: transform callback storage and batched dispatch with error handling
- E2E tests and shared snapshot YAML files

Wire protocol: single batched RPC call with all transform sections, matching
the runtime implementation in copilot-agent-runtime PR #5103.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 2 people

dotnet/src/Client.cs

@@ -365,6 +365,44 @@ private async Task CleanupConnectionAsync(List<Exception>? errors)
         }
     }
 
+    private static (SystemMessageConfig? wireConfig, Dictionary<string, Func<string, Task<string>>>? callbacks) ExtractTransformCallbacks(SystemMessageConfig? systemMessage)
+    {
+        if (systemMessage?.Mode != SystemMessageMode.Customize || systemMessage.Sections == null)
+        {
+            return (systemMessage, null);
+        }
+
+        var callbacks = new Dictionary<string, Func<string, Task<string>>>();
+        var wireSections = new Dictionary<string, SectionOverride>();
+
+        foreach (var (sectionId, sectionOverride) in systemMessage.Sections)
+        {
+            if (sectionOverride.Transform != null)
+            {
+                callbacks[sectionId] = sectionOverride.Transform;
+                wireSections[sectionId] = new SectionOverride { Action = SectionOverrideAction.Transform };
+            }
+            else
+            {
+                wireSections[sectionId] = sectionOverride;
+            }
+        }
+
+        if (callbacks.Count == 0)
+        {
+            return (systemMessage, null);
+        }
+
+        var wireConfig = new SystemMessageConfig
+        {
+            Mode = systemMessage.Mode,
+            Content = systemMessage.Content,
+            Sections = wireSections
+        };
+
+        return (wireConfig, callbacks);
+    }
+
     /// <summary>
     /// Creates a new Copilot session with the specified configuration.
     /// </summary>
@@ -409,6 +447,8 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
             config.Hooks.OnSessionEnd != null ||
             config.Hooks.OnErrorOccurred != null);
 
+        var (wireSystemMessage, transformCallbacks) = ExtractTransformCallbacks(config.SystemMessage);
+
         var sessionId = config.SessionId ?? Guid.NewGuid().ToString();
 
         // Create and register the session before issuing the RPC so that
@@ -424,6 +464,10 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
         {
             session.RegisterHooks(config.Hooks);
         }
+        if (transformCallbacks != null)
+        {
+            session.RegisterTransformCallbacks(transformCallbacks);
+        }
         if (config.OnEvent != null)
         {
             session.On(config.OnEvent);
@@ -440,7 +484,7 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
                 config.ClientName,
                 config.ReasoningEffort,
                 config.Tools?.Select(ToolDefinition.FromAIFunction).ToList(),
-                config.SystemMessage,
+                wireSystemMessage,
                 config.AvailableTools,
                 config.ExcludedTools,
                 config.Provider,
@@ -519,6 +563,8 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
             config.Hooks.OnSessionEnd != null ||
             config.Hooks.OnErrorOccurred != null);
 
+        var (wireSystemMessage, transformCallbacks) = ExtractTransformCallbacks(config.SystemMessage);
+
         // Create and register the session before issuing the RPC so that
         // events emitted by the CLI (e.g. session.start) are not dropped.
         var session = new CopilotSession(sessionId, connection.Rpc, _logger);
@@ -532,6 +578,10 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
         {
             session.RegisterHooks(config.Hooks);
         }
+        if (transformCallbacks != null)
+        {
+            session.RegisterTransformCallbacks(transformCallbacks);
+        }
         if (config.OnEvent != null)
         {
             session.On(config.OnEvent);
@@ -548,7 +598,7 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
                 config.Model,
                 config.ReasoningEffort,
                 config.Tools?.Select(ToolDefinition.FromAIFunction).ToList(),
-                config.SystemMessage,
+                wireSystemMessage,
                 config.AvailableTools,
                 config.ExcludedTools,
                 config.Provider,
@@ -1222,6 +1272,7 @@ private async Task<Connection> ConnectToServerAsync(Process? cliProcess, string?
         rpc.AddLocalRpcMethod("permission.request", handler.OnPermissionRequestV2);
         rpc.AddLocalRpcMethod("userInput.request", handler.OnUserInputRequest);
         rpc.AddLocalRpcMethod("hooks.invoke", handler.OnHooksInvoke);
+        rpc.AddLocalRpcMethod("systemMessage.transform", handler.OnSystemMessageTransform);
         rpc.StartListening();
 
         // Transition state to Disconnected if the JSON-RPC connection drops
@@ -1350,6 +1401,12 @@ public async Task<HooksInvokeResponse> OnHooksInvoke(string sessionId, string ho
             return new HooksInvokeResponse(output);
         }
 
+        public async Task<SystemMessageTransformRpcResponse> OnSystemMessageTransform(string sessionId, JsonElement sections)
+        {
+            var session = client.GetSession(sessionId) ?? throw new ArgumentException($"Unknown session {sessionId}");
+            return await session.HandleSystemMessageTransformAsync(sections);
+        }
+
         // Protocol v2 backward-compatibility adapters
 
         public async Task<ToolCallResponseV2> OnToolCallV2(string sessionId,
@@ -1683,9 +1740,9 @@ private static LogLevel MapLevel(TraceEventType eventType)
     [JsonSerializable(typeof(ProviderConfig))]
     [JsonSerializable(typeof(ResumeSessionRequest))]
     [JsonSerializable(typeof(ResumeSessionResponse))]
-    [JsonSerializable(typeof(SectionOverride))]
     [JsonSerializable(typeof(SessionMetadata))]
     [JsonSerializable(typeof(SystemMessageConfig))]
+    [JsonSerializable(typeof(SystemMessageTransformRpcResponse))]
     [JsonSerializable(typeof(ToolCallResponseV2))]
     [JsonSerializable(typeof(ToolDefinition))]
     [JsonSerializable(typeof(ToolResultAIContent))]

dotnet/src/Session.cs

@@ -65,6 +65,8 @@ public sealed partial class CopilotSession : IAsyncDisposable
 
     private SessionHooks? _hooks;
     private readonly SemaphoreSlim _hooksLock = new(1, 1);
+    private Dictionary<string, Func<string, Task<string>>>? _transformCallbacks;
+    private readonly SemaphoreSlim _transformCallbacksLock = new(1, 1);
     private SessionRpc? _sessionRpc;
     private int _isDisposed;
 
@@ -653,6 +655,72 @@ internal void RegisterHooks(SessionHooks hooks)
         };
     }
 
+    /// <summary>
+    /// Registers transform callbacks for system message sections.
+    /// </summary>
+    /// <param name="callbacks">The transform callbacks keyed by section identifier.</param>
+    internal void RegisterTransformCallbacks(Dictionary<string, Func<string, Task<string>>>? callbacks)
+    {
+        _transformCallbacksLock.Wait();
+        try
+        {
+            _transformCallbacks = callbacks;
+        }
+        finally
+        {
+            _transformCallbacksLock.Release();
+        }
+    }
+
+    /// <summary>
+    /// Handles a systemMessage.transform RPC call from the Copilot CLI.
+    /// </summary>
+    /// <param name="sections">The raw JSON element containing sections to transform.</param>
+    /// <returns>A task that resolves with the transformed sections.</returns>
+    internal async Task<SystemMessageTransformRpcResponse> HandleSystemMessageTransformAsync(JsonElement sections)
+    {
+        Dictionary<string, Func<string, Task<string>>>? callbacks;
+        await _transformCallbacksLock.WaitAsync();
+        try
+        {
+            callbacks = _transformCallbacks;
+        }
+        finally
+        {
+            _transformCallbacksLock.Release();
+        }
+
+        var parsed = JsonSerializer.Deserialize(
+            sections.GetRawText(),
+            SessionJsonContext.Default.DictionaryStringSystemMessageTransformSection) ?? new();
+
+        var result = new Dictionary<string, SystemMessageTransformSection>();
+        foreach (var (sectionId, data) in parsed)
+        {
+            Func<string, Task<string>>? callback = null;
+            callbacks?.TryGetValue(sectionId, out callback);
+
+            if (callback != null)
+            {
+                try
+                {
+                    var transformed = await callback(data.Content ?? "");
+                    result[sectionId] = new SystemMessageTransformSection { Content = transformed };
+                }
+                catch
+                {
+                    result[sectionId] = new SystemMessageTransformSection { Content = data.Content ?? "" };
+                }
+            }
+            else
+            {
+                result[sectionId] = new SystemMessageTransformSection { Content = data.Content ?? "" };
+            }
+        }
+
+        return new SystemMessageTransformRpcResponse { Sections = result };
+    }
+
     /// <summary>
     /// Gets the complete list of messages and events in the session.
     /// </summary>
@@ -890,5 +958,8 @@ internal record SessionDestroyRequest
     [JsonSerializable(typeof(SessionEndHookOutput))]
     [JsonSerializable(typeof(ErrorOccurredHookInput))]
     [JsonSerializable(typeof(ErrorOccurredHookOutput))]
+    [JsonSerializable(typeof(SystemMessageTransformSection))]
+    [JsonSerializable(typeof(SystemMessageTransformRpcResponse))]
+    [JsonSerializable(typeof(Dictionary<string, SystemMessageTransformSection>))]
     internal partial class SessionJsonContext : JsonSerializerContext;
 }

dotnet/src/Types.cs

@@ -991,7 +991,10 @@ public enum SectionOverrideAction
     Append,
     /// <summary>Prepend content before the existing section.</summary>
     [JsonStringEnumMemberName("prepend")]
-    Prepend
+    Prepend,
+    /// <summary>Transform the section content via a callback.</summary>
+    [JsonStringEnumMemberName("transform")]
+    Transform
 }
 
 /// <summary>
@@ -1000,14 +1003,24 @@ public enum SectionOverrideAction
 public class SectionOverride
 {
     /// <summary>
-    /// The operation to perform on this section.
+    /// The operation to perform on this section. Ignored when Transform is set.
     /// </summary>
-    public SectionOverrideAction Action { get; set; }
+    [JsonPropertyName("action")]
+    public SectionOverrideAction? Action { get; set; }
 
     /// <summary>
     /// Content for the override. Optional for all actions. Ignored for remove.
     /// </summary>
+    [JsonPropertyName("content")]
     public string? Content { get; set; }
+
+    /// <summary>
+    /// Transform callback. When set, takes precedence over Action.
+    /// Receives current section content, returns transformed content.
+    /// Not serialized — the SDK handles this locally.
+    /// </summary>
+    [JsonIgnore]
+    public Func<string, Task<string>>? Transform { get; set; }
 }
 
 /// <summary>
@@ -2106,6 +2119,30 @@ public class SetForegroundSessionResponse
     public string? Error { get; set; }
 }
 
+/// <summary>
+/// Content data for a single system prompt section in a transform RPC call.
+/// </summary>
+public class SystemMessageTransformSection
+{
+    /// <summary>
+    /// The content of the section.
+    /// </summary>
+    [JsonPropertyName("content")]
+    public string? Content { get; set; }
+}
+
+/// <summary>
+/// Response to a systemMessage.transform RPC call.
+/// </summary>
+public class SystemMessageTransformRpcResponse
+{
+    /// <summary>
+    /// The transformed sections keyed by section identifier.
+    /// </summary>
+    [JsonPropertyName("sections")]
+    public Dictionary<string, SystemMessageTransformSection>? Sections { get; set; }
+}
+
 [JsonSourceGenerationOptions(
     JsonSerializerDefaults.Web,
     AllowOutOfOrderMetadataProperties = true,