ai-coding-agents-settings-policy

AI Coding Agents Settings Policy

Use this skill to design or review the settings and policy layer of a coding-agent runtime: settings sources, precedence, managed policy, validation, safe environment handling, and runtime application of settings changes.

This skill owns configuration and policy architecture for coding-agent runtimes. For project memory in AGENTS.md or CLAUDE.md, use ../agents-memory/SKILL.md.

ASCII Flow

settings sources
  defaults + managed policy + user + project + local + flags + env
       |
       v
precedence merge
  deterministic order + source provenance + plugin-only restrictions
       |
       v
validation
  schema + forbidden keys + unsafe env + unknown options
       |
       v
runtime application
  provider policy + tools + permissions + plugins + UI + cache invalidation
       |
       v
audit record
  effective settings without secrets

Quick Reference

When To Use

• Design a settings system for a coding-agent CLI or runtime
• Separate user, project, local, flag, and managed policy sources
• Review how managed settings should override user configuration
• Define which environment variables or customization surfaces are safe to accept
• Apply runtime settings changes without restarting the whole process

Use Other Skills

Default Workflow

1. Define source layers. Separate user, shared project, local gitignored, CLI-flag, and managed-policy sources.
2. Freeze precedence. Document one merge order and keep it consistent across disk reads, UI display, and runtime application.
3. Make managed policy authoritative. Policy layers should override user-controlled settings and bypass local customization where required.
4. Validate at the boundary. Parse, coerce, and validate settings before they mutate runtime state.
5. Fail soft on invalid fragments. Preserve the file on disk, but ignore invalid pieces when safe to do so.
6. Protect dangerous env and customization surfaces. Whitelist what can be applied automatically; strip or gate anything that could redirect providers or execute shell code.
7. Separate cache tiers. Keep merged settings, per-source reads, and parsed-file caches distinct so invalidation is targeted and explainable.
8. Apply changes through one runtime path. Re-read settings, snapshot hooks or dependent callbacks, reload dependent subsystems, and update app state through a single function.
9. Test hostile cases. Cover malformed JSON, invalid permission rules, drop-in conflicts, managed overrides, and live settings-change notifications.

Host Rules

• Keep source precedence explicit and stable.
• Always include managed-policy and CLI-flag sources even when users restrict editable sources.
• Distinguish editable sources from read-only policy and flag overlays.
• Prefer schema validation plus targeted filtering over all-or-nothing rejection when individual rules are bad.
• Keep dangerous environment settings and shell-like helper values behind explicit trust gates.
• Apply settings changes by recomputing derived runtime state, not by mutating scattered subsystems in place.
• Treat plugin-only customization policy as source-aware. Not every settings source is equally trusted to enable plugin surfaces.
• Sanitize persisted permission rules after reload before they become active state.

Build Order

1. Define settings sources and immutable precedence.
2. Define the canonical merged schema and validation path.
3. Add managed-policy and CLI-flag overlays.
4. Add dangerous-surface filtering for env and helper values.
5. Split merged, per-source, and parsed-file caches.
6. Implement one runtime re-application path.
7. Add reload sequencing for caches, hook snapshots, plugins, and UI state.

Core Invariants

• Precedence must be identical in disk reads, UI views, and runtime application.
• Managed policy overrides user settings even when users can edit local files.
• Invalid fragments should not corrupt valid configuration.
• Dangerous customization surfaces require explicit trust rules.
• Runtime state should be recomputed from merged settings, not patched piecemeal.
• Cache invalidation must respect which layer changed: parsed file, source layer, or merged result.

Failure Modes

• Different parts of the runtime seeing different precedence orders.
• Managed drop-ins loading after user config but before flags in one code path and not another.
• Invalid permission rules poisoning the whole settings load.
• Reload side effects applying out of order across cache resets, hooks, and app state.
• Plugin-only restrictions differing by source because trust class was lost during merge.
• Safe-looking env overrides redirecting providers or shell helpers unexpectedly.

Minimal Viable Version

• One source-precedence table.
• One merged schema and validation pass.
• One managed-policy overlay.
• One filter for dangerous env or helper surfaces.
• One source-aware trust rule for plugin-only or privileged customization.
• One central function that reapplies derived runtime state after settings change.

What Strong Implementations Add

• Read-only versus editable source distinctions in UI and runtime.
• Plugin-only customization restrictions.
• Fine-grained invalid-fragment filtering instead of all-or-nothing rejection.
• Distinct caches for parsed files, per-source layers, and merged effective settings.
• Explicit sequencing for hook snapshots, cache resets, and state reapplication.
• Auditability explaining which source won for any effective value.

Known Traps

• Letting different subsystems invent their own precedence rules and ending up with settings that disagree between runtime, UI, and policy enforcement.
• Treating environment overrides as harmless configuration even when they bypass managed policy or expand the trust boundary.
• Reapplying one changed field in place instead of rebuilding the derived state that depends on source layering, hooks, and permissions.
• Using one shared cache for parse results, merged settings, and source-specific state, which makes invalidation unreliable.
• Hiding policy wins from the effective-settings view and making debugging impossible for operators.

Common Anti-Patterns

• Letting every subsystem define its own precedence order.
• Treating flags, policy, and user files as one merge layer.
• Reapplying only the changed field instead of rebuilding derived state.
• Using one undifferentiated settings cache for parse results, source layers, and merged output.
• Accepting arbitrary env overrides because they are “just config.”
• Hiding managed-policy wins from the effective settings view.

Claude Code: Precedence, Managed Policy, and Cleanup (2026, web-verified)

Verified against code.claude.com/docs/en/settings and code.claude.com/docs/en/hooks on 2026-07-11. The Claude Code precedence order is the reference implementation for the settings-precedence-table.md model in this skill:

managed (highest, cannot be overridden)
  > CLI flags (session-only)
    > .claude/settings.local.json (gitignored; allow rules apply without a trust dialog)
      > .claude/settings.json (project, checked in; requires the trust dialog)
        > ~/.claude/settings.json (user, lowest)

The most common audit mistake is inverting the last three: local is the most specific and highest-precedence editable file, not the least. A clean ~/.claude/settings.json changes nothing in a repo that carries a conflicting .claude/settings.local.json.

cleanupPeriodDays (any editable scope; default 30, minimum 1) controls how many days of session files and other application data Claude Code deletes at startup. Setting it to 0 is a validation error, not "disable cleanup." When auditing a fleet for stale-session accumulation or unexpected data loss, check this key before assuming a bug — 30 days is the shipped default and a lower value elsewhere is a deliberate override, not drift.

Managed-settings-only keys

These keys are honored only when set in managed/enterprise policy; the same key in user or project settings is silently ignored. This is the strongest lockdown class — verify this distinction before telling an operator "just set X in your project settings," because for this table that advice is wrong.

Keys that exist in all scopes but are commonly set via managed policy

Do not describe these as "managed-only" — a user or project file can set them too; policy is simply the layer that makes the choice non-negotiable for that user or repo.

A prior version of this skill listed strictPluginOnlyCustomization, policyHelper, and parentSettingsBehavior as managed-policy keys. None of the three could be verified against current docs on re-check (2026-07-11) — they have been removed rather than carried forward as unverified claims. If a runtime you are auditing needs "all customization must come through plugins" or "policy context injected into the system prompt" behavior, treat it as a custom control you are designing, not an existing Claude Code key, until you find it in current docs yourself.

Hook events relevant to settings and policy

Both events follow the standard hook lifecycle alongside PreToolUse, PostToolUse, SessionStart, and SessionEnd, and are available in user, project, and managed-policy hook sources.

OpenAI Codex: Config Home, File Layering, and Approval-Mode TOML Key

Re-verified against learn.chatgpt.com/docs/config-file/config-reference on 2026-07-11. This supersedes an earlier version of this section that was pinned to a May 2026 source snapshot and had drifted on two points — see corrections below.

CODEX_HOME and Config File Location

$CODEX_HOME is the base directory for all Codex user state, defaulting to ~/.codex/ (%USERPROFILE%\.codex\ on Windows). The primary user config file is $CODEX_HOME/config.toml.

Operators can relocate all user state by setting $CODEX_HOME — no config file edits required. Managed/enterprise configuration and CLI flags sit above this in precedence and are not affected by $CODEX_HOME.

Config Layering (named profiles) — corrected

Named profiles are separate files next to config.toml, not a [profiles.NAME] table inside it: $CODEX_HOME/<profile-name>.config.toml, selected at launch with --profile <profile-name>. A prior version of this skill showed [profiles.strict] / [profiles.ci] tables inside one config.toml — that syntax is not current and should not be used as a template.

# $CODEX_HOME/ci.config.toml
approval_policy = "never"

[sandbox_workspace_write]
network_access = false

The active profile is selected via --profile ci, letting one Codex install serve multiple use-case contexts (interactive dev, CI, enterprise review) without one file trying to hold every mode.

Approval-Mode TOML Key — corrected value

# ~/.codex/config.toml
approval_policy = "on-request"  # default; see AskForApproval enum in ai-coding-agents-permissions

Verified valid values (2026-07-11): "untrusted", "on-request", "never", or a granular object (sub-keys for sandbox_approval, rules, mcp_elicitations, request_permissions, skill_approval). "on-failure" still appears but is deprecated. "unless-trusted" is not a valid value — a prior version of this skill used that spelling; if you find it in an older Codex install or a stale example elsewhere, treat it as the pre-rename form of "untrusted" and do not propagate the old spelling into new configs.

Precedence, including project scope

Current documented order (highest first): managed/enterprise configuration > CLI flags > project-scoped .codex/config.toml > profile file (via --profile) > user-level $CODEX_HOME/config.toml. A fixed set of security-critical keys — provider selection, authentication, notification routing, telemetry routing, and the approval/sandbox trio (approval_policy, sandbox_mode, sandbox_workspace_write) — are deliberately ignored if set in project-scoped config, so a compromised or careless repo cannot loosen its own sandbox. Treat "which keys project config is allowed to touch" as a threat-modeling question, not an oversight, when designing an equivalent for another CLI.

Cross-Platform Patterns (Goose)

Goose introduces two settings-layer patterns beyond the standard user/project/flag/managed-policy stack: custom distros as policy-delivery mechanism, and .goosehints-style narrative project hints as a distinct source class.

Custom distros as a read-only policy source

Goose's Custom Distributions (see ai-coding-agents-release-distribution) bake an allowlist, provider pinning, and branding into the binary itself. From the settings layer's perspective, this is a new source class: read-only, above CLI flags in precedence, immutable at runtime.

• Pattern: add distro_policy to the source-precedence table as the highest immutable layer (above managed_policy, which can be updated without a binary change). Effective-settings UI must attribute wins to the distro layer explicitly so operators can explain "why can't I change this."
• Anti-pattern: encoding enterprise restrictions through managed-policy files shipped alongside the open-source binary. Users can rename, move, or delete those files; distro policy cannot be bypassed without swapping the binary.
• Recipe: add a distro source class with a frozen manifest, rendered in --version output and visible in the effective-settings debug view. Managed-policy layers can still narrow further but cannot broaden beyond the distro envelope.

.goosehints — narrative project-hint layer

Goose loads .goosehints as a per-project narrative file (similar to AGENTS.md / CLAUDE.md). This is not structured settings — it is unstructured guidance for the agent about the project. But it is a source layer in the sense that the agent consumes it deterministically at session start.

• Pattern: model project-narrative hints as a distinct source class, separate from typed settings. It has its own trust model (user-editable), its own precedence (always loaded, low priority), and its own invalidation (file-watch triggers re-read).
• Anti-pattern: treating narrative hints as "just settings" and applying schema validation to prose. Or treating them as entirely separate and duplicating source-precedence logic for them.
• Recipe: the settings layer acknowledges project-narrative as a source with explicit lifecycle hooks (read, invalidate, merge into agent context). Concrete formats — AGENTS.md, CLAUDE.md, .goosehints, .cursorrules — are implementations of that source class. The agents-memory skill owns the content side; the settings-policy layer owns the source-loader plumbing.

Navigation

References

• references/settings-source-precedence-and-managed-policy.md — Source layering, managed policy, and customization restrictions
• references/settings-validation-and-safe-runtime-application.md — Validation, safe env handling, and runtime application
• references/settings-precedence-table.md — Concrete precedence table with override examples (managed > CLI flags > local > project > user)
• references/plugin-only-restriction-recipes.md — Trust-class enforcement for plugin-surface activations
• references/deferred-tool-policy-layer.md — How ToolSearch trigger is settings-gated
• references/openai-codex-managed-config-and-requirements.md — OpenAI Codex config layer stack, managed requirements, requirements-only settings, and policy debug surfaces

Data

• data/sources.json — Primary documentation and implementation references for settings and policy guidance

Related Skills

• ../ai-coding-agents-permissions/SKILL.md — Permission modes and rule handling
• ../ai-coding-agents-plugins/SKILL.md — Plugin-only customization and extension policy
• ../agents-memory/SKILL.md — Project instruction files rather than runtime settings

Fact-Checking

• Known bugs, regressions, framework/compiler/runtime footguns, and version-specific crash or workaround guidance must be verified against current primary web sources before being treated as current fact.
• These patterns are grounded in a local April 2026 claude_code source snapshot. Re-check upstream code or docs before relying on volatile runtime details.
• Managed policy, safe-env rules, and live settings application are implementation-specific. Preserve the control model, but verify the exact field names and trust semantics in the target runtime.

Learnings Loop

Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.