[Birfy]

Closes #886

An unknown top-level verb no longer lists the internal detached-worker run command among argparse's choose from choices (#420 hid it from --help and the {…} usage metavar, but a typo still walked sub.choices). A hyphen/case fold or close typo (algoritms, compile_skill, COMPILE-SKILL) now gets did you mean …?. agentdescent run itself still parses for evolve --detach.

--json carries the same error text. Other choices= flags reuse the helper; their invalid choice: '…' prefix is unchanged.

Verification

• pytest -q tests/test_cli_help_hides_internal_run.py tests/test_cli_json_usage_errors.py tests/test_install_host_aliases.py tests/test_changelog_fragments.py::test_real_fragments_are_valid tests/test_cli_algorithms_bare.py passed
• live agentdescent algoritms / compile_skill / --json algoritms hide 'run' and suggest the public verb

[Birfy]

Verdict: PASS
Tip SHA: d50b5f2
Ran: pytest -q tests/test_cli_help_hides_internal_run.py tests/test_cli_json_usage_errors.py tests/test_install_host_aliases.py tests/test_changelog_fragments.py::test_real_fragments_are_valid tests/test_cli_algorithms_bare.py at the tip → passed; live agentdescent algoritms / compile_skill / --json algoritms hide 'run' and print did you mean …?; agentdescent run --help still describes the internal worker.
risk_gate: T2 (101 lines / 3 files). No CHANGES REQUESTED. AGENT_PAUSE=false.

[Birfy]

Verdict: PASS
Tip SHA: d50b5f2
Ran: pytest -q tests/test_cli_help_hides_internal_run.py tests/test_cli_json_usage_errors.py tests/test_install_host_aliases.py tests/test_changelog_fragments.py::test_real_fragments_are_valid tests/test_cli_algorithms_bare.py tests/test_init_honor_agent.py at the tip → passed; live algoritms / stauts / compile_skill / COMPILE-SKILL hide 'run' and suggest the public verb; --json algoritms carries the same error text; no-such-verb has no guess; ruun/rn do not suggest the internal worker; run --help still says it is internal and parse_args(["run", "--run-dir", ...]) still binds cmd_run. risk_gate.py from main → T2 (101 changed lines / 3 files).
Not run: full suite (CI covers 3.9–3.13).

Correctness. #420 already kept run out of --help and the {…} metavar; an unknown verb still walked sub.choices and advertised it. Overriding _CliParser._check_value is the right layer — argparse builds the choose from list there, and subparsers inherit this class — so the public-only list and did you mean …? apply to the top-level verb and to other choices= flags without changing their invalid choice: '…' prefix. value in action.choices still accepts run, so evolve --detach / runstore's worker command line is unchanged. Suggestions run only over visible names (exact fold of case and -/_, else difflib at cutoff 0.75, same bar as #874 / #882 / #884), and two names that fold together are treated as ambiguous rather than guessed.

Design. Reusing _INTERNAL_COMMANDS for help, usage, and now the unknown-verb list keeps the three surfaces aligned. Filtering run out of every choices= action is harmless today (no other flag lists that token). Suggestion-only, no auto-accept of a hyphen/case alias as the verb, matches the issue's non-goals.

Tests / docs. New cases cover the #886 acceptance list (hide run, hyphen/case fold, --json, nonsense verb with no guess) on top of the existing #420 help/usage/run --help/parse tests. Changelog fragment 886-unknown-verb-hint.md is valid.

Risk. T2 by size/path (package CLI argparse error text only; 101 lines / 3 files, under the 250-line cap). No evolve-loop change. AGENT_PAUSE=false; will squash-merge when required CI is green.