Struct ToolArgs 

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

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).

words: Option<Vec<Value>>

Every word after the tool name, in source order, post-expansion — Some only for an ArgBinding::Verbatim tool, None for every other tool.

A text word arrives as Value::String; a heredoc- or pipe-bound word keeps its Value::Bytes. positional and named are empty when this is Some; flags holds only the global flags the binder lifted out (today just json), so has_flag("json") still answers.

Render it to a clap argv with ToolArgs::words_argv.

Implementations

impl ToolArgs

pub fn new() -> ToolArgs

Create empty args.

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

Render words into argv tokens for a verbatim tool’s own parser. Empty when the tool is not verbatim.

A Value::Bytes word renders as an inert placeholder token, as to_argv does for a binary positional; the real bytes stay at the matching index in words.

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”.

Idempotent. Non-bool named entries are left alone.

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

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 -.

Errors

Returns ToolArgvError when a named/flag value is Value::Bytes — binary can’t cross the argv/text stringification boundary (GH #164, closing the root cause behind GH #120’s stringified [binary: N bytes] placeholder). A positional Value::Bytes does NOT error here; see value_to_argv_token’s doc comment for why.

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

Equivalent to to_argv_excluding(&[]) — same rendering path, nothing excluded.

pub fn to_argv_excluding( &self, exclude: &[&str], ) -> Result<Vec<String>, ToolArgvError>

Like to_argv, but skips the given named keys entirely — neither the key’s flag token nor its value appears in the rendered argv, and (crucially) a Value::Bytes under an excluded key is never passed to render_named_value, so it can never trip ToolArgvError::BinaryNamedValue.

Use this when a builtin deliberately reads one of its own named parameters raw off ToolArgs (e.g. args.named.get("content")) instead of the clap-parsed field, specifically to preserve a typed/binary value that must not cross the argv/text stringification boundary — while still wanting the rest of its arguments bound through the normal clap path. write’s content param is the motivating case (GH #218, a follow-up from the GH #164 / #215 review): before this helper, the builtin cloned the whole ToolArgs and called named.remove("content") by hand, which silently stops covering a second Bytes-capable named param the moment one is added. Naming the excluded keys here instead makes the exemption a greppable, drift-resistant idiom.

Only named keys are excludable — not flags or positionals, by design. A bool flag carries no value to protect, so there is nothing to exempt. A positional’s clap-reflected field is already a validation-only sink nobody reads (see CLAUDE.md’s clap-builtin convention), so a positional Value::Bytes never needed an exemption in the first place — value_to_argv_token renders it as an inert placeholder rather than erroring. If a future case needs to exclude a flag or positional too, that is new design, not an extension of this helper.

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.