ktg-plugin-marketplace/plugins/ultraplan-local/skills/cc-architect-catalog/subagents-reference.md

name	description	layer	cc_feature	source	concept	last_verified	ngram_overlap_score	review_status
subagents-reference	CC subagents — how the Task tool spawns isolated agent instances with scoped tools and context.	reference	subagents	https://docs.claude.com/en/docs/claude-code/sub-agents	task-tool-delegation	2026-04-18	null	approved

Subagents — Reference

Subagents are fresh Claude instances spawned via the Task tool. Each receives a task prompt, a tool subset, and no memory of the parent conversation except what the parent explicitly passes. They return a single final message to the parent.

Anatomy

A subagent has:

• A name — either a built-in type (general-purpose, Explore, Plan) or a plugin-defined type (code-reviewer, test-runner, ...).
• A system prompt — defined by the agent type. The parent cannot override it.
• A tool set — subset of the parent's tools, as declared in the agent definition's frontmatter tools: field.
• A task prompt — what the parent asks it to do. Self-contained; the subagent has no access to prior messages.
• A model — either explicit in the agent definition (model: opus | sonnet | haiku) or inherited from the parent.

How to define a subagent

A plugin agent is a markdown file in agents/ with frontmatter:

---
name: code-reviewer
description: <when to invoke, include examples>
model: sonnet
tools: ["Read", "Grep", "Glob"]
---

<system prompt content>

The description field is how Claude decides when to spawn this subagent. Include concrete trigger examples.

How to invoke

Parent calls the Task / Agent tool with:

• subagent_type — the agent's name
• description — short label for logs
• prompt — the self-contained task

Optional:

• run_in_background: true — agent runs in the background; parent is notified on completion.
• isolation: "worktree" — agent runs in a temporary git worktree (isolated copy of the repo).

Return protocol

• Foreground agent: parent blocks until the agent returns. Return value is a single text message.
• Background agent: parent continues. On completion, the harness injects a notification into the parent's next turn.

Isolation guarantees

• No conversation history sharing. Each subagent starts cold.
• Separate context window. A subagent can read large files without polluting the parent's context.
• Separate tool permissions. A subagent with only Read tools cannot write files, even if the parent can.

Cost and latency

• Every subagent call is a full model call with its own token budget.
• Model choice matters: Sonnet is ~5× cheaper than Opus; Haiku is cheaper still but cannot be used (per project policy).
• Parallel subagents: the parent can launch multiple in one message; the harness runs them concurrently. Total latency ≈ slowest agent.

Failure modes

• Subagent hits context limit → partial or missing return.
• Subagent runs in background and the parent conversation ends → result may be orphaned.
• Subagent's return message hallucinates file paths → caller must verify.