@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 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-and-what-that-does-not-yet-prove).
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 SubagentStart, SubagentStop; hook set 2 → 3
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
  ![setup --no-pair finishing with "Ready."](https://raw.githubusercontent.com/ascendaone-com/ai-engineer-tools/main/docs/images/cli-setup-no-pair.png)
149
156
 
150
- Two things work with no pairing at all, which is why this mode exists. The
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. Neither owes anything to a backend, and gating the install on
154
- one kept them from the people still setting Ascenda up.
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
- | `ASCENDA_OUTBOX_DRAIN` | `true` lets the next hook re-send queued events. **Off by default** until the ingest endpoint is confirmed to dedupe live events on `idempotencyKey`; see "When the collector cannot reach Ascenda" |
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
- ### When the collector cannot reach Ascenda
372
+ ### How events leave the machine
359
373
 
360
- A send that fails without a verdict — the endpoint unreachable, a timeout, a
361
- `429` or `5xx` — is retried once after 250 ms and then **kept**, not dropped.
362
- The payload is appended to an outbox next to the journal:
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
- one JSON line per event, exactly as it would have gone on the wire, plus the
369
- time it was queued. Anything longer than a blip — a laptop waking from sleep,
370
- a VPN reconnecting, a captive portal, a slow network on a train — used to lose
371
- every event for its duration with no copy anywhere. Now it costs nothing but
372
- delay. A rejection *with* a verdict (`400`, `401`, `403`) is not queued:
373
- replaying it cannot change the answer.
374
-
375
- The next hook invocation drains the outbox, oldest first, one batch of up to
376
- 100 per invocation and never with a backoff loop — the hook is on your
377
- critical path, and the invocation after that is usually seconds away. An
378
- entry is deleted when the server answers `accepted` **or** `duplicate`; a
379
- duplicate means the server already had it, which is the point of the
380
- `idempotencyKey` every event carries. If the door refuses again, the pass stops
381
- with everything still on disk, and the live event joins the queue instead of
382
- knocking on a door that just said no.
383
-
384
- > **Sending from the outbox is off by default.** Set `ASCENDA_OUTBOX_DRAIN=true`
385
- > to enable it. A drain against an ingest endpoint that does not yet dedupe
386
- > live events on `idempotencyKey` would land every queued event a second
387
- > time — the exact double-count that blocked this queue until the key existed.
388
- > Until the deployed backend is confirmed to answer a replay with `duplicate`,
389
- > events are queued, bounded and reported, but not re-sent.
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 — how many, when, why, and how far back
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 off (queued events are kept and bounded, not sent) — ASCENDA_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 — Claude Code fires `PreToolUse` and `PostToolUse` from separate
411
- processes — so appends use `O_APPEND` (whole lines, never fragments) and a
412
- drain takes the file by renaming it out from under concurrent appenders. An
413
- entry is never deleted before the server has confirmed it; a drain that dies
414
- mid-way leaves a claim file that the next drain sweeps back in.
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 `other`. The
488
- notification's own wording is read to pick one of those three labels and is
489
- then discarded; it never leaves the hook process, and neither does anything you
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
- Repository and branch identity travel only as machine-salted digests, derived
494
- in the hook process and never as text: `workspaceHash` and `projectHash` from
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
@@ -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;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"}
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"}