Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

docs: describe goose support in CLAUDE.md and the README

Claudec1c4447ea9d6
diff --git a/CLAUDE.md b/CLAUDE.md
index 09120ef5..a3c0e711 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -39,6 +39,7 @@ Supported runtime surfaces today:
- Muse Code (Meta) hook telemetry through a Beacon-owned managed hooks file (`$XDG_CONFIG_HOME/muse/beacon-endpoint-hooks.json`, else `~/.config/muse/...`) that Muse's own `settings.json` points at with the `managed_hooks_path` key. Covers session start, prompts, tool lifecycle, operator approval decisions from `PermissionRequest`, subagent start/stop, context compaction, commands, and file activity. Muse Spark is the model and Muse Code is the agent: the harness is `muse_code`, and Muse Spark spellings are deliberately unmapped in `NormalizeHarnessName` so a model id cannot masquerade as the runtime. `PreLLMCall`/`PostLLMCall` are deliberately not subscribed to -- both carry the full `messages` array and tool schemas on every model call, and `PostLLMCall` fires per response chunk. Not collected, because Muse exposes none of it on a hook: token usage/cost, a session-end event, and subagent-to-parent correlation. Muse publishes no hook API, so the contract is reverse-engineered from a shipped build and a bad hooks file is rejected in total silence -- which is why the installer's emitted shape and the payload readers are both pinned by tests. Implementation lives in `cli/beacon/internal/endpoint/hooks/muse.go` and the `muse` platform branches in `cli/beacon-hooks/cmd`.
- OpenHands (All Hands) hook telemetry through the runtime's own `.openhands/hooks.json`, which Beacon merges its six commands into rather than owning. Covers session start and end, prompts, pre-tool and post-tool activity, commands with exit code and output, file reads and edits, MCP tool calls, and failed tools. The harness is `openhands`; OpenHands LM spellings are deliberately unmapped in `NormalizeHarnessName` so a model id cannot masquerade as the runtime. OpenHands rides the shared hook subcommands rather than getting a mapper of its own, because its six events line up one for one with them; the runtime-specific readers live in `cli/beacon-hooks/cmd/openhands.go` and the installer in `cli/beacon/internal/endpoint/hooks/openhands.go`. File diffs come from the observation's `old_content`/`new_content` rather than from the edit instruction, so they describe what landed on disk; one `apply_patch` call becomes one `file.modified` per changed file. Approval decisions are not exposed by OpenHands' hooks and are not synthesized, matching the Cline, Pi and fx decision. Not collected, because OpenHands exposes none of it on a hook: token usage and cost, a per-call tool id, and assistant response text. The verbatim payload is deliberately not retained under `raw`: its only unhoused field is `metadata`, which is empty on five of six events and constant on the sixth. `hooks.json` has a closed schema that rejects silently -- unknown top-level keys are fatal, a legacy `{"hooks": {...}}` wrapper replaces the whole document, and naming one event in both snake_case and PascalCase takes the file down -- so the installer refuses a file that already breaks one of those, and both the emitted shape and the payload readers are pinned by tests. Both scopes are real, but project scope is the one every host reads: the loader takes the first hooks file it finds rather than merging, and the agent server behind the CLI and the GUI reads only the project file.
- Kiro (AWS) hook telemetry through a Beacon-owned hook file in the directory Kiro scans (`.kiro/hooks/beacon-endpoint.json` at project scope, `$KIRO_HOME`/`~/.kiro/hooks/` at user scope). Covers session start, prompts, pre-tool and post-tool activity, commands with output, file reads and edits, MCP tool calls, failed tools, and the agent's final response from `Stop`'s `assistant_response` as an `agent.message`. The harness is `kiro` -- one name for the IDE and the CLI, because they are one harness reading one hooks directory. Kiro rides the shared hook subcommands: its envelope is spelled exactly as Claude Code's (`hook_event_name`, `cwd`, `session_id`, `tool_name`, `tool_input`, `tool_response`, `prompt`), so `cli/beacon-hooks/cmd/kiro.go` holds no envelope readers at all -- only the tool taxonomy, the `operations`-array path reader, MCP `@server/tool` detection, and the write-`command` guard. Kiro publishes its tool names and not its tool argument schemas, so classification is keyed on names and the diff builder reads both the Amazon Q lineage spellings (`file_text`, `old_str`, `new_str`) and the ecosystem ones, returning no diff rather than a wrong one when neither resolves. Two contract details are load-bearing and easy to get wrong: hook stdout is *added to the agent's context* on `SessionStart` and `UserPromptSubmit`, so Beacon writes nothing to stdout on this platform (`hookStdoutIsConsumedAsAgentContext`); and a block is exit code 2 with the reason on stderr rather than a JSON object, which is why the policy seam's deny is a `policyDenial` carrying an exit code. Timeouts are seconds and `0` means no timeout at all, so every trigger carries an explicit value. Beacon owns one filename in a directory Kiro loads whole, so the installer never reads another file and refuses rather than overwriting one it did not write. Approval decisions are not exposed by Kiro's hooks and are not synthesized -- Kiro does ask the operator through `permissions.yaml` and a trust picker, and `PreToolUse` fires identically whether or not it will, so an inferred approval would claim a decision precisely where none was made. Not subscribed to: `PostFileCreate`/`PostFileSave`/`PostFileDelete`, which duplicate `PostToolUse` for the same write; `PreTaskExec`/`PostTaskExec`, whose stdin payload Kiro does not document; and `Manual`. Not collected, because Kiro exposes none of it on a hook: token usage and cost, a per-call tool id, and a session-end event. Implementation lives in `cli/beacon-hooks/cmd/kiro.go` and `cli/beacon/internal/endpoint/hooks/kiro.go`.
+- goose (Block) telemetry over two paths that are collected together because neither is sufficient alone. The hook path is a Beacon-owned plugin: goose discovers plugins as the immediate subdirectories of `.agents/plugins` (user scope honours `GOOSE_PATH_ROOT`; project scope is always `<project>/.agents/plugins`) and loads `<plugin-root>/hooks/hooks.json` from each, so Beacon owns the directory `beacon-endpoint` rather than a file. Seven of goose's twelve events are subscribed to -- `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `SessionEnd` -- covering session lifecycle, prompts, tool lifecycle, command lines, file creates and edits with diffs, and MCP tool calls. The OTLP path configures `otel_exporter_otlp_endpoint` in goose's own `config.yaml` and carries what no hook does: token usage including cache reads and writes, model and provider, response ids, finish reasons and agent reasoning, on OTel GenAI semconv `chat` and `execute_tool` spans the collector exporter already reads. The harness is `goose`; GooseAI spellings are deliberately unmapped in `NormalizeHarnessName` and unaccepted as targets, because that is a different company's inference service rather than this runtime. Four contract details are load-bearing. goose classifies a *blocking* hook's stdout, so `PreToolUse` and `Stop` must answer `{"decision":"allow"}` -- the `{}` every other runtime reads as no opinion is classified a failed hook, and on a rule configured `on_failure: block` it denies the tool call; the policy seam's deny is correspondingly `{"decision":"block"}`, because goose does not recognise "deny" and would read it as no verdict and allow. `developer` is registered with `unprefixed_tools`, so its tools arrive as bare `shell`, `write`, `edit`, `tree`, `read_image`, and MCP tools are identified only by their `<extension>__<tool>` prefix not naming a built-in extension -- there is no `mcp` in the name, no `mcp_*` argument and no result to inspect. `PostToolUseFailure` carries a payload identical to `PostToolUse`, so the `event` field is the only thing separating a write that landed from one that did not, and it is what the diff guard turns on. And goose exports OTLP over HTTP only, so it takes the collector's HTTP port where Claude Code, Codex and Gemini take gRPC; pointing it at 4317 fails silently. `BeforeShellExecution`, `AfterShellExecution`, `BeforeReadFile` and `AfterFileEdit` are deliberately not subscribed to -- each duplicates `PreToolUse`/`PostToolUse` for the same call and carries no `tool_call_id` -- and `PreToolUseResult` is deferred because it fires once per call to report an outcome that is almost always "allow". Not collected, because goose exposes none of it on a hook: tool output of any kind (so no command exit codes, no command output, no file-read contents), reported cost, and approval decisions -- goose does ask the operator through `ToolApprovalOperation`, exposes none of it, and its `PreToolUse` chain is a separate plugin-policy layer that runs after the operator's decision, so an approval derived from it would claim a decision precisely where Beacon cannot see one. `.agents/plugins` is the shared Open Plugins directory rather than goose's own namespace, so another host implementing that specification would also run these hooks and Beacon could not tell from the payload; that is a stated limitation with no fix on Beacon's side. Implementation lives in `cli/beacon-hooks/cmd/goose.go`, `cli/beacon/internal/endpoint/hooks/goose.go` and `cli/beacon/internal/endpoint/harness/goose.go`.
- fx (vercel-labs/fx) telemetry read from the session store fx commits under `~/.fx/sessions/`, covering session start, prompts, tool calls, commands with exit codes and output, file reads/creates/edits with diffs, MCP tool calls, agent messages, history compaction, and per-turn token usage plus reported cost. fx exposes no third-party hook, plugin, or OTLP surface -- its lifecycle hooks are compiled into the binary -- so collection is a read of fx's own records, run by `beacon endpoint fx sync`. Every event carries `harness.collection_method=poll`; approvals are not synthesized (fx persists permission feedback text, not a per-call decision, matching the Cline and Pi posture) and no session-end event is invented, since fx sessions are resumable. Implementation lives in `cli/beacon/internal/fxsession` and `cli/beacon/cmd/endpoint_fx.go`.
- Claude Cowork admin-configured OpenTelemetry setup guidance and local validation.
- Browser chat telemetry through an optional Chrome MV3 extension (`browser-extension/`) covering claude.ai and chatgpt.com. A main-world interceptor tees the streamed response, a per-site adapter parses it into a normalized turn, and the service worker POSTs OTLP GenAI logs to the local collector on `127.0.0.1:4318`; the extension never writes files and never contacts a remote endpoint. `harness.name` resolves to `claude_web` or `chatgpt_web` (already handled by `NormalizeHarnessName` in `pkg/asymptoteobserve/harness.go`, where the browser cases must stay above the generic `claude` rule) and `harness.collection_method` is `otlp`. Scope is deliberately narrow: only those origins' chat streams, never other tabs or general browsing. Retention defaults to `full`, so prompt and response text is retained by default; this is documented rather than defaulted down, because browser chat telemetry without content has no investigative value. Treat the adapters as experimental, since both sites' stream formats are private and undocumented.
@@ -142,6 +143,17 @@ npx playwright install chromium # one-time
npm test # builds dist/, runs the replay e2e
```
+Install both goose paths during manual testing (the two are separate commands on purpose: hooks
+see prompts, tools, commands and file edits; OTLP carries the token usage, model and reasoning goose
+puts on no hook):
+
+```bash
+cd cli/beacon
+go run . endpoint hooks install --harness goose # plugin hooks in ~/.agents/plugins/beacon-endpoint
+go run . endpoint install --harness goose # otel_exporter_otlp_endpoint in goose's config.yaml
+go run . endpoint hooks status --harness goose
+```
+
Collect fx session telemetry during manual testing:
```bash
diff --git a/README.md b/README.md
index e3950798..1dc77e78 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,7 @@ to compare it with the managed path.
| [Factory Droid](https://docs.asymptotelabs.ai/cli/supported-runtimes-factory-droid) | OTLP HTTP plus optional hooks | Session, prompt, write/edit/create tool use, stop, and session end |
| [fx (Vercel Labs)](https://docs.asymptotelabs.ai/runtimes/vercel-fx) | Poll of fx's own session records under `~/.fx/sessions/` through `beacon endpoint fx sync`; events land a turn late and cannot gate a tool call | Session start, prompts, tool calls, commands with exit codes and output, file reads/creates/edits with diffs, MCP tool calls, agent messages, compaction, and token usage/cost. No approval or session-end record, because fx persists neither |
| [Gemini CLI](https://docs.asymptotelabs.ai/cli/supported-runtimes-gemini-cli) | Opt-in local OTLP | Prompts, tool calls, MCP activity, file operations, and approval-related events |
+| [goose](https://docs.asymptotelabs.ai/runtimes/goose) | Two paths, both wanted: native plugin hooks in `.agents/plugins/beacon-endpoint/`, plus opt-in local OTLP over HTTP | Hooks: session start and end, prompt, pre-tool, post-tool, failed tool, command line, file create/modify with diffs, and MCP tool calls. OTLP adds token usage, model and provider, response ids and agent reasoning. No tool output, exit codes or command output at all, and no approval decisions, because goose exposes none of those on a hook |
| [GitHub Copilot CLI](https://docs.asymptotelabs.ai/cli/supported-runtimes-github-copilot-cli) | MDM-managed OTLP HTTP | Prompt, session, tool, and approval-like activity |
| [Grok Build](https://docs.asymptotelabs.ai/cli/supported-runtimes-grok-build) | Native hooks | Session, prompt, pre-tool, post-tool, failed tool, stop, session end, command, and file |
| [Hermes Agent](https://docs.asymptotelabs.ai/cli/supported-runtimes-hermes-agent) | Shell hooks | Prompt, observed tool, command, file, approval request and response, session lifecycle, and subagent stop |