[Epic] Sub-Agent System v2

[bug-ops]

Overview

A comprehensive upgrade of Zeph's sub-agent system, bringing it to feature parity with Claude Code's agent capabilities. The work covers the full lifecycle: file-based definitions, multi-scope discovery, built-in agents, resume/transcript persistence, persistent memory, worktree isolation, lifecycle hooks, fine-grained permissions, skill preloading, and a management interface.

Motivation

Zeph's current sub-agent system (SubAgentDef, SubAgentManager, FilteredToolExecutor) provides the structural foundation but lacks the operational features needed for production use. Users cannot define agents as files, agents have no persistent memory, there is no resume capability, and there is no management interface. Claude Code's agent system — studied at https://code.claude.com/docs/en/sub-agents — provides a well-validated feature set that maps cleanly onto Zeph's architecture.

Issues

• File-based sub-agent definitions (Markdown + YAML frontmatter in .zeph/agents/) #963 — File-based sub-agent definitions (Markdown + YAML frontmatter in .zeph/agents/)
• Multi-scope agent file discovery with priority resolution #964 — Multi-scope agent file discovery with priority resolution
• Built-in sub-agents: Explore, Plan, Summarizer #965 — Built-in sub-agents: Explore, Plan, Summarizer
• Sub-agent resume and transcript persistence #966 — Sub-agent resume and transcript persistence
• Persistent memory for sub-agents (user/project/local scopes) #967 — Persistent memory for sub-agents (user/project/local scopes)
• Worktree isolation for sub-agents #968 — Worktree isolation for sub-agents
• Lifecycle hooks system (SubagentStart/Stop, PreToolUse/PostToolUse) #969 — Lifecycle hooks system (SubagentStart/Stop, PreToolUse/PostToolUse)
• disallowedTools denylist and Task(agent_type) spawn restrictions #970 — disallowedTools denylist and Task(agent_type) spawn restrictions
• permissionMode field per sub-agent #971 — permissionMode field per sub-agent
• Skill preloading into sub-agent context at startup #972 — Skill preloading into sub-agent context at startup
• /agents TUI/CLI management interface #973 — /agents TUI/CLI management interface

Recommended implementation order

1. File-based sub-agent definitions (Markdown + YAML frontmatter in .zeph/agents/) #963 (file format) — foundation for all other issues
2. Multi-scope agent file discovery with priority resolution #964 (discovery) — depends on File-based sub-agent definitions (Markdown + YAML frontmatter in .zeph/agents/) #963
3. disallowedTools denylist and Task(agent_type) spawn restrictions #970 (denylist + spawn restrictions) — extends existing FilteredToolExecutor
4. permissionMode field per sub-agent #971 (permissionMode) — extends existing FilteredToolExecutor
5. Built-in sub-agents: Explore, Plan, Summarizer #965 (built-in agents) — depends on File-based sub-agent definitions (Markdown + YAML frontmatter in .zeph/agents/) #963 and Multi-scope agent file discovery with priority resolution #964
6. Sub-agent resume and transcript persistence #966 (resume + transcripts) — independent of definition format
7. Persistent memory for sub-agents (user/project/local scopes) #967 (persistent memory) — depends on Sub-agent resume and transcript persistence #966 for agent ID
8. Worktree isolation for sub-agents #968 (worktree isolation) — independent
9. Lifecycle hooks system (SubagentStart/Stop, PreToolUse/PostToolUse) #969 (lifecycle hooks) — depends on Sub-agent resume and transcript persistence #966 for AgentId
10. Skill preloading into sub-agent context at startup #972 (skill preloading) — depends on File-based sub-agent definitions (Markdown + YAML frontmatter in .zeph/agents/) #963
11. /agents TUI/CLI management interface #973 (management interface) — depends on all above

Out of scope

• Agent-to-agent communication protocols (covered by A2A, see zeph-a2a).
• Streaming sub-agent output to Telegram channel.
• Sub-agent sandboxing via containers or VMs (worktree isolation is sufficient for v2).
• Web UI for agent management (TUI and CLI only).
• LLM provider-specific agent features (e.g. Anthropic computer use).