feat(cli): --safe-mode troubleshooting flag (Claude Code v2.1.169-inspired)

[teknium1]

Summary

Refactor + completeness pass on --safe-mode (feature already on main): centralizes the env-gate wiring in _apply_safe_mode(args), extends safe mode to all agent entrypoints via _prepare_agent_startup, and closes the last customization gap — config-declared shell hooks now also skip registration under safe mode.

Changes

• hermes_cli/main.py: _apply_safe_mode(args) chokepoint, called from cmd_chat AND _prepare_agent_startup — so --safe-mode now takes effect on every agent subcommand/oneshot path, not just hermes chat
• agent/shell_hooks.py: register_from_config() no-ops under HERMES_SAFE_MODE — hooks are user customizations too, and they previously registered regardless (they bypass plugin discovery, and load_config() does not honor HERMES_IGNORE_USER_CONFIG)
• hermes_cli/plugins.py, tools/mcp_tool.py: drop duplicated prose comments at the gates
• tests/hermes_cli/test_safe_mode.py: rewritten from logic-mirroring classes to direct behavior tests (real parser → real cmd_chat/_prepare_agent_startup); + shell-hook skip/register pair
• docs: hook skip documented in cli-commands.md + environment-variables.md (en + zh)

Validation

Check	Result
tests/hermes_cli/test_safe_mode.py	9 passed
tests/agent/test_shell_hooks.py	56 passed
tests/hermes_cli/test_plugins.py + test_startup_plugin_gating.py	137 passed
ruff + ty on touched files	clean
E2E (isolated HERMES_HOME, real user plugin + MCP server + config hook)	safe: 0 plugins, 0 MCP servers, 0 hooks · normal: 52 plugins (incl. user plugin), MCP loads, 1 hook registers

Left alone on purpose: oneshot skip_context_files/skip_memory plumbing — that's the territory of open contributor PRs #59402 / #51797.

Infographic

[github-actions]

🔎 Lint report: claude-code-inspired/safe-mode vs origin/main

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 10876 on HEAD, 10878 on base (✅ -2)

🆕 New issues (1):

Rule	Count
invalid-assignment	1

First entries

tests/run_agent/test_credits_notices_toggle.py:76: [invalid-assignment] invalid-assignment: Object of type `None` is not assignable to attribute `_credits_session_start_micros` of type `int`

✅ Fixed issues (2):

Rule	Count
unresolved-attribute	2

First entries

tests/run_agent/test_credits_notices_toggle.py:76: [unresolved-attribute] unresolved-attribute: Unresolved attribute `_credits_session_start_micros` on type `AIAgent`
run_agent.py:2891: [unresolved-attribute] unresolved-attribute: Object of type `Self@get_credits_spent_micros` has no attribute `_credits_session_start_micros`

Unchanged: 5707 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.

[teknium1]

Refreshed against current origin/main and force-pushed as cleanup-only.

Important: the safe-mode feature itself already landed on main via #45488. This branch is now just cleanup/reduction on top of that implementation.

Cleanup:

• centralizes safe-mode env setup in _apply_safe_mode(args)
• removes duplicated verbose comments from plugin/MCP gates
• tightens direct behavior tests
• net 102 insertions / 105 deletions

Validation:

• python3 -m pytest tests/hermes_cli/test_safe_mode.py -> 7 passed
• python3 -m pytest tests/hermes_cli/test_safe_mode.py tests/hermes_cli/test_argparse_flag_propagation.py -> 24 passed
• python3 -m pytest tests/hermes_cli/test_plugins.py tests/hermes_cli/test_startup_plugin_gating.py tests/hermes_cli/test_ignore_user_config_flags.py tests/hermes_cli/test_safe_mode.py -> 141 passed
• python3 -m compileall -q hermes_cli/_parser.py hermes_cli/main.py hermes_cli/plugins.py tools/mcp_tool.py tests/hermes_cli/test_safe_mode.py -> passed
• python3 -m ruff check hermes_cli/_parser.py hermes_cli/main.py hermes_cli/plugins.py tools/mcp_tool.py tests/hermes_cli/test_safe_mode.py -> passed
• git diff --check -> passed