@github/copilot-sdk 0.1.33-preview.3 → 0.1.33-preview.4

package/README.md

@@ -473,7 +473,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 "@github/copilot-sdk";
+import type { SectionOverride, SystemPromptSection } from "@github/copilot-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`, `last_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"`:
 

package/dist/cjs/client.js

@@ -45,6 +45,30 @@ function toJsonSchema(parameters) {
   }
   return parameters;
 }
+function extractTransformCallbacks(systemMessage) {
+  if (!systemMessage || systemMessage.mode !== "customize" || !systemMessage.sections) {
+    return { wirePayload: systemMessage, transformCallbacks: void 0 };
+  }
+  const transformCallbacks = /* @__PURE__ */ new Map();
+  const wireSections = {};
+  for (const [sectionId, override] of Object.entries(systemMessage.sections)) {
+    if (!override) continue;
+    if (typeof override.action === "function") {
+      transformCallbacks.set(sectionId, override.action);
+      wireSections[sectionId] = { action: "transform" };
+    } else {
+      wireSections[sectionId] = { action: override.action, content: override.content };
+    }
+  }
+  if (transformCallbacks.size === 0) {
+    return { wirePayload: systemMessage, transformCallbacks: void 0 };
+  }
+  const wirePayload = {
+    ...systemMessage,
+    sections: wireSections
+  };
+  return { wirePayload, transformCallbacks };
+}
 function getNodeExecPath() {
   if (process.versions.bun) {
     return "node";
@@ -434,6 +458,12 @@ class CopilotClient {
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
+    const { wirePayload: wireSystemMessage, transformCallbacks } = extractTransformCallbacks(
+      config.systemMessage
+    );
+    if (transformCallbacks) {
+      session.registerTransformCallbacks(transformCallbacks);
+    }
     if (config.onEvent) {
       session.on(config.onEvent);
     }
@@ -452,7 +482,7 @@ class CopilotClient {
           overridesBuiltInTool: tool.overridesBuiltInTool,
           skipPermission: tool.skipPermission
         })),
-        systemMessage: config.systemMessage,
+        systemMessage: wireSystemMessage,
         availableTools: config.availableTools,
         excludedTools: config.excludedTools,
         provider: config.provider,
@@ -529,6 +559,12 @@ class CopilotClient {
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
+    const { wirePayload: wireSystemMessage, transformCallbacks } = extractTransformCallbacks(
+      config.systemMessage
+    );
+    if (transformCallbacks) {
+      session.registerTransformCallbacks(transformCallbacks);
+    }
     if (config.onEvent) {
       session.on(config.onEvent);
     }
@@ -540,7 +576,7 @@ class CopilotClient {
         clientName: config.clientName,
         model: config.model,
         reasoningEffort: config.reasoningEffort,
-        systemMessage: config.systemMessage,
+        systemMessage: wireSystemMessage,
         availableTools: config.availableTools,
         excludedTools: config.excludedTools,
         tools: config.tools?.map((tool) => ({
@@ -1098,6 +1134,10 @@ stderr: ${stderrOutput}`
       "hooks.invoke",
       async (params) => await this.handleHooksInvoke(params)
     );
+    this.connection.onRequest(
+      "systemMessage.transform",
+      async (params) => await this.handleSystemMessageTransform(params)
+    );
     this.connection.onClose(() => {
       this.state = "disconnected";
     });
@@ -1161,6 +1201,16 @@ stderr: ${stderrOutput}`
     const output = await session._handleHooksInvoke(params.hookType, params.input);
     return { output };
   }
+  async handleSystemMessageTransform(params) {
+    if (!params || typeof params.sessionId !== "string" || !params.sections || typeof params.sections !== "object") {
+      throw new Error("Invalid systemMessage.transform payload");
+    }
+    const session = this.sessions.get(params.sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${params.sessionId}`);
+    }
+    return await session._handleSystemMessageTransform(params.sections);
+  }
   // ========================================================================
   // Protocol v2 backward-compatibility adapters
   // ========================================================================

package/dist/cjs/generated/rpc.js

@@ -65,7 +65,33 @@ function createSessionRpc(connection, sessionId) {
       list: async () => connection.sendRequest("session.agent.list", { sessionId }),
       getCurrent: async () => connection.sendRequest("session.agent.getCurrent", { sessionId }),
       select: async (params) => connection.sendRequest("session.agent.select", { sessionId, ...params }),
-      deselect: async () => connection.sendRequest("session.agent.deselect", { sessionId })
+      deselect: async () => connection.sendRequest("session.agent.deselect", { sessionId }),
+      reload: async () => connection.sendRequest("session.agent.reload", { sessionId })
+    },
+    /** @experimental */
+    skills: {
+      list: async () => connection.sendRequest("session.skills.list", { sessionId }),
+      enable: async (params) => connection.sendRequest("session.skills.enable", { sessionId, ...params }),
+      disable: async (params) => connection.sendRequest("session.skills.disable", { sessionId, ...params }),
+      reload: async () => connection.sendRequest("session.skills.reload", { sessionId })
+    },
+    /** @experimental */
+    mcp: {
+      list: async () => connection.sendRequest("session.mcp.list", { sessionId }),
+      enable: async (params) => connection.sendRequest("session.mcp.enable", { sessionId, ...params }),
+      disable: async (params) => connection.sendRequest("session.mcp.disable", { sessionId, ...params }),
+      reload: async () => connection.sendRequest("session.mcp.reload", { sessionId })
+    },
+    /** @experimental */
+    plugins: {
+      list: async () => connection.sendRequest("session.plugins.list", { sessionId })
+    },
+    /** @experimental */
+    extensions: {
+      list: async () => connection.sendRequest("session.extensions.list", { sessionId }),
+      enable: async (params) => connection.sendRequest("session.extensions.enable", { sessionId, ...params }),
+      disable: async (params) => connection.sendRequest("session.extensions.disable", { sessionId, ...params }),
+      reload: async () => connection.sendRequest("session.extensions.reload", { sessionId })
     },
     /** @experimental */
     compaction: {
@@ -74,6 +100,12 @@ function createSessionRpc(connection, sessionId) {
     tools: {
       handlePendingToolCall: async (params) => connection.sendRequest("session.tools.handlePendingToolCall", { sessionId, ...params })
     },
+    commands: {
+      handlePendingCommand: async (params) => connection.sendRequest("session.commands.handlePendingCommand", { sessionId, ...params })
+    },
+    ui: {
+      elicitation: async (params) => connection.sendRequest("session.ui.elicitation", { sessionId, ...params })
+    },
     permissions: {
       handlePendingPermissionRequest: async (params) => connection.sendRequest("session.permissions.handlePendingPermissionRequest", { sessionId, ...params })
     },

package/dist/cjs/index.js

@@ -20,6 +20,7 @@ var index_exports = {};
 __export(index_exports, {
   CopilotClient: () => import_client.CopilotClient,
   CopilotSession: () => import_session.CopilotSession,
+  SYSTEM_PROMPT_SECTIONS: () => import_types.SYSTEM_PROMPT_SECTIONS,
   approveAll: () => import_types.approveAll,
   defineTool: () => import_types.defineTool
 });
@@ -31,6 +32,7 @@ var import_types = require("./types.js");
 0 && (module.exports = {
   CopilotClient,
   CopilotSession,
+  SYSTEM_PROMPT_SECTIONS,
   approveAll,
   defineTool
 });

package/dist/cjs/session.js

@@ -48,6 +48,7 @@ class CopilotSession {
   permissionHandler;
   userInputHandler;
   hooks;
+  transformCallbacks;
   _rpc = null;
   traceContextProvider;
   /**
@@ -364,6 +365,40 @@ class CopilotSession {
   registerHooks(hooks) {
     this.hooks = hooks;
   }
+  /**
+   * Registers transform callbacks for system message sections.
+   *
+   * @param callbacks - Map of section ID to transform callback, or undefined to clear
+   * @internal This method is typically called internally when creating a session.
+   */
+  registerTransformCallbacks(callbacks) {
+    this.transformCallbacks = callbacks;
+  }
+  /**
+   * Handles a systemMessage.transform request from the runtime.
+   * Dispatches each section to its registered transform callback.
+   *
+   * @param sections - Map of section IDs to their current rendered content
+   * @returns A promise that resolves with the transformed sections
+   * @internal This method is for internal use by the SDK.
+   */
+  async _handleSystemMessageTransform(sections) {
+    const result = {};
+    for (const [sectionId, { content }] of Object.entries(sections)) {
+      const callback = this.transformCallbacks?.get(sectionId);
+      if (callback) {
+        try {
+          const transformed = await callback(content);
+          result[sectionId] = { content: transformed };
+        } catch (_error) {
+          result[sectionId] = { content };
+        }
+      } else {
+        result[sectionId] = { content };
+      }
+    }
+    return { sections: result };
+  }
   /**
    * Handles a permission request in the v2 protocol format (synchronous RPC).
    * Used as a back-compat adapter when connected to a v2 server.

package/dist/cjs/types.js

@@ -18,6 +18,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var types_exports = {};
 __export(types_exports, {
+  SYSTEM_PROMPT_SECTIONS: () => SYSTEM_PROMPT_SECTIONS,
   approveAll: () => approveAll,
   defineTool: () => defineTool
 });
@@ -25,9 +26,24 @@ module.exports = __toCommonJS(types_exports);
 function defineTool(name, config) {
   return { name, ...config };
 }
+const SYSTEM_PROMPT_SECTIONS = {
+  identity: { description: "Agent identity preamble and mode statement" },
+  tone: { description: "Response style, conciseness rules, output formatting preferences" },
+  tool_efficiency: { description: "Tool usage patterns, parallel calling, batching guidelines" },
+  environment_context: { description: "CWD, OS, git root, directory listing, available tools" },
+  code_change_rules: { description: "Coding rules, linting/testing, ecosystem tools, style" },
+  guidelines: { description: "Tips, behavioral best practices, behavioral guidelines" },
+  safety: { description: "Environment limitations, prohibited actions, security policies" },
+  tool_instructions: { description: "Per-tool usage instructions" },
+  custom_instructions: { description: "Repository and organization custom instructions" },
+  last_instructions: {
+    description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
+  }
+};
 const approveAll = () => ({ kind: "approved" });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  SYSTEM_PROMPT_SECTIONS,
   approveAll,
   defineTool
 });

package/dist/client.d.ts

@@ -423,6 +423,7 @@ export declare class CopilotClient {
     private handleSessionLifecycleNotification;
     private handleUserInputRequest;
     private handleHooksInvoke;
+    private handleSystemMessageTransform;
     /**
      * Handles a v2-style tool.call RPC request from the server.
      * Looks up the session and tool handler, executes it, and returns the result

package/dist/client.js

@@ -25,6 +25,30 @@ function toJsonSchema(parameters) {
   }
   return parameters;
 }
+function extractTransformCallbacks(systemMessage) {
+  if (!systemMessage || systemMessage.mode !== "customize" || !systemMessage.sections) {
+    return { wirePayload: systemMessage, transformCallbacks: void 0 };
+  }
+  const transformCallbacks = /* @__PURE__ */ new Map();
+  const wireSections = {};
+  for (const [sectionId, override] of Object.entries(systemMessage.sections)) {
+    if (!override) continue;
+    if (typeof override.action === "function") {
+      transformCallbacks.set(sectionId, override.action);
+      wireSections[sectionId] = { action: "transform" };
+    } else {
+      wireSections[sectionId] = { action: override.action, content: override.content };
+    }
+  }
+  if (transformCallbacks.size === 0) {
+    return { wirePayload: systemMessage, transformCallbacks: void 0 };
+  }
+  const wirePayload = {
+    ...systemMessage,
+    sections: wireSections
+  };
+  return { wirePayload, transformCallbacks };
+}
 function getNodeExecPath() {
   if (process.versions.bun) {
     return "node";
@@ -414,6 +438,12 @@ class CopilotClient {
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
+    const { wirePayload: wireSystemMessage, transformCallbacks } = extractTransformCallbacks(
+      config.systemMessage
+    );
+    if (transformCallbacks) {
+      session.registerTransformCallbacks(transformCallbacks);
+    }
     if (config.onEvent) {
       session.on(config.onEvent);
     }
@@ -432,7 +462,7 @@ class CopilotClient {
           overridesBuiltInTool: tool.overridesBuiltInTool,
           skipPermission: tool.skipPermission
         })),
-        systemMessage: config.systemMessage,
+        systemMessage: wireSystemMessage,
         availableTools: config.availableTools,
         excludedTools: config.excludedTools,
         provider: config.provider,
@@ -509,6 +539,12 @@ class CopilotClient {
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
+    const { wirePayload: wireSystemMessage, transformCallbacks } = extractTransformCallbacks(
+      config.systemMessage
+    );
+    if (transformCallbacks) {
+      session.registerTransformCallbacks(transformCallbacks);
+    }
     if (config.onEvent) {
       session.on(config.onEvent);
     }
@@ -520,7 +556,7 @@ class CopilotClient {
         clientName: config.clientName,
         model: config.model,
         reasoningEffort: config.reasoningEffort,
-        systemMessage: config.systemMessage,
+        systemMessage: wireSystemMessage,
         availableTools: config.availableTools,
         excludedTools: config.excludedTools,
         tools: config.tools?.map((tool) => ({
@@ -1078,6 +1114,10 @@ stderr: ${stderrOutput}`
       "hooks.invoke",
       async (params) => await this.handleHooksInvoke(params)
     );
+    this.connection.onRequest(
+      "systemMessage.transform",
+      async (params) => await this.handleSystemMessageTransform(params)
+    );
     this.connection.onClose(() => {
       this.state = "disconnected";
     });
@@ -1141,6 +1181,16 @@ stderr: ${stderrOutput}`
     const output = await session._handleHooksInvoke(params.hookType, params.input);
     return { output };
   }
+  async handleSystemMessageTransform(params) {
+    if (!params || typeof params.sessionId !== "string" || !params.sections || typeof params.sections !== "object") {
+      throw new Error("Invalid systemMessage.transform payload");
+    }
+    const session = this.sessions.get(params.sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${params.sessionId}`);
+    }
+    return await session._handleSystemMessageTransform(params.sections);
+  }
   // ========================================================================
   // Protocol v2 backward-compatibility adapters
   // ========================================================================