claude-dev-env 8.43.5 → 8.44.0

package/_shared/advisor/advisor-protocol.md

@@ -138,8 +138,8 @@ Drift signals and the per-host re-spawn / re-bind steps: [`reference/lifecycle.m
 
 ## CLI chain
 
-The shared runner is `python "$HOME/.claude/scripts/claude_chain_runner.py" [--routing-mode usage_ranked|ordered_account] -- <claude args...>`.
-Modes and failover, the tier-to-alias table, brief piping, and `--resume` session handling: [`reference/cli-chain.md`](reference/cli-chain.md).
+The shared runner is `python "$HOME/.claude/scripts/account_broker.py" run --product claude --report <path> -- claude <args...>`.
+Account choice, failover, the tier-to-alias table, brief piping, and `--resume` session handling: [`reference/cli-chain.md`](reference/cli-chain.md).
 
 **Third-party host:** the primary bind and consult path; the walk order and fail-closed rule live in [`reference/third-party-bind.md`](reference/third-party-bind.md).
 

package/_shared/advisor/reference/cli-chain.md

@@ -1,18 +1,15 @@
 # CLI Claude-chain
 
 Detail behind the `## CLI chain` section of [`advisor-protocol.md`](../advisor-protocol.md).
-The shared runner is `python "$HOME/.claude/scripts/claude_chain_runner.py" [--routing-mode usage_ranked|ordered_account] -- <claude args...>`.
+The shared runner is `python "$HOME/.claude/scripts/account_broker.py" run --product claude --report <path> -- claude <args...>`.
 
-## Modes
+## Account choice
 
-| Mode | Flag | Walk order | Failover |
-|---|---|---|---|
-| Usage-ranked (default) | `--routing-mode usage_ranked` or omit the flag | Highest weekly remaining first (`claude_chain_usage` / usage-pause OAuth probe) | Usage-limit signature only |
-| Ordered-account | `--routing-mode ordered_account` | Config list order in `~/.claude/claude-chain.json` | Usage-limit signature only; auth / timeout / config / other process errors → `advisor_blocked` |
-
-**Root advisor bind and consult** (the third-party host path): ordered-account mode. A non-usage failure terminates with `terminal_status=advisor_blocked`, exit code 4 on the CLI.
-
-**General chain calls** (non-root automation): keep the default usage-ranked mode.
+The broker applies the main account guard and chooses an eligible extra account
+by remaining usage. On a usage-limit response, it tries another account. If no
+account has room, it reports a reset time and exits with code 3. A non-usage
+Claude failure has `JobOutcome.status == "advisor_blocked"`; the CLI exits with
+code 4. The report path receives the broker's decision and attempt events.
 
 ## Tier-to-alias map
 
@@ -38,8 +35,8 @@ Drop the file once the consult completes.
 
 ## Session resume
 
-Read the `session_id` out of the first call's JSON events.
+Read the `session_id` out of the first call's JSON events or `JobOutcome.session_id`.
 Pass it to `-p --resume <session_id> --output-format json` on every later consult — `-p` stays on the resume call too, since it is still a non-interactive invocation.
-A session store belongs to the binary and account that minted it, so after a usage-limit failover to the next binary a `--resume` against it can fail.
+A session store belongs to the account that minted it. The broker keeps account affinity when that account has room. If the account reaches a usage limit, a `--resume` on another account can fail.
 Treat that failure as starting over.
 Resend the charter plus a compact recap of the consults since the last one, capture the new `session_id` the fresh call returns, and continue from there.

package/_shared/advisor/reference/lifecycle.md

@@ -22,6 +22,6 @@ Every other consumer reaches it by message alone; spawn, respawn, and shutdown b
 
 The orchestrating session owns the CLI advisor bind for the whole run: first bind, re-bind on drift or lost `session_id`, and fail-closed report when the bound path cannot serve.
 
-**Re-bind on drift.** If a reply shows a stale picture, the task pivots, or `--resume` fails after a usage-limit failover (session stores are per binary/account), re-bind Opus through `claude_chain_runner.py` with the charter plus a compact recap of consults so far.
+**Re-bind on drift.** If a reply shows a stale picture, the task pivots, or `--resume` fails after a usage-limit failover, re-bind Opus through `python "$HOME/.claude/scripts/account_broker.py" run --product claude --report <path> -- claude <args...>` with the charter plus a compact recap of consults so far.
 Capture the new `session_id`, and log a fresh Opus walk with `result: "cli"` on success, then Astra when that rung is open. An Astra re-bind uses `codex_astra_advisor.py --bind --enable-astra` with the same charter and recap, and records `result: "codex"` on success.
 Executors keep reporting to the orchestrating session; advisor binding stays with that session alone.

package/_shared/advisor/reference/third-party-bind.md

@@ -22,15 +22,15 @@ When the Astra flag is off, follow the Claude-chain steps below.
 3. **CLI bind (primary path):** for Opus, pipe a charter file into:
 
    ```
-   python "$HOME/.claude/scripts/claude_chain_runner.py" --routing-mode ordered_account -- -p --model <alias> --effort <effort> --output-format json
+   python "$HOME/.claude/scripts/account_broker.py" run --product claude --report <path> -- claude -p --model <alias> --effort <effort> --output-format json
    ```
 
    Use `--model opus --effort` with the value of `ADVISOR_EFFORT` (default `xhigh`) on Opus.
    User-facing wording follows [`rules/asd-ste100-language.md`](../../../rules/asd-ste100-language.md).
-   A root advisor bind uses `--routing-mode ordered_account`. Walk order, failover, and the `advisor_blocked` terminal status are in [`cli-chain.md`](cli-chain.md).
+   Account choice, failover, and the `advisor_blocked` status are in [`cli-chain.md`](cli-chain.md).
 4. Stop at the first successful bind.
    Record `{tier, result: "cli"}` for Opus or `{tier: "Astra", result: "codex"}` for the Astra helper, and set `selected_tier` to that tier.
-   Persist `session_id` from the JSON events (any event carries it; the runner also surfaces it on `ChainInvocationOutcome.session_id`; reply text is the `type == "result"` event's `.result` field).
+   Persist `session_id` from the JSON events or `JobOutcome.session_id`; reply text is the `type == "result"` event's `.result` field.
    Run every bind and every later consult with cwd set to the repo root the work is for. Claude sessions are project-scoped by working directory.
 5. **Fail closed:** when every candidate fails (chain exhausted, `advisor_blocked`, or model unavailable), set `selected_tier = null` and a `fallback_reason`, report that the advisor is unreachable, and **stop**. ENDORSE / CORRECTION / PLAN / STOP come only from a bound advisor.
 6. Assemble and paste each executor's Advisor block from [`advisor-block.md`](advisor-block.md). Executors report to the orchestrating session; that session consults the bound advisor and relays the four-signal reply.

package/bin/install.test.mjs

@@ -216,7 +216,7 @@ test('core includeDirectories ships _shared and scripts for advisor protocol and
     );
     assert.ok(
         CORE_INCLUDE_DIRECTORIES.includes('scripts'),
-        'scripts must ship with --only core so claude_chain_runner.py is available for advisor CLI fallback',
+        'scripts must ship with --only core so account_broker.py is available for advisor CLI fallback',
     );
 });
 

package/docs/second-claude-account.md

@@ -9,12 +9,12 @@ keeps its own sign-in and history.
 | File | What it does |
 |---|---|
 | `scripts/claude_account_profile.py` | Links each shared entry of `~/.claude` into the profile `~/.claude-profiles/ev`, moves stale copies into `.replaced/<time>/`, and writes the `claude-ev.cmd` launcher into `~/.local/bin` |
-| `scripts/claude_account_choice.py` | Reads both accounts' 5-hour and weekly meters and prints which account a job runs on |
-| `scripts/claude_account_worker.py` | Runs one headless Claude worker using the account chosen by the picker |
-| `scripts/claude_account_worker_process.py` | Launches the worker process, feeds it the brief, and kills it on timeout |
+| `scripts/account_broker.py` | Reads the account roster and usage meters, chooses an account, and runs Claude with that account's home |
+| `scripts/claude_account_worker.py` | Runs one headless Claude worker through the broker |
+| `scripts/claude_account_worker_process.py` | Sends the brief to the broker and measures the run |
 | `scripts/claude_account_worker_report.py` | Builds and writes the JSON report a worker leaves behind |
 | `scripts/dev_env_scripts_constants/claude_account_worker_constants.py` | The worker's flag names, defaults, exit codes, and report keys |
-| `scripts/dev_env_scripts_constants/claude_account_constants.py` | The profile name, the entries that stay per account, and the picker thresholds |
+| `scripts/dev_env_scripts_constants/claude_account_constants.py` | The profile name, the entries that stay per account, and the account thresholds |
 
 The launcher sets `CLAUDE_CONFIG_DIR` to the profile and passes every argument to
 `claude`, so `claude-ev -p "..."` runs like `claude -p "..."` on the second
@@ -43,19 +43,17 @@ to spend leftover usage that expires soon.
 |---|---|
 | Main week resets within 24 hours, main under 90% of its week, main under 50% of its 5-hour window | main |
 | Otherwise, second under 95% of its week and under 90% of its 5-hour window | second |
-| Second meter unreadable | second, whose own run refreshes the sign-in |
+| Second meter unreadable | wait until the meter can be read |
 | Otherwise | wait, with the next reset time |
 
 An unreadable main meter never picks main.
 
 ```
-python packages/claude-dev-env/scripts/claude_account_choice.py
-{"account": "second", "config_dir": "C:\\Users\\me\\.claude-profiles\\ev", "reason": "...",
- "meters": {"main": {"session_used_percent": 12.0, "session_resets_at": "...",
-                     "weekly_used_percent": 34.0, "weekly_resets_at": "..."},
-            "second": null}}
+python packages/claude-dev-env/scripts/account_broker.py choose --product claude
 ```
 
-The `meters` object carries each account's used percent and reset time for the
-5-hour window and the week. An account whose meter could not be read shows `null`.
-A usage report reads both accounts from this one call.
+The JSON output has a `decision` object and an `accounts` list. Each account's
+`meters` holds its remaining percent and reset time for the 5-hour window and
+the week. An unreadable meter appears as `null`. A wait decision has
+`action: "wait"` and a `resets_at` timestamp. The broker exits with code 3 on
+wait. The worker writes the same reset time to its report.

package/hooks/blocking/reply_length_gate.py

@@ -18,6 +18,10 @@ It denies a banned word or phrase, matched whole and case-insensitive::
 The gate uses the ``banned_words`` list in ``~/.claude/reply-banned-words.json``,
 or in the file that CLAUDE_REPLY_BANNED_WORDS_PATH names. Without a valid
 list there, it uses ALL_DEFAULT_BANNED_WORDS.
+
+The banned-word check also reads every text field of a decision card.
+A decision card gets no length check.
+
 Each non-empty line counts as its own sentence, so a list counts one
 sentence per item. URLs, markdown link targets, inline code spans, and
 fenced blocks carry no words.
@@ -52,8 +56,10 @@ from hooks_constants.reply_length_gate_constants import (
     BANNED_WORDS_JSON_KEY,
     BANNED_WORDS_PATH_ENV_VAR,
     BLOCK_EXIT_CODE,
+    CARD_TEXT_SEPARATOR,
     CLAUDE_HOME_DIRECTORY_NAME,
     CONFIG_FILE_ENCODING,
+    DECISION_CARD_TOOL_NAME,
     FENCED_BLOCK_PATTERN,
     HOOK_EVENT_NAME,
     INLINE_CODE_PATTERN,
@@ -163,26 +169,52 @@ def banned_word_violation(reply_text: str, all_banned_words: tuple[str, ...]) ->
     return None
 
 
+def all_card_texts(card_value: object) -> list[str]:
+    """Collect every string inside a decision card's input, in order."""
+    if isinstance(card_value, str):
+        return [card_value]
+    if isinstance(card_value, dict):
+        return [
+            each_text
+            for each_value in card_value.values()
+            for each_text in all_card_texts(each_value)
+        ]
+    if isinstance(card_value, list):
+        return [each_text for each_value in card_value for each_text in all_card_texts(each_value)]
+    return []
+
+
+def tool_violation(tool_name: object, all_tool_input: dict[str, object]) -> tuple[str, str] | None:
+    """Return the deny reason and the checked text for one call, or None when it passes."""
+    if tool_name == DECISION_CARD_TOOL_NAME:
+        card_text = CARD_TEXT_SEPARATOR.join(all_card_texts(all_tool_input))
+        card_violation = banned_word_violation(card_text, configured_banned_words())
+        return None if card_violation is None else (card_violation, card_text)
+    if tool_name not in ALL_CHECKED_TOOL_NAMES:
+        return None
+    reply_text = all_tool_input.get(TEXT_KEY)
+    if not isinstance(reply_text, str):
+        return None
+    violation = (
+        length_violation(reply_text)
+        or unlinked_pull_request_violation(reply_text)
+        or banned_word_violation(reply_text, configured_banned_words())
+    )
+    return None if violation is None else (violation, reply_text)
+
+
 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 tool_name not in ALL_CHECKED_TOOL_NAMES:
-        return ALLOW_EXIT_CODE
     tool_input = hook_input.get(TOOL_INPUT_KEY)
     if not isinstance(tool_input, dict):
         return ALLOW_EXIT_CODE
-    reply_text = tool_input.get(TEXT_KEY)
-    if not isinstance(reply_text, str):
-        return ALLOW_EXIT_CODE
-    violation = (
-        length_violation(reply_text)
-        or unlinked_pull_request_violation(reply_text)
-        or banned_word_violation(reply_text, configured_banned_words())
-    )
-    if violation is None:
+    checked = tool_violation(tool_name, tool_input)
+    if checked is None:
         return ALLOW_EXIT_CODE
+    violation, reply_text = checked
     block_reason = violation + RETRY_INSTRUCTION
     log_hook_block(
         Path(__file__).name,

package/hooks/blocking/test_reply_length_gate.py

@@ -322,3 +322,58 @@ def test_should_keep_the_defaults_when_the_config_file_is_malformed(
     config_path.write_text("{not json", encoding="utf-8")
     exit_code, _ = run_gate(monkeypatch, capsys, REPLY_TOOL_NAME, {"text": "It likely passed."})
     assert exit_code == 2
+
+
+DECISION_TOOL_NAME = "mcp__hearthbot__ask_decision"
+
+
+def test_should_deny_a_decision_card_that_hedges_in_an_option(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        DECISION_TOOL_NAME,
+        {
+            "question": "Exclude the call button?",
+            "context": "Crops show the call button flagged in 7 themes.",
+            "options": [
+                {"label": "Exclude it", "consequence": "Three themes probably pass."},
+                {"label": "Leave it", "consequence": "Three themes keep a warning."},
+            ],
+            "recommended": 0,
+        },
+    )
+    assert exit_code == 2
+    assert '"probably"' in stderr_text
+
+
+def test_should_allow_a_long_decision_card_with_no_hedge(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        DECISION_TOOL_NAME,
+        {
+            "question": "Exclude the call button?",
+            "context": " ".join([FIFTEEN_WORD_SENTENCE] * 5),
+            "options": [
+                {"label": "Exclude it", "consequence": SIXTEEN_WORD_SENTENCE},
+                {"label": "Leave it", "consequence": "Three themes keep a warning."},
+            ],
+            "recommended": 0,
+        },
+    )
+    assert (exit_code, stderr_text) == (0, "")
+
+
+@pytest.mark.parametrize(
+    "reply_text",
+    ["It maybe passed.", "Perhaps it passed.", "It might be the cache.", "I am not sure it passed."],
+)
+def test_should_deny_the_hedges_the_default_list_adds(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], reply_text: str
+) -> None:
+    exit_code, _ = run_gate(monkeypatch, capsys, REPLY_TOOL_NAME, {"text": reply_text})
+    assert exit_code == 2

package/hooks/hooks.json

@@ -83,7 +83,7 @@
         ]
       },
       {
-        "matcher": "mcp__hearthbot__reply|mcp__hearthbot__post_message",
+        "matcher": "mcp__hearthbot__reply|mcp__hearthbot__post_message|mcp__hearthbot__ask_decision",
         "hooks": [
           {
             "type": "command",

package/hooks/hooks_constants/reply_length_gate_constants.py

@@ -5,6 +5,8 @@ import re
 MAXIMUM_SENTENCE_COUNT = 3
 MAXIMUM_WORDS_PER_SENTENCE = 15
 ALL_CHECKED_TOOL_NAMES = frozenset({"mcp__hearthbot__reply", "mcp__hearthbot__post_message"})
+DECISION_CARD_TOOL_NAME = "mcp__hearthbot__ask_decision"
+CARD_TEXT_SEPARATOR = "\n"
 TOOL_NAME_KEY = "tool_name"
 TOOL_INPUT_KEY = "tool_input"
 TEXT_KEY = "text"
@@ -45,6 +47,15 @@ ALL_DEFAULT_BANNED_WORDS = (
     "suspect",
     "guess",
     "my theory",
+    "maybe",
+    "perhaps",
+    "presumably",
+    "might be",
+    "may be",
+    "appears to",
+    "i believe",
+    "not sure",
+    "unsure",
 )
 BANNED_WORD_PART_SEPARATOR = r"\s+"
 BANNED_WORD_PATTERN_TEMPLATE = r"(?<![A-Za-z0-9]){word_pattern}(?![A-Za-z0-9])"

package/package.json

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

package/scripts/_code_review_test_support.py

@@ -24,13 +24,8 @@ _SCRIPTS_DIRECTORY = str(Path(__file__).resolve().parent)
 if _SCRIPTS_DIRECTORY not in sys.path:
     sys.path.insert(0, _SCRIPTS_DIRECTORY)
 
-import claude_chain_runner as chain_runner  # noqa: E402
 import invoke_code_review as invoker  # noqa: E402
-from claude_chain_runner import ChainAttempt, ChainInvocationOutcome  # noqa: E402
-from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
-    TERMINAL_STATUS_CHAIN_EXHAUSTED,
-    TERMINAL_STATUS_SERVED,
-)
+from dev_env_scripts_constants.account_broker_constants import JobOutcome, Product, WAIT_EXIT_CODE
 from dev_env_scripts_constants.code_review_constants import (  # noqa: E402
     CLI_SESSION_MODEL_FLAG,
     CODE_REVIEW_MODEL_ALIAS,
@@ -111,27 +106,29 @@ def claude_served(
     *,
     returncode: int = FIXTURE_CHAIN_RETURNCODE,
     stdout: str = FIXTURE_CHAIN_STDOUT,
-) -> ChainInvocationOutcome:
-    return ChainInvocationOutcome(
-        served_command=FIXTURE_SERVED_COMMAND,
+) -> JobOutcome:
+    return JobOutcome(
         returncode=returncode,
         stdout=stdout,
         stderr="",
-        attempts=(ChainAttempt(command=FIXTURE_SERVED_COMMAND, status="served"),),
-        terminal_status=TERMINAL_STATUS_SERVED,
+        account_name=FIXTURE_SERVED_COMMAND,
+        attempts=((FIXTURE_SERVED_COMMAND, "served"),),
+        status="served" if returncode == 0 else "advisor_blocked",
+        session_id=None,
+        wait_reset_at=None,
     )
 
 
-def claude_failed() -> ChainInvocationOutcome:
-    return ChainInvocationOutcome(
-        served_command=None,
-        returncode=FIXTURE_FAILED_RETURNCODE,
+def claude_failed() -> JobOutcome:
+    return JobOutcome(
+        returncode=WAIT_EXIT_CODE,
         stdout="",
-        stderr="chain exhausted",
-        attempts=(
-            ChainAttempt(command=FIXTURE_SERVED_COMMAND, status="usage_limited"),
-        ),
-        terminal_status=TERMINAL_STATUS_CHAIN_EXHAUSTED,
+        stderr="",
+        account_name=None,
+        attempts=((FIXTURE_SERVED_COMMAND, "usage_limited"),),
+        status="exhausted",
+        session_id=None,
+        wait_reset_at=None,
     )
 
 
@@ -179,7 +176,7 @@ class SeamCallLog:
 @dataclass
 class _SeamConfiguration:
     host_profile: str
-    claude_outcome: ChainInvocationOutcome | BaseException | None
+    claude_outcome: JobOutcome | BaseException | None
     should_dirty_tree_on_chain: bool
     working_directory: Path | None
 
@@ -220,23 +217,21 @@ def _build_host_profile_seam(
 
 def _build_claude_seam(
     call_log: SeamCallLog, configuration: _SeamConfiguration
-) -> Callable[..., ChainInvocationOutcome]:
+) -> Callable[..., JobOutcome]:
     def fake_claude(
-        all_claude_arguments: list[str], *, timeout_seconds: int
-    ) -> ChainInvocationOutcome:
+        product: Product, all_claude_arguments: list[str], **options: object
+    ) -> JobOutcome:
+        assert product is Product.CLAUDE
         call_log.claude_calls += 1
-        call_log.claude_arguments = list(all_claude_arguments)
-        chain_runner.chain_subprocess_runner(
-            ["claude", *all_claude_arguments],
-            capture_output=True,
-            text=True,
-            timeout=timeout_seconds,
-            check=False,
-        )
+        call_log.claude_arguments = list(all_claude_arguments[1:])
+        call_log.is_stdin_empty = options.get("stdin_text") == ""
+        if options.get("cwd") is not None:
+            call_log.claude_working_directory = Path(options["cwd"])
+            call_log.all_observed_working_directories.append(Path(options["cwd"]))
         _record_dirty_tree(configuration)
         if isinstance(configuration.claude_outcome, BaseException):
             raise configuration.claude_outcome
-        assert isinstance(configuration.claude_outcome, ChainInvocationOutcome)
+        assert isinstance(configuration.claude_outcome, JobOutcome)
         return configuration.claude_outcome
 
     return fake_claude
@@ -284,18 +279,13 @@ def _apply_seams(
         "review_claude_runner",
         _build_claude_seam(call_log, configuration),
     )
-    monkeypatch.setattr(
-        chain_runner,
-        "chain_subprocess_runner",
-        _build_subprocess_seam(call_log),
-    )
 
 
 def install_seams(
     monkeypatch: pytest.MonkeyPatch,
     *,
     host_profile: str = HOST_PROFILE_CLAUDE,
-    claude_outcome: ChainInvocationOutcome | BaseException | None = None,
+    claude_outcome: JobOutcome | BaseException | None = None,
     should_dirty_tree_on_chain: bool = False,
     working_directory: Path | None = None,
 ) -> SeamCallLog: