feat: unify agent isolation (--ignore-rules / --safe-mode) across TUI, messaging gateway, and API server

[YuYigeng]

Problem

--ignore-rules / HERMES_IGNORE_RULES and --safe-mode / HERMES_SAFE_MODE are honored by CLI chat and -z oneshot sessions, but not consistently by the other agent session entry points. On current main:

• TUI session agents read only HERMES_IGNORE_RULES; HERMES_SAFE_MODE is ignored for the skip flags, and TUI background turns do not inherit the parent session's isolation.
• The messaging gateway only supports an opt-in per-platform gateway.platforms.<platform>.skip_context_files config; both env vars are ignored on foreground turns and background tasks.
• The API server constructs AIAgent without either skip flag and never reads the env vars.
• CLI background tasks and ACP (Agent Client Protocol) sessions construct AIAgent without the skip flags.

Root cause

Isolation intent is resolved per entry point instead of once. --ignore-rules and --safe-mode are normalized to HERMES_IGNORE_RULES / HERMES_SAFE_MODE at CLI startup, but the other agent construction sites never resolve them, so AIAgent receives default False skip flags and injects rules/memory even when isolation was requested.

Scope

Included:

• agent/isolation.py: one private resolver, precedence = explicit flag > env (HERMES_IGNORE_RULES, HERMES_SAFE_MODE; safe mode implies ignore-rules) > default False; returns (skip_context_files, skip_memory).
• TUI session agent construction (tui_gateway/server.py, _make_agent) and TUI background/preview turns (_background_agent_kwargs).
• Messaging gateway foreground turns and background tasks (gateway/run.py), including the agent cache signature so a cached AIAgent is never reused across an isolation change.
• API server agent construction (gateway/platforms/api_server.py).
• CLI background tasks (hermes_cli/cli_commands_mixin.py).
• ACP session agents (acp_adapter/session.py).
• Docs and per-entry behavior tests.

Not included (follow-ups): -z oneshot / Termux wiring (tracked in #72075, kept independent; can be refactored onto the shared resolver after it merges); cron / batch / curator / delegate worker policies (deliberate internal contracts); new config.yaml keys (public config surface, only if maintainers want it).

Design

One resolver as the single source of truth. For the gateway, isolation composes with the existing per-platform latency opt-out: skip_context_files = isolation OR platform config, skip_memory = isolation. Default behavior is unchanged everywhere.

Coverage matrix

Entry	Before	After	Test
CLI chat	env honored	unchanged	existing
CLI oneshot / Termux	#72075	unchanged (merged separately)	#72075
CLI background task	neither	both	resolver contract + review
TUI session	HERMES_IGNORE_RULES only	both env vars	test_make_agent_forwards_isolation_env
TUI background turn	no inheritance	inherits parent session	test_background_agent_kwargs_inherits_isolation
Messaging gateway foreground	per-platform config only	config OR isolation; cache signature includes both skip flags	test_skip_context_files_change_different_signature, test_skip_memory_change_different_signature, test_resolve_gateway_isolation_skip_flags
Messaging gateway background task	neither	both	test_resolve_gateway_isolation_skip_flags
API server	neither	both	test_create_agent_honors_isolation_env
ACP session	neither	both	test_make_agent_forwards_isolation_env, test_make_agent_defaults_isolation_off

Compatibility

• Default behavior: unchanged (resolver returns False when no flag/env is set).
• Existing config: the gateway per-platform skip_context_files key keeps working and composes with isolation.
• Public API: no public interface or config format changes.
• Session cache: skip_memory now participates in the gateway agent cache signature, so an isolation toggle rebuilds the agent instead of silently reusing a stale one.

Related / competing work

• Scope proposal: Scope proposal: unify agent isolation (--ignore-rules / --safe-mode) across TUI, messaging gateway, and API server #88214
• Canonical oneshot issues (open): [Bug] hermes -z silently ignores --ignore-rules (oneshot path never reads HERMES_IGNORE_RULES) #26633, oneshot (-z) has no way to skip built-in memory injection — --ignore-rules is silently ignored #72064
• Oneshot fix kept independent: fix(cli): honor --ignore-rules in oneshot mode #72075
• Earlier partial oneshot fixes (open, not updated): fix(cli): honor --ignore-rules in oneshot mode #26771, fix(oneshot): honor --skills / --ignore-rules / --ignore-user-config in -z mode #59402
• Respect HERMES_IGNORE_RULES in gateway agent creation #29930: earlier partial gateway-only fix for HERMES_IGNORE_RULES (stale base, not updated since 2026-07). This PR covers that gateway path plus safe mode, background tasks, cache invalidation, TUI, CLI background, API server, and ACP via the shared resolver.

Validation

Command	Result
scripts/run_tests.sh tests/agent/test_isolation.py tests/gateway/test_isolation_skip_flags.py tests/gateway/test_agent_cache.py tests/acp/test_session.py	passed
scripts/run_tests.sh tests/test_tui_gateway_server.py	573+ passed
scripts/run_tests.sh tests/gateway/test_api_server.py	passed
ruff check on changed files	passed
git diff --check	clean