claude-dev-env 8.103.1 → 8.105.0

package/.agents/agents/test_verifier_agent.py

@@ -0,0 +1,41 @@
+"""The verifier agent carries the verified-work contract: three modes, reproduce first, and no pass without a reproduction."""
+
+from pathlib import Path
+
+VERIFIER_PATH = Path(__file__).resolve().parent / "verifier.md"
+
+
+def _verifier_text() -> str:
+    return VERIFIER_PATH.read_text(encoding="utf-8")
+
+
+def test_the_verifier_names_a_mode_for_research_plan_and_fix() -> None:
+    verifier_text = _verifier_text()
+    assert "**Research.**" in verifier_text
+    assert "CONFIRMED or REFUTED" in verifier_text
+    assert "**Plan.**" in verifier_text
+    assert "SOUND or GAP" in verifier_text
+    assert "**Fix.**" in verifier_text
+
+
+def test_the_fix_mode_reproduces_on_the_old_state_before_it_confirms_on_the_new() -> None:
+    verifier_text = _verifier_text()
+    reproduce_position = verifier_text.index("1. Reproduce. On the old state")
+    confirm_position = verifier_text.index("2. Confirm. On the new state")
+    undo_position = verifier_text.index("3. Undo.")
+    assert reproduce_position < confirm_position < undo_position
+
+
+def test_a_fix_whose_issue_did_not_reproduce_never_passes() -> None:
+    assert "NOT REPRODUCED is never a pass" in _verifier_text()
+
+
+def test_the_verifier_leaves_the_work_under_review_untouched() -> None:
+    assert "Do not edit, create, or delete any file in the work under review" in _verifier_text()
+
+
+def test_the_brief_template_carries_the_spawn_oversight_clauses() -> None:
+    verifier_text = _verifier_text()
+    assert "Outcome: <" in verifier_text
+    assert "On a blocker: <" in verifier_text
+    assert "leaves out the worker's conclusion" in verifier_text

package/.agents/agents/verifier.md

@@ -0,0 +1,43 @@
+---
+name: verifier
+description: Separate checker for the verified-work flow. Spawn a fresh one after research, after the plan, and after the fix of each piece of work. It never checks work it did. For a fix it reproduces the issue on the old state first, then confirms the issue is gone on the new state, and it does not pass a fix whose issue it could not reproduce.
+tools: Read, Glob, Grep, Bash, PowerShell
+---
+
+You check work that another agent did. Read the brief, then run the mode it names. Use only primary evidence: files, command output, logs, and runs you read or produce yourself. A claim in the brief is a claim to test, never evidence.
+
+Your check ends the chain: it needs no research, plan, or verifier of its own.
+
+Do not edit, create, or delete any file in the work under review. Put probes and scratch files outside it, and name each one in the report.
+
+## Modes
+
+**Research.** For each claim, report CONFIRMED or REFUTED, with the file:line or command output you produced. Then list what the research missed that bears on the issue.
+
+**Plan.** For each piece, report SOUND or GAP. SOUND means the piece closes part of the researched issue and breaks no test, budget, or constraint the brief names. Check each scope tag against the user's own words. A piece the words do not name, and that the named work does not need, is new scope: report it as GAP with the tag "new scope".
+
+**Fix.** Run these steps in order.
+
+1. Reproduce. On the old state, run the check that shows the issue. Report REPRODUCED with the output, or NOT REPRODUCED.
+2. Confirm. On the new state, run the same check. Report FIXED with the output, or NOT FIXED.
+3. Undo. Revert the fix in a scratch copy and run the check again. It must fail again. When the fix lives outside the files, such as an installed setting, and no scratch copy can revert it, report UNDO NOT RUN with the reason.
+
+A fix passes only with REPRODUCED, FIXED, and an undo that fails again or UNDO NOT RUN with its reason. NOT REPRODUCED is never a pass: report what you ran, and say what check would show the issue.
+
+## Report
+
+End with one line per item: the item, the verdict, and the evidence. Then one overall line: PASS or FAIL.
+
+## Brief template
+
+The agent that spawns you writes the brief with these lines:
+
+```text
+Mode: research | plan | fix
+Outcome: <the user's outcome, in the user's words>
+Issue: <the issue, with the source that shows it>
+Sources: <files, commands, the old state and the new state>
+On a blocker: <the other routes to the same evidence>
+```
+
+The brief gives the issue and the sources. It leaves out the worker's conclusion.

package/.agents/skills/orchestrator/SKILL.md

@@ -26,7 +26,7 @@ The current agent owns the user's outcome, its own work, and any delegated work.
 Keep the goal, decisions, ownership, and next actions in the parent context.
 Put bulk research, logs, and implementation detail in bounded worker contexts and linked artifacts.
 Do short work inline when that keeps the task clear.
-This session is the advisor for its executors and verifies their returned claims.
+This session is the advisor for its executors. A fresh `verifier` agent checks each returned claim, per `~/.claude/docs/rule-guides/verified-work.md`.
 
 ## Gotchas
 
@@ -105,7 +105,7 @@ Send follow-ups only through a transport authorized by the current runtime and u
 Read the evidence needed for your decision. Keep lengthy output in files and return short evidence pointers.
 Check scope, acceptance results, and unresolved work before accepting a worker's conclusion.
 Review every close a worker reports. Send a close back to that worker when it routes a defect the worker found in its own subject to another issue or epic, and have the worker carry the defect through its fix pull request.
-Use independent verification where the task or repository requires it.
+Run every piece through the verified-work flow: a fresh `verifier` agent checks the research, the plan, and the fix, and the fix check reproduces the issue before it confirms the fix.
 Checkpoint after decisions and state changes, before waiting, and before a known compaction.
 
 ### Complete the requested outcome

package/.agents/skills/orchestrator/reference/completion-reporting.md

@@ -3,10 +3,11 @@
 Use this procedure before a completion report or an answer about whether work is done.
 
 1. Recover the user's requested outcome and acceptance conditions. Read the evidence for that outcome before choosing its status.
-2. Check what each unfinished item changes. Missing deliverables, required verification, necessary approvals, and stated completion prerequisites keep the affected goal open. An administrative item whose absence has no effect on the result, its use, or its acceptance keeps its own task open.
-3. State the main outcome first. When that outcome is verified complete and only incidental recordkeeping remains, report the task as complete. A requested status notice alone does not make the main outcome incomplete. Mention the administrative item separately when useful or required by the active reporting rules.
-4. Keep unfinished work tracked honestly. When one tracker item combines the completed outcome and unfinished administration, preserve the outcome's goal and evidence, mark its work complete, and keep a separate open administrative follow-up. Do reachable administrative work before ending. Preserve its next action or blocker when it cannot be finished. Never mark it done merely to make the report look complete.
-5. Preserve other goals and required delivery. A complete subgoal does not close an unfinished goal or the parent run. Use the goal's acceptance conditions in the [run record](run-state.md) to decide what its remaining work affects.
+2. Confirm that a fresh `verifier` agent passed the result, per `~/.claude/docs/rule-guides/verified-work.md`. A fix passes only when the verifier reproduced the issue first and then confirmed it gone. A result with no passed verifier stays open and is reported as waiting on verification.
+3. Check what each unfinished item changes. Missing deliverables, required verification, necessary approvals, and stated completion prerequisites keep the affected goal open. An administrative item whose absence has no effect on the result, its use, or its acceptance keeps its own task open.
+4. State the main outcome first. When that outcome is verified complete and only incidental recordkeeping remains, report the task as complete. A requested status notice alone does not make the main outcome incomplete. Mention the administrative item separately when useful or required by the active reporting rules.
+5. Keep unfinished work tracked honestly. When one tracker item combines the completed outcome and unfinished administration, preserve the outcome's goal and evidence, mark its work complete, and keep a separate open administrative follow-up. Do reachable administrative work before ending. Preserve its next action or blocker when it cannot be finished. Never mark it done merely to make the report look complete.
+6. Preserve other goals and required delivery. A complete subgoal does not close an unfinished goal or the parent run. Use the goal's acceptance conditions in the [run record](run-state.md) to decide what its remaining work affects.
 
 An administrative action can be requested without being a condition of the main outcome's completion. Treat it as a completion prerequisite when the user states that dependency, when it carries an essential requested result, or when its absence affects the result's usability, safety, or completeness.
 

package/.agents/skills/orchestrator/reference/oversee-delegated-work.md

@@ -1,13 +1,15 @@
 # Oversee delegated work
 
 Every agent that spawns a subagent, thread, or session owns that work until it reaches the user.
-Agents make mistakes. The spawner is a fresh second set of eyes that catches and corrects them before they reach the user.
+Agents make mistakes. A fresh `verifier` agent, separate from the worker, catches them before they reach the user.
 The `spawn_oversight_hook` adds this duty to every spawn, at every level of the tree.
 
-- Brief each agent with the user's own words, the standards that apply, and the acceptance check.
-- While it runs, read its progress. Wake a quiet agent with one concrete next step.
-- Before its output reaches the user, check it against the user's words and standards yourself.
-- Send the agent a correction when it misses, and check the corrected output the same way.
-- Give each piece of a multi-piece task its own reviewer or helper.
+- Run each piece through the verified-work flow in `~/.claude/docs/rule-guides/verified-work.md`: research, verify, plan, verify, implement, verify.
+- Brief each worker with the user's own words, the standards that apply, and the acceptance check.
+- Brief each verifier with the issue, the sources, the old state, and the new state. Leave the worker's conclusion out.
+- While a worker runs, read its progress. Wake a quiet agent with one concrete next step.
+- A fix passes only when its verifier reproduced the issue on the old state and confirmed it gone on the new state.
+- Send a FAIL back to the worker with the verifier's evidence, and give the next attempt a new verifier.
+- Tag each piece in-scope or new scope. Ask the user once before building new scope, and keep in-scope work moving.
 - Keep each brief, prompt, and context file you hand an agent a short map: when to use it, the steps, and pointers to reference files it opens on demand.
-- Show the user you are involved: say what you checked and what you corrected.
+- Report as done only what a verifier passed, and name the verdict and its evidence. Report the rest as waiting on verification.

package/.agents/skills/orchestrator/test_orchestrator_skill_contract.py

@@ -58,3 +58,30 @@ def test_executor_consult_block_names_orchestrating_session() -> None:
     )
     assert "<orchestrator-name>" in text
     assert "your advisor" in text
+
+
+_OVERSEE_PATH = _SKILL_DIR / "reference" / "oversee-delegated-work.md"
+_COMPLETION_PATH = _SKILL_DIR / "reference" / "completion-reporting.md"
+_VERIFIED_WORK_GUIDE = "~/.claude/docs/rule-guides/verified-work.md"
+
+
+def test_independent_verification_is_no_longer_conditional() -> None:
+    text = (_SKILL_DIR / "SKILL.md").read_text(encoding="utf-8")
+    assert "Use independent verification where the task or repository requires it." not in text
+    assert "Run every piece through the verified-work flow" in text
+    assert _VERIFIED_WORK_GUIDE in text
+
+
+def test_a_separate_verifier_checks_delegated_work() -> None:
+    text = _OVERSEE_PATH.read_text(encoding="utf-8")
+    assert "check it against the user's words and standards yourself" not in text
+    assert "A fresh `verifier` agent, separate from the worker" in text
+    assert "Leave the worker's conclusion out." in text
+    assert "reproduced the issue on the old state and confirmed it gone on the new state" in text
+    assert "Ask the user once before building new scope" in text
+
+
+def test_completion_needs_a_passed_verifier() -> None:
+    text = _COMPLETION_PATH.read_text(encoding="utf-8")
+    assert "Confirm that a fresh `verifier` agent passed the result" in text
+    assert "reported as waiting on verification" in text

package/docs/rule-guides/verified-work.md

@@ -0,0 +1,51 @@
+Back to the [rules index](../../rules/index.md).
+
+# Verified work
+
+## In brief
+
+Every piece of work runs in six steps: research, verify the research, plan, verify the plan, implement, verify the fix. A separate `verifier` agent runs each verify step. The fix check reproduces the issue on the old state first, then confirms it is gone on the new state. The user gets only results a verifier passed. New scope goes to the user as one question before it is built.
+
+**When this applies:** Any task: a change to code, configuration, rules, or a document, and any finding, cause, or fix reported to the user.
+
+## The six steps
+
+1. **Research.** Find the issue and its cause in primary sources: files, logs, runs, command output. Write each finding as a claim with its source.
+2. **Verify the research.** Spawn a fresh `verifier` in research mode. It reports CONFIRMED or REFUTED for each claim, and what the research missed. Fix the research before you plan.
+3. **Plan.** List the pieces of the fix. Tag each piece in-scope or new scope (see [Scope](#scope)).
+4. **Verify the plan.** Spawn a fresh `verifier` in plan mode. It reports SOUND or GAP for each piece: does it close part of the researched issue, and does it break a test, a budget, or a constraint. It checks each scope tag against the user's words. Revise the plan for each GAP.
+5. **Implement.** Build the in-scope pieces.
+6. **Verify the fix.** Spawn a fresh `verifier` in fix mode. It reproduces the issue on the old state, confirms the issue is gone on the new state, and confirms an undo of the fix fails again. When no scratch copy can revert the fix, such as an installed setting, it reports UNDO NOT RUN with the reason, and REPRODUCED plus FIXED still pass. A fix whose issue did not reproduce does not pass.
+
+## The verifier
+
+- The verifier is never the agent that did the work. The spawner is the owner of the work. A fresh agent at each verify step keeps the check apart from the author.
+- Its brief gives the issue, the sources, the old state and the new state. It leaves out the worker's conclusion, so the verifier tests the claim and does not inherit it.
+- Use the `verifier` agent definition and its brief template. On a host without that agent, give a fresh general-purpose agent the same contract.
+- A verifier's own check ends the chain. It runs no research, plan, or verifier of its own.
+- A FAIL goes back to the worker with the verifier's evidence. After the next attempt, a new verifier checks it.
+
+## Scope
+
+A piece is in-scope when it traces to the user's own words, or when the named work needs it to be done, such as a test for the fix, a doc row that the change makes stale, or a refactor the fix cannot land without. A piece is new scope when it is a feature, task, or system the user's words do not name and the named work does not need.
+
+- In-scope work runs with no ask.
+- New scope goes to the user as one question before any of it is built: what it is, why the work led to it, and what it costs. Use the session's question tool, per [`question-presentation.md`](question-presentation.md).
+- While the question waits, keep building the in-scope pieces, per [`long-horizon-autonomy.md`](long-horizon-autonomy.md).
+
+Examples, labelled as a format guide:
+
+| Ask | Piece | Tag |
+|-|-|-|
+| Fix the sign-in step that fails in cloud sessions | Repair the token refresh the sign-in calls | in-scope |
+| Fix the sign-in step that fails in cloud sessions | A lock and write-back system for shared credentials | new scope: ask first |
+| Add a flag that skips the cache | Update the README table that lists the flags | in-scope |
+| Add a flag that skips the cache | Rewrite the cache as a separate service | new scope: ask first |
+
+## Reporting
+
+Report only what a verifier passed. Name the verifier's verdict and the evidence it produced. A result that no verifier has passed is still work in progress: say that it waits on verification.
+
+## Enforcement
+
+`hooks/routing/spawn_oversight_hook.py` adds the six steps, the separate verifier, the reproduce-first check, the scope ask, and the reporting rule to every spawn at every level of the agent tree whose brief has an `Outcome:` line and an `On a blocker:` line; the hook already denies a brief without them, and the verifier brief template carries both. The flow itself adds context only. No hook refuses a report, a commit, or a spawn for a missing verifier run, so the flow never blocks work the user asked for.

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/features/spawn-routing.md

@@ -5,7 +5,7 @@ This family reminds the agent to gather context before a spawn, refuses a brief
 ## Checks
 
 - `routing/spawn_readiness_hook.py` adds context to a spawn that comes before a read step, or before an answered question or a settled-scope line. The spawn still runs.
-- `routing/spawn_oversight_hook.py` denies a spawn whose brief has no `Outcome:` line or no `On a blocker:` clause, each with text after it. A spawn that passes gets the orchestrator oversight directive: watch the agent, check its output against the user's words and standards, and correct it before the output reaches the user. `routing/spawn_brief_text.py` reads the brief from each spawn tool for this hook and the readiness hook.
+- `routing/spawn_oversight_hook.py` denies a spawn whose brief has no `Outcome:` line or no `On a blocker:` clause, each with text after it. A spawn that passes gets the orchestrator oversight directive: run each piece through the verified-work flow, with a fresh verifier agent that checks the research, the plan, and the fix, reproduces the issue before it confirms the fix, and leaves the worker's conclusion out of its brief; ask the user before new scope; report as done only what a verifier passed; and watch the agent while it runs. `routing/spawn_brief_text.py` reads the brief from each spawn tool for this hook and the readiness hook.
 - `routing/thread_spawn_pace_hook.py` reshapes a thread request when usage is over pace or unreadable.
 - `routing/subagent_model_routing.mjs` allows a selected Luna model, remaps eligible requests, and denies unsupported model routing.
 - `blocking/haiku_spawn_slim_gate.py` denies an Agent, Task, or thread spawn whose `model` names Haiku. The deny reason gives the headless `claude -p` command that loads the slim profile through the account broker.

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/spawn_oversight_hook_constants.py

@@ -36,11 +36,17 @@ REFUSAL_SUFFIX = (
 REASON_SEPARATOR = " "
 
 SPAWN_OVERSIGHT_DIRECTIVE = (
-    "You own the work this spawn starts. Load the orchestrator skill and follow "
-    "its oversee delegated work reference. While the agent runs, read its progress "
-    "and wake it with one next step when it goes quiet. Before its output "
-    "reaches the user, check it against the user's own words and standards, and "
-    "send the agent a correction when it misses. Give each piece of a "
-    "multi-piece task its own reviewer or helper. Tell the user you are "
-    "checking the work."
+    "You own the work this spawn starts. Run each piece through the verified-work "
+    "flow: research, then a separate verifier checks the research; plan, then a "
+    "separate verifier checks that the plan fixes the researched issue; implement, "
+    "then a separate verifier reproduces the issue on the old state before it "
+    "confirms the fix on the new state. Spawn a fresh verifier agent for each "
+    "check, never the agent that did the work, and brief it with the issue and "
+    "the sources and leave the worker's conclusion out. A verifier's check ends "
+    "the chain and gets no verifier of its own. Ask the user once before "
+    "you build new scope the user's words do not name, and keep in-scope work "
+    "moving while the question waits. Report as done only what a verifier "
+    "passed, with its evidence. While the agent runs, read its progress and wake "
+    "it with one next step when it goes quiet. Load the orchestrator skill and "
+    "follow its oversee delegated work reference."
 )

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/routing/test_spawn_oversight_hook.py

@@ -232,3 +232,43 @@ def test_brief_gaps_should_name_each_missing_clause() -> None:
 def test_a_workflow_script_path_that_cannot_be_opened_gets_the_directive() -> None:
     payload = {"tool_name": "Workflow", "tool_input": {"scriptPath": "bad\u0000path.js"}}
     assert json.loads(_run_script(json.dumps(payload))) == _directive_output()
+
+
+def _emitted_directive() -> str:
+    stdout = _run_script(json.dumps(_spawn_payload("Agent", GOOD_BRIEF)))
+    return json.loads(stdout)["hookSpecificOutput"]["additionalContext"]
+
+
+def test_the_emitted_directive_runs_research_plan_and_fix_in_order() -> None:
+    directive = _emitted_directive()
+    research_position = directive.index("research, then a separate verifier checks the research")
+    plan_position = directive.index("plan, then a separate verifier checks that the plan fixes the researched issue")
+    fix_position = directive.index("implement, then a separate verifier reproduces the issue")
+    assert research_position < plan_position < fix_position
+
+
+def test_the_emitted_directive_reproduces_the_issue_before_it_confirms_the_fix() -> None:
+    directive = _emitted_directive()
+    assert directive.index("reproduces the issue on the old state") < directive.index(
+        "confirms the fix on the new state"
+    )
+
+
+def test_the_emitted_directive_keeps_the_verifier_apart_from_the_worker() -> None:
+    directive = _emitted_directive()
+    assert "Spawn a fresh verifier agent for each check, never the agent that did the work" in directive
+    assert "leave the worker's conclusion out" in directive
+
+
+def test_the_emitted_directive_asks_before_new_scope_and_keeps_in_scope_work_moving() -> None:
+    directive = _emitted_directive()
+    assert "Ask the user once before you build new scope" in directive
+    assert "keep in-scope work moving while the question waits" in directive
+
+
+def test_the_emitted_directive_reports_only_verified_results() -> None:
+    assert "Report as done only what a verifier passed, with its evidence" in _emitted_directive()
+
+
+def test_the_emitted_directive_ends_the_chain_at_the_verifier() -> None:
+    assert "A verifier's check ends the chain and gets no verifier of its own" in _emitted_directive()

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.105.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/index.md

@@ -1,13 +1,14 @@
 # Rules
-Each line gives a rule in brief. When its trigger matches your task, open the guide and follow it in full. Correction lens, question presentation, and the agent board load as their own files.
+Each line gives a rule in brief. When its trigger matches your task, open the guide and follow it in full.
 
 **Writing**
 - **Plain language** ([guide](../docs/rule-guides/asd-ste100-language.md)). Writing chat, narration, or repository prose. Short complete sentences on one topic, active voice, one action per step, each fact said once.
-- **No contrast framing** ([guide](../docs/rule-guides/no-contrast-framing.md)). Any sentence a person reads. State the chosen point and leave out the discarded reading. Remove the six forms: `trailing-comma-not`, `corrective-it-is-not`, `substitution-rather-than`, `additive-not-just`, `comparative-ranking`, `substitution-as-opposed-to`.
+- **No contrast framing** ([guide](../docs/rule-guides/no-contrast-framing.md)). Any sentence a person reads. State the chosen point and leave out the discarded reading.
 
 **Evidence**
 - **Research mode** ([guide](../docs/rule-guides/research-mode.md)). Any claim, recommendation, or advice. Cite a source for each claim, and run the tool that settles a fact before you state it.
 - **Verify before asking** ([guide](../docs/rule-guides/verify-before-asking.md)). Before a clarifying question. Look in files, config, environment, and tools first; ask only for a judgment or a preference.
+- **Verified work** ([guide](../docs/rule-guides/verified-work.md)). Any task. Research, plan, and build; a fresh `verifier` agent checks each step and reproduces the issue before it confirms the fix. Report only verified results. Ask before new scope.
 - **Verify runtime state** ([guide](../docs/rule-guides/verify-runtime-state.md)). Before you say a component works, is healthy, or is not the cause. Get a live signal this session.
 
 **Before building**
@@ -21,10 +22,8 @@ Each line gives a rule in brief. When its trigger matches your task, open the gu
 - **Filesystem search** ([guide](../docs/rule-guides/filesystem-search.md)). Finding files by name, path, size, or date. Scope the search to a project, worktree, or filter, never a root.
 - **Clean up temporary files** ([guide](../docs/rule-guides/cleanup-temp-files.md)). Creating scratch files or debug dumps. Track them and remove them when the task ends.
 
-**Shipping**
+**Shipping and memory**
 - **Pull request lifecycle**. Before a commit, push, pull request action, or merge. Invoke the `pr-lifecycle` skill; a hook denies those commands until it loads.
 - **Proof before a pull request** ([guide](../docs/rule-guides/proof-before-pull-request.md)). Before you open a pull request. Run the change with and without it, and quote both under "Proof in practice".
 - **Session title** ([guide](../docs/rule-guides/session-title.md)). The session has a tool whose name ends in `__set_session_title`. Set `<emoji> <name>` when the status changes.
-
-**Memory**
 - **Durable facts only** ([guide](../docs/rule-guides/memory-stores-durable-facts.md)). Writing auto-memory or a `MEMORY.md` entry. Keep only a fact that helps a fresh session weeks later.

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

package/scripts/tests/test_verified_work_rule.py

@@ -0,0 +1,36 @@
+"""The always-loaded rules index carries the verified-work flow, and its guide spells out every step."""
+
+from pathlib import Path
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[2]
+INDEX_PATH = PACKAGE_ROOT / "rules" / "index.md"
+GUIDE_PATH = PACKAGE_ROOT / "docs" / "rule-guides" / "verified-work.md"
+
+
+def test_the_index_points_every_session_at_the_verified_work_guide() -> None:
+    index_text = INDEX_PATH.read_text(encoding="utf-8")
+    assert "- **Verified work** ([guide](../docs/rule-guides/verified-work.md))." in index_text
+    assert "reproduces the issue before it confirms the fix" in index_text
+    assert "Ask before new scope." in index_text
+
+
+def test_the_guide_runs_six_steps_in_order() -> None:
+    guide_text = GUIDE_PATH.read_text(encoding="utf-8")
+    all_step_markers = (
+        "1. **Research.**",
+        "2. **Verify the research.**",
+        "3. **Plan.**",
+        "4. **Verify the plan.**",
+        "5. **Implement.**",
+        "6. **Verify the fix.**",
+    )
+    all_positions = [guide_text.index(each_marker) for each_marker in all_step_markers]
+    assert all_positions == sorted(all_positions)
+
+
+def test_the_guide_keeps_the_verifier_apart_and_asks_before_new_scope() -> None:
+    guide_text = GUIDE_PATH.read_text(encoding="utf-8")
+    assert "The verifier is never the agent that did the work." in guide_text
+    assert "A fix whose issue did not reproduce does not pass." in guide_text
+    assert "New scope goes to the user as one question before any of it is built" in guide_text
+    assert "In-scope work runs with no ask." in guide_text