# Subagents and Background Tasks

[Docs](https://www.rightnowai.co/docs) / [RightNow Agent](https://www.rightnowai.co/docs/agent) / [Subagents and Background Tasks](https://www.rightnowai.co/docs/subagents)

Updated 2026-10-11

> **Release status**
>
> RightNow Agent, the terminal coding agent, is paused. Its guides stay online as reference.

Subagents run delegated tasks in child sessions with their own context while the parent conversation continues.

## Delegate with spawn\_subagent

The `spawn_subagent` tool starts a child session with a focused prompt, a short description, and an agent type. By default, it runs in the background and returns a subagent ID; set `background: false` to block until the child finishes.

Give the parent a focused task with the files, context, and result you need. To collect a background child's result, ask the parent to read it with `get_command_or_subagent_output` and the subagent ID, or watch the child in the [Tasks pane](https://www.rightnowai.co/docs/subagents#tasks-and-todos) (`Ctrl+G`).

**Subagent types**

| Agent type | Use |
| --- | --- |
| general-purpose | Full-capability work that may read, edit, and execute under its permissions. |
| explore | Read-only file investigation, directory listing, and search. |
| plan | Codebase exploration followed by a structured implementation plan, without file edits or shell commands. |

## Spawn reference

**Spawn arguments**

| Argument | Behavior |
| --- | --- |
| prompt | Required. The full task instructions for the child. |
| description | Required. A short task label of 3-5 words. |
| subagent\_type | Selects the child type; defaults to general-purpose. |
| background | Runs in the background and returns a subagent ID; defaults to true. |
| capability\_mode | Filters tool classes: read-only, read-write, execute, or all. Omitted values use the resolved agent and role configuration. |
| isolation | Requests none for a shared workspace or worktree for edits kept separate until explicitly merged. |
| resume\_from | Continues a completed child from the current parent session with the same agent type. Its transcript, tool state, and model carry forward. |
| cwd | Uses an existing directory. Do not combine it with worktree isolation; a resumed child keeps its source directory. |
| model | Selects an available model slug when the user requests one; ignored when resuming a child. |

The requested capability mode is intersected with the agent definition and role limits; it cannot widen their tool access. `read-only` removes built-in file-edit and shell tools; `read-write` adds file changes, and `execute` adds shell commands without file-edit tools. Tools without a classified kind, including MCP tools, are retained by this filter.

Worktree isolation copies the working tree, including uncommitted and untracked files. Files are copy-on-write clones where the file system supports it and full copies elsewhere, such as NTFS on Windows. If the worktree cannot be created, the child runs in the shared workspace. Manage worktrees from [Sessions](https://www.rightnowai.co/docs/sessions).

### MCP inheritance

Children inherit already-connected parent MCP servers by default, including plugin agents. Set `mcpInheritance` in the agent frontmatter to change that.

**MCP inheritance values**

| mcpInheritance | Inherited servers |
| --- | --- |
| all (default) | Every connected parent server. |
| none | No parent servers. |
| named: \[server\] | Only the named parent servers. |
| except: \[server\] | All parent servers except the named ones. |

## Configuration and limits

Keys live in `config.toml`; the values shown are the defaults.

**Subagent settings**

| Setting | Effect |
| --- | --- |
| \[subagents\] enabled = true | false or RIGHTNOW\_SUBAGENTS=0 disables subagents; the interactive TUI honors it only when started with --no-subagents, except in leader mode, where the leader process applies it. |
| \[subagents\] max\_depth = 1 | Only the top-level session spawns; set 2 or more to allow deeper nesting. |
| \[subagents\] max\_concurrent = 32 | Concurrent non-workflow subagents per session; additional spawns queue. |
| \[subagents\] limit\_behavior = "queue" | "fail" rejects excess spawns instead of queuing. |
| \[subagents.toggle\] <type> = true | false disables that agent type; omitted types remain enabled. |
| \[subagents.models\] <type> | Maps a type to an available model ID; without one, the child uses the parent model. |

## Tasks and todos

**Task and todo panes**

| Shortcut | Pane |
| --- | --- |
| Ctrl+G | Tasks, in fullscreen and inline modes: subagents, background commands, monitors, loops, statuses, elapsed time, and task IDs. In minimal mode, Ctrl+G edits the prompt in an external editor. |
| Ctrl+T | Todos: the current task's separate todo list. |

## Background commands

A command launched through `run_terminal_command` with `background: true` returns a task ID immediately. Press `Ctrl+B` to move an already-running foreground command into the background.

**Task and todo tools**

| Tool | Purpose |
| --- | --- |
| get\_command\_or\_subagent\_output | Read current output and status, optionally waiting up to a timeout (capped at 10 minutes by default). |
| wait\_commands\_or\_subagents | Wait for any or all of up to 20 task IDs. |
| kill\_command\_or\_subagent | Stop a command, monitor, or subagent, or report that it already exited. |

## Monitor and scheduled loops

### Real-time events with monitor

The `monitor` tool runs a long-lived script and turns stdout and stderr output into rate-limited notifications. Blank or suppressed lines do not produce notifications. Filter noisy output and use line-buffered pipes. A monitor ends after `timeout_ms` (default and maximum 10 hours); `persistent: true` keeps it for the life of the session until it is killed. 30 seconds of sustained overload also stops it.

### Periodic checks with /loop

**Text**

```text
/loop 5m Check whether the test suite passes
```

Intervals use seconds, minutes, hours, or days (`60s`, `5m`, `2h`, `1d`). The minimum is 60 seconds. A loop fires immediately, expires after 7 days, and is managed through the scheduler tools. By default, each run executes in a detached background subagent; `[scheduler] background_loops = false` runs it in the conversation instead.

## Scheduler tools

**Scheduler tools**

| Tool | Arguments and result |
| --- | --- |
| scheduler\_create | Creates a recurring prompt from interval and prompt; returns its ID and readable schedule. |
| scheduler\_list | Lists active task IDs, shortened prompts, intervals, and next fire times. |
| scheduler\_delete | Pass id to cancel a schedule; use the kill tool for a running command, monitor, or subagent. |

- `durable`, `foreground`, and `fire_immediately` default to false. Durable tasks persist across sessions; foreground tasks run in the main conversation.
- Pass `task_id` to update the interval or prompt of an existing schedule; omitted fields stay unchanged.
- One-shot scheduler tasks are rejected: `recurring: false` is not supported.
- At most 50 scheduled tasks can be active at once.

## Personas

A persona layers tone, output format, task focus, model, reasoning effort, isolation, and declared input or output contracts onto a subagent without changing its agent type.

Open `/personas` to manage personas, or `/config-agents` to open the full Agents and Personas modal. Project personas live under `.rightnow/personas/*.toml`; user personas live under `<RIGHTNOW_HOME>/personas/*.toml` in the effective product home. RightNow Agent 1.0.5 loads project personas without a folder-trust check, so review a repository's `.rightnow/personas/` before running RightNow in it.

> **Troubleshooting**
>
> If a task cannot start, run `rightnow doctor` and follow the [Troubleshooting guide](https://www.rightnowai.co/docs/troubleshooting).

## Related guides

- [Agent dashboard](https://www.rightnowai.co/docs/dashboard)
- [Plan mode scope](https://www.rightnowai.co/docs/plan-mode#read-only-scope)
- [MCP servers](https://www.rightnowai.co/docs/mcp)
- [Configuration](https://www.rightnowai.co/docs/configuration)

## Previous

[Plan Mode](https://www.rightnowai.co/docs/plan-mode)

## Next

[Agent Dashboard](https://www.rightnowai.co/docs/dashboard)