@ascenda-one/claude-code-hooks 0.1.26 → 0.1.28

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
@@ -72,6 +72,7 @@ npx @ascenda-one/claude-code-hooks uninstall # removes hooks and the binary
72
72
  | `--api-base-url <url>` | ingest host (default `https://api.ascenda.one`) |
73
73
  | `--local [port]` | shorthand for a local [dev server](../ascenda-dev-server/) (default `4477`) |
74
74
  | `--tool-installation-id <id>` / `--token <t>` | reuse an existing pairing instead of creating one |
75
+ | `--no-pair` | install the local half only: hooks work, nothing is sent |
75
76
  | `--scope project\|user` | register in this project (default) or in `~/.claude/settings.json` |
76
77
  | `--project-dir <path>` | project root for `--scope project` (default cwd) |
77
78
  | `--dry-run` | print what would change, write nothing |
@@ -86,7 +87,7 @@ DevAuth. Stop it with `./scripts/setup-local.sh --stop`. See
86
87
  | Path | |
87
88
  | --- | --- |
88
89
  | `~/.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/credentials.json` | `apiBaseUrl` + `toolInstallationId`, `0600` (plus `localOnly` on an install with no pairing) |
90
91
  | `~/.ascenda/tokens/<id>` | the event write token, `0600`, rotated in place on renew |
91
92
  | `.claude/settings.local.json` | one hook entry per lifecycle event, `timeout: 5` |
92
93
 
@@ -103,7 +104,56 @@ opened from a launcher rather than a terminal. The variables below still
103
104
  override the file when set.
104
105
 
105
106
  `status` also flags hook entries pointing at a binary that no longer exists —
106
- those fail silently on every event otherwise.
107
+ those fail silently on every event otherwise. It checks one scope, defaulting
108
+ to `project` like `setup`; if it finds nothing there it looks in the other one
109
+ and says where the hooks actually are. User settings apply in every project, so
110
+ hooks found there answer a project-scope check.
111
+
112
+ #### Installing without a pairing
113
+
114
+ `--no-pair` installs the hooks and stops before pairing. A `setup` that tried
115
+ to pair and couldn't finish — the backend unreachable, nobody at the keyboard
116
+ to confirm the code, the session expired — lands in the same place instead of
117
+ failing. The install completes either way, and the summary names which half is
118
+ running:
119
+
120
+ ```text
121
+ Installed, not paired.
122
+ active the session prompts, and the live signal to a socket on this machine
123
+ inactive delivery to https://api.ascenda.one. Nothing is sent, and nothing is queued for later.
124
+ pair later npx @ascenda-one/claude-code-hooks pair
125
+ ```
126
+
127
+ Two things work with no pairing at all, which is why this mode exists. The
128
+ session prompts are composed locally in the hook process. The live signal goes
129
+ to a socket on your own machine, so a listener there sees an agent working the
130
+ moment it starts. Neither owes anything to a backend, and gating the install on
131
+ one kept them from the people still setting Ascenda up.
132
+
133
+ What that install holds: the hook binary, the registered events, and a
134
+ credentials file with an installation id, `localOnly: true` and `installedAt`.
135
+ No `pairedAt` and no token — nothing here fabricates a credential it doesn't
136
+ have. The id is the part that matters later. `pair` claims that same id, so the
137
+ hooks already registered in your settings file end up paired; the flag is
138
+ dropped and `pairedAt` takes its place.
139
+
140
+ Delivery is a deliberate no-op until then. Nothing is sent, nothing is queued,
141
+ and the send journal stays empty rather than recording an outage on every hook
142
+ event. An absent token on an install that *was* paired is a different matter:
143
+ that's a revoked or deleted credential, and it goes on being reported. `status`
144
+ and `doctor` both distinguish the two:
145
+
146
+ ```text
147
+ pairing claude_code:… (not paired, installed 2026-09-23T05:13:40.907Z)
148
+ token — none until this install is paired
149
+ delivery inactive — nothing is sent, and nothing is queued for later
150
+ local features active — the session prompts and the live socket signal need no pairing
151
+ hooks 10/10 registered in ~/.claude/settings.json
152
+ ```
153
+
154
+ `uninstall` removes an unpaired install the same way, and says there is no
155
+ token to revoke. It leaves any other agent's pairing in the credentials file
156
+ where it is.
107
157
 
108
158
  ### Pairing by hand (if you skip `setup`)
109
159
 
@@ -121,6 +171,10 @@ never copied around — every CLI tool reads it from the file `pair` wrote. (The
121
171
  editor extension's pairing cannot be reused here: its token lives in the
122
172
  editor's private secret storage.)
123
173
 
174
+ Run on a machine `setup` has already touched, `pair` attaches to the
175
+ installation that file names instead of minting a second one, and pairs against
176
+ the host recorded there. That's what finishes a `--no-pair` install.
177
+
124
178
  `--tool-type <type>` pairs something else CLI-shaped that has no `setup` of its
125
179
  own. An explicit type always mints its own id: naming a different tool is
126
180
  pairing a second one, not re-pairing this one, and reusing the id there would
@@ -163,6 +217,31 @@ Optional environment:
163
217
  On first run the CLI seeds `~/.ascenda/tokens/<toolInstallationId>` so
164
218
  **tool-scoped renew** can persist rotated tokens without you editing anything.
165
219
 
220
+ ### Cloud sessions
221
+
222
+ A hosted Claude Code session (Claude Code on the web, or one it spawns) runs in
223
+ a fresh container every time. Its transcript never reaches your machine, so a
224
+ history import can't see it and these hooks are its only record. Every event
225
+ carries `metadata.runtime`: `cloud` when Claude Code sets `CLAUDE_CODE_REMOTE`,
226
+ `local` otherwise.
227
+
228
+ Nothing under `~/.ascenda` survives a session there, so everything the hooks
229
+ need comes from the environment's settings:
230
+
231
+ | Variable | Why |
232
+ | --- | --- |
233
+ | `ASCENDA_TOOL_INSTALLATION_ID` | The installation to send as. Pair one just for cloud sessions (run `pair` inside one); don't reuse your laptop's pairing, which re-pairing would rotate. |
234
+ | `ASCENDA_EVENT_WRITE_TOKEN` | Its write token. |
235
+ | the salt, `~/.ascenda/salt` | Without it every session mints a new one and one repository turns into a new project hash every time. Have whatever launches the hooks write a fixed value there first. Your laptop's value makes cloud and local hashes match. |
236
+
237
+ The environment's network access must also allow the Ascenda API host.
238
+
239
+ **Tokens never rotate in a cloud session.** Renewal revokes the previous
240
+ token, and the replacement would die with the container, taking the
241
+ environment's copy down for every later session. So the hooks record a
242
+ rejected token as a failed send and stop there. Tokens last 30 days; when one runs out, pair again
243
+ and replace the token in the environment.
244
+
166
245
  ### Register hooks manually
167
246
 
168
247
  The plugin does this for you — this section is only for the standalone route.
@@ -173,19 +252,23 @@ for machine-wide coverage:
173
252
  ```json
174
253
  {
175
254
  "hooks": {
176
- "SessionStart": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SessionStart" }] }],
177
- "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks UserPromptSubmit" }] }],
178
- "PreToolUse": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PreToolUse" }] }],
179
- "PostToolUse": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostToolUse" }] }],
180
- "PostToolUseFailure": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostToolUseFailure" }] }],
181
- "PreCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PreCompact" }] }],
182
- "PostCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostCompact" }] }],
183
- "Stop": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Stop" }] }],
184
- "Notification": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Notification" }] }]
255
+ "SessionStart": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SessionStart", "timeout": 5 }] }],
256
+ "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks UserPromptSubmit", "timeout": 5 }] }],
257
+ "PreToolUse": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PreToolUse", "timeout": 5 }] }],
258
+ "PostToolUse": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostToolUse", "timeout": 5 }] }],
259
+ "PostToolUseFailure": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostToolUseFailure", "timeout": 5 }] }],
260
+ "PreCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PreCompact", "timeout": 5 }] }],
261
+ "PostCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostCompact", "timeout": 5 }] }],
262
+ "Stop": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Stop", "timeout": 5 }] }],
263
+ "Notification": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Notification", "timeout": 5 }] }],
264
+ "SessionEnd": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SessionEnd", "timeout": 5 }] }]
185
265
  }
186
266
  }
187
267
  ```
188
268
 
269
+ Keep the timeouts. Without one Claude Code gives a hook up to 600s, and all
270
+ SessionEnd hooks share 1.5s between them.
271
+
189
272
  ### Verify
190
273
 
191
274
  ```bash
@@ -323,6 +406,7 @@ on Claude Code's PATH, use an absolute path such as
323
406
  ## Supported Claude hook events
324
407
 
325
408
  ```text
409
+ SessionStart
326
410
  UserPromptSubmit
327
411
  PreToolUse
328
412
  PostToolUse
@@ -331,6 +415,7 @@ PreCompact
331
415
  PostCompact
332
416
  Stop
333
417
  Notification
418
+ SessionEnd
334
419
  ```
335
420
 
336
421
  ## Ascenda event mappings
@@ -338,6 +423,7 @@ Notification
338
423
  Full mapping: [docs/CLAUDE_MAPPING.md](./docs/CLAUDE_MAPPING.md). Catalog-only event types (no aliases).
339
424
 
340
425
  ```text
426
+ SessionStart -> create_focus_session (startup and resume; clear and compact are skipped)
341
427
  UserPromptSubmit -> ai_prompt_submitted / ai_correction_prompt
342
428
  PreToolUse -> ai_tool_call_started
343
429
  PostToolUse Edit -> ai_file_edit
@@ -348,6 +434,7 @@ PreCompact -> context_compression_manual / context_compression_auto
348
434
  PostCompact -> context_pressure_high
349
435
  Stop -> ai_turn_completed (every turn), agent_loop_long (long only)
350
436
  Notification -> supervision_interruption (interruptionKind only, never the message)
437
+ SessionEnd -> recovery_offline_period (activity session_ended, sessionEndReason)
351
438
  ```
352
439
 
353
440
  ## Privacy defaults
@@ -11,6 +11,7 @@ export class AscendaClient {
11
11
  tokenFilePath: config.tokenFilePath,
12
12
  stateFilePath: config.stateFilePath,
13
13
  outboxFilePath: config.outboxFilePath,
14
+ renewToken: config.renewToken,
14
15
  sessionId: config.sessionId,
15
16
  workspaceHash: config.workspaceHash,
16
17
  projectHash: config.projectHash
@@ -23,6 +24,10 @@ export class AscendaClient {
23
24
  async send(mapped) {
24
25
  return this.sender.send(mapped);
25
26
  }
27
+ /** Outbox only, no network. See {@link AscendaEventSender.queue}. */
28
+ queue(mapped) {
29
+ return this.sender.queue(mapped);
30
+ }
26
31
  async renewEventToken() {
27
32
  return this.sender.renewEventToken();
28
33
  }
@@ -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,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,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"}