feat(telemetry): add telemetry reporting and document the default-off telemetry (4/4, GRO-305)

AGENTS.md

@@ -14,6 +14,17 @@ for a marked rules block.
 - 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. Reporting and maintained
+  docs for exports live in `scripts/telemetry-report.mjs` and
+  `docs/telemetry.md`. `test/telemetry-report.test.mjs` cross-checks adapters
+  when `hooks/telemetry-adapters/<host>.mjs` exists on the branch.
 - 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.

ARCHITECTURE.md

@@ -85,6 +85,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 `scripts/telemetry-report.mjs`
+for aggregating exports. Gateway telemetry remains authoritative; plugin events
+do not establish task success.

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 how
+to aggregate exports with `scripts/telemetry-report.mjs`. The Arcade MCP
+gateway remains the canonical source for request and tool-call telemetry.
+Adapter behavior is covered by in-process tests when those files are present;
+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).

docs/install/claude-code.md

@@ -37,6 +37,19 @@ 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`. See
+[telemetry.md](../telemetry.md) for opt-outs (`ARCADE_PLUGIN_TELEMETRY=0`,
+`DISABLE_TELEMETRY`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`) and limits.
+
+**Repo coverage:** in-process hook tests and `claude plugin validate --strict`
+(**2.1.258**). Not live sessions, IDE extensions, desktop Code tab, or Cowork.
+
 ## First steps
 
 - "What's on my calendar tomorrow?"

docs/install/copilot.md

@@ -26,6 +26,19 @@ 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).
+
+**Repo coverage:** in-process fixtures and `npm run verify:copilot` (**1.0.88**).
+Not live sessions, Windows PowerShell hook commands, or VS Code agent sessions.
+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?"

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.

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