claude-dev-env 2.1.0 → 2.2.1

package/CLAUDE.md

@@ -43,7 +43,7 @@ Run every multi-step code task in two phases:
 1. **Coders** — one coder agent per scoped assignment writes the code. A coder that hits a decision it can't reasonably solve consults the advisor (see beginning of this file).
 2. **Verification** — when the coders finish, the main session spawns the `code-verifier` agent in a fresh context, but you must first verify that their work is based on upstream's origin main (aka: the commit live on github). It derives and runs the checks itself rather than trusting coder reports: the task's named gates, tests against baselines recorded before the coders ran, and a two-way diff-vs-assignment reading (every task item maps to a hunk, every hunk maps to a task item, nothing missing). A finding must cite a failing command or a named task item. Before it emits the verdict, it puts the draft through one strongest-tier validation subagent — selected per the advisor protocol's host detection and tier ladder — that tries to refute it, and it re-checks and corrects any part the validator overturns. Source: the fresh-context review step in Claude Code best practices (https://code.claude.com/docs/en/best-practices) — the agent doing the work isn't the one grading it.
 
-Repair agents run only on reported findings; the verifier re-checks after each repair. Work lands (commit, push, draft PR) only on a clean verdict — enforced by the `verified_commit_gate` hook, which blocks `git commit`/`git push` unless a hook-minted verdict covers the current branch diff. One exemption is mechanical, not discretionary: a diff whose every changed file is non-code or has an unchanged Python AST once docstrings are stripped (docs, docstrings, comments). One escape hatch is manual and narrow: appending `# verify-skip` as a trailing shell comment (outside every quoted region) to the blocked commit or push command bypasses the gate for that one command — allowed only when the branch surface is the same code a code-verifier already passed clean and the gate is blocking on a verdict that doesn't cover it (an unminted verdict, staging churn, a reverted concurrent write); any real code change since the clean verdict runs a fresh verification instead. Full rule: `~/.claude/rules/verified-commit-gate-skip.md`.
+Repair agents run only on reported findings; the verifier re-checks after each repair. Work lands (commit, push, draft PR) only on a clean verdict — enforced by the `verified_commit_gate` hook, which blocks `git commit`/`git push` unless a hook-minted verdict covers the current branch diff. One exemption is mechanical, not discretionary: a diff whose every changed file is non-code (docs, images), a pytest test file by name (`test_*.py`, `*_test.py`, or `conftest.py`), or a Python file whose docstring-stripped AST is unchanged (docstring, comment, or formatting-only edits). One escape hatch is manual and narrow: appending `# verify-skip` as a trailing shell comment (outside every quoted region) to the blocked commit or push command bypasses the gate for that one command — allowed only when the branch surface is the same code a code-verifier already passed clean and the gate is blocking on a verdict that doesn't cover it (an unminted verdict, staging churn, a reverted concurrent write); any real code change since the clean verdict runs a fresh verification instead. Full rule: `~/.claude/rules/verified-commit-gate-skip.md`.
 
 ## Sub-agent Output Validation
 

package/_shared/pr-loop/scripts/pyproject.toml

@@ -0,0 +1,22 @@
+# mypy configuration for pr-loop production scripts.
+#
+# Scoped separately from hooks/pyproject.toml so pr-loop and hooks stay
+# independent. check.ps1 invokes this via the mypy-pr-loop tool label.
+
+[tool.mypy]
+mypy_path = "."
+python_version = "3.13"
+ignore_missing_imports = true
+warn_unused_ignores = false
+warn_redundant_casts = true
+no_implicit_optional = true
+strict_equality = true
+exclude = [
+    "tests/",
+    "test_",
+    "code_rules_gate_parts/tests/",
+]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false

package/hooks/blocking/code_rules_shared.py

@@ -412,8 +412,10 @@ def is_ephemeral_path(file_path: str, hook_payload: dict | None = None) -> bool:
     harness session scratchpad. The session scratchpad match reads the session id
     from the payload when one is supplied, and from the harness environment
     variable otherwise, so a caller that holds no payload still gets the match.
-    One call answers path exemption for both families, so a gate that skips
-    throwaway paths need not repeat the two checks itself.
+    The run_all_validators PreToolUse gate calls this predicate to skip a scratch
+    target before it validates. The code-rules and TDD gates call the two path
+    predicates ``is_ephemeral_script_path`` and ``is_under_session_scratchpad``
+    directly.
 
     Args:
         file_path: The candidate path to classify.

package/hooks/blocking/pii_payload_scan.py

@@ -18,6 +18,7 @@ try:
     for each_bootstrap_directory in (_blocking_directory, _hooks_directory):
         if each_bootstrap_directory not in sys.path:
             sys.path.insert(0, each_bootstrap_directory)
+    from code_rules_shared import is_ephemeral_path
     from pii_prevention_blocker_parts.repository_exemption import (
         repository_allowlisted_values,
     )
@@ -47,6 +48,41 @@ except ImportError as import_error:
     ) from import_error
 
 
+def _target_is_ephemeral_outside_repository(
+    file_path: str, hook_payload: dict | None
+) -> bool:
+    """Report whether a write target is a throwaway draft outside every repo.
+
+    ::
+
+        ephemeral path, no repo tree  ->  True   (write scan skipped)
+        ephemeral path inside a repo  ->  False  (write scan kept)
+        ordinary path                 ->  False  (write scan kept)
+
+    A draft under the harness scratchpad or an ephemeral scratch root turns
+    durable only through a surface that keeps its own scan, so scanning it at
+    write time is a false positive. A draft that resolves inside a git tree
+    still carries that repository's own allowlist, so the scan stays.
+
+    Args:
+        file_path: The write target path to classify.
+        hook_payload: The PreToolUse payload carrying the session id, or None to
+            read the session id from the environment alone.
+
+    Returns:
+        True only when the path is ephemeral and no enclosing git repository
+        resolves.
+    """
+    if not file_path:
+        return False
+    if not is_ephemeral_path(file_path, hook_payload):
+        return False
+    resolution_directory = _existing_ancestor_directory(file_path)
+    if resolution_directory is None:
+        return True
+    return resolve_repository_root(resolution_directory) is None
+
+
 def build_deny_reason(all_findings: list[PiiFinding], gate_surface: str) -> str:
     """Return the deny message listing each finding for *gate_surface*.
 
@@ -165,29 +201,16 @@ def _write_path_allowlisted_values(file_path: str) -> frozenset[str]:
     return repository_allowlisted_values(repository_root)
 
 
-def evaluate_write_edit_payload(
-    tool_name: str,
-    all_tool_input: dict[str, object],
-    all_allowlisted_values: frozenset[str] = frozenset(),
+def _write_deny_reason_for_texts(
+    all_texts: list[str],
+    file_path: str,
+    all_allowlisted_values: frozenset[str],
 ) -> str | None:
-    """Return a deny reason when Write/Edit/MultiEdit content carries PII.
-
-    A value in the target repository's PII allowlist is dropped from the
-    findings, so a write under that repository's tree may carry it. Repository
-    resolution for that allowlist runs only after a raw PII hit.
-
-    Args:
-        tool_name: The intercepted tool name.
-        all_tool_input: The tool input mapping.
-        all_allowlisted_values: Extra exact values allowed past the scan,
-            unioned with the target repository's own allowlist.
+    """Return the deny reason for the first text carrying non-allowlisted PII.
 
-    Returns:
-        Deny reason text, or None when the write is clean or out of scope.
+    Repository allowlist resolution runs once, only after a raw PII hit, so a
+    clean payload triggers no git call.
     """
-    if tool_name not in ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES:
-        return None
-    file_path, all_texts = _collect_write_edit_texts(tool_name, all_tool_input)
     resolved_allowlisted_values: frozenset[str] | None = None
     for each_text in all_texts:
         all_raw_findings = scan_text_for_pii(each_text)
@@ -208,6 +231,41 @@ def evaluate_write_edit_payload(
     return None
 
 
+def evaluate_write_edit_payload(
+    tool_name: str,
+    all_tool_input: dict[str, object],
+    all_allowlisted_values: frozenset[str] = frozenset(),
+    hook_payload: dict | None = None,
+) -> str | None:
+    """Return a deny reason when Write/Edit/MultiEdit content carries PII.
+
+    A value in the target repository's PII allowlist is dropped from the
+    findings, so a write under that repository's tree may carry it. A draft
+    under an ephemeral scratch root outside every repository is skipped, since
+    it turns durable only through surfaces that keep their own scans.
+
+    Args:
+        tool_name: The intercepted tool name.
+        all_tool_input: The tool input mapping.
+        all_allowlisted_values: Extra exact values allowed past the scan,
+            unioned with the target repository's own allowlist.
+        hook_payload: The PreToolUse payload carrying the session id, threaded
+            to the ephemeral-path predicate; None reads the session id from the
+            environment alone.
+
+    Returns:
+        Deny reason text, or None when the write is clean or out of scope.
+    """
+    if tool_name not in ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES:
+        return None
+    file_path, all_texts = _collect_write_edit_texts(tool_name, all_tool_input)
+    if not all_texts:
+        return None
+    if _target_is_ephemeral_outside_repository(file_path, hook_payload):
+        return None
+    return _write_deny_reason_for_texts(all_texts, file_path, all_allowlisted_values)
+
+
 def evaluate_post_body_texts(
     all_body_texts: list[str],
     all_allowlisted_values: frozenset[str] = frozenset(),

package/hooks/blocking/pii_prevention_blocker.py

@@ -329,7 +329,9 @@ def evaluate(payload_by_key: dict[str, object]) -> str | None:
     raw_tool_input = payload_by_key.get("tool_input", {})
     all_tool_input = raw_tool_input if isinstance(raw_tool_input, dict) else {}
     if tool_name in ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES:
-        return evaluate_write_edit_payload(tool_name, all_tool_input)
+        return evaluate_write_edit_payload(
+            tool_name, all_tool_input, hook_payload=payload_by_key
+        )
     if tool_name in ALL_SHELL_TOOL_NAMES:
         return _evaluate_shell_tool(all_tool_input, payload_by_key)
     if tool_name.startswith(MCP_GITHUB_TOOL_PREFIX):

package/hooks/blocking/test_pii_write_surface_ephemeral.py

@@ -0,0 +1,221 @@
+"""Behavior tests for the ephemeral-path skip on the Write/Edit PII surface.
+
+Sub-defect (ii): the Write/Edit surface scanned files under an ephemeral scratch
+root that sit outside every git repository. Such a draft only becomes durable
+through ``gh --body-file`` or a staged commit, and each of those surfaces keeps
+its own PII scan, so scanning the draft at write time is a pure false positive.
+
+The write surface consults the shared ``is_ephemeral_path`` predicate directly.
+These tests drive that real predicate on genuine ephemeral shapes: a harness
+session scratchpad under the user temp directory, and a ``CLAUDE_JOB_DIR``
+scratch tree. A write inside a git repository keeps full scanning, and the
+durable-post and staged-commit surfaces stay gated even from ephemeral sources.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+import uuid
+from collections.abc import Iterator
+from pathlib import Path
+
+import pytest
+
+_HOOK_DIR = Path(__file__).parent
+_HOOKS_DIR = _HOOK_DIR.parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+if str(_HOOKS_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_DIR))
+
+import tempfile  # noqa: E402
+
+from pii_payload_scan import evaluate_write_edit_payload  # noqa: E402
+from pii_prevention_blocker import evaluate, evaluate_bash_command  # noqa: E402
+
+from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+    CLAUDE_JOB_DIR_ENVIRONMENT_VARIABLE_NAME,
+    CLAUDE_JOB_DIR_SCRATCH_SUBDIRECTORY,
+    EPHEMERAL_EXEMPT_DISABLE_ENVIRONMENT_VARIABLE_NAME,
+)
+from hooks_constants.harness_scratchpad_constants import (  # noqa: E402
+    HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME,
+    HARNESS_SCRATCHPAD_USER_DIRECTORY_NAME,
+    HOOK_PAYLOAD_SESSION_ID_KEY,
+)
+
+
+def _real_pii_email() -> str:
+    return "owner.fixture" + "@" + "acme-corp" + ".example" + ".io"
+
+
+def _bot_trailer_address() -> str:
+    return "noreply" + "@" + "anthropic" + ".com"
+
+
+def _write_deny_reason(
+    target_path: Path,
+    sensitive_text: str,
+    hook_payload: dict[str, object] | None = None,
+) -> str | None:
+    content = "owner contact " + sensitive_text + "\n"
+    return evaluate_write_edit_payload(
+        "Write",
+        {"file_path": str(target_path), "content": content},
+        hook_payload=hook_payload,
+    )
+
+
+def _enable_job_dir_ephemeral_root(
+    monkeypatch: pytest.MonkeyPatch, job_directory: Path
+) -> Path:
+    monkeypatch.delenv(EPHEMERAL_EXEMPT_DISABLE_ENVIRONMENT_VARIABLE_NAME, raising=False)
+    monkeypatch.setenv(CLAUDE_JOB_DIR_ENVIRONMENT_VARIABLE_NAME, str(job_directory))
+    ephemeral_root = job_directory / CLAUDE_JOB_DIR_SCRATCH_SUBDIRECTORY
+    ephemeral_root.mkdir(parents=True, exist_ok=True)
+    return ephemeral_root
+
+
+@pytest.fixture
+def harness_scratchpad() -> Iterator[tuple[Path, str]]:
+    session_id = "session-" + uuid.uuid4().hex
+    mangled_working_directory = "cwd-" + uuid.uuid4().hex
+    temp_root = Path(tempfile.gettempdir())
+    user_root = temp_root / HARNESS_SCRATCHPAD_USER_DIRECTORY_NAME
+    scratchpad_root = (
+        user_root
+        / mangled_working_directory
+        / session_id
+        / HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME
+    )
+    scratchpad_root.mkdir(parents=True, exist_ok=True)
+    try:
+        yield scratchpad_root, session_id
+    finally:
+        try:
+            shutil.rmtree(user_root / mangled_working_directory)
+        except OSError:
+            pass
+
+
+def _init_repo_with_github_origin(repository_root: Path, origin_slug: str) -> None:
+    repository_root.mkdir(parents=True, exist_ok=True)
+    subprocess.run(["git", "init", "-q"], cwd=repository_root, check=True)
+    origin_url = "https://github.com/" + origin_slug + ".git"
+    subprocess.run(
+        ["git", "remote", "add", "origin", origin_url],
+        cwd=repository_root,
+        check=True,
+    )
+
+
+def _init_repo_with_staged_email(repository_root: Path, staged_email: str) -> None:
+    repository_root.mkdir(parents=True, exist_ok=True)
+    subprocess.run(["git", "init", "-q"], cwd=repository_root, check=True)
+    subprocess.run(
+        ["git", "config", "user.email", "dev@example.com"],
+        cwd=repository_root,
+        check=True,
+    )
+    subprocess.run(
+        ["git", "config", "user.name", "Fixture Dev"],
+        cwd=repository_root,
+        check=True,
+    )
+    tracked_file = repository_root / "notes.md"
+    tracked_file.write_text("owner email " + staged_email + "\n", encoding="utf-8")
+    subprocess.run(["git", "add", "notes.md"], cwd=repository_root, check=True)
+
+
+def test_windows_shaped_scratchpad_write_is_skipped(
+    harness_scratchpad: tuple[Path, str],
+) -> None:
+    scratchpad_root, session_id = harness_scratchpad
+    scratch_target = scratchpad_root / "blocker-matrix.txt"
+    payload = {HOOK_PAYLOAD_SESSION_ID_KEY: session_id}
+    assert _write_deny_reason(scratch_target, _bot_trailer_address(), payload) is None
+
+
+def test_write_with_no_scannable_texts_returns_none(tmp_path: Path) -> None:
+    target_path = tmp_path / "empty-write.md"
+    assert (
+        evaluate_write_edit_payload(
+            "Write",
+            {"file_path": str(target_path), "content": ""},
+        )
+        is None
+    )
+
+
+def test_entry_point_threads_payload_session_id_to_scratchpad_skip(
+    monkeypatch: pytest.MonkeyPatch,
+    harness_scratchpad: tuple[Path, str],
+) -> None:
+    scratchpad_root, session_id = harness_scratchpad
+    monkeypatch.delenv("CLAUDE_CODE_SESSION_ID", raising=False)
+    scratch_target = scratchpad_root / "blocker-matrix.txt"
+    content = "owner contact " + _real_pii_email() + "\n"
+    payload = {
+        "tool_name": "Write",
+        "tool_input": {"file_path": str(scratch_target), "content": content},
+        HOOK_PAYLOAD_SESSION_ID_KEY: session_id,
+    }
+    assert evaluate(payload) is None
+
+
+def test_job_dir_ephemeral_write_outside_repo_is_skipped(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    ephemeral_root = _enable_job_dir_ephemeral_root(monkeypatch, tmp_path)
+    scratch_target = ephemeral_root / "drafts" / "draft.md"
+    scratch_target.parent.mkdir(parents=True)
+    assert _write_deny_reason(scratch_target, _real_pii_email()) is None
+
+
+def test_write_inside_ordinary_repository_is_still_denied(
+    tmp_path: Path,
+) -> None:
+    repository_root = tmp_path / "repo"
+    _init_repo_with_github_origin(repository_root, "SomeOwner/some-repo")
+    deny_reason = _write_deny_reason(repository_root / "notes.md", _real_pii_email())
+    assert deny_reason is not None
+    assert "email" in deny_reason
+
+
+def test_ephemeral_path_inside_a_repository_is_still_denied(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    ephemeral_root = _enable_job_dir_ephemeral_root(monkeypatch, tmp_path)
+    repository_root = ephemeral_root / "repo"
+    _init_repo_with_github_origin(repository_root, "SomeOwner/some-repo")
+    deny_reason = _write_deny_reason(repository_root / "notes.md", _real_pii_email())
+    assert deny_reason is not None
+    assert "email" in deny_reason
+
+
+def test_gh_body_file_from_ephemeral_path_is_still_scanned(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    ephemeral_root = _enable_job_dir_ephemeral_root(monkeypatch, tmp_path)
+    body_path = ephemeral_root / "pr_body.md"
+    body_path.write_text("contact " + _real_pii_email() + "\n", encoding="utf-8")
+    command = 'gh pr comment 12 --body-file "' + str(body_path) + '"'
+    deny_reason = evaluate_bash_command(command, working_directory=None)
+    assert deny_reason is not None
+    assert "email" in deny_reason
+
+
+def test_staged_commit_from_ephemeral_tree_is_still_scanned(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    ephemeral_root = _enable_job_dir_ephemeral_root(monkeypatch, tmp_path)
+    repository_root = ephemeral_root / "repo"
+    _init_repo_with_staged_email(repository_root, _real_pii_email())
+    deny_reason = evaluate_bash_command(
+        "git commit -m test", working_directory=str(repository_root)
+    )
+    assert deny_reason is not None
+    assert "email" in deny_reason
+    assert "staged commit" in deny_reason

package/hooks/validators/ruff_integration.py

@@ -38,8 +38,9 @@ def run_ruff_check(files: list[Path]) -> RuffResult:
     if not py_files:
         return RuffResult(passed=True, output="No Python files", fixed_count=0)
 
+    concise_output_arguments = ["--output-format", "concise"]
     result = subprocess.run(
-        ["ruff", "check"] + py_files,
+        ["ruff", "check", *concise_output_arguments] + py_files,
         check=False,
         capture_output=True,
         text=True,