Task subagents do not load project CLAUDE.md or .claude/rules/ -- project configuration silently ignored

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/13627
2. https://github.com/anthropics/claude-code/issues/15993
3. https://github.com/anthropics/claude-code/issues/18454

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

claude code and i reviewed the 3 potential duplicates before ensuring this is a different issue.

Detailed comparison with the 3 flagged issues:

#13627 -- About .claude/agents/*.md custom agent definition files. The YAML body (custom instructions in agent definitions) is not injected when a subagent is spawned. Different mechanism: that's agent definition content, not the project configuration files (CLAUDE.md, .claude/rules/) that the runtime auto-loads.

#15993 -- Closest match. Also about Task subagents missing project context. However, #15993 frames the problem as subagents not reading "protocol documents" -- custom project documentation the parent agent loaded during conversation. Our issue is narrower and more specific: it's about the built-in configuration loading mechanism (CLAUDE.md + .claude/rules/*.md) that the runtime auto-loads for every new claude session. These aren't arbitrary docs -- they're the files the runtime is designed to auto-load. The fix for ours is straightforward: run the same config-loading step for subagents that already runs for the main session. #15993 may require a more complex context-forking solution.

#18454 -- About the main agent ignoring CLAUDE.md and skills during multi-step tasks. Not about subagents at all -- the main session has the config loaded but doesn't follow it. Behavioral compliance issue, not a config-loading issue.

Can confirm this is a real issue and it has practical consequences for anyone using subagents heavily.

The workaround I've been using: embed critical rules directly in the subagent definition frontmatter rather than relying on CLAUDE.md being inherited.

For example, in .claude/agents/test-runner.md:

---
model: sonnet
description: Run tests and fix failures
allowed-tools: Bash, Read, Edit, Grep, Glob
---
You are a test runner agent.

## Project Rules (from CLAUDE.md)
- Use pnpm, not npm
- Tests go in __tests__/ directories
- Follow existing patterns in the codebase

## Your Task
...

Yes, this duplicates some CLAUDE.md content — but it ensures the subagent actually follows your project conventions. The duplication cost (a few hundred extra tokens) is much less than the cost of a subagent that ignores your conventions and makes changes you have to undo.

I've built a collection of subagent definitions with this pattern baked in: claude-code-recipes/subagents

That said, proper CLAUDE.md inheritance would be the right fix — especially for team settings where subagents are spawned dynamically and can't anticipate every rule.

Can also confirm. This is a problem and will keep us from using sub-agents for coding which is disappointing as it is a natural fit.

+1 on this. I hit the exact same problem and filed #49106 (now closed as duplicate).

Additional data point: Even with explicit instructions in CLAUDE.md to "prepend the contents of ~/.claude/subagent-rules.md to every subagent prompt," the model progressively abbreviates across multi-subagent sessions. Audited twice — same pattern both times: Task 1 gets full rules, by Task 4+ it's down to a 1-2 line summary (~5% of the original). The model drifts under context pressure regardless of how strongly instructed.

Implementation suggestion beyond auto-loading config: An OnAgentSpawn hook event (fitting the existing PreToolUse/PostToolUse architecture) would let users intercept subagent prompts before execution. This enables:

• Automatic preamble injection from a file
• Conditional injection based on agent type (code-writing agents get quality rules, Explore agents don't)
• Auditing/logging of what subagents actually receive

A simpler alternative: a subagentPreamble key in settings.json (string or file path) that the harness prepends automatically.

Either way, the fix needs to be at the harness level — the model can't be trusted to consistently copy-paste instructions across many subagent spawns.

Adding points from @0xbrainkid on #49106 before it goes stale:

• Baseline fix should be config inheritance, not hooks — subagents spawned within a project directory should automatically inherit the project's CLAUDE.md and .claude/rules/ the same way the parent session does. This is a configuration resolution change, not a new hook surface.
• Hooks for customization on top — the OnAgentSpawn hook would be for cases where inherited config needs to be modified or augmented per-subagent (e.g., injecting different rules based on task type).
• Hook payload should include spawn context — parent session ID, subagent task description, requested tools — so injection decisions can be conditional rather than blanket.

Experiencing the same issue. The lack of project rule inheritance in Task subagents is actively holding us back from adopting subagents in our workflow.

This is the subagent-inheritance case of the state-coordination problem documented in #59309. Task subagents don't have a mechanism to access the parent session's project configuration files (CLAUDE.md, .claude/rules/, etc.), so they operate without the constraints that the parent session enforces.

Root cause: Configuration state doesn't propagate from parent to subagent. Each agent has its own isolated context.

Solution: A workspace-level coordinator that tracks configuration artifacts (CLAUDE.md, rules, specs) across all agents. Subagents access the same coordinator as the parent, so on their first tool call, PreToolUse checks whether they're reading stale versions. If they are, additionalContext surfaces the drift and the subagent re-reads.

The subagent doesn't need to inherit the files — it just needs visibility into version mismatches.

I'm building this in the agent-coherence plugin (private alpha). It solves this exact issue: parallel subagents on the same codebase now see consistent rule versions.

The plugin is in active development; v0.1 ships in weeks, v0.1.1 (marketplace) on a 4-week deadline. If you'd want early access, I can add you to the alpha.

A simpler native solution exists for the specific failure mode here.

@phpmac just documented (in #59309) that SubagentStart + PreCompact hooks with additionalContext cover the CLAUDE.md rule propagation case in ~40 lines of Python with no external dependencies — the hook fires at subagent spawn and before compaction, reads CLAUDE.md, and injects it as a system reminder. Verified working (subagent switched from grep to rg on spawn).

My earlier comment framed this as a state-coordination failure requiring a MESI coordinator. That was the wrong diagnosis. The root cause here is instruction-propagation (rule absent from subagent context), not state-coherence (concurrent sessions disagreeing on a shared file version). The hook approach is the right fix for this class of problem.

The MESI coordinator is relevant when CLAUDE.md itself changes mid-session and running subagents are still working from a stale injected snapshot — a version-divergence problem rather than a rule-absence one. Different failure mode.

Leaving this correction so the thread stays accurate.

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

That seems way too hasty to close this issue – as it means that subagents in Claude Code behave fundamentally differently to how most users are going to expect them to behave. And opening a brand new issue to describe the exact same problem is a waste of time.

Can anyone comment on whether there is a genuinely good reason why subagents shouldn't read CLAUDE.md?