NEWCloud agents are live.See how

Agents

Subagent

A separate agent session spawned by a main agent to handle a scoped piece of work (searching the codebase, reviewing a diff) and return only its conclusion. The point is context hygiene: the subagent burns its own window on the search and hands back the answer.

At a glance

Spawned by
A main agent, mid-task
Context
Its own fresh window
Returns
One final message
Typical jobs
Search, review, research
Main benefit
Keeps the parent's context small

How it works

The main agent decides a piece of work is self-contained, writes a short brief, and starts a new session with that brief as its only task. The subagent gets an empty context window and often a restricted tool set, for example read and search only. It runs its own loop of tool calls until it can answer, then returns a single message. Only that message lands in the parent's context.

A search that reads forty files and runs a dozen greps therefore costs the parent a few hundred tokens of conclusion instead of tens of thousands of tokens of raw output. In Claude Code, for instance, each subagent runs with its own system prompt, its own tool access, and independent permissions, configured in a small markdown file.

Why it matters

Long sessions degrade as the window fills with stale file dumps and dead ends. Subagents are the main structural defense against that inside a single task: the parent keeps its window for holding the plan and editing code. They also let one agent fan out, sending three independent questions (where is auth handled, which tests cover billing, what calls this function) to three helpers at once.

Named subagents with narrow roles are useful for consistency. A reviewer told to report only correctness bugs, or an explorer that is never allowed to edit, behaves the same way every time it is called, instead of depending on how the parent happened to phrase the request that day. The quality of the brief decides the quality of the answer, so the best briefs name files, constraints, and the exact shape of the result.

Subagent vs. parallel agents

A subagent is a helper inside one task: spawned by an agent, working for it, and reporting back to it. Parallel agents are peers, each owning a separate task end to end, usually on its own branch, with a human coordinating. Subagents manage context within one job; parallel agents multiply the jobs in flight. Each parallel agent can still use subagents for its own searches.

Example

A well-scoped subagent brief
Find every place that reads the session cookie outside src/server/auth.ts.
Search only, do not edit anything.
Return file:line references with one sentence each on what the code does with the cookie.
If you find none, list the search patterns you used.

Common mistakes

  1. Writing a brief that leans on the parent's conversation, which the subagent never sees.
  2. Trusting a "not found" answer without file paths to check, since a narrow search can simply miss things.
  3. Spawning a subagent to read one file you already know the path of, which costs more than reading it directly.

Frequently asked questions

Does a subagent share the main agent's context?

No. It starts with an empty context window plus the brief it was given, and only its final answer is passed back to the parent.

Do subagents cost more tokens?

They spend their own tokens, so total usage can rise. In exchange the parent's context stays small, which usually keeps the main session accurate for longer.

Sources

Know the words. Run the work.