hyperhive/docs/tools/lifecycle.md

Lifecycle and approvals tools

Two tool groups govern agent lifecycle management and config changes. The server scopes both to the caller's own subtree (topology-enforced per topology.json: a child, a child's child, every agent below them — plus the caller itself). No privileged class exists to belong to; the root agent reaches every agent purely because the check is transitive and everything sits under it.

lifecycle tool group

No operator approval required. The caller's own subtree.

list_containers()

List the caller's whole subtree with running status — children, their children, every agent below them. The calling agent is part of its own subtree, so it appears in its own listing; a leaf agent gets a one-row answer naming itself.

approvals tool group

Meta-flake input bumps route through the operator approval queue.

Creating a new agent is not in this group — agents have no tool for it. The swarm controller's InitAgentConfigRepo job scaffolds a new agent's config repo (POST /api/agents, see swarm-controller/), and the operator spawns the container from the dashboard (◆ R3QU3ST SP4WN / Spawn approval, routed via HostRequest::RequestSpawn).

Config changes on an existing agent go through a forge PR on the agent's agent-configs/<name> repo (queues a MergeConfigPr approval on open/update — no MCP tool involved), not a tool call. See docs/agent-lifecycle/approvals.md.

request_update_meta_inputs(inputs?, description?)

Queue an approval to run nix flake update [inputs...] on the meta flake. Pass specific input names (for example ["bitburner-agent"]) or omit / pass [] for all inputs. Returns immediately; the lock update runs on operator approval.

Doesn't trigger container rebuilds — the operator rebuilds affected agents after the approval resolves.

Boundary summary

Operation	Requires approval?	Scope
list_containers	No	Own subtree, caller included
request_update_meta_inputs	Yes (MetaUpdate)	Meta flake (global)

See also

• docs/agent-lifecycle/approvals.md — full approval flow, kinds, helper events (approval_resolved), flake.lock validation.