Agent control

Agent control is the model-facing surface for long-lived teammates. It is separate from the one-shot task tool and from agent swarm: a teammate is backed by a normal Roder thread, keeps a canonical path, and can receive later messages or follow-up work during the parent session.

Tool surface

• spawn_agent creates a teammate, starts its first turn, and returns a canonical path such as /root/reviewer.
• send_message queues coordination for an existing teammate without starting a new idle turn.
• followup_task assigns work and starts or wakes the teammate when it is idle or completed.
• wait_agent yields on completion, mailbox activity, or user steering instead of forcing blind polling.
• list_agents lists the accessible live task tree.
• interrupt_agent interrupts the active teammate turn while keeping the identity available for later follow-up work.

Context inheritance

Spawning a teammate can copy all parent turns, copy none, or copy only the most recent N turns. With copied history, the child inherits the parent agent type and live model selection. With a fresh or last-N fork, the spawn may either inherit the parent provider, model, reasoning effort, workspace, policy, tools, runner, and developer context, or provide an explicit compatible model selection.

Configured subagent roles are advertised to the model and validated before a child starts. Roder rejects lane names used as roles and reports lane/tool incompatibilities early, so orchestration mistakes fail before consuming a teammate turn. Native full-history forks may use agent_type as an advisory role label, while model, provider, and reasoning overrides remain rejected for that mode.

{
  "task_name": "reviewer",
  "message": "Review the current patch and report blocking risks.",
  "fork_turns": "all"
}

{
  "task_name": "fast_search",
  "message": "Locate the relevant implementation and report file paths.",
  "fork_turns": "none",
  "model_provider": "codex",
  "model": "gpt-5.6-sol",
  "reasoning_effort": "high"
}

Canonical task paths

A local task name becomes one path segment. A lead spawning reviewercreates /root/reviewer; if that worker spawns tests, the nested path is /root/reviewer/tests. Roder supports at most five nested levels below /root and rejects deeper spawns before creating thread state.

Messages and follow-ups

send_message and followup_task deliberately behave differently. Use send_message when a running teammate should see more context at a safe boundary. Use followup_task when the teammate should start or continue a turn. Inter-agent messages use typed MESSAGE, NEW_TASK, andFINAL_ANSWER envelopes with canonical sender and recipient paths.

Waiting and interruption

wait_agent can wait for one teammate or any accessible teammate. A terminal result includes completed, failed, interrupted, or closed status plus optional final text and terminal error. The same terminal result is delivered automatically to the direct parent mailbox, so the parent can continue from the next inference round.

interrupt_agent targets only the active turn. It does not delete the teammate, clean up the team, or invalidate the canonical path. Assign later work withfollowup_task.

Client control plane

App-server clients use the matching team/* methods: team/start,team/read, team/member/start, team/member/message,team/member/interrupt, and team/cleanup. Team notifications include started members, status changes, message deltas, and completed-member payloads with optional finalMessage and error.