@ascenda-one/claude-code-hooks 0.1.15 → 0.1.17
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 +83 -8
- package/dist/ascendaClient.js +1 -0
- package/dist/ascendaClient.js.map +1 -1
- package/dist/cli.js +2029 -312
- package/dist/cli.js.map +1 -1
- package/dist/config.js +71 -12
- package/dist/config.js.map +1 -1
- package/dist/mapClaudeEvent.js +196 -11
- package/dist/mapClaudeEvent.js.map +1 -1
- package/dist/paths.js +7 -25
- package/dist/paths.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -126,11 +126,14 @@ Code. The token itself is never copied around — every CLI tool reads it from
|
|
|
126
126
|
the file `pair` wrote. (The editor extension's pairing cannot be reused here:
|
|
127
127
|
its token lives in the editor's private secret storage.)
|
|
128
128
|
|
|
129
|
-
> **
|
|
130
|
-
>
|
|
131
|
-
>
|
|
132
|
-
>
|
|
133
|
-
>
|
|
129
|
+
> **When the variable is absent** — and it is absent for any app launched from
|
|
130
|
+
> the Dock, Finder or Spotlight, which never see a shell profile — the hooks
|
|
131
|
+
> fall back to the `~/.ascenda/credentials.json` that `setup` writes, and then
|
|
132
|
+
> to the token store: when `~/.ascenda/tokens/` holds exactly one `claude_code`
|
|
133
|
+
> token, its filename is the id. With none, or several, every hook invocation
|
|
134
|
+
> records a `skipped_no_installation_id` attempt in the journal and exits
|
|
135
|
+
> saying so. The adapter refuses to guess rather than silently mint a second,
|
|
136
|
+
> unpaired identity that would fragment your telemetry across two installations.
|
|
134
137
|
|
|
135
138
|
On a Dev backend with no phone, [pairing-sim](../ascenda-pairing-sim/) stands in
|
|
136
139
|
for the app:
|
|
@@ -151,6 +154,8 @@ Optional environment:
|
|
|
151
154
|
| `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) |
|
|
152
155
|
| `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 |
|
|
153
156
|
| `ASCENDA_STATE_FILE` | Override the send journal path (default `~/.ascenda/state/<toolInstallationId>.json`) |
|
|
157
|
+
| `ASCENDA_OUTBOX_FILE` | Override the outbox path (default `~/.ascenda/state/<toolInstallationId>.outbox.jsonl`) |
|
|
158
|
+
| `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" |
|
|
154
159
|
| `ASCENDA_DISABLE_FAILURE_NOTICE` | `true` silences the one-time in-session notice about a collector that has stopped delivering |
|
|
155
160
|
|
|
156
161
|
On first run the CLI seeds `~/.ascenda/tokens/<toolInstallationId>` so
|
|
@@ -185,9 +190,10 @@ for machine-wide coverage:
|
|
|
185
190
|
npx -y @ascenda-one/claude-code-hooks doctor
|
|
186
191
|
```
|
|
187
192
|
|
|
188
|
-
`doctor` prints the installation id
|
|
189
|
-
|
|
190
|
-
|
|
193
|
+
`doctor` prints the installation id and where it came from (environment,
|
|
194
|
+
credentials file, or the token store on disk), the token's presence and age,
|
|
195
|
+
the last recorded send outcome, any sends skipped for want of an installation
|
|
196
|
+
id, and the result of a live round trip against the real ingest endpoint. It is the first thing to run when the Ascenda app shows a
|
|
191
197
|
connected tool that is not producing data.
|
|
192
198
|
|
|
193
199
|
A telemetry failure never blocks your turn: **every hook invocation exits `0`**,
|
|
@@ -228,6 +234,64 @@ call, and never repeats until the collector has recovered and failed again.
|
|
|
228
234
|
distinguish a dead token from a night's sleep, because both are "no events".
|
|
229
235
|
Only the collector knows it tried and was refused.
|
|
230
236
|
|
|
237
|
+
### When the collector cannot reach Ascenda
|
|
238
|
+
|
|
239
|
+
A send that fails without a verdict — the endpoint unreachable, a timeout, a
|
|
240
|
+
`429` or `5xx` — is retried once after 250 ms and then **kept**, not dropped.
|
|
241
|
+
The payload is appended to an outbox next to the journal:
|
|
242
|
+
|
|
243
|
+
```
|
|
244
|
+
~/.ascenda/state/<toolInstallationId>.outbox.jsonl
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
one JSON line per event, exactly as it would have gone on the wire, plus the
|
|
248
|
+
time it was queued. Anything longer than a blip — a laptop waking from sleep,
|
|
249
|
+
a VPN reconnecting, a captive portal, a slow network on a train — used to lose
|
|
250
|
+
every event for its duration with no copy anywhere. Now it costs nothing but
|
|
251
|
+
delay. A rejection *with* a verdict (`400`, `401`, `403`) is not queued:
|
|
252
|
+
replaying it cannot change the answer.
|
|
253
|
+
|
|
254
|
+
The next hook invocation drains the outbox, oldest first, one batch of up to
|
|
255
|
+
100 per invocation and never with a backoff loop — the hook is on your
|
|
256
|
+
critical path, and the invocation after that is usually seconds away. An
|
|
257
|
+
entry is deleted when the server answers `accepted` **or** `duplicate`; a
|
|
258
|
+
duplicate means the server already had it, which is the point of the
|
|
259
|
+
`idempotencyKey` every event carries. If the door refuses again, the pass stops
|
|
260
|
+
with everything still on disk, and the live event joins the queue instead of
|
|
261
|
+
knocking on a door that just said no.
|
|
262
|
+
|
|
263
|
+
> **Sending from the outbox is off by default.** Set `ASCENDA_OUTBOX_DRAIN=true`
|
|
264
|
+
> to enable it. A drain against an ingest endpoint that does not yet dedupe
|
|
265
|
+
> live events on `idempotencyKey` would land every queued event a second
|
|
266
|
+
> time — the exact double-count that blocked this queue until the key existed.
|
|
267
|
+
> Until the deployed backend is confirmed to answer a replay with `duplicate`,
|
|
268
|
+
> events are queued, bounded and reported, but not re-sent.
|
|
269
|
+
|
|
270
|
+
The outbox is bounded: 10,000 entries and 7 days. When a bound evicts, the
|
|
271
|
+
discard is recorded in the journal as `"lastOutcome": "outbox_discarded"` with
|
|
272
|
+
a cumulative `outboxDiscarded` block — how many, when, why, and how far back
|
|
273
|
+
the loss reaches. It survives every later success, because a gap that has
|
|
274
|
+
since closed is still a gap in the data.
|
|
275
|
+
|
|
276
|
+
`doctor` reads all of this:
|
|
277
|
+
|
|
278
|
+
```
|
|
279
|
+
Outbox ~/.ascenda/state/claude_code_….outbox.jsonl
|
|
280
|
+
Outbox depth 37 waiting — oldest queued 2026-09-03T01:12:08.114Z (3h 41m ago)
|
|
281
|
+
Outbox drain off (queued events are kept and bounded, not sent) — ASCENDA_OUTBOX_DRAIN
|
|
282
|
+
Outbox discarded 12 total; last 12 at 2026-09-02T… (12 age, reaching back to 2026-08-25T…)
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
A non-empty outbox is the honest health answer. `consecutiveFailures` resets
|
|
286
|
+
on the first success after an outage; the outbox says events from that outage
|
|
287
|
+
are still on this machine.
|
|
288
|
+
|
|
289
|
+
Hooks overlap — Claude Code fires `PreToolUse` and `PostToolUse` from separate
|
|
290
|
+
processes — so appends use `O_APPEND` (whole lines, never fragments) and a
|
|
291
|
+
drain takes the file by renaming it out from under concurrent appenders. An
|
|
292
|
+
entry is never deleted before the server has confirmed it; a drain that dies
|
|
293
|
+
mid-way leaves a claim file that the next drain sweeps back in.
|
|
294
|
+
|
|
231
295
|
## Build from source
|
|
232
296
|
|
|
233
297
|
Not needed to use this — both routes above ship prebuilt. It is here because
|
|
@@ -288,6 +352,17 @@ Notification -> (skipped — no catalog event)
|
|
|
288
352
|
|
|
289
353
|
Metadata-only telemetry. Does not send raw prompts, responses, code, file names, repository names, branch names, or terminal output.
|
|
290
354
|
|
|
355
|
+
Repository and branch identity travel only as machine-salted digests, derived
|
|
356
|
+
in the hook process and never as text: `workspaceHash` and `projectHash` from
|
|
357
|
+
the checkout's and repository's folder names, and `metadata.branchHash` from
|
|
358
|
+
the branch the checkout is on. The salt is random per machine, stored at
|
|
359
|
+
`~/.ascenda/salt`, and never transmitted — without it, a digest of a name from
|
|
360
|
+
a short list is recoverable by guessing. A branch name is low-entropy in
|
|
361
|
+
exactly that way, so the branch digest is not a security boundary; it is what
|
|
362
|
+
lets work be grouped by branch on the other side without the name itself
|
|
363
|
+
leaving the machine. On a detached HEAD, outside a checkout, or with no
|
|
364
|
+
readable salt the key is omitted entirely rather than sent blank.
|
|
365
|
+
|
|
291
366
|
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.
|
|
292
367
|
|
|
293
368
|
## Roadmap
|
package/dist/ascendaClient.js
CHANGED
|
@@ -10,6 +10,7 @@ export class AscendaClient {
|
|
|
10
10
|
eventWriteToken: config.eventWriteToken,
|
|
11
11
|
tokenFilePath: config.tokenFilePath,
|
|
12
12
|
stateFilePath: config.stateFilePath,
|
|
13
|
+
outboxFilePath: config.outboxFilePath,
|
|
13
14
|
sessionId: config.sessionId,
|
|
14
15
|
workspaceHash: config.workspaceHash,
|
|
15
16
|
projectHash: config.projectHash
|
|
@@ -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,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,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,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,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,KAAK,CAAC,eAAe;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;IACvC,CAAC;CACF"}
|