78021ce982
Apply contraction fixes across ~40 doc files (setup, integrations, lifecycle, networking, scheduler, swarm, tools, trust-boundary, UI, etc.). Skipped 14 hits: - 10 where words appear in ALL CAPS for deliberate emphasis (is NOT, do NOT, etc.) - 4 where text could not be safely located due to markdown formatting or column position Applied via systematic scan with checks for fenced code blocks, inline code spans, and intentional caps. Preserves sentence-initial capitalization throughout.
3.1 KiB
Lifecycle and approvals tools
Two tool groups govern agent lifecycle management and config changes.
Both are scoped to direct children only (topology-enforced: the
server rejects any name that's not a direct child of the calling
agent per topology.json). Privileged agents (e.g. ruth) may operate
on any sub-agent — the topology scope applies to all others.
lifecycle tool group
No operator approval required. Direct children only.
kill(name)
Graceful stop. Container state is preserved; recreating the agent reuses prior config and credentials.
start(name)
Start a stopped sub-agent.
restart(name)
Stop + start in one call.
update(name)
Rebuild: re-applies the current hyperhive flake + agent.nix,
then restarts. Idempotent — safe to call repeatedly. Used in response
to needs_update system events.
list_containers()
List all descendant containers (children + their subtrees) with running status. Topology-scoped to descendants only.
approvals tool group
Config changes and new-agent spawns route through the operator approval queue. Direct children only (topology-enforced).
request_init_config(name, description?)
Step 1 of spawning a new direct child agent. Queues an InitConfig
approval; on operator approve, hive-c0re seeds the proposed config
repo at /agents/<name>/config/agent.nix with a default template and
delivers a config_ready system event. Then edit agent.nix, commit,
and the operator spawns the agent (the dashboard ◆ R3QU3ST SP4WN
button / Spawn approval, routed via HostRequest::RequestSpawn),
which creates the container from that config.
Subsequent config changes 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.
Fails if a proposed config repo for name already exists.
name is ≤ 9 characters.
request_update_meta_inputs(inputs?, description?)
Queue an approval to run nix flake update [inputs...] on the meta
flake. Pass specific input names (e.g. ["bitburner-agent"]) or omit
/ pass [] for all inputs. Returns immediately; the lock update runs
on operator approval.
Does NOT trigger container rebuilds — call update(name) on affected
agents after the approval resolves.
Boundary summary
| Operation | Requires approval? | Scope |
|---|---|---|
kill / start / restart / update |
No | Direct children |
list_containers |
No | All descendants |
request_init_config |
Yes (InitConfig) | New direct child only |
request_update_meta_inputs |
Yes (MetaUpdate) | Meta flake (global) |
See also
docs/agent-lifecycle/approvals.md— full approval flow, kinds, helper events (config_ready,approval_resolved), flake.lock validation.