[FEATURE] Settings schema validation failures should result in more fault-tolerant behavior

Status Open
Maintainer reply None cached
Activity 0 comments · opened Aug 21, 2026

Preflight Checklist

  • [x] I have searched existing requests and this feature hasn't been requested yet
  • [x] This is a single feature request (not multiple features)

Problem Statement

Currently, setting an invalid value for a member of the permissions object (at least via Server-Managed Settings) results in Claude Code discarding the entire permissions object. For example this managed configuration:

{
  "permissions": {
    "defaultMode": "foo", // invalid
    "disableBypassPermissionsMode": "disable" // valid
  }
}

...results in a ~/.claude/remote-settings.json of:

{
}

The Claude Code user sees this message:

  Settings Warning

  remote managed settings
  └ permissions: Failed schema validation. This field was ignored.

  The values listed above were skipped; the rest of the file is in effect.

This is a much more catastrophic failure mode than I'd expect, with security-relevant settings that aren't directly related to the invalid entry being discarded. The doc in https://code.claude.com/docs/en/settings#invalid-entries-in-managed-settings does not IMO make it sufficiently clear that an entire object that contains an invalid field will be discarded; I would expect it to exhibit more targeted self-healing behavior, only discarding the invalid field.

Note that the managed settings editor does check against the schema, and warns against invalid values, but it only does this for the current version of the schema. This means that when a new permissible value is introduced (like permissions.defaultMode: manual was recently), and is introduced to the managed configuration, older versions of Claude Code will exhibit the failure mode above, and the person updating the managed configuration will not be warned about this at the time they update the settings.

Proposed Solution

The behavior I'd expect would be that:

{
  "permissions": {
    "defaultMode": "foo", // invalid
    "disableBypassPermissionsMode": "disable" // valid
  }
}

Writes this to ~/.claude/remote-settings.json instead of completely removing the "permissions" object:

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

Alternative Solutions

When it comes to backwards-incompatible settings changes that are valid against the latest schema but not the version of the schema in the current Claude Code build, Claude Code could handle this case by:

  • Validating as it currently does
  • If validation error: pull down the current live schema and validate against it

If validation passes against the latest schema, but not the bundled schema, bail and require Claude Code to be updated before any other action can be taken.

Priority

High - Greatly affects ability to have any confidence in integrity of server-managed settings

Feature Category

Configuration and settings

Use Case Example

  1. A Claude Code admin wants to enforce security-relevant settings, including a managed permissions object
  2. They do not want a single typo anywhere in the permissions object (or use of a new permissible configuration value that is not backwards-compatible with older versions of Claude Code) to cause the object to be discarded in its entirety in clients where schema validation fails.

Additional Context

_No response_

View original on GitHub ↗