Skip to main content
Subagents and Agent Teams move work into separate agent contexts, but they solve different problems:
  • A subagent handles one delegated investigation or task and reports back to the parent conversation.
  • An Agent Team runs an approved implementation plan with up to three workers editing disjoint paths in parallel.

​
Use subagents for isolated work

Ask Embedder to delegate work when an investigation would consume substantial context or when several independent questions can run at the same time:
Each subagent runs in a child session with its own context. You can open that session to watch or steer it. Dispatch requires your consent, and that approval covers the actions taken inside the child session.

​
Subagent types

  • codebase-explorer reads and searches the codebase.
  • document-explorer searches uploaded hardware documentation and datasheets.
  • web-searcher researches current information on the web.
  • planning-agent reads the project and prepares an implementation plan.
  • general can read, search, edit files, run shell commands, and use the web. It cannot access hardware by default.
The first four types are read-only. A general subagent has a 30-minute runtime limit and cannot create more child agents or ask you questions. Give it enough context to resolve ambiguity without rediscovering the parent session’s work. For long work that the parent does not need immediately, Embedder can start a general subagent in the background. The result is inserted into the parent conversation when it finishes. You can stop it from the background task view.

​
Control subagent hardware access

General subagents start without hardware tools. They are also instructed not to reach devices through shell commands. Toggle hardware access with:
You can also start Embedder with:
The setting affects newly spawned general subagents only. Existing children keep the tool set they received at creation. When enabled, hardware requests share the parent’s devices and serialize through the hardware lease queue.
The hardware toggle does not grant hardware to read-only specialists or Agent Team workers. It applies only to the general subagent type.
Target one named device or port in the delegated task. A child that holds a monitor or debugger should release it promptly so the parent and other children can continue.

​
Use Agent Teams for parallel implementation

Agent Team execution is disabled at the start of a session. Enable it with:
Or launch Embedder with:
Enabling the feature does not launch workers. It allows an approved Plan mode workflow to include an Agent Team structure.

​
Plan and launch a team

1

Enable Agent Teams

Run /agent-team before planning the change.
2

Enter Plan mode

Ask Embedder to divide the work only when files can be owned independently.
3

Review the team plan

Each worker must have an ID, a title, a goal, one or more owned paths, and explicit success criteria. A plan can contain one to three workers.
4

Approve the plan

Embedder stores the structured team plan beside the approved Markdown plan.
5

Run the plan

After switching to Act mode, the first mutating action launches the approved team. The agent can read briefly before launch, but it cannot edit files or run shell commands first.
6

Integrate and verify

The parent agent reviews all worker results, resolves cross-worker issues, and runs the final checks.

​
Worker boundaries

Agent Team workers run concurrently in the same project workspace. They do not receive separate worktrees. Each worker can:
  • Read any project file needed for context
  • Search code, documents, schematics, and the web
  • Read project memory
  • Load an available skill
  • Write or edit only its approved paths
Each worker cannot:
  • Write outside the project
  • Write a path owned by another worker
  • Run shell commands
  • Access hardware, serial, flashing, trace, plots, or debuggers
  • Delegate again or ask you a question
File ownership is checked before the run. File scopes and directory scopes must stay inside the project and cannot overlap. A worker has a ten-minute execution limit. The Monitor shows the team, each worker’s current action, owned paths, changed files, output preview, and final status.

​
Choose the right execution model

Use a read-only subagent when you need evidence or a plan without file changes. Use a general subagent for one autonomous task that does not need a pre-approved multi-worker file split. Use an Agent Team when all of these conditions hold:
  • The implementation has two or three independent path groups.
  • Each group has a clear completion check.
  • Workers can make progress without shell commands, hardware, or user input.
  • The parent can integrate and verify the combined result after the parallel run.
Keep tightly coupled edits in the parent session. Overlapping ownership, shared generated files, and migrations that require ordered steps do not fit the Agent Team execution model.
If a team worker fails, Embedder preserves the workspace changes and returns control to the parent. It does not silently replace the failed team with ordinary subagents.
Last modified on August 24, 2026