ROADMAP #38 no longer reflects current main. The runtime already runs a
post-compaction session-health probe, but the backlog lacked explicit
regression proof. This change adds focused tests for the two important
behaviors: a broken tool surface aborts a compacted session with a targeted
error, while a freshly compacted empty session does not false-positive as
dead. With that proof in place, the roadmap item can be marked done.
Constraint: User required fresh cargo fmt/clippy/test evidence before closing any backlog item
Rejected: Leave #38 open because the implementation already existed | backlog stays stale and invites duplicate work
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Reopen#38 only with a fresh same-turn repro that bypasses the current health-probe gate
Tested: cargo fmt --all --check; cargo clippy --workspace --all-targets -- -D warnings; cargo test --workspace
Not-tested: No live long-running dogfood session replay beyond existing automated coverage
The ROADMAP #37 code path was correct, but the Rust and usage guides still
advertised `claw login` / `claw logout` and OAuth-login wording after the
command surface had been removed. This follow-up updates both docs to point
users at `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` only and removes the
stale command examples.
Constraint: Prior follow-up review rejected the closeout until user-facing auth docs matched the landed behavior
Rejected: Leave docs stale because runtime behavior was already correct | contradicts shipped CLI and re-opens support confusion
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: When auth policy changes, update both rust/README.md and USAGE.md in the same change as the code surface
Tested: cargo fmt --all --check; cargo clippy --workspace --all-targets -- -D warnings; cargo test --workspace
Not-tested: External rendered-doc consumers beyond repository markdown
ROADMAP #37 was still open even though several earlier backlog items were
already closed. This change removes the local login/logout surface, stops
startup auth resolution from treating saved OAuth credentials as a supported
path, and updates diagnostics/help to point users at ANTHROPIC_API_KEY or
ANTHROPIC_AUTH_TOKEN only.
While proving the change with the user-requested workspace gates, clippy
surfaced additional pre-existing warning failures across the Rust workspace.
Those were cleaned up in-place so the required `cargo fmt`, `cargo clippy
--workspace --all-targets -- -D warnings`, and `cargo test --workspace`
sequence now passes end to end.
Constraint: User explicitly required full-workspace fmt/clippy/test before commit/push
Constraint: Existing dirty leader worktree had to be stashed before attempted OMX team worktree launch
Rejected: Keep login/logout but hide them from help | left unsupported auth flow and saved OAuth fallback intact
Rejected: Stop after ROADMAP #37 targeted tests | did not satisfy required full-workspace verification gate
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Do not reintroduce saved OAuth as a silent Anthropic startup fallback without an explicit supported auth policy
Tested: cargo fmt --all --check; cargo clippy --workspace --all-targets -- -D warnings; cargo test --workspace
Not-tested: Remote push effects beyond origin/main update
ROADMAP #41 was still leaving a phantom-completion class open: managed
sessions could be resumed from the wrong workspace, and the CLI/runtime
paths were split between partially isolated storage and older helper
flows. This squashes the verified team work into one deliverable that
routes managed session operations through the per-worktree SessionStore,
rejects workspace mismatches explicitly, extends lane-event taxonomy for
workspace mismatch reporting, and updates the affected CLI regression
fixtures/docs so the new contract is enforced without losing same-
workspace legacy coverage.
Constraint: Keep same-workspace legacy flat sessions readable while blocking cross-worktree misuse
Constraint: No new dependencies; stay within the ROADMAP #41 changed-file scope
Rejected: Leave team auto-checkpoint history as final branch state | noisy/non-lore history for a single roadmap fix
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Preserve workspace_root validation on future resume/load helpers; do not reintroduce path-only fallback without equivalent mismatch checks
Tested: cargo test -p runtime session_control -- --nocapture; cargo test -p rusty-claude-cli resume -- --nocapture; cargo test -p rusty-claude-cli --test cli_flags_and_config_defaults; cargo test -p rusty-claude-cli --test output_format_contract; cargo test -p rusty-claude-cli --test resume_slash_commands; cargo test --workspace --exclude compat-harness; cargo check --workspace --all-targets; git diff --check
Not-tested: cargo clippy --workspace --all-targets -- -D warnings (pre-existing failures in unchanged rust/crates/rusty-claude-cli/build.rs)
Related: ROADMAP #41
Implements ROADMAP #40: Show warnings for broken/missing plugin manifests
instead of silently failing.
- Add PluginLoadFailure import
- New render_plugins_report_with_failures() function
- Shows ⚠️ warnings for failed plugin loads with error details
- Updates ROADMAP.md to mark #40 in progress
Ultraclaw droid session: ultraclaw-03-broken-plugins
When OPENAI_BASE_URL is set, the user explicitly configured an
OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, etc.). Model names
like 'qwen2.5-coder:7b' or 'llama3:latest' don't match any recognized
prefix, so detect_provider_kind() fell through to Anthropic — asking for
Anthropic credentials even though the user clearly intended a local
provider.
Now: OPENAI_BASE_URL + OPENAI_API_KEY beats Anthropic env-check in the
cascade. OPENAI_BASE_URL alone (no API key — common for Ollama) is a
last-resort fallback before the Anthropic default.
Source: MaxDerVerpeilte in #claw-code (Ollama + qwen2.5-coder:7b);
traced by gaebal-gajae.
The glob crate (v0.3) does not support shell-style brace groups like
{cs,uxml,uss}. Patterns such as 'Assets/**/*.{cs,uxml,uss}' silently
returned 0 results.
Added expand_braces() to pre-expand brace groups before passing patterns
to glob::glob(). Handles nested braces (e.g. src/{a,b}.{rs,toml}).
Results are deduplicated via HashSet.
5 new tests:
- expand_braces_no_braces
- expand_braces_single_group
- expand_braces_nested
- expand_braces_unmatched
- glob_search_with_braces_finds_files
Source: user 'zero' in #claw-code (Windows, Unity project with
Assets/**/*.{cs,uxml,uss} glob). Traced by gaebal-gajae.
Add 'model: Option<String>' to Session struct. The model used is now
saved in the session_meta JSONL record and surfaced in resumed /status:
- JSON mode: {model: 'claude-sonnet-4-6'} instead of null
- Text mode: shows actual model instead of 'restored-session'
Model is set in build_runtime_with_plugin_state() before the runtime
is constructed, and only when not already set (preserves model through
fork/resume cycles).
Backward compatible: old sessions without a model field load cleanly
with model: None (shown as null in JSON, 'restored-session' in text).
All workspace tests pass.
On Windows, HOME is often unset. The CLI crashed at startup with
'error: io error: HOME is not set' because three paths only checked
HOME:
- config_home_dir() in tools crate (config/settings loading)
- credentials_home_dir() in runtime crate (OAuth credentials)
- detect_broad_cwd() in CLI (CWD-is-home-dir check)
- skill lookup roots in tools crate
All now fall through to USERPROFILE when HOME is absent. Error message
updated to suggest USERPROFILE or CLAW_CONFIG_HOME on Windows.
Source: MaxDerVerpeilte in #claw-code (Windows user, 2026-04-10).
- Add #[allow(dead_code)] on test-only Delta struct (content field
used for deserialization but not read in assertion)
- Remove duplicated #[test] attribute on
assistant_message_without_tool_calls_omits_tool_calls_field
Zero warnings in cargo test --workspace.
claw --output-format json --resume <session> (no command) was printing:
'Restored session from <path> (N messages).'
to stdout as prose, regardless of output format.
Now emits:
{"kind":"restored","session_id":"...","path":"...","message_count":N}
159 CLI tests pass.
/session list previously returned 'unsupported resumed slash command' in
--output-format json --resume mode. It only reads the sessions directory
so does not need a live runtime session.
Adds a Session{action:"list"} arm in run_resume_command() before the
unsupported catchall. Emits:
{kind:session_list, sessions:[...ids], active:<current-session-id>}
159 CLI tests pass.
'failed to restore session' errors from both the path-resolution step
and the JSONL-load step now check output_format and emit:
{"type":"error","error":"failed to restore session: <detail>"}
instead of bare eprintln prose.
Covers: session not found, corrupt JSONL, permission errors.
/stats was accidentally listed in STUB_COMMANDS (both in the original list
and overlooked in 1e14d59). Since SlashCommand::Stats is fully implemented
with REPL and resume dispatch, it should not be intercepted as unimplemented.
/tokens and /cache alias to Stats and were already working correctly.
/stats now works again in all modes.
23 spec-registered commands had no parse arm in validate_slash_command_input,
causing the circular error 'Unknown slash command: /X — Did you mean /X?'
when users typed them in --resume mode.
Two fixes:
1. Add the 23 confirmed parse-armless commands to STUB_COMMANDS (excluded
from REPL completions and help output).
2. In resume dispatch, intercept STUB_COMMANDS before SlashCommand::parse
and emit a clean '{error: "/X is not yet implemented in this build"}'
instead of the confusing error from the Err parse path.
Affected: /allowed-tools, /bookmarks, /workspace, /reasoning, /budget,
/rate-limit, /changelog, /diagnostics, /metrics, /tool-details, /focus,
/unfocus, /pin, /unpin, /language, /profile, /max-tokens, /temperature,
/system-prompt, /notifications, /telemetry, /env, /project, plus ~40
additional unreachable spec names.
159 CLI tests pass.
/export now emits: {kind:export, file:<path>, message_count:<n>}
/agents now emits: {kind:agents, text:<agents report>}
Previously both returned json:None and fell through to prose output even
in --output-format json --resume mode. 159 CLI tests pass.
Two integration tests expected 'model':'restored-session' in the /status
JSON output but dc4fa55 changed resume mode to emit null for model.
Updated both assertions to assert model is null (correct behavior).
Also remove unused 'estimate_session_tokens' import in compact.rs tests
(surfaced as warning in CI, kept failing CI green noise).
All workspace tests pass.
/help now emits: {kind:help, text:<full help text>}
/diff now emits:
- no git repo: {kind:diff, result:no_git_repo, detail:...}
- clean tree: {kind:diff, result:clean, staged:'', unstaged:''}
- changes: {kind:diff, result:changes, staged:..., unstaged:...}
Previously both returned json:None and fell through to prose output even
in --output-format json --resume mode. 159 CLI tests pass.
Before: doctor reported 'loaded 0/5' and listed 5 'Discovered file'
entries for paths that don't exist on disk. This looked like 5 files
failed to load, when in fact they are just standard search locations.
After: only paths that actually exist on disk are shown as 'Discovered
file'. 'loaded N/M' denominator is now the count of present files, not
candidate paths. With no config files present: 'loaded 0/0' +
'Discovered files <none> (defaults active)'.
159 CLI tests pass.
Two bugs in --output-format json --resume /status:
1. 'model' field emitted 'restored-session' (a run-mode label) instead of
the actual model or null. Fixed: status_json_value now takes Option<&str>
for model; resume path passes None; live REPL path passes Some(model).
2. 'session_id' extracted parent dir name ('sessions') instead of the file
stem. Session files are session-<id>.jsonl directly under .claw/sessions/,
not in a subdirectory. Fixed: extract file_stem() instead of
parent().file_name().
159 CLI tests pass.
Adds sanitize_tool_message_pairing() called from build_chat_completion_request()
after translate_message() runs. Drops any role:"tool" message whose
immediately-preceding non-tool message is role:"assistant" but has no
tool_calls entry matching the tool_call_id.
This is the second layer of the tool-pairing invariant defense:
- 6e301c8: compaction boundary fix (producer layer)
- this commit: request-builder sanitizer (sender layer)
Together these close the 400-error loop for resumed/compacted multi-turn
tool sessions on OpenAI-compatible backends.
Sanitization only fires when preceding message is role:assistant (not
user/system) to avoid dropping valid translation artifacts from mixed
user-message content blocks.
Regression tests: sanitize_drops_orphaned_tool_messages covers valid pair,
orphaned tool (no tool_calls in preceding assistant), mismatched id, and
two tool results both referencing the same assistant turn.
116 api + 159 CLI + 431 runtime tests pass. Fmt clean.
/compact now emits: {kind:compact, skipped, removed_messages, kept_messages}
/clear now emits: {kind:clear, previous_session_id, new_session_id, backup, session_file}
/clear (no --confirm) now emits: {kind:error, error:..., hint:...}
Previously both returned json:None and fell through to prose output even
in --output-format json --resume mode. 159 CLI tests pass.
Before:
error: failed to extract manifests: No such file or directory (os error 2)
After:
error: failed to extract manifests: No such file or directory (os error 2)
looked in: /Users/yeongyu/clawd/claw-code/rust
The workspace_dir is computed from CARGO_MANIFEST_DIR at compile time and
only resolves correctly when running from the build tree. Surfacing the
resolved path lets users understand immediately why it fails outside the
build context.
ROADMAP #45 root cause (build-tree-only path) remains open.
Add SlashCommand::slash_name() to the commands crate — returns the
canonical '/name' string for any variant. Used in the REPL's stub
catch-all arm to surface which command was typed instead of printing
the opaque 'Command registered but not yet implemented.'
Before: typing /rewind → 'Command registered but not yet implemented.'
After: typing /rewind → '/rewind is not yet implemented in this build.'
Also update the compacts_sessions_via_slash_command test assertion to
tolerate the boundary-guard fix from 6e301c8 (removed_message_count
can be 1 or 2 depending on whether the boundary falls on a tool-result
pair). All 159 CLI + 431 runtime + 115 api tests pass.
Two fixes:
1. compact.rs: When the compaction boundary falls at the start of a
tool-result turn, the preceding assistant turn with ToolUse would be
removed — leaving an orphaned role:tool message with no preceding
assistant tool_calls. OpenAI-compat backends reject this with 400.
Fix: after computing raw_keep_from, walk the boundary back until the
first preserved message is not a ToolResult (or its preceding assistant
has been included). Regression test added:
compaction_does_not_split_tool_use_tool_result_pair.
Source: gaebal-gajae multi-turn tool-call 400 repro 2026-04-09.
2. /cost resume: add JSON output:
{kind:cost, input_tokens, output_tokens, cache_creation_input_tokens,
cache_read_input_tokens, total_tokens}
159 CLI + 431 runtime tests pass. Fmt clean.
Two gaps closed:
1. /memory (resume): json field was None, emitting prose regardless of
--output-format json. Now emits:
{kind:memory, cwd, instruction_files:N, files:[{path,lines,preview}...]}
2. /providers (resume): had a spec entry but no parse arm, producing the
circular 'Unknown slash command: /providers — Did you mean /providers'.
Added 'providers' as an alias for 'doctor' in the parse match so
/providers dispatches to the same structured diagnostic output.
3. /doctor (resume): also wired json_value() so --output-format json
returns the structured doctor report instead of None.
Continues ROADMAP #26 resumed-command JSON parity track.
159 CLI tests pass, fmt clean.
Same fix as ff416ff but for the streaming path. Some backends embed an
error JSON object in an SSE data: frame:
data: {"error":{"message":"context too long","code":400}}
parse_sse_frame() was attempting to deserialize this as ChatCompletionChunk
and failing with 'missing field' / 'invalid type', hiding the actual
backend error message.
Fix: check for an 'error' key before full chunk deserialization, same as
the non-streaming path in ff416ff. Symmetric pair:
- ff416ff: non-streaming path (response body)
- this: streaming path (SSE data: frame)
115 api + 159 CLI tests pass. Fmt clean.
When a local/proxy OpenAI-compatible backend returns an error object:
{"error":{"message":"...","type":"...","code":...}}
claw was trying to deserialize it as a ChatCompletionResponse and
failing with the cryptic 'failed to parse OpenAI response: missing
field id', completely hiding the actual backend error message.
Fix: before full deserialization, check if the parsed JSON has an
'error' key and promote it directly to ApiError::Api so the user
sees the real error (e.g. 'The number of tokens to keep from the
initial prompt is greater than the context length').
Source: devilayu in #claw-code 2026-04-09 — local LM Studio context
limit error was invisible; user saw 'missing field id' instead.
159 CLI + 115 api tests pass. Fmt clean.
When serializing a multi-turn conversation for the OpenAI-compatible path,
assistant messages with no tool calls were always emitting 'tool_calls: []'.
Some providers reject requests where a prior assistant turn carries an
explicit empty tool_calls array (400 on subsequent turns after a plain
text assistant response).
Fix: only include 'tool_calls' in the serialized assistant message when
the vec is non-empty. Empty case omits the field entirely.
This is a companion fix to fd7aade (null tool_calls in stream delta).
The two bugs are symmetric: fd7aade handled inbound null -> empty vec;
this handles outbound empty vec -> field omitted.
Two regression tests added:
- assistant_message_without_tool_calls_omits_tool_calls_field
- assistant_message_with_tool_calls_includes_tool_calls_field
115 api tests pass. Fmt clean.
Source: gaebal-gajae repro 2026-04-09 (400 on multi-turn, companion to
null tool_calls stream-delta fix).
/config resumed returned json:None, falling back to prose output even in
--output-format json mode. Adds render_config_json() that produces:
{
"kind": "config",
"cwd": "...",
"loaded_files": N,
"merged_keys": N,
"files": [{"path":"...","source":"user|project|local","loaded":true|false}, ...]
}
Wires it into the SlashCommand::Config resume arm alongside the existing
prose render. Continues the resumed-command JSON parity track (ROADMAP #26).
159 CLI tests pass, fmt clean.
Some OpenAI-compatible providers emit 'tool_calls: null' in streaming
delta chunks instead of omitting the field or using an empty array:
"delta": {"content":"","function_call":null,"tool_calls":null}
serde's #[serde(default)] only handles absent keys — an explicit null
value still fails deserialization with:
'invalid type: null, expected a sequence'
Fix: replace #[serde(default)] with a custom deserializer helper
deserialize_null_as_empty_vec() that maps null -> Vec::default(),
keeping the existing absent-key default behaviour.
Regression test added: delta_with_null_tool_calls_deserializes_as_empty_vec
uses the exact provider response shape from gaebal-gajae's repro (2026-04-09).
112 api lib tests pass. Fmt clean.
Companion to gaebal-gajae's local 448cf2c — independently reproduced
and landed on main.
Dogfood found that /tokens and /cache had spec entries (resume_supported:
true) but no parse arms in the command parser, resulting in:
'Unknown slash command: /tokens — Did you mean /tokens'
(the suggestion engine found the spec entry but parsing always failed)
Fix three things:
1. Add 'tokens' | 'cache' as aliases for 'stats' in the parse match so
the commands actually resolve to SlashCommand::Stats
2. Implement SlashCommand::Stats in the REPL dispatch — previously fell
through to 'Command registered but not yet implemented'. Now shows
cumulative token usage for the session.
3. Implement SlashCommand::Stats in run_resume_command — previously
returned 'unsupported resumed slash command'. Now emits:
text: Cost / Input tokens / Output tokens / Cache create / Cache read
json: {kind:stats, input_tokens, output_tokens, cache_*, total_tokens}
159 CLI tests pass, fmt clean.
Users launching claw from their home directory (or /) have no project
boundary — the agent can read/search the entire machine, often far beyond
the intended scope. kapcomunica in #claw-code reported exactly this:
'it searched my entire computer.'
Add warn_if_broad_cwd() called at prompt and REPL startup:
- checks if CWD == $HOME or CWD has no parent (fs root)
- prints a clear warning to stderr:
Warning: claw is running from a very broad directory (/home/user).
The agent can read and search everything under this path.
Consider running from inside your project: cd /path/to/project && claw
Warning fires on both claw (REPL) and claw prompt '...' paths.
Does not fire from project subdirectories. Uses std::env::var_os("HOME"),
no extra deps.
159 CLI tests pass, fmt clean.
When claw --output-format json --resume <session> /commit (or /plugins, etc.)
encountered an 'unsupported resumed slash command' error, it called
eprintln!() and exit(2) directly, bypassing both the main() JSON error
handler and the output_format check.
Fix: in both the slash-command parse-error path and the run_resume_command
Err path, check output_format and emit a structured JSON error:
{"type":"error","error":"unsupported resumed slash command","command":"/commit"}
Text mode unchanged (still exits 2 with prose to stderr).
Addresses the resumed-command parity gap (gaebal-gajae ROADMAP #26 track).
159 CLI tests pass, fmt clean.
When stdin is not a terminal (pipe or redirect) and no prompt is given on
the command line, claw was starting the interactive REPL and printing the
startup banner, then consuming the pipe without sending anything to the API.
Fix: in parse_args, when rest.is_empty() and stdin is not a terminal, read
stdin synchronously and dispatch as CliAction::Prompt instead of Repl.
Empty pipe still falls through to Repl (interactive launch with no input).
Before: echo 'hello' | claw -> startup banner + REPL start
After: echo 'hello' | claw -> dispatches as one-shot prompt
159 CLI tests pass, fmt clean.
Previously claw --resume <session> /diff would produce:
'git diff --cached failed: error: unknown option `cached\''
when the CWD was not inside a git project, because git falls back to
--no-index mode which does not support --cached.
Two fixes:
1. render_diff_report_for() checks 'git rev-parse --is-inside-work-tree'
before running git diff, and returns a human-readable message if not
in a git repo:
'Diff\n Result no git repository\n Detail <cwd> is not inside a git project'
2. resume /diff now uses std::env::current_dir() instead of the session
file's parent directory as the CWD for the diff (session parent dir
is the .claw/sessions/<id>/ directory, never a git repo).
159 CLI tests pass, fmt clean.
Previously claw --output-format json --resume <session> /history emitted
prose text regardless of the output format flag. Now emits structured JSON:
{"kind":"history","total":N,"showing":M,"entries":[{"timestamp_ms":...,"text":"..."},...]}
Mirrors the parity pattern established in ROADMAP #26 for other resume commands.
159 CLI tests pass, fmt clean.
When running claw --output-format json --resume <session> /status, the
JSON output had 'session' (full file path) but no 'session_id' field,
making it impossible for scripts to extract the loaded session ID.
Now extracts the session-id directory component from the session path
(e.g. .claw/sessions/<session-id>/session-xxx.jsonl → session-id)
and includes it as 'session_id' in the JSON status envelope.
159 CLI tests pass, fmt clean.
Previously 'claw state' printed an error message but exited 0, making it
impossible for scripts/CI to detect the absence of state without parsing
prose. Now propagates Err() to main() which exits 1 and formats the error
correctly for both text and --output-format json modes.
Text: 'error: no worker state file found at ... — run a worker first'
JSON: {"type":"error","error":"no worker state file found at ..."}
3 new tests in mod tests:
- rejects_invalid_reasoning_effort_value: confirms 'turbo' etc rejected at parse time
- accepts_valid_reasoning_effort_values: confirms low/medium/high accepted and threaded
- stub_commands_absent_from_repl_completions: asserts STUB_COMMANDS are not in completions
156 -> 159 CLI tests pass.
When claw --output-format json hits an error, the error was previously
printed as plain prose to stderr, making it invisible to downstream tooling
that parses JSON output. Now:
{"type":"error","error":"api returned 401 ..."}
Detection: scan argv at process exit for --output-format json or
--output-format=json. Non-JSON error path unchanged. 156 CLI tests pass.
Users were typing skill names (e.g. 'caveman', 'find-skills') directly in
the REPL and getting LLM responses instead of skill invocation. Only
'/skills <name>' triggered dispatch; bare names fell through to run_turn.
Fix: after slash-command parse returns None (bare text), check if the first
token looks like a skill name (alphanumeric/dash/underscore, no slash).
If resolve_skill_invocation() confirms the skill exists, dispatch the full
input as a skill prompt. Unknown words fall through unchanged.
156 CLI tests pass, fmt clean.
Previously any string was accepted and silently forwarded to the API,
which would fail at the provider with an unhelpful error. Now invalid
values produce a clear error at parse time:
invalid value for --reasoning-effort: 'xyz'; must be low, medium, or high
156 CLI tests pass, fmt clean.
The --help slash-command section was listing ~35 unimplemented commands
alongside working ones. Combined with the completions fix (c55c510), the
discovery surface now consistently shows only implemented commands.
Changes:
- commands crate: add render_slash_command_help_filtered(exclude: &[&str])
- move STUB_COMMANDS to module-level const in main.rs (reused by both
completions and help rendering)
- replace render_slash_command_help() with filtered variant at all
help-rendering call sites
156 CLI tests pass, fmt clean.
'claw prompt --help' was triggering an API call instead of showing help
because --help was parsed as part of the prompt args. Now '--help' after
known pass-through subcommands (prompt, login, logout, version, state,
init, export, commit, pr, issue) sets wants_help=true and shows the
top-level help page.
Subcommands that consume their own args (agents, mcp, plugins, skills)
and local help-topic subcommands (status, sandbox, doctor) are excluded
from this interception so their existing --help handling is preserved.
156 CLI tests pass, fmt clean.
