Sub-agents
Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (agent:<agentId>:subagent:<uuid>) and, when finished, announce their result back to the requester chat channel.
Slash command
Use/subagents to inspect or control sub-agent runs for the current session:
/subagents list/subagents kill <id|#|all>/subagents log <id|#> [limit] [tools]/subagents info <id|#>/subagents send <id|#> <message>/subagents steer <id|#> <message>/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]
/focus <subagent-label|session-key|session-id|session-label>/unfocus/agents/session idle <duration|off>/session max-age <duration|off>
/subagents info shows run metadata (status, timestamps, session id, transcript path, cleanup).
Spawn behavior
/subagents spawn starts a background sub-agent as a user command, not an internal relay, and it sends one final completion update back to the requester chat when the run finishes.
- The spawn command is non-blocking; it returns a run id immediately.
- On completion, the sub-agent announces a summary/result message back to the requester chat channel.
- For manual spawns, delivery is resilient:
- WednesdayAI tries direct
agentdelivery first with a stable idempotency key. - If direct delivery fails, it falls back to queue routing.
- If queue routing is still not available, the announce is retried with a short exponential backoff before final give-up.
- WednesdayAI tries direct
- The completion handoff to the requester session is runtime-generated internal context (not user-authored text) and includes:
Result(assistantreply text, or latesttoolResultif the assistant reply is empty)Status(completed successfully/failed/timed out/unknown)- compact runtime/token stats
- a delivery instruction telling the requester agent to rewrite in normal assistant voice (not forward raw internal metadata)
--modeland--thinkingoverride defaults for that specific run.- Use
info/logto inspect details and output after completion. /subagents spawnis one-shot mode (mode: "run"). For persistent thread-bound sessions, usesessions_spawnwiththread: trueandmode: "session".- For ACP harness sessions (Codex, Claude Code, Gemini CLI), use
sessions_spawnwithruntime: "acp"and see ACP Agents.
Completion delivery
completionDelivery applies to sessions_spawn calls with runtime: "subagent" and to
runtime: "acp" calls with mode: "run". Thread-bound ACP sessions (mode: "session") ignore
it: their output goes straight to the bound thread.
Top-level sub-agent completions use parent-first delivery by default. The completion is
passed to the parent as an internal task_completion event, and the parent model turn
authors the user-facing reply. This keeps raw child output out of the channel and lets the
parent synthesize sibling results or return NO_REPLY when no response is needed.
Use completionDelivery: "direct" when a top-level sub-agent completion must be sent straight
to the requester channel in the existing completion format. Direct delivery is suppressed while
sibling or descendant sub-agent runs are pending; the completion follows the parent agent-turn
path instead of being sent externally immediately. Nested requesters remain internal: their child
completions are delivered to their parent and are not externally delivered. The parent mode is
the default.
You can select the mode at either of these configuration levels:
sessions_spawn parameter:
agents.list[].subagents.completionDelivery, the global
agents.defaults.subagents.completionDelivery, and finally parent.
Cron job announces always use direct delivery, regardless of these settings. Thread-bound
and other forced direct routes keep their existing direct behavior.
Primary goals:
- Parallelize “research / long task / slow tool” work without blocking the main run.
- Keep sub-agents isolated by default (session separation + optional sandboxing).
- Keep the tool surface hard to misuse: sub-agents do not get session tools by default.
- Support configurable nesting depth for orchestrator patterns.
agents.defaults.subagents.model or per-agent overrides.
Tool
Usesessions_spawn:
- Starts a sub-agent run (
deliver: false, global lane:subagent) - Then runs an announce step and posts the announce reply to the requester chat channel
- Default model: inherits the caller unless you set
agents.defaults.subagents.model(or per-agentagents.list[].subagents.model); an explicitsessions_spawn.modelstill wins. - Default thinking: inherits the caller unless you set
agents.defaults.subagents.thinking(or per-agentagents.list[].subagents.thinking); an explicitsessions_spawn.thinkingstill wins. - Default run timeout: if
sessions_spawn.runTimeoutSecondsis omitted, WednesdayAI usesagents.defaults.subagents.runTimeoutSecondswhen set; otherwise it falls back to0(no timeout).
task(required)label?(optional)agentId?(optional; spawn under another agent id if allowed)model?(optional; overrides the sub-agent model; an invalid or disallowed value fails the spawn with an error instead of starting the run)thinking?(optional; overrides thinking level for the sub-agent run)runTimeoutSeconds?(defaults toagents.defaults.subagents.runTimeoutSecondswhen set, otherwise0; when set, the sub-agent run is aborted after N seconds)thread?(defaultfalse; whentrue, requests channel thread binding for this sub-agent session)mode?(run|session)- default is
run - if
thread: trueandmodeomitted, default becomessession mode: "session"requiresthread: true
- default is
cleanup?(delete|keep, defaultkeep)sandbox?(inherit|require, defaultinherit;requirerejects spawn unless target child runtime is sandboxed)sessions_spawndoes not accept channel-delivery params (target,channel,to,threadId,replyTo,transport). For delivery, usemessage/sessions_sendfrom the spawned run.
Thread-bound sessions
When thread bindings are enabled for a channel, a sub-agent can stay bound to a thread so follow-up user messages in that thread keep routing to the same sub-agent session.Thread supporting channels
- Discord (currently the only supported channel): supports persistent thread-bound subagent sessions (
sessions_spawnwiththread: true), manual thread controls (/focus,/unfocus,/agents,/session idle,/session max-age), and adapter keyschannels.discord.threadBindings.enabled,channels.discord.threadBindings.idleHours,channels.discord.threadBindings.maxAgeHours, andchannels.discord.threadBindings.spawnSubagentSessions.
- Spawn with
sessions_spawnusingthread: true(and optionallymode: "session"). - WednesdayAI creates or binds a thread to that session target in the active channel.
- Replies and follow-up messages in that thread route to the bound session.
- Use
/session idleto inspect/update inactivity auto-unfocus and/session max-ageto control the hard cap. - Use
/unfocusto detach manually.
/focus <target>binds the current thread (or creates one) to a sub-agent/session target./unfocusremoves the binding for the current bound thread./agentslists active runs and binding state (thread:<id>orunbound)./session idleand/session max-ageonly work for focused bound threads.
- Global default:
session.threadBindings.enabled,session.threadBindings.idleHours,session.threadBindings.maxAgeHours - Channel override and spawn auto-bind keys are adapter-specific. See Thread supporting channels above.
agents.list[].subagents.allowAgents: list of agent ids that can be targeted viaagentId(["*"]to allow any). Default: only the requester agent.- Sandbox inheritance guard: if the requester session is sandboxed,
sessions_spawnrejects targets that would run unsandboxed.
- Use
agents_listto see which agent ids are currently allowed forsessions_spawn.
- Sub-agent sessions are automatically archived after
agents.defaults.subagents.archiveAfterMinutes(default: 60). - Archive uses
sessions.deleteand renames the transcript to*.deleted.<timestamp>(same folder). cleanup: "delete"archives immediately after announce (still keeps the transcript via rename).- Auto-archive is best-effort; pending timers are lost if the gateway restarts.
runTimeoutSecondsdoes not auto-archive; it only stops the run. The session remains until auto-archive.- Auto-archive applies equally to depth-1 and depth-2 sessions.
Nested Sub-Agents
By default, sub-agents cannot spawn their own sub-agents (maxSpawnDepth: 1). You can enable one level of nesting by setting maxSpawnDepth: 2, which allows the orchestrator pattern: main → orchestrator sub-agent → worker sub-sub-agents.
How to enable
Depth levels
Announce chain
Results flow back up the chain:- Depth-2 worker finishes → announces to its parent (depth-1 orchestrator)
- Depth-1 orchestrator receives the announce, synthesizes results, finishes → announces to main
- Main agent receives the announce and delivers to the user
Tool policy by depth
- Depth 1 (orchestrator, when
maxSpawnDepth >= 2): Getssessions_spawn,subagents,sessions_list,sessions_historyso it can manage its children. Other session/system tools remain denied. - Depth 1 (leaf, when
maxSpawnDepth == 1): No session tools (current default behavior). - Depth 2 (leaf worker): No session tools —
sessions_spawnis always denied at depth 2. Cannot spawn further children.
Per-agent spawn limit
Each agent session (at any depth) can have at mostmaxChildrenPerAgent (default: 5) active children at a time. This prevents runaway fan-out from a single orchestrator.
Cascade stop
Stopping a depth-1 orchestrator automatically stops all its depth-2 children:/stopin the main chat stops all depth-1 agents and cascades to their depth-2 children./subagents kill <id>stops a specific sub-agent and cascades to its children./subagents kill allstops all sub-agents for the requester and cascades.
Authentication
Sub-agent auth is resolved by agent id, not by session type:- The sub-agent session key is
agent:<agentId>:subagent:<uuid>. - The auth store is loaded from that agent’s
agentDir. - The main agent’s auth profiles are merged in as a fallback; agent profiles override main profiles on conflicts.
identitySource: "parent-session"), so tools with identity-based access checks resolve the same
user in the child run. The target agent’s agents.list[].inheritRequesterIdentity: false switches
this off at the gateway: delegated turns on that agent run without a person identity (see
inheritRequesterIdentity).
System-triggered parents that run without a resolved identity spawn
unattributed children — there is no fallback identity. Sub-agent runs and announces resolve the
target agent’s workspace lane from that identity, so an unattributed run or announce into a
lane-enabled agent is denied (see Workspace Lanes).
Announce
Sub-agents report back via an announce step:- The announce step runs inside the sub-agent session (not the requester session).
- If the sub-agent replies exactly
ANNOUNCE_SKIP, nothing is posted. - Otherwise the announce reply is posted to the requester chat channel via a follow-up
agentcall (deliver=true). - If the requester session’s stored route names a non-default account that the channel’s configured account list no longer includes, the announce has no external target: the completion is delivered as the announce turn inside the requester session instead, with no default-account fallback (see Sessions).
- Announce replies preserve thread/topic routing when available on channel adapters.
- Announce context is normalized to a stable internal event block:
- source (
subagentorcron) - child session key/id
- announce type + task label
- status line derived from runtime outcome (
success,error,timeout, orunknown) - result content from the announce step (or
(no output)if missing) - a follow-up instruction describing when to reply vs. stay silent
- source (
Statusis not inferred from model output; it comes from runtime outcome signals.- If the gateway RPC channel fails while waiting for a sub-agent to complete, the run is finalized with
status: errorand a message indicating the wait failure, rather than silently remaining in an active state.
- Runtime (e.g.,
runtime 5m12s) - Token usage (input/output/total)
- Estimated cost when model pricing is configured (
models.providers.*.models[].cost) sessionKey,sessionId, and transcript path (so the main agent can fetch history viasessions_historyor inspect the file on disk)- Internal metadata is meant for orchestration only; user-facing replies should be rewritten in normal assistant voice.
cleanup: "keep"), fires the deferred
subagent_ended and task_outcome hooks exactly like the give-up path, and logs
Subagent announce denied by workspace lane.
Parent-mode announce turns are recorded in session-run history with kind: "announce".
Direct and cron delivery do not create these turns. Inspect parent-mode turns with
sessions.runs.list, for example:
Sub-agent access control (which agents, which tools)
Sub-agent configuration lives across three independent surfaces. They answer different questions — keep them straight.1. Which agent IDs can this agent spawn? (per-agent allowlist)
agents.list[].subagents.allowAgents — per-agent allowlist of target agent IDs for sessions_spawn’s agentId parameter.
- Default (field omitted): only the requester agent’s own ID is allowed — an agent can spawn sub-agents under its own ID but not under others.
["*"]opens it to any agent ID.- Entries are matched case-insensitively after normalization.
- This is allowlist-only; there is no deny-list for target agent IDs. To restrict, omit IDs from
allowAgents. - Sandbox inheritance guard still applies: a sandboxed requester cannot spawn into an unsandboxed target, even if the ID is allowlisted.
- Discovery: call
agents_listto see which IDs are currently allowed forsessions_spawn. - Teams: an agent that leads an
agents.teamsentry can also spawn every member of that team, in addition toallowAgents. Members get no extra rights from the team. - Internal agents (
userFacing: false) can be spawned like any other agent, but not withthread: true, because that binds them to a user-visible thread.
2. Global sub-agent tuning (timing, depth, concurrency)
agents.defaults.subagents.* — global defaults for all sub-agent runs, not per-agent.
- No
allowAgentsfield here — the per-agent allowlist (#1) is the only place to restrict target IDs. - Per-agent overrides:
agents.list[].subagents.modelandagents.list[].subagents.thinkingwin over the defaults.
3. Which tools can sub-agents use? (global tool policy)
tools.subagents.tools.* — global tool policy applied to all spawned sub-agents. This controls tool access, not which agent IDs can be spawned.
- Deny wins over allow. If both are set, denied tools stay denied.
- Sub-agents always start with all tools except session tools (
sessions_list,sessions_history,sessions_send,agents_nudge,sessions_spawn) and system tools. AtmaxSpawnDepth >= 2, depth-1 orchestrators additionally receivesessions_spawn,subagents,sessions_list,sessions_history. - See Tool Policy below for the default denylist and nesting behavior.
Tool Policy (sub-agent tools)
By default, sub-agents get all tools except session tools and system tools:sessions_listsessions_historysessions_sendagents_nudgesessions_spawn
maxSpawnDepth >= 2, depth-1 orchestrator sub-agents additionally receive sessions_spawn, subagents, sessions_list, and sessions_history so they can manage their children.
Override via config:
tools.subagents.model: default model selection for spawned sub-agents (string or{ primary, fallbacks }).tools.subagents.tools.allow: if set, becomes allow-only (deny still wins).tools.subagents.tools.alsoAllow: additional allowlist entries merged into allow and/or default sub-agent denylist.tools.subagents.tools.deny: denied tools (deny wins over allow).
Concurrency
Sub-agents use a dedicated in-process queue lane:- Lane name:
subagent - Concurrency:
agents.defaults.subagents.maxConcurrent(default8) - Nested/orchestrator coordination uses the
nestedlane withagents.defaults.nested.maxConcurrent(default2)
Stopping
- Sending
/stopin the requester chat aborts the requester session and stops any active sub-agent runs spawned from it, cascading to nested children. For run-mode ACP children this also cancels the ACP turn. /subagents kill <id>stops a specific sub-agent (cancelling the ACP turn for an ACP child) and cascades to its children. A child cancelled with/acp cancelis reported to the requester as not completed.
Limitations
- Pending announce work is durable through the configured session storage and is resumed after a gateway restart. The in-process steer fast-path retains its existing crash window.
- If a sub-agent’s
agent.waitcall fails (e.g., gateway RPC channel drops), the run is finalized as an error completion with cleanup, rather than remaining stuck as “active” until the next gateway restart. - Sub-agents still share the same gateway process resources; treat
maxConcurrentas a safety valve. sessions_spawnis always non-blocking: it returns{ status: "accepted", runId, childSessionKey }immediately.- Sub-agent context only injects
AGENTS.md+TOOLS.md(noSOUL.md,IDENTITY.md,USER.md,HEARTBEAT.md, orBOOTSTRAP.md). - Maximum nesting depth is 5 (
maxSpawnDepthrange: 1–5). Depth 2 is recommended for most use cases. maxChildrenPerAgentcaps active children per session (default: 5, range: 1–20).