code-context-engine 0.4.0__py3-none-any.whl

context_engine/memory/hook_installer.py

@@ -0,0 +1,258 @@
+"""Install/uninstall the 5 Claude Code lifecycle hooks for memory capture.
+
+Two pieces of state to manage:
+
+1. The shell script `cce_hook.sh` lives at `~/.cce/hooks/cce_hook.sh`. It's
+   tiny (~20 lines) and reads stdin → POSTs to the local memory hook server.
+
+2. The project-level `<project>/.claude/settings.json` gets entries under
+   `hooks.<HookName>` pointing to the script. Existing CCE entries (and any
+   user-added entries) are preserved.
+
+Install is idempotent: re-running adds nothing new if the entries already
+exist. Uninstall removes only the entries we added (matched by command
+substring).
+"""
+from __future__ import annotations
+
+import json
+import logging
+import stat
+import sys
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+
+def _is_windows() -> bool:
+    return sys.platform.startswith("win")
+
+
+# On Windows, Claude Code hook commands are passed to cmd.exe rather than sh,
+# so we install a .cmd script. On POSIX (macOS/Linux), the original .sh.
+HOOK_SCRIPT_NAME = "cce_hook.cmd" if _is_windows() else "cce_hook.sh"
+HOOK_DIR = Path.home() / ".cce" / "hooks"
+HOOK_PATH = HOOK_DIR / HOOK_SCRIPT_NAME
+
+# Marker substring used to identify hooks we own — survives subsequent
+# format/path tweaks as long as the script name stays.
+HOOK_MARKER = "cce_hook"
+
+LIFECYCLE_HOOKS = [
+    "SessionStart",
+    "UserPromptSubmit",
+    "PostToolUse",
+    "Stop",
+    "SessionEnd",
+]
+
+# Per-hook matcher overrides. Claude Code accepts a regex-like alternation
+# in the matcher field; SessionStart's subtypes are:
+#   startup  — fresh new conversation
+#   clear    — `/clear` command was run
+#   compact  — `/compact` command was run
+# Re-firing SessionStart on `clear`/`compact` is the trigger that re-
+# injects the memory resume after the model's context window is wiped —
+# without it, "/clear" would erase your prior-decisions context.
+# All other hooks default to matcher="" (any).
+HOOK_MATCHERS = {
+    "SessionStart": "startup|clear|compact",
+}
+
+_HOOK_SCRIPT_BODY_POSIX = """#!/bin/sh
+# CCE memory hook — installed by `cce init`. Forwards Claude Code hook
+# payloads (JSON on stdin) to the local memory capture server.
+#
+# Failure is silent — capture is best-effort and must never block the
+# user's flow. The hook name is passed as $1 (first argument).
+#
+# Special case: SessionStart's HTTP response is written to stdout so
+# Claude Code injects it into the model's context at session start
+# (this is what prevents last week's decisions from being re-explained).
+# Other hooks discard their response.
+set -u
+
+HOOK_NAME="${1:-unknown}"
+PORT_FILE="${HOME}/.cce/projects/$(basename "${PWD}")/serve.port"
+[ -r "${PORT_FILE}" ] || exit 0
+PORT="$(cat "${PORT_FILE}" 2>/dev/null)"
+[ -n "${PORT}" ] || exit 0
+
+if [ "${HOOK_NAME}" = "SessionStart" ]; then
+    RESPONSE="$(curl -sf -m 2 -X POST -H "Content-Type: application/json" \\
+        --data-binary @- "http://127.0.0.1:${PORT}/hooks/${HOOK_NAME}" \\
+        2>/dev/null || true)"
+    if [ -n "${RESPONSE}" ]; then
+        printf "%s\\n" "${RESPONSE}"
+    fi
+else
+    curl -sf -m 1 -X POST -H "Content-Type: application/json" \\
+        --data-binary @- "http://127.0.0.1:${PORT}/hooks/${HOOK_NAME}" \\
+        >/dev/null 2>&1 || true
+fi
+exit 0
+"""
+
+# Windows .cmd equivalent. PowerShell would be more flexible but cmd is
+# always present and avoids the execution-policy gotcha. The same fail-
+# closed semantics: any error → exit 0.
+#
+# SessionStart's response is written to stdout for context injection (see
+# the POSIX comment above); other hooks discard their response.
+_HOOK_SCRIPT_BODY_WIN = """@echo off
+REM CCE memory hook — installed by `cce init`. Forwards Claude Code hook
+REM payloads (JSON on stdin) to the local memory capture server.
+REM Failure is silent (always exit 0) so capture never blocks the user.
+setlocal enabledelayedexpansion
+
+set "HOOK_NAME=%~1"
+if "%HOOK_NAME%"=="" set "HOOK_NAME=unknown"
+
+for %%I in ("%CD%") do set "PROJECT_NAME=%%~nxI"
+set "PORT_FILE=%USERPROFILE%\\.cce\\projects\\%PROJECT_NAME%\\serve.port"
+if not exist "%PORT_FILE%" exit /b 0
+
+set /p PORT=<"%PORT_FILE%"
+if "%PORT%"=="" exit /b 0
+
+if /i "%HOOK_NAME%"=="SessionStart" (
+    set "TMP_RESP=%TEMP%\\cce_hook_resp_%RANDOM%.txt"
+    curl -sf -m 2 -X POST -H "Content-Type: application/json" ^
+        --data-binary @- "http://127.0.0.1:%PORT%/hooks/%HOOK_NAME%" ^
+        > "%TMP_RESP%" 2>nul
+    if exist "%TMP_RESP%" type "%TMP_RESP%"
+    if exist "%TMP_RESP%" del "%TMP_RESP%" >nul 2>&1
+) else (
+    curl -sf -m 1 -X POST -H "Content-Type: application/json" ^
+        --data-binary @- "http://127.0.0.1:%PORT%/hooks/%HOOK_NAME%" >nul 2>&1
+)
+exit /b 0
+"""
+
+
+def _hook_script_body() -> str:
+    return _HOOK_SCRIPT_BODY_WIN if _is_windows() else _HOOK_SCRIPT_BODY_POSIX
+
+
+def _quote_hook_path(path: Path) -> str:
+    """Shell-quote `path` for the host shell. POSIX uses sh; Windows uses cmd.
+
+    sh accepts single quotes (via shlex.quote), cmd accepts double quotes.
+    The two are not interchangeable — POSIX single-quoting on cmd produces
+    a literal-quote'd path that cmd won't dequote.
+    """
+    s = str(path)
+    if _is_windows():
+        # Escape any embedded double quotes the cmd way (rare in real paths).
+        return '"' + s.replace('"', '""') + '"'
+    import shlex
+    return shlex.quote(s)
+
+
+def install_hook_script(target: Path = HOOK_PATH) -> bool:
+    """Write the platform-appropriate hook script to ~/.cce/hooks/.
+    Returns True if created/updated.
+    """
+    target.parent.mkdir(parents=True, exist_ok=True)
+    body = _hook_script_body()
+    existing = target.read_text() if target.exists() else None
+    if existing == body:
+        return False
+    target.write_text(body)
+    if not _is_windows():
+        target.chmod(
+            target.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+        )
+    return True
+
+
+def install_settings(project_dir: Path) -> dict:
+    """Wire all 5 lifecycle hooks into <project>/.claude/settings.json.
+
+    Idempotent. Preserves any existing user hooks. Returns a summary dict
+    with `added` (hook names we wrote) and `skipped` (hook names already
+    present).
+    """
+    settings_dir = project_dir / ".claude"
+    settings_path = settings_dir / "settings.json"
+    settings_dir.mkdir(parents=True, exist_ok=True)
+
+    data: dict = {}
+    if settings_path.exists():
+        try:
+            data = json.loads(settings_path.read_text() or "{}")
+            if not isinstance(data, dict):
+                data = {}
+        except json.JSONDecodeError:
+            log.warning("Existing settings.json is invalid JSON; rewriting.")
+            data = {}
+
+    hooks = data.setdefault("hooks", {})
+    added: list[str] = []
+    skipped: list[str] = []
+
+    for hook_name in LIFECYCLE_HOOKS:
+        bucket = hooks.setdefault(hook_name, [])
+        if _has_cce_hook(bucket):
+            skipped.append(hook_name)
+            continue
+        # Claude Code passes `command` to `sh -c` on POSIX and to `cmd.exe`
+        # on Windows. Both tokenise on whitespace, but they understand
+        # *different* quoting: sh wants single quotes (shlex.quote), cmd
+        # wants double quotes. POSIX-only quoting on a Windows .cmd path
+        # like `C:\Users\Alice Smith\.cce\hooks\cce_hook.cmd` would emit
+        # single quotes that cmd doesn't recognise, breaking capture.
+        bucket.append({
+            "matcher": HOOK_MATCHERS.get(hook_name, ""),
+            "hooks": [{
+                "type": "command",
+                "command": f"{_quote_hook_path(HOOK_PATH)} {hook_name}",
+            }],
+        })
+        added.append(hook_name)
+
+    settings_path.write_text(json.dumps(data, indent=2) + "\n")
+    return {"added": added, "skipped": skipped, "settings_path": str(settings_path)}
+
+
+def uninstall_settings(project_dir: Path) -> dict:
+    """Remove our 5 hook entries from settings.json. Idempotent."""
+    settings_path = project_dir / ".claude" / "settings.json"
+    if not settings_path.exists():
+        return {"removed": [], "settings_path": str(settings_path)}
+    try:
+        data = json.loads(settings_path.read_text() or "{}")
+    except json.JSONDecodeError:
+        return {"removed": [], "settings_path": str(settings_path)}
+    if not isinstance(data, dict):
+        return {"removed": [], "settings_path": str(settings_path)}
+
+    hooks = data.get("hooks") or {}
+    removed: list[str] = []
+    for hook_name in LIFECYCLE_HOOKS:
+        bucket = hooks.get(hook_name)
+        if not bucket:
+            continue
+        kept = [entry for entry in bucket if not _has_cce_hook([entry])]
+        if len(kept) != len(bucket):
+            removed.append(hook_name)
+        if kept:
+            hooks[hook_name] = kept
+        else:
+            del hooks[hook_name]
+
+    if removed:
+        if not hooks:
+            data.pop("hooks", None)
+        settings_path.write_text(json.dumps(data, indent=2) + "\n")
+    return {"removed": removed, "settings_path": str(settings_path)}
+
+
+def _has_cce_hook(bucket: list) -> bool:
+    """True if any entry in the bucket runs our hook script."""
+    for entry in bucket:
+        for h in entry.get("hooks", []) or []:
+            cmd = h.get("command", "") or ""
+            if HOOK_MARKER in cmd:
+                return True
+    return False

context_engine/memory/hook_server.py

@@ -0,0 +1,83 @@
+"""Loopback HTTP server for Claude Code hook payloads.
+
+Bound to 127.0.0.1 on a random free port. The port is written to
+`<storage_base>/serve.port` so the hook shell script can find it without
+configuration. No auth — the listener is loopback-only.
+
+Started as a background asyncio task from `_run_serve` (the MCP server
+process). Stopped gracefully on shutdown.
+"""
+from __future__ import annotations
+
+import logging
+import socket
+from pathlib import Path
+
+from aiohttp import web
+
+from context_engine.memory import db as memory_db
+from context_engine.memory.hooks import add_routes
+
+log = logging.getLogger(__name__)
+
+
+def _find_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+async def start_hook_server(
+    *,
+    storage_base: Path,
+    project_name: str,
+) -> tuple[web.AppRunner, int]:
+    """Spin up the hook HTTP listener. Returns (runner, port).
+
+    Caller is responsible for `await runner.cleanup()` on shutdown.
+    """
+    db_path = memory_db.memory_db_path(storage_base)
+    conn = memory_db.connect(db_path)
+
+    app = web.Application()
+    app["memory_db"] = conn
+    app["project_name"] = project_name
+    add_routes(app)
+
+    async def _close_db(app):
+        try:
+            app["memory_db"].close()
+        except Exception:
+            log.exception("memory_db close failed")
+
+    app.on_cleanup.append(_close_db)
+
+    runner = web.AppRunner(app)
+    await runner.setup()
+
+    port = _find_free_port()
+    site = web.TCPSite(runner, host="127.0.0.1", port=port)
+    await site.start()
+
+    # Authoritative port file lives in the project's storage_base.
+    port_file = Path(storage_base) / "serve.port"
+    port_file.parent.mkdir(parents=True, exist_ok=True)
+    port_file.write_text(str(port))
+
+    # Stable rendezvous file at the *default* storage location. The hook
+    # shell script always looks here (`${HOME}/.cce/projects/<name>/serve.port`)
+    # because it has no way to read the user's config.yaml. When storage_path
+    # is customised, this is the only way capture stays wired up.
+    default_rendezvous = (
+        Path.home() / ".cce" / "projects" / project_name / "serve.port"
+    )
+    try:
+        if default_rendezvous.resolve() != port_file.resolve():
+            default_rendezvous.parent.mkdir(parents=True, exist_ok=True)
+            default_rendezvous.write_text(str(port))
+    except OSError as exc:
+        # Non-fatal — capture still works for users with default storage.
+        log.warning("rendezvous port file write failed: %s", exc)
+
+    log.info("Memory hook server listening on 127.0.0.1:%d", port)
+    return runner, port

context_engine/memory/hooks.py

@@ -0,0 +1,327 @@
+"""HTTP handlers backing the 5 Claude Code lifecycle hooks.
+
+Endpoints (all loopback-only, no auth):
+    POST /hooks/SessionStart        -> insert sessions row
+    POST /hooks/UserPromptSubmit    -> insert prompts row, enqueue prev-turn compress
+    POST /hooks/PostToolUse         -> insert tool_event + tool_event_payload
+    POST /hooks/Stop                -> mark turn complete, enqueue compress
+    POST /hooks/SessionEnd          -> mark session complete, enqueue rollup
+
+Hooks are best-effort: every write is wrapped so a payload-shape error never
+500s back to the hook script (which is `set -e` shell). On error we log + return
+202 so the user's flow is never blocked. The dashboard surfaces error counts.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+import time
+from typing import Any
+
+from aiohttp import web
+
+log = logging.getLogger(__name__)
+
+
+def _now_epoch() -> int:
+    return int(time.time())
+
+
+def _now_iso(epoch: int | None = None) -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime(epoch or _now_epoch()))
+
+
+async def _read_json(request: web.Request) -> dict:
+    try:
+        return await request.json()
+    except Exception as exc:
+        log.warning("Hook payload not JSON: %s", exc)
+        return {}
+
+
+def _conn(request: web.Request) -> sqlite3.Connection:
+    return request.app["memory_db"]
+
+
+_RESUME_RECENT_DECISIONS = 5
+_RESUME_DECISION_REASON_CHARS = 200
+
+
+def build_session_resume(conn: sqlite3.Connection, project: str) -> str:
+    """Compose a short text block summarising recent state for the model.
+
+    Returned as plain text and printed by the hook shell script to stdout.
+    Claude Code injects SessionStart hook stdout into the model's context at
+    conversation start — so this is the mechanism that prevents "decisions
+    you made last week have to be re-explained today." Empty string for
+    a brand-new project so there's no awkward header on the first session.
+    """
+    parts: list[str] = []
+
+    last_rollup = conn.execute(
+        "SELECT id, rollup_summary, ended_at "
+        "FROM sessions "
+        "WHERE rollup_summary IS NOT NULL AND rollup_summary != '' "
+        "ORDER BY started_at_epoch DESC LIMIT 1"
+    ).fetchone()
+
+    decisions = list(conn.execute(
+        "SELECT decision, reason, source, session_id, created_at "
+        "FROM decisions "
+        "ORDER BY created_at_epoch DESC LIMIT ?",
+        (_RESUME_RECENT_DECISIONS,),
+    ))
+
+    if not last_rollup and not decisions:
+        return ""
+
+    parts.append(f"## CCE memory · resuming {project}")
+    # Stored values went through grammar.compress on the write side; expand
+    # before display so the resume reads as natural prose.
+    from context_engine.memory.grammar import expand as _grammar_expand
+
+    if last_rollup:
+        when = last_rollup["ended_at"] or "in progress"
+        parts.append("")
+        parts.append(f"**Previous session** ({when}):")
+        rollup = _grammar_expand((last_rollup["rollup_summary"] or "").strip())
+        for line in rollup.split("\n"):
+            line = line.strip()
+            if line:
+                parts.append(f"  {line}")
+    if decisions:
+        parts.append("")
+        parts.append("**Recent decisions** (most-recent first):")
+        for d in decisions:
+            decision = _grammar_expand((d["decision"] or "").strip())
+            # Truncate before expand so the cap operates on stored bytes,
+            # not on post-expand bytes — otherwise two reasons that stored
+            # equal length display unequal length depending on how many
+            # abbreviations expand.
+            stored_reason = (d["reason"] or "").strip()
+            if len(stored_reason) > _RESUME_DECISION_REASON_CHARS:
+                stored_reason = stored_reason[:_RESUME_DECISION_REASON_CHARS] + "…"
+            reason = _grammar_expand(stored_reason)
+            tag = ""
+            if d["source"] != "manual":
+                tag = f" _[{d['source']}]_"
+            sid_hint = ""
+            if d["session_id"]:
+                sid_hint = f' (session: `{d["session_id"]}`)'
+            parts.append(f"  - {decision} — {reason}{tag}{sid_hint}")
+    parts.append("")
+    parts.append(
+        "Call `session_recall(\"<topic>\")` to find more, or "
+        "`session_timeline(\"<sid>\")` to drill into a session."
+    )
+    return "\n".join(parts)
+
+
+async def handle_session_start(request: web.Request) -> web.Response:
+    """Insert the new session row and return resume context as plain text.
+
+    The body of the response is captured by the hook shell script and
+    printed to stdout, which Claude Code injects into the model's context
+    at session start. That's how prior-week decisions surface without a
+    tool call.
+    """
+    data = await _read_json(request)
+    session_id = data.get("session_id") or data.get("sessionId")
+    if not session_id:
+        return web.Response(text="", status=400)
+    project = data.get("project") or request.app.get("project_name", "")
+    started_epoch = int(data.get("started_at") or _now_epoch())
+
+    conn = _conn(request)
+    try:
+        conn.execute(
+            "INSERT OR IGNORE INTO sessions "
+            "(id, project, started_at_epoch, started_at, status) "
+            "VALUES (?, ?, ?, ?, 'active')",
+            (session_id, project, started_epoch, _now_iso(started_epoch)),
+        )
+        conn.commit()
+    except Exception:
+        log.exception("SessionStart insert failed")
+        return web.Response(text="", status=202)
+
+    try:
+        resume = build_session_resume(conn, project)
+    except Exception:
+        log.exception("SessionStart resume build failed")
+        resume = ""
+    return web.Response(text=resume, content_type="text/plain")
+
+
+async def handle_user_prompt_submit(request: web.Request) -> web.Response:
+    data = await _read_json(request)
+    session_id = data.get("session_id")
+    prompt_text = data.get("prompt_text") or data.get("prompt") or ""
+    prompt_number = data.get("prompt_number")
+    if not session_id:
+        return web.json_response({"error": "session_id required"}, status=400)
+
+    conn = _conn(request)
+    try:
+        if prompt_number is None:
+            row = conn.execute(
+                "SELECT COALESCE(MAX(prompt_number), 0) + 1 AS next "
+                "FROM prompts WHERE session_id = ?",
+                (session_id,),
+            ).fetchone()
+            prompt_number = int(row["next"])
+
+        epoch = _now_epoch()
+        conn.execute(
+            "INSERT OR IGNORE INTO prompts "
+            "(session_id, prompt_number, prompt_text, created_at_epoch, created_at) "
+            "VALUES (?, ?, ?, ?, ?)",
+            (session_id, int(prompt_number), str(prompt_text), epoch, _now_iso(epoch)),
+        )
+        conn.execute(
+            "UPDATE sessions SET prompt_count = prompt_count + 1 WHERE id = ?",
+            (session_id,),
+        )
+        # Enqueue previous turn for compression. The session may have N-1
+        # prompts now; compress turn N-1.
+        if int(prompt_number) > 1:
+            _enqueue_compression(
+                conn, kind="turn",
+                session_id=session_id,
+                prompt_number=int(prompt_number) - 1,
+            )
+        conn.commit()
+    except Exception:
+        log.exception("UserPromptSubmit insert failed")
+        return web.json_response({"ok": False}, status=202)
+    return web.json_response({"ok": True, "prompt_number": prompt_number})
+
+
+async def handle_post_tool_use(request: web.Request) -> web.Response:
+    data = await _read_json(request)
+    session_id = data.get("session_id")
+    if not session_id:
+        return web.json_response({"error": "session_id required"}, status=400)
+
+    tool_name = data.get("tool_name", "unknown")
+    tool_input = data.get("tool_input") or data.get("tool_input_json") or {}
+    tool_output = data.get("tool_output") or data.get("tool_output_json") or ""
+    prompt_number = data.get("prompt_number")
+
+    raw_input = tool_input if isinstance(tool_input, str) else json.dumps(tool_input)
+    raw_output = tool_output if isinstance(tool_output, str) else json.dumps(tool_output)
+    size = len(raw_input) + len(raw_output)
+
+    conn = _conn(request)
+    try:
+        if prompt_number is None:
+            row = conn.execute(
+                "SELECT COALESCE(MAX(prompt_number), 0) AS cur FROM prompts "
+                "WHERE session_id = ?",
+                (session_id,),
+            ).fetchone()
+            prompt_number = int(row["cur"]) or 0
+
+        cur = conn.execute(
+            "INSERT INTO tool_event_payloads (raw_input, raw_output, size_bytes) "
+            "VALUES (?, ?, ?)",
+            (raw_input, raw_output, size),
+        )
+        payload_id = cur.lastrowid
+        epoch = _now_epoch()
+        conn.execute(
+            "INSERT INTO tool_events "
+            "(session_id, prompt_number, tool_name, payload_id, created_at_epoch, created_at) "
+            "VALUES (?, ?, ?, ?, ?, ?)",
+            (session_id, int(prompt_number), tool_name, payload_id, epoch, _now_iso(epoch)),
+        )
+        conn.commit()
+    except Exception:
+        log.exception("PostToolUse insert failed")
+        return web.json_response({"ok": False}, status=202)
+    return web.json_response({"ok": True})
+
+
+async def handle_stop(request: web.Request) -> web.Response:
+    data = await _read_json(request)
+    session_id = data.get("session_id")
+    prompt_number = data.get("prompt_number")
+    if not session_id:
+        return web.json_response({"error": "session_id required"}, status=400)
+
+    conn = _conn(request)
+    try:
+        if prompt_number is None:
+            row = conn.execute(
+                "SELECT COALESCE(MAX(prompt_number), 0) AS cur FROM prompts "
+                "WHERE session_id = ?",
+                (session_id,),
+            ).fetchone()
+            prompt_number = int(row["cur"]) or 0
+        if int(prompt_number) > 0:
+            _enqueue_compression(
+                conn, kind="turn",
+                session_id=session_id, prompt_number=int(prompt_number),
+            )
+        conn.commit()
+    except Exception:
+        log.exception("Stop enqueue failed")
+        return web.json_response({"ok": False}, status=202)
+    return web.json_response({"ok": True})
+
+
+async def handle_session_end(request: web.Request) -> web.Response:
+    data = await _read_json(request)
+    session_id = data.get("session_id")
+    exit_reason = data.get("exit_reason") or "normal"
+    if not session_id:
+        return web.json_response({"error": "session_id required"}, status=400)
+
+    conn = _conn(request)
+    try:
+        epoch = _now_epoch()
+        conn.execute(
+            "UPDATE sessions SET status = 'completed', exit_reason = ?, "
+            "ended_at_epoch = ?, ended_at = ? WHERE id = ?",
+            (exit_reason, epoch, _now_iso(epoch), session_id),
+        )
+        _enqueue_compression(
+            conn, kind="session_rollup",
+            session_id=session_id, prompt_number=None,
+        )
+        conn.commit()
+    except Exception:
+        log.exception("SessionEnd update failed")
+        return web.json_response({"ok": False}, status=202)
+    return web.json_response({"ok": True})
+
+
+def _enqueue_compression(
+    conn: sqlite3.Connection,
+    *,
+    kind: str,
+    session_id: str,
+    prompt_number: int | None,
+) -> None:
+    """Add a (kind, session_id, prompt_number) row to pending_compressions.
+
+    UNIQUE(kind, session_id, prompt_number) guards against double-enqueue when
+    a prompt fires both Stop *and* the next UserPromptSubmit's "compress prev"
+    trigger in quick succession.
+    """
+    conn.execute(
+        "INSERT OR IGNORE INTO pending_compressions "
+        "(kind, session_id, prompt_number, enqueued_at_epoch) "
+        "VALUES (?, ?, ?, ?)",
+        (kind, session_id, prompt_number, _now_epoch()),
+    )
+
+
+def add_routes(app: web.Application) -> None:
+    """Attach the 5 hook routes to an existing aiohttp app."""
+    app.router.add_post("/hooks/SessionStart", handle_session_start)
+    app.router.add_post("/hooks/UserPromptSubmit", handle_user_prompt_submit)
+    app.router.add_post("/hooks/PostToolUse", handle_post_tool_use)
+    app.router.add_post("/hooks/Stop", handle_stop)
+    app.router.add_post("/hooks/SessionEnd", handle_session_end)