claude-dev-env 1.41.0 → 1.43.0

package/CLAUDE.md

@@ -23,6 +23,14 @@ When writing tests, always write tests that actually test the behavior of the fu
 
 When writing tests, always ensure you utilize the production code paths instead of duplicating explicitly for the test.
 
+## Research via Subagents
+
+Delegate exploration whose raw content you won't directly edit or reuse. If you'd `Read` more than one file or `Grep` more than one pattern just to extract a fact, dispatch an `Explore` subagent.
+
+Ask the subagent for a specific answer: "return the file:line where X is defined." For multiple unrelated questions, fan out parallel subagents — issue several `Agent` calls in a single response.
+
+Reserve `Read`/`Grep`/`Glob` for files you will actually touch this turn. Compose subagent prompts via the protocol in `agent-spawn-protocol`.
+
 ## Additional Non-overlapping Rules
 
 - **task_scope:** Match every action to what was explicitly requested. When intent is ambiguous, research official docs and present options via AskUserQuestion before making any changes. Proceed with edits only on explicit instruction.

package/_shared/pr-loop/scripts/_claude_permissions_common.py

@@ -13,14 +13,12 @@ import os
 import secrets
 import stat
 import sys
+from collections.abc import Callable
 from pathlib import Path
 from typing import NoReturn
 
-sys.modules.pop("config", None)
-if str(Path(__file__).resolve().parent) not in sys.path:
-    sys.path.insert(0, str(Path(__file__).resolve().parent))
-
-from config.claude_permissions_constants import (
+from pr_loop_shared_constants.claude_permissions_constants import (
+    ALL_TRUST_ENTRY_PROJECT_PATH_BOUNDARY_QUOTE_CHARACTERS,
     CLAUDE_SETTINGS_DIRECTORY_NAME,
     GIT_DIRECTORY_NAME,
     TEXT_FILE_ENCODING as TEXT_FILE_ENCODING,
@@ -29,11 +27,27 @@ from config.claude_permissions_constants import (
 
 
 def exit_with_error(message: str) -> NoReturn:
+    """Print an error message to stderr and terminate the process.
+
+    Args:
+        message: The error message to print to stderr.
+
+    Raises:
+        SystemExit: Always raised with a non-zero exit code.
+    """
     print(f"Error: {message}", file=sys.stderr)
     raise SystemExit(1)
 
 
 def path_contains_glob_metacharacters(candidate_path: str) -> bool:
+    """Check whether a path contains characters reserved for glob patterns.
+
+    Args:
+        candidate_path: The file path string to inspect.
+
+    Returns:
+        True when any glob metacharacter is present in the path.
+    """
     all_glob_metacharacters_in_path: tuple[str, ...] = (
         "*",
         "?",
@@ -49,6 +63,14 @@ def path_contains_glob_metacharacters(candidate_path: str) -> bool:
 
 
 def get_current_project_path() -> str:
+    """Return the normalized current working directory path.
+
+    Returns:
+        The cwd as a POSIX-style path string.
+
+    Raises:
+        ValueError: When the path contains glob metacharacters.
+    """
     normalized_project_path = str(Path.cwd()).replace("\\", "/")
     if path_contains_glob_metacharacters(normalized_project_path):
         raise ValueError(
@@ -65,13 +87,142 @@ def build_permission_rule(tool_name: str, project_path: str) -> str:
 def build_permission_rules(
     project_path: str, all_permission_allow_tools: tuple[str, ...]
 ) -> list[str]:
+    """Construct permission rule strings for each tool.
+
+    Args:
+        project_path: The POSIX-style project root path.
+        all_permission_allow_tools: Tool names to build rules for.
+
+    Returns:
+        List of permission rule strings for the given project path.
+    """
     return [
         build_permission_rule(each_tool, project_path)
         for each_tool in all_permission_allow_tools
     ]
 
 
+def build_agent_config_deny_rule(
+    tool_name: str, project_path: str, agent_config_path_pattern: str
+) -> str:
+    """Construct a deny rule for a single agent-config path pattern.
+
+    Args:
+        tool_name: The permission tool name (e.g., "Edit", "Write", "Read").
+        project_path: The POSIX-style project root path.
+        agent_config_path_pattern: The agent-config path pattern under .claude/.
+
+    Returns:
+        The deny rule string Claude Code matches against tool invocations.
+    """
+    return f"{tool_name}({project_path}/.claude/{agent_config_path_pattern})"
+
+
+def build_agent_config_deny_rules(
+    project_path: str,
+    all_permission_allow_tools: tuple[str, ...],
+    all_agent_config_path_patterns: tuple[str, ...],
+) -> list[str]:
+    """Construct deny rules covering every tool and pattern pair.
+
+    Args:
+        project_path: The POSIX-style project root path.
+        all_permission_allow_tools: Tool names to build deny rules for.
+        all_agent_config_path_patterns: Agent-config path patterns to deny under .claude/.
+
+    Returns:
+        List of deny rule strings, one per tool/pattern combination.
+    """
+    return [
+        build_agent_config_deny_rule(each_tool, project_path, each_pattern)
+        for each_tool in all_permission_allow_tools
+        for each_pattern in all_agent_config_path_patterns
+    ]
+
+
+def _is_project_path_token_at_word_boundary(
+    body_after_prefix: str, token_position: int
+) -> bool:
+    if token_position == 0:
+        return True
+    preceding_character = body_after_prefix[token_position - 1]
+    if preceding_character.isspace():
+        return True
+    return preceding_character in ALL_TRUST_ENTRY_PROJECT_PATH_BOUNDARY_QUOTE_CHARACTERS
+
+
+def is_trust_entry_for_project(
+    candidate_entry: object, project_path: str, prefix: str
+) -> bool:
+    """Detect whether an autoMode.environment entry is a trust entry for the project.
+
+    The predicate matches any string entry whose prefix matches the trust-entry
+    marker and that contains the project's .claude/** path token anchored on a
+    non-path boundary (the start of the body after the prefix, a whitespace
+    character, or a quote character). The boundary anchor prevents
+    cross-project false positives where the current project's path is a path
+    suffix of an unrelated entry's path. The exact wording after the prefix is
+    allowed to vary between template revisions.
+
+    Args:
+        candidate_entry: The autoMode.environment list value to inspect.
+        project_path: The POSIX-style project root path.
+        prefix: The literal prefix that marks a trust entry.
+
+    Returns:
+        True when the entry is a prior trust entry for this project.
+    """
+    if not isinstance(candidate_entry, str):
+        return False
+    if not candidate_entry.startswith(prefix):
+        return False
+    project_path_token = f"{project_path}/.claude/**"
+    body_after_prefix = candidate_entry[len(prefix):]
+    token_position = body_after_prefix.find(project_path_token)
+    while token_position != -1:
+        if _is_project_path_token_at_word_boundary(body_after_prefix, token_position):
+            return True
+        next_search_start = token_position + 1
+        token_position = body_after_prefix.find(project_path_token, next_search_start)
+    return False
+
+
+def remove_matching_entries_from_list(
+    all_target_list: list[object],
+    match_predicate: Callable[[object], bool],
+) -> int:
+    """Remove every entry from a list that satisfies the predicate.
+
+    Args:
+        all_target_list: The list to filter in place.
+        match_predicate: Function returning True for entries to remove.
+
+    Returns:
+        Number of entries removed.
+    """
+    original_length = len(all_target_list)
+    all_target_list[:] = [
+        each_value
+        for each_value in all_target_list
+        if not match_predicate(each_value)
+    ]
+    return original_length - len(all_target_list)
+
+
 def load_settings(settings_path: Path) -> dict[str, object]:
+    """Read and parse a JSON settings file from disk.
+
+    Args:
+        settings_path: Path to the JSON settings file.
+
+    Returns:
+        Parsed settings dictionary. Returns an empty dict when the file
+        does not exist.
+
+    Raises:
+        SystemExit: When the file exists but is not valid JSON, or when
+            its root value is not a JSON object.
+    """
     if not settings_path.exists():
         return {}
     parsed_settings: dict[str, object] = {}
@@ -96,6 +247,14 @@ def load_settings(settings_path: Path) -> dict[str, object]:
 
 
 def serialize_settings_to_json_text(all_settings: dict[str, object]) -> str:
+    """Serialize a settings dictionary to JSON text with stable formatting.
+
+    Args:
+        all_settings: The settings dictionary to serialize.
+
+    Returns:
+        Pretty-printed JSON string with sorted keys.
+    """
     json_indent_width_columns: int = len("  ")
     return json.dumps(
         all_settings,
@@ -105,6 +264,15 @@ def serialize_settings_to_json_text(all_settings: dict[str, object]) -> str:
 
 
 def get_mode_to_preserve(settings_path: Path) -> int:
+    """Return the file permission bits from an existing settings file.
+
+    Args:
+        settings_path: Path to the target settings file to stat.
+
+    Returns:
+        The permission bits from the file mode. Returns the default
+        secure mode when the file does not exist.
+    """
     default_settings_file_mode: int = 0o600
     try:
         stat_result = os.stat(settings_path)
@@ -118,6 +286,23 @@ def get_mode_to_preserve(settings_path: Path) -> int:
 def write_atomically_with_mode(
     temporary_path: Path, serialized_content: str, file_mode: int
 ) -> None:
+    """Create and write to a temporary file with the given mode.
+
+    Uses os.open with O_CREAT | O_EXCL to create the file securely, then
+    writes the serialized content. The caller is responsible for replacing
+    the target file with os.replace afterward.
+
+    Args:
+        temporary_path: Path for the temporary file (sibling of target).
+        serialized_content: The content to write to the temporary file.
+        file_mode: Unix permission bits for the new file.
+
+    Raises:
+        OSError: When os.open or os.fdopen fails. The raw file descriptor
+            is closed before re-raising so the descriptor does not leak.
+        MemoryError: When os.fdopen runs out of buffer memory; the file
+            descriptor is closed before re-raising.
+    """
     file_descriptor = os.open(
         str(temporary_path),
         os.O_WRONLY | os.O_CREAT | os.O_EXCL,
@@ -125,7 +310,7 @@ def write_atomically_with_mode(
     )
     try:
         writer = os.fdopen(file_descriptor, "w", encoding=TEXT_FILE_ENCODING)
-    except BaseException:
+    except (OSError, MemoryError):
         os.close(file_descriptor)
         raise
     with writer:
@@ -133,6 +318,15 @@ def write_atomically_with_mode(
 
 
 def save_settings(settings_path: Path, all_settings: dict[str, object]) -> None:
+    """Write settings to a JSON file atomically with permission preservation.
+
+    Creates a temporary sibling file, writes content, then atomically
+    replaces the target. Cleans up the temporary file in a finally block.
+
+    Args:
+        settings_path: Path to the target settings JSON file.
+        all_settings: The settings dictionary to serialize and save.
+    """
     unique_temporary_suffix_byte_length = UNIQUE_TEMPORARY_SUFFIX_BYTE_LENGTH
     settings_path.parent.mkdir(parents=True, exist_ok=True)
     serialized_settings = serialize_settings_to_json_text(all_settings)
@@ -163,6 +357,15 @@ def save_settings(settings_path: Path, all_settings: dict[str, object]) -> None:
 
 
 def append_if_missing(all_target_list: list[object], new_value: str) -> bool:
+    """Add a value to a list when it is not already present.
+
+    Args:
+        all_target_list: The list to potentially append to.
+        new_value: The string value to add when missing.
+
+    Returns:
+        True when the value was appended, False when it already existed.
+    """
     if new_value in all_target_list:
         return False
     all_target_list.append(new_value)
@@ -172,12 +375,19 @@ def append_if_missing(all_target_list: list[object], new_value: str) -> bool:
 def ensure_dict_section(
     all_settings: dict[str, object], section_name: str
 ) -> dict[str, object]:
-    """Return an existing dict section or create an empty one if absent.
+    """Return an existing dict section or create an empty one when absent.
 
     A missing key and an explicit JSON null are treated identically: both
     produce a fresh empty dict stored back into settings. Any other non-dict
     value (string, list, number, bool) calls exit_with_error to avoid
     overwriting user data.
+
+    Args:
+        all_settings: The parsed settings dictionary.
+        section_name: Key name of the section to retrieve or create.
+
+    Returns:
+        The existing or newly created section dictionary.
     """
     existing_section = all_settings.get(section_name)
     if existing_section is None:
@@ -194,12 +404,19 @@ def ensure_dict_section(
 
 
 def ensure_list_entry(all_section: dict[str, object], entry_name: str) -> list[object]:
-    """Return an existing list entry or create an empty one if absent.
+    """Return an existing list entry or create an empty one when absent.
 
     A missing key and an explicit JSON null are treated identically: both
     produce a fresh empty list stored back into the section. Any other
     non-list value (string, dict, number, bool) calls exit_with_error to
     avoid overwriting user data.
+
+    Args:
+        all_section: The parent dictionary section.
+        entry_name: Key name of the list entry to retrieve or create.
+
+    Returns:
+        The existing or newly created list entry.
     """
     existing_entry = all_section.get(entry_name)
     if existing_entry is None:
@@ -224,6 +441,13 @@ def is_valid_project_root(candidate_path: Path) -> bool:
 def prune_empty_list_then_empty_section(
     all_settings: dict[str, object], section_key: str, list_key: str
 ) -> None:
+    """Remove an empty list key and its parent section when both are empty.
+
+    Args:
+        all_settings: The parsed settings dictionary to prune in place.
+        section_key: Key of the parent section to check.
+        list_key: Key of the list entry within the section.
+    """
     section = all_settings.get(section_key)
     if not isinstance(section, dict):
         return