drydock-cli 2.10.12__tar.gz → 3.0.15__tar.gz

{drydock_cli-2.10.12 → drydock_cli-3.0.15}/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025 Mistral AI
+   Copyright 2026 Frank Bobe III
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

drydock_cli-3.0.15/NOTICE

@@ -0,0 +1,11 @@
+Drydock
+Copyright 2026 Frank Bobe III
+
+This product is an original, clean-room implementation. It contains no source
+code from Anthropic's Claude Code, from Mistral's mistral-vibe, or from any
+other third-party project. UX conventions common to terminal coding agents
+were emulated from first principles; no third-party code, prompt text, or
+branding was copied.
+
+Licensed under the Apache License, Version 2.0 (the "License"); see the
+LICENSE file for the full text.

drydock_cli-3.0.15/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: drydock-cli
+Version: 3.0.15
+Summary: Drydock — a local, provider-agnostic terminal coding agent for local LLMs
+Author: Frank Bobe III
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/fbobe321/drydock
+Project-URL: Repository, https://github.com/fbobe321/drydock
+Project-URL: Issues, https://github.com/fbobe321/drydock/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: openai>=1.0
+Requires-Dist: textual>=0.80
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Dynamic: license-file
+
+# ⚓ Drydock
+
+A local-first, provider-agnostic **terminal coding agent** for your own LLM.
+No accounts, no telemetry, no cloud — the only network call it makes is to
+the model endpoint you configure. Primary target: **Gemma-4-26B-A4B** served
+by llama.cpp on a single workstation.
+
+> **v3 — clean-room rebuild.** Drydock is being rebuilt as an original,
+> Apache-2.0 codebase owned end to end (no upstream fork). Every release is
+> gated by a credential-exfiltration scanner that blocks anything reaching
+> off-box. See [`HARNESS_DESIGN.md`](HARNESS_DESIGN.md) and
+> [`docs/PRD.md`](docs/PRD.md).
+
+## Why
+
+A coding agent should build real projects from your machine without sending
+your code or credentials anywhere. Drydock runs entirely against a local
+model, feels like a first-class terminal agent, and keeps its data plane on
+your box.
+
+## Status
+
+Shipping. Published on PyPI as **`drydock-cli`** (v3.x). The Textual TUI is the
+default surface: a scrolling transcript with streamed assistant text, collapsible
+tool cards, a live nautical activity line, and a multi-line prompt. The agent
+loop, OpenAI-compatible provider, two-tier compaction, and the core tools
+(Read/Write/Edit/Bash/Glob/Grep) are in, with Gemma reliability hardening verified.
+
+## Install
+
+```bash
+pip install drydock-cli
+drydock
+```
+
+Requires Python 3.12+. From source instead:
+`git clone https://github.com/fbobe321/drydock-v3.git && cd drydock-v3 && pip install -e .`
+
+On first launch with no config, Drydock probes localhost for a running local
+LLM (llama.cpp/vLLM `:8000`, Ollama `:11434`, LM Studio `:1234`) and wires up
+the first one it finds — no account or API-key prompt. Override anytime with
+`--model` / `--provider` / `--base-url` or `~/.drydock/config.toml`.
+
+## Using it
+
+Type a task and press **Enter**. Drydock reads/writes/edits files and runs
+commands to do the work, showing each as a collapsible tool card.
+
+- **Enter** submits · **Ctrl+J** newline (multi-line prompts)
+- **↑ / ↓** recall command history (persists across sessions)
+- **PgUp / PgDn** (and **Ctrl+Home/End**) scroll the transcript
+- **Ctrl+O** expand/collapse tool output · **drag + Ctrl+C** copy a selection
+- **Ctrl+C twice** (or **Ctrl+D**, `/quit`) to exit
+- A live activity line shows progress while it works:
+  `◡ Keelhauling…  (12s · ↓ 6.2k tokens · thinking with high effort)`
+- Submit while it's working and the prompt **queues** (drains in order)
+- Slash commands: `/model [name]` · `/cwd [path]` · `/undo` (revert last write)
+  · `/back` (rewind last turn) · `/status` · `/clear` · `/help` · `/quit`
+
+It honors `AGENTS.md` / `DRYDOCK.md` in the working directory for project
+conventions.
+
+## Safety
+
+Two tiers, plus advisory guards — all designed so legitimate work is never
+blocked:
+
+- **Catastrophic denylist** — commands like `rm -rf /`, `mkfs`, raw block-device
+  writes, and fork bombs are refused outright (never run).
+- **Approval prompt** — sensitive-but-legitimate commands (`sudo`, package
+  installs, network fetches, `git push`) pause for **Allow / Always / Deny**.
+- **Advisory write guards** — Drydock flags (never blocks) Python syntax errors,
+  stub-only files, imports of sibling modules that don't exist yet, bare
+  `raise` outside an except, and refuses to write git conflict-marker content.
+
+Point it at a local OpenAI-compatible endpoint (e.g. llama.cpp's `server-cuda`
+serving Gemma 4 26B).
+
+## Model server (reference setup)
+
+Drydock is provider-agnostic, but it's tuned and measured against this rig:
+
+- **Model:** Gemma-4-26B-A4B-it (26B MoE, ~4B active/token), Unsloth `Q3_K_M`
+  GGUF, served by `ghcr.io/ggml-org/llama.cpp:server-cuda` with `--jinja`.
+- **GPUs:** 2× NVIDIA RTX 4060 Ti 16GB. The Q3_K_M weights (~13 GB) fit on a
+  **single 16 GB card**, so each GPU runs a **full, independent instance** —
+  two cards give two parallel instances for throughput; the model is **not**
+  tensor-split or "pooled" across both.
+- **Context:** 64k (`-c 65536`) with `q8_0` KV-cache quantization
+  (`-ctk q8_0 -ctv q8_0`) — 64k @ q8 fits roughly the same VRAM as 32k @ f16.
+- **Throughput:** ~**64 tok/s** decode, ~94 tok/s prompt (per instance, Q3_K_M).
+- **Minimum:** any single 16 GB+ CUDA card runs it.
+
+## Principles
+
+- **Clean provenance** — original code only; nothing copied from any other
+  project.
+- **Local-only data plane** — no telemetry, no phone-home, no hardcoded
+  third-party hosts, no credential transmission.
+- **Advisory, never blocking** — loop/safety mechanisms inject better
+  context; they never hard-stop legitimate work.
+- **The scanner is law** — `scripts/security_scan.py` gates every release.
+
+## Security scan
+
+```bash
+python3 scripts/security_scan.py drydock/      # scan the source tree
+python3 scripts/security_scan.py dist/*.whl    # scan a built wheel
+```
+
+Exit 2 (HIGH finding) blocks a release.
+
+## License
+
+Apache-2.0, © 2026 Frank Bobe III. See [`LICENSE`](LICENSE) and
+[`NOTICE`](NOTICE).

drydock_cli-3.0.15/README.md

@@ -0,0 +1,116 @@
+# ⚓ Drydock
+
+A local-first, provider-agnostic **terminal coding agent** for your own LLM.
+No accounts, no telemetry, no cloud — the only network call it makes is to
+the model endpoint you configure. Primary target: **Gemma-4-26B-A4B** served
+by llama.cpp on a single workstation.
+
+> **v3 — clean-room rebuild.** Drydock is being rebuilt as an original,
+> Apache-2.0 codebase owned end to end (no upstream fork). Every release is
+> gated by a credential-exfiltration scanner that blocks anything reaching
+> off-box. See [`HARNESS_DESIGN.md`](HARNESS_DESIGN.md) and
+> [`docs/PRD.md`](docs/PRD.md).
+
+## Why
+
+A coding agent should build real projects from your machine without sending
+your code or credentials anywhere. Drydock runs entirely against a local
+model, feels like a first-class terminal agent, and keeps its data plane on
+your box.
+
+## Status
+
+Shipping. Published on PyPI as **`drydock-cli`** (v3.x). The Textual TUI is the
+default surface: a scrolling transcript with streamed assistant text, collapsible
+tool cards, a live nautical activity line, and a multi-line prompt. The agent
+loop, OpenAI-compatible provider, two-tier compaction, and the core tools
+(Read/Write/Edit/Bash/Glob/Grep) are in, with Gemma reliability hardening verified.
+
+## Install
+
+```bash
+pip install drydock-cli
+drydock
+```
+
+Requires Python 3.12+. From source instead:
+`git clone https://github.com/fbobe321/drydock-v3.git && cd drydock-v3 && pip install -e .`
+
+On first launch with no config, Drydock probes localhost for a running local
+LLM (llama.cpp/vLLM `:8000`, Ollama `:11434`, LM Studio `:1234`) and wires up
+the first one it finds — no account or API-key prompt. Override anytime with
+`--model` / `--provider` / `--base-url` or `~/.drydock/config.toml`.
+
+## Using it
+
+Type a task and press **Enter**. Drydock reads/writes/edits files and runs
+commands to do the work, showing each as a collapsible tool card.
+
+- **Enter** submits · **Ctrl+J** newline (multi-line prompts)
+- **↑ / ↓** recall command history (persists across sessions)
+- **PgUp / PgDn** (and **Ctrl+Home/End**) scroll the transcript
+- **Ctrl+O** expand/collapse tool output · **drag + Ctrl+C** copy a selection
+- **Ctrl+C twice** (or **Ctrl+D**, `/quit`) to exit
+- A live activity line shows progress while it works:
+  `◡ Keelhauling…  (12s · ↓ 6.2k tokens · thinking with high effort)`
+- Submit while it's working and the prompt **queues** (drains in order)
+- Slash commands: `/model [name]` · `/cwd [path]` · `/undo` (revert last write)
+  · `/back` (rewind last turn) · `/status` · `/clear` · `/help` · `/quit`
+
+It honors `AGENTS.md` / `DRYDOCK.md` in the working directory for project
+conventions.
+
+## Safety
+
+Two tiers, plus advisory guards — all designed so legitimate work is never
+blocked:
+
+- **Catastrophic denylist** — commands like `rm -rf /`, `mkfs`, raw block-device
+  writes, and fork bombs are refused outright (never run).
+- **Approval prompt** — sensitive-but-legitimate commands (`sudo`, package
+  installs, network fetches, `git push`) pause for **Allow / Always / Deny**.
+- **Advisory write guards** — Drydock flags (never blocks) Python syntax errors,
+  stub-only files, imports of sibling modules that don't exist yet, bare
+  `raise` outside an except, and refuses to write git conflict-marker content.
+
+Point it at a local OpenAI-compatible endpoint (e.g. llama.cpp's `server-cuda`
+serving Gemma 4 26B).
+
+## Model server (reference setup)
+
+Drydock is provider-agnostic, but it's tuned and measured against this rig:
+
+- **Model:** Gemma-4-26B-A4B-it (26B MoE, ~4B active/token), Unsloth `Q3_K_M`
+  GGUF, served by `ghcr.io/ggml-org/llama.cpp:server-cuda` with `--jinja`.
+- **GPUs:** 2× NVIDIA RTX 4060 Ti 16GB. The Q3_K_M weights (~13 GB) fit on a
+  **single 16 GB card**, so each GPU runs a **full, independent instance** —
+  two cards give two parallel instances for throughput; the model is **not**
+  tensor-split or "pooled" across both.
+- **Context:** 64k (`-c 65536`) with `q8_0` KV-cache quantization
+  (`-ctk q8_0 -ctv q8_0`) — 64k @ q8 fits roughly the same VRAM as 32k @ f16.
+- **Throughput:** ~**64 tok/s** decode, ~94 tok/s prompt (per instance, Q3_K_M).
+- **Minimum:** any single 16 GB+ CUDA card runs it.
+
+## Principles
+
+- **Clean provenance** — original code only; nothing copied from any other
+  project.
+- **Local-only data plane** — no telemetry, no phone-home, no hardcoded
+  third-party hosts, no credential transmission.
+- **Advisory, never blocking** — loop/safety mechanisms inject better
+  context; they never hard-stop legitimate work.
+- **The scanner is law** — `scripts/security_scan.py` gates every release.
+
+## Security scan
+
+```bash
+python3 scripts/security_scan.py drydock/      # scan the source tree
+python3 scripts/security_scan.py dist/*.whl    # scan a built wheel
+```
+
+Exit 2 (HIGH finding) blocks a release.
+
+## License
+
+Apache-2.0, © 2026 Frank Bobe III. See [`LICENSE`](LICENSE) and
+[`NOTICE`](NOTICE).

drydock_cli-3.0.15/drydock/__init__.py

@@ -0,0 +1,10 @@
+"""DryDock — local coding agent."""
+from importlib.metadata import PackageNotFoundError, version as _version
+
+try:
+    # Authoritative: the installed distribution's version. Keeps --version and
+    # the TUI banner in sync with the published wheel automatically.
+    __version__ = _version("drydock-cli")
+except PackageNotFoundError:
+    # Running from source before install (e.g. PYTHONPATH dev runs).
+    __version__ = "3.0.15"

drydock_cli-3.0.15/drydock/__main__.py

@@ -0,0 +1,2 @@
+from drydock.cli import main
+main()

drydock_cli-3.0.15/drydock/agent.py

@@ -0,0 +1,224 @@
+"""Core agent loop — multi-turn tool-calling with any LLM.
+
+DryDock v3 — clean, provider-agnostic, no model-specific hacks.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Generator
+
+from drydock.providers import stream, AssistantTurn, TextChunk
+from drydock.tool_registry import schemas, execute
+from drydock.tools import register_all
+
+# Register the built-in tools as a side effect of importing the agent. This is
+# explicit (not a bare side-effect import) so a linter can't "helpfully" delete
+# it: without it the registry is empty, the model is offered no tools, and it
+# emits tool calls as TEXT — which is exactly how the empty-registry regression
+# manifested. register_all() is idempotent.
+register_all()
+from drydock.compaction import maybe_compact, emergency_compact, is_context_length_error
+from drydock.loop_detect import LoopTracker
+from drydock.tuning import (
+    filter_tool_schemas,
+    hallucinated_tool_message,
+    thinking_level_for_turn,
+)
+
+
+# ── Event types ───────────────────────────────────────────────────────────
+
+@dataclass
+class ToolStart:
+    name: str
+    inputs: dict
+
+@dataclass
+class ToolEnd:
+    name: str
+    result: str
+
+@dataclass
+class TurnDone:
+    input_tokens: int
+    output_tokens: int
+
+@dataclass
+class AgentState:
+    """Mutable session state."""
+    messages: list = field(default_factory=list)
+    total_input_tokens: int = 0
+    total_output_tokens: int = 0
+    turn_count: int = 0
+    current_effort: str = ""  # "high"/"low" of the in-flight LLM call (for the UI)
+
+
+def drop_last_turn(messages: list) -> bool:
+    """Remove the last user message and everything after it (the assistant
+    replies + tool results for that turn). Returns True if a turn was dropped.
+
+    Cutting at a user-message boundary keeps the history valid — the remaining
+    list ends with a complete prior turn and never leaves an orphaned tool
+    result (those all followed the removed user message).
+    """
+    for i in range(len(messages) - 1, -1, -1):
+        if messages[i].get("role") == "user":
+            del messages[i:]
+            return True
+    return False
+
+
+# ── Agent loop ────────────────────────────────────────────────────────────
+
+def run(
+    user_message: str,
+    state: AgentState,
+    config: dict,
+    system_prompt: str,
+) -> Generator:
+    """Multi-turn agent loop.
+
+    Yields: TextChunk | ToolStart | ToolEnd | TurnDone
+
+    The loop continues as long as the model makes tool calls.
+    When the model responds with text only (no tools), the turn ends.
+    """
+    state.messages.append({"role": "user", "content": user_message})
+
+    max_turns = config.get("max_turns", 200)
+    max_tool_calls = config.get("max_tool_calls", 0)  # 0 = unlimited
+    tool_call_count = 0
+    session_has_edited = False
+    leaked_call_retries = 0
+    run_iteration = 0  # stream calls within THIS run() (resets per user message)
+    loop_tracker = LoopTracker()
+
+    while state.turn_count < max_turns:
+        state.turn_count += 1
+        run_iteration += 1
+        assistant_turn: AssistantTurn | None = None
+
+        # Compact context if approaching limit
+        maybe_compact(state, config)
+
+        # Force tool use on first turn to prevent the model from just outputting text
+        turn_config = dict(config)
+        if state.turn_count == 1 and config.get("force_first_tool", False):
+            turn_config["tool_choice"] = "required"
+        # Adaptive reasoning budget: high to PLAN the response to the user's new
+        # message (first iteration of this run), low for routine continuation
+        # turns that just consume tool results — cuts latency without hurting
+        # correctness (verified: same answer, fewer tokens). The provider only
+        # forwards it to endpoints that accept reasoning_effort.
+        if "reasoning_effort" not in turn_config:
+            level = thinking_level_for_turn(run_iteration, is_user_turn=(run_iteration == 1))
+            turn_config["reasoning_effort"] = "high" if level == "high" else "low"
+        # Expose the in-flight effort to the UI (GIL-atomic string read in the
+        # status line; no message plumbing needed).
+        state.current_effort = turn_config.get("reasoning_effort", "")
+        # After many calls without editing, don't force but the nudge message handles it
+
+        # Stream from LLM — with retry on context-length 400 error
+        retries = 0
+        while retries < 2:
+            try:
+                for event in stream(
+                    model=turn_config["model"],
+                    system=system_prompt,
+                    messages=state.messages,
+                    tool_schemas=filter_tool_schemas(schemas(), turn_config.get("model")),
+                    config=turn_config,
+                ):
+                    if isinstance(event, TextChunk):
+                        yield event
+                    elif isinstance(event, AssistantTurn):
+                        assistant_turn = event
+                break  # success
+            except Exception as e:
+                err = str(e)
+                if is_context_length_error(err):
+                    retries += 1
+                    limit = config.get("context_limit", 131072)
+                    state.messages = emergency_compact(state.messages, limit)
+                    if retries >= 2:
+                        raise
+                    yield TextChunk("\n[context limit hit — compacting and retrying...]\n")
+                else:
+                    raise
+
+        if assistant_turn is None:
+            break
+
+        # Record assistant message
+        state.messages.append({
+            "role": "assistant",
+            "content": assistant_turn.text,
+            "tool_calls": assistant_turn.tool_calls,
+        })
+
+        state.total_input_tokens += assistant_turn.input_tokens
+        state.total_output_tokens += assistant_turn.output_tokens
+        yield TurnDone(assistant_turn.input_tokens, assistant_turn.output_tokens)
+
+        # No tool calls = conversation complete — UNLESS the model emitted a
+        # tool call as text (a Gemma quirk the API can't structure). In that
+        # case nudge it to use the real function interface and retry, instead
+        # of ending the turn with nothing done. Capped so it can never spin.
+        if not assistant_turn.tool_calls:
+            if assistant_turn.had_leaked_call and leaked_call_retries < 2:
+                leaked_call_retries += 1
+                state.messages.append({
+                    "role": "user",
+                    "content": (
+                        "[SYSTEM] Your tool call came through as plain text, so "
+                        "it did not run. Call the tool using the function/tool "
+                        "interface — not text, no <|tool_call> markers. Use the "
+                        "exact tool names (Write, Read, Edit, Bash). Try again."
+                    ),
+                })
+                continue
+            break
+
+        # Execute each tool call
+        for tc in assistant_turn.tool_calls:
+            tool_call_count += 1
+            if tc["name"] in ("Edit", "Write"):
+                session_has_edited = True
+
+            # Check tool call limit
+            if max_tool_calls > 0 and tool_call_count > max_tool_calls:
+                state.messages.append({
+                    "role": "tool",
+                    "tool_call_id": tc["id"],
+                    "name": tc["name"],
+                    "content": "[Tool call limit reached. Respond with your final answer now.]",
+                })
+                continue
+
+            yield ToolStart(tc["name"], tc["input"])
+
+            # Redirect hallucinated tool names to a benign hint instead of a
+            # "tool not found" error the model would loop on.
+            halluc = hallucinated_tool_message(tc["name"])
+            result = halluc if halluc is not None else execute(tc["name"], tc["input"], config)
+            # Guide (never block) on exact-repeat tool calls: prepend an
+            # advisory note when the same call is made again.
+            result = loop_tracker.annotate(tc["name"], tc["input"], result)
+
+            yield ToolEnd(tc["name"], result)
+
+            # Append tool result
+            state.messages.append({
+                "role": "tool",
+                "tool_call_id": tc["id"],
+                "name": tc["name"],
+                "content": result,
+            })
+
+        # Nudge: if past 15 tool calls without any edits, inject gentle guidance
+        if tool_call_count == 15 and not session_has_edited and config.get("force_first_tool"):
+            state.messages.append({
+                "role": "user",
+                "content": "[SYSTEM] Reminder: you should call Edit to fix the bug soon. "
+                           "Read the file if you haven't already, then make your edit.",
+            })

drydock_cli-3.0.15/drydock/bash_safety.py

@@ -0,0 +1,167 @@
+"""Bash command safety denylist.
+
+`tool_bash` runs `shell=True`, so a single hallucinated or careless command
+could wipe the user's disk. This module screens a command *before* it runs and
+refuses only the small set of patterns that are catastrophic and irreversible
+*and* have no legitimate place in a coding task: wiping the filesystem root or
+home, writing raw to a block device, reformatting a disk, or a classic fork
+bomb.
+
+The bar is deliberately high. Ordinary destructive-but-scoped work
+(`rm -rf build/`, `rm -rf node_modules`, `git reset --hard`) is NOT blocked —
+that is real coding work and blocking it would be the kind of net-negative
+circuit breaker we have learned to avoid. When something *is* blocked, the
+tool returns a plain refusal string (it never raises), so the model gets clear
+feedback and can choose a safer command instead of looping on an exception.
+
+All logic original to Drydock.
+"""
+from __future__ import annotations
+
+import re
+
+# Each entry: (compiled pattern, human reason). A reason of None marks the
+# special rm rule, which needs a second check on the delete target (below).
+# Patterns match against the whitespace-normalized command string. Keep them
+# narrow — a false positive blocks legitimate work and erodes trust.
+_RULES: list[tuple[re.Pattern[str], str | None]] = [
+    # rm -rf targeting the filesystem root, home, or a root-level wildcard.
+    # Matches: rm -rf /, rm -fr /*, rm -rf ~, rm -rf $HOME, rm -rf /  (trailing).
+    (
+        re.compile(
+            r"\brm\b[^|;&]*\s-[a-z]*r[a-z]*f|\brm\b[^|;&]*\s-[a-z]*f[a-z]*r",
+            re.IGNORECASE,
+        ),
+        None,  # placeholder; rm needs a second check on the target (below)
+    ),
+    # Raw write to a whole block device (dd of=/dev/sda, > /dev/nvme0n1).
+    (
+        re.compile(r"\bof=/dev/(?:sd|nvme|hd|vd|xvd|mmcblk)", re.IGNORECASE),
+        "writes a raw image directly onto a block device, destroying the disk",
+    ),
+    (
+        re.compile(r">\s*/dev/(?:sd|nvme|hd|vd|xvd|mmcblk)", re.IGNORECASE),
+        "redirects output onto a raw block device, corrupting the disk",
+    ),
+    # Reformat a filesystem.
+    (
+        re.compile(r"\bmkfs(?:\.\w+)?\b", re.IGNORECASE),
+        "reformats a filesystem, erasing everything on it",
+    ),
+    # Repartition / zero a disk.
+    (
+        re.compile(r"\bdd\b[^|;&]*\bof=/dev/", re.IGNORECASE),
+        "uses dd to overwrite a device node",
+    ),
+    # Classic fork bomb.
+    (
+        re.compile(r":\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:"),
+        "is a fork bomb that will exhaust the system's process table",
+    ),
+    # Recursively strip all permissions / ownership from the root.
+    (
+        re.compile(r"\b(?:chmod|chown)\b[^|;&]*\s-[a-z]*R[a-z]*\s[^|;&]*\s/(?:\s|$)", re.IGNORECASE),
+        "recursively changes permissions/ownership of the filesystem root",
+    ),
+]
+
+# rm targets that mean "the whole world." Checked only when the command is an
+# `rm -rf`-style recursive force delete.
+_RM_CATASTROPHIC_TARGET = re.compile(
+    r"\brm\b[^|;&]*\s"
+    r"(?:/|~|\$HOME|/\*|/\s|\.\s*/?\s*\*|--no-preserve-root)"
+    r"(?:\s|$|/\*)",
+    re.IGNORECASE,
+)
+
+
+def dangerous_command(command: str) -> str | None:
+    """Return a refusal reason if the command is catastrophic, else None.
+
+    Conservative by design: only the patterns above trip it. Everything
+    else — including scoped `rm -rf subdir/` — passes through untouched.
+    """
+    if not command or not command.strip():
+        return None
+    cmd = " ".join(command.split())  # normalize whitespace
+
+    for pattern, reason in _RULES:
+        if reason is None:
+            # The rm rule: recursive-force flag present *and* a world target.
+            if pattern.search(cmd) and _rm_hits_world(cmd):
+                return (
+                    "deletes the filesystem root or home directory recursively"
+                )
+            continue
+        if pattern.search(cmd):
+            return reason
+    return None
+
+
+def _rm_hits_world(cmd: str) -> bool:
+    """True if an `rm -rf` command targets / ~ $HOME or a root-level wildcard."""
+    if _RM_CATASTROPHIC_TARGET.search(cmd):
+        return True
+    # `--no-preserve-root` is never used for legitimate scoped deletes.
+    if "--no-preserve-root" in cmd.lower():
+        return True
+    return False
+
+
+def refusal_message(command: str, reason: str) -> str:
+    """The string returned to the model in place of running the command."""
+    return (
+        f"REFUSED: this command {reason}. Drydock will not run it.\n"
+        f"Command: {command.strip()}\n"
+        f"If this was a mistake, run a narrower command scoped to the specific "
+        f"files or directory you intend to change."
+    )
+
+
+# ── Approval tier ───────────────────────────────────────────────────────────
+# Commands that are legitimate but consequential: they should RUN, but only
+# after the user okays them. This is distinct from the catastrophic denylist
+# above (which is never run). Each entry: (pattern, human reason).
+_APPROVAL_RULES: list[tuple[re.Pattern[str], str]] = [
+    (
+        re.compile(r"\b(?:sudo|doas)\b", re.IGNORECASE),
+        "runs with elevated privileges (sudo)",
+    ),
+    (
+        re.compile(
+            r"\b(?:apt|apt-get|dnf|yum|pacman|zypper|apk|brew)\b\s+"
+            r"(?:install|remove|purge|upgrade|update|add)\b",
+            re.IGNORECASE,
+        ),
+        "installs or removes system packages",
+    ),
+    (
+        re.compile(
+            r"\b(?:pip|pip3|pipx|npm|pnpm|yarn|cargo|gem|go)\b\s+"
+            r"(?:install|add|i)\b",
+            re.IGNORECASE,
+        ),
+        "installs packages from a network index",
+    ),
+    (
+        re.compile(r"\b(?:curl|wget)\b", re.IGNORECASE),
+        "fetches content from the network",
+    ),
+    (
+        re.compile(r"\bgit\s+push\b", re.IGNORECASE),
+        "pushes commits to a remote repository",
+    ),
+]
+
+
+def requires_approval(command: str) -> str | None:
+    """Return a reason if the command is sensitive enough to need user
+    approval before running, else None. Assumes the catastrophic denylist
+    (dangerous_command) has already passed."""
+    if not command or not command.strip():
+        return None
+    cmd = " ".join(command.split())
+    for pattern, reason in _APPROVAL_RULES:
+        if pattern.search(cmd):
+            return reason
+    return None