Skip to main content

Sub-agents & orchestration internals

Delegation lets one agent hand work to another. Architecturally it is not a special execution mode — it is a tool call (invoke_agent), which is what keeps it inside every bound that applies to any other tool.

Why delegation is a tool​

Making delegation a tool rather than a runtime feature buys three properties for free:

  • it crosses the same trusted boundary, so the same authority bundle is re-checked;
  • it is subject to the same capability ceiling, so an agent cannot delegate its way to a tool it was not granted;
  • it is recorded through the same audit funnel, so an orchestration is reviewable like anything else.

There is no separate "orchestration authority" to reason about, because there is no separate path.

Effective roster, per member and per agent​

Member-configured delegation is off by default. Selection is stored per (member, agent) pair and exposed at /api/agent-subagent-selection. Protected source agents may also carry a reviewed delegation edge.

Which of those bounds a member's choice is one field, AgentSpec.subagent_ceiling:

  • a concrete ceiling clamps — a registry agent's authored subagent_allowlist, or a source agent that pins its reviewed edges (Agent Builder → Package Creator). The member selects within it and nothing else;
  • no declared ceiling hands the choice to the member. The general Default agent is deliberately in this class: its reviewed Web Researcher and Prompt Builder edges are the defaults it starts with, and the member can add any chat agent they can already select. Its own reviewed edges are always included, so a resolved bundle: ref can never fall outside its own ceiling.

That is not a widening. The addable ids come from the member's own ACL-scoped roster, the runner re-resolves the target under that same scope immediately before dispatch (an id the member cannot select returns target_unavailable), and the child still runs at min(parent ceiling, target ceiling).

Consequences worth stating plainly:

  • an agent's persona cannot enable delegation for itself;
  • an administrator default does not enable it for a member;
  • a model cannot expand its own roster mid-turn — the set is resolved server-side before the turn and a request body cannot reach past the member's own roster;
  • one member's selection never affects another's.

Deselecting an optional sub-agent closes the path at the next turn. A per-prompt reduction can also close a source-reviewed edge for that turn. There is no cached grant that outlives the turn and no teardown step to forget.

Self-delegation​

An agent may appear on its own roster, and the runner treats that as an ordinary target. Fan-out — the same persona over four slices, one child run each — is the reason. What bounds it is DG-4's depth cap, not a self-check: the child is at depth 1 and cannot delegate again, so recursion terminates after one level whatever the target is. Re-entering an ancestor is still refused as denied_cycle, which is what keeps that bound honest if the depth limit ever moves.

The roster capability​

list_available_agents is a shared, member-safe roster tool granted to every eligible chat agent. It exists so an agent can answer "what other agents are available?" without the routing layer injecting the full roster into every prompt.

The roster returns what the member has made available to that agent — not the deployment's full agent list. Each entry also carries invocable and, when false, an unavailable_reason (not_enabled, nested_run) drawn from the exact authority invoke_agent is bound to for that turn — a routing grant's single approved target, or the spec's effective delegate set. Discovery and dispatch therefore cannot disagree: an agent the roster calls invocable will run, and one it does not will be refused with a member-safe reason naming the remedy.

What a delegated turn inherits​

A sub-agent turn runs under the calling member's identity. It inherits:

  • the member's permissions, re-resolved per tool call,
  • the same budgets — delegation buys no extra tokens or wall-clock,
  • the same guardrails, write guard, and approval gates,
  • the same audit trail and journal.

It does not inherit the sub-agent author's access, and it cannot exceed the capability ceiling of the agent that invoked it. Delegation redistributes work; it never escalates authority.

The child keeps its own durable runtime journal for retry and recovery, but it does not create a standalone member transcript. Its complete member-safe answer is retained for the visible child card. A separate sentence-bounded projection is folded into the parent's prompt, which prevents parent-context growth from clipping the answer the member reads. Projection truncation and partial-runtime facts remain backend state. Parallel support tasks follow the same rule.

Execution patterns​

PatternFlagDefault
Sequential delegationAGENT_ORCHESTRATION_ENABLEDon
Parallel sub-agent executionAGENT_ORCHESTRATION_PARALLEL_ENABLEDon
Evaluator-optimizerAGENT_ORCHESTRATION_EVALUATOR_OPTIMIZER_ENABLEDoff

Parallel execution improves latency on genuinely independent sub-tasks. It does not raise the turn's budget — the parallel branches share it, which is what keeps a fan-out from being a way to buy more model steps.

Orchestration trace​

An orchestration produces a trace: which sub-agents were invoked, what each was asked, and how results folded back into the answer.

The trace is available while the orchestration runs and after it completes, and it can be resumed or cancelled through the member API. Like the task run trace, it references runtime sources rather than copying prompts, completions, or raw tool payloads into it.

Routing​

AGENT_ROUTING_ENABLED governs whether Kaizen may select an agent for a turn based on the request, rather than using the member's explicit choice.

Routing also evaluates Default's effective source-reviewed roster before the runtime starts. A high-confidence capability gap, such as a public technical comparison, creates one exact Web Researcher grant. Default remains the parent and must call that child before it completes the answer. The grant keeps invoke_agent directly visible, pins it to the selected child, and makes the handoff a required Turn Engine step. A parent substitute tool is refused; if the model tries to answer without the handoff, the runtime suppresses that premature answer and gives it one bounded retry. Matching is deterministic over reviewed compact cards and the current turn's action. Explicit references to material already in the conversation are removed from lexical routing, so a request to transform “this research” does not become another retrieval request. A source-only specialist must also add a capability the current action requires before the server forces a pre-dispatch handoff; fresh information, a new search, or current public sources satisfy that gate. When the gate does not fire, the source-reviewed delegation tool remains available to the coordinator, which may use it if producing the answer reveals a real evidence gap. At least one explicit routing-tag match is required, common comparison inflections are normalized, and generic overlap with a specialist's prose description cannot route a turn. A tie or no positive tag match stays with Default.

The exact required handoff is server-authored policy. It is supplied once as a system instruction, reinforced by the turn engine's required-tool interlock, and never appended to the member's message. The model chooses only the focused sub-task; it cannot choose a different recipient or broaden the tool grant.

Routing selects configuration, never authority. A routed agent still runs under the member's permissions and its own capability ceiling. A routing decision cannot be used to reach an agent the member could not have selected.

Bounded by construction​

Three limits make orchestration safe to leave on:

  1. Depth and fan-out are bounded server-side, not by the model's judgment.
  2. Budgets are per turn, not per agent. A coordinator that delegates ten times does not get eleven budgets.
  3. The write guard sits below delegation. A sub-agent proposing an external effect meets the same gate as a top-level agent, and the approval is evaluated against the initiating member.