thwip-cli 1.1.3__tar.gz → 1.2.0__tar.gz

{thwip_cli-1.1.3 → thwip_cli-1.2.0}/.github/workflows/publish.yml

@@ -49,7 +49,7 @@ jobs:
         run: uv build
 
       - name: Verify package metadata
-        run: uvx twine check dist/*
+        run: uvx twine check dist/*.whl dist/*.tar.gz
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
@@ -60,5 +60,7 @@ jobs:
         uses: softprops/action-gh-release@v2
         if: startsWith(github.ref, 'refs/tags/')
         with:
-          files: dist/*
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
           generate_release_notes: true

{thwip_cli-1.1.3 → thwip_cli-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thwip-cli
-Version: 1.1.3
+Version: 1.2.0
 Summary: Universal coding agent multiplexer: detect, switch, and route between AI coding agents seamlessly
 Project-URL: Homepage, https://github.com/tanmayhutt/thwip-cli
 Project-URL: Repository, https://github.com/tanmayhutt/thwip-cli
@@ -46,7 +46,8 @@ Description-Content-Type: text/markdown
 ## Features
 
 - **Auto-Detection**: Discovers installed AI coding agents (Claude Code, Antigravity, Gemini CLI, OpenAI/Codex, Aider, Copilot, Cursor, Windsurf, Cline, Ollama) and configured credentials.
-- **Context Portability**: Switch between Anthropic Claude, Google Gemini, OpenAI Codex, or local Ollama mid-project. Conversation history and working files transfer directly.
+- **Context Portability**: Switch providers with stored conversational text. Working files remain in the selected local project; they are not automatically uploaded.
+- **Handoff Preview**: Inspect text continuity, omitted state, capability changes, approximate context pressure, and a text fingerprint before switching. Runs locally without model calls.
 - **Dynamic UI**: Terminal interface adapts its status bar, capabilities, and theme based on the active provider.
 - **Capability Disclaimers**: Highlights when an agent lacks specific capabilities such as file editing or code execution.
 - **Rate Limit Failover**: Detects HTTP 429 errors or quota exhaustion and prompts instant switching to ready fallback models.
@@ -89,6 +90,7 @@ thwip
 | Command | Action |
 |:---|:---|
 | `/switch [agent] [model]` | Switch active agent or model mid-conversation |
+| `/handoff [agent] [model]` | Preview a target locally without switching or sending data |
 | `/agents` | Show all detected coding agents, company status, and capabilities |
 | `/models [agent]` | List available models for current or target agent |
 | `/key [provider]` | Enter an API key securely without placing it in prompt history |
@@ -111,6 +113,39 @@ Short aliases are available for frequent commands: `/a`, `/m`, `/s`, `/k`, `/g`,
 
 ---
 
+## Auditable handoffs
+
+```text
+/handoff
+/handoff google
+/handoff openai gpt-5.6-terra
+```
+
+`/handoff` previews the current target; specifying a provider uses its default model
+unless you supply a model ID. Targets can be inspected without credentials or an
+installed provider. `/switch` shows the same report before changing the active agent.
+
+The report includes:
+
+- Exact counts of transferred user/assistant text messages and excluded stored records.
+- A count of observed transient tool results that are not in portable history. New
+  sessions track from creation; older saved sessions explicitly report partial coverage.
+- Capability gains and losses using the local model catalog.
+- Approximate request size including tool schemas, with up to 4,096 tokens reserved
+  for an answer in the advisory calculation. This does not change generation settings.
+- SHA-256 of canonical system-prompt and conversational-text JSON. It stays the same
+  across targets when that text is unchanged. Tool schemas and attribution metadata
+  are intentionally outside this text fingerprint.
+
+The preview makes no model requests, saves no transcript exports, executes no tools,
+and does not trim or summarize history. Token sizing uses UTF-8 bytes divided by four
+plus per-message overhead, not a provider tokenizer. Catalog limits can be stale;
+an apparently fitting request can still fail. Warnings are advisory, not switch gates.
+Hidden reasoning and provider-native state do not transfer. The digest proves neither
+delivery nor semantic understanding, and is not a signature or privacy guarantee.
+
+See [research and prior art](docs/handoff-research.md) for the differentiation rationale.
+
 ## Supported Companies and Agents
 
 | Company | Agent | Capabilities |

{thwip_cli-1.1.3 → thwip_cli-1.2.0}/README.md

@@ -9,7 +9,8 @@
 ## Features
 
 - **Auto-Detection**: Discovers installed AI coding agents (Claude Code, Antigravity, Gemini CLI, OpenAI/Codex, Aider, Copilot, Cursor, Windsurf, Cline, Ollama) and configured credentials.
-- **Context Portability**: Switch between Anthropic Claude, Google Gemini, OpenAI Codex, or local Ollama mid-project. Conversation history and working files transfer directly.
+- **Context Portability**: Switch providers with stored conversational text. Working files remain in the selected local project; they are not automatically uploaded.
+- **Handoff Preview**: Inspect text continuity, omitted state, capability changes, approximate context pressure, and a text fingerprint before switching. Runs locally without model calls.
 - **Dynamic UI**: Terminal interface adapts its status bar, capabilities, and theme based on the active provider.
 - **Capability Disclaimers**: Highlights when an agent lacks specific capabilities such as file editing or code execution.
 - **Rate Limit Failover**: Detects HTTP 429 errors or quota exhaustion and prompts instant switching to ready fallback models.
@@ -52,6 +53,7 @@ thwip
 | Command | Action |
 |:---|:---|
 | `/switch [agent] [model]` | Switch active agent or model mid-conversation |
+| `/handoff [agent] [model]` | Preview a target locally without switching or sending data |
 | `/agents` | Show all detected coding agents, company status, and capabilities |
 | `/models [agent]` | List available models for current or target agent |
 | `/key [provider]` | Enter an API key securely without placing it in prompt history |
@@ -74,6 +76,39 @@ Short aliases are available for frequent commands: `/a`, `/m`, `/s`, `/k`, `/g`,
 
 ---
 
+## Auditable handoffs
+
+```text
+/handoff
+/handoff google
+/handoff openai gpt-5.6-terra
+```
+
+`/handoff` previews the current target; specifying a provider uses its default model
+unless you supply a model ID. Targets can be inspected without credentials or an
+installed provider. `/switch` shows the same report before changing the active agent.
+
+The report includes:
+
+- Exact counts of transferred user/assistant text messages and excluded stored records.
+- A count of observed transient tool results that are not in portable history. New
+  sessions track from creation; older saved sessions explicitly report partial coverage.
+- Capability gains and losses using the local model catalog.
+- Approximate request size including tool schemas, with up to 4,096 tokens reserved
+  for an answer in the advisory calculation. This does not change generation settings.
+- SHA-256 of canonical system-prompt and conversational-text JSON. It stays the same
+  across targets when that text is unchanged. Tool schemas and attribution metadata
+  are intentionally outside this text fingerprint.
+
+The preview makes no model requests, saves no transcript exports, executes no tools,
+and does not trim or summarize history. Token sizing uses UTF-8 bytes divided by four
+plus per-message overhead, not a provider tokenizer. Catalog limits can be stale;
+an apparently fitting request can still fail. Warnings are advisory, not switch gates.
+Hidden reasoning and provider-native state do not transfer. The digest proves neither
+delivery nor semantic understanding, and is not a signature or privacy guarantee.
+
+See [research and prior art](docs/handoff-research.md) for the differentiation rationale.
+
 ## Supported Companies and Agents
 
 | Company | Agent | Capabilities |

thwip_cli-1.2.0/docs/handoff-research.md

@@ -0,0 +1,50 @@
+# Handoff preview: research and scope
+
+Research date: 2026-09-04. This is a bounded public-source comparison, not a patent
+search or proof of worldwide novelty. Search indexes miss unpublished work, private
+products, and features documented under different names. No "world first" claim is made.
+
+## What already exists
+
+| Primary source | Existing approach | Implication for Thwip |
+| --- | --- | --- |
+| [Aider chat modes](https://aider.chat/docs/usage/modes.html) | Architect and editor model pairing | Multi-model collaboration alone is not novel. |
+| [Aider model warnings](https://aider.chat/docs/llms/warnings.html) and [token limits](https://aider.chat/docs/troubleshooting/token-limits.html) | Metadata warnings, token accounting, and overflow guidance | Model-fit diagnostics alone are not novel. |
+| [OpenCode compaction](https://opencode.ai/v2/docs/compaction) | Structured checkpoints plus recent context; durable messages retained separately | Summaries and checkpoints alone are not novel. |
+| [OpenRouter fallbacks](https://openrouter.ai/docs/guides/routing/model-fallbacks) | Ordered fallback models on request failures | Routing and failover alone are not novel. |
+| [OpenRouter message transforms](https://openrouter.ai/docs/guides/features/message-transforms) | Context compression by removing or truncating messages | Automatic fitting can trade away recall. |
+| [Agent Handoff](https://github.com/AniruddhaHumane/handoff) | Portable file-backed resume briefs across agents | Cross-agent memory alone is not novel. |
+| [rosehgal/handoff](https://github.com/rosehgal/handoff) | Append-only action log and rendered handoff document | Tool-action tracking and durable handoffs already exist. |
+
+Searches included combinations of "coding agent", "model switch", "handoff",
+"context loss report", "preflight", "capability loss", "fingerprint", and "receipt",
+as well as product-specific documentation queries. Sources were inspected through
+web search retrieval. No restricted pages or private data were scraped.
+
+## Chosen differentiation
+
+Thwip already owns the provider switch boundary. Put a local continuity report at
+that boundary: exact text-message coverage, explicit state omissions, capability
+differences, advisory context pressure, and a deterministic text fingerprint together.
+The examined sources establish prior art for the components; they did not establish
+the same integrated report. That is an opportunity hypothesis, not proof of uniqueness.
+
+## Implementation boundaries
+
+- `/handoff [provider] [model]` is a non-mutating dry run. `/switch` displays it too.
+- No new dependencies, model calls, summarization costs, or external data storage.
+- Only a result count is added to saved sessions, not raw tool inputs or outputs.
+- Legacy sessions explicitly show incomplete tool-result tracking.
+- SHA-256 covers canonical system prompt and portable text, not provider wire formats,
+  delivery, hidden reasoning, tool schemas, project file contents, or model comprehension.
+- Context estimates are heuristic and warnings advisory. Provider-native tool
+  continuation correctness remains a separate issue, not solved by this report.
+- Production deployment and other defects from the previous audit remain separate work.
+
+## Validation
+
+Offline tests cover stable/change-sensitive fingerprints, exclusions, capability
+gains/losses, context thresholds and unknown limits, unknown targets, private session
+persistence, legacy migration, clear commands, dry-run non-mutation, safe terminal
+rendering, switch integration, and command completion. Live generation is not needed
+to validate this diagnostic, and no claim about live provider success follows from it.

{thwip_cli-1.1.3 → thwip_cli-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thwip-cli"
-version = "1.1.3"
+version = "1.2.0"
 description = "Universal coding agent multiplexer: detect, switch, and route between AI coding agents seamlessly"
 readme = "README.md"
 license = "MIT"

{thwip_cli-1.1.3 → thwip_cli-1.2.0}/tests/test_cli.py

@@ -67,6 +67,7 @@ async def test_tool_results_are_returned_to_agent(tmp_path):
 
     assert len(cli.current_agent.calls) == 2
     assert cli.session.messages[-1].content == "Used the tool result."
+    assert cli.session.observed_tool_results == 1
 
 
 class UnconfiguredAgent(ToolCallingAgent):

thwip_cli-1.2.0/tests/test_handoff.py

@@ -0,0 +1,222 @@
+"""Offline regression coverage for auditable text handoffs."""
+
+import importlib
+import json
+from copy import deepcopy
+from io import StringIO
+from types import SimpleNamespace
+
+import pytest
+from prompt_toolkit.document import Document
+from rich.console import Console
+
+from thwip.agents.base import Capability, ModelInfo
+from thwip.cli import ThwipCLI
+from thwip.handoff import build_handoff_report
+from thwip.session import Message, Session
+from thwip.shortcuts import ThwipCompleter
+from thwip.tools import ToolManager
+
+
+class OfflineAgent:
+    name = "offline"
+    company = "Test"
+    display_name = "Offline Agent"
+    capabilities = {Capability.CHAT, Capability.FILE_EDIT}
+
+    def __init__(self, window=100_000, tools=True):
+        self.model = ModelInfo(id="test-model", name="Test", context_window=window,
+                               max_output=4096, supports_tools=tools)
+        self.available_models = [self.model]
+
+    def get_model_info(self, model):
+        return self.model if model == self.model.id else None
+
+    def get_default_model(self):
+        return self.model.id
+
+    def get_handoff_models(self):
+        return self.available_models
+
+    def get_capabilities_for_model(self, model):
+        return {Capability.CHAT, Capability.FILE_EDIT} if self.model.supports_tools else {Capability.CHAT}
+
+    def is_installed(self):
+        return True
+
+    def is_configured(self):
+        return False
+
+
+def test_fingerprint_is_stable_and_does_not_mutate_session():
+    session = Session(current_model="test-model")
+    session.add_user_message("Keep Unicode: नमस्ते")
+    session.add_assistant_message("Understood", "offline", "test-model")
+    before = deepcopy(session)
+    agent = OfflineAgent()
+    first = build_handoff_report(session, agent, agent, "test-model")
+    second = build_handoff_report(session, agent, agent, "test-model", [{"name": "read"}])
+    assert first.text_fingerprint == second.text_fingerprint
+    assert second.estimated_input_tokens > first.estimated_input_tokens
+    assert session == before
+    assert first.transferred_messages == 2
+    session.system_prompt += "Changed instruction"
+    assert build_handoff_report(session, agent, agent, "test-model").text_fingerprint != first.text_fingerprint
+
+
+@pytest.mark.parametrize("change", ["text", "order"])
+def test_fingerprint_changes_with_payload(change):
+    session = Session()
+    session.add_user_message("one")
+    session.add_user_message("two")
+    agent = OfflineAgent()
+    initial = build_handoff_report(session, agent, agent, "test-model")
+    if change == "text":
+        session.messages[0].content = "different"
+    else:
+        session.messages.reverse()
+    assert build_handoff_report(session, agent, agent, "test-model").text_fingerprint != initial.text_fingerprint
+
+
+def test_exclusions_and_capability_changes_are_explicit():
+    session = Session(current_model="test-model")
+    session.messages = [Message(role="assistant", content="text", tool_calls=[{"id": "one"}]),
+                        Message(role="tool", content="private result")]
+    session.record_tool_result()
+    source, target = OfflineAgent(), OfflineAgent(tools=False)
+    report = build_handoff_report(session, source, target, "test-model")
+    assert report.transferred_messages == 1
+    assert report.excluded_messages == report.excluded_tool_calls == report.observed_tool_results == 1
+    assert report.lost_capabilities == (Capability.FILE_EDIT.display_name,)
+    assert report.gained_capabilities == ()
+    reverse = build_handoff_report(session, target, source, "test-model")
+    assert reverse.gained_capabilities == report.lost_capabilities
+    assert "private result" not in repr(report)
+
+
+@pytest.mark.parametrize("window,expected", [(0, "unknown"), (100, "likely over budget"),
+                                             (5000, "near limit"), (100000, "below advisory budget")])
+def test_advisory_pressure(window, expected):
+    agent = OfflineAgent(window=window)
+    report = build_handoff_report(Session(), agent, agent, "test-model")
+    assert report.context_pressure == expected
+
+
+def test_unknown_model_is_not_silently_assumed():
+    with pytest.raises(ValueError, match="Unknown model"):
+        build_handoff_report(Session(), OfflineAgent(), OfflineAgent(), "missing")
+
+
+def test_tracking_survives_save_and_legacy_load(tmp_path, monkeypatch):
+    monkeypatch.setenv("THWIP_CONFIG_DIR", str(tmp_path))
+    session = Session(name="tracking")
+    session.record_tool_result()
+    path = session.save()
+    loaded = Session.load("tracking")
+    assert loaded.observed_tool_results == 1
+    assert loaded.tool_tracking_complete
+    assert path.stat().st_mode & 0o777 == 0o600
+    data = json.loads(path.read_text())
+    del data["observed_tool_results"]
+    del data["tool_tracking_complete"]
+    path.write_text(json.dumps(data))
+    legacy = Session.load("tracking")
+    assert not legacy.tool_tracking_complete
+    legacy.record_tool_result()
+    assert legacy.observed_tool_results == 1
+    legacy.clear_context()
+    assert legacy.observed_tool_results == 0
+    assert legacy.tool_tracking_complete
+
+
+@pytest.mark.asyncio
+async def test_cli_preview_is_offline_non_mutating_and_safe_to_render(tmp_path, monkeypatch):
+    agent = OfflineAgent()
+    agent.name = "[red]offline[/red]"
+    cli = ThwipCLI.__new__(ThwipCLI)
+    cli.current_agent = agent
+    cli.registry = SimpleNamespace(get_agent=lambda name: agent if name == "offline" else None)
+    cli.session = Session(current_model="test-model")
+    cli.session.add_user_message("PRIVATE USER TEXT")
+    cli.tool_manager = ToolManager(tmp_path)
+    buffer = StringIO()
+    monkeypatch.setattr("thwip.cli.console", Console(file=buffer, width=140, color_system=None))
+    before = deepcopy(cli.session)
+    await cli.handle_command("/handoff offline test-model")
+    assert cli.session == before
+    assert "PRIVATE USER TEXT" not in buffer.getvalue()
+    assert "[red]offline[/red]" in buffer.getvalue()
+    assert "No model calls" in " ".join(buffer.getvalue().split())
+
+
+@pytest.mark.asyncio
+async def test_switch_previews_before_mutating(tmp_path, monkeypatch):
+    source, target = OfflineAgent(), OfflineAgent(tools=False)
+    cli = ThwipCLI.__new__(ThwipCLI)
+    cli.current_agent = source
+    cli.registry = SimpleNamespace(get_agent=lambda name: target)
+    cli.session = Session(current_model="test-model")
+    cli.tool_manager = ToolManager(tmp_path)
+    calls = []
+
+    def preview(*args):
+        assert cli.current_agent is source
+        calls.append(args)
+
+    monkeypatch.setattr(cli, "cmd_handoff", preview)
+    await cli.cmd_switch("offline", "test-model")
+    assert calls == [("offline", "test-model")]
+    assert cli.current_agent is target
+
+
+@pytest.mark.parametrize("command", ["/clear", "/session clear"])
+@pytest.mark.asyncio
+async def test_clear_commands_reset_tracking(command):
+    cli = ThwipCLI.__new__(ThwipCLI)
+    cli.session = Session(observed_tool_results=2, tool_tracking_complete=False)
+    await cli.handle_command(command)
+    assert cli.session.observed_tool_results == 0
+    assert cli.session.tool_tracking_complete
+
+
+def test_handoff_completion():
+    matches = list(ThwipCompleter(["claude"]).get_completions(Document("/handoff cl"), None))
+    assert [match.text for match in matches] == ["/handoff claude"]
+
+
+def test_ollama_preview_never_discovers_models_over_network(monkeypatch):
+    from thwip.agents.ollama_agent import OllamaAgent
+
+    def forbidden(*args, **kwargs):
+        pytest.fail("Preview must not access the network")
+
+    monkeypatch.setattr("urllib.request.urlopen", forbidden)
+    agent = OllamaAgent(host="https://example.invalid")
+    session = Session(current_agent="ollama", current_model="llama3.3")
+    report = build_handoff_report(session, agent, agent, "llama3.3")
+    assert report.context_pressure == "unknown"
+    assert agent._cached_models is None
+
+
+@pytest.mark.parametrize("module,class_name", [
+    ("claude", "ClaudeAgent"), ("google", "GoogleAgent"), ("openai", "OpenAIAgent"),
+    ("deepseek", "DeepSeekAgent"), ("groq", "GroqAgent"), ("ollama", "OllamaAgent"),
+    ("openrouter", "OpenRouterAgent"),
+])
+def test_every_adapter_supports_offline_catalog_reports(module, class_name, monkeypatch):
+    def forbidden(*args, **kwargs):
+        pytest.fail("Handoff must not discover providers or generate responses")
+
+    adapter = getattr(importlib.import_module(f"thwip.agents.{module}_agent"), class_name)
+    agent = adapter.__new__(adapter)
+    if module == "ollama":
+        agent._cached_models = None
+    monkeypatch.setattr(agent, "chat", forbidden)
+    monkeypatch.setattr(agent, "is_installed", forbidden)
+    monkeypatch.setattr(agent, "is_configured", forbidden)
+    monkeypatch.setattr("urllib.request.urlopen", forbidden)
+    model = agent.get_handoff_models()[0]
+    session = Session(current_agent=agent.name, current_model=model.id)
+    report = build_handoff_report(session, agent, agent, model.id)
+    assert report.lost_capabilities == report.gained_capabilities == ()
+    assert len(report.text_fingerprint) == 64

{thwip_cli-1.1.3 → thwip_cli-1.2.0}/thwip/__init__.py

@@ -1,4 +1,4 @@
 """thwip: Universal Coding Agent Multiplexer."""
 
-__version__ = "1.1.3"
+__version__ = "1.2.0"
 __app_name__ = "thwip"

{thwip_cli-1.1.3 → thwip_cli-1.2.0}/thwip/agents/base.py

@@ -298,6 +298,10 @@ class BaseAgent(ABC):
                 return m
         return None
 
+    def get_handoff_models(self) -> list[ModelInfo]:
+        """Return local catalog metadata without requesting provider discovery."""
+        return list(self.available_models)
+
     def has_capability(self, cap: Capability) -> bool:
         """Check if this agent supports a capability."""
         return cap in self.capabilities

{thwip_cli-1.1.3 → thwip_cli-1.2.0}/thwip/agents/ollama_agent.py

@@ -98,6 +98,17 @@ class OllamaAgent(BaseAgent):
     def is_installed(self) -> bool:
         return shutil.which("ollama") is not None or self._is_server_reachable()
 
+    def get_handoff_models(self) -> list[ModelInfo]:
+        """Never query even a remote configured Ollama host during a preview."""
+        if self._cached_models is not None:
+            return list(self._cached_models)
+        return [
+            ModelInfo(id="llama3.3", name="Llama 3.3", is_default=True),
+            ModelInfo(id="qwen2.5-coder", name="Qwen 2.5 Coder"),
+            ModelInfo(id="deepseek-r1", name="DeepSeek R1 Distill"),
+            ModelInfo(id="codellama", name="CodeLlama"),
+        ]
+
     def _is_server_reachable(self) -> bool:
         try:
             req = urllib.request.Request(f"{self.host}/api/tags")

{thwip_cli-1.1.3 → thwip_cli-1.2.0}/thwip/cli.py

@@ -38,6 +38,7 @@ from thwip.agents.base import (
 )
 from thwip.config import ThwipConfig, get_config_dir
 from thwip.detector import SystemDetector
+from thwip.handoff import build_handoff_report, local_capabilities, local_model
 from thwip.limits import UsageTracker
 from thwip.session import Session
 from thwip.shortcuts import ThwipCompleter, create_keybindings
@@ -210,6 +211,9 @@ class ThwipCLI:
         elif cmd in ("/switch", "/s"):
             await self.cmd_switch(arg1, arg2)
 
+        elif cmd == "/handoff":
+            self.cmd_handoff(arg1, arg2)
+
         elif cmd in ("/agents", "/list", "/a"):
             self.cmd_show_agents()
 
@@ -235,7 +239,7 @@ class ThwipCLI:
             self.cmd_show_history()
 
         elif cmd in ("/clear", "/reset"):
-            self.session.messages.clear()
+            self.session.clear_context()
             print_info("Conversation history cleared.")
 
         elif cmd == "/cost":
@@ -272,7 +276,7 @@ class ThwipCLI:
             elif sub == "list":
                 self.cmd_list_sessions()
             elif sub == "clear":
-                self.session.messages.clear()
+                self.session.clear_context()
                 print_info("Conversation history cleared.")
             else:
                 print_info("Usage: /session [save|load|list|clear] [name]")
@@ -326,7 +330,8 @@ class ThwipCLI:
 
         commands = [
             ("/about", "Display full About section, architecture, and navigation guide"),
-            ("/switch [agent] [model]", "Switch active agent/model mid-conversation without losing context"),
+            ("/switch [agent] [model]", "Switch provider with a text-continuity report"),
+            ("/handoff [agent] [model]", "Preview transfer losses and context pressure without switching"),
             ("/agents", "Show all detected coding agents, company status & capabilities"),
             ("/models [agent|tier]", "List models filtered by provider or tier (flagship, balanced, fast)"),
             ("/key [provider]", "Securely enter an API key without storing it in terminal history"),
@@ -350,6 +355,54 @@ class ThwipCLI:
             table.add_row(c, d)
         console.print(table)
 
+    def cmd_handoff(self, agent_name: str = "", model_id: str = "") -> None:
+        """Preview any catalogued target without requiring credentials or API calls."""
+        target = self.registry.get_agent(agent_name) if agent_name else self.current_agent
+        if target is None:
+            print_error(f"Unknown agent '{agent_name}'.")
+            return
+        models = target.get_handoff_models()
+        default = next((model.id for model in models if model.is_default), models[0].id if models else "")
+        chosen = model_id or (self.session.current_model if not agent_name else default)
+        if local_model(target, chosen) is None:
+            print_error(f"Unknown model '{chosen}' for {target.display_name}.")
+            return
+        caps = local_capabilities(target, chosen)
+        tools = None
+        if Capability.FILE_EDIT in caps:
+            tools = (
+                self.tool_manager.get_anthropic_tools() if target.name == "claude"
+                else self.tool_manager.get_openai_tools()
+            )
+        report = build_handoff_report(self.session, self.current_agent, target, chosen, tools)
+        table = Table(title="Handoff Preview (local only)", box=box.ROUNDED)
+        table.add_column("Check", style="cyan")
+        table.add_column("Result")
+        rows = [
+            ("Route", f"{report.source} -> {report.target}"),
+            ("Preserved", f"{report.transferred_messages} user/assistant text messages + system prompt"),
+            ("Excluded records", (f"{report.excluded_messages} non-text-history messages; "
+             f"{report.excluded_tool_calls} stored tool-call entries")),
+            ("Transient results", f"{report.observed_tool_results} observed tool results not transferred"),
+            ("Tracking coverage", "Since session creation" if report.tracking_complete
+             else "Partial: legacy session has uncounted earlier tool results"),
+            ("Capabilities lost", ", ".join(report.lost_capabilities) or "None in local catalog"),
+            ("Capabilities gained", ", ".join(report.gained_capabilities) or "None in local catalog"),
+            ("Context pressure", (f"{report.context_pressure}: ~{report.estimated_input_tokens:,} input "
+             f"+ {report.output_reserve:,} advisory output reserve / "
+             f"{report.context_window or 'unknown'} catalog tokens")),
+            ("Text SHA-256", report.text_fingerprint),
+        ]
+        for label, value in rows:
+            table.add_row(Text(label), Text(value))
+        console.print(table)
+        console.print(Text(
+            "Advisory only: token estimates and catalog limits can differ from provider behavior. "
+            "Hidden reasoning and provider-native state do not transfer. Working files stay on disk; "
+            "they are not uploaded by this preview. The fingerprint checks text equality, not delivery. "
+            "No model calls, trimming, or switching were performed by the preview.", style="dim",
+        ))
+
     async def cmd_switch(self, agent_name: str, model_id: str = "") -> None:
         """Switch to a different agent and/or model."""
         if not agent_name:
@@ -408,6 +461,8 @@ class ThwipCLI:
         old_agent = self.current_agent
         old_caps = old_agent.get_capabilities_for_model(self.session.current_model)
 
+        self.cmd_handoff(new_agent.name, chosen_model)
+
         self.current_agent = new_agent
         self.session.switch_agent(new_agent.name, chosen_model)
 
@@ -867,6 +922,7 @@ class ThwipCLI:
                     if approved
                     else "Denied by user."
                 )
+                self.session.record_tool_result()
                 result_preview = Text("  Result: ", style="green")
                 result_preview.append(output[:500], style="dim")
                 console.print(result_preview)

thwip_cli-1.2.0/thwip/handoff.py

@@ -0,0 +1,91 @@
+"""Local, non-mutating diagnostics for provider-neutral conversation transfers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from dataclasses import dataclass
+from typing import Any
+
+from thwip.agents.base import BaseAgent, Capability, ModelInfo
+from thwip.session import Session
+
+
+@dataclass(frozen=True)
+class HandoffReport:
+    source: str
+    target: str
+    text_fingerprint: str
+    transferred_messages: int
+    excluded_messages: int
+    excluded_tool_calls: int
+    observed_tool_results: int
+    tracking_complete: bool
+    lost_capabilities: tuple[str, ...]
+    gained_capabilities: tuple[str, ...]
+    estimated_input_tokens: int
+    context_window: int
+    output_reserve: int
+
+    @property
+    def context_pressure(self) -> str:
+        if self.context_window <= 0:
+            return "unknown"
+        fraction = (self.estimated_input_tokens + self.output_reserve) / self.context_window
+        if fraction > 1:
+            return "likely over budget"
+        if fraction >= 0.8:
+            return "near limit"
+        return "below advisory budget"
+
+
+def local_model(agent: BaseAgent, model_id: str) -> ModelInfo | None:
+    return next((model for model in agent.get_handoff_models() if model.id == model_id), None)
+
+
+def local_capabilities(agent: BaseAgent, model_id: str) -> set[Capability]:
+    model = local_model(agent, model_id)
+    if model and not model.supports_tools:
+        return {Capability.CHAT}
+    return set(agent.capabilities)
+
+
+def build_handoff_report(
+    session: Session,
+    source: BaseAgent,
+    target: BaseAgent,
+    model_id: str,
+    tools: list[dict[str, Any]] | None = None,
+) -> HandoffReport:
+    """Fingerprint text only; estimate request size without contacting a provider.
+
+    The digest is an equality check, not a signature, confidentiality mechanism,
+    or proof that the target provider received or understood the context.
+    """
+    model = local_model(target, model_id)
+    if model is None:
+        raise ValueError(f"Unknown model '{model_id}' for {target.name}.")
+    portable = session.to_portable_messages()
+    text = {"system_prompt": session.system_prompt, "messages": portable}
+    canonical = json.dumps(text, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    request = json.dumps({**text, "tools": tools or []}, ensure_ascii=False)
+    # This heuristic is advisory, especially for code and non-Latin languages.
+    estimate = math.ceil(len(request.encode("utf-8")) / 4) + 8 * len(portable)
+    old = local_capabilities(source, session.current_model)
+    new = local_capabilities(target, model_id)
+    return HandoffReport(
+        source=f"{source.name}/{session.current_model}",
+        target=f"{target.name}/{model_id}",
+        text_fingerprint=hashlib.sha256(canonical.encode("utf-8")).hexdigest(),
+        transferred_messages=len(portable),
+        excluded_messages=len(session.messages) - len(portable),
+        excluded_tool_calls=sum(len(message.tool_calls) for message in session.messages),
+        observed_tool_results=session.observed_tool_results,
+        tracking_complete=session.tool_tracking_complete,
+        lost_capabilities=tuple(sorted(cap.display_name for cap in old - new)),
+        gained_capabilities=tuple(sorted(cap.display_name for cap in new - old)),
+        estimated_input_tokens=estimate,
+        context_window=model.context_window,
+        output_reserve=min(4096, model.max_output) if model.max_output > 0 else 4096,
+    )

{thwip_cli-1.1.3 → thwip_cli-1.2.0}/thwip/session.py

@@ -1,7 +1,7 @@
 """
 Session & conversation state manager for thwip.
 
-Enables seamless context portability across agent switches without losing history.
+Preserves conversational text across provider switches, not native reasoning state.
 """
 
 from __future__ import annotations
@@ -63,6 +63,20 @@ class Session:
     created_at: float = field(default_factory=time.time)
     updated_at: float = field(default_factory=time.time)
     messages: list[Message] = field(default_factory=list)
+    observed_tool_results: int = 0
+    tool_tracking_complete: bool = True
+
+    def clear_context(self) -> None:
+        """Clear text and its associated handoff accounting together."""
+        self.messages.clear()
+        self.observed_tool_results = 0
+        self.tool_tracking_complete = True
+        self.updated_at = time.time()
+
+    def record_tool_result(self) -> None:
+        """Count transient results without persisting potentially sensitive outputs."""
+        self.observed_tool_results += 1
+        self.updated_at = time.time()
 
     def add_user_message(self, content: str) -> Message:
         msg = Message(role="user", content=content)
@@ -102,7 +116,7 @@ class Session:
         return portable
 
     def switch_agent(self, agent_name: str, model: str) -> None:
-        """Switch current agent and model while preserving full history."""
+        """Switch current agent and model while preserving stored text history."""
         self.current_agent = agent_name
         self.current_model = model
         self.updated_at = time.time()
@@ -128,6 +142,8 @@ class Session:
             "created_at": self.created_at,
             "updated_at": self.updated_at,
             "messages": [m.to_dict() for m in self.messages],
+            "observed_tool_results": self.observed_tool_results,
+            "tool_tracking_complete": self.tool_tracking_complete,
         }
         temporary_path: Path | None = None
         try:
@@ -180,6 +196,8 @@ class Session:
                 created_at=data.get("created_at", time.time()),
                 updated_at=data.get("updated_at", time.time()),
                 messages=[Message.from_dict(m) for m in data.get("messages", [])],
+                observed_tool_results=data.get("observed_tool_results", 0),
+                tool_tracking_complete=data.get("tool_tracking_complete", False),
             )
             return session
         except Exception:

{thwip_cli-1.1.3 → thwip_cli-1.2.0}/thwip/shortcuts.py

@@ -9,6 +9,7 @@ from prompt_toolkit.key_binding import KeyBindings
 
 SLASH_COMMANDS = [
     ("/switch", "Switch agent and model mid-conversation"),
+    ("/handoff", "Preview context transfer, losses, and model fit locally"),
     ("/agents", "Show all detected coding agents & status"),
     ("/models", "List available models for current agent"),
     ("/status", "Display current session and agent info"),
@@ -41,12 +42,12 @@ class ThwipCompleter(Completer):
                     yield Completion(cmd, start_position=-len(text), display_meta=desc)
 
             # /switch <agent> autocompletion
-            if text.startswith("/switch "):
+            if text.startswith(("/switch ", "/handoff ")):
                 parts = text.split(" ")
                 prefix = parts[1] if len(parts) > 1 else ""
                 for name in self.agent_names:
                     if name.startswith(prefix):
-                        yield Completion(f"/switch {name}", start_position=-len(text), display_meta="Agent")
+                        yield Completion(f"{parts[0]} {name}", start_position=-len(text), display_meta="Agent")
 
 
 def create_keybindings(on_switch=None, on_status=None, on_history=None) -> KeyBindings:

{thwip_cli-1.1.3 → thwip_cli-1.2.0}/thwip/theme.py

@@ -198,7 +198,7 @@ def render_about_guide(
     content.append("HOW IT WORKS\n", style="bold cyan")
     content.append("  1. Auto-Detection:   Scans environment variables, local CLI agents, and existing credentials\n", style="dim")
     content.append("                       in ~/.claude.json, ~/.gemini/config.json, ~/.config/openai/, or Ollama.\n", style="dim")
-    content.append("  2. Unified State:    Maintains conversation history and tool outputs in a portable format.\n", style="dim")
+    content.append("  2. Unified State:    Preserves text history; /handoff previews excluded state and model fit.\n", style="dim")
     content.append("  3. Hot-Swapping:     Switch models with completed text history preserved.\n", style="dim")
     content.append("  4. Universal Tools:  Provides safe file editing, shell commands, execution, and git operations.\n", style="dim")
     content.append("  5. Quota Failover:   Catches HTTP 429 errors and offers immediate one-key fallback switching.\n\n", style="dim")

{thwip_cli-1.1.3 → thwip_cli-1.2.0}/uv.lock

@@ -1022,7 +1022,7 @@ wheels = [
 
 [[package]]
 name = "thwip-cli"
-version = "1.1.3"
+version = "1.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "anthropic" },