docs(turn-loop): document allowedRecipients, claudePlugins, cargo.shortMessages

Five per-agent agent.nix options were undocumented:

- hyperhive.allowedRecipients — restricts which peers send() accepts;
  note added inline to the send tool description
- hyperhive.claudeMarketplaces — Claude Code plugin marketplace sources
  (default: official Anthropic marketplace)
- hyperhive.claudePlugins — plugin specs installed at harness boot
- hyperhive.claudePluginsAutoUpdate — pull latest marketplace index
  before install; off by default
- hyperhive.cargo.shortMessages — shell wrapper injecting
  --message-format short on cargo compile subcommands; on by default
This commit is contained in:
iris 2026-06-05 18:05:52 +02:00 committed by mara
commit 3328b396e7

View file

@ -418,6 +418,52 @@ should talk to a different homeserver — for example a remote hive's
tuwunel reached over a VPN, or an external Matrix server for a
federation-only agent.
### Claude Code plugins
The harness installs Claude Code plugins before the serve loop opens.
Two per-agent `agent.nix` options control this:
```nix
hyperhive.claudeMarketplaces = [ "anthropics/claude-plugins-official" ]; # default
hyperhive.claudePlugins = [ "formatter@my-marketplace" ]; # default: []
hyperhive.claudePluginsAutoUpdate = false; # default
```
- **`claudeMarketplaces`** — list of marketplace sources passed to
`claude plugin marketplace add <source>`. The official Anthropic
marketplace is pre-configured by default; override or extend to add
custom marketplaces. Idempotent — re-adding an existing source is
a no-op.
- **`claudePlugins`** — list of plugin specs passed to
`claude plugin install <spec>`. Empty by default. Each spec is
installed on every boot (`install` is expected to be idempotent);
failures log a warning but do not abort boot.
- **`claudePluginsAutoUpdate`** — when `true`, runs
`claude plugin marketplace update` before installing plugins to pull
the latest index. Disabled by default to keep boot times short and
plugin versions pinned.
### `cargo.shortMessages`
```nix
hyperhive.cargo.shortMessages = true; # default
```
When enabled (the default), the harness injects a `cargo` shell
function into `/etc/hyperhive/bash-env.sh` that transparently appends
`--message-format short` to compile subcommands (`build`, `check`,
`clippy`, `test`, `run`, `doc`, `bench`, `install`, `rustc`, `fix`).
This suppresses the per-crate progress lines that flood the response
window, leaving only warnings and errors.
The function handles `+toolchain` selectors (`cargo +nightly build`)
and passes through cleanly when `--message-format` is already present.
Non-compile subcommands (`new`, `add`, third-party `cargo-*`) are
left untouched.
Set to `false` for agents that parse cargo's JSON output
programmatically and do not pass `--message-format json` themselves.
## MCP surface
The harness ships an embedded MCP server (rmcp 1.7). Claude launches
@ -439,7 +485,11 @@ ttl_seconds?, to?)`, `answer(id, answer)`.
(`to: "operator"`). Use `to: "<parent>"` to address the topology
parent without hardcoding the label; the broker resolves the
sentinel at delivery time. Optional `in_reply_to: i64` links the
message to a prior id for thread rendering.
message to a prior id for thread rendering. Per-agent
`hyperhive.allowedRecipients` (default: empty = unrestricted) limits
which names `send` accepts — useful for sandboxing: set
`[ "manager" ]` to restrict a sub-agent to manager-only chatter.
The manager is always reachable regardless of the list.
- `recv` — drain inbox. Without `wait_seconds` (or `0`) returns
immediately. Positive value parks the turn up to that many seconds
(cap 180) — incoming messages wake instantly. `max` (default 1, cap