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

Subagents Support Plan (Flynn)

Date: 2026-02-26
Status: phases 1-3 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 (Implemented)

1. Added idle TTL eviction plus audit lifecycle events for cleanup visibility.
2. Added transcript export/summarization via subagent.summary.
3. Added per-subagent tool-profile override (queue_mode, tool_profile on spawn).
4. Added parent-child trace IDs and subagent lifecycle/turn audit events.

Phase 3 (Implemented)

1. Added queue semantics per child session (followup FIFO, interrupt latest-wins).
2. Added explicit resource budgets (max turns, max total tokens, per-turn timeout).
3. Added operator/UI affordances:
   • /subagents command (list/summary/cancel/delete),
   • gateway chat slash suggestion for /subagents.

Final Acceptance Criteria

1. Parent agent can spawn and continue child subagents 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. Child sessions support queue policy + budget guardrails + transcript inspection.
5. Tests cover manager lifecycle, tool behavior, config parsing, routing command wiring, and audit event logging.