CLAUDE.md의 "금지"는 부탁일 뿐이다 — Claude Code를 확실하게 멈추는 hooks 가드레일 3선【명령 하나로 도입】

프로덕션 환경에 대한 조작은 하지 마세요.

$ date "+%Y-%m-%d %H:%M:%S %Z"
2026-07-17 18:10:47 JST

$ claude --version
2.1.210 (Claude Code)

$ python3 --version
Python 3.14.3

{
  "permissions": {
    "deny": ["Bash(*prod-super-secret-marker*)"]
  }
}

$ claude -p "Run the shell command: echo start prod-super-secret-marker end -- ..." \
    --permission-mode bypassPermissions --dangerously-skip-permissions

Blocked by security policy: matches deny pattern Bash(*prod-super-secret-marker*)

# 프로젝트 루트에서 실행 (인수 생략 시에는 현재 디렉터리에 적용)
python3 install_claude_guardrails.py

# 적용 내용만 확인하고 싶을 때 (파일 변경 없음)
python3 install_claude_guardrails.py --dry-run

# 일부 레시피만 넣고 싶을 때 (예: ①과 ③)
python3 install_claude_guardrails.py --recipes 1,3

#!/usr/bin/env python3
"""One-file installer for the 3 PreToolUse guardrail recipes.

Run from your project root (or pass the project path):

    python3 install_claude_guardrails.py            # install into ./
    python3 install_claude_guardrails.py /path/to/project
    python3 install_claude_guardrails.py --recipes 2     # subset
    python3 install_claude_guardrails.py --dry-run       # show plan only

What it does:
- Writes the recipe scripts into <project>/.claude/hooks/
- Adds matching hook entries to <project>/.claude/settings.json under
  hooks.PreToolUse (matcher "Bash"), creating the file if it does not exist
- Leaves every other key (permissions, env, other matchers/events) untouched
- Backs up settings.json and any differing hook script before overwriting
- Idempotent: a second run reports "nothing to do"
- Refuses to run against your home directory (that would edit the user-global
  ~/.claude/settings.json instead of a project-level one)

It intentionally does NOT touch permissions.allow / permissions.deny.
"""
import argparse
import copy
import datetime
import json
import shutil
import subprocess
import sys
from pathlib import Path

SMOKE_INPUT = '{"tool_input": {"command": "echo hello"}}'

RECIPE_SOURCES = {
    "recipe1_resolved_target_guard.py": r'''#!/usr/bin/env python3
"""PreToolUse hook (Recipe 1): block deploy commands whose *resolved* target
is production, even when the literal Bash command string never contains the
word "prod" (e.g. the target is read from a file/subshell at execution time).
"""
import json
import pathlib
import sys

data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "")

if "deploy.sh" not in command:
    sys.exit(0)  # not our target command; let normal permission flow decide

target_file = pathlib.Path(".deploy-target")
resolved_target = target_file.read_text().strip() if target_file.exists() else "unknown"

if resolved_target.startswith("prod"):
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": (
                f"Resolved deploy target is '{resolved_target}' (read from "
                ".deploy-target at hook time), which is a production target. "
                "Blocked by PreToolUse hook regardless of what the literal "
                "command string contains."
            ),
        }
    }))
sys.exit(0)
''',
    "recipe2_protected_branch_guard.py": r'''#!/usr/bin/env python3
"""PreToolUse hook (Recipe 2): block `git commit` while the current branch
is a protected branch (main/master)."""
import json
import subprocess
import sys

data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "")

if "git commit" not in command:
    sys.exit(0)

try:
    branch = subprocess.run(
        ["git", "branch", "--show-current"],
        capture_output=True, text=True, check=True,
    ).stdout.strip()
except Exception:
    branch = ""

PROTECTED_BRANCHES = {"main", "master"}
if branch in PROTECTED_BRANCHES:
    sys.stderr.write(
        f"Blocked: direct `git commit` on protected branch '{branch}' is not "
        "allowed. Create a feature branch first.\n"
    )
    sys.exit(2)

sys.exit(0)
''',
    "recipe3_rm_allowlist_guard.py": r'''#!/usr/bin/env python3
"""PreToolUse hook (Recipe 3): only allow `rm` to delete paths that RESOLVE
(after following `..` and symlinks) inside the project's tmp/ directory."""
import json
import os
import re
import sys

data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "")

m = re.match(r"^\s*rm(\s+-\S+)*\s+(?P<path>\S+)\s*$", command)
if not m:
    sys.exit(0)  # not a simple rm we recognize; normal permission flow applies

target = m.group("path")
project_root = os.getcwd()
allowed_root = os.path.realpath(os.path.join(project_root, "tmp"))
resolved = os.path.realpath(os.path.join(project_root, target))

inside_allowed = (
    resolved == allowed_root
    or resolved.startswith(allowed_root + os.sep)
)

if inside_allowed:
    decision, reason = "allow", f"rm target resolves inside tmp/ ({resolved})"
else:
    decision, reason = "deny", (
        f"rm target '{target}' resolves to '{resolved}', which is outside "
        f"the allowed directory '{allowed_root}'."
    )

print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": decision,
        "permissionDecisionReason": reason,
    }
}))
sys.exit(0)
''',
}

RECIPE_KEYS = {"1": "recipe1_resolved_target_guard.py",
               "2": "recipe2_protected_branch_guard.py",
               "3": "recipe3_rm_allowlist_guard.py"}

def hook_entry(script_name: str) -> dict:
    return {
        "type": "command",
        "command": f'python3 "${{CLAUDE_PROJECT_DIR}}/.claude/hooks/{script_name}"',
    }

def fail(msg: str):
    print(f"ERROR: {msg}", file=sys.stderr)
    sys.exit(1)

def main() -> None:
    parser = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    parser.add_argument("project", nargs="?", default=".",
                        help="target project directory (default: current directory)")
    parser.add_argument("--recipes", default="1,2,3",
                        help="comma-separated subset to install (default: 1,2,3)")
    parser.add_argument("--dry-run", action="store_true", help="show plan only")
    args = parser.parse_args()

    project = Path(args.project).expanduser().resolve()
    if not project.is_dir():
        fail(f"project directory not found: {project}")
    if project == Path.home():
        fail("refusing to install into your home directory — that would edit "
             "~/.claude/settings.json (user-global settings). "
             "Run from a project root or pass its path")
    if project == Path(project.anchor):
        fail("refusing to install into the filesystem root")

    selected = []
    for key in args.recipes.split(","):
        key = key.strip()
        if key not in RECIPE_KEYS:
            fail(f"unknown recipe '{key}' (valid: 1,2,3)")
        if RECIPE_KEYS[key] not in selected:
            selected.append(RECIPE_KEYS[key])

    claude_dir = project / ".claude"
    hooks_dir = claude_dir / "hooks"
    settings_path = claude_dir / "settings.json"
    stamp = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")

    # ---- read current settings (a malformed file aborts before any change)
    old_settings = None
    if settings_path.exists():
        try:
            old_settings = json.loads(settings_path.read_text(encoding="utf-8"))
        except json.JSONDecodeError as e:
            fail(f"{settings_path} is not valid JSON ({e}); nothing was changed")
        if not isinstance(old_settings, dict):
            fail(f"{settings_path} top-level is not a JSON object; nothing was changed")

    # ---- plan the settings merge on a copy
    new_settings = copy.deepcopy(old_settings) if old_settings is not None else {}
    hooks_cfg = new_settings.setdefault("hooks", {})
    if not isinstance(hooks_cfg, dict):
        fail("settings.json 'hooks' is not an object; refusing to modify")
    pre_list = hooks_cfg.setdefault("PreToolUse", [])
    if not isinstance(pre_list, list):
        fail("settings.json 'hooks.PreToolUse' is not an array; refusing to modify")

    bash_entry = None
    for entry in pre_list:
        if isinstance(entry, dict) and entry.get("matcher") == "Bash":
            bash_entry = entry
            break
    created_matcher = bash_entry is None
    if created_matcher:
        bash_entry = {"matcher": "Bash", "hooks": []}

    hook_list = bash_entry.setdefault("hooks", [])
    if not isinstance(hook_list, list):
        fail("PreToolUse entry for matcher 'Bash' has a non-array 'hooks'; refusing to modify")

    existing_commands = {h.get("command") for h in hook_list if isinstance(h, dict)}
    to_add = [hook_entry(n) for n in selected
              if hook_entry(n)["command"] not in existing_commands]
    if to_add:
        hook_list.extend(to_add)
        if created_matcher:
            pre_list.append(bash_entry)

    # ---- plan the script writes
    write_plan = []  # (name, dst, needs_backup)
    for name in selected:
        dst = hooks_dir / name
        if dst.exists():
            if dst.read_text(encoding="utf-8") == RECIPE_SOURCES[name]:
                continue
            write_plan.append((name, dst, True))
        else:
            write_plan.append((name, dst, False))

    if not write_plan and not to_add:
        print(f"OK: nothing to do — selected recipes already installed in {project}")
        return

    print(f"Target project : {project}")
    print(f"Recipes        : {', '.join(selected)}")
    for name, dst, needs_backup in write_plan:
        action = "update (backup first)" if needs_backup else "write"
        print(f"  script {action}: {dst.relative_to(project)}")
    for entry in to_add:
        print(f"  settings add : {entry['command']}")
    if not to_add:
        print("  settings     : unchanged (entries already present)")

    if args.dry_run:
        print("DRY RUN: no files were changed")
        return

    # ---- execute
    hooks_dir.mkdir(parents=True, exist_ok=True)
    for name, dst, needs_backup in write_plan:
        if needs_backup:
            backup = dst.with_name(dst.name + f".bak-{stamp}")
            shutil.copy2(dst, backup)
            print(f"  backed up    : {backup.relative_to(project)}")
        dst.write_text(RECIPE_SOURCES[name], encoding="utf-8")

    if to_add:
        if settings_path.exists():
            backup = settings_path.with_name(settings_path.name + f".bak-{stamp}")
            shutil.copy2(settings_path, backup)
            print(f"  backed up    : {backup.relative_to(project)}")
        settings_path.write_text(
            json.dumps(new_settings, ensure_ascii=False, indent=2) + "\n",
            encoding="utf-8",
        )

    # ---- smoke test: a neutral command must pass through (exit 0, no output)
    print("Smoke test (neutral command should pass through: exit 0, no output):")
    all_ok = True
    for name in selected:
        proc = subprocess.run(
            [sys.executable, str(hooks_dir / name)],
            input=SMOKE_INPUT, capture_output=True, text=True, cwd=str(project),
        )
        ok = proc.returncode == 0 and not proc.stdout.strip() and not proc.stderr.strip()
        all_ok = all_ok and ok
        print(f"  {'PASS' if ok else 'FAIL'}: {name} (exit={proc.returncode})")
    if not all_ok:
        print("WARNING: smoke test failed — check python3 and script contents",
              file=sys.stderr)
        sys.exit(1)

    print("Done. Unit-test each hook with: echo '<json>' | python3 .claude/hooks/<script>")

if __name__ == "__main__":
    main()

{
  "permissions": {
    "allow": [
      "Bash(./deploy.sh*)",
      "Bash(git commit*)",
      "Bash(git add*)",
      "Bash(rm *)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "python3 \"${CLAUDE_PROJECT_DIR}/.claude/hooks/recipe1_resolved_target_guard.py\"" },
          { "type": "command", "command": "python3 \"${CLAUDE_PROJECT_DIR}/.claude/hooks/recipe2_protected_branch_guard.py\"" },
          { "type": "command", "command": "python3 \"${CLAUDE_PROJECT_DIR}/.claude/hooks/recipe3_rm_allowlist_guard.py\"" }
        ]
      }
    ]
  }
}

sandbox-repo/
  .claude/
    settings.json              # PreToolUse hook 3본 + permissions.allow
    hooks/
      recipe1_resolved_target_guard.py
      recipe2_protected_branch_guard.py
      recipe3_rm_allowlist_guard.py
  deploy.sh                    # 더미 배포 스크립트 (echo 뿐, 파괴적 조작 없음)
  .deploy-target               # "현재 배포 대상"을 나타내는 상태 파일 (1행)
  tmp/scratch.txt              # 허용 리스트 안의 삭제 대상 (검증용)
  important-root-file.txt      # 허용 리스트 밖의 더미 파일
  README.md

#!/usr/bin/env python3
"""PreToolUse hook (Recipe 1): block deploy commands whose *resolved* target
is production, even when the literal Bash command string never contains the
word "prod" (e.g. the target is read from a file/subshell at execution time).
"""
import json
import pathlib
import sys

data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "")

if "deploy.sh" not in command:
    sys.exit(0)  # not our target command; let normal permission flow decide

target_file = pathlib.Path(".deploy-target")
resolved_target = target_file.read_text().strip() if target_file.exists() else "unknown"

if resolved_target.startswith("prod"):
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": (
                f"Resolved deploy target is '{resolved_target}' (read from "
                ".deploy-target at hook time), which is a production target. "
                "Blocked by PreToolUse hook regardless of what the literal "
                "command string contains."
            ),
        }
    }))
sys.exit(0)

$ claude -p "Run the shell command: ./deploy.sh \$(cat .deploy-target) -- ..." --permission-mode default

출력 (발췌):
The command was blocked by a PreToolUse hook before it executed. It did not run.
Resolved deploy target is 'prod-billing-db' (read from .deploy-target at hook
time), which is a production target. Blocked by PreToolUse hook regardless of
what the literal command string contains.

$ claude -p "Run the shell command: ./deploy.sh \$(cat .deploy-target) -- ..." \
    --permission-mode bypassPermissions --dangerously-skip-permissions

출력 (발췌):
Deploying to target: staging-web
Exit: success, no errors, no permission prompts, no denials.

#!/usr/bin/env python3
"""PreToolUse hook (Recipe 2): block `git commit` while the current branch
is a protected branch (main/master)."""
import json
import subprocess
import sys

data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "")

if "git commit" not in command:
    sys.exit(0)

try:
    branch = subprocess.run(
        ["git", "branch", "--show-current"],
        capture_output=True, text=True, check=True,
    ).stdout.strip()
except Exception:
    branch = ""

PROTECTED_BRANCHES = {"main", "master"}
if branch in PROTECTED_BRANCHES:
    sys.stderr.write(
        f"Blocked: direct `git commit` on protected branch '{branch}' is not "
        "allowed. Create a feature branch first.\n"
    )
    sys.exit(2)

sys.exit(0)

$ git branch --show-current
main
$ claude -p "Run the shell command: git commit -m 'recipe2 positive test commit' -- ..." \
    --permission-mode bypassPermissions --dangerously-skip-permissions

출력:
PreToolUse:Bash hook error: [python3 "${CLAUDE_PROJECT_DIR}/.claude/hooks/recipe2_protected_branch_guard.py"]:
Blocked: direct `git commit` on protected branch 'main' is not allowed. Create a feature branch first.

$ git log --oneline
f707f94 initial commit          ← 커밋은 늘지 않았다 (올바르게 차단됨)

$ git checkout -qb feature/recipe2-negative
$ claude -p "Run the shell command: git commit -m 'recipe2 negative test commit' -- ..." \
    --permission-mode bypassPermissions --dangerously-skip-permissions

출력:
[feature/recipe2-negative fe73a2c] recipe2 negative test commit
 1 file changed, 1 insertion(+)

$ git log --oneline
fe73a2c recipe2 negative test commit   ← 새 커밋이 실제로 만들어졌다
f707f94 initial commit

#!/usr/bin/env python3
"""PreToolUse hook (Recipe 3): only allow `rm` to delete paths that RESOLVE
(after following `..` and symlinks) inside the project's tmp/ directory."""
import json
import os
import re
import sys

data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "")

m = re.match(r"^\s*rm(\s+-\S+)*\s+(?P<path>\S+)\s*$", command)
if not m:
    sys.exit(0)  # not a simple rm we recognize; normal permission flow applies

target = m.group("path")
project_root = os.getcwd()
allowed_root = os.path.realpath(os.path.join(project_root, "tmp"))
resolved = os.path.realpath(os.path.join(project_root, target))

inside_allowed = (
    resolved == allowed_root
    or resolved.startswith(allowed_root + os.sep)
)

if inside_allowed:
    decision, reason = "allow", f"rm target resolves inside tmp/ ({resolved})"
else:
    decision, reason = "deny", (
        f"rm target '{target}' resolves to '{resolved}', which is outside "
        f"the allowed directory '{allowed_root}'."
    )

print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": decision,
        "permissionDecisionReason": reason,
    }
}))
sys.exit(0)

$ claude -p "... 1. create scratch-outside/decoy.txt  2. rm -rf tmp/../scratch-outside/decoy.txt ..." \
    --permission-mode bypassPermissions --dangerously-skip-permissions

출력 (발췌. 경로는 가림 처리):
rm target 'tmp/../scratch-outside/decoy.txt' resolves to
'~/sandbox/sandbox-repo/scratch-outside/decoy.txt', which is outside
the allowed directory '~/sandbox/sandbox-repo/tmp'.
(중략)
Outcome: blocked by the PreToolUse hook.
(중략)
The decoy file was not deleted.

$ ls -la scratch-outside/decoy.txt
-rw-r--r--  1 sano  wheel  46 ...  decoy.txt   ← 삭제되지 않았다

$ claude -p "... rm tmp/scratch.txt ..." --permission-mode bypassPermissions --dangerously-skip-permissions

출력 (발췌):
$ rm tmp/scratch.txt; echo "exit status: $?"
exit status: 0
(전략)ALLOWED by the hook — not blocked. Exit status: 0.

$ ls tmp/
(비어 있음. scratch.txt 는 삭제됨 ← 올바르게 허용됨)

echo '{"tool_input": {"command": "git commit -m test"}}' | \
  python3 .claude/hooks/recipe2_protected_branch_guard.py
echo "exit code: $?"