> ## Documentation Index
> Fetch the complete documentation index at: https://beige.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Spawn Tool

{/* Run: pnpm run docs:sync-toolkit */}

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:

```bash theme={null}
beige tools install github:matthias-hausberger/beige-toolkit/tools/spawn
```

Or install all tools from the toolkit:

```bash theme={null}
# 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:

```json5 theme={null}
tools: {
  spawn: {
    config: {
      targets: {
        reviewer: {},
        coder: {},
      },
      maxDepth: 1,
    },
  },
},

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

**Sub-agent support** — every agent can spawn itself:

```json5 theme={null}
{
  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:

```json5 theme={null}
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/`