@ascenda-one/claude-code-hooks 0.1.3 → 0.1.4
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 +82 -65
- package/examples/settings.local.json +8 -8
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,7 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
Claude Code hooks adapter for Ascenda AI workload telemetry.
|
|
4
4
|
|
|
5
|
-
Part of [ai-engineer-tools](../).
|
|
5
|
+
Part of [ai-engineer-tools](../). For what these measurements do and do not
|
|
6
|
+
establish, see [What this measures](../#what-this-measures-and-what-that-does-not-yet-prove).
|
|
7
|
+
Event mapping: [docs/CLAUDE_MAPPING.md](./docs/CLAUDE_MAPPING.md).
|
|
6
8
|
|
|
7
9
|
## Role in workload detection (Phase 1)
|
|
8
10
|
|
|
@@ -30,119 +32,131 @@ Claude Code hook adapter
|
|
|
30
32
|
|
|
31
33
|
Same loose-coupled pairing model as the VS Code and Cursor extensions. See [TOOL_PAIRING_API_REFERENCE.md](../api-docs/TOOL_PAIRING_API_REFERENCE.md).
|
|
32
34
|
|
|
33
|
-
##
|
|
35
|
+
## Install
|
|
34
36
|
|
|
35
|
-
###
|
|
37
|
+
### Recommended: the Claude Code plugin
|
|
36
38
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
- A paired Ascenda `toolInstallationId` + `eventWriteToken` (from VS Code/Cursor extension or [pairing-sim `e2e`](../ascenda-pairing-sim/))
|
|
40
|
-
|
|
41
|
-
### 1. Build and install the hook CLI
|
|
39
|
+
One command installs this adapter, the work-signals skill, and the MCP server
|
|
40
|
+
together — already wired to every lifecycle event, no settings file to edit:
|
|
42
41
|
|
|
43
42
|
```bash
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
npm run build:shared
|
|
47
|
-
|
|
48
|
-
cd ascenda-claude-code-hooks
|
|
49
|
-
npm run build
|
|
50
|
-
npm link
|
|
43
|
+
claude plugin marketplace add ascendaone-com/ai-engineer-tools
|
|
44
|
+
claude plugin install ascenda@ascenda-one
|
|
51
45
|
```
|
|
52
46
|
|
|
53
|
-
|
|
47
|
+
From inside a session, use `/plugin marketplace add …` then `/plugin install …`.
|
|
48
|
+
See [ascenda-agent-skills](../ascenda-agent-skills/) for what the bundle holds.
|
|
54
49
|
|
|
55
|
-
|
|
56
|
-
./scripts/install-local.sh
|
|
57
|
-
```
|
|
50
|
+
### Alternative: this adapter on its own
|
|
58
51
|
|
|
59
|
-
|
|
52
|
+
If you want the deterministic hooks without the skill or MCP server, the
|
|
53
|
+
published package runs with no clone and no build:
|
|
60
54
|
|
|
61
55
|
```bash
|
|
62
|
-
|
|
63
|
-
ascenda-claude-hook # prints usage if no hook name is passed
|
|
56
|
+
npx @ascenda-one/claude-code-hooks --help
|
|
64
57
|
```
|
|
65
58
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
This package does **not** show a QR code. Pair first, then export the token:
|
|
59
|
+
Then wire the events yourself — see [Register hooks manually](#register-hooks-manually).
|
|
69
60
|
|
|
70
|
-
|
|
61
|
+
### Pair first (both routes)
|
|
71
62
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
3. Copy `toolInstallationId` and `eventWriteToken` from extension storage, or run pairing-sim `e2e` and use its printed values.
|
|
63
|
+
Neither route sends anything until this machine is paired. This package shows
|
|
64
|
+
no QR code of its own; it reuses a pairing made elsewhere.
|
|
75
65
|
|
|
76
|
-
|
|
66
|
+
1. Install and pair the [Ascenda extension](../ascenda-vscode-extension-telemetry/)
|
|
67
|
+
in VS Code or Cursor, then run **Ascenda: Connect App**.
|
|
68
|
+
2. Run **Ascenda: Show Status** and copy the tool installation id.
|
|
69
|
+
3. Export it where Claude Code will see it:
|
|
77
70
|
|
|
78
71
|
```bash
|
|
79
|
-
|
|
80
|
-
# local.devauth.env configured (gitignored DevAuth tokens)
|
|
81
|
-
npm run build
|
|
82
|
-
node dist/cli.js e2e --tool-type claude_code
|
|
72
|
+
export ASCENDA_TOOL_INSTALLATION_ID="claude_code:<uuid>" # or the cursor_mcp:… / vscode_extension:… id you already have
|
|
83
73
|
```
|
|
84
74
|
|
|
85
|
-
|
|
75
|
+
Add that to your shell profile (`~/.zshrc`, `~/.bashrc`) and restart Claude
|
|
76
|
+
Code. The write token is read from `~/.ascenda/tokens/`, written at pairing
|
|
77
|
+
time — you do not copy it separately.
|
|
86
78
|
|
|
87
|
-
|
|
79
|
+
> **This variable is required, not optional.** Without it every hook
|
|
80
|
+
> invocation exits with `Missing ASCENDA_TOOL_INSTALLATION_ID`. The adapter
|
|
81
|
+
> refuses to guess rather than silently mint a second, unpaired identity that
|
|
82
|
+
> would fragment your telemetry across two installations.
|
|
88
83
|
|
|
89
|
-
|
|
84
|
+
On a Dev backend with no phone, [pairing-sim](../ascenda-pairing-sim/) stands in
|
|
85
|
+
for the app:
|
|
90
86
|
|
|
91
87
|
```bash
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
export ASCENDA_EVENT_WRITE_TOKEN="<eventWriteToken>"
|
|
88
|
+
cd ../ascenda-pairing-sim && npm run build
|
|
89
|
+
node dist/cli.js e2e --tool-type claude_code
|
|
95
90
|
```
|
|
96
91
|
|
|
97
|
-
Optional:
|
|
92
|
+
Optional environment:
|
|
98
93
|
|
|
99
94
|
| Variable | Purpose |
|
|
100
95
|
| --- | --- |
|
|
96
|
+
| `ASCENDA_API_BASE_URL` | Backend to send to. Defaults to `https://api.ascenda.one`; use `http://localhost:5002` or the Azure Dev host for development |
|
|
97
|
+
| `ASCENDA_EVENT_WRITE_TOKEN` | Only if you have no prior pairing to reuse — normally the token file supplies this |
|
|
101
98
|
| `ASCENDA_EVENT_WRITE_TOKEN_FILE` | Override token file path (default `~/.ascenda/tokens/<toolInstallationId>`) |
|
|
102
99
|
| `ASCENDA_SESSION_ID` | Stable session id across hooks |
|
|
103
100
|
| `ASCENDA_WORKSPACE_HASH` | Opaque workspace hash if you set one |
|
|
104
101
|
|
|
105
|
-
On first run
|
|
102
|
+
On first run the CLI seeds `~/.ascenda/tokens/<toolInstallationId>` so
|
|
103
|
+
**tool-scoped renew** can persist rotated tokens without you editing anything.
|
|
106
104
|
|
|
107
|
-
###
|
|
105
|
+
### Register hooks manually
|
|
108
106
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
107
|
+
The plugin does this for you — this section is only for the standalone route.
|
|
108
|
+
Merge [`examples/settings.local.json`](./examples/settings.local.json) into
|
|
109
|
+
`.claude/settings.local.json` in a project, or into Claude Code's user settings
|
|
110
|
+
for machine-wide coverage:
|
|
112
111
|
|
|
113
112
|
```json
|
|
114
113
|
{
|
|
115
114
|
"hooks": {
|
|
116
|
-
"
|
|
117
|
-
"
|
|
118
|
-
"
|
|
119
|
-
"
|
|
120
|
-
"
|
|
121
|
-
"
|
|
122
|
-
"
|
|
115
|
+
"SessionStart": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SessionStart" }] }],
|
|
116
|
+
"UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks UserPromptSubmit" }] }],
|
|
117
|
+
"PreToolUse": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PreToolUse" }] }],
|
|
118
|
+
"PostToolUse": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostToolUse" }] }],
|
|
119
|
+
"PreCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PreCompact" }] }],
|
|
120
|
+
"PostCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostCompact" }] }],
|
|
121
|
+
"Stop": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Stop" }] }],
|
|
122
|
+
"Notification": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Notification" }] }]
|
|
123
123
|
}
|
|
124
124
|
}
|
|
125
125
|
```
|
|
126
126
|
|
|
127
|
-
|
|
127
|
+
### Verify
|
|
128
128
|
|
|
129
|
-
|
|
129
|
+
Start Claude Code in a project with hooks configured, submit a prompt or run a
|
|
130
|
+
tool, and confirm events reach the backend (or simply that the hook exits `0`).
|
|
130
131
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
132
|
+
Exit codes: `3` on auth failure (re-pair), `2` on missing consent (renew in the
|
|
133
|
+
Ascenda app). A telemetry failure never blocks your turn.
|
|
134
|
+
|
|
135
|
+
## Build from source
|
|
134
136
|
|
|
135
|
-
|
|
137
|
+
Not needed to use this — both routes above ship prebuilt. It is here because
|
|
138
|
+
"read what runs on your machine" is a fair thing to want from a telemetry tool.
|
|
136
139
|
|
|
137
140
|
```bash
|
|
138
|
-
#
|
|
139
|
-
npm
|
|
141
|
+
# from the repo root (workspace install + shared packages first)
|
|
142
|
+
npm install
|
|
143
|
+
npm run build:shared
|
|
144
|
+
|
|
145
|
+
cd ascenda-claude-code-hooks
|
|
146
|
+
npm run build
|
|
147
|
+
npm link # or ./scripts/install-local.sh
|
|
148
|
+
|
|
149
|
+
which ascenda-claude-hook
|
|
150
|
+
ascenda-claude-hook # prints usage when passed no hook name
|
|
151
|
+
|
|
152
|
+
npm run test:sample # pipes a sample PostToolUse payload through the CLI
|
|
140
153
|
npm run test:compact
|
|
141
154
|
```
|
|
142
155
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
156
|
+
A local build exposes the binary as `ascenda-claude-hook` — substitute it for
|
|
157
|
+
`npx -y @ascenda-one/claude-code-hooks` in the hook config above. If it is not
|
|
158
|
+
on Claude Code's PATH, use an absolute path such as
|
|
159
|
+
`/Users/<you>/.nvm/versions/node/<ver>/bin/ascenda-claude-hook`.
|
|
146
160
|
|
|
147
161
|
## Supported Claude hook events
|
|
148
162
|
|
|
@@ -188,4 +202,7 @@ Correction detection uses local pattern matching on prompt text in the hook proc
|
|
|
188
202
|
|
|
189
203
|
## Compliance
|
|
190
204
|
|
|
191
|
-
`consentScope: ide_telemetry` and `provenance: ai_work_telemetry` on every
|
|
205
|
+
`consentScope: ide_telemetry` and `provenance: ai_work_telemetry` on every
|
|
206
|
+
event. Australian-hosted backend. Not a medical device — workload
|
|
207
|
+
self-awareness only, no diagnosis, no clinical claim. Consent is revocable from
|
|
208
|
+
the app at any time; after revocation ingest returns `401`.
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"hooks": {
|
|
3
|
-
"SessionStart": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-
|
|
4
|
-
"UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-
|
|
5
|
-
"PreToolUse": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-
|
|
6
|
-
"PostToolUse": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-
|
|
7
|
-
"PreCompact": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-
|
|
8
|
-
"PostCompact": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-
|
|
9
|
-
"Stop": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-
|
|
10
|
-
"Notification": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-
|
|
3
|
+
"SessionStart": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks SessionStart" }] }],
|
|
4
|
+
"UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks UserPromptSubmit" }] }],
|
|
5
|
+
"PreToolUse": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PreToolUse" }] }],
|
|
6
|
+
"PostToolUse": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostToolUse" }] }],
|
|
7
|
+
"PreCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PreCompact" }] }],
|
|
8
|
+
"PostCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks PostCompact" }] }],
|
|
9
|
+
"Stop": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Stop" }] }],
|
|
10
|
+
"Notification": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/claude-code-hooks Notification" }] }]
|
|
11
11
|
}
|
|
12
12
|
}
|
package/package.json
CHANGED