Spawn Tool

Spawn another Beige agent (or a sub-agent of yourself) and hold a multi-turn conversation with it. Each call returns the target agent’s full response plus a session key for follow-up turns.

Installation

Install this tool individually:

beige tools install github:matthias-hausberger/beige-toolkit/tools/spawn

Or install all tools from the toolkit:

# From npm
beige tools install npm:@matthias-hausberger/beige-toolkit

# From GitHub
beige tools install github:matthias-hausberger/beige-toolkit

Configuration

Key	Default	Description
targets	undefined (no spawns permitted)	Map of spawnable agent names to their config. Each key is a target agent name; value is an object with optional maxDepth. The special key "SELF" resolves to the calling agent’s own name at runtime. When absent or empty, all spawns are rejected.
targets.<name>.maxDepth	inherits top-level maxDepth	Maximum nesting depth for spawns to this specific target. Overrides the top-level default when set.
maxDepth	1	Default maximum nesting depth for targets that don’t specify their own. 0 = all spawns blocked. 1 = agents may spawn agents, but sub-agents may not spawn further.

No spawns are permitted until targets is explicitly configured — installing the tool changes nothing until you opt in. When any config is provided (even just maxDepth), the targets map must still be set to allow spawns.

Prerequisites

No external dependencies. The tool uses beige’s internal agent manager and session store.

The SELF Keyword

The special target key "SELF" resolves to the calling agent’s name at runtime, enabling sub-agent patterns without hardcoding agent names:

• When coder calls the tool, "SELF" → "coder"
• When reviewer calls the tool, "SELF" → "reviewer"

This is particularly useful in the top-level config — every agent with this tool gets the ability to spawn sub-agents of itself.

Depth Limiting

maxDepth	What is allowed
0	No spawns at all for this target
1 (default)	Agents may spawn agents; sub-agents may not spawn further agents
2	Two levels of nesting; agents at depth 2 may not spawn further agents

Each target can override the default maxDepth independently. For example, you might allow deep nesting for sub-agents (SELF: { maxDepth: 3 }) while keeping cross-agent spawns shallow.

Config Examples

Basic setup — coder and reviewer can spawn each other:

tools: {
  spawn: {
    config: {
      targets: {
        reviewer: {},
        coder: {},
      },
      maxDepth: 1,
    },
  },
},

agents: {
  coder:    { tools: ["spawn"] },
  reviewer: { tools: ["spawn"] },
},

Sub-agent support — every agent can spawn itself:

{
  tools: {
    spawn: {
      config: {
        targets: {
          "SELF": { maxDepth: 2 },
          reviewer: {},
        },
      },
    },
  },
}

Per-Agent Configuration (pluginConfigs)

Since beige supports per-agent pluginConfigs overrides (deep-merged with the top-level tool config), different agents can have different target lists:

tools: {
  spawn: {
    config: {
      // Baseline: every agent can spawn itself as a sub-agent
      targets: {
        "SELF": {},
      },
      maxDepth: 1,
    },
  },
},

agents: {
  // coder can additionally spawn reviewer
  coder: {
    tools: ["spawn"],
    pluginConfigs: {
      spawn: {
        targets: {
          reviewer: {},
        },
      },
    },
  },

  // reviewer can additionally spawn coder, with deeper nesting
  reviewer: {
    tools: ["spawn"],
    pluginConfigs: {
      spawn: {
        targets: {
          coder: { maxDepth: 2 },
        },
      },
    },
  },

  // assistant gets only the baseline (SELF sub-agents)
  assistant: {
    tools: ["spawn"],
  },
},

Note: pluginConfigs values are deep-merged with the top-level config. In the example above, coder’s effective targets are { "SELF": {}, reviewer: {} } — the baseline SELF entry is preserved and reviewer is added.

Security Model

Concern	How it is handled
Default deny	No spawns permitted unless targets is configured.
Target-level control	Only explicitly listed targets can be spawned.
Per-agent overrides	Use pluginConfigs to grant different agents different targets.
SELF keyword	Enables sub-agent patterns; resolves to caller’s own name at runtime.
Per-target depth cap	Each target can have its own maxDepth to prevent runaway recursion.
Unknown targets	Spawns of non-existent agents are rejected immediately.
Session integrity	Resuming a session with a mismatched --target is rejected.

Error Reference

Error	Cause
--target <agent> is required	No --target flag provided and --info not used
No targets configured	Config has no targets key or it’s empty
Target agent 'X' is not in the configured targets	Target not in the targets config (after SELF resolution)
Agent call depth limit reached	Session is at maxDepth for this target
Unknown agent 'X'	Target not defined in beige config
Session 'X' not found	--session key doesn’t exist
Session 'X' belongs to agent 'Y'	Session was created for a different target
No message provided	No message text or file given

Implementation Details

• Target: Gateway (runs on the host, not in the sandbox)
• No dependencies: Uses beige’s internal agent manager
• Session persistence: Sessions persist across gateway restarts in ~/.beige/sessions/