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