credence-governor-claude-code 0.1.0__tar.gz

credence_governor_claude_code-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: credence-governor-claude-code
+Version: 0.1.0
+Summary: Claude Code adapter for credence-governor — a thin PreToolUse hook that Bayesian-governs tool calls (proceed/block/ask) via the governor daemon.
+Author: Guy Freeman
+License-Expression: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/gfrmin/credence-governor
+Project-URL: Repository, https://github.com/gfrmin/credence-governor
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: credence-governor-core; extra == "dev"
+
+# credence-governor — Claude Code adapter
+
+A thin **Claude Code** adapter for [credence-governor](../../README.md): a
+`PreToolUse` subprocess hook that Bayesian-governs tool calls (`proceed` /
+`block` / `ask`) by asking the governor daemon, which runs the one EU-max reasoner
+over the Credence engine.
+
+The adapter carries **no probabilistic code and no feature logic**. Its only job is
+to translate Claude Code's native hook events into the harness-neutral wire shape and
+render the daemon's decision. Feature & taint extraction is server-side in the daemon
+(single-sourced — DRY).
+
+## How it works
+
+```
+Claude Code  ──PreToolUse JSON on stdin──▶  credence-governor-claude-code (this hook)
+                                                  │  transcript_path JSONL → neutral messages
+                                                  ▼  POST /decide  (tool, input, session)
+                                            governor daemon (credence-governor-core)
+                                                  │  server-side feature/taint extraction
+                                                  ▼  one EU-max decision over the skin wire
+                                            credence-skin engine (Julia)
+        ◀──permissionDecision JSON on stdout──────┘
+```
+
+- **`transcript.py`** — replays the session transcript (`transcript_path`) into the
+  neutral `messages` list the extractors expect (`user` / `assistant` / `tool_call` /
+  `tool_result`). The proposed call — already persisted to the transcript before
+  `PreToolUse` fires — is excluded so loop counts see priors only. Sidechain
+  (subagent) turns are excluded by default.
+- **`client.py`** — `POST /decide` (stdlib `urllib`).
+- **`effectors.py`** — maps the governor action to a `PreToolUse` decision.
+- **`hook.py`** — the entry point (`credence-governor-claude-code`).
+
+## Overlay semantics (the governor never weakens the host)
+
+| governor action | Claude Code decision | effect |
+|---|---|---|
+| `proceed` | *(nothing emitted)* | defer to Claude Code's own permission rules |
+| `block`   | `deny` + reason | refuse regardless of native rules |
+| `ask`     | `ask` + reason | force a user prompt even if native rules would auto-allow |
+
+`permissionDecision: "allow"` is **never** emitted — that would bypass Claude Code's
+own safety prompts. The governor can only *add* friction, not remove it.
+
+**Fail-open is absolute.** A malformed event, a daemon that is down, a timeout, or any
+error prints nothing and exits 0 — the call proceeds through Claude Code's normal
+flow. Run with `CREDENCE_GOVERNOR_DEBUG=1` to log decisions/failures to stderr.
+
+## Capability boundary (Claude Code, hook transport)
+
+| Dimension | Supported |
+|---|---|
+| Waste gating (loops / repetition) | ✅ |
+| Safety (taint-flow / exfil / injected imperatives) | ✅ |
+| Routing / model selection | ❌ (no model-resolve hook) |
+| Cost / dollars-saved | ◑ observe-only |
+| Online ask-response learning | ◌ deferred — see below |
+
+v1 gates **`PreToolUse` only**. `PostToolUse` / `UserPromptSubmit` are intentionally
+not wired: neither carries a clean approval label, and treating "the call completed"
+as belief evidence would be a second learning path (a constitutional violation), not
+just a weak one. The warm-trained brain governs; the daemon logs every decision.
+Online ask-learning on Claude Code (inferring the user's reply from the next
+transcript turn) is an open design question, deferred.
+
+## Install
+
+**1. Start the daemon** — every adapter shares one local daemon; see the
+[core README](../../packages/governor_core) or the
+[repo quickstart](../../README.md#install). In short, from a clone of the repo:
+
+```bash
+pip install -e packages/governor_core -e ~/git/credence/apps/skin/clients/python
+CREDENCE_ENGINE_DIR=~/git/credence credence-governor-daemon   # or CREDENCE_SKIN_COMMAND="docker run … credence-skin@<digest>"
+```
+
+**2. Register the hook** — two ways; both end at the same `PreToolUse` hook.
+
+### Method A — as a Claude Code plugin (recommended; no `pip install`)
+
+The hook is pure stdlib, so the plugin **bundles** it and runs it via
+`${CLAUDE_PLUGIN_ROOT}` — there's nothing to `pip install`. Inside Claude Code:
+
+```
+/plugin marketplace add gfrmin/credence-governor
+/plugin install credence-governor-claude-code@credence-governor
+```
+
+The hook is active in new sessions (run `/reload-plugins` to pick it up in the current
+one). Manage or remove it from the `/plugin` menu. The plugin reuses the *same*
+`credence_governor_claude_code` package this directory ships — `plugin_hook.py` is a
+thin launcher that puts it on `sys.path` and calls the same entry point the pip console
+script uses (one implementation, two install paths). Manifests:
+[`.claude-plugin/plugin.json`](.claude-plugin/plugin.json),
+[`hooks/hooks.json`](hooks/hooks.json), and the repo-root
+[`.claude-plugin/marketplace.json`](../../.claude-plugin/marketplace.json).
+
+### Method B — as a pip package + settings hook
+
+If you'd rather manage it with pip (or script the registration):
+
+```bash
+pip install -e adapters/claude-code        # not yet on PyPI; once published: pip install credence-governor-claude-code
+credence-governor-cc-install               # → ~/.claude/settings.json  (idempotent)
+#   --project   → ./.claude/settings.json   ·   --uninstall → remove
+```
+
+Either way the hook has **no runtime dependencies** (pure stdlib); `credence-governor-core`
+is needed only for the daemon and the parity test. Static config example:
+[`settings.example.json`](settings.example.json).
+
+### Environment
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `CREDENCE_GOVERNOR_URL` | `http://127.0.0.1:8787` | governor daemon base URL |
+| `CREDENCE_GOVERNOR_TIMEOUT` | `5.0` | per-call `/decide` timeout (s); on timeout → fail open |
+| `CREDENCE_GOVERNOR_PROFILE` | *(none)* | utility profile passed to the daemon (e.g. `flow-guard`) |
+| `CREDENCE_GOVERNOR_DEBUG` | *(off)* | log decisions/failures to stderr |
+
+## Tests
+
+```bash
+python -m pytest tests -q
+```
+
+Pure-stdlib at runtime; the round-trip parity test (`test_roundtrip.py`) imports
+`credence-governor-core` to assert the wire payload deserialises through the daemon's
+`event_and_session_from_payload` to the Session the extractors expect — it is skipped
+if the core isn't importable.

credence_governor_claude_code-0.1.0/README.md

@@ -0,0 +1,131 @@
+# credence-governor — Claude Code adapter
+
+A thin **Claude Code** adapter for [credence-governor](../../README.md): a
+`PreToolUse` subprocess hook that Bayesian-governs tool calls (`proceed` /
+`block` / `ask`) by asking the governor daemon, which runs the one EU-max reasoner
+over the Credence engine.
+
+The adapter carries **no probabilistic code and no feature logic**. Its only job is
+to translate Claude Code's native hook events into the harness-neutral wire shape and
+render the daemon's decision. Feature & taint extraction is server-side in the daemon
+(single-sourced — DRY).
+
+## How it works
+
+```
+Claude Code  ──PreToolUse JSON on stdin──▶  credence-governor-claude-code (this hook)
+                                                  │  transcript_path JSONL → neutral messages
+                                                  ▼  POST /decide  (tool, input, session)
+                                            governor daemon (credence-governor-core)
+                                                  │  server-side feature/taint extraction
+                                                  ▼  one EU-max decision over the skin wire
+                                            credence-skin engine (Julia)
+        ◀──permissionDecision JSON on stdout──────┘
+```
+
+- **`transcript.py`** — replays the session transcript (`transcript_path`) into the
+  neutral `messages` list the extractors expect (`user` / `assistant` / `tool_call` /
+  `tool_result`). The proposed call — already persisted to the transcript before
+  `PreToolUse` fires — is excluded so loop counts see priors only. Sidechain
+  (subagent) turns are excluded by default.
+- **`client.py`** — `POST /decide` (stdlib `urllib`).
+- **`effectors.py`** — maps the governor action to a `PreToolUse` decision.
+- **`hook.py`** — the entry point (`credence-governor-claude-code`).
+
+## Overlay semantics (the governor never weakens the host)
+
+| governor action | Claude Code decision | effect |
+|---|---|---|
+| `proceed` | *(nothing emitted)* | defer to Claude Code's own permission rules |
+| `block`   | `deny` + reason | refuse regardless of native rules |
+| `ask`     | `ask` + reason | force a user prompt even if native rules would auto-allow |
+
+`permissionDecision: "allow"` is **never** emitted — that would bypass Claude Code's
+own safety prompts. The governor can only *add* friction, not remove it.
+
+**Fail-open is absolute.** A malformed event, a daemon that is down, a timeout, or any
+error prints nothing and exits 0 — the call proceeds through Claude Code's normal
+flow. Run with `CREDENCE_GOVERNOR_DEBUG=1` to log decisions/failures to stderr.
+
+## Capability boundary (Claude Code, hook transport)
+
+| Dimension | Supported |
+|---|---|
+| Waste gating (loops / repetition) | ✅ |
+| Safety (taint-flow / exfil / injected imperatives) | ✅ |
+| Routing / model selection | ❌ (no model-resolve hook) |
+| Cost / dollars-saved | ◑ observe-only |
+| Online ask-response learning | ◌ deferred — see below |
+
+v1 gates **`PreToolUse` only**. `PostToolUse` / `UserPromptSubmit` are intentionally
+not wired: neither carries a clean approval label, and treating "the call completed"
+as belief evidence would be a second learning path (a constitutional violation), not
+just a weak one. The warm-trained brain governs; the daemon logs every decision.
+Online ask-learning on Claude Code (inferring the user's reply from the next
+transcript turn) is an open design question, deferred.
+
+## Install
+
+**1. Start the daemon** — every adapter shares one local daemon; see the
+[core README](../../packages/governor_core) or the
+[repo quickstart](../../README.md#install). In short, from a clone of the repo:
+
+```bash
+pip install -e packages/governor_core -e ~/git/credence/apps/skin/clients/python
+CREDENCE_ENGINE_DIR=~/git/credence credence-governor-daemon   # or CREDENCE_SKIN_COMMAND="docker run … credence-skin@<digest>"
+```
+
+**2. Register the hook** — two ways; both end at the same `PreToolUse` hook.
+
+### Method A — as a Claude Code plugin (recommended; no `pip install`)
+
+The hook is pure stdlib, so the plugin **bundles** it and runs it via
+`${CLAUDE_PLUGIN_ROOT}` — there's nothing to `pip install`. Inside Claude Code:
+
+```
+/plugin marketplace add gfrmin/credence-governor
+/plugin install credence-governor-claude-code@credence-governor
+```
+
+The hook is active in new sessions (run `/reload-plugins` to pick it up in the current
+one). Manage or remove it from the `/plugin` menu. The plugin reuses the *same*
+`credence_governor_claude_code` package this directory ships — `plugin_hook.py` is a
+thin launcher that puts it on `sys.path` and calls the same entry point the pip console
+script uses (one implementation, two install paths). Manifests:
+[`.claude-plugin/plugin.json`](.claude-plugin/plugin.json),
+[`hooks/hooks.json`](hooks/hooks.json), and the repo-root
+[`.claude-plugin/marketplace.json`](../../.claude-plugin/marketplace.json).
+
+### Method B — as a pip package + settings hook
+
+If you'd rather manage it with pip (or script the registration):
+
+```bash
+pip install -e adapters/claude-code        # not yet on PyPI; once published: pip install credence-governor-claude-code
+credence-governor-cc-install               # → ~/.claude/settings.json  (idempotent)
+#   --project   → ./.claude/settings.json   ·   --uninstall → remove
+```
+
+Either way the hook has **no runtime dependencies** (pure stdlib); `credence-governor-core`
+is needed only for the daemon and the parity test. Static config example:
+[`settings.example.json`](settings.example.json).
+
+### Environment
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `CREDENCE_GOVERNOR_URL` | `http://127.0.0.1:8787` | governor daemon base URL |
+| `CREDENCE_GOVERNOR_TIMEOUT` | `5.0` | per-call `/decide` timeout (s); on timeout → fail open |
+| `CREDENCE_GOVERNOR_PROFILE` | *(none)* | utility profile passed to the daemon (e.g. `flow-guard`) |
+| `CREDENCE_GOVERNOR_DEBUG` | *(off)* | log decisions/failures to stderr |
+
+## Tests
+
+```bash
+python -m pytest tests -q
+```
+
+Pure-stdlib at runtime; the round-trip parity test (`test_roundtrip.py`) imports
+`credence-governor-core` to assert the wire payload deserialises through the daemon's
+`event_and_session_from_payload` to the Session the extractors expect — it is skipped
+if the core isn't importable.

credence_governor_claude_code-0.1.0/credence_governor_claude_code/__init__.py

@@ -0,0 +1,15 @@
+"""credence-governor-claude-code — the Claude Code adapter.
+
+A thin subprocess-hook shim: it translates Claude Code's native PreToolUse events
+into the harness-neutral wire shape and asks the governor daemon (credence-governor-core)
+for a proceed/block/ask decision. Carries no probabilistic code and no feature logic
+— extraction is server-side in the daemon (DRY). The adapter's only job is
+native-events -> neutral schema (+ render the decision).
+"""
+
+from __future__ import annotations
+
+from .hook import handle, main
+from .transcript import messages_from_transcript, session_from_hook
+
+__all__ = ["main", "handle", "session_from_hook", "messages_from_transcript"]

credence_governor_claude_code-0.1.0/credence_governor_claude_code/client.py

@@ -0,0 +1,38 @@
+"""client.py — POST the neutral event to the governor daemon's `/decide`.
+
+Zero-dependency (urllib): the hook is a short-lived subprocess that must start fast
+and never block a tool call for long. The caller treats every failure as fail-open.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.request
+from typing import Any
+
+DEFAULT_URL = "http://127.0.0.1:8787"
+DEFAULT_TIMEOUT = 5.0
+
+
+def base_url() -> str:
+    return os.environ.get("CREDENCE_GOVERNOR_URL", DEFAULT_URL)
+
+
+def timeout_s() -> float:
+    try:
+        return float(os.environ.get("CREDENCE_GOVERNOR_TIMEOUT", DEFAULT_TIMEOUT))
+    except (TypeError, ValueError):
+        return DEFAULT_TIMEOUT
+
+
+def decide(payload: dict[str, Any]) -> dict[str, Any]:
+    """POST /decide and return the daemon's JSON ({action, features, event_id}).
+    Raises on transport/HTTP error — the caller fails open."""
+    url = base_url().rstrip("/") + "/decide"
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        url, data=data, headers={"content-type": "application/json"}, method="POST"
+    )
+    with urllib.request.urlopen(req, timeout=timeout_s()) as resp:  # noqa: S310 (localhost daemon)
+        return json.loads(resp.read().decode("utf-8"))

credence_governor_claude_code-0.1.0/credence_governor_claude_code/effectors.py

@@ -0,0 +1,41 @@
+"""effectors.py — a governor action -> a Claude Code PreToolUse decision.
+
+The governor is an OVERLAY on Claude Code's native permission system, so it may only
+ever ADD restriction, never remove it:
+
+  proceed -> None        (emit nothing: defer to Claude Code's own permission rules)
+  block   -> deny        (refuse regardless of native rules)
+  ask     -> ask         (force a user prompt even if native rules would auto-allow)
+
+We deliberately never emit permissionDecision "allow": that would bypass Claude
+Code's native safety prompts, i.e. the governance layer weakening the host. A
+returned None means "print nothing", which leaves the call to the normal flow.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+_DECISION = {"proceed": None, "block": "deny", "ask": "ask"}
+
+
+def _reason(action: str, tool_name: str) -> str:
+    tool = tool_name or "this tool"
+    if action == "block":
+        return f"credence-governor refused `{tool}`: low expected utility under the current belief (likely a loop or unsafe action)."
+    return f"credence-governor wants confirmation before `{tool}` runs."
+
+
+def pretooluse_output(action: str, tool_name: str = "") -> dict[str, Any] | None:
+    """The JSON to print on stdout for a PreToolUse hook, or None to print nothing
+    (proceed / unknown action -> defer to Claude Code)."""
+    decision = _DECISION.get(action)
+    if decision is None:
+        return None
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": decision,
+            "permissionDecisionReason": _reason(action, tool_name),
+        }
+    }

credence_governor_claude_code-0.1.0/credence_governor_claude_code/hook.py

@@ -0,0 +1,72 @@
+"""hook.py — the Claude Code subprocess-hook entry point.
+
+Registered as a `PreToolUse` hook (see install.py / settings.example.json). On each
+proposed tool call Claude Code pipes a JSON event on stdin; we translate it to the
+neutral wire shape, ask the governor daemon for a decision, and print a PreToolUse
+permission decision on stdout.
+
+v1 gates PreToolUse only. PostToolUse / UserPromptSubmit are intentionally NOT wired:
+neither carries a clean approval label, and recording "the call completed" as belief
+evidence would be a second learning path (Invariant 1) — wrong, not just weak. Online
+ask-learning on Claude Code is an open design question (transcript-inference), so v1
+is observation-only: the warm-trained brain governs, the daemon logs every decision.
+
+Fail-open is absolute: any malformed input, daemon-down, timeout, or non-PreToolUse
+event prints nothing and exits 0, leaving the call to Claude Code's normal flow. The
+governor can add friction (deny / ask) but never removes the host's own safety.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+from . import client, effectors, transcript
+
+
+def _debug(msg: str) -> None:
+    if os.environ.get("CREDENCE_GOVERNOR_DEBUG"):
+        sys.stderr.write(f"credence-governor: {msg}\n")
+
+
+def _read_stdin() -> dict[str, Any]:
+    raw = sys.stdin.read()
+    return json.loads(raw) if raw and raw.strip() else {}
+
+
+def handle(hook_input: dict[str, Any]) -> dict[str, Any] | None:
+    """Pure core: a PreToolUse hook payload -> the stdout JSON (or None to defer).
+    Raises on daemon failure so `main` can fail open around it."""
+    if (hook_input.get("hook_event_name") or "") != "PreToolUse":
+        return None  # v1 gates only PreToolUse
+    payload = transcript.session_from_hook(hook_input)
+    profile = os.environ.get("CREDENCE_GOVERNOR_PROFILE")
+    if profile:
+        payload["profile"] = profile
+    result = client.decide(payload)
+    action = str(result.get("action") or "proceed")
+    _debug(f"{payload['tool_name']} -> {action} ({result.get('features')})")
+    return effectors.pretooluse_output(action, payload["tool_name"])
+
+
+def main() -> int:
+    try:
+        hook_input = _read_stdin()
+    except (ValueError, OSError) as err:
+        _debug(f"unreadable stdin (failing open): {err}")
+        return 0
+    try:
+        out = handle(hook_input)
+    except Exception as err:  # fail-open: daemon down, timeout, anything
+        _debug(f"decision error (failing open): {err}")
+        return 0
+    if out is not None:
+        sys.stdout.write(json.dumps(out))
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

credence_governor_claude_code-0.1.0/credence_governor_claude_code/install.py

@@ -0,0 +1,92 @@
+"""install.py — idempotently register (or remove) the PreToolUse hook in a Claude
+Code settings.json.
+
+    credence-governor-cc-install            # -> ~/.claude/settings.json
+    credence-governor-cc-install --project  # -> ./.claude/settings.json
+    credence-governor-cc-install --path X    # -> X
+    credence-governor-cc-install --uninstall
+
+The hook command defaults to the installed console script `credence-governor-claude-code`.
+Existing settings are preserved; we only touch hooks.PreToolUse, and dedupe by command.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Any
+
+HOOK_COMMAND = "credence-governor-claude-code"
+_MATCHER = "*"  # all tools
+
+
+def _load(path: str) -> dict[str, Any]:
+    if not os.path.exists(path):
+        return {}
+    with open(path, encoding="utf-8") as fh:
+        text = fh.read().strip()
+    return json.loads(text) if text else {}
+
+
+def _save(path: str, data: dict[str, Any]) -> None:
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(data, fh, indent=2)
+        fh.write("\n")
+
+
+def _command_present(entries: list[dict[str, Any]], command: str) -> bool:
+    for entry in entries:
+        for h in entry.get("hooks", []):
+            if h.get("type") == "command" and h.get("command") == command:
+                return True
+    return False
+
+
+def add(settings: dict[str, Any], command: str = HOOK_COMMAND) -> dict[str, Any]:
+    hooks = settings.setdefault("hooks", {})
+    pre = hooks.setdefault("PreToolUse", [])
+    if not _command_present(pre, command):
+        pre.append({"matcher": _MATCHER, "hooks": [{"type": "command", "command": command}]})
+    return settings
+
+
+def remove(settings: dict[str, Any], command: str = HOOK_COMMAND) -> dict[str, Any]:
+    pre = settings.get("hooks", {}).get("PreToolUse", [])
+    for entry in pre:
+        entry["hooks"] = [
+            h for h in entry.get("hooks", []) if not (h.get("type") == "command" and h.get("command") == command)
+        ]
+    settings.get("hooks", {})["PreToolUse"] = [e for e in pre if e.get("hooks")]
+    return settings
+
+
+def _target(args: argparse.Namespace) -> str:
+    if args.path:
+        return args.path
+    if args.project:
+        return os.path.join(os.getcwd(), ".claude", "settings.json")
+    return os.path.join(os.path.expanduser("~"), ".claude", "settings.json")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Register the credence-governor PreToolUse hook.")
+    ap.add_argument("--project", action="store_true", help="install into ./.claude/settings.json")
+    ap.add_argument("--path", help="explicit settings.json path")
+    ap.add_argument("--command", default=HOOK_COMMAND, help="hook command to register")
+    ap.add_argument("--uninstall", action="store_true", help="remove the hook instead")
+    args = ap.parse_args()
+
+    path = _target(args)
+    settings = _load(path)
+    settings = remove(settings, args.command) if args.uninstall else add(settings, args.command)
+    _save(path, settings)
+    verb = "removed from" if args.uninstall else "installed into"
+    sys.stdout.write(f"credence-governor PreToolUse hook {verb} {path}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

credence_governor_claude_code-0.1.0/credence_governor_claude_code/transcript.py

@@ -0,0 +1,175 @@
+"""transcript.py — Claude Code transcript JSONL -> the neutral wire `session`.
+
+The adapter's whole job is native-events -> the harness-neutral schema the daemon
+extracts from (see ../../packages/governor_core/credence_governor_core/schema.py).
+A Claude Code PreToolUse hook hands us `transcript_path` (a JSONL of the session so
+far) + the proposed `tool_name`/`tool_input`. We replay the transcript into the
+`messages` list the server-side extractors expect:
+
+  user        — a real user prompt (drives time-since-user)
+  assistant   — model prose (kept only as a turn marker)
+  tool_call   — an assistant `tool_use` block (drives repetition / parent-tool / loops)
+  tool_result — a user `tool_result` block (the taint SOURCE for safety)
+
+Two correctness points the extractors depend on:
+  • the PROPOSED call must NOT appear in `messages` (repetition/identical_call count
+    PRIOR calls only). Claude Code persists the assistant `tool_use` to the transcript
+    *before* firing PreToolUse, so we drop the trailing tool_call iff it matches.
+  • sidechain (subagent) turns are excluded by default — they would pollute the main
+    thread's loop counts with a subagent's unrelated calls.
+
+Pure stdlib, no governor-core import: the hook must start fast and fail open. The
+shared contract is the JSON key set, not shared code.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Iterable
+
+
+def _iter_jsonl(path: str) -> Iterable[dict[str, Any]]:
+    with open(path, encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except (ValueError, TypeError):
+                continue
+            if isinstance(rec, dict):
+                yield rec
+
+
+def _blocks(content: Any) -> list[Any]:
+    """Normalise a message `content` to a list of blocks (a bare string is one
+    text block)."""
+    if isinstance(content, str):
+        return [{"type": "text", "text": content}]
+    if isinstance(content, list):
+        return content
+    return []
+
+
+def result_to_text(content: Any) -> str:
+    """Flatten a tool_result's content to plain text so taint tokens read cleanly.
+    Claude Code tool_result content is a string or a list of `{type:text,text}` (and
+    occasionally nested `{content:[...]}`)."""
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for b in content:
+            if isinstance(b, dict):
+                if b.get("type") == "text" and isinstance(b.get("text"), str):
+                    parts.append(b["text"])
+                elif "content" in b:
+                    parts.append(result_to_text(b["content"]))
+            elif isinstance(b, str):
+                parts.append(b)
+        return "\n".join(p for p in parts if p)
+    try:
+        return json.dumps(content)
+    except (TypeError, ValueError):
+        return str(content)
+
+
+def _has_text(blocks: list[Any]) -> bool:
+    for b in blocks:
+        if isinstance(b, dict) and b.get("type") == "text" and (b.get("text") or "").strip():
+            return True
+        if isinstance(b, str) and b.strip():
+            return True
+    return False
+
+
+def messages_from_transcript(path: str, include_sidechain: bool = False) -> list[dict[str, Any]]:
+    """Replay a Claude Code transcript into neutral wire messages, in order."""
+    out: list[dict[str, Any]] = []
+    for rec in _iter_jsonl(path):
+        if rec.get("type") not in ("user", "assistant"):
+            continue
+        if rec.get("isSidechain") and not include_sidechain:
+            continue
+        ts = rec.get("timestamp")
+        message = rec.get("message") or {}
+        role = message.get("role")
+        blocks = _blocks(message.get("content"))
+
+        if role == "assistant":
+            for b in blocks:
+                if not isinstance(b, dict):
+                    continue
+                if b.get("type") == "tool_use":
+                    out.append(
+                        {
+                            "role": "tool_call",
+                            "tool_name": b.get("name"),
+                            "input": b.get("input"),
+                            "timestamp": ts,
+                        }
+                    )
+                elif b.get("type") == "text" and (b.get("text") or "").strip():
+                    out.append({"role": "assistant", "timestamp": ts})
+        elif role == "user":
+            for b in blocks:
+                if isinstance(b, dict) and b.get("type") == "tool_result":
+                    out.append(
+                        {"role": "tool_result", "result": result_to_text(b.get("content")), "timestamp": ts}
+                    )
+            # A user record carrying tool_result blocks is a tool delivery, not a
+            # human turn; only emit a user message when there is genuine user text.
+            if _has_text(blocks):
+                out.append({"role": "user", "timestamp": ts})
+    return out
+
+
+def drop_proposed(messages: list[dict[str, Any]], tool_name: str, tool_input: Any) -> list[dict[str, Any]]:
+    """Remove the trailing tool_call iff it is the proposed call (already persisted
+    to the transcript by the time PreToolUse fires). Only the LAST tool_call is a
+    candidate; if it doesn't match (transcript not yet flushed) nothing is dropped."""
+    for i in range(len(messages) - 1, -1, -1):
+        if messages[i].get("role") == "tool_call":
+            if messages[i].get("tool_name") == tool_name and messages[i].get("input") == tool_input:
+                del messages[i]
+            break
+    return messages
+
+
+def find_project_root(cwd: str) -> str:
+    """Nearest enclosing dir containing a `.git` (file or dir), or "" if none —
+    feeds the working-directory-relative feature (project-root/subdir/outside)."""
+    cur = os.path.abspath(cwd) if cwd else ""
+    while cur and cur != os.path.dirname(cur):
+        if os.path.exists(os.path.join(cur, ".git")):
+            return cur
+        cur = os.path.dirname(cur)
+    return ""
+
+
+def session_from_hook(hook_input: dict[str, Any]) -> dict[str, Any]:
+    """A PreToolUse hook payload -> the `/decide` request body the daemon extracts
+    from (neutral AgentToolEvent + Session, snake_case keys)."""
+    cwd = hook_input.get("cwd") or ""
+    transcript = hook_input.get("transcript_path") or ""
+    tool_name = hook_input.get("tool_name") or ""
+    tool_input = hook_input.get("tool_input")
+
+    messages: list[dict[str, Any]] = []
+    if transcript and os.path.exists(transcript):
+        messages = messages_from_transcript(transcript)
+        drop_proposed(messages, tool_name, tool_input)
+
+    return {
+        "tool_name": tool_name,
+        "input": tool_input,
+        "session": {
+            "cwd": cwd,
+            "project_root": find_project_root(cwd),
+            "messages": messages,
+        },
+    }

credence_governor_claude_code-0.1.0/credence_governor_claude_code.egg-info/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: credence-governor-claude-code
+Version: 0.1.0
+Summary: Claude Code adapter for credence-governor — a thin PreToolUse hook that Bayesian-governs tool calls (proceed/block/ask) via the governor daemon.
+Author: Guy Freeman
+License-Expression: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/gfrmin/credence-governor
+Project-URL: Repository, https://github.com/gfrmin/credence-governor
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: credence-governor-core; extra == "dev"
+
+# credence-governor — Claude Code adapter
+
+A thin **Claude Code** adapter for [credence-governor](../../README.md): a
+`PreToolUse` subprocess hook that Bayesian-governs tool calls (`proceed` /
+`block` / `ask`) by asking the governor daemon, which runs the one EU-max reasoner
+over the Credence engine.
+
+The adapter carries **no probabilistic code and no feature logic**. Its only job is
+to translate Claude Code's native hook events into the harness-neutral wire shape and
+render the daemon's decision. Feature & taint extraction is server-side in the daemon
+(single-sourced — DRY).
+
+## How it works
+
+```
+Claude Code  ──PreToolUse JSON on stdin──▶  credence-governor-claude-code (this hook)
+                                                  │  transcript_path JSONL → neutral messages
+                                                  ▼  POST /decide  (tool, input, session)
+                                            governor daemon (credence-governor-core)
+                                                  │  server-side feature/taint extraction
+                                                  ▼  one EU-max decision over the skin wire
+                                            credence-skin engine (Julia)
+        ◀──permissionDecision JSON on stdout──────┘
+```
+
+- **`transcript.py`** — replays the session transcript (`transcript_path`) into the
+  neutral `messages` list the extractors expect (`user` / `assistant` / `tool_call` /
+  `tool_result`). The proposed call — already persisted to the transcript before
+  `PreToolUse` fires — is excluded so loop counts see priors only. Sidechain
+  (subagent) turns are excluded by default.
+- **`client.py`** — `POST /decide` (stdlib `urllib`).
+- **`effectors.py`** — maps the governor action to a `PreToolUse` decision.
+- **`hook.py`** — the entry point (`credence-governor-claude-code`).
+
+## Overlay semantics (the governor never weakens the host)
+
+| governor action | Claude Code decision | effect |
+|---|---|---|
+| `proceed` | *(nothing emitted)* | defer to Claude Code's own permission rules |
+| `block`   | `deny` + reason | refuse regardless of native rules |
+| `ask`     | `ask` + reason | force a user prompt even if native rules would auto-allow |
+
+`permissionDecision: "allow"` is **never** emitted — that would bypass Claude Code's
+own safety prompts. The governor can only *add* friction, not remove it.
+
+**Fail-open is absolute.** A malformed event, a daemon that is down, a timeout, or any
+error prints nothing and exits 0 — the call proceeds through Claude Code's normal
+flow. Run with `CREDENCE_GOVERNOR_DEBUG=1` to log decisions/failures to stderr.
+
+## Capability boundary (Claude Code, hook transport)
+
+| Dimension | Supported |
+|---|---|
+| Waste gating (loops / repetition) | ✅ |
+| Safety (taint-flow / exfil / injected imperatives) | ✅ |
+| Routing / model selection | ❌ (no model-resolve hook) |
+| Cost / dollars-saved | ◑ observe-only |
+| Online ask-response learning | ◌ deferred — see below |
+
+v1 gates **`PreToolUse` only**. `PostToolUse` / `UserPromptSubmit` are intentionally
+not wired: neither carries a clean approval label, and treating "the call completed"
+as belief evidence would be a second learning path (a constitutional violation), not
+just a weak one. The warm-trained brain governs; the daemon logs every decision.
+Online ask-learning on Claude Code (inferring the user's reply from the next
+transcript turn) is an open design question, deferred.
+
+## Install
+
+**1. Start the daemon** — every adapter shares one local daemon; see the
+[core README](../../packages/governor_core) or the
+[repo quickstart](../../README.md#install). In short, from a clone of the repo:
+
+```bash
+pip install -e packages/governor_core -e ~/git/credence/apps/skin/clients/python
+CREDENCE_ENGINE_DIR=~/git/credence credence-governor-daemon   # or CREDENCE_SKIN_COMMAND="docker run … credence-skin@<digest>"
+```
+
+**2. Register the hook** — two ways; both end at the same `PreToolUse` hook.
+
+### Method A — as a Claude Code plugin (recommended; no `pip install`)
+
+The hook is pure stdlib, so the plugin **bundles** it and runs it via
+`${CLAUDE_PLUGIN_ROOT}` — there's nothing to `pip install`. Inside Claude Code:
+
+```
+/plugin marketplace add gfrmin/credence-governor
+/plugin install credence-governor-claude-code@credence-governor
+```
+
+The hook is active in new sessions (run `/reload-plugins` to pick it up in the current
+one). Manage or remove it from the `/plugin` menu. The plugin reuses the *same*
+`credence_governor_claude_code` package this directory ships — `plugin_hook.py` is a
+thin launcher that puts it on `sys.path` and calls the same entry point the pip console
+script uses (one implementation, two install paths). Manifests:
+[`.claude-plugin/plugin.json`](.claude-plugin/plugin.json),
+[`hooks/hooks.json`](hooks/hooks.json), and the repo-root
+[`.claude-plugin/marketplace.json`](../../.claude-plugin/marketplace.json).
+
+### Method B — as a pip package + settings hook
+
+If you'd rather manage it with pip (or script the registration):
+
+```bash
+pip install -e adapters/claude-code        # not yet on PyPI; once published: pip install credence-governor-claude-code
+credence-governor-cc-install               # → ~/.claude/settings.json  (idempotent)
+#   --project   → ./.claude/settings.json   ·   --uninstall → remove
+```
+
+Either way the hook has **no runtime dependencies** (pure stdlib); `credence-governor-core`
+is needed only for the daemon and the parity test. Static config example:
+[`settings.example.json`](settings.example.json).
+
+### Environment
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `CREDENCE_GOVERNOR_URL` | `http://127.0.0.1:8787` | governor daemon base URL |
+| `CREDENCE_GOVERNOR_TIMEOUT` | `5.0` | per-call `/decide` timeout (s); on timeout → fail open |
+| `CREDENCE_GOVERNOR_PROFILE` | *(none)* | utility profile passed to the daemon (e.g. `flow-guard`) |
+| `CREDENCE_GOVERNOR_DEBUG` | *(off)* | log decisions/failures to stderr |
+
+## Tests
+
+```bash
+python -m pytest tests -q
+```
+
+Pure-stdlib at runtime; the round-trip parity test (`test_roundtrip.py`) imports
+`credence-governor-core` to assert the wire payload deserialises through the daemon's
+`event_and_session_from_payload` to the Session the extractors expect — it is skipped
+if the core isn't importable.

credence_governor_claude_code-0.1.0/credence_governor_claude_code.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+credence_governor_claude_code/__init__.py
+credence_governor_claude_code/client.py
+credence_governor_claude_code/effectors.py
+credence_governor_claude_code/hook.py
+credence_governor_claude_code/install.py
+credence_governor_claude_code/transcript.py
+credence_governor_claude_code.egg-info/PKG-INFO
+credence_governor_claude_code.egg-info/SOURCES.txt
+credence_governor_claude_code.egg-info/dependency_links.txt
+credence_governor_claude_code.egg-info/entry_points.txt
+credence_governor_claude_code.egg-info/requires.txt
+credence_governor_claude_code.egg-info/top_level.txt
+tests/test_effectors.py
+tests/test_roundtrip.py
+tests/test_transcript.py

credence_governor_claude_code-0.1.0/credence_governor_claude_code.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

credence_governor_claude_code-0.1.0/credence_governor_claude_code.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+credence-governor-cc-install = credence_governor_claude_code.install:main
+credence-governor-claude-code = credence_governor_claude_code.hook:main

credence_governor_claude_code-0.1.0/credence_governor_claude_code.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[dev]
+pytest>=7.4
+ruff
+credence-governor-core

credence_governor_claude_code-0.1.0/credence_governor_claude_code.egg-info/top_level.txt

@@ -0,0 +1 @@
+credence_governor_claude_code

credence_governor_claude_code-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "credence-governor-claude-code"
+version = "0.1.0"
+description = "Claude Code adapter for credence-governor — a thin PreToolUse hook that Bayesian-governs tool calls (proceed/block/ask) via the governor daemon."
+requires-python = ">=3.11"
+readme = "README.md"
+license = "AGPL-3.0-or-later"
+authors = [{ name = "Guy Freeman" }]
+classifiers = [
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+# Runtime is pure stdlib (json, urllib, os): the hook must start fast and fail open.
+# The shared contract with the daemon is the JSON key set, not shared code.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/gfrmin/credence-governor"
+Repository = "https://github.com/gfrmin/credence-governor"
+
+[project.scripts]
+credence-governor-claude-code = "credence_governor_claude_code.hook:main"
+credence-governor-cc-install = "credence_governor_claude_code.install:main"
+
+[project.optional-dependencies]
+# governor-core is a TEST-only dep: the round-trip parity test asserts our wire
+# payload deserialises through the daemon's event_and_session_from_payload to the
+# Session the server-side extractors expect.
+dev = ["pytest>=7.4", "ruff", "credence-governor-core"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["credence_governor_claude_code*"]

credence_governor_claude_code-0.1.0/setup.cfg

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

credence_governor_claude_code-0.1.0/tests/test_effectors.py

@@ -0,0 +1,36 @@
+"""Action -> PreToolUse decision. The governor may only add restriction:
+proceed defers (None), block denies, ask prompts; "allow" is never emitted."""
+
+from __future__ import annotations
+
+from credence_governor_claude_code.effectors import pretooluse_output
+
+
+def test_proceed_defers_to_host():
+    assert pretooluse_output("proceed", "Bash") is None
+
+
+def test_unknown_action_defers():
+    assert pretooluse_output("weird", "Bash") is None
+
+
+def test_block_denies_with_reason():
+    out = pretooluse_output("block", "Bash")
+    hso = out["hookSpecificOutput"]
+    assert hso["hookEventName"] == "PreToolUse"
+    assert hso["permissionDecision"] == "deny"
+    assert "Bash" in hso["permissionDecisionReason"]
+
+
+def test_ask_prompts_with_reason():
+    out = pretooluse_output("ask", "Write")
+    hso = out["hookSpecificOutput"]
+    assert hso["permissionDecision"] == "ask"
+    assert "Write" in hso["permissionDecisionReason"]
+
+
+def test_never_emits_allow():
+    for action in ("proceed", "block", "ask", "weird"):
+        out = pretooluse_output(action, "X")
+        if out is not None:
+            assert out["hookSpecificOutput"]["permissionDecision"] != "allow"

credence_governor_claude_code-0.1.0/tests/test_roundtrip.py

@@ -0,0 +1,69 @@
+"""Wire-contract parity: the payload the adapter POSTs must deserialise through the
+daemon's `event_and_session_from_payload` and feed the server-side extractors to the
+right feature buckets. This is the only place the two sides are tied together — at
+the JSON contract, not at shared code. Skipped if governor-core isn't importable."""
+
+from __future__ import annotations
+
+import json
+import os
+
+import pytest
+
+# Make the sibling core package importable without an install.
+_CORE = os.path.normpath(
+    os.path.join(os.path.dirname(__file__), "..", "..", "..", "packages", "governor_core")
+)
+import sys
+
+if _CORE not in sys.path:
+    sys.path.insert(0, _CORE)
+
+core = pytest.importorskip("credence_governor_core")
+
+from credence_governor_claude_code.transcript import session_from_hook  # noqa: E402
+
+
+def _write(tmp_path, records) -> str:
+    p = os.path.join(tmp_path, "t.jsonl")
+    with open(p, "w", encoding="utf-8") as fh:
+        for r in records:
+            fh.write(json.dumps(r) + "\n")
+    return p
+
+
+def test_payload_deserialises_and_extracts(tmp_path):
+    from credence_governor_core import extract_features, extract_safety
+    from credence_governor_core.schema import event_and_session_from_payload
+
+    def tool_use(cmd, ts):
+        return {"type": "assistant", "timestamp": ts, "isSidechain": False,
+                "message": {"role": "assistant",
+                            "content": [{"type": "tool_use", "id": "t", "name": "Bash",
+                                         "input": {"command": cmd}}]}}
+
+    # Three prior identical Bash(ls) calls + the proposed fourth -> a loop.
+    records = [
+        {"type": "user", "timestamp": "2026-06-25T10:00:00.000Z", "isSidechain": False,
+         "message": {"role": "user", "content": "loop ls please"}},
+        tool_use("ls", "2026-06-25T10:00:01.000Z"),
+        tool_use("ls", "2026-06-25T10:00:02.000Z"),
+        tool_use("ls", "2026-06-25T10:00:03.000Z"),
+        tool_use("ls", "2026-06-25T10:00:04.000Z"),  # the proposed call (dropped)
+    ]
+    path = _write(tmp_path, records)
+    payload = session_from_hook(
+        {"hook_event_name": "PreToolUse", "cwd": str(tmp_path), "transcript_path": path,
+         "tool_name": "Bash", "tool_input": {"command": "ls"}}
+    )
+
+    event, session = event_and_session_from_payload(payload)
+    assert event.tool_name == "Bash"
+    # The proposed call was excluded -> exactly the three priors remain.
+    assert sum(1 for m in session.messages if m.role == "tool_call") == 3
+
+    feats = {**extract_features(event, session), **extract_safety(event, session)}
+    # Three identical priors -> rep-3plus / ident-3plus (the loop signal the daemon decides on).
+    assert feats["recent-repetition-count"] == "rep-3plus"
+    assert feats["recent-identical-call-count"] == "ident-3plus"
+    assert feats["parent-tool-call-name"] == "bash"

credence_governor_claude_code-0.1.0/tests/test_transcript.py

@@ -0,0 +1,114 @@
+"""Transcript replay: Claude Code JSONL -> neutral wire messages.
+
+The fixtures are minimal hand-written transcript records matching the real schema
+(type=user/assistant, message.content blocks, top-level timestamp/isSidechain).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from credence_governor_claude_code.transcript import (
+    drop_proposed,
+    messages_from_transcript,
+    result_to_text,
+    session_from_hook,
+)
+
+
+def _write(tmp_path, records) -> str:
+    p = os.path.join(tmp_path, "transcript.jsonl")
+    with open(p, "w", encoding="utf-8") as fh:
+        for r in records:
+            fh.write(json.dumps(r) + "\n")
+    return p
+
+
+def _user(text, ts="2026-06-25T10:00:00.000Z", sidechain=False):
+    return {"type": "user", "timestamp": ts, "isSidechain": sidechain,
+            "message": {"role": "user", "content": text}}
+
+
+def _tool_use(name, inp, ts="2026-06-25T10:00:01.000Z", sidechain=False):
+    return {"type": "assistant", "timestamp": ts, "isSidechain": sidechain,
+            "message": {"role": "assistant",
+                        "content": [{"type": "tool_use", "id": "t1", "name": name, "input": inp}]}}
+
+
+def _tool_result(content, ts="2026-06-25T10:00:02.000Z", sidechain=False):
+    return {"type": "user", "timestamp": ts, "isSidechain": sidechain,
+            "message": {"role": "user",
+                        "content": [{"type": "tool_result", "tool_use_id": "t1", "content": content}]}}
+
+
+def test_roles_and_order(tmp_path):
+    path = _write(tmp_path, [
+        _user("hello"),
+        _tool_use("Bash", {"command": "ls"}),
+        _tool_result("a.txt\nb.txt"),
+    ])
+    msgs = messages_from_transcript(path)
+    assert [m["role"] for m in msgs] == ["user", "tool_call", "tool_result"]
+    assert msgs[1]["tool_name"] == "Bash"
+    assert msgs[1]["input"] == {"command": "ls"}
+    assert msgs[2]["result"] == "a.txt\nb.txt"
+
+
+def test_sidechain_excluded_by_default(tmp_path):
+    path = _write(tmp_path, [
+        _user("hi"),
+        _tool_use("Read", {"file_path": "x"}, sidechain=True),
+    ])
+    assert [m["role"] for m in messages_from_transcript(path)] == ["user"]
+    assert len(messages_from_transcript(path, include_sidechain=True)) == 2
+
+
+def test_tool_result_list_content_flattened():
+    text = result_to_text([{"type": "text", "text": "alpha"}, {"type": "text", "text": "beta"}])
+    assert text == "alpha\nbeta"
+
+
+def test_drop_proposed_removes_matching_trailing_call():
+    msgs = [
+        {"role": "tool_call", "tool_name": "Bash", "input": {"command": "ls"}},
+        {"role": "tool_call", "tool_name": "Bash", "input": {"command": "pwd"}},
+    ]
+    drop_proposed(msgs, "Bash", {"command": "pwd"})
+    assert [m["input"] for m in msgs] == [{"command": "ls"}]
+
+
+def test_drop_proposed_keeps_nonmatching_trailing_call():
+    msgs = [{"role": "tool_call", "tool_name": "Bash", "input": {"command": "ls"}}]
+    drop_proposed(msgs, "Bash", {"command": "different"})
+    assert len(msgs) == 1
+
+
+def test_session_from_hook_excludes_proposed_call(tmp_path):
+    # The proposed Bash(pwd) is already persisted to the transcript when PreToolUse
+    # fires; the wire `messages` must NOT contain it (repetition counts priors only).
+    path = _write(tmp_path, [
+        _user("go"),
+        _tool_use("Bash", {"command": "ls"}),
+        _tool_result("ok"),
+        _tool_use("Bash", {"command": "pwd"}),
+    ])
+    payload = session_from_hook(
+        {"hook_event_name": "PreToolUse", "cwd": str(tmp_path),
+         "transcript_path": path, "tool_name": "Bash", "tool_input": {"command": "pwd"}}
+    )
+    assert payload["tool_name"] == "Bash"
+    assert payload["input"] == {"command": "pwd"}
+    calls = [m for m in payload["session"]["messages"] if m["role"] == "tool_call"]
+    assert [c["input"] for c in calls] == [{"command": "ls"}]
+
+
+def test_project_root_detected(tmp_path):
+    os.makedirs(os.path.join(tmp_path, ".git"))
+    sub = os.path.join(tmp_path, "src")
+    os.makedirs(sub)
+    payload = session_from_hook(
+        {"hook_event_name": "PreToolUse", "cwd": sub, "transcript_path": "",
+         "tool_name": "Read", "tool_input": {}}
+    )
+    assert payload["session"]["project_root"] == str(tmp_path)