[DOCS] Document subagent auto-compaction behavior (compactMetadata and preTokens) #16944

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

https://code.claude.com/docs/en/sub-agents#performance-considerations

Current Documentation

No mention of auto-compaction for subagents. To the contrary, most info on the web says agents can't compact, and Anthropics doesn't mention anywhere that they do.

What's Wrong or Missing?

Documentation Request

Feature to Document

Subagents (Task tool) appear to support auto-compaction, but this is not documented anywhere.

Evidence

In Claude Code v2.1.1, I observed auto-compaction occurring within a subagent transcript (agent-{agentId}.jsonl):

Log entry (line 305):

{
  "isSidechain": true,
  "agentId": "a2223d9",
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

Observed behavior:

• Pre-compaction context: ~167K tokens
• Post-compaction context: ~27K tokens (83% reduction)
• isCompactSummary: true message injected after compaction
• Subagent continued working successfully after compaction

Current Documentation Gap

The subagents documentation states:

"Each subagent operates in its own context"

But does not mention:

• Whether subagents support auto-compaction
• The compactMetadata log field format
• The compact_boundary system message subtype
• How compaction affects cache efficiency in subagents

Requested Documentation

Please document:

1. Whether subagent auto-compaction is an intended/supported feature
2. When auto-compaction triggers for subagents (threshold)
3. The log format for compaction events (compactMetadata, isCompactSummary)
4. Any differences between main agent and subagent compaction behavior

Why This Matters

Understanding subagent compaction is critical for:

• Designing long-running agent workflows
• Estimating costs (cache invalidation after compaction)
• Monitoring context usage in orchestration systems
• Deciding whether to scope subagent tasks tightly or allow them to run longer

Environment

• Claude Code version: 2.1.1
• Platform: macOS

Suggested Improvement

Indicate that subagents follow the same compaction rules that the main agent, or specify what are the compaction rules and provide an indication of the reserved compaction buffer.

Impact

High - Prevents users from using a feature

Additional Context

No response