ctxtop 0.0.0-stage → 4.1.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 (262) hide show
  1. package/.antigravity-plugin/plugin.json +36 -0
  2. package/.claude-plugin/plugin.json +18 -0
  3. package/CHECKSUMS.sha256 +166 -0
  4. package/LICENSE +27 -0
  5. package/README.md +350 -2
  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 +175 -0
  16. package/bin/cli.mjs +3 -0
  17. package/bin/ctxtop.mjs +1799 -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 +133 -0
  25. package/config/modelCatalog.json +785 -0
  26. package/config/platformQuirks.json +19 -0
  27. package/hooks/handlers/compact-lifecycle.mjs +577 -0
  28. package/hooks/handlers/config-change.mjs +402 -0
  29. package/hooks/handlers/hookIo.mjs +311 -0
  30. package/hooks/handlers/hookIpcClient.mjs +83 -0
  31. package/hooks/handlers/post-model-switch.mjs +111 -0
  32. package/hooks/handlers/post-tool-use.mjs +366 -0
  33. package/hooks/handlers/pre-model-switch.mjs +1048 -0
  34. package/hooks/handlers/pre-tool-use.mjs +632 -0
  35. package/hooks/handlers/stop-gate.mjs +526 -0
  36. package/hooks/handlers/user-prompt-submit.mjs +367 -0
  37. package/hooks/hooks.json +131 -0
  38. package/hooks/post_invocation.mjs +13 -0
  39. package/hooks/post_tool_use.mjs +25 -0
  40. package/hooks/pre_invocation.mjs +14 -0
  41. package/hooks/pre_tool_use.mjs +97 -0
  42. package/hooks/register.js +726 -0
  43. package/hooks/session_start.mjs +24 -0
  44. package/hooks/stop.mjs +23 -0
  45. package/hooks.json +56 -0
  46. package/package.json +110 -4
  47. package/packages/antigravity/package.json +14 -0
  48. package/packages/antigravity/src/index.mjs +1 -0
  49. package/packages/claude-code/package.json +14 -0
  50. package/packages/claude-code/src/index.mjs +2 -0
  51. package/packages/core/package.json +14 -0
  52. package/packages/core/src/index.mjs +1 -0
  53. package/packages/engine-node/package.json +14 -0
  54. package/packages/engine-node/src/index.mjs +1 -0
  55. package/packages/mcp/package.json +17 -0
  56. package/packages/mcp/src/server.mjs +396 -0
  57. package/packages/pro/LICENSE-COMMERCIAL.md +19 -0
  58. package/packages/pro/README-SIGNING.md +30 -0
  59. package/packages/pro/package.json +16 -0
  60. package/packages/pro/src/index.mjs +3 -0
  61. package/packages/pro/src/team_finops_pack.mjs +241 -0
  62. package/packages/pro/workers/polar_webhook_worker.mjs +215 -0
  63. package/plugin.json +36 -0
  64. package/rules/AGENTS.md +10 -0
  65. package/sidecars/horizon-daemon/ipcServer.mjs +24 -0
  66. package/sidecars/horizon-daemon/server.mjs +2038 -0
  67. package/sidecars/horizon-daemon/sidecar.json +19 -0
  68. package/skills/cost-radar/SKILL.md +21 -0
  69. package/skills/evolve/SKILL.md +21 -0
  70. package/skills/handoff/SKILL.md +50 -0
  71. package/skills/horizon/SKILL.md +17 -0
  72. package/skills/inspect/SKILL.md +18 -0
  73. package/skills/precheck/SKILL.md +44 -0
  74. package/src/adapters/antigravity/index.mjs +109 -0
  75. package/src/adapters/claude-code/index.mjs +194 -0
  76. package/src/cli/cost_radar.mjs +70 -0
  77. package/src/cli/doctor.mjs +351 -0
  78. package/src/cli/horizon_hud.mjs +888 -0
  79. package/src/cli/init.mjs +425 -0
  80. package/src/cli/postmortem.mjs +515 -0
  81. package/src/coach/cacheGravityRouter.mjs +12 -0
  82. package/src/config/modelCatalog.json +704 -0
  83. package/src/config/platformQuirks.json +19 -0
  84. package/src/core/action_queue.mjs +264 -0
  85. package/src/core/ag_bridge.mjs +346 -0
  86. package/src/core/atomic_io.mjs +124 -0
  87. package/src/core/baseline.mjs +607 -0
  88. package/src/core/blindspot_sensors.mjs +399 -0
  89. package/src/core/bucket_b_runtime.mjs +1200 -0
  90. package/src/core/classifier.mjs +1757 -0
  91. package/src/core/coach/circuit_breakers.mjs +650 -0
  92. package/src/core/coach/contradiction_auditor.mjs +239 -0
  93. package/src/core/coach/effort_advisor.mjs +143 -0
  94. package/src/core/coach/handoff_hydrator.mjs +483 -0
  95. package/src/core/coach/progressive_checkpointer.mjs +551 -0
  96. package/src/core/coach/prompt_decomposer_coach.mjs +141 -0
  97. package/src/core/coach/reflector_queue.mjs +505 -0
  98. package/src/core/coach/saved_quota_ledger.mjs +615 -0
  99. package/src/core/coach/subagent_ipi_sanitizer.mjs +200 -0
  100. package/src/core/coach/subagent_phantom_auditor.mjs +261 -0
  101. package/src/core/coach/task_quota_router.mjs +955 -0
  102. package/src/core/coach/turn_zero_gate.mjs +574 -0
  103. package/src/core/compaction_coach.mjs +1126 -0
  104. package/src/core/config.mjs +214 -0
  105. package/src/core/constants.mjs +1987 -0
  106. package/src/core/detectors_det01_to_16.mjs +1523 -0
  107. package/src/core/doc_indexer.mjs +338 -0
  108. package/src/core/episodic_memory.mjs +135 -0
  109. package/src/core/fts5_output_compressor.mjs +359 -0
  110. package/src/core/git_ledger.mjs +189 -0
  111. package/src/core/handoff_audit.mjs +558 -0
  112. package/src/core/history.mjs +221 -0
  113. package/src/core/hook_diagnostics.mjs +158 -0
  114. package/src/core/horizon_classifier.mjs +326 -0
  115. package/src/core/horizon_config.mjs +802 -0
  116. package/src/core/host_watchdog.mjs +200 -0
  117. package/src/core/layer5_hygiene.mjs +1084 -0
  118. package/src/core/log_resolver.mjs +231 -0
  119. package/src/core/mcp_auditor.mjs +138 -0
  120. package/src/core/micro_skills_store.mjs +91 -0
  121. package/src/core/offenders.mjs +161 -0
  122. package/src/core/parser.mjs +1997 -0
  123. package/src/core/path_canonicalizer.mjs +73 -0
  124. package/src/core/paths.mjs +311 -0
  125. package/src/core/prefix_cache_shield.mjs +386 -0
  126. package/src/core/pro_license.mjs +385 -0
  127. package/src/core/prompt_rubric.mjs +518 -0
  128. package/src/core/pruner.mjs +433 -0
  129. package/src/core/quota.mjs +1860 -0
  130. package/src/core/rsi_instinct_engine.mjs +1197 -0
  131. package/src/core/rsl_clash_auditor.mjs +423 -0
  132. package/src/core/rsl_distiller.mjs +372 -0
  133. package/src/core/rsl_ledger.mjs +969 -0
  134. package/src/core/rsl_triage.mjs +909 -0
  135. package/src/core/sanitizer.mjs +121 -0
  136. package/src/core/session_auditor.mjs +658 -0
  137. package/src/core/session_forensics.mjs +303 -0
  138. package/src/core/session_timeline.mjs +358 -0
  139. package/src/core/settings.mjs +99 -0
  140. package/src/core/shared/detectors.mjs +1342 -0
  141. package/src/core/shared/fnv1a64.mjs +85 -0
  142. package/src/core/shared/handoff_schema.mjs +123 -0
  143. package/src/core/shared/index.mjs +5 -0
  144. package/src/core/shared/ipi_sanitizer.mjs +165 -0
  145. package/src/core/shared/micro_skills.mjs +1 -0
  146. package/src/core/shared/plugin_validator.mjs +202 -0
  147. package/src/core/shared/prompt_hygiene_governor.mjs +1 -0
  148. package/src/core/shield_manager.mjs +1417 -0
  149. package/src/core/sidecar_store.mjs +302 -0
  150. package/src/core/sprint_metrics.mjs +366 -0
  151. package/src/core/sqlite_client.mjs +283 -0
  152. package/src/core/storage_doctor.mjs +358 -0
  153. package/src/core/subagents.mjs +609 -0
  154. package/src/core/swarm_topology.mjs +360 -0
  155. package/src/core/task_quota_router.mjs +1656 -0
  156. package/src/core/telemetry/cache_ttl_watchdog.mjs +284 -0
  157. package/src/core/telemetry/scope_lock_registry.mjs +578 -0
  158. package/src/core/telemetry/shadow_file_detector.mjs +291 -0
  159. package/src/core/telemetry/trajectory_watcher.mjs +259 -0
  160. package/src/core/timeline_svg.mjs +236 -0
  161. package/src/core/tool_surgeon.mjs +305 -0
  162. package/src/core/trajectory_stitcher.mjs +645 -0
  163. package/src/core/u_shaped_optimizer.mjs +789 -0
  164. package/src/core/wal_hygiene.mjs +233 -0
  165. package/src/core-isomorphic/catalog/detectorCatalog.mjs +558 -0
  166. package/src/core-isomorphic/catalog/index.mjs +1 -0
  167. package/src/core-isomorphic/coach/cacheGravityRouter.mjs +1547 -0
  168. package/src/core-isomorphic/coach/microSkills.mjs +1 -0
  169. package/src/core-isomorphic/coach/promptHygieneGovernor.mjs +1 -0
  170. package/src/core-isomorphic/coach/repoCalibration.mjs +254 -0
  171. package/src/core-isomorphic/coach/resumeToolsetAuditor.mjs +321 -0
  172. package/src/core-isomorphic/coach/savedQuotaLedger.mjs +527 -0
  173. package/src/core-isomorphic/coach/smartCompactAdvisor.mjs +305 -0
  174. package/src/core-isomorphic/coach/stateBatonHydrator.mjs +810 -0
  175. package/src/core-isomorphic/coach/ttlWatchdog.mjs +464 -0
  176. package/src/core-isomorphic/config/anthropicModelCatalog.json +606 -0
  177. package/src/core-isomorphic/config/catalogLoader.mjs +1268 -0
  178. package/src/core-isomorphic/config/horizonConfig.mjs +1055 -0
  179. package/src/core-isomorphic/control/callTree.mjs +338 -0
  180. package/src/core-isomorphic/control/coachLatches.mjs +126 -0
  181. package/src/core-isomorphic/control/controlStateMachine.mjs +205 -0
  182. package/src/core-isomorphic/control/index.mjs +49 -0
  183. package/src/core-isomorphic/control/swarmWorktree.mjs +109 -0
  184. package/src/core-isomorphic/control/toolSuspension.mjs +197 -0
  185. package/src/core-isomorphic/diagnostics/drift_guard.mjs +382 -0
  186. package/src/core-isomorphic/diagnostics/index.mjs +9 -0
  187. package/src/core-isomorphic/diagnostics/micro_skills.mjs +471 -0
  188. package/src/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs +888 -0
  189. package/src/core-isomorphic/economics/billingBlocks.mjs +251 -0
  190. package/src/core-isomorphic/economics/cacheGravity.mjs +369 -0
  191. package/src/core-isomorphic/economics/cliffBreaker.mjs +256 -0
  192. package/src/core-isomorphic/economics/driftLatency.mjs +433 -0
  193. package/src/core-isomorphic/economics/dualTtl.mjs +198 -0
  194. package/src/core-isomorphic/economics/index.mjs +47 -0
  195. package/src/core-isomorphic/economics/retentionRadar.mjs +348 -0
  196. package/src/core-isomorphic/guards/bucketBAlphaBeta.mjs +860 -0
  197. package/src/core-isomorphic/guards/bucketBGamma.mjs +442 -0
  198. package/src/core-isomorphic/guards/bucketBHeuristics.mjs +37 -0
  199. package/src/core-isomorphic/guards/circuitBreakers.mjs +1202 -0
  200. package/src/core-isomorphic/guards/det01_03_shell_secret.mjs +1184 -0
  201. package/src/core-isomorphic/guards/det04_12_thrash_rot.mjs +572 -0
  202. package/src/core-isomorphic/guards/det13_20_mcp_scope.mjs +913 -0
  203. package/src/core-isomorphic/guards/docIndexCore.mjs +446 -0
  204. package/src/core-isomorphic/guards/losslessPostSanitizer.mjs +317 -0
  205. package/src/core-isomorphic/guards/slopsquatGate.mjs +551 -0
  206. package/src/core-isomorphic/index.js +27 -0
  207. package/src/core-isomorphic/telemetry/otelExporter.mjs +187 -0
  208. package/src/core-isomorphic/telemetry/scopeLockRegistry.mjs +522 -0
  209. package/src/core-isomorphic/telemetry/sprintMetrics.mjs +327 -0
  210. package/src/core-isomorphic/telemetry/swarmTopology.mjs +152 -0
  211. package/src/core-isomorphic/telemetry/telemetryBridge.mjs +1156 -0
  212. package/src/core-isomorphic/ui/brailleSparkline.mjs +142 -0
  213. package/src/core-isomorphic/ui/costRadarSvg.mjs +276 -0
  214. package/src/core-isomorphic/ui/horizonGrid.mjs +475 -0
  215. package/src/core-isomorphic/ui/horizonPanelHtml.mjs +1237 -0
  216. package/src/core-isomorphic/ui/modViews.mjs +1504 -0
  217. package/src/core-isomorphic/ui/pdfReceiptGenerator.mjs +329 -0
  218. package/src/core-isomorphic/ustf/index.mjs +7 -0
  219. package/src/core-isomorphic/ustf/normalizer.mjs +512 -0
  220. package/src/core-isomorphic/ustf/schema.mjs +186 -0
  221. package/src/core-isomorphic/utils/runtime.mjs +962 -0
  222. package/src/demo/synthetic_states.mjs +661 -0
  223. package/src/diagnostics/bugReportGenerator.mjs +253 -0
  224. package/src/diagnostics/claudeHookCapabilities.mjs +396 -0
  225. package/src/diagnostics/doctorEngine.mjs +295 -0
  226. package/src/engine-node/db/index.mjs +58 -0
  227. package/src/engine-node/db/jsonl_fallback.mjs +184 -0
  228. package/src/engine-node/db/probe.mjs +342 -0
  229. package/src/engine-node/db/sqlite_wrapper.mjs +122 -0
  230. package/src/engine-node/index.mjs +12 -0
  231. package/src/engine-node/ipc/client.mjs +447 -0
  232. package/src/engine-node/ipc/index.mjs +22 -0
  233. package/src/engine-node/ipc/protocol.mjs +177 -0
  234. package/src/engine-node/ipc/server.mjs +445 -0
  235. package/src/engine-node/offloader/index.mjs +6 -0
  236. package/src/engine-node/offloader/tool_offloader.mjs +241 -0
  237. package/src/engine-node/sensors/blindspots.mjs +376 -0
  238. package/src/engine-node/sensors/git_merge_tree.mjs +223 -0
  239. package/src/engine-node/sensors/index.mjs +7 -0
  240. package/src/hooks/antigravity_rsl_hook.mjs +250 -0
  241. package/src/hooks/claude_rsl_hook.mjs +288 -0
  242. package/src/hooks/portfolio_runtime.mjs +858 -0
  243. package/src/hooks/post_invocation.mjs +611 -0
  244. package/src/hooks/pre_invocation.mjs +1725 -0
  245. package/src/hooks/session_start.mjs +199 -0
  246. package/src/shims/agy_cli_compressor.mjs +705 -0
  247. package/src/shims/agy_git_guard.mjs +749 -0
  248. package/src/shims/ah_log_query.mjs +39 -0
  249. package/src/ui/costRadarSvg.mjs +6 -0
  250. package/src/ui/horizonGrid.mjs +1 -0
  251. package/src/ui/horizonPanelHtml.mjs +1 -0
  252. package/src/ui/horizon_panel.css +167 -0
  253. package/src/ui/horizon_panel.js +212 -0
  254. package/src/ui/modViews.mjs +1 -0
  255. package/src/utils/modelSwitchTelemetry.mjs +308 -0
  256. package/src/utils/nodeIo.mjs +59 -0
  257. package/src/utils/runtime.mjs +1 -0
  258. package/src/utils/sessionCalibration.mjs +657 -0
  259. package/src/webview/advanced_view.html +1808 -0
  260. package/src/webview/horizon_panel.html +12397 -0
  261. package/src/webview/registry.mjs +80 -0
  262. package/src/webview/simple_view.html +1370 -0
@@ -0,0 +1,526 @@
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 { evaluateSmartCompactSuggestion } from '../../src/core-isomorphic/coach/smartCompactAdvisor.mjs';
10
+ import { computeActiveToolsetHash } from '../../src/core-isomorphic/coach/resumeToolsetAuditor.mjs';
11
+ import { readLiveStateSnapshot } from '../../src/core-isomorphic/telemetry/telemetryBridge.mjs';
12
+ import { updateSessionCalibrationOnStop } from '../../src/utils/sessionCalibration.mjs';
13
+ import {
14
+ evaluateDet14PrematureStopGate,
15
+ evaluateDet15BatchedStopFormatter,
16
+ readBreakerStateSnapshot,
17
+ writeBreakerStateSnapshot
18
+ } from '../../src/core-isomorphic/guards/circuitBreakers.mjs';
19
+ import { runBucketBStopPass } from '../../src/core/bucket_b_runtime.mjs';
20
+ import { handleClaudeRslHook } from '../../src/hooks/claude_rsl_hook.mjs';
21
+ import {
22
+ isCliEntrypoint,
23
+ readStdinJsonAsync,
24
+ exitPassThrough,
25
+ exitDiagnosticZero,
26
+ exitWithStdoutJson
27
+ } from './hookIo.mjs';
28
+
29
+ /**
30
+ * Evaluates a `Stop` hook event for `DET-14` and `DET-15`.
31
+ * Loads `flightMode` from `.attention-horizon.json` and persisted breaker state across CLI spawns (`ISS-038`).
32
+ * Never emits invalid `hookSpecificOutput.permissionDecision` on `Stop` (`ISS-034`):
33
+ * - Blocking (`AUTO_PILOT` & `!stop_hook_active`): returns `exitCode: 0` with `{ decision: 'block', reason }`
34
+ * - Advisory (`COACH` or formatted-files note): returns `exitCode: 0` with `{ systemMessage: reasons }`
35
+ *
36
+ * @param {object} event
37
+ * @param {object} [options={}]
38
+ */
39
+ export function runStopGateHook(event = {}, options = {}) {
40
+ const sessionId = event.session_id || event.sessionId || 'default';
41
+ const cwdOptions = event.cwd && !options.cwd ? { ...options, cwd: event.cwd } : options;
42
+ const horizonConfig = options.horizonConfig || loadHorizonConfig(cwdOptions);
43
+ const effectiveMode = options.mode || event.mode || horizonConfig?.flightMode || 'COACH';
44
+ const stopHookActive = Boolean(event.stop_hook_active ?? event.stopHookActive);
45
+ const isSessionEnd =
46
+ String(options.phase || event.phase || '').toLowerCase() === 'end' ||
47
+ event.hook_event_name === 'SessionEnd';
48
+
49
+ const shouldPersistState =
50
+ options.persistState !== false &&
51
+ Boolean(event.cwd || options.cwd || options.breakerStatePath || options.persistState);
52
+
53
+ const breakerSnap = shouldPersistState
54
+ ? readBreakerStateSnapshot(sessionId, cwdOptions)
55
+ : null;
56
+
57
+ const rawBgTasks =
58
+ event.active_background_tasks ??
59
+ event.activeBackgroundTasks ??
60
+ event.backgroundTasks ??
61
+ breakerSnap?.activeBackgroundTasks ??
62
+ [];
63
+ const activeBackgroundTasks = Array.isArray(rawBgTasks)
64
+ ? rawBgTasks
65
+ .filter(Boolean)
66
+ .map((t) => (typeof t === 'string' ? t : String(t?.id || t?.command || 'bg_task')))
67
+ : [];
68
+ const bgDrainWarning =
69
+ activeBackgroundTasks.length > 0 && !isSilentOrOffMode(effectiveMode)
70
+ ? `[Highbeam Quota Shield — Orphan Background Drain (#10)] ${activeBackgroundTasks.length} active background task(s) still running (${activeBackgroundTasks.slice(0, 3).join(', ')}). Terminate orphan daemons/watchers to prevent idle token & CPU drain.`
71
+ : null;
72
+
73
+ if (isSessionEnd) {
74
+ if (shouldPersistState) {
75
+ const liveEnd = options.telemetryState || readLiveStateSnapshot(sessionId, cwdOptions);
76
+ const endContextTokens = Number(
77
+ event.context_tokens ??
78
+ event.contextTokens ??
79
+ event.cached_tokens ??
80
+ event.cachedTokens ??
81
+ liveEnd?.contextWindow?.cachedTokens ??
82
+ breakerSnap?.lastContextTokens ??
83
+ 0
84
+ );
85
+ const endModelId = String(
86
+ event.model || event.modelId || liveEnd?.modelId || breakerSnap?.lastModelId || 'claude-sonnet-5-5'
87
+ );
88
+ const toolsetHash = computeActiveToolsetHash(event, cwdOptions);
89
+ writeBreakerStateSnapshot(
90
+ sessionId,
91
+ {
92
+ ...(breakerSnap || {}),
93
+ updatedAt: Date.now(),
94
+ ...(activeBackgroundTasks.length === 0 ? { activeBackgroundTasks: [] } : {}),
95
+ pending_downshift: null,
96
+ pendingDownshiftModel: null,
97
+ justCompacted: false,
98
+ lastToolsetHash: toolsetHash,
99
+ lastContextTokens: endContextTokens,
100
+ lastModelId: endModelId
101
+ },
102
+ cwdOptions
103
+ );
104
+ if (!stopHookActive && Boolean(event.cwd || options.cwd) && options.enableRsl !== false) {
105
+ try {
106
+ handleClaudeRslHook(event, { ...cwdOptions, event: 'SessionEnd' });
107
+ } catch {
108
+ // Fail open for RSL post-mortem
109
+ }
110
+ }
111
+ }
112
+ if (bgDrainWarning) {
113
+ const stdoutJson = { systemMessage: bgDrainWarning };
114
+ return {
115
+ exitCode: 0,
116
+ stdout: JSON.stringify(stdoutJson),
117
+ stdoutJson,
118
+ stderr: '',
119
+ activeBackgroundTasks,
120
+ bgDrainWarning
121
+ };
122
+ }
123
+ return {
124
+ exitCode: 0,
125
+ stdout: '',
126
+ stderr: '',
127
+ activeBackgroundTasks,
128
+ bgDrainWarning: null
129
+ };
130
+ }
131
+
132
+ const hasDirectOutput =
133
+ event.output_tokens !== undefined ||
134
+ event.outputTokens !== undefined ||
135
+ event.usage?.output_tokens !== undefined;
136
+ const shouldPersistCalibration =
137
+ options.persistCalibration !== false &&
138
+ Boolean(
139
+ event.transcript_path ||
140
+ event.transcriptPath ||
141
+ options.calibrationPath ||
142
+ (hasDirectOutput && (options.homeDir || event.cwd || options.cwd))
143
+ );
144
+ const sessionCalibration = shouldPersistCalibration
145
+ ? updateSessionCalibrationOnStop(event, cwdOptions)
146
+ : null;
147
+
148
+ if (stopHookActive) {
149
+ if (shouldPersistState && breakerSnap) {
150
+ writeBreakerStateSnapshot(
151
+ sessionId,
152
+ {
153
+ ...breakerSnap,
154
+ updatedAt: Date.now(),
155
+ modifiedFilesInTurn: [],
156
+ editedFiles: [],
157
+ pendingFormatFiles: [],
158
+ turnFileDiffs: [],
159
+ codeEditedSinceLastTest: false
160
+ },
161
+ cwdOptions
162
+ );
163
+ }
164
+ return {
165
+ exitCode: 0,
166
+ stdout: '',
167
+ stderr: '',
168
+ sessionCalibration,
169
+ det14: {
170
+ detectorId: 'DET-14',
171
+ triggered: false,
172
+ stopHookActive: true,
173
+ decision: 'allow',
174
+ advisory: false,
175
+ reason: null
176
+ },
177
+ det15: {
178
+ detectorId: 'DET-15',
179
+ triggered: false,
180
+ filesToFormat: [],
181
+ batchCommand: null
182
+ }
183
+ };
184
+ }
185
+
186
+ const editedFiles = Array.isArray(event.editedFiles)
187
+ ? event.editedFiles
188
+ : Array.isArray(breakerSnap?.modifiedFilesInTurn)
189
+ ? breakerSnap.modifiedFilesInTurn
190
+ : [];
191
+
192
+ const codeEditedSinceLastTest =
193
+ event.codeEditedSinceLastTest !== undefined
194
+ ? Boolean(event.codeEditedSinceLastTest)
195
+ : breakerSnap?.codeEditedSinceLastTest !== undefined
196
+ ? Boolean(breakerSnap.codeEditedSinceLastTest)
197
+ : editedFiles.length > 0;
198
+
199
+ const modifiedFilesForFormat =
200
+ event.modifiedFiles ||
201
+ event.editedFiles ||
202
+ breakerSnap?.pendingFormatFiles ||
203
+ breakerSnap?.modifiedFilesInTurn ||
204
+ [];
205
+
206
+ let det14 = evaluateDet14PrematureStopGate({
207
+ stopHookActive,
208
+ codeEditedSinceLastTest,
209
+ editedFiles,
210
+ mode: effectiveMode
211
+ });
212
+
213
+ const det14Override = resolveDetectorOverride('DET-14', horizonConfig);
214
+ if (!stopHookActive) {
215
+ if (det14Override === 'off') {
216
+ det14 = {
217
+ detectorId: 'DET-14',
218
+ triggered: false,
219
+ stopHookActive: false,
220
+ decision: 'allow',
221
+ advisory: false,
222
+ overriddenByConfig: 'off',
223
+ reason: null
224
+ };
225
+ } else if (det14Override === 'warn' && det14.decision === 'block') {
226
+ det14 = {
227
+ ...det14,
228
+ decision: 'allow',
229
+ advisory: true,
230
+ overriddenByConfig: 'warn'
231
+ };
232
+ } else if (det14Override === 'block' && codeEditedSinceLastTest) {
233
+ const fileSummary = editedFiles.slice(0, 4).join(', ') || 'workspace source files';
234
+ det14 = {
235
+ detectorId: 'DET-14',
236
+ triggered: true,
237
+ stopHookActive: false,
238
+ decision: 'block',
239
+ advisory: false,
240
+ overriddenByConfig: 'block',
241
+ reason:
242
+ det14.reason ||
243
+ `[DET-14 Premature Stop Gate] Modified ${fileSummary} without running verification tests.`
244
+ };
245
+ }
246
+ }
247
+
248
+ const det15Override = resolveDetectorOverride('DET-15', horizonConfig);
249
+ const suppressDet15 =
250
+ det15Override === 'off' ||
251
+ (isSilentOrOffMode(effectiveMode) && det15Override !== 'warn' && det15Override !== 'block');
252
+
253
+ const det15 = suppressDet15
254
+ ? { detectorId: 'DET-15', triggered: false, filesToFormat: [], batchCommand: null }
255
+ : evaluateDet15BatchedStopFormatter({
256
+ modifiedFiles: modifiedFilesForFormat
257
+ });
258
+
259
+ let stopPass = null;
260
+ if (
261
+ !isSessionEnd &&
262
+ !stopHookActive &&
263
+ det14.decision !== 'block' &&
264
+ String(effectiveMode).toUpperCase() !== 'OFF' &&
265
+ options.bucketBShadow !== false &&
266
+ event.bucketBShadow !== false
267
+ ) {
268
+ const turnFileDiffs = Array.isArray(event.fileDiffs)
269
+ ? event.fileDiffs
270
+ : Array.isArray(breakerSnap?.turnFileDiffs)
271
+ ? breakerSnap.turnFileDiffs
272
+ : [];
273
+ const lastUserPrompt = String(
274
+ event.lastUserPrompt ?? event.prompt ?? breakerSnap?.lastUserPrompt ?? ''
275
+ );
276
+ if (turnFileDiffs.length > 0) {
277
+ try {
278
+ stopPass = runBucketBStopPass({
279
+ platform: 'claude',
280
+ sessionId,
281
+ cwd: event.cwd || options.cwd || '',
282
+ hasExplicitCwd: Boolean(event.cwd || options.cwd),
283
+ fileDiffs: turnFileDiffs,
284
+ lastUserPrompt,
285
+ options: { ...options, mode: effectiveMode, horizonConfig }
286
+ });
287
+ } catch (_stopPassErr) {
288
+ stopPass = null;
289
+ }
290
+ }
291
+ }
292
+
293
+ const liveForStop =
294
+ shouldPersistState ||
295
+ event.smartCompactBoundarySuggest !== undefined ||
296
+ options.smartCompactBoundarySuggest !== undefined ||
297
+ horizonConfig?.thresholds?.smartCompactBoundarySuggest
298
+ ? (options.telemetryState || readLiveStateSnapshot(sessionId, cwdOptions))
299
+ : null;
300
+ const currentContextTokens = Number(
301
+ event.context_tokens ??
302
+ event.contextTokens ??
303
+ event.cached_tokens ??
304
+ event.cachedTokens ??
305
+ liveForStop?.contextWindow?.cachedTokens ??
306
+ breakerSnap?.lastContextTokens ??
307
+ 0
308
+ );
309
+ const currentModelId = String(
310
+ event.model ||
311
+ event.modelId ||
312
+ liveForStop?.modelId ||
313
+ breakerSnap?.lastModelId ||
314
+ 'claude-sonnet-5-5'
315
+ );
316
+ const effectiveTurnsSinceLastCompact =
317
+ event.turns_since_last_compact ??
318
+ event.turnsSinceLastCompact ??
319
+ breakerSnap?.turnsSinceLastCompact ??
320
+ null;
321
+ const boundaryReached = Boolean(
322
+ event.boundary_detected ?? event.boundaryDetected ?? breakerSnap?.turnBoundaryReached
323
+ );
324
+ const midDebugActive = Boolean(
325
+ event.mid_debug ??
326
+ event.midDebug ??
327
+ breakerSnap?.turnMidDebug ??
328
+ breakerSnap?.taskBoundaryState?.openFailure
329
+ );
330
+ const smartCompactSuggestion =
331
+ det14.decision === 'block' ||
332
+ stopPass?.decision === 'block' ||
333
+ isSilentOrOffMode(effectiveMode) ||
334
+ stopHookActive
335
+ ? { shouldSuggest: false, suppressedReason: 'blocked_or_silent', detectorStatus: 'unverified', message: null }
336
+ : evaluateSmartCompactSuggestion(
337
+ {
338
+ enabled:
339
+ event.smartCompactBoundarySuggest ??
340
+ options.smartCompactBoundarySuggest ??
341
+ horizonConfig?.thresholds?.smartCompactBoundarySuggest ??
342
+ false,
343
+ detectorState: midDebugActive
344
+ ? 'mid_debug'
345
+ : boundaryReached
346
+ ? 'task_boundary'
347
+ : (event.detectorState || 'other'),
348
+ boundaryDetected: boundaryReached,
349
+ openFailure: Boolean(breakerSnap?.taskBoundaryState?.openFailure),
350
+ consecutiveFailures: Number(breakerSnap?.consecutiveFailures || 0),
351
+ turnsSinceLastCompact: effectiveTurnsSinceLastCompact,
352
+ modelId: currentModelId,
353
+ preCompactTokens: currentContextTokens,
354
+ cacheTtlTier: liveForStop?.promptCache?.ttlTier === '1h' ? '1h' : '5m',
355
+ expectedRemainingRequests:
356
+ event.expected_remaining_requests ?? event.expectedRemainingRequests,
357
+ expectedRemainingTurns:
358
+ event.expected_remaining_turns ??
359
+ event.expectedRemainingTurns ??
360
+ horizonConfig?.expectedRemainingTurns,
361
+ turnsCompleted: sessionCalibration?.turnsCompleted ?? liveForStop?.turnsCompleted ?? 0,
362
+ apiCallsCompleted: sessionCalibration?.apiCallsCompleted,
363
+ requestsPerTurn:
364
+ event.requests_per_turn ??
365
+ event.requestsPerTurn ??
366
+ sessionCalibration?.requestsPerTurn,
367
+ contextGrowthPerTurn: sessionCalibration?.rollingMedianPromptGrowthTokens,
368
+ contextCeiling: liveForStop?.contextWindow?.contextCeiling
369
+ },
370
+ { ...cwdOptions, horizonConfig }
371
+ );
372
+
373
+ if (shouldPersistState && det14.decision !== 'block') {
374
+ const nextTurnsSinceCompact =
375
+ typeof breakerSnap?.turnsSinceLastCompact === 'number' &&
376
+ Number.isFinite(breakerSnap.turnsSinceLastCompact)
377
+ ? breakerSnap.turnsSinceLastCompact + 1
378
+ : null;
379
+ const toolsetHash =
380
+ event.cwd || cwdOptions.cwd || event.tools || event.mcp_servers || options.cliArgs || event.cliArgs
381
+ ? computeActiveToolsetHash(event, cwdOptions)
382
+ : (breakerSnap?.lastToolsetHash || null);
383
+ writeBreakerStateSnapshot(
384
+ sessionId,
385
+ {
386
+ ...(breakerSnap || {}),
387
+ updatedAt: Date.now(),
388
+ modifiedFilesInTurn: [],
389
+ editedFiles: [],
390
+ pendingFormatFiles: [],
391
+ turnFileDiffs: [],
392
+ codeEditedSinceLastTest: false,
393
+ justCompacted: false,
394
+ turnBoundaryReached: false,
395
+ turnMidDebug: false,
396
+ ...(nextTurnsSinceCompact !== null ? { turnsSinceLastCompact: nextTurnsSinceCompact } : {}),
397
+ ...(toolsetHash ? { lastToolsetHash: toolsetHash } : {}),
398
+ lastContextTokens: currentContextTokens,
399
+ lastModelId: currentModelId
400
+ },
401
+ cwdOptions
402
+ );
403
+ if (!stopHookActive && Boolean(event.cwd || options.cwd) && options.enableRsl !== false) {
404
+ try {
405
+ handleClaudeRslHook(event, { ...cwdOptions, event: 'Stop' });
406
+ } catch {
407
+ // Fail open for RSL post-mortem
408
+ }
409
+ }
410
+ }
411
+
412
+ if (det14.decision === 'block') {
413
+ const locSuffix = breakerSnap?.lastFailingLocation
414
+ ? ` (last failing location: ${breakerSnap.lastFailingLocation})`
415
+ : '';
416
+ const stdoutJson = {
417
+ decision: 'block',
418
+ reason: `${det14.reason}${locSuffix}`
419
+ };
420
+ return {
421
+ exitCode: 0,
422
+ stdout: JSON.stringify(stdoutJson),
423
+ stdoutJson,
424
+ stderr: '',
425
+ sessionCalibration,
426
+ det14,
427
+ det15,
428
+ smartCompactSuggestion,
429
+ activeBackgroundTasks
430
+ };
431
+ }
432
+
433
+ if (stopPass?.triggered && stopPass.decision === 'block') {
434
+ const stdoutJson = {
435
+ decision: 'block',
436
+ reason: stopPass.reason
437
+ };
438
+ return {
439
+ exitCode: 0,
440
+ stdout: JSON.stringify(stdoutJson),
441
+ stdoutJson,
442
+ stderr: '',
443
+ sessionCalibration,
444
+ det14,
445
+ det15,
446
+ smartCompactSuggestion,
447
+ overengineeringGate: stopPass,
448
+ activeBackgroundTasks
449
+ };
450
+ }
451
+
452
+ if (det14.advisory || det15.triggered || bgDrainWarning || stopPass?.triggered || smartCompactSuggestion.shouldSuggest) {
453
+ const reasons = [
454
+ det14.advisory ? det14.reason : null,
455
+ det15.batchCommand ? `Batch format: ${det15.batchCommand}` : null,
456
+ bgDrainWarning,
457
+ stopPass?.triggered ? stopPass.reason : null,
458
+ smartCompactSuggestion.shouldSuggest ? smartCompactSuggestion.message : null
459
+ ]
460
+ .filter(Boolean)
461
+ .join(' | ');
462
+ const stdoutJson = {
463
+ systemMessage: reasons
464
+ };
465
+ return {
466
+ exitCode: 0,
467
+ stdout: JSON.stringify(stdoutJson),
468
+ stdoutJson,
469
+ stderr: '',
470
+ sessionCalibration,
471
+ det14,
472
+ det15,
473
+ smartCompactSuggestion,
474
+ ...(stopPass ? { overengineeringGate: stopPass } : {}),
475
+ activeBackgroundTasks
476
+ };
477
+ }
478
+
479
+ return {
480
+ exitCode: 0,
481
+ stdout: '',
482
+ stderr: '',
483
+ sessionCalibration,
484
+ det14,
485
+ det15,
486
+ smartCompactSuggestion,
487
+ ...(stopPass ? { overengineeringGate: stopPass } : {}),
488
+ activeBackgroundTasks
489
+ };
490
+ }
491
+
492
+ /**
493
+ * CLI runner for `Stop` and `SessionEnd` (`--phase=end`) (`ISS-035`).
494
+ * Non-blocking lifecycle hook on uncaught internal error: logs diagnostic to stderr and exits `0`.
495
+ *
496
+ * @param {object} [cliOptions={}]
497
+ */
498
+ export async function executeStopGateCli(cliOptions = {}) {
499
+ const readPayload = cliOptions.readPayload || readStdinJsonAsync;
500
+ const runHook = cliOptions.runHook || runStopGateHook;
501
+ const ioOverride = cliOptions.ioOverride || {};
502
+ try {
503
+ const argv = cliOptions.argv || globalThis.process?.argv || [];
504
+ const phaseArg = argv.find((a) => String(a).startsWith('--phase='));
505
+ const explicitPhase = phaseArg ? String(phaseArg).split('=')[1] : undefined;
506
+ const payload = await readPayload(cliOptions.timeoutMs);
507
+ const res = runHook(payload, {
508
+ persistState: true,
509
+ ...(cliOptions.hookOptions || {}),
510
+ ...(explicitPhase ? { phase: explicitPhase } : {})
511
+ });
512
+ if (res.stdout) {
513
+ exitWithStdoutJson(res.stdout, ioOverride);
514
+ } else {
515
+ exitPassThrough(ioOverride.exitFn);
516
+ }
517
+ } catch (err) {
518
+ exitDiagnosticZero(err?.message || String(err), 'StopGate', ioOverride);
519
+ }
520
+ }
521
+
522
+ if (isCliEntrypoint(import.meta.url)) {
523
+ executeStopGateCli().catch((err) => {
524
+ exitDiagnosticZero(err?.message || String(err), 'StopGate');
525
+ });
526
+ }