claude-dev-env 4.1.0 → 4.3.0

package/hooks/hooks_constants/test_path_rewriter_constants.py

@@ -1,57 +0,0 @@
-"""Pin tests for path_rewriter_constants — values consumed by es_exe_path_rewriter."""
-
-import sys
-from pathlib import Path
-
-_HOOKS_ROOT = Path(__file__).resolve().parent.parent
-if str(_HOOKS_ROOT) not in sys.path:
-    sys.path.insert(0, str(_HOOKS_ROOT))
-
-from hooks_constants.path_rewriter_constants import (
-    BASH_TOOL_NAME,
-    HOOK_EVENT_NAME,
-    PERMISSION_ALLOW,
-    PLACEHOLDER_TOKEN_PATTERN,
-)
-
-
-def test_bash_tool_name_is_bash() -> None:
-    assert BASH_TOOL_NAME == "Bash"
-
-
-def test_hook_event_name_is_pre_tool_use() -> None:
-    assert HOOK_EVENT_NAME == "PreToolUse"
-
-
-def test_permission_allow_is_allow() -> None:
-    assert PERMISSION_ALLOW == "allow"
-
-
-def test_placeholder_token_pattern_matches_curly_brace_form() -> None:
-    match = PLACEHOLDER_TOKEN_PATTERN.match("{my-repo}")
-    assert match is not None
-    assert match.group(1) == "my-repo"
-
-
-def test_placeholder_token_pattern_matches_double_quoted_form() -> None:
-    match = PLACEHOLDER_TOKEN_PATTERN.match('"{my-repo}"')
-    assert match is not None
-    assert match.group(1) == "my-repo"
-
-
-def test_placeholder_token_pattern_matches_single_quoted_form() -> None:
-    match = PLACEHOLDER_TOKEN_PATTERN.match("'{my-repo}'")
-    assert match is not None
-    assert match.group(1) == "my-repo"
-
-
-def test_placeholder_token_pattern_does_not_match_shell_parameter_expansion() -> None:
-    assert PLACEHOLDER_TOKEN_PATTERN.search("${myrepo}") is None
-
-
-def test_placeholder_token_pattern_does_not_match_embedded_in_flag() -> None:
-    assert PLACEHOLDER_TOKEN_PATTERN.search("--flag={my-repo}") is None
-
-
-def test_placeholder_token_pattern_does_not_match_embedded_in_token() -> None:
-    assert PLACEHOLDER_TOKEN_PATTERN.search("foo{my-repo}bar") is None

package/hooks/hooks_constants/volatile_path_in_post_blocker_constants.py

@@ -1,55 +0,0 @@
-"""Configuration constants for the volatile_path_in_post_blocker PreToolUse hook."""
-
-BASH_TOOL_NAME: str = "Bash"
-
-MCP_GITHUB_TOOL_PREFIX: str = "mcp__plugin_github_github__"
-
-ALL_MCP_BODY_PARAM_NAMES: tuple[str, ...] = ("body", "comment")
-
-GH_COMMAND_NAME: str = "gh"
-
-MINIMUM_POST_SUBCOMMAND_TOKEN_COUNT: int = 2
-
-TOKEN_JOIN_SEPARATOR: str = " "
-
-BODY_FILE_ENCODING: str = "utf-8"
-
-ALL_GH_POST_SUBCOMMANDS: dict[str, frozenset[str]] = {
-    "pr": frozenset({"create", "comment", "edit", "review"}),
-    "issue": frozenset({"create", "comment", "edit"}),
-}
-
-PATH_ANCHOR_CHARACTER: str = "/"
-
-PATH_SEGMENT_START_CHARACTERS: str = "_-"
-
-ALL_PATH_ANCHORED_VOLATILE_PATH_MARKERS: tuple[str, ...] = (
-    ".claude-profile-a/jobs/",
-    ".claude/worktrees/",
-)
-
-ALL_BARE_VOLATILE_PATH_MARKERS: tuple[str, ...] = (
-    "appdata/local/temp",
-    "/tmp/",
-    "%temp%",
-    "$env:temp",
-    "$claude_job_dir",
-)
-
-GH_ARTIFACT_UPLOAD_INVOCATION: str = (
-    "python3 ~/.claude/scripts/gh_artifact_upload.py <file-path> <owner/repo>"
-)
-
-CORRECTIVE_MESSAGE: str = (
-    "BLOCKED [durable-post-artifacts]: this post body references a volatile path "
-    "(a job scratch dir, worktree, or system temp location). The post is durable "
-    "and outlives that scratch, so the reference breaks the moment the directory "
-    "is cleaned.\n\n"
-    "Fix it before posting:\n"
-    "  1. Text data (logs, tables, diffs): paste the actual content inline in the "
-    "post instead of linking a scratch file path.\n"
-    "  2. Binary artifacts (images, archives): upload the file to the repo's "
-    "durable 'artifacts' release and link the permanent asset URL it prints:\n"
-    f"       {GH_ARTIFACT_UPLOAD_INVOCATION}\n\n"
-    "See ~/.claude/rules/durable-post-artifacts.md for the full contract."
-)

package/hooks/observability/pr_description_writer_spawn_tracker.py

@@ -1,113 +0,0 @@
-#!/usr/bin/env python3
-"""PostToolUse hook: record that this session spawned the pr-description-writer agent.
-
-Picture opening a pull request whose body nobody wrote from the diff — it reads
-like a commit message, and the reviewer learns nothing before opening the files.
-The ``pr-description-writer`` agent exists to write that body, and it hands the
-markdown and a body-file path back to the caller to publish.
-
-This hook remembers that the agent ran. After each Agent or Task spawn naming
-``pr-description-writer``, it touches an empty marker file for this session in
-the system temp directory. The ``gh pr create`` gate reads that marker.
-
-The marker carries one fact — the agent ran this session — so a touch records
-everything the gate needs, and two parallel spawns racing on the same touch
-leave the same result. The file name carries the session id, so a marker a
-crashed session leaves behind is inert: no later session reads it.
-
-The hook never blocks a tool call. A tool that is not a spawn, a spawn of
-another agent, a malformed payload, a payload naming no session, or a failed
-touch each returns quietly.
-"""
-
-from __future__ import annotations
-
-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.pr_description_writer_gate_constants import (  # noqa: E402
-    ALL_AGENT_SPAWN_TOOL_NAMES,
-    PR_DESCRIPTION_WRITER_SUBAGENT_TYPE,
-    SUBAGENT_TYPE_FIELD_NAME,
-    TOOL_INPUT_FIELD_NAME,
-    TOOL_NAME_FIELD_NAME,
-)
-from hooks_constants.pr_description_writer_gate_constants import (  # noqa: E402
-    spawn_marker_path as shared_spawn_marker_path,
-)
-from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
-    read_hook_input_dictionary_from_stdin,
-)
-
-
-def spawn_marker_path(session_id: str, temp_directory: Path | None = None) -> Path | None:
-    """Return the marker path for one session, or None without a usable id.
-
-    ::
-
-        session_id = "abc-123"  ->  <temp>/claude-session-pr-description-writer-abc-123.marker
-        session_id = ""         ->  None
-        session_id = "///"      ->  None
-
-    Unsafe characters are stripped so the name stays anchored inside the temp
-    directory. A session id that sanitizes to nothing yields no path, so every
-    marker on disk belongs to one real session and a marker a crashed session
-    leaves behind is inert — no later session reads it.
-
-    Args:
-        session_id: Raw ``session_id`` from the hook payload.
-        temp_directory: The directory holding the marker. Defaults to the
-            system temp directory.
-
-    Returns:
-        Absolute path to this session's marker file, or None when the payload
-        names no session this hook can key on.
-    """
-    return shared_spawn_marker_path(session_id, temp_directory)
-
-
-def _record_spawn(session_id: str) -> None:
-    """Touch this session's marker file, ignoring a write failure.
-
-    Args:
-        session_id: Raw ``session_id`` from the hook payload.
-    """
-    marker_file = spawn_marker_path(session_id)
-    if marker_file is None:
-        return
-    try:
-        marker_file.parent.mkdir(parents=True, exist_ok=True)
-        marker_file.touch(exist_ok=True)
-    except OSError:
-        return
-
-
-def main() -> None:
-    """Record the marker when this payload is a pr-description-writer spawn.
-
-    Reads the PostToolUse payload from stdin and touches this session's marker
-    file when an Agent or Task spawn names the ``pr-description-writer`` agent.
-    Returns on every other branch — another tool, another agent, a malformed
-    payload, or a missing ``tool_input`` — so the spawn is never blocked.
-    """
-    hook_payload = read_hook_input_dictionary_from_stdin()
-    if hook_payload is None:
-        return
-    tool_name = hook_payload.get(TOOL_NAME_FIELD_NAME, "")
-    if tool_name not in ALL_AGENT_SPAWN_TOOL_NAMES:
-        return
-    tool_input = hook_payload.get(TOOL_INPUT_FIELD_NAME, {})
-    if not isinstance(tool_input, dict):
-        return
-    if tool_input.get(SUBAGENT_TYPE_FIELD_NAME) != PR_DESCRIPTION_WRITER_SUBAGENT_TYPE:
-        return
-    session_id = str(hook_payload.get("session_id") or "")
-    _record_spawn(session_id)
-
-
-if __name__ == "__main__":
-    main()

package/hooks/observability/test_pr_description_writer_spawn_tracker.py

@@ -1,150 +0,0 @@
-"""Unit tests for the pr-description-writer spawn tracker PostToolUse hook."""
-
-from __future__ import annotations
-
-import importlib.util
-import io
-import json
-import sys
-from pathlib import Path
-from unittest import mock
-
-import pytest
-
-_OBSERVABILITY_DIRECTORY = Path(__file__).resolve().parent
-_HOOKS_DIRECTORY = _OBSERVABILITY_DIRECTORY.parent
-for each_directory in (_OBSERVABILITY_DIRECTORY, _HOOKS_DIRECTORY):
-    if str(each_directory) not in sys.path:
-        sys.path.insert(0, str(each_directory))
-
-_TRACKER_SPEC = importlib.util.spec_from_file_location(
-    "pr_description_writer_spawn_tracker",
-    _OBSERVABILITY_DIRECTORY / "pr_description_writer_spawn_tracker.py",
-)
-assert _TRACKER_SPEC is not None
-assert _TRACKER_SPEC.loader is not None
-tracker_module = importlib.util.module_from_spec(_TRACKER_SPEC)
-_TRACKER_SPEC.loader.exec_module(tracker_module)
-
-_GATE_CONSTANTS = importlib.import_module(
-    "hooks_constants.pr_description_writer_gate_constants"
-)
-
-_SESSION_ID = "session-abc123"
-_OTHER_SUBAGENT_TYPE = "general-purpose"
-
-
-def _spawn_payload(
-    subagent_type: str,
-    tool_name: str = "Agent",
-    session_id: str = _SESSION_ID,
-) -> dict[str, object]:
-    """Build a PostToolUse payload for one agent spawn.
-
-    Args:
-        subagent_type: The agent type the spawn names.
-        tool_name: The spawning tool name.
-        session_id: The session the spawn belongs to.
-
-    Returns:
-        The payload dictionary the tracker reads from stdin.
-    """
-    return {
-        "tool_name": tool_name,
-        "session_id": session_id,
-        "tool_input": {
-            "subagent_type": subagent_type,
-            "description": "Write the PR body",
-            "prompt": "Write a PR description from the diff.",
-        },
-    }
-
-
-def _run_tracker(payload: dict[str, object], temp_directory: Path) -> None:
-    """Run the tracker's main against a payload with temp redirected.
-
-    Args:
-        payload: The PostToolUse payload to feed on stdin.
-        temp_directory: The directory standing in for the system temp root.
-    """
-    with mock.patch("sys.stdin", io.StringIO(json.dumps(payload))):
-        with mock.patch.object(
-            _GATE_CONSTANTS.tempfile, "gettempdir", return_value=str(temp_directory)
-        ):
-            tracker_module.main()
-
-
-def should_record_marker_when_pr_description_writer_spawns(tmp_path: Path) -> None:
-    """A pr-description-writer spawn leaves this session's marker on disk."""
-    _run_tracker(_spawn_payload(tracker_module.PR_DESCRIPTION_WRITER_SUBAGENT_TYPE), tmp_path)
-    assert tracker_module.spawn_marker_path(_SESSION_ID, tmp_path).exists() is True
-
-
-def should_leave_no_marker_when_another_agent_spawns(tmp_path: Path) -> None:
-    """A spawn of a different agent type records nothing."""
-    _run_tracker(_spawn_payload(_OTHER_SUBAGENT_TYPE), tmp_path)
-    assert tracker_module.spawn_marker_path(_SESSION_ID, tmp_path).exists() is False
-
-
-@pytest.mark.parametrize("spawn_tool_name", ["Agent", "Task"])
-def should_record_marker_for_each_spawn_tool_name(spawn_tool_name: str, tmp_path: Path) -> None:
-    """Both spawning tool names record the marker."""
-    payload = _spawn_payload(
-        tracker_module.PR_DESCRIPTION_WRITER_SUBAGENT_TYPE, tool_name=spawn_tool_name
-    )
-    _run_tracker(payload, tmp_path)
-    assert tracker_module.spawn_marker_path(_SESSION_ID, tmp_path).exists() is True
-
-
-def should_leave_no_marker_for_an_unrelated_tool(tmp_path: Path) -> None:
-    """A tool that is not a spawn records nothing, even naming the agent."""
-    payload = _spawn_payload(tracker_module.PR_DESCRIPTION_WRITER_SUBAGENT_TYPE, tool_name="Bash")
-    _run_tracker(payload, tmp_path)
-    assert tracker_module.spawn_marker_path(_SESSION_ID, tmp_path).exists() is False
-
-
-def should_keep_each_session_marker_separate(tmp_path: Path) -> None:
-    """A spawn in one session leaves another session's marker absent."""
-    payload = _spawn_payload(
-        tracker_module.PR_DESCRIPTION_WRITER_SUBAGENT_TYPE, session_id="session-one"
-    )
-    _run_tracker(payload, tmp_path)
-    assert tracker_module.spawn_marker_path("session-one", tmp_path).exists() is True
-    assert tracker_module.spawn_marker_path("session-two", tmp_path).exists() is False
-
-
-def should_record_twice_without_error(tmp_path: Path) -> None:
-    """A second spawn in one session leaves the marker in place."""
-    payload = _spawn_payload(tracker_module.PR_DESCRIPTION_WRITER_SUBAGENT_TYPE)
-    _run_tracker(payload, tmp_path)
-    _run_tracker(payload, tmp_path)
-    assert tracker_module.spawn_marker_path(_SESSION_ID, tmp_path).exists() is True
-
-
-def should_ignore_a_malformed_payload(tmp_path: Path) -> None:
-    """Unparseable stdin records nothing and raises nothing."""
-    with mock.patch("sys.stdin", io.StringIO("this is not json")):
-        with mock.patch.object(_GATE_CONSTANTS.tempfile, "gettempdir", return_value=str(tmp_path)):
-            tracker_module.main()
-    assert list(tmp_path.iterdir()) == []
-
-
-def should_ignore_a_payload_with_no_tool_input(tmp_path: Path) -> None:
-    """A spawn payload missing tool_input records nothing."""
-    payload: dict[str, object] = {"tool_name": "Agent", "session_id": _SESSION_ID}
-    _run_tracker(payload, tmp_path)
-    assert tracker_module.spawn_marker_path(_SESSION_ID, tmp_path).exists() is False
-
-
-@pytest.mark.parametrize("unusable_session_id", ["", "///"])
-def should_record_nothing_without_a_usable_session_id(
-    unusable_session_id: str, tmp_path: Path
-) -> None:
-    """A payload naming no usable session records no marker at all."""
-    payload = _spawn_payload(
-        tracker_module.PR_DESCRIPTION_WRITER_SUBAGENT_TYPE,
-        session_id=unusable_session_id,
-    )
-    _run_tracker(payload, tmp_path)
-    assert tracker_module.spawn_marker_path(unusable_session_id, tmp_path) is None
-    assert list(tmp_path.iterdir()) == []

package/hooks/session/gh_pr_author_session_cleanup.py

@@ -1,175 +0,0 @@
-#!/usr/bin/env python3
-"""SessionStart hook — sweep stale gh-pr-author swap state files at session start.
-
-The PreToolUse enforcer (``gh_pr_author_enforcer.py``) writes a per-session
-state file recording the original gh CLI account before swapping to
-``GITHUB_DEFAULT_ACCOUNT``. The PostToolUse companion
-(``gh_pr_author_restore.py``) reads that file and switches back when
-``gh pr create`` finishes. When a session is interrupted between the
-swap and the restore — a crash, a downstream PreToolUse deny that fires
-*after* the enforcer's swap completed, or any other path that skips
-PostToolUse — the user is left on ``GITHUB_DEFAULT_ACCOUNT`` with a
-stale state file on disk.
-
-This hook runs at the start of every Claude Code session. When
-``GITHUB_DEFAULT_ACCOUNT`` is set, it scans ``tempfile.gettempdir()``
-for every file matching ``{STATE_FILE_PREFIX}*{STATE_FILE_SUFFIX}``,
-reads the original account from each, runs ``gh auth switch --user
-<original>``, and deletes the file. A state file whose switch fails is
-left in place so the next session can retry. The hook is a strict no-op
-when ``GITHUB_DEFAULT_ACCOUNT`` is unset, so users who have not opted
-into the swap workflow are completely unaffected.
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-import tempfile
-import time
-from pathlib import Path
-
-hooks_parent_directory = str(Path(__file__).resolve().parent.parent)
-if hooks_parent_directory not in sys.path:
-    sys.path.insert(0, hooks_parent_directory)
-
-from _gh_pr_author_swap_utils import (  # noqa: E402
-    _build_restore_failure_message,
-    _delete_state_file,
-    _lstat_indicates_attacker_planted,
-    _read_original_account,
-    _switch_gh_account,
-    _write_line,
-)
-from hooks_constants.gh_pr_author_swap_constants import (  # noqa: E402
-    REQUIRED_ACCOUNT_ENV_VAR,
-    STATE_FILE_PREFIX,
-    STATE_FILE_STALE_AGE_SECONDS,
-    STATE_FILE_SUFFIX,
-)
-
-
-def _collect_stale_state_files(temp_directory: Path) -> list[Path]:
-    """Return swap-state files older than the stale threshold and safe to process.
-
-    A state file younger than ``STATE_FILE_STALE_AGE_SECONDS`` is
-    treated as belonging to a concurrent Claude Code session that may
-    still be mid-``gh pr create``. Sweeping such a file would steal the
-    active session's restore target. Files older than the threshold are
-    overwhelmingly likely to be stale — the enforcer-to-restore window
-    is bounded by the gh subprocess timeouts (10s switch + 5s api user
-    + filesystem work), so any file older than
-    ``STATE_FILE_STALE_AGE_SECONDS`` is past the longest plausible
-    active window.
-
-    Each candidate is also screened for ownership and permission bits
-    matching the enforcer's write contract. A file with mode bits other
-    than ``STATE_FILE_PERMISSION_MODE`` or (on POSIX) owned by a
-    different user is silently skipped — it was not written by an
-    enforcer running as the current user and must not be allowed to
-    drive ``gh auth switch``.
-
-    The candidate is inspected via ``lstat`` rather than ``stat`` so a
-    symlink at the predictable swap-state path is screened on its own
-    metadata, not on whatever the symlink resolves to. Any entry that
-    is not a regular file (symlink, socket, fifo, device) is silently
-    skipped. The enforcer creates state files with ``O_NOFOLLOW``;
-    mirroring that contract here closes the symlink-hijack window where
-    an attacker plants a symlink pointing to a legitimate 0o600 file
-    owned by the current user to trick the cleanup hook into reading
-    that file as a swap-state payload.
-
-    Returned paths are sorted by modification time in ascending order so
-    that when the caller iterates and runs ``gh auth switch`` for each
-    file, the newest stale file is processed LAST. ``gh auth switch``
-    is global state — only the last switch wins — so processing the
-    newest file last leaves the gh CLI on the most recently captured
-    original account when multiple sessions crashed with different
-    original accounts. The single ``lstat`` syscall performed per
-    candidate is reused for both the attacker-planted screen and the
-    mtime ordering key so the sort does not double-stat.
-
-    Args:
-        temp_directory: System temp directory returned by
-            ``tempfile.gettempdir()``.
-
-    Returns:
-        List of swap-state file paths that are regular files whose
-        modification time is older than ``STATE_FILE_STALE_AGE_SECONDS``
-        seconds before now and whose ownership/mode bits match the
-        enforcer's write contract. Sorted by mtime ascending so the
-        newest stale file is last in iteration order. Empty list when
-        the temp directory cannot be listed.
-    """
-    glob_pattern = f"{STATE_FILE_PREFIX}*{STATE_FILE_SUFFIX}"
-    current_time_seconds = time.time()
-    all_stale_candidates_with_mtime: list[tuple[float, Path]] = []
-    try:
-        all_candidate_paths = list(temp_directory.glob(glob_pattern))
-    except OSError:
-        return []
-    for each_candidate_path in all_candidate_paths:
-        try:
-            file_lstat_result = each_candidate_path.lstat()
-        except OSError:
-            continue
-        if _lstat_indicates_attacker_planted(file_lstat_result):
-            continue
-        file_age_seconds = current_time_seconds - file_lstat_result.st_mtime
-        if file_age_seconds >= STATE_FILE_STALE_AGE_SECONDS:
-            all_stale_candidates_with_mtime.append(
-                (file_lstat_result.st_mtime, each_candidate_path)
-            )
-    all_stale_candidates_with_mtime.sort(key=lambda each_mtime_path_pair: each_mtime_path_pair[0])
-    return [each_mtime_path_pair[1] for each_mtime_path_pair in all_stale_candidates_with_mtime]
-
-
-def _restore_stale_state_file(state_file: Path) -> None:
-    """Restore one stale state file: switch back, then delete on success.
-
-    A malformed state file is deleted without a switch attempt. A
-    well-formed file whose switch attempt fails is left on disk so the
-    next session-start can retry.
-
-    Args:
-        state_file: Absolute path to a candidate state file.
-    """
-    original_account = _read_original_account(state_file)
-    if original_account is None:
-        _delete_state_file(state_file)
-        return
-    has_switched_account = _switch_gh_account(original_account)
-    if has_switched_account:
-        _delete_state_file(state_file)
-    else:
-        _write_line(
-            _build_restore_failure_message(
-                "gh-pr-author-cleanup",
-                original_account,
-                state_file,
-                "stale state file",
-            ),
-            sys.stderr,
-        )
-
-
-def main() -> None:
-    """Sweep stale gh-pr-author swap state files when the workflow is enabled.
-
-    Exits 0 in every path. When ``GITHUB_DEFAULT_ACCOUNT`` is unset the
-    hook returns immediately so users who have not opted into the swap
-    workflow see no behavior change. Otherwise iterates every matching
-    state file under ``tempfile.gettempdir()`` and restores each one
-    independently — a failure on one file does not block the others.
-    """
-    required_account = os.environ.get(REQUIRED_ACCOUNT_ENV_VAR, "").strip()
-    if not required_account:
-        return
-    temp_directory = Path(tempfile.gettempdir())
-    all_stale_state_files = _collect_stale_state_files(temp_directory)
-    for each_state_file in all_stale_state_files:
-        _restore_stale_state_file(each_state_file)
-
-
-if __name__ == "__main__":
-    main()