Shared Tasks & Messaging

Learn

Tasks as a Coordination Primitive

In Agent Teams, tasks are the central unit of work distribution. The lead creates tasks, and the teammates work through them. Each task follows a simple lifecycle:

pending  -->  in_progress  -->  completed

• pending: The task is waiting to be picked up by a teammate
• in_progress: A teammate has claimed the task and is working on it
• completed: The task is finished, and the result is ready

Dependencies Between Tasks

Tasks can depend on each other. This is crucial for workflows where a specific order must be maintained:

Task A: "Implement API endpoint"          [no dependency]
Task B: "Write tests for API"             [depends on Task A]
Task C: "Create API documentation"        [depends on Task A]

In this example, Tasks B and C can only start when Task A is completed. As soon as Task A switches to completed, B and C are automatically released -- and can be worked on in parallel by different teammates.

File Locking in Detail

When a teammate wants to claim a task, the following happens:

1. The teammate attempts to acquire a lock on the task file
2. If the lock succeeds: Status is set to in_progress, teammate ID is recorded
3. If the lock fails: Another teammate was faster -- the current one looks for the next available task

This optimistic locking prevents race conditions without requiring a central coordinator. Each teammate can independently pick tasks from the queue.

Direct Agent-to-Agent Communication

In addition to the task list, there's a mailbox system for direct communication:

message(recipient, content) -- Message to a specific teammate:

"Hey test-writer, the API got an additional parameter 'format'.
Please account for that in the tests."

broadcast(content) -- Message to all teammates:

"Attention: The database schema migration was just executed.
Please pull the latest version."

Messages are not delivered in real time. Instead, each agent checks their mailbox during every tool-call cycle. This means: A message typically arrives within a few seconds, but not instantly.

Understand

Known Limitations

Agent Teams are in active development. These limitations are known as of May 2026:

1. No session resume for in-process teammates: When you end the session, the teammate contexts are lost. Only the lead can be resumed with /resume.

2. Task status can be stale: Since the task list is file-based, a teammate may briefly see a stale status. File locking prevents duplicate processing, but the display can be briefly inconsistent.

3. Shutdown can be slow: When you end the session, all teammates must be cleanly shut down. With many running tasks, this can take several seconds.

4. One team session per lead: You cannot run multiple teams simultaneously from one lead session. For multiple teams, you need multiple terminal sessions.

5. No nested teams: A teammate cannot spawn their own teammates. The hierarchy is flat: Lead --> Teammates. If a teammate wants to delegate a subtask, they use classic subagents.

When Tasks, When Messages?

The rule of thumb:

• Tasks for plannable work: "Implement feature X", "Write tests for Y"
• Messages for unexpected situations: "Attention, interface has changed", "Do you need help?"

Tasks are the main coordination axis. Messages are the emergency channel for everything that doesn't fit into the plan.

Reflect

The combination of task list and messaging gives Agent Teams enough structure for plannable work and enough flexibility for unforeseen situations. In the next section, we'll look at concrete practice patterns and clarify when Agent Teams make more sense than subagents.