Agent Tool

What is the Agent Tool, and how does it differ from a regular tool call?

The Agent tool is a special built-in Claude Code tool whose job is to spawn a Subagent — a new Claude instance with its own independent Context Window. This differs from a regular tool (like reading a file or running a command): a regular tool call finishes and its result returns directly into the current context, while an Agent tool call kicks off an entirely separate conversation flow with its own System Prompt, tool list, and permission settings, only returning a result summary to the caller once it finishes.

This tool was originally called Task, and was officially renamed to Agent in Claude Code v2.1.63. The rename happened because the original name was easily confused with a separate internal task-tracking system (the Task* family of features). Official documentation and the current version now use Agent consistently, but existing config files or hook scripts using Task(...) still work as an alias — they don't break just because of the rename.

Why does the Agent Tool exist, and what problem does it solve?

A standard conversation has a fixed-size Context Window, and in a long, multi-step task, the output accumulated from exploratory file reads and code searches keeps consuming context space, diluting the information that actually matters. The Agent tool provides a mechanism for isolating that noise away — work that generates a lot of intermediate process gets handed off to a Subagent to complete in its own independent context, and the main conversation only receives the refined result.

This also explains why the tool needs to be designed separately from regular tools, with its own name: what it does isn't simple information retrieval — it kicks off an entire independent execution branch. That branch needs its own permission controls (for example, restricting a particular subagent to read-only access) and its own model choice (assigning a cheaper model to handle exploratory work), capabilities that a regular tool doesn't have.

What does the Agent Tool actually look like in practice, and what are its limits?

When the main agent calls the Agent tool, it specifies which Subagent type to spawn (like general-purpose or a custom subagent's name) along with a task description. The subagent starts with its own clean context, not inheriting the main conversation's history, and returns a result summary once it finishes its task.

A subagent can also call the Agent tool itself to spawn a further layer of subagents, but this nesting capability has a depth limit — the current default is three layers below the main conversation. Once a subagent hits that depth limit, the Agent tool is removed from its tool list, so it has to finish the remaining work itself and return a summary rather than extending downward indefinitely. This depth limit can be adjusted via an environment variable, and setting it to 1 disables nesting entirely. There's also a special variant called a "fork," which inherits the main conversation's full history directly instead of starting from a clean context — but a fork itself can't call the Agent tool to spawn a further layer.

Understanding how the Agent Tool works — how does this actually help me using Claude Code?

If you see Task(...) syntax in a config file, settings.json, or a custom hook script, there's no need to worry it's outdated — this is an officially preserved alias that behaves identically to writing Agent(...), and continuing to use it won't cause problems. It's just that new configs are better written with the current name, Agent, so they match the documentation going forward.

If you're designing a custom Subagent or writing a hook script that intercepts tool calls, there's one thing worth watching for: a script that hardcodes a string comparison against "Task" when checking the tool_name field may break after the rename, since the actual value passed in is now "Agent". Scripts like this are better off checking for both names, or using the current official permission-rule syntax (like Agent(agent_type)) to restrict which subagent types can be spawned, rather than hand-rolling your own string-matching logic.