@ascenda-one/claude-code-hooks 0.1.14 → 0.1.16
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 +134 -11
- package/dist/ascendaClient.js +1 -0
- package/dist/ascendaClient.js.map +1 -1
- package/dist/cli.js +2622 -372
- package/dist/cli.js.map +1 -1
- package/dist/config.js +68 -7
- package/dist/config.js.map +1 -1
- package/dist/mapClaudeEvent.js +196 -11
- package/dist/mapClaudeEvent.js.map +1 -1
- package/dist/paths.js +18 -0
- package/dist/paths.js.map +1 -0
- package/dist/setup.js +375 -0
- package/dist/setup.js.map +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -53,14 +53,61 @@ If you want the deterministic hooks without the skill or MCP server, the
|
|
|
53
53
|
published package runs with no clone and no build:
|
|
54
54
|
|
|
55
55
|
```bash
|
|
56
|
-
npx @ascenda-one/claude-code-hooks
|
|
56
|
+
npx @ascenda-one/claude-code-hooks setup
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
|
|
59
|
+
This pairs (printing a 6-digit code to confirm in the Ascenda app), installs a
|
|
60
|
+
self-contained hook bundle to `~/.ascenda/bin`, writes
|
|
61
|
+
`~/.ascenda/credentials.json`, and registers the hooks in this project's
|
|
62
|
+
`.claude/settings.local.json`. Restart Claude Code and events flow — no shell
|
|
63
|
+
exports, no settings file to hand-edit.
|
|
60
64
|
|
|
61
|
-
|
|
65
|
+
```bash
|
|
66
|
+
npx @ascenda-one/claude-code-hooks status # exits non-zero if anything is unwired
|
|
67
|
+
npx @ascenda-one/claude-code-hooks uninstall # removes hooks and the binary
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
| Option | |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| `--api-base-url <url>` | ingest host (default `https://api.ascenda.one`) |
|
|
73
|
+
| `--local [port]` | shorthand for a local [dev server](../ascenda-dev-server/) (default `4477`) |
|
|
74
|
+
| `--tool-installation-id <id>` / `--token <t>` | reuse an existing pairing instead of creating one |
|
|
75
|
+
| `--scope project\|user` | register in this project (default) or in `~/.claude/settings.json` |
|
|
76
|
+
| `--project-dir <path>` | project root for `--scope project` (default cwd) |
|
|
77
|
+
| `--dry-run` | print what would change, write nothing |
|
|
78
|
+
|
|
79
|
+
From a clone, `./scripts/setup-local.sh` builds the workspace, starts the dev
|
|
80
|
+
server detached, and runs the same `setup --local` — no backend, no phone, no
|
|
81
|
+
DevAuth. Stop it with `./scripts/setup-local.sh --stop`. See
|
|
82
|
+
[TESTING.md](../TESTING.md).
|
|
83
|
+
|
|
84
|
+
#### What setup writes
|
|
85
|
+
|
|
86
|
+
| Path | |
|
|
87
|
+
| --- | --- |
|
|
88
|
+
| `~/.ascenda/bin/ascenda-claude-hook` | the self-contained bundle — no `npm -g`, no sudo, no PATH edit |
|
|
89
|
+
| `~/.ascenda/credentials.json` | `apiBaseUrl` + `toolInstallationId`, `0600` |
|
|
90
|
+
| `~/.ascenda/tokens/<id>` | the event write token, `0600`, rotated in place on renew |
|
|
91
|
+
| `.claude/settings.local.json` | one hook entry per lifecycle event, `timeout: 5` |
|
|
92
|
+
|
|
93
|
+
Registration is idempotent and marker-keyed: re-running replaces our entries
|
|
94
|
+
rather than appending, hooks belonging to anyone else are left alone, and the
|
|
95
|
+
file is backed up to `.ascenda-backup` before the first write. Settings that
|
|
96
|
+
are not valid JSON abort the run rather than being overwritten.
|
|
97
|
+
|
|
98
|
+
Hooks then need **no environment at all**: the command pins the absolute path
|
|
99
|
+
of the Node that ran setup, and configuration comes from the credentials file.
|
|
100
|
+
Claude Code spawns hooks with whatever environment it was launched from, so
|
|
101
|
+
anything depending on shell exports stops working the moment the editor is
|
|
102
|
+
opened from a launcher rather than a terminal. The variables below still
|
|
103
|
+
override the file when set.
|
|
104
|
+
|
|
105
|
+
`status` also flags hook entries pointing at a binary that no longer exists —
|
|
106
|
+
those fail silently on every event otherwise.
|
|
107
|
+
|
|
108
|
+
### Pairing by hand (if you skip `setup`)
|
|
62
109
|
|
|
63
|
-
|
|
110
|
+
`setup` pairs for you. To pair this machine directly instead:
|
|
64
111
|
|
|
65
112
|
```bash
|
|
66
113
|
npx -y @ascenda-one/claude-code-hooks pair
|
|
@@ -79,10 +126,14 @@ Code. The token itself is never copied around — every CLI tool reads it from
|
|
|
79
126
|
the file `pair` wrote. (The editor extension's pairing cannot be reused here:
|
|
80
127
|
its token lives in the editor's private secret storage.)
|
|
81
128
|
|
|
82
|
-
> **
|
|
83
|
-
>
|
|
84
|
-
>
|
|
85
|
-
>
|
|
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.
|
|
86
137
|
|
|
87
138
|
On a Dev backend with no phone, [pairing-sim](../ascenda-pairing-sim/) stands in
|
|
88
139
|
for the app:
|
|
@@ -103,6 +154,8 @@ Optional environment:
|
|
|
103
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) |
|
|
104
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 |
|
|
105
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" |
|
|
106
159
|
| `ASCENDA_DISABLE_FAILURE_NOTICE` | `true` silences the one-time in-session notice about a collector that has stopped delivering |
|
|
107
160
|
|
|
108
161
|
On first run the CLI seeds `~/.ascenda/tokens/<toolInstallationId>` so
|
|
@@ -137,9 +190,10 @@ for machine-wide coverage:
|
|
|
137
190
|
npx -y @ascenda-one/claude-code-hooks doctor
|
|
138
191
|
```
|
|
139
192
|
|
|
140
|
-
`doctor` prints the installation id
|
|
141
|
-
|
|
142
|
-
|
|
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
|
|
143
197
|
connected tool that is not producing data.
|
|
144
198
|
|
|
145
199
|
A telemetry failure never blocks your turn: **every hook invocation exits `0`**,
|
|
@@ -180,6 +234,64 @@ call, and never repeats until the collector has recovered and failed again.
|
|
|
180
234
|
distinguish a dead token from a night's sleep, because both are "no events".
|
|
181
235
|
Only the collector knows it tried and was refused.
|
|
182
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
|
+
|
|
183
295
|
## Build from source
|
|
184
296
|
|
|
185
297
|
Not needed to use this — both routes above ship prebuilt. It is here because
|
|
@@ -240,6 +352,17 @@ Notification -> (skipped — no catalog event)
|
|
|
240
352
|
|
|
241
353
|
Metadata-only telemetry. Does not send raw prompts, responses, code, file names, repository names, branch names, or terminal output.
|
|
242
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
|
+
|
|
243
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.
|
|
244
367
|
|
|
245
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"}
|