ctxtop 0.0.0-stage → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (240) hide show
  1. package/.antigravity-plugin/plugin.json +36 -0
  2. package/.claude-plugin/plugin.json +18 -0
  3. package/CHECKSUMS.sha256 +149 -0
  4. package/LICENSE +27 -0
  5. package/README.md +330 -3
  6. package/SECURITY.md +22 -0
  7. package/agents/ah-flash-scout.md +25 -0
  8. package/assets/advanced_view_loaded_420px.png +0 -0
  9. package/assets/hero-demo.svg +188 -0
  10. package/assets/logo.svg +19 -0
  11. package/assets/simple_view_lean_420px.png +0 -0
  12. package/assets/simple_view_loaded_420px.png +0 -0
  13. package/assets/social-preview.svg +72 -0
  14. package/assets/zone_c_step3_shield_full.png +0 -0
  15. package/bin/ah-statusline.mjs +145 -0
  16. package/bin/cli.mjs +3 -0
  17. package/bin/ctxtop.mjs +1474 -0
  18. package/commands/cost-radar.md +11 -0
  19. package/commands/evolve.md +10 -0
  20. package/commands/handoff.md +10 -0
  21. package/commands/horizon.md +10 -0
  22. package/commands/inspect.md +10 -0
  23. package/commands/precheck.md +10 -0
  24. package/config/default_flightcheck.json +114 -0
  25. package/config/modelCatalog.json +620 -0
  26. package/config/platformQuirks.json +19 -0
  27. package/hooks/handlers/compact-lifecycle.mjs +262 -0
  28. package/hooks/handlers/hookIo.mjs +255 -0
  29. package/hooks/handlers/hookIpcClient.mjs +83 -0
  30. package/hooks/handlers/post-tool-use.mjs +265 -0
  31. package/hooks/handlers/pre-model-switch.mjs +249 -0
  32. package/hooks/handlers/pre-tool-use.mjs +365 -0
  33. package/hooks/handlers/stop-gate.mjs +240 -0
  34. package/hooks/handlers/user-prompt-submit.mjs +143 -0
  35. package/hooks/hooks.json +81 -0
  36. package/hooks/post_invocation.mjs +13 -0
  37. package/hooks/post_tool_use.mjs +17 -0
  38. package/hooks/pre_invocation.mjs +14 -0
  39. package/hooks/pre_tool_use.mjs +97 -0
  40. package/hooks/register.js +687 -0
  41. package/hooks/session_start.mjs +14 -0
  42. package/hooks/stop.mjs +13 -0
  43. package/hooks.json +56 -0
  44. package/package.json +103 -4
  45. package/packages/antigravity/package.json +14 -0
  46. package/packages/antigravity/src/index.mjs +1 -0
  47. package/packages/claude-code/package.json +14 -0
  48. package/packages/claude-code/src/index.mjs +2 -0
  49. package/packages/core/package.json +14 -0
  50. package/packages/core/src/index.mjs +1 -0
  51. package/packages/engine-node/package.json +14 -0
  52. package/packages/engine-node/src/index.mjs +1 -0
  53. package/packages/mcp/package.json +17 -0
  54. package/packages/mcp/src/server.mjs +396 -0
  55. package/packages/pro/LICENSE-COMMERCIAL.md +19 -0
  56. package/packages/pro/README-SIGNING.md +30 -0
  57. package/packages/pro/package.json +16 -0
  58. package/packages/pro/src/index.mjs +3 -0
  59. package/packages/pro/src/team_finops_pack.mjs +241 -0
  60. package/packages/pro/workers/polar_webhook_worker.mjs +215 -0
  61. package/plugin.json +36 -0
  62. package/rules/AGENTS.md +10 -0
  63. package/sidecars/horizon-daemon/ipcServer.mjs +24 -0
  64. package/sidecars/horizon-daemon/server.mjs +2002 -0
  65. package/sidecars/horizon-daemon/sidecar.json +19 -0
  66. package/skills/cost-radar/SKILL.md +21 -0
  67. package/skills/evolve/SKILL.md +21 -0
  68. package/skills/handoff/SKILL.md +42 -0
  69. package/skills/horizon/SKILL.md +17 -0
  70. package/skills/inspect/SKILL.md +18 -0
  71. package/skills/precheck/SKILL.md +44 -0
  72. package/src/adapters/antigravity/index.mjs +79 -0
  73. package/src/adapters/claude-code/index.mjs +155 -0
  74. package/src/cli/cost_radar.mjs +70 -0
  75. package/src/cli/doctor.mjs +351 -0
  76. package/src/cli/horizon_hud.mjs +686 -0
  77. package/src/cli/init.mjs +425 -0
  78. package/src/cli/postmortem.mjs +515 -0
  79. package/src/coach/cacheGravityRouter.mjs +12 -0
  80. package/src/config/modelCatalog.json +620 -0
  81. package/src/config/platformQuirks.json +19 -0
  82. package/src/core/action_queue.mjs +264 -0
  83. package/src/core/ag_bridge.mjs +346 -0
  84. package/src/core/atomic_io.mjs +124 -0
  85. package/src/core/baseline.mjs +607 -0
  86. package/src/core/blindspot_sensors.mjs +399 -0
  87. package/src/core/classifier.mjs +1757 -0
  88. package/src/core/coach/circuit_breakers.mjs +650 -0
  89. package/src/core/coach/contradiction_auditor.mjs +239 -0
  90. package/src/core/coach/effort_advisor.mjs +143 -0
  91. package/src/core/coach/handoff_hydrator.mjs +483 -0
  92. package/src/core/coach/progressive_checkpointer.mjs +551 -0
  93. package/src/core/coach/prompt_decomposer_coach.mjs +141 -0
  94. package/src/core/coach/reflector_queue.mjs +505 -0
  95. package/src/core/coach/saved_quota_ledger.mjs +615 -0
  96. package/src/core/coach/subagent_ipi_sanitizer.mjs +200 -0
  97. package/src/core/coach/subagent_phantom_auditor.mjs +261 -0
  98. package/src/core/coach/task_quota_router.mjs +955 -0
  99. package/src/core/coach/turn_zero_gate.mjs +574 -0
  100. package/src/core/compaction_coach.mjs +1126 -0
  101. package/src/core/config.mjs +214 -0
  102. package/src/core/constants.mjs +1800 -0
  103. package/src/core/detectors_det01_to_16.mjs +1474 -0
  104. package/src/core/episodic_memory.mjs +135 -0
  105. package/src/core/fts5_output_compressor.mjs +359 -0
  106. package/src/core/git_ledger.mjs +189 -0
  107. package/src/core/handoff_audit.mjs +558 -0
  108. package/src/core/history.mjs +221 -0
  109. package/src/core/hook_diagnostics.mjs +158 -0
  110. package/src/core/horizon_classifier.mjs +326 -0
  111. package/src/core/horizon_config.mjs +802 -0
  112. package/src/core/host_watchdog.mjs +200 -0
  113. package/src/core/layer5_hygiene.mjs +966 -0
  114. package/src/core/log_resolver.mjs +231 -0
  115. package/src/core/mcp_auditor.mjs +138 -0
  116. package/src/core/micro_skills_store.mjs +91 -0
  117. package/src/core/offenders.mjs +161 -0
  118. package/src/core/parser.mjs +1996 -0
  119. package/src/core/path_canonicalizer.mjs +73 -0
  120. package/src/core/paths.mjs +310 -0
  121. package/src/core/prefix_cache_shield.mjs +386 -0
  122. package/src/core/pro_license.mjs +385 -0
  123. package/src/core/prompt_rubric.mjs +518 -0
  124. package/src/core/pruner.mjs +433 -0
  125. package/src/core/quota.mjs +1860 -0
  126. package/src/core/rsi_instinct_engine.mjs +1197 -0
  127. package/src/core/sanitizer.mjs +121 -0
  128. package/src/core/session_forensics.mjs +303 -0
  129. package/src/core/session_timeline.mjs +358 -0
  130. package/src/core/settings.mjs +99 -0
  131. package/src/core/shared/detectors.mjs +1342 -0
  132. package/src/core/shared/fnv1a64.mjs +85 -0
  133. package/src/core/shared/handoff_schema.mjs +123 -0
  134. package/src/core/shared/index.mjs +5 -0
  135. package/src/core/shared/ipi_sanitizer.mjs +165 -0
  136. package/src/core/shared/micro_skills.mjs +1 -0
  137. package/src/core/shared/plugin_validator.mjs +202 -0
  138. package/src/core/shared/prompt_hygiene_governor.mjs +1 -0
  139. package/src/core/sidecar_store.mjs +302 -0
  140. package/src/core/sprint_metrics.mjs +366 -0
  141. package/src/core/sqlite_client.mjs +283 -0
  142. package/src/core/storage_doctor.mjs +358 -0
  143. package/src/core/subagents.mjs +609 -0
  144. package/src/core/swarm_topology.mjs +360 -0
  145. package/src/core/task_quota_router.mjs +1656 -0
  146. package/src/core/telemetry/cache_ttl_watchdog.mjs +284 -0
  147. package/src/core/telemetry/scope_lock_registry.mjs +578 -0
  148. package/src/core/telemetry/shadow_file_detector.mjs +291 -0
  149. package/src/core/telemetry/trajectory_watcher.mjs +259 -0
  150. package/src/core/timeline_svg.mjs +236 -0
  151. package/src/core/tool_surgeon.mjs +305 -0
  152. package/src/core/trajectory_stitcher.mjs +645 -0
  153. package/src/core/u_shaped_optimizer.mjs +789 -0
  154. package/src/core/wal_hygiene.mjs +233 -0
  155. package/src/core-isomorphic/catalog/detectorCatalog.mjs +558 -0
  156. package/src/core-isomorphic/catalog/index.mjs +1 -0
  157. package/src/core-isomorphic/coach/cacheGravityRouter.mjs +720 -0
  158. package/src/core-isomorphic/coach/microSkills.mjs +1 -0
  159. package/src/core-isomorphic/coach/promptHygieneGovernor.mjs +1 -0
  160. package/src/core-isomorphic/coach/repoCalibration.mjs +254 -0
  161. package/src/core-isomorphic/coach/savedQuotaLedger.mjs +527 -0
  162. package/src/core-isomorphic/coach/stateBatonHydrator.mjs +810 -0
  163. package/src/core-isomorphic/coach/ttlWatchdog.mjs +457 -0
  164. package/src/core-isomorphic/config/anthropicModelCatalog.json +203 -0
  165. package/src/core-isomorphic/config/catalogLoader.mjs +768 -0
  166. package/src/core-isomorphic/config/horizonConfig.mjs +1009 -0
  167. package/src/core-isomorphic/control/callTree.mjs +338 -0
  168. package/src/core-isomorphic/control/coachLatches.mjs +126 -0
  169. package/src/core-isomorphic/control/controlStateMachine.mjs +205 -0
  170. package/src/core-isomorphic/control/index.mjs +49 -0
  171. package/src/core-isomorphic/control/swarmWorktree.mjs +109 -0
  172. package/src/core-isomorphic/control/toolSuspension.mjs +197 -0
  173. package/src/core-isomorphic/diagnostics/drift_guard.mjs +382 -0
  174. package/src/core-isomorphic/diagnostics/index.mjs +9 -0
  175. package/src/core-isomorphic/diagnostics/micro_skills.mjs +471 -0
  176. package/src/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs +622 -0
  177. package/src/core-isomorphic/economics/billingBlocks.mjs +251 -0
  178. package/src/core-isomorphic/economics/cacheGravity.mjs +351 -0
  179. package/src/core-isomorphic/economics/cliffBreaker.mjs +170 -0
  180. package/src/core-isomorphic/economics/driftLatency.mjs +319 -0
  181. package/src/core-isomorphic/economics/dualTtl.mjs +198 -0
  182. package/src/core-isomorphic/economics/index.mjs +47 -0
  183. package/src/core-isomorphic/economics/retentionRadar.mjs +348 -0
  184. package/src/core-isomorphic/guards/circuitBreakers.mjs +1202 -0
  185. package/src/core-isomorphic/guards/det01_03_shell_secret.mjs +1035 -0
  186. package/src/core-isomorphic/guards/det04_12_thrash_rot.mjs +480 -0
  187. package/src/core-isomorphic/guards/det13_20_mcp_scope.mjs +603 -0
  188. package/src/core-isomorphic/guards/losslessPostSanitizer.mjs +301 -0
  189. package/src/core-isomorphic/index.js +26 -0
  190. package/src/core-isomorphic/telemetry/otelExporter.mjs +187 -0
  191. package/src/core-isomorphic/telemetry/scopeLockRegistry.mjs +522 -0
  192. package/src/core-isomorphic/telemetry/sprintMetrics.mjs +327 -0
  193. package/src/core-isomorphic/telemetry/swarmTopology.mjs +152 -0
  194. package/src/core-isomorphic/telemetry/telemetryBridge.mjs +1132 -0
  195. package/src/core-isomorphic/ui/brailleSparkline.mjs +142 -0
  196. package/src/core-isomorphic/ui/costRadarSvg.mjs +276 -0
  197. package/src/core-isomorphic/ui/horizonGrid.mjs +475 -0
  198. package/src/core-isomorphic/ui/horizonPanelHtml.mjs +1181 -0
  199. package/src/core-isomorphic/ui/modViews.mjs +1478 -0
  200. package/src/core-isomorphic/ui/pdfReceiptGenerator.mjs +329 -0
  201. package/src/core-isomorphic/ustf/index.mjs +7 -0
  202. package/src/core-isomorphic/ustf/normalizer.mjs +512 -0
  203. package/src/core-isomorphic/ustf/schema.mjs +186 -0
  204. package/src/core-isomorphic/utils/runtime.mjs +962 -0
  205. package/src/demo/synthetic_states.mjs +661 -0
  206. package/src/diagnostics/bugReportGenerator.mjs +253 -0
  207. package/src/diagnostics/doctorEngine.mjs +203 -0
  208. package/src/engine-node/db/index.mjs +58 -0
  209. package/src/engine-node/db/jsonl_fallback.mjs +184 -0
  210. package/src/engine-node/db/probe.mjs +110 -0
  211. package/src/engine-node/db/sqlite_wrapper.mjs +122 -0
  212. package/src/engine-node/index.mjs +9 -0
  213. package/src/engine-node/ipc/client.mjs +447 -0
  214. package/src/engine-node/ipc/index.mjs +22 -0
  215. package/src/engine-node/ipc/protocol.mjs +177 -0
  216. package/src/engine-node/ipc/server.mjs +445 -0
  217. package/src/engine-node/offloader/index.mjs +6 -0
  218. package/src/engine-node/offloader/tool_offloader.mjs +241 -0
  219. package/src/engine-node/sensors/blindspots.mjs +369 -0
  220. package/src/engine-node/sensors/git_merge_tree.mjs +223 -0
  221. package/src/engine-node/sensors/index.mjs +7 -0
  222. package/src/hooks/portfolio_runtime.mjs +858 -0
  223. package/src/hooks/post_invocation.mjs +419 -0
  224. package/src/hooks/pre_invocation.mjs +1015 -0
  225. package/src/hooks/session_start.mjs +161 -0
  226. package/src/shims/agy_cli_compressor.mjs +705 -0
  227. package/src/shims/agy_git_guard.mjs +749 -0
  228. package/src/shims/ah_log_query.mjs +39 -0
  229. package/src/ui/costRadarSvg.mjs +6 -0
  230. package/src/ui/horizonGrid.mjs +1 -0
  231. package/src/ui/horizonPanelHtml.mjs +1 -0
  232. package/src/ui/horizon_panel.css +167 -0
  233. package/src/ui/horizon_panel.js +212 -0
  234. package/src/ui/modViews.mjs +1 -0
  235. package/src/utils/nodeIo.mjs +59 -0
  236. package/src/utils/runtime.mjs +1 -0
  237. package/src/webview/advanced_view.html +1808 -0
  238. package/src/webview/horizon_panel.html +11389 -0
  239. package/src/webview/registry.mjs +80 -0
  240. package/src/webview/simple_view.html +1370 -0
@@ -0,0 +1,365 @@
1
+ /**
2
+ * @file hooks/handlers/pre-tool-use.mjs
3
+ * Tier 2 Command Hook handler for `PreToolUse`
4
+ * (`Bash|PowerShell|Edit|MultiEdit|Write|NotebookEdit|Read|Grep|Glob|Task|Agent|WebFetch|mcp__.*`).
5
+ */
6
+
7
+ import fs from 'node:fs';
8
+ import path from 'node:path';
9
+ import { readLiveStateSnapshot } from '../../src/core-isomorphic/telemetry/telemetryBridge.mjs';
10
+ import { computeTotalPromptTokens } from '../../src/core-isomorphic/config/catalogLoader.mjs';
11
+ import { loadHorizonConfig } from '../../src/core-isomorphic/config/horizonConfig.mjs';
12
+ import { recordInterventionSavings } from '../../src/core-isomorphic/coach/savedQuotaLedger.mjs';
13
+ import { requireProFeature } from '../../src/core/pro_license.mjs';
14
+ import { foldCodeToSignatureStub, computeCompactLineDiff } from '../../src/core/pruner.mjs';
15
+ import {
16
+ CircuitBreakerEngine,
17
+ readBreakerStateSnapshot,
18
+ writeBreakerStateSnapshot
19
+ } from '../../src/core-isomorphic/guards/circuitBreakers.mjs';
20
+ import {
21
+ isCliEntrypoint,
22
+ readStdinJsonAsync,
23
+ exitPassThrough,
24
+ exitHardBlockStderr,
25
+ exitWithStdoutJson
26
+ } from './hookIo.mjs';
27
+ import { dispatchPreToolUseWithFallback } from './hookIpcClient.mjs';
28
+
29
+ /**
30
+ * Evaluates a `PreToolUse` hook payload and returns the contract response.
31
+ * Persists stateful breaker counters atomically across separate CLI hook spawns (`ISS-038`).
32
+ *
33
+ * @param {object} event
34
+ * @param {object} [options={}]
35
+ */
36
+ export function runPreToolUseHook(event = {}, options = {}) {
37
+ const toolName = String(event.tool_name || event.toolName || '');
38
+ const tier1Active = Boolean(
39
+ options.tier1ModActive ||
40
+ event.tier1ModActive ||
41
+ globalThis.process?.env?.AH_TIER1_MOD_ACTIVE === '1'
42
+ );
43
+ if (tier1Active && /^(Grep|Glob)$/i.test(toolName)) {
44
+ return {
45
+ exitCode: 0,
46
+ stdout: '',
47
+ stderr: '',
48
+ fastPath: 'tier1_mod_active',
49
+ verdict: { triggered: false, decision: 'allow', reason: 'Handled in-process by Tier 1 Mod' }
50
+ };
51
+ }
52
+ const sessionId = event.session_id || event.sessionId || 'default';
53
+ const cwdOptions = event.cwd && !options.cwd ? { ...options, cwd: event.cwd } : options;
54
+ const horizonConfig = options.horizonConfig || loadHorizonConfig(cwdOptions);
55
+ const liveState = options.telemetryState || readLiveStateSnapshot(sessionId, cwdOptions);
56
+ const configHasDiskSource = Boolean(
57
+ horizonConfig?.sources?.projectLoaded || horizonConfig?.sources?.globalLoaded
58
+ );
59
+ const rawEffectiveMode =
60
+ event.mode ||
61
+ options.mode ||
62
+ options.telemetryState?.flightMode ||
63
+ (configHasDiskSource
64
+ ? horizonConfig.flightMode
65
+ : liveState?.flightMode || horizonConfig?.flightMode || 'COACH');
66
+ const proAutoPilot =
67
+ rawEffectiveMode === 'AUTO_PILOT' ? requireProFeature('auto_pilot_locks', options) : { allowed: true };
68
+ const effectiveMode =
69
+ rawEffectiveMode === 'AUTO_PILOT' && !proAutoPilot.allowed ? 'COACH' : rawEffectiveMode;
70
+
71
+ const shouldPersistState =
72
+ !options.engine &&
73
+ options.persistState !== false &&
74
+ Boolean(event.cwd || options.cwd || options.breakerStatePath || options.persistState);
75
+
76
+ const priorSnapshot = shouldPersistState
77
+ ? readBreakerStateSnapshot(sessionId, cwdOptions)
78
+ : null;
79
+
80
+ const engine =
81
+ options.engine ||
82
+ new CircuitBreakerEngine({
83
+ ...cwdOptions,
84
+ horizonConfig,
85
+ mode: effectiveMode,
86
+ initialState: priorSnapshot
87
+ });
88
+
89
+ const eventUsage = event.usage || event.context_window?.current_usage || null;
90
+ const computedEventPromptTokens = Math.max(
91
+ computeTotalPromptTokens(event),
92
+ eventUsage ? computeTotalPromptTokens(eventUsage) : 0
93
+ );
94
+ const enrichedEvent = {
95
+ ...event,
96
+ ...(computedEventPromptTokens > 0 && event.totalPromptTokens === undefined
97
+ ? { totalPromptTokens: computedEventPromptTokens }
98
+ : {}),
99
+ mode: event.mode || effectiveMode
100
+ };
101
+
102
+ const verdict = engine.evaluatePreToolUse(enrichedEvent, {
103
+ ...liveState,
104
+ flightMode: effectiveMode
105
+ });
106
+
107
+ // Playbook Step 4 & VC Gap 4: Post-Edit Unified Delta Diff + 3rd-Read AST Signature Stub Interception
108
+ const isReadTool = /^(Read|read_file)$/i.test(toolName);
109
+ const tIn = event.tool_input || event.toolInput || event.args || {};
110
+ const hasLineBounds =
111
+ tIn.StartLine !== undefined ||
112
+ tIn.EndLine !== undefined ||
113
+ tIn.offset !== undefined ||
114
+ tIn.limit !== undefined;
115
+ const rawReadPath = String(tIn.file_path || tIn.Path || tIn.path || '').trim();
116
+
117
+ if (isReadTool && !hasLineBounds && rawReadPath) {
118
+ try {
119
+ const baseCwd = event.cwd || options.cwd || '';
120
+ const absReadPath = path.isAbsolute(rawReadPath)
121
+ ? rawReadPath
122
+ : path.resolve(baseCwd || process.cwd(), rawReadPath);
123
+ if (fs.existsSync(absReadPath) && fs.statSync(absReadPath).isFile()) {
124
+ const st = fs.statSync(absReadPath);
125
+ if (st.size > 256 && st.size <= 256 * 1024) {
126
+ const rawSrc = fs.readFileSync(absReadPath, 'utf8');
127
+ const normKey = absReadPath.replace(/\\/g, '/').toLowerCase();
128
+ let prevSrc = typeof event.priorContentSnapshot === 'string' ? event.priorContentSnapshot : null;
129
+ let snapFilePath = '';
130
+ let snapMap = {};
131
+
132
+ if (baseCwd && shouldPersistState) {
133
+ const safeSid = String(sessionId).replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
134
+ const cacheDir = path.join(baseCwd, '.claude', 'cache');
135
+ snapFilePath = path.join(cacheDir, `read_snapshots_${safeSid}.json`);
136
+ if (fs.existsSync(snapFilePath)) {
137
+ try {
138
+ snapMap = JSON.parse(fs.readFileSync(snapFilePath, 'utf8')) || {};
139
+ if (prevSrc === null && typeof snapMap[normKey] === 'string') {
140
+ prevSrc = snapMap[normKey];
141
+ }
142
+ } catch (_e) {
143
+ snapMap = {};
144
+ }
145
+ }
146
+ }
147
+
148
+ if (prevSrc !== null && prevSrc !== rawSrc) {
149
+ const delta = computeCompactLineDiff(prevSrc, rawSrc, path.basename(absReadPath));
150
+ if (delta.wasDiffed) {
151
+ verdict.triggered = true;
152
+ verdict.detectorId = verdict.detectorId || 'DET-06';
153
+ verdict.decision = verdict.decision || 'allow';
154
+ verdict.deltaDiffStub = delta.diffText;
155
+ verdict.savedTokens = Math.max(Number(verdict.savedTokens || 0), delta.savedTokens);
156
+ verdict.reason = `[GUARD-4 Post-Edit Delta Read] File modified since last read; returning unified delta diff (+${delta.savedTokens} tokens saved):\n${delta.diffText}`;
157
+ }
158
+ } else if (verdict.detectorId === 'DET-06' || Number(event.priorUnclippedReads || 0) >= 2) {
159
+ const folded = foldCodeToSignatureStub(rawSrc, rawReadPath);
160
+ if (folded.wasFolded) {
161
+ const stubSavedTok = Math.max(250, Math.round(folded.savedChars / 4));
162
+ verdict.triggered = true;
163
+ verdict.detectorId = verdict.detectorId || 'DET-06';
164
+ verdict.decision = verdict.decision || 'allow';
165
+ verdict.astSignatureStub = folded.condensed;
166
+ verdict.savedTokens = Math.max(Number(verdict.savedTokens || 0), stubSavedTok);
167
+ verdict.reason = `${verdict.reason ? verdict.reason + '\n\n' : '[GUARD-4 Repeat-Read Surgeon] Full-file re-read intercepted; returning AST signature stub (+' + stubSavedTok + ' tokens saved):\n'}${folded.condensed}`;
168
+ }
169
+ }
170
+
171
+ if (snapFilePath && rawSrc.length <= 128 * 1024) {
172
+ try {
173
+ fs.mkdirSync(path.dirname(snapFilePath), { recursive: true });
174
+ const keys = Object.keys(snapMap);
175
+ if (!snapMap[normKey] && keys.length >= 12) {
176
+ delete snapMap[keys[0]];
177
+ }
178
+ snapMap[normKey] = rawSrc;
179
+ fs.writeFileSync(snapFilePath, JSON.stringify(snapMap), 'utf8');
180
+ } catch (_writeErr) {
181
+ void _writeErr;
182
+ }
183
+ }
184
+ }
185
+ }
186
+ } catch (_stubErr) {
187
+ void _stubErr;
188
+ }
189
+ }
190
+
191
+ if (shouldPersistState) {
192
+ writeBreakerStateSnapshot(sessionId, engine.exportStateSnapshot(), cwdOptions);
193
+ }
194
+ if (!verdict.triggered) {
195
+ return {
196
+ exitCode: 0,
197
+ stdout: '',
198
+ stderr: '',
199
+ verdict
200
+ };
201
+ }
202
+
203
+ const detId = String(verdict.detectorId || '');
204
+ const isQuotaSavingGuard =
205
+ /^(DET-04|DET-06|DET-09|DET-10|DET-11|DET-12|DET-13|DET-14|DET-20)$/.test(detId);
206
+ if (
207
+ isQuotaSavingGuard &&
208
+ (verdict.decision === 'deny' || verdict.decision === 'ask' || verdict.decision === 'defer' || Boolean(verdict.astSignatureStub) || Boolean(verdict.deltaDiffStub)) &&
209
+ options.recordLedger !== false &&
210
+ Boolean(event.cwd || options.cwd || options.ledgerPath || options.recordLedger)
211
+ ) {
212
+ const isPrefixFence = detId === 'DET-09';
213
+ const isBoundedRead = detId === 'DET-11' || Boolean(verdict.astSignatureStub) || Boolean(verdict.deltaDiffStub);
214
+ const estimatedSavedTokens = Math.max(
215
+ 0,
216
+ Number(
217
+ verdict.savedTokens ||
218
+ verdict.estimatedTokensSaved ||
219
+ (isPrefixFence ? liveState?.contextWindow?.cachedTokens || 25000 : 4000)
220
+ )
221
+ );
222
+ recordInterventionSavings(
223
+ {
224
+ sessionId,
225
+ category: isPrefixFence
226
+ ? 'DET_09_PREFIX_FENCE'
227
+ : isBoundedRead
228
+ ? 'BOUNDED_READ_ENFORCED'
229
+ : 'LOOP_TURN_PREVENTED',
230
+ modelId: liveState?.modelId || 'claude-sonnet-5-5',
231
+ savedTokens: estimatedSavedTokens,
232
+ savedUSD: Math.max(0, Number(verdict.avoidedPenaltyUSD || 0)),
233
+ dedupeId:
234
+ event.tool_use_id ||
235
+ event.toolUseId ||
236
+ event.turn_id ||
237
+ event.turnId ||
238
+ `${detId}:${event.tool_name || event.toolName || 'tool'}`,
239
+ detail: `${detId} intervention (${verdict.decision}): ${String(verdict.reason || '').slice(0, 120)}`
240
+ },
241
+ cwdOptions
242
+ );
243
+ }
244
+
245
+ if (verdict.decision === 'ask' || verdict.decision === 'defer') {
246
+ const out = {
247
+ hookSpecificOutput: {
248
+ hookEventName: 'PreToolUse',
249
+ permissionDecision: verdict.decision === 'defer' ? 'defer' : 'ask',
250
+ permissionDecisionReason: verdict.reason
251
+ }
252
+ };
253
+ return {
254
+ exitCode: 0,
255
+ stdout: JSON.stringify(out),
256
+ stderr: '',
257
+ verdict
258
+ };
259
+ }
260
+
261
+ if (verdict.decision === 'deny') {
262
+ if (options.useJsonDecision) {
263
+ const out = {
264
+ hookSpecificOutput: {
265
+ hookEventName: 'PreToolUse',
266
+ permissionDecision: 'deny',
267
+ permissionDecisionReason: verdict.reason
268
+ }
269
+ };
270
+ return {
271
+ exitCode: 0,
272
+ stdout: JSON.stringify(out),
273
+ stderr: '',
274
+ verdict
275
+ };
276
+ }
277
+ return {
278
+ exitCode: 2,
279
+ stdout: '',
280
+ stderr: verdict.reason,
281
+ verdict
282
+ };
283
+ }
284
+
285
+ // ISS-034: Coach advisory on 'allow' uses additionalContext so Claude sees the message!
286
+ const out = {
287
+ hookSpecificOutput: {
288
+ hookEventName: 'PreToolUse',
289
+ permissionDecision: 'allow',
290
+ additionalContext: verdict.reason,
291
+ ...(verdict.astSignatureStub ? { astSignatureStub: verdict.astSignatureStub, savedTokens: verdict.savedTokens } : {}),
292
+ ...(verdict.deltaDiffStub ? { deltaDiffStub: verdict.deltaDiffStub, savedTokens: verdict.savedTokens } : {})
293
+ }
294
+ };
295
+ return {
296
+ exitCode: 0,
297
+ stdout: JSON.stringify(out),
298
+ stderr: '',
299
+ verdict,
300
+ ...(verdict.astSignatureStub ? { decision: 'allow', astSignatureStub: verdict.astSignatureStub, savedTokens: verdict.savedTokens } : {}),
301
+ ...(verdict.deltaDiffStub ? { decision: 'allow', deltaDiffStub: verdict.deltaDiffStub, savedTokens: verdict.savedTokens } : {})
302
+ };
303
+ }
304
+
305
+ /**
306
+ * Fail-closed CLI runner for `PreToolUse` (`ISS-035`).
307
+ * Any uncaught error exits `2` via `exitHardBlockStderr` so security/billing guards never fail open.
308
+ *
309
+ * @param {object} [cliOptions={}]
310
+ */
311
+ export async function executePreToolUseCli(cliOptions = {}) {
312
+ const readPayload = cliOptions.readPayload || readStdinJsonAsync;
313
+ const ioOverride = cliOptions.ioOverride || {};
314
+ try {
315
+ const payload = await readPayload(cliOptions.timeoutMs);
316
+ let res;
317
+ if (cliOptions.runHook) {
318
+ res = cliOptions.runHook(payload, { persistState: true, ...(cliOptions.hookOptions || {}) });
319
+ } else {
320
+ const dispatch = await dispatchPreToolUseWithFallback(payload, {
321
+ persistState: true,
322
+ ...(cliOptions.hookOptions || {})
323
+ });
324
+ if (dispatch.source === 'ipc') {
325
+ const ipcRes = dispatch.result;
326
+ if (ipcRes?.decision === 'deny' || ipcRes?.decision === 'block') {
327
+ res = {
328
+ exitCode: 2,
329
+ stderr: ipcRes.reason || ipcRes.hookSpecificOutput?.permissionDecisionReason || '[Highbeam] Tool execution denied'
330
+ };
331
+ } else {
332
+ res = runPreToolUseHook(payload, {
333
+ persistState: true,
334
+ ...(cliOptions.hookOptions || {})
335
+ });
336
+ }
337
+ } else {
338
+ res = dispatch.result;
339
+ }
340
+ }
341
+
342
+ if (res.exitCode === 2) {
343
+ exitHardBlockStderr(res.stderr, 'PreToolUse', ioOverride);
344
+ } else if (res.stdout) {
345
+ exitWithStdoutJson(res.stdout, ioOverride);
346
+ } else {
347
+ exitPassThrough(ioOverride.exitFn);
348
+ }
349
+ } catch (err) {
350
+ exitHardBlockStderr(
351
+ `[Highbeam Fail-Closed] ${err?.message || String(err)}`,
352
+ 'PreToolUse',
353
+ ioOverride
354
+ );
355
+ }
356
+ }
357
+
358
+ if (isCliEntrypoint(import.meta.url)) {
359
+ executePreToolUseCli().catch((err) => {
360
+ exitHardBlockStderr(
361
+ `[Highbeam Fail-Closed] ${err?.message || String(err)}`,
362
+ 'PreToolUse'
363
+ );
364
+ });
365
+ }
@@ -0,0 +1,240 @@
1
+ /**
2
+ * @file hooks/handlers/stop-gate.mjs
3
+ * Tier 2 Command Hook handler for `Stop` (`DET-14` Premature Completion Stop Gate
4
+ * and `DET-15` Batched Stop-Phase Formatter — `ISS-034`, `ISS-035`).
5
+ */
6
+
7
+ import { loadHorizonConfig, resolveDetectorOverride } from '../../src/core-isomorphic/config/horizonConfig.mjs';
8
+ import { isSilentOrOffMode } from '../../src/core-isomorphic/coach/cacheGravityRouter.mjs';
9
+ import {
10
+ evaluateDet14PrematureStopGate,
11
+ evaluateDet15BatchedStopFormatter,
12
+ readBreakerStateSnapshot,
13
+ writeBreakerStateSnapshot
14
+ } from '../../src/core-isomorphic/guards/circuitBreakers.mjs';
15
+ import {
16
+ isCliEntrypoint,
17
+ readStdinJsonAsync,
18
+ exitPassThrough,
19
+ exitDiagnosticZero,
20
+ exitWithStdoutJson
21
+ } from './hookIo.mjs';
22
+
23
+ /**
24
+ * Evaluates a `Stop` hook event for `DET-14` and `DET-15`.
25
+ * Loads `flightMode` from `.attention-horizon.json` and persisted breaker state across CLI spawns (`ISS-038`).
26
+ * Never emits invalid `hookSpecificOutput.permissionDecision` on `Stop` (`ISS-034`):
27
+ * - Blocking (`AUTO_PILOT` & `!stop_hook_active`): returns `exitCode: 0` with `{ decision: 'block', reason }`
28
+ * - Advisory (`COACH` or formatted-files note): returns `exitCode: 0` with `{ systemMessage: reasons }`
29
+ *
30
+ * @param {object} event
31
+ * @param {object} [options={}]
32
+ */
33
+ export function runStopGateHook(event = {}, options = {}) {
34
+ const sessionId = event.session_id || event.sessionId || 'default';
35
+ const cwdOptions = event.cwd && !options.cwd ? { ...options, cwd: event.cwd } : options;
36
+ const horizonConfig = options.horizonConfig || loadHorizonConfig(cwdOptions);
37
+ const effectiveMode = options.mode || event.mode || horizonConfig?.flightMode || 'COACH';
38
+ const stopHookActive = Boolean(event.stop_hook_active ?? event.stopHookActive);
39
+
40
+ const shouldPersistState =
41
+ options.persistState !== false &&
42
+ Boolean(event.cwd || options.cwd || options.breakerStatePath || options.persistState);
43
+
44
+ const breakerSnap = shouldPersistState
45
+ ? readBreakerStateSnapshot(sessionId, cwdOptions)
46
+ : null;
47
+
48
+ if (stopHookActive) {
49
+ if (shouldPersistState && breakerSnap) {
50
+ writeBreakerStateSnapshot(
51
+ sessionId,
52
+ {
53
+ ...breakerSnap,
54
+ updatedAt: Date.now(),
55
+ modifiedFilesInTurn: [],
56
+ editedFiles: [],
57
+ pendingFormatFiles: [],
58
+ codeEditedSinceLastTest: false
59
+ },
60
+ cwdOptions
61
+ );
62
+ }
63
+ return {
64
+ exitCode: 0,
65
+ stdout: '',
66
+ stderr: '',
67
+ det14: {
68
+ detectorId: 'DET-14',
69
+ triggered: false,
70
+ stopHookActive: true,
71
+ decision: 'allow',
72
+ advisory: false,
73
+ reason: null
74
+ },
75
+ det15: {
76
+ detectorId: 'DET-15',
77
+ triggered: false,
78
+ filesToFormat: [],
79
+ batchCommand: null
80
+ }
81
+ };
82
+ }
83
+
84
+ const editedFiles = Array.isArray(event.editedFiles)
85
+ ? event.editedFiles
86
+ : Array.isArray(breakerSnap?.modifiedFilesInTurn)
87
+ ? breakerSnap.modifiedFilesInTurn
88
+ : [];
89
+
90
+ const codeEditedSinceLastTest =
91
+ event.codeEditedSinceLastTest !== undefined
92
+ ? Boolean(event.codeEditedSinceLastTest)
93
+ : breakerSnap?.codeEditedSinceLastTest !== undefined
94
+ ? Boolean(breakerSnap.codeEditedSinceLastTest)
95
+ : editedFiles.length > 0;
96
+
97
+ const modifiedFilesForFormat =
98
+ event.modifiedFiles ||
99
+ event.editedFiles ||
100
+ breakerSnap?.pendingFormatFiles ||
101
+ breakerSnap?.modifiedFilesInTurn ||
102
+ [];
103
+
104
+ let det14 = evaluateDet14PrematureStopGate({
105
+ stopHookActive,
106
+ codeEditedSinceLastTest,
107
+ editedFiles,
108
+ mode: effectiveMode
109
+ });
110
+
111
+ const det14Override = resolveDetectorOverride('DET-14', horizonConfig);
112
+ if (!stopHookActive) {
113
+ if (det14Override === 'off') {
114
+ det14 = {
115
+ detectorId: 'DET-14',
116
+ triggered: false,
117
+ stopHookActive: false,
118
+ decision: 'allow',
119
+ advisory: false,
120
+ overriddenByConfig: 'off',
121
+ reason: null
122
+ };
123
+ } else if (det14Override === 'warn' && det14.decision === 'block') {
124
+ det14 = {
125
+ ...det14,
126
+ decision: 'allow',
127
+ advisory: true,
128
+ overriddenByConfig: 'warn'
129
+ };
130
+ } else if (det14Override === 'block' && codeEditedSinceLastTest) {
131
+ const fileSummary = editedFiles.slice(0, 4).join(', ') || 'workspace source files';
132
+ det14 = {
133
+ detectorId: 'DET-14',
134
+ triggered: true,
135
+ stopHookActive: false,
136
+ decision: 'block',
137
+ advisory: false,
138
+ overriddenByConfig: 'block',
139
+ reason:
140
+ det14.reason ||
141
+ `[DET-14 Premature Stop Gate] Modified ${fileSummary} without running verification tests.`
142
+ };
143
+ }
144
+ }
145
+
146
+ const det15Override = resolveDetectorOverride('DET-15', horizonConfig);
147
+ const suppressDet15 =
148
+ det15Override === 'off' ||
149
+ (isSilentOrOffMode(effectiveMode) && det15Override !== 'warn' && det15Override !== 'block');
150
+
151
+ const det15 = suppressDet15
152
+ ? { detectorId: 'DET-15', triggered: false, filesToFormat: [], batchCommand: null }
153
+ : evaluateDet15BatchedStopFormatter({
154
+ modifiedFiles: modifiedFilesForFormat
155
+ });
156
+
157
+ if (shouldPersistState && breakerSnap && det14.decision !== 'block') {
158
+ writeBreakerStateSnapshot(
159
+ sessionId,
160
+ {
161
+ ...breakerSnap,
162
+ updatedAt: Date.now(),
163
+ modifiedFilesInTurn: [],
164
+ editedFiles: [],
165
+ pendingFormatFiles: [],
166
+ codeEditedSinceLastTest: false
167
+ },
168
+ cwdOptions
169
+ );
170
+ }
171
+
172
+ if (det14.decision === 'block') {
173
+ const stdoutJson = {
174
+ decision: 'block',
175
+ reason: det14.reason
176
+ };
177
+ return {
178
+ exitCode: 0,
179
+ stdout: JSON.stringify(stdoutJson),
180
+ stdoutJson,
181
+ stderr: '',
182
+ det14,
183
+ det15
184
+ };
185
+ }
186
+
187
+ if (det14.advisory || det15.triggered) {
188
+ const reasons = [det14.reason, det15.batchCommand ? `Batch format: ${det15.batchCommand}` : null]
189
+ .filter(Boolean)
190
+ .join(' | ');
191
+ const stdoutJson = {
192
+ systemMessage: reasons
193
+ };
194
+ return {
195
+ exitCode: 0,
196
+ stdout: JSON.stringify(stdoutJson),
197
+ stdoutJson,
198
+ stderr: '',
199
+ det14,
200
+ det15
201
+ };
202
+ }
203
+
204
+ return {
205
+ exitCode: 0,
206
+ stdout: '',
207
+ stderr: '',
208
+ det14,
209
+ det15
210
+ };
211
+ }
212
+
213
+ /**
214
+ * CLI runner for `Stop` (`ISS-035`).
215
+ * Non-blocking lifecycle hook on uncaught internal error: logs diagnostic to stderr and exits `0`.
216
+ *
217
+ * @param {object} [cliOptions={}]
218
+ */
219
+ export async function executeStopGateCli(cliOptions = {}) {
220
+ const readPayload = cliOptions.readPayload || readStdinJsonAsync;
221
+ const runHook = cliOptions.runHook || runStopGateHook;
222
+ const ioOverride = cliOptions.ioOverride || {};
223
+ try {
224
+ const payload = await readPayload(cliOptions.timeoutMs);
225
+ const res = runHook(payload, { persistState: true, ...(cliOptions.hookOptions || {}) });
226
+ if (res.stdout) {
227
+ exitWithStdoutJson(res.stdout, ioOverride);
228
+ } else {
229
+ exitPassThrough(ioOverride.exitFn);
230
+ }
231
+ } catch (err) {
232
+ exitDiagnosticZero(err?.message || String(err), 'StopGate', ioOverride);
233
+ }
234
+ }
235
+
236
+ if (isCliEntrypoint(import.meta.url)) {
237
+ executeStopGateCli().catch((err) => {
238
+ exitDiagnosticZero(err?.message || String(err), 'StopGate');
239
+ });
240
+ }