Run long subagents in the background and keep working

Some jobs are too long to watch. Take a pre-change pass over a codebase: the full test suite, lint, build, and a fresh audit sweep over everything you are about to disturb. On the small Express plus TypeScript payments service this course uses as its example (npm test runs six tests; npm run dev, npm run build, and npm run lint are the other scripts), that pass is quick. On a repo ten times the size, the same brief is a coffee break. The mechanics of not watching are identical at either size.

A background subagent is a subagent (a worker with its own context window that returns a summary) that runs while you keep working in the foreground. This lesson is about that second mode: how to send work there, what can and cannot reach you while it runs, and how to check on it or stop it.

Foreground blocks; background does not

The documented distinction is whether the main conversation waits. Foreground subagents block until they finish. Background subagents run concurrently while you keep working, and their results reach Claude as a completion notification in a later turn; ask about progress in between, and Claude reports the subagent is still running.

Claude Code picks the mode, and the current lean is toward background. In an interactive session, subagents typically run in the background already (fork mode, a session setting that keeps spawned subagents in the background and lets Claude hand one the whole conversation so far instead of a fresh start, is on by default there). Even where fork mode is off, background is the default, with Claude moving a subagent to the foreground when it needs its result before continuing.

Two levers stay yours regardless. Ctrl+B pushes a running task into the background, and where fork mode is off you can ask in words for background or foreground. Both are documented under run subagents in foreground or background.

Ask for the pass and you are back at the prompt immediately. The transcript line is illustrative, not captured:

> run the full suite, lint, and build, then a fresh audit sweep over
  src/ and tests/, in the background. report failures with file and
  test names, and any findings beyond the ones we already have.

  ⏵ Agent (general-purpose)  suite + audit pass   ▶ running in background

You keep drafting in the foreground while the pass churns behind you. When it finishes, the result arrives as a message in your conversation.

Prompts reach you; questions do not

Older guides describe background subagents as silently non-interactive: work that hits a permission prompt just gets denied and carries on short. That was the behavior before v2.1.186, and it is worth naming because you will still read it presented as current. It is not. When a background subagent reaches a tool call that needs permission, Claude Code surfaces the prompt in your main session and names the subagent asking.

Approve and it continues; press Esc and you deny that one tool call without stopping the subagent. An answer that outlives a single call applies to the whole session, including your main conversation.

What still cannot happen is a clarifying question. AskUserQuestion, the tool Claude uses to put a multiple-choice question to you, is filtered out of every non-fork subagent’s tool pool, foreground or background; a fork inherits the main conversation’s exact tools instead. A subagent that hits ambiguity must resolve it from the files or finish without the answer. So the failure mode has moved rather than disappeared: not work silently skipped, but work you denied with Esc, or work that finished while you were deep in something else and missed the prompt.

The preparation is a permissions habit, restated for long jobs. Pre-approve the command patterns the job will need with an allow rule, so npm test runs without interrupting you; the permissions chapter covers writing those rules. Then write the brief so no clarifying question is ever necessary: name the paths, name the rule that governs them, and say what the report should contain.

/tasks is the control surface

Work you cannot see is work you have lost track of. Seeing and stopping work you sent away is the course’s control principle - what guides execution, enforces boundaries, or allows intervention - in its most practical form. Use /tasks to see running shells and subagents: press Enter on a subagent’s row to open its transcript, and stop it from the same view. A finished background subagent stays listed briefly, marked done and sorted below running work. Ctrl+X Ctrl+K stops every running background subagent in the session, pressed twice to confirm, and it also turns off artifact auto-replies for the rest of the session. The keyboard reference documents these under interactive mode.

An illustrative view, not a capture:

> /tasks
  ▶ suite + audit pass    running    3m41s

Opening the row shows you the worker’s transcript; stopping kills it. The point of backgrounding was to stop watching. /tasks means you never lose the ability to look, or to pull the plug on a worker that is clearly off the rails.

If a job comes back short, with a denied call or a step skipped after a missed prompt, do not rerun it blind. Open its transcript from /tasks, find the step that failed, and re-brief with the fact it lacked or the permission now granted. A rerun without that diagnosis repeats the stall and pays for the reading twice.

A subagent can run alone or in parallel, in the foreground while you wait or in the background while you work, and every brief on this page has been ad hoc: typed out each time you want the audit. Next we save it as a file that runs the same way for everyone who pulls the repo.