[Feature Request] Subagents should inherit parent agent context to avoid redundant codebase scanning

Yes - need this big time. I have related, but opposite problem - i'm trying to save context in a planning agent by having it spawn subagents to straightforward stuff (like write documents, etc.). The idea being that file writing is context expensive. But the cost of transferring context to an agent eats up the savings from file writing. "Spawn" would solve this nicely.

BTW - anyone with a different workaround for my issue, let me know (i've reached the limits of my creativity on this one...)

This would be epic. Most subagent use-cases would benefit, enabling more frequent delegation even as the context window grows, without wasting context:

• Explore again mid session as new information becomes available
• Perform web research on an issue
• Test a new feature using a browser integration

Write tests

Some new use cases may emerge:

• git commiting frequently throughout the session
• branching off to turn a new insight into a skill asynchronously / writing to a memory system
• frequently checking for relevant skills/memories as new user prompts or environment interactions come in

Shouldn't be just frontmatter though, the main agent should be allowed to decide (also for a generic Task)

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

I really think this is the optimal behavior for a large percentage of the agents (and skills and commands) people currently create.

Right now, if you want to define a re-usable prompt for something that involves a lot of detailed thinking/tools you have to choose between:

1. Polluting the main context window with all of the intermediate thinking and tool calls.
2. Running it without access to the main conversation context (essentially forcing an extremely harsh super compact before running the prompt).
3. Really weird and complicated approaches like trying to make the skill use bash to spawn a new claude instance with --fork-session or read the conversation history log files (very wasteful because of lack of token caching).

As an example: The other day I wanted to implement a /reflect skill that asks Claude to look back at the conversation so far, identify anything it got hung up on or had to hack around, and brainstorm specific followups that would make the process smoother in the future. As far as I can tell, there is effectively no way to implement something like that right now without dumping all of the intermediate brainstorming into the main context.

I think the _ideal_ solution would be for the existing context: fork option on skills to work this way (and to create some other option like context: isolated for the current behavior). This naming would be more consistent with what the --fork-session cli option.
https://code.claude.com/docs/en/skills#run-skills-in-a-subagent
(That's a breaking change though, so I'm assuming the Claude Code team would want to do something slightly different)

Rather than the breaking change I think it could just be a new argument for the Task tool and/or a new field in the subagent frontmatter. I'm honestly surprised this hasn't been prioritized, it seems so obvious

Adding evidence from a heavy production user (11 custom agents, daily use since Dec 2025, v2.1.70).

What We Tried

We have 11 specialized agents (pipeline orchestrator, RAM safety auditor, VOLD analysis, news/shock agent, live ops monitor, etc.) for a 0DTE options trading system. Each agent has detailed instructions in its definition MD file.

Over the past month, we systematically tried to get sub-agents to follow instructions:

1. Added "MANDATORY: Sub-Agent Workflow" block to all 11 agent MDs — prominent, at the top, impossible to miss. Sub-agents still don't follow it.
2. Made it Rule #1 in CLAUDE.md — "USE SUB-AGENTS FOR ALL WORK. Main context is for COORDINATION ONLY." Still ignored by spawned sub-agents.
3. Created an InstructionsLoaded hook (new in v2.1.69) — only fires for the main session, not sub-agents.
4. Added "Document Your Work in Memory" instructions to all 11 agent MDs — sub-agents don't document anything.

What Actually Works

The only reliable way to get a sub-agent to follow instructions is to put them directly in the prompt parameter of the Agent tool call. Agent definition MDs and CLAUDE.md are effectively decorative for sub-agent behavior.

Impact

This makes the agent architecture unreliable for real production use. We configure detailed instructions in agent MDs and CLAUDE.md expecting them to cascade to sub-agents — and they silently don't. The main session follows the rules, spawns a sub-agent, and that sub-agent flies blind.

Related issues confirming the same class of problem: #5528 (all directives ignored, locked), #4554 (name-based override), #7166 (CLAUDE.md inheritance undocumented), #22177 (inheritance flip-flopped between versions), #7515 (locked), #8395 (rule propagation, locked), #24773 (identity conflicts), #6825 (context inheritance configurable).

This is arguably the most fundamental gap in the agent system — everything else (permissions, hooks, compaction) is secondary if sub-agents can't read their own instructions.

Yes I agree. It should be an option Claude can decide.

Would save a lot of tokens when Claude decides

+1 on this. One specific use case: after a long investigation session, I'd love to spin off a subagent that inherits the full conversation context to generate documentation about what occurred — while I continue working in the main conversation in parallel.

Today the only options are /fork (interactive, blocks you) or the Agent tool (no parent context). A background fork that inherits context would bridge that gap.

One request: please consider making context inheritance opt-in (e.g. inherit_context=true) rather than the default. Subagents starting fresh is a useful property for isolated tasks, and changing the default would break existing workflows that rely on clean subagent contexts. Backwards compatibility matters here.

We experimentally confirmed the current limitations:

• /branch text passed to Agent prompt → treated as plain string, no history
• Parent session ID passed via resume → "No transcript found" (only subagent IDs work)
• /fork works for interactive branching but can't be dispatched as background

A PreToolUse hook on the Agent tool can inject context into every subagent launch:

CONTEXT=""
for f in CLAUDE.md .claude/CLAUDE.md README.md; do
    [ -f "$f" ] && CONTEXT+="--- $f ---
$(head -50 "$f")
"
done
CONTEXT+="--- Recent changes ---
$(git log --oneline -5 2>/dev/null)
"
for f in src/index.ts src/main.py package.json pyproject.toml; do
    [ -f "$f" ] && CONTEXT+="--- $f (first 30 lines) ---
$(head -30 "$f")
"
done
[ -z "$CONTEXT" ] && exit 0
echo "[SubagentContext] Key project files loaded for this agent" >&2
exit 0

A more practical approach: maintain a project-context.md that gets injected via UserPromptSubmit:

CTX_FILE=".claude/project-context.md"
[ -f "$CTX_FILE" ] || exit 0
jq -n --arg ctx "$(cat "$CTX_FILE")" '{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": $ctx
  }
}'
exit 0

Then auto-generate the context file periodically:

cat > .claude/project-context.md << 'EOF'
$(find src -name '*.ts' -o -name '*.py' | head -20)
$(cat package.json 2>/dev/null | jq '.dependencies | keys[]' 2>/dev/null | head -10)
$(git log --oneline -10 2>/dev/null)
EOF
exit 0

This ensures subagents (which also trigger UserPromptSubmit hooks) automatically receive the project context without the main agent needing to pass it explicitly.