@ascenda-one/claude-code-hooks 0.1.28 → 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
  ```
@@ -96,6 +97,25 @@ rather than appending, hooks belonging to anyone else are left alone, and the
96
97
  file is backed up to `.ascenda-backup` before the first write. Settings that
97
98
  are not valid JSON abort the run rather than being overwritten.
98
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
+
99
119
  Hooks then need **no environment at all**: the command pins the absolute path
100
120
  of the Node that ran setup, and configuration comes from the credentials file.
101
121
  Claude Code spawns hooks with whatever environment it was launched from, so
@@ -148,7 +168,7 @@ pairing claude_code:… (not paired, installed 2026-09-23T05:13:40.907Z)
148
168
  token — none until this install is paired
149
169
  delivery inactive — nothing is sent, and nothing is queued for later
150
170
  local features active — the session prompts and the live socket signal need no pairing
151
- hooks 10/10 registered in ~/.claude/settings.json
171
+ hooks 11/11 registered in ~/.claude/settings.json
152
172
  ```
153
173
 
154
174
  `uninstall` removes an unpaired install the same way, and says there is no
@@ -239,8 +259,9 @@ The environment's network access must also allow the Ascenda API host.
239
259
  **Tokens never rotate in a cloud session.** Renewal revokes the previous
240
260
  token, and the replacement would die with the container, taking the
241
261
  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.
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.
244
265
 
245
266
  ### Register hooks manually
246
267
 
@@ -260,8 +281,11 @@ for machine-wide coverage:
260
281
  "PreCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PreCompact", "timeout": 5 }] }],
261
282
  "PostCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostCompact", "timeout": 5 }] }],
262
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 }] }],
263
285
  "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 }] }]
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 }] }]
265
289
  }
266
290
  }
267
291
  ```
@@ -414,8 +438,11 @@ PostToolUseFailure
414
438
  PreCompact
415
439
  PostCompact
416
440
  Stop
441
+ StopFailure
417
442
  Notification
418
443
  SessionEnd
444
+ SubagentStart
445
+ SubagentStop
419
446
  ```
420
447
 
421
448
  ## Ascenda event mappings
@@ -433,8 +460,11 @@ PostToolUseFailure -> compile_error / ai_tool_call_failed
433
460
  PreCompact -> context_compression_manual / context_compression_auto
434
461
  PostCompact -> context_pressure_high
435
462
  Stop -> ai_turn_completed (every turn), agent_loop_long (long only)
463
+ StopFailure -> nothing sent (live signal only)
436
464
  Notification -> supervision_interruption (interruptionKind only, never the message)
437
465
  SessionEnd -> recovery_offline_period (activity session_ended, sessionEndReason)
466
+ SubagentStart -> subagent_started (subagentId, subagentClass)
467
+ SubagentStop -> subagent_stopped (subagentId, subagentClass)
438
468
  ```
439
469
 
440
470
  ## Privacy defaults
@@ -461,14 +491,6 @@ readable salt the key is omitted entirely rather than sent blank.
461
491
 
462
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.
463
493
 
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
494
  ## Compliance
473
495
 
474
496
  `consentScope: ide_telemetry` and `provenance: ai_work_telemetry` on every