5af1f6a8e5
`docs/tools/subagent.md` and `docs/tools/bash.md` both described their MCP server as injected "unconditionally". Both entries are `lib.mkDefault`, and the module says why one line above each: "so an agent.nix can still override/disable the entry", "so the operator's own agent.nix can override the entry". The word matters for the subagent one in particular. The same comment block records the framing that it is default-on for now and should become a real capability gate later, so "can I turn this off today?" is a question an operator has — and "unconditionally" answers it as "patch nix/" when the answer is one override in agent.nix. Both pages now say default, and say what the default yields to. The other direction on the same page: `subagentHttpPort`'s option description and the unit comment beside it both listed three tools, `start`/`continue`/`interrupt`. The daemon serves four. #4101, which introduced it, is titled with the three-verb phrasing, so `status` landed afterwards and never reached either description — while `subagent.md` had the full set all along. The option description renders into the generated options doc, so it is the one an operator reads. Closes #4231.
2.6 KiB
Subagent daemon
hive-subagent-daemon (crate hive-subagent-mcp) spawns nested headless
claude sessions on request. Own process, own systemd unit, own MCP
server (subagent, not hyperhive) — independent of hive-bash-daemon:
a subagent is a full nested claude process, a materially heavier
capability than a background shell command, so it gets its own
deployable/restartable unit rather than living inside the bash daemon.
Shipped default-on for every agent — nix/agent-modules/mcp.nix injects
subagent into hyperhive.extraMcpServers via lib.mkDefault
(allowedTools = ["*"]), same as bash. Default-on rather than
unconditional: an agent.nix can override or drop the entry, which is
what mkDefault is there for. The operator's own framing: default-on for
now, a real opt-in capability later.
For what the tools do and when an agent should reach for them, see the
subagent MCP server's own tool descriptions and the
base:claude-subagents skill — this page covers the daemon as deployed
infrastructure, not the agent-facing API.
Tools
Served under the subagent MCP server (mcp__subagent__<tool>): start,
continue, status, interrupt.
State
In-memory only: a map of currently running processes, live only as long
as the daemon process is. A daemon restart stops whatever was running
rather than adopting it. The durable record of a subagent's existence is
claude's own on-disk session (hive_claude::SessionStore), which
continue reattaches to independent of the daemon's own lifetime — a
restart loses the in-flight turn, not the subagent's history.
Compaction trade-off
Built on hive_claude::Claude::spawn + RunningClaude::wait directly
rather than InfiniteSession::run, since only the low-level driver
exposes a cancel handle to stop a turn mid-flight — that's what makes
interrupt genuinely stop a running turn rather than only cancelling a
still-pending one. The cost: a turn that overflows the context window
surfaces as an error rather than self-healing via reactive compaction.
Subagents are meant to be bounded, single-batch work, not sessions
long-lived enough to need in-place compaction — a real follow-up if that
assumption stops holding.
Configuration
hyperhive.mcp.subagentHttpPort — the daemon's streamable-http listen
port. Same pattern as bashHttpPort/matrixHttpPort: a per-agent default
assigned by nix/agent-modules/mcp.nix, only worth overriding for an
agent that needs a stable or non-default port.
Own systemd unit, defined alongside the other per-agent MCP daemons in
nix/agent-modules/mcp.nix.