Subagents

A subagent is a second agent that the agent starts for part of a task. It gets a brief the agent writes, does that work on its own, and reports back. The agent decides when one helps, and you can ask for them: "Use subagents to review each package."

A subagent lives inside its chat. For work that needs a chat of its own (its own worktree, machine or model, or work that outlasts the conversation), one of your agents starts a whole chat instead.

A subagent:

• starts with a fresh context: it sees its brief, not your chat
• works in the same project with the same tools, on the chat's model and effort unless you choose another (its model)
• works in Ask when the chat is in Ask
• can't start subagents of its own or save to memory

Waited on or not

Every subagent is the same kind of run, with the same row, the same chat of its own and the same controls. The one difference is whether the agent waits for it:

A message you steer into the chat while the agent waits for a subagent ends the wait, not the subagent: the agent reads your message within moments, and the subagent goes on as one it doesn't wait for. A message queued for the next turn leaves the wait as it is.

When a subagent the agent didn't wait for finishes, the chat shows Subagent finished (or Subagent failed) and its report goes to the agent: at its next step if it's working, or in a turn of its own if the chat is idle. The agent then tells you what came back.

Its model and effort

A subagent runs on the chat's model and effort, the ones the chat has when it starts (an effort you changed while the chat's turn ran counts). To put subagents on another model, ask for it in the chat by the name the model menu in the message box shows, with an effort if you want one, such as high. The agent picks a model only when you ask. It can choose from the models your account runs now, the ones that menu lists. A model that can't run now (signed out, not on your plan, its plan used up) isn't started: the agent hears which models run now and tells you. When its provider is signed out or doesn't offer it and another provider serves the same model, it runs there instead, unless that provider is billed per token, such as an API key: then the agent hears the exact model to ask for and tells you, and it runs there only when you ask (When a model can't run). Another effort alone works too: "Run it on low effort."

The effort goes to the nearest level the model has. A model chosen without an effort takes the chat's, the same way switching models in the message box keeps it. A subagent that is still running keeps its model: a follow-up the agent sends it can't move it to another.

A subagent started without a model or effort follows the chat. While it runs, a change of the chat's effort reaches it at its next request, moved to the nearest level its model has; a change of the chat's model waits until it next waits or parks, since moving a running subagent would throw away its cache. Each time it runs again (the agent continues it, you continue it from its row or its chat, it goes on after a plan wait or a restart), it takes the chat's model and effort as they are then, so switching the chat's model moves its subagents along at their next run. Its own conversation says where the model changed, the way a chat's does. A subagent you put on a model or effort keeps it every time it runs again, until you ask for another, or for the chat's ("same as yours"), which makes it follow again.

To change the default, open Settings › Chat › Subagents: Subagent model is Same as the parent unless you pick one, with its effort on the slider under the models. A project can have its own in its settings, Subagents: Use the default follows Settings. What you ask for in the chat wins over both.

Agents without asking, in the same group, is how many agents one turn may start before a card asks you: its subagents, and the chats an agent starts or steers. A workflow run that wants more asks too. It is 24 unless you change it.

A subagent on another model spends that model's plan, and Usage counts it there. If that model fails while the subagent works, the subagent stops: it doesn't move to the chat's model on its own. Continue picks it up when the model is back, and its chevron continues it on another.

A subagent on the chat's model and effort says nothing about it at rest. One on another model shows that model and effort on its row and in the sidebar; hover it to see what the parent runs and why it differs. Its opened chat names its model and effort either way, where a chat shows its model.

Follow a subagent

Each subagent is one row in the chat: a mark, its title, what it is doing in plain words, and how long it has run. The subagents the agent starts together share one block, in the order they started; past six, the last line reads And 4 more.

• While it works, the row says what it is doing now, such as Looking through 4 files, Running a command or Thinking between steps. It never shows a tool's name or a path.
• Once it finishes, a check and the first sentence of its report.
• When it fails, its mark turns into a red alert mark and the row says why, such as Couldn't reach the provider.
• When it waits out a spent plan, the row says when it Goes on by itself; one cut short by a restart says Interrupted, kept its context. Such a row shows Continue on at rest: its main part names the move (Continue on its own model, or Continue on MODEL), its chevron the other models a subagent can run now. In a narrow row the line fades first, then the control keeps only Continue on and its chevron.

Click a row to open it in place: its report, the files it changed by name, and a line that counts its steps, such as 17 files read, 13 commands, 21 searches. Click that line for its steps in order, such as Read store.ts, Looked through 6 files or Ran 3 commands, the one it is on last. Its commands, what they printed and every result are in its chat: Open. To see what the agent asked of it, choose Brief from the parent in the row's ⋯.

Hover a row (or move to it with the keyboard) for Open and Cancel, and ⋯ for Brief from the parent, Open, Copy report, Stop waiting and Cancel, each where it applies. On a touch screen or in a narrow window, ⋯ shows all the time.

While subagents work, they also show under the chat's row in the sidebar (an agent's main chat: under the agent), three at most, then how many more are working; one that waits out a spent plan stays there on a hollow ring. One that ends shows its mark a moment and leaves, so a long chat's row stays one line plus what runs now. While its subagents work after its own turn has ended, the chat's row keeps its working mark.

Nothing under the message box repeats them. Scrolled away from their rows, open a subagent at work from its line in the sidebar, or press ⌥⌘↓ for the one that needs you, else the latest at work.

Every subagent of the chat keeps its row in the chat where it started: one that ends, waits or is cut off changes its mark and its line, never its place. In a chat with an agent, they also nest under the agent's row while they run. Search's Work filter (⌘K, then ⌘] twice) lists a chat's subagents by day, the ones that ended included.

Click a row's Open, or its row in the sidebar, to open that subagent.

Open a subagent as a chat

Click Open on its row, or click its row in the sidebar. The run fills the main pane as a chat of its own, and the top bar shows the path back up to the chat that started it: the brief first, then every step as it happens, a web search its model's provider runs included. Its steps open as the chat's do: an edit to its diff, a command to its output. An older run that didn't keep them says Diff not kept for this run or Output not kept for this run instead. The top bar's last step names it, with its mark and how long it has run; its message box reads Message this subagent, and while it works the send button is its stop square. Click the chat's name in the top bar, or press ⌥⌘↑, to go back up: the chat opens where its row was, and the row glows once. ⌥⌘← and ⌥⌘→ step to the subagents beside it; Esc leaves the page as it is. The run keeps its own address, so leaving the chat, reloading or following a link opens it again with every step it took.

While a subagent runs, you can message it from there. It reads your message at its next step, in its own context, never the agent's. If a plan limit cuts it off before that step, the message is kept: it reads it once when it continues.

Stop a subagent

• Cancel on its row, or the stop square in its opened chat, stops one subagent. When the agent was waiting for it, the agent hears that it was stopped and carries on with the rest of its turn.
• Or ask the agent: "Stop the audit." It stops that subagent itself, and stops one on its own when it replaces it with another.
• While a turn runs, the chat's stop button opens a menu: Stop this turn keeps its subagents working, Stop this turn and 2 subagents (or how many) stops them too. Esc never stops a subagent: it ends the running turn only.

Continue a subagent

A subagent cut off before it finished keeps its whole context: by a spent plan, a provider failure, a restart, its time limit, Cancel or Stop. Its row says why it stopped, such as Stopped, and when a spent plan resets. A lost connection doesn't cut it: it shows Waiting for the network, its parent is told it waits rather than failed, and it goes on by itself on the same model once the network answers, with the time it waited not counted against its time limit.

• Continue, on its row or in its opened chat, picks it up where it stopped. Its chevron continues it on another model, at an effort you pick; the run keeps that model, and hovering its model on the row reads You moved it.
• In its opened chat, type a message: the subagent continues with it.
• The agent can continue one too, with its whole context. Ask it: "The plan reset, continue the audit." The agent continues one you stopped only when you ask it to.
• The agent continues a subagent only for that subagent's own work. New work, even in the same area, goes to a new subagent, since a continued one carries its whole context into every request. The agent sees how full a subagent's context is when it starts, continues or hears from one.
• Ask for more while a subagent works on it, and the agent sends your ask to that subagent instead of starting another: it reads it at its next step, and its one report covers both. The chat shows Sent to and the subagent's name, which takes you to its row.

What a subagent keeps to continue from stays for 7 days after its last step, and goes once its chat is archived or deleted. Continuing one after that says it kept nothing to continue from (the agent is told to start a new subagent), and its transcript still opens. A subagent still running, or one in a workflow that is still going, keeps it.

A subagent the agent doesn't wait for, cut off by a spent plan, a provider that keeps failing or a lost connection to it, waits instead and continues on its own once its plan answers again: its row says it Goes on by itself at the time its plan resets (hover it for the model it waits for), and its chat's row shows a clock in place of its dot (it lists under Running, never Needs you). It goes on from where it stopped, on the same model. When the wait is half an hour or longer, the agent hears of it once: which subagent, its model, why it waits and until when, and the call that continues it now on another model that is open. It decides as you would: it moves the subagent when the work can't wait, and otherwise leaves it waiting and hears again when it finishes. A workflow agent's wait reaches the chat whose agent launched the run the same way. In a chat with fallback models (or one set to wait at a spent plan), it goes on on the first of them that is open, in order (the chat's own model first, then its fallback models), at once if one is open, else on the first to open; a plan that reopens within a minute or two is waited out, not skipped. Such a move doesn't stick: each time it runs again, and at a later request once an earlier model is open again, it goes back to the first open one, and one started while the chat's own model is spent starts there. One that follows the chat follows a switch of the chat's model while it waits: it goes on at once on the new model, or waits for that model's plan if it is spent too. Continue on, on its row and in its opened chat, moves it now to a model a subagent can run now (the chat's fallback models first; a model whose provider is failing, whose plan is used up on the account the chat uses, that runs in chats only, or that refused subagents lately, isn't offered, and Lookout refuses one that closed meanwhile with why), from where it stopped; Try now, last in its menu, goes on at once on the same model. Stop waiting, in the row's ⋯ and in its opened chat, leaves it interrupted, for Continue later. A wait gives up after a day without an answer.

A subagent the agent doesn't wait for that Lookout's restart cut off, with nothing to continue it, starts a turn in its idle chat, so the agent hears about it and can continue it. Any other subagent cut off by a plan limit, a sign-in or a lost connection, and one whose wait you stopped, doesn't start a turn in an idle chat: the agent hears about it with your next message. Until it is continued, its row keeps a still mark and Continue. Editing an earlier message removes the subagents that the turns after it started and that have ended.

Multitask

With Multitask on in Agent mode, the agent sends substantial requests to subagents it doesn't wait for, instead of working on them in the chat. It starts one subagent per request as a rule, and several only for parts that are independent of each other; a quick request it still answers itself. You can keep asking while they work. Reports arrive as each one finishes, and the agent puts them together when several make one answer. Modes shows how to turn Multitask on and off.

Limits

• A chat runs up to 8 subagents the agent doesn't wait for at once, and all chats together up to 32. Past that, a new one doesn't start: the agent waits for one to finish, or runs the work in a subagent it waits for.
• Up to 3 subagents the agent waits for run at the same time.
• A subagent the agent waits for moves to the background after 10 minutes and keeps working; the agent hears its report when it ends.
• A subagent the agent doesn't wait for pauses after two hours of working time or 8 hours in all. Its commands count as working time, and so does waiting on one (a build, a test run); time it waits for its plan or the network to answer doesn't. When 80% of its working time is gone, it is told how many minutes are left and to write its report; when its steps run long, it is told earlier, up to 60%. When its time is up, the step it is on stops the way Stop stops it: a reply it was writing is cut off, and a tool still running stops and keeps what it printed so far. A command is the exception: it moves to the background and keeps running, and a wait on one just ends. Then it gets one last reply with its tools off, which becomes its report. It keeps its whole context, and the agent hears its budget beside the time it worked (such as "stopped at its 3 min working-time budget after 3 min 12 s") and can continue it. Its commands still running pass to the agent, which hears each one's shell id and can wait for it or stop it. A short provider rate limit is waited out, not an end; if its time runs out during the wait, it still gets its last reply. When a subagent ends any other way, the commands it left running in the background stop with it.
• A subagent keeps the folder its commands last moved to, across a restart and when it continues; so does the chat.