Config Schemas

• Entity ID: ent-20260410-8260003548dd
• Type: concept
• Scope: shared
• Status: active
• Aliases: settings schema, settings.json, configuration, SettingsSchema

Description

The configuration schema system uses Zod v4 to validate all settings.json files across 5 configuration scopes. It defines the structure for user settings, project settings, enterprise policies, permission rules, hooks, MCP server configs, and sandbox settings. Managed settings follow a systemd-style drop-in convention for enterprise customization.

Configuration scopes

5 setting sources with defined precedence (later overrides earlier):

policySettings and flagSettings are always loaded. User/project/local sources can be selectively enabled via --setting-sources user,project,local.

SettingsSchema structure

The unified SettingsSchema (in src/utils/settings/types.ts) covers all configuration:

Authentication

• apiKeyHelper — script path for API key retrieval
• awsCredentialExport, awsAuthRefresh, gcpAuthRefresh — cloud auth scripts
• forceLoginMethod — 'claudeai' or 'console'
• forceLoginOrgUUID

Permissions

• permissions.allow / permissions.deny / permissions.ask — tool permission rules
• permissions.defaultMode — default permission mode
• permissions.disableBypassPermissionsMode — lock out bypass mode
• permissions.additionalDirectories — extra allowed directories

MCP

• enableAllProjectMcpServers, enabledMcpjsonServers, disabledMcpjsonServers
• allowedMcpServers, deniedMcpServers — enterprise allow/deny lists

Hooks

• hooks — HooksSchema: per-event hook arrays with matchers
• disableAllHooks, allowManagedHooksOnly
• allowedHttpHookUrls, httpHookAllowedEnvVars — HTTP hook security

Model and behavior

• model — model override
• availableModels — enterprise model allowlist
• modelOverrides — map from Anthropic model ID to provider-specific ID
• effortLevel — low/medium/high/max
• fastMode, fastModePerSessionOptIn
• alwaysThinkingEnabled, advisorModel
• outputStyle, language

UI and display

• statusLine — { type: 'command', command: string, padding? }
• syntaxHighlightingDisabled
• terminalTitleFromRename
• spinnerTipsEnabled, spinnerVerbs, spinnerTipsOverride
• promptSuggestionEnabled

Enterprise

• allowManagedPermissionRulesOnly, allowManagedMcpServersOnly
• strictPluginOnlyCustomization — boolean or array of categories
• companyAnnouncements — startup announcements

Other

• env — environment variables (record of string -> coerced string)
• attribution — { commit?: string, pr?: string } for git commits/PRs
• cleanupPeriodDays — transcript retention (0 disables)
• respectGitignore — boolean
• sandbox — SandboxSettingsSchema
• worktree — { symlinkDirectories?, sparsePaths? }
• enabledPlugins, pluginConfigs
• feedbackSurveyRate — 0-1 probability

Hook schemas

Hooks are defined in src/schemas/hooks.ts (extracted to break import cycles). Four hook types:

All hooks support: statusMessage, once (run only first time), and if condition (permission rule syntax like "Bash(git *)" to filter when the hook fires).

Validation approach

• Zod v4 for all schema validation with lazySchema() wrapper for deferred evaluation
• .passthrough() on permissions preserves unknown fields (backward compatibility)
• z.coerce for type coercion (env vars converting numbers to strings)
• .catch(undefined) prevents individual field failures from nulling the entire config
• Invalid settings are preserved in the file but not applied (graceful degradation)
• Published to JSON Schema Store: https://json.schemastore.org/claude-code-settings.json

Managed settings

loadManagedFileSettings() follows the systemd/sudoers drop-in convention:

1. Load managed-settings.json from platform-specific managed path
2. Load managed-settings.d/*.json (sorted alphabetically)
3. Merge using lodash-es/mergeWith with settingsMergeCustomizer

Base file provides defaults; drop-in files customize for specific teams or environments.

Trade-offs

1. Single unified schema — all scopes use the same SettingsSchema, making it easy to understand but meaning every scope can potentially set any field (policy enforcement must be separate from validation).
2. Graceful degradation — invalid fields are ignored rather than rejecting the whole file. Good for forward compatibility but can mask configuration errors silently.
3. Drop-in convention — flexible for enterprise deployment but adds precedence complexity beyond the 5-scope hierarchy.
4. lazySchema() wrapper — breaks import cycles but makes the schema harder to inspect statically.

Depends on

• Zod v4 — schema definition and validation
• lodash-es/mergeWith — settings merge

Key claims

• 5 configuration scopes with defined precedence (user < project < local < flag < policy)
• Invalid settings are preserved in file but not applied (graceful degradation)
• Hook schemas support 4 types: bash command, prompt, HTTP, and agent
• Managed settings follow systemd drop-in convention (base file + .d/ directory)

Relations

• used_by entrypoint-system
• used_by mcp-server-discovery
• used_by permission-pipeline
• used_by hooks-system

Sources

src-20260409-a5fc157bc756, source code analysis of src/schemas/hooks.ts, src/utils/settings/types.ts, src/utils/settings/constants.ts