@ascenda-one/claude-code-hooks 0.1.28 → 0.1.34
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/README.md +80 -46
- package/dist/cli.js +3170 -618
- package/dist/cli.js.map +1 -1
- package/dist/hookHealth.js +21 -0
- package/dist/hookHealth.js.map +1 -0
- package/dist/launcher.js +14 -0
- package/dist/launcher.js.map +1 -0
- package/dist/liveDoctor.js +27 -0
- package/dist/liveDoctor.js.map +1 -0
- package/dist/liveEvent.js +95 -0
- package/dist/liveEvent.js.map +1 -0
- package/dist/mapClaudeEvent.js +68 -4
- package/dist/mapClaudeEvent.js.map +1 -1
- package/dist/paths.js +30 -1
- package/dist/paths.js.map +1 -1
- package/dist/setup.js +311 -95
- package/dist/setup.js.map +1 -1
- package/dist/types.js +2 -1
- package/dist/types.js.map +1 -1
- package/dist/usageLimitReset.js +207 -0
- package/dist/usageLimitReset.js.map +1 -0
- package/examples/settings.local.json +13 -10
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,18 +6,19 @@ Part of [ai-engineer-tools](../). For what these measurements do and do not
|
|
|
6
6
|
establish, see [What this measures](../#what-this-measures-and-what-that-does-not-yet-prove).
|
|
7
7
|
Event mapping: [docs/CLAUDE_MAPPING.md](./docs/CLAUDE_MAPPING.md).
|
|
8
8
|
|
|
9
|
-
##
|
|
9
|
+
## What it sends
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Metadata only. It doesn't send prompts, responses, code, file names,
|
|
12
|
+
repository names, branch names or terminal output. [Privacy defaults](#privacy-defaults)
|
|
13
|
+
has the detail, and [Build from source](#build-from-source) shows how to read
|
|
14
|
+
what runs on your machine.
|
|
12
15
|
|
|
13
|
-
|
|
|
16
|
+
| Signal | What the hook records |
|
|
14
17
|
| --- | --- |
|
|
15
|
-
|
|
|
16
|
-
|
|
|
17
|
-
|
|
|
18
|
-
| Verification
|
|
19
|
-
|
|
20
|
-
Signals feed backend aggregation into creation / verification / supervision composition and the prototype workload score. Subjective strain and meeting load come from the app; baselines from backend Phase 3.
|
|
18
|
+
| Agent interaction | That a prompt, correction loop or compaction happened, and for each tool call the tool's name (`Bash`, `Edit`) |
|
|
19
|
+
| Long agent runs | That a loop ran long (`agent_loop_long`) |
|
|
20
|
+
| Friction | Tool failures and context pressure |
|
|
21
|
+
| Verification | A test, lint or build command ran (`editor_verification_activity` / `compile_error`) |
|
|
21
22
|
|
|
22
23
|
## Architecture
|
|
23
24
|
|
|
@@ -25,7 +26,7 @@ Signals feed backend aggregation into creation / verification / supervision comp
|
|
|
25
26
|
Claude Code hook adapter
|
|
26
27
|
-> toolInstallationId + eventWriteToken
|
|
27
28
|
-> Ascenda backend (POST /v1/tool-events)
|
|
28
|
-
-> paired
|
|
29
|
+
-> paired pseudonymous Ascenda user
|
|
29
30
|
-> workload aggregation + baseline comparison
|
|
30
31
|
-> app notification / dashboard
|
|
31
32
|
```
|
|
@@ -58,8 +59,8 @@ npx @ascenda-one/claude-code-hooks setup
|
|
|
58
59
|
|
|
59
60
|
This pairs (printing a 6-digit code to confirm in the Ascenda app), installs a
|
|
60
61
|
self-contained hook bundle to `~/.ascenda/bin`, writes
|
|
61
|
-
`~/.ascenda/credentials.json`, and registers the hooks in
|
|
62
|
-
|
|
62
|
+
`~/.ascenda/credentials.json`, and registers the hooks in `~/.claude/settings.json`,
|
|
63
|
+
so they load in every project. Restart Claude Code and events flow — no shell
|
|
63
64
|
exports, no settings file to hand-edit.
|
|
64
65
|
|
|
65
66
|
```bash
|
|
@@ -73,7 +74,7 @@ npx @ascenda-one/claude-code-hooks uninstall # removes hooks and the binary
|
|
|
73
74
|
| `--local [port]` | shorthand for a local [dev server](../ascenda-dev-server/) (default `4477`) |
|
|
74
75
|
| `--tool-installation-id <id>` / `--token <t>` | reuse an existing pairing instead of creating one |
|
|
75
76
|
| `--no-pair` | install the local half only: hooks work, nothing is sent |
|
|
76
|
-
| `--scope project
|
|
77
|
+
| `--scope user\|project` | register in `~/.claude/settings.json` (default, every project) or in this project's `.claude/settings.local.json` |
|
|
77
78
|
| `--project-dir <path>` | project root for `--scope project` (default cwd) |
|
|
78
79
|
| `--dry-run` | print what would change, write nothing |
|
|
79
80
|
|
|
@@ -86,43 +87,65 @@ DevAuth. Stop it with `./scripts/setup-local.sh --stop`. See
|
|
|
86
87
|
|
|
87
88
|
| Path | |
|
|
88
89
|
| --- | --- |
|
|
89
|
-
| `~/.ascenda/bin/ascenda-claude-hook` | the
|
|
90
|
+
| `~/.ascenda/bin/ascenda-claude-hook` | the launcher every hook command names: a small `sh` script that finds Node and runs the bundle |
|
|
91
|
+
| `~/.ascenda/bin/ascenda-claude-hook.mjs` | the self-contained bundle — no `npm -g`, no sudo, no PATH edit |
|
|
92
|
+
| `~/.ascenda/bin/ascenda-claude-hook.node` | the Node the launcher last found, starting with the one that ran setup |
|
|
90
93
|
| `~/.ascenda/credentials.json` | `apiBaseUrl` + `toolInstallationId`, `0600` (plus `localOnly` on an install with no pairing) |
|
|
91
94
|
| `~/.ascenda/tokens/<id>` | the event write token, `0600`, rotated in place on renew |
|
|
92
|
-
|
|
|
95
|
+
| `~/.claude/settings.json` | one hook entry per lifecycle event, `timeout: 5` (`.claude/settings.local.json` under `--scope project`) |
|
|
93
96
|
|
|
94
97
|
Registration is idempotent and marker-keyed: re-running replaces our entries
|
|
95
98
|
rather than appending, hooks belonging to anyone else are left alone, and the
|
|
96
99
|
file is backed up to `.ascenda-backup` before the first write. Settings that
|
|
97
100
|
are not valid JSON abort the run rather than being overwritten.
|
|
98
101
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
102
|
+
#### Upgrading
|
|
103
|
+
|
|
104
|
+
Re-run `setup` with the scope you installed with. It keeps your pairing, adds
|
|
105
|
+
the hooks this version registers, and prints what it added:
|
|
106
|
+
|
|
107
|
+
```text
|
|
108
|
+
hooks ~/.claude/settings.json (13 events)
|
|
109
|
+
upgraded: added SubagentStart, SubagentStop; hook set 2 → 3
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
`status` prints the installed hook set and, when it's older, the command to
|
|
113
|
+
run. The Flow app on your Mac shows one line in **Connections → Ingest
|
|
114
|
+
telemetry** when an agent's signals come from an older set. Restart Claude
|
|
115
|
+
Code afterwards: a session keeps the hooks it started with.
|
|
116
|
+
|
|
117
|
+
If you use the plugin, run `claude plugin update ascenda@ascenda-one` instead.
|
|
118
|
+
Its `hooks.json` registers the same set. Having both the plugin and a `setup` install runs every hook
|
|
119
|
+
twice. `setup` moves its own entries out of the other scope's file (and out of
|
|
120
|
+
`~/.claude/settings.local.json`, where a project install run from the home
|
|
121
|
+
folder used to put them, loading only when Claude Code started in `~`), but it
|
|
122
|
+
can't remove the plugin's.
|
|
123
|
+
|
|
124
|
+
Hooks then need **no environment at all**. The command names the launcher, and
|
|
125
|
+
the launcher finds Node: the one that ran setup while it's still there, and
|
|
126
|
+
otherwise the first Node 20 or newer on `PATH`, in Homebrew, volta, nvm's
|
|
127
|
+
default alias, fnm, asdf or mise, which it records for next time. So a hook
|
|
128
|
+
keeps working when Claude Code is opened from the Dock or an IDE, and after a
|
|
129
|
+
version manager removes the Node that ran setup. If there is no Node at all,
|
|
130
|
+
`SessionStart` says so once and the other hooks stay quiet. Configuration comes
|
|
131
|
+
from the credentials file; the variables below still override it when set.
|
|
105
132
|
|
|
106
133
|
`status` also flags hook entries pointing at a binary that no longer exists —
|
|
107
|
-
those fail silently on every event otherwise
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
134
|
+
those fail silently on every event otherwise — and names the Node the hooks
|
|
135
|
+
will run and the last hook Claude Code ran. It checks one scope, defaulting to
|
|
136
|
+
`user` like `setup`; if it finds nothing there it looks in the other one and
|
|
137
|
+
says where the hooks actually are.
|
|
111
138
|
|
|
112
139
|
#### Installing without a pairing
|
|
113
140
|
|
|
114
141
|
`--no-pair` installs the hooks and stops before pairing. A `setup` that tried
|
|
115
142
|
to pair and couldn't finish — the backend unreachable, nobody at the keyboard
|
|
116
143
|
to confirm the code, the session expired — lands in the same place instead of
|
|
117
|
-
failing. The install completes either way, and the summary
|
|
118
|
-
|
|
144
|
+
failing. The install completes either way, and the summary says which it was.
|
|
145
|
+
Asked for, it reads as finished; a pairing that didn't finish warns, and offers
|
|
146
|
+
the retry:
|
|
119
147
|
|
|
120
|
-
|
|
121
|
-
Installed, not paired.
|
|
122
|
-
active the session prompts, and the live signal to a socket on this machine
|
|
123
|
-
inactive delivery to https://api.ascenda.one. Nothing is sent, and nothing is queued for later.
|
|
124
|
-
pair later npx @ascenda-one/claude-code-hooks pair
|
|
125
|
-
```
|
|
148
|
+

|
|
126
149
|
|
|
127
150
|
Two things work with no pairing at all, which is why this mode exists. The
|
|
128
151
|
session prompts are composed locally in the hook process. The live signal goes
|
|
@@ -148,7 +171,7 @@ pairing claude_code:… (not paired, installed 2026-09-23T05:13:40.907Z)
|
|
|
148
171
|
token — none until this install is paired
|
|
149
172
|
delivery inactive — nothing is sent, and nothing is queued for later
|
|
150
173
|
local features active — the session prompts and the live socket signal need no pairing
|
|
151
|
-
hooks
|
|
174
|
+
hooks 11/11 registered in ~/.claude/settings.json
|
|
152
175
|
```
|
|
153
176
|
|
|
154
177
|
`uninstall` removes an unpaired install the same way, and says there is no
|
|
@@ -239,8 +262,9 @@ The environment's network access must also allow the Ascenda API host.
|
|
|
239
262
|
**Tokens never rotate in a cloud session.** Renewal revokes the previous
|
|
240
263
|
token, and the replacement would die with the container, taking the
|
|
241
264
|
environment's copy down for every later session. So the hooks record a
|
|
242
|
-
rejected token as a failed send and stop there. Tokens last 30 days
|
|
243
|
-
|
|
265
|
+
rejected token as a failed send and stop there. Tokens last 30 days. On a
|
|
266
|
+
laptop the hooks renew theirs well before then, but a cloud session can't, so
|
|
267
|
+
pair again before the 30 days are up and replace the token in the environment.
|
|
244
268
|
|
|
245
269
|
### Register hooks manually
|
|
246
270
|
|
|
@@ -260,8 +284,11 @@ for machine-wide coverage:
|
|
|
260
284
|
"PreCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PreCompact", "timeout": 5 }] }],
|
|
261
285
|
"PostCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostCompact", "timeout": 5 }] }],
|
|
262
286
|
"Stop": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Stop", "timeout": 5 }] }],
|
|
287
|
+
"StopFailure": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks StopFailure", "timeout": 5 }] }],
|
|
263
288
|
"Notification": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Notification", "timeout": 5 }] }],
|
|
264
|
-
"SessionEnd": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SessionEnd", "timeout": 5 }] }]
|
|
289
|
+
"SessionEnd": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SessionEnd", "timeout": 5 }] }],
|
|
290
|
+
"SubagentStart": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SubagentStart", "timeout": 5 }] }],
|
|
291
|
+
"SubagentStop": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SubagentStop", "timeout": 5 }] }]
|
|
265
292
|
}
|
|
266
293
|
}
|
|
267
294
|
```
|
|
@@ -275,7 +302,16 @@ SessionEnd hooks share 1.5s between them.
|
|
|
275
302
|
npx -y @ascenda-one/claude-code-hooks doctor
|
|
276
303
|
```
|
|
277
304
|
|
|
278
|
-
`doctor`
|
|
305
|
+
`doctor` starts with the local half, which needs no pairing: the Node the
|
|
306
|
+
hooks will run (found with a bare `PATH`, the way a Dock-launched Claude Code
|
|
307
|
+
starts them), which settings files register them and whether those load in
|
|
308
|
+
every project, the last hook Claude Code ran, who is listening on the live
|
|
309
|
+
socket (the desktop app, or the Waterline screen saver and whether it is the
|
|
310
|
+
one on screen), and a ping that the saver answers in its heartbeat. The System
|
|
311
|
+
Settings preview never listens, so testing with it shows resting water;
|
|
312
|
+
`doctor` says so.
|
|
313
|
+
|
|
314
|
+
Then it prints the installation id and where it came from (environment,
|
|
279
315
|
credentials file, or the token store on disk), the token's presence and age,
|
|
280
316
|
the last recorded send outcome, any sends skipped for want of an installation
|
|
281
317
|
id, and the result of a live round trip against the real ingest endpoint. It is the first thing to run when the Ascenda app shows a
|
|
@@ -414,8 +450,11 @@ PostToolUseFailure
|
|
|
414
450
|
PreCompact
|
|
415
451
|
PostCompact
|
|
416
452
|
Stop
|
|
453
|
+
StopFailure
|
|
417
454
|
Notification
|
|
418
455
|
SessionEnd
|
|
456
|
+
SubagentStart
|
|
457
|
+
SubagentStop
|
|
419
458
|
```
|
|
420
459
|
|
|
421
460
|
## Ascenda event mappings
|
|
@@ -433,8 +472,11 @@ PostToolUseFailure -> compile_error / ai_tool_call_failed
|
|
|
433
472
|
PreCompact -> context_compression_manual / context_compression_auto
|
|
434
473
|
PostCompact -> context_pressure_high
|
|
435
474
|
Stop -> ai_turn_completed (every turn), agent_loop_long (long only)
|
|
475
|
+
StopFailure -> nothing sent (live signal only)
|
|
436
476
|
Notification -> supervision_interruption (interruptionKind only, never the message)
|
|
437
477
|
SessionEnd -> recovery_offline_period (activity session_ended, sessionEndReason)
|
|
478
|
+
SubagentStart -> subagent_started (subagentId, subagentClass)
|
|
479
|
+
SubagentStop -> subagent_stopped (subagentId, subagentClass)
|
|
438
480
|
```
|
|
439
481
|
|
|
440
482
|
## Privacy defaults
|
|
@@ -461,14 +503,6 @@ readable salt the key is omitted entirely rather than sent blank.
|
|
|
461
503
|
|
|
462
504
|
Correction detection uses local pattern matching on prompt text in the hook process only — classified metadata (`reason: repeated_reprompting`) is sent; raw prompt text is not.
|
|
463
505
|
|
|
464
|
-
## Roadmap
|
|
465
|
-
|
|
466
|
-
| Phase | Scope |
|
|
467
|
-
| --- | --- |
|
|
468
|
-
| Phase 1 | Hook mappings, metadata-only ingest, shared pairing tokens |
|
|
469
|
-
| Phase 2 | Standalone CLI pairing (`ascenda-claude-pair`) |
|
|
470
|
-
| Phase 3 | Session rollup metadata aligned with backend baselines |
|
|
471
|
-
|
|
472
506
|
## Compliance
|
|
473
507
|
|
|
474
508
|
`consentScope: ide_telemetry` and `provenance: ai_work_telemetry` on every
|