Subagents

Your agents already delegate. Claude hands a search to its Agent tool, Codex spawns a helper, and the parent gets back a summary instead of a window full of grep output. That is the right move: a filling context window costs more per turn and reasons less sharply, and a bounded side task is the cheapest thing to push out of it.

The provider's own subagent runs headless inside the parent's process. It has to be the parent's provider, it has no pane you can look at, and when it stalls or stops on a permission question, nothing reaches you. It has no deadline you set, and its work vanishes with the turn.

rimz subagents gives your agents the same move with a full agent on the other end. The parent hands a bounded prompt to a child and keeps working; the child runs in its own pane in your room, on any provider you have configured, under a deadline, with a card nested under its parent in the sidebar. When the work ends, the pane closes, the answer comes back to the parent, and the run record and transcript stay on disk.

Your agents run rimz subagents; you mostly do not. Your part is deciding which children exist and which agent may launch which, then watching and stopping them like any other agent in the room. This page covers that part in that order. Every flag the parent uses is in the subagents reference.

What a launch does on your machine

A parent's rimz subagents codex "map the auth call path" uses the supervised background runner from the scripting guide, with the flags chosen for the parent, the child tied to it, and time reserved for reporting at its deadline. In order:

1. It checks that the caller is an agent RimZ launched and not itself a child, that the parent's profile allows this child, that the child's reporting hooks are installed and trusted, that the child would not start in your home directory (a parent started in ~ passes its home to the child; pass --cwd <DIR> or start the parent in a project), and, for a Codex child, that no folder-trust screen will block the task. An undecided project or a folder saved as untrusted refuses; a projectless folder without a saved decision passes. RimZ never changes a saved-untrusted decision: trust the folder in Codex before a supervised launch. It also checks the room's and the provider account's daily caps (budgets). A failure stops here, before a record or a pane exists.
2. It writes a durable run record under ~/.rimz/ws/<workspace-dir>/owned/runs/.
3. It opens a pane running the child's own CLI, by default in the parent's checkout and channel, whatever directory the parent's shell has moved to. The first child splits to the right of the parent's pane and later ones stack beside it; a team member's children open in a #<channel> subagents tab after its own, eight to a tab in two equal-width columns. Overflow and unavailable placement use the same companion name. On the main channel the name is <view> subagents, or subagents when the caller's view is unavailable.
4. It prints the child's petname, such as calm-fox, and returns. The parent keeps working.
5. If the child's CLI exits with an error before it opens a session, RimZ waits three seconds and launches it again in the same pane, under the same petname and deadline, up to three times (startup relaunches). A child whose parent has ended is not relaunched. The parent hears of a failure only when the last launch dies the same way, and rimz stats counts each relaunch as a Launch retry.
6. When the child's work ends, its pane closes. If it reaches its deadline, RimZ tells it to stop and report, allows three more minutes by default, then stops it and preserves its last available assistant message as a partial response. RimZ writes the first turn's non-empty response to out/<parent>/<petname>.output in the room's state directory as that child settles, even while siblings still run. Follow-up turns use <petname>.2.output, <petname>.3.output, and so on, so earlier answers stay readable. Once every child the parent launched has settled, RimZ parks one report for the parent's next turn boundary (how results come back).

Nothing else moves. The child's session file lands where its CLI always writes it, and rimz agents show @calm-fox and rimz transcript @calm-fox read the run back after the pane is gone.

Children share their parent's checkout by default. No worktree separates their edits from each other or from the parent, so give an editing child files no one else is touching, or have the parent use rimz agents -p --worktree (choose the right tool).

A researcher may need no project instructions at all. Set empty-dir: true in its definition to give it a directory of its own under ~/.rimz/empty/, keeping it in the parent's channel. RimZ uses that directory only when the child's account needs no folder-trust prompt there; otherwise it prints a notice and uses the parent's checkout. The directory survives the child's exit and is reused for follow-ups. For an explicit one-off directory, pass --cwd <DIR>, which overrides the profile setting. The child stays in the same room either way.

Give your agents children to launch

A parent can launch a bare agent kind (rimz subagents codex "...") with no profile at all. A child profile is what makes delegation deliberate: a file under ~/.rimz/subagents/ that fixes the child's model, effort, tools, and craft prompt, so the parent picks a job rather than composing a launch. Write ~/.rimz/subagents/explorer.md:

---
description: Maps the code a change will touch and reports paths, invariants, and test commands. Read-only. For wide searches the caller wants out of its window.
agent: codex
model: luna
effort: medium
tools: [Bash, Read, Grep, Glob]
---

Map the code the brief names and change nothing. Report each finding with its path and symbol.

rimz agents validate          # check every definition, subagents included
rimz subagents profiles       # what a child can be launched from

The format is the one direct profiles use (profiles), with two differences. A child profile's agent: chain stays inside subagents/, so it can build on another child profile or a kind but never on a profile from agents/. And the kind base still lives in agents/: a Codex child needs ~/.rimz/agents/codex.md exactly as a direct Codex profile does. Every key is in the definition reference.

Write the description for the parent, because it is how the parent chooses. The list RimZ gives the parent carries each profile's name and description and nothing else, since a model codename and an effort level do not tell it which child is cheaper or stronger. Say what the child does, what it will not do, and when to pick it.

Two other sources feed the same list. An [agents.commands] entry is launchable as a child, and a trusted project can ship child profiles in [subagents.profiles] of its project config, which win a name collision with yours.

Decide who may delegate

By default every agent may launch every child. A subagents: list on a direct profile narrows that:

---
description: Read code and propose a plan
agent: claude
model: fable
tools: [Bash, Read, Grep, Glob, AskUserQuestion]
subagents: [explorer]
---

Omit the field and delegation is unrestricted; subagents: [explorer] allows only explorer; subagents: [] allows none. A launch outside the list is refused before any record or pane exists, including one that re-bases a listed profile onto an unlisted one with --agent. A profile that sets any subagents: list cannot also grant the native Agent tool, so each agent delegates through one doorway or the other, and a child profile cannot set the field at all.

Every agent RimZ launches on Claude, Codex, Qwen, or Droid learns its list at launch, in the system prompt RimZ appends: the children its profile allows, with their descriptions. When the list is [], it is told to do the work itself; when nothing is configured, it is told that you enable children by adding subagents/<name>.md files. The paragraph points the agent at a skill named rimz-subagents for how to launch and collect. Other providers get no paragraph and learn their list from rimz subagents profiles, which applies the same filter when an agent runs it.

Share code navigation

A native language-server tool starts a full index for every agent and child, so a parent with three children can hold four copies of the same index over one checkout. A shared language server gives them one instead: configure it once, launch as usual, and the first query starts it if memory permits. A child joins its parent's shared server, including while dormant, and its launch reminder names it the same way. Its queries can wake that server rather than starting a private index.

Watch and answer children

A child is an agent in your room, so the sidebar treats it as one, nested one level under its parent. The parent's card gains a ⧉ subagents (N) line with what the children cost; click it to list each child with its state, the task it was given, and, while it runs, its model, tokens, and elapsed time. The parent's dollar figure already includes its children's spend.

A child that stops on a permission prompt or a question flips to ? waiting and reaches you the way any agent does: the cockpit counts it and your notification handler fires. Answer in the child's pane. Its permission mode is the one its profile's mode: sets, or the automatic-approval default every supervised run starts with, so a child with a narrow tool list rarely needs to ask.

From your own shell:

rimz subagents list              # every child in the current channel, with its parent
rimz agents show @calm-fox       # one child's activity, context, and recent transcript
rimz transcript @calm-fox        # last 20 entries, after the pane has closed too
rimz transcript @calm-fox -n 0   # the whole run

list from a shell outside any channel shows every child in the room. A child parked on a provider usage limit reads paused there while it can still resume, with the provider's message under its row. Once the park is spent, it reads failed; RUN still says running until the run ends (status reference). A reset alone does not guarantee continuation; automatic continuation depends on the configured resume policy. Channel and @all transcript views leave children out, so read a child by its handle.

A child runs one prompt and is not built to read messages mid-run. To change what a child is doing, stop it and let the parent relaunch.

How results come back

An interactive peer launched by an agent reports through the same fleet message, but keeps its pane afterward. Only its launcher's requested turns join the fleet. An open requested turn delays sibling results; a turn you type in an otherwise idle peer does not.

Each child's response file is available when that child settles, including when the parent joins it with rimz subagents wait. A child that ends a turn with its report while it still waits on something (a rimz wait, its own children) keeps that report: the file holds it, then whatever the child said after the wake. The parent does not need to poll for a report: once every child it launched has settled, RimZ parks one message for its next turn boundary:

Type: SUBAGENT_REPORT
From: @rimz
Content:
All 3 subagents settled, responses total ~5.1k tokens, 96 lines:
- @naming: completed in 4m12s, task: "map spec/profile surfaces", response: /home/me/.rimz/ws/myrepo-f89e/out/planner/naming.output (~4.2k tokens, 84 lines)
- @runtime: completed in 5m3s, task: "inspect runtime behavior", no response
- @slow-reviewer: timed out after 33m; provider did not stop, task: "review correctness", partial response: /home/me/.rimz/ws/myrepo-f89e/out/planner/slow-reviewer.output (<1k tokens, 12 lines)

The report carries status and a file path per answer, never the answers themselves, so the parent decides how much of each to read into its window. Follow-up answers get their own rows and elapsed times; an earlier answer is not lost when a child answers again before its siblings finish. A parent that needs an answer sooner joins with rimz subagents wait <petname>: only the answer it prints drops out of the report, while stopping a child dismisses all its answers. The path is the host path under every isolation; a sandboxed parent reaches it too. Every field of the report is in the reference.

While the parent rests waiting for that report, RimZ keeps its prompt cache warm with facts-only pings.

For a follow-up, the parent can use rimz message @child --wait "next question" to read the reply directly. That reply drops out of the next report; any earlier unread answer still comes back there.

A parent that is itself a supervised run (rimz agents -p, or a scheduled task) can end its turn while its children work. Its run stays open and your script keeps blocking until the report arrives and the parent finishes.

Deadlines, stopping, and cleanup

Every child has a work deadline: 30 minutes unless the parent passes --timeout, and the defaults are yours to change (subagent launches). Supported providers receive warnings six and three minutes before it, so they can finish what is in flight instead of starting another investigation. At the deadline RimZ asks the child to stop and report. Three minutes later, a child still running is stopped and reports as timed out, with its last available assistant text marked as a partial response. The room enforces that limit whether or not anyone is waiting. Warning and stop delivery depend on the provider's hooks; the deadline reference lists support and overrides.

A child that stops on a provider usage limit is not finished. While its park can resume, it has not failed and reads paused in rimz subagents list; a spent park reads failed (status reference). Its run stays open until the deadline, and its parent gets one SUBAGENT_PAUSED message naming the child and the provider's error, so the parent can wait for the reset, stop the child, or relaunch the task on another provider (reference). The parent's card parks too. If you enable auto-continue, it resumes the child, not a parent whose card is paused only because of that child.

A launched child silent past the stall window shows ! with silent Nm under its parent and stops counting as the parent's work, so the parent shows its own status. The parent gets one SUBAGENT_STALLED message naming the child. RimZ never stops a child because it is silent; the deadline and explicit stop still apply (notice and once-per-run rule).

To stop a child yourself, stop it like any agent. The parent's report lists it as canceled:

rimz agents stop @calm-fox

Stopping a parent, with rimz agents stop or rimz teams stop, stops its live children first. A parent that ends any other way takes its children with it: each child watches its parent and cancels itself when the parent's session ends, and the room sweeps up any child still running ten minutes after its parent ended.

A child launched with --detach is fire-and-forget: it stays out of the report, the parent is never held waiting for it, and it keeps working after the parent exits. Its pane closes when it finishes, and rimz subagents wait <name> still reads its answer if the parent wants it after all. Stopping the parent still stops it.

A child launched with --keep is the other exception. Its pane stays open after it finishes and after its parent exits, for you to read; it closes when the parent runs rimz subagents stop, when you stop the parent, or when you close the pane by hand.

What remains after a child ends is its run record under ~/.rimz/ws/<workspace-dir>/owned/runs/ and the session file its CLI wrote, so rimz agents show and the parent's rimz subagents wait still read the outcome. The answer files outlive the room; rimz gc removes one once it is 7 days old and no run record names its agent, and rimz reset --hard at once. A child has no restart or resume command. Its parent can continue an ended child's session by messaging it, where the provider supports resuming. Beyond that and the startup relaunches, RimZ does not relaunch ended work: to run the task again, the parent launches the same profile and prompt. Rebirth recovery restores root agents but not children, and reports a child whose run was cut off as canceled to its parent.

Children cannot delegate

A child does its assignment itself. RimZ refuses any rimz agents, rimz teams, or rimz subagents launch from a child, tells the child so in its prompt, and switches off the provider's own delegation where it has a verified switch: Claude's Agent tool is denied, Codex's multi_agent feature is off, and OpenCode's delegation permission is denied (an agent-specific allow in your OpenCode config can override it). Other providers get the instruction only.

That keeps delegation one level deep. A parent's children are the whole family, the sidebar shows them all under one card, and stopping the parent reaches every one. For the same reason [agents] max-chain-length does not count subagent launches; it limits agents launching peers, below.

Choose the right tool

• A provider's own subagent is right for a quick lookup you never need to see. It is fast, runs inside the parent's process, and costs no pane.
• rimz subagents is right for a bounded task you want visible or durable. Reach for it when the task should run on another provider, needs a deadline, might stop to ask you something, or produces a result worth keeping after the turn.
• rimz agents -p from an agent is right when the child needs a control subagents leaves out. A separate worktree, --stdin, --verify, and --retries are there (scripting). The result is an independent peer with its own top-level card, joined with rimz agents wait, and it counts toward the launch chain, which stops at three successive agent-started launches by default (max-chain-length). A background peer left unjoined still comes back in the parent's report. To replace your own session rather than delegate, use rimz agents molt: it keeps the generation and is unavailable to subagents.
• A team is right when the work needs rounds. A child answers once and is finished; team members keep their windows open and talk back and forth.
• rimz message is right when the task belongs to an agent already running. It hands the work over without starting a fresh turn.

See also

• Subagents CLI: every flag the parent uses, the fanout task format, the report fields, and the pane placement rules.
• Definition reference: every key a child profile accepts, and the subagents: list rules.
• Scripting: the supervised run every child is, and the rimz agents -p peer launch.
• Sidebar: how children render under their parent's card.
• Subagents internals: parentage, the watchdog, and how the report is composed.