Sub-agents

The main agent calls the spawn_agent tool with an agent name and a task. That agent runs a full loop of its own on the provider and model it was configured with, never your conversation - it sees the task and the project, nothing else - and its final report comes back as the tool result. Two things it is not: it is not a second copy of your chat (nothing you said reaches it unless the main agent puts it in the task), and it is not recursive - a sub-agent can never spawn a sub-agent, that limit lives on the child's own run, and no setting relaxes it. consult_mixture, by contrast, asks a panel of models for an opinion and cannot touch files; a sub-agent does the work.

delegate edits inside a throwaway copy of your project (a git worktree). When it finishes, its diff is checked before anything reaches your files: the project's own tests run against the worktree, and the change is admitted only if it broke nothing that was passing before it started. A repo whose tests were already red does not block a correct change - Bodega records which tests were failing before the sub-agent touched anything and refuses only on new failures. A diff that fails is discarded and the report says so; it never reads like a success.

researcher runs in place, read-only. It can read your project's files and code as well as search the web, and it reports rather than edits.

Any custom agent you have marked spawnable can be named too - see Custom Agents → Running an agent on its own provider. The main agent is told which names are valid: its prompt carries a list of the built-ins and every spawnable custom agent, with the provider and model each runs on.

Settings → Agent → Sub-agents (agent.subagents_enabled, off by default). Once on, spawn_agent appears in the agent's tool list, including for smaller local models that otherwise see a reduced set.

The same group holds:

• Per-sub-agent Spend Cap (agent.subagent_spend_cap_usd, default 1) - a cloud sub-agent stops once it has spent this in one run. Your own run's cap covers the whole run, sub-agents included, and a run stopped by it says how much of the total went to them.
• Sub-agents in unattended runs (agent.subagents_headless, off) - whether a run nobody is watching (the CLI, a Loop, a background run) may spawn. bodega run --subagents turns it on for one run without changing this.
• Sub-agents may use the shell (agent.subagent_shell_opt_in, off) - only inside a worktree, only for sub-agents; lets a delegate run the project's tests itself. Output goes through the same credential scan as your own shell.

None of these can be set from a project's committed config. A cloud sub-agent is refused under air-gap, and spawning is always refused in Sidechat.

spawn_agent is a write tool: in Ask mode it pauses for your approval like any other change to files, even when the child is a read-only researcher. Three spawns per turn.

Spend is counted live, so a sub-agent's own cap can actually stop it mid-run rather than after the money is gone. On OpenRouter the live price list is fetched before any cost is recorded.

Before a local sub-agent starts, Bodega checks whether its model fits in VRAM beside the one already loaded. A foreground sub-agent may cost one swap out and back (logged). A background sub-agent that would force the runtime to swap models on every request is refused up front rather than left to thrash. Only one sub-agent on a local provider runs at a time, whatever the overall background-sessions ceiling is; cloud sub-agents run up to that ceiling. Two local models generating on one GPU is the failure these rules exist to prevent.

By default the main agent waits for the report. With background: true the tool returns started at once, the main agent keeps working, and the report arrives on a later turn - including a turn where you only ask a plain question.

A strip under the conversation shows each sub-agent while it runs. Click its chip to open a panel with the agent and model, how long it has run, what it has cost, every tool call as it happens, and its report once it finishes. What a tool returned stays on the backend; only the call itself is shown, and anything that looks like a credential is redacted.

A sub-agent that stops for a reason says which: hitting its spend or iteration cap is reported to the main agent as a reason, not as an empty result. If Bodega restarts while a background sub-agent is running, your next reply says it was lost and that none of its work was applied.

Stopping the run cancels its sub-agents within about a second and discards their worktrees; a cancelled sub-agent's changes are never applied.

Picking a custom agent from the agent dropdown is a different thing from spawning it. As the main agent it runs your conversation directly, and it runs on the provider set in its Runs on field - a DeepSeek or OpenRouter agent goes to that provider even when your active provider is a local one. Its When spawned as a sub-agent setting is ignored in that case; it only applies to a spawned run.

spawn_agent returns one of done, rejected (the diff failed verification and was discarded), no_changes, unavailable (the agent could not run - sub-agents off, air-gap, no VRAM fit, or the local concurrency rule) or started (background), with the report, the files changed and what it cost. Reports that arrive later carry the same fields.

bodega agents lists this backend's custom agents - each one's provider ("(active)" when it follows yours), model, the isolation it runs under when spawned, and whether the main agent may hand it work. --json for scripts, --all to include disabled ones.

bodega run "<task>" --subagents opts that one run into sub-agents. The two settings it flips are snapshotted before the run and put back when it ends, however it ends, so the desktop app and later headless runs are not left with sub-agents on. Pair it with --max-cost, which covers the run including its sub-agents. Without the flag an unattended run never spawns unless Sub-agents in unattended runs is on.