# 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.

### `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 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. A new agent's config repo is scaffolded by the swarm controller's
`InitAgentConfigRepo` job (`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 — call `update(name)` on affected
agents after the approval resolves.

## Boundary summary

| Operation                               | Requires approval? | Scope                        |
| --------------------------------------- | ------------------ | ---------------------------- |
| `kill` / `start` / `restart` / `update` | No                 | Own subtree                  |
| `list_containers`                       | No                 | Own subtree, caller included |
| `request_update_meta_inputs`            | Yes (MetaUpdate)   | Meta flake (global)          |

## See also

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