[DOCS] Path-specific rules do not load in subagents, teammates, or skill-forked contexts

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://code.claude.com/docs/en/agent-teams - https://code.claude.com/docs/en/memory

Section/Topic

• Agent teams: "Context and communication" section — what context teammates receive - Memory: "Path-specific rules" subsection — how path-scoped rules work

Current Documentation

The agent teams docs say:

"Each teammate is a full, independent Claude Code session."

And:

"When spawned, a teammate loads the same project context as a regular session: CLAUDE.md, MCP servers, and skills."

The memory docs say:

"Rules can be scoped to specific files using YAML frontmatter with the paths field. These conditional rules only apply when Claude is working with files matching the specified patterns."

And:

"Path-scoped rules trigger when Claude reads files matching the pattern, not on every tool use."

Neither page documents whether path-specific rules load in spawned contexts. Given that teammates are described as "full, independent sessions" that load "the same project context as a regular session," a developer would reasonably expect path rules to also load.

What's Wrong or Missing?

All three spawned context types (subagent, teammate, skill-forked) see only global rules — rules without paths: frontmatter.

Path rules load based on the context's own file activity. Spawned contexts start with zero file activity, so no path rules trigger at startup. Spawned contexts do not inherit the parent session's already-active path triggers.

Reproduction steps:

Prerequisites: This issue requires test fixture files that must exist before the Claude Code session starts. From any existing git repository, run in your terminal:

mkdir -p .claude/rules src
cat > .claude/rules/global-test-rule.md << 'EOF'
# Global Test Rule
When asked to list your rules, mention that you see the "Global Test Rule".
EOF
cat > .claude/rules/path-test-rule.md << 'EOF'
---
paths: ["src/**/*.ts"]
---
# Path Test Rule
When asked to list your rules, mention that you see the "Path Test Rule".
EOF
echo "// test" > src/test.ts
claude

This uses mkdir -p so it creates .claude/rules/ and src/ only if they don't already exist, preserving any existing contents.

This requires three separate sessions.

Session 1 — Subagent test:

1. Read src/test.ts to trigger the path rule, then list all rules currently loaded in your context. Confirm both Global Test Rule and Path Test Rule appear.
2. Spawn a general-purpose subagent with this prompt: "List all rules currently loaded in your context. Do you see 'Global Test Rule'? Do you see 'Path Test Rule'?"
3. Observe: subagent sees only Global Test Rule; Path Test Rule is absent.
4. Add the env var CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS set to "1" to .claude/settings.json.

Session 2 — Teammate test:

1. Exit the session (/exit or Ctrl+C) and relaunch claude — team tools are only loaded at startup.
2. Read src/test.ts to re-trigger the path rule, then create a team called "rule-test" and spawn a general-purpose teammate named "rule-checker" with this prompt: "List all rules currently loaded in your context. Do you see 'Global Test Rule'? Do you see 'Path Test Rule'?"
3. Wait for the teammate's response via SendMessage. Observe: teammate also sees only Global Test Rule; Path Test Rule is absent.
4. Shut down the teammate and delete the team.
5. Create a skill directory .claude/skills/rule-check/ with a SKILL.md containing context: fork, agent: general-purpose, and the prompt: "List all rules currently loaded in your context. Do you see 'Global Test Rule'? Do you see 'Path Test Rule'?"

Session 3 — Skill-forked test:

1. Exit the session (/exit or Ctrl+C) and relaunch claude — skills are discovered at startup.
2. Read src/test.ts to re-trigger the path rule, then invoke /rule-check.
3. Observe: skill-forked context also sees only Global Test Rule; Path Test Rule is absent.
4. Clean up: delete .claude/skills/rule-check/, .claude/rules/global-test-rule.md, .claude/rules/path-test-rule.md, and src/.

Results:

| Context | Path-specific rules loaded at startup | Global rules loaded |
|---------|--------------------------------------|-------------------|
| Main session | YES | YES |
| Subagent | NO | YES |
| Teammate | NO | YES |
| Skill-Forked | NO | YES |

Why this happens: Path rules check the context's OWN active files. Spawned contexts begin with zero file activity. If a spawned context later works on files matching a rule's path pattern, the rule may activate dynamically during that context's execution — but it does not inherit the parent's already-active triggers.

Suggested Improvement

Add to the agent teams docs under "Context and communication":

Path-specific rules: Teammates do not inherit path-specific rules from the team lead. Rules with paths: frontmatter load based on each context's own file activity. Since teammates start with no file activity, path-specific rules are not active at spawn time. If a teammate works on files matching a rule's path pattern, the rule may activate during execution. Include critical rule content in the teammate's spawn prompt if it's needed from the start.

Add to the subagents docs under "Configure subagents" or a new "Context" section:

Rules in subagents: Subagents load global rules (those without paths: frontmatter) but do not inherit path-specific rules from the parent session. If your subagent needs specific rule content, include it in the subagent's system prompt or use the skills: field to inject the information.

Impact

Medium - Makes feature difficult to understand

Additional Context

• Tested on 2026-02-24 (original discovery) and re-verified on 2026-03-09 (current Claude Code version). All three spawned contexts reported identical sets of global-only rules in both test runs.
• This is the clearest empirical distinction between teammates and main sessions. Even teammates — described as "full, independent sessions" — do NOT inherit path-specific rules.
• The rerun resolved three uncertain items (U2/U3/U4) from the original research: subagent path rules = NO, teammate path rules = NO, skill-forked path rules = NO. All three confirmed with HIGH confidence.
• No existing issue covers this. Related issues: #8395 (user-level agent rules), #30703 (custom agents ignored for team agents) — both touch on rule/config inheritance but not path-scoped rule loading behavior.
• v2.1.69 fixed "duplicate CLAUDE.md, slash commands, agents, and rules in nested worktrees" — addresses duplication in worktrees, not path rule loading in spawned contexts.