Struct ToolArgs 

#[non_exhaustive]
pub struct ToolArgs {
    pub positional: Vec<Value>,
    pub named: BTreeMap<String, Value>,
    pub flags: HashSet<String>,
}

Parsed arguments ready for tool execution.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

positional: Vec<Value>

Positional arguments in order.

named: BTreeMap<String, Value>

Named arguments by key.

flags: HashSet<String>

Boolean flags (e.g., -l, –force).

Implementations

impl ToolArgs

pub fn new() -> ToolArgs

Create empty args.

pub fn get_positional(&self, index: usize) -> Option<&Value>

Get a positional argument by index.

pub fn get_named(&self, key: &str) -> Option<&Value>

Get a named argument by key.

pub fn get(&self, name: &str, positional_index: usize) -> Option<&Value>

Get a named argument or positional fallback.

Useful for tools that accept both cat file.txt and cat path=file.txt.

pub fn get_string(&self, name: &str, positional_index: usize) -> Option<String>

Get a string value from args.

pub fn get_bool(&self, name: &str, positional_index: usize) -> Option<bool>

Get a boolean value from args.

pub fn has_flag(&self, name: &str) -> bool

Check if a flag is set (in flags set, or named bool).

pub fn flagify_bool_named(&mut self, schema: &ToolSchema)

Move bool entries from named into the appropriate set so a downstream clap parser (with #[arg(...)] field: bool) accepts them.

Tests routinely seed args.named.insert(K, Value::Bool(true)) for the schema-pre-clap path; to_argv() would emit those as --K=true, which clap rejects for bool fields. Promote to:

• Bool(true) → presence in flags (clap sees --K).
• Bool(false) → dropped (clap treats absent flag and explicit false the same; preserving it would only resurface as --K=false and break the same parser).

A Value::Bool parked under a key the schema declares as a value-taking flag is the flag’s literal value, not a bare bool flag — spawn --command true binds command = Bool(true). Those keys are left in named so to_argv() renders --command=true and clap’s Option<String> field accepts it; collapsing them to a bare --command drops the value and makes clap error “a value is required”. (See docs/issues.md.)

Idempotent. Non-bool named entries are left alone.

pub fn to_argv(&self) -> Vec<String>

Reconstruct a clap-friendly argv vector from already-parsed ToolArgs.

kaish has already done shell parsing (variables expanded, globs expanded, $(...) substituted, schema-driven flag/value splitting). to_argv rebuilds a flat token stream suitable for Parser::parse_from(std::iter::once("<tool>").chain(args.to_argv())).

Layout: flags first (as --<name>), then named values (as --<name>=<value>), then positionals — separated from earlier sections by -- so trailing-passthrough builtins still see them as positionals even if a value happens to begin with -.

See the clap builtin pattern in CLAUDE.md (Contributor conventions).

Trait Implementations

impl Clone for ToolArgs

fn clone(&self) -> ToolArgs

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ToolArgs

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

Formats the value using the given formatter.

impl Default for ToolArgs

fn default() -> ToolArgs

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ToolArgs

fn deserialize<__D>( __deserializer: __D, ) -> Result<ToolArgs, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ToolArgs

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.