Add machine-readable error codes to JSON commands

[NathanaelRea]

Motivation

Callers using --format=json can parse successful results, but failures such as approval-required, hook failure, and Git failure still require compatibility matching against human-readable stderr.

Request

For JSON-mode commands, return a stable structured error envelope or another documented machine-readable error channel with codes for at least:

• approval required;
• hook failure;
• Git failure;
• invalid input or unsupported operation.

Human diagnostics can remain on stderr, but callers should not need regexes to classify failures.

[worktrunk-bot]

Thanks for the suggestion — this is a real gap. There's no machine-readable error channel today: --format=json shapes only the success payload, and every failure path renders the same way regardless of format.

Concretely, on failure a command routes through print_command_error → format_command_error, which emits human-readable, styled text to stderr with no JSON variant. The exit code then comes from error.exit_code().unwrap_or(1) — so it isn't a category channel either. Walking WorktrunkError::exit_code and its enum, of your four categories only hook failure carries a distinct code (it passes through the hook's own exit code); approval-required (CommandNotApproved) and most git/invalid-input failures are plain anyhow errors with no typed code, so they all collapse to 1. So regex-against-stderr is indeed the only classifier right now.

Where a change would slot in, and one existing precedent worth pointing at: wt step for-each --format=json already emits a per-item structured failure — {branch, path, exit_code, success: false, error} — from for_each.rs. That's the shape you're describing, just scoped to one command's per-worktree results rather than offered as a top-level command-failure envelope. Generalizing it would mean (a) giving the failure categories a stable discriminant — the ~40-variant GitError enum plus the WorktrunkError variants are a good foundation (an error_code() mapping alongside the existing exit_code() walk), with a fallback code for the untyped anyhow/bail! context that can't be classified today; and (b) deciding the transport. One concrete plumbing cost either way: --format is declared per-subcommand and consumed inside each handler, so it isn't currently visible at the top-level error handler (handle_command_failure) — a JSON error envelope would need the effective format threaded up there, or emitted inside each handler.

Two tradeoffs a maintainer would weigh on (b):

• A JSON error envelope on stdout (mirroring for_each) is richest, but it changes the "JSON is the only stdout payload, diagnostics stay on stderr" invariant that the related #3501 thread leaned on — errors would now also print structured JSON to stdout.
• A documented stable exit-code scheme (one code per category) keeps stdout pure and is a smaller surface, but it's coarser than an envelope with a code + message.

This is closely tied to #3501 (stable automation contract), where "structured error category" was flagged as the open item before that issue was closed by a different requester who opted to pin versions and build against the existing CLI. Per the project's CLAUDE.md, output formatting is explicitly on the flexible, uncommitted side of the interface line — so both the envelope and the stability commitment behind it are a maintainer policy call rather than a mechanical fix. I'll leave it for a maintainer to evaluate and prioritize.