claude-dev-env 8.50.1 → 8.51.1

package/docs/rule-guides/session-title.md

@@ -0,0 +1,25 @@
+Back to the [rule entry](../../rules/session-title.md).
+
+# Status in the session title
+
+**When this applies:** The session has a tool whose name ends in `__set_session_title`, such as `mcp__claude-code-remote__set_session_title` in a cloud session or `mcp__ccd_session_mgmt__set_session_title` in the desktop app.
+
+## Rule
+
+Before each turn ends, set the title to `<emoji> <name>`. Get the session id from `get_session` with no `session_id` when the tool asks for one.
+
+## Status emoji
+
+| Emoji | Use it when |
+|---|---|
+| Red flag | The user must act: a question, an approval, or a step only the user can do. |
+| Check mark | The work is done: merged, or nothing left. |
+| Hourglass | Work, CI, or a merge queue still runs and nothing waits on the user. |
+
+## Name
+
+The name has 25 characters or fewer and names the main change or outcome in concrete nouns, such as `Broker gate + replay rule`. Join two parts with ` + `. Use sentence case and no end punctuation. Leave out dates, IDs, branch names, and filler words such as "work on" or "fix for". Rename the session when the scope of the work changes.
+
+## Enforcement
+
+`hooks/blocking/session_title_format_gate.py` denies a malformed title. `hooks/blocking/session_title_stop_gate.py` blocks the end of a turn that set no title.

package/hooks/blocking/session_title_format_gate.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""PreToolUse hook that keeps every session title in the '<emoji> <name>' shape.
+
+The gate reads the title a tool whose name ends in __set_session_title is about
+to set. It denies the call when the title breaks one of these rules:
+
+- It starts with one status emoji (red flag, check mark or hourglass) and a space.
+- It is one line.
+- The name after the emoji has 1 to 25 characters.
+- It ends without punctuation.
+- The name starts with a capital letter.
+- The name holds no run of three or more digits and no slash.
+
+A call with no string title passes, so a tool with another schema keeps working.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.session_title_constants import (
+    ALLOW_EXIT_CODE,
+    BLOCK_EXIT_CODE,
+    BRANCH_NAME_MESSAGE,
+    FORMAT_GATE_EVENT_NAME,
+    FORMAT_RETRY_INSTRUCTION,
+    IDENTIFIER_DIGITS_PATTERN,
+    IDENTIFIER_MESSAGE,
+    MAXIMUM_NAME_LENGTH,
+    NAME_LENGTH_MESSAGE,
+    SENTENCE_CASE_MESSAGE,
+    SINGLE_LINE_MESSAGE,
+    STATUS_PREFIX_MESSAGE,
+    STATUS_PREFIX_PATTERN,
+    TITLE_INPUT_KEY,
+    TITLE_TOOL_NAME_PATTERN,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+    TRAILING_PUNCTUATION,
+    TRAILING_PUNCTUATION_MESSAGE,
+)
+
+
+def _name_violation(name: str) -> str | None:
+    if name != name.strip() or not 1 <= len(name) <= MAXIMUM_NAME_LENGTH:
+        return NAME_LENGTH_MESSAGE.format(maximum=MAXIMUM_NAME_LENGTH, length=len(name.strip()))
+    if name[-1] in TRAILING_PUNCTUATION:
+        return TRAILING_PUNCTUATION_MESSAGE
+    if name[0].isalpha() and not name[0].isupper():
+        return SENTENCE_CASE_MESSAGE
+    if IDENTIFIER_DIGITS_PATTERN.search(name):
+        return IDENTIFIER_MESSAGE
+    if "/" in name:
+        return BRANCH_NAME_MESSAGE
+    return None
+
+
+def title_format_violation(title: str) -> str | None:
+    """Return the first rule a session title breaks, or None when it is well formed.
+
+    >>> title_format_violation("\u23f3 Broker gate + replay rule") is None
+    True
+    >>> title_format_violation("Broker gate") == STATUS_PREFIX_MESSAGE
+    True
+
+    Args:
+        title: The title the tool call would set.
+
+    Returns:
+        The message for the broken rule, or None.
+    """
+    if "\n" in title or "\r" in title:
+        return SINGLE_LINE_MESSAGE
+    status_prefix = STATUS_PREFIX_PATTERN.match(title)
+    if status_prefix is None:
+        return STATUS_PREFIX_MESSAGE
+    return _name_violation(title[status_prefix.end() :])
+
+
+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)
+    if not isinstance(tool_name, str) or not TITLE_TOOL_NAME_PATTERN.match(tool_name):
+        return ALLOW_EXIT_CODE
+    tool_input = hook_input.get(TOOL_INPUT_KEY)
+    title = tool_input.get(TITLE_INPUT_KEY) if isinstance(tool_input, dict) else None
+    if not isinstance(title, str):
+        return ALLOW_EXIT_CODE
+    violation = title_format_violation(title)
+    if violation is None:
+        return ALLOW_EXIT_CODE
+    block_reason = violation + FORMAT_RETRY_INSTRUCTION
+    log_hook_block(
+        Path(__file__).name,
+        FORMAT_GATE_EVENT_NAME,
+        block_reason,
+        tool_name=tool_name,
+        offending_input_preview=title,
+    )
+    sys.stderr.write(block_reason)
+    return BLOCK_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/session_title_stop_gate.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""Stop hook that ends each turn only after the session title shows its status.
+
+A turn starts at the latest user prompt in the transcript, skipping tool
+results and meta entries. The turn may end once a tool whose name ends in
+__set_session_title ran in it without error. Otherwise the hook blocks the
+stop once and tells the model to set '<emoji> <name>'.
+
+The hook stays silent when:
+
+- the stop is already a retry after a block (stop_hook_active is true);
+- the session shows no title tool: no remote session id in the environment,
+  and no title tool named anywhere in the transcript;
+- the transcript cannot be read.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.session_title_constants import (
+    ALLOW_EXIT_CODE,
+    BLOCK_DECISION,
+    DEFERRED_TOOL_ATTACHMENT_TYPES,
+    REMOTE_SESSION_ENVIRONMENT_VARIABLE,
+    REMOTE_TITLE_TOOL_NAME,
+    STOP_BLOCK_REASON,
+    STOP_GATE_EVENT_NAME,
+    STOP_HOOK_ACTIVE_KEY,
+    TITLE_TOOL_NAME_PATTERN,
+    TRANSCRIPT_PATH_KEY,
+    UNKNOWN_TITLE_TOOL_NAME,
+)
+from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
+
+
+def _content_blocks(all_entry_fields: dict[str, object]) -> list[dict[str, object]]:
+    message = all_entry_fields.get("message")
+    content = message.get("content") if isinstance(message, dict) else None
+    if not isinstance(content, list):
+        return []
+    return [each_block for each_block in content if isinstance(each_block, dict)]
+
+
+def _is_user_prompt(all_entry_fields: dict[str, object]) -> bool:
+    if all_entry_fields.get("type") != "user" or all_entry_fields.get("isMeta") is True:
+        return False
+    message = all_entry_fields.get("message")
+    if isinstance(message, dict) and isinstance(message.get("content"), str):
+        return True
+    return any(each_block.get("type") == "text" for each_block in _content_blocks(all_entry_fields))
+
+
+def _title_tool_names_in(all_entry_fields: dict[str, object]) -> list[str]:
+    all_names: list[str] = []
+    if all_entry_fields.get("type") == "assistant":
+        all_names = [
+            str(each_block.get("name"))
+            for each_block in _content_blocks(all_entry_fields)
+            if each_block.get("type") == "tool_use"
+        ]
+    attachment = all_entry_fields.get("attachment")
+    if isinstance(attachment, dict) and attachment.get("type") in DEFERRED_TOOL_ATTACHMENT_TYPES:
+        all_names += [str(each_name) for each_name in attachment.get("addedNames") or []]
+        all_names += [
+            str(each_record.get("name"))
+            for each_record in attachment.get("entries") or []
+            if isinstance(each_record, dict)
+        ]
+    return [each_name for each_name in all_names if TITLE_TOOL_NAME_PATTERN.match(each_name)]
+
+
+def _is_title_call(entry_type: object, all_block_fields: dict[str, object]) -> bool:
+    return (
+        entry_type == "assistant"
+        and all_block_fields.get("type") == "tool_use"
+        and bool(TITLE_TOOL_NAME_PATTERN.match(str(all_block_fields.get("name"))))
+    )
+
+
+def _title_set_since(all_turn_entries: list[dict[str, object]]) -> bool:
+    all_entry_blocks = [
+        (each_entry.get("type"), each_block)
+        for each_entry in all_turn_entries
+        for each_block in _content_blocks(each_entry)
+    ]
+    all_title_call_ids = {
+        str(each_block.get("id"))
+        for each_entry_type, each_block in all_entry_blocks
+        if _is_title_call(each_entry_type, each_block)
+    }
+    return any(
+        each_block.get("type") == "tool_result"
+        and str(each_block.get("tool_use_id")) in all_title_call_ids
+        and not each_block.get("is_error")
+        for _, each_block in all_entry_blocks
+    )
+
+
+def _turn_start_index(all_entries: list[dict[str, object]]) -> int:
+    return max(
+        (
+            each_index
+            for each_index, each_entry in enumerate(all_entries)
+            if _is_user_prompt(each_entry)
+        ),
+        default=0,
+    )
+
+
+def stop_block_reason(all_entries: list[dict[str, object]], is_remote_session: bool) -> str | None:
+    """Return the block reason when this turn has not set the title, else None.
+
+    ::
+
+        prompt -> set_session_title -> ok result   => None
+        prompt -> work, no title call              => block reason
+        no title tool anywhere, not remote         => None
+
+    Args:
+        all_entries: The transcript entries, oldest first.
+        is_remote_session: True when the session runs in a cloud session with a title tool.
+
+    Returns:
+        The reason to send back to the model, or None to let the turn end.
+    """
+    all_seen_tool_names = [
+        each_name for each_entry in all_entries for each_name in _title_tool_names_in(each_entry)
+    ]
+    if not all_seen_tool_names and not is_remote_session:
+        return None
+    if _title_set_since(all_entries[_turn_start_index(all_entries) :]):
+        return None
+    if all_seen_tool_names:
+        return STOP_BLOCK_REASON.format(tool_name=all_seen_tool_names[-1])
+    tool_name = REMOTE_TITLE_TOOL_NAME if is_remote_session else UNKNOWN_TITLE_TOOL_NAME
+    return STOP_BLOCK_REASON.format(tool_name=tool_name)
+
+
+def _parsed_entry(line: str) -> dict[str, object] | None:
+    try:
+        parsed_entry = json.loads(line)
+    except json.JSONDecodeError:
+        return None
+    return parsed_entry if isinstance(parsed_entry, dict) else None
+
+
+def _read_entries(transcript_path: str) -> list[dict[str, object]]:
+    with open(transcript_path, encoding=UTF8_ENCODING, errors=DECODE_ERRORS_POLICY) as transcript:
+        all_lines = transcript.readlines()
+    all_parsed_entries = [_parsed_entry(each_line) for each_line in all_lines]
+    return [each_entry for each_entry in all_parsed_entries if each_entry is not None]
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None or hook_input.get(STOP_HOOK_ACTIVE_KEY):
+        return ALLOW_EXIT_CODE
+    transcript_path = hook_input.get(TRANSCRIPT_PATH_KEY)
+    if not isinstance(transcript_path, str) or not transcript_path:
+        return ALLOW_EXIT_CODE
+    try:
+        all_entries = _read_entries(transcript_path)
+    except OSError:
+        return ALLOW_EXIT_CODE
+    is_remote_session = bool(os.environ.get(REMOTE_SESSION_ENVIRONMENT_VARIABLE))
+    block_reason = stop_block_reason(all_entries, is_remote_session)
+    if block_reason is None:
+        return ALLOW_EXIT_CODE
+    log_hook_block(Path(__file__).name, STOP_GATE_EVENT_NAME, block_reason)
+    sys.stdout.write(json.dumps({"decision": BLOCK_DECISION, "reason": block_reason}))
+    return ALLOW_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/test_session_title_format_gate.py

@@ -0,0 +1,130 @@
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+import session_title_format_gate
+from hooks_constants.session_title_constants import (
+    BRANCH_NAME_MESSAGE,
+    IDENTIFIER_MESSAGE,
+    SENTENCE_CASE_MESSAGE,
+    SINGLE_LINE_MESSAGE,
+    STATUS_PREFIX_MESSAGE,
+    TRAILING_PUNCTUATION_MESSAGE,
+)
+
+REMOTE_TITLE_TOOL = "mcp__claude-code-remote__set_session_title"
+DESKTOP_TITLE_TOOL = "mcp__ccd_session_mgmt__set_session_title"
+RED_FLAG = "\U0001f6a9"
+CHECK_MARK = "✅"
+HOURGLASS = "⏳"
+
+
+def run_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tool_name: str,
+    tool_input: object,
+) -> tuple[int, 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 = session_title_format_gate.main()
+    return exit_code, capsys.readouterr().err
+
+
+@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("tool_name", [REMOTE_TITLE_TOOL, DESKTOP_TITLE_TOOL])
+@pytest.mark.parametrize(
+    "title",
+    [
+        f"{HOURGLASS} Broker gate + replay rule",
+        f"{CHECK_MARK} Session title gate",
+        f"{RED_FLAG}️ Runner sign-in",
+        f"{RED_FLAG} CI gate + docs",
+    ],
+)
+def test_should_allow_a_well_formed_title_on_each_title_tool(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tool_name: str, title: str
+) -> None:
+    assert run_gate(monkeypatch, capsys, tool_name, {"session_id": "s", "title": title}) == (0, "")
+
+
+@pytest.mark.parametrize(
+    ("title", "expected_message"),
+    [
+        ("Broker gate + replay rule", STATUS_PREFIX_MESSAGE),
+        ("\U0001f680 Broker gate", STATUS_PREFIX_MESSAGE),
+        (f"{HOURGLASS}Broker gate", STATUS_PREFIX_MESSAGE),
+        (f"{HOURGLASS} Broker gate\nand more", SINGLE_LINE_MESSAGE),
+        (f"{HOURGLASS} Broker gate.", TRAILING_PUNCTUATION_MESSAGE),
+        (f"{HOURGLASS} broker gate", SENTENCE_CASE_MESSAGE),
+        (f"{HOURGLASS} PR 5608 review", IDENTIFIER_MESSAGE),
+        (f"{HOURGLASS} Plan for 2026-10-04", IDENTIFIER_MESSAGE),
+        (f"{HOURGLASS} Feature/title cleanup", BRANCH_NAME_MESSAGE),
+    ],
+)
+def test_should_deny_a_title_and_name_the_rule_it_breaks(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    title: str,
+    expected_message: str,
+) -> None:
+    exit_code, stderr_text = run_gate(monkeypatch, capsys, REMOTE_TITLE_TOOL, {"title": title})
+    assert exit_code == 2
+    assert stderr_text.startswith(expected_message)
+    assert "Call the title tool again" in stderr_text
+
+
+def test_should_deny_a_name_longer_than_twenty_five_characters(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        DESKTOP_TITLE_TOOL,
+        {"title": f"{CHECK_MARK} Broker gate and replay rules"},
+    )
+    assert exit_code == 2
+    assert "1 to 25 characters; it has 28" in stderr_text
+
+
+def test_should_allow_a_name_of_exactly_twenty_five_characters(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    title = f"{CHECK_MARK} " + "A" * 25
+    assert run_gate(monkeypatch, capsys, REMOTE_TITLE_TOOL, {"title": title}) == (0, "")
+
+
+@pytest.mark.parametrize(
+    ("tool_name", "tool_input"),
+    [
+        ("mcp__chat__update_message", {"title": "fix stuff."}),
+        (REMOTE_TITLE_TOOL, {"name": "fix stuff."}),
+        (REMOTE_TITLE_TOOL, "fix stuff."),
+    ],
+)
+def test_should_leave_other_tools_and_schemas_alone(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tool_name: str,
+    tool_input: object,
+) -> None:
+    assert run_gate(monkeypatch, capsys, tool_name, tool_input) == (0, "")
+
+
+def test_title_format_violation_returns_none_for_a_good_title() -> None:
+    assert session_title_format_gate.title_format_violation(f"{RED_FLAG} Runner sign-in") is None
+
+
+def test_title_format_violation_names_the_missing_emoji() -> None:
+    assert (
+        session_title_format_gate.title_format_violation("Runner sign-in") == STATUS_PREFIX_MESSAGE
+    )

package/hooks/blocking/test_session_title_stop_gate.py

@@ -0,0 +1,209 @@
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+import session_title_stop_gate
+
+REMOTE_TITLE_TOOL = "mcp__claude-code-remote__set_session_title"
+DESKTOP_TITLE_TOOL = "mcp__ccd_session_mgmt__set_session_title"
+REMOTE_SESSION_VARIABLE = "CLAUDE_CODE_REMOTE_SESSION_ID"
+
+
+def prompt(text: str) -> dict[str, object]:
+    return {"type": "user", "message": {"role": "user", "content": text}}
+
+
+def meta_prompt(text: str) -> dict[str, object]:
+    return {
+        "type": "user",
+        "isMeta": True,
+        "message": {"role": "user", "content": [{"type": "text", "text": text}]},
+    }
+
+
+def tool_call(tool_use_id: str, name: str) -> dict[str, object]:
+    return {
+        "type": "assistant",
+        "message": {
+            "role": "assistant",
+            "content": [{"type": "tool_use", "id": tool_use_id, "name": name, "input": {}}],
+        },
+    }
+
+
+def tool_result(tool_use_id: str, is_error: bool = False) -> dict[str, object]:
+    return {
+        "type": "user",
+        "message": {
+            "role": "user",
+            "content": [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": tool_use_id,
+                    "content": "ok",
+                    "is_error": is_error,
+                }
+            ],
+        },
+    }
+
+
+def deferred_tools(*all_names: str) -> dict[str, object]:
+    return {
+        "type": "attachment",
+        "attachment": {"type": "deferred_tools_delta", "addedNames": list(all_names)},
+    }
+
+
+def run_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: Path,
+    all_entries: list[dict[str, object]],
+    stop_hook_active: bool = False,
+) -> tuple[int, str]:
+    transcript_path = tmp_path / "session.jsonl"
+    transcript_path.write_text(
+        "".join(json.dumps(each) + "\n" for each in all_entries), encoding="utf-8"
+    )
+    hook_input = {
+        "hook_event_name": "Stop",
+        "transcript_path": str(transcript_path),
+        "stop_hook_active": stop_hook_active,
+    }
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    exit_code = session_title_stop_gate.main()
+    return exit_code, capsys.readouterr().out
+
+
+@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))
+    monkeypatch.delenv(REMOTE_SESSION_VARIABLE, raising=False)
+
+
+def test_should_block_a_remote_turn_that_set_no_title(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    monkeypatch.setenv(REMOTE_SESSION_VARIABLE, "cse_1")
+    exit_code, stdout_text = run_gate(
+        monkeypatch,
+        capsys,
+        tmp_path,
+        [prompt("Fix the runner"), tool_call("t1", "Bash"), tool_result("t1")],
+    )
+    decision = json.loads(stdout_text)
+    assert exit_code == 0
+    assert decision["decision"] == "block"
+    assert REMOTE_TITLE_TOOL in decision["reason"]
+
+
+def test_should_pass_a_turn_whose_title_call_succeeded(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    monkeypatch.setenv(REMOTE_SESSION_VARIABLE, "cse_1")
+    all_entries = [prompt("Fix the runner"), tool_call("t1", REMOTE_TITLE_TOOL), tool_result("t1")]
+    assert run_gate(monkeypatch, capsys, tmp_path, all_entries) == (0, "")
+
+
+def test_should_block_when_the_only_title_call_was_denied(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    monkeypatch.setenv(REMOTE_SESSION_VARIABLE, "cse_1")
+    all_entries = [
+        prompt("Fix the runner"),
+        tool_call("t1", REMOTE_TITLE_TOOL),
+        tool_result("t1", is_error=True),
+    ]
+    _, stdout_text = run_gate(monkeypatch, capsys, tmp_path, all_entries)
+    assert json.loads(stdout_text)["decision"] == "block"
+
+
+def test_should_block_when_the_title_was_set_only_in_an_earlier_turn(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    all_entries = [
+        prompt("Fix the runner"),
+        tool_call("t1", DESKTOP_TITLE_TOOL),
+        tool_result("t1"),
+        prompt("Now open the pull request"),
+        tool_call("t2", "Bash"),
+        tool_result("t2"),
+    ]
+    _, stdout_text = run_gate(monkeypatch, capsys, tmp_path, all_entries)
+    assert DESKTOP_TITLE_TOOL in json.loads(stdout_text)["reason"]
+
+
+def test_should_keep_a_title_set_before_a_meta_entry_in_the_same_turn(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    monkeypatch.setenv(REMOTE_SESSION_VARIABLE, "cse_1")
+    all_entries = [
+        prompt("Fix the runner"),
+        tool_call("t1", REMOTE_TITLE_TOOL),
+        tool_result("t1"),
+        meta_prompt("Base directory for this skill: /skills/pr-lifecycle"),
+    ]
+    assert run_gate(monkeypatch, capsys, tmp_path, all_entries) == (0, "")
+
+
+def test_should_block_a_desktop_session_once_its_title_tool_is_listed(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    all_entries = [deferred_tools("TaskCreate", DESKTOP_TITLE_TOOL), prompt("Fix the runner")]
+    _, stdout_text = run_gate(monkeypatch, capsys, tmp_path, all_entries)
+    assert DESKTOP_TITLE_TOOL in json.loads(stdout_text)["reason"]
+
+
+def test_should_stay_silent_in_a_session_with_no_title_tool(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    all_entries = [
+        deferred_tools("TaskCreate"),
+        prompt("Fix the runner"),
+        tool_call("t1", "Bash"),
+        tool_result("t1"),
+    ]
+    assert run_gate(monkeypatch, capsys, tmp_path, all_entries) == (0, "")
+
+
+def test_should_stay_silent_on_the_retry_after_a_block(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    monkeypatch.setenv(REMOTE_SESSION_VARIABLE, "cse_1")
+    assert run_gate(
+        monkeypatch, capsys, tmp_path, [prompt("Fix the runner")], stop_hook_active=True
+    ) == (0, "")
+
+
+def test_should_stay_silent_when_the_transcript_is_missing(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    monkeypatch.setenv(REMOTE_SESSION_VARIABLE, "cse_1")
+    hook_input = {"hook_event_name": "Stop", "transcript_path": str(tmp_path / "absent.jsonl")}
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    assert session_title_stop_gate.main() == 0
+    assert capsys.readouterr().out == ""
+
+
+def test_stop_block_reason_returns_none_after_a_successful_title_call() -> None:
+    all_entries = [prompt("Fix the runner"), tool_call("t1", REMOTE_TITLE_TOOL), tool_result("t1")]
+    assert session_title_stop_gate.stop_block_reason(all_entries, is_remote_session=True) is None
+
+
+def test_stop_block_reason_names_the_seen_tool_when_the_turn_has_no_title() -> None:
+    all_entries = [
+        prompt("Fix the runner"),
+        tool_call("t1", DESKTOP_TITLE_TOOL),
+        tool_result("t1"),
+        prompt("Next"),
+    ]
+    block_reason = session_title_stop_gate.stop_block_reason(all_entries, is_remote_session=False)
+    assert block_reason is not None and DESKTOP_TITLE_TOOL in block_reason

package/hooks/hooks.json

@@ -117,6 +117,16 @@
           }
         ]
       },
+      {
+        "matcher": "mcp__.*__set_session_title",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/session_title_format_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "mcp__hearthbot__start_thread_session",
         "hooks": [
@@ -251,6 +261,17 @@
         ]
       }
     ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/session_title_stop_gate.py",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",

package/hooks/hooks_constants/session_title_constants.py

@@ -0,0 +1,55 @@
+"""Constants for session_title_format_gate.py and session_title_stop_gate.py."""
+
+import re
+
+TITLE_TOOL_NAME_PATTERN = re.compile(r"^mcp__.+__set_session_title$")
+REMOTE_SESSION_ENVIRONMENT_VARIABLE = "CLAUDE_CODE_REMOTE_SESSION_ID"
+TITLE_INPUT_KEY = "title"
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+TRANSCRIPT_PATH_KEY = "transcript_path"
+STOP_HOOK_ACTIVE_KEY = "stop_hook_active"
+FORMAT_GATE_EVENT_NAME = "PreToolUse"
+STOP_GATE_EVENT_NAME = "Stop"
+ALLOW_EXIT_CODE = 0
+BLOCK_EXIT_CODE = 2
+BLOCK_DECISION = "block"
+DEFERRED_TOOL_ATTACHMENT_TYPES = frozenset({"deferred_tools_delta", "deferred_tools_record"})
+
+STATUS_PREFIX_PATTERN = re.compile("^(\U0001f6a9|\u2705|\u23f3)\ufe0f? (?=\\S)")
+MAXIMUM_NAME_LENGTH = 25
+TRAILING_PUNCTUATION = ".!?,;:"
+IDENTIFIER_DIGITS_PATTERN = re.compile(r"\d{3,}")
+
+STATUS_PREFIX_MESSAGE = (
+    "The title must start with one status emoji and one space:"
+    " \U0001f6a9 when the user must act, \u2705 when the work is done,"
+    " \u23f3 while work runs and nothing waits on the user."
+)
+SINGLE_LINE_MESSAGE = "The title must be one line."
+NAME_LENGTH_MESSAGE = "The name after the emoji must be 1 to {maximum} characters; it has {length}."
+TRAILING_PUNCTUATION_MESSAGE = "The title must end without punctuation."
+SENTENCE_CASE_MESSAGE = "The name must start with a capital letter (sentence case)."
+IDENTIFIER_MESSAGE = "The name must hold no dates, IDs or numbers of three or more digits."
+BRANCH_NAME_MESSAGE = "The name must hold no branch names or paths (no '/')."
+FORMAT_RETRY_INSTRUCTION = (
+    " Call the title tool again with '<emoji> <name>', where the name names"
+    " the main change or outcome in concrete nouns, such as"
+    " '\u23f3 Broker gate + replay rule'."
+)
+
+STOP_BLOCK_REASON = (
+    "Before you end this turn, set the session title to its current status."
+    " Call the session title tool ({tool_name}); when it asks for a session id,"
+    " get it from get_session with no session_id."
+    " Use the shape '<emoji> <name>'."
+    " Emoji: \U0001f6a9 when the user must act (a question, an approval, or a step only the user can do);"
+    " \u2705 when the work is done (merged, or nothing left);"
+    " \u23f3 while work, CI or a merge queue still runs and nothing waits on the user."
+    " Name: 25 characters or fewer, the main change or outcome in concrete nouns,"
+    " two parts joined with ' + ', sentence case, no end punctuation,"
+    " no dates, IDs, branch names or filler words."
+    " Rename it when the scope of the work has changed."
+)
+REMOTE_TITLE_TOOL_NAME = "mcp__claude-code-remote__set_session_title"
+UNKNOWN_TITLE_TOOL_NAME = "its name ends in __set_session_title"

package/package.json

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

package/rules/session-title.md

@@ -0,0 +1,9 @@
+# Status in the session title
+
+**When:** The session has a tool whose name ends in `__set_session_title`.
+
+Before each turn ends, set the title to `<emoji> <name>`. Use the red flag when the user must act, the check mark when the work is done, and the hourglass while work, CI, or a merge queue runs. The name has 25 characters or fewer, in sentence case, with concrete nouns and no IDs, dates, or branch names.
+
+**Enforcement:** `hooks/blocking/session_title_format_gate.py` denies a malformed title; `hooks/blocking/session_title_stop_gate.py` blocks a turn end with no title.
+
+**Full text:** [`docs/rule-guides/session-title.md`](../docs/rule-guides/session-title.md). Read it for the emoji table and naming rules.

package/scripts/policy_lint/adapter_configuration.py

@@ -132,6 +132,8 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
         hooks/blocking/reply_length_gate.py              -> exempt
         hooks/blocking/edit_marker_gate.py               -> exempt
         hooks/blocking/verify_before_acting.py           -> exempt
+        hooks/blocking/session_title_format_gate.py      -> exempt
+        hooks/blocking/session_title_stop_gate.py        -> exempt
         hooks/blocking/some_new_blocker.py               -> flagged
 
     The Bash PreToolUse dispatcher sits under ``blocking/`` for layout reasons
@@ -156,6 +158,10 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
     The verify-before-acting hook runs after a mutating call has finished. It
     asks the model to check a hedged claim, and the call it reads stays in place.
 
+    The session title gates keep the session title in its status format. One
+    denies a malformed title, and the other asks for a title before a turn
+    ends. They decide the shape of a title and no code or safety policy.
+
     Args:
         registered_string: One command, path, script, or entrypoint string.
     """

package/scripts/policy_lint/config/constants.py

@@ -68,6 +68,8 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/reply_length_gate.py",
     "blocking/edit_marker_gate.py",
     "blocking/verify_before_acting.py",
+    "blocking/session_title_format_gate.py",
+    "blocking/session_title_stop_gate.py",
 )
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
 ALL_TEST_FILE_PREFIXES = ("test_",)

package/scripts/sweep_empty_dirs.py

@@ -36,12 +36,29 @@ def _log_walk_error(os_error: OSError) -> None:
     logging.warning("cannot scan %s -- %s", os_error.filename, os_error.strerror)
 
 
+def _is_older_than(directory_path: str, now: float, min_age_seconds: int) -> bool:
+    """Report whether a directory ctime precedes *now* by more than the minimum age."""
+    try:
+        raw_ctime = os.path.getctime(directory_path)
+    except FileNotFoundError:
+        return False
+    except PermissionError:
+        logging.warning("permission denied -- %s", directory_path)
+        return False
+    except OSError:
+        return False
+    ctime = min(raw_ctime, now)
+    return now - ctime > min_age_seconds
+
+
 def sweep(root: str, min_age_seconds: int) -> list[str]:
     """Remove empty directories under *root* older than *min_age_seconds*.
 
-    Walks bottom-up so nested empty directories are cleaned from the leaves
-    inward.  Relies on os.rmdir to fail harmlessly for non-empty directories
-    instead of checking snapshotted subdirectory lists.
+    Reads the age of every directory before the first removal, because on
+    POSIX removing a child directory moves its parent's ctime to the present.
+    Then removes bottom-up so nested empty directories are cleaned from the
+    leaves inward.  os.rmdir decides emptiness and fails harmlessly for a
+    directory that still holds an entry.
 
     Args:
         root: Root directory to walk; directories below the root are
@@ -56,35 +73,28 @@ def sweep(root: str, min_age_seconds: int) -> list[str]:
     all_removed: list[str] = []
 
     now = time.time()
-    for each_directory_path, _, _ in os.walk(
-        root, onerror=_log_walk_error, topdown=False
-    ):
-        if each_directory_path == root:
-            continue
+    all_expired_directories = [
+        each_directory_path
+        for each_directory_path, _, _ in os.walk(
+            root, onerror=_log_walk_error, topdown=False
+        )
+        if each_directory_path != root
+        and _is_older_than(each_directory_path, now, min_age_seconds)
+    ]
+    for each_directory_path in all_expired_directories:
         try:
-            raw_ctime = os.path.getctime(each_directory_path)
+            os.rmdir(each_directory_path)
+            logging.info("deleted: %s", each_directory_path)
+            all_removed.append(each_directory_path)
         except FileNotFoundError:
-            continue
-        except PermissionError:
-            logging.warning("permission denied -- %s", each_directory_path)
-            continue
-        except OSError:
-            continue
-        ctime = min(raw_ctime, now)
-        if now - ctime > min_age_seconds:
-            try:
-                os.rmdir(each_directory_path)
-                logging.info("deleted: %s", each_directory_path)
-                all_removed.append(each_directory_path)
-            except FileNotFoundError:
-                pass
-            except OSError as e:
-                if e.errno not in (errno.ENOTEMPTY, errno.EEXIST):
-                    logging.warning(
-                        "could not remove %s -- %s",
-                        each_directory_path,
-                        e,
-                    )
+            pass
+        except OSError as e:
+            if e.errno not in (errno.ENOTEMPTY, errno.EEXIST):
+                logging.warning(
+                    "could not remove %s -- %s",
+                    each_directory_path,
+                    e,
+                )
 
     return all_removed
 

package/scripts/test_sweep_empty_dirs.py

@@ -107,6 +107,17 @@ def test_sweep_removes_nested_empty_dirs(tmp_path: Path) -> None:
     assert not (tmp_path / "level1").exists()
 
 
+def test_sweep_reports_a_nested_chain_removed_leaf_first_in_one_pass(tmp_path: Path) -> None:
+    """sweep reads every age before it removes, so one pass clears the whole chain."""
+    outer = tmp_path / "outer"
+    inner = outer / "inner"
+    inner.mkdir(parents=True)
+
+    removed = sweep(str(tmp_path), min_age_seconds=0)
+
+    assert removed == [str(inner), str(outer)]
+
+
 def test_sweep_removes_only_old_enough_directories(tmp_path: Path) -> None:
     """sweep does not remove directories newer than the age threshold."""
     young_dir = tmp_path / "young"

package/scripts/tests/test_adapter_configuration.py

@@ -90,6 +90,17 @@ def test_new_verify_before_acting_registration_is_clean(tmp_path: Path) -> None:
     assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
 
 
+def test_new_session_title_gate_registrations_are_clean(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        [
+            "hooks/blocking/session_title_format_gate.py",
+            "hooks/blocking/session_title_stop_gate.py",
+        ],
+        '{"hooks": {}}',
+    )
+    assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
+
+
 def test_new_blocker_in_staged_change_is_rejected(tmp_path: Path) -> None:
     current_document = _hook_document(
         ["hooks/blocking/new.py"],

package/scripts/tests/test_rule_load_scopes.py

@@ -20,6 +20,7 @@ ALWAYS_ON_RULE_NAMES = frozenset(
         "no-contrast-framing.md",
         "question-presentation.md",
         "research-mode.md",
+        "session-title.md",
         "skill-pointers.md",
         "shell-invocation.md",
         "verify-before-asking.md",