nested-orchestration

Nested orchestration (orchestrator-of-orchestrators)

Methodology + commands for turning an agent into a scoped orchestrator: it spawns its own sub-agents, supervises them (session_monitor), reads their outputs, and sees its subtree (session_tree). Distilled from a real session where every case below was proven live.

To be distinguished from the agent-session-orchestration-agentproto skill (flat orchestration: it's you, in cowork, driving the agents). Here we add a tier: you delegate the orchestration to a parent agent, which drives children. Useful when the breakdown is deep, when you want to offload the polling from your own context, or for a workflow that must run without you at every turn.

The principle in one line

parent claude-code (orchestrator:true) → spawns N children → session_monitor (fan-in) → reads the outputs → session_tree

The daemon mints a scope-token per orchestrator-child, injects the URL of a scoped sub-gateway into the parent's session (alongside any mcpServers you pass), and revokes the token on exit. The parent only receives a curated subset of orchestration tools — never shell / fs / remote / import / terminal.

Golden rule — the parent MUST be claude-code

Proven broken with hermes, working with claude-code. A hermes parent ignores the mcpServers field injected over ACP: it sees its own tools but not the orchestration gateway → it cannot spawn a sub-agent. claude-code mounts the gateway correctly (the ACP fix "mcpServers wire shape for session/new" was on the claude-code side). So: nesting ⇒ parent = claude-code. For the child, any adapter will do (cheap haiku for trivial work, hermes/lightweight for code — see light-coder-orchestration).

Making a parent an orchestrator

agent_start({
  adapter: "claude-code",
  model:   "claude-sonnet-4-6",   // reliable parent for driving
  orchestrator: true,             // ← auto-mounts the scoped sub-gateway
  cwd:     "<absolute HOST path>",
  label:   "parent-…",
  prompt:  "<orchestration brief>"
})