From 79352a2d20e5d607ba3f2f8b75cc2e8bb5707797 Mon Sep 17 00:00:00 2001
From: YeonGyu-Kim <code.yeon.gyu@gmail.com>
Date: Tue, 21 Apr 2026 21:23:17 +0900
Subject: [PATCH] =?UTF-8?q?feat:=20#152=20=E2=80=94=20hint=20`--output-for?=
 =?UTF-8?q?mat=20json`=20when=20user=20types=20`--json`=20on=20diagnostic?=
 =?UTF-8?q?=20verbs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Problem

Users commonly type `claw doctor --json`, `claw status --json`, or
`claw system-prompt --json` expecting JSON output. These fail with
`unrecognized argument \`--json\` for subcommand` with no hint that
`--output-format json` is the correct flag.

## Discovery

Filed as #152 during 21:17 dogfood nudge. The #127 worktree contained
a more comprehensive patch but conflicted with #141 (unified --help).
On re-investigation of main, Bugs 1 and 3 from #127 are already closed
(positional arg rejection works, no double "error:" prefix). Only
Bug 2 (the `--json` hint) remained.

## Fix

Two call sites add the hint:

1. `parse_single_word_command_alias`'s diagnostic-verb suffix path:
   when rest[1] == "--json", append "Did you mean \`--output-format json\`?"

2. `parse_system_prompt_options` unknown-option path: same hint when
   the option is exactly `--json`.

## Verification

Before:
  $ claw doctor --json
  error: unrecognized argument `--json` for subcommand `doctor`
  Run `claw --help` for usage.

After:
  $ claw doctor --json
  error: unrecognized argument `--json` for subcommand `doctor`
  Did you mean `--output-format json`?
  Run `claw --help` for usage.

Covers: `doctor --json`, `status --json`, `sandbox --json`,
`system-prompt --json`, and any other diagnostic verb that routes
through `parse_single_word_command_alias`.

Other unrecognized args (`claw doctor garbage`) correctly don't
trigger the hint.

## Tests

- 2 new assertions in `parses_multiple_diagnostic_subcommands`:
  - `claw doctor --json` produces hint
  - `claw doctor garbage` does NOT produce hint
- 177 rusty-claude-cli tests pass
- Workspace tests green

Closes ROADMAP #152.
---
 rust/crates/rusty-claude-cli/src/main.rs | 35 ++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/rust/crates/rusty-claude-cli/src/main.rs b/rust/crates/rusty-claude-cli/src/main.rs
index f70902f..5262a1b 100644
--- a/rust/crates/rusty-claude-cli/src/main.rs
+++ b/rust/crates/rusty-claude-cli/src/main.rs
@@ -1009,10 +1009,16 @@ fn parse_single_word_command_alias(
             return None;
         }
         // Unrecognized suffix like "--json"
-        return Some(Err(format!(
+        let mut msg = format!(
             "unrecognized argument `{}` for subcommand `{}`",
             rest[1], verb
-        )));
+        );
+        // #152: common mistake — users type `--json` expecting JSON output.
+        // Hint at the correct flag so they don't have to re-read --help.
+        if rest[1] == "--json" {
+            msg.push_str("\nDid you mean `--output-format json`?");
+        }
+        return Some(Err(msg));
     }
 
     if rest.len() != 1 {
@@ -1551,7 +1557,14 @@ fn parse_system_prompt_args(
                 date.clone_from(value);
                 index += 2;
             }
-            other => return Err(format!("unknown system-prompt option: {other}")),
+            other => {
+                // #152: hint `--output-format json` when user types `--json`.
+                let mut msg = format!("unknown system-prompt option: {other}");
+                if other == "--json" {
+                    msg.push_str("\nDid you mean `--output-format json`?");
+                }
+                return Err(msg);
+            }
         }
     }
 
@@ -10272,6 +10285,22 @@ mod tests {
                 output_format: CliOutputFormat::Text,
             }
         );
+        // #152: `--json` on diagnostic verbs should hint the correct flag.
+        let err = parse_args(&["doctor".to_string(), "--json".to_string()])
+            .expect_err("`doctor --json` should fail with hint");
+        assert!(
+            err.contains("unrecognized argument `--json` for subcommand `doctor`"),
+            "error should name the verb: {err}"
+        );
+        assert!(
+            err.contains("Did you mean `--output-format json`?"),
+            "error should hint the correct flag: {err}"
+        );
+        // Other unrecognized args should NOT trigger the --json hint.
+        let err_other = parse_args(&["doctor".to_string(), "garbage".to_string()])
+            .expect_err("`doctor garbage` should fail without --json hint");
+        assert!(!err_other.contains("--output-format json"),
+            "unrelated args should not trigger --json hint: {err_other}");
     }
 
     #[test]