@github/copilot-sdk 1.0.0-beta.8 → 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.
        */
@@ -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)
     }
   };
 }
@@ -1034,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.
        *

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 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

@@ -96,6 +96,7 @@ class CopilotSession {
       prompt: options.prompt,
       attachments: options.attachments,
       mode: options.mode,
+      agentMode: options.agentMode,
       requestHeaders: options.requestHeaders
     });
     return response.messageId;
@@ -716,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,

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
+};

package/dist/types.d.ts

@@ -7,6 +7,7 @@ import type { SessionEvent as GeneratedSessionEvent } from "./generated/session-
 import type { CopilotSession } from "./session.js";
 import type { RemoteSessionMode } from "./generated/rpc.js";
 import type { OpenCanvasInstance } from "./generated/rpc.js";
+import type { ToolSet } from "./toolSet.js";
 export type { RemoteSessionMode } from "./generated/rpc.js";
 export type SessionEvent = GeneratedSessionEvent;
 export type { SessionFsProvider } from "./sessionFsProvider.js";
@@ -128,12 +129,38 @@ export declare const RuntimeConnection: {
         connectionToken?: string;
     }) => UriRuntimeConnection;
 };
+/**
+ * Controls SDK defaults for ambient features.
+ *
+ * - `"copilot-cli"` (default): Defaults equivalent to Copilot CLI. Useful when
+ *   building a coding agent that shares sessions with Copilot CLI. Do not use
+ *   this mode for server-based multi-user applications — the default coding
+ *   agent has tools and capabilities that operate across sessions and can
+ *   access the host OS environment.
+ * - `"empty"`: Disables optional features by default. The app must explicitly
+ *   opt into anything it needs. Required for any scenario where CLI-like
+ *   ambient behavior is unsafe (e.g. multi-user servers).
+ */
+export type CopilotClientMode = "empty" | "copilot-cli";
 export interface CopilotClientOptions {
     /**
      * How to connect to the Copilot runtime. When omitted, defaults to
      * {@link RuntimeConnection.forStdio} with the bundled runtime.
      */
     connection?: RuntimeConnection;
+    /**
+     * Selects the SDK defaulting strategy. See {@link CopilotClientMode}.
+     *
+     * When set to `"empty"`, the SDK validates that the app has supplied the
+     * required configuration ({@link CopilotClientOptions.baseDirectory} or
+     * {@link CopilotClientOptions.sessionFs}, plus
+     * {@link SessionConfigBase.availableTools} on each session) and translates
+     * session creation requests into runtime options that flip tool filter
+     * precedence to deny-wins so exclusions are expressible.
+     *
+     * @default "copilot-cli"
+     */
+    mode?: CopilotClientMode;
     /**
      * Working directory for the runtime process.
      * If not set, inherits the current process's working directory.
@@ -849,6 +876,47 @@ export interface PostToolUseHookOutput {
 export type PostToolUseHandler = (input: PostToolUseHookInput, invocation: {
     sessionId: string;
 }) => Promise<PostToolUseHookOutput | void> | PostToolUseHookOutput | void;
+/**
+ * Input for post-tool-use-failure hook.
+ *
+ * Dispatched after a tool execution whose `resultType` is `"failure"`.
+ * The input differs from {@link PostToolUseHookInput}: the host CLI does not
+ * forward the full `ToolResultObject` to failure hooks — only `error`, the
+ * stringified failure message extracted from the tool's result, is provided.
+ */
+export interface PostToolUseFailureHookInput extends BaseHookInput {
+    toolName: string;
+    toolArgs: unknown;
+    /**
+     * Failure message from the tool's result (the `error` field of the
+     * underlying `ToolResultObject`, falling back to its text/log fields).
+     */
+    error: string;
+}
+/**
+ * Output for post-tool-use-failure hook.
+ *
+ * Only `additionalContext` is consumed by the host CLI — it is appended as
+ * hidden guidance to the model alongside the failed tool result. Other fields
+ * such as `modifiedResult` or `suppressOutput` are not honored for failure
+ * hooks (see {@link PostToolUseHookOutput} for the success-only hook).
+ */
+export interface PostToolUseFailureHookOutput {
+    additionalContext?: string;
+}
+/**
+ * Handler for post-tool-use-failure hook.
+ *
+ * Fires after a tool execution whose result was `"failure"`. `onPostToolUse`
+ * only fires for successful results, so register this handler to observe or
+ * react to failed tool outcomes.
+ *
+ * Note: `"rejected"`, `"denied"`, and `"timeout"` results do not currently
+ * trigger this hook either — only `"failure"` does.
+ */
+export type PostToolUseFailureHandler = (input: PostToolUseFailureHookInput, invocation: {
+    sessionId: string;
+}) => Promise<PostToolUseFailureHookOutput | void> | PostToolUseFailureHookOutput | void;
 /**
  * Input for user-prompt-submitted hook
  */
@@ -947,9 +1015,20 @@ export interface SessionHooks {
      */
     onPreMcpToolCall?: PreMcpToolCallHandler;
     /**
-     * Called after a tool is executed
+     * Called after a tool is executed with a successful result.
+     *
+     * For failed tool executions, register {@link onPostToolUseFailure} instead;
+     * this handler does not fire for non-success results.
      */
     onPostToolUse?: PostToolUseHandler;
+    /**
+     * Called after a tool execution whose result was `"failure"`.
+     *
+     * Register this handler alongside {@link onPostToolUse} to observe failed
+     * tool calls — `onPostToolUse` only fires for successful results, so
+     * without this hook failed tool calls are invisible to extensions.
+     */
+    onPostToolUseFailure?: PostToolUseFailureHandler;
     /**
      * Called when the user submits a prompt
      */
@@ -1207,14 +1286,25 @@ export interface SessionConfigBase {
     systemMessage?: SystemMessageConfig;
     /**
      * List of tool names to allow. When specified, only these tools will be available.
-     * Takes precedence over excludedTools.
+     *
+     * Supports source-qualified filter patterns (`builtin:*`, `builtin:<name>`,
+     * `mcp:*`, `mcp:<name>`, `custom:*`, `custom:<name>`) as well as the bare
+     * name form (exact match across any source). Build this list with
+     * {@link ToolSet} for type safety and readable intent.
+     *
+     * Composes with {@link excludedTools}: a tool is enabled when it matches
+     * `availableTools` (or `availableTools` is unset) AND it does not match
+     * `excludedTools`. This lets you express "everything matching X except Y".
      */
-    availableTools?: string[];
+    availableTools?: string[] | ToolSet;
     /**
-     * List of tool names to disable. All other tools remain available.
-     * Ignored if availableTools is specified.
+     * List of tool names to disable. Supports the same pattern syntax as
+     * {@link availableTools}.
+     *
+     * Always takes precedence over {@link availableTools}: a tool listed here
+     * is disabled even if it also matches `availableTools`.
      */
-    excludedTools?: string[];
+    excludedTools?: string[] | ToolSet;
     /**
      * Custom provider configuration (BYOK - Bring Your Own Key).
      * When specified, uses the provided API endpoint instead of the Copilot API.
@@ -1229,6 +1319,39 @@ export interface SessionConfigBase {
      * This is independent of the OpenTelemetry configuration in {@link CopilotClientOptions.telemetry}.
      */
     enableSessionTelemetry?: boolean;
+    /**
+     * When true, the runtime skips loading custom-instruction sources
+     * (e.g. `.github/copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`).
+     *
+     * Defaults to `false` (custom instructions are loaded). Under
+     * {@link CopilotClientOptions.mode} = `"empty"`, defaults to `true`; apps
+     * can pass `false` here to opt back in.
+     */
+    skipCustomInstructions?: boolean;
+    /**
+     * When true, custom agents default to local-only execution and are not
+     * dispatched to remote workers.
+     *
+     * Defaults to `false`. Under {@link CopilotClientOptions.mode} = `"empty"`,
+     * defaults to `true`; apps can pass `false` here to opt back in.
+     */
+    customAgentsLocalOnly?: boolean;
+    /**
+     * When true, the runtime instructs the agent to include a `Co-authored-by`
+     * trailer in commit messages it composes.
+     *
+     * Defaults to `true`. Under {@link CopilotClientOptions.mode} = `"empty"`,
+     * defaults to `false`; apps can pass `true` here to opt back in.
+     */
+    coauthorEnabled?: boolean;
+    /**
+     * When true, the `manage_schedule` tool is exposed to the agent.
+     *
+     * Defaults to whatever the runtime exposes (typically gated to staff
+     * users). Under {@link CopilotClientOptions.mode} = `"empty"`, defaults to
+     * `false`; apps can pass `true` here to opt back in.
+     */
+    manageScheduleEnabled?: boolean;
     /**
      * Optional handler for permission requests from the server.
      * When omitted, permission requests are surfaced as events and left pending for
@@ -1514,6 +1637,11 @@ export interface MessageOptions {
      * - "immediate": Send immediately
      */
     mode?: "enqueue" | "immediate";
+    /**
+     * The UI mode the agent was in when this message was sent (for example "plan" or "autopilot").
+     * Defaults to the session's current mode when unset.
+     */
+    agentMode?: "interactive" | "plan" | "autopilot" | "shell";
     /**
      * Custom HTTP headers to include in outbound model requests for this turn.
      */