Subagents

Subagents

Subagents are read-only research workers; delegates are for editing and implementation work.

Subagent vs delegate

The code and tool descriptions draw a clear line:

• subagent: non-editing research/analysis worker; designed for background or waited-on investigation
• delegate: the path for implementation/editing work

The built-in subagent tool description explicitly says it is for investigation, code exploration, shell-backed inspection, and analysis, and that implementation/editing tasks should use delegate() instead.

Subagent-driven development

Subagent-driven development means using background research workers to reduce planner load:

• investigate code paths in parallel
• gather file lists, line numbers, and behavior notes
• summarize findings before the planner commits to a change
• keep the main chat focused on decisions

This is especially useful when the planner needs evidence from several places before choosing a direction.

Swarm investigate

The system supports a parallel read-only pattern often described as swarm investigation. The important property is that the worker set is constrained to analysis tools, not editing tools.

In the current code, the subagent tool allows a read-only tool allowlist including:

• cat
• tree
• search_pattern
• knowledge
• web
• web_search
• shell
• tasks_set
• compress_chat_probe
• compress_chat_apply
• subagent_finish

That makes it suitable for parallel exploration while keeping writes out of scope.

Background vs wait

subagent can run in two modes:

• background: default; returns immediately with a handle/result summary
• wait: blocks until the worker finishes and returns the final result

This lets a planner either fan out work and continue, or pause until the investigation is complete.

Project-defined subagents

Project-defined subagents are exposed as tools through the configuration layer. The tool implementation loads a named subagent configuration and uses its declared toolset and prompt template.

That means subagents are not just a fixed built-in idea; they are configuration-driven workers that projects can define and expose as tools.

Marketplace subagents

The marketplace supports subagent entries alongside skills and commands. The marketplace code classifies items by kind, and the bundled marketplace data includes subagent entries such as:

• research_helper
• code_explainer

So subagents can be shipped and installed through the marketplace, not only defined locally.

How this fits together

flowchart TD
  A[Planner or agent needs research] --> B[subagent]
  B --> C{wait?}
  C -- no --> D[background investigation]
  C -- yes --> E[wait for completion]
  D --> F[findings and summary]
  E --> F
  F --> G[planner decides next action]
  G --> H[delegate if editing is needed]

Loading

See also

• Agent Tools
• Marketplace