Module machine 

Machine mode (--machine) — agent-contract output selector.

See docs/agents/spec.md §10. This module ships the runtime layer of --machine: pre-parse detection, clap-error interception, and the canonical ExitCode mapping for pre-command exits.

Runtime guarantees, regardless of which command is invoked:

• color is disabled (wired through crate::opts::GlobalArgs::shell),
• parse / usage failures are wrapped in an error envelope (cli.usage.invalid, exit 2),
• --help / --version are wrapped in a success envelope (exit 0).

Per-command behavior — emitting only the declared output_mode, suppressing progress bars and interactive prompts, returning the canonical ExitCode for the failure category — is opt-in and adopted incrementally.

The flag is detected before clap parsing — see check_machine — so the mode is known by the time clap errors need to be intercepted.

Statics

MACHINE_MODE 🔒

Functions

bail_machine_usage

Emit a cli.usage.invalid envelope on stdout and exit with ExitCode::Usage (2). Use at call sites that intentionally reject a flag combination under --machine.

bail_machine_usage_with_details

Like bail_machine_usage but attaches structured details so agents can react without parsing the prose message.

check_machine

Pre-parse scan for --machine.

exit_code_for_clap_error 🔒

Maps a clap error kind to the canonical ExitCode.

handle_machine_clap_error 🔒

Convert a clap error into a structured machine-mode envelope and exit.

is_machine

Returns whether --machine was set on the current invocation.

parse_or_exit

Parse arguments, intercepting clap errors when machine mode is on.

report_machine_error

Fallback envelope emitter for an untyped eyre::Report. Always tags cli.unknown and preserves the eyre cause chain in details.cause_chain. The process exit code is the caller’s responsibility.

set_machine 🔒

Force machine mode on or off. Intentionally crate-private: production activation goes through check_machine (pre-parse) or crate::opts::GlobalArgs::init (post-parse re-sync).