Struct SubAgentConfig 

pub struct SubAgentConfig {

    pub enabled: bool,
    pub delegation_mode: DelegationMode,
    pub max_concurrent: usize,
    pub max_spawns_per_session: usize,
    pub extra_dirs: Vec<PathBuf>,
    pub user_agents_dir: Option<PathBuf>,
    pub default_permission_mode: Option<PermissionMode>,
    pub default_disallowed_tools: Vec<String>,
    pub allow_bypass_permissions: bool,
    pub default_memory_scope: Option<MemoryScope>,
    pub hooks: SubAgentLifecycleHooks,
    pub transcript_dir: Option<PathBuf>,
    pub transcript_enabled: bool,
    pub transcript_max_files: usize,
    pub forward_transcript: bool,
    pub context_window_turns: usize,
    pub max_spawn_depth: u32,
    pub context_injection_mode: ContextInjectionMode,
    pub parent_context_policy: ParentContextPolicy,
    pub max_parent_messages: usize,
    pub summary_max_chars: usize,
    pub llm_timeout_secs: u64,
    pub worktree: WorktreeConfig,
}

Sub-agent pool configuration, nested under [agents] in TOML.

When enabled = true, the agent can spawn isolated sub-agent sessions from SKILL.md-based agent definitions. Sub-agents inherit the parent’s provider pool unless overridden by model in their definition frontmatter.

Example (TOML)

[agents]
enabled = true
delegation_mode = "explicit_request_only"
max_concurrent = 3
max_spawn_depth = 2
max_spawns_per_session = 50

Fields

enabled: bool

Enable the sub-agent subsystem. Default: false.

Outer kill switch: when false, the effective delegation_mode is always DelegationMode::Disabled regardless of that field’s configured value (spec 042-subagent-delegation-mode-parity FR-002).

delegation_mode: DelegationMode

Whether the main agent may spawn sub-agents, and who may trigger it: disabled / explicit_request_only / proactive. Default: DelegationMode::Proactive (preserves the subsystem’s unconstrained behavior prior to this field’s introduction, per FR-008). Overridable via ZEPH_AGENTS_DELEGATION_MODE or the --delegation-mode CLI flag.

max_concurrent: usize

Maximum number of sub-agents that can run concurrently.

max_spawns_per_session: usize

Maximum cumulative number of sub-agents that may be spawned within a single session, independent of max_concurrent (in-flight limit) and max_spawn_depth (recursion limit). Guards against a shallow, low-concurrency but high-frequency sequential delegation loop that neither of those limits would catch (issue #6545). 0 = unlimited. The counter resets at session start and is shared across every spawn chokepoint (SubAgentManager::spawn/resume and the ACP /subagent spawn path). Default: 100.

extra_dirs: Vec<PathBuf>

Additional directories to search for .agent.md definition files.

user_agents_dir: Option<PathBuf>

User-level agents directory.

default_permission_mode: Option<PermissionMode>

Default permission mode applied to sub-agents that do not specify one.

default_disallowed_tools: Vec<String>

Global denylist applied to all sub-agents in addition to per-agent tools.except.

allow_bypass_permissions: bool

Allow sub-agents to use bypass_permissions mode.

default_memory_scope: Option<MemoryScope>

Default memory scope applied to sub-agents that do not set memory in their definition.

hooks: SubAgentLifecycleHooks

Lifecycle hooks executed when any sub-agent starts or stops.

transcript_dir: Option<PathBuf>

Directory where transcript JSONL files and meta sidecars are stored.

transcript_enabled: bool

Enable writing JSONL transcripts for sub-agent sessions.

transcript_max_files: usize

Maximum number of .jsonl transcript files to keep.

forward_transcript: bool

Forward each running sub-agent’s full, untruncated per-turn text/thinking output to an active consumer surface (TUI runtime detail view and/or --bare stdout) as it is produced, instead of only the 120-char once-per-turn status snippet (issue #6359, spec 068-subagent-transcript-forward). Default: false — disabling it (the default) preserves today’s exact SubAgentStatus/collect() behavior byte-for-byte. Mirrors CLAUDE_CODE_FORWARD_SUBAGENT_TEXT; overridable via ZEPH_AGENTS_FORWARD_TRANSCRIPT or the --forward-subagent-text CLI flag.

context_window_turns: usize

Number of recent parent conversation turns to pass to spawned sub-agents. Set to 0 to disable history propagation.

max_spawn_depth: u32

Maximum nesting depth for sub-agent spawns.

context_injection_mode: ContextInjectionMode

How parent context is injected into the sub-agent’s task prompt.

parent_context_policy: ParentContextPolicy

Whether to sanitize parent conversation history before passing to a spawned sub-agent.

Defaults to ParentContextPolicy::InheritSanitized which runs each text message part through the IPI sanitizer, stripping prompt-injection payloads that may have entered the parent history via tool results, web scrapes, or A2A messages.

max_parent_messages: usize

Maximum number of parent messages to inject, independent of context_window_turns.

Acts as a hard upper bound on context propagation volume to limit the blast radius of poisoned histories. When max_parent_messages < context_window_turns * 2 this cap wins and fewer messages are passed; otherwise context_window_turns * 2 is the binding limit. The tighter of the two limits always applies.

summary_max_chars: usize

Maximum character count for the Summary context injection mode.

When context_injection_mode = "summary", the extracted summary is truncated to this many characters at a UTF-8 char boundary before being prepended to the sub-agent’s task prompt. Consistent with the max_state_chars naming convention.

Default: 600 (≈200 tokens at 3 chars/token).

llm_timeout_secs: u64

Maximum wall time in seconds for a single LLM call inside a sub-agent turn.

If the provider does not return a response within this window, the call is cancelled and the sub-agent turn fails with a timeout error. Default: 120.

worktree: WorktreeConfig

Worktree isolation settings propagated from the top-level [worktree] section.

Passed to the subagent manager’s spawn function so it can determine whether and how to create a per-agent git worktree without needing a reference to the full Config.

Invariant

This field is always populated from Config::worktree in runner.rs bootstrap. Do not set defaults independently — changes here will not take effect in production because the bootstrap overwrites this value before passing it to SubAgentManager.

Implementations

impl SubAgentConfig

pub fn effective_delegation_mode(&self) -> DelegationMode

Resolve enabled and delegation_mode into the single effective mode that must be enforced at every spawn call site (spec 042-subagent-delegation-mode-parity FR-002, issue #5857).

enabled is the outer kill switch: enabled = false always resolves to DelegationMode::Disabled, regardless of the configured delegation_mode value.

Examples

use zeph_config::{DelegationMode, SubAgentConfig};

let mut cfg = SubAgentConfig {
    enabled: false,
    delegation_mode: DelegationMode::Proactive,
    ..SubAgentConfig::default()
};
assert_eq!(cfg.effective_delegation_mode(), DelegationMode::Disabled);

cfg.enabled = true;
assert_eq!(cfg.effective_delegation_mode(), DelegationMode::Proactive);

Trait Implementations

impl Clone for SubAgentConfig

fn clone(&self) -> SubAgentConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SubAgentConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for SubAgentConfig

fn default() -> SubAgentConfig

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for SubAgentConfig

where SubAgentConfig: Default,

fn deserialize<__D>( __deserializer: __D, ) -> Result<SubAgentConfig, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for SubAgentConfig

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.