Skip to content

Agents and delegation ​

Orchestrate agents across providers from one Rho parent session. Each agent can bind its own provider and model on the Rho runtime, or hand a delegated child to the Claude Code runtime so it can use your Claude subscription while Rho keeps fan-out, attach, cancel, and the session tree.

Rho uses one agent definition model for interactive sessions, rho run, and delegated work. The built-in catalog contains:

  • default - standard root coding-agent behavior
  • explorer - fast read-only investigation
  • reviewer - code review and verification; it can run shell commands (diffs, targeted tests) but is instructed never to change code or repository state
  • worker - independent implementation

The reviewer's shell commands follow the permission mode. Bypass runs them unchecked, so only the reviewer's instructions keep it from changing code or repository state. A child started with the agent tool cannot ask for approval, so Auto sends each command to the classifier, and Allow edits, Supervised, and Plan deny them; the reviewer then falls back to its read tools. Workflow agents differ: an interactive rho workflow run asks in the terminal under Allow edits and Supervised, and Plan still denies them. Because it has a shell, reviewer cannot back a read_only workflow node; use explorer or a workflow-local agent there.

Select an agent at startup:

bash
rho --agent reviewer
rho run --agent worker "address the issue"

Agent switching within an active session is intentionally unsupported.

Unknown frontmatter keys and invalid values make a definition invalid. Rho skips that file and lists it in /agents; the rest of the catalog still loads. The field contract is on definition schema. Runtimes and attachment are on Claude Code, Cursor, Antigravity, and attachment and artifacts.

Use /agents create or /create-agent to define an agent through a guided questionnaire. Use bare /agents to inspect the loaded catalog. Press Enter on an internal agent, or on a Rho-runtime agent from an Agent Plugin, to set its model override. Press Enter on an agent loaded from ~/.rho/agents or a trusted project .agents/agents directory to edit its definition, or press Delete to remove it after confirmation. Frontmatter fields use structured TUI controls, while the prompt body opens in $VISUAL or $EDITOR. Review the draft and choose Save to validate and write the source file. Agents loaded from ~/.agents/agents, Agent Plugins, workflows, and built-ins remain read-only; press Enter on one to read its full prompt. A Rho-runtime plugin agent shows its full prompt in the detail pane instead, since Enter sets its model.

Edits take effect without rewriting the conversation. Each agent call reloads definitions from disk, so the next launch uses the latest prompt, model, reasoning, runtime, and tools. Already-running delegated agents and the root session keep their configuration. Prior messages, the system prompt, and the original tool schema never change.

The agent tool advertises only agent IDs and descriptions. After saving or deleting an agent in /agents, Rho compares that advertised list, plus any earlier corrections, with the current definitions. If any agent became available or unavailable, or changed its description, Rho appends one correction listing those changes. The correction includes changes made by editing files outside /agents since the last correction. External edits never append a correction on their own, and edits to fields that are not advertised append nothing.

Definition files ​

Agent definitions are Markdown with strict frontmatter. The Markdown body extends the base coding prompt by default:

markdown
---
id: security-review
description: Reviews changes for security defects
runtime: rho
model-policy: inherit
reasoning: high
tools: [read_file, list_dir, bash]
---
Review the requested changes. Do not modify files.

Discovery order ​

Definitions are discovered deterministically from built-ins, Agent Plugins, ~/.agents/agents, ~/.rho/agents, and trusted project .agents/agents directories, with later sources taking precedence. Project definitions are ignored unless RHO_TRUST_PROJECT_AGENTS=1, so an untrusted checkout cannot affect prompts, models, or tools. Project plugin agents follow plugin trust (RHO_TRUST_PROJECT_PLUGINS=1) instead. Plugin agents cannot use built-in agent IDs. Duplicate IDs within one precedence level are errors. The file name supplies id when the field is omitted.

For the full value set, constraints, and defaults, see Agent definition schema.

Quick field summary ​

FieldRequiredMeaning
idnoStable lowercase identifier; defaults to the file name
descriptionyesDescription shown by the agent tool
runtimenoExecution harness: rho (default), claude-cli, or cursor
promptnoextend (default) or replace
model-policynoFor runtime: rho: inherit, prefer, require, or select. For runtime: claude-cli: omit, inherit, or select
modelpolicy-dependentModel selected by non-inherit policies. On runtime: rho, use @name to reference a model alias. On runtime: claude-cli, the value is passed through as the Claude session model option and must be a Claude model name or Claude alias such as claude-opus-5 (Rho @alias references are rejected)
providernoProvider selected with the model. Valid only for runtime: rho; rejected on runtime: claude-cli
fastnoruntime: rho with a pinned model only. true turns on fast serving for this agent at a higher credit rate. Subagents never inherit the parent's /fast; without fast: true they run at standard speed. Launch fails when the bound model cannot use fast mode
reasoningnoFor runtime: rho: off, minimal, low, medium, high, xhigh, or max. For runtime: claude-cli: maps to Claude effort as low, medium, high, xhigh, or max. Omit to inherit Claude's default. off and minimal are rejected on claude-cli
toolsnoTool allowlist. Vocabulary depends on runtime (see definition schema)
inherit_claude_confignotrue or false (default). Opt in only with runtime: claude-cli to load the user's full Claude settings (user,project,local). Default stays closed

Delegating work ​

Every agent call starts a background run and returns a six-character run ID immediately. There is no foreground mode or background parameter. Independent calls in the same batch run together.

Per-call model selection ​

Select a different model without creating a custom agent definition:

js
agent({
  agent_id: "reviewer",
  model: "openai-codex/gpt-6.1-sol",
  prompt: "Review the diff for correctness and security. Do not edit files."
})
agent({
  agent_id: "reviewer",
  model: "@independent-review",
  prompt: "Review the diff for maintainability. Do not edit files."
})

model is optional. Omit it to preserve the agent's existing model policy. An explicit value replaces its model, provider, and auth pins for this call only, including prefer, require, and select policies (all three currently pin the same way). It does not change the definition, root defaults, prompt, tools, or parent permission ceiling. The agent's reasoning and fast-mode policy still apply (an [internal_agents.<id>] entry turns fast mode off and its reasoning, when set, replaces the definition's); incompatible fast mode fails the launch rather than being silently disabled.

References use the same local catalog and model aliases as /model: provider/model, an unambiguous catalog model ID, or @alias. Only the first slash separates provider and model: myproxy/vendor/model selects vendor/model on myproxy. A bare alias target keeps the parent's provider. Custom/discovered models must already be in the local model cache; refresh model lists with /refresh-models if necessary. Delegation does not discover or invent models.

Compatible available parent auth is preferred; otherwise selection uses an available login for the target model/provider. Definition auth pins do not carry across an explicit override. Unknown/ambiguous models, undefined aliases, unavailable cached models, missing credentials, and provider failures are explicit errors, never fallback to the parent or pinned model. An available credential does not guarantee the account has access; provider-side auth/access errors still fail the child.

Per-call overrides require runtime: rho. Claude CLI, Cursor, and Antigravity use different model namespaces and reject this field; their existing definition-based selection is unchanged. CLI, TUI, and ACP native delegation use the same binder.

Native agent receipts and agents structured status include the bound provider and model; completion/status text and run artifacts also report that selection.

Completions reach the parent automatically at safe provider boundaries. The parent can continue independent work or end its turn to wait for required results, without polling. Interactive sessions wake an idle parent. CLI and ACP runs wait for outstanding children before natural completion and deliver their results back into the same run, preserving its step limit and cancellation handling. They wait the same way for workflows and for background tasks started during the run; a background process started as a service neither holds the run nor wakes an idle parent. Side chats still disable delegation.

Cancellation, errors, and step limits end CLI and ACP runs without waiting for more child results. A CLI run then stops its remaining children; their saved status and artifacts remain available for inspection. An ACP session keeps them running, as the TUI does across cancelled turns, because hosts such as T3 Code cancel the open prompt to send each mid-turn message. The next prompt waits for the children and delivers their results. ACP sessions run in the daemon, so closing or reloading the session in the host does not stop its children either. Stop children with the agents tool. Under rho acp --t3code, children run as T3 threads instead: they report to the parent through T3 and never hold a prompt open.

Rho-runtime agents stay in-process. runtime: claude-cli agents spawn the external claude-agent-acp adapter and still report through the same status and attachment files. The agents tool lists, inspects, cancels, or messages handles tracked by SubagentManager. Parent shutdown cancels active handles and waits for bounded cleanup. Delegated agents run without their own TUI. Questionnaires raised by delegated Rho agents surface in an interactive parent session; approvals still cannot.

After /new, newly delegated runs belong to the new session, including their completion notifications and artifacts. Existing runs keep their original parent session; switching sessions does not transfer their notifications to the new one.

Parents can steer a running Rho-runtime child with agents action message, applied at the child's next provider turn. Claude children have neither message_parent nor request_parent_action.

ACP children (Claude Code, Cursor, Antigravity) take parent messages the same way. An ACP agent that advertises steering (_session/steering in initialize) receives each message inside the turn that is running, and the attach view shows it as received. Otherwise, or when the agent declines because no turn is running, Rho sends the message as the child's next turn.

In Supervised mode, Rho-runtime-delegated Write and Process operations fail closed. Claude-cli agents refuse to spawn under Supervised mode because Rho cannot ask a human to approve a Claude tool call. Auto and Allow edits spawn only when tools: are bare names and inherit_claude_config is false. Claude auto-approves read-only Bash and allowedTools entries, so a specifier such as Bash(git *) (which exposes the Bash base tool) or inherited Claude settings would run actions outside the bound set and is refused. Those runs load no Claude settings (settingSources: []) so project hooks cannot widen the child, and Rho rejects every permission request. See Claude permission modes. Interactive permission-mode changes apply to delegated agents launched after the change. An already-running delegated agent keeps the launch-time mode because it cannot be retroactively sandboxed; future launches receive the changed mode.

Pass --no-subagents to remove delegation capabilities from a root invocation.

The child's attach view shows parent messages as incoming cards. For Rho children, a card appears when the correction enters conversation history, not merely when the parent queues it. ACP cards are labeled received when the agent accepts a steer, and queued when the message waits for the next turn. The cards are saved in the attachment journal and survive reattachment.

Child-to-parent messages ​

Delegated agents work quietly by default. They should save findings for their final result, which is delivered automatically, rather than send acknowledgments, progress updates, or completion previews. This overrides general instructions to keep a human updated during substantial work.

Background Rho agents with an interactive parent have two non-blocking messaging tools:

ToolUseDelivery
message_parentA useful, nonurgent finding that cannot wait for the final resultQueued for an otherwise-scheduled parent turn; never wakes an idle parent on its own
request_parent_actionA blocking decision or immediate coordination need, such as conflicting editsWakes an idle parent at a safe turn boundary; the message must state what action is needed

Pending notices share a batch with action requests and completion notifications. Multiple notices already waiting at a boundary become one parent turn, not one turn per message. While the parent is working, notices wait for a safe provider boundary rather than interrupt streaming or tool work. Idle delivery still respects input and confirmation gates.

Delivered messages appear in left-rail transcript cards, distinct from human input. Each card shows the task, sender, run ID, event type, and message body. Bodies use the same Markdown formatting as assistant replies, including headings, emphasis, and code blocks. Updates and results use the configured tool-output preview length; clicking a card (or Ctrl+O on the latest one) expands the full body and run details. Action requests and failed results show their full body without expansion. Incoming cards remain visible in Zen mode. The event label distinguishes an update from a completed, failed, or stopped run; receiving an update does not imply that the child finished or paused.

Neither tool waits for a reply. Use questionnaire when a human must answer before the child can proceed; use agents action message to steer a child in response to an action request. Both child messaging tools and agents action message reject bodies over 8 KiB after trimming. Queued notices retain their end-to-end queue budget until delivery or discard. Ordinary notices are admitted while fewer than 32 notices are outstanding; action requests can use one additional reserved slot, so an ordinary backlog cannot prevent the request that wakes the parent to deliver it. Both tools fail explicitly when their allowance is full.

Background delivery during a turn ​

The interactive parent collects child notices, agent completions, workflow results, and process exits at safe provider boundaries after tool work, not only between human messages. It also checks pending notifications before committing its final response. Streaming stays live, so text may already be visible when a notification arrives. Transcript notices wait until the current message's queued and buffered text has finished, so they cannot split an assistant response. This display delay does not delay delivery to the model. Completions, workflow/process results, and action requests found at the final checkpoint cause another provider step. Informational notices alone do not; they wait for an already-scheduled provider request or join another delivery. Completions arriving after the finalization handoff remain queued and wake an idle parent as before.

Child messages retain their send order and run identity. When a terminal result is in the same batch, earlier planning and progress are marked as historical context. Rho does not guess which free-text findings are safe to delete. Reading a terminal result through agents status or agents stop includes pending child notices as earlier context and acknowledges their exact receipts, so they do not later wake the parent as a fresh task. Polling a terminal process or workflow similarly acknowledges its completion. A failed delivery attempt cannot undo a later explicit acknowledgement.

Parent-to-child messages in the transcript ​

Messages sent through agents action message show the task title first, then muted parent → <agent role> · queued routing and an excerpt of the message itself. If a run has no generated title yet, its first nonempty prompt line identifies the task. This keeps different tasks using the same agent role distinguishable.

The excerpt uses your max_tool_output_lines setting. Press Ctrl+O or click the card to see the complete message, full task title, and run ID. Surrounding whitespace is trimmed to match the text accepted for delivery. The durable receipt remains plain text for ACP clients and exported transcripts. Short messages can also expand to show those details. Queued means the message was accepted for delivery, not that the child has acted on it or completed its task. Child-to-parent message_parent notices keep their existing notification display.

Binding and security ​

Every invocation goes through the same binder. Rho-runtime agents resolve aliases and tool capabilities against the host. Claude-cli agents are delegated-only and keep Claude's model/tool vocabulary. Delegated Rho agents cannot recurse through agent/agents, or start workflow runs, whose agent nodes would run outside the parent session's agent budget.

Details: Binding and security.

Claude Code as a delegated runtime ​

Rho can hand a delegated agent to Claude Code, through the claude-agent-acp adapter, so a child run can use a Claude subscription while the parent stays in Rho. This is not Anthropic API-key access and is not available as the root session runtime.

Quick path: install claude-agent-acp, run /login claude-code, define an agent with runtime: claude-cli, then launch it through the agent tool under Plan or Bypass. Auto and Allow edits work only for proven no-prompt tools: with inherit_claude_config: false; unknown Claude, plugin, and MCP names fail closed.

Full guide: Claude Code as a delegated runtime.

Cursor Agent as a delegated runtime ​

Rho can hand a delegated agent to the installed cursor-agent binary so a child run can use a Cursor sign-in while the parent stays in Rho. This is not available as the root session runtime.

Quick path: install cursor-agent, run /login cursor, define an agent with runtime: cursor and a nonempty classified tools: list, then launch it through the agent tool under Plan or Bypass. Auto, Allow edits, and Supervised refuse at bind. Rho drives Cursor over ACP; parent messages arrive as the child's next turn.

Full guide: Cursor Agent as a delegated runtime.

Google Antigravity as a delegated runtime ​

Rho can hand a delegated agent to Google Antigravity (agy acp, agy 1.5.0 or later) so a child run can use Gemini models and agy's sign-in while the parent stays in Rho. This is not available as the root session runtime.

Quick path: install agy, run /login antigravity, define an agent with runtime: antigravity and a nonempty tools: list (agy enforces it through a per-run agy custom agent), then launch it through the agent tool under Plan or Bypass. Auto, Allow edits, and Supervised refuse at bind.

Full guide: Google Antigravity as a delegated runtime.

Attachment and artifacts ​

Watch a delegated run with /attach or a click on its activity-rail row. The picker lists runs from the current directory. Detaching does not cancel the run. Artifacts live under the parent session folder when available, otherwise under ~/.rho/subagents/<id>/. The title model names each run so the activity rail and attach picker can show role and title instead of a run id.

Details: Attachment and artifacts.