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. Each sub-agent run is tracked as a background task.

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.

Slash command

Use /subagents to inspect sub-agent runs for the current session:

/subagents list/subagents log <id|#> [limit] [tools]/subagents info <id|#>

/subagents info shows run metadata (status, timestamps, session id, transcript path, cleanup). Use sessions_history for a bounded, safety-filtered recall view; inspect the transcript path on disk when you need the raw full transcript.

Thread binding controls

These commands work on channels that support persistent thread bindings. See Thread supporting channels below.

/focus <subagent-label|session-key|session-id|session-label>/unfocus/agents/session idle <duration|off>/session max-age <duration|off>

Spawn behavior

Agents start background sub-agents with sessions_spawn. Sub-agent completions return as internal parent-session events; the parent/requester agent decides whether a user-facing update is needed.

Context modes

Native sub-agents start isolated unless the caller explicitly asks to fork the current transcript.

Use fork sparingly. It is for context-sensitive delegation, not a replacement for writing a clear task prompt.

Tool: sessions_spawn

Starts a sub-agent run with deliver: false on the global subagent lane, then runs an announce step and posts the announce reply to the requester chat channel.

Availability depends on the caller's effective tool policy. The coding and full profiles expose sessions_spawn by default. The messaging profile does not; add tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"] or use tools.profile: "coding" for agents that should delegate work. Channel/group, provider, sandbox, and per-agent allow/deny policies can still remove the tool after the profile stage. Use /tools from the same session to confirm the effective tool list.

Defaults:

• Model: native sub-agents inherit the caller unless you set agents.defaults.subagents.model (or per-agent agents.list[].subagents.model). ACP runtime spawns use the same configured subagent model when present; otherwise the ACP harness keeps its own default. An explicit sessions_spawn.model still wins.
• Thinking: native sub-agents inherit the caller unless you set agents.defaults.subagents.thinking (or per-agent agents.list[].subagents.thinking). ACP runtime spawns also apply agents.defaults.models["provider/model"].params.thinking for the selected model. An explicit sessions_spawn.thinking still wins.
• Run timeout: OmeniaClaw uses agents.defaults.subagents.runTimeoutSeconds when set; otherwise it falls back to 0 (no timeout). sessions_spawn does not accept per-call timeout overrides.
• Task delivery: native sub-agents receive the delegated task in their first visible [Subagent Task] message. The sub-agent system prompt carries runtime rules and routing context, not a hidden duplicate of the task.

Accepted native sub-agent spawns include the resolved child model metadata in the tool result: resolvedModel contains the applied model ref and resolvedProvider contains the provider prefix when the ref has one.

Delegation prompt mode

agents.defaults.subagents.delegationMode controls prompt guidance only; it does not change tool policy or enforce delegation.

• suggest (default): keep the standard prompt nudge to use sub-agents for larger or slower work.
• prefer: tell the main agent to stay responsive and delegate anything more involved than a direct reply through sessions_spawn.

Per-agent overrides use agents.list[].subagents.delegationMode.

{  agents: {    defaults: {      subagents: {        delegationMode: "prefer",        maxConcurrent: 4,      },    },    list: [      {        id: "coordinator",        subagents: { delegationMode: "prefer" },      },    ],  },}

Tool parameters

Task names and targeting

taskName is a model-facing handle for orchestration, not a session key. Use it for stable child names such as review_subagents, linux_validation, or docs_update when a coordinator may need to inspect that child later.

Target resolution accepts exact taskName matches and unambiguous prefixes. Matching is scoped to the same active/recent target window used by numbered /subagents targets, so a stale completed child does not make a reused handle ambiguous. If two active or recent children share the same taskName, the target is ambiguous; use the list index, session key, or run id instead.

The reserved targets last and all are not valid taskName values because they already have control meanings.

Tool: sessions_yield

Ends the current model turn and waits for runtime events, primarily sub-agent completion events, to arrive as the next message. Use it after spawning required child work when the requester cannot produce a final answer until those completions arrive.

sessions_yield is the waiting primitive. Do not replace it with polling loops over subagents, sessions_list, sessions_history, shell sleep, or process polling just to detect child completion.

Only use sessions_yield when the session's effective tool list includes it. Some minimal or custom tool profiles may expose sessions_spawn and subagents without exposing sessions_yield; in that case, do not invent a polling loop just to wait for completion.

When active children exist, OmeniaClaw injects a compact runtime-generated Active Subagents prompt block into normal turns so the requester can see the current child sessions, run ids, statuses, labels, tasks, and taskName aliases without polling. The task and label fields in that block are quoted as data, not instructions, because they can originate from user/model-provided spawn arguments.

Tool: subagents

Lists spawned sub-agent runs owned by the requester session. It is scoped to the current requester; a child can only see its own controlled children.

Use subagents for on-demand status and debugging. Use sessions_yield to wait for completion events.

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

Any channel with a session-binding adapter can support persistent thread-bound subagent sessions (sessions_spawn with thread: true). Bundled adapters currently include Discord threads, Matrix threads, Telegram forum topics, and current-conversation bindings for Feishu. Use the per-channel threadBindings config keys for enablement, timeouts, and spawnSessions.

Quick flow

Manual controls

Config switches

• 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.

See Configuration reference and Slash commands for current adapter details.

Allowlist

If the requester session is sandboxed, sessions_spawn rejects targets that would run unsandboxed.

Discovery

Use agents_list to see which agent ids are currently allowed for sessions_spawn. The response includes each listed agent's effective model and embedded runtime metadata so callers can distinguish OmeniaClaw, Codex app-server, and other configured native runtimes.

allowAgents entries must point at configured agent ids in agents.list[]. ["*"] means any configured target agent plus the requester. If an agent config is deleted but its id remains in allowAgents, sessions_spawn rejects that id and agents_list omits it. Run OmeniaClaw doctor --fix to clean stale allowlist entries, or add a minimal agents.list[] entry when the target should remain spawnable while inheriting defaults.

Auto-archive

• Sub-agent sessions are automatically archived after agents.defaults.subagents.archiveAfterMinutes (default 60).
• Archive uses sessions.delete and 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.
• Configured run timeouts do not auto-archive; they only stop the run. The session remains until auto-archive.
• Auto-archive applies equally to depth-1 and depth-2 sessions.
• Browser cleanup is separate from archive cleanup: tracked browser tabs/processes are best-effort closed when the run finishes, even if the transcript/session record is kept.

Nested sub-agents

By default, sub-agents cannot spawn their own sub-agents (maxSpawnDepth: 1). Set maxSpawnDepth: 2 to enable one level of nesting — the orchestrator pattern: main → orchestrator sub-agent → worker sub-sub-agents.

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)        maxConcurrent: 8, // global concurrency lane cap (default: 8)        runTimeoutSeconds: 900, // default timeout for sessions_spawn (0 = no timeout)        announceTimeoutMs: 120000, // per-call gateway announce timeout      },    },  },}

Depth levels

Announce chain

Results flow back up the chain:

1. Depth-2 worker finishes → announces to its parent (depth-1 orchestrator).
2. Depth-1 orchestrator receives the announce, synthesizes results, finishes → announces to main.
3. Main agent receives the announce and delivers to the user.

Each level only sees announces from its direct children.

Tool policy by depth

• Role and control scope are written into session metadata at spawn time. That keeps flat or restored session keys from accidentally regaining orchestrator privileges.
• Depth 1 (orchestrator, when maxSpawnDepth >= 2): gets sessions_spawn, subagents, sessions_list, sessions_history so it can spawn children and inspect their status. 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_spawn is always denied at depth 2. Cannot spawn further children.

Per-agent spawn limit

Each agent session (at any depth) can have at most maxChildrenPerAgent (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:

• /stop in the main chat stops all depth-1 agents and cascades to their depth-2 children.

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.

The merge is additive, so main profiles are always available as fallbacks. Fully isolated auth per agent is not supported yet.

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.
• If the latest assistant text is the exact silent token NO_REPLY / no_reply, announce output is suppressed even if earlier visible progress existed.

Delivery depends on requester depth:

• Top-level requester sessions use a follow-up agent call with external delivery (deliver=true).
• Nested requester subagent sessions receive an internal follow-up injection (deliver=false) so the orchestrator can synthesize child results in-session.
• If a nested requester subagent session is gone, OmeniaClaw falls back to that session's requester when available.

For top-level requester sessions, completion-mode direct delivery first resolves any bound conversation/thread route and hook override, then fills missing channel-target fields from the requester session's stored route. That keeps completions on the right chat/topic even when the completion origin only identifies the channel.

Child completion aggregation is scoped to the current requester run when building nested completion findings, preventing stale prior-run child outputs from leaking into the current announce. Announce replies preserve thread/topic routing when available on channel adapters.

Announce context

Announce context is normalized to a stable internal event block:

Terminal failed runs report failure status without replaying captured reply text. Tool/toolResult output is not promoted into child result text.

Stats line

Announce payloads include a stats line at the end (even when wrapped):

• 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 via sessions_history or inspect the file on disk.

Internal metadata is meant for orchestration only; user-facing replies should be rewritten in normal assistant voice.

Why prefer sessions_history

sessions_history is the safer orchestration path:

• Assistant recall is normalized first: thinking tags stripped; <relevant-memories> / <relevant_memories> scaffolding stripped; plain-text tool-call XML payload blocks (<tool_call>, <function_call>, <tool_calls>, <function_calls>) stripped, including truncated payloads that never close cleanly; downgraded tool-call/result scaffolding and historical-context markers stripped; leaked model control tokens (<|assistant|>, other ASCII <|...|>, full-width <｜...｜>) stripped; malformed MiniMax tool-call XML stripped.
• Credential/token-like text is redacted.
• Long blocks can be truncated.
• Very large histories can drop older rows or replace an oversized row with [sessions_history omitted: message too large].
• Raw on-disk transcript inspection is the fallback when you need the full byte-for-byte transcript.

Tool policy

Sub-agents use the same profile and tool-policy pipeline as the parent or target agent first. After that, OmeniaClaw applies the sub-agent restriction layer.

With no restrictive tools.profile, sub-agents get all tools except the message tool, session tools, and system tools:

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn
• message

sessions_history remains a bounded, sanitized recall view here too — it is not a raw transcript dump.

When 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

{  agents: {    defaults: {      subagents: {        maxConcurrent: 1,      },    },  },  tools: {    subagents: {      tools: {        // deny wins        deny: ["gateway", "cron"],        // if allow is set, it becomes allow-only (deny still wins)        // allow: ["read", "exec", "process"]      },    },  },}

tools.subagents.tools.allow is a final allow-only filter. It can narrow the already-resolved tool set, but it cannot add back a tool removed by tools.profile. For example, tools.profile: "coding" includes web_search/web_fetch but not the browser tool. To let coding-profile sub-agents use browser automation, add browser at the profile stage:

{  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

Use per-agent agents.list[].tools.alsoAllow: ["browser"] when only one agent should get browser automation.

Concurrency

Sub-agents use a dedicated in-process queue lane:

• Lane name: subagent
• Concurrency: agents.defaults.subagents.maxConcurrent (default 8)

Liveness and recovery

OmeniaClaw does not treat endedAt absence as permanent proof that a sub-agent is still alive. Unended runs older than the stale-run window stop counting as active/pending in /subagents list, status summaries, descendant completion gating, and per-session concurrency checks.

After a gateway restart, stale unended restored runs are pruned unless their child session is marked abortedLastRun: true. Those restart-aborted child sessions remain recoverable through the sub-agent orphan recovery flow, which sends a synthetic resume message before clearing the aborted marker.

Automatic restart recovery is bounded per child session. If the same sub-agent child is accepted for orphan recovery repeatedly inside the rapid re-wedge window, OmeniaClaw persists a recovery tombstone on that session and stops auto-resuming it on later restarts. Run OmeniaClaw tasks maintenance --apply to reconcile the task record, or OmeniaClaw doctor --fix to clear stale aborted recovery flags on tombstoned sessions.

Stopping

• Sending /stop in the requester chat aborts the requester session and stops any active sub-agent runs spawned from it, cascading to nested children.

Limitations

• Sub-agent announce is best-effort. If the gateway restarts, pending "announce back" work is lost.
• Sub-agents still share the same gateway process resources; treat maxConcurrent as a safety valve.
• sessions_spawn is always non-blocking: it returns { status: "accepted", runId, childSessionKey } immediately.
• Sub-agent context only injects AGENTS.md and TOOLS.md (no SOUL.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md, or BOOTSTRAP.md). Codex-native subagents follow the same boundary: TOOLS.md stays in inherited Codex thread instructions, while parent-only persona, identity, and user files are injected as turn-scoped collaboration instructions so children do not clone them.
• Maximum nesting depth is 5 (maxSpawnDepth range: 1–5). Depth 2 is recommended for most use cases.
• maxChildrenPerAgent caps active children per session (default 5, range 1–20).

Related

• ACP agents
• Agent send
• Background tasks
• Multi-agent sandbox tools