claude-dev-env 8.17.1 → 8.19.0

package/.agents/skills/eli5/SKILL.md

@@ -71,6 +71,8 @@ keep ownership of their native artifact rules while ELI5 supplies the global
 - Preserve an explicit user-supplied output path and an existing artifact path.
 - Keep one artifact path across all updates in the active task or conversation.
 - Keep every page self-contained and browser-ready.
+- Give every source change a card in a digest. The reader reads less and still
+  knows every change, so a dropped change is a defect.
 - Preserve native wrapper, payload, evidence, and file-format contracts owned by
   the named capability skill.
 - Use human review for accuracy, terminology, safety, confidentiality, meaning,
@@ -92,7 +94,19 @@ Process steps in order.
    `~/.claude/rules/asd-ste100-language.md` to every sentence. Frame the topic
    for a beginner, use a large useful visual, keep the text minimal, and update
    the same artifact in place.
-3. **Judgment — share the updated artifact with the user.**
+3. **Deterministic — run the digest check on a summary of many changes.** A
+   summary of a set of changes, such as the pull requests merged in a day, is a
+   digest. Give each change one card marked `data-digest-card="<id>"` that holds
+   its picture and its one-line change. Pass every source id to the check:
+
+   ```bash
+   python "$HOME/.claude/scripts/digest_check.py" <page.html> --expect <id> <id>
+   ```
+
+   The check reports each source id with no card, each card over 25 words, each
+   card without a picture, and more than 40 words outside the cards. Fix every
+   finding and run it again until it prints `CLEAN`.
+4. **Judgment — share the updated artifact with the user.**
 
 ### Examples
 

package/.agents/skills/eli5/reference/task-seeds.md

@@ -7,4 +7,6 @@ the start of the ELI5 process.
 2. Create the artifact when no active path exists and keep it self-contained.
 3. Apply the ASD-STE100 rule to page and response sentences.
 4. Add the concise beginner explanation and useful large visual in place.
-5. Share the updated artifact with the user.
+5. Run `digest_check.py` on a digest with every source id until it prints
+   `CLEAN`.
+6. Share the updated artifact with the user.

package/.agents/skills/step-notes/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: step-notes
+description: Turns the status-line gate for step notes on or off. While on, a hook asks for a short status line naming each tool action, like a progress caption, so the user can follow the session. Use when the user types /step-notes or asks to turn step notes on or off.
+argument-hint: "[on | off | status]"
+---
+
+# /step-notes
+
+The step-notes gate is a PreToolUse hook (`hooks/blocking/step_note_gate.py`). It is off by default. While it is on, each message that calls a tool starts with a short status line naming the action, such as "Reading hooks.json." or "Running the gate tests." A call with no status line fails with "Status line missing".
+
+## Run the toggle
+
+Pass the user's argument through. With no argument, the toggle flips the current state.
+
+Run `python "${CLAUDE_SKILL_DIR}/scripts/toggle_step_notes.py" <on|off|status>`.
+
+Tell the user the line the script prints. The change applies at once, to every session on this machine.
+
+## Status lines
+
+A status line names the action and its target in a few words. One status line covers every call in the same message. Subagent calls pass without a check.
+
+## Layout
+
+| File | Role |
+|---|---|
+| `SKILL.md` | This flow: run the toggle, add status lines while the gate is on |
+| `scripts/toggle_step_notes.py` | The on, off, flip, and status CLI for the flag file |
+| `scripts/test_toggle_step_notes.py` | Behavior tests for each action |
+| `scripts/step_notes_constants/config/constants.py` | Flag path, action names, report lines |

package/.agents/skills/step-notes/scripts/step_notes_constants/config/__init__.py

@@ -0,0 +1 @@
+"""Config package for the toggle_step_notes constants."""

package/.agents/skills/step-notes/scripts/step_notes_constants/config/constants.py

@@ -0,0 +1,12 @@
+"""Flag path, action names, and report lines for the toggle script."""
+
+from pathlib import Path
+
+STEP_NOTES_ON_FLAG_PATH = Path.home() / ".claude" / ".step-notes-on"
+ON_ACTION = "on"
+OFF_ACTION = "off"
+STATUS_ACTION = "status"
+FLIP_ACTION = "flip"
+ALL_ACTIONS = (ON_ACTION, OFF_ACTION, STATUS_ACTION, FLIP_ACTION)
+ON_REPORT = "Step notes are on. Each tool call needs a short status line before it."
+OFF_REPORT = "Step notes are off. Tool calls run without a status line."

package/.agents/skills/step-notes/scripts/test_toggle_step_notes.py

@@ -0,0 +1,62 @@
+import sys
+from pathlib import Path
+
+import pytest
+
+scripts_directory = str(Path(__file__).resolve().parent)
+if scripts_directory not in sys.path:
+    sys.path.insert(0, scripts_directory)
+
+import toggle_step_notes
+
+
+@pytest.fixture
+def on_flag(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
+    flag_path = tmp_path / "config" / ".step-notes-on"
+    monkeypatch.setattr(toggle_step_notes, "STEP_NOTES_ON_FLAG_PATH", flag_path)
+    return flag_path
+
+
+def run_toggle(monkeypatch: pytest.MonkeyPatch, *all_arguments: str) -> None:
+    monkeypatch.setattr(sys, "argv", ["toggle_step_notes.py", *all_arguments])
+    toggle_step_notes.main()
+
+
+def test_should_create_the_flag_when_turned_on(
+    on_flag: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    run_toggle(monkeypatch, "on")
+
+    assert on_flag.exists()
+    assert capsys.readouterr().out.strip() == toggle_step_notes.ON_REPORT
+
+
+def test_should_remove_the_flag_when_turned_off(
+    on_flag: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    on_flag.parent.mkdir(parents=True)
+    on_flag.touch()
+
+    run_toggle(monkeypatch, "off")
+
+    assert not on_flag.exists()
+    assert capsys.readouterr().out.strip() == toggle_step_notes.OFF_REPORT
+
+
+def test_should_flip_off_to_on_and_back_with_no_argument(
+    on_flag: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    run_toggle(monkeypatch)
+    was_on_after_first_flip = on_flag.exists()
+    run_toggle(monkeypatch)
+
+    assert (was_on_after_first_flip, on_flag.exists()) == (True, False)
+
+
+def test_should_report_off_by_default_without_changing_the_flag(
+    on_flag: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    run_toggle(monkeypatch, "status")
+
+    assert not on_flag.exists()
+    assert capsys.readouterr().out.strip() == toggle_step_notes.OFF_REPORT

package/.agents/skills/step-notes/scripts/toggle_step_notes.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""Turn the step-notes gate on or off, or report its state.
+
+The gate is on while STEP_NOTES_ON_FLAG_PATH exists and off by default. `on`
+creates the flag file, `off` removes it, `flip` does whichever changes the
+state, and `status` changes nothing. The flag applies to every session on
+this machine.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+scripts_directory = str(Path(__file__).resolve().parent)
+if scripts_directory not in sys.path:
+    sys.path.insert(0, scripts_directory)
+
+from step_notes_constants.config.constants import (
+    ALL_ACTIONS,
+    FLIP_ACTION,
+    OFF_ACTION,
+    OFF_REPORT,
+    ON_ACTION,
+    ON_REPORT,
+    STEP_NOTES_ON_FLAG_PATH,
+)
+
+
+def apply_action(action: str) -> bool:
+    """Apply one action to the flag file and return whether step notes are on.
+
+    Args:
+        action: One of ALL_ACTIONS. `on` creates the flag file, `off` removes it,
+            `flip` does whichever changes the state, and `status` changes nothing.
+
+    Returns:
+        True when the flag file exists after the action, False otherwise.
+    """
+    is_on = STEP_NOTES_ON_FLAG_PATH.exists()
+    if action == FLIP_ACTION:
+        action = OFF_ACTION if is_on else ON_ACTION
+    if action == ON_ACTION:
+        STEP_NOTES_ON_FLAG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        STEP_NOTES_ON_FLAG_PATH.touch()
+        return True
+    if action == OFF_ACTION:
+        STEP_NOTES_ON_FLAG_PATH.unlink(missing_ok=True)
+        return False
+    return is_on
+
+
+def main() -> int:
+    """Parse the action from the command line, apply it, and print the new state.
+
+    Returns:
+        0 after printing ON_REPORT or OFF_REPORT.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("action", nargs="?", default=FLIP_ACTION, choices=ALL_ACTIONS)
+    parsed_arguments = parser.parse_args()
+    print(ON_REPORT if apply_action(parsed_arguments.action) else OFF_REPORT)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/ever-shipped-skills.mjs

@@ -102,6 +102,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'source-command-logifix',
     'source-command-sr-loop',
     'split-pr',
+    'step-notes',
     'structure-prompt',
     'syncing-submodules',
     'task-build',

package/hooks/blocking/step_note_gate.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""PreToolUse hook that asks for a status line before each tool call.
+
+A status line is a short text block, such as "Reading hooks.json.", that
+opens the message holding the call. It works like a progress caption so the
+user can follow the session.
+
+The gate is off by default. The step-notes skill turns it on by creating the
+flag file at STEP_NOTES_ON_FLAG_PATH, and off again by removing it.
+
+Claude Code writes the assistant message to the transcript after this hook
+starts: 100 to 420 ms later in headless runs, and 650 ms to past 3 s in the
+desktop app. The hook polls the transcript tail until its own tool_use entry
+appears. Three cases pass without a check:
+
+- A subagent call. Its input carries agent_id, its messages live in a separate
+  transcript, and its status lines stay inside the subagent.
+- A call that does not appear before the poll limit.
+- A call whose message is larger than the tail window the hook reads.
+"""
+
+from __future__ import annotations
+
+import enum
+import json
+import os
+import sys
+import time
+from collections.abc import Iterator
+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.step_note_gate_constants import (
+    ALLOW_EXIT_CODE,
+    ASSISTANT_ROLE,
+    BLOCK_EXIT_CODE,
+    BLOCK_MESSAGE,
+    POLL_INTERVAL_SECONDS,
+    POLL_LIMIT_SECONDS,
+    STEP_NOTES_ON_FLAG_PATH,
+    TAIL_WINDOW_BYTES,
+    TEXT_BLOCK_TYPE,
+    TOOL_USE_BLOCK_TYPE,
+    USER_ROLE,
+)
+
+
+class NoteCheck(enum.Enum):
+    NOTED = "noted"
+    MISSING = "missing"
+    CALL_NOT_WRITTEN = "call_not_written"
+    WINDOW_TOO_SHORT = "window_too_short"
+
+
+def read_transcript_tail(transcript_path: Path) -> list[dict]:
+    """Parse the complete JSON lines in the last TAIL_WINDOW_BYTES of the transcript."""
+    try:
+        with transcript_path.open("rb") as transcript_file:
+            file_size = transcript_file.seek(0, os.SEEK_END)
+            window_start = max(0, file_size - TAIL_WINDOW_BYTES)
+            transcript_file.seek(window_start)
+            window_bytes = transcript_file.read()
+    except OSError:
+        return []
+    window_lines = window_bytes.split(b"\n")
+    if window_start > 0:
+        window_lines = window_lines[1:]
+    all_entries = []
+    for each_line in window_lines:
+        try:
+            parsed_entry = json.loads(each_line)
+        except ValueError:
+            continue
+        if isinstance(parsed_entry, dict):
+            all_entries.append(parsed_entry)
+    return all_entries
+
+
+def entry_content_blocks(entry: dict) -> list[dict]:
+    """Return the content blocks of one transcript entry, wrapping plain text as a text block."""
+    content = (entry.get("message") or {}).get("content")
+    if isinstance(content, str):
+        return [{"type": TEXT_BLOCK_TYPE, "text": content}]
+    if isinstance(content, list):
+        return [each_block for each_block in content if isinstance(each_block, dict)]
+    return []
+
+
+def transcript_blocks(all_entries: list[dict]) -> Iterator[tuple[str, dict]]:
+    """Yield (role, content block) pairs for user and assistant entries, in order."""
+    for each_entry in all_entries:
+        role = each_entry.get("type")
+        if role not in (USER_ROLE, ASSISTANT_ROLE):
+            continue
+        for each_block in entry_content_blocks(each_entry):
+            yield role, each_block
+
+
+def is_step_note(block: dict) -> bool:
+    return block.get("type") == TEXT_BLOCK_TYPE and bool(str(block.get("text", "")).strip())
+
+
+def check_step_note(all_entries: list[dict], tool_use_id: str) -> NoteCheck:
+    """Report whether a text block sits between the last user entry and this call.
+
+    A user entry is either a tool result or a prompt, so it marks where the
+    previous step ended. Sibling calls in one message share the note that
+    opens the message.
+    """
+    all_blocks = list(transcript_blocks(all_entries))
+    call_position = next(
+        (
+            position
+            for position, (role, block) in enumerate(all_blocks)
+            if role == ASSISTANT_ROLE
+            and block.get("type") == TOOL_USE_BLOCK_TYPE
+            and block.get("id") == tool_use_id
+        ),
+        None,
+    )
+    if call_position is None:
+        return NoteCheck.CALL_NOT_WRITTEN
+    for each_preceding_role, each_preceding_block in reversed(all_blocks[:call_position]):
+        if each_preceding_role == USER_ROLE:
+            return NoteCheck.MISSING
+        if is_step_note(each_preceding_block):
+            return NoteCheck.NOTED
+    return NoteCheck.WINDOW_TOO_SHORT
+
+
+def wait_for_note_check(transcript_path: Path, tool_use_id: str) -> NoteCheck:
+    deadline = time.monotonic() + POLL_LIMIT_SECONDS
+    while True:
+        note_check = check_step_note(read_transcript_tail(transcript_path), tool_use_id)
+        if note_check is not NoteCheck.CALL_NOT_WRITTEN or time.monotonic() >= deadline:
+            return note_check
+        time.sleep(POLL_INTERVAL_SECONDS)
+
+
+def main() -> int:
+    if not STEP_NOTES_ON_FLAG_PATH.exists():
+        return ALLOW_EXIT_CODE
+    hook_input = json.load(sys.stdin)
+    if hook_input.get("agent_id"):
+        return ALLOW_EXIT_CODE
+    tool_use_id = hook_input.get("tool_use_id")
+    transcript_path = hook_input.get("transcript_path")
+    if not tool_use_id or not transcript_path:
+        return ALLOW_EXIT_CODE
+    if wait_for_note_check(Path(transcript_path), tool_use_id) is NoteCheck.MISSING:
+        sys.stderr.write(BLOCK_MESSAGE)
+        return BLOCK_EXIT_CODE
+    return ALLOW_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/test_step_note_gate.py

@@ -0,0 +1,245 @@
+import io
+import json
+import threading
+from pathlib import Path
+
+import pytest
+
+import step_note_gate
+
+PROMPT_ENTRY = {"type": "user", "message": {"role": "user", "content": "List the folder."}}
+
+
+def assistant_entry(message_id, block):
+    return {
+        "type": "assistant",
+        "message": {"id": message_id, "role": "assistant", "content": [block]},
+    }
+
+
+def note_entry(message_id, text):
+    return assistant_entry(message_id, {"type": "text", "text": text})
+
+
+def call_entry(message_id, tool_use_id):
+    return assistant_entry(
+        message_id,
+        {"type": "tool_use", "id": tool_use_id, "name": "Bash", "input": {"command": "echo one"}},
+    )
+
+
+def result_entry(tool_use_id):
+    return {
+        "type": "user",
+        "message": {
+            "role": "user",
+            "content": [{"type": "tool_result", "tool_use_id": tool_use_id, "content": "one"}],
+        },
+    }
+
+
+def write_transcript(path, all_entries):
+    path.write_text("".join(json.dumps(each) + "\n" for each in all_entries), encoding="utf-8")
+
+
+def run_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    transcript_path: Path,
+    tool_use_id: str,
+    **extra_input: str,
+) -> tuple[int, str]:
+    hook_input = {
+        "hook_event_name": "PreToolUse",
+        "tool_name": "Bash",
+        "tool_use_id": tool_use_id,
+        "transcript_path": str(transcript_path),
+        **extra_input,
+    }
+    monkeypatch.setattr("sys.stdin", io.StringIO(json.dumps(hook_input)))
+    exit_code = step_note_gate.main()
+    return exit_code, capsys.readouterr().err
+
+
+@pytest.fixture(autouse=True)
+def isolated_gate(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(step_note_gate, "POLL_LIMIT_SECONDS", 0.3)
+    on_flag_path = tmp_path / ".step-notes-on"
+    on_flag_path.write_text("", encoding="utf-8")
+    monkeypatch.setattr(step_note_gate, "STEP_NOTES_ON_FLAG_PATH", on_flag_path)
+
+
+def test_should_allow_a_call_that_follows_a_note_in_its_message(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    transcript = tmp_path / "session.jsonl"
+    write_transcript(
+        transcript,
+        [PROMPT_ENTRY, note_entry("m1", "Listing the folder."), call_entry("m1", "call_1")],
+    )
+
+    exit_code, stderr_text = run_gate(monkeypatch, capsys, transcript, "call_1")
+
+    assert (exit_code, stderr_text) == (0, "")
+
+
+def test_should_block_a_call_with_no_note_after_the_previous_result(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    transcript = tmp_path / "session.jsonl"
+    write_transcript(
+        transcript,
+        [
+            PROMPT_ENTRY,
+            note_entry("m1", "Listing the folder."),
+            call_entry("m1", "call_1"),
+            result_entry("call_1"),
+            call_entry("m2", "call_2"),
+        ],
+    )
+
+    exit_code, stderr_text = run_gate(monkeypatch, capsys, transcript, "call_2")
+
+    assert exit_code == 2
+    assert stderr_text == step_note_gate.BLOCK_MESSAGE
+
+
+def test_should_allow_a_bare_call_while_the_on_flag_is_absent(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    transcript = tmp_path / "session.jsonl"
+    write_transcript(transcript, [PROMPT_ENTRY, call_entry("m1", "call_1")])
+    step_note_gate.STEP_NOTES_ON_FLAG_PATH.unlink()
+
+    exit_code, _ = run_gate(monkeypatch, capsys, transcript, "call_1")
+
+    assert exit_code == 0
+
+
+def test_should_block_the_first_call_after_a_prompt_when_no_note_precedes_it(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    transcript = tmp_path / "session.jsonl"
+    write_transcript(transcript, [PROMPT_ENTRY, call_entry("m1", "call_1")])
+
+    exit_code, _ = run_gate(monkeypatch, capsys, transcript, "call_1")
+
+    assert exit_code == 2
+
+
+def test_should_block_when_the_only_text_is_blank(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    transcript = tmp_path / "session.jsonl"
+    write_transcript(
+        transcript, [PROMPT_ENTRY, note_entry("m1", "  \n "), call_entry("m1", "call_1")]
+    )
+
+    exit_code, _ = run_gate(monkeypatch, capsys, transcript, "call_1")
+
+    assert exit_code == 2
+
+
+def test_should_allow_every_parallel_call_under_one_note(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    transcript = tmp_path / "session.jsonl"
+    write_transcript(
+        transcript,
+        [
+            PROMPT_ENTRY,
+            note_entry("m1", "Running two echoes together."),
+            call_entry("m1", "call_1"),
+            call_entry("m1", "call_2"),
+        ],
+    )
+
+    first_exit_code, _ = run_gate(monkeypatch, capsys, transcript, "call_1")
+    second_exit_code, _ = run_gate(monkeypatch, capsys, transcript, "call_2")
+
+    assert (first_exit_code, second_exit_code) == (0, 0)
+
+
+def test_should_see_a_note_the_harness_writes_after_the_hook_starts(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    transcript = tmp_path / "session.jsonl"
+    write_transcript(transcript, [PROMPT_ENTRY])
+    late_lines = "".join(
+        json.dumps(each) + "\n"
+        for each in (note_entry("m1", "Listing the folder."), call_entry("m1", "call_1"))
+    )
+
+    def append_late_lines():
+        with transcript.open("a", encoding="utf-8") as transcript_file:
+            transcript_file.write(late_lines)
+
+    writer = threading.Timer(0.15, append_late_lines)
+    writer.start()
+    exit_code, _ = run_gate(monkeypatch, capsys, transcript, "call_1")
+    writer.join()
+
+    assert exit_code == 0
+
+
+def test_should_block_a_bare_call_the_harness_writes_after_the_hook_starts(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    transcript = tmp_path / "session.jsonl"
+    write_transcript(transcript, [PROMPT_ENTRY])
+
+    def append_late_call():
+        with transcript.open("a", encoding="utf-8") as transcript_file:
+            transcript_file.write(json.dumps(call_entry("m1", "call_1")) + "\n")
+
+    writer = threading.Timer(0.15, append_late_call)
+    writer.start()
+    exit_code, _ = run_gate(monkeypatch, capsys, transcript, "call_1")
+    writer.join()
+
+    assert exit_code == 2
+
+
+def test_should_allow_a_call_that_never_reaches_the_transcript(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    transcript = tmp_path / "session.jsonl"
+    write_transcript(transcript, [PROMPT_ENTRY])
+
+    exit_code, _ = run_gate(monkeypatch, capsys, transcript, "call_1")
+
+    assert exit_code == 0
+
+
+def test_should_allow_a_subagent_call_even_without_a_note(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    transcript = tmp_path / "session.jsonl"
+    write_transcript(transcript, [PROMPT_ENTRY, call_entry("m1", "call_1")])
+
+    exit_code, _ = run_gate(
+        monkeypatch, capsys, transcript, "call_1", agent_id="a1", agent_type="general-purpose"
+    )
+
+    assert exit_code == 0
+
+
+def test_should_allow_a_call_whose_message_outgrows_the_tail_window(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    transcript = tmp_path / "session.jsonl"
+    write_transcript(
+        transcript,
+        [
+            PROMPT_ENTRY,
+            call_entry("m1", "call_0"),
+            result_entry("call_0"),
+            call_entry("m2", "call_1"),
+        ],
+    )
+    call_line_bytes = len(json.dumps(call_entry("m2", "call_1")).encode("utf-8")) + 1
+    monkeypatch.setattr(step_note_gate, "TAIL_WINDOW_BYTES", call_line_bytes + 10)
+
+    exit_code, _ = run_gate(monkeypatch, capsys, transcript, "call_1")
+
+    assert exit_code == 0

package/hooks/hooks.json

@@ -59,6 +59,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/lifecycle/nested_project_hooks.py",
             "timeout": 120
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/step_note_gate.py",
+            "timeout": 15
           }
         ]
       }

package/hooks/hooks_constants/step_note_gate_constants.py

@@ -0,0 +1,19 @@
+"""Constants for the step-note gate PreToolUse hook."""
+
+from pathlib import Path
+
+STEP_NOTES_ON_FLAG_PATH = Path.home() / ".claude" / ".step-notes-on"
+POLL_INTERVAL_SECONDS = 0.05
+POLL_LIMIT_SECONDS = 8.0
+TAIL_WINDOW_BYTES = 1_000_000
+BLOCK_EXIT_CODE = 2
+ALLOW_EXIT_CODE = 0
+USER_ROLE = "user"
+ASSISTANT_ROLE = "assistant"
+TEXT_BLOCK_TYPE = "text"
+TOOL_USE_BLOCK_TYPE = "tool_use"
+BLOCK_MESSAGE = (
+    "Status line missing. Start the message with a short status line that names "
+    "this action, such as 'Reading hooks.json.', then retry the call. "
+    "The user turns this gate on and off with /step-notes."
+)

package/package.json

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