Struct SubAgentManager 

pub struct SubAgentManager { /* private fields */ }

Manages sub-agent lifecycle: definitions, spawning, cancellation, and result collection.

Implementations

impl SubAgentManager

pub fn new(max_concurrent: usize) -> Self

Create a new manager with the given concurrency limit.

pub fn set_transcript_config(&mut self, dir: Option<PathBuf>, max_files: usize)

Configure transcript storage settings.

pub fn set_stop_hooks(&mut self, hooks: Vec<HookDef>)

Set config-level lifecycle stop hooks (fired when any agent finishes or is cancelled).

pub fn load_definitions( &mut self, dirs: &[PathBuf], ) -> Result<(), SubAgentError>

Load sub-agent definitions from the given directories.

Higher-priority directories should appear first. Name conflicts are resolved by keeping the first occurrence. Non-existent directories are silently skipped.

Errors

Returns SubAgentError if any definition file fails to parse.

pub fn load_definitions_with_sources( &mut self, ordered_paths: &[PathBuf], cli_agents: &[PathBuf], config_user_dir: Option<&PathBuf>, extra_dirs: &[PathBuf], ) -> Result<(), SubAgentError>

Load definitions with full scope context for source tracking and security checks.

Errors

Returns SubAgentError if a CLI-sourced definition file fails to parse.

pub fn definitions(&self) -> &[SubAgentDef]

Return all loaded definitions.

pub fn definitions_mut(&mut self) -> &mut Vec<SubAgentDef>

Return mutable access to definitions, for testing and dynamic registration.

pub fn spawn( &mut self, def_name: &str, task_prompt: &str, provider: AnyProvider, tool_executor: Arc<dyn ErasedToolExecutor>, skills: Option<Vec<String>>, config: &SubAgentConfig, ) -> Result<String, SubAgentError>

Spawn a sub-agent by definition name with real background execution.

Returns the task_id (UUID string) that can be used with cancel and collect.

Errors

Returns SubAgentError::NotFound if no definition with the given name exists, SubAgentError::Spawn if the concurrency limit is exceeded, or SubAgentError::Invalid if the agent requests bypass_permissions but the config does not allow it (allow_bypass_permissions: false).

pub fn shutdown_all(&mut self)

Cancel all active sub-agents. Called during main agent shutdown.

pub fn cancel(&mut self, task_id: &str) -> Result<(), SubAgentError>

Cancel a running sub-agent by task ID.

Errors

Returns SubAgentError::NotFound if the task ID is unknown.

pub fn approve_secret( &mut self, task_id: &str, secret_key: &str, ttl: Duration, ) -> Result<(), SubAgentError>

Approve a secret request for a running sub-agent.

Called after the user approves a vault secret access prompt. The secret key must appear in the sub-agent definition’s allowed secrets list; otherwise the request is auto-denied.

Errors

Returns SubAgentError::NotFound if the task ID is unknown, SubAgentError::Invalid if the key is not in the definition’s allowed list.

pub fn deliver_secret( &mut self, task_id: &str, key: String, ) -> Result<(), SubAgentError>

Deliver a secret value to a waiting sub-agent loop.

Should be called after the user approves the request and the vault value has been resolved. Returns an error if no such agent is found.

Errors

Returns SubAgentError::NotFound if the task ID is unknown.

pub fn deny_secret(&mut self, task_id: &str) -> Result<(), SubAgentError>

Deny a pending secret request — sends None to unblock the waiting sub-agent loop.

Errors

Returns SubAgentError::NotFound if the task ID is unknown, SubAgentError::Other if the channel is full or closed.

pub fn try_recv_secret_request(&mut self) -> Option<(String, SecretRequest)>

Try to receive a pending secret request from a sub-agent (non-blocking).

Returns Some((task_id, SecretRequest)) if a request is waiting.

pub async fn collect(&mut self, task_id: &str) -> Result<String, SubAgentError>

Collect the result from a completed sub-agent, removing it from the active set.

Writes a final TranscriptMeta sidecar with the terminal state and turn count.

Errors

Returns SubAgentError::NotFound if the task ID is unknown, SubAgentError::Spawn if the task panicked.

pub fn resume( &mut self, id_prefix: &str, task_prompt: &str, provider: AnyProvider, tool_executor: Arc<dyn ErasedToolExecutor>, skills: Option<Vec<String>>, config: &SubAgentConfig, ) -> Result<(String, String), SubAgentError>

Resume a previously completed (or failed/cancelled) sub-agent session.

Loads the transcript from the original session into memory and spawns a new agent loop with that history prepended. The new session gets a fresh UUID.

Returns (new_task_id, def_name) on success so the caller can resolve skills by name.

Errors

Returns SubAgentError::StillRunning if the agent is still active, SubAgentError::NotFound if no transcript with the given prefix exists, SubAgentError::AmbiguousId if the prefix matches multiple agents, SubAgentError::Transcript on I/O or parse failure, SubAgentError::Spawn if the concurrency limit is exceeded.

pub fn def_name_for_resume( &self, id_prefix: &str, config: &SubAgentConfig, ) -> Result<String, SubAgentError>

Look up the definition name for a resumable transcript without spawning.

Used by callers that need to resolve skills before calling resume().

Errors

Returns the same errors as TranscriptReader::find_by_prefix and TranscriptReader::load_meta.

pub fn statuses(&self) -> Vec<(String, SubAgentStatus)>

Return a snapshot of all active sub-agent statuses.

pub fn agents_def(&self, task_id: &str) -> Option<&SubAgentDef>

Return the definition for a specific agent by task_id.

pub fn spawn_for_task( &mut self, def_name: &str, task_prompt: &str, provider: AnyProvider, tool_executor: Arc<dyn ErasedToolExecutor>, skills: Option<Vec<String>>, config: &SubAgentConfig, orch_task_id: TaskId, event_tx: Sender<TaskEvent>, ) -> Result<String, SubAgentError>

Spawn a sub-agent for an orchestrated task.

Identical to spawn but wraps the JoinHandle to send a crate::orchestration::TaskEvent on the provided channel when the agent loop terminates. This allows the DagScheduler to receive completion notifications without polling (ADR-027).

The event_tx channel is best-effort: if the scheduler is dropped before all agents complete, the send will fail silently with a warning log.

Errors

Same error conditions as spawn.

Panics

Panics if the internal agent entry is missing after a successful spawn call. This is a programming error and should never occur in normal operation.

Trait Implementations

impl Debug for SubAgentManager

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

Formats the value using the given formatter.