Struct Conversation 

pub struct Conversation<R: CommandRunner = DefaultRunner> { /* private fields */ }

Stateful multi-turn conversation wrapper around ClaudeClient.

Manages session_id automatically across turns using --resume. The base config is cloned per turn; each turn builds a temporary config with --resume <session_id> injected.

Design decisions

Ownership model: Owns cloned copies of ClaudeConfig and the runner instead of borrowing &ClaudeClient. ClaudeClient is stateless (config + runner only, no connection pool), so cloning is cheap and avoids lifetime parameters that complicate async usage (spawn, struct storage).

session_id storage: Uses Arc<Mutex<Option<String>>> so that the streaming path can update the session ID while the caller consumes the returned Stream (which outlives the &mut self borrow).

Note

Callers must set ClaudeConfigBuilder::no_session_persistence(false) in the config for multi-turn to work. The library does not override this; option validation is the CLI’s responsibility.

Implementations

impl<R: CommandRunner> Conversation<R>

pub fn session_id(&self) -> Option<String>

Returns the current session ID, or None if no turn has completed.

impl<R: CommandRunner + Clone> Conversation<R>

pub async fn ask(&mut self, prompt: &str) -> Result<ClaudeResponse, ClaudeError>

Sends a prompt and returns the response.

Shorthand for ask_with(prompt, |b| b).

pub async fn ask_with<F>( &mut self, prompt: &str, config_fn: F, ) -> Result<ClaudeResponse, ClaudeError>

where F: FnOnce(ClaudeConfigBuilder) -> ClaudeConfigBuilder,

Sends a prompt with per-turn config overrides and returns the response.

The closure receives a ClaudeConfigBuilder pre-filled with the base config. Overrides apply to this turn only; the base config is unchanged.

impl Conversation

pub async fn ask_stream( &mut self, prompt: &str, ) -> Result<Pin<Box<dyn Stream<Item = Result<StreamEvent, ClaudeError>> + Send>>, ClaudeError>

Available on crate feature stream only.

Sends a prompt and returns a stream of events.

Shorthand for ask_stream_with(prompt, |b| b).

Only available for Conversation<DefaultRunner> (i.e., conversations created via ClaudeClient::new). The CommandRunner trait’s run method returns a completed std::process::Output, which cannot support streaming; therefore streaming always spawns a real CLI subprocess.

Note: Timeout from the base config is not applied to streams. Use tokio_stream::StreamExt::timeout() if needed.

pub async fn ask_stream_with<F>( &mut self, prompt: &str, config_fn: F, ) -> Result<Pin<Box<dyn Stream<Item = Result<StreamEvent, ClaudeError>> + Send>>, ClaudeError>

where F: FnOnce(ClaudeConfigBuilder) -> ClaudeConfigBuilder,

Available on crate feature stream only.

Sends a prompt with per-turn config overrides and returns a stream.

The closure receives a ClaudeConfigBuilder pre-filled with the base config. Overrides apply to this turn only; the base config is unchanged.

All events are passed through transparently. Internally, session_id is captured from StreamEvent::SystemInit and updated from StreamEvent::Result.

Only available for Conversation<DefaultRunner>. See ask_stream for details on the streaming constraint.

Trait Implementations

impl<R: Debug + CommandRunner> Debug for Conversation<R>

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

Formats the value using the given formatter.