claude-dev-env 1.94.0 → 1.95.0

package/docs/CODE_RULES.md

@@ -94,4 +94,4 @@ If you already have the data, don't fetch it again.
 
 ## 11. ENFORCEMENT SURFACES
 
-⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery, docstring-prose-matches-implementation; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–Q) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit. The diagram-first docstring standard (a summary line, then a `::` example or doctest, then a couple of short prose lines) lives in `packages/claude-dev-env/rules/plain-illustrative-docstrings.md`, enforced by the `check_docstring_runon_sentence` and `check_docstring_prose_wall_without_illustration` backstop hooks and Category O9 audit.
+⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery, docstring-prose-matches-implementation). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–Q) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit. The diagram-first docstring standard (a summary line, then a `::` example or doctest, then a couple of short prose lines) lives in `packages/claude-dev-env/rules/plain-illustrative-docstrings.md`, enforced by the `check_docstring_runon_sentence` and `check_docstring_prose_wall_without_illustration` backstop hooks and Category O9 audit.

package/hooks/blocking/code_rules_enforcer.py

@@ -158,6 +158,7 @@ from code_rules_shared import (  # noqa: E402
     is_ephemeral_script_path,
     is_hook_infrastructure,
     is_test_file,
+    is_under_session_scratchpad,
 )
 from code_rules_string_magic import (  # noqa: E402
     check_inline_literal_collections,
@@ -1104,6 +1105,9 @@ def main(all_arguments: list[str]) -> None:
     tool_input = pretooluse_payload.get("tool_input", {})
     file_path = tool_input.get("file_path", "")
 
+    if is_under_session_scratchpad(file_path, pretooluse_payload):
+        sys.exit(0)
+
     runs_full_verdict = _is_validated_target(file_path)
     if not runs_full_verdict and not _is_hook_infrastructure_python_target(file_path):
         sys.exit(0)

package/hooks/blocking/code_rules_shared.py

@@ -4,6 +4,7 @@ import ast
 import difflib
 import os
 import sys
+import tempfile
 from collections.abc import Collection, Iterator
 from pathlib import Path
 
@@ -29,6 +30,13 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     LEADING_DRIVE_LETTER_PATTERN,
     STRICT_TEST_FILE_BASENAME_PATTERN,
 )
+from hooks_constants.harness_scratchpad_constants import (  # noqa: E402
+    HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME,
+    HARNESS_SCRATCHPAD_PATH_SEPARATOR_REPLACEMENT,
+    HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX,
+    HOOK_PAYLOAD_SESSION_ID_KEY,
+    HOOK_PAYLOAD_WORKING_DIRECTORY_KEY,
+)
 from hooks_constants.unused_module_import_constants import (  # noqa: E402
     TYPE_CHECKING_IDENTIFIER,
 )
@@ -267,6 +275,80 @@ def is_ephemeral_script_path(file_path: str) -> bool:
     return False
 
 
+def _resolve_session_scratchpad_root(hook_payload: dict) -> str | None:
+    """Rebuild the harness session scratchpad directory from a PreToolUse payload.
+
+    ::
+
+        payload.cwd = /home/user/project    payload.session_id = 5f2c...
+                          |                            |
+        <tempdir>/claude-<uid>/-home-user-project/5f2c.../scratchpad
+                     |               |
+                  os.getuid()   cwd with each "/" turned to "-"
+
+    No environment variable carries this path, so it is rebuilt from the three
+    signals a hook can read: the POSIX user id and the ``cwd`` and ``session_id``
+    fields the harness puts in every PreToolUse payload. The rebuilt directory
+    is returned only when it exists on disk, so a wrong guess or a non-POSIX
+    platform yields None and the gates keep full enforcement.
+
+    Args:
+        hook_payload: The PreToolUse payload carrying ``cwd`` and ``session_id``.
+
+    Returns:
+        The scratchpad directory path when it exists on disk, else None.
+    """
+    get_user_id = getattr(os, "getuid", None)
+    if get_user_id is None:
+        return None
+    session_id = hook_payload.get(HOOK_PAYLOAD_SESSION_ID_KEY, "")
+    working_directory = hook_payload.get(HOOK_PAYLOAD_WORKING_DIRECTORY_KEY, "")
+    if not isinstance(session_id, str) or not session_id:
+        return None
+    if not isinstance(working_directory, str) or not working_directory:
+        return None
+    mangled_working_directory = working_directory.replace("\\", "/").replace(
+        "/", HARNESS_SCRATCHPAD_PATH_SEPARATOR_REPLACEMENT
+    )
+    user_directory_name = f"{HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX}{get_user_id()}"
+    scratchpad_root = os.path.join(
+        tempfile.gettempdir(),
+        user_directory_name,
+        mangled_working_directory,
+        session_id,
+        HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME,
+    )
+    if not os.path.isdir(scratchpad_root):
+        return None
+    return scratchpad_root
+
+
+def is_under_session_scratchpad(file_path: str, hook_payload: dict) -> bool:
+    """Return True when file_path resolves under the harness session scratchpad.
+
+    One-off scripts written to the session scratchpad are throwaway tooling
+    outside every repo, so the TDD and CODE_RULES gates skip them. Both
+    file_path and the rebuilt scratchpad root are resolved through the real
+    filesystem (symlinks followed) before the containment test, so a symlink
+    into the scratchpad exempts and a symlink out of it does not.
+
+    Args:
+        file_path: The path the write targets.
+        hook_payload: The PreToolUse payload carrying ``cwd`` and ``session_id``.
+
+    Returns:
+        True when file_path's real path sits at or under the session scratchpad.
+    """
+    if not file_path:
+        return False
+    scratchpad_root = _resolve_session_scratchpad_root(hook_payload)
+    if scratchpad_root is None:
+        return False
+    real_target = os.path.realpath(file_path)
+    real_root = os.path.realpath(scratchpad_root)
+    return real_target == real_root or real_target.startswith(real_root + os.sep)
+
+
 def is_migration_file(file_path: str) -> bool:
     """Check if file is a Django migration (must be self-contained)."""
     path_lower = file_path.lower().replace("\\", "/")

package/hooks/blocking/code_rules_test_layout.py

@@ -133,7 +133,11 @@ def _referenced_names(tree: ast.Module) -> set[str]:
     }
     return load_names | literal_values
 
-def _dead_constant_messages(tree: ast.Module, referenced_names: set[str]) -> list[str]:
+def _dead_constant_messages(
+    tree: ast.Module,
+    referenced_names: set[str],
+    maximum_issues: int,
+) -> list[str]:
     """Return one message per module constant absent from the referenced set."""
     issues: list[str] = []
     for each_name, each_line in _module_constant_targets(tree):
@@ -142,7 +146,7 @@ def _dead_constant_messages(tree: ast.Module, referenced_names: set[str]) -> lis
         issues.append(
             f"Line {each_line}: constant {each_name!r} - {DEAD_TEST_CONSTANT_GUIDANCE}"
         )
-        if len(issues) >= MAX_TEST_LAYOUT_ISSUES:
+        if len(issues) >= maximum_issues:
             break
     return issues
 
@@ -174,7 +178,9 @@ def check_dead_test_module_constant(content: str, file_path: str) -> list[str]:
     tree = _parse_module(content)
     if tree is None:
         return []
-    return _dead_constant_messages(tree, _referenced_names(tree))
+    return _dead_constant_messages(
+        tree, _referenced_names(tree), MAX_TEST_LAYOUT_ISSUES
+    )
 
 def _node_names_fixture(node: ast.AST) -> bool:
     """Return whether one decorator sub-node spells the pytest fixture marker."""

package/hooks/blocking/plain_language_blocker.py

@@ -26,10 +26,14 @@ from hooks_constants.plain_language_blocker_constants import (  # noqa: E402
     ALL_WRITE_EDIT_TOOL_NAMES,
     ASK_USER_QUESTION_TOOL_NAME,
     BLOCKQUOTE_LINE_PATTERN,
+    DOT_CLAUDE_DIRECTORY_NAME,
     FENCED_CODE_BLOCK_PATTERN,
     FILE_PATH_PATTERN,
     INLINE_CODE_PATTERN,
     MARKDOWN_EXTENSION,
+    PROJECT_ALLOWLIST_FILENAME,
+    PROJECT_ROOT_WALK_LIMIT,
+    REPOSITORY_MARKER_NAME,
     URL_PATTERN,
     USER_FACING_PLAIN_LANGUAGE_NOTICE,
 )
@@ -49,13 +53,23 @@ def strip_non_prose_regions(text: str) -> str:
     return without_paths
 
 
-def find_banned_terms(text: str) -> list[tuple[str, str]]:
+def find_banned_terms(
+    text: str, all_allowlisted_terms: frozenset[str] = frozenset()
+) -> list[tuple[str, str]]:
     """Return each (matched term, suggested replacement) found in the prose.
 
     Each term appears at most once, in first-seen order. Matching is
     case-insensitive and respects word boundaries; multi-word phrases match as
-    whole units. Terms in the software-term allowlist are exempt and never
-    flagged.
+    whole units. Terms in the software-term allowlist and terms in the
+    caller-supplied per-project allowlist are exempt and never flagged.
+
+    Args:
+        text: The prose to scan.
+        all_allowlisted_terms: Lowercased project-vocabulary terms to exempt, on top
+            of the built-in software-term allowlist.
+
+    Returns:
+        The (matched term, suggested replacement) pairs, in first-seen order.
     """
     prose_text = strip_non_prose_regions(text)
     all_matches: list[tuple[str, str]] = []
@@ -69,11 +83,128 @@ def find_banned_terms(text: str) -> list[tuple[str, str]]:
             continue
         if normalized_term in ALL_SOFTWARE_TERMS:
             continue
+        if normalized_term in all_allowlisted_terms:
+            continue
         seen_terms.add(normalized_term)
         all_matches.append((normalized_term, each_replacement))
     return all_matches
 
 
+def _allowlist_start_directory(
+    tool_name: str, tool_input: dict, payload_by_key: dict[str, object]
+) -> Path | None:
+    """Return the directory to begin the project-allowlist search from.
+
+    A Write/Edit/MultiEdit on a file starts at that file's parent directory; an
+    AskUserQuestion (or a write with no path) starts at the session working
+    directory the payload carries.
+
+    Args:
+        tool_name: The intercepted tool's name.
+        tool_input: The intercepted tool's input payload.
+        payload_by_key: The full PreToolUse payload carrying ``cwd``.
+
+    Returns:
+        The starting directory, or None when neither a file path nor a working
+        directory is available.
+    """
+    if tool_name in ALL_WRITE_EDIT_TOOL_NAMES:
+        file_path = tool_input.get("file_path", "")
+        if isinstance(file_path, str) and file_path:
+            return Path(file_path).parent
+    working_directory = payload_by_key.get("cwd", "")
+    if isinstance(working_directory, str) and working_directory:
+        return Path(working_directory)
+    return None
+
+
+def _find_project_allowlist_file(start_directory: Path) -> Path | None:
+    """Walk ancestors from start_directory for a repo-scoped project allowlist file.
+
+    ::
+
+        parent/                      .claude/allow  -> ignored (above the repo root)
+        parent/repo/     <- .git     .claude/allow  -> applied (repo root reached)
+        parent/repo/pkg/             .claude/allow  -> applied (inside the repo tree)
+
+    The allowlist must live inside the repository so it is reviewed like any
+    other committed config. The walk checks each directory for the allowlist,
+    then for the ``.git`` repository marker; it accepts an allowlist at or below
+    the first ``.git``-bearing directory, stops at that repository root, and
+    never ascends past it. When no ``.git`` marker appears within the walk
+    limit, the directory is not inside a repository and no allowlist applies, so
+    a global file such as ``~/.claude/plain-language-allow.json`` never loosens
+    the gate for every project.
+
+    Args:
+        start_directory: The directory to begin the upward walk from.
+
+    Returns:
+        The nearest in-repository ``.claude/plain-language-allow.json`` at or
+        below the repository root, or None when the walk finds no repository
+        root or no allowlist within it.
+    """
+    nearest_allowlist: Path | None = None
+    current_directory = start_directory
+    for _ in range(PROJECT_ROOT_WALK_LIMIT):
+        candidate = current_directory / DOT_CLAUDE_DIRECTORY_NAME / PROJECT_ALLOWLIST_FILENAME
+        if nearest_allowlist is None and candidate.is_file():
+            nearest_allowlist = candidate
+        if (current_directory / REPOSITORY_MARKER_NAME).exists():
+            return nearest_allowlist
+        if current_directory.parent == current_directory:
+            break
+        current_directory = current_directory.parent
+    return None
+
+
+def _parse_project_allowlist_file(allowlist_path: Path) -> frozenset[str]:
+    """Read a JSON array of allowlist words into a lowercased term set.
+
+    Malformed JSON, an unreadable file, or any non-list shape yields an empty
+    set, so the hook falls back to the standard check rather than crashing.
+
+    Args:
+        allowlist_path: The allowlist file to read.
+
+    Returns:
+        The lowercased string entries, or an empty set on any read/parse fault.
+    """
+    try:
+        raw_text = allowlist_path.read_text(encoding="utf-8")
+        parsed_entries = json.loads(raw_text)
+    except (OSError, ValueError):
+        return frozenset()
+    if not isinstance(parsed_entries, list):
+        return frozenset()
+    return frozenset(
+        each_entry.lower() for each_entry in parsed_entries if isinstance(each_entry, str)
+    )
+
+
+def _load_project_allowlist(
+    tool_name: str, tool_input: dict, payload_by_key: dict[str, object]
+) -> frozenset[str]:
+    """Load the per-project domain-vocabulary allowlist for the write's project.
+
+    Args:
+        tool_name: The intercepted tool's name.
+        tool_input: The intercepted tool's input payload.
+        payload_by_key: The full PreToolUse payload carrying ``cwd``.
+
+    Returns:
+        The lowercased allowlist terms for the project the write targets, or an
+        empty set when no allowlist applies.
+    """
+    start_directory = _allowlist_start_directory(tool_name, tool_input, payload_by_key)
+    if start_directory is None:
+        return frozenset()
+    allowlist_path = _find_project_allowlist_file(start_directory)
+    if allowlist_path is None:
+        return frozenset()
+    return _parse_project_allowlist_file(allowlist_path)
+
+
 def build_block_reason(all_matches: list[tuple[str, str]]) -> str:
     """Return a deny reason naming each flagged term and its plain replacement."""
     swap_phrases = ", ".join(
@@ -197,7 +328,10 @@ def evaluate(payload_by_key: dict[str, object]) -> str | None:
     if not prose_text:
         return None
 
-    all_matches = find_banned_terms(prose_text)
+    all_allowlisted_terms = _load_project_allowlist(
+        raw_tool_name, raw_tool_input, payload_by_key
+    )
+    all_matches = find_banned_terms(prose_text, all_allowlisted_terms)
     if not all_matches:
         return None
 

package/hooks/blocking/sensitive_file_protector.py

@@ -1,48 +1,129 @@
 #!/usr/bin/env python3
+"""Deny a Write or Edit whose target filename names a secret or a lock file.
+
+::
+
+    .env              flag: a live secrets file
+    .env.local        flag: a live per-machine secrets file
+    credentials.json  flag: a live credential file
+    id_ed25519        flag: a live private key
+    package-lock.json flag: regenerated by its package manager, never hand-edited
+
+    .env.example      ok: a placeholders-only template, committed on purpose
+    .env.sample       ok: the same shape, .sample spelling
+    .env.template     ok: the same shape, .template spelling
+    main.py           ok: ordinary source
+
+A basename whose FINAL suffix is ``.example``, ``.sample``, or ``.template``
+names a committed template, so the filename guard steps aside for it. The
+suffix has to come last: ``.env.example.bak`` is a copy of a live secrets
+file, not a template, and stays denied.
+
+The guard over a write's contents stays in force: the ``pii_prevention_blocker``
+hook scans what a write carries, so a template holding a real secret or a real
+email address is denied on its contents. The two hooks are layered, and this
+one rules on the filename alone.
+"""
+
+from __future__ import annotations
+
 import fnmatch
 import json
 import os
 import sys
-from pathlib import Path
-
-_hooks_dir = str(Path(__file__).resolve().parent.parent)
-if _hooks_dir not in sys.path:
-    sys.path.insert(0, _hooks_dir)
-
-from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
-
-SENSITIVE_PATTERNS = [
-    ".env",
-    ".env.*",
-    "*.env",
-    "*.pem",
-    "*.key",
-    "*.p12",
-    "*.pfx",
-    "credentials.json",
-    "secrets.json",
-    "id_rsa",
-    "id_ed25519",
-    "package-lock.json",
-    "yarn.lock",
-    "Pipfile.lock",
-    "poetry.lock",
-    "pnpm-lock.yaml",
-    "composer.lock",
-]
-
-WRITE_EDIT_TOOLS = {"Write", "Edit"}
+
+import _path_setup  # noqa: F401
+
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.sensitive_file_protector_constants import (
+    ALL_SENSITIVE_PATTERNS,
+    ALL_TEMPLATE_SUFFIXES,
+    ALL_WRITE_EDIT_TOOLS,
+    DENY_DECISION,
+    DENY_REASON_TEMPLATE,
+    HOOK_EVENT_NAME,
+    HOOK_SCRIPT_NAME,
+)
+
+
+def is_template_filename(filename: str) -> bool:
+    """Report whether a basename names a placeholders-only committed template.
+
+    ::
+
+        .env.example     -> True
+        .ENV.Template    -> True
+        .env.example.bak -> False
+        .env.local       -> False
+
+    Args:
+        filename: The basename of the file a Write or Edit targets.
+
+    Returns:
+        True when the basename's final suffix is a template suffix.
+    """
+    return filename.lower().endswith(ALL_TEMPLATE_SUFFIXES)
 
 
 def is_sensitive_file(file_path: str) -> str | None:
+    """Return the sensitive pattern a path's basename matches, or None.
+
+    Args:
+        file_path: The path the Write or Edit targets.
+
+    Returns:
+        The matched pattern, or None when the basename names a template or
+        matches no pattern.
+    """
     filename = os.path.basename(file_path)
-    for each_pattern in SENSITIVE_PATTERNS:
-        if fnmatch.fnmatch(filename, each_pattern):
+    if is_template_filename(filename):
+        return None
+    for each_pattern in ALL_SENSITIVE_PATTERNS:
+        if fnmatch.fnmatch(filename.lower(), each_pattern.lower()):
             return each_pattern
     return None
 
 
+def build_deny_response(deny_reason: str) -> dict[str, dict[str, str]]:
+    """Wrap a deny reason in the PreToolUse decision payload Claude Code reads.
+
+    Args:
+        deny_reason: The operator-facing sentence explaining the denial.
+
+    Returns:
+        The hook decision dictionary carrying the deny permission decision.
+    """
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": HOOK_EVENT_NAME,
+            "permissionDecision": DENY_DECISION,
+            "permissionDecisionReason": deny_reason,
+        }
+    }
+
+
+def deny_write(file_path: str, matched_pattern: str) -> None:
+    """Record the block in the hook-blocks log and emit the deny decision.
+
+    Args:
+        file_path: The path the Write or Edit targets.
+        matched_pattern: The sensitive pattern the basename matched.
+    """
+    deny_reason = DENY_REASON_TEMPLATE.format(
+        filename=os.path.basename(file_path),
+        matched_pattern=matched_pattern,
+    )
+    log_hook_block(
+        calling_hook_name=HOOK_SCRIPT_NAME,
+        hook_event=HOOK_EVENT_NAME,
+        block_reason=deny_reason,
+        offending_input_preview=file_path,
+    )
+    sys.stdout.write(json.dumps(build_deny_response(deny_reason)))
+
+
 def main() -> None:
+    """Deny the write when the stdin payload targets a sensitive filename."""
     try:
         hook_input = json.load(sys.stdin)
     except json.JSONDecodeError:
@@ -51,7 +132,7 @@ def main() -> None:
     tool_name = hook_input.get("tool_name", "")
     tool_input = hook_input.get("tool_input", {})
 
-    if tool_name not in WRITE_EDIT_TOOLS:
+    if tool_name not in ALL_WRITE_EDIT_TOOLS:
         sys.exit(0)
 
     file_path = tool_input.get("file_path", "")
@@ -59,23 +140,8 @@ def main() -> None:
         sys.exit(0)
 
     matched_pattern = is_sensitive_file(file_path)
-
     if matched_pattern is not None:
-        deny_reason = f"BLOCKED: Sensitive file '{os.path.basename(file_path)}' (pattern: '{matched_pattern}'). Edit manually outside Claude Code."
-        deny_response = {
-            "hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "permissionDecision": "deny",
-                "permissionDecisionReason": deny_reason,
-            }
-        }
-        log_hook_block(
-            calling_hook_name="sensitive_file_protector.py",
-            hook_event="PreToolUse",
-            block_reason=deny_reason,
-            offending_input_preview=file_path,
-        )
-        print(json.dumps(deny_response))
+        deny_write(file_path, matched_pattern)
 
     sys.exit(0)
 

package/hooks/blocking/tdd_enforcer.py

@@ -22,7 +22,10 @@ if _hooks_root_path_string not in sys.path:
 if _blocking_directory_path_string not in sys.path:
     sys.path.insert(0, _blocking_directory_path_string)
 
-from code_rules_shared import is_ephemeral_script_path  # noqa: E402
+from code_rules_shared import (  # noqa: E402
+    is_ephemeral_script_path,
+    is_under_session_scratchpad,
+)
 
 from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.messages import USER_FACING_TDD_NOTICE  # noqa: E402
@@ -592,7 +595,11 @@ def main() -> None:
     if not file_path:
         sys.exit(0)
 
-    if _is_inside_dotclaude_segment(file_path) or is_ephemeral_script_path(file_path):
+    if (
+        is_under_session_scratchpad(file_path, input_data)
+        or _is_inside_dotclaude_segment(file_path)
+        or is_ephemeral_script_path(file_path)
+    ):
         sys.exit(0)
 
     path = Path(file_path)

package/hooks/blocking/test_code_rules_enforcer_scratchpad.py

@@ -0,0 +1,105 @@
+"""Tests for the session-scratchpad exemption wired into code_rules_enforcer.main."""
+
+import importlib.util
+import io
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+ENFORCER_PATH = Path(__file__).parent / "code_rules_enforcer.py"
+FIXED_USER_ID = 6070
+WORKING_DIRECTORY = "/home/user/project"
+SESSION_ID = "enforcer-session-654"
+VIOLATING_CONTENT = "def compute():\n    data = 42\n    return data\n"
+
+
+def _load_enforcer() -> ModuleType:
+    module_spec = importlib.util.spec_from_file_location(
+        "code_rules_enforcer_scratchpad_under_test", ENFORCER_PATH
+    )
+    assert module_spec is not None and module_spec.loader is not None
+    loaded_module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(loaded_module)
+    return loaded_module
+
+
+_ENFORCER = _load_enforcer()
+
+
+def _install_scratchpad_signals(monkeypatch: pytest.MonkeyPatch, temporary_root: Path) -> Path:
+    monkeypatch.setattr(os, "getuid", lambda: FIXED_USER_ID, raising=False)
+    monkeypatch.setattr(tempfile, "gettempdir", lambda: str(temporary_root))
+    mangled_working_directory = WORKING_DIRECTORY.replace("/", "-")
+    scratchpad_directory = (
+        temporary_root
+        / f"claude-{FIXED_USER_ID}"
+        / mangled_working_directory
+        / SESSION_ID
+        / "scratchpad"
+    )
+    scratchpad_directory.mkdir(parents=True)
+    return scratchpad_directory
+
+
+def _write_payload(target: Path) -> dict[str, object]:
+    return {
+        "tool_name": "Write",
+        "cwd": WORKING_DIRECTORY,
+        "session_id": SESSION_ID,
+        "tool_input": {"file_path": str(target), "content": VIOLATING_CONTENT},
+    }
+
+
+def _run_main(
+    monkeypatch: pytest.MonkeyPatch, payload: dict[str, object]
+) -> tuple[int | None, str]:
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(payload)))
+    captured_stdout = io.StringIO()
+    monkeypatch.setattr(sys, "stdout", captured_stdout)
+    exit_code: int | None = None
+    try:
+        _ENFORCER.main([])
+    except SystemExit as raised_exit:
+        raw_code = raised_exit.code
+        exit_code = raw_code if isinstance(raw_code, int) else None
+    return exit_code, captured_stdout.getvalue()
+
+
+def _decision_from(stdout_text: str) -> str | None:
+    if not stdout_text.strip():
+        return None
+    parsed = json.loads(stdout_text)
+    return parsed.get("hookSpecificOutput", {}).get("permissionDecision")
+
+
+def test_scratchpad_write_is_exempt_from_code_rules(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    scratchpad_directory = _install_scratchpad_signals(monkeypatch, tmp_path)
+    monkeypatch.setenv("CLAUDE_CODE_RULES_DISABLE_EPHEMERAL_EXEMPT", "1")
+    throwaway_script = scratchpad_directory / "one_off_probe.py"
+
+    exit_code, stdout_text = _run_main(monkeypatch, _write_payload(throwaway_script))
+
+    assert exit_code == 0
+    assert _decision_from(stdout_text) != "deny"
+
+
+def test_identical_non_scratchpad_write_is_still_blocked(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install_scratchpad_signals(monkeypatch, tmp_path)
+    monkeypatch.setenv("CLAUDE_CODE_RULES_DISABLE_EPHEMERAL_EXEMPT", "1")
+    outside_directory = tmp_path / "project" / "orders"
+    outside_directory.mkdir(parents=True)
+    production_module = outside_directory / "one_off_probe.py"
+
+    exit_code, stdout_text = _run_main(monkeypatch, _write_payload(production_module))
+
+    assert exit_code == 0
+    assert _decision_from(stdout_text) == "deny"