@github/copilot-sdk 0.3.0 → 1.0.0-beta.10

package/dist/client.js

@@ -7,16 +7,23 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   createMessageConnection,
+  ErrorCodes,
+  ResponseError,
   StreamMessageReader,
   StreamMessageWriter
 } from "vscode-jsonrpc/node.js";
-import { createServerRpc, registerClientSessionApiHandlers } from "./generated/rpc.js";
+import {
+  createServerRpc,
+  createInternalServerRpc,
+  registerClientSessionApiHandlers
+} from "./generated/rpc.js";
 import { getSdkProtocolVersion } from "./sdkProtocolVersion.js";
-import { CopilotSession, NO_RESULT_PERMISSION_V2_ERROR } from "./session.js";
+import { CopilotSession } from "./session.js";
 import { createSessionFsAdapter } from "./sessionFsProvider.js";
 import { getTraceContext } from "./telemetry.js";
+import { ToolSet } from "./toolSet.js";
 import { defaultJoinSessionPermissionHandler } from "./types.js";
-const MIN_PROTOCOL_VERSION = 2;
+const MIN_PROTOCOL_VERSION = 3;
 function isZodSchema(value) {
   return value != null && typeof value === "object" && "toJSONSchema" in value && typeof value.toJSONSchema === "function";
 }
@@ -27,6 +34,53 @@ function toJsonSchema(parameters) {
   }
   return parameters;
 }
+function toWireMcpServers(mcpServers) {
+  if (!mcpServers) return void 0;
+  return Object.fromEntries(
+    Object.entries(mcpServers).map(([name, server]) => {
+      if ("workingDirectory" in server) {
+        const { workingDirectory, ...rest } = server;
+        return [name, { ...rest, cwd: workingDirectory }];
+      }
+      return [name, server];
+    })
+  );
+}
+function toWireCustomAgents(agents) {
+  if (!agents) return void 0;
+  return agents.map((agent) => {
+    if (!agent.mcpServers) return agent;
+    const { mcpServers, ...rest } = agent;
+    return { ...rest, mcpServers: toWireMcpServers(mcpServers) };
+  });
+}
+function toWireLargeOutput(config) {
+  if (!config) return void 0;
+  const { outputDirectory, ...rest } = config;
+  const wire = { ...rest };
+  if (outputDirectory !== void 0) {
+    wire.outputDir = outputDirectory;
+  }
+  return wire;
+}
+function toolFilterListToArray(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return value instanceof ToolSet ? value.toArray() : value;
+}
+function validateToolFilterList(field, list) {
+  if (!list) {
+    return;
+  }
+  for (const entry of list) {
+    if (entry === "*") {
+      throw new Error(
+        `Invalid ${field} entry '*': there is no bare wildcard. Use one or more of \`new ToolSet().addBuiltIn('*')\`, \`.addMcp('*')\`, or \`.addCustom('*')\` to target a specific source.`
+      );
+    }
+  }
+}
 function extractTransformCallbacks(systemMessage) {
   if (!systemMessage || systemMessage.mode !== "customize" || !systemMessage.sections) {
     return { wirePayload: systemMessage, transformCallbacks: void 0 };
@@ -80,15 +134,23 @@ class CopilotClient {
   cliProcess = null;
   connection = null;
   socket = null;
-  actualPort = null;
+  runtimePort = null;
   actualHost = "localhost";
   state = "disconnected";
   sessions = /* @__PURE__ */ new Map();
   stderrBuffer = "";
   // Captures CLI stderr for error messages
+  /** Resolved connection mode chosen in the constructor. */
+  connectionConfig;
+  /** Resolved path to the runtime executable (only used for child-process kinds). */
+  resolvedCliPath;
+  /** Resolved environment passed to the spawned runtime. */
+  resolvedEnv;
   options;
   isExternalServer = false;
   forceStopping = false;
+  /** Token sent in `connect`; auto-generated when the SDK spawns its own CLI in TCP mode. */
+  effectiveConnectionToken;
   onListModels;
   onGetTraceContext;
   modelsCache = null;
@@ -96,6 +158,7 @@ class CopilotClient {
   sessionLifecycleHandlers = /* @__PURE__ */ new Set();
   typedLifecycleHandlers = /* @__PURE__ */ new Map();
   _rpc = null;
+  _internalRpc = null;
   processExitPromise = null;
   // Rejects when CLI process exits
   negotiatedProtocolVersion = null;
@@ -114,77 +177,107 @@ class CopilotClient {
     }
     return this._rpc;
   }
+  /**
+   * Internal RPC surface (e.g. handshake helpers). Not part of the public API.
+   * @internal
+   */
+  get internalRpc() {
+    if (!this.connection) {
+      throw new Error("Client is not connected. Call start() first.");
+    }
+    if (!this._internalRpc) {
+      this._internalRpc = createInternalServerRpc(this.connection);
+    }
+    return this._internalRpc;
+  }
   /**
    * Creates a new CopilotClient instance.
    *
    * @param options - Configuration options for the client
-   * @throws Error if mutually exclusive options are provided (e.g., cliUrl with useStdio or cliPath)
    *
    * @example
    * ```typescript
-   * // Default options - spawns CLI server using stdio
+   * // Default: spawns the bundled runtime over stdio
    * const client = new CopilotClient();
    *
-   * // Connect to an existing server
-   * const client = new CopilotClient({ cliUrl: "localhost:3000" });
+   * // Connect to an existing runtime
+   * const client = new CopilotClient({
+   *   connection: RuntimeConnection.forUri("localhost:3000"),
+   * });
    *
-   * // Custom CLI path with specific log level
+   * // Spawn the runtime over TCP on a chosen port
    * const client = new CopilotClient({
-   *   cliPath: "/usr/local/bin/copilot",
-   *   logLevel: "debug"
+   *   connection: RuntimeConnection.forTcp({ port: 9001 }),
+   * });
+   *
+   * // Use a custom runtime binary
+   * const client = new CopilotClient({
+   *   connection: RuntimeConnection.forStdio({ path: "/usr/local/bin/copilot" }),
+   *   logLevel: "debug",
    * });
    * ```
    */
   constructor(options = {}) {
-    if (options.cliUrl && (options.useStdio === true || options.cliPath)) {
-      throw new Error("cliUrl is mutually exclusive with useStdio and cliPath");
-    }
-    if (options.isChildProcess && (options.cliUrl || options.useStdio === false)) {
+    const conn = options._internalConnection ?? options.connection ?? { kind: "stdio" };
+    if (conn.kind === "uri" && (options.gitHubToken !== void 0 || options.useLoggedInUser !== void 0)) {
       throw new Error(
-        "isChildProcess must be used in conjunction with useStdio and not with cliUrl"
+        "gitHubToken and useLoggedInUser cannot be used with RuntimeConnection.forUri (external server manages its own auth)"
       );
     }
-    if (options.cliUrl && (options.gitHubToken || options.useLoggedInUser !== void 0)) {
-      throw new Error(
-        "gitHubToken and useLoggedInUser cannot be used with cliUrl (external server manages its own auth)"
-      );
+    if (conn.kind === "tcp" && conn.connectionToken !== void 0) {
+      if (typeof conn.connectionToken !== "string" || conn.connectionToken.length === 0) {
+        throw new Error("connectionToken must be a non-empty string");
+      }
     }
+    this.connectionConfig = conn;
     if (options.sessionFs) {
       this.validateSessionFsConfig(options.sessionFs);
     }
-    if (options.cliUrl) {
-      const { host, port } = this.parseCliUrl(options.cliUrl);
+    if (conn.kind === "uri") {
+      const { host, port } = this.parseCliUrl(conn.url);
       this.actualHost = host;
-      this.actualPort = port;
+      this.runtimePort = port;
       this.isExternalServer = true;
-    }
-    if (options.isChildProcess) {
+    } else if (conn.kind === "parent-process") {
       this.isExternalServer = true;
     }
+    if (conn.kind === "tcp") {
+      this.effectiveConnectionToken = conn.connectionToken ?? randomUUID();
+    } else if (conn.kind === "uri") {
+      this.effectiveConnectionToken = conn.connectionToken;
+    }
     this.onListModels = options.onListModels;
     this.onGetTraceContext = options.onGetTraceContext;
     this.sessionFsConfig = options.sessionFs ?? null;
     const effectiveEnv = options.env ?? process.env;
+    this.resolvedEnv = effectiveEnv;
+    this.resolvedCliPath = conn.kind === "stdio" || conn.kind === "tcp" ? conn.path ?? effectiveEnv.COPILOT_CLI_PATH ?? getBundledCliPath() : void 0;
+    const connArgs = conn.kind === "stdio" || conn.kind === "tcp" ? conn.args ?? [] : [];
+    this.connectionExtraArgs = [...connArgs];
     this.options = {
-      cliPath: options.cliUrl ? void 0 : options.cliPath || effectiveEnv.COPILOT_CLI_PATH || getBundledCliPath(),
-      cliArgs: options.cliArgs ?? [],
-      cwd: options.cwd ?? process.cwd(),
-      port: options.port || 0,
-      useStdio: options.cliUrl ? false : options.useStdio ?? true,
-      // Default to stdio unless cliUrl is provided
-      isChildProcess: options.isChildProcess ?? false,
-      cliUrl: options.cliUrl,
-      logLevel: options.logLevel || "debug",
-      autoStart: options.autoStart ?? true,
-      autoRestart: false,
-      env: effectiveEnv,
+      workingDirectory: options.workingDirectory ?? process.cwd(),
+      logLevel: options.logLevel,
       gitHubToken: options.gitHubToken,
-      // Default useLoggedInUser to false when gitHubToken is provided, otherwise true
+      // Default useLoggedInUser to false when gitHubToken is provided, otherwise true.
       useLoggedInUser: options.useLoggedInUser ?? (options.gitHubToken ? false : true),
       telemetry: options.telemetry,
-      sessionIdleTimeoutSeconds: options.sessionIdleTimeoutSeconds ?? 0
+      baseDirectory: options.baseDirectory,
+      sessionIdleTimeoutSeconds: options.sessionIdleTimeoutSeconds ?? 0,
+      enableRemoteSessions: options.enableRemoteSessions ?? false,
+      mode: options.mode ?? "copilot-cli"
     };
+    if (this.options.mode === "empty") {
+      const hasPersistence = this.options.baseDirectory !== void 0 || this.sessionFsConfig !== null || // External runtimes manage their own persistence layer; the SDK
+      // can't enforce it from here.
+      conn.kind === "uri" || conn.kind === "parent-process";
+      if (!hasPersistence) {
+        throw new Error(
+          "CopilotClient was created with mode: 'empty' but neither 'baseDirectory' nor 'sessionFs' was set. Empty mode requires an explicit per-session persistence location; pick one."
+        );
+      }
+    }
   }
+  connectionExtraArgs = [];
   /**
    * Parse CLI URL into host and port
    * Supports formats: "host:port", "http://host:port", "https://host:port", or just "port"
@@ -218,20 +311,37 @@ class CopilotClient {
       throw new Error("sessionFs.conventions must be either 'windows' or 'posix'");
     }
   }
+  setupSessionFs(session, config) {
+    if (!this.sessionFsConfig) {
+      return;
+    }
+    if (!config.createSessionFsProvider) {
+      throw new Error(
+        "createSessionFsProvider is required in session config when sessionFs is enabled in client options."
+      );
+    }
+    const provider = config.createSessionFsProvider(session);
+    if (this.sessionFsConfig.capabilities?.sqlite && !provider.sqlite) {
+      throw new Error(
+        "SessionFsConfig declares capabilities.sqlite but the provider does not implement sqlite."
+      );
+    }
+    session.clientSessionApis.sessionFs = createSessionFsAdapter(provider);
+  }
   /**
    * Starts the CLI server and establishes a connection.
    *
    * If connecting to an external server (via cliUrl), only establishes the connection.
    * Otherwise, spawns the CLI server process and then connects.
    *
-   * This method is called automatically when creating a session if `autoStart` is true (default).
+   * This method is called automatically the first time you create or resume a session.
    *
    * @returns A promise that resolves when the connection is established
    * @throws Error if the server fails to start or the connection fails
    *
    * @example
    * ```typescript
-   * const client = new CopilotClient({ autoStart: false });
+   * const client = new CopilotClient();
    * await client.start();
    * // Now ready to create sessions
    * ```
@@ -251,7 +361,8 @@ class CopilotClient {
         await this.connection.sendRequest("sessionFs.setProvider", {
           initialCwd: this.sessionFsConfig.initialCwd,
           sessionStatePath: this.sessionFsConfig.sessionStatePath,
-          conventions: this.sessionFsConfig.conventions
+          conventions: this.sessionFsConfig.conventions,
+          capabilities: this.sessionFsConfig.capabilities
         });
       }
       this.state = "connected";
@@ -325,8 +436,15 @@ class CopilotClient {
     }
     this.modelsCache = null;
     if (this.socket) {
+      const socket = this.socket;
+      this.socket = null;
       try {
-        this.socket.end();
+        if (!socket.destroyed) {
+          await new Promise((resolve) => {
+            socket.once("close", () => resolve());
+            socket.end();
+          });
+        }
       } catch (error) {
         errors.push(
           new Error(
@@ -334,11 +452,18 @@ class CopilotClient {
           )
         );
       }
-      this.socket = null;
     }
     if (this.cliProcess && !this.isExternalServer) {
+      const child = this.cliProcess;
+      this.cliProcess = null;
       try {
-        this.cliProcess.kill();
+        if (child.exitCode === null && child.signalCode === null) {
+          const exited = new Promise((resolve) => {
+            child.once("exit", () => resolve());
+          });
+          child.kill();
+          await exited;
+        }
       } catch (error) {
         errors.push(
           new Error(
@@ -346,18 +471,32 @@ class CopilotClient {
           )
         );
       }
-      this.cliProcess = null;
     }
     if (this.cliStartTimeout) {
       clearTimeout(this.cliStartTimeout);
       this.cliStartTimeout = null;
     }
     this.state = "disconnected";
-    this.actualPort = null;
+    this.runtimePort = null;
     this.stderrBuffer = "";
     this.processExitPromise = null;
     return errors;
   }
+  /**
+   * Alias for {@link stop} that lets `CopilotClient` participate in `await using`
+   * blocks for automatic cleanup.
+   *
+   * @example
+   * ```typescript
+   * await using client = new CopilotClient();
+   * const session = await client.createSession({ onPermissionRequest: approveAll });
+   * await session.sendAndWait("Hello");
+   * // client.stop() is called automatically when the block exits.
+   * ```
+   */
+  async [Symbol.asyncDispose]() {
+    await this.stop();
+  }
   /**
    * Forcefully stops the CLI server without graceful cleanup.
    *
@@ -414,7 +553,7 @@ class CopilotClient {
       this.cliStartTimeout = null;
     }
     this.state = "disconnected";
-    this.actualPort = null;
+    this.runtimePort = null;
     this.stderrBuffer = "";
     this.processExitPromise = null;
   }
@@ -422,12 +561,11 @@ class CopilotClient {
    * Creates a new conversation session with the Copilot CLI.
    *
    * Sessions maintain conversation state, handle events, and manage tool execution.
-   * If the client is not connected and `autoStart` is enabled, this will automatically
-   * start the connection.
+   * If the client is not connected, this method automatically starts the connection.
    *
    * @param config - Optional configuration for the session
    * @returns A promise that resolves with the created session
-   * @throws Error if the client is not connected and autoStart is disabled
+   * @throws Error if the client fails to start
    *
    * @example
    * ```typescript
@@ -447,66 +585,189 @@ class CopilotClient {
    * });
    * ```
    */
-  async createSession(config) {
-    if (!config?.onPermissionRequest) {
-      throw new Error(
-        "An onPermissionRequest handler is required when creating a session. For example, to allow all permissions, use { onPermissionRequest: approveAll }."
-      );
-    }
-    if (!this.connection) {
-      if (this.options.autoStart) {
-        await this.start();
-      } else {
-        throw new Error("Client not connected. Call start() first.");
+  /**
+   * Normalizes session-level tool filter options. Converts {@link ToolSet}
+   * instances to plain string arrays, rejects misuse (bare `"*"`) and the
+   * missing-availableTools case in `mode = "empty"`.
+   *
+   * The SDK always sends `toolFilterPrecedence: "excluded"` so callers can
+   * compose include + exclude lists naturally (e.g. "everything matching X
+   * except Y") regardless of mode. Allowlist-precedence is intentionally not
+   * exposed — it's available on the runtime side as a CLI-only concession to
+   * legacy behavior, but SDK consumers always get the composable semantics.
+   *
+   * @internal
+   */
+  resolveToolFilterOptions(config) {
+    const availableTools = toolFilterListToArray(config.availableTools);
+    const excludedTools = toolFilterListToArray(config.excludedTools);
+    validateToolFilterList("availableTools", availableTools);
+    validateToolFilterList("excludedTools", excludedTools);
+    if (this.options.mode === "empty") {
+      if (availableTools === void 0) {
+        throw new Error(
+          "CopilotClient is in mode: 'empty' but the session config did not specify 'availableTools'. Empty mode requires every session to explicitly opt into the tools it wants \u2014 e.g. `new ToolSet().addBuiltIn(BuiltInTools.Isolated)`."
+        );
       }
     }
-    const sessionId = config.sessionId ?? randomUUID();
-    const session = new CopilotSession(
-      sessionId,
-      this.connection,
-      void 0,
-      this.onGetTraceContext
-    );
-    session.registerTools(config.tools);
-    session.registerCommands(config.commands);
-    session.registerPermissionHandler(config.onPermissionRequest);
-    if (config.onUserInputRequest) {
-      session.registerUserInputHandler(config.onUserInputRequest);
+    return { availableTools, excludedTools, toolFilterPrecedence: "excluded" };
+  }
+  /** Mode-specific defaults spread under the caller's config (app values win). */
+  configDefaultsForMode() {
+    if (this.options.mode === "empty") {
+      return {
+        enableSessionTelemetry: false,
+        mcpOAuthTokenStorage: "in-memory",
+        skipEmbeddingRetrieval: true,
+        embeddingCacheStorage: "in-memory",
+        enableOnDemandInstructionDiscovery: false,
+        enableFileHooks: false,
+        enableHostGitOperations: false,
+        enableSessionStore: false,
+        enableSkills: false
+      };
     }
-    if (config.onElicitationRequest) {
-      session.registerElicitationHandler(config.onElicitationRequest);
+    return {};
+  }
+  /**
+   * Returns the systemMessage config to use, adjusted for the current mode.
+   * In empty mode we ensure the environment_context section is removed
+   * unless the app has already taken control of it. `append` (and
+   * unspecified) mode is promoted to `customize` so we can also strip
+   * environment_context; the caller's `content` is preserved verbatim
+   * because the runtime appends it as additional instructions in both
+   * customize and append modes.
+   */
+  getSystemMessageConfigForMode(supplied) {
+    if (this.options.mode !== "empty") return supplied;
+    if (!supplied) {
+      return {
+        mode: "customize",
+        sections: { environment_context: { action: "remove" } }
+      };
     }
-    if (config.hooks) {
-      session.registerHooks(config.hooks);
+    switch (supplied.mode) {
+      case "replace":
+        return supplied;
+      case "customize":
+        if (supplied.sections?.environment_context) return supplied;
+        return {
+          ...supplied,
+          sections: {
+            ...supplied.sections,
+            environment_context: { action: "remove" }
+          }
+        };
+      case "append":
+      case void 0:
+        return {
+          mode: "customize",
+          content: supplied.content,
+          sections: { environment_context: { action: "remove" } }
+        };
+    }
+  }
+  /**
+   * Mode-specific options applied via session.options.update after create/resume.
+   *
+   * In empty mode, defaults the four overridable feature flags to safe values
+   * (caller values from `config` win). `installedPlugins=[]` is unconditional
+   * in empty mode — apps that need custom plugins should switch modes.
+   */
+  async updateSessionOptionsForMode(session, config) {
+    const patch = {};
+    if (this.options.mode === "empty") {
+      patch.skipCustomInstructions = config.skipCustomInstructions ?? true;
+      patch.customAgentsLocalOnly = config.customAgentsLocalOnly ?? true;
+      patch.coauthorEnabled = config.coauthorEnabled ?? false;
+      patch.manageScheduleEnabled = config.manageScheduleEnabled ?? false;
+      patch.installedPlugins = [];
+    } else {
+      if (config.skipCustomInstructions !== void 0)
+        patch.skipCustomInstructions = config.skipCustomInstructions;
+      if (config.customAgentsLocalOnly !== void 0)
+        patch.customAgentsLocalOnly = config.customAgentsLocalOnly;
+      if (config.coauthorEnabled !== void 0)
+        patch.coauthorEnabled = config.coauthorEnabled;
+      if (config.manageScheduleEnabled !== void 0)
+        patch.manageScheduleEnabled = config.manageScheduleEnabled;
+    }
+    if (Object.keys(patch).length === 0) {
+      return;
+    }
+    try {
+      await session.rpc.options.update(patch);
+    } catch (e) {
+      try {
+        await session.disconnect();
+      } catch {
+      }
+      throw e;
+    }
+  }
+  async createSession(config) {
+    if (!this.connection) {
+      await this.start();
     }
+    config = { ...this.configDefaultsForMode(), ...config };
+    config.systemMessage = this.getSystemMessageConfigForMode(config.systemMessage);
+    const callerSessionId = config.sessionId;
+    const useServerGeneratedId = config.cloud != null && callerSessionId == null;
+    const localSessionId = useServerGeneratedId ? void 0 : callerSessionId ?? randomUUID();
     const { wirePayload: wireSystemMessage, transformCallbacks } = extractTransformCallbacks(
       config.systemMessage
     );
-    if (transformCallbacks) {
-      session.registerTransformCallbacks(transformCallbacks);
-    }
-    if (config.onEvent) {
-      session.on(config.onEvent);
-    }
-    this.sessions.set(sessionId, session);
-    if (this.sessionFsConfig) {
-      if (config.createSessionFsHandler) {
-        session.clientSessionApis.sessionFs = createSessionFsAdapter(
-          config.createSessionFsHandler(session)
-        );
-      } else {
-        throw new Error(
-          "createSessionFsHandler is required in session config when sessionFs is enabled in client options."
-        );
+    const initializeSession = (sessionId) => {
+      const s = new CopilotSession(
+        sessionId,
+        this.connection,
+        void 0,
+        this.onGetTraceContext
+      );
+      s.registerTools(config.tools);
+      s.registerCanvases(config.canvases);
+      s.registerCommands(config.commands);
+      s.registerPermissionHandler(config.onPermissionRequest);
+      if (config.onUserInputRequest) {
+        s.registerUserInputHandler(config.onUserInputRequest);
+      }
+      if (config.onElicitationRequest) {
+        s.registerElicitationHandler(config.onElicitationRequest);
+      }
+      if (config.onExitPlanModeRequest) {
+        s.registerExitPlanModeHandler(config.onExitPlanModeRequest);
       }
+      if (config.onAutoModeSwitchRequest) {
+        s.registerAutoModeSwitchHandler(config.onAutoModeSwitchRequest);
+      }
+      if (config.hooks) {
+        s.registerHooks(config.hooks);
+      }
+      if (transformCallbacks) {
+        s.registerTransformCallbacks(transformCallbacks);
+      }
+      if (config.onEvent) {
+        s.on(config.onEvent);
+      }
+      this.sessions.set(sessionId, s);
+      this.setupSessionFs(s, config);
+      return s;
+    };
+    let session;
+    let registeredId;
+    if (localSessionId !== void 0) {
+      session = initializeSession(localSessionId);
+      registeredId = localSessionId;
     }
+    const toolFilterOptions = this.resolveToolFilterOptions(config);
     try {
       const response = await this.connection.sendRequest("session.create", {
         ...await getTraceContext(this.onGetTraceContext),
         model: config.model,
-        sessionId,
+        sessionId: localSessionId,
         clientName: config.clientName,
         reasoningEffort: config.reasoningEffort,
+        reasoningSummary: config.reasoningSummary,
         tools: config.tools?.map((tool) => ({
           name: tool.name,
           description: tool.description,
@@ -514,39 +775,81 @@ class CopilotClient {
           overridesBuiltInTool: tool.overridesBuiltInTool,
           skipPermission: tool.skipPermission
         })),
+        canvases: config.canvases?.map((canvas) => canvas.declaration),
+        requestCanvasRenderer: config.requestCanvasRenderer,
+        requestExtensions: config.requestExtensions,
+        extensionInfo: config.extensionInfo,
         commands: config.commands?.map((cmd) => ({
           name: cmd.name,
           description: cmd.description
         })),
         systemMessage: wireSystemMessage,
-        availableTools: config.availableTools,
-        excludedTools: config.excludedTools,
+        availableTools: toolFilterOptions.availableTools,
+        excludedTools: toolFilterOptions.excludedTools,
+        toolFilterPrecedence: toolFilterOptions.toolFilterPrecedence,
         provider: config.provider,
+        enableSessionTelemetry: config.enableSessionTelemetry,
         modelCapabilities: config.modelCapabilities,
-        requestPermission: true,
+        largeOutput: toWireLargeOutput(config.largeOutput),
+        requestPermission: !!config.onPermissionRequest,
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
+        ...config.enableMcpApps ? { requestMcpApps: true } : {},
+        requestExitPlanMode: !!config.onExitPlanModeRequest,
+        requestAutoModeSwitch: !!config.onAutoModeSwitchRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,
-        mcpServers: config.mcpServers,
+        mcpServers: toWireMcpServers(config.mcpServers),
+        mcpOAuthTokenStorage: config.mcpOAuthTokenStorage,
         envValueMode: "direct",
-        customAgents: config.customAgents,
+        customAgents: toWireCustomAgents(config.customAgents),
         defaultAgent: config.defaultAgent,
         agent: config.agent,
-        configDir: config.configDir,
+        configDir: config.configDirectory,
         enableConfigDiscovery: config.enableConfigDiscovery,
+        skipEmbeddingRetrieval: config.skipEmbeddingRetrieval,
+        embeddingCacheStorage: config.embeddingCacheStorage,
+        organizationCustomInstructions: config.organizationCustomInstructions,
+        enableOnDemandInstructionDiscovery: config.enableOnDemandInstructionDiscovery,
+        enableFileHooks: config.enableFileHooks,
+        enableHostGitOperations: config.enableHostGitOperations,
+        enableSessionStore: config.enableSessionStore,
+        enableSkills: config.enableSkills,
         skillDirectories: config.skillDirectories,
+        pluginDirectories: config.pluginDirectories,
+        instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
-        gitHubToken: config.gitHubToken
+        gitHubToken: config.gitHubToken,
+        remoteSession: config.remoteSession,
+        cloud: config.cloud
       });
-      const { workspacePath, capabilities } = response;
+      const {
+        sessionId: returnedSessionId,
+        workspacePath,
+        capabilities
+      } = response;
+      if (!returnedSessionId) {
+        throw new Error("session.create response did not include a sessionId");
+      }
+      if (localSessionId !== void 0 && localSessionId !== returnedSessionId) {
+        throw new Error(
+          `session.create returned sessionId ${returnedSessionId} but the caller requested ${localSessionId}`
+        );
+      }
+      if (session === void 0) {
+        session = initializeSession(returnedSessionId);
+        registeredId = returnedSessionId;
+      }
       session["_workspacePath"] = workspacePath;
       session.setCapabilities(capabilities);
+      await this.updateSessionOptionsForMode(session, config);
     } catch (e) {
-      this.sessions.delete(sessionId);
+      if (registeredId !== void 0) {
+        this.sessions.delete(registeredId);
+      }
       throw e;
     }
     return session;
@@ -576,17 +879,8 @@ class CopilotClient {
    * ```
    */
   async resumeSession(sessionId, config) {
-    if (!config?.onPermissionRequest) {
-      throw new Error(
-        "An onPermissionRequest handler is required when resuming a session. For example, to allow all permissions, use { onPermissionRequest: approveAll }."
-      );
-    }
     if (!this.connection) {
-      if (this.options.autoStart) {
-        await this.start();
-      } else {
-        throw new Error("Client not connected. Call start() first.");
-      }
+      await this.start();
     }
     const session = new CopilotSession(
       sessionId,
@@ -595,6 +889,7 @@ class CopilotClient {
       this.onGetTraceContext
     );
     session.registerTools(config.tools);
+    session.registerCanvases(config.canvases);
     session.registerCommands(config.commands);
     session.registerPermissionHandler(config.onPermissionRequest);
     if (config.onUserInputRequest) {
@@ -603,9 +898,17 @@ class CopilotClient {
     if (config.onElicitationRequest) {
       session.registerElicitationHandler(config.onElicitationRequest);
     }
+    if (config.onExitPlanModeRequest) {
+      session.registerExitPlanModeHandler(config.onExitPlanModeRequest);
+    }
+    if (config.onAutoModeSwitchRequest) {
+      session.registerAutoModeSwitchHandler(config.onAutoModeSwitchRequest);
+    }
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
+    config = { ...this.configDefaultsForMode(), ...config };
+    config.systemMessage = this.getSystemMessageConfigForMode(config.systemMessage);
     const { wirePayload: wireSystemMessage, transformCallbacks } = extractTransformCallbacks(
       config.systemMessage
     );
@@ -616,17 +919,8 @@ class CopilotClient {
       session.on(config.onEvent);
     }
     this.sessions.set(sessionId, session);
-    if (this.sessionFsConfig) {
-      if (config.createSessionFsHandler) {
-        session.clientSessionApis.sessionFs = createSessionFsAdapter(
-          config.createSessionFsHandler(session)
-        );
-      } else {
-        throw new Error(
-          "createSessionFsHandler is required in session config when sessionFs is enabled in client options."
-        );
-      }
-    }
+    this.setupSessionFs(session, config);
+    const toolFilterOptions = this.resolveToolFilterOptions(config);
     try {
       const response = await this.connection.sendRequest("session.resume", {
         ...await getTraceContext(this.onGetTraceContext),
@@ -634,9 +928,12 @@ class CopilotClient {
         clientName: config.clientName,
         model: config.model,
         reasoningEffort: config.reasoningEffort,
+        reasoningSummary: config.reasoningSummary,
         systemMessage: wireSystemMessage,
-        availableTools: config.availableTools,
-        excludedTools: config.excludedTools,
+        availableTools: toolFilterOptions.availableTools,
+        excludedTools: toolFilterOptions.excludedTools,
+        toolFilterPrecedence: toolFilterOptions.toolFilterPrecedence,
+        enableSessionTelemetry: config.enableSessionTelemetry,
         tools: config.tools?.map((tool) => ({
           name: tool.name,
           description: tool.description,
@@ -644,56 +941,65 @@ class CopilotClient {
           overridesBuiltInTool: tool.overridesBuiltInTool,
           skipPermission: tool.skipPermission
         })),
+        canvases: config.canvases?.map((canvas) => canvas.declaration),
+        requestCanvasRenderer: config.requestCanvasRenderer,
+        requestExtensions: config.requestExtensions,
+        extensionInfo: config.extensionInfo,
         commands: config.commands?.map((cmd) => ({
           name: cmd.name,
           description: cmd.description
         })),
         provider: config.provider,
         modelCapabilities: config.modelCapabilities,
+        largeOutput: toWireLargeOutput(config.largeOutput),
         requestPermission: config.onPermissionRequest !== defaultJoinSessionPermissionHandler,
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
+        ...config.enableMcpApps ? { requestMcpApps: true } : {},
+        requestExitPlanMode: !!config.onExitPlanModeRequest,
+        requestAutoModeSwitch: !!config.onAutoModeSwitchRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
-        configDir: config.configDir,
+        configDir: config.configDirectory,
         enableConfigDiscovery: config.enableConfigDiscovery,
+        skipEmbeddingRetrieval: config.skipEmbeddingRetrieval,
+        embeddingCacheStorage: config.embeddingCacheStorage,
+        organizationCustomInstructions: config.organizationCustomInstructions,
+        enableOnDemandInstructionDiscovery: config.enableOnDemandInstructionDiscovery,
+        enableFileHooks: config.enableFileHooks,
+        enableHostGitOperations: config.enableHostGitOperations,
+        enableSessionStore: config.enableSessionStore,
+        enableSkills: config.enableSkills,
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,
-        mcpServers: config.mcpServers,
+        mcpServers: toWireMcpServers(config.mcpServers),
+        mcpOAuthTokenStorage: config.mcpOAuthTokenStorage,
         envValueMode: "direct",
-        customAgents: config.customAgents,
+        customAgents: toWireCustomAgents(config.customAgents),
         defaultAgent: config.defaultAgent,
         agent: config.agent,
         skillDirectories: config.skillDirectories,
+        pluginDirectories: config.pluginDirectories,
+        instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
-        disableResume: config.disableResume,
-        gitHubToken: config.gitHubToken
+        suppressResumeEvent: config.suppressResumeEvent,
+        continuePendingWork: config.continuePendingWork,
+        gitHubToken: config.gitHubToken,
+        remoteSession: config.remoteSession,
+        openCanvases: config.openCanvases
       });
-      const { workspacePath, capabilities } = response;
+      const { workspacePath, capabilities, openCanvases } = response;
       session["_workspacePath"] = workspacePath;
       session.setCapabilities(capabilities);
+      session.setOpenCanvases(openCanvases ?? []);
+      await this.updateSessionOptionsForMode(session, config);
     } catch (e) {
       this.sessions.delete(sessionId);
       throw e;
     }
     return session;
   }
-  /**
-   * Gets the current connection state of the client.
-   *
-   * @returns The current connection state: "disconnected", "connecting", "connected", or "error"
-   *
-   * @example
-   * ```typescript
-   * if (client.getState() === "connected") {
-   *   const session = await client.createSession({ onPermissionRequest: approveAll });
-   * }
-   * ```
-   */
-  getState() {
-    return this.state;
-  }
   /**
    * Sends a ping request to the server to verify connectivity.
    *
@@ -789,18 +1095,29 @@ class CopilotClient {
     }
   }
   /**
-   * Verify that the server's protocol version is within the supported range
-   * and store the negotiated version.
+   * Send the `connect` handshake (carrying the optional token) and verify the
+   * server's protocol version. Falls back to `ping` against legacy servers
+   * that don't implement `connect`.
    */
   async verifyProtocolVersion() {
+    if (!this.connection) {
+      throw new Error("Client not connected");
+    }
     const maxVersion = getSdkProtocolVersion();
-    let pingResult;
-    if (this.processExitPromise) {
-      pingResult = await Promise.race([this.ping(), this.processExitPromise]);
-    } else {
-      pingResult = await this.ping();
+    const raceAgainstExit = (p) => this.processExitPromise ? Promise.race([p, this.processExitPromise]) : p;
+    let serverVersion;
+    try {
+      const result = await raceAgainstExit(
+        this.internalRpc.connect({ token: this.effectiveConnectionToken })
+      );
+      serverVersion = result.protocolVersion;
+    } catch (err) {
+      if (err instanceof ResponseError && (err.code === ErrorCodes.MethodNotFound || err.message === "Unhandled method connect")) {
+        serverVersion = (await raceAgainstExit(this.ping())).protocolVersion;
+      } else {
+        throw err;
+      }
     }
-    const serverVersion = pingResult.protocolVersion;
     if (serverVersion === void 0) {
       throw new Error(
         `SDK protocol version mismatch: SDK supports versions ${MIN_PROTOCOL_VERSION}-${maxVersion}, but server does not report a protocol version. Please update your server to ensure compatibility.`
@@ -884,8 +1201,13 @@ class CopilotClient {
     if (!this.connection) {
       throw new Error("Client not connected");
     }
+    let wireFilter;
+    if (filter) {
+      const { workingDirectory, ...rest } = filter;
+      wireFilter = { ...rest, cwd: workingDirectory };
+    }
     const response = await this.connection.sendRequest("session.list", {
-      filter
+      filter: wireFilter
     });
     const { sessions } = response;
     return sessions.map(CopilotClient.toSessionMetadata);
@@ -920,13 +1242,19 @@ class CopilotClient {
     return CopilotClient.toSessionMetadata(session);
   }
   static toSessionMetadata(raw) {
+    const { context } = raw;
     return {
       sessionId: raw.sessionId,
       startTime: new Date(raw.startTime),
       modifiedTime: new Date(raw.modifiedTime),
       summary: raw.summary,
       isRemote: raw.isRemote,
-      context: raw.context
+      context: context ? {
+        workingDirectory: context.cwd,
+        gitRoot: context.gitRoot,
+        repository: context.repository,
+        branch: context.branch
+      } : void 0
     };
   }
   /**
@@ -979,7 +1307,7 @@ class CopilotClient {
       throw new Error(result.error || "Failed to set foreground session");
     }
   }
-  on(eventTypeOrHandler, handler) {
+  onLifecycle(eventTypeOrHandler, handler) {
     if (typeof eventTypeOrHandler === "string" && handler) {
       const eventType = eventTypeOrHandler;
       if (!this.typedLifecycleHandlers.has(eventType)) {
@@ -1006,17 +1334,17 @@ class CopilotClient {
   async startCLIServer() {
     return new Promise((resolve, reject) => {
       this.stderrBuffer = "";
-      const args = [
-        ...this.options.cliArgs,
-        "--headless",
-        "--no-auto-update",
-        "--log-level",
-        this.options.logLevel
-      ];
-      if (this.options.useStdio) {
+      const args = [...this.connectionExtraArgs, "--headless", "--no-auto-update"];
+      if (this.options.logLevel) {
+        args.push("--log-level", this.options.logLevel);
+      }
+      if (this.connectionConfig.kind === "stdio") {
         args.push("--stdio");
-      } else if (this.options.port > 0) {
-        args.push("--port", this.options.port.toString());
+      } else if (this.connectionConfig.kind === "tcp") {
+        const requestedPort = this.connectionConfig.port ?? 0;
+        if (requestedPort > 0) {
+          args.push("--port", requestedPort.toString());
+        }
       }
       if (this.options.gitHubToken) {
         args.push("--auth-token-env", "COPILOT_SDK_AUTH_TOKEN");
@@ -1030,14 +1358,26 @@ class CopilotClient {
           this.options.sessionIdleTimeoutSeconds.toString()
         );
       }
-      const envWithoutNodeDebug = { ...this.options.env };
+      if (this.options.enableRemoteSessions) {
+        args.push("--remote");
+      }
+      const envWithoutNodeDebug = { ...this.resolvedEnv };
       delete envWithoutNodeDebug.NODE_DEBUG;
       if (this.options.gitHubToken) {
         envWithoutNodeDebug.COPILOT_SDK_AUTH_TOKEN = this.options.gitHubToken;
       }
-      if (!this.options.cliPath) {
+      if (this.effectiveConnectionToken) {
+        envWithoutNodeDebug.COPILOT_CONNECTION_TOKEN = this.effectiveConnectionToken;
+      }
+      if (this.options.baseDirectory) {
+        envWithoutNodeDebug.COPILOT_HOME = this.options.baseDirectory;
+      }
+      if (this.options.mode === "empty") {
+        envWithoutNodeDebug.COPILOT_DISABLE_KEYTAR = "1";
+      }
+      if (!this.resolvedCliPath) {
         throw new Error(
-          "Path to Copilot CLI is required. Please provide it via the cliPath option, or use cliUrl to rely on a remote CLI."
+          "Path to Copilot CLI is required. Please supply it via `RuntimeConnection.forStdio({ path })` or `RuntimeConnection.forTcp({ path })`, set the COPILOT_CLI_PATH environment variable, or use `RuntimeConnection.forUri(...)` to connect to an already-running runtime."
         );
       }
       if (this.options.telemetry) {
@@ -1056,31 +1396,31 @@ class CopilotClient {
             t.captureContent
           );
       }
-      if (!existsSync(this.options.cliPath)) {
+      if (!existsSync(this.resolvedCliPath)) {
         throw new Error(
-          `Copilot CLI not found at ${this.options.cliPath}. Ensure @github/copilot is installed.`
+          `Copilot CLI not found at ${this.resolvedCliPath}. Ensure @github/copilot is installed.`
         );
       }
-      const stdioConfig = this.options.useStdio ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"];
-      const isJsFile = this.options.cliPath.endsWith(".js");
+      const stdioConfig = this.connectionConfig.kind === "stdio" ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"];
+      const isJsFile = this.resolvedCliPath.endsWith(".js");
       if (isJsFile) {
-        this.cliProcess = spawn(getNodeExecPath(), [this.options.cliPath, ...args], {
+        this.cliProcess = spawn(getNodeExecPath(), [this.resolvedCliPath, ...args], {
           stdio: stdioConfig,
-          cwd: this.options.cwd,
+          cwd: this.options.workingDirectory,
           env: envWithoutNodeDebug,
           windowsHide: true
         });
       } else {
-        this.cliProcess = spawn(this.options.cliPath, args, {
+        this.cliProcess = spawn(this.resolvedCliPath, args, {
           stdio: stdioConfig,
-          cwd: this.options.cwd,
+          cwd: this.options.workingDirectory,
           env: envWithoutNodeDebug,
           windowsHide: true
         });
       }
       let stdout = "";
       let resolved = false;
-      if (this.options.useStdio) {
+      if (this.connectionConfig.kind === "stdio") {
         resolved = true;
         resolve();
       } else {
@@ -1088,7 +1428,7 @@ class CopilotClient {
           stdout += data.toString();
           const match = stdout.match(/listening on port (\d+)/i);
           if (match && !resolved) {
-            this.actualPort = parseInt(match[1], 10);
+            this.runtimePort = parseInt(match[1], 10);
             resolved = true;
             resolve();
           }
@@ -1162,19 +1502,21 @@ stderr: ${stderrOutput}`
           resolved = true;
           reject(new Error("Timeout waiting for CLI server to start"));
         }
-      }, 1e4);
+      }, 3e4);
     });
   }
   /**
    * Connect to the CLI server (via socket or stdio)
    */
   async connectToServer() {
-    if (this.options.isChildProcess) {
-      return this.connectToParentProcessViaStdio();
-    } else if (this.options.useStdio) {
-      return this.connectToChildProcessViaStdio();
-    } else {
-      return this.connectViaTcp();
+    switch (this.connectionConfig.kind) {
+      case "parent-process":
+        return this.connectToParentProcessViaStdio();
+      case "stdio":
+        return this.connectToChildProcessViaStdio();
+      case "tcp":
+      case "uri":
+        return this.connectViaTcp();
     }
   }
   /**
@@ -1214,12 +1556,17 @@ stderr: ${stderrOutput}`
    * Connect to the CLI server via TCP socket
    */
   async connectViaTcp() {
-    if (!this.actualPort) {
+    if (!this.runtimePort) {
       throw new Error("Server port not available");
     }
     return new Promise((resolve, reject) => {
       this.socket = new Socket();
-      this.socket.connect(this.actualPort, this.actualHost, () => {
+      const connectionTimeout = setTimeout(() => {
+        this.socket?.destroy();
+        reject(new Error("Timeout connecting to CLI server"));
+      }, 1e4);
+      this.socket.connect(this.runtimePort, this.actualHost, () => {
+        clearTimeout(connectionTimeout);
         this.connection = createMessageConnection(
           new StreamMessageReader(this.socket),
           new StreamMessageWriter(this.socket)
@@ -1229,6 +1576,7 @@ stderr: ${stderrOutput}`
         resolve();
       });
       this.socket.on("error", (error) => {
+        clearTimeout(connectionTimeout);
         reject(new Error(`Failed to connect to CLI server: ${error.message}`));
       });
     });
@@ -1244,16 +1592,16 @@ stderr: ${stderrOutput}`
       this.handleSessionLifecycleNotification(notification);
     });
     this.connection.onRequest(
-      "tool.call",
-      async (params) => await this.handleToolCallRequestV2(params)
+      "userInput.request",
+      async (params) => await this.handleUserInputRequest(params)
     );
     this.connection.onRequest(
-      "permission.request",
-      async (params) => await this.handlePermissionRequestV2(params)
+      "exitPlanMode.request",
+      async (params) => await this.handleExitPlanModeRequest(params)
     );
     this.connection.onRequest(
-      "userInput.request",
-      async (params) => await this.handleUserInputRequest(params)
+      "autoModeSwitch.request",
+      async (params) => await this.handleAutoModeSwitchRequest(params)
     );
     this.connection.onRequest(
       "hooks.invoke",
@@ -1289,7 +1637,20 @@ stderr: ${stderrOutput}`
     if (typeof notification !== "object" || !notification || !("type" in notification) || typeof notification.type !== "string" || !("sessionId" in notification) || typeof notification.sessionId !== "string") {
       return;
     }
-    const event = notification;
+    const raw = notification;
+    let metadata;
+    if (raw.metadata && raw.metadata.startTime && raw.metadata.modifiedTime) {
+      metadata = {
+        startTime: new Date(raw.metadata.startTime),
+        modifiedTime: new Date(raw.metadata.modifiedTime),
+        summary: raw.metadata.summary
+      };
+    }
+    const event = {
+      type: raw.type,
+      sessionId: raw.sessionId,
+      metadata
+    };
     const typedHandlers = this.typedLifecycleHandlers.get(event.type);
     if (typedHandlers) {
       for (const handler of typedHandlers) {
@@ -1321,125 +1682,55 @@ stderr: ${stderrOutput}`
     });
     return result;
   }
-  async handleHooksInvoke(params) {
-    if (!params || typeof params.sessionId !== "string" || typeof params.hookType !== "string") {
-      throw new Error("Invalid hooks invoke payload");
+  async handleExitPlanModeRequest(params) {
+    if (!params || typeof params.sessionId !== "string" || typeof params.summary !== "string" || !Array.isArray(params.actions) || typeof params.recommendedAction !== "string") {
+      throw new Error("Invalid exit plan mode request payload");
     }
     const session = this.sessions.get(params.sessionId);
     if (!session) {
       throw new Error(`Session not found: ${params.sessionId}`);
     }
-    const output = await session._handleHooksInvoke(params.hookType, params.input);
-    return { output };
+    return await session._handleExitPlanModeRequest({
+      summary: params.summary,
+      planContent: params.planContent,
+      actions: params.actions,
+      recommendedAction: params.recommendedAction
+    });
   }
-  async handleSystemMessageTransform(params) {
-    if (!params || typeof params.sessionId !== "string" || !params.sections || typeof params.sections !== "object") {
-      throw new Error("Invalid systemMessage.transform payload");
+  async handleAutoModeSwitchRequest(params) {
+    if (!params || typeof params.sessionId !== "string") {
+      throw new Error("Invalid auto mode switch request payload");
     }
     const session = this.sessions.get(params.sessionId);
     if (!session) {
       throw new Error(`Session not found: ${params.sessionId}`);
     }
-    return await session._handleSystemMessageTransform(params.sections);
+    const response = await session._handleAutoModeSwitchRequest({
+      errorCode: params.errorCode,
+      retryAfterSeconds: params.retryAfterSeconds
+    });
+    return { response };
   }
-  // ========================================================================
-  // Protocol v2 backward-compatibility adapters
-  // ========================================================================
-  /**
-   * Handles a v2-style tool.call RPC request from the server.
-   * Looks up the session and tool handler, executes it, and returns the result
-   * in the v2 response format.
-   */
-  async handleToolCallRequestV2(params) {
-    if (!params || typeof params.sessionId !== "string" || typeof params.toolCallId !== "string" || typeof params.toolName !== "string") {
-      throw new Error("Invalid tool call payload");
+  async handleHooksInvoke(params) {
+    if (!params || typeof params.sessionId !== "string" || typeof params.hookType !== "string") {
+      throw new Error("Invalid hooks invoke payload");
     }
     const session = this.sessions.get(params.sessionId);
     if (!session) {
-      throw new Error(`Unknown session ${params.sessionId}`);
-    }
-    const handler = session.getToolHandler(params.toolName);
-    if (!handler) {
-      return {
-        result: {
-          textResultForLlm: `Tool '${params.toolName}' is not supported by this client instance.`,
-          resultType: "failure",
-          error: `tool '${params.toolName}' not supported`,
-          toolTelemetry: {}
-        }
-      };
-    }
-    try {
-      const traceparent = params.traceparent;
-      const tracestate = params.tracestate;
-      const invocation = {
-        sessionId: params.sessionId,
-        toolCallId: params.toolCallId,
-        toolName: params.toolName,
-        arguments: params.arguments,
-        traceparent,
-        tracestate
-      };
-      const result = await handler(params.arguments, invocation);
-      return { result: this.normalizeToolResultV2(result) };
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      return {
-        result: {
-          textResultForLlm: "Invoking this tool produced an error. Detailed information is not available.",
-          resultType: "failure",
-          error: message,
-          toolTelemetry: {}
-        }
-      };
+      throw new Error(`Session not found: ${params.sessionId}`);
     }
+    const output = await session._handleHooksInvoke(params.hookType, params.input);
+    return { output };
   }
-  /**
-   * Handles a v2-style permission.request RPC request from the server.
-   */
-  async handlePermissionRequestV2(params) {
-    if (!params || typeof params.sessionId !== "string" || !params.permissionRequest) {
-      throw new Error("Invalid permission request payload");
+  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}`);
     }
-    try {
-      const result = await session._handlePermissionRequestV2(params.permissionRequest);
-      return { result };
-    } catch (error) {
-      if (error instanceof Error && error.message === NO_RESULT_PERMISSION_V2_ERROR) {
-        throw error;
-      }
-      return {
-        result: {
-          kind: "user-not-available"
-        }
-      };
-    }
-  }
-  normalizeToolResultV2(result) {
-    if (result === void 0 || result === null) {
-      return {
-        textResultForLlm: "Tool returned no result",
-        resultType: "failure",
-        error: "tool returned no result",
-        toolTelemetry: {}
-      };
-    }
-    if (this.isToolResultObject(result)) {
-      return result;
-    }
-    const textResult = typeof result === "string" ? result : JSON.stringify(result);
-    return {
-      textResultForLlm: textResult,
-      resultType: "success",
-      toolTelemetry: {}
-    };
-  }
-  isToolResultObject(value) {
-    return typeof value === "object" && value !== null && "textResultForLlm" in value && typeof value.textResultForLlm === "string" && "resultType" in value;
+    return await session._handleSystemMessageTransform(params.sections);
   }
 }
 export {