@github/copilot-sdk 1.0.0-beta.7 → 1.0.0-beta.9

package/dist/generated/rpc.js

@@ -145,7 +145,7 @@ function createServerRpc(connection) {
       /**
        * Lists persisted sessions, optionally filtered by working-directory context.
        *
-       * @param params Optional metadata-load limit and context filter applied to the returned sessions.
+       * @param params Optional metadata-load limit and filters applied to the returned sessions.
        *
        * @returns Persisted sessions matching the filter, ordered most-recently-modified first.
        */
@@ -249,7 +249,7 @@ function createServerRpc(connection) {
        *
        * @param params Session metadata records to enrich with summary and context information.
        *
-       * @returns The same metadata records, with summary and context fields backfilled where available.
+       * @returns The enriched metadata records, with summary and context fields backfilled where available. Sessions confirmed empty and unnamed are omitted.
        */
       enrichMetadata: async (params) => connection.sendRequest("sessions.enrichMetadata", params),
       /**
@@ -276,6 +276,17 @@ function createServerRpc(connection) {
        * @returns Replace the manager-wide additional plugins. New session creations and subsequent hook reloads see the new set; already-running sessions keep their existing hook installation until the next reload.
        */
       setAdditionalPlugins: async (params) => connection.sendRequest("sessions.setAdditionalPlugins", params)
+    },
+    /** @experimental */
+    agentRegistry: {
+      /**
+       * Spawns a managed-server child with the supplied configuration and returns a discriminated-union result. The caller (typically the CLI controller) is responsible for attaching to the spawned child and sending any follow-up prompt. When the controller-local spawn gate is closed the server returns JSON-RPC MethodNotFound.
+       *
+       * @param params Inputs to spawn a managed-server child via the controller's spawn delegate.
+       *
+       * @returns Outcome of an agentRegistry.spawn call.
+       */
+      spawn: async (params) => connection.sendRequest("agentRegistry.spawn", params)
     }
   };
 }
@@ -512,7 +523,15 @@ function createSessionRpc(connection, sessionId) {
        *
        * @returns Descriptor for the saved paste file, or null when the workspace is unavailable.
        */
-      saveLargePaste: async (params) => connection.sendRequest("session.workspaces.saveLargePaste", { sessionId, ...params })
+      saveLargePaste: async (params) => connection.sendRequest("session.workspaces.saveLargePaste", { sessionId, ...params }),
+      /**
+       * Computes a diff for the session workspace.
+       *
+       * @param params Parameters for computing a workspace diff.
+       *
+       * @returns Workspace diff result for the requested mode.
+       */
+      diff: async (params) => connection.sendRequest("session.workspaces.diff", { sessionId, ...params })
     },
     /** @experimental */
     instructions: {
@@ -1026,6 +1045,20 @@ function createSessionRpc(connection, sessionId) {
        * @returns Indicates whether the operation succeeded.
        */
       setApproveAll: async (params) => connection.sendRequest("session.permissions.setApproveAll", { sessionId, ...params }),
+      /**
+       * Enables or disables full allow-all permissions (tools, paths, and URLs) for the session. Used by attach-mode clients (e.g. LocalRpcSession's `/allow-all` forwarder) to flip the target session's permission state. Unlike `setApproveAll`, this swaps in the unrestricted path and URL managers and emits `session.permissions_changed` on transition. The result returns the authoritative post-mutation state so callers can update their local mirrors without racing the `session.permissions_changed` notification on the same wire.
+       *
+       * @param params Whether to enable full allow-all permissions for the session.
+       *
+       * @returns Indicates whether the operation succeeded and reports the post-mutation state.
+       */
+      setAllowAll: async (params) => connection.sendRequest("session.permissions.setAllowAll", { sessionId, ...params }),
+      /**
+       * Returns whether full allow-all permissions are currently active for the session.
+       *
+       * @returns Current full allow-all permission state.
+       */
+      getAllowAll: async () => connection.sendRequest("session.permissions.getAllowAll", { sessionId }),
       /**
        * Adds or removes session-scoped or location-scoped permission rules.
        *
@@ -1432,6 +1465,21 @@ function registerClientSessionApiHandlers(connection, getHandlers) {
     if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
     return handler.sqliteExists(params);
   });
+  connection.onRequest("canvas.open", async (params) => {
+    const handler = getHandlers(params.sessionId).canvas;
+    if (!handler) throw new Error(`No canvas handler registered for session: ${params.sessionId}`);
+    return handler.open(params);
+  });
+  connection.onRequest("canvas.close", async (params) => {
+    const handler = getHandlers(params.sessionId).canvas;
+    if (!handler) throw new Error(`No canvas handler registered for session: ${params.sessionId}`);
+    return handler.close(params);
+  });
+  connection.onRequest("canvas.invokeAction", async (params) => {
+    const handler = getHandlers(params.sessionId).canvas;
+    if (!handler) throw new Error(`No canvas handler registered for session: ${params.sessionId}`);
+    return handler.invokeAction(params);
+  });
 }
 export {
   createInternalServerRpc,

package/dist/generated/session-events.d.ts

@@ -5,7 +5,7 @@
 /**
  * Union of all session event variants emitted by the Copilot CLI runtime.
  */
-export type SessionEvent = StartEvent | ResumeEvent | RemoteSteerableChangedEvent | ErrorEvent | IdleEvent | TitleChangedEvent | ScheduleCreatedEvent | ScheduleCancelledEvent | InfoEvent | WarningEvent | ModelChangeEvent | ModeChangedEvent | PlanChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | ContextChangedEvent | UsageInfoEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantUsageEvent | ModelCallFailureEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | CustomNotificationEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | AutoModeSwitchRequestedEvent | AutoModeSwitchCompletedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | ExtensionsLoadedEvent | CanvasOpenedEvent | CanvasRegistryChangedEvent | McpAppToolCallCompleteEvent;
+export type SessionEvent = StartEvent | ResumeEvent | RemoteSteerableChangedEvent | ErrorEvent | IdleEvent | TitleChangedEvent | ScheduleCreatedEvent | ScheduleCancelledEvent | AutopilotObjectiveChangedEvent | InfoEvent | WarningEvent | ModelChangeEvent | ModeChangedEvent | PermissionsChangedEvent | PlanChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | ContextChangedEvent | UsageInfoEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantUsageEvent | ModelCallFailureEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | HookProgressEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | CustomNotificationEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | AutoModeSwitchRequestedEvent | AutoModeSwitchCompletedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | ExtensionsLoadedEvent | CanvasOpenedEvent | CanvasRegistryChangedEvent | McpAppToolCallCompleteEvent;
 /**
  * Hosting platform type of the repository (github or ado)
  */
@@ -24,6 +24,28 @@ export type ReasoningSummary =
  | "concise"
 /** Request a detailed summary of the model's reasoning. */
  | "detailed";
+/**
+ * The type of operation performed on the autopilot objective state file
+ */
+export type AutopilotObjectiveChangedOperation = 
+/** Autopilot objective state file was created for a new objective. */
+"create"
+/** Autopilot objective state file was updated for an existing objective. */
+ | "update"
+/** Autopilot objective state file was deleted or cleared. */
+ | "delete";
+/**
+ * Current autopilot objective status, if one exists
+ */
+export type AutopilotObjectiveChangedStatus = 
+/** Objective is active and can drive autopilot continuations. */
+"active"
+/** Objective is paused and will not drive autopilot continuations. */
+ | "paused"
+/** Legacy objective state indicating the previous continuation cap was reached. */
+ | "cap_reached"
+/** Objective was completed by the agent. */
+ | "completed";
 /**
  * The session mode the agent is operating in
  */
@@ -828,6 +850,47 @@ export interface ScheduleCancelledData {
      */
     id: number;
 }
+/**
+ * Session event "session.autopilot_objective_changed". Autopilot objective state file operation details indicating what changed
+ */
+export interface AutopilotObjectiveChangedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: AutopilotObjectiveChangedData;
+    /**
+     * When true, the event is transient and not persisted to the session event log on disk
+     */
+    ephemeral?: boolean;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "session.autopilot_objective_changed".
+     */
+    type: "session.autopilot_objective_changed";
+}
+/**
+ * Autopilot objective state file operation details indicating what changed
+ */
+export interface AutopilotObjectiveChangedData {
+    /**
+     * Current autopilot objective id, if one exists
+     */
+    id?: number;
+    operation: AutopilotObjectiveChangedOperation;
+    status?: AutopilotObjectiveChangedStatus;
+}
 /**
  * Session event "session.info". Informational message for timeline display with categorization
  */
@@ -1026,6 +1089,49 @@ export interface ModeChangedData {
     newMode: SessionMode;
     previousMode: SessionMode;
 }
+/**
+ * Session event "session.permissions_changed". Permissions change details carrying the aggregate allow-all boolean transition.
+ */
+export interface PermissionsChangedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: PermissionsChangedData;
+    /**
+     * When true, the event is transient and not persisted to the session event log on disk
+     */
+    ephemeral?: boolean;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "session.permissions_changed".
+     */
+    type: "session.permissions_changed";
+}
+/**
+ * Permissions change details carrying the aggregate allow-all boolean transition.
+ */
+export interface PermissionsChangedData {
+    /**
+     * Aggregate allow-all flag after the change
+     */
+    allowAllPermissions: boolean;
+    /**
+     * Aggregate allow-all flag before the change
+     */
+    previousAllowAllPermissions: boolean;
+}
 /**
  * Session event "session.plan_changed". Plan file operation details indicating what changed
  */
@@ -2853,6 +2959,10 @@ export interface ToolExecutionStartData {
     arguments?: {
         [k: string]: unknown | undefined;
     };
+    /**
+     * When true, the tool output should be displayed expanded (verbatim) in the CLI timeline
+     */
+    displayVerbatim?: boolean;
     /**
      * Name of the MCP server hosting this tool, when the tool is an MCP tool
      */
@@ -3803,6 +3913,45 @@ export interface HookEndError {
      */
     stack?: string;
 }
+/**
+ * Session event "hook.progress". Ephemeral progress update from a running hook process
+ */
+export interface HookProgressEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: HookProgressData;
+    /**
+     * Always true for events that are transient and not persisted to the session event log on disk.
+     */
+    ephemeral: true;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * Type discriminator. Always "hook.progress".
+     */
+    type: "hook.progress";
+}
+/**
+ * Ephemeral progress update from a running hook process
+ */
+export interface HookProgressData {
+    /**
+     * Human-readable progress message from the hook process
+     */
+    message: string;
+}
 /**
  * Session event "system.message". System/developer instruction content with role and optional template metadata
  */
@@ -5473,6 +5622,10 @@ export interface ExternalToolRequestedData {
      * W3C Trace Context tracestate header for the execute_tool span
      */
     tracestate?: string;
+    /**
+     * Active session working directory, when known.
+     */
+    workingDirectory?: string;
 }
 /**
  * Session event "external_tool.completed". External tool completion notification signaling UI dismissal

package/dist/index.d.ts

@@ -5,8 +5,9 @@
  */
 export { CopilotClient } from "./client.js";
 export { RuntimeConnection } from "./types.js";
+export { BuiltInTools, ToolSet } from "./toolSet.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
-export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasActionContext, type CanvasDeclaration, type CanvasHostContext, type CanvasJsonSchema, type CanvasLifecycleContext, type CanvasOpenContext, type CanvasOpenResponse, type CanvasOptions, } from "./canvas.js";
+export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
 export { defineTool, approveAll, convertMcpCallToolResult, createSessionFsAdapter, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
 export type * from "./generated/session-events.js";
-export type { CommandContext, CommandDefinition, CommandHandler, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, CopilotClientOptions, StdioRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolTelemetry, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { CommandContext, CommandDefinition, CommandHandler, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, CopilotClientMode, CopilotClientOptions, StdioRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolTelemetry, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 import { CopilotClient } from "./client.js";
 import { RuntimeConnection } from "./types.js";
+import { BuiltInTools, ToolSet } from "./toolSet.js";
 import { CopilotSession } from "./session.js";
 import {
   Canvas,
@@ -14,12 +15,14 @@ import {
   SYSTEM_MESSAGE_SECTIONS
 } from "./types.js";
 export {
+  BuiltInTools,
   Canvas,
   CanvasError,
   CopilotClient,
   CopilotSession,
   RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS,
+  ToolSet,
   approveAll,
   convertMcpCallToolResult,
   createCanvas,

package/dist/session.js

@@ -1,5 +1,6 @@
-import { ConnectionError, ResponseError } from "vscode-jsonrpc/node.js";
+import { ConnectionError, ErrorCodes, ResponseError } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
+import { CanvasError } from "./canvas.js";
 import { getTraceContext } from "./telemetry.js";
 function deserializeHookInput(raw) {
   if (!raw || typeof raw !== "object" || typeof raw.timestamp !== "number") {
@@ -95,6 +96,7 @@ class CopilotSession {
       prompt: options.prompt,
       attachments: options.attachments,
       mode: options.mode,
+      agentMode: options.agentMode,
       requestHeaders: options.requestHeaders
     });
     return response.messageId;
@@ -378,22 +380,52 @@ class CopilotSession {
    */
   registerCanvases(canvases) {
     this.canvases.clear();
-    if (!canvases) {
+    if (!canvases || canvases.length === 0) {
+      delete this.clientSessionApis.canvas;
       return;
     }
     for (const canvas of canvases) {
       this.canvases.set(canvas.declaration.id, canvas);
     }
-  }
-  /**
-   * Retrieves a registered canvas by id.
-   *
-   * @param canvasId - The id of the canvas to retrieve
-   * @returns The registered Canvas if found, or undefined
-   * @internal Used by the SDK's direct `canvas.*` dispatcher.
-   */
-  getCanvas(canvasId) {
-    return this.canvases.get(canvasId);
+    const self = this;
+    this.clientSessionApis.canvas = {
+      async open(params) {
+        const canvas = self.canvases.get(params.canvasId);
+        if (!canvas) throw new Error(`No canvas registered with id "${params.canvasId}"`);
+        try {
+          return await canvas.open(params) ?? {};
+        } catch (error) {
+          throw toCanvasRpcError(error);
+        }
+      },
+      async close(params) {
+        const canvas = self.canvases.get(params.canvasId);
+        if (!canvas) throw new Error(`No canvas registered with id "${params.canvasId}"`);
+        try {
+          if (canvas.onClose) {
+            await canvas.onClose(params);
+          }
+        } catch (error) {
+          throw toCanvasRpcError(error);
+        }
+      },
+      async invokeAction(params) {
+        const canvas = self.canvases.get(params.canvasId);
+        if (!canvas) throw new Error(`No canvas registered with id "${params.canvasId}"`);
+        const handler = canvas.actionHandlers.get(params.actionName);
+        if (!handler) {
+          throw new CanvasError(
+            "canvas_action_no_handler",
+            "No handler implemented for this canvas action"
+          );
+        }
+        try {
+          return await handler(params);
+        } catch (error) {
+          throw toCanvasRpcError(error);
+        }
+      }
+    };
   }
   /**
    * Registers command handlers for this session.
@@ -685,6 +717,7 @@ class CopilotSession {
       preToolUse: this.hooks.onPreToolUse,
       preMcpToolCall: this.hooks.onPreMcpToolCall,
       postToolUse: this.hooks.onPostToolUse,
+      postToolUseFailure: this.hooks.onPostToolUseFailure,
       userPromptSubmitted: this.hooks.onUserPromptSubmitted,
       sessionStart: this.hooks.onSessionStart,
       sessionEnd: this.hooks.onSessionEnd,
@@ -844,6 +877,12 @@ function isToolResultObject(value) {
   ];
   return allowedResultTypes.includes(value.resultType);
 }
+function toCanvasRpcError(error) {
+  if (error instanceof ResponseError) return error;
+  const code = error instanceof CanvasError ? error.code : "canvas_handler_error";
+  const message = error instanceof Error ? error.message : String(error);
+  return new ResponseError(ErrorCodes.InternalError, message, { code, message });
+}
 export {
   CopilotSession
 };

package/dist/toolSet.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Builder that produces a list of source-qualified tool filter strings for
+ * {@link SessionConfigBase.availableTools}.
+ *
+ * Tools are classified by the runtime at registration time (not from name
+ * parsing), so `addBuiltIn("foo")` matches only tools the runtime registered
+ * as built-in, even if an MCP server or custom-agent extension happens to
+ * register a tool with the same wire name.
+ *
+ * @example
+ * ```typescript
+ * const tools = new ToolSet()
+ *     .addBuiltIn(BuiltInTools.Isolated)
+ *     .addMcp("*")
+ *     .addCustom("*");
+ *
+ * const session = await client.createSession({
+ *     availableTools: tools,
+ *     // ...
+ * });
+ * ```
+ */
+export declare class ToolSet {
+    private readonly items;
+    /**
+     * Adds one or more built-in tool patterns.
+     *
+     * @param name A specific built-in tool name (e.g. `"bash"`) or `"*"` to match all
+     *   built-in tools.
+     */
+    addBuiltIn(name: string): ToolSet;
+    /**
+     * Adds a list of built-in tool patterns (e.g. {@link BuiltInTools.Isolated}).
+     */
+    addBuiltIn(names: readonly string[]): ToolSet;
+    /**
+     * Adds a custom tool pattern. Matches tools registered via the SDK's
+     * `tools` option or via custom agents.
+     *
+     * @param name A specific custom tool name or `"*"` to match all custom tools.
+     */
+    addCustom(name: string): ToolSet;
+    /**
+     * Adds an MCP tool pattern. Matches tools advertised by any configured
+     * MCP server.
+     *
+     * @param toolName The runtime's canonical wire name for the MCP tool
+     *   (e.g. `"github-list_issues"`), or `"*"` to match all MCP tools from
+     *   any server.
+     */
+    addMcp(toolName: string): ToolSet;
+    /**
+     * Returns a defensive copy of the accumulated filter strings, suitable for
+     * passing as {@link SessionConfigBase.availableTools}.
+     */
+    toArray(): string[];
+}
+/**
+ * Curated sets of built-in tool names for common scenarios. Each constant is
+ * meant to be passed to {@link ToolSet.addBuiltIn}.
+ */
+export declare const BuiltInTools: {
+    /**
+     * Built-in tools that operate only within the bounds of a single session —
+     * no host filesystem access outside the session, no cross-session state,
+     * no host environment access, no network. Safe to enable in `Mode = "empty"`
+     * scenarios (e.g. multi-tenant servers) without leaking host capabilities.
+     *
+     * **Contract:** tools in this set MUST NOT be extended (even behind options
+     * or args) to read or write state outside the session boundary. Adding
+     * cross-session or host-state behavior to one of these tools is a
+     * breaking change that requires removing it from this set.
+     */
+    readonly Isolated: readonly string[];
+};

package/dist/toolSet.js

@@ -0,0 +1,82 @@
+const VALID_TOOL_NAME = /^[a-zA-Z0-9_-]+$/;
+function validateName(kind, name) {
+  if (name === "*") {
+    return;
+  }
+  if (!VALID_TOOL_NAME.test(name)) {
+    throw new Error(
+      `Invalid ${kind} tool name '${name}': tool names must match /^[a-zA-Z0-9_-]+$/ or be the wildcard '*'.`
+    );
+  }
+}
+class ToolSet {
+  items = [];
+  addBuiltIn(nameOrNames) {
+    const names = typeof nameOrNames === "string" ? [nameOrNames] : nameOrNames;
+    for (const name of names) {
+      validateName("builtin", name);
+      this.items.push(`builtin:${name}`);
+    }
+    return this;
+  }
+  /**
+   * Adds a custom tool pattern. Matches tools registered via the SDK's
+   * `tools` option or via custom agents.
+   *
+   * @param name A specific custom tool name or `"*"` to match all custom tools.
+   */
+  addCustom(name) {
+    validateName("custom", name);
+    this.items.push(`custom:${name}`);
+    return this;
+  }
+  /**
+   * Adds an MCP tool pattern. Matches tools advertised by any configured
+   * MCP server.
+   *
+   * @param toolName The runtime's canonical wire name for the MCP tool
+   *   (e.g. `"github-list_issues"`), or `"*"` to match all MCP tools from
+   *   any server.
+   */
+  addMcp(toolName) {
+    validateName("mcp", toolName);
+    this.items.push(`mcp:${toolName}`);
+    return this;
+  }
+  /**
+   * Returns a defensive copy of the accumulated filter strings, suitable for
+   * passing as {@link SessionConfigBase.availableTools}.
+   */
+  toArray() {
+    return [...this.items];
+  }
+}
+const BuiltInTools = {
+  /**
+   * Built-in tools that operate only within the bounds of a single session —
+   * no host filesystem access outside the session, no cross-session state,
+   * no host environment access, no network. Safe to enable in `Mode = "empty"`
+   * scenarios (e.g. multi-tenant servers) without leaking host capabilities.
+   *
+   * **Contract:** tools in this set MUST NOT be extended (even behind options
+   * or args) to read or write state outside the session boundary. Adding
+   * cross-session or host-state behavior to one of these tools is a
+   * breaking change that requires removing it from this set.
+   */
+  Isolated: [
+    "ask_user",
+    "task_complete",
+    "exit_plan_mode",
+    "task",
+    "read_agent",
+    "write_agent",
+    "list_agents",
+    "send_inbox",
+    "context_board",
+    "skill"
+  ]
+};
+export {
+  BuiltInTools,
+  ToolSet
+};