Skip to main content
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:
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, and use the web. It cannot access hardware by default.
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 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 parent session, and the subagent waits until you answer.
  • Approving lets the tool proceed. Rejecting aborts the subagent’s turn.
  • 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 the exception: it stays denied regardless of approvals and is governed only by the hardware toggle below.

​
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 start without hardware access. They cannot access hardware, including 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 capabilities they received at creation. When enabled, hardware requests share the parent’s devices and wait until the board is free.
The hardware toggle applies only to general subagents. Read-only specialist subagents never receive hardware tools.
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.

​
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.
Embedder excludes hardware commands from automatic backgrounding. A hardware script run holds its device lease in the foreground unless you ask for a background run. See Hardware scripts.

​
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

Agent Teams have been removed. The /agent-team command and --agent-team flag no longer exist, and approved plans no longer include a team structure. Use parallel subagents instead:
  • 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.
Last modified on September 19, 2026