[DOCS] Agent tool security guidance omits indirect prompt injection from subagent-read content
Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/tools-reference
Section/Topic
The Agent tool behavior section, especially the description of what a parent conversation receives from a subagent and the security implications of content the subagent reads.
Current Documentation
The Agent tool behavior section currently says:
The Agent tool spawns a subagent in a separate context window. The subagent works through its task autonomously, then returns a single text result to the parent conversation. The parent doesn't see the subagent's intermediate tool calls or outputs, only that final result.
The security page defines prompt injection generally and lists safeguards, but its guidance for untrusted content only says:
Best practices for working with untrusted content: 1. Review suggested commands before approval 2. Avoid piping untrusted content directly to Claude 3. Verify proposed changes to critical files 4. Use virtual machines (VMs) to run scripts and make tool calls, especially when interacting with external web services 5. Report suspicious behavior with /feedback
What's Wrong or Missing?
Claude Code v2.1.210 hardened the Agent tool against indirect prompt injection through content read by a subagent. The user-facing documentation does not identify this threat model or explain the corresponding safety boundary.
The current Agent tool description emphasizes that the parent receives only the subagent's final text result, but does not warn that files, search results, command output, or other material read by the subagent can contain instructions aimed at manipulating the agent or its parent. It also does not explain whether the returned result should be treated as untrusted content, how the mitigation affects the parent conversation, or which user approvals remain authoritative.
The security page discusses prompt injection and untrusted content in general terms, but does not connect those protections to delegated subagent work. Users who ask an Agent subagent to inspect an untrusted repository or fetched content therefore have no documentation for the specific indirect-injection risk addressed in v2.1.210.
Suggested Improvement
Add a security note to Agent tool behavior and cross-reference it from the security page. Document, using precise implementation-approved wording:
- That content a subagent reads can contain indirect prompt-injection instructions, including content from files, command output, or external sources.
- That v2.1.210 adds defenses for this Agent-tool path and what those defenses do and do not guarantee.
- How the parent conversation should interpret subagent results and distinguish reported content from instructions.
- That content read by a subagent cannot grant permission, approve an action, or override the user's instructions and permission settings.
- Recommended precautions when delegating work over untrusted repositories or web content, such as limiting subagent tools and reviewing proposed actions and changes.
Avoid implying that the mitigation makes arbitrary untrusted content safe; retain the existing warning that no system is immune to all attacks.
Impact
Medium - Makes feature difficult to understand
Additional Context
The v2.1.210 change concerns the boundary between a delegated subagent's tool-read content and the parent Agent-tool conversation. The related documentation should be kept consistent across these pages:
Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/tools-reference | 90-114 | Agent tool behavior, subagent results, and permission boundaries |
| https://code.claude.com/docs/en/security | 36-85 | Prompt-injection protections and untrusted-content practices |
| https://code.claude.com/docs/en/sub-agents | 827-845 | Subagent context contents and delegated work |
Total scope: 3 pages affected
The relevant behavior was hardened in v2.1.210.