{
  "title": "Sub-agents",
  "content": "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.\n\nUse `/subagents` to inspect or control sub-agent runs for the **current session**:\n\n* `/subagents list`\n* `/subagents stop <id|#|all>`\n* `/subagents log <id|#> [limit] [tools]`\n* `/subagents info <id|#>`\n* `/subagents send <id|#> <message>`\n\n`/subagents info` shows run metadata (status, timestamps, session id, transcript path, cleanup).\n\n* Parallelize “research / long task / slow tool” work without blocking the main run.\n* Keep sub-agents isolated by default (session separation + optional sandboxing).\n* Keep the tool surface hard to misuse: sub-agents do **not** get session tools by default.\n* Avoid nested fan-out: sub-agents cannot spawn sub-agents.\n\nCost note: each sub-agent has its **own** context and token usage. For heavy or repetitive\ntasks, set a cheaper model for sub-agents and keep your main agent on a higher-quality model.\nYou can configure this via `agents.defaults.subagents.model` or per-agent overrides.\n\nUse `sessions_spawn`:\n\n* Starts a sub-agent run (`deliver: false`, global lane: `subagent`)\n* Then runs an announce step and posts the announce reply to the requester chat channel\n* Default model: inherits the caller unless you set `agents.defaults.subagents.model` (or per-agent `agents.list[].subagents.model`); an explicit `sessions_spawn.model` still wins.\n* Default thinking: inherits the caller unless you set `agents.defaults.subagents.thinking` (or per-agent `agents.list[].subagents.thinking`); an explicit `sessions_spawn.thinking` still wins.\n\n* `task` (required)\n* `label?` (optional)\n* `agentId?` (optional; spawn under another agent id if allowed)\n* `model?` (optional; overrides the sub-agent model; invalid values are skipped and the sub-agent runs on the default model with a warning in the tool result)\n* `thinking?` (optional; overrides thinking level for the sub-agent run)\n* `runTimeoutSeconds?` (default `0`; when set, the sub-agent run is aborted after N seconds)\n* `cleanup?` (`delete|keep`, default `keep`)\n\n* `agents.list[].subagents.allowAgents`: list of agent ids that can be targeted via `agentId` (`[\"*\"]` to allow any). Default: only the requester agent.\n\n* Use `agents_list` to see which agent ids are currently allowed for `sessions_spawn`.\n\n* Sub-agent sessions are automatically archived after `agents.defaults.subagents.archiveAfterMinutes` (default: 60).\n* Archive uses `sessions.delete` and renames the transcript to `*.deleted.<timestamp>` (same folder).\n* `cleanup: \"delete\"` archives immediately after announce (still keeps the transcript via rename).\n* Auto-archive is best-effort; pending timers are lost if the gateway restarts.\n* `runTimeoutSeconds` does **not** auto-archive; it only stops the run. The session remains until auto-archive.\n\nSub-agent auth is resolved by **agent id**, not by session type:\n\n* The sub-agent session key is `agent:<agentId>:subagent:<uuid>`.\n* The auth store is loaded from that agent’s `agentDir`.\n* The main agent’s auth profiles are merged in as a **fallback**; agent profiles override main profiles on conflicts.\n\nNote: the merge is additive, so main profiles are always available as fallbacks. Fully isolated auth per agent is not supported yet.\n\nSub-agents report back via an announce step:\n\n* The announce step runs inside the sub-agent session (not the requester session).\n* If the sub-agent replies exactly `ANNOUNCE_SKIP`, nothing is posted.\n* Otherwise the announce reply is posted to the requester chat channel via a follow-up `agent` call (`deliver=true`).\n* Announce replies preserve thread/topic routing when available (Slack threads, Telegram topics, Matrix threads).\n* Announce messages are normalized to a stable template:\n  * `Status:` derived from the run outcome (`success`, `error`, `timeout`, or `unknown`).\n  * `Result:` the summary content from the announce step (or `(not available)` if missing).\n  * `Notes:` error details and other useful context.\n* `Status` is not inferred from model output; it comes from runtime outcome signals.\n\nAnnounce payloads include a stats line at the end (even when wrapped):\n\n* Runtime (e.g., `runtime 5m12s`)\n* Token usage (input/output/total)\n* Estimated cost when model pricing is configured (`models.providers.*.models[].cost`)\n* `sessionKey`, `sessionId`, and transcript path (so the main agent can fetch history via `sessions_history` or inspect the file on disk)\n\n## Tool Policy (sub-agent tools)\n\nBy default, sub-agents get **all tools except session tools**:\n\n* `sessions_list`\n* `sessions_history`\n* `sessions_send`\n* `sessions_spawn`\n\nSub-agents use a dedicated in-process queue lane:\n\n* Lane name: `subagent`\n* Concurrency: `agents.defaults.subagents.maxConcurrent` (default `8`)\n\n* Sending `/stop` in the requester chat aborts the requester session and stops any active sub-agent runs spawned from it.\n\n* Sub-agent announce is **best-effort**. If the gateway restarts, pending “announce back” work is lost.\n* Sub-agents still share the same gateway process resources; treat `maxConcurrent` as a safety valve.\n* `sessions_spawn` is always non-blocking: it returns `{ status: \"accepted\", runId, childSessionKey }` immediately.\n* Sub-agent context only injects `AGENTS.md` + `TOOLS.md` (no `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, or `BOOTSTRAP.md`).",
  "code_samples": [],
  "headings": [
    {
      "level": "h2",
      "text": "Slash command",
      "id": "slash-command"
    },
    {
      "level": "h2",
      "text": "Tool",
      "id": "tool"
    },
    {
      "level": "h2",
      "text": "Authentication",
      "id": "authentication"
    },
    {
      "level": "h2",
      "text": "Announce",
      "id": "announce"
    },
    {
      "level": "h2",
      "text": "Tool Policy (sub-agent tools)",
      "id": "tool-policy-(sub-agent-tools)"
    },
    {
      "level": "h2",
      "text": "Concurrency",
      "id": "concurrency"
    },
    {
      "level": "h2",
      "text": "Stopping",
      "id": "stopping"
    },
    {
      "level": "h2",
      "text": "Limitations",
      "id": "limitations"
    }
  ],
  "url": "llms-txt#sub-agents",
  "links": []
}