feat(server): inherit host Claude Code plugins, carry MCP headers and sse (#700)

[edspencer]

Closes #700. Bumps @herdctl/core to 5.32.0 and consumes both capabilities
herdctl#446 added.

What changed

1. Host Claude Code plugins reach keepers (#700). New claude-plugins.ts
enumerates the host's installed plugin directories from the CLI's own
~/.claude/plugins/installed_plugins.json registry (v1 and v2) and passes them as
agent.plugins. A --plugin-dir plugin is a session plugin, whose enablement is
enabledPlugins["<name>@inline"] ?? manifest.defaultEnabled !== false — i.e.
enabled by default, needing no settings-source grant. That is precisely why the
passthrough works where the symlink did not, and #446 was right to refuse to widen
setting_sources.

2. headers and type: sse survive, so #699's warnings are gone. Proven, not
inferred — see below.

Two things that contradict the brief / #446's design notes

#446 says "paddock#700 is unblocked as written". As written is where it breaks.
#700 (and this PR's brief) scope plugin enumeration to claude.mcpServers: host.
But plugins/ is bridged by claude.instructions, alongside CLAUDE.md,
agents/ and commands/ — because most of a plugin is instructions. Under
instructions: own Paddock withdraws that symlink and prints a boot notice saying
the host's plugins are not loaded; passing them anyway because a different key
says host would contradict Paddock's own log. So both levers apply, to the two
halves of a plugin, and the SDK has exactly the flag for it:

claude.instructions	claude.mcpServers	a keeper gets
host	host	the plugin, whole
host	own	the plugin with skipMcpDiscovery: true (commands/agents/skills/hooks only)
own	any	no plugins — plus a notice naming the key to flip, when mcpServers: host is set

The allowlist is not "the same treatment". The brief says a plugin-provided
server "needs the same treatment — work out what its server names will be". They
are not the declared names. The CLI registers a plugin's servers as
`plugin:${pluginName}:${serverName}` and then normalises [^a-zA-Z0-9_-] → _
before it becomes a tool prefix, so the pattern is
mcp__plugin_<plugin>_<server>__*. Using the declared name would have produced
a pattern matching nothing — i.e. exactly the silent-auto-deny failure the rule
exists to prevent, with the allowlist code looking correct.

That derivation is not a guess: it is i8g() in the bundled CLI, and it lands on
the Agent SDK's own documented example, mcp__plugin_documents_docs__doc_export.

Evidence, and its limits

headers / type: sse — proven at the boundary, twice. Against the installed
5.32.0, FleetManager.addAgent() → getAgents() → toSDKOptions() returns
{type: "sse", url, headers} unchanged (and still infers type: "http" for a bare
url). The permanent form of that proof is a new integration assertion that reads
the agent back out of the live fleet, after AgentConfigSchema.parse — the one
place a stripped field is observable. I installed 5.31.0 and confirmed both new
integration tests fail there and pass on 5.32.0, so they are the dependency-floor
guard, not just code coverage. Every unit test in this PR passes on 5.31.x, which is
the point: the unit layer is where #699's bug hid.

Plugins — the enumeration is tested, the loading is not, by anyone. This box is
Linux with an empty plugin root, no marketplace and no credentials for a real turn.
The tests plant fake plugin directories and assert the config Paddock produces; none
is named as though a plugin loaded. herdctl's tests carry the next layer
(config → the SDK query() options); whether the CLI, handed --plugin-dir <dir>,
then loads it is the SDK's contract and is verified in neither repo.

Needs a real host with a plugin actually installed (a Mac work laptop is the
reported case):

• that a marketplace-installed plugin loads via type: "local" — still the open
  question Plugin-provided MCP servers cannot reach Paddock agents — needs a herdctl plugins passthrough #700 flags, and this PR does not close it;
• that a live plugin server really registers as plugin:<plugin>:<server>, so the
  derived allowlist pattern is the one the runtime checks;
• that a real installed_plugins.json matches the v2 shape read here. If it does
  not, Paddock enumerates nothing — it fails closed, quietly, which is the right
  direction but worth knowing.

A new cost, which the design notes do not mention

Carrying headers widens an existing exposure. herdctl's CLI runtime serialises
the whole mcp_servers record into one --mcp-config '{…}' argv element, readable
from /proc/<pid>/cmdline by any process of the same user. That was already true of
an env value; it is now true of an Authorization bearer, which is the likelier
place a long-lived token lives. Scope: driveMode: batch only (chats default to the
SDK runtime; the sweeper and triggers never get these servers). Not a reason to keep
stripping — a dropped header fails authentication for everyone, while this is a
same-user disclosure on one non-default drive mode — but documented in
claude-mcp.ts, mcp-servers.ts and CLAUDE.md rather than left to be discovered.

Also in scope, deliberately

The instance's own mcpServers: block hard-errored on headers and type: sse,
for the same reason the host lever warned. Leaving those in place would have refused
declarations that now work, with an error message stating something false about the
engine. Both are accepted; headers values take env:VAR_NAME references like
everything else in that block, are counted-not-printed by describeServer, and get
the same credential-shaped-key warning env values get.

Docs — for the overhaul chat, not touched here

website/**, README.md and NPM-README.md are untouched per the brief. Three
passages in website/src/content/docs/configuration/config-file.md are now wrong:

1. "Plugins are not covered by this key" (under claude.mcpServers, ~L389) —
   "none of them reach Paddock… the engine also has no way to pass a plugin path per
   session… until then, a plugin's MCP server has to be declared directly with
   claude mcp add." All three clauses are now false. Replacement is the lever table
   above.
2. "What cannot be declared" caution block (~L478) — the headers: and
   type: sse bullets should be deleted; the unrecognised-key and
   command-xor-url bullets stay.
3. The claude.mcpServers section could gain a line that headers and sse
   servers are now carried faithfully, which is what makes credentials: host +
   mcpServers: host work for an OAuth server at all.

Not done

• No web UI surface for plugins (the dashboard does not expose mcp_servers
  either).
• Did not widen setting_sources. Agreeing with docs(website): Running Paddock on Proxmox (LXC) guide (#414) #446, with one Paddock-specific
  observation recorded rather than acted on: Paddock's "user" scope is its own
  curated home, whose CLAUDE.md and settings.json the instructions/hooks
  levers already decide the contents of — so docs(website): Running Paddock on Proxmox (LXC) guide (#414) #446's blast-radius argument is weaker
  here than for a generic embedder. It is not zero, though: plugins/ in that home
  is a symlink to the host's real directory, so reading user settings would pull the
  host's enabledPlugins semantics back in and re-couple the levers. The explicit
  list needs no grant and keeps them apart.
• Project-scope plugin installs are passed like user-scope ones rather than being
  matched to a Paddock project's working directory. Doing that properly means
  deciding what a host projectPath means over here; not guessed at.
• No MCPB download. A plugin whose manifest points mcpServers at a bundle is
  attached, but its server names cannot be read statically, so its tools would be
  auto-denied. That is a boot warning naming the plugin and the
  mcp__plugin_<x>_<server>__* pattern to add by hand — the one case where this
  feature degrades, made loud instead of silent.

One correction to this PR's brief

npm run typecheck has been failing on this box with Property 'reapChatSession' does not exist on type 'FleetManager' — that is precisely the stale-install symptom
your bump should CURE.

It was a stale install, but the bump did not cure it — a clean npm install in
a fresh worktree did. Typecheck was already green here on 5.31.0, before the
dependency was touched. The declared ^5.31.0 range was fine; only the main
checkout's node_modules was old.

Verification

• env -u NODE_ENV npm test — green: server 1876 passed / 148 files, web 941
  passed / 70 files. Baseline on main in this worktree was also green, so nothing
  moved that was not meant to.
• env -u NODE_ENV npm run typecheck — clean, both packages.
• The two new integration tests were confirmed red on @herdctl/core@5.31.0 and
  green on 5.32.0.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying paddock with    Cloudflare Pages

Latest commit:	463e191
Status:	✅  Deploy successful!
Preview URL:	https://7483655e.paddock-7u2.pages.dev
Branch Preview URL:	https://feat-700-consume-herdctl-5-3.paddock-7u2.pages.dev

View logs

[edspencer]

Merged origin/main (f5cf1d2, PR #702) and integrated it rather than just resolving it.

#702 landed the same finding this PR documents independently — a declared server's env reaching the claude command line under driveMode: batch — but it measures it (declared-mcp-argv.test.ts reads the token back out of a real spawned process's argv) and turns it into a boot notice, which is strictly better than the prose I had written. So my duplicate module-doc paragraph is now a pointer to argvExposure.

One thing the merge made newly wrong, fixed here. #702's warning fires on servers that declare env values. This PR makes headers carryable, which puts an Authorization bearer into the same argv element — and a bearer is the likelier long-lived credential of the two. A url server declared with headers: and no env: was, after the textual merge, the one shape that warning silently missed. argvExposure now covers both, with a test.

Also updated: the website/src/content/docs/configuration/config-file.md caution block #702 added is correct as written, but the other block on that page ("What cannot be declared") still lists headers: and type: sse as refusals — that is in the docs-handoff list in the PR body, for the overhaul chat.