> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subagents and background tasks

> Delegate isolated investigations to child agents, run long shell commands and subagents as durable background tasks, and steer or stop them mid-run.

Embedder delegates work to subagents. A subagent handles one delegated investigation or task in its own child session and reports back to the parent conversation. Long shell commands and subagents share one background task model: each gets a task ID, keeps running across turns, and can be inspected or stopped from the same task view.

## 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:

```txt theme={"system"}
Use subagents to inspect the boot sequence, linker layout, and flash scripts.
Run the independent investigations in parallel and report the evidence by file.
```

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. For read-only subagents, that approval covers the actions taken inside the child session. A general subagent additionally asks for the same confirmations the parent session would.

### 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, use the web, and use hardware tools. You can turn hardware access off with `/subagent-hardware`.

The first four types are read-only. A general subagent can write inside the project workspace. It cannot create more child agents or ask you questions. Give it enough context to resolve ambiguity without rediscovering the parent session's work.

### Approvals inside a general subagent

A general subagent follows the same [tool approval rules](/core-concepts/approvals) as the parent session:

* Shell commands on your approvals allowlist run without asking.
* Any other shell command, file write, or path outside the project raises the normal confirmation card. The card appears in the main chat, labeled with the subagent's name, and the subagent waits until you answer. See [Approvals from subagents](/core-concepts/approvals#approvals-from-subagents).
* Approving lets the tool proceed. Rejecting without a reply aborts the subagent's turn; in VS Code you can reply with what to do instead, and the subagent continues.
* Your `allowOutsideProject` grants apply, so a trusted toolchain directory outside the project works in a subagent without extra prompts.

This means a delegated task can run build and test commands such as `npm run build` or `bun test`. The command asks for confirmation exactly as it would in the main session instead of being refused. Hardware access is governed separately by the hardware toggle below. When the toggle is off, hardware calls stay denied regardless of approvals.

### Runtime limits

A subagent has no fixed runtime limit. It runs until it finishes, you stop it, or the parent turn is cancelled. Embedder treats a subagent that produces no activity for an extended period as stalled and stops it.

## Run subagents in the background

For long work that the parent does not need immediately, Embedder can start a general subagent in the background. The dispatch returns a task ID immediately, the subagent keeps working after the turn ends, and Embedder inserts its result into the parent conversation when it finishes.

A background subagent keeps a durable identity. Embedder can:

* Check its status and read its latest progress.
* Send it a message to steer the current turn or start a follow-up turn on the same child session.
* Interrupt it without destroying the child session or its transcript.

You can stop a background subagent from the background task view, or ask Embedder to stop it by task ID. A stop you issue directly is sticky: Embedder cannot restart that subagent until you release the stop.

## Control subagent hardware access

General subagents have hardware access by default. They can use hardware tools and run hardware commands through the shell. Every hardware request goes through the same lease queue as the parent session and other subagents. One agent drives a board at a time, and the others wait until the board is free.

Toggle hardware access off or back on with:

```txt theme={"system"}
/subagent-hardware
```

The setting affects newly spawned general subagents only. Existing children keep the capabilities they received at creation. The setting is not saved, so each new Embedder session starts with subagent hardware access on. When hardware access is off, a general subagent cannot access hardware, including through shell commands, and reports the hardware step back to the parent session.

A parent session and its subagents wait on each other's turns. If a call would queue behind a long-lived activity held by a related session, such as a debug server or a background hardware task, Embedder refuses the call instead of waiting. The refusal names the session holding the board and the activity. Stop that activity or let it finish, then retry, or leave the hardware step to the session that holds the board.

<Warning>
  The hardware toggle applies only to general subagents. Read-only specialist
  subagents never receive hardware tools.
</Warning>

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. Avoid leaving a debugger or background hardware task running in the parent while a subagent needs the same board.

## Long shell commands become background tasks

Shell commands use the same task model as subagents. When Embedder runs a command:

1. Embedder registers the command as a task and captures its output to a log file from the start.
2. Embedder observes the command in the foreground for one minute.
3. If the command finishes within that window, Embedder returns the result inline.
4. If it is still running, the same process moves to the background without restarting, and Embedder receives its task ID.

A backgrounded command continues until it completes or you stop it. Embedder reports completion to the conversation automatically, so it does not need to poll or sleep while it waits. The full log stays on disk, and Embedder reads newer output incrementally when it checks the task.

Commands started explicitly in the background, such as dev servers, watchers, and log followers, skip the observation window and detach immediately.

<Note>
  A hardware command keeps the board leased to its session until the command
  exits, including after it moves to the background. Flash commands and
  commands that disconnect serial monitors always stay in the foreground. See
  [Hardware scripts](/debug-mode/hardware-scripts).
</Note>

## View and manage background tasks

The background task view lists every running and finished task in the session: backgrounded shell commands and background subagents. Open it in the terminal UI with `/background`.

From the conversation, ask Embedder to:

* List the running background tasks.
* Report the status or latest output of a task by ID.
* Stop a task. Stopping a shell task terminates its process tree. Stopping a subagent interrupts its turn but keeps the child session and transcript.

## Parallelize with subagents

For ad hoc parallel work, use subagents:

* Dispatch several read-only subagents in one message when you have independent questions. They run concurrently.
* Use a general subagent for an autonomous implementation task, in the foreground or the background.
* Keep tightly coupled edits in the parent session.

Use a read-only subagent when you need evidence or a plan without file changes. Use a general subagent when the task should write files or run commands on its own.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.