claude-dev-env 8.52.0 → 8.53.0

package/_shared/process-tree/scripts/config/process_tree_scripts_constants/process_tree_kill_constants.py

@@ -25,3 +25,15 @@ PROCESS_TREE_KILL_TIMEOUT_SECONDS: int = 10
 Gates the kill command alone. Each caller sets its own bound on the drain that
 follows the kill.
 """
+
+PROCESS_TREE_EXIT_WAIT_SECONDS: float = 2.0
+"""Seconds ``terminate_process_tree`` waits for the signalled POSIX group to exit.
+
+A SIGKILL takes effect when the kernel next schedules each target, so a
+descendant can still run for a moment after ``killpg`` returns. The wait ends
+as soon as no group member is still running; the bound applies only when a
+member survived the signal.
+"""
+
+PROCESS_TREE_EXIT_POLL_SECONDS: float = 0.01
+"""Pause between checks for running members of the signalled process group."""

package/_shared/process-tree/scripts/process_tree_kill.py

@@ -25,6 +25,7 @@ import os
 import signal
 import subprocess
 import sys
+import time
 from pathlib import Path
 
 _config_directory = str(Path(__file__).resolve().parent / "config")
@@ -32,6 +33,8 @@ if _config_directory not in sys.path:
     sys.path.insert(0, _config_directory)
 
 from process_tree_scripts_constants.process_tree_kill_constants import (  # noqa: E402
+    PROCESS_TREE_EXIT_POLL_SECONDS,
+    PROCESS_TREE_EXIT_WAIT_SECONDS,
     PROCESS_TREE_KILL_TIMEOUT_SECONDS,
     WINDOWS_TASKKILL_COMMAND,
     WINDOWS_TASKKILL_FORCE_FLAG,
@@ -126,19 +129,103 @@ def terminate_process_tree(process: subprocess.Popen[str]) -> None:
         tree kill takes            ok:  grandchildren die, pipes close
         tree kill misses the child ok:  Popen.kill() ends the direct child
         child exits mid-kill       ok:  the raised lookup error is swallowed
+        grandchild still running   ok:  returns once the POSIX group has exited
 
     Falls back to ``Popen.kill()`` when the direct child survives the tree kill,
-    so the caller never waits on a live process.
+    so the caller never waits on a live process. On POSIX it then waits, bounded
+    by ``PROCESS_TREE_EXIT_WAIT_SECONDS``, until no group member is running, so
+    a descendant cannot touch files after this call returns.
 
     Args:
         process: The process whose tree is ended.
     """
     if process.poll() is not None:
         return
+    process_group_identifier = _posix_process_group(process.pid)
     kill_process_tree_by_identifier(process.pid)
-    if process.poll() is not None:
-        return
+    if process.poll() is None:
+        try:
+            process.kill()
+        except ProcessLookupError:
+            pass
+    if process_group_identifier is not None:
+        _wait_for_process_group_exit(process, process_group_identifier)
+
+
+def _posix_process_group(process_identifier: int) -> int | None:
+    if sys.platform == "win32":
+        return None
     try:
-        process.kill()
-    except ProcessLookupError:
-        return
+        return os.getpgid(process_identifier)
+    except OSError:
+        return None
+
+
+def _wait_for_process_group_exit(
+    process: subprocess.Popen[str], process_group_identifier: int
+) -> None:
+    """Block until no member of the signalled group is still running, bounded.
+
+    ``killpg`` returns once the signal is queued, and each target dies only when
+    the kernel next schedules it. A grandchild preempted inside a system call
+    finishes that call first, so it can still truncate or write a file after
+    the caller has moved on. Waiting here keeps that work inside the call.
+    """
+    deadline = time.monotonic() + PROCESS_TREE_EXIT_WAIT_SECONDS
+    while running_process_group_members(process, process_group_identifier):
+        if time.monotonic() >= deadline:
+            return
+        time.sleep(PROCESS_TREE_EXIT_POLL_SECONDS)
+
+
+def running_process_group_members(
+    process: subprocess.Popen[str], process_group_identifier: int
+) -> list[int]:
+    """List the process ids in a POSIX group that have not exited yet.
+
+    Reads ``/proc`` where it exists, which tells a running member from a zombie
+    waiting on its reaper. Elsewhere it reaps the direct child and asks the
+    kernel whether the group still has any member.
+
+    Args:
+        process: The direct child that leads the group.
+        process_group_identifier: The group the direct child leads.
+
+    Returns:
+        Process ids still running, or an empty list once the group has exited.
+    """
+    if sys.platform == "win32":
+        return []
+    proc_directory = Path("/proc")
+    if proc_directory.is_dir():
+        return _running_members_from_proc(proc_directory, process_group_identifier)
+    try:
+        process.wait(timeout=PROCESS_TREE_EXIT_POLL_SECONDS)
+    except subprocess.TimeoutExpired:
+        return [process.pid]
+    try:
+        os.killpg(process_group_identifier, 0)
+    except OSError:
+        return []
+    return [process_group_identifier]
+
+
+def _running_members_from_proc(
+    proc_directory: Path, process_group_identifier: int
+) -> list[int]:
+    all_running: list[int] = []
+    for each_entry in proc_directory.iterdir():
+        if not each_entry.name.isdigit():
+            continue
+        try:
+            stat_text = (each_entry / "stat").read_text(
+                encoding="ascii", errors="replace"
+            )
+        except OSError:
+            continue
+        state, _parent_identifier, group_identifier, *_later_fields = stat_text.rsplit(
+            ")", 1
+        )[1].split()
+        if int(group_identifier) == process_group_identifier and state != "Z":
+            all_running.append(int(each_entry.name))
+    return all_running

package/_shared/process-tree/scripts/test_process_tree_kill.py

@@ -7,9 +7,12 @@ the taskkill argv it builds, the failures it swallows, and the
 
 from __future__ import annotations
 
+import os
 import subprocess
 import sys
+import time
 from pathlib import Path
+from typing import cast
 
 import pytest
 
@@ -23,6 +26,8 @@ from process_tree_kill import (  # noqa: E402
     terminate_process_tree,
 )
 from process_tree_scripts_constants.process_tree_kill_constants import (  # noqa: E402
+    PROCESS_TREE_EXIT_POLL_SECONDS,
+    PROCESS_TREE_EXIT_WAIT_SECONDS,
     PROCESS_TREE_KILL_TIMEOUT_SECONDS,
     WINDOWS_TASKKILL_COMMAND,
     WINDOWS_TASKKILL_FORCE_FLAG,
@@ -276,3 +281,147 @@ def test_new_session_is_requested_off_windows_only(
 
     _install_windows_platform(monkeypatch)
     assert process_tree_kill.should_start_new_session() is False
+
+
+def _install_posix_group_wait(
+    monkeypatch: pytest.MonkeyPatch, all_member_snapshots: list[list[int]]
+) -> list[float]:
+    """Script what the group wait sees after the kill, and record each pause.
+
+    The last snapshot repeats once the list runs dry, so a never-empty script
+    models a group that outlives the deadline.
+    """
+    all_sleeps: list[float] = []
+    remaining_snapshots = list(all_member_snapshots)
+
+    def scripted_members(process: object, process_group_identifier: int) -> list[int]:
+        del process, process_group_identifier
+        if len(remaining_snapshots) > 1:
+            return remaining_snapshots.pop(0)
+        return remaining_snapshots[0]
+
+    _install_posix_platform(monkeypatch)
+    monkeypatch.setattr(
+        process_tree_kill.os,
+        "getpgid",
+        lambda process_identifier: FAKE_PROCESS_GROUP_IDENTIFIER,
+        raising=False,
+    )
+    monkeypatch.setattr(
+        process_tree_kill.os,
+        "killpg",
+        lambda group_identifier, signal_number: None,
+        raising=False,
+    )
+    monkeypatch.setattr(
+        process_tree_kill, "running_process_group_members", scripted_members
+    )
+    monkeypatch.setattr(process_tree_kill.time, "sleep", all_sleeps.append)
+    return all_sleeps
+
+
+def test_terminate_waits_until_no_group_member_is_running(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The POSIX kill returns only once the signalled group has emptied.
+
+    ::
+
+        members [7], [7], []  ok:   two pauses, then return
+        no wait               flag: a grandchild still inside a system call
+                                    writes after the caller has moved on
+    """
+    all_sleeps = _install_posix_group_wait(monkeypatch, [[7], [7], []])
+
+    terminate_process_tree(_as_popen(_FakeProcess([None, 0])))
+
+    assert all_sleeps == [PROCESS_TREE_EXIT_POLL_SECONDS] * 2
+
+
+def test_terminate_stops_waiting_at_the_exit_deadline(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A group member that survives the signal does not hold the caller forever."""
+    all_sleeps = _install_posix_group_wait(monkeypatch, [[7]])
+    clock = iter(
+        [0.0, 0.0, PROCESS_TREE_EXIT_WAIT_SECONDS / 2, PROCESS_TREE_EXIT_WAIT_SECONDS]
+    )
+    monkeypatch.setattr(process_tree_kill.time, "monotonic", lambda: next(clock))
+
+    terminate_process_tree(_as_popen(_FakeProcess([None, 0])))
+
+    assert all_sleeps == [PROCESS_TREE_EXIT_POLL_SECONDS] * 2
+
+
+def _as_popen(fake_process: _FakeProcess) -> subprocess.Popen[str]:
+    return cast("subprocess.Popen[str]", fake_process)
+
+
+def _group_led_by(process: subprocess.Popen[str]) -> int:
+    """Name the group a session-leading child owns; Windows has none, so its pid."""
+    if process_tree_kill.should_start_new_session():
+        return os.getpgid(process.pid)
+    return process.pid
+
+
+def test_running_members_leave_out_a_zombie() -> None:
+    """A member that died but awaits its reaper is not running.
+
+    ::
+
+        child sleeping               ok:   listed on POSIX, [] on Windows
+        child killed, not yet reaped ok:   dropped, so the wait ends
+    """
+    sleeper = subprocess.Popen(
+        [sys.executable, "-c", "import time; time.sleep(60)"],
+        start_new_session=process_tree_kill.should_start_new_session(),
+    )
+    group_identifier = _group_led_by(sleeper)
+    all_expected_running = (
+        [sleeper.pid] if process_tree_kill.should_start_new_session() else []
+    )
+    try:
+        assert (
+            process_tree_kill.running_process_group_members(sleeper, group_identifier)
+            == all_expected_running
+        )
+        sleeper.kill()
+        deadline = time.monotonic() + PROCESS_TREE_EXIT_WAIT_SECONDS
+        while process_tree_kill.running_process_group_members(
+            sleeper, group_identifier
+        ):
+            assert time.monotonic() < deadline, "the killed sleeper still counts"
+            time.sleep(PROCESS_TREE_EXIT_POLL_SECONDS)
+    finally:
+        sleeper.wait()
+
+
+def test_terminate_returns_with_the_grandchild_already_gone(tmp_path: Path) -> None:
+    """Right after the kill returns, no process in the child's group still runs."""
+    heartbeat_file = tmp_path / "heartbeat.txt"
+    grandchild_source = (
+        "import pathlib, sys\n"
+        "heartbeat = pathlib.Path(sys.argv[1])\n"
+        "while True:\n"
+        "    heartbeat.write_text('beat', encoding='utf-8')\n"
+    )
+    child_source = (
+        "import subprocess, sys, time\n"
+        "subprocess.Popen([sys.executable, '-c', sys.argv[1], sys.argv[2]])\n"
+        "time.sleep(60)\n"
+    )
+    child = subprocess.Popen(
+        [sys.executable, "-c", child_source, grandchild_source, str(heartbeat_file)],
+        start_new_session=process_tree_kill.should_start_new_session(),
+    )
+    group_identifier = _group_led_by(child)
+    while not heartbeat_file.exists():
+        time.sleep(PROCESS_TREE_EXIT_POLL_SECONDS)
+
+    terminate_process_tree(child)
+    still_running = process_tree_kill.running_process_group_members(
+        child, group_identifier
+    )
+    child.wait()
+
+    assert still_running == []

package/hooks/advisory/auto_mode_denial_quick_fix.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""PermissionDenied advisor: a proposed quick fix for each auto mode denial.
+
+This hook never retries the denied call. It reads the denial, names the
+classifier rule from the bracketed label in ``denial_reason``, drafts one
+``autoMode.allow`` entry for the denied action, and adds a PowerShell 7 block
+that writes the entry to ``~/.claude/settings.json`` with ``"$defaults"``
+kept. The agent receives the proposal as ``additionalContext``; the user
+receives a one-line ``systemMessage``.
+
+A denial with no ``classifier_verdict`` gets a short note and no block,
+because an allow entry cannot clear it.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+_hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if _hooks_root_directory not in sys.path:
+    sys.path.insert(0, _hooks_root_directory)
+
+from hooks_constants.auto_mode_denial_quick_fix_constants import (
+    ALL_COMMAND_INPUT_KEYS,
+    ALLOW_ENTRY_TEMPLATE,
+    HOOK_EVENT_NAME,
+    MAXIMUM_ACTION_SUMMARY_CHARACTERS,
+    NO_VERDICT_CONTEXT_TEMPLATE,
+    POWERSHELL_BLOCK_TEMPLATE,
+    RULE_LABEL_PATTERN,
+    SUMMARY_WORD_SEPARATOR,
+    TRUNCATION_MARKER,
+    UNNAMED_RULE_LABEL,
+    USER_MESSAGE_TEMPLATE,
+    VERDICT_CONTEXT_TEMPLATE,
+)
+
+
+def rule_label_from(denial_reason: str) -> str:
+    """Return the classifier rule name from a denial reason.
+
+    Args:
+        denial_reason: The ``denial_reason`` text, such as
+            ``"[Security Weaken] lowers a guard"``.
+
+    Returns:
+        The first bracketed label, or the unnamed-rule label.
+    """
+    label_match = re.search(RULE_LABEL_PATTERN, denial_reason)
+    return label_match.group(1).strip() if label_match else UNNAMED_RULE_LABEL
+
+
+def _summary_source_text(tool_input: object) -> str:
+    if not isinstance(tool_input, dict):
+        return json.dumps(tool_input, sort_keys=True)
+    for each_key in ALL_COMMAND_INPUT_KEYS:
+        if isinstance(tool_input.get(each_key), str):
+            return tool_input[each_key]
+    return json.dumps(tool_input, sort_keys=True)
+
+
+def action_summary_from(tool_input: object) -> str:
+    """Return one short line that names the denied action.
+
+    Args:
+        tool_input: The denied call's ``tool_input``.
+
+    Returns:
+        The command, URL or path when the input has one, else the compact
+        JSON input, cut to the summary length limit.
+    """
+    single_line_text = SUMMARY_WORD_SEPARATOR.join(_summary_source_text(tool_input).split())
+    if len(single_line_text) <= MAXIMUM_ACTION_SUMMARY_CHARACTERS:
+        return single_line_text
+    kept_length = MAXIMUM_ACTION_SUMMARY_CHARACTERS - len(TRUNCATION_MARKER)
+    return single_line_text[:kept_length] + TRUNCATION_MARKER
+
+
+def powershell_block_for(allow_entry: str) -> str:
+    """Return the PowerShell 7 block that adds one allow entry.
+
+    Args:
+        allow_entry: The ``autoMode.allow`` entry text.
+
+    Returns:
+        The block, with the entry in a single-quoted PowerShell literal.
+    """
+    escaped_entry = allow_entry.replace("'", "''")
+    return POWERSHELL_BLOCK_TEMPLATE.replace("{escaped_entry}", escaped_entry)
+
+
+def _verdict_context_text(
+    tool_name: str, denial_reason: str, action_summary: str, rule_label: str
+) -> str:
+    allow_entry = ALLOW_ENTRY_TEMPLATE.format(
+        rule_label=rule_label,
+        tool_name=tool_name,
+        action_summary=action_summary,
+    )
+    return VERDICT_CONTEXT_TEMPLATE.format(
+        tool_name=tool_name,
+        rule_label=rule_label,
+        denial_reason=denial_reason,
+        action_summary=action_summary,
+        powershell_block=powershell_block_for(allow_entry),
+    )
+
+
+def build_hook_output(all_denial_fields: dict[str, object]) -> dict[str, object]:
+    """Return the PermissionDenied hook output for one denial payload.
+
+    Args:
+        all_denial_fields: The hook input JSON.
+
+    Returns:
+        A ``hookSpecificOutput`` with ``additionalContext`` for the agent and
+        a top-level ``systemMessage`` for the user.
+    """
+    tool_name = str(all_denial_fields.get("tool_name") or "tool")
+    denial_reason = str(all_denial_fields.get("denial_reason") or "")
+    action_summary = action_summary_from(all_denial_fields.get("tool_input"))
+    rule_label = rule_label_from(denial_reason)
+    if all_denial_fields.get("classifier_verdict"):
+        context_text = _verdict_context_text(tool_name, denial_reason, action_summary, rule_label)
+    else:
+        context_text = NO_VERDICT_CONTEXT_TEMPLATE.format(
+            tool_name=tool_name,
+            denial_reason=denial_reason,
+            action_summary=action_summary,
+        )
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": HOOK_EVENT_NAME,
+            "additionalContext": context_text,
+        },
+        "systemMessage": USER_MESSAGE_TEMPLATE.format(tool_name=tool_name, rule_label=rule_label),
+    }
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0
+    if not isinstance(payload, dict):
+        return 0
+    sys.stdout.write(json.dumps(build_hook_output(payload)))
+    sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/advisory/test_auto_mode_denial_quick_fix.py

@@ -0,0 +1,113 @@
+"""Behavior tests for the auto mode denial quick-fix advisor."""
+
+from __future__ import annotations
+
+import io
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+advisory_directory = str(Path(__file__).resolve().parent)
+if advisory_directory not in sys.path:
+    sys.path.insert(0, advisory_directory)
+import auto_mode_denial_quick_fix
+
+
+def _denial_payload(**overrides: object) -> dict[str, object]:
+    payload: dict[str, object] = {
+        "hook_event_name": "PermissionDenied",
+        "tool_name": "mcp__github__resolve_review_thread",
+        "tool_input": {"threadId": "PRRT_abc"},
+        "denial_reason": "[Security Weaken] resolving review threads bypasses review",
+        "classifier_verdict": "deny",
+    }
+    payload.update(overrides)
+    return payload
+
+
+def test_should_name_the_bracketed_rule() -> None:
+    assert (
+        auto_mode_denial_quick_fix.rule_label_from("[Git Destructive] force") == "Git Destructive"
+    )
+
+
+def test_should_fall_back_when_the_reason_has_no_label() -> None:
+    assert auto_mode_denial_quick_fix.rule_label_from("Blocked by classifier") == "unnamed rule"
+
+
+def test_should_summarize_a_bash_call_by_its_command() -> None:
+    summary = auto_mode_denial_quick_fix.action_summary_from(
+        {"command": "git push\n --force origin x"}
+    )
+    assert summary == "git push --force origin x"
+
+
+def test_should_cut_a_long_summary_to_the_limit() -> None:
+    summary = auto_mode_denial_quick_fix.action_summary_from({"command": "x" * 500})
+    assert len(summary) == 160
+    assert summary.endswith("...")
+
+
+def test_should_escape_single_quotes_in_the_powershell_entry() -> None:
+    block = auto_mode_denial_quick_fix.powershell_block_for("it's allowed")
+    assert "$entry = 'it''s allowed'" in block
+    assert "$allowList.Add('$defaults')" in block
+
+
+def test_should_propose_rule_entry_and_block_for_a_classifier_denial() -> None:
+    hook_output = auto_mode_denial_quick_fix.build_hook_output(_denial_payload())
+    context_text = hook_output["hookSpecificOutput"]["additionalContext"]
+    assert "rule [Security Weaken]" in context_text
+    assert (
+        "Security Weaken exception: mcp__github__resolve_review_thread calls like" in context_text
+    )
+    assert "```powershell" in context_text
+    assert "retry" not in hook_output["hookSpecificOutput"]
+    assert hook_output["systemMessage"].startswith(
+        "Auto mode blocked mcp__github__resolve_review_thread"
+    )
+
+
+def test_should_omit_the_block_when_no_verdict_exists() -> None:
+    payload = _denial_payload(denial_reason="classifier unavailable")
+    del payload["classifier_verdict"]
+    context_text = auto_mode_denial_quick_fix.build_hook_output(payload)["hookSpecificOutput"][
+        "additionalContext"
+    ]
+    assert "no classifier verdict" in context_text
+    assert "powershell" not in context_text
+
+
+def test_should_print_the_output_from_stdin(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(_denial_payload())))
+    assert auto_mode_denial_quick_fix.main() == 0
+    assert (
+        json.loads(capsys.readouterr().out)["hookSpecificOutput"]["hookEventName"]
+        == "PermissionDenied"
+    )
+
+
+def test_should_stay_quiet_on_malformed_input(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(sys, "stdin", io.StringIO("not json"))
+    assert auto_mode_denial_quick_fix.main() == 0
+    assert capsys.readouterr().out == ""
+
+
+def test_should_write_the_entry_with_defaults_when_powershell_runs(tmp_path: Path) -> None:
+    block = (
+        auto_mode_denial_quick_fix.powershell_block_for("it's allowed")
+        .replace("claude auto-mode config", "")
+        .replace("Join-Path $HOME", f"Join-Path '{tmp_path}'")
+    )
+    subprocess.run(["pwsh", "-NoProfile", "-Command", block], check=True)
+    written_settings = json.loads(
+        (tmp_path / ".claude" / "settings.json").read_text(encoding="utf-8")
+    )
+    assert written_settings["autoMode"]["allow"] == ["$defaults", "it's allowed"]

package/hooks/hooks.json

@@ -335,6 +335,18 @@
           }
         ]
       }
+    ],
+    "PermissionDenied": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/advisory/auto_mode_denial_quick_fix.py",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/hooks_constants/auto_mode_denial_quick_fix_constants.py

@@ -0,0 +1,79 @@
+"""Constants for the auto mode denial quick-fix advisor.
+
+The advisor is a PermissionDenied hook. It never retries the call. It turns
+each auto mode denial into a proposed fix: the rule name, a draft
+``autoMode.allow`` entry, and a PowerShell 7 block that adds the entry to
+``~/.claude/settings.json`` with ``"$defaults"`` kept in the list.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "HOOK_EVENT_NAME",
+    "RULE_LABEL_PATTERN",
+    "UNNAMED_RULE_LABEL",
+    "MAXIMUM_ACTION_SUMMARY_CHARACTERS",
+    "TRUNCATION_MARKER",
+    "SUMMARY_WORD_SEPARATOR",
+    "ALL_COMMAND_INPUT_KEYS",
+    "ALLOW_ENTRY_TEMPLATE",
+    "POWERSHELL_BLOCK_TEMPLATE",
+    "VERDICT_CONTEXT_TEMPLATE",
+    "NO_VERDICT_CONTEXT_TEMPLATE",
+    "USER_MESSAGE_TEMPLATE",
+]
+
+HOOK_EVENT_NAME = "PermissionDenied"
+RULE_LABEL_PATTERN = r"\[([^\]]+)\]"
+UNNAMED_RULE_LABEL = "unnamed rule"
+MAXIMUM_ACTION_SUMMARY_CHARACTERS = 160
+TRUNCATION_MARKER = "..."
+SUMMARY_WORD_SEPARATOR = " "
+ALL_COMMAND_INPUT_KEYS = ("command", "url", "file_path", "path")
+
+ALLOW_ENTRY_TEMPLATE = (
+    "{rule_label} exception: {tool_name} calls like `{action_summary}` "
+    "are allowed when they serve the task the user gave."
+)
+
+POWERSHELL_BLOCK_TEMPLATE = """\
+$settingsPath = Join-Path $HOME '.claude/settings.json'
+New-Item -ItemType Directory -Force -Path (Split-Path $settingsPath) | Out-Null
+$settings = if (Test-Path $settingsPath) { Get-Content -Raw $settingsPath | ConvertFrom-Json -AsHashtable } else { @{} }
+if (-not $settings.ContainsKey('autoMode')) { $settings['autoMode'] = @{} }
+$allowList = [System.Collections.Generic.List[string]]::new()
+if ($settings['autoMode'].ContainsKey('allow')) { $allowList.AddRange([string[]]@($settings['autoMode']['allow'])) } else { $allowList.Add('$defaults') }
+$entry = '{escaped_entry}'
+if ($allowList -notcontains $entry) { $allowList.Add($entry) }
+$settings['autoMode']['allow'] = $allowList.ToArray()
+$settings | ConvertTo-Json -Depth 32 | Set-Content -Encoding utf8NoBOM $settingsPath
+claude auto-mode config"""
+
+VERDICT_CONTEXT_TEMPLATE = """\
+=== AUTO MODE DENIAL QUICK FIX ===
+Auto mode denied {tool_name} under rule [{rule_label}].
+Denial reason: {denial_reason}
+Denied action: {action_summary}
+
+In your next message to the user, propose these two fixes. Do not retry and do not run the block yourself.
+1. One-off: the user replies with a message that names this exact action and its target; then you retry once.
+2. Lasting: the user runs this PowerShell 7 block on their machine. It adds one autoMode.allow entry to ~/.claude/settings.json and keeps "$defaults". Narrow the entry text to this action before you send it.
+
+```powershell
+{powershell_block}
+```
+
+For cloud sessions, the same entry must land in the ~/.claude/settings.json that the session's setup installs.
+Read the rule wording with: claude auto-mode defaults --label '{rule_label}'"""
+
+NO_VERDICT_CONTEXT_TEMPLATE = """\
+=== AUTO MODE DENIAL QUICK FIX ===
+Auto mode denied {tool_name} with no classifier verdict.
+Denial reason: {denial_reason}
+Denied action: {action_summary}
+
+An autoMode.allow entry cannot clear a denial with no verdict. Tell the user the action and the reason, and ask them to run it themselves or to retry it later."""
+
+USER_MESSAGE_TEMPLATE = (
+    "Auto mode blocked {tool_name} [{rule_label}]. Claude will propose a quick fix."
+)

package/package.json

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

package/scripts/account_broker_support.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import dataclasses
 import errno
+import importlib
 import json
 import os
 import shutil
@@ -63,6 +64,16 @@ from dev_env_scripts_constants.codex_account_constants import (
     WEEKLY_WINDOW_MINUTES,
 )
 from dev_env_scripts_constants.shared_tree_constants import CLAUDE_CONFIG_DIR_ENV_VAR
+from shared_tree_paths import resolve_shared_process_tree_scripts_directory
+
+_shared_process_tree_scripts_directory = resolve_shared_process_tree_scripts_directory(
+    __file__,
+    all_environment=os.environ,
+)
+if str(_shared_process_tree_scripts_directory) not in sys.path:
+    sys.path.insert(0, str(_shared_process_tree_scripts_directory))
+
+_process_tree_kill = importlib.import_module("process_tree_kill")
 
 
 def _read_list(path: Path) -> object:
@@ -492,21 +503,26 @@ def _run_captured_subprocess(all_argv: Sequence[str], **options: object) -> subp
     errors = str(options.get("errors") or "replace")
     stdin_bytes = options.get("input")
     with tempfile.TemporaryFile() as stdout_file, tempfile.TemporaryFile() as stderr_file:
-        completion = subprocess.run(
+        with subprocess.Popen(
             _resolve_command(all_argv),
-            input=stdin_bytes,
+            stdin=subprocess.PIPE if stdin_bytes is not None else None,
             stdout=stdout_file,
             stderr=stderr_file,
             env=options.get("env"),
             cwd=options.get("cwd"),
-            timeout=options.get("timeout"),
-            check=False,
-        )
+            start_new_session=_process_tree_kill.should_start_new_session(),
+        ) as process:
+            try:
+                process.communicate(input=stdin_bytes, timeout=options.get("timeout"))
+            except (subprocess.TimeoutExpired, KeyboardInterrupt):
+                _process_tree_kill.terminate_process_tree(process)
+                process.wait()
+                raise
         stdout_file.seek(0)
         stderr_file.seek(0)
         stdout = stdout_file.read().decode(encoding, errors).replace("\r\n", "\n").replace("\r", "\n")
         stderr = stderr_file.read().decode(encoding, errors).replace("\r\n", "\n").replace("\r", "\n")
-    return subprocess.CompletedProcess(list(all_argv), completion.returncode, stdout, stderr)
+    return subprocess.CompletedProcess(list(all_argv), process.returncode, stdout, stderr)
 
 
 subprocess_runner: SubprocessRunner = _run_captured_subprocess

package/scripts/test_account_broker_support.py

@@ -5,6 +5,8 @@ import json
 import os
 import shutil
 import subprocess
+import sys
+import time
 from datetime import datetime, timezone
 from pathlib import Path
 from types import SimpleNamespace
@@ -222,16 +224,85 @@ def test_should_raise_windows_lock_error_other_than_contention(tmp_path: Path) -
     assert all_calls == [lock_descriptor]
 
 
-def test_should_launch_the_path_resolved_command_file(monkeypatch: pytest.MonkeyPatch) -> None:
-    resolved_command = r"C:\Users\someone\AppData\Roaming\npm\claude.cmd"
-    monkeypatch.setattr(shutil, "which", lambda name: resolved_command if name == "claude" else None)
+GRANDCHILD_HEARTBEAT_SCRIPT = (
+    "import pathlib, sys, time\n"
+    "heartbeat = pathlib.Path(sys.argv[1])\n"
+    "for each_beat in range(300):\n"
+    "    heartbeat.write_text(str(each_beat), encoding='utf-8')\n"
+    "    time.sleep(0.1)\n"
+)
+
+CHILD_SCRIPT = (
+    "import subprocess, sys, time\n"
+    "subprocess.Popen([sys.executable, '-c', sys.argv[1], sys.argv[2]])\n"
+    "time.sleep(60)\n"
+)
+
+
+def test_should_end_grandchildren_when_the_job_times_out(tmp_path: Path) -> None:
+    heartbeat_file = tmp_path / "heartbeat.txt"
+
+    with pytest.raises(subprocess.TimeoutExpired):
+        support._run_captured_subprocess(
+            [sys.executable, "-c", CHILD_SCRIPT, GRANDCHILD_HEARTBEAT_SCRIPT, str(heartbeat_file)],
+            timeout=5,
+        )
+
+    beat_after_timeout = heartbeat_file.read_text(encoding="utf-8")
+    time.sleep(0.5)
+    assert heartbeat_file.read_text(encoding="utf-8") == beat_after_timeout
+
+
+def test_should_end_grandchildren_when_the_broker_is_interrupted(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    heartbeat_file = tmp_path / "heartbeat.txt"
+    original_communicate = subprocess.Popen.communicate
+
+    def interrupted_communicate(process: subprocess.Popen[bytes], *args: object, **kwargs: object) -> object:
+        try:
+            return original_communicate(process, *args, timeout=5)
+        except subprocess.TimeoutExpired:
+            raise KeyboardInterrupt from None
+
+    monkeypatch.setattr(subprocess.Popen, "communicate", interrupted_communicate)
+
+    with pytest.raises(KeyboardInterrupt):
+        support._run_captured_subprocess(
+            [sys.executable, "-c", CHILD_SCRIPT, GRANDCHILD_HEARTBEAT_SCRIPT, str(heartbeat_file)],
+        )
+
+    beat_after_interrupt = heartbeat_file.read_text(encoding="utf-8")
+    time.sleep(0.5)
+    assert heartbeat_file.read_text(encoding="utf-8") == beat_after_interrupt
+
+
+def _record_launches(monkeypatch: pytest.MonkeyPatch) -> list[list[str]]:
     all_launched_argv: list[list[str]] = []
 
-    def fake_run(all_argv: list[str], **options: object) -> subprocess.CompletedProcess[bytes]:
-        all_launched_argv.append(list(all_argv))
-        return subprocess.CompletedProcess(all_argv, 0)
+    class FakeProcess:
+        returncode = 0
+
+        def __init__(self, all_argv: list[str], **options: object) -> None:
+            all_launched_argv.append(list(all_argv))
+
+        def __enter__(self) -> "FakeProcess":
+            return self
+
+        def __exit__(self, *exception_info: object) -> None:
+            return None
 
-    monkeypatch.setattr(support.subprocess, "run", fake_run)
+        def communicate(self, **options: object) -> tuple[None, None]:
+            return None, None
+
+    monkeypatch.setattr(support.subprocess, "Popen", FakeProcess)
+    return all_launched_argv
+
+
+def test_should_launch_the_path_resolved_command_file(monkeypatch: pytest.MonkeyPatch) -> None:
+    resolved_command = r"C:\Users\someone\AppData\Roaming\npm\claude.cmd"
+    monkeypatch.setattr(shutil, "which", lambda name: resolved_command if name == "claude" else None)
+    all_launched_argv = _record_launches(monkeypatch)
 
     completion = support.subprocess_runner(["claude", "-p"], input=b"", encoding="utf-8", errors="replace")
 
@@ -241,7 +312,7 @@ def test_should_launch_the_path_resolved_command_file(monkeypatch: pytest.Monkey
 
 def test_should_refuse_to_launch_a_bare_command_missing_from_path(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(shutil, "which", lambda name: None)
-    monkeypatch.setattr(support.subprocess, "run", lambda *arguments, **options: pytest.fail("a missing command ran"))
+    monkeypatch.setattr(support.subprocess, "Popen", lambda *arguments, **options: pytest.fail("a missing command ran"))
 
     with pytest.raises(FileNotFoundError) as raised:
         support.subprocess_runner(["claude", "-p"])
@@ -256,7 +327,7 @@ def test_should_refuse_a_batch_file_argument_that_cmd_would_parse(
 ) -> None:
     resolved_command = r"C:\Users\someone\AppData\Roaming\npm\claude.cmd"
     monkeypatch.setattr(shutil, "which", lambda name: resolved_command)
-    monkeypatch.setattr(support.subprocess, "run", lambda *arguments, **options: pytest.fail("a batch file ran"))
+    monkeypatch.setattr(support.subprocess, "Popen", lambda *arguments, **options: pytest.fail("a batch file ran"))
 
     with pytest.raises(OSError) as raised:
         support.subprocess_runner(["claude", "-p", f"fix{metacharacter}test"])
@@ -269,7 +340,7 @@ def test_should_refuse_a_batch_file_argument_that_cmd_would_parse(
 def test_should_refuse_metacharacters_for_an_uppercase_bat_extension(monkeypatch: pytest.MonkeyPatch) -> None:
     resolved_command = r"C:\tools\CLAUDE.BAT"
     monkeypatch.setattr(shutil, "which", lambda name: resolved_command)
-    monkeypatch.setattr(support.subprocess, "run", lambda *arguments, **options: pytest.fail("a batch file ran"))
+    monkeypatch.setattr(support.subprocess, "Popen", lambda *arguments, **options: pytest.fail("a batch file ran"))
 
     with pytest.raises(OSError) as raised:
         support.subprocess_runner(["claude", "a & b"])
@@ -280,13 +351,7 @@ def test_should_refuse_metacharacters_for_an_uppercase_bat_extension(monkeypatch
 def test_should_launch_a_batch_file_with_flags_only(monkeypatch: pytest.MonkeyPatch) -> None:
     resolved_command = r"C:\Users\someone\AppData\Roaming\npm\claude.cmd"
     monkeypatch.setattr(shutil, "which", lambda name: resolved_command)
-    all_launched_argv: list[list[str]] = []
-
-    def fake_run(all_argv: list[str], **options: object) -> subprocess.CompletedProcess[bytes]:
-        all_launched_argv.append(list(all_argv))
-        return subprocess.CompletedProcess(all_argv, 0)
-
-    monkeypatch.setattr(support.subprocess, "run", fake_run)
+    all_launched_argv = _record_launches(monkeypatch)
 
     support.subprocess_runner(["claude", "-p", "--output-format", "json", "--model", "opus"], input=b"a & b")
 
@@ -296,13 +361,7 @@ def test_should_launch_a_batch_file_with_flags_only(monkeypatch: pytest.MonkeyPa
 def test_should_pass_metacharacters_to_an_executable_unchanged(monkeypatch: pytest.MonkeyPatch) -> None:
     resolved_command = "/usr/local/bin/claude"
     monkeypatch.setattr(shutil, "which", lambda name: resolved_command)
-    all_launched_argv: list[list[str]] = []
-
-    def fake_run(all_argv: list[str], **options: object) -> subprocess.CompletedProcess[bytes]:
-        all_launched_argv.append(list(all_argv))
-        return subprocess.CompletedProcess(all_argv, 0)
-
-    monkeypatch.setattr(support.subprocess, "run", fake_run)
+    all_launched_argv = _record_launches(monkeypatch)
 
     support.subprocess_runner(["claude", "-p", 'say "a & b" | 100%!'])