Add fine-grained system prompt customization (customize mode)

Add a new 'customize' mode for systemMessage configuration, enabling
SDK consumers to selectively override individual sections of the CLI
system prompt while preserving the rest. This sits between the existing
'append' and 'replace' modes.

9 configurable sections: identity, tone, tool_efficiency,
environment_context, code_change_rules, guidelines, safety,
tool_instructions, custom_instructions.

4 override actions per section: replace, remove, append, prepend.

Unknown section IDs are handled gracefully: content-bearing overrides
are appended to additional instructions with a warning, and remove
on unknown sections is silently ignored.

Types and constants added to all 4 SDK languages (TypeScript, Python,
Go, .NET). Documentation updated across all READMEs and getting-started
guide.

Companion runtime PR: github/copilot-agent-runtime#4751

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

Author: MackinnonBuck

docs/getting-started.md

@@ -1245,7 +1245,7 @@ const session = await client.createSession({
 
 ### Customize the System Message
 
-Control the AI's behavior and personality:
+Control the AI's behavior and personality by appending instructions:
 
 ```typescript
 const session = await client.createSession({
@@ -1255,6 +1255,28 @@ const session = await client.createSession({
 });
 ```
 
+For more fine-grained control, use `mode: "customize"` to override individual sections of the system prompt while preserving the rest:
+
+```typescript
+const session = await client.createSession({
+    systemMessage: {
+        mode: "customize",
+        sections: {
+            tone: { action: "replace", content: "Respond in a warm, professional tone. Be thorough in explanations." },
+            code_change_rules: { action: "remove" },
+            guidelines: { action: "append", content: "\n* Always cite data sources" },
+        },
+        content: "Focus on financial analysis and reporting.",
+    },
+});
+```
+
+Available section IDs: `identity`, `tone`, `tool_efficiency`, `environment_context`, `code_change_rules`, `guidelines`, `safety`, `tool_instructions`, `custom_instructions`.
+
+Each override supports four actions: `replace`, `remove`, `append`, and `prepend`. Unknown section IDs are handled gracefully — content is appended to additional instructions and a warning is emitted; `remove` on unknown sections is silently ignored.
+
+See the language-specific SDK READMEs for examples in [TypeScript](../nodejs/README.md), [Python](../python/README.md), [Go](../go/README.md), and [C#](../dotnet/README.md).
+
 ---
 
 ## Connecting to an External CLI Server

dotnet/README.md

@@ -469,6 +469,34 @@ var session = await client.CreateSessionAsync(new SessionConfig
 });
 ```
 
+#### Customize Mode
+
+Use `Mode = SystemMessageMode.Customize` to selectively override individual sections of the prompt while preserving the rest:
+
+```csharp
+var session = await client.CreateSessionAsync(new SessionConfig
+{
+    Model = "gpt-5",
+    SystemMessage = new SystemMessageConfig
+    {
+        Mode = SystemMessageMode.Customize,
+        Sections = new Dictionary<string, SectionOverride>
+        {
+            [SystemPromptSections.Tone] = new() { Action = SectionOverrideAction.Replace, Content = "Respond in a warm, professional tone. Be thorough in explanations." },
+            [SystemPromptSections.CodeChangeRules] = new() { Action = SectionOverrideAction.Remove },
+            [SystemPromptSections.Guidelines] = new() { Action = SectionOverrideAction.Append, Content = "\n* Always cite data sources" },
+        },
+        Content = "Focus on financial analysis and reporting."
+    }
+});
+```
+
+Available section IDs are defined as constants on `SystemPromptSections`: `Identity`, `Tone`, `ToolEfficiency`, `EnvironmentContext`, `CodeChangeRules`, `Guidelines`, `Safety`, `ToolInstructions`, `CustomInstructions`.
+
+Each section override supports four actions: `Replace`, `Remove`, `Append`, and `Prepend`. Unknown section IDs are handled gracefully: content is appended to additional instructions, and `Remove` overrides are silently ignored.
+
+#### Replace Mode
+
 For full control (removes all guardrails), use `Mode = SystemMessageMode.Replace`:
 
 ```csharp

dotnet/src/Client.cs

@@ -1646,6 +1646,7 @@ 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(ToolCallResponseV2))]

dotnet/src/SdkProtocolVersion.cs

@@ -16,8 +16,5 @@ internal static class SdkProtocolVersion
     /// <summary>
     /// Gets the SDK protocol version.
     /// </summary>
-    public static int GetVersion()
-    {
-        return Version;
-    }
+    public static int GetVersion() => Version;
 }

dotnet/src/Types.cs

@@ -912,7 +912,71 @@ public enum SystemMessageMode
     Append,
     /// <summary>Replace the default system message entirely.</summary>
     [JsonStringEnumMemberName("replace")]
-    Replace
+    Replace,
+    /// <summary>Override individual sections of the system prompt.</summary>
+    [JsonStringEnumMemberName("customize")]
+    Customize
+}
+
+/// <summary>
+/// Specifies the operation to perform on a system prompt section.
+/// </summary>
+[JsonConverter(typeof(JsonStringEnumConverter<SectionOverrideAction>))]
+public enum SectionOverrideAction
+{
+    /// <summary>Replace the section content entirely.</summary>
+    [JsonStringEnumMemberName("replace")]
+    Replace,
+    /// <summary>Remove the section from the prompt.</summary>
+    [JsonStringEnumMemberName("remove")]
+    Remove,
+    /// <summary>Append content after the existing section.</summary>
+    [JsonStringEnumMemberName("append")]
+    Append,
+    /// <summary>Prepend content before the existing section.</summary>
+    [JsonStringEnumMemberName("prepend")]
+    Prepend
+}
+
+/// <summary>
+/// Override operation for a single system prompt section.
+/// </summary>
+public class SectionOverride
+{
+    /// <summary>
+    /// The operation to perform on this section.
+    /// </summary>
+    public SectionOverrideAction Action { get; set; }
+
+    /// <summary>
+    /// Content for the override. Optional for all actions. Ignored for remove.
+    /// </summary>
+    public string? Content { get; set; }
+}
+
+/// <summary>
+/// Known system prompt section identifiers for the "customize" mode.
+/// </summary>
+public static class SystemPromptSections
+{
+    /// <summary>Agent identity preamble and mode statement.</summary>
+    public const string Identity = "identity";
+    /// <summary>Response style, conciseness rules, output formatting preferences.</summary>
+    public const string Tone = "tone";
+    /// <summary>Tool usage patterns, parallel calling, batching guidelines.</summary>
+    public const string ToolEfficiency = "tool_efficiency";
+    /// <summary>CWD, OS, git root, directory listing, available tools.</summary>
+    public const string EnvironmentContext = "environment_context";
+    /// <summary>Coding rules, linting/testing, ecosystem tools, style.</summary>
+    public const string CodeChangeRules = "code_change_rules";
+    /// <summary>Tips, behavioral best practices, behavioral guidelines.</summary>
+    public const string Guidelines = "guidelines";
+    /// <summary>Environment limitations, prohibited actions, security policies.</summary>
+    public const string Safety = "safety";
+    /// <summary>Per-tool usage instructions.</summary>
+    public const string ToolInstructions = "tool_instructions";
+    /// <summary>Repository and organization custom instructions.</summary>
+    public const string CustomInstructions = "custom_instructions";
 }
 
 /// <summary>
@@ -921,13 +985,21 @@ public enum SystemMessageMode
 public class SystemMessageConfig
 {
     /// <summary>
-    /// How the system message is applied (append or replace).
+    /// How the system message is applied (append, replace, or customize).
     /// </summary>
     public SystemMessageMode? Mode { get; set; }
+
     /// <summary>
-    /// Content of the system message.
+    /// Content of the system message. Used by append and replace modes.
+    /// In customize mode, additional content appended after all sections.
     /// </summary>
     public string? Content { get; set; }
+
+    /// <summary>
+    /// Section-level overrides for customize mode.
+    /// Keys are section identifiers (see <see cref="SystemPromptSections"/>).
+    /// </summary>
+    public Dictionary<string, SectionOverride>? Sections { get; set; }
 }
 
 /// <summary>
@@ -2005,6 +2077,7 @@ public class SetForegroundSessionResponse
 [JsonSerializable(typeof(SessionLifecycleEvent))]
 [JsonSerializable(typeof(SessionLifecycleEventMetadata))]
 [JsonSerializable(typeof(SessionListFilter))]
+[JsonSerializable(typeof(SectionOverride))]
 [JsonSerializable(typeof(SessionMetadata))]
 [JsonSerializable(typeof(SetForegroundSessionResponse))]
 [JsonSerializable(typeof(SystemMessageConfig))]

go/README.md

@@ -148,7 +148,10 @@ Event types: `SessionLifecycleCreated`, `SessionLifecycleDeleted`, `SessionLifec
 - `ReasoningEffort` (string): Reasoning effort level for models that support it ("low", "medium", "high", "xhigh"). Use `ListModels()` to check which models support this option.
 - `SessionID` (string): Custom session ID
 - `Tools` ([]Tool): Custom tools exposed to the CLI
-- `SystemMessage` (\*SystemMessageConfig): System message configuration
+- `SystemMessage` (\*SystemMessageConfig): System message configuration. Supports three modes:
+  - **append** (default): Appends `Content` after the SDK-managed prompt
+  - **replace**: Replaces the entire prompt with `Content`
+  - **customize**: Selectively override individual sections via `Sections` map (keys: `SectionIdentity`, `SectionTone`, `SectionToolEfficiency`, `SectionEnvironmentContext`, `SectionCodeChangeRules`, `SectionGuidelines`, `SectionSafety`, `SectionToolInstructions`, `SectionCustomInstructions`; values: `SectionOverride` with `Action` and optional `Content`)
 - `Provider` (\*ProviderConfig): Custom API provider configuration (BYOK). See [Custom Providers](#custom-providers) section.
 - `Streaming` (bool): Enable streaming delta events
 - `InfiniteSessions` (\*InfiniteSessionConfig): Automatic context compaction configuration

go/types.go

@@ -81,6 +81,27 @@ func Float64(v float64) *float64 {
 	return &v
 }
 
+// Known system prompt section identifiers for the "customize" mode.
+const (
+	SectionIdentity           = "identity"
+	SectionTone               = "tone"
+	SectionToolEfficiency     = "tool_efficiency"
+	SectionEnvironmentContext = "environment_context"
+	SectionCodeChangeRules    = "code_change_rules"
+	SectionGuidelines         = "guidelines"
+	SectionSafety             = "safety"
+	SectionToolInstructions   = "tool_instructions"
+	SectionCustomInstructions = "custom_instructions"
+)
+
+// SectionOverride defines an override operation for a single system prompt section.
+type SectionOverride struct {
+	// Action is the operation to perform: "replace", "remove", "append", or "prepend".
+	Action string `json:"action"`
+	// Content for the override. Optional for all actions. Ignored for "remove".
+	Content string `json:"content,omitempty"`
+}
+
 // SystemMessageAppendConfig is append mode: use CLI foundation with optional appended content.
 type SystemMessageAppendConfig struct {
 	// Mode is optional, defaults to "append"
@@ -99,11 +120,15 @@ type SystemMessageReplaceConfig struct {
 }
 
 // SystemMessageConfig represents system message configuration for session creation.
-// Use SystemMessageAppendConfig for default behavior, SystemMessageReplaceConfig for full control.
-// In Go, use one struct or the other based on your needs.
+//   - Append mode (default): SDK foundation + optional custom content
+//   - Replace mode: Full control, caller provides entire system message
+//   - Customize mode: Section-level overrides with graceful fallback
+//
+// In Go, use one struct and set fields appropriate for the desired mode.
 type SystemMessageConfig struct {
-	Mode    string `json:"mode,omitempty"`
-	Content string `json:"content,omitempty"`
+	Mode     string                     `json:"mode,omitempty"`
+	Content  string                     `json:"content,omitempty"`
+	Sections map[string]SectionOverride `json:"sections,omitempty"`
 }
 
 // PermissionRequestResultKind represents the kind of a permission request result.

nodejs/README.md

@@ -443,7 +443,45 @@ const session = await client.createSession({
 });
 ```
 
-The SDK auto-injects environment context, tool instructions, and security guardrails. The default CLI persona is preserved, and your `content` is appended after SDK-managed sections. To change the persona or fully redefine the prompt, use `mode: "replace"`.
+The SDK auto-injects environment context, tool instructions, and security guardrails. The default CLI persona is preserved, and your `content` is appended after SDK-managed sections. To change the persona or fully redefine the prompt, use `mode: "replace"` or `mode: "customize"`.
+
+#### Customize Mode
+
+Use `mode: "customize"` to selectively override individual sections of the prompt while preserving the rest:
+
+```typescript
+import { SYSTEM_PROMPT_SECTIONS } from "@anthropic-ai/sdk";
+import type { SectionOverride, SystemPromptSection } from "@anthropic-ai/sdk";
+
+const session = await client.createSession({
+    model: "gpt-5",
+    systemMessage: {
+        mode: "customize",
+        sections: {
+            // Replace the tone/style section
+            tone: { action: "replace", content: "Respond in a warm, professional tone. Be thorough in explanations." },
+            // Remove coding-specific rules
+            code_change_rules: { action: "remove" },
+            // Append to existing guidelines
+            guidelines: { action: "append", content: "\n* Always cite data sources" },
+        },
+        // Additional instructions appended after all sections
+        content: "Focus on financial analysis and reporting.",
+    },
+});
+```
+
+Available section IDs: `identity`, `tone`, `tool_efficiency`, `environment_context`, `code_change_rules`, `guidelines`, `safety`, `tool_instructions`, `custom_instructions`. Use the `SYSTEM_PROMPT_SECTIONS` constant for descriptions of each section.
+
+Each section override supports four actions:
+- **`replace`** — Replace the section content entirely
+- **`remove`** — Remove the section from the prompt
+- **`append`** — Add content after the existing section
+- **`prepend`** — Add content before the existing section
+
+Unknown section IDs are handled gracefully: content from `replace`/`append`/`prepend` overrides is appended to additional instructions, and `remove` overrides are silently ignored.
+
+#### Replace Mode
 
 For full control (removes all guardrails), use `mode: "replace"`:
 

nodejs/src/index.ts

@@ -10,7 +10,7 @@
 
 export { CopilotClient } from "./client.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
-export { defineTool, approveAll } from "./types.js";
+export { defineTool, approveAll, SYSTEM_PROMPT_SECTIONS } from "./types.js";
 export type {
     ConnectionState,
     CopilotClientOptions,
@@ -31,6 +31,7 @@ export type {
     PermissionRequest,
     PermissionRequestResult,
     ResumeSessionConfig,
+    SectionOverride,
     SessionConfig,
     SessionEvent,
     SessionEventHandler,
@@ -44,7 +45,9 @@ export type {
     SessionMetadata,
     SystemMessageAppendConfig,
     SystemMessageConfig,
+    SystemMessageCustomizeConfig,
     SystemMessageReplaceConfig,
+    SystemPromptSection,
     Tool,
     ToolHandler,
     ToolInvocation,