[DOCS] Sub-agents page: omitClaudeMd and Explore do not stop a nested CLAUDE.md or path-scoped rule loaded after a Read; --agent session has no git status

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

"Frontmatter reference" (omitClaudeMd row), "What loads at startup", and "Invoke subagents explicitly" > "Run the whole session as a subagent"

Current Documentation

The omitClaudeMd row says: "Set to true to launch this subagent without the user, project, and local CLAUDE.md files; managed policy files still load, except for managed subagents."

"What loads at startup" says a subagent whose definition sets omitClaudeMd "loads only the managed policy files", and that Explore and Plan skip CLAUDE.md files and the git status snapshot.

"Run the whole session as a subagent" says that, unless the agent's prompt is empty, a custom subagent's system prompt "replaces the default Claude Code system prompt entirely, the same way --system-prompt does", and that CLAUDE.md files still load.

What's Wrong or Missing?

Measured on Claude Code 2.1.293 with a request-capturing local API server and a unique marker string in each instruction file:

1. At startup, omitClaudeMd: true (in frontmatter or in --agents JSON) works as documented: none of the user, project, local or .claude/rules/ content reached the subagent, while the same agent without the field received all of it. But after the subagent Reads a file in a subdirectory, that subdirectory's CLAUDE.md and a paths:-scoped rule matching the file arrive as system-reminders in its next request. The built-in Explore agent behaves the same way (Plan skipped CLAUDE.md at startup as documented; its read-triggered behaviour was not tested). Several sentences state the omission without a startup qualifier: the frontmatter row ("launch this subagent without the user, project, and local CLAUDE.md files"), "Explore and Plan skip your CLAUDE.md files", and "To launch one of your own subagents without the user, project, and local CLAUDE.md files". Nested CLAUDE.md loading on read is documented on the memory page, but not how it interacts with omitClaudeMd or Explore, so a reader can take omitClaudeMd as a guarantee that no CLAUDE.md content reaches the subagent.

1. A session started with claude -p --agent <name> had no git status snapshot in its requests, while plain claude -p in the same repository did. CLAUDE.md files loaded and omitClaudeMd was ignored, both as documented. The page does not say whether the git status snapshot goes away with the replaced system prompt. (Only --agent was tested, not the agent setting or --system-prompt alone.)

Suggested Improvement

• In the omitClaudeMd row and "What loads at startup", say that the omission applies to startup, and that a nested CLAUDE.md or a path-scoped rule can still be attached when the subagent reads a file they apply to, if that is intended. Add the same note for Explore, and confirm whether Plan behaves the same.
• In "Run the whole session as a subagent", say whether the git status snapshot is kept or dropped.

Impact

Medium - Makes feature difficult to understand

Additional Context

Method: a throwaway git repo with a different marker string in each of CLAUDE.md, CLAUDE.local.md, .claude/rules/*.md, a parent repo's rules, a paths: sub/** rule and sub/CLAUDE.md. Each case ran claude -p against a local server that recorded every request. Positive control: the main loop's first request carried all the startup markers in every run except the --bare and --safe-mode cases, where their absence was the expected result. The startup omitClaudeMd case was repeated in the interactive TUI with the same result.

Steps to reproduce item 1:

1. In a git repo, create sub/CLAUDE.md containing a unique string, and sub/file.txt.
2. Create .claude/agents/omit-probe.md:

``
---
name: omit-probe
description: Reads one file and reports its first line
omitClaudeMd: true
---
Read the file you are given and reply with its first line.
``

1. Start a session and ask: "Use the omit-probe agent to read sub/file.txt."
2. Inspect the subagent's request after the Read (for example with ANTHROPIC_BASE_URL pointed at a logging proxy): the sub/CLAUDE.md string is present as a system-reminder. Its first request does not contain it.

Related: #92750 (another item in the same "What loads at startup" list).

Environment: Claude Code 2.1.293, macOS.