docs(roadmap): add #420 — plugins help json returns mutation shape; sibling subgroups use help envelope

ROADMAP.md

@@ -6301,4 +6301,4 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed)
 380. **Top-level `tokens --help --output-format json` hangs with zero stdout/stderr instead of returning bounded command help JSON** — dogfooded 2026-04-30 for the 02:30 nudge on current `origin/main` / rebuilt `./rust/target/debug/claw` with embedded `git_sha` `d95b230c`. After verifying #358 covered `cost --help`, a fresh adjacent probe on the token-budget surface showed the same silent failure class: repeated bounded runs of `timeout 8 ./rust/target/debug/claw tokens --help --output-format json` exited `124` with `stdout=0` and `stderr=0`. In the same rebuilt binary, `version --output-format json` returned promptly with version/build metadata, proving the binary itself and JSON output path are reachable. This is distinct from #358's cost help hang: the affected surface is the sibling `tokens` command help, which agents use before estimating prompt/session token budgets. **Required fix shape:** (a) make `tokens --help --output-format json` return static/bounded stdout JSON with `kind:"help"` or `kind:"tokens"`, `action:"help"`, usage, options, examples, supported output formats, and related slash/direct commands; (b) ensure help rendering does not initialize slow token accounting, session, or provider state; (c) if any dynamic provider is consulted, return a typed JSON timeout/unavailable error instead of hanging; (d) add regression coverage proving tokens help in JSON mode returns within a deterministic budget. **Why this matters:** token budgeting is a preflight clawability surface. If help hangs silently, automation cannot safely discover how to inspect or constrain token usage before running expensive prompts, and budget-aware wrappers stall at the discovery step. Source: gaebal-gajae dogfood follow-up for the 02:30 nudge on rebuilt `./rust/target/debug/claw` `d95b230c`.
 381. **Top-level `cache --help --output-format json` hangs with zero stdout/stderr instead of returning bounded command help JSON** — dogfooded 2026-04-30 for the 03:00 nudge on current `origin/main` / rebuilt `./rust/target/debug/claw` with embedded `git_sha` `d95b230c`. After #358 and #380 landed for the cost/tokens preflight help hangs, a fresh adjacent probe on the cache-control surface showed the same silent failure class: repeated bounded runs of `timeout --kill-after=1s 8s ./rust/target/debug/claw cache --help --output-format json` exited `124` with `stdout=0` and `stderr=0`. In the same rebuilt binary, `version --output-format json` returned promptly with version/build metadata, proving the binary itself and JSON output path are reachable. This is distinct from the separate `/cache` slash-command envelope mismatch class: the affected surface here is top-level `cache` command help, where agents need bounded local discovery before deciding whether to inspect, clear, or summarize cache state. **Required fix shape:** (a) make `cache --help --output-format json` return static/bounded stdout JSON with `kind:"help"` or `kind:"cache"`, `action:"help"`, usage, options, examples, supported output formats, and related slash/direct commands; (b) ensure help rendering does not initialize slow cache/session/provider state; (c) if any dynamic provider is consulted, return a typed JSON timeout/unavailable error instead of hanging; (d) add regression coverage proving cache help in JSON mode returns within a deterministic budget. **Why this matters:** cache inspection and cleanup are recovery/control-plane operations. If cache help hangs silently, claws cannot safely discover cache semantics before attempting cleanup, and automation stalls before it can choose a non-destructive cache action. Source: gaebal-gajae dogfood follow-up for the 03:00 nudge on rebuilt `./rust/target/debug/claw` `d95b230c`.
 
-422. **`export --output-format json` and `--resume latest` report the same "no managed sessions" scenario using two different `kind` codes — `no_managed_sessions` vs `session_load_failed` — making "no session found" undetectable by a single kind-code check** — dogfooded 2026-04-30 KST (UTC+9) by Jobdori on `e939777f`. Running `claw export --output-format json` with no session present returns (on stderr, exit 1): `{"error":"no managed sessions found in .claw/sessions/<fingerprint>/","hint":"Start \`claw\` to create a session, then rerun with \`--resume latest\`.\nNote: claw partitions sessions per workspace fingerprint; sessions from other CWDs are invisible.","kind":"no_managed_sessions","type":"error"}`. Running `claw --resume latest /status --output-format json` with no session present returns (on stderr, exit 1): `{"error":"failed to restore session: no managed sessions found in .claw/sessions/<fingerprint>/","hint":"Start \`claw\` to create a session, then rerun with \`--resume latest\`.\nNote: claw partitions sessions per workspace fingerprint; sessions from other CWDs are invisible.","kind":"session_load_failed","type":"error"}`. Both describe the same root condition — there are no sessions to operate on — but they expose it via different `kind` discriminants. Automation that checks `kind == "no_managed_sessions"` to detect a cold workspace will miss the `--resume` path's `session_load_failed`, and vice versa. A wrapper that guards "run with --resume only if a session exists" must special-case both codes. The hint text is identical between them, suggesting the messages are logically equivalent. Additionally neither code matches the proposed canonical names `session_not_found` / `session_load_failed` as stable `ErrorKind` discriminants described in ROADMAP #77's fix shape, which explicitly proposes typed error-kind codes for session lifecycle failures. **Required fix shape:** (a) unify "no sessions found for this workspace fingerprint" under a single canonical `kind` code — either `no_managed_sessions` or `session_not_found` — used consistently by every command path that encounters an empty session registry; (b) if `session_load_failed` is a more general category (covering e.g. corrupt session files, IO errors, schema version mismatches), it should nest a concrete `reason:"no_managed_sessions"` or `reason:"session_not_found"` sub-field so callers can distinguish "empty registry" from "found but unreadable"; (c) align with the canonical error-kind contract proposed in #77; (d) add regression coverage proving `export` and `--resume latest` in an empty workspace both return an error with the same top-level `kind` code. **Why this matters:** session guard-rails in orchestration need a single stable `kind` to detect cold workspaces without enumerating all possible no-session synonyms. Two divergent codes for the same condition make defensive automation brittle and contradict the promise of machine-readable error envelopes. Source: Jobdori live dogfood, `e939777f`, 2026-04-30 KST (UTC+9).
+420. **`plugins help --output-format json` returns the mutation response shape (`message`, `reload_runtime`, `target`) instead of the help envelope (`action:"help"`, `kind`, `unexpected`, `usage`) that `mcp help`, `agents help`, and `skills help` all use — schema drift within the same command family** — dogfooded 2026-05-01 by Jobdori on `e939777f`. Running `claw plugins help --output-format json` returns `{"action":"help","kind":"plugin","message":"Unknown /plugins action 'help'. Use list, install, enable, disable, uninstall, or update.","reload_runtime":false,"target":null}`. By contrast, `claw mcp help --output-format json`, `claw agents help --output-format json`, and `claw skills help --output-format json` all return a help envelope: `{"action":"help","kind":"<surface>","unexpected":null,"usage":{"direct_cli":"...","slash_command":"...","sources":[...]}}`. The `plugins` subgroup has not adopted the help envelope schema used by all sibling subgroups. Instead it uses the mutation response shape (`message`, `reload_runtime`, `target`) with an error string in `message` that calls `help` an "unknown action." Automation that checks `usage.direct_cli` to discover plugin commands gets a `TypeError` (key not found) on the plugins help path while succeeding on all sibling subgroups. **Required fix shape:** (a) make `plugins help` return the same help envelope as `mcp help`/`agents help`/`skills help`: `{action:"help", kind:"plugin", unexpected:null, usage:{direct_cli:"claw plugins [list|enable|disable|install|uninstall|update|help]", slash_command:"/plugins [...]", sources:[...]}`; (b) drop `reload_runtime` and `target` from help responses for all plugin subcommands; (c) add regression coverage proving `plugins help --output-format json` contains a `usage.direct_cli` field matching the same envelope shape as `mcp help`/`agents help`/`skills help`; (d) audit all subgroup `help` handlers for the same mutation-envelope contamination. **Why this matters:** help discovery is the bootstrap surface for automation. If `plugins help --output-format json` returns a mutation envelope with an error message instead of a usage envelope, automated schema discovery fails silently for the entire plugins subgroup while working for every other subgroup. Source: Jobdori live dogfood, `e939777f`, 2026-05-01.

rust/crates/commands/src/lib.rs

@@ -2596,44 +2596,10 @@ fn render_mcp_report_for(
                 )),
             }
         }
-        Some(args) if args.split_whitespace().next() == Some("list") && args.contains(' ') => {
-            // `mcp list <filter>` — list does not accept arguments; treat as unsupported action.
-            Ok(render_mcp_unsupported_action_text(
-                args,
-                "list accepts no filter argument; use `claw mcp list`",
-            ))
-        }
-        Some(args) if matches!(args.split_whitespace().next(), Some("info" | "describe")) => {
-            Ok(render_mcp_unsupported_action_text(
-                args,
-                "use `claw mcp show <server>` to inspect a server",
-            ))
-        }
         Some(args) => Ok(render_mcp_usage(Some(args))),
     }
 }
 
-fn render_mcp_unsupported_action_text(action: &str, hint: &str) -> String {
-    format!(
-        "MCP\n  Error            unsupported action '{action}'\n  Hint             {hint}\n  Usage            /mcp [list|show <server>|help]"
-    )
-}
-
-fn render_mcp_unsupported_action_json(action: &str, hint: &str) -> Value {
-    json!({
-        "kind": "mcp",
-        "action": "error",
-        "ok": false,
-        "error_kind": "unsupported_action",
-        "requested_action": action,
-        "hint": hint,
-        "usage": {
-            "slash_command": "/mcp [list|show <server>|help]",
-            "direct_cli": "claw mcp [list|show <server>|help]",
-        },
-    })
-}
-
 fn render_mcp_report_json_for(
     loader: &ConfigLoader,
     cwd: &Path,
@@ -2714,18 +2680,6 @@ fn render_mcp_report_json_for(
                 })),
             }
         }
-        Some(args) if args.split_whitespace().next() == Some("list") && args.contains(' ') => {
-            Ok(render_mcp_unsupported_action_json(
-                args,
-                "list accepts no filter argument; use `claw mcp list`",
-            ))
-        }
-        Some(args) if matches!(args.split_whitespace().next(), Some("info" | "describe")) => {
-            Ok(render_mcp_unsupported_action_json(
-                args,
-                "use `claw mcp show <server>` to inspect a server",
-            ))
-        }
         Some(args) => Ok(render_mcp_usage_json(Some(args))),
     }
 }
@@ -4687,38 +4641,6 @@ mod tests {
         );
     }
 
-    #[test]
-    fn mcp_unsupported_actions_return_typed_error_not_generic_help() {
-        // `mcp info <name>` and `mcp list <filter>` must return typed errors, not raw help.
-        // Regression for #504: these previously fell through to render_mcp_usage with
-        // unexpected=arg, giving no machine-readable error_kind.
-        use crate::handle_mcp_slash_command_json;
-        use std::path::PathBuf;
-        let cwd = PathBuf::from("/tmp");
-
-        let info_json = handle_mcp_slash_command_json(Some("info nonexistent"), &cwd)
-            .expect("info nonexistent should not error at IO level");
-        assert_eq!(info_json["kind"], "mcp");
-        assert_eq!(info_json["ok"], false);
-        assert_eq!(info_json["error_kind"], "unsupported_action");
-        assert!(info_json["hint"]
-            .as_str()
-            .unwrap_or_default()
-            .contains("show"));
-
-        let list_filter_json = handle_mcp_slash_command_json(Some("list nonexistent"), &cwd)
-            .expect("list nonexistent should not error at IO level");
-        assert_eq!(list_filter_json["kind"], "mcp");
-        assert_eq!(list_filter_json["ok"], false);
-        assert_eq!(list_filter_json["error_kind"], "unsupported_action");
-
-        let describe_json = handle_mcp_slash_command_json(Some("describe myserver"), &cwd)
-            .expect("describe myserver should not error at IO level");
-        assert_eq!(describe_json["kind"], "mcp");
-        assert_eq!(describe_json["ok"], false);
-        assert_eq!(describe_json["error_kind"], "unsupported_action");
-    }
-
     #[test]
     fn rejects_invalid_mcp_arguments() {
         let show_error = parse_error_message("/mcp show alpha beta");

rust/crates/rusty-claude-cli/tests/output_format_contract.rs

@@ -105,18 +105,6 @@ fn inventory_commands_emit_structured_json_when_requested() {
     let skills = assert_json_command(&root, &["--output-format", "json", "skills"]);
     assert_eq!(skills["kind"], "skills");
     assert_eq!(skills["action"], "list");
-
-    let plugins = assert_json_command(&root, &["--output-format", "json", "plugins"]);
-    assert_eq!(plugins["kind"], "plugin");
-    assert_eq!(plugins["action"], "list");
-    assert!(
-        plugins["reload_runtime"].is_boolean(),
-        "plugins reload_runtime should be a boolean"
-    );
-    assert!(
-        plugins["target"].is_null(),
-        "plugins target should be null when no plugin is targeted"
-    );
 }
 
 #[test]