Summary

Adds a /set-workspace slash command to change the working directory used by the terminal, file, and code-execution tools for the current CLI session. Aliases: /workspace, /cd, /setworkspace.

The change takes effect immediately — no /reset required — because all downstream caches that read cwd are kept in sync.

Why

Switching projects mid-session currently means either restarting Hermes (losing context) or relying on cd inside a terminal call (only updates the active terminal env, not file_tools' relative-path anchor or new sandboxes). /set-workspace makes this a first-class operation.

Behavior

/set-workspace                       # show current workspace + usage
/set-workspace ~/personal/foo        # absolute, with ~ expansion
/cd ../bar                           # relative, anchored on current TERMINAL_CWD
/workspace "/path with spaces/"      # quoted (single or double)
/set-workspace $MY_PROJECT           # env var expansion

Implementation

Updates the single source of truth (TERMINAL_CWD env var) plus all downstream caches that read from it on tool invocation:

1. os.environ["TERMINAL_CWD"] — read by every tool path that resolves cwd: file_tools relative-path anchoring, code_execution sandbox cwd, runtime footer, checkpoint manager, subagent inheritance via delegate_tool.
2. tools.terminal_tool._active_environments[*].cwd — the cwd actually fed to subprocesses for every long-lived shell or sandbox. Normally maintained by the cwd-marker mechanism on each cd; force-synced here because the user is changing it out-of-band.
3. tools.file_tools._file_ops_cache[*].cwd — ShellFileOperations prefers env.cwd (already updated above) and falls back to self.cwd, so we keep both in sync.

Session-scoped only; does not write to config.yaml. Failures during cache sync (e.g. a remote backend that refuses cwd reassignment) are isolated per-cache so they cannot block the env var update or other downstream caches.

Validation: rejects nonexistent paths, files, and directories without read+exec permission. Same-dir detected and reported as no-op.

Related Issues

This PR doesn't directly close any of these, but /set-workspace provides a manual escape hatch / mitigation for several long-standing pain points around session cwd handling:

• Config migration resets terminal.cwd and clears all auxiliary.*.model fields on upgrade #17182 [P1] — when hermes update resets terminal.cwd to a broken value, /set-workspace lets you recover the session in-place instead of restarting and losing context.
• [Bug]: Gateway working directory config not respected, and resets after update. #11312 — gateway working directory not respected after update; same recovery story applies.
• [Bug]: Telegram/gateway ignores profile working directory (pwd returns ~/.hermes/hermes-agent) #7663 — Telegram/gateway ignores profile working directory (pwd returns ~/.hermes/hermes-agent); /set-workspace is a usable workaround until the underlying profile-cwd discovery is fixed.
• [Bug]: terminal tool passes invalid workdir to Docker exec and overrides configured terminal.cwd #4669 — Docker backend terminal.cwd is overridden by invalid per-call workdir; orthogonal cause but same symptom (terminal lands in the wrong place), and /set-workspace lets the user re-anchor.
• Feature: session-scoped repo pinning to preserve repository identity across compression/resume #10309 — proposes session-scoped repo pinning to preserve repository identity across compression/resume. /set-workspace is a minimal manual precursor: explicit user-driven cwd switching as a building block toward automatic per-session pinning.

Test Plan

tests/cli/test_cli_set_workspace.py — 15 tests, all pass:

• Arg parsing: no-arg shows current + usage hint (no mutation), blank arg same, single/double quote stripping
• Path resolution: ~ expansion, $VAR expansion, relative paths anchored on TERMINAL_CWD not os.getcwd (load-bearing invariant — explicitly tested by moving the process cwd elsewhere)
• Validation: nonexistent rejected, file rejected, unreadable dir rejected (skipped under root), same-dir no-op
• Cache sync: active terminal envs synced, file_ops synced, partial sync failure isolated (one bad env doesn't block env var update or file_ops update)
• Registry wiring: all 4 aliases (set-workspace, setworkspace, workspace, cd) resolve to canonical name with cli_only=True

Full local regression: tests/cli/ + tests/hermes_cli/test_commands.py — 812 passed (8 unrelated ruamel-missing tests deselected, exists on main independent of this PR).

Files Changed

• hermes_cli/commands.py — register CommandDef (1 entry, 3 aliases)
• cli.py — add _handle_set_workspace_command (~95 lines including docstring + per-cache try/except blocks) and one-line dispatch in process_command
• tests/cli/test_cli_set_workspace.py — new, 15 tests

Notes

• For non-local terminal backends (docker/ssh/modal/etc.), TERMINAL_CWD still updates so file_tools relative-path resolution moves, but the recommendation in the docstring is to do cd via the terminal tool inside the remote session for shell-state correctness.
• Pattern mirrors how cron/scheduler.py already uses TERMINAL_CWD to bridge per-job workdir into the agent process.