zeph-subagent Crate

Subagent management for Zeph — spawning, grants, transcripts, and lifecycle hooks.

Purpose

zeph-subagent manages autonomous agents spawned from within the main agent. Each subagent has scoped tools, skills, memory, and zero-trust secret delegation. Subagents can operate in the background, produce persistent transcripts, and are managed via TOML definitions or interactive CLI.

Key Types

• SubAgentManager — Manages subagent lifecycle (spawn, pause, resume, stop)
• SubAgentDef — YAML/TOML definition of a subagent (tools, skills, grants, memory scope)
• SubAgentHandle — Reference to a running subagent with state, stdin/stdout
• SubAgentGrant — Fine-grained permission (tool name, input filter, memory scope)
• SubAgentCommand — Control commands (pause, resume, cancel, get transcript)

Features

• Scoped execution — Subagents use allowlist of tools/skills, not full access
• Memory isolation — User/project/local memory scopes for persistent state
• Transcript persistence — Conversation history stored in JSONL for audit and replay
• Grants system — Fine-grained permission model with deny/allow lists
• Lifecycle hooks — PreToolUse / PostToolUse for monitoring/filtering
• Fire-and-forget — Background execution with max_turns limit
• Session resume — /agent resume to continue completed sessions
• Interactive UI — TUI agents panel for real-time management

Usage

Define a subagent (YAML)

# .zeph/agents/researcher.yaml
name: researcher
tools:
  - web_search
  - file_read
memory: project
max_turns: 20
background: false
permission_mode: accept_edits

tools_except:
  - write_file  # researcher can't write files

Spawn from Markdown

# Sub-agent: Code Reviewer

Specialized code reviewer agent with denied write access.

**Definition:**
- **tools**: code_search, read_file, git_show
- **deny**: write_file, shell
- **memory**: project

Manage via CLI

zeph agents list                    # list all subagents
zeph agents show researcher         # show definition
zeph agents create my-agent.yaml    # create new subagent
zeph agents delete researcher       # delete subagent

Feature Flags

• None — subagent is unconditional (always enabled)

Dependencies

• zeph-config — SubAgentConfig for configuration
• zeph-memory — SemanticMemory for transcript and memory scope storage
• zeph-tools — ToolExecutor for executing subagent tools
• zeph-skills — SkillRegistry for subagent skill access
• zeph-common — Shared utilities

Integration with zeph-core

Re-exported via zeph-core as crate::subagent::*:

#![allow(unused)]
fn main() {
use zeph_core::subagent::{SubAgentManager, SubAgentDef, SubAgentHandle};
}

All public types are available via the re-export shim in zeph-core/src/lib.rs.

Configuration

In config.toml:

[agent.subagents]
enabled = true
default_permission_mode = "accept_edits"

[[agent.subagents.hooks]]
event = "PreToolUse"
# trigger custom logic before tool execution

CLI Commands

• zeph agents list — List all defined subagents
• zeph agents show <name> — Show subagent definition
• zeph agents create <path> — Create new subagent from YAML/Markdown
• zeph agents edit <name> — Edit subagent definition interactively
• zeph agents delete <name> — Delete a subagent definition
• /agent resume <id> — Resume a completed subagent session (TUI)

Documentation

Full API documentation: docs.rs/zeph-subagent

mdBook reference: Sub-agents

License

MIT