Feature request

Add a first-class automatic fresh-session handoff mode for long-running Hermes tasks when context compression becomes risky or repeatedly degrades.

The goal is to avoid the failure mode where a useful, multi-hour agent session keeps compressing in-place until it becomes slow, inaccurate, or prone to ACP/gateway stalls. Instead, Hermes should be able to create a compact handoff packet, end the risky session cleanly, and continue in a fresh session/agent with a small, task-focused context.

Motivation

In long VS Code ACP / coding sessions, compression can keep the conversation alive, but after several compressions the session becomes fragile:

• context summaries can become lossy;
• completed tasks can remain overrepresented;
• current task focus can drift;
• preflight/auxiliary compression can be slow or timeout;
• ACP clients can appear stuck while the backend is still trying to compress or recover.

A concrete related bug was filed as #20250, where a VS Code ACP prompt remained in-flight after repeated compression timeout. That issue is about fixing the stall/error path. This feature request is about a proactive lifecycle policy: before repeated compression becomes dangerous, hand off to a fresh agent/session.

Hermes already has useful building blocks:

• context compression;
• session DB parent/child links and end_reason='compression' continuation chains;
• /new / /reset session controls;
• session search and persisted transcripts;
• subagent/fresh process capabilities.

But today those pieces do not provide a product-level fresh-agent handoff. The live runtime generally continues with compressed context rather than producing a clean handoff artifact and starting a fresh context.

Proposed behavior

Add configurable policy, for example:

agent:
  auto_handoff_on_compression:
    enabled: false
    after_compressions: 2
    max_prompt_tokens: null          # optional absolute token trigger
    on_compression_failure: true     # trigger after fallback/timeout/lossy marker
    mode: fresh_session              # fresh_session | fresh_process | prompt_user
    handoff_artifact_dir: .hermes/handoffs
    max_auto_handoffs: 3
    require_clean_checkpoint: true
    prompt: |
      Create a compact handoff packet for a fresh Hermes session. Include repo path,
      branch, git status, active plan/artifact paths, completed work, validation already
      run, blockers, and exact next task. Do not include secrets or raw credentials.

Trigger examples

Hermes could offer a handoff when any configured threshold is met:

1. compression count reaches after_compressions;
2. preflight prompt tokens exceed max_prompt_tokens or a model-derived threshold;
3. compression summary generation fails and Hermes inserts a fallback/lossy marker;
4. repeated compression cooldowns or timeouts happen;
5. the user explicitly runs a command such as /handoff or /fresh.

Handoff packet

The outgoing session should produce a structured, compact packet that a fresh agent can trust and verify:

# Hermes handoff packet

## Scope
- Workspace/repo path:
- Current branch:
- Current task/request:
- Active profile/model/toolsets:

## Current repo state
- `git status --short` summary:
- Staged/unstaged files:
- Latest relevant commits:

## Completed work
- ...

## Validation already run
- command:
- result:
- evidence path/log path:

## Open blockers / approvals needed
- ...

## Next recommended action
- exact next command or task:

## Safety notes
- do not repeat:
- do not modify without approval:
- secrets intentionally omitted:

Prefer saving this packet as an artifact, for example:

.hermes/handoffs/<session-id>-<timestamp>.md

The packet should avoid secrets, avoid dumping huge raw tool output, and prefer references to files/logs/artifacts that the fresh agent can inspect.

Platform UX

CLI / TUI

• Show a clear message: Session compressed 2 times; creating fresh handoff...
• Start a new session automatically when configured, or ask: Continue in fresh session? [Y/n].
• New session starts with the handoff packet plus an instruction to verify live repo state before editing.

Gateway / messaging

• For unattended/high-autonomy sessions, auto-handoff can continue in a new logical session and post a short notice with the handoff path.
• For lower-autonomy settings, send the handoff packet and ask the user to confirm continuation.

ACP / VS Code

ACP is the most important case for this request.

Minimum viable behavior:

• Old ACP turn completes cleanly with a visible handoff message and artifact path.
• Hermes emits enough metadata/event information for clients to present a Continue in fresh session action.
• If client-side auto-switch is not available, the final message should be copy/paste-ready for a new chat.

Ideal behavior:

• Hermes starts a fresh ACP session, linked to the prior session, and the VS Code extension switches or offers a one-click switch to it.

Safety / autonomy rules

The feature should not blindly continue through risky boundaries.

Suggested defaults:

• disabled by default initially;
• mode: prompt_user or fresh_session only after a safe checkpoint;
• stop and ask if destructive/external side effects are next;
• require clean git status or a checkpoint commit when require_clean_checkpoint: true;
• never include secrets, tokens, .env values, raw credentials, or private health/payment data in the handoff packet;
• preserve links to original session/transcript for auditability.

Acceptance criteria

• Config schema and defaults exist for agent.auto_handoff_on_compression.
• Hermes tracks compression count / lossy compression failures in a way the policy can use.
• A manual command (/handoff or similar) can produce a handoff packet without starting a new session.
• Automatic policy can trigger after N compressions or compression failure.
• Old session is finalized cleanly with a distinct end reason such as handoff or compression_handoff.
• New session is linked to the old one via parent_session_id or equivalent relationship.
• Fresh session starts with the handoff packet and verifies live repo state before editing.
• ACP/gateway clients receive a clear final/transition message rather than a dangling in-flight prompt.
• Tests cover CLI/TUI, gateway/API, and ACP lifecycle behavior.

Related issues

• [Bug]: VS Code ACP prompt can remain in-flight indefinitely after repeated compression timeout #20250 — bug: VS Code ACP prompt can remain in-flight after repeated compression timeout. This feature would reduce the likelihood of reaching that state, but does not replace the need to fix the stall path.
• Expose real prompt context usage and compaction metadata in API run events #15618 — exposing context/compression metadata in API run events would make this easier for clients to display.
• Feature: Cross-Platform Session Handoff (CLI ↔ Telegram ↔ iMessage) #8366 — cross-platform session handoff. This request is narrower/different: automatic lifecycle handoff to a fresh context because compression has become risky.
• Feature: Context Compaction Quality Overhaul — Handoff-Oriented Prompts, User Message Preservation, and Configurable Compaction (inspired by Codex CLI) #499 — context compaction quality / handoff-oriented prompts. This request is not just a better compaction prompt; it asks for a first-class fresh-session/agent lifecycle transition.

Why this should be first-class

Users can manually ask for a handoff today, but manual handoffs happen too late: the user notices the session is stale only after it has already become degraded or stuck. Hermes has enough internal signals to detect the danger earlier and either offer or perform a clean transition.

A proactive handoff policy would make long-running coding and operations sessions more reliable than repeatedly compressing the same live session until it fails.