feat: sub-agent background execution, TUI panel, and CLI commands (M28-E/F/G)

CHANGELOG.md

@@ -20,6 +20,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Zero-trust permission model with TTL-based grants and automatic revocation (#713)
 - In-process A2A channels for orchestrator-to-sub-agent communication
 - `PermissionGrants` with audit trail via tracing
+- Real LLM loop wired into `SubAgentManager::spawn()` with background tokio task execution (#714)
+- `poll_subagents()` on `Agent<C>` for collecting completed sub-agent results (#714)
+- `shutdown_all()` on `SubAgentManager` for graceful teardown (#714)
+- `SubAgentMetrics` in `MetricsSnapshot` with state, turns, elapsed time (#715)
+- TUI sub-agents panel (`zeph-tui` widgets/subagents) with color-coded states (#715)
+- `/agent` CLI commands: `list`, `spawn`, `bg`, `status`, `cancel`, `approve`, `deny` (#716)
+- Typed `AgentCommand` enum with `parse()` for type-safe command dispatch replacing string matching in the agent loop
+- `@agent_name` mention syntax for quick sub-agent invocation with disambiguation from `@`-triggered file references
 
 ### Changed
 - Migrated all 6 hardcoded filters (cargo_build, test_output, clippy, git, dir_listing, log_dedup) into the declarative TOML engine

README.md

@@ -117,6 +117,16 @@ zeph skill unblock <name>      Unblock a previously blocked skill
 
 # Custom skill secrets use the ZEPH_SECRET_* prefix:
 zeph vault set ZEPH_SECRET_GITHUB_TOKEN ghp_...   # injected as GITHUB_TOKEN for skills that require it
+
+# In-session sub-agent commands:
+/agent list                    List available sub-agent definitions
+/agent spawn <name> <prompt>   Spawn a sub-agent with a task prompt
+/agent bg <name> <prompt>      Spawn a background sub-agent
+/agent status                  Show active sub-agents with state, turns, and elapsed time
+/agent cancel <id>             Cancel a running sub-agent by ID prefix
+
+# @mention shorthand (equivalent to /agent spawn):
+@code-reviewer check the auth module
 ```
 
 ## Automated Context Engineering
@@ -289,7 +299,7 @@ Skills can declare **required secrets** via the `x-requires-secrets` frontmatter
 |----------|-------------|
 | **MCP** | Connect external tool servers (stdio + HTTP) with SSRF protection, command allowlist, and env var blocklist |
 | **A2A** | Agent-to-agent communication via JSON-RPC 2.0 with SSE streaming |
-| **Sub-agent orchestration** | Spawn scoped sub-agents with zero-trust permissions, filtered tools/skills, and A2A-based in-process channels |
+| **Sub-agent orchestration** | Spawn scoped sub-agents with zero-trust permissions, background execution, filtered tools/skills, and A2A-based in-process channels; manage via `/agent` CLI commands |
 | **Audio input** | Speech-to-text via OpenAI Whisper API or local Candle Whisper (offline, feature-gated); Telegram and Slack audio files transcribed automatically |
 | **Vision** | Image input via CLI (`/image`), TUI (`/image`), and Telegram photo messages; supported by Claude, OpenAI, and Ollama providers (20 MB max, automatic MIME detection) |
 | **Channels** | CLI (with persistent input history), Telegram (text + voice), Discord, Slack, TUI — all with streaming support |
@@ -308,6 +318,7 @@ A full terminal UI powered by ratatui — not a separate monitoring tool, but an
 - Command palette for quick access to agent actions
 - Live metrics: token usage, filter savings, cost tracking, confidence distribution
 - Conversation history with message queueing
+- Sub-agent panel: live status, turn count, elapsed time, and background markers for all active sub-agents
 - Responsive input handling during streaming with render cache and event batching
 - Deferred model warmup with progress indicator
 

crates/zeph-core/README.md

@@ -9,7 +9,7 @@ Core agent loop, configuration, context builder, metrics, vault, and sub-agent o
 
 ## Overview
 
-Core orchestration crate for the Zeph agent. Manages the main agent loop, bootstraps the application from TOML configuration with environment variable overrides, and assembles the LLM context from conversation history, skills, and memory. Includes sub-agent orchestration with zero-trust permission grants, filtered tool/skill access, and A2A-based in-process communication channels. All other workspace crates are coordinated through `zeph-core`.
+Core orchestration crate for the Zeph agent. Manages the main agent loop, bootstraps the application from TOML configuration with environment variable overrides, and assembles the LLM context from conversation history, skills, and memory. Includes sub-agent orchestration with zero-trust permission grants, background execution, filtered tool/skill access, A2A-based in-process communication channels, and `/agent` CLI commands for runtime management. All other workspace crates are coordinated through `zeph-core`.
 
 ## Key modules
 
@@ -19,7 +19,7 @@ Core orchestration crate for the Zeph agent. Manages the main agent loop, bootst
 | `agent::tool_execution` | Tool call handling, redaction, and result processing |
 | `agent::message_queue` | Message queue management |
 | `agent::builder` | Agent builder API |
-| `agent::commands` | Chat command dispatch (skills, feedback, skill management via `/skill install` and `/skill remove`, etc.) |
+| `agent::commands` | Chat command dispatch (skills, feedback, skill management via `/skill install` and `/skill remove`, sub-agent management via `/agent`, etc.) |
 | `agent::utils` | Shared agent utilities |
 | `bootstrap` | `AppBuilder` — fluent builder for application startup |
 | `channel` | `Channel` trait defining I/O adapters; `LoopbackChannel` / `LoopbackHandle` for headless daemon I/O; `Attachment` / `AttachmentKind` for multimodal inputs |
@@ -33,7 +33,7 @@ Core orchestration crate for the Zeph agent. Manages the main agent loop, bootst
 | `vault` | Secret storage and resolution via vault providers (age-encrypted read/write); scans `ZEPH_SECRET_*` keys to build the custom-secrets map used by skill env injection |
 | `diff` | Diff rendering utilities |
 | `pipeline` | Composable, type-safe step chains for multi-stage workflows |
-| `subagent` | Sub-agent orchestration: `SubAgentManager` lifecycle, `SubAgentDef` TOML definitions, `PermissionGrants` zero-trust delegation, `FilteredToolExecutor` scoped tool access, A2A in-process channels |
+| `subagent` | Sub-agent orchestration: `SubAgentManager` lifecycle with background execution, `SubAgentDef` TOML definitions, `PermissionGrants` zero-trust delegation, `FilteredToolExecutor` scoped tool access, A2A in-process channels, real-time status tracking |
 
 **Re-exports:** `Agent`
 
@@ -55,6 +55,21 @@ auto_update_check = true   # set to false to disable update notifications
 
 Set `ZEPH_AUTO_UPDATE_CHECK=false` to disable without changing the config file.
 
+## Sub-agent Commands
+
+In-session commands for managing sub-agents:
+
+| Command | Description |
+|---------|-------------|
+| `/agent list` | List available sub-agent definitions |
+| `/agent spawn <name> <prompt>` | Spawn a sub-agent with a task prompt |
+| `/agent bg <name> <prompt>` | Spawn a background sub-agent |
+| `/agent status` | Show active sub-agents with state, turns, and elapsed time |
+| `/agent cancel <id>` | Cancel a running sub-agent by ID prefix |
+| `@agent_name <prompt>` | Mention shorthand for `/agent spawn` (disambiguated from file references) |
+
+Sub-agents run as independent tokio tasks with their own LLM provider and filtered tool executor. Each sub-agent receives only explicitly granted tools, skills, and secrets via `PermissionGrants`.
+
 ## Installation
 
 ```bash