@github/copilot-sdk-darwin-arm64 1.0.15 → 1.0.16

package/schemas/api.schema.json

@@ -3,6 +3,158 @@
   "title": "CopilotApi",
   "description": "Describes all JSON-RPC methods exposed by the Copilot CLI server. SDK codegen tools consume this to produce typed client wrappers.",
   "server": {
+    "environments": {
+      "list": {
+        "rpcMethod": "environments.list",
+        "description": "Lists GitHub Mission Control environments visible to the authenticated identity. Does not require a running host and excludes host relay credentials.",
+        "params": {
+          "$ref": "#/definitions/EnvironmentsListRequest",
+          "description": "Optional discovery filters supported by GitHub Mission Control."
+        },
+        "result": {
+          "$ref": "#/definitions/EnvironmentsListResult",
+          "description": "Environments visible to the authenticated caller and matching the supplied filters."
+        },
+        "stability": "experimental"
+      },
+      "get": {
+        "rpcMethod": "environments.get",
+        "description": "Gets safe discovery information for a GitHub Mission Control environment without requiring a running host.",
+        "params": {
+          "$ref": "#/definitions/EnvironmentsGetRequest",
+          "description": "Identify a Mission Control environment to retrieve."
+        },
+        "result": {
+          "$ref": "#/definitions/EnvironmentsGetResult",
+          "description": "Safe discovery information for the requested environment."
+        },
+        "stability": "experimental"
+      },
+      "delete": {
+        "rpcMethod": "environments.delete",
+        "description": "Deletes a user-managed GitHub Mission Control environment. GitHub-managed environments cannot be deleted. Does not stop a running host, which may register again.",
+        "params": {
+          "$ref": "#/definitions/EnvironmentsDeleteRequest",
+          "description": "Identify a user-managed Mission Control environment to delete."
+        },
+        "result": {
+          "$ref": "#/definitions/EnvironmentsDeleteResult",
+          "description": "Acknowledgement that the requested environment was deleted."
+        },
+        "stability": "experimental"
+      }
+    },
+    "host": {
+      "publishSession": {
+        "rpcMethod": "host.publishSession",
+        "description": "Publishes an attached resident session for this listener's lifetime without copying it.",
+        "params": {
+          "$ref": "#/definitions/HostPublishSessionRequest",
+          "description": "Publishes a resident session attached to the listener's owning connection."
+        },
+        "result": {
+          "$ref": "#/definitions/HostPublishSessionResult",
+          "description": "The existing runtime identity and its resource on the listener."
+        },
+        "stability": "experimental"
+      },
+      "createSession": {
+        "rpcMethod": "host.createSession",
+        "description": "Requests app-owned materialization over the owning SDK participant.",
+        "params": {
+          "$ref": "#/definitions/HostSessionCreateRequest",
+          "description": "One application-owned session handoff, requested by the supervised hosting participant."
+        },
+        "result": {
+          "$ref": "#/definitions/HostSessionCreateResult",
+          "description": "The resident session the application has materialized on its own connection."
+        },
+        "stability": "experimental",
+        "visibility": "internal"
+      },
+      "releaseSession": {
+        "rpcMethod": "host.releaseSession",
+        "description": "Releases app ownership retention after AHP detaches.",
+        "params": {
+          "$ref": "#/definitions/HostSessionReleaseRequest",
+          "description": "Ends one participation, not the application's session lifetime."
+        },
+        "result": {
+          "$ref": "#/definitions/HostEmptyResult",
+          "description": "Empty acknowledgement for a completed host lifecycle operation."
+        },
+        "stability": "experimental",
+        "visibility": "internal"
+      },
+      "start": {
+        "rpcMethod": "host.start",
+        "description": "Starts a connection-owned AHP host with explicit localServer and/or githubEnvironment transports as a supervised SDK participant.",
+        "params": {
+          "$ref": "#/definitions/HostStartRequest",
+          "description": "Starts a supervised AHP host with at least one explicitly selected transport."
+        },
+        "result": {
+          "$ref": "#/definitions/HostStartResult",
+          "description": "Listener readiness, returned only after binding and the supervised participant's SDK handshake."
+        },
+        "stability": "experimental"
+      },
+      "dispose": {
+        "rpcMethod": "host.dispose",
+        "description": "Stops a listener owned by this SDK connection and joins its cleanup without deleting sessions.",
+        "params": {
+          "$ref": "#/definitions/HostDisposeRequest",
+          "description": "Stops a connection-owned listener and joins its teardown."
+        },
+        "result": {
+          "$ref": "#/definitions/HostEmptyResult",
+          "description": "Empty acknowledgement for a completed host lifecycle operation."
+        },
+        "stability": "experimental"
+      },
+      "getEnvironmentCredentials": {
+        "rpcMethod": "host.getEnvironmentCredentials",
+        "description": "Resolves current authenticated credentials and remote-control policy only for the runtime-owned Mission Control hosting participant.",
+        "params": {
+          "$ref": "#/definitions/HostEmptyResult",
+          "description": "Empty acknowledgement for a completed host lifecycle operation."
+        },
+        "result": {
+          "$ref": "#/definitions/HostEnvironmentCredentials",
+          "description": "Private credentials delivered only to a runtime-owned Mission Control hosting participant."
+        },
+        "stability": "experimental",
+        "visibility": "internal"
+      },
+      "getConfiguration": {
+        "rpcMethod": "host.getConfiguration",
+        "description": "Returns listener settings only to the supervised hosting participant over its SDK connection.",
+        "params": {
+          "$ref": "#/definitions/HostEmptyResult",
+          "description": "Empty acknowledgement for a completed host lifecycle operation."
+        },
+        "result": {
+          "$ref": "#/definitions/HostConfiguration",
+          "description": "Normalized listener settings delivered only to the supervised hosting participant."
+        },
+        "stability": "experimental",
+        "visibility": "internal"
+      },
+      "ready": {
+        "rpcMethod": "host.ready",
+        "description": "Reports a supervised hosting participant's bound AHP endpoint after its SDK handshake.",
+        "params": {
+          "$ref": "#/definitions/HostReadyRequest",
+          "description": "Readiness reported by the supervised hosting participant on its own SDK connection."
+        },
+        "result": {
+          "$ref": "#/definitions/HostEmptyResult",
+          "description": "Empty acknowledgement for a completed host lifecycle operation."
+        },
+        "stability": "experimental",
+        "visibility": "internal"
+      }
+    },
     "ping": {
       "rpcMethod": "ping",
       "description": "Checks server responsiveness and returns protocol information.",
@@ -1681,6 +1833,40 @@
           "description": "Result of attempting to disable sandboxing for the current session."
         },
         "stability": "experimental"
+      },
+      "grantPathForRequest": {
+        "rpcMethod": "session.sandbox.grantPathForRequest",
+        "description": "Adds the path offered by a pending sandbox escalation permission request's sandboxPathGrant to the session's sandbox policy and approves the request, so the blocked operation re-runs inside the sandbox rather than outside it. The request is rejected unless the exact request is still pending, carries a sandboxPathGrant, and the grant still takes effect under the current managed policy. Does not persist the path; hosts that store sandbox settings save it themselves.",
+        "params": {
+          "type": "object",
+          "properties": {
+            "sessionId": {
+              "type": "string",
+              "description": "Target session identifier"
+            },
+            "requestId": {
+              "type": "string",
+              "description": "Identifier of the exact pending sandbox escalation permission request whose sandboxPathGrant to accept."
+            },
+            "decisionContext": {
+              "$ref": "#/definitions/PermissionDecisionContext",
+              "description": "Optional attribution for the permission decision."
+            }
+          },
+          "required": [
+            "sessionId",
+            "requestId"
+          ],
+          "additionalProperties": false,
+          "description": "Request to accept the sandbox path grant offered on an active sandbox escalation permission prompt.",
+          "title": "SandboxGrantPathForRequestRequest",
+          "stability": "experimental"
+        },
+        "result": {
+          "$ref": "#/definitions/SandboxGrantPathForRequestResult",
+          "description": "Result of accepting a sandbox path grant."
+        },
+        "stability": "experimental"
       }
     },
     "sendSystemNotification": {
@@ -7615,6 +7801,39 @@
           "description": "The selectable model entries and selection ids synthesized for the synchronized BYOK models."
         },
         "stability": "experimental"
+      },
+      "withdraw": {
+        "rpcMethod": "session.provider.withdraw",
+        "description": "Withdraws named host-managed models from the session's BYOK registry, leaving every other entry untouched. The scoped counterpart to `provider.sync`: a snapshot can only describe entries the caller knows about, so using it to remove one model silently withdraws rows registered by another source, such as a plugin calling `provider.add` at runtime. Naming what to remove leaves unrelated entries alone. Selection ids that are not registered are ignored, so withdrawal is idempotent. A provider is removed only when one of the withdrawn models was the last entry referencing it; a provider that simply has no models, which is the normal state while its rows are supplied by catalog discovery, is left in place.",
+        "params": {
+          "type": "object",
+          "properties": {
+            "sessionId": {
+              "type": "string",
+              "description": "Target session identifier"
+            },
+            "models": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Provider-qualified selection ids to withdraw. Ids that are not registered are ignored, so withdrawal is idempotent. A provider left with no models referencing it is removed too."
+            }
+          },
+          "required": [
+            "sessionId",
+            "models"
+          ],
+          "additionalProperties": false,
+          "description": "Host-managed model selection ids to withdraw from the session's BYOK registry.",
+          "title": "ProviderWithdrawRequest",
+          "stability": "experimental"
+        },
+        "result": {
+          "$ref": "#/definitions/ProviderWithdrawResult",
+          "description": "What the withdrawal actually removed from the registry."
+        },
+        "stability": "experimental"
       }
     },
     "options": {
@@ -7748,7 +7967,8 @@
             },
             "sandboxConfigSource": {
               "$ref": "#/definitions/SandboxConfigSource",
-              "description": "Origin of the sandbox choice. Settings-derived origins (never_configured, user_enabled, user_disabled, repository_policy) let managed policy floor a host preference; explicit below-floor changes remain policy conflicts unless a session opt-out is authorized. Also used for telemetry provenance."
+              "description": "Origin of the sandbox choice. Settings-derived origins (never_configured, user_enabled, user_disabled, repository_policy) let managed policy floor a host preference; explicit below-floor changes remain policy conflicts unless a session opt-out is authorized. Also used for telemetry provenance.",
+              "stability": "experimental"
             },
             "logInteractiveShells": {
               "type": "boolean",
@@ -12810,6 +13030,77 @@
     }
   },
   "clientGlobal": {
+    "host": {
+      "registerSession": {
+        "rpcMethod": "host.registerSession",
+        "description": "Registers an existing resident session on the supervised listener without durable adoption.",
+        "params": {
+          "$ref": "#/definitions/HostRegisterSessionRequest",
+          "description": "Listener-scoped registration, not a copy or durable adoption of a session."
+        },
+        "result": {
+          "$ref": "#/definitions/HostPublishSessionResult",
+          "description": "The existing runtime identity and its resource on the listener."
+        },
+        "stability": "experimental",
+        "visibility": "internal"
+      },
+      "materializeSession": {
+        "rpcMethod": "host.materializeSession",
+        "description": "Materializes an AHP session in the owning application.",
+        "params": {
+          "$ref": "#/definitions/HostSessionCreateCallback",
+          "description": "Application callback routed over its existing SDK connection."
+        },
+        "result": {
+          "$ref": "#/definitions/HostSessionCreateResult",
+          "description": "The resident session the application has materialized on its own connection."
+        },
+        "stability": "experimental",
+        "visibility": "internal"
+      },
+      "sessionReleased": {
+        "rpcMethod": "host.sessionReleased",
+        "description": "Ends application object retention for an AHP participation.",
+        "params": {
+          "$ref": "#/definitions/HostSessionReleasedNotification",
+          "description": "Releases the original application session object retained for one handoff."
+        },
+        "result": {
+          "type": "null"
+        },
+        "notification": true,
+        "stability": "experimental",
+        "visibility": "internal"
+      },
+      "shutdown": {
+        "rpcMethod": "host.shutdown",
+        "description": "Requests graceful shutdown of a supervised AHP listener and its clients.",
+        "params": {
+          "$ref": "#/definitions/HostEmptyResult",
+          "description": "Empty acknowledgement for a completed host lifecycle operation."
+        },
+        "result": {
+          "$ref": "#/definitions/HostEmptyResult",
+          "description": "Empty acknowledgement for a completed host lifecycle operation."
+        },
+        "stability": "experimental",
+        "visibility": "internal"
+      },
+      "exited": {
+        "rpcMethod": "host.exited",
+        "description": "Reports termination of a connection-owned host listener.",
+        "params": {
+          "$ref": "#/definitions/HostExitedNotification",
+          "description": "Reports a supervised listener's hosting-task termination and cleanup outcome."
+        },
+        "result": {
+          "type": "null"
+        },
+        "notification": true,
+        "stability": "experimental"
+      }
+    },
     "hooks": {
       "invoke": {
         "rpcMethod": "hooks.invoke",
@@ -21507,6 +21798,133 @@
       "description": "Authentication-info input variant for a token sourced from an environment variable, with host, optional login, token, and env var name.",
       "title": "EnvAuthInfo"
     },
+    "EnvironmentCapabilities": {
+      "type": "object",
+      "properties": {
+        "ahpVersion": {
+          "type": "string",
+          "description": "Advertised Agent Host Protocol version."
+        },
+        "features": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Feature identifiers advertised by the environment."
+        },
+        "maxSessions": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum session capacity, when advertised."
+        },
+        "currentSessions": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Current session count, when advertised."
+        }
+      },
+      "required": [
+        "features"
+      ],
+      "description": "Hosting capabilities and session capacity advertised by an environment."
+    },
+    "EnvironmentKind": {
+      "type": "string",
+      "enum": [
+        "user-local",
+        "user-codespace",
+        "managed-actions",
+        "managed-sandbox",
+        "managed-cca"
+      ],
+      "description": "GitHub Mission Control compute kind.",
+      "x-enumDescriptions": {
+        "user-local": "A user-managed environment on a local machine.",
+        "user-codespace": "A user-managed environment in a GitHub Codespace.",
+        "managed-actions": "A GitHub-managed environment backed by GitHub Actions.",
+        "managed-sandbox": "A GitHub-managed sandbox environment.",
+        "managed-cca": "A GitHub-managed cloud coding agent environment."
+      }
+    },
+    "EnvironmentsDeleteRequest": {
+      "type": "object",
+      "properties": {
+        "environmentId": {
+          "type": "string",
+          "description": "User-managed environment to delete. GitHub-managed environments cannot be deleted."
+        }
+      },
+      "required": [
+        "environmentId"
+      ],
+      "additionalProperties": false,
+      "description": "Identify a user-managed Mission Control environment to delete."
+    },
+    "EnvironmentsDeleteResult": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false,
+      "description": "Acknowledgement that the requested environment was deleted."
+    },
+    "EnvironmentsGetRequest": {
+      "type": "object",
+      "properties": {
+        "environmentId": {
+          "type": "string",
+          "description": "Identifier assigned by Mission Control."
+        }
+      },
+      "required": [
+        "environmentId"
+      ],
+      "additionalProperties": false,
+      "description": "Identify a Mission Control environment to retrieve."
+    },
+    "EnvironmentsGetResult": {
+      "type": "object",
+      "properties": {
+        "environment": {
+          "$ref": "#/definitions/GitHubEnvironment",
+          "description": "The requested environment without relay bootstrap credentials."
+        }
+      },
+      "required": [
+        "environment"
+      ],
+      "description": "Safe discovery information for the requested environment."
+    },
+    "EnvironmentsListRequest": {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "$ref": "#/definitions/EnvironmentKind",
+          "description": "Restrict discovery to this compute kind."
+        },
+        "status": {
+          "type": "string",
+          "description": "Operational status, such as online, offline, degraded, waking, or draining."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Optional discovery filters supported by GitHub Mission Control."
+    },
+    "EnvironmentsListResult": {
+      "type": "object",
+      "properties": {
+        "environments": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/GitHubEnvironment",
+            "description": "Safe discovery information. Host-side relay bootstrap credentials are never included."
+          },
+          "description": "Safe discovery records without relay bootstrap credentials."
+        }
+      },
+      "required": [
+        "environments"
+      ],
+      "description": "Environments visible to the authenticated caller and matching the supplied filters."
+    },
     "EventLogReadRequest": {
       "type": "object",
       "properties": {
@@ -22511,6 +22929,61 @@
       "description": "Authentication-info input variant for GitHub CLI credentials, carrying host, login, and the `gh auth token` value.",
       "title": "GhCliAuthInfo"
     },
+    "GitHubEnvironment": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Identifier assigned by Mission Control."
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable environment name."
+        },
+        "kind": {
+          "$ref": "#/definitions/EnvironmentKind",
+          "description": "Compute kind reported by Mission Control."
+        },
+        "status": {
+          "type": "string",
+          "description": "Open-ended operational status vocabulary."
+        },
+        "capabilities": {
+          "$ref": "#/definitions/EnvironmentCapabilities",
+          "description": "Hosting capabilities advertised by the environment."
+        },
+        "ownerId": {
+          "type": "string",
+          "description": "Identifier of the environment owner."
+        },
+        "ownerType": {
+          "type": "string",
+          "description": "Owner category reported by Mission Control."
+        },
+        "orgId": {
+          "type": "string",
+          "description": "Organization identifier, when the environment belongs to an organization."
+        },
+        "labels": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Discovery labels attached to the environment."
+        },
+        "lastHeartbeatAt": {
+          "type": "string",
+          "description": "Timestamp of the last heartbeat received by Mission Control."
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "kind",
+        "status"
+      ],
+      "description": "Safe discovery information. Host-side relay bootstrap credentials are never included."
+    },
     "GitHubRepoRef": {
       "type": "object",
       "properties": {
@@ -23566,6 +24039,459 @@
         "notification": "Runs when the agent emits a notification."
       }
     },
+    "HostConfiguration": {
+      "type": "object",
+      "properties": {
+        "localServer": {
+          "$ref": "#/definitions/HostLocalServerConfiguration",
+          "description": "Normalized local listener settings, absent for relay-only hosts."
+        },
+        "githubEnvironment": {
+          "$ref": "#/definitions/HostGithubEnvironmentOptions",
+          "description": "Requested GitHub Mission Control registration."
+        },
+        "sessionFactory": {
+          "type": "boolean",
+          "description": "Whether session materialization is delegated to the owning application."
+        },
+        "resumeFactory": {
+          "type": "boolean",
+          "description": "Whether app-owned durable sessions are resumed by the owning application."
+        }
+      },
+      "required": [
+        "sessionFactory",
+        "resumeFactory"
+      ],
+      "description": "Normalized listener settings delivered only to the supervised hosting participant."
+    },
+    "HostDisposeRequest": {
+      "type": "object",
+      "properties": {
+        "hostId": {
+          "type": "string",
+          "description": "Listener UUID. Unknown or successfully stopped IDs are harmless."
+        }
+      },
+      "required": [
+        "hostId"
+      ],
+      "description": "Stops a connection-owned listener and joins its teardown."
+    },
+    "HostEmptyResult": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false,
+      "description": "Empty acknowledgement for a completed host lifecycle operation."
+    },
+    "HostEnvironmentCredentials": {
+      "type": "object",
+      "properties": {
+        "token": {
+          "type": "string",
+          "description": "Current bearer token for the authenticated GitHub identity."
+        },
+        "githubHost": {
+          "type": "string",
+          "description": "Hostname of the authenticated GitHub service."
+        },
+        "githubApiUrl": {
+          "type": "string",
+          "description": "GitHub API base URL for the authenticated service."
+        },
+        "missionControlUrl": {
+          "type": "string",
+          "description": "Mission Control API origin for environment registration and management."
+        }
+      },
+      "required": [
+        "token",
+        "githubHost",
+        "githubApiUrl",
+        "missionControlUrl"
+      ],
+      "additionalProperties": false,
+      "description": "Private credentials delivered only to a runtime-owned Mission Control hosting participant."
+    },
+    "HostExitedNotification": {
+      "type": "object",
+      "properties": {
+        "hostId": {
+          "type": "string",
+          "description": "Listener UUID."
+        },
+        "reason": {
+          "$ref": "#/definitions/HostExitReason",
+          "description": "Cause of termination."
+        },
+        "exitCode": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "description": "Process exit status when available; absent for in-process listener tasks."
+        },
+        "error": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Explicit startup or teardown failure, when present."
+        }
+      },
+      "required": [
+        "hostId",
+        "reason"
+      ],
+      "description": "Reports a supervised listener's hosting-task termination and cleanup outcome."
+    },
+    "HostExitReason": {
+      "type": "string",
+      "enum": [
+        "disposed",
+        "exited",
+        "ownerDisconnected",
+        "runtimeShutdown"
+      ],
+      "x-enumDescriptions": {
+        "disposed": "The owner requested disposal.",
+        "exited": "The hosting task or its SDK transport exited; this does not mean the runtime process exited.",
+        "ownerDisconnected": "The owning SDK connection disconnected.",
+        "runtimeShutdown": "The runtime is shutting down."
+      }
+    },
+    "HostGithubEnvironmentOptions": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Human-readable environment display name."
+        },
+        "computeId": {
+          "type": "string",
+          "description": "Stable application installation identity, reused across host restarts."
+        }
+      },
+      "required": [
+        "name",
+        "computeId"
+      ],
+      "additionalProperties": false,
+      "description": "GitHub Mission Control registration options. The compute ID is application-owned and stable."
+    },
+    "HostLocalServerConfiguration": {
+      "type": "object",
+      "properties": {
+        "hostname": {
+          "type": "string",
+          "description": "Hostname or IP address to bind."
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 65535,
+          "description": "Port to bind, with zero requesting OS allocation."
+        },
+        "token": {
+          "type": "string",
+          "description": "Secret connection token, absent when authentication is disabled."
+        },
+        "requireConnectionToken": {
+          "type": "boolean",
+          "description": "Whether the listener requires token authentication."
+        }
+      },
+      "required": [
+        "hostname",
+        "port",
+        "requireConnectionToken"
+      ],
+      "description": "Normalized local WebSocket listener settings."
+    },
+    "HostLocalServerOptions": {
+      "type": "object",
+      "properties": {
+        "hostname": {
+          "type": "string",
+          "description": "Listener hostname. Defaults to 127.0.0.1; explicit non-loopback binds are allowed."
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 65535,
+          "description": "Listener port. Omitted or zero requests an OS-allocated port."
+        },
+        "token": {
+          "type": "string",
+          "description": "Nonempty connection token. Generated randomly when required and omitted."
+        },
+        "requireConnectionToken": {
+          "type": "boolean",
+          "description": "Require token authentication (default true). Cannot be false with a token."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Local WebSocket transport options."
+    },
+    "HostPublishSessionRequest": {
+      "type": "object",
+      "properties": {
+        "hostId": {
+          "type": "string",
+          "description": "Listener UUID returned by host.start."
+        },
+        "sessionId": {
+          "type": "string",
+          "description": "Canonical runtime session ID attached to the listener's owning connection."
+        }
+      },
+      "required": [
+        "hostId",
+        "sessionId"
+      ],
+      "additionalProperties": false,
+      "description": "Publishes a resident session attached to the listener's owning connection."
+    },
+    "HostPublishSessionResult": {
+      "type": "object",
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "description": "Canonical runtime ID of the published session."
+        },
+        "sessionUri": {
+          "type": "string",
+          "description": "AHP resource URI for the session on this listener."
+        }
+      },
+      "required": [
+        "sessionId",
+        "sessionUri"
+      ],
+      "additionalProperties": false,
+      "description": "The existing runtime identity and its resource on the listener."
+    },
+    "HostReadyRequest": {
+      "type": "object",
+      "properties": {
+        "address": {
+          "type": "string",
+          "description": "Actual bound WebSocket URL."
+        },
+        "token": {
+          "type": "string",
+          "description": "Configured secret token, absent when authentication is disabled."
+        },
+        "environmentId": {
+          "type": "string",
+          "description": "Registered environment ID, reported only once the relay transport is connected."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Readiness reported by the supervised hosting participant on its own SDK connection."
+    },
+    "HostRegisterSessionRequest": {
+      "type": "object",
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "description": "Canonical ID of the existing resident runtime session."
+        },
+        "workingDirectory": {
+          "type": "string",
+          "description": "Absolute working directory of the resident session."
+        },
+        "additionalDirectories": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Additional directories already granted to the resident session."
+        },
+        "title": {
+          "type": "string",
+          "description": "Current display title of the resident session, when available."
+        },
+        "createdAtUnixMs": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Session creation time in milliseconds since the Unix epoch, when available."
+        },
+        "modifiedAtUnixMs": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Last session modification time in milliseconds since the Unix epoch, when available."
+        }
+      },
+      "required": [
+        "sessionId",
+        "workingDirectory"
+      ],
+      "additionalProperties": false,
+      "description": "Listener-scoped registration, not a copy or durable adoption of a session."
+    },
+    "HostSessionCreateCallback": {
+      "type": "object",
+      "properties": {
+        "hostId": {
+          "type": "string",
+          "description": "Listener UUID identifying the owning application's host."
+        },
+        "handoffId": {
+          "type": "string",
+          "description": "Unique identity of the session participation being requested."
+        },
+        "resume": {
+          "type": "boolean",
+          "default": false,
+          "description": "Resume an app-owned durable session instead of creating a new session."
+        },
+        "config": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": true,
+          "description": "Host-selected SDK creation or resume settings, without executable callbacks or tools."
+        }
+      },
+      "required": [
+        "hostId",
+        "handoffId",
+        "config"
+      ],
+      "description": "Application callback routed over its existing SDK connection."
+    },
+    "HostSessionCreateRequest": {
+      "type": "object",
+      "properties": {
+        "handoffId": {
+          "type": "string",
+          "description": "Unique identity for this participation, independent of the session lifetime."
+        },
+        "resume": {
+          "type": "boolean",
+          "default": false,
+          "description": "Resume an app-owned durable session instead of creating a new session."
+        },
+        "config": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": true,
+          "description": "Host-selected SDK creation or resume settings, without executable callbacks or tools."
+        }
+      },
+      "required": [
+        "handoffId",
+        "config"
+      ],
+      "additionalProperties": false,
+      "description": "One application-owned session handoff, requested by the supervised hosting participant."
+    },
+    "HostSessionCreateResult": {
+      "type": "object",
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "description": "Runtime session UUID materialized on the application's SDK connection."
+        }
+      },
+      "required": [
+        "sessionId"
+      ],
+      "additionalProperties": false,
+      "description": "The resident session the application has materialized on its own connection."
+    },
+    "HostSessionReleasedNotification": {
+      "type": "object",
+      "properties": {
+        "hostId": {
+          "type": "string",
+          "description": "Listener UUID whose application session participation ended."
+        },
+        "handoffId": {
+          "type": "string",
+          "description": "Identity of the handoff retaining the original application session object."
+        }
+      },
+      "required": [
+        "hostId",
+        "handoffId"
+      ],
+      "description": "Releases the original application session object retained for one handoff."
+    },
+    "HostSessionReleaseRequest": {
+      "type": "object",
+      "properties": {
+        "handoffId": {
+          "type": "string",
+          "description": "Identity of the participation to release without destroying the session."
+        }
+      },
+      "required": [
+        "handoffId"
+      ],
+      "additionalProperties": false,
+      "description": "Ends one participation, not the application's session lifetime."
+    },
+    "HostStartRequest": {
+      "type": "object",
+      "properties": {
+        "hostId": {
+          "type": "string",
+          "description": "Caller-generated UUID identifying this connection-owned listener."
+        },
+        "localServer": {
+          "$ref": "#/definitions/HostLocalServerOptions",
+          "description": "Enables a local WebSocket listener."
+        },
+        "githubEnvironment": {
+          "$ref": "#/definitions/HostGithubEnvironmentOptions",
+          "description": "Registers a GitHub Mission Control environment and enables its relay transport."
+        },
+        "sessionFactory": {
+          "type": "boolean",
+          "description": "Ask the owning SDK application to materialize AHP sessions."
+        },
+        "resumeFactory": {
+          "type": "boolean",
+          "description": "Ask the owning application to resume its durable AHP sessions."
+        }
+      },
+      "required": [
+        "hostId"
+      ],
+      "additionalProperties": false,
+      "description": "Starts a supervised AHP host with at least one explicitly selected transport."
+    },
+    "HostStartResult": {
+      "type": "object",
+      "properties": {
+        "hostId": {
+          "type": "string",
+          "description": "Caller-generated listener UUID."
+        },
+        "url": {
+          "type": "string",
+          "description": "Actual bound WebSocket URL, including the allocated port."
+        },
+        "token": {
+          "type": "string",
+          "description": "Secret connection token, absent when authentication is disabled."
+        },
+        "environmentId": {
+          "type": "string",
+          "description": "GitHub Mission Control environment ID, present when its relay transport is ready."
+        },
+        "pid": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Separate host process ID, when provided by a legacy runtime. Absent for in-process listeners."
+        }
+      },
+      "required": [
+        "hostId"
+      ],
+      "description": "Listener readiness, returned only after binding and the supervised participant's SDK handshake."
+    },
     "IndexedSearchState": {
       "type": "string",
       "enum": [
@@ -32402,6 +33328,10 @@
           "$ref": "#/definitions/PermissionDecisionApproveForSession",
           "description": "Permission-decision request variant to approve for the rest of the session, with optional tool approval or URL domain."
         },
+        {
+          "$ref": "#/definitions/PermissionDecisionApproveReadOnlyForSession",
+          "description": "Approve file-tool read access to specific directories for this logical session, including continuation or resume."
+        },
         {
           "$ref": "#/definitions/PermissionDecisionApproveForLocation",
           "description": "Permission-decision request variant to approve and persist a permission for a project location, with approval details and location key."
@@ -33180,6 +34110,31 @@
       "description": "Permission-decision request variant to permanently approve a URL domain across sessions.",
       "title": "PermissionDecisionApprovePermanently"
     },
+    "PermissionDecisionApproveReadOnlyForSession": {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "const": "approve-read-only-for-session",
+          "description": "Approve read-only file-tool directory access for this session"
+        },
+        "directories": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "description": "Canonical directories covered by the read-only grant"
+        }
+      },
+      "required": [
+        "kind",
+        "directories"
+      ],
+      "additionalProperties": false,
+      "description": "Approve file-tool read access to specific directories for this logical session, including continuation or resume.",
+      "title": "PermissionDecisionApproveReadOnlyForSession"
+    },
     "PermissionDecisionCancelled": {
       "type": "object",
       "properties": {
@@ -36248,6 +37203,56 @@
       "description": "A bearer token supplied by the SDK client for a BYOK provider. The runtime sets it as `Authorization: Bearer <token>` on the outbound request and does no caching; the SDK consumer owns token caching and refresh.",
       "title": "ProviderTokenAcquireResult"
     },
+    "ProviderWithdrawRequest": {
+      "type": "object",
+      "properties": {
+        "models": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Provider-qualified selection ids to withdraw. Ids that are not registered are ignored, so withdrawal is idempotent. A provider left with no models referencing it is removed too."
+        }
+      },
+      "required": [
+        "models"
+      ],
+      "additionalProperties": false,
+      "description": "Host-managed model selection ids to withdraw from the session's BYOK registry.",
+      "title": "ProviderWithdrawRequest",
+      "stability": "experimental"
+    },
+    "ProviderWithdrawResult": {
+      "type": "object",
+      "properties": {
+        "withdrawn": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Selection ids that were registered and are now withdrawn. Excludes requested ids that were not present."
+        },
+        "providersRemoved": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Providers removed because one of the withdrawn models was the last entry referencing them. A provider that merely has no models is not removed."
+        },
+        "modelDeselected": {
+          "type": "boolean",
+          "description": "True when withdrawal removed the selected host-managed model, leaving the session with no explicit selection, so ordinary model resolution picks the session default. Withdrawal never promotes a surviving model in its place: the choice of which model to use stays with the user."
+        }
+      },
+      "required": [
+        "withdrawn",
+        "providersRemoved"
+      ],
+      "additionalProperties": false,
+      "description": "What the withdrawal actually removed from the registry.",
+      "title": "ProviderWithdrawResult",
+      "stability": "experimental"
+    },
     "PushAttachment": {
       "anyOf": [
         {
@@ -38306,6 +39311,10 @@
           "$ref": "#/definitions/SandboxConfigAuth",
           "description": "Credential-injection capability flags."
         },
+        "credentials": {
+          "$ref": "#/definitions/SandboxCredentialsConfig",
+          "description": "Opt-in whole-value environment masking for sandboxed shell, MCP, and LSP children. Configured names get random sentinels; the local proxy substitutes them only in HTTPS request headers at their injection hosts. Approved bypasses skip masking and the sandbox proxy, so bypassed shells may receive the real environment values. Disabled or explicitly opted-out routes are not protected. No credential values are stored in this configuration."
+        },
         "allowDevToolAccess": {
           "type": "boolean",
           "description": "Whether to auto-grant read access to tool directories discovered on PATH and in toolchain environment variables (GOROOT, JAVA_HOME, VIRTUAL_ENV, and similar), and to common developer-tool caches, config, and toolchains. Writable grants cover scratch caches, the Unix GitHub CLI cache, and Cargo's registry, git store, and lock/tracker files. A relocated CARGO_HOME gets the same narrow split: registry and git are read-write; bin is read-only; the home root, config.toml, and credentials.toml stay ungranted. Set to false to disable every grant listed above; user-installed toolchains and caches then need explicit userPolicy.filesystem readonlyPaths and readwritePaths entries. The working directory (see addCurrentWorkingDirectory), temporary storage, session log paths, and system locations follow their own rules and stay granted. Default: true (enabled by default; set to false to opt out)."
@@ -38324,11 +39333,11 @@
       "properties": {
         "git": {
           "type": "boolean",
-          "description": "Whether to inject git credentials as an `http.<url>.extraheader` so authenticated HTTPS git works inside the sandbox without the shell-based credential helper the sandbox blocks. github.com is served by the Copilot token; every other forge (Azure DevOps, GitHub Enterprise Server, GitLab, ...) by a credential the host resolves from the user's own helper before the sandbox is applied. Default: false (opt-in)."
+          "description": "Whether to authenticate sandboxed HTTPS git through the local masking proxy. The child receives a fake `http.<url>.extraheader`; the real Authorization header is substituted only at its original HTTPS host, port, and repository path scope. github.com uses the Copilot token; other forges use credentials resolved from the user's own helper on the host. Default: false (opt-in)."
         },
         "gh": {
           "type": "boolean",
-          "description": "Whether to export `GH_TOKEN` so the `gh` CLI authenticates inside the sandbox without the OS keyring the sandbox blocks. Default: false (opt-in)."
+          "description": "Whether to authenticate sandboxed gh through the local masking proxy. The child receives a fake GH_TOKEN; its real value is substituted only at github.com, api.github.com and uploads.github.com (github.com because gh repo clone authenticates git through gh auth git-credential). The repository's GitHub account takes precedence over the Copilot login. Default: false (opt-in)."
         }
       },
       "additionalProperties": false,
@@ -38346,17 +39355,18 @@
         "unsupported_host",
         "repository_policy"
       ],
-      "description": "Origin of the sandbox choice supplied by the host. Settings-derived origins let managed policy floor the host preference; do not tag explicit session overrides as settings-derived.",
+      "description": "Origin of the sandbox choice supplied by the host. This value describes preference or session intent; it does not authorize bypassing managed policy.",
       "title": "SandboxConfigSource",
       "x-enumDescriptions": {
         "never_configured": "The client applied the default because no sandbox preference was configured.",
         "user_enabled": "The user's persisted settings enabled the sandbox.",
         "user_disabled": "The user's persisted settings disabled the sandbox.",
-        "session_flag": "A command-line flag selected the sandbox state for this session.",
+        "session_flag": "An explicit session-scoped choice selected the sandbox state, such as a command-line flag.",
         "session_disabled": "The user disabled the sandbox for the current session.",
         "unsupported_host": "The client disabled the sandbox because the host cannot enforce it.",
         "repository_policy": "A repository policy selected the sandbox state."
-      }
+      },
+      "stability": "experimental"
     },
     "SandboxConfigUserPolicy": {
       "type": "object",
@@ -38508,6 +39518,25 @@
       "description": "macOS seatbelt-specific options.",
       "title": "SandboxConfigUserPolicySeatbelt"
     },
+    "SandboxCredentialsConfig": {
+      "type": "object",
+      "properties": {
+        "envVars": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/SandboxMaskedEnvVar",
+            "description": "Destinations authorized to receive one masked environment credential."
+          },
+          "description": "Environment variable names and their HTTPS injection destinations. Absent variables stay absent. No real values or sentinels are stored in this map."
+        }
+      },
+      "required": [
+        "envVars"
+      ],
+      "additionalProperties": false,
+      "description": "Whole-value environment credential masking for sandboxed children.",
+      "title": "SandboxCredentialsConfig"
+    },
     "SandboxDisableForSessionRequest": {
       "type": "object",
       "properties": {
@@ -38572,6 +39601,42 @@
       "description": "Managed sandbox enforcement state for a session.",
       "title": "SandboxEnforcementStatus"
     },
+    "SandboxGrantPathForRequestRequest": {
+      "type": "object",
+      "properties": {
+        "requestId": {
+          "type": "string",
+          "description": "Identifier of the exact pending sandbox escalation permission request whose sandboxPathGrant to accept."
+        },
+        "decisionContext": {
+          "$ref": "#/definitions/PermissionDecisionContext",
+          "description": "Optional attribution for the permission decision."
+        }
+      },
+      "required": [
+        "requestId"
+      ],
+      "additionalProperties": false,
+      "description": "Request to accept the sandbox path grant offered on an active sandbox escalation permission prompt.",
+      "title": "SandboxGrantPathForRequestRequest",
+      "stability": "experimental"
+    },
+    "SandboxGrantPathForRequestResult": {
+      "type": "object",
+      "properties": {
+        "success": {
+          "type": "boolean",
+          "description": "Whether this call resolved the pending request and added the path to the session's sandbox policy."
+        }
+      },
+      "required": [
+        "success"
+      ],
+      "additionalProperties": false,
+      "description": "Result of accepting a sandbox path grant.",
+      "title": "SandboxGrantPathForRequestResult",
+      "stability": "experimental"
+    },
     "SandboxHostCapability": {
       "type": "object",
       "properties": {
@@ -38632,6 +39697,24 @@
       "description": "Whether the host running this runtime can run the command sandbox. The runtime checks `supported` once per process. A capability answer can change while the process runs, for example after the user installs a missing package.",
       "title": "SandboxHostSupport"
     },
+    "SandboxMaskedEnvVar": {
+      "type": "object",
+      "properties": {
+        "injectHosts": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Nonempty list of HTTPS injection hostnames or *.example.com patterns. Bare * is not accepted. These grants never override the sandbox network policy. Values in plaintext HTTP requests, URLs, bodies, encoded credentials, and signed requests are not substituted."
+        }
+      },
+      "required": [
+        "injectHosts"
+      ],
+      "additionalProperties": false,
+      "description": "Destinations authorized to receive one masked environment credential.",
+      "title": "SandboxMaskedEnvVar"
+    },
     "SandboxSessionChange": {
       "type": "string",
       "enum": [
@@ -41455,7 +42538,8 @@
         },
         "sandboxConfigSource": {
           "$ref": "#/definitions/SandboxConfigSource",
-          "description": "Origin of the sandbox choice. Settings-derived origins (never_configured, user_enabled, user_disabled, repository_policy) let managed policy floor a host preference; explicit below-floor changes remain policy conflicts unless a session opt-out is authorized. Also used for telemetry provenance."
+          "description": "Origin of the sandbox choice. Settings-derived origins (never_configured, user_enabled, user_disabled, repository_policy) let managed policy floor a host preference; explicit below-floor changes remain policy conflicts unless a session opt-out is authorized. Also used for telemetry provenance.",
+          "stability": "experimental"
         },
         "logInteractiveShells": {
           "type": "boolean",
@@ -43570,7 +44654,8 @@
         },
         "sandboxConfigSource": {
           "$ref": "#/definitions/SandboxConfigSource",
-          "description": "Origin of the sandbox choice. Settings-derived origins (never_configured, user_enabled, user_disabled, repository_policy) let managed policy floor a host preference; explicit below-floor changes remain policy conflicts unless a session opt-out is authorized. Also used for telemetry provenance."
+          "description": "Origin of the sandbox choice. Settings-derived origins (never_configured, user_enabled, user_disabled, repository_policy) let managed policy floor a host preference; explicit below-floor changes remain policy conflicts unless a session opt-out is authorized. Also used for telemetry provenance.",
+          "stability": "experimental"
         },
         "logInteractiveShells": {
           "type": "boolean",