agentdetox 0.2.0__py3-none-any.whl

agentdetox/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

agentdetox/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

agentdetox/adapters.py

@@ -0,0 +1,161 @@
+"""Each agent's hook protocol: what its events look like and how it wants an answer.
+
+Everything agent-specific stays here, so the engine and policy see only Writes, shell
+commands and file paths. An agent without its own adapter gets Claude Code's reply
+format and no ask prompt.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+
+from .agentscan import read_text
+from .engine import Write
+from .policy import Decision
+
+SHELL_TOOLS = {"bash", "shell", "exec", "exec_command", "local_shell", "run_terminal_cmd"}
+_EVENTS = {"pretooluse": "pre", "posttooluse": "post", "afterfileedit": "post", "sessionstart": "session"}
+_PATCH_FILE_RE = re.compile(r"^\*\*\* (Add|Update) File: (.+)$")
+
+
+class Adapter:
+    name = "generic"
+    can_ask = False         # whether the agent can put a question to the user mid-task
+    session_chars = 6000    # how much session-start context the agent takes
+
+    def event(self, payload: dict) -> str:
+        """pre (a tool call about to run), post (a file was written), session, or empty."""
+        return _EVENTS.get(str(payload.get("hook_event_name", "")).lower(), "")
+
+    def project(self, payload: dict) -> Path:
+        roots = payload.get("workspace_roots") or []
+        return Path(payload.get("cwd") or (roots[0] if roots else None) or os.getcwd())
+
+    def command(self, payload: dict) -> str | None:
+        """The command line, if the tool call is a shell command."""
+        if str(payload.get("tool_name", "")).lower() not in SHELL_TOOLS:
+            return None
+        command = (payload.get("tool_input") or {}).get("command", "")
+        return " ".join(map(str, command)) if isinstance(command, list) else command
+
+    def writes(self, payload: dict, project: Path) -> list[Write]:
+        """The file changes a tool call would make, from the edit tools' various inputs."""
+        tool_input = payload.get("tool_input") or {}
+        patch = next((v for v in tool_input.values() if isinstance(v, str) and "*** Begin Patch" in v), None)
+        if patch is not None:
+            return _patch_writes(patch, project)
+        path_value = next((tool_input[k] for k in ("file_path", "path", "target_file") if k in tool_input), None)
+        if not path_value:
+            return []
+        path = Path(path_value)
+        if not path.is_absolute():
+            path = project / path
+        old = read_text(path) if path.is_file() else ""
+        if "edits" in tool_input:
+            new = old
+            for e in tool_input["edits"]:
+                new = _apply_edit(new, e)
+        elif "old_string" in tool_input:
+            new = _apply_edit(old, tool_input)
+        else:
+            new = next((tool_input[k] for k in ("content", "contents", "code_edit", "new_string") if k in tool_input), "")
+        return [Write(path, old, str(new))]
+
+    def written(self, payload: dict, project: Path) -> list[Path]:
+        """Files a finished tool call wrote."""
+        tool_input = payload.get("tool_input") or {}
+        paths = [Path(p) for p in (tool_input.get("file_path"), tool_input.get("path"), payload.get("file_path")) if p]
+        return [p if p.is_absolute() else project / p for p in paths]
+
+    def transcript(self, payload: dict) -> str | None:
+        return None
+
+    def session(self, payload: dict) -> str:
+        """The agent's id for the session, for the ledger."""
+        return str(payload.get("session_id") or payload.get("conversation_id") or "")
+
+    def render_pre(self, decision: Decision) -> str:
+        if decision.action == "allow":
+            return ""
+        return json.dumps({"hookSpecificOutput": {
+            "hookEventName": "PreToolUse", "permissionDecision": decision.action,
+            "permissionDecisionReason": decision.reason}})
+
+    def render_session(self, text: str) -> str:
+        text = text[: self.session_chars]
+        if not text:
+            return ""
+        return json.dumps({"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": text}})
+
+    def render_allow(self) -> str:
+        return ""
+
+
+class ClaudeCode(Adapter):
+    name = "claude-code"
+    can_ask = True
+    session_chars = 9000
+
+    def transcript(self, payload: dict) -> str | None:
+        return payload.get("transcript_path")
+
+
+class Codex(Adapter):
+    name = "codex"
+
+
+class Cursor(Adapter):
+    name = "cursor"
+    session_chars = 9000
+
+    def render_pre(self, decision: Decision) -> str:
+        out = {"permission": "deny" if decision.action != "allow" else "allow"}
+        if decision.action != "allow":
+            out.update(user_message=decision.reason, agent_message=decision.reason)
+        return json.dumps(out)
+
+    def render_session(self, text: str) -> str:
+        text = text[: self.session_chars]
+        return json.dumps({"additional_context": text} if text else {})
+
+    def render_allow(self) -> str:
+        # Cursor treats an empty or invalid reply from a permission hook as a block.
+        return json.dumps({"permission": "allow"})
+
+
+ADAPTERS = {a.name: a for a in (ClaudeCode(), Codex(), Cursor())}
+
+
+def get(agent: str) -> Adapter:
+    return ADAPTERS.get(agent) or Adapter()
+
+
+def _apply_edit(text: str, edit: dict) -> str:
+    old, new = edit.get("old_string", ""), edit.get("new_string", "")
+    if not old:
+        return text + new
+    return text.replace(old, new) if edit.get("replace_all") else text.replace(old, new, 1)
+
+
+def _patch_writes(patch: str, project: Path) -> list[Write]:
+    """Codex apply_patch: collect each file's added lines."""
+    writes: dict[Path, list[str]] = {}
+    current: Path | None = None
+    for line in patch.splitlines():
+        m = _PATCH_FILE_RE.match(line)
+        if m:
+            current = Path(m.group(2).strip())
+            current = current if current.is_absolute() else project / current
+            writes.setdefault(current, [])
+        elif line.startswith("*** "):
+            current = None
+        elif current is not None and line.startswith("+"):
+            writes[current].append(line[1:])
+    out = []
+    for path, added in writes.items():
+        old = read_text(path) if path.is_file() else ""
+        out.append(Write(path, old, old + "\n" + "\n".join(added)))
+    return out

agentdetox/agentscan.py

@@ -0,0 +1,70 @@
+"""Scan an agent's persistent context files for planted instructions."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .consistency import find_contradictions, statements, store_statements
+from .context import ContextFile, related_files
+from .corpus import Doc
+from .findings import Finding, line_at, pair_anchor, snippet
+from .hidden import normalize, scan_doc
+from .persistence import config_commands, text_findings
+
+
+def read_text(path) -> str:
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def scan_text(doc_id: str, source: str, text: str, kind: str) -> list[Finding]:
+    """Findings for one piece of context text. `kind` is a ContextFile kind."""
+    if kind == "config":
+        return _scan_config(doc_id, source, text)
+    findings = scan_doc(Doc(doc_id, text, source))
+    norm = normalize(text)
+    for severity, label, pos in text_findings(text):
+        findings.append(Finding(doc_id, source, "persistence", severity, label, snippet(norm, pos),
+                                anchor=line_at(norm, pos)))
+    return findings
+
+
+def _scan_config(doc_id: str, source: str, text: str) -> list[Finding]:
+    findings = []
+    for where, command in config_commands(Path(source), text):
+        for severity, label, _ in text_findings(command):
+            findings.append(Finding(doc_id, source, "config-command", severity, f"{label} ({where})", command[:200],
+                                    anchor=command))
+    return findings
+
+
+def consistency_findings(files: list[ContextFile], project: Path | None, nli) -> list[Finding]:
+    """Contradictions between files in each memory scope (one project's memory plus the
+    instructions that apply to it). Each conflicting pair is reported once."""
+    seen: set[frozenset] = set()
+    out: list[Finding] = []
+    for cf in files:
+        if cf.kind not in ("memory", "instructions"):
+            continue
+        own = statements(read_text(cf.path), str(cf.path))
+        if not own:
+            continue
+        others = store_statements(related_files(cf, project), skip={str(cf.path)})
+        # Sentences of one note were written together; within a file the model only adds noise.
+        for c in find_contradictions(own, others, nli):
+            key = frozenset((c.new.text, c.existing.text))
+            if key in seen:
+                continue
+            seen.add(key)
+            out.append(Finding(str(cf.path), str(cf.path), "contradiction", "medium",
+                               f'contradicts "{c.existing.text[:120]}" ({c.existing.source}:{c.existing.line}), '
+                               f"p={c.probability:.2f}", c.new.text[:200],
+                               anchor=pair_anchor(c.new.text, c.existing.text)))
+    return out
+
+
+def scan_context(files: list[ContextFile]) -> list[Finding]:
+    findings: list[Finding] = []
+    for cf in files:
+        text = read_text(cf.path)
+        findings.extend(scan_text(str(cf.path), str(cf.path), text, cf.kind))
+    return findings

agentdetox/allowlist.py

@@ -0,0 +1,101 @@
+"""Findings the user reviewed and allowed: "always allow this one".
+
+Ids come from what was flagged (the line, the conflicting pair, the untrusted source),
+not from where or when, so one `agentdetox allow <id>` covers the write check, the
+session notice and `agentdetox agent scan`. The file sits with the snapshots, and the
+hooks make an agent ask before changing it, or an injected instruction could allow
+itself.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .consistency import Contradiction
+from .findings import ID_LENGTH, Finding, finding_id, make_id, pair_anchor
+from .integrity import private_dir, store_dir, store_lock, write_private
+from .provenance import CopyFinding
+
+ID_RE = re.compile(rf"^[0-9a-f]{{{ID_LENGTH}}}$")
+SCHEMA_VERSION = 1
+
+
+@dataclass
+class Flag:
+    id: str
+    what: str
+
+
+def path() -> Path:
+    return store_dir() / "allowlist.json"
+
+
+def entries() -> dict[str, dict]:
+    """Allowed ids. An unreadable file allows nothing: failing closed only costs a prompt."""
+    p = path()
+    try:
+        data = json.loads(p.read_text(encoding="utf-8")) if p.exists() else {}
+    except (OSError, ValueError):
+        return {}
+    if not isinstance(data, dict) or data.get("version", SCHEMA_VERSION) > SCHEMA_VERSION:
+        return {}
+    allowed = data.get("allowed")
+    return allowed if isinstance(allowed, dict) else {}
+
+
+def _save(allowed: dict[str, dict]) -> None:
+    p = path()
+    if p.exists():
+        try:
+            data = json.loads(p.read_text(encoding="utf-8"))
+        except ValueError:
+            raise ValueError(f"{p} is not valid JSON; fix or delete it first") from None
+        if isinstance(data, dict) and data.get("version", SCHEMA_VERSION) > SCHEMA_VERSION:
+            raise ValueError(f"{p} was written by a newer AgentDetox; upgrade agentdetox")
+    tmp = private_dir(store_dir()) / "allowlist.json.tmp"
+    write_private(tmp, json.dumps({"version": SCHEMA_VERSION, "allowed": allowed}, indent=1,
+                                  ensure_ascii=False).encode())
+    tmp.replace(p)
+
+
+def add(flag_id: str, what: str = "", note: str = "") -> None:
+    with store_lock():
+        allowed = entries()
+        allowed[flag_id] = {"what": what, "note": note, "added": time.strftime("%Y-%m-%dT%H:%M:%S")}
+        _save(allowed)
+
+
+def remove(flag_id: str) -> bool:
+    with store_lock():
+        allowed = entries()
+        if allowed.pop(flag_id, None) is None:
+            return False
+        _save(allowed)
+    return True
+
+
+def unsuppressed(findings: list[Finding]) -> list[Finding]:
+    allowed = entries()
+    return [f for f in findings if finding_id(f) not in allowed] if allowed else findings
+
+
+def finding_flag(f: Finding) -> Flag:
+    detail = " ".join((f.anchor or f.evidence).split())[:100]
+    return Flag(finding_id(f), f"{f.message}" + (f" | {detail}" if detail and detail != f.message else ""))
+
+
+def source_id(tool: str, origin: str) -> str:
+    return make_id("copied", tool, origin)
+
+
+def copy_flag(c: CopyFinding) -> Flag:
+    return Flag(source_id(c.tool, c.origin), f"copied from {c.tool} {c.origin}".strip())
+
+
+def contradiction_flag(c: Contradiction) -> Flag:
+    return Flag(make_id("contradiction", pair_anchor(c.new.text, c.existing.text)),
+                f'"{c.new.text[:100]}" contradicts "{c.existing.text[:100]}"')