cli-subagents git:20261103.0b95088A

Immutable. This exact content never changes and is served at /api/v1/blob/59551f6dabecd89d.

---
name: cli-subagents
description: How to run subagents through CLI Subagents (the cli-subagents-* agent types in Claude Code; subagent_start, subagent_wait, subagent_result, subagent_message elsewhere). Use it like your built-in subagent tool whenever work can be delegated, run in parallel, reviewed independently, or moved to another of the user's accounts or another agent CLI (Claude Code, Codex, Antigravity, OpenCode). Skip it for trivial answers and tiny edits.
---

# CLI Subagents

These tools are your subagent tool. Use them the way you would use a built-in "spawn a subagent" tool: hand over a self-contained task, keep working, collect the result, check it. Each subagent runs in Claude Code, Codex, Antigravity or OpenCode with the parent's MCP servers and instructions. Same-CLI accounts also share its plugins, skills and settings. Choosing a pooled account and switching at a quota limit happen on their own. OpenCode uses the user's one profile and does not rotate accounts after a free-model limit.

## In Claude Code: always start a relay agent

In Claude Code, start every CLI Subagents job with your Agent tool and one of the four relay agent types. This holds at every depth where delegation is allowed.

| Runs in | `subagent_type` |
|---|---|
| Codex | `cli-subagents:cli-subagents-codex` |
| Antigravity (Gemini) | `cli-subagents:cli-subagents-antigravity` |
| OpenCode v2 | `cli-subagents:cli-subagents-opencode` |
| Claude Code on another account | `cli-subagents:cli-subagents-claude` |

Don't run `csa run`, `csa start` or `csa follow` in your own shell, and don't call `subagent_start`. A job started that way never appears in the user's agent list, and your turn is blocked while you wait on it. A relay agent appears with its own color, the user can open it and watch every step the worker takes (commands, edits, messages, reasoning), and you get the usual notice when it finishes.

```text
Agent tool:
  subagent_type: cli-subagents:cli-subagents-codex
  description: Sol 6.1 high · edit · fix the login test
  run_in_background: true
  prompt: |
    model=gpt-6.1-sol
    effort=high
    access=edit

    <the complete, self-contained task>
```

- Description: `<model> · <access> · <task in a few words>`. The user reads it to see what runs where.
- Prompt: option lines first, one per line (`model=...`, `effort=...`, `access=read|edit`, and only when needed `account=NAME`, `cwd=PATH`, `timeout=SECONDS`, `override=USER_WORDS` under the Limits rule below), then a blank line and the complete task written as below. `access` defaults to `edit` in the Claude relay and `read` in the Codex, Antigravity and OpenCode relays.
- Start it in the background and keep working. Don't poll or wait in a shell; the notice arrives when it finishes.
- Its final message is the worker's result, unchanged. If the worker asks something, the agent stops and tells you; answer with SendMessage to that agent and it passes the answer on. While the job runs, SendMessage "cancel" stops it and anything else goes to the worker as a follow-up, unchanged; the relay never answers it itself, whatever the text says. After the job has finished, SendMessage to the same relay continues the worker's conversation as a new job; the relay follows it and returns its result.

A relay shows the worker's messages, the notes it writes between steps, as its own messages, word for word and one after another, like the Codex app. Its first message names the relay's model and the worker's, read from their logs, and says when the worker runs another model or effort than the one asked for. Each `csa follow` call returns as soon as a new message is complete. Only the worker's final result comes back to you; the copied messages stay in the relay's view.

The relay gets a fresh absolute path from `csa relay-path`, writes the complete prompt with its host's file tool, then runs `csa run --follow --window 180 --runtime <runtime> --relay-file <path>`. csa validates the inbox file, reads UTF-8, deletes it and parses the same leading option lines as `--relay -`. Keep the blank separator before the task. Payload never appears in shell syntax, so its length and quotes cannot break a shell command. Answers and follow-ups use fresh files with `csa message --relay-file` and remain message text, even when they begin with `key=value`. Files are limited to 16 MiB; invalid files or options return an authenticated FAILED result. Claude uses Write in the csa home inbox with a narrow plugin permission hook. Codex and Antigravity use `csa relay-path --workspace` in the caller's writable workspace. csa writes a `.gitignore` containing `*` there before returning a payload path. Codex uses native apply_patch to write plain text; its line-ending normalization and final newline are acceptable. Keep quotes and Windows paths literal. Do not widen host permissions or fall back to embedding payload in a shell command if writing fails.

The MCP tools below work everywhere. In Codex, `csa setup --host codex` installs the same four relays as native agents (`cli-subagents-codex` and so on); start them with Codex's own subagent tool as [the Codex note](hosts/codex.md) shows, and use the MCP tools there only when those agents are missing. In Antigravity, `csa setup --host antigravity` installs them as a companion plugin of subagents; start them as [the Antigravity note](hosts/antigravity.md) shows. In Claude Code, too, use the MCP tools only when the relay agent types are missing.

## The loop with the MCP tools

1. Start: `subagent_start` with a complete task (`prompt`), the project folder (`cwd`, absolute) and `access` (`read` for analysis and review, `edit` for changes). Claude workers on `read` get read-only tools (file reading, search, web) plus shell commands with read-only options, including `git diff`; a worker hook rejects writes, execution helpers and named secret paths. Start several jobs before waiting if the work is independent.
2. Wait: `subagent_wait` with the job IDs. It returns when a job finishes or a subagent sends a message or question. Call it again for the jobs still running.
3. Answer: if a result shows `open_questions`, reply with `subagent_message` and `reply_to` set to the question id. To give a running subagent new instructions, send `subagent_message` without `reply_to`. In Claude Code a hook also wakes an idle session when a job finishes or asks something, so you can end your turn after starting jobs.
4. Collect and check: finished jobs come back with `outcome` and `result`. `success` means the subagent finished. Collecting a result claims it and suppresses later automatic notifications. Explicit `subagent_result` or `csa follow` calls can return it again. Still read the diff, run the tests and confirm the files exist before relying on it.
5. Follow up: `subagent_message` to a finished job continues the same conversation as a new job.

## Writing the task

The subagent can't see this conversation. State the goal, the files or folders involved, what it must not touch, decisions already made, how to verify the result, and what to report back. Point to files instead of pasting them.

Optional arguments: `runtime` (`claude` by default, `codex`, `antigravity`, `opencode`) when a specific agent or a second opinion from another vendor helps; `model`; `effort`; `max_turns`; `timeout_seconds` (default 1800); `resume_job` to continue an earlier job's conversation; `account` to pin one account; `add_dirs`. Turn-limit support depends on the runtime.

`access: "full"` skips the CLI's own permission checks. Use it only when the user asked for that.

Codex and Antigravity workers have their own web search and page reading, which reach sites such as Reddit that block other tools, so they suit web research. Antigravity workers find YouTube videos and read their title and description, but can't watch them or read transcripts.

## When to pick OpenCode

Use `opencode` for personal projects when the user wants OpenCode or a free model and their vendor rules allow it. csa discovers OpenCode v2 (`@opencode/cli`) when `opencode` is on PATH. A missing binary adds no setup task; `[opencode] enabled = false` disables it. OpenCode is a worker only, not a supported host.

Omit `model` to keep the user's OpenCode model. When none is configured, csa uses `opencode/deepseek-v4.1-flash-free`. An unavailable model fails the job; csa never lets OpenCode fall back to another model. `effort` becomes the model's variant (`low`, `high` or `max` on the default model); an effort the model lacks fails with a clear message. Free models are for personal projects only. The provider says DeepSeek does not train on your data, but Anomaly's unpaid-content terms still apply. Big Pickle, MiMo and Flint may use collected data and the Nemotron endpoints log it; csa never defaults to them and blocks them unless the user chose that model. Free limits are per IP per day and reset at UTC midnight. On `provider.free-limit`, stop without account rotation; wait for the reset or follow the user's fallback rules.

On supported Windows, OpenCode `edit` workers' shell commands run in fresh MXC containers (workspace writes, protected git/agent settings, no Git Bash). Fixed-rule builds/tests have no internet egress, with host loopback allowed; reviewed commands get egress. OpenCode, its file tools, the gate and reviewer chain stay on the host with normal state and logins. File tools rely on gate paths. `read` allows workspace reads/list/search and no commands, so its file reads have no OS containment. `edit` adds workspace edits and ordinary read-only commands. The default reviewers are Claude Haiku then Gemini Flash through agy; configure `[review]` or `[[opencode.reviewers]]`. Reviewers off or unable to decide means denial. Both levels deny Code Mode `execute`, subagents and MCP servers other than `csa-parent`, send web fetch/search to review and ignore project OpenCode config. `full` uses `--auto` without gate or sandbox and requires the user's explicit request. See [OpenCode](../../docs/opencode.md) and [Sandbox](../../docs/sandbox.md), including Fence for macOS/Linux.

## Limits

Limits are enforced by csa. If a start is refused, follow the suggestion in the message; don't count quotas yourself.

Accounts marked `explicit_only` require an explicit `account`; automatic selection and failover skip them. All account spend caps apply together, including rolling windows, and cannot be bypassed with `override`; a `budget` outcome stops without retry or failover, so follow its message or wait for room under every cap.

Never set override on your own judgment; use it only when the user asked for more jobs in this conversation, or confirmed after you warned them and told them how much of the 5-hour window is left. Use csa's reported usage and reset time; if the window is unknown, say so. Otherwise ask the user or use the home model.

Put the user's own words in `override`, for example the relay line `override=user asked for 6 Codex agents`, the `override` field on `subagent_start`, or `--override "user asked for 6 Codex agents"` on `csa run` or `csa start`. Empty values are rejected. This bypasses only csa's job caps, quota steps, usage ceiling, pool budgets and queueing. Account and pool cooldowns after real usage-limit errors, `models`, `max_effort`, login, depth and access still apply. Override jobs count toward later starts. The text is stored and shown in job lists, follow headers and status/result summaries. A new start needs its own override; a follow-up to a finished job does not inherit it.

## Outcomes

| outcome | What to do |
|---|---|
| `success` | Check the work |
| `usage_limit` | The selected account hit a limit. Unpinned jobs try other accounts when failover is enabled. OpenCode free limits never rotate accounts; check the UTC reset time. |
| `no_account` | All accounts are busy or cooling down; wait or tell the user |
| `auth` | For an extra account, ask the user to run `csa accounts login <name>`; add `--runtime codex` or `--runtime antigravity` for non-Claude accounts. For a primary login, use the vendor CLI (`claude auth login`, `codex login`, `agy` or `opencode auth login`). OpenCode has no extra account folders in this version. |
| `timeout`, `max_turns` | Narrow the task or raise the limit |
| `error`, `lost` | Read `message` and `warnings`; retry once at most. `model at capacity after N retries` means csa already waited and retried, and the model stayed overloaded. Fall back as your delegation rules say; do not manage another retry timer. |

## Per host

Read the note for the CLI you are running in once: [Claude Code](hosts/claude-code.md), [Codex](hosts/codex.md) or [Antigravity](hosts/antigravity.md). It covers how waiting works there and where to put new skills, MCP servers and instructions so every subagent shares them.

- Claude Code: `subagent_wait` can run for up to an hour; Claude Code moves it to the background and notifies you when it returns.
- Codex: waits end after 240 seconds; call `subagent_wait` again until the jobs finish.
- Antigravity: keep waits to a few minutes and call again.

## What subagents get

Subagents in the same CLI as you load the same setup you have. Subagents in another CLI get a short note listing your instruction files and skill folders to read. Claude, Codex and OpenCode workers get `message_parent` (progress notes), `ask_parent` (a question; it waits for your answer) and `check_parent_messages` (follow-ups you send). OpenCode also receives instruction-file paths in its config and exposes the parent tools individually with `codemode: false`. Antigravity workers get them only with an effective account cap of exactly 1 and a managed worker folder; the primary file-login fallback has no parent channel. See [Gemini messages](../../docs/gemini.md#messages). Subagents can't start subagents of their own. Tools built into the Claude desktop app itself (its browser or terminal panes, for example) aren't available to them. Plugins from another CLI are not translated into OpenCode plugins.

Never put secrets or credentials in a prompt.