observability-toolkit-hooks 0.0.0-stage → 1.0.1

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 (306) hide show
  1. package/CONFIG.md +144 -0
  2. package/LICENSE +95 -0
  3. package/README.md +201 -2
  4. package/dist/handlers/compact.js +38 -0
  5. package/dist/handlers/mcp-status.js +66 -0
  6. package/dist/handlers/notification.js +45 -0
  7. package/dist/handlers/post-tool-agent.js +157 -0
  8. package/dist/handlers/post-tool-changelog-sync.js +148 -0
  9. package/dist/handlers/post-tool-code-structure.js +116 -0
  10. package/dist/handlers/post-tool-edit-ledger.js +15 -0
  11. package/dist/handlers/post-tool-failure.js +83 -0
  12. package/dist/handlers/post-tool-git.js +79 -0
  13. package/dist/handlers/post-tool-mcp.js +105 -0
  14. package/dist/handlers/post-tool-outcome.js +48 -0
  15. package/dist/handlers/post-tool-task-state.js +74 -0
  16. package/dist/handlers/post-tool.js +132 -0
  17. package/dist/handlers/pre-tool-agent.js +192 -0
  18. package/dist/handlers/pre-tool.js +218 -0
  19. package/dist/handlers/session-end.js +39 -0
  20. package/dist/handlers/session-start.js +262 -0
  21. package/dist/handlers/stop-error-reminder.js +195 -0
  22. package/dist/handlers/stop-quality-evaluation.js +58 -0
  23. package/dist/handlers/stop-session-summary.js +62 -0
  24. package/dist/handlers/stop-token-metrics.js +83 -0
  25. package/dist/handlers/stop.js +25 -0
  26. package/dist/handlers/subagent.js +105 -0
  27. package/dist/handlers/tool-event-router.js +39 -0
  28. package/dist/handlers/user-prompt.js +218 -0
  29. package/dist/hook-runner.js +10 -0
  30. package/dist/hook-runner.js.map +7 -0
  31. package/dist/lib/agent/agent-context.js +123 -0
  32. package/dist/lib/agent/agent-evaluations.js +155 -0
  33. package/dist/lib/agent/agent-file-budget.js +65 -0
  34. package/dist/lib/agent/agent-sources.js +165 -0
  35. package/dist/lib/agent/synth-spans.js +51 -0
  36. package/dist/lib/core/bounded-label.js +6 -0
  37. package/dist/lib/core/category-rules.js +11 -0
  38. package/dist/lib/core/child-result.js +19 -0
  39. package/dist/lib/core/config-dir-recovery.js +22 -0
  40. package/dist/lib/core/constants.js +171 -0
  41. package/dist/lib/core/detached-runner.js +55 -0
  42. package/dist/lib/core/file-utils.js +353 -0
  43. package/dist/lib/core/format-utils.js +51 -0
  44. package/dist/lib/core/http-utils.js +74 -0
  45. package/dist/lib/core/http1-fetch.js +14 -0
  46. package/dist/lib/core/identity-key-resolver.js +149 -0
  47. package/dist/lib/core/jsonl-tail.js +207 -0
  48. package/dist/lib/core/load-envrc.js +72 -0
  49. package/dist/lib/core/parsers.js +43 -0
  50. package/dist/lib/core/regex.js +27 -0
  51. package/dist/lib/core/settings-env.js +31 -0
  52. package/dist/lib/core/shell-command.js +122 -0
  53. package/dist/lib/core/units.js +97 -0
  54. package/dist/lib/git/git-cache.js +158 -0
  55. package/dist/lib/git/git-commit.js +189 -0
  56. package/dist/lib/git/git-exec.js +30 -0
  57. package/dist/lib/mcp/mcp-completeness.js +40 -0
  58. package/dist/lib/mcp/mcp-config.js +118 -0
  59. package/dist/lib/mcp/mcp-failure-latch.js +22 -0
  60. package/dist/lib/mcp/mcp-identity-launcher.js +43 -0
  61. package/dist/lib/otel/attributes.js +322 -0
  62. package/dist/lib/otel/evaluation-attrs.js +51 -0
  63. package/dist/lib/otel/file-exporters.js +169 -0
  64. package/dist/lib/otel/host-resource.js +61 -0
  65. package/dist/lib/otel/otel-headers-helper.js +26 -0
  66. package/dist/lib/otel/otel-monitor.js +181 -0
  67. package/dist/lib/otel/otel.js +235 -0
  68. package/dist/lib/otel/otlp-headers.js +101 -0
  69. package/dist/lib/otel/otlp-post.js +122 -0
  70. package/dist/lib/otel/otlp-serialize.js +142 -0
  71. package/dist/lib/otel/otlp-signal.js +2 -0
  72. package/dist/lib/otel/remote-spans.js +142 -0
  73. package/dist/lib/otel/service-identity.js +10 -0
  74. package/dist/lib/otel/telemetry-alerts.js +43 -0
  75. package/dist/lib/otel/token-metrics.js +122 -0
  76. package/dist/lib/otel/trace-context.js +81 -0
  77. package/dist/lib/quality/judge-meta-eval.js +70 -0
  78. package/dist/lib/quality/judge-prompts.js +104 -0
  79. package/dist/lib/quality/judge-providers.js +193 -0
  80. package/dist/lib/quality/judge-transport.js +93 -0
  81. package/dist/lib/quality/llm-judge.js +170 -0
  82. package/dist/lib/quality/quality-budget.js +99 -0
  83. package/dist/lib/quality/quality-degradation.js +156 -0
  84. package/dist/lib/quality/quality-eval-handoff.js +74 -0
  85. package/dist/lib/quality/quality-evaluator.js +178 -0
  86. package/dist/lib/quality/quality-sampler.js +43 -0
  87. package/dist/lib/quality/quality-signals.js +150 -0
  88. package/dist/lib/runtime/categorizers.js +101 -0
  89. package/dist/lib/runtime/hook-input.js +16 -0
  90. package/dist/lib/runtime/hook-output.js +50 -0
  91. package/dist/lib/runtime/output-analyzer.js +160 -0
  92. package/dist/lib/runtime/run-handlers.js +32 -0
  93. package/dist/lib/runtime/tool-input.js +111 -0
  94. package/dist/lib/runtime/tool-output.js +44 -0
  95. package/dist/lib/runtime/unknown-tool.js +32 -0
  96. package/dist/lib/session/edit-ledger.js +29 -0
  97. package/dist/lib/session/forked-skill.js +39 -0
  98. package/dist/lib/session/handoffs.js +77 -0
  99. package/dist/lib/session/session-state.js +169 -0
  100. package/dist/lib/session/skill-rules.js +196 -0
  101. package/dist/lib/session/task-tracker.js +83 -0
  102. package/dist/lib/shipper/shipper-credentials.js +38 -0
  103. package/dist/lib/shipper/shipper-cursor.js +89 -0
  104. package/dist/lib/shipper/shipper-status.js +174 -0
  105. package/dist/lib/shipper/span-shipper.js +272 -0
  106. package/dist/lib/shipper/telemetry-shipper.js +39 -0
  107. package/dist/lib/transcript/agent-transcript-metrics.js +34 -0
  108. package/dist/lib/transcript/context-breakdown.js +134 -0
  109. package/dist/lib/transcript/context-history.js +69 -0
  110. package/dist/lib/transcript/context-tracker.js +226 -0
  111. package/dist/lib/transcript/message-count.js +49 -0
  112. package/dist/lib/transcript/model-ids.js +36 -0
  113. package/dist/lib/transcript/model-pricing.js +153 -0
  114. package/dist/lib/transcript/token-metrics-checkpoint.js +152 -0
  115. package/dist/lib/transcript/tool-call-durations.js +64 -0
  116. package/dist/lib/transcript/transcript-entry.js +67 -0
  117. package/dist/lib/transcript/transcript-fold.js +130 -0
  118. package/dist/lib/transcript/transcript-layout.js +39 -0
  119. package/dist/lib/transcript/transcript-parser.js +117 -0
  120. package/dist/runner/agent-context-4XTCLMLZ.js +23 -0
  121. package/dist/runner/agent-context-4XTCLMLZ.js.map +7 -0
  122. package/dist/runner/agent-file-budget-Q33ESBBE.js +68 -0
  123. package/dist/runner/agent-file-budget-Q33ESBBE.js.map +7 -0
  124. package/dist/runner/agent-transcript-metrics-W5CZZFMI.js +39 -0
  125. package/dist/runner/agent-transcript-metrics-W5CZZFMI.js.map +7 -0
  126. package/dist/runner/chunk-2NTNAJZE.js +49 -0
  127. package/dist/runner/chunk-2NTNAJZE.js.map +7 -0
  128. package/dist/runner/chunk-4KWBQTTG.js +78 -0
  129. package/dist/runner/chunk-4KWBQTTG.js.map +7 -0
  130. package/dist/runner/chunk-52RY6LQT.js +699 -0
  131. package/dist/runner/chunk-52RY6LQT.js.map +7 -0
  132. package/dist/runner/chunk-7OM5CYES.js +8695 -0
  133. package/dist/runner/chunk-7OM5CYES.js.map +7 -0
  134. package/dist/runner/chunk-7PEOKGYR.js +1568 -0
  135. package/dist/runner/chunk-7PEOKGYR.js.map +7 -0
  136. package/dist/runner/chunk-AGSGKELQ.js +126 -0
  137. package/dist/runner/chunk-AGSGKELQ.js.map +7 -0
  138. package/dist/runner/chunk-AVM7PJFW.js +12 -0
  139. package/dist/runner/chunk-AVM7PJFW.js.map +7 -0
  140. package/dist/runner/chunk-C3WHUMU5.js +178 -0
  141. package/dist/runner/chunk-C3WHUMU5.js.map +7 -0
  142. package/dist/runner/chunk-DGB4NSSD.js +157 -0
  143. package/dist/runner/chunk-DGB4NSSD.js.map +7 -0
  144. package/dist/runner/chunk-DNSTWC26.js +151 -0
  145. package/dist/runner/chunk-DNSTWC26.js.map +7 -0
  146. package/dist/runner/chunk-FDJJ3TYU.js +449 -0
  147. package/dist/runner/chunk-FDJJ3TYU.js.map +7 -0
  148. package/dist/runner/chunk-FGKYDQHZ.js +137 -0
  149. package/dist/runner/chunk-FGKYDQHZ.js.map +7 -0
  150. package/dist/runner/chunk-GG2I4TGI.js +582 -0
  151. package/dist/runner/chunk-GG2I4TGI.js.map +7 -0
  152. package/dist/runner/chunk-GNNKUMRF.js +60 -0
  153. package/dist/runner/chunk-GNNKUMRF.js.map +7 -0
  154. package/dist/runner/chunk-I7TD2QVR.js +118 -0
  155. package/dist/runner/chunk-I7TD2QVR.js.map +7 -0
  156. package/dist/runner/chunk-IJ4SLUBV.js +78 -0
  157. package/dist/runner/chunk-IJ4SLUBV.js.map +7 -0
  158. package/dist/runner/chunk-IY7AP7NA.js +32 -0
  159. package/dist/runner/chunk-IY7AP7NA.js.map +7 -0
  160. package/dist/runner/chunk-J3F3Z3EQ.js +177 -0
  161. package/dist/runner/chunk-J3F3Z3EQ.js.map +7 -0
  162. package/dist/runner/chunk-JLEO5OHU.js +104 -0
  163. package/dist/runner/chunk-JLEO5OHU.js.map +7 -0
  164. package/dist/runner/chunk-JRNNLOPR.js +168 -0
  165. package/dist/runner/chunk-JRNNLOPR.js.map +7 -0
  166. package/dist/runner/chunk-KGSA5JYP.js +82 -0
  167. package/dist/runner/chunk-KGSA5JYP.js.map +7 -0
  168. package/dist/runner/chunk-LBCZAYFR.js +125 -0
  169. package/dist/runner/chunk-LBCZAYFR.js.map +7 -0
  170. package/dist/runner/chunk-LHWRXY2G.js +41 -0
  171. package/dist/runner/chunk-LHWRXY2G.js.map +7 -0
  172. package/dist/runner/chunk-LQ2LGUYJ.js +41 -0
  173. package/dist/runner/chunk-LQ2LGUYJ.js.map +7 -0
  174. package/dist/runner/chunk-LYY6RCIE.js +158 -0
  175. package/dist/runner/chunk-LYY6RCIE.js.map +7 -0
  176. package/dist/runner/chunk-M4R4QIQH.js +41 -0
  177. package/dist/runner/chunk-M4R4QIQH.js.map +7 -0
  178. package/dist/runner/chunk-MC75VXMX.js +207 -0
  179. package/dist/runner/chunk-MC75VXMX.js.map +7 -0
  180. package/dist/runner/chunk-NKZU4RRG.js +104 -0
  181. package/dist/runner/chunk-NKZU4RRG.js.map +7 -0
  182. package/dist/runner/chunk-PJHWHJ3K.js +56 -0
  183. package/dist/runner/chunk-PJHWHJ3K.js.map +7 -0
  184. package/dist/runner/chunk-RIGVYJ2O.js +114 -0
  185. package/dist/runner/chunk-RIGVYJ2O.js.map +7 -0
  186. package/dist/runner/chunk-RWRGC7ZK.js +93 -0
  187. package/dist/runner/chunk-RWRGC7ZK.js.map +7 -0
  188. package/dist/runner/chunk-SRMAJQMV.js +54 -0
  189. package/dist/runner/chunk-SRMAJQMV.js.map +7 -0
  190. package/dist/runner/chunk-TRMFD36J.js +47 -0
  191. package/dist/runner/chunk-TRMFD36J.js.map +7 -0
  192. package/dist/runner/chunk-U4IOZYQ3.js +21 -0
  193. package/dist/runner/chunk-U4IOZYQ3.js.map +7 -0
  194. package/dist/runner/chunk-UEXDE3WP.js +83 -0
  195. package/dist/runner/chunk-UEXDE3WP.js.map +7 -0
  196. package/dist/runner/chunk-UW3GQZSM.js +50 -0
  197. package/dist/runner/chunk-UW3GQZSM.js.map +7 -0
  198. package/dist/runner/chunk-V2GSP6VR.js +46 -0
  199. package/dist/runner/chunk-V2GSP6VR.js.map +7 -0
  200. package/dist/runner/chunk-VOV4Y5VU.js +81 -0
  201. package/dist/runner/chunk-VOV4Y5VU.js.map +7 -0
  202. package/dist/runner/chunk-VT5T6OEI.js +65 -0
  203. package/dist/runner/chunk-VT5T6OEI.js.map +7 -0
  204. package/dist/runner/chunk-VUYVFWIN.js +12 -0
  205. package/dist/runner/chunk-VUYVFWIN.js.map +7 -0
  206. package/dist/runner/chunk-VVGOPPEN.js +36 -0
  207. package/dist/runner/chunk-VVGOPPEN.js.map +7 -0
  208. package/dist/runner/chunk-VXFSLM6P.js +14 -0
  209. package/dist/runner/chunk-VXFSLM6P.js.map +7 -0
  210. package/dist/runner/chunk-W3EK7JUT.js +26125 -0
  211. package/dist/runner/chunk-W3EK7JUT.js.map +7 -0
  212. package/dist/runner/chunk-WJHNCOUF.js +52 -0
  213. package/dist/runner/chunk-WJHNCOUF.js.map +7 -0
  214. package/dist/runner/chunk-WU7ANGCW.js +269 -0
  215. package/dist/runner/chunk-WU7ANGCW.js.map +7 -0
  216. package/dist/runner/chunk-X7XLMSZX.js +44 -0
  217. package/dist/runner/chunk-X7XLMSZX.js.map +7 -0
  218. package/dist/runner/chunk-XSO3B4QN.js +124 -0
  219. package/dist/runner/chunk-XSO3B4QN.js.map +7 -0
  220. package/dist/runner/chunk-YGFN3LN2.js +174 -0
  221. package/dist/runner/chunk-YGFN3LN2.js.map +7 -0
  222. package/dist/runner/chunk-YHYDBLVB.js +33 -0
  223. package/dist/runner/chunk-YHYDBLVB.js.map +7 -0
  224. package/dist/runner/compact-36NP3PKT.js +60 -0
  225. package/dist/runner/compact-36NP3PKT.js.map +7 -0
  226. package/dist/runner/getMachineId-bsd-AGENNHN6.js +42 -0
  227. package/dist/runner/getMachineId-bsd-AGENNHN6.js.map +7 -0
  228. package/dist/runner/getMachineId-bsd-I5WZGCL4.js +33 -0
  229. package/dist/runner/getMachineId-bsd-I5WZGCL4.js.map +7 -0
  230. package/dist/runner/getMachineId-bsd-ZXK225P7.js +33 -0
  231. package/dist/runner/getMachineId-bsd-ZXK225P7.js.map +7 -0
  232. package/dist/runner/getMachineId-darwin-47GDLEXL.js +42 -0
  233. package/dist/runner/getMachineId-darwin-47GDLEXL.js.map +7 -0
  234. package/dist/runner/getMachineId-darwin-5CRLMDD6.js +33 -0
  235. package/dist/runner/getMachineId-darwin-5CRLMDD6.js.map +7 -0
  236. package/dist/runner/getMachineId-darwin-ADG4I32N.js +33 -0
  237. package/dist/runner/getMachineId-darwin-ADG4I32N.js.map +7 -0
  238. package/dist/runner/getMachineId-linux-5KVS3T2M.js +27 -0
  239. package/dist/runner/getMachineId-linux-5KVS3T2M.js.map +7 -0
  240. package/dist/runner/getMachineId-linux-GDFB5GSO.js +34 -0
  241. package/dist/runner/getMachineId-linux-GDFB5GSO.js.map +7 -0
  242. package/dist/runner/getMachineId-linux-NQMWCRO3.js +27 -0
  243. package/dist/runner/getMachineId-linux-NQMWCRO3.js.map +7 -0
  244. package/dist/runner/getMachineId-unsupported-5PFIGMVX.js +18 -0
  245. package/dist/runner/getMachineId-unsupported-5PFIGMVX.js.map +7 -0
  246. package/dist/runner/getMachineId-unsupported-DW27K3ZX.js +18 -0
  247. package/dist/runner/getMachineId-unsupported-DW27K3ZX.js.map +7 -0
  248. package/dist/runner/getMachineId-unsupported-XV3FHTHD.js +25 -0
  249. package/dist/runner/getMachineId-unsupported-XV3FHTHD.js.map +7 -0
  250. package/dist/runner/getMachineId-win-5JVMW3EI.js +44 -0
  251. package/dist/runner/getMachineId-win-5JVMW3EI.js.map +7 -0
  252. package/dist/runner/getMachineId-win-SNESQF7R.js +35 -0
  253. package/dist/runner/getMachineId-win-SNESQF7R.js.map +7 -0
  254. package/dist/runner/getMachineId-win-UJYHSBM2.js +35 -0
  255. package/dist/runner/getMachineId-win-UJYHSBM2.js.map +7 -0
  256. package/dist/runner/git-commit-BA53DOJQ.js +30 -0
  257. package/dist/runner/git-commit-BA53DOJQ.js.map +7 -0
  258. package/dist/runner/hook-runner-JHH6PGKE.js +220 -0
  259. package/dist/runner/hook-runner-JHH6PGKE.js.map +7 -0
  260. package/dist/runner/judge-transport-R4TF5LEH.js +91 -0
  261. package/dist/runner/judge-transport-R4TF5LEH.js.map +7 -0
  262. package/dist/runner/mcp-status-QEUH2KGX.js +89 -0
  263. package/dist/runner/mcp-status-QEUH2KGX.js.map +7 -0
  264. package/dist/runner/notification-FKMBCSXF.js +69 -0
  265. package/dist/runner/notification-FKMBCSXF.js.map +7 -0
  266. package/dist/runner/post-tool-3MRHTBKH.js +192 -0
  267. package/dist/runner/post-tool-3MRHTBKH.js.map +7 -0
  268. package/dist/runner/post-tool-agent-BB34MNHI.js +370 -0
  269. package/dist/runner/post-tool-agent-BB34MNHI.js.map +7 -0
  270. package/dist/runner/post-tool-changelog-sync-OP2TT2I7.js +147 -0
  271. package/dist/runner/post-tool-changelog-sync-OP2TT2I7.js.map +7 -0
  272. package/dist/runner/post-tool-code-structure-LE7J2SC2.js +130 -0
  273. package/dist/runner/post-tool-code-structure-LE7J2SC2.js.map +7 -0
  274. package/dist/runner/post-tool-edit-ledger-IJMEYHKF.js +30 -0
  275. package/dist/runner/post-tool-edit-ledger-IJMEYHKF.js.map +7 -0
  276. package/dist/runner/post-tool-failure-XTH2I2Z7.js +111 -0
  277. package/dist/runner/post-tool-failure-XTH2I2Z7.js.map +7 -0
  278. package/dist/runner/post-tool-git-E46HZGZO.js +94 -0
  279. package/dist/runner/post-tool-git-E46HZGZO.js.map +7 -0
  280. package/dist/runner/post-tool-mcp-AMCDY5GH.js +144 -0
  281. package/dist/runner/post-tool-mcp-AMCDY5GH.js.map +7 -0
  282. package/dist/runner/post-tool-task-state-TLDOI33H.js +100 -0
  283. package/dist/runner/post-tool-task-state-TLDOI33H.js.map +7 -0
  284. package/dist/runner/pre-tool-SQE2FZQO.js +245 -0
  285. package/dist/runner/pre-tool-SQE2FZQO.js.map +7 -0
  286. package/dist/runner/pre-tool-agent-OZUPVFUI.js +218 -0
  287. package/dist/runner/pre-tool-agent-OZUPVFUI.js.map +7 -0
  288. package/dist/runner/quality-evaluator-XYNDKDRG.js +901 -0
  289. package/dist/runner/quality-evaluator-XYNDKDRG.js.map +7 -0
  290. package/dist/runner/session-end-3MJTDLLA.js +57 -0
  291. package/dist/runner/session-end-3MJTDLLA.js.map +7 -0
  292. package/dist/runner/session-start-5ZMCLKBS.js +352 -0
  293. package/dist/runner/session-start-5ZMCLKBS.js.map +7 -0
  294. package/dist/runner/shipper-status-MADX6SPG.js +37 -0
  295. package/dist/runner/shipper-status-MADX6SPG.js.map +7 -0
  296. package/dist/runner/span-shipper-4HQDHC47.js +3408 -0
  297. package/dist/runner/span-shipper-4HQDHC47.js.map +7 -0
  298. package/dist/runner/stop-RTKSIYJV.js +596 -0
  299. package/dist/runner/stop-RTKSIYJV.js.map +7 -0
  300. package/dist/runner/subagent-CBCG4OLZ.js +116 -0
  301. package/dist/runner/subagent-CBCG4OLZ.js.map +7 -0
  302. package/dist/runner/token-metrics-AD2RAFGM.js +31 -0
  303. package/dist/runner/token-metrics-AD2RAFGM.js.map +7 -0
  304. package/dist/runner/user-prompt-T5NZ2UJD.js +376 -0
  305. package/dist/runner/user-prompt-T5NZ2UJD.js.map +7 -0
  306. package/package.json +70 -5
package/CONFIG.md ADDED
@@ -0,0 +1,144 @@
1
+ # Hooks Configuration Guide
2
+
3
+ ## Quick Start Configuration
4
+
5
+ ### 1. Register Hooks in settings.json
6
+
7
+ `~/.claude/settings.json` registers twelve events against one TypeScript runner, which dispatches on the sub-type argument. Every event carries one entry of this shape, differing only in the sub-type:
8
+
9
+ ```json
10
+ {
11
+ "hooks": {
12
+ "SessionStart": [
13
+ { "hooks": [{ "type": "command", "command": "node ~/.claude/hooks/dist/hook-runner.js session-start", "timeout": 15 }] }
14
+ ]
15
+ }
16
+ }
17
+ ```
18
+
19
+ | Event | Sub-type | Event | Sub-type |
20
+ |-------|----------|-------|----------|
21
+ | `SessionStart` | `session-start` | `SubagentStart` | `subagent-start` |
22
+ | `PreToolUse` | `pre-tool` | `SubagentStop` | `subagent-stop` |
23
+ | `PostToolUse` | `post-tool` | `PostToolUseFailure` | `post-tool-failure` |
24
+ | `Stop` | `stop` | `PreCompact` | `pre-compact` |
25
+ | `UserPromptSubmit` | `user-prompt` | `PostCompact` | `post-compact` |
26
+ | `Notification` | `notification` | `SessionEnd` | `session-end` |
27
+
28
+ `settings.json` is gitignored, so this section is the only version-controlled record of the registration, and `HOOK_TIMEOUT_MS` in `lib/core/constants.ts` the only one of the timeout. Keep all three in sync. The live file also registers an iTerm2 status-line command (`~/.config/iterm2/cc-status`, `timeout: 5`) on most of these events and on `PermissionRequest` and `StopFailure`; it is not part of this hooks system.
29
+
30
+ **Every runner entry sets `timeout: 15`; none sets `matcher`.** Both are deliberate.
31
+
32
+ - **`timeout` (CCH3)**: 15 s is a safety ceiling, not a tuning knob. It clears the measured 13.6 s maximum while cutting the 600 s default by 40×. Lowering it toward p99 (9.2 s) would kill the slowest legitimate runs and discard their telemetry silently.
33
+ - **`SessionEnd` ignores it.** Claude Code runs the whole SessionEnd phase under one `timeoutMs` shared by every registered SessionEnd hook, default **1500 ms**; on every other event the per-command `timeout` is the only ceiling. Since at least 2.1.319 the phase ceiling is the larger of that default and `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` (settings `env` or the shell; capped at 3,600,000 ms). This install sets it to `5000` in `settings.json` `env`, which is not version-controlled, so a fresh install runs at 1500 ms until it is set. `handlers/session-end.ts` is written to fit: one span, one metric and a *detached* shipper spawn. Keep transcript parsing and anything network-bound out of it.
34
+ - **`matcher` is unset; do not "optimise" it back in.** `handleBuiltinPreTool` and `handleBuiltinPostTool` act on every member of `BUILTIN_TOOLS` (42), so 97.5 % of tool calls (26,075 of 26,754 measured) reach a real handler and only 1.3 % are no-op spawns. A matcher would be a second, hand-maintained source of truth for that set; such a list has drifted before, leaving `ToolSearch` and 13 other tools emitting nothing. Membership comes from one table, and a tool outside it is counted in `integritystudio.tool.unknown` (CCH7). Narrowing PostToolUse off `Agent`/`Task` is the destructive case: it drops `popPendingAgent` + `appendSynthSpans`, so every invocation opens a record nothing closes and no `invoke_agent` span or `gen_ai.invoke_agent.duration` sample is emitted, with nothing failing (PT2).
35
+
36
+ See CCH2 (rejected, with measurements), CCH3 and CCH7 in [`docs/reviews/2026-07-28-claude-code-hooks-conformance-audit.md`](../docs/reviews/2026-07-28-claude-code-hooks-conformance-audit.md).
37
+
38
+ ### What the hooks deliver
39
+
40
+ The event, not the handler, decides the channel: plain stdout (`writePlainContext()`) reaches the model only on `SessionStart`, `UserPromptSubmit` and `UserPromptExpansion`; everything else must use `addAdditionalContext()`. Per-handler breakdown: [What Each Handler Delivers](./README.md#what-each-handler-delivers).
41
+
42
+ ### 2. Build the Hooks
43
+
44
+ ```bash
45
+ cd ~/.claude
46
+ npm install --prefix hooks # first time only
47
+ npm run hooks:build
48
+ ```
49
+
50
+ `hooks:build` runs two steps in order:
51
+
52
+ 1. `tsc -p tsconfig.build.json` emits `hooks/dist/` for every module, which the other lib CLIs still run from
53
+ 2. `scripts/bundle-runner.ts` (esbuild) bundles `runner-entry.ts` over that into `dist/hook-runner.js`, with content-hashed split chunks in `dist/runner/` so a handler loads only when its event fires (HDF22). It clears `dist/runner/` first, so superseded chunks do not pile up
54
+
55
+ The runner executes the bundle, so an unbuilt change is a silent no-op, and `build:watch` (tsc only) does not refresh it. `dist/` is tracked: commit the rebuild, including added and removed chunks, with the source.
56
+
57
+ ## Environment Variables
58
+
59
+ `OTEL_*` and credential variables from the shell or `settings.json` `env` never reach a hook. See root [README.md § Hook environment and credentials](../README.md#hook-environment-and-credentials) for what does, and where the endpoint and credential come from.
60
+
61
+ ### Per-Session Environment Variables
62
+
63
+ The SDK's standard `OTEL_*` variables take effect only when a hook is run by hand with a saved event payload on stdin:
64
+
65
+ ```bash
66
+ # Verbose SDK diagnostics
67
+ OTEL_LOG_LEVEL=debug node ~/.claude/hooks/dist/hook-runner.js <type> < payload.json
68
+
69
+ # No spans (traces only)
70
+ OTEL_TRACES_SAMPLER=always_off node ~/.claude/hooks/dist/hook-runner.js <type> < payload.json
71
+ ```
72
+
73
+ The payload must carry the fields Claude Code sends on every event: `session_id`, `transcript_path`, `cwd` and `hook_event_name`, plus `tool_name` on a tool event (`permission_mode` is optional; six events never send it). Otherwise the runner prints `stdin payload is missing required field` on stderr and exits 0 without running a handler, so a hand-written `{}` does nothing.
74
+
75
+ **The hooks have no telemetry off switch.** `OTEL_ENABLED` and `OTEL_SDK_DISABLED` change nothing, and the sampler variable never reaches a hook Claude Code runs (see [HOOKS_ARCHITECTURE.md § Sampling](../docs/architecture/HOOKS_ARCHITECTURE.md#sampling)). To stop delivery instead, unset the endpoint or the credential: the detached shipper stops and records `no-endpoint` / `no-auth` in `status.json`. Local JSONL is still written.
76
+
77
+ ## Hook Execution Order
78
+
79
+ Hooks run in the order `settings.json` lists them. `Stop` registers one entry; the `stop.ts` handler sequences the phases, each its own `stop-*.ts` file:
80
+
81
+ 1. Token metrics extraction from the transcript
82
+ 2. T2 LLM-judge quality evaluation: for a sampled session, spawns the detached `evaluate-quality` process with four positional args (session id, canary flag, transcript path, transcript bytes; `encodeEvaluationArgs`), which runs the judge (HDF3). Nothing here waits on the network
83
+ 3. Error-handling reminder: **skipped when `stop_hook_active` is set** (a hook-caused resume, HSF4) and latched to once per session. Reads the session's edit ledger, `edits.log` (`logEdit`/`loadEdits` in `lib/session/edit-ledger.ts`). Delivery is gated on the `REMINDER_SECTIONS` table in `stop-error-reminder.ts`, so the latch is claimed only when there is a section to render. `SKIP_ERROR_REMINDER=1` disables the step. History: CCH6a/CCH6b in the [conformance audit](../docs/reviews/2026-07-28-claude-code-hooks-conformance-audit.md)
84
+ 4. MCP session failure summary and telemetry alert evaluation (telemetry only)
85
+ 5. Detached `ship-telemetry` spawn, so no hook waits on a network flush. Runs only when some telemetry file in the window holds bytes past the shipper's cursor (`hasUnshippedTelemetry`, HDF2); otherwise it spawns nothing and leaves the status record alone. That process has no stdout, stderr or OTEL SDK, so it reports through `<telemetry>/shipper-ctx/status.json`; `session-start` prints one line from it when the last flush was unhealthy
86
+
87
+ ## Cache Management
88
+
89
+ ### Cache Locations
90
+
91
+ Paths come from `sessionStateDir` / `projectStateDir` in `lib/session/session-state.ts`; anchor on those symbols, not on the copies here. Everything a session leaves on disk lives under one directory. The only write into a project tree is the changelog link rewrite in `README.md`.
92
+
93
+ | Cache | Location | Purpose |
94
+ |-------|----------|---------|
95
+ | Session state | `~/.claude/session-state/<session_id>/` | Every per-session store (`sessionStateDir`); the per-file list is in [`TrackingFiles.md` § session-state](../docs/TrackingFiles.md#session-state); swept whole by `pruneSessionState` 30 days after its last write |
96
+ | Per-project pointers | `~/.claude/session-state/.projects/<slug>/` | `current-session-id`, read by the pre-commit staging-scope guard in `scripts/git-hooks/pre-commit` (GCS1; slug = project path with `/` and `.` as `-`), and `last-session.json`, the predecessor-session edge |
97
+ | Host state | `~/.claude/session-state/.host/` | Machine-level facts every hook would otherwise re-derive: `host-resource.json` (`hostStateDir`) |
98
+ | Quality state | `~/.claude/session-state/.quality/` | Cross-session: `budget.json` (the judge's daily spend, rolls over by date) and `degradation.json` (the post-judge drift window) (`qualityStateDir`) |
99
+ | Tool list cache | `~/.claude/.cache/active-tools-list.md` | Cached `/ls-tools` output |
100
+ | Agent/skill list | `~/.claude/.cache/agents-skills-list.md` | Cached `/ls-tools-all` output |
101
+
102
+ Clear the cached tool lists with `rm -rf ~/.claude/.cache/*`.
103
+
104
+ ## Troubleshooting Configuration
105
+
106
+ ### Hook Not Executing
107
+
108
+ 1. **Registration:** the event is in `~/.claude/settings.json`; a partial registration is a supported shape
109
+ 2. **Build:** `dist/` contains compiled JS (`npm run hooks:build` from `~/.claude`)
110
+ 3. **Sub-type argument:** the runner accepts only the twelve keys of `HOOK_HANDLERS` in `hook-runner.ts` (the same keys as `HOOK_EVENT_NAMES`); any other exits 1 (CCH5)
111
+ 4. **Payload:** one missing a required field is refused before any handler runs, with exit 0 (see [Per-Session Environment Variables](#per-session-environment-variables)); mostly a hook run by hand with a trimmed payload
112
+ 5. **Matcher:** none is set in this repo; if you added one, verify it matches the tool
113
+ 6. **Telemetry:** a hook that ran leaves a `hook:<name>` span in today's `traces-*.jsonl`; exit codes and non-blocking stderr go to Claude Code's debug log
114
+
115
+ ### TypeScript Compilation Errors
116
+
117
+ ```bash
118
+ cd ~/.claude/hooks
119
+ npx tsc --noEmit
120
+ ```
121
+
122
+ ### Performance Issues
123
+
124
+ Measure before changing anything, and measure the right thing: hook spans time the *handler*, while Claude Code blocks on the whole *process*. See [PERFORMANCE_MONITORING.md § Measurement caveat (CCH1)](./PERFORMANCE_MONITORING.md#measurement-caveat-cch1) for how to read `hook_success` `durationMs` instead, and [PERFORMANCE_PROFILE.md](../docs/PERFORMANCE_PROFILE.md) for where the time goes (dependency load per spawn, not per-component work). Leave matchers unset.
125
+
126
+ ### Debugging Hooks
127
+
128
+ SDK debug logging reaches only a hook run by hand (see [Per-Session Environment Variables](#per-session-environment-variables)). Local telemetry:
129
+
130
+ ```bash
131
+ ls -la ~/.claude-history/telemetry/
132
+ tail -20 ~/.claude-history/telemetry/traces-$(date +%Y-%m-%d).jsonl
133
+ cat ~/.claude-history/telemetry/shipper-ctx/status.json # is shipping working
134
+ ```
135
+
136
+ `TELEMETRY_DIR` names that directory (default `~/.claude-history/telemetry`). See root [README.md § Telemetry dir](../README.md#telemetry-dir).
137
+
138
+ ## See Also
139
+
140
+ - [README.md](./README.md) — hooks overview, and what each handler delivers through which channel
141
+ - [PERFORMANCE_MONITORING.md](./PERFORMANCE_MONITORING.md) — the fallback log, how to read it, and the CCH1 measurement caveat
142
+ - [docs/PERFORMANCE_PROFILE.md](../docs/PERFORMANCE_PROFILE.md) — measured latency, memory profile, regression guards
143
+ - [docs/architecture/HOOKS_ARCHITECTURE.md](../docs/architecture/HOOKS_ARCHITECTURE.md) — why the system is shaped this way
144
+ - [docs/architecture/hooks.md](../docs/architecture/hooks.md) — the code-level map: entry point, routing, `lib/` inventory
package/LICENSE ADDED
@@ -0,0 +1,95 @@
1
+ Copyright 2026 Integrity Studio
2
+
3
+ Elastic License 2.0
4
+
5
+ URL: https://www.elastic.co/licensing/elastic-license
6
+
7
+ Acceptance
8
+
9
+ By using the software, you agree to all of the terms and conditions below.
10
+
11
+ Copyright License
12
+
13
+ The licensor grants you a non-exclusive, royalty-free, worldwide,
14
+ non-sublicensable, non-transferable license to use, copy, distribute, make
15
+ available, and prepare derivative works of the software, in each case subject to
16
+ the limitations and conditions below.
17
+
18
+ Limitations
19
+
20
+ You may not provide the software to third parties as a hosted or managed
21
+ service, where the service provides users with access to any substantial set of
22
+ the features or functionality of the software.
23
+
24
+ You may not move, change, disable, or circumvent the license key functionality
25
+ in the software, and you may not remove or obscure any functionality in the
26
+ software that is protected by the license key.
27
+
28
+ You may not alter, remove, or obscure any licensing, copyright, or other notices
29
+ of the licensor in the software. Any use of the licensor’s trademarks is subject
30
+ to applicable law.
31
+
32
+ Patents
33
+
34
+ The licensor grants you a license, under any patent claims the licensor can
35
+ license, or becomes able to license, to make, have made, use, sell, offer for
36
+ sale, import and have imported the software, in each case subject to the
37
+ limitations and conditions in this license. This license does not cover any
38
+ patent claims that you cause to be infringed by modifications or additions to
39
+ the software. If you or your company make any written claim that the software
40
+ infringes or contributes to infringement of any patent, your patent license for
41
+ the software granted under these terms ends immediately. If your company makes
42
+ such a claim, your patent license ends immediately for work on behalf of your
43
+ company.
44
+
45
+ Notices
46
+
47
+ You must ensure that anyone who gets a copy of any part of the software from you
48
+ also gets a copy of these terms.
49
+
50
+ If you modify the software, you must include in any modified copies of the
51
+ software prominent notices stating that you have modified the software.
52
+
53
+ ## No Other Rights
54
+
55
+ These terms do not imply any licenses other than those expressly granted in
56
+ these terms.
57
+
58
+ Termination
59
+
60
+ If you use the software in violation of these terms, such use is not licensed,
61
+ and your licenses will automatically terminate. If the licensor provides you
62
+ with a notice of your violation, and you cease all violation of this license no
63
+ later than 30 days after you receive that notice, your licenses will be
64
+ reinstated retroactively. However, if you violate these terms after such
65
+ reinstatement, any additional violation of these terms will cause your licenses
66
+ to terminate automatically and permanently.
67
+
68
+ No Liability
69
+
70
+ As far as the law allows, the software comes as is, without any warranty or
71
+ condition, and the licensor will not be liable to you for any damages arising
72
+ out of these terms or the use or nature of the software, under any kind of
73
+ legal claim.
74
+
75
+ Definitions
76
+
77
+ The licensor is the entity offering these terms, and the software is the
78
+ software the licensor makes available under these terms, including any portion
79
+ of it.
80
+
81
+ you refers to the individual or entity agreeing to these terms.
82
+
83
+ your company is any legal entity, sole proprietorship, or other kind of
84
+ organization that you work for, plus all organizations that have control over,
85
+ are under the control of, or are under common control with that
86
+ organization. control means ownership of substantially all the assets of an
87
+ entity, or the power to direct its management and policies by vote, contract, or
88
+ otherwise. Control can be direct or indirect.
89
+
90
+ your licenses are all the licenses granted to you for the software under
91
+ these terms.
92
+
93
+ use means anything you do with the software requiring one of your licenses.
94
+
95
+ trademark means trademarks, service marks, and similar rights.
package/README.md CHANGED
@@ -1,3 +1,202 @@
1
- # Temporary Holding Version
1
+ # Claude Code Hooks
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Observability and quality-signal hooks for Claude Code sessions. Every tool invocation flows through a hook pipeline that emits OTEL traces, metrics, and local logs.
4
+
5
+ ## Data Flow
6
+
7
+ ```
8
+ Claude Code event (registered in settings.json)
9
+ |
10
+ v
11
+ hook-runner.js reads stdin JSON, extracts session_id, dispatches on HOOK_HANDLERS
12
+ |
13
+ +--> one of twelve hook types, dispatched to ten handler files in handlers/
14
+ | session-start, pre-tool, post-tool, stop, user-prompt, notification,
15
+ | subagent-start, subagent-stop, post-tool-failure, pre-compact,
16
+ | post-compact, session-end (subagent.ts and compact.ts serve two each)
17
+ |
18
+ v
19
+ each handler branch calls instrumentHook() itself
20
+ |
21
+ +--> OTEL spans/metrics/logs (all levels) -> local JSONL -> detached shipper -> OTLP
22
+ +--> Filesystem ~/.claude/session-state/<sid>/ every per-session store (HOOKS_DATA_FLOW.md)
23
+ +--> stdout/stderr the only model-facing path -- see Output Channels below
24
+ ```
25
+
26
+ **The runner instruments nothing.** It dispatches; every span comes from an
27
+ `instrumentHook()` call written inside a handler branch. A new branch that omits
28
+ the call runs, succeeds, and emits no telemetry.
29
+
30
+ This diagram deliberately stops at the handler boundary. Four documents own what
31
+ happens past it, and are kept current against the source:
32
+
33
+ - the complete data flow diagram, event to cloud consumer —
34
+ [`HOOKS_DATA_FLOW.md`](../docs/architecture/HOOKS_DATA_FLOW.md)
35
+ - the per-spawn hot path: what loads, and which files are read and written, around one handler —
36
+ [`HOOKS_HOT_PATH.html`](../docs/architecture/HOOKS_HOT_PATH.html)
37
+ - the PostToolUse router's ten arms —
38
+ [`hooks.md` § PostToolUse Routing](../docs/architecture/hooks.md#posttooluse-routing-handleposttool)
39
+ - the full export pipeline and every transport path —
40
+ [`HOOKS_ARCHITECTURE.md` § End-to-End Pipeline](../docs/architecture/HOOKS_ARCHITECTURE.md#end-to-end-pipeline)
41
+ and [§ Transport Paths](../docs/architecture/HOOKS_ARCHITECTURE.md#transport-paths)
42
+
43
+ ## Output Channels
44
+
45
+ The **event**, not the handler, decides where a hook's output goes. Claude Code injects plain stdout into the model's context for `SessionStart`, `UserPromptSubmit` and `UserPromptExpansion` only; on every other event stdout goes to the debug log. A mistake here is silent: the handler runs, the span records success, and nothing is delivered.
46
+
47
+ | Channel | How | Reaches Claude |
48
+ |---------|-----|----------------|
49
+ | stdout, plain text | `writePlainContext()` (`lib/runtime/hook-output.ts`) | SessionStart, UserPromptSubmit, UserPromptExpansion only |
50
+ | stdout, JSON `hookSpecificOutput.additionalContext` | `addAdditionalContext()` (`lib/runtime/hook-output.ts`), flushed once per process by the runner | Any event — injected as a system reminder |
51
+ | stderr + exit 2 | `writeStderr()` (`lib/core/format-utils.ts`) then `process.exit(2)` | Yes, and blocks the action (PreToolUse) |
52
+ | stderr + exit 0 | `writeStderr()` | No — diagnostics only, user-visible in transcript view |
53
+ | OTEL | `instrumentHook()` spans, metrics, logs (every severity, TRACE through FATAL) | No — telemetry sinks only |
54
+ | Filesystem | `~/.claude/session-state/<sid>/` (one directory per session, swept at 30 days), the `README.md` rewrite | No — side effects |
55
+
56
+ Two consequences:
57
+
58
+ - **Plain stdout outside those three events reaches nobody.** This was CCH0: the post-commit review prompt fired 244 times and was delivered zero times. Every other event must use `addAdditionalContext()`.
59
+ - **stderr reaches Claude only at exit 2.** Every stderr line in `hooks/` goes through `writeStderr()`; tests capture it with `captureStderr()` (`lib/__tests__/stderr-capture.ts`). `hook-runner.ts` never exits 2 — it exits `HOOK_EXIT.OK` on every handler path and `HOOK_EXIT.NONBLOCKING_ERROR` (1) on misconfiguration, a crashed detached mode, or a reported `evaluate-quality` failure, and neither delivers stderr to Claude. The one model-facing stderr path in the system is the PreToolUse agent scope-guard denials, which exit 2 through `denyToolUse()` (`lib/runtime/hook-output.ts`).
60
+
61
+ ## What Each Handler Delivers
62
+
63
+ "Model-facing" means the output reaches Claude. Everything else is telemetry, diagnostics, or a side effect on disk.
64
+
65
+ ### SessionStart — `handlers/session-start.ts`
66
+
67
+ | Deliverable | Channel | Model-facing |
68
+ |-------------|---------|--------------|
69
+ | Session banner: Node version, project name, active tasks, git branch + uncommitted count, context-window utilization, pending `docs/handoffs/` notes, and restored tasks (on resume only) | stdout, plain text | Yes |
70
+ | `Telemetry: not shipping — …` — one line read from `shipper-ctx/status.json`, emitted **only when the last flush was unhealthy**. The detached shipper has no other channel: no SDK, and `stdio: 'ignore'`. See [Shipper Status Record](../docs/architecture/HOOKS_ARCHITECTURE.md#shipper-status-record-libshippershipper-statusts) | stdout, plain text | Yes |
71
+ | `hook:session-start` span, predecessor-session attributes, `integritystudio.telemetry.shipper.outcome` when unhealthy | OTEL | No |
72
+ | Git state disk cache | Filesystem | No |
73
+
74
+ ### UserPromptSubmit — `handlers/user-prompt.ts`
75
+
76
+ | Deliverable | Channel | Model-facing |
77
+ |-------------|---------|--------------|
78
+ | `SKILL ACTIVATION CHECK` block — matched skills grouped by priority, with "Use Skill tool BEFORE responding" | stdout, plain text | Yes |
79
+ | `skill_activation.keyword_matches` / `.intent_matches` | OTEL | No |
80
+ | `Skipped an unusable skill-rules.json` — a candidate file exists but carries no `skills` object, so it is skipped rather than shadowing the home rules | OTEL log (WARN) | No |
81
+
82
+ ### PreToolUse — `handlers/pre-tool.ts`, `handlers/pre-tool-agent.ts`
83
+
84
+ Mostly instrumentation. The one model-facing path is the agent scope guards (`handleAgentScopeGuards` in `pre-tool-agent.ts`, run first; the router loads that file on first use), which deny an out-of-scope call from a subagent; they act only when `input.agent_type` is present, so they never deny a main-loop call.
85
+
86
+ | Deliverable | Channel | Model-facing |
87
+ |-------------|---------|--------------|
88
+ | Agent scope-guard denial via `denyToolUse()` (`lib/runtime/hook-output.ts`): an out-of-scope call (AA1e), or an auto-error-resolver write past its 3-file budget (AA1g) | stderr + **exit 2**, blocking the call | Yes |
89
+ | `hook:mcp-pre-tool` / `hook:plugin-pre-tool` / `hook:agent.operation.prepare` / `hook:builtin-pre-tool` spans | OTEL | No |
90
+ | On `hook:builtin-pre-tool`: `gen_ai.tool.name`, `integritystudio.tool.category`, `session.id`, agent attribution, the prompt-span link, and per-tool context (`file.path` / `file.extension` on file tools; `edit.*`, `bash.*`, `glob.*`, `grep.*`, `web.*` sizes and shapes, never contents); the `integritystudio.tool.invocations` counter. Legacy `builtin.*` keys on older stored spans were renamed by the toolkit's D1 migration 0019 | OTEL | No |
91
+ | Pending agent record, a per-name LIFO stack (`lib/agent/agent-context.ts`), and the auto-error-resolver file budget (`lib/agent/agent-file-budget.ts`), both written by `pre-tool-agent.ts`; the HEAD snapshot before a git commit (`lib/git/git-commit.ts`). The prompt-span link is only read here (`lib/otel/trace-context.ts`) | Filesystem | No |
92
+
93
+ ### PostToolUse — `handlers/post-tool.ts`
94
+
95
+ Router with ten arms (`handlePostTool`), enumerated against the source in [`hooks.md` § PostToolUse Routing](../docs/architecture/hooks.md#posttooluse-routing-handleposttool). Two deliverables are model-facing: one on Bash (git commit — `handlers/post-tool-git.ts`), one on Write/Bash (the changelog link rewrite).
96
+
97
+ | Branch | Deliverable | Channel | Model-facing |
98
+ |--------|-------------|---------|--------------|
99
+ | Bash (git commit) | Post-commit code review prompt — launches the `code-reviewer` agent. Also fires for the `/git-commit-smart` helper (`conventional-commit.sh`), which commits without `git commit` in the command line; its commits are found through the PreToolUse HEAD snapshot. When the command made several commits (the helper's source/config/docs run), the prompt diffs `<HEAD before>..HEAD` and the docs-only check covers all of them. Suppressed when every path in `git diff-tree -m --first-parent --root HEAD` (or, for several commits, every file they touched) ends in `.md`; a list git cannot produce (not a repo, missing binary, timeout) is treated as unknown and still reviews. **Not `git show`** — see the merge note below | `additionalContext` | Yes |
100
+ | Bash (git commit) | `hook:post-commit-review` span: `integritystudio.git.{command,commit_count,files_changed,files_outcome,docs_only}` and `integritystudio.git.files`, the committed names (capped at 200; `files_truncated` when capped). That list is the one per-file record a Bash-driven edit leaves, and the session files ledger unions it with the edit-tool spans' `file.path`. Counters: `integritystudio.git.commits_reviewed` / `commits_review_skipped` | OTEL | No |
101
+ | Write/Edit/MultiEdit | `hook:code-structure` signals and score metric | OTEL | No |
102
+ | Write/Edit/MultiEdit | Appends `(tool, agent, realpath)` to the session's `edits.log` (`lib/session/edit-ledger.ts`): the input to the Stop error-handling reminder. Main-loop edits carry no `agent_type`, so their agent field is empty | Filesystem | No |
103
+ | Write / Bash `mkdir` | Only for a Write into, or a Bash `mkdir` of, a new `docs/changelog/<version>/` (the version must be newer than the README's current link): rewrites the `[Changelog](…)` link in `README.md` to the latest version, and says so — the notice names the file and both links so the mutation is visible in the turn that caused it (HRV11) | Filesystem (mutates a tracked file) + `additionalContext` | Yes |
104
+ | MCP | `hook:mcp-post-tool` span, MCP completeness record (`session-state/<sid>/mcp-invocations.jsonl`) | OTEL + Filesystem | No |
105
+ | Plugin (Skill) | `hook:plugin-post-tool` span | OTEL | No |
106
+ | Agent | `hook:agent.operation.finalize` span, plus the synthetic `create_agent` / `invoke_agent` spans (appended to the traces file) and the `gen_ai.invoke_agent.duration` histogram, built from the pre-tool record persisted per session (PT2). There are no `execute_tool` spans | OTEL | No |
107
+ | McpResource | `hook:mcp-server-failure` span + `mcp.server.failures` on "Server not found", once per server per session — latched on disk (`~/.claude/session-state/<session>/mcp-failures/<server>.marker`, atomic `wx`), reset at SessionStart; with no `session_id` every failure reports | OTEL | No |
108
+ | TaskCreate/TaskUpdate | `hook:builtin.task-state` span (`integritystudio.task.id`, `integritystudio.task.status`), task-state persistence and status transitions (`handlers/post-tool-task-state.ts`) | OTEL + Filesystem | No |
109
+ | other builtin | `hook:builtin-post-tool` span — `gen_ai.tool.name`, `integritystudio.tool.{category,success,output_size,has_error,error_type,error_category,result_count}`, and `file.path` on file tools — plus the `integritystudio.tool.{completions,errors,output_size,result_count}` instruments and the `integritystudio.llm.tool.correctness` metric | OTEL | No |
110
+ | unmatched tool | `hook:unknown-tool` span and the `integritystudio.tool.unknown` counter — the drift alarm, mirrored in `pre-tool.ts` (`lib/runtime/unknown-tool.ts`) | OTEL | No |
111
+
112
+ **Note — the docs-only skip lists files with `diff-tree`, never `git show`.** `git show` defaults to a dense combined diff (`--cc`) on a merge commit, which drops every file identical to at least one parent. A clean merge therefore listed *nothing* — harmless, since an empty list means "unknown" and falls open into reviewing. The case that bit was a merge whose **only conflicts were Markdown**: the resolved file differs from both parents, so it survived the filter and was listed *alone*, making a merge that introduced arbitrary code look documentation-only. That list is non-empty, so the empty-list guard does not catch it, and the review was silently skipped. `diff-tree -m --first-parent` names the files against the first parent instead, classifying a merge on everything it brought in. `--root` is load-bearing — without it `diff-tree` is silent on a parentless initial commit; `-m` still emits one block per parent despite `--first-parent`, hence the dedupe.
113
+
114
+ ### Stop — `handlers/stop.ts`
115
+
116
+ `stop.ts` is the sequencer: it owns the phase order (listed in
117
+ [CONFIG.md § Hook Execution Order](./CONFIG.md#hook-execution-order); the table below is by
118
+ deliverable, not in run order). Stop never blocks. Each phase is its own file
119
+ (HRV12): `stop-error-reminder.ts` (row 1), `stop-token-metrics.ts` (row 2),
120
+ `stop-quality-evaluation.ts` (row 3, with the judge client in `lib/quality/llm-judge.ts`) and
121
+ `stop-session-summary.ts` (row 4). Row 5 has no phase file: `stop.ts` calls
122
+ `spawnTelemetryShipper` (`lib/shipper/telemetry-shipper.ts`) itself.
123
+
124
+ | Deliverable | Channel | Model-facing |
125
+ |-------------|---------|--------------|
126
+ | Error-handling self-check over risky edited files, once per session (`claimErrorReminder` latch) — see note below | `additionalContext` | Yes |
127
+ | Token usage and main-loop tool durations from the incremental transcript read; no cost — `integritystudio.gen_ai.cost` is judge-only and Claude Code reports its own spend as `claude_code.cost.usage` (TMX3) | OTEL | No |
128
+ | T2 handoff when the session is sampled: the transcript path and size Stop recorded, passed as CLI args to the detached `evaluate-quality` process that draws and scores the turns, so the judge never shares Stop's hook timeout (HDF3) | subprocess args | No |
129
+ | MCP session failure summary, telemetry alert evaluation | OTEL only | No |
130
+ | Detached `ship-telemetry` process forwarding spans to OTLP | Subprocess | No |
131
+
132
+ The detached evaluator (`lib/quality/quality-evaluator.ts`) delivers the LLM-judge evaluation (relevance, coherence) as evaluation log events and metrics, and — NORMAL cohort only — the post-judge EWMA drift check over those scores (`integritystudio.quality.degradation_check` counter; `integritystudio.quality.degradation_confirmed` span event on two consecutive breaches). Its `quality-evaluation-t2` span carries `hook.trigger: Stop`, so dashboards keyed on the span name are unchanged.
133
+
134
+ The Stop latch is load-bearing: `additionalContext` on `Stop` **resumes the conversation**, and the reminder's trigger stays true across the resume, so without the latch it loops.
135
+
136
+ **Note — the error-handling self-check** (CCH6a/CCH6b): when it fires is in [CONFIG.md § Hook Execution Order](./CONFIG.md#hook-execution-order) (step 3).
137
+
138
+ ### Notification — `handlers/notification.ts`
139
+
140
+ | Deliverable | Channel | Model-facing |
141
+ |-------------|---------|--------------|
142
+ | `integritystudio.notification.total` / `.errors` / `.warnings`, `integritystudio.notification.severity` classification, exception recording | OTEL | No |
143
+
144
+ ### SubagentStart / SubagentStop — `handlers/subagent.ts` (CCH4)
145
+
146
+ | Deliverable | Channel | Model-facing |
147
+ |-------------|---------|--------------|
148
+ | `integritystudio.subagent.starts` / `.completions`, labelled `integritystudio.agent.{type,category}`; spans carry `integritystudio.agent.instance_id`, `.type`, `.category`, plus `integritystudio.agent.transcript_path` and `.has_transcript` on stop. SubagentStop also emits `gen_ai.invoke_agent.inference_calls`, `gen_ai.invoke_agent.tool_calls` and agent-scoped `gen_ai.execute_tool.duration` | OTEL | No |
149
+
150
+ These events track the agent's *own* lifecycle, not the Agent tool call `pre-tool.ts` already instruments: a tool result can arrive without the agent having run. Claude Code also sends `agent_id`/`agent_type` on PreToolUse/PostToolUse fired inside a subagent; the builtin pre/post handlers stamp them as `gen_ai.agent.name`/`integritystudio.agent.instance_id` via `agentAttribution()` in `lib/agent/agent-sources.ts`. On tool spans before 2026-09-29, `gen_ai.agent.id` holds that run id instead of the stable `composeAgentId` identity agent spans use.
151
+
152
+ ### PostToolUseFailure — `handlers/post-tool-failure.ts` (CCH4)
153
+
154
+ | Deliverable | Channel | Model-facing |
155
+ |-------------|---------|--------------|
156
+ | `integritystudio.tool.failures`, labelled `gen_ai.tool.name` and `integritystudio.tool.{router_category,error_category,is_interrupt}`, and `integritystudio.tool.failure_duration` (by tool name), from Claude Code's reported `error` / `is_interrupt` / `duration_ms` | OTEL | No |
157
+
158
+ This is ground truth; `analyzeBuiltinOutput` on the success path is a substring heuristic. Both are kept, because only comparing them shows how wrong the heuristic is. A user interrupt is split out as `error_category: interrupt` so cancellations do not inflate the failure rate.
159
+
160
+ ### PreCompact / PostCompact — `handlers/compact.ts` (CCH4)
161
+
162
+ | Deliverable | Channel | Model-facing |
163
+ |-------------|---------|--------------|
164
+ | `integritystudio.context.compactions`, `.compactions_completed`, `.compaction_summary_size`, all labelled `integritystudio.compaction.trigger` | OTEL | No |
165
+
166
+ `context-tracker.ts` measures how full the window is on every prompt; this is the event that empties it. Without it the utilization series is a sawtooth with no cause.
167
+
168
+ ### SessionEnd — `handlers/session-end.ts` (CCH4)
169
+
170
+ | Deliverable | Channel | Model-facing |
171
+ |-------------|---------|--------------|
172
+ | `integritystudio.session.ends`, labelled `integritystudio.session.end_reason`, plus the detached telemetry shipper spawn | OTEL + process | No |
173
+
174
+ **Runs under a budget Claude Code imposes on the whole event** (1.5 s by default, 5 s as configured here) — see [CONFIG.md](./CONFIG.md#1-register-hooks-in-settingsjson). Keep it cheap. Before this existed, `Stop` was the only flush point, so spans produced after the final turn shipped on the *next* session's first stop, or never.
175
+
176
+ ## Where the rest of this is documented
177
+
178
+ Other documents own these five topics. They are linked here, not copied, because
179
+ copies drift from their owner:
180
+
181
+ | Topic | Owner |
182
+ |---|---|
183
+ | Core Libraries table | [`hooks.md` § Library Layer](../docs/architecture/hooks.md#library-layer-lib) — grouped by role and kept against the source |
184
+ | Span Types table | [`PERFORMANCE_MONITORING.md` § Span names](./PERFORMANCE_MONITORING.md#span-names) — organized by event, and complete |
185
+ | Resource Attributes | [`HOOKS_ARCHITECTURE.md` § OpenTelemetry](../docs/architecture/HOOKS_ARCHITECTURE.md#opentelemetry-libotelotelts-libotelotel-monitorts) — including why only `metrics-*.jsonl` carries the full bag |
186
+ | Transport | [`HOOKS_ARCHITECTURE.md` § Transport Paths](../docs/architecture/HOOKS_ARCHITECTURE.md#transport-paths) |
187
+ | Attribute and metric keys | [`PERFORMANCE_PROFILE.md` § Attribute Naming](../docs/PERFORMANCE_PROFILE.md#attribute-naming-obp7b-canonical-keys) — canonical-only emission, the legacy → canonical renames, and the D1 migrations that renamed the stored keys |
188
+
189
+ This file owns the output-channel rules and the per-handler delivery tables above;
190
+ [`CLAUDE.md`](../CLAUDE.md) cites them as authoritative for what each handler
191
+ delivers and through which channel.
192
+
193
+ ## Running Tests
194
+
195
+ Run from `~/.claude`. The root `vitest.config.ts` holds the `hooks` project; `npm test`
196
+ inside `hooks/` delegates to it:
197
+
198
+ ```bash
199
+ npm run hooks:test # full suite
200
+ npx vitest run --project hooks handlers/ # handler tests only
201
+ npm run hooks:check # tsc --noEmit, then agents:check
202
+ ```
@@ -0,0 +1,38 @@
1
+ /**
2
+ * PreCompact / PostCompact (CCH4): the event that empties the context window,
3
+ * without which the utilization series is a sawtooth with no cause.
4
+ */
5
+ import { boundedLabel } from '../lib/core/bounded-label.js';
6
+ import { UNITS } from '../lib/core/units.js';
7
+ import { COMPACTION_ATTRIBUTES, COMPACTION_TRIGGERS, CONTEXT_METRICS, HOOK_NAMES, HOOK_TYPE_ATTR } from '../lib/otel/attributes.js';
8
+ import { instrumentHook } from '../lib/otel/otel-monitor.js';
9
+ const KNOWN_TRIGGERS = new Set(Object.values(COMPACTION_TRIGGERS));
10
+ /** Both phases: bounded trigger label on the span, log and metrics; raw value on the span so payload drift stays visible. */
11
+ function handleCompaction(hookName, rawTrigger, phase) {
12
+ return instrumentHook(hookName, (ctx) => {
13
+ const triggerLabel = { [COMPACTION_ATTRIBUTES.TRIGGER]: boundedLabel(rawTrigger, KNOWN_TRIGGERS) };
14
+ ctx.addAttributes({ ...triggerLabel, [COMPACTION_ATTRIBUTES.TRIGGER_RAW]: rawTrigger ?? '' });
15
+ phase(ctx, triggerLabel);
16
+ }, { [HOOK_TYPE_ATTR]: 'compaction' });
17
+ }
18
+ export function handlePreCompact(input) {
19
+ return handleCompaction(HOOK_NAMES.PRE_COMPACT, input.trigger, (ctx, triggerLabel) => {
20
+ const instructions = input.custom_instructions ?? '';
21
+ ctx.addAttributes({
22
+ [COMPACTION_ATTRIBUTES.HAS_CUSTOM_INSTRUCTIONS]: !!instructions,
23
+ [COMPACTION_ATTRIBUTES.CUSTOM_INSTRUCTIONS_LENGTH]: instructions.length,
24
+ });
25
+ ctx.logger.info('Context compaction starting', triggerLabel);
26
+ ctx.recordMetric(CONTEXT_METRICS.COMPACTIONS, 1, triggerLabel, { unit: UNITS.RUN });
27
+ });
28
+ }
29
+ export function handlePostCompact(input) {
30
+ return handleCompaction(HOOK_NAMES.POST_COMPACT, input.trigger, (ctx, triggerLabel) => {
31
+ const summaryLength = (input.compact_summary ?? '').length;
32
+ ctx.addAttributes({ [COMPACTION_ATTRIBUTES.SUMMARY_LENGTH]: summaryLength });
33
+ ctx.logger.info('Context compaction complete', { ...triggerLabel, [COMPACTION_ATTRIBUTES.SUMMARY_LENGTH]: summaryLength });
34
+ // The retained floor each compaction leaves behind.
35
+ ctx.recordMetric(CONTEXT_METRICS.COMPACTION_SUMMARY_SIZE, summaryLength, triggerLabel, { unit: UNITS.BYTE });
36
+ ctx.recordMetric(CONTEXT_METRICS.COMPACTIONS_COMPLETED, 1, triggerLabel, { unit: UNITS.COMPLETION });
37
+ });
38
+ }
@@ -0,0 +1,66 @@
1
+ /** MCP server-unavailable failures, parsed from tool errors and reported once per session per server. */
2
+ import { UNITS } from '../lib/core/units.js';
3
+ import { getAllMcpServers } from '../lib/mcp/mcp-config.js';
4
+ import { claimFailureReport } from '../lib/mcp/mcp-failure-latch.js';
5
+ import { HOOK_NAMES, HOOK_TYPE_ATTR } from '../lib/otel/attributes.js';
6
+ import { instrumentHook } from '../lib/otel/otel-monitor.js';
7
+ import { boundedScanText } from '../lib/runtime/output-analyzer.js';
8
+ import { resolveOutputText } from '../lib/runtime/tool-output.js';
9
+ /** Vendor-prefixed: `mcp.*` is the semconv MCP namespace and these are not its keys; no alias rows for the old names. */
10
+ const MCP_FAILURE_ATTR = {
11
+ SERVER_NAME: 'integritystudio.mcp.server.name',
12
+ SERVER_STATUS: 'integritystudio.mcp.server.status',
13
+ SERVER_CONFIGURED: 'integritystudio.mcp.server.configured',
14
+ SERVER_COMMAND: 'integritystudio.mcp.server.command',
15
+ SERVER_TYPE: 'integritystudio.mcp.server.type',
16
+ SERVER_DESCRIPTION: 'integritystudio.mcp.server.description',
17
+ SERVERS_AVAILABLE: 'integritystudio.mcp.servers.available',
18
+ SERVERS_AVAILABLE_COUNT: 'integritystudio.mcp.servers.available_count',
19
+ SERVERS_CONFIGURED_COUNT: 'integritystudio.mcp.servers.configured_count',
20
+ };
21
+ function parseMcpError(output) {
22
+ const match = boundedScanText(output).match(/Server "([^"]+)" not found\. Available servers: (.+)/);
23
+ if (!match)
24
+ return null;
25
+ const [, server = '', available = ''] = match;
26
+ return { server, available: available.split(', ').map((s) => s.trim()) };
27
+ }
28
+ export async function handleMcpStatus(input) {
29
+ const output = resolveOutputText(input);
30
+ if (!output)
31
+ return;
32
+ // The gate: a non-matching output is not a server failure, so callers carry no copy of the grammar.
33
+ const errorInfo = parseMcpError(output);
34
+ if (!errorInfo)
35
+ return;
36
+ if (!claimFailureReport(input.session_id, errorInfo.server))
37
+ return;
38
+ await instrumentHook(HOOK_NAMES.MCP_SERVER_FAILURE, (ctx) => {
39
+ const configuredServers = getAllMcpServers(input.cwd);
40
+ const serverConfig = configuredServers.get(errorInfo.server);
41
+ ctx.addAttributes({
42
+ [MCP_FAILURE_ATTR.SERVER_NAME]: errorInfo.server,
43
+ [MCP_FAILURE_ATTR.SERVER_STATUS]: 'failed',
44
+ [MCP_FAILURE_ATTR.SERVER_CONFIGURED]: configuredServers.has(errorInfo.server),
45
+ [MCP_FAILURE_ATTR.SERVERS_AVAILABLE]: errorInfo.available.join(','),
46
+ [MCP_FAILURE_ATTR.SERVERS_AVAILABLE_COUNT]: errorInfo.available.length,
47
+ [MCP_FAILURE_ATTR.SERVERS_CONFIGURED_COUNT]: configuredServers.size,
48
+ });
49
+ if (serverConfig?.command) {
50
+ ctx.addAttribute(MCP_FAILURE_ATTR.SERVER_COMMAND, serverConfig.command);
51
+ }
52
+ if (serverConfig?.type) {
53
+ ctx.addAttribute(MCP_FAILURE_ATTR.SERVER_TYPE, serverConfig.type);
54
+ }
55
+ if (serverConfig?.description) {
56
+ ctx.addAttribute(MCP_FAILURE_ATTR.SERVER_DESCRIPTION, serverConfig.description);
57
+ }
58
+ ctx.recordMetric('integritystudio.mcp.server.failures', 1, {
59
+ [MCP_FAILURE_ATTR.SERVER_NAME]: errorInfo.server,
60
+ }, { unit: UNITS.FAILURE });
61
+ ctx.logger.warn('MCP server not available', {
62
+ [MCP_FAILURE_ATTR.SERVER_NAME]: errorInfo.server,
63
+ [MCP_FAILURE_ATTR.SERVERS_AVAILABLE]: errorInfo.available.join(', '),
64
+ });
65
+ }, { [HOOK_TYPE_ATTR]: 'mcp-init' });
66
+ }
@@ -0,0 +1,45 @@
1
+ /** Notification event: level, classified severity, and error/warning counters. */
2
+ import { THRESHOLDS, UNKNOWN_TOOL_NAME } from '../lib/core/constants.js';
3
+ import { UNITS } from '../lib/core/units.js';
4
+ import { GENAI_TOOL_NAME_ATTR, HOOK_NAMES, HOOK_TYPE_ATTR } from '../lib/otel/attributes.js';
5
+ import { instrumentHook } from '../lib/otel/otel-monitor.js';
6
+ import { classifyNotification } from '../lib/runtime/categorizers.js';
7
+ /** Span, log and metric-label key for the notification level. */
8
+ const NOTIFICATION_LEVEL_ATTR = 'integritystudio.notification.level';
9
+ export async function handleNotification(input) {
10
+ await instrumentHook(HOOK_NAMES.NOTIFICATION, (ctx) => {
11
+ const message = input.message || input.tool_output || '';
12
+ const level = input.level || 'info';
13
+ const toolName = input.tool_name ?? '';
14
+ ctx.addAttributes({
15
+ [NOTIFICATION_LEVEL_ATTR]: level,
16
+ 'integritystudio.notification.message_length': message.length,
17
+ 'integritystudio.notification.tool_name': toolName,
18
+ });
19
+ const severity = classifyNotification(level, message);
20
+ ctx.addAttribute('integritystudio.notification.severity', severity);
21
+ const recordedMessage = message.slice(0, THRESHOLDS.ERROR_MESSAGE_TRUNCATE);
22
+ if (severity === 'error') {
23
+ ctx.span.recordException(new Error(recordedMessage));
24
+ ctx.logger.error('Notification error', {
25
+ 'integritystudio.notification.message': recordedMessage,
26
+ 'integritystudio.notification.tool': toolName,
27
+ });
28
+ ctx.recordMetric('integritystudio.notification.errors', 1, {
29
+ [GENAI_TOOL_NAME_ATTR]: toolName || UNKNOWN_TOOL_NAME,
30
+ }, { unit: UNITS.ERROR });
31
+ }
32
+ else if (severity === 'warning') {
33
+ ctx.logger.warn('Notification warning', {
34
+ 'integritystudio.notification.message': recordedMessage,
35
+ });
36
+ ctx.recordMetric('integritystudio.notification.warnings', 1, undefined, { unit: UNITS.WARNING });
37
+ }
38
+ else {
39
+ ctx.logger.info('Notification received', {
40
+ [NOTIFICATION_LEVEL_ATTR]: level,
41
+ });
42
+ }
43
+ ctx.recordMetric('integritystudio.notification.total', 1, { [NOTIFICATION_LEVEL_ATTR]: level }, { unit: UNITS.NOTIFICATION });
44
+ }, { [HOOK_TYPE_ATTR]: 'notification' });
45
+ }