@iaforged/context-code 1.0.72 → 1.0.74

package/dist/src/services/remoteManagedSettings/index.js

@@ -0,0 +1,534 @@
+/**
+ * Remote Managed Settings Service
+ *
+ * Manages fetching, caching, and validation of remote-managed settings
+ * for enterprise customers. Uses checksum-based validation to minimize
+ * network traffic and provides graceful degradation on failures.
+ *
+ * Eligibility:
+ * - Console users (API key): All eligible
+ * - OAuth users (Claude.ai): Only Enterprise/C4E and Team subscribers are eligible
+ * - API fails open (non-blocking) - if fetch fails, continues without remote settings
+ * - API returns empty settings for users without managed settings
+ */
+import axios from 'axios';
+import { createHash } from 'crypto';
+import { open, unlink } from 'fs/promises';
+import { getOauthConfig, OAUTH_BETA_HEADER } from '../../constants/oauth.js';
+import { checkAndRefreshOAuthTokenIfNeeded, getAnthropicApiKeyWithSource, getClaudeAIOAuthTokens, } from '../../utils/auth.js';
+import { registerCleanup } from '../../utils/cleanupRegistry.js';
+import { logForDebugging } from '../../utils/debug.js';
+import { classifyAxiosError, getErrnoCode } from '../../utils/errors.js';
+import { settingsChangeDetector } from '../../utils/settings/changeDetector.js';
+import { SettingsSchema, } from '../../utils/settings/types.js';
+import { sleep } from '../../utils/sleep.js';
+import { jsonStringify } from '../../utils/slowOperations.js';
+import { getClaudeCodeUserAgent } from '../../utils/userAgent.js';
+import { getRetryDelay } from '../api/withRetry.js';
+import { checkManagedSettingsSecurity, handleSecurityCheckResult, } from './securityCheck.js';
+import { isRemoteManagedSettingsEligible, resetSyncCache } from './syncCache.js';
+import { getRemoteManagedSettingsSyncFromCache, getSettingsPath, setSessionCache, } from './syncCacheState.js';
+import { RemoteManagedSettingsResponseSchema, } from './types.js';
+// Constants
+const SETTINGS_TIMEOUT_MS = 10000; // 10 seconds for settings fetch
+const DEFAULT_MAX_RETRIES = 5;
+const POLLING_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+// Background polling state
+let pollingIntervalId = null;
+// Promise that resolves when initial remote settings loading completes
+// This allows other systems to wait for remote settings before initializing
+let loadingCompletePromise = null;
+let loadingCompleteResolve = null;
+// Timeout for the loading promise to prevent deadlocks if loadRemoteManagedSettings() is never called
+// (e.g., in Agent SDK tests that don't go through main.tsx)
+const LOADING_PROMISE_TIMEOUT_MS = 30000; // 30 seconds
+/**
+ * Initialize the loading promise for remote managed settings
+ * This should be called early (e.g., in init.ts) to allow other systems
+ * to await remote settings loading even if loadRemoteManagedSettings()
+ * hasn't been called yet.
+ *
+ * Only creates the promise if the user is eligible for remote settings.
+ * Includes a timeout to prevent deadlocks if loadRemoteManagedSettings() is never called.
+ */
+export function initializeRemoteManagedSettingsLoadingPromise() {
+    if (loadingCompletePromise) {
+        return;
+    }
+    if (isRemoteManagedSettingsEligible()) {
+        loadingCompletePromise = new Promise(resolve => {
+            loadingCompleteResolve = resolve;
+            // Set a timeout to resolve the promise even if loadRemoteManagedSettings() is never called
+            // This prevents deadlocks in Agent SDK tests and other non-CLI contexts
+            setTimeout(() => {
+                if (loadingCompleteResolve) {
+                    logForDebugging('Remote settings: Loading promise timed out, resolving anyway');
+                    loadingCompleteResolve();
+                    loadingCompleteResolve = null;
+                }
+            }, LOADING_PROMISE_TIMEOUT_MS);
+        });
+    }
+}
+/**
+ * Get the remote settings API endpoint
+ * Uses the OAuth config base API URL
+ */
+function getRemoteManagedSettingsEndpoint() {
+    return `${getOauthConfig().BASE_API_URL}/api/claude_code/settings`;
+}
+/**
+ * Recursively sort all keys in an object to match Python's json.dumps(sort_keys=True)
+ */
+function sortKeysDeep(obj) {
+    if (Array.isArray(obj)) {
+        return obj.map(sortKeysDeep);
+    }
+    if (obj !== null && typeof obj === 'object') {
+        const sorted = {};
+        for (const key of Object.keys(obj).sort()) {
+            sorted[key] = sortKeysDeep(obj[key]);
+        }
+        return sorted;
+    }
+    return obj;
+}
+/**
+ * Compute checksum from settings content for HTTP caching
+ * Must match server's Python: json.dumps(settings, sort_keys=True, separators=(",", ":"))
+ * Exported for testing to verify compatibility with server-side implementation
+ */
+export function computeChecksumFromSettings(settings) {
+    const sorted = sortKeysDeep(settings);
+    // No spaces after separators to match Python's separators=(",", ":")
+    const normalized = jsonStringify(sorted);
+    const hash = createHash('sha256').update(normalized).digest('hex');
+    return `sha256:${hash}`;
+}
+/**
+ * Check if the current user is eligible for remote managed settings
+ * This is the public API for other systems to check eligibility
+ * Used to determine if they should wait for remote settings to load
+ */
+export function isEligibleForRemoteManagedSettings() {
+    return isRemoteManagedSettingsEligible();
+}
+/**
+ * Wait for the initial remote settings loading to complete
+ * Returns immediately if:
+ * - User is not eligible for remote settings
+ * - Loading has already completed
+ * - Loading was never started
+ */
+export async function waitForRemoteManagedSettingsToLoad() {
+    if (loadingCompletePromise) {
+        await loadingCompletePromise;
+    }
+}
+/**
+ * Get auth headers for remote settings without calling getSettings()
+ * This avoids circular dependencies during settings loading
+ * Supports both API key and OAuth authentication
+ */
+function getRemoteSettingsAuthHeaders() {
+    // Try API key first (for Console users)
+    // Skip apiKeyHelper to avoid circular dependency with getSettings()
+    // Wrap in try-catch because getAnthropicApiKeyWithSource throws in CI/test environments
+    try {
+        const { key: apiKey } = getAnthropicApiKeyWithSource({
+            skipRetrievingKeyFromApiKeyHelper: true,
+        });
+        if (apiKey) {
+            return {
+                headers: {
+                    'x-api-key': apiKey,
+                },
+            };
+        }
+    }
+    catch {
+        // No API key available - continue to check OAuth
+    }
+    // Fall back to OAuth tokens (for Claude.ai users)
+    const oauthTokens = getClaudeAIOAuthTokens();
+    if (oauthTokens?.accessToken) {
+        return {
+            headers: {
+                Authorization: `Bearer ${oauthTokens.accessToken}`,
+                'anthropic-beta': OAUTH_BETA_HEADER,
+            },
+        };
+    }
+    return {
+        headers: {},
+        error: 'No authentication available',
+    };
+}
+/**
+ * Fetch remote settings with retry logic and exponential backoff
+ * Uses existing codebase retry utilities for consistency
+ */
+async function fetchWithRetry(cachedChecksum) {
+    let lastResult = null;
+    for (let attempt = 1; attempt <= DEFAULT_MAX_RETRIES + 1; attempt++) {
+        lastResult = await fetchRemoteManagedSettings(cachedChecksum);
+        // Return immediately on success
+        if (lastResult.success) {
+            return lastResult;
+        }
+        // Don't retry if the error is not retryable (e.g., auth errors)
+        if (lastResult.skipRetry) {
+            return lastResult;
+        }
+        // If we've exhausted retries, return the last error
+        if (attempt > DEFAULT_MAX_RETRIES) {
+            return lastResult;
+        }
+        // Calculate delay and wait before next retry
+        const delayMs = getRetryDelay(attempt);
+        logForDebugging(`Remote settings: Retry ${attempt}/${DEFAULT_MAX_RETRIES} after ${delayMs}ms`);
+        await sleep(delayMs);
+    }
+    // Should never reach here, but TypeScript needs it
+    return lastResult;
+}
+/**
+ * Fetch the full remote settings (single attempt, no retries)
+ * Optionally pass a cached checksum for ETag-based caching
+ */
+async function fetchRemoteManagedSettings(cachedChecksum) {
+    try {
+        // Ensure OAuth token is fresh before fetching settings
+        // This prevents 401 errors from stale cached tokens
+        await checkAndRefreshOAuthTokenIfNeeded();
+        // Use local auth header getter to avoid circular dependency with getSettings()
+        const authHeaders = getRemoteSettingsAuthHeaders();
+        if (authHeaders.error) {
+            // Auth errors should not be retried - return a special flag to skip retries
+            return {
+                success: false,
+                error: `Authentication required for remote settings`,
+                skipRetry: true,
+            };
+        }
+        const endpoint = getRemoteManagedSettingsEndpoint();
+        const headers = {
+            ...authHeaders.headers,
+            'User-Agent': getClaudeCodeUserAgent(),
+        };
+        // Add If-None-Match header for ETag-based caching
+        if (cachedChecksum) {
+            headers['If-None-Match'] = `"${cachedChecksum}"`;
+        }
+        const response = await axios.get(endpoint, {
+            headers,
+            timeout: SETTINGS_TIMEOUT_MS,
+            // Allow 204, 304, and 404 responses without treating them as errors.
+            // 204/404 are returned when no settings exist for the user or the feature flag is off.
+            validateStatus: status => status === 200 || status === 204 || status === 304 || status === 404,
+        });
+        // Handle 304 Not Modified - cached version is still valid
+        if (response.status === 304) {
+            logForDebugging('Remote settings: Using cached settings (304)');
+            return {
+                success: true,
+                settings: null, // Signal that cache is valid
+                checksum: cachedChecksum,
+            };
+        }
+        // Handle 204 No Content / 404 Not Found - no settings exist or feature flag is off.
+        // Return empty object (not null) so callers don't fall back to cached settings.
+        if (response.status === 204 || response.status === 404) {
+            logForDebugging(`Remote settings: No settings found (${response.status})`);
+            return {
+                success: true,
+                settings: {},
+                checksum: undefined,
+            };
+        }
+        const parsed = RemoteManagedSettingsResponseSchema().safeParse(response.data);
+        if (!parsed.success) {
+            logForDebugging(`Remote settings: Invalid response format - ${parsed.error.message}`);
+            return {
+                success: false,
+                error: 'Invalid remote settings format',
+            };
+        }
+        // Full validation of settings structure
+        const settingsValidation = SettingsSchema().safeParse(parsed.data.settings);
+        if (!settingsValidation.success) {
+            logForDebugging(`Remote settings: Settings validation failed - ${settingsValidation.error.message}`);
+            return {
+                success: false,
+                error: 'Invalid settings structure',
+            };
+        }
+        logForDebugging('Remote settings: Fetched successfully');
+        return {
+            success: true,
+            settings: settingsValidation.data,
+            checksum: parsed.data.checksum,
+        };
+    }
+    catch (error) {
+        const { kind, status, message } = classifyAxiosError(error);
+        if (status === 404) {
+            // 404 means no remote settings configured
+            return { success: true, settings: {}, checksum: '' };
+        }
+        switch (kind) {
+            case 'auth':
+                // Auth errors (401, 403) should not be retried - the API key doesn't have access
+                return {
+                    success: false,
+                    error: 'Not authorized for remote settings',
+                    skipRetry: true,
+                };
+            case 'timeout':
+                return { success: false, error: 'Remote settings request timeout' };
+            case 'network':
+                return { success: false, error: 'Cannot connect to server' };
+            default:
+                return { success: false, error: message };
+        }
+    }
+}
+/**
+ * Save remote settings to file
+ * Stores raw settings JSON (checksum is computed on-demand when needed)
+ */
+async function saveSettings(settings) {
+    try {
+        const path = getSettingsPath();
+        const handle = await open(path, 'w', 0o600);
+        try {
+            await handle.writeFile(jsonStringify(settings, null, 2), {
+                encoding: 'utf-8',
+            });
+            await handle.datasync();
+        }
+        finally {
+            await handle.close();
+        }
+        logForDebugging(`Remote settings: Saved to ${path}`);
+    }
+    catch (error) {
+        logForDebugging(`Remote settings: Failed to save - ${error instanceof Error ? error.message : 'unknown error'}`);
+        // Ignore save errors - we'll refetch on next startup
+    }
+}
+/**
+ * Clear all remote settings (session, persistent, and stop polling)
+ */
+export async function clearRemoteManagedSettingsCache() {
+    // Stop background polling
+    stopBackgroundPolling();
+    // Clear session cache
+    resetSyncCache();
+    // Clear loading promise state
+    loadingCompletePromise = null;
+    loadingCompleteResolve = null;
+    try {
+        const path = getSettingsPath();
+        await unlink(path);
+    }
+    catch {
+        // Ignore errors when clearing file (ENOENT is expected)
+    }
+}
+/**
+ * Fetch and load remote settings with file caching
+ * Internal function that handles the full load/fetch logic
+ * Fails open - returns null if fetch fails and no cache exists
+ */
+async function fetchAndLoadRemoteManagedSettings() {
+    if (!isRemoteManagedSettingsEligible()) {
+        return null;
+    }
+    // Load cached settings from file
+    const cachedSettings = getRemoteManagedSettingsSyncFromCache();
+    // Compute checksum locally from cached settings for HTTP caching validation
+    const cachedChecksum = cachedSettings
+        ? computeChecksumFromSettings(cachedSettings)
+        : undefined;
+    try {
+        // Fetch settings from API with retry logic
+        const result = await fetchWithRetry(cachedChecksum);
+        if (!result.success) {
+            // On fetch failure, use stale file if available (graceful degradation)
+            if (cachedSettings) {
+                logForDebugging('Remote settings: Using stale cache after fetch failure');
+                setSessionCache(cachedSettings);
+                return cachedSettings;
+            }
+            // No cache available - fail open, continue without remote settings
+            return null;
+        }
+        // Handle 304 Not Modified - cached settings are still valid
+        if (result.settings === null && cachedSettings) {
+            logForDebugging('Remote settings: Cache still valid (304 Not Modified)');
+            setSessionCache(cachedSettings);
+            return cachedSettings;
+        }
+        // Save new settings to file (only if non-empty)
+        const newSettings = result.settings || {};
+        const hasContent = Object.keys(newSettings).length > 0;
+        if (hasContent) {
+            // Check for dangerous settings changes before applying
+            const securityResult = await checkManagedSettingsSecurity(cachedSettings, newSettings);
+            if (!handleSecurityCheckResult(securityResult)) {
+                // User rejected - don't apply settings, return cached or null
+                logForDebugging('Remote settings: User rejected new settings, using cached settings');
+                return cachedSettings;
+            }
+            setSessionCache(newSettings);
+            await saveSettings(newSettings);
+            logForDebugging('Remote settings: Applied new settings successfully');
+            return newSettings;
+        }
+        // Empty settings (404 response) - delete cached file if it exists
+        // This ensures stale settings don't persist when a user's remote settings are removed
+        setSessionCache(newSettings);
+        try {
+            const path = getSettingsPath();
+            await unlink(path);
+            logForDebugging('Remote settings: Deleted cached file (404 response)');
+        }
+        catch (e) {
+            const code = getErrnoCode(e);
+            if (code !== 'ENOENT') {
+                logForDebugging(`Remote settings: Failed to delete cached file - ${e instanceof Error ? e.message : 'unknown error'}`);
+            }
+        }
+        return newSettings;
+    }
+    catch {
+        // On any error, use stale file if available (graceful degradation)
+        if (cachedSettings) {
+            logForDebugging('Remote settings: Using stale cache after error');
+            setSessionCache(cachedSettings);
+            return cachedSettings;
+        }
+        // No cache available - fail open, continue without remote settings
+        return null;
+    }
+}
+/**
+ * Load remote settings during CLI initialization
+ * Fails open - if fetch fails, continues without remote settings
+ * Also starts background polling to pick up settings changes mid-session
+ *
+ * This function sets up a promise that other systems can await via
+ * waitForRemoteManagedSettingsToLoad() to ensure they don't initialize
+ * until remote settings have been fetched.
+ */
+export async function loadRemoteManagedSettings() {
+    // Set up the promise for other systems to wait on
+    // Only if the user is eligible for remote settings AND promise not already set up
+    // (initializeRemoteManagedSettingsLoadingPromise may have been called earlier)
+    if (isRemoteManagedSettingsEligible() && !loadingCompletePromise) {
+        loadingCompletePromise = new Promise(resolve => {
+            loadingCompleteResolve = resolve;
+        });
+    }
+    // Cache-first: if we have cached settings on disk, apply them and unblock
+    // waiters immediately. The fetch still runs below; notifyChange fires once,
+    // after the fetch, as before. Saves the ~77ms fetch-wait on print-mode startup.
+    // getRemoteManagedSettingsSyncFromCache has the eligibility guard and populates
+    // the session cache internally — no need to call setSessionCache here.
+    if (getRemoteManagedSettingsSyncFromCache() && loadingCompleteResolve) {
+        loadingCompleteResolve();
+        loadingCompleteResolve = null;
+    }
+    try {
+        const settings = await fetchAndLoadRemoteManagedSettings();
+        // Start background polling to pick up settings changes mid-session
+        if (isRemoteManagedSettingsEligible()) {
+            startBackgroundPolling();
+        }
+        // Trigger hot-reload if settings were loaded (new or from cache).
+        // notifyChange resets the settings cache internally before iterating
+        // listeners — env vars, telemetry, and permissions update on next read.
+        if (settings !== null) {
+            settingsChangeDetector.notifyChange('policySettings');
+        }
+    }
+    finally {
+        // Always resolve the promise, even if fetch failed (fail-open)
+        if (loadingCompleteResolve) {
+            loadingCompleteResolve();
+            loadingCompleteResolve = null;
+        }
+    }
+}
+/**
+ * Refresh remote settings asynchronously (for auth state changes)
+ * This is used when login/logout occurs
+ * Fails open - if fetch fails, continues without remote settings
+ */
+export async function refreshRemoteManagedSettings() {
+    // Clear caches first
+    await clearRemoteManagedSettingsCache();
+    // If not enabled, notify that policy settings changed (to empty)
+    if (!isRemoteManagedSettingsEligible()) {
+        settingsChangeDetector.notifyChange('policySettings');
+        return;
+    }
+    // Try to load new settings (fails open if fetch fails)
+    await fetchAndLoadRemoteManagedSettings();
+    logForDebugging('Remote settings: Refreshed after auth change');
+    // Notify listeners. notifyChange resets the settings cache internally;
+    // this triggers hot-reload (AppState update, env var application, etc.)
+    settingsChangeDetector.notifyChange('policySettings');
+}
+/**
+ * Background polling callback - fetches settings and triggers hot-reload if changed
+ */
+async function pollRemoteSettings() {
+    if (!isRemoteManagedSettingsEligible()) {
+        return;
+    }
+    // Get current cached settings for comparison
+    const prevCache = getRemoteManagedSettingsSyncFromCache();
+    const previousSettings = prevCache ? jsonStringify(prevCache) : null;
+    try {
+        await fetchAndLoadRemoteManagedSettings();
+        // Check if settings actually changed
+        const newCache = getRemoteManagedSettingsSyncFromCache();
+        const newSettings = newCache ? jsonStringify(newCache) : null;
+        if (newSettings !== previousSettings) {
+            logForDebugging('Remote settings: Changed during background poll');
+            settingsChangeDetector.notifyChange('policySettings');
+        }
+    }
+    catch {
+        // Don't fail closed for background polling - just continue
+    }
+}
+/**
+ * Start background polling for remote settings
+ * Polls every hour to pick up settings changes mid-session
+ */
+export function startBackgroundPolling() {
+    if (pollingIntervalId !== null) {
+        return;
+    }
+    if (!isRemoteManagedSettingsEligible()) {
+        return;
+    }
+    pollingIntervalId = setInterval(() => {
+        void pollRemoteSettings();
+    }, POLLING_INTERVAL_MS);
+    pollingIntervalId.unref();
+    // Register cleanup to stop polling on shutdown
+    registerCleanup(async () => stopBackgroundPolling());
+}
+/**
+ * Stop background polling for remote settings
+ */
+export function stopBackgroundPolling() {
+    if (pollingIntervalId !== null) {
+        clearInterval(pollingIntervalId);
+        pollingIntervalId = null;
+    }
+}

package/dist/src/services/remoteManagedSettings/securityCheck.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { getIsInteractive } from '../../bootstrap/state.js';
+import { ManagedSettingsSecurityDialog } from '../../components/ManagedSettingsSecurityDialog/ManagedSettingsSecurityDialog.js';
+import { extractDangerousSettings, hasDangerousSettings, hasDangerousSettingsChanged } from '../../components/ManagedSettingsSecurityDialog/utils.js';
+import { render } from '../../ink.js';
+import { KeybindingSetup } from '../../keybindings/KeybindingProviderSetup.js';
+import { AppStateProvider } from '../../state/AppState.js';
+import { gracefulShutdownSync } from '../../utils/gracefulShutdown.js';
+import { getBaseRenderOptions } from '../../utils/renderOptions.js';
+import { logEvent } from '../analytics/index.js';
+/**
+ * Check if new remote managed settings contain dangerous settings that require user approval.
+ * Shows a blocking dialog if dangerous settings have changed or been added.
+ *
+ * @param cachedSettings The current cached settings (may be null for first run)
+ * @param newSettings The new settings fetched from the API
+ * @returns 'approved' if user accepts, 'rejected' if user declines, 'no_check_needed' if no dangerous changes
+ */
+export async function checkManagedSettingsSecurity(cachedSettings, newSettings) {
+    // If new settings don't have dangerous settings, no check needed
+    if (!newSettings || !hasDangerousSettings(extractDangerousSettings(newSettings))) {
+        return 'no_check_needed';
+    }
+    // If dangerous settings haven't changed, no check needed
+    if (!hasDangerousSettingsChanged(cachedSettings, newSettings)) {
+        return 'no_check_needed';
+    }
+    // Skip dialog in non-interactive mode (consistent with trust dialog behavior)
+    if (!getIsInteractive()) {
+        return 'no_check_needed';
+    }
+    // Log that dialog is being shown
+    logEvent('tengu_managed_settings_security_dialog_shown', {});
+    // Show blocking dialog
+    return new Promise(resolve => {
+        void (async () => {
+            const { unmount } = await render(_jsx(AppStateProvider, { children: _jsx(KeybindingSetup, { children: _jsx(ManagedSettingsSecurityDialog, { settings: newSettings, onAccept: () => {
+                            logEvent('tengu_managed_settings_security_dialog_accepted', {});
+                            unmount();
+                            void resolve('approved');
+                        }, onReject: () => {
+                            logEvent('tengu_managed_settings_security_dialog_rejected', {});
+                            unmount();
+                            void resolve('rejected');
+                        } }) }) }), getBaseRenderOptions(false));
+        })();
+    });
+}
+/**
+ * Handle the security check result by exiting if rejected
+ * Returns true if we should continue, false if we should stop
+ */
+export function handleSecurityCheckResult(result) {
+    if (result === 'rejected') {
+        gracefulShutdownSync(1);
+        return false;
+    }
+    return true;
+}

package/dist/src/services/remoteManagedSettings/syncCache.js

@@ -0,0 +1,90 @@
+/**
+ * Eligibility check for remote managed settings.
+ *
+ * The cache state itself lives in syncCacheState.ts (a leaf, no auth import).
+ * This file keeps isRemoteManagedSettingsEligible — the one function that
+ * needs auth.ts — plus resetSyncCache wrapped to clear the local eligibility
+ * mirror alongside the leaf's state.
+ */
+import { CLAUDE_AI_INFERENCE_SCOPE } from '../../constants/oauth.js';
+import { getAnthropicApiKeyWithSource, getClaudeAIOAuthTokens, } from '../../utils/auth.js';
+import { getAPIProvider, isFirstPartyAnthropicBaseUrl, } from '../../utils/model/providers.js';
+import { resetSyncCache as resetLeafCache, setEligibility, } from './syncCacheState.js';
+let cached;
+export function resetSyncCache() {
+    cached = undefined;
+    resetLeafCache();
+}
+/**
+ * Check if the current user is eligible for remote managed settings
+ *
+ * Eligibility:
+ * - Console users (API key): All eligible (must have actual key, not just apiKeyHelper)
+ * - OAuth users with known subscriptionType: Only Enterprise/C4E and Team
+ * - OAuth users with subscriptionType === null (externally-injected tokens via
+ *   CLAUDE_CODE_OAUTH_TOKEN / FD, or keychain tokens missing metadata): Eligible —
+ *   the API returns empty settings for ineligible orgs, so the cost of a false
+ *   positive is one round-trip
+ *
+ * This is a pre-check to determine if we should query the API.
+ * The API will return empty settings for users without managed settings.
+ *
+ * IMPORTANT: This function must NOT call getSettings() or any function that calls
+ * getSettings() to avoid circular dependencies during settings loading.
+ */
+export function isRemoteManagedSettingsEligible() {
+    if (cached !== undefined)
+        return cached;
+    // 3p provider users should not hit the settings endpoint
+    if (getAPIProvider() !== 'firstParty') {
+        return (cached = setEligibility(false));
+    }
+    // Custom base URL users should not hit the settings endpoint
+    if (!isFirstPartyAnthropicBaseUrl()) {
+        return (cached = setEligibility(false));
+    }
+    // Cowork runs in a VM with its own permission model; server-managed settings
+    // (designed for CLI/CCD) don't apply there, and per-surface settings don't
+    // exist yet. MDM/file-based managed settings still apply via settings.ts —
+    // those require physical deployment and a different IT intent.
+    if (process.env.CLAUDE_CODE_ENTRYPOINT === 'local-agent') {
+        return (cached = setEligibility(false));
+    }
+    // Check OAuth first: most Claude.ai users have no API key in the keychain.
+    // The API key check spawns `security find-generic-password` (~20-50ms) which
+    // returns null for OAuth-only users. Checking OAuth first short-circuits
+    // that subprocess for the common case.
+    const tokens = getClaudeAIOAuthTokens();
+    // Externally-injected tokens (CCD via CLAUDE_CODE_OAUTH_TOKEN, CCR via
+    // CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR, Agent SDK, CI) carry no
+    // subscriptionType metadata — getClaudeAIOAuthTokens() constructs them with
+    // subscriptionType: null. The token itself is valid; let the API decide.
+    // fetchRemoteManagedSettings handles 204/404 gracefully (returns {}), and
+    // settings.ts falls through to MDM/file when remote is empty, so ineligible
+    // orgs pay one round-trip and nothing else changes.
+    if (tokens?.accessToken && tokens.subscriptionType === null) {
+        return (cached = setEligibility(true));
+    }
+    if (tokens?.accessToken &&
+        tokens.scopes?.includes(CLAUDE_AI_INFERENCE_SCOPE) &&
+        (tokens.subscriptionType === 'enterprise' ||
+            tokens.subscriptionType === 'team')) {
+        return (cached = setEligibility(true));
+    }
+    // Console users (API key) are eligible if we can get the actual key
+    // Skip apiKeyHelper to avoid circular dependency with getSettings()
+    // Wrap in try-catch because getAnthropicApiKeyWithSource throws in CI/test environments
+    // when no API key is available
+    try {
+        const { key: apiKey } = getAnthropicApiKeyWithSource({
+            skipRetrievingKeyFromApiKeyHelper: true,
+        });
+        if (apiKey) {
+            return (cached = setEligibility(true));
+        }
+    }
+    catch {
+        // No API key available (e.g., CI/test environment)
+    }
+    return (cached = setEligibility(false));
+}