From f4c3a8400bf1d58c031c9f16caa519fc5b97d4d4 Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Wed, 22 Jul 2026 14:31:36 -0600 Subject: [PATCH] docs: Added documentation for the new spawnable_agents whitelist property --- Agents.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 51 insertions(+), 9 deletions(-) diff --git a/Agents.md b/Agents.md index 3b3871c..526d354 100644 --- a/Agents.md +++ b/Agents.md @@ -533,20 +533,25 @@ see the [code-reviewer](https://github.com/Dark-Alex-17/coyote/blob/main/assets/ ## Spawning Configuration -| Setting | Type | Default | Description | -|-----------------------------|---------|---------------|--------------------------------------------------------------------------------| -| `can_spawn_agents` | boolean | `false` | Enable this agent to spawn child agents | -| `max_concurrent_agents` | integer | `4` | Maximum number of child agents that can run simultaneously | -| `max_agent_depth` | integer | `3` | Maximum nesting depth for sub-agents (prevents runaway spawning chains) | -| `inject_spawn_instructions` | boolean | `true` | Inject the default spawning instructions into the agent's system prompt | -| `summarization_model` | string | current model | Model to use for summarizing long sub-agent output (e.g. `openai:gpt-4o-mini`) | -| `summarization_threshold` | integer | `4000` | Character count above which sub-agent output is summarized before returning | -| `escalation_timeout` | integer | `300` | Seconds a sub-agent waits for an escalated user interaction response | +| Setting | Type | Default | Description | +|-----------------------------|-------------------|---------------|--------------------------------------------------------------------------------| +| `can_spawn_agents` | boolean | `false` | Enable this agent to spawn child agents | +| `spawnable_agents` | list of strings | *unset* | Whitelist of agent names this agent may spawn. Omit for unrestricted access. | +| `max_concurrent_agents` | integer | `4` | Maximum number of child agents that can run simultaneously | +| `max_agent_depth` | integer | `3` | Maximum nesting depth for sub-agents (prevents runaway spawning chains) | +| `inject_spawn_instructions` | boolean | `true` | Inject the default spawning instructions into the agent's system prompt | +| `summarization_model` | string | current model | Model to use for summarizing long sub-agent output (e.g. `openai:gpt-4o-mini`) | +| `summarization_threshold` | integer | `4000` | Character count above which sub-agent output is summarized before returning | +| `escalation_timeout` | integer | `300` | Seconds a sub-agent waits for an escalated user interaction response | **Example configuration:** ```yaml # agents/my-orchestrator/config.yaml can_spawn_agents: true +spawnable_agents: + - explore + - coder + - oracle max_concurrent_agents: 6 max_agent_depth: 2 inject_spawn_instructions: true @@ -555,6 +560,43 @@ summarization_threshold: 3000 escalation_timeout: 600 ``` +### Restricting which agents can be spawned (`spawnable_agents`) + +By default (i.e. when `spawnable_agents` is omitted), any agent installed under +`/agents/` is spawnable. + +To restrict, add a list of agent names. Only agents whose directory name +appears in the list will be spawnable. Anything else the agent tries to +spawn via `agent__spawn` is rejected with an actionable error, and hidden +from `agent__list_available` output. + +```yaml +can_spawn_agents: true +spawnable_agents: + - explore + - coder + - oracle +``` + +Use this to: +- **Scope an orchestrator to a focused set of specialists.** An orchestrator + that only needs `explore`/`coder`/`oracle` won't accidentally spawn + unrelated personal agents in your config directory. +- **Enforce team boundaries.** In a shared/CI setup, restrict what a given + agent is allowed to invoke. +- **Prevent recursion cycles.** Combined with `max_agent_depth`, an explicit + whitelist gives you fine-grained control over the spawn graph. + +Notes: +- Match is exact and case-sensitive. Use directory names as they appear on + disk. +- `spawnable_agents: []` means literally nothing spawnable (rare but valid). +- Graph agents (with a `graph.yaml`) always ignore `spawnable_agents`; they + statically declare their spawn targets via `agent` nodes in the graph + itself. +- Override at runtime via env var: `_SPAWNABLE_AGENTS` as a JSON + array (e.g. `SISYPHUS_SPAWNABLE_AGENTS='["explore","coder"]'`). + ## Spawning & Collecting Agents When `can_spawn_agents` is enabled, the agent receives tools for spawning and managing child agents: