claude-dev-env 8.126.0 → 8.126.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -69,9 +69,12 @@ Read the JSON report and worker log after the process ends. The JSON fields are
69
69
  The runner writes one summary line with the selected account, exit code, and
70
70
  report path.
71
71
 
72
- When the command exits 3 and the report has `"account": "wait"`, no account is
73
- eligible. Report the picker's reason and reset time. Do not fall back to the
74
- Agent tool. Claude can also return exit 3 after a worker starts. When the
72
+ When the command exits 3 and the report has `"account": "wait"`, read the
73
+ picker's reason and follow the exit 3 steps in
74
+ [Proof before a pull request](~/.claude/docs/rule-guides/proof-before-pull-request.md).
75
+ Do not fall back to the Agent tool, except where those steps send the work
76
+ there after a failed meter read.
77
+ Claude can also return exit 3 after a worker starts. When the
75
78
  report account is `main`, `second`, or `extra_2` and later, report the child's
76
79
  exit code and result. Exit 124 with reason `timeout` means the worker ran past
77
80
  `--timeout-minutes`.
@@ -31,7 +31,7 @@ The broker stores cached meters, spent marks, and Claude session bindings in one
31
31
  | Code | Meaning |
32
32
  | --- | --- |
33
33
  | `0` | `choose` or `check` found an account, or the job exited successfully. |
34
- | `3` | No account clears its floor. The decision includes `resets_at`. |
34
+ | `3` | Wait. No account clears its floor, no read account clears its floor while other meters went unread, or no account meter could be read. The reason says which. The decision includes `resets_at`. |
35
35
  | `4` | A Claude job stopped with `advisor_blocked`, or every Claude account was unusable: each had no token or was signed out. |
36
36
  | `127` | A Codex job timed out, its command could not start while no Codex roster is configured, or the command could not start on any account in the roster. |
37
37
  | Other command code | `run` returns the command's exit code after a served response. |
@@ -35,7 +35,7 @@ When the host keeps an asks ledger with `ledger.py` and `asks_check.py`, record
35
35
 
36
36
  The installer registers `open_tasks_stop_gate.py` as a Stop hook for each host:
37
37
 
38
- - Claude Code: `hooks.json`. A block returns the reason, and the session updates its task list and ends the turn. An install into `~/.claude` also adds the same Stop entry to every profile under `~/.claude-profiles` that has its own `settings.json` and does not already run its own copy of the gate. A profile whose `settings.json` links to `~/.claude/settings.json` already has it. Uninstall removes only that entry. On install, a profile `settings.json` that is not valid JSON is left unchanged and listed under Action needed with its path and parse error, and the rest of the install goes on. On uninstall, such a file that still names the gate stops the uninstall before anything changes, so the manifest stays and a rerun after the fix removes the gate; one that does not name the gate is left as it is.
38
+ - Claude Code: `hooks.json`. A block returns the reason, and the session updates its task list and ends the turn. An install into `~/.claude` also adds the same Stop entry, and the `closing_question_round_gate.py` Stop entry after it, to every profile under `~/.claude-profiles` that has its own `settings.json`. Each gate is added on its own: a profile that holds one gets the other, and a gate the profile already runs from its own copy of the script is skipped. A profile whose `settings.json` links to `~/.claude/settings.json` already has both. Uninstall removes only those two entries. On install, a profile `settings.json` that is not valid JSON is left unchanged and listed under Action needed with its path and parse error, and the rest of the install goes on. On uninstall, such a file that still names either gate stops the uninstall before anything changes, so the manifest stays and a rerun after the fix removes the gates; one that names neither gate is left as it is.
39
39
  - Codex: `$CODEX_HOME/hooks.json`. Codex turns the reason into a continuation prompt.
40
40
  - Cursor: a native `stop` entry in `~/.cursor/hooks.json`. The reason comes back as `followup_message`, the next user message. A stop with status `aborted` or `error` passes, so a turn the user cancels stays silent.
41
41
 
@@ -42,3 +42,4 @@ The SessionStart hook `hooks/session/working_style_prompt.py` points every sessi
42
42
  - Use a clearly stated low-risk assumption when the intended result remains stable.
43
43
  - Pause for the user's choice before making a high-impact decision.
44
44
  - Hand the user a step as its own question, with the command block to paste or the link to open inside it. Leave long guides out.
45
+ - End a session the user started with a round of question cards, one for each item it leaves open. Brief every item in chat before the first card. When nothing is open, end the closing reply with the line `Open items: none.`
@@ -30,7 +30,11 @@ For a change to Claude Code behavior, such as a hook, skill, rule, setting, prom
30
30
  - Start the broker from your own shell, with your environment as is. The broker reads the account meters with your session's credentials and starts Claude without your session's variables.
31
31
  - Leave out `--bare` and `claude plugin eval`. Both drop the hooks and settings the user runs with.
32
32
  - Read the broker report for the account it chose. Read the stream for the hook events and their output, `permission_denials`, the final result, and the token usage on the result event.
33
- - When the broker exits 3 with action "wait", no account has room. Treat that as a blocked proof and report its reason and `resets_at`. Spawn Claude only through the broker.
33
+ - When the broker exits 3 with action "wait", read its reason. Start headless Claude only through the broker.
34
+ - "no account has room" means each account is below its usage floor. Treat that as a blocked proof and report the reason and `resets_at`.
35
+ - "no readable account has room" means each read account is below its usage floor, and the reason names the accounts whose meter went unread. Run the broker once more after `resets_at`. When it waits again, treat that as a blocked proof.
36
+ - "no account meter could be read" means the meter reads failed, often with HTTP 429. Usage may be left, and `resets_at` is when the broker checks again. Run the broker once more after `resets_at`.
37
+ - When that second run also says "no account meter could be read" in a cloud session, the session's own account has usage, because the session runs on it. Run the step with a subagent of the session, on the `--model` and `--effort` pair of the broker call, and in its own worktree when it edits code. In the proof, name the route and quote each account's unread reason. Outside a cloud session, a second wait is a blocked proof.
34
38
 
35
39
  Report it in the pull request body under "Proof in practice". List each command you ran, quote the output lines that show the effect, and state the difference between the runs with and without the change. The run on the target the change exists to fix belongs in this section before the pull request opens. List a condition the change does not target, such as an older data shape, under a "Not covered" heading at the same level.
36
40
 
@@ -24,6 +24,71 @@ When the user has several items to review or decide, such as test cases, finding
24
24
 
25
25
  The limit is 450 words and 15 list or table items of chat text before a question, counted from the start of the question's turn. A turn starts at a message the user types, at an answer or refusal of an earlier question, or at the first input after the previous turn ends, so text from an earlier turn never counts. A Stop hook that holds a reply keeps the turn open, so that reply's text counts. Each bullet or numbered line is one item, and each table row below the header is one item. Lines inside a code fence are not items. On Claude, the `question_brief_gate.py` PreToolUse hook refuses an `AskUserQuestion` call past either limit and names the limit it passed. The hook reads only the last 1 MB of the transcript, so a long review followed by more than 1 MB of tool output in the same turn is not seen. The text has already posted by then, so do not repeat it. Shorten the brief to the context and each choice's effect, or split the question and ask about one item now.
26
26
 
27
+ ## The closing round
28
+
29
+ A session the user started ends with a round of question cards on what it leaves open. When it leaves nothing open, its closing reply ends with this line alone, in plain text: `Open items: none.` On Claude, the `closing_question_round_gate.py` Stop hook holds the stop until the cards or that line follow.
30
+
31
+ ### What the gate checks
32
+
33
+ The gate reads the stretch: the session's records after the last question tool call that reached the user, then the payload's `last_assistant_message`. Claude Code runs Stop hooks before it writes the closing reply to the transcript, so the payload holds the newest text. When the transcript already ends with that text, it is read once: its last assistant record, question calls left aside, ends in the same text. A text that sits before a later work call is an older reply, so the payload text is read as new. It holds in two cases.
34
+
35
+ 1. The stretch holds an open-item line. The reason quotes the lines. The declaration does not release this hold.
36
+ 2. The stretch holds work, no open-item line, and the closing reply does not end with the declaration. Work is any tool call of the main thread other than a question call: an edit, a shell command, a read, or a subagent. Work counts from the last reply in the stretch that ended with the declaration.
37
+
38
+ A stretch with no work and no open-item line passes, so a chat-only answer needs no declaration. A reply that ends with the declaration closes the work before it, so a later turn of chat only needs no declaration. An open-item line written before that reply still holds.
39
+
40
+ Fences, HTML blocks, quoted paragraphs, code spans, and indented code blocks are left out. An indented code block is a run of lines indented by four spaces or a tab after a blank line, outside a list item. Tool inputs, tool results, and thinking are never read.
41
+
42
+ Each paragraph is matched with its single line breaks folded to spaces, so a marker split across a soft line break, such as "out of" and "scope" on the next line, still counts. The reason quotes the line, or the lines the marker spans. A line that holds a deferral, uncertainty, or judgment marker is an open-item line. Markers include "deferred", "follow-up", "parked", "out of scope", "for later", "later pull request", "separate PR", "pending", "TODO", "skipped", "blocked", "not run", "known gap", "open question", "not sure", "I assumed", "unverified", "untested", "did not test", "could not confirm", "not yet implemented", "your call", "up to you", "you may want to", "your judgment", "need your input", and "waiting on you". A line of chat text that ends with a question mark is an open-item line too. A marker reads as a whole word, and one to three underscores around it read as emphasis, so `_untested_` and `__untested__` count, and `retry_untested_flag` and `retry__untested__flag` do not. A marker inside a file name with a short lower-case extension, such as `todo.md`, or inside a path of two or more names that ends in a slash or a file name, such as `docs/pending/`, does not count either. A marker joined to another word, such as `skipped/untested`, and a marker of two or more words, such as `not tested`, still count. The module docstring of `closing_question_round_open_items.py` lists every marker. A negation does not cancel a marker, so "Nothing is deferred." is held. That hold costs one extra card, and the declaration line carries no marker.
43
+
44
+ The declaration counts when the last non-empty line of the reply's prose is `Open items: none.` alone, or that line wrapped in one bold or italic mark. The period may be left out, because a session after a compaction often drops it. It must come after the last work call. Bold and italic pass. The line in backticks, in a list item, in a quote, in a fence, or with more words on it does not.
45
+
46
+ ### The stretch
47
+
48
+ A call reached the user when the transcript holds its tool result, matched by `tool_use_id`, and that result is no error. A call a hook refused, a call that errored, and a call with no result yet do not end the stretch, so send the call again after a refusal. A later turn that a task notification starts does not clear what an earlier turn left open. Answers come back in the same turn, so act on them at once. An open-item line written after the cards starts a new stretch, and it needs its own cards. Work after the cards needs the cards or the declaration again.
49
+
50
+ ### Sessions the gate leaves alone
51
+
52
+ - A subagent, and a Cursor session.
53
+ - A headless run, where `CLAUDE_CODE_SESSION_ATTENDED` is `0`.
54
+ - A session no person typed into: a `claude -p` run, a session another agent created, or a scheduled run. A prompt a person typed carries `turnOrigin` equal to `human`, and so does a custom slash command. Once a person types a prompt there, the gate covers the session. On a host whose records carry no `turnOrigin` field at all, a session with a prompt counts as started by a person when `CLAUDE_CODE_SESSION_ATTENDED` is `1`.
55
+ - A stop while background work runs: a non-empty `background_tasks` list, object, or string. The session stops again when that work ends, and what it left open carries over.
56
+ - A session whose transcript cannot be read.
57
+ - A stop the gate cannot finish within 7 seconds by its own clock checks. The check runs in a child process, which is killed 8 seconds after the payload read starts, so one long step, such as a JSON parse, cannot keep the stop waiting. A watchdog thread ends a payload read that never finishes at 8.5 seconds. It reads the clock between lines, texts, and windows of each marker scan. A single regular expression pass over one text cannot be cut short, which is why a text over 2 MiB is skipped. In local runs, a 190 MB transcript of short prompt lines took 4.5 seconds, and 160 to 180 MB transcripts that hold many 2 MiB texts of code spans reached the deadline and passed in 7.3 to 7.4 seconds.
58
+ - A stop where the gate itself fails, or where a standard stream is closed or cannot be written. It passes with exit code 0. A hold whose output write has not finished 1 second after it starts, such as a write to a full pipe nobody reads, ends with exit code 0.
59
+
60
+ ### Two holds
61
+
62
+ The gate counts its own holds, as feedback records that open with the first sentence of a reason, since the later of the last typed prompt and the last answered question call, and it allows the stop after two. Both reasons count. It checks every stop again, also one a Stop hook already held, so a reply in plain text does not release a hold. A host with no question tool gets two holds and then stops. There, give each open item its own short paragraph in the reply.
63
+
64
+ ### How to run a round
65
+
66
+ 1. Find the items. Look in the task list, your running notes, worker reports, the "Not covered" section of each pull request body, and your own words in the transcript.
67
+ 2. Read the live state of each item, and drop each one that is done.
68
+ 3. Write one chat brief before the first call. Say where things stand in two or three lines. Then give each item one short paragraph that names each option label and its effect, with its links. The brief covers every item, because the user answers the first set of cards before the second set shows. `question_brief_gate.py` counts the chat text since the last typed prompt or question result, the held reply included, and refuses a call past 450 words or 15 list or table items. When the held reply is already past that, write a one-line brief and send the cards. That call is refused, and a refused question starts a new count, so send the same cards again at once with no new text.
69
+ 4. Send each item as its own question. One call holds at most four questions, so a longer round takes more calls. Give each question a header of 12 characters or fewer and two or three options, with your recommendation first. Give each option a one-sentence description. A card shows plain text, so write a link in a card as a bare URL.
70
+ 5. An answer can be free text. Follow what it says, and treat new work it adds as an ask.
71
+ 6. Close in plain words with what you did with each answer, and do not restate the items. A reply after the cards that repeats a marker, such as "The backoff setting stays deferred", starts a new stretch and is held. Write "The backoff setting stays as it is" there. When that work leaves nothing open, end with `Open items: none.`
72
+
73
+ When the lines name nothing that is still open, send one question that says so and lets the user add an item.
74
+
75
+ ### Limits
76
+
77
+ - The gate holds at most twice per typed prompt or answered card.
78
+ - A marker can hold a line that names no open item, such as a negation or a line about the word itself. That hold costs one card.
79
+ - An item recorded only in the task list or in a file is not seen. The hold reason tells the agent to read those.
80
+ - A card about another subject still ends the stretch.
81
+ - A session whose only prompts came from an agent is not covered.
82
+ - A scheduled wake inside a session a person started is held like any other stop.
83
+ - A payload over 16 MiB passes unread. A transcript line over 16 MiB or a text over 2 MiB is skipped, and a stop the gate cannot finish within 7 seconds passes.
84
+ - The gate counts one of its holds only when the feedback record starts with "Stop hook feedback" and carries the first sentence of the reason in its first 200 characters. A host that writes the feedback in another shape gets a hold on every stop, up to its own limit.
85
+ - Text inside an HTML block is not read.
86
+ - A marker joined to a word by four or more underscores still reads as a marker.
87
+ - A marker joined to a file name by a hyphen, such as `todo-list.md`, still reads as a marker.
88
+ - Text the masking misses reads as prose and can hold, such as an unclosed fence or a quote indented four spaces inside a nested list item.
89
+ - A question call whose id holds a character the transcript escapes outside printable ASCII, such as `"` or `é`, is not matched to its result, so the stretch does not end there. Claude Code writes ids of letters, digits, and underscores.
90
+ - The gate runs on Claude Code only.
91
+
27
92
  ## Codex visual comparisons
28
93
 
29
94
  For Codex visual comparisons, find Page creation, visualization upload, and Page opening tools. Create the comparison, upload its visualization, and open its Page here before asking. If tools are missing, steps fail, or opening queues, compare in chat before asking. Put inline Visualize references only in final replies. An async acknowledgement or saved visual is context only; wait for and use the submitted answer before dependent work.
@@ -51,6 +51,12 @@ the wait reason names each account whose meter could not be read. A window the
51
51
  usage endpoint returns as `null` holds no account back, but an account needs at
52
52
  least one window with a percent to have room.
53
53
 
54
+ A wait whose reason starts "no account meter could be read" is a failed read,
55
+ and the account may have usage left. An HTTP 429 from the usage endpoint holds
56
+ that account's probe for 5 minutes.
57
+ [Proof before a pull request](rule-guides/proof-before-pull-request.md) says
58
+ what a session does next.
59
+
54
60
  ```
55
61
  python packages/claude-dev-env/scripts/account_broker.py choose --product claude
56
62
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-dev-env",
3
- "version": "8.126.0",
3
+ "version": "8.126.2",
4
4
  "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,11 +1,13 @@
1
1
  # Present questions clearly
2
2
 
3
- Before every ask, repeats too, give a short chat brief with context, each choice's effect, and helpful visuals.
3
+ Before every ask, repeats too, brief in chat: context, each choice's effect, visuals.
4
4
 
5
- Ask one short question per item, never a chat list, with two or three choices, each a short label and sentence. Reuse labels in brief, comparison, and picker. Keep the turn's chat text before a question to 450 words and 15 list or table items; a Claude hook refuses more.
5
+ One question per item, no chat list: two or three choices, each a label and sentence. Reuse labels in brief, comparison, picker. Cap a turn's pre-question chat at 450 words and 15 list or table items; a Claude hook refuses more.
6
6
 
7
- Find the native question tool. Claude may use `AskUserQuestion`; Codex may use `request_user_input_async` or `request_user_input`. Honor mode rules. Put the question and choices in its fields. If unusable, ask in chat.
7
+ Question tools: Claude `AskUserQuestion`, Codex `request_user_input_async` or `request_user_input`. Honor mode rules. Its fields hold question and choices; if unusable, ask in chat.
8
8
 
9
- To hand over a step, option cards, or a Codex visual comparison, read the full text first.
9
+ End a user-started session with a card per open item or end on `Open items: none.`; a Claude hook holds the stop.
10
+
11
+ Read the full text for a step handover, option cards, or Codex visual comparison.
10
12
 
11
13
  **Full text:** [`~/.claude/docs/rule-guides/question-presentation.md`](../docs/rule-guides/question-presentation.md).