subcortex 0.3.0__py3-none-any.whl

subcortex/installers/claude_family.py

@@ -0,0 +1,229 @@
+"""Installers for Claude-Code-style hook files.
+
+All of them write ``{"<Event>": [{"matcher": ..., "hooks": [{"type": "command",
+"command": ..., "timeout": N}]}]}`` groups — under a top-level ``hooks`` key or
+(Droid's hooks.json) at the top level — for exactly the events the TUI's
+adapter handles.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..adapters import get_adapter
+from .base import Installer, Target, add_grouped, json_target, mcp_json_target, remove_grouped
+
+SESSION = "3f6c0e1a-5b7d-4c2e-9a18-6d0f4b2c7e91"
+
+
+class ClaudeStyleInstaller(Installer):
+    seam = "hooks"
+    wrapper: Optional[str] = "hooks"   # None: events at the file's top level
+    shell_tool = "Bash"                # PostToolUse matcher
+    timeout = 10                       # seconds
+
+    def settings_path(self) -> Path:
+        raise NotImplementedError
+
+    def mcp_target(self) -> Optional[Target]:
+        return None
+
+    # -- events -----------------------------------------------------------------------
+
+    def _adapter(self):
+        return get_adapter(self.name)
+
+    def hook_events(self) -> List[str]:
+        order = ["UserPromptSubmit", "PostToolUse", "PreCompact", "SessionStart"]
+        order += [e for e in self._adapter().events if e not in order]
+        return [e for e in order if e in self._adapter().events]
+
+    def matcher(self, event: str) -> Optional[str]:
+        return {"PostToolUse": self.shell_tool, "SessionStart": "compact"}.get(event)
+
+    def entry(self, event: str) -> Dict[str, Any]:
+        return {"type": "command", "command": self.command(event), "timeout": self.timeout}
+
+    # -- file edits ---------------------------------------------------------------------
+
+    def _table(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        if self.wrapper is None:
+            return data
+        table = data.get(self.wrapper)
+        if not isinstance(table, dict):
+            table = data[self.wrapper] = {}
+        return table
+
+    def targets(self) -> List[Target]:
+        def add(data: Dict[str, Any]) -> None:
+            table = self._table(data)
+            for event in self.hook_events():
+                add_grouped(table, event, self.matcher(event), self.entry(event))
+
+        def remove(data: Dict[str, Any]) -> None:
+            table = data if self.wrapper is None else data.get(self.wrapper)
+            if isinstance(table, dict):
+                remove_grouped(table)
+                if self.wrapper is not None and not table:
+                    del data[self.wrapper]
+
+        def installed(data: Dict[str, Any]) -> bool:
+            table = data if self.wrapper is None else data.get(self.wrapper)
+            if not isinstance(table, dict):
+                return False
+            probe = {k: [dict(g) for g in v if isinstance(g, dict)]
+                     for k, v in table.items() if isinstance(v, list)}
+            return bool(remove_grouped(probe))
+
+        targets = [json_target(self.settings_path(), add, remove, installed)]
+        mcp = self.mcp_target() if self.mcp else None
+        if mcp is not None:
+            targets.append(mcp)
+        return targets
+
+    # -- self-test ------------------------------------------------------------------------
+
+    def sample_payload(self, event: str) -> Dict[str, Any]:
+        common = {"session_id": SESSION, "transcript_path": "{transcript}", "cwd": "/tmp",
+                  "hook_event_name": event, "permission_mode": "default"}
+        if event == "UserPromptSubmit":
+            return {**common, "prompt": "what does ls -la do?"}
+        if event == "PostToolUse":
+            return {**common, "tool_name": self.shell_tool, "tool_use_id": "toolu_01",
+                    "tool_input": {"command": "make build"},
+                    "tool_response": {"stdout": "{big_output}", "stderr": "",
+                                      "interrupted": False, "isImage": False}}
+        if event == "PreCompact":
+            return {**common, "trigger": "auto", "custom_instructions": ""}
+        return {**common, "source": "compact"}
+
+    def expects_output(self, event: str) -> bool:
+        if event == "PostToolUse":
+            return bool(getattr(self._adapter(), "replaces_output", False))
+        if event == "SessionStart":
+            return "PreCompact" in self.hook_events()
+        return event == "UserPromptSubmit"
+
+
+def _home_dir(env: str, default: Path) -> Path:
+    override = os.environ.get(env, "").strip()
+    return Path(override).expanduser() if override else default
+
+
+class ClaudeCodeInstaller(ClaudeStyleInstaller):
+    name = "claude-code"
+    display_name = "Claude Code"
+    binaries = ("claude",)
+    docs = "https://code.claude.com/docs/en/hooks"
+    post_install = ("new Claude Code sessions pick this up; optional on-demand tools: "
+                    "claude mcp add --scope user subcortex -- subcortex mcp")
+
+    def settings_path(self) -> Path:
+        return _home_dir("CLAUDE_CONFIG_DIR", Path.home() / ".claude") / "settings.json"
+
+
+class QoderInstaller(ClaudeStyleInstaller):
+    name = "qoder"
+    display_name = "Qoder CLI"
+    binaries = ("qodercli",)
+    docs = "https://docs.qoder.com/cli/hooks"
+    supports_mcp = True
+
+    def qoder_dir(self) -> Path:
+        # Qoder's own resolution: QODER_CONFIG_DIR, else (QODER_CLI_HOME |
+        # GEMINI_CLI_HOME | ~)/(QODER_CONFIG_DIR_NAME | .qoder).
+        explicit = os.environ.get("QODER_CONFIG_DIR", "").strip()
+        if explicit:
+            return Path(explicit).expanduser()
+        home = (os.environ.get("QODER_CLI_HOME", "").strip() or os.environ.get("GEMINI_CLI_HOME", "").strip())
+        name = os.environ.get("QODER_CONFIG_DIR_NAME", "").strip() or ".qoder"
+        return (Path(home).expanduser() if home else Path.home()) / name
+
+    def settings_path(self) -> Path:
+        return self.qoder_dir() / "settings.json"
+
+    def mcp_target(self) -> Optional[Target]:
+        return mcp_json_target(self.settings_path(), self.mcp_command())
+
+
+class CodeBuddyInstaller(ClaudeStyleInstaller):
+    name = "codebuddy"
+    display_name = "CodeBuddy Code"
+    binaries = ("codebuddy",)
+    docs = "https://www.codebuddy.ai/docs/cli/hooks"
+    supports_mcp = True
+
+    def codebuddy_dir(self) -> Path:
+        return _home_dir("CODEBUDDY_CONFIG_DIR", Path.home() / ".codebuddy")
+
+    def settings_path(self) -> Path:
+        return self.codebuddy_dir() / "settings.json"
+
+    def mcp_target(self) -> Optional[Target]:
+        return mcp_json_target(self.codebuddy_dir() / ".mcp.json", self.mcp_command())
+
+
+class DroidInstaller(ClaudeStyleInstaller):
+    name = "droid"
+    display_name = "Factory Droid"
+    binaries = ("droid",)
+    docs = "https://docs.factory.ai/reference/hooks-reference"
+    wrapper = None  # ~/.factory/hooks.json is keyed by event directly
+    shell_tool = "Execute"
+    supports_mcp = True
+    post_install = ("hooks are snapshotted at startup: restart droid. Hints reach interactive and "
+                    "SDK/stream sessions; one-shot `droid exec` skips the prompt hook")
+
+    def factory_dir(self) -> Path:
+        return _home_dir("FACTORY_HOME_OVERRIDE", Path.home()) / ".factory"
+
+    def settings_path(self) -> Path:
+        return self.factory_dir() / "hooks.json"
+
+    def mcp_target(self) -> Optional[Target]:
+        return mcp_json_target(self.factory_dir() / "mcp.json", self.mcp_command(),
+                               extra={"disabled": False})
+
+    def sample_payload(self, event: str) -> Dict[str, Any]:
+        payload = super().sample_payload(event)
+        if event == "SessionStart":  # compaction rotates the session id
+            payload["previous_session_id"] = payload["session_id"]
+            payload["session_id"] = "a1d4e7f0-2c93-4b6e-9f15-7e0c3b8a2d41"
+        return payload
+
+
+class JunieInstaller(ClaudeStyleInstaller):
+    name = "junie"
+    display_name = "Junie CLI"
+    binaries = ("junie",)
+    docs = "https://junie.jetbrains.com/docs/junie-cli-hooks.html"
+    supports_mcp = True
+    post_install = "hints apply to interactive Junie sessions (batch mode doesn't run hooks)"
+
+    def junie_dir(self) -> Path:
+        return _home_dir("JUNIE_HOME", Path.home() / ".junie")
+
+    def settings_path(self) -> Path:
+        return self.junie_dir() / "config.json"
+
+    def mcp_target(self) -> Optional[Target]:
+        return mcp_json_target(self.junie_dir() / "mcp" / "mcp.json", self.mcp_command())
+
+
+class DevinInstaller(ClaudeStyleInstaller):
+    name = "devin"
+    display_name = "Devin CLI"
+    binaries = ("devin",)
+    docs = "https://docs.devin.ai/cli/extensibility/hooks"
+    supports_mcp = True
+
+    def devin_dir(self) -> Path:
+        return _home_dir("XDG_CONFIG_HOME", Path.home() / ".config") / "devin"
+
+    def settings_path(self) -> Path:
+        return self.devin_dir() / "config.json"
+
+    def mcp_target(self) -> Optional[Target]:
+        return mcp_json_target(self.devin_dir() / "mcp_config.json", self.mcp_command())

subcortex/installers/codex.py

@@ -0,0 +1,110 @@
+"""Codex CLI (``$CODEX_HOME/hooks.json``) and Open Interpreter (``~/.openinterpreter/hooks.json``).
+
+``hooks.json`` rather than inline ``[hooks]`` in ``config.toml``: Codex
+writes its own hook-trust state into ``config.toml``, so a JSON file we merge
+into is the exact-uninstall target. ``config.toml`` is still touched for two
+things: removing the (malformed) block subcortex 0.1.0 wrote there, and, with
+``--mcp``, a marked ``[mcp_servers.subcortex]`` block.
+
+Codex only runs non-managed hooks after the user trusts them (``/hooks``);
+until then they are skipped, which is fail-safe.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .base import (InstallError, Target, append_block, has_block, strip_block, toml_str)
+from .claude_family import SESSION, ClaudeStyleInstaller
+
+TRUST = ("run /hooks inside {name} once and trust the subcortex hooks (hooks are hash-verified; "
+         "they are skipped until trusted)")
+
+
+def _toml_target(path: Path, body: Optional[str], tui: str) -> Target:
+    """config.toml: drop any subcortex block (0.1.0 hooks included); add ``body`` if given."""
+    import tomllib
+
+    def check(text: str) -> str:
+        try:
+            tomllib.loads(text)
+        except tomllib.TOMLDecodeError as exc:
+            raise InstallError(f"{path}: result would not be valid TOML ({exc}); refusing to write") from exc
+        return text
+
+    def merge(text: str) -> str:
+        if body is None:
+            return check(strip_block(text)) if has_block(text) else text
+        return check(append_block(text, body, tui))
+
+    def unmerge(text: str) -> str:
+        return check(strip_block(text)) if has_block(text) else text
+
+    return Target(path, merge, unmerge, has_block)
+
+
+class _CodexEngineInstaller(ClaudeStyleInstaller):
+    supports_mcp = True
+
+    def home(self) -> Path:
+        raise NotImplementedError
+
+    def settings_path(self) -> Path:
+        return self.home() / "hooks.json"
+
+    def matcher(self, event: str) -> Optional[str]:
+        return {"PostToolUse": "^Bash$", "SessionStart": "^compact$"}.get(event)
+
+    def targets(self) -> List[Target]:
+        targets = [t for t in super().targets() if t.path == self.settings_path()]
+        body = None
+        if self.mcp:
+            argv = self.mcp_command()
+            body = "\n".join([
+                "[mcp_servers.subcortex]",
+                f"command = {toml_str(argv[0])}",
+                f"args = [{', '.join(toml_str(a) for a in argv[1:])}]",
+                "startup_timeout_sec = 10",
+            ]) + "\n"
+        targets.append(_toml_target(self.home() / "config.toml", body, self.name))
+        return targets
+
+    def sample_payload(self, event: str) -> Dict[str, Any]:
+        common = {"session_id": SESSION, "transcript_path": "{transcript}", "cwd": "/tmp",
+                  "hook_event_name": event, "model": "gpt-5.5-codex"}
+        if event == "UserPromptSubmit":
+            return {**common, "turn_id": "0", "permission_mode": "default", "prompt": "what does ls -la do?"}
+        if event == "PostToolUse":
+            return {**common, "turn_id": "3", "permission_mode": "default", "tool_name": "Bash",
+                    "tool_use_id": "call_1", "tool_input": {"command": "make build"},
+                    "tool_response": "{big_output}"}
+        if event == "PreCompact":
+            return {**common, "turn_id": "7", "trigger": "auto"}
+        return {**common, "permission_mode": "default", "source": "compact"}
+
+
+class CodexInstaller(_CodexEngineInstaller):
+    name = "codex"
+    display_name = "Codex CLI"
+    binaries = ("codex",)
+    docs = "https://developers.openai.com/codex/hooks"
+    min_version = "0.133.0"
+    post_install = TRUST.format(name="codex")
+
+    def home(self) -> Path:
+        override = os.environ.get("CODEX_HOME", "").strip()
+        return Path(override) if override else Path.home() / ".codex"
+
+
+class OpenInterpreterInstaller(_CodexEngineInstaller):
+    name = "open-interpreter"
+    display_name = "Open Interpreter"
+    binaries = ("interpreter",)
+    docs = "https://github.com/openinterpreter/openinterpreter/blob/main/docs/hooks.md"
+    post_install = TRUST.format(name="interpreter")
+
+    def home(self) -> Path:
+        override = os.environ.get("INTERPRETER_HOME", "").strip()
+        return Path(override).expanduser() if override else Path.home() / ".openinterpreter"

subcortex/installers/copilot.py

@@ -0,0 +1,65 @@
+"""GitHub Copilot CLI: a hooks file we own, ``$COPILOT_HOME/hooks/subcortex.json``.
+
+Copilot loads every ``*.json`` in its user hooks directory, so subcortex gets
+its own file (uninstall deletes it) and never touches ``settings.json``.
+Hooks are read at startup: restart copilot after installing.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, List
+
+from .base import Installer, Target, mcp_json_target, owned_file_target
+
+EVENTS = {"userPromptSubmitted": (None, 5), "postToolUse": ("bash|powershell", 10), "preCompact": (None, 10)}
+SESSION = "8c5d7b2e-3f41-4d0a-9c6b-1e2f3a4b5c6d"
+
+
+def copilot_home() -> Path:
+    override = os.environ.get("COPILOT_HOME", "").strip()
+    return Path(override) if override else Path.home() / ".copilot"
+
+
+class CopilotInstaller(Installer):
+    name = "copilot"
+    display_name = "GitHub Copilot CLI"
+    seam = "hooks"
+    binaries = ("copilot",)
+    docs = "https://docs.github.com/en/copilot/reference/hooks-reference"
+    min_version = "1.0.67"
+    supports_mcp = True
+    post_install = "restart copilot to load the hooks"
+
+    def _content(self) -> str:
+        hooks: Dict[str, List[Dict[str, Any]]] = {}
+        for event, (matcher, timeout) in EVENTS.items():
+            entry: Dict[str, Any] = {"type": "command", "bash": self.command(event), "timeoutSec": timeout}
+            if matcher:
+                entry["matcher"] = matcher
+            hooks[event] = [entry]
+        return json.dumps({"version": 1, "hooks": hooks}, indent=2) + "\n"
+
+    def targets(self) -> List[Target]:
+        targets = [owned_file_target(copilot_home() / "hooks" / "subcortex.json", self._content())]
+        if self.mcp:
+            targets.append(mcp_json_target(copilot_home() / "mcp-config.json", self.mcp_command(),
+                                           extra={"type": "local", "env": {}, "tools": ["*"]}))
+        return targets
+
+    def hook_events(self) -> List[str]:
+        return list(EVENTS)
+
+    def sample_payload(self, event: str) -> Dict[str, Any]:
+        common = {"sessionId": SESSION, "timestamp": 1790019371523, "cwd": "/tmp"}
+        if event == "userPromptSubmitted":
+            return {**common, "prompt": "what does ls -la do?"}
+        if event == "postToolUse":
+            return {**common, "toolName": "bash", "toolArgs": {"command": "make build"},
+                    "toolResult": {"resultType": "success", "textResultForLlm": "{big_output}"}}
+        return {**common, "transcriptPath": "{transcript}", "trigger": "auto", "customInstructions": ""}
+
+    def expects_output(self, event: str) -> bool:
+        return event in ("userPromptSubmitted", "postToolUse")

subcortex/installers/crush.py

@@ -0,0 +1,36 @@
+"""Crush: register the ``subcortex mcp`` server in the global ``crush.json``.
+
+Crush (>= v0.64) only has a ``PreToolUse`` hook — no prompt, post-tool or
+compaction events — and it already truncates bash output itself, so its seam
+is MCP. Crush refuses to start on invalid JSON (comments included), so the
+file is only ever rewritten as strict JSON, and refused if it isn't.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import List
+
+from .base import Installer, Target, mcp_json_target
+
+
+def crush_config_dir() -> Path:
+    override = os.environ.get("CRUSH_GLOBAL_CONFIG", "").strip()
+    if override:
+        return Path(override)
+    xdg = os.environ.get("XDG_CONFIG_HOME", "").strip()
+    return (Path(xdg) if xdg else Path.home() / ".config") / "crush"
+
+
+class CrushInstaller(Installer):
+    name = "crush"
+    display_name = "Crush"
+    seam = "mcp"
+    binaries = ("crush",)
+    docs = "https://github.com/charmbracelet/crush#mcps"
+    post_install = "restart crush to load the MCP server (tools appear as mcp_subcortex_*)"
+
+    def targets(self) -> List[Target]:
+        return [mcp_json_target(crush_config_dir() / "crush.json", self.mcp_command(), key="mcp",
+                                extra={"type": "stdio", "timeout": 10})]

subcortex/installers/cursor.py

@@ -0,0 +1,79 @@
+"""Cursor CLI: ``~/.cursor/hooks.json`` (flat, versioned) + optional ``~/.cursor/mcp.json``.
+
+Two ways to disable *every* hook in that file, both avoided here: an unknown
+event key, and any ``//`` inside a string (Cursor strips comments naively).
+The path is hard-coded to the real home directory by Cursor
+(``CURSOR_CONFIG_DIR`` does not move it).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List
+
+from .base import InstallError, Installer, Target, add_flat, json_target, mcp_json_target, remove_flat
+
+EVENTS = {"beforeSubmitPrompt": 5, "preCompact": 10}
+CONVERSATION = "5b0d6c1e-8a4f-4f1e-9d8e-2b7f1c3a9e10"
+
+
+class CursorInstaller(Installer):
+    name = "cursor"
+    display_name = "Cursor CLI"
+    seam = "hooks"
+    binaries = ("agent", "cursor-agent")
+    docs = "https://cursor.com/docs/hooks"
+    supports_mcp = True
+    post_install = "prompt hints fire in interactive sessions (Cursor skips beforeSubmitPrompt in -p mode)"
+
+    def cursor_dir(self) -> Path:
+        return Path.home() / ".cursor"
+
+    def _entry(self, event: str) -> Dict[str, Any]:
+        command = self.command(event)
+        if "//" in command:
+            raise InstallError("the hook command contains '//', which Cursor's hooks.json parser "
+                               f"would treat as a comment: {command}")
+        return {"command": command, "timeout": EVENTS[event]}
+
+    def targets(self) -> List[Target]:
+        def add(data: Dict[str, Any]) -> None:
+            data.setdefault("version", 1)
+            table = data.get("hooks")
+            if not isinstance(table, dict):
+                table = data["hooks"] = {}
+            for event in EVENTS:
+                add_flat(table, event, self._entry(event))
+
+        def remove(data: Dict[str, Any]) -> None:
+            table = data.get("hooks")
+            if isinstance(table, dict):
+                remove_flat(table)
+            if data == {"version": 1, "hooks": {}}:
+                data.clear()  # only ever held our entries
+
+        def installed(data: Dict[str, Any]) -> bool:
+            table = data.get("hooks")
+            return isinstance(table, dict) and bool(remove_flat(json.loads(json.dumps(table))))
+
+        targets = [json_target(self.cursor_dir() / "hooks.json", add, remove, installed)]
+        if self.mcp:
+            targets.append(mcp_json_target(self.cursor_dir() / "mcp.json", self.mcp_command(),
+                                           extra={"type": "stdio", "env": {}}))
+        return targets
+
+    def hook_events(self) -> List[str]:
+        return list(EVENTS)
+
+    def sample_payload(self, event: str) -> Dict[str, Any]:
+        common = {"conversation_id": CONVERSATION, "generation_id": "f2a9c0d4", "model": "composer-2.5",
+                  "session_id": CONVERSATION, "hook_event_name": event,
+                  "cursor_version": "2026.09.18-9a7762b", "workspace_roots": ["/tmp"],
+                  "transcript_path": "{transcript}"}
+        if event == "beforeSubmitPrompt":
+            return {**common, "prompt": "what does ls -la do?", "attachments": []}
+        return {**common, "trigger": "auto", "context_usage_percent": 91, "message_count": 146}
+
+    def expects_output(self, event: str) -> bool:
+        return event == "beforeSubmitPrompt"

subcortex/installers/gemini_family.py

@@ -0,0 +1,83 @@
+"""Gemini CLI (``~/.gemini/settings.json``) and Qwen Code (``~/.qwen/settings.json``).
+
+Entries are tagged ``name: "subcortex:<Event>"`` (Gemini's dedupe key and the
+``/hooks disable`` handle) plus ``description: "managed-by=subcortex"``.
+Timeouts are milliseconds in Gemini; Qwen reads any value >= 1000 as ms on
+every version, so both get ms.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .base import Target, mcp_json_target
+from .claude_family import ClaudeStyleInstaller
+
+TIMEOUT_MS = 10000
+
+
+class _GeminiStyleInstaller(ClaudeStyleInstaller):
+    supports_mcp = True
+
+    def entry(self, event: str) -> Dict[str, Any]:
+        return {"type": "command", "name": f"subcortex:{event}",
+                "description": "managed-by=subcortex",
+                "command": self.command(event), "timeout": TIMEOUT_MS}
+
+    def mcp_target(self) -> Optional[Target]:
+        return mcp_json_target(self.settings_path(), self.mcp_command(),
+                               extra={"description": "managed-by=subcortex"})
+
+
+class GeminiCliInstaller(_GeminiStyleInstaller):
+    name = "gemini-cli"
+    display_name = "Gemini CLI"
+    binaries = ("gemini",)
+    docs = "https://geminicli.com/docs/hooks/"
+    min_version = "0.27.0"
+    post_install = ("restart gemini; hooks (even user-level ones) only run in trusted folders, "
+                    "and the compaction snapshot is taken on /compress")
+
+    def settings_path(self) -> Path:
+        home = os.environ.get("GEMINI_CLI_HOME", "").strip()
+        return (Path(home) if home else Path.home()) / ".gemini" / "settings.json"
+
+    def matcher(self, event: str) -> Optional[str]:
+        # PreCompress fires before *every* model request; lifecycle matchers are
+        # exact strings, so this runs us only for a real /compress.
+        return "manual" if event == "PreCompress" else None
+
+    def sample_payload(self, event: str) -> Dict[str, Any]:
+        common = {"session_id": "3f0c2a7e-5b1d-4c8e-9a41-2d7e6b0f9c13", "transcript_path": "{transcript}",
+                  "cwd": "/tmp", "hook_event_name": event, "timestamp": "2026-09-21T14:02:11.512Z"}
+        if event == "BeforeAgent":
+            return {**common, "prompt": "what does ls -la do?"}
+        return {**common, "trigger": "manual"}
+
+    def expects_output(self, event: str) -> bool:
+        return event == "BeforeAgent"
+
+
+class QwenCodeInstaller(_GeminiStyleInstaller):
+    name = "qwen-code"
+    display_name = "Qwen Code"
+    binaries = ("qwen",)
+    docs = "https://qwenlm.github.io/qwen-code-docs/en/users/features/hooks/"
+    min_version = "0.16.0"
+    post_install = "restart qwen (or open /hooks to reload)"
+
+    def settings_path(self) -> Path:
+        home = os.environ.get("QWEN_HOME", "").strip()
+        return (Path(home) if home else Path.home() / ".qwen") / "settings.json"
+
+    def matcher(self, event: str) -> Optional[str]:
+        return "^compact$" if event == "SessionStart" else None
+
+    def sample_payload(self, event: str) -> Dict[str, Any]:
+        payload = super().sample_payload(event)
+        payload["timestamp"] = "2026-09-21T14:02:11.512Z"
+        if event == "UserPromptSubmit":
+            payload["submitted_prompt"] = payload["prompt"]
+        return payload