@ascenda-one/claude-code-hooks 0.1.27 → 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 +98 -11
- package/dist/ascendaClient.js +5 -0
- package/dist/ascendaClient.js.map +1 -1
- package/dist/cli.js +642 -246
- package/dist/cli.js.map +1 -1
- package/dist/config.js +34 -1
- package/dist/config.js.map +1 -1
- package/dist/mapClaudeEvent.js +46 -2
- package/dist/mapClaudeEvent.js.map +1 -1
- package/dist/paths.js +20 -1
- package/dist/paths.js.map +1 -1
- package/dist/setup.js +176 -37
- package/dist/setup.js.map +1 -1
- package/dist/types.js +11 -1
- package/dist/types.js.map +1 -1
- package/examples/settings.local.json +10 -9
- package/package.json +2 -2
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
|
package/dist/ascendaClient.js
CHANGED
|
@@ -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"}
|