# 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.