Module tool_invocation 

ToolInvocation extraction from a PeeledCommand (R295-F1).

Extracts a structured ToolInvocation once the peeled command’s basename is matched against a registered ToolLookup. The schema (global-flag specs, max subcommand depth) lives in ToolSchemaInfo, which the full policy types in agent_tools::tool_schema embed.

Dependency direction is intentionally one-way:

• bash-ast (this crate) defines extraction + the lookup trait.
• agent-tools defines policy (ApprovalTier, ToolSchema) and implements ToolLookup on its ToolRegistry. No circular deps arise.

@arch:see(.yah/docs/working/W086-git-subcommand-gate.md)

@yah:ticket(R295-F7, “bash-ast: arg provenance + path scope + pipe-edge facts”) @yah:assignee(agent:miravel) @yah:at(2026-05-25T23:42:54Z) @yah:status(review) @yah:parent(R295) @yah:next(“Add pure fns over the existing tree: arg_provenance(&CommandArgument) -> Provenance (Literal from Word; Variable from SimpleExpansion/Expansion; CommandSub from CommandSubstitution; ProcessSub from ProcessSubstitution; Glob when a Word contains unquoted */?/[) and path_scope(literal, camp_root) -> PathScope (WithinCamp/OutsideCamp/System/Unresolvable via canonicalization against camp root). See addendum table in the design doc.”) @yah:next(“Add a pipe-edge stamping helper: when walking a Pipeline, expose each stage’s upstream/downstream tool basename so the floor walker can populate CommandFact.pipe_into/pipe_from.”) @yah:verify(“cargo test -p bash-ast # provenance per node-kind + path_scope buckets (within/outside/system/unresolvable) + glob detection”) @arch:see(.yah/docs/working/W086-git-subcommand-gate.md) @yah:handoff(“Shipped. bash-ast/src/tool_invocation.rs grew three public families:\n(1) Provenance enum (Literal/Glob/Variable/ProcessSub/CommandSub) with Ord-derived severity order; arg_provenance(&CommandArgument)->Provenance pure fn; arg_fact(&CommandArgument, &Path)->ArgFact combines provenance + path_scope.\n(2) PathScope enum (WithinCamp/Unresolvable/OutsideCamp/System); path_scope(literal, camp_root) pure fn — no disk I/O, static ..-escape analysis via escapes_camp().\n(3) pipeline_stage_basenames(&Pipeline)->Vec<Option> pipe-edge helper — peels each stage via peel_simple_command_loose, returns lowercased tool basenames for all stages (None for subshells/control-flow stages).\nPrivate helpers: primary_provenance, string_parts_provenance (fold over StringPart variants), arg_raw_text/primary_raw_text/string_parts_text (display), is_system_path (SYSTEM_DIR_PREFIXES const), looks_like_path, escapes_camp, stmt_basename.\n38 new tests: 14 provenance, 16 path_scope, 5 pipeline_stage_basenames + 2 existing extraction tests untouched. cargo test -p bash-ast: 69/69 green, no warnings.”) @yah:verify(“cargo test -p bash-ast tool_invocation # 49/49 green”)

Structs

ArgFact

Per-argument provenance and path scope derived from the raw AST node.

ToolInvocation

Structured representation of a single tool invocation extracted from a PeeledCommand. All string fields borrow from the source PeeledCommand to avoid heap allocation in the hot approval-gate path.

ToolSchemaInfo

Minimal schema info needed for tool_invocation_of.

Enums

GlobalFlagSpec

Describes how a single global flag (one that appears between the tool name and the subcommand chain) should be consumed during extraction.

PathScope

How far a literal-provenance argument reaches relative to camp_root.

Provenance

How statically bounded a command argument’s value is.

Traits

ToolLookup

Abstraction over a tool-schema registry. tool_invocation_of calls this to resolve the basename of the peeled primary to a schema.

Functions

arg_fact

Build an ArgFact for a single command argument.

arg_provenance

Classify the provenance of a CommandArgument from the parse tree.

arg_raw_text

path_scope

Classify a literal argument string by how far it can reach relative to camp_root. Pure — no disk I/O; uses static path analysis only.

pipeline_stage_basenames

For each stage of pipeline, resolve the lowercased tool basename after peeling wrappers. None for stages that are not simple commands or that cannot be peeled (subshells, control flow, …).

tool_invocation_of

Extract a ToolInvocation from peeled, looking the primary up in registry. Returns None when the primary’s basename is not registered.