forgecommandline 0.8.0__py3-none-any.whl

forgecli/quality.py

@@ -0,0 +1,192 @@
+"""How capable each model is at building things, scored 1-10, worked out automatically.
+
+Routing sends the work to the highest-scoring model that is available; speed only breaks ties.
+Nobody has to maintain a list: any model a user adds gets a score from three layers.
+
+  1. A first guess from the name: known model families, then the parameter count in the id
+     ("70b", "397B-A17B"), lowered for "mini", "flash", "nano" and similar light versions.
+  2. A quick automatic test (roster.bench_one): a small reasoning check and a tool-call check,
+     run once in the background for models that haven't had one. Failing the tool call matters
+     most: a model that can't call tools can't edit files or run commands.
+  3. Its track record in real work: empty or junk replies, broken tool calls, claims the check
+     caught, getting stuck, versus turns that finished cleanly. Recorded per model and kept.
+
+Override any score in ~/.forge/model_quality.json: {"gpt-oss-120b": 9, "groq:openai/gpt-oss-120b": 7}
+"""
+from __future__ import annotations
+
+import json
+import re
+import threading
+import time
+
+from .config import HOME_DIR
+
+OVERRIDES_FILE = HOME_DIR / "model_quality.json"
+RECORD_FILE = HOME_DIR / "model_record.json"
+STATS_FILE = HOME_DIR / "roster_stats.json"     # written by roster.bench
+BENCH_EVERY = 14 * 86400                        # re-test a model after two weeks
+RECORD_SIZE = 40                                # outcomes kept per model
+MIN_RECORD = 6                                  # outcomes needed before the record counts
+
+# Frontier families whose names don't say how big they are. First match wins.
+FAMILIES = [
+    (r"claude-(opus|sonnet)|gpt-5(?![\w.-]*(mini|nano))|gemini-[2-9][.\d]*-pro|grok-4|kimi-k2"
+     r"|qwen3-coder-480|qwen3\.5-397|nemotron-3-ultra|deepseek-(v[3-9]|r1)(?!.*(flash|lite|distill))"
+     r"|glm-[4-9][.\d]*(?![\w.-]*(flash|air))|o[34](-pro)?$", 10),
+    (r"claude-haiku|gpt-4\.1(?!-nano)|gpt-4o(?!-mini)|gemini-[2-9][.\d]*-flash(?!-lite)|gpt-5[\w.-]*mini"
+     r"|mistral-(large|medium)|command-a", 8),
+]
+FAMILIES.insert(1, (r"minimax-m\d|deepseek-v[3-9]|qwen3[.\d]*-(max|plus)|kimi", 9))
+# Light versions, matched as whole words so "minimax" and "gemini" don't count as "mini".
+LIGHT = [(r"(?<![a-z])(nano|tiny|e[1-4]b)(?![a-z])", -3),
+         (r"(?<![a-z])(mini|lite|small|bolt|air)(?![a-z])", -2),
+         (r"(?<![a-z])(flash|lightning|turbo|haiku|instant|fast)(?![a-z])", -1)]
+SIZE_TIERS = [(300, 9), (100, 8), (30, 7), (13, 6), (7, 5), (3, 4), (0, 3)]
+_SIZE = re.compile(r"(?<![a-z])(\d+(?:\.\d+)?)\s*b(?![a-z])", re.I)
+
+_lock = threading.Lock()
+_cache: dict = {"at": 0.0, "over": {}, "stats": {}, "record": {}}
+
+
+def _load(path) -> dict:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _fresh() -> dict:
+    with _lock:
+        if time.time() - _cache["at"] > 30:
+            over = {}
+            for k, v in _load(OVERRIDES_FILE).items():
+                try:
+                    over[str(k).lower()] = int(v)
+                except (TypeError, ValueError):
+                    pass
+            _cache.update(at=time.time(), over=over, stats=_load(STATS_FILE),
+                          record=_load(RECORD_FILE) or _cache["record"])
+        return _cache
+
+
+def size_of(model: str) -> float:
+    """Total parameters in billions, from the model id (0 when it doesn't say)."""
+    sizes = [float(n) for n in _SIZE.findall(model.split("/")[-1].replace("_", "-"))]
+    sizes = [s for s in sizes if s >= 0.1]
+    return max(sizes) if sizes else 0.0
+
+
+def guess(model: str) -> int:
+    """Layer 1: a first guess from the model id alone."""
+    m = model.lower()
+    for pattern, score in FAMILIES:
+        if re.search(pattern, m):
+            base = score
+            break
+    else:
+        size = size_of(m)
+        if size:
+            base = next(score for floor, score in SIZE_TIERS if size >= floor)
+        elif re.search(r"auto|free$", m.split("/")[-1]) and "/" not in m.rstrip("/").split("/")[-1]:
+            base = 5   # a router's "auto" model: could be anything
+        else:
+            base = 6   # an unknown name is usually a mid-sized current model
+        for pattern, cut in LIGHT:
+            if re.search(pattern, m):
+                return max(1, base + cut)
+        return base
+    for pattern, cut in LIGHT:
+        if re.search(pattern, m):
+            return max(1, base + max(cut, -2))
+    return base
+
+
+def tested(provider: str, model: str) -> int:
+    """Layer 2: adjustment from the automatic test (0 when not tested yet)."""
+    s = _fresh()["stats"].get(f"{provider}:{model}") or {}
+    if not s.get("up"):
+        return 0
+    return (-3 if s.get("tools") is False else 0) + (-1 if s.get("check") is False else 0)
+
+
+def track(provider: str, model: str) -> int:
+    """Layer 3: adjustment from how the model has done in real work."""
+    rec = _fresh()["record"].get(f"{provider}:{model}") or []
+    if len(rec) < MIN_RECORD:
+        return 0
+    rate = sum(1 for x in rec if x) / len(rec)
+    return 1 if rate >= 0.9 else 0 if rate >= 0.7 else -1 if rate >= 0.5 else -2
+
+
+def score(model: str, provider: str = "") -> int:
+    over = _fresh()["over"]
+    m = model.lower()
+    for key in (f"{provider}:{m}", m):
+        if key in over:
+            return max(1, min(10, over[key]))
+    return max(1, min(10, guess(model) + tested(provider, model) + track(provider, model)))
+
+
+def explain(model: str, provider: str = "") -> str:
+    """A short "why" for /roster."""
+    over = _fresh()["over"]
+    if f"{provider}:{model.lower()}" in over or model.lower() in over:
+        return "set in model_quality.json"
+    parts = [f"name {guess(model)}"]
+    t, k = tested(provider, model), track(provider, model)
+    if t:
+        parts.append(f"test {t:+d}")
+    if k:
+        parts.append(f"record {k:+d}")
+    n = len(_fresh()["record"].get(f"{provider}:{model}") or [])
+    if n:
+        parts.append(f"{n} graded")
+    return " · ".join(parts)
+
+
+def record(provider: str, model: str, good: bool) -> None:
+    """Remember one outcome of real work (kept across sessions)."""
+    if not provider or not model:
+        return
+    c = _fresh()
+    with _lock:
+        rec = c["record"].setdefault(f"{provider}:{model}", [])
+        rec.append(bool(good))
+        del rec[:-RECORD_SIZE]
+        try:
+            HOME_DIR.mkdir(parents=True, exist_ok=True)
+            RECORD_FILE.write_text(json.dumps(c["record"]), encoding="utf-8")
+        except OSError:
+            pass
+
+
+def untested(router) -> list:
+    """Workers with no recent automatic test."""
+    from . import roster
+    stats = _fresh()["stats"]
+    now = time.time()
+    return [w for w in roster.build(router)
+            if now - (stats.get(w.id) or {}).get("when", 0) > BENCH_EVERY]
+
+
+def auto_bench(router, on_done=None) -> threading.Thread | None:
+    """Test new models in the background (two tiny requests each), so their scores are measured."""
+    todo = untested(router)
+    if not todo:
+        return None
+
+    def run():
+        from . import roster
+        try:
+            roster.bench(router, todo)
+        except Exception:
+            return
+        with _lock:
+            _cache["at"] = 0.0
+        if on_done:
+            on_done(len(todo))
+    t = threading.Thread(target=run, daemon=True, name="forge-auto-bench")
+    t.start()
+    return t

forgecli/repomap.py

@@ -0,0 +1,78 @@
+"""Bounded, dependency-free repository symbol map."""
+from __future__ import annotations
+
+import os
+import pathlib
+import re
+import time
+
+SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", ".mypy_cache",
+             ".next", "dist", "build", "target", "bin", "obj"}
+EXTENSIONS = {
+    ".py", ".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".go", ".rs", ".java", ".kt",
+    ".c", ".cc", ".cpp", ".h", ".hpp", ".cs", ".rb", ".php", ".swift",
+}
+DECLARATION = re.compile(
+    r"^\s*(?:(?:export|pub|public|private|protected|static|abstract|async|default|final)\s+)*"
+    r"(?:"
+    r"(?:async\s+)?(?:def|function|class|interface|enum|struct|trait|type|fn|func|record)\s+"
+    r"([A-Za-z_$][\w$]*)"
+    r"|(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>"
+    r")"
+)
+
+
+def build(root: pathlib.Path, max_files: int = 1500, max_symbols: int = 250,
+          max_dirs: int = 5000, max_seconds: float = 4.0) -> str:
+    root = root.resolve()
+    if not root.is_dir():
+        return f"Error: repository folder not found: {root}"
+
+    started = time.monotonic()
+    dirs_seen, files_seen, bytes_seen = 0, 0, 0
+    symbols: list[str] = []
+    limited = False
+    for current, dirs, names in os.walk(root):
+        dirs_seen += 1
+        if dirs_seen > max_dirs or time.monotonic() - started > max_seconds:
+            limited = True
+            break
+        dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS and not d.startswith("."))
+        for name in sorted(names):
+            file_path = pathlib.Path(current, name)
+            if file_path.suffix.lower() not in EXTENSIONS:
+                continue
+            files_seen += 1
+            if files_seen > max_files or time.monotonic() - started > max_seconds:
+                limited = True
+                break
+            try:
+                size = file_path.stat().st_size
+                if size > 1_000_000 or bytes_seen + size > 12_000_000:
+                    continue
+                bytes_seen += size
+                content = file_path.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            relative = file_path.relative_to(root).as_posix()
+            for line_number, line in enumerate(content.splitlines(), 1):
+                match = DECLARATION.match(line)
+                if match:
+                    symbol = match.group(1) or match.group(2)
+                    symbols.append(f"{relative}:{line_number} {symbol}")
+                    if len(symbols) >= max_symbols:
+                        limited = True
+                        break
+            if limited:
+                break
+        if limited:
+            break
+
+    if not symbols:
+        summary = f"No symbols found in {files_seen} source files."
+    else:
+        summary = f"Repository map ({len(symbols)} symbols from {files_seen} source files):\n"
+        summary += "\n".join(symbols)
+    if limited:
+        summary += "\n… map truncated at a safety limit; narrow the folder or inspect specific files."
+    return summary

forgecli/roster.py

@@ -0,0 +1,227 @@
+"""The roster: every model Forge can use, and what each one is good at.
+
+Three layers, later ones win:
+  1. built-in profiles below (a starting guess from each model family's reputation)
+  2. your edits in ~/.forge/roster.json
+  3. measurements from /roster bench (speed, tool calling, a small reasoning check)
+
+The coordinator (team mode) reads this to decide which model gets which task."""
+from __future__ import annotations
+
+import json
+import re
+import threading
+import time
+from dataclasses import dataclass, field
+
+from .config import HOME_DIR
+
+ROSTER_FILE = HOME_DIR / "roster.json"
+STATS_FILE = HOME_DIR / "roster_stats.json"
+
+STRENGTHS = ["coding", "reasoning", "math", "tool-use", "fast", "vision", "long-context",
+             "writing", "multilingual", "review", "general"]
+
+# (substring of the model id, strengths, notes). First match wins, so specific patterns go first.
+PROFILES: list[tuple[str, list[str], str]] = [
+    ("gpt-oss-120b", ["reasoning", "coding", "tool-use"], "Open-weight 120B reasoning model. Strong all-rounder for code and multi-step tool work; fast on Groq and Cerebras."),
+    ("gpt-oss-20b", ["fast", "tool-use"], "Small and fast. Simple edits, lookups, summaries."),
+    ("nemotron-3-ultra", ["reasoning", "coding", "long-context", "review"], "NVIDIA's largest Nemotron. Slower; good for hard planning, reviews and long files."),
+    ("bolt", ["fast"], "Very small and fast. Quick reads, summaries, simple questions; not for hard reasoning or big edits."),
+    ("nemotron", ["reasoning", "coding"], "NVIDIA Nemotron family. Solid reasoning and agentic work."),
+    ("minimax", ["coding", "tool-use", "vision"], "MiniMax agentic model that also accepts images. Good for coding and multi-step tool use."),
+    ("glm", ["coding", "reasoning", "tool-use"], "Zhipu GLM. Strong at coding and agentic work."),
+    ("kimi", ["coding", "long-context", "tool-use"], "Moonshot Kimi. Long context, agentic coding."),
+    ("deepseek", ["coding", "reasoning", "math"], "DeepSeek. Strong code and math."),
+    ("qwen", ["coding", "multilingual", "reasoning"], "Qwen. Good coder, many languages."),
+    ("codestral", ["coding", "fast"], "Mistral's code model. Fast completions and edits."),
+    ("mistral", ["writing", "multilingual"], "Mistral. Good writer; especially strong in French and other European languages."),
+    ("command", ["writing", "multilingual", "long-context"], "Cohere Command. Writing, summarising long documents, many languages (incl. Arabic)."),
+    ("gemma", ["general", "multilingual", "fast"], "Google Gemma. Light general model, many languages."),
+    ("gemini", ["long-context", "vision", "reasoning"], "Gemini. Very long context and images."),
+    ("gpt-4.1", ["coding", "long-context", "tool-use"], "GPT-4.1. Precise instruction following, long context, reliable tool calls."),
+    ("gpt-5", ["reasoning", "coding", "tool-use"], "GPT-5 family. Strong reasoning and code."),
+    ("llama", ["general", "writing"], "Llama. General chat and writing."),
+]
+UNPROFILED = (["general"], "No built-in profile yet. Run /roster bench, and describe it in ~/.forge/roster.json.")
+
+
+@dataclass
+class Worker:
+    provider: str
+    model: str
+    strengths: list[str]
+    notes: str
+    source: str = "built-in"            # built-in | roster.json | unknown
+    stats: dict = field(default_factory=dict)
+
+    @property
+    def id(self) -> str:
+        return f"{self.provider}:{self.model}"
+
+    @property
+    def prefer(self) -> tuple[str, str]:
+        return (self.provider, self.model)
+
+    def measured(self) -> str:
+        s = self.stats
+        if not s:
+            return "not benched"
+        if not s.get("up"):
+            return f"DOWN at last check ({s.get('error', 'no answer')[:60]})"
+        bits = [f"{s.get('latency', 0):.1f}s",
+                "tools ✓" if s.get("tools") else "tools ✗",
+                "check ✓" if s.get("check") else "check ✗ (got a simple reasoning question wrong)"]
+        return ", ".join(bits)
+
+
+def _load(path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def profile(model: str) -> tuple[list[str], str]:
+    low = model.lower()
+    for pat, strengths, notes in PROFILES:
+        if pat in low:
+            st = list(strengths)
+            if re.search(r"(^|[-/_])(vl|vision)([-/_.:]|$)", low) and "vision" not in st:
+                st.append("vision")
+            return st, notes
+    return list(UNPROFILED[0]), UNPROFILED[1]
+
+
+def build(router) -> list[Worker]:
+    """One worker per (provider, model) Forge can call."""
+    edits, stats = _load(ROSTER_FILE), _load(STATS_FILE)
+    out = []
+    for p in router.providers:
+        for m in p.all_models():
+            strengths, notes = profile(m)
+            source = "built-in" if notes != UNPROFILED[1] else "unknown"
+            own = edits.get(f"{p.name}:{m}") or edits.get(m)
+            if isinstance(own, dict):
+                strengths = [str(x) for x in own.get("strengths", strengths)]
+                notes = str(own.get("notes", notes))
+                source = "roster.json"
+            out.append(Worker(p.name, m, strengths, notes, source, stats.get(f"{p.name}:{m}", {})))
+    return out
+
+
+def resolve(workers: list[Worker], name: str) -> Worker | None:
+    """Find a worker by id, model id, or an unambiguous part of either."""
+    name = (name or "").strip().lstrip("@").lower()
+    if not name:
+        return None
+    for w in workers:
+        if name in (w.id.lower(), w.model.lower()):
+            return w
+    hits = [w for w in workers if name in w.id.lower()]
+    return hits[0] if len(hits) == 1 else None
+
+
+def usable(w: Worker, router) -> bool:
+    if w.stats and not w.stats.get("up"):
+        return False
+    provider = router.get(w.provider)
+    return bool(provider and provider.pool.any_available(w.model) and not router.is_down(*w.prefer))
+
+
+def pick_coordinator(workers: list[Worker], router, wanted: str = "") -> Worker | None:
+    def qualified(w: Worker) -> bool:
+        measured = ("reasoning" in w.strengths and w.stats.get("tools") and w.stats.get("check"))
+        profiled = "reasoning" in w.strengths and "tool-use" in w.strengths
+        return bool(measured or profiled)
+
+    if wanted:
+        w = resolve(workers, wanted)
+        if w and usable(w, router) and qualified(w):
+            return w
+    ok = [w for w in workers if usable(w, router) and qualified(w)]
+    # Prefer a measured tool-capable reasoner; otherwise a profiled tool-capable reasoner.
+    for cond in (lambda w: "reasoning" in w.strengths and w.stats.get("tools") and w.stats.get("check"),
+                 lambda w: "reasoning" in w.strengths and "tool-use" in w.strengths,
+                 ):
+        hit = [w for w in ok if cond(w)]
+        if hit:
+            return min(hit, key=lambda w: w.stats.get("latency", 99)) if hit[0].stats else hit[0]
+    return None
+
+
+def describe(workers: list[Worker], router) -> str:
+    lines = []
+    for w in workers:
+        if not usable(w, router):
+            continue
+        lines.append(f"- {w.id} — good at: {', '.join(w.strengths)}. {w.notes} Measured: {w.measured()}.")
+    return "\n".join(lines)
+
+
+def write_template(workers: list[Worker]) -> None:
+    """Create ~/.forge/roster.json with the current profiles so it can be edited."""
+    if ROSTER_FILE.exists():
+        return
+    HOME_DIR.mkdir(parents=True, exist_ok=True)
+    data = {"_help": ("Describe what each model is good at. Keys are provider:model (or just the model id). "
+                      "strengths can use: " + ", ".join(STRENGTHS) + " (or your own words).")}
+    for w in workers:
+        data[w.id] = {"strengths": w.strengths, "notes": w.notes}
+    ROSTER_FILE.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+# --- bench ----------------------------------------------------------------------------
+
+CHECK = ("Which is larger, 9.11 or 9.8? And what is 17 * 23? "
+         "Reply with exactly two values separated by a comma, nothing else.")
+TOOL_PROMPT = "Read the file notes.txt using the tool."
+TOOL = [{"type": "function", "function": {
+    "name": "read_file", "description": "Read a text file",
+    "parameters": {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}}}]
+
+
+def bench_one(router, w: Worker, timeout: float = 60) -> dict:
+    p = router.get(w.provider)
+    key = p.pool.next_key() if p else None
+    if not key:
+        return {"up": False, "error": "no usable key", "when": time.time()}
+    t = time.time()
+    r = p.call(key, [{"role": "user", "content": CHECK}], None, w.model, timeout)
+    latency = time.time() - t
+    if not r:
+        return {"up": False, "error": p.last_error, "when": time.time()}
+    text = r["content"]
+    check = "391" in text and "9.8" in text and "9.11" not in text
+    r2 = p.call(p.pool.next_key() or key, [{"role": "user", "content": TOOL_PROMPT}], TOOL, w.model, timeout)
+    return {"up": True, "latency": round(latency, 2), "check": check,
+            "tools": bool(r2 and r2["tool_calls"]), "answer": text[:80], "when": time.time()}
+
+
+def bench(router, workers: list[Worker], on_done=None) -> dict[str, dict]:
+    results: dict[str, dict] = {}
+    lock = threading.Lock()
+
+    def run(w: Worker):
+        res = bench_one(router, w)
+        with lock:
+            results[w.id] = res
+            w.stats = res
+        if on_done:
+            on_done(w, res)
+
+    # A model failing its bench must not push its whole provider to the back of the chain.
+    saved = {p.name: p.last_fail for p in router.providers}
+    threads = [threading.Thread(target=run, args=(w,), daemon=True) for w in workers]
+    for th in threads:
+        th.start()
+    for th in threads:
+        while th.is_alive():
+            th.join(0.2)   # short joins keep ctrl+c working on Windows
+    for p in router.providers:
+        p.last_fail = saved.get(p.name, p.last_fail)
+    stats = _load(STATS_FILE)
+    stats.update(results)
+    HOME_DIR.mkdir(parents=True, exist_ok=True)
+    STATS_FILE.write_text(json.dumps(stats, indent=2), encoding="utf-8")
+    return results

forgecli/safety.py

@@ -0,0 +1,93 @@
+"""Which actions need the user's OK.
+
+Approval modes:
+  smart (default)  reading, and writing/editing files inside the project folder, just happen.
+                   Shell commands run without asking unless they look risky: deleting, force-pushing,
+                   installing system-wide, touching the registry or disks, shutting down, piping
+                   downloads into a shell, or anything aimed outside the project folder.
+  ask              every write, edit and shell command asks (the old behaviour).
+  auto             nothing asks. Use with care.
+"""
+from __future__ import annotations
+
+import pathlib
+import re
+import fnmatch
+import os
+
+MODES = ("smart", "ask", "auto")
+
+# Patterns that always ask in smart mode. Kept deliberately broad: a false alarm costs one keypress.
+RISKY = [
+    (r"\b(rm|rmdir|del|erase|rd)\b", "deletes files"),
+    (r"\bremove-item\b|\bri\b\s", "deletes files"),
+    (r"\bclear-content\b|\bset-content\b.*-force", "overwrites files"),
+    (r"\bmove-item\b|\bmv\b|\bmove\b|\bren(ame)?\b|\brename-item\b", "moves or renames files"),
+    (r"\bgit\s+(push|reset\s+--hard|clean|checkout\s+--|restore|rebase|branch\s+-D|stash\s+drop)", "changes git history or discards work"),
+    (r"\bformat\b|\bdiskpart\b|\bmkfs\b|\bdd\s+if=", "touches disks"),
+    (r"\b(shutdown|restart-computer|stop-computer|logoff)\b", "shuts the machine down"),
+    (r"\breg(\.exe)?\s+(add|delete|import)|\bset-itemproperty\b|\bnew-itemproperty\b|hklm:|hkcu:", "edits the registry"),
+    (r"\b(stop-process|taskkill|kill|pkill|killall)\b", "kills processes"),
+    (r"\bset-executionpolicy\b|\bnetsh\b|\bsc(\.exe)?\s+(delete|config|stop)", "changes system settings"),
+    (r"\b(npm|pnpm|yarn)\s+(i|install|add)\s+(-g|--global)\b", "installs globally"),
+    (r"\bchoco\s+install|\bwinget\s+(install|uninstall)|\bscoop\s+install", "installs software"),
+    (r"\bpip\s+uninstall|\bnpm\s+uninstall|\bwinget\s+uninstall", "uninstalls software"),
+    (r"(curl|wget|iwr|invoke-webrequest|irm|invoke-restmethod)[^|]*\|\s*(sh|bash|iex|invoke-expression|python|powershell)", "runs a downloaded script"),
+    (r"\biex\b|\binvoke-expression\b", "runs generated code"),
+    (r"\bsudo\b|\brunas\b|-verb\s+runas", "asks for admin rights"),
+    (r">\s*[a-z]:\\(windows|program files)|\bc:\\windows\b", "writes into system folders"),
+    (r"\b(docker|kubectl)\s+(rm|rmi|delete|prune|system\s+prune)", "deletes containers or resources"),
+    (r"\bdrop\s+(table|database)\b|\btruncate\s+table\b", "deletes database data"),
+]
+_RISKY = [(re.compile(p, re.I), why) for p, why in RISKY]
+
+
+def policy_denial(tool: str, command: str = "") -> str:
+    """Return a hard deny from the user's explicit environment policy."""
+    blocked_tools = [item.strip().lower() for item in os.environ.get("FORGE_DENY_TOOLS", "").split(",")
+                     if item.strip()]
+    if any(fnmatch.fnmatchcase(tool.lower(), pattern) for pattern in blocked_tools):
+        return f"blocked by FORGE_DENY_TOOLS policy ({tool})"
+    for pattern in (item.strip() for item in os.environ.get("FORGE_DENY_COMMANDS", "").split(";")
+                    if item.strip()):
+        if not command and tool != "run_shell":
+            continue
+        try:
+            if re.search(pattern, command, re.I):
+                return f"blocked by FORGE_DENY_COMMANDS policy ({pattern})"
+        except re.error as exc:
+            if tool == "run_shell":
+                return f"invalid FORGE_DENY_COMMANDS pattern {pattern!r}: {exc}; shell commands are blocked"
+    return ""
+
+
+def shell_risk(command: str) -> str:
+    """'' if the command looks safe, otherwise a short reason it needs approval."""
+    for rx, why in _RISKY:
+        if rx.search(command):
+            return why
+    return ""
+
+
+def inside(path: pathlib.Path, root: pathlib.Path) -> bool:
+    try:
+        path.resolve().relative_to(root.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def needs_ok(mode: str, tool: str, root: pathlib.Path, path: pathlib.Path | None = None,
+             command: str = "") -> str:
+    """'' when the action can go ahead, otherwise why it needs the user's OK."""
+    if mode == "auto":
+        return ""
+    if mode == "ask":
+        return "asks before every change (approval mode: ask)"
+    if tool in ("write_file", "edit_file"):
+        if path is not None and not inside(path, root):
+            return "outside the project folder"
+        return ""
+    if tool == "run_shell":
+        return shell_risk(command)
+    return ""

forgecli/sandbox.py

@@ -0,0 +1,83 @@
+"""Optional OS-level sandbox for shell commands. Forge's approval prompts decide *whether* a command
+runs; a sandbox limits *what it can reach* once it does. With FORGE_SANDBOX=docker every run_shell
+command runs in a throwaway Docker container that can see only the project folder (mounted at
+/work), not your home folder, keys or other projects.
+
+  FORGE_SANDBOX=docker               turn it on (needs Docker Desktop running)
+  FORGE_SANDBOX_IMAGE=node:22-bookworm  image to use (this default has Node, npm, Python 3 and git)
+  FORGE_SANDBOX_NET=none             cut network access too (installs and web requests then fail)
+  FORGE_SANDBOX_PORTS=5173,3000,8000,8080  ports published to 127.0.0.1 so dev servers stay reachable
+
+Commands use Linux shell syntax inside the container. File tools (read/write/edit) still run in
+Forge itself and are limited by the approval rules, not by the container."""
+from __future__ import annotations
+
+import os
+import pathlib
+import shutil
+import subprocess
+
+DEFAULT_IMAGE = "node:22-bookworm"
+DEFAULT_PORTS = "5173,3000,8000,8080"
+
+
+def mode() -> str:
+    return os.environ.get("FORGE_SANDBOX", "").strip().lower()
+
+
+def active() -> bool:
+    return mode() == "docker"
+
+
+def available() -> str | None:
+    """None when Docker is ready, otherwise why not (in plain words)."""
+    if not shutil.which("docker"):
+        return "Docker isn't installed (install Docker Desktop, or unset FORGE_SANDBOX)."
+    try:
+        r = subprocess.run(["docker", "info", "--format", "{{.ServerVersion}}"], capture_output=True,
+                           text=True, timeout=15)
+    except (OSError, subprocess.TimeoutExpired):
+        return "Docker didn't answer (start Docker Desktop, or unset FORGE_SANDBOX)."
+    return None if r.returncode == 0 else "Docker isn't running (start Docker Desktop, or unset FORGE_SANDBOX)."
+
+
+def _ports() -> list[str]:
+    out = []
+    for part in os.environ.get("FORGE_SANDBOX_PORTS", DEFAULT_PORTS).split(","):
+        part = part.strip()
+        if part.isdigit() and 0 < int(part) < 65536:
+            out += ["-p", f"127.0.0.1:{part}:{part}"]
+    return out
+
+
+def argv(root: pathlib.Path, where: pathlib.Path, command: str) -> list[str] | str:
+    """The docker command line for `command` run in `where`, or an error string if `where` is outside
+    the project folder (the container can only see the project)."""
+    root, where = pathlib.Path(root).resolve(), pathlib.Path(where).resolve()
+    try:
+        rel = where.relative_to(root)
+    except ValueError:
+        return (f"Error: the sandbox can only run commands inside the project folder {root}; "
+                f"{where} is outside it.")
+    workdir = "/work" + ("/" + rel.as_posix() if str(rel) != "." else "")
+    net = os.environ.get("FORGE_SANDBOX_NET", "").strip().lower()
+    cmd = ["docker", "run", "--rm", "-i", "--init",
+           "-v", f"{root}:/work", "-w", workdir,
+           "--memory", os.environ.get("FORGE_SANDBOX_MEMORY", "4g"),
+           "--pids-limit", "512",
+           "--security-opt", "no-new-privileges",
+           "-e", "PYTHONUNBUFFERED=1", "-e", "CI=1"]
+    if net == "none":
+        cmd += ["--network", "none"]
+    else:
+        cmd += _ports()
+    cmd += [os.environ.get("FORGE_SANDBOX_IMAGE", DEFAULT_IMAGE) or DEFAULT_IMAGE, "sh", "-lc", command]
+    return cmd
+
+
+def describe() -> str:
+    if not active():
+        return "off — commands run directly on this computer (approval rules still apply)"
+    net = "no network" if os.environ.get("FORGE_SANDBOX_NET", "").lower() == "none" else "network on"
+    return (f"docker · {os.environ.get('FORGE_SANDBOX_IMAGE', DEFAULT_IMAGE)} · only the project folder "
+            f"is visible · {net}")