Align layered settings/source precedence across config, agents, and plugins

[Crsei]

Background

The Rust port currently ships a narrower settings/source model than both the upstream TypeScript implementation and the configuration docs in this repo. The gaps are not limited to one screen: they affect general settings precedence, /agents source visibility, and plugin intent/configuration.

This matters now because the repo is in Full Build mode, and existing UI issues like #34 and #47 depend on the missing backend/source model rather than only missing presentation.

Related: #34, #47

Evidence

1. Effective settings precedence diverges from the documented/upstream hierarchy

The current loader in crates/cc-config/src/settings.rs merges settings as:

• managed
• user
• project
• local
• env
• cli

and the source rank table also makes Cli the highest winner (SettingsSource::Cli => 6).

Relevant code:

• crates/cc-config/src/settings.rs:5-18
• crates/cc-config/src/settings.rs:48-79
• crates/cc-config/src/settings.rs:1026-1062
• crates/claude-code-rs/src/main.rs:494-511

But the docs in this repo currently say the precedence is:

• managed (highest; cannot be overridden by command-line arguments)
• command line arguments
• local
• project
• user

Relevant docs:

• docs/claude-code-configuration/settings.md:448-467

So today we have a direct doc/code mismatch on one of the most security-sensitive parts of the settings model.

2. Agent settings only wire built-in + user + project, with plugin still marked as future work

The agent settings backend says it supports these sources:

• Builtin
• User
• Project
• Plugin (future hook; none registered today)

Relevant code:

• crates/claude-code-rs/src/ipc/agent_settings.rs:21-25
• crates/claude-code-rs/src/ipc/subsystem_types.rs:290-314

But the actual list loader only returns:

• built-ins
• ~/.cc-rust/agents/*.md
• {cwd}/.cc-rust/agents/*.md

Relevant code:

• crates/claude-code-rs/src/ipc/agent_settings.rs:104-129

There is no local/policy/flag agent scope in the Rust IPC model today, and plugin agents are not actually discovered. The Plugin enum variant exists, but list_all_agents() never loads it, and agents_dir_for_source() routes plugin/built-in entries to a dummy path.

Relevant code:

• crates/claude-code-rs/src/ipc/agent_settings.rs:366-372

Compared with the upstream src/components/agents/* chain, this means Rust currently lacks the broader source model needed for correct source ordering / override visibility.

3. Plugin "intent" from settings is documented, but not implemented in the Rust codepath

The plugin module comment explicitly describes a three-layer architecture where settings files declare desired plugins/marketplaces:

• intent
• materialization
• active

Relevant code:

• crates/claude-code-rs/src/plugins/mod.rs:9-12

The docs in this repo also document enabledPlugins and extraKnownMarketplaces, including managed/local/project/user scopes and managed policy gates like marketplace restrictions.

Relevant docs:

• docs/claude-code-configuration/settings.md:521-570
• docs/claude-code-configuration/settings.md:545-570

But in the current Rust codebase:

• enabledPlugins is not referenced outside docs
• extraKnownMarketplaces / strictKnownMarketplaces are not referenced outside docs
• plugin state is persisted through ~/.cc-rust/plugins/installed_plugins.json
• active plugin discovery only covers tools / skills / MCP

Relevant code:

• crates/claude-code-rs/src/commands/plugin_cmd.rs:3-8
• crates/claude-code-rs/src/commands/plugin_cmd.rs:85-90
• crates/claude-code-rs/src/plugins/mod.rs:151-156
• crates/claude-code-rs/src/plugins/mod.rs:499-598

There is also no plugin-agent discovery path today: we have discover_plugin_skills() / tool / MCP discovery, but no corresponding agent discovery wired into /agents.

Gap Summary

The missing pieces are:

1. A parity-correct effective settings precedence model for managed / local / project / user / flag(cli) / env, including a decision on whether Rust should match the documented "managed cannot be overridden by CLI" rule or update docs to reflect an intentional divergence.
2. A complete agent-definition source model that can represent and surface upstream-style source layers and override/shadow rules, rather than only built-in + user + project.
3. A real settings-driven plugin intent layer (enabledPlugins, marketplace registration/restriction, managed policy gates), instead of only installed_plugins.json + in-memory session state.
4. Plugin-contributed agent discovery, not just tools / skills / MCP.

Acceptance

• Align the effective settings precedence with the intended full-build model and add tests that prove the winner order.
• Implement the missing managed/policy resolution pieces (or explicitly scope/document what is intentionally unsupported).
• Extend agent source modeling so /agents can distinguish and order the missing scopes correctly, including override/shadow visibility.
• Wire plugin-contributed agents into the same source model, or explicitly mark them unsupported in code and docs.
• Implement plugin settings intent keys (enabledPlugins, marketplace registration/restriction) and thread them into plugin activation/materialization.
• Update docs/tests so the repo no longer documents behavior that the Rust implementation does not actually provide.