[DOCS] Subagent tools frontmatter missing Task(agent_type) syntax for restricting sub-agent spawning

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Available tools" subsection under "Control subagent behavior"

Current Documentation

The tools frontmatter field is documented as an allowlist of tool names:

To restrict tools, use the tools field (allowlist) or disallowedTools field (denylist): ``yaml --- name: safe-researcher description: Research agent with restricted capabilities tools: Read, Grep, Glob, Bash disallowedTools: Write, Edit --- ``

The "Disable specific subagents" section documents Task(subagent-name) syntax but only in the permissions deny array context:

You can prevent Claude from using specific subagents by adding them to the deny array in your settings. Use the format Task(subagent-name) where subagent-name matches the subagent's name field.

There is no mention of using Task(agent_type) syntax within the tools frontmatter field itself.

What's Wrong or Missing?

Changelog v2.1.33 added support for restricting which sub-agents can be spawned via Task(agent_type) syntax in agent tools frontmatter. This means subagent authors can now control which sub-agents their subagent is allowed to spawn by including entries like Task(Explore) in the tools allowlist.

For example, a subagent that should only be able to spawn Explore sub-agents could declare:

tools: Read, Grep, Glob, Task(Explore)

This capability is not documented anywhere. Users who want to build hierarchical agent configurations with controlled sub-agent spawning cannot discover this syntax.

Suggested Improvement

In the "Available tools" section, after the existing tools/disallowedTools example, add documentation explaining:

• The Task(agent_type) syntax can be used in both tools and disallowedTools fields
• When used in tools (allowlist), it restricts which sub-agents the subagent can spawn
• When used in disallowedTools (denylist), it prevents the subagent from spawning specific sub-agents
• Include an example showing a subagent that can only use read-only tools and spawn Explore sub-agents

Also add a cross-reference from the "Disable specific subagents" section, noting that the same Task(name) syntax works in frontmatter tools/disallowedTools fields in addition to the permissions deny array.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/sub-agents | "Available tools" section — tools field examples only show regular tool names |
| https://code.claude.com/docs/en/sub-agents | "Disable specific subagents" section — only shows permissions deny array, not frontmatter |

Total scope: 1 page affected (2 sections)

Source: Changelog v2.1.33

Added support for restricting which sub-agents can be spawned via Task(agent_type) syntax in agent "tools" frontmatter