claude-dev-env 8.25.1 → 8.26.0

package/docs/CODE_RULES.md

@@ -13,7 +13,7 @@ Do not add code comments. Preserve existing comments. Docstrings remain allowed.
 When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
 Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
 
-A keep marker is the one comment that may be added and kept: a comment that opens with `STEALTH: Keep`, or with a prefix the repository lists under `comment_keep_markers` in `.claude/policy-lint.json`.
+A keep marker is the one comment that may be added and kept: a comment that opens with a prefix the repository lists under `comment_keep_markers` in `.claude/policy-lint.json`.
 
 ---
 

package/hooks/blocking/code_rules_comments.py

@@ -36,7 +36,6 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     REPOSITORY_LINT_SETTINGS_RELATIVE_PATH,
     REPOSITORY_ROOT_MARKER_NAME,
     SETTINGS_TEXT_ENCODING,
-    STEALTH_KEEP_COMMENT_MARKER,
 )
 _javascript_comment_scanner = importlib.import_module("javascript_comment_scanner")
 extract_javascript_comment_occurrences = (
@@ -180,26 +179,22 @@ def comment_keep_markers(file_path: str) -> tuple[str, ...]:
     ::
 
         repo/.claude/policy-lint.json  {"comment_keep_markers": ["VENDOR: Keep"]}
-        repo/app/main.py               ("STEALTH: Keep", "VENDOR: Keep")
-        no settings file               ("STEALTH: Keep",)
+        repo/app/main.py               ("VENDOR: Keep",)
+        no settings file               ()
 
     The repository that holds the file names its own markers. A missing or
-    unreadable settings file adds none.
+    unreadable settings file names none.
 
     Args:
         file_path: The path of the file under check.
 
     Returns:
-        The package's built-in marker, then the markers the file's repository
-        adds.
+        The markers the file's repository names.
     """
     for each_directory in Path(file_path).resolve().parents:
         if (each_directory / REPOSITORY_ROOT_MARKER_NAME).exists():
-            return (
-                STEALTH_KEEP_COMMENT_MARKER,
-                *_repository_keep_markers(each_directory),
-            )
-    return (STEALTH_KEEP_COMMENT_MARKER,)
+            return _repository_keep_markers(each_directory)
+    return ()
 
 
 def _is_keep_occurrence(comment_text: str, all_keep_markers: tuple[str, ...]) -> bool:
@@ -230,10 +225,9 @@ def check_comment_changes(old_content: str, new_content: str, file_path: str) ->
     """Check for comment additions or removals between old and new content.
 
     Inline and standalone comments are blocking findings when added, except
-    keep-marker occurrences (``STEALTH: Keep`` and any marker the file's
-    repository names in ``.claude/policy-lint.json``), which are excluded
-    entirely so the marker can be added and can persist across edits to its
-    line.
+    keep-marker occurrences (a marker the file's repository names in
+    ``.claude/policy-lint.json``), which are excluded entirely so the marker
+    can be added and can persist across edits to its line.
     Existing comments can be removed when the touched code no longer needs them.
 
     When the file is Python and either *old_content* or *new_content* cannot
@@ -431,14 +425,11 @@ def _is_exempt_python_comment(comment_token: tokenize.TokenInfo) -> bool:
     token-anchored directive body never legitimately carries a ``#``
     (noqa codes, pylint symbols, and pragma directives contain none), so
     any inner ``#`` reliably marks chained prose. Free-form markers
-    (``type:``, ``TODO``, ``FIXME``, ``HACK``, ``XXX``, ``STEALTH: Keep``)
-    accept any trailing prose:
-    ``# type:`` participates in the documented justification
-    convention enforced by ``check_type_escape_hatches`` (which
-    requires a trailing reason), the TODO-family markers carry
-    annotation text by convention, and ``STEALTH: Keep`` is the
-    acknowledged-bypass marker the CDP runtime-usage scanner reads
-    from the flagged line together with its reason.
+    (``type:``, ``TODO``, ``FIXME``, ``HACK``, ``XXX``) accept any
+    trailing prose: ``# type:`` participates in the documented
+    justification convention enforced by ``check_type_escape_hatches``
+    (which requires a trailing reason), and the TODO-family markers carry
+    annotation text by convention.
     """
     comment_string = comment_token.string
     if comment_string.startswith("#!") and comment_token.start == (1, 0):

package/hooks/blocking/test_code_rules_enforcer_comment_string_awareness.py

@@ -134,18 +134,15 @@ def test_check_comment_changes_allows_comment_removal_without_advisory(
     assert captured.err == ""
 
 
-def test_check_comment_changes_does_not_flag_added_stealth_keep_marker() -> None:
-    old_content = "x = 1\n"
-    new_content = "x = 1  # STEALTH: Keep -- reason\n"
-    issues = code_rules_enforcer.check_comment_changes(old_content, new_content, "foo.py")
-    assert issues == []
-
-
-def test_check_comment_changes_does_not_flag_stealth_keep_retained_on_touched_line() -> None:
-    old_content = "x = 1  # STEALTH: Keep -- reason\n"
-    new_content = "x = 2  # STEALTH: Keep -- reason\n"
-    issues = code_rules_enforcer.check_comment_changes(old_content, new_content, "foo.py")
-    assert issues == []
+def test_check_comment_changes_flags_stealth_keep_in_a_repository_that_names_no_marker(
+    tmp_path: Path,
+) -> None:
+    file_path = _repository_file(tmp_path, None)
+    issues = code_rules_enforcer.check_comment_changes(
+        "x = 1\n", "x = 1  # STEALTH: Keep -- reason\n", file_path
+    )
+    assert len(issues) == 1
+    assert "comment added" in issues[0]
 
 
 @pytest.mark.parametrize(

package/hooks/blocking/test_code_rules_enforcer_exempt_marker_chained.py

@@ -156,16 +156,6 @@ def test_should_exempt_fixme_with_trailing_prose() -> None:
     assert _is_exempt_python_comment(token) is True
 
 
-def test_should_exempt_stealth_keep_with_trailing_reason() -> None:
-    token = _build_comment_token("# STEALTH: Keep bypass reviewed in incident 4021")
-    assert _is_exempt_python_comment(token) is True
-
-
-def test_should_flag_stealth_marker_missing_required_space_after_colon() -> None:
-    token = _build_comment_token("# STEALTH:Keep bypass reviewed in incident 4021")
-    assert _is_exempt_python_comment(token) is False
-
-
 def test_should_exempt_shebang_at_line_one_column_zero() -> None:
     token = tokenize.TokenInfo(
         type=tokenize.COMMENT,

package/hooks/hooks.json

@@ -72,6 +72,16 @@
           }
         ]
       },
+      {
+        "matcher": "mcp__hearthbot__start_thread_session",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/thread_spawn_pace_hook.py",
+            "timeout": 30
+          }
+        ]
+      },
       {
         "matcher": "*",
         "hooks": [

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -133,7 +133,6 @@ ALL_TOKEN_ANCHORED_EXEMPT_COMMENT_BODIES: tuple[str, ...] = (
     "pragma:",
 )
 ALL_TOKEN_ANCHORED_DIRECTIVE_BOUNDARY_CHARACTERS: frozenset[str] = frozenset({":"})
-STEALTH_KEEP_COMMENT_MARKER: str = "STEALTH: Keep"
 REPOSITORY_LINT_SETTINGS_RELATIVE_PATH: str = ".claude/policy-lint.json"
 COMMENT_KEEP_MARKERS_KEY: str = "comment_keep_markers"
 REPOSITORY_ROOT_MARKER_NAME: str = ".git"
@@ -144,7 +143,6 @@ ALL_FREE_FORM_EXEMPT_COMMENT_BODIES: tuple[str, ...] = (
     "FIXME",
     "HACK",
     "XXX",
-    STEALTH_KEEP_COMMENT_MARKER,
 )
 CHAINED_INLINE_COMMENT_PATTERN = re.compile(r"#")
 ALL_JAVASCRIPT_EXEMPT_COMMENT_PREFIXES: tuple[str, ...] = (

package/hooks/hooks_constants/test_code_rules_enforcer_constants.py

@@ -17,7 +17,6 @@ if str(_HOOKS_ROOT) not in sys.path:
     sys.path.insert(0, str(_HOOKS_ROOT))
 
 from hooks_constants.code_rules_enforcer_constants import (
-    ALL_FREE_FORM_EXEMPT_COMMENT_BODIES,
     ALL_VALIDATION_PHASES,
     CONFIG_DIRECTORY_SEGMENT,
     CONSTANTS_MODULE_SUFFIX,
@@ -27,7 +26,6 @@ from hooks_constants.code_rules_enforcer_constants import (
     JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN,
     RETURN_CALL_OPENING_PARENTHESIS_PATTERN,
     SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN,
-    STEALTH_KEEP_COMMENT_MARKER,
     UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE,
     apply_edits,
     edits_for_tool,
@@ -108,10 +106,6 @@ def test_constants_module_suffix_and_config_directory_segment_are_defined() -> N
     assert CONFIG_DIRECTORY_SEGMENT == "config"
 
 
-def test_free_form_exempt_comment_bodies_include_stealth_keep_marker() -> None:
-    assert STEALTH_KEEP_COMMENT_MARKER in ALL_FREE_FORM_EXEMPT_COMMENT_BODIES
-
-
 def test_validation_phase_constants_are_reexported_and_render() -> None:
     assert ALL_VALIDATION_PHASES == {EDIT_LANE_PHASE, FULL_GATE_PHASE}
     rendered_message = UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE.format(

package/hooks/hooks_constants/thread_spawn_pace_hook_constants.py

@@ -0,0 +1,45 @@
+"""Constants for the thread spawn pace PreToolUse hook.
+
+Groups: the usage-pace script it runs, the reshape values for an over-pace
+spawn, and the hook output keys and messages.
+"""
+
+from __future__ import annotations
+
+USAGE_PACE_SCRIPT_ENV_VAR = "COORDINATOR_USAGE_PACE_SCRIPT"
+USAGE_PACE_SCRIPT_FILE_NAME = "usage_pace.py"
+USAGE_PACE_TIMEOUT_SECONDS = 15
+
+TOOL_INPUT_KEY = "tool_input"
+THREAD_MODEL_WHEN_OVER_PACE = "claude-sonnet-5-5"
+THREAD_EFFORT_WHEN_OVER_PACE = "medium"
+MODEL_INPUT_KEY = "model"
+EFFORT_INPUT_KEY = "effort"
+INSTRUCTIONS_INPUT_KEY = "instructions"
+INSTRUCTIONS_MAXIMUM_BYTES = 8192
+INSTRUCTIONS_SEPARATOR = "\n\n"
+INSTRUCTIONS_ENCODING = "utf-8"
+FABLE_ADVISOR_LINE = (
+    "Mandatory Fable advisor: usage is over pace, so this thread runs on "
+    "Sonnet 5.5 at medium effort. Invoke /team-advisor before substantive "
+    "work and bind a Fable advisor through it. Consult that advisor again "
+    "before you report done, and name its verdict in your report."
+)
+
+PERMISSION_DENY = "deny"
+PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
+ADDITIONAL_CONTEXT_KEY = "additionalContext"
+NOT_AN_OBJECT_REASON = "start_thread_session input is not a JSON object"
+NO_INSTRUCTIONS_REASON = "start_thread_session input has no instructions text"
+OVER_BYTE_CAP_REASON_TEMPLATE = (
+    "usage is over pace and the brief plus the mandatory Fable advisor line is "
+    "{reshaped_byte_count} bytes, over the {maximum_bytes}-byte cap; "
+    "shorten the instructions by {excess_byte_count} bytes"
+)
+RESHAPE_CONTEXT_PREFIX = (
+    "Usage over pace or unreadable: this thread spawn now runs on "
+    "claude-sonnet-5-5 at medium effort with a mandatory Fable advisor line. "
+    "Pace verdict: "
+)
+PACE_VERDICT_CONTEXT_MAXIMUM_CHARACTERS = 600
+LAUNCH_FAILURE_ERROR_TEMPLATE = "usage pace did not finish: {failure_type}"

package/hooks/hooks_constants/usage_pace_constants.py

@@ -0,0 +1,49 @@
+"""Constants for the usage-pace reader that the thread spawn pace hook runs.
+
+Groups: the OAuth usage endpoint probe, the token and certificate sources,
+the rate windows and their lengths, the exit codes, and the JSON keys of the
+verdict.
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+
+USAGE_ENDPOINT_URL = "https://api.anthropic.com/api/oauth/usage"
+ANTHROPIC_BETA_HEADER = "anthropic-beta"
+USAGE_BETA_VALUE = "oauth-2025-04-20"
+AUTHORIZATION_HEADER = "Authorization"
+BEARER_PREFIX = "Bearer "
+CONTENT_TYPE_HEADER_NAME = "Content-Type"
+CONTENT_TYPE_JSON = "application/json"
+PROBE_TIMEOUT_SECONDS = 8
+
+INGRESS_BEARER_FILE_ENV_VAR = "CLAUDE_SESSION_INGRESS_TOKEN_FILE"
+SSL_CERT_FILE_ENV_VAR = "SSL_CERT_FILE"
+CONTAINER_PROXY_CA_BUNDLE_PATH = "/root/.ccr/ca-bundle.crt"
+
+UTILIZATION_KEY = "utilization"
+RESETS_AT_KEY = "resets_at"
+ISO_UTC_SUFFIX = "Z"
+ISO_UTC_OFFSET = "+00:00"
+ALL_RATE_WINDOW_LENGTHS = (
+    ("five_hour", timedelta(hours=5)),
+    ("seven_day", timedelta(days=7)),
+)
+PERCENT_SCALE = 100.0
+PERCENT_DECIMAL_PLACES = 1
+MINIMUM_ELAPSED_PERCENT_FOR_PACE = 10.0
+
+EXIT_CODE_OVER_PACE = 0
+EXIT_CODE_UNDER_PACE = 1
+EXIT_CODE_UNREADABLE = 2
+
+RESULT_KEY_OVER_PACE = "over_pace"
+RESULT_KEY_CHECKED_AT = "checked_at"
+RESULT_KEY_WINDOWS = "windows"
+RESULT_KEY_ERROR = "error"
+WINDOW_KEY_NAME = "window"
+WINDOW_KEY_USED_PERCENT = "used_percent"
+WINDOW_KEY_ELAPSED_PERCENT = "elapsed_percent"
+WINDOW_KEY_RESETS_AT = "resets_at"
+WINDOW_KEY_OVER_PACE = "over_pace"

package/hooks/routing/conftest.py

@@ -0,0 +1,10 @@
+"""Add hooks/routing and hooks/ to sys.path for every test collected under this directory."""
+
+import sys
+from pathlib import Path
+
+_ROUTING_DIRECTORY = str(Path(__file__).resolve().parent)
+_HOOKS_DIRECTORY = str(Path(_ROUTING_DIRECTORY).parent)
+for each_directory in (_ROUTING_DIRECTORY, _HOOKS_DIRECTORY):
+    if each_directory not in sys.path:
+        sys.path.insert(0, each_directory)

package/hooks/routing/test_thread_spawn_pace_hook.py

@@ -0,0 +1,139 @@
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+from hooks_constants.thread_spawn_pace_hook_constants import FABLE_ADVISOR_LINE
+
+HOOK_SCRIPT = Path(__file__).resolve().parent / "thread_spawn_pace_hook.py"
+SPAWN_INPUT = {
+    "thread_id": "cmsg_example",
+    "title": "Example thread",
+    "ack": "Starting on the example first.",
+    "instructions": "Do the example task.",
+    "context_message_ids": ["cmsg_example"],
+}
+
+
+def _write_pace_stub(
+    tmp_path: Path, exit_code: int, verdict: dict[str, object]
+) -> Path:
+    stub_path = tmp_path / f"pace_stub_{exit_code}.py"
+    stub_path.write_text(
+        f"import sys\nprint({json.dumps(json.dumps(verdict))})\nsys.exit({exit_code})\n",
+        encoding="utf-8",
+    )
+    return stub_path
+
+
+def _run_hook(pace_script: Path, tool_input: object) -> str:
+    hook_payload = {
+        "hook_event_name": "PreToolUse",
+        "tool_name": "mcp__hearthbot__start_thread_session",
+        "tool_input": tool_input,
+    }
+    completed = subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT)],
+        input=json.dumps(hook_payload),
+        capture_output=True,
+        text=True,
+        env={**os.environ, "COORDINATOR_USAGE_PACE_SCRIPT": str(pace_script)},
+        check=True,
+    )
+    return completed.stdout
+
+
+def _hook_specific_output(stdout: str) -> dict[str, object]:
+    return json.loads(stdout)["hookSpecificOutput"]
+
+
+def _assert_reshaped(stdout: str) -> None:
+    decision = _hook_specific_output(stdout)
+    assert decision["hookEventName"] == "PreToolUse"
+    assert decision["permissionDecision"] == "allow"
+    assert decision["updatedInput"] == {
+        **SPAWN_INPUT,
+        "model": "claude-sonnet-5-5",
+        "effort": "medium",
+        "instructions": f"Do the example task.\n\n{FABLE_ADVISOR_LINE}",
+    }
+
+
+def test_should_reshape_the_spawn_when_usage_is_over_pace(tmp_path: Path) -> None:
+    _assert_reshaped(
+        _run_hook(_write_pace_stub(tmp_path, 0, {"over_pace": True}), SPAWN_INPUT)
+    )
+
+
+def test_should_pass_the_spawn_through_unchanged_when_usage_is_under_pace(
+    tmp_path: Path,
+) -> None:
+    assert (
+        _run_hook(_write_pace_stub(tmp_path, 1, {"over_pace": False}), SPAWN_INPUT)
+        == ""
+    )
+
+
+def test_should_reshape_the_spawn_when_usage_is_unreadable(tmp_path: Path) -> None:
+    _assert_reshaped(
+        _run_hook(
+            _write_pace_stub(tmp_path, 2, {"over_pace": None, "error": "x"}),
+            SPAWN_INPUT,
+        )
+    )
+
+
+def test_should_reshape_the_spawn_when_the_pace_script_is_missing(
+    tmp_path: Path,
+) -> None:
+    _assert_reshaped(_run_hook(tmp_path / "absent.py", SPAWN_INPUT))
+
+
+def test_should_append_the_advisor_line_once(tmp_path: Path) -> None:
+    already_reshaped = {
+        **SPAWN_INPUT,
+        "instructions": f"Do the example task.\n\n{FABLE_ADVISOR_LINE}",
+    }
+    stdout = _run_hook(
+        _write_pace_stub(tmp_path, 0, {"over_pace": True}), already_reshaped
+    )
+    assert (
+        _hook_specific_output(stdout)["updatedInput"]["instructions"].count(
+            FABLE_ADVISOR_LINE
+        )
+        == 1
+    )
+
+
+@pytest.mark.parametrize(
+    ("tool_input", "reason"),
+    [
+        (["not", "an", "object"], "start_thread_session input is not a JSON object"),
+        ({"title": "No brief"}, "start_thread_session input has no instructions text"),
+    ],
+)
+def test_should_deny_a_spawn_it_cannot_reshape(
+    tmp_path: Path, tool_input: object, reason: str
+) -> None:
+    decision = _hook_specific_output(
+        _run_hook(_write_pace_stub(tmp_path, 0, {"over_pace": True}), tool_input)
+    )
+    assert decision["permissionDecision"] == "deny"
+    assert decision["permissionDecisionReason"] == reason
+    assert "updatedInput" not in decision
+
+
+def test_should_deny_a_brief_the_advisor_line_would_push_past_the_byte_cap(
+    tmp_path: Path,
+) -> None:
+    full_brief = {**SPAWN_INPUT, "instructions": "x" * 8100}
+    decision = _hook_specific_output(
+        _run_hook(_write_pace_stub(tmp_path, 0, {"over_pace": True}), full_brief)
+    )
+    assert decision["permissionDecision"] == "deny"
+    over_by = 8100 + 2 + len(FABLE_ADVISOR_LINE.encode("utf-8")) - 8192
+    assert decision["permissionDecisionReason"].endswith(
+        f"shorten the instructions by {over_by} bytes"
+    )

package/hooks/routing/test_usage_pace.py

@@ -0,0 +1,142 @@
+import json
+import subprocess
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import pytest
+from usage_pace import (
+    UsageUnreadable,
+    build_verdict,
+    measure_account_pace,
+    measure_window_pace,
+)
+
+USAGE_PACE_SCRIPT = Path(__file__).resolve().parent / "usage_pace.py"
+NOW = datetime(2026, 9, 29, 13, 57, 40, tzinfo=timezone.utc)
+FIVE_HOUR_RESET = "2026-09-29T18:50:00+00:00"
+WEEKLY_RESET = "2026-10-03T20:00:00+00:00"
+
+
+def _payload(five_hour_used: float, weekly_used: float) -> dict[str, object]:
+    return {
+        "five_hour": {"utilization": five_hour_used, "resets_at": FIVE_HOUR_RESET},
+        "seven_day": {"utilization": weekly_used, "resets_at": WEEKLY_RESET},
+        "seven_day_opus": None,
+    }
+
+
+def _run_script(tmp_path: Path, payload: object) -> tuple[int, dict[str, object]]:
+    payload_path = tmp_path / "usage.json"
+    payload_path.write_text(json.dumps(payload), encoding="utf-8")
+    completed = subprocess.run(
+        [
+            sys.executable,
+            str(USAGE_PACE_SCRIPT),
+            "--payload-file",
+            str(payload_path),
+            "--now",
+            NOW.isoformat(),
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return completed.returncode, json.loads(completed.stdout)
+
+
+def test_should_hold_a_window_clear_before_ten_percent_of_it_has_elapsed() -> None:
+    pace = measure_window_pace(
+        "five_hour",
+        timedelta(hours=5),
+        {"utilization": 3.0, "resets_at": FIVE_HOUR_RESET},
+        NOW,
+    )
+    assert pace.elapsed_percent == 2.6
+    assert pace.over_pace is False
+
+
+def test_should_flag_a_window_whose_spend_runs_ahead_of_the_clock_past_the_floor() -> (
+    None
+):
+    pace = measure_window_pace(
+        "five_hour",
+        timedelta(hours=5),
+        {"utilization": 50.0, "resets_at": "2026-09-29T17:00:00+00:00"},
+        NOW,
+    )
+    assert pace.elapsed_percent == 39.2
+    assert pace.over_pace is True
+
+
+def test_should_clear_a_window_whose_spend_trails_the_clock() -> None:
+    pace = measure_window_pace(
+        "seven_day",
+        timedelta(days=7),
+        {"utilization": 20.0, "resets_at": WEEKLY_RESET},
+        NOW,
+    )
+    assert pace.elapsed_percent == 39.3
+    assert pace.over_pace is False
+
+
+def test_should_clamp_elapsed_time_to_the_window_length() -> None:
+    long_past_reset = measure_window_pace(
+        "five_hour",
+        timedelta(hours=5),
+        {"utilization": 99.0, "resets_at": "2026-09-29T10:00:00Z"},
+        NOW,
+    )
+    assert long_past_reset.elapsed_percent == 100.0
+    assert long_past_reset.over_pace is False
+
+
+def test_should_report_over_pace_when_any_window_runs_ahead() -> None:
+    verdict = build_verdict(measure_account_pace(_payload(1.0, 93.0), NOW), NOW)
+    assert verdict["over_pace"] is True
+    assert [each["over_pace"] for each in verdict["windows"]] == [False, True]
+
+
+def test_should_report_under_pace_when_every_window_trails() -> None:
+    verdict = build_verdict(measure_account_pace(_payload(1.0, 20.0), NOW), NOW)
+    assert verdict["over_pace"] is False
+
+
+@pytest.mark.parametrize(
+    "broken_payload",
+    [
+        {"seven_day": {"utilization": 20.0, "resets_at": WEEKLY_RESET}},
+        {
+            "five_hour": {"utilization": None, "resets_at": FIVE_HOUR_RESET},
+            "seven_day": {"utilization": 1.0, "resets_at": WEEKLY_RESET},
+        },
+        {
+            "five_hour": {"utilization": 1.0, "resets_at": "soon"},
+            "seven_day": {"utilization": 1.0, "resets_at": WEEKLY_RESET},
+        },
+    ],
+)
+def test_should_treat_a_missing_or_unreadable_window_as_unreadable(
+    broken_payload: dict[str, object],
+) -> None:
+    with pytest.raises(UsageUnreadable):
+        measure_account_pace(broken_payload, NOW)
+
+
+def test_should_exit_zero_with_the_verdict_when_over_pace(tmp_path: Path) -> None:
+    exit_code, verdict = _run_script(tmp_path, _payload(3.0, 93.0))
+    assert exit_code == 0
+    assert verdict["over_pace"] is True
+
+
+def test_should_exit_one_when_under_pace(tmp_path: Path) -> None:
+    exit_code, verdict = _run_script(tmp_path, _payload(1.0, 20.0))
+    assert exit_code == 1
+    assert verdict["over_pace"] is False
+
+
+def test_should_exit_two_with_a_null_verdict_when_unreadable(tmp_path: Path) -> None:
+    exit_code, verdict = _run_script(tmp_path, {"five_hour": None})
+    assert exit_code == 2
+    assert verdict["over_pace"] is None
+    assert verdict["error"] == "usage response has no five_hour window"

package/hooks/routing/thread_spawn_pace_hook.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: reshape a thread spawn when usage runs over pace.
+
+Registered on ``mcp__hearthbot__start_thread_session``. It runs ``usage_pace.py``
+beside it, or the script ``COORDINATOR_USAGE_PACE_SCRIPT`` names.
+
+::
+
+    usage under pace (exit 1)          -> no output; the call runs unchanged
+    over pace (exit 0) or unreadable   -> allow with updatedInput:
+        model "claude-sonnet-5-5", effort "medium",
+        instructions + the mandatory Fable advisor line
+    input that cannot be reshaped      -> deny with a one-line reason
+
+``updatedInput`` is the whole tool input the call runs with, so it carries
+every original key.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+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.bash_pre_tool_use_dispatcher_constants import (
+    ALLOW_DECISION,
+    HOOK_EVENT_NAME,
+)
+from hooks_constants.pre_tool_use_allow_output 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.thread_spawn_pace_hook_constants import (
+    ADDITIONAL_CONTEXT_KEY,
+    EFFORT_INPUT_KEY,
+    FABLE_ADVISOR_LINE,
+    INSTRUCTIONS_ENCODING,
+    INSTRUCTIONS_INPUT_KEY,
+    INSTRUCTIONS_MAXIMUM_BYTES,
+    INSTRUCTIONS_SEPARATOR,
+    LAUNCH_FAILURE_ERROR_TEMPLATE,
+    MODEL_INPUT_KEY,
+    NO_INSTRUCTIONS_REASON,
+    NOT_AN_OBJECT_REASON,
+    OVER_BYTE_CAP_REASON_TEMPLATE,
+    PACE_VERDICT_CONTEXT_MAXIMUM_CHARACTERS,
+    PERMISSION_DECISION_REASON_KEY,
+    PERMISSION_DENY,
+    RESHAPE_CONTEXT_PREFIX,
+    THREAD_EFFORT_WHEN_OVER_PACE,
+    THREAD_MODEL_WHEN_OVER_PACE,
+    TOOL_INPUT_KEY,
+    USAGE_PACE_SCRIPT_ENV_VAR,
+    USAGE_PACE_SCRIPT_FILE_NAME,
+    USAGE_PACE_TIMEOUT_SECONDS,
+)
+from hooks_constants.usage_pace_constants import (
+    EXIT_CODE_UNDER_PACE,
+    EXIT_CODE_UNREADABLE,
+    RESULT_KEY_ERROR,
+    RESULT_KEY_OVER_PACE,
+)
+
+
+class SpawnNotReshapable(Exception):
+    """The spawn input cannot carry the over-pace model, effort, and advisor line."""
+
+
+def _instructions_with_advisor_line(instructions: str) -> str:
+    reshaped_instructions = (
+        instructions
+        if FABLE_ADVISOR_LINE in instructions
+        else f"{instructions}{INSTRUCTIONS_SEPARATOR}{FABLE_ADVISOR_LINE}"
+    )
+    reshaped_byte_count = len(reshaped_instructions.encode(INSTRUCTIONS_ENCODING))
+    if reshaped_byte_count > INSTRUCTIONS_MAXIMUM_BYTES:
+        raise SpawnNotReshapable(
+            OVER_BYTE_CAP_REASON_TEMPLATE.format(
+                reshaped_byte_count=reshaped_byte_count,
+                maximum_bytes=INSTRUCTIONS_MAXIMUM_BYTES,
+                excess_byte_count=reshaped_byte_count - INSTRUCTIONS_MAXIMUM_BYTES,
+            )
+        )
+    return reshaped_instructions
+
+
+def reshape_thread_spawn(tool_input: object) -> dict[str, object]:
+    """Move a thread spawn to Sonnet at medium effort with a Fable advisor line.
+
+    ::
+
+        {"title": "t", "instructions": "Do X."}
+        -> {"title": "t", "instructions": "Do X.\\n\\nMandatory Fable advisor: ...",
+            "model": "claude-sonnet-5-5", "effort": "medium"}
+
+    An instructions text that already carries the advisor line keeps one copy.
+
+    Args:
+        tool_input: The ``tool_input`` object of the start_thread_session call.
+
+    Raises:
+        SpawnNotReshapable: The input is not an object, has no instructions
+            text, or would pass the server's instructions byte cap.
+    """
+    if not isinstance(tool_input, dict):
+        raise SpawnNotReshapable(NOT_AN_OBJECT_REASON)
+    instructions = tool_input.get(INSTRUCTIONS_INPUT_KEY)
+    if not isinstance(instructions, str):
+        raise SpawnNotReshapable(NO_INSTRUCTIONS_REASON)
+    return {
+        **tool_input,
+        MODEL_INPUT_KEY: THREAD_MODEL_WHEN_OVER_PACE,
+        EFFORT_INPUT_KEY: THREAD_EFFORT_WHEN_OVER_PACE,
+        INSTRUCTIONS_INPUT_KEY: _instructions_with_advisor_line(instructions),
+    }
+
+
+def _hook_output(all_decision_fields: dict[str, object]) -> dict[str, object]:
+    return {
+        HOOK_SPECIFIC_OUTPUT_KEY: {
+            HOOK_EVENT_NAME_KEY: HOOK_EVENT_NAME,
+            **all_decision_fields,
+        }
+    }
+
+
+def _deny_output(reason: str) -> dict[str, object]:
+    return _hook_output(
+        {PERMISSION_DECISION_KEY: PERMISSION_DENY, PERMISSION_DECISION_REASON_KEY: reason}
+    )
+
+
+def decide_hook_output(
+    tool_input: object, pace_exit_code: int, pace_verdict_text: str
+) -> dict[str, object] | None:
+    """Choose the hook's output for one spawn and one pace reading.
+
+    Args:
+        tool_input: The ``tool_input`` of the PreToolUse payload, or None when
+            stdin held no JSON object.
+        pace_exit_code: The usage-pace exit code; anything but under pace
+            counts as over pace.
+        pace_verdict_text: The usage-pace stdout, quoted into the context.
+
+    Returns:
+        None to pass the call through unchanged, else the hook JSON output.
+    """
+    if pace_exit_code == EXIT_CODE_UNDER_PACE:
+        return None
+    try:
+        reshaped_input = reshape_thread_spawn(tool_input)
+    except SpawnNotReshapable as not_reshapable:
+        return _deny_output(str(not_reshapable))
+    verdict_excerpt = pace_verdict_text.strip()[:PACE_VERDICT_CONTEXT_MAXIMUM_CHARACTERS]
+    return _hook_output(
+        {
+            PERMISSION_DECISION_KEY: ALLOW_DECISION,
+            UPDATED_INPUT_KEY: reshaped_input,
+            ADDITIONAL_CONTEXT_KEY: RESHAPE_CONTEXT_PREFIX + verdict_excerpt,
+        }
+    )
+
+
+def run_usage_pace() -> tuple[int, str]:
+    """Run the usage-pace script and return its exit code and stdout.
+
+    Returns:
+        The exit code and stdout. A missing script, a launch failure, or a
+        timeout returns the unreadable exit code.
+    """
+    pace_script = os.environ.get(USAGE_PACE_SCRIPT_ENV_VAR) or str(
+        Path(__file__).resolve().parent / USAGE_PACE_SCRIPT_FILE_NAME
+    )
+    try:
+        completed = subprocess.run(
+            [sys.executable, pace_script],
+            capture_output=True,
+            text=True,
+            timeout=USAGE_PACE_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as launch_error:
+        return EXIT_CODE_UNREADABLE, json.dumps(
+            {
+                RESULT_KEY_OVER_PACE: None,
+                RESULT_KEY_ERROR: LAUNCH_FAILURE_ERROR_TEMPLATE.format(
+                    failure_type=type(launch_error).__name__
+                ),
+            }
+        )
+    return completed.returncode, completed.stdout
+
+
+def main() -> int:
+    """Read the PreToolUse payload, read the pace, and print the decision.
+
+    Returns:
+        0 in every case; a deny travels in the JSON output.
+    """
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    tool_input = hook_payload.get(TOOL_INPUT_KEY) if hook_payload is not None else None
+    pace_exit_code, pace_verdict_text = run_usage_pace()
+    hook_output = decide_hook_output(tool_input, pace_exit_code, pace_verdict_text)
+    if hook_output is not None:
+        sys.stdout.write(json.dumps(hook_output))
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/routing/usage_pace.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""Report whether the account running the project spends faster than its windows reset.
+
+::
+
+    python usage_pace.py
+    {"over_pace": true, "checked_at": "2026-09-29T13:57:40+00:00",
+     "windows": [{"window": "five_hour", "used_percent": 3.0,
+                  "elapsed_percent": 2.6, "resets_at": "...", "over_pace": false},
+                 {"window": "seven_day", "used_percent": 93.0,
+                  "elapsed_percent": 39.3, "resets_at": "...", "over_pace": true}]}
+
+A window is over pace when at least 10% of it has elapsed and its used percent
+exceeds the percent already elapsed. The floor keeps a window's first minutes,
+where any spend outruns the clock, from reading as over pace. The account is over pace when any window is. The script reads
+the OAuth usage endpoint with the session ingress bearer token, the same probe
+the usage-pause skill's ``resolve_usage_window.py`` uses. It never prints or
+stores the token.
+
+Exit codes: 0 over pace, 1 under pace, 2 unreadable. ``--payload-file`` and
+``--now`` replace the live probe and the clock for a deterministic run.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import ssl
+import sys
+import urllib.error
+import urllib.request
+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.usage_pace_constants import (
+    ALL_RATE_WINDOW_LENGTHS,
+    ANTHROPIC_BETA_HEADER,
+    AUTHORIZATION_HEADER,
+    BEARER_PREFIX,
+    CONTAINER_PROXY_CA_BUNDLE_PATH,
+    CONTENT_TYPE_HEADER_NAME,
+    CONTENT_TYPE_JSON,
+    EXIT_CODE_OVER_PACE,
+    EXIT_CODE_UNDER_PACE,
+    EXIT_CODE_UNREADABLE,
+    INGRESS_BEARER_FILE_ENV_VAR,
+    ISO_UTC_OFFSET,
+    ISO_UTC_SUFFIX,
+    MINIMUM_ELAPSED_PERCENT_FOR_PACE,
+    PERCENT_DECIMAL_PLACES,
+    PERCENT_SCALE,
+    PROBE_TIMEOUT_SECONDS,
+    RESETS_AT_KEY,
+    RESULT_KEY_CHECKED_AT,
+    RESULT_KEY_ERROR,
+    RESULT_KEY_OVER_PACE,
+    RESULT_KEY_WINDOWS,
+    SSL_CERT_FILE_ENV_VAR,
+    USAGE_BETA_VALUE,
+    USAGE_ENDPOINT_URL,
+    UTILIZATION_KEY,
+    WINDOW_KEY_ELAPSED_PERCENT,
+    WINDOW_KEY_NAME,
+    WINDOW_KEY_OVER_PACE,
+    WINDOW_KEY_RESETS_AT,
+    WINDOW_KEY_USED_PERCENT,
+)
+
+
+class UsageUnreadable(Exception):
+    """The usage meters could not be read, so the pace is unknown."""
+
+
+@dataclass(frozen=True)
+class WindowPace:
+    """One rate window's spend against the time it has run.
+
+    Attributes:
+        name: The usage bucket key, such as ``five_hour``.
+        used_percent: Percent of the window's allowance spent.
+        elapsed_percent: Percent of the window's length already passed.
+        resets_at: When the window resets.
+    """
+
+    name: str
+    used_percent: float
+    elapsed_percent: float
+    resets_at: datetime
+
+    @property
+    def over_pace(self) -> bool:
+        """True when spend runs ahead of the clock past the window's opening stretch.
+
+        ::
+
+            elapsed 2.6%,  used 3.0%   -> False  (under the 10% floor)
+            elapsed 39.3%, used 93.0%  -> True
+            elapsed 39.3%, used 20.0%  -> False
+        """
+        return (
+            self.elapsed_percent >= MINIMUM_ELAPSED_PERCENT_FOR_PACE
+            and self.used_percent > self.elapsed_percent
+        )
+
+
+def _parse_resets_at(raw_resets_at: object, window_name: str) -> datetime:
+    if not isinstance(raw_resets_at, str):
+        raise UsageUnreadable(f"{window_name} has no resets_at time")
+    try:
+        parsed = datetime.fromisoformat(raw_resets_at.replace(ISO_UTC_SUFFIX, ISO_UTC_OFFSET))
+    except ValueError as parse_error:
+        raise UsageUnreadable(f"{window_name} resets_at is unreadable") from parse_error
+    if parsed.tzinfo is None:
+        raise UsageUnreadable(f"{window_name} resets_at carries no time zone")
+    return parsed
+
+
+def _read_utilization(all_bucket_fields: dict[object, object], window_name: str) -> float:
+    raw_utilization = all_bucket_fields.get(UTILIZATION_KEY)
+    if isinstance(raw_utilization, bool) or not isinstance(raw_utilization, (int, float)):
+        raise UsageUnreadable(f"{window_name} has no utilization number")
+    return float(raw_utilization)
+
+
+def _elapsed_percent(window_length: timedelta, resets_at: datetime, now: datetime) -> float:
+    elapsed_fraction = (now - (resets_at - window_length)) / window_length
+    clamped_elapsed_fraction = min(max(elapsed_fraction, 0.0), 1.0)
+    return round(clamped_elapsed_fraction * PERCENT_SCALE, PERCENT_DECIMAL_PLACES)
+
+
+def measure_window_pace(
+    window_name: str, window_length: timedelta, bucket: object, now: datetime
+) -> WindowPace:
+    """Measure one usage bucket's spend against its elapsed time.
+
+    ::
+
+        five_hour, 5h, {"utilization": 3.0, "resets_at": 18:50Z}, now 13:58Z
+        -> WindowPace("five_hour", 3.0, 2.7, 18:50Z)   over pace
+
+    Elapsed time counts from one window length before the reset, clamped to 0-100.
+
+    Args:
+        window_name: The usage bucket key.
+        window_length: How long the window runs.
+        bucket: The bucket object from the usage response.
+        now: The time the pace is measured at.
+
+    Raises:
+        UsageUnreadable: The bucket, its utilization, or its reset is unreadable.
+    """
+    if not isinstance(bucket, dict):
+        raise UsageUnreadable(f"usage response has no {window_name} window")
+    resets_at = _parse_resets_at(bucket.get(RESETS_AT_KEY), window_name)
+    return WindowPace(
+        name=window_name,
+        used_percent=_read_utilization(bucket, window_name),
+        elapsed_percent=_elapsed_percent(window_length, resets_at, now),
+        resets_at=resets_at,
+    )
+
+
+def measure_account_pace(
+    all_usage_buckets: dict[str, object], now: datetime
+) -> list[WindowPace]:
+    """Measure every rate window the verdict covers.
+
+    Args:
+        all_usage_buckets: The decoded usage response body.
+        now: The time the pace is measured at.
+
+    Returns:
+        One WindowPace per rate window, five-hour first.
+
+    Raises:
+        UsageUnreadable: Any covered window is missing or unreadable.
+    """
+    return [
+        measure_window_pace(each_name, each_length, all_usage_buckets.get(each_name), now)
+        for each_name, each_length in ALL_RATE_WINDOW_LENGTHS
+    ]
+
+
+def build_verdict(
+    all_window_paces: list[WindowPace], now: datetime
+) -> dict[str, object]:
+    """Assemble the JSON verdict for a set of measured windows.
+
+    Args:
+        all_window_paces: The measured windows.
+        now: The time the pace was measured at.
+
+    Returns:
+        The verdict mapping: the account-level flag, the check time, and
+        each window's percents, reset time, and flag.
+    """
+    return {
+        RESULT_KEY_OVER_PACE: any(
+            each_pace.over_pace for each_pace in all_window_paces
+        ),
+        RESULT_KEY_CHECKED_AT: now.isoformat(),
+        RESULT_KEY_WINDOWS: [
+            {
+                WINDOW_KEY_NAME: each_pace.name,
+                WINDOW_KEY_USED_PERCENT: each_pace.used_percent,
+                WINDOW_KEY_ELAPSED_PERCENT: each_pace.elapsed_percent,
+                WINDOW_KEY_RESETS_AT: each_pace.resets_at.isoformat(),
+                WINDOW_KEY_OVER_PACE: each_pace.over_pace,
+            }
+            for each_pace in all_window_paces
+        ],
+    }
+
+
+def _read_session_ingress_bearer() -> str:
+    configured_path = os.environ.get(INGRESS_BEARER_FILE_ENV_VAR)
+    if not configured_path:
+        raise UsageUnreadable(f"{INGRESS_BEARER_FILE_ENV_VAR} is unset")
+    try:
+        file_text = Path(configured_path).read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError) as read_error:
+        raise UsageUnreadable("session ingress token file is unreadable") from read_error
+    if not file_text:
+        raise UsageUnreadable("session ingress token file is empty")
+    return file_text
+
+
+def _certificate_context() -> ssl.SSLContext:
+    named_bundle = os.environ.get(SSL_CERT_FILE_ENV_VAR)
+    if named_bundle:
+        return ssl.create_default_context(cafile=named_bundle)
+    if Path(CONTAINER_PROXY_CA_BUNDLE_PATH).is_file():
+        return ssl.create_default_context(cafile=CONTAINER_PROXY_CA_BUNDLE_PATH)
+    return ssl.create_default_context()
+
+
+def _build_usage_request() -> urllib.request.Request:
+    return urllib.request.Request(
+        USAGE_ENDPOINT_URL,
+        headers={
+            AUTHORIZATION_HEADER: f"{BEARER_PREFIX}{_read_session_ingress_bearer()}",
+            ANTHROPIC_BETA_HEADER: USAGE_BETA_VALUE,
+            CONTENT_TYPE_HEADER_NAME: CONTENT_TYPE_JSON,
+        },
+    )
+
+
+def fetch_usage_payload() -> dict[str, object]:
+    """Read the usage of the account the session ingress token belongs to.
+
+    Returns:
+        The decoded response body.
+
+    Raises:
+        UsageUnreadable: No token, a failed request, or a body that is not a
+            JSON object. The message names the failure type, never the token.
+    """
+    try:
+        with urllib.request.urlopen(
+            _build_usage_request(),
+            timeout=PROBE_TIMEOUT_SECONDS,
+            context=_certificate_context(),
+        ) as usage_reply:
+            decoded = json.loads(usage_reply.read())
+    except urllib.error.HTTPError as http_error:
+        raise UsageUnreadable(f"usage endpoint answered HTTP {http_error.code}") from http_error
+    except (urllib.error.URLError, TimeoutError, OSError, ValueError) as probe_error:
+        raise UsageUnreadable(
+            f"usage probe failed with {type(probe_error).__name__}"
+        ) from probe_error
+    if not isinstance(decoded, dict):
+        raise UsageUnreadable("usage response body is not a JSON object")
+    return decoded
+
+
+def _read_payload_file(payload_path: str) -> dict[str, object]:
+    try:
+        decoded = json.loads(Path(payload_path).read_text(encoding="utf-8"))
+    except (OSError, ValueError) as read_error:
+        raise UsageUnreadable(
+            f"payload file unreadable: {type(read_error).__name__}"
+        ) from read_error
+    if not isinstance(decoded, dict):
+        raise UsageUnreadable("payload file is not a JSON object")
+    return decoded
+
+
+def _parse_arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Report whether the account running the project spends faster than its windows reset.",
+    )
+    parser.add_argument(
+        "--payload-file",
+        default=None,
+        help="A saved usage response to read instead of probing the endpoint.",
+    )
+    parser.add_argument(
+        "--now",
+        default=None,
+        help="ISO-8601 time with a zone to measure at; defaults to the current time.",
+    )
+    return parser.parse_args()
+
+
+def _measure_verdict(arguments: argparse.Namespace) -> dict[str, object]:
+    now = datetime.fromisoformat(arguments.now) if arguments.now else datetime.now(timezone.utc)
+    if now.tzinfo is None:
+        raise UsageUnreadable("--now carries no time zone")
+    all_usage_buckets = (
+        _read_payload_file(arguments.payload_file)
+        if arguments.payload_file
+        else fetch_usage_payload()
+    )
+    return build_verdict(measure_account_pace(all_usage_buckets, now), now)
+
+
+def _write_json_line(all_document_fields: dict[str, object]) -> None:
+    sys.stdout.write(json.dumps(all_document_fields) + "\n")
+    sys.stdout.flush()
+
+
+def main() -> int:
+    """Print the pace verdict JSON and return its exit code.
+
+    Returns:
+        0 when any window is over pace, 1 when every window is under pace,
+        2 when the meters or the arguments are unreadable.
+    """
+    try:
+        verdict = _measure_verdict(_parse_arguments())
+    except (UsageUnreadable, ValueError) as unreadable:
+        _write_json_line({RESULT_KEY_OVER_PACE: None, RESULT_KEY_ERROR: str(unreadable)})
+        return EXIT_CODE_UNREADABLE
+    _write_json_line(verdict)
+    return EXIT_CODE_OVER_PACE if verdict[RESULT_KEY_OVER_PACE] else EXIT_CODE_UNDER_PACE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/package.json

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

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -87,16 +87,12 @@ ROLE_BUGTEAM: str = "bugteam"
 ROLE_CLEAN_CODER: str = "clean-coder"
 """Compatibility role for FIX and standards-fix using poteto-agent."""
 
-ROLE_TRANSLATOR: str = "translator"
-"""Role the shared_utils translation chain dispatches, served by poteto-agent."""
-
 DEFAULT_ROLE: str = ROLE_BUGTEAM
 """Role applied when the caller does not pass ``--role``."""
 
 ALL_AGENT_FILENAMES_BY_ROLE: dict[str, tuple[str, ...]] = {
     ROLE_BUGTEAM: ("poteto-agent.md",),
     ROLE_CLEAN_CODER: ("poteto-agent.md",),
-    ROLE_TRANSLATOR: ("poteto-agent.md",),
 }
 """Agent definition filenames required under ``agents/`` for each known role."""
 

package/scripts/test_resolve_worker_spawn.py

@@ -57,7 +57,6 @@ from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     REASON_GROK_AUTH_FAILED,
     REASON_PROMPT_FILE_MISSING,
     REASON_TIMEOUT_OUT_OF_BOUNDS,
-    ROLE_TRANSLATOR,
     RESULT_KEY_ATTEMPTS,
     RESULT_KEY_OK,
     RESULT_KEY_OUTPUT,
@@ -867,33 +866,6 @@ def test_tier_three_argv_includes_agent_for_default_role(
     )
 
 
-def test_translator_role_dispatches_the_poteto_agent_on_tier_three(
-    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
-) -> None:
-    prompt_file, working_directory, run_state_directory = _paths(tmp_path)
-    call_log = _install_seams(
-        monkeypatch,
-        grok_outcome=_grok_failure(CLASSIFICATION_AUTH_FAILURE),
-        claude_outcome=_claude_served(),
-        host_profile=HOST_PROFILE_CLAUDE,
-    )
-
-    spawn_outcome = dispatcher.resolve_worker_spawn(
-        role=ROLE_TRANSLATOR,
-        prompt_file=prompt_file,
-        working_directory=working_directory,
-        timeout_seconds=DEFAULT_WORKER_TIMEOUT_SECONDS,
-        is_claude_tier_enabled=True,
-        run_state_directory=run_state_directory,
-    )
-
-    assert spawn_outcome.tier_used == TIER_CLAUDE_HEADLESS
-    assert call_log.claude_arguments is not None
-    agent_flag_index = call_log.claude_arguments.index(AGENT_FLAG)
-    assert call_log.claude_arguments[agent_flag_index + 1] == "poteto-agent"
-    assert ROLE_TRANSLATOR not in call_log.claude_arguments
-
-
 def test_large_prompt_stays_out_of_claude_argv(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None: