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.
- package/bin/install.settings-defaults.test.mjs +51 -5
- package/bin/merge_settings_defaults.test.mjs +38 -0
- package/hooks/blocking/test_verify_before_acting.py +52 -2
- package/hooks/blocking/verify_before_acting.py +20 -2
- package/hooks/features/conduct-gates.md +3 -3
- package/hooks/hooks_constants/test_verify_before_acting_constants.py +5 -0
- package/hooks/hooks_constants/verify_before_acting_constants.py +7 -0
- package/package.json +1 -1
- package/scripts/account_broker_support.py +64 -1
- package/scripts/dev_env_scripts_constants/account_broker_constants.py +4 -0
- package/scripts/test_account_broker_support.py +84 -0
- package/settings.json +3 -0
|
@@ -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
|
|
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,
|
|
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
|
|
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
|
-
|
|
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
|
@@ -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
|
-
"""
|
|
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