From 3328b396e78dfde81c5d32739bc555c74e043aaa Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Fri, 5 Jun 2026 18:05:52 +0200
Subject: [PATCH] docs(turn-loop): document allowedRecipients, claudePlugins,
 cargo.shortMessages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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
---
 docs/turn-loop.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 51 insertions(+), 1 deletion(-)

diff --git a/docs/turn-loop.md b/docs/turn-loop.md
index 4d295b82..6d3b0812 100644
--- a/docs/turn-loop.md
+++ b/docs/turn-loop.md
@@ -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