@ascenda-one/claude-code-hooks 0.1.35 → 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/README.md +77 -41
- package/dist/ascendaClient.js +8 -1
- package/dist/ascendaClient.js.map +1 -1
- package/dist/cli.js +1942 -914
- 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 +96 -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 +1 -1
package/README.md
CHANGED
|
@@ -74,6 +74,7 @@ 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 |
|
|
77
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 |
|
|
78
79
|
| `--scope user\|project` | register in `~/.claude/settings.json` (default, every project) or in this project's `.claude/settings.local.json` |
|
|
79
80
|
| `--project-dir <path>` | project root for `--scope project` (default cwd) |
|
|
@@ -100,6 +101,11 @@ rather than appending, hooks belonging to anyone else are left alone, and the
|
|
|
100
101
|
file is backed up to `.ascenda-backup` before the first write. Settings that
|
|
101
102
|
are not valid JSON abort the run rather than being overwritten.
|
|
102
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
|
+
|
|
103
109
|
#### Upgrading
|
|
104
110
|
|
|
105
111
|
Re-run `setup` with the scope you installed with. It keeps your pairing, adds
|
|
@@ -107,7 +113,7 @@ the hooks this version registers, and prints what it added:
|
|
|
107
113
|
|
|
108
114
|
```text
|
|
109
115
|
hooks ~/.claude/settings.json (13 events)
|
|
110
|
-
upgraded: added
|
|
116
|
+
upgraded: added PermissionRequest, PermissionDenied; hook set 3 → 4
|
|
111
117
|
```
|
|
112
118
|
|
|
113
119
|
`status` prints the installed hook set and, when it's older, the command to
|
|
@@ -233,12 +239,14 @@ Optional environment:
|
|
|
233
239
|
| `ASCENDA_EVENT_WRITE_TOKEN` | Only if you have no prior pairing to reuse — normally the token file supplies this |
|
|
234
240
|
| `ASCENDA_EVENT_WRITE_TOKEN_FILE` | Override token file path (default `~/.ascenda/tokens/<toolInstallationId>`) |
|
|
235
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` |
|
|
236
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 |
|
|
237
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) |
|
|
238
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 |
|
|
239
246
|
| `ASCENDA_STATE_FILE` | Override the send journal path (default `~/.ascenda/state/<toolInstallationId>.json`) |
|
|
240
247
|
| `ASCENDA_OUTBOX_FILE` | Override the outbox path (default `~/.ascenda/state/<toolInstallationId>.outbox.jsonl`) |
|
|
241
|
-
| `
|
|
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 |
|
|
242
250
|
| `ASCENDA_DISABLE_FAILURE_NOTICE` | `true` silences the one-time in-session notice about a collector that has stopped delivering |
|
|
243
251
|
|
|
244
252
|
On first run the CLI seeds `~/.ascenda/tokens/<toolInstallationId>` so
|
|
@@ -292,7 +300,9 @@ for machine-wide coverage:
|
|
|
292
300
|
"Notification": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Notification", "timeout": 5 }] }],
|
|
293
301
|
"SessionEnd": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SessionEnd", "timeout": 5 }] }],
|
|
294
302
|
"SubagentStart": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SubagentStart", "timeout": 5 }] }],
|
|
295
|
-
"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 }] }]
|
|
296
306
|
}
|
|
297
307
|
}
|
|
298
308
|
```
|
|
@@ -359,42 +369,46 @@ call, and never repeats until the collector has recovered and failed again.
|
|
|
359
369
|
distinguish a dead token from a night's sleep, because both are "no events".
|
|
360
370
|
Only the collector knows it tried and was refused.
|
|
361
371
|
|
|
362
|
-
###
|
|
372
|
+
### How events leave the machine
|
|
363
373
|
|
|
364
|
-
A
|
|
365
|
-
|
|
366
|
-
|
|
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:
|
|
367
377
|
|
|
368
378
|
```
|
|
369
379
|
~/.ascenda/state/<toolInstallationId>.outbox.jsonl
|
|
370
380
|
```
|
|
371
381
|
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
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.
|
|
394
408
|
|
|
395
409
|
The outbox is bounded: 10,000 entries and 7 days. When a bound evicts, the
|
|
396
410
|
discard is recorded in the journal as `"lastOutcome": "outbox_discarded"` with
|
|
397
|
-
a cumulative `outboxDiscarded` block
|
|
411
|
+
a cumulative `outboxDiscarded` block: how many, when, why, and how far back
|
|
398
412
|
the loss reaches. It survives every later success, because a gap that has
|
|
399
413
|
since closed is still a gap in the data.
|
|
400
414
|
|
|
@@ -403,7 +417,8 @@ since closed is still a gap in the data.
|
|
|
403
417
|
```
|
|
404
418
|
Outbox ~/.ascenda/state/claude_code_….outbox.jsonl
|
|
405
419
|
Outbox depth 37 waiting — oldest queued 2026-09-03T01:12:08.114Z (3h 41m ago)
|
|
406
|
-
Outbox drain
|
|
420
|
+
Outbox drain on (queued events are replayed, oldest first) — ASCENDA_OUTBOX_DRAIN
|
|
421
|
+
Delivery background sender (the hook queues and returns)
|
|
407
422
|
Outbox discarded 12 total; last 12 at 2026-09-02T… (12 age, reaching back to 2026-08-25T…)
|
|
408
423
|
```
|
|
409
424
|
|
|
@@ -411,11 +426,11 @@ A non-empty outbox is the honest health answer. `consecutiveFailures` resets
|
|
|
411
426
|
on the first success after an outage; the outbox says events from that outage
|
|
412
427
|
are still on this machine.
|
|
413
428
|
|
|
414
|
-
Hooks overlap
|
|
415
|
-
processes
|
|
416
|
-
|
|
417
|
-
entry is never deleted before the server has confirmed it
|
|
418
|
-
|
|
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.
|
|
419
434
|
|
|
420
435
|
## Build from source
|
|
421
436
|
|
|
@@ -459,6 +474,8 @@ Notification
|
|
|
459
474
|
SessionEnd
|
|
460
475
|
SubagentStart
|
|
461
476
|
SubagentStop
|
|
477
|
+
PermissionRequest
|
|
478
|
+
PermissionDenied
|
|
462
479
|
```
|
|
463
480
|
|
|
464
481
|
## Ascenda event mappings
|
|
@@ -481,6 +498,8 @@ Notification -> supervision_interruption (interruptionKind only, never the
|
|
|
481
498
|
SessionEnd -> recovery_offline_period (activity session_ended, sessionEndReason)
|
|
482
499
|
SubagentStart -> subagent_started (subagentId, subagentClass)
|
|
483
500
|
SubagentStop -> subagent_stopped (subagentId, subagentClass)
|
|
501
|
+
PermissionRequest -> permission_requested (toolName, autonomyMode)
|
|
502
|
+
PermissionDenied -> permission_denied (toolName, autonomyMode), auto mode only
|
|
484
503
|
```
|
|
485
504
|
|
|
486
505
|
## Privacy defaults
|
|
@@ -488,14 +507,21 @@ SubagentStop -> subagent_stopped (subagentId, subagentClass)
|
|
|
488
507
|
Metadata-only telemetry. Does not send raw prompts, responses, code, file names, repository names, branch names, or terminal output.
|
|
489
508
|
|
|
490
509
|
When the agent stops and waits for you, `Notification` records only which kind
|
|
491
|
-
of wait it was — `permission_request`, `idle_prompt` or
|
|
492
|
-
|
|
493
|
-
|
|
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
|
|
494
514
|
answer. `tests/interruptionContentGuard.test.mjs` fails the build if that
|
|
495
515
|
changes.
|
|
496
516
|
|
|
497
|
-
|
|
498
|
-
|
|
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
|
|
499
525
|
the checkout's and repository's folder names, and `metadata.branchHash` from
|
|
500
526
|
the branch the checkout is on. The salt is random per machine, stored at
|
|
501
527
|
`~/.ascenda/salt`, and never transmitted — without it, a digest of a name from
|
|
@@ -505,6 +531,16 @@ lets work be grouped by branch on the other side without the name itself
|
|
|
505
531
|
leaving the machine. On a detached HEAD, outside a checkout, or with no
|
|
506
532
|
readable salt the key is omitted entirely rather than sent blank.
|
|
507
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
|
+
|
|
508
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.
|
|
509
545
|
|
|
510
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"}
|