[BUG] Plugin userConfig values written to global settings.json even when plugin is installed with project scope

This is a scope-boundary bug, not just a config placement bug.

If a plugin is installed with project scope, any generated or requested userConfig should be attributable to that scope all the way through persistence. A project-scoped install writing into global settings turns a local trust decision into ambient configuration for unrelated workspaces.

A regression test I would want:

1. install plugin at project scope with userConfig
2. assert config is written only under project/local settings, not global settings
3. open a second project where plugin is not installed and assert no config is visible or active
4. uninstall or disable the project plugin and assert only that project's config is removed
5. repeat for explicit global install and verify the global path is used only there

The durable event should record scope, target settings file, plugin id, and whether the write was project, global, or inherited. If a global write is intentional fallback, it should be explicit in UI/CLI and in audit output.

From the brainAI agent-receipts angle, this is the same core problem as agent identity and config provenance: a verifier needs to know which principal and scope authorized a setting, not just that a setting exists.

Boundary: architecture/test feedback only. I have not reproduced this path locally or inspected Claude Code internals.

Follow-up finding, related to but distinct from the storage-location issue described above.

Repro (Claude Code CLI 2.1.210, Windows):

1. A plugin declares userConfig.local_repo_path (type: "directory", required), referenced in one of its agents' instructions as ${user_config.local_repo_path}.
2. Removed the pluginConfigs entry for this plugin from the global ~/.claude/settings.json, and set only a project-local .claude/settings.json → pluginConfigs["my-plugin@my-marketplace"].options.local_repo_path, pointing at a valid, existing directory. Ran /reload-plugins, then invoked the agent fresh.

• Result: the agent's live instructions contained the literal, unsubstituted string ${user_config.local_repo_path} — no value was injected at all, even though a valid value existed in project scope and installed_plugins.json correctly recorded the install as "scope": "project" for this exact project path.

1. Restored a pluginConfigs entry for the same key in the global settings (a different directory value than the project-local one — both directories exist on disk), left the project-local entry untouched. Ran /reload-plugins again, invoked the agent fresh.

• Result: ${user_config.local_repo_path} was now substituted, but with the global value. The project-local value was never consulted.

So this isn't only about where userConfig answers get written during install (the original report above) — the placeholder-substitution step itself appears to read exclusively from ~/.claude/settings.json, never from the project-local .claude/settings.json, regardless of how the project-local value got there (installer or manual edit). When no global entry exists for the key, the placeholder is left raw/unsubstituted in the agent's live instructions rather than falling back to project scope or failing with a clear error.

This makes per-project userConfig values effectively non-functional today, not just inconveniently stored in the wrong scope.

Thanks for the detailed report. I reproduced the behavior on 2.1.233: installing a plugin with --scope project and answering its userConfig prompts records the install as project-scoped and writes enabledPlugins to the project's .claude/settings.json, but the option values land in pluginConfigs in the user-level ~/.claude/settings.json.

This is currently intended rather than a bug. pluginConfigs values are substituted into plugin hook, MCP, LSP, and monitor commands, so since 2.1.207 they are only written to and read from user settings, the --settings flag, and managed settings — never from a project's .claude/settings.json or .claude/settings.local.json, because a cloned repository could otherwise supply values that end up in commands. That also explains your follow-up: a project-local pluginConfigs entry is ignored, and the placeholder stays unsubstituted when there is no user-level value. Docs: https://code.claude.com/docs/en/settings#pluginconfigs and https://code.claude.com/docs/en/plugins-reference#user-configuration

That said, we agree the current model is limiting for project-scoped installs whose values are inherently per-project (sibling repo paths, branch names). We're leaving this open as a usability improvement — e.g. per-project option values stored outside the workspace so they can't be repo-supplied. In the meantime, a --settings file passed at launch is a way to give a project its own values.

🤖 Generated with Claude Code