pattermDocsGitHub

Agents that run agents

View as Markdown

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.

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.
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.

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 for what you see and how to control it.

A worked example##

You open a Claude Code agent in your project and type:

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 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.