let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document multi-agent mode

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-06 18:25:52 +00:00
parent dbfa316d19
commit 730cc72388
35 changed files with 343 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/session-tool.md
View File

@@ -6,7 +6,7 @@ read_when:
# Session Tools
Goal: small, hard-to-misuse tool surface so agents can list sessions, fetch history, and send to another session.
Goal: small, hard-to-misuse tool set so agents can list sessions, fetch history, and send to another session.
## Tool Names
- `sessions_list`
@@ -16,7 +16,7 @@ Goal: small, hard-to-misuse tool surface so agents can list sessions, fetch hist
## Key Model
- Main direct chat bucket is always the literal key `"main"`.
- Group chats use `surface:group:<id>` or `surface:channel:<id>`.
- Group chats use `<provider>:group:<id>` or `<provider>:channel:<id>`.
- Cron jobs use `cron:<job.id>`.
- Hooks use `hook:<uuid>` unless explicitly set.
- Node bridge uses `node-<nodeId>` unless explicitly set.
@@ -47,7 +47,7 @@ Row shape (JSON):
- `model`, `contextTokens`, `totalTokens`
- `thinkingLevel`, `verboseLevel`, `systemSent`, `abortedLastRun`
- `sendPolicy` (session override if set)
- `lastChannel`, `lastTo`
- `lastProvider`, `lastTo`
- `transcriptPath` (best-effort path derived from store dir + sessionId)
- `messages?` (only when `messageLimit > 0`)
@@ -84,17 +84,17 @@ Behavior:
- Max turns is `session.agentToAgent.maxPingPongTurns` (0–5, default 5).
- Once the loop ends, Clawdbot runs the **agent‑to‑agent announce step** (target agent only):
- Reply exactly `ANNOUNCE_SKIP` to stay silent.
- Any other reply is sent to the target channel.
- Any other reply is sent to the target provider.
- Announce step includes the original request + round‑1 reply + latest ping‑pong reply.
## Provider Field
- For groups, `provider` is the `surface` recorded on the session entry.
- For direct chats, `provider` maps from `lastChannel`.
- For groups, `provider` is the provider recorded on the session entry.
- For direct chats, `provider` maps from `lastProvider`.
- For cron/hook/node, `provider` is `internal`.
- If missing, `provider` is `unknown`.
## Security / Send Policy
Policy-based blocking by surface/chat type (not per session id).
Policy-based blocking by provider/chat type (not per session id).
```json
{
@@ -102,7 +102,7 @@ Policy-based blocking by surface/chat type (not per session id).
"sendPolicy": {
"rules": [
{
"match": { "surface": "discord", "chatType": "group" },
"match": { "provider": "discord", "chatType": "group" },
"action": "deny"
}
],
@@ -121,7 +121,7 @@ Enforcement points:
- auto-reply delivery logic
## sessions_spawn
Spawn a sub-agent run in an isolated session and announce the result back to the requester chat surface.
Spawn a sub-agent run in an isolated session and announce the result back to the requester chat provider.
Parameters:
- `task` (required)
@@ -131,9 +131,9 @@ Parameters:
Behavior:
- Starts a new `subagent:<uuid>` session with `deliver: false`.
- Sub-agents default to the full tool surface **minus session tools** (configurable via `agent.subagents.tools`).
- Sub-agents default to the full tool set **minus session tools** (configurable via `agent.subagents.tools`).
- Sub-agents are not allowed to call `sessions_spawn` (no sub-agent → sub-agent spawning).
- After completion (or best-effort wait), Clawdbot runs a sub-agent **announce step** and posts the result to the requester chat surface.
- After completion (or best-effort wait), Clawdbot runs a sub-agent **announce step** and posts the result to the requester chat provider.
- Reply exactly `ANNOUNCE_SKIP` during the announce step to stay silent.
## Sandbox Session Visibility