claude-dev-env 8.103.0 → 8.104.0

package/docs/templates/artifact-page/README.md

@@ -10,6 +10,8 @@ Three templates live here. Pick the one that fits the ask before you write a lin
 
 `diagram.html` draws the content in inline SVG: boxes for things, arrows for links, and color for state. Labels are a few words. Text in bordered cards is a tracker, so it never answers a visual-only ask.
 
+Show a diagram whole when the page opens, scaled to the page width. Never put a diagram in a box with a fixed or maximum height, because the reader then sees only part of it. A wide diagram may add a full-size button that lets the page scroll.
+
 `status-flowchart.html` reads left to right. Done steps are green boxes, each yes-or-no check is a diamond, a stuck step is an amber box under its check with a dashed recheck loop back to it, and the next step is a dashed box. A click on any shape opens its detail from the `detail-data` block below the chart. Replace the `<title>`, the `h1`, the svg `aria-label`, the shapes, the arrows and the `detail-data` entries with the work being reported. Keep each label to three words or fewer, in plain words with no abbreviations or item numbers.
 
 Render the page and look at the screenshot before you publish. Headless Chromium renders at least 500 pixels wide, so take the screenshot at 800 wide.

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.0",
+    "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_",)