claude-dev-env 8.103.1 → 8.104.0

package/hooks/blocking/test_wakeup_cap_gate.py

@@ -0,0 +1,280 @@
+import io
+import json
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import pytest
+
+import wakeup_cap_gate
+
+SEND_LATER_TOOL = "mcp__claude-code-remote__send_later"
+CREATE_TRIGGER_TOOL = "mcp__claude-code-remote__create_trigger"
+UPDATE_TRIGGER_TOOL = "mcp__claude-code-remote__update_trigger"
+
+
+def run_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tool_name: str,
+    tool_input: dict[str, object],
+) -> tuple[int, str, str]:
+    hook_input = {"hook_event_name": "PreToolUse", "tool_name": tool_name, "tool_input": tool_input}
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    exit_code = wakeup_cap_gate.main()
+    captured = capsys.readouterr()
+    return exit_code, captured.out, captured.err
+
+
+def updated_input_of(stdout_text: str) -> dict[str, object]:
+    payload = json.loads(stdout_text)
+    hook_output = payload["hookSpecificOutput"]
+    assert hook_output["permissionDecision"] == "allow"
+    return hook_output["updatedInput"]
+
+
+def utc_text(moment: datetime) -> str:
+    return moment.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def minutes_from_now(minutes: float) -> datetime:
+    return datetime.now(timezone.utc) + timedelta(minutes=minutes)
+
+
+@pytest.fixture(autouse=True)
+def isolated_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+
+
+@pytest.mark.parametrize("requested_minutes", [58, 59, 60])
+def test_send_later_at_the_cache_edge_is_rewritten_to_the_step_down(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], requested_minutes: int
+) -> None:
+    tool_input = {"delay_minutes": requested_minutes, "message": "check in", "name": "probe"}
+    exit_code, stdout_text, _ = run_gate(monkeypatch, capsys, SEND_LATER_TOOL, tool_input)
+    assert exit_code == 0
+    assert updated_input_of(stdout_text) == {
+        "delay_minutes": 57,
+        "message": "check in",
+        "name": "probe",
+    }
+
+
+@pytest.mark.parametrize("requested_minutes", [1, 45, 57])
+def test_send_later_under_the_step_down_passes_untouched(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], requested_minutes: int
+) -> None:
+    exit_code, stdout_text, stderr_text = run_gate(
+        monkeypatch, capsys, SEND_LATER_TOOL, {"delay_minutes": requested_minutes, "message": "x"}
+    )
+    assert (exit_code, stdout_text, stderr_text) == (0, "", "")
+
+
+def test_send_later_over_an_hour_is_refused_with_the_stacking_instruction(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stdout_text, stderr_text = run_gate(
+        monkeypatch, capsys, SEND_LATER_TOOL, {"delay_minutes": 90, "message": "x"}
+    )
+    assert exit_code == 2
+    assert stdout_text == ""
+    assert "delay_minutes=57" in stderr_text
+    assert "delaySeconds=3480" in stderr_text
+    assert "stack" in stderr_text
+
+
+def test_send_later_at_inside_the_cache_edge_is_rewritten(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stdout_text, _ = run_gate(
+        monkeypatch,
+        capsys,
+        SEND_LATER_TOOL,
+        {"at": utc_text(minutes_from_now(59.5)), "message": "x"},
+    )
+    assert exit_code == 0
+    rewritten_at = datetime.fromisoformat(
+        str(updated_input_of(stdout_text)["at"]).replace("Z", "+00:00")
+    )
+    assert rewritten_at <= minutes_from_now(57)
+    assert rewritten_at >= minutes_from_now(56)
+
+
+def test_send_later_at_two_hours_out_is_refused(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        SEND_LATER_TOOL,
+        {"at": utc_text(minutes_from_now(120)), "message": "x"},
+    )
+    assert exit_code == 2
+    assert "stack" in stderr_text
+
+
+@pytest.mark.parametrize(("requested_seconds", "allowed_seconds"), [(3500, 3480), (3600, 3480)])
+def test_schedule_wakeup_at_the_cache_edge_is_rewritten(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    requested_seconds: int,
+    allowed_seconds: int,
+) -> None:
+    tool_input = {"delaySeconds": requested_seconds, "prompt": "/loop tick", "reason": "r"}
+    exit_code, stdout_text, _ = run_gate(monkeypatch, capsys, "ScheduleWakeup", tool_input)
+    assert exit_code == 0
+    assert updated_input_of(stdout_text)["delaySeconds"] == allowed_seconds
+    assert updated_input_of(stdout_text)["prompt"] == "/loop tick"
+
+
+@pytest.mark.parametrize("requested_seconds", [60, 1800, 3480])
+def test_schedule_wakeup_under_the_step_down_passes(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], requested_seconds: int
+) -> None:
+    exit_code, stdout_text, _ = run_gate(
+        monkeypatch, capsys, "ScheduleWakeup", {"delaySeconds": requested_seconds, "prompt": "p"}
+    )
+    assert (exit_code, stdout_text) == (0, "")
+
+
+def test_schedule_wakeup_over_an_hour_is_refused(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _, stderr_text = run_gate(
+        monkeypatch, capsys, "ScheduleWakeup", {"delaySeconds": 5400, "prompt": "p"}
+    )
+    assert exit_code == 2
+    assert "delaySeconds=3480" in stderr_text
+
+
+def test_create_trigger_run_once_at_the_hour_is_rewritten(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    tool_input = {
+        "name": "n",
+        "prompt": "p",
+        "initiation": "own_followup",
+        "run_once_at": utc_text(minutes_from_now(60)),
+    }
+    exit_code, stdout_text, _ = run_gate(monkeypatch, capsys, CREATE_TRIGGER_TOOL, tool_input)
+    assert exit_code == 0
+    rewritten_at = datetime.fromisoformat(
+        str(updated_input_of(stdout_text)["run_once_at"]).replace("Z", "+00:00")
+    )
+    assert rewritten_at <= minutes_from_now(57)
+
+
+@pytest.mark.parametrize(
+    "cron_expression", ["0 * * * *", "0 */4 * * *", "CRON_TZ=America/Los_Angeles 37 8 * * 1-5"]
+)
+def test_create_trigger_cron_into_a_session_is_refused(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], cron_expression: str
+) -> None:
+    tool_input = {
+        "name": "n",
+        "prompt": "p",
+        "initiation": "own_followup",
+        "cron_expression": cron_expression,
+    }
+    exit_code, _, stderr_text = run_gate(monkeypatch, capsys, CREATE_TRIGGER_TOOL, tool_input)
+    assert exit_code == 2
+    assert cron_expression in stderr_text
+
+
+def test_create_trigger_with_a_fresh_session_per_firing_passes(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    tool_input = {
+        "name": "n",
+        "prompt": "p",
+        "initiation": "human_request",
+        "cron_expression": "0 9 * * *",
+        "create_new_session_on_fire": True,
+    }
+    exit_code, stdout_text, _ = run_gate(monkeypatch, capsys, CREATE_TRIGGER_TOOL, tool_input)
+    assert (exit_code, stdout_text) == (0, "")
+
+
+def test_update_trigger_run_once_at_over_an_hour_is_refused(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    tool_input = {"trigger_id": "trig_x", "run_once_at": utc_text(minutes_from_now(90))}
+    exit_code, _, _ = run_gate(monkeypatch, capsys, UPDATE_TRIGGER_TOOL, tool_input)
+    assert exit_code == 2
+
+
+def test_update_trigger_cron_change_passes(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    tool_input = {"trigger_id": "trig_x", "cron_expression": "0 9 * * *"}
+    exit_code, stdout_text, _ = run_gate(monkeypatch, capsys, UPDATE_TRIGGER_TOOL, tool_input)
+    assert (exit_code, stdout_text) == (0, "")
+
+
+@pytest.mark.parametrize(
+    "cron_expression",
+    ["*/5 * * * *", "*/30 * * * *", "7,37 * * * *", "*/20 0-23 1-31 1-12 0-7", "*/20 * * * 0-6"],
+)
+def test_cron_create_firing_more_often_than_the_step_down_passes(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], cron_expression: str
+) -> None:
+    exit_code, stdout_text, _ = run_gate(
+        monkeypatch, capsys, "CronCreate", {"cron": cron_expression, "prompt": "p"}
+    )
+    assert (exit_code, stdout_text) == (0, "")
+
+
+@pytest.mark.parametrize(
+    "cron_expression",
+    ["7 * * * *", "57 8 * * *", "0,58 * * * *", "*/20 9-17 * * *", "*/5 * * * 1-5", "*/5 * * * MON"],
+)
+def test_cron_create_with_an_hour_or_more_between_wakes_is_refused(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], cron_expression: str
+) -> None:
+    exit_code, _, stderr_text = run_gate(
+        monkeypatch, capsys, "CronCreate", {"cron": cron_expression, "prompt": "p"}
+    )
+    assert exit_code == 2
+    assert "stack" in stderr_text
+
+
+def pinned_local_cron(minutes_ahead: float) -> str:
+    fire_time = datetime.now().astimezone() + timedelta(minutes=minutes_ahead)
+    return f"{fire_time.minute} {fire_time.hour} {fire_time.day} {fire_time.month} *"
+
+
+def test_cron_create_one_shot_within_the_step_down_passes(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    tool_input = {"cron": pinned_local_cron(30), "prompt": "p", "recurring": False}
+    exit_code, stdout_text, _ = run_gate(monkeypatch, capsys, "CronCreate", tool_input)
+    assert (exit_code, stdout_text) == (0, "")
+
+
+def test_cron_create_one_shot_with_a_timezone_prefix_is_refused(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    tool_input = {
+        "cron": "CRON_TZ=America/Los_Angeles " + pinned_local_cron(30),
+        "prompt": "p",
+        "recurring": False,
+    }
+    exit_code, _, _ = run_gate(monkeypatch, capsys, "CronCreate", tool_input)
+    assert exit_code == 2
+
+
+def test_cron_create_one_shot_two_hours_out_is_refused(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    tool_input = {"cron": pinned_local_cron(120), "prompt": "p", "recurring": False}
+    exit_code, _, _ = run_gate(monkeypatch, capsys, "CronCreate", tool_input)
+    assert exit_code == 2
+
+
+def test_other_tools_pass(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stdout_text, _ = run_gate(monkeypatch, capsys, "Bash", {"command": "sleep 4000"})
+    assert (exit_code, stdout_text) == (0, "")

package/hooks/blocking/wakeup_cap_gate.py

@@ -0,0 +1,400 @@
+#!/usr/bin/env python3
+"""PreToolUse hook that keeps every self-wakeup inside the 1-hour prompt cache.
+
+A session that wakes 60 minutes or more after its last turn resumes with a cold
+prompt cache and re-reads its whole transcript. The gate reads each tool call
+that schedules a later wake of a session and acts on how far away the wake is:
+
+- At most the step-down (57 minutes for send_later and Routines, 3480 seconds
+  for ScheduleWakeup): the call passes untouched.
+- Over the step-down and at most 60 minutes: the call runs with the delay
+  rewritten to the step-down through ``updatedInput``.
+- Over 60 minutes: the call is denied with a reason that names the step-down and
+  tells the session to stack wakes under it.
+
+A cron schedule cannot be rewritten, so a cron that leaves more than the
+step-down between wakes is denied. A Routine that starts a fresh session on each
+firing has no cache to keep and passes. An ``update_trigger`` cron change passes,
+because its input does not say whether the Routine wakes a session.
+
+The step-down values come from fire-time probes: send_later rounds its fire time
+up to the next minute and then waits up to one more minute for its poll, so it
+lands up to two minutes after its requested delay. ScheduleWakeup rounds its
+fire time up to the next minute and lands a few seconds after it, so it lands up
+to about 64 seconds after its requested delay.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+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.hook_block_logger import log_hook_block
+from hooks_constants.hook_specific_output_keys import (
+    HOOK_EVENT_NAME_KEY,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+    PERMISSION_DECISION_KEY,
+    UPDATED_INPUT_KEY,
+)
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.wakeup_cap_constants import (
+    ADDITIONAL_CONTEXT_KEY,
+    ALL_CRON_FIELD_RANGES,
+    ALLOW_DECISION,
+    ALLOW_EXIT_CODE,
+    AT_KEY,
+    BLOCK_EXIT_CODE,
+    CACHE_LIFETIME_MINUTES,
+    CACHE_LIFETIME_SECONDS,
+    CREATE_TRIGGER_TOOL_PATTERN,
+    CRON_CREATE_TOOL_NAME,
+    CRON_EXPRESSION_KEY,
+    CRON_FIELD_COUNT,
+    CRON_KEY,
+    CRON_TIMEZONE_PREFIX_PATTERN,
+    DELAY_MINUTES_KEY,
+    DELAY_SECONDS_KEY,
+    DENY_CRON_DETAIL,
+    DENY_DELAY_DETAIL,
+    DENY_REASON_TEMPLATE,
+    GATE_EVENT_NAME,
+    MINUTES_PER_HOUR,
+    NEW_SESSION_ON_FIRE_KEY,
+    PINNED_FIELD_COUNT,
+    RECURRING_KEY,
+    REWRITE_CONTEXT_TEMPLATE,
+    RFC3339_OUTPUT_FORMAT,
+    RUN_ONCE_AT_KEY,
+    SCHEDULE_WAKEUP_STEP_DOWN_SECONDS,
+    SCHEDULE_WAKEUP_TOOL_NAME,
+    SECONDS_PER_MINUTE,
+    SEND_LATER_STEP_DOWN_MINUTES,
+    SEND_LATER_TOOL_PATTERN,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+    UPDATE_TRIGGER_TOOL_PATTERN,
+    UTC_OFFSET_TEXT,
+    UTC_SUFFIX,
+)
+
+
+@dataclass(frozen=True)
+class Rewrite:
+    """A tool input field to replace with the step-down value."""
+
+    field: str
+    requested: object
+    allowed: object
+
+
+@dataclass(frozen=True)
+class Denial:
+    """The part of the deny reason that names what the call asked for."""
+
+    detail: str
+
+
+Decision = Rewrite | Denial | None
+
+
+def _number_or_none(value: object) -> float | None:
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        return None
+    return float(value)
+
+
+def _parse_utc_moment(text: object) -> datetime | None:
+    if not isinstance(text, str):
+        return None
+    try:
+        moment = datetime.fromisoformat(text.strip().replace(UTC_SUFFIX, UTC_OFFSET_TEXT))
+    except ValueError:
+        return None
+    if moment.tzinfo is None:
+        return None
+    return moment
+
+
+def _decide_minutes(
+    field: str, requested: object, minutes_away: float, allowed: object
+) -> Decision:
+    if minutes_away > CACHE_LIFETIME_MINUTES:
+        return Denial(DENY_DELAY_DETAIL.format(minutes=math.ceil(minutes_away)))
+    if minutes_away > SEND_LATER_STEP_DOWN_MINUTES:
+        return Rewrite(field, requested, allowed)
+    return None
+
+
+def _decide_delay_minutes(all_tool_input_fields: dict[str, object]) -> Decision:
+    requested = all_tool_input_fields.get(DELAY_MINUTES_KEY)
+    requested_minutes = _number_or_none(requested)
+    if requested_minutes is None:
+        return None
+    return _decide_minutes(
+        DELAY_MINUTES_KEY, requested, requested_minutes, SEND_LATER_STEP_DOWN_MINUTES
+    )
+
+
+def _decide_fire_time(
+    field: str, all_tool_input_fields: dict[str, object], now: datetime
+) -> Decision:
+    requested = all_tool_input_fields.get(field)
+    fire_time = _parse_utc_moment(requested)
+    if fire_time is None:
+        return None
+    minutes_away = (fire_time - now).total_seconds() / SECONDS_PER_MINUTE
+    latest_allowed = (now + timedelta(minutes=SEND_LATER_STEP_DOWN_MINUTES)).replace(
+        second=0, microsecond=0
+    )
+    allowed_text = latest_allowed.astimezone(timezone.utc).strftime(RFC3339_OUTPUT_FORMAT)
+    return _decide_minutes(field, requested, minutes_away, allowed_text)
+
+
+def _decide_delay_seconds(all_tool_input_fields: dict[str, object]) -> Decision:
+    requested = all_tool_input_fields.get(DELAY_SECONDS_KEY)
+    requested_seconds = _number_or_none(requested)
+    if requested_seconds is None:
+        return None
+    if requested_seconds > CACHE_LIFETIME_SECONDS:
+        return Denial(
+            DENY_DELAY_DETAIL.format(minutes=math.ceil(requested_seconds / SECONDS_PER_MINUTE))
+        )
+    if requested_seconds > SCHEDULE_WAKEUP_STEP_DOWN_SECONDS:
+        return Rewrite(DELAY_SECONDS_KEY, requested, SCHEDULE_WAKEUP_STEP_DOWN_SECONDS)
+    return None
+
+
+def _base_bounds(base: str, has_step: bool, lowest: int, highest: int) -> tuple[int, int] | None:
+    if base == "*":
+        return lowest, highest
+    first_text, separator, last_text = base.partition("-")
+    if separator and first_text.isdigit() and last_text.isdigit():
+        return int(first_text), int(last_text)
+    if separator or not base.isdigit():
+        return None
+    return int(base), highest if has_step else int(base)
+
+
+def _part_values(cron_part: str, lowest: int, highest: int) -> range | None:
+    base, _, step_text = cron_part.partition("/")
+    if step_text and not step_text.isdigit():
+        return None
+    step = int(step_text) if step_text else 1
+    bounds = _base_bounds(base, bool(step_text), lowest, highest)
+    if bounds is None or step < 1 or not lowest <= bounds[0] <= bounds[1] <= highest:
+        return None
+    return range(bounds[0], bounds[1] + 1, step)
+
+
+def _field_values(cron_field: str, lowest: int, highest: int) -> set[int] | None:
+    all_values: set[int] = set()
+    for each_part in cron_field.split(","):
+        part_values = _part_values(each_part, lowest, highest)
+        if part_values is None:
+            return None
+        all_values.update(part_values)
+    return all_values
+
+
+def _covers_every_value(cron_field: str, lowest: int, highest: int, wrap: int) -> bool:
+    all_values = _field_values(cron_field, lowest, highest)
+    if all_values is None:
+        return False
+    return {each_value % wrap for each_value in all_values} == set(range(lowest, wrap))
+
+
+def _cron_fields(cron_expression: str) -> list[str] | None:
+    all_fields = CRON_TIMEZONE_PREFIX_PATTERN.sub("", cron_expression.strip()).split()
+    if len(all_fields) != CRON_FIELD_COUNT:
+        return None
+    return all_fields
+
+
+def longest_cron_gap_minutes(cron_expression: str) -> int | None:
+    """Return the longest wait between two firings of a cron schedule, in minutes.
+
+    A schedule that limits its hour, day, month or weekday leaves an hour or more
+    between some firings, so it reports the cache lifetime as a floor.
+
+    >>> longest_cron_gap_minutes("*/20 * * * *")
+    20
+    >>> longest_cron_gap_minutes("5 9 * * *")
+    60
+
+    Args:
+        cron_expression: A 5-field cron expression, with an optional CRON_TZ prefix.
+
+    Returns:
+        The longest gap in minutes, or None when the expression cannot be read.
+    """
+    all_fields = _cron_fields(cron_expression)
+    if all_fields is None:
+        return None
+    all_minutes = _field_values(all_fields[0], 0, MINUTES_PER_HOUR - 1)
+    if not all_minutes:
+        return None
+    if not _fires_every_hour(all_fields[1:]):
+        return CACHE_LIFETIME_MINUTES
+    return _longest_minute_gap(all_minutes)
+
+
+def _fires_every_hour(all_hour_and_day_fields: list[str]) -> bool:
+    return all(
+        _covers_every_value(each_field, lowest, highest, wrap)
+        for each_field, (lowest, highest, wrap) in zip(
+            all_hour_and_day_fields, ALL_CRON_FIELD_RANGES, strict=True
+        )
+    )
+
+
+def _longest_minute_gap(all_minutes: set[int]) -> int:
+    ordered_minutes = sorted(all_minutes)
+    all_gaps = [
+        later - earlier
+        for earlier, later in zip(ordered_minutes, ordered_minutes[1:], strict=False)
+    ]
+    all_gaps.append(ordered_minutes[0] + MINUTES_PER_HOUR - ordered_minutes[-1])
+    return max(all_gaps)
+
+
+def _decide_cron_gap(cron_expression: object) -> Decision:
+    if not isinstance(cron_expression, str):
+        return None
+    longest_gap = longest_cron_gap_minutes(cron_expression)
+    if longest_gap is None or longest_gap <= SEND_LATER_STEP_DOWN_MINUTES:
+        return None
+    return Denial(DENY_CRON_DETAIL.format(cron=cron_expression, minutes=longest_gap))
+
+
+def _pinned_local_fire_time(cron_expression: str, now: datetime) -> datetime | None:
+    if CRON_TIMEZONE_PREFIX_PATTERN.match(cron_expression.strip()):
+        return None
+    all_fields = _cron_fields(cron_expression)
+    if all_fields is None:
+        return None
+    all_pinned_fields = all_fields[:PINNED_FIELD_COUNT]
+    if not all(each_field.isdigit() for each_field in all_pinned_fields):
+        return None
+    minute, hour, day, month = (int(each_field) for each_field in all_pinned_fields)
+    local_now = now.astimezone()
+    try:
+        fire_time = local_now.replace(
+            month=month, day=day, hour=hour, minute=minute, second=0, microsecond=0
+        )
+        if fire_time < local_now.replace(second=0, microsecond=0):
+            fire_time = fire_time.replace(year=fire_time.year + 1)
+    except ValueError:
+        return None
+    return fire_time
+
+
+def _decide_pinned_one_shot(fire_time: datetime, now: datetime) -> Decision:
+    minutes_away = (fire_time - now).total_seconds() / SECONDS_PER_MINUTE
+    if minutes_away > SEND_LATER_STEP_DOWN_MINUTES:
+        return Denial(DENY_DELAY_DETAIL.format(minutes=math.ceil(minutes_away)))
+    return None
+
+
+def _decide_cron_create(all_tool_input_fields: dict[str, object], now: datetime) -> Decision:
+    cron_expression = all_tool_input_fields.get(CRON_KEY)
+    if not isinstance(cron_expression, str):
+        return None
+    is_one_shot = all_tool_input_fields.get(RECURRING_KEY) is False
+    fire_time = _pinned_local_fire_time(cron_expression, now) if is_one_shot else None
+    if fire_time is not None:
+        return _decide_pinned_one_shot(fire_time, now)
+    return _decide_cron_gap(cron_expression)
+
+
+def _decide_create_trigger(all_tool_input_fields: dict[str, object], now: datetime) -> Decision:
+    if all_tool_input_fields.get(NEW_SESSION_ON_FIRE_KEY) is True:
+        return None
+    if RUN_ONCE_AT_KEY in all_tool_input_fields:
+        return _decide_fire_time(RUN_ONCE_AT_KEY, all_tool_input_fields, now)
+    return _decide_cron_gap(all_tool_input_fields.get(CRON_EXPRESSION_KEY))
+
+
+def decide(tool_name: str, all_tool_input_fields: dict[str, object], now: datetime) -> Decision:
+    """Return how the gate treats one tool call that may schedule a wake.
+
+    Args:
+        tool_name: The name of the tool being called.
+        all_tool_input_fields: The tool call's input.
+        now: The current time, timezone aware.
+
+    Returns:
+        A Rewrite, a Denial, or None when the call passes untouched.
+    """
+    if tool_name == SCHEDULE_WAKEUP_TOOL_NAME:
+        return _decide_delay_seconds(all_tool_input_fields)
+    if tool_name == CRON_CREATE_TOOL_NAME:
+        return _decide_cron_create(all_tool_input_fields, now)
+    if SEND_LATER_TOOL_PATTERN.match(tool_name):
+        if DELAY_MINUTES_KEY in all_tool_input_fields:
+            return _decide_delay_minutes(all_tool_input_fields)
+        return _decide_fire_time(AT_KEY, all_tool_input_fields, now)
+    if CREATE_TRIGGER_TOOL_PATTERN.match(tool_name):
+        return _decide_create_trigger(all_tool_input_fields, now)
+    if UPDATE_TRIGGER_TOOL_PATTERN.match(tool_name):
+        return _decide_fire_time(RUN_ONCE_AT_KEY, all_tool_input_fields, now)
+    return None
+
+
+def _write_rewrite(all_tool_input_fields: dict[str, object], rewrite: Rewrite) -> None:
+    payload = {
+        HOOK_SPECIFIC_OUTPUT_KEY: {
+            HOOK_EVENT_NAME_KEY: GATE_EVENT_NAME,
+            PERMISSION_DECISION_KEY: ALLOW_DECISION,
+            UPDATED_INPUT_KEY: {**all_tool_input_fields, rewrite.field: rewrite.allowed},
+            ADDITIONAL_CONTEXT_KEY: REWRITE_CONTEXT_TEMPLATE.format(
+                field=rewrite.field,
+                requested=rewrite.requested,
+                allowed=rewrite.allowed,
+                cap=f"{CACHE_LIFETIME_MINUTES} minutes",
+            ),
+        }
+    }
+    sys.stdout.write(json.dumps(payload) + "\n")
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
+        return ALLOW_EXIT_CODE
+    tool_name = hook_input.get(TOOL_NAME_KEY)
+    tool_input = hook_input.get(TOOL_INPUT_KEY)
+    if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
+        return ALLOW_EXIT_CODE
+    decision = decide(tool_name, tool_input, datetime.now(timezone.utc))
+    if isinstance(decision, Rewrite):
+        _write_rewrite(tool_input, decision)
+        return ALLOW_EXIT_CODE
+    if decision is None:
+        return ALLOW_EXIT_CODE
+    block_reason = DENY_REASON_TEMPLATE.format(
+        tool_name=tool_name,
+        detail=decision.detail,
+        send_later_cap=SEND_LATER_STEP_DOWN_MINUTES,
+        schedule_wakeup_cap=SCHEDULE_WAKEUP_STEP_DOWN_SECONDS,
+    )
+    log_hook_block(
+        Path(__file__).name,
+        GATE_EVENT_NAME,
+        block_reason,
+        tool_name=tool_name,
+        offending_input_preview=json.dumps(tool_input),
+    )
+    sys.stderr.write(block_reason)
+    return BLOCK_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/features/conduct-gates.md

@@ -15,6 +15,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/session_title_format_gate.py` denies a session title that breaks the `<emoji> <name>` shape or has a name longer than 25 characters.
 - `blocking/session_title_turn_gate.py` holds the end of a turn once, in a session that has a `__set_session_title` tool, when the shown title does not fit the session's state: no title yet, a red flag after a prompt that asks for work, a check mark while the task list has open items, or an hourglass once every item is completed or deleted. A turn that set a title passes. A turn that called no tool other than the title tool passes, and so does a held turn.
 - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
+- `blocking/wakeup_cap_gate.py` keeps a self-wakeup inside the 1-hour prompt cache. A wake over the step-down (57 minutes for `send_later` and Routines, 3480 seconds for `ScheduleWakeup`) and at most 60 minutes away runs with its delay rewritten to the step-down. A wake over 60 minutes away, or a cron with more than 57 minutes between wakes, is denied with a reason that says to stack wakes under the cap. A Routine that starts a fresh session on each firing passes.
 - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim.
 - `blocking/pr_lifecycle_skill_gate.py` denies a commit, push, pull request action, or merge until the `pr-lifecycle` skill appears in the transcript since the last compaction.
 - `blocking/resolve_thread_reply_gate.py` denies a review thread resolve until the agent's own transcript shows a reply on that same thread that posted after the last user prompt and that no successful resolve of the thread has spent. A resolve is a `resolve_review_thread` call, which names the thread by `threadID`; a `pull_request_review_write` call with method `resolve_thread`, which names it by `threadId`; a shell command with a `gh api graphql` `resolveReviewThread` mutation, which names it by a literal `PRRT_` id; or a shell call to `pulls/<n>/ccr/comments/<id>/resolve`, which names it by a comment id. A graphql resolve that names no `PRRT_` id is denied. A reply is an `add_reply_to_pull_request_comment` call, or a `gh api` call to a comment's `replies` endpoint or to `addPullRequestReviewThreadReply`, which names its thread by `PRRT_` id. A reply and a resolve by comment id match when they name the same comment, or when a successful tool result in the transcript, such as `pull_request_read` `get_review_comments`, lists the comment under the thread by its `discussion_r` anchor or `databaseId`. A reply whose result is an error, such as a refusal from `blocking/reply_length_gate.py`, does not count. With no readable transcript, the resolve passes.
@@ -39,6 +40,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/session_title_format_gate.py` runs on `PreToolUse`, matcher `mcp__.*__set_session_title`, timeout `10` seconds in `hooks.json`.
 - `blocking/session_title_turn_gate.py` runs on `Stop`, timeout `10` seconds in `hooks.json`.
 - `blocking/step_note_gate.py` runs on `PreToolUse`, matcher `*`, timeout `15` seconds in `hooks.json`.
+- `blocking/wakeup_cap_gate.py` runs on `PreToolUse`, matcher `ScheduleWakeup|CronCreate|mcp__.*__(send_later|create_trigger|update_trigger)`, timeout `10` seconds in `hooks.json`.
 - `blocking/verify_before_acting.py` runs on `PostToolUse`, matcher `Write|Edit|MultiEdit|NotebookEdit|Agent|Task|apply_patch|Bash|PowerShell|mcp__.*`, timeout `10` seconds in `hooks.json`.
 - `blocking/pr_lifecycle_skill_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request|actions_run_trigger)`, timeout `10` seconds in `hooks.json`.
 - `blocking/resolve_thread_reply_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__resolve_review_thread|mcp__.*__pull_request_review_write`, timeout `10` seconds in `hooks.json`.
@@ -68,6 +70,7 @@ Preconditions:
 - **Session title.** Input is a set session title call with no leading emoji or a name over 25 characters. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_format_gate.py -q`. The adjacent test observes a denial that names the broken rule; a well-formed title passes.
 - **Stale title.** Input is a transcript that lists the title tool, an earlier turn that set the red flag, and a work prompt whose turn ran a tool and set no title. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_turn_gate.py -q`. The adjacent test observes a `block` decision that names the shown title, the tool, and the four status emoji. A carried hourglass with an item in progress passes, and so does a turn whose title call came back without an error.
 - **Step note.** Input is a tool call after a transcript message without a status line while the flag is on. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_step_note_gate.py -q`. The adjacent test observes a block until a status line appears.
+- **Wakeup cap.** Input is a `send_later` call with `delay_minutes` of 60, then 90, then 45. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_wakeup_cap_gate.py -q`. The adjacent test observes 60 rewritten to 57 through `updatedInput`, 90 denied with the stacking instruction, and 45 passing untouched.
 - **Checked claim.** Input is a Write after hedged reasoning in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_acting.py -q`. The adjacent test observes a block and a logged blocked outcome.
 - **Lifecycle skill.** Input is a `git commit` or `gh pr create` command with no `pr-lifecycle` invocation in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pr_lifecycle_skill_gate.py -q`. The adjacent test observes a denial, then a silent allow once the skill or its slash command appears.
 - **Verify before commit.** Input is `git add app.py; git commit -m change` in a temporary repository with `.agents/skills/verify`, and a transcript with no `verify` load after its last prompt. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_commit_gate.py -q`. The adjacent test observes a denial, then a silent allow after a `verify` Skill call or a `/verify` prompt. A load before the last prompt still denies. A docs-only commit, a commit of data files under a `docs` folder, a tests-only commit, and a repository with no verify skill pass. A `.py` file under `docs` and a `.json` file outside `docs` still deny.
@@ -84,6 +87,7 @@ Preconditions:
 - `blocking/turn_review_gate.py` starts `claude -p`, which inherits the parent session id unless the gate strips it. A review that kept `CLAUDE_CODE_SESSION_ID` would write into the parent's transcript.
 - Each review run calls a model and costs about $0.03. Leave `CLAUDE_TURN_REVIEW_REPOSITORIES` unset and the gate makes no snapshot and no call.
 - `blocking/step_note_gate.py` is off by default and polls for the transcript record. Subagent calls and unreadable records pass.
+- `blocking/wakeup_cap_gate.py` lets an `update_trigger` cron change pass, because that input does not say whether the Routine wakes a session. Its step-down values come from fire-time probes: `send_later` rounds its fire time up to the next minute and polls once a minute, so a 1-minute request landed 123 and 158 seconds later. `ScheduleWakeup` rounds its fire time up to the next minute, so requests of 60 and 90 seconds landed 70 and 121 seconds later.
 - `blocking/verify_before_acting.py` runs after the tool. A block asks the agent to check the claim and undo a contradicted change.
 - The reply gate counts each nonempty list line as a sentence. Link targets and code spans add no words. Its banned words come from `reply-banned-words.json` in the Claude home, or the file `CLAUDE_REPLY_BANNED_WORDS_PATH` names, with built-in defaults.
 - The final reply gate blocks the stop and returns its reason to the model, which rewrites the reply. Claude Code ends the turn anyway after eight blocks in a row. The cited number checks in both gates skip when the transcript cannot be read.

package/hooks/hooks.json

@@ -224,6 +224,16 @@
           }
         ]
       },
+      {
+        "matcher": "ScheduleWakeup|CronCreate|mcp__.*__(send_later|create_trigger|update_trigger)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/wakeup_cap_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "Artifact",
         "hooks": [

package/hooks/hooks_constants/wakeup_cap_constants.py

@@ -0,0 +1,56 @@
+"""Constants for wakeup_cap_gate.py."""
+
+import re
+
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+GATE_EVENT_NAME = "PreToolUse"
+ALLOW_EXIT_CODE = 0
+BLOCK_EXIT_CODE = 2
+ALLOW_DECISION = "allow"
+ADDITIONAL_CONTEXT_KEY = "additionalContext"
+
+SCHEDULE_WAKEUP_TOOL_NAME = "ScheduleWakeup"
+CRON_CREATE_TOOL_NAME = "CronCreate"
+SEND_LATER_TOOL_PATTERN = re.compile(r"^mcp__.+__send_later$")
+CREATE_TRIGGER_TOOL_PATTERN = re.compile(r"^mcp__.+__create_trigger$")
+UPDATE_TRIGGER_TOOL_PATTERN = re.compile(r"^mcp__.+__update_trigger$")
+
+DELAY_SECONDS_KEY = "delaySeconds"
+DELAY_MINUTES_KEY = "delay_minutes"
+AT_KEY = "at"
+RUN_ONCE_AT_KEY = "run_once_at"
+CRON_EXPRESSION_KEY = "cron_expression"
+CRON_KEY = "cron"
+RECURRING_KEY = "recurring"
+NEW_SESSION_ON_FIRE_KEY = "create_new_session_on_fire"
+
+SECONDS_PER_MINUTE = 60
+MINUTES_PER_HOUR = 60
+CACHE_LIFETIME_MINUTES = 60
+CACHE_LIFETIME_SECONDS = CACHE_LIFETIME_MINUTES * SECONDS_PER_MINUTE
+SEND_LATER_STEP_DOWN_MINUTES = 57
+SCHEDULE_WAKEUP_STEP_DOWN_SECONDS = 3480
+
+CRON_TIMEZONE_PREFIX_PATTERN = re.compile(r"^CRON_TZ=\S+\s+")
+CRON_FIELD_COUNT = 5
+PINNED_FIELD_COUNT = 4
+ALL_CRON_FIELD_RANGES = ((0, 23, 24), (1, 31, 32), (1, 12, 13), (0, 7, 7))
+UTC_SUFFIX = "Z"
+UTC_OFFSET_TEXT = "+00:00"
+RFC3339_OUTPUT_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+
+REWRITE_CONTEXT_TEMPLATE = (
+    "wakeup_cap_gate rewrote {field} from {requested} to {allowed}. A wake {cap} or later"
+    " lands after the 1-hour prompt cache expires, so this wake now fires sooner."
+)
+DENY_REASON_TEMPLATE = (
+    "wakeup_cap_gate refused {tool_name}: {detail} A wake 60 minutes or more after the last"
+    " turn lands after the 1-hour prompt cache expires and resumes cold. Arm a wake of at"
+    " most {send_later_cap} minutes (send_later delay_minutes={send_later_cap}, ScheduleWakeup"
+    " delaySeconds={schedule_wakeup_cap}). For a longer wait, stack wakes under that cap:"
+    " put the remaining wait in the wake prompt and re-arm on each wake until it is covered,"
+    " as the usage-pause skill's stages_seconds chain does."
+)
+DENY_DELAY_DETAIL = "the wake is {minutes} minutes away."
+DENY_CRON_DETAIL = "the cron '{cron}' leaves {minutes} minutes or more between wakes."

package/hooks/test_context_budget_hooks.py

@@ -31,6 +31,7 @@ UNMEASURED_REASON_BY_SCRIPT = {
     "project registry names by absolute path",
     "session/plugin_change_warning.py": "emits only after a plugin changes on disk mid-session, "
     "once per plugin, naming plugin ids",
+    "blocking/wakeup_cap_gate.py": "emits one fixed-template line only when it rewrites a wake delay",
 }
 
 

package/package.json

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

package/scripts/policy_lint/adapter_configuration.py

@@ -146,6 +146,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
         hooks/blocking/session_title_turn_gate.py        -> exempt
         hooks/blocking/resolve_thread_reply_gate.py      -> exempt
         hooks/blocking/turn_review_gate.py               -> exempt
+        hooks/blocking/wakeup_cap_gate.py                -> exempt
         hooks/blocking/some_new_blocker.py               -> flagged
 
     The Bash PreToolUse dispatcher sits under ``blocking/`` for layout reasons
@@ -213,6 +214,10 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
     the agent fixes or answers each finding; the gate itself only decides when
     a turn may end.
 
+    The wakeup cap gate shortens or denies a self-wakeup scheduled 60 minutes
+    or more away, so the wake lands inside the prompt cache. It decides when a
+    session wakes and no code or safety policy.
+
     Args:
         registered_string: One command, path, script, or entrypoint string.
     """

package/scripts/policy_lint/config/constants.py

@@ -85,6 +85,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/session_title_turn_gate.py",
     "blocking/resolve_thread_reply_gate.py",
     "blocking/turn_review_gate.py",
+    "blocking/wakeup_cap_gate.py",
 )
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
 ALL_TEST_FILE_PREFIXES = ("test_",)