subcortex 0.3.0__py3-none-any.whl

subcortex/__init__.py

@@ -0,0 +1,3 @@
+"""subcortex — a local decision layer for coding-agent TUIs."""
+
+__version__ = "0.3.0"

subcortex/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

subcortex/adapters/__init__.py

@@ -0,0 +1,48 @@
+"""Registry of command-hook adapters (lazy: a hook process imports only its own)."""
+
+from __future__ import annotations
+
+import importlib
+from typing import Dict, List, Optional
+
+from ..tuis import canonical
+from .base import HookAdapter
+
+# canonical name -> "module:Class" (relative to this package)
+_ADAPTERS: Dict[str, str] = {
+    "claude-code": "claude_family:ClaudeCodeAdapter",
+    "qoder": "claude_family:QoderAdapter",
+    "codebuddy": "claude_family:CodeBuddyAdapter",
+    "droid": "claude_family:DroidAdapter",
+    "junie": "claude_family:JunieAdapter",
+    "devin": "claude_family:DevinAdapter",
+    "codex": "codex:CodexAdapter",
+    "open-interpreter": "codex:OpenInterpreterAdapter",
+    "gemini-cli": "gemini_family:GeminiCliAdapter",
+    "qwen-code": "gemini_family:QwenCodeAdapter",
+    "cursor": "cursor:CursorAdapter",
+    "copilot": "copilot:CopilotAdapter",
+    "kimi-code": "kimi_code:KimiCodeAdapter",
+    "openhands": "openhands:OpenHandsAdapter",
+    "grok-build": "grok:GrokBuildAdapter",
+    "docker-agent": "docker_agent:DockerAgentAdapter",
+    "letta": "letta_vibe:LettaAdapter",
+    "vibe": "letta_vibe:VibeAdapter",
+}
+
+
+def canonical_name(name: str) -> Optional[str]:
+    return canonical(name, _ADAPTERS)
+
+
+def get_adapter(name: str) -> Optional[HookAdapter]:
+    key = canonical_name(name)
+    if key is None:
+        return None
+    module_name, cls_name = _ADAPTERS[key].split(":")
+    module = importlib.import_module(f".{module_name}", __name__)
+    return getattr(module, cls_name)()
+
+
+def names() -> List[str]:
+    return sorted(_ADAPTERS)

subcortex/adapters/base.py

@@ -0,0 +1,230 @@
+"""Base class for command-hook adapters.
+
+An adapter is pure translation: it maps a TUI's hook event names onto the four
+canonical kinds, parses the TUI's stdin payload into a ``HookEvent``, and
+renders policy results into the TUI's stdout response. All decisions live in
+``subcortex.policy``; process safety lives in ``subcortex.hook``.
+
+The default ``parse`` understands the Claude-Code-style payload that many TUIs
+copied (``session_id``, ``prompt``, ``tool_name``, ``tool_input``,
+``tool_response``, ``transcript_path``, ``source``, ``trigger``); adapters
+override only what differs.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+PROMPT = "prompt"
+TOOL_OUTPUT = "tool_output"
+PRE_COMPACT = "pre_compact"
+POST_COMPACT = "post_compact"
+SESSION_START = "session_start"
+KINDS = (PROMPT, TOOL_OUTPUT, PRE_COMPACT, POST_COMPACT, SESSION_START)
+
+Response = Union[Dict[str, Any], str, None]
+
+# Values that would block, deny, or stop an agent in at least one TUI. A
+# response containing any of them is dropped by ``guard`` unless the adapter
+# explicitly allows that exact (key, value) for that kind.
+BLOCKING_VALUES: Tuple[Tuple[str, Any], ...] = (
+    ("continue", False),
+    ("decision", "block"),
+    ("decision", "deny"),
+    ("decision", "ask"),
+    ("permission", "deny"),
+    ("permission", "ask"),
+    ("permissionDecision", "deny"),
+    ("permissionDecision", "ask"),
+    ("behavior", "deny"),
+    ("block", True),
+    ("abort", True),
+    ("cancel", True),
+)
+
+
+class HookEvent:
+    """One hook event, normalized. A plain class on purpose: importing
+    ``dataclasses`` costs ~3 ms in every (cold-started) hook process."""
+
+    def __init__(self, kind: str, name: str, payload: Dict[str, Any], session_id: str = "",
+                 prompt: str = "", tool: str = "", tool_input: Any = None,
+                 output: Optional[str] = None, failed: bool = False, transcript_path: str = "",
+                 source: str = "", trigger: str = "",
+                 messages: Optional[List[Dict[str, str]]] = None,
+                 extra: Optional[Dict[str, Any]] = None) -> None:
+        self.kind = kind
+        self.name = name
+        self.payload = payload
+        self.session_id = session_id
+        self.prompt = prompt
+        self.tool = tool
+        self.tool_input = tool_input
+        self.output = output
+        self.failed = failed
+        self.transcript_path = transcript_path
+        self.source = source
+        self.trigger = trigger
+        self.messages = messages
+        self.extra = {} if extra is None else extra
+        # Set by the runner: commit callables to run once the response is delivered.
+        self.commits: Optional[List[Any]] = None
+
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, HookEvent) and vars(self) == vars(other)
+
+    def __repr__(self) -> str:
+        return f"HookEvent({vars(self)!r})"
+
+
+def text_of(value: Any) -> Optional[str]:
+    """Flatten common tool-result shapes (str, content blocks, dicts) to text."""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        parts = [b.get("text") for b in value if isinstance(b, dict) and isinstance(b.get("text"), str)]
+        parts += [b for b in value if isinstance(b, str)]
+        return "\n".join(parts) if parts else None
+    if isinstance(value, dict):
+        for key in ("stdout", "output", "llmContent", "content", "text", "result", "returnDisplay"):
+            if key in value:
+                text = text_of(value[key])
+                if text:
+                    return text
+    return None
+
+
+def failed_of(value: Any) -> bool:
+    """True when a tool-result dict signals failure (non-zero exit, error flag, interrupt)."""
+    if not isinstance(value, dict):
+        return False
+    if value.get("interrupted") or value.get("is_error") or value.get("isError"):
+        return True
+    if value.get("error") not in (None, "", False):
+        return True
+    for key in ("exit_code", "exitCode", "returncode", "exit_status"):
+        code = value.get(key)
+        if isinstance(code, int) and code != 0:
+            return True
+    stderr = value.get("stderr")
+    return isinstance(stderr, str) and "traceback" in stderr.lower()
+
+
+class HookAdapter:
+    name: str = ""
+    display_name: str = ""
+    aliases: Tuple[str, ...] = ()
+    # TUI event name -> canonical kind. Lookup is case-insensitive.
+    events: Dict[str, str] = {}
+    # Payload key carrying the event name, used when argv omits it.
+    event_field: str = "hook_event_name"
+    # SessionStart ``source`` values meaning "right after compaction".
+    compact_sources: Tuple[str, ...] = ("compact",)
+    # (kind, key, value) triples this adapter may emit despite BLOCKING_VALUES.
+    allowed_blocking: Tuple[Tuple[str, str, Any], ...] = ()
+    # Deliver the compaction snapshot with the first prompt after compaction
+    # (for TUIs whose session-start/post-compact hooks can't inject context).
+    restore_on_prompt: bool = False
+    # False when the TUI discards prompt-hook output: the hint isn't computed.
+    delivers_hints: bool = True
+
+    # -- event resolution -----------------------------------------------------------
+
+    def resolve(self, name: Any) -> Optional[Tuple[str, str]]:
+        """(TUI event name, kind) for ``name``, or None if we don't handle it."""
+        if not isinstance(name, str) or not name.strip():
+            return None
+        wanted = name.strip().lower().replace("_", "").replace("-", "")
+        for event, kind in self.events.items():
+            if event.lower().replace("_", "").replace("-", "") == wanted:
+                return event, kind
+        return None
+
+    # -- parsing ----------------------------------------------------------------------
+
+    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 payload.get("sessionId") or ""),
+            transcript_path=str(payload.get("transcript_path") or payload.get("transcriptPath") or ""),
+            source=str(payload.get("source") or ""),
+            trigger=str(payload.get("trigger") or ""),
+        )
+        if kind == PROMPT:
+            prompt = payload.get("prompt")
+            event.prompt = prompt if isinstance(prompt, str) else ""
+        elif kind == TOOL_OUTPUT:
+            response = payload.get("tool_response", payload.get("tool_output"))
+            event.tool = str(payload.get("tool_name") or "")
+            event.tool_input = payload.get("tool_input")
+            event.output = text_of(response)
+            event.failed = failed_of(response)
+        return event
+
+    def is_after_compaction(self, event: HookEvent) -> bool:
+        return event.source.lower() in self.compact_sources
+
+    def prompt_context(self, event: HookEvent, cfg: Dict[str, Any]) -> Optional[str]:
+        """Context to deliver alongside a prompt (before any hint). By default:
+        the compaction snapshot, for adapters that restore on the next prompt."""
+        if not self.restore_on_prompt:
+            return None
+        from .. import policy
+
+        return policy.restore_snapshot(event.session_id, cfg, require_ready=True, tui=self.name,
+                                       commits=event.commits)
+
+    def output_context(self, event: HookEvent, cfg: Dict[str, Any]) -> Optional[str]:
+        """Context to deliver alongside a tool result (after the trim decision).
+        None by default; for TUIs whose only model-visible channel is a tool result."""
+        return None
+
+    # -- rendering (None = no output = pass-through) ---------------------------------
+
+    def render_prompt(self, event: HookEvent, text: str) -> Response:
+        """``text`` is the hint, possibly preceded by restored compaction context."""
+        return None
+
+    def render_tool_output(self, event: HookEvent, replacement: str) -> Response:
+        return None
+
+    def render_pre_compact(self, event: HookEvent) -> Response:
+        return None
+
+    def render_post_compact(self, event: HookEvent) -> Response:
+        return None
+
+    def render_session_start(self, event: HookEvent, context: str) -> Response:
+        return None
+
+    # -- safety -------------------------------------------------------------------------
+
+    def guard(self, kind: str, response: Response) -> Response:
+        """Drop any response that could block, deny, or stop the agent."""
+        if response is None or isinstance(response, str):
+            return response
+        if not isinstance(response, dict):
+            return None
+        for key, value in _walk(response):
+            for bad_key, bad_value in BLOCKING_VALUES:
+                if key == bad_key and value == bad_value \
+                        and (kind, key, value) not in self.allowed_blocking:
+                    return None
+        try:
+            json.dumps(response)
+        except (TypeError, ValueError):
+            return None
+        return response
+
+
+def _walk(obj: Any):
+    if isinstance(obj, dict):
+        for key, value in obj.items():
+            yield key, value
+            yield from _walk(value)
+    elif isinstance(obj, list):
+        for item in obj:
+            yield from _walk(item)

subcortex/adapters/claude_family.py

@@ -0,0 +1,133 @@
+"""Adapters for TUIs that copied Claude Code's hook contract.
+
+Same event names and stdin fields (``session_id``, ``transcript_path``,
+``prompt``, ``tool_name``/``tool_input``/``tool_response``, ``source``,
+``trigger``) and the same response envelope
+(``{"hookSpecificOutput": {"hookEventName": ..., ...}}``). What differs is
+which events exist and whether ``updatedToolOutput`` replaces a tool result —
+so each TUI declares that explicitly. Blocking semantics differ too, which is
+why nothing here ever emits ``decision``/``continue``/``permissionDecision``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+from .base import PRE_COMPACT, PROMPT, SESSION_START, TOOL_OUTPUT, HookAdapter, HookEvent, Response
+
+ALL_EVENTS = {
+    "UserPromptSubmit": PROMPT,
+    "PostToolUse": TOOL_OUTPUT,
+    "PreCompact": PRE_COMPACT,
+    "SessionStart": SESSION_START,
+}
+
+
+class ClaudeStyleAdapter(HookAdapter):
+    events = ALL_EVENTS
+    # Does hookSpecificOutput.updatedToolOutput (a string) replace the result the model sees?
+    replaces_output = False
+
+    def _specific(self, event: HookEvent, **fields: Any) -> Dict[str, Any]:
+        # hookEventName is mandatory: some clones reject the whole object without it.
+        return {"hookSpecificOutput": {"hookEventName": event.name, **fields}}
+
+    def render_prompt(self, event: HookEvent, text: str) -> Response:
+        return self._specific(event, additionalContext=text)
+
+    def render_tool_output(self, event: HookEvent, replacement: str) -> Response:
+        if not self.replaces_output:
+            return None
+        return self._specific(event, updatedToolOutput=replacement)
+
+    def render_session_start(self, event: HookEvent, context: str) -> Response:
+        return self._specific(event, additionalContext=context)
+
+
+class ClaudeCodeAdapter(ClaudeStyleAdapter):
+    name = "claude-code"
+    display_name = "Claude Code"
+    # Since 2.1.121 updatedToolOutput replaces the output of any tool — but for
+    # built-in tools only in the tool's own shape (a string is silently ignored).
+    replaces_output = True
+
+    def render_tool_output(self, event: HookEvent, replacement: str) -> Response:
+        response = event.payload.get("tool_response")
+        if not isinstance(response, dict) or not isinstance(response.get("stdout"), str):
+            return None
+        # Already spilled to a file / background / image / interrupted: leave it be.
+        if any(response.get(k) for k in ("persistedOutputPath", "backgroundTaskId", "isImage", "interrupted")):
+            return None
+        return self._specific(event, updatedToolOutput={**response, "stdout": replacement})
+
+    def parse(self, name: str, kind: str, payload: Dict[str, Any]) -> Optional[HookEvent]:
+        # Grok Build, Devin CLI and Cortex Code also execute hooks from
+        # ~/.claude/settings.json, with their own payload shapes. Only answer
+        # payloads that look like Claude Code's own.
+        if not is_claude_code_payload(payload):
+            return None
+        return super().parse(name, kind, payload)
+
+
+# Set in hook processes by other TUIs that also execute ~/.claude/settings.json hooks.
+# Copilot CLI also runs a trusted repo's .claude/settings.json hooks.
+FOREIGN_HOST_ENV = ("CURSOR_VERSION", "DROID_PROJECT_DIR", "FACTORY_PROJECT_DIR", "GROK_HOOK_EVENT",
+                    "COPILOT_CLI")
+
+
+def is_claude_code_payload(payload: Dict[str, Any]) -> bool:
+    if any(os.environ.get(var) for var in FOREIGN_HOST_ENV) or "cursor_version" in payload:
+        return False  # Cursor CLI / Factory Droid running Claude-format hooks
+    if any(k in payload for k in ("hookEventName", "sessionId", "workspaceRoot", "toolName")):
+        return False  # camelCase: Grok Build
+    # NB: not `prompt_id` — Claude Code itself sends it on every event since 2.1.196.
+    if not isinstance(payload.get("transcript_path"), str) or not payload["transcript_path"]:
+        return False  # Devin CLI (absent), Continue cn (empty)
+    if not isinstance(payload.get("session_id"), str) or not payload["session_id"]:
+        return False
+    tool = payload.get("tool_name")
+    return not (isinstance(tool, str) and tool == "bash")  # Cortex Code's lowercase tools
+
+
+class QoderAdapter(ClaudeStyleAdapter):
+    name = "qoder"
+    display_name = "Qoder CLI"
+    replaces_output = True  # "Replaces the tool response (works for any tool)"
+
+
+class CodeBuddyAdapter(ClaudeStyleAdapter):
+    name = "codebuddy"
+    display_name = "CodeBuddy Code"
+    # Its PostToolUse tool_response for Bash carries exit status and byte
+    # counts but no output (verified against 2.156.0): nothing to trim, so the
+    # event isn't registered (a Python start on every Bash call for nothing).
+    events = {k: v for k, v in ALL_EVENTS.items() if v != TOOL_OUTPUT}
+
+
+class DroidAdapter(ClaudeStyleAdapter):
+    name = "droid"
+    display_name = "Factory Droid"
+    # PostToolUse can only block or append in Droid: not registered.
+    events = {k: v for k, v in ALL_EVENTS.items() if v != TOOL_OUTPUT}
+
+    def parse(self, name: str, kind: str, payload: Dict[str, Any]) -> Optional[HookEvent]:
+        event = super().parse(name, kind, payload)
+        previous = payload.get("previous_session_id")
+        if kind == SESSION_START and isinstance(previous, str) and previous:
+            event.session_id = previous  # compaction starts a new session id
+        return event
+
+
+class JunieAdapter(ClaudeStyleAdapter):
+    name = "junie"
+    display_name = "Junie CLI"
+    # No PostToolUse and no PreCompact (so nothing to restore after compaction).
+    events = {"UserPromptSubmit": PROMPT}
+
+
+class DevinAdapter(ClaudeStyleAdapter):
+    name = "devin"
+    display_name = "Devin CLI"
+    # PostToolUse only appends; there is no pre-compaction event.
+    events = {"UserPromptSubmit": PROMPT}

subcortex/adapters/codex.py

@@ -0,0 +1,87 @@
+"""OpenAI Codex CLI (>= 0.133) and Open Interpreter (a Rust fork on the same hook engine).
+
+Claude-like event names and ``hookSpecificOutput`` envelope, with Codex's own
+semantics:
+
+- Every output struct is ``deny_unknown_fields``: any extra key makes the run
+  "Failed" and the output is ignored — so only schema keys are ever emitted.
+- ``PostToolUse``: ``tool_response`` is the model-facing text (a string, no
+  exit code). ``{"decision": "block"}`` would hand the model a *failed* tool
+  call; ``{"continue": false, "stopReason": S, "reason": R}`` replaces the
+  result with ``R`` and the turn continues — the one deliberate ``continue:
+  false`` subcortex ever emits, allowed for this event only. Output Codex
+  already truncated (``Warning: truncated output``) is left alone.
+- ``SessionStart`` with ``source: "compact"`` runs before the next model
+  request after compaction; same ``session_id`` as before.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .base import TOOL_OUTPUT, HookEvent, Response
+from .claude_family import ALL_EVENTS, ClaudeStyleAdapter
+
+CODEX_TRUNCATED = "Warning: truncated output"
+
+
+def _exit_status(payload: Dict[str, Any]) -> Optional[int]:
+    """The command's exit code. The payload has none, but by the time the hook
+    runs the session log (``transcript_path``) records the finished command as
+    an ``item_completed`` CommandExecution with ``exit_code``. None if unknown."""
+    call_id, path = payload.get("tool_use_id"), payload.get("transcript_path")
+    if not isinstance(call_id, str) or not call_id or not isinstance(path, str) or not path:
+        return None
+    try:
+        from ..transcript import read_tail
+
+        for line in reversed(read_tail(Path(path)).splitlines()):
+            if call_id not in line or "CommandExecution" not in line:
+                continue
+            item = ((json.loads(line).get("payload") or {}).get("item") or {})
+            if item.get("type") == "CommandExecution" and item.get("id") == call_id:
+                code = item.get("exit_code")
+                if item.get("status") == "failed" and not (isinstance(code, int) and code != 0):
+                    return 1
+                return code if isinstance(code, int) and not isinstance(code, bool) else None
+    except Exception:
+        return None
+    return None
+
+
+class CodexAdapter(ClaudeStyleAdapter):
+    name = "codex"
+    display_name = "Codex CLI"
+    events = ALL_EVENTS
+    replaces_output = True
+    allowed_blocking = ((TOOL_OUTPUT, "continue", False),)
+
+    def parse(self, name: str, kind: str, payload: Dict[str, Any]) -> Optional[HookEvent]:
+        event = super().parse(name, kind, payload)
+        if kind == TOOL_OUTPUT and isinstance(event.output, str) \
+                and event.output.lstrip().startswith(CODEX_TRUNCATED):
+            event.output = None  # Codex already head/tail-truncated it
+        if kind == TOOL_OUTPUT and event.output is not None:
+            # A failed command must never be trimmed: the model has to see why.
+            code = _exit_status(payload)
+            event.extra["exit_code"] = code
+            event.failed = event.failed or (code is not None and code != 0)
+        return event
+
+    def render_tool_output(self, event: HookEvent, replacement: str) -> Response:
+        removed = len(event.output or "") - len(replacement)
+        # `reason` replaces the whole result, Codex's exit-status header included.
+        if event.extra.get("exit_code") == 0:
+            replacement = "Process exited with code 0\n" + replacement
+        return {
+            "continue": False,
+            "stopReason": f"subcortex: trimmed {max(removed, 0)} chars of low-value output",
+            "reason": replacement,
+        }
+
+
+class OpenInterpreterAdapter(CodexAdapter):
+    name = "open-interpreter"
+    display_name = "Open Interpreter"

subcortex/adapters/copilot.py

@@ -0,0 +1,60 @@
+"""GitHub Copilot CLI (>= 1.0.67) with camelCase hook events.
+
+- ``userPromptSubmitted`` → ``{"additionalContext": ...}`` (model-facing since 1.0.65).
+- ``postToolUse`` (successful calls only) → ``{"modifiedResult": {...}}`` replaces
+  what the model sees; ``resultType`` must stay ``"success"`` (anything else
+  routes the call to the failure path).
+- ``preCompact`` is a notification (can't block); there is no post-compaction
+  ``sessionStart`` source, so the snapshot rides along with the next prompt.
+- Payloads carry no event name: it always comes from argv.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+from .base import PRE_COMPACT, PROMPT, TOOL_OUTPUT, HookAdapter, HookEvent, Response
+
+
+class CopilotAdapter(HookAdapter):
+    name = "copilot"
+    display_name = "GitHub Copilot CLI"
+    events = {"userPromptSubmitted": PROMPT, "postToolUse": TOOL_OUTPUT, "preCompact": PRE_COMPACT}
+    event_field = "hookEventName"
+    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("sessionId") or ""),
+                          transcript_path=str(payload.get("transcriptPath") or ""),
+                          trigger=str(payload.get("trigger") or ""))
+        if kind == PROMPT:
+            prompt = payload.get("prompt")
+            event.prompt = prompt if isinstance(prompt, str) else ""
+        elif kind == TOOL_OUTPUT:
+            result = payload.get("toolResult")
+            if not isinstance(result, dict) or result.get("resultType") != "success":
+                return event
+            args = payload.get("toolArgs")
+            if isinstance(args, str):
+                try:
+                    args = json.loads(args)
+                except ValueError:
+                    pass
+            event.tool = str(payload.get("toolName") or "")
+            event.tool_input = args
+            text = result.get("textResultForLlm")
+            event.output = text if isinstance(text, str) else None
+        elif kind == PRE_COMPACT:
+            event.extra["compacted"] = True  # notification of a compaction in progress
+        return event
+
+    def render_prompt(self, event: HookEvent, text: str) -> Response:
+        return {"additionalContext": text}
+
+    def render_tool_output(self, event: HookEvent, replacement: str) -> Response:
+        result = event.payload.get("toolResult")
+        if not isinstance(result, dict):
+            return None
+        return {"modifiedResult": {**result, "resultType": "success", "textResultForLlm": replacement}}

subcortex/adapters/cursor.py

@@ -0,0 +1,36 @@
+"""Cursor CLI (``agent`` / ``cursor-agent``, builds >= 2026.05.20).
+
+- ``beforeSubmitPrompt`` → ``{"additional_context": ...}`` (> 10,000 chars
+  and Cursor drops it entirely, so we stay under). Only fires in interactive
+  sessions, not ``-p``.
+- ``postToolUse`` can't replace Shell output (only MCP results): not registered.
+- ``preCompact`` is observe-only and fires when compaction happens; there is
+  no post-compaction event (``sessionStart`` is new chats only), so the
+  snapshot is marked ready right away and delivered with the next prompt.
+- Never ``continue``/``permission``/``decision`` keys; exit 2 would reject the prompt.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .base import PRE_COMPACT, PROMPT, HookAdapter, HookEvent, Response
+
+MAX_CONTEXT_CHARS = 9000
+
+
+class CursorAdapter(HookAdapter):
+    name = "cursor"
+    display_name = "Cursor CLI"
+    events = {"beforeSubmitPrompt": PROMPT, "preCompact": 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)
+        event.session_id = str(payload.get("conversation_id") or payload.get("session_id") or "")
+        if kind == PRE_COMPACT:
+            event.extra["compacted"] = True  # fires as compaction runs; can't veto
+        return event
+
+    def render_prompt(self, event: HookEvent, text: str) -> Response:
+        return {"additional_context": text[:MAX_CONTEXT_CHARS]}