ctxtop 4.0.0 → 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 (89) hide show
  1. package/.antigravity-plugin/plugin.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/CHECKSUMS.sha256 +59 -42
  4. package/README.md +351 -330
  5. package/bin/ah-statusline.mjs +30 -0
  6. package/bin/ctxtop.mjs +330 -5
  7. package/config/default_flightcheck.json +19 -0
  8. package/config/modelCatalog.json +165 -0
  9. package/hooks/handlers/compact-lifecycle.mjs +323 -8
  10. package/hooks/handlers/config-change.mjs +402 -0
  11. package/hooks/handlers/hookIo.mjs +56 -0
  12. package/hooks/handlers/post-model-switch.mjs +111 -0
  13. package/hooks/handlers/post-tool-use.mjs +117 -16
  14. package/hooks/handlers/pre-model-switch.mjs +823 -24
  15. package/hooks/handlers/pre-tool-use.mjs +271 -4
  16. package/hooks/handlers/stop-gate.mjs +297 -11
  17. package/hooks/handlers/user-prompt-submit.mjs +224 -0
  18. package/hooks/hooks.json +50 -0
  19. package/hooks/post_tool_use.mjs +8 -0
  20. package/hooks/register.js +48 -9
  21. package/hooks/session_start.mjs +11 -1
  22. package/hooks/stop.mjs +11 -1
  23. package/package.json +11 -4
  24. package/packages/antigravity/package.json +1 -1
  25. package/packages/claude-code/package.json +1 -1
  26. package/packages/core/package.json +1 -1
  27. package/packages/engine-node/package.json +1 -1
  28. package/packages/mcp/package.json +1 -1
  29. package/packages/mcp/src/server.mjs +1 -1
  30. package/packages/pro/package.json +1 -1
  31. package/plugin.json +1 -1
  32. package/sidecars/horizon-daemon/server.mjs +38 -2
  33. package/skills/handoff/SKILL.md +8 -0
  34. package/src/adapters/antigravity/index.mjs +31 -1
  35. package/src/adapters/claude-code/index.mjs +40 -1
  36. package/src/cli/horizon_hud.mjs +254 -52
  37. package/src/config/modelCatalog.json +84 -0
  38. package/src/core/bucket_b_runtime.mjs +1200 -0
  39. package/src/core/constants.mjs +191 -4
  40. package/src/core/detectors_det01_to_16.mjs +54 -5
  41. package/src/core/doc_indexer.mjs +338 -0
  42. package/src/core/layer5_hygiene.mjs +118 -0
  43. package/src/core/parser.mjs +2 -1
  44. package/src/core/paths.mjs +3 -2
  45. package/src/core/rsl_clash_auditor.mjs +423 -0
  46. package/src/core/rsl_distiller.mjs +372 -0
  47. package/src/core/rsl_ledger.mjs +969 -0
  48. package/src/core/rsl_triage.mjs +909 -0
  49. package/src/core/session_auditor.mjs +658 -0
  50. package/src/core/shield_manager.mjs +1417 -0
  51. package/src/core/task_quota_router.mjs +1 -1
  52. package/src/core-isomorphic/coach/cacheGravityRouter.mjs +874 -47
  53. package/src/core-isomorphic/coach/resumeToolsetAuditor.mjs +321 -0
  54. package/src/core-isomorphic/coach/smartCompactAdvisor.mjs +305 -0
  55. package/src/core-isomorphic/coach/ttlWatchdog.mjs +13 -6
  56. package/src/core-isomorphic/config/anthropicModelCatalog.json +404 -1
  57. package/src/core-isomorphic/config/catalogLoader.mjs +546 -46
  58. package/src/core-isomorphic/config/horizonConfig.mjs +47 -1
  59. package/src/core-isomorphic/diagnostics/prompt_hygiene_governor.mjs +266 -0
  60. package/src/core-isomorphic/economics/cacheGravity.mjs +18 -0
  61. package/src/core-isomorphic/economics/cliffBreaker.mjs +98 -12
  62. package/src/core-isomorphic/economics/driftLatency.mjs +114 -0
  63. package/src/core-isomorphic/guards/bucketBAlphaBeta.mjs +860 -0
  64. package/src/core-isomorphic/guards/bucketBGamma.mjs +442 -0
  65. package/src/core-isomorphic/guards/bucketBHeuristics.mjs +37 -0
  66. package/src/core-isomorphic/guards/circuitBreakers.mjs +191 -191
  67. package/src/core-isomorphic/guards/det01_03_shell_secret.mjs +154 -5
  68. package/src/core-isomorphic/guards/det04_12_thrash_rot.mjs +103 -11
  69. package/src/core-isomorphic/guards/det13_20_mcp_scope.mjs +311 -1
  70. package/src/core-isomorphic/guards/docIndexCore.mjs +446 -0
  71. package/src/core-isomorphic/guards/losslessPostSanitizer.mjs +16 -0
  72. package/src/core-isomorphic/guards/slopsquatGate.mjs +551 -0
  73. package/src/core-isomorphic/index.js +1 -0
  74. package/src/core-isomorphic/telemetry/telemetryBridge.mjs +36 -12
  75. package/src/core-isomorphic/ui/horizonPanelHtml.mjs +293 -237
  76. package/src/core-isomorphic/ui/modViews.mjs +35 -9
  77. package/src/diagnostics/claudeHookCapabilities.mjs +396 -0
  78. package/src/diagnostics/doctorEngine.mjs +95 -3
  79. package/src/engine-node/db/probe.mjs +234 -2
  80. package/src/engine-node/index.mjs +3 -0
  81. package/src/engine-node/sensors/blindspots.mjs +13 -6
  82. package/src/hooks/antigravity_rsl_hook.mjs +250 -0
  83. package/src/hooks/claude_rsl_hook.mjs +288 -0
  84. package/src/hooks/post_invocation.mjs +196 -4
  85. package/src/hooks/pre_invocation.mjs +732 -22
  86. package/src/hooks/session_start.mjs +39 -1
  87. package/src/utils/modelSwitchTelemetry.mjs +308 -0
  88. package/src/utils/sessionCalibration.mjs +657 -0
  89. package/src/webview/horizon_panel.html +1325 -317
@@ -3,12 +3,30 @@
3
3
  * Tier 2 Command Hook handler for `PreModelSwitch` (`DET-08` Warm KV-Cache Cross-Model Switch Guard).
4
4
  */
5
5
 
6
+ import { fs, path, os, readJsonSafe, writeJsonAtomic } from '../../src/utils/nodeIo.mjs';
7
+ import {
8
+ DEFAULT_RPT_SHRINKAGE_PRIOR,
9
+ isRealHumanUserTranscriptEntry,
10
+ readSessionCalibration,
11
+ shrinkRollingOutputEstimate,
12
+ shrinkRollingRequestsPerTurn,
13
+ computeRollingMedianFloat
14
+ } from '../../src/utils/sessionCalibration.mjs';
6
15
  import { readLiveStateSnapshot } from '../../src/core-isomorphic/telemetry/telemetryBridge.mjs';
7
- import { computeTotalPromptTokens } from '../../src/core-isomorphic/config/catalogLoader.mjs';
16
+ import {
17
+ computeTotalPromptTokens,
18
+ isKnownCatalogModel,
19
+ normalizeModelId
20
+ } from '../../src/core-isomorphic/config/catalogLoader.mjs';
21
+ import {
22
+ readBreakerStateSnapshot,
23
+ writeBreakerStateSnapshot
24
+ } from '../../src/core-isomorphic/guards/circuitBreakers.mjs';
8
25
  import { loadHorizonConfig, resolveDetectorOverride } from '../../src/core-isomorphic/config/horizonConfig.mjs';
9
26
  import { CacheGravityRouter } from '../../src/core-isomorphic/coach/cacheGravityRouter.mjs';
10
27
  import { recordInterventionSavings } from '../../src/core-isomorphic/coach/savedQuotaLedger.mjs';
11
28
  import { requireProFeature } from '../../src/core/pro_license.mjs';
29
+ import { recordPreModelSwitchEvent } from '../../src/utils/modelSwitchTelemetry.mjs';
12
30
  import {
13
31
  isCliEntrypoint,
14
32
  readStdinJsonAsync,
@@ -17,6 +35,213 @@ import {
17
35
  exitWithStdoutJson
18
36
  } from './hookIo.mjs';
19
37
 
38
+ const PRIOR_CACHE_TTL_MS = 3_600_000;
39
+
40
+ export const MIN_LOCAL_RPT_PRIOR_SESSIONS = 3;
41
+
42
+ function isExcludedBenchmarkTranscript(filePath = '', content = '') {
43
+ const normPath = String(filePath || '').replace(/\\/g, '/').toLowerCase();
44
+ if (
45
+ normPath.includes('model-switch-benchmark') ||
46
+ normPath.includes('smart-compact') ||
47
+ normPath.includes('e2e_harness') ||
48
+ normPath.includes('ctxtop-model-switch')
49
+ ) {
50
+ return true;
51
+ }
52
+ if (typeof content === 'string' && content.includes('Benchmark-Run-Salt:')) {
53
+ return true;
54
+ }
55
+ return false;
56
+ }
57
+
58
+ /**
59
+ * Samples recent local Claude Code session assistant-turn counts and requests/turn (read-only,
60
+ * bounded to 50 files, deduplicated by `message.id`, 1h disk cache under
61
+ * `~/.attention-horizon/cache/ah_session_prior.json`).
62
+ * Excludes the current session (`excludeSessionId` / `excludeTranscriptPath`) and benchmark/harness
63
+ * transcripts (`excludeBenchmarkSessions !== false`), requiring `>= 3` qualifying sessions for
64
+ * `medianRequestsPerTurn`.
65
+ *
66
+ * @param {object} [options={}]
67
+ * @returns {{ apiCounts: number[], medianRequestsPerTurn: number | null, sessionCount: number } | null}
68
+ */
69
+ export function loadLocalClaudeSessionPriors(options = {}) {
70
+ if (Array.isArray(options.historicalSessionApiCalls)) {
71
+ return {
72
+ apiCounts: options.historicalSessionApiCalls,
73
+ medianRequestsPerTurn:
74
+ Number.isFinite(Number(options.historicalSessionRequestsPerTurn))
75
+ ? Number(options.historicalSessionRequestsPerTurn)
76
+ : null,
77
+ sessionCount: options.historicalSessionApiCalls.length
78
+ };
79
+ }
80
+ const home =
81
+ options.homeDir ||
82
+ globalThis.process?.env?.HOME ||
83
+ globalThis.process?.env?.USERPROFILE ||
84
+ os.homedir();
85
+ const cachePath = path.join(home, '.attention-horizon', 'cache', 'ah_session_prior.json');
86
+ const nowMs = Number.isFinite(Number(options.nowMs)) ? Number(options.nowMs) : Date.now();
87
+ const excludeSessionId =
88
+ options.excludeSessionId && options.excludeSessionId !== 'default'
89
+ ? String(options.excludeSessionId).trim()
90
+ : null;
91
+ const excludeTranscriptPathNorm = options.excludeTranscriptPath
92
+ ? path.resolve(String(options.excludeTranscriptPath)).replace(/\\/g, '/').toLowerCase()
93
+ : null;
94
+ const excludeBenchmarks = options.excludeBenchmarkSessions !== false;
95
+
96
+ const cached = readJsonSafe(cachePath, null, options);
97
+ if (
98
+ cached &&
99
+ Array.isArray(cached.sessions) &&
100
+ Number.isFinite(cached.sampledAtMs) &&
101
+ nowMs - cached.sampledAtMs < PRIOR_CACHE_TTL_MS
102
+ ) {
103
+ const filtered = cached.sessions.filter((s) => {
104
+ if (excludeSessionId && s.sessionId === excludeSessionId) return false;
105
+ if (excludeTranscriptPathNorm && s.normPath === excludeTranscriptPathNorm) return false;
106
+ if (excludeBenchmarks && s.isBenchmark) return false;
107
+ return true;
108
+ });
109
+ if (filtered.length >= 1) {
110
+ const apiCounts = filtered.map((s) => s.assistantTurns);
111
+ const rpts = filtered.map((s) => s.rpt).filter((r) => Number.isFinite(r) && r >= 1);
112
+ return {
113
+ apiCounts,
114
+ medianRequestsPerTurn:
115
+ rpts.length >= MIN_LOCAL_RPT_PRIOR_SESSIONS
116
+ ? computeRollingMedianFloat(rpts, rpts.length)
117
+ : null,
118
+ sessionCount: apiCounts.length
119
+ };
120
+ }
121
+ return null;
122
+ }
123
+
124
+ try {
125
+ const ccProjects = path.join(home, '.claude', 'projects');
126
+ if (!fs.existsSync(ccProjects)) return null;
127
+
128
+ const jsonlFiles = [];
129
+ const queue = [ccProjects];
130
+ while (queue.length > 0 && jsonlFiles.length < 150) {
131
+ const dir = queue.shift();
132
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
133
+ const full = path.join(dir, entry.name);
134
+ if (entry.isDirectory()) {
135
+ if (entry.name !== 'subagents') queue.push(full);
136
+ } else if (entry.name.endsWith('.jsonl')) {
137
+ const st = fs.statSync(full);
138
+ if (st.size >= 512 && st.size <= 5_000_000) {
139
+ jsonlFiles.push({ path: full, mtimeMs: st.mtimeMs });
140
+ }
141
+ }
142
+ }
143
+ }
144
+ jsonlFiles.sort((a, b) => b.mtimeMs - a.mtimeMs);
145
+ const allSessions = [];
146
+ for (const item of jsonlFiles.slice(0, 50)) {
147
+ let fd = null;
148
+ try {
149
+ const normPath = path.resolve(item.path).replace(/\\/g, '/').toLowerCase();
150
+ const fileSessionId = path.basename(item.path, '.jsonl');
151
+ fd = fs.openSync(item.path, 'r');
152
+ const txt = fs.readFileSync(fd, 'utf8');
153
+ const isBenchmark = isExcludedBenchmarkTranscript(item.path, txt);
154
+ const assistantMsgIds = new Set();
155
+ let humanTurnCount = 0;
156
+ let idx = 0;
157
+ for (const line of txt.split(/\r?\n/)) {
158
+ idx += 1;
159
+ if (!line.includes('"assistant"') && !line.includes('"user"')) continue;
160
+ try {
161
+ const obj = JSON.parse(line);
162
+ if (isRealHumanUserTranscriptEntry(obj)) {
163
+ humanTurnCount += 1;
164
+ } else if (obj?.type === 'assistant') {
165
+ assistantMsgIds.add(obj?.message?.id || `line_${idx}`);
166
+ }
167
+ } catch {
168
+ if (line.includes('"type":"assistant"')) assistantMsgIds.add(`raw_${idx}`);
169
+ }
170
+ }
171
+ const assistantTurns = assistantMsgIds.size;
172
+ if (assistantTurns >= 2) {
173
+ const rpt =
174
+ humanTurnCount >= 1
175
+ ? Math.max(1, Number((assistantTurns / humanTurnCount).toFixed(4)))
176
+ : null;
177
+ allSessions.push({
178
+ sessionId: fileSessionId,
179
+ normPath,
180
+ isBenchmark,
181
+ assistantTurns,
182
+ rpt
183
+ });
184
+ }
185
+ } catch {
186
+ // Ignore unreadable session file
187
+ } finally {
188
+ if (fd !== null) {
189
+ try {
190
+ fs.closeSync(fd);
191
+ } catch {
192
+ // Ignore close failure
193
+ }
194
+ }
195
+ }
196
+ }
197
+ const filtered = allSessions.filter((s) => {
198
+ if (excludeSessionId && s.sessionId === excludeSessionId) return false;
199
+ if (excludeTranscriptPathNorm && s.normPath === excludeTranscriptPathNorm) return false;
200
+ if (excludeBenchmarks && s.isBenchmark) return false;
201
+ return true;
202
+ });
203
+ const apiCounts = filtered.map((s) => s.assistantTurns);
204
+ const sessionRpts = filtered.map((s) => s.rpt).filter((r) => Number.isFinite(r) && r >= 1);
205
+ const medianRequestsPerTurn =
206
+ sessionRpts.length >= MIN_LOCAL_RPT_PRIOR_SESSIONS
207
+ ? computeRollingMedianFloat(sessionRpts, sessionRpts.length)
208
+ : null;
209
+ if (allSessions.length >= 1) {
210
+ writeJsonAtomic(
211
+ cachePath,
212
+ {
213
+ sampledAtMs: nowMs,
214
+ sessions: allSessions,
215
+ apiCounts,
216
+ medianRequestsPerTurn,
217
+ sessionCount: apiCounts.length
218
+ },
219
+ options
220
+ );
221
+ }
222
+ if (apiCounts.length >= 1) {
223
+ return { apiCounts, medianRequestsPerTurn, sessionCount: apiCounts.length };
224
+ }
225
+ } catch {
226
+ // Fallback to built-in 496-session prior
227
+ }
228
+ return null;
229
+ }
230
+
231
+ /**
232
+ * Backward-compatible accessor returning `apiCounts` once >= 5 local sessions exist
233
+ * (or any explicit `options.historicalSessionApiCalls` override).
234
+ * @param {object} [options={}]
235
+ * @returns {number[] | null}
236
+ */
237
+ export function loadLocalClaudeSessionApiCalls(options = {}) {
238
+ if (Array.isArray(options.historicalSessionApiCalls)) {
239
+ return options.historicalSessionApiCalls;
240
+ }
241
+ const priors = loadLocalClaudeSessionPriors(options);
242
+ return Array.isArray(priors?.apiCounts) && priors.apiCounts.length >= 5 ? priors.apiCounts : null;
243
+ }
244
+
20
245
  /**
21
246
  * Evaluates a `PreModelSwitch` event against `CacheGravityRouter` break-even threshold `C*`.
22
247
  * @param {object} event
@@ -61,31 +286,135 @@ export function runPreModelSwitchHook(event = {}, options = {}) {
61
286
  const effectiveMode =
62
287
  rawEffectiveMode === 'AUTO_PILOT' && !proAutoPilot.allowed ? 'COACH' : rawEffectiveMode;
63
288
 
289
+ const rawRemainingTurns =
290
+ event.expected_remaining_turns ??
291
+ event.expectedRemainingTurns ??
292
+ options.expectedRemainingTurns ??
293
+ horizonConfig?.expectedRemainingTurns;
294
+ const useEmpiricalHorizonPrior = Boolean(
295
+ event.use_empirical_horizon_prior ??
296
+ event.useEmpiricalHorizonPrior ??
297
+ options.useEmpiricalHorizonPrior ??
298
+ horizonConfig?.useEmpiricalHorizonPrior
299
+ );
300
+ const sessionCal =
301
+ options.useSessionCalibration === false
302
+ ? null
303
+ : readSessionCalibration(sessionId, event, cwdOptions);
304
+ const turnsCompleted = Number(
305
+ event.current_turn ??
306
+ event.currentTurn ??
307
+ (sessionCal?.turnsCompleted > 0 ? sessionCal.turnsCompleted : undefined) ??
308
+ liveState?.turnsCompleted ??
309
+ 0
310
+ );
311
+ const localPriorsOptions = {
312
+ ...cwdOptions,
313
+ excludeSessionId: sessionId,
314
+ excludeTranscriptPath:
315
+ event.transcript_path || event.transcriptPath || sessionCal?.transcriptPath || null
316
+ };
317
+ const localPriors =
318
+ options.useLocalRptPrior !== false &&
319
+ (options.homeDir ||
320
+ options.cliInvocation ||
321
+ options.useLocalRptPrior === true ||
322
+ useEmpiricalHorizonPrior ||
323
+ Boolean(sessionCal))
324
+ ? loadLocalClaudeSessionPriors(localPriorsOptions)
325
+ : null;
326
+ const localSurvivalApiCalls =
327
+ localPriors && Array.isArray(localPriors.apiCounts) && localPriors.apiCounts.length >= 5
328
+ ? localPriors.apiCounts
329
+ : null;
330
+ const historicalSessionApiCalls =
331
+ useEmpiricalHorizonPrior && (rawRemainingTurns === undefined || rawRemainingTurns === null)
332
+ ? (localSurvivalApiCalls ?? loadLocalClaudeSessionApiCalls(localPriorsOptions))
333
+ : options.historicalSessionApiCalls;
334
+
64
335
  const router =
65
336
  options.router ||
66
337
  new CacheGravityRouter({
67
338
  ...cwdOptions,
339
+ ...(historicalSessionApiCalls ? { historicalSessionApiCalls } : {}),
68
340
  mode: effectiveMode,
69
341
  strictBlock:
70
342
  det08Override === 'block' ? true : (event.strictBlock ?? options.strictBlock)
71
343
  });
72
344
 
345
+ const shouldPersistBreaker =
346
+ options.persistState !== false &&
347
+ Boolean(
348
+ options.persistState === true ||
349
+ options.cliInvocation ||
350
+ options.breakerStatePath ||
351
+ event.persistState ||
352
+ event.cwd
353
+ );
354
+ const breakerSnap = shouldPersistBreaker
355
+ ? readBreakerStateSnapshot(sessionId, cwdOptions)
356
+ : null;
357
+ const justCompacted = Boolean(
358
+ event.just_compacted ?? event.justCompacted ?? breakerSnap?.justCompacted
359
+ );
360
+
73
361
  const currentModel =
74
- event.current_model || event.currentModel || liveState.modelId || 'claude-opus-5-5';
362
+ event.current_model ||
363
+ event.currentModel ||
364
+ event.from_model ||
365
+ event.fromModel ||
366
+ liveState.modelId ||
367
+ 'claude-opus-5-5';
75
368
  const targetModel =
76
- event.target_model || event.targetModel || event.model || 'claude-sonnet-5-5';
77
- const cachedTokens = Number(
369
+ event.target_model ||
370
+ event.targetModel ||
371
+ event.to_model ||
372
+ event.toModel ||
373
+ event.requested_model ||
374
+ event.requestedModel ||
375
+ event.model ||
376
+ 'claude-sonnet-5-5';
377
+ const explicitCachedTokens =
78
378
  event.cached_tokens ??
79
- event.cachedTokens ??
80
- liveState.contextWindow?.cachedTokens ??
81
- 0
379
+ event.cachedTokens ??
380
+ event.context_tokens ??
381
+ event.contextTokens;
382
+ const cachedTokens = Number(
383
+ explicitCachedTokens ??
384
+ (justCompacted
385
+ ? (liveState.contextWindow?.cacheReadTokens ?? liveState.contextWindow?.cachedTokens ?? 0)
386
+ : (liveState.contextWindow?.cachedTokens ?? 0))
387
+ );
388
+ const explicitUncachedWrite =
389
+ event.uncached_write_tokens ?? event.uncachedWriteTokens;
390
+ const uncachedWriteTokens = Math.max(
391
+ 0,
392
+ Number(
393
+ explicitUncachedWrite ??
394
+ (justCompacted ? (liveState.contextWindow?.cacheCreationTokens ?? 0) : 0)
395
+ )
82
396
  );
397
+ const nowMs = Number.isFinite(Number(options.nowMs)) ? Number(options.nowMs) : Date.now();
398
+ const rawExpiresAt = liveState?.promptCache?.expiresAt;
399
+ const liveCacheExpired =
400
+ rawExpiresAt !== null &&
401
+ rawExpiresAt !== undefined &&
402
+ Number.isFinite(Number(rawExpiresAt)) &&
403
+ Number(rawExpiresAt) > 0 &&
404
+ nowMs >= Number(rawExpiresAt);
405
+ const explicitCacheWarm =
406
+ event.cache_warm ??
407
+ event.cacheWarm ??
408
+ event.prompt_cache_warm ??
409
+ event.promptCacheWarm;
83
410
  const cacheWarm =
84
- event.cache_warm !== undefined
85
- ? Boolean(event.cache_warm)
86
- : event.cacheWarm !== undefined
87
- ? Boolean(event.cacheWarm)
88
- : Boolean(liveState.promptCache?.warm);
411
+ explicitCacheWarm !== undefined
412
+ ? Boolean(explicitCacheWarm)
413
+ : liveCacheExpired
414
+ ? false
415
+ : justCompacted && cachedTokens === 0
416
+ ? false
417
+ : Boolean(liveState.promptCache?.warm);
89
418
 
90
419
  const uncachedDeltaTokens = Number(
91
420
  event.uncached_delta_tokens ?? event.uncachedDeltaTokens ?? 0
@@ -93,6 +422,8 @@ export function runPreModelSwitchHook(event = {}, options = {}) {
93
422
  const rawTier =
94
423
  event.cache_ttl_tier ??
95
424
  event.cacheTtlTier ??
425
+ event.cache_ttl ??
426
+ event.cacheTtl ??
96
427
  event.prompt_cache?.ttl ??
97
428
  liveState.promptCache?.ttlTier ??
98
429
  '5m';
@@ -101,23 +432,304 @@ export function runPreModelSwitchHook(event = {}, options = {}) {
101
432
  const usageSource =
102
433
  event.usage || event.context_window?.current_usage || liveState.contextWindow || {};
103
434
  const totalPromptTokens = Math.max(
104
- cachedTokens + uncachedDeltaTokens,
435
+ cachedTokens + uncachedDeltaTokens + uncachedWriteTokens,
105
436
  computeTotalPromptTokens(event),
106
437
  computeTotalPromptTokens(usageSource)
107
438
  );
108
439
 
440
+ const isNativePreModelSwitch = Boolean(
441
+ event.hook_event_name === 'PreModelSwitch' ||
442
+ event.from_model !== undefined ||
443
+ event.to_model !== undefined ||
444
+ event.fromModel !== undefined ||
445
+ event.toModel !== undefined ||
446
+ options.nativeHook === true
447
+ );
448
+ const resolvedAutoPilotDecision =
449
+ det08Override === 'block'
450
+ ? 'deny'
451
+ : (event.autoPilotDecision ??
452
+ options.autoPilotDecision ??
453
+ horizonConfig?.autoPilotDecision ??
454
+ (isNativePreModelSwitch ? 'ask' : 'deny'));
455
+
456
+ const apiCallsCompletedRaw =
457
+ event.api_calls_completed ??
458
+ event.apiCallsCompleted ??
459
+ sessionCal?.apiCallsCompleted;
460
+ const apiCallsCompleted =
461
+ apiCallsCompletedRaw !== undefined &&
462
+ apiCallsCompletedRaw !== null &&
463
+ Number.isFinite(Number(apiCallsCompletedRaw))
464
+ ? Math.max(0, Number(apiCallsCompletedRaw))
465
+ : undefined;
466
+ const explicitRptRaw =
467
+ event.requests_per_turn ?? event.requestsPerTurn ?? options.requestsPerTurn;
468
+ const rptShrinkageMinTurns = Number(
469
+ options.rptShrinkageMinTurns ?? horizonConfig?.thresholds?.rptShrinkageMinTurns ?? 5
470
+ );
471
+ const rptShrinkagePriorDefault = Number(
472
+ options.rptShrinkagePrior ??
473
+ horizonConfig?.thresholds?.rptShrinkagePrior ??
474
+ DEFAULT_RPT_SHRINKAGE_PRIOR
475
+ );
476
+ let requestsPerTurn;
477
+ let rptEstimateSource = `placeholder_rpt_prior_${rptShrinkagePriorDefault}`;
478
+ let rptSampleSize = 0;
479
+ let rawRollingMedianRequestsPerTurn = sessionCal?.rollingMedianRequestsPerTurn ?? null;
480
+ let rawCumulativeRequestsPerTurn = sessionCal?.requestsPerTurn ?? null;
481
+ let rptShrinkageWeight = 0;
482
+ let rptPriorUsed = rptShrinkagePriorDefault;
483
+ let isPlaceholderRptPrior = true;
484
+ let rptTurnsAgree = false;
485
+ let rptEffectiveMinTrustedTurns = rptShrinkageMinTurns;
486
+
487
+ if (
488
+ explicitRptRaw !== undefined &&
489
+ explicitRptRaw !== null &&
490
+ Number.isFinite(Number(explicitRptRaw)) &&
491
+ Number(explicitRptRaw) > 0
492
+ ) {
493
+ requestsPerTurn = Number(explicitRptRaw);
494
+ rptEstimateSource = 'explicit';
495
+ rptSampleSize = Number(sessionCal?.rptSampleSize ?? sessionCal?.turnsCompleted ?? 0);
496
+ rptShrinkageWeight = 1;
497
+ rptPriorUsed = null;
498
+ isPlaceholderRptPrior = false;
499
+ rptTurnsAgree = false;
500
+ rptEffectiveMinTrustedTurns = rptShrinkageMinTurns;
501
+ } else if (sessionCal) {
502
+ const localMedianRpt =
503
+ options.historicalSessionRequestsPerTurn ?? localPriors?.medianRequestsPerTurn ?? null;
504
+ const hasLocalRptPrior =
505
+ options.useLocalRptPrior !== false &&
506
+ Number.isFinite(Number(localMedianRpt)) &&
507
+ Number(localMedianRpt) >= 1;
508
+ const rawRollingRpt =
509
+ sessionCal.rollingMedianRequestsPerTurn ?? sessionCal.requestsPerTurn ?? null;
510
+ const sampleTurns = Number(
511
+ sessionCal.rptSampleSize ??
512
+ (Array.isArray(sessionCal.recentTurnRequestCounts)
513
+ ? sessionCal.recentTurnRequestCounts.length
514
+ : sessionCal.turnsCompleted || 0)
515
+ );
516
+ const shrunkRpt = shrinkRollingRequestsPerTurn(rawRollingRpt, sampleTurns, {
517
+ minTrustedTurns: rptShrinkageMinTurns,
518
+ priorRequestsPerTurn: hasLocalRptPrior ? localMedianRpt : rptShrinkagePriorDefault,
519
+ priorSource: hasLocalRptPrior ? 'local_transcripts' : 'placeholder',
520
+ recentTurnRequestCounts: sessionCal.recentTurnRequestCounts
521
+ });
522
+ requestsPerTurn = shrunkRpt.expectedRequestsPerTurn;
523
+ rptEstimateSource = shrunkRpt.source;
524
+ rptSampleSize = shrunkRpt.sampleSize;
525
+ rawRollingMedianRequestsPerTurn = shrunkRpt.rawRollingMedianRequestsPerTurn;
526
+ rptShrinkageWeight = shrunkRpt.shrinkageWeight;
527
+ rptPriorUsed = shrunkRpt.priorRequestsPerTurn;
528
+ isPlaceholderRptPrior = shrunkRpt.isPlaceholderShrinkagePrior;
529
+ rptTurnsAgree = shrunkRpt.turnsAgree;
530
+ rptEffectiveMinTrustedTurns = shrunkRpt.effectiveMinTrustedTurns;
531
+ } else if (
532
+ options.useLocalRptPrior !== false &&
533
+ Number.isFinite(Number(options.historicalSessionRequestsPerTurn ?? localPriors?.medianRequestsPerTurn)) &&
534
+ Number(options.historicalSessionRequestsPerTurn ?? localPriors?.medianRequestsPerTurn) >= 1
535
+ ) {
536
+ requestsPerTurn = Number(
537
+ Number(options.historicalSessionRequestsPerTurn ?? localPriors?.medianRequestsPerTurn).toFixed(4)
538
+ );
539
+ rptEstimateSource = 'local_transcript_rpt_prior';
540
+ rptPriorUsed = requestsPerTurn;
541
+ isPlaceholderRptPrior = false;
542
+ }
543
+
544
+ const explicitGrowthRaw =
545
+ event.context_growth_per_turn ?? event.contextGrowthPerTurn ?? options.contextGrowthPerTurn;
546
+ const allowObservedGrowth =
547
+ (event.useObservedPromptGrowth ?? options.useObservedPromptGrowth) !== false;
548
+ let contextGrowthPerTurn = 0;
549
+ let promptGrowthEstimateSource = 'default_0';
550
+ let promptGrowthSampleSize = Number(sessionCal?.promptGrowthSampleSize ?? 0);
551
+ const hasRecentRptHistory =
552
+ Array.isArray(sessionCal?.recentTurnRequestCounts) &&
553
+ sessionCal.recentTurnRequestCounts.length >= 2;
554
+ const growthRegimeTrusted =
555
+ turnsCompleted >= 5 &&
556
+ promptGrowthSampleSize >= 4 &&
557
+ (!hasRecentRptHistory || Boolean(rptTurnsAgree));
558
+ if (
559
+ explicitGrowthRaw !== undefined &&
560
+ explicitGrowthRaw !== null &&
561
+ Number.isFinite(Number(explicitGrowthRaw)) &&
562
+ Number(explicitGrowthRaw) >= 0
563
+ ) {
564
+ contextGrowthPerTurn = Math.max(0, Math.round(Number(explicitGrowthRaw)));
565
+ promptGrowthEstimateSource = 'explicit';
566
+ } else if (
567
+ allowObservedGrowth &&
568
+ sessionCal?.rollingMedianPromptGrowthTokens !== null &&
569
+ sessionCal?.rollingMedianPromptGrowthTokens !== undefined &&
570
+ Number.isFinite(Number(sessionCal.rollingMedianPromptGrowthTokens)) &&
571
+ Number(sessionCal.rollingMedianPromptGrowthTokens) >= 0
572
+ ) {
573
+ if (growthRegimeTrusted) {
574
+ contextGrowthPerTurn = Math.max(
575
+ 0,
576
+ Math.round(Number(sessionCal.rollingMedianPromptGrowthTokens))
577
+ );
578
+ promptGrowthEstimateSource = 'stop_hook_rolling_growth_median';
579
+ } else {
580
+ contextGrowthPerTurn = 0;
581
+ promptGrowthEstimateSource =
582
+ turnsCompleted < 5
583
+ ? 'capped_early_session_no_extrapolation'
584
+ : 'capped_unstable_regime_no_extrapolation';
585
+ }
586
+ }
587
+ const contextCeilingRaw =
588
+ event.context_ceiling ??
589
+ event.contextCeiling ??
590
+ event.context_window_size ??
591
+ event.contextWindowSize ??
592
+ event.context_window?.context_window_size ??
593
+ options.contextCeiling ??
594
+ liveState?.contextWindow?.contextCeiling;
595
+ const contextCeiling =
596
+ contextCeilingRaw !== undefined &&
597
+ contextCeilingRaw !== null &&
598
+ Number.isFinite(Number(contextCeilingRaw)) &&
599
+ Number(contextCeilingRaw) >= 10_000
600
+ ? Math.round(Number(contextCeilingRaw))
601
+ : undefined;
602
+
603
+ const shrinkageMinTurns = Number(
604
+ options.outputShrinkageMinTurns ?? horizonConfig?.thresholds?.outputShrinkageMinTurns ?? 5
605
+ );
606
+ const shrinkagePriorTokens = Number(
607
+ options.outputShrinkagePriorTokens ?? horizonConfig?.thresholds?.outputShrinkagePriorTokens ?? 500
608
+ );
609
+
610
+ let resolvedExpectedOutputTokens =
611
+ event.expectedOutputTokens ?? event.expected_output_tokens ?? options.expectedOutputTokens;
612
+ let outputEstimateSource =
613
+ resolvedExpectedOutputTokens !== undefined ? 'explicit' : 'default_1500';
614
+ let outputSampleSize = 0;
615
+ let rawRollingMedianOutputTokens = null;
616
+ let shrinkageWeight = resolvedExpectedOutputTokens !== undefined ? 1 : 0;
617
+ const allowObservedOutput =
618
+ (event.useObservedOutputTokens ?? options.useObservedOutputTokens) !== false;
619
+ if (resolvedExpectedOutputTokens === undefined && allowObservedOutput) {
620
+ const turnsDone = Number(liveState?.turnsCompleted || 0);
621
+ const cumOut =
622
+ Number(liveState?.cumulative?.outputTokens || 0) +
623
+ Number(liveState?.cumulative?.thinkingTokens || 0);
624
+ const lastOut =
625
+ Number(liveState?.contextWindow?.lastOutputTokens || 0) +
626
+ Number(liveState?.contextWindow?.lastThinkingTokens || 0);
627
+ if (Number(sessionCal?.rollingMedianOutputTokens) > 0) {
628
+ const calSampleSize = Math.max(
629
+ 1,
630
+ Number(
631
+ sessionCal.outputSampleSize ??
632
+ (Array.isArray(sessionCal.recentTurnOutputs)
633
+ ? sessionCal.recentTurnOutputs.length
634
+ : sessionCal.turnsCompleted || 0)
635
+ )
636
+ );
637
+ const shrunk = shrinkRollingOutputEstimate(
638
+ sessionCal.rollingMedianOutputTokens,
639
+ calSampleSize,
640
+ { minTrustedTurns: shrinkageMinTurns, priorTokens: shrinkagePriorTokens }
641
+ );
642
+ resolvedExpectedOutputTokens = shrunk.expectedOutputTokens;
643
+ outputEstimateSource = shrunk.source;
644
+ outputSampleSize = shrunk.sampleSize;
645
+ rawRollingMedianOutputTokens = shrunk.rawRollingMedianOutputTokens;
646
+ shrinkageWeight = shrunk.shrinkageWeight;
647
+ } else if (Number(liveState?.rollingMedianOutputTokens) > 0) {
648
+ const liveSampleSize = Math.max(1, turnsDone);
649
+ const shrunk = shrinkRollingOutputEstimate(
650
+ liveState.rollingMedianOutputTokens,
651
+ liveSampleSize,
652
+ { minTrustedTurns: shrinkageMinTurns, priorTokens: shrinkagePriorTokens }
653
+ );
654
+ resolvedExpectedOutputTokens = shrunk.expectedOutputTokens;
655
+ outputEstimateSource =
656
+ shrunk.shrinkageWeight < 1 ? 'live_state_shrunk_median' : 'live_state_rolling_median';
657
+ outputSampleSize = shrunk.sampleSize;
658
+ rawRollingMedianOutputTokens = shrunk.rawRollingMedianOutputTokens;
659
+ shrinkageWeight = shrunk.shrinkageWeight;
660
+ } else if (turnsDone > 0 && cumOut > 0) {
661
+ const shrunk = shrinkRollingOutputEstimate(Math.round(cumOut / turnsDone), turnsDone, {
662
+ minTrustedTurns: shrinkageMinTurns,
663
+ priorTokens: shrinkagePriorTokens
664
+ });
665
+ resolvedExpectedOutputTokens = shrunk.expectedOutputTokens;
666
+ outputEstimateSource =
667
+ shrunk.shrinkageWeight < 1 ? 'live_state_shrunk_mean' : 'live_state_mean';
668
+ outputSampleSize = shrunk.sampleSize;
669
+ rawRollingMedianOutputTokens = shrunk.rawRollingMedianOutputTokens;
670
+ shrinkageWeight = shrunk.shrinkageWeight;
671
+ } else if (lastOut > 0) {
672
+ const shrunk = shrinkRollingOutputEstimate(lastOut, 1, {
673
+ minTrustedTurns: shrinkageMinTurns,
674
+ priorTokens: shrinkagePriorTokens
675
+ });
676
+ resolvedExpectedOutputTokens = shrunk.expectedOutputTokens;
677
+ outputEstimateSource = 'live_state_shrunk_last';
678
+ outputSampleSize = 1;
679
+ rawRollingMedianOutputTokens = shrunk.rawRollingMedianOutputTokens;
680
+ shrinkageWeight = shrunk.shrinkageWeight;
681
+ }
682
+ }
683
+
109
684
  let verdict = router.evaluateModelSwitch({
110
685
  currentModel,
111
686
  targetModel,
112
687
  cachedTokens,
113
688
  uncachedDeltaTokens,
689
+ uncachedWriteTokens,
690
+ justCompacted,
114
691
  totalPromptTokens,
115
692
  cacheWarm,
116
693
  cacheTtlTier,
117
- expectedOutputTokens: event.expectedOutputTokens ?? 1500,
694
+ turnsCompleted,
695
+ ...(apiCallsCompleted !== undefined ? { apiCallsCompleted } : {}),
696
+ ...(requestsPerTurn !== undefined ? { requestsPerTurn } : {}),
697
+ ...(contextGrowthPerTurn > 0 ? { contextGrowthPerTurn } : {}),
698
+ ...(contextCeiling !== undefined ? { contextCeiling } : {}),
699
+ initialPrefixTokens: sessionCal?.initialPrefixTokens,
700
+ expectedOutputTokens: resolvedExpectedOutputTokens ?? 1500,
701
+ ...(event.minSwitchPenaltyUSD !== undefined ||
702
+ event.min_switch_penalty_usd !== undefined ||
703
+ options.minSwitchPenaltyUSD !== undefined ||
704
+ horizonConfig?.thresholds?.minSwitchPenaltyUSD !== undefined
705
+ ? {
706
+ minSwitchPenaltyUSD:
707
+ event.minSwitchPenaltyUSD ??
708
+ event.min_switch_penalty_usd ??
709
+ options.minSwitchPenaltyUSD ??
710
+ horizonConfig?.thresholds?.minSwitchPenaltyUSD
711
+ }
712
+ : {}),
713
+ ...(event.notableAllowPenaltyUSD !== undefined ||
714
+ event.notable_allow_penalty_usd !== undefined ||
715
+ options.notableAllowPenaltyUSD !== undefined ||
716
+ horizonConfig?.thresholds?.notableAllowPenaltyUSD !== undefined
717
+ ? {
718
+ notableAllowPenaltyUSD:
719
+ event.notableAllowPenaltyUSD ??
720
+ event.notable_allow_penalty_usd ??
721
+ options.notableAllowPenaltyUSD ??
722
+ horizonConfig?.thresholds?.notableAllowPenaltyUSD
723
+ }
724
+ : {}),
725
+ ...(rawRemainingTurns !== undefined && rawRemainingTurns !== null
726
+ ? { expectedRemainingTurns: Number(rawRemainingTurns) }
727
+ : useEmpiricalHorizonPrior
728
+ ? { useEmpiricalHorizonPrior: true }
729
+ : {}),
118
730
  strictBlock:
119
731
  det08Override === 'block' ? true : (event.strictBlock ?? options.strictBlock),
120
- autoPilotDecision: event.autoPilotDecision ?? options.autoPilotDecision
732
+ autoPilotDecision: resolvedAutoPilotDecision
121
733
  });
122
734
 
123
735
  if (det08Override === 'warn' && verdict.blocked) {
@@ -138,20 +750,186 @@ export function runPreModelSwitchHook(event = {}, options = {}) {
138
750
  };
139
751
  }
140
752
 
753
+ const isHeldDownshift = Boolean(
754
+ (verdict.blocked || verdict.advisory) &&
755
+ verdict.breakEven?.shouldHoldModel &&
756
+ !verdict.belowMinSwitchPenaltyUSD &&
757
+ !verdict.breakEven?.isCapabilityUpshift &&
758
+ !verdict.breakEven?.unknownModel &&
759
+ verdict.breakEven?.currentModel &&
760
+ verdict.breakEven?.targetModel &&
761
+ verdict.breakEven.currentModel !== verdict.breakEven.targetModel
762
+ );
763
+ const recordedPendingDownshift = isHeldDownshift
764
+ ? {
765
+ fromModel: verdict.breakEven.currentModel,
766
+ toModel: verdict.breakEven.targetModel,
767
+ recordedAt: new Date(nowMs).toISOString()
768
+ }
769
+ : null;
770
+
771
+ if (shouldPersistBreaker) {
772
+ if (recordedPendingDownshift) {
773
+ writeBreakerStateSnapshot(
774
+ sessionId,
775
+ {
776
+ ...(breakerSnap || {}),
777
+ updatedAt: nowMs,
778
+ pending_downshift: recordedPendingDownshift,
779
+ pendingDownshiftModel: recordedPendingDownshift.toModel,
780
+ lastModelId: verdict.breakEven.currentModel,
781
+ lastContextTokens: cachedTokens
782
+ },
783
+ cwdOptions
784
+ );
785
+ } else if (
786
+ !verdict.blocked &&
787
+ !verdict.advisory &&
788
+ breakerSnap &&
789
+ (breakerSnap.pending_downshift || breakerSnap.pendingDownshiftModel || breakerSnap.justCompacted)
790
+ ) {
791
+ writeBreakerStateSnapshot(
792
+ sessionId,
793
+ {
794
+ ...breakerSnap,
795
+ updatedAt: nowMs,
796
+ pending_downshift: null,
797
+ pendingDownshiftModel: null,
798
+ justCompacted: false
799
+ },
800
+ cwdOptions
801
+ );
802
+ }
803
+ }
804
+
805
+ verdict = {
806
+ ...verdict,
807
+ ...(recordedPendingDownshift ? { pending_downshift: recordedPendingDownshift } : {}),
808
+ turnsCompletedUsed: turnsCompleted,
809
+ apiCallsCompletedUsed: apiCallsCompleted ?? null,
810
+ requestsPerTurnUsed: verdict.breakEven?.requestsPerTurn ?? requestsPerTurn ?? 1,
811
+ rptEstimateSource,
812
+ rptSampleSize,
813
+ rawRollingMedianRequestsPerTurn,
814
+ rawCumulativeRequestsPerTurn,
815
+ rptShrinkageWeight,
816
+ rptPriorUsed,
817
+ isPlaceholderRptPrior,
818
+ rptTurnsAgree,
819
+ rptEffectiveMinTrustedTurns,
820
+ contextGrowthPerTurnUsed: verdict.breakEven?.contextGrowthPerTurn ?? contextGrowthPerTurn ?? 0,
821
+ promptGrowthEstimateSource,
822
+ promptGrowthSampleSize,
823
+ outputEstimateSource,
824
+ outputSampleSize,
825
+ rawRollingMedianOutputTokens,
826
+ shrinkageWeight
827
+ };
828
+
829
+ const interceptionLogPath =
830
+ options.interceptionLogPath || globalThis.process?.env?.AH_INTERCEPTION_LOG_PATH;
831
+ if (typeof interceptionLogPath === 'string' && interceptionLogPath.trim()) {
832
+ try {
833
+ const logTarget = interceptionLogPath.trim();
834
+ const logDir = path.dirname(logTarget);
835
+ if (logDir && logDir !== '.' && !fs.existsSync(logDir)) {
836
+ fs.mkdirSync(logDir, { recursive: true });
837
+ }
838
+ fs.appendFileSync(
839
+ logTarget,
840
+ `${JSON.stringify({
841
+ timestampMs: nowMs,
842
+ sessionId,
843
+ fromModel: currentModel,
844
+ toModel: targetModel,
845
+ turnsCompletedUsed: turnsCompleted,
846
+ apiCallsCompleted: apiCallsCompleted ?? null,
847
+ requestsPerTurn: verdict.breakEven?.requestsPerTurn ?? requestsPerTurn ?? null,
848
+ rptEstimateSource,
849
+ rptSampleSize,
850
+ rawRollingMedianRequestsPerTurn,
851
+ rawCumulativeRequestsPerTurn,
852
+ rptShrinkageWeight,
853
+ rptPriorUsed,
854
+ isPlaceholderRptPrior,
855
+ rptTurnsAgree,
856
+ rptEffectiveMinTrustedTurns,
857
+ contextGrowthPerTurn: verdict.breakEven?.contextGrowthPerTurn ?? contextGrowthPerTurn ?? 0,
858
+ promptGrowthEstimateSource,
859
+ promptGrowthSampleSize,
860
+ outputEstimateSource,
861
+ outputSampleSize,
862
+ rawRollingMedianOutputTokens,
863
+ shrinkageWeight,
864
+ expectedOutputTokens: verdict.breakEven?.expectedOutputTokens ?? null,
865
+ cachedTokens,
866
+ breakEvenTokens: verdict.breakEven?.breakEvenTokens ?? null,
867
+ horizonMaxCachedTokens:
868
+ verdict.breakEven?.horizonMaxCachedTokens === Infinity
869
+ ? 'Infinity'
870
+ : (verdict.breakEven?.horizonMaxCachedTokens ?? null),
871
+ coldWritePenaltyUSD: verdict.breakEven?.coldWritePenaltyUSD ?? null,
872
+ perTurnPostSwitchSavingUSD: verdict.breakEven?.perTurnPostSwitchSavingUSD ?? null,
873
+ averagePostSwitchSavingUSD: verdict.breakEven?.averagePostSwitchSavingUSD ?? null,
874
+ horizonNetSavingsUSD: verdict.breakEven?.horizonNetSavingsUSD ?? null,
875
+ paybackTurns: verdict.breakEven?.paybackTurns ?? null,
876
+ paybackWarmRequests: verdict.breakEven?.paybackWarmRequests ?? null,
877
+ expectedRemainingTurns: verdict.breakEven?.expectedRemainingTurns ?? null,
878
+ postSwitchRemainingTurns: verdict.breakEven?.postSwitchRemainingTurns ?? null,
879
+ expectedRemainingRequests: verdict.breakEven?.expectedRemainingRequests ?? null,
880
+ horizonUnit: verdict.breakEven?.horizonUnit ?? 'turns',
881
+ priorNativeUnit: verdict.breakEven?.priorNativeUnit ?? null,
882
+ priorBucket: verdict.breakEven?.priorBucket ?? null,
883
+ isPlaceholderPrior: Boolean(verdict.breakEven?.isPlaceholderPrior),
884
+ horizonPriorSource: verdict.breakEven?.horizonPriorSource ?? null,
885
+ contextCeilingUsed: verdict.breakEven?.contextCeilingUsed ?? null,
886
+ initialPrefixTokensUsed: verdict.breakEven?.initialPrefixTokensUsed ?? null,
887
+ belowMinSwitchPenaltyUSD: Boolean(verdict.belowMinSwitchPenaltyUSD),
888
+ minSwitchPenaltyUSD: verdict.minSwitchPenaltyUSD ?? null,
889
+ notableAllowNote: verdict.notableAllowNote ?? null,
890
+ ruleVersion: verdict.breakEven?.ruleVersion ?? null,
891
+ decision: verdict.decision,
892
+ reason: verdict.reason ?? null
893
+ })}\n`,
894
+ 'utf8'
895
+ );
896
+ } catch {
897
+ // Never fail PreModelSwitch hook on diagnostic log write
898
+ }
899
+ }
900
+
901
+ const shouldRecordSwitchTelemetry =
902
+ options.recordSwitchTelemetry !== false &&
903
+ Boolean(
904
+ options.cliInvocation ||
905
+ options.homeDir ||
906
+ options.telemetryPath ||
907
+ options.recordSwitchTelemetry ||
908
+ globalThis.process?.env?.AH_MODEL_SWITCH_TELEMETRY_PATH
909
+ );
910
+ if (shouldRecordSwitchTelemetry) {
911
+ try {
912
+ recordPreModelSwitchEvent(event, verdict.decision, {
913
+ homeDir: options.homeDir,
914
+ telemetryPath: options.telemetryPath
915
+ });
916
+ } catch {
917
+ // Never fail PreModelSwitch hook on local acceptance telemetry error
918
+ }
919
+ }
920
+
921
+ const avoidedPenaltyUSD = Math.max(
922
+ 0,
923
+ Number(verdict.breakEven?.coldWritePenaltyUSD ?? 0)
924
+ );
925
+
141
926
  if (
142
927
  (verdict.blocked || verdict.decision === 'ask') &&
143
928
  cachedTokens > 0 &&
929
+ avoidedPenaltyUSD > 0 &&
144
930
  options.recordLedger !== false &&
145
931
  Boolean(event.cwd || options.cwd || options.ledgerPath || options.recordLedger)
146
932
  ) {
147
- const avoidedPenaltyUSD = Math.max(
148
- 0,
149
- Number(
150
- verdict.breakEven?.netSwitchSavingsUSD < 0
151
- ? Math.abs(verdict.breakEven.netSwitchSavingsUSD)
152
- : verdict.breakEven?.coldTargetTurnUSD || 0
153
- )
154
- );
155
933
  recordInterventionSavings(
156
934
  {
157
935
  sessionId,
@@ -180,6 +958,22 @@ export function runPreModelSwitchHook(event = {}, options = {}) {
180
958
  verdict
181
959
  };
182
960
  }
961
+ if (verdict.notableAllowNote) {
962
+ const hookSpecificOutput = {
963
+ hookEventName: 'PreModelSwitch',
964
+ permissionDecision: 'allow',
965
+ permissionDecisionReason: verdict.notableAllowNote
966
+ };
967
+ return {
968
+ exitCode: 0,
969
+ stdout: JSON.stringify({
970
+ systemMessage: verdict.notableAllowNote,
971
+ hookSpecificOutput
972
+ }),
973
+ stderr: '',
974
+ verdict
975
+ };
976
+ }
183
977
  return {
184
978
  exitCode: 0,
185
979
  stdout: '',
@@ -220,9 +1014,14 @@ export async function executePreModelSwitchCli(cliOptions = {}) {
220
1014
  const readPayload = cliOptions.readPayload || readStdinJsonAsync;
221
1015
  const runHook = cliOptions.runHook || runPreModelSwitchHook;
222
1016
  const ioOverride = cliOptions.ioOverride || {};
1017
+ const isRealCliRun =
1018
+ !cliOptions.ioOverride && !cliOptions.readPayload && !cliOptions.runHook;
223
1019
  try {
224
1020
  const payload = await readPayload(cliOptions.timeoutMs);
225
- const res = runHook(payload, cliOptions.hookOptions);
1021
+ const res = runHook(payload, {
1022
+ cliInvocation: isRealCliRun,
1023
+ ...(cliOptions.hookOptions || {})
1024
+ });
226
1025
  if (res.exitCode === 2) {
227
1026
  exitHardBlockStderr(res.stderr, 'PreModelSwitch', ioOverride);
228
1027
  } else if (res.stdout) {