@github/copilot-sdk 1.0.13-preview.6 → 1.0.14-preview.0

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

@@ -9,9 +9,9 @@ export type JsonValue = null | boolean | number | string | JsonValue[] | {
 /**
  * Union of all session event variants emitted by the Copilot CLI runtime.
  */
-export type SessionEvent = StartEvent | ResumeEvent | RemoteSteerableChangedEvent | ErrorEvent | IdleEvent | TitleChangedEvent | ScheduleCreatedEvent | ScheduleCancelledEvent | ScheduleRearmedEvent | AutopilotObjectiveChangedEvent | InfoEvent | WarningEvent | ModelChangeEvent | ModeChangedEvent | ModeNoticeDeliveredEvent | SessionLimitsChangedEvent | PermissionsChangedEvent | PlanChangedEvent | TodosChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | UsageCheckpointEvent | ContextChangedEvent | UsageInfoEvent | ContextClearedEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | CompletionReceiptEvent | FusionRouteStartedEvent | FusionRouteFailedEvent | FusionResolvedEvent | FusionCompletedEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantFusionPhaseStartedEvent | AssistantFusionPhaseActivityEvent | AssistantFusionPhaseCompletedEvent | AssistantFusionPhaseFailedEvent | AssistantServerToolProgressEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantToolCallDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantIdleEvent | AssistantUsageEvent | ModelCallFailureEvent | ModelCallFinishedEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | ToolSearchActivatedEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentConfiguredEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | HookProgressEvent | BinaryAssetEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | McpHeadersRefreshRequiredEvent | McpHeadersRefreshCompletedEvent | CustomNotificationEvent | UIEphemeralQueryEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | AutoModeSwitchRequestedEvent | AutoModeSwitchCompletedEvent | SessionLimitsExhaustedRequestedEvent | SessionLimitsExhaustedCompletedEvent | AutoModeResolvedEvent | ManagedSettingsResolvedEvent | ManagedSettingsEnforcedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | FactoryRunUpdatedEvent | FactoryRunStartedEvent | FactoryRunSettledEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | McpToolsListChangedEvent | McpResourcesListChangedEvent | McpPromptsListChangedEvent | ExtensionsLoadedEvent | CanvasOpenedEvent | CanvasRegistryChangedEvent | CanvasClosedEvent | CanvasUnavailableEvent | CanvasRecordedEvent | CanvasRemovedEvent | ExtensionsAttachmentsPushedEvent | McpAppToolCallCompleteEvent;
+export type SessionEvent = StartEvent | ResumeEvent | RemoteSteerableChangedEvent | ErrorEvent | IdleEvent | TitleChangedEvent | ScheduleCreatedEvent | ScheduleCancelledEvent | ScheduleRearmedEvent | AutopilotObjectiveChangedEvent | InfoEvent | WarningEvent | ModelChangeEvent | AutoTierRecommendationEvent | AutoTierSwitchFailedEvent | ModeChangedEvent | ModeNoticeDeliveredEvent | SessionLimitsChangedEvent | PermissionsChangedEvent | PlanChangedEvent | TodosChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | UsageCheckpointEvent | ContextChangedEvent | UsageInfoEvent | ContextClearedEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | CompletionReceiptEvent | FusionRouteStartedEvent | FusionRouteFailedEvent | FusionResolvedEvent | FusionCompletedEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantFusionPhaseStartedEvent | AssistantFusionPhaseActivityEvent | AssistantFusionPhaseCompletedEvent | AssistantFusionPhaseFailedEvent | AssistantServerToolProgressEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantToolCallDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantIdleEvent | AssistantUsageEvent | ModelCallFailureEvent | ModelCallFinishedEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | ToolSearchActivatedEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentConfiguredEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | HookProgressEvent | BinaryAssetEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | PermissionCarriedForwardEvent | PermissionMessageAuthorizationEvent | PermissionMessageAuthorizationReadEvent | PermissionMessageAuthorizationDegradedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | McpHeadersRefreshRequiredEvent | McpHeadersRefreshCompletedEvent | CustomNotificationEvent | UIEphemeralQueryEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | AutoModeSwitchRequestedEvent | AutoModeSwitchCompletedEvent | SessionLimitsExhaustedRequestedEvent | SessionLimitsExhaustedCompletedEvent | AutoModeResolvedEvent | ManagedSettingsResolvedEvent | ManagedSettingsEnforcedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | FactoryRunUpdatedEvent | FactoryRunStartedEvent | FactoryRunSettledEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | McpServerRemovedEvent | McpServerNeedsReconnectEvent | McpToolsListChangedEvent | McpResourcesListChangedEvent | McpPromptsListChangedEvent | ExtensionsLoadedEvent | CanvasOpenedEvent | CanvasRegistryChangedEvent | CanvasClosedEvent | CanvasUnavailableEvent | CanvasRecordedEvent | CanvasRemovedEvent | ExtensionsAttachmentsPushedEvent | McpAppToolCallCompleteEvent;
 /**
- * Routing preference used when the session model is `auto`.
+ * Routing preference used when the session model is `auto`. `fast` is an integrator-only latency preset and is not a first-party GitHub Copilot product preference.
  */
 export type AutoTier = 
 /** Optimize for efficiency. */
@@ -19,7 +19,9 @@ export type AutoTier =
 /** Balance efficiency and intelligence. */
  | "balance"
 /** Optimize for intelligence. */
- | "intelligence";
+ | "intelligence"
+/** Integrator-only preset that optimizes for latency. */
+ | "fast";
 /**
  * Hosting platform type of the repository (github or ado)
  */
@@ -56,6 +58,20 @@ export type Verbosity =
  | "medium"
 /** A more detailed response was requested. */
  | "high";
+/**
+ * What the user must do to recover from a failure, named as an action rather than as one client's affordance. The runtime cannot know which affordance a client offers — a slash command, a settings pane, a link — so the accompanying message stays host-agnostic and each client renders its own copy from this value. Absent when the runtime knows of no action the user can take.
+ */
+export type RemediationAction = 
+/** Authenticate again with the Copilot backend. The current credential is absent, expired, or rejected. */
+"sign_in"
+/** Authenticate as a different account. The current account exists but lacks access to the requested resource. */
+ | "switch_account"
+/** Inspect which account is currently authenticated before deciding what to change. */
+ | "show_account"
+/** Review or widen the sandbox policy. The blocked path or host is named by the accompanying message or by the tool result the action arrived with. */
+ | "review_sandbox_policy"
+/** Permit outbound network access in the sandbox policy. */
+ | "allow_sandbox_outbound";
 /**
  * The session mode the agent is operating in
  */
@@ -122,6 +138,28 @@ export type ModelChangeSource =
  | "automatic"
 /** An SDK or RPC caller selected the model. */
  | "sdk";
+/**
+ * Auto preferences that Copilot API can recommend.
+ */
+export type RecommendedAutoTier = 
+/** Optimize for efficiency. */
+"efficiency"
+/** Balance efficiency and intelligence. */
+ | "balance"
+/** Optimize for intelligence. */
+ | "intelligence";
+/**
+ * Terminal reason an Auto preference activation failed.
+ */
+export type AutoTierSwitchFailureReason = 
+/** The candidate model was rejected by model policy. */
+"policy_rejected"
+/** The Auto routing request failed or returned an unusable response. */
+ | "request_failed"
+/** The runtime could not prepare the Auto routing request. */
+ | "setup_failed"
+/** The provider does not support Auto routing. */
+ | "unsupported";
 /**
  * Permission mode for the session.
  */
@@ -444,6 +482,18 @@ export type AbortReason =
  | "user_abort"
 /** Autopilot stopped the run because the active objective reached its user-set --max-ai-credits limit. */
  | "autopilot_credit_limit";
+/**
+ * Transport mechanism: stdio, http, sse (deprecated), or memory (in-process MCP server)
+ */
+export type McpServerTransport = 
+/** Server communicates over stdio with a local child process. */
+"stdio"
+/** Server communicates over streamable HTTP. */
+ | "http"
+/** Server communicates over Server-Sent Events (deprecated). */
+ | "sse"
+/** Server is backed by an in-memory runtime implementation. */
+ | "memory";
 /**
  * Allowed values for the `ToolExecutionStartToolDescriptionMetaUIVisibility` enumeration.
  */
@@ -515,6 +565,36 @@ export type SkillInvokedTrigger =
  | "agent-invoked"
 /** Skill content loaded as part of another context, such as a configured custom agent or subagent. */
  | "context-load";
+/**
+ * Where the model input for a task-tool sub-agent came from.
+ */
+export type SubagentTaskModelSource = 
+/** The spawning agent supplied the task tool's model argument. */
+"task_argument"
+/** The task omitted a model and the per-sub-agent settings entry supplied a concrete one. */
+ | "subagent_configuration"
+/** The task omitted a model and the user-defined custom agent's definition supplied one. */
+ | "custom_agent_definition"
+/** Neither the task call, the per-sub-agent settings entry, nor a custom agent definition supplied a model. */
+ | "unset";
+/**
+ * Authority or runtime mechanism responsible for sub-agent model selection.
+ */
+export type SubagentModelSelectionSource = 
+/** Explicit model supplied by the parent agent on the task call and selected for dispatch. */
+"explicit_override"
+/** Required model policy configured for the sub-agent. */
+ | "configured_required"
+/** Non-required model preference configured for the sub-agent. */
+ | "configured_preference"
+/** Complementary-model default selected for the sub-agent. */
+ | "complementary_default"
+/** Model inherited from the parent session. */
+ | "session_inheritance"
+/** Default model declared by the agent definition. */
+ | "agent_definition_default"
+/** Runtime policy, Auto mode, or an experiment selected the model. */
+ | "runtime_policy";
 /**
  * Binary asset type discriminator. Use "image" for images and "resource" otherwise.
  */
@@ -543,6 +623,24 @@ export type SystemNotificationAgentCompletedStatus =
 "completed"
 /** The agent failed. */
  | "failed";
+/**
+ * Durable metadata describing who initiated a factory pause.
+ */
+export type SystemNotificationFactoryPauseInfo = {
+    /**
+     * Factory pause initiator discriminator.
+     */
+    type: "user";
+} | {
+    /**
+     * Stable author-defined checkpoint key that initiated the pause.
+     */
+    key: string;
+    /**
+     * Factory pause initiator discriminator.
+     */
+    type: "checkpoint";
+};
 /**
  * Terminal status reached by a factory execution attempt.
  */
@@ -551,6 +649,8 @@ export type SystemNotificationFactoryCompletedStatus =
 "completed"
 /** The factory was halted. */
  | "halted"
+/** The factory attempt paused intentionally. */
+ | "paused"
 /** The factory was cancelled. */
  | "cancelled"
 /** The factory failed. */
@@ -640,6 +740,20 @@ export type PermissionPromptRequestPathAccessKind =
  | "shell"
 /** Write access to a filesystem path. */
  | "write";
+/**
+ * Controlled reason or actor responsible for a permission response.
+ */
+export type PermissionDecisionSource = 
+/** The response followed the assisted-approval judge recommendation. */
+"assisted_approval"
+/** A human supplied the response through an interactive prompt. */
+ | "human_response"
+/** The host applied a standing policy or override rather than a judge recommendation or human decision. */
+ | "host_policy"
+/** The host denied the request because no interactive user response was available. */
+ | "unattended_fallback"
+/** A live authorization record from an earlier human decision in this session contained the proposal, so it ran without another prompt. This is not a new human decision and never mints authority of its own. */
+ | "authorization_carry_forward";
 /**
  * The result of the permission request
  */
@@ -648,6 +762,15 @@ export type PermissionResult = PermissionApproved | PermissionApprovedForSession
  * The approval to add as a session-scoped rule
  */
 export type UserToolSessionApproval = UserToolSessionApprovalCommands | UserToolSessionApprovalRead | UserToolSessionApprovalWrite | UserToolSessionApprovalMcp | UserToolSessionApprovalMemory | UserToolSessionApprovalCustomTool | UserToolSessionApprovalExtensionManagement | UserToolSessionApprovalFactory | UserToolSessionApprovalExtensionPermissionAccess | UserToolSessionApprovalExtensionEnvAccess;
+/**
+ * Which direction a message-backed authorization claim moves authority in.
+ */
+/** @experimental */
+export type PermissionMessageAuthorizationPolarity = 
+/** The human's words authorized an effect. */
+"grant"
+/** The human's words refused an effect. */
+ | "denial";
 /**
  * Elicitation mode; "form" for structured input, "url" for browser-based. Defaults to "form" when absent.
  */
@@ -819,6 +942,8 @@ export type FactoryRunSettledStatus =
 "completed"
 /** The run was stopped by a limit, an approval refusal or another policy decision. */
  | "halted"
+/** The attempt paused intentionally while preserving resumable run state. */
+ | "paused"
 /** The run was cancelled by its caller or by session disposal. */
  | "cancelled"
 /** The run failed, with `failureType` carrying the class when it has one. */
@@ -881,18 +1006,6 @@ export type McpServerStatus =
  | "stopped"
 /** The server is not configured for this session. */
  | "not_configured";
-/**
- * Transport mechanism: stdio, http, sse (deprecated), or memory (in-process MCP server)
- */
-export type McpServerTransport = 
-/** Server communicates over stdio with a local child process. */
-"stdio"
-/** Server communicates over streamable HTTP. */
- | "http"
-/** Server communicates over Server-Sent Events (deprecated). */
- | "sse"
-/** Server is backed by an in-memory runtime implementation. */
- | "memory";
 /**
  * Discovery source
  */
@@ -1246,6 +1359,7 @@ export interface ErrorData {
      * GitHub request tracing ID (x-github-request-id header) for correlating with server-side logs
      */
     providerCallId?: string;
+    remediation?: RemediationAction;
     /**
      * Copilot service request ID (x-copilot-service-request-id header) for CAPI log correlation
      */
@@ -1626,6 +1740,7 @@ export interface WarningData {
      * Human-readable warning message for display in the timeline
      */
     message: string;
+    remediation?: RemediationAction;
     /**
      * Optional URL associated with this warning that the user can open in a browser
      */
@@ -1669,6 +1784,10 @@ export interface ModelChangeEvent {
  * Model change details including previous and new model identifiers
  */
 export interface ModelChangeData {
+    /**
+     * Committed Auto preference after the model configuration change, when applicable.
+     */
+    autoTier?: AutoTier | null;
     /**
      * Reason the change happened, when not user-initiated. `"rate_limit_auto_switch"` for changes triggered by the auto-mode-switch rate-limit recovery path, or `"refusal_fallback"` when the active model declined a request (content refusal) and the runtime switched to the configured refusal-fallback model. UI clients can use this to render contextual copy.
      */
@@ -1681,6 +1800,7 @@ export interface ModelChangeData {
      * Newly selected model identifier
      */
     newModel: string;
+    previousAutoTier?: AutoTier;
     /**
      * Model that was previously selected, if any
      */
@@ -1699,6 +1819,85 @@ export interface ModelChangeData {
     source?: ModelChangeSource;
     verbosity?: Verbosity;
 }
+/**
+ * Session event "session.auto_tier_recommendation". Live-only Auto preference recommendation from Copilot API after a successful Auto model call.
+ */
+/** @experimental */
+export interface AutoTierRecommendationEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: AutoTierRecommendationData;
+    /**
+     * 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 "session.auto_tier_recommendation".
+     */
+    type: "session.auto_tier_recommendation";
+}
+/**
+ * Live-only Auto preference recommendation from Copilot API after a successful Auto model call.
+ */
+/** @experimental */
+export interface AutoTierRecommendationData {
+    recommendedAutoTier: RecommendedAutoTier;
+}
+/**
+ * Session event "session.auto_tier_switch_failed". A transient Auto preference failure emitted when the runtime cannot mint or accept a usable model and token pair. The previously effective preference remains active, so SDK clients can surface a non-blocking failure without changing their committed-tier state. This event is ephemeral and is not persisted or replayed on resume.
+ */
+export interface AutoTierSwitchFailedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: AutoTierSwitchFailedData;
+    /**
+     * 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 "session.auto_tier_switch_failed".
+     */
+    type: "session.auto_tier_switch_failed";
+}
+/**
+ * A transient Auto preference failure emitted when the runtime cannot mint or accept a usable model and token pair. The previously effective preference remains active, so SDK clients can surface a non-blocking failure without changing their committed-tier state. This event is ephemeral and is not persisted or replayed on resume.
+ */
+export interface AutoTierSwitchFailedData {
+    effectiveAutoTier?: AutoTier;
+    reason: AutoTierSwitchFailureReason;
+    /**
+     * Auto preference that failed to activate, or null when returning to provider-default routing failed.
+     */
+    requestedAutoTier: AutoTier | null;
+}
 /**
  * Session event "session.mode_changed". Agent mode change details including previous and new modes
  */
@@ -1862,13 +2061,13 @@ export interface PermissionsChangedData {
      *
      * @experimental
      */
-    mode: PermissionMode;
+    mode?: PermissionMode;
     /**
      * Permission mode before the change
      *
      * @experimental
      */
-    previousMode: PermissionMode;
+    previousMode?: PermissionMode;
 }
 /**
  * Session event "session.plan_changed". Plan file operation details indicating what changed
@@ -2774,6 +2973,10 @@ export interface CompactionCompleteCompactionTokensUsedCopilotUsageTokenDetail {
      * Cost per batch of tokens
      */
     costPerBatch: number;
+    /**
+     * Model responsible for this billing entry
+     */
+    model?: string;
     /**
      * Total token count for this entry
      */
@@ -5192,6 +5395,10 @@ export interface AssistantUsageData {
  * Per-request cost and usage data from the CAPI copilot_usage response field
  */
 export interface AssistantUsageCopilotUsage {
+    /**
+     * Default billing model for token details that do not identify their own model
+     */
+    model?: string;
     /**
      * Total cost in nano-AI units for this request
      */
@@ -5209,6 +5416,10 @@ export interface AssistantUsageCopilotUsageTokenDetail {
      * Cost per batch of tokens
      */
     costPerBatch: number;
+    /**
+     * Model responsible for this billing entry
+     */
+    model?: string;
     /**
      * Total token count for this entry
      */
@@ -5561,6 +5772,7 @@ export interface ToolExecutionStartData {
      * Original tool name on the MCP server, when the tool is an MCP tool
      */
     mcpToolName?: string;
+    mcpTransport?: McpServerTransport;
     /**
      * Model identifier that generated this tool call
      */
@@ -5832,6 +6044,7 @@ export interface ToolExecutionCompleteError {
      * Human-readable error message
      */
     message: string;
+    remediation?: RemediationAction;
 }
 /**
  * Tool execution result on success
@@ -6494,6 +6707,7 @@ export interface SubagentStartedData {
      * Whether this sub-agent can be resumed. Currently always false.
      */
     resumable?: boolean;
+    taskModelSource?: SubagentTaskModelSource;
     /**
      * Tool call ID of the parent tool invocation that spawned this sub-agent
      */
@@ -6628,6 +6842,7 @@ export interface SubagentCompletedData {
      * Why an explicit task-call model did not become the effective model
      */
     modelOverrideReason?: string;
+    modelSelectionSource?: SubagentModelSelectionSource;
     /**
      * Tool call ID of the parent tool invocation that spawned this sub-agent
      */
@@ -6719,6 +6934,7 @@ export interface SubagentFailedData {
      * Why an explicit task-call model did not become the effective model
      */
     modelOverrideReason?: string;
+    modelSelectionSource?: SubagentModelSelectionSource;
     /**
      * Tool call ID of the parent tool invocation that spawned this sub-agent
      */
@@ -7319,6 +7535,7 @@ export interface SystemNotificationFactoryCompleted {
      * Machine-readable terminal failure details, when present.
      */
     failure?: JsonValue;
+    pauseInfo?: SystemNotificationFactoryPauseInfo;
     /**
      * Bounded prompt-safe preview of the completed result.
      */
@@ -7445,13 +7662,31 @@ export interface PermissionRequestShell {
      */
     possibleUrls: PermissionRequestShellPossibleUrl[];
     /**
-     * True when the model has requested to run this command outside the sandbox (it set requestSandboxBypass: true and the host opted in via sandbox.allowBypass). This is a request, not a grant: the command runs unsandboxed only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
+     * True when the tool is asking to run this command outside the sandbox, either because the command detaches and cannot be sandboxed at all, or because a sandboxed run looked blocked (host opted in via sandbox.allowBypass). The model cannot ask for this; only the tool raises it. This is a request, not a grant: the command runs unsandboxed only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
      */
     requestSandboxBypass?: boolean;
     /**
-     * Model-provided justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true.
+     * What the tool tells the user about the bypass on offer: which policy rule blocked the call, or why it cannot be sandboxed. Only meaningful when requestSandboxBypass is true.
      */
     requestSandboxBypassReason?: string;
+    /**
+     * True when the requested escalation is a permissive retry rather than a full bypass: the command re-runs inside the sandbox with its file and process restrictions recording instead of blocking, while the network policy stays enforced. Always accompanied by requestSandboxBypass, so hosts that do not recognize this field still treat the request as the escalation it is. Hosts that do recognize it must not describe the command as running outside the sandbox, which would overstate the privilege being granted.
+     */
+    requestSandboxPermissive?: boolean;
+    /**
+     * Runtime-resolved canonical object each possiblePaths entry names, keyed by the requested spelling, used for authorization identity checks. Internal and experimental; clients should continue to display possiblePaths.
+     *
+     * @experimental
+     */
+    resolvedPaths?: {
+        [k: string]: string | undefined;
+    };
+    /**
+     * Runtime-resolved canonical working directory the command runs in, used for authorization identity checks. Internal and experimental; clients should not display it.
+     *
+     * @experimental
+     */
+    resolvedWorkingDirectory?: string;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -7536,6 +7771,12 @@ export interface PermissionRequestWrite {
      * Justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true.
      */
     requestSandboxBypassReason?: string;
+    /**
+     * Runtime-resolved canonical path used for authorization identity checks. Internal and experimental; clients should continue to display fileName.
+     *
+     * @experimental
+     */
+    resolvedPath?: string;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -7562,13 +7803,19 @@ export interface PermissionRequestRead {
      */
     path: string;
     /**
-     * True when the model has requested to run this search outside the sandbox (it set requestSandboxBypass: true and the host opted in via sandbox.allowBypass). This is a request, not a grant: the search runs unsandboxed only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
+     * True when the tool is asking to re-run this search outside the sandbox, after a sandboxed run looked blocked (host opted in via sandbox.allowBypass). The model cannot ask for this; only the tool raises it. This is a request, not a grant: the search runs unsandboxed only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
      */
     requestSandboxBypass?: boolean;
     /**
-     * Model-provided justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true.
+     * What the tool tells the user about the bypass on offer: which policy rule blocked the call, or why it cannot be sandboxed. Only meaningful when requestSandboxBypass is true.
      */
     requestSandboxBypassReason?: string;
+    /**
+     * Runtime-resolved canonical path used for authorization identity checks. Internal and experimental; clients should continue to display path.
+     *
+     * @experimental
+     */
+    resolvedPath?: string;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -7634,11 +7881,11 @@ export interface PermissionRequestUrl {
      */
     redirectedFrom?: string;
     /**
-     * True when this URL fetch is requesting to bypass the sandbox network policy: either the model set requestSandboxBypass: true, or the tool re-issued the request as an interactive bypass after the network policy denied the approved URL (host opted in via sandbox.allowBypass). This is a request, not a grant: the fetch runs only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
+     * True when the tool is asking to run this URL fetch outside the sandbox, after the network policy denied the approved URL or the sandbox proxy could not reach it (host opted in via sandbox.allowBypass). The model cannot ask for this; only the tool raises it. This is a request, not a grant: the fetch runs only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
      */
     requestSandboxBypass?: boolean;
     /**
-     * Model-provided justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true.
+     * What the tool tells the user about the bypass on offer: which policy rule blocked the call, or why it cannot be sandboxed. Only meaningful when requestSandboxBypass is true.
      */
     requestSandboxBypassReason?: string;
     /**
@@ -7940,6 +8187,18 @@ export interface PermissionPromptRequestCommands {
      * Whether managed policy requires a human response and forbids host auto-approval
      */
     managedApprovalRequired?: boolean;
+    /**
+     * True when the shell command is requesting sandbox escalation. This is a request, not a grant.
+     */
+    requestSandboxBypass?: boolean;
+    /**
+     * Reason for the sandbox escalation request.
+     */
+    requestSandboxBypassReason?: string;
+    /**
+     * True when the escalation is a permissive retry that keeps the sandbox and network policy attached while recording file and process accesses instead of blocking them.
+     */
+    requestSandboxPermissive?: boolean;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -7987,6 +8246,12 @@ export interface PermissionPromptRequestWrite {
      * Complete new file contents for newly created files
      */
     newFileContents?: string;
+    /**
+     * Runtime-resolved canonical path used for authorization identity checks. Internal and experimental; clients should continue to display fileName.
+     *
+     * @experimental
+     */
+    resolvedPath?: string;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -8018,6 +8283,12 @@ export interface PermissionPromptRequestRead {
      * Path of the file or directory being read
      */
     path: string;
+    /**
+     * Runtime-resolved canonical path used for authorization identity checks. Internal and experimental; clients should continue to display path.
+     *
+     * @experimental
+     */
+    resolvedPath?: string;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -8095,11 +8366,11 @@ export interface PermissionPromptRequestUrl {
      */
     redirectedFrom?: string;
     /**
-     * True when this URL fetch is requesting to bypass the sandbox network policy: either the model set requestSandboxBypass: true, or the tool re-issued the request as an interactive bypass after the network policy denied the approved URL (host opted in via sandbox.allowBypass). This is a request, not a grant: the fetch runs only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
+     * True when the tool is asking to run this URL fetch outside the sandbox, after the network policy denied the approved URL or the sandbox proxy could not reach it (host opted in via sandbox.allowBypass). The model cannot ask for this; only the tool raises it. This is a request, not a grant: the fetch runs only if the user approves this permission request. Hosts should highlight the elevated risk in the approval UI.
      */
     requestSandboxBypass?: boolean;
     /**
-     * Model-provided justification for the sandbox-bypass request. Only meaningful when requestSandboxBypass is true.
+     * What the tool tells the user about the bypass on offer: which policy rule blocked the call, or why it cannot be sandboxed. Only meaningful when requestSandboxBypass is true.
      */
     requestSandboxBypassReason?: string;
     /**
@@ -8427,6 +8698,12 @@ export interface PermissionCompletedEvent {
  * Permission request completion notification signaling UI dismissal
  */
 export interface PermissionCompletedData {
+    /**
+     * Who decided this permission request. Absent on completions recorded before this field existed, which consumers must treat as "not a human decision" rather than assuming one. Authorization records are minted only for `human_response`; an assisted-approval verdict, a host policy, an unattended fallback, and a hook resolution all produce the same `result` a person does, so this is the only field that distinguishes them.
+     *
+     * @experimental
+     */
+    decisionSource?: PermissionDecisionSource;
     /**
      * Request ID of the resolved permission request; clients should dismiss any UI for this request
      */
@@ -8709,6 +8986,244 @@ export interface PermissionDeniedByPermissionRequestHook {
      */
     message?: string;
 }
+/**
+ * Session event "permission.carriedForward". Records that a live authorization record from an earlier human decision in this session contained a permission proposal, so it ran without another prompt. This mints no authority: it accounts for one more effect against the prior grant, which is what lets a replayed session agree with the live one about how much of that grant is left.
+ */
+/** @experimental */
+export interface PermissionCarriedForwardEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: PermissionCarriedForwardData;
+    /**
+     * 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 "permission.carriedForward".
+     */
+    type: "permission.carriedForward";
+}
+/**
+ * Records that a live authorization record from an earlier human decision in this session contained a permission proposal, so it ran without another prompt. This mints no authority: it accounts for one more effect against the prior grant, which is what lets a replayed session agree with the live one about how much of that grant is left.
+ */
+/** @experimental */
+export interface PermissionCarriedForwardData {
+    /**
+     * Always `authorization_carry_forward`. Stated explicitly so a consumer reading this event cannot mistake it for a human, host-policy, or assisted-approval decision.
+     *
+     * @experimental
+     */
+    decisionSource: PermissionDecisionSource;
+    /**
+     * Identity of the prior authorization record that contained the proposal.
+     *
+     * @experimental
+     */
+    recordId: string;
+    /**
+     * Authorization edge minted for this admission. Not a prompt id: no prompt was raised, so no client should expect a request with this id.
+     *
+     * @experimental
+     */
+    requestId: string;
+    /**
+     * Tool call this admission authorizes. Its execution receipts the prior grant, which is how a single-effect approval is spent rather than carried forward again.
+     *
+     * @experimental
+     */
+    toolCallId: string;
+}
+/**
+ * Session event "permission.messageAuthorization". Freezes one blinded, verbatim-verified authorization claim the runtime minted from a human user message, so a resumed session re-establishes the same grant deterministically instead of re-running the extraction model. This mints no authority on its own: it records what a blinded proposer pointed at and the trusted discriminator the runtime established, and deterministic establishment runs on replay. Persisted so recorded authority survives compaction and process resume.
+ */
+/** @experimental */
+export interface PermissionMessageAuthorizationEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: PermissionMessageAuthorizationData;
+    /**
+     * 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 "permission.messageAuthorization".
+     */
+    type: "permission.messageAuthorization";
+}
+/**
+ * Freezes one blinded, verbatim-verified authorization claim the runtime minted from a human user message, so a resumed session re-establishes the same grant deterministically instead of re-running the extraction model. This mints no authority on its own: it records what a blinded proposer pointed at and the trusted discriminator the runtime established, and deterministic establishment runs on replay. Persisted so recorded authority survives compaction and process resume.
+ */
+/** @experimental */
+export interface PermissionMessageAuthorizationData {
+    /**
+     * The kind of effect authorized, as an action-class identifier.
+     *
+     * @experimental
+     */
+    actionClass: string;
+    /**
+     * Whether the claim granted or denied authority.
+     *
+     * @experimental
+     */
+    polarity: PermissionMessageAuthorizationPolarity;
+    /**
+     * Deterministic identity of the record, derived from the turn and span offsets so re-extracting the same span mints nothing new.
+     *
+     * @experimental
+     */
+    recordId: string;
+    /**
+     * End byte offset of the authorizing span within the turn.
+     *
+     * @experimental
+     */
+    spanEnd: number;
+    /**
+     * Start byte offset of the authorizing span within the turn.
+     *
+     * @experimental
+     */
+    spanStart: number;
+    /**
+     * Concrete named targets that appear verbatim inside the span.
+     *
+     * @experimental
+     */
+    targetMembers?: string[];
+    /**
+     * The task the permission is scoped to, when the human named one.
+     *
+     * @experimental
+     */
+    task?: string;
+    /**
+     * The human turn the quoted span was read from.
+     *
+     * @experimental
+     */
+    turnIndex: number;
+    /**
+     * The trusted version discriminator, when one exists. Exact shell-command grants carry the byte-identical commands grounded in the human span; world-derived classes carry a file object, remote tip, or runner only when that state was captured safely. An opaque object mirroring the runtime's adjacently-tagged resolution.
+     *
+     * @experimental
+     */
+    world?: JsonValue;
+}
+/**
+ * Session event "permission.messageAuthorizationRead". Records that one human turn has been read by the blinded authorization proposer, whether or not it minted anything, so a resumed session does not re-run the extraction model on a turn the live session already read. Persisted purely to avoid wasted model calls across resume; it is never a correctness mechanism.
+ */
+/** @experimental */
+export interface PermissionMessageAuthorizationReadEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: PermissionMessageAuthorizationReadData;
+    /**
+     * 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 "permission.messageAuthorizationRead".
+     */
+    type: "permission.messageAuthorizationRead";
+}
+/**
+ * Records that one human turn has been read by the blinded authorization proposer, whether or not it minted anything, so a resumed session does not re-run the extraction model on a turn the live session already read. Persisted purely to avoid wasted model calls across resume; it is never a correctness mechanism.
+ */
+/** @experimental */
+export interface PermissionMessageAuthorizationReadData {
+    /**
+     * The human turn that was read by the proposer.
+     *
+     * @experimental
+     */
+    turnIndex: number;
+}
+/**
+ * Session event "permission.messageAuthorizationDegraded". Records that message-backed authorization could not safely represent one human turn before compaction. The runtime may compact the original message after this marker is durable, but message-derived carry-forward and assisted auto-approval remain disabled for the rest of the session so subsequent commands continue through the ordinary permission prompt.
+ */
+/** @experimental */
+export interface PermissionMessageAuthorizationDegradedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: PermissionMessageAuthorizationDegradedData;
+    /**
+     * 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 "permission.messageAuthorizationDegraded".
+     */
+    type: "permission.messageAuthorizationDegraded";
+}
+/**
+ * Records that message-backed authorization could not safely represent one human turn before compaction. The runtime may compact the original message after this marker is durable, but message-derived carry-forward and assisted auto-approval remain disabled for the rest of the session so subsequent commands continue through the ordinary permission prompt.
+ */
+/** @experimental */
+export interface PermissionMessageAuthorizationDegradedData {
+    /**
+     * The human turn that could not be represented safely.
+     *
+     * @experimental
+     */
+    turnIndex: number;
+}
 /**
  * Session event "user_input.requested". User input request notification with question and optional predefined choices
  */
@@ -10602,6 +11117,10 @@ export interface CustomAgentsUpdatedAgent {
      * Description of what the agent does
      */
     description: string;
+    /**
+     * Whether model-driven invocation is disabled for this agent.
+     */
+    disableModelInvocation?: boolean;
     /**
      * Human-readable display name
      */
@@ -10695,10 +11214,20 @@ export interface McpServersLoadedServer {
      * Version of the plugin that supplied the effective MCP server config, only when source is plugin
      */
     pluginVersion?: string;
+    serverMetadata?: McpServerMetadata;
     source?: McpServerSource;
     status: McpServerStatus;
     transport?: McpServerTransport;
 }
+/**
+ * Server-advertised metadata learned through modern discovery or legacy initialization.
+ */
+export interface McpServerMetadata {
+    /**
+     * Non-empty natural-language guidance for using the server, or null when the server omitted instructions or advertised an empty string.
+     */
+    instructions: string | null;
+}
 /**
  * Session event "session.mcp_server_status_changed". Payload of `session.mcp_server_status_changed` for one MCP server's status and optional failure error.
  */
@@ -10743,6 +11272,84 @@ export interface McpServerStatusChangedData {
     serverName: string;
     status: McpServerStatus;
 }
+/**
+ * Session event "session.mcp_server_removed". Payload of `session.mcp_server_removed` identifying an MCP server the graph no longer runs.
+ */
+export interface McpServerRemovedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: McpServerRemovedData;
+    /**
+     * 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 "session.mcp_server_removed".
+     */
+    type: "session.mcp_server_removed";
+}
+/**
+ * Payload of `session.mcp_server_removed` identifying an MCP server the graph no longer runs.
+ */
+export interface McpServerRemovedData {
+    /**
+     * Name of the MCP server that was removed from the graph
+     */
+    serverName: string;
+}
+/**
+ * Session event "session.mcp_server_needs_reconnect". Payload of `session.mcp_server_needs_reconnect` identifying an MCP server whose connection must be re-established.
+ */
+export interface McpServerNeedsReconnectEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: McpServerNeedsReconnectData;
+    /**
+     * 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 "session.mcp_server_needs_reconnect".
+     */
+    type: "session.mcp_server_needs_reconnect";
+}
+/**
+ * Payload of `session.mcp_server_needs_reconnect` identifying an MCP server whose connection must be re-established.
+ */
+export interface McpServerNeedsReconnectData {
+    /**
+     * Name of the MCP server that needs to reconnect
+     */
+    serverName: string;
+}
 /**
  * Session event "mcp.tools.list_changed". Payload identifying the MCP server associated with a list change.
  */