pb-nested-orchestrator

pb-nested-orchestrator — an agent that spawns its own sub-agents

Goal

Build a two-level tree: you spawn ONE parent; the parent spawns and supervises its own children through a scoped orchestration gateway; you inspect the whole tree from the root and tear it all down at the end.

Golden rule

The nesting PARENT must be adapter claude-code or claude-sdk. A hermes parent ignores the injected orchestration gateway (proven) and simply cannot spawn. Children can be any adapter.

Prerequisites (reference by name): ap-spawn-agent, ap-wait-fanin, ap-lifecycle, and the drive-agents group. Single-level supervision is pb-supervise-parallel-mission.

Steps

1. Spawn the parent as an orchestrator

agent_start({
  adapter: 'claude-code',
  cwd: '<ABSOLUTE host path>',
  label: 'orch-parent',
  orchestrator: true,
  prompt: '<parent brief - see step 3>'
})

orchestrator: true mounts a scoped sub-gateway in the parent: a curated tool subset — start/prompt/wait/poll/output + session_tree + subtree kill — with a per-child scope token that is revoked when the parent exits.

2. Prove the mount

The agent_start response carries an mcpServers entry whose ref ends in /mcp/orchestrator?scope=.... That entry is the proof the gateway is mounted. No entry, no nesting: re-spawn with orchestrator: true before briefing further — a hermes parent fails silently here, not loudly.

3. Brief the parent to use its tools

The parent brief MUST:

• NAME the orchestration tools it should use (its mounted gateway's start/prompt/wait/poll/output plus session_tree and subtree kill).
• FORBID shell poll loops, verbatim: "Never wait with a shell/terminal sleep-poll loop. Use session_monitor. A killed poll loop corrupts the session permanently."
• Give children authentic, bounded tasks (see gotchas) with disjoint ownership and absolute cwds — the same brief discipline as pb-supervise-parallel-mission, one level down.

4. Watch the tree grow from the root