truthstone 0.2.0__py3-none-any.whl

truthstone/__init__.py

@@ -0,0 +1,7 @@
+"""Truthstone — host-powered reliability and reasoning layer for AI coding agents.
+
+Deliberately empty of imports: `truthstone.adapters.claude_code.shim` runs on the hook
+path and must not pay for loading pydantic/fastapi transitively.
+"""
+
+__version__ = "0.2.0"

truthstone/adapters/claude_code/__init__.py

@@ -0,0 +1 @@
+"""Claude Code adapter (SPEC §24.1 — the first and highest-priority integration)."""

truthstone/adapters/claude_code/forward.py

@@ -0,0 +1,308 @@
+"""Hot-path forwarder for command hooks: stdin -> Truthstone daemon -> stdout.
+
+Why a command hook, and why this file
+-------------------------------------
+Settings-based installs reach the daemon through Claude Code ``http`` hooks, which carry
+the local bearer token in a header. A *plugin* cannot do that. Measured on Claude Code
+2.1.317 (see ``docs/CLAUDE-PLUGIN.md``): a plugin ``http`` hook interpolates header values
+only from variables already in Claude Code's own launch environment — never
+``${CLAUDE_PLUGIN_ROOT}``/``${CLAUDE_PLUGIN_DATA}``, and never anything a ``SessionStart``
+hook writes to ``CLAUDE_ENV_FILE``. A per-user secret therefore cannot reach the header
+without the user exporting it by hand, so the plugin uses ``command`` hooks, and every
+tool call pays for one process. This module keeps that process as cheap as Python allows:
+
+* it runs as a **file**, ``python -I -S forward.py``: no ``site`` (no site-packages scan,
+  no ``.pth`` processing), no user site, no ``PYTHON*`` variables, and — the security
+  half — no working directory on ``sys.path``. Hooks run inside the user's repository, so
+  a repository file named ``json.py`` must never be importable here;
+* it imports only builtin C modules: ``_socket`` instead of ``socket`` (whose ``enum``
+  import costs ~2 ms) and ``_json`` instead of ``json`` (whose ``re`` import costs
+  ~7 ms). The scanner below *is* CPython's JSON parser, minus the regex wrappers;
+* it makes **one** request. There is no ``/health`` probe first: a refused connection is
+  the probe, and it fails open in microseconds. Liveness checks, revival and the visible
+  "unguarded" warning happen once per prompt, in ``plugin.py``, not once per tool call.
+
+It must stay standalone: no ``truthstone`` imports (the package is not importable under
+``-S``), standard library only.
+
+Two safety properties are enforced here, at the transport boundary, so they hold even if a
+daemon bug — or a foreign process squatting on the daemon's port — produces bad output:
+
+* **Truthstone never grants permissions.** A response carrying ``permissionDecision:
+  "allow"`` is dropped, which is the same as saying nothing.
+* **Fail open.** Every failure — no handshake, refused connection, timeout, non-200,
+  unparsable body — exits 0 with no output, so the agent proceeds as if Truthstone were
+  not installed. Exit code 2 (which would *block* the agent) is never used.
+"""
+
+from __future__ import annotations
+
+import _json
+import _socket
+import os
+import sys
+
+MAX_STDIN_BYTES = 1_000_000
+MAX_RESPONSE_BYTES = 64_000
+DEFAULT_TIMEOUT_S = 4.0
+HOOK_PATH = "/hook/claude-code"
+_TRUE = ("1", "true", "yes", "on")
+
+
+class _Ctx:
+    """The attribute bag ``_json.make_scanner`` reads: ``json.decoder``'s defaults.
+
+    This is a private CPython interface and it does change — 3.15 added ``array_hook`` —
+    so construction is guarded below and falls back to the public ``json`` module.
+    """
+
+    strict = True
+    object_hook = None
+    object_pairs_hook = None
+    array_hook = None
+    parse_float = float
+    parse_int = int
+    memo: dict = {}  # noqa: RUF012 - read by the C scanner, never mutated here
+
+    @staticmethod
+    def parse_constant(name: str) -> float:
+        return {"-Infinity": float("-inf"), "Infinity": float("inf"), "NaN": float("nan")}[name]
+
+
+try:
+    _scan = _json.make_scanner(_Ctx())
+except Exception:  # noqa: BLE001 - a newer CPython's scanner wants more; use the public API
+    _scan = None
+
+
+def loads(text: str) -> object:
+    """Parse one JSON document with the C scanner. Raises ``ValueError`` on bad input."""
+    if _scan is None:
+        import json  # ~7 ms, only on a CPython whose private scanner contract moved
+
+        return json.loads(text)
+    start = len(text) - len(text.lstrip(" \t\n\r"))
+    try:
+        value, end = _scan(text, start)
+    except StopIteration as exc:  # the C scanner's "no value here"
+        raise ValueError("not JSON") from exc
+    if text[end:].strip(" \t\n\r"):
+        raise ValueError("trailing data")
+    return value
+
+
+# Former product names, newest first, as (display, slug, upper): the registry in
+# truthstone/names.py, which this file cannot import. scripts/rename_product.py records a
+# rename in both, and tests/test_names.py keeps them equal.
+# rename-tool: keep-begin former-names
+FORMER: tuple[tuple[str, str, str], ...] = (("AgentGuard", "agentguard", "AGENTGUARD"),)
+# rename-tool: keep-end
+
+
+def setting(key: str) -> str:
+    """``TRUTHSTONE_<key>``, else the same setting under a former name; ``""`` if unset.
+
+    The rule of ``names.env``: the first non-empty value wins, the current name first.
+    """
+    for upper in ("TRUTHSTONE", *(former[2] for former in FORMER)):
+        value = os.environ.get(upper + "_" + key)
+        if value:
+            return value
+    return ""
+
+
+def truthstone_home() -> str:
+    """The rule of ``names.data_dir``: ``$TRUTHSTONE_HOME``, else ``~/.truthstone``, unless
+    only a former name's directory exists."""
+    explicit = setting("HOME")
+    if explicit:
+        return os.path.expanduser(explicit)
+    home = os.path.expanduser("~/.truthstone")
+    if not os.path.lexists(home):
+        for former in FORMER:
+            candidate = os.path.expanduser("~/." + former[1])
+            if os.path.lexists(candidate):
+                return candidate
+    return home
+
+
+def read_handshake(home: str) -> dict | None:
+    """``daemon.json``, or ``None``. A symlinked handshake is refused, as in the shim."""
+    path = os.path.join(home, "daemon.json")
+    try:
+        if os.path.islink(path):
+            return None
+        with open(path, "rb") as fh:
+            raw = fh.read(MAX_RESPONSE_BYTES + 1)
+        if len(raw) > MAX_RESPONSE_BYTES:
+            return None
+        data = loads(raw.decode("utf-8"))
+    except (OSError, ValueError, UnicodeDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def loopback_ipv4(host: object) -> str | None:
+    """The daemon binds IPv4 loopback only; refuse to send the token anywhere else."""
+    if not isinstance(host, str):
+        return None
+    host = host.strip()
+    if host.lower() == "localhost":
+        return "127.0.0.1"
+    parts = host.split(".")
+    if len(parts) != 4 or not all(p.isdigit() and len(p) <= 3 for p in parts):
+        return None
+    octets = [int(p) for p in parts]
+    if octets[0] != 127 or any(o > 255 for o in octets):
+        return None
+    return ".".join(str(o) for o in octets)
+
+
+def endpoint_of(hs: dict) -> tuple[str, int, str] | None:
+    """``(host, port, token)`` from a handshake, or ``None`` if any part is unsafe."""
+    host = loopback_ipv4(hs.get("host", "127.0.0.1"))
+    port = hs.get("port")
+    token = hs.get("token")
+    if host is None or type(port) is not int or not 0 < port <= 65535:
+        return None
+    if not isinstance(token, str) or not token or not token.isascii():
+        return None
+    if any(c in token for c in "\r\n "):
+        return None  # header injection
+    return host, port, token
+
+
+def _dechunk(body: bytes) -> bytes:
+    out = bytearray()
+    while True:
+        line, sep, rest = body.partition(b"\r\n")
+        if not sep:
+            raise ValueError("truncated chunk header")
+        size = int(line.split(b";", 1)[0].strip() or b"0", 16)
+        if size == 0:
+            return bytes(out)
+        if len(rest) < size:
+            raise ValueError("truncated chunk")
+        out += rest[:size]
+        body = rest[size + 2 :]
+
+
+def post(host: str, port: int, token: str, body: bytes, timeout: float) -> bytes:
+    """One HTTP/1.1 POST over a raw socket; the 200 response body, or ``b""``."""
+    head = (
+        f"POST {HOOK_PATH} HTTP/1.1\r\n"
+        f"Host: {host}:{port}\r\n"
+        "Content-Type: application/json\r\n"
+        f"Authorization: Bearer {token}\r\n"
+        f"Content-Length: {len(body)}\r\n"
+        "Connection: close\r\n\r\n"
+    ).encode("ascii")
+    sock = _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM)
+    try:
+        sock.settimeout(timeout)
+        sock.connect((host, port))
+        sock.sendall(head + body)
+        chunks: list[bytes] = []
+        size = 0
+        while True:
+            chunk = sock.recv(65536)
+            if not chunk:
+                break
+            size += len(chunk)
+            if size > MAX_RESPONSE_BYTES + 16_384:
+                return b""
+            chunks.append(chunk)
+    finally:
+        sock.close()
+
+    raw = b"".join(chunks)
+    header, sep, payload = raw.partition(b"\r\n\r\n")
+    if not sep:
+        return b""
+    lines = header.split(b"\r\n")
+    status = lines[0].split()
+    if len(status) < 2 or status[1] != b"200":
+        return b""
+    for line in lines[1:]:
+        name, _, value = line.partition(b":")
+        if name.strip().lower() == b"transfer-encoding" and b"chunked" in value.lower():
+            return _dechunk(payload)
+    return payload
+
+
+def grants_permission(response: dict) -> bool:
+    """Whether a response would approve a tool call on the developer's behalf."""
+    specific = response.get("hookSpecificOutput")
+    if isinstance(specific, dict):
+        if specific.get("permissionDecision") == "allow":
+            return True
+        decision = specific.get("decision")  # PermissionRequest shape
+        if isinstance(decision, dict) and decision.get("behavior") == "allow":
+            return True
+    return response.get("decision") == "approve"  # legacy alias of "allow"
+
+
+def standing_down() -> bool:
+    """Whether the plugin must stay silent because settings hooks already cover this.
+
+    ``plugin.py`` writes these markers at SessionStart when it finds Truthstone's
+    settings-based hooks in a settings file Claude Code reads for this project. Both
+    installs would otherwise handle every event, and the daemon would count each tool
+    call, challenge and completion-gate hold twice.
+    """
+    data = os.environ.get("CLAUDE_PLUGIN_DATA")
+    if not data:
+        return False
+    marks = os.path.join(data, "standdown")
+    if os.path.exists(os.path.join(marks, "user")):
+        return True
+    project = os.environ.get("CLAUDE_PROJECT_DIR")
+    return bool(project) and os.path.exists(os.path.join(marks, project_key(project)))
+
+
+def project_key(project_dir: str) -> str:
+    """A filename for a project directory, shared by writer (plugin.py) and reader."""
+    key = "".join(c if c.isalnum() else "-" for c in project_dir)
+    return "project" + key[-200:]
+
+
+def _timeout(argv: list[str]) -> float:
+    if "--timeout" in argv:
+        try:
+            value = float(argv[argv.index("--timeout") + 1])
+        except (IndexError, ValueError):
+            return DEFAULT_TIMEOUT_S
+        if 0 < value <= 60:
+            return value
+    return DEFAULT_TIMEOUT_S
+
+
+def run(argv: list[str], stdin: object, stdout: object) -> int:
+    """Forward one hook event. Always returns 0: Truthstone never blocks by crashing."""
+    try:
+        if setting("DISABLE").strip().lower() in _TRUE:
+            return 0
+        if standing_down():
+            return 0
+        body = stdin.read(MAX_STDIN_BYTES + 1)
+        if not body or len(body) > MAX_STDIN_BYTES or not body.strip():
+            return 0
+        hs = read_handshake(truthstone_home())
+        target = endpoint_of(hs) if hs else None
+        if target is None:
+            return 0
+        raw = post(*target, body, _timeout(argv))
+        if not raw:
+            return 0
+        response = loads(raw.decode("utf-8"))
+        if not isinstance(response, dict) or not response or grants_permission(response):
+            return 0
+        stdout.write(raw)
+        stdout.flush()
+    except Exception:  # noqa: BLE001 - fail open: any failure means "no decision"
+        return 0
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(run(sys.argv[1:], sys.stdin.buffer, sys.stdout.buffer))

truthstone/adapters/claude_code/install.py

@@ -0,0 +1,268 @@
+"""Install/uninstall Truthstone's hooks in Claude Code settings (SPEC §26).
+
+This is the *settings-based* install, kept as the fallback for setups that cannot use the
+Claude Code plugin (``plugins/truthstone-claude``; see ``docs/CLAUDE-PLUGIN.md``). The two
+must never both handle a session: the plugin stands down wherever these hooks are present
+(``settings_scan``), and ``truthstone install`` / ``doctor`` say so.
+
+Transport split, and why
+------------------------
+* ``SessionStart`` is a **command** hook running the shim with ``--ensure-daemon``. It
+  fires once per session, so ~50ms of process startup is invisible, and it guarantees the
+  daemon is warm before any hot-path hook fires.
+* Everything else is an **http** hook straight to the daemon. Claude Code performs the
+  request itself, so per-tool-call cost is a localhost round trip instead of a Python
+  interpreter start — the difference between meeting and missing SPEC §8.
+
+``PreToolUse``/``PostToolUse`` are matched to tools that can change something: the edit
+tools, both shells, and MCP tools. Read/Grep/Glob would short-circuit to ALLOW anyway, so
+intercepting them would be pure latency for no signal. ``PostToolUseFailure`` is matched
+to the shells: a test run that exits non-zero arrives *only* there, so without it the
+completion gate never sees a failing run (G1).
+
+Idempotent: installing twice leaves one copy; uninstalling removes exactly what was added
+and nothing a human put there.
+"""
+
+from __future__ import annotations
+
+import json
+import shlex
+import sys
+from pathlib import Path
+from typing import Any
+
+from truthstone.adapters.claude_code import settings_scan
+from truthstone.core.config import Settings, get_or_create_token, write_private_text
+
+# Tools that can change something. An anchored regex: unanchored, "Write" would also match
+# TodoWrite, and Claude Code treats any matcher with regex characters as a regex.
+MUTATING_MATCHER = "^(Edit|Write|MultiEdit|NotebookEdit|Bash|PowerShell|mcp__.*)$"
+# Where a failing command's output arrives (exact-name list, no regex needed).
+FAILURE_MATCHER = "Bash|PowerShell"
+
+# Hook timeouts (seconds). Deliberately tight: a wedged daemon must never hold the
+# developer hostage, and the fail-open path is cheap.
+TIMEOUTS = {
+    "SessionStart": 20,
+    "Health": 12,
+    "UserPromptSubmit": 10,
+    "PreToolUse": 5,
+    "PostToolUse": 5,
+    "PostToolUseFailure": 5,
+    "Stop": 10,
+    "SessionEnd": 3,
+}
+
+# Kept for callers and tests that predate the shared module.
+_command_argv = settings_scan.command_argv
+_is_ours_hook = settings_scan.is_ours_hook
+_is_ours = settings_scan.is_ours_group
+
+
+def global_settings_path() -> Path:
+    """User settings — under ``CLAUDE_CONFIG_DIR`` when Claude Code is configured to use one."""
+    return settings_scan.user_settings_path()
+
+
+def project_settings_path(workspace: Path | None = None) -> Path:
+    # settings.local.json is gitignored by Claude Code convention, which matters here
+    # because the config carries a local auth token.
+    return (workspace or Path.cwd()) / ".claude" / "settings.local.json"
+
+
+def settings_path(
+    project: bool = False, global_: bool = False, workspace: Path | None = None
+) -> Path:
+    """Resolve an install target, rejecting ambiguous scope flags."""
+    if project and global_:
+        raise ValueError("choose exactly one of --project or --global")
+    return project_settings_path(workspace) if project else global_settings_path()
+
+
+def _http_hook(url: str, token: str, timeout: int) -> dict[str, Any]:
+    return {
+        "type": "http",
+        "url": url,
+        "headers": {
+            "Authorization": f"Bearer {token}",
+            # Doubles as the ownership marker for _is_ours() and as a label for any
+            # human who opens settings.json and wonders what this entry is.
+            settings_scan.OWNERSHIP_HEADER: "1",
+        },
+        "timeout": timeout,
+    }
+
+
+def _command_hook(
+    argv: list[str], timeout: int, status_message: str | None = None
+) -> dict[str, Any]:
+    """Build a Claude Code command hook from argv.
+
+    Claude Code's command-hook schema accepts one shell command string, not a separate
+    executable plus an ``args`` array.  ``shlex.join`` keeps paths and other arguments
+    correctly quoted while preserving the exact argv we intend to run.
+    """
+    hook: dict[str, Any] = {
+        "type": "command",
+        "command": shlex.join(argv),
+        "timeout": timeout,
+    }
+    if status_message is not None:
+        hook["statusMessage"] = status_message
+    return hook
+
+
+def _shim_argv(py: str, flag: str) -> list[str]:
+    # `-P`: never put the working directory on sys.path. Hooks run inside the developer's
+    # repository, and `python -m` would otherwise import a repository file named, say,
+    # `json.py` in place of the standard library — code execution by opening a folder.
+    return [py, "-P", "-m", settings_scan.SHIM_MODULE, flag]
+
+
+def build_hook_config(settings: Settings | None = None, python_exe: str | None = None) -> dict[str, Any]:
+    settings = settings or Settings.load()
+    token = get_or_create_token()
+    url = f"{settings.daemon.base_url}/hook/claude-code"
+    py = python_exe or sys.executable
+
+    return {
+        "SessionStart": [
+            {
+                "matcher": "startup|resume|clear",
+                "hooks": [
+                    _command_hook(
+                        _shim_argv(py, "--ensure-daemon"),
+                        TIMEOUTS["SessionStart"],
+                        "Truthstone: warming repository index",
+                    )
+                ],
+            }
+        ],
+        "UserPromptSubmit": [
+            {
+                "hooks": [
+                    # Health check first: detect a dead daemon, try once to revive it,
+                    # and tell the developer if it cannot be. Silent fail-open would
+                    # leave them believing they are guarded when they are not.
+                    # Once per prompt, not per tool call, so the cost is invisible.
+                    _command_hook(_shim_argv(py, "--health"), TIMEOUTS["Health"]),
+                    _http_hook(url, token, TIMEOUTS["UserPromptSubmit"]),
+                ]
+            }
+        ],
+        "PreToolUse": [
+            {"matcher": MUTATING_MATCHER, "hooks": [_http_hook(url, token, TIMEOUTS["PreToolUse"])]}
+        ],
+        "PostToolUse": [
+            {"matcher": MUTATING_MATCHER, "hooks": [_http_hook(url, token, TIMEOUTS["PostToolUse"])]}
+        ],
+        "PostToolUseFailure": [
+            {
+                "matcher": FAILURE_MATCHER,
+                "hooks": [_http_hook(url, token, TIMEOUTS["PostToolUseFailure"])],
+            }
+        ],
+        "Stop": [{"hooks": [_http_hook(url, token, TIMEOUTS["Stop"])]}],
+        "SessionEnd": [{"hooks": [_http_hook(url, token, TIMEOUTS["SessionEnd"])]}],
+    }
+
+
+def _remove_ours_from_group(group: Any) -> Any:
+    """Remove only our hooks, preserving a user's hooks in a mixed group.
+
+    Claude groups can contain multiple hook entries. Treating the group as the ownership
+    unit would delete an unrelated hook whenever a developer placed it beside ours.
+    ``None`` means the group became empty and may be removed by the caller.
+    """
+    if not isinstance(group, dict):
+        return group
+    hooks = group.get("hooks")
+    if not isinstance(hooks, list):
+        return group
+    remaining = [hook for hook in hooks if not _is_ours_hook(hook)]
+    if len(remaining) == len(hooks):
+        return group
+    if not remaining:
+        return None
+    out = dict(group)
+    out["hooks"] = remaining
+    return out
+
+
+def _load(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        raise RuntimeError(f"{path} is not valid JSON; refusing to overwrite it ({exc})") from exc
+    return data if isinstance(data, dict) else {}
+
+
+def _save(path: Path, data: dict[str, Any]) -> None:
+    # Truthstone's bearer token is embedded in the HTTP hook headers. Both project-local
+    # and global Claude settings are therefore credential-bearing files.
+    write_private_text(path, json.dumps(data, indent=2) + "\n")
+
+
+def merge_hooks(existing: dict[str, Any], new_hooks: dict[str, Any]) -> dict[str, Any]:
+    """Add our groups, replacing any previous Truthstone groups, preserving all others."""
+    out = dict(existing)
+    hooks: dict[str, Any] = dict(out.get("hooks") or {})
+
+    for event, groups in new_hooks.items():
+        current = []
+        for group in hooks.get(event) or []:
+            cleaned = _remove_ours_from_group(group)
+            if cleaned is not None:
+                current.append(cleaned)
+        hooks[event] = current + list(groups)
+
+    out["hooks"] = hooks
+    return out
+
+
+def strip_hooks(existing: dict[str, Any]) -> dict[str, Any]:
+    out = dict(existing)
+    hooks: dict[str, Any] = dict(out.get("hooks") or {})
+    for event in list(hooks):
+        remaining = []
+        for group in hooks.get(event) or []:
+            cleaned = _remove_ours_from_group(group)
+            if cleaned is not None:
+                remaining.append(cleaned)
+        if remaining:
+            hooks[event] = remaining
+        else:
+            hooks.pop(event)
+    if hooks:
+        out["hooks"] = hooks
+    else:
+        out.pop("hooks", None)
+    return out
+
+
+def install(
+    path: Path, settings: Settings | None = None, dry_run: bool = False, python_exe: str | None = None
+) -> tuple[dict[str, Any], bool]:
+    """Returns (resulting settings, changed)."""
+    existing = _load(path)
+    merged = merge_hooks(existing, build_hook_config(settings, python_exe))
+    changed = merged != existing
+    if changed and not dry_run:
+        _save(path, merged)
+    return merged, changed
+
+
+def uninstall(path: Path, dry_run: bool = False) -> tuple[dict[str, Any], bool]:
+    existing = _load(path)
+    stripped = strip_hooks(existing)
+    changed = stripped != existing
+    if changed and not dry_run:
+        _save(path, stripped)
+    return stripped, changed
+
+
+def is_installed(path: Path) -> bool:
+    return settings_scan.hooks_installed(path)