Module tools

Expand description

Tool system for kaish.

Tools are the primary way to perform actions in kaish. Every command is a tool — builtins and user-defined tools all implement the same Tool trait.

§Architecture

ToolRegistry
├── Builtins (echo, ls, cat, ...)
└── User Tools (defined via `tool` statements)

ExecContext: Execution context passed to tools.
GlobalFlags: Flags injected into every migrated builtin via #[command(flatten)] global: GlobalFlags.
ParamSchema: Schema for a tool parameter.
ToolArgs: Parsed arguments ready for tool execution.
ToolRegistry: Registry of available tools.
ToolSchema: Schema describing a tool’s interface.

ArgBinding: How the kernel’s argv binder hands a tool its arguments.
ExternalCommandsUnavailable: Why kaish will not run an external command for this dispatch — distinct from “not found in PATH”, which is a different condition entirely (see crate::tools::builtin::spawn::virtual_cwd_error for that one).
OutputContext: Output context determines how command output should be formatted.
OverwriteExpectation: What a snapshotted overwrite must still find at the target before it writes — the compare-and-swap expectation overwrite_checked enforces.

WORD_ASSIGN_BUILTINS: Commands that consume bareword key=value argv (Arg::WordAssign) as shell-assignment pairs and route them through tool_args.named. For every other command, key=value lands as a positional "key=value" string — matching bash (cat foo=bar opens a file named foo=bar).

accepts_word_assign
external_commands_unavailable_error: Refuse to run name as an external command, exit 127 — the same code POSIX gives “command not found”, since from here it’s indistinguishable to a caller checking only the exit code. The message is what carries the distinction; see ExternalCommandsUnavailable::condition.
global_flag_value_is_truthy: Is a kernel-owned global flag written as --flag=VALUE on?
is_global_output_flag: Check if a flag name is the kernel-owned --json flag.
params_from_clap: Reflect each Arg in a clap Command into a ParamSchema.
register_builtins: Register all built-in tools with the registry.
schema_from_clap: Build a ToolSchema for a builtin from its clap Command reflection plus hand-written description and examples.
schema_tree_from_clap: Build a recursive ToolSchema from a composed clap Command tree.
validate_against_schema: Validate arguments against a tool schema.

GateExpectations: What each snapshotted target must still look like when the caller writes it, keyed by resolved path (see overwrite_checked).