subcortex 0.3.0__py3-none-any.whl

subcortex/adapters/docker_agent.py

@@ -0,0 +1,115 @@
+"""Docker Agent (formerly cagent, >= 1.137).
+
+snake_case payloads and responses — Claude's camelCase ``hookSpecificOutput``
+is silently ignored here, so everything goes under ``hook_specific_output``.
+
+- ``user_prompt_submit`` plus the steering / follow-up events (messages sent
+  while the agent is busy) → ``additional_context``.
+- ``tool_response_transform`` on ``shell`` → ``updated_tool_response`` replaces
+  what the model sees *and* what is persisted (never an empty string: that
+  would erase the output). Synthesized errors (``tool_error``) are left alone.
+- ``before_compaction`` gets no transcript; recent messages are read
+  read-only from the session database. ``after_compaction`` marks the
+  snapshot ready and it is delivered with the next prompt. Never returns
+  ``summary``/``decision``/``continue`` (they would replace the summary or block).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..transcript import message_from_entry
+from .base import POST_COMPACT, PRE_COMPACT, PROMPT, TOOL_OUTPUT, HookAdapter, HookEvent, Response
+
+SNAPSHOT_ROWS = 40
+
+
+def session_db() -> Path:
+    return Path.home() / ".cagent" / "session.db"
+
+
+def recent_messages(session_id: str, limit: int = SNAPSHOT_ROWS) -> List[Dict[str, str]]:
+    """Latest user/assistant messages of a session, read-only; [] on any problem."""
+    path = session_db()
+    if not session_id or not path.is_file():
+        return []
+    try:
+        conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True, timeout=2.0)
+    except sqlite3.Error:
+        return []
+    try:
+        rows = conn.execute(
+            "SELECT message_json FROM session_items WHERE session_id = ? AND item_type = 'message' "
+            "ORDER BY position DESC LIMIT ?", (session_id, limit)).fetchall()
+    except sqlite3.Error:
+        return []
+    finally:
+        conn.close()
+    messages = []
+    for (raw,) in reversed(rows):
+        try:
+            msg = message_from_entry(json.loads(raw))
+        except (TypeError, ValueError):
+            continue
+        if msg:
+            messages.append(msg)
+    return messages
+
+
+class DockerAgentAdapter(HookAdapter):
+    name = "docker-agent"
+    display_name = "Docker Agent"
+    events = {
+        "user_prompt_submit": PROMPT,
+        "user_steering_messages_submit": PROMPT,
+        "user_followup_submit": PROMPT,
+        "tool_response_transform": TOOL_OUTPUT,
+        "before_compaction": PRE_COMPACT,
+        "after_compaction": POST_COMPACT,
+    }
+    restore_on_prompt = True
+
+    def parse(self, name: str, kind: str, payload: Dict[str, Any]) -> Optional[HookEvent]:
+        event = HookEvent(kind=kind, name=name, payload=payload,
+                          session_id=str(payload.get("session_id") or ""),
+                          trigger=str(payload.get("compaction_reason") or ""))
+        if kind == PROMPT:
+            steering = payload.get("steering_messages")
+            if isinstance(steering, list):
+                event.prompt = "\n".join(m for m in steering if isinstance(m, str))
+            elif isinstance(payload.get("prompt"), str):
+                event.prompt = payload["prompt"]
+        elif kind == TOOL_OUTPUT:
+            response = payload.get("tool_response")
+            event.output = response if isinstance(response, str) else None
+            event.failed = bool(payload.get("tool_error"))
+            event.tool = str(payload.get("tool_name") or "shell")
+            event.tool_input = payload.get("tool_input")
+        elif kind == PRE_COMPACT:
+            event.messages = recent_messages(event.session_id)
+        return event
+
+    def render_prompt(self, event: HookEvent, text: str) -> Response:
+        return {"hook_specific_output": {"additional_context": text}}
+
+    def render_tool_output(self, event: HookEvent, replacement: Optional[str]) -> Response:
+        if not replacement:
+            return None  # an empty string would erase the output
+        return {"hook_specific_output": {"updated_tool_response": replacement}}
+
+    def guard(self, kind: str, response: Response) -> Response:
+        if isinstance(response, dict) and set(response) - {"hook_specific_output"}:
+            return None
+        return super().guard(kind, response)
+
+
+def config_dir() -> Path:
+    for var in ("DOCKER_AGENT_CONFIG_DIR", "CAGENT_CONFIG_DIR"):
+        value = os.environ.get(var, "").strip()
+        if value:
+            return Path(value)
+    return Path.home() / ".config" / "cagent"

subcortex/adapters/gemini_family.py

@@ -0,0 +1,60 @@
+"""Gemini CLI and its fork Qwen Code.
+
+Both use Claude-like ``hookSpecificOutput`` envelopes but their own event
+names and semantics:
+
+Gemini CLI (>= 0.27): ``BeforeAgent`` injects context; ``AfterTool`` can only
+append or *block* (no replacement — Gemini truncates at 40k chars itself), so
+it isn't registered; ``PreCompress`` fires before every model request (the
+installer matches only ``manual`` triggers, i.e. a real ``/compress``) and there
+is no post-compaction SessionStart, so the snapshot is delivered with the next
+prompt. Any exit status >= 2 with text output BLOCKS in Gemini — the runner
+and the installer's shell guard make that impossible.
+
+Qwen Code (>= 0.16): ``UserPromptSubmit`` also fires on tool-result
+continuations, so only prompts carrying ``submitted_prompt`` are classified;
+``PostToolUse`` is append-only (not registered); ``PreCompact`` fires only when
+compaction will run and ``SessionStart(compact)`` puts context into the system
+instruction.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, Optional
+
+from .base import PRE_COMPACT, PROMPT, SESSION_START
+from .claude_family import ClaudeStyleAdapter
+from .base import HookEvent
+
+_HOOK_CONTEXT_RE = re.compile(r"<hook_context>.*?</hook_context>\s*", re.S)
+
+
+class GeminiCliAdapter(ClaudeStyleAdapter):
+    name = "gemini-cli"
+    display_name = "Gemini CLI"
+    events = {"BeforeAgent": PROMPT, "PreCompress": PRE_COMPACT}
+    restore_on_prompt = True
+
+    def parse(self, name: str, kind: str, payload: Dict[str, Any]) -> Optional[HookEvent]:
+        event = super().parse(name, kind, payload)
+        if kind == PROMPT:
+            # In -p mode SessionStart context is prefixed to the prompt.
+            event.prompt = _HOOK_CONTEXT_RE.sub("", event.prompt)
+        elif kind == PRE_COMPACT and event.trigger == "manual":
+            event.extra["compacted"] = True  # /compress always compresses
+        return event
+
+
+class QwenCodeAdapter(ClaudeStyleAdapter):
+    name = "qwen-code"
+    display_name = "Qwen Code"
+    events = {"UserPromptSubmit": PROMPT, "PreCompact": PRE_COMPACT, "SessionStart": SESSION_START}
+
+    def parse(self, name: str, kind: str, payload: Dict[str, Any]) -> Optional[HookEvent]:
+        event = super().parse(name, kind, payload)
+        if kind == PROMPT:
+            submitted = payload.get("submitted_prompt")
+            # Absent on tool-result continuations: nothing to classify there.
+            event.prompt = submitted if isinstance(submitted, str) else ""
+        return event

subcortex/adapters/grok.py

@@ -0,0 +1,98 @@
+"""Grok Build (xAI ``grok`` >= 1.0.40), verified end to end against 1.0.40.
+
+- Prompt-submit output is discarded by Grok (no hint possible).
+- ``PostToolUse`` can genuinely replace a shell result — but only with the
+  complete tagged ``ToolOutput`` object: the received ``toolResult`` with
+  ``output_for_prompt`` replaced and ``output: []`` (Grok's own doc example is
+  rejected). The ``exit: N …`` header line is kept verbatim; truncated,
+  backgrounded or non-Bash results are left alone.
+- ``PreCompact`` is observe-only; the model's view lives in
+  ``chat_history.jsonl`` next to ``transcriptPath``. ``PostCompact`` output is
+  ignored, so the snapshot rides the next shell call as ``additionalContext``
+  (the only model-visible channel Grok gives command hooks).
+- Any ``decision``/``permissionDecision``/``continue:false`` would block or
+  steer; subcortex only ever writes ``updatedToolOutput`` and ``additionalContext``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .. import policy
+from .base import POST_COMPACT, PRE_COMPACT, PROMPT, TOOL_OUTPUT, HookAdapter, HookEvent, Response
+
+MAX_CONTEXT_CHARS = 9000
+
+
+def _split_header(text: str):
+    """(``exit: N …`` header incl. newline or "", body)."""
+    if text.startswith("exit: "):
+        newline = text.find("\n")
+        if newline != -1:
+            return text[:newline + 1], text[newline + 1:]
+    return "", text
+
+
+class GrokBuildAdapter(HookAdapter):
+    name = "grok-build"
+    display_name = "Grok Build"
+    events = {"UserPromptSubmit": PROMPT, "PostToolUse": TOOL_OUTPUT, "PreCompact": PRE_COMPACT,
+              "PostCompact": POST_COMPACT}
+    delivers_hints = False  # prompt-submit output is discarded; the event only records the request
+
+    def parse(self, name: str, kind: str, payload: Dict[str, Any]) -> Optional[HookEvent]:
+        event = HookEvent(kind=kind, name=name, payload=payload,
+                          session_id=str(payload.get("sessionId") or payload.get("session_id") or ""),
+                          transcript_path=str(payload.get("transcriptPath") or ""),
+                          trigger=str(payload.get("source") or ""))
+        if kind == PROMPT:
+            prompt = payload.get("prompt")
+            event.prompt = prompt if isinstance(prompt, str) else ""
+        elif kind == PRE_COMPACT and event.transcript_path:
+            chat = Path(event.transcript_path).parent / "chat_history.jsonl"
+            if chat.is_file():
+                event.transcript_path = str(chat)
+        elif kind == TOOL_OUTPUT:
+            result = payload.get("toolResult")
+            if payload.get("toolResultTruncated") or not isinstance(result, dict) \
+                    or result.get("type") != "Bash" or result.get("signal") == "backgrounded":
+                return event
+            text = result.get("output_for_prompt")
+            if not isinstance(text, str):
+                return event
+            header, body = _split_header(text)
+            event.extra["header"] = header
+            event.output = body
+            event.tool = str(payload.get("toolName") or "run_terminal_command")
+            event.tool_input = payload.get("toolInput")
+            code = result.get("exit_code")
+            event.failed = bool(result.get("timed_out")) or (isinstance(code, int) and code != 0)
+        return event
+
+    def output_context(self, event: HookEvent, cfg: Dict[str, Any]) -> Optional[str]:
+        # PostCompact output is ignored, so the snapshot rides the next shell call.
+        restored = policy.restore_snapshot(event.session_id, cfg, require_ready=True, tui=self.name,
+                                           commits=event.commits)
+        return restored[:MAX_CONTEXT_CHARS] if restored else None
+
+    def render_tool_output(self, event: HookEvent, replacement: Optional[str]) -> Response:
+        specific: Dict[str, Any] = {"hookEventName": "PostToolUse"}
+        result = event.payload.get("toolResult")
+        if replacement and isinstance(result, dict):
+            specific["updatedToolOutput"] = {**result, "output": [],
+                                             "output_for_prompt": event.extra.get("header", "") + replacement}
+        if event.extra.get("context"):
+            specific["additionalContext"] = event.extra["context"]
+        return {"hookSpecificOutput": specific} if len(specific) > 1 else None
+
+    def guard(self, kind: str, response: Response) -> Response:
+        if isinstance(response, dict) and set(response) - {"hookSpecificOutput"}:
+            return None  # only hookSpecificOutput is ever safe in Grok
+        return super().guard(kind, response)
+
+
+def grok_home() -> Path:
+    override = os.environ.get("GROK_HOME", "").strip()
+    return Path(override) if override else Path.home() / ".grok"

subcortex/adapters/kimi_code.py

@@ -0,0 +1,138 @@
+"""Kimi Code CLI (MoonshotAI/kimi-code >= 0.33) hook adapter.
+
+Kimi's hook contract differs from Claude Code's in ways that matter:
+
+- ``UserPromptSubmit.prompt`` is a list of content parts, not a string.
+- On exit 0 the hook's *message* is injected as context: ``{"message": ...}``
+  or, failing that, the whole stdout verbatim — so Claude-style JSON (or even
+  ``{}``) would be injected as literal text. We emit ``{"message": ...}`` only.
+- ``PostToolUse`` is fire-and-forget: its output is discarded, so tool output
+  can't be replaced (Kimi externalizes huge results itself). Not registered.
+- ``SessionStart`` output is ignored and it never fires after compaction, so
+  the snapshot is delivered with the first prompt after ``PostCompact``.
+- Payloads carry no transcript path: the session's ``wire.jsonl`` is found via
+  ``$KIMI_CODE_HOME/session_index.jsonl``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..transcript import read_tail
+from .base import POST_COMPACT, PRE_COMPACT, PROMPT, HookAdapter, HookEvent, Response
+
+SNAPSHOT_LIMIT = 5
+SNAPSHOT_CHARS = 500
+
+
+def kimi_home() -> Path:
+    override = os.environ.get("KIMI_CODE_HOME", "").strip()
+    return Path(override).expanduser() if override else Path.home() / ".kimi-code"
+
+
+def session_wire(session_id: str) -> Optional[Path]:
+    """``<sessionDir>/agents/main/wire.jsonl`` for a Kimi session id."""
+    if not session_id or "/" in session_id:
+        return None
+    home = kimi_home()
+    session_dir = None
+    try:
+        with open(home / "session_index.jsonl", encoding="utf-8") as fh:
+            for line in fh:
+                try:
+                    record = json.loads(line)
+                except ValueError:
+                    continue
+                if isinstance(record, dict) and record.get("sessionId") == session_id:
+                    session_dir = None if record.get("deleted") else record.get("sessionDir")
+    except OSError:
+        pass
+    if isinstance(session_dir, str):
+        wire = Path(session_dir) / "agents" / "main" / "wire.jsonl"
+        if wire.is_file():
+            return wire
+    matches = sorted((home / "sessions").glob(f"*/{session_id}/agents/main/wire.jsonl"))
+    return matches[-1] if matches else None
+
+
+def wire_messages(path: Path, limit: int = SNAPSHOT_LIMIT,
+                  max_chars: int = SNAPSHOT_CHARS) -> List[Dict[str, str]]:
+    """User prompts and assistant text from a Kimi ``wire.jsonl`` tail.
+
+    User turns are ``context.append_message`` records whose origin kind is
+    ``user`` (injections, hook results and task notices are skipped); assistant
+    text streams as ``content.part`` loop events and is joined per step.
+    """
+    messages: List[Dict[str, str]] = []
+    step, buffer = None, []
+
+    def flush() -> None:
+        text = "".join(buffer).strip()
+        if text:
+            messages.append({"role": "assistant", "text": text[:max_chars]})
+        buffer.clear()
+
+    for line in read_tail(path).splitlines():
+        try:
+            record = json.loads(line)
+        except ValueError:
+            continue
+        if not isinstance(record, dict):
+            continue
+        kind = record.get("type")
+        if kind == "context.clear":
+            flush()
+            messages.clear()
+        elif kind == "context.append_message":
+            message = record.get("message") or {}
+            origin = message.get("origin")
+            origin_kind = origin.get("kind") if isinstance(origin, dict) else origin
+            if message.get("role") != "user" or origin_kind not in (None, "user"):
+                continue
+            flush()
+            text = "\n".join(
+                part.get("text", "") for part in message.get("content") or []
+                if isinstance(part, dict) and part.get("type") == "text").strip()
+            if text:
+                messages.append({"role": "user", "text": text[:max_chars]})
+        elif kind == "context.append_loop_event":
+            event = record.get("event") or {}
+            part = event.get("part") or {}
+            if event.get("type") != "content.part" or part.get("type") != "text":
+                continue
+            if event.get("stepUuid") != step:
+                flush()
+                step = event.get("stepUuid")
+            buffer.append(str(part.get("text", "")))
+    flush()
+    return messages[-limit:]
+
+
+class KimiCodeAdapter(HookAdapter):
+    name = "kimi-code"
+    display_name = "Kimi Code CLI"
+    events = {
+        "UserPromptSubmit": PROMPT,
+        "PreCompact": PRE_COMPACT,
+        "PostCompact": POST_COMPACT,
+    }
+    restore_on_prompt = True
+
+    def parse(self, name: str, kind: str, payload: Dict[str, Any]) -> Optional[HookEvent]:
+        event = super().parse(name, kind, payload)
+        if kind == PROMPT:
+            parts = payload.get("prompt")
+            if isinstance(parts, list):
+                event.prompt = "\n".join(
+                    p.get("text", "") for p in parts
+                    if isinstance(p, dict) and p.get("type") == "text" and isinstance(p.get("text"), str))
+        elif kind == PRE_COMPACT:
+            wire = session_wire(event.session_id)
+            event.messages = wire_messages(wire) if wire else []
+        return event
+
+    def render_prompt(self, event: HookEvent, text: str) -> Response:
+        return {"message": text}

subcortex/adapters/letta_vibe.py

@@ -0,0 +1,96 @@
+"""Letta Code (>= 0.32) and Mistral Vibe (>= 2.25.5).
+
+Letta: ``UserPromptSubmit`` exit-0 stdout is injected verbatim (JSON is not
+parsed — ``{}`` would be injected as text), so the hint is plain text. No
+hook can replace tool output, and there's no transcript to snapshot.
+
+Vibe: no prompt or compaction events, but ``post_tool`` can replace what the
+model sees: ``{"decision": "deny", "reason": R}`` swaps ``tool_output_text``
+for ``R`` without failing or un-running the call (verified in both of Vibe's
+harnesses). That is the one place subcortex emits ``decision: deny``; it is
+allowed for this adapter's tool-output event only. Failed calls
+(``tool_status`` other than ``success``) are left alone.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from ..transcript import _entries, message_from_entry
+from .base import PROMPT, TOOL_OUTPUT, HookAdapter, HookEvent, Response
+
+
+def turn_request(transcript_path: Any) -> str:
+    """The user request of the turn in progress, from Vibe's messages.jsonl.
+
+    Vibe rewrites that log after every LLM step, so once a turn is past its
+    first step the log ends with that step's tool results and its last
+    (non-injected) user message is the current request. At a turn's first
+    step the log still ends with the previous turn, whose request is not
+    this one's evidence: "" then (the output is kept).
+    """
+    try:
+        if not isinstance(transcript_path, str) or not transcript_path:
+            return ""
+        entries = [e for e in _entries(Path(transcript_path)) if isinstance(e, dict)]
+    except Exception:
+        return ""
+    if not entries or entries[-1].get("role") != "tool":
+        return ""
+    for entry in reversed(entries):
+        if entry.get("role") == "user" and not entry.get("injected"):
+            message = message_from_entry(entry)
+            return message["text"] if message else ""
+    return ""
+
+
+class LettaAdapter(HookAdapter):
+    name = "letta"
+    display_name = "Letta Code"
+    events = {"UserPromptSubmit": PROMPT}
+    event_field = "event_type"
+
+    def parse(self, name: str, kind: str, payload: Dict[str, Any]) -> Optional[HookEvent]:
+        if payload.get("is_command"):
+            return None  # slash commands
+        prompt = payload.get("prompt")
+        # conversation_id is literally "default" for every agent's default
+        # conversation: scope it to the agent, or all Letta sessions share state.
+        agent = str(payload.get("agent_id") or "")
+        conversation = str(payload.get("conversation_id") or "")
+        if not conversation or conversation == "default":
+            session = f"{agent}:default" if agent else ""
+        else:
+            session = conversation
+        return HookEvent(kind=kind, name=name, payload=payload, session_id=session,
+                         prompt=prompt if isinstance(prompt, str) else "")
+
+    def render_prompt(self, event: HookEvent, text: str) -> Response:
+        return text  # plain stdout; Letta wraps it in a system reminder
+
+
+class VibeAdapter(HookAdapter):
+    name = "vibe"
+    display_name = "Mistral Vibe"
+    events = {"post_tool": TOOL_OUTPUT}
+    allowed_blocking = ((TOOL_OUTPUT, "decision", "deny"),)
+
+    def parse(self, name: str, kind: str, payload: Dict[str, Any]) -> Optional[HookEvent]:
+        event = HookEvent(kind=kind, name=name, payload=payload,
+                          session_id=str(payload.get("session_id") or ""))
+        text = payload.get("tool_output_text")
+        if payload.get("tool_status") != "success" or not isinstance(text, str):
+            return event
+        event.output = text
+        event.extra["task"] = turn_request(payload.get("transcript_path"))
+        event.tool = str(payload.get("tool_name") or "bash")
+        event.tool_input = payload.get("tool_input")
+        return event
+
+    def render_tool_output(self, event: HookEvent, replacement: Optional[str]) -> Response:
+        if not replacement:
+            return None  # an empty reason would blank the output
+        removed = len(event.output or "") - len(replacement)
+        return {"decision": "deny", "reason": replacement,
+                "system_message": f"subcortex: trimmed {max(removed, 0)} chars of low-value output"}

subcortex/adapters/openhands.py

@@ -0,0 +1,153 @@
+"""OpenHands CLI (>= 1.12, SDK hook engine) adapter.
+
+Only ``UserPromptSubmit`` can inject (``{"additionalContext": ...}``); the
+terminal tool truncates big outputs itself (30k chars) and PostToolUse /
+SessionStart output is ignored, so those aren't registered.
+
+There is no compaction hook. OpenHands' event log is append-only, though: a
+``Condensation`` event hides older events from the model but leaves them on
+disk. So on each prompt we check for a condensation we haven't handled yet and,
+if there is one, hand back the last messages it hid. The first prompt of a
+session only records a baseline (a resumed, already-condensed conversation is
+not re-injected).
+
+Never emitted, per the SDK executor: exit 2, ``decision: deny`` (with any exit
+code) or ANY ``continue`` key (every falsy value blocks).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .. import state
+from ..transcript import message_from_entry
+from .base import PROMPT, HookAdapter, HookEvent, Response
+
+MAX_EVENT_FILES = 3000
+
+
+def conversations_dir() -> Path:
+    override = os.environ.get("OPENHANDS_CONVERSATIONS_DIR", "").strip()
+    if override:
+        return Path(override)
+    persistence = os.environ.get("OPENHANDS_PERSISTENCE_DIR", "").strip()
+    base = Path(persistence) if persistence else Path.home() / ".openhands"
+    return base / "conversations"
+
+
+def _read(path: Path) -> Optional[Dict[str, Any]]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _event_message(event: Dict[str, Any]) -> Optional[Dict[str, str]]:
+    if event.get("kind") != "MessageEvent":
+        return None
+    role = {"user": "user", "agent": "assistant"}.get(str(event.get("source")))
+    if role is None:
+        return None
+    msg = message_from_entry({"role": role, **(event.get("llm_message") or {})})
+    return {"role": role, "text": msg["text"]} if msg else None
+
+
+def _record(session_id: str, record: Dict[str, Any]) -> None:
+    marker = state.path("openhands", "openhands", session_id)
+    if marker is not None:
+        with state.locked(state.key("openhands", session_id)):
+            state.write_json(marker, record)
+
+
+def condensation_context(session_id: str, cfg: Dict[str, Any],
+                         commits: Optional[List[Any]] = None) -> Optional[str]:
+    """Messages hidden by a condensation not yet reported for this session.
+
+    Only event files newer than the last scan are read (a long conversation has
+    thousands). The "reported" marker is written once the context was delivered
+    (via ``commits``), so a hook that dies mid-way reports it next time.
+    """
+    from .. import policy
+
+    if not session_id or "/" in session_id:
+        return None
+    events_dir = conversations_dir() / session_id.replace("-", "") / "events"
+    try:
+        files = sorted(events_dir.glob("event-*.json"))[-MAX_EVENT_FILES:]
+        marker = state.path("openhands", "openhands", session_id)
+        recorded = state.read_json(marker) if marker is not None else None
+    except Exception:
+        return None
+    if not files:
+        return None
+    first_visit = recorded is None
+    seen = (recorded or {}).get("condensation")
+    scanned = str((recorded or {}).get("scanned") or "")
+    newest, index = seen, -1
+    for i in range(len(files) - 1, -1, -1):
+        if not first_visit and files[i].name <= scanned:
+            break  # older files were checked on an earlier prompt
+        event = _read(files[i])
+        if event and event.get("kind") == "Condensation":
+            newest, index = event.get("id") or files[i].name, i
+            break
+    record = {"condensation": newest, "scanned": files[-1].name}
+    deliver = not first_visit and index != -1 and newest != seen
+    context = None
+    if deliver:
+        limit = int((cfg.get("hooks") or {}).get("snapshot_messages", 5))
+        max_chars = int((cfg.get("hooks") or {}).get("snapshot_chars", 500))
+        messages: List[Dict[str, str]] = []
+        for path in reversed(files[:index]):  # newest hidden message first, stop when enough
+            event = _read(path)
+            msg = _event_message(event) if event else None
+            if msg:
+                messages.append({"role": msg["role"], "text": msg["text"][:max_chars]})
+                if len(messages) >= limit:
+                    break
+        if messages:
+            lines = [f"{m['role']}: {m['text']}" for m in reversed(messages)]
+            context = policy.RESTORE_HEADER + "\n" + "\n".join(lines)
+    try:
+        state.prune("openhands", policy.SNAPSHOT_MAX_AGE_S)
+        if context and commits is not None:
+            commits.append(lambda: _record(session_id, record))
+        elif record != recorded:
+            _record(session_id, record)
+    except Exception:
+        return None
+    return context
+
+
+class OpenHandsAdapter(HookAdapter):
+    name = "openhands"
+    display_name = "OpenHands CLI"
+    events = {"UserPromptSubmit": PROMPT}
+    event_field = "event_type"
+
+    def parse(self, name: str, kind: str, payload: Dict[str, Any]) -> Optional[HookEvent]:
+        event = super().parse(name, kind, payload)
+        message = payload.get("message")
+        event.prompt = message if isinstance(message, str) else ""
+        return event
+
+    def prompt_context(self, event: HookEvent, cfg: Dict[str, Any]) -> Optional[str]:
+        if not (cfg.get("features") or {}).get("compaction_snapshot", True):
+            return None
+        try:
+            return condensation_context(event.session_id, cfg, event.commits)
+        except Exception:
+            return None
+
+    def render_prompt(self, event: HookEvent, text: str) -> Response:
+        return {"additionalContext": text}
+
+    def guard(self, kind: str, response: Response) -> Response:
+        # Any `continue` key with a falsy value blocks in OpenHands; allow none at all.
+        if isinstance(response, dict) and "continue" in response:
+            return None
+        return super().guard(kind, response)