observability-toolkit-hooks 0.0.0-stage → 1.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.
- package/CONFIG.md +144 -0
- package/README.md +201 -2
- package/dist/handlers/compact.js +38 -0
- package/dist/handlers/mcp-status.js +66 -0
- package/dist/handlers/notification.js +45 -0
- package/dist/handlers/post-tool-agent.js +157 -0
- package/dist/handlers/post-tool-changelog-sync.js +148 -0
- package/dist/handlers/post-tool-code-structure.js +116 -0
- package/dist/handlers/post-tool-edit-ledger.js +15 -0
- package/dist/handlers/post-tool-failure.js +83 -0
- package/dist/handlers/post-tool-git.js +79 -0
- package/dist/handlers/post-tool-mcp.js +105 -0
- package/dist/handlers/post-tool-outcome.js +48 -0
- package/dist/handlers/post-tool-task-state.js +74 -0
- package/dist/handlers/post-tool.js +132 -0
- package/dist/handlers/pre-tool-agent.js +192 -0
- package/dist/handlers/pre-tool.js +218 -0
- package/dist/handlers/session-end.js +39 -0
- package/dist/handlers/session-start.js +262 -0
- package/dist/handlers/stop-error-reminder.js +195 -0
- package/dist/handlers/stop-quality-evaluation.js +58 -0
- package/dist/handlers/stop-session-summary.js +62 -0
- package/dist/handlers/stop-token-metrics.js +83 -0
- package/dist/handlers/stop.js +25 -0
- package/dist/handlers/subagent.js +105 -0
- package/dist/handlers/tool-event-router.js +39 -0
- package/dist/handlers/user-prompt.js +218 -0
- package/dist/hook-runner.js +10 -0
- package/dist/hook-runner.js.map +7 -0
- package/dist/lib/agent/agent-context.js +123 -0
- package/dist/lib/agent/agent-evaluations.js +155 -0
- package/dist/lib/agent/agent-file-budget.js +65 -0
- package/dist/lib/agent/agent-sources.js +165 -0
- package/dist/lib/agent/synth-spans.js +51 -0
- package/dist/lib/core/bounded-label.js +6 -0
- package/dist/lib/core/category-rules.js +11 -0
- package/dist/lib/core/child-result.js +19 -0
- package/dist/lib/core/config-dir-recovery.js +22 -0
- package/dist/lib/core/constants.js +171 -0
- package/dist/lib/core/detached-runner.js +55 -0
- package/dist/lib/core/file-utils.js +353 -0
- package/dist/lib/core/format-utils.js +51 -0
- package/dist/lib/core/http-utils.js +74 -0
- package/dist/lib/core/http1-fetch.js +14 -0
- package/dist/lib/core/identity-key-resolver.js +149 -0
- package/dist/lib/core/jsonl-tail.js +207 -0
- package/dist/lib/core/load-envrc.js +72 -0
- package/dist/lib/core/parsers.js +43 -0
- package/dist/lib/core/regex.js +27 -0
- package/dist/lib/core/settings-env.js +31 -0
- package/dist/lib/core/shell-command.js +122 -0
- package/dist/lib/core/units.js +97 -0
- package/dist/lib/git/git-cache.js +158 -0
- package/dist/lib/git/git-commit.js +189 -0
- package/dist/lib/git/git-exec.js +30 -0
- package/dist/lib/mcp/mcp-completeness.js +40 -0
- package/dist/lib/mcp/mcp-config.js +118 -0
- package/dist/lib/mcp/mcp-failure-latch.js +22 -0
- package/dist/lib/mcp/mcp-identity-launcher.js +43 -0
- package/dist/lib/otel/attributes.js +322 -0
- package/dist/lib/otel/evaluation-attrs.js +51 -0
- package/dist/lib/otel/file-exporters.js +169 -0
- package/dist/lib/otel/host-resource.js +61 -0
- package/dist/lib/otel/otel-headers-helper.js +26 -0
- package/dist/lib/otel/otel-monitor.js +181 -0
- package/dist/lib/otel/otel.js +235 -0
- package/dist/lib/otel/otlp-headers.js +101 -0
- package/dist/lib/otel/otlp-post.js +122 -0
- package/dist/lib/otel/otlp-serialize.js +142 -0
- package/dist/lib/otel/otlp-signal.js +2 -0
- package/dist/lib/otel/remote-spans.js +142 -0
- package/dist/lib/otel/service-identity.js +10 -0
- package/dist/lib/otel/telemetry-alerts.js +43 -0
- package/dist/lib/otel/token-metrics.js +122 -0
- package/dist/lib/otel/trace-context.js +81 -0
- package/dist/lib/quality/judge-meta-eval.js +70 -0
- package/dist/lib/quality/judge-prompts.js +104 -0
- package/dist/lib/quality/judge-providers.js +193 -0
- package/dist/lib/quality/judge-transport.js +93 -0
- package/dist/lib/quality/llm-judge.js +170 -0
- package/dist/lib/quality/quality-budget.js +99 -0
- package/dist/lib/quality/quality-degradation.js +156 -0
- package/dist/lib/quality/quality-eval-handoff.js +74 -0
- package/dist/lib/quality/quality-evaluator.js +178 -0
- package/dist/lib/quality/quality-sampler.js +43 -0
- package/dist/lib/quality/quality-signals.js +150 -0
- package/dist/lib/runtime/categorizers.js +101 -0
- package/dist/lib/runtime/hook-input.js +16 -0
- package/dist/lib/runtime/hook-output.js +50 -0
- package/dist/lib/runtime/output-analyzer.js +160 -0
- package/dist/lib/runtime/run-handlers.js +32 -0
- package/dist/lib/runtime/tool-input.js +111 -0
- package/dist/lib/runtime/tool-output.js +44 -0
- package/dist/lib/runtime/unknown-tool.js +32 -0
- package/dist/lib/session/edit-ledger.js +29 -0
- package/dist/lib/session/forked-skill.js +39 -0
- package/dist/lib/session/handoffs.js +77 -0
- package/dist/lib/session/session-state.js +169 -0
- package/dist/lib/session/skill-rules.js +196 -0
- package/dist/lib/session/task-tracker.js +83 -0
- package/dist/lib/shipper/shipper-credentials.js +38 -0
- package/dist/lib/shipper/shipper-cursor.js +89 -0
- package/dist/lib/shipper/shipper-status.js +174 -0
- package/dist/lib/shipper/span-shipper.js +272 -0
- package/dist/lib/shipper/telemetry-shipper.js +39 -0
- package/dist/lib/transcript/agent-transcript-metrics.js +34 -0
- package/dist/lib/transcript/context-breakdown.js +134 -0
- package/dist/lib/transcript/context-history.js +69 -0
- package/dist/lib/transcript/context-tracker.js +226 -0
- package/dist/lib/transcript/message-count.js +49 -0
- package/dist/lib/transcript/model-ids.js +36 -0
- package/dist/lib/transcript/model-pricing.js +153 -0
- package/dist/lib/transcript/token-metrics-checkpoint.js +152 -0
- package/dist/lib/transcript/tool-call-durations.js +64 -0
- package/dist/lib/transcript/transcript-entry.js +67 -0
- package/dist/lib/transcript/transcript-fold.js +130 -0
- package/dist/lib/transcript/transcript-layout.js +39 -0
- package/dist/lib/transcript/transcript-parser.js +117 -0
- package/dist/runner/agent-context-4XTCLMLZ.js +23 -0
- package/dist/runner/agent-context-4XTCLMLZ.js.map +7 -0
- package/dist/runner/agent-file-budget-Q33ESBBE.js +68 -0
- package/dist/runner/agent-file-budget-Q33ESBBE.js.map +7 -0
- package/dist/runner/agent-transcript-metrics-W5CZZFMI.js +39 -0
- package/dist/runner/agent-transcript-metrics-W5CZZFMI.js.map +7 -0
- package/dist/runner/chunk-2NTNAJZE.js +49 -0
- package/dist/runner/chunk-2NTNAJZE.js.map +7 -0
- package/dist/runner/chunk-4KWBQTTG.js +78 -0
- package/dist/runner/chunk-4KWBQTTG.js.map +7 -0
- package/dist/runner/chunk-52RY6LQT.js +699 -0
- package/dist/runner/chunk-52RY6LQT.js.map +7 -0
- package/dist/runner/chunk-7OM5CYES.js +8695 -0
- package/dist/runner/chunk-7OM5CYES.js.map +7 -0
- package/dist/runner/chunk-7PEOKGYR.js +1568 -0
- package/dist/runner/chunk-7PEOKGYR.js.map +7 -0
- package/dist/runner/chunk-AGSGKELQ.js +126 -0
- package/dist/runner/chunk-AGSGKELQ.js.map +7 -0
- package/dist/runner/chunk-AVM7PJFW.js +12 -0
- package/dist/runner/chunk-AVM7PJFW.js.map +7 -0
- package/dist/runner/chunk-C3WHUMU5.js +178 -0
- package/dist/runner/chunk-C3WHUMU5.js.map +7 -0
- package/dist/runner/chunk-DGB4NSSD.js +157 -0
- package/dist/runner/chunk-DGB4NSSD.js.map +7 -0
- package/dist/runner/chunk-DNSTWC26.js +151 -0
- package/dist/runner/chunk-DNSTWC26.js.map +7 -0
- package/dist/runner/chunk-FDJJ3TYU.js +449 -0
- package/dist/runner/chunk-FDJJ3TYU.js.map +7 -0
- package/dist/runner/chunk-FGKYDQHZ.js +137 -0
- package/dist/runner/chunk-FGKYDQHZ.js.map +7 -0
- package/dist/runner/chunk-GG2I4TGI.js +582 -0
- package/dist/runner/chunk-GG2I4TGI.js.map +7 -0
- package/dist/runner/chunk-GNNKUMRF.js +60 -0
- package/dist/runner/chunk-GNNKUMRF.js.map +7 -0
- package/dist/runner/chunk-I7TD2QVR.js +118 -0
- package/dist/runner/chunk-I7TD2QVR.js.map +7 -0
- package/dist/runner/chunk-IJ4SLUBV.js +78 -0
- package/dist/runner/chunk-IJ4SLUBV.js.map +7 -0
- package/dist/runner/chunk-IY7AP7NA.js +32 -0
- package/dist/runner/chunk-IY7AP7NA.js.map +7 -0
- package/dist/runner/chunk-J3F3Z3EQ.js +177 -0
- package/dist/runner/chunk-J3F3Z3EQ.js.map +7 -0
- package/dist/runner/chunk-JLEO5OHU.js +104 -0
- package/dist/runner/chunk-JLEO5OHU.js.map +7 -0
- package/dist/runner/chunk-JRNNLOPR.js +168 -0
- package/dist/runner/chunk-JRNNLOPR.js.map +7 -0
- package/dist/runner/chunk-KGSA5JYP.js +82 -0
- package/dist/runner/chunk-KGSA5JYP.js.map +7 -0
- package/dist/runner/chunk-LBCZAYFR.js +125 -0
- package/dist/runner/chunk-LBCZAYFR.js.map +7 -0
- package/dist/runner/chunk-LHWRXY2G.js +41 -0
- package/dist/runner/chunk-LHWRXY2G.js.map +7 -0
- package/dist/runner/chunk-LQ2LGUYJ.js +41 -0
- package/dist/runner/chunk-LQ2LGUYJ.js.map +7 -0
- package/dist/runner/chunk-LYY6RCIE.js +158 -0
- package/dist/runner/chunk-LYY6RCIE.js.map +7 -0
- package/dist/runner/chunk-M4R4QIQH.js +41 -0
- package/dist/runner/chunk-M4R4QIQH.js.map +7 -0
- package/dist/runner/chunk-MC75VXMX.js +207 -0
- package/dist/runner/chunk-MC75VXMX.js.map +7 -0
- package/dist/runner/chunk-NKZU4RRG.js +104 -0
- package/dist/runner/chunk-NKZU4RRG.js.map +7 -0
- package/dist/runner/chunk-PJHWHJ3K.js +56 -0
- package/dist/runner/chunk-PJHWHJ3K.js.map +7 -0
- package/dist/runner/chunk-RIGVYJ2O.js +114 -0
- package/dist/runner/chunk-RIGVYJ2O.js.map +7 -0
- package/dist/runner/chunk-RWRGC7ZK.js +93 -0
- package/dist/runner/chunk-RWRGC7ZK.js.map +7 -0
- package/dist/runner/chunk-SRMAJQMV.js +54 -0
- package/dist/runner/chunk-SRMAJQMV.js.map +7 -0
- package/dist/runner/chunk-TRMFD36J.js +47 -0
- package/dist/runner/chunk-TRMFD36J.js.map +7 -0
- package/dist/runner/chunk-U4IOZYQ3.js +21 -0
- package/dist/runner/chunk-U4IOZYQ3.js.map +7 -0
- package/dist/runner/chunk-UEXDE3WP.js +83 -0
- package/dist/runner/chunk-UEXDE3WP.js.map +7 -0
- package/dist/runner/chunk-UW3GQZSM.js +50 -0
- package/dist/runner/chunk-UW3GQZSM.js.map +7 -0
- package/dist/runner/chunk-V2GSP6VR.js +46 -0
- package/dist/runner/chunk-V2GSP6VR.js.map +7 -0
- package/dist/runner/chunk-VOV4Y5VU.js +81 -0
- package/dist/runner/chunk-VOV4Y5VU.js.map +7 -0
- package/dist/runner/chunk-VT5T6OEI.js +65 -0
- package/dist/runner/chunk-VT5T6OEI.js.map +7 -0
- package/dist/runner/chunk-VUYVFWIN.js +12 -0
- package/dist/runner/chunk-VUYVFWIN.js.map +7 -0
- package/dist/runner/chunk-VVGOPPEN.js +36 -0
- package/dist/runner/chunk-VVGOPPEN.js.map +7 -0
- package/dist/runner/chunk-VXFSLM6P.js +14 -0
- package/dist/runner/chunk-VXFSLM6P.js.map +7 -0
- package/dist/runner/chunk-W3EK7JUT.js +26125 -0
- package/dist/runner/chunk-W3EK7JUT.js.map +7 -0
- package/dist/runner/chunk-WJHNCOUF.js +52 -0
- package/dist/runner/chunk-WJHNCOUF.js.map +7 -0
- package/dist/runner/chunk-WU7ANGCW.js +269 -0
- package/dist/runner/chunk-WU7ANGCW.js.map +7 -0
- package/dist/runner/chunk-X7XLMSZX.js +44 -0
- package/dist/runner/chunk-X7XLMSZX.js.map +7 -0
- package/dist/runner/chunk-XSO3B4QN.js +124 -0
- package/dist/runner/chunk-XSO3B4QN.js.map +7 -0
- package/dist/runner/chunk-YGFN3LN2.js +174 -0
- package/dist/runner/chunk-YGFN3LN2.js.map +7 -0
- package/dist/runner/chunk-YHYDBLVB.js +33 -0
- package/dist/runner/chunk-YHYDBLVB.js.map +7 -0
- package/dist/runner/compact-36NP3PKT.js +60 -0
- package/dist/runner/compact-36NP3PKT.js.map +7 -0
- package/dist/runner/getMachineId-bsd-AGENNHN6.js +42 -0
- package/dist/runner/getMachineId-bsd-AGENNHN6.js.map +7 -0
- package/dist/runner/getMachineId-bsd-I5WZGCL4.js +33 -0
- package/dist/runner/getMachineId-bsd-I5WZGCL4.js.map +7 -0
- package/dist/runner/getMachineId-bsd-ZXK225P7.js +33 -0
- package/dist/runner/getMachineId-bsd-ZXK225P7.js.map +7 -0
- package/dist/runner/getMachineId-darwin-47GDLEXL.js +42 -0
- package/dist/runner/getMachineId-darwin-47GDLEXL.js.map +7 -0
- package/dist/runner/getMachineId-darwin-5CRLMDD6.js +33 -0
- package/dist/runner/getMachineId-darwin-5CRLMDD6.js.map +7 -0
- package/dist/runner/getMachineId-darwin-ADG4I32N.js +33 -0
- package/dist/runner/getMachineId-darwin-ADG4I32N.js.map +7 -0
- package/dist/runner/getMachineId-linux-5KVS3T2M.js +27 -0
- package/dist/runner/getMachineId-linux-5KVS3T2M.js.map +7 -0
- package/dist/runner/getMachineId-linux-GDFB5GSO.js +34 -0
- package/dist/runner/getMachineId-linux-GDFB5GSO.js.map +7 -0
- package/dist/runner/getMachineId-linux-NQMWCRO3.js +27 -0
- package/dist/runner/getMachineId-linux-NQMWCRO3.js.map +7 -0
- package/dist/runner/getMachineId-unsupported-5PFIGMVX.js +18 -0
- package/dist/runner/getMachineId-unsupported-5PFIGMVX.js.map +7 -0
- package/dist/runner/getMachineId-unsupported-DW27K3ZX.js +18 -0
- package/dist/runner/getMachineId-unsupported-DW27K3ZX.js.map +7 -0
- package/dist/runner/getMachineId-unsupported-XV3FHTHD.js +25 -0
- package/dist/runner/getMachineId-unsupported-XV3FHTHD.js.map +7 -0
- package/dist/runner/getMachineId-win-5JVMW3EI.js +44 -0
- package/dist/runner/getMachineId-win-5JVMW3EI.js.map +7 -0
- package/dist/runner/getMachineId-win-SNESQF7R.js +35 -0
- package/dist/runner/getMachineId-win-SNESQF7R.js.map +7 -0
- package/dist/runner/getMachineId-win-UJYHSBM2.js +35 -0
- package/dist/runner/getMachineId-win-UJYHSBM2.js.map +7 -0
- package/dist/runner/git-commit-BA53DOJQ.js +30 -0
- package/dist/runner/git-commit-BA53DOJQ.js.map +7 -0
- package/dist/runner/hook-runner-JHH6PGKE.js +220 -0
- package/dist/runner/hook-runner-JHH6PGKE.js.map +7 -0
- package/dist/runner/judge-transport-R4TF5LEH.js +91 -0
- package/dist/runner/judge-transport-R4TF5LEH.js.map +7 -0
- package/dist/runner/mcp-status-QEUH2KGX.js +89 -0
- package/dist/runner/mcp-status-QEUH2KGX.js.map +7 -0
- package/dist/runner/notification-FKMBCSXF.js +69 -0
- package/dist/runner/notification-FKMBCSXF.js.map +7 -0
- package/dist/runner/post-tool-3MRHTBKH.js +192 -0
- package/dist/runner/post-tool-3MRHTBKH.js.map +7 -0
- package/dist/runner/post-tool-agent-BB34MNHI.js +370 -0
- package/dist/runner/post-tool-agent-BB34MNHI.js.map +7 -0
- package/dist/runner/post-tool-changelog-sync-OP2TT2I7.js +147 -0
- package/dist/runner/post-tool-changelog-sync-OP2TT2I7.js.map +7 -0
- package/dist/runner/post-tool-code-structure-LE7J2SC2.js +130 -0
- package/dist/runner/post-tool-code-structure-LE7J2SC2.js.map +7 -0
- package/dist/runner/post-tool-edit-ledger-IJMEYHKF.js +30 -0
- package/dist/runner/post-tool-edit-ledger-IJMEYHKF.js.map +7 -0
- package/dist/runner/post-tool-failure-XTH2I2Z7.js +111 -0
- package/dist/runner/post-tool-failure-XTH2I2Z7.js.map +7 -0
- package/dist/runner/post-tool-git-E46HZGZO.js +94 -0
- package/dist/runner/post-tool-git-E46HZGZO.js.map +7 -0
- package/dist/runner/post-tool-mcp-AMCDY5GH.js +144 -0
- package/dist/runner/post-tool-mcp-AMCDY5GH.js.map +7 -0
- package/dist/runner/post-tool-task-state-TLDOI33H.js +100 -0
- package/dist/runner/post-tool-task-state-TLDOI33H.js.map +7 -0
- package/dist/runner/pre-tool-SQE2FZQO.js +245 -0
- package/dist/runner/pre-tool-SQE2FZQO.js.map +7 -0
- package/dist/runner/pre-tool-agent-OZUPVFUI.js +218 -0
- package/dist/runner/pre-tool-agent-OZUPVFUI.js.map +7 -0
- package/dist/runner/quality-evaluator-XYNDKDRG.js +901 -0
- package/dist/runner/quality-evaluator-XYNDKDRG.js.map +7 -0
- package/dist/runner/session-end-3MJTDLLA.js +57 -0
- package/dist/runner/session-end-3MJTDLLA.js.map +7 -0
- package/dist/runner/session-start-5ZMCLKBS.js +352 -0
- package/dist/runner/session-start-5ZMCLKBS.js.map +7 -0
- package/dist/runner/shipper-status-MADX6SPG.js +37 -0
- package/dist/runner/shipper-status-MADX6SPG.js.map +7 -0
- package/dist/runner/span-shipper-4HQDHC47.js +3408 -0
- package/dist/runner/span-shipper-4HQDHC47.js.map +7 -0
- package/dist/runner/stop-RTKSIYJV.js +596 -0
- package/dist/runner/stop-RTKSIYJV.js.map +7 -0
- package/dist/runner/subagent-CBCG4OLZ.js +116 -0
- package/dist/runner/subagent-CBCG4OLZ.js.map +7 -0
- package/dist/runner/token-metrics-AD2RAFGM.js +31 -0
- package/dist/runner/token-metrics-AD2RAFGM.js.map +7 -0
- package/dist/runner/user-prompt-T5NZ2UJD.js +376 -0
- package/dist/runner/user-prompt-T5NZ2UJD.js.map +7 -0
- package/package.json +68 -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/README.md
CHANGED
|
@@ -1,3 +1,202 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Claude Code Hooks
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
}
|