@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 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
- ## Role in workload detection (Phase 1)
9
+ ## What it sends
10
10
 
11
- This package is the **primary AI interaction load** source in the tooling repo. For AI engineers, digital telemetry from agent workflows is potentially more valuable than wearables in Phase 1.
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
- | Workload input | How this adapter contributes |
16
+ | Signal | What the hook records |
14
17
  | --- | --- |
15
- | AIInteractionLoad | Prompts, tool calls, correction loops, compaction |
16
- | FocusDuration | Long agent loops (`agent_loop_long`) |
17
- | Workflow friction | Tool failures, context pressure |
18
- | Verification load | Test/lint/build bash → `editor_verification_activity` / `compile_error` |
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 anonymous Ascenda user
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 this project's
62
- `.claude/settings.local.json`. Restart Claude Code and events flow — no shell
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\|user` | register in this project (default) or in `~/.claude/settings.json` |
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 self-contained bundle — no `npm -g`, no sudo, no PATH edit |
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
- | `.claude/settings.local.json` | one hook entry per lifecycle event, `timeout: 5` |
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
- Hooks then need **no environment at all**: the command pins the absolute path
100
- of the Node that ran setup, and configuration comes from the credentials file.
101
- Claude Code spawns hooks with whatever environment it was launched from, so
102
- anything depending on shell exports stops working the moment the editor is
103
- opened from a launcher rather than a terminal. The variables below still
104
- override the file when set.
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. It checks one scope, defaulting
108
- to `project` like `setup`; if it finds nothing there it looks in the other one
109
- and says where the hooks actually are. User settings apply in every project, so
110
- hooks found there answer a project-scope check.
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 names which half is
118
- running:
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
- ```text
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
+ ![setup --no-pair finishing with "Ready."](https://raw.githubusercontent.com/ascendaone-com/ai-engineer-tools/main/docs/images/cli-setup-no-pair.png)
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 10/10 registered in ~/.claude/settings.json
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; when one runs out, pair again
243
- and replace the token in the environment.
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` prints the installation id and where it came from (environment,
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