Struct SubagentController 

pub struct SubagentController { /* private fields */ }

Central controller that manages spawning, lifecycle, and state of all subagents. The background completion monitor is cancelled when the final controller owner is dropped; its task-held clone is intentionally non-owning.

Implementations

impl SubagentController

pub async fn matrix_tracker_projection(&self) -> Option<Value>

impl SubagentController

pub fn take_matrix_completion(&self) -> Option<MatrixSnapshot>

Coalesced notification projection; lifecycle authority stays in events.

pub fn has_matrix_completion(&self) -> bool

Idle wakeups inspect readiness without consuming the outer loop’s result.

pub async fn set_matrix_persistence( &self, persistence: MatrixPersistence, ) -> Result<()>

pub fn matrix_is_executing(&self) -> bool

pub async fn cancel_matrix(&self) -> Result<()>

pub async fn matrix_control(&self, args: Value) -> Result<Value>

impl SubagentController

pub async fn background_status_entries(&self) -> Vec<BackgroundSubprocessEntry>

Returns status entries for all tracked background subprocesses.

pub async fn background_snapshot( &self, target: &str, ) -> Result<BackgroundSubprocessSnapshot>

Returns a snapshot of a background subprocess including its preview output.

pub fn background_subagents_enabled(&self) -> bool

Returns whether background subagents are enabled in the configuration.

pub fn configured_default_background_agent(&self) -> Option<&str>

Returns the configured default background agent name, if any.

pub async fn toggle_default_background_subagent( &self, ) -> Result<BackgroundSubprocessEntry>

Toggles the default background subagent between running and stopped.

pub async fn restore_background_subagents( &self, ) -> Result<Vec<BackgroundSubprocessEntry>>

Restarts background subagents that were previously enabled but are no longer running.

pub async fn refresh_background_processes( &self, ) -> Result<Vec<BackgroundSubprocessEntry>>

Refreshes the state of all background subprocesses and respawns as needed.

pub async fn wait_for_background( &self, targets: &[String], timeout_ms: Option<u64>, ) -> Result<Option<BackgroundSubprocessEntry>>

Blocks until one of the target background subprocesses reaches a terminal state (Stopped/Error) or the timeout expires.

This is the background counterpart to the delegated SubagentController::wait: managed subprocesses previously had no model-visible wait path, so the main orchestrator could only observe completion via manual /subprocesses polling or the Local Agents drawer. Unknown ids resolve to Ok(None) (fail-closed) rather than an error so the unified agent action=wait dispatcher can race this alongside the delegated wait without hallucinating completion.

pub async fn graceful_stop_background( &self, target: &str, ) -> Result<BackgroundSubprocessEntry>

Gracefully stops a background subprocess by setting its desired state to disabled.

pub async fn force_cancel_background( &self, target: &str, ) -> Result<BackgroundSubprocessEntry>

Force-cancels a background subprocess, closing its exec session immediately.

pub async fn snapshot_for_thread( &self, target: &str, ) -> Result<SubagentThreadSnapshot>

Returns a thread snapshot for a tracked child subagent by its target id.

impl SubagentController

pub async fn spawn( &self, request: SpawnAgentRequest, ) -> Result<SubagentStatusEntry>

Spawns a new subagent child process from a SpawnAgentRequest.

pub async fn spawn_background_subprocess( &self, request: SpawnBackgroundSubprocessRequest, ) -> Result<BackgroundSubprocessEntry>

Spawns a background subprocess for a subagent marked background: true.

pub async fn spawn_custom( &self, spec: SubagentSpec, request: SpawnAgentRequest, ) -> Result<SubagentStatusEntry>

Spawns a subagent with a custom SubagentSpec that must be read-only.

pub async fn send_input( &self, request: SendInputRequest, ) -> Result<SubagentStatusEntry>

Sends additional input to a running or queued subagent.

pub async fn resume(&self, target: &str) -> Result<SubagentStatusEntry>

Resumes a closed or errored subagent and its descendants by re-queuing their prompts. Cascades recursively through child-scoped controllers so grandchildren closed by close_tree are resumed too, not merely un-gated.

pub async fn close(&self, target: &str) -> Result<SubagentStatusEntry>

Closes a subagent and all its descendants, aborting any in-flight work.

pub async fn wait( &self, targets: &[String], timeout_ms: Option<u64>, ) -> Result<Option<SubagentStatusEntry>>

Blocks until one of the target subagents reaches a terminal state or the timeout expires.

pub async fn status_for(&self, target: &str) -> Result<SubagentStatusEntry>

Returns the current status of a tracked subagent by its target id.

pub async fn signal_shutdown(&self)

Signal that the program is shutting down. Subsequent calls to save_background_state will be skipped. All running child handles are aborted so subagent tasks do not outlive the parent session.

impl SubagentController

pub async fn verify_proposed_change( &self, diff_description: &str, file_paths: &[PathBuf], ) -> Result<VerificationResult>

Verify a proposed change by spawning a read-only verifier sub-agent.

The verifier re-reads the affected files and either approves or rejects the change. On rejection, the caller can retry the mutation up to N times.

This implements the propose/verify separation from Osmani’s loop engineering pattern: the proposer and verifier are independent agents with no shared context bias.

impl SubagentController

pub async fn new(config: SubagentControllerConfig) -> Result<Self>

Creates a new controller, discovering subagent specs and loading persisted background state.

pub async fn new_with_discovered( config: SubagentControllerConfig, discovered: DiscoveredSubagents, ) -> Result<Self>

Creates a new controller reusing an already-discovered spec set.

Interactive startup discovers specs once on the first-paint path; hydration passes that result here to skip a second workspace/plugin filesystem scan. Behavior matches Self::new otherwise.

pub fn subscribe_background_completions( &self, ) -> Receiver<BackgroundCompletionEvent>

Subscribes to terminal notifications for managed background subprocesses.

pub fn subscribe_parent_background_completions( &self, ) -> Receiver<BackgroundCompletionEvent>

Subscribes the parent run loop and replays completions that arrived before its receiver was installed.

pub fn background_completion_notify(&self) -> Arc<Notify>

Returns the wake signal used by the interactive loop while it is idle.

pub async fn reload(&self) -> Result<()>

Re-discovers subagent specs from the workspace.

pub async fn set_parent_messages(&self, messages: &[Message])

Stores the parent conversation messages for context forking into children.

pub async fn set_turn_delegation_hints_from_input( &self, input: &str, ) -> Vec<String>

Parses the current user input to extract explicit agent mentions and delegation signals.

pub async fn clear_turn_delegation_hints(&self)

Resets delegation hints at the end of a turn.

pub async fn set_parent_session_id(&self, session_id: impl Into<String>)

Updates the parent session identifier at runtime.

pub async fn effective_specs(&self) -> Vec<SubagentSpec>

Returns the currently effective subagent specifications (merged builtin + workspace).

pub async fn shadowed_specs(&self) -> Vec<SubagentSpec>

Returns specs that are shadowed by workspace-level overrides.

pub async fn status_entries(&self) -> Vec<SubagentStatusEntry>

Returns status entries for all tracked child subagents.

Trait Implementations

impl Clone for SubagentController

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Drop for SubagentController

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

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

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.