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: document DeepSeek Harness support
Claude2c5a7c8c55f4
diff --git a/CLAUDE.md b/CLAUDE.mdindex ebb49e40..2301ed0b 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -47,6 +47,7 @@ Supported runtime surfaces today:- 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. **Only the adapter half of this is implemented.** `cli/beacon-hooks/cmd/goose.go` maps the payloads and `NormalizeHarnessName` pins the name, so a `hooks.json` that invokes `beacon-hooks --platform goose` is collected correctly today. There is no installer: `goose` is not an accepted `beacon endpoint hooks install --harness` target, there is no `cli/beacon/internal/endpoint/hooks/goose.go`, and no `harness.DiscoverGoose` configures `otel_exporter_otlp_endpoint` in goose's `config.yaml`. Both files must be written by hand. `docs/runtimes/goose.mdx` and the README runtime table both describe the install commands as if they shipped; they have not. Close that gap before treating goose as a supported install target.+- DeepSeek Harness (`dsh`) hook telemetry through `@deepseek-ai/dsh-hooks-claude-code`, the Claude Code hook bridge DeepSeek ships as a dependency of the CLI but does not mount. Covers session start, prompts, pre-tool and post-tool activity, commands with output and exit code, file reads/creates/edits with diffs, MCP tool calls, subagent start/stop, and the turn-closing `Stop`. The harness is `deepseek_harness`; `dsh` is the `--platform` value, and bare `deepseek` plus every DeepSeek model spelling are deliberately unmapped in `NormalizeHarnessName` so a vendor or model id cannot masquerade as the runtime. The envelope is Claude Code's field for field and MCP tools are `mcp__server__tool`, so dsh rides the shared hook subcommands and `cli/beacon-hooks/cmd/dsh.go` holds no envelope or MCP reader -- only the tool taxonomy, the `str_replace_editor` multiplexed-`command` guard, `terminal_send`'s `text` command line, and the `[exit code: N]` marker that is the only place an exit status reaches a hook (the bridge flattens a tool result to text, so `tool_response` is a string). `run_code` is `tool.invoked` rather than `command.executed`: dsh dispatches a program's nested tool calls back through the guarded pipeline, so each fires its own hooks with a real command line, and a TypeScript program in `command.command` would match shell rules on its comments instead. dsh is in `rawPayloadKeys` largely for that tool, since non-MCP tool arguments reach no schema field. Installing takes two files, which is unique to this runtime: a hooks file Beacon owns at `$DSH_HOME/beacon-endpoint-hooks.json`, and one row in `$DSH_HOME/cordis.patch.yml` -- the user's own patch layer, edited as a yaml.Node document so comments, quoting and `!!js` tags survive. An empty patch file fails dsh boot, so an uninstall that would empty it removes it. There is no project scope: the bridge's `configPath` is process-level, so `--level project` is refused. Approval decisions are not exposed by the bridge (it supports seven events and `PermissionRequest` is not among them) and are not synthesized, matching the Cline, Pi, fx, OpenHands and Kiro decision. Not collected, because the bridge exposes none of it: token usage and cost, a session-end event, a per-tool error flag, compaction, and parent-session correlation for a subagent. Implementation lives in `cli/beacon-hooks/cmd/dsh.go` and `cli/beacon/internal/endpoint/hooks/dsh.go` plus `dsh_patch.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.- OpenClaw Gateway telemetry over two paths, collected together because neither is sufficient alone. The plugin path is a Beacon-managed plugin: OpenClaw discovers a plugin as the *directory* `beacon-endpoint` under an extensions root (user scope honours `OPENCLAW_STATE_DIR`; project scope is always `<workspace>/.openclaw/extensions`), holding three files -- a plain-JavaScript entry plus the `package.json` and `openclaw.plugin.json` that declare it, with the entry named under both `openclaw.extensions` and `openclaw.runtimeExtensions` so either host build reaches it. Ten of OpenClaw's forty-one typed hooks are registered, covering session lifecycle and resume, prompts, tool lifecycle, commands with exit code and output, file reads/creates/edits with diffs, `apply_patch` as one `file.modified` per changed path, MCP tool calls, compaction, subagent lifecycle, and token usage including cache reads and writes. The OTLP path is OpenClaw's own `diagnostics-otel` plugin, configured *inside OpenClaw* and only printed by `beacon endpoint integrations openclaw` (`cli/beacon/internal/endpoint/integrations/openclaw`); it carries gateway traces and metrics, and by OpenClaw's default carries no content at all. Both paths report the harness `openclaw_gateway`. Five contract details are load-bearing. OpenClaw registers `before_tool_call` **fail-closed**, so a handler that throws or exceeds its timeout blocks the tool call -- that handler therefore dispatches and returns synchronously with no promise to await, which costs event ordering and nothing else, since `gen_ai.tool.call.id` is the join. Conversation hooks, `llm_output` among them, are withheld from every non-bundled plugin until `plugins.entries.beacon-endpoint.hooks.allowConversationAccess` is set, so an otherwise perfect install collects everything except tokens and agent messages. Beacon reads OpenClaw's config and never writes it -- it is JSON *or JSON5*, and a Go round trip would strip an operator's comments out of the file configuring every chat channel they run -- so the installer prints advice instead, and only mentions `plugins.allow` when that key already exists, because introducing an allowlist would deny every other plugin. MCP tools are named `<server>__<tool>` with no `mcp` anywhere, so the separator is the only signal, as on goose. And `derivedPaths` arrives only on `before_tool_call`, so the plugin carries it forward by `toolCallId` -- without it an `apply_patch` is an opaque blob with no file rows. The prompt is `message_received`, the inbound chat message, not `llm_input`'s assembled prompt. Approval decisions are not exposed by OpenClaw's plugin hooks and are not synthesized, matching the Cline, Pi, goose, OpenHands and Kiro decision; the trap is that an `exec` result's `details.approvalReviewOutcome` reads like one and is a *model-backed* review, so it stays in `raw`. Not collected: reported cost (OpenClaw computes it from an operator-configured table rather than a provider report), and gateway lifecycle. Deliberately not registered: the prompt-injection, claim, gate and evaluate hooks, which would give Beacon power over the agent; `llm_input` and `agent_end`, which carry the whole conversation per call; and the two synchronous persistence hooks, which ignore promises. Implementation lives in `plugins/openclaw-beacon`, `cli/beacon-hooks/cmd/openclaw_event.go` and `cli/beacon/internal/endpoint/hooks/openclaw.go`.diff --git a/README.md b/README.mdindex dc682c51..6863d9c2 100644--- a/README.md+++ b/README.md@@ -162,6 +162,7 @@ for the full breakdown by surface.| <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/codex.png" alt="" width="16"> | [Codex CLI](https://docs.asymptotelabs.ai/cli/supported-runtimes-codex-cli) | OTLP + hook | ✅ | ✅ | ✅ | ✅ | – | ✅ | – | ✅ || <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/codex.png" alt="" width="16"> | [Codex Desktop](https://docs.asymptotelabs.ai/cli/supported-runtimes-codex-cli) | OTLP | ✅ | ✅ | ✅ | ✅ | – | ✅ | – | ✅ || <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/cursor.png" alt="" width="16"> | [Cursor](https://docs.asymptotelabs.ai/cli/supported-runtimes-cursor) | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | – |+| <img src="https://www.google.com/s2/favicons?domain=deepseek.com&sz=32" alt="" width="16"> | [DeepSeek Harness](https://docs.asymptotelabs.ai/runtimes/deepseek-harness) | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | – | ✅ | – || <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/devin.png" alt="" width="16"> | [Devin CLI](https://docs.asymptotelabs.ai/cli/supported-runtimes-devin) | Hooks | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | – || <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/devin.png" alt="" width="16"> | [Devin Desktop](https://docs.asymptotelabs.ai/cli/supported-runtimes-devin-desktop) | Hooks | – | ✅ | ✅ | ✅ | ✅ | – | ✅ | – || <img src="cli/beacon/internal/endpoint/dashboard/static/runtime-logos/factory.png" alt="" width="16"> | [Factory Droid](https://docs.asymptotelabs.ai/cli/supported-runtimes-factory-droid) | OTLP + hooks | ✅ | ✅ | ✅ | – | ✅ | – | – | – |diff --git a/cli/beacon/README.md b/cli/beacon/README.mdindex 0d569bbb..ec0eb8b6 100644--- a/cli/beacon/README.md+++ b/cli/beacon/README.md@@ -555,6 +555,9 @@ contract, what leaves the machine, and revocation../beacon endpoint hooks install --harness kiro./beacon endpoint hooks status --harness kiro+./beacon endpoint hooks install --harness dsh+./beacon endpoint hooks status --harness dsh+./beacon endpoint hooks install --harness hermes./beacon endpoint hooks status --harness hermes@@ -642,6 +645,31 @@ hook's stdout to the model's context, and an observing hook has nothing to say tthe model. The one exception is the optional policy seam, whose deny is exit code2 with the reason on stderr -- Kiro's documented way to block a tool call.+The DeepSeek Harness integration is the one install that takes two files,+because `dsh` reads no hooks file until something mounts a reader at it: the+harness composes itself from a plugin tree, and `@deepseek-ai/dsh-hooks-claude-code`+-- the Claude Code hook bridge DeepSeek ships as a dependency of the CLI -- is not+in the default tree. So Beacon writes `$DSH_HOME/beacon-endpoint-hooks.json`, a+hooks file it owns outright, and adds one row to `$DSH_HOME/cordis.patch.yml`+mounting the bridge at it. `$DSH_HOME` defaults to `~/.dsh`. The home-level patch+layer applies over every profile, so one install covers the CLI, Web, ACP and SDK+surfaces; there is no project scope, because the bridge's `configPath` is+process-level and a repository has nowhere to mount from, so `--level project` is+refused with that explanation rather than silently becoming a machine-wide+install.++The patch file is the user's own, and is edited as a document rather than+rewritten: parsed into a YAML node tree, one self-contained element appended or+removed, re-encoded from the same tree, so comments, quoting and `!!js`+expressions survive. Beacon refuses rather than rewriting a patch file it cannot+parse, one that is not a list of entries, or an insert element carrying its row+alongside rows it did not write. An uninstall that would leave the file empty+removes it instead: an empty or comments-only patch file fails `dsh` boot, while+an absent one is skipped cleanly. `hooks status` and `endpoint inventory` report+both files, because installed is the conjunction of the two -- a hooks file with+nothing mounted at it is a file nothing reads, and a mount pointing at a missing+hooks file registers nothing.+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, setdiff --git a/docs/docs.json b/docs/docs.jsonindex e505c898..741949cc 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -144,6 +144,7 @@"runtimes/cline","runtimes/codex-cli","runtimes/cursor",+ "runtimes/deepseek-harness","runtimes/devin","runtimes/devin-desktop","runtimes/factory-droid",diff --git a/docs/runtimes/deepseek-harness.mdx b/docs/runtimes/deepseek-harness.mdxnew file mode 100644index 00000000..9d1cbb30--- /dev/null+++ b/docs/runtimes/deepseek-harness.mdx@@ -0,0 +1,248 @@+---+title: "DeepSeek Harness"+description: "Asymptote support details for DeepSeek Harness (dsh) endpoint telemetry"+---++## Runtime overview++Asymptote supports DeepSeek Harness — DeepSeek's open agent harness, run as `dsh` — through the Claude Code hook bridge DeepSeek ships in the CLI, sent to `beacon-hooks`.++```bash+beacon endpoint hooks install --harness dsh+```++`--harness deepseek-harness` and `--harness deepseek_harness` are also accepted, and all three install the same thing.++DeepSeek Harness is composed rather than configured: every capability is a plugin, and the CLI, Web, ACP, and SDK surfaces are four compositions of one harness booting from one Harness home. There is one integration rather than one per surface, and one harness name — `deepseek_harness` — rather than a name per surface.++<Note>+**`dsh` does not read a hooks file until something mounts a reader at it.** `@deepseek-ai/dsh-hooks-claude-code` ships as a dependency of the `dsh` CLI but is not in the default plugin tree, so there is no convention that picks a hooks file up. That is why an Asymptote install here is **two files**: the hooks file, and one row mounting the bridge at it.+</Note>++## Prerequisites++Before enabling DeepSeek Harness telemetry, make sure:++- `dsh` is installed and has been run at least once, so the Harness home exists.+- `beacon endpoint install` has run so shared endpoint config and runtime log paths exist.+- `dsh` is restarted after hook install or removal, unless your profile enables HMR — the config watcher picks the patch layer up live, and without it the plugin tree is read at startup.++## Collection path++Asymptote writes two files into the Harness home:++| File | Owner | Purpose |+|------|-------|---------|+| `$DSH_HOME/beacon-endpoint-hooks.json` | Asymptote, outright | The Claude Code hooks file — one command hook per event |+| `$DSH_HOME/cordis.patch.yml` | **You** | Your patch layer. Asymptote adds one row mounting the bridge at the file above |++`$DSH_HOME` defaults to `~/.dsh`, and replaces it when set — matching how `dsh` resolves the Harness home itself.++The row Asymptote adds looks like this:++```yaml+# Beacon endpoint telemetry. Mounts DeepSeek's Claude Code hook bridge at+# a hooks file Beacon owns. Local only: the hooks make no network calls.+# Managed by `beacon endpoint hooks`; remove with `beacon endpoint hooks uninstall`.+- insert:+ - id: beacon-endpoint-hooks+ name: '@deepseek-ai/dsh-hooks-claude-code'+ config:+ configPath: '/home/you/.dsh/beacon-endpoint-hooks.json'+```++The home-level patch layer is applied over **every** profile and outranks each profile's own, so one install covers `dsh`, `dsh web`, the ACP server, and the SDK. `configPath` is absolute because the bridge resolves a relative path against the directory the process was launched from, which for an agent runtime is wherever you happened to be standing.++<Warning>+**There is no project scope.** The bridge's `configPath` is process-level — read once at startup — and per-session discovery of a project-local hooks file is unimplemented in the bridge itself. A repository has nowhere to mount a hook bridge from, so `--level project` is **refused with that explanation** rather than quietly becoming a machine-wide install. DeepSeek Harness is also left out of the project-level `--all` sweep for the same reason.+</Warning>++### Asymptote edits your patch file as a document++`cordis.patch.yml` is yours. It carries your comments, your quoting, and `!!js` expressions the loader evaluates at boot — so Asymptote parses it into a YAML node tree, appends or removes **one self-contained element**, and re-encodes from the same tree. Comments, scalar style, and custom tags survive that round trip, and a test pins it.++A self-contained element rather than a row pushed into one of your existing `insert:` lists, so an uninstall removes exactly what an install added.++Asymptote **refuses** rather than rewriting:++- a patch file it cannot parse — unlike the hooks file, which it will replace, because this is where your whole plugin tree is tweaked and `dsh`'s parser is not Go's;+- a patch file that is not a list of entries;+- an `insert` element carrying Asymptote's row alongside rows it did not write.++<Warning>+**An empty patch file does not boot `dsh`.** A present-but-empty or comments-only `cordis.patch.yml` fails startup — it is not ignored and it is not a warning. So an uninstall that would leave the file empty **removes the file** instead of truncating it. An absent patch layer is skipped cleanly.+</Warning>++### Registered events++The bridge supports seven of Claude Code's hook events. Asymptote registers all seven — there is nothing to leave out, because config for the other 23 is discarded before the bridge's parser sees it.++| Event | 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 |+| `SubagentStart` | `subagent-start` | 10 s |+| `SubagentStop` | `subagent-stop` | 10 s |++Timeouts are **seconds**, matching Claude Code — the bridge reads `timeout` as `timeoutSec`. Its own default is 600 seconds, which is a very long time to hold an agent turn for a hook that finishes in milliseconds; Asymptote writes explicit lower values as ceilings on a hang, not budgets.++Asymptote's hooks carry no `matcher`. An absent matcher is the match-all form in this dialect, which is what a telemetry hook wants on all seven — and the bridge validates a written matcher at parse time and rejects the **whole config** on a bad one, so the value that needs no validating is the safer one to write.++## Discovery and status++```bash title="Show DeepSeek Harness hook status"+beacon endpoint hooks status --harness dsh+```++Status reports **both** paths, because `installed` is the conjunction of the two files: a hooks file with nothing mounted at it is a file nothing reads, and a mount pointing at a missing hooks file is a bridge that logs a warning and registers nothing. `beacon endpoint inventory` lists both for the same reason, so a half-install is visible as a half-install.++DeepSeek Harness reports as the `deepseek_harness` harness with capability `hooks`, and every event carries `harness.collection_method=hook`. The bridge is a plugin, but it is DeepSeek's plugin, shipped and versioned with the CLI; what Asymptote contributes is command hooks, and the thing that runs on each event is the same `beacon-hooks` binary every other hook runtime runs.++## Install or configuration support++```bash+beacon endpoint hooks install --harness dsh+beacon endpoint hooks status --harness dsh+beacon endpoint hooks uninstall --harness dsh+```++Re-running the install rewrites the hooks file wholesale and **repoints** the mount in place rather than adding a second one — so a reinstall after `$DSH_HOME` moved updates the path the bridge reads, and a repair does not end with each event registered twice.++Uninstall removes Asymptote's hooks file and its one patch element, and leaves your rows and comments alone.++## Telemetry coverage++| Area | Support |+|------|---------|+| Runtime discovery | Supported through both files in the Harness home |+| Harness attribution | Supported. `dsh`, `dsh_cli`, `dsh-cli`, `dshcli`, `deepseek_harness`, `deepseek-harness`, `deepseekharness`, `deepseek-ai/dsh`, and `@deepseek-ai/dsh` normalize to `deepseek_harness` |+| Hook install, status, uninstall, and repair | Supported at user scope |+| 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, with `gen_ai.tool.call.id` from `tool_use_id` |+| Commands | Supported. `command.executed` with the command, its output, and its exit code |+| File activity | Supported. `file.read` and `file.modified` with paths, operations, and diffs |+| MCP activity | Supported. Recognized from `mcp__<server>__<tool>`, with the server and tool split out |+| Subagents | Supported. `subagent.started` and `subagent.stopped` |+| Approval decisions | Not collected. See [Known gaps](#known-gaps) |+| Token usage and cost | Not collected. See [Known gaps](#known-gaps) |+| Failed tools | Not collected. See [Known gaps](#known-gaps) |+| Local JSONL and dashboard | Supported |+| MDM deployment | Supported for the endpoint agent. Hooks are installed in the logged-in user's Harness home |++### Tool taxonomy++`dsh` publishes a generated tool catalog with both names and full argument schemas, so classification is backed by schemas rather than inferred from names, and is exhaustive over what the catalog lists:++| Tool | Recorded as |+|------|-------------|+| `read`, `read_image`, `glob`, `grep` | `file.read` |+| `write` | `file.modified`, operation `create` |+| `edit` | `file.modified`, operation `modify` |+| `str_replace_editor` | `file.read` or `file.modified`, per its `command` argument |+| `bash`, `pwsh` | `command.executed`, with `command.output` and `command.exit_code` |+| `terminal_send` | `command.executed`, with the submitted `text` as the command |+| `mcp__<server>__<tool>` | `mcp.tool_invoked`, with `mcp.server` and `mcp.tool` |+| `run_code`, `terminal_read`, `terminal_list`, `job_*`, `subagent`, `skill`, `workflow`, and the rest | `tool.invoked` |++Four entries in that table are there because the generic classifier every runtime shares gets them wrong. `write` and `edit` — the two most common write tools — contain none of the words it looks for. `terminal_read` and `terminal_list` contain "terminal", which it reads as shell execution; both read retained output or enumerate sessions, and neither runs anything.++### `terminal_send` names its command line `text`++`dsh` runs commands through a persistent terminal as well as through `bash`, and that tool's payload is `text`, not `command`. Asymptote reads it, so a command run through a terminal session carries a command line rather than being an empty `command.executed` invisible to every rule matching on `command.command`.++A call with `submit: false` is still read. It carries control characters or an incomplete REPL line rather than a whole command, so what is recorded is a *fragment* of shell input — worth knowing, and better than letting "send the command in two writes" be a way to run commands Asymptote does not record.++### `run_code` is a tool call, not a command++`run_code` executes a TypeScript program against the other tools and is the one tool that can ask for `danger-full-access`. Asymptote records it as `tool.invoked`, for two reasons.++A program's nested tool calls are **not invisible**: `dsh` dispatches them back through the complete guarded tool pipeline, which is the same seam the hook bridge listens on. So `await tools.bash({command: '...'})` inside a program fires its own `PreToolUse` and `PostToolUse` and is recorded as a command execution with a real command line. Classifying the outer wrapper as a command too would double-count it.++And `command.command` is a *shell* command line — every threat rule that reads it is written in shell terms. A TypeScript program in that field would match those rules on its comments and string literals while matching none of them on what it does, and it would do so *instead of* the precise nested events.++The program text is not lost: it is retained under `raw.dsh.tool_input.code`, redacted and size-limited like every other field.++### Exit codes come from the output text++The bridge flattens a tool result to text before a hook sees it, so `tool_response` is a plain string rather than an object. `dsh`'s `bash` and `pwsh` tools report a non-zero exit as `[exit code: N]` in that text, and that marker is the only place an exit code reaches a hook.++Asymptote reads the **last** marker in the output: everything above it is the command's own, and a command that prints something looking like the marker — a test asserting on one, a log line quoting one — would otherwise decide the event's exit code.++A non-zero exit is recorded as `command.executed` with `command.exit_code`, not as a tool failure. A failing test run is an ordinary outcome of a command that ran.++<Note>+**`command` on `str_replace_editor` is not a shell command.** That tool multiplexes `view`, `create`, `str_replace`, and `insert` onto a `command` argument, and `command` is also what `bash` and `pwsh` call their 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. `view` is the case that matters most: same tool, same arguments as the three writes, and only that word separates looking from creating.+</Note>++## Approvals and enforcement++**Asymptote records no approval decisions for DeepSeek Harness, and does not synthesize any.**++The bridge supports seven events and `PermissionRequest` is not among them, so there is no approval decision anywhere on this runtime's hook surface. `PreToolUse` announces a call the agent is about to make, not a question anybody was asked. This is the same call already settled for [Cline](/runtimes/cline), [Pi](/runtimes/pi), [OpenHands](/runtimes/openhands), [Kiro](/runtimes/kiro), and [fx](/runtimes/vercel-fx).++Asymptote's observing hooks answer with an empty JSON object, which the bridge's decoder reads as no opinion. They deliberately do **not** answer `allow`: on this runtime that is a real pre-approval, so an observing hook answering it would be disarming your permission gate for every tool call rather than watching it.++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. DeepSeek Harness is one of the runtimes where a provider deny takes effect, using Claude Code's deny shape — which is the shape the bridge's decoder reads:++```json+{"hookSpecificOutput": {"hookEventName": "PreToolUse",+ "permissionDecision": "deny",+ "permissionDecisionReason": "..."}}+```++`hookEventName` must equal the firing event or the bridge discards the whole block; it passes the event name in as a guard precisely to stop a hook answering for an event that is not running.++## Data handling++DeepSeek Harness content is handled like every other runtime. Prompts, tool arguments, commands, command output, paths, and diffs 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 [Kiro](/runtimes/kiro) and [OpenHands](/runtimes/openhands), Asymptote **does** preserve the verbatim payload under `raw.dsh`, as it does for [Qwen Code](/runtimes/qwen-code) and [Muse Code](/runtimes/muse-code). Non-MCP tool arguments reach no endpoint-schema field on any runtime, so on `dsh` this is where `run_code`'s program, a `glob` or `grep` pattern, a `terminal_send` `submit` flag, and `SessionStart`'s `source` survive. The cost is stated rather than hidden: on a `write` the payload repeats the file content the diff already carries. `raw` is the first thing dropped at the size ceiling, so the duplication is bounded and the diff is what survives.++## Known gaps++- **No approval decisions.** The bridge exposes no `PermissionRequest` event, and Asymptote does not synthesize one from `PreToolUse`. Approval rules and dashboards will show nothing for this runtime.+- **No token usage or cost.** The bridge builds each payload from a fixed base plus per-event fields, and no usage count is among them on any of the seven events. `dsh` does record usage in its own session log; nothing on the hook surface exposes it. DeepSeek Harness activity therefore does not appear in `beacon token-usage` reports or the dashboard token view.+- **No failed-tool events.** The bridge hands a hook the result's flattened text and nothing else, so a tool that threw is indistinguishable at the hook from one that returned. `tool.failed` is never recorded, and a diff is built from a write's arguments whether or not the write landed. A non-zero shell exit is *not* a tool failure and is recorded as such.+- **No session-end event.** `dsh` has no `SessionEnd`. `Stop` fires when a turn finishes, not when a session ends, so it is recorded as `tool.completed`.+- **No transcript path.** The bridge always sends `transcript_path` as the empty string: the persistence seam exposes no artifact path, and the default session log is Zstandard-compressed and not readable by a hook script.+- **No compaction events.** `PreCompact` and `PostCompact` are among the events the bridge does not support.+- **Subagent detail is thin.** The bridge reports a constant `agent_type` of `general-purpose` and uses the child's session id where Claude Code reports the parent's, so a subagent event cannot be joined to the session that spawned it.+- **No project scope.** See the warning under [Collection path](#collection-path).+- **Only command hooks run.** The bridge runs shell-form `command` handlers only, which is what Asymptote writes. It has no bearing on Asymptote's install and is noted because it bounds what else you can put in the same file.++## Deployment notes++The plugin tree is read at startup unless your profile enables HMR, so an install taken while `dsh` is running takes effect on the next start. The install prints that reminder.++Confirm status, then generate one event and check the log:++```bash+beacon endpoint hooks status --harness dsh+beacon endpoint doctor --system+grep '"name":"deepseek_harness"' ~/.beacon/endpoint/logs/runtime.jsonl | tail -3+```++If DeepSeek Harness telemetry is missing:++- Confirm **both** files exist. `beacon endpoint hooks status --harness dsh` prints both paths; either one alone is inert.+- Check `$DSH_HOME`: if it is set, both files are under that directory, not `~/.dsh`.+- Confirm the mount's `configPath` points at the hooks file that is actually there. A reinstall repoints it.+- Confirm the hooks file contains commands with `--platform dsh`.+- Preview the composed configuration with `dsh --dump-config` to confirm the bridge row is in the tree the profile mounts.+- Check the startup log under `$DSH_HOME/logs/` for a `hooks-claude-code` warning. A config the bridge cannot read registers **no** hooks and says so only there.+- Restart `dsh` so the updated plugin tree 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>diff --git a/docs/runtimes/index.mdx b/docs/runtimes/index.mdxindex 1e3d5633..5f2579a1 100644--- a/docs/runtimes/index.mdx+++ b/docs/runtimes/index.mdx@@ -25,6 +25,7 @@ These integrations are grouped by where the agent runs and how telemetry is coll| [Cline](/runtimes/cline) | Managed plugin hooks | Prompts, task lifecycle, tool lifecycle, commands, file reads and edits with diffs, MCP activity, and token usage || [Codex CLI](/runtimes/codex-cli) | Local OTLP logs and a selective usage trace plus endpoint hooks | Session, prompt, approval, and tool-result activity plus per-user/session/model turn token usage || [Cursor](/runtimes/cursor) | Native hooks | Prompt, tool, shell command, MCP-like, approval, and file edit telemetry |+| [DeepSeek Harness](/runtimes/deepseek-harness) | DeepSeek's own Claude Code hook bridge, mounted by a Beacon row in `$DSH_HOME/cordis.patch.yml` at a hooks file Beacon owns | Session start, prompts, pre-tool and post-tool activity, commands with output and exit code, file reads and edits with diffs, MCP tool calls, subagent start and stop, and the turn-closing stop. No approval decisions, token usage, or failed-tool events, because the bridge exposes none of them on a hook || [Devin CLI](/runtimes/devin) | Native hooks | Session, prompt, pre-tool, post-tool, permission request, stop, session-end, approval, and file telemetry || [Devin Desktop](/runtimes/devin-desktop) | Cascade/Windsurf hooks | Prompt, command, MCP tool, file read, and file write telemetry where Desktop exposes Cascade hook payloads || [Factory Droid](/runtimes/factory-droid) | OTLP HTTP plus optional hooks | Session, prompt, write/edit/create tool use, stop, session-end, and available OTLP telemetry |