Feature Request: Scoped Context Passing for Subagents

[coygeek]

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:

  ---
  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.

[nitsanavni]

I suggest to also be able, as an additional option, to start the sub agent with full context from original session, this will allow to 1. preserve context 2. leverage context caching.

This will make the sub agent behave like a dedicated fork of the thread.

[mrsions]

To make this feature more intuitive and consistent, I’d like to propose a configuration syntax similar to how tools: is defined. For example:

tools: Read, Write, Bash
includes: System, User, Project, Subagent

Descriptions:

• System: Inherit the parent agent’s system prompt (mandatory if core logic requires it)
• User: Include user-level memory (personal context/history)
• Project: Include project-level memory (project history and context)
• Subagent: Use independent, persistent memory scoped to this subagent

This approach would:

• Provide clear, declarative configuration for what context is passed
• Prevent unnecessary token usage
• Keep the setup consistent with the existing tools syntax
• Support both lightweight isolated agents and full-inheritance workflows

I think merging this syntax idea into the scoped context proposal would make the feature even more powerful and developer-friendly.

[github-actions[bot]]

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.

[danieldrasin]

I'd sure like to open this one back up (system says it was auto closed).

I need this big time. I have this problem in a lot of areas, but a very specific (and high value example): 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 unavoidably 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...)

[awrobel-gd]

@danieldrasin exactly. Claude Code doesnt have the manual "cache_control" parameter to be used, like direct API has.

I replaced subagents with just parallel code that starts multiple calls to Anthropic API. For example. first message - push the assembled common context. Mark it with "cache_control". Create more messages now in parallel (this replaces spawning subagents) and make them reuse that context and hit 97%+ cache.

Exactly my case that only some subset of typical work we do requires subagents and its very efficient. For others, stick to running parallel code yourself but manually control context and caching - without agent. Or maybe agent only in some part of that requires flexibility