claude-dev-env 8.111.4 → 8.112.0
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.
- package/.agents/skills/build-eval/evals/review/README.md +2 -2
- package/.agents/skills/build-eval/evals/review/review_eval_support/account.py +166 -0
- package/.agents/skills/build-eval/evals/review/review_eval_support/config/constants.py +26 -0
- package/.agents/skills/build-eval/evals/review/review_eval_support/execution.py +8 -0
- package/.agents/skills/build-eval/evals/review/test_run.py +261 -0
- package/_shared/advisor/reference/astra-rung.md +13 -5
- package/_shared/advisor/scripts/codex_astra_advisor.py +31 -8
- package/_shared/advisor/scripts/codex_astra_preflight.py +70 -14
- package/_shared/advisor/scripts/config/advisor_scripts_constants/astra_advisor_constants.py +7 -0
- package/_shared/advisor/scripts/tests/test_codex_astra_advisor.py +266 -2
- package/_shared/advisor/scripts/tests/test_codex_astra_preflight.py +114 -8
- package/_shared/pr-loop/scripts/check_convergence.py +5 -1
- package/_shared/pr-loop/scripts/codex_review_account.py +180 -0
- package/_shared/pr-loop/scripts/codex_review_scripts_constants/account_constants.py +28 -0
- package/_shared/pr-loop/scripts/codex_review_scripts_constants/run_constants.py +3 -1
- package/_shared/pr-loop/scripts/run_codex_review.py +144 -15
- package/_shared/pr-loop/scripts/test_check_convergence_codex.py +3 -3
- package/_shared/pr-loop/scripts/test_codex_review_account.py +355 -0
- package/_shared/pr-loop/scripts/test_run_codex_review.py +507 -6
- package/docs/account-broker.md +6 -4
- package/docs/codex-accounts.md +57 -16
- package/docs/rule-guides/question-presentation.md +4 -0
- package/docs/second-claude-account.md +1 -1
- package/hooks/blocking/final_reply_gate.py +59 -3
- package/hooks/blocking/open_tasks_transcript.py +18 -0
- package/hooks/blocking/test_final_reply_gate.py +160 -0
- package/hooks/features/conduct-gates.md +1 -4
- package/hooks/hooks.json +0 -10
- package/hooks/hooks_constants/final_reply_gate_constants.py +16 -0
- package/hooks/hooks_constants/open_tasks_stop_gate_constants.py +9 -0
- package/package.json +1 -1
- package/rules/question-presentation.md +1 -1
- package/scripts/account_broker.py +122 -27
- package/scripts/account_broker_support.py +54 -3
- package/scripts/codex_account_choice.py +12 -8
- package/scripts/codex_account_chooser.py +110 -0
- package/scripts/codex_account_meters.py +43 -4
- package/scripts/codex_plan_rules.py +156 -0
- package/scripts/dev_env_scripts_constants/account_broker_constants.py +41 -42
- package/scripts/dev_env_scripts_constants/codex_account_constants.py +62 -2
- package/scripts/dev_env_scripts_constants/test_account_broker_constants.py +359 -2
- package/scripts/dev_env_scripts_constants/test_codex_account_constants.py +213 -14
- package/scripts/policy_lint/adapter_configuration.py +0 -5
- package/scripts/policy_lint/config/constants.py +0 -1
- package/scripts/test_account_broker.py +1913 -526
- package/scripts/test_account_broker_support.py +77 -0
- package/scripts/test_codex_account_meters.py +95 -0
- package/scripts/tests/test_adapter_configuration.py +0 -8
- package/hooks/blocking/merge_over_review_offer_gate.py +0 -114
- package/hooks/blocking/test_merge_over_review_offer_gate.py +0 -138
- package/hooks/hooks_constants/merge_over_review_offer_gate_constants.py +0 -34
package/docs/codex-accounts.md
CHANGED
|
@@ -11,16 +11,20 @@ A job asks the broker which account to use.
|
|
|
11
11
|
|---|---|
|
|
12
12
|
| `scripts/account_broker.py` | `choose --product codex` names the account and tier a job runs on; `check --product codex` reports whether any account has room |
|
|
13
13
|
| `scripts/codex_account_choice.py` | `sync` links the shared setup into every account's home; `setup` and `install` write one launcher per account |
|
|
14
|
-
| `scripts/codex_account_meters.py` | Reads one account's rate-limit windows through `codex app-server` with `CODEX_HOME` set to that account's home |
|
|
15
|
-
| `scripts/
|
|
14
|
+
| `scripts/codex_account_meters.py` | Reads one account's rate-limit windows, plan and credits through `codex app-server` with `CODEX_HOME` set to that account's home |
|
|
15
|
+
| `scripts/codex_plan_rules.py` | Judges one account's meters: the paid-plan list, the free, unlisted and Pro plan rules, the floors, and the tier the account reaches |
|
|
16
|
+
| `scripts/codex_account_chooser.py` | Picks the Codex account and tier from the readings, Pro plan accounts first, up to the tier a caller requires |
|
|
17
|
+
| `scripts/dev_env_scripts_constants/codex_account_constants.py` | The fallback account names, the roster variable and file, the launcher template, the shared entry names, the 10% bar, the 1% Luna stop, the 20% short-window floor for Luna, the switch that lifts the weekly stop, the Pro, other paid and free plan names, and the credit keys |
|
|
16
18
|
|
|
17
19
|
## Names and order
|
|
18
20
|
|
|
19
|
-
The account list names the accounts
|
|
20
|
-
|
|
21
|
+
The account list names the accounts. The accounts carry no priority, so a
|
|
22
|
+
choice ranks them by plan and room, and the list order breaks only an exact tie.
|
|
23
|
+
The list comes from the `CODEX_ACCOUNT_PROFILES` environment variable, a comma-separated list such as
|
|
21
24
|
`alpha,beta`. When that variable is unset or empty, the roster is the saved list
|
|
22
25
|
in `account-launchers.json` under the profiles root. When neither exists, the
|
|
23
|
-
|
|
26
|
+
roster is empty. The broker's `choose` and `check` then read the default Codex home
|
|
27
|
+
as the account `default`, and `install` has no accounts. `sync` falls back to `codex-1`, `codex-2`, `codex-3` and `codex-4` when no list names an account. `choose` and `check` fall back to them only when `CODEX_ACCOUNT_PROFILES` holds only separators, such as `,`, and no saved list names an account.
|
|
24
28
|
|
|
25
29
|
Each read of the variable's list saves it to `account-launchers.json` when the
|
|
26
30
|
file holds a different list. A service, runner, or other process started
|
|
@@ -30,8 +34,8 @@ cannot be written, the read prints a warning and uses the variable's list.
|
|
|
30
34
|
The broker's `choose` and `check` commands and the setup commands use that list.
|
|
31
35
|
Each account's home is `~/.codex-profiles/<name>`, or
|
|
32
36
|
`<name>` under `CODEX_PROFILES_ROOT` when set. `~/.codex` holds the shared setup
|
|
33
|
-
and is never
|
|
34
|
-
`main`, `wait` and the Windows device names are refused.
|
|
37
|
+
and is never a roster account. With no roster, `choose` and `check` read it as the account `default` unless `CODEX_HOME` names another home. A name starts with an ASCII letter or digit, and the rest uses ASCII letters, digits, hyphens or underscores.
|
|
38
|
+
`main`, `wait` and the Windows device names are refused, in any letter case.
|
|
35
39
|
|
|
36
40
|
## Sign in once
|
|
37
41
|
|
|
@@ -99,15 +103,39 @@ list, so a process without the variable reads whichever list was saved last.
|
|
|
99
103
|
|
|
100
104
|
Room is the least percent left across an account's windows, such as the 5-hour window and the week.
|
|
101
105
|
A window that reports no length counts as weekly.
|
|
106
|
+
The broker reuses an account's reading for 60 seconds, so a reading can be up to 60 seconds old.
|
|
107
|
+
|
|
108
|
+
This table covers a choice made without `--home`. A home that a caller names with `--home` follows the `--home` paragraph after the table.
|
|
109
|
+
On a paid plan with readable meters, that home runs whatever its room, credits or floors. It takes the tier its meters allow, or `luna` when no tier allows it.
|
|
110
|
+
The rows that rank accounts by plan, room and credits do not apply to it. The rows for a free plan, an unlisted plan and a failed meter read still apply.
|
|
102
111
|
|
|
103
112
|
| Condition | Answer |
|
|
104
113
|
|---|---|
|
|
105
|
-
|
|
|
106
|
-
| No account
|
|
107
|
-
|
|
|
108
|
-
| No account over 1% | `
|
|
109
|
-
|
|
|
110
|
-
|
|
|
114
|
+
| A Pro plan account (`pro`, `prolite` and `promax`) with more than 10% left | `normal` on the Pro account with the most room, before any account on another plan |
|
|
115
|
+
| No such Pro account, and a Pro plan account with more than 0% left in each window | `luna` on the Pro account with the most room, before any account on another plan, even one with more than 10% left |
|
|
116
|
+
| No Pro plan account reaches `normal` or `luna`, and an account on another paid plan with more than 10% left | `normal` on the account with the most room |
|
|
117
|
+
| No Pro plan account reaches `normal` or `luna`, no other account over 10%, and an account on another paid plan with more than 1% of its week left and at least 20% left in any window shorter than a week | `luna` on the account with the most room |
|
|
118
|
+
| Within one plan group (the Pro plan accounts, or the accounts on another paid plan), one account reaches `normal` and another reaches only `luna` | the `normal` account, whatever the room of each |
|
|
119
|
+
| Two accounts in one plan group at the same tier with the same room | The account that comes first in the account list. The accounts carry no priority, so the list order breaks only an exact tie |
|
|
120
|
+
| An account on a free plan (`free`) | never chosen, whatever its room or credits; a `wait` reason names it |
|
|
121
|
+
| An account whose plan is missing, blank or not one of the paid plans, which are `business`, `edu`, `enterprise`, `plus`, `pro`, `prolite`, `promax` and `team` | never chosen, whatever its room or credits; a `wait` reason names it |
|
|
122
|
+
| An account with credits (`hasCredits` is `true` with a balance above zero, or `unlimited` is `true`) and 10% or less left | `normal`, even at or under 1% of its week left or under 20% of a short window; the rows above that give `luna` count only accounts without credits; a Pro plan account with credits comes before every account on another plan; among accounts of the same kind, the one with the most room, so plan usage comes before credits alone |
|
|
123
|
+
| An account on another paid plan that reports a window shorter than a week, such as the 5-hour window, with under 20% of that window left | never takes `luna` |
|
|
124
|
+
| No account can run: no Pro plan account with more than 0% left in each window, no account on another paid plan with over 10% left or with more than 1% of its week left and at least 20% left in any window shorter than a week, and no account with credits | `wait`, naming the next reset when known |
|
|
125
|
+
| A meter read finds no Codex executable, or fails with text that holds `HTTP Error 429` | The broker makes that 1 read and does not retry. A 429 text sets no rate-limit cooldown for a Codex account |
|
|
126
|
+
| A meter read fails with a `CodexMeterUnreadError`, `OSError`, `ValueError`, `RuntimeError` or `subprocess.SubprocessError` that the row above does not cover | The broker reads it again, up to 3 reads, waiting 1 second and then 2 seconds |
|
|
127
|
+
| A meter read raises any other exception type | The broker does not catch it, so the command ends with that exception after 1 read |
|
|
128
|
+
| A meter is unread after every read | The account has `meters: null` and the failure text in `unread_reason`; a `wait` reason names the account and that text. An unread account is not judged by plan |
|
|
129
|
+
|
|
130
|
+
A caller that needs the `normal` tier passes `--require-tier normal`. The broker then chooses a Pro plan account only when it reaches `normal`, and otherwise the account on another paid plan with the most room that does. A caller that passes no tier takes a Pro plan account first, even on `luna`, before an account on another plan with more room.
|
|
131
|
+
|
|
132
|
+
With no roster configured, `choose` and `check` read the default Codex home, `CODEX_HOME` or `~/.codex`, as the account `default` and apply the same rules. A `CODEX_HOME` that is empty or only whitespace counts as unset. A failed read gives `wait` and exit 3, and the reason names the failure.
|
|
133
|
+
|
|
134
|
+
`--home <path>` judges that Codex home alone. A home on a paid plan with readable meters runs, whatever its room, with or without credits, and whatever `CODEX_WEEKLY_FLOOR_DISABLED` says. It reports the tier its meters allow, or `luna` when no tier allows it. A free, missing, blank, unknown or unlisted plan, or a home whose meters are unread, still gives `wait`. `--require-tier normal` still applies, so a home that does not reach `normal` gives `wait`. `check --home` answers as `choose --home` does. A spent mark saved for the roster account that has this home, by `run` or by `choose --spent`, still gives `wait` until its reset on a paid plan, unless that account has spendable credits. A mark is keyed by product, account name and home, and `--home` reads a home the roster does not list as an account named for its folder. So a mark saved for the no-roster default account, named `default`, does not hold `--home <that home>` unless the folder of that home is also named `default`, and a mark saved for an account outside the roster never holds a `--home` answer. After an account leaves the roster, a mark saved while it was in the roster still holds `--home <its home>` only when the account's name equals the name of its resolved home folder and the account has no spendable credits. A roster account `Alpha` whose home folder is `alpha`, or whose home folder is a junction to a folder with another name, stops holding `--home <its home>` once it leaves the roster. The broker refuses `--home` for the Claude product and with `--spent`.
|
|
135
|
+
|
|
136
|
+
A spent mark for an account outside the roster holds every answer made without `--home`. `choose --spent <name>[:reset]` saves it for a name the roster does not list, and `choose`, `check` and `run` then give `wait` until its reset, even when a roster account has room. The reason reads `account <name> outside the roster is spent; next reset at <time>`. With several such marks, the soonest reset counts. When the roster already answers `wait`, the earlier of the two resets is the one the answer reports. A mark with no reset lasts one hour.
|
|
137
|
+
|
|
138
|
+
The name `default` is the exception beside a roster that lists no account named `default`. There, `default` is not an account, because the default home is read only when no roster is configured. `choose --spent default` then saves nothing and prints a warning on standard error, and a stored `default` mark does not make `choose`, `check` or `run` wait.
|
|
111
139
|
|
|
112
140
|
```
|
|
113
141
|
python packages/claude-dev-env/scripts/account_broker.py choose --product codex
|
|
@@ -129,16 +157,29 @@ python packages/claude-dev-env/scripts/account_broker.py check --product codex
|
|
|
129
157
|
has room. The job stops on 3. `choose` also exits 3 for `wait` and still prints
|
|
130
158
|
the JSON answer.
|
|
131
159
|
|
|
160
|
+
Set `CODEX_WEEKLY_FLOOR_DISABLED` to lift the 1% weekly stop for an account on a paid plan other than a Pro plan. The values that turn it on are `1`, `on`, `true` and `yes`. While it is on, such an account without credits that has 1% or less of its week left can take `luna`, and `choose` and `check` do not wait for its weekly reset. The 20% short-window floor still applies to it. The switch changes nothing for a Pro plan account. Without credits, a Pro plan account takes `luna` with more than 0% left in each window and waits at 0% in either window, whether the switch is on or off. An account with credits already runs under both floors, so the switch matters only for an account on another paid plan without credits.
|
|
161
|
+
|
|
162
|
+
```
|
|
163
|
+
$env:CODEX_WEEKLY_FLOOR_DISABLED = "1"
|
|
164
|
+
```
|
|
165
|
+
|
|
132
166
|
## Shared callers
|
|
133
167
|
|
|
134
|
-
|
|
168
|
+
Three scripts under `_shared` and the review evaluation run `choose --product codex` by path. Each script under `_shared` finds the
|
|
135
169
|
broker at `scripts/account_broker.py` in the directory that holds `_shared`.
|
|
136
|
-
Once installed, that is `~/.claude/scripts/account_broker.py`.
|
|
170
|
+
Once installed, that is `~/.claude/scripts/account_broker.py`. The evaluation looks for
|
|
171
|
+
`scripts/account_broker.py` in the package that holds `.agents`, and then for the same file name under that package's `.claude/scripts` folder.
|
|
137
172
|
|
|
138
173
|
| Caller | What it does with the answer |
|
|
139
174
|
|---|---|
|
|
140
175
|
| `_shared/pr-loop/scripts/check_convergence.py` | Requires a Codex clean stamp on HEAD only on `normal`. `luna`, `wait`, or a failed broker skips the Codex gate |
|
|
141
|
-
| `_shared/advisor/scripts/codex_astra_advisor.py` |
|
|
176
|
+
| `_shared/advisor/scripts/codex_astra_advisor.py` | Calls `run_astra_preflight` in `_shared/advisor/scripts/codex_astra_preflight.py`, which runs the broker and judges its answer. With `CODEX_HOME` unset or blank, the preflight accepts only `normal`, and the advisor runs Codex with `CODEX_HOME` set to `decision.home`. With a non-blank `CODEX_HOME` set, the preflight asks the broker to judge that home and accepts `normal` or `luna`, which the broker answers for a paid plan whatever its room, and the advisor binds on that home. A `wait` answer or a tier it does not accept returns a `declined` fallback with the broker's reason and starts no Codex process. A broker that times out, cannot start, exits with a code other than 0 or 3, prints malformed JSON, or answers `normal` or `luna` with no home or no meters returns a `broken` fallback and starts no Codex process |
|
|
177
|
+
| `_shared/pr-loop/scripts/run_codex_review.py` | Runs the review with `CODEX_HOME` set to `decision.home`. With `CODEX_HOME` unset or blank, it accepts only `normal`. With a non-blank `CODEX_HOME`, it asks the broker to judge that home and accepts `normal` or `luna`, and the review runs on `decision.home`, the trimmed absolute folder the broker judged. `wait`, a tier it does not accept, or a failed broker returns `codex_down`, so the gate fails closed. A failed broker is one that does not answer, exits with a code other than 0 or 3, prints an answer that is not JSON or holds no `decision` object, or answers with no home. A broker that does not answer covers a timeout (exit code 124), a missing interpreter binary (127), and any other `OSError` from the spawn, such as `PermissionError` (126). Any other `OSError` at spawn returns 126 for a Codex probe, the broker or the review process, and on Windows that includes a removed working directory (`NotADirectoryError`), which only the review process can hit because the probes and the broker run with no working directory. A missing `account_broker.py` makes Python exit 2, and the outcome carries 2. Exit 69 covers a malformed broker answer, a wait, a refused tier, and an answer that names no home. Output that is not UTF-8 is decoded with replacement characters and checked like any other output. The `agent_message` text is `no Codex account has room for a review (<the broker's reason>)` for `wait` and a refused tier. Any other failure gives the script's own text, such as `account broker exit 2`, `account broker answer is malformed`, `account broker answer names no Codex home` or `account broker did not answer: exit 124`. A spawn error gives `account broker did not answer: exit 126` |
|
|
178
|
+
| `.agents/skills/build-eval/evals/review/review_eval_support/account.py` | Runs each live `codex exec` with `CODEX_HOME` set to `decision.home`. With `CODEX_HOME` unset or blank, it accepts only `normal`. With a non-blank `CODEX_HOME`, it asks the broker to judge that home and accepts `normal` or `luna`, and the run uses `decision.home`, the trimmed absolute folder the broker judged. `wait`, a tier it does not accept, or a failed broker records `infra_error` with the failure `no_codex_account` and starts no model call |
|
|
179
|
+
|
|
180
|
+
`run_codex_review.py`, the evaluation and `codex_astra_advisor.py` keep the account a non-blank `CODEX_HOME` names, but ask the broker to judge that home first with `choose --product codex --home <path>`, which the advisor runs through `codex_astra_preflight.py`. The home runs whether or not the roster lists it, whatever its room, at the tier the broker answers, `normal` or `luna`. A free plan, a missing, blank, unknown or unlisted plan, a `wait`, an unreadable home, or a failed broker gives `codex_down`, `infra_error`, or for the Astra advisor a fallback reply, with no model call. The Astra fallback is `declined` with the broker's reason when the broker answered `wait` or a tier the advisor does not accept, and `broken` when the broker failed to answer or its answer is unusable. `run_codex_review.py`, the evaluation and `codex_astra_advisor.py` launch Codex on `decision.home`, the trimmed absolute folder the broker judged, so whitespace around the exported value never reaches Codex.
|
|
181
|
+
|
|
182
|
+
A Pro plan account without credits takes `luna` for a caller that names no tier when its room is more than 0% and at most 10%. Each caller above passes `--require-tier normal` when it chooses among accounts, so the broker gives it the best account that reaches `normal`, or `wait`. A caller that judges a `CODEX_HOME` already set passes `--home` and no tier, so the broker answers `normal` or `luna` for a paid home with readable meters.
|
|
142
183
|
|
|
143
184
|
## Trimmed Sol prompt
|
|
144
185
|
|
|
@@ -2,6 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
Full text behind [`rules/question-presentation.md`](../../rules/question-presentation.md).
|
|
4
4
|
|
|
5
|
+
## A question that stays open
|
|
6
|
+
|
|
7
|
+
The user may see only the question dialog or the closing line of a reply. Each time a question stays open, send it through the question tool again, with the context inside the question text and each option's effect in its description. A closing line that repeats the question reaches the user with no brief. The `final_reply_gate.py` Stop hook blocks a reply whose last paragraph ends with a question mark, or says a question still stands, when the turn sent no question tool call.
|
|
8
|
+
|
|
5
9
|
## Codex visual comparisons
|
|
6
10
|
|
|
7
11
|
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.
|
|
@@ -61,4 +61,4 @@ the week. An account whose meter could not be read has `meters` of `null`, and
|
|
|
61
61
|
its `unread_reason` holds the failure text when the reader raised one. A window
|
|
62
62
|
with no data has a `null` percent inside a read `meters` object. A wait decision has
|
|
63
63
|
`action: "wait"` and a `resets_at` timestamp. The broker exits with code 3 on
|
|
64
|
-
wait. The worker writes the same reset time to its report.
|
|
64
|
+
wait, and with code 4 when every account is unusable. The worker writes the same reset time to its report.
|
|
@@ -16,6 +16,17 @@ a path outside code whose backslash the terminal drops, such as
|
|
|
16
16
|
``D:\\Reports\\.claude``. A block sends
|
|
17
17
|
the reason back so the model rewrites the reply. Claude Code ends the turn
|
|
18
18
|
after eight blocks in a row.
|
|
19
|
+
|
|
20
|
+
It also blocks a reply whose last paragraph ends with a question mark, or says a question still stands, when the
|
|
21
|
+
turn sent no AskUserQuestion, hearthbot decision card, or Codex
|
|
22
|
+
request_user_input call. Fences, HTML blocks, quoted paragraphs, and code spans
|
|
23
|
+
are left out first, and the check is skipped when the transcript cannot be read::
|
|
24
|
+
|
|
25
|
+
flag: My question still stands. Keep it merged, or revert it? (no question tool this turn)
|
|
26
|
+
flag: My question on the revert still stands. (no question tool this turn)
|
|
27
|
+
ok: the same reply after an AskUserQuestion call in this turn
|
|
28
|
+
ok: > Keep it or revert it? (a quote)
|
|
29
|
+
ok: Both branches are rebuilt.
|
|
19
30
|
"""
|
|
20
31
|
|
|
21
32
|
from __future__ import annotations
|
|
@@ -38,6 +49,7 @@ from reply_length_gate import (
|
|
|
38
49
|
unseen_citation_violation,
|
|
39
50
|
unvalidated_claim_violation,
|
|
40
51
|
)
|
|
52
|
+
from open_tasks_transcript import replayed_transcript
|
|
41
53
|
from hooks_constants.hook_block_logger import log_hook_block
|
|
42
54
|
from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
|
|
43
55
|
from hooks_constants.final_reply_gate_constants import (
|
|
@@ -65,11 +77,16 @@ from hooks_constants.final_reply_gate_constants import (
|
|
|
65
77
|
MASKED_CODE_TEXT,
|
|
66
78
|
NON_SPACE_TOKEN_PATTERN,
|
|
67
79
|
PARAGRAPH_SEPARATOR,
|
|
80
|
+
QUESTION_MARK,
|
|
68
81
|
QUOTE_MARKER,
|
|
69
82
|
QUOTE_MARKER_PATTERN,
|
|
83
|
+
QUOTED_LINE_PATTERN,
|
|
70
84
|
REASON_KEY,
|
|
71
85
|
REWRITE_INSTRUCTION,
|
|
86
|
+
STANDING_QUESTION_PATTERN,
|
|
87
|
+
TRAILING_MARKUP_CHARACTERS,
|
|
72
88
|
TRANSCRIPT_PATH_KEY,
|
|
89
|
+
UNBRIEFED_QUESTION_MESSAGE,
|
|
73
90
|
WINDOWS_PATH_MESSAGE,
|
|
74
91
|
)
|
|
75
92
|
|
|
@@ -216,6 +233,40 @@ def windows_path_violation(reply_text: str) -> str | None:
|
|
|
216
233
|
return None
|
|
217
234
|
|
|
218
235
|
|
|
236
|
+
def closing_paragraph(reply_text: str) -> str:
|
|
237
|
+
"""Return the last prose paragraph, with fences, HTML blocks, quoted paragraphs, and code spans left out."""
|
|
238
|
+
line_feed_text = reply_text.replace(CARRIAGE_RETURN_LINE_BREAK, LINE_BREAK)
|
|
239
|
+
unfenced_text = blocks_masked(line_feed_text, FENCE_OPENER_PATTERN, _fence_closer_for)
|
|
240
|
+
unfenced_text = blocks_masked(unfenced_text, HTML_BLOCK_OPENER_PATTERN, _html_block_closer_for)
|
|
241
|
+
unquoted_text = QUOTED_LINE_PATTERN.sub("", unfenced_text)
|
|
242
|
+
all_prose_paragraphs = [
|
|
243
|
+
code_spans_masked(each_paragraph).strip()
|
|
244
|
+
for each_paragraph in BLOCK_BOUNDARY_PATTERN.split(unquoted_text)
|
|
245
|
+
if each_paragraph.strip()
|
|
246
|
+
]
|
|
247
|
+
return all_prose_paragraphs[-1] if all_prose_paragraphs else ""
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
def ends_on_question(reply_text: str) -> bool:
|
|
251
|
+
"""Return True when the closing paragraph ends with a question mark or says a question still stands."""
|
|
252
|
+
paragraph_text = closing_paragraph(reply_text)
|
|
253
|
+
return (
|
|
254
|
+
paragraph_text.rstrip(TRAILING_MARKUP_CHARACTERS).endswith(QUESTION_MARK)
|
|
255
|
+
or STANDING_QUESTION_PATTERN.search(paragraph_text) is not None
|
|
256
|
+
)
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
def unbriefed_question_violation(reply_text: str, transcript_path: object) -> str | None:
|
|
260
|
+
"""Return the block reason for a closing question no question tool sent this turn, or None."""
|
|
261
|
+
if not isinstance(transcript_path, str) or not Path(transcript_path).is_file():
|
|
262
|
+
return None
|
|
263
|
+
if not ends_on_question(reply_text):
|
|
264
|
+
return None
|
|
265
|
+
if replayed_transcript(transcript_path).has_turn_question_tool:
|
|
266
|
+
return None
|
|
267
|
+
return UNBRIEFED_QUESTION_MESSAGE
|
|
268
|
+
|
|
269
|
+
|
|
219
270
|
def final_reply_violation(reply_text: str, transcript_path: object) -> str | None:
|
|
220
271
|
"""Return the block reason for the closing reply, or None when it passes."""
|
|
221
272
|
return (
|
|
@@ -233,10 +284,15 @@ def main() -> int:
|
|
|
233
284
|
reply_text = hook_input.get(LAST_ASSISTANT_MESSAGE_KEY)
|
|
234
285
|
if not isinstance(reply_text, str):
|
|
235
286
|
return ALLOW_EXIT_CODE
|
|
236
|
-
|
|
237
|
-
|
|
287
|
+
transcript_path = hook_input.get(TRANSCRIPT_PATH_KEY)
|
|
288
|
+
violation = final_reply_violation(reply_text, transcript_path)
|
|
289
|
+
block_reason = (
|
|
290
|
+
violation + REWRITE_INSTRUCTION
|
|
291
|
+
if violation is not None
|
|
292
|
+
else unbriefed_question_violation(reply_text, transcript_path)
|
|
293
|
+
)
|
|
294
|
+
if block_reason is None:
|
|
238
295
|
return ALLOW_EXIT_CODE
|
|
239
|
-
block_reason = violation + REWRITE_INSTRUCTION
|
|
240
296
|
log_hook_block(
|
|
241
297
|
Path(__file__).name, HOOK_EVENT_NAME, block_reason, offending_input_preview=reply_text
|
|
242
298
|
)
|
|
@@ -24,6 +24,8 @@ The replay also notes what the current turn did::
|
|
|
24
24
|
has_turn_work_tool any other assistant tool call ran, except the title tool,
|
|
25
25
|
AskUserQuestion, a hearthbot decision card, ToolSearch,
|
|
26
26
|
TaskList, TaskGet, and the Codex request_user_input card
|
|
27
|
+
has_turn_question_tool an AskUserQuestion, hearthbot decision card, or Codex
|
|
28
|
+
request_user_input call ran
|
|
27
29
|
|
|
28
30
|
A turn starts at the last user prompt record. A tool result, a record flagged
|
|
29
31
|
``isMeta``, ``isSidechain`` or ``isCompactSummary``, and a ``Stop hook feedback``
|
|
@@ -52,6 +54,7 @@ from hooks_constants.open_tasks_stop_gate_constants import (
|
|
|
52
54
|
ASSISTANT_RECORD_TYPE,
|
|
53
55
|
ALL_CODEX_TOOL_CALL_TYPES,
|
|
54
56
|
ALL_NON_WORK_TOOL_NAMES,
|
|
57
|
+
ALL_QUESTION_TOOL_NAMES,
|
|
55
58
|
ALL_TRACKER_TOOL_NAMES,
|
|
56
59
|
ASSISTANT_ROLE,
|
|
57
60
|
CCD_PLAN_ADVANCE_KEY,
|
|
@@ -224,6 +227,14 @@ def is_codex_work_call(all_record_fields: dict[str, object]) -> bool:
|
|
|
224
227
|
return tool_name != CODEX_PLAN_TOOL_NAME and is_work_tool_name(tool_name)
|
|
225
228
|
|
|
226
229
|
|
|
230
|
+
def is_codex_question_call(all_record_fields: dict[str, object]) -> bool:
|
|
231
|
+
"""Return True for a Codex tool call record that sends a question card."""
|
|
232
|
+
payload_body = _codex_payload(all_record_fields)
|
|
233
|
+
if payload_body is None or payload_body.get(RECORD_TYPE_KEY) not in ALL_CODEX_TOOL_CALL_TYPES:
|
|
234
|
+
return False
|
|
235
|
+
return payload_body.get(TOOL_NAME_KEY) in ALL_QUESTION_TOOL_NAMES
|
|
236
|
+
|
|
237
|
+
|
|
227
238
|
def is_work_tool_name(tool_name: object) -> bool:
|
|
228
239
|
"""Return True for a tool name other than a non-work tool or the session title tool."""
|
|
229
240
|
return not (
|
|
@@ -332,11 +343,13 @@ class TranscriptReplay:
|
|
|
332
343
|
self.turn_prompt_text = ""
|
|
333
344
|
self.has_turn_tracker_write = False
|
|
334
345
|
self.has_turn_work_tool = False
|
|
346
|
+
self.has_turn_question_tool = False
|
|
335
347
|
|
|
336
348
|
def start_turn(self, prompt_text: str) -> None:
|
|
337
349
|
self.turn_prompt_text = prompt_text
|
|
338
350
|
self.has_turn_tracker_write = False
|
|
339
351
|
self.has_turn_work_tool = False
|
|
352
|
+
self.has_turn_question_tool = False
|
|
340
353
|
|
|
341
354
|
def apply_record(self, all_record_fields: dict[str, object]) -> None:
|
|
342
355
|
prompt_text = codex_prompt_text(all_record_fields)
|
|
@@ -350,6 +363,9 @@ class TranscriptReplay:
|
|
|
350
363
|
self.latest_items = plan_items
|
|
351
364
|
self.has_turn_tracker_write = True
|
|
352
365
|
return
|
|
366
|
+
if is_codex_question_call(all_record_fields):
|
|
367
|
+
self.has_turn_question_tool = True
|
|
368
|
+
return
|
|
353
369
|
if is_codex_work_call(all_record_fields):
|
|
354
370
|
self.has_turn_work_tool = True
|
|
355
371
|
return
|
|
@@ -406,6 +422,8 @@ class TranscriptReplay:
|
|
|
406
422
|
self.apply_tool_result(all_block_fields)
|
|
407
423
|
|
|
408
424
|
def note_turn_tool(self, tool_name: str) -> None:
|
|
425
|
+
if tool_name in ALL_QUESTION_TOOL_NAMES:
|
|
426
|
+
self.has_turn_question_tool = True
|
|
409
427
|
if tool_name in ALL_TRACKER_TOOL_NAMES:
|
|
410
428
|
self.has_turn_tracker_write = True
|
|
411
429
|
elif is_work_tool_name(tool_name):
|
|
@@ -239,3 +239,163 @@ def test_should_mask_code_spans_the_way_commonmark_pairs_them(
|
|
|
239
239
|
paragraph_text: str, masked_text: str
|
|
240
240
|
) -> None:
|
|
241
241
|
assert final_reply_gate.code_spans_masked(paragraph_text) == masked_text
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
BARE_QUESTION_REPLY = (
|
|
245
|
+
"PR 8093 merged into the branch of PR 8007 by mistake.\n\n"
|
|
246
|
+
"My question on PR 8093 still stands. Keep it merged into the branch of PR 8007, or revert it?"
|
|
247
|
+
)
|
|
248
|
+
STANDING_QUESTION_REPLY = "Checks are green.\n\nMy question on the revert still stands."
|
|
249
|
+
REPORT_ONLY_REPLY = "Both branches are rebuilt.\n\nThe tests pass on each."
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
def prompt_record(prompt_text: str) -> dict[str, object]:
|
|
253
|
+
return {"type": "user", "message": {"role": "user", "content": prompt_text}}
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
def assistant_tool_record(tool_name: str, tool_input: dict[str, object]) -> dict[str, object]:
|
|
257
|
+
tool_use = {"type": "tool_use", "id": "q1", "name": tool_name, "input": tool_input}
|
|
258
|
+
return {"type": "assistant", "message": {"role": "assistant", "content": [tool_use]}}
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
def assistant_text_record(reply_text: str) -> dict[str, object]:
|
|
262
|
+
text_block = {"type": "text", "text": reply_text}
|
|
263
|
+
return {"type": "assistant", "message": {"role": "assistant", "content": [text_block]}}
|
|
264
|
+
|
|
265
|
+
|
|
266
|
+
def stop_feedback_record() -> dict[str, object]:
|
|
267
|
+
feedback = {"role": "user", "content": "Stop hook feedback: send the question"}
|
|
268
|
+
return {"type": "user", "isMeta": True, "message": feedback}
|
|
269
|
+
|
|
270
|
+
|
|
271
|
+
def write_records(transcript_path: Path, all_records: list[dict[str, object]]) -> Path:
|
|
272
|
+
transcript_path.write_text(
|
|
273
|
+
"\n".join(json.dumps(each_record) for each_record in all_records), encoding="utf-8"
|
|
274
|
+
)
|
|
275
|
+
return transcript_path
|
|
276
|
+
|
|
277
|
+
|
|
278
|
+
ASK_INPUT: dict[str, object] = {"questions": [{"question": "Keep PR 8093 merged?", "options": []}]}
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
@pytest.mark.parametrize(
|
|
282
|
+
("reply_text", "all_turn_records"),
|
|
283
|
+
[
|
|
284
|
+
(BARE_QUESTION_REPLY, [prompt_record("what now"), assistant_text_record(BARE_QUESTION_REPLY)]),
|
|
285
|
+
(STANDING_QUESTION_REPLY, [prompt_record("status"), assistant_text_record(STANDING_QUESTION_REPLY)]),
|
|
286
|
+
(
|
|
287
|
+
BARE_QUESTION_REPLY,
|
|
288
|
+
[
|
|
289
|
+
prompt_record("first"),
|
|
290
|
+
assistant_tool_record("AskUserQuestion", ASK_INPUT),
|
|
291
|
+
prompt_record("second"),
|
|
292
|
+
assistant_text_record(BARE_QUESTION_REPLY),
|
|
293
|
+
],
|
|
294
|
+
),
|
|
295
|
+
(
|
|
296
|
+
BARE_QUESTION_REPLY,
|
|
297
|
+
[
|
|
298
|
+
prompt_record("what now"),
|
|
299
|
+
assistant_tool_record("mcp__ccd_turn__wrap_up", {"recap": "r", "ask": "Keep or revert?"}),
|
|
300
|
+
assistant_text_record(BARE_QUESTION_REPLY),
|
|
301
|
+
],
|
|
302
|
+
),
|
|
303
|
+
],
|
|
304
|
+
)
|
|
305
|
+
def test_should_block_a_closing_question_no_question_tool_sent(
|
|
306
|
+
monkeypatch: pytest.MonkeyPatch,
|
|
307
|
+
capsys: pytest.CaptureFixture[str],
|
|
308
|
+
tmp_path: Path,
|
|
309
|
+
reply_text: str,
|
|
310
|
+
all_turn_records: list[dict[str, object]],
|
|
311
|
+
) -> None:
|
|
312
|
+
transcript_path = write_records(tmp_path / "s.jsonl", all_turn_records)
|
|
313
|
+
_, stdout_text = run_gate(monkeypatch, capsys, reply_text, transcript_path)
|
|
314
|
+
decision = json.loads(stdout_text)
|
|
315
|
+
assert decision["decision"] == "block"
|
|
316
|
+
assert "AskUserQuestion" in decision["reason"]
|
|
317
|
+
assert "Rewrite the reply without it." not in decision["reason"]
|
|
318
|
+
|
|
319
|
+
|
|
320
|
+
@pytest.mark.parametrize(
|
|
321
|
+
("reply_text", "all_turn_records"),
|
|
322
|
+
[
|
|
323
|
+
(
|
|
324
|
+
BARE_QUESTION_REPLY,
|
|
325
|
+
[
|
|
326
|
+
prompt_record("what now"),
|
|
327
|
+
assistant_tool_record("AskUserQuestion", ASK_INPUT),
|
|
328
|
+
assistant_text_record(BARE_QUESTION_REPLY),
|
|
329
|
+
],
|
|
330
|
+
),
|
|
331
|
+
(
|
|
332
|
+
BARE_QUESTION_REPLY,
|
|
333
|
+
[
|
|
334
|
+
prompt_record("what now"),
|
|
335
|
+
assistant_text_record(BARE_QUESTION_REPLY),
|
|
336
|
+
stop_feedback_record(),
|
|
337
|
+
assistant_tool_record("AskUserQuestion", ASK_INPUT),
|
|
338
|
+
assistant_text_record(BARE_QUESTION_REPLY),
|
|
339
|
+
],
|
|
340
|
+
),
|
|
341
|
+
(REPORT_ONLY_REPLY, [prompt_record("status"), assistant_text_record(REPORT_ONLY_REPLY)]),
|
|
342
|
+
(
|
|
343
|
+
"The release decision is still pending the DBA review.",
|
|
344
|
+
[prompt_record("status"), assistant_text_record("x")],
|
|
345
|
+
),
|
|
346
|
+
(
|
|
347
|
+
"Question answered: the patch still stands. The question was closed and the bug still stands.",
|
|
348
|
+
[prompt_record("status"), assistant_text_record("x")],
|
|
349
|
+
),
|
|
350
|
+
(
|
|
351
|
+
"The decision to ship still stands, and the ask to rebase still stands.",
|
|
352
|
+
[prompt_record("status"), assistant_text_record("x")],
|
|
353
|
+
),
|
|
354
|
+
(
|
|
355
|
+
"Your question about the flaky test is resolved, but the PR is still open.",
|
|
356
|
+
[prompt_record("status"), assistant_text_record("x")],
|
|
357
|
+
),
|
|
358
|
+
(
|
|
359
|
+
"The question of the build is closed and the PR is still open.",
|
|
360
|
+
[prompt_record("status"), assistant_text_record("x")],
|
|
361
|
+
),
|
|
362
|
+
(
|
|
363
|
+
"Checks pass.\n> Keep it or revert?",
|
|
364
|
+
[prompt_record("status"), assistant_text_record("x")],
|
|
365
|
+
),
|
|
366
|
+
(
|
|
367
|
+
"The question of the API is open-ended, and the decision is open source.",
|
|
368
|
+
[prompt_record("status"), assistant_text_record("x")],
|
|
369
|
+
),
|
|
370
|
+
(
|
|
371
|
+
"The log shows:\n\n```\nretry?\n```",
|
|
372
|
+
[prompt_record("status"), assistant_text_record("x")],
|
|
373
|
+
),
|
|
374
|
+
(
|
|
375
|
+
"He wrote:\n\n> Keep it or revert it?",
|
|
376
|
+
[prompt_record("status"), assistant_text_record("x")],
|
|
377
|
+
),
|
|
378
|
+
(
|
|
379
|
+
"The flag reads `--confirm?`",
|
|
380
|
+
[prompt_record("status"), assistant_text_record("x")],
|
|
381
|
+
),
|
|
382
|
+
],
|
|
383
|
+
)
|
|
384
|
+
def test_should_pass_a_reply_whose_question_went_through_the_tool_or_that_asks_nothing(
|
|
385
|
+
monkeypatch: pytest.MonkeyPatch,
|
|
386
|
+
capsys: pytest.CaptureFixture[str],
|
|
387
|
+
tmp_path: Path,
|
|
388
|
+
reply_text: str,
|
|
389
|
+
all_turn_records: list[dict[str, object]],
|
|
390
|
+
) -> None:
|
|
391
|
+
transcript_path = write_records(tmp_path / "s.jsonl", all_turn_records)
|
|
392
|
+
exit_code, stdout_text = run_gate(monkeypatch, capsys, reply_text, transcript_path)
|
|
393
|
+
assert exit_code == 0
|
|
394
|
+
assert stdout_text == ""
|
|
395
|
+
|
|
396
|
+
|
|
397
|
+
def test_should_pass_a_closing_question_when_the_transcript_cannot_be_read(
|
|
398
|
+
monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
|
|
399
|
+
) -> None:
|
|
400
|
+
_, stdout_text = run_gate(monkeypatch, capsys, BARE_QUESTION_REPLY, tmp_path / "missing.jsonl")
|
|
401
|
+
assert stdout_text == ""
|
|
@@ -5,7 +5,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
|
|
|
5
5
|
## Checks
|
|
6
6
|
|
|
7
7
|
- `blocking/reply_length_gate.py` caps chat reply length, denies a configured banned word, requires a readable link when the text names a pull request number, and denies a causal claim in a reply that cites no code span, output block, or link. It denies a sentence that guesses, estimates, hedges a duration, or admits a skipped check, such as "I didn't confirm this one." It denies a cited Actions run, pull request, or run, job, or check id that no successful tool result in the transcript shows; a subagent's report is the result of its Agent call. A question card from `AskUserQuestion` gets the banned word check and `unvalidated_claim_violation`, like a decision card. One refusal names every broken rule and every offending sentence, numbered, and ends with "Fix every item above in your next write." With visual reply mode on, it also runs the checks in `visual_reply_rules.py` from the rule list in `rules/visual-reply-rules.json`: no abbreviation or tracker number outside a link, a widget or page before a reply of more than one sentence, and no anchor link inside widget code. The mode is off by default; `~/.claude/visual-reply-mode.json` with `{"enabled": true}` turns the mode checks on. The results-picture check runs with the mode off too. A reply with a markdown table, or more than two figures, needs a picture: an attached `.svg`, `.png`, `.jpg`, `.jpeg`, `.gif`, or `.webp` file, an attached `frame` output such as a published page, or a markdown picture outside code. The check reads the attached name only, so it does not confirm that the file exists. It skips an edit of a posted message, because the edit tool attaches nothing, and the closing reply of a turn, which `blocking/final_reply_gate.py` does not run it on.
|
|
8
|
-
- `blocking/final_reply_gate.py` applies the banned words, `unvalidated_claim_violation`, and `unseen_citation_violation` from the reply gate to the reply a session ends its turn with. Its `windows_path_violation` blocks a path the terminal would render without one of its backslashes.
|
|
8
|
+
- `blocking/final_reply_gate.py` applies the banned words, `unvalidated_claim_violation`, and `unseen_citation_violation` from the reply gate to the reply a session ends its turn with. Its `windows_path_violation` blocks a path the terminal would render without one of its backslashes. Its `unbriefed_question_violation` blocks a reply whose last paragraph, with fences, quotes, and code spans left out, ends with a question mark or says a question still stands, when the turn sent no `AskUserQuestion`, hearthbot decision card, or Codex `request_user_input` call; it is skipped when the transcript cannot be read.
|
|
9
9
|
- `blocking/open_tasks_stop_gate.py` holds the end of a turn once when the prompt that started it asks for work, the turn ran a work tool, and the turn made no tracker call: TaskCreate, TaskUpdate, TodoWrite, the Codex `update_plan`, or the desktop `mcp__ccd_turn__update_plan`. A work tool is any tool but a tracker call, the session title tool, `AskUserQuestion`, a hearthbot decision card, Codex `request_user_input`, `ToolSearch`, `TaskList`, or `TaskGet`. It never reads the reply text. `open_task_asks.is_ask` decides whether a prompt asks for work: a question-only prompt, an acknowledgement such as `thanks!`, an empty prompt, a prompt of only `<system-reminder>` blocks, and an envelope such as `<agent-message>` or `<task-notification>` do not. `blocking/open_tasks_transcript.py` replays the transcript for it: the turn's prompt, its tool calls, and the task list. `session_task_items` merges the task store with the transcript items whose subject the store does not hold, for the session title gate.
|
|
10
10
|
- `session/tracking_nudge.py` adds one `additionalContext` note to a prompt that asks for work. The note asks for a task list item. When the title shows the red flag or the check mark, it also asks for the hourglass before other work. It never blocks.
|
|
11
11
|
- The claim judge is a `prompt` hook in `hooks.json`, with no `model` set, so Claude Code's small default hook model reads each chat message and denies every claim, numbered in one refusal, about how code, a file, a tool, a service, a run, or a process behaves, or why something happened, when nothing in the message shows it: inline code that quotes output or a code line, a file and line, or a link. A pull request link covers what that change does, what it blocks or lets through, and its checks. The author's own actions, a restatement of the user's words, questions, instructions, and a decision card's option consequences pass. It catches the plain claims the causal word list in `blocking/reply_length_gate.py` misses, such as "The code lets any of them rewrite it mid-check." `continueOnBlock` returns the reason to the agent as the tool error, so it can add the source and send again. The installer owns it through the `claude-dev-env: ` prefix on its `statusMessage`. It skips `post_widget`, whose input is SVG or HTML markup.
|
|
@@ -22,7 +22,6 @@ This family stops a chat reply, edited message, or tool call when its payload br
|
|
|
22
22
|
- `blocking/verify_before_commit_gate.py` denies a `git commit` in a repository with a `.claude/skills/verify` or `.agents/skills/verify` directory until the `verify` skill loads after the last user prompt, through a Skill call whose result comes back without an error, or the `/verify` command in that prompt. It reads the committed paths from the staged diff, the tracked changes for `-a`, and the paths of each `git add` earlier in the same command, and passes a commit whose paths are all docs, images, test files, or `.json`, `.jsonl`, `.yaml`, `.yml`, or `.csv` files under a `docs` folder.
|
|
23
23
|
- `blocking/build_eval_before_eval_write_gate.py` denies a write to an eval file until a Skill call named exactly `claude-api` with args `build-eval`, or the `/claude-api build-eval` command, appears in the transcript.
|
|
24
24
|
- `blocking/merge_review_gate.py` denies an agent's merge until a review pass on the merged head reported zero findings, or ruled out every finding and linked the posted rulings. It reads the receipt `scripts/merge_review_receipt.py` writes, requires the merge, auto-merge or merge-queue entry to be pinned to that head, and skips repositories listed in `CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES`. Its deny reason names the review command `CLAUDE_MERGE_REVIEW_COMMAND` sets. The reason tells the agent to run that command for the first three passes and `/code-review low --fix <number>` for each later pass; the gate itself counts no passes. It also denies a pull request open, through `gh pr create`, `pull_request.py create` or a `create_pull_request` tool, until a pass recorded as `merge_review_receipt.py <owner/name> open <head> 0` covers the head the pull request opens with. An open pass also counts when every finding is ruled out: `merge_review_receipt.py <owner/name> open <head> <count> --ruled-out <count> --rulings <path:line,...>`, with a different `path:line` for each finding, checked against the file at that head when the pass is recorded. A merge pinned to that same head passes on the open receipt only when the pass found zero findings.
|
|
25
|
-
- `blocking/merge_over_review_offer_gate.py` denies a decision card or question that offers a merge while it names open review findings, a red check, unaddressed review comments, or an override. It reads the whole card as one text: every question, header, context, reason, and option, whether the option is a string or a label with a consequence or description.
|
|
26
25
|
- `blocking/artifact_dark_mode_gate.py` denies an Artifact page publish when the page, inside the publish wrapper, keeps a light body or shows text under 4.5:1 contrast in dark mode. `blocking/artifact_dark_mode_render.cjs` renders the page in headless Chromium for it.
|
|
27
26
|
- `blocking/send_user_file_worktree_root_gate.py` denies a `SendUserFile` call that names a file outside the session's working directory, the `cwd` in the hook payload. The desktop file pane opens a sent file only under that folder and shows "Couldn't find this file" for any other path. The reason lists each outside file and names `<cwd>\.scratch\` as the folder to copy it into.
|
|
28
27
|
- `blocking/turn_review_gate.py` holds the end of a turn when a fresh `claude -p "/code-review low <base>..<turn>"` run finds a problem in that turn's edits. At the prompt it snapshots each opted-in checkout into a commit built from a copy of the index after `git add -A`; at the stop it snapshots again with the first snapshot as parent, so the range holds only the turn's edits, untracked files included. A checkout takes part when it is `CLAUDE_PROJECT_DIR` or a folder directly inside it and its GitHub origin `owner/repo` slug is listed in `CLAUDE_TURN_REVIEW_REPOSITORIES`, comma-separated. A finding is an entry in the review's last non-empty JSON array of objects with a `file` key, where `file` is a changed path and `line` is a number. An empty `[]` counts as no array. A review with no such array has a finding on each line that opens with a changed path, a colon and a line number, after an optional list marker, backtick or emphasis mark. A review that opens with `(none)` has none. A saved baseline that is not a 40- or 64-character commit name is dropped, and that stop takes a fresh baseline. Each stop moves the baseline to its snapshot, so the stop after a block reviews only the fix. It holds a stop at most 3 times in a row until the next prompt, skips a turn that changed more than 30 files, and lets the stop through when the review fails. The reviews of one stop share 240 seconds, and a checkout reached with less than a second left goes unreviewed. The review run gets `--setting-sources ""`, `--tools Read,Grep,Glob,Bash`, `--no-session-persistence`, `--permission-mode dontAsk`, read tools plus `git diff`, `git show` and `git log` in the checkout, a deny list for git's `-c`, `--config-env`, `--output`, `--ext-diff`, `--textconv`, `--git-dir`, `--work-tree` and `--exec-path` options, `--settings '{"disableAllHooks": true}'` so no other hook steers the review, `CLAUDE_TURN_REVIEW_CHILD=1`, and none of the parent session's id, messaging or ingress variables; the gate does nothing inside such a run.
|
|
@@ -47,7 +46,6 @@ This family stops a chat reply, edited message, or tool call when its payload br
|
|
|
47
46
|
- `blocking/verify_before_commit_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell`, timeout `30` seconds in `hooks.json`.
|
|
48
47
|
- `blocking/build_eval_before_eval_write_gate.py` runs on `PreToolUse`, matcher `Write|Edit|MultiEdit|NotebookEdit|apply_patch`, timeout `10` seconds in `hooks.json`.
|
|
49
48
|
- `blocking/merge_review_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge)`, timeout `30` seconds in `hooks.json`. A `create_pull_request` call reads its head branch from GitHub with `git ls-remote` over https, so the working folder does not matter. The lookup runs in an empty folder, so no checkout's git config applies, takes no terminal prompt, and gets 5 seconds. A fork head `user:branch` reads the repository of `user`. A branch GitHub does not list, or a lookup that fails, resolves in the working folder as a shell open does, as `origin/<branch>` first. The timeout covers the lookup beside those local git calls.
|
|
50
|
-
- `blocking/merge_over_review_offer_gate.py` runs on `PreToolUse`, matcher `AskUserQuestion|mcp__.*__ask_decision`, timeout `10` seconds in `hooks.json`.
|
|
51
49
|
- `blocking/artifact_dark_mode_gate.py` runs on `PreToolUse`, matcher `Artifact`, timeout `60` seconds in `hooks.json`.
|
|
52
50
|
- `blocking/send_user_file_worktree_root_gate.py` runs on `PreToolUse`, matcher `SendUserFile`, timeout `10` seconds in `hooks.json`.
|
|
53
51
|
- `blocking/turn_review_gate.py` runs on `UserPromptSubmit`, matcher empty, timeout `30` seconds, and on `Stop`, timeout `300` seconds, in `hooks.json`. The review itself times out after 240 seconds.
|
|
@@ -76,7 +74,6 @@ Preconditions:
|
|
|
76
74
|
- **Verify before commit.** Input is `git add app.py; git commit -m change` in a temporary repository with `.agents/skills/verify`, and a transcript with no `verify` load after its last prompt. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_commit_gate.py -q`. The adjacent test observes a denial, then a silent allow after a `verify` Skill call or a `/verify` prompt. A load before the last prompt still denies. A docs-only commit, a commit of data files under a `docs` folder, a tests-only commit, and a repository with no verify skill pass. A `.py` file under `docs` and a `.json` file outside `docs` still deny.
|
|
77
75
|
- **Eval write.** Input is a Write to `evals/cases.json` with no build-eval call in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_build_eval_before_eval_write_gate.py -q`. The adjacent test observes a denial, then an allow once the call appears; a write outside an eval path passes.
|
|
78
76
|
- **Clean review.** Input is a merge with no receipt, a receipt with findings, a merge pinned to a newer head, an unpinned merge, or auto-merge with no head. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_merge_review_gate.py -q`. The adjacent test observes a denial for each; a merge or auto-merge pinned to the clean head and a merge in an exempt repository pass. An open with no clean open receipt at its head is denied; an open reviewed clean at its head, and a merge pinned to that head, pass. An open pass whose every finding has its own `path:line` ruling lets the open through; a merge pinned to that head is denied, since only a zero-finding open pass carries to the merge. An open whose branch neither GitHub nor the working folder holds is denied as unreadable.
|
|
79
|
-
- **Merge offer.** Input is a decision card or AskUserQuestion that offers "Merge now", the merge queue, or a yes to "Merge it now?" while any part of the card names open findings or unaddressed review comments. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_merge_over_review_offer_gate.py -q`. The adjacent test observes a denial for each, including an offer and findings in separate questions; a card with no merge offer, a card about the merge review check itself, a card about shipping a docs change, and a merge offer after a clean review pass.
|
|
80
77
|
- **Dark mode page.** Input is an Artifact publish of a page that themes `html` but leaves `body` to the publish wrapper. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_artifact_dark_mode_gate.py -q`. The adjacent test observes a denial that names the text and its contrast; a page that themes `body` passes. The render tests skip on a host with no Node Playwright and Chromium.
|
|
81
78
|
- **Sent file root.** Input is a `SendUserFile` call for a file on `Y:\` or in the session scratchpad, with `cwd` set to a worktree. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_send_user_file_worktree_root_gate.py -q`. The adjacent test observes a denial that names the file and `<cwd>\.scratch\`; a file under `<cwd>\.scratch\` passes.
|
|
82
79
|
- **Turn review.** Input is a temporary checkout with an opted-in origin, a `UserPromptSubmit`, an edit that drops a decorator, and a `Stop`, with a stub `claude` on PATH that prints a finding. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_turn_review_gate.py -q`. The adjacent test observes a `block` decision with the finding, a review range whose diff holds only the edited file, and a review environment with no parent session id. A `(none)` review, an unchanged turn, a failed review, an unlisted repository, a 31-file turn, and a fourth stop in a row pass.
|
package/hooks/hooks.json
CHANGED
|
@@ -204,16 +204,6 @@
|
|
|
204
204
|
}
|
|
205
205
|
]
|
|
206
206
|
},
|
|
207
|
-
{
|
|
208
|
-
"matcher": "AskUserQuestion|mcp__.*__ask_decision",
|
|
209
|
-
"hooks": [
|
|
210
|
-
{
|
|
211
|
-
"type": "command",
|
|
212
|
-
"command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/merge_over_review_offer_gate.py",
|
|
213
|
-
"timeout": 10
|
|
214
|
-
}
|
|
215
|
-
]
|
|
216
|
-
},
|
|
217
207
|
{
|
|
218
208
|
"matcher": "mcp__.*__(add_issue_comment|issue_write|update_issue_comment)",
|
|
219
209
|
"hooks": [
|
|
@@ -64,3 +64,19 @@ WINDOWS_PATH_MESSAGE = (
|
|
|
64
64
|
" markdown and drops a backslash before punctuation, so a copied path"
|
|
65
65
|
" points nowhere. Wrap the path in backticks."
|
|
66
66
|
)
|
|
67
|
+
QUOTED_LINE_PATTERN = re.compile(r"^ {0,3}>[^\n]*$", re.MULTILINE)
|
|
68
|
+
TRAILING_MARKUP_CHARACTERS = "*_)]\"'\u201d\u2019 \t\n"
|
|
69
|
+
QUESTION_MARK = "?"
|
|
70
|
+
STANDING_QUESTION_PATTERN = re.compile(
|
|
71
|
+
r"\bquestion(?:\s+(?:on|about|for|of)(?:\s+[^\s.!?,;:]+){1,3})?\s+still\s+stands\b",
|
|
72
|
+
re.IGNORECASE,
|
|
73
|
+
)
|
|
74
|
+
UNBRIEFED_QUESTION_MESSAGE = (
|
|
75
|
+
"The reply ends on a question to the user, and this turn sent no question"
|
|
76
|
+
" through the native question tool. The user may see only the closing line,"
|
|
77
|
+
" so a question at the end of a reply reaches the user with no brief. Send it"
|
|
78
|
+
" through AskUserQuestion (Codex: request_user_input): put the context the"
|
|
79
|
+
" user needs inside the question text, give two or three options, and put"
|
|
80
|
+
" each option's effect in its description. A repeated open question goes"
|
|
81
|
+
" through the tool again with its brief. Then end the reply without the question."
|
|
82
|
+
)
|
|
@@ -100,6 +100,15 @@ ALL_NON_WORK_TOOL_NAMES = frozenset(
|
|
|
100
100
|
"request_user_input_async",
|
|
101
101
|
}
|
|
102
102
|
)
|
|
103
|
+
ALL_QUESTION_TOOL_NAMES = frozenset(
|
|
104
|
+
{
|
|
105
|
+
"AskUserQuestion",
|
|
106
|
+
"mcp__hearthbot__ask_decision",
|
|
107
|
+
"mcp__hearthbot__request_decision",
|
|
108
|
+
"request_user_input",
|
|
109
|
+
"request_user_input_async",
|
|
110
|
+
}
|
|
111
|
+
)
|
|
103
112
|
SESSION_TITLE_TOOL_SUFFIX = "__set_session_title"
|
|
104
113
|
ALL_CODEX_TOOL_CALL_TYPES = frozenset({CODEX_FUNCTION_CALL_TYPE, "custom_tool_call", "local_shell_call"})
|
|
105
114
|
BLOCK_REASON = (
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Present questions clearly
|
|
2
2
|
|
|
3
|
-
Before
|
|
3
|
+
Before every ask, repeats included, give a short formatted chat brief with context and each choice's effect. Add helpful visuals or artifacts.
|
|
4
4
|
|
|
5
5
|
Ask one short, self-contained question with two or three choices. Give each a short label and one short sentence. Reuse labels in the brief, comparison, and picker.
|
|
6
6
|
|