@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 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 --help
56
+ npx @ascenda-one/claude-code-hooks setup
57
57
  ```
58
58
 
59
- Then wire the events yourself — see [Register hooks manually](#register-hooks-manually).
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
- ### Pair first (both routes)
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
- Neither route sends anything until this machine is paired:
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
- > **This variable is required, not optional.** Without it every hook
83
- > invocation exits with `Missing ASCENDA_TOOL_INSTALLATION_ID`. The adapter
84
- > refuses to guess rather than silently mint a second, unpaired identity that
85
- > would fragment your telemetry across two installations.
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, the token's presence and age, the last
141
- recorded send outcome, and the result of a live round trip against the real
142
- ingest endpoint. It is the first thing to run when the Ascenda app shows a
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
@@ -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"}