damage-control-dev 0.1.0__py3-none-any.whl

damage_control/breakglass.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Break-glass for the damage-control hooks: works when the venv they run from does not.
+
+The hooks run ``<venv python> -I -m damage_control.hook <kind>`` with ``"onFailure": "block"``,
+so a venv that is gone (``uv tool install --force`` died halfway, a managed Python was
+uninstalled) makes Claude Code refuse EVERY tool call, including the ones you would use to
+repair it. This file is the way out. It is standard library only and ``init`` copies it to
+``<config dir>/bin/damage-control-breakglass``. Run it with the system ``python3`` from an
+ordinary terminal (not through Claude Code):
+
+    python3 damage-control-breakglass status     [--settings PATH]
+    python3 damage-control-breakglass unregister [--settings PATH]
+
+``unregister`` removes exactly the damage-control entries (the file is backed up first,
+written atomically, and an unparseable file is refused, never rewritten). With them gone
+Claude Code stops calling the hooks, so **damage control is OFF** until you repair the
+install and run ``damage-control-dev init``.
+
+It is a human's tool: the hook guards ``~/.claude/settings.json``, so a policed agent
+cannot rewrite it.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+HOOK_MODULE = "damage_control.hook"
+BACKUP_SUFFIX = ".breakglass.bak"
+
+
+def default_settings() -> Path:
+    return Path.home() / ".claude" / "settings.json"
+
+
+def is_ours(hook) -> bool:
+    args = hook.get("args") if isinstance(hook, dict) else None
+    return isinstance(args, list) and HOOK_MODULE in args
+
+
+def load(path: Path):
+    try:
+        raw = path.read_bytes()
+    except FileNotFoundError:
+        return None, {}
+    parsed = json.loads(raw.decode("utf-8-sig"))  # ValueError propagates: an unparseable file is refused
+    if not isinstance(parsed, dict):
+        raise ValueError(f"{path} is not a JSON object")
+    return raw, parsed
+
+
+def owned(settings) -> list:
+    hooks = settings.get("hooks")
+    pre = hooks.get("PreToolUse") if isinstance(hooks, dict) else None
+    found = []
+    for entry in pre if isinstance(pre, list) else []:
+        inner = entry.get("hooks") if isinstance(entry, dict) else None
+        for hook in inner if isinstance(inner, list) else []:
+            if is_ours(hook):
+                found.append((entry.get("matcher"), hook))
+    return found
+
+
+def runs(interpreter: str) -> bool:
+    try:
+        return subprocess.run([interpreter, "-I", "-c", "import damage_control"],
+                              capture_output=True, timeout=20).returncode == 0
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+def cmd_status(path: Path) -> int:
+    try:
+        _, settings = load(path)
+    except (ValueError, OSError) as e:
+        print(f"{path}: cannot read it ({e}); nothing to report")
+        return 1
+    entries = owned(settings)
+    if not entries:
+        print(f"No damage-control hooks are registered in {path}.")
+        return 0
+    print(f"{len(entries)} damage-control hook entries in {path}")
+    code = 0
+    for interpreter in sorted({h.get("command", "") for _, h in entries}):
+        ok = runs(interpreter)
+        print(f"  interpreter {interpreter}: {'ok' if ok else 'DEAD — every tool call is being blocked'}")
+        code |= 0 if ok else 1
+    if code:
+        print("Fix: run `unregister`, repair the install, then `damage-control-dev init`.")
+    return code
+
+
+def cmd_unregister(path: Path) -> int:
+    try:
+        raw, settings = load(path)
+    except (ValueError, OSError) as e:
+        print(f"REFUSED: {path} cannot be read as JSON ({e}). Edit it by hand: delete the "
+              f"PreToolUse entries whose command runs `-m {HOOK_MODULE}`.")
+        return 1
+    if not owned(settings):
+        print("Nothing to remove.")
+        return 0
+    kept = []
+    for entry in settings["hooks"]["PreToolUse"]:
+        inner = entry.get("hooks") if isinstance(entry, dict) else None
+        if isinstance(inner, list):
+            remaining = [h for h in inner if not is_ours(h)]
+            if len(remaining) != len(inner):
+                if not remaining:
+                    continue
+                entry = dict(entry, hooks=remaining)
+        kept.append(entry)
+    settings["hooks"]["PreToolUse"] = kept
+    backup = path.with_name(path.name + BACKUP_SUFFIX)
+    if raw is not None and not backup.exists():
+        shutil.copy2(path, backup)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(json.dumps(settings, indent=2))
+            f.flush()
+            os.fsync(f.fileno())
+        shutil.copymode(path, tmp)
+        os.replace(tmp, path)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+    print(f"Removed the damage-control hooks from {path} (backup: {backup.name}).")
+    print("DAMAGE CONTROL IS NOW OFF. Repair the install, then re-register:")
+    print("  damage-control-dev init")
+    return 0
+
+
+def main(argv) -> int:
+    args = list(argv)
+    path = default_settings()
+    if "--settings" in args:
+        i = args.index("--settings")
+        if i + 1 >= len(args):
+            print(__doc__)
+            return 2
+        path = Path(args[i + 1])
+        del args[i:i + 2]
+    commands = {"status": cmd_status, "unregister": cmd_unregister}
+    if len(args) != 1 or args[0] not in commands:
+        print(__doc__)
+        return 2
+    return commands[args[0]](path)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

damage_control/claude_code.py

@@ -0,0 +1,148 @@
+"""Claude Code as an install target (#1209 M5): where its settings live, what a registration is.
+
+A registration is the exec form Claude Code runs without a shell:
+``{"command": <absolute interpreter>, "args": ["-I", "-m", "damage_control.hook", kind, ...],
+"timeout": N, "onFailure": "block"}``. Our entries are recognized by the package module name
+in ``args`` and by nothing else.
+
+Standard library only.
+"""
+
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, NamedTuple, Optional, Tuple
+
+HOOK_MODULE = "damage_control.hook"
+HARNESS = "claude-code"
+
+# ``onFailure: "block"`` and exec-form ``args`` need Claude Code >= this. Below it a hook crash,
+# timeout or missing interpreter lets the tool call RUN, so registering anyway is a weaker
+# config than the one asked for.
+ONFAILURE_MIN_VERSION = (2, 1, 295)
+
+# matcher -> hook kind. Several matchers share a kind (Read/Grep/Glob), PowerShell is a
+# separate tool name with Bash's input shape.
+MATCHERS: Dict[str, str] = {
+    "Bash": "bash",
+    "PowerShell": "bash",
+    "Edit": "edit",
+    "NotebookEdit": "edit",
+    "Write": "write",
+    "Read": "read",
+    "Grep": "read",
+    "Glob": "read",
+    "mcp__.*": "mcp",
+}
+
+SCOPES = ("user", "project", "managed")
+
+
+def settings_path(scope: str, cwd: Optional[Path] = None) -> Path:
+    """The settings file ``scope`` registers into."""
+    if scope == "user":
+        return Path.home() / ".claude" / "settings.json"
+    if scope == "project":
+        return (cwd or Path.cwd()) / ".claude" / "settings.json"
+    if scope == "managed":
+        base = (Path("/Library/Application Support/ClaudeCode") if sys.platform == "darwin"
+                else Path("/etc/claude-code"))
+        return base / "managed-settings.d" / "50-damage-control.json"
+    raise ValueError(f"unknown scope {scope!r}; expected one of {SCOPES}")
+
+
+def parse_version(text: str) -> Optional[Tuple[int, ...]]:
+    m = re.match(r"\s*(\d+)\.(\d+)\.(\d+)", text or "")
+    return tuple(int(g) for g in m.groups()) if m else None
+
+
+def detect_version() -> Optional[Tuple[int, ...]]:
+    """The installed Claude Code version, or None when ``claude`` is absent or unreadable."""
+    try:
+        out = subprocess.run(["claude", "--version"], capture_output=True, text=True, timeout=15).stdout
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return parse_version(out)
+
+
+def version_text(version: Optional[Tuple[int, ...]]) -> str:
+    return ".".join(map(str, version)) if version else "unknown"
+
+
+def supports_fail_closed(version: Optional[Tuple[int, ...]]) -> Optional[bool]:
+    """True/False once the version is known; None when it could not be read."""
+    return None if version is None else version >= ONFAILURE_MIN_VERSION
+
+
+def hook_args(kind: str, profile: Optional[str] = None) -> List[str]:
+    args = ["-I", "-m", HOOK_MODULE, kind]
+    if profile:
+        args += ["--profile", profile]
+    return args
+
+
+def is_ours(hook: Any) -> bool:
+    """A hook dict that runs this package's hook module."""
+    args = hook.get("args") if isinstance(hook, dict) else None
+    return isinstance(args, list) and HOOK_MODULE in args
+
+
+def profile_of(hook: Dict[str, Any]) -> Optional[str]:
+    """The ``--profile`` path in one of our hook dicts, if any."""
+    args = hook.get("args") or []
+    return args[args.index("--profile") + 1] if "--profile" in args and args.index("--profile") + 1 < len(args) else None
+
+
+def kind_of(hook: Dict[str, Any]) -> Optional[str]:
+    args = hook.get("args") or []
+    i = args.index(HOOK_MODULE) + 1 if HOOK_MODULE in args else len(args)
+    return args[i] if i < len(args) else None
+
+
+class Owned(NamedTuple):
+    matcher: Any
+    hook: Dict[str, Any]
+
+
+def pre_tool_use(settings: Dict[str, Any]) -> Optional[List[Any]]:
+    hooks = settings.get("hooks")
+    pre = hooks.get("PreToolUse") if isinstance(hooks, dict) else None
+    return pre if isinstance(pre, list) else None
+
+
+def owned_entries(settings: Dict[str, Any]) -> List[Owned]:
+    """Every hook of ours in ``settings``, with the matcher it sits under. Malformed entries are skipped."""
+    found: List[Owned] = []
+    for entry in pre_tool_use(settings) or []:
+        inner = entry.get("hooks") if isinstance(entry, dict) else None
+        if isinstance(inner, list):
+            found.extend(Owned(entry.get("matcher"), h) for h in inner if is_ours(h))
+    return found
+
+
+def foreign_entry_count(settings: Dict[str, Any]) -> int:
+    """PreToolUse hooks that are not ours: the user's own, left strictly alone."""
+    count = 0
+    for entry in pre_tool_use(settings) or []:
+        inner = entry.get("hooks") if isinstance(entry, dict) else None
+        count += sum(1 for h in inner if not is_ours(h)) if isinstance(inner, list) else 0
+    return count
+
+
+def wanted_hook(interpreter: str, kind: str, timeout: int, fail_closed: bool,
+                profile: Optional[str] = None) -> Dict[str, Any]:
+    hook: Dict[str, Any] = {"type": "command", "command": interpreter,
+                            "args": hook_args(kind, profile), "timeout": timeout}
+    if fail_closed:
+        hook["onFailure"] = "block"
+    return hook
+
+
+def selftest_command(interpreter: str, kind: str, profile: Optional[str] = None) -> List[str]:
+    return [interpreter, *hook_args(kind, profile)]
+
+
+def absolute_interpreter() -> str:
+    return os.path.abspath(sys.executable)

damage_control/cli.py

@@ -0,0 +1,173 @@
+"""``damage-control-dev``: install, inspect and operate the Claude Code hooks (#1209 M5).
+
+    damage-control-dev init [--scope user|project|managed] [--dry-run] [--refresh] [--fail-open]
+    damage-control-dev status [--json]      # read-only drift report
+    damage-control-dev doctor [--fix] [--json]
+    damage-control-dev uninstall [--purge]
+    damage-control-dev check "<command>"    # what would the hook decide?
+    damage-control-dev rules                # the enforced rule ids
+    damage-control-dev packs|groups list|enable|disable [name]
+
+Exit status: 0 = fine, 1 = a refusal or a finding marked ``[!!]``, 2 = bad usage.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from damage_control import __version__, engine, install, packs
+from damage_control import claude_code as cc
+from damage_control import harness_config as hc
+from damage_control.profile import ProfileError, load_profile
+
+
+def _common(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--harness", default=cc.HARNESS, choices=[cc.HARNESS], help="the agent harness (Claude Code only)")
+    parser.add_argument("--scope", default="user", choices=cc.SCOPES, help="which settings file to manage (default: user)")
+    parser.add_argument("--settings", metavar="PATH", help="manage this settings file instead of the scope's")
+    parser.add_argument("--profile", metavar="PATH", help="a host profile manifest the hooks load (for host installers)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="damage-control-dev", description=__doc__.split("\n\n")[0])
+    parser.add_argument("--version", action="version", version=f"damage-control-dev {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("init", help="register the hooks, prove they run, record the install")
+    _common(p)
+    p.add_argument("--dry-run", action="store_true", help="show the diff and write nothing")
+    p.add_argument("--refresh", action="store_true", help="print and acknowledge the ruleset diff (loosening is marked !!)")
+    p.add_argument("--force", action="store_true", help="override the downgrade refusal")
+    p.add_argument("--fail-open", action="store_true", help="register without onFailure=block (recorded in the policy)")
+    p.add_argument("--allow-dev-source", action="store_true", help="allow an editable/vcs/uvx install to write machine-global state")
+    p.add_argument("--apply", action="store_true", help="managed scope only: actually write (otherwise a dry run)")
+
+    p = sub.add_parser("status", help="read-only drift report")
+    _common(p)
+    p.add_argument("--json", action="store_true")
+
+    p = sub.add_parser("doctor", help="status plus self-test, harness version and repair")
+    _common(p)
+    p.add_argument("--json", action="store_true")
+    p.add_argument("--fix", action="store_true", help="re-run init to repair the registration")
+    p.add_argument("--allow-dev-source", action="store_true")
+
+    p = sub.add_parser("uninstall", help="remove exactly our entries")
+    _common(p)
+    p.add_argument("--purge", action="store_true", help="also delete the policy, overlays and install state")
+
+    p = sub.add_parser("check", help="what would the hooks decide for a shell command?")
+    p.add_argument("--profile", metavar="PATH")
+    p.add_argument("text")
+    p.add_argument("--json", action="store_true")
+
+    p = sub.add_parser("rules", help="list the enforced rule ids")
+    p.add_argument("--profile", metavar="PATH")
+    p.add_argument("--json", action="store_true")
+
+    for noun in ("packs", "groups"):
+        p = sub.add_parser(noun, help=f"list, enable or disable {noun} (enable/disable: human terminal only)")
+        p.add_argument("--profile", metavar="PATH")
+        p.add_argument("action", choices=["list", "enable", "disable"])
+        p.add_argument("name", nargs="?")
+    return parser
+
+
+def _load_profile(path: Optional[str]) -> None:
+    if path:
+        engine.install_profile(load_profile(Path(path)))
+
+
+def _print_findings(findings: List[install.Finding], as_json: bool) -> int:
+    code = install.exit_code(findings)
+    if as_json:
+        print(json.dumps({"ok": code == 0, "version": __version__, "profile": engine.PROFILE.name,
+                          "findings": [f._asdict() for f in findings]}, indent=2))
+    else:
+        for f in findings:
+            print(f.line())
+    return code
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    result = engine.check_command(args.text, engine.load_effective_config(), cwd=str(Path.cwd()))
+    if args.json:
+        print(json.dumps(result, indent=2, default=str))
+    else:
+        print(f"{result.get('decision')}: {result.get('reason') or 'no rule matched'}"
+              + (f" [{result['id']}]" if result.get("id") else ""))
+    return 0
+
+
+def _cmd_rules(args: argparse.Namespace) -> int:
+    config = engine.load_effective_config()
+    rows = [{"id": r["id"], "tier": "ask" if r.get("ask") else "block", "source": r.get("source")}
+            for r in config["bashToolPatterns"]]
+    if args.json:
+        print(json.dumps(rows, indent=2))
+    else:
+        for r in rows:
+            print(f"{r['tier']:5} {r['id']}  ({r['source']})")
+    return 0
+
+
+def _cmd_pack_group(args: argparse.Namespace) -> int:
+    kind = "pack" if args.command == "packs" else "group"
+    policy = engine.policy_file_path()
+    if args.action == "list":
+        for row in packs.overview(policy, *engine.overlay_dirs()):
+            if row["kind"] == kind:
+                print(f"{'on ' if row['enabled'] else 'off'} {row['name']:16} {row['description']}")
+        return 0
+    if not sys.stdin.isatty():
+        print(f"REFUSED: changing damage-control {kind}s is a policy change; run it from your own terminal.", file=sys.stderr)
+        return 1
+    try:
+        packs.set_enabled(policy, kind, args.name or "", args.action == "enable")
+    except packs.MembershipError as e:
+        print(f"REFUSED: {e}", file=sys.stderr)
+        return 1
+    print(f"{args.name}: {'enabled' if args.action == 'enable' else 'disabled'}")
+    return 0
+
+
+def run(args: argparse.Namespace) -> int:
+    _load_profile(getattr(args, "profile", None))
+    profile = getattr(args, "profile", None)
+    command = args.command
+    if command == "init":
+        return install.init(scope=args.scope, settings=args.settings, dry_run=args.dry_run, refresh=args.refresh,
+                            force=args.force, fail_open=args.fail_open, allow_dev_source=args.allow_dev_source,
+                            apply=args.apply, profile=profile)
+    if command == "status":
+        return _print_findings(install.inspect(args.scope, args.settings, profile_hint=profile), args.json)
+    if command == "doctor":
+        findings = install.inspect(args.scope, args.settings, deep=True, profile_hint=profile)
+        code = _print_findings(findings, args.json)
+        if args.fix and code:
+            print("--fix: re-running init to repair the registration", file=sys.stderr)
+            return install.init(scope=args.scope, settings=args.settings, allow_dev_source=args.allow_dev_source,
+                                profile=profile, force=False)
+        return code
+    if command == "uninstall":
+        return install.uninstall(args.scope, args.settings, purge=args.purge)
+    if command == "check":
+        return _cmd_check(args)
+    if command == "rules":
+        return _cmd_rules(args)
+    return _cmd_pack_group(args)
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return run(args)
+    except (install.InstallError, hc.ConfigError, ProfileError) as e:
+        print(f"REFUSED: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())