サブエージェント

サブエージェントは、既存のエージェント実行から生成されるバックグラウンドエージェント実行です。独自のセッション（''agent:<agentId>:subagent:<uuid>''）で実行され、完了時に結果をリクエスト元チャットチャンネルに''通知''します。

''/subagents'' を使用して''現在のセッション''のサブエージェント実行を検査または制御：

- ''/subagents list''

- ''/subagents stop <id|#|all>''

- ''/subagents log <id|#> [limit] [tools]''

- ''/subagents info <id|#>''

- ''/subagents send <id|#> <message>''

''/subagents info'' shows run metadata (status, timestamps, session id, transcript path, cleanup).

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.

- Avoid nested fan-out: sub-agents cannot spawn sub-agents.

Cost note: each sub-agent has its <strong>own</strong> context and token usage. For heavy or repetitive

tasks, set a cheaper model for sub-agents and keep your main agent on a higher-quality model.

You can configure this via ''agents.defaults.subagents.model'' or per-agent overrides.

Use ''sessions_spawn'':

- ''スキル''：''deliver: false'' スキルを使用（''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-agent ''agents.list[].subagents.model''); an explicit ''sessions_spawn.model'' still wins.

Tool params:

- ''task'' (required)

- ''label?'' (optional)

- ''agentId?'' (optional; spawn under another agent id if allowed)

- ''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)

- ''thinking?'' (optional; overrides thinking level for the sub-agent run)

- ''runTimeoutSeconds?'' (default ''0''; when set, the sub-agent run is aborted after N seconds)

- ''cleanup?'' (''delete|keep'', default ''keep'')

Allowlist:

- ''agents.list[].subagents.allowAgents'': list of agent ids that can be targeted via ''agentId'' (''["*"]'' to allow any). Default: only the requester agent.

Discovery:

- Use ''agents_list'' to see which agent ids are currently allowed for ''sessions_spawn''.

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.

- ''runTimeoutSeconds'' does ''not'' auto-archive; it only stops the run. The session remains until auto-archive.

サブエージェントは独自のセッションで実行されます：

- セッション ID 形式：''agent:<agentId>:subagent:<uuid>''

- The auth store is loaded from that agent's ''agentDir''.

- 独自のトランスクリプトとコンテキストを維持

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

完了時、サブエージェントは結果を通知：

- 結果はリクエスト元チャットチャンネルに送信

- 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 ''agent'' call (''deliver=true'').

- Announce replies preserve thread/topic routing when available (Slack threads, Telegram topics, Matrix threads).

- Announce messages are normalized to a stable template:

- ''Status:'' derived from the run outcome (''success'', ''error'', ''timeout'', or ''unknown'').

- ''Result:'' the summary content from the announce step (or ''(not available)'' if missing).

- ''Notes:'' error details and other useful context.

- ''Status'' is not inferred from model output; it comes from runtime outcome signals.

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)

サブエージェントの管理：

- ''sessions_list'' で実行中のサブエージェントを一覧表示

- ''sessions_history'' でサブエージェントを停止

- ''sessions_send'' でログを確認

- ''sessions_spawn'' で詳細情報を取得

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"]
      '}',
    '}',
  '}',
'}'

一般的な使用例：

- Lane name: ''subagent''

- Concurrency: ''agents.defaults.subagents.maxConcurrent'' (default ''8'')

- Sending ''/stop'' in the requester chat aborts the requester session and stops any active sub-agent runs spawned from it.

- 長時間実行タスクにはサブエージェントを使用

- 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'' + ''TOOLS.md'' (no ''SOUL.md'', ''IDENTITY.md'', ''USER.md'', ''HEARTBEAT.md'', or ''BOOTSTRAP.md'').