feat: add recursive interactive tmux subagents

[ShaanNarendran]

Purpose

Add daemon-owned recursive child sessions and project them into interactive tmux panes. The feature keeps one authoritative daemon, gives each child a separate durable transcript and context window, returns bounded attributed results bottom-up, and keeps model-visible delegation disabled unless the user explicitly enables pane mode.

Related to #77 and #85.

Approach

• Add wire-version 14 child start/send contracts and canonical child relationship, input, and result events.
• Add SDK child methods and deterministic child lifecycle projection.
• Add recursive daemon-owned delegation with fresh model-created contexts, separate JSONL logs, bottom-up synthesis, serialized tree mutation, policy narrowing, provider selection, and bounded result delivery.
• Enforce three descendant levels, four direct children per node, and twelve total descendants.
• Cascade interruption and disposal through the child tree.
• Add a trusted tmux CLI adapter. Pane commands use fixed argv and captured server, window, pane, title, and child-session identity.
• Use tmux's tiled layout so larger trees use rows and columns.
• Tag tmux child panes with their session identity, verify pane ownership before focus or closure, and close all verified managed panes during coordinated daemon shutdown.
• Keep aborted panes for inspection. Close completed and failed panes after their result reaches the parent.
• Preserve upstream provider management, daemon lifecycle, request settings, and atomic interrupt-and-deliver behavior during the rebase.

Security and compatibility:

• Ordinary sessions receive no subagent tools or delegation prompt.
• Child authority, tools, profiles, provider configuration, depth, and capacity are validated by the daemon.
• Child policy may narrow parent authority but cannot widen it.
• Pane IDs, titles, session names, socket paths, and multiplexer output are validated and bounded.
• Wire protocol advances from 13 to 14 because child RPCs and canonical child metadata change accepted wire data.

How was this tested?

Passed:

pnpm install --frozen-lockfile
pnpm build
pnpm typecheck
pnpm lint
pnpm format:check
pnpm check:boundaries
pnpm check:generated
pnpm audit --audit-level high

Focused protocol, SDK, daemon, runtime, CLI, and TUI runs passed, including:

node --test packages/protocol/test/*.test.ts
node --test packages/sdk/test/*.test.ts
node --test packages/daemon/test/child-session.test.ts
node --test packages/runtime/test/local-runtime.test.ts
node --test packages/cli/test/tmux.test.ts
node --test packages/cli/test/tmux.test.ts

Focused coverage includes:

• three-level recursive authority;
• four-direct-child and twelve-descendant limits;
• concurrent sibling-name serialization;
• bottom-up result propagation;
• parent completion waiting for descendants;
• bounded model-visible results with complete child transcripts retained;
• policy and provider narrowing;
• interruption and disposal cascades;
• child attachment during active work;
• pane ownership, focus, layout, and shutdown cleanup.

Manual tmux verification passed:

• a recursive live-model tree spawned children and grandchildren through one daemon;
• results propagated to immediate parents before reaching the root;
• a 12-child test used a tiled row-and-column layout in a 240x60 window;
• coordinated cleanup removed every tagged child pane and retained the parent;
• inherited tmux remain-on-exit configuration was restored.

A complete pnpm test run reported 842 passing, 20 skipped, and 9 failing tests. The remaining failures are host-specific sandbox integration failures involving macOS Seatbelt behavior, Linux /proc assumptions, and filesystem-policy integration. Relevant subagent, protocol, SDK, daemon, runtime, CLI, and TUI tests pass.

reuse lint could not be run because the reuse executable is not installed. SPDX headers were reviewed, and every new source or documentation file carries SPDX-FileCopyrightText: 2026 Shaan Narendran and SPDX-License-Identifier: Apache-2.0.

Manual test guide

See docs/guides/interactive-subagents.md.

The guide includes prerequisites, cleanup, expected pane behavior, controls, troubleshooting, and this recursive test shape:

root
└── lead-coordinator
    ├── architecture-reviewer
    │   ├── boundary-reviewer
    │   └── lifecycle-reviewer
    └── test-reviewer
        └── coverage-reviewer

It also contains a complete prompt users can paste into:

axl --subagent-panes tmux

Learning

The pane UX was informed by the public behavior and documentation of amosblomqvist/pi-interactive-subagents, particularly asynchronous result delivery and tmux layout behavior. The Axl implementation was written independently around Axl's daemon, protocol, SDK, policy, and canonical-log architecture. No source was copied or translated.

Checklist

• I reviewed the complete diff.
• I added or updated the smallest relevant test for behavior changes.
• I ran the relevant formatting, lint, type-check, test, and boundary checks.
• reuse lint completed locally. The executable is not installed; SPDX headers were reviewed manually.
• Every new file has SPDX metadata.
• Every commit has a matching DCO Signed-off-by trailer.
• UI screenshots are not attached yet. Screenshots were not committed to the repository.

AI assistance

• Generative AI materially assisted this change. Tools and model/version: Pi coding agent and Axl coding agent, both using GPT-5.6-sol.
• I manually reviewed, understood, and tested the generated work.