Struct Pool 

pub struct Pool<S: PoolStore> { /* private fields */ }

A pool of Claude CLI slots.

Created via Pool::builder. Manages slot lifecycle, task routing, and budget enforcement.

Implementations

impl<S: PoolStore + 'static> Pool<S>

pub async fn auto(&self, prompt: &str) -> Result<AutoResult>

Auto-route a task: let an LLM decide whether to run, fan_out, or chain.

Sends prompt to a single routing call that classifies the work, then executes via the chosen pool method.

Decomposition boundary

For parallel and chain routes, the router decomposes the task into subtasks/steps. This works well when the decomposition is obvious from the prompt (e.g. “review these 5 files” -> one task per file). For ambiguous decompositions, prefer explicit Pool::fan_out or Pool::submit_chain where the caller controls the split.

Fallback

If the routing LLM returns unparseable output, the original prompt is executed as a single task rather than returning an error. Wrong routing is suboptimal, not catastrophic.

pub async fn auto_with_hints( &self, prompt: &str, hints: &AutoHint, ) -> Result<AutoResult>

Auto-route with structured hints.

Hints inform the routing decision without overriding it. See AutoHint for available fields.

pub async fn auto_with_config( &self, prompt: &str, config: Option<&AutoConfig>, ) -> Result<AutoResult>

Auto-route with full configuration.

Use this when you need the escape hatch of a custom prompt or when combining a custom prompt with hints.

pub async fn route(&self, prompt: &str) -> Result<AutoRoute>

Route only: get the routing decision without executing.

Useful for debugging, logging, or prompt iteration — see what the router would choose without spending slots on execution.

pub async fn route_with_hints( &self, prompt: &str, hints: &AutoHint, ) -> Result<AutoRoute>

Route with structured hints (no execution).

pub async fn route_with_config( &self, prompt: &str, config: Option<&AutoConfig>, ) -> Result<AutoRoute>

Route with full configuration (no execution).

pub async fn execute_route(&self, route: AutoRoute) -> Result<AutoResult>

Execute an already-decided route.

Normalizes degenerate routes before execution:

• Parallel with 0-1 prompts becomes Single
• Chain with 0-1 steps becomes Single
• Empty prompts are rejected

impl Pool<InMemoryStore>

pub fn builder(claude: Claude) -> PoolBuilder<InMemoryStore>

Create a builder with the default in-memory store.

impl<S: PoolStore + 'static> Pool<S>

pub fn builder_with_store(claude: Claude, store: S) -> PoolBuilder<S>

Create a builder with a custom store.

pub fn run<'pool>( &'pool self, prompt: impl Into<String>, ) -> RunOptions<'pool, S>

Begin building a synchronous task execution.

Returns a RunOptions builder. Call .await immediately for the simple case, or chain builder methods before awaiting:

// Simple usage — identical to the old pool.run("prompt").await
let result = pool.run("write a haiku about rust").await?;

// With overrides
let result = pool
    .run("refactor this file")
    .config(TaskOverrides { model: Some("claude-opus-4-6".into()), ..Default::default() })
    .working_dir("/tmp/myproject")
    .on_output(|chunk| print!("{chunk}"))
    .await?;

pub async fn run_with_config( &self, prompt: &str, task_config: Option<TaskOverrides>, ) -> Result<TaskResult>

👎Deprecated since 0.1.0:

use pool.run(prompt).config(config).await

Run a task with per-task config overrides.

Deprecated

Use Pool::run with the builder instead: pool.run(prompt).config(config).await

pub async fn run_with_config_and_dir( &self, prompt: &str, task_config: Option<TaskOverrides>, working_dir: Option<PathBuf>, ) -> Result<TaskResult>

👎Deprecated since 0.1.0:

use pool.run(prompt).config(config).working_dir(dir).await

Run a task with per-task config overrides and an optional working directory override.

Deprecated

Use Pool::run with the builder instead: pool.run(prompt).config(config).working_dir(dir).await

pub async fn submit(&self, prompt: &str) -> Result<TaskId>

Submit a task for async execution, returning the task ID immediately.

Use Pool::result to poll for completion.

pub async fn submit_with_config( &self, prompt: &str, task_config: Option<TaskOverrides>, tags: Vec<String>, ) -> Result<TaskId>

Submit a task with config overrides and tags.

pub async fn submit_with_review( &self, prompt: &str, task_config: Option<TaskOverrides>, tags: Vec<String>, max_rejections: Option<u32>, ) -> Result<TaskId>

Submit a task that requires coordinator review before completion.

When the task finishes execution, it transitions to PendingReview instead of Completed. Use Pool::approve_result to accept or Pool::reject_result to reject with feedback and re-queue.

pub async fn approve_result(&self, task_id: &TaskId) -> Result<()>

Approve a task that is pending review, transitioning it to Completed.

pub async fn reject_result( &self, task_id: &TaskId, feedback: &str, ) -> Result<()>

Reject a task that is pending review, re-queuing it with feedback appended.

The original prompt is preserved and the feedback is appended. If the rejection count reaches max_rejections, the task is marked as Failed.

pub async fn result(&self, task_id: &TaskId) -> Result<Option<TaskResult>>

Get the result of a submitted task.

Returns None if the task is still pending/running.

pub async fn cancel(&self, task_id: &TaskId) -> Result<()>

Cancel a pending or running task.

pub async fn claim(&self, slot_id: &SlotId) -> Result<Option<TaskId>>

Claim the next pending task for a specific slot.

Atomically finds the oldest pending task (with no slot assigned), assigns it to the given slot, and executes it in the background. Returns the claimed task ID, or None if no pending tasks are available.

pub async fn cancel_chain(&self, task_id: &TaskId) -> Result<()>

Cancel a running chain, skipping remaining steps.

Sets the chain’s task state to Cancelled. The currently-executing step (if any) runs to completion; remaining steps are then skipped. Partial results are available via Pool::result once the chain finishes.

pub async fn fan_out(&self, prompts: &[&str]) -> Result<Vec<TaskResult>>

Execute tasks in parallel across available slots, collecting all results.

Queues excess prompts until a slot becomes idle. Returns once all prompts complete or timeout waiting for slot availability.

pub async fn submit_chain( &self, steps: Vec<ChainStep>, options: ChainOptions, ) -> Result<TaskId>

Submit a chain for async execution, returning a task ID immediately.

Use Pool::chain_progress to check per-step progress, or Pool::result to get the final crate::ChainResult (serialized as JSON) once complete.

pub async fn fan_out_chains( &self, chains: Vec<Vec<ChainStep>>, options: ChainOptions, ) -> Result<Vec<TaskId>>

Submit multiple chains for parallel execution, returning all task IDs immediately.

Each chain runs on its own slot concurrently. Use Pool::chain_progress to check per-step progress, or Pool::result to get the final result once complete.

pub fn chain_progress(&self, task_id: &TaskId) -> Option<ChainProgress>

Get the progress of an in-flight chain.

Returns None if no chain is tracked for this task ID.

pub fn list_chain_progress(&self) -> Vec<(TaskId, ChainProgress)>

List all tracked chain progress entries.

Returns (chain_id, progress) pairs for every chain the pool is tracking, including completed and failed chains that haven’t been cleaned up yet.

pub fn set_context(&self, key: impl Into<String>, value: impl Into<String>)

Set a shared context value.

Context is injected into slot system prompts at task start.

pub fn get_context(&self, key: &str) -> Option<String>

Get a shared context value.

pub fn delete_context(&self, key: &str) -> Option<String>

Remove a shared context value.

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

List all context keys and values.

pub fn send_message(&self, from: SlotId, to: SlotId, content: String) -> String

Send a message from one slot to another.

Returns the message ID.

pub async fn broadcast_message( &self, from: SlotId, content: String, ) -> Result<Vec<String>>

Broadcast a message from one slot to all other active slots.

Returns the list of message IDs created (one per recipient).

pub async fn find_slots( &self, name: Option<&str>, role: Option<&str>, state: Option<SlotState>, ) -> Result<Vec<SlotRecord>>

Find slots matching optional name, role, and/or state filters.

All filters are optional; omitted filters match everything.

pub fn read_messages(&self, slot_id: &SlotId) -> Vec<Message>

Read and drain all messages for a slot.

Returns messages in order, removing them from the inbox.

pub fn peek_messages(&self, slot_id: &SlotId) -> Vec<Message>

Peek at all messages for a slot without removing them.

Returns messages in order without draining the inbox.

pub fn message_count(&self, slot_id: &SlotId) -> usize

Get the count of messages in a slot’s inbox.

pub async fn drain(&self) -> Result<DrainSummary>

Gracefully shut down the pool.

Marks the pool as shut down so no new tasks are accepted, then waits for in-flight tasks to complete.

pub async fn status(&self) -> Result<PoolStatus>

Get a snapshot of pool status.

pub fn store(&self) -> &S

Get a reference to the store.

pub fn config(&self) -> &PoolConfig

Get a reference to the pool configuration.

pub fn claude(&self) -> &Claude

Get a reference to the underlying Claude client.

pub async fn session_metrics( &self, filter: &MetricsFilter, ) -> Result<SessionMetrics>

Compute aggregated session metrics from all tasks.

Scans all tasks in the store and computes cost, timing, and model breakdowns useful for developer insights. Accepts an optional filter to narrow results by time window, tags, or model.

pub fn start_supervisor(&self) -> Option<SupervisorHandle>

Start the background supervisor loop.

The supervisor periodically checks for errored slots and restarts them (up to PoolConfig::max_restarts). Returns a SupervisorHandle that can be used to stop the loop.

Returns None if PoolConfig::supervisor_enabled is false.

pub async fn scale_up(&self, count: usize) -> Result<usize>

Scale up the pool by adding N new slots.

Returns the new total slot count. Fails if the new count exceeds max_slots.

pub async fn scale_down(&self, count: usize) -> Result<usize>

Scale down the pool by removing N slots.

Removes idle slots first. If not enough idle slots are available, waits for busy slots to complete (with timeout) before removing them. Returns the new total slot count. Fails if the new count drops below min_slots.

pub async fn set_target_slots(&self, target: usize) -> Result<usize>

Set the target number of slots, scaling up or down as needed.

Trait Implementations

impl<S: PoolStore> Clone for Pool<S>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.