In an interactive Claude Code session, why do spawned subagents run in the background, and what changes for a background subagent?
answer
- fork mode decides, not Claude
- on by default interactively since 2.1.232
- prompts surface in the main session
- smaller built-in tool set
- result arrives as a later notification
basics
~20 sFork mode, on by default in interactive sessions since v2.1.232, backgrounds every spawned subagent. A background subagent gets a smaller built-in tool set, raises permission prompts in your main session, and reports through a later completion notification.
solid answer
~40 sClaude Code picks foreground or background by rule, not by whim. With **fork mode** on, the interactive default since v2.1.232, it runs every subagent Claude spawns in the background and removes the `Agent` tool's `run_in_background` parameter, so Claude cannot ask for the foreground. Fork mode is off in `claude -p` and the Agent SDK, where Claude backgrounds by default but runs in the foreground when it needs the result first. `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` forces the foreground everywhere. In the background, a subagent keeps MCP tools but only a listed set of built-in tools, its permission prompts appear in your main session naming the subagent, a session-long grant there applies to the whole session, and its result reaches Claude as a completion notification in a later turn.
go deeper
Recall that a foreground subagent blocks you while a background one runs alongside, and that interactive sessions background spawned subagents by default.
Walk through the rule order (teammate, the disable variable, fork mode on, fork mode off) and what fork mode removes from the Agent tool.
Diagnose background surprises: tools dropped by the background filter, session-wide grants leaking into the main conversation, and results that only arrive in a later notification.
Decide where concurrency is worth interruptions and wider grants, and when a team should force the foreground for predictable, sequential runs.
## Foreground and background - A **foreground** subagent blocks the main conversation until it finishes, and its permission prompts pass straight through to you. - A **background** subagent runs concurrently while you keep working. You can watch it in the panel below the prompt or in `/tasks`, and the `Ctrl+B` shortcut moves a running task to the background. ## Who decides For each subagent Claude spawns through the `Agent` tool, Claude Code applies the first rule that fits: 1. A subagent spawned by an in-process agent-team teammate runs in the **foreground**. 2. With `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`, every subagent runs in the **foreground**, in every kind of session. 3. Where **fork mode** is on, every spawned subagent runs in the **background**, forks and non-fork subagents alike. Claude Code removes the `run_in_background` parameter, so Claude cannot request the foreground. 4. Where fork mode is off, Claude runs the subagent in the background by default and in the **foreground when it needs the result** before continuing. A definition with `background: true` stays in the background even then. Fork mode is **on by default in interactive sessions** (since v2.1.232) and **off in `claude -p` and the Agent SDK**; `CLAUDE_CODE_FORK_SUBAGENT` set to `1` or `0` overrides either default. That is why an interactive session on a current release shows subagents running in the panel while you type, and why a headless run often waits on them inline. ## What changes in the background | Concern | Foreground | Background | | --- | --- | --- | | Main conversation | Blocked until it finishes | Free while it runs | | Permission prompts | Passed through as they come | Surfaced in your main session, naming the subagent | | Built-in tools | The inherited pool, minus the tools no subagent gets | Only a listed subset, plus every MCP tool | | Result | Returned as the `Agent` tool result | A completion notification in a later turn | | API failure | Partial text with a note, or an error | Marked failed; the message names the error and keeps its last output | **Permission prompts.** When a background subagent needs approval, the prompt appears in your main session with the subagent's name. Approve it, or press `Esc` to deny that one call without stopping the subagent. A choice that lasts beyond one call, such as a grant for the rest of the session, applies to the **whole session**, the main conversation included. **Tools.** Two filters narrow a subagent's tools. The first applies to every subagent: tools such as `AskUserQuestion`, `EnterPlanMode` and `ScheduleWakeup` are removed even when listed. The second applies only in the background: apart from `Agent` and `ExitPlanMode`, which follow the first filter, a background subagent keeps every MCP tool but only these built-ins: `Read`, `Grep`, `Glob`, `LSP`, `Bash`, `PowerShell`, `Edit`, `Write`, `NotebookEdit`, `WebFetch`, `WebSearch`, `TodoWrite`, `Skill`, `ToolSearch`, `EnterWorktree`, `ExitWorktree`, `Monitor`, `TaskStop`, `SendMessage` and `Artifact`, plus `SubagentHandback` where it applies. The same definition can therefore resolve to different tools in the two modes, and the removal is silent unless the `tools` list ends up empty. Forks and resumed foreground subagents skip the background filter. Before v2.1.280, background subagents could not use `LSP`. **Results.** Claude waits for the completion notification before reporting a background subagent's results, and if you ask about progress first it says the subagent is still running. Before v2.1.211, Claude sometimes reported results for a background subagent that had not finished. ## Practical consequences - In an interactive session you can keep talking while a long bug hunt runs; expect its prompts to interrupt you, labelled by subagent name. - A grant you give a background subagent for the session also loosens your main conversation, so prefer one-off approvals when a subagent asks for something broad. - If a workflow depends on a tool outside the background list, test it as a background run, because that is what an interactive session will do. - In CI with `claude -p`, set `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` when you need strictly sequential behaviour. - When you ask Claude how a background bug hunt is going, an answer of "still running" is correct behaviour, not a hang: the results arrive with the completion notification, and `/tasks` shows the subagent's row and transcript in the meantime. - A definition's `background: true` field matters only where fork mode is off; in an interactive session on a current release, spawned subagents are already in the background.
- A background subagent asks to run `npm install`, and you choose to allow that for the rest of the session. What else does your answer affect?A choice that lasts beyond one call applies to the whole session, including the main conversation, not just the subagent that asked. If you only want that subagent's single command to run, approve it once; pressing `Esc` denies that one call without stopping the subagent.
- A subagent definition works in a `claude -p` CI job but fails in an interactive session because a tool is missing. What is the likely cause?In `-p`, fork mode is off, so Claude ran the subagent in the foreground when it needed the result, with its full inherited tool pool. Interactively, fork mode backgrounds it, and the background filter keeps only a listed set of built-in tools, silently dropping the rest. Check the tool against that list, or force the foreground with `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`.
- Claude chooses foreground or background freely in every session
- Background subagents silently auto-approve tool calls
- A background subagent has exactly the same tools as a foreground one
- Setting CLAUDE_CODE_FORK_SUBAGENT=0 forces every subagent to the foreground
- A session-wide grant given to a subagent stays scoped to that subagent
Assumes Claude Code 2.1.286: fork mode, which backgrounds every spawned subagent, has been on by default in interactive sessions since 2.1.232.