[Feature]: forge settings surface — user + managed (MDM) layers for enabled channels / models / tools / gateway

[initializ-mk]

Problem

What forge offers for tools, models, and channels during forge init / forge run / forge try is pre-built / hardcoded, with no configurable settings surface — and no way for an enterprise to centrally set defaults or constrain the offered set on a fleet:

• Channels are a hardcoded factory switch — createPlugin() (forge-cli/cmd/channel.go:236) + defaultRegistry() (:250) enumerate slack/telegram/msteams; adding/removing an offered channel is a code change.
• Builtin tools offered in the quickstart are a hardcoded list — quickstartPreset() (forge-cli/cmd/try.go:248): BuiltinTools: []string{"http_request","datetime_now","math_calculate"}.
• Model options come from CLI flags with baked-in provider names — --provider openai|anthropic|gemini|ollama (try.go:56), and the wizard's provider choices in forge init.
• The model gateway endpoint (base_url / auth_scheme / auth_header_name, ModelRef, forge-core/types/config.go:281) is set per-agent in forge.yaml, not injectable from a machine/org setting.

There is no user-level or org-level (MDM) settings layer that configures which channels/models/tools are enabled or defaulted, or that injects the gateway endpoint centrally.

What exists today (and what's missing)

Forge already has a three-layer policy system — forge-core/security/platform_policy_layers.go: LayerSystem (/etc/forge/policy.yaml), LayerUser (~/.forge/policy.yaml), LayerWorkspace — with FirstLayerDenyingTool / FirstLayerForbiddingModel / FirstLayerDenyingChannel / egress-max and a one-way tighten ratchet.

But that is a deny/restrict construct (a layer can forbid a tool/model/channel at runtime). It is not an enablement/config/defaults construct: it can't say "these are the channels offered in forge init," "this is the default model," "this is the gateway URL," or "this org's fleet may only use these models." The offered/default surface is hardcoded (above).

Goal

Add a layered settings surface for forge, mirroring Claude Code settings + managed settings: a user layer and a managed (enterprise, MDM-droppable) layer, so enabled channels, enabled model options / providers / gateway endpoint, enabled builtin tools, and defaults all become configurable — and init / run / try read the offered/default/enabled set from settings instead of hardcoding it.

Precedence (mirror Claude Code, highest → lowest)

1. Managed settings — org, non-overridable (with a security-stricter-wins exception for restrictive keys). OS system dirs + MDM + drop-in dir:
   • macOS: /Library/Application Support/forge/managed-settings.json (+ MDM config profile domain), Linux/WSL: /etc/forge/managed-settings.json, Windows: C:\Program Files\forge\managed-settings.json; plus managed-settings.d/*.json merged alphabetically.
2. Command line — forge --settings <file> / existing flags for one session.
3. Project local — .forge/settings.local.json.
4. Shared project — .forge/settings.json.
5. User — ~/.forge/settings.json.

Configurable surface (initial set)

Key	Controls	Replaces today's hardcode
channels.enabled (+ available)	which channel adapters forge init/run/channel add offer/enable	createPlugin/defaultRegistry switch
models.availableModels (allowlist) + models.default + models.providers.enabled	which providers/models are offered + the default; managed layer can lock the allowlist (Claude Code's availableModels semantic)	--provider flag enum + wizard choices
models.gateway (base_url, auth_scheme, auth_header_name)	inject the model gateway endpoint centrally (per-user or org)	per-agent forge.yaml ModelRef only
tools.builtins.enabled	which builtin tools are offered/defaulted	quickstartPreset list
env, defaults for egress posture, etc.	fleet defaults	—

Settings vs policy — SEPARATE surfaces (decided)

Settings and the existing policy.yaml layers stay separate constructs — they are different surfaces with different owners and delivery paths:

	Settings (this issue)	Policy (platform_policy_layers.go, exists)
Role	Positive: config / enablement / defaults / gateway injection — what's offered	Negative: deny / restrict / tighten — what's forbidden
Surface	Developer surface management (client-side)	Server surface equivalent — the runtime deny enforcement
Delivery	user ~/.forge/settings.json → managed managed-settings.json (MDM / system dir)	injected server-side via the control plane (platform policy, already wired), AND can be delivered client-side alongside managed-settings.json in the same system dir / drop-in
Semantics	list keys merge; managed can additionally lock an allowlist (availableModels-style)	one-way tighten ratchet; stricter layer wins

So: do NOT fold policy deny-keys into settings. Settings manages the developer/client surface (offered/enabled/defaulted channels, models, tools, gateway); policy remains the server/control-plane deny layer. They're complementary — an org can ship managed-settings.json (developer-surface constraints + defaults) next to a policy.yaml (deny) on the fleet, while the control plane injects the same policy server-side. The two loaders stay independent; a managed lock in settings (positive allowlist) is the counterpart to a policy deny (negative), and both can be present.

List keys merge across settings layers (like Claude Code's permissions.allow); allowlist/lock keys and the managed layer follow "managed wins / stricter wins." Policy keeps its own existing merge/tighten semantics — unchanged by this issue.

Deliverables

• Settings schema ($schema-published, like Claude Code) + a loader with the 5-layer precedence, list-merge, and managed-lock semantics; OS system-dir + drop-in + MDM discovery.
• Wire forge init, forge run, forge try, and forge channel to read the offered/enabled/default sets (channels, models/providers, builtins, gateway endpoint) from resolved settings instead of hardcoded lists/flags.
• Managed non-overridability + security-stricter-wins exceptions; a forge settings inspect/verify command (mirror Claude Code's precedence-debug affordance).
• Docs: a settings + managed-settings reference under docs/, and how it relates to docs/security/platform-policy.md (the deny layers).

Acceptance

• A user ~/.forge/settings.json can set the default model, enabled channels, enabled builtins, and the model gateway base_url/auth_scheme; init/run/try honor it.
• A managed managed-settings.json (system dir / MDM) overrides user/project values and can lock the model allowlist so --model/forge.yaml can't select outside it.
• Removing a channel from channels.enabled (managed) makes forge run --with <that> refuse it, and forge channel add not offer it.
• The offered set in init/try is no longer hardcoded — it derives from resolved settings.
• Precedence + merge + managed-lock covered by tests; a forge settings command shows the effective value + which layer set it.

Related

• Companion backlog: OAuth/OIDC login to the model gateway (acquire + inject a short-lived token) — the gateway URL + OIDC config it needs are injected by THIS settings surface. (cross-link on creation)
• Existing deny layers: forge-core/security/platform_policy_layers.go, docs/security/platform-policy.md.
• Model gateway auth: ModelRef (forge-core/types/config.go:281), AuthScheme (forge-core/llm/client.go:13), issues LLM client: apikey-header auth scheme for Kong AI Gateway (key-auth) #302/feat(llm): apikey_header auth scheme for Kong AI Gateway key-auth #303.
• Prior art: Claude Code settings + managed settings.

[initializ-mk]

Companion: #455 (OAuth/OIDC login to the model gateway). The gateway base_url + OIDC issuer/client/scopes that #455 needs are injected by this settings surface (models.gateway + a user/managed OIDC config block). Land the settings loader first so #455 has a config source.

[initializ-mk]

Decision recorded (see updated body): settings and policy stay separate. Settings = developer surface management (positive config/enablement/defaults/gateway, client-side, user→managed). Policy = server surface equivalent (deny/restrict/tighten), injected server-side via the control plane AND deliverable alongside managed-settings.json on the fleet. Not unifying — a managed lock in settings is the positive counterpart to a policy deny; both can co-exist, independent loaders.

[initializ-mk]

First slice implemented in #456 (foundation + models.default/gateway consumer).

• forge-core/settings: schema (channels/models/tools/gateway/env) + 5-layer loader (managed → CLI → project-local → project → user) with OS system-dir managed paths + managed-settings.d/ drop-ins + FORGE_MANAGED_SETTINGS/FORGE_USER_SETTINGS; list-union / scalar-highest-wins merge; managed available_models LOCK; fail-loud on unknown/malformed.
• forge settings [show] inspect command (layers + paths + effective, --json).
• Proof consumer: forge try seeds provider/model from models.default and injects models.gateway into the scaffolded forge.yaml model block (base_url/auth_scheme/auth_header_name) — the config source [Feature]: OAuth/OIDC login to the model gateway — acquire + inject a short-lived token on LLM calls (apiKeyHelper analog) #455 needs.
• Kept separate from platform policy per the decided design (independent loaders; policy untouched).

Remaining (follow-up PRs): wire forge init, forge run --with channel gating, and builtin-tool offering to resolved settings; optional per-field provenance in forge settings.

[initializ-mk]

Managed settings must be non-developer-overridable (confirmed in #456 review). #456 now loads the managed layer only from the fixed OS system path (no env/flag redirect) — macOS /Library/Application Support/forge, Linux/WSL /etc/forge, Windows C:\Program Files\forge — co-located with policy.yaml. Tamper-resistance = OS file perms on that path (root-owned on a managed machine).

Follow-up — additional managed delivery mechanisms (Claude Code supports these beyond file-based; all non-developer-overridable by design):

• Server-managed: control-plane fetch + local cache applied at startup, replaced on each successful fetch (the natural fit with the platform control plane, which already injects policy server-side).
• macOS configuration profile: a managed-preferences domain (e.g. ai.initializ.forge), same top-level keys as managed-settings.json, nested as dicts / plist arrays.
• Windows registry: JSON under HKLM\SOFTWARE\Policies\… (and HKCU), as an alternative to the file path.
• managed-mcp.json sibling for managed MCP servers.

This PR ships the file-based mechanism (fixed path + managed-settings.d/ drop-ins); the above are tracked here for later.

[initializ-mk]

Next consumer wired: channels.enabled gating — #458. When channels.enabled is non-empty it's an allowlist: forge run --with <x> refuses a non-enabled adapter (before the policy deny filter) and forge channel add <x> refuses to scaffold one; empty = unconstrained. Positive enablement surface complementing the policy deny — shared channelsEnabledBySettings helper, tests + docs.

Remaining consumers: forge init wiring (models/channels/builtins into wizard + non-interactive scaffold), builtin-tool offering (tools.builtins.enabled), and the additional managed delivery mechanisms noted earlier (server-managed / config profile / registry).

[initializ-mk]

forge init wiring + builtin-tool offering — #459.

• forge init: models.gateway injected into the scaffolded forge.yaml (both modes); non-interactive models.default seeds provider/model + tools.builtins.enabled seeds builtins when flags omitted (a settings default even satisfies the required --model-provider); channels.enabled gates --channels.
• forge try: tools.builtins.enabled overrides the quickstart builtin set.

Consumers now wired: models.default/gateway (try #456, init #459), channel gating on all 3 entry points (#458), builtin offering (try/init #459).

Remaining follow-ups: interactive-wizard defaulting for forge init (deferred to avoid TUI churn — wizard stays authoritative, only gateway injected there), and the additional managed delivery mechanisms (server-managed control-plane fetch / macOS config profile / Windows registry).

[initializ-mk]

Skills setting + interactive-wizard filtering — #460.

• New skills.enabled setting (union-merged). forge init seeds --skills from it (non-interactive) and gates the selection (both modes); forge try left as the fixed weather demo.
• Interactive wizard now filters its options by settings — offers only channels.enabled channels (closes the feat(settings): wire forge init + builtin-tool offering to settings (#454) #459-review late-failure) and skills.enabled skills; disabled options can't be picked. Generalized feat(settings): gate channels on settings.channels.enabled (#454) #458's gate helper to enabledBySettings(noun, …).

Deferred (last wizard piece): pre-selecting models.default in the interactive provider step — needs a preselect capability in the SingleSelect component (only a Selected() getter today); deferred rather than force a TUI-component change. Also remaining: the additional managed delivery mechanisms (server-managed / macOS config profile / Windows registry).

Settings surface now covers channels, models(+gateway), tools.builtins, and skills, with consumers wired across try/init/run --with/channel add|serve + interactive wizard filtering.

[initializ-mk]

Provider/model wizard pre-selection — #462. Added SingleSelect.SelectByValue (cursor-only preselect, no auto-confirm) and wired NewProviderStep to pre-highlight models.default.provider + preselect models.default.model (OpenAI model phase); collectInteractive passes them through.

Interactive-wizard defaulting is now complete (channel/skill filtering #460 + provider/model pre-selection #462). The settings surface — channels, models(+gateway), tools.builtins, skills — is fully wired across try / init (interactive + non-interactive) / run --with / channel add|serve.

Remaining epic item: additional managed delivery mechanisms (server-managed control-plane fetch / macOS config profile / Windows registry).

[initializ-mk]

Filed the server-managed settings delivery mechanism as its own backlog issue: #463 — control-plane fetch (reusing the existing platform-callout contract: tenancy headers + Bearer + X-Workload-Token) + local last-known-good cache, in the managed tier, non-developer-overridable. The remaining managed mechanisms (macOS config profile, Windows registry) stay as future sibling follow-ups.