hubble-cli 4.0.0__py3-none-any.whl

hubble/main.py

@@ -0,0 +1,299 @@
+"""`hubble` entry point: interactive REPL, headless -p mode, session resume."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from hubble import __version__
+from hubble.permissions import MODES, Permissions
+from hubble.prompts import PERSONAS
+from hubble.provider import OpenAICompatProvider
+from hubble.session import SessionStore
+from hubble.settings import ConfigError, load_settings, require_api_key, trust_folder
+from hubble.tools import ToolContext, detect_shell
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="hubble", description="Hubble: agentic coding CLI for AIHub and other OpenAI-compatible APIs.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""examples:
+  hubble                                  start an interactive session
+  hubble "explain this repo"              start a session with a first prompt
+  hubble -p "fix the failing test" --permission-mode accept-edits
+  git diff | hubble -p "review this diff" --output-format json
+  hubble -c                               continue the latest session here
+  hubble -r                               pick a session to resume
+""")
+    p.add_argument("prompt", nargs="?", help="initial prompt")
+    p.add_argument("-p", "--print", dest="print_mode", action="store_true",
+                   help="non-interactive: run the prompt, print the result and exit")
+    p.add_argument("-c", "--continue", dest="continue_", action="store_true", help="continue the latest session")
+    p.add_argument("-r", "--resume", nargs="?", const="", metavar="ID", help="resume a session (lists them without ID)")
+    p.add_argument("-m", "--model", help="model id")
+    p.add_argument("--provider", help="provider name from /provider (default: last used)")
+    p.add_argument("--permission-mode", choices=MODES, help="default | accept-edits | plan | yolo")
+    p.add_argument("--yolo", action="store_true", help="shortcut for --permission-mode yolo (no approvals)")
+    p.add_argument("--persona", choices=list(PERSONAS), help="system persona")
+    p.add_argument("--output-format", choices=["text", "json"], default="text", help="output format for -p")
+    p.add_argument("--max-turns", type=int, help="max model calls per prompt")
+    p.add_argument("--cwd", help="workspace root (default: current directory)")
+    p.add_argument("--base-url", help="API base URL")
+    p.add_argument("--api-key", help="API key (default: HUBBLE_API_KEY / .env)")
+    p.add_argument("--allow", action="append", default=[], metavar="RULE", help='allow rule, e.g. "shell(pytest*)"')
+    p.add_argument("--deny", action="append", default=[], metavar="RULE", help='deny rule, e.g. "shell(git push*)"')
+    p.add_argument("--no-session", action="store_true", help="do not save this session")
+    p.add_argument("--quiet", action="store_true", help="with -p: hide tool progress on stderr")
+    p.add_argument("--test", metavar="MODEL", help="check that a model responds, then exit")
+    p.add_argument("-v", "--version", action="version", version=f"hubble {__version__}")
+    return p
+
+
+def main(argv=None):
+    if sys.platform == "win32":
+        for stream in (sys.stdout, sys.stderr):
+            try:
+                stream.reconfigure(encoding="utf-8")  # model output often contains emoji
+            except (AttributeError, ValueError):
+                pass
+    args = build_parser().parse_args(argv)
+    root = Path(args.cwd or ".").resolve()
+    if not root.is_dir():
+        sys.exit(f"hubble: workspace not found: {root}")
+
+    overrides = {
+        "model": args.model, "base_url": args.base_url, "api_key": args.api_key,
+        "persona": args.persona, "max_turns": args.max_turns,
+        "permission_mode": "yolo" if args.yolo else args.permission_mode,
+    }
+    interactive = not args.print_mode and sys.stdin.isatty()
+    try:
+        settings = load_settings(root, overrides)
+        ignored = settings["_ignored_project_keys"]
+        if ignored:
+            if _ask_trust(root, ignored, interactive=interactive):
+                trust_folder(root)
+                settings = load_settings(root, overrides)
+    except ConfigError as e:
+        sys.exit(f"hubble: {e}")
+
+    from hubble.providers import DEFAULT_PROVIDER, load_providers
+    providers = load_providers(settings)
+    active = args.provider or settings.get("provider") or DEFAULT_PROVIDER
+    if args.api_key or args.base_url:
+        active = DEFAULT_PROVIDER  # explicit credentials on the command line win
+    if active not in providers:
+        if args.provider:
+            sys.exit(f"hubble: unknown provider '{args.provider}'. Known: {', '.join(providers) or 'none'}")
+        if providers:
+            active = DEFAULT_PROVIDER if DEFAULT_PROVIDER in providers else next(iter(providers))
+        elif interactive:
+            active = _first_run(providers, settings)
+        else:
+            try:
+                require_api_key(settings)
+            except ConfigError as e:
+                sys.exit(f"hubble: {e}")
+    cfg = providers[active]
+    settings["provider"] = active
+    provider = OpenAICompatProvider(cfg.base_url, cfg.api_key)
+
+    if args.test:
+        res = provider.ping(args.test)
+        print(f"{'OK' if res['ok'] else 'FAILED'} {args.test} {res['latency_ms']} ms  {res['msg']}")
+        sys.exit(0 if res["ok"] else 1)
+
+    ctx = ToolContext(
+        root=root,
+        extra_dirs=[Path(d).expanduser().resolve() for d in settings.get("additional_dirs", [])],
+        allow_secrets=bool(settings.get("allow_secret_files")),
+        shell_argv=detect_shell(settings.get("shell", "auto")),
+        shell_timeout=int(settings.get("shell_timeout", 120)),
+        sandbox=settings.get("shell_sandbox", "off"),
+        sandbox_image=settings.get("sandbox_image", "python:3.12-slim"),
+        sandbox_memory=settings.get("sandbox_memory", "1g"),
+        sandbox_cpus=str(settings.get("sandbox_cpus", "2")),
+        sandbox_network=bool(settings.get("sandbox_network", True)),
+    )
+    perms = Permissions(settings["permission_mode"],
+                        allow=settings["permissions"].get("allow", []) + args.allow,
+                        deny=settings["permissions"].get("deny", []) + args.deny)
+    store = SessionStore(root)
+
+    prompt = args.prompt or ""
+    if args.resume and not any(args.resume in it["id"] for it in store.list(limit=500)):
+        # `hubble -r "fix the bug"`: argparse took the prompt as a session id.
+        prompt = f"{args.resume} {prompt}".strip()
+        args.resume = ""
+    if args.print_mode and not sys.stdin.isatty():
+        piped = sys.stdin.read()
+        if piped.strip():
+            prompt = f"{prompt}\n\n<stdin>\n{piped}\n</stdin>" if prompt else piped
+
+    if args.print_mode:
+        args._providers = providers
+        sys.exit(run_headless(args, settings, provider, ctx, perms, store, prompt,
+                              _fallback_client(providers, active, provider)))
+
+    from hubble.agent import Agent
+    try:
+        from hubble.repl import Repl
+        from hubble.ui import ReplEvents, console
+    except ImportError as e:
+        sys.exit(f"hubble: missing dependency ({e.name}). Install with:\n"
+                 f'  "{sys.executable}" -m pip install -r "{Path(__file__).resolve().parent.parent / "requirements.txt"}"')
+
+    agent = Agent(provider, settings, ctx, perms, ReplEvents(ctx, show_reasoning=bool(settings.get("show_reasoning"))))
+    agent.fallback_client = _fallback_client(providers, active, provider)
+    repl = Repl(agent, store, providers)
+    resumed = _resume(args, store, agent, console)
+    if resumed is None:
+        return
+    if not resumed and not args.no_session:
+        agent.session = store.new(agent.model)
+    repl.run(initial_prompt=prompt or None)
+
+
+def _headless_resolver(settings, providers, agent):
+    from hubble.providers import resolve_fallback
+    clients = {agent.provider_name: agent.provider}
+
+    def resolve(provider_name, model):
+        choice = resolve_fallback(settings, providers, provider_name, model)
+        if not choice:
+            return None
+        name, fb = choice
+        if name not in clients:
+            if name not in providers:
+                return None
+            clients[name] = OpenAICompatProvider(providers[name].base_url, providers[name].api_key)
+        return clients[name], fb
+    return resolve
+
+
+def _fallback_client(providers, active, current):
+    """fallback_model lives on the built-in hubble provider."""
+    from hubble.providers import DEFAULT_PROVIDER
+    if active == DEFAULT_PROVIDER:
+        return current
+    cfg = providers.get(DEFAULT_PROVIDER)
+    return OpenAICompatProvider(cfg.base_url, cfg.api_key) if cfg else None
+
+
+def _first_run(providers, settings) -> str:
+    from hubble.onboarding import add_provider_wizard
+    from hubble.repl import register_provider
+    from hubble.settings import save_user_setting
+    from hubble.ui import console, pick
+
+    result = add_provider_wizard(providers.keys(), first_run=True)
+    if not result:
+        sys.exit("hubble: no provider configured.")
+    cfg, ids = result
+    register_provider(cfg, ids)
+    providers[cfg.name] = cfg
+    model = pick(f"Choose a model ({len(ids)} listed)", [(m, m, "") for m in sorted(ids)]) or sorted(ids)[0]
+    settings["model"] = model
+    save_user_setting("provider", cfg.name)
+    save_user_setting("model", model)
+    console.print(f"[green]Saved. Using {cfg.name}: {model}[/green]")
+    return cfg.name
+
+
+def _ask_trust(root: Path, ignored, interactive: bool) -> bool:
+    never = [k for k in ignored if k in ("base_url", "api_key")]
+    if never:
+        print(f"hubble: ignoring {', '.join(never)} from {root / '.hubble'} (only user settings or env may set them)",
+              file=sys.stderr)
+    rest = [k for k in ignored if k not in ("base_url", "api_key")]
+    if not rest:
+        return False
+    if not interactive:
+        print(f"hubble: ignoring untrusted project settings: {', '.join(rest)}. Run hubble interactively once "
+              "in this folder to trust it.", file=sys.stderr)
+        return False
+    print(f"This folder's .hubble settings want to change security options: {', '.join(rest)}.")
+    try:
+        answer = input(f"Trust {root} and apply them? [y/N] ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        return False
+    return answer in ("y", "yes")
+
+
+def _resume(args, store, agent, console):
+    """True if a session was loaded, False to start fresh, None to exit."""
+    if args.resume == "" and not args.continue_:
+        from hubble.repl import session_items
+        from hubble.ui import pick
+        items = store.list()
+        if not items:
+            console.print("[dim]No sessions to resume; starting a new one.[/dim]")
+            return False
+        sid = pick("Resume a session (Esc for a new one)", session_items(items))
+        if not sid:
+            return False
+    elif args.resume or args.continue_:
+        sid = args.resume or store.latest()
+        if not sid:
+            console.print("[dim]No previous session here; starting a new one.[/dim]")
+            return False
+    else:
+        return False
+    try:
+        session, messages, meta = store.load(sid)
+    except FileNotFoundError as e:
+        console.print(f"[red]{e}[/red]")
+        return None
+    agent.session = session
+    agent.load_history(messages)
+    # Keep the model only if the session used the provider that is active now.
+    from hubble.providers import normalize_provider_name
+    if meta.get("model") and not args.model and normalize_provider_name(meta.get("provider")) == agent.provider_name:
+        agent.model = meta["model"]
+    console.print(f"[green]Resumed session {session.id}[/green] [dim]({len(messages)} messages)[/dim]")
+    from hubble.repl import print_history_tail
+    print_history_tail(messages)
+    return True
+
+
+def run_headless(args, settings, provider, ctx, perms, store, prompt, fallback_client=None) -> int:
+    from hubble.agent import Agent
+    from hubble.ui import HeadlessEvents
+
+    if not prompt.strip():
+        print("hubble: -p needs a prompt (argument or stdin)", file=sys.stderr)
+        return 2
+    events = HeadlessEvents(stream_text=args.output_format == "text", quiet=args.quiet)
+    agent = Agent(provider, settings, ctx, perms, events)
+    agent.fallback_client = fallback_client
+    agent.fallback_resolver = _headless_resolver(settings, getattr(args, "_providers", {}), agent)
+    if args.continue_ or args.resume:
+        sid = args.resume or store.latest()
+        if sid:
+            try:
+                session, messages, _ = store.load(sid)
+                agent.session = session
+                agent.load_history(messages)
+            except FileNotFoundError as e:
+                print(f"hubble: {e}", file=sys.stderr)
+                return 2
+    if agent.session is None and not args.no_session:
+        agent.session = store.new(agent.model)
+
+    result = agent.run(prompt)
+    stats = agent.last_stats
+    is_error = bool(stats.error) or stats.interrupted
+    if args.output_format == "json":
+        print(json.dumps({
+            "result": result, "is_error": is_error, "error": stats.error,
+            "session_id": agent.session.id if agent.session else None, "model": agent.model,
+            "num_model_calls": stats.model_calls, "num_tool_calls": stats.tool_calls,
+            "usage": {"prompt_tokens": stats.prompt_tokens, "completion_tokens": stats.completion_tokens},
+            "duration_s": round(stats.duration, 2),
+        }, ensure_ascii=False, indent=2))
+    return 1 if is_error else 0
+
+
+if __name__ == "__main__":
+    main()

hubble/models.py

@@ -0,0 +1,92 @@
+"""Model registry: curated categories plus the latest scan from test_models.py."""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List
+
+PROJECT_DIR = Path(__file__).resolve().parent.parent
+SCAN_FILE = PROJECT_DIR / "available_models.json"
+
+DEFAULT_MODEL = "codestral-latest"
+
+MODEL_CATEGORIES = {
+    "Coding Specialists": [
+        "codestral-latest",
+        "codestral-2508",
+        "mistral-code-latest",
+        "mistral-code-fim-latest",
+    ],
+    "Reasoning & Logic": [
+        "nvidia/nemotron-3-super-120b-a12b",
+        "intern-s2-preview",
+        "intern-s1-mini",
+        "intern-s1",
+        "intern-s1-pro",
+    ],
+    "Fast Chat & General": [
+        "ministral-14b-latest",
+        "open-mistral-nemo",
+        "ministral-8b-latest",
+        "ministral-3b-latest",
+        "mistral-tiny-latest",
+        "qwen-8b",
+    ],
+    "Multimodal & Vision": [
+        "meta/llama-3.2-11b-vision-instruct",
+        "internvl3.5-latest",
+        "internvl-latest",
+    ],
+}
+
+RELIABLE_MODELS = [
+    "codestral-latest",
+    "codestral-2508",
+    "mistral-code-latest",
+    "mistral-code-fim-latest",
+    "nvidia/nemotron-3-super-120b-a12b",
+    "ministral-14b-latest",
+    "open-mistral-nemo",
+    "ministral-8b-latest",
+    "intern-s2-preview",
+    "intern-s1-mini",
+]
+
+
+def load_scanned_models(path: Path = SCAN_FILE) -> List[Dict[str, Any]]:
+    """Working models found by the last `python test_models.py` run."""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f).get("working_models", [])
+    except (OSError, ValueError):
+        return []
+
+
+def all_models() -> List[Dict[str, Any]]:
+    """Curated models first, then any extra scanned ones.
+
+    Each entry has model, category, latency_ms and available (None when there is no scan yet).
+    """
+    scanned = {m["model"]: m for m in load_scanned_models() if m.get("model")}
+    have_scan = bool(scanned)
+    out: List[Dict[str, Any]] = []
+    seen = set()
+    for category, names in MODEL_CATEGORIES.items():
+        for name in names:
+            out.append({"model": name, "category": category,
+                        "latency_ms": scanned.get(name, {}).get("latency_ms"),
+                        "available": (name in scanned) if have_scan else None})
+            seen.add(name)
+    for name, info in scanned.items():
+        if name not in seen:
+            out.append({"model": name, "category": "Other Verified",
+                        "latency_ms": info.get("latency_ms"), "available": True})
+    return out
+
+
+def resolve_model(query: str, candidates: List[str]) -> List[str]:
+    """Exact match wins, otherwise case-insensitive substring matches."""
+    q = query.strip().lower()
+    exact = [m for m in candidates if m.lower() == q]
+    if exact:
+        return exact
+    return [m for m in candidates if q in m.lower()]

hubble/onboarding.py

@@ -0,0 +1,94 @@
+"""Interactive wizard for adding a provider (base URL + API key), with verification."""
+
+from typing import Iterable, List, Optional, Tuple
+from urllib.parse import urlparse
+
+from rich.markup import escape
+
+from hubble.provider import normalize_base_url
+from hubble.providers import KNOWN_EXAMPLES, NAME_RX, ProviderConfig, verify
+from hubble.ui import console, pick
+
+
+def _ask(message: str, default: str = "", password: bool = False) -> Optional[str]:
+    from prompt_toolkit import prompt
+    try:
+        return prompt(message, default=default, is_password=password).strip()
+    except (EOFError, KeyboardInterrupt):
+        return None
+
+
+def _confirm(message: str, default: bool = True) -> bool:
+    hint = "[Y/n]" if default else "[y/N]"
+    answer = _ask(f"{message} {hint} ")
+    if answer is None:
+        return False
+    return default if not answer else answer.lower() in ("y", "yes")
+
+
+def _suggest_name(url: str, taken: Iterable[str]) -> str:
+    host = urlparse(url).hostname or "provider"
+    parts = [p for p in host.split(".") if p not in ("www", "api", "com", "ai", "io", "xyz", "net", "org", "dev")]
+    base = (parts[0] if parts else "provider").lower()
+    base = "".join(ch for ch in base if ch.isalnum() or ch in "-_")[:24] or "provider"
+    name, n = base, 2
+    while name in taken:
+        name, n = f"{base}{n}", n + 1
+    return name
+
+
+def add_provider_wizard(taken: Iterable[str], first_run: bool = False) -> Optional[Tuple[ProviderConfig, List[str]]]:
+    """Returns (config, model_ids) after a successful check, or None if cancelled."""
+    taken = set(taken)
+    if first_run:
+        console.print("[bold cyan]✦ Welcome to Hubble[/bold cyan]\n"
+                      "  No API key is configured yet. Add any OpenAI-compatible provider to start.\n")
+    else:
+        console.print("[bold]Add a provider[/bold] [dim](any OpenAI-compatible API; Esc/Ctrl+C cancels)[/dim]")
+
+    choice = pick("Provider", [(url, name, url) for name, url in KNOWN_EXAMPLES] +
+                  [("custom", "Custom URL...", "enter any OpenAI-compatible base URL")])
+    if choice is None:
+        return None
+    default_url = "" if choice == "custom" else choice
+
+    while True:
+        raw_url = _ask("Base URL: ", default=default_url)
+        if not raw_url:
+            return None
+        url = normalize_base_url(raw_url)
+        local = urlparse(url).hostname in ("localhost", "127.0.0.1", "::1")
+        key = _ask("API key" + (" (optional for local servers)" if local else "") + ": ", password=True)
+        if key is None:
+            return None
+        key = key or ("none" if local else "")
+        if not key:
+            console.print("[red]An API key is required.[/red]")
+            continue
+
+        with console.status(f"[dim]Checking {escape(url)} ...[/dim]"):
+            ok, message, ids = verify(url, key)
+        if ok:
+            console.print(f"[green]✔ {escape(message)}[/green]")
+            break
+        console.print(f"[red]✘ {escape(message)}[/red]")
+        if not _confirm("Try again?"):
+            return None
+        default_url = raw_url
+
+    while True:
+        name = _ask("Name for this provider: ", default=_suggest_name(url, taken))
+        if name is None:
+            return None
+        name = name.lower()
+        if not NAME_RX.match(name):
+            console.print("[red]Use lowercase letters, digits, - or _ (max 31 chars).[/red]")
+        elif name in taken:
+            console.print(f"[red]'{escape(name)}' already exists.[/red]")
+        else:
+            break
+
+    console.print(f"[dim]  Checking availability sends one tiny request to each of the {len(ids)} models. "
+                  "That is free on most gateways but can cost a little on paid APIs.[/dim]")
+    check = _confirm(f"Check which of the {len(ids)} models respond now (runs in the background)?")
+    return ProviderConfig(name, url, key, check_models=check), ids

hubble/permissions.py

@@ -0,0 +1,139 @@
+"""Permission modes and allow/deny rules.
+
+Rule syntax: `tool` or `tool(pattern)`, e.g. `shell(git status*)`, `edit_file(src/*)`,
+`read_file(secrets/*)`. Patterns use fnmatch against the tool's target (a workspace-relative
+path, or a command). Deny rules win, then allow rules, then the mode default.
+"""
+
+import fnmatch
+import re
+from typing import List, Optional, Tuple
+
+MODES = ["default", "accept-edits", "plan", "yolo"]
+CYCLE_MODES = ["default", "accept-edits", "plan"]  # yolo only by explicit choice
+MODE_HELP = {
+    "default": "ask before edits and shell commands",
+    "accept-edits": "auto-approve file edits, ask before shell commands",
+    "plan": "read-only: explore and propose a plan, no edits or commands",
+    "yolo": "auto-approve everything except deny rules",
+}
+ALIASES = {"bash": "shell", "run": "shell", "edit": "edit_file", "write": "write_file",
+           "read": "read_file", "ls": "list_dir", "find": "glob", "todo": "todo_write"}
+# A command may ride on a pattern allow rule only if it is one plain program invocation:
+# no separators, subexpressions, redirects, variables or quotes in any shell (cmd, PowerShell, bash).
+SAFE_COMMAND = re.compile(r"^[\w ./:=+,@\-]+$")
+# Split points used to apply deny rules to every part of a chained command.
+SEPARATORS = re.compile(r"&&|\|\||[;|&\r\n()`{}]|\$\(")
+MULTI_WORD_LAUNCHERS = {"python", "python3", "py", "node", "npx", "uv", "uvx", "poetry", "pipx", "dotnet", "go",
+                        "cargo", "npm", "pnpm", "yarn", "git", "docker", "kubectl", "pip", "make"}
+
+RULE_RX = re.compile(r"^\s*([\w-]+)\s*(?:\((.*)\))?\s*$")
+
+
+def parse_rule(rule: str) -> Optional[Tuple[str, Optional[str]]]:
+    m = RULE_RX.match(rule)
+    if not m:
+        return None
+    name = m.group(1).lower()
+    return ALIASES.get(name, name), m.group(2)
+
+
+def rule_matches(rule: str, tool: str, target: str) -> bool:
+    parsed = parse_rule(rule)
+    if not parsed:
+        return False
+    name, pattern = parsed
+    if name not in (tool, "*"):
+        return False
+    if pattern is None or pattern == "*":
+        return True
+    norm = target.replace("\\", "/").strip()
+    return fnmatch.fnmatchcase(norm, pattern) or fnmatch.fnmatchcase(norm.lower(), pattern.lower())
+
+
+def command_prefix(command: str) -> str:
+    """`python -m pytest -q tests` -> `python -m pytest`; `git status -s` -> `git status`; `pytest -q` -> `pytest`."""
+    words = command.strip().split()
+    if not words:
+        return ""
+    prefix = [words[0]]
+    exe = words[0].lower().removesuffix(".exe")
+    if exe in MULTI_WORD_LAUNCHERS:
+        rest = words[1:]
+        if rest[:1] == ["-m"] and len(rest) > 1:
+            prefix += rest[:2]
+        elif rest and re.match(r"^[a-z][\w:-]*$", rest[0]):
+            prefix.append(rest[0])
+            if exe in ("npm", "pnpm", "yarn") and rest[0] == "run" and len(rest) > 1:
+                prefix.append(rest[1])
+    return " ".join(prefix)
+
+
+class Permissions:
+    def __init__(self, mode: str = "default", allow: Optional[List[str]] = None,
+                 deny: Optional[List[str]] = None):
+        self.mode = mode if mode in MODES else "default"
+        self.allow = list(allow or [])
+        self.deny = list(deny or [])
+        self.session_allow: List[str] = []
+
+    def cycle_mode(self) -> str:
+        idx = CYCLE_MODES.index(self.mode) if self.mode in CYCLE_MODES else -1
+        self.mode = CYCLE_MODES[(idx + 1) % len(CYCLE_MODES)]
+        return self.mode
+
+    def _denied(self, tool: str, kind: str, target: str) -> Optional[str]:
+        targets = [target]
+        if kind == "exec":
+            targets += [part.strip() for part in SEPARATORS.split(target) if part.strip()]
+        for rule in self.deny:
+            if any(rule_matches(rule, tool, t) for t in targets):
+                return rule
+        return None
+
+    def check(self, tool: str, kind: str, target: str) -> Tuple[str, str]:
+        """Returns (decision, reason) where decision is allow | ask | deny."""
+        rule = self._denied(tool, kind, target)
+        if rule:
+            return "deny", f"blocked by deny rule {rule}"
+        if kind == "read":
+            return "allow", ""
+        if self.mode == "plan" and kind != "web":  # fetching docs is fine while planning
+            return "deny", ("plan mode is read-only. Finish exploring, then present your plan; "
+                            "the user will switch modes to implement it")
+        plain = kind != "exec" or bool(SAFE_COMMAND.match(target.strip()))
+        for rule in self.allow + self.session_allow:
+            if rule_matches(rule, tool, target):
+                parsed = parse_rule(rule)
+                if not plain and parsed and parsed[1] not in (None, "*"):
+                    continue
+                return "allow", f"allowed by rule {rule}"
+        if self.mode == "yolo":
+            return "allow", "yolo mode"
+        if kind == "edit" and self.mode == "accept-edits":
+            return "allow", "accept-edits mode"
+        return "ask", ""
+
+    def _add(self, rule: str):
+        if rule not in self.session_allow:
+            self.session_allow.append(rule)
+
+    def always_rule(self, tool: str, kind: str, target: str) -> str:
+        """Session rule(s) added when the user answers 'always'. Returns a description."""
+        if kind == "exec":
+            prefix = command_prefix(target)
+            if not prefix or not SAFE_COMMAND.match(target.strip()):
+                self._add(f"{tool}({target.strip()})")
+                return f"{tool}({target.strip()})"
+            self._add(f"{tool}({prefix})")
+            self._add(f"{tool}({prefix} *)")
+            return f"{tool}({prefix} *)"
+        if kind == "web":
+            self._add(f"{tool}({target})")
+            return f"{tool}({target})"
+        if kind == "edit":
+            self._add("edit_file")
+            self._add("write_file")
+            return "edit_file, write_file"
+        self._add(tool)
+        return tool