Enum SubAgentError 

#[non_exhaustive]
pub enum SubAgentError {
    Parse {
        path: String,
        reason: String,
    },
    Invalid(String),
    NotFound(String),
    Spawn(String),
    ConcurrencyLimit {
        active: usize,
        max: usize,
    },
    Cancelled,
    InvalidCommand(String),
    Transcript(String),
    Integrity(String),
    AmbiguousId(String, usize),
    StillRunning(String),
    Memory {
        name: String,
        reason: String,
    },
    Io {
        path: String,
        reason: String,
    },
    Llm(String),
    Channel(String),
    TaskPanic(String),
    MaxDepthExceeded {
        depth: u32,
        max: u32,
    },
    WorktreeSetup(String),
    Durable(String),
    DelegationDenied {
        mode: DelegationMode,
        origin: SpawnOrigin,
        def_name: String,
    },
    SessionSpawnLimit {
        spawned: usize,
        max: usize,
    },
}

All errors that can arise during sub-agent lifecycle operations.

SubAgentError is the single error type for the entire zeph-subagent crate. Every fallible public function returns Result<_, SubAgentError>.

Examples

use zeph_subagent::{SubAgentDef, SubAgentError};

let err = SubAgentDef::parse("missing frontmatter").unwrap_err();
assert!(matches!(err, SubAgentError::Parse { .. }));

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Parse

Frontmatter parsing failed (malformed YAML/TOML or missing delimiters).

Fields

path: String

reason: String

Invalid(String)

Definition semantics are invalid (e.g. empty name, conflicting tool policies).

NotFound(String)

No definition or running agent with the requested name or ID was found.

Spawn(String)

The background task could not be spawned (OS or tokio error).

ConcurrencyLimit

The manager’s concurrency limit is exhausted; no new agents can be spawned.

Fields

active: usize

max: usize

Cancelled

The agent loop was cancelled via its tokio_util::sync::CancellationToken.

InvalidCommand(String)

A slash-command string (/agent, /agents) could not be parsed.

Transcript(String)

An I/O operation on a transcript file failed.

Integrity(String)

A transcript’s hash chain failed to verify (issue #6360): a definite tamper verdict, a partial strip of chain metadata, an unverifiable/possibly-re-keyed chain, or a chained file read with no history-integrity key configured. Distinct from SubAgentError::Transcript (JSON-syntax/I-O errors) because a chain break always escalates to a hard failure — even in TranscriptReader::load’s otherwise-lenient mode — since it invalidates trust in everything downstream of the break, unlike a single malformed line.

AmbiguousId(String, usize)

An ID prefix matched more than one transcript; provide a longer prefix.

StillRunning(String)

Resume was requested for an agent that is still running.

Memory

A memory directory could not be created or resolved.

Fields

name: String

reason: String

Io

A filesystem I/O error unrelated to transcripts.

Fields

path: String

reason: String

Llm(String)

The underlying LLM provider returned an error during the agent loop.

Channel(String)

A channel send (status watch, secret approval) failed.

TaskPanic(String)

The tokio task panicked and the join handle propagated the panic.

MaxDepthExceeded

The recursion depth for nested sub-agent spawning exceeded the configured limit.

Fields

depth: u32

max: u32

WorktreeSetup(String)

Worktree creation or cwd setup failed during agent spawn.

This error is returned when permissions.worktree = true and the worktree manager fails to create a dedicated worktree or cannot restore the working directory. The agent loop never starts in this case (INV-4).

Durable(String)

The durable promise layer returned an error during subagent spawn or await.

Wraps a zeph_durable::DurableError string so the crate does not take a hard compile-time dependency on zeph-durable in code paths where the feature is disabled at runtime (the durable module is always compiled in but the adapter functions are only called when durable.enabled && durable.subagent).

DelegationDenied

The spawn attempt was rejected by delegation_mode (spec 042-subagent-delegation-mode-parity, issue #5857): either delegation_mode = "disabled" (all spawns rejected) or delegation_mode = "explicit_request_only" and origin was SpawnOrigin::Autonomous. Distinct from SubAgentError::ConcurrencyLimit and SubAgentError::MaxDepthExceeded so the rejection reason is unambiguous in logs (FR-007).

Fields

mode: DelegationMode

origin: SpawnOrigin

def_name: String

SessionSpawnLimit

The session-wide cumulative spawn budget has been exhausted (issue #6545).

Distinct from SubAgentError::ConcurrencyLimit (bounds in-flight agents) and SubAgentError::MaxDepthExceeded (bounds recursion depth): this bounds the total number of subagents spawned over the session’s lifetime, independent of both, so a shallow, low-concurrency but high-frequency sequential delegation loop is still caught. The Display string names the config key directly because the only user-visible surface for most callers is format!("Failed to spawn sub-agent: {e}").

Fields

spawned: usize

max: usize

Trait Implementations

impl Debug for SubAgentError

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

Formats the value using the given formatter.

impl Display for SubAgentError

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

Formats the value using the given formatter.

impl Error for SubAgentError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.