@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 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 SubagentStart, SubagentStop; hook set 2 → 3
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
- | `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 |
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
- ### When the collector cannot reach Ascenda
372
+ ### How events leave the machine
363
373
 
364
- A send that fails without a verdict — the endpoint unreachable, a timeout, a
365
- `429` or `5xx` — is retried once after 250 ms and then **kept**, not dropped.
366
- 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:
367
377
 
368
378
  ```
369
379
  ~/.ascenda/state/<toolInstallationId>.outbox.jsonl
370
380
  ```
371
381
 
372
- one JSON line per event, exactly as it would have gone on the wire, plus the
373
- time it was queued. Anything longer than a blip — a laptop waking from sleep,
374
- a VPN reconnecting, a captive portal, a slow network on a train — used to lose
375
- every event for its duration with no copy anywhere. Now it costs nothing but
376
- delay. A rejection *with* a verdict (`400`, `401`, `403`) is not queued:
377
- replaying it cannot change the answer.
378
-
379
- The next hook invocation drains the outbox, oldest first, one batch of up to
380
- 100 per invocation and never with a backoff loop — the hook is on your
381
- critical path, and the invocation after that is usually seconds away. An
382
- entry is deleted when the server answers `accepted` **or** `duplicate`; a
383
- duplicate means the server already had it, which is the point of the
384
- `idempotencyKey` every event carries. If the door refuses again, the pass stops
385
- with everything still on disk, and the live event joins the queue instead of
386
- knocking on a door that just said no.
387
-
388
- > **Sending from the outbox is off by default.** Set `ASCENDA_OUTBOX_DRAIN=true`
389
- > to enable it. A drain against an ingest endpoint that does not yet dedupe
390
- > live events on `idempotencyKey` would land every queued event a second
391
- > time — the exact double-count that blocked this queue until the key existed.
392
- > Until the deployed backend is confirmed to answer a replay with `duplicate`,
393
- > 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.
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 — how many, when, why, and how far back
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 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)
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 — Claude Code fires `PreToolUse` and `PostToolUse` from separate
415
- processes — so appends use `O_APPEND` (whole lines, never fragments) and a
416
- drain takes the file by renaming it out from under concurrent appenders. An
417
- entry is never deleted before the server has confirmed it; a drain that dies
418
- 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.
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 `other`. The
492
- notification's own wording is read to pick one of those three labels and is
493
- 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
494
514
  answer. `tests/interruptionContentGuard.test.mjs` fails the build if that
495
515
  changes.
496
516
 
497
- Repository and branch identity travel only as machine-salted digests, derived
498
- 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
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
@@ -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"}