claude-dev-env 8.114.0 → 8.114.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.
@@ -54,6 +54,16 @@ const LEGACY_MANAGED_DENY_ENTRIES = [
54
54
  'MultiEdit($HOME/.claude/code-review-stamps/**)',
55
55
  ];
56
56
  const USER_OWNED_DENY_ENTRY = 'Bash(rm -rf /)';
57
+ const REMINDER_OFF_ENV = {
58
+ CLAUDE_CODE_TODO_REMINDER_MODE: 'off',
59
+ CLAUDE_CODE_SILENT_TURN_REMINDER: '0',
60
+ CLAUDE_CODE_SILENT_TURN_REMINDER_TURNS: '100000',
61
+ };
62
+ const PACKAGE_ENV_DEFAULTS = {
63
+ CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS: '100000',
64
+ PYTHONUTF8: '1',
65
+ ...REMINDER_OFF_ENV,
66
+ };
57
67
 
58
68
  function packageManagedPermissions() {
59
69
  const packageSettings = JSON.parse(readFileSync(PACKAGE_SETTINGS_PATH, 'utf8'));
@@ -275,7 +285,7 @@ test('sandbox uninstall removes only package-owned permission entries and keeps
275
285
  }
276
286
  });
277
287
 
278
- test('package settings.json publishes the session agent, advisor model, auto-compact, auto mode, idle compaction and Python UTF-8 defaults', () => {
288
+ test('package settings.json publishes the session agent, advisor model, auto-compact, auto mode, idle compaction, Python UTF-8 and reminder-off defaults', () => {
279
289
  const packageSettings = JSON.parse(readFileSync(PACKAGE_SETTINGS_PATH, 'utf8'));
280
290
  const settingsDefaults = settingsDefaultsFromPackageSettings(packageSettings);
281
291
  assert.deepEqual(
@@ -283,7 +293,7 @@ test('package settings.json publishes the session agent, advisor model, auto-com
283
293
  ['advisorModel', 'agent', 'autoCompactWindow', 'autoMode', 'env', 'modelSettings'],
284
294
  );
285
295
  assert.equal(settingsDefaults.autoCompactWindow, 350000);
286
- assert.deepEqual(settingsDefaults.env, { CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS: '100000', PYTHONUTF8: '1' });
296
+ assert.deepEqual(settingsDefaults.env, PACKAGE_ENV_DEFAULTS);
287
297
  assert.deepEqual(settingsDefaults.modelSettings, {
288
298
  'claude-haiku-5-5': { autoCompactWindow: 250000 },
289
299
  'claude-haiku-4-5': { autoCompactWindow: 250000 },
@@ -314,7 +324,7 @@ test('a missing default is added and a user-set value is kept', () => {
314
324
  assert.equal(userSettings.advisorModel, 'sonnet');
315
325
  });
316
326
 
317
- test('install adds the idle compaction and Python UTF-8 variables to an env block and keeps a user value on rerun', () => {
327
+ test('install adds the idle compaction, Python UTF-8 and reminder-off variables to an env block and keeps a user value on rerun', () => {
318
328
  const sandboxHome = mkdtempSync(join(tmpdir(), 'cde-settings-defaults-'));
319
329
  try {
320
330
  const settingsPath = join(sandboxHome, '.claude', 'settings.json');
@@ -324,8 +334,7 @@ test('install adds the idle compaction and Python UTF-8 variables to an env bloc
324
334
  assert.equal(firstRun.status, 0, firstRun.stderr);
325
335
  assert.deepEqual(JSON.parse(readFileSync(settingsPath, 'utf8')).env, {
326
336
  EDITOR: 'vim',
327
- CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS: '100000',
328
- PYTHONUTF8: '1',
337
+ ...PACKAGE_ENV_DEFAULTS,
329
338
  });
330
339
  const userChoice = JSON.parse(readFileSync(settingsPath, 'utf8'));
331
340
  userChoice.env.CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS = '300000';
@@ -338,6 +347,43 @@ test('install adds the idle compaction and Python UTF-8 variables to an env bloc
338
347
  }
339
348
  });
340
349
 
350
+ test('a fresh install writes the three reminder-off variables into the user settings env block', () => {
351
+ const sandboxHome = mkdtempSync(join(tmpdir(), 'cde-settings-defaults-'));
352
+ try {
353
+ const install = runInstallerInSandbox(sandboxHome);
354
+ assert.equal(install.status, 0, install.stderr);
355
+ const settingsPath = join(sandboxHome, '.claude', 'settings.json');
356
+ const installedEnv = JSON.parse(readFileSync(settingsPath, 'utf8')).env;
357
+ for (const [variableName, variableValue] of Object.entries(REMINDER_OFF_ENV)) {
358
+ assert.equal(installedEnv[variableName], variableValue, variableName);
359
+ }
360
+ } finally {
361
+ rmSync(sandboxHome, { recursive: true, force: true });
362
+ }
363
+ });
364
+
365
+ test('install leaves reminder-off variables the user already set in place and adds the missing ones', () => {
366
+ const sandboxHome = mkdtempSync(join(tmpdir(), 'cde-settings-defaults-'));
367
+ try {
368
+ const settingsPath = join(sandboxHome, '.claude', 'settings.json');
369
+ mkdirSync(join(sandboxHome, '.claude'), { recursive: true });
370
+ const userEnv = {
371
+ CLAUDE_CODE_TODO_REMINDER_MODE: 'off',
372
+ CLAUDE_CODE_SILENT_TURN_REMINDER: 'false',
373
+ EDITOR: 'vim',
374
+ };
375
+ writeFileSync(settingsPath, JSON.stringify({ env: userEnv }, null, 4) + '\n');
376
+ const install = runInstallerInSandbox(sandboxHome);
377
+ assert.equal(install.status, 0, install.stderr);
378
+ assert.deepEqual(JSON.parse(readFileSync(settingsPath, 'utf8')).env, {
379
+ ...PACKAGE_ENV_DEFAULTS,
380
+ ...userEnv,
381
+ });
382
+ } finally {
383
+ rmSync(sandboxHome, { recursive: true, force: true });
384
+ }
385
+ });
386
+
341
387
  test('install adds advisorModel when missing and keeps a user choice on rerun', () => {
342
388
  const sandboxHome = mkdtempSync(join(tmpdir(), 'cde-settings-defaults-'));
343
389
  try {
@@ -1,11 +1,25 @@
1
1
  import { test } from 'node:test';
2
2
  import { strict as assert } from 'node:assert';
3
+ import { readFileSync } from 'node:fs';
4
+ import { dirname, join } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
3
6
 
4
7
  import {
5
8
  mergeMissingSettingsDefaults,
6
9
  settingsDefaultsFromPackageSettings,
7
10
  } from './merge_settings_defaults.mjs';
8
11
 
12
+ const PACKAGE_SETTINGS_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', 'settings.json');
13
+ const REMINDER_OFF_ENV = {
14
+ CLAUDE_CODE_TODO_REMINDER_MODE: 'off',
15
+ CLAUDE_CODE_SILENT_TURN_REMINDER: '0',
16
+ CLAUDE_CODE_SILENT_TURN_REMINDER_TURNS: '100000',
17
+ };
18
+
19
+ function packageSettingsDefaults() {
20
+ return settingsDefaultsFromPackageSettings(JSON.parse(readFileSync(PACKAGE_SETTINGS_PATH, 'utf8')));
21
+ }
22
+
9
23
  test('settingsDefaultsFromPackageSettings excludes managed lists', () => {
10
24
  const packageSettings = {
11
25
  permissions: { allow: ['Read'] },
@@ -136,3 +150,27 @@ test('mergeMissingSettingsDefaults should keep a non-object env value as the use
136
150
  assert.deepEqual(targetSettings, { env: userEnv });
137
151
  }
138
152
  });
153
+
154
+ test('package defaults land the three reminder-off variables in a fresh settings object', () => {
155
+ const targetSettings = {};
156
+
157
+ mergeMissingSettingsDefaults(targetSettings, packageSettingsDefaults());
158
+
159
+ for (const [variableName, variableValue] of Object.entries(REMINDER_OFF_ENV)) {
160
+ assert.equal(targetSettings.env[variableName], variableValue, variableName);
161
+ }
162
+ });
163
+
164
+ test('package defaults keep the reminder-off variables a settings file already holds and add the missing one', () => {
165
+ const userEnv = {
166
+ CLAUDE_CODE_SILENT_TURN_REMINDER: 'false',
167
+ CLAUDE_CODE_SILENT_TURN_REMINDER_TURNS: '5',
168
+ EDITOR: 'code',
169
+ };
170
+ const targetSettings = { env: { ...userEnv } };
171
+
172
+ mergeMissingSettingsDefaults(targetSettings, packageSettingsDefaults());
173
+
174
+ assert.deepEqual(targetSettings.env, { ...packageSettingsDefaults().env, ...userEnv });
175
+ assert.equal(targetSettings.env.CLAUDE_CODE_TODO_REMINDER_MODE, 'off');
176
+ });
@@ -120,6 +120,19 @@ def expected_block(tool_name: str, quoted_sentence: str) -> dict[str, object]:
120
120
  }
121
121
 
122
122
 
123
+ def expected_advisory(tool_name: str, quoted_sentence: str) -> dict[str, object]:
124
+ return {
125
+ "hookSpecificOutput": {
126
+ "hookEventName": "PostToolUse",
127
+ "additionalContext": (
128
+ f'The reasoning behind this {tool_name} call hedges: "{quoted_sentence}" '
129
+ "Check that claim with a read-only tool before you act on the agent's result. "
130
+ "If it is wrong, send the agent a correction or stop it."
131
+ ),
132
+ }
133
+ }
134
+
135
+
123
136
  @pytest.fixture(autouse=True)
124
137
  def isolated_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
125
138
  monkeypatch.setenv("HOME", str(tmp_path))
@@ -438,8 +451,6 @@ def test_should_block_a_git_change_behind_a_wrapper(
438
451
  "Edit",
439
452
  "MultiEdit",
440
453
  "NotebookEdit",
441
- "Agent",
442
- "Task",
443
454
  "apply_patch",
444
455
  "mcp__gmail__send_message",
445
456
  "mcp__github__issue_write",
@@ -463,6 +474,45 @@ def test_should_block_each_always_mutating_tool_after_hedged_reasoning(
463
474
  assert json.loads(stdout_text)["decision"] == "block"
464
475
 
465
476
 
477
+ AGENT_INPUT = {"description": "Find the config", "prompt": "Read settings.json and report."}
478
+
479
+
480
+ @pytest.mark.parametrize("tool_name", ["Agent", "Task"])
481
+ def test_should_advise_without_blocking_a_spawn_after_hedged_reasoning(
482
+ monkeypatch: pytest.MonkeyPatch,
483
+ capsys: pytest.CaptureFixture[str],
484
+ tmp_path: Path,
485
+ tool_name: str,
486
+ ) -> None:
487
+ transcript_path = acting_transcript(tmp_path, HEDGED_SENTENCE, tool_name, AGENT_INPUT)
488
+ exit_code, stdout_text = run_hook(monkeypatch, capsys, tool_name, AGENT_INPUT, transcript_path)
489
+ output = json.loads(stdout_text)
490
+ assert exit_code == 0
491
+ assert "decision" not in output
492
+ assert output == expected_advisory(tool_name, HEDGED_SENTENCE)
493
+ assert logged_outcomes(tmp_path) == ["advised"]
494
+
495
+
496
+ def test_should_allow_a_spawn_after_clean_reasoning(
497
+ monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
498
+ ) -> None:
499
+ transcript_path = acting_transcript(tmp_path, CLEAN_SENTENCE, "Agent", AGENT_INPUT)
500
+ exit_code, stdout_text = run_hook(monkeypatch, capsys, "Agent", AGENT_INPUT, transcript_path)
501
+ assert (exit_code, stdout_text) == (0, "")
502
+ assert logged_outcomes(tmp_path) == ["allowed_clean"]
503
+
504
+
505
+ def test_should_still_block_an_edit_after_the_same_hedge_that_advises_a_spawn(
506
+ monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
507
+ ) -> None:
508
+ edit_input = {"file_path": "settings.json", "old_string": "a", "new_string": "b"}
509
+ transcript_path = acting_transcript(tmp_path, HEDGED_SENTENCE, "Edit", edit_input)
510
+ exit_code, stdout_text = run_hook(monkeypatch, capsys, "Edit", edit_input, transcript_path)
511
+ assert exit_code == 0
512
+ assert json.loads(stdout_text) == expected_block("Edit", HEDGED_SENTENCE)
513
+ assert logged_outcomes(tmp_path) == ["blocked"]
514
+
515
+
466
516
  def test_should_register_a_matcher_covering_every_mutating_tool_name() -> None:
467
517
  hooks_configuration = json.loads(
468
518
  (Path(__file__).resolve().parent.parent / "hooks.json").read_text(encoding="utf-8")
@@ -6,12 +6,16 @@ found in the session transcript by the call's ``tool_use_id``. When that
6
6
  reasoning hedges, the hook blocks and quotes the hedge sentence::
7
7
 
8
8
  flag: The config probably lives in settings.json. -> Write blocks
9
+ note: The config probably lives in settings.json. -> Agent gets advice
9
10
  ok: The config lives in settings.json, as read. -> Write passes
10
11
  ok: The config probably lives in settings.json. -> gh pr view passes
11
12
 
12
13
  The tool has already run, so the block reason tells the model to check the
13
14
  claim now with a read-only tool and to undo the change when the check
14
- contradicts it.
15
+ contradicts it. A spawn in ALL_ADVISORY_TOOL_NAMES (Agent, Task) has also
16
+ already run, so a block stops nothing there; the hook adds the same quote as
17
+ additionalContext with no decision, and asks the model to check the claim
18
+ before it acts on the agent's result.
15
19
 
16
20
  A call counts as mutating when its tool is in ALL_ALWAYS_MUTATING_TOOL_NAMES
17
21
  (Write, Edit, MultiEdit, NotebookEdit, apply_patch, Agent, Task), when a
@@ -24,7 +28,7 @@ from the quote-aware parser after every wrapper is stepped over, so
24
28
  is a check and passes with no log line.
25
29
 
26
30
  Each mutating call writes one JSON line to DECISION_LOG_RELATIVE_PATH under
27
- the home directory: blocked, allowed_clean, or reasoning_unseen when the
31
+ the home directory: blocked, advised, allowed_clean, or reasoning_unseen when the
28
32
  transcript record is missing or its thinking text is empty. A missing or
29
33
  unreadable input always allows, so the hook never fails closed.
30
34
  """
@@ -49,9 +53,12 @@ from hooks_constants.hook_specific_output_keys import (
49
53
  HOOK_SPECIFIC_OUTPUT_KEY,
50
54
  )
51
55
  from hooks_constants.hook_block_logger import log_hook_block
56
+ from hooks_constants.post_tool_use_context import write_post_tool_use_context_to_stdout
52
57
  from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
53
58
  from hooks_constants.shell_command_mutation import is_mutating_shell_command
54
59
  from hooks_constants.verify_before_acting_constants import (
60
+ ADVISORY_CONTEXT_TEMPLATE,
61
+ ALL_ADVISORY_TOOL_NAMES,
55
62
  ALL_ALWAYS_MUTATING_TOOL_NAMES,
56
63
  ALL_MCP_MUTATING_ACTION_NAMES,
57
64
  ALL_MCP_MUTATING_VERBS,
@@ -80,6 +87,7 @@ from hooks_constants.verify_before_acting_constants import (
80
87
  MCP_TOOL_PREFIX,
81
88
  MESSAGE_ID_KEY,
82
89
  MESSAGE_KEY,
90
+ OUTCOME_ADVISED,
83
91
  OUTCOME_ALLOWED_CLEAN,
84
92
  OUTCOME_BLOCKED,
85
93
  OUTCOME_REASONING_UNSEEN,
@@ -299,6 +307,13 @@ def _emit_block(tool_name: str, tool_use_id: object, hedge_sentence: str) -> Non
299
307
  sys.stdout.write(json.dumps(block_payload))
300
308
 
301
309
 
310
+ def _emit_advisory(tool_name: str, tool_use_id: object, hedge_sentence: str) -> None:
311
+ _log_decision(tool_name, tool_use_id, OUTCOME_ADVISED, hedge_sentence)
312
+ write_post_tool_use_context_to_stdout(
313
+ ADVISORY_CONTEXT_TEMPLATE.format(tool_name=tool_name, hedge_sentence=hedge_sentence)
314
+ )
315
+
316
+
302
317
  def main() -> int:
303
318
  hook_input = read_hook_input_dictionary_from_stdin()
304
319
  if hook_input is None:
@@ -317,6 +332,9 @@ def main() -> int:
317
332
  if hedge_sentence is None:
318
333
  _log_decision(tool_name, tool_use_id, OUTCOME_ALLOWED_CLEAN, None)
319
334
  return ALLOW_EXIT_CODE
335
+ if tool_name in ALL_ADVISORY_TOOL_NAMES:
336
+ _emit_advisory(tool_name, tool_use_id, hedge_sentence)
337
+ return ALLOW_EXIT_CODE
320
338
  _emit_block(tool_name, tool_use_id, hedge_sentence)
321
339
  return ALLOW_EXIT_CODE
322
340
 
@@ -17,7 +17,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
17
17
  - `blocking/session_title_turn_gate.py` holds the end of a turn once, in a session that has a `__set_session_title` tool, when the shown title does not fit the session's state: no title yet, a red flag after a prompt that asks for work, a check mark while the task list has open items, or an hourglass once every item is completed or deleted. A turn that set a title passes. A turn that called no tool other than the title tool passes, and so does a held turn.
18
18
  - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
19
19
  - `blocking/wakeup_cap_gate.py` keeps a self-wakeup inside the 1-hour prompt cache. A wake over the step-down (57 minutes for `send_later` and Routines, 3480 seconds for `ScheduleWakeup`) and at most 60 minutes away runs with its delay rewritten to the step-down. A wake over 60 minutes away, or a cron with more than 57 minutes between wakes, is denied with a reason that says to stack wakes under the cap. A Routine that starts a fresh session on each firing passes.
20
- - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim.
20
+ - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim. For an `Agent` or `Task` spawn it adds the same quote as an advisory note and does not block.
21
21
  - `blocking/pr_lifecycle_skill_gate.py` denies a commit, push, pull request action, or merge until the `pr-lifecycle` skill appears in the transcript since the last compaction. Read-only `gh pr` subcommands (`view`, `list`, `checks`, `diff`, `status`) pass without it, unless a later argument names another `gh pr` subcommand.
22
22
  - `blocking/resolve_thread_reply_gate.py` denies a review thread resolve until the agent's own transcript shows a reply on that same thread that posted after the last user prompt and that no successful resolve of the thread has spent. A resolve is a `resolve_review_thread` call, which names the thread by `threadID`; a `pull_request_review_write` call with method `resolve_thread`, which names it by `threadId`; a shell command with a `gh api graphql` `resolveReviewThread` mutation, which names it by a literal `PRRT_` id; or a shell call to `pulls/<n>/ccr/comments/<id>/resolve`, which names it by a comment id. A graphql resolve that names no `PRRT_` id is denied. A reply is an `add_reply_to_pull_request_comment` call, or a `gh api` call to a comment's `replies` endpoint or to `addPullRequestReviewThreadReply`, which names its thread by `PRRT_` id. A reply and a resolve by comment id match when they name the same comment, or when a successful tool result in the transcript, such as `pull_request_read` `get_review_comments`, lists the comment under the thread by its `discussion_r` anchor or `databaseId`. A reply whose result is an error, such as a refusal from `blocking/reply_length_gate.py`, does not count. With no readable transcript, the resolve passes.
23
23
  - `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.
@@ -72,7 +72,7 @@ Preconditions:
72
72
  - **Stale title.** Input is a transcript that lists the title tool, an earlier turn that set the red flag, and a work prompt whose turn ran a tool and set no title. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_turn_gate.py -q`. The adjacent test observes a `block` decision that names the shown title, the tool, and the four status emoji. A carried hourglass with an item in progress passes, and so does a turn whose title call came back without an error.
73
73
  - **Step note.** Input is a tool call after a transcript message without a status line while the flag is on. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_step_note_gate.py -q`. The adjacent test observes a block until a status line appears.
74
74
  - **Wakeup cap.** Input is a `send_later` call with `delay_minutes` of 60, then 90, then 45. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_wakeup_cap_gate.py -q`. The adjacent test observes 60 rewritten to 57 through `updatedInput`, 90 denied with the stacking instruction, and 45 passing untouched.
75
- - **Checked claim.** Input is a Write after hedged reasoning in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_acting.py -q`. The adjacent test observes a block and a logged blocked outcome.
75
+ - **Checked claim.** Input is a Write after hedged reasoning in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_acting.py -q`. The adjacent test observes a block and a logged blocked outcome. The same hedge before an `Agent` call gives `additionalContext`, no `decision`, and a logged advised outcome.
76
76
  - **Lifecycle skill.** Input is a `git commit` or `gh pr create` command with no `pr-lifecycle` invocation in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pr_lifecycle_skill_gate.py -q`. The adjacent test observes a denial, then a silent allow once the skill or its slash command appears.
77
77
  - **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.
78
78
  - **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.
@@ -89,7 +89,7 @@ Preconditions:
89
89
  - Each review run calls a model and costs about $0.03. Leave `CLAUDE_TURN_REVIEW_REPOSITORIES` unset and the gate makes no snapshot and no call.
90
90
  - `blocking/step_note_gate.py` is off by default and polls for the transcript record. Subagent calls and unreadable records pass.
91
91
  - `blocking/wakeup_cap_gate.py` lets an `update_trigger` cron change pass, because that input does not say whether the Routine wakes a session. Its step-down values come from fire-time probes: `send_later` rounds its fire time up to the next minute and polls once a minute, so a 1-minute request landed 123 and 158 seconds later. `ScheduleWakeup` rounds its fire time up to the next minute, so requests of 60 and 90 seconds landed 70 and 121 seconds later.
92
- - `blocking/verify_before_acting.py` runs after the tool. A block asks the agent to check the claim and undo a contradicted change.
92
+ - `blocking/verify_before_acting.py` runs after the tool. A block asks the agent to check the claim and undo a contradicted change. A spawn has already started when the hook runs, so a block would stop nothing. The advisory note asks the agent to check the claim before it acts on the spawned agent's result.
93
93
  - The reply gate counts each nonempty list line as a sentence. Link targets and code spans add no words. Its banned words come from `reply-banned-words.json` in the Claude home, or the file `CLAUDE_REPLY_BANNED_WORDS_PATH` names, with built-in defaults.
94
94
  - The final reply gate blocks the stop and returns its reason to the model, which rewrites the reply. Claude Code ends the turn anyway after eight blocks in a row. The cited number checks in both gates skip when the transcript cannot be read.
95
95
  - The edit marker gate scans replacement cards as well as the message text.
@@ -12,6 +12,11 @@ def test_mutating_tool_and_mcp_names_are_classified() -> None:
12
12
  assert "create" in constants.ALL_MCP_MUTATING_VERBS
13
13
 
14
14
 
15
+ def test_advisory_tools_are_scanned_as_mutating_calls() -> None:
16
+ assert {"Agent", "Task"} == constants.ALL_ADVISORY_TOOL_NAMES
17
+ assert constants.ALL_ADVISORY_TOOL_NAMES <= constants.ALL_ALWAYS_MUTATING_TOOL_NAMES
18
+
19
+
15
20
  def test_hedge_pattern_matches_a_hedged_claim_only() -> None:
16
21
  assert constants.HEDGE_PATTERN.search("Perhaps the command writes a file.")
17
22
  assert constants.HEDGE_PATTERN.search("I might be mistaken.")
@@ -27,6 +27,7 @@ TRANSCRIPT_POLL_LIMIT_SECONDS = 5.0
27
27
  ALL_ALWAYS_MUTATING_TOOL_NAMES = frozenset(
28
28
  {"Write", "Edit", "MultiEdit", "NotebookEdit", "Agent", "Task", APPLY_PATCH_TOOL_NAME}
29
29
  )
30
+ ALL_ADVISORY_TOOL_NAMES = frozenset({"Agent", "Task"})
30
31
  ALL_SHELL_TOOL_NAMES = frozenset({"Bash", "PowerShell"})
31
32
  MCP_TOOL_PREFIX = "mcp__"
32
33
  MCP_SEGMENT_SEPARATOR = "__"
@@ -156,6 +157,11 @@ BLOCK_REASON_TEMPLATE = (
156
157
  "Check that claim now with a read-only tool, then continue. "
157
158
  "If the check contradicts it, undo this change first."
158
159
  )
160
+ ADVISORY_CONTEXT_TEMPLATE = (
161
+ 'The reasoning behind this {tool_name} call hedges: "{hedge_sentence}" '
162
+ "Check that claim with a read-only tool before you act on the agent's result. "
163
+ "If it is wrong, send the agent a correction or stop it."
164
+ )
159
165
 
160
166
  DECISION_LOG_RELATIVE_PATH = ".claude/logs/verify-before-acting.jsonl"
161
167
  LOG_APPEND_MODE = "a"
@@ -166,5 +172,6 @@ LOG_TOOL_USE_ID_KEY = "tool_use_id"
166
172
  LOG_OUTCOME_KEY = "outcome"
167
173
  LOG_HEDGE_SENTENCE_KEY = "hedge_sentence"
168
174
  OUTCOME_BLOCKED = "blocked"
175
+ OUTCOME_ADVISED = "advised"
169
176
  OUTCOME_ALLOWED_CLEAN = "allowed_clean"
170
177
  OUTCOME_REASONING_UNSEEN = "reasoning_unseen"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-dev-env",
3
- "version": "8.114.0",
3
+ "version": "8.114.2",
4
4
  "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
5
5
  "type": "module",
6
6
  "bin": {
@@ -49,6 +49,10 @@ from dev_env_scripts_constants.account_broker_constants import (
49
49
  Meters,
50
50
  Product,
51
51
  ProductAdapter,
52
+ PUBLISHED_USAGE_DIRECTORY_ENV_VAR,
53
+ PUBLISHED_USAGE_FILE_PATTERN,
54
+ PUBLISHED_USAGE_CLOCK_SKEW_SECONDS,
55
+ PUBLISHED_USAGE_MAX_AGE_SECONDS,
52
56
  Reading,
53
57
  Report,
54
58
  REPORT_INDENT_SPACES,
@@ -281,8 +285,64 @@ def refresh_claude_login(account_home: Path) -> bool:
281
285
  return True
282
286
 
283
287
 
288
+ def read_published_meters(account: Account) -> Meters | None:
289
+ """Read one account's meters from the readings a single usage reader publishes.
290
+
291
+ ::
292
+
293
+ CLAUDE_USAGE_READINGS_DIR=/readings, account home .../alpha
294
+ /readings/meters-ALPHA.json {"read_at": "<5 minutes ago>", "accounts": [{"name": "alpha",
295
+ "meters": {"weekly_percent_left": 45.0, ...}}]}
296
+ -> Meters(weekly_percent_left=45.0, ...), and the usage endpoint is not called
297
+
298
+ A reading matches an account when its ``name`` equals the account home's folder name.
299
+ A reading older than ``PUBLISHED_USAGE_MAX_AGE_SECONDS``, or dated more than
300
+ ``PUBLISHED_USAGE_CLOCK_SKEW_SECONDS`` ahead of now, is ignored. The newest match wins.
301
+
302
+ Args:
303
+ account: Account whose meter is read.
304
+
305
+ Returns:
306
+ The published meters, or None when the folder is unset or holds no fresh reading for the account.
307
+ """
308
+ folder_text = os.environ.get(PUBLISHED_USAGE_DIRECTORY_ENV_VAR)
309
+ if not folder_text:
310
+ return None
311
+ home_name = account.home.name.casefold()
312
+ all_matches = [
313
+ (each_read_at, each_row)
314
+ for each_read_at, each_row in _fresh_published_rows(Path(folder_text), datetime.now(timezone.utc))
315
+ if str(each_row.get("name", "")).casefold() == home_name
316
+ ]
317
+ if not all_matches:
318
+ return None
319
+ newest_row = max(all_matches, key=lambda each_match: each_match[0])[1]
320
+ return _meters_from_payload(newest_row.get("meters"))
321
+
322
+
323
+ def _fresh_published_rows(folder: Path, now: datetime) -> Iterator[tuple[datetime, dict[str, object]]]:
324
+ for each_path in sorted(folder.glob(PUBLISHED_USAGE_FILE_PATTERN)):
325
+ yield from _fresh_rows_of(each_path, now)
326
+
327
+
328
+ def _fresh_rows_of(reading_path: Path, now: datetime) -> list[tuple[datetime, dict[str, object]]]:
329
+ try:
330
+ reading = json.loads(reading_path.read_text(encoding="utf-8-sig"))
331
+ except (OSError, ValueError):
332
+ return []
333
+ if not isinstance(reading, dict) or not isinstance(reading.get("accounts"), list):
334
+ return []
335
+ read_at = parse_utc_time(reading.get("read_at"))
336
+ if read_at is None:
337
+ return []
338
+ age_seconds = (now - read_at).total_seconds()
339
+ if not -PUBLISHED_USAGE_CLOCK_SKEW_SECONDS <= age_seconds <= PUBLISHED_USAGE_MAX_AGE_SECONDS:
340
+ return []
341
+ return [(read_at, each_row) for each_row in reading["accounts"] if isinstance(each_row, dict)]
342
+
343
+
284
344
  def read_claude_meters(account: Account) -> Meters | None:
285
- """Probe one Claude account.
345
+ """Read one Claude account's meters, from a published reading when one is fresh.
286
346
 
287
347
  Args:
288
348
  account: Account whose meter is read.
@@ -294,6 +354,9 @@ def read_claude_meters(account: Account) -> Meters | None:
294
354
  WeeklyUtilizationProbeError: The usage meters could not be measured.
295
355
  OSError: The credentials file could not be read.
296
356
  """
357
+ published_meters = read_published_meters(account)
358
+ if published_meters is not None:
359
+ return published_meters
297
360
  usage = probe_account_meters(account.home / CREDENTIALS_FILE_NAME, refresh_claude_login)
298
361
  return Meters(
299
362
  FULL_PERCENT - usage.session_utilization if usage.session_utilization is not None else None,
@@ -61,6 +61,10 @@ METER_READ_DELAY_FACTOR = 2.0
61
61
  METER_READ_MAX_DELAY_SECONDS = 8.0
62
62
  LAST_GOOD_METER_MAX_AGE_SECONDS = 1800.0
63
63
  METER_RATE_LIMIT_COOLDOWN_SECONDS = 300.0
64
+ PUBLISHED_USAGE_DIRECTORY_ENV_VAR = "CLAUDE_USAGE_READINGS_DIR"
65
+ PUBLISHED_USAGE_FILE_PATTERN = "meters-*.json"
66
+ PUBLISHED_USAGE_MAX_AGE_SECONDS = 1800.0
67
+ PUBLISHED_USAGE_CLOCK_SKEW_SECONDS = 300.0
64
68
  WAIT_EXIT_CODE = 3
65
69
  COMMAND_MISSING_EXIT_CODE = 127
66
70
  TIMEOUT_EXIT_CODE = 124
@@ -249,6 +249,90 @@ def test_should_load_codex_roster_without_meter_reads(
249
249
  assert [each_account.name for each_account in support.load_codex_accounts()] == ["one"]
250
250
 
251
251
 
252
+ def _write_published_reading(folder: Path, profile_name: str, read_at: datetime) -> None:
253
+ folder.mkdir(exist_ok=True)
254
+ reading = {
255
+ "read_at": read_at.strftime("%Y-%m-%dT%H:%M:%SZ"),
256
+ "accounts": [
257
+ {
258
+ "name": profile_name,
259
+ "meters": {
260
+ "session_percent_left": None,
261
+ "session_resets_at": None,
262
+ "weekly_percent_left": 45.0,
263
+ "weekly_resets_at": "2026-10-10T06:00:00Z",
264
+ },
265
+ }
266
+ ],
267
+ }
268
+ (folder / f"meters-{profile_name.upper()}.json").write_text(json.dumps(reading), encoding="utf-8")
269
+
270
+
271
+ def test_should_read_claude_meters_from_a_fresh_published_reading_without_a_probe(
272
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
273
+ ) -> None:
274
+ readings_folder = tmp_path / "readings"
275
+ _write_published_reading(readings_folder, "alpha", datetime.now(timezone.utc))
276
+ monkeypatch.setenv("CLAUDE_USAGE_READINGS_DIR", str(readings_folder))
277
+ all_probed_paths: list[object] = []
278
+ monkeypatch.setattr(support, "probe_account_meters", lambda path, _: all_probed_paths.append(path))
279
+
280
+ meters = support.read_claude_meters(Account(Product.CLAUDE, "one", tmp_path / "Alpha"))
281
+
282
+ assert all_probed_paths == []
283
+ assert meters.weekly_percent_left == 45.0
284
+ assert meters.session_percent_left is None
285
+ assert meters.weekly_resets_at == datetime(2026, 10, 10, 6, tzinfo=timezone.utc)
286
+
287
+
288
+ def test_should_use_the_newest_of_two_published_readings_for_one_account(
289
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
290
+ ) -> None:
291
+ readings_folder = tmp_path / "readings"
292
+ _write_published_reading(readings_folder, "alpha", datetime.now(timezone.utc) - timedelta(minutes=20))
293
+ newer = json.loads((readings_folder / "meters-ALPHA.json").read_text(encoding="utf-8"))
294
+ newer["read_at"] = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
295
+ newer["accounts"][0]["meters"]["weekly_percent_left"] = 12.0
296
+ (readings_folder / "meters-ZULU.json").write_text(json.dumps(newer), encoding="utf-8")
297
+ monkeypatch.setenv("CLAUDE_USAGE_READINGS_DIR", str(readings_folder))
298
+
299
+ meters = support.read_published_meters(Account(Product.CLAUDE, "one", tmp_path / "alpha"))
300
+
301
+ assert meters.weekly_percent_left == 12.0
302
+
303
+
304
+ def test_should_find_no_published_meters_when_no_readings_folder_is_named(
305
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
306
+ ) -> None:
307
+ readings_folder = tmp_path / "readings"
308
+ _write_published_reading(readings_folder, "alpha", datetime.now(timezone.utc))
309
+ account = Account(Product.CLAUDE, "one", tmp_path / "alpha")
310
+ monkeypatch.delenv("CLAUDE_USAGE_READINGS_DIR", raising=False)
311
+ assert support.read_published_meters(account) is None
312
+ monkeypatch.setenv("CLAUDE_USAGE_READINGS_DIR", str(readings_folder))
313
+ assert support.read_published_meters(account).weekly_percent_left == 45.0
314
+
315
+
316
+ @pytest.mark.parametrize(
317
+ ("profile_name", "age_minutes"),
318
+ [("alpha", 45), ("beta", 1), ("alpha", -60)],
319
+ )
320
+ def test_should_probe_when_the_published_reading_is_old_or_for_another_account(
321
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, profile_name: str, age_minutes: int
322
+ ) -> None:
323
+ readings_folder = tmp_path / "readings"
324
+ _write_published_reading(
325
+ readings_folder, profile_name, datetime.now(timezone.utc) - timedelta(minutes=age_minutes)
326
+ )
327
+ monkeypatch.setenv("CLAUDE_USAGE_READINGS_DIR", str(readings_folder))
328
+ usage = SimpleNamespace(session_utilization=None, session_resets_at=None, weekly_utilization=30.0, weekly_resets_at=None)
329
+ monkeypatch.setattr(support, "probe_account_meters", lambda _, refresh_login: usage)
330
+
331
+ meters = support.read_claude_meters(Account(Product.CLAUDE, "one", tmp_path / "alpha"))
332
+
333
+ assert meters.weekly_percent_left == 70.0
334
+
335
+
252
336
  def test_should_read_claude_meters_through_injected_probe(
253
337
  monkeypatch: pytest.MonkeyPatch, tmp_path: Path
254
338
  ) -> None:
package/settings.json CHANGED
@@ -30,6 +30,9 @@
30
30
  },
31
31
  "env": {
32
32
  "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "100000",
33
+ "CLAUDE_CODE_SILENT_TURN_REMINDER": "0",
34
+ "CLAUDE_CODE_SILENT_TURN_REMINDER_TURNS": "100000",
35
+ "CLAUDE_CODE_TODO_REMINDER_MODE": "off",
33
36
  "PYTHONUTF8": "1"
34
37
  }
35
38
  }