Delegation with a Contract: Inside Prime Agent's Recursive Agents
Prime Agent's recursive agents address a specific coordination problem: a repository task may contain several questions that can be investigated independently, while the parent model still needs one coherent, verifiable result. This chapter follows the lifecycle of rlm.spawn, from the parent's Python call through host admission and child execution to the later return of findings. The practical goal is not to make recursion sound mysterious; it is to show how to design focused delegation without confusing a task receipt with an answer.
Spawn begins with an admission decision
Return to a repository review in which the parent needs to assess an authentication change. One investigation concerns the public API, another concerns regression tests, and a third concerns documentation or integration behavior. These questions overlap enough to require a final synthesis, but they are separate enough that the parent does not need to inspect every file for every question. Prime Agent lets the model express that separation from its persistent Python environment.
The parent calls await rlm.spawn(...) with a focused prompt and a required name. That call is not a request to run a miniature conversation inside the current Python cell until an answer appears. It is a request to the TypeScript host to consider and admit a child task. The host validates the request, checks the recursion depth, resolves the requested model or inherits the parent's model, enforces a unique sibling name, creates the child's runtime and session directory, records it in the parent's registry, and then returns a handle.
The handle is an admission receipt. It identifies the child with an rlm_child_id and a name, and it carries the child session directory and model. It does not carry the child's eventual answer. That distinction determines how the parent should be written. The parent can admit an API reviewer, a test reviewer, and an integration reviewer in separate calls, retain their handles, and finish its current turn rather than blocking while the children work. The calls can be near one another in the parent's code, but the results are not values waiting to be unpacked from those calls.
This contract is useful because admission and execution have different owners and different times. The parent session decides that a subtask is worth starting. The host creates a normal child agent session and runs its prompt. The child then has its own model loop, context, tools, resources, and session machinery. The parent receives evidence later, after the child has either produced a response or written something that the parent can inspect. A function that returned an answer immediately would hide that lifecycle and encourage the parent to treat asynchronous work as if it were already complete.
The runtime choices made at admission are part of the contract rather than informal hints. A child can inherit the parent model, or the request can select a model under Prime Agent's configured model rules. Thinking configuration is also resolved for the child. The parent must give each child an unambiguous name because names are how a retained worker can be addressed later, not just labels printed in a log. The host's recursion check supplies another boundary: the repository documents a default maximum depth of two. A root agent can create children, and those children can create grandchildren, but the grandchildren cannot create another generation unless the limit is configured higher.
That limit is more than a defensive number. Recursive delegation multiplies context, process, and provider work. Without a stopping rule, a broad instruction could produce a tree whose shape is determined by the model's momentary interpretation rather than by the task's actual structure. A depth limit does not ensure that a child is well chosen, but it prevents recursion from being treated as an unlimited resource. A parent still needs to decide whether a subtask is independent, whether its result can be checked, and whether the additional work is worth the added coordination.
The validation step also protects the meaning of the relationship. A name is not merely decorative if the parent may later address a retained child. A model selector is not merely a suggestion if the parent is trying to allocate a particular kind of reasoning or capability. A depth value is not a prompt convention if the host uses it to decide whether another runtime may be created. Keeping these decisions in the host means that a child cannot silently change the structure of the session by interpreting an informal instruction as permission for another generation.
This is especially important when a parent admits several children in one turn. The parent should define separate questions, not simply distribute the same broad prompt three times. An API child might identify the callers affected by a change; a test child might inspect whether the behavior is exercised; an integration child might look for a mismatch between documentation and actual use. Their shared subject is the repository, but their working contexts and evidence paths can remain distinct. The parent then has a reason to compare the results instead of counting three similar summaries as three independent confirmations.
The parent also needs to choose a return shape before it delegates. A useful child prompt asks for the observation, the evidence behind it, and any uncertainty that would change the conclusion. That shape turns a later message or file into something the parent can evaluate. It does not force agreement, and it does not make the child a reviewer of the parent's entire objective. It simply makes the boundary between independent investigation and parent synthesis visible.
The host bridge makes the admission sequence concrete:
The sequence has two return paths that should not be conflated. The first is the short host reply that confirms admission. The second is the later child communication that carries findings. The parent can therefore continue using its own context while the child works, but it cannot infer the child's conclusion from the existence of a handle.
A child is useful only if the parent can receive and verify its work
The child session is independent, but it is not detached from the architecture that gives Prime Agent its meaning. It runs through the same general TypeScript agent machinery as the parent and inherits provider configuration, resources, tools, retry policy, session storage, and thinking configuration unless the request supplies another configured model. The child does not receive every detail of the parent's conversation by default. That is the point of the split: a test reviewer can focus on tests, while an API reviewer can focus on the interface and its callers.
Focused context is an advantage only when the prompt defines a useful boundary. “Review this repository” gives each child a broad and potentially overlapping assignment. “Inspect the authentication change and identify which regression behavior is covered, which is missing, and what evidence supports the conclusion” gives a child a question with a return shape. The second kind of prompt makes later synthesis easier because the parent knows what the child was asked to establish and what uncertainty the answer should expose.
The child must also have a return channel. Prime Agent documents two: an explicit agent_message reply to the parent or a file that the parent can read. In the message path, the child sends its findings as an ordinary agent message delivered to the parent later. In the file path, the artifact becomes the handoff, which can be useful when the result is larger or needs to be inspected independently. Neither path is automatic aggregation. If the child never reports, writes an unusable artifact, or answers a different question, the parent has no reason to treat the subtask as complete merely because it was admitted.
This is the hidden responsibility in recursive systems: delegation creates a new source of evidence, not a new source of truth. The parent has to compare a child's claim with the repository, the original objective, and the findings from other children. If the test reviewer says a behavior is covered, the parent still needs to distinguish a passing test from a test that was not run or a test whose output is inconclusive. A child can reduce the amount of direct searching the parent performs, but it cannot remove the parent's obligation to interpret and verify.
Prime Agent keeps a parent-scoped registry to make this ongoing relationship addressable. The parent can list direct children and see stable child identifiers, names, session information, directories, and running or completed status. The registry survives compaction, a kernel restart, and restoration of the parent session. A retained child can be followed up with another message, so the collaboration does not have to end at the first response. That persistence turns a spawn into a manageable work unit rather than a disposable background process whose identity is lost when the original Python cell ends.
The scope matters. The registry follows the parent transcript; an unrelated new parent session does not inherit the children. This prevents a name from becoming a global pointer to an arbitrary worker and keeps the meaning of a child relationship tied to the session that created it. It also means that a user planning a long-running review should preserve or resume the parent session rather than assume that any later session can rediscover the same delegation tree automatically.
Usage accounting follows a similarly careful boundary. The child handle does not contain completion or cost data. As the child produces assistant work, Prime Agent asynchronously folds the child's usage and cost into the parent assistant turn that launched it and persists an attribution entry. Reports can still distinguish the child's own usage from the parent node's own context measurement while reconciling the root's aggregate total. In practical terms, delegation can make a task easier to divide, but it is not free work hidden outside the parent's accounting.
That accounting changes how a parent should judge “parallel.” Several child runtimes can execute concurrently because they have distinct sessions. The parent Python kernel, however, still has its own shared namespace and ordinary cells remain serialized. A parent should not try to coordinate children by assuming that two ordinary cells are safely mutating the same state at once. Instead, it should give each child an explicit prompt and return channel, then combine their messages or files in a later parent turn.
The lifecycle also has failure-shaped outcomes. A child can be incomplete when the parent is ready to synthesize. A message can arrive after the parent's working context has been compacted. A child can expose a disagreement rather than a clean answer. These are not defects that the spawn handle can conceal; they are reasons to retain the child identity, preserve its artifacts, and make the parent’s synthesis conditional on evidence. The registry and usage attribution help the parent know what work exists, but they do not certify its quality.
A sound delegation pattern for the authentication review therefore has four stages. First, define independent questions that do not require all children to edit the same state. Second, give each child a prompt that asks for findings and uncertainty, not just a verdict. Third, retain the handles and wait for explicit messages or files rather than treating admission as completion. Fourth, have the parent reconcile the findings with the repository and run the appropriate checks before reporting a conclusion. These stages are a practical interpretation of Prime Agent's contracts, not a promise that every delegation will succeed.
The most important design choice is what not to delegate. A subtask whose correctness depends on a rapidly changing shared file, an unreviewed external side effect, or an unresolved decision by the parent may be a poor candidate for independent execution. The host can create the child, but it cannot know whether the parent has decomposed the problem correctly. Recursion is strongest where the questions are separable and the evidence can be brought back into a common review.
Prime Agent's recursive agents therefore extend the Python control surface in a precise way. rlm.spawn creates an independently addressable execution path, bounded by host policy and connected to the parent through explicit communication. Its value is not that many models are always better than one. Its value is that a long task can allocate attention to separate questions while preserving a parent responsible for synthesis, accounting, and verification.
That raises the next lifecycle question. Parallel child work matters only if it remains available when the terminal closes, the context window fills, or a worker must reconnect after a failure. The next part of Prime Agent's design follows the session and its artifacts through those transitions, asking what continuity preserves—and what it still cannot undo.