feat: add mission control-inspired multi-agent features

CLAUDE.md

@@ -0,0 +1,130 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What Is OpenClaw
+
+Multi-channel AI gateway with extensible messaging integrations. TypeScript (ESM), pnpm monorepo. Connects to WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, MS Teams, and many more via a plugin/extension system.
+
+## Essential Commands
+
+```bash
+pnpm install                # Install dependencies (Node ≥22.12.0, pnpm 10.x)
+pnpm build                  # Full build (tsdown → dist/)
+pnpm check                  # Format check + tsgo + oxlint (run before commits)
+pnpm test                   # Run all tests (parallel vitest)
+pnpm test:fast              # Unit tests only (excludes gateway/extensions)
+pnpm test:e2e               # E2E tests
+pnpm test:coverage          # Unit tests with V8 coverage
+pnpm test:watch             # Watch mode
+pnpm lint                   # oxlint --type-aware
+pnpm lint:fix               # oxlint fix + format
+pnpm format                 # oxfmt --write
+pnpm format:check           # oxfmt --check
+pnpm tsgo                   # TypeScript type checking
+```
+
+### Running a Single Test
+
+```bash
+vitest run --config vitest.unit.config.ts src/path/to/file.test.ts
+```
+
+### Dev Mode
+
+```bash
+pnpm openclaw ...           # Run CLI in dev (via tsx)
+pnpm dev                    # Start dev server
+pnpm gateway:dev            # Gateway dev mode (skips channels)
+pnpm ui:dev                 # Control UI dev (Vite)
+pnpm tui:dev                # Terminal UI dev
+```
+
+### Commits
+
+Use `scripts/committer "<msg>" <file...>` instead of manual `git add`/`git commit` to keep staging scoped. Follow concise action-oriented messages (e.g., `CLI: add verbose flag to send`).
+
+## Architecture
+
+### Monorepo Layout
+
+- **`src/`** — Core TypeScript source (CLI, gateway, agents, channels, memory, media, plugins, providers, web)
+- **`extensions/`** — Channel plugins as workspace packages (~38: discord, telegram, matrix, msteams, voice-call, etc.)
+- **`packages/`** — Sub-packages (clawdbot, moltbot)
+- **`ui/`** — Control UI (Vite + Lit with legacy decorators)
+- **`apps/`** — Native apps (macOS/Swift, iOS/Swift, Android/Kotlin)
+- **`docs/`** — Mintlify-hosted documentation (docs.openclaw.ai)
+- **`dist/`** — Built output
+
+### Key Source Directories (`src/`)
+
+| Directory    | Purpose                                                   |
+| ------------ | --------------------------------------------------------- |
+| `agents/`    | Multi-agent routing, Pi agent integration, tools          |
+| `channels/`  | Channel routing, group rules, allowlists                  |
+| `commands/`  | CLI commands (gateway, agent, send, wizard, doctor, etc.) |
+| `cli/`       | CLI wiring and command setup                              |
+| `config/`    | Configuration loading, validation, state migrations       |
+| `gateway/`   | WebSocket control plane, server, protocol                 |
+| `memory/`    | Vector DB (SQLite-vec), RAG, memory core                  |
+| `media/`     | Image/audio/video pipeline, transcription                 |
+| `plugins/`   | Plugin runtime, registry, manifest discovery              |
+| `providers/` | Model providers (Claude, GPT, Gemini, etc.)               |
+| `routing/`   | Message routing logic                                     |
+| `security/`  | Security checks, DM policies                              |
+| `tui/`       | Terminal UI                                               |
+| `web/`       | WebChat UI, websocket bridge                              |
+
+### Extension System
+
+Extensions live in `extensions/` as separate workspace packages. Plugin-only deps go in the extension's own `package.json`, not root. Runtime deps must be in `dependencies` (npm install runs `--omit=dev` in plugin dir). Avoid `workspace:*` in `dependencies`; put `openclaw` in `devDependencies` or `peerDependencies` instead.
+
+### Entry Points
+
+- CLI: `openclaw.mjs` → `dist/entry.js`
+- Dev: `node scripts/run-node.mjs` (tsx)
+- Gateway: WebSocket control plane started via `openclaw gateway run`
+- Plugin SDK: exported via `openclaw/plugin-sdk`
+
+## Coding Standards
+
+- **TypeScript ESM only**, strict mode. Avoid `any` types.
+- **Formatting/linting:** oxfmt + oxlint (not ESLint/Prettier). Run `pnpm check` before commits.
+- **File size:** aim for ~500-700 LOC; split/refactor when it improves clarity.
+- **Dependency injection:** use `createDefaultDeps` pattern.
+- **Naming:** **OpenClaw** for product/docs headings; `openclaw` for CLI/package/config keys.
+- **Comments:** brief comments for tricky/non-obvious logic only.
+- **Tool schemas (google-antigravity):** no `Type.Union` in tool input schemas; no `anyOf`/`oneOf`/`allOf`. Use `stringEnum`/`optionalStringEnum` for string lists, `Type.Optional(...)` instead of `... | null`.
+- **CLI progress:** use `src/cli/progress.ts`; don't hand-roll spinners.
+- **Patched deps:** any dep with `pnpm.patchedDependencies` must use an exact version (no `^`/`~`). Patching deps requires explicit approval.
+- **Never update the Carbon dependency.**
+- **Control UI:** uses Lit with legacy decorators (`@state()`, `@property()`). Do not switch to standard decorators.
+
+## Testing
+
+- Framework: Vitest with V8 coverage (70% lines/branches/functions/statements thresholds).
+- Tests colocated as `*.test.ts`; e2e as `*.e2e.test.ts`.
+- Test setup: `test/setup.ts` (isolated home dirs, plugin registry mocking, channel stubs).
+- Live tests (real API keys): `OPENCLAW_LIVE_TEST=1 pnpm test:live`
+- Do not set test workers above 16.
+
+## Pre-commit & CI
+
+- Pre-commit hooks: `prek install` (trailing-whitespace, yaml, large-file detection, secret detection, shellcheck, oxlint, oxfmt, swiftlint).
+- CI runs: format check → tsgo → oxlint → unit tests → e2e → Docker integration tests.
+- Before pushing: `pnpm build && pnpm check && pnpm test`
+
+## Multi-Agent Safety
+
+When working alongside other agents:
+
+- Do not create/apply/drop `git stash` entries unless explicitly requested.
+- Do not switch branches or modify git worktrees unless explicitly requested.
+- Scope commits to your changes only; avoid cross-cutting state changes.
+- When you see unrecognized files, keep going; focus on your changes.
+
+## Docs
+
+- Hosted on Mintlify (docs.openclaw.ai). Internal links: root-relative, no `.md`/`.mdx` suffix.
+- `docs/zh-CN/**` is generated; do not edit manually.
+- Avoid em dashes and apostrophes in doc headings (breaks Mintlify anchors).

docs/tools/slash-commands.md

@@ -77,6 +77,7 @@ Text + native (when enabled):
 - `/approve <id> allow-once|allow-always|deny` (resolve exec approval prompts)
 - `/context [list|detail|json]` (explain “context”; `detail` shows per-file + per-tool + per-skill + system prompt size)
 - `/whoami` (show your sender id; alias: `/id`)
+- `/agent <agentId> <message>` (send a message to a specific agent; in Slack, shows an interactive agent picker)
 - `/subagents list|kill|log|info|send|steer` (inspect, kill, log, or steer sub-agent runs for the current session)
 - `/kill <id|#|all>` (immediately abort one or all running sub-agents for this session; no confirmation message)
 - `/steer <id|#> <message>` (steer a running sub-agent immediately: in-run when possible, otherwise abort current work and restart on the steer message)

examples/multi-agent-poc/README.md

@@ -0,0 +1,111 @@
+# Multi-Agent POC
+
+Demonstrates OpenClaw's multi-agent capability with a router/classifier agent that automatically delegates to specialized agents.
+
+## Architecture
+
+```
+User message
+    |
+    v
+[Router Agent]  (Haiku - fast, cheap classifier)
+    |
+    +---> [Research Agent]  (Sonnet - deep research)
+    +---> [Writing Agent]   (Sonnet - writing/editing)
+    +---> [Code Agent]      (Sonnet - coding/debugging)
+```
+
+The **Router Agent** receives all messages, classifies intent, and uses `sessions_spawn` to delegate to the right specialist. Users don't need to manually select an agent.
+
+For manual agent selection, the `/agent` slash command (Slack) or the agent picker dropdown (Control UI) lets you target a specific agent directly.
+
+## Agents
+
+| Agent       | ID           | Emoji | Purpose                               | Tool Profile |
+| ----------- | ------------ | ----- | ------------------------------------- | ------------ |
+| Switchboard | `router`     | 🔀    | Classify intent, route to specialist  | `minimal`    |
+| Scout       | `researcher` | 🔍    | Research, fact-finding, summarization | `full`       |
+| Quill       | `writer`     | ✍️    | Writing, editing, communications      | `messaging`  |
+| Forge       | `coder`      | ⚡    | Code, debugging, reviews              | `coding`     |
+| Architect   | `designer`   | 🏗️    | Create new agents conversationally    | `minimal`    |
+
+## Setup
+
+1. Copy the agent config into your `~/.openclaw/config.yaml`:
+
+```bash
+# Or merge the agents section manually
+cp config.yaml ~/.openclaw/config.yaml
+```
+
+2. Copy workspace files:
+
+```bash
+cp -r workspaces/* ~/.openclaw/workspaces/
+```
+
+3. Start the gateway:
+
+```bash
+pnpm openclaw gateway run
+```
+
+## Verify
+
+```bash
+# List agents
+pnpm openclaw gateway call agents.list
+
+# Chat with the router (auto-classifies and delegates)
+pnpm openclaw agent --message "What is quantum computing?"
+# -> Router spawns Research Agent
+
+pnpm openclaw agent --message "Write a haiku about code"
+# -> Router spawns Writing Agent
+
+pnpm openclaw agent --message "Review this function for bugs"
+# -> Router spawns Code Agent
+
+# Chat with a specific agent directly (bypasses router)
+pnpm openclaw agent --message "Hello" --agent researcher
+pnpm openclaw agent --message "Hello" --agent writer
+pnpm openclaw agent --message "Hello" --agent coder
+```
+
+## Slack Usage
+
+```
+/agent researcher What is quantum computing?
+/agent writer Draft an email about the new feature
+/agent coder Review this pull request
+```
+
+The `/agent` slash command lets you target a specific agent in Slack. Without it, messages go to the default router agent which auto-classifies.
+
+## Control UI
+
+Open the Control UI to see the agent picker dropdown, switch between agents mid-conversation, and see which agent is responding.
+
+## Squad Builder (Agent Designer)
+
+The `designer` agent creates new agents conversationally. Instead of editing YAML by hand, chat with the Architect to design and deploy agents on the fly:
+
+```bash
+pnpm openclaw agent --message "Create a new agent called translator that translates text between languages" --agent designer
+```
+
+The designer uses `config.patch` to safely append new agents to your config and `agents_files_set` to create workspace files (SOUL.md, IDENTITY.md). After creation, verify with:
+
+```bash
+pnpm openclaw gateway call agents.list
+```
+
+## Agent Handoff
+
+Agents can delegate to each other using `sessions_spawn`:
+
+- Research Agent discovers an API -> spawns Code Agent to write the integration
+- Code Agent finishes a feature -> spawns Writing Agent to document it
+- Writing Agent needs technical details -> spawns Research Agent to look them up
+
+The `maxSpawnDepth: 2` setting enables orchestrator patterns where an agent can spawn sub-agents that spawn their own sub-agents.

examples/multi-agent-poc/config.yaml

@@ -0,0 +1,70 @@
+# Multi-Agent POC Configuration
+# Copy this into your ~/.openclaw/config.yaml (or merge with existing config)
+#
+# Each agent gets its own workspace, persona (SOUL.md), identity (IDENTITY.md),
+# model config, and tool profile. The gateway resolves agents by ID and routes
+# messages to the correct workspace.
+#
+# The "router" agent acts as a classifier: it receives all messages first and
+# delegates to the right specialist via sessions_spawn. Users don't need to
+# pick an agent manually.
+
+agents:
+  defaults:
+    model:
+      primary: claude-sonnet-4-5-20250929
+    subagents:
+      maxSpawnDepth: 2
+
+  list:
+    - id: router
+      name: Router Agent
+      default: true
+      workspace: ~/.openclaw/workspaces/router
+      model:
+        primary: claude-haiku-4-5-20251001
+      tools:
+        profile: minimal
+      subagents:
+        allowAgents: ["*"]
+
+    - id: researcher
+      name: Research Agent
+      workspace: ~/.openclaw/workspaces/researcher
+      model:
+        primary: claude-sonnet-4-5-20250929
+      tools:
+        profile: full
+      subagents:
+        allowAgents: ["*"]
+
+    - id: writer
+      name: Writing Agent
+      workspace: ~/.openclaw/workspaces/writer
+      model:
+        primary: claude-sonnet-4-5-20250929
+      tools:
+        profile: messaging
+        alsoAllow:
+          - read
+
+    - id: coder
+      name: Code Agent
+      workspace: ~/.openclaw/workspaces/coder
+      model:
+        primary: claude-sonnet-4-5-20250929
+      tools:
+        profile: coding
+      subagents:
+        allowAgents: ["*"]
+
+    - id: designer
+      name: Agent Designer
+      workspace: ~/.openclaw/workspaces/designer
+      model:
+        primary: claude-sonnet-4-5-20250929
+      tools:
+        profile: minimal
+        alsoAllow:
+          - gateway
+          - agents_files_set

examples/multi-agent-poc/workspaces/coder/IDENTITY.md

@@ -0,0 +1,6 @@
+# IDENTITY.md
+
+- **Name:** Forge
+- **Creature:** Code-forging AI
+- **Vibe:** Pragmatic, precise, direct
+- **Emoji:** ⚡

examples/multi-agent-poc/workspaces/coder/SOUL.md

@@ -0,0 +1,35 @@
+# SOUL.md - Code Agent
+
+You are a coding specialist. Your purpose is to write, review, debug, and explain code.
+
+## Core Behavior
+
+- Read existing code before modifying it. Understand context first.
+- Write clean, tested, minimal code. Don't over-engineer.
+- Explain your reasoning when making architectural choices.
+- Run tests after making changes. Don't assume things work without verification.
+
+## What You Do
+
+- Write new code and features
+- Debug and fix issues
+- Review code for bugs, performance, and style
+- Explain code and architectural decisions
+- Set up development environments and tooling
+
+## What You Don't Do
+
+- Write long-form prose or documentation (hand off to the Writing Agent)
+- Deep research on non-technical topics (hand off to the Research Agent)
+- Deploy to production without explicit user approval
+
+## Handoff
+
+If a task is better suited for another agent, use `sessions_spawn` to delegate:
+
+- Research tasks -> `researcher`
+- Writing/docs tasks -> `writer`
+
+## Vibe
+
+Pragmatic, precise, and opinionated about code quality. You're the person who ships working code.

examples/multi-agent-poc/workspaces/designer/IDENTITY.md

@@ -0,0 +1,6 @@
+# IDENTITY.md
+
+- **Name:** Architect
+- **Creature:** Agent designer
+- **Vibe:** Creative, methodical
+- **Emoji:** 🏗️