docs: sync with goclaw source changes 4d31fe0..0dab087f (EN+VI) (#33)

Author: thieung

agent-teams/delegation-and-handoff.md

@@ -1,126 +1,65 @@
 # Delegation & Handoff
 
-Delegation allows the lead to spawn work on member agents. Handoff transfers conversation control between agents without interrupting the user's session.
+Delegation allows the lead to assign work to member agents via the task board. Handoff transfers conversation control between agents without interrupting the user's session.
 
 ## Agent Delegation Flow
 
+Delegation works through the `team_tasks` tool — the lead creates a task with an assignee, and the system auto-dispatches it to the assigned member:
+
 ```mermaid
 flowchart TD
-    LEAD["Lead receives user request"] --> DELEGATE["1. Delegate to member<br/>spawn agent=member,<br/>task='do the work'"]
-    DELEGATE --> MEMBER["Member agent executes<br/>in isolated session"]
-    MEMBER --> COMPLETE["2. Task auto-completed<br/>with delegation result"]
-    COMPLETE --> ANNOUNCE["3. Result announced<br/>back to lead"]
+    LEAD["Lead receives user request"] --> CREATE["1. Create task on board<br/>team_tasks(action=create,<br/>assignee=member)"]
+    CREATE --> DISPATCH["2. System auto-dispatches<br/>to assigned member"]
+    DISPATCH --> MEMBER["Member agent executes<br/>in isolated session"]
+    MEMBER --> COMPLETE["3. Task auto-completed<br/>with result"]
+    COMPLETE --> ANNOUNCE["4. Result announced<br/>back to lead"]
 
     subgraph "Parallel Delegation"
-        DELEGATE2["spawn member_A"] --> RUNA["Member A works"]
-        DELEGATE3["spawn member_B"] --> RUNB["Member B works"]
+        CREATE2["create task → member_A"] --> RUNA["Member A works"]
+        CREATE3["create task → member_B"] --> RUNB["Member B works"]
         RUNA --> COLLECT["Results accumulate"]
         RUNB --> COLLECT
         COLLECT --> ANNOUNCE2["Single combined<br/>announcement to lead"]
     end
 ```
 
-## Task Linking
+> **Note**: The `spawn` tool is for **self-clone subagents only** — it does not accept an `agent` parameter. To delegate to a team member, always use `team_tasks(action="create", assignee=...)`.
 
-Delegations can optionally link to a team task via `team_task_id`. For v2 teams, **if you omit `team_task_id`, the system auto-creates a task** — you don't need a separate create step:
+## Creating a Delegation Task
 
-```json
-{
-  "action": "spawn",
-  "agent": "analyst_agent",
-  "task": "Analyze the market trends in the Q1 report"
-}
-```
-
-The system auto-creates a task and links the delegation. You can also provide an explicit task ID:
+Use the `team_tasks` tool with `action: "create"` and a required `assignee`:
 
 ```json
 {
-  "action": "spawn",
-  "agent": "analyst_agent",
-  "task": "Analyze the market trends in the Q1 report",
-  "team_task_id": "550e8400-e29b-41d4-a716-446655440000"
+  "action": "create",
+  "subject": "Analyze the market trends in the Q1 report",
+  "description": "Focus on Q1 revenue data and competitor analysis",
+  "assignee": "analyst_agent"
 }
 ```
 
-**If `team_task_id` is invalid** or from a wrong team:
-- Delegation rejected with helpful error message
-- Error includes guidance to omit `team_task_id` to auto-create
+The system validates and auto-dispatches:
+- **`assignee` is required** — every task must be assigned to a team member
+- **Assignee must be a team member** — non-members are rejected
+- **Lead cannot self-assign** — prevents dual-session execution loops
+- **Auto-dispatch**: after the lead's turn ends, pending tasks are dispatched to their assigned agents
 
 **Guards enforced**:
-- Cannot reuse a completed or cancelled task ID
-- Cannot reuse an in-progress task ID (each spawn needs its own task)
-
-This ensures every piece of work is tracked on the task board.
-
-## Sync vs Async Delegation
-
-### Sync Delegation (Default)
+- Max **3 dispatches** per task — auto-fails after 3 attempts to prevent infinite loops
+- Task dispatched to lead agent is blocked and auto-failed
+- Member requests (non-lead) can optionally require leader approval before dispatch
 
-Parent waits for result before continuing:
+## Parallel Delegation
 
-```json
-{
-  "action": "spawn",
-  "agent": "analyst_agent",
-  "task": "Quick analysis",
-  "team_task_id": "550e8400-e29b-41d4-a716-446655440000",
-  "mode": "sync"
-}
-```
-
-- Lead blocks until member finishes
-- Result returned directly to lead
-- Best for quick tasks (< 2 minutes)
-- Task auto-claimed and auto-completed on success
-
-### Async Delegation
-
-Parent spawns work in the background and receives the result via a system announcement when complete:
+Create multiple tasks in the same turn — they dispatch simultaneously after the turn:
 
 ```json
-{
-  "action": "spawn",
-  "agent": "analyst_agent",
-  "task": "Deep research into market trends",
-  "team_task_id": "550e8400-e29b-41d4-a716-446655440000",
-  "mode": "async"
-}
+// Lead creates 2 tasks in one turn
+{"action": "create", "subject": "Extract facts", "assignee": "analyst1"}
+{"action": "create", "subject": "Extract opinions", "assignee": "analyst2"}
 ```
 
-- Lead gets a delegation ID immediately
-- Lead can continue with other work
-- Periodic progress notifications sent to chat (every 30 seconds, if enabled)
-- Result announced when complete via a system message to the lead
-
-**Response** (delegation ID for tracking):
-```json
-{
-  "delegation_id": "abc123def456",
-  "team_task_id": "550e8400-e29b-41d4-a716-446655440000"
-}
-```
-
-## Parallel Delegation Batching
-
-When lead delegates to multiple members simultaneously, results are collected and announced together:
-
-1. Each delegation runs independently
-2. Intermediate completions accumulate results (artifacts)
-3. When **last sibling** finishes, all results are collected
-4. Single combined announcement delivered to lead
-
-**Example**:
-
-```json
-// Lead delegates to 2 members simultaneously
-{"action": "spawn", "agent": "analyst1", "task": "Extract facts"}
-{"action": "spawn", "agent": "analyst2", "task": "Extract opinions"}
-
-// Results announced together:
-// "analyst1 (facts extraction): ..."
-// "analyst2 (opinions extraction): ..."
-```
+Results are collected and announced together when all complete.
 
 ## Auto-Completion & Artifacts
 
@@ -252,24 +191,14 @@ Please greet the user and continue the conversation.
 
 ## Evaluate Loop (Generator-Evaluator)
 
-For iterative work, use the evaluate pattern:
+For iterative work, use the evaluate pattern with task creation:
 
 ```json
-{
-  "action": "spawn",
-  "agent": "generator_agent",
-  "task": "Generate initial proposal",
-  "mode": "async"
-}
+{"action": "create", "subject": "Generate initial proposal", "assignee": "generator_agent"}
 
 // Wait for result, then:
 
-{
-  "action": "spawn",
-  "agent": "evaluator_agent",
-  "task": "Review proposal and provide feedback",
-  "context": "[previous result from generator]"
-}
+{"action": "create", "subject": "Review proposal and provide feedback", "assignee": "evaluator_agent"}
 
 // Generator refines based on feedback...
 ```
@@ -290,12 +219,12 @@ For async delegations, the lead receives periodic grouped updates (if progress n
 
 ## Best Practices
 
-1. **Omit `team_task_id` for simplicity**: v2 teams auto-create tasks on delegation
-2. **Use sync for quick tasks**: < 2 minutes
-3. **Use async for long tasks**: > 2 minutes, parallel work
-4. **Batch parallel work**: Delegate to multiple members simultaneously
+1. **Use `team_tasks` to delegate**: create tasks with `assignee` — system auto-dispatches
+2. **Don't use `spawn` for delegation**: `spawn` is self-clone only, not for team members
+3. **Create multiple tasks in one turn**: they dispatch in parallel after the turn ends
+4. **Use `blocked_by`**: coordinate task ordering with dependencies
 5. **Link dependencies**: Use `blocked_by` on task board to coordinate order
 6. **Handle handoffs gracefully**: Notify user of transfer; pass context
 7. **Set iteration limits in instructions**: Prevent infinite evaluate loops
 
-<!-- goclaw-source: 57754a5 | updated: 2026-03-18 -->
+<!-- goclaw-source: 0dab087f | updated: 2026-03-27 -->

channels/telegram.md

@@ -40,6 +40,7 @@ All config keys are in `channels.telegram`:
 | `dm_policy` | string | `"pairing"` | `pairing`, `allowlist`, `open`, `disabled` |
 | `group_policy` | string | `"open"` | `open`, `allowlist`, `disabled` |
 | `require_mention` | bool | true | Require @bot mention in groups |
+| `mention_mode` | string | `"strict"` | `strict` = only respond when @mentioned; `yield` = respond unless another bot is @mentioned (multi-bot groups) |
 | `history_limit` | int | 50 | Pending messages per group (0=disabled) |
 | `dm_stream` | bool | false | Enable streaming for DMs (edits placeholder) |
 | `group_stream` | bool | false | Enable streaming for groups (new message) |
@@ -94,6 +95,7 @@ Group config keys:
 - `group_policy` — Override group-level policy
 - `allow_from` — Override allowlist
 - `require_mention` — Override mention requirement
+- `mention_mode` — Override mention mode (`strict` or `yield`)
 - `skills` — Whitelist skills (nil=all, []=none)
 - `tools` — Whitelist tools (supports `group:xxx` syntax)
 - `system_prompt` — Extra system prompt for this group
@@ -105,9 +107,37 @@ Group config keys:
 
 In groups, bot responds only to messages that mention it (default `require_mention: true`). When not mentioned, messages are stored in a pending history buffer (default 50 messages) and included as context when the bot is mentioned. Replying to a bot message counts as mentioning it.
 
+#### Mention Modes
+
+| Mode | Behavior | Use case |
+|------|----------|----------|
+| `strict` (default) | Only respond when @mentioned or replied to | Single-bot groups |
+| `yield` | Respond to all messages UNLESS another bot/user is @mentioned | Multi-bot shared groups |
+
+**Yield mode** enables multiple bots to coexist in one group without conflicts:
+- Bot responds to all messages where no specific @mention targets another bot
+- If a user @mentions a different bot, this bot stays silent (yields)
+- Messages from other bots are automatically skipped to prevent infinite cross-bot loops
+- Cross-bot @commands still work (e.g., `@my_bot help` sent by another bot)
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "mention_mode": "yield",
+      "require_mention": false
+    }
+  }
+}
+```
+
 ```mermaid
 flowchart TD
-    MSG["User posts in group"] --> MENTION{"Bot @mentioned<br/>or reply?"}
+    MSG["User posts in group"] --> MODE{"mention_mode?"}
+    MODE -->|strict| MENTION{"Bot @mentioned<br/>or reply?"}
+    MODE -->|yield| OTHER{"Another bot/user<br/>@mentioned?"}
+    OTHER -->|Yes| YIELD["Yield — stay silent"]
+    OTHER -->|No| PROCESS
     MENTION -->|No| BUFFER["Add to pending history<br/>(max 50 messages)"]
     MENTION -->|Yes| PROCESS["Process now<br/>Include history as context"]
     BUFFER --> NEXT["Next mention:<br/>history included"]
@@ -232,7 +262,7 @@ Each Telegram instance maintains an isolated HTTP transport — no shared connec
 
 | Issue | Solution |
 |-------|----------|
-| Bot not responding in groups | Ensure privacy mode is disabled via @BotFather (`/setprivacy` → Disable). Then check `require_mention=true` (default) — mention bot or reply to its message. |
+| Bot not responding in groups | Ensure privacy mode is disabled via @BotFather (`/setprivacy` → Disable). Then check `require_mention=true` (default) — mention bot or reply to its message. For multi-bot groups, try `mention_mode: "yield"`. |
 | Media downloads fail | Verify bot has `Can read all group messages` in @BotFather (`/setprivacy` → Disable). Check `media_max_bytes` limit. |
 | STT transcription missing | Verify STT proxy URL and API key. Check logs for timeout. |
 | Streaming not working | Enable `dm_stream` or `group_stream`. Ensure provider supports streaming. |
@@ -245,4 +275,4 @@ Each Telegram instance maintains an isolated HTTP transport — no shared connec
 - [Browser Pairing](#channel-browser-pairing) — Pairing flow
 - [Sessions & History](#sessions-and-history) — Conversation history
 
-<!-- goclaw-source: eab3766c | updated: 2026-03-24 -->
+<!-- goclaw-source: 0dab087f | updated: 2026-03-26 -->

core-concepts/how-goclaw-works.md

@@ -15,7 +15,7 @@ graph TD
     GW --> SC[Scheduler<br/>4 lanes]
     SC --> AL[Agent Loop<br/>Think → Act → Observe]
     AL --> PR[Provider Registry<br/>18+ LLM providers]
-    AL --> TR[Tool Registry<br/>33+ built-in tools]
+    AL --> TR[Tool Registry<br/>50+ built-in tools]
     AL --> SS[Session Store<br/>PostgreSQL]
     AL --> MM[Memory Store<br/>Vector + FTS]
     PR --> LLM[LLM APIs<br/>OpenAI / Anthropic / ...]
@@ -37,7 +37,7 @@ If the LLM wants to use a tool (search the web, read a file, run code), GoClaw e
 
 The tool results go back to the LLM. It can call more tools or generate a final response. This loop repeats up to 20 iterations per turn.
 
-GoClaw detects tool loop patterns: a **warning** is raised after 3 identical consecutive calls, and the loop is **force-stopped** after 5 identical no-progress calls.
+GoClaw detects tool loop patterns: a **warning** is raised after 3 identical consecutive calls, and the loop is **force-stopped** after 5 identical no-progress calls. Note: `exec`/`bash` tools and MCP bridge tools (`mcp_*` prefix) are treated as **neutral** — they neither reset nor increment the read-only streak, since their side effects are ambiguous.
 
 ```mermaid
 graph LR
@@ -82,7 +82,7 @@ Each lane has its own semaphore. This prevents cron jobs from starving user mess
 |-----------|-------------|
 | **Gateway** | HTTP + WebSocket server on port 18790 |
 | **Provider Registry** | Manages 18+ LLM provider connections and credentials |
-| **Tool Registry** | 33+ built-in tools with policy-based access control (extensible via MCP and custom tools) |
+| **Tool Registry** | 50+ built-in tools with policy-based access control (extensible via MCP and custom tools) |
 | **Session Store** | Write-behind cache + PostgreSQL persistence |
 | **Memory Store** | Hybrid search with pgvector + tsvector |
 | **Channel Managers** | Telegram, Discord, WhatsApp, Zalo, Feishu adapters |
@@ -103,4 +103,4 @@ Each lane has its own semaphore. This prevents cron jobs from starving user mess
 - [Tools Overview](#tools-overview) — The full tool catalog
 - [Sessions and History](#sessions-and-history) — How conversations persist
 
-<!-- goclaw-source: 19eef35 | updated: 2026-03-25 -->
+<!-- goclaw-source: 9168e4b4 | updated: 2026-03-26 -->

providers/ollama.md

@@ -21,10 +21,27 @@ Ollama lets you run large language models on your own machine. GoClaw connects t
 }
 ```
 
+## Docker Deployment
+
+When running GoClaw inside Docker, `localhost` and `127.0.0.1` in provider URLs are automatically rewritten to `host.docker.internal` so the container can reach Ollama running on the host machine. No manual configuration needed.
+
+If Ollama is running on a different host, set the full URL explicitly:
+
+```json
+{
+  "providers": {
+    "ollama": {
+      "provider_type": "ollama",
+      "api_base": "http://my-ollama-server:11434/v1"
+    }
+  }
+}
+```
+
 ## What's Next
 
 - [Provider Overview](#providers-overview)
 - [Ollama Cloud](#provider-ollama-cloud) — hosted Ollama option
 - [Custom / OpenAI-Compatible](#provider-custom)
 
-<!-- goclaw-source: 57754a5 | updated: 2026-03-18 -->
+<!-- goclaw-source: 9168e4b4 | updated: 2026-03-26 -->

reference/rest-api.md

@@ -436,7 +436,24 @@ Get an MCP server.
 
 ### `PUT /v1/mcp/servers/{id}`
 
-Update an MCP server.
+Update an MCP server. Updatable fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Server display name |
+| `transport` | string | `"stdio"`, `"sse"`, `"streamable-http"` |
+| `command` | string | Command to run (stdio) |
+| `args` | string[] | Command arguments |
+| `url` | string | Server URL (sse/streamable-http) |
+| `api_key` | string | API key for the server |
+| `env` | object | Environment variables |
+| `headers` | object | HTTP headers |
+| `enabled` | boolean | Enable/disable |
+| `tool_prefix` | string | Prefix for tool names |
+| `timeout_sec` | integer | Request timeout in seconds |
+| `agent_id` | string | Bind to specific agent |
+| `config` | object | Additional configuration |
+| `settings` | object | Server settings |
 
 ### `DELETE /v1/mcp/servers/{id}`
 
@@ -502,7 +519,20 @@ Get a channel instance.
 
 ### `PUT /v1/channels/instances/{id}`
 
-Update a channel instance.
+Update a channel instance. Updatable fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `channel_type` | string | Channel type |
+| `credentials` | object | Channel credentials |
+| `agent_id` | string | Bound agent UUID |
+| `enabled` | boolean | Enable/disable |
+| `display_name` | string | Human-readable name |
+| `group_policy` | string | Group message policy |
+| `allow_from` | string[] | Allowed sender IDs |
+| `metadata` | object | Custom metadata |
+| `webhook_secret` | string | Webhook verification secret |
+| `config` | object | Additional configuration |
 
 ### `DELETE /v1/channels/instances/{id}`
 
@@ -782,4 +812,4 @@ The following are **only available via WebSocket RPC**, not HTTP:
 - [Config Reference](#config-reference) — full `config.json` schema
 - [Database Schema](#database-schema) — table definitions and relationships
 
-<!-- goclaw-source: 4d31fe0 | updated: 2026-03-26 -->
+<!-- goclaw-source: 9168e4b4 | updated: 2026-03-26 -->