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,265 @@
1
+ /**
2
+ * @file hooks/handlers/post-tool-use.mjs
3
+ * Tier 2 Command Hook handler for `PostToolUse` (`Bash|PowerShell|Grep|Glob|Task|Agent|WebFetch|mcp__.*`).
4
+ * Runs lossless output sanitization, 100% critical error-line recovery,
5
+ * >4,000 token programmatic artifact offloading (excluding workspace `Read`),
6
+ * and `DET-19` subagent IPI boundary & Unicode tag stripping (`ISS-034`, `ISS-053`).
7
+ */
8
+
9
+ import { sanitizePostToolOutput } from '../../src/core-isomorphic/guards/losslessPostSanitizer.mjs';
10
+ import {
11
+ CircuitBreakerEngine,
12
+ evaluateDet19SubagentIpiSanitizer,
13
+ readBreakerStateSnapshot,
14
+ writeBreakerStateSnapshot
15
+ } from '../../src/core-isomorphic/guards/circuitBreakers.mjs';
16
+ import { loadHorizonConfig, resolveDetectorOverride } from '../../src/core-isomorphic/config/horizonConfig.mjs';
17
+ import { recordWorkspaceShellOutcome } from '../../src/core-isomorphic/coach/microSkills.mjs';
18
+ import { recordSavingsReceipt } from '../../src/core-isomorphic/coach/savedQuotaLedger.mjs';
19
+ import { readLiveStateSnapshot } from '../../src/core-isomorphic/telemetry/telemetryBridge.mjs';
20
+ import { resolveEffectiveRates, computeTotalPromptTokens } from '../../src/core-isomorphic/config/catalogLoader.mjs';
21
+ import {
22
+ isCliEntrypoint,
23
+ readStdinJsonAsync,
24
+ exitPassThrough,
25
+ exitDiagnosticZero,
26
+ exitWithStdoutJson
27
+ } from './hookIo.mjs';
28
+
29
+ /**
30
+ * Extracts text from a string or structured `tool_response` object.
31
+ * @param {object} event
32
+ * @returns {string}
33
+ */
34
+ function extractPostToolText(event = {}) {
35
+ const resp = event.tool_response ?? event.tool_output ?? event.toolOutput ?? event.output;
36
+ if (typeof resp === 'string') return resp;
37
+ if (resp && typeof resp === 'object') {
38
+ const parts = [resp.stdout, resp.stderr, resp.output, resp.content, resp.error]
39
+ .filter((x) => typeof x === 'string' && x.length > 0);
40
+ if (parts.length > 0) return parts.join('\n');
41
+ return '';
42
+ }
43
+ return resp !== undefined && resp !== null ? String(resp) : '';
44
+ }
45
+
46
+ /**
47
+ * Determines whether a completed tool call failed (`is_error`, non-zero `exit_code`, etc.).
48
+ * @param {object} event
49
+ * @returns {boolean}
50
+ */
51
+ function didToolExecutionFail(event = {}) {
52
+ if (
53
+ event.is_error === true ||
54
+ event.isError === true ||
55
+ event.succeeded === false ||
56
+ Boolean(event.tool_error || event.error) ||
57
+ (typeof event.exit_code === 'number' && event.exit_code !== 0) ||
58
+ (typeof event.exitCode === 'number' && event.exitCode !== 0)
59
+ ) {
60
+ return true;
61
+ }
62
+ const resp = event.tool_response;
63
+ if (resp && typeof resp === 'object') {
64
+ if (
65
+ resp.is_error === true ||
66
+ resp.isError === true ||
67
+ resp.succeeded === false ||
68
+ resp.status === 'error' ||
69
+ resp.status === 'failed' ||
70
+ Boolean(resp.error) ||
71
+ (typeof resp.exit_code === 'number' && resp.exit_code !== 0) ||
72
+ (typeof resp.exitCode === 'number' && resp.exitCode !== 0) ||
73
+ (typeof resp.returncode === 'number' && resp.returncode !== 0)
74
+ ) {
75
+ return true;
76
+ }
77
+ }
78
+ return false;
79
+ }
80
+
81
+ /**
82
+ * Evaluates a `PostToolUse` hook payload and returns the contract response.
83
+ * @param {object} event
84
+ * @param {object} [options={}]
85
+ */
86
+ export function runPostToolUseHook(event = {}, options = {}) {
87
+ const toolName = String(event.tool_name || event.toolName || 'Bash');
88
+ const rawOutput = extractPostToolText(event);
89
+ const tier1Active = Boolean(
90
+ options.tier1ModActive ||
91
+ event.tier1ModActive ||
92
+ globalThis.process?.env?.AH_TIER1_MOD_ACTIVE === '1'
93
+ );
94
+ if (tier1Active && /^(Grep|Glob)$/i.test(toolName) && rawOutput.length < 16000 && !didToolExecutionFail(event)) {
95
+ return {
96
+ exitCode: 0,
97
+ stdout: '',
98
+ stderr: '',
99
+ fastPath: 'tier1_mod_active',
100
+ sanitized: { modified: false, offloaded: false }
101
+ };
102
+ }
103
+ const sessionId = event.session_id || event.sessionId || 'default';
104
+ const cwdOptions = event.cwd && !options.cwd ? { ...options, cwd: event.cwd } : options;
105
+ const horizonConfig = options.horizonConfig || loadHorizonConfig(cwdOptions);
106
+
107
+ const shouldPersistState =
108
+ options.persistState !== false &&
109
+ Boolean(event.cwd || options.cwd || options.breakerStatePath || options.persistState);
110
+
111
+ if (shouldPersistState) {
112
+ const failed = didToolExecutionFail(event);
113
+ const priorSnap = readBreakerStateSnapshot(sessionId, cwdOptions);
114
+ const engine = new CircuitBreakerEngine({
115
+ ...cwdOptions,
116
+ horizonConfig,
117
+ mode: event.mode || options.mode || horizonConfig.flightMode || 'COACH',
118
+ initialState: priorSnap
119
+ });
120
+ engine.recordToolOutcome(!failed, toolName);
121
+ if (failed && engine.modifiedFilesInTurn.size > 0) {
122
+ // If a test command failed, code edits remain unverified
123
+ engine.codeEditedSinceLastTest = true;
124
+ }
125
+ writeBreakerStateSnapshot(sessionId, engine.exportStateSnapshot(), cwdOptions);
126
+
127
+ // RSI-04 ('micro-skills'): Capture shell failure -> recovery pairs within <= 3 turns
128
+ if (/^(Bash|PowerShell|pwsh|cmd|sh)$/i.test(toolName) && resolveDetectorOverride('micro-skills', horizonConfig) !== 'off') {
129
+ const toolInput = event.tool_input || event.toolInput || {};
130
+ const cmdStr = String(toolInput.command || toolInput.cmd || event.command || '');
131
+ if (cmdStr) {
132
+ const rawExit =
133
+ event.exit_code ??
134
+ event.exitCode ??
135
+ event.tool_response?.exit_code ??
136
+ event.tool_response?.exitCode;
137
+ recordWorkspaceShellOutcome(
138
+ {
139
+ command: cmdStr,
140
+ exitCode: typeof rawExit === 'number' ? rawExit : (failed ? 1 : 0),
141
+ turn: Number(event.turnId ?? event.turn_id ?? event.turn ?? 1),
142
+ sessionId: String(sessionId),
143
+ confirmSessions: Number(horizonConfig.thresholds?.microSkillConfirmSessions ?? 2)
144
+ },
145
+ cwdOptions
146
+ );
147
+ }
148
+ }
149
+ }
150
+
151
+ const sanitized = sanitizePostToolOutput(
152
+ {
153
+ toolName,
154
+ toolOutput: rawOutput
155
+ },
156
+ cwdOptions
157
+ );
158
+
159
+ let finalOutput = sanitized.updatedToolOutput;
160
+ let wasModified = sanitized.sanitized;
161
+
162
+ // Apply DET-19 IPI sanitizer if output comes from a subagent (Task/Agent/agentId) or external WebFetch/MCP tool
163
+ const isSubagentSource =
164
+ Boolean(event.agentId || event.subagentId) || /^(Task|Agent)$/i.test(toolName);
165
+ const isUntrustedSource =
166
+ isSubagentSource || /^(WebFetch|mcp__.+)$/i.test(toolName);
167
+
168
+ if (
169
+ isUntrustedSource &&
170
+ finalOutput &&
171
+ resolveDetectorOverride('DET-19', horizonConfig) !== 'off'
172
+ ) {
173
+ const ipi = evaluateDet19SubagentIpiSanitizer({
174
+ text: finalOutput,
175
+ wrapUntrusted: isSubagentSource
176
+ });
177
+ if (ipi.triggered || isSubagentSource) {
178
+ finalOutput = ipi.sanitizedText;
179
+ wasModified = true;
180
+ }
181
+ }
182
+
183
+ if (sanitized.savedTokens > 0 && options.recordLedger !== false) {
184
+ const liveState = options.telemetryState || readLiveStateSnapshot(sessionId, cwdOptions);
185
+ const rawEventModel =
186
+ typeof event.model === 'string'
187
+ ? event.model
188
+ : event.model?.id || event.model?.model_id || event.modelId || event.model_id;
189
+ const modelId = rawEventModel || liveState?.modelId || 'claude-sonnet-5-5';
190
+ const usageSource =
191
+ event.usage || event.context_window?.current_usage || liveState?.contextWindow || {};
192
+ const totalPromptTokens = computeTotalPromptTokens(usageSource);
193
+ const rates = resolveEffectiveRates(modelId, totalPromptTokens, cwdOptions);
194
+
195
+ recordSavingsReceipt(
196
+ {
197
+ sessionId,
198
+ modelId: rates.modelId,
199
+ category: sanitized.offloaded ? 'ARTIFACT_OFFLOAD_4K' : 'LOSSLESS_POST_SANITIZER',
200
+ savedTokens: sanitized.savedTokens,
201
+ savedUSD: Number(((sanitized.savedTokens / 1_000_000) * rates.inputPer1M).toFixed(6)),
202
+ detail: `${toolName} output compressed (${sanitized.originalTokens} -> ${sanitized.finalTokens} tokens)`
203
+ },
204
+ cwdOptions
205
+ );
206
+ }
207
+
208
+ if (!wasModified) {
209
+ return {
210
+ exitCode: 0,
211
+ stdout: '',
212
+ stderr: '',
213
+ sanitized
214
+ };
215
+ }
216
+
217
+ // ISS-034: updatedMCPToolOutput applies strictly to MCP tools; built-in tools use additionalContext!
218
+ const isMcpTool = /^mcp__/i.test(toolName);
219
+ const hookSpecificOutput = isMcpTool
220
+ ? {
221
+ hookEventName: 'PostToolUse',
222
+ updatedMCPToolOutput: finalOutput
223
+ }
224
+ : {
225
+ hookEventName: 'PostToolUse',
226
+ additionalContext: finalOutput
227
+ };
228
+
229
+ return {
230
+ exitCode: 0,
231
+ stdout: JSON.stringify({ hookSpecificOutput }),
232
+ stderr: '',
233
+ sanitized,
234
+ hookSpecificOutput
235
+ };
236
+ }
237
+
238
+ /**
239
+ * CLI runner for `PostToolUse` (`ISS-035`).
240
+ * Non-blocking post hook: logs diagnostic to stderr and exits `0` on uncaught error.
241
+ *
242
+ * @param {object} [cliOptions={}]
243
+ */
244
+ export async function executePostToolUseCli(cliOptions = {}) {
245
+ const readPayload = cliOptions.readPayload || readStdinJsonAsync;
246
+ const runHook = cliOptions.runHook || runPostToolUseHook;
247
+ const ioOverride = cliOptions.ioOverride || {};
248
+ try {
249
+ const payload = await readPayload(cliOptions.timeoutMs);
250
+ const res = runHook(payload, { persistState: true, ...(cliOptions.hookOptions || {}) });
251
+ if (res.stdout) {
252
+ exitWithStdoutJson(res.stdout, ioOverride);
253
+ } else {
254
+ exitPassThrough(ioOverride.exitFn);
255
+ }
256
+ } catch (err) {
257
+ exitDiagnosticZero(err?.message || String(err), 'PostToolUse', ioOverride);
258
+ }
259
+ }
260
+
261
+ if (isCliEntrypoint(import.meta.url)) {
262
+ executePostToolUseCli().catch((err) => {
263
+ exitDiagnosticZero(err?.message || String(err), 'PostToolUse');
264
+ });
265
+ }
@@ -0,0 +1,249 @@
1
+ /**
2
+ * @file hooks/handlers/pre-model-switch.mjs
3
+ * Tier 2 Command Hook handler for `PreModelSwitch` (`DET-08` Warm KV-Cache Cross-Model Switch Guard).
4
+ */
5
+
6
+ import { readLiveStateSnapshot } from '../../src/core-isomorphic/telemetry/telemetryBridge.mjs';
7
+ import { computeTotalPromptTokens } from '../../src/core-isomorphic/config/catalogLoader.mjs';
8
+ import { loadHorizonConfig, resolveDetectorOverride } from '../../src/core-isomorphic/config/horizonConfig.mjs';
9
+ import { CacheGravityRouter } from '../../src/core-isomorphic/coach/cacheGravityRouter.mjs';
10
+ import { recordInterventionSavings } from '../../src/core-isomorphic/coach/savedQuotaLedger.mjs';
11
+ import { requireProFeature } from '../../src/core/pro_license.mjs';
12
+ import {
13
+ isCliEntrypoint,
14
+ readStdinJsonAsync,
15
+ exitPassThrough,
16
+ exitHardBlockStderr,
17
+ exitWithStdoutJson
18
+ } from './hookIo.mjs';
19
+
20
+ /**
21
+ * Evaluates a `PreModelSwitch` event against `CacheGravityRouter` break-even threshold `C*`.
22
+ * @param {object} event
23
+ * @param {object} [options={}]
24
+ */
25
+ export function runPreModelSwitchHook(event = {}, options = {}) {
26
+ const sessionId = event.session_id || event.sessionId || 'default';
27
+ const cwdOptions = event.cwd && !options.cwd ? { ...options, cwd: event.cwd } : options;
28
+ const horizonConfig = options.horizonConfig || loadHorizonConfig(cwdOptions);
29
+ const det08Override = resolveDetectorOverride('DET-08', horizonConfig);
30
+
31
+ if (det08Override === 'off') {
32
+ return {
33
+ exitCode: 0,
34
+ stdout: '',
35
+ stderr: '',
36
+ verdict: {
37
+ detectorId: null,
38
+ triggered: false,
39
+ decision: 'allow',
40
+ blocked: false,
41
+ overriddenByConfig: 'off',
42
+ suppressedDetectorId: 'DET-08',
43
+ reason: null
44
+ }
45
+ };
46
+ }
47
+
48
+ const liveState = options.telemetryState || readLiveStateSnapshot(sessionId, cwdOptions);
49
+ const configHasDiskSource = Boolean(
50
+ horizonConfig?.sources?.projectLoaded || horizonConfig?.sources?.globalLoaded
51
+ );
52
+ const rawEffectiveMode =
53
+ event.mode ||
54
+ options.mode ||
55
+ options.telemetryState?.flightMode ||
56
+ (configHasDiskSource
57
+ ? horizonConfig.flightMode
58
+ : liveState?.flightMode || horizonConfig?.flightMode || 'COACH');
59
+ const proAutoPilot =
60
+ rawEffectiveMode === 'AUTO_PILOT' ? requireProFeature('auto_pilot_locks', options) : { allowed: true };
61
+ const effectiveMode =
62
+ rawEffectiveMode === 'AUTO_PILOT' && !proAutoPilot.allowed ? 'COACH' : rawEffectiveMode;
63
+
64
+ const router =
65
+ options.router ||
66
+ new CacheGravityRouter({
67
+ ...cwdOptions,
68
+ mode: effectiveMode,
69
+ strictBlock:
70
+ det08Override === 'block' ? true : (event.strictBlock ?? options.strictBlock)
71
+ });
72
+
73
+ const currentModel =
74
+ event.current_model || event.currentModel || liveState.modelId || 'claude-opus-5-5';
75
+ const targetModel =
76
+ event.target_model || event.targetModel || event.model || 'claude-sonnet-5-5';
77
+ const cachedTokens = Number(
78
+ event.cached_tokens ??
79
+ event.cachedTokens ??
80
+ liveState.contextWindow?.cachedTokens ??
81
+ 0
82
+ );
83
+ 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);
89
+
90
+ const uncachedDeltaTokens = Number(
91
+ event.uncached_delta_tokens ?? event.uncachedDeltaTokens ?? 0
92
+ );
93
+ const rawTier =
94
+ event.cache_ttl_tier ??
95
+ event.cacheTtlTier ??
96
+ event.prompt_cache?.ttl ??
97
+ liveState.promptCache?.ttlTier ??
98
+ '5m';
99
+ const cacheTtlTier =
100
+ rawTier === '1h' || rawTier === '3600s' || Number(rawTier) > 300 ? '1h' : '5m';
101
+ const usageSource =
102
+ event.usage || event.context_window?.current_usage || liveState.contextWindow || {};
103
+ const totalPromptTokens = Math.max(
104
+ cachedTokens + uncachedDeltaTokens,
105
+ computeTotalPromptTokens(event),
106
+ computeTotalPromptTokens(usageSource)
107
+ );
108
+
109
+ let verdict = router.evaluateModelSwitch({
110
+ currentModel,
111
+ targetModel,
112
+ cachedTokens,
113
+ uncachedDeltaTokens,
114
+ totalPromptTokens,
115
+ cacheWarm,
116
+ cacheTtlTier,
117
+ expectedOutputTokens: event.expectedOutputTokens ?? 1500,
118
+ strictBlock:
119
+ det08Override === 'block' ? true : (event.strictBlock ?? options.strictBlock),
120
+ autoPilotDecision: event.autoPilotDecision ?? options.autoPilotDecision
121
+ });
122
+
123
+ if (det08Override === 'warn' && verdict.blocked) {
124
+ verdict = {
125
+ ...verdict,
126
+ decision: 'allow',
127
+ blocked: false,
128
+ advisory: true,
129
+ overriddenByConfig: 'warn'
130
+ };
131
+ } else if (det08Override === 'block' && verdict.breakEven?.shouldHoldModel && !verdict.blocked) {
132
+ verdict = {
133
+ ...verdict,
134
+ decision: 'deny',
135
+ blocked: true,
136
+ advisory: false,
137
+ overriddenByConfig: 'block'
138
+ };
139
+ }
140
+
141
+ if (
142
+ (verdict.blocked || verdict.decision === 'ask') &&
143
+ cachedTokens > 0 &&
144
+ options.recordLedger !== false &&
145
+ Boolean(event.cwd || options.cwd || options.ledgerPath || options.recordLedger)
146
+ ) {
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
+ recordInterventionSavings(
156
+ {
157
+ sessionId,
158
+ category: 'DET_08_MODEL_SWITCH_HOLD',
159
+ modelId: currentModel,
160
+ savedTokens: cachedTokens,
161
+ savedUSD: avoidedPenaltyUSD,
162
+ dedupeId: event.turn_id || event.turnId || `${currentModel}->${targetModel}:${cachedTokens}`,
163
+ detail: `DET-08 held warm prefix (${cachedTokens.toLocaleString()} tok) on ${currentModel} vs ${targetModel}`
164
+ },
165
+ cwdOptions
166
+ );
167
+ }
168
+
169
+ if (!verdict.blocked) {
170
+ if (verdict.advisory && verdict.reason) {
171
+ const hookSpecificOutput = {
172
+ hookEventName: 'PreModelSwitch',
173
+ permissionDecision: 'allow',
174
+ additionalContext: verdict.reason
175
+ };
176
+ return {
177
+ exitCode: 0,
178
+ stdout: JSON.stringify({ hookSpecificOutput }),
179
+ stderr: '',
180
+ verdict
181
+ };
182
+ }
183
+ return {
184
+ exitCode: 0,
185
+ stdout: '',
186
+ stderr: '',
187
+ verdict
188
+ };
189
+ }
190
+
191
+ if (options.useJsonDecision || verdict.decision === 'ask') {
192
+ const hookSpecificOutput = {
193
+ hookEventName: 'PreModelSwitch',
194
+ permissionDecision: verdict.decision === 'ask' ? 'ask' : 'deny',
195
+ permissionDecisionReason: verdict.reason
196
+ };
197
+ return {
198
+ exitCode: 0,
199
+ stdout: JSON.stringify({ hookSpecificOutput }),
200
+ stderr: '',
201
+ verdict
202
+ };
203
+ }
204
+
205
+ return {
206
+ exitCode: 2,
207
+ stdout: '',
208
+ stderr: verdict.reason,
209
+ verdict
210
+ };
211
+ }
212
+
213
+ /**
214
+ * Fail-closed CLI runner for `PreModelSwitch` (`ISS-035`).
215
+ * Any uncaught error exits `2` via `exitHardBlockStderr`.
216
+ *
217
+ * @param {object} [cliOptions={}]
218
+ */
219
+ export async function executePreModelSwitchCli(cliOptions = {}) {
220
+ const readPayload = cliOptions.readPayload || readStdinJsonAsync;
221
+ const runHook = cliOptions.runHook || runPreModelSwitchHook;
222
+ const ioOverride = cliOptions.ioOverride || {};
223
+ try {
224
+ const payload = await readPayload(cliOptions.timeoutMs);
225
+ const res = runHook(payload, cliOptions.hookOptions);
226
+ if (res.exitCode === 2) {
227
+ exitHardBlockStderr(res.stderr, 'PreModelSwitch', ioOverride);
228
+ } else if (res.stdout) {
229
+ exitWithStdoutJson(res.stdout, ioOverride);
230
+ } else {
231
+ exitPassThrough(ioOverride.exitFn);
232
+ }
233
+ } catch (err) {
234
+ exitHardBlockStderr(
235
+ `[Highbeam Fail-Closed] ${err?.message || String(err)}`,
236
+ 'PreModelSwitch',
237
+ ioOverride
238
+ );
239
+ }
240
+ }
241
+
242
+ if (isCliEntrypoint(import.meta.url)) {
243
+ executePreModelSwitchCli().catch((err) => {
244
+ exitHardBlockStderr(
245
+ `[Highbeam Fail-Closed] ${err?.message || String(err)}`,
246
+ 'PreModelSwitch'
247
+ );
248
+ });
249
+ }