hx-cli 0.1.0__py3-none-any.whl

hx/permissions/engine.py

@@ -0,0 +1,406 @@
+"""Permission rule engine.
+
+Rules are ``Tool(specifier)`` strings - ``Bash(git commit:*)``, ``Edit(src/**)``,
+``Read(~/.ssh/**)``. Evaluation order is deny, then ask, then allow: an explicit
+deny can never be overridden by a broader allow, including in bypass mode.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, ClassVar
+
+from hx.config import PermissionMode
+from hx.permissions.parser import CommandSegment, is_read_only, match_specifier, parse
+
+
+class Decision(StrEnum):
+    ALLOW = "allow"
+    ASK = "ask"
+    DENY = "deny"
+
+
+class GrantScope(StrEnum):
+    ONCE = "once"
+    SESSION = "session"
+    ALWAYS = "always"
+    """Persisted to project settings.json."""
+
+
+DEFAULT_MUTATING_TOOLS = frozenset({"Bash", "Write", "Edit", "MultiEdit", "Task", "NotebookEdit"})
+"""Fallback when the caller does not supply the registry's own metadata."""
+
+
+@dataclass(slots=True)
+class Rule:
+    tool: str
+    specifier: str | None
+    decision: Decision
+    source: str
+    """Where the rule came from, so ``/permissions`` can show it."""
+
+
+@dataclass(slots=True)
+class PermissionRequest:
+    tool_name: str
+    specifier: str | None
+    params: dict[str, Any]
+    mutating: bool
+    description: str
+    detail: str = ""
+    """Rendered diff or command text shown in the approval modal."""
+    origin: str | None = None
+    """Which subagent asked, when it was not the main conversation."""
+
+
+@dataclass(slots=True)
+class PermissionOutcome:
+    decision: Decision
+    reason: str
+    matched_rule: Rule | None = None
+
+
+@dataclass(slots=True)
+class PermissionAnswer:
+    allowed: bool
+    scope: GrantScope = GrantScope.ONCE
+
+
+Asker = Callable[[PermissionRequest], Awaitable[PermissionAnswer]]
+"""Supplied by the frontend. Absent means nothing can answer an ASK."""
+
+
+class PermissionEngine:
+    #: Modes that never prompt for a file edit.
+    EDIT_TOOLS: ClassVar[frozenset[str]] = frozenset({"Write", "Edit", "MultiEdit", "NotebookEdit"})
+
+    def __init__(
+        self,
+        mode: PermissionMode,
+        rules: list[Rule],
+        cwd: Path,
+        asker: Asker | None = None,
+    ) -> None:
+        self.mode = mode
+        self.rules = list(rules)
+        self.cwd = cwd
+        self.asker = asker
+        self._session_grants: set[tuple[str, str | None]] = set()
+
+    # --- decision ---------------------------------------------------------
+
+    def evaluate(self, request: PermissionRequest) -> PermissionOutcome:
+        """Pure decision - no prompting, no I/O. Ordering: deny, ask, allow, then
+        the mode default.
+
+        For Bash the specifier is decomposed by ``hx.permissions.parser`` and every
+        segment must pass; an unparseable command degrades to ASK.
+        """
+        if denial := self._match(request, Decision.DENY):
+            return PermissionOutcome(Decision.DENY, "matched a deny rule", denial)
+
+        if request.tool_name == "Bash" and request.specifier:
+            parsed = parse(request.specifier)
+            if parsed.unparseable:
+                return PermissionOutcome(
+                    Decision.ASK,
+                    "command could not be decomposed; approving it blind is not safe",
+                )
+
+        if (request.tool_name, request.specifier) in self._session_grants:
+            return PermissionOutcome(Decision.ALLOW, "granted for this session")
+
+        if ask_rule := self._match(request, Decision.ASK):
+            return PermissionOutcome(Decision.ASK, "matched an ask rule", ask_rule)
+
+        if allow_rule := self._match_allow(request):
+            return PermissionOutcome(Decision.ALLOW, "matched an allow rule", allow_rule)
+
+        return self._mode_default(request)
+
+    def _mode_default(self, request: PermissionRequest) -> PermissionOutcome:
+        if self.mode is PermissionMode.BYPASS:
+            return PermissionOutcome(Decision.ALLOW, "bypass mode")
+
+        if self.mode is PermissionMode.PLAN:
+            if request.mutating:
+                return PermissionOutcome(
+                    Decision.DENY, "plan mode is read-only; no writes or commands"
+                )
+            return PermissionOutcome(Decision.ALLOW, "read-only tool in plan mode")
+
+        if not request.mutating:
+            return PermissionOutcome(Decision.ALLOW, "read-only tool")
+
+        if self.mode is PermissionMode.ACCEPT_EDITS and request.tool_name in self.EDIT_TOOLS:
+            return PermissionOutcome(Decision.ALLOW, "acceptEdits mode")
+
+        if request.tool_name == "Bash" and request.specifier:
+            parsed = parse(request.specifier)
+            if parsed.segments and all(is_read_only(s) for s in parsed.segments):
+                if parsed.has_redirect_out:
+                    return PermissionOutcome(Decision.ASK, "command redirects output to a file")
+                return PermissionOutcome(Decision.ALLOW, "read-only command")
+
+        return PermissionOutcome(Decision.ASK, "mutating tool")
+
+    def _match(self, request: PermissionRequest, decision: Decision) -> Rule | None:
+        for rule in self.rules:
+            if rule.decision is not decision or rule.tool not in {request.tool_name, "*"}:
+                continue
+            if rule.specifier is None or self._specifier_matches(request, rule.specifier):
+                return rule
+        return None
+
+    def _match_allow(self, request: PermissionRequest) -> Rule | None:
+        """Allow requires *every* segment to be covered.
+
+        Any-segment matching is right for deny (``safe && danger`` must be
+        caught) but catastrophic for allow: an ``allow: Bash(git status:*)``
+        rule would green-light ``git status && rm -rf /``. Each segment must
+        find its own allow rule, substitutions included.
+        """
+        candidates = [
+            rule
+            for rule in self.rules
+            if rule.decision is Decision.ALLOW and rule.tool in {request.tool_name, "*"}
+        ]
+        if not candidates:
+            return None
+
+        if request.tool_name != "Bash" or not request.specifier:
+            for rule in candidates:
+                if rule.specifier is None or self._specifier_matches(request, rule.specifier):
+                    return rule
+            return None
+
+        parsed = parse(request.specifier)
+        if not parsed.segments or parsed.unparseable:
+            return None
+
+        first: Rule | None = None
+        for segment in parsed.segments:
+            covering = next(
+                (
+                    rule
+                    for rule in candidates
+                    if rule.specifier is None or match_specifier(segment, rule.specifier)
+                ),
+                None,
+            )
+            if covering is None:
+                return None
+            first = first or covering
+        return first
+
+    def _specifier_matches(self, request: PermissionRequest, pattern: str) -> bool:
+        if not request.specifier:
+            return False
+
+        if request.tool_name == "Bash":
+            # Deny and ask: one dangerous segment is enough to trigger.
+            parsed = parse(request.specifier)
+            return any(match_specifier(segment, pattern) for segment in parsed.segments)
+
+        return match_path(request.specifier, pattern, self.cwd)
+
+    # --- prompting --------------------------------------------------------
+
+    async def request(self, request: PermissionRequest) -> tuple[bool, str]:
+        """Evaluate and, on ASK, prompt through :attr:`asker`.
+
+        Returns ``(allowed, reason)``. The reason is handed to the model on a
+        denial so it can adapt, instead of guessing why a tool went silent.
+        """
+        outcome = self.evaluate(request)
+
+        if outcome.decision is Decision.ALLOW:
+            return True, outcome.reason
+        if outcome.decision is Decision.DENY:
+            return False, outcome.reason
+        if self.asker is None:
+            # Nothing can answer, so the only safe reading of ASK is "no".
+            return False, (
+                "this tool call needs approval, but this session has no way to ask "
+                "(non-interactive). Run hx interactively, or add a permission rule."
+            )
+
+        answer = await self.asker(request)
+        if answer.allowed:
+            self.grant(request, answer.scope)
+            return True, "approved by the user"
+        return False, "the user declined"
+
+    def grant(self, request: PermissionRequest, scope: GrantScope) -> None:
+        """Record an approval. ``ALWAYS`` writes a rule into project settings."""
+        if scope is GrantScope.ONCE:
+            return
+
+        self._session_grants.add((request.tool_name, request.specifier))
+        if scope is not GrantScope.ALWAYS:
+            return
+
+        specifier = self._persistable_specifier(request)
+        rule_text = f"{request.tool_name}({specifier})" if specifier else request.tool_name
+        self.rules.append(parse_rule(rule_text, "project settings", Decision.ALLOW))
+        persist_allow_rule(rule_text, self.cwd)
+
+    def _persistable_specifier(self, request: PermissionRequest) -> str | None:
+        """Generalise a one-off approval into a rule worth keeping.
+
+        A Bash approval becomes a prefix rule for that executable and
+        subcommand, never the exact argument vector - otherwise "always allow"
+        would be useless on the very next invocation.
+        """
+        if not request.specifier:
+            return None
+        if request.tool_name != "Bash":
+            return request.specifier
+
+        parsed = parse(request.specifier)
+        if len(parsed.segments) != 1:
+            return request.specifier
+        segment = parsed.segments[0]
+        head = _rule_prefix(segment)
+        return f"{head}:*"
+
+    # --- modes ------------------------------------------------------------
+
+    def set_mode(self, mode: PermissionMode) -> None:
+        self.mode = mode
+
+    def allowed_tools(self, all_tools: list[str], mutating: set[str] | None = None) -> set[str]:
+        """Tools exposed in the current mode - plan mode hides mutating tools
+        entirely rather than letting the model call them and be refused."""
+        mutating_set = mutating if mutating is not None else set(DEFAULT_MUTATING_TOOLS)
+        if self.mode is not PermissionMode.PLAN:
+            return set(all_tools)
+        return {name for name in all_tools if name not in mutating_set}
+
+
+def _rule_prefix(segment: CommandSegment) -> str:
+    """``git commit -m x`` -> ``git commit``; ``ls -la`` -> ``ls``."""
+    if segment.args and not segment.args[0].startswith("-"):
+        return f"{segment.executable} {segment.args[0]}"
+    return segment.executable
+
+
+_RULE_RE = re.compile(r"^(?P<tool>[A-Za-z_][\w-]*|\*)(?:\((?P<spec>.*)\))?$", re.DOTALL)
+
+
+def parse_rule(text: str, source: str, decision: Decision) -> Rule:
+    """Parse ``Tool(specifier)`` or bare ``Tool``.
+
+    Raises:
+        InvalidRule: on malformed syntax - a rule that silently fails to parse is
+            a rule that silently does not protect anything.
+    """
+    match = _RULE_RE.match(text.strip())
+    if match is None:
+        raise InvalidRule(f"malformed permission rule: {text!r}")
+    specifier = match.group("spec")
+    return Rule(
+        tool=match.group("tool"),
+        specifier=specifier.strip() if specifier else None,
+        decision=decision,
+        source=source,
+    )
+
+
+def match_path(candidate: str, pattern: str, cwd: Path) -> bool:
+    """Glob-match a path specifier, with ``**`` spanning directory separators."""
+    path = Path(candidate).expanduser()
+    absolute = path if path.is_absolute() else (cwd / path)
+    expanded = Path(pattern).expanduser()
+    target = expanded if expanded.is_absolute() else (cwd / expanded)
+
+    regex = _glob_regex(str(target))
+    if regex.match(str(absolute)):
+        return True
+
+    # Also match against the cwd-relative form, so `Edit(src/**)` works.
+    try:
+        relative = absolute.relative_to(cwd)
+    except ValueError:
+        return False
+    return bool(_glob_regex(pattern).match(str(relative)))
+
+
+def _glob_regex(pattern: str) -> re.Pattern[str]:
+    """Translate a glob to a regex.
+
+    ``**`` crosses directory separators and ``*`` does not, and crucially
+    ``**/`` also matches *zero* directories - so ``**/.ssh/**`` protects
+    ``.ssh/id_rsa`` sitting directly in the project, not only nested copies of
+    it. ``fnmatch`` cannot express either rule.
+    """
+    out: list[str] = []
+    index = 0
+    while index < len(pattern):
+        if pattern.startswith("**/", index):
+            out.append("(?:[\\s\\S]*/)?")
+            index += 3
+        elif pattern.startswith("**", index):
+            out.append("[\\s\\S]*")
+            index += 2
+        elif pattern[index] == "*":
+            out.append("[^/]*")
+            index += 1
+        elif pattern[index] == "?":
+            out.append("[^/]")
+            index += 1
+        elif pattern[index] == "[":
+            close = pattern.find("]", index + 1)
+            if close == -1:
+                out.append(re.escape("["))
+                index += 1
+            else:
+                out.append(pattern[index : close + 1])
+                index = close + 1
+        else:
+            out.append(re.escape(pattern[index]))
+            index += 1
+    return re.compile("".join(out) + r"\Z")
+
+
+def load_rules(cwd: Path) -> list[Rule]:
+    """Collect rules from user and project settings, project last."""
+    from hx.config import read_settings_file
+    from hx.paths import project_settings_file, user_settings_file
+
+    rules: list[Rule] = []
+    for path, source in (
+        (user_settings_file(), "user settings"),
+        (project_settings_file(cwd), "project settings"),
+    ):
+        permissions = read_settings_file(path).get("permissions") or {}
+        for key, decision in (
+            ("deny", Decision.DENY),
+            ("ask", Decision.ASK),
+            ("allow", Decision.ALLOW),
+        ):
+            for text in permissions.get(key) or []:
+                rules.append(parse_rule(str(text), source, decision))
+    return rules
+
+
+def persist_allow_rule(rule_text: str, cwd: Path) -> None:
+    """Append an allow rule to the project settings file."""
+    from hx.config import read_settings_file, write_settings_file
+    from hx.paths import project_settings_file
+
+    path = project_settings_file(cwd)
+    data = read_settings_file(path)
+    permissions = data.setdefault("permissions", {})
+    allow = permissions.setdefault("allow", [])
+    if rule_text not in allow:
+        allow.append(rule_text)
+    write_settings_file(path, data)
+
+
+class InvalidRule(Exception):
+    pass

hx/permissions/parser.py

@@ -0,0 +1,306 @@
+"""Shell command decomposition for permission matching.
+
+Matching a rule against the whole command string is unsafe: ``git status && rm
+-rf /`` would match an ``allow: Bash(git status:*)`` rule. Every command is
+split into its individual executed segments and each segment must pass on its
+own.
+
+This is a permission-matching aid, not a shell. When it cannot decompose a
+command with confidence it says so, and the caller must treat that as "ask".
+"""
+
+from __future__ import annotations
+
+import shlex
+from dataclasses import dataclass
+
+OPERATORS = ("&&", "||", ";;", ";", "|&", "|", "\n", "&")
+
+DYNAMIC_EXECUTABLES = frozenset({"eval", "exec", "source", ".", "env"})
+"""Commands whose real payload is decided at runtime. They cannot be decomposed,
+so a command invoking one is reported unparseable rather than guessed at."""
+
+REDIRECT_TOKENS = (">>", ">", "<")
+
+READ_ONLY_COMMANDS = frozenset(
+    {
+        "ls",
+        "cat",
+        "head",
+        "tail",
+        "wc",
+        "file",
+        "stat",
+        "du",
+        "df",
+        "pwd",
+        "echo",
+        "printf",
+        "date",
+        "whoami",
+        "uname",
+        "which",
+        "type",
+        "grep",
+        "rg",
+        "find",
+        "fd",
+        "diff",
+        "tree",
+        "basename",
+        "dirname",
+        "sort",
+        "uniq",
+        "cut",
+        "awk",
+        "sed",
+        "jq",
+        "column",
+    }
+)
+"""Commands that do not mutate state on their own. Used only to relax prompting."""
+
+READ_ONLY_SUBCOMMANDS = {
+    "git": frozenset({"status", "log", "diff", "show", "branch", "remote", "blame", "describe"}),
+}
+
+
+@dataclass(slots=True)
+class CommandSegment:
+    """One command that will actually execute."""
+
+    raw: str
+    executable: str
+    args: tuple[str, ...]
+    in_substitution: bool = False
+    """True for ``$(...)`` / backtick content, which executes just as readily."""
+
+
+@dataclass(slots=True)
+class ParsedCommand:
+    raw: str
+    segments: tuple[CommandSegment, ...]
+    has_redirect_out: bool = False
+    redirect_targets: tuple[str, ...] = ()
+    unparseable: bool = False
+    """Set when the command could not be decomposed with confidence. Callers must
+    treat this as "ask", never as "allow"."""
+
+
+def parse(command: str) -> ParsedCommand:
+    """Split on ``&&``, ``||``, ``;``, ``|``, newlines, and command substitution,
+    respecting quoting.
+
+    Anything not understood sets ``unparseable`` rather than degrading to a
+    naive split - a wrong split here is a real escape.
+    """
+    try:
+        pieces, substitutions, ok = _scan(command)
+    except _ScanError:
+        return ParsedCommand(raw=command, segments=(), unparseable=True)
+
+    segments: list[CommandSegment] = []
+    redirects: list[str] = []
+    unparseable = not ok
+
+    for text, in_sub in [*[(p, False) for p in pieces], *[(s, True) for s in substitutions]]:
+        segment, targets, segment_ok = _to_segment(text, in_sub)
+        redirects.extend(targets)
+        if not segment_ok:
+            unparseable = True
+        if segment is not None:
+            segments.append(segment)
+            if segment.executable in DYNAMIC_EXECUTABLES:
+                unparseable = True
+
+    return ParsedCommand(
+        raw=command,
+        segments=tuple(segments),
+        has_redirect_out=bool(redirects),
+        redirect_targets=tuple(redirects),
+        unparseable=unparseable or not segments,
+    )
+
+
+def _to_segment(text: str, in_sub: bool) -> tuple[CommandSegment | None, list[str], bool]:
+    stripped = text.strip()
+    if not stripped:
+        return None, [], True
+
+    try:
+        tokens = shlex.split(stripped)
+    except ValueError:
+        return None, [], False
+    if not tokens:
+        return None, [], True
+
+    words: list[str] = []
+    redirects: list[str] = []
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        if token in REDIRECT_TOKENS or (token[:1].isdigit() and token[1:] in REDIRECT_TOKENS):
+            index += 1
+            if index < len(tokens):
+                redirects.append(tokens[index])
+            index += 1
+            continue
+        for marker in REDIRECT_TOKENS:
+            if marker in token and not token.startswith(marker):
+                head, _, tail = token.partition(marker)
+                words.append(head)
+                if tail:
+                    redirects.append(tail)
+                break
+        else:
+            words.append(token)
+        index += 1
+
+    words = [word for word in words if word]
+    if not words:
+        return None, redirects, True
+
+    executable = words[0]
+    # A name produced by expansion is only known at runtime.
+    ok = "$" not in executable and "`" not in executable
+    return (
+        CommandSegment(
+            raw=stripped,
+            executable=executable,
+            args=tuple(words[1:]),
+            in_substitution=in_sub,
+        ),
+        redirects,
+        ok,
+    )
+
+
+class _ScanError(Exception):
+    pass
+
+
+def _scan(text: str) -> tuple[list[str], list[str], bool]:
+    """Split into top-level pieces and extracted substitution bodies.
+
+    Returns ``(pieces, substitutions, ok)``. ``ok`` is False when quoting is
+    unbalanced or a substitution never closes.
+    """
+    pieces: list[str] = []
+    substitutions: list[str] = []
+    buffer: list[str] = []
+    ok = True
+
+    index = 0
+    length = len(text)
+    quote: str | None = None
+
+    while index < length:
+        char = text[index]
+
+        if char == "\\" and quote != "'":
+            buffer.append(text[index : index + 2])
+            index += 2
+            continue
+
+        if quote:
+            if char == quote:
+                quote = None
+            # Substitutions are live inside double quotes.
+            elif quote == '"' and (text.startswith("$(", index) or char == "`"):
+                body, consumed, closed = _read_substitution(text, index)
+                substitutions.extend(_recurse(body, substitutions))
+                ok = ok and closed
+                index += consumed
+                continue
+            buffer.append(char)
+            index += 1
+            continue
+
+        if char in "'\"":
+            quote = char
+            buffer.append(char)
+            index += 1
+            continue
+
+        if text.startswith("$(", index) or char == "`":
+            body, consumed, closed = _read_substitution(text, index)
+            substitutions.extend(_recurse(body, substitutions))
+            ok = ok and closed
+            index += consumed
+            continue
+
+        if char in "()":
+            # Subshell grouping: the contents run at this level.
+            index += 1
+            continue
+
+        operator = next((op for op in OPERATORS if text.startswith(op, index)), None)
+        if operator:
+            pieces.append("".join(buffer))
+            buffer.clear()
+            index += len(operator)
+            continue
+
+        buffer.append(char)
+        index += 1
+
+    if quote:
+        ok = False
+    pieces.append("".join(buffer))
+    return [piece for piece in pieces if piece.strip()], substitutions, ok
+
+
+def _recurse(body: str, seen: list[str]) -> list[str]:
+    """Substitution bodies are themselves commands; flatten them one level deep."""
+    inner_pieces, inner_subs, _ = _scan(body)
+    return [*inner_pieces, *[s for s in inner_subs if s not in seen]]
+
+
+def _read_substitution(text: str, index: int) -> tuple[str, int, bool]:
+    """Read a ``$(...)`` or backtick substitution starting at ``index``."""
+    if text[index] == "`":
+        end = text.find("`", index + 1)
+        if end == -1:
+            return text[index + 1 :], len(text) - index, False
+        return text[index + 1 : end], end - index + 1, True
+
+    depth = 0
+    cursor = index + 1  # points at "("
+    while cursor < len(text):
+        if text[cursor] == "(":
+            depth += 1
+        elif text[cursor] == ")":
+            depth -= 1
+            if depth == 0:
+                return text[index + 2 : cursor], cursor - index + 1, True
+        cursor += 1
+    return text[index + 2 :], len(text) - index, False
+
+
+def match_specifier(segment: CommandSegment, pattern: str) -> bool:
+    """Match a segment against a rule specifier such as ``git commit:*`` or ``ls``.
+
+    ``:*`` is a prefix match on the whole command line; a bare executable name
+    matches any invocation of it.
+    """
+    if pattern in {"*", ":*"}:
+        return True
+
+    command_line = " ".join([segment.executable, *segment.args])
+    if pattern.endswith(":*"):
+        prefix = pattern[:-2].strip()
+        return command_line == prefix or command_line.startswith(prefix + " ")
+    if " " in pattern:
+        return command_line == pattern
+    return segment.executable == pattern
+
+
+def is_read_only(segment: CommandSegment) -> bool:
+    """Heuristic allowlist of non-mutating commands (``ls``, ``cat``, ``git status``).
+
+    Used only to relax prompting, never to grant something an explicit deny rule
+    covers.
+    """
+    if subcommands := READ_ONLY_SUBCOMMANDS.get(segment.executable):
+        return bool(segment.args) and segment.args[0] in subcommands
+    return segment.executable in READ_ONLY_COMMANDS