# Agents that run agents Any agent in Patterm can start other agents and processes, hand them work, and wait for their reports, while you watch every one of them in its own tab. Patterm does not add an orchestrator on top of your agent CLIs. It gives each agent a set of MCP tools for starting children, messaging them and waiting on them. Claude Code, Codex and OpenCode all use the same tools, so a Claude agent can delegate to a Codex agent and the other way round. The full list is in the [MCP tool reference](https://patterm.com/docs/mcp-tools.md). ## How delegation works An agent that you start from a project tab is a root agent. When it calls `spawn_agent`, the new agent is its child and appears under the parent's tab. A child can spawn children of its own, as long as the work is part of what it was asked to do. The pieces are: | Tool | What it does | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `spawn_agent` | Starts a child agent. Pass `agent` (`claude`, `codex`, `opencode` or `rawpty`), a `preset`, or a `conversation_id` to resume an earlier conversation. Add a `prompt` to give it its task. | | `spawn_process` | Starts a command or terminal as a child process. Processes close when their parent closes. | | `send_message` | Sends text to another process. Children can use `parent` as the target, and any agent can use `assistant` to reach the [assistant](https://patterm.com/docs/assistant.md). | | `report_to_parent` | A child's way of saying it is done, blocked, failed, or found nothing. The status is `completed`, `blocked`, `failed` or `no_findings`. | | `list_processes` | Lists the processes in the project. Agents call this before messaging or reading another process. | | `get_conversation_output` | Reads what an agent said, newest first, with its latest answer and last report. | When you spawn through `spawn_agent` with a `prompt`, Patterm appends an instruction telling the child to call `report_to_parent` when it finishes, is blocked, fails or has nothing to report, and to stay available for follow-ups. Children join the caller's project. If you pass `worktree_id`, the worktree must belong to the same project. See [Worktrees](https://patterm.com/docs/worktrees.md). > [!NOTE] > Agents keep their own harness permissions. If a child needs approval to run a command, it shows the harness's normal prompt in its own tab, and it waits for you. ## Waiting for children After delegating, the parent should stop and wait. It should not poll. Patterm gives it timers that deliver a message into the parent's session when a condition is met. | Timer | Fires when | | ------------------------------ | --------------------------------------------------------------------- | | `timer_fire_when_reported_all` | Every watched agent has called `report_to_parent` or stopped running. | | `timer_fire_when_reported_any` | The first watched agent reports or stops running. | | `timer_fire_when_idle_all` | Every watched process has gone quiet. | | `timer_fire_when_idle_any` | Any watched process has gone quiet. | Use the report timers for delegated agents. Terminal quietness is not a reliable sign of completion, because a model can pause for a long time and then carry on. Use the idle timers for readiness checks (a dev server has finished starting), first-result-wins work, and quietness checks. Each timer takes `watched` (a list of process IDs) and `body` (the message Patterm sends the parent when the timer fires). The message begins with a line saying why the timer fired and what each watched process did, then your `body`. A report timer also fires if a watched process exits without reporting, and the message says so. ### max_wait_seconds is a rescue timeout `max_wait_seconds` is optional. If the condition never happens, it fires the timer anyway after that many seconds. It is not a polling interval. Model-heavy work such as a code review can be quiet for 20 minutes or more, so leave it out for ordinary delegated waits, or use a real rescue value such as 1200 or more. A value of 30 seconds would wake the parent long before the work is done. Only reports made after a timer is created count towards it. When a child has already reported and you want a second pass, send that same child a follow-up with `send_message` and set a new timer. The child keeps its earlier context. ## When children need you A child's `notify_user` and `request_close` go to its parent as messages, and the parent decides whether to answer them or escalate to you. If the parent is no longer running, or the agent has no parent, the request reaches you directly. See [Notifications and close requests](https://patterm.com/docs/notifications.md#child-agents) for what you see and how to control it. ## A worked example You open a Claude Code agent in your project and type: ```text Review the changes on this branch. Start two reviewers: a Codex agent that looks for security problems, and a Claude agent that checks test coverage. Wait for both, then give me one list of issues ordered by severity. ``` This is what happens: 1. The parent may check `list_processes` for an existing reviewer, then calls `spawn_agent` twice. Each call has a `name` and a `prompt` describing the review. Two child tabs appear under the parent's tab. 2. The parent calls `timer_fire_when_reported_all` with both process IDs and a `body` such as "Read both reports and combine them." It then waits for the callback. 3. Each reviewer works in its own terminal. If one needs permission to run a command, you approve it in that reviewer's tab. 4. Each reviewer calls `report_to_parent` with its findings. You may see the first one arrive while the other is still working. 5. When both have reported, the timer fires and types its message into the parent. The parent reads the full reports with `get_conversation_output` and answers you with the combined list. 6. The reviewers stay open, so you can ask the parent to send one of them a follow-up. When you are done, close them, or let the parent do it. ## Watching and stepping in Each agent has a tab in the top bar. Children are listed in the popover of the agent that started them. Hover over a parent's tab to see its subagents, its processes and its timers. Open any of them to see its terminal, or its conversation if it is an [Integrated](https://patterm.com/docs/agents-and-processes.md#integrated-and-tui-agents) agent. You can step in at any point: - Type into a child's terminal as you would in any other tab. Your input answers whatever it was waiting for. - Right-click a subagent in its parent's popover and choose **Close** to stop its work. Closing a parent closes its children as well. - Set a timer on any process yourself from the tab's context menu, using **Set timer**. Agents are told not to message a running child to ask for status or to hurry it up. They wait for the report. ## Detached agents A parent can start an agent with `detached: true`. It opens as a normal top-level tab that outlives its parent. It has no parent, so it cannot call `report_to_parent`, and it cannot be watched with a report timer. Its `notify_user` requests come straight to you. Agents are told to detach only when you have asked for it. ## Agents on other hosts If you have paired another machine and linked the project, agents on that host appear in `list_processes` as `host:process`, for example `workstation:process_7`. An agent can read them and send them messages. It cannot stop, restart or type into them. See [Multiple hosts](https://patterm.com/docs/multiple-hosts.md). ## Related - [Notifications and close requests](https://patterm.com/docs/notifications.md) - [Timers and routines](https://patterm.com/docs/timers-and-routines.md) - [MCP tool reference](https://patterm.com/docs/mcp-tools.md) --- This is one page of the Patterm documentation. The index of every page is at https://patterm.com/llms.txt.