docs, mcp.nix: an overridable default is not unconditional, and there are four subagent tools

`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.
This commit is contained in:
atlas 2026-09-11 16:13:31 +02:00 committed by mara
commit 5af1f6a8e5
3 changed files with 11 additions and 8 deletions

View file

@ -2,10 +2,11 @@
Background shell execution via `hive-bash-daemon`. Tools land as
`mcp__bash__<tool>` (the MCP server name is `bash`, not `hyperhive`).
Available on every agent unconditionally — `nix/agent-modules/mcp.nix` always
injects bash into `hyperhive.extraMcpServers` (with `allowedTools =
["*"]`), so `mcp__bash__*` is in `--allowedTools` for every claude
invocation regardless of tool groups.
Available on every agent by default — `nix/agent-modules/mcp.nix` injects
bash into `hyperhive.extraMcpServers` via `lib.mkDefault` (with
`allowedTools = ["*"]`), so `mcp__bash__*` is in `--allowedTools` for
every claude invocation regardless of tool groups. Default rather than
unconditional: an `agent.nix` can override or drop the entry.
## Tools

View file

@ -8,8 +8,10 @@ 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` unconditionally (`allowedTools
= ["*"]`), same as `bash`. The operator's own framing: default-on for
`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

View file

@ -203,7 +203,7 @@ in
example = 8794;
description = ''
Loopback port `hive-subagent-daemon` serves its MCP tools
(`start`/`continue`/`interrupt`) on. Independent daemon (own crate,
(`start`/`continue`/`status`/`interrupt`) on. Independent daemon (own crate,
`hive-subagent-mcp`) a subagent spawns a full nested `claude`
process, a much heavier capability than a bash command, worth its own
deployable/restartable unit. Same shape/reasoning as
@ -308,7 +308,7 @@ in
# Subagent task runner daemon — independent of `hive-bash-daemon` (own
# crate, own process): spawns nested claude sessions on request, serves
# the `start`/`continue`/`interrupt` MCP tools directly over
# the `start`/`continue`/`status`/`interrupt` MCP tools directly over
# streamable-http on `hyperhive.mcp.subagentHttpPort`. No task files —
# this daemon's only state is an in-memory map of currently-running
# processes, live only as long as the process is (see