@github/copilot-sdk 0.1.33-unstable.1 → 0.2.0

package/dist/index.d.ts

@@ -5,5 +5,5 @@
  */
 export { CopilotClient } from "./client.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
-export { defineTool, approveAll } from "./types.js";
-export type { ConnectionState, CopilotClientOptions, CustomAgentConfig, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, MCPLocalServerConfig, MCPRemoteServerConfig, MCPServerConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ResumeSessionConfig, SessionConfig, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventType, SessionLifecycleHandler, SessionContext, SessionListFilter, SessionMetadata, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageReplaceConfig, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export { defineTool, approveAll, SYSTEM_PROMPT_SECTIONS } from "./types.js";
+export type { ConnectionState, CopilotClientOptions, CustomAgentConfig, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, MCPLocalServerConfig, MCPRemoteServerConfig, MCPServerConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionConfig, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventType, SessionLifecycleHandler, SessionContext, SessionListFilter, SessionMetadata, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemPromptSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";

package/dist/index.js

@@ -1,9 +1,10 @@
 import { CopilotClient } from "./client.js";
 import { CopilotSession } from "./session.js";
-import { defineTool, approveAll } from "./types.js";
+import { defineTool, approveAll, SYSTEM_PROMPT_SECTIONS } from "./types.js";
 export {
   CopilotClient,
   CopilotSession,
+  SYSTEM_PROMPT_SECTIONS,
   approveAll,
   defineTool
 };

package/dist/session.d.ts

@@ -4,7 +4,8 @@
  */
 import type { MessageConnection } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
-import type { MessageOptions, PermissionHandler, PermissionRequestResult, SessionEvent, SessionEventHandler, SessionEventType, SessionHooks, Tool, ToolHandler, TypedSessionEventHandler, UserInputHandler, UserInputResponse } from "./types.js";
+import type { MessageOptions, PermissionHandler, PermissionRequestResult, ReasoningEffort, SectionTransformFn, SessionEvent, SessionEventHandler, SessionEventType, SessionHooks, Tool, ToolHandler, TraceContextProvider, TypedSessionEventHandler, UserInputHandler, UserInputResponse } from "./types.js";
+export declare const NO_RESULT_PERMISSION_V2_ERROR = "Permission handlers cannot return 'no-result' when connected to a protocol v2 server.";
 /** Assistant message event - the final response from the assistant. */
 export type AssistantMessageEvent = Extract<SessionEvent, {
     type: "assistant.message";
@@ -37,23 +38,26 @@ export type AssistantMessageEvent = Extract<SessionEvent, {
 export declare class CopilotSession {
     readonly sessionId: string;
     private connection;
-    private readonly _workspacePath?;
+    private _workspacePath?;
     private eventHandlers;
     private typedEventHandlers;
     private toolHandlers;
     private permissionHandler?;
     private userInputHandler?;
     private hooks?;
+    private transformCallbacks?;
     private _rpc;
+    private traceContextProvider?;
     /**
      * Creates a new CopilotSession instance.
      *
      * @param sessionId - The unique identifier for this session
      * @param connection - The JSON-RPC message connection to the Copilot CLI
      * @param workspacePath - Path to the session workspace directory (when infinite sessions enabled)
+     * @param traceContextProvider - Optional callback to get W3C Trace Context for outbound RPCs
      * @internal This constructor is internal. Use {@link CopilotClient.createSession} to create sessions.
      */
-    constructor(sessionId: string, connection: MessageConnection, _workspacePath?: string | undefined);
+    constructor(sessionId: string, connection: MessageConnection, _workspacePath?: string | undefined, traceContextProvider?: TraceContextProvider);
     /**
      * Typed session-scoped RPC methods.
      */
@@ -226,6 +230,28 @@ export declare class CopilotSession {
      * @internal This method is typically called internally when creating a session.
      */
     registerHooks(hooks?: SessionHooks): void;
+    /**
+     * 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?: Map<string, SectionTransformFn>): void;
+    /**
+     * 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.
+     */
+    _handleSystemMessageTransform(sections: Record<string, {
+        content: string;
+    }>): Promise<{
+        sections: Record<string, {
+            content: string;
+        }>;
+    }>;
     /**
      * Handles a permission request in the v2 protocol format (synchronous RPC).
      * Used as a back-compat adapter when connected to a v2 server.
@@ -332,13 +358,17 @@ export declare class CopilotSession {
      * The new model takes effect for the next message. Conversation history is preserved.
      *
      * @param model - Model ID to switch to
+     * @param options - Optional settings for the new model
      *
      * @example
      * ```typescript
      * await session.setModel("gpt-4.1");
+     * await session.setModel("claude-sonnet-4.6", { reasoningEffort: "high" });
      * ```
      */
-    setModel(model: string): Promise<void>;
+    setModel(model: string, options?: {
+        reasoningEffort?: ReasoningEffort;
+    }): Promise<void>;
     /**
      * Log a message to the session timeline.
      * The message appears in the session event stream and is visible to SDK consumers

package/dist/session.js

@@ -1,5 +1,7 @@
 import { ConnectionError, ResponseError } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
+import { getTraceContext } from "./telemetry.js";
+const NO_RESULT_PERMISSION_V2_ERROR = "Permission handlers cannot return 'no-result' when connected to a protocol v2 server.";
 class CopilotSession {
   /**
    * Creates a new CopilotSession instance.
@@ -7,12 +9,14 @@ class CopilotSession {
    * @param sessionId - The unique identifier for this session
    * @param connection - The JSON-RPC message connection to the Copilot CLI
    * @param workspacePath - Path to the session workspace directory (when infinite sessions enabled)
+   * @param traceContextProvider - Optional callback to get W3C Trace Context for outbound RPCs
    * @internal This constructor is internal. Use {@link CopilotClient.createSession} to create sessions.
    */
-  constructor(sessionId, connection, _workspacePath) {
+  constructor(sessionId, connection, _workspacePath, traceContextProvider) {
     this.sessionId = sessionId;
     this.connection = connection;
     this._workspacePath = _workspacePath;
+    this.traceContextProvider = traceContextProvider;
   }
   eventHandlers = /* @__PURE__ */ new Set();
   typedEventHandlers = /* @__PURE__ */ new Map();
@@ -20,7 +24,9 @@ class CopilotSession {
   permissionHandler;
   userInputHandler;
   hooks;
+  transformCallbacks;
   _rpc = null;
+  traceContextProvider;
   /**
    * Typed session-scoped RPC methods.
    */
@@ -58,6 +64,7 @@ class CopilotSession {
    */
   async send(options) {
     const response = await this.connection.sendRequest("session.send", {
+      ...await getTraceContext(this.traceContextProvider),
       sessionId: this.sessionId,
       prompt: options.prompt,
       attachments: options.attachments,
@@ -187,9 +194,19 @@ class CopilotSession {
       const { requestId, toolName } = event.data;
       const args = event.data.arguments;
       const toolCallId = event.data.toolCallId;
+      const traceparent = event.data.traceparent;
+      const tracestate = event.data.tracestate;
       const handler = this.toolHandlers.get(toolName);
       if (handler) {
-        void this._executeToolAndRespond(requestId, toolName, toolCallId, args, handler);
+        void this._executeToolAndRespond(
+          requestId,
+          toolName,
+          toolCallId,
+          args,
+          handler,
+          traceparent,
+          tracestate
+        );
       }
     } else if (event.type === "permission.requested") {
       const { requestId, permissionRequest } = event.data;
@@ -202,13 +219,15 @@ class CopilotSession {
    * Executes a tool handler and sends the result back via RPC.
    * @internal
    */
-  async _executeToolAndRespond(requestId, toolName, toolCallId, args, handler) {
+  async _executeToolAndRespond(requestId, toolName, toolCallId, args, handler, traceparent, tracestate) {
     try {
       const rawResult = await handler(args, {
         sessionId: this.sessionId,
         toolCallId,
         toolName,
-        arguments: args
+        arguments: args,
+        traceparent,
+        tracestate
       });
       let result;
       if (rawResult == null) {
@@ -239,6 +258,9 @@ class CopilotSession {
       const result = await this.permissionHandler(permissionRequest, {
         sessionId: this.sessionId
       });
+      if (result.kind === "no-result") {
+        return;
+      }
       await this.rpc.permissions.handlePendingPermissionRequest({ requestId, result });
     } catch (_error) {
       try {
@@ -319,6 +341,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.
@@ -335,8 +391,14 @@ class CopilotSession {
       const result = await this.permissionHandler(request, {
         sessionId: this.sessionId
       });
+      if (result.kind === "no-result") {
+        throw new Error(NO_RESULT_PERMISSION_V2_ERROR);
+      }
       return result;
-    } catch (_error) {
+    } catch (error) {
+      if (error instanceof Error && error.message === NO_RESULT_PERMISSION_V2_ERROR) {
+        throw error;
+      }
       return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
     }
   }
@@ -492,14 +554,16 @@ class CopilotSession {
    * The new model takes effect for the next message. Conversation history is preserved.
    *
    * @param model - Model ID to switch to
+   * @param options - Optional settings for the new model
    *
    * @example
    * ```typescript
    * await session.setModel("gpt-4.1");
+   * await session.setModel("claude-sonnet-4.6", { reasoningEffort: "high" });
    * ```
    */
-  async setModel(model) {
-    await this.rpc.model.switchTo({ modelId: model });
+  async setModel(model, options) {
+    await this.rpc.model.switchTo({ modelId: model, ...options });
   }
   /**
    * Log a message to the session timeline.
@@ -522,5 +586,6 @@ class CopilotSession {
   }
 }
 export {
-  CopilotSession
+  CopilotSession,
+  NO_RESULT_PERMISSION_V2_ERROR
 };

package/dist/telemetry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Trace-context helpers.
+ *
+ * The SDK does not depend on any OpenTelemetry packages.  Instead, users
+ * provide an {@link TraceContextProvider} callback via client options.
+ *
+ * @module telemetry
+ */
+import type { TraceContext, TraceContextProvider } from "./types.js";
+/**
+ * Calls the user-provided {@link TraceContextProvider} to obtain the current
+ * W3C Trace Context.  Returns `{}` when no provider is configured.
+ */
+export declare function getTraceContext(provider?: TraceContextProvider): Promise<TraceContext>;

package/dist/telemetry.js

@@ -0,0 +1,11 @@
+async function getTraceContext(provider) {
+  if (!provider) return {};
+  try {
+    return await provider() ?? {};
+  } catch {
+    return {};
+  }
+}
+export {
+  getTraceContext
+};

package/dist/types.d.ts

@@ -6,6 +6,38 @@ export type SessionEvent = GeneratedSessionEvent;
 /**
  * Options for creating a CopilotClient
  */
+/**
+ * W3C Trace Context headers used for distributed trace propagation.
+ */
+export interface TraceContext {
+    traceparent?: string;
+    tracestate?: string;
+}
+/**
+ * Callback that returns the current W3C Trace Context.
+ * Wire this up to your OpenTelemetry (or other tracing) SDK to enable
+ * distributed trace propagation between your app and the Copilot CLI.
+ */
+export type TraceContextProvider = () => TraceContext | Promise<TraceContext>;
+/**
+ * Configuration for OpenTelemetry instrumentation.
+ *
+ * When provided via {@link CopilotClientOptions.telemetry}, the SDK sets
+ * the corresponding environment variables on the spawned CLI process so
+ * that the CLI's built-in OTel exporter is configured automatically.
+ */
+export interface TelemetryConfig {
+    /** OTLP HTTP endpoint URL for trace/metric export. Sets OTEL_EXPORTER_OTLP_ENDPOINT. */
+    otlpEndpoint?: string;
+    /** File path for JSON-lines trace output. Sets COPILOT_OTEL_FILE_EXPORTER_PATH. */
+    filePath?: string;
+    /** Exporter backend type: "otlp-http" or "file". Sets COPILOT_OTEL_EXPORTER_TYPE. */
+    exporterType?: string;
+    /** Instrumentation scope name. Sets COPILOT_OTEL_SOURCE_NAME. */
+    sourceName?: string;
+    /** Whether to capture message content (prompts, responses). Sets OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT. */
+    captureContent?: boolean;
+}
 export interface CopilotClientOptions {
     /**
      * Path to the CLI executable or JavaScript entry point.
@@ -56,8 +88,7 @@ export interface CopilotClientOptions {
      */
     autoStart?: boolean;
     /**
-     * Auto-restart the CLI server if it crashes
-     * @default true
+     * @deprecated This option has no effect and will be removed in a future release.
      */
     autoRestart?: boolean;
     /**
@@ -84,6 +115,37 @@ export interface CopilotClientOptions {
      * available from your custom provider.
      */
     onListModels?: () => Promise<ModelInfo[]> | ModelInfo[];
+    /**
+     * OpenTelemetry configuration for the CLI process.
+     * When provided, the corresponding OTel environment variables are set
+     * on the spawned CLI server.
+     */
+    telemetry?: TelemetryConfig;
+    /**
+     * Advanced: callback that returns the current W3C Trace Context for distributed
+     * trace propagation.  Most users do not need this — the {@link telemetry} config
+     * alone is sufficient to collect traces from the CLI.
+     *
+     * This callback is only useful when your application creates its own
+     * OpenTelemetry spans and you want them to appear in the **same** distributed
+     * trace as the CLI's spans.  The SDK calls this before `session.create`,
+     * `session.resume`, and `session.send` RPCs to inject `traceparent`/`tracestate`
+     * into the request.
+     *
+     * @example
+     * ```typescript
+     * import { propagation, context } from "@opentelemetry/api";
+     *
+     * const client = new CopilotClient({
+     *   onGetTraceContext: () => {
+     *     const carrier: Record<string, string> = {};
+     *     propagation.inject(context.active(), carrier);
+     *     return carrier;
+     *   },
+     * });
+     * ```
+     */
+    onGetTraceContext?: TraceContextProvider;
 }
 /**
  * Configuration for creating a session
@@ -109,6 +171,10 @@ export interface ToolInvocation {
     toolCallId: string;
     toolName: string;
     arguments: unknown;
+    /** W3C Trace Context traceparent from the CLI's execute_tool span. */
+    traceparent?: string;
+    /** W3C Trace Context tracestate from the CLI's execute_tool span. */
+    tracestate?: string;
 }
 export type ToolHandler<TArgs = unknown> = (args: TArgs, invocation: ToolInvocation) => Promise<unknown> | unknown;
 /**
@@ -136,6 +202,10 @@ export interface Tool<TArgs = unknown> {
      * will return an error.
      */
     overridesBuiltInTool?: boolean;
+    /**
+     * When true, the tool can execute without a permission prompt.
+     */
+    skipPermission?: boolean;
 }
 /**
  * Helper to define a tool with Zod schema and get type inference for the handler.
@@ -146,6 +216,7 @@ export declare function defineTool<T = unknown>(name: string, config: {
     parameters?: ZodSchema<T> | Record<string, unknown>;
     handler: ToolHandler<T>;
     overridesBuiltInTool?: boolean;
+    skipPermission?: boolean;
 }): Tool<T>;
 export interface ToolCallRequestPayload {
     sessionId: string;
@@ -156,6 +227,46 @@ export interface ToolCallRequestPayload {
 export interface ToolCallResponsePayload {
     result: ToolResult;
 }
+/**
+ * Known system prompt section identifiers for the "customize" mode.
+ * Each section corresponds to a distinct part of the system prompt.
+ */
+export type SystemPromptSection = "identity" | "tone" | "tool_efficiency" | "environment_context" | "code_change_rules" | "guidelines" | "safety" | "tool_instructions" | "custom_instructions" | "last_instructions";
+/** Section metadata for documentation and tooling. */
+export declare const SYSTEM_PROMPT_SECTIONS: Record<SystemPromptSection, {
+    description: string;
+}>;
+/**
+ * Transform callback for a single section: receives current content, returns new content.
+ */
+export type SectionTransformFn = (currentContent: string) => string | Promise<string>;
+/**
+ * Override action: a string literal for static overrides, or a callback for transforms.
+ *
+ * - `"replace"`: Replace section content entirely
+ * - `"remove"`: Remove the section
+ * - `"append"`: Append to existing section content
+ * - `"prepend"`: Prepend to existing section content
+ * - `function`: Transform callback — receives current section content, returns new content
+ */
+export type SectionOverrideAction = "replace" | "remove" | "append" | "prepend" | SectionTransformFn;
+/**
+ * Override operation for a single system prompt section.
+ */
+export interface SectionOverride {
+    /**
+     * The operation to perform on this section.
+     * Can be a string action or a transform callback function.
+     */
+    action: SectionOverrideAction;
+    /**
+     * Content for the override. Optional for all actions.
+     * - For replace, omitting content replaces with an empty string.
+     * - For append/prepend, content is added before/after the existing section.
+     * - Ignored for the remove action.
+     */
+    content?: string;
+}
 /**
  * Append mode: Use CLI foundation with optional appended content (default).
  */
@@ -178,12 +289,31 @@ export interface SystemMessageReplaceConfig {
      */
     content: string;
 }
+/**
+ * Customize mode: Override individual sections of the system prompt.
+ * Keeps the SDK-managed prompt structure while allowing targeted modifications.
+ */
+export interface SystemMessageCustomizeConfig {
+    mode: "customize";
+    /**
+     * Override specific sections of the system prompt by section ID.
+     * Unknown section IDs gracefully fall back: content-bearing overrides are appended
+     * to additional instructions, and "remove" on unknown sections is a silent no-op.
+     */
+    sections?: Partial<Record<SystemPromptSection, SectionOverride>>;
+    /**
+     * Additional content appended after all sections.
+     * Equivalent to append mode's content field — provided for convenience.
+     */
+    content?: string;
+}
 /**
  * System message configuration for session creation.
  * - 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
  */
-export type SystemMessageConfig = SystemMessageAppendConfig | SystemMessageReplaceConfig;
+export type SystemMessageConfig = SystemMessageAppendConfig | SystemMessageReplaceConfig | SystemMessageCustomizeConfig;
 /**
  * Permission request types from the server
  */
@@ -193,7 +323,9 @@ export interface PermissionRequest {
     [key: string]: unknown;
 }
 import type { SessionPermissionsHandlePendingPermissionRequestParams } from "./generated/rpc.js";
-export type PermissionRequestResult = SessionPermissionsHandlePendingPermissionRequestParams["result"];
+export type PermissionRequestResult = SessionPermissionsHandlePendingPermissionRequestParams["result"] | {
+    kind: "no-result";
+};
 export type PermissionHandler = (request: PermissionRequest, invocation: {
     sessionId: string;
 }) => Promise<PermissionRequestResult> | PermissionRequestResult;
@@ -613,11 +745,21 @@ export interface SessionConfig {
      * Set to `{ enabled: false }` to disable.
      */
     infiniteSessions?: InfiniteSessionConfig;
+    /**
+     * Optional event handler that is registered on the session before the
+     * session.create RPC is issued. This guarantees that early events emitted
+     * by the CLI during session creation (e.g. session.start) are delivered to
+     * the handler.
+     *
+     * Equivalent to calling `session.on(handler)` immediately after creation,
+     * but executes earlier in the lifecycle so no events are missed.
+     */
+    onEvent?: SessionEventHandler;
 }
 /**
  * Configuration for resuming a session
  */
-export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "streaming" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "hooks" | "workingDirectory" | "configDir" | "mcpServers" | "customAgents" | "agent" | "skillDirectories" | "disabledSkills" | "infiniteSessions"> & {
+export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "streaming" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "hooks" | "workingDirectory" | "configDir" | "mcpServers" | "customAgents" | "agent" | "skillDirectories" | "disabledSkills" | "infiniteSessions" | "onEvent"> & {
     /**
      * When true, skips emitting the session.resume event.
      * Useful for reconnecting to a session without triggering resume-related side effects.
@@ -670,7 +812,7 @@ export interface MessageOptions {
      */
     prompt: string;
     /**
-     * File, directory, or selection attachments
+     * File, directory, selection, or blob attachments
      */
     attachments?: Array<{
         type: "file";
@@ -695,6 +837,11 @@ export interface MessageOptions {
             };
         };
         text?: string;
+    } | {
+        type: "blob";
+        data: string;
+        mimeType: string;
+        displayName?: string;
     }>;
     /**
      * Message delivery mode

package/dist/types.js

@@ -1,8 +1,23 @@
 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" });
 export {
+  SYSTEM_PROMPT_SECTIONS,
   approveAll,
   defineTool
 };

package/docs/agent-author.md

@@ -59,11 +59,9 @@ Discovery rules:
 ## Minimal Skeleton
 
 ```js
-import { approveAll } from "@github/copilot-sdk";
 import { joinSession } from "@github/copilot-sdk/extension";
 
 await joinSession({
-    onPermissionRequest: approveAll, // Required — handle permission requests
     tools: [],                     // Optional — custom tools
     hooks: {},                     // Optional — lifecycle hooks
 });

package/docs/examples.md

@@ -7,11 +7,9 @@ A practical guide to writing extensions using the `@github/copilot-sdk` extensio
 Every extension starts with the same boilerplate:
 
 ```js
-import { approveAll } from "@github/copilot-sdk";
 import { joinSession } from "@github/copilot-sdk/extension";
 
 const session = await joinSession({
-    onPermissionRequest: approveAll,
     hooks: { /* ... */ },
     tools: [ /* ... */ ],
 });
@@ -33,7 +31,6 @@ Use `session.log()` to surface messages to the user in the CLI timeline:
 
 ```js
 const session = await joinSession({
-    onPermissionRequest: approveAll,
     hooks: {
         onSessionStart: async () => {
             await session.log("My extension loaded");
@@ -383,7 +380,6 @@ function copyToClipboard(text) {
 }
 
 const session = await joinSession({
-    onPermissionRequest: approveAll,
     hooks: {
         onUserPromptSubmitted: async (input) => {
             if (/\\bcopy\\b/i.test(input.prompt)) {
@@ -425,15 +421,12 @@ Correlate `tool.execution_start` / `tool.execution_complete` events by `toolCall
 ```js
 import { existsSync, watchFile, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { approveAll } from "@github/copilot-sdk";
 import { joinSession } from "@github/copilot-sdk/extension";
 
 const agentEdits = new Set(); // toolCallIds for in-flight agent edits
 const recentAgentPaths = new Set(); // paths recently written by the agent
 
-const session = await joinSession({
-    onPermissionRequest: approveAll,
-});
+const session = await joinSession();
 
 const workspace = session.workspacePath; // e.g. ~/.copilot/session-state/<id>
 if (workspace) {
@@ -480,14 +473,11 @@ Filter out agent edits by tracking `tool.execution_start` / `tool.execution_comp
 ```js
 import { watch, readFileSync, statSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
-import { approveAll } from "@github/copilot-sdk";
 import { joinSession } from "@github/copilot-sdk/extension";
 
 const agentEditPaths = new Set();
 
-const session = await joinSession({
-    onPermissionRequest: approveAll,
-});
+const session = await joinSession();
 
 const cwd = process.cwd();
 const IGNORE = new Set(["node_modules", ".git", "dist"]);
@@ -582,7 +572,6 @@ Register `onUserInputRequest` to enable the agent's `ask_user` tool:
 
 ```js
 const session = await joinSession({
-    onPermissionRequest: approveAll,
     onUserInputRequest: async (request) => {
         // request.question has the agent's question
         // request.choices has the options (if multiple choice)
@@ -599,7 +588,6 @@ An extension that combines tools, hooks, and events.
 
 ```js
 import { execFile, exec } from "node:child_process";
-import { approveAll } from "@github/copilot-sdk";
 import { joinSession } from "@github/copilot-sdk/extension";
 
 const isWindows = process.platform === "win32";
@@ -617,7 +605,6 @@ function openInEditor(filePath) {
 }
 
 const session = await joinSession({
-    onPermissionRequest: approveAll,
     hooks: {
         onUserPromptSubmitted: async (input) => {
             if (/\\bcopy this\\b/i.test(input.prompt)) {