claude-code - 💡(How to fix) Fix fix(managed-settings): spinnerVerbs without mode key silently breaks all managed settings

:robot: This was written by an AI agent on behalf of @paolomainardi.

Bug description

When spinnerVerbs is included in server-managed settings (via claude.ai Admin Console) without the mode key, the client silently rejects the entire managed settings config. No error is shown — the settings simply don't load, and /status shows only "User settings" instead of "Enterprise managed settings (remote)".

Combined with forceRemoteSettingsRefresh: true, this makes Claude Code refuse to start entirely with:

Your organization requires remote managed settings to load, but they could not be loaded.

Steps to reproduce

1. Deploy this to the claude.ai Admin Console managed settings:

{
  "forceRemoteSettingsRefresh": true,
  "spinnerVerbs": {
    "verbs": ["CustomVerb1", "CustomVerb2"]
  }
}

1. Restart Claude Code
2. Run /status — managed settings are missing

Expected behavior

Either:

• The client should accept spinnerVerbs without mode and default to "append" (or "replace")
• Or the JSON schema should list mode as required ("required": ["verbs", "mode"] instead of "required": ["verbs"])

Workaround

Adding "mode": "append" (or "replace") makes it work:

{
  "spinnerVerbs": {
    "mode": "append",
    "verbs": ["CustomVerb1", "CustomVerb2"]
  }
}

Root cause

The schema at schemastore.org/claude-code-settings.json defines mode as optional (required: ["verbs"]), but the client's managed settings parser requires it. The schema and client validation disagree.

Additional context

• Also tested with the plain array form "spinnerVerbs": ["Verb1", "Verb2"] — also breaks managed settings
• spinnerTipsOverride works fine in managed settings (no issues)
• env, companyAnnouncements, attribution, and all other keys work fine
• The failure is silent — no client-side error, the config is just dropped
• Version: 2.1.142
• Plan: Team