How Subagents Work
When the agent spawns a subagent, it selects one of the available subagent profiles and chooses whether the subagent should run in the foreground or background. Subagents can run in two modes:Foreground
Runs inline in your session. The parent agent pauses and waits for the subagent to finish before continuing. You can approve or deny tool calls as they come up.
Background
Runs in parallel while the parent agent continues working. The parent is automatically notified when the subagent completes. Unapproved tools are automatically denied.
You do not see the subagent’s raw output directly. When a subagent finishes, the parent agent reads the result and summarizes the key findings and actions for you.
Subagent Profiles
Each subagent runs with a specific profile that determines its capabilities:| Profile | Description | Tool Access |
|---|---|---|
subagent_explore | Read-only codebase exploration and research | Read-only tools only (regardless of foreground or background) |
subagent_general | General-purpose tasks including code changes | Full tool access (foreground) or pre-approved tools only (background) |
The agent automatically chooses the appropriate profile based on the task. Explore subagents are ideal for research and understanding, while general subagents can make changes.
Tool Permissions
How tool permissions work depends on whether the subagent is running in the foreground or background:- Foreground subagents behave like the main agent — you are prompted to approve or deny tool calls as usual.
- Background subagents inherit any tool permissions you have already granted during the current session. Any tool that has not been pre-approved is automatically denied. Background subagents cannot prompt you for new permissions.
Monitoring Subagents
Subagent Indicator
When background subagents are running, an indicator appears below the input area showing their status. You can navigate to the indicator by pressing ↓ from the input area, then press Enter to open the subagent panel. When a foreground subagent is running, the spinner displays “Subagent running · Ctrl+B to run in background”.Subagent Panel
The subagent panel lets you view and manage all active and completed subagents. It shows each subagent’s profile, title, status, elapsed time, and tool call count. Selector mode (when multiple subagents exist):| Key | Action |
|---|---|
| ↑ / k / Shift+Tab / Ctrl+P | Navigate up |
| ↓ / j / Tab / Ctrl+N | Navigate down |
| Enter | View selected subagent |
| f | Move background subagent to foreground |
| x | Cancel a running subagent |
| Esc / Ctrl+C | Close the panel |
| Key | Action |
|---|---|
| f | Move background subagent to foreground |
| x | Cancel a running subagent |
| Esc / Ctrl+C | Go back to selector (or close if only one subagent) |
Foreground / Background Switching
You can move subagents between foreground and background while they’re running:- Background a foreground subagent: Press Ctrl+B while a foreground subagent is running. The subagent continues working in the background, and the parent agent resumes.
- Foreground a background subagent: Open the subagent panel and press f on a running background subagent. The subagent’s output will display inline.
When you move a subagent to the background, the parent agent’s tool call has already returned, so the parent continues independently. The subagent’s result won’t feed back into the parent’s current pipeline, but you’ll be notified when it completes.
Cancelling Subagents
You can cancel a running subagent in two ways:- From the subagent panel: Open the panel and press x on a running subagent.
- Foreground subagent: Press Ctrl+C or Esc to cancel the currently running foreground subagent.
Resuming Subagents
Cancelled, failed, or completed subagents can be resumed with a new prompt. You can ask the agent to resume a subagent, and it will continue where it left off. Resumed subagents always run in the foreground, so you can approve any tool calls that were previously denied. This is especially useful when:- A background subagent failed because a required tool was denied — resume it in the foreground to grant the necessary permissions.
- A subagent completed but you want it to do additional follow-up work based on its findings.
- A subagent was cancelled prematurely and you want it to continue.