Skip to content
Python
20.1 KB
Raw Blame
"""The steps of a plan the user approved in auto-approve, and exact matching (OPE-237).

In auto-approve the agent can propose a plan as a list of steps. Once the user approves
it, every later action in the same request is checked here against the steps, by code.
Only an exact match counts:

* ``write``  - a file tool writing exactly that file (every file, for a patch);
* ``delete`` - a plain delete of exactly that file (``rm``/``del``/``Remove-Item`` with no
  pattern, no recursion, nothing chained), or a patch's ``Delete File`` of it;
* ``run``    - exactly that command, ignoring spacing;
* ``send``   - that file going to exactly that host (a network command whose every URL is
  that host, with no user-info in the URL, that reads exactly that file and nothing
  else, with nothing piped or chained; or a web tool whose URL is that host), or a
  connector action to exactly that recipient.

Paths in a shell command are judged from the shell's current folder when the engine
knows it (``shell_base``), and nothing matches when it cannot. A step naming a protected
in-project file (git hooks, CI configs, the workspace policy) never matches: those files
always reach a person.

When the action is exactly a step, the reviewer gets one fixed line
(``review_facts.PLAN_STEP``). Any other action gets no plan line at all, so a plan can
only add evidence for its own steps and never makes anything else harder. The reviewer
never sees the plan's text: the steps are written by the agent, and a step can only ever
vouch for itself.
"""

from __future__ import annotations

import json
import re
import shlex
import sys
from dataclasses import dataclass
from urllib.parse import urlsplit
from pathlib import Path
from typing import Any, Callable, Iterable, Optional

from .review_facts import shell_reaches_network

KINDS = ("write", "delete", "run", "send")
MAX_STEPS = 30
MAX_TEXT = 1000
MAX_NOTE = 200

_FILE_TOOLS = {"write_file", "replace_in_file", "apply_patch", "apply_unified_diff"}
_PATCH_DELETE = re.compile(r"^\*\*\* Delete File: (.+)$", re.MULTILINE)
# Anything that makes a command more than "delete these named files": chaining, pipes,
# redirection, substitution, globbing, variables.
_SHELL_META = re.compile(r"[;&|`$<>(){}*?\[\]\n\r]")
_DELETE_COMMANDS = {"rm", "del", "erase", "remove-item", "ri"}
_DELETE_FLAGS = {"-f", "--force", "-force", "-path", "-literalpath", "/q", "/f"}
_LOOKS_LIKE_FILE = re.compile(r"^[\w.-]+\.[A-Za-z0-9]{1,8}$")
# A send step's target is a file when it has an extension (a message is not a file).
_FILE_TARGET = re.compile(r"^[^\s<>|&;`$\"']+\.[A-Za-z0-9]{1,8}$")
# Shown as risky on the card: something besides the named program runs or decides.
_RISKY_META = re.compile(r"[;&|<>`$\n\r]")
_RISKY_PROGRAMS = {
    "sudo", "doas", "runas", "su", "crontab", "schtasks", "at", "launchctl", "mkfs",
    "dd", "format", "shutdown", "reboot", "diskpart", "chown", "chmod", "icacls", "takeown",
}
_RISKY_GIT = {"clean", "push", "restore", "filter-branch", "filter-repo"}
_RISKY_GIT_WITH = {
    ("reset", "--hard"), ("checkout", "--"), ("checkout", "."), ("branch", "-d"),
    ("branch", "--delete"), ("stash", "drop"), ("stash", "clear"),
}
# A program and a verb that publishes, deploys or uploads: the work leaves the machine.
_RISKY_VERBS = {
    ("npm", "publish"), ("yarn", "publish"), ("pnpm", "publish"), ("npm", "deprecate"),
    ("twine", "upload"), ("cargo", "publish"), ("gem", "push"), ("poetry", "publish"),
    ("docker", "push"), ("podman", "push"), ("gh", "release"), ("gh", "pr"), ("glab", "mr"),
    ("aws", "s3"), ("gsutil", "cp"), ("gsutil", "rsync"), ("az", "storage"),
    ("kubectl", "apply"), ("kubectl", "delete"), ("terraform", "apply"),
    ("terraform", "destroy"), ("pulumi", "up"), ("vercel", "deploy"), ("netlify", "deploy"),
    ("fly", "deploy"), ("heroku", "push"),
}
# Shell tokens that name the local file a network client sends. curl's short flags are
# case-sensitive (-F is a form, -f is --fail; -T uploads, -t is a telnet option); the long
# names, and PowerShell's -InFile, are not.
_UPLOAD_LONG = {"--upload-file", "-infile", "--post-file", "--body-file"}
_DATA_LONG = {"--data", "--data-binary", "--data-ascii", "--data-urlencode", "--json"}
_FORM_LONG = {"--form"}
_SHORT = {"T": "upload", "d": "data", "F": "form"}
_STDIN = {"-", "@-"}
# More than one upload in a command: chaining, pipes, redirection, substitution. Globs in
# the URL (a query string) are fine; globs in a file name are refused in `_sent_files`.
_SEND_META = re.compile(r"[;&|`$<>(){}\n\r]")
_GLOB = re.compile(r"[*?\[]")
# "httpbin.org/post", "httpbin.org:443": a host with a path or a port, no scheme.
_HOST_WITH_TAIL = re.compile(r"^([a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+)(?::\d+)?(?:[/?#].*)?$")


def _destination(raw: str) -> str:
    """A send step's destination as it is checked: a URL or host with a path or port
    becomes the bare host (agents write "https://httpbin.org/post"); a connector
    recipient ("slack:T1/C9", an email address) keeps its shape. Lower case."""
    text = raw.strip().lower()
    if "://" in text:
        return (urlsplit(text).hostname or "").strip(".")
    match = _HOST_WITH_TAIL.match(text)
    return match.group(1) if match else text


@dataclass(frozen=True)
class PlanStep:
    kind: str
    target: str
    destination: str = ""  # a send's destination; for a run that reaches the network, its host(s)
    note: str = ""  # the agent's few words for the user; never part of the match

    def as_dict(self) -> dict[str, str]:
        return {
            "kind": self.kind,
            "target": self.target,
            **({"destination": self.destination} if self.destination else {}),
            **({"note": self.note} if self.note else {}),
        }


def normalize_steps(raw: Any) -> tuple[list[PlanStep], list[str]]:
    """The well-formed steps, and one line per entry dropped, saying why (for the agent).

    A write or delete target is one file path; a run target is the exact command, and when
    it reaches the network its URL hosts are shown on the card and a URL with a login before
    "@" is refused (the text before "@" is not the host). Live 28 Oct 2026: the agent wrote
    "cd src && rm old-notes.txt" as a delete step and a deceptive URL as a run step."""
    if raw is None:
        return [], []
    if not isinstance(raw, list):
        return [], ["`steps` must be a list of {kind, target[, destination][, note]}"]
    steps: list[PlanStep] = []
    dropped: list[str] = []
    for entry in raw:
        if not isinstance(entry, dict):
            dropped.append(f"{str(entry)[:60]!r}: a step is an object with kind and target")
            continue
        kind = str(entry.get("kind") or "").strip().lower()
        target = str(entry.get("target") or "").strip()
        note = str(entry.get("note") or "").strip()[:MAX_NOTE]
        destination = _destination(str(entry.get("destination") or "")) if kind == "send" else ""
        label = f"{kind} {target[:60]!r}"
        reason = ""
        if kind not in KINDS:
            reason = "kind must be write, delete, run or send"
        elif not target:
            reason = "a step needs a target"
        elif len(target) > MAX_TEXT or len(destination) > MAX_TEXT:
            reason = "too long"
        elif kind in ("write", "delete") and _looks_like_command(target):
            reason = f"a {kind} step's target is one file path, not a command (use a run step for a command)"
        elif kind == "send" and not destination:
            reason = "a send step needs a destination (host or recipient)"
        elif kind == "run" and shell_reaches_network(target):
            hosts = _url_hosts(_words(target))
            if hosts is None:
                reason = "the URL has a login before '@' or no host; write the destination host plainly"
            else:
                destination = ", ".join(sorted(hosts))
        if not reason and len(steps) >= MAX_STEPS:
            reason = f"more than {MAX_STEPS} steps"
        if reason:
            dropped.append(f"{label}: {reason}")
            continue
        steps.append(PlanStep(kind, target, destination, note))
    return steps, dropped


def _looks_like_command(target: str) -> bool:
    """A write/delete target that is really a command line."""
    if _SEND_META.search(target):
        return True
    words = target.split()
    return len(words) > 1 and words[0].lower() in _DELETE_COMMANDS | {"cd", "rmdir", "rd", "mv", "move", "cp", "copy"}


def _words(command: str) -> list[str]:
    try:
        return [w.strip("'\"") for w in shlex.split(command, posix=False)]
    except ValueError:
        return command.split()


def step_is_risky(step: PlanStep, resolve: Optional[Callable[[str], Path]] = None) -> bool:
    """Shown as risky on the card: sending, deleting, pushing or publishing, a command
    that deletes, reaches the network, runs inline code, chains, pipes or redirects, or a
    write or delete of a protected in-project file (with `resolve`). Writes outside the
    workspace are marked by the engine, which knows the workspace."""
    if step.kind in ("delete", "send"):
        return True
    if step.kind == "write":
        return resolve is not None and _protected(resolve(step.target))
    if step.kind == "run":
        from .permissions import _DANGEROUS_FLAGS, _INLINE_CODE_FLAGS, _INTERPRETERS

        words = [w.lower() for w in _words(step.target)]
        if not words:
            return False
        if _RISKY_META.search(step.target) or shell_reaches_network(step.target):
            return True
        programs = {_program(w) for w in words}
        if programs & (_DELETE_COMMANDS | {"rmdir", "rd"}) or _program(words[0]) in _RISKY_PROGRAMS:
            return True
        if any(w in _DANGEROUS_FLAGS for w in words):
            return True
        inline = {f.lower() for f in _INLINE_CODE_FLAGS}
        if programs & _INTERPRETERS and any(w in inline for w in words):
            return True
        for i, word in enumerate(words):
            rest = words[i + 1 :]
            program = _program(word)
            if program == "git" and (
                set(rest) & _RISKY_GIT or any(a in rest and b in rest for a, b in _RISKY_GIT_WITH)
            ):
                return True
            if any(program == prog and verb in rest for prog, verb in _RISKY_VERBS):
                return True
    return False


def _program(word: str) -> str:
    name = Path(word).name
    return name[:-4] if name.endswith(".exe") else name


def _protected(path: Path) -> bool:
    from .permissions import _is_protected_in_project

    return _is_protected_in_project(path)


def _key(path: Path) -> str:
    text = path.as_posix()
    return text.casefold() if sys.platform in ("win32", "darwin") else text


def _host(host: str) -> str:
    host = host.lower().strip().strip(".")
    return host[4:] if host.startswith("www.") else host


def _norm_command(command: Any) -> str:
    return " ".join(str(command or "").split())


def _plain_delete_paths(command: str) -> Optional[list[str]]:
    """The files a command deletes when it is only a plain delete of named files."""
    if _SHELL_META.search(command):
        return None
    words = _words(command)
    if not words or words[0].lower() not in _DELETE_COMMANDS:
        return None
    paths = []
    for word in words[1:]:
        if word.lower() in _DELETE_FLAGS:
            continue
        if word.startswith("-"):
            return None  # -r, -rf, -Recurse …: not a plain file delete
        paths.append(word)
    return paths or None


def _mentions(text: str, name: str) -> bool:
    base = Path(name.replace("\\", "/")).name or name
    return re.search(r"(?<![\w.-])" + re.escape(base) + r"(?![\w.-])", text) is not None


def _covered(paths: Iterable[str], approved: set[str], resolve: Callable[[str], Path]) -> bool:
    keys = [_key(resolve(p)) for p in paths]
    return bool(keys) and all(k in approved for k in keys) and not any(_protected(resolve(p)) for p in paths)


def _url_hosts(words: list[str]) -> Optional[set[str]]:
    """The host of every URL in a command, or None when a URL carries user-info (the text
    before "@" is a login, not the host: "https://httpbin.org:[email protected]/" goes to
    evil.example) or has no host."""
    hosts: set[str] = set()
    for word in words:
        if "://" not in word:
            continue
        try:
            parts = urlsplit(word)
        except ValueError:
            return None
        if parts.username is not None or parts.password is not None or not parts.hostname:
            return None
        hosts.add(_host(parts.hostname))
    return hosts


def _sent_files(words: list[str]) -> Optional[list[str]]:
    """The local files a network command sends (curl, wget and PowerShell forms), or None
    when it sends standard input, a glob, or something that cannot be read as a file."""
    files: list[str] = []
    is_curl = bool(words) and _program(words[0]).lower() == "curl"
    skip = False
    for i, word in enumerate(words):
        if skip:
            skip = False
            continue
        kind, attached = "", ""
        low = word.lower()
        name, _, rest = low.partition("=")
        if name in _UPLOAD_LONG | _DATA_LONG | _FORM_LONG:
            kind = "upload" if name in _UPLOAD_LONG else "data" if name in _DATA_LONG else "form"
            attached = word.partition("=")[2] if _ else ""
        elif is_curl and re.fullmatch(r"-[A-Za-z]+.*", word):
            # Short flags, possibly combined ("-sF", "-d@file"): the first letter that
            # takes a value takes the rest of the word, or the next word.
            for j, ch in enumerate(word[1:], 1):
                if ch in _SHORT:
                    kind, attached = _SHORT[ch], word[j + 1 :]
                    break
                if not ch.isalpha():
                    break
        if kind and not attached:
            if i + 1 >= len(words):
                return None
            attached, skip = words[i + 1], True
        if kind == "upload":
            if attached in _STDIN:
                return None
            files.append(attached)
        elif kind == "data":
            if "@" in attached:
                name = attached.split("@", 1)[1]
                if not name or name == "-":
                    return None
                files.append(name)
        elif kind == "form":
            if "=@" in attached or "=<" in attached:
                name = re.split(r"=[@<]", attached, 1)[1]
                if not name or name == "-":
                    return None
                files.append(name)
        elif word.startswith("@"):
            if word in _STDIN:
                return None
            files.append(word[1:])
    if any(_GLOB.search(f) for f in files):
        return None  # the shell may expand it to any number of files
    return files


def match_step(
    steps: list[PlanStep],
    tool_name: str,
    arguments: dict[str, Any],
    *,
    resolve: Callable[[str], Path],
    egress_host: Optional[Callable[[str, dict[str, Any]], str]] = None,
    shell_base: Optional[Callable[[], Optional[str]]] = None,
) -> bool:
    """True only when the action is exactly one of the approved steps. `resolve` maps a
    step's or a file tool's path to its real place. `shell_base`, when given, returns the
    shell's current folder, from which a command's paths are judged, or None when the
    engine cannot know it: then no shell path matches."""
    if not steps:
        return False
    args = arguments if isinstance(arguments, dict) else {}
    try:
        writes = {_key(resolve(s.target)) for s in steps if s.kind == "write"}
        deletes = {_key(resolve(s.target)) for s in steps if s.kind == "delete"}
        sends = [s for s in steps if s.kind == "send"]

        if tool_name in _FILE_TOOLS:
            from .permissions import write_paths

            paths, located = write_paths(tool_name, args)
            if not located:
                return False
            removed = _PATCH_DELETE.findall(str(args.get("patch", ""))) if tool_name == "apply_patch" else []
            removed = [p.strip() for p in removed]
            changed = [p for p in paths if p not in removed]
            return (not changed or _covered(changed, writes, resolve)) and (
                not removed or _covered(removed, deletes, resolve)
            ) and bool(changed or removed)

        if tool_name == "run_shell":
            command = str(args.get("command", ""))
            same_run = any(s.kind == "run" and _norm_command(s.target) == _norm_command(command) for s in steps)
            deleted = _plain_delete_paths(command)
            if deleted is not None:
                # A plain delete is judged as a delete even when listed as a run step, so
                # a protected file is never deleted on a plan's word.
                shell_resolve = _shell_resolver(resolve, shell_base)
                if shell_resolve is None or any(_protected(shell_resolve(p)) for p in deleted):
                    return False
                return same_run or _covered(deleted, deletes, shell_resolve)
            if same_run:
                # A run step that reaches the network was checked at proposal time; a URL
                # with a login before "@" never matches, whatever the plan says.
                return not shell_reaches_network(command) or _url_hosts(_words(command)) is not None
            if shell_reaches_network(command):
                if not sends or _SEND_META.search(command):
                    return False  # piped, chained or redirected: more than the one upload
                words = _words(command)
                hosts = _url_hosts(words)
                files = _sent_files(words)
                shell_resolve = _shell_resolver(resolve, shell_base)
                if not hosts or len(hosts) != 1 or not files or shell_resolve is None:
                    return False
                host = next(iter(hosts))
                approved = {
                    _key(resolve(s.target))
                    for s in sends
                    if _host(s.destination) == host and _FILE_TARGET.match(s.target)
                }
                return all(_key(shell_resolve(f)) in approved for f in files)
            return False

        if not sends:
            return False
        blob = json.dumps(args, ensure_ascii=False, default=str)
        if args.get("url") and egress_host is not None:
            # A web tool: its URL's host, exactly.
            host = _host(egress_host(tool_name, args) or "")
            return bool(host) and any(_host(s.destination) == host and _mentions(blob, s.target) for s in sends)

        from .connectors.tool_defs import standing_target_for

        recipient = str(standing_target_for(tool_name, args) or "").strip().lower()
        if not recipient:
            return False  # e.g. a browser upload: where it goes is not in the action
        return any(
            s.destination.strip().lower() == recipient
            and (not _LOOKS_LIKE_FILE.match(s.target) or _mentions(blob, s.target))
            for s in sends
        )
    except Exception:  # noqa: BLE001 - a step that cannot be checked does not match
        return False


def _shell_resolver(
    resolve: Callable[[str], Path], shell_base: Optional[Callable[[], Optional[str]]]
) -> Optional[Callable[[str], Path]]:
    """How a shell command's relative paths resolve: from the shell's current folder when
    the engine tracks it, else like a step's path. None when the folder cannot be known."""
    if shell_base is None:
        return resolve
    cwd = shell_base()
    if not cwd:
        return None
    base = Path(cwd).expanduser().resolve()

    def from_shell(path: str) -> Path:
        p = Path(path).expanduser()
        return p.resolve() if p.is_absolute() else (base / p).resolve()

    return from_shell


def steps_text(shown: list[dict[str, Any]]) -> str:
    """The steps as plain lines, for the Inbox body and its Slack mirror."""
    lines = []
    for step in shown or []:
        if not isinstance(step, dict):
            continue
        line = f"- {step.get('kind', '')} {step.get('target', '')}"
        if step.get("destination"):
            line += f" -> {step['destination']}"
        if step.get("risky"):
            line += " (risky)"
        if step.get("note"):
            line += f"\n  {step['note']}"
        lines.append(line)
    return "Steps:\n" + "\n".join(lines) if lines else ""