Support custom label/description for managed-settings.json keys shown in the "Managed settings require approval" dialog

Status Open
Maintainer reply None cached
Activity 0 comments · opened Jul 24, 2026

Problem

When an org deploys managed-settings.json (via MDM, file-based deploy, or the admin console), any new/changed key under env (and similarly for other policy-controlled fields) triggers a "Managed settings require approval" prompt on next launch:

Managed settings require approval

Your organization has configured managed settings that could allow execution of
arbitrary code or interception of your prompts and responses.

Settings requiring approval:
  · EXAMPLE_ENV_VAR

Only accept if you trust your organization's IT administration and expect these
settings to be configured.

> 1. Yes, I trust these settings
  2. No, exit Claude Code

The dialog renders the raw JSON key with no context — e.g. EXAMPLE_ENV_VAR, a setting IT configured for a legitimate internal purpose. Every user in the org sees this cold, with default language calling out "arbitrary code execution" and "interception of your prompts and responses." At org scale, that's a lot of people getting a scary security prompt over a setting they have no context for, and no way for IT to add explanation inline.

I confirmed via binary inspection (strings on bin/claude) that there's currently no label/description mechanism for this at all — no friendlyName/displayName/settingLabel field anywhere tied to policySettings, just the fixed template text plus the raw key.

Why not just rename the key

Not always viable — some managed-settings keys are third-party/standard names (e.g. a vendor SDK env var) that must match exactly to function. Renaming them for readability would break the underlying integration. The gap is in the display layer of the approval dialog, not the config key itself.

Proposed solution

Add an optional description/label field admins can set alongside env (or any other policy-controlled block) in managed-settings.json, rendered in the approval dialog in place of (or alongside) the raw key. E.g.:

{
  "env": {
    "EXAMPLE_ENV_VAR": "some-value"
  },
  "envDescriptions": {
    "EXAMPLE_ENV_VAR": "Configured by IT for [purpose]. Safe to approve — not user-configurable."
  }
}

Fallback: if no description is provided, keep current behavior (show the raw key).

Alternatives considered

  • Company-wide Slack/email heads-up before rollout — helps, but doesn't scale to every new setting change over time, and doesn't reach new hires who see it later without context.
  • companyAnnouncements field — shown separately from the approval dialog itself, not contextually tied to the specific setting the user is being asked to trust.

Impact

Any org deploying managed-settings.json env vars hits this — not specific to any one setting. A generic label/description field would help every admin communicating managed settings to end users.

View original on GitHub ↗