Claude Code Agent Teams made me rethink what a “subagent” actually is

I've been digging into how Claude Code Agent Teams works internally, and I initially thought it was mostly a more structured way to run subagents in parallel. But after looking at the spawning, shared task board, and messaging model, I think there's a more fundamental distinction: A teammate isn't just a subagent. It can be a first-class interactive agent. A normal subagent is basically delegation: ┌────────────┐ │ User │ └─────┬──────┘ │ ▼ ┌────────────┐ │ Main Agent │ └─────┬──────┘ │ delegate ▼ ┌────────────┐ │ Subagent │ └─────┬──────┘ │ result ▼ ┌────────────┐ │ Main Agent │ └────────────┘ Subagent = Delegation The user talks to the main agent. The subagent is mostly an implementation detail: receive a task, do some work, return the result. Agent Teams can look quite different: ┌────────────┐ │ User │ └──────┬─────┘ │ ▼ ┌────────────┐ │ Lead Agent │ └──────┬─────┘ │ ┌────────────────┼────────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Research │ │ Coding │ │ Testing │ │ Agent │ │ Agent │ │ Agent │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ └────────────────┼────────────────┘ ▼ ┌─────────────────────┐ │ Shared Task Board │ │ task/status/owner │ └──────────┬──────────┘ │ ┌─────────────────────┐ │ Mailboxes │ │ agent ↔ agent msgs │ └─────────────────────┘ Teammate = Collaboration Some teammates can even be separate Claude Code processes running in their own terminal panes. They don't just return a result upward. They can: - see the same shared tasks - claim work - own tasks - communicate with other teammates - receive direct assignments - continue finding new work - maintain their own agent/session lifecycle And this creates another interesting possibility: the user can interact with an individual teammate directly. Imagine the Research Agent has spent 15 minutes investigating the wrong hypothesis. With hidden subagents, the interaction is: User ↓ Lead ↓ “Tell Research Agent to stop X and investigate Y” ↓ Research Agent But if teammates are first-class sessions: User ───────────────► Research Agent “Stop investigating the updater. I've already ruled that out. Check the installer rollback path.” The team can still work autonomously 95% of the time. But when human intervention is useful, you can enter the relevant agent instead of routing everything through the lead. So I'm starting to think these are actually two useful abstractions: Subagent - short-lived - delegated task - hidden by default - result flows back to parent Teammate - longer-lived - owns work - communicates with peers - first-class session - optionally interactive with the user Which leads to the UI question I'm currently thinking about for my own desktop coding agent: Option A Project └── Main Agent ├── hidden subagent ├── hidden subagent └── hidden subagent Option B Project ├── Lead Agent ├── Research Agent ← can open ├── Coding Agent ← can open └── Testing Agent ← can open │ └── Shared Task System My current preference is actuI've been digging into how Claude Code Agent Teams works internally, and I initially thought it was mostly a more structured way to run subagents in parallel. But after looking at the spawning, shared task board, and messaging model, I think there's a more fundamental distinction: A teammate isn't just a subagent. It can be a first-class interactive agent. A normal subagent is basically delegation: ``` ┌────────────┐ │ User │ └─────┬──────┘ │ ▼ ┌────────────┐ │ Main Agent │ └─────┬──────┘ │ delegate ▼ ┌────────────┐ │ Subagent │ └─────┬──────┘ │ result ▼ ┌────────────┐ │ Main Agent │ └────────────┘ ``` **Subagent = Delegation** The user talks to the main agent. The subagent is mostly an implementation detail: receive a task, do some work, return the result. Agent Teams can look quite different: ``` ┌────────────┐ │ User │ └──────┬─────┘ │ ▼ ┌────────────┐ │ Lead Agent │ └──────┬─────┘ │ ┌────────────────┼────────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Research │ │ Coding │ │ Testing │ │ Agent │ │ Agent │ │ Agent │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ └────────────────┼────────────────┘ ▼ ┌─────────────────────┐ │ Shared Task Board │ │ task/status/owner │ └──────────┬──────────┘ │ ┌─────────────────────┐ │ Mailboxes │ │ agent ↔ agent msgs │ └─────────────────────┘ ``` **Teammate = Collaboration** Some teammates can even be separate Claude Code processes running in their own terminal panes. They don't just return a result upward. They can: - see the same shared tasks - claim work - own tasks - communicate with other teammates - receive direct assignments - continue finding new work - maintain their own agent/session lifecycle And this creates another interesting possibility: the user can interact with an individual teammate directly. Imagine the Research Agent has spent 15 minutes investigating the wrong hypothesis. With hidden subagents, the interaction is: ``` User ↓ Lead ↓ "Tell Research Agent to stop X and investigate Y" ↓ Research Agent ``` But if teammates are first-class sessions: ``` User ───────────────► Research Agent "Stop investigating the updater. I've already ruled that out. Check the installer rollback path." ``` The team can still work autonomously 95% of the time. But when human intervention is useful, you can enter the relevant agent instead of routing everything through the lead. So I'm starting to think these are actually two useful abstractions: **Subagent** - short-lived - delegated task - hidden by default - result flows back to parent **Teammate** - longer-lived - owns work - communicates with peers - first-class session - optionally interactive with the user Which leads to the UI question I'm currently thinking about for my own desktop coding agent: **Option A** ``` Project └── Main Agent ├── hidden subagent ├── hidden subagent └── hidden subagent ``` **Option B** ``` Project ├── Lead Agent ├── Research Agent ← can open ├── Coding Agent ← can open └── Testing Agent ← can open │ └── Shared Task System ``` My current preference is actually a hybrid: Default to A. Allow the user to expand into B when they need it. Simple tasks remain simple. Complex tasks can gradually become a visible team. For people actually using Agent Teams: do you ever want to jump into a teammate and talk to it directly, or should all human interaction always I've been digging into how Claude Code Agent Teams works internally, and I initially thought it was mostly a more structured way to run subagents in parallel. But after looking at the spawning, shared task board, and messaging model, I think there's a more fundamental distinction: A teammate isn't just a subagent. It can be a first-class interactive agent. A normal subagent is basically delegation: ``` User | v Main Agent --delegate--> Subagent ^ | +-------- result ----------+ ``` **Subagent = Delegation** The user talks to the main agent. The subagent is mostly an implementation detail: receive a task, do some work, return the result. Agent Teams can look quite different: ``` +------------+ | Lead Agent | +-----+------+ +-----------+-----------+ | | | v v v Research Coding Testing Agent Agent Agent \ | / +----------+----------+ +------------------+ | Shared Task Board| +------------------+ +------------------+ | Mailboxes | +------------------+ ``` **Teammate = Collaboration** Some teammates can even be separate Claude Code processes running in their own terminal panes. They don't just return a result upward. They can: - see the same shared tasks - claim work - own tasks - communicate with other teammates - receive direct assignments - continue finding new work - maintain their own agent/session lifecycle And this creates another interesting possibility: the user can interact with an individual teammate directly. Imagine the Research Agent has spent 15 minutes investigating the wrong hypothesis. With hidden subagents, the interaction is: ``` User -> Lead -> Research Agent "Stop X; investigate Y" ``` But if teammates are first-class sessions: ``` User -----------------> Research Agent "Stop X; investigate Y" ``` The team can still work autonomously 95% of the time. But when human intervention is useful, you can enter the relevant agent instead of routing everything through the lead. So I'm starting to think these are actually two useful abstractions: **Subagent** - short-lived - delegated task - hidden by default - result flows back to parent **Teammate** - longer-lived - owns work - communicates with peers - first-class session - optionally interactive with the user Which leads to the UI question I'm currently thinking about for my own desktop coding agent: **Option A** ``` Project └─ Main Agent ├─ hidden subagent ├─ hidden subagent └─ hidden subagent ``` **Option B** ``` Project ├─ Lead Agent ├─ Research Agent <- can open ├─ Coding Agent <- can open └─ Testing Agent <- can open └─ Shared Tasks ``` My current preference is actually a hybrid: Default to A. Allow the user to expand into B when they need it. Simple tasks remain simple. Complex tasks can gradually become a visible team. For people actually using Agent Teams: do you ever want to jump into a teammate and talk to it directly, or should all human interaction always go through the lead agent?go through the lead agent?ally a hybrid: Default to A. Allow the user to expand into B when they need it. Simple tasks remain simple. Complex tasks can gradually become a visible team. For people actually using Agent Teams: do you ever want to jump into a teammate and talk to it directly, or should all human interaction always go through the lead agent?