gemcode 0.3.30__py3-none-any.whl → 0.3.32__py3-none-any.whl

gemcode/agent.py

@@ -49,11 +49,77 @@ def _chain_before_model_callbacks(*callbacks):
 
 
 def _load_gemini_md(project_root: Path) -> str:
-  for name in ("GEMINI.md", "gemini.md"):
-    p = project_root / name
-    if p.is_file():
-      return p.read_text(encoding="utf-8", errors="replace")[:50_000]
-  return ""
+  """
+  Load GEMINI.md / .gemcode/NOTES.md from a Claude Code–style hierarchy.
+
+  Priority (later entries override earlier ones, all are concatenated):
+    1. ~/.gemcode/GEMINI.md           — user-global instructions (all projects)
+    2. Walk UP from project_root: each directory's GEMINI.md / .gemcode/GEMINI.md
+       (org-level files at higher dirs, project-level at project_root)
+    3. project_root/GEMINI.md         — the primary project instructions
+    4. project_root/.gemcode/GEMINI.md — alternative location
+    5. project_root/.gemcode/notes.md  — agent auto-generated notes (read-only context)
+
+  Max total: 80,000 chars.  Each file is capped at 30,000 chars.
+  HTML comments (<!-- ... -->) are stripped before injection (saves tokens).
+  """
+  import re
+
+  _NAMES = ("GEMINI.md", "gemini.md", ".gemcode/GEMINI.md")
+  _FILE_CAP = 30_000
+  _TOTAL_CAP = 80_000
+  _COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+
+  def _read(p: Path) -> str:
+    if not p.is_file():
+      return ""
+    try:
+      raw = p.read_text(encoding="utf-8", errors="replace")[:_FILE_CAP]
+      # Strip HTML comments (like Claude Code does — saves tokens)
+      return _COMMENT_RE.sub("", raw).strip()
+    except OSError:
+      return ""
+
+  seen: set[Path] = set()
+  sections: list[str] = []
+
+  def _add(p: Path, label: str | None = None) -> None:
+    resolved = p.resolve()
+    if resolved in seen:
+      return
+    seen.add(resolved)
+    text = _read(p)
+    if text:
+      sections.append(f"<!-- {label or str(p)} -->\n{text}" if label else text)
+
+  # 1. User-global: ~/.gemcode/GEMINI.md
+  user_global = Path.home() / ".gemcode" / "GEMINI.md"
+  _add(user_global, "user-global (~/.gemcode/GEMINI.md)")
+
+  # 2. Walk UP from project_root to filesystem root — loads org / monorepo-level instructions
+  walk = project_root.resolve()
+  ancestors = []
+  while walk != walk.parent:
+    walk = walk.parent
+    if walk == Path.home() or walk == Path("/"):
+      break
+    ancestors.append(walk)
+  # Walk outer→inner (org first, closer dirs later — later = higher priority)
+  for ancestor in reversed(ancestors):
+    for name in _NAMES:
+      _add(ancestor / name)
+
+  # 3+4. Project-root level instructions (primary location)
+  for name in ("GEMINI.md", "gemini.md", ".gemcode/GEMINI.md", ".gemcode/gemini.md"):
+    _add(project_root / name)
+
+  # 5. Agent-generated notes (informational context, not instructions)
+  notes = project_root / ".gemcode" / "notes.md"
+  if notes.is_file():
+    _add(notes, "agent notes (.gemcode/notes.md)")
+
+  combined = "\n\n---\n\n".join(s for s in sections if s.strip())
+  return combined[:_TOTAL_CAP]
 
 
 def _build_runtime_facts(cfg: GemCodeConfig) -> str:
@@ -383,6 +449,13 @@ You have native deep thinking capability — use it actively:
   - For **dev servers**: `bash("npm run dev", background=True, cwd_subdir="frontend")`
   - For **subfolders**: `bash("cargo build --release", cwd_subdir="backend")`
 
+- **`bash_stream`** — streaming version of bash: yields stdout line-by-line in real-time. Use for long-running commands where the user wants to see live progress:
+  - `bash_stream("pytest -v tests/")` — see each test result as it runs
+  - `bash_stream("npm run build")` — watch build progress in real-time
+  - `bash_stream("pip install -r requirements.txt")` — see install progress
+  - `bash_stream("tail -f logs/app.log", timeout_seconds=60)` — live log watching
+  - Prefer `bash_stream` over `bash` whenever the command takes > 5 seconds and progress visibility matters
+
 - **`run_command`** — simple single-executable calls without shell features:
   - `run_command("npm", args=["install", "--legacy-peer-deps"])` — clean npm install
   - `run_command("python3", args=["-m", "pytest", "--version"])` — version check
@@ -527,7 +600,23 @@ For tasks where quality matters:
 - Prefer small, testable, accurate changes over broad rewrites.
 
 ## Workspace scope
-All file tools use paths **relative to the project root** (where GemCode was started). The root may be the home folder — subfolders like `Desktop`, `Desktop/code`, `Documents` are inside the sandbox. Call `list_directory("Desktop")` or `glob_files("**/*name*.ts")` instead of assuming access is blocked. Only treat access as denied when a tool returns an explicit `error`."""
+All file tools use paths **relative to the project root** (where GemCode was started). The root may be the home folder — subfolders like `Desktop`, `Desktop/code`, `Documents` are inside the sandbox. Call `list_directory("Desktop")` or `glob_files("**/*name*.ts")` instead of assuming access is blocked. Only treat access as denied when a tool returns an explicit `error`.
+
+## Agent notes (.gemcode/notes.md)
+You have two tools to persist project insights across sessions, like Claude Code's auto-memory:
+
+- **`append_project_note(note)`** — write a note to `.gemcode/notes.md`. Use this proactively when you discover something worth remembering:
+  - Build/test/lint commands you discover ("Build: `npm run build` — requires Node 20")
+  - Key file locations ("Auth middleware: `src/middleware/auth.ts`")
+  - Known issues or patterns ("DB migrations: always run `prisma db push` after schema changes")
+  - User workflow preferences ("User prefers running tests before committing")
+  - Architecture decisions or tricky patterns
+  
+  Call this **immediately** when you discover something useful — not just at the end of tasks.
+  Notes are loaded at session start so future sessions inherit this knowledge.
+
+- **`read_project_notes()`** — read current notes before starting a new project task.
+  If notes exist and you haven't read them yet, read them first to avoid re-discovering known information."""
 
   # Inject capability-specific strategy sections only when those caps are on.
   if getattr(cfg, "enable_computer_use", False):
@@ -590,6 +679,14 @@ def build_root_agent(
   except Exception:
     pass
 
+  # Agent auto-notes: write project insights to .gemcode/notes.md (Claude Code MEMORY.md equivalent)
+  try:
+    from gemcode.tools.notes import build_notes_tools
+    notes_tools = build_notes_tools(cfg.project_root)
+    tools = [*tools, *notes_tools]
+  except Exception:
+    pass
+
   if extra_tools:
     tools = [*tools, *extra_tools]
 

gemcode/callbacks.py

@@ -157,6 +157,24 @@ def make_before_tool_callback(cfg: GemCodeConfig):
     except Exception:
       pass
 
+    # ── Permission rules (.gemcode/settings.json allow/deny) ──────────────
+    # Evaluated before the normal permission flow so explicit allow/deny rules
+    # override cfg.permission_mode and interactive prompts.
+    try:
+      from gemcode.permissions import check_rules
+      rule_result = check_rules(name, args or {}, cfg.project_root)
+      if rule_result == "deny":
+        return {
+          "error": f"Tool call blocked by .gemcode/settings.json deny rule for '{name}'.",
+          "error_kind": _ERROR_KIND_PERMISSION_DENIED,
+        }
+      if rule_result == "allow":
+        # Explicit allow — skip the normal permission prompt entirely
+        # but still run post-tool hook (logging/audit).
+        pass  # fall through to tool execution
+    except Exception:
+      rule_result = None
+
     streak = 0
     if tool_context is not None:
       try:
@@ -181,6 +199,10 @@ def make_before_tool_callback(cfg: GemCodeConfig):
         "error_kind": _ERROR_KIND_CIRCUIT_BREAKER,
       }
 
+    # If permission rules explicitly allowed this tool call, skip the gate entirely.
+    if rule_result == "allow" and (name in MUTATING_TOOLS or is_computer_tool):
+      return None  # allow without prompting
+
     if name in MUTATING_TOOLS or is_computer_tool:
       if cfg.permission_mode == "strict":
         if is_computer_tool:

gemcode/cli.py

@@ -151,13 +151,8 @@ async def _run_prompt(
   _maybe_prompt_google_api_key()
   require_google_api_key()
   _initialize_gemcode_project(cfg)
-  extra: list = []
-  if use_mcp:
-    from gemcode.mcp_loader import load_mcp_toolsets
-
-    extra = load_mcp_toolsets(cfg)
-
-  runner = create_runner(cfg, extra_tools=extra or None)
+  # MCP and OpenAPI toolsets are now loaded inside create_runner() directly.
+  runner = create_runner(cfg, extra_tools=None)
   try:
     collected = await run_turn(
         runner,
@@ -184,13 +179,8 @@ async def _run_repl(cfg: GemCodeConfig, session_id: str, *, use_mcp: bool) -> No
   require_google_api_key()
   _initialize_gemcode_project(cfg)
 
-  extra: list = []
-  if use_mcp:
-    from gemcode.mcp_loader import load_mcp_toolsets
-
-    extra = load_mcp_toolsets(cfg)
-
-  runner = create_runner(cfg, extra_tools=extra or None)
+  # MCP and OpenAPI toolsets are now loaded inside create_runner() directly.
+  runner = create_runner(cfg, extra_tools=None)
   try:
     # For CLI UX, show concise tool summaries (helps users see what ran).
     if os.environ.get("GEMCODE_EMIT_TOOL_USE_SUMMARIES") is None:

gemcode/mcp_loader.py

@@ -1,27 +1,60 @@
 """
 Optional MCP toolsets from `.gemcode/mcp.json`.
 
+Now supports all three ADK connection types — like Claude Code's MCP integration:
+
 Schema (example):
 {
   "servers": [
     {
-      "name": "docs",
-      "stdio": { "command": "npx", "args": ["-y", "@some/mcp-server"] }
+      "name": "filesystem",
+      "stdio": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
+    },
+    {
+      "name": "github",
+      "http": {
+        "url": "https://api.githubcopilot.com/mcp/",
+        "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
+      }
+    },
+    {
+      "name": "notion",
+      "sse": { "url": "https://mcp.notion.com/sse" }
     }
   ]
 }
 
+Connection types:
+  stdio  — local subprocess (npx, python, etc.) — legacy, always worked
+  http   — Streamable HTTP (remote servers, Cloud Run, Smithery.ai)
+  sse    — Server-Sent Events (older remote servers; use http when possible)
+
+Header values support ${ENV_VAR} substitution from environment.
+
 Requires: pip install gemcode[mcp]
 """
 
 from __future__ import annotations
 
 import json
+import os
+import re
 from pathlib import Path
 from typing import Any
 
 from gemcode.config import GemCodeConfig
 
+_ENV_VAR_RE = re.compile(r"\$\{([A-Z_][A-Z0-9_]*)\}")
+
+
+def _expand_env(value: str) -> str:
+  """Expand ${VAR} placeholders from environment variables."""
+  return _ENV_VAR_RE.sub(lambda m: os.environ.get(m.group(1), m.group(0)), value)
+
+
+def _expand_headers(headers: dict) -> dict:
+  return {k: _expand_env(str(v)) for k, v in headers.items()}
+
 
 def load_mcp_toolsets(cfg: GemCodeConfig) -> list:
   path = cfg.project_root / ".gemcode" / "mcp.json"
@@ -40,18 +73,75 @@ def load_mcp_toolsets(cfg: GemCodeConfig) -> list:
 
   servers = data.get("servers") or []
   toolsets: list[Any] = []
+
   for s in servers:
-    stdio = s.get("stdio") or {}
-    cmd = stdio.get("command")
-    args = stdio.get("args") or []
-    if not cmd:
-      continue
-    params = StdioServerParameters(command=cmd, args=args)
     prefix = s.get("name") or "mcp"
-    toolsets.append(
-      McpToolset(
-        connection_params=params,
-        tool_name_prefix=prefix,
+    tool_filter: list[str] | None = s.get("tools") or None  # optional allowlist
+
+    # ── stdio (local subprocess) ─────────────────────────────────────────
+    if "stdio" in s:
+      stdio = s["stdio"]
+      cmd = stdio.get("command")
+      args = stdio.get("args") or []
+      env_extra = {k: _expand_env(str(v)) for k, v in (stdio.get("env") or {}).items()}
+      if not cmd:
+        continue
+      params = StdioServerParameters(
+          command=cmd,
+          args=args,
+          env={**os.environ, **env_extra} if env_extra else None,
       )
-    )
+      kw: dict[str, Any] = dict(connection_params=params, tool_name_prefix=prefix)
+      if tool_filter:
+        kw["tool_filter"] = tool_filter
+      toolsets.append(McpToolset(**kw))
+      continue
+
+    # ── http (Streamable HTTP — modern, Cloud Run-friendly) ──────────────
+    if "http" in s:
+      http_cfg = s["http"]
+      url = _expand_env(http_cfg.get("url", ""))
+      if not url:
+        continue
+      headers = _expand_headers(http_cfg.get("headers") or {})
+      try:
+        from google.adk.tools.mcp_tool.mcp_session_manager import (
+            StreamableHTTPConnectionParams,
+        )
+        params_http = StreamableHTTPConnectionParams(url=url, headers=headers or None)
+        kw = dict(connection_params=params_http, tool_name_prefix=prefix)
+        if tool_filter:
+          kw["tool_filter"] = tool_filter
+        toolsets.append(McpToolset(**kw))
+      except ImportError:
+        # Fallback: try SseConnectionParams for older ADK builds
+        try:
+          from google.adk.tools.mcp_tool.mcp_session_manager import SseConnectionParams
+          params_sse_fb = SseConnectionParams(url=url, headers=headers or None)
+          kw = dict(connection_params=params_sse_fb, tool_name_prefix=prefix)
+          if tool_filter:
+            kw["tool_filter"] = tool_filter
+          toolsets.append(McpToolset(**kw))
+        except ImportError:
+          pass  # ADK version doesn't support remote MCP — skip silently
+      continue
+
+    # ── sse (Server-Sent Events — older remote servers) ──────────────────
+    if "sse" in s:
+      sse_cfg = s["sse"]
+      url = _expand_env(sse_cfg.get("url", ""))
+      if not url:
+        continue
+      headers = _expand_headers(sse_cfg.get("headers") or {})
+      try:
+        from google.adk.tools.mcp_tool.mcp_session_manager import SseConnectionParams
+        params_sse = SseConnectionParams(url=url, headers=headers or None)
+        kw = dict(connection_params=params_sse, tool_name_prefix=prefix)
+        if tool_filter:
+          kw["tool_filter"] = tool_filter
+        toolsets.append(McpToolset(**kw))
+      except ImportError:
+        pass  # ADK version too old — skip
+      continue
+
   return toolsets

gemcode/openapi_loader.py

@@ -0,0 +1,127 @@
+"""
+Auto-loads OpenAPI specs from `.gemcode/openapi/` as ADK OpenAPIToolset instances.
+
+Inspired by the ADK community pattern: drop an OpenAPI spec in a directory and
+the agent automatically gets REST API tools for it — no manual tool wiring needed.
+
+Supported formats: .yaml, .yml, .json
+
+Example:
+  .gemcode/openapi/
+  ├── github.yaml        → tools: mcp__github__list_repos, mcp__github__create_pr, …
+  ├── sentry.json        → tools: mcp__sentry__list_issues, …
+  └── internal_api.yaml  → tools from your company's internal REST API
+
+The filename (without extension) is used as the tool name prefix.
+So `github.yaml` → tools prefixed with `github_`.
+
+Auth:
+  Each spec file can have a matching `.auth` sidecar file with JSON:
+  {
+    "type": "api_key",        // "api_key" | "bearer" | "basic" | "oauth2"
+    "header": "X-API-Key",
+    "value": "${GITHUB_TOKEN}"  // ${ENV_VAR} is expanded from environment
+  }
+  For oauth2: {"type": "oauth2", "token_url": "...", "client_id": "...", "client_secret": "${VAR}"}
+
+Requires: pip install google-adk (OpenAPIToolset is included in the main package)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+_ENV_VAR_RE = re.compile(r"\$\{([A-Z_][A-Z0-9_]*)\}")
+_OPENAPI_DIR = ".gemcode/openapi"
+
+
+def _expand(value: str) -> str:
+  return _ENV_VAR_RE.sub(lambda m: os.environ.get(m.group(1), m.group(0)), value)
+
+
+def _load_auth(spec_path: Path):
+  """Try to load auth config from <spec_stem>.auth next to the spec file."""
+  auth_path = spec_path.with_suffix(".auth")
+  if not auth_path.is_file():
+    auth_path = spec_path.parent / (spec_path.stem + ".auth.json")
+  if not auth_path.is_file():
+    return None, None
+  try:
+    auth_data = json.loads(auth_path.read_text())
+  except Exception:
+    return None, None
+
+  auth_type = auth_data.get("type", "").lower()
+  try:
+    from google.adk.auth import AuthCredential, AuthCredentialTypes
+    if auth_type == "api_key":
+      return None, AuthCredential(
+          auth_type=AuthCredentialTypes.API_KEY,
+          api_key=_expand(auth_data.get("value", "")),
+      )
+    if auth_type in ("bearer", "token"):
+      return None, AuthCredential(
+          auth_type=AuthCredentialTypes.HTTP,
+          http={"scheme": "bearer", "token": _expand(auth_data.get("value", ""))},
+      )
+  except ImportError:
+    pass
+  return None, None
+
+
+def load_openapi_toolsets(project_root: Path) -> list[Any]:
+  """
+  Scan .gemcode/openapi/ for spec files and return OpenAPIToolset instances.
+
+  Returns an empty list if the directory doesn't exist or no valid specs are found.
+  Errors loading individual specs are logged but don't crash GemCode.
+  """
+  openapi_dir = project_root / _OPENAPI_DIR
+  if not openapi_dir.is_dir():
+    return []
+
+  try:
+    from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import (
+        OpenAPIToolset,
+    )
+  except ImportError:
+    log.debug("[openapi] OpenAPIToolset not available in this ADK version — skipping")
+    return []
+
+  toolsets: list[Any] = []
+
+  for spec_file in sorted(openapi_dir.iterdir()):
+    if spec_file.suffix.lower() not in (".yaml", ".yml", ".json"):
+      continue
+    if spec_file.stem.endswith(".auth"):
+      continue
+
+    prefix = spec_file.stem  # e.g. "github" from "github.yaml"
+    fmt = "json" if spec_file.suffix.lower() == ".json" else "yaml"
+
+    try:
+      spec_str = spec_file.read_text(encoding="utf-8", errors="replace")
+    except OSError as e:
+      log.warning("[openapi] Could not read %s: %s", spec_file.name, e)
+      continue
+
+    _, auth_credential = _load_auth(spec_file)
+
+    try:
+      kwargs: dict[str, Any] = dict(spec_str=spec_str, spec_str_type=fmt)
+      if auth_credential is not None:
+        kwargs["auth_credential"] = auth_credential
+      toolset = OpenAPIToolset(**kwargs)
+      toolsets.append(toolset)
+      log.info("[openapi] Loaded spec '%s' from %s", prefix, spec_file.name)
+    except Exception as exc:
+      log.warning("[openapi] Failed to load %s: %s", spec_file.name, exc)
+
+  return toolsets

gemcode/permissions.py

@@ -1,5 +1,206 @@
-"""Backward-compatible re-exports. Prefer `gemcode.callbacks` for new code."""
+"""
+Permission rules engine — inspired by Claude Code's allow/deny pattern system.
 
-from gemcode.callbacks import make_before_tool_callback
+Users define rules in `.gemcode/settings.json` (project) or `~/.gemcode/settings.json` (global).
+Rules are evaluated for every tool call: deny first, then allow, then default.
 
-__all__ = ["make_before_tool_callback"]
+Schema:
+{
+  "permissions": {
+    "allow": [
+      "bash(git *)",
+      "bash(npm run *)",
+      "bash(pytest *)",
+      "read_file(*)",
+      "write_file(src/**)"
+    ],
+    "deny": [
+      "bash(rm -rf *)",
+      "bash(curl *)",
+      "bash(wget *)",
+      "read_file(.env)",
+      "read_file(.env.*)",
+      "write_file(secrets/**)"
+    ]
+  }
+}
+
+Pattern syntax (same as Claude Code's permission rules):
+  - "bash"                   — matches ALL bash calls
+  - "bash(*)"                — same as above
+  - "bash(git *)"            — bash calls whose command starts with "git "
+  - "write_file(src/**)"     — write_file calls where path matches src/**
+  - "read_file(.env)"        — exact path match for .env
+  - "*"                      — matches all tool calls
+
+Evaluation order: deny → allow → default (ask/yes_to_all/strict from cfg)
+First matching rule wins.
+
+Files (merged in order — later rules take precedence):
+  1. ~/.gemcode/settings.json     (user-global)
+  2. .gemcode/settings.json       (project-specific, can override global)
+
+Reloaded on every tool call (file is stat-cached to avoid repeated disk reads).
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+# ── Cache so we don't re-read files every millisecond ────────────────────────
+_file_cache: dict[str, tuple[float, float, list]] = {}  # path → (mtime, stat_time, rules)
+_CACHE_TTL = 2.0  # seconds
+
+
+def _read_settings_rules(path: Path) -> list[dict]:
+  """Read and cache permission rules from a settings file."""
+  path_str = str(path)
+  now = time.monotonic()
+  if path_str in _file_cache:
+    cached_mtime, cached_time, cached_rules = _file_cache[path_str]
+    if now - cached_time < _CACHE_TTL:
+      return cached_rules
+
+  if not path.is_file():
+    _file_cache[path_str] = (0.0, now, [])
+    return []
+
+  try:
+    mtime = path.stat().st_mtime
+    if path_str in _file_cache and _file_cache[path_str][0] == mtime:
+      # File hasn't changed — just refresh the TTL
+      old = _file_cache[path_str]
+      _file_cache[path_str] = (old[0], now, old[2])
+      return old[2]
+
+    data = json.loads(path.read_text(encoding="utf-8", errors="replace"))
+    perms = data.get("permissions") or {}
+    rules: list[dict] = []
+    for pattern in perms.get("deny") or []:
+      rules.append({"action": "deny", "pattern": str(pattern)})
+    for pattern in perms.get("allow") or []:
+      rules.append({"action": "allow", "pattern": str(pattern)})
+    _file_cache[path_str] = (mtime, now, rules)
+    return rules
+  except Exception:
+    _file_cache[path_str] = (0.0, now, [])
+    return []
+
+
+def load_rules(project_root: Path) -> list[dict]:
+  """
+  Load merged rules from user-global and project settings.
+  Order: global first (lower priority), project second (higher priority / overrides).
+  """
+  global_rules = _read_settings_rules(Path.home() / ".gemcode" / "settings.json")
+  project_rules = _read_settings_rules(project_root / ".gemcode" / "settings.json")
+  # Deny rules always evaluated first regardless of file order, so combine and re-sort
+  all_rules = global_rules + project_rules
+  # Stable sort: deny rules before allow rules (deny has priority)
+  deny_rules = [r for r in all_rules if r["action"] == "deny"]
+  allow_rules = [r for r in all_rules if r["action"] == "allow"]
+  return deny_rules + allow_rules
+
+
+def _parse_pattern(pattern: str) -> tuple[str, str | None]:
+  """
+  Parse a rule pattern into (tool_glob, arg_glob | None).
+
+  Examples:
+    "bash"            → ("bash", None)
+    "bash(*)"         → ("bash", "*")
+    "bash(git *)"     → ("bash", "git *")
+    "write_file(src/*)→ ("write_file", "src/*")
+    "*"               → ("*", None)
+  """
+  pattern = pattern.strip()
+  paren_open = pattern.find("(")
+  if paren_open == -1:
+    return (pattern, None)
+  tool_glob = pattern[:paren_open].strip()
+  arg_part = pattern[paren_open + 1:]
+  if arg_part.endswith(")"):
+    arg_part = arg_part[:-1]
+  return (tool_glob, arg_part.strip() or None)
+
+
+def _get_primary_arg(tool_name: str, args: dict[str, Any]) -> str:
+  """
+  Extract the primary argument to match against the pattern's arg_glob.
+  For bash: the command string.
+  For file tools: the path argument.
+  For everything else: concatenate all string args.
+  """
+  if tool_name in ("bash", "run_command"):
+    return (
+        args.get("command") or
+        args.get("cmd") or
+        args.get("args", [""])[0] if isinstance(args.get("args"), list) else args.get("args", "")
+    ) or ""
+  # File tools — use first path-like arg
+  for key in ("path", "file_path", "file", "filename", "dest", "src"):
+    val = args.get(key)
+    if val and isinstance(val, str):
+      return val
+  # Fallback: join all string values
+  return " ".join(str(v) for v in args.values() if isinstance(v, str))
+
+
+def check_rules(
+    tool_name: str,
+    args: dict[str, Any],
+    project_root: Path,
+) -> str | None:
+  """
+  Evaluate permission rules for a tool call.
+
+  Returns:
+    "allow"  — explicit allow rule matched → skip normal permission prompts
+    "deny"   — explicit deny rule matched  → block the tool call
+    None     — no rule matched             → use default behavior (cfg.permission_mode)
+  """
+  rules = load_rules(project_root)
+  if not rules:
+    return None
+
+  primary_arg = _get_primary_arg(tool_name, args)
+
+  for rule in rules:
+    tool_glob, arg_glob = _parse_pattern(rule["pattern"])
+
+    # Match tool name
+    if tool_glob != "*" and not fnmatch.fnmatch(tool_name, tool_glob):
+      continue
+
+    # Match argument (if pattern specifies one)
+    if arg_glob is not None and arg_glob != "*":
+      if not fnmatch.fnmatch(primary_arg, arg_glob):
+        continue
+
+    return rule["action"]  # "allow" or "deny"
+
+  return None  # no rule matched
+
+
+def describe_rules(project_root: Path) -> list[str]:
+  """Human-readable rule listing for /permissions output."""
+  rules = load_rules(project_root)
+  if not rules:
+    return ["  (no rules — using default permission_mode)"]
+  lines: list[str] = []
+  deny_rules = [r for r in rules if r["action"] == "deny"]
+  allow_rules = [r for r in rules if r["action"] == "allow"]
+  if deny_rules:
+    lines.append("  deny:")
+    for r in deny_rules:
+      lines.append(f"    ✗  {r['pattern']}")
+  if allow_rules:
+    lines.append("  allow:")
+    for r in allow_rules:
+      lines.append(f"    ✓  {r['pattern']}")
+  return lines