[DOCS] Sub-agents docs missing background agent completion notification content and output file path #31683

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Background agent completion and result retrieval section (currently absent)

Current Documentation

sub-agents.md extensively documents how to define subagents (YAML frontmatter, memory, tools, examples), but contains no documentation about:

• What background agent completion notifications contain
• That notifications include an output file path
• How parent agents retrieve results from completed background agents
• What happens to results after context compaction

agent-teams.md mentions:

"Idle notifications: when a teammate finishes and stops, they automatically notify the lead."

No details about notification content or output file paths.

interactive-mode.md documents Ctrl+F to kill background agents but nothing about completion notification content.

What's Wrong or Missing?

A changelog fix reveals that background agent completion notifications include an output file path, and that this path is the mechanism parent agents use to recover agent results after context compaction:

"Fixed background agent completion notifications missing the output file path, which made it difficult for parent agents to recover agent results after context compaction"

This reveals several undocumented behaviors:

1. Background agent notifications include an output file path — the completion notification sent to the parent agent contains a path to a file holding the agent's output.
2. This file path is how parent agents recover results after context compaction — when the parent agent's context is compacted, the output file path in the notification is the recovery mechanism.
3. The output file path was previously missing — users experiencing context compaction in long multi-agent sessions would have found their parent agent unable to locate subagent results.

None of this recovery mechanism is documented. sub-agents.md explains how to define and invoke subagents but not how to access their results, especially after context compaction.

Suggested Improvement

Add a section to sub-agents.md covering background agent result retrieval:

## Accessing background agent results

When a background agent completes, it sends a completion notification to
the parent agent. The notification includes:

- A summary of the agent's final response
- The path to an output file containing the agent's full results

**After context compaction:** If the parent agent's context has been
compacted, the output file path in the notification is the primary way
to recover the agent's results. Reference the file path directly in
follow-up prompts if needed.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

Total scope: 2 pages affected

Source: Changelog v2.1.71

Exact changelog entry:

"Fixed background agent completion notifications missing the output file path, which made it difficult for parent agents to recover agent results after context compaction"