claude-dev-env 8.84.0 → 8.84.1

package/hooks/blocking/pull_request_proof.py

@@ -21,10 +21,20 @@ from hooks_constants.pull_request_proof_constants import (
     ALL_VISIBLE_FILE_SUFFIXES,
     CHANGED_FILES_SEPARATOR,
     COMMAND_MARKER,
+    ALL_BASE_FLAGS,
     ALL_DEFAULT_BRANCH_REFERENCES,
     ALL_HEAD_FLAGS,
+    ALL_REPOSITORY_FLAGS,
+    BASE_FLAG_ASSIGNMENT_PREFIX,
+    COMPARE_ENDPOINT_TEMPLATE,
+    COMPARE_FILE_LIST_LIMIT,
+    COMPARE_FILE_NAMES_QUERY,
+    DEFAULT_BRANCH_QUERY,
+    GH_TIMEOUT_SECONDS,
     HEAD_FLAG_ASSIGNMENT_PREFIX,
     REMOTE_BRANCH_PREFIX,
+    REPOSITORY_ENDPOINT_TEMPLATE,
+    REPOSITORY_FLAG_ASSIGNMENT_PREFIX,
     UNREADABLE_CHANGES_REASON,
     EVAL_HEADING_PATTERN,
     EXISTING_WORK_HEADING_PATTERN,
@@ -174,28 +184,55 @@ def _shell_create_calls(command: str, working_directory: str) -> list[CreateCall
     ]
 
 
-def _head_flag_value(all_create_arguments: list[str]) -> str | None:
+def _flag_value(all_create_arguments: list[str], all_flags: frozenset[str], assignment_prefix: str) -> str | None:
     for each_position, each_argument in enumerate(all_create_arguments):
-        if each_argument in ALL_HEAD_FLAGS and each_position + 1 < len(all_create_arguments):
-            return all_create_arguments[each_position + 1]
-        if each_argument.startswith(HEAD_FLAG_ASSIGNMENT_PREFIX):
-            return each_argument[len(HEAD_FLAG_ASSIGNMENT_PREFIX) :]
+        if each_argument in all_flags and each_position + 1 < len(all_create_arguments):
+            return unquoted_token(all_create_arguments[each_position + 1])
+        if each_argument.startswith(assignment_prefix):
+            return unquoted_token(each_argument[len(assignment_prefix) :])
     return None
 
 
-def _named_head_branch(all_payload_fields: Mapping[str, object]) -> str | None:
-    create_fields = create_tool_fields(all_payload_fields)
-    head_branch = None if create_fields is None else create_fields.get("head")
-    if isinstance(head_branch, str):
-        return head_branch
+def _shell_flag_value(
+    all_payload_fields: Mapping[str, object], all_flags: frozenset[str], assignment_prefix: str
+) -> str | None:
     command = _shell_command(all_payload_fields)
     if command is None:
         return None
-    all_head_flag_values = [
-        _head_flag_value(all_create_arguments)
+    all_flag_values = [
+        _flag_value(all_create_arguments, all_flags, assignment_prefix)
         for all_create_arguments in _all_create_argument_lists(command)
     ]
-    return next((each_value for each_value in all_head_flag_values if each_value), None)
+    return next((each_value for each_value in all_flag_values if each_value), None)
+
+
+def _named_create_field(
+    all_payload_fields: Mapping[str, object], field_name: str, all_flags: frozenset[str], assignment_prefix: str
+) -> str | None:
+    create_fields = create_tool_fields(all_payload_fields)
+    field_value = None if create_fields is None else create_fields.get(field_name)
+    if isinstance(field_value, str) and field_value:
+        return field_value
+    return _shell_flag_value(all_payload_fields, all_flags, assignment_prefix)
+
+
+def _named_head_branch(all_payload_fields: Mapping[str, object]) -> str | None:
+    return _named_create_field(all_payload_fields, "head", ALL_HEAD_FLAGS, HEAD_FLAG_ASSIGNMENT_PREFIX)
+
+
+def _named_base_branch(all_payload_fields: Mapping[str, object]) -> str | None:
+    return _named_create_field(all_payload_fields, "base", ALL_BASE_FLAGS, BASE_FLAG_ASSIGNMENT_PREFIX)
+
+
+def _named_repository(all_payload_fields: Mapping[str, object]) -> str | None:
+    create_fields = create_tool_fields(all_payload_fields)
+    if create_fields is not None:
+        owner = create_fields.get("owner")
+        repository_name = create_fields.get("repo")
+        if isinstance(owner, str) and owner and isinstance(repository_name, str) and repository_name:
+            return f"{owner}/{repository_name}"
+        return None
+    return _shell_flag_value(all_payload_fields, ALL_REPOSITORY_FLAGS, REPOSITORY_FLAG_ASSIGNMENT_PREFIX)
 
 
 def _create_calls(all_payload_fields: Mapping[str, object]) -> list[CreateCall]:
@@ -485,9 +522,83 @@ def visible_changed_files(working_directory: str, head_branch: object) -> list[s
     all_changed_paths = _git_lines(working_directory, "diff", "--name-only", merge_base, head_reference)
     if all_changed_paths is None:
         return None
+    return _visible_paths(all_changed_paths)
+
+
+def _visible_paths(all_changed_paths: list[str]) -> list[str]:
     return [each_path for each_path in all_changed_paths if each_path.lower().endswith(ALL_VISIBLE_FILE_SUFFIXES)]
 
 
+def _gh_api_lines(endpoint: str, query: str) -> list[str] | None:
+    try:
+        completed = subprocess.run(
+            ["gh", "api", endpoint, "--jq", query],
+            capture_output=True,
+            text=True,
+            timeout=GH_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return completed.stdout.splitlines() if completed.returncode == 0 else None
+
+
+def _compare_base_branch(repository: str, base_branch: str | None) -> str | None:
+    if base_branch:
+        return base_branch
+    all_default_branch_lines = _gh_api_lines(
+        REPOSITORY_ENDPOINT_TEMPLATE.format(repository=repository), DEFAULT_BRANCH_QUERY
+    )
+    if not all_default_branch_lines:
+        return None
+    return all_default_branch_lines[0]
+
+
+def _visible_compare_paths(repository: str, base_branch: str, head_branch: str) -> list[str] | None:
+    all_changed_paths = _gh_api_lines(
+        COMPARE_ENDPOINT_TEMPLATE.format(
+            repository=repository, base_branch=base_branch, head_branch=head_branch
+        ),
+        COMPARE_FILE_NAMES_QUERY,
+    )
+    if all_changed_paths is None:
+        return None
+    all_visible_paths = _visible_paths(all_changed_paths)
+    if all_visible_paths or len(all_changed_paths) < COMPARE_FILE_LIST_LIMIT:
+        return all_visible_paths
+    return None
+
+
+def remote_visible_changed_files(
+    repository: str | None, base_branch: str | None, head_branch: str | None
+) -> list[str] | None:
+    """Return the changed files people see, read from the GitHub compare API, or None when it cannot tell.
+
+    ::
+
+        compare lists tool.py                          -> []
+        compare lists web/page.html                    -> ["web/page.html"]
+        compare returns 300 paths and none are visible -> None
+        repository or head missing                     -> None
+
+    The base is the named base branch, else the repository's default branch.
+    A page of 300 paths is the compare API's file cap. A visible file on that
+    page is returned. A full page with none is None, because a later file can
+    still be one people see.
+
+    Args:
+        repository: The owner/name the create call names, or None.
+        base_branch: The base branch the create call names, or None.
+        head_branch: The head branch the create call names, or None.
+    """
+    if not repository or not head_branch:
+        return None
+    resolved_base_branch = _compare_base_branch(repository, base_branch)
+    if resolved_base_branch is None:
+        return None
+    return _visible_compare_paths(repository, resolved_base_branch, head_branch)
+
+
 def missing_look_reason(all_payload_fields: Mapping[str, object]) -> str | None:
     """Return a deny reason when a pull request changing visible files shows no picture, else None.
 
@@ -496,7 +607,9 @@ def missing_look_reason(all_payload_fields: Mapping[str, object]) -> str | None:
         branch changes page.html, proof has ![after](https://x/after.png) -> None
         branch changes page.html, proof quotes only command output        -> MISSING_LOOK_REASON
         branch changes only .py files                                     -> None
-        git cannot read the branch, proof shows no picture                -> UNREADABLE_CHANGES_REASON
+        git cannot read the branch, compare API lists only .py files      -> None
+        git cannot read the branch, compare API returns 300 .py files     -> UNREADABLE_CHANGES_REASON
+        neither git nor the compare API can read it, no picture           -> UNREADABLE_CHANGES_REASON
 
     Args:
         all_payload_fields: The parsed PreToolUse input.
@@ -505,9 +618,12 @@ def missing_look_reason(all_payload_fields: Mapping[str, object]) -> str | None:
     if not all_bodies:
         return None
     working_directory = all_payload_fields.get("cwd")
-    all_visible_files = visible_changed_files(
-        str(working_directory or ""), _named_head_branch(all_payload_fields)
-    )
+    head_branch = _named_head_branch(all_payload_fields)
+    all_visible_files = visible_changed_files(str(working_directory or ""), head_branch)
+    if all_visible_files is None:
+        all_visible_files = remote_visible_changed_files(
+            _named_repository(all_payload_fields), _named_base_branch(all_payload_fields), head_branch
+        )
     if all_visible_files == []:
         return None
     for each_body in all_bodies:

package/hooks/blocking/test_pull_request_proof.py

@@ -4,12 +4,15 @@ import subprocess
 import sys
 from pathlib import Path
 
+import pytest
+
 HOOKS_DIRECTORY = Path(__file__).resolve().parent.parent
 if str(HOOKS_DIRECTORY) not in sys.path:
     sys.path.insert(0, str(HOOKS_DIRECTORY))
 
 from blocking import pull_request_proof as gate
 from hooks_constants.pull_request_proof_constants import (
+    COMPARE_FILE_LIST_LIMIT,
     MISSING_BODY_REASON,
     MISSING_EVAL_SECTION_REASON,
     MISSING_EXISTING_WORK_REASON,
@@ -306,6 +309,147 @@ def test_should_deny_when_git_cannot_read_the_branch_and_proof_shows_no_picture(
     assert gate.missing_look_reason(payload) == UNREADABLE_CHANGES_REASON
 
 
+def _fake_gh_api(all_responses: dict[str, list[str] | None], all_endpoints: list[str]):
+    def fake_gh_api_lines(endpoint: str, query: str) -> list[str] | None:
+        all_endpoints.append(endpoint)
+        return all_responses.get(endpoint)
+
+    return fake_gh_api_lines
+
+
+def _shell_create_elsewhere(tmp_path: Path, extra_flags: str) -> dict[str, object]:
+    body_path = tmp_path / "body.md"
+    body_path.write_text(PROVEN_BODY, encoding="utf-8")
+    return _shell(f"gh pr create --title t --body-file {body_path} {extra_flags}", tmp_path)
+
+
+def test_should_allow_a_python_only_change_the_compare_api_lists_when_git_cannot_read_it(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    all_endpoints: list[str] = []
+    compare_endpoint = "repos/o/r/compare/main...feature"
+    monkeypatch.setattr(gate, "_gh_api_lines", _fake_gh_api({compare_endpoint: ["tool.py"]}, all_endpoints))
+    payload = _shell_create_elsewhere(tmp_path, "--repo o/r --base main --head feature")
+    assert gate.missing_look_reason(payload) is None
+    assert all_endpoints == [compare_endpoint]
+
+
+def test_should_deny_a_page_change_the_compare_api_lists_without_a_picture(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    all_responses = {"repos/o/r": ["trunk"], "repos/o/r/compare/trunk...feature": ["web/page.html", "tool.py"]}
+    all_endpoints: list[str] = []
+    monkeypatch.setattr(gate, "_gh_api_lines", _fake_gh_api(all_responses, all_endpoints))
+    reason = gate.missing_look_reason(_shell_create_elsewhere(tmp_path, "-R o/r --head=feature"))
+    assert reason is not None
+    assert "web/page.html" in reason
+    assert "tool.py" not in reason
+    assert all_endpoints == ["repos/o/r", "repos/o/r/compare/trunk...feature"]
+
+
+def test_should_deny_as_unreadable_when_the_compare_api_fails(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(gate, "_gh_api_lines", _fake_gh_api({}, []))
+    payload = _shell_create_elsewhere(tmp_path, "--repo o/r --base main --head feature")
+    reason = gate.missing_look_reason(payload)
+    assert reason == UNREADABLE_CHANGES_REASON
+    assert reason is not None
+    assert "compare API" in reason
+    assert "--repo" in reason
+    assert "--head" in reason
+    assert "origin fetched" in reason
+    assert "Artifact" in reason
+    assert "before any change to this gate" in reason
+
+
+def _python_paths(count: int) -> list[str]:
+    return [f"pkg/module_{each_index}.py" for each_index in range(count)]
+
+
+def test_should_deny_as_unreadable_when_a_full_compare_page_lists_no_visible_file(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    all_endpoints: list[str] = []
+    compare_endpoint = "repos/o/r/compare/main...feature"
+    monkeypatch.setattr(
+        gate,
+        "_gh_api_lines",
+        _fake_gh_api({compare_endpoint: _python_paths(COMPARE_FILE_LIST_LIMIT)}, all_endpoints),
+    )
+    assert COMPARE_FILE_LIST_LIMIT == 300
+    payload = _shell_create_elsewhere(tmp_path, "--repo o/r --base main --head feature")
+    assert gate.remote_visible_changed_files("o/r", "main", "feature") is None
+    assert gate.missing_look_reason(payload) == UNREADABLE_CHANGES_REASON
+    assert all_endpoints == [compare_endpoint, compare_endpoint]
+
+
+def test_should_allow_a_short_compare_page_that_lists_only_python(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    all_endpoints: list[str] = []
+    compare_endpoint = "repos/o/r/compare/main...feature"
+    monkeypatch.setattr(
+        gate,
+        "_gh_api_lines",
+        _fake_gh_api({compare_endpoint: _python_paths(COMPARE_FILE_LIST_LIMIT - 1)}, all_endpoints),
+    )
+    payload = _shell_create_elsewhere(tmp_path, "--repo o/r --base main --head feature")
+    assert gate.remote_visible_changed_files("o/r", "main", "feature") == []
+    assert gate.missing_look_reason(payload) is None
+
+
+def test_should_deny_a_visible_file_on_a_full_compare_page(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    all_endpoints: list[str] = []
+    compare_endpoint = "repos/o/r/compare/main...feature"
+    all_paths = [*_python_paths(COMPARE_FILE_LIST_LIMIT - 1), "web/page.html"]
+    monkeypatch.setattr(gate, "_gh_api_lines", _fake_gh_api({compare_endpoint: all_paths}, all_endpoints))
+    reason = gate.missing_look_reason(_shell_create_elsewhere(tmp_path, "--repo o/r --base main --head feature"))
+    assert reason is not None
+    assert "web/page.html" in reason
+    assert "module_0.py" not in reason
+
+
+def test_should_allow_a_page_the_compare_api_lists_when_the_proof_links_an_artifact(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    all_endpoints: list[str] = []
+    compare_endpoint = "repos/o/r/compare/main...feature"
+    monkeypatch.setattr(gate, "_gh_api_lines", _fake_gh_api({compare_endpoint: ["page.html"]}, all_endpoints))
+    body_path = tmp_path / "body.md"
+    body_path.write_text(PROVEN_BODY + "https://claude.ai/code/artifact/abc-123\n", encoding="utf-8")
+    payload = _shell(
+        f"gh pr create --title t --body-file {body_path} --repo o/r --base main --head feature",
+        tmp_path,
+    )
+    assert gate.missing_look_reason(payload) is None
+    assert all_endpoints == [compare_endpoint]
+
+
+def test_should_skip_the_compare_api_without_a_named_repository(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    all_endpoints: list[str] = []
+    monkeypatch.setattr(gate, "_gh_api_lines", _fake_gh_api({}, all_endpoints))
+    payload = _shell_create_elsewhere(tmp_path, "--base main --head feature")
+    assert gate.missing_look_reason(payload) == UNREADABLE_CHANGES_REASON
+    assert all_endpoints == []
+
+
+def test_should_read_owner_and_repo_of_an_mcp_create_for_the_compare_api(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    all_endpoints: list[str] = []
+    compare_endpoint = "repos/o/r/compare/main...feature"
+    monkeypatch.setattr(gate, "_gh_api_lines", _fake_gh_api({compare_endpoint: ["tool.py"]}, all_endpoints))
+    payload = _mcp_create_on_branch(PROVEN_BODY, tmp_path)
+    payload["tool_input"].update(owner="o", repo="r", base="main")
+    assert gate.missing_look_reason(payload) is None
+    assert all_endpoints == [compare_endpoint]
+
+
 def test_visible_changed_files_falls_back_to_origin_main_without_origin_head(tmp_path: Path) -> None:
     clone_path = _repository_with_change(tmp_path, "page.html")
     subprocess.run(["git", "-C", str(clone_path), "remote", "set-head", "origin", "-d"], check=True)

package/hooks/hooks_constants/pull_request_proof_constants.py

@@ -85,7 +85,17 @@ ALL_DEFAULT_BRANCH_REFERENCES = ("origin/HEAD", "origin/main", "main")
 REMOTE_BRANCH_PREFIX = "origin/"
 ALL_HEAD_FLAGS = frozenset({"--head", "-H"})
 HEAD_FLAG_ASSIGNMENT_PREFIX = "--head="
+ALL_BASE_FLAGS = frozenset({"--base", "-B"})
+BASE_FLAG_ASSIGNMENT_PREFIX = "--base="
+ALL_REPOSITORY_FLAGS = frozenset({"--repo", "-R"})
+REPOSITORY_FLAG_ASSIGNMENT_PREFIX = "--repo="
 GIT_TIMEOUT_SECONDS = 5
+GH_TIMEOUT_SECONDS = 15
+COMPARE_ENDPOINT_TEMPLATE = "repos/{repository}/compare/{base_branch}...{head_branch}"
+COMPARE_FILE_NAMES_QUERY = ".files[].filename"
+COMPARE_FILE_LIST_LIMIT = 300
+REPOSITORY_ENDPOINT_TEMPLATE = "repos/{repository}"
+DEFAULT_BRANCH_QUERY = ".default_branch"
 MISSING_LOOK_REASON = (
     "This pull request changes files people see ({changed_files}), and its 'Proof in"
     " practice' section shows no picture. Render the change, open the screenshot with the"
@@ -96,11 +106,14 @@ MISSING_LOOK_REASON = (
 )
 CHANGED_FILES_SEPARATOR = ", "
 UNREADABLE_CHANGES_REASON = (
-    "Git in this directory cannot list the files this pull request changes, so the"
-    " picture check cannot tell whether people see the change. Put a screenshot or"
-    " Artifact link in the 'Proof in practice' section and run the create call again,"
-    " or run it from a checkout of the head branch with origin fetched. Take one of"
-    " these routes now, before any change to this gate. Read " + PROOF_GUIDE_PATH + " for the full rule."
+    "Neither git in this directory nor the GitHub compare API can list the files this"
+    " pull request changes, so the picture check cannot tell whether people see the change."
+    " Name the repository and head branch with --repo and --head, run the create call"
+    " from a checkout of the head branch with origin fetched, or put a screenshot or"
+    " Artifact link in the 'Proof in practice' section and run the create call again."
+    " Take one of these routes now, before any change to this gate. Read "
+    + PROOF_GUIDE_PATH
+    + " for the full rule."
 )
 FEATURE_TITLE_PATTERN = r"^\s*feat(\([^)]*\))?!?:"
 EVAL_HEADING_PATTERN = r"^(#{1,6})[ \t]+evals?[ \t]*#*[ \t]*$"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.84.0",
+    "version": "8.84.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/conftest.py

@@ -18,6 +18,7 @@ is in place by the time any test module runs its top-level imports.
 from __future__ import annotations
 
 import importlib
+import site
 import subprocess
 import sys
 from collections.abc import Callable
@@ -35,25 +36,33 @@ for each_import_directory in (
     if str(each_import_directory) not in sys.path:
         sys.path.insert(0, str(each_import_directory))
 
-_live_broker_state_resolver = importlib.import_module("account_broker_support").broker_state_path
+from dev_env_scripts_constants.account_broker_constants import ALL_ACCOUNT_ENVIRONMENT_VARIABLES
 
 
 @pytest.fixture(autouse=True)
-def isolated_broker_state_path(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
-    """Point every module's ``broker_state_path`` at a per-test file.
-
-    ``account_broker`` binds ``broker_state_path`` by name from
-    ``account_broker_support``, so each bound copy is replaced. A test that
-    patches only one copy still keeps the other off the home directory.
+def isolated_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
+    """Point the home directory at a per-test folder for every test here.
+
+    ``Path.home()`` reads ``HOME`` on POSIX and ``USERPROFILE`` on Windows, so
+    redirecting both keeps call-time home lookups, such as
+    ``broker_state_path``, off the user's home directory. The variables in
+    ``ALL_ACCOUNT_ENVIRONMENT_VARIABLES`` are cleared, so account roots fall
+    back to the per-test home and no developer roster applies. A value built
+    from ``Path.home()`` at import time keeps the user's home.
+    ``PYTHONUSERBASE`` stays on the user base captured before the redirect, so
+    a new interpreter still imports packages installed for this user.
 
     Returns:
-        The isolated broker state path for this test.
+        The per-test home directory.
     """
-    isolated_path = tmp_path / "account-broker" / "state.json"
-    for each_module in list(sys.modules.values()):
-        if getattr(each_module, "broker_state_path", None) is _live_broker_state_resolver:
-            monkeypatch.setattr(each_module, "broker_state_path", lambda: isolated_path)
-    return isolated_path
+    user_base = site.getuserbase()
+    isolated_home_directory = tmp_path / "home"
+    monkeypatch.setenv("PYTHONUSERBASE", user_base)
+    monkeypatch.setenv("HOME", str(isolated_home_directory))
+    monkeypatch.setenv("USERPROFILE", str(isolated_home_directory))
+    for each_account_variable in ALL_ACCOUNT_ENVIRONMENT_VARIABLES:
+        monkeypatch.delenv(each_account_variable, raising=False)
+    return isolated_home_directory
 
 
 def _link_directory(*, from_link: Path, to_target: Path) -> None:

package/scripts/dev_env_scripts_constants/account_broker_constants.py

@@ -16,12 +16,15 @@ from dev_env_scripts_constants.claude_account_constants import (
     FULL_PERCENT,
     MAIN_SESSION_USED_CEILING_PERCENT,
     MAIN_WEEKLY_USED_CEILING_PERCENT,
+    PROFILES_ROOT_ENVIRONMENT_VARIABLE,
     SECOND_SESSION_USED_CEILING_PERCENT,
     SECOND_WEEKLY_USED_CEILING_PERCENT,
 )
 from dev_env_scripts_constants.codex_account_constants import (
     ALL_PRO_PLAN_TYPES,
+    CODEX_ACCOUNT_PROFILES_ENVIRONMENT_VARIABLE,
     CODEX_HOME_ENVIRONMENT_VARIABLE,
+    CODEX_PROFILES_ROOT_ENVIRONMENT_VARIABLE,
     LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT,
     LUNA_TIER_STOP_PERCENT_LEFT,
     MAIN_CODEX_HOME_DIRECTORY_NAME,
@@ -30,6 +33,7 @@ from dev_env_scripts_constants.codex_account_constants import (
     TIER_NORMAL,
 )
 from dev_env_scripts_constants.shared_tree_constants import (
+    CLAUDE_CONFIG_DIR_ENV_VAR,
     CODEX_CLASSIFIER_CONSTANTS_RELATIVE_PATH,
     CONSTANTS_PACKAGE_ANCHOR_DEPTH,
     PR_LOOP_DIRECTORY_NAME,
@@ -64,6 +68,14 @@ BROKER_STATE_DIRECTORY_NAME = "account-broker"
 BROKER_STATE_FILE_NAME = "state.json"
 BROKER_STATE_TEMP_SUFFIX = ".json"
 BROKER_STATE_LOCK_SUFFIX = ".lock"
+ALL_ACCOUNT_ENVIRONMENT_VARIABLES = (
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+    CODEX_HOME_ENVIRONMENT_VARIABLE,
+    CODEX_ACCOUNT_PROFILES_ENVIRONMENT_VARIABLE,
+    CODEX_PROFILES_ROOT_ENVIRONMENT_VARIABLE,
+    PROFILES_ROOT_ENVIRONMENT_VARIABLE,
+)
+"""Variables that point the account tools at a developer's own account roots, Codex home and Codex roster."""
 ALL_BATCH_FILE_EXTENSIONS = frozenset({".bat", ".cmd"})
 CMD_SHELL_METACHARACTERS = "&|<>^%!\"\r\n"
 CLAUDE_BINARY_NAME = "claude"

package/scripts/dev_env_scripts_constants/test_account_broker_constants.py

@@ -15,7 +15,9 @@ from pathlib import Path
 import pytest
 
 from dev_env_scripts_constants import account_broker_constants as broker_constants
+from dev_env_scripts_constants import claude_account_constants, codex_account_constants, shared_tree_constants
 from dev_env_scripts_constants.account_broker_constants import (
+    ALL_ACCOUNT_ENVIRONMENT_VARIABLES,
     ALL_BATCH_FILE_EXTENSIONS,
     ALL_CLAUDE_FLOORS,
     ALL_CODEX_FLOORS,
@@ -57,6 +59,16 @@ def test_should_keep_codex_floors_tied_to_the_tier_limits() -> None:
     }
 
 
+def test_should_list_every_account_environment_variable() -> None:
+    all_declared_variables = {
+        each_value
+        for each_module in (claude_account_constants, codex_account_constants, shared_tree_constants)
+        for each_name, each_value in vars(each_module).items()
+        if each_name.endswith(("_ENVIRONMENT_VARIABLE", "_ENV_VAR"))
+    }
+    assert all_declared_variables == set(ALL_ACCOUNT_ENVIRONMENT_VARIABLES)
+
+
 def test_batch_command_boundaries_include_shell_metacharacters() -> None:
     assert ALL_BATCH_FILE_EXTENSIONS == frozenset({".bat", ".cmd"})
     assert set(CMD_SHELL_METACHARACTERS) == set('&|<>^%!"\r\n')

package/scripts/test_account_broker.py

@@ -42,12 +42,6 @@ def _freeze_clock(monkeypatch: pytest.MonkeyPatch, instant: datetime) -> None:
     monkeypatch.setattr(account_broker, "datetime", _FrozenClock)
 
 
-@pytest.fixture(autouse=True)
-def isolated_state(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
-    monkeypatch.setattr(account_broker, "broker_state_path", lambda: tmp_path / "broker" / "state.json")
-    monkeypatch.setattr(account_broker.support, "broker_state_path", lambda: tmp_path / "broker" / "state.json")
-
-
 def _account(name: str, product: Product = Product.CODEX, main: bool = False) -> Account:
     return Account(product, name, Path("/profiles") / name, main, name)
 

package/scripts/test_account_broker_support.py

@@ -256,8 +256,7 @@ def _recorded_sleeps(monkeypatch: pytest.MonkeyPatch) -> list[float]:
     return all_delays
 
 
-def _first_reading(monkeypatch: pytest.MonkeyPatch, tmp_path: Path, account: Account, read_meters: object) -> object:
-    monkeypatch.setattr(support, "broker_state_path", lambda: tmp_path / "broker" / "state.json")
+def _first_reading(account: Account, read_meters: object) -> object:
     adapter = ProductAdapter(lambda: (account,), read_meters, "HOME", ())
     state = support._load_state(support.broker_state_path())
     now = datetime(2026, 10, 3, tzinfo=timezone.utc)
@@ -272,7 +271,7 @@ def test_should_read_claude_meters_after_transient_failures_with_growing_delays(
     all_paths_read = _claude_meter_reads(monkeypatch, [unread, unread, usage])
     all_delays = _recorded_sleeps(monkeypatch)
 
-    reading = _first_reading(monkeypatch, tmp_path, Account(Product.CLAUDE, "org-jon", tmp_path), support.read_claude_meters)[0]
+    reading = _first_reading(Account(Product.CLAUDE, "org-jon", tmp_path), support.read_claude_meters)[0]
 
     assert reading.meters is not None
     assert reading.meters.weekly_percent_left == 70.0
@@ -289,7 +288,7 @@ def test_should_read_codex_meters_after_transient_failures_with_growing_delays(
     all_homes_read = _codex_meter_reads(monkeypatch, tmp_path, [unread, unread, usage])
     all_delays = _recorded_sleeps(monkeypatch)
 
-    reading = _first_reading(monkeypatch, tmp_path, Account(Product.CODEX, "one", tmp_path), support.read_codex_account_meters)[0]
+    reading = _first_reading(Account(Product.CODEX, "one", tmp_path), support.read_codex_account_meters)[0]
 
     assert reading.meters is not None
     assert reading.meters.weekly_percent_left == 70.0
@@ -307,7 +306,7 @@ def test_should_stop_at_once_when_no_codex_executable_is_found(
     monkeypatch.setattr(Path, "home", lambda: tmp_path)
     all_delays = _recorded_sleeps(monkeypatch)
 
-    reading = _first_reading(monkeypatch, tmp_path, Account(Product.CODEX, "one", tmp_path), support.read_codex_account_meters)[0]
+    reading = _first_reading(Account(Product.CODEX, "one", tmp_path), support.read_codex_account_meters)[0]
 
     assert reading.meters is None
     assert reading.unread_reason == "no codex executable on PATH or at its install path"
@@ -322,7 +321,7 @@ def test_should_keep_the_unread_reason_after_every_claude_read_fails(
     all_paths_read = _claude_meter_reads(monkeypatch, all_failures)
     all_delays = _recorded_sleeps(monkeypatch)
 
-    reading, adapter, state, now = _first_reading(monkeypatch, tmp_path, Account(Product.CLAUDE, "org-jon", tmp_path), support.read_claude_meters)
+    reading, adapter, state, now = _first_reading(Account(Product.CLAUDE, "org-jon", tmp_path), support.read_claude_meters)
     cached_reading = support.read_accounts(Product.CLAUDE, adapter, all_state=state, now=now)[0]
 
     assert reading.meters is None
@@ -340,7 +339,7 @@ def test_should_keep_the_unread_reason_after_every_codex_read_fails(
     all_homes_read = _codex_meter_reads(monkeypatch, tmp_path, [first_unread, first_unread, last_unread])
     _recorded_sleeps(monkeypatch)
 
-    reading, adapter, state, now = _first_reading(monkeypatch, tmp_path, Account(Product.CODEX, "codex-3", tmp_path), support.read_codex_account_meters)
+    reading, adapter, state, now = _first_reading(Account(Product.CODEX, "codex-3", tmp_path), support.read_codex_account_meters)
     cached_reading = support.read_accounts(Product.CODEX, adapter, all_state=state, now=now)[0]
 
     assert reading.meters is None

package/scripts/test_broker_state_isolation.py

@@ -1,4 +1,4 @@
-"""Broker state written during a test stays out of the home directory."""
+"""Broker state written during a test lands in the per-test home directory."""
 
 from __future__ import annotations
 
@@ -18,14 +18,11 @@ from dev_env_scripts_constants.account_broker_constants import (
 )
 
 
-def test_meter_cache_write_lands_outside_the_home_directory(
+def test_meter_cache_write_lands_in_the_isolated_home(
     monkeypatch: pytest.MonkeyPatch,
     tmp_path: Path,
-    isolated_broker_state_path: Path,
+    isolated_home: Path,
 ) -> None:
-    fake_home = tmp_path / "home"
-    monkeypatch.setenv("HOME", str(fake_home))
-    monkeypatch.setenv("USERPROFILE", str(fake_home))
     account = Account(Product.CLAUDE, "only", tmp_path / "only")
     reset_at = datetime(2026, 10, 5, tzinfo=timezone.utc)
     adapter = ProductAdapter(
@@ -39,10 +36,12 @@ def test_meter_cache_write_lands_outside_the_home_directory(
     def runner(argv: list[str], **options: object) -> subprocess.CompletedProcess[str]:
         return subprocess.CompletedProcess(argv, 0, "", "")
 
+    isolated_broker_state_path = account_broker.broker_state_path()
+    assert Path.home() == isolated_home
+    assert isolated_broker_state_path.is_relative_to(isolated_home)
+    assert not isolated_broker_state_path.exists()
     with account_broker.override_subprocess_runner(runner):
         account_broker.run_job(Product.CLAUDE, ["claude"])
 
-    home_state_path = fake_home / ".claude" / "account-broker" / "state.json"
-    assert not home_state_path.exists()
     state = json.loads(isolated_broker_state_path.read_text(encoding="utf-8"))
     assert f"claude:only:{account.home}" in state["meters"]

package/scripts/test_conftest.py

@@ -0,0 +1,54 @@
+import os
+import subprocess
+import sys
+from collections.abc import Iterator
+from pathlib import Path
+
+import pytest
+
+import account_broker_support
+from dev_env_scripts_constants.account_broker_constants import ALL_ACCOUNT_ENVIRONMENT_VARIABLES
+
+
+@pytest.fixture(scope="module")
+def exported_account_variables(tmp_path_factory: pytest.TempPathFactory) -> Iterator[None]:
+    exported_root = tmp_path_factory.mktemp("exported-overrides")
+    with pytest.MonkeyPatch.context() as module_monkeypatch:
+        for each_account_variable in ALL_ACCOUNT_ENVIRONMENT_VARIABLES:
+            module_monkeypatch.setenv(each_account_variable, str(exported_root / each_account_variable))
+        yield
+
+
+def test_broker_state_path_follows_the_redirected_home(
+    isolated_home: Path, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    assert Path.home() == isolated_home
+    assert account_broker_support.broker_state_path().is_relative_to(isolated_home)
+    moved_home = tmp_path / "moved-home"
+    monkeypatch.setenv("HOME", str(moved_home))
+    monkeypatch.setenv("USERPROFILE", str(moved_home))
+    assert account_broker_support.broker_state_path().is_relative_to(moved_home)
+
+
+def test_isolated_home_clears_the_exported_account_variables(
+    exported_account_variables: None, isolated_home: Path
+) -> None:
+    for each_account_variable in ALL_ACCOUNT_ENVIRONMENT_VARIABLES:
+        assert each_account_variable not in os.environ
+
+
+def test_isolated_home_keeps_the_python_user_base_for_a_new_interpreter(
+    isolated_home: Path,
+) -> None:
+    completed = subprocess.run(
+        [sys.executable, "-c", "import site; print(site.getuserbase())"],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+
+    assert completed.returncode == 0
+    child_user_base = Path(completed.stdout.strip())
+    assert str(child_user_base) == os.environ["PYTHONUSERBASE"]
+    assert child_user_base != isolated_home
+    assert isolated_home not in child_user_base.parents