[FEATURE] VS Code Extension: Respect .claude/SUBAGENTS.md and Hide Subagent Internals

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

The Claude Code VS Code extension shows ALL subagent tool calls, file reads, and internal operations in the UI,
even when project documentation explicitly instructs to hide them.

Related Issues

• #6007 - Viewing subagent task sessions (closed as duplicate)
• #2685 - Subagent logs visibility
• #8832 - Customizable status bar with verbosity levels

Difference: Those issues wanted MORE visibility. This requests LESS (by default, with option to expand).

Current Behavior

When using the VS Code extension (version 2.0.46):

1. User requests: "Find all authentication code"
2. Main agent delegates to subagent (e.g., code-searcher)
3. Extension UI shows:

• ❌ "Using Grep tool..."
• ❌ "Reading file X..."
• ❌ "Reading file Y..."
• ❌ All grep results
• ❌ All file contents

1. Subagent returns to main agent
2. Main agent sends clean summary
3. User sees: Both verbose internals + summary (redundant and cluttered)

### Expected Behavior

The extension should respect project-level instructions in .claude/SUBAGENTS.md:

## Handling Subagent Results

What User Sees: Brief summary + next steps
What User Doesn't See: Raw search results, file dumps, verbose details

When these instructions exist, the extension should:

• ✅ Hide subagent tool calls from UI
• ✅ Show only the final summary from main agent
• ✅ Match the behavior of Claude Code CLI (which already does this correctly)

Proposed Solution

Add a new VS Code extension setting:

{
"claude-code.respectSubagentInstructions": true, // Default
"claude-code.ui.showSubagentToolCalls": false, // Hide by default
"claude-code.ui.verbosity": "minimal" // "minimal" | "normal" | "verbose"
}

Implementation Options

Option 1: Automatic Detection (Recommended)

• If .claude/SUBAGENTS.md exists with "Handling Subagent Results" section
• Automatically hide subagent internals
• Show only summaries

Option 2: Manual Setting

• User explicitly sets showSubagentToolCalls: false
• Works regardless of .claude/SUBAGENTS.md presence

Option 3: Click to Expand (Best UX)

• Show collapsed: "🔍 Code-searcher agent (2 files searched) - [View Details]"
• User clicks "[View Details]" to expand full tool calls if needed
• Similar to Issue #6007's proposal but for hiding, not revealing

Use Cases

Use Case 1: Clean Context Management

Problem: Subagent tool calls pollute conversation history
Impact:

• Session context fills up faster
• User can't find important information in clutter
• Professional appearance suffers

Solution: Hide internals → context stays 15x cleaner (see token analysis below)

Use Case 2: Team Projects with .claude/ Conventions

Problem: Many teams document in .claude/SUBAGENTS.md how agents should behave
Impact: VS Code extension ignores project conventions
Solution: Respect project documentation automatically

Use Case 3: Non-Technical Users

Problem: Technical details overwhelm non-developers
Impact: Users get confused by grep/glob/read operations
Solution: Show only actionable summaries

Benefits

1. Context Preservation (Token Efficiency)

Current: Each subagent operation adds ~13,770 tokens to context

• Full file contents stay in conversation history
• Every future message includes this baggage
• Sessions die faster

With Feature: Each operation adds ~920 tokens

• Only summary in history
• 15x more efficient
• Sessions last 10-20+ operations instead of 5-7

1. Consistency with CLI

Claude Code CLI already does this:

• Hides subagent internals
• Shows clean summaries
• Users love it

VS Code extension should match: Same UX across platforms

1. Respects Project Conventions

Many projects have .claude/SUBAGENTS.md with clear instructions:
DO NOT Dump - Never paste entire subagent response verbatim

Extension should honor these conventions.

1. Better UX

• Cleaner interface
• Less cognitive load
• Focus on results, not implementation
• Professional appearance

Real-World Example

My Project Structure:
Edvisor-Ecosystem/
├── .claude/
│ ├── SUBAGENTS.md # ← Clear instructions
│ └── agents/
│ ├── code-searcher.md
│ └── file-creator.md

From .claude/SUBAGENTS.md (lines 9-32):
## Handling Subagent Results

IMPORTANT COMMUNICATION RULE:

1. Analyze Internally - Main agent receives full response
2. Summarize Briefly - Extract key findings (2-5 sentences)
3. Highlight Actions - State next steps
4. DO NOT Dump - Never paste entire subagent response verbatim

What User Sees: Brief summary + next steps
What User Doesn't See: Raw search results, file dumps, verbose details

Current VS Code Extension: Ignores this completely ❌
Expected: Respects this automatically ✅

Alternative Solutions

Alternative 1: Global --verbose Flag

Problem: Not granular enough

• Affects ALL output, not just subagents
• No project-level control

Alternative 2: User Manually Filters

Problem: Unrealistic

• User can't filter UI in real-time
• Defeats purpose of automation

Alternative 3: Do Nothing (Current State)

Problem:

• Inconsistent with CLI behavior
• Ignores project conventions
• Poor UX for non-technical users

Priority

High - Significant impact on productivity

Feature Category

Performance and speed

Use Case Example

### Scenario: Multi-Service Codebase Exploration (Real Project)

Context: I'm working on Edvisor-Ecosystem, a monorepo with 3 services (API, Web, Mobile) totaling ~50,000
lines of code.

Task: "Find where student schedule creation happens across the entire codebase"

#### Current Behavior (With Verbose Subagent Output):

Step 1: I ask Claude Code in VS Code:
User: "Find all code related to student schedule creation"

Step 2: Extension shows ALL of this in the chat UI:
🔧 Using Grep tool with pattern "schedule.*create|create.schedule"...
📄 Found matches in 12 files
🔧 Using Glob tool with pattern "**/schedule.{js,vue,cs}"...
📁 Found 47 files
🔧 Reading api/Services/ScheduleService.cs (347 lines)...
[Full file content displayed - 347 lines]
🔧 Reading web/src/services/scheduleService.js (189 lines)...
[Full file content displayed - 189 lines]
🔧 Reading mobile/src/services/calendarService.js (120 lines)...
[Full file content displayed - 120 lines]
🔧 Using Grep in api/Endpoints/...
📄 Found 8 more files
🔧 Reading api/Endpoints/ScheduleEndpoint.cs...
[Full file content - 234 lines]
... [continues for 8 more files]

Result:

• ❌ Chat UI filled with 2,000+ lines of file contents
• ❌ Context budget consumed: 27,550 tokens
• ❌ I can't find the actual answer in the noise
• ❌ Next question I ask costs more tokens (includes all that history)

Step 3: Claude finally responds:
Assistant: "I found the schedule creation logic in 3 key locations:

• api/Services/ScheduleService.cs:145 (CreateScheduleAsync method)
• web/src/services/scheduleService.js:67 (createSchedule function)
• mobile/src/services/calendarService.js:90 (currently read-only)

The API endpoint is api/Endpoints/ScheduleEndpoint.cs:45"

But by this point:

• I already scrolled past 2000 lines of verbose output
• My session context is 75% full (only room for 3-4 more questions)
• The chat is unusable for reference

---

#### Expected Behavior (With Feature Enabled):

Step 1: I ask Claude Code in VS Code:
User: "Find all code related to student schedule creation"

Step 2: Extension shows CLEAN output:
🔍 Searching codebase with code-searcher agent...

Step 3: Claude responds immediately with clean summary:
Assistant: "I found the schedule creation logic in 3 key locations:

1. Backend (API):

• api/Services/ScheduleService.cs:145 - CreateScheduleAsync method
• api/Endpoints/ScheduleEndpoint.cs:45 - POST /api/schedules endpoint

1. Frontend (Web Dashboard):

• web/src/services/scheduleService.js:67 - createSchedule function
• web/src/components/ScheduleForm.vue:123 - Form component

1. Mobile App:

• mobile/src/services/calendarService.js:90 - Currently read-only (no creation)

Would you like me to show you the implementation details of any of these?"

Result:

• ✅ Clean, actionable answer
• ✅ Context budget consumed: Only ~920 tokens (clean summary)
• ✅ Can ask 15+ more questions in same session
• ✅ Can see conversation history clearly
• ✅ If I need details, I ask: "Show me ScheduleService.cs:145"

---

#### Impact Comparison:

| Metric | Current (Verbose) | With Feature (Clean) |
|--------|------------------|---------------------|
| Lines in chat | 2,000+ | 15 |
| Tokens used | 27,550 | 920 |
| Time to find answer | 3-5 minutes (scrolling) | 10 seconds |
| Follow-up questions possible | 3-4 | 15+ |
| Session usability | Poor | Excellent |

#### Real-World Benefit:

Before (Current):

• I spend 70% of time scrolling past verbose output
• I start new sessions every 4-5 questions (context limit)
• Non-technical team members can't use Claude Code (too confusing)

After (With Feature):

• I get immediate, actionable answers
• Sessions last entire work day (20+ interactions)
• Anyone on the team can use it (clean, clear output)

#### Optional: User Controls

If I do need to see the internals (debugging subagent behavior):
Settings → Claude Code → Show Subagent Tool Calls: true

Or, inline expansion (like #6007 proposed):
🔍 Code-searcher agent (12 files searched, 47 results) [View Details ▼]

Click "[View Details ▼]" → See full tool calls on demand.

---

### Why This Example Matters

This isn't a hypothetical scenario. This happens every single day when:

• Exploring unfamiliar codebases
• Debugging multi-service issues
• Onboarding new team members
• Answering "where does X happen?" questions

The feature would transform Claude Code from "occasionally useful but noisy" to "essential daily tool."

Additional Context

Related Issues

• #6007 - Viewing subagent task sessions (closed as duplicate)
• #2685 - Subagent logs visibility
• #8832 - Customizable status bar with verbosity levels

Difference: Those issues wanted MORE visibility. This requests LESS (by default, with option to expand).

Implementation Difficulty

Estimated Effort: Low-Medium

Why:

• UI layer already intercepts tool calls
• Just need to add conditional rendering
• Similar to how thinking blocks are collapsible
• Config reading from .claude/SUBAGENTS.md already implemented in CLI

Pseudocode:
// In VS Code extension UI layer:
function renderToolCall(toolCall: ToolCall) {
const isSubagentCall = toolCall.fromSubagent;
const hideSubagentInternals = settings.get('showSubagentToolCalls') === false;

if (isSubagentCall && hideSubagentInternals) {
return renderCollapsed(toolCall); // Or skip entirely
}

return renderFull(toolCall); // Current behavior
}

Environment

• VS Code Extension Version: 2.0.46
• Platform: Windows (but affects all platforms)
• Claude Code CLI: Already implements this feature correctly
• Token Usage Analysis (from my testing):

| Approach | Tokens per Operation | Context Added | Sessions Possible |
|----------------------|----------------------|---------------|-------------------|
| Current (verbose) | 8,480 | 13,770 | 5-7 operations |
| With feature (clean) | 15,500* | 920 | 10-20+ operations |

*Higher execution cost but way lower context pollution

Why This Matters: Clean context = longer sessions = better UX

Conclusion

This feature would:

1. ✅ Improve UX for all user types
2. ✅ Respect project-level conventions
3. ✅ Match CLI behavior (consistency)
4. ✅ Preserve context budget (token efficiency)
5. ✅ Low implementation effort
6. ✅ High user value

Current Workaround: Use Claude Code CLI instead of VS Code extension (not ideal for IDE integration)

Requested Priority: Medium-High (affects user experience significantly)