vetter 0.2.0__py3-none-any.whl

vetter/__init__.py

@@ -0,0 +1,3 @@
+"""vetter: vets every command an AI agent wants to run."""
+
+__version__ = "0.2.0"

vetter/__main__.py

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

vetter/agents/__init__.py

@@ -0,0 +1,2 @@
+"""The agents' side: their hooks (requests in, decisions out, installing),
+and the log of decided commands."""

vetter/agents/hook.py

@@ -0,0 +1,298 @@
+"""Each agent's hook (docs/agents.md): the agent's request on
+stdin (JSON, read with rt.parse), the policy found (places.py), the
+command decided, the answer on stdout in the agent's format, as json.dumps
+writes it. A hook never fails open by crashing: any error is an ask (a
+deny where the agent can't ask).
+
+    run(rt, "claude", None)       # stdin -> stdout, as `vetter hook claude`
+
+An agent's answer has `default` true when no rule decided (only the
+policy's default, or nothing to vet): where the agent has its own
+permission rules, vetter then says nothing and they decide. Agents whose
+hooks can't ask (Codex, Gemini, Cline's extension) get ask as deny, with
+the reason. A decision is logged (log.py) unless the policy says `log off`.
+"""
+
+import sys
+from dataclasses import dataclass
+from os import getcwd, getenv
+
+import zgram
+
+from .. import paths
+from ..check import check
+from ..jsontext import dumps, loads
+from ..places import home_dir, load_policy, log_path, native_shell, temp_dirs, workspace_project, written_path
+from ..policy.language import followed, where
+from . import log, written
+
+CLAUDE_TOOLS = {"Bash": "bash", "PowerShell": "powershell"}
+COPILOT_TOOLS = {"bash": "bash", "powershell": "powershell", "Bash": "bash", "PowerShell": "powershell",
+                 "run_in_terminal": "", "runInTerminal": "", "terminal": ""}
+CLINE_TOOLS = ("execute_command", "run_commands")
+AGENTS = ("claude", "codex", "gemini", "cursor", "copilot", "cline", "amp", "opencode", "json")
+
+
+@dataclass
+class Call:
+    command: object
+    cwd: object
+    shell: object
+    # (Cursor's preToolUse, Cline's CLI: answered their way)
+    mode: str
+
+
+def workspace_of(agent, request):
+    """The folder the user opened the agent in, as the agent tells its
+    hooks: Claude Code's CLAUDE_PROJECT_DIR (Gemini's GEMINI_PROJECT_DIR),
+    Cursor's and Copilot's workspace roots; None: not told."""
+    if agent == "claude":
+        return getenv("CLAUDE_PROJECT_DIR")
+    if agent == "gemini":
+        return getenv("GEMINI_PROJECT_DIR") or getenv("CLAUDE_PROJECT_DIR")
+    roots = request.get("workspace_roots") or request.get("workspaceRoots")
+    if isinstance(roots, list) and len(roots) > 0 and isinstance(roots[0], str):
+        return roots[0]
+    return None
+
+
+def cant_ask(decision, reason):
+    if decision == "ask":
+        return ("deny", reason + " (vetter would ask, and this agent's hooks can't: run it yourself if it's fine)")
+    return (decision, reason)
+
+
+def command_of(tool_input):
+    if not isinstance(tool_input, dict):
+        return None
+    for key in ("command", "commands", "cmd"):
+        v = tool_input.get(key)
+        if isinstance(v, str):
+            return v
+        if isinstance(v, list):
+            strs = True
+            for x in v:
+                if not isinstance(x, str):
+                    strs = False
+            if strs:
+                return "\n".join(v)
+    return None
+
+
+def read(rt, agent, request):
+    """The shell call of a request (None: not one)."""
+    if agent == "claude":
+        shell = CLAUDE_TOOLS.get(request.get("tool_name"))
+        if shell is None:
+            return None
+        return Call(command_of(request.get("tool_input")), request.get("cwd"), shell, "")
+    if agent == "codex":
+        if request.get("tool_name") != "Bash":
+            return None
+        return Call(command_of(request.get("tool_input")), request.get("cwd"), native_shell(), "")
+    if agent == "gemini":
+        if request.get("tool_name") != "run_shell_command":
+            return None
+        ti = request.get("tool_input") or {}
+        cwd = request.get("cwd")
+        d = ti.get("dir_path") if isinstance(ti, dict) else None
+        if isinstance(d, str) and d:
+            cwd = paths.join(cwd, d) if cwd else d
+        return Call(command_of(ti), cwd, native_shell(), "")
+    if agent == "cursor":
+        if "tool_name" in request:
+            if request.get("tool_name") != "Shell":
+                return None
+            ti = request.get("tool_input") or {}
+            return Call(command_of(ti), ti.get("working_directory") or request.get("cwd"), native_shell(), "pre_tool")
+        command = request.get("command")
+        roots = request.get("workspace_roots") or [None]
+        return Call(command if isinstance(command, str) else None, request.get("cwd") or roots[0], native_shell(), "")
+    if agent == "copilot":
+        if "toolName" in request:
+            name = request.get("toolName")
+            args = request.get("toolArgs")
+            if isinstance(args, str):
+                try:
+                    args = loads(rt, args)
+                except zgram.ParseError:
+                    args = None
+        else:
+            name = request.get("tool_name")
+            args = request.get("tool_input")
+        if name not in COPILOT_TOOLS:
+            return None
+        return Call(command_of(args), request.get("cwd"), COPILOT_TOOLS[name] or native_shell(), "")
+    if agent == "cline":
+        roots = request.get("workspaceRoots") or [None]
+        if "tool_call" in request:
+            mode = "cli"
+            tc = request.get("tool_call") or {}
+            name = tc.get("name")
+            args = tc.get("input")
+        else:
+            mode = ""
+            p = request.get("preToolUse") or {}
+            name = p.get("toolName")
+            args = p.get("parameters")
+        if name not in CLINE_TOOLS:
+            return None
+        cwd = (args or {}).get("cwd") if isinstance(args, dict) else None
+        return Call(command_of(args), cwd if isinstance(cwd, str) else roots[0], native_shell(), mode)
+    command = request.get("command")
+    return Call(command if isinstance(command, str) else None, request.get("cwd"),
+                request.get("shell") or native_shell(), "")
+
+
+# The agents' editing tools: the file they write (its key in the tool's input)
+CLAUDE_EDITS = {"Write": "file_path", "Edit": "file_path", "MultiEdit": "file_path", "NotebookEdit": "notebook_path"}
+GEMINI_EDITS = {"write_file": "file_path", "replace": "file_path"}
+CLINE_EDITS = {"write_to_file": "path", "replace_in_file": "path"}
+
+
+def edited_file(agent, request):
+    """The file an editing tool's request writes, absolute and through this
+    machine's links as decisions see paths; None: not such a request."""
+    args = None
+    key = None
+    cwd = request.get("cwd")
+    if agent == "claude" or agent == "gemini":
+        edits = CLAUDE_EDITS if agent == "claude" else GEMINI_EDITS
+        name = request.get("tool_name")
+        if name in edits:
+            args = request.get("tool_input")
+            key = edits[name]
+    elif agent == "cline":
+        roots = request.get("workspaceRoots") or [None]
+        if "tool_call" in request:
+            tc = request.get("tool_call") or {}
+            name = tc.get("name")
+            given = tc.get("input")
+        else:
+            p = request.get("preToolUse") or {}
+            name = p.get("toolName")
+            given = p.get("parameters")
+        if name in CLINE_EDITS:
+            args = given
+            key = CLINE_EDITS[name]
+            cwd = roots[0]
+    if not isinstance(args, dict):
+        return None
+    v = args.get(key)
+    if not isinstance(v, str) or v == "":
+        return None
+    if not paths.is_abs(v):
+        if not isinstance(cwd, str) or not paths.is_abs(cwd):
+            return None
+        v = paths.join(cwd, v)
+    return followed(paths.norm(v), "write")
+
+
+def hook_output(decision, reason):
+    return {"hookEventName": "PreToolUse", "permissionDecision": decision, "permissionDecisionReason": reason}
+
+
+def answer(agent, mode, decision, reason, default):
+    """What the agent is told (None: nothing)."""
+    if agent == "claude":
+        if default and decision != "deny":
+            return None
+        return {"hookSpecificOutput": hook_output(decision, reason)}
+    if agent == "codex":
+        if default and decision != "deny":
+            return None
+        decision, reason = cant_ask(decision, reason)
+        if decision != "deny":
+            return None
+        return {"hookSpecificOutput": hook_output("deny", reason)}
+    if agent == "gemini":
+        if default and decision != "deny":
+            return {}
+        decision, reason = cant_ask(decision, reason)
+        if decision == "deny":
+            return {"decision": "deny", "reason": reason}
+        return {"decision": "allow", "reason": reason}
+    if agent == "cursor":
+        if mode == "pre_tool":
+            decision, reason = cant_ask(decision, reason)
+        return {"permission": decision, "user_message": reason, "agent_message": reason}
+    if agent == "copilot":
+        if default and decision != "deny":
+            return None
+        return {"permissionDecision": decision, "permissionDecisionReason": reason,
+                "hookSpecificOutput": hook_output(decision, reason)}
+    if agent == "cline":
+        if mode == "cli":
+            if decision == "deny":
+                return {"cancel": True, "errorMessage": reason}
+            if decision == "ask" and not default:
+                return {"review": True, "context": reason}
+            return {}
+        decision, reason = cant_ask(decision, reason)
+        if decision == "deny":
+            return {"cancel": True, "errorMessage": reason}
+        return {"cancel": False}
+    return {"decision": decision, "reason": reason, "default": default}
+
+
+def decide(rt, agent, request, policy_path):
+    """What to answer: (the agent's answer or None, whether anything)"""
+    if not isinstance(request, dict):
+        return answer(agent, "", "ask", "vetter: a request it doesn't understand", False)
+    if (agent == "claude" or agent == "codex") and request.get("hook_event_name") == "PostToolUse":
+        it_ran(rt, agent, request, policy_path)
+        return None
+    edited = edited_file(agent, request)
+    if edited is not None:
+        # (an editing tool: what it writes remembered, nothing decided)
+        written.record([edited], "generated", written_path(home_dir()))
+        mode = "cli" if agent == "cline" and "tool_call" in request else ""
+        return answer(agent, mode, "allow", "", True)
+    call = read(rt, agent, request)
+    if call is None:
+        return None
+    if not isinstance(call.command, str):
+        return answer(agent, call.mode, "ask", "vetter: a shell call without a command", False)
+    cwd = call.cwd if isinstance(call.cwd, str) and call.cwd else getcwd()
+    home = home_dir()
+    policy = load_policy(rt, policy_path, cwd, home)
+    project = workspace_project(cwd, home, workspace_of(agent, request))
+    d = check(rt, policy, call.command, call.shell, cwd, home, project, temp_dirs(home, True))
+    call_id = request.get("tool_use_id")
+    if policy.log:
+        log.record_call(rt, agent, cwd, call.command, d, log_path(home), call_id if isinstance(call_id, str) else "",
+                        project)
+    written.record_decision(d, policy.written, written_path(home))
+    at = " [" + where(d.rule) + "]" if d.rule is not None else ""
+    return answer(agent, call.mode, d.decision, "vetter: " + d.reason + at, d.by == "default" or d.by == "nothing")
+
+
+def it_ran(rt, agent, request, policy_path):
+    """A call that ran (PostToolUse): if vetter asked, the user said yes
+    (`vetter learn`'s); logged by its id, nothing answered."""
+    ident = text_field(request, "tool_use_id")
+    cwd = text_field(request, "cwd")
+    home = home_dir()
+    policy = load_policy(rt, policy_path, cwd if cwd != "" else getcwd(), home)
+    if ident != "" and policy.log:
+        log.record_ran(rt, agent, ident, log_path(home))
+
+
+def text_field(request, key):
+    """request[key] if it's a str, else ""."""
+    v = request.get(key)
+    if isinstance(v, str):
+        return v
+    return ""
+
+
+def run(rt, agent, policy_path):
+    """The request on stdin decided, the answer on stdout; never failing
+    open: an error is an ask (a deny where the agent can't ask)."""
+    try:
+        out = decide(rt, agent, loads(rt, sys.stdin.read()), policy_path)
+    except Exception as e:  # noqa: BLE001 (whatever goes wrong, a decision: ask)
+        out = answer(agent, "", "ask", "vetter couldn't decide (" + type(e).__name__ + ": " + str(e) + ")", False)
+    if out is not None:
+        sys.stdout.write(dumps(out) + "\n")
+    return 0

vetter/agents/importing.py

@@ -0,0 +1,219 @@
+"""`vetter import`: an agent's own permission rules as a vetter policy.
+
+Their rules come first (Claude Code's deny, then ask, then allow; Codex's
+in their order), then `use stock`: the stock policy's denies still come
+before everything (what they forbid stays forbidden), its other rules
+decide what the imported ones don't name. What can't be said in vetter's
+terms is left as a comment saying why.
+
+    text = from_claude(settings_dict, "~/.claude/settings.json")
+    text = from_codex({"default.rules": source})
+"""
+
+import ast
+import datetime
+import json
+import re
+
+# Claude Code: permissions.allow / ask / deny
+
+_ENTRY = re.compile(r"^(?P<tool>[A-Za-z]+)(?:\((?P<arg>.*)\))?$", re.S)
+_OPERATORS = re.compile(r"[;&|<>`$()\n]")
+
+
+def _q(s):
+    return '"' + s.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _word(w):
+    """A word as the policy language takes it: bare when it can be."""
+    return w if re.fullmatch(r"\$?[A-Za-z0-9_.+:@%/~=?*-]+", w) and not w.startswith("-") else _q(w)
+
+
+def _command_match(spec):
+    """A Bash rule's command (`git diff:*`, `npm run build`, `ls *`) as a
+    program match, and a note when vetter's is broader; None and why when
+    it can't be said."""
+    prefix = spec.endswith(":*")
+    cmd = spec[:-2] if prefix else spec
+    cmd = cmd.strip()
+    if cmd.endswith(" *"):
+        cmd, prefix = cmd[:-2].rstrip(), True
+    if not cmd or cmd == "*":
+        return "any", None
+    if _OPERATORS.search(cmd):
+        return None, "a command with shell operators: vetter decides each part of a command on its own"
+    words = cmd.split()
+    if any("*" in w for w in words):
+        return None, "a wildcard inside the command"
+    names = []
+    for w in words:
+        if w.startswith("-"):
+            break
+        names.append(w)
+    rest = words[len(names):]
+    # (its options: each must be there, as in the agent's prefix)
+    options = [w for w in rest if w.startswith("-") and re.fullmatch(r"-[A-Za-z0-9_=-]*", w)]
+    note = None
+    if len(options) < len(rest):
+        note = "the words after its options left out: vetter matches a program by name, subcommands and options"
+    elif not prefix:
+        note = "with more arguments too: vetter matches a program by name, subcommands and options"
+    withs = "".join(f" with {o}" for o in options)
+    if "/" in names[0] or "\\" in names[0]:
+        path = names[0]
+        if path.startswith("./"):
+            path = "$project/" + path[2:]
+        return f"run exactly {_word(path)}", note
+    return " ".join(_word(n) for n in names) + withs, note
+
+
+def _place(path):
+    """A Read/Edit rule's path (gitignore-style, as Claude Code reads it) as
+    a place: ./x and /x from the project, //x absolute, ~/x home."""
+    if path.startswith("//"):
+        p = path[1:]
+    elif path.startswith("~/") or path == "~":
+        p = path
+    elif path.startswith("/"):
+        p = "$project" + path
+    elif path.startswith("./"):
+        p = "$project/" + path[2:]
+    else:
+        p = "$project/" + path
+    p = p.replace("/**/", "/*/").removesuffix("/**").removesuffix("/*") or p
+    return _word(p)
+
+
+def _claude_rule(decision, entry):
+    m = _ENTRY.match(entry.strip())
+    if not m:
+        return None, f"not a permission rule vetter reads: {entry}"
+    tool, arg = m["tool"], m["arg"]
+    reason = _q(f"claude: {entry}")
+    if tool in ("Bash", "PowerShell"):
+        match, note = _command_match(arg or "*")
+        if match is None:
+            return None, f"{entry}: {note}"
+        rule = f"{decision} {reason} {match}"
+        return rule + (f"   # ({note})" if note else ""), None
+    if tool in ("Read", "Edit", "Write", "MultiEdit", "NotebookEdit"):
+        verb = "read" if tool == "Read" else "write"
+        if not arg:
+            return f"{decision} {reason} {verb}", None
+        return f"{decision} {reason} {verb} in {_place(arg)}", None
+    if tool == "WebFetch":
+        if arg and arg.startswith("domain:"):
+            # (a domain the agent may fetch from: the same for commands)
+            return f"{decision} {reason} download from {_word(arg[7:])}", None
+        return None, f"{entry}: WebFetch without a domain"
+    return None, f"{entry}: not a shell or file rule (vetter vets commands)"
+
+
+def from_claude(settings, where="~/.claude/settings.json", today=None):
+    perms = (settings or {}).get("permissions") or {}
+    lines = _header("Claude Code", where, today)
+    skipped = []
+    for decision in ("deny", "ask", "allow"):
+        entries = perms.get(decision) or []
+        if entries:
+            lines.append(f"\n# {decision}")
+        for e in entries:
+            rule, why = _claude_rule(decision, e)
+            if rule is not None:
+                lines.append(rule)
+            else:
+                skipped.append(why)
+    return _footer(lines, skipped)
+
+
+# Codex: execpolicy's prefix_rule(...) in ~/.codex/rules/*.rules
+
+_CODEX_DECISIONS = {"allow": "allow", "prompt": "ask", "forbidden": "deny"}
+
+
+def _codex_rules(source, name):
+    """The prefix_rule calls of a .rules file (Starlark, read as Python's
+    syntax: literals only)."""
+    out, skipped = [], []
+    try:
+        tree = ast.parse(source, name)
+    except SyntaxError as e:
+        return [], [f"{name}: not read ({e.msg}, line {e.lineno})"]
+    for node in ast.walk(tree):
+        if not (isinstance(node, ast.Call) and getattr(node.func, "id", None) == "prefix_rule"):
+            continue
+        try:
+            kw = {k.arg: ast.literal_eval(k.value) for k in node.keywords}
+        except ValueError:
+            skipped.append(f"{name}:{node.lineno}: a prefix_rule with values that aren't literals")
+            continue
+        pattern = kw.get("pattern")
+        if not pattern and node.args:
+            pattern = ast.literal_eval(node.args[0])
+        out.append((node.lineno, pattern, kw.get("decision", "allow"), kw.get("justification")))
+    return out, skipped
+
+
+def from_codex(files, where="~/.codex/rules", today=None):
+    lines = _header("Codex", where, today)
+    skipped = []
+    for name, source in sorted(files.items()):
+        rules, bad = _codex_rules(source, name)
+        skipped += bad
+        if rules:
+            lines.append(f"\n# {name}")
+        for lineno, pattern, decision, why in rules:
+            d = _CODEX_DECISIONS.get(decision)
+            if d is None or not isinstance(pattern, (list, tuple)) or not pattern:
+                skipped.append(f"{name}:{lineno}: a rule vetter doesn't read ({decision!r}, {pattern!r})")
+                continue
+            levels = []
+            withs = []
+            note = None
+            for token in pattern:
+                alts = token if isinstance(token, (list, tuple)) else [token]
+                if any(not isinstance(a, str) for a in alts):
+                    note = "a pattern vetter doesn't read whole"
+                    break
+                if any(a.startswith("-") for a in alts):
+                    if all(re.fullmatch(r"-[A-Za-z0-9_=-]*", a) for a in alts):
+                        # (alternatives: any of them; each token: all)
+                        withs.append(" with " + ", ".join(alts))
+                        continue
+                    note = "a pattern vetter doesn't read whole"
+                    break
+                if withs:
+                    note = "the words after its options left out: vetter matches a program by name, subcommands " \
+                           "and options"
+                    break
+                levels.append(", ".join(_word(a) for a in alts))
+            if not levels:
+                skipped.append(f"{name}:{lineno}: {pattern!r}: no program name")
+                continue
+            reason = _q(f"codex: {why}" if why else f"codex: {' '.join(map(str, pattern))}")
+            lines.append(f"{d} {reason} " + " ".join(levels) + "".join(withs) + (f"   # ({note})" if note else ""))
+    return _footer(lines, skipped)
+
+
+def _header(agent, where, today):
+    today = today or datetime.date.today().isoformat()
+    return [
+        "policy imported",
+        f"# {agent}'s permission rules from {where} ({today}), by `vetter import`.",
+        "# They come first; the stock policy's denies come before everything",
+        "# (what they forbid stays forbidden), its other rules decide the rest.",
+    ]
+
+
+def _footer(lines, skipped):
+    lines.append("\nuse stock")
+    if skipped:
+        lines.append("\n# Not imported:")
+        lines += [f"#   {s}" for s in skipped]
+    return "\n".join(lines) + "\n"
+
+
+def read_claude(path):
+    with open(path) as f:
+        return json.load(f)