[DOCS] `--setting-sources` docs do not say what each source value actually gates (CLAUDE.md, plugins, hooks, skills, agents, commands, `--settings`)

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/cli-reference

Section/Topic

The --setting-sources flag on the CLI reference, plus the settings, memory, hooks, plugins, MCP and headless pages that describe the things it filters.

Current Documentation

The CLI reference describes the flag in one line:

--setting-sources — Comma-separated list of setting sources to load (user, project, local)

The memory guide adds that CLAUDE.local.md is skipped without local and, since #78007, that project rules are skipped without project. That's all the docs say about what the flag reaches.

What's Wrong or Missing?

The flag gates far more than the three settings.json files, and none of it is written down. I measured this on 2.1.261 (Windows, subscription OAuth) with content probes: a marker phrase in each file, then a headless claude -p asked whether the phrase is in its context, with tools forbidden. Command:

claude -p "<probe>" --setting-sources project,local --settings .claude/settings.agent.json

Dropped when user is omitted:

• ~/.claude/CLAUDE.md
• ~/.claude/settings.json
• every plugin, including the plugins' hooks and skills (a SessionStart hook from one plugin stopped injecting its context)
• ~/.claude/skills/, ~/.claude/agents/, ~/.claude/commands/

Still loaded with project,local:

• the project CLAUDE.md
• .claude/settings.json, and its PreToolUse hooks still fire
• .claude/settings.local.json
• project .mcp.json servers
• auto-memory (MEMORY.md)
• .claude/commands/
• the --settings file

I only know this because I probed for it. Nobody reading the CLI reference could predict that omitting user removes plugins and their hooks, or that --settings survives the filter. #49860 asked for the flag to cover CLAUDE.md, skills, agents and commands in April; on 2.1.261 it apparently does, and the docs never caught up.

Two behaviours are worth documenting alongside, because they change the answer for anyone using the flag for isolation:

• #87590: with the project directory under $HOME, ~/.claude/CLAUDE.md and ~/.claude/rules/*.md still load under --setting-sources project, since the parent-directory walk reaches ~. My project is outside the home directory, which is why the probe above came out clean. Until that's fixed, the doc should say the isolation depends on where the project lives.
• #86837: CLAUDE_CONFIG_DIR does not exclude ~/.claude/CLAUDE.md either, so the flag is currently the only way to keep a headless run from inheriting an operator's user-level instructions without --bare, which also drops the project CLAUDE.md, hooks and MCP.

Suggested Improvement

On the --setting-sources row in cli-reference.md, replace the one-liner with a table showing what each source value controls. The rows I'd expect are settings.json, CLAUDE.md, .claude/rules/, skills, agents, commands, hooks, plugins, .mcp.json and auto-memory. Say explicitly that --settings is not subject to the filter. Add the $HOME caveat from #87590 until it's fixed.

On headless.md, cross-link the flag from the section that recommends --bare, since --setting-sources project,local is the option for a scheduled run that needs the project's hooks and MCP servers but must not inherit the operator's interactive config.

Impact

Medium - Makes feature difficult to understand

Additional Context

My use case is a scheduled headless run that must take its configuration from the repository alone. Before adding the flag it inherited a 15 KB user-level CLAUDE.md written for interactive sessions, plus three plugins' SessionStart, UserPromptSubmit and Stop hooks. The behaviour I measured is exactly what I wanted, but I had to find it by experiment, and I can't tell from the docs whether any of it is intended and stable.

Version: 2.1.261.