# 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 is 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/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/approvals.md`](../approvals.md) — full approval flow, kinds,
  helper events (`config_ready`, `approval_resolved`), flake.lock
  validation.