claude-dev-env 8.125.0 → 8.126.1
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/ever-registered-hooks.mjs +1 -0
- package/bin/ever-registered-hooks.test.mjs +4 -0
- package/bin/install-constants.mjs +5 -0
- package/bin/install-constants.test.mjs +29 -0
- package/bin/install.mjs +15 -15
- package/bin/install.test.mjs +6 -2
- package/bin/profile-stop-gate.mjs +99 -68
- package/bin/profile-stop-gate.test.mjs +203 -13
- package/docs/agents-guidance/asks.md +1 -1
- package/docs/references/working-style.md +1 -0
- package/docs/rule-guides/question-presentation.md +65 -0
- package/hooks/features/conduct-gates.md +3 -0
- package/hooks/hooks.json +5 -0
- package/package.json +1 -1
- package/rules/question-presentation.md +6 -4
- package/scripts/gh_artifact_upload.py +3 -3
- package/scripts/policy_lint/adapter_configuration.py +6 -0
- package/scripts/policy_lint/config/constants.py +1 -0
- package/scripts/tests/test_adapter_configuration.py +8 -0
- package/scripts/tests/test_gh_artifact_upload.py +18 -0
|
@@ -23,6 +23,7 @@ export const EVER_REGISTERED_HOOK_RELATIVE_PATHS = new Set([
|
|
|
23
23
|
'blocking/build_eval_before_eval_write_gate.py',
|
|
24
24
|
'blocking/chat_reply_gate.py',
|
|
25
25
|
'blocking/claude_md_orphan_file_blocker.py',
|
|
26
|
+
'blocking/closing_question_round_gate.py',
|
|
26
27
|
'blocking/code-rules-enforcer.py',
|
|
27
28
|
'blocking/code_review_pr_create_gate.py',
|
|
28
29
|
'blocking/code_rules_enforcer.py',
|
|
@@ -24,6 +24,10 @@ test('EVER_REGISTERED_HOOK_RELATIVE_PATHS keeps the question brief gate', () =>
|
|
|
24
24
|
assert.ok(EVER_REGISTERED_HOOK_RELATIVE_PATHS.has('blocking/question_brief_gate.py'));
|
|
25
25
|
});
|
|
26
26
|
|
|
27
|
+
test('EVER_REGISTERED_HOOK_RELATIVE_PATHS keeps the closing question round gate', () => {
|
|
28
|
+
assert.ok(EVER_REGISTERED_HOOK_RELATIVE_PATHS.has('blocking/closing_question_round_gate.py'));
|
|
29
|
+
});
|
|
30
|
+
|
|
27
31
|
test('EVER_REGISTERED_HOOK_RELATIVE_PATHS keeps the artifact current page gate and its link record', () => {
|
|
28
32
|
assert.ok(EVER_REGISTERED_HOOK_RELATIVE_PATHS.has('blocking/artifact_current_page_gate.py'));
|
|
29
33
|
assert.ok(EVER_REGISTERED_HOOK_RELATIVE_PATHS.has('session/artifact_link_record.py'));
|
|
@@ -192,6 +192,11 @@ export const CURSOR_HOOKS_SCHEMA_VERSION = 1;
|
|
|
192
192
|
export const CURSOR_HOOK_TIMEOUT_SECONDS = 10;
|
|
193
193
|
export const CURSOR_GUIDANCE_HOOK_RELATIVE_PATH = Object.freeze(['session', 'cursor_agents_guidance.py']);
|
|
194
194
|
export const CURSOR_OPEN_TASKS_HOOK_RELATIVE_PATH = Object.freeze(['blocking', 'open_tasks_stop_gate.py']);
|
|
195
|
+
export const CLOSING_QUESTION_ROUND_HOOK_RELATIVE_PATH = Object.freeze(['blocking', 'closing_question_round_gate.py']);
|
|
196
|
+
export const ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS = Object.freeze([
|
|
197
|
+
CURSOR_OPEN_TASKS_HOOK_RELATIVE_PATH,
|
|
198
|
+
CLOSING_QUESTION_ROUND_HOOK_RELATIVE_PATH,
|
|
199
|
+
]);
|
|
195
200
|
export const CURSOR_SESSION_START_EVENT = 'sessionStart';
|
|
196
201
|
export const CURSOR_BEFORE_SUBMIT_PROMPT_EVENT = 'beforeSubmitPrompt';
|
|
197
202
|
export const CURSOR_STOP_EVENT = 'stop';
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { strict as assert } from 'node:assert';
|
|
2
|
+
import { test } from 'node:test';
|
|
3
|
+
import { existsSync } from 'node:fs';
|
|
4
|
+
import { fileURLToPath } from 'node:url';
|
|
5
|
+
import path from 'node:path';
|
|
6
|
+
import {
|
|
7
|
+
ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS,
|
|
8
|
+
CLOSING_QUESTION_ROUND_HOOK_RELATIVE_PATH,
|
|
9
|
+
CURSOR_OPEN_TASKS_HOOK_RELATIVE_PATH,
|
|
10
|
+
} from './install-constants.mjs';
|
|
11
|
+
|
|
12
|
+
const HOOKS_DIRECTORY = fileURLToPath(new URL('../hooks', import.meta.url));
|
|
13
|
+
|
|
14
|
+
test('ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS should list the open tasks gate, then the closing question round gate', () => {
|
|
15
|
+
assert.deepEqual(ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS, [
|
|
16
|
+
CURSOR_OPEN_TASKS_HOOK_RELATIVE_PATH,
|
|
17
|
+
CLOSING_QUESTION_ROUND_HOOK_RELATIVE_PATH,
|
|
18
|
+
]);
|
|
19
|
+
assert.deepEqual(CLOSING_QUESTION_ROUND_HOOK_RELATIVE_PATH, ['blocking', 'closing_question_round_gate.py']);
|
|
20
|
+
assert.ok(Object.isFrozen(ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS));
|
|
21
|
+
assert.ok(Object.isFrozen(CLOSING_QUESTION_ROUND_HOOK_RELATIVE_PATH));
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
test('each profile Stop gate path should name a hook script the package ships', () => {
|
|
25
|
+
const allMissingPaths = ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS.map(
|
|
26
|
+
relativeParts => path.join(HOOKS_DIRECTORY, ...relativeParts),
|
|
27
|
+
).filter(scriptPath => !existsSync(scriptPath));
|
|
28
|
+
assert.deepEqual(allMissingPaths, []);
|
|
29
|
+
});
|
package/bin/install.mjs
CHANGED
|
@@ -146,9 +146,9 @@ import {
|
|
|
146
146
|
} from './install-transaction.mjs';
|
|
147
147
|
import { findShadowingGlobalInstall, shadowingGlobalAdvice } from './global-install-shadow.mjs';
|
|
148
148
|
import {
|
|
149
|
-
|
|
149
|
+
addStopGatesToProfiles,
|
|
150
150
|
otherProfileSettingsPaths,
|
|
151
|
-
|
|
151
|
+
removeStopGatesFromProfiles,
|
|
152
152
|
splitUnreadableProfileSettings,
|
|
153
153
|
unparsedSettingsMayHoldGate,
|
|
154
154
|
} from './profile-stop-gate.mjs';
|
|
@@ -2876,10 +2876,10 @@ function install(selectedGroups, options = {}) {
|
|
|
2876
2876
|
}
|
|
2877
2877
|
|
|
2878
2878
|
/**
|
|
2879
|
-
* List the profile settings paths that get the open
|
|
2879
|
+
* List the profile settings paths that get the open tasks and closing question round Stop gates.
|
|
2880
2880
|
*
|
|
2881
|
-
* Only an install into the main ~/.claude does this, because
|
|
2882
|
-
* names the main home
|
|
2881
|
+
* Only an install into the main ~/.claude does this, because each gate entry
|
|
2882
|
+
* names a hook script in the main home.
|
|
2883
2883
|
*
|
|
2884
2884
|
* @param {string} mainSettingsPath
|
|
2885
2885
|
* @returns {string[]}
|
|
@@ -2901,7 +2901,7 @@ function readableProfileSettingsPathsForStopGate(mainSettingsPath) {
|
|
|
2901
2901
|
);
|
|
2902
2902
|
for (const { settingsPath, reason } of allUnreadable) {
|
|
2903
2903
|
const actionLine = `Profile settings: ${settingsPath} was left unchanged because it is not valid JSON (${reason}).`
|
|
2904
|
-
+ ' Fix the file and run the install again to add the open
|
|
2904
|
+
+ ' Fix the file and run the install again to add the open tasks and closing question round Stop gates there.';
|
|
2905
2905
|
console.warn(` ${actionLine}`);
|
|
2906
2906
|
allActionNeededLines.push(actionLine);
|
|
2907
2907
|
}
|
|
@@ -2909,12 +2909,12 @@ function readableProfileSettingsPathsForStopGate(mainSettingsPath) {
|
|
|
2909
2909
|
}
|
|
2910
2910
|
|
|
2911
2911
|
/**
|
|
2912
|
-
* Return the profile settings the uninstall removes the
|
|
2912
|
+
* Return the profile settings the uninstall removes the gates from, or the reason it must stop first.
|
|
2913
2913
|
*
|
|
2914
|
-
* A profile file that does not parse and may still hold
|
|
2914
|
+
* A profile file that does not parse and may still hold a gate stops the
|
|
2915
2915
|
* uninstall before it changes anything. The manifest then stays, so running
|
|
2916
|
-
* --uninstall again after fixing the file removes the
|
|
2917
|
-
* not parse and
|
|
2916
|
+
* --uninstall again after fixing the file removes the gates. A file that does
|
|
2917
|
+
* not parse and names neither gate has nothing to remove and is left as
|
|
2918
2918
|
* it is.
|
|
2919
2919
|
*
|
|
2920
2920
|
* @param {string} mainSettingsPath
|
|
@@ -2930,7 +2930,7 @@ function profileSettingsPathsForGateRemoval(mainSettingsPath) {
|
|
|
2930
2930
|
if (allHoldingGate.length === 0) return { allReadablePaths, blockingReason: null };
|
|
2931
2931
|
const fileLines = allHoldingGate.map(({ settingsPath, reason }) => ` ${settingsPath}: not valid JSON (${reason})`);
|
|
2932
2932
|
const blockingReason = [
|
|
2933
|
-
'ERROR: uninstall stopped before changing anything. These profile settings files still name the open
|
|
2933
|
+
'ERROR: uninstall stopped before changing anything. These profile settings files still name the open tasks or closing question round Stop gate, and they are not valid JSON, so the gates cannot be removed from them:',
|
|
2934
2934
|
...fileLines,
|
|
2935
2935
|
'Fix each file and run --uninstall again.',
|
|
2936
2936
|
].join('\n');
|
|
@@ -3435,14 +3435,14 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
|
|
|
3435
3435
|
for (const eachLine of describeProfileSettingsOutcome(mergeOutcome, false)) {
|
|
3436
3436
|
console.log(` Profile settings: ${eachLine}`);
|
|
3437
3437
|
}
|
|
3438
|
-
for (const eachOutcome of
|
|
3438
|
+
for (const eachOutcome of addStopGatesToProfiles({
|
|
3439
3439
|
mainSettingsPath: join(CLAUDE_HOME, SETTINGS_FILE_NAME),
|
|
3440
3440
|
claudeHome: CLAUDE_HOME,
|
|
3441
3441
|
allProfileSettingsPaths: readableProfileSettingsPathsForStopGate(join(CLAUDE_HOME, SETTINGS_FILE_NAME)),
|
|
3442
3442
|
homeDirectory: homedir(),
|
|
3443
3443
|
})) {
|
|
3444
3444
|
if (eachOutcome.additions.length > 0) {
|
|
3445
|
-
console.log(` Profile settings:
|
|
3445
|
+
console.log(` Profile settings: Stop gates added to ${eachOutcome.settingsPath}`);
|
|
3446
3446
|
}
|
|
3447
3447
|
}
|
|
3448
3448
|
|
|
@@ -3732,11 +3732,11 @@ function executeUninstallPlan(plan, helpers = {}) {
|
|
|
3732
3732
|
writeFileAtomically(plan.settingsPath, JSON.stringify(settings, null, 4) + '\n');
|
|
3733
3733
|
}
|
|
3734
3734
|
}
|
|
3735
|
-
for (const eachChangedPath of
|
|
3735
|
+
for (const eachChangedPath of removeStopGatesFromProfiles({
|
|
3736
3736
|
claudeHome: CLAUDE_HOME,
|
|
3737
3737
|
allProfileSettingsPaths: helpers.allProfileSettingsPaths,
|
|
3738
3738
|
})) {
|
|
3739
|
-
console.log(` Profile settings:
|
|
3739
|
+
console.log(` Profile settings: Stop gates removed from ${eachChangedPath}`);
|
|
3740
3740
|
}
|
|
3741
3741
|
if (!codexRoutingHookExists()) {
|
|
3742
3742
|
pruneManagedHooksFromHostConfiguration(CODEX_HOOKS_CONFIGURATION_PATH, 2);
|
package/bin/install.test.mjs
CHANGED
|
@@ -3933,7 +3933,7 @@ test('install prints no Action needed block when every side step finished', (con
|
|
|
3933
3933
|
assert.equal(result.stderr.includes('Action needed'), false, result.stderr);
|
|
3934
3934
|
});
|
|
3935
3935
|
|
|
3936
|
-
test('install adds the open
|
|
3936
|
+
test('install adds the open tasks and closing question round Stop gates to every profile with its own settings.json, and uninstall removes both', (context) => {
|
|
3937
3937
|
const homeDirectory = mkdtempSync(join(tmpdir(), 'cde-profile-gate-install-'));
|
|
3938
3938
|
context.after(() => rmSync(homeDirectory, { recursive: true, force: true }));
|
|
3939
3939
|
const profileSettingsPath = join(homeDirectory, '.claude-profiles', 'prefs-only', 'settings.json');
|
|
@@ -3966,7 +3966,11 @@ test('install adds the open-tasks Stop gate to every profile with its own settin
|
|
|
3966
3966
|
|
|
3967
3967
|
const installation = runInstaller([]);
|
|
3968
3968
|
assert.equal(installation.status, 0, installation.stderr);
|
|
3969
|
-
assert.
|
|
3969
|
+
assert.deepEqual(
|
|
3970
|
+
profileStopCommands().map((eachCommand) => eachCommand.replace(/\\/g, '/').split('/').pop()),
|
|
3971
|
+
['open_tasks_stop_gate.py', 'closing_question_round_gate.py'],
|
|
3972
|
+
);
|
|
3973
|
+
assert.ok(installation.stdout.includes(`Profile settings: Stop gates added to ${profileSettingsPath}`), installation.stdout);
|
|
3970
3974
|
|
|
3971
3975
|
const uninstallation = runInstaller(['--uninstall']);
|
|
3972
3976
|
assert.equal(uninstallation.status, 0, uninstallation.stderr);
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
3
|
|
|
4
|
-
import {
|
|
4
|
+
import { ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS } from './install-constants.mjs';
|
|
5
5
|
import {
|
|
6
6
|
discoverProfileSettingsPaths,
|
|
7
7
|
hostConfigurationIndent,
|
|
@@ -28,36 +28,52 @@ function comparableCommand(command) {
|
|
|
28
28
|
}
|
|
29
29
|
|
|
30
30
|
/**
|
|
31
|
-
* Return
|
|
31
|
+
* Return one gate script's path under a Claude home, in the spelling hook commands compare by.
|
|
32
32
|
*
|
|
33
33
|
* @param {string} claudeHome
|
|
34
|
+
* @param {readonly string[]} hookRelativePath The script's path segments under the hooks directory.
|
|
34
35
|
* @returns {string}
|
|
35
36
|
*/
|
|
36
|
-
export function gateScriptCommandFragment(claudeHome) {
|
|
37
|
-
return comparableCommand(join(claudeHome, MANAGED_HOOKS_DIRECTORY_NAME, ...
|
|
37
|
+
export function gateScriptCommandFragment(claudeHome, hookRelativePath) {
|
|
38
|
+
return comparableCommand(join(claudeHome, MANAGED_HOOKS_DIRECTORY_NAME, ...hookRelativePath));
|
|
38
39
|
}
|
|
39
40
|
|
|
40
|
-
function isGateHook(eachHook, claudeHome) {
|
|
41
|
-
|
|
42
|
-
|
|
41
|
+
function isGateHook(eachHook, claudeHome, allHookRelativePaths = ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS) {
|
|
42
|
+
if (typeof eachHook?.command !== 'string') return false;
|
|
43
|
+
const command = comparableCommand(eachHook.command);
|
|
44
|
+
return allHookRelativePaths.some(
|
|
45
|
+
(eachRelativePath) => command.includes(gateScriptCommandFragment(claudeHome, eachRelativePath)),
|
|
46
|
+
);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function stopHooks(settingsPath) {
|
|
50
|
+
const settingsText = readFileSync(settingsPath, 'utf8');
|
|
51
|
+
if (!settingsText.trim()) return [];
|
|
52
|
+
const settings = JSON.parse(settingsText);
|
|
53
|
+
const stopGroups = settings?.hooks?.[STOP_EVENT_NAME];
|
|
54
|
+
if (!Array.isArray(stopGroups)) return [];
|
|
55
|
+
return stopGroups.flatMap((eachGroup) => (Array.isArray(eachGroup?.hooks) ? eachGroup.hooks : []));
|
|
43
56
|
}
|
|
44
57
|
|
|
45
58
|
/**
|
|
46
|
-
* Find
|
|
59
|
+
* Find each profile Stop gate hook the install wrote into the main settings.
|
|
60
|
+
*
|
|
61
|
+
* The gates come back in the order of ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS.
|
|
62
|
+
* A gate the main settings do not hold is left out.
|
|
47
63
|
*
|
|
48
64
|
* @param {string} mainSettingsPath
|
|
49
65
|
* @param {string} claudeHome
|
|
50
|
-
* @returns {Record<string, unknown
|
|
66
|
+
* @returns {{ hookRelativePath: readonly string[], gateHook: Record<string, unknown> }[]} A copy of each hook entry.
|
|
51
67
|
*/
|
|
52
|
-
export function
|
|
53
|
-
if (!existsSync(mainSettingsPath)) return
|
|
54
|
-
const
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
}
|
|
68
|
+
export function mainStopGateHooks(mainSettingsPath, claudeHome) {
|
|
69
|
+
if (!existsSync(mainSettingsPath)) return [];
|
|
70
|
+
const allMainStopHooks = stopHooks(mainSettingsPath);
|
|
71
|
+
const allMainGates = [];
|
|
72
|
+
for (const eachRelativePath of ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS) {
|
|
73
|
+
const gateHook = allMainStopHooks.find((eachHook) => isGateHook(eachHook, claudeHome, [eachRelativePath]));
|
|
74
|
+
if (gateHook) allMainGates.push({ hookRelativePath: eachRelativePath, gateHook: structuredClone(gateHook) });
|
|
59
75
|
}
|
|
60
|
-
return
|
|
76
|
+
return allMainGates;
|
|
61
77
|
}
|
|
62
78
|
|
|
63
79
|
/**
|
|
@@ -112,11 +128,11 @@ export function splitUnreadableProfileSettings(allProfileSettingsPaths) {
|
|
|
112
128
|
}
|
|
113
129
|
|
|
114
130
|
/**
|
|
115
|
-
* True when a settings.json that does not parse may still hold this Claude home's
|
|
131
|
+
* True when a settings.json that does not parse may still hold one of this Claude home's profile Stop gates.
|
|
116
132
|
*
|
|
117
|
-
* The raw text is searched for
|
|
133
|
+
* The raw text is searched for each gate script path, with JSON-escaped
|
|
118
134
|
* backslashes read as path separators. A file that cannot be read counts as
|
|
119
|
-
* one that may hold
|
|
135
|
+
* one that may hold a gate.
|
|
120
136
|
*
|
|
121
137
|
* @param {string} settingsPath
|
|
122
138
|
* @param {string} claudeHome
|
|
@@ -129,91 +145,104 @@ export function unparsedSettingsMayHoldGate(settingsPath, claudeHome) {
|
|
|
129
145
|
} catch {
|
|
130
146
|
return true;
|
|
131
147
|
}
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
const settingsText = readFileSync(settingsPath, 'utf8');
|
|
137
|
-
if (!settingsText.trim()) return [];
|
|
138
|
-
const settings = JSON.parse(settingsText);
|
|
139
|
-
const stopGroups = settings?.hooks?.[STOP_EVENT_NAME];
|
|
140
|
-
if (!Array.isArray(stopGroups)) return [];
|
|
141
|
-
return stopGroups.flatMap((eachGroup) => (Array.isArray(eachGroup?.hooks) ? eachGroup.hooks : []));
|
|
148
|
+
const comparableText = comparableCommand(settingsText.replace(/\\\\/g, '/'));
|
|
149
|
+
return ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS.some(
|
|
150
|
+
(eachRelativePath) => comparableText.includes(gateScriptCommandFragment(claudeHome, eachRelativePath)),
|
|
151
|
+
);
|
|
142
152
|
}
|
|
143
153
|
|
|
144
|
-
function profileGateHooks(settingsPath, claudeHome) {
|
|
145
|
-
return stopHooks(settingsPath).filter((eachHook) => isGateHook(eachHook, claudeHome));
|
|
154
|
+
function profileGateHooks(settingsPath, claudeHome, hookRelativePath) {
|
|
155
|
+
return stopHooks(settingsPath).filter((eachHook) => isGateHook(eachHook, claudeHome, [hookRelativePath]));
|
|
146
156
|
}
|
|
147
157
|
|
|
148
158
|
/**
|
|
149
|
-
* True when a profile's settings.json already runs
|
|
159
|
+
* True when a profile's settings.json already runs one gate script from another Claude home.
|
|
150
160
|
*
|
|
151
161
|
* An install with CLAUDE_CONFIG_DIR set to the profile writes a gate entry
|
|
152
162
|
* for the profile's own copy of the script, and a second entry for the main
|
|
153
|
-
* home's copy would run
|
|
163
|
+
* home's copy would run that gate twice on every stop.
|
|
154
164
|
*
|
|
155
165
|
* @param {string} settingsPath
|
|
156
166
|
* @param {string} claudeHome
|
|
167
|
+
* @param {readonly string[]} hookRelativePath The gate script's path segments under the hooks directory.
|
|
157
168
|
* @returns {boolean}
|
|
158
169
|
*/
|
|
159
|
-
export function profileRunsItsOwnGate(settingsPath, claudeHome) {
|
|
160
|
-
const scriptPathSuffix = `/${comparableCommand(join(MANAGED_HOOKS_DIRECTORY_NAME, ...
|
|
170
|
+
export function profileRunsItsOwnGate(settingsPath, claudeHome, hookRelativePath) {
|
|
171
|
+
const scriptPathSuffix = `/${comparableCommand(join(MANAGED_HOOKS_DIRECTORY_NAME, ...hookRelativePath))}`;
|
|
161
172
|
return stopHooks(settingsPath).some((eachHook) => typeof eachHook?.command === 'string'
|
|
162
173
|
&& comparableCommand(eachHook.command).includes(scriptPathSuffix)
|
|
163
|
-
&& !isGateHook(eachHook, claudeHome));
|
|
174
|
+
&& !isGateHook(eachHook, claudeHome, [hookRelativePath]));
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
function staleGateRelativePaths(settingsPath, claudeHome, allWantedGates) {
|
|
178
|
+
return allWantedGates
|
|
179
|
+
.filter(({ hookRelativePath, gateHook }) => profileGateHooks(settingsPath, claudeHome, hookRelativePath)
|
|
180
|
+
.some((eachHook) => eachHook.command !== gateHook.command || eachHook.timeout !== gateHook.timeout))
|
|
181
|
+
.map(({ hookRelativePath }) => hookRelativePath);
|
|
164
182
|
}
|
|
165
183
|
|
|
166
184
|
/**
|
|
167
|
-
* Add the main settings'
|
|
185
|
+
* Add each of the main settings' profile Stop gates to every other profile's settings.json.
|
|
168
186
|
*
|
|
169
|
-
* A profile keeps its own settings and hooks.
|
|
170
|
-
* entry, in the spelling the main settings use,
|
|
171
|
-
*
|
|
172
|
-
*
|
|
173
|
-
*
|
|
187
|
+
* A profile keeps its own settings and hooks. Each gate is handled on its
|
|
188
|
+
* own. The merge adds a gate entry, in the spelling the main settings use,
|
|
189
|
+
* only where that gate is missing, so a profile that holds one gate gets the
|
|
190
|
+
* other. An entry left with an older interpreter spelling or timeout is replaced. The
|
|
191
|
+
* file as it was before either change is copied to a timestamped `.bak`. A
|
|
192
|
+
* gate the profile already runs from its own copy of the script is left as
|
|
193
|
+
* it is, and so is a gate the main settings do not hold.
|
|
174
194
|
*
|
|
175
195
|
* @param {{ mainSettingsPath: string, claudeHome: string, allProfileSettingsPaths: string[],
|
|
176
196
|
* homeDirectory: string, now?: Date }} options
|
|
177
197
|
* @returns {{ settingsPath: string, additions: string[], backupPath: string|null }[]}
|
|
178
198
|
*/
|
|
179
|
-
export function
|
|
180
|
-
const
|
|
181
|
-
if (!gateHook) return [];
|
|
199
|
+
export function addStopGatesToProfiles(options) {
|
|
200
|
+
const allMainGates = mainStopGateHooks(options.mainSettingsPath, options.claudeHome);
|
|
182
201
|
const timestamp = (options.now ?? new Date()).toISOString().replace(/[:.]/g, '-');
|
|
183
|
-
const
|
|
184
|
-
const
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
(
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
202
|
+
const allOutcomes = [];
|
|
203
|
+
for (const eachPath of options.allProfileSettingsPaths) {
|
|
204
|
+
const allWantedGates = allMainGates.filter(
|
|
205
|
+
({ hookRelativePath }) => !profileRunsItsOwnGate(eachPath, options.claudeHome, hookRelativePath),
|
|
206
|
+
);
|
|
207
|
+
if (allWantedGates.length === 0) continue;
|
|
208
|
+
const allStaleRelativePaths = staleGateRelativePaths(eachPath, options.claudeHome, allWantedGates);
|
|
209
|
+
const originalText = readFileSync(eachPath, 'utf8');
|
|
210
|
+
removeStopGatesFromProfiles({
|
|
211
|
+
claudeHome: options.claudeHome,
|
|
212
|
+
allProfileSettingsPaths: [eachPath],
|
|
213
|
+
allHookRelativePaths: allStaleRelativePaths,
|
|
214
|
+
});
|
|
194
215
|
const outcome = mergeProfileSettingsFile(eachPath, {
|
|
195
216
|
dryRun: false,
|
|
196
217
|
homeDirectory: options.homeDirectory,
|
|
197
218
|
timestamp,
|
|
198
|
-
declaredSettings
|
|
219
|
+
declaredSettings: [{
|
|
220
|
+
keyPath: ['hooks', STOP_EVENT_NAME],
|
|
221
|
+
items: allWantedGates.map(({ gateHook }) => ({ hooks: [gateHook] })),
|
|
222
|
+
}],
|
|
199
223
|
});
|
|
200
|
-
if (outcome.backupPath &&
|
|
201
|
-
writeFileSync(outcome.backupPath,
|
|
224
|
+
if (outcome.backupPath && allStaleRelativePaths.length > 0) {
|
|
225
|
+
writeFileSync(outcome.backupPath, originalText);
|
|
202
226
|
}
|
|
203
|
-
|
|
204
|
-
}
|
|
227
|
+
allOutcomes.push(outcome);
|
|
228
|
+
}
|
|
229
|
+
return allOutcomes;
|
|
205
230
|
}
|
|
206
231
|
|
|
207
232
|
/**
|
|
208
|
-
* Remove the gate
|
|
233
|
+
* Remove the gate entries that point at the main Claude home from each listed profile settings path.
|
|
209
234
|
*
|
|
210
|
-
* Only a hook whose command runs the main home's gate
|
|
211
|
-
* group left empty goes too, and so does an emptied Stop list or hooks
|
|
235
|
+
* Only a hook whose command runs one of the main home's gate scripts goes. A
|
|
236
|
+
* Stop group left empty goes too, and so does an emptied Stop list or hooks
|
|
237
|
+
* object.
|
|
212
238
|
*
|
|
213
|
-
* @param {{ claudeHome: string, allProfileSettingsPaths: string[]
|
|
239
|
+
* @param {{ claudeHome: string, allProfileSettingsPaths: string[],
|
|
240
|
+
* allHookRelativePaths?: readonly (readonly string[])[] }} options
|
|
241
|
+
* allHookRelativePaths limits the removal to those gates. Every profile Stop gate goes without it.
|
|
214
242
|
* @returns {string[]} The settings paths that changed.
|
|
215
243
|
*/
|
|
216
|
-
export function
|
|
244
|
+
export function removeStopGatesFromProfiles(options) {
|
|
245
|
+
const allHookRelativePaths = options.allHookRelativePaths ?? ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS;
|
|
217
246
|
const allChangedPaths = [];
|
|
218
247
|
for (const eachPath of options.allProfileSettingsPaths) {
|
|
219
248
|
const settingsText = readFileSync(eachPath, 'utf8');
|
|
@@ -224,7 +253,9 @@ export function removeOpenTasksGateFromProfiles(options) {
|
|
|
224
253
|
let removedCount = 0;
|
|
225
254
|
for (const eachGroup of stopGroups) {
|
|
226
255
|
if (!Array.isArray(eachGroup?.hooks)) continue;
|
|
227
|
-
const keptHooks = eachGroup.hooks.filter(
|
|
256
|
+
const keptHooks = eachGroup.hooks.filter(
|
|
257
|
+
(eachHook) => !isGateHook(eachHook, options.claudeHome, allHookRelativePaths),
|
|
258
|
+
);
|
|
228
259
|
removedCount += eachGroup.hooks.length - keptHooks.length;
|
|
229
260
|
eachGroup.hooks = keptHooks;
|
|
230
261
|
}
|
|
@@ -1,16 +1,17 @@
|
|
|
1
1
|
import { test } from 'node:test';
|
|
2
2
|
import { strict as assert } from 'node:assert';
|
|
3
|
-
import { lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
|
|
3
|
+
import { lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
|
|
4
4
|
import { tmpdir } from 'node:os';
|
|
5
5
|
import { dirname, join } from 'node:path';
|
|
6
6
|
import { fileURLToPath } from 'node:url';
|
|
7
7
|
|
|
8
8
|
import { mergeHooksIntoSettings } from './install.mjs';
|
|
9
9
|
|
|
10
|
+
import { ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS } from './install-constants.mjs';
|
|
10
11
|
import {
|
|
11
|
-
|
|
12
|
+
addStopGatesToProfiles,
|
|
12
13
|
otherProfileSettingsPaths,
|
|
13
|
-
|
|
14
|
+
removeStopGatesFromProfiles,
|
|
14
15
|
splitUnreadableProfileSettings,
|
|
15
16
|
unparsedSettingsMayHoldGate,
|
|
16
17
|
} from './profile-stop-gate.mjs';
|
|
@@ -28,6 +29,26 @@ function makeHome(context) {
|
|
|
28
29
|
return { homeDirectory, claudeHome, mainSettingsPath, gateCommand };
|
|
29
30
|
}
|
|
30
31
|
|
|
32
|
+
function makeTwoGateHome(context) {
|
|
33
|
+
const home = makeHome(context);
|
|
34
|
+
const closingGateCommand = `python3 ${join(home.claudeHome, 'hooks', 'blocking', 'closing_question_round_gate.py').replace(/\\/g, '/')}`;
|
|
35
|
+
writeFileSync(home.mainSettingsPath, JSON.stringify({
|
|
36
|
+
hooks: {
|
|
37
|
+
Stop: [{
|
|
38
|
+
hooks: [
|
|
39
|
+
{ type: 'command', command: home.gateCommand, timeout: 10 },
|
|
40
|
+
{ type: 'command', command: closingGateCommand, timeout: 10 },
|
|
41
|
+
],
|
|
42
|
+
}],
|
|
43
|
+
},
|
|
44
|
+
}, null, 4));
|
|
45
|
+
return { ...home, closingGateCommand };
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
function backupFileNames(settingsPath) {
|
|
49
|
+
return readdirSync(dirname(settingsPath)).filter((eachName) => eachName.endsWith('.bak'));
|
|
50
|
+
}
|
|
51
|
+
|
|
31
52
|
function gateTimeouts(settingsPath) {
|
|
32
53
|
const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
|
|
33
54
|
return (settings.hooks?.Stop ?? []).flatMap((eachGroup) => eachGroup.hooks
|
|
@@ -57,7 +78,7 @@ test('every profile with its own settings.json gets the main gate entry', (conte
|
|
|
57
78
|
writeProfile(homeDirectory, 'no-settings');
|
|
58
79
|
|
|
59
80
|
const allProfilePaths = otherProfileSettingsPaths({ homeDirectory, environment: {}, mainSettingsPath });
|
|
60
|
-
|
|
81
|
+
addStopGatesToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: allProfilePaths, homeDirectory });
|
|
61
82
|
|
|
62
83
|
assert.deepEqual(allProfilePaths.sort(), [ownHooksPath, prefsOnlyPath].sort());
|
|
63
84
|
assert.deepEqual(stopCommands(ownHooksPath), ['python3 /opt/own/stop.py', gateCommand]);
|
|
@@ -96,7 +117,7 @@ test('removal through a linked profile settings.json updates the shared file and
|
|
|
96
117
|
throw error;
|
|
97
118
|
}
|
|
98
119
|
|
|
99
|
-
const allChangedPaths =
|
|
120
|
+
const allChangedPaths = removeStopGatesFromProfiles({ claudeHome, allProfileSettingsPaths: [linkedPath] });
|
|
100
121
|
|
|
101
122
|
assert.deepEqual(allChangedPaths, [linkedPath]);
|
|
102
123
|
assert.equal(lstatSync(linkedPath).isSymbolicLink(), true, 'the profile entry is still a link');
|
|
@@ -111,8 +132,8 @@ test('a second run adds nothing, and an older interpreter spelling is replaced',
|
|
|
111
132
|
});
|
|
112
133
|
const options = { mainSettingsPath, claudeHome, allProfileSettingsPaths: [profilePath], homeDirectory };
|
|
113
134
|
|
|
114
|
-
|
|
115
|
-
const secondOutcome =
|
|
135
|
+
addStopGatesToProfiles(options);
|
|
136
|
+
const secondOutcome = addStopGatesToProfiles(options);
|
|
116
137
|
|
|
117
138
|
assert.deepEqual(stopCommands(profilePath), [gateCommand]);
|
|
118
139
|
assert.deepEqual(secondOutcome[0].additions, []);
|
|
@@ -126,7 +147,7 @@ test('replacing an older spelling backs up the file as it was before the replace
|
|
|
126
147
|
});
|
|
127
148
|
const originalText = readFileSync(profilePath, 'utf8');
|
|
128
149
|
|
|
129
|
-
const [outcome] =
|
|
150
|
+
const [outcome] = addStopGatesToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: [profilePath], homeDirectory });
|
|
130
151
|
|
|
131
152
|
assert.equal(readFileSync(outcome.backupPath, 'utf8'), originalText);
|
|
132
153
|
});
|
|
@@ -138,9 +159,9 @@ test('removal takes out only the main gate entry and leaves the profile as it wa
|
|
|
138
159
|
});
|
|
139
160
|
const prefsOnlyPath = writeProfile(homeDirectory, 'prefs-only', { outputStyle: 'plain' });
|
|
140
161
|
const allProfilePaths = [ownHooksPath, prefsOnlyPath];
|
|
141
|
-
|
|
162
|
+
addStopGatesToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: allProfilePaths, homeDirectory });
|
|
142
163
|
|
|
143
|
-
const allChangedPaths =
|
|
164
|
+
const allChangedPaths = removeStopGatesFromProfiles({ claudeHome, allProfileSettingsPaths: allProfilePaths });
|
|
144
165
|
|
|
145
166
|
assert.deepEqual(allChangedPaths, allProfilePaths);
|
|
146
167
|
assert.deepEqual(stopCommands(ownHooksPath), ['python3 /opt/own/stop.py']);
|
|
@@ -154,7 +175,7 @@ test('a profile that already runs its own copy of the gate script gets no second
|
|
|
154
175
|
hooks: { Stop: [{ hooks: [{ type: 'command', command: ownGateCommand }] }] },
|
|
155
176
|
});
|
|
156
177
|
|
|
157
|
-
const allOutcomes =
|
|
178
|
+
const allOutcomes = addStopGatesToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: [profilePath], homeDirectory });
|
|
158
179
|
|
|
159
180
|
assert.deepEqual(allOutcomes, []);
|
|
160
181
|
assert.deepEqual(stopCommands(profilePath), [ownGateCommand]);
|
|
@@ -194,6 +215,172 @@ test('a settings.json that does not parse may hold the gate when its text names
|
|
|
194
215
|
assert.equal(unparsedSettingsMayHoldGate(join(homeDirectory, 'missing', 'settings.json'), claudeHome), true);
|
|
195
216
|
});
|
|
196
217
|
|
|
218
|
+
test('the profile Stop gates are the open tasks gate and then the closing question round gate', () => {
|
|
219
|
+
assert.deepEqual(
|
|
220
|
+
ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS.map((eachRelativePath) => eachRelativePath.join('/')),
|
|
221
|
+
['blocking/open_tasks_stop_gate.py', 'blocking/closing_question_round_gate.py'],
|
|
222
|
+
);
|
|
223
|
+
assert.ok(Object.isFrozen(ALL_PROFILE_STOP_GATE_HOOK_RELATIVE_PATHS));
|
|
224
|
+
});
|
|
225
|
+
|
|
226
|
+
test('a profile gets both main gates, the open tasks gate first, each in its own Stop group', (context) => {
|
|
227
|
+
const { homeDirectory, claudeHome, mainSettingsPath, gateCommand, closingGateCommand } = makeTwoGateHome(context);
|
|
228
|
+
const ownHooksPath = writeProfile(homeDirectory, 'own-hooks', {
|
|
229
|
+
hooks: { Stop: [{ hooks: [{ type: 'command', command: 'python3 /opt/own/stop.py' }] }] },
|
|
230
|
+
});
|
|
231
|
+
|
|
232
|
+
const [outcome] = addStopGatesToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: [ownHooksPath], homeDirectory });
|
|
233
|
+
|
|
234
|
+
assert.deepEqual(stopCommands(ownHooksPath), ['python3 /opt/own/stop.py', gateCommand, closingGateCommand]);
|
|
235
|
+
assert.equal(outcome.additions.length, 2);
|
|
236
|
+
assert.equal(JSON.parse(readFileSync(ownHooksPath, 'utf8')).hooks.Stop.length, 3);
|
|
237
|
+
});
|
|
238
|
+
|
|
239
|
+
test('a profile that already holds the open tasks gate gets only the closing question round gate', (context) => {
|
|
240
|
+
const { homeDirectory, claudeHome, mainSettingsPath, gateCommand, closingGateCommand } = makeTwoGateHome(context);
|
|
241
|
+
const profilePath = writeProfile(homeDirectory, 'holds-open-tasks', {
|
|
242
|
+
hooks: { Stop: [{ hooks: [{ type: 'command', command: gateCommand, timeout: 10 }] }] },
|
|
243
|
+
});
|
|
244
|
+
|
|
245
|
+
const [outcome] = addStopGatesToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: [profilePath], homeDirectory });
|
|
246
|
+
|
|
247
|
+
assert.deepEqual(stopCommands(profilePath), [gateCommand, closingGateCommand]);
|
|
248
|
+
assert.equal(outcome.additions.length, 1);
|
|
249
|
+
assert.ok(outcome.additions[0].includes('closing_question_round_gate.py'));
|
|
250
|
+
});
|
|
251
|
+
|
|
252
|
+
test('a profile that already holds the closing question round gate gets only the open tasks gate', (context) => {
|
|
253
|
+
const { homeDirectory, claudeHome, mainSettingsPath, gateCommand, closingGateCommand } = makeTwoGateHome(context);
|
|
254
|
+
const profilePath = writeProfile(homeDirectory, 'holds-closing-round', {
|
|
255
|
+
hooks: { Stop: [{ hooks: [{ type: 'command', command: closingGateCommand, timeout: 10 }] }] },
|
|
256
|
+
});
|
|
257
|
+
|
|
258
|
+
const [outcome] = addStopGatesToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: [profilePath], homeDirectory });
|
|
259
|
+
|
|
260
|
+
assert.deepEqual(stopCommands(profilePath), [closingGateCommand, gateCommand]);
|
|
261
|
+
assert.equal(outcome.additions.length, 1);
|
|
262
|
+
assert.ok(outcome.additions[0].includes('open_tasks_stop_gate.py'));
|
|
263
|
+
});
|
|
264
|
+
|
|
265
|
+
test('an older spelling of the closing question round gate alone is replaced, the open tasks entry stays, and the backup holds the file as it was', (context) => {
|
|
266
|
+
const { homeDirectory, claudeHome, mainSettingsPath, gateCommand, closingGateCommand } = makeTwoGateHome(context);
|
|
267
|
+
const staleClosingCommand = closingGateCommand.replace(/^python3/, '/usr/bin/python3.9');
|
|
268
|
+
const profilePath = writeProfile(homeDirectory, 'stale-closing', {
|
|
269
|
+
hooks: {
|
|
270
|
+
Stop: [
|
|
271
|
+
{ hooks: [{ type: 'command', command: gateCommand, timeout: 10 }] },
|
|
272
|
+
{ hooks: [{ type: 'command', command: staleClosingCommand }] },
|
|
273
|
+
],
|
|
274
|
+
},
|
|
275
|
+
});
|
|
276
|
+
const originalText = readFileSync(profilePath, 'utf8');
|
|
277
|
+
|
|
278
|
+
const [outcome] = addStopGatesToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: [profilePath], homeDirectory });
|
|
279
|
+
|
|
280
|
+
assert.deepEqual(stopCommands(profilePath), [gateCommand, closingGateCommand]);
|
|
281
|
+
assert.equal(outcome.additions.length, 1);
|
|
282
|
+
assert.equal(readFileSync(outcome.backupPath, 'utf8'), originalText);
|
|
283
|
+
});
|
|
284
|
+
|
|
285
|
+
test('an older spelling of the open tasks gate alone is replaced and the closing question round entry stays', (context) => {
|
|
286
|
+
const { homeDirectory, claudeHome, mainSettingsPath, gateCommand, closingGateCommand } = makeTwoGateHome(context);
|
|
287
|
+
const staleOpenTasksCommand = gateCommand.replace(/^python3/, '/usr/bin/python3.9');
|
|
288
|
+
const profilePath = writeProfile(homeDirectory, 'stale-open-tasks', {
|
|
289
|
+
hooks: {
|
|
290
|
+
Stop: [
|
|
291
|
+
{ hooks: [{ type: 'command', command: staleOpenTasksCommand }] },
|
|
292
|
+
{ hooks: [{ type: 'command', command: closingGateCommand, timeout: 10 }] },
|
|
293
|
+
],
|
|
294
|
+
},
|
|
295
|
+
});
|
|
296
|
+
|
|
297
|
+
const [outcome] = addStopGatesToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: [profilePath], homeDirectory });
|
|
298
|
+
|
|
299
|
+
assert.deepEqual(stopCommands(profilePath), [closingGateCommand, gateCommand]);
|
|
300
|
+
assert.equal(outcome.additions.length, 1);
|
|
301
|
+
});
|
|
302
|
+
|
|
303
|
+
test('a second run with both gates in place adds nothing and writes no second backup', (context) => {
|
|
304
|
+
const { homeDirectory, claudeHome, mainSettingsPath, gateCommand, closingGateCommand } = makeTwoGateHome(context);
|
|
305
|
+
const profilePath = writeProfile(homeDirectory, 'prefs-only', { outputStyle: 'plain' });
|
|
306
|
+
const options = { mainSettingsPath, claudeHome, allProfileSettingsPaths: [profilePath], homeDirectory };
|
|
307
|
+
|
|
308
|
+
addStopGatesToProfiles({ ...options, now: new Date('2030-01-01T00:00:00Z') });
|
|
309
|
+
const [secondOutcome] = addStopGatesToProfiles({ ...options, now: new Date('2030-01-02T00:00:00Z') });
|
|
310
|
+
|
|
311
|
+
assert.deepEqual(stopCommands(profilePath), [gateCommand, closingGateCommand]);
|
|
312
|
+
assert.deepEqual(secondOutcome.additions, []);
|
|
313
|
+
assert.equal(secondOutcome.backupPath, null);
|
|
314
|
+
assert.equal(backupFileNames(profilePath).length, 1);
|
|
315
|
+
});
|
|
316
|
+
|
|
317
|
+
test('removal takes out both main gates and leaves the profile as it was', (context) => {
|
|
318
|
+
const { homeDirectory, claudeHome, mainSettingsPath } = makeTwoGateHome(context);
|
|
319
|
+
const ownHooksPath = writeProfile(homeDirectory, 'own-hooks', {
|
|
320
|
+
hooks: { Stop: [{ hooks: [{ type: 'command', command: 'python3 /opt/own/stop.py' }] }] },
|
|
321
|
+
});
|
|
322
|
+
const prefsOnlyPath = writeProfile(homeDirectory, 'prefs-only', { outputStyle: 'plain' });
|
|
323
|
+
const allProfilePaths = [ownHooksPath, prefsOnlyPath];
|
|
324
|
+
addStopGatesToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: allProfilePaths, homeDirectory });
|
|
325
|
+
|
|
326
|
+
const allChangedPaths = removeStopGatesFromProfiles({ claudeHome, allProfileSettingsPaths: allProfilePaths });
|
|
327
|
+
|
|
328
|
+
assert.deepEqual(allChangedPaths, allProfilePaths);
|
|
329
|
+
assert.deepEqual(stopCommands(ownHooksPath), ['python3 /opt/own/stop.py']);
|
|
330
|
+
assert.deepEqual(JSON.parse(readFileSync(prefsOnlyPath, 'utf8')), { outputStyle: 'plain' });
|
|
331
|
+
});
|
|
332
|
+
|
|
333
|
+
test('removal takes out a closing question round entry from a profile that holds no open tasks entry', (context) => {
|
|
334
|
+
const { homeDirectory, claudeHome, closingGateCommand } = makeTwoGateHome(context);
|
|
335
|
+
const profilePath = writeProfile(homeDirectory, 'closing-only', {
|
|
336
|
+
outputStyle: 'plain',
|
|
337
|
+
hooks: { Stop: [{ hooks: [{ type: 'command', command: closingGateCommand, timeout: 10 }] }] },
|
|
338
|
+
});
|
|
339
|
+
|
|
340
|
+
const allChangedPaths = removeStopGatesFromProfiles({ claudeHome, allProfileSettingsPaths: [profilePath] });
|
|
341
|
+
|
|
342
|
+
assert.deepEqual(allChangedPaths, [profilePath]);
|
|
343
|
+
assert.deepEqual(JSON.parse(readFileSync(profilePath, 'utf8')), { outputStyle: 'plain' });
|
|
344
|
+
});
|
|
345
|
+
|
|
346
|
+
test('a profile that runs its own copy of the open tasks gate still gets the main closing question round gate', (context) => {
|
|
347
|
+
const { homeDirectory, claudeHome, mainSettingsPath, closingGateCommand } = makeTwoGateHome(context);
|
|
348
|
+
const ownGateCommand = `python3 ${join(homeDirectory, '.claude-profiles', 'isolated', 'hooks', 'blocking', 'open_tasks_stop_gate.py').replace(/\\/g, '/')}`;
|
|
349
|
+
const profilePath = writeProfile(homeDirectory, 'isolated', {
|
|
350
|
+
hooks: { Stop: [{ hooks: [{ type: 'command', command: ownGateCommand }] }] },
|
|
351
|
+
});
|
|
352
|
+
|
|
353
|
+
addStopGatesToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: [profilePath], homeDirectory });
|
|
354
|
+
|
|
355
|
+
assert.deepEqual(stopCommands(profilePath), [ownGateCommand, closingGateCommand]);
|
|
356
|
+
});
|
|
357
|
+
|
|
358
|
+
test('a profile that runs its own copy of both gates gets no entry and no outcome', (context) => {
|
|
359
|
+
const { homeDirectory, claudeHome, mainSettingsPath } = makeTwoGateHome(context);
|
|
360
|
+
const ownHooksDirectory = join(homeDirectory, '.claude-profiles', 'isolated', 'hooks', 'blocking');
|
|
361
|
+
const allOwnCommands = ['open_tasks_stop_gate.py', 'closing_question_round_gate.py']
|
|
362
|
+
.map((eachScriptName) => `python3 ${join(ownHooksDirectory, eachScriptName).replace(/\\/g, '/')}`);
|
|
363
|
+
const profilePath = writeProfile(homeDirectory, 'isolated', {
|
|
364
|
+
hooks: { Stop: [{ hooks: allOwnCommands.map((eachCommand) => ({ type: 'command', command: eachCommand })) }] },
|
|
365
|
+
});
|
|
366
|
+
|
|
367
|
+
const allOutcomes = addStopGatesToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: [profilePath], homeDirectory });
|
|
368
|
+
|
|
369
|
+
assert.deepEqual(allOutcomes, []);
|
|
370
|
+
assert.deepEqual(stopCommands(profilePath), allOwnCommands);
|
|
371
|
+
});
|
|
372
|
+
|
|
373
|
+
test('a settings.json that does not parse may hold a gate when its text names only the closing question round script', (context) => {
|
|
374
|
+
const { homeDirectory, claudeHome, closingGateCommand } = makeTwoGateHome(context);
|
|
375
|
+
const closingOnlyPath = writeProfile(homeDirectory, 'closing-only');
|
|
376
|
+
writeFileSync(closingOnlyPath, `{"hooks":{"Stop":[{"hooks":[{"command":"${closingGateCommand}"}]}]},}`);
|
|
377
|
+
const otherHomePath = writeProfile(homeDirectory, 'other-home');
|
|
378
|
+
writeFileSync(otherHomePath, '{"hooks":{"Stop":[{"hooks":[{"command":"python3 /opt/other/.claude/hooks/blocking/closing_question_round_gate.py"}]}]},}');
|
|
379
|
+
|
|
380
|
+
assert.equal(unparsedSettingsMayHoldGate(closingOnlyPath, claudeHome), true);
|
|
381
|
+
assert.equal(unparsedSettingsMayHoldGate(otherHomePath, claudeHome), false);
|
|
382
|
+
});
|
|
383
|
+
|
|
197
384
|
test('should raise a profile gate timeout of 10 to 45 on install', (context) => {
|
|
198
385
|
const { homeDirectory, claudeHome, mainSettingsPath, gateCommand } = makeHome(context);
|
|
199
386
|
const profilePath = writeProfile(homeDirectory, 'older-install', {
|
|
@@ -205,9 +392,12 @@ test('should raise a profile gate timeout of 10 to 45 on install', (context) =>
|
|
|
205
392
|
|
|
206
393
|
mergeHooksIntoSettings(mainSettings, hooksConfig, claudeHome, 'python3', null, homeDirectory);
|
|
207
394
|
writeFileSync(mainSettingsPath, JSON.stringify(mainSettings, null, 4));
|
|
208
|
-
|
|
395
|
+
addStopGatesToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: [profilePath], homeDirectory });
|
|
209
396
|
|
|
210
397
|
assert.deepEqual(gateTimeouts(mainSettingsPath), [45]);
|
|
211
398
|
assert.deepEqual(gateTimeouts(profilePath), [45]);
|
|
212
|
-
assert.deepEqual(
|
|
399
|
+
assert.deepEqual(
|
|
400
|
+
stopCommands(profilePath).filter((eachCommand) => eachCommand.includes('open_tasks_stop_gate.py')),
|
|
401
|
+
[gateCommand],
|
|
402
|
+
);
|
|
213
403
|
});
|
|
@@ -35,7 +35,7 @@ When the host keeps an asks ledger with `ledger.py` and `asks_check.py`, record
|
|
|
35
35
|
|
|
36
36
|
The installer registers `open_tasks_stop_gate.py` as a Stop hook for each host:
|
|
37
37
|
|
|
38
|
-
- Claude Code: `hooks.json`. A block returns the reason, and the session updates its task list and ends the turn. An install into `~/.claude` also adds the same Stop entry to every profile under `~/.claude-profiles` that has its own `settings.json
|
|
38
|
+
- Claude Code: `hooks.json`. A block returns the reason, and the session updates its task list and ends the turn. An install into `~/.claude` also adds the same Stop entry, and the `closing_question_round_gate.py` Stop entry after it, to every profile under `~/.claude-profiles` that has its own `settings.json`. Each gate is added on its own: a profile that holds one gets the other, and a gate the profile already runs from its own copy of the script is skipped. A profile whose `settings.json` links to `~/.claude/settings.json` already has both. Uninstall removes only those two entries. On install, a profile `settings.json` that is not valid JSON is left unchanged and listed under Action needed with its path and parse error, and the rest of the install goes on. On uninstall, such a file that still names either gate stops the uninstall before anything changes, so the manifest stays and a rerun after the fix removes the gates; one that names neither gate is left as it is.
|
|
39
39
|
- Codex: `$CODEX_HOME/hooks.json`. Codex turns the reason into a continuation prompt.
|
|
40
40
|
- Cursor: a native `stop` entry in `~/.cursor/hooks.json`. The reason comes back as `followup_message`, the next user message. A stop with status `aborted` or `error` passes, so a turn the user cancels stays silent.
|
|
41
41
|
|
|
@@ -42,3 +42,4 @@ The SessionStart hook `hooks/session/working_style_prompt.py` points every sessi
|
|
|
42
42
|
- Use a clearly stated low-risk assumption when the intended result remains stable.
|
|
43
43
|
- Pause for the user's choice before making a high-impact decision.
|
|
44
44
|
- Hand the user a step as its own question, with the command block to paste or the link to open inside it. Leave long guides out.
|
|
45
|
+
- End a session the user started with a round of question cards, one for each item it leaves open. Brief every item in chat before the first card. When nothing is open, end the closing reply with the line `Open items: none.`
|
|
@@ -24,6 +24,71 @@ When the user has several items to review or decide, such as test cases, finding
|
|
|
24
24
|
|
|
25
25
|
The limit is 450 words and 15 list or table items of chat text before a question, counted from the start of the question's turn. A turn starts at a message the user types, at an answer or refusal of an earlier question, or at the first input after the previous turn ends, so text from an earlier turn never counts. A Stop hook that holds a reply keeps the turn open, so that reply's text counts. Each bullet or numbered line is one item, and each table row below the header is one item. Lines inside a code fence are not items. On Claude, the `question_brief_gate.py` PreToolUse hook refuses an `AskUserQuestion` call past either limit and names the limit it passed. The hook reads only the last 1 MB of the transcript, so a long review followed by more than 1 MB of tool output in the same turn is not seen. The text has already posted by then, so do not repeat it. Shorten the brief to the context and each choice's effect, or split the question and ask about one item now.
|
|
26
26
|
|
|
27
|
+
## The closing round
|
|
28
|
+
|
|
29
|
+
A session the user started ends with a round of question cards on what it leaves open. When it leaves nothing open, its closing reply ends with this line alone, in plain text: `Open items: none.` On Claude, the `closing_question_round_gate.py` Stop hook holds the stop until the cards or that line follow.
|
|
30
|
+
|
|
31
|
+
### What the gate checks
|
|
32
|
+
|
|
33
|
+
The gate reads the stretch: the session's records after the last question tool call that reached the user, then the payload's `last_assistant_message`. Claude Code runs Stop hooks before it writes the closing reply to the transcript, so the payload holds the newest text. When the transcript already ends with that text, it is read once: its last assistant record, question calls left aside, ends in the same text. A text that sits before a later work call is an older reply, so the payload text is read as new. It holds in two cases.
|
|
34
|
+
|
|
35
|
+
1. The stretch holds an open-item line. The reason quotes the lines. The declaration does not release this hold.
|
|
36
|
+
2. The stretch holds work, no open-item line, and the closing reply does not end with the declaration. Work is any tool call of the main thread other than a question call: an edit, a shell command, a read, or a subagent. Work counts from the last reply in the stretch that ended with the declaration.
|
|
37
|
+
|
|
38
|
+
A stretch with no work and no open-item line passes, so a chat-only answer needs no declaration. A reply that ends with the declaration closes the work before it, so a later turn of chat only needs no declaration. An open-item line written before that reply still holds.
|
|
39
|
+
|
|
40
|
+
Fences, HTML blocks, quoted paragraphs, code spans, and indented code blocks are left out. An indented code block is a run of lines indented by four spaces or a tab after a blank line, outside a list item. Tool inputs, tool results, and thinking are never read.
|
|
41
|
+
|
|
42
|
+
Each paragraph is matched with its single line breaks folded to spaces, so a marker split across a soft line break, such as "out of" and "scope" on the next line, still counts. The reason quotes the line, or the lines the marker spans. A line that holds a deferral, uncertainty, or judgment marker is an open-item line. Markers include "deferred", "follow-up", "parked", "out of scope", "for later", "later pull request", "separate PR", "pending", "TODO", "skipped", "blocked", "not run", "known gap", "open question", "not sure", "I assumed", "unverified", "untested", "did not test", "could not confirm", "not yet implemented", "your call", "up to you", "you may want to", "your judgment", "need your input", and "waiting on you". A line of chat text that ends with a question mark is an open-item line too. A marker reads as a whole word, and one to three underscores around it read as emphasis, so `_untested_` and `__untested__` count, and `retry_untested_flag` and `retry__untested__flag` do not. A marker inside a file name with a short lower-case extension, such as `todo.md`, or inside a path of two or more names that ends in a slash or a file name, such as `docs/pending/`, does not count either. A marker joined to another word, such as `skipped/untested`, and a marker of two or more words, such as `not tested`, still count. The module docstring of `closing_question_round_open_items.py` lists every marker. A negation does not cancel a marker, so "Nothing is deferred." is held. That hold costs one extra card, and the declaration line carries no marker.
|
|
43
|
+
|
|
44
|
+
The declaration counts when the last non-empty line of the reply's prose is `Open items: none.` alone, or that line wrapped in one bold or italic mark. The period may be left out, because a session after a compaction often drops it. It must come after the last work call. Bold and italic pass. The line in backticks, in a list item, in a quote, in a fence, or with more words on it does not.
|
|
45
|
+
|
|
46
|
+
### The stretch
|
|
47
|
+
|
|
48
|
+
A call reached the user when the transcript holds its tool result, matched by `tool_use_id`, and that result is no error. A call a hook refused, a call that errored, and a call with no result yet do not end the stretch, so send the call again after a refusal. A later turn that a task notification starts does not clear what an earlier turn left open. Answers come back in the same turn, so act on them at once. An open-item line written after the cards starts a new stretch, and it needs its own cards. Work after the cards needs the cards or the declaration again.
|
|
49
|
+
|
|
50
|
+
### Sessions the gate leaves alone
|
|
51
|
+
|
|
52
|
+
- A subagent, and a Cursor session.
|
|
53
|
+
- A headless run, where `CLAUDE_CODE_SESSION_ATTENDED` is `0`.
|
|
54
|
+
- A session no person typed into: a `claude -p` run, a session another agent created, or a scheduled run. A prompt a person typed carries `turnOrigin` equal to `human`, and so does a custom slash command. Once a person types a prompt there, the gate covers the session. On a host whose records carry no `turnOrigin` field at all, a session with a prompt counts as started by a person when `CLAUDE_CODE_SESSION_ATTENDED` is `1`.
|
|
55
|
+
- A stop while background work runs: a non-empty `background_tasks` list, object, or string. The session stops again when that work ends, and what it left open carries over.
|
|
56
|
+
- A session whose transcript cannot be read.
|
|
57
|
+
- A stop the gate cannot finish within 7 seconds by its own clock checks. The check runs in a child process, which is killed 8 seconds after the payload read starts, so one long step, such as a JSON parse, cannot keep the stop waiting. A watchdog thread ends a payload read that never finishes at 8.5 seconds. It reads the clock between lines, texts, and windows of each marker scan. A single regular expression pass over one text cannot be cut short, which is why a text over 2 MiB is skipped. In local runs, a 190 MB transcript of short prompt lines took 4.5 seconds, and 160 to 180 MB transcripts that hold many 2 MiB texts of code spans reached the deadline and passed in 7.3 to 7.4 seconds.
|
|
58
|
+
- A stop where the gate itself fails, or where a standard stream is closed or cannot be written. It passes with exit code 0. A hold whose output write has not finished 1 second after it starts, such as a write to a full pipe nobody reads, ends with exit code 0.
|
|
59
|
+
|
|
60
|
+
### Two holds
|
|
61
|
+
|
|
62
|
+
The gate counts its own holds, as feedback records that open with the first sentence of a reason, since the later of the last typed prompt and the last answered question call, and it allows the stop after two. Both reasons count. It checks every stop again, also one a Stop hook already held, so a reply in plain text does not release a hold. A host with no question tool gets two holds and then stops. There, give each open item its own short paragraph in the reply.
|
|
63
|
+
|
|
64
|
+
### How to run a round
|
|
65
|
+
|
|
66
|
+
1. Find the items. Look in the task list, your running notes, worker reports, the "Not covered" section of each pull request body, and your own words in the transcript.
|
|
67
|
+
2. Read the live state of each item, and drop each one that is done.
|
|
68
|
+
3. Write one chat brief before the first call. Say where things stand in two or three lines. Then give each item one short paragraph that names each option label and its effect, with its links. The brief covers every item, because the user answers the first set of cards before the second set shows. `question_brief_gate.py` counts the chat text since the last typed prompt or question result, the held reply included, and refuses a call past 450 words or 15 list or table items. When the held reply is already past that, write a one-line brief and send the cards. That call is refused, and a refused question starts a new count, so send the same cards again at once with no new text.
|
|
69
|
+
4. Send each item as its own question. One call holds at most four questions, so a longer round takes more calls. Give each question a header of 12 characters or fewer and two or three options, with your recommendation first. Give each option a one-sentence description. A card shows plain text, so write a link in a card as a bare URL.
|
|
70
|
+
5. An answer can be free text. Follow what it says, and treat new work it adds as an ask.
|
|
71
|
+
6. Close in plain words with what you did with each answer, and do not restate the items. A reply after the cards that repeats a marker, such as "The backoff setting stays deferred", starts a new stretch and is held. Write "The backoff setting stays as it is" there. When that work leaves nothing open, end with `Open items: none.`
|
|
72
|
+
|
|
73
|
+
When the lines name nothing that is still open, send one question that says so and lets the user add an item.
|
|
74
|
+
|
|
75
|
+
### Limits
|
|
76
|
+
|
|
77
|
+
- The gate holds at most twice per typed prompt or answered card.
|
|
78
|
+
- A marker can hold a line that names no open item, such as a negation or a line about the word itself. That hold costs one card.
|
|
79
|
+
- An item recorded only in the task list or in a file is not seen. The hold reason tells the agent to read those.
|
|
80
|
+
- A card about another subject still ends the stretch.
|
|
81
|
+
- A session whose only prompts came from an agent is not covered.
|
|
82
|
+
- A scheduled wake inside a session a person started is held like any other stop.
|
|
83
|
+
- A payload over 16 MiB passes unread. A transcript line over 16 MiB or a text over 2 MiB is skipped, and a stop the gate cannot finish within 7 seconds passes.
|
|
84
|
+
- The gate counts one of its holds only when the feedback record starts with "Stop hook feedback" and carries the first sentence of the reason in its first 200 characters. A host that writes the feedback in another shape gets a hold on every stop, up to its own limit.
|
|
85
|
+
- Text inside an HTML block is not read.
|
|
86
|
+
- A marker joined to a word by four or more underscores still reads as a marker.
|
|
87
|
+
- A marker joined to a file name by a hyphen, such as `todo-list.md`, still reads as a marker.
|
|
88
|
+
- Text the masking misses reads as prose and can hold, such as an unclosed fence or a quote indented four spaces inside a nested list item.
|
|
89
|
+
- A question call whose id holds a character the transcript escapes outside printable ASCII, such as `"` or `é`, is not matched to its result, so the stretch does not end there. Claude Code writes ids of letters, digits, and underscores.
|
|
90
|
+
- The gate runs on Claude Code only.
|
|
91
|
+
|
|
27
92
|
## Codex visual comparisons
|
|
28
93
|
|
|
29
94
|
For Codex visual comparisons, find Page creation, visualization upload, and Page opening tools. Create the comparison, upload its visualization, and open its Page here before asking. If tools are missing, steps fail, or opening queues, compare in chat before asking. Put inline Visualize references only in final replies. An async acknowledgement or saved visual is context only; wait for and use the submitted answer before dependent work.
|
|
@@ -7,6 +7,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
|
|
|
7
7
|
- `blocking/final_reply_gate.py` checks 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.
|
|
8
8
|
- `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 also holds the turn once when completed items sit beside open ones on the task list the user sees: the session's task store, or the transcript's list when the session has no store. A list that `CLAUDE_CODE_TASK_LIST_ID` shares with other sessions is left alone. It also holds the turn once when the closing reply, or a Markdown, text, or HTML file the turn sent with `SendUserFile`, says something waits on the user and the turn ran no read call or sent no question tool call. `blocking/user_step_wording.py` finds that wording: phrases such as "needs you", "waiting on you", "you need to", and "say when", outside fences, quotes, and code spans, unless a negation on the same line covers the phrase ("Nothing here needs you", "This change does not need you") or the phrase is a label with nothing under it ("Action required: none."). The module docstring of `blocking/user_step_wording.py` names each skip shape. Every other wording is held, because a wrong hold costs the agent one step and a wrong skip hides a step from the user. "Say when" counts only at the start of its clause. Markdown and plain text are read one paragraph at a time. In an HTML file it reads the text one block at a time, counts white space in the source as one space and a `br` as a line break, and leaves out the contents of `script`, `style`, `template`, `title`, `textarea`, `noscript`, `code`, `pre`, and `blockquote` elements; text under a hidden attribute still counts. It skips a sent path that is no regular file and a file over 256 KB, and reads a path sent twice once. A read call is a shell, a file or web read, a subagent, a Codex `local_shell_call`, or a tool whose name carries a read word such as `get`, `list`, or `read` and no write word such as `update` or `append`. Only the part of an MCP tool name after the server is read, and it is split into words at underscores, hyphens, and a capital that follows a lower-case letter or a digit. `TaskList`, `TaskGet`, `ToolSearch`, and the question tools do not count. The gate checks that a read ran and leaves which item it read to the agent, so each such hold tells the agent to read the live state of every item it shows as open, and to end the turn when the wording hands the user no step. It also holds the turn once on two closing-reply faults: a promised later report, and open decisions listed in chat. On a Claude Code stop with `claude` on PATH, `blocking/closing_reply_judge.py` judges them with one model call. A Codex or Cursor stop, or a Claude Code stop with no `claude` on PATH, uses two closing-reply shapes that `blocking/closing_reply_shapes.py` finds outside fences, HTML blocks, quotes, and code spans. The first is a promised later report, such as "will be posted when you get back" or "I'll report back once CI ends", that no typed prompt in the turn asked for. The second is a run of 3 or more bullets, numbered lines, or table body rows under a lead that names open work, such as "What I deferred" or "Next steps", when the turn sent no question tool call. The lead loses its code spans and double-quoted text first, and a lead whose every open-work word has a completion word such as "fixed", "passed", or "merged" in its clause names done work and passes ("I fixed the three follow-ups you flagged:"). A prompt asks for a report or a list only outside its `<system-reminder>` blocks, `>` quoted lines, code spans, and double-quoted text that holds a space, and only when no negator comes before the ask in its clause; a harness envelope never asks. The module docstring of `blocking/closing_reply_shapes.py` names each pattern. Such a hold names what it found and the steps, then one line that ends the turn, then the narrow conditions under which the reply may stay as it is. Two shapes are known costs and still hold: a reply that waits on a run and says so, such as "The lint job is still running, and I'll report once it finishes.", and "Results will land once CI ends."; the keep condition in the reason tells the agent to leave such a reply as it is. One reason carries every finding. A Claude Code stop that another Stop hook already held still gets the two closing reply findings, at most once per turn. A marker file named for the session and the `uuid` of the turn's prompt record keeps that count, and a `Stop hook feedback` record from this gate in the turn also ends it. A Codex turn, a Cursor payload, a prompt record with no `uuid`, or a marker that cannot be written keeps the old skip, and the tracker and user-step checks stay off such a stop. `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.
|
|
9
9
|
- The judge module `blocking/closing_reply_judge.py` asks `claude -p --model haiku --effort medium` whether a closing reply promises the user a later report or lists open decisions in chat. `open_tasks_stop_gate.py` calls it. The prompt goes on stdin with the turn's prompt kind and text, the reply, and whether the turn called the question tool. A task notification sends only its summary, and a slash command sends its name and arguments. The child runs in a new empty folder with no tools, hooks, MCP servers, CLAUDE.md files or auto memory, with `CLAUDE_TURN_REVIEW_CHILD=1` and none of the parent session's variables. A verdict counts only when it is the four-key JSON object, and each raised flag names a span found in the reply. The list flag drops when the turn called the question tool or the prompt asked for a list. A hold quotes the span. The judge fails open: a timeout, a start failure, an exit code other than 0, an answer that is not the verdict shape, a span not in the reply, an unreadable transcript, or a turn with no prompt `uuid` gives no closing-reply finding and one line in `~/.claude/logs/closing-reply-judge.log`. It makes at most one call per turn: a stop after a closing-reply hold in the same turn makes none, and a judge child's own stop passes at once. A reply that waits on a running agent and says it will report, such as "The lint job is still running, and I'll report once it finishes.", is held at times; that cost is known.
|
|
10
|
+
- `blocking/closing_question_round_gate.py` holds the end of a turn in a session a person started in two cases: the stretch holds an open-item line, or the stretch holds work, no open-item line, and the closing reply does not end with the line `Open items: none.`. The stretch is each main-thread record after the last `AskUserQuestion`, hearthbot decision card, or Codex `request_user_input` call that reached the user, across turns, then the payload's `last_assistant_message`, because Claude Code runs Stop hooks before it writes the closing reply; a closing reply the transcript already ends with is read once. A call reached the user when the transcript holds its `tool_result`, matched by `tool_use_id`, with no truthy `is_error`, so a refused call, an errored call, and a call with no result leave earlier items owed. Work is any assistant `tool_use` in the stretch whose name is not a question tool. Fences, HTML blocks, quoted paragraphs, code spans, and indented code blocks are left out, and each paragraph is matched with its single line breaks folded to spaces, so a marker split across a soft line break counts. A line is an open-item line when it holds a deferral, uncertainty, or judgment marker such as "deferred", "follow-up", "parked", "out of scope", "separate PR", "pending", "TODO", "skipped", "blocked", "not run", "not sure", "I assumed", "untested", "did not test", "could not confirm", "not yet implemented", "you may want to", "your judgment", "need your input", "waiting on you", or "up to you", or when it ends with a question mark. A one-word marker inside a file name with a short lower-case extension, such as `todo.md`, or inside a path of two or more names that ends in a slash or such a file name, such as `docs/pending/`, does not count, and a marker joined to another word, such as `skipped/untested`, does. A negation does not cancel a marker, so "Nothing is deferred." is held, because a wrong hold costs one extra card. The declaration counts when the reply's last non-empty prose line is `Open items: none.` alone or wrapped in one bold or italic mark, after the last work call, and it does not excuse an open-item line. `blocking/closing_question_round_open_items.py` finds the open-item lines and the declaration, and its module docstring lists every marker. `blocking/closing_question_round_transcript.py` reads the transcript for it: the last typed prompt, the stretch, its work calls, its assistant texts, and the closing reply. `blocking/closing_question_round_lines.py` reads the transcript's lines with a clock check before each one. Tool inputs, tool results, thinking blocks, and sidechain records are not read. An open-item hold quotes the last 8 such lines at most, each cut to 160 characters, and counts the earlier ones; a work hold quotes nothing. Each reason tells the agent to read the task list, its notes, and the live state of each item, brief every item that still stands, send each one as its own `AskUserQuestion` question, write a link in a card as a bare URL, and then close with what it did with each answer and the declaration line. The gate counts its own holds since the later of the last typed prompt and the last answered question call, and allows the stop after two. It does not read `stop_hook_active`. It passes a subagent stop, a Cursor stop, a headless run (`CLAUDE_CODE_SESSION_ATTENDED` is `0`), a stop with a non-empty `background_tasks` list, object, or string, an unreadable payload or transcript, and a transcript with no prompt whose `turnOrigin` is `human`. When no record carries a `turnOrigin` key at all, a transcript with a prompt counts as started by a person when `CLAUDE_CODE_SESSION_ATTENDED` is `1`. It passes a payload over 16 MiB unread, parses only the lines a substring scan picks, after it spells out a line's `\u0020` to `\u007f` escapes and drops a leading byte order mark, skips a transcript line over 16 MiB or a text over 2 MiB, reads the clock between lines, texts, and marker scan windows, and passes with no output once 7 seconds pass on a monotonic clock or any step raises. The check runs in a child process that is killed 8 seconds after the payload read starts, and a watchdog thread ends a payload read that never finishes at 8.5 seconds; both allow the stop. A closed standard stream or one that cannot be written allows the stop with exit code 0, and so does an output write that has not finished 1 second after it starts. Limits: text inside an HTML block is not read; an item recorded only in the task list or a file is not seen, so the reason tells the agent to read those; a card about another subject still ends the stretch; a session whose only prompts came from an agent is not covered; a scheduled wake inside a session a person started is held like any other stop; a long transcript can pass at the deadline.
|
|
10
11
|
- `session/tracking_nudge.py` adds one `additionalContext` note to a prompt that asks for work. The note asks for an item in the session's task list tool. It shows on the session's first ask and on the first ask after each compaction, through `once_per_session.py`. When the title shows the red flag or the check mark, it also asks for the hourglass before other work. In a session that has a `__set_session_title` tool and no title yet, it asks once for a first title in the `⏳ <name>` form, and never again in that session, compactions included, through `once_per_session.claim_only_showing`. On a turn that an event starts, with no message from the user, it adds one wake note while the title shows the red flag. The note names that title and asks for the status that fits now if the event cleared what the user had to do. It shows on each such prompt and on no other title. The hook runs only when a prompt starts a turn, so a notification that reaches the agent in the middle of a turn gets no note. `tracking_nudge.is_event_wake` counts a prompt as an event only when it opens with one `<task-notification>` envelope with a bare opening tag, or one `<agent-message>` whose opening tag has `from` as its only attribute, both in lower case, with nothing after it but `<system-reminder>` blocks. A sender that is empty or `human`, in any letter case and with white space around it ignored, is no event. The first closing tag ends the envelope, so a body that quotes its own closing tag reads as typed text after the envelope and gets no wake note. A `<wake reason="external-event">` envelope, a plain `[SYSTEM NOTIFICATION - NOT USER INPUT]` prompt, two envelopes in one prompt, an envelope with a lead line before it, and an opening tag with another attribute or letter case get no wake note. Of these, a prompt with a lead line, a plain system notification prompt, and a tag in another letter case can still get the ask notes when they ask for work. `session_title_transcript.py` reads the title tool and the shown title from the transcript. It never blocks. No hook holds the end of a turn for the title.
|
|
11
12
|
- `session/background_silence_prompt.py` adds one `additionalContext` note to a background event prompt, one that starts with `<task-notification>` or opens itself or a `<system-reminder>` block with `[SYSTEM NOTIFICATION - NOT USER INPUT]`, while the user asked for silence. The newest user-typed message that sets silence ("silent unless", "stay silent", "silent on updates", "no updates unless") or lifts it ("you can talk again", "updates are fine", "stop being silent") decides. The note quotes the user's "unless" or "except" clause word for word, or the whole message when it has no such clause, and says to end the turn with no text unless that exception applies now. Envelope prompts, compaction summaries, and quoted `>` lines are not the user's words. It never blocks.
|
|
12
13
|
- 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 plain claims 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.
|
|
@@ -35,6 +36,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
|
|
|
35
36
|
|
|
36
37
|
- `blocking/final_reply_gate.py` runs on `Stop`, timeout `10` seconds in `hooks.json`.
|
|
37
38
|
- `blocking/open_tasks_stop_gate.py` runs on `Stop`, timeout `45` seconds in `hooks.json`, so the judge call has room for its own 35 second timeout. The installer raises a profile's older 10 second entry to 45. The installer also registers it on Codex `Stop` and as a native Cursor `stop` entry in `~/.cursor/hooks.json`, where a block also returns `followup_message`. A Cursor stop with status `aborted` or `error` passes. A Cursor stop whose `loop_count` is above 0 passes, because a copy Cursor imports from `~/.claude/settings.json` has no follow-up limit.
|
|
39
|
+
- `blocking/closing_question_round_gate.py` runs on `Stop`, timeout `10` seconds in `hooks.json`. It runs on Claude Code only. The installer registers it for no other host, and a Cursor stop that reaches it through an imported `~/.claude/settings.json` passes. An install into `~/.claude` also adds its Stop entry to every profile under `~/.claude-profiles` that has its own `settings.json`, beside the open tasks entry, and uninstall removes it; `bin/profile-stop-gate.mjs` handles each gate on its own.
|
|
38
40
|
- `session/tracking_nudge.py` runs on `UserPromptSubmit`, matcher empty, timeout `10` seconds in `hooks.json`.
|
|
39
41
|
- `session/background_silence_prompt.py` runs on `UserPromptSubmit`, matcher empty, timeout `10` seconds in `hooks.json`. It reads the transcript only for a background event prompt.
|
|
40
42
|
- The claim judge runs on `PreToolUse`, matcher `mcp__hearthbot__reply|mcp__hearthbot__post_message|mcp__hearthbot__update_message|mcp__hearthbot__ask_decision`, timeout `30` seconds in `hooks.json`.
|
|
@@ -68,6 +70,7 @@ Preconditions:
|
|
|
68
70
|
- **Resolve reply.** Input is a transcript where a thread reply came back refused, or with no reply, or with one reply already spent on a resolve, or with a reply on another thread, then a resolve call, a `pull_request_review_write` `resolve_thread` call, a graphql `resolveReviewThread` command, or a `ccr/comments/<id>/resolve` call. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_resolve_thread_reply_gate.py -q`. The adjacent test observes a deny whose reason says to post the reply, confirm it posted, then resolve. A reply that posted before the resolve passes, and an unreadable transcript passes.
|
|
69
71
|
- **Final reply.** Input is a closing reply. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_final_reply_gate.py -q`. The adjacent test observes a `block` decision for a path in plain text. A reply with a plain-text `D:\Reports\.claude\report.html` is blocked; the same path in backticks or a fenced block passes.
|
|
70
72
|
- **Open tasks.** Input is a transcript whose last prompt asks for work and whose turn ran a Bash call and no tracker call. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_open_tasks_stop_gate.py -q`. The adjacent test observes one `block` decision; the same turn with a TaskCreate, TaskUpdate, TodoWrite, or desktop plan call passes. A question, an acknowledgement, a `<task-notification>` envelope, a tool-free turn, and a held stop pass. The same file covers Codex and Cursor payloads. To drive the two holds on a reply that ends the turn, feed a turn whose reply says "will be posted when you get back", or lists 5 items under "What I deferred" with no question call; each observes one `block` decision whose reason opens with "The closing reply". The same list after an `AskUserQuestion` call, and the promise after the prompt "report back when the run ends", pass. `python -m pytest packages/claude-dev-env/hooks/blocking/test_closing_reply_shapes.py -q` runs the detector rows. Those gate tests keep `claude` off PATH. `python -m pytest packages/claude-dev-env/hooks/blocking/test_closing_reply_judge.py -q` runs the judge with a stub `claude`, and the judge tests in `test_open_tasks_stop_gate.py` drive the gate with it: a promise verdict, a list verdict, a timeout, a second stop, a judge child's stop, and Codex and Cursor payloads. `python3 .claude/hillclimb/closing-reply-judge/run.py --model haiku --effort medium --runs 3` measures the live model on 208 made-up cases, and `run.py --score` prints each bar.
|
|
73
|
+
- **Closing round.** Input is a transcript with a typed prompt and an assistant line that says "I deferred the backoff setting to a later change." Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_closing_question_round_gate.py packages/claude-dev-env/hooks/blocking/test_closing_question_round_gate_work.py -q`. The adjacent test observes one `block` decision whose reason quotes that line; the same transcript with an answered `AskUserQuestion` call after the line passes, a refused, errored, or unanswered call is held, and a line written after the call is held again, also when only the payload's closing reply holds it. A transcript with an `Edit` call and the reply "Done." is held with the work reason, and the same transcript ending with `Open items: none.` passes; the declaration in backticks or not on the last line is held. A marker inside a fence, quote, code span, indented code block, tool input, or tool result, a subagent, a headless run, a session no person typed into, a stop with background work, a third stop after two holds, a passed deadline, and an internal error pass. The eval runs the hook as its own process on 75 labelled transcripts: `python .claude/hillclimb/closing-question-round-gate/run.py` prints one row per case and `passed 75/75`.
|
|
71
74
|
- **Ask nudge.** Input is a `UserPromptSubmit` payload with a work prompt, a question, and a `<task-notification>` envelope, after a transcript whose title shows the red flag. Run `python -m pytest packages/claude-dev-env/hooks/session/test_tracking_nudge.py -q`. The adjacent test observes a task list note and a title note for the work prompt, empty stdout for the question, and the wake note alone for the envelope. The wake note also shows for a queued `<agent-message>` hand-back. A check mark, hourglass, or construction sign title, a session without the title tool, typed text after the envelope, a body that quotes its own closing tag, two envelopes in one prompt, a mention wake, an empty prompt, and a prompt of only reminder blocks get empty stdout. A second ask in the same session gets no task list note until the transcript records a compaction.
|
|
72
75
|
- **Background silence.** Input is a `UserPromptSubmit` payload whose prompt is a `<task-notification>` envelope, after a transcript whose user message reads "Silent on updates unless something merges or youre blocked". Run `python -m pytest packages/claude-dev-env/hooks/session/test_background_silence_prompt.py -q`. The adjacent test observes a note that quotes "unless something merges or youre blocked", and empty stdout for a user-typed prompt, after a lift, and with no silence message.
|
|
73
76
|
- **Claim judge.** Input is a headless `claude -p` session with a stub MCP server named `hearthbot` that exposes `reply` and `ask_decision`, told to send "The code lets any of them rewrite it mid-check." The session settings add the `hooks.json` prompt hook. The stub logs zero bytes sent, and the tool error reads `PreToolUse:mcp__hearthbot__reply hook error: [<the prompt>]: Facts with no source: 1. ...`, numbering every failing claim. The same sentence with a `file:line` in backticks posts. A hook whose `model` Claude Code does not recognize lets every message through, so leave `model` unset. Run `node --test packages/claude-dev-env/bin/install.prompt-hook.test.mjs` for the installer side; it observes one managed prompt hook after two installs and none after uninstall.
|
package/hooks/hooks.json
CHANGED
|
@@ -495,6 +495,11 @@
|
|
|
495
495
|
"command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/auto_mode_refusal_stop_gate.py",
|
|
496
496
|
"timeout": 10
|
|
497
497
|
},
|
|
498
|
+
{
|
|
499
|
+
"type": "command",
|
|
500
|
+
"command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/closing_question_round_gate.py",
|
|
501
|
+
"timeout": 10
|
|
502
|
+
},
|
|
498
503
|
{
|
|
499
504
|
"type": "command",
|
|
500
505
|
"command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/turn_review_gate.py",
|
package/package.json
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
# Present questions clearly
|
|
2
2
|
|
|
3
|
-
Before every ask, repeats too,
|
|
3
|
+
Before every ask, repeats too, brief in chat: context, each choice's effect, visuals.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
One question per item, no chat list: two or three choices, each a label and sentence. Reuse labels in brief, comparison, picker. Cap a turn's pre-question chat at 450 words and 15 list or table items; a Claude hook refuses more.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Question tools: Claude `AskUserQuestion`, Codex `request_user_input_async` or `request_user_input`. Honor mode rules. Its fields hold question and choices; if unusable, ask in chat.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
End a user-started session with a card per open item or end on `Open items: none.`; a Claude hook holds the stop.
|
|
10
|
+
|
|
11
|
+
Read the full text for a step handover, option cards, or Codex visual comparison.
|
|
10
12
|
|
|
11
13
|
**Full text:** [`~/.claude/docs/rule-guides/question-presentation.md`](../docs/rule-guides/question-presentation.md).
|
|
@@ -25,7 +25,7 @@ import shutil
|
|
|
25
25
|
import subprocess
|
|
26
26
|
import sys
|
|
27
27
|
import tempfile
|
|
28
|
-
from pathlib import Path
|
|
28
|
+
from pathlib import Path, PureWindowsPath
|
|
29
29
|
|
|
30
30
|
from dev_env_scripts_constants.gh_artifact_upload_constants import (
|
|
31
31
|
ALL_OXIPNG_LOSSLESS_ARGUMENTS,
|
|
@@ -123,7 +123,7 @@ def ensure_artifacts_release(repository: str) -> None:
|
|
|
123
123
|
|
|
124
124
|
|
|
125
125
|
def timestamped_asset_name(file_path: str) -> str:
|
|
126
|
-
"""Return ``YYYYMMDD_HHMMSS_<basename>`` for
|
|
126
|
+
"""Return ``YYYYMMDD_HHMMSS_<basename>`` for a path with either slash direction.
|
|
127
127
|
|
|
128
128
|
Args:
|
|
129
129
|
file_path: The source file to be uploaded.
|
|
@@ -133,7 +133,7 @@ def timestamped_asset_name(file_path: str) -> str:
|
|
|
133
133
|
"""
|
|
134
134
|
current_timestamp = datetime.datetime.now().strftime(ASSET_NAME_TIMESTAMP_FORMAT)
|
|
135
135
|
return ASSET_NAME_TEMPLATE.format(
|
|
136
|
-
timestamp=current_timestamp, basename=
|
|
136
|
+
timestamp=current_timestamp, basename=PureWindowsPath(file_path).name
|
|
137
137
|
)
|
|
138
138
|
|
|
139
139
|
|
|
@@ -144,6 +144,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
|
|
|
144
144
|
hooks/blocking/final_reply_gate.py -> exempt
|
|
145
145
|
hooks/blocking/open_tasks_stop_gate.py -> exempt
|
|
146
146
|
hooks/blocking/auto_mode_refusal_stop_gate.py -> exempt
|
|
147
|
+
hooks/blocking/closing_question_round_gate.py -> exempt
|
|
147
148
|
hooks/blocking/resolve_thread_reply_gate.py -> exempt
|
|
148
149
|
hooks/blocking/turn_review_gate.py -> exempt
|
|
149
150
|
hooks/blocking/wakeup_cap_gate.py -> exempt
|
|
@@ -211,6 +212,11 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
|
|
|
211
212
|
step waits on the user's question or on its rule. It decides when a turn
|
|
212
213
|
may end and no code or safety policy.
|
|
213
214
|
|
|
215
|
+
The closing question round Stop gate holds the end of a turn when a
|
|
216
|
+
session a person started wrote about an open item and sent no question
|
|
217
|
+
card after it. It decides when a turn may end and no code or safety
|
|
218
|
+
policy.
|
|
219
|
+
|
|
214
220
|
The resolve reply gate denies a review thread resolve until a reply on the
|
|
215
221
|
thread has posted. It decides the order of two review calls and no code or
|
|
216
222
|
safety policy.
|
|
@@ -83,6 +83,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
|
|
|
83
83
|
"blocking/final_reply_gate.py",
|
|
84
84
|
"blocking/open_tasks_stop_gate.py",
|
|
85
85
|
"blocking/auto_mode_refusal_stop_gate.py",
|
|
86
|
+
"blocking/closing_question_round_gate.py",
|
|
86
87
|
"blocking/resolve_thread_reply_gate.py",
|
|
87
88
|
"blocking/turn_review_gate.py",
|
|
88
89
|
"blocking/wakeup_cap_gate.py",
|
|
@@ -98,6 +98,14 @@ def test_new_auto_mode_refusal_stop_gate_registration_is_clean(tmp_path: Path) -
|
|
|
98
98
|
assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
|
|
99
99
|
|
|
100
100
|
|
|
101
|
+
def test_new_closing_question_round_gate_registration_is_clean(tmp_path: Path) -> None:
|
|
102
|
+
current_document = _hook_document(
|
|
103
|
+
["hooks/blocking/closing_question_round_gate.py"],
|
|
104
|
+
'{"hooks": {}}',
|
|
105
|
+
)
|
|
106
|
+
assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
|
|
107
|
+
|
|
108
|
+
|
|
101
109
|
def test_new_step_note_gate_registration_is_clean(tmp_path: Path) -> None:
|
|
102
110
|
current_document = _hook_document(
|
|
103
111
|
["hooks/blocking/step_note_gate.py"],
|
|
@@ -70,6 +70,24 @@ def test_timestamped_asset_name_prefixes_basename() -> None:
|
|
|
70
70
|
assert len(asset_name) > len("_contact_sheet.png")
|
|
71
71
|
|
|
72
72
|
|
|
73
|
+
@pytest.mark.parametrize(
|
|
74
|
+
"source_path",
|
|
75
|
+
[
|
|
76
|
+
r"C:\stage\nested\contact_sheet.png",
|
|
77
|
+
"/stage/nested/contact_sheet.png",
|
|
78
|
+
"C:/stage/nested/contact_sheet.png",
|
|
79
|
+
],
|
|
80
|
+
)
|
|
81
|
+
def test_timestamped_asset_name_should_keep_only_the_basename_for_either_slash(
|
|
82
|
+
source_path: str,
|
|
83
|
+
) -> None:
|
|
84
|
+
asset_name = mod.timestamped_asset_name(source_path)
|
|
85
|
+
date_part, time_part, basename = asset_name.split("_", 2)
|
|
86
|
+
assert date_part.isdigit()
|
|
87
|
+
assert time_part.isdigit()
|
|
88
|
+
assert basename == "contact_sheet.png"
|
|
89
|
+
|
|
90
|
+
|
|
73
91
|
def test_upload_artifact_returns_the_readback_url(
|
|
74
92
|
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
|
|
75
93
|
) -> None:
|