flynn/docs/plans/2026-02-26-subagents-support-plan.md

Subagents Support Plan (Flynn)

Date: 2026-02-26
Status: phase 1 implemented
Scope: add OpenClaw-style multi-turn subagent session support in Flynn without changing channel surface scope (Telegram-first)

Constraints

1. Keep channel scope unchanged (Telegram remains default for now).
2. Deliver subagent capability through the existing native tool loop.
3. Keep gateway protocol additive-only (no new JSON-RPC methods required).

Phase 1 (Implemented in this change)

1. Added subagent runtime manager (src/backends/native/subagents.ts) that can:
   • spawn child sessions,
   • send follow-up turns,
   • list active child sessions,
   • cancel in-flight child runs,
   • delete child sessions.
2. Added new tools:
   • subagent.spawn
   • subagent.send
   • subagent.list
   • subagent.cancel
   • subagent.delete
3. Wired tools into per-session router orchestration (src/daemon/routing.ts).
4. Added config guardrails under agents.subagents:
   • enabled
   • max_active_sessions
5. Added policy/profile support so subagent.* is controlled through group:agents and tool profiles.

Phase 2 (Next)

1. Add per-subagent TTL/idle eviction and auto-cleanup metrics.
2. Add optional transcript export/summarization (subagent.summary).
3. Add per-subagent tool-profile override (read-only by default for risky workloads).
4. Add parent-child trace IDs in audit events for easier debugging.

Phase 3 (Stretch)

1. Add queue semantics for child sessions (followup vs interrupt per subagent).
2. Add explicit resource budgets (token/time) per child session.
3. Add UI affordances in gateway chat for subagent session inspection.

Acceptance Criteria (Phase 1)

1. Parent agent can spawn and continue a child subagent across multiple turns.
2. Child session state is isolated and delete clears history.
3. Recursion tooling (agent.delegate, council.run, subagent.*) is removed from child registries.
4. Tests cover manager lifecycle, tool behavior, config parsing, and policy profile inclusion.