Task subagents do not load project CLAUDE.md or .claude/rules/ -- project configuration silently ignored
Description
Task subagents (launched via the Task tool) do not load project-level configuration files:
CLAUDE.md(project root).claude/rules/*.md~/.claude/CLAUDE.md(user-level)
These files define HOW the agent should behave in a project -- code conventions, error handling rules, cross-platform requirements, protected file review gates, etc. When a subagent works in the same project directory, it should get the same configuration loaded as the main agent. Currently it operates with no project context at all.
Distinct from existing issues
- #12790 asks for optional conversation context forking (complex feature -- sharing chat history)
- #26429 asks for
CLAUDE_PROJECT_DIRenv var (path access) - This issue: project configuration files that define behavioral rules are not loaded. This is baseline configuration loading, not optional context sharing.
Real-world impact
We maintain a cross-platform tooling project with ~15 rule files in .claude/rules/ covering error handling, script standards, cross-platform dispatch, protected file review gates, and more.
We wrote new error handling rules in .claude/rules/error-handling.md and .claude/rules/script-standards.md, then delegated a full audit of ~89 error-suppression patterns across all scripts to 6 parallel Task subagents. The subagents reported 10 violations found. A manual re-audit with the rules in main-agent context found 5 additional violations, 4 logic bugs, and 1 missing error path that the subagents missed entirely.
Root cause: The subagents did not have the rules loaded -- they applied their own interpretation of "error handling" rather than the specific requirements defined in the project's rule files. The subagent prompts included a summary of what to look for, but summaries lose precision compared to the actual rule language.
Current workaround
We maintain a coaching item: "Never delegate code-writing to subagents in projects with cross-cutting rules. Use subagents for research only, or include the critical rules verbatim in the subagent prompt."
This is unsustainable -- it means subagents can never be used for their most valuable purpose (parallel work on the same codebase) in any project that has meaningful rules. Including rules verbatim in every subagent prompt is error-prone and doesn't scale as rule files change.
Expected behavior
When a Task subagent is launched, it should automatically load:
CLAUDE.mdin the project root (and subdirectories as applicable).claude/rules/*.mdfiles~/.claude/CLAUDE.md(user-level)
This matches what happens when a user starts a new claude session in the same directory.
Environment
- Claude Code 2.1.62
- Windows 11 (Git Bash) and macOS
- Observed across multiple sessions
This issue has 12 comments on GitHub. Read the full discussion on GitHub ↗