coderio 0.4.0__py3-none-any.whl

coderio/tools/__init__.py

@@ -0,0 +1,94 @@
+"""coderio tools."""
+
+from coderio.tools.base import (
+    DESTRUCTIVE_TOOLS,
+    Tool,
+    to_langchain_tool,
+)
+from coderio.tools.bash import BashArgs, BashTool
+from coderio.tools.edit_file import EditFileArgs, EditFileTool
+from coderio.tools.glob_tool import GlobArgs, GlobTool
+from coderio.tools.grep_tool import GrepArgs, GrepTool
+from coderio.tools.list_dir import ListDirArgs, ListDirTool
+from coderio.tools.multi_edit import MultiEditArgs, MultiEditTool
+from coderio.tools.note import NoteArgs, NoteTool
+from coderio.tools.permission import (
+    AutoPermissionGate,
+    PermissionGate,
+    PermissionMode,
+    RichPromptPermissionGate,
+)
+from coderio.tools.read_file import ReadFileArgs, ReadFileTool
+from coderio.tools.todo import TodoArgs, TodoStore, TodoTool
+from coderio.tools.web_fetch import WebFetchArgs, WebFetchTool
+from coderio.tools.web_search import WebSearchArgs, WebSearchTool
+from coderio.tools.write_file import WriteFileArgs, WriteFileTool
+
+__all__ = [
+    "Tool",
+    "to_langchain_tool",
+    "DESTRUCTIVE_TOOLS",
+    "PermissionGate",
+    "PermissionMode",
+    "RichPromptPermissionGate",
+    "AutoPermissionGate",
+    "TodoStore",
+    "build_default_tools",
+    "to_langchain_tools",
+]
+
+
+def build_default_tools(bash_shell: str = "", **_) -> list:
+    """Return the default tool set (12 tools)."""
+    return [
+        ReadFileTool(),
+        WriteFileTool(),
+        EditFileTool(),
+        MultiEditTool(),
+        ListDirTool(),
+        BashTool(shell=bash_shell),
+        GlobTool(),
+        GrepTool(),
+        TodoTool(TodoStore()),
+        WebSearchTool(),
+        WebFetchTool(),
+        NoteTool(),
+    ]
+
+
+_ARGS_SCHEMAS: dict = {
+    "read_file": ReadFileArgs,
+    "write_file": WriteFileArgs,
+    "edit_file": EditFileArgs,
+    "multi_edit": MultiEditArgs,
+    "list_dir": ListDirArgs,
+    "bash": BashArgs,
+    "glob": GlobArgs,
+    "grep": GrepArgs,
+    "todo": TodoArgs,
+    "web_search": WebSearchArgs,
+    "web_fetch": WebFetchArgs,
+    "note": NoteArgs,
+}
+
+
+def to_langchain_tools(tools: list, extra: dict | None = None) -> list:
+    """Adapt coderio tools (+ optional extras like activate_skill) to langchain tools.
+
+    `extra` maps tool name -> args_schema for tools not in the default set.
+    Skill-carried tools (loaded from a skill's tools.py) carry their own
+    ``args_schema`` attribute and are picked up automatically here — they don't
+    need to be pre-registered in _ARGS_SCHEMAS.
+    """
+    schemas = dict(_ARGS_SCHEMAS)
+    if extra:
+        schemas.update(extra)
+    out = []
+    for t in tools:
+        # Prefer the explicit schema registry; fall back to the tool's own
+        # args_schema (skill-carried tools define their schema in tools.py).
+        schema = schemas.get(t.name) or getattr(t, "args_schema", None)
+        if schema is None:
+            continue
+        out.append(to_langchain_tool(t, schema))
+    return out

coderio/tools/base.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from langchain_core.tools import StructuredTool
+from pydantic import BaseModel
+
+
+@runtime_checkable
+class Tool(Protocol):
+    """Unified tool interface. Each tool declares a pydantic args_schema and a run()."""
+
+    name: str
+    description: str
+
+    def run(self, **kwargs: Any) -> str: ...
+
+
+def to_langchain_tool(tool: "Tool", args_schema: type[BaseModel]) -> StructuredTool:
+    """Adapt a coderio Tool to a langchain StructuredTool (spec §3.1).
+
+    The bound model then exposes the tool's JSON schema to the LLM and returns
+    tool_calls whose args are validated against args_schema.
+    """
+
+    def _invoke(**kwargs: Any) -> str:
+        return tool.run(**kwargs)
+
+    return StructuredTool.from_function(
+        _invoke,
+        name=tool.name,
+        description=tool.description,
+        args_schema=args_schema,
+    )
+
+
+# Tool classification by permission risk level. Uses deepagents native tool
+# names (execute/write_todos/ls) since the production engine is deepagents.
+# The old ReAct engine names (bash/todo/list_dir) are no longer in use.
+
+# Destructive tools: require permission in CONFIRM/AUTO_EDIT/PLAN modes.
+# multi_edit is destructive (atomic multi-edit of one file) and must NOT be
+# omitted — without it, CONFIRM/AUTO_EDIT modes treat multi_edit as read-only
+# and let it through without asking (permission.py: check() returns True for
+# any tool not in DESTRUCTIVE_TOOLS). The deepagents backend doesn't expose
+# multi_edit, but this list is also the permission model's source of truth.
+# task is the subagent-delegation tool (2026-08-14 report P0-2): delegating
+# spawns a subagent with write/execute tools — without gating task itself,
+# PLAN mode (nominally read-only) could delegate destructive work even after
+# the general-purpose subagent got coderio middleware (defense in depth).
+DESTRUCTIVE_TOOLS = {"write_file", "edit_file", "multi_edit", "execute", "web_fetch", "note", "task"}
+
+# Auto Edit mode: file edits auto-allowed (fast + reversible via git), but
+# shell/network/note-writes still need confirmation (harder to undo side effects).
+FILE_EDIT_TOOLS = {"write_file", "edit_file"}

coderio/tools/bash.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from coderio.tools.win_job import kill_process_tree as _kill_process_tree
+
+_WIN_CANDIDATES = (
+    "C:\\Program Files\\Git\\bin\\bash.exe",
+    "C:\\Program Files\\Git\\usr\\bin\\bash.exe",
+    "C:\\Program Files (x86)\\Git\\bin\\bash.exe",
+)
+
+
+class BashArgs(BaseModel):
+    command: str = Field(description="The shell command to execute.")
+    timeout: int = Field(default=120, description="Timeout in seconds.")
+    run_in_background: bool = Field(default=False, description="Run detached; returns a pid.")
+    cwd: str = Field(default="", description="Working directory for the command.")
+
+
+def detect_shell(configured: str) -> str:
+    """Resolve the bash executable path. Spec §3.3.
+
+    Order: explicit config > Windows candidates > PATH `bash`.
+    """
+    if configured:
+        p = Path(configured)
+        if p.is_file():
+            return str(p)
+    if sys.platform == "win32":
+        for cand in _WIN_CANDIDATES:
+            if Path(cand).is_file():
+                return cand
+    found = shutil.which("bash")
+    if found:
+        return found
+    if sys.platform == "win32":
+        raise FileNotFoundError(
+            "bash not found. Install Git Bash (https://git-scm.com) and/or set [tools].bash_shell in config.toml."
+        )
+    raise FileNotFoundError(
+        "bash not found. Install it via your package manager "
+        "(e.g. apt install bash / brew install bash) "
+        "and/or set [tools].bash_shell in config.toml."
+    )
+
+
+class BashTool:
+    name = "bash"
+    description = (
+        "Execute a shell command via bash (Git Bash on Windows, native bash on Linux/macOS). "
+        "Returns combined stdout+stderr with an [exit_code: N] marker. "
+        "Supports timeout (default 120s) and run_in_background.\n\n"
+        "ENVIRONMENT DISCOVERY (important on Windows): the bash shell inherits the system "
+        "PATH, which may differ from the environment coderio itself runs in. Before assuming "
+        "'the environment is broken', discover what's actually available:\n"
+        "  - `which python python3 py 2>/dev/null` — find which Python interpreters exist\n"
+        "  - Check for a project virtual environment: `ls .venv/Scripts/python.exe` "
+        "(Windows) or `ls venv/bin/python` (Linux/macOS). If found, use that path directly: "
+        "`.venv/Scripts/python.exe -m pytest` instead of bare `python -m pytest`.\n"
+        "  - `py -3 --version` — Windows Python launcher may find a Python 3 even when "
+        "`python` resolves to Python 2.\n"
+        "A bare `python` that fails does NOT mean dependencies are missing. Always verify "
+        "with the correct interpreter before concluding the environment is broken."
+    )
+    args_schema = BashArgs
+
+    def __init__(self, shell: str = ""):
+        self._shell = shell
+
+    def _resolve(self):
+        if self._shell and Path(self._shell).is_file():
+            return self._shell
+        return detect_shell(self._shell)
+
+    @staticmethod
+    def _prepend_venv_activate(command: str, cwd: str) -> str:
+        """Prepend 'source .venv/bin/activate' (or Scripts path on Windows) if
+        a virtual environment exists in the working directory.
+
+        This ensures `python` / `pip` in the bash command resolve to the
+        project's venv interpreter, not a random system Python. The check is
+        purely additive — if no .venv exists, the command runs unchanged.
+        """
+        if not command or not cwd:
+            return command
+        work = Path(cwd)
+        if sys.platform == "win32":
+            activate = work / ".venv" / "Scripts" / "activate"
+        else:
+            activate = work / ".venv" / "bin" / "activate"
+        if not activate.is_file():
+            return command
+        # Use 'source' (bash builtin) to activate in the same shell session.
+        # 'command' runs after activation, so `python` now points to .venv.
+        return f"source '{activate}' 2>/dev/null; {command}"
+
+    def run(
+        self,
+        command: str,
+        timeout: int = 120,
+        run_in_background: bool = False,
+        cwd: str = "",
+    ) -> str:
+        shell = self._resolve()
+        work = cwd or os.getcwd()
+        # Auto-activate a project virtual environment if one exists in the
+        # working directory. Without this, bash's login shell inherits the
+        # system PATH, where `python` may resolve to a wrong interpreter (e.g.
+        # Python 2.7 on Windows, or no python at all on macOS). The agent then
+        # sees 'No module named pytest' even though coderio itself runs fine
+        # with all deps installed in .venv.
+        command = self._prepend_venv_activate(command, work)
+        if run_in_background:
+            proc = subprocess.Popen(
+                [shell, "-l", "-c", command],
+                cwd=work,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+            return f"Started background task (pid={proc.pid})"
+        # Use Popen + manual timeout instead of subprocess.run(timeout=...).
+        # subprocess.run's timeout on Windows only kills the direct child —
+        # grandchildren (pytest workers, hanging test threads) survive and
+        # hold the pipes open, so the call NEVER returns. The manual timeout
+        # below uses _kill_process_tree (Windows Job Objects) to kill the
+        # entire process tree, then closes the pipes explicitly.
+        try:
+            proc = subprocess.Popen(
+                [shell, "-l", "-c", command],
+                cwd=work,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                # On Linux/macOS, start a new process group so os.killpg works.
+                start_new_session=(sys.platform != "win32"),
+            )
+        except FileNotFoundError as e:
+            return f"Error: {e}"
+        try:
+            stdout, stderr = proc.communicate(timeout=timeout)
+            out = (stdout or "") + (stderr or "")
+            # Append exit code so the model can tell success (0) from failure
+            # without guessing from the output text. Critical for the harness
+            # VerifyGate: a non-zero exit means the verification attempt failed,
+            # which the model should read and fix — not just "ran = verified".
+            return f"{out}\n[exit_code: {proc.returncode}]"
+        except subprocess.TimeoutExpired:
+            # Kill the ENTIRE process tree (not just the direct child). Without
+            # this, grandchildren hold the pipes open and communicate() never
+            # returns — the TUI freezes indefinitely.
+            _kill_process_tree(proc)
+            try:
+                proc.communicate(timeout=5)
+            except Exception:
+                pass
+            return f"Error: command timed out after {timeout}s"

coderio/tools/command_policy.py

@@ -0,0 +1,364 @@
+"""Command-content review policy for the shell (execute) tool.
+
+This is the cheapest layer of defense against destructive shell commands — it
+catches the obvious catastrophe patterns (``rm -rf /``, ``mkfs``, fork bombs)
+before they reach ``subprocess.run(shell=True)``. It is NOT a real OS sandbox:
+a determined model can obfuscate commands (base64 decode, variable expansion,
+``$(...)`` substitution) to bypass regex matching. The goal is to stop the
+*accidental* and *careless* cases, not a adversarial one.
+
+Two complementary modes (both can be active at once):
+
+**Blacklist (always on, even in FULL mode)**: built-in patterns that block the
+catastrophic commands. Users can append via ``[tools].blocked_commands``. A
+blacklist match → hard block (the command never runs).
+
+**Whitelist (opt-in via ``[tools].whitelist_mode = true``)**: when enabled,
+commands whose first token isn't in the allowed set are flagged for confirmation
+(NOT hard-blocked — they degrade to the tier's confirm path, so FULL still
+allows them, CONFIRM prompts, PLAN blocks). This is stricter than the blacklist
+alone but less disruptive than hard-denying unknown commands. Users extend the
+allowlist via ``[tools].allowed_commands``.
+
+The whitelist, like the blacklist, is name-matching only — ``python -c
+"import os; os.system('rm -rf /')"`` passes because the first token is
+``python``. It raises the bar for accidental damage (a typo'd command name, a
+wrong tool), not for adversarial input. True isolation needs OS-level sandboxing
+(see win_sandbox.py / linux_sandbox.py).
+
+For true isolation, run coderio inside a container/VM — see the architecture
+doc's security section. This policy is the "at least do this" floor that the
+2026-08-07 analysis report (P0-1) asked for.
+
+Design:
+- Default blacklist is built-in and always active (even in FULL mode). Users
+  can append their own patterns via config.toml [tools].blocked_commands.
+- Matching is regex on the raw command string (no shell AST parsing). This
+  will false-positive on ``echo "rm -rf /"`` — acceptable, since safety > the
+  rare case of quoting a destructive pattern in a string literal.
+- ``network_allowed=False`` disables web_fetch/web_search entirely (offline mode).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+# Built-in blacklist: (pattern, reason). Compiled once at import.
+#
+# Each pattern matches the destructive form but NOT safe variants:
+# - `rm -rf /` blocks recursive root deletion, but `rm -rf ./build` is fine
+# - `rm -rf ~` / `rm -rf $HOME` blocks home-dir nuking
+# - `mkfs` blocks filesystem formatting
+# - `dd ... of=/dev/` blocks writing to raw devices
+# - fork bomb `:(){:|:&};:` (and the spaced variant)
+# - `chmod -R 777 /` blocks global permission corruption
+# - `> /dev/sda` blocks redirect-to-device
+# - `shutdown` / `reboot` / `halt` / `poweroff` block system power control
+# - `:(){` is the canonical fork-bomb opener (catches variants before the full form)
+_DEFAULT_BLOCKED: list[tuple[str, str]] = [
+    # Recursive deletion of root or any system directory (/home, /etc, /usr, ...).
+    # `rm -rf /home` is just as catastrophic as `rm -rf /`. Any absolute path
+    # under root with -rf is blocked; `rm -rf ./build` (relative) is fine.
+    #
+    # REGRESSION HARDENING (2026-08-14 report): the original single-flag regex
+    # `-[rRfF]*[rR][fF]*` missed several ACTUALLY-DESTRUCTIVE forms while the
+    # harmless bare `rm -rf /` (coreutils refuses it without
+    # --no-preserve-root!) was the only one blocked:
+    #   - `rm -rf / --no-preserve-root`  ← the only form that truly deletes /
+    #   - `rm -r -f /`                  ← flags written separately
+    #   - `rm -rf "/"`                  ← quoted root
+    #   - `chmod -R 0777 /`             ← leading-zero mode
+    # Fixed below with dedicated patterns; each verified by tests in
+    # test_command_policy.py ("blacklist hardening" section).
+    # Flags may be split across multiple dash-groups: rm -r -f, rm -rf -v, ...
+    (r"\brm\s+(?:-[rRfFvIi]+\s+)+/(?:\S|$)", "recursive delete of system directory (absolute path under /)"),
+    # Bare `rm -rf /` at end-of-line (trailing space or EOL).
+    (r"\brm\s+(?:-[rRfFvIi]+\s+)+/\s*$", "recursive delete of root directory"),
+    # Quoted root: rm -rf "/" or rm -rf '/'.
+    (r"\brm\s+(?:-[rRfFvIi]+\s+)+[\"']/[\"'](?:\s|$)", "recursive delete of root directory (quoted)"),
+    # --no-preserve-root anywhere after rm: its ONLY purpose is defeating the
+    # coreutils root protection — no legitimate coding task uses it.
+    (r"\brm\b[^|;&]*--no-preserve-root", "rm with --no-preserve-root (removes root-delete protection)"),
+    (r"\brm\s+(?:-[rRfFvIi]+\s+)+~(?:\s|$|/)", "recursive delete of home directory"),
+    (r"\brm\s+(?:-[rRfFvIi]+\s+)+\$HOME(?:\s|$|/)", "recursive delete of home directory"),
+    (r"\brm\s+(?:-[rRfFvIi]+\s+)+\*", "recursive delete of all files (rm -rf *)"),
+    # find starting at / with -delete: deletes every match under root.
+    # `find / -name x -delete` etc. — any find rooted at / ending in -delete.
+    (r"\bfind\s+/(?:\s|$).*?-delete\b", "find -delete starting at filesystem root"),
+    # Filesystem format — destroys all data on a device.
+    (r"\bmkfs(?:\.\w+)?\s", "filesystem format (destroys all data on target)"),
+    # Writing to raw block devices.
+    (r"\bdd\b.*\bof\s*=\s*/dev/", "dd writing to a raw device"),
+    (r">\s*/dev/(?:sd|nvme|hd)", "redirect to a raw block device"),
+    # Fork bomb — the bash classic `:(){:|:&};:` and spaced variants.
+    # Allow optional space between `:` and `()` (some shells/users space it).
+    (r":\s*\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;", "fork bomb"),
+    # Global permission corruption. Accept 777 with or without leading 0
+    # (chmod accepts both `777` and `0777`; the old pattern missed 0777).
+    (r"\bchmod\s+-R\s+0?777\s+/(?:\S|$)", "recursive world-writable on system directory"),
+    # System power control — no coding task needs these.
+    (r"\b(?:shutdown|reboot|halt|poweroff)\b", "system power control"),
+    # Kernel module manipulation — loading/unloading kernel code.
+    (r"\brmmod\b", "kernel module unload"),
+    (r"\binsmod\b", "kernel module load"),
+    (r"\bmodprobe\b", "kernel module manipulation"),
+]
+
+# Built-in whitelist: commands a coding agent legitimately needs. When
+# whitelist_mode is enabled, any command whose first token isn't here (or in
+# the user's allowed_commands) is flagged for confirmation.
+#
+# Keep this conservative — adding a command here means "the agent can run this
+# without asking, even in whitelist mode". Destructive commands (rm, dd, mkfs)
+# are intentionally absent: even in whitelist mode, they should prompt.
+_DEFAULT_ALLOWED = frozenset(
+    {
+        # Language runtimes & package managers
+        "python",
+        "python3",
+        "py",
+        "pip",
+        "pip3",
+        "pipx",
+        "uv",
+        "poetry",
+        "node",
+        "npm",
+        "npx",
+        "yarn",
+        "pnpm",
+        "bun",
+        "deno",
+        "cargo",
+        "rustc",
+        "go",
+        "java",
+        "javac",
+        "gradle",
+        "mvn",
+        "ruby",
+        "gem",
+        "bundle",
+        # Build / task runners
+        "make",
+        "cmake",
+        "ninja",
+        "just",
+        # Dev tools
+        "git",
+        "gh",
+        "ruff",
+        "mypy",
+        "pyright",
+        "black",
+        "isort",
+        "pytest",
+        "tox",
+        "nox",
+        "jest",
+        "vitest",
+        "test",
+        "eslint",
+        "tsc",
+        # Read-only inspection (safe, no side effects)
+        "ls",
+        "ll",
+        "dir",
+        "cat",
+        "head",
+        "tail",
+        "less",
+        "more",
+        "grep",
+        "rg",
+        "find",
+        "fd",
+        "which",
+        "where",
+        "whereis",
+        "wc",
+        "sort",
+        "uniq",
+        "diff",
+        "comm",
+        "cut",
+        "tr",
+        "awk",
+        "sed",
+        "stat",
+        "file",
+        "du",
+        "df",
+        "env",
+        "printenv",
+        "echo",
+        "printf",
+        "date",
+        "uname",
+        "whoami",
+        "hostname",
+        # File ops (non-destructive)
+        "mkdir",
+        "touch",
+        "cp",
+        "mv",
+        "ln",
+        "chmod",
+        "chown",
+        "tree",
+        "exa",
+        "bat",
+        # Shell builtins / misc
+        "cd",
+        "pwd",
+        "export",
+        "set",
+        "source",
+        "eval",
+        "true",
+        "false",
+        "test",
+        # Compression (common in build flows)
+        "tar",
+        "zip",
+        "unzip",
+        "gzip",
+        "gunzip",
+    }
+)
+
+
+def _extract_command_name(command: str) -> str:
+    """Extract the first token of a command (the executable name).
+
+    Handles a few common prefixes that wrap the real command:
+    - ``source venv/bin/activate && python ...`` → ``python``
+    - ``sudo apt install ...`` → ``apt``
+    - ``env VAR=x python ...`` → ``python``
+
+    Returns the bare name (no path prefix): ``/usr/bin/python`` → ``python``.
+    Returns "" for empty/whitespace input.
+    """
+    if not command or not command.strip():
+        return ""
+    # Strip leading env-var assignments (``VAR=x foo``) and common wrappers.
+    tokens = command.strip().split()
+    i = 0
+    # Skip ``env`` + its VAR=val args.
+    if tokens and tokens[0] in ("env", "sudo", "command"):
+        i = 1
+        while i < len(tokens) and "=" in tokens[i] and not tokens[i].startswith("-"):
+            i += 1
+    # Skip ``source x && ...`` / ``. x && ...`` prefix.
+    if i < len(tokens) and tokens[i] in ("source", "."):
+        # Skip the script arg, then any && / ; separator.
+        i += 2
+        while i < len(tokens) and tokens[i] in ("&&", "||", ";", "&", "|"):
+            i += 1
+    if i >= len(tokens):
+        return ""
+    name = tokens[i]
+    # Strip path prefix: /usr/bin/python → python, ./foo → foo.
+    if "/" in name or "\\" in name:
+        name = name.replace("\\", "/").rsplit("/", 1)[-1]
+    return name
+
+
+@dataclass
+class CommandPolicy:
+    """Decides whether a shell command or network call may proceed.
+
+    Attributes:
+        extra_blocked: user-supplied patterns (from config.toml
+            [tools].blocked_commands). Appended to the built-in defaults, so
+            both layers apply. Each entry is a regex string.
+        network_allowed: if False, web_fetch and web_search are blocked
+            entirely (offline mode). Defaults to True.
+        whitelist_mode: if True, commands whose first token isn't in the
+            allowed set are flagged for confirmation (see check_whitelist).
+            Defaults to False (blacklist-only, backward compatible).
+        allowed_commands: user-supplied additions to the built-in whitelist
+            (from config.toml [tools].allowed_commands). Applied only when
+            whitelist_mode is True.
+    """
+
+    extra_blocked: list[str] = field(default_factory=list)
+    network_allowed: bool = True
+    whitelist_mode: bool = False
+    allowed_commands: list[str] = field(default_factory=list)
+    # Compiled patterns, lazily built. Cached on first check_command call.
+    _compiled: list[tuple[re.Pattern, str]] = field(default_factory=list, repr=False)
+    _initialized: bool = field(default=False, repr=False)
+
+    def _ensure_compiled(self) -> None:
+        """Compile regexes once, on first use (avoids import-time work if the
+        policy is constructed but never checked — e.g. in tests)."""
+        if self._initialized:
+            return
+        for pattern, reason in _DEFAULT_BLOCKED:
+            self._compiled.append((re.compile(pattern), reason))
+        for user_pattern in self.extra_blocked:
+            # User patterns get a generic reason; we don't know their intent.
+            try:
+                self._compiled.append((re.compile(user_pattern), f"matches user blocklist: {user_pattern}"))
+            except re.error:
+                # Skip invalid regex rather than crashing — log via the reason
+                # so a future check could surface it. Silently dropping is
+                # safer than blocking all commands because one pattern is bad.
+                continue
+        self._initialized = True
+
+    def check_command(self, command: str) -> str | None:
+        """Check a shell command against the blacklist.
+
+        Returns a human-readable reason string if the command is blocked, or
+        None if it may proceed. The reason is surfaced to the model via a
+        ToolMessage so it can understand WHY and try a different approach.
+
+        The blacklist is ALWAYS active (even in FULL mode) — safety takes
+        priority. The whitelist (check_whitelist) is a separate, softer layer.
+        """
+        if not command:
+            return None
+        self._ensure_compiled()
+        for pattern, reason in self._compiled:
+            if pattern.search(command):
+                return reason
+        return None
+
+    def check_whitelist(self, command: str) -> str | None:
+        """Check if a command is outside the whitelist (whitelist mode only).
+
+        Returns a reason string if the command's first token is NOT in the
+        allowed set (the command should be flagged for confirmation), or None
+        if the command is whitelisted (or whitelist_mode is disabled).
+
+        Unlike check_command (hard block), a whitelist miss is NOT a hard
+        block — the caller (CommandReviewMiddleware) degrades it to the tier's
+        confirm path. This means FULL mode still allows whitelist-miss
+        commands, PLAN mode still blocks them (PLAN blocks all shell anyway),
+        and CONFIRM/AUTO_EDIT prompt the user.
+        """
+        if not self.whitelist_mode or not command:
+            return None
+        name = _extract_command_name(command)
+        if not name:
+            return None  # empty after extraction — let it through, blacklist will catch real issues
+        allowed = _DEFAULT_ALLOWED | frozenset(self.allowed_commands)
+        if name not in allowed:
+            return (
+                f"command {name!r} is not in the whitelist "
+                f"(whitelist_mode=true). This is not a hard block — the "
+                f"permission tier decides whether to confirm (CONFIRM/AUTO_EDIT) "
+                f"or allow (FULL). Add {name!r} to [tools].allowed_commands to "
+                f"silence this."
+            )
+        return None
+
+    @classmethod
+    def default(cls) -> CommandPolicy:
+        """The policy used when config doesn't specify one: built-in blacklist
+        active, network allowed. Safe default that adds protection without
+        breaking any normal coding workflow."""
+        return cls()