Kairo

Appearance

ADR-031: Task-Scoped Agent Collaboration ​

Status ​

Accepted (2026-07-15). Supersedes ADR-015 and ADR-016.

Context ​

Kairo previously exposed two orchestration models:

  • a parent Agent that could delegate work to independent child Agents; and
  • an Expert Team subsystem with persistent Team objects, fixed expert roles, a second coordinator, a separate state machine, Team CRUD tools, Team memory, and evaluator loops.

The second model duplicated responsibilities that already belong to the parent Agent: planning, dispatch, messaging, cancellation, retries, acceptance, and final synthesis. It also made role names carry unrelated concerns such as task risk and verification. Kairo Code never adopted the Team runtime; its production path uses one task-scoped Subagent model.

Decision ​

Kairo has one collaboration model composed of four orthogonal concepts:

  1. Agent Profile — a stateless reusable capability definition. It contains instructions and optional model, reasoning, sandbox, skill, MCP, and tool ceilings.
  2. Assignment — one bounded goal, acceptance criteria, selected workspace roots, and risk classification. Risk belongs to the assignment, never to the Profile name.
  3. Agent Thread — one running invocation with independent context, lifecycle, messages, cancellation, usage, and diagnostics. A task-scoped child invocation is a Subagent.
  4. Acceptance Policy — deterministic checks and optional independent model review driven by assignment risk and host-observed execution evidence.

The parent Agent owns decomposition, dispatch, steering, waiting, and final acceptance. Multiple active Agent Threads may be presented as a collaboration view, but that projection is not a Team runtime or persistent Team resource.

Runtime invariants ​

  • A child always has an independent context and remains inside its parent session tree.
  • A child inherits the parent's live permission policy atomically. Profiles may only narrow it.
  • Model and reasoning overrides are optional optimizations; one configured model is sufficient.
  • Verification is an acceptance phase. A reviewer Profile is not proof that work was verified.
  • High-impact writes cannot opt out of independent verification.
  • Workspaces, payloads, task depth, concurrency, and evidence are bounded by the host runtime.
  • Child completion, cancellation, and result publication have one terminal owner.

Built-in roles ​

The framework does not define a taxonomy of domain experts. Products may provide a deliberately small execution vocabulary. Kairo Code uses default, worker, and explorer; deeper analysis, testing, reviewing, and security work are assignments or custom Profiles rather than more runtime types.

Removed surfaces ​

Because Kairo has not shipped publicly, the conflicting model is removed without compatibility shims:

  • io.kairo.api.team and TeamCoordinator;
  • kairo-multi-agent and both multi-agent starters;
  • Expert roles, Expert Profiles, Team state machines, MoA, Team memory, and Team CRUD;
  • the special CoordinatorAgent and untracked agent_spawn tool.

Reusable admission policy moves to kairo-core. Agent Profile parsing and registration remain in the plugin subsystem. A product runtime registers its session-bound task, messaging, and steering tools only after a live parent session and permission boundary exist.

Consequences ​

Positive ​

  • One execution vocabulary across Java runtime, CLI, server protocol, and UI.
  • Fewer model-visible tools and fewer ways to start untracked child work.
  • Role selection, cost tuning, and verification can evolve independently.
  • Collaboration state maps directly to Agent Threads and can be restored without reconstructing a synthetic Team object.
  • Security policy is enforced by the runtime instead of role prose.

Trade-offs ​

  • Applications built against experimental Team APIs must adopt task-scoped Subagents.
  • Generic Subagent execution remains intentionally session-bound; it cannot be auto-configured as a context-free singleton.
  • Alternative choreographies such as debate or mixture-of-agents must first demonstrate measurable quality-per-token gains before being added as policies over the same runtime.

Verification ​

  • The upstream reactor must contain no Team/Expert module or API package.
  • Kairo Code must compile without kairo-multi-agent.
  • Source scans must find no production reference to TeamCoordinator, CoordinatorAgent, agent_spawn, Team CRUD, or Team memory.
  • Runtime tests must continue covering independent context, permission inheritance, bounded concurrency, cancellation, steering, and evidence-based verification.