Feature Request: Scoped Context Passing for Subagents

Title: Feature Request: Scoped Context Passing for Subagents

Body

Is your feature request related to a problem? Please describe.

The subagent feature, introduced in v1.0.60 and detailed in the official documentation, is a powerful mechanism for creating specialized AI assistants. The key benefit of a subagent having its own context window is that it prevents the main conversation from getting polluted with task-specific details.

However, the current implementation of this context isolation is "all or nothing." When a task is delegated, the subagent starts with a completely clean slate. This forces the subagent to perform redundant context-gathering steps that the parent agent may have already completed (e.g., analyzing a git diff, reading relevant files, or understanding the user's high-level goal).

This leads to a few key inefficiencies:

• Increased Latency & Token Cost: The subagent consumes time and tokens re-discovering information that was already available in the parent context.
• Loss of High-Level Context: The subagent might miss the strategic goal or important constraints known to the parent agent, leading to solutions that are technically correct but not perfectly aligned with the user's original intent.
• Limited Workflow Complexity: It's difficult to build truly hierarchical agent workflows where a primary agent can effectively delegate well-scoped sub-tasks.

Describe the solution you'd like

I propose an enhancement to allow for scoped context passing from the parent agent to a subagent. This would provide a middle ground between complete context isolation and full context inheritance, enabling more efficient and effective delegation.

Here are a couple of potential implementation approaches this could take:

1. Explicit Context Passing via Prompt

Allow the user to pass a summary, file reference, or other context directly in the invocation prompt. This gives the user fine-grained, on-the-fly control.

2. Declarative Context Scoping via Frontmatter

Introduce a new optional field in the subagent's markdown definition file (e.g., in .claude/agents/my-agent.md) to specify what context should be automatically inherited from the parent.

Example code-reviewer.md frontmatter:

---
name: code-reviewer
description: An expert code reviewer that checks for quality, style, and bugs.
tools: Read, Grep, Glob
inherit_context: [summary, git_diff, user_prompt] 
---

You are a senior code reviewer. Your task is to analyze the provided code changes...

The inherit_context array could accept predefined keys that the system knows how to populate, such as: summary, git_diff, relevant_files, user_prompt, etc.

Expanded Usage Examples

Here is how this feature would improve common development workflows:

Scenario 1: Targeted Debugging

The parent agent identifies a bug from a log file and needs to delegate the fix.

User Prompt: `` I found an error in @logs/app-error.log. Use the debugger subagent to find the root cause in @src/payment/processor.ts and suggest a fix. ``

With scoped context, the debugger subagent would immediately receive the contents of both app-error.log and processor.ts, allowing it to start analyzing the problem without having to be re-told which files to read.

Scenario 2: Test-Driven Development (TDD) Chain

A user wants to add a new feature using a two-step TDD process involving two different subagents.

Step 1 - Write Tests: `` Use the test-writer subagent to create Jest tests for the new user profile feature described in @specs/user-profile.md. ``

The test-writer subagent receives the feature spec and creates user-profile.test.js.

Step 2 - Implement Code: `` Now, use the implementer subagent to write the code in @src/user-profile.js that makes the tests in @tests/user-profile.test.js pass. ``

The implementer subagent receives both the original feature spec and the newly created test file, giving it a clear target and constraints for implementation.

Scenario 3: Refactoring with a Plan

The parent agent creates a refactoring plan and delegates the execution. This directly supports the "Explore, plan, code, commit" workflow from the best practices guide.

User Prompt: `` I've created a refactoring plan in @docs/refactor-plan.md. Use the refactor-specialist to execute Step 1 of the plan, which involves updating the files listed in the plan. ``

The refactor-specialist starts with the plan and knows exactly what to do, rather than having to re-read the plan file and parse it.

Scenario 4: Combining Declarative and Explicit Context

A subagent can have default context inheritance rules, which the user can supplement on the fly.

• code-reviewer.md frontmatter:

``yaml
---
name: code-reviewer
description: Reviews code changes.
inherit_context: [git_diff]
---
You review code diffs for quality...
``

• User Prompt:

> ``
> Use the code-reviewer subagent. In addition to the diff, please pay special attention to the security implications mentioned in our team's guide at @docs/security-guide.md.
> `
Here, the subagent would automatically receive the git diff (declarative) and also get the contents of security-guide.md` (explicit), combining the power of both approaches.

Describe alternatives you've considered

The alternative is the current state, where the user must manually re-provide all necessary context to the subagent after it's been invoked. This is cumbersome and negates many of the efficiency benefits that an agentic tool should provide.

Additional context

Implementing this feature would make subagents dramatically more powerful, enabling more sophisticated, multi-agent workflows and making Claude Code an even more effective development partner.

Thank you for considering this enhancement.