claude-dev-env 1.84.0 → 1.86.0

package/hooks/hooks_constants/session_edit_stage_gate_constants.py

@@ -0,0 +1,92 @@
+"""Constants for the session-edit stage gate hook trio.
+
+Shared by the PostToolUse tracker
+(``hooks/observability/session_file_edit_tracker.py``), the PreToolUse gate
+(``hooks/blocking/session_edit_stage_gate.py``), and the SessionStart cleanup
+(``hooks/session/session_edit_tracker_cleanup.py``): the per-session tracker
+filename shape and JSON payload key, the session-id sanitize pattern, the
+SessionStart source key and the fresh-startup source value the cleanup keys its
+deletion on, the edit-tool name set, the per-session lock filename suffix and
+the lock-acquire timing, the git-diff command and its output encoding, the
+commit-flag escapes the gate honors, the git executable token, the staging
+subcommand tokens, the git global value-option tokens, and the stage-all add
+flag and pathspec tokens that mark a pre-commit ``git add``/``git stage``
+segment as staging the commit, and the deny-message template.
+"""
+
+from __future__ import annotations
+
+import re
+
+SESSION_EDIT_FILE_PREFIX: str = "claude-session-edits-"
+SESSION_EDIT_FILE_SUFFIX: str = ".json"
+ALL_EDITED_FILE_PATHS_KEY: str = "all_edited_file_paths"
+STATE_FILE_DEFAULT_SESSION_ID: str = "default"
+SESSION_ID_UNSAFE_CHARACTERS_PATTERN: re.Pattern[str] = re.compile(r"[^A-Za-z0-9_-]")
+
+SESSION_START_SOURCE_PAYLOAD_KEY: str = "source"
+SESSION_START_SOURCE_FRESH_STARTUP: str = "startup"
+
+ALL_TRACKED_EDIT_TOOL_NAMES: tuple[str, ...] = ("Write", "Edit", "MultiEdit")
+
+STATE_FILE_ATOMIC_WRITE_SUFFIX: str = ".tmp"
+STATE_FILE_JSON_INDENT_SPACES: int = 2
+
+SESSION_EDIT_LOCK_FILE_SUFFIX: str = ".lock"
+LOCK_ACQUIRE_TIMEOUT_SECONDS: float = 5.0
+LOCK_ACQUIRE_RETRY_SECONDS: float = 0.01
+
+GIT_DIFF_TIMEOUT_SECONDS: int = 5
+GIT_DIFF_OUTPUT_ENCODING: str = "utf-8"
+ALL_TRACKED_UNSTAGED_FILES_COMMAND: tuple[str, ...] = (
+    "git",
+    "-c",
+    "core.quotePath=false",
+    "diff",
+    "--name-only",
+)
+
+PARTIAL_COMMIT_BYPASS_MARKER: str = "# partial-commit"
+COMMIT_SUBCOMMAND_TOKEN: str = "commit"
+GIT_EXECUTABLE_TOKEN: str = "git"
+ENV_ASSIGNMENT_PREFIX_PATTERN: re.Pattern[str] = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
+ALL_STAGING_SUBCOMMAND_TOKENS: frozenset[str] = frozenset({"add", "stage"})
+ALL_STAGE_ALL_ADD_FLAG_TOKENS: frozenset[str] = frozenset({"-A", "--all", "-u", "--update"})
+ALL_STAGE_ALL_ADD_PATHSPEC_TOKENS: frozenset[str] = frozenset({".", ":/"})
+ALL_GIT_GLOBAL_VALUE_OPTION_TOKENS: frozenset[str] = frozenset(
+    {"-C", "-c", "--git-dir", "--work-tree", "--namespace", "--exec-path"}
+)
+SHORT_FLAG_PREFIX: str = "-"
+LONG_FLAG_PREFIX: str = "--"
+COMMIT_ALL_SHORT_FLAG_LETTER: str = "a"
+ALL_COMMIT_VALUE_OPTION_SHORT_LETTERS: frozenset[str] = frozenset({"m", "F", "C", "c"})
+ALL_COMMIT_ALL_FLAGS: frozenset[str] = frozenset({"-a", "--all"})
+ALL_COMMIT_VALUE_OPTION_TOKENS: frozenset[str] = frozenset(
+    {
+        "-m",
+        "--message",
+        "-F",
+        "--file",
+        "-C",
+        "--reuse-message",
+        "-c",
+        "--reedit-message",
+        "--author",
+        "--date",
+        "--fixup",
+        "--squash",
+        "--cleanup",
+    }
+)
+ALL_COMMAND_SEPARATOR_TOKENS: frozenset[str] = frozenset({"&&", "||", ";", "|", "&"})
+
+DENY_FILE_BULLET_PREFIX: str = "  - "
+DENY_FILE_BULLET_LINE_SEPARATOR: str = "\n"
+DENY_PATHSPEC_SEPARATOR: str = " "
+SESSION_EDIT_DENY_TEMPLATE: str = (
+    "BLOCKED: these files were edited this session and are tracked but left "
+    "unstaged, so this commit would drop them:\n{file_list}\n"
+    "Stage them with `git add -- {space_joined_paths}`, or run `git commit -a` to "
+    "include every tracked change, or add `{bypass_marker}` to the command to "
+    "commit without them on purpose."
+)

package/hooks/hooks_constants/task_list_loop_starter_constants.py

@@ -0,0 +1,18 @@
+"""Directive text for the task_list_loop_starter SessionStart hook."""
+
+from __future__ import annotations
+
+__all__ = [
+    "TASK_LIST_MAINTENANCE_INSTRUCTION",
+    "TASK_LIST_LOOP_DIRECTIVE",
+]
+
+TASK_LIST_MAINTENANCE_INSTRUCTION = "build or update the task list using the task tools"
+
+TASK_LIST_LOOP_DIRECTIVE = (
+    "TASK LIST MAINTENANCE: Keep this session's task list current on a 10-minute "
+    "cadence. If a task-list maintenance loop is not already running this session, "
+    "start one now with Claude Code's built-in /loop skill on a 10-minute interval: "
+    f'/loop 10m "{TASK_LIST_MAINTENANCE_INSTRUCTION}". Run that instruction once '
+    "immediately, then let the loop refresh the list every 10 minutes."
+)

package/hooks/lifecycle/CLAUDE.md

@@ -7,7 +7,7 @@ Hooks that run at session or config-change boundaries rather than on individual
 | File | Event | What it does |
 |---|---|---|
 | `config_change_guard.py` | PostToolUse (Write/Edit on `settings.json`) | Counts hooks in the edited `settings.json` and logs any change to `~/.claude/cache/config-change-audit.log`; alerts when the hook count drops below the last known value |
-| `pr_converge_bugteam_skill_tracker.py` | PostToolUse | Tracks which bugteam skill runs have completed within a pr-converge loop, so the enforcer can verify parallel execution |
+| `pr_converge_bugteam_skill_tracker.py` | PreToolUse (Skill) | Tracks which bugteam skill runs have completed within a pr-converge loop, so the enforcer can verify parallel execution |
 | `session_end_cleanup.py` | SessionEnd | Purges stale cache entries from `~/.claude/cache/` (entries older than the configured threshold) and old backup files |
 | `test_config_change_guard.py` | — | Tests for `config_change_guard.py` |
 | `test_pr_converge_bugteam_skill_tracker.py` | — | Tests for `pr_converge_bugteam_skill_tracker.py` |

package/hooks/observability/CLAUDE.md

@@ -7,7 +7,9 @@ PostToolUse hooks that record agent behavior for later review. These hooks do no
 | File | Event | What it does |
 |---|---|---|
 | `instructions_loaded_logger.py` | PostToolUse (file load events) | Appends a JSONL record to `~/.claude/logs/instructions_loaded.jsonl` each time Claude Code loads a context file (CLAUDE.md, rules, skills), capturing the file path, load reason, memory type, and session ID |
+| `session_file_edit_tracker.py` | PostToolUse (Write/Edit/MultiEdit) | Records the resolved absolute path of each file edited this session into a per-session JSON file under the system temp directory, for the session edit stage gate to read at commit time |
 | `test_instructions_loaded_logger.py` | — | Tests for `instructions_loaded_logger.py` |
+| `test_session_file_edit_tracker.py` | — | Tests for `session_file_edit_tracker.py` |
 
 ## Conventions
 

package/hooks/observability/session_file_edit_tracker.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""PostToolUse hook: record files edited this session for the stage gate.
+
+Picture finishing a change, running `git commit`, and later finding one file
+never made it in — it was edited but never staged, and the commit dropped it
+silently. This hook prevents that by remembering every file the session
+touches. After each Write, Edit, or MultiEdit it appends the edited file's
+resolved absolute path to a per-session JSON file in the system temp directory,
+which the stage gate reads at commit time. Concurrent invocations — the case
+parallel Write or Edit calls in one turn produce — serialize on a best-effort
+per-session lock file. When the lock cannot be acquired within the timeout, the
+write proceeds without it rather than stalling the edit that triggered the hook.
+
+The hook never blocks a tool call. A non-edit tool, a malformed payload, a
+missing file path, or a failed write each returns quietly, so a logging problem
+never interrupts the edit that triggered it.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import sys
+import tempfile
+import time
+from collections.abc import Iterator
+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.pre_tool_use_stdin import (  # noqa: E402
+    read_hook_input_dictionary_from_stdin,
+)
+from hooks_constants.session_edit_stage_gate_constants import (  # noqa: E402
+    ALL_EDITED_FILE_PATHS_KEY,
+    ALL_TRACKED_EDIT_TOOL_NAMES,
+    LOCK_ACQUIRE_RETRY_SECONDS,
+    LOCK_ACQUIRE_TIMEOUT_SECONDS,
+    SESSION_EDIT_FILE_PREFIX,
+    SESSION_EDIT_FILE_SUFFIX,
+    SESSION_EDIT_LOCK_FILE_SUFFIX,
+    SESSION_ID_UNSAFE_CHARACTERS_PATTERN,
+    STATE_FILE_ATOMIC_WRITE_SUFFIX,
+    STATE_FILE_DEFAULT_SESSION_ID,
+    STATE_FILE_JSON_INDENT_SPACES,
+)
+
+
+def _session_edit_file_path(session_id: str) -> Path:
+    """Return the per-session tracker file path in the system temp directory.
+
+    Args:
+        session_id: Raw ``session_id`` from the hook payload. Unsafe
+            characters are stripped so the value stays anchored inside the
+            temp directory, and an empty result falls back to the default id.
+
+    Returns:
+        Absolute path to this session's tracker file.
+    """
+    sanitized_session_id = SESSION_ID_UNSAFE_CHARACTERS_PATTERN.sub("", session_id)
+    effective_session_id = sanitized_session_id or STATE_FILE_DEFAULT_SESSION_ID
+    file_name = f"{SESSION_EDIT_FILE_PREFIX}{effective_session_id}{SESSION_EDIT_FILE_SUFFIX}"
+    return Path(tempfile.gettempdir()) / file_name
+
+
+def _read_recorded_paths(edit_file: Path) -> list[str]:
+    """Return the file paths already recorded in a tracker file.
+
+    Args:
+        edit_file: Path to this session's tracker file.
+
+    Returns:
+        The recorded absolute paths, or an empty list when the file is
+        absent, unreadable, malformed, or the wrong shape.
+    """
+    try:
+        raw_contents = edit_file.read_text(encoding="utf-8")
+    except (FileNotFoundError, OSError):
+        return []
+    try:
+        parsed_payload = json.loads(raw_contents)
+    except json.JSONDecodeError:
+        return []
+    if not isinstance(parsed_payload, dict):
+        return []
+    recorded_paths = parsed_payload.get(ALL_EDITED_FILE_PATHS_KEY, [])
+    if not isinstance(recorded_paths, list):
+        return []
+    return [each_path for each_path in recorded_paths if isinstance(each_path, str)]
+
+
+def _atomic_write_edit_file(edit_file: Path, all_edited_file_paths: list[str]) -> None:
+    """Write the tracker payload to disk atomically via tempfile plus rename.
+
+    Args:
+        edit_file: Destination tracker file path.
+        all_edited_file_paths: The full deduplicated path list to persist.
+    """
+    parent_directory = edit_file.parent
+    parent_directory.mkdir(parents=True, exist_ok=True)
+    encoded_text = json.dumps(
+        {ALL_EDITED_FILE_PATHS_KEY: all_edited_file_paths},
+        indent=STATE_FILE_JSON_INDENT_SPACES,
+    )
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        encoding="utf-8",
+        dir=str(parent_directory),
+        delete=False,
+        suffix=STATE_FILE_ATOMIC_WRITE_SUFFIX,
+    ) as temporary_handle:
+        temporary_handle.write(encoded_text)
+        temporary_path = Path(temporary_handle.name)
+    try:
+        os.replace(str(temporary_path), str(edit_file))
+    except OSError:
+        temporary_path.unlink(missing_ok=True)
+        raise
+
+
+def _acquire_edit_file_lock(lock_file: Path) -> int | None:
+    """Grab an exclusive per-session lock, spinning until it frees or times out.
+
+    Args:
+        lock_file: Path to this session's lock file.
+
+    Returns:
+        An open file descriptor for the held lock, or None when the lock stayed
+        held past the acquire timeout so the caller proceeds without it rather
+        than stalling the edit that triggered the hook.
+    """
+    lock_acquire_deadline = time.monotonic() + LOCK_ACQUIRE_TIMEOUT_SECONDS
+    while True:
+        try:
+            return os.open(str(lock_file), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            if time.monotonic() >= lock_acquire_deadline:
+                return None
+            time.sleep(LOCK_ACQUIRE_RETRY_SECONDS)
+
+
+@contextlib.contextmanager
+def _hold_edit_file_lock(edit_file: Path) -> Iterator[None]:
+    """Hold the per-session lock across one read-modify-write of the tracker.
+
+    Two PostToolUse invocations run concurrently when Claude issues parallel
+    Write or Edit calls in one turn. Serializing the read-then-write on a shared
+    lock file keeps each invocation's appended path from overwriting another's.
+    The lock is best-effort: when it cannot be acquired within the timeout, the
+    write proceeds without it rather than stalling the edit.
+
+    Args:
+        edit_file: This session's tracker file path.
+
+    Yields:
+        Control to the caller while the lock is held.
+    """
+    lock_file = edit_file.with_name(edit_file.name + SESSION_EDIT_LOCK_FILE_SUFFIX)
+    lock_file.parent.mkdir(parents=True, exist_ok=True)
+    lock_descriptor = _acquire_edit_file_lock(lock_file)
+    try:
+        yield
+    finally:
+        if lock_descriptor is not None:
+            os.close(lock_descriptor)
+            lock_file.unlink(missing_ok=True)
+
+
+def _record_edited_path(session_id: str, resolved_file_path: str) -> None:
+    """Append one edited path to this session's tracker file when it is new.
+
+    The read of the recorded paths and the write back run under a best-effort
+    per-session lock, so parallel invocations do not drop one another's appended
+    path while the lock holds.
+
+    Args:
+        session_id: Raw ``session_id`` from the hook payload.
+        resolved_file_path: The resolved absolute path of the edited file.
+    """
+    edit_file = _session_edit_file_path(session_id)
+    with _hold_edit_file_lock(edit_file):
+        recorded_paths = _read_recorded_paths(edit_file)
+        if resolved_file_path in recorded_paths:
+            return
+        recorded_paths.append(resolved_file_path)
+        try:
+            _atomic_write_edit_file(edit_file, recorded_paths)
+        except OSError:
+            return
+
+
+def main() -> None:
+    """Record the edited file path for a Write, Edit, or MultiEdit.
+
+    Reads the PostToolUse payload from stdin, and for a tracked edit tool
+    appends the resolved absolute file path to this session's tracker file.
+    Returns on every branch — a non-edit tool, a malformed payload, a missing
+    file path, or a failed write — so the tool call is never blocked.
+    """
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        return
+    tool_name = hook_payload.get("tool_name", "")
+    if tool_name not in ALL_TRACKED_EDIT_TOOL_NAMES:
+        return
+    tool_input = hook_payload.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        return
+    file_path = tool_input.get("file_path", "")
+    if not isinstance(file_path, str) or not file_path:
+        return
+    try:
+        resolved_file_path = str(Path(file_path).resolve())
+    except OSError:
+        return
+    session_id = str(hook_payload.get("session_id") or "")
+    _record_edited_path(session_id, resolved_file_path)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/observability/test_session_file_edit_tracker.py

@@ -0,0 +1,174 @@
+"""Behavior tests for the session_file_edit_tracker PostToolUse hook.
+
+The tracker records the resolved absolute file path of every Write, Edit, and
+MultiEdit into a per-session JSON file under the system temp directory. These
+tests drive the hook's ``main`` through real stdin payloads with
+``tempfile.gettempdir`` redirected to a temporary directory, then read the
+JSON file back to confirm what was recorded.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+import io
+import json
+import pathlib
+import sys
+import tempfile
+import threading
+import time
+from typing import Any
+from unittest import mock
+
+import pytest
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+_HOOKS_TREE = _HOOK_DIR.parent
+for each_path in (str(_HOOK_DIR), str(_HOOKS_TREE)):
+    if each_path not in sys.path:
+        sys.path.insert(0, each_path)
+
+hook_spec = importlib.util.spec_from_file_location(
+    "session_file_edit_tracker",
+    _HOOK_DIR / "session_file_edit_tracker.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+
+from hooks_constants.session_edit_stage_gate_constants import (  # noqa: E402
+    ALL_EDITED_FILE_PATHS_KEY,
+    SESSION_EDIT_FILE_PREFIX,
+    SESSION_EDIT_FILE_SUFFIX,
+)
+
+_SESSION_ID = "sessionabc123"
+_CONCURRENT_EDIT_COUNT = 5
+_CONCURRENT_READ_DELAY_SECONDS = 0.05
+
+
+def _run_main_with_stdin(input_text: str) -> None:
+    with (
+        mock.patch("sys.stdin", io.StringIO(input_text)),
+        mock.patch("sys.stdout", new_callable=io.StringIO),
+        contextlib.suppress(SystemExit),
+    ):
+        hook_module.main()
+
+
+@pytest.fixture()
+def redirected_temp_directory(
+    tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
+) -> pathlib.Path:
+    monkeypatch.setattr(tempfile, "gettempdir", lambda: str(tmp_path))
+    return tmp_path
+
+
+def _edit_file_path(temp_directory: pathlib.Path, session_id: str) -> pathlib.Path:
+    return temp_directory / f"{SESSION_EDIT_FILE_PREFIX}{session_id}{SESSION_EDIT_FILE_SUFFIX}"
+
+
+def _read_recorded_paths(temp_directory: pathlib.Path, session_id: str) -> list[str]:
+    edit_file = _edit_file_path(temp_directory, session_id)
+    parsed = json.loads(edit_file.read_text(encoding="utf-8"))
+    return parsed[ALL_EDITED_FILE_PATHS_KEY]
+
+
+def _write_payload(tool_name: str, file_path: pathlib.Path, session_id: str) -> str:
+    payload: dict[str, Any] = {
+        "session_id": session_id,
+        "tool_name": tool_name,
+        "tool_input": {"file_path": str(file_path)},
+    }
+    return json.dumps(payload)
+
+
+def test_should_record_write_tool_edit(redirected_temp_directory: pathlib.Path) -> None:
+    edited_file = redirected_temp_directory / "module_under_edit.py"
+    _run_main_with_stdin(_write_payload("Write", edited_file, _SESSION_ID))
+    recorded = _read_recorded_paths(redirected_temp_directory, _SESSION_ID)
+    assert str(edited_file.resolve()) in recorded
+
+
+def test_should_record_edit_tool_edit(redirected_temp_directory: pathlib.Path) -> None:
+    edited_file = redirected_temp_directory / "module_under_edit.py"
+    _run_main_with_stdin(_write_payload("Edit", edited_file, _SESSION_ID))
+    recorded = _read_recorded_paths(redirected_temp_directory, _SESSION_ID)
+    assert str(edited_file.resolve()) in recorded
+
+
+def test_should_record_multiedit_tool_edit(redirected_temp_directory: pathlib.Path) -> None:
+    edited_file = redirected_temp_directory / "module_under_edit.py"
+    _run_main_with_stdin(_write_payload("MultiEdit", edited_file, _SESSION_ID))
+    recorded = _read_recorded_paths(redirected_temp_directory, _SESSION_ID)
+    assert str(edited_file.resolve()) in recorded
+
+
+def test_should_ignore_bash_tool(redirected_temp_directory: pathlib.Path) -> None:
+    bash_payload = json.dumps(
+        {
+            "session_id": _SESSION_ID,
+            "tool_name": "Bash",
+            "tool_input": {"command": "git status"},
+        }
+    )
+    _run_main_with_stdin(bash_payload)
+    assert not _edit_file_path(redirected_temp_directory, _SESSION_ID).exists()
+
+
+def test_should_deduplicate_repeated_paths(redirected_temp_directory: pathlib.Path) -> None:
+    edited_file = redirected_temp_directory / "module_under_edit.py"
+    _run_main_with_stdin(_write_payload("Write", edited_file, _SESSION_ID))
+    _run_main_with_stdin(_write_payload("Edit", edited_file, _SESSION_ID))
+    recorded = _read_recorded_paths(redirected_temp_directory, _SESSION_ID)
+    assert recorded.count(str(edited_file.resolve())) == 1
+
+
+def test_should_sanitize_unsafe_session_id_in_filename(
+    redirected_temp_directory: pathlib.Path,
+) -> None:
+    unsafe_session_id = "a/../b c"
+    edited_file = redirected_temp_directory / "module_under_edit.py"
+    _run_main_with_stdin(_write_payload("Write", edited_file, unsafe_session_id))
+    sanitized_file = _edit_file_path(redirected_temp_directory, "abc")
+    assert sanitized_file.exists()
+
+
+def test_should_record_every_path_under_concurrent_edits(
+    redirected_temp_directory: pathlib.Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    concurrent_session_id = "concurrentsession"
+    real_read_recorded_paths = hook_module._read_recorded_paths
+
+    def slow_read_recorded_paths(edit_file: pathlib.Path) -> list[str]:
+        recorded_before_delay = real_read_recorded_paths(edit_file)
+        time.sleep(_CONCURRENT_READ_DELAY_SECONDS)
+        return recorded_before_delay
+
+    monkeypatch.setattr(hook_module, "_read_recorded_paths", slow_read_recorded_paths)
+    all_edited_paths = [
+        str((redirected_temp_directory / f"module_{each_index}.py").resolve())
+        for each_index in range(_CONCURRENT_EDIT_COUNT)
+    ]
+    all_threads = [
+        threading.Thread(
+            target=hook_module._record_edited_path,
+            args=(concurrent_session_id, each_path),
+        )
+        for each_path in all_edited_paths
+    ]
+    for each_thread in all_threads:
+        each_thread.start()
+    for each_thread in all_threads:
+        each_thread.join()
+    recorded = _read_recorded_paths(redirected_temp_directory, concurrent_session_id)
+    assert sorted(recorded) == sorted(all_edited_paths)
+
+
+def test_should_exit_zero_on_malformed_stdin(
+    redirected_temp_directory: pathlib.Path,
+) -> None:
+    _run_main_with_stdin("not valid json {{{")
+    assert not any(redirected_temp_directory.iterdir())

package/hooks/session/CLAUDE.md

@@ -1,6 +1,6 @@
 # hooks/session
 
-SessionStart and SessionEnd hooks that manage per-session resources: cleaning up stale directories at startup and pruning plugin data at shutdown.
+SessionStart and SessionEnd hooks for per-session setup and cleanup: removing stale session and plugin-data directories at startup, detecting unregistered repositories, starting the session's task-list maintenance loop, and clearing PR-author swap state at shutdown.
 
 ## Key files
 
@@ -8,11 +8,15 @@ SessionStart and SessionEnd hooks that manage per-session resources: cleaning up
 |---|---|---|
 | `session_env_cleanup.py` | SessionStart | Removes the current session's pre-existing `~/.claude/session-env/<session_id>/` directory and prunes sibling entries older than the stale-age threshold. Prevents `EEXIST` errors from non-recursive `mkdir` calls in the Bash tool on Windows. |
 | `gh_pr_author_session_cleanup.py` | SessionEnd | Clears any PR-author swap state left over from the current session |
-| `plugin_data_dir_cleanup.py` | SessionEnd | Prunes stale plugin data directories |
+| `session_edit_tracker_cleanup.py` | SessionStart, SessionEnd | Deletes the tracker file for the running Claude Code conversation from the system temp directory — at start for a clean slate and at end for a clean exit. A tracker is read only by the conversation that wrote it, so a live idle tracker is kept while a peer cleans up |
+| `plugin_data_dir_cleanup.py` | SessionStart | Removes empty plugin data directories at startup to prevent `EEXIST` when Claude Code recreates them |
 | `untracked_repo_detector.py` | SessionStart | Detects when the session cwd is inside a git repository that is not registered in `~/.claude/project-paths.json` and logs a warning |
+| `task_list_loop_starter.py` | SessionStart | Emits an `additionalContext` directive telling Claude to keep the task list current on a 10-minute cadence, starting the `/loop` skill when one is not already running. Writes nothing and runs no tools itself. |
 | `test_gh_pr_author_session_cleanup.py` | — | Tests for `gh_pr_author_session_cleanup.py` |
+| `test_session_edit_tracker_cleanup.py` | — | Tests for `session_edit_tracker_cleanup.py` |
 | `test_session_env_cleanup.py` | — | Tests for `session_env_cleanup.py` |
 | `test_untracked_repo_detector.py` | — | Tests for `untracked_repo_detector.py` |
+| `test_task_list_loop_starter.py` | — | Tests for `task_list_loop_starter.py` |
 
 ## Conventions
 

package/hooks/session/session_edit_tracker_cleanup.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""SessionStart and SessionEnd hook: clear this session's own tracker file.
+
+The session-edit tracker writes a per-session JSON file under the system temp
+directory, and the stage gate reads only the running session's own file at
+commit time. This hook deletes that file only when the session is genuinely
+beginning or ending: at a fresh SessionStart (a ``startup`` source) so a new
+session begins with an empty record, and at session end so a clean exit leaves
+nothing behind. A SessionStart that continues the same conversation — a compact
+or a resume — keeps the in-flight tracker, so an edit already recorded this
+session survives the continuation.
+
+A tracker file belongs to one session and is read only by that same session, so
+a file a hard-crashed session leaves behind is inert — no other session ever
+reads it. Cleanup keys off the session lifecycle rather than a file's age, so a
+live session that pauses for a long review gap keeps its own tracker: no peer
+session deletes another session's file.
+
+The hook exits zero on every branch and never blocks the session.
+"""
+
+from __future__ import annotations
+
+import sys
+import tempfile
+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.pre_tool_use_stdin import (  # noqa: E402
+    read_hook_input_dictionary_from_stdin,
+)
+from hooks_constants.session_edit_stage_gate_constants import (  # noqa: E402
+    SESSION_EDIT_FILE_PREFIX,
+    SESSION_EDIT_FILE_SUFFIX,
+    SESSION_ID_UNSAFE_CHARACTERS_PATTERN,
+    SESSION_START_SOURCE_FRESH_STARTUP,
+    SESSION_START_SOURCE_PAYLOAD_KEY,
+    STATE_FILE_DEFAULT_SESSION_ID,
+)
+
+
+def _delete_file(target_file: Path) -> None:
+    """Remove a file, ignoring an already-absent file or a delete failure.
+
+    Args:
+        target_file: Path to delete.
+    """
+    try:
+        target_file.unlink()
+    except FileNotFoundError:
+        return
+    except OSError:
+        return
+
+
+def _current_session_file_name(session_id: str) -> str:
+    """Return the tracker file name that belongs to the current session.
+
+    Args:
+        session_id: Raw ``session_id`` from the session-lifecycle payload.
+
+    Returns:
+        The tracker file name for the sanitized session id, falling back to
+        the default id when sanitizing leaves an empty string.
+    """
+    sanitized_session_id = SESSION_ID_UNSAFE_CHARACTERS_PATTERN.sub("", session_id)
+    effective_session_id = sanitized_session_id or STATE_FILE_DEFAULT_SESSION_ID
+    return f"{SESSION_EDIT_FILE_PREFIX}{effective_session_id}{SESSION_EDIT_FILE_SUFFIX}"
+
+
+def _is_tracker_deletion_lifecycle_event(payload_by_field: dict[str, object]) -> bool:
+    """Report whether this lifecycle event should delete the session tracker.
+
+    The ``source`` key rides only on a SessionStart payload. A fresh startup
+    carries the ``startup`` source and a session end carries no source at all,
+    so both delete the tracker. A SessionStart that continues the same
+    conversation carries a non-startup source (a compact or a resume) and keeps
+    the in-flight tracker.
+
+    Args:
+        payload_by_field: The parsed session-lifecycle payload.
+
+    Returns:
+        True when the tracker should be deleted, False when a continuation
+        should keep it.
+    """
+    session_start_source = str(
+        payload_by_field.get(SESSION_START_SOURCE_PAYLOAD_KEY) or ""
+    )
+    if not session_start_source:
+        return True
+    return session_start_source == SESSION_START_SOURCE_FRESH_STARTUP
+
+
+def main() -> None:
+    """Delete the running session's own tracker file at a fresh start or end.
+
+    Reads the session-lifecycle payload from stdin for the session id and
+    deletes that session's tracker file from the system temp directory, unless
+    the payload is a SessionStart that continues the same conversation (a
+    compact or a resume), which keeps the in-flight tracker. A malformed or
+    empty payload is a no-op that deletes nothing. Exits zero on every branch,
+    so the session is never blocked.
+    """
+    payload_by_field = read_hook_input_dictionary_from_stdin()
+    if payload_by_field is None:
+        return
+    if not _is_tracker_deletion_lifecycle_event(payload_by_field):
+        return
+    session_id = str(payload_by_field.get("session_id") or "")
+    temp_directory = Path(tempfile.gettempdir())
+    current_session_file_name = _current_session_file_name(session_id)
+    _delete_file(temp_directory / current_session_file_name)
+
+
+if __name__ == "__main__":
+    main()