@github/copilot-sdk 1.0.21-preview.0 → 1.0.21-preview.2

package/dist/generated/rpc.js

@@ -1,5 +1,141 @@
 function createServerRpc(connection) {
   return {
+    /** @experimental */
+    sandbox: {
+      /** @experimental */
+      proxyCa: {
+        /**
+         * Reports whether this runtime process can offer installing the sandbox credential-proxy certificate authority into OS trust.
+         *
+         * @returns True when this process can offer installing the sandbox credential-proxy certificate authority into OS trust.
+         */
+        checkInstallationSupport: async () => connection.sendRequest("sandbox.proxyCa.checkInstallationSupport", {}),
+        /**
+         * Reports whether this sandbox configuration uses the credential proxy and can need certificate-authority setup.
+         *
+         * @param params Identifies the credential hosts that the persistent certificate authority of the sandbox credential proxy must cover. The runtime always adds the hosts from the saved user settings.
+         *
+         * @returns True when the sandbox configuration uses the credential proxy and can need certificate-authority setup.
+         */
+        checkRelevance: async (params) => connection.sendRequest("sandbox.proxyCa.checkRelevance", params),
+        /**
+         * Reports whether the persistent certificate authority of the sandbox credential proxy exists, whether OS trust includes it, and whether it must be rotated. Changes nothing.
+         *
+         * @param params Identifies the credential hosts that the persistent certificate authority of the sandbox credential proxy must cover. The runtime always adds the hosts from the saved user settings.
+         *
+         * @returns Status of the persistent certificate authority of the sandbox credential proxy.
+         */
+        getStatus: async (params) => connection.sendRequest("sandbox.proxyCa.getStatus", params),
+        /**
+         * Creates the persistent certificate authority of the sandbox credential proxy if none is stored, without changing OS trust, and returns the path of its public certificate. Keeps an existing certificate authority, even one that must be rotated. Fails where OS trust is unsupported. Trust it with sandbox.proxyCa.trust: the CLI trusts only the hosts in the saved user settings, so it refuses a certificate authority that also covers hosts from sandboxConfig.
+         *
+         * @param params Identifies the credential hosts that the persistent certificate authority of the sandbox credential proxy must cover. The runtime always adds the hosts from the saved user settings.
+         *
+         * @returns Result of creating the persistent certificate authority of the sandbox credential proxy.
+         */
+        create: async (params) => connection.sendRequest("sandbox.proxyCa.create", params),
+        /**
+         * Replaces the persistent certificate authority of the sandbox credential proxy with a new one for the current credential hosts. If OS trust included the old one, removes it and trusts the new one, which can show an OS authentication prompt. Running sandboxed tools keep the old certificate authority until they restart.
+         *
+         * @param params Identifies the credential hosts that the persistent certificate authority of the sandbox credential proxy must cover. The runtime always adds the hosts from the saved user settings.
+         *
+         * @returns Status of the persistent certificate authority of the sandbox credential proxy.
+         */
+        rotate: async (params) => connection.sendRequest("sandbox.proxyCa.rotate", params),
+        /**
+         * Adds the persistent certificate authority of the sandbox credential proxy to OS trust, so sandboxed clients that read only OS trust accept the proxy. Call create first. Refuses a certificate authority that is not constrained to the current credential hosts. Can show an OS authentication prompt.
+         *
+         * @param params Identifies the credential hosts that the persistent certificate authority of the sandbox credential proxy must cover. The runtime always adds the hosts from the saved user settings.
+         *
+         * @returns Status of the persistent certificate authority of the sandbox credential proxy.
+         */
+        trust: async (params) => connection.sendRequest("sandbox.proxyCa.trust", params),
+        /**
+         * Removes the persistent certificate authority of the sandbox credential proxy from OS trust. Keeps the stored certificate authority. Can show an OS authentication prompt. Sandboxed clients that read only OS trust then reject the proxy; clients that read the per-process certificate bundle continue to work.
+         *
+         * @returns Status of the persistent certificate authority of the sandbox credential proxy.
+         */
+        remove: async () => connection.sendRequest("sandbox.proxyCa.remove", {})
+      },
+      /**
+       * Reports whether the host running this runtime can run the command sandbox, without starting a session or spawning a sandboxed command.
+       *
+       * @returns 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.
+       */
+      getHostSupport: async () => connection.sendRequest("sandbox.getHostSupport", {})
+    },
+    /** @experimental */
+    user: {
+      /** @experimental */
+      settings: {
+        /**
+         * Lists every known user setting from settings.json, each with its effective value, its default, and whether it is at the default — so settings the user has never set still appear with their default value. Does not include repository- or enterprise-managed overrides that the runtime layers on top at session time.
+         *
+         * @returns Per-key metadata for every known user setting in settings.json, including settings left at their default. Excludes repository- and enterprise-managed overrides.
+         */
+        get: async () => connection.sendRequest("user.settings.get", {}),
+        /**
+         * Writes one or more user settings to settings.json, replacing each provided top-level key. A key whose value is null is removed.
+         *
+         * @param params Partial user settings to write to settings.json. Each top-level key is written individually, replacing the existing value; a key whose value is null is removed.
+         */
+        set: async (params) => connection.sendRequest("user.settings.set", params)
+      }
+    },
+    /** @experimental */
+    managedSettings: {
+      /**
+       * Discovers device-managed settings from production MDM and managed-file sources, validates them against the runtime-owned managed-settings schema, and returns the canonical JSON without requiring a session. `managedSettings.resolve` returns the same device settings together with the account's server policy.
+       *
+       * @returns Validated device-managed settings discovered before a session exists.
+       */
+      read: async () => connection.sendRequest("managedSettings.read", {}),
+      /**
+       * Force-refreshes enterprise managed settings for every account: wipes the persistent server-policy cache (the whole `<cacheHome>/managed-settings` directory) and drops this runtime process's in-memory retained server policy. It does not itself fetch policy — the effect is that the next time a session resolves managed settings for an account, that resolution re-fetches the account's org policy from the network instead of serving a cached response. Note that `managedSettings.read` returns only device/MDM settings and never triggers the account server-policy fetch, so a host implementing "sync account policy" should call `managedSettings.resolve` or start a fresh session resolution rather than treat a subsequent `managedSettings.read` as the refreshed org policy. Mirrors the invalidation a sign-out performs, broadened from the one signing-out account to all of them; device/MDM layers describe the machine, not the account, and are left untouched. Rejects if the on-disk cache cannot be removed.
+       */
+      clearCache: async () => connection.sendRequest("managedSettings.clearCache", {}),
+      /**
+       * Resolves the effective enterprise managed settings without a session, from the device channel and, when an account is available, the account's server policy through the same per-account cache sessions use. A cached server policy less than an hour old is used without a fetch; otherwise the policy is fetched, and when the fetch fails a cached policy up to 24 hours old is used instead, unless `forceRemoteSettingsRefresh` requires a live fetch. With no account requested or signed in, it reports device policy only; signing out removes the account's cached policy. It can fetch server policy over the network when the cache is stale, so call it off latency-critical paths such as startup rather than before listing models. The policy helper is not run. `layers` lists each channel's document before merging, and `values` and `meta` carry typed effective values and their lock state for the keys typed so far.
+       *
+       * @param params Optional opaque account selection or GitHub token whose managed settings are resolved.
+       *
+       * @returns Effective enterprise managed settings for an account, resolved without a session.
+       */
+      resolve: async (params) => connection.sendRequest("managedSettings.resolve", params),
+      /** @experimental */
+      permissions: {
+        /**
+         * Pure, sessionless evaluation of operations against a supplied permissionsContext. Performs no policy discovery, I/O, prompting, navigation, permission grants, or sandbox changes. Obtain the context from managedSettings.resolve or session.managedSettings.get, or reuse an in-memory context. Results preserve input order and duplicates. Consumers must block deny, obtain approval for ask, and use their normal permission flow for unmanaged. Unknown policy returns failClosed with every operation denied. This is not a substitute for user permissions or other security controls.
+         *
+         * @param params Managed policy context and ordered operations for pure, sessionless evaluation.
+         *
+         * @returns Ordered managed permission verdicts and the supplied policy's fail-closed posture.
+         */
+        evaluate: async (params) => connection.sendRequest("managedSettings.permissions.evaluate", params)
+      },
+      /**
+       * Returns the managed-settings authoring JSON schema with descriptive `x-composition` annotations aligned with the shared settings-engine vocabulary. These annotations are not a complete runtime composition contract: model, effortLevel, and contextTier remain coupled. Use `managedSettings.compose` for the runtime's effective result. Performs no I/O.
+       *
+       * @returns The authoring JSON schema for managed settings recognized by this runtime.
+       */
+      schema: async () => connection.sendRequest("managedSettings.schema", {}),
+      /**
+       * Validates a candidate managed-settings document the way the runtime validates delivered policy, without applying it. Reports errors that would reject the document, warnings for content the runtime ignores, and the canonical document it would apply. Document text nested more than 64 levels deep is rejected. Performs no I/O.
+       *
+       * @param params A candidate managed-settings document to validate without applying it.
+       *
+       * @returns Result of validating a managed-settings document.
+       */
+      validate: async (params) => connection.sendRequest("managedSettings.validate", params),
+      /**
+       * Merges candidate managed-settings documents for the device, server, and policy-helper channels into the effective settings the runtime would enforce on this host, using the same precedence and composition rules as live resolution, without applying them. Like live resolution, a server's advisory sandbox force-enable is declined on a host that cannot run the sandbox. Does not fetch policy or read policy files, but may perform blocking OS or subprocess probes for sandbox support. Preview documents are limited to 1 MiB and 64 levels of nesting.
+       *
+       * @param params Candidate managed-settings documents to merge without applying them.
+       *
+       * @returns The effective managed settings the runtime would enforce for the given documents, in the same shape `managedSettings.resolve` returns.
+       */
+      compose: async (params) => connection.sendRequest("managedSettings.compose", params)
+    },
     /** @experimental */
     environments: {
       /**
@@ -101,56 +237,6 @@ function createServerRpc(connection) {
       getBuiltInCatalog: async () => connection.sendRequest("models.getBuiltInCatalog", {})
     },
     /** @experimental */
-    sandbox: {
-      /**
-       * Reports whether the host running this runtime can run the command sandbox, without starting a session or spawning a sandboxed command.
-       *
-       * @returns 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.
-       */
-      getHostSupport: async () => connection.sendRequest("sandbox.getHostSupport", {}),
-      /** @experimental */
-      proxyCa: {
-        /**
-         * Reports whether the persistent certificate authority of the sandbox credential proxy exists, whether OS trust includes it, and whether it must be rotated. Changes nothing.
-         *
-         * @param params Identifies the credential hosts that the persistent certificate authority of the sandbox credential proxy must cover. The runtime always adds the hosts from the saved user settings.
-         *
-         * @returns Status of the persistent certificate authority of the sandbox credential proxy.
-         */
-        getStatus: async (params) => connection.sendRequest("sandbox.proxyCa.getStatus", params),
-        /**
-         * Creates the persistent certificate authority of the sandbox credential proxy if none is stored, without changing OS trust, and returns the path of its public certificate. Keeps an existing certificate authority, even one that must be rotated. Fails where OS trust is unsupported. Trust it with sandbox.proxyCa.trust: the CLI trusts only the hosts in the saved user settings, so it refuses a certificate authority that also covers hosts from sandboxConfig.
-         *
-         * @param params Identifies the credential hosts that the persistent certificate authority of the sandbox credential proxy must cover. The runtime always adds the hosts from the saved user settings.
-         *
-         * @returns Result of creating the persistent certificate authority of the sandbox credential proxy.
-         */
-        create: async (params) => connection.sendRequest("sandbox.proxyCa.create", params),
-        /**
-         * Replaces the persistent certificate authority of the sandbox credential proxy with a new one for the current credential hosts. If OS trust included the old one, removes it and trusts the new one, which can show an OS authentication prompt. Running sandboxed tools keep the old certificate authority until they restart.
-         *
-         * @param params Identifies the credential hosts that the persistent certificate authority of the sandbox credential proxy must cover. The runtime always adds the hosts from the saved user settings.
-         *
-         * @returns Status of the persistent certificate authority of the sandbox credential proxy.
-         */
-        rotate: async (params) => connection.sendRequest("sandbox.proxyCa.rotate", params),
-        /**
-         * Adds the persistent certificate authority of the sandbox credential proxy to OS trust, so sandboxed clients that read only OS trust accept the proxy. Call create first. Refuses a certificate authority that is not constrained to the current credential hosts. Can show an OS authentication prompt.
-         *
-         * @param params Identifies the credential hosts that the persistent certificate authority of the sandbox credential proxy must cover. The runtime always adds the hosts from the saved user settings.
-         *
-         * @returns Status of the persistent certificate authority of the sandbox credential proxy.
-         */
-        trust: async (params) => connection.sendRequest("sandbox.proxyCa.trust", params),
-        /**
-         * Removes the persistent certificate authority of the sandbox credential proxy from OS trust. Keeps the stored certificate authority. Can show an OS authentication prompt. Sandboxed clients that read only OS trust then reject the proxy; clients that read the per-process certificate bundle continue to work.
-         *
-         * @returns Status of the persistent certificate authority of the sandbox credential proxy.
-         */
-        remove: async () => connection.sendRequest("sandbox.proxyCa.remove", {})
-      }
-    },
-    /** @experimental */
     tools: {
       /**
        * Lists built-in tools available for a model.
@@ -642,78 +728,6 @@ function createServerRpc(connection) {
       list: async () => connection.sendRequest("commands.list", {})
     },
     /** @experimental */
-    user: {
-      /** @experimental */
-      settings: {
-        /**
-         * Lists every known user setting from settings.json, each with its effective value, its default, and whether it is at the default — so settings the user has never set still appear with their default value. Does not include repository- or enterprise-managed overrides that the runtime layers on top at session time.
-         *
-         * @returns Per-key metadata for every known user setting in settings.json, including settings left at their default. Excludes repository- and enterprise-managed overrides.
-         */
-        get: async () => connection.sendRequest("user.settings.get", {}),
-        /**
-         * Writes one or more user settings to settings.json, replacing each provided top-level key. A key whose value is null is removed.
-         *
-         * @param params Partial user settings to write to settings.json. Each top-level key is written individually, replacing the existing value; a key whose value is null is removed.
-         */
-        set: async (params) => connection.sendRequest("user.settings.set", params)
-      }
-    },
-    /** @experimental */
-    managedSettings: {
-      /**
-       * Discovers device-managed settings from production MDM and managed-file sources, validates them against the runtime-owned managed-settings schema, and returns the canonical JSON without requiring a session. `managedSettings.resolve` returns the same device settings together with the account's server policy.
-       *
-       * @returns Validated device-managed settings discovered before a session exists.
-       */
-      read: async () => connection.sendRequest("managedSettings.read", {}),
-      /**
-       * Force-refreshes enterprise managed settings for every account: wipes the persistent server-policy cache (the whole `<cacheHome>/managed-settings` directory) and drops this runtime process's in-memory retained server policy. It does not itself fetch policy — the effect is that the next time a session resolves managed settings for an account, that resolution re-fetches the account's org policy from the network instead of serving a cached response. Note that `managedSettings.read` returns only device/MDM settings and never triggers the account server-policy fetch, so a host implementing "sync account policy" should call `managedSettings.resolve` or start a fresh session resolution rather than treat a subsequent `managedSettings.read` as the refreshed org policy. Mirrors the invalidation a sign-out performs, broadened from the one signing-out account to all of them; device/MDM layers describe the machine, not the account, and are left untouched. Rejects if the on-disk cache cannot be removed.
-       */
-      clearCache: async () => connection.sendRequest("managedSettings.clearCache", {}),
-      /**
-       * Resolves the effective enterprise managed settings without a session, from the device channel and, when an account is available, the account's server policy through the same per-account cache sessions use. A cached server policy less than an hour old is used without a fetch; otherwise the policy is fetched, and when the fetch fails a cached policy up to 24 hours old is used instead, unless `forceRemoteSettingsRefresh` requires a live fetch. With no account requested or signed in, it reports device policy only; signing out removes the account's cached policy. It can fetch server policy over the network when the cache is stale, so call it off latency-critical paths such as startup rather than before listing models. The policy helper is not run. `layers` lists each channel's document before merging, and `values` and `meta` carry typed effective values and their lock state for the keys typed so far.
-       *
-       * @param params Optional opaque account selection or GitHub token whose managed settings are resolved.
-       *
-       * @returns Effective enterprise managed settings for an account, resolved without a session.
-       */
-      resolve: async (params) => connection.sendRequest("managedSettings.resolve", params),
-      /** @experimental */
-      permissions: {
-        /**
-         * Pure, sessionless evaluation of operations against a supplied permissionsContext. Performs no policy discovery, I/O, prompting, navigation, permission grants, or sandbox changes. Obtain the context from managedSettings.resolve or session.managedSettings.get, or reuse an in-memory context. Results preserve input order and duplicates. Consumers must block deny, obtain approval for ask, and use their normal permission flow for unmanaged. Unknown policy returns failClosed with every operation denied. This is not a substitute for user permissions or other security controls.
-         *
-         * @param params Managed policy context and ordered operations for pure, sessionless evaluation.
-         *
-         * @returns Ordered managed permission verdicts and the supplied policy's fail-closed posture.
-         */
-        evaluate: async (params) => connection.sendRequest("managedSettings.permissions.evaluate", params)
-      },
-      /**
-       * Returns the managed-settings authoring JSON schema with descriptive `x-composition` annotations aligned with the shared settings-engine vocabulary. These annotations are not a complete runtime composition contract: model, effortLevel, and contextTier remain coupled. Use `managedSettings.compose` for the runtime's effective result. Performs no I/O.
-       *
-       * @returns The authoring JSON schema for managed settings recognized by this runtime.
-       */
-      schema: async () => connection.sendRequest("managedSettings.schema", {}),
-      /**
-       * Validates a candidate managed-settings document the way the runtime validates delivered policy, without applying it. Reports errors that would reject the document, warnings for content the runtime ignores, and the canonical document it would apply. Document text nested more than 64 levels deep is rejected. Performs no I/O.
-       *
-       * @param params A candidate managed-settings document to validate without applying it.
-       *
-       * @returns Result of validating a managed-settings document.
-       */
-      validate: async (params) => connection.sendRequest("managedSettings.validate", params),
-      /**
-       * Merges candidate managed-settings documents for the device, server, and policy-helper channels into the effective settings the runtime would enforce on this host, using the same precedence and composition rules as live resolution, without applying them. Like live resolution, a server's advisory sandbox force-enable is declined on a host that cannot run the sandbox. Does not fetch policy or read policy files, but may perform blocking OS or subprocess probes for sandbox support. Preview documents are limited to 1 MiB and 64 levels of nesting.
-       *
-       * @param params Candidate managed-settings documents to merge without applying them.
-       *
-       * @returns The effective managed settings the runtime would enforce for the given documents, in the same shape `managedSettings.resolve` returns.
-       */
-      compose: async (params) => connection.sendRequest("managedSettings.compose", params)
-    },
-    /** @experimental */
     runtime: {
       /**
        * Gracefully shuts down an SDK-owned runtime. The response is sent only after cleanup completes; callers may then terminate the owned runtime process.
@@ -1002,12 +1016,499 @@ function createServerRpc(connection) {
 function createInternalServerRpc(connection) {
   return {
     /** @experimental */
-    host: {
-      /**
-       * Requests app-owned materialization over the owning SDK participant.
-       *
-       * @param params One application-owned session handoff, requested by the supervised hosting participant.
-       *
+    sandbox: {
+      /** @experimental */
+      proxySecret: {
+        /**
+         * Reports where this runtime keeps the sandbox proxy password: the credential store directory and the entry identifier within it. Both are derived from the configuration directory this runtime was started with, so a host does not resolve them itself. Read this to recognize a `${secret:…}` value in stored sandbox settings as this runtime's own proxy password rather than a reference the user wrote by hand. Marked internal because it exists to carry a CLI call site off the napi boundary onto the SDK contract.
+         *
+         * @returns Where this runtime keeps the sandbox proxy password.
+         */
+        getLocation: async () => connection.sendRequest("sandbox.proxySecret.getLocation", {}),
+        /**
+         * Reads the stored sandbox proxy password from the credential store `sandbox.proxySecret.getLocation` names, preferring the OS keychain and falling back to the on-disk store. Reports an absent value rather than failing when no entry exists. Marked internal because it exists to carry a CLI call site off the napi boundary onto the SDK contract.
+         *
+         * @returns The stored sandbox proxy password, if one is present.
+         */
+        get: async () => connection.sendRequest("sandbox.proxySecret.get", {}),
+        /**
+         * Stores the sandbox proxy password in the credential store `sandbox.proxySecret.getLocation` names, replacing any existing entry. Reports whether the OS keychain accepted it or it fell back to the on-disk store. Marked internal because it exists to carry a CLI call site off the napi boundary onto the SDK contract.
+         *
+         * @param params The sandbox proxy password to store.
+         *
+         * @returns Where the sandbox proxy password was stored.
+         */
+        save: async (params) => connection.sendRequest("sandbox.proxySecret.save", params),
+        /**
+         * Removes the stored sandbox proxy password from the credential store `sandbox.proxySecret.getLocation` names. Succeeds when no entry exists, so it is safe to call while clearing a proxy password whose origin is unknown. Marked internal because it exists to carry a CLI call site off the napi boundary onto the SDK contract.
+         */
+        delete: async () => connection.sendRequest("sandbox.proxySecret.delete", {})
+      },
+      /** @experimental */
+      settings: {
+        /**
+         * Resolves a stored sandbox settings object into the effective one, filling every value the user left unset with its default. Read this to render or reason about the sandbox configuration a session would actually run under, rather than the sparse document the user wrote.
+         *
+         * @param params The stored sandbox settings to resolve against the defaults.
+         *
+         * @returns The effective sandbox settings, with every unset value resolved to its default.
+         */
+        applyDefaults: async (params) => connection.sendRequest("sandbox.settings.applyDefaults", params)
+      },
+      /**
+       * Raises a user's sandbox settings to an administrator's managed sandbox floor and returns the result a session should actually run under. The floor can only tighten: an enterprise force-on is reflected even when the user's own `enabled` is false, and a user cannot lower a setting the floor raised. The result is normalized through the declared sandbox shape, so a key reorder or an undeclared passthrough key is not mistaken for a policy change by callers that diff two results. A host must call this rather than merge the two layers itself, because reimplementing the direction of the fold is what turns an administrator's floor into a suggestion.
+       *
+       * @param params The user's sandbox settings and the managed sandbox floor to raise them to.
+       *
+       * @returns The user's sandbox settings raised to the managed floor.
+       */
+      resolveFlooredConfig: async (params) => connection.sendRequest("sandbox.resolveFlooredConfig", params),
+      /**
+       * Builds the effective filesystem policy one `@`-file picker checks its suggestions against, so Git discovery and grant canonicalization run once for the picker's lifetime instead of on every debounced keystroke. Returns no policy when the sandbox is absent or disabled, which the paired filter reads as "keep every candidate". A host must pair this with `sandbox.filterPickerCandidates` rather than resolve a grant list itself, because the picker's grants are narrower than a file tool's — the same path a built-in tool may read can be one the picker must not offer.
+       *
+       * @param params The working directory and sandbox settings to build a file-picker policy from.
+       *
+       * @returns The prepared file-picker policy, or none when the sandbox is disabled.
+       */
+      preparePickerPolicy: async (params) => connection.sendRequest("sandbox.preparePickerPolicy", params),
+      /**
+       * Checks a batch of `@`-file picker suggestions against a policy prepared by `sandbox.preparePickerPolicy` and returns one allow decision per candidate, positionally aligned with the request. Batched deliberately: each check canonicalizes a path component-by-component through the real filesystem, so one call amortizes that over a single hop rather than dozens while the user types. A directory the policy does not itself allow can still be kept as a waypoint to an allowed subtree. An absent policy keeps every candidate.
+       *
+       * @param params A batch of file-picker candidates to check against a prepared policy.
+       *
+       * @returns Per-candidate allow decisions, positionally aligned with the request.
+       */
+      filterPickerCandidates: async (params) => connection.sendRequest("sandbox.filterPickerCandidates", params),
+      /**
+       * The sandbox a single named feature actually launches under, which is not the same as the session's sandbox. A feature is routed out of the sandbox by its own flag — `sandboxMcpServers`, `sandboxLspServers` — so an enabled session can still start one server confined and another free. Returns a disabled sandbox rather than an error when the host has no sandbox slice at all, so an absent config and an opted-out feature read alike at the launch site. A host must ask per feature rather than reuse the session config, because reading only `enabled` confines a server the user opted out of, or reports as sandboxed one that is not.
+       *
+       * @param params A sandbox config and the per-feature routing flag to resolve it for.
+       *
+       * @returns The sandbox a named feature actually launches under.
+       */
+      resolveForOptional: async (params) => connection.sendRequest("sandbox.resolveForOptional", params),
+      /**
+       * Reports whether this machine can run an OS-level command sandbox at all. A host must ask before it offers sandboxing, because the answer is a property of the machine rather than of any setting: on Linux it depends on bubblewrap being installed, and on Windows on the OS build supporting BaseContainer. Probing it requires spawning a process the first time, so the answer is cached for the life of the runtime. A host that assumes support and enables the sandbox anyway produces a session in which every shell command fails.
+       *
+       * @returns True when an OS-level sandbox can run on this host.
+       */
+      checkPlatformSupport: async () => connection.sendRequest("sandbox.checkPlatformSupport", {}),
+      /**
+       * Reports whether this Windows host's BaseContainer implementation can reach the host's loopback interface directly, which is what a local-network policy needs to avoid routing through the egress proxy. Like `sandbox.checkPlatformSupport`, the answer is a property of the machine's OS build rather than of any setting, and resolving it the first time spawns a platform probe. A host that offers the direct local-network option on a machine that lacks the capability produces a session whose sandboxed commands cannot reach local services. Always false off Windows.
+       *
+       * @returns True when the sandbox on this host can reach host loopback directly.
+       */
+      checkWindowsHostLoopbackSupport: async () => connection.sendRequest("sandbox.checkWindowsHostLoopbackSupport", {}),
+      /**
+       * The explanation a host shows when it refuses an explicit request to turn the sandbox on for a machine that cannot run one. Carries the platform-specific remedy — install bubblewrap, update Windows — and the documentation link, so a host that got `false` from `sandbox.checkPlatformSupport` does not have to compose its own reason and cannot describe the same machine differently from the runtime's own spawn path.
+       *
+       * @returns The user-facing refusal, including the platform remedy and the documentation link.
+       */
+      getUnsupportedMessage: async () => connection.sendRequest("sandbox.getUnsupportedMessage", {}),
+      /**
+       * The notice a host shows when a stored `sandbox` setting is being ignored for this session because the machine cannot enforce it. Distinct from `sandbox.getUnsupportedMessage`, which refuses an explicit request: this one reports that a setting the user already saved is inert, states that commands will run unsandboxed, and confirms the stored setting itself is left alone. A host that stays silent here leaves the user believing a sandbox is active.
+       *
+       * @returns The user-facing notice that a saved sandbox setting is inert for this session.
+       */
+      getUnsupportedSettingDisabledNotice: async () => connection.sendRequest("sandbox.getUnsupportedSettingDisabledNotice", {}),
+      /**
+       * The warning a host prints at startup when a session asked for a sandbox on a machine that cannot run one. The third of the unsupported notices, and the only one that depends on the policy in force: it names the remedy the reader can actually act on, which is the stored setting for an unmanaged host, an administrator for a managed one, and waiting for the policy to resolve when the sandbox stayed on only because the policy could not be determined. Returns no notice when the machine does support a sandbox, so a host can call it unconditionally on the startup path. A host that composes its own warning tells a managed user to change a setting their policy will overwrite.
+       *
+       * @param params The managed sandbox policy in force, which selects which remedy the notice offers.
+       *
+       * @returns The startup warning, absent when the machine can run a sandbox.
+       */
+      getUnsupportedStartupNotice: async (params) => connection.sendRequest("sandbox.getUnsupportedStartupNotice", params),
+      /**
+       * Whether one slash command stays reachable while sandbox enforcement is unavailable and the session is otherwise blocked. The permitted set is deliberately narrow — commands that only report state, and the few that let the user repair or leave the situation — and it is keyed on the arguments as well as the name, so `/sandbox status` is admitted where `/sandbox enable` is not. A host must ask rather than keep its own list: a command this returns false for is one the runtime would refuse anyway, and a divergent list either strands the user with no way out or admits a command that acts on an unenforced session.
+       *
+       * @param params One slash command, as typed, to test against the enforcement-block allowlist.
+       *
+       * @returns True when the command stays available while enforcement is blocked.
+       */
+      checkEnforcementCommand: async (params) => connection.sendRequest("sandbox.checkEnforcementCommand", params),
+      /**
+       * Returns the documentation URL a host should point a user at when it declines or downgrades a sandbox setting. The runtime owns the address so every surface cites the same page and a host does not hard-code a link that later moves.
+       *
+       * @returns The documentation URL a host cites when it declines or downgrades a sandbox setting.
+       */
+      getDocsUrl: async () => connection.sendRequest("sandbox.getDocsUrl", {})
+    },
+    /** @experimental */
+    persistence: {
+      /**
+       * Atomically replaces a JSON file's entire contents while holding the runtime's per-path lock. The lock lives in the runtime process, so a host that writes these files itself takes no part in it and can tear a concurrent runtime write; route the write here instead. Unlike a merging write this never reads or parses the existing file, so a previously corrupted snapshot is replaced wholesale rather than failing every later write. Use it only for callers that always persist a complete snapshot.
+       *
+       * @param params A complete JSON snapshot to write under the runtime's per-path file lock.
+       *
+       * @returns The outcome of a locked snapshot write.
+       */
+      writeRawJsonLocked: async (params) => connection.sendRequest("persistence.writeRawJsonLocked", params)
+    },
+    /** @experimental */
+    user: {
+      /** @experimental */
+      settings: {
+        /**
+         * Adds or removes one hook key in the user `disabledHooks` setting, rewriting settings.json in place and leaving every other setting untouched. Reports a typed outcome rather than failing the call, so a host can tell an unparseable settings file apart from a write that could not complete.
+         *
+         * @param params One hook to disable or re-enable.
+         *
+         * @returns Outcome of rewriting the `disabledHooks` setting.
+         */
+        setHookDisabled: async (params) => connection.sendRequest("user.settings.setHookDisabled", params),
+        /**
+         * Reads the user's settings document exactly as `user.settings.load` does, but from a caller-supplied configuration directory instead of the one the server resolved for itself. Use this when a consumer scopes a session to its own Copilot home — the SDK's per-session `configDir` override — so the settings read match the directory that session actually uses. An absent or empty `configDir` resolves the server's own home, making this identical to `user.settings.load`. Hook-validation relaxations are deliberately not caller-supplied: they continue to come from the server's environment, so a consumer cannot widen the host's hook policy through this method.
+         *
+         * @param params Selects the configuration directory whose user settings to read.
+         *
+         * @returns The stored user settings document, keyed by setting name.
+         */
+        loadForConfigDir: async (params) => connection.sendRequest("user.settings.loadForConfigDir", params),
+        /**
+         * Reads a repository's checked-in settings document as stored, normalized, together with any diagnostic raised while reading it. This is the repository half of the layering `user.settings.get` reports: `user.settings.load` reads the user's own document, and this reads the one a repository checks in to govern the keys `user.settings.governanceKeys` lists as repo-governable. A document that fails to parse, or that sets a key a repository may not govern, is reported through `warning` while the settings that did load are still returned, so a consumer surfaces the diagnostic and continues rather than failing the session. When `repoRoot` is the user's home directory the Claude-compatible configuration is skipped, so a home-directory session does not inherit a personal config as repository policy.
+         *
+         * @param params Selects the repository whose checked-in settings to read.
+         *
+         * @returns A repository's settings as stored, together with any diagnostic raised while reading them.
+         */
+        loadRepo: async (params) => connection.sendRequest("user.settings.loadRepo", params),
+        /**
+         * Reads a repository's settings and merges them over a supplied user layer in one step, returning the settings a consumer should act on inside that repository. Use this rather than reading the two layers separately: the merge is per setting and collection-aware, so a repository adds to the collections it is allowed to influence without replacing the user's own entries, and a whole-document overlay would get that wrong. Any diagnostic raised while reading the repository layer is returned rather than printed, so the consumer decides how to surface it; the settings that did load are merged regardless.
+         *
+         * @param params A repository to read settings from, and the user layer they are merged over.
+         *
+         * @returns The settings a consumer should act on inside a repository, together with any diagnostic raised while reading the repository layer.
+         */
+        loadAndMergeRepo: async (params) => connection.sendRequest("user.settings.loadAndMergeRepo", params),
+        /**
+         * Reports the on-disk path of the settings document `user.settings.load` and `user.settings.set` read and write. Resolved the same way those methods resolve it, so a host that shows or opens the settings file names the file the runtime actually uses, including the extensionless legacy `settings` file when that is what is present.
+         *
+         * @returns The on-disk location of the user's settings document.
+         */
+        getPath: async () => connection.sendRequest("user.settings.getPath", {}),
+        /**
+         * Reads the user's stored settings together with the diagnostic raised while reading them. This is `user.settings.load` plus the reason part of the document was ignored: that one answers the document alone, so a caller cannot tell a clean read from a salvaged one. Read this when the caller is about to write the file back, where accepting a partial parse would discard every value the loader could not read. The settings that did load are still reported alongside the warning, so a consumer may surface it and continue instead of failing.
+         *
+         * @returns The user's stored settings, together with any diagnostic raised while reading them.
+         */
+        loadWithWarning: async () => connection.sendRequest("user.settings.loadWithWarning", {}),
+        /**
+         * Folds a user settings layer over a managed (enterprise policy) layer and returns the merged settings. The managed layer's governance keys win, `autoTier` resolves through its overridable form, and the two per-entry control maps (`enabledPlugins`, `extraKnownMarketplaces`) union across the layers and are then stamped back from the managed layer, so each entry an administrator declares wins while the user keeps control of the rest. The parameters are named for their layers rather than being a generic base/override pair: nothing about a settings object identifies which layer produced it, so the runtime cannot detect a transposed call, and transposing one resolves the governance keys in the user's favour instead of the administrator's. Supplying only one layer returns it unchanged, and supplying neither returns an empty object. Rejects a managed `autoTier` that is neither a user-configurable tier nor a single-key overridable form, rather than silently dropping it.
+         *
+         * @param params The managed (enterprise policy) layer and the user layer to fold together. The field names carry the layer identity: nothing about a settings object identifies which layer produced it, so a generic base/override pair would let a caller transpose them and silently resolve the governance keys in the user's favour.
+         *
+         * @returns The user layer folded over the managed layer.
+         */
+        mergeManagedAndUser: async (params) => connection.sendRequest("user.settings.mergeManagedAndUser", params),
+        /**
+         * Folds a repository's settings layer into the user layer. Each repo-overridable key carries a directional policy chosen so a repository can only add restrictions and never relax the user's own. The two per-entry managed control maps are the exception those directional rules cannot express — a repository may legitimately enable plugins and declare marketplaces — so they are re-stamped afterwards from the runtime's ambient managed policy. That makes the result depend on the runtime process's managed state and not on the arguments alone: a host must call this rather than reimplement the fold, or a repository could relax a restriction the administrator imposed. Rejects when either layer is not a JSON object.
+         *
+         * @param params The user layer and the repository layer to fold together.
+         *
+         * @returns The repository layer folded into the user layer.
+         */
+        mergeRepoValue: async (params) => connection.sendRequest("user.settings.mergeRepoValue", params),
+        /**
+         * Runs the one-time migration that moves a staff account's update channel to stable, and records that it ran. Idempotent and self-gating: it takes a lock over the global-state file, re-reads the completion stamp inside it, and returns `current` rather than migrating twice, so two hosts racing at startup cannot both migrate. Only a `migrated` status means the persisted settings changed and the caller should reload them. An account on the experimental channel is deliberately left alone and reported as `excluded-experimental`.
+         *
+         * @param params The filesystem and environment facts a user-settings file is resolved from. Passed explicitly rather than read from the runtime's own process, so a host whose configuration directory differs from its process environment resolves the file it means.
+         *
+         * @returns The outcome of the one-time staff update-channel migration.
+         */
+        migrateStaffUpdateChannelOnce: async (params) => connection.sendRequest("user.settings.migrateStaffUpdateChannelOnce", params),
+        /**
+         * Runs the one-time reset that clears a staff account's pinned model selection, and reports the timestamp the host should record. Idempotent and self-gating: the reset is gated on a fixed cutoff, so a caller that passes back the timestamp it recorded gets `didReset: false` rather than a second reset. It applies to staff accounts only; any other account is reported as not reset without the settings document being opened. Only `didReset: true` means the persisted settings changed, and only then are the updated settings returned for the host to adopt.
+         *
+         * @param params Selects the configuration directory to run the one-time staff model-selection reset against, and supplies the caller's record of whether it has already run.
+         *
+         * @returns The outcome of the one-time staff model-selection reset.
+         */
+        resetStaffModelSelectionOnce: async (params) => connection.sendRequest("user.settings.resetStaffModelSelectionOnce", params),
+        /**
+         * Reports the top-level keys in the user settings document that the runtime does not recognize, phrased for display to the user. This is a separate question from the warning `user.settings.loadWithWarning` returns: that one describes parts of the document the loader had to ignore to load the rest, whereas an unknown key parses cleanly and is simply not a setting, so a host that surfaces only the load warning silently accepts a misspelled key that will never take effect. Nothing is reported when the document is absent, unreadable, or failed to load, because an unknown-key list derived from a document the runtime could not read would be misleading rather than helpful. Inspection never modifies the document.
+         *
+         * @param params Selects the configuration directory whose user settings document should be inspected for unrecognized top-level keys.
+         *
+         * @returns The unrecognized top-level keys found in the user settings document, already phrased for display.
+         */
+        getUnknownKeysWarning: async (params) => connection.sendRequest("user.settings.getUnknownKeysWarning", params),
+        /**
+         * Resolves the effective runtime settings for a host that is about to start a session, layering the given overrides over the settings documents, the environment and the platform defaults. A host cannot assemble this itself: the precedence between a user document, a repository document, the managed layers and the environment is the runtime's own rule, and a host that re-implements it drifts from the server it is configuring. The working directory, environment and platform are taken as arguments rather than read from the server process, so a host resolving settings for a directory other than its own gets that directory's answer. Nothing is written; this only computes.
+         *
+         * @param params The overrides and host context to resolve effective runtime settings from.
+         *
+         * @returns The effective runtime settings, keyed by setting name. Keys this runtime does not recognize are preserved rather than dropped, so a caller reading a document written by a newer runtime keeps every value.
+         */
+        buildRuntime: async (params) => connection.sendRequest("user.settings.buildRuntime", params),
+        /**
+         * Runs the one-time migration that moves a staff account's log level to the current default, and records that it ran. Idempotent and self-gating: it takes a lock over the global-state file and re-reads the completion stamp inside it, so two hosts racing at startup cannot both migrate. Only `refreshed` can have changed the persisted settings, and the settings it returns are the document re-read after the write, so a host should adopt them rather than reloading separately and racing the next writer.
+         *
+         * @param params Selects the configuration directory to run the one-time staff log-level migration against, and supplies the caller's record of whether it has already run.
+         *
+         * @returns The outcome of the one-time staff log-level migration.
+         */
+        migrateStaffLogLevelOnce: async (params) => connection.sendRequest("user.settings.migrateStaffLogLevelOnce", params),
+        /**
+         * Runs the one-time cleanup that removes obsolete CLI-owned settings and legacy rubber-duck keys from the user's settings document, and reports what it did. Idempotent and safe to call on every startup: with nothing obsolete left it reports `unchanged` and writes nothing. The cleanup preserves every key it does not recognize, so a setting written by a newer host is never dropped by an older one, and a document that fails to parse is reported `invalid` and left untouched rather than rewritten from a partial read. The cleaned document is not returned: it is written before this replies, so `user.settings.load` reads it authoritatively. A host that surfaces unrecognized keys through `user.settings.unknownKeys` wants this first, because the keys this retires would otherwise be shown to the user as if they were misspelled settings.
+         *
+         * @param params Selects the configuration directory whose settings document to clean.
+         *
+         * @returns The outcome of the one-time obsolete-settings cleanup.
+         */
+        migrateObsoleteOnDisk: async (params) => connection.sendRequest("user.settings.migrateObsoleteOnDisk", params),
+        /**
+         * Resolves the on-disk locations of the settings files this runtime reads, so a consumer can show or open them. The user path is the same file `user.settings.get`, `user.settings.load`, and `user.settings.set` operate on. Supply `repoRoot` to also resolve that repository's checked-in and local settings paths. A path is reported whether or not the file exists.
+         *
+         * @param params Selects which settings file paths to resolve.
+         *
+         * @returns On-disk locations of the settings files this runtime reads. A path is reported whether or not the file exists.
+         */
+        getPaths: async (params) => connection.sendRequest("user.settings.getPaths", params),
+        /**
+         * Lists the top-level user-setting keys by who is allowed to govern them: `repo` keys a repository may override through `.github/copilot/settings.json`, `claudeRepo` keys a repository may override through a Claude-compatible config, and `managed` keys an enterprise policy may fix. The lists are static for a given runtime build and fail closed: a key absent from a list cannot be governed that way.
+         *
+         * @returns Top-level user-setting keys grouped by who may govern them.
+         */
+        listGovernanceKeys: async () => connection.sendRequest("user.settings.listGovernanceKeys", {}),
+        /**
+         * Atomically edits one canonical user setting inside its settings-file lock. Reads, canonicalizes touched aliases, applies the edit, validates the resulting top-level setting and writes before releasing the lock. An explicit autoUpdatesChannel set completes the staff migration in the same transaction. Only a malformed existing file returns `invalid`; refused keys, invalid values and I/O errors reject the call.
+         *
+         * @param params One atomic edit of a canonical setting in settings.json.
+         *
+         * @returns Outcome of an atomic user or repository settings edit.
+         */
+        edit: async (params) => connection.sendRequest("user.settings.edit", params),
+        /**
+         * Rewrites legacy and snake_case setting names in a settings object to their canonical spelling. A caller editing settings.json must normalize before writing: a legacy key left in place survives the write, is re-normalized on the next load, and silently shadows the canonical value the write just stored.
+         *
+         * @param params Settings object whose key names should be canonicalized.
+         *
+         * @returns Settings object with canonical key names.
+         */
+        normalize: async (params) => connection.sendRequest("user.settings.normalize", params),
+        /**
+         * Diagnoses a set of already-loaded settings layers, reporting each key that will not take effect and why. Settings load tolerantly so that one bad key does not stop a session from starting; this method surfaces what was dropped so a caller can report it instead of silently ignoring the user's intent. Takes the layers as given rather than reading them, so a caller can diagnose exactly the content it is showing, including unsaved edits. Never echoes a setting's value, because a value may be a token or another secret. Marked internal because it exists to carry a CLI call site off the native addon, not to serve a consumer-facing need; it becomes public once an SDK consumer needs to inspect settings health itself.
+         *
+         * @param params The settings layers to diagnose.
+         *
+         * @returns The settings that will not take effect across the given layers.
+         */
+        diagnoseProblems: async (params) => connection.sendRequest("user.settings.diagnoseProblems", params),
+        /**
+         * Validates one top-level setting subtree and writes just that key to settings.json as a single step. Doing both here closes the race a caller cannot close itself: between a separate preflight read and the write, the file may change. Rewriting only the touched key keeps legacy siblings out of settings.json. Answers a status rather than failing, so a validation problem and a write problem stay distinguishable.
+         *
+         * @param params A single top-level setting subtree to validate and write.
+         *
+         * @returns Outcome of validating and writing one top-level setting subtree.
+         */
+        applyTopKey: async (params) => connection.sendRequest("user.settings.applyTopKey", params),
+        /**
+         * Replaces the user settings file's entire content in one write. A key absent from `settings` is removed, which is what distinguishes this from `user.settings.set`: that one merges, so it can never clear a key the caller has dropped. For a caller saving the result of a raw edit, a merge would silently resurrect every key the user deleted. Records the same one-time mutation marks a per-key write records, so a setting the user has now chosen explicitly stops being migrated for them.
+         *
+         * @param params The whole content to store in the user settings file.
+         */
+        writeAll: async (params) => connection.sendRequest("user.settings.writeAll", params),
+        /**
+         * Merges a partial object into one top-level user setting, re-reading the stored value inside this runtime process's settings.json write lock so that concurrent writers in this process to different sub-fields of the same key do not clobber each other. Unlike `user.settings.set`, which replaces a key's whole value with what the caller last read, this keeps sub-fields the caller did not name when both the stored value and supplied value are objects; otherwise the supplied value replaces the stored value. Use it whenever two independent surfaces own different sub-fields of one setting. Returns the key's stored value after the write, in `value`.
+         *
+         * @param params Names the user setting to merge into, and the partial object to merge.
+         *
+         * @returns The stored value of the user setting after the merge.
+         */
+        update: async (params) => connection.sendRequest("user.settings.update", params),
+        /**
+         * Reads settings.json as stored for a caller that is about to edit it. Unlike `user.settings.get`, this returns file values rather than per-key metadata and defaults. Reports `missing` for an absent file and `invalid` when the existing file will not parse. Retired config.json and extensionless files are not read.
+         *
+         * @returns Contents of settings.json as stored, for a caller about to rewrite it.
+         */
+        loadForEdit: async () => connection.sendRequest("user.settings.loadForEdit", {}),
+        /**
+         * Validates one top-level setting subtree without writing it, reporting each problem with the path it applies to. Scoped to a single top-level key on purpose: validating the whole file would reject an edit whenever an unrelated pre-existing field is malformed, locking the user out of the very tool that could fix it.
+         *
+         * @param params A single top-level setting subtree to validate.
+         *
+         * @returns Outcome of validating one top-level setting subtree.
+         */
+        validate: async (params) => connection.sendRequest("user.settings.validate", params)
+      }
+    },
+    /** @experimental */
+    repo: {
+      /** @experimental */
+      settings: {
+        /**
+         * Atomically edits one allowed top-level repository setting. Reads the raw file, preserves unrelated keys, applies one scalar or list edit, validates the result and writes under one file lock, so concurrent sibling or list edits are not lost. A malformed or unsafe existing file returns `invalid` without a write; rejected keys, invalid values and I/O errors reject the call.
+         *
+         * @param params One atomic edit of an allowed top-level repository setting.
+         *
+         * @returns Outcome of an atomic user or repository settings edit.
+         */
+        edit: async (params) => connection.sendRequest("repo.settings.edit", params),
+        /**
+         * Reads one repository settings file without settings normalization or layering. The existing JSONC parser accepts comments and trailing commas and applies its prototype-safety rules. Missing or blank files return an empty valid config. Invalid files return an empty config with invalid=true; other read failures reject.
+         *
+         * @param params Which repository settings file to read.
+         *
+         * @returns Parsed repository settings without normalization or layering.
+         */
+        readRaw: async (params) => connection.sendRequest("repo.settings.readRaw", params),
+        /**
+         * Writes or removes one allowed top-level repository setting through the existing validator and file lock. Preserves unrelated stored keys. Invalid keys, values, existing documents, and I/O errors reject without replacing the file. Deletion requires delete=true; otherwise value must be present.
+         *
+         * @param params One key to write or remove in a repository settings file.
+         */
+        writeKey: async (params) => connection.sendRequest("repo.settings.writeKey", params),
+        /**
+         * Replaces the repository-overridable settings in one locked write. Allowed keys present in settings are validated and written; allowed keys absent from settings are removed. Other input keys are ignored, and unknown keys already stored in the file remain unchanged. Invalid values or an invalid existing file reject without a partial write.
+         *
+         * @param params The complete set of repository-overridable settings to store.
+         */
+        writeAll: async (params) => connection.sendRequest("repo.settings.writeAll", params)
+      }
+    },
+    /** @experimental */
+    featureFlags: {
+      /**
+       * Resolves named gates against this installation's cached online-experiment assignment, for the account the runtime is already authenticated as. Unlike `featureFlags.resolve`, which layers static availability with the populations supplied, this reads the experiment assignment the runtime cached for its own current authentication, so a launch can honor a rollout before any session exists. The account is never taken from the request: naming one would read another account's cached assignments. The cached assignment answers immediately and any network refresh happens behind it, so this call does not wait on the network. Not available to an extension, which cannot carry the user's consent to read their assignment.
+       *
+       * @param params Caller population and startup inputs to resolve named online-experiment gates for. Carries no account: the runtime resolves the assignment for the authentication it already holds.
+       *
+       * @returns The resolved gates, keyed by flag name.
+       */
+      resolveStartupGates: async (params) => connection.sendRequest("featureFlags.resolveStartupGates", params),
+      /**
+       * Lists every feature flag this runtime declares, with the population each one is declared for, its experimental description, and the online-experiment flag it maps to. This is the static catalog: it describes how each flag is defined, not whether it is on for anyone. Use `featureFlags.resolve` for static values with caller overrides, not active runtime values or experiment assignments.
+       *
+       * @returns Every feature flag this runtime declares, with the shape each one was declared with.
+       */
+      listMetadata: async () => connection.sendRequest("featureFlags.listMetadata", {}),
+      /**
+       * Computes static feature flags from the supplied population and overrides without changing runtime state or verifying audience membership. Starts from declared availability, then applies direct feature-flag environment values, user settings, and explicit `flagOverrides`. It does not apply `COPILOT_EXP_*` experiment assignments, authenticated startup gates, or active runtime state. Settings include `enabledFeatureFlags`, the legacy `feature_flags.enabled` list, and supported convenience settings. Supply `baseFlags` to use an existing flag set instead of declared availability. Omit `isStaffGitHub` or `isStaffMicrosoft` when membership was never recorded: a legacy staff account then counts as both populations.
+       *
+       * @param params Caller population and overrides for static feature-flag resolution, independent of experiment assignments and active runtime state.
+       *
+       * @returns The resolved feature flags, keyed by flag name.
+       */
+      resolve: async (params) => connection.sendRequest("featureFlags.resolve", params)
+    },
+    /** @experimental */
+    permissions: {
+      /** @experimental */
+      locations: {
+        /**
+         * Drops stored per-location permission grants whose directory no longer exists, and reports which location keys were removed. Runs against the permission store under the runtime's own Copilot home, the same store `session.permissions.locations.resolve` reads. Marked internal because it exists to carry a CLI call site off the napi boundary onto the SDK contract; it is migration plumbing, not a surface consumers are meant to depend on. It can become public once an SDK consumer needs to prune its own permission store.
+         *
+         * @returns Which stored location permissions were dropped because their directory is gone.
+         */
+        cleanupOrphaned: async () => connection.sendRequest("permissions.locations.cleanupOrphaned", {})
+      },
+      /** @experimental */
+      folderTrust: {
+        /**
+         * Reports whether a folder is trusted, reading the persisted trusted-folders list directly rather than through a session. Use this from a host that has no session yet, such as a one-shot command deciding whether to honor a checkout's own settings. It differs from the session-scoped check in two ways that matter: it takes the configuration directory to read the list from, instead of inheriting the session's, and it answers only from the persisted list, so trust a user granted for the lifetime of one session is not visible here. A host that has a session should prefer the session-scoped check, which also covers session-only trust.
+         *
+         * @param params A folder to check against a persisted trusted-folders list, and the configuration directory holding that list.
+         *
+         * @returns Folder trust check result.
+         */
+        checkTrust: async (params) => connection.sendRequest("permissions.folderTrust.checkTrust", params)
+      },
+      /**
+       * Interprets a verbatim managed `permissions` slice into the three policy questions a host asks before granting elevated permissions: whether bypass-permissions mode is forbidden, whether a policy exists that this build could not determine, and whether the layer supplies permission rules the session must enforce. An absent or empty slice means no managed policy applies. The runtime and its permission service share one policy type, so a new managed permission setting is interpreted in exactly one place; a host that reimplements the reading would silently diverge the first time that set grows. Hosts must fail closed on an undetermined policy rather than treating it as permission granted.
+       *
+       * @param params The verbatim managed `permissions` slice to interpret.
+       *
+       * @returns The policy questions a host asks before granting elevated permissions.
+       */
+      evaluateManagedPolicy: async (params) => connection.sendRequest("permissions.evaluateManagedPolicy", params)
+    },
+    /** @experimental */
+    managedSettings: {
+      /**
+       * Discovers device-managed settings the way the runtime's own device layer does, and reports the sandbox floor and the load outcome alongside the validated document. This differs from `managedSettings.read` in three ways a policy-enforcing host depends on: a document that validates to an empty object is reported as absent rather than as an empty policy, a discovery error does not suppress a document that still validates, and a failure is reported as a flag rather than only as error text. Hosts that compose the device layer into an effective policy use this, because `managedSettings.read` cannot distinguish "no device policy" from "device policy could not be read" and would silently hand the user's own layer the win.
+       *
+       * @returns The device-managed settings layer, with the sandbox floor and the load outcome a host needs to compose it into an effective policy.
+       */
+      readDevice: async () => connection.sendRequest("managedSettings.readDevice", {}),
+      /**
+       * Retains the supplied managed layers as this runtime process's startup policy and re-applies the result to every live session. Hosts that own their own short-lived process policy use this, so a guarded mutation is checked against the policy the host actually fetched. Retaining is a whole-process replacement rather than a merge, so a host that already resolved a good policy must not retain a partial one over it. The failure flags are honest inputs rather than assumptions: reporting a fetch or load that failed keeps the layers already retained, and the interim fail-closed state, instead of clearing them.
+       *
+       * @param params The managed layers to retain as this process's startup policy, with the outcome of fetching each one.
+       */
+      retainPolicy: async (params) => connection.sendRequest("managedSettings.retainPolicy", params),
+      /**
+       * Stamps an effective managed policy's individually-controlled entries onto a user settings document, returning the settings a host should actually act on. The managed layer wins on every plugin spec and marketplace name it names, and leaves everything it does not name as the user wrote it. Hosts use this rather than merging the two documents themselves, because the merge is per entry rather than per document and a whole-document overlay would either discard the user's unmanaged entries or let a user entry outrank a managed one. Omitting the managed layer returns the settings unchanged, which is what an unmanaged host wants. Rejects when either document is present but is not a JSON object rather than treating it as absent, since silently dropping a malformed policy hands the user's layer the win on exactly the entries the policy exists to control.
+       *
+       * @param params A user settings document and the effective managed policy whose controlled entries should be stamped onto it.
+       *
+       * @returns The user settings with the managed layer's controlled entries stamped on.
+       */
+      applyControls: async (params) => connection.sendRequest("managedSettings.applyControls", params),
+      /**
+       * Validates the managed settings a client is supplying for a session it is about to open, and returns them reduced to the keys a client is allowed to set. A client-supplied policy is not the same thing as an administrator's: it may only narrow permissions, so this accepts `permissions` and rejects every other key outright rather than ignoring it. Rejecting is the point — a host that silently dropped an unsupported key would report a policy as applied while running without it. Hosts call this before opening the session rather than letting the open fail, so a malformed policy is reported against the request that carried it. The runtime applies the same rule again when the session starts, so this cannot be used to smuggle a wider document past it. An accepted document that sets nothing comes back as an empty object, which is distinct from supplying nothing at all.
+       *
+       * @param params The client-supplied managed settings to validate and normalize. Omitting them is valid and yields no policy.
+       *
+       * @returns The accepted managed settings, reduced to the keys a client is allowed to set.
+       */
+      parseClientValue: async (params) => connection.sendRequest("managedSettings.parseClientValue", params),
+      /**
+       * Composes the supplied server, device/MDM, device sandbox floor and policy-helper layers into the single effective managed policy a host should enforce, resolving each key across the layers by the runtime's own precedence rules. Hosts that assemble managed layers themselves use this so their precedence matches the runtime's exactly instead of reimplementing it. The composition is not a pure function of its inputs: an advisory sandbox force-on that arrived over the server channel is declined when this host cannot run a sandbox, so the result reflects the runtime host's capabilities, and the returned settings carry `sandboxAdvisoryFloorDeclined: true` when that happened. Enforced channels (device/MDM and policy helper) are never declined, and a server force-on carrying `failIfUnavailable` is preserved so the session fails loudly instead of quietly running unsandboxed. Rejects when a supplied layer is present but is not a JSON object, rather than treating it as unmanaged, because silently dropping a malformed policy would hand the user's own layer the win on exactly the keys the policy exists to control.
+       *
+       * @param params The managed-settings layers to compose into an effective policy. Every layer is optional; omitting all of them yields no effective policy.
+       *
+       * @returns The effective managed policy composed from the supplied layers.
+       */
+      resolveEffectiveValue: async (params) => connection.sendRequest("managedSettings.resolveEffectiveValue", params),
+      /**
+       * Decides what a host must do to its bypass-permissions state after a managed-policy resolution lands, given the state already in force and the account now signed in. A host holds two pieces of state — which layer disabled bypass mode, and for a server-delivered disable, the account it was pinned to — and cannot decide the next step from the new policy alone. Three rules make that so, and each one is a control rather than a preference. A device/MDM disable outranks the account, so a later server answer never lifts it. An unknown policy, which is what a failed fetch or a refusal this build cannot enforce yields, preserves whatever is in force instead of reverting to permissive. And a server disable is lifted only when the account it was pinned to is no longer the signed-in one, which is what makes signing in to an unrestricted account recover without a restart while a reconnect on the same restricted account does not. Hosts call this rather than reimplementing it because getting the pinning backwards either strands a disable on an account that never carried one or drops one that still applies. `setDisabledState` is omitted when the host must leave its stored flag untouched, which is distinct from being told to set it to false.
+       *
+       * @param params The bypass-permissions state a host holds today, the account now signed in, and what the managed-policy resolution said.
+       *
+       * @returns The bypass-permissions state a host should hold after the resolution, and what it must do to get there.
+       */
+      resolveBypassDisableTransition: async (params) => connection.sendRequest("managedSettings.resolveBypassDisableTransition", params),
+      /**
+       * Resolves managed (enterprise policy) settings for a host from every layer at once: the account's server-delivered policy, the device/MDM layer, and a platform policy helper. Hosts use this instead of fetching and composing the layers themselves, because the per-layer precedence and the fail-closed rules that apply when a layer cannot be confirmed are the runtime's own and must match the policy a session will later enforce. It does not retain or apply anything to process-global policy state, so a host may call it before any session exists — which is the point, since plugin activation and one-shot commands resolve policy before a session is available to carry it. The returned per-layer outcome flags are load-bearing rather than diagnostic: a host must distinguish an unmanaged device from a managed device whose policy could not be confirmed, and apply its fail-closed gates in the second case. Reports its diagnostics in `logMessages` rather than logging them, so a host that runs before a log sink exists still sees them.
+       *
+       * @param params Inputs describing the host and account an ingestion should resolve managed policy for.
+       *
+       * @returns The managed policy layers an ingestion resolved, together with the per-layer outcome flags a host needs to decide how much to trust the result. The flags are reported rather than folded into the settings because a host must be able to distinguish an unmanaged device from a managed device whose policy could not be confirmed, and apply its fail-closed gates in the second case.
+       */
+      ingest: async (params) => connection.sendRequest("managedSettings.ingest", params),
+      /**
+       * Resolves the managed (enterprise policy) settings a host must enforce from startup, and judges the account against the enterprise sign-in pin in the same pass. This composes the layers the way `managedSettings.ingest` does and then answers the two questions a host cannot answer for itself: which fail-closed floors apply when a layer could not be confirmed, and whether this credential is allowed to sign in at all. The sign-in verdict is the reason a host must not assemble this itself from `managedSettings.ingest` — a pinned organization is an access control, and a host that composed the layers but skipped the pin would let a developer sign in with a personal or another enterprise's account and escape every control that keys off the signed-in identity. The verdict is computed on every resolution, including one that is not retained, so declining to apply policy never widens access. Set `retainAndApply` to keep the resolved policy as this runtime process's startup policy; leave it false to resolve without side effects.
+       *
+       * @param params Inputs describing the host and account a startup policy resolution should run for. Mirrors `managedSettings.ingest`, and adds the decision of whether the resolved policy is retained for this runtime process.
+       *
+       * @returns The startup policy a resolution composed, the per-layer outcome flags a host needs to decide how much to trust it, and the enterprise sign-in verdict for the credential it ran against. The flags are reported rather than folded into the settings because a host must distinguish an unmanaged device from a managed device whose policy could not be confirmed, and apply its fail-closed gates in the second case.
+       */
+      resolveStartupPolicy: async (params) => connection.sendRequest("managedSettings.resolveStartupPolicy", params),
+      /**
+       * Resolves the managed `remoteControl` policy for an account on its own, for a host deciding whether a remote-control session may start. Composes the same layers as `managedSettings.ingest` and returns only that one key, so a host does not have to know which layer won. An absent policy means the account is unmanaged for this capability and the host may proceed; that default is safe only while absence really does mean "no policy", so a service refusal that says an account policy exists which this client is too old to enforce resolves to an explicit disabled policy instead of to absence. A resolution that cannot be completed is rejected rather than answered as absence, for the same reason.
+       *
+       * @param params Inputs describing the host and account whose managed remote-control policy should be resolved. Mirrors `managedSettings.ingest`, and deliberately carries no retention decision: reading this gate never becomes this runtime process's startup policy.
+       *
+       * @returns The managed remote-control policy in force for an account, if any. An absent policy means the account is unmanaged for this capability, which a host reads as allowed — so absence here is a positive statement that no policy applies, never a stand-in for a resolution that failed. A resolution that cannot be completed is rejected instead.
+       */
+      loadRemoteControl: async (params) => connection.sendRequest("managedSettings.loadRemoteControl", params),
+      /**
+       * Evaluates the device-channel enterprise sign-in pin (MDM plist, registry, or managed-settings file) against a credential, without resolving any server-delivered policy. This is the gate an entry point runs before it branches, and the only one that can refuse a developer's first sign-in: it is local, needs no credential, and a server-delivered pin only ever reaches accounts already inside the organization. It fails closed by construction — a discovery that cannot determine whether a pin exists refuses rather than allows, because a control that fails open under a triggerable condition is not a control. Hosts that also want the server channel should call `managedSettings.resolveStartupPolicy`, which folds both channels into one verdict.
+       *
+       * @param params The credential and environment to evaluate the device-channel sign-in pin against.
+       *
+       * @returns The verdict of the `forceLoginOrgs` enterprise sign-in pin for one credential. A managed device may pin Copilot to an approved set of GitHub organizations so a developer cannot sign in with a personal — or another enterprise's — account and escape every control that keys off the signed-in identity. A host must refuse to proceed when `allowed` is false; the remaining fields explain the refusal rather than qualifying it.
+       */
+      resolveDeviceForceLoginOrgsGate: async (params) => connection.sendRequest("managedSettings.resolveDeviceForceLoginOrgsGate", params)
+    },
+    /** @experimental */
+    host: {
+      /**
+       * Requests app-owned materialization over the owning SDK participant.
+       *
+       * @param params One application-owned session handoff, requested by the supervised hosting participant.
+       *
        * @returns The resident session the application has materialized on its own connection.
        */
       createSession: async (params) => connection.sendRequest("host.createSession", params),
@@ -1211,129 +1712,6 @@ function createInternalServerRpc(connection) {
       writeKey: async (params) => connection.sendRequest("globalState.writeKey", params)
     },
     /** @experimental */
-    user: {
-      /** @experimental */
-      settings: {
-        /**
-         * Resolves the on-disk locations of the settings files this runtime reads, so a consumer can show or open them. The user path is the same file `user.settings.get`, `user.settings.load`, and `user.settings.set` operate on. Supply `repoRoot` to also resolve that repository's checked-in and local settings paths. A path is reported whether or not the file exists.
-         *
-         * @param params Selects which settings file paths to resolve.
-         *
-         * @returns On-disk locations of the settings files this runtime reads. A path is reported whether or not the file exists.
-         */
-        getPaths: async (params) => connection.sendRequest("user.settings.getPaths", params),
-        /**
-         * Lists the top-level user-setting keys by who is allowed to govern them: `repo` keys a repository may override through `.github/copilot/settings.json`, `claudeRepo` keys a repository may override through a Claude-compatible config, and `managed` keys an enterprise policy may fix. The lists are static for a given runtime build and fail closed: a key absent from a list cannot be governed that way.
-         *
-         * @returns Top-level user-setting keys grouped by who may govern them.
-         */
-        listGovernanceKeys: async () => connection.sendRequest("user.settings.listGovernanceKeys", {}),
-        /**
-         * Atomically edits one canonical user setting inside its settings-file lock. Reads, canonicalizes touched aliases, applies the edit, validates the resulting top-level setting and writes before releasing the lock. An explicit autoUpdatesChannel set completes the staff migration in the same transaction. Only a malformed existing file returns `invalid`; refused keys, invalid values and I/O errors reject the call.
-         *
-         * @param params One atomic edit of a canonical setting in settings.json.
-         *
-         * @returns Outcome of an atomic user or repository settings edit.
-         */
-        edit: async (params) => connection.sendRequest("user.settings.edit", params),
-        /**
-         * Rewrites legacy and snake_case setting names in a settings object to their canonical spelling. A caller editing settings.json must normalize before writing: a legacy key left in place survives the write, is re-normalized on the next load, and silently shadows the canonical value the write just stored.
-         *
-         * @param params Settings object whose key names should be canonicalized.
-         *
-         * @returns Settings object with canonical key names.
-         */
-        normalize: async (params) => connection.sendRequest("user.settings.normalize", params),
-        /**
-         * Diagnoses a set of already-loaded settings layers, reporting each key that will not take effect and why. Settings load tolerantly so that one bad key does not stop a session from starting; this method surfaces what was dropped so a caller can report it instead of silently ignoring the user's intent. Takes the layers as given rather than reading them, so a caller can diagnose exactly the content it is showing, including unsaved edits. Never echoes a setting's value, because a value may be a token or another secret. Marked internal because it exists to carry a CLI call site off the native addon, not to serve a consumer-facing need; it becomes public once an SDK consumer needs to inspect settings health itself.
-         *
-         * @param params The settings layers to diagnose.
-         *
-         * @returns The settings that will not take effect across the given layers.
-         */
-        diagnoseProblems: async (params) => connection.sendRequest("user.settings.diagnoseProblems", params),
-        /**
-         * Validates one top-level setting subtree and writes just that key to settings.json as a single step. Doing both here closes the race a caller cannot close itself: between a separate preflight read and the write, the file may change. Rewriting only the touched key keeps legacy siblings out of settings.json. Answers a status rather than failing, so a validation problem and a write problem stay distinguishable.
-         *
-         * @param params A single top-level setting subtree to validate and write.
-         *
-         * @returns Outcome of validating and writing one top-level setting subtree.
-         */
-        applyTopKey: async (params) => connection.sendRequest("user.settings.applyTopKey", params),
-        /**
-         * Replaces the user settings file's entire content in one write. A key absent from `settings` is removed, which is what distinguishes this from `user.settings.set`: that one merges, so it can never clear a key the caller has dropped. For a caller saving the result of a raw edit, a merge would silently resurrect every key the user deleted. Records the same one-time mutation marks a per-key write records, so a setting the user has now chosen explicitly stops being migrated for them.
-         *
-         * @param params The whole content to store in the user settings file.
-         */
-        writeAll: async (params) => connection.sendRequest("user.settings.writeAll", params),
-        /**
-         * Merges a partial object into one top-level user setting, re-reading the stored value inside this runtime process's settings.json write lock so that concurrent writers in this process to different sub-fields of the same key do not clobber each other. Unlike `user.settings.set`, which replaces a key's whole value with what the caller last read, this keeps sub-fields the caller did not name when both the stored value and supplied value are objects; otherwise the supplied value replaces the stored value. Use it whenever two independent surfaces own different sub-fields of one setting. Returns the key's stored value after the write, in `value`.
-         *
-         * @param params Names the user setting to merge into, and the partial object to merge.
-         *
-         * @returns The stored value of the user setting after the merge.
-         */
-        update: async (params) => connection.sendRequest("user.settings.update", params),
-        /**
-         * Reads settings.json as stored for a caller that is about to edit it. Unlike `user.settings.get`, this returns file values rather than per-key metadata and defaults. Reports `missing` for an absent file and `invalid` when the existing file will not parse. Retired config.json and extensionless files are not read.
-         *
-         * @returns Contents of settings.json as stored, for a caller about to rewrite it.
-         */
-        loadForEdit: async () => connection.sendRequest("user.settings.loadForEdit", {}),
-        /**
-         * Validates one top-level setting subtree without writing it, reporting each problem with the path it applies to. Scoped to a single top-level key on purpose: validating the whole file would reject an edit whenever an unrelated pre-existing field is malformed, locking the user out of the very tool that could fix it.
-         *
-         * @param params A single top-level setting subtree to validate.
-         *
-         * @returns Outcome of validating one top-level setting subtree.
-         */
-        validate: async (params) => connection.sendRequest("user.settings.validate", params)
-      }
-    },
-    /** @experimental */
-    featureFlags: {
-      /**
-       * Lists every feature flag this runtime declares, with the population each one is declared for, its experimental description, and the online-experiment flag it maps to. This is the static catalog: it describes how each flag is defined, not whether it is on for anyone. Use `featureFlags.resolve` for static values with caller overrides, not active runtime values or experiment assignments.
-       *
-       * @returns Every feature flag this runtime declares, with the shape each one was declared with.
-       */
-      listMetadata: async () => connection.sendRequest("featureFlags.listMetadata", {}),
-      /**
-       * Computes static feature flags from the supplied population and overrides without changing runtime state or verifying audience membership. Starts from declared availability, then applies direct feature-flag environment values, user settings, and explicit `flagOverrides`. It does not apply `COPILOT_EXP_*` experiment assignments, authenticated startup gates, or active runtime state. Settings include `enabledFeatureFlags`, the legacy `feature_flags.enabled` list, and supported convenience settings. Supply `baseFlags` to use an existing flag set instead of declared availability. Omit `isStaffGitHub` or `isStaffMicrosoft` when membership was never recorded: a legacy staff account then counts as both populations.
-       *
-       * @param params Caller population and overrides for static feature-flag resolution, independent of experiment assignments and active runtime state.
-       *
-       * @returns The resolved feature flags, keyed by flag name.
-       */
-      resolve: async (params) => connection.sendRequest("featureFlags.resolve", params)
-    },
-    /** @experimental */
-    repo: {
-      /** @experimental */
-      settings: {
-        /**
-         * Reads one repository settings file without settings normalization or layering. The existing JSONC parser accepts comments and trailing commas and applies its prototype-safety rules. Missing or blank files return an empty valid config. Invalid files return an empty config with invalid=true; other read failures reject.
-         *
-         * @param params Which repository settings file to read.
-         *
-         * @returns Parsed repository settings without normalization or layering.
-         */
-        readRaw: async (params) => connection.sendRequest("repo.settings.readRaw", params),
-        /**
-         * Writes or removes one allowed top-level repository setting through the existing validator and file lock. Preserves unrelated stored keys. Invalid keys, values, existing documents, and I/O errors reject without replacing the file. Deletion requires delete=true; otherwise value must be present.
-         *
-         * @param params One key to write or remove in a repository settings file.
-         */
-        writeKey: async (params) => connection.sendRequest("repo.settings.writeKey", params),
-        /**
-         * Replaces the repository-overridable settings in one locked write. Allowed keys present in settings are validated and written; allowed keys absent from settings are removed. Other input keys are ignored, and unknown keys already stored in the file remain unchanged. Invalid values or an invalid existing file reject without a partial write.
-         *
-         * @param params The complete set of repository-overridable settings to store.
-         */
-        writeAll: async (params) => connection.sendRequest("repo.settings.writeAll", params)
-      }
-    },
-    /** @experimental */
     gitHubRepository: {
       /**
        * Resolves the GitHub repository that owns a working-tree path by reading the selected git remote configured for it, preferring `origin`. Returns a null `repository` when the path is inside a git working tree but that selected remote does not resolve to a GitHub host. Fails when the path is not inside a git working tree at all, so a caller can tell 'not a repository' apart from 'a repository with no GitHub remote'.