Struct SubagentHandle 

pub struct SubagentHandle { /* private fields */ }

A live handle to a spawned ACP sub-agent session.

SubagentHandle serialises all ACP operations through a command channel that is serviced by a background driver task. Concurrent reads are rejected with AcpClientError::DriverBusy; callers must wait for the in-flight operation to complete before issuing another read.

Dropping the handle without calling close aborts the driver task, which in turn kills the subprocess via kill_on_drop.

Implementations

impl SubagentHandle

pub fn session_id(&self) -> &SessionId

The ACP SessionId assigned by the sub-agent.

pub async fn send_prompt( &mut self, text: impl Into<String>, ) -> Result<(), AcpClientError>

Send a text prompt to the sub-agent.

Returns immediately after enqueuing the prompt — the sub-agent will process it asynchronously. Call read_update or read_to_string to receive the response.

Errors

Returns AcpClientError::Closed when the session has been closed, AcpClientError::DriverDied when the background driver has exited unexpectedly, or AcpClientError::Sdk for protocol errors.

Examples

use zeph_acp::client::{SubagentConfig, spawn_subagent};

let cfg = SubagentConfig { command: "zeph --acp".to_owned(), ..SubagentConfig::default() };
let mut handle = spawn_subagent(cfg).await?;
handle.send_prompt("What is 2 + 2?").await?;

pub async fn read_update(&mut self) -> Result<SessionMessage, AcpClientError>

Read one SessionMessage update from the sub-agent.

Blocks until an update arrives or the session closes. A concurrent call returns AcpClientError::DriverBusy immediately.

Errors

Returns AcpClientError::Closed or AcpClientError::DriverDied when the session ends, or AcpClientError::DriverBusy when a concurrent read is already in progress.

Examples

use zeph_acp::client::{SubagentConfig, spawn_subagent};

let cfg = SubagentConfig { command: "zeph --acp".to_owned(), ..SubagentConfig::default() };
let mut handle = spawn_subagent(cfg).await?;
handle.send_prompt("hello").await?;
let update = handle.read_update().await?;

pub async fn read_to_string(&mut self) -> Result<RunOutcome, AcpClientError>

Drain all updates until StopReason, collecting text into a RunOutcome.

Equivalent to calling read_update in a loop, filtering for text chunks and terminating on StopReason. Ignores thought chunks, tool calls, and plans.

A send_cancel issued concurrently will interrupt the drain and the in-flight read will resolve with StopReason::Cancelled.

Errors

Returns AcpClientError::Closed or AcpClientError::DriverDied when the session ends, or AcpClientError::DriverBusy when another read is in progress.

pub async fn send_cancel(&mut self) -> Result<(), AcpClientError>

Send a session/cancel notification to the sub-agent.

This does not close the session; the sub-agent should acknowledge the cancel by sending a StopReason::Cancelled update on the active read.

The one-poll-cycle preemption guarantee (a cancel delivered while read_update or read_to_string is blocked will interrupt the read within one tokio::select! cycle) only applies when one of those read operations is currently in progress. Calling send_cancel outside of an active read sends the ACP notification but does not interrupt any future read.

Errors

Returns AcpClientError::Closed when the session is already closed or AcpClientError::DriverDied if the driver has exited.

pub async fn close(&mut self) -> Result<(), AcpClientError>

Close the session and wait for the driver to shut down.

Idempotent: a second call returns AcpClientError::Closed immediately.

Errors

Returns AcpClientError::DriverDied if the driver exited before the close acknowledgement was received.

Examples

use zeph_acp::client::{SubagentConfig, spawn_subagent};

let cfg = SubagentConfig { command: "zeph --acp".to_owned(), ..SubagentConfig::default() };
let mut handle = spawn_subagent(cfg).await?;
handle.close().await?;

Trait Implementations

impl Drop for SubagentHandle

fn drop(&mut self)

Executes the destructor for this type.