@ascenda-one/claude-code-hooks 0.1.27 → 0.1.33

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
  ```
@@ -72,6 +73,7 @@ npx @ascenda-one/claude-code-hooks uninstall # removes hooks and the binary
72
73
  | `--api-base-url <url>` | ingest host (default `https://api.ascenda.one`) |
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 |
76
+ | `--no-pair` | install the local half only: hooks work, nothing is sent |
75
77
  | `--scope project\|user` | register in this project (default) or in `~/.claude/settings.json` |
76
78
  | `--project-dir <path>` | project root for `--scope project` (default cwd) |
77
79
  | `--dry-run` | print what would change, write nothing |
@@ -86,7 +88,7 @@ DevAuth. Stop it with `./scripts/setup-local.sh --stop`. See
86
88
  | Path | |
87
89
  | --- | --- |
88
90
  | `~/.ascenda/bin/ascenda-claude-hook` | the self-contained bundle — no `npm -g`, no sudo, no PATH edit |
89
- | `~/.ascenda/credentials.json` | `apiBaseUrl` + `toolInstallationId`, `0600` |
91
+ | `~/.ascenda/credentials.json` | `apiBaseUrl` + `toolInstallationId`, `0600` (plus `localOnly` on an install with no pairing) |
90
92
  | `~/.ascenda/tokens/<id>` | the event write token, `0600`, rotated in place on renew |
91
93
  | `.claude/settings.local.json` | one hook entry per lifecycle event, `timeout: 5` |
92
94
 
@@ -95,6 +97,25 @@ rather than appending, hooks belonging to anyone else are left alone, and the
95
97
  file is backed up to `.ascenda-backup` before the first write. Settings that
96
98
  are not valid JSON abort the run rather than being overwritten.
97
99
 
100
+ #### Upgrading
101
+
102
+ Re-run `setup` with the scope you installed with. It keeps your pairing, adds
103
+ the hooks this version registers, and prints what it added:
104
+
105
+ ```text
106
+ hooks ~/.claude/settings.json (13 events)
107
+ upgraded: added SubagentStart, SubagentStop; hook set 2 → 3
108
+ ```
109
+
110
+ `status` prints the installed hook set and, when it's older, the command to
111
+ run. The Flow app on your Mac shows one line in **Connections → Ingest
112
+ telemetry** when an agent's signals come from an older set. Restart Claude
113
+ Code afterwards: a session keeps the hooks it started with.
114
+
115
+ If you use the plugin, run `claude plugin update ascenda@ascenda-one` instead.
116
+ Its `hooks.json` registers the same set. Having both the plugin and a `setup` install runs every hook
117
+ twice, and `setup` warns when the other scope already registers them.
118
+
98
119
  Hooks then need **no environment at all**: the command pins the absolute path
99
120
  of the Node that ran setup, and configuration comes from the credentials file.
100
121
  Claude Code spawns hooks with whatever environment it was launched from, so
@@ -103,7 +124,56 @@ opened from a launcher rather than a terminal. The variables below still
103
124
  override the file when set.
104
125
 
105
126
  `status` also flags hook entries pointing at a binary that no longer exists —
106
- those fail silently on every event otherwise.
127
+ those fail silently on every event otherwise. It checks one scope, defaulting
128
+ to `project` like `setup`; if it finds nothing there it looks in the other one
129
+ and says where the hooks actually are. User settings apply in every project, so
130
+ hooks found there answer a project-scope check.
131
+
132
+ #### Installing without a pairing
133
+
134
+ `--no-pair` installs the hooks and stops before pairing. A `setup` that tried
135
+ to pair and couldn't finish — the backend unreachable, nobody at the keyboard
136
+ to confirm the code, the session expired — lands in the same place instead of
137
+ failing. The install completes either way, and the summary names which half is
138
+ running:
139
+
140
+ ```text
141
+ Installed, not paired.
142
+ active the session prompts, and the live signal to a socket on this machine
143
+ inactive delivery to https://api.ascenda.one. Nothing is sent, and nothing is queued for later.
144
+ pair later npx @ascenda-one/claude-code-hooks pair
145
+ ```
146
+
147
+ Two things work with no pairing at all, which is why this mode exists. The
148
+ session prompts are composed locally in the hook process. The live signal goes
149
+ to a socket on your own machine, so a listener there sees an agent working the
150
+ moment it starts. Neither owes anything to a backend, and gating the install on
151
+ one kept them from the people still setting Ascenda up.
152
+
153
+ What that install holds: the hook binary, the registered events, and a
154
+ credentials file with an installation id, `localOnly: true` and `installedAt`.
155
+ No `pairedAt` and no token — nothing here fabricates a credential it doesn't
156
+ have. The id is the part that matters later. `pair` claims that same id, so the
157
+ hooks already registered in your settings file end up paired; the flag is
158
+ dropped and `pairedAt` takes its place.
159
+
160
+ Delivery is a deliberate no-op until then. Nothing is sent, nothing is queued,
161
+ and the send journal stays empty rather than recording an outage on every hook
162
+ event. An absent token on an install that *was* paired is a different matter:
163
+ that's a revoked or deleted credential, and it goes on being reported. `status`
164
+ and `doctor` both distinguish the two:
165
+
166
+ ```text
167
+ pairing claude_code:… (not paired, installed 2026-09-23T05:13:40.907Z)
168
+ token — none until this install is paired
169
+ delivery inactive — nothing is sent, and nothing is queued for later
170
+ local features active — the session prompts and the live socket signal need no pairing
171
+ hooks 11/11 registered in ~/.claude/settings.json
172
+ ```
173
+
174
+ `uninstall` removes an unpaired install the same way, and says there is no
175
+ token to revoke. It leaves any other agent's pairing in the credentials file
176
+ where it is.
107
177
 
108
178
  ### Pairing by hand (if you skip `setup`)
109
179
 
@@ -121,6 +191,10 @@ never copied around — every CLI tool reads it from the file `pair` wrote. (The
121
191
  editor extension's pairing cannot be reused here: its token lives in the
122
192
  editor's private secret storage.)
123
193
 
194
+ Run on a machine `setup` has already touched, `pair` attaches to the
195
+ installation that file names instead of minting a second one, and pairs against
196
+ the host recorded there. That's what finishes a `--no-pair` install.
197
+
124
198
  `--tool-type <type>` pairs something else CLI-shaped that has no `setup` of its
125
199
  own. An explicit type always mints its own id: naming a different tool is
126
200
  pairing a second one, not re-pairing this one, and reusing the id there would
@@ -163,6 +237,32 @@ Optional environment:
163
237
  On first run the CLI seeds `~/.ascenda/tokens/<toolInstallationId>` so
164
238
  **tool-scoped renew** can persist rotated tokens without you editing anything.
165
239
 
240
+ ### Cloud sessions
241
+
242
+ A hosted Claude Code session (Claude Code on the web, or one it spawns) runs in
243
+ a fresh container every time. Its transcript never reaches your machine, so a
244
+ history import can't see it and these hooks are its only record. Every event
245
+ carries `metadata.runtime`: `cloud` when Claude Code sets `CLAUDE_CODE_REMOTE`,
246
+ `local` otherwise.
247
+
248
+ Nothing under `~/.ascenda` survives a session there, so everything the hooks
249
+ need comes from the environment's settings:
250
+
251
+ | Variable | Why |
252
+ | --- | --- |
253
+ | `ASCENDA_TOOL_INSTALLATION_ID` | The installation to send as. Pair one just for cloud sessions (run `pair` inside one); don't reuse your laptop's pairing, which re-pairing would rotate. |
254
+ | `ASCENDA_EVENT_WRITE_TOKEN` | Its write token. |
255
+ | the salt, `~/.ascenda/salt` | Without it every session mints a new one and one repository turns into a new project hash every time. Have whatever launches the hooks write a fixed value there first. Your laptop's value makes cloud and local hashes match. |
256
+
257
+ The environment's network access must also allow the Ascenda API host.
258
+
259
+ **Tokens never rotate in a cloud session.** Renewal revokes the previous
260
+ token, and the replacement would die with the container, taking the
261
+ environment's copy down for every later session. So the hooks record a
262
+ rejected token as a failed send and stop there. Tokens last 30 days. On a
263
+ laptop the hooks renew theirs well before then, but a cloud session can't, so
264
+ pair again before the 30 days are up and replace the token in the environment.
265
+
166
266
  ### Register hooks manually
167
267
 
168
268
  The plugin does this for you — this section is only for the standalone route.
@@ -173,19 +273,26 @@ for machine-wide coverage:
173
273
  ```json
174
274
  {
175
275
  "hooks": {
176
- "SessionStart": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SessionStart" }] }],
177
- "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks UserPromptSubmit" }] }],
178
- "PreToolUse": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PreToolUse" }] }],
179
- "PostToolUse": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostToolUse" }] }],
180
- "PostToolUseFailure": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostToolUseFailure" }] }],
181
- "PreCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PreCompact" }] }],
182
- "PostCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostCompact" }] }],
183
- "Stop": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Stop" }] }],
184
- "Notification": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Notification" }] }]
276
+ "SessionStart": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SessionStart", "timeout": 5 }] }],
277
+ "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks UserPromptSubmit", "timeout": 5 }] }],
278
+ "PreToolUse": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PreToolUse", "timeout": 5 }] }],
279
+ "PostToolUse": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostToolUse", "timeout": 5 }] }],
280
+ "PostToolUseFailure": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostToolUseFailure", "timeout": 5 }] }],
281
+ "PreCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PreCompact", "timeout": 5 }] }],
282
+ "PostCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostCompact", "timeout": 5 }] }],
283
+ "Stop": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Stop", "timeout": 5 }] }],
284
+ "StopFailure": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks StopFailure", "timeout": 5 }] }],
285
+ "Notification": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Notification", "timeout": 5 }] }],
286
+ "SessionEnd": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SessionEnd", "timeout": 5 }] }],
287
+ "SubagentStart": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SubagentStart", "timeout": 5 }] }],
288
+ "SubagentStop": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SubagentStop", "timeout": 5 }] }]
185
289
  }
186
290
  }
187
291
  ```
188
292
 
293
+ Keep the timeouts. Without one Claude Code gives a hook up to 600s, and all
294
+ SessionEnd hooks share 1.5s between them.
295
+
189
296
  ### Verify
190
297
 
191
298
  ```bash
@@ -323,6 +430,7 @@ on Claude Code's PATH, use an absolute path such as
323
430
  ## Supported Claude hook events
324
431
 
325
432
  ```text
433
+ SessionStart
326
434
  UserPromptSubmit
327
435
  PreToolUse
328
436
  PostToolUse
@@ -330,7 +438,11 @@ PostToolUseFailure
330
438
  PreCompact
331
439
  PostCompact
332
440
  Stop
441
+ StopFailure
333
442
  Notification
443
+ SessionEnd
444
+ SubagentStart
445
+ SubagentStop
334
446
  ```
335
447
 
336
448
  ## Ascenda event mappings
@@ -338,6 +450,7 @@ Notification
338
450
  Full mapping: [docs/CLAUDE_MAPPING.md](./docs/CLAUDE_MAPPING.md). Catalog-only event types (no aliases).
339
451
 
340
452
  ```text
453
+ SessionStart -> create_focus_session (startup and resume; clear and compact are skipped)
341
454
  UserPromptSubmit -> ai_prompt_submitted / ai_correction_prompt
342
455
  PreToolUse -> ai_tool_call_started
343
456
  PostToolUse Edit -> ai_file_edit
@@ -347,7 +460,11 @@ PostToolUseFailure -> compile_error / ai_tool_call_failed
347
460
  PreCompact -> context_compression_manual / context_compression_auto
348
461
  PostCompact -> context_pressure_high
349
462
  Stop -> ai_turn_completed (every turn), agent_loop_long (long only)
463
+ StopFailure -> nothing sent (live signal only)
350
464
  Notification -> supervision_interruption (interruptionKind only, never the message)
465
+ SessionEnd -> recovery_offline_period (activity session_ended, sessionEndReason)
466
+ SubagentStart -> subagent_started (subagentId, subagentClass)
467
+ SubagentStop -> subagent_stopped (subagentId, subagentClass)
351
468
  ```
352
469
 
353
470
  ## Privacy defaults
@@ -374,14 +491,6 @@ readable salt the key is omitted entirely rather than sent blank.
374
491
 
375
492
  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.
376
493
 
377
- ## Roadmap
378
-
379
- | Phase | Scope |
380
- | --- | --- |
381
- | Phase 1 | Hook mappings, metadata-only ingest, shared pairing tokens |
382
- | Phase 2 | Standalone CLI pairing (`ascenda-claude-pair`) |
383
- | Phase 3 | Session rollup metadata aligned with backend baselines |
384
-
385
494
  ## Compliance
386
495
 
387
496
  `consentScope: ide_telemetry` and `provenance: ai_work_telemetry` on every
@@ -11,6 +11,7 @@ export class AscendaClient {
11
11
  tokenFilePath: config.tokenFilePath,
12
12
  stateFilePath: config.stateFilePath,
13
13
  outboxFilePath: config.outboxFilePath,
14
+ renewToken: config.renewToken,
14
15
  sessionId: config.sessionId,
15
16
  workspaceHash: config.workspaceHash,
16
17
  projectHash: config.projectHash
@@ -23,6 +24,10 @@ export class AscendaClient {
23
24
  async send(mapped) {
24
25
  return this.sender.send(mapped);
25
26
  }
27
+ /** Outbox only, no network. See {@link AscendaEventSender.queue}. */
28
+ queue(mapped) {
29
+ return this.sender.queue(mapped);
30
+ }
26
31
  async renewEventToken() {
27
32
  return this.sender.renewEventToken();
28
33
  }
@@ -1 +1 @@
1
- {"version":3,"file":"ascendaClient.js","sourceRoot":"","sources":["../src/ascendaClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAI3D,OAAO,EAAE,eAAe,IAAI,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE9E,MAAM,OAAO,aAAa;IACP,MAAM,CAAqB;IAE5C,YAAY,MAAyB;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,kBAAkB,CAAC;YACnC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;YAC7C,MAAM,EAAE,aAAa;YACrB,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,WAAW,EAAE,MAAM,CAAC,WAAW;SAChC,CAAC,CAAC;IACL,CAAC;IAED,iEAAiE;IACjE,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAA0B;QACnC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,eAAe;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;IACvC,CAAC;CACF"}
1
+ {"version":3,"file":"ascendaClient.js","sourceRoot":"","sources":["../src/ascendaClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAI3D,OAAO,EAAE,eAAe,IAAI,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE9E,MAAM,OAAO,aAAa;IACP,MAAM,CAAqB;IAE5C,YAAY,MAAyB;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,kBAAkB,CAAC;YACnC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;YAC7C,MAAM,EAAE,aAAa;YACrB,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,WAAW,EAAE,MAAM,CAAC,WAAW;SAChC,CAAC,CAAC;IACL,CAAC;IAED,iEAAiE;IACjE,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAA0B;QACnC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,qEAAqE;IACrE,KAAK,CAAC,MAA0B;QAC9B,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,eAAe;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;IACvC,CAAC;CACF"}