agentperm 0.2.0__tar.gz → 0.2.1__tar.gz

{agentperm-0.2.0 → agentperm-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentperm
-Version: 0.2.0
+Version: 0.2.1
 Summary: Permission policy mediator for Claude Code, Codex, OpenCode, and Gemini CLI.
 Project-URL: Homepage, https://github.com/jacks0n/agentperm
 Project-URL: Repository, https://github.com/jacks0n/agentperm
@@ -117,7 +117,7 @@ After `install`, each agent calls agentperm before running a tool. Your native s
 Rules go in `allow`, `ask`, or `deny`. Three forms:
 
 - **`"Bash(git status:*)"`** — match a shell command by prefix (`git status` and anything after it). Drop the `:*` for an exact match, or use glob tokens: `*` matches one argument, `**` matches zero or more (e.g. `Bash(pnpm --dir * build:*)`).
-- **`"Read"`, `"WebFetch(domain:github.com)"`** — match a named, non-shell tool, optionally scoped.
+- **`"Read"`, `"WebFetch(domain:github.com)"`** — match a non-shell tool by name (`Read`, `mcp__memory__*`, `*`). An optional specifier scopes by the tool's input fields: `WebFetch(domain:github.com)` matches a URL field on that host or a subdomain; any other specifier is a path glob (`*` within a segment, `**` across) on the tool's path fields (`Read(/etc/**)`, `Edit(src/*)`). Bare name (or `(*)`) matches any input.
 - **Object form** — match on flags: `{ "tool": "Bash", "command": ["sed"], "when": { "hasOption": ["-i"] }, "reason": "..." }`.
 
 In a compound command the strictest segment decides — one unrecognized command turns the whole line into an `ask`, and **deny always wins**. Full grammar: [policy reference](docs/policy-reference.md).
@@ -163,6 +163,14 @@ So you allow a tool broadly once, and a single repo can both add its own command
 
 Create or edit the project file with `agentperm edit --local` (it writes to your git repo root). `import` and `install` always act on the global file and your agents' global hooks.
 
+## Examples
+
+Ready-to-crib policies in [`examples/`](examples/):
+
+- [`starter.agent-permissions.jsonc`](examples/starter.agent-permissions.jsonc) — a minimal global policy to begin from: read-only shell and tools allowed, `sed -i` asks, `sudo` / `rm -rf` denied.
+- [`global.agent-permissions.jsonc`](examples/global.agent-permissions.jsonc) — a fuller real-world global policy: a large allow-list of read-only AWS and CLI commands, the `sed -i` ask rule, a deny list, and shell-redirection defaults.
+- [`project.agent-permissions.jsonc`](examples/project.agent-permissions.jsonc) — this repo's own per-project file, allowing just its dev-tooling commands on top of whatever your global policy permits.
+
 ## Commands
 
 | Command | What it does |

{agentperm-0.2.0 → agentperm-0.2.1}/README.md

@@ -58,7 +58,7 @@ After `install`, each agent calls agentperm before running a tool. Your native s
 Rules go in `allow`, `ask`, or `deny`. Three forms:
 
 - **`"Bash(git status:*)"`** — match a shell command by prefix (`git status` and anything after it). Drop the `:*` for an exact match, or use glob tokens: `*` matches one argument, `**` matches zero or more (e.g. `Bash(pnpm --dir * build:*)`).
-- **`"Read"`, `"WebFetch(domain:github.com)"`** — match a named, non-shell tool, optionally scoped.
+- **`"Read"`, `"WebFetch(domain:github.com)"`** — match a non-shell tool by name (`Read`, `mcp__memory__*`, `*`). An optional specifier scopes by the tool's input fields: `WebFetch(domain:github.com)` matches a URL field on that host or a subdomain; any other specifier is a path glob (`*` within a segment, `**` across) on the tool's path fields (`Read(/etc/**)`, `Edit(src/*)`). Bare name (or `(*)`) matches any input.
 - **Object form** — match on flags: `{ "tool": "Bash", "command": ["sed"], "when": { "hasOption": ["-i"] }, "reason": "..." }`.
 
 In a compound command the strictest segment decides — one unrecognized command turns the whole line into an `ask`, and **deny always wins**. Full grammar: [policy reference](docs/policy-reference.md).
@@ -104,6 +104,14 @@ So you allow a tool broadly once, and a single repo can both add its own command
 
 Create or edit the project file with `agentperm edit --local` (it writes to your git repo root). `import` and `install` always act on the global file and your agents' global hooks.
 
+## Examples
+
+Ready-to-crib policies in [`examples/`](examples/):
+
+- [`starter.agent-permissions.jsonc`](examples/starter.agent-permissions.jsonc) — a minimal global policy to begin from: read-only shell and tools allowed, `sed -i` asks, `sudo` / `rm -rf` denied.
+- [`global.agent-permissions.jsonc`](examples/global.agent-permissions.jsonc) — a fuller real-world global policy: a large allow-list of read-only AWS and CLI commands, the `sed -i` ask rule, a deny list, and shell-redirection defaults.
+- [`project.agent-permissions.jsonc`](examples/project.agent-permissions.jsonc) — this repo's own per-project file, allowing just its dev-tooling commands on top of whatever your global policy permits.
+
 ## Commands
 
 | Command | What it does |

{agentperm-0.2.0 → agentperm-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentperm"
-version = "0.2.0"
+version = "0.2.1"
 description = "Permission policy mediator for Claude Code, Codex, OpenCode, and Gemini CLI."
 readme = "README.md"
 license = { file = "LICENSE" }

{agentperm-0.2.0 → agentperm-0.2.1}/src/agentperm/__init__.py

@@ -17,13 +17,16 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import posixpath
 import re
 import shlex
 import shutil
 import subprocess
 import sys
 import tempfile
+import urllib.parse
 from abc import ABC, abstractmethod
+from collections import deque
 from collections.abc import Iterable, Iterator, Mapping, Sequence
 from dataclasses import dataclass, field
 from enum import StrEnum
@@ -135,6 +138,12 @@ class Pipeline:
     unparseable_reason: str = ""
 
 
+# A tool request's input flattened to (field-name, value) pairs, e.g.
+# (("url", "https://github.com/x"), ("prompt", "…")). Keeping field identity lets a scoped
+# rule match only the authoritative field, never a look-alike value in another field.
+ToolArguments = tuple[tuple[str, str], ...]
+
+
 class Request:
     """Marker base for ShellRequest / ToolRequest. Sum-typed via isinstance dispatch."""
 
@@ -147,6 +156,7 @@ class ShellRequest(Request):
 @dataclass(frozen=True)
 class ToolRequest(Request):
     tool: str
+    arguments: ToolArguments = ()
 
 
 # Permission rules are a sum type. Each rule knows how to match its kind of request.
@@ -232,21 +242,132 @@ class BashOption(Rule):
         }
 
 
+_URL_ARG_KEYS = frozenset({"url", "uri", "href"})
+_PATH_ARG_KEYS = frozenset(
+    {"path", "file_path", "filepath", "paths", "file_paths", "notebook_path", "absolute_path"}
+)
+_MAX_ARG_NODES = 1000
+
+
 @dataclass(frozen=True)
 class NamedTool(Rule):
-    """Tool name pattern: exact (``Read``), wildcard (``*``), or prefix (``mcp__memory__*``)."""
+    """Non-shell tool rule: a name plus an optional argument specifier.
 
-    pattern: str
+    Name matches exactly (``Read``), as a prefix glob (``mcp__memory__*``), or as ``*``.
+    The optional specifier scopes by the tool's input, keyed by conventional field names so
+    the same syntax works for any tool without hard-coding tool names:
 
-    def matches(self, name: str) -> bool:
-        if self.pattern in ("*", name):
+    - ``WebFetch(domain:github.com)`` — a URL field (``url`` / ``uri`` / ``href``) whose
+      host is ``github.com`` or a subdomain.
+    - ``Read(/etc/**)`` / ``Edit(src/*)`` — a path field (``path`` / ``file_path`` / …)
+      matching the glob: ``*`` within one segment, ``**`` across ``/``.
+    - bare name / ``(*)`` / ``()`` — matches the tool regardless of input.
+    """
+
+    name: str
+    specifier: str | None = None
+
+    def matches(self, name: str, arguments: ToolArguments = ()) -> bool:
+        if not self._name_matches(name):
+            return False
+        if self.specifier is None or self.specifier == "*":
             return True
-        if self.pattern.endswith("*"):
-            return name.startswith(self.pattern[:-1])
-        return False
+        return self._specifier_matches(arguments)
+
+    def _name_matches(self, name: str) -> bool:
+        if self.name in ("*", name):
+            return True
+        return self.name.endswith("*") and name.startswith(self.name[:-1])
+
+    def _specifier_matches(self, arguments: ToolArguments) -> bool:
+        spec = self.specifier
+        if spec is None:
+            return True
+        if spec.startswith("domain:"):
+            host = spec[len("domain:") :]
+            return any(_url_host_matches(value, host) for key, value in arguments if key.lower() in _URL_ARG_KEYS)
+        return any(_path_glob_matches(spec, value) for key, value in arguments if key.lower() in _PATH_ARG_KEYS)
 
     def serialize(self) -> str:
-        return self.pattern
+        return self.name if self.specifier is None else f"{self.name}({self.specifier})"
+
+
+def _url_host_matches(value: str, host: str) -> bool:
+    """True if ``value`` is a URL whose host equals ``host`` or is a subdomain of it."""
+    target = _idna_host(host)
+    if not target:
+        return False
+    try:
+        parsed = urllib.parse.urlparse(value if "//" in value else f"//{value}")
+        actual = _idna_host(parsed.hostname or "")
+    except ValueError:
+        return False
+    return bool(actual) and (actual == target or actual.endswith(f".{target}"))
+
+
+def _idna_host(host: str) -> str:
+    """Canonicalize a host for comparison: lowercase, no trailing root dot, IDNA/ASCII form."""
+    host = host.rstrip(".").lower()
+    if not host:
+        return ""
+    try:
+        return host.encode("idna").decode("ascii")
+    except (UnicodeError, ValueError):
+        return host
+
+
+def _path_glob_matches(pattern: str, value: str) -> bool:
+    """Glob match where ``*`` stays within one path segment and ``**`` crosses ``/``.
+
+    The value's ``.``/``..`` segments are normalized first, so a scope can't be escaped via
+    traversal (``/repo/src/../secrets`` is matched as ``/repo/secrets``).
+    """
+    return re.fullmatch(_glob_to_regex(pattern), posixpath.normpath(value)) is not None
+
+
+def _glob_to_regex(pattern: str) -> str:
+    out: list[str] = []
+    i = 0
+    while i < len(pattern):
+        if pattern.startswith("**", i):
+            out.append(".*")
+            i += 2
+        elif pattern[i] == "*":
+            out.append("[^/]*")
+            i += 1
+        elif pattern[i] == "?":
+            out.append("[^/]")
+            i += 1
+        else:
+            out.append(re.escape(pattern[i]))
+            i += 1
+    return "".join(out)
+
+
+def _tool_arguments(value: object) -> ToolArguments:
+    """Flatten a tool-input payload to (field-name, string-value) pairs for scoping.
+
+    Breadth-first and bounded by ``_MAX_ARG_NODES`` so a deep or huge payload can't cause
+    ``RecursionError`` or unbounded work; shallow (authoritative) fields are kept first.
+    List items inherit their containing field's name.
+    """
+    out: list[tuple[str, str]] = []
+    queue: deque[tuple[str, object]] = deque([("", value)])
+    seen = 0
+    while queue and seen < _MAX_ARG_NODES:
+        key, node = queue.popleft()
+        seen += 1
+        if isinstance(node, str):
+            out.append((key, node))
+        elif isinstance(node, dict):
+            for sub_key, sub_value in node.items():
+                if isinstance(sub_key, str) and len(queue) < _MAX_ARG_NODES:
+                    queue.append((sub_key, sub_value))
+        elif isinstance(node, list):
+            for item in node:
+                if len(queue) < _MAX_ARG_NODES:
+                    queue.append((key, item))
+    return tuple(out)
 
 
 def _basename(arg: str) -> str:
@@ -299,7 +420,7 @@ class Policy:
         if isinstance(request, ShellRequest):
             return self._decide_shell(request.pipeline)
         if isinstance(request, ToolRequest):
-            return self._decide_tool(request.tool)
+            return self._decide_tool(request.tool, request.arguments)
         return Verdict(Decision.NoOpinion, "unrecognized request")
 
     def all_rules(self) -> Iterator[tuple[Decision, Rule]]:
@@ -369,9 +490,9 @@ class Policy:
             return Verdict(Decision.Allow, "inert shell builtin")
         return Verdict(Decision.NoOpinion, f"no rule matched {segment.argv[0] if segment.argv else '<empty>'!r}")
 
-    def _decide_tool(self, name: str) -> Verdict:
+    def _decide_tool(self, name: str, arguments: ToolArguments) -> Verdict:
         for decision, rule in self.all_rules():
-            if isinstance(rule, NamedTool) and rule.matches(name):
+            if isinstance(rule, NamedTool) and rule.matches(name, arguments):
                 return Verdict(decision, _format_rule(rule, decision))
         return Verdict(Decision.NoOpinion, f"no rule matched {name!r}")
 
@@ -1011,6 +1132,10 @@ def _parse_string_rule(text: str) -> Rule | None:
     bash_exact = re.fullmatch(r"Bash\((.+)\)", text)
     if bash_exact:
         return BashCommand(tuple(bash_exact.group(1).split()), trailing_wildcard=False)
+    named = re.fullmatch(r"(.+?)\((.*)\)", text)
+    if named:
+        spec = named.group(2)
+        return NamedTool(named.group(1), None if spec in ("", "*") else spec)
     if text:
         return NamedTool(text)
     return None
@@ -1250,7 +1375,7 @@ class ClaudeAdapter(AgentAdapter):
             tool_input = payload.get("tool_input")
             command = tool_input.get("command") if isinstance(tool_input, dict) else None
             return ShellRequest(parse_pipeline(command if isinstance(command, str) else ""))
-        return ToolRequest(tool_name)
+        return ToolRequest(tool_name, _tool_arguments(payload.get("tool_input")))
 
     def write_verdict(
         self,
@@ -1346,7 +1471,7 @@ class CodexAdapter(AgentAdapter):
                     command = metadata.get("command") if isinstance(metadata, dict) else None
                     return ShellRequest(parse_pipeline(command if isinstance(command, str) else ""))
                 if isinstance(permission_type, str):
-                    return ToolRequest(permission_type)
+                    return ToolRequest(permission_type, _tool_arguments(metadata))
                 return None
         return ClaudeAdapter().parse_event(payload, event_name)
 
@@ -1518,7 +1643,7 @@ class OpencodeAdapter(AgentAdapter):
             command = metadata.get("command")
             return ShellRequest(parse_pipeline(command if isinstance(command, str) else ""))
         if isinstance(permission_type, str):
-            return ToolRequest(permission_type)
+            return ToolRequest(_opencode_tool_name(permission_type), _tool_arguments(metadata))
         return None
 
     def write_verdict(self, verdict: Verdict, event_name: str) -> None:
@@ -1550,19 +1675,25 @@ def _opencode_rule(tool: str, pattern: str) -> Rule | None:
         if pattern == "*":
             return None
         return BashCommand(tuple(pattern.split()))
-    return NamedTool(
-        {
-            "read": "Read",
-            "grep": "Grep",
-            "glob": "Glob",
-            "edit": "Edit",
-            "write": "Write",
-            "webfetch": "WebFetch",
-            "websearch": "WebSearch",
-            "task": "Task",
-            "skill": "Skill",
-        }.get(tool, tool)
-    )
+    return NamedTool(_opencode_tool_name(tool))
+
+
+_OPENCODE_TOOL_NAMES = {
+    "read": "Read",
+    "grep": "Grep",
+    "glob": "Glob",
+    "edit": "Edit",
+    "write": "Write",
+    "webfetch": "WebFetch",
+    "websearch": "WebSearch",
+    "task": "Task",
+    "skill": "Skill",
+}
+
+
+def _opencode_tool_name(tool: str) -> str:
+    """Canonicalize an OpenCode tool key (``webfetch``) to the policy name (``WebFetch``)."""
+    return _OPENCODE_TOOL_NAMES.get(tool, tool)
 
 
 def _opencode_decision(action: str) -> Decision | None:
@@ -1584,7 +1715,7 @@ class GeminiAdapter(AgentAdapter):
         if tool_name == "run_shell_command":
             command = tool_input.get("command") if isinstance(tool_input, dict) else None
             return ShellRequest(parse_pipeline(command if isinstance(command, str) else ""))
-        return ToolRequest(_gemini_tool_name(tool_name))
+        return ToolRequest(_gemini_tool_name(tool_name), _tool_arguments(tool_input))
 
     def write_verdict(self, verdict: Verdict, event_name: str) -> None:
         if verdict.decision is Decision.NoOpinion:

{agentperm-0.2.0 → agentperm-0.2.1}/tests/test_adapters.py

@@ -106,6 +106,7 @@ def test_claude_parse_non_bash_tool_event():
     request = adapter.parse_event({"tool_name": "Read", "tool_input": {"file_path": "/tmp/x"}}, "PreToolUse")
     assert isinstance(request, ToolRequest)
     assert request.tool == "Read"
+    assert ("file_path", "/tmp/x") in request.arguments  # input threaded through for scoping
 
 
 def test_claude_write_verdict_no_opinion_emits_empty():
@@ -321,11 +322,12 @@ def test_codex_parse_permission_request_bash_modern_envelope():
 def test_codex_parse_permission_request_other_tool():
     adapter = CodexAdapter()
     request = adapter.parse_event(
-        {"permission": {"type": "apply_patch"}},
+        {"permission": {"type": "apply_patch", "metadata": {"file_path": "/tmp/x"}}},
         "PermissionRequest",
     )
     assert isinstance(request, ToolRequest)
     assert request.tool == "apply_patch"
+    assert ("file_path", "/tmp/x") in request.arguments  # metadata threaded through for scoping
 
 
 def test_codex_pretooluse_passes_allow_through():
@@ -417,6 +419,17 @@ def test_opencode_parse_bash_event():
     assert request.pipeline.segments[0].argv == ("rm", "-rf", "/")
 
 
+def test_opencode_parse_non_bash_event_threads_arguments():
+    adapter = OpencodeAdapter()
+    request = adapter.parse_event(
+        {"permission": {"type": "webfetch", "metadata": {"url": "https://github.com/x"}}},
+        "permission.ask",
+    )
+    assert isinstance(request, ToolRequest)
+    assert request.tool == "WebFetch"  # canonicalized to match imported/written rule names
+    assert ("url", "https://github.com/x") in request.arguments  # metadata threaded through
+
+
 def test_opencode_write_verdict_emits_status():
     adapter = OpencodeAdapter()
     buf = io.StringIO()
@@ -456,6 +469,7 @@ def test_gemini_parse_read_tool_event():
     )
     assert isinstance(request, ToolRequest)
     assert request.tool == "Read"
+    assert ("absolute_path", "/tmp/x") in request.arguments  # input threaded through for scoping
 
 
 def test_gemini_ask_blocks_because_beforetool_cannot_prompt():

{agentperm-0.2.0 → agentperm-0.2.1}/tests/test_policy.py

@@ -19,6 +19,7 @@ from agentperm import (
     coerce_for_pane_bypass,
     coerce_for_permission_mode,
     parse_pipeline,
+    parse_rule,
 )
 
 # ---- Rule matching --------------------------------------------------------
@@ -128,6 +129,88 @@ def test_named_tool_prefix_glob():
     assert NamedTool("mcp__memory__*").matches("mcp__other__x") is False
 
 
+def test_named_tool_no_specifier_ignores_arguments():
+    # Bare name (and the `*` specifier) match the tool regardless of input.
+    assert NamedTool("Read").matches("Read", (("file_path", "/etc/passwd"),)) is True
+    assert NamedTool("Read", "*").matches("Read", (("file_path", "/anything"),)) is True
+
+
+def test_named_tool_domain_specifier_matches_url_field():
+    rule = NamedTool("WebFetch", "domain:github.com")
+    assert rule.matches("WebFetch", (("url", "https://github.com/a/b"),)) is True
+    assert rule.matches("WebFetch", (("url", "https://api.github.com/x"),)) is True  # subdomain
+    assert rule.matches("WebFetch", (("url", "https://github.com./x"),)) is True  # trailing root dot
+    assert rule.matches("WebFetch", (("url", "https://evil.com/x"),)) is False
+    assert rule.matches("WebFetch", (("url", "https://notgithub.com/x"),)) is False  # not a suffix
+    assert rule.matches("WebFetch", ()) is False  # no URL to check
+
+
+def test_named_tool_domain_ignores_url_in_non_url_field():
+    # A github.com URL sitting in a non-URL field (e.g. prompt) must NOT satisfy the rule.
+    rule = NamedTool("WebFetch", "domain:github.com")
+    args = (("url", "https://evil.example/x"), ("prompt", "compare with https://github.com/x"))
+    assert rule.matches("WebFetch", args) is False
+
+
+def test_named_tool_domain_does_not_crash_on_malformed_url():
+    rule = NamedTool("WebFetch", "domain:github.com")
+    assert rule.matches("WebFetch", (("url", "http://[::1"),)) is False  # no exception
+
+
+def test_named_tool_domain_idna_normalizes_host():
+    # Unicode and punycode forms of the same host are equivalent in both directions.
+    assert NamedTool("WebFetch", "domain:bücher.example").matches(
+        "WebFetch", (("url", "https://xn--bcher-kva.example/x"),)
+    ) is True
+    assert NamedTool("WebFetch", "domain:xn--bcher-kva.example").matches(
+        "WebFetch", (("url", "https://bücher.example/x"),)
+    ) is True
+
+
+def test_named_tool_glob_specifier_matches_path_field():
+    rule = NamedTool("Read", "/etc/**")
+    assert rule.matches("Read", (("file_path", "/etc/passwd"),)) is True
+    assert rule.matches("Read", (("file_path", "/etc/ssl/cert.pem"),)) is True  # ** crosses /
+    assert rule.matches("Read", (("file_path", "/home/user/x"),)) is False
+    # `*` stays within one segment; the same mechanism scopes any tool, not just Read
+    assert NamedTool("Edit", "src/*").matches("Edit", (("file_path", "src/main.py"),)) is True
+    assert NamedTool("Edit", "src/*").matches("Edit", (("file_path", "src/sub/secret"),)) is False
+
+
+def test_named_tool_glob_normalizes_path_traversal():
+    # `..` is collapsed before matching, so a scope can't be escaped via traversal.
+    assert NamedTool("Read", "/repo/src/**").matches(
+        "Read", (("file_path", "/repo/src/../secrets/token"),)
+    ) is False
+    assert NamedTool("Read", "/repo/secrets/**").matches(
+        "Read", (("file_path", "/repo/src/../secrets/token"),)
+    ) is True
+
+
+def test_named_tool_glob_ignores_path_in_non_path_field():
+    # Path-like text in a non-path field (e.g. an edit's old_string) must NOT match.
+    rule = NamedTool("Edit", "src/**")
+    args = (("file_path", "/etc/passwd"), ("old_string", "import src.app"))
+    assert rule.matches("Edit", args) is False
+
+
+def test_named_tool_specifier_requires_name_match():
+    # specifier only applies once the name matches
+    assert NamedTool("Read", "/etc/**").matches("Write", (("file_path", "/etc/passwd"),)) is False
+
+
+def test_parse_round_trips_scoped_named_tool():
+    rule = parse_rule("WebFetch(domain:github.com)")
+    assert isinstance(rule, NamedTool)
+    assert (rule.name, rule.specifier) == ("WebFetch", "domain:github.com")
+    assert rule.serialize() == "WebFetch(domain:github.com)"
+    # `Name(*)` and `Name()` normalize to the bare name (no dead rules)
+    read_star = parse_rule("Read(*)")
+    read_bare = parse_rule("Read")
+    assert isinstance(read_star, NamedTool) and read_star.serialize() == "Read"
+    assert isinstance(read_bare, NamedTool) and read_bare.serialize() == "Read"
+
+
 # ---- Strictness aggregation ----------------------------------------------