The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
docs(runtimes): endpoint install already writes the hooks
Saurav Singh4037582f7617
diff --git a/docs/runtimes/antigravity-cli.mdx b/docs/runtimes/antigravity-cli.mdxindex 47761672..add743f3 100644--- a/docs/runtimes/antigravity-cli.mdx+++ b/docs/runtimes/antigravity-cli.mdx@@ -13,7 +13,7 @@ Before enabling Antigravity hooks, make sure:- Antigravity CLI is installed as `antigravity` or `antigravity-cli`, or an Antigravity hook config directory exists.- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.-- Beacon hooks are installed with `beacon endpoint hooks install --harness antigravity`.+- Beacon hooks are installed, either by `beacon endpoint install` when it detects Antigravity (or with `--harness antigravity`) or with `beacon endpoint hooks install --harness antigravity`.- For project-level collection, install hooks from the target project with `--level project`.- Antigravity is restarted after hook install or removal so new sessions load the updated hook configuration.@@ -29,7 +29,7 @@ Use `beacon endpoint hooks status --harness antigravity` to inspect Antigravity## Install or configuration support-`beacon endpoint install` prepares shared endpoint config and runtime log paths. Install Antigravity hooks separately:+`beacon endpoint install` prepares shared endpoint config and runtime log paths, and installs the user-level Antigravity hooks when it detects Antigravity (or when run with `--harness antigravity`). To install, refresh, or manage the hooks on their own, run:```bash title="Install runtime hooks"beacon endpoint hooks install --harness antigravitydiff --git a/docs/runtimes/claude-code.mdx b/docs/runtimes/claude-code.mdxindex 2cde1061..38147e88 100644--- a/docs/runtimes/claude-code.mdx+++ b/docs/runtimes/claude-code.mdx@@ -5,7 +5,7 @@ description: "Beacon support details for Claude Code endpoint telemetry"## Runtime overview-Beacon supports Claude Code through local OpenTelemetry export to Beacon's localhost collector, optional hook telemetry for richer lifecycle and tool activity, and local session-file sync for historical backfill.+Beacon supports Claude Code through local OpenTelemetry export to Beacon's localhost collector, hook telemetry for richer lifecycle and tool activity, and local session-file sync for historical backfill.## Prerequisites@@ -130,7 +130,7 @@ Managed-ingest privacy is a separate forwarding policy and does not switch off l| Turn identity | Supported. Claude Code's `prompt.id` is kept as `prompt.id` on OTLP events; hook events after the prompt read the same id from the session transcript, and `beacon endpoint claude sync` reads it from `promptId`. The hook-recorded prompt itself takes its id from the OTLP `user_prompt` event, because the hook runs before Claude Code records the prompt || Command, tool, and file telemetry | Supported through Claude Code OTLP with detailed tool inputs enabled. Command output requires hooks || Token usage and cost | Supported through OTLP token and cost metrics, with per-model and per-session attribution |-| Hook lifecycle and tool telemetry | Optional through `beacon endpoint hooks install --harness claude` |+| Hook lifecycle and tool telemetry | Supported. `beacon endpoint install` writes the hooks whenever the `claude` harness is selected; `beacon endpoint hooks install --harness claude` and `beacon endpoint hooks uninstall --harness claude` manage them separately || Historical session sync | Supported through `beacon endpoint claude sync`; marked as poll collection || Claude Code cloud agent sessions | Supported through cloud sandbox hooks with GCS upload || Model-visible skill listings | Supported through Claude transcript `attachment.type=skill_listing`, one part per skill in `gen_ai.system_instructions`, with the skills named in `system_context`; invoked skill file bodies remain excluded |@@ -171,7 +171,7 @@ attributes remain under `raw.attributes`, subject to the configured redactionand event-size controls. Future full-body `claude_code.*` lifecycle recordsdefault to `session.activity` until Beacon assigns a more specific mapping.-Optional hooks add detail that OTLP does not report. A pre-tool hook can appear+Hooks add detail that OTLP does not report. A pre-tool hook can appearas `tool.invoked`, and the Bash post-tool hook records the command's output in`command.output`. For a successful command, Claude reports stdout and stderrseparately, so Beacon stores stdout first and stderr after it. When a command@@ -209,7 +209,7 @@ claude sync: 3496 sessions, 168 changed, 33689 events (33689 retained), 0 errorsstopped before log rotation would discard this sweep's own events; 3329 session(s) left pending for the next sweep.```-Every `beacon endpoint <runtime> sync` that reads a session store (Codex, Copilot, Cursor, Cline, OpenCode, Pi, Prime Agent, Factory Droid, Grok Build, Hermes Agent, OpenClaw, DeepSeek Harness and fx as well as Claude Code and Devin CLI) stops the same way and takes the same `--rotate-bytes`. Their summaries carry `events_retained`, `events_rotated_out` and `retention_limited`; only Claude Code and Devin CLI also count `sessions_pending`.+Every `beacon endpoint <runtime> sync` that reads a session store (Codex, Copilot, Cursor, Cline, OpenCode, Pi, Prime Agent, Factory Droid, Grok Build, Hermes Agent, OpenClaw, DeepSeek Harness, fx and Harness² as well as Claude Code and Devin CLI) stops the same way and takes the same `--rotate-bytes`. Their summaries carry `events_retained`, `events_rotated_out` and `retention_limited`; only Claude Code and Devin CLI also count `sessions_pending`.With `--json`, the summary carries `events_retained` (events this sweep wrote that are still in the log or its archives when it finishes), `events_rotated_out` (events another writer's rotations discarded during the sweep, which also makes the sweep exit non-zero), `retention_limited`, and `sessions_pending`.diff --git a/docs/runtimes/cline.mdx b/docs/runtimes/cline.mdxindex 2e0bab83..d1192d43 100644--- a/docs/runtimes/cline.mdx+++ b/docs/runtimes/cline.mdx@@ -15,7 +15,7 @@ Before enabling Cline telemetry, make sure:- Cline is installed in at least one host, or has a local config directory at `~/.cline`.- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.-- Beacon's Cline plugin is installed with `beacon endpoint hooks install --harness cline`.+- Beacon's Cline plugin is installed, either by `beacon endpoint install` when it detects Cline or with `beacon endpoint hooks install --harness cline`.- Cline is restarted after plugin install or removal so new sessions load the updated plugin. In the IDE hosts this means reloading the window.## Collection paths@@ -46,7 +46,7 @@ Use `beacon endpoint cline status` to inspect Cline session stores and how much## Install or configuration support-`beacon endpoint install` prepares shared endpoint config and runtime log paths. Install Cline hooks separately:+`beacon endpoint install` prepares shared endpoint config and runtime log paths, and installs the Cline plugin at user level when it detects Cline (or when you pass `--harness cline`). To install, refresh, or manage the plugin on its own, including at project level:```bash title="Install runtime hooks"beacon endpoint hooks install --harness clinediff --git a/docs/runtimes/cursor.mdx b/docs/runtimes/cursor.mdxindex 9846cb57..ad97a8f7 100644--- a/docs/runtimes/cursor.mdx+++ b/docs/runtimes/cursor.mdx@@ -15,7 +15,7 @@ Before enabling Cursor hooks, make sure:- Cursor is installed for the user or the `~/.cursor` directory exists.- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.-- Beacon hooks are installed with `beacon endpoint hooks install --harness cursor`.+- Beacon hooks are installed, either by `beacon endpoint install` when it detects Cursor (or with `--harness cursor`) or with `beacon endpoint hooks install --harness cursor`.- For project-level collection, install hooks from the target project with `--level project`.- Cursor is restarted after hook install or removal so new sessions load the updated hook configuration.@@ -40,7 +40,7 @@ Use `beacon endpoint hooks status --harness cursor` to inspect Cursor hook statu## Install or configuration support-`beacon endpoint install` prepares shared endpoint config and runtime log paths. Install Cursor hooks separately:+`beacon endpoint install` prepares shared endpoint config and runtime log paths, and installs the user-level Cursor hooks when it detects Cursor (or when run with `--harness cursor`). To refresh or manage the hooks on their own, run:```bash title="Install runtime hooks"beacon endpoint hooks install --harness cursordiff --git a/docs/runtimes/devin-desktop.mdx b/docs/runtimes/devin-desktop.mdxindex 02f3ea2d..ae71c694 100644--- a/docs/runtimes/devin-desktop.mdx+++ b/docs/runtimes/devin-desktop.mdx@@ -13,7 +13,7 @@ Before enabling Devin Desktop hooks, make sure:- Devin Desktop is installed for the user or available in the workspace where hooks will run.- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.-- Beacon hooks are installed with `beacon endpoint hooks install --harness devin-desktop`.+- Beacon hooks are installed, either by `beacon endpoint install` when it detects Devin Desktop (or with `--harness devin-desktop`) or with `beacon endpoint hooks install --harness devin-desktop`.- For project-level collection, install hooks from the target workspace with `--level project`.- Devin Desktop is restarted after hook install or removal so new sessions load the updated hook configuration.@@ -23,13 +23,13 @@ Devin Desktop invokes Beacon's hook adapter through Cascade/Windsurf hook files.## Discovery and status-Beacon detects Devin Desktop through Cascade/Windsurf hook paths such as `~/.codeium/windsurf/hooks.json` or `./.windsurf/hooks.json`.+Beacon detects Devin Desktop through the `/Applications/Devin.app` bundle, `~/Library/Application Support/Devin`, or the Cascade/Windsurf directories `~/.codeium/windsurf` and `./.windsurf`, then checks Beacon hook configuration in `~/.codeium/windsurf/hooks.json` or `./.windsurf/hooks.json`.Use `beacon endpoint hooks status --harness devin-desktop` to inspect Devin Desktop hook status.## Install or configuration support-`beacon endpoint install` prepares shared endpoint config and runtime log paths. Install Devin Desktop hooks separately:+`beacon endpoint install` prepares shared endpoint config and runtime log paths, and installs the user-level Devin Desktop hooks when it detects Devin Desktop (or when run with `--harness devin-desktop`). To install, refresh, or manage the hooks on their own, run:```bash title="Install runtime hooks"beacon endpoint hooks install --harness devin-desktopdiff --git a/docs/runtimes/devin.mdx b/docs/runtimes/devin.mdxindex 0eda7eda..2308bffa 100644--- a/docs/runtimes/devin.mdx+++ b/docs/runtimes/devin.mdx@@ -13,7 +13,7 @@ Before enabling Devin CLI hooks, make sure:- Devin CLI is installed for the user or configured in the project where hooks will run.- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.-- Beacon hooks are installed with `beacon endpoint hooks install --harness devin-cli`. The legacy `devin` harness name still maps to Devin CLI.+- Beacon hooks are installed, either by `beacon endpoint install` when it detects Devin CLI (or with `--harness devin-cli`) or with `beacon endpoint hooks install --harness devin-cli`. The legacy `devin` harness name still maps to Devin CLI.- For project-level collection, install hooks from the target project with `--level project`.- Devin CLI is restarted after hook install or removal so new sessions load the updated hook configuration.@@ -38,7 +38,7 @@ Use `beacon endpoint hooks status --harness devin-cli` to inspect Devin CLI hook## Install or configuration support-`beacon endpoint install` prepares shared endpoint config and runtime log paths. Install Devin CLI hooks separately:+`beacon endpoint install` prepares shared endpoint config and runtime log paths, and installs the user-level Devin CLI hooks when it detects Devin CLI (or when run with `--harness devin-cli`). To install, refresh, or manage the hooks on their own, run:```bash title="Install runtime hooks"beacon endpoint hooks install --harness devin-clidiff --git a/docs/runtimes/factory-droid.mdx b/docs/runtimes/factory-droid.mdxindex 906c0a1e..d6516963 100644--- a/docs/runtimes/factory-droid.mdx+++ b/docs/runtimes/factory-droid.mdx@@ -14,7 +14,7 @@ Before enabling Factory Droid telemetry, make sure:- Factory Droid is installed and available as the `droid` executable for the user or managed endpoint.- `beacon endpoint install` has run so the local collector, shared endpoint config, and runtime log paths exist.- Droid's launch environment sets `OTEL_TELEMETRY_ENDPOINT=http://127.0.0.1:4318` through MDM or another customer-owned policy.-- Optional hook telemetry is installed with `beacon endpoint hooks install --harness factory`.+- Optional hook telemetry is installed by `beacon endpoint install` when it detects `droid` (or with `--harness factory`), or with `beacon endpoint hooks install --harness factory`.- Historical session telemetry can be synced from Factory's local session store with `beacon endpoint factory sync`.- Factory Droid is restarted after launch-environment or hook changes so new sessions use the updated settings.@@ -34,9 +34,9 @@ Use `beacon endpoint factory status` to inspect local Factory sessions and how m`beacon endpoint install` prepares the collector, shared endpoint config, and runtime log paths. Factory Droid's launch environment is managed by MDM or customer policy.-Install optional Factory hooks separately:+`beacon endpoint install` also installs user-level Factory hooks when it detects the `droid` executable, or when `--harness factory` (or `droid`) is given. To install, refresh, or manage the hooks on their own:-```bash title="Install optional Factory hooks separately"+```bash title="Install Factory hooks on their own"beacon endpoint hooks install --harness factory```diff --git a/docs/runtimes/grok-build.mdx b/docs/runtimes/grok-build.mdxindex b9d6f2a5..73b09fee 100644--- a/docs/runtimes/grok-build.mdx+++ b/docs/runtimes/grok-build.mdx@@ -13,7 +13,7 @@ Before enabling Grok Build hooks, make sure:- Grok Build is installed for the user or available in the project where hooks will run.- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.-- Beacon hooks are installed with `beacon endpoint hooks install --harness grok`.+- Beacon hooks are installed, either by `beacon endpoint install` (user-level, when Grok Build is detected or with `--harness grok`) or with `beacon endpoint hooks install --harness grok`.- Project-level hooks are trusted with `/hooks-trust` in Grok before you expect them to execute.- Grok is restarted after hook install or removal so new sessions load the updated hook file.@@ -34,7 +34,7 @@ Use `beacon endpoint hooks status --harness grok` to inspect Grok Build hook sta## Install or configuration support-`beacon endpoint install` prepares shared endpoint config and runtime log paths. Install Grok Build hooks separately:+`beacon endpoint install` prepares shared endpoint config and runtime log paths, and installs user-level Grok Build hooks when it detects Grok Build or when `--harness grok` is given. To install, refresh, or manage the hooks on their own:```bash title="Install runtime hooks"beacon endpoint hooks install --harness grok@@ -66,7 +66,7 @@ beacon endpoint grok sync --print| Command, tool, and file telemetry | Supported for live hook payloads and committed session records. Session sync reads `chat_history.jsonl`, `events.jsonl`, `summary.json`, `prompt_context.json`, and terminal logs where present || Approval telemetry | Live hooks can observe and enforce at pre-tool time; session sync can report committed Grok permission request/resolution records after the fact || Pre-tool answer | The `PreToolUse` hook answers with an empty object, which carries no decision, so Grok's own permission gate decides the call as it would without Beacon. A deny from a `BEACON_POLICY_PROVIDER` policy provider still returns `{"decision":"deny"}` |-| Session lifecycle | `session.started` only. Grok's `turn_ended` record ends a turn, not a session — the next prompt appends to the same session — so session sync records it as `session.context` carrying the turn number and outcome. Grok exposes no session-end record, so Beacon writes no `session.ended` for this runtime rather than inventing one |+| Session lifecycle | Live hooks record `session.started` and `session.ended` (from Grok's `SessionEnd` hook). Session sync records `session.started` only: Grok's `turn_ended` record ends a turn, not a session — the next prompt appends to the same session — so session sync records it as `session.context` carrying the turn number and outcome, and writes no `session.ended` rather than inventing one || Local JSONL and dashboard | Supported || MDM deployment | Supported for the endpoint agent. Grok hooks are installed separately in the logged-in user's context or project context |diff --git a/docs/runtimes/kiro.mdx b/docs/runtimes/kiro.mdxindex 1b945dbb..963308aa 100644--- a/docs/runtimes/kiro.mdx+++ b/docs/runtimes/kiro.mdx@@ -90,7 +90,7 @@ Kiro reports as the `kiro` harness with capability `hooks`, and every event carr## Install or configuration support-`beacon endpoint install` prepares shared endpoint config and runtime log paths. Kiro hooks are installed separately, because they live in a user config directory or a repository rather than in collector service configuration:+`beacon endpoint install` prepares shared endpoint config and runtime log paths, and installs the user-scope Kiro hook file when it detects Kiro (or when given `--harness kiro`). Install, refresh, or remove the hooks on their own, or at project scope, with `beacon endpoint hooks`:```bashbeacon endpoint hooks install --harness kiro # ~/.kiro/hooks/@@ -107,7 +107,7 @@ Uninstall removes the file Beacon wrote and nothing else. Your own hook files in| Area | Support ||------|---------|-| Runtime discovery | Supported through `.kiro/hooks/beacon-endpoint.json` at both scopes |+| Runtime discovery | Supported through the user-scope `~/.kiro/hooks/beacon-endpoint.json` (or under `$KIRO_HOME`). `beacon endpoint inventory` reports both scopes || Harness attribution | Supported. `kiro`, `kiro_ide`, `kiro-ide`, `kiro ide`, `kiro_cli`, `kiro-cli`, `kiro cli`, `kirocli`, `kiro_code`, `kiro-code`, `kiro code`, `kirocode`, `kiro_agent`, `kiro-agent`, `kiro agent`, and `kiro.dev` normalize to `kiro` || Hook install, status, uninstall, and repair | Supported || Session lifecycle | Supported. `session.started` from `SessionStart`, and `tool.completed` from `Stop` |@@ -172,7 +172,7 @@ A failed write is never recorded as an edit. Kiro reports one with the same toolKiro genuinely does ask the operator — through `permissions.yaml` rules and an interactive trust picker — and exposes none of that to a hook. `PreToolUse` fires identically whether the call was pre-approved by a rule, waved through by autopilot, or about to stop and wait for a person. An `approval.allowed` derived from it would therefore claim a decision in exactly the cases where none has been made yet, which is worse than the runtimes that have no approval gate at all. This is the same call already settled for [Cline](/runtimes/cline), [Pi](/runtimes/pi), [OpenHands](/runtimes/openhands), and [fx](/runtimes/vercel-fx).-Enforcement stays behind the optional, off-by-default policy provider seam (`BEACON_POLICY_PROVIDER`), which is inert unless it names an executable and fails open on any error. Kiro is one of the runtimes where a provider deny does take effect, and it is the only one where the deny is **not** a JSON object: Beacon exits with code **2** and writes the reason to stderr, which is Kiro's documented way to block `PreToolUse`. Kiro hands that stderr text to the agent as the explanation for the refusal. Any other non-zero exit code is an error to Kiro rather than a block, which is why Beacon exits 0 on every other path.+Enforcement stays behind the optional, off-by-default policy provider seam (`BEACON_POLICY_PROVIDER`), which is inert unless it names an executable and fails open on any error. Kiro is one of the runtimes where a provider deny does take effect, and, like [Kimi Code](/runtimes/kimi-code), the deny is **not** a JSON object: Beacon exits with code **2** and writes the reason to stderr, which is Kiro's documented way to block `PreToolUse`. Kiro hands that stderr text to the agent as the explanation for the refusal. Any other non-zero exit code is an error to Kiro rather than a block, which is why Beacon exits 0 on every other path.## Data handlingdiff --git a/docs/runtimes/openclaw-gateway.mdx b/docs/runtimes/openclaw-gateway.mdxindex 1dbca862..5293e533 100644--- a/docs/runtimes/openclaw-gateway.mdx+++ b/docs/runtimes/openclaw-gateway.mdx@@ -171,13 +171,13 @@ beacon endpoint hooks status --harness openclawbeacon endpoint hooks uninstall --harness openclaw```-`beacon endpoint install --harness openclaw` is **not** the command — OpenClaw's OTLP export lives in OpenClaw's own config, so Beacon prints the settings rather than writing them. Running it says so and names both commands.+`beacon endpoint install` also installs the plugin at user level when it detects OpenClaw, or when given `--harness openclaw`; it runs the same plugin install as `hooks install`. It does not configure the OTLP export, which lives in OpenClaw's own config: Beacon prints those settings with `beacon endpoint integrations openclaw print-config` rather than writing them.## Telemetry coverage| Area | Support ||------|---------|-| Runtime discovery | Supported through the plugin directory at both scopes |+| Runtime discovery | Supported through the user-scope plugin directory. `beacon endpoint inventory` reports both scopes || Harness attribution | Supported. `openclaw`, `openclaw_gateway`, `open-claw` and related spellings normalize to `openclaw_gateway` || Plugin install, status, uninstall, and repair | Supported || OTLP export configuration | Printed, not written. It lives in OpenClaw's own config |diff --git a/docs/runtimes/opencode.mdx b/docs/runtimes/opencode.mdxindex 47a6bffd..f99d08f3 100644--- a/docs/runtimes/opencode.mdx+++ b/docs/runtimes/opencode.mdx@@ -17,12 +17,12 @@ Before enabling OpenCode telemetry, make sure:- OpenCode is installed and available as the `opencode` executable or has a local config directory.- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.-- Beacon's OpenCode plugin is installed with `beacon endpoint hooks install --harness opencode`.+- Beacon's OpenCode plugin is installed, either by `beacon endpoint install` when it detects OpenCode or with `beacon endpoint hooks install --harness opencode`.- OpenCode is restarted after plugin install or removal so new sessions load the updated plugin.## Collection path-Beacon installs an owned OpenCode plugin at `~/.config/opencode/plugins/beacon.ts` for user-level hooks or `./.opencode/plugins/beacon.ts` for project-level hooks. The plugin forwards supported OpenCode hook payloads to Beacon's hook adapter.+Beacon installs an owned OpenCode plugin at `$XDG_CONFIG_HOME/opencode/plugins/beacon.ts` (default `~/.config/opencode/plugins/beacon.ts`) for user-level hooks or `./.opencode/plugins/beacon.ts` for project-level hooks. The plugin forwards supported OpenCode hook payloads to Beacon's hook adapter.The one plugin file loads in both OpenCode 1.x and OpenCode 2.x. Its default export carries the plugin `id`, the 1.x `server` entry, and the 2.x `setup` entry. On 2.x, `setup` registers the session `prompt` hook and the tool `execute.before`/`execute.after` hooks, and it subscribes to the event stream. It translates those into the same payloads the 1.x hooks produce, so events from either version look the same in the runtime log. After upgrading OpenCode from 1.x to 2.x, run `beacon endpoint hooks install --harness opencode` again, because a plugin written by an older Beacon exports only the 1.x factory, and OpenCode 2.x refuses to load it ("Plugin must export a default definition with an id and an effect or setup function").@@ -32,14 +32,14 @@ For backfill, `beacon endpoint opencode sync` reads OpenCode's local `opencode.d## Discovery and status-Beacon detects OpenCode through the `opencode` executable or `~/.config/opencode`, then checks for Beacon plugin configuration.+Beacon detects OpenCode through the `opencode` executable or `$XDG_CONFIG_HOME/opencode` (default `~/.config/opencode`), then checks for Beacon plugin configuration.Use `beacon endpoint hooks status --harness opencode` to inspect OpenCode plugin status.Use `beacon endpoint opencode status` to inspect persisted session-store collection progress.## Install or configuration support-`beacon endpoint install` prepares shared endpoint config and runtime log paths. Install OpenCode hooks separately:+`beacon endpoint install` prepares shared endpoint config and runtime log paths, and installs the OpenCode plugin at user level when it detects OpenCode (or when you pass `--harness opencode`). To install, refresh, or manage the plugin on its own, including at project level:```bash title="Install runtime hooks"beacon endpoint hooks install --harness opencodediff --git a/docs/runtimes/pi.mdx b/docs/runtimes/pi.mdxindex be87820b..f4eaeb14 100644--- a/docs/runtimes/pi.mdx+++ b/docs/runtimes/pi.mdx@@ -70,7 +70,7 @@ An unmarked extension file reports `disabled` rather than `enabled`, because rep## Install or configuration support-`beacon endpoint install` prepares shared endpoint config and runtime log paths. The extension is installed separately, because Pi loads it from the user's own profile rather than from a machine-wide location:+`beacon endpoint install` prepares shared endpoint config and runtime log paths, and installs the extension at user level when it detects Pi (or when you pass `--harness pi`). Pi loads it from the user's own profile rather than from a machine-wide location. To install, refresh, or manage the extension on its own, including at project level:```bashbeacon endpoint hooks install --harness pi # user level (default)diff --git a/docs/runtimes/prime-agent.mdx b/docs/runtimes/prime-agent.mdxindex 9f88cdfa..d0266c36 100644--- a/docs/runtimes/prime-agent.mdx+++ b/docs/runtimes/prime-agent.mdx@@ -84,7 +84,7 @@ An unmarked extension file reports `disabled` rather than `enabled`, because rep## Install or configuration support-`beacon endpoint install` prepares shared endpoint config and runtime log paths. The extension is installed separately, because Prime Agent loads it from the user's own profile rather than from a machine-wide location:+`beacon endpoint install` prepares shared endpoint config and runtime log paths, and installs the extension at user level when it detects Prime Agent (or when you pass `--harness prime`). Prime Agent loads it from the user's own profile rather than from a machine-wide location. To install, refresh, or manage the extension on its own, including at project level:```bashbeacon endpoint hooks install --harness prime # user level (default)diff --git a/docs/runtimes/qwen-code.mdx b/docs/runtimes/qwen-code.mdxindex a1508949..818520ae 100644--- a/docs/runtimes/qwen-code.mdx+++ b/docs/runtimes/qwen-code.mdx@@ -100,7 +100,7 @@ beacon endpoint hooks status --harness qwen## Install or configuration support-`beacon endpoint install` prepares shared endpoint config and runtime log paths. Qwen Code hooks are installed separately, because Qwen loads them from the user's own profile rather than from a machine-wide location:+`beacon endpoint install` prepares shared endpoint config and runtime log paths, and installs the user-level Qwen Code hooks when it detects Qwen Code (or when given `--harness qwen`). Install, refresh, or remove them on their own, or at project level, with `beacon endpoint hooks`:```bashbeacon endpoint hooks install --harness qwen # user level (default)@@ -111,8 +111,6 @@ beacon endpoint hooks uninstall --harness qwenA project-level install reports that Qwen Code runs project hooks only in a trusted folder. Without that, the file is written and nothing runs.-`beacon endpoint install` does not configure Qwen Code. Passing `--harness qwen` to it fails with a message pointing at `beacon endpoint hooks install`.-## Telemetry coverage| Area | Support |@@ -171,10 +169,9 @@ Qwen carries signal with no endpoint-schema field of its own: `permission_mode`## Known gaps-- **No OTLP path.** Qwen Code is a Gemini CLI fork without Gemini's OpenTelemetry export, so there is no collector endpoint to configure. Hooks are the only collection path, and `beacon endpoint install --harness qwen` says so rather than appearing to succeed.+- **No OTLP path.** Qwen Code is a Gemini CLI fork without Gemini's OpenTelemetry export, so there is no collector endpoint to configure. Hooks are the only collection path.- **Token spend is not collected, and cannot be.** Qwen's `Stop` payload carries no per-call token counts. Its `input_tokens` is the prompt for that turn, which in a multi-turn session already contains every prior turn, so summing it into `gen_ai.usage` would inflate a session's total by roughly the square of its length. Qwen Code therefore contributes no rows to the spend totals in `beacon token-usage`.- **Context utilization is collected.** The same numbers describe how full the window was, which is a level rather than an amount, so they normalize into `gen_ai.context` instead: `input_tokens` becomes `gen_ai.context.used_tokens` and `context_limit` becomes `gen_ai.context.limit_tokens`. Qwen Code appears in the context utilization section of `beacon token-usage`, measured against the window it reported rather than a static model table. `context_usage` is the ratio of the two and stays in `raw.qwen` rather than being stored a second time in different units.-- **A policy deny is honored in one of two phases.** The seam runs in both the `pre-tool` and `permission-request` hooks, and Beacon returns Claude Code's deny shape, which Qwen's `PreToolUse` contract honors. Qwen's `PermissionRequest` event reads a differently shaped `hookSpecificOutput.decision` object, so a deny raised from that phase is not honored. Because the seam fails open, the cost is a deny that does not take effect on one phase, never a tool call blocked for the wrong reason.- **Assistant text is not collected.** `MessageDisplay` is not registered, so Beacon records no assistant output or reasoning for Qwen Code. See [Events that are not collected](#events-that-are-not-collected).- **Project-level installs need a trusted folder.** Qwen gates project hooks behind trusted-folder status, so a user-level install is the one that works without further interaction. Grok Build has the same caveat.- **Payload fixtures are built from documentation.** Beacon's Qwen fixtures are constructed from Qwen Code's published hooks documentation rather than captured from a running install. The documentation specifies the envelope and per-event fields precisely, so the shapes match the documented contract, but they are not evidence that a shipped build sends exactly this.diff --git a/docs/runtimes/senpi.mdx b/docs/runtimes/senpi.mdxindex a5000774..21a0b3d6 100644--- a/docs/runtimes/senpi.mdx+++ b/docs/runtimes/senpi.mdx@@ -76,7 +76,7 @@ An unmarked extension file reports `disabled` rather than `enabled`, because rep## Install or configuration support-`beacon endpoint install` prepares shared endpoint config and runtime log paths. The extension is installed separately, because Senpi loads it from the user's own profile rather than from a machine-wide location:+`beacon endpoint install` prepares shared endpoint config and runtime log paths, and installs the extension at user level when it detects Senpi (or when you pass `--harness omo`). Senpi loads it from the user's own profile rather than from a machine-wide location. To install, refresh, or manage the extension on its own, including at project level:```bashbeacon endpoint hooks install --harness omo # user level (default)diff --git a/docs/runtimes/vscode.mdx b/docs/runtimes/vscode.mdxindex 0fd8dd5c..ed26932f 100644--- a/docs/runtimes/vscode.mdx+++ b/docs/runtimes/vscode.mdx@@ -55,7 +55,7 @@ User-level hooks:beacon endpoint hooks install --harness vscode --level user```-Hook-derived events use `harness.name=vscode`. They can capture VS Code lifecycle events such as prompt submission, pre-tool and post-tool activity, stop events, and subagent start/stop where VS Code exposes those hook payloads. Because hooks are preview, behavior may vary across VS Code versions, organizations, and agent surfaces.+Hook-derived events also use `harness.name=vscode_copilot`, so one session is not split across two names; tell them apart from OTel-derived events by `harness.collection_method` (`hook` vs `otlp`). They can capture VS Code lifecycle events such as prompt submission, pre-tool and post-tool activity, stop events, and subagent start/stop where VS Code exposes those hook payloads. Because hooks are preview, behavior may vary across VS Code versions, organizations, and agent surfaces.## Discovery and status@@ -88,7 +88,7 @@ For managed endpoint deployments, include `vscode` in the endpoint harness listbeacon endpoint install --system --harness claude,codex,vscode```-If hooks are allowed by organization policy, install them separately in the logged-in user's context or within the target project. Do not rely on hooks as the primary VS Code signal path; Copilot OTel is preferred and should provide most of the session, prompt, model, and tool visibility needed for Beacon.+A default `beacon endpoint install` (`--harness auto`) also writes user-level VS Code hooks to `~/.copilot/hooks/beacon.json` when it detects VS Code; an explicit `--harness vscode` configures OTel only. If hooks are not allowed by organization policy, remove them with `beacon endpoint hooks uninstall --harness vscode`; if they are allowed, install them in the logged-in user's context or within the target project. Do not rely on hooks as the primary VS Code signal path; Copilot OTel is preferred and should provide most of the session, prompt, model, and tool visibility needed for Beacon.## Related