Subagents

The Developer Agent doesn’t do everything itself. When work is multi-step and delegatable, it calls the task tool (provided by deepagents’ SubAgentMiddleware) to spawn a specialist. Nine subagents ship — 8 custom + 1 general-purpose from deepagents.

The delegation contract

The LLM decides when to delegate. The task tool takes two arguments:

Argument	Meaning
subagent_type	Which specialist (debugger, tester, architect, …)
description	Self-contained brief — the subagent doesn’t see parent conversation

Multiple task calls run in parallel when the work is independent (e.g. tester and reviewer after a feature lands).

The system prompt tells the LLM: delegate when the task is complex, isolable, and would benefit from focused reasoning. Don’t delegate trivial multi-tool work or when you need to observe intermediate steps.

Subagent lifecycle

sequenceDiagram participant DA as Developer Agent participant SA as Subagent DA->>SA: task({subagent_type, description}) Note over SA: New ReactAgent<br/>role-filtered tools + own middleware loop SA->>SA: Tool calls, reasoning end SA-->>DA: ToolMessage (result) Note over SA: Destroyed

• Ephemeral — new instance per task; destroyed after result returns.
• Context-isolated — subagent never sees parent history. Only the description you write.
• Shared infrastructure — same CompositeBackend, so /workspace/ and /docs/ are visible.
• All MCP tools included — every subagent gets the full MCP tool set on top of its role-filtered core tools.
• Skills inheritance — only general-purpose inherits skills; the 8 custom subagents don’t unless explicitly configured.

The 9 subagents

Each row is one specialist. Column shape: name → focus → distinctive tools. The full tool set is filtered from the core list via ToolProvider.getToolsForRole().

Subagent	Focus	Signature tools
code-analyzer	Review, bug detection, arch analysis. Reads deeply before speaking.	ripgrep_search, get_diagnostics, search_symbols, search_vector_db
doc-writer	Technical docs, API refs, ADRs. Writes to /docs/ for cross-session persistence.	edit_file, standup_intelligence, team_graph
debugger	Root-cause via Debug Adapter Protocol. Requires an active vscode.debug session.	5× debug_* (see below)
file-organizer	Directory restructuring, moves, import path updates.	manage_terminal, ripgrep_search, git_ops
architect	System design, ADRs. Trade-off analysis.	think, search_vector_db, manage_core_memory
reviewer	Quality + security review. Read-only-ish.	get_diagnostics, search_symbols
tester	Test strategy, writing, execution, failure analysis.	run_tests, manage_terminal, browser
architecture-expert	Q&A over pre-computed static analysis. Answers first, always.	get_architecture_knowledge
general-purpose	Deepagents auto-adds. Inherits all parent tools + skills.	Everything

Debug tool cluster (debugger subagent)

Requires vscode.debug.activeDebugSession. All 5 tools return errors if no session is running.

Tool	DAP request	Purpose
debug_get_state	threads	Threads + state
debug_get_stack_trace	stackTrace	Call stack for a thread
debug_get_variables	scopes → variables	Variables in a frame
debug_evaluate	evaluate	Expression eval in a frame
debug_control	next, stepIn, continue, …	Execution flow

Architecture-expert data shape

get_architecture_knowledge queries PersistentCodebaseUnderstandingService and returns markdown by section:

Section	Data
overview	Project type, entry points, frameworks, file count
patterns	Detected architectural patterns with confidence scores
call-graph	Import graph stats, dependency hubs, cycles
middleware	Auth strategies, middleware chain, error handlers
endpoints	API routes with HTTP method + source file
models	Data models with property names
all	Everything, capped at 12 KB output

Output is bounded (5 patterns / 8 hot nodes / 15 endpoints / 10 models max) to protect the caller’s context window.

Tool role mapping

ToolProvider.getToolsForRole(role) filters the full tool list by substring match against TOOL_ROLE_MAPPING[role]. Then:

1. Appends every loaded MCP tool (all subagents get all MCP tools)
2. Deduplicates by name
3. Applies the active permission profile
4. Falls back to all non-MCP core tools if the pattern list matched nothing

Collaboration patterns

The Developer Agent’s LLM picks the sequence. Common shapes:

New feature: architect (design) → main agent (implement) → tester (verify) → reviewer (final check).

Bug fix: debugger (root cause) → main agent (patch) → tester (regression tests).

Refactor: code-analyzer (map current state) → architect (target shape) → file-organizer (move files) → main agent (rewire logic) → tester (verify).

These aren’t hard-wired workflows — the LLM decides based on the request. Independent steps run in parallel via multiple task calls in one turn.

Error handling

Layered:

1. Tool errors return descriptive strings; the subagent reasons over them.
2. Subagents have their own ReAct loop and can retry within their own turn.
3. If a subagent fails outright, the error surfaces to the Developer Agent as the task tool’s return; it decides whether to retry a different specialist, do it directly, or ask the user.
4. No automatic delegation-level retry. The LLM makes that call.

Configuration

Global toggle (defaults to true):

enableSubAgents: false;  // in ICodeBuddyAgentConfig

Per-subagent toggle via settings:

{
  "codebuddy.rules.subagents": {
    "code-analyzer": { "enabled": true },
    "doc-writer":    { "enabled": true },
    "debugger":      { "enabled": true },
    "file-organizer": { "enabled": false }
  }
}

The webview rules panel currently exposes toggles for the first four; architect, reviewer, tester, architecture-expert, and general-purpose are always on.

Related

• Architecture — where subagents sit in the whole graph
• Tools — the full role-filterable tool list
• Self-healing — how the safety guard interacts with subagents