@ascenda-one/claude-code-hooks 0.1.34 → 0.1.36
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/NOTICE +6 -0
- package/README.md +85 -45
- package/dist/ascendaClient.js +8 -1
- package/dist/ascendaClient.js.map +1 -1
- package/dist/cli.js +2229 -944
- package/dist/cli.js.map +1 -1
- package/dist/mapClaudeEvent.js +127 -15
- package/dist/mapClaudeEvent.js.map +1 -1
- package/dist/paths.js +11 -1
- package/dist/paths.js.map +1 -1
- package/dist/setup.js +115 -26
- package/dist/setup.js.map +1 -1
- package/dist/types.js +1 -1
- package/dist/types.js.map +1 -1
- package/dist/usageLimitReset.js +2 -3
- package/dist/usageLimitReset.js.map +1 -1
- package/examples/settings.local.json +15 -13
- package/package.json +3 -2
package/NOTICE
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
@ascenda-one/claude-code-hooks
|
|
2
|
+
Copyright 2026 Ascenda One Pty Ltd
|
|
3
|
+
|
|
4
|
+
Licensed under the Apache License, Version 2.0. See LICENSE.
|
|
5
|
+
|
|
6
|
+
Metadata-only AI workload telemetry adapter. Do not send source code, raw prompts, raw responses, file names, branch names, repository names, or terminal output by default.
|
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
Claude Code hooks adapter for Ascenda AI workload telemetry.
|
|
4
4
|
|
|
5
5
|
Part of [ai-engineer-tools](../). For what these measurements do and do not
|
|
6
|
-
establish, see [What this measures](../#what-this-measures
|
|
6
|
+
establish, see [What this measures](../#what-this-measures).
|
|
7
7
|
Event mapping: [docs/CLAUDE_MAPPING.md](./docs/CLAUDE_MAPPING.md).
|
|
8
8
|
|
|
9
9
|
## What it sends
|
|
@@ -74,6 +74,8 @@ npx @ascenda-one/claude-code-hooks uninstall # removes hooks and the binary
|
|
|
74
74
|
| `--local [port]` | shorthand for a local [dev server](../ascenda-dev-server/) (default `4477`) |
|
|
75
75
|
| `--tool-installation-id <id>` / `--token <t>` | reuse an existing pairing instead of creating one |
|
|
76
76
|
| `--no-pair` | install the local half only: hooks work, nothing is sent |
|
|
77
|
+
| `--no-repo-keys` | GitHub repositories get a `repoKey` and, off the default branch, a `branchKey`, so a pull request can be matched to a session. They are unsalted digests, so anyone who guesses the names can recompute them. This turns both off, machine-wide. `--repo-keys` turns them back on |
|
|
78
|
+
| `--event-log [path\|off]` | keep every event in a local JSONL file (default `~/.ascenda/events.jsonl`). On by default without a pairing; `off` stops it |
|
|
77
79
|
| `--scope user\|project` | register in `~/.claude/settings.json` (default, every project) or in this project's `.claude/settings.local.json` |
|
|
78
80
|
| `--project-dir <path>` | project root for `--scope project` (default cwd) |
|
|
79
81
|
| `--dry-run` | print what would change, write nothing |
|
|
@@ -99,6 +101,11 @@ rather than appending, hooks belonging to anyone else are left alone, and the
|
|
|
99
101
|
file is backed up to `.ascenda-backup` before the first write. Settings that
|
|
100
102
|
are not valid JSON abort the run rather than being overwritten.
|
|
101
103
|
|
|
104
|
+
With `CLAUDE_CONFIG_DIR` set, user-scope setup, `status` and `uninstall` use
|
|
105
|
+
`$CLAUDE_CONFIG_DIR/settings.json`. If another tool has added its own hook to
|
|
106
|
+
one of our groups, setup and `uninstall` take out only ours and leave theirs.
|
|
107
|
+
A symlinked settings file stays a symlink.
|
|
108
|
+
|
|
102
109
|
#### Upgrading
|
|
103
110
|
|
|
104
111
|
Re-run `setup` with the scope you installed with. It keeps your pairing, adds
|
|
@@ -106,7 +113,7 @@ the hooks this version registers, and prints what it added:
|
|
|
106
113
|
|
|
107
114
|
```text
|
|
108
115
|
hooks ~/.claude/settings.json (13 events)
|
|
109
|
-
upgraded: added
|
|
116
|
+
upgraded: added PermissionRequest, PermissionDenied; hook set 3 → 4
|
|
110
117
|
```
|
|
111
118
|
|
|
112
119
|
`status` prints the installed hook set and, when it's older, the command to
|
|
@@ -147,11 +154,13 @@ the retry:
|
|
|
147
154
|
|
|
148
155
|

|
|
149
156
|
|
|
150
|
-
|
|
157
|
+
Three things work with no pairing at all, which is why this mode exists. The
|
|
151
158
|
session prompts are composed locally in the hook process. The live signal goes
|
|
152
159
|
to a socket on your own machine, so a listener there sees an agent working the
|
|
153
|
-
moment it starts.
|
|
154
|
-
|
|
160
|
+
moment it starts. And every event is written to `~/.ascenda/events.jsonl`, the
|
|
161
|
+
same metadata a paired install would send, for you or any other tool to read.
|
|
162
|
+
[examples/local-event-reader](../examples/local-event-reader/) is a small
|
|
163
|
+
script that does. None of it owes anything to a backend.
|
|
155
164
|
|
|
156
165
|
What that install holds: the hook binary, the registered events, and a
|
|
157
166
|
credentials file with an installation id, `localOnly: true` and `installedAt`.
|
|
@@ -230,11 +239,14 @@ Optional environment:
|
|
|
230
239
|
| `ASCENDA_EVENT_WRITE_TOKEN` | Only if you have no prior pairing to reuse — normally the token file supplies this |
|
|
231
240
|
| `ASCENDA_EVENT_WRITE_TOKEN_FILE` | Override token file path (default `~/.ascenda/tokens/<toolInstallationId>`) |
|
|
232
241
|
| `ASCENDA_SESSION_ID` | Stable session id across hooks |
|
|
242
|
+
| `ASCENDA_REPO_KEYS` | `off` leaves the repository and branch keys off every event. Wins over `setup --no-repo-keys` |
|
|
243
|
+
| `ASCENDA_EVENT_LOG_FILE` | Local JSONL event log path, or `off`. Wins over `setup --event-log`. Without either, an unpaired install writes `~/.ascenda/events.jsonl` and a paired one writes nothing |
|
|
233
244
|
| `ASCENDA_WORKSPACE_HASH` | Override only. By default the hook derives this from the payload's own `cwd`: a machine-salted hash of the checkout folder's basename (never the path itself) |
|
|
234
245
|
| `ASCENDA_PROJECT_HASH` | Override only. Defaults to the salted hash of the canonical repository's basename — a git worktree folds into the repo it was created from |
|
|
235
246
|
| `ASCENDA_STATE_FILE` | Override the send journal path (default `~/.ascenda/state/<toolInstallationId>.json`) |
|
|
236
247
|
| `ASCENDA_OUTBOX_FILE` | Override the outbox path (default `~/.ascenda/state/<toolInstallationId>.outbox.jsonl`) |
|
|
237
|
-
| `
|
|
248
|
+
| `ASCENDA_HOOK_DELIVERY` | `inline` makes each hook send its own events and wait for the answer. By default a background sender does it; see "How events leave the machine" |
|
|
249
|
+
| `ASCENDA_OUTBOX_DRAIN` | `0` holds the outbox without sending it, and hooks send their own events inline. On by default |
|
|
238
250
|
| `ASCENDA_DISABLE_FAILURE_NOTICE` | `true` silences the one-time in-session notice about a collector that has stopped delivering |
|
|
239
251
|
|
|
240
252
|
On first run the CLI seeds `~/.ascenda/tokens/<toolInstallationId>` so
|
|
@@ -288,7 +300,9 @@ for machine-wide coverage:
|
|
|
288
300
|
"Notification": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Notification", "timeout": 5 }] }],
|
|
289
301
|
"SessionEnd": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SessionEnd", "timeout": 5 }] }],
|
|
290
302
|
"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 }] }]
|
|
303
|
+
"SubagentStop": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SubagentStop", "timeout": 5 }] }],
|
|
304
|
+
"PermissionRequest": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PermissionRequest", "timeout": 5 }] }],
|
|
305
|
+
"PermissionDenied": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PermissionDenied", "timeout": 5 }] }]
|
|
292
306
|
}
|
|
293
307
|
}
|
|
294
308
|
```
|
|
@@ -355,42 +369,46 @@ call, and never repeats until the collector has recovered and failed again.
|
|
|
355
369
|
distinguish a dead token from a night's sleep, because both are "no events".
|
|
356
370
|
Only the collector knows it tried and was refused.
|
|
357
371
|
|
|
358
|
-
###
|
|
372
|
+
### How events leave the machine
|
|
359
373
|
|
|
360
|
-
A
|
|
361
|
-
|
|
362
|
-
|
|
374
|
+
A hook doesn't send anything itself. It appends its events to an outbox next
|
|
375
|
+
to the journal, starts a background sender, and hands control back to Claude
|
|
376
|
+
Code in a few milliseconds:
|
|
363
377
|
|
|
364
378
|
```
|
|
365
379
|
~/.ascenda/state/<toolInstallationId>.outbox.jsonl
|
|
366
380
|
```
|
|
367
381
|
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
382
|
+
Each line is one event, exactly as it goes on the wire, plus the time it was
|
|
383
|
+
queued. The background sender is the same CLI run with `__flush-outbox`. It
|
|
384
|
+
sends the outbox oldest first, up to 100 events per request, until it's empty,
|
|
385
|
+
and exits. One sender runs at a time: a lock file next to the outbox
|
|
386
|
+
(`.flushing`) tells the next hook that one is already working.
|
|
387
|
+
|
|
388
|
+
So the network never sits between you and your agent. A slow connection, a
|
|
389
|
+
captive portal or an outage costs delay, not a stalled tool call. Each event's
|
|
390
|
+
time and `idempotencyKey` are set when the hook fires, so an event sent a few
|
|
391
|
+
seconds later keeps its time, and one sent twice comes back `duplicate`.
|
|
392
|
+
|
|
393
|
+
An entry is deleted when the server answers `accepted` or `duplicate`. If the
|
|
394
|
+
server can't be reached (a timeout, a `429` or `5xx`), the sender stops with
|
|
395
|
+
everything still on disk and journals the failure, and the next hook starts
|
|
396
|
+
another. A refusal with a verdict (`400`, `401`, `403`) isn't kept: replaying it
|
|
397
|
+
can't change the answer.
|
|
398
|
+
|
|
399
|
+
Two settings send from the hook itself, as earlier versions did:
|
|
400
|
+
|
|
401
|
+
- `ASCENDA_HOOK_DELIVERY=inline`. The hook sends each event and waits for the
|
|
402
|
+
answer. A failed send is retried once after 250 ms and then queued.
|
|
403
|
+
- `ASCENDA_OUTBOX_DRAIN=0`, which holds the outbox without sending it. The
|
|
404
|
+
hook still sends its own events inline, so nothing stops arriving.
|
|
405
|
+
|
|
406
|
+
A hosted session always sends inline. Its container goes when the session
|
|
407
|
+
does, and an outbox in it would go too.
|
|
390
408
|
|
|
391
409
|
The outbox is bounded: 10,000 entries and 7 days. When a bound evicts, the
|
|
392
410
|
discard is recorded in the journal as `"lastOutcome": "outbox_discarded"` with
|
|
393
|
-
a cumulative `outboxDiscarded` block
|
|
411
|
+
a cumulative `outboxDiscarded` block: how many, when, why, and how far back
|
|
394
412
|
the loss reaches. It survives every later success, because a gap that has
|
|
395
413
|
since closed is still a gap in the data.
|
|
396
414
|
|
|
@@ -399,7 +417,8 @@ since closed is still a gap in the data.
|
|
|
399
417
|
```
|
|
400
418
|
Outbox ~/.ascenda/state/claude_code_….outbox.jsonl
|
|
401
419
|
Outbox depth 37 waiting — oldest queued 2026-09-03T01:12:08.114Z (3h 41m ago)
|
|
402
|
-
Outbox drain
|
|
420
|
+
Outbox drain on (queued events are replayed, oldest first) — ASCENDA_OUTBOX_DRAIN
|
|
421
|
+
Delivery background sender (the hook queues and returns)
|
|
403
422
|
Outbox discarded 12 total; last 12 at 2026-09-02T… (12 age, reaching back to 2026-08-25T…)
|
|
404
423
|
```
|
|
405
424
|
|
|
@@ -407,11 +426,11 @@ A non-empty outbox is the honest health answer. `consecutiveFailures` resets
|
|
|
407
426
|
on the first success after an outage; the outbox says events from that outage
|
|
408
427
|
are still on this machine.
|
|
409
428
|
|
|
410
|
-
Hooks overlap
|
|
411
|
-
processes
|
|
412
|
-
|
|
413
|
-
entry is never deleted before the server has confirmed it
|
|
414
|
-
|
|
429
|
+
Hooks overlap, since Claude Code fires `PreToolUse` and `PostToolUse` from
|
|
430
|
+
separate processes. Appends use `O_APPEND` (whole lines, never fragments), and
|
|
431
|
+
a sender takes the file by renaming it out from under concurrent appenders. An
|
|
432
|
+
entry is never deleted before the server has confirmed it. A sender that dies
|
|
433
|
+
partway leaves a claim file that the next one sweeps back in.
|
|
415
434
|
|
|
416
435
|
## Build from source
|
|
417
436
|
|
|
@@ -455,6 +474,8 @@ Notification
|
|
|
455
474
|
SessionEnd
|
|
456
475
|
SubagentStart
|
|
457
476
|
SubagentStop
|
|
477
|
+
PermissionRequest
|
|
478
|
+
PermissionDenied
|
|
458
479
|
```
|
|
459
480
|
|
|
460
481
|
## Ascenda event mappings
|
|
@@ -477,6 +498,8 @@ Notification -> supervision_interruption (interruptionKind only, never the
|
|
|
477
498
|
SessionEnd -> recovery_offline_period (activity session_ended, sessionEndReason)
|
|
478
499
|
SubagentStart -> subagent_started (subagentId, subagentClass)
|
|
479
500
|
SubagentStop -> subagent_stopped (subagentId, subagentClass)
|
|
501
|
+
PermissionRequest -> permission_requested (toolName, autonomyMode)
|
|
502
|
+
PermissionDenied -> permission_denied (toolName, autonomyMode), auto mode only
|
|
480
503
|
```
|
|
481
504
|
|
|
482
505
|
## Privacy defaults
|
|
@@ -484,14 +507,21 @@ SubagentStop -> subagent_stopped (subagentId, subagentClass)
|
|
|
484
507
|
Metadata-only telemetry. Does not send raw prompts, responses, code, file names, repository names, branch names, or terminal output.
|
|
485
508
|
|
|
486
509
|
When the agent stops and waits for you, `Notification` records only which kind
|
|
487
|
-
of wait it was — `permission_request`, `idle_prompt` or
|
|
488
|
-
|
|
489
|
-
|
|
510
|
+
of wait it was — `permission_request`, `input_request`, `idle_prompt` or
|
|
511
|
+
`other`. Claude Code's `notification_type` picks the label, and the
|
|
512
|
+
notification's own wording does it on a version that doesn't send one. The
|
|
513
|
+
wording is then discarded; it never leaves the hook process, and neither does anything you
|
|
490
514
|
answer. `tests/interruptionContentGuard.test.mjs` fails the build if that
|
|
491
515
|
changes.
|
|
492
516
|
|
|
493
|
-
|
|
494
|
-
|
|
517
|
+
`PermissionRequest` and `PermissionDenied` send the tool's name and the
|
|
518
|
+
permission posture, and nothing about what the tool was asked to do. The
|
|
519
|
+
request hook fires before you answer and no hook reports the answer, so a
|
|
520
|
+
request doesn't say whether it was granted. The denied hook only fires in auto
|
|
521
|
+
mode.
|
|
522
|
+
|
|
523
|
+
Repository and branch identity travel only as digests, derived in the hook
|
|
524
|
+
process and never as text. Most are machine-salted: `workspaceHash` and `projectHash` from
|
|
495
525
|
the checkout's and repository's folder names, and `metadata.branchHash` from
|
|
496
526
|
the branch the checkout is on. The salt is random per machine, stored at
|
|
497
527
|
`~/.ascenda/salt`, and never transmitted — without it, a digest of a name from
|
|
@@ -501,6 +531,16 @@ lets work be grouped by branch on the other side without the name itself
|
|
|
501
531
|
leaving the machine. On a detached HEAD, outside a checkout, or with no
|
|
502
532
|
readable salt the key is omitted entirely rather than sent blank.
|
|
503
533
|
|
|
534
|
+
Two more digests are not salted, on purpose. `metadata.repoKey` and
|
|
535
|
+
`metadata.branchKey` use the recipe Ascenda's GitHub collector uses, which runs
|
|
536
|
+
where no salt exists, so a session and a pull request on the same repository
|
|
537
|
+
and branch carry the same pair. They go on events for github.com remotes only,
|
|
538
|
+
and `branchKey` is left off the default branch. Because they're unsalted,
|
|
539
|
+
anyone who guesses a repository or branch name can confirm it, and for a public
|
|
540
|
+
repository those names are public. Turn them off with `setup --no-repo-keys`
|
|
541
|
+
or `ASCENDA_REPO_KEYS=off`. `metadata.promptId` is Claude Code's own id for the
|
|
542
|
+
prompt a turn answers, and says nothing about its text.
|
|
543
|
+
|
|
504
544
|
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.
|
|
505
545
|
|
|
506
546
|
## Compliance
|
package/dist/ascendaClient.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { AscendaEventSender } from "@ascenda-one/tool-kit";
|
|
1
|
+
import { AscendaEventSender, runOutboxFlush } from "@ascenda-one/tool-kit";
|
|
2
2
|
export { AscendaApiError as AscendaClientError } from "@ascenda-one/tool-kit";
|
|
3
3
|
export class AscendaClient {
|
|
4
4
|
sender;
|
|
@@ -28,6 +28,13 @@ export class AscendaClient {
|
|
|
28
28
|
queue(mapped) {
|
|
29
29
|
return this.sender.queue(mapped);
|
|
30
30
|
}
|
|
31
|
+
outboxFilePath() {
|
|
32
|
+
return this.sender.outboxFilePath();
|
|
33
|
+
}
|
|
34
|
+
/** Drains the outbox until it's empty or the door refuses. What the background flusher runs. */
|
|
35
|
+
async flushOutbox() {
|
|
36
|
+
await runOutboxFlush(this.sender);
|
|
37
|
+
}
|
|
31
38
|
async renewEventToken() {
|
|
32
39
|
return this.sender.renewEventToken();
|
|
33
40
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ascendaClient.js","sourceRoot":"","sources":["../src/ascendaClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;
|
|
1
|
+
{"version":3,"file":"ascendaClient.js","sourceRoot":"","sources":["../src/ascendaClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAI3E,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,cAAc;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;IACtC,CAAC;IAED,gGAAgG;IAChG,KAAK,CAAC,WAAW;QACf,MAAM,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,eAAe;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;IACvC,CAAC;CACF"}
|