diff --git a/docs/turn-loop.md b/docs/turn-loop.md index f8ec8e35..18065494 100644 --- a/docs/turn-loop.md +++ b/docs/turn-loop.md @@ -389,6 +389,25 @@ it as a stdio child via `--mcp-config`. The hyperhive socket name is effort wake was still sent so the agent is not silently blocked. Exposed as `mcp__bash__status`. +**Agent lifecycle + config tools** (direct children only; requires +`lifecycle` or `approvals` tool group): + +- `kill(name)`, `start(name)`, `restart(name)`, `update(name)` — manage + a direct child sub-agent (graceful stop, start, stop+start, rebuild). + No approval required. Topology-enforced: `name` must be a direct child + per `topology.json`. Server rejects all other agent names. Requires + `lifecycle` tool group. +- `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 with a default + `agent.nix` template. `name` must be a direct child. Topology-enforced. + Fails if config already exists. Requires `approvals` tool group. +- `request_apply_commit(agent, commit_ref, description?)` — step 2 of + spawning a new direct child (or updating an existing child's config). + Submit a commit sha from the child's proposed config repo for operator + approval. `agent` must be a direct child. Topology-enforced. `commit_ref` + must be a 7-40 char hex sha. Requires `approvals` tool group. + ### Waking the agent from inside the container External MCP servers (and any other in-container process) can @@ -471,16 +490,25 @@ meta's. config creates the container. Fails if a proposed repo for this name already exists. (The operator can also direct-spawn an empty agent from the dashboard's `◆ R3QU3ST SP4WN` button, which routes - via `HostRequest::RequestSpawn`.) -- `kill(name)` — graceful stop. No approval required. -- `start(name)` — start a stopped sub-agent. No approval. -- `restart(name)` — stop + start. No approval. + via `HostRequest::RequestSpawn`.) Also available to agents for direct + children only (requires `approvals` tool group; see agent lifecycle + tools section above). +- `kill(name)` — graceful stop. No approval required. Also available to + agents for direct children only (requires `lifecycle` tool group; see + agent lifecycle tools section above). +- `start(name)` — start a stopped sub-agent. No approval. Also available + to agents for direct children only. +- `restart(name)` — stop + start. No approval. Also available to agents + for direct children only. - `update(name)` — rebuild (re-applies the current hyperhive flake + agent.nix, restarts). No approval, idempotent. Manager calls - this on receipt of a `needs_update` system event. + this on receipt of a `needs_update` system event. Also available to + agents for direct children only. - `request_apply_commit(agent, commit_ref)` — submit a config change for any agent (`root` for the manager's own config) for - operator approval. + operator approval. Also available to agents for direct children only + (requires `approvals` tool group; see agent lifecycle tools section + above). - `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 @@ -545,11 +573,14 @@ meta's. to inspect one agent. `cancel_loose_end` may cancel any agent's row. -The boundary: lifecycle ops on *existing* sub-agents -(`kill`/`start`/`restart`) are at the manager's discretion — no -operator approval. Creating a new agent (`request_init_config` → -`request_apply_commit` for the first sha) and changing any agent's -config (`request_apply_commit`) still go through the approval queue. +The boundary: lifecycle ops on *existing* direct children +(`kill`/`start`/`restart`/`update`) are discretionary — no operator +approval required (manager can do so for any sub-agent; agents can do so +only for direct children with `lifecycle` tool group). Creating a new +agent (`request_init_config` → `request_apply_commit` for the first sha) +and changing any agent's config (`request_apply_commit`) still go through +the approval queue (same topology scoping for agents: direct children only +with `approvals` tool group). ### Authoritative state