zeph_subagent/
lib.rs

1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Subagent management: spawning, grants, transcripts, and lifecycle hooks.
5//!
6//! `zeph-subagent` provides the full lifecycle of sub-agent tasks within the Zeph agent
7//! framework. It covers:
8//!
9//! - **Definitions** ([`SubAgentDef`]) — parse YAML/TOML frontmatter from `.md` files,
10//!   validate names and permissions, and load from priority-ordered directories.
11//! - **Manager** ([`SubAgentManager`]) — spawn, cancel, collect, and resume sub-agent tasks
12//!   against a configurable concurrency limit.
13//! - **Grants** ([`PermissionGrants`]) — zero-trust TTL-bounded permission tracking for
14//!   vault secrets and runtime tool grants.
15//! - **Hooks** ([`fire_hooks`]) — run shell commands at `PreToolUse`, `PostToolUse`,
16//!   `SubagentStart`, and `SubagentStop` lifecycle events.
17//! - **Filter** ([`FilteredToolExecutor`]) — enforce per-agent [`ToolPolicy`] and denylist
18//!   on every tool call before it reaches the real executor.
19//! - **Transcripts** ([`TranscriptWriter`], [`TranscriptReader`]) — persist conversation
20//!   history to JSONL files for session resume and auditing.
21//! - **Memory** ([`ensure_memory_dir`], [`load_memory_content`]) — resolve and inject
22//!   persistent `MEMORY.md` content into the sub-agent system prompt.
23//! - **Commands** ([`AgentCommand`], [`AgentsCommand`]) — typed parsers for `/agent` and
24//!   `/agents` slash commands.
25//!
26//! # Quick start
27//!
28//! ```rust,no_run
29//! use std::sync::Arc;
30//! use zeph_subagent::{SubAgentDef, SubAgentManager};
31//!
32//! // Parse a definition from markdown frontmatter.
33//! let content = "---\nname: helper\ndescription: A helpful sub-agent\n---\nYou are a helper.\n";
34//! let def = SubAgentDef::parse(content).expect("valid definition");
35//! assert_eq!(def.name, "helper");
36//!
37//! // Create a manager with a concurrency limit of 4.
38//! let _manager = SubAgentManager::new(4);
39//! ```
40
41mod agent_loop;
42pub mod command;
43pub mod cwd_guard;
44pub mod def;
45pub mod error;
46pub mod filter;
47pub mod fleet;
48pub mod grants;
49pub mod hooks;
50pub mod manager;
51pub mod memory;
52pub mod resolve;
53pub mod state;
54pub mod transcript;
55
56pub use command::{AgentCommand, AgentsCommand};
57pub use cwd_guard::CwdLock;
58pub use def::{
59    MemoryScope, ModelSpec, PermissionMode, SkillFilter, SubAgentDef, SubAgentPermissions,
60    ToolPolicy, is_valid_agent_name,
61};
62pub use error::SubAgentError;
63pub use filter::{FilteredToolExecutor, PlanModeExecutor, filter_skills};
64pub use fleet::{FleetRegistry, FleetSessionInfo, FleetSessionStatus, SharedFleetRegistry};
65pub use grants::{Grant, GrantKind, PermissionGrants, SecretRequest};
66pub use hooks::{
67    HookAction, HookDef, HookError, HookMatcher, HookOutput, HookRunResult, McpDispatch,
68    PostToolUseHookInput, SubagentHooks, TOOL_ARGS_JSON_LIMIT, fire_hooks, make_base_hook_env,
69    matching_hooks,
70};
71pub use manager::{SpawnContext, SubAgentHandle, SubAgentManager, SubAgentStatus};
72pub use memory::{ensure_memory_dir, load_memory_content};
73pub use resolve::resolve_agent_paths;
74pub use state::SubAgentState;
75pub use transcript::{TranscriptMeta, TranscriptReader, TranscriptWriter, sweep_old_transcripts};
76
77/// Async callback type for spawning an external ACP sub-agent by shell command.
78///
79/// Returns the sub-agent's text output on success or an error string on failure.
80/// Installed via `AgentBuilder::with_acp_subagent_spawn_fn` when the `acp` feature is enabled.
81pub type AcpSubagentSpawnFn = std::sync::Arc<
82    dyn Fn(
83            String,
84        ) -> std::pin::Pin<
85            Box<dyn std::future::Future<Output = Result<String, String>> + Send + 'static>,
86        > + Send
87        + Sync,
88>;
zeph_subagent/lib.rs

zeph_subagent/
lib.rs
