anolisa-tokenless 0.7.14 → 0.8.1

package/adapters/tokenless/hermes/__init__.py

@@ -1,30 +1,11 @@
-"""Token-Less Plugin for Hermes Agent.
-
-Combines multiple context-compression strategies into a single plugin:
-
-  1. **Response compression** — ``transform_tool_result`` : compresses tool
-     results via ``tokenless compress-response`` with per-layer thresholds
-     (moderate for shell, zero-truncation for API tools), stripping debug
-     fields, nulls, empty values.
-  2. **TOON encoding** — ``transform_tool_result`` : pipeline step after
-     response compression; re-encodes JSON results to TOON format via
-     ``tokenless compress-toon`` for additional token savings (15-40%)
-     with proper stats recording and size check.
-  3. **Tool Ready** — ``pre_tool_call`` : environment readiness pre-check
-     with auto-fix and skip-retry feedback for missing dependencies.
-  4. **Command rewriting** — ``pre_tool_call`` : blocks shell commands
-     and suggests RTK-rewritten equivalents.  Hermes's hook cannot modify
-     arguments, so the agent must re-execute with the suggested command
-     (one extra round-trip).  Safe: ``rtk rewrite`` only does text
-     substitution, never executes the command.
-  5. **Session tracking** — ``on_session_start`` : propagates agent/session
-     IDs to tokenless stats recording.
-
-Not available in Hermes: schema compression (Hermes hooks do not expose
-tool schemas).
-
-Every hook degrades gracefully: if ``tokenless`` is not installed, all
-hooks are silently skipped.
+"""Tokenless lifecycle adapter for Hermes Agent.
+
+Hermes cannot replace tool arguments on older supported releases, so PreTool
+blocks a shell call and suggests the Core-rewritten command. PostTool sends the
+final model-bound result to Core and applies only the returned disposition.
+Schema compression is not available from the Hermes hook surface. Marker-directed
+recovery uses Hermes's existing shell tool and the trusted local Tokenless CLI.
+Tool Ready remains product-wide hard-disabled.
 
 Activation is controlled by the Hermes plugin system — list ``tokenless`` in
 ``plugins.enabled`` in ``config.yaml``, or enable via
@@ -33,10 +14,11 @@ Activation is controlled by the Hermes plugin system — list ``tokenless`` in
 
 from __future__ import annotations
 
+import inspect
 import json
 import logging
 import os
-import subprocess
+import shlex
 import sys
 from typing import Any
 
@@ -95,18 +77,153 @@ def _validate_hooks_dir(path: str) -> str | None:
     return None
 
 
+# Symbols that must exist in the shared hook_utils module, paired with the
+# exact call shape this adapter uses at its hook entry points.  When a
+# candidate passes the trust check but ships an older hook_utils.py (e.g. a
+# stale install from a previous adapter version), the candidate is rejected and
+# the search continues to later paths.  The lifecycle migration made the Hermes
+# adapter a thin Core client, so the required symbols are the Protocol v2
+# request builders, the compress runner, and the Retrieve helpers this module
+# from-imports at load time.  The remaining load-time imports (resolve_binary,
+# SHELL_TOOLS, SKIP_TOOLS, and the local-path constants) predate Protocol v2,
+# so every module that ships the v2 API also ships them.  A module missing any
+# listed symbol would pass a narrower check and then raise ImportError at the
+# top-level from-import, after the candidate search has already ended — with no
+# fallback to later complete candidates.
+#
+# Symbol names alone are not enough: hook_utils has also changed *call
+# signatures* while keeping names stable.  ``build_post_tool_request`` took a
+# keyword-only ``retrieval_available`` flag until c2c7e580e replaced it with
+# the ``recovery`` mapping, so the module shipped by 9f109d559 exports all five
+# required symbols yet rejects the ``recovery=`` this adapter passes — the
+# plugin would import cleanly and every PostTool request would then die with
+# "unexpected keyword argument 'recovery'", again after the candidate search
+# has ended and with no fallback.  Each shape is therefore bound with
+# :func:`inspect.signature`; the values below are placeholders mirroring the
+# real call sites (``bind`` only checks arity and parameter names, so nothing
+# is ever called here).
+_HOOK_UTILS_CALL_SHAPES: tuple[tuple[str, tuple[Any, ...], dict[str, Any]], ...] = (
+    # on_compress_pre_tool:
+    #   build_pre_tool_request(args, AGENT_ID, tool_name, "command",
+    #                          session_id, tool_call_id,
+    #                          replace_arguments=False, block_and_suggest=True)
+    (
+        "build_pre_tool_request",
+        ({}, "", "", "", "", ""),
+        {"replace_arguments": False, "block_and_suggest": True},
+    ),
+    # on_transform_tool_result:
+    #   build_post_tool_request(content, AGENT_ID, tool_name, protocol_status,
+    #                           content_origin, output_optimization,
+    #                           result_kind=..., recovery=..., session_id=...,
+    #                           tool_use_id=..., replace_output=True,
+    #                           replace_with_text=True)
+    (
+        "build_post_tool_request",
+        ("", "", "", "", "", ""),
+        {
+            "result_kind": "tool",
+            "recovery": {"kind": "none"},
+            "session_id": "",
+            "tool_use_id": "",
+            "replace_output": True,
+            "replace_with_text": True,
+        },
+    ),
+    # Both hooks: run_compress(tokenless_bin, request, timeout, operation)
+    ("run_compress", ("", {}, 0, ""), {}),
+    # on_transform_tool_result: is_tokenless_retrieve_command(tool_name, args)
+    ("is_tokenless_retrieve_command", ("", {}), {}),
+    # on_transform_tool_result: tokenless_retrieve_command_available()
+    ("tokenless_retrieve_command_available", (), {}),
+)
+
+_HOOK_UTILS_REQUIRED_SYMBOLS = tuple(name for name, _, _ in _HOOK_UTILS_CALL_SHAPES)
+
+
+def _restore_cached_hook_utils(saved: Any) -> None:
+    """Reinstate the module cached before a trial import, or drop the trial."""
+    if saved is not None:
+        sys.modules["hook_utils"] = saved
+    else:
+        sys.modules.pop("hook_utils", None)
+
+
+def _call_shape_rejection(
+    symbol: Any, name: str, args: tuple[Any, ...], kwargs: dict[str, Any]
+) -> str | None:
+    """Return why *symbol* cannot take the adapter call shape, else ``None``."""
+    try:
+        signature = inspect.signature(symbol)
+    except (TypeError, ValueError) as exc:
+        return f"{name} is not an introspectable callable ({exc})"
+    try:
+        signature.bind(*args, **kwargs)
+    except TypeError as exc:
+        # Name the shape the adapter needs, not only what the module offers:
+        # a renamed keyword (retrieval_available -> recovery) reports as a
+        # missing argument on some Python versions, which alone would not tell
+        # the reader which side of the contract moved.
+        return (
+            f"{name}{signature} rejects the adapter call shape "
+            f"({len(args)} positional, kwargs: {', '.join(sorted(kwargs)) or 'none'}): "
+            f"{exc}"
+        )
+    return None
+
+
+def _check_api_compat(candidate_dir: str) -> str | None:
+    """Trial-import hook_utils from *candidate_dir* and verify its API.
+
+    Returns ``None`` when the module loads, exposes every symbol in
+    :data:`_HOOK_UTILS_REQUIRED_SYMBOLS`, and every one of them accepts the
+    matching call shape in :data:`_HOOK_UTILS_CALL_SHAPES`; otherwise a
+    human-readable rejection reason.  On success the freshly imported module is
+    kept in ``sys.modules`` so the subsequent ``from hook_utils import …``
+    reuses it rather than a stale cached copy.  On rejection the ``sys.path``
+    mutation is cleaned up and the previously cached module (if any) is
+    restored so later candidates start from a clean state.
+    """
+    sys.path.insert(0, candidate_dir)
+    saved = sys.modules.pop("hook_utils", None)
+    try:
+        import hook_utils as _trial  # type: ignore[import-not-found]
+        missing = [s for s in _HOOK_UTILS_REQUIRED_SYMBOLS
+                   if not hasattr(_trial, s)]
+        if missing:
+            _restore_cached_hook_utils(saved)
+            return f"API mismatch: missing {', '.join(missing)}"
+        mismatched = []
+        for name, args, kwargs in _HOOK_UTILS_CALL_SHAPES:
+            reason = _call_shape_rejection(getattr(_trial, name), name, args, kwargs)
+            if reason is not None:
+                mismatched.append(reason)
+        if mismatched:
+            _restore_cached_hook_utils(saved)
+            return "API mismatch: " + "; ".join(mismatched)
+        # Success — keep the freshly imported module in sys.modules.
+        return None
+    except Exception as exc:
+        _restore_cached_hook_utils(saved)
+        return f"import failed: {exc}"
+    finally:
+        sys.path.pop(0)
+
+
+
 def _resolve_hook_utils() -> tuple[str, list[str]]:
     """Locate a trusted shared hooks directory and make it importable.
 
     Returns ``(resolved_path, candidate_list)``.  The resolved path is
     inserted at the front of ``sys.path`` so the shared ``hook_utils``
     module can be imported.  Raises :exc:`ImportError` when no candidate
-    passes the trust policy.
+    passes both the trust policy and the API compatibility check.
     """
     # Resolve real home from passwd DB for user-install fallback path
     # (NOT $HOME — env-controllable).
     try:
         import pwd as _pwd
+
         real_home = _pwd.getpwuid(os.getuid()).pw_dir
     except (ImportError, KeyError):
         real_home = ""
@@ -114,9 +231,10 @@ def _resolve_hook_utils() -> tuple[str, list[str]]:
         real_home = ""
 
     candidates = [
-        os.path.join(_HERE, "..", "common", "hooks"),                          # source-tree / symlink install
-        "/usr/share/anolisa/adapters/tokenless/common/hooks",                  # RPM system
-        "/usr/local/share/anolisa/adapters/tokenless/common/hooks",            # manual system
+        # Source-tree / symlink install.
+        os.path.join(_HERE, "..", "common", "hooks"),
+        "/usr/share/anolisa/adapters/tokenless/common/hooks",  # RPM system
+        "/usr/local/share/anolisa/adapters/tokenless/common/hooks",  # Manual system
     ]
     # XDG user data dir first (anolisa FsLayout::user precedence), then the
     # passwd-home default. XDG_DATA_HOME is env-controllable, but candidates
@@ -124,20 +242,29 @@ def _resolve_hook_utils() -> tuple[str, list[str]]:
     xdg_data = os.environ.get("XDG_DATA_HOME", "")
     if xdg_data and os.path.isabs(xdg_data):
         candidates.append(
-            os.path.join(xdg_data, "anolisa", "adapters", "tokenless", "common", "hooks"))
+            os.path.join(xdg_data, "anolisa", "adapters", "tokenless", "common", "hooks")
+        )
     if real_home:
         candidates.append(
-            os.path.join(real_home, ".local", "share",
-                         "anolisa", "adapters", "tokenless", "common", "hooks"))
+            os.path.join(
+                real_home, ".local", "share", "anolisa", "adapters", "tokenless", "common", "hooks"
+            )
+        )
 
     rejections: list[str] = []
     for candidate in candidates:
         reason = _validate_hooks_dir(candidate)
-        if reason is None:
-            resolved = os.path.realpath(candidate)
-            sys.path.insert(0, resolved)
-            return resolved, candidates
-        rejections.append(f"  - {candidate}: {reason}")
+        if reason is not None:
+            rejections.append(f"  - {candidate}: {reason}")
+            continue
+        # Trust check passed — verify API compat (version mismatch guard).
+        resolved = os.path.realpath(candidate)
+        api_reason = _check_api_compat(resolved)
+        if api_reason is not None:
+            rejections.append(f"  - {candidate}: {api_reason}")
+            continue
+        sys.path.insert(0, resolved)
+        return resolved, candidates
 
     raise ImportError(
         "tokenless: no trusted shared hook_utils module (common/hooks/) found.\n"
@@ -153,22 +280,22 @@ def _resolve_hook_utils() -> tuple[str, list[str]]:
 _HOOK_UTILS_RESOLVED, _HOOK_UTILS_CANDIDATES = _resolve_hook_utils()
 
 from hook_utils import (
-    _TOKENLESS_FALLBACK,
-    _TOKENLESS_LOCAL_SHARE,
-    _TOKENLESS_LOCAL_LIB,
     _RTK_FALLBACK,
-    _RTK_LOCAL_SHARE,
     _RTK_LOCAL_LIB,
+    _RTK_LOCAL_SHARE,
+    _TOKENLESS_FALLBACK,
+    _TOKENLESS_LOCAL_LIB,
+    _TOKENLESS_LOCAL_SHARE,
+)
+from hook_utils import SHELL_TOOLS as _SHELL_TOOLS_SHARED
+from hook_utils import SKIP_TOOLS as _SKIP_TOOLS_SHARED
+from hook_utils import (
+    build_post_tool_request,
+    build_pre_tool_request,
+    is_tokenless_retrieve_command,
     resolve_binary,
-    warn as _warn_shared,
-    try_parse_json as _try_parse_json,
-    is_skill_file as _is_skill_file,
-    write_context as _write_context,
-    run as _run,
-    parse_version as _parse_version,
-    SKIP_TOOLS as _SKIP_TOOLS_SHARED,
-    SHELL_TOOLS as _SHELL_TOOLS_SHARED,
-    get_thresholds,
+    run_compress,
+    tokenless_retrieve_command_available,
 )
 
 logger = logging.getLogger(__name__)
@@ -178,26 +305,17 @@ logger = logging.getLogger(__name__)
 # ---------------------------------------------------------------------------
 
 AGENT_ID = "hermes-agent"
-_MIN_RESPONSE_LEN = 200
-
-# Minimum payload size for the TOON encoding step. TOON on small JSON
-# saves only a few characters (observed ~0.3% below ~500 chars) while
-# the per-event encode cost stays the same, so payloads under this
-# threshold keep the response-compressed form and skip TOON entirely.
-# Mirrors tokenless-runtime's MIN_TOON_CHARS, the default the
-# compress-toon CLI applies; keep the two values in sync.
-_MIN_TOON_CHARS = 500
+_COMPRESS_TIMEOUT_SECONDS = 8
 
 _SKIP_TOOLS: set[str] = _SKIP_TOOLS_SHARED | {
-    "session_search", "list_sessions",
+    "session_search",
+    "list_sessions",
 }
 
 # Use shared SHELL_TOOLS directly - all tools (including "terminal") are now
 # defined in the unified tool_categories.json
 _SHELL_TOOLS: set[str] = _SHELL_TOOLS_SHARED
 
-_MIN_RTK_VERSION = (0, 35, 0)
-
 # ---------------------------------------------------------------------------
 # Binary resolution (thin wrapper over shared cached resolve_binary)
 # ---------------------------------------------------------------------------
@@ -210,7 +328,14 @@ def _resolve_binary(name: str, fallback: str) -> str | None:
     """Resolve binary with hermes-specific fallback paths (cached via shared)."""
     local_bin = os.path.join(os.path.expanduser("~"), ".local", "bin", name)
     if name == "rtk":
-        return resolve_binary(name, fallback, _RTK_LIB_FALLBACK, local_bin, _RTK_LOCAL_LIB, _RTK_LOCAL_SHARE)
+        return resolve_binary(
+            name,
+            fallback,
+            _RTK_LIB_FALLBACK,
+            local_bin,
+            _RTK_LOCAL_LIB,
+            _RTK_LOCAL_SHARE,
+        )
     return resolve_binary(name, fallback, local_bin, _TOKENLESS_LOCAL_LIB, _TOKENLESS_LOCAL_SHARE)
 
 
@@ -218,211 +343,60 @@ def _have(name: str, fallback: str) -> bool:
     return _resolve_binary(name, fallback) is not None
 
 
-# ---------------------------------------------------------------------------
-# Helpers (shared via hook_utils)
-# ---------------------------------------------------------------------------
-
-
-# ---------------------------------------------------------------------------
-# 1. Response Compression (via tokenless compress-response)
-# ---------------------------------------------------------------------------
-
-
-def _compress_response(
-    tool_name: str,
-    result: str,
-    session_id: str,
-    tool_call_id: str,
-) -> str | None:
-    tokenless_bin = _resolve_binary("tokenless", _TOKENLESS_FALLBACK)
-    if not tokenless_bin:
-        return None
-
-    parsed = _try_parse_json(result)
-    if not isinstance(parsed, (dict, list)):
-        return None
-
-    # 3-layer dispatch: shell tools use moderate truncation, API tools use zero-truncation
-    thresholds = get_thresholds(tool_name)
-
-    cmd = [
-        tokenless_bin, "compress-response",
-        "--agent-id", AGENT_ID,
-        "--truncate-strings-at", str(thresholds[0]),
-        "--truncate-arrays-at", str(thresholds[1]),
-        "--max-depth", str(thresholds[2]),
-    ]
-    if session_id:
-        cmd.extend(["--session-id", session_id])
-    if tool_call_id:
-        cmd.extend(["--tool-use-id", tool_call_id])
-
-    proc = _run(cmd, result)
-    if not proc or proc.returncode != 0 or not proc.stdout.strip():
-        return None
-
-    compressed = proc.stdout.strip()
-    if len(compressed) >= len(result):
-        return None
-    return compressed
-
-
-# ---------------------------------------------------------------------------
-# 2. TOON Encoding (via tokenless compress-toon)
-# ---------------------------------------------------------------------------
-
-
-def _encode_toon(data: str, session_id: str = "", tool_call_id: str = "") -> tuple[str, int] | None:
-    tokenless_bin = _resolve_binary("tokenless", _TOKENLESS_FALLBACK)
-    if not tokenless_bin:
-        return None
-
-    parsed = _try_parse_json(data)
-    if not isinstance(parsed, (dict, list)):
-        return None
-
-    cmd = [tokenless_bin, "compress-toon", "--agent-id", AGENT_ID]
-    if session_id:
-        cmd.extend(["--session-id", session_id])
-    if tool_call_id:
-        cmd.extend(["--tool-use-id", tool_call_id])
-
-    proc = _run(cmd, data, timeout=1)
-    if not proc or proc.returncode != 0 or not proc.stdout.strip():
-        return None
-
-    toon_text = proc.stdout.strip()
-    if len(toon_text) >= len(data):
-        return None
-
-    savings_pct = 0
-    if len(data) > 0:
-        savings_pct = (len(data) - len(toon_text)) * 100 // len(data)
-
-    return toon_text, savings_pct
-
-
-# ---------------------------------------------------------------------------
-# 3. Tool Ready (via tokenless env-check)
-# ---------------------------------------------------------------------------
-
-
-def _env_check(tool_name: str) -> str | None:
-    """Run tool-ready env-check and return feedback if tool is not ready."""
-    tokenless_bin = _resolve_binary("tokenless", _TOKENLESS_FALLBACK)
-    if not tokenless_bin:
-        return None
-
-    proc = _run([tokenless_bin, "env-check", "--tool", tool_name, "--json"], "", timeout=5)
-    if not proc or not proc.stdout.strip():
+def _protocol_status(status: Any, result: str) -> str | None:
+    """Map Hermes status, deriving it for hosts that omit the field."""
+    if isinstance(status, str) and status:
+        return {
+            "ok": "success",
+            "success": "success",
+            "error": "error",
+            "blocked": "denied",
+            "denied": "denied",
+            "interrupted": "interrupted",
+        }.get(status.lower())
+    if status not in (None, ""):
         return None
-
-    try:
-        parsed = json.loads(proc.stdout)
-    except json.JSONDecodeError:
-        return None
-
-    status = parsed.get("status", "UNKNOWN")
-    if status in ("UNKNOWN", "READY"):
-        return None
-
-    # Attempt auto-fix
-    proc = _run([tokenless_bin, "env-check", "--tool", tool_name, "--fix", "--json"], "", timeout=10)
-    if not proc or not proc.stdout.strip():
-        return _not_ready_msg(tool_name)
-
     try:
-        fix_parsed = json.loads(proc.stdout)
+        parsed = json.loads(result)
     except json.JSONDecodeError:
-        return _not_ready_msg(tool_name)
-
-    if fix_parsed.get("status") == "READY":
-        return None
-
-    diagnostic = fix_parsed.get("diagnostic", "")
-    return diagnostic or _not_ready_msg(tool_name)
-
-
-def _not_ready_msg(tool_name: str) -> str:
-    return f"[tokenless:ready] {tool_name}: NOT_READY. Skip retry."
+        return "success"
+    return "error" if isinstance(parsed, dict) and parsed.get("error") else "success"
 
 
-# ---------------------------------------------------------------------------
-# 4. Command Rewriting (via rtk rewrite)
-# ---------------------------------------------------------------------------
-
-
-def _try_rewrite(
-    args: Any,
-    session_id: str,
-    tool_call_id: str,
-) -> dict[str, str] | None:
-    """Attempt RTK command rewrite for terminal tool calls.
+def _content_origin(tool_name: str) -> str:
+    if tool_name in _SKIP_TOOLS:
+        return "file_content"
+    if tool_name in _SHELL_TOOLS:
+        return "command_output"
+    return "api_response"
 
-    Calls ``rtk rewrite <command>`` — a pure text substitution that never
-    executes the command.  On success, returns a block directive suggesting
-    the rewritten command so the agent re-executes with the optimized version.
-    """
-    rtk_bin = _resolve_binary("rtk", _RTK_FALLBACK)
-    if not rtk_bin:
-        return None
 
+def _output_optimization(args: Any) -> str:
+    """Recognize the attributed RTK wrapper in the command Hermes executed."""
     if not isinstance(args, dict):
-        return None
-
-    command = args.get("command", "")
-    if not command:
-        return None
-
-    # Version guard — non-fatal
+        return "none"
+    command = args.get("command")
+    if not isinstance(command, str):
+        return "none"
     try:
-        ver_proc = subprocess.run(
-            [rtk_bin, "--version"], capture_output=True, text=True, timeout=3,
-        )
-        ver = _parse_version(ver_proc.stdout)
-        if ver and ver < _MIN_RTK_VERSION:
-            logger.warning("tokenless: rtk %s too old (need >= 0.35.0), rewrite skipped", ver_proc.stdout.strip())
-            return None
-    except Exception:
-        pass
-
-    # Write context file so rtk (running as proxy later) can recover IDs
-    _write_context(AGENT_ID, session_id, tool_call_id)
-
-    # Set env vars for rtk stats context
-    env = os.environ.copy()
-    env["TOKENLESS_AGENT_ID"] = AGENT_ID
-    if session_id:
-        env["TOKENLESS_SESSION_ID"] = session_id
-    if tool_call_id:
-        env["TOKENLESS_TOOL_USE_ID"] = tool_call_id
-
-    proc = subprocess.run(
-        [rtk_bin, "rewrite", command],
-        capture_output=True, text=True, timeout=5, env=env,
-    )
-
-    # Exit code protocol (from rtk rewrite_cmd.rs):
-    #   0 = rewrite available, Allow verdict (auto-allow by permission rule)
-    #   1 = no RTK equivalent (passthrough)
-    #   2 = deny rule matched (let Hermes handle)
-    #   3 = Ask/Default verdict (rewrite available but permission model requires
-    #       user confirmation; in non-interactive hook context, treat as valid
-    #       rewrite since the intent is token optimization, not permission gating)
-    if proc.returncode == 1 or proc.returncode == 2:
-        return None
-    if proc.returncode != 0 and proc.returncode != 3:
-        return None
-
-    rewritten = proc.stdout.strip()
-    if not rewritten or rewritten == command:
-        return None
-
-    logger.info("tokenless: rtk rewrite %s → %s", command, rewritten)
-    return {
-        "action": "block",
-        "message": f"[tokenless:rewrite] Re-execute as: {rewritten}",
-    }
+        lexer = shlex.shlex(command, posix=True, punctuation_chars=True)
+        lexer.whitespace_split = True
+        tokens = list(lexer)
+    except ValueError:
+        return "none"
+    for index, token in enumerate(tokens):
+        wrapper = tokens[index : index + 6]
+        if len(wrapper) < 6 or token != "env":
+            continue
+        if (
+            wrapper[1] == f"TOKENLESS_AGENT_ID={AGENT_ID}"
+            and wrapper[2].startswith("TOKENLESS_SESSION_ID=")
+            and wrapper[3].startswith("TOKENLESS_TOOL_USE_ID=")
+            and wrapper[4].startswith("TOKENLESS_DATA_DIR=")
+            and os.path.basename(wrapper[5]) == "rtk"
+        ):
+            return "rtk"
+    return "none"
 
 
 # ---------------------------------------------------------------------------
@@ -446,28 +420,39 @@ def on_pre_tool_call(
     tool_call_id: str = "",
     **kwargs: Any,
 ) -> dict[str, str] | None:
-    """Tool Ready + RTK rewrite pre-check.
-
-    Step 1: env-check blocks when the tool's environment is not ready.
-    Step 2: for ``terminal`` calls, blocks and suggests RTK-rewritten
-    command (one extra round-trip; safe — rtk rewrite never executes).
-    """
-    # Step 1: env-check (all tools, needs tokenless)
-    if _have("tokenless", _TOKENLESS_FALLBACK):
-        if session_id:
-            os.environ["TOKENLESS_SESSION_ID"] = str(session_id)
-        feedback = _env_check(tool_name)
-        if feedback:
-            logger.info("tokenless: tool-ready blocking %s — %s", tool_name, feedback)
-            return {"action": "block", "message": feedback}
-
-    # Step 2: RTK rewrite (terminal only, needs rtk)
-    if tool_name in _SHELL_TOOLS and _have("rtk", _RTK_FALLBACK):
-        result = _try_rewrite(args, str(session_id), str(tool_call_id))
-        if result:
-            return result
-
-    return None
+    """Ask Core for an RTK rewrite and translate it to a Hermes block."""
+    if tool_name not in _SHELL_TOOLS or not isinstance(args, dict):
+        return None
+    tokenless_bin = _resolve_binary("tokenless", _TOKENLESS_FALLBACK)
+    if not tokenless_bin:
+        return None
+    request = build_pre_tool_request(
+        args,
+        AGENT_ID,
+        tool_name,
+        "command",
+        str(session_id),
+        str(tool_call_id),
+        replace_arguments=False,
+        block_and_suggest=True,
+    )
+    result = run_compress(tokenless_bin, request, _COMPRESS_TIMEOUT_SECONDS, "pre_tool")
+    if not isinstance(result, dict):
+        return None
+    rewritten_args = result.get("arguments")
+    rewritten = rewritten_args.get("command") if isinstance(rewritten_args, dict) else None
+    if (
+        result.get("action") != "block_and_suggest"
+        or result.get("output_optimization") != "rtk"
+        or not isinstance(rewritten, str)
+        or rewritten == args.get("command")
+    ):
+        return None
+    logger.info("tokenless: Core rewrote %s", tool_name)
+    return {
+        "action": "block",
+        "message": f"[tokenless:rewrite] Re-execute as: {rewritten}",
+    }
 
 
 def on_transform_tool_result(
@@ -478,83 +463,81 @@ def on_transform_tool_result(
     session_id: str = "",
     tool_call_id: str = "",
     duration_ms: int = 0,
+    status: str = "",
     **kwargs: Any,
 ) -> str | None:
-    """Response compression + TOON encoding pipeline.
-
-    Replaces the tool result string with a compressed/TOON-encoded version.
-    Runs after post_tool_call; first valid string return wins.
-
-    Content retrieval tools (Read/Glob/Grep) are skipped entirely.
-    Shell/exec tools (Bash/Shell) use moderate truncation (64K/128/8).
-    All other tools use zero-truncation compress-response + TOON.
-    """
-    if not _have("tokenless", _TOKENLESS_FALLBACK):
+    """Send one final Hermes result to Core and apply its disposition."""
+    if not isinstance(result, str):
         return None
-
-    # Content retrieval — skip entirely (preserve integrity)
-    if tool_name in _SKIP_TOOLS:
-        return None
-
-    if not result or result in ("{}", "[]"):
+    protocol_status = _protocol_status(status, result)
+    if protocol_status is None:
         return None
-
-    # Skip skill files (YAML frontmatter)
-    if _is_skill_file(result):
+    tokenless_bin = _resolve_binary("tokenless", _TOKENLESS_FALLBACK)
+    if not tokenless_bin:
         return None
+    output_optimization = _output_optimization(args)
+    retrieve_result = protocol_status == "success" and is_tokenless_retrieve_command(
+        tool_name, args
+    )
 
-    # Skip small responses
-    if len(result) < _MIN_RESPONSE_LEN:
+    # Hermes's terminal tool returns a JSON envelope whose `output` field is
+    # the model-visible command output. Compress that field so structured JSON
+    # produced by the command remains visible to JsonCompressor, then restore
+    # the host envelope below. Other tools already expose their model-bound
+    # result directly and must keep the existing path.
+    shell_envelope = None
+    content = result
+    if tool_name in _SHELL_TOOLS:
+        try:
+            parsed_result = json.loads(result)
+        except json.JSONDecodeError:
+            parsed_result = None
+        if isinstance(parsed_result, dict) and isinstance(parsed_result.get("output"), str):
+            shell_envelope = parsed_result
+            content = parsed_result["output"]
+
+    request = build_post_tool_request(
+        content,
+        AGENT_ID,
+        tool_name,
+        protocol_status,
+        _content_origin(tool_name),
+        output_optimization,
+        result_kind="retrieve" if retrieve_result else "tool",
+        recovery={
+            "kind": (
+                "shell"
+                if (
+                    protocol_status == "success"
+                    and output_optimization == "none"
+                    and not retrieve_result
+                    and tokenless_retrieve_command_available()
+                )
+                else "none"
+            )
+        },
+        session_id=str(session_id),
+        tool_use_id=str(tool_call_id),
+        replace_output=True,
+        replace_with_text=True,
+    )
+    response = run_compress(tokenless_bin, request, _COMPRESS_TIMEOUT_SECONDS, "post_tool")
+    if not isinstance(response, dict):
         return None
-
-    # Validate it's JSON
-    parsed = _try_parse_json(result)
-    if parsed is None:
+    if response.get("disposition") == "applied":
+        output = response.get("output")
+        if isinstance(output, str):
+            logger.info("tokenless: Core optimized %s", tool_name)
+            if shell_envelope is not None:
+                shell_envelope["output"] = output
+                return json.dumps(shell_envelope, ensure_ascii=False)
+            return output
         return None
-
-    # Normalize: result is already a JSON string (Hermes tool contract)
-    original = result
-    original_len = len(original)
-
-    # Step 1: Response compression (per-layer thresholds via get_thresholds)
-    compressed = _compress_response(tool_name, result,
-                                     str(session_id), str(tool_call_id))
-    current = compressed if compressed else result
-
-    # Step 2: TOON encoding — only for payloads at or above the minimum
-    # threshold; small JSON gains near-zero chars from TOON but would still
-    # pay the full encode cost on every tool result.
-    toon_result = None
-    if len(current) >= _MIN_TOON_CHARS:
-        toon_result = _encode_toon(current, str(session_id), str(tool_call_id))
-    used_compression = compressed is not None
-    used_toon = toon_result is not None
-
-    if not used_compression and not used_toon:
-        return None
-
-    # Build final output
-    if used_toon:
-        toon_text, savings_pct = toon_result
-        final = toon_text
-        final_len = len(toon_text)
-        savings_label = (
-            "response compressed + TOON encoded"
-            if used_compression
-            else "TOON encoded"
-        )
-    else:
-        final = current  # type: ignore[assignment]
-        final_len = len(final)
-        savings_pct = (original_len - final_len) * 100 // original_len if original_len else 0
-        savings_label = "response compressed"
-
-    logger.info(
-        "tokenless: %s %s: %d -> %d chars (%d%% reduction)",
-        savings_label, tool_name, original_len, final_len, savings_pct,
-    )
-
-    return final
+    if response.get("disposition") == "tool_error":
+        additional_context = response.get("additional_context")
+        if isinstance(additional_context, str) and additional_context:
+            return f"{result}\n\n{additional_context}"
+    return None
 
 
 # ---------------------------------------------------------------------------
@@ -569,16 +552,8 @@ def register(ctx: Any) -> None:
     ctx.register_hook("pre_tool_call", on_pre_tool_call)
     ctx.register_hook("transform_tool_result", on_transform_tool_result)
 
-    # Log what's active
-    features: list[str] = []
-    if _have("tokenless", _TOKENLESS_FALLBACK):
-        features.append("response-compression")
-        features.append("toon-encoding")
-        features.append("tool-ready")
-    if _have("rtk", _RTK_FALLBACK):
-        features.append("rtk-rewrite")
-
+    features = ["pre-tool", "post-tool"] if _have("tokenless", _TOKENLESS_FALLBACK) else []
     logger.info(
         "tokenless: Hermes plugin registered — active features: %s",
-        ", ".join(features) if features else "none (install tokenless/rtk binary)",
+        ", ".join(features) if features else "none (install tokenless binary)",
     )