sovara-claude-code 0.1.0__tar.gz

sovara_claude_code-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sovara Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sovara_claude_code-0.1.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: sovara-claude-code
+Version: 0.1.0
+Summary: Record Claude Code sessions in Sovara and add relevant lessons to each prompt
+License-Expression: MIT
+Project-URL: Documentation, https://docs.sovara-labs.com/integrations/claude-code
+Project-URL: Repository, https://github.com/SovaraLabs/sovara-claude-code/tree/main/python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sovara<0.11,>=0.10
+Dynamic: license-file
+
+# sovara-claude-code
+
+The Python hook program for [Sovara for Claude Code](https://github.com/SovaraLabs/sovara-claude-code#readme).
+
+```sh
+uv tool install sovara-claude-code
+# or: pip install sovara-claude-code
+```
+
+Then load the `sovara-recording` plugin.
+
+## License
+
+MIT.

sovara_claude_code-0.1.0/README.md

@@ -0,0 +1,14 @@
+# sovara-claude-code
+
+The Python hook program for [Sovara for Claude Code](https://github.com/SovaraLabs/sovara-claude-code#readme).
+
+```sh
+uv tool install sovara-claude-code
+# or: pip install sovara-claude-code
+```
+
+Then load the `sovara-recording` plugin.
+
+## License
+
+MIT.

sovara_claude_code-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sovara-claude-code"
+version = "0.1.0"
+description = "Record Claude Code sessions in Sovara and add relevant lessons to each prompt"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = ["sovara>=0.10,<0.11"]
+
+[project.scripts]
+sovara-claude-code = "sovara_claude_code.__main__:main"
+
+[project.urls]
+Documentation = "https://docs.sovara-labs.com/integrations/claude-code"
+Repository = "https://github.com/SovaraLabs/sovara-claude-code/tree/main/python"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["sovara_claude_code*"]
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "ruff==0.17.2",
+    "httpx",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E4", "E7", "E9", "F", "I", "UP", "B",
+    "D100", "D101", "D102", "D103", "D104", "D106", "D107",
+    "D200", "D205", "D400", "D401", "D419",
+    "ERA001", "PGH004", "RUF100",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["D1"]
+
+[tool.ruff.lint.isort]
+# Sovara's own packages sort together, as in the sovara repository.
+known-first-party = ["sovara", "sovara_common", "sovara_claude_code", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sovara_claude_code-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sovara_claude_code-0.1.0/src/sovara_claude_code/__init__.py

@@ -0,0 +1,9 @@
+"""Record Claude Code sessions in Sovara and add relevant lessons to each prompt.
+
+Claude Code runs ``sovara-claude-code hook`` for each hook event (see the plugin in this
+package's ``plugin/`` directory). ``handle(event)`` is the same entry point for tests.
+"""
+
+from sovara_claude_code._hooks import handle
+
+__all__ = ["handle"]

sovara_claude_code-0.1.0/src/sovara_claude_code/__main__.py

@@ -0,0 +1,28 @@
+"""Command line: ``sovara-claude-code hook`` reads one Claude Code hook event from stdin."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from sovara_claude_code._hooks import handle
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run a hook and print its output for Claude Code; always exits 0."""
+    args = sys.argv[1:] if argv is None else argv
+    if args != ["hook"]:
+        print("usage: sovara-claude-code hook", file=sys.stderr)
+        return 0
+    try:
+        event = json.loads(sys.stdin.read() or "{}")
+    except ValueError:
+        return 0
+    output = handle(event) if isinstance(event, dict) else None
+    if output:
+        print(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sovara_claude_code-0.1.0/src/sovara_claude_code/_hooks.py

@@ -0,0 +1,233 @@
+"""Record a Claude Code session in Sovara from its hook events.
+
+Hooks run as separate processes, so the session's recording is shared through a handle
+(``sovara.open_recording``) kept in the session's state file. A hook never blocks Claude Code:
+failures are swallowed and requests retry only briefly.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+import sovara
+from sovara import (
+    ConversationInput,
+    ConversationOutput,
+    ErrorInfo,
+    ErrorOutcome,
+    LlmCall,
+    Message,
+    SuccessOutcome,
+    TextBlock,
+    ToolCall,
+)
+from sovara.integration import flush_recordings, json_value, short_retries
+from sovara_claude_code import _state
+
+logger = logging.getLogger("sovara_claude_code")
+
+# Per-request timeout, so a hook's usual three requests fit in the 15 s Claude Code allows
+# it (hooks/hooks.json).
+REQUEST_TIMEOUT_SECONDS = 4.0
+# How long a hook waits, before exiting, for reports the SDK sends in the background.
+FLUSH_SECONDS = REQUEST_TIMEOUT_SECONDS
+
+# Errors meaning the recording no longer exists. A write token the server no longer knows
+# is a SovaraConfigError with HTTP 403.
+_LOST_RECORDING = {"recording_inactive", "not_found"}
+
+
+def _recording_lost(exc: Exception) -> bool:
+    if isinstance(exc, sovara.SovaraConfigError):
+        return exc.status_code == 403
+    return isinstance(exc, sovara.RecordingError) and exc.code in _LOST_RECORDING
+
+
+def _project_name(event: dict[str, Any]) -> str:
+    configured = os.environ.get("SOVARA_PROJECT", "").strip()
+    return configured or Path(str(event.get("cwd") or os.getcwd())).name or "claude-code"
+
+
+def _text_message(role: str, text: str) -> Message:
+    return Message(role=role, content=(TextBlock(text=text),))  # type: ignore[arg-type]
+
+
+def _open(event: dict[str, Any], http_client: httpx.Client | None) -> str:
+    """Open a recording of the session's trace; the same session always gets the same trace."""
+    return sovara.open_recording(
+        project_name=_project_name(event),
+        name="Claude Code session",
+        trace_id=f"claude-code:{event['session_id']}",
+        agent_token=os.environ.get("SOVARA_AGENT_TOKEN") or None,
+        http_client=http_client,
+    )
+
+
+def session_start(event: dict[str, Any], http_client: httpx.Client | None = None) -> str | None:
+    """Open the session's recording, or keep it on resume, clear and compact."""
+    session_id = event["session_id"]
+    _state.prune()
+    if _state.load(session_id) is not None:
+        return None
+    _state.save(session_id, {"session": _open(event, http_client), "turn": None, "prompt": None})
+    return None
+
+
+def _start_turn(session: str, prompt: str, http_client: httpx.Client | None) -> str | None:
+    with sovara.resume_recording(session, http_client=http_client):
+        sovara.start_turn(turn_input=prompt)
+        return sovara.export_recording()
+
+
+def _lessons(handle: str, prompt: str, http_client: httpx.Client | None) -> Any:
+    # Retrieved, not applied: Claude Code does not show what reaches the model.
+    with sovara.resume_recording(handle, http_client=http_client):
+        return sovara.retrieve_lessons(prompt)
+
+
+def user_prompt_submit(
+    event: dict[str, Any], http_client: httpx.Client | None = None
+) -> str | None:
+    """Start a turn for the prompt and return matching lessons as extra context."""
+    session_id = event["session_id"]
+    state = _state.load(session_id)
+    if state is None:
+        # SessionStart could not open the recording; the trace key is stable, so open it now.
+        state = {"session": _open(event, http_client), "turn": None, "prompt": None}
+        _state.save(session_id, state)
+    prompt = str(event.get("prompt") or "")
+    try:
+        turn = _start_turn(state["session"], prompt, http_client)
+    except (sovara.RecordingError, sovara.SovaraConfigError) as exc:
+        # Only a recording the exec server lost (e.g. after a restart) is reopened; a passing
+        # failure must not open a second recording of the session.
+        if not _recording_lost(exc):
+            raise
+        state = {**state, "session": _open(event, http_client)}
+        turn = _start_turn(state["session"], prompt, http_client)
+    # Saved before retrieving lessons, so later steps join this turn even if retrieval fails.
+    _state.save(session_id, {**state, "turn": turn, "prompt": prompt})
+    try:
+        lessons = _lessons(turn or state["session"], prompt, http_client) if prompt else None
+    except sovara.RecordingError:
+        lessons = None
+    if lessons is None:
+        return None
+    return json.dumps(
+        {
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": lessons.text,
+            }
+        }
+    )
+
+
+def _record(
+    state: dict[str, Any], call: Any, outcome: Any, http_client: httpx.Client | None
+) -> None:
+    handle = state.get("turn") or state["session"]
+    with sovara.resume_recording(handle, http_client=http_client):
+        sovara.record_step(call, outcome)
+
+
+def _tool_call(event: dict[str, Any]) -> ToolCall:
+    arguments = json_value(event.get("tool_input"))
+    return ToolCall(
+        name=str(event.get("tool_name") or "tool"),
+        arguments=arguments if isinstance(arguments, dict) else {"input": arguments},
+        call_id=str(event.get("tool_use_id") or "").strip() or None,
+        metadata={"source": "claude-code"},
+    )
+
+
+def post_tool_use(event: dict[str, Any], http_client: httpx.Client | None = None) -> str | None:
+    """Record a tool call that succeeded."""
+    state = _state.load(event["session_id"])
+    if state is not None:
+        outcome = SuccessOutcome(output=json_value(event.get("tool_response")))
+        _record(state, _tool_call(event), outcome, http_client)
+    return None
+
+
+def post_tool_use_failure(
+    event: dict[str, Any], http_client: httpx.Client | None = None
+) -> str | None:
+    """Record a tool call that failed or was interrupted."""
+    state = _state.load(event["session_id"])
+    if state is not None:
+        error = ErrorInfo(type="ToolError", message=str(event.get("error") or ""))
+        _record(state, _tool_call(event), ErrorOutcome(error=error), http_client)
+    return None
+
+
+def stop(event: dict[str, Any], http_client: httpx.Client | None = None) -> str | None:
+    """Record Claude's reply to the turn's prompt as a model step."""
+    state = _state.load(event["session_id"])
+    reply = str(event.get("last_assistant_message") or "")
+    if state is None or not reply or event.get("stop_hook_active"):
+        return None
+    prompt = str(state.get("prompt") or "")
+    call = LlmCall(
+        provider="anthropic",
+        input=ConversationInput(messages=(_text_message("user", prompt),) if prompt else ()),
+        metadata={"source": "claude-code"},
+    )
+    outcome = SuccessOutcome(output=ConversationOutput(message=_text_message("assistant", reply)))
+    _record(state, call, outcome, http_client)
+    return None
+
+
+def session_end(event: dict[str, Any], http_client: httpx.Client | None = None) -> str | None:
+    """Close the session's recording and forget its state."""
+    session_id = event["session_id"]
+    state = _state.load(session_id)
+    if state is None:
+        return None
+    try:
+        sovara.close_recording(state["session"], http_client=http_client)
+    finally:
+        _state.delete(session_id)
+    return None
+
+
+HANDLERS = {
+    "SessionStart": session_start,
+    "UserPromptSubmit": user_prompt_submit,
+    "PostToolUse": post_tool_use,
+    "PostToolUseFailure": post_tool_use_failure,
+    "Stop": stop,
+    "SessionEnd": session_end,
+}
+
+
+def handle(event: dict[str, Any], http_client: httpx.Client | None = None) -> str | None:
+    """Run the handler for one hook event; return text for Claude Code, or None.
+
+    Never raises: a failure is logged by type only and the session continues unrecorded.
+    """
+    handler = HANDLERS.get(str(event.get("hook_event_name")))
+    if handler is None or not event.get("session_id"):
+        return None
+    try:
+        with short_retries(), contextlib.ExitStack() as stack:
+            if http_client is None:
+                http_client = stack.enter_context(httpx.Client(timeout=REQUEST_TIMEOUT_SECONDS))
+            output = handler(event, http_client)
+            # Reports queued in the background use http_client, which closes on return.
+            flush_recordings(FLUSH_SECONDS)
+            return output
+    except Exception as exc:
+        logger.warning(
+            "Sovara Claude Code hook failed event=%s error_type=%s",
+            event.get("hook_event_name"),
+            type(exc).__name__,
+        )
+        return None

sovara_claude_code-0.1.0/src/sovara_claude_code/_state.py

@@ -0,0 +1,73 @@
+"""Per-session state shared by the hook processes of one Claude Code session.
+
+Each session has one JSON file holding its recording handles, which carry a write token: the
+file is private (0600), written atomically, and never logged. The format is shared with the
+TypeScript integration (``@sovara/claude-code``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+# A session whose SessionEnd never ran (a crash) is forgotten after this long.
+STALE_AFTER_SECONDS = 7 * 24 * 3600
+_SAFE_ID = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+
+
+def state_dir() -> Path:
+    """Return the state directory: the plugin's data directory, else ``~/.sovara/claude-code``."""
+    plugin_data = os.environ.get("CLAUDE_PLUGIN_DATA", "").strip()
+    if plugin_data:
+        return Path(plugin_data)
+    return Path.home() / ".sovara" / "claude-code"
+
+
+def _path(session_id: str) -> Path:
+    if not _SAFE_ID.match(session_id):
+        raise ValueError("Unsupported Claude Code session ID.")
+    return state_dir() / f"{session_id}.json"
+
+
+def load(session_id: str) -> dict[str, Any] | None:
+    """Return the session's state, or None when it has none."""
+    try:
+        return json.loads(_path(session_id).read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return None
+
+
+def save(session_id: str, state: dict[str, Any]) -> None:
+    """Replace the session's state atomically, readable only by the current user."""
+    path = _path(session_id)
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=".tmp-")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as file:
+            json.dump(state, file)
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def delete(session_id: str) -> None:
+    """Forget the session's state."""
+    _path(session_id).unlink(missing_ok=True)
+
+
+def prune() -> None:
+    """Delete state files of sessions that ended without SessionEnd."""
+    cutoff = time.time() - STALE_AFTER_SECONDS
+    for path in state_dir().glob("*.json"):
+        try:
+            if path.stat().st_mtime < cutoff:
+                path.unlink()
+        except OSError:
+            continue

sovara_claude_code-0.1.0/src/sovara_claude_code.egg-info/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: sovara-claude-code
+Version: 0.1.0
+Summary: Record Claude Code sessions in Sovara and add relevant lessons to each prompt
+License-Expression: MIT
+Project-URL: Documentation, https://docs.sovara-labs.com/integrations/claude-code
+Project-URL: Repository, https://github.com/SovaraLabs/sovara-claude-code/tree/main/python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sovara<0.11,>=0.10
+Dynamic: license-file
+
+# sovara-claude-code
+
+The Python hook program for [Sovara for Claude Code](https://github.com/SovaraLabs/sovara-claude-code#readme).
+
+```sh
+uv tool install sovara-claude-code
+# or: pip install sovara-claude-code
+```
+
+Then load the `sovara-recording` plugin.
+
+## License
+
+MIT.

sovara_claude_code-0.1.0/src/sovara_claude_code.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/sovara_claude_code/__init__.py
+src/sovara_claude_code/__main__.py
+src/sovara_claude_code/_hooks.py
+src/sovara_claude_code/_state.py
+src/sovara_claude_code.egg-info/PKG-INFO
+src/sovara_claude_code.egg-info/SOURCES.txt
+src/sovara_claude_code.egg-info/dependency_links.txt
+src/sovara_claude_code.egg-info/entry_points.txt
+src/sovara_claude_code.egg-info/requires.txt
+src/sovara_claude_code.egg-info/top_level.txt
+tests/test_sovara_claude_code.py

sovara_claude_code-0.1.0/src/sovara_claude_code.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sovara_claude_code-0.1.0/src/sovara_claude_code.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sovara-claude-code = sovara_claude_code.__main__:main

sovara_claude_code-0.1.0/src/sovara_claude_code.egg-info/requires.txt

@@ -0,0 +1 @@
+sovara<0.11,>=0.10

sovara_claude_code-0.1.0/src/sovara_claude_code.egg-info/top_level.txt

@@ -0,0 +1 @@
+sovara_claude_code

sovara_claude_code-0.1.0/tests/test_sovara_claude_code.py

@@ -0,0 +1,223 @@
+"""A Claude Code session recorded through its hooks, against a fake exec server."""
+
+import json
+
+import httpx
+import pytest
+
+from sovara_claude_code import _state, handle
+from sovara_claude_code._hooks import REQUEST_TIMEOUT_SECONDS
+
+TOKEN = "write-token-secret"
+HEALTH = {
+    "status": "ok",
+    "service": "sovara-exec-server",
+    "compatibility": {"component": "exec-server", "contracts": {"runner-api": [6]}},
+}
+
+
+class FakeExecServer:
+    """Answer the runner-api 6 routes the hooks use and keep the requests."""
+
+    def __init__(self, lessons: str | None = "Run the tests first.") -> None:
+        self.lessons = lessons
+        self.lost_recordings = 0
+        self.failing_turns = 0
+        self.failing_status = 500
+        self.failing_lessons = False
+        self.failing_opens = 0
+        self.requests: list[tuple[str, dict]] = []
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        path = request.url.path
+        if path == "/exec/health":
+            return httpx.Response(200, json=HEALTH)
+        body = json.loads(request.content or b"{}")
+        self.requests.append((path, body))
+        if path == "/exec/traces" and self.failing_opens:
+            self.failing_opens -= 1
+            return httpx.Response(500, json={"error": "internal_error", "message": "x"})
+        if path == "/exec/traces":
+            return httpx.Response(
+                200,
+                json={
+                    "trace_id": "trace-1",
+                    "recording_id": "rec-1",
+                    "project_id": "project-1",
+                    "appended": False,
+                    "trace_write_token": TOKEN,
+                },
+            )
+        if path.endswith("/turns"):
+            if self.failing_turns:
+                self.failing_turns -= 1
+                return httpx.Response(self.failing_status, json={"error": "x", "message": "x"})
+            if self.lost_recordings:
+                self.lost_recordings -= 1
+                return httpx.Response(
+                    409, json={"error": "recording_inactive", "message": "Not active."}
+                )
+            return httpx.Response(200, json={"turn_id": "turn-1", "recording_id": "rec-1"})
+        if path.endswith("/lesson-retrievals") and self.failing_lessons:
+            return httpx.Response(500, json={"error": "internal_error", "message": "x"})
+        if path.endswith("/lesson-retrievals"):
+            context = (
+                {"text": self.lessons, "retrieval_id": "retrieval-1"} if self.lessons else None
+            )
+            return httpx.Response(200, json={"ok": True, "lesson_context": context})
+        if path.endswith("/steps/record"):
+            return httpx.Response(200, json={"ok": True, "step_uuid": body["step_uuid"]})
+        return httpx.Response(200, json={"ok": True})
+
+    def paths(self) -> list[str]:
+        return [path.removeprefix("/exec/traces/trace-1") or path for path, _ in self.requests]
+
+
+@pytest.fixture
+def server(tmp_path, monkeypatch):
+    monkeypatch.setenv("CLAUDE_PLUGIN_DATA", str(tmp_path))
+    monkeypatch.setenv("SOVARA_EXEC_SERVER_URL", "http://exec.test")
+    fake = FakeExecServer()
+    with httpx.Client(transport=httpx.MockTransport(fake)) as client:
+        yield fake, client
+
+
+def _event(name: str, **fields) -> dict:
+    return {"hook_event_name": name, "session_id": "s1", "cwd": "/work/my-repo", **fields}
+
+
+def test_a_session_is_recorded_with_lessons_tools_and_the_reply(server, tmp_path, caplog):
+    fake, client = server
+    assert handle(_event("SessionStart", source="startup"), client) is None
+    output = handle(_event("UserPromptSubmit", prompt="Fix the build"), client)
+    handle(
+        _event(
+            "PostToolUse",
+            tool_name="Bash",
+            tool_input={"command": "make"},
+            tool_response={"stdout": "ok"},
+            tool_use_id="t1",
+        ),
+        client,
+    )
+    handle(
+        _event(
+            "PostToolUseFailure",
+            tool_name="Bash",
+            tool_input={"command": "x"},
+            error="Exit code 1",
+            tool_use_id="t2",
+        ),
+        client,
+    )
+    handle(_event("Stop", last_assistant_message="Fixed it."), client)
+    handle(_event("SessionEnd", reason="other"), client)
+
+    assert json.loads(output or "")["hookSpecificOutput"]["additionalContext"] == (
+        "Run the tests first."
+    )
+    assert fake.paths() == [
+        "/exec/traces",
+        "/turns",
+        "/lesson-retrievals",
+        "/steps/record",
+        "/steps/record",
+        "/steps/record",
+        "/complete",
+    ]
+    opened = fake.requests[0][1]
+    assert (opened["project_name"], opened["trace_id"]) == ("my-repo", "claude-code:s1")
+    tool, failed, reply = (body for path, body in fake.requests if path.endswith("/record"))
+    assert tool["call"]["value"]["name"] == "Bash" and tool["turn_id"] == "turn-1"
+    assert failed["outcome"]["value"]["status"] == "error"
+    assert reply["call"]["value"]["kind"] == "llm"
+    assert reply["outcome"]["value"]["output"]["message"]["content"][0]["text"] == "Fixed it."
+    assert list(tmp_path.glob("*.json")) == []
+    assert TOKEN not in caplog.text
+
+
+def test_a_resumed_session_keeps_its_recording(server):
+    fake, client = server
+    handle(_event("SessionStart", source="startup"), client)
+    handle(_event("SessionStart", source="resume"), client)
+    assert fake.paths() == ["/exec/traces"]
+
+
+def test_state_is_private_and_failures_never_reach_claude_code(server, tmp_path, monkeypatch):
+    fake, client = server
+    handle(_event("SessionStart", source="startup"), client)
+    assert oct((tmp_path / "s1.json").stat().st_mode & 0o777) == "0o600"
+
+    def down(request):
+        raise httpx.ConnectError("down", request=request)
+
+    with httpx.Client(transport=httpx.MockTransport(down)) as broken:
+        assert handle(_event("UserPromptSubmit", prompt="hi"), broken) is None
+    assert handle({"hook_event_name": "Unknown"}, client) is None
+    with pytest.raises(ValueError):
+        _state.load("../escape")
+
+
+def test_a_recording_lost_by_the_server_is_reopened_at_the_next_prompt(server):
+    fake, client = server
+    handle(_event("SessionStart", source="startup"), client)
+    fake.lost_recordings = 1  # e.g. the exec server restarted
+
+    output = handle(_event("UserPromptSubmit", prompt="Fix the build"), client)
+
+    assert output is not None
+    assert fake.paths() == [
+        "/exec/traces",
+        "/turns",
+        "/exec/traces",
+        "/turns",
+        "/lesson-retrievals",
+    ]
+    assert fake.requests[2][1]["trace_id"] == "claude-code:s1"
+
+
+@pytest.mark.parametrize("status", [500, 422])
+def test_a_passing_failure_does_not_open_a_second_recording(server, status):
+    fake, client = server
+    handle(_event("SessionStart", source="startup"), client)
+    fake.failing_turns, fake.failing_status = 1, status
+
+    assert handle(_event("UserPromptSubmit", prompt="hi"), client) is None
+    assert fake.paths() == ["/exec/traces", "/turns"]
+
+
+def test_a_failed_lesson_retrieval_still_starts_the_turn(server):
+    fake, client = server
+    handle(_event("SessionStart", source="startup"), client)
+    fake.failing_lessons = True
+
+    assert handle(_event("UserPromptSubmit", prompt="second"), client) is None
+    handle(_event("Stop", last_assistant_message="Done."), client)
+
+    reply = fake.requests[-1][1]
+    assert reply["turn_id"] == "turn-1"
+    assert reply["call"]["value"]["input"]["messages"][0]["content"][0]["text"] == "second"
+
+
+def test_a_session_that_could_not_start_is_recorded_from_the_next_prompt(server):
+    fake, client = server
+    fake.failing_opens = 1
+    handle(_event("SessionStart", source="startup"), client)
+
+    assert handle(_event("UserPromptSubmit", prompt="hi"), client) is not None
+    assert fake.paths() == ["/exec/traces", "/exec/traces", "/turns", "/lesson-retrievals"]
+
+
+def test_hooks_without_a_client_time_out_within_the_hook_limit(server, monkeypatch):
+    fake, _ = server
+    timeouts = []
+    real_client = httpx.Client
+
+    def client(**kwargs):
+        timeouts.append(kwargs["timeout"])
+        return real_client(transport=httpx.MockTransport(fake), **kwargs)
+
+    monkeypatch.setattr("sovara_claude_code._hooks.httpx.Client", client)
+    handle(_event("SessionStart", source="startup"))
+    assert handle(_event("UserPromptSubmit", prompt="hi")) is not None
+    assert timeouts == [REQUEST_TIMEOUT_SECONDS] * 2