[Hazenix]

Summary

- unknown CLI or missing model -> generic agent format error
+ unknown CLI -> name the CLI and point to the CLI reference
+ missing model -> explain the missing model and show the format

The parser now distinguishes these two invalid -a inputs. Reference and troubleshooting docs match the messages, and tests cover the public CLI parser, a built-in alias, and a configured ACP CLI. This addresses MFCP task #113.

Evidence

• Before (reported in the linked MFCP task): both inputs exited 2 with expected [NAME=]CLI[@PROVIDER]/MODEL[:EFFORT].
• After: hmz exec -f chat -a assistant=codxe/gpt-6.1-sol check exits 2 with unknown CLI 'codxe'; see the CLI reference for supported names.
• After: hmz exec -f chat -a assistant=codex/ check exits 2 with missing model; expected [NAME=]CLI[@PROVIDER]/MODEL[:EFFORT].
• uv run pytest tests/integration/test_agents_acp.py tests/unit/coganchor/test_backends.py tests/unit/runtime/test_runner.py: 319 passed.
• uv run ruff check . and git diff --check main...HEAD: passed.
• uv run pre-commit run --all-files: all hooks passed except pyright, which reports Import "litellm" could not be resolved because that optional extra is absent locally. The ruff-format hook reformatted one test; the formatted result is committed.
• uv run pytest: 6798 passed, 45 skipped, 14 failed, 1 collection error on macOS/Python 3.14.8. The failures include missing optional deepseek_harness and unavailable Docker/remote Python; collection fails on missing litellm. The full local suite is not green.

Merge Danger

Door: two-way

Blast Radius: invalid hmz exec -a diagnostics

Valid agent specifications keep their existing parsing behavior; the change affects only the usage messages for unknown CLIs and missing models.

Checklist

• The title is a Conventional Commit.
• New and changed tests are in the appropriate unit and integration tiers.
• Docs reflect the code; no specs/ files changed.

[Hazenix]

@zevorn This is the upstream PR for MFCP task #113. Could you please review the diagnostic classification, alias/ACP compatibility, and advise on the MFCP mentor DCO/sign-off process?