Skip to content

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

Document Kiro support

Claude74904dfcb611
diff --git a/CLAUDE.md b/CLAUDE.md
index ae538d8c..371537ae 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -38,6 +38,7 @@ Supported runtime surfaces today:
- Oh My Pi (`omp`) hook telemetry through a Beacon-managed local extension (`~/.omp/agent/extensions/beacon.ts`, or `.omp/extensions/beacon.ts` at project level) covering session lifecycle, prompts, tool lifecycle and results, operator approval decisions, commands including operator `!` and `$` Python commands, file reads/creates/edits with the unified patch, MCP tool activity, agent reasoning, and token usage/cost. Oh My Pi is a fork of pi-mono and kept Pi's event payload shapes, so the two share one mapper (`cli/beacon-hooks/cmd/pi_family.go`) but never share identity: separate harness names, separate extension markers, separate install directories. Unlike Pi and Cline it does expose real operator approval decisions (`tool_approval_requested`/`tool_approval_resolved`), so those are recorded as `observed` approvals rather than withheld -- Beacon still never synthesizes one from a blocking `tool_call` handler. Those events carry no tool arguments, so the extension remembers each `tool_call`'s input by `toolCallId` and attaches it to the approval; without it the approval rules, which all match on `command.command` or `file.path`, could not read Oh My Pi approvals at all. The user-level install path honors `PI_CODING_AGENT_DIR` and `PI_CONFIG_DIR`; the project path is always `.omp/extensions`. `mcp_notification` is deliberately not subscribed to.
- 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`.
- 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.
diff --git a/README.md b/README.md
index 55caf5de..becb6195 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,7 @@ to compare it with the managed path.
| [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 |
+| [Kiro](https://docs.asymptotelabs.ai/runtimes/kiro) | Native hooks through a Beacon-owned file in `.kiro/hooks/` | Session start, prompt, pre-tool, post-tool, failed tool, command with output, file read/modify with diffs, MCP tool calls, and the agent's final response. No approval decisions or token usage, because Kiro exposes neither on a hook |
| [Muse Code](https://docs.asymptotelabs.ai/runtimes/muse-code) | Native hooks through a managed hooks file | Session start, prompt, pre-tool, post-tool, permission request/approval, subagent, context compaction, stop, command, and file. No session end or token usage, because Muse emits neither on a hook |
| [Oh My Pi](https://docs.asymptotelabs.ai/runtimes/oh-my-pi) | Managed extension hooks | Session lifecycle, prompts, tool lifecycle and results, approval decisions with the session's approval mode, commands including operator `!` and `$`, file reads/writes/edits with diffs, MCP activity, agent reasoning, and token usage/cost |
| [OpenClaw Gateway](https://docs.asymptotelabs.ai/cli/supported-runtimes-openclaw-gateway) | Gateway-configured OTLP/HTTP | OTLP logs, traces, and metrics from the Gateway diagnostics plugin |
diff --git a/cli/beacon/README.md b/cli/beacon/README.md
index 80b925ab..7eece0e2 100644
--- a/cli/beacon/README.md
+++ b/cli/beacon/README.md
@@ -548,6 +548,9 @@ contract, what leaves the machine, and revocation.
./beacon endpoint hooks install --harness openhands --level project
./beacon endpoint hooks status --harness openhands --level project
+./beacon endpoint hooks install --harness kiro
+./beacon endpoint hooks status --harness kiro
+
./beacon endpoint hooks install --harness hermes
./beacon endpoint hooks status --harness hermes
@@ -618,6 +621,23 @@ of one event, or a top-level event added beside a legacy `{"hooks": {...}}` wrap
all end with hooks not running and no error -- so install refuses a file that
already breaks one of those rather than reporting a success that collects nothing.
+The Kiro integration writes one hook file of Beacon's own,
+`beacon-endpoint.json`, into the `.kiro/hooks/` directory Kiro scans -- at
+`<repo>/.kiro/hooks/` for project-level installs or `$KIRO_HOME`/`~/.kiro/hooks/`
+for user-level ones. Kiro loads every `.json` file in that directory, so the
+install is additive by construction: your own hook files are never read,
+rewritten or deleted, and uninstall removes only the file Beacon wrote. Beacon
+does claim that one filename -- a file at it holding a hook Beacon did not write
+is refused rather than overwritten, with an error naming the hook. Both scopes
+are live at once, because Kiro merges hook files across scopes rather than taking
+the first it finds, so one install covers the Kiro IDE and the Kiro CLI and a
+user-scope install keeps working inside a repository with hooks of its own.
+Kiro's hook contract is exit codes rather than response objects, so Beacon writes
+nothing to stdout there: on `SessionStart` and `UserPromptSubmit` Kiro adds a
+hook's stdout to the model's context, and an observing hook has nothing to say to
+the model. The one exception is the optional policy seam, whose deny is exit code
+2 with the reason on stderr -- Kiro's documented way to block a tool call.
+
The Hermes Agent integration writes shell-hook entries into
`~/.hermes/config.yaml`. Hermes prompts for first-use consent for each
`(event, command)` pair; for non-interactive gateway, cron, or CI runs, set
diff --git a/cli/beacon/internal/tokens/coverage.go b/cli/beacon/internal/tokens/coverage.go
index 4a20830d..df084c3a 100644
--- a/cli/beacon/internal/tokens/coverage.go
+++ b/cli/beacon/internal/tokens/coverage.go
@@ -106,6 +106,7 @@ var usageExpectation = map[string]struct {
"claude_web": {ExpectNone, "no recorded claude.ai stream has carried a usage object"},
"chatgpt_web": {ExpectNone, "the chat stream reports no token counts"},
"openhands": {ExpectNone, "hook payloads carry no token counts"},
+ "kiro": {ExpectNone, "hook payloads carry no token counts"},
}
// InstalledConfig is the part of a config-scanner row that install detection reads.
diff --git a/cli/beacon/internal/tokens/coverage_test.go b/cli/beacon/internal/tokens/coverage_test.go
index f1a06699..078cb914 100644
--- a/cli/beacon/internal/tokens/coverage_test.go
+++ b/cli/beacon/internal/tokens/coverage_test.go
@@ -212,7 +212,7 @@ func TestEveryScannedRuntimeHasAnExpectation(t *testing.T) {
scanned := []string{
"antigravity_cli", "claude_code", "cline", "codex_cli", "copilot_cli", "cursor",
"devin-cli", "devin-desktop", "factory", "gemini_cli", "grok", "hermes",
- "muse_code", "omp", "opencode", "openhands", "pi_cli", "qwen_code", "vscode",
+ "kiro", "muse_code", "omp", "opencode", "openhands", "pi_cli", "qwen_code", "vscode",
}
for _, runtime := range scanned {
harness := normalizedHarnessForTest(runtime)
@@ -250,6 +250,13 @@ func TestNewHarnessesAreClassifiedNotAlerted(t *testing.T) {
if openhands.Status != CoverageNotInstrumented || openhands.Expectation != ExpectNone {
t.Errorf("openhands = %+v, want not_instrumented/none -- no OpenHands hook payload carries token counts", openhands)
}
+ // A runtime missing from the expectation table is reported as silent, which is the one status
+ // the table exists to keep clean: it means "should be reporting and is not". Kiro reports no
+ // tokens because no Kiro hook payload carries any, so its row has to say expected-none.
+ kiro := lineFor(t, Coverage([]schema.Event{plainEvent("kiro")}, []string{"kiro"}), "kiro")
+ if kiro.Status != CoverageNotInstrumented || kiro.Expectation != ExpectNone {
+ t.Errorf("kiro = %+v, want not_instrumented/none -- no Kiro hook payload carries token counts", kiro)
+ }
grokBot := lineFor(t, Coverage([]schema.Event{plainEvent("grok_bot")}, nil), "grok_bot")
if grokBot.Expectation != ExpectGenericOTLP {
diff --git a/docs/cli/token-usage.mdx b/docs/cli/token-usage.mdx
index 8eba626f..bc8d3cfb 100644
--- a/docs/cli/token-usage.mdx
+++ b/docs/cli/token-usage.mdx
@@ -85,6 +85,7 @@ A runtime that reports occupancy and no spend still shows as `not_instrumented`
| Muse Code | Usage arrives on `PostLLMCall` and in Muse's own session log, neither of which Beacon reads. See [Muse Code](/runtimes/muse-code) |
| Qwen Code | The `Stop` payload carries session-level context counters, not per-call usage. Those counters are recorded as context occupancy rather than spend -- see [Context occupancy](#context-occupancy) below. See [Qwen Code](/runtimes/qwen-code) |
| OpenHands | None of the six hook payloads carries token counts, and OpenHands exposes no other hook that would. See [OpenHands](/runtimes/openhands) |
+| Kiro | No Kiro hook payload carries token counts. See [Kiro](/runtimes/kiro) |
| Prime Agent | No managed extension ships yet, so nothing is collected |
| Claude.ai | The adapter parses counts, but no recorded claude.ai stream has carried a usage object. See [Claude.ai](/runtimes/claude-web#limits) |
| ChatGPT | The chat stream reports no token counts |
diff --git a/docs/docs.json b/docs/docs.json
index 85ad6e68..6523d55b 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -148,6 +148,7 @@
"runtimes/gemini-cli",
"runtimes/github-copilot-cli",
"runtimes/grok-build",
+ "runtimes/kiro",
"runtimes/muse-code",
"runtimes/oh-my-pi",
"runtimes/opencode",
diff --git a/docs/runtimes/index.mdx b/docs/runtimes/index.mdx
index 70aafb85..bafb6735 100644
--- a/docs/runtimes/index.mdx
+++ b/docs/runtimes/index.mdx
@@ -32,6 +32,7 @@ These integrations are grouped by where the agent runs and how telemetry is coll
| [Gemini CLI](/runtimes/gemini-cli) | Opt-in local OTLP | Prompts, tool calls, MCP activity, file operations, and approval-related events emitted through OTLP |
| [GitHub Copilot CLI](/runtimes/github-copilot-cli) | MDM-managed OTLP HTTP | Prompt, session, tool, and approval-like activity emitted through Copilot CLI spans |
| [Grok Build](/runtimes/grok-build) | Native hooks | Session, prompt, pre-tool, post-tool, failed tool, stop, session-end, command, and file telemetry |
+| [Kiro](/runtimes/kiro) | Native hooks through a Beacon-owned file in `.kiro/hooks/` | 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. No approval decisions or token usage, because Kiro exposes neither on a hook |
| [Muse Code](/runtimes/muse-code) | Native hooks through a managed hooks file | Session start, prompt, pre-tool, post-tool, permission request, subagent, context compaction, stop, command, and file telemetry |
| [Oh My Pi](/runtimes/oh-my-pi) | Managed extension hooks | Session lifecycle, prompts, tool lifecycle, operator approval decisions, commands including operator `!` and `$` commands, file reads and edits with the unified patch, MCP tool activity, agent reasoning, and token usage |
| [OpenCode](/runtimes/opencode) | Managed plugin hooks | Chat messages, session events, command execution, permission activity, diffs, and errors |
diff --git a/docs/runtimes/integration-model.mdx b/docs/runtimes/integration-model.mdx
index 85359b99..5d47d5d4 100644
--- a/docs/runtimes/integration-model.mdx
+++ b/docs/runtimes/integration-model.mdx
@@ -25,6 +25,7 @@ Beacon supports multiple [runtime surfaces](/concepts/core-concepts#runtime-surf
| [Oh My Pi](/runtimes/oh-my-pi) | Looks for the `omp` executable, treating the resolved agent directory as an extra signal for the same reason as Pi, then checks for Beacon's managed extension at `~/.omp/agent/extensions/beacon.ts` |
| [fx (Vercel Labs)](/runtimes/vercel-fx) | Looks for the `fx` executable, treating `~/.fx` as an extra signal, then reports how much of the session store under `~/.fx/sessions` a sweep has actually collected. There is no managed file to check, so collection progress is the only honest evidence telemetry is flowing |
| [Muse Code](/runtimes/muse-code) | Checks Muse's config directory (`$XDG_CONFIG_HOME/muse`, else `~/.config/muse`) for Beacon's managed hooks file and for the `managed_hooks_path` key in Muse's own `settings.json`. Both are reported, because either one alone is a broken install that Muse says nothing about |
+| [Kiro](/runtimes/kiro) | Checks `<repo>/.kiro/hooks/beacon-endpoint.json` and the user-level file (`$KIRO_HOME`, else `~/.kiro`) for Beacon's hook commands. Both scopes are reported because Kiro merges hook files across scopes rather than resolving them by precedence, so both can be live at once |
| [OpenHands](/runtimes/openhands) | Checks `<repo>/.openhands/hooks.json` and the user-level file (`$OH_PERSISTENCE_DIR`, else `~/.openhands`) for Beacon's hook commands. Both scopes are reported, because OpenHands reads the first file it finds rather than merging them, so a repository file shadows the user one entirely |
| [Qwen Code](/runtimes/qwen-code) | Looks for the `qwen` executable, treating `~/.qwen` as an extra signal because an npm or version-manager install is often off the inherited `PATH`, then checks `~/.qwen/settings.json` for Beacon's `--platform qwen` hook entries |
| [Devin CLI](/runtimes/devin) | Looks for the `devin` executable, `~/.config/devin`, or `./.devin`, then checks Beacon hook configuration |
@@ -48,7 +49,7 @@ During install, Beacon configures the runtime surfaces it can safely manage:
| [Factory Droid](/runtimes/factory-droid) | Droid's OTLP endpoint remains under its launch environment, commonly managed through MDM or another customer-owned policy. |
| [OpenClaw Gateway](/runtimes/openclaw-gateway) | Configure OpenClaw with the `diagnostics-otel` plugin. Beacon prints local OTLP/HTTP setup guidance and validates observed events. |
| [fx (Vercel Labs)](/runtimes/vercel-fx) | Nothing is installed or configured. fx has no hook file, plugin directory, or OTLP endpoint, so collection is an action: run or schedule [`beacon endpoint fx sync`](/cli/endpoint-fx). |
-| Hook-based runtimes | [Antigravity CLI](/runtimes/antigravity-cli), [Claude Code](/runtimes/claude-code), [Cline](/runtimes/cline), [Cursor](/runtimes/cursor), [Devin CLI](/runtimes/devin), [Devin Desktop](/runtimes/devin-desktop), [Factory](/runtimes/factory-droid), [Grok Build](/runtimes/grok-build), [Hermes Agent](/runtimes/hermes-agent), [Muse Code](/runtimes/muse-code), [Oh My Pi](/runtimes/oh-my-pi), [OpenCode](/runtimes/opencode), [OpenHands](/runtimes/openhands), [Pi](/runtimes/pi), and [Qwen Code](/runtimes/qwen-code) hooks and managed plugins are installed separately with [`beacon endpoint hooks`](/cli/hooks), because hooks are per-user or per-project runtime configuration rather than base collector service configuration. |
+| Hook-based runtimes | [Antigravity CLI](/runtimes/antigravity-cli), [Claude Code](/runtimes/claude-code), [Cline](/runtimes/cline), [Cursor](/runtimes/cursor), [Devin CLI](/runtimes/devin), [Devin Desktop](/runtimes/devin-desktop), [Factory](/runtimes/factory-droid), [Grok Build](/runtimes/grok-build), [Hermes Agent](/runtimes/hermes-agent), [Kiro](/runtimes/kiro), [Muse Code](/runtimes/muse-code), [Oh My Pi](/runtimes/oh-my-pi), [OpenCode](/runtimes/opencode), [OpenHands](/runtimes/openhands), [Pi](/runtimes/pi), and [Qwen Code](/runtimes/qwen-code) hooks and managed plugins are installed separately with [`beacon endpoint hooks`](/cli/hooks), because hooks are per-user or per-project runtime configuration rather than base collector service configuration. |
## Integration paths
@@ -69,6 +70,7 @@ During install, Beacon configures the runtime surfaces it can safely manage:
| [Prime Agent](/runtimes/prime-agent) | Not yet collected | Another pi-mono fork with the same extension API. Harness identity and the plugin collection method ship today; the managed extension, discovery probe, and install target do not, so no Prime Agent events are collected yet. |
| [fx (Vercel Labs)](/runtimes/vercel-fx) | Poll of fx's own session store | fx exposes no third-party observation surface: its lifecycle hooks are compiled into the binary, it has no OpenTelemetry export, and its plugin story is MCP. Beacon reads the append-only session records under `~/.fx/sessions` and marks every event `harness.collection_method=poll`, so a consumer knows nothing on this path could have been intercepted. |
| [Muse Code](/runtimes/muse-code) | Native hook payloads through `beacon-hooks` | Beacon writes a managed hooks file it owns outright and points Muse's own `settings.json` at it with the `managed_hooks_path` key, then maps session, prompt, tool, command, file, approval, subagent, and compaction events into endpoint events. Muse ships an OTLP export that cannot be pointed at a local collector, so hooks are the only collection path. |
+| [Kiro](/runtimes/kiro) | Native hook payloads through `beacon-hooks` | Beacon writes one hook file of its own into the `.kiro/hooks/` directory Kiro scans, leaving every other file in it untouched, then maps session, prompt, tool, command, file, MCP and agent-response events into endpoint events. Kiro's hook contract is exit codes rather than response objects, so Beacon writes nothing to stdout: on the two events Kiro reads it for, stdout is added to the model's context. |
| [OpenHands](/runtimes/openhands) | Native hook payloads through `beacon-hooks` | Beacon merges its six commands into the `.openhands/hooks.json` the runtime already reads, preserving hooks you wrote, then maps session, prompt, tool, command, file, and MCP events into endpoint events. File edits carry an exact diff, because OpenHands reports the file's content before and after rather than the edit instruction. |
| [Qwen Code](/runtimes/qwen-code) | Native hook payloads through `beacon-hooks` | Beacon merges a managed hook block into Qwen's own `settings.json` and maps session, prompt, tool, command, file, failed-tool, approval, and subagent events into endpoint events. Qwen Code is a Gemini CLI fork without Gemini's OTLP export, so hooks are the only collection path. |
| [Devin CLI](/runtimes/devin) | Native hook payloads through `beacon-hooks` | Hooks emit session, prompt, pre-tool, post-tool, permission request, stop, session-end, approval, and file telemetry where Devin CLI exposes payloads. |
@@ -99,6 +101,7 @@ Antigravity CLI, Claude Code, Cline, Cursor, Devin CLI, Devin Desktop, Factory,
| [Pi](/runtimes/pi) | Session lifecycle, prompt submission, tool invocation and results, command execution including operator `!` commands, file reads, creates, and edits with the unified patch, agent reasoning from assistant thinking parts, and token usage and cost. Approval decisions are not exposed by Pi's extension API and are not synthesized. |
| [Oh My Pi](/runtimes/oh-my-pi) | Everything Pi reports, plus real operator approval decisions carrying the command or file being decided on, the session's approval mode, and the tool call id. Commands include operator `!` shell and `$` Python prefixes, and MCP tool activity is resolved from Oh My Pi's `mcp__<server>_<tool>` naming. |
| [Muse Code](/runtimes/muse-code) | Session start, prompt submission, pre-tool and post-tool activity, permission requests, subagent start and stop, context compaction, stop events, command execution, and file activity. Hook timeouts are second values. User scope only: Muse's project `.muse/hooks.json` is ignored by the shipping build. |
+| [Kiro](/runtimes/kiro) | Session start, prompt submission, pre-tool and post-tool activity, stop events with the agent's final response, command execution with output, and file activity. Hook timeouts are second values, and `0` means no timeout rather than the default. One install covers the Kiro IDE and the Kiro CLI, because they are one harness reading one hooks directory; both scopes are live at once, because Kiro merges them. |
| [OpenHands](/runtimes/openhands) | Session start and end, prompt submission, pre-tool and post-tool activity, stop events, command execution with exit code and output, and file activity with exact before/after diffs. Hook timeouts are second values. Both scopes work, but project scope is the one every host reads: OpenHands takes the first hooks file it finds, and its agent server never consults the user-level one. |
| [Qwen Code](/runtimes/qwen-code) | Session lifecycle, prompt submission, pre-tool and post-tool activity, post-tool failures, permission requests, subagent start and stop, stop events, session-end events, command execution, and file activity where payloads are available. Hook timeouts are millisecond values, and project-level hooks require a trusted folder in Qwen. |
diff --git a/docs/runtimes/kiro.mdx b/docs/runtimes/kiro.mdx
new file mode 100644
index 00000000..6c3e02c8
--- /dev/null
+++ b/docs/runtimes/kiro.mdx
@@ -0,0 +1,227 @@
+---
+title: "Kiro"
+description: "Asymptote support details for Kiro endpoint telemetry"
+---
+
+## Runtime overview
+
+Asymptote supports Kiro — the AI coding agent from AWS — through its native [hooks](https://kiro.dev/docs/hooks/), sent to `beacon-hooks`.
+
+```bash
+beacon endpoint hooks install --harness kiro
+```
+
+`--harness kiro-ide`, `--harness kiro-cli`, and `--harness kiro-code` are also accepted, and all four install the same thing.
+
+Kiro runs one agent harness behind the Kiro IDE, the Kiro CLI (`kiro-cli`), Kiro Web, Mobile, and Crew, and every local surface loads hooks from the same `.kiro/hooks/` directory. There is one integration rather than one per surface, and one harness name — `kiro` — rather than a name per surface.
+
+<Note>
+**Kiro Web and Mobile read project configuration only.** Kiro Web loads `.kiro/hooks/` committed to a repository; neither Web nor Mobile reads the machine's `~/.kiro/`, because neither has a local filesystem. Hooks committed at project scope therefore reach Kiro Web; a user-scope install does not.
+</Note>
+
+## Prerequisites
+
+Before enabling Kiro telemetry, make sure:
+
+- Kiro IDE 1.0 or later, or Kiro CLI 3.0 or later, is installed. The `.kiro/hooks/*.json` format was introduced in those releases; earlier versions use the `.kiro.hook` format and the embedded agent-config format, which Asymptote does not write.
+- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.
+- Kiro is restarted, or a new session started, after hook install or removal — hooks are loaded when a session begins.
+
+## Collection path
+
+Kiro loads **every** `.json` file in its hooks directory, so Asymptote writes **one file of its own** and never reads, rewrites, or deletes anything you put beside it.
+
+| Scope | File | Read by |
+|-------|------|---------|
+| User | `~/.kiro/hooks/beacon-endpoint.json` | The IDE and the CLI, in every project on the machine |
+| Project | `<repo>/.kiro/hooks/beacon-endpoint.json` | The IDE, the CLI, and Kiro Web |
+
+`$KIRO_HOME` replaces `~/.kiro` when it is set, matching how Kiro resolves the global directory itself. It exists so one machine can hold separate Kiro profiles.
+
+<Note>
+**Both scopes are live at once.** Kiro *merges* hooks across scopes rather than resolving them by precedence, so a user-scope install keeps working inside a repository that has hooks of its own, and installing at both scopes is not a conflict. This is the opposite of [OpenHands](/runtimes/openhands), where a project file shadows the user one entirely — so unlike OpenHands, there is no scope here that leaves a successful install silently collecting nothing. Pick user scope to cover every project on the machine; pick project scope to commit the hook with the repository and reach Kiro Web.
+</Note>
+
+`beacon endpoint inventory` reports both scopes, so an install at either is visible.
+
+### Registered events
+
+Kiro exposes eleven triggers. Asymptote registers five of them, and the six it leaves out are covered under [Known gaps](#known-gaps).
+
+| Kiro trigger | Adapter subcommand | Timeout |
+|--------------|--------------------|---------|
+| `SessionStart` | `session-start` | 10 s |
+| `UserPromptSubmit` | `prompt-submit` | 30 s |
+| `PreToolUse` | `pre-tool` | 10 s |
+| `PostToolUse` | `post-tool` | 10 s |
+| `Stop` | `stop` | 45 s |
+
+<Warning>
+**Kiro hook timeouts are seconds, not milliseconds.** The same `timeout` field is milliseconds on [Qwen Code](/runtimes/qwen-code), in a hooks file that looks similar. Kiro's own default is 60 seconds; Asymptote writes explicit lower values, because 60 seconds is a long time to hold an agent turn for a hook that finishes in milliseconds. These are ceilings on a hang, not budgets. `0` is never written: on Kiro it means *no timeout at all*, not "the default".
+</Warning>
+
+Asymptote's hooks carry no `matcher`. The field is a regex whose subject depends on the trigger — a tool name on `PreToolUse` and `PostToolUse`, the prompt text on `UserPromptSubmit`, nothing at all on `SessionStart` and `Stop` — and omitting it means always-match, which is what a telemetry hook wants on all five. The `*` that means "all tools" in the IDE's tool-name field is a different thing here and is not a valid regex.
+
+### Asymptote owns one filename and nothing else
+
+Because Kiro loads every file in the directory, an install is additive by construction: your `lint-on-save.json` keeps working, untouched, and Asymptote never parses it.
+
+The one thing Asymptote does claim is the name `beacon-endpoint.json`. If a file with that name already exists and holds a hook Asymptote did not write, both install and uninstall **refuse** with an error naming the hook, rather than overwriting or deleting it — move that hook into another file in the same directory and run the install again. A file at that name that Kiro itself could not parse is overwritten, since there are no live hooks in it to protect.
+
+Re-running the install rewrites the file rather than appending to it, so a repair does not end with each trigger registered twice.
+
+### The hook environment
+
+Kiro runs a `command` action as a shell command in the project root and sends the hook event as JSON on stdin. On `UserPromptSubmit` the IDE also exports the prompt as `USER_PROMPT`; Asymptote reads the payload's `prompt` field instead, which both surfaces send.
+
+Asymptote passes the endpoint log and config locations to `beacon-hooks` as `--log` and `--config` flags rather than through the environment, so a hook finds them wherever it runs.
+
+<Warning>
+**On Kiro, a hook's stdout is model context, not a response.** Kiro's hook contract is exit codes: on exit 0 a hook's stdout is *added to the agent's context* for `SessionStart` and `UserPromptSubmit`, and ignored for everything else. Asymptote therefore writes **nothing** to stdout on Kiro — an observing hook that emitted its usual no-op JSON object would be putting unexplained text in front of the model at the start of every session and before every prompt. Silence is a complete answer under an exit-code contract.
+</Warning>
+
+## Discovery and status
+
+```bash title="Show Kiro hook status"
+beacon endpoint hooks status --harness kiro
+```
+
+Kiro reports as the `kiro` harness with capability `hooks`, and every event carries `harness.collection_method=hook`: the events, the payload shapes, and the v1 hook schema are all AWS's. Asymptote owning the file it writes is a question of who authored it, not of who defines the contract — it ships no plugin source Kiro loads and executes.
+
+## 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:
+
+```bash
+beacon endpoint hooks install --harness kiro # ~/.kiro/hooks/
+beacon endpoint hooks install --harness kiro --level project # <repo>/.kiro/hooks/
+beacon endpoint hooks status --harness kiro
+beacon endpoint hooks uninstall --harness kiro
+```
+
+Commit `.kiro/hooks/beacon-endpoint.json` if you want the hooks to apply to everyone working in the repository, and to Kiro Web sessions on it.
+
+Uninstall removes the file Asymptote wrote and nothing else. Your own hook files in the same directory are never touched.
+
+## Telemetry coverage
+
+| Area | Support |
+|------|---------|
+| Runtime discovery | Supported through `.kiro/hooks/beacon-endpoint.json` at 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` |
+| Prompts | Supported. `prompt.submitted` from `UserPromptSubmit` |
+| Tool use | Supported for pre-tool and post-tool activity |
+| Commands | Supported. `command.executed` with the command and its output |
+| File activity | Supported. `file.read` and `file.modified` with paths, operations, and diffs where the argument shape resolves |
+| MCP activity | Supported. Recognized from Kiro's `@server/tool` naming, with the server and tool split out |
+| Agent responses | Supported. `agent.message` from the `Stop` payload's `assistant_response` |
+| Failed tools | Supported. `tool.failed` at high severity when the tool result reports `success: false` |
+| Approval decisions | Not collected. See [Known gaps](#known-gaps) |
+| Token usage and cost | Not collected. See [Known gaps](#known-gaps) |
+| Spec task lifecycle | Not collected. See [Known gaps](#known-gaps) |
+| Local JSONL and dashboard | Supported |
+| MDM deployment | Supported for the endpoint agent. Kiro hooks are installed per repository or in the logged-in user's context |
+
+### Tool taxonomy
+
+Kiro publishes its tool **names** and not its tool **argument schemas**, so Asymptote classifies on names alone, from a table covering Kiro's whole published catalog and its aliases:
+
+| Tool | Recorded as |
+|------|-------------|
+| `read` / `fs_read` / `fsRead`, `read_file`, `read_files`, `list_directory` | `file.read` |
+| `file_search` / `glob`, `grep_search` / `grep`, `code`, `read_code` | `file.read`, against the path or directory searched |
+| `write` / `fs_write` / `fsWrite` | `file.modified`, operation `create` |
+| `fs_append`, `str_replace` | `file.modified`, operation `modify` |
+| `delete_file` | `file.modified`, operation `delete` |
+| `shell` / `execute_bash` / `execute_cmd`, `control_bash_process` | `command.executed`, with `command.output` |
+| `@server/tool` | `mcp.tool_invoked`, with `mcp.server` and `mcp.tool` |
+| `aws` / `use_aws`, `web_search`, `web_fetch`, `invoke_subagent`, `get_process_output`, `list_processes`, and the rest | `tool.invoked` |
+
+Two entries in that table are there because the generic classifier every runtime shares gets them wrong. `execute_bash` contains none of the words that classifier looks for, so Kiro's shell tool would otherwise be an unclassified `tool.invoked` — a shell execution missing from every query that looks for one. And `list_processes` and `get_process_output` read process state rather than run anything, so they are recorded as plain tool calls rather than as command executions.
+
+`aws` / `use_aws` is deliberately **not** `command.executed`. It does run the AWS CLI, but its arguments are a service, an operation, and a parameter map rather than a command string, so classifying it as a command would produce a command event with no command in it. It is recorded as the tool call it is, with the tool name intact.
+
+### The read tool's path lives in an array
+
+Kiro's most frequent tool takes an `operations` array rather than a `path`:
+
+```json
+{"hook_event_name": "preToolUse", "tool_name": "read",
+ "tool_input": {"operations": [{"mode": "Line", "path": "/repo/docs/hooks.md"}]}}
+```
+
+Asymptote reads it, so a read event carries a file. A call naming several files records the first — the endpoint schema's `file.path` is one string, and joining them would produce a value no rule matching on `file.path` could use.
+
+### Diffs, and what Asymptote will not guess
+
+Kiro does not publish its write tool's arguments, so the diff builder reads **both** plausible spellings of each field: `file_text`, `old_str`, and `new_str` from the Amazon Q Developer CLI lineage Kiro CLI descends from, and `content`, `old_string`, and `new_string` from the ecosystem convention.
+
+That is deliberately not guessing. A shape Asymptote cannot read produces **no diff**, never a wrong one — the event still records `file.modified` with the path and the operation, and only the diff is honestly unavailable.
+
+A failed write is never recorded as an edit. Kiro reports one with the same tool name and the same arguments as a success, and `success` on the result is the only thing that separates them; without that guard a diff would be built from a write that never landed.
+
+<Note>
+**`command` on a write is not a shell command.** Kiro's write tool descends from a multiplexed `fs_write` where `command` names the editor operation — `create`, `str_replace`, `insert` — and `command` is also what the shell tool calls its command line. Asymptote guards on the tool name, so an editor operation is never recorded under `command.command` and a real shell command is never dropped.
+</Note>
+
+## Approvals and enforcement
+
+**Asymptote records no approval decisions for Kiro, and does not synthesize any.**
+
+Kiro 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: Asymptote 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 Asymptote exits 0 on every other path.
+
+## Data handling
+
+Kiro content is handled like every other runtime. Prompts, tool arguments, commands, command output, paths, diffs, and the agent's final response are retained in local or customer-controlled logs, with local secret redaction and per-string limits applied before writing, and a hash and byte count on each content-bearing event. Events over the 64 KiB limit drop raw and retained content, preserve stable metadata, and set `field_truncated`.
+
+Unlike [Qwen Code](/runtimes/qwen-code) and [Muse Code](/runtimes/muse-code), Asymptote does **not** preserve the verbatim Kiro payload under a `raw` key. Kiro's envelope has no field left over once the readers have run, so keeping the payload would duplicate `tool_input` and `tool_response` — file contents included — to preserve nothing.
+
+## Known gaps
+
+- **No approval decisions.** Kiro exposes no approval or permission hook, and Asymptote does not synthesize one from `PreToolUse`. Approval rules and dashboards will show nothing for this runtime.
+- **No token usage or cost.** No Kiro hook payload carries token counts or cost. Kiro activity therefore does not appear in `beacon token-usage` reports or the dashboard token view.
+- **No spec task lifecycle.** Kiro's `PreTaskExec` and `PostTaskExec` triggers announce a spec task starting and finishing, and they are real signal with no duplicate elsewhere — but Kiro does not document what they put on stdin, and without a task id or name the event would say only that some task began. Asymptote does not subscribe to them. This is the one gap a published payload would close.
+- **No file-trigger events.** `PostFileCreate`, `PostFileSave`, and `PostFileDelete` are deliberately not subscribed to. Kiro's file triggers fire only for changes the agent made, and every such change goes through a write tool — so subscribing would record two events for one write with no way for a reader to tell they were the same action, and the duplicate would be the poorer of the two: a file trigger offers a path where `PostToolUse` carries the path, the operation, the content, and the result. Nothing is lost, and double-counting a file change in a security log is avoided.
+- **No per-session end event.** Kiro's `Stop` fires when the agent finishes a turn, not when a session ends, so it is recorded as `tool.completed` rather than `session.ended`. There is no session-end trigger to subscribe to.
+- **No tool call identity.** The hook payload carries no per-call identifier, so `gen_ai.tool.call.id` is absent and a pre-tool event cannot be joined to its post-tool event by id.
+- **No transcript path.** Kiro keeps session state in its own directory and no payload field points at it.
+- **No compaction or subagent events.** Kiro emits neither on a hook, so neither is recorded.
+- **Write argument shapes are inferred.** Kiro publishes its tool names and not its tool argument schemas. Asymptote reads both plausible spellings and records no diff when neither resolves — see [Diffs, and what Asymptote will not guess](#diffs-and-what-asymptote-will-not-guess).
+- **Kiro Web and Mobile do not read a user-scope install.** Neither surface has a local filesystem, so only hooks committed under a repository's `.kiro/hooks/` reach them.
+
+## Deployment notes
+
+Hooks are loaded when a session starts, so an install taken while Kiro is running takes effect on the next session. Restart Kiro, or start a new session, after installing or removing hooks.
+
+Confirm status, then generate one Kiro event and check the log:
+
+```bash
+beacon endpoint hooks status --harness kiro
+beacon endpoint doctor --system
+grep '"name":"kiro"' ~/.beacon/endpoint/logs/runtime.jsonl | tail -3
+```
+
+If Kiro telemetry is missing:
+
+- Confirm the Kiro version. `.kiro/hooks/*.json` needs IDE 1.0 or CLI 3.0; earlier versions use formats Asymptote does not write. In the CLI, `kiro-cli agent migrate` converts 2.x hooks.
+- Confirm the file exists at the scope you installed and contains commands with `--platform kiro`.
+- Check `$KIRO_HOME`: if it is set, the user-scope file is under that directory, not `~/.kiro`.
+- Confirm the file's `version` is `"v1"`. Kiro skips a hook file whose version it does not recognize, without an error.
+- Confirm hook timeouts are second values, not milliseconds.
+- Run `/config hooks` in a V3 session to see the hooks loaded for that session.
+- Start a new session so the updated registration is loaded.
+
+## Related
+
+<Columns cols={2}>
+ <Card title="Supported agent harnesses" icon="list-check" href="/runtimes">
+ Return to the runtime support overview.
+ </Card>
+ <Card title="Agent harness integration model" icon="plug" href="/runtimes/integration-model">
+ See how Asymptote discovers and configures each runtime.
+ </Card>
+</Columns>