@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 +44 -22
- package/dist/cli.js +2027 -467
- package/dist/cli.js.map +1 -1
- package/dist/liveEvent.js +87 -0
- package/dist/liveEvent.js.map +1 -0
- package/dist/mapClaudeEvent.js +68 -4
- package/dist/mapClaudeEvent.js.map +1 -1
- package/dist/setup.js +99 -15
- 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
|
```
|
|
@@ -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
|
|
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
|
|
243
|
-
|
|
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
|