0a80f21003
`require_descendant` (`socket_server/mod.rs:666`) authorises
kill/start/restart/update/get_logs with `topology::is_descendant_of` — the
caller's whole subtree, itself included. That has been true since `53b4e752`
(#1865), whose message says "a parent owns its whole subtree; the root covers
every agent as a consequence, no positional privilege", and two tests pin it
(`is_descendant_of_in_grandchild`, `is_descendant_of_in_self_is_true`).
The prose never followed. The four lifecycle tool descriptions, their
`// IMPORTANT:` comments, `docs/tools/lifecycle.md`, the tools README,
hive-agent-mcp's README and the system prompt every agent is rendered from all
still said "direct children only" — while `list_containers`, four tools away in
the same file, said "direct children + their subtrees".
`lifecycle.md` also taught the model #1865 deleted: "Privileged agents (for
example ruth) may operate on any sub-agent — the topology scope applies to all
others." There is no privileged class to belong to; ruth reaches every agent
because the check is transitive and everything sits under it.
Same drift on the state-query side: `resolve_agent_state_target` is
subtree-scoped by the same commit, so `get_loose_ends`' argument doc, the
`QueryAgentState` capability doc and `docs/turn-loop/mcp.md` were all telling a
parent it needs a capability to read a grandchild's threads.
Two smaller corrections found on the way:
* `list_containers` returns the caller itself. `is_descendant_of` is true for
`candidate == ancestor` and `handle_list_descendants` filters the topology
with it; called from a leaf agent it answers one row, that agent.
* `request_init_config` accepts any unused name — the requester becomes its
parent — or an existing agent already in the caller's subtree, not "a direct
child". The editing surface is narrower than the guard, though: only direct
children's config repos are bind-mounted, so re-seeding deeper in the subtree
leaves no local copy to edit. `lifecycle.md` now says so.
The prompt's other stale claim, the dead `request_apply_commit`, is #4226 and
was fixed independently by damocles in #4227 while this was being gated. This
branch keeps only the scope wording on that line.
Closes #4225.
49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
# Tools
|
|
|
|
`hivectl` is _your_ tool — the operator's own host CLI. Everything
|
|
else here documents the tool surface your **agents** get inside their
|
|
containers (the MCP tools an agent's own claude session can call).
|
|
You never call these directly, but they're the reference for what an
|
|
agent can actually do — useful when you're trying to understand or
|
|
debug agent behavior.
|
|
|
|
## For the operator
|
|
|
|
- **[hivectl](hivectl.md)** — the curated guide: provisioning forge
|
|
and matrix accounts, gateway htpasswd management, container
|
|
lifecycle shortcuts, interactive agent shell access.
|
|
- **[hivectl-cli](hivectl-cli.md)** — the exhaustive, autogenerated
|
|
flag-by-flag reference, kept in lockstep with the binary by CI.
|
|
|
|
## For the swarm operator
|
|
|
|
- **[swarmctl-cli](swarmctl-cli.md)** — the exhaustive, autogenerated
|
|
flag-by-flag reference for `swarmctl`, kept in lockstep with the
|
|
binary by CI the same way `hivectl-cli.md` is. `swarmctl` itself
|
|
runs as root on the swarm-controller host, not through `hivectl` —
|
|
see `swarmctl/README.md` for why. No curated guide yet (one verb,
|
|
`user add`, doesn't need one); add one here if/when that grows.
|
|
|
|
## What your agents can do
|
|
|
|
- **[bash](bash.md)** — background shell execution (`mcp__bash__*`),
|
|
available on every agent unconditionally.
|
|
- **[subagent](subagent.md)** — spawn nested headless claude sessions
|
|
(`mcp__subagent__{start,continue,status,interrupt}`), shipped
|
|
default-on for every agent today alongside `bash` (expected to become a
|
|
real opt-in capability later).
|
|
- **[forge](forge.md)** — the `hive-forge` Forgejo CLI every agent has
|
|
for issues, PRs, and comments. Not an MCP tool — a binary agents
|
|
shell out to instead of ad-hoc curl.
|
|
- **[forge-cli](forge-cli.md)** — the exhaustive, autogenerated
|
|
flag-by-flag reference for `hive-forge`, kept in lockstep with the
|
|
binary by CI the same way `hivectl-cli.md` is.
|
|
- **[lifecycle](lifecycle.md)** — kill/start/restart/update for the
|
|
agents in a caller's own subtree, plus the approval-gated
|
|
config-change tools.
|
|
- **[matrix](matrix.md)** — the matrix MCP tool surface
|
|
(`mcp__matrix__*`) for agents with a matrix account, multiple
|
|
accounts per agent, and declaring extra MCP servers generally.
|
|
- **[scheduling](scheduling.md)** — scheduled prompts (operator
|
|
approval required) and the diagnostics tools (`get_logs`,
|
|
`get_host_journal`).
|