feat: distinct exit codes so callers can tell usage errors from runtime failures

[msampathkumar]

Goal: Let a script or CI job tell how an a2a command failed from the exit code alone, without parsing output.
User story: As a CI or script author, I want exit code 2 for a bad invocation and 1 for a real failure, so that my pipeline can distinguish a wrong call from a failed agent call without parsing text.

Priority: P0 · Area: CLI code

Problem

Invalid flags/arguments and genuine runtime failures both exit with status 1. A caller cannot distinguish "I invoked the tool wrong" from "the tool ran and failed," so shell/CI branching on $? is impossible.

$ a2a send --bogus-flag 'x'
Error: unknown flag: --bogus-flag
$ echo $?
1        # want: 2 (usage error)

Proposed behavior

A small, stable exit-code scheme that reports whether the CLI did its job — not what the agent decided:

Code	Meaning
0	Success — the operation was carried out and reported, regardless of the agent's task outcome (a task that ends FAILED/REJECTED or pauses at INPUT_REQUIRED/AUTH_REQUIRED is still exit 0)
1	Failure the CLI owns and no more specific code applies
2	Usage error — invalid arguments, flags, or flag combination

Optional, reserved for later (fall back to 1 if unimplemented): 3 agent/card unreachable or unresolvable · 4 authentication required/rejected · 5 timeout.

Acceptance criteria

• Unknown/invalid flags and bad flag combinations exit 2.
• A faithfully-conducted, reported turn exits 0 irrespective of the task's outcome.
• Other CLI-owned failures exit 1.
• Table-driven test asserting the exit code for: a valid run, a usage error, and an unreachable agent.

Environment

• CLI version: a2a version v0.0.0-…1e29dfe94f95+dirty
• OS: Linux x86_64

Notes

Naturally implemented alongside machine-readable error output (companion request) — both live in the top-level Execute()/error-handling path (internal/cli/root.go). The exit code and any reported error code should agree.