@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 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](../). See the [Workload Telemetry Research Direction](../docs/WORKLOAD_TELEMETRY_RESEARCH_DIRECTION.md) and [Tooling Phase Alignment](../docs/TOOLING_PHASE_ALIGNMENT.md) (if present). Event mapping: [docs/CLAUDE_MAPPING.md](./docs/CLAUDE_MAPPING.md).
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
- ## Installation (Claude Code)
35
+ ## Install
34
36
 
35
- ### Prerequisites
37
+ ### Recommended: the Claude Code plugin
36
38
 
37
- - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed and working
38
- - Node.js **20+** and npm
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
- # from the repo root (workspace install + shared packages first)
45
- npm install
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
- Or:
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
- ```bash
56
- ./scripts/install-local.sh
57
- ```
50
+ ### Alternative: this adapter on its own
58
51
 
59
- Confirm the binary is on your PATH:
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
- which ascenda-claude-hook
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
- ### 2. Obtain pairing credentials
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
- **Option A — IDE extension**
61
+ ### Pair first (both routes)
71
62
 
72
- 1. Install and pair the [Ascenda extension](../ascenda-vscode-extension-telemetry/) (VS Code or Cursor — same extension).
73
- 2. Run **Ascenda: Show Status** and note `tool=…`.
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
- **Option B — pairing-sim e2e (Dev only)**
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
- cd ../ascenda-pairing-sim
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
- Use the printed `ASCENDA_TOOL_INSTALLATION_ID` and `ASCENDA_EVENT_WRITE_TOKEN`. Tokens are also written under `~/.ascenda/tokens/`.
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
- ### 3. Configure environment
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
- Add to your shell profile (`~/.zshrc`, `~/.bashrc`) or export in the terminal before starting Claude Code:
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
- export ASCENDA_API_BASE_URL="https://app-asc-dev-api-aue.azurewebsites.net" # or http://localhost:5002 / https://api.ascenda.one
93
- export ASCENDA_TOOL_INSTALLATION_ID="claude_code:<uuid>" # or cursor_mcp:… / vscode_extension:… from IDE pair
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, the CLI seeds `~/.ascenda/tokens/<toolInstallationId>` so **tool-scoped renew** can persist rotated tokens without updating your shell profile.
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
- ### 4. Register hooks in Claude Code settings
105
+ ### Register hooks manually
108
106
 
109
- Merge the hooks from [`examples/settings.local.json`](./examples/settings.local.json) into your Claude Code settings.
110
-
111
- **Project-local** (recommended while testing): create or edit `.claude/settings.local.json` in the project root:
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
- "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-hook UserPromptSubmit" }] }],
117
- "PreToolUse": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-hook PreToolUse" }] }],
118
- "PostToolUse": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-hook PostToolUse" }] }],
119
- "PreCompact": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-hook PreCompact" }] }],
120
- "PostCompact": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-hook PostCompact" }] }],
121
- "Stop": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-hook Stop" }] }],
122
- "Notification": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-hook Notification" }] }]
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
- **User-global:** merge the same `hooks` block into Claude Code’s user settings file (location depends on Claude Code version; often under `~/.claude/`).
127
+ ### Verify
128
128
 
129
- If `ascenda-claude-hook` is not on PATH inside Claude Code’s environment, use an absolute path:
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
- ```text
132
- /Users/<you>/.nvm/versions/node/<ver>/bin/ascenda-claude-hook UserPromptSubmit
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
- ### 5. Verify
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
- # Smoke-test one hook with sample payload
139
- npm run test:sample
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
- Then start Claude Code in a project with hooks configured, submit a prompt / run a tool, and confirm events appear on the Ascenda backend (or that the hook exits `0`).
144
-
145
- On auth failure the CLI exits `3` (re-pair). On missing consent it exits `2` (renew consent in the Ascenda app).
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 event. Australian-hosted backend with transparent consent. Not a medical device — workload self-awareness only. See [research direction §7–8](../docs/WORKLOAD_TELEMETRY_RESEARCH_DIRECTION.md).
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-hook SessionStart" }] }],
4
- "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-hook UserPromptSubmit" }] }],
5
- "PreToolUse": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-hook PreToolUse" }] }],
6
- "PostToolUse": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-hook PostToolUse" }] }],
7
- "PreCompact": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-hook PreCompact" }] }],
8
- "PostCompact": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-hook PostCompact" }] }],
9
- "Stop": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-hook Stop" }] }],
10
- "Notification": [{ "hooks": [{ "type": "command", "command": "ascenda-claude-hook Notification" }] }]
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
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "publishConfig": { "access": "public" },
3
3
  "name": "@ascenda-one/claude-code-hooks",
4
- "version": "0.1.3",
4
+ "version": "0.1.4",
5
5
  "description": "Claude Code hooks adapter for Ascenda AI workload telemetry.",
6
6
  "repository": {
7
7
  "type": "git",