@inneranimalmedia/agentsam-sdk 2.0.0 → 2.2.0

package/python/agentsam_sdk/repository/recon/packet.py

@@ -0,0 +1,294 @@
+"""Build a bounded ReconTaskPacket from an explicit repo root and an explicit file list.
+
+Design law (mirrors protocol/README.md rule 6 and docs/REPOSITORY_INTELLIGENCE.md):
+  - Read-only. This module never writes into the target repository.
+  - Accepts an explicit repo_root; never assumes one repository's layout.
+  - Never hardcodes a tenant/workspace/provider ID as the task handle.
+  - The caller (a capable agent, or repository.intelligence output) selects the files.
+    This module does not go searching for "relevant" files on its own — that discovery
+    step belongs upstream, where budget and reasoning are cheap.
+
+Stdlib only.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Iterable
+
+SCHEMA_VERSION = 1
+TOOL_NAME_PACK = "repository.recon.pack"
+MAX_SLICES = 5
+MAX_FOLLOW_UP_READS = 2
+DEFAULT_TIMEOUT_SECONDS = 90
+DEFAULT_MAX_OUTPUT_TOKENS = 800
+
+
+class PacketError(ValueError):
+    """Raised when a task packet cannot be built as specified."""
+
+
+def _head_sha(repo_root: Path) -> str:
+    try:
+        out = subprocess.check_output(
+            ["git", "rev-parse", "HEAD"], cwd=repo_root, stderr=subprocess.DEVNULL
+        )
+        return out.decode("utf-8", errors="surrogateescape").strip()
+    except (subprocess.CalledProcessError, FileNotFoundError, OSError):
+        return "unknown"
+
+
+def _read_slice(repo_root: Path, rel_path: str, start_line: int | None, end_line: int | None) -> str:
+    target = (repo_root / rel_path).resolve()
+    try:
+        target.relative_to(repo_root.resolve())
+    except ValueError as exc:
+        raise PacketError(f"slice_escapes_repo_root:{rel_path}") from exc
+    if not target.is_file():
+        raise PacketError(f"slice_not_found:{rel_path}")
+    try:
+        text = target.read_text(encoding="utf-8", errors="strict")
+    except (UnicodeDecodeError, OSError) as exc:
+        raise PacketError(f"slice_unreadable:{rel_path}") from exc
+    if start_line is None and end_line is None:
+        return text
+    lines = text.splitlines()
+    start = max(1, start_line or 1)
+    end = min(len(lines), end_line or len(lines))
+    if start > end:
+        raise PacketError(f"slice_range_invalid:{rel_path}:{start}-{end}")
+    return "\n".join(lines[start - 1 : end])
+
+
+def build_task_packet(
+    repo_root: str | Path,
+    *,
+    question: str,
+    slices: Iterable[dict[str, Any]],
+    task_id: str | None = None,
+    allowed_diagnostics: Iterable[str] = (),
+    max_follow_up_reads: int = MAX_FOLLOW_UP_READS,
+    max_output_tokens: int = DEFAULT_MAX_OUTPUT_TOKENS,
+    timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS,
+    embed_content: bool = True,
+) -> dict[str, Any]:
+    """Build one bounded ReconTaskPacket.
+
+    `slices` is a list of {"path", "start_line"?, "end_line"?, "reason"?} — exact,
+    caller-chosen material. This function never expands that list; it only reads and
+    validates it, and enforces the hard ceilings from protocol/recon/task-packet.schema.json.
+    """
+    root = Path(repo_root).expanduser().resolve()
+    if not root.is_dir():
+        raise PacketError(f"repo_root_not_found:{root}")
+    if not question or not question.strip():
+        raise PacketError("question_required")
+
+    slice_list = list(slices)
+    if not slice_list:
+        raise PacketError("at_least_one_slice_required")
+    if len(slice_list) > MAX_SLICES:
+        raise PacketError(f"too_many_slices:{len(slice_list)}>{MAX_SLICES}")
+    if not (0 <= max_follow_up_reads <= MAX_FOLLOW_UP_READS):
+        raise PacketError(f"max_follow_up_reads_out_of_range:{max_follow_up_reads}")
+
+    resolved_slices: list[dict[str, Any]] = []
+    for item in slice_list:
+        path = item.get("path")
+        if not path:
+            raise PacketError("slice_missing_path")
+        start_line = item.get("start_line")
+        end_line = item.get("end_line")
+        entry: dict[str, Any] = {"path": path}
+        if start_line is not None:
+            entry["start_line"] = int(start_line)
+        if end_line is not None:
+            entry["end_line"] = int(end_line)
+        if item.get("reason"):
+            entry["reason"] = str(item["reason"])
+        if item.get("kind"):
+            entry["kind"] = str(item["kind"])
+        if item.get("hit_count"):
+            entry["hit_count"] = int(item["hit_count"])
+        if embed_content:
+            entry["content"] = _read_slice(root, path, entry.get("start_line"), entry.get("end_line"))
+        resolved_slices.append(entry)
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "task_id": task_id or f"recon-{uuid.uuid4().hex[:12]}",
+        "repo_root": str(root),
+        "base_sha": _head_sha(root),
+        "generated_at_unix": int(time.time()),
+        "question": question.strip(),
+        "slices": resolved_slices,
+        "allowed_diagnostics": list(allowed_diagnostics),
+        "ceilings": {
+            "max_follow_up_reads": max_follow_up_reads,
+            "max_output_tokens": max_output_tokens,
+            "timeout_seconds": timeout_seconds,
+        },
+        "response_schema_ref": "./finding-report.schema.json",
+    }
+
+
+def from_matches(
+    repo_root: str | Path,
+    *,
+    question: str,
+    matches: Iterable[dict[str, Any]],
+    task_id_prefix: str = "recon",
+    max_files_per_packet: int = MAX_SLICES,
+    context_lines: int = 3,
+    **packet_kwargs: Any,
+) -> list[dict[str, Any]]:
+    """Turn raw, tool-agnostic search hits into one or more bounded packets.
+
+    This is the adapter for "I already ran rg/ast-grep and have a hit list, now I
+    need packets" -- it does not run any search itself. `matches` is any iterable of
+    {"path": str, "line": int, "kind": str?} -- output from from_ripgrep()/from_ast_grep()
+    (or any hand-built equivalent) works directly.
+
+    Hits are grouped by file into one slice per file (a [min-context, max+context]
+    line window covering every hit in that file), then chunked into packets of at
+    most `max_files_per_packet` files each -- so a 16-file, 41-hit sweep becomes
+    several small packets instead of one that violates the slice ceiling or silently
+    drops files.
+
+    The worker still never searches. This function is what the controller runs
+    *instead of* handing the worker rg.
+    """
+    if max_files_per_packet > MAX_SLICES:
+        raise PacketError(f"max_files_per_packet_exceeds_ceiling:{max_files_per_packet}>{MAX_SLICES}")
+
+    by_path: dict[str, dict[str, Any]] = {}
+    for hit in matches:
+        path = hit.get("path")
+        if not path:
+            raise PacketError("match_missing_path")
+        line = hit.get("line")
+        entry = by_path.setdefault(path, {"lines": [], "kinds": set()})
+        if line is not None:
+            entry["lines"].append(int(line))
+        if hit.get("kind"):
+            entry["kinds"].add(str(hit["kind"]))
+
+    if not by_path:
+        raise PacketError("no_matches_supplied")
+
+    files = sorted(by_path)
+    packets: list[dict[str, Any]] = []
+    chunks = [files[i : i + max_files_per_packet] for i in range(0, len(files), max_files_per_packet)]
+    for idx, chunk in enumerate(chunks, start=1):
+        slices = []
+        for path in chunk:
+            entry = by_path[path]
+            lines = entry["lines"]
+            if lines:
+                start = max(1, min(lines) - context_lines)
+                end = max(lines) + context_lines
+            else:
+                start = end = None
+            kinds = sorted(entry["kinds"])
+            reason = f"{len(lines) or 'unknown-count of'} hit(s)"
+            if kinds:
+                reason += f" ({', '.join(kinds)})"
+            slice_entry: dict[str, Any] = {"path": path, "reason": reason}
+            if start is not None:
+                slice_entry["start_line"] = start
+                slice_entry["end_line"] = end
+            if lines:
+                slice_entry["hit_count"] = len(lines)
+            if len(kinds) == 1:
+                slice_entry["kind"] = kinds[0]
+            slices.append(slice_entry)
+        suffix = f"-{idx}of{len(chunks)}" if len(chunks) > 1 else ""
+        packets.append(
+            build_task_packet(
+                repo_root,
+                question=question,
+                slices=slices,
+                task_id=f"{task_id_prefix}{suffix}",
+                **packet_kwargs,
+            )
+        )
+    return packets
+
+
+def from_ripgrep(rg_json: str | Iterable[str]) -> list[dict[str, Any]]:
+    """Parse `rg --json` NDJSON output into `from_matches()`-shaped hits.
+
+    Runs no search itself -- pass the captured stdout of an `rg --json ...` call
+    (a single string, or an iterable of its lines). Only `type: "match"` records are
+    kept. rg is lexical only, so hits carry no `kind` -- pair with `from_ast_grep()`
+    output in the same `matches` list when structural classification is available.
+
+    Example::
+
+        raw = subprocess.run(
+            ["rg", "--json", "-e", "workspace_id", "backend/workflows"],
+            capture_output=True, text=True,
+        ).stdout
+        matches = recon.from_ripgrep(raw)
+    """
+    lines = rg_json.splitlines() if isinstance(rg_json, str) else rg_json
+    hits: list[dict[str, Any]] = []
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise PacketError(f"rg_json_line_invalid:{line[:80]}") from exc
+        if obj.get("type") != "match":
+            continue
+        data = obj.get("data", {})
+        path = (data.get("path") or {}).get("text")
+        line_number = data.get("line_number")
+        if not path or line_number is None:
+            continue
+        hits.append({"path": path, "line": int(line_number)})
+    return hits
+
+
+def from_ast_grep(sg_json_compact: str, *, kind: str | None = None) -> list[dict[str, Any]]:
+    """Parse `sg`/`ast-grep ... --json=compact` array output into `from_matches()`-shaped hits.
+
+    Runs no search itself. One ast-grep invocation is one pattern or one inline rule --
+    i.e. one structural shape -- so `kind` is a caller-supplied label applied to every
+    hit from that call (e.g. "member", "member_camel", "sql_string"), not something
+    this function infers. Redirect the deprecation banner ast-grep prints on stderr
+    away from stdout (it does not appear in --json=compact stdout, but callers piping
+    `2>&1` will see it mixed in).
+
+    Example::
+
+        raw = subprocess.run(
+            ["sg", "-p", "$X.workspace_id", "-l", "js", "--json=compact",
+             "backend/workflows"],
+            capture_output=True, text=True,
+        ).stdout
+        matches = recon.from_ast_grep(raw, kind="member")
+    """
+    text = sg_json_compact.strip()
+    if not text:
+        return []
+    try:
+        records = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise PacketError(f"sg_json_invalid:{text[:80]}") from exc
+    hits: list[dict[str, Any]] = []
+    for record in records:
+        path = record.get("file")
+        line_number = ((record.get("range") or {}).get("start") or {}).get("line")
+        if not path or line_number is None:
+            continue
+        hit: dict[str, Any] = {"path": path, "line": int(line_number)}
+        if kind:
+            hit["kind"] = kind
+        hits.append(hit)
+    return hits

package/python/agentsam_sdk/repository/recon/validate.py

@@ -0,0 +1,76 @@
+"""Validate a worker's ReconFindingReport against its originating packet.
+
+This is the deterministic validator in the pipeline:
+    controller -> packet -> mini worker -> [this module] -> capable agent
+
+It does not trust the worker. It checks structure, checks that every referenced file
+was actually inside the packet's slices (a worker cannot invent evidence for a file it
+was never given), and enforces the "never guess" rule: a report that isn't clearly
+`answered` or `needs_context` is rejected rather than passed upstream.
+
+Stdlib only.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+TOOL_NAME_VALIDATE = "repository.recon.validate"
+REQUIRED_TOP_LEVEL = ("schema_version", "task_id", "status")
+VALID_STATUSES = ("answered", "needs_context")
+VALID_SEVERITIES = ("low", "medium", "high")
+
+
+class ReportError(ValueError):
+    """Raised when a finding report fails validation and must not be forwarded."""
+
+
+def _known_paths(packet: dict[str, Any]) -> set[str]:
+    return {s["path"] for s in packet.get("slices", [])}
+
+
+def validate_report(report: dict[str, Any], packet: dict[str, Any]) -> dict[str, Any]:
+    """Return the report unchanged if valid; raise ReportError otherwise.
+
+    Callers should treat a ReportError as "discard this worker output, do not hand it
+    to the capable agent" — never as something to silently patch and pass along.
+    """
+    if not isinstance(report, dict):
+        raise ReportError("report_not_an_object")
+
+    missing = [key for key in REQUIRED_TOP_LEVEL if key not in report]
+    if missing:
+        raise ReportError(f"missing_fields:{','.join(missing)}")
+
+    if report.get("schema_version") != 1:
+        raise ReportError(f"unsupported_schema_version:{report.get('schema_version')}")
+
+    if report.get("task_id") != packet.get("task_id"):
+        raise ReportError("task_id_mismatch")
+
+    status = report.get("status")
+    if status not in VALID_STATUSES:
+        raise ReportError(f"invalid_status:{status}")
+
+    if status == "needs_context":
+        if not report.get("reason"):
+            raise ReportError("needs_context_missing_reason")
+        return report
+
+    # status == "answered"
+    known = _known_paths(packet)
+    for finding in report.get("findings", []):
+        for key in ("severity", "file", "finding"):
+            if key not in finding:
+                raise ReportError(f"finding_missing_field:{key}")
+        if finding["severity"] not in VALID_SEVERITIES:
+            raise ReportError(f"invalid_severity:{finding['severity']}")
+        if finding["file"] not in known:
+            raise ReportError(
+                f"finding_cites_file_outside_packet:{finding['file']}"
+            )
+
+    for path in report.get("affected_files", []):
+        if path not in known:
+            raise ReportError(f"affected_file_outside_packet:{path}")
+
+    return report

package/python/tests/test_knowledge_models.py

@@ -12,10 +12,14 @@ class KnowledgeContractsTest(unittest.TestCase):
                     return {"run_id": "run", "source_id": payload["source_id"], "status": "succeeded"}
                 return {"query_id": "query", "hits": [{"chunk_id": "chunk", "content": "code", "score": 1, "lane": "code"}]}
         client = KnowledgeClient(Transport())
-        query = RetrievalQuery(text="function", workspace_id="workspace")
+        query = RetrievalQuery(text="function")
         self.assertEqual(asyncio.run(client.retrieve(query)).hits[0].content, "code")
         self.assertEqual(asyncio.run(client.index("source")).status, "succeeded")
-        self.assertEqual(Source("s", "repository", "workspace", "file:///repo").source_id, "s")
+        self.assertEqual(Source("s", "repository", "file:///repo").source_id, "s")
+
+    def test_workspace_is_optional_compatibility_metadata(self):
+        query = RetrievalQuery(text="function", workspace_id="legacy-workspace")
+        self.assertEqual(query.workspace_id, "legacy-workspace")
 
 
 if __name__ == "__main__":

package/python/tests/test_recon.py

@@ -0,0 +1,257 @@
+"""Unit tests for repository.recon -- packet building and report validation.
+
+No git dependency required (base_sha falls back to "unknown" outside a repo);
+no model calls; no network.
+"""
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from agentsam_sdk.repository.recon import (
+    PacketError,
+    ReportError,
+    build_task_packet,
+    from_ast_grep,
+    from_matches,
+    from_ripgrep,
+    validate_report,
+)
+
+
+class TestBuildTaskPacket(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self.tmp.name)
+        (self.root / "backend").mkdir()
+        (self.root / "backend" / "workflows.js").write_text(
+            "\n".join(f"line {i}" for i in range(1, 201)), encoding="utf-8"
+        )
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_builds_bounded_packet_with_content(self):
+        packet = build_task_packet(
+            self.root,
+            question="Does this file depend on workspace_id?",
+            slices=[{"path": "backend/workflows.js", "start_line": 1, "end_line": 5}],
+        )
+        self.assertEqual(packet["schema_version"], 1)
+        self.assertEqual(len(packet["slices"]), 1)
+        self.assertEqual(packet["slices"][0]["content"], "line 1\nline 2\nline 3\nline 4\nline 5")
+        self.assertEqual(packet["ceilings"]["max_follow_up_reads"], 2)
+        self.assertTrue(packet["task_id"].startswith("recon-"))
+
+    def test_rejects_missing_question(self):
+        with self.assertRaises(PacketError):
+            build_task_packet(self.root, question="  ", slices=[{"path": "backend/workflows.js"}])
+
+    def test_rejects_more_than_five_slices(self):
+        slices = [{"path": "backend/workflows.js"} for _ in range(6)]
+        with self.assertRaises(PacketError):
+            build_task_packet(self.root, question="q", slices=slices)
+
+    def test_rejects_slice_outside_repo_root(self):
+        with self.assertRaises(PacketError):
+            build_task_packet(self.root, question="q", slices=[{"path": "../../etc/passwd"}])
+
+    def test_rejects_missing_file(self):
+        with self.assertRaises(PacketError):
+            build_task_packet(self.root, question="q", slices=[{"path": "backend/nope.js"}])
+
+
+class TestFromMatches(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.root = Path(self.tmp.name)
+        (self.root / "backend").mkdir()
+        for name in ("a.js", "b.js", "c.js", "d.js", "e.js", "f.js"):
+            (self.root / "backend" / name).write_text(
+                "\n".join(f"line {i}" for i in range(1, 51)), encoding="utf-8"
+            )
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_chunks_more_than_five_files_into_multiple_packets(self):
+        # 6 files -> ceiling is 5 per packet -> 2 packets
+        matches = [
+            {"path": f"backend/{name}", "line": 10, "kind": "member"}
+            for name in ("a.js", "b.js", "c.js", "d.js", "e.js", "f.js")
+        ]
+        packets = from_matches(self.root, question="q", matches=matches, task_id_prefix="wf")
+        self.assertEqual(len(packets), 2)
+        self.assertEqual(packets[0]["task_id"], "wf-1of2")
+        self.assertEqual(packets[1]["task_id"], "wf-2of2")
+        total_slices = sum(len(p["slices"]) for p in packets)
+        self.assertEqual(total_slices, 6)
+        for p in packets:
+            self.assertLessEqual(len(p["slices"]), 5)
+
+    def test_groups_multiple_hits_in_one_file_into_one_windowed_slice(self):
+        matches = [
+            {"path": "backend/a.js", "line": 5, "kind": "sql_string"},
+            {"path": "backend/a.js", "line": 20, "kind": "sql_string"},
+        ]
+        packets = from_matches(self.root, question="q", matches=matches, context_lines=2)
+        slice_ = packets[0]["slices"][0]
+        self.assertEqual(slice_["start_line"], 3)
+        self.assertEqual(slice_["end_line"], 22)
+        self.assertEqual(slice_["hit_count"], 2)
+        self.assertEqual(slice_["kind"], "sql_string")
+
+    def test_rejects_empty_matches(self):
+        with self.assertRaises(PacketError):
+            from_matches(self.root, question="q", matches=[])
+
+
+class TestFromRipgrep(unittest.TestCase):
+    def test_parses_ndjson_match_lines_only(self):
+        # Real `rg --json` shape: begin/match/end/summary records per file.
+        ndjson = "\n".join([
+            json.dumps({"type": "begin", "data": {"path": {"text": "backend/http/workflows/scope.js"}}}),
+            json.dumps({
+                "type": "match",
+                "data": {
+                    "path": {"text": "backend/http/workflows/scope.js"},
+                    "line_number": 66,
+                    "lines": {"text": "  body.workspace_id\n"},
+                },
+            }),
+            json.dumps({"type": "end", "data": {"path": {"text": "backend/http/workflows/scope.js"}}}),
+            json.dumps({"type": "summary", "data": {}}),
+        ])
+        hits = from_ripgrep(ndjson)
+        self.assertEqual(hits, [{"path": "backend/http/workflows/scope.js", "line": 66}])
+
+    def test_accepts_a_list_of_lines_too(self):
+        lines = [json.dumps({"type": "match", "data": {"path": {"text": "a.js"}, "line_number": 1}})]
+        self.assertEqual(from_ripgrep(lines), [{"path": "a.js", "line": 1}])
+
+    def test_empty_input_yields_no_hits(self):
+        self.assertEqual(from_ripgrep(""), [])
+
+    def test_rejects_malformed_json_line(self):
+        with self.assertRaises(PacketError):
+            from_ripgrep("not json")
+
+
+class TestFromAstGrep(unittest.TestCase):
+    def test_parses_compact_json_array_with_caller_supplied_kind(self):
+        # Real `sg -p '...' --json=compact` shape.
+        raw = json.dumps([
+            {
+                "text": "body.workspace_id",
+                "range": {"start": {"line": 66, "column": 76}, "end": {"line": 66, "column": 93}},
+                "file": "backend/http/workflows/scope.js",
+            },
+            {
+                "text": "ctx.workspaceId",
+                "range": {"start": {"line": 12, "column": 4}, "end": {"line": 12, "column": 19}},
+                "file": "backend/workflows/handlers/tool.js",
+            },
+        ])
+        hits = from_ast_grep(raw, kind="member")
+        self.assertEqual(hits, [
+            {"path": "backend/http/workflows/scope.js", "line": 66, "kind": "member"},
+            {"path": "backend/workflows/handlers/tool.js", "line": 12, "kind": "member"},
+        ])
+
+    def test_kind_is_optional(self):
+        raw = json.dumps([{"range": {"start": {"line": 1}}, "file": "a.js"}])
+        self.assertEqual(from_ast_grep(raw), [{"path": "a.js", "line": 1}])
+
+    def test_empty_array_yields_no_hits(self):
+        self.assertEqual(from_ast_grep("[]"), [])
+
+    def test_rejects_invalid_json(self):
+        with self.assertRaises(PacketError):
+            from_ast_grep("not json")
+
+    def test_adapters_compose_into_from_matches(self):
+        # The actual workflow: run several classified sg queries + one rg sweep,
+        # concatenate, then chunk into packets -- same shape as the iMac smoke test.
+        member_hits = from_ast_grep(
+            json.dumps([{"range": {"start": {"line": 5}}, "file": "backend/a.js"}]), kind="member"
+        )
+        sql_hits = from_ast_grep(
+            json.dumps([{"range": {"start": {"line": 20}}, "file": "backend/b.js"}]), kind="sql_string"
+        )
+        rg_hits = from_ripgrep(json.dumps({
+            "type": "match", "data": {"path": {"text": "backend/c.js"}, "line_number": 8},
+        }))
+        combined = member_hits + sql_hits + rg_hits
+        self.assertEqual(len(combined), 3)
+        self.assertEqual({h["path"] for h in combined}, {"backend/a.js", "backend/b.js", "backend/c.js"})
+        self.assertEqual(combined[2].get("kind"), None)  # rg hit carries no kind
+
+
+class TestValidateReport(unittest.TestCase):
+    def setUp(self):
+        self.packet = {
+            "task_id": "recon-abc123",
+            "slices": [{"path": "backend/workflows.js"}],
+        }
+
+    def test_accepts_answered_report_citing_known_file(self):
+        report = {
+            "schema_version": 1,
+            "task_id": "recon-abc123",
+            "status": "answered",
+            "findings": [
+                {
+                    "severity": "high",
+                    "file": "backend/workflows.js",
+                    "finding": "still queries workspace_id",
+                }
+            ],
+        }
+        self.assertEqual(validate_report(report, self.packet), report)
+
+    def test_accepts_needs_context_with_reason(self):
+        report = {
+            "schema_version": 1,
+            "task_id": "recon-abc123",
+            "status": "needs_context",
+            "reason": "definition of ensureWorkflowRun() not supplied",
+        }
+        self.assertEqual(validate_report(report, self.packet)["status"], "needs_context")
+
+    def test_rejects_needs_context_without_reason(self):
+        report = {"schema_version": 1, "task_id": "recon-abc123", "status": "needs_context"}
+        with self.assertRaises(ReportError):
+            validate_report(report, self.packet)
+
+    def test_rejects_finding_that_cites_a_file_outside_the_packet(self):
+        report = {
+            "schema_version": 1,
+            "task_id": "recon-abc123",
+            "status": "answered",
+            "findings": [
+                {"severity": "high", "file": "backend/other.js", "finding": "made up"}
+            ],
+        }
+        with self.assertRaises(ReportError):
+            validate_report(report, self.packet)
+
+    def test_rejects_task_id_mismatch(self):
+        report = {"schema_version": 1, "task_id": "recon-different", "status": "needs_context", "reason": "x"}
+        with self.assertRaises(ReportError):
+            validate_report(report, self.packet)
+
+    def test_rejects_invalid_severity(self):
+        report = {
+            "schema_version": 1,
+            "task_id": "recon-abc123",
+            "status": "answered",
+            "findings": [
+                {"severity": "critical", "file": "backend/workflows.js", "finding": "x"}
+            ],
+        }
+        with self.assertRaises(ReportError):
+            validate_report(report, self.packet)
+
+
+if __name__ == "__main__":
+    unittest.main()