claude-dev-env 8.114.4 → 8.114.6

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.
@@ -2,7 +2,7 @@
2
2
 
3
3
  Every agent that spawns a subagent, thread, or session owns that work until it reaches the user.
4
4
  Agents make mistakes. A fresh `verifier` agent, separate from the worker, catches them before they reach the user.
5
- The `spawn_oversight_hook` adds this duty to every spawn, at every level of the tree.
5
+ The `spawn_oversight_hook` adds this duty to the first spawn of each agent in the tree, and again after a compaction.
6
6
 
7
7
  - Run each piece through the verified-work flow in `~/.claude/docs/rule-guides/verified-work.md`: research, verify, plan, verify, implement, verify.
8
8
  - Brief each worker with the user's own words, the standards that apply, and the acceptance check.
@@ -0,0 +1,189 @@
1
+ export const EVER_REGISTERED_HOOK_RELATIVE_PATHS = new Set([
2
+ 'advisory/auto_mode_denial_quick_fix.py',
3
+ 'advisory/instruction_file_write_warning.py',
4
+ 'advisory/migration-safety-advisor.py',
5
+ 'advisory/migration_safety_advisor.py',
6
+ 'advisory/msys_path_conversion_advisor.py',
7
+ 'advisory/owned_pr_review_loop.py',
8
+ 'advisory/pieces_per_level_note.py',
9
+ 'advisory/refactor-guard.py',
10
+ 'advisory/refactor_guard.py',
11
+ 'blocking/agent-execution-intent-gate.py',
12
+ 'blocking/artifact_dark_mode_gate.py',
13
+ 'blocking/artifact_look_gate.py',
14
+ 'blocking/ask_user_question_shape_blocker.py',
15
+ 'blocking/ask_user_question_style_blocker.py',
16
+ 'blocking/bash_post_call_dispatcher.py',
17
+ 'blocking/bash_pre_tool_use_dispatcher.py',
18
+ 'blocking/block-main-commit.py',
19
+ 'blocking/block_main_commit.py',
20
+ 'blocking/bot_mention_comment_blocker.py',
21
+ 'blocking/build_eval_before_eval_write_gate.py',
22
+ 'blocking/chat_reply_gate.py',
23
+ 'blocking/claude_md_orphan_file_blocker.py',
24
+ 'blocking/code-rules-enforcer.py',
25
+ 'blocking/code_review_pr_create_gate.py',
26
+ 'blocking/code_rules_enforcer.py',
27
+ 'blocking/code_verifier_spawn_preflight_gate.py',
28
+ 'blocking/content-search-to-zoekt-redirector.py',
29
+ 'blocking/content_search_to_zoekt_redirector.py',
30
+ 'blocking/conventional_pr_title_gate.py',
31
+ 'blocking/convergence_gate_blocker.py',
32
+ 'blocking/cursor_cli_python_misfire_blocker.py',
33
+ 'blocking/destructive-command-blocker.py',
34
+ 'blocking/destructive_command_blocker.py',
35
+ 'blocking/docker-settings-guard.py',
36
+ 'blocking/docstring_rule_gate_count_blocker.py',
37
+ 'blocking/duplicate_rmtree_helper_blocker.py',
38
+ 'blocking/edit_marker_gate.py',
39
+ 'blocking/env_var_table_code_drift_blocker.py',
40
+ 'blocking/es_exe_path_rewriter.py',
41
+ 'blocking/fable_spawn_gate.py',
42
+ 'blocking/final_reply_gate.py',
43
+ 'blocking/gate_question_default_gate.py',
44
+ 'blocking/gh_body_arg_blocker.py',
45
+ 'blocking/gh_pr_author_enforcer.py',
46
+ 'blocking/gh_pr_author_restore.py',
47
+ 'blocking/haiku_spawn_slim_gate.py',
48
+ 'blocking/hedging-language-blocker.py',
49
+ 'blocking/hedging_language_blocker.py',
50
+ 'blocking/hook_prose_detector_consistency.py',
51
+ 'blocking/image_read_size_gate.py',
52
+ 'blocking/intent_only_ending_blocker.py',
53
+ 'blocking/issue_close_handoff_gate.py',
54
+ 'blocking/luna_fast_mode_gate.py',
55
+ 'blocking/md_to_html_blocker.py',
56
+ 'blocking/merge_over_review_offer_gate.py',
57
+ 'blocking/merge_review_gate.py',
58
+ 'blocking/nas_ssh_binary_enforcer.py',
59
+ 'blocking/open_questions_in_plans_blocker.py',
60
+ 'blocking/open_tasks_stop_gate.py',
61
+ 'blocking/orchestrator_refresh_reschedule_gate.py',
62
+ 'blocking/owned_pr_merge_stop_gate.py',
63
+ 'blocking/package_inventory_stale_blocker.py',
64
+ 'blocking/parallel-task-blocker.py',
65
+ 'blocking/parallel_task_blocker.py',
66
+ 'blocking/pii_prevention_blocker.py',
67
+ 'blocking/piped_pytest_blocker.py',
68
+ 'blocking/plain_language_blocker.py',
69
+ 'blocking/pr-description-enforcer.py',
70
+ 'blocking/pr_converge_bugteam_enforcer.py',
71
+ 'blocking/pr_description_enforcer.py',
72
+ 'blocking/pr_description_writer_gate.py',
73
+ 'blocking/pr_lifecycle_skill_gate.py',
74
+ 'blocking/pre_tool_use_dispatcher.py',
75
+ 'blocking/precommit_code_rules_gate.py',
76
+ 'blocking/prompt-workflow-stop-guard.py',
77
+ 'blocking/pyautogui-scroll-blocker.py',
78
+ 'blocking/pyautogui_scroll_blocker.py',
79
+ 'blocking/pytest_testpaths_orphan_blocker.py',
80
+ 'blocking/question_to_user_enforcer.py',
81
+ 'blocking/reply_length_gate.py',
82
+ 'blocking/resolve_thread_reply_gate.py',
83
+ 'blocking/reviewer_spawn_gate.py',
84
+ 'blocking/route_review_spawn_permit.py',
85
+ 'blocking/send_user_file_open_locally_blocker.py',
86
+ 'blocking/send_user_file_worktree_root_gate.py',
87
+ 'blocking/sensitive-file-protector.py',
88
+ 'blocking/sensitive_file_protector.py',
89
+ 'blocking/session_edit_stage_gate.py',
90
+ 'blocking/session_handoff_blocker.py',
91
+ 'blocking/session_title_format_gate.py',
92
+ 'blocking/session_title_stop_gate.py',
93
+ 'blocking/session_title_turn_gate.py',
94
+ 'blocking/shell_substitution_blocker.py',
95
+ 'blocking/state_description_blocker.py',
96
+ 'blocking/step_note_gate.py',
97
+ 'blocking/stop_dispatcher.py',
98
+ 'blocking/subagent_model_gate.py',
99
+ 'blocking/subagent_model_routing.mjs',
100
+ 'blocking/subprocess_budget_completeness.py',
101
+ 'blocking/tdd-enforcer.py',
102
+ 'blocking/tdd_enforcer.py',
103
+ 'blocking/test-preflight-check.py',
104
+ 'blocking/test_preflight_check.py',
105
+ 'blocking/transcript_root_search_gate.py',
106
+ 'blocking/turn_review_gate.py',
107
+ 'blocking/unscoped_search_blocker.py',
108
+ 'blocking/verdict_directory_write_blocker.py',
109
+ 'blocking/verified_commit_gate.py',
110
+ 'blocking/verified_commit_message_accuracy_blocker.py',
111
+ 'blocking/verifier_verdict_minter.py',
112
+ 'blocking/verify_before_acting.py',
113
+ 'blocking/verify_before_commit_gate.py',
114
+ 'blocking/volatile_path_in_post_blocker.py',
115
+ 'blocking/wakeup_cap_gate.py',
116
+ 'blocking/windows_rmtree_blocker.py',
117
+ 'blocking/workflow_substitution_slot_blocker.py',
118
+ 'blocking/write-existing-file-blocker.py',
119
+ 'blocking/write_existing_file_blocker.py',
120
+ 'diagnostic/hook_log_stop_wrapper.py',
121
+ 'lifecycle/config-change-guard.py',
122
+ 'lifecycle/config_change_guard.py',
123
+ 'lifecycle/enter_worktree_origin_prefetch.py',
124
+ 'lifecycle/mcp_session_lifecycle.py',
125
+ 'lifecycle/nested_project_hooks.py',
126
+ 'lifecycle/pr_converge_bugteam_skill_tracker.py',
127
+ 'lifecycle/session-end-cleanup.py',
128
+ 'lifecycle/session_end_cleanup.py',
129
+ 'notification/attention-needed-notify.py',
130
+ 'notification/attention_needed_notify.py',
131
+ 'notification/claude-notification-handler.py',
132
+ 'notification/claude_notification_handler.py',
133
+ 'observability/instructions_loaded_logger.py',
134
+ 'observability/pr_description_writer_spawn_tracker.py',
135
+ 'observability/session_file_edit_tracker.py',
136
+ 'observability/test_failure_recorder.py',
137
+ 'policy/guards/git_find_handle_guard.py',
138
+ 'routing/spawn_oversight_hook.py',
139
+ 'routing/spawn_readiness_hook.py',
140
+ 'routing/subagent_effort_route_hook.py',
141
+ 'routing/subagent_model_pin_hook.py',
142
+ 'routing/subagent_model_routing.mjs',
143
+ 'routing/thread_spawn_pace_hook.py',
144
+ 'session/advisor_rules_prompt.py',
145
+ 'session/artifact_template_pointer.py',
146
+ 'session/background_silence_prompt.py',
147
+ 'session/bulk-edit-reminder.py',
148
+ 'session/bulk_edit_reminder.py',
149
+ 'session/code-rules-reminder.py',
150
+ 'session/code_rules_reminder.py',
151
+ 'session/compact-context-reinject.py',
152
+ 'session/compaction_recall_prompt.py',
153
+ 'session/deepen_first_prompt.py',
154
+ 'session/gh_pr_author_session_cleanup.py',
155
+ 'session/hook-structure-context.py',
156
+ 'session/issue_tracker_session_starter.py',
157
+ 'session/npx_pele_guidance.py',
158
+ 'session/open_task_ask_recorder.py',
159
+ 'session/orchestrator_auto_starter.py',
160
+ 'session/plugin-data-dir-cleanup.py',
161
+ 'session/plugin_change_warning.py',
162
+ 'session/plugin_data_dir_cleanup.py',
163
+ 'session/plugin_session_baseline_writer.py',
164
+ 'session/pr_lifecycle_skill_session_start.py',
165
+ 'session/restore_dev_null.py',
166
+ 'session/session_edit_tracker_cleanup.py',
167
+ 'session/session_env_cleanup.py',
168
+ 'session/skill_loaded_reminder.py',
169
+ 'session/style_reminder_prompt.py',
170
+ 'session/task_list_loop_starter.py',
171
+ 'session/task_tool_prompt.py',
172
+ 'session/tracking_nudge.py',
173
+ 'session/untracked_repo_detector.py',
174
+ 'session/working_style_prompt.py',
175
+ 'validation/code-style-validator.py',
176
+ 'validation/code_style_validator.py',
177
+ 'validation/e2e-test-validator.py',
178
+ 'validation/hook-format-validator.py',
179
+ 'validation/hook_format_validator.py',
180
+ 'validation/mypy_validator.py',
181
+ 'validation/post_tool_use_dispatcher.py',
182
+ 'validators/run_all_validators.py',
183
+ 'workflow/auto-formatter.py',
184
+ 'workflow/auto_formatter.py',
185
+ 'workflow/doc_gist_auto_publish.py',
186
+ 'workflow/investigation-tracker-reset.py',
187
+ 'workflow/investigation_tracker_reset.py',
188
+ 'workflow/md_to_html_companion.py',
189
+ ]);
@@ -0,0 +1,28 @@
1
+ import { strict as assert } from 'node:assert';
2
+ import { test } from 'node:test';
3
+ import { readFileSync } from 'node:fs';
4
+ import { EVER_REGISTERED_HOOK_RELATIVE_PATHS } from './ever-registered-hooks.mjs';
5
+ import { managedHookScriptRelativePaths } from './install.mjs';
6
+
7
+ const SHIPPED_HOOKS_CONFIG = JSON.parse(
8
+ readFileSync(new URL('../hooks/hooks.json', import.meta.url), 'utf8'),
9
+ );
10
+
11
+ test('EVER_REGISTERED_HOOK_RELATIVE_PATHS includes every script the package registers or prunes by name', () => {
12
+ const allUncoveredPaths = [...managedHookScriptRelativePaths(SHIPPED_HOOKS_CONFIG)].filter(
13
+ relativePath => !EVER_REGISTERED_HOOK_RELATIVE_PATHS.has(relativePath),
14
+ );
15
+
16
+ assert.deepEqual(
17
+ allUncoveredPaths,
18
+ [],
19
+ 'add each new registration here so a later release that drops it still removes it from settings',
20
+ );
21
+ });
22
+
23
+ test('EVER_REGISTERED_HOOK_RELATIVE_PATHS keeps the retired merge-over-review card gate', () => {
24
+ assert.equal(
25
+ EVER_REGISTERED_HOOK_RELATIVE_PATHS.has('blocking/merge_over_review_offer_gate.py'),
26
+ true,
27
+ );
28
+ });
package/bin/install.mjs CHANGED
@@ -15,6 +15,7 @@ import {
15
15
  expandHomeDirectoryTokens,
16
16
  expandHomeDirectoryTokensInSettings,
17
17
  } from './expand_home_directory_tokens.mjs';
18
+ import { EVER_REGISTERED_HOOK_RELATIVE_PATHS } from './ever-registered-hooks.mjs';
18
19
  import { EVER_SHIPPED_SKILL_NAMES } from './ever-shipped-skills.mjs';
19
20
  import {
20
21
  MANAGED_PERMISSION_LIST_NAMES,
@@ -1467,33 +1468,49 @@ export function commandReferencesManagedHook(
1467
1468
  * @returns {boolean} True when the command runs that script under a sharing root.
1468
1469
  */
1469
1470
  function commandRunsHookOfRootSharingSettings(normalizedCommand, relativePath, sharedSettingsRealPath) {
1470
- const commandArgumentBoundary = /[\s'";]/;
1471
- const hookPathTail = `/${MANAGED_HOOKS_DIRECTORY_NAME}/${relativePath}`;
1472
1471
  const sharedSettingsKey = comparisonKeyForPath(sharedSettingsRealPath);
1473
- let tailStart = normalizedCommand.indexOf(hookPathTail);
1472
+ const hookPathTail = `/${MANAGED_HOOKS_DIRECTORY_NAME}/${relativePath}`;
1473
+ return pathPrefixesBeforeTail(normalizedCommand, hookPathTail).some(rootPath => {
1474
+ const rootSettingsRealPath = rootPath
1475
+ ? realPathOrNull(join(rootPath, SETTINGS_FILE_NAME))
1476
+ : null;
1477
+ return Boolean(rootSettingsRealPath)
1478
+ && comparisonKeyForPath(rootSettingsRealPath) === sharedSettingsKey;
1479
+ });
1480
+ }
1481
+
1482
+ /**
1483
+ * List the path text in front of each spot where a command argument ends with
1484
+ * the given tail.
1485
+ *
1486
+ * A tail counts only where it ends at an argument boundary. A quoted argument is
1487
+ * decoded through quotedRootPathBeforeTail; an unquoted one runs back to the
1488
+ * previous argument boundary.
1489
+ *
1490
+ * @param {string} normalizedCommand Forward-slash-normalized hook command.
1491
+ * @param {string} pathTail The path tail to look for, starting with a slash.
1492
+ * @returns {string[]} The prefix in front of each boundary-ended tail.
1493
+ */
1494
+ function pathPrefixesBeforeTail(normalizedCommand, pathTail) {
1495
+ const commandArgumentBoundary = /[\s'";]/;
1496
+ const allPrefixes = [];
1497
+ let tailStart = normalizedCommand.indexOf(pathTail);
1474
1498
  while (tailStart !== -1) {
1475
- const characterAfterPath = normalizedCommand[tailStart + hookPathTail.length];
1476
- if (characterAfterPath === undefined || commandArgumentBoundary.test(characterAfterPath)) {
1477
- let rootPath;
1478
- if (characterAfterPath === '"' || characterAfterPath === "'") {
1479
- rootPath = quotedRootPathBeforeTail(normalizedCommand.slice(0, tailStart), characterAfterPath);
1480
- } else {
1481
- let rootStart = tailStart;
1482
- while (rootStart > 0 && !commandArgumentBoundary.test(normalizedCommand[rootStart - 1])) {
1483
- rootStart--;
1484
- }
1485
- rootPath = normalizedCommand.slice(rootStart, tailStart);
1486
- }
1487
- const rootSettingsRealPath = rootPath
1488
- ? realPathOrNull(join(rootPath, SETTINGS_FILE_NAME))
1489
- : null;
1490
- if (rootSettingsRealPath && comparisonKeyForPath(rootSettingsRealPath) === sharedSettingsKey) {
1491
- return true;
1499
+ const characterAfterPath = normalizedCommand[tailStart + pathTail.length];
1500
+ if (characterAfterPath === '"' || characterAfterPath === "'") {
1501
+ allPrefixes.push(
1502
+ quotedRootPathBeforeTail(normalizedCommand.slice(0, tailStart), characterAfterPath),
1503
+ );
1504
+ } else if (characterAfterPath === undefined || commandArgumentBoundary.test(characterAfterPath)) {
1505
+ let prefixStart = tailStart;
1506
+ while (prefixStart > 0 && !commandArgumentBoundary.test(normalizedCommand[prefixStart - 1])) {
1507
+ prefixStart--;
1492
1508
  }
1509
+ allPrefixes.push(normalizedCommand.slice(prefixStart, tailStart));
1493
1510
  }
1494
- tailStart = normalizedCommand.indexOf(hookPathTail, tailStart + 1);
1511
+ tailStart = normalizedCommand.indexOf(pathTail, tailStart + 1);
1495
1512
  }
1496
- return false;
1513
+ return allPrefixes;
1497
1514
  }
1498
1515
 
1499
1516
  /**
@@ -1781,6 +1798,27 @@ export function retiredManagedHookRelativePaths(
1781
1798
  return retiredRelativePaths;
1782
1799
  }
1783
1800
 
1801
+ /**
1802
+ * Name each hook script some release of the package registered that no package
1803
+ * source root ships now, each relative to the hooks root.
1804
+ *
1805
+ * The manifest diff misses a script a prior install recorded under another
1806
+ * managed root, and it forgets the script once a run under the new root writes
1807
+ * a fresh manifest. EVER_REGISTERED_HOOK_RELATIVE_PATHS keeps every name the
1808
+ * package has registered, so a retired name stays reachable after both. A hook
1809
+ * the user wrote is in no release, so its name never enters this set.
1810
+ *
1811
+ * @param {string[]} allSourceHooksDirectories The hooks directory of each package source root.
1812
+ * @returns {Set<string>} Forward-slash relative script paths under the hooks root.
1813
+ */
1814
+ export function unshippedEverRegisteredHookRelativePaths(allSourceHooksDirectories) {
1815
+ return new Set([...EVER_REGISTERED_HOOK_RELATIVE_PATHS].filter(
1816
+ relativePath => !allSourceHooksDirectories.some(
1817
+ sourceHooksDirectory => existsSync(join(sourceHooksDirectory, ...relativePath.split('/'))),
1818
+ ),
1819
+ ));
1820
+ }
1821
+
1784
1822
  const MANAGED_HOOK_ROOT_PATHS = [
1785
1823
  join(CLAUDE_HOME, MANAGED_HOOKS_DIRECTORY_NAME),
1786
1824
  join(AGENTS_HOME, MANAGED_HOOKS_DIRECTORY_NAME),
@@ -1865,6 +1903,11 @@ export function hookCommandComparisonSpelling(commandString, homeDirectory) {
1865
1903
  * Report whether a hook command runs one script under a hooks directory this
1866
1904
  * installer owns.
1867
1905
  *
1906
+ * The command may spell the hooks directory through a link, such as a
1907
+ * ~/.claude/hooks pointer an install under another root left behind. The
1908
+ * directory in front of the script resolves through every link before it is
1909
+ * compared, and the script itself need not exist.
1910
+ *
1868
1911
  * @param {unknown} commandString The hook command from a host configuration file.
1869
1912
  * @param {string} relativePath The script path under a hooks directory.
1870
1913
  * @param {{allOwnedHookRootKeys: Set<string>, homeDirectory: string}} ownership The owned roots.
@@ -1881,7 +1924,13 @@ export function commandNamesOwnedHookScript(commandString, relativePath, ownersh
1881
1924
  const ownedScriptPath = `${ownedRootKey}/${comparisonRelativePath}`;
1882
1925
  if (commandHoldsPathAtBoundary(comparisonCommand, ownedScriptPath)) return true;
1883
1926
  }
1884
- return false;
1927
+ return pathPrefixesBeforeTail(comparisonCommand, `/${comparisonRelativePath}`).some(
1928
+ hooksDirectory => {
1929
+ const realHooksDirectory = hooksDirectory ? realPathOrNull(hooksDirectory) : null;
1930
+ return realHooksDirectory !== null
1931
+ && ownership.allOwnedHookRootKeys.has(comparisonKeyForPath(realHooksDirectory));
1932
+ },
1933
+ );
1885
1934
  }
1886
1935
 
1887
1936
  /**
@@ -2724,9 +2773,14 @@ function runFullInstallPrunes(
2724
2773
  const hooksRoot = join(CLAUDE_HOME, MANAGED_HOOKS_DIRECTORY_NAME);
2725
2774
  const settingsPath = join(CLAUDE_HOME, SETTINGS_FILE_NAME);
2726
2775
  const retiredSkillMovedCount = pruneRetiredSkills(copiedSkillNames, priorManifestSkills);
2727
- const retiredHookPaths = retiredManagedHookRelativePaths(
2728
- priorManifestFiles, installedFiles, hooksRoot,
2729
- );
2776
+ const retiredHookPaths = new Set([
2777
+ ...retiredManagedHookRelativePaths(priorManifestFiles, installedFiles, hooksRoot),
2778
+ ...unshippedEverRegisteredHookRelativePaths(
2779
+ managedPackageSourceRoots().map(
2780
+ sourceRoot => resolvePackageManagedDirectory(sourceRoot, MANAGED_HOOKS_DIRECTORY_NAME),
2781
+ ),
2782
+ ),
2783
+ ]);
2730
2784
  const registeredRetiredPaths = retiredHookPathsNamedByCommands(
2731
2785
  priorSettingsHookCommands, retiredHookPaths,
2732
2786
  );
@@ -11,6 +11,7 @@ import {
11
11
  rmSync,
12
12
  symlinkSync,
13
13
  lstatSync,
14
+ realpathSync,
14
15
  } from 'node:fs';
15
16
  import { tmpdir } from 'node:os';
16
17
  import { join, dirname, basename } from 'node:path';
@@ -1614,6 +1615,157 @@ test('a full reinstall removes a retired hook entry under an event type the curr
1614
1615
  }
1615
1616
  });
1616
1617
 
1618
+ const UNSHIPPED_GATE_RELATIVE_SEGMENTS = ['blocking', 'merge_over_review_offer_gate.py'];
1619
+ const UNSHIPPED_GATE_MATCHER = 'AskUserQuestion|mcp__.*__ask_decision';
1620
+ const USER_AUTHORED_HOOK_RELATIVE_SEGMENTS = ['blocking', 'codemap_first_redirector.py'];
1621
+ const USER_AUTHORED_HOOK_MATCHER = 'Grep|Glob';
1622
+ const USER_AUTHORED_HOOK_BYTES = Buffer.from('a redirector the user wrote\n', 'utf8');
1623
+ const SHIPPED_SCRIPT_REFERENCE_PATTERN = /\$\{CLAUDE_PLUGIN_ROOT\}\/hooks\/(\S+?\.(?:py|mjs))/g;
1624
+
1625
+
1626
+ /**
1627
+ * Build a hook command the way an earlier install spelled it: unquoted, with
1628
+ * forward slashes.
1629
+ *
1630
+ * @param {string} hooksRoot The hooks directory the registration names.
1631
+ * @param {string[]} relativeSegments The script path segments under that directory.
1632
+ * @returns {string} The registration command.
1633
+ */
1634
+ function unquotedHookCommandUnder(hooksRoot, relativeSegments) {
1635
+ return `python3 ${join(hooksRoot, ...relativeSegments).replace(/\\/g, '/')}`;
1636
+ }
1637
+
1638
+
1639
+ /**
1640
+ * Add one matcher group holding the given commands to a host hook configuration file.
1641
+ *
1642
+ * @param {string} configurationPath The settings.json or Codex hooks.json path.
1643
+ * @param {string} matcher The group's matcher.
1644
+ * @param {string[]} allCommands The commands the group runs.
1645
+ */
1646
+ function appendPreToolUseGroup(configurationPath, matcher, allCommands) {
1647
+ const configuration = existsSync(configurationPath)
1648
+ ? JSON.parse(readFileSync(configurationPath, 'utf8'))
1649
+ : { hooks: {} };
1650
+ configuration.hooks[RETIRED_HOOK_EVENT_TYPE] ??= [];
1651
+ configuration.hooks[RETIRED_HOOK_EVENT_TYPE].push({
1652
+ matcher,
1653
+ hooks: allCommands.map(command => ({ type: 'command', command })),
1654
+ });
1655
+ writeFileWithParents(configurationPath, JSON.stringify(configuration, null, 4) + '\n');
1656
+ }
1657
+
1658
+
1659
+ /**
1660
+ * List every script path the shipped hooks.json registers, relative to hooks/.
1661
+ *
1662
+ * @returns {string[]} The registered script paths.
1663
+ */
1664
+ function shippedRegisteredScriptPaths() {
1665
+ const shippedHooksText = readFileSync(
1666
+ join(THIS_DIRECTORY, '..', HOOKS_DIRECTORY_NAME, 'hooks.json'), 'utf8',
1667
+ );
1668
+ return [...new Set([...shippedHooksText.matchAll(SHIPPED_SCRIPT_REFERENCE_PATTERN)].map(
1669
+ scriptMatch => scriptMatch[1],
1670
+ ))];
1671
+ }
1672
+
1673
+
1674
+ test('an install after the managed root moves removes a registration for a hook the package no longer ships', () => {
1675
+ const sandboxParent = mkdtempSync(join(tmpdir(), 'cdev-root-move-'));
1676
+ try {
1677
+ const priorHomeDirectory = join(sandboxParent, 'prior-home');
1678
+ const currentHomeDirectory = join(sandboxParent, 'current-home');
1679
+ const priorClaudeDirectory = join(priorHomeDirectory, '.claude');
1680
+ mkdirSync(priorClaudeDirectory, { recursive: true });
1681
+ runInstaller(priorHomeDirectory, []);
1682
+ const priorHooksRoot = join(priorClaudeDirectory, HOOKS_DIRECTORY_NAME);
1683
+ const unshippedGatePath = join(priorHooksRoot, ...UNSHIPPED_GATE_RELATIVE_SEGMENTS);
1684
+ writeFileWithParents(unshippedGatePath, RETIRED_HOOK_SEEDED_CONTENTS);
1685
+ appendManifestFiles(join(priorClaudeDirectory, MANIFEST_FILE_NAME), [unshippedGatePath]);
1686
+ const userAuthoredHookPath = join(priorHooksRoot, ...USER_AUTHORED_HOOK_RELATIVE_SEGMENTS);
1687
+ writeFileWithParents(userAuthoredHookPath, USER_AUTHORED_HOOK_BYTES);
1688
+ const userAuthoredHookRealPath = realpathSync(userAuthoredHookPath);
1689
+ const settingsPath = join(priorClaudeDirectory, SETTINGS_FILE_NAME);
1690
+ const unshippedGateCommand = unquotedHookCommandUnder(
1691
+ priorHooksRoot, UNSHIPPED_GATE_RELATIVE_SEGMENTS,
1692
+ );
1693
+ const userAuthoredCommand = unquotedHookCommandUnder(
1694
+ priorHooksRoot, USER_AUTHORED_HOOK_RELATIVE_SEGMENTS,
1695
+ );
1696
+ const foreignHooksRoot = join(sandboxParent, FOREIGN_TOOL_DIRECTORY_NAME, HOOKS_DIRECTORY_NAME);
1697
+ const foreignGatePath = join(foreignHooksRoot, ...UNSHIPPED_GATE_RELATIVE_SEGMENTS);
1698
+ const foreignGateBytes = Buffer.from('another tool keeps a gate of this name\n', 'utf8');
1699
+ writeFileWithParents(foreignGatePath, foreignGateBytes);
1700
+ const foreignGateCommand = unquotedHookCommandUnder(
1701
+ foreignHooksRoot, UNSHIPPED_GATE_RELATIVE_SEGMENTS,
1702
+ );
1703
+ appendPreToolUseGroup(settingsPath, UNSHIPPED_GATE_MATCHER, [unshippedGateCommand]);
1704
+ appendPreToolUseGroup(settingsPath, USER_AUTHORED_HOOK_MATCHER, [
1705
+ userAuthoredCommand, foreignGateCommand,
1706
+ ]);
1707
+ mkdirSync(currentHomeDirectory, { recursive: true });
1708
+ symlinkSync(priorClaudeDirectory, join(currentHomeDirectory, '.claude'), 'junction');
1709
+ const codexHooksRoot = join(currentHomeDirectory, CODEX_DIRECTORY_NAME, HOOKS_DIRECTORY_NAME);
1710
+ const codexHooksPath = join(
1711
+ currentHomeDirectory, CODEX_DIRECTORY_NAME, CODEX_HOOKS_CONFIGURATION_FILE_NAME,
1712
+ );
1713
+ const codexGateCommand = unquotedHookCommandUnder(
1714
+ codexHooksRoot, UNSHIPPED_GATE_RELATIVE_SEGMENTS,
1715
+ );
1716
+ appendPreToolUseGroup(codexHooksPath, UNSHIPPED_GATE_MATCHER, [codexGateCommand]);
1717
+ appendPreToolUseGroup(codexHooksPath, USER_AUTHORED_HOOK_MATCHER, [FOREIGN_CODEX_HOOK_COMMAND]);
1718
+
1719
+ runInstaller(currentHomeDirectory, []);
1720
+
1721
+ const settings = readSettings(priorClaudeDirectory);
1722
+ const settingsCommands = allHookCommands(settings);
1723
+ assert.equal(
1724
+ settingsCommands.includes(unshippedGateCommand),
1725
+ false,
1726
+ 'the registration for the gate the package stopped shipping leaves settings.json',
1727
+ );
1728
+ assert.equal(
1729
+ settings.hooks[RETIRED_HOOK_EVENT_TYPE].some(group => group.matcher === UNSHIPPED_GATE_MATCHER),
1730
+ false,
1731
+ 'the matcher group the gate held alone leaves with it',
1732
+ );
1733
+ assert.equal(
1734
+ settingsCommands.includes(userAuthoredCommand),
1735
+ true,
1736
+ 'a hook the user wrote under the managed hooks root keeps its registration',
1737
+ );
1738
+ assert.deepEqual(
1739
+ readFileSync(userAuthoredHookRealPath),
1740
+ USER_AUTHORED_HOOK_BYTES,
1741
+ 'the user-authored hook keeps its bytes',
1742
+ );
1743
+ assert.equal(
1744
+ settingsCommands.includes(foreignGateCommand),
1745
+ true,
1746
+ 'a registration outside every managed hooks root stays even when its name matches',
1747
+ );
1748
+ assert.deepEqual(readFileSync(foreignGatePath), foreignGateBytes);
1749
+ for (const shippedScriptPath of shippedRegisteredScriptPaths()) {
1750
+ assert.ok(
1751
+ settingsCommands.some(command => command.replace(/\\/g, '/').includes(
1752
+ `/${HOOKS_DIRECTORY_NAME}/${shippedScriptPath}`,
1753
+ )),
1754
+ `the shipped registration for ${shippedScriptPath} stays in settings.json`,
1755
+ );
1756
+ }
1757
+ const codexCommands = allHookCommands(JSON.parse(readFileSync(codexHooksPath, 'utf8')));
1758
+ assert.equal(
1759
+ codexCommands.includes(codexGateCommand),
1760
+ false,
1761
+ 'the Codex registration for the gate leaves hooks.json too',
1762
+ );
1763
+ assert.equal(codexCommands.includes(FOREIGN_CODEX_HOOK_COMMAND), true);
1764
+ } finally {
1765
+ rmSync(sandboxParent, { recursive: true, force: true });
1766
+ }
1767
+ });
1768
+
1617
1769
  test('an uninstall skips a manifest record outside ~/.claude and still removes the managed records', () => {
1618
1770
  const sandbox = createSandbox();
1619
1771
  const outsideDirectory = mkdtempSync(join(tmpdir(), 'cdev-outside-home-'));
@@ -54,6 +54,7 @@ import {
54
54
  detectPython,
55
55
  pythonFileAndPrefixArguments,
56
56
  retainNewestRunBackupOnly,
57
+ unshippedEverRegisteredHookRelativePaths,
57
58
  } from './install.mjs';
58
59
  import { EVER_SHIPPED_SKILL_NAMES } from './ever-shipped-skills.mjs';
59
60
  import {
@@ -2743,6 +2744,57 @@ test('a retired registration reaching an owned root through a junction is named'
2743
2744
  });
2744
2745
 
2745
2746
 
2747
+ test('a missing script spelled through a link from an unowned spelling into an owned root is named', () => {
2748
+ const sandboxRoot = mkdtempSync(join(tmpdir(), 'cdev-linked-hook-spelling-'));
2749
+ try {
2750
+ const agentsHooksRoot = join(sandboxRoot, ...AGENTS_HOOKS_ROOT_SEGMENTS);
2751
+ const priorUserHooksLink = join(sandboxRoot, 'prior-user', '.claude', 'hooks');
2752
+ mkdirSync(agentsHooksRoot, { recursive: true });
2753
+ mkdirSync(dirname(priorUserHooksLink), { recursive: true });
2754
+ symlinkSync(agentsHooksRoot, priorUserHooksLink, 'junction');
2755
+ const linkedCommand = `python3 ${join(priorUserHooksLink, ...RETIRED_HOOK_RELATIVE_PATH.split('/')).replace(/\\/g, '/')}`;
2756
+
2757
+ const namedPaths = retiredHookPathsNamedByCommands(
2758
+ [linkedCommand],
2759
+ new Set([RETIRED_HOOK_RELATIVE_PATH]),
2760
+ sandboxHookOwnership(sandboxRoot, [agentsHooksRoot]),
2761
+ );
2762
+
2763
+ assert.deepEqual(
2764
+ [...namedPaths],
2765
+ [RETIRED_HOOK_RELATIVE_PATH],
2766
+ 'the directory in front of the script resolves into the owned root',
2767
+ );
2768
+ } finally {
2769
+ rmSync(sandboxRoot, { recursive: true, force: true });
2770
+ }
2771
+ });
2772
+
2773
+
2774
+ test('unshippedEverRegisteredHookRelativePaths names a once-registered script no source root ships', () => {
2775
+ const sandboxRoot = mkdtempSync(join(tmpdir(), 'cdev-unshipped-hooks-'));
2776
+ try {
2777
+ const shippedRelativePath = 'blocking/pre_tool_use_dispatcher.py';
2778
+ const unshippedRelativePath = 'blocking/merge_over_review_offer_gate.py';
2779
+ const sourceHooksDirectory = join(sandboxRoot, 'hooks');
2780
+ mkdirSync(join(sourceHooksDirectory, 'blocking'), { recursive: true });
2781
+ writeFileSync(join(sourceHooksDirectory, ...shippedRelativePath.split('/')), '');
2782
+
2783
+ const unshippedPaths = unshippedEverRegisteredHookRelativePaths([sourceHooksDirectory]);
2784
+
2785
+ assert.equal(unshippedPaths.has(unshippedRelativePath), true);
2786
+ assert.equal(unshippedPaths.has(shippedRelativePath), false);
2787
+ assert.equal(
2788
+ unshippedPaths.has('blocking/codemap_first_redirector.py'),
2789
+ false,
2790
+ 'a script no release registered never counts as retired',
2791
+ );
2792
+ } finally {
2793
+ rmSync(sandboxRoot, { recursive: true, force: true });
2794
+ }
2795
+ });
2796
+
2797
+
2746
2798
  test('a registration under a hooks root the installer does not own is never named or pruned', () => {
2747
2799
  const sandboxRoot = mkdtempSync(join(tmpdir(), 'cdev-foreign-hook-root-'));
2748
2800
  try {
@@ -45,7 +45,7 @@ The gate holds a turn once when all three hold:
45
45
 
46
46
  The gate never reads the reply text. A held turn passes, so the gate adds at most one step to a turn.
47
47
 
48
- In Claude Code, `tracking_nudge.py` runs on `UserPromptSubmit`. For a prompt that asks for work, it adds one note that asks for a task list item, so the agent tracks the ask before it starts. The note never blocks.
48
+ In Claude Code, `tracking_nudge.py` runs on `UserPromptSubmit`. For the session's first prompt that asks for work, and the first after each compaction, it adds one note that asks for an item in the session's task list tool, so the agent tracks the ask before it starts. The note never blocks.
49
49
 
50
50
  ## Cursor
51
51
 
@@ -50,4 +50,4 @@ Report only what a verifier passed. Name the verifier's verdict and the evidence
50
50
 
51
51
  ## Enforcement
52
52
 
53
- `hooks/routing/spawn_oversight_hook.py` adds the six steps, the separate verifier, the reproduce-first check, the scope ask, and the reporting rule to every spawn at every level of the agent tree whose brief has an `Outcome:` line and an `On a blocker:` line; the hook already denies a brief without them, and the verifier brief template carries both. The flow itself adds context only. No hook refuses a report, a commit, or a spawn for a missing verifier run, so the flow never blocks work the user asked for.
53
+ `hooks/routing/spawn_oversight_hook.py` adds the six steps, the separate verifier, the reproduce-first check, the scope ask, and the reporting rule to the first passing spawn of each agent in the tree, and again after a compaction. A passing brief has an `Outcome:` line and an `On a blocker:` line; the hook denies a brief without them on every spawn, and the verifier brief template carries both. The flow itself adds context only. No hook refuses a report, a commit, or a spawn for a missing verifier run, so the flow never blocks work the user asked for.