# Agents running agents An agent running in marsh can call registered commands to start child jobs. Each child gets a fresh container, appears under its parent in `marsh jobs --tree`, and stops when its parent ends. Ctrl-C cancels the whole foreground job tree. With [marsh installed](https://runmar.sh/docs/install.md) and both [providers configured](https://runmar.sh/docs/kits.md#signing-in), try this from your marsh shell: ```sh claude -p "use your Bash tool to run: codex exec 'reply with the number 7'" marsh jobs --tree ``` If Claude makes the requested call, Codex appears as its child in the tree. The child inherits its parent's project mounts and shared guest home, with its own Kit's network policy and credentials. A [split](https://runmar.sh/docs/split.md) can narrow its project mount to a fork. Any registered command is allowed by default, including another invocation of the same agent, subject to the [limits](#limits-and-messages) and [spawn set](#narrowing-what-an-agent-may-start). ## Signing in Configure each child's provider through [Docker Sandboxes](https://runmar.sh/docs/kits.md#signing-in), as you would for a direct call. ## Split from inside an agent An agent can split work across private forks and read the results back as patches. From a job, each branch must be `::: LABEL CMD ARG...`, naming a registered command. The child mounts its fork at the fork's own host path; the guest home is still shared. ```sh marsh split ::: fix codex exec 'fix the typo in notes.txt' ::: review claude -p 'review notes.txt' | marsh join ``` This assumes `notes.txt` exists. Both branches begin with the same snapshot; the reviewer does not see the fixer's edits. `marsh join` prints one section per branch, with `kit:NAME` identifying the Kit and a patch for any captured changes. It never applies the patches. Use `marsh join --keep` if you want to inspect or apply them after join exits. See [Split and join](https://runmar.sh/docs/split.md). Shell branches (`marsh split -b`, `split { a: ...; b: ... }`) run only from your own shell. A job that asks for one is refused: ```text split: a: shell branches (-b, split { }) run only from the session shell ``` ## Parallel work on the same files Inside a job, `marsh fanout` runs commands concurrently in that job's container, sharing its files. A registered command starts a child job; other commands use the container's own tools. Writes can race. ```sh claude -p "run tests and lint at once with marsh fanout" ``` The agent can run argv branches directly: ```sh marsh fanout ::: tests make test ::: lint make lint | marsh collect ``` `collect` prints each branch's output in the order written, and exits with the first failing branch's status. This example needs the project's `test` and `lint` Makefile targets. From a job, branches must be `::: LABEL CMD ARG...`, as for `split`. The [fanout reference](https://runmar.sh/docs/fanout.md) also covers shell branches and Brush blocks for use from your own shell. ## Ctrl-C and cleanup Ctrl-C in your shell cancels the foreground job's whole tree: 1. Every job gets `INT`. 2. Anything still running 10 seconds later gets `KILL`. 3. marsh checks each container's deletion and records the cancellation and cleanup result. A job that had already ended keeps its completed state. 4. Your command exits 130. A job that ends cancels its own children the same way: `INT`, then `KILL` after 10 seconds. If marsh cannot confirm a job ended, `jobs --tree` shows it as `cleanup uncertain`. `marsh workers reset KIT` removes that Kit's VM and frees the slot ([Troubleshooting](https://runmar.sh/docs/troubleshooting.md#cleanup-uncertain-and-quarantine)). ## Narrowing what an agent may start To restrict child commands, set `MARSH_SPAWN` in your shell to a comma-separated list of names, or `none`. `marsh run --spawn a,b NAME` and `--no-spawn` do the same for one command. Nothing inside a job can widen the list. ```sh export MARSH_SPAWN=codex claude -p "use your Bash tool to run: shell -c true" ``` This limits which commands start. It does not limit what a permitted agent does to your project files. ## Limits and messages A refused call starts nothing and prints the reason on stderr. A registered-name link outside `MARSH_SPAWN` exits 126; other refusals, including those through `marsh run`, exit 125. `marsh status` counts refusals (`processes: N running, N refused, N held`). | Limit | Message | |---|---| | 8 jobs at once per daemon, all depths | `capacity: 8 jobs` | | Depth 4 (your command is depth 1) | `depth limit 4` | | The same Kit at most twice in a row | `claude → claude → claude refused: same-Kit chain limit 2` | | 4 live children per job | `fan-out limit 4` | | 64 launches per tree, counting refused child calls | `total limit 64` | | 4 distinct Kit VMs used by live jobs in one tree, by default | `tree already uses 4 Kit VMs (...) (MARSH_TREE_KIT_VMS)` | | At least one second must remain before the parent's deadline | `deadline: parent job ... has ... ms of wall time left` | | A name outside `MARSH_SPAWN` | `spawn refused: NAME not in this job's spawn set (MARSH_SPAWN)` | | No terminal for a child | `interactive child jobs are not supported yet` | A child job gets no terminal. If either stdin or stdout is a terminal, marsh refuses it. Run the command as `codex exec '...'