teallarson · Oct 15, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 14, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -5,15 +5,27 @@ For agents editing **arcade-plugin** itself.
 Client-specific files are generated. Edit the source, run `npm run generate`,
 then `npm run verify` (it fails if a generated file was edited by hand).
 [ARCHITECTURE.md](ARCHITECTURE.md) lists the sources; `.gitattributes` lists
-every fully generated file. `skills/try-arcade/SKILL.md` and
-`agents/arcade-operator.agent.md` are hand-written except
-for a marked rules block.
+every fully generated file. `skills/try-arcade/SKILL.md`,
+`agents/arcade-operator.agent.md`, and `docs/telemetry.md` are hand-written
+except for a marked generated block (the event tables in docs/telemetry.md
+come from `hooks/telemetry-contract.mjs`; never edit inside those markers).
 
 - Routing rules: edit `hooks/routing-guidance.mjs`, never the rules text in
   the Cursor rule, arcade-operator, or try-arcade.
 - Hooks: add a hook or a client in `hooks/hook-hosts.mjs`, never in a
   `hooks.json`. A new client also needs its expected output in
   `test/hooks.test.mjs`.
+- Telemetry: `hooks/telemetry-contract.mjs` defines every event, property,
+  and allowed value; change them there only. Client-specific hook input mapping
+  lives only in `hooks/telemetry-adapters/<host>.mjs`. Wire a client through
+  `HOSTS.telemetry` in `hooks/hook-hosts.mjs` (generated manifests follow
+  that source). `telemetry.mjs` prints nothing; only `telemetry-send.mjs` may
+  touch the network (a test enforces both). `TELEMETRY_ENABLED` in
+  `hooks/telemetry-config.mjs` stays `false` without separate approval; while
+  false, `npm run generate` writes no telemetry hooks. `docs/telemetry.md`
+  documents the event contract, privacy, opt-outs, and approval before enabling.
+  `scripts/telemetry-docs.mjs` generates its event tables from the contract;
+  keep its tests in `test/telemetry-docs.test.mjs`.
 - Codex hooks are blocked upstream ([docs/install/codex.md](docs/install/codex.md)).
   Don't remove the root `$schema` to force them; that breaks Agent Plugins
   conformance.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -10,6 +10,7 @@ edited by hand. The package ships no credentials.
 | `plugin.json`, `mcp.json`, `VERSION` | identity, gateway URL, version, Codex listing metadata |
 | `hooks/routing-guidance.mjs` | the routing rules, as sentences |
 | `hooks/hook-hosts.mjs` | which hook script runs on which event in which client |
+| `hooks/telemetry-contract.mjs` | the telemetry event contract; also generates the event tables in docs/telemetry.md |
 | `agents/arcade-operator.agent.md` | the operator, outside its generated rules block |
 | `skills/` | the skills, outside the generated rules block in try-arcade |
 
@@ -85,6 +86,12 @@ success or narrating tool internals.
 
 The Arcade MCP server is the canonical place to record request, authentication,
 tool-discovery, tool-call, and completion outcomes. This package does not ask a
-model to self-report tokens, turns, or success, and it ships no telemetry hook.
-If a host-specific hook later adds supplemental signals, it must be explicit,
-opt-in, and documented as non-portable.
+model to self-report tokens, turns, or success.
+
+Optional client hooks in `hooks/telemetry-adapters/` can send supplemental,
+scoped usage events when `TELEMETRY_ENABLED` is `true` and the user has not
+opted out. **This build keeps `TELEMETRY_ENABLED` false**, so no telemetry
+hooks are generated and nothing is sent. See [docs/telemetry.md](docs/telemetry.md)
+for the contract, opt-outs, local state, and the separate approval required
+before collection can be enabled. Gateway telemetry remains authoritative;
+plugin events do not establish task success.
diff --git a/README.md b/README.md
@@ -69,6 +69,17 @@ anything is sent, created, or deleted.
 - Privacy: tasks run through Arcade's hosted gateway and the apps you
   connect — [privacy policy](https://www.arcade.dev/privacy-policy).
 
+## Plugin usage events (off in this build)
+
+Claude Code and Copilot CLI include telemetry adapters, but **`TELEMETRY_ENABLED`
+is `false`**: this package sends no usage events and generates no telemetry
+hooks in client manifests. [docs/telemetry.md](docs/telemetry.md) describes
+the event contract, what would be stored locally when enabled, opt-outs, and
+the separate approval required before collection can be enabled. The Arcade MCP
+gateway remains the canonical source for request and tool-call telemetry.
+Adapter behavior is covered by in-process tests;
+see [docs/telemetry.md](docs/telemetry.md) for what CI does and does not exercise.
+
 ## Develop
 
 Agents editing this repo should read [AGENTS.md](AGENTS.md).

diff --git a/docs/install/claude-code.md b/docs/install/claude-code.md
@@ -37,6 +37,18 @@ If your host has other Arcade MCP connectors too, Claude may pick the wrong one
 connected and prefer disabling other Arcade connectors while testing this
 plugin.
 
+## Telemetry
+
+Telemetry is **off** in this build (`TELEMETRY_ENABLED` is `false`): no usage
+events are sent and generated manifests include no telemetry hooks. When
+telemetry is enabled, the adapter in `hooks/telemetry-adapters/claude-code.mjs`
+classifies prompts, records `PreToolUse` on the plugin and claude.ai Arcade
+prefixes, and stores scope under `CLAUDE_PLUGIN_DATA`. Opt out with
+`ARCADE_PLUGIN_TELEMETRY=0`, `DISABLE_TELEMETRY`, or
+`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`. See
+[telemetry.md](../telemetry.md) and
+[what CI exercises](../telemetry.md#what-ci-exercises).
+
 ## First steps
 
 - "What's on my calendar tomorrow?"

diff --git a/docs/install/copilot.md b/docs/install/copilot.md
@@ -26,6 +26,20 @@ from config files, so there's no per-prompt reminder here. VS Code reads the
 same file but can't run Agent Plugins hook commands yet, so it relies on the
 skills.
 
+## Telemetry
+
+Telemetry is **off** in this build: generated manifests include no telemetry
+hooks and nothing is sent. When enabled, `hooks/telemetry-adapters/copilot-cli.mjs`
+records MCP tools as `<server>-<tool>`, operator stops with `subagent_session`,
+and session-scoped prompt state under `COPILOT_PLUGIN_DATA` (no `turn`, no
+`PreToolUse`, no built-in CLI/web events). See
+[telemetry.md](../telemetry.md) for opt-outs (`ARCADE_PLUGIN_TELEMETRY=0` and
+`COPILOT_OFFLINE`) and
+[what CI exercises](../telemetry.md#what-ci-exercises).
+
+Shared `com.github.copilot/hooks/hooks.json` uses `runOnlyIfScriptExists` so VS
+Code exits quietly without a plugin path.
+
 ## First steps
 
 - "What's on my calendar tomorrow?"

diff --git a/docs/install/vscode.md b/docs/install/vscode.md
@@ -17,6 +17,9 @@ VS Code loads root `plugin.json` as an Agent Plugin: 2 skills, the gateway,
 and `arcade-operator` from `com.github.copilot/agents/`. It does not read the
 `.cursor-plugin/` adapter. No lifecycle hooks: VS Code doesn't yet run Agent
 Plugins hook commands with the plugin's path or pass their output to the model.
+Copilot hook commands check that the script exists at the plugin path and exit
+when the path is missing; this package has no validated VS Code telemetry flow,
+and nothing is sent from VS Code.
 
 If you already installed the plugin via Copilot CLI, VS Code may auto-discover
 it from `~/.copilot/installed-plugins/`. Install in one place.

diff --git a/docs/support-matrix.md b/docs/support-matrix.md
@@ -27,6 +27,19 @@ session-start text doesn't reach the main conversation. The files are
 `clients/cursor/hooks/hooks.json` (Cursor CLI), and
 `com.github.copilot/hooks/hooks.json` (Copilot CLI).
 
+Telemetry adapters are separate from routing. **`TELEMETRY_ENABLED` is false**
+in this build, so manifests include no telemetry hooks and nothing is sent.
+When enabled, wiring comes from `hooks/hook-hosts.mjs`:
+
+| Client adapter | Telemetry events (when enabled) |
+| --- | --- |
+| Claude Code | `UserPromptSubmit`, `PreToolUse` on `^(?:mcp__plugin_arcade_arcade__\|mcp__claude_ai_arcade__)`, MCP `PostToolUse` / `PostToolUseFailure`, built-in `WebFetch` / `WebSearch` / listed `Bash` CLIs, Arcade operator `SubagentStop` |
+| Copilot CLI | `UserPromptSubmit`, MCP `PostToolUse` / `PostToolUseFailure` (`<server>-<tool>`), Arcade operator `SubagentStop` with `subagent_session` (no `PreToolUse`, no `turn`, no built-in tools) |
+
+Session start clears local prompt scope through the routing hook; it sends no
+telemetry event. No other adapter in this package sends telemetry. See
+[what's sent and its limits](telemetry.md).
+
 ¹ The Cursor IDE (3.21.18) lists the commands on the plugin page but not in
 the `/` menu. Other plugins' commands don't appear there either.
 ² The IDE (3.21.18) and Cloud Agents don't run plugin hooks, so the
@@ -37,10 +50,12 @@ load the always-apply rule.
 ⁴ Cowork runs the prompt and subagent hooks but doesn't add the session-start
 text, so its main conversation gets the short reminder and the skill, not the
 full rules.
-⁵ Copilot CLI drops the output of prompt hooks from config files, so it gets
-session and subagent hooks only.
+⁵ Copilot CLI drops the output of **routing** prompt hooks from config files,
+so the main conversation gets session and subagent hooks only. Telemetry still
+hooks `UserPromptSubmit` when enabled; `reminder_sent` is always `false` there.
 ⁶ VS Code reads `com.github.copilot/hooks/hooks.json` but doesn't expand
-`${PLUGIN_ROOT}` for Agent Plugins hooks or pass their output to the model yet.
+`${PLUGIN_ROOT}` for Agent Plugins hooks or pass their output to the model yet;
+`runOnlyIfScriptExists` makes those commands no-ops without a plugin path.
 ⁷ Blocked upstream; see [codex.md](install/codex.md).
 
 Skills are `try-arcade` and `scale-arcade`. The subagent is