From 0851682080c232c2dc7e0e82f6bb786cf99e54b3 Mon Sep 17 00:00:00 2001
From: sheeek <gitlab@ott.team>
Date: Wed, 7 Jan 2026 11:57:51 +0100
Subject: [PATCH 01/14] feat(types): add sandbox and tools fields to
 routing.agents

Add optional per-agent configuration:
- sandbox: { mode, scope, perSession, workspaceRoot }
- tools: { allow, deny }

These will allow agents to override global agent.sandbox and
agent.tools settings.
---
 src/config/types.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/config/types.ts b/src/config/types.ts
index e5a23ad01..a1c8adb44 100644
--- a/src/config/types.ts
+++ b/src/config/types.ts
@@ -592,6 +592,10 @@ export type RoutingConfig = {
         perSession?: boolean;
         workspaceRoot?: string;
       };
+      tools?: {
+        allow?: string[];
+        deny?: string[];
+      };
     }
   >;
   bindings?: Array<{

From 304857cf438ab487ed71a04121d92d8446bc5556 Mon Sep 17 00:00:00 2001
From: sheeek <gitlab@ott.team>
Date: Wed, 7 Jan 2026 11:57:57 +0100
Subject: [PATCH 02/14] feat(config): add Zod validation for routing.agents
 sandbox and tools

Validate per-agent sandbox config:
- mode: 'off' | 'non-main' | 'all'
- scope: 'session' | 'agent' | 'shared'
- perSession: boolean
- workspaceRoot: string

Validate per-agent tools config:
- allow: string[]
- deny: string[]
---
 src/config/zod-schema.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/config/zod-schema.ts b/src/config/zod-schema.ts
index 28eeb4d1b..0f4e018d3 100644
--- a/src/config/zod-schema.ts
+++ b/src/config/zod-schema.ts
@@ -247,6 +247,12 @@ const RoutingSchema = z
                 workspaceRoot: z.string().optional(),
               })
               .optional(),
+            tools: z
+              .object({
+                allow: z.array(z.string()).optional(),
+                deny: z.array(z.string()).optional(),
+              })
+              .optional(),
           })
           .optional(),
       )

From cc9fdfe56263d78b5dfefc4c9cbf436fed57c43e Mon Sep 17 00:00:00 2001
From: sheeek <gitlab@ott.team>
Date: Wed, 7 Jan 2026 11:58:04 +0100
Subject: [PATCH 03/14] feat(agent-scope): extend resolveAgentConfig to return
 sandbox and tools

Return newly added fields from routing.agents config:
- sandbox: agent-specific sandbox configuration
- tools: agent-specific tool restrictions

This makes per-agent sandbox and tool settings accessible
to other parts of the codebase.
---
 src/agents/agent-scope.ts | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/agents/agent-scope.ts b/src/agents/agent-scope.ts
index 34feee5d6..adc5e3789 100644
--- a/src/agents/agent-scope.ts
+++ b/src/agents/agent-scope.ts
@@ -27,6 +27,16 @@ export function resolveAgentConfig(
       workspace?: string;
       agentDir?: string;
       model?: string;
+      sandbox?: {
+        mode?: "off" | "non-main" | "all";
+        scope?: "session" | "agent" | "shared";
+        perSession?: boolean;
+        workspaceRoot?: string;
+      };
+      tools?: {
+        allow?: string[];
+        deny?: string[];
+      };
     }
   | undefined {
   const id = normalizeAgentId(agentId);
@@ -40,6 +50,8 @@ export function resolveAgentConfig(
       typeof entry.workspace === "string" ? entry.workspace : undefined,
     agentDir: typeof entry.agentDir === "string" ? entry.agentDir : undefined,
     model: typeof entry.model === "string" ? entry.model : undefined,
+    sandbox: entry.sandbox,
+    tools: entry.tools,
   };
 }
 

From 1e3caf07d4c511a193c7cd00a86eec023d66412b Mon Sep 17 00:00:00 2001
From: sheeek <gitlab@ott.team>
Date: Wed, 7 Jan 2026 11:58:12 +0100
Subject: [PATCH 04/14] feat(sandbox): support agent-specific sandbox config
 override

Changes to defaultSandboxConfig():
- Add optional agentId parameter
- Load routing.agents[agentId].sandbox if available
- Prefer agent-specific settings over global agent.sandbox

Update callers in resolveSandboxContext() and
ensureSandboxWorkspaceForSession() to extract agentId
from sessionKey and pass it to defaultSandboxConfig().

This enables per-agent sandbox modes (e.g., main: off, family: all).
---
 src/agents/sandbox.ts | 28 ++++++++++++++++++++--------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/src/agents/sandbox.ts b/src/agents/sandbox.ts
index d3134f04b..547553268 100644
--- a/src/agents/sandbox.ts
+++ b/src/agents/sandbox.ts
@@ -226,16 +226,26 @@ function resolveSandboxScopeKey(scope: SandboxScope, sessionKey: string) {
   return `agent:${agentId}`;
 }
 
-function defaultSandboxConfig(cfg?: ClawdbotConfig): SandboxConfig {
+function defaultSandboxConfig(cfg?: ClawdbotConfig, agentId?: string): SandboxConfig {
   const agent = cfg?.agent?.sandbox;
+  
+  // Agent-specific sandbox config overrides global
+  let agentSandbox: typeof agent | undefined;
+  if (agentId && cfg?.routing?.agents) {
+    const agentConfig = cfg.routing.agents[agentId];
+    if (agentConfig && typeof agentConfig === "object") {
+      agentSandbox = agentConfig.sandbox;
+    }
+  }
+  
   return {
-    mode: agent?.mode ?? "off",
+    mode: agentSandbox?.mode ?? agent?.mode ?? "off",
     scope: resolveSandboxScope({
-      scope: agent?.scope,
-      perSession: agent?.perSession,
+      scope: agentSandbox?.scope ?? agent?.scope,
+      perSession: agentSandbox?.perSession ?? agent?.perSession,
     }),
-    workspaceAccess: agent?.workspaceAccess ?? "none",
-    workspaceRoot: agent?.workspaceRoot ?? DEFAULT_SANDBOX_WORKSPACE_ROOT,
+    workspaceAccess: agentSandbox?.workspaceAccess ?? agent?.workspaceAccess ?? "none",
+    workspaceRoot: agentSandbox?.workspaceRoot ?? agent?.workspaceRoot ?? DEFAULT_SANDBOX_WORKSPACE_ROOT,
     docker: {
       image: agent?.docker?.image ?? DEFAULT_SANDBOX_IMAGE,
       containerPrefix:
@@ -924,7 +934,8 @@ export async function resolveSandboxContext(params: {
 }): Promise<SandboxContext | null> {
   const rawSessionKey = params.sessionKey?.trim();
   if (!rawSessionKey) return null;
-  const cfg = defaultSandboxConfig(params.config);
+  const agentId = resolveAgentIdFromSessionKey(rawSessionKey);
+  const cfg = defaultSandboxConfig(params.config, agentId);
   const mainKey = params.config?.session?.mainKey?.trim() || "main";
   if (!shouldSandboxSession(cfg, rawSessionKey, mainKey)) return null;
 
@@ -986,7 +997,8 @@ export async function ensureSandboxWorkspaceForSession(params: {
 }): Promise<SandboxWorkspaceInfo | null> {
   const rawSessionKey = params.sessionKey?.trim();
   if (!rawSessionKey) return null;
-  const cfg = defaultSandboxConfig(params.config);
+  const agentId = resolveAgentIdFromSessionKey(rawSessionKey);
+  const cfg = defaultSandboxConfig(params.config, agentId);
   const mainKey = params.config?.session?.mainKey?.trim() || "main";
   if (!shouldSandboxSession(cfg, rawSessionKey, mainKey)) return null;
 

From 0fffde00a8cb497e2dae9b2903e0f0c5d75f6a15 Mon Sep 17 00:00:00 2001
From: sheeek <gitlab@ott.team>
Date: Wed, 7 Jan 2026 11:58:19 +0100
Subject: [PATCH 05/14] feat(tools): add agent-specific tool filtering
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add tool filtering layer for per-agent restrictions:
- Extract agentId from sessionKey
- Load routing.agents[agentId].tools via resolveAgentConfig()
- Apply agent-specific allow/deny before sandbox filtering

Filtering order:
1. Global (agent.tools)
2. Agent-specific (routing.agents[id].tools) ← NEW
3. Sandbox (agent.sandbox.tools)
4. Subagent policy

This enables different tool permissions per agent
(e.g., main: all tools, family: read only).
---
 src/agents/pi-tools.ts | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/agents/pi-tools.ts b/src/agents/pi-tools.ts
index baaadd0b8..7687e788d 100644
--- a/src/agents/pi-tools.ts
+++ b/src/agents/pi-tools.ts
@@ -11,6 +11,10 @@ import type { ClawdbotConfig } from "../config/config.js";
 import { detectMime } from "../media/mime.js";
 import { isSubagentSessionKey } from "../routing/session-key.js";
 import { startWebLoginWithQr, waitForWebLogin } from "../web/login-qr.js";
+import {
+  resolveAgentConfig,
+  resolveAgentIdFromSessionKey,
+} from "./agent-scope.js";
 import {
   type BashToolDefaults,
   createBashTool,
@@ -592,9 +596,20 @@ export function createClawdbotCodingTools(options?: {
       options.config.agent.tools.deny?.length)
       ? filterToolsByPolicy(filtered, options.config.agent.tools)
       : filtered;
+  
+  // Agent-specific tool policy
+  let agentFiltered = globallyFiltered;
+  if (options?.sessionKey && options?.config) {
+    const agentId = resolveAgentIdFromSessionKey(options.sessionKey);
+    const agentConfig = resolveAgentConfig(options.config, agentId);
+    if (agentConfig?.tools) {
+      agentFiltered = filterToolsByPolicy(globallyFiltered, agentConfig.tools);
+    }
+  }
+  
   const sandboxed = sandbox
-    ? filterToolsByPolicy(globallyFiltered, sandbox.tools)
-    : globallyFiltered;
+    ? filterToolsByPolicy(agentFiltered, sandbox.tools)
+    : agentFiltered;
   const subagentFiltered =
     isSubagentSessionKey(options?.sessionKey) && options?.sessionKey
       ? filterToolsByPolicy(

From 23210f5f70a7d4e02ab96cd2276d2d2fcf0c8240 Mon Sep 17 00:00:00 2001
From: sheeek <gitlab@ott.team>
Date: Wed, 7 Jan 2026 11:58:28 +0100
Subject: [PATCH 06/14] test(agent-scope): add tests for sandbox and tools
 config resolution

Add 7 tests for resolveAgentConfig():
- Return undefined when no agents config exists
- Return undefined when agent id does not exist
- Return basic agent config (name, workspace, agentDir, model)
- Return agent-specific sandbox config
- Return agent-specific tools config
- Return both sandbox and tools config
- Normalize agent id

All tests pass.
---
 src/agents/agent-scope.test.ts | 130 +++++++++++++++++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 src/agents/agent-scope.test.ts

diff --git a/src/agents/agent-scope.test.ts b/src/agents/agent-scope.test.ts
new file mode 100644
index 000000000..339087959
--- /dev/null
+++ b/src/agents/agent-scope.test.ts
@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+import type { ClawdbotConfig } from "../config/config.js";
+import { resolveAgentConfig } from "./agent-scope.js";
+
+describe("resolveAgentConfig", () => {
+  it("should return undefined when no agents config exists", () => {
+    const cfg: ClawdbotConfig = {};
+    const result = resolveAgentConfig(cfg, "main");
+    expect(result).toBeUndefined();
+  });
+
+  it("should return undefined when agent id does not exist", () => {
+    const cfg: ClawdbotConfig = {
+      routing: {
+        agents: {
+          main: { workspace: "~/clawd" },
+        },
+      },
+    };
+    const result = resolveAgentConfig(cfg, "nonexistent");
+    expect(result).toBeUndefined();
+  });
+
+  it("should return basic agent config", () => {
+    const cfg: ClawdbotConfig = {
+      routing: {
+        agents: {
+          main: {
+            name: "Main Agent",
+            workspace: "~/clawd",
+            agentDir: "~/.clawdbot/agents/main",
+            model: "anthropic/claude-opus-4",
+          },
+        },
+      },
+    };
+    const result = resolveAgentConfig(cfg, "main");
+    expect(result).toEqual({
+      name: "Main Agent",
+      workspace: "~/clawd",
+      agentDir: "~/.clawdbot/agents/main",
+      model: "anthropic/claude-opus-4",
+      sandbox: undefined,
+      tools: undefined,
+    });
+  });
+
+  it("should return agent-specific sandbox config", () => {
+    const cfg: ClawdbotConfig = {
+      routing: {
+        agents: {
+          work: {
+            workspace: "~/clawd-work",
+            sandbox: {
+              mode: "all",
+              scope: "agent",
+              perSession: false,
+              workspaceRoot: "~/sandboxes",
+            },
+          },
+        },
+      },
+    };
+    const result = resolveAgentConfig(cfg, "work");
+    expect(result?.sandbox).toEqual({
+      mode: "all",
+      scope: "agent",
+      perSession: false,
+      workspaceRoot: "~/sandboxes",
+    });
+  });
+
+  it("should return agent-specific tools config", () => {
+    const cfg: ClawdbotConfig = {
+      routing: {
+        agents: {
+          restricted: {
+            workspace: "~/clawd-restricted",
+            tools: {
+              allow: ["read"],
+              deny: ["bash", "write", "edit"],
+            },
+          },
+        },
+      },
+    };
+    const result = resolveAgentConfig(cfg, "restricted");
+    expect(result?.tools).toEqual({
+      allow: ["read"],
+      deny: ["bash", "write", "edit"],
+    });
+  });
+
+  it("should return both sandbox and tools config", () => {
+    const cfg: ClawdbotConfig = {
+      routing: {
+        agents: {
+          family: {
+            workspace: "~/clawd-family",
+            sandbox: {
+              mode: "all",
+              scope: "agent",
+            },
+            tools: {
+              allow: ["read"],
+              deny: ["bash"],
+            },
+          },
+        },
+      },
+    };
+    const result = resolveAgentConfig(cfg, "family");
+    expect(result?.sandbox?.mode).toBe("all");
+    expect(result?.tools?.allow).toEqual(["read"]);
+  });
+
+  it("should normalize agent id", () => {
+    const cfg: ClawdbotConfig = {
+      routing: {
+        agents: {
+          main: { workspace: "~/clawd" },
+        },
+      },
+    };
+    // Should normalize to "main" (default)
+    const result = resolveAgentConfig(cfg, "");
+    expect(result).toBeDefined();
+    expect(result?.workspace).toBe("~/clawd");
+  });
+});

From 6d241be4302e357fcec375c27dac5222d8ac22b6 Mon Sep 17 00:00:00 2001
From: sheeek <gitlab@ott.team>
Date: Wed, 7 Jan 2026 11:58:36 +0100
Subject: [PATCH 07/14] test(sandbox): add tests for agent-specific sandbox
 override

Add 6 tests for agent-specific sandbox configuration:
- Use global sandbox config when no agent-specific config exists
- Override with agent-specific sandbox mode 'off'
- Use agent-specific sandbox mode 'all'
- Use agent-specific scope
- Use agent-specific workspaceRoot
- Prefer agent config over global for multiple agents

All tests pass.
---
 src/agents/sandbox-agent-config.test.ts | 216 ++++++++++++++++++++++++
 1 file changed, 216 insertions(+)
 create mode 100644 src/agents/sandbox-agent-config.test.ts

diff --git a/src/agents/sandbox-agent-config.test.ts b/src/agents/sandbox-agent-config.test.ts
new file mode 100644
index 000000000..040b3d483
--- /dev/null
+++ b/src/agents/sandbox-agent-config.test.ts
@@ -0,0 +1,216 @@
+import { describe, expect, it } from "vitest";
+import type { ClawdbotConfig } from "../config/config.js";
+
+// We need to test the internal defaultSandboxConfig function, but it's not exported.
+// Instead, we test the behavior through resolveSandboxContext which uses it.
+
+describe("Agent-specific sandbox config", () => {
+  it("should use global sandbox config when no agent-specific config exists", async () => {
+    const { resolveSandboxContext } = await import("./sandbox.js");
+    
+    const cfg: ClawdbotConfig = {
+      agent: {
+        sandbox: {
+          mode: "all",
+          scope: "agent",
+        },
+      },
+      routing: {
+        agents: {
+          main: {
+            workspace: "~/clawd",
+          },
+        },
+      },
+    };
+
+    const context = await resolveSandboxContext({
+      config: cfg,
+      sessionKey: "agent:main:main",
+      workspaceDir: "/tmp/test",
+    });
+
+    expect(context).toBeDefined();
+    expect(context?.enabled).toBe(true);
+  });
+
+  it("should override with agent-specific sandbox mode 'off'", async () => {
+    const { resolveSandboxContext } = await import("./sandbox.js");
+    
+    const cfg: ClawdbotConfig = {
+      agent: {
+        sandbox: {
+          mode: "all", // Global default
+          scope: "agent",
+        },
+      },
+      routing: {
+        agents: {
+          main: {
+            workspace: "~/clawd",
+            sandbox: {
+              mode: "off", // Agent override
+            },
+          },
+        },
+      },
+    };
+
+    const context = await resolveSandboxContext({
+      config: cfg,
+      sessionKey: "agent:main:main",
+      workspaceDir: "/tmp/test",
+    });
+
+    // Should be null because mode is "off"
+    expect(context).toBeNull();
+  });
+
+  it("should use agent-specific sandbox mode 'all'", async () => {
+    const { resolveSandboxContext } = await import("./sandbox.js");
+    
+    const cfg: ClawdbotConfig = {
+      agent: {
+        sandbox: {
+          mode: "off", // Global default
+        },
+      },
+      routing: {
+        agents: {
+          family: {
+            workspace: "~/clawd-family",
+            sandbox: {
+              mode: "all", // Agent override
+              scope: "agent",
+            },
+          },
+        },
+      },
+    };
+
+    const context = await resolveSandboxContext({
+      config: cfg,
+      sessionKey: "agent:family:whatsapp:group:123",
+      workspaceDir: "/tmp/test-family",
+    });
+
+    expect(context).toBeDefined();
+    expect(context?.enabled).toBe(true);
+  });
+
+  it("should use agent-specific scope", async () => {
+    const { resolveSandboxContext } = await import("./sandbox.js");
+    
+    const cfg: ClawdbotConfig = {
+      agent: {
+        sandbox: {
+          mode: "all",
+          scope: "session", // Global default
+        },
+      },
+      routing: {
+        agents: {
+          work: {
+            workspace: "~/clawd-work",
+            sandbox: {
+              mode: "all",
+              scope: "agent", // Agent override
+            },
+          },
+        },
+      },
+    };
+
+    const context = await resolveSandboxContext({
+      config: cfg,
+      sessionKey: "agent:work:slack:channel:456",
+      workspaceDir: "/tmp/test-work",
+    });
+
+    expect(context).toBeDefined();
+    // The container name should use agent scope (agent:work)
+    expect(context?.containerName).toContain("agent-work");
+  });
+
+  it("should use agent-specific workspaceRoot", async () => {
+    const { resolveSandboxContext } = await import("./sandbox.js");
+    
+    const cfg: ClawdbotConfig = {
+      agent: {
+        sandbox: {
+          mode: "all",
+          scope: "agent",
+          workspaceRoot: "~/.clawdbot/sandboxes", // Global default
+        },
+      },
+      routing: {
+        agents: {
+          isolated: {
+            workspace: "~/clawd-isolated",
+            sandbox: {
+              mode: "all",
+              scope: "agent",
+              workspaceRoot: "/tmp/isolated-sandboxes", // Agent override
+            },
+          },
+        },
+      },
+    };
+
+    const context = await resolveSandboxContext({
+      config: cfg,
+      sessionKey: "agent:isolated:main",
+      workspaceDir: "/tmp/test-isolated",
+    });
+
+    expect(context).toBeDefined();
+    expect(context?.workspaceDir).toContain("/tmp/isolated-sandboxes");
+  });
+
+  it("should prefer agent config over global for multiple agents", async () => {
+    const { resolveSandboxContext } = await import("./sandbox.js");
+    
+    const cfg: ClawdbotConfig = {
+      agent: {
+        sandbox: {
+          mode: "non-main",
+          scope: "session",
+        },
+      },
+      routing: {
+        agents: {
+          main: {
+            workspace: "~/clawd",
+            sandbox: {
+              mode: "off", // main: no sandbox
+            },
+          },
+          family: {
+            workspace: "~/clawd-family",
+            sandbox: {
+              mode: "all", // family: always sandbox
+              scope: "agent",
+            },
+          },
+        },
+      },
+    };
+
+    // main agent should not be sandboxed
+    const mainContext = await resolveSandboxContext({
+      config: cfg,
+      sessionKey: "agent:main:telegram:group:789",
+      workspaceDir: "/tmp/test-main",
+    });
+    expect(mainContext).toBeNull();
+
+    // family agent should be sandboxed
+    const familyContext = await resolveSandboxContext({
+      config: cfg,
+      sessionKey: "agent:family:whatsapp:group:123",
+      workspaceDir: "/tmp/test-family",
+    });
+    expect(familyContext).toBeDefined();
+    expect(familyContext?.enabled).toBe(true);
+  });
+});

From 04bbe3a594a0892bf2cc6c5eaa42f59684e2b05d Mon Sep 17 00:00:00 2001
From: sheeek <gitlab@ott.team>
Date: Wed, 7 Jan 2026 11:58:43 +0100
Subject: [PATCH 08/14] test(tools): add tests for agent-specific tool
 filtering

Add 5 tests for agent-specific tool restrictions:
- Apply global tool policy when no agent-specific policy exists
- Apply agent-specific tool policy
- Allow different tool policies for different agents
- Combine global and agent-specific deny lists
- Work with sandbox tools filtering

All tests pass.
---
 src/agents/pi-tools-agent-config.test.ts | 207 +++++++++++++++++++++++
 1 file changed, 207 insertions(+)
 create mode 100644 src/agents/pi-tools-agent-config.test.ts

diff --git a/src/agents/pi-tools-agent-config.test.ts b/src/agents/pi-tools-agent-config.test.ts
new file mode 100644
index 000000000..0b8affd39
--- /dev/null
+++ b/src/agents/pi-tools-agent-config.test.ts
@@ -0,0 +1,207 @@
+import { describe, expect, it } from "vitest";
+import type { ClawdbotConfig } from "../config/config.js";
+import { createClawdbotCodingTools } from "./pi-tools.js";
+
+describe("Agent-specific tool filtering", () => {
+  it("should apply global tool policy when no agent-specific policy exists", () => {
+    const cfg: ClawdbotConfig = {
+      agent: {
+        tools: {
+          allow: ["read", "write"],
+          deny: ["bash"],
+        },
+      },
+      routing: {
+        agents: {
+          main: {
+            workspace: "~/clawd",
+          },
+        },
+      },
+    };
+
+    const tools = createClawdbotCodingTools({
+      config: cfg,
+      sessionKey: "agent:main:main",
+      workspaceDir: "/tmp/test",
+      agentDir: "/tmp/agent",
+    });
+
+    const toolNames = tools.map((t) => t.name);
+    expect(toolNames).toContain("read");
+    expect(toolNames).toContain("write");
+    expect(toolNames).not.toContain("bash");
+  });
+
+  it("should apply agent-specific tool policy", () => {
+    const cfg: ClawdbotConfig = {
+      agent: {
+        tools: {
+          allow: ["read", "write", "bash"],
+          deny: [],
+        },
+      },
+      routing: {
+        agents: {
+          restricted: {
+            workspace: "~/clawd-restricted",
+            tools: {
+              allow: ["read"], // Agent override: only read
+              deny: ["bash", "write", "edit"],
+            },
+          },
+        },
+      },
+    };
+
+    const tools = createClawdbotCodingTools({
+      config: cfg,
+      sessionKey: "agent:restricted:main",
+      workspaceDir: "/tmp/test-restricted",
+      agentDir: "/tmp/agent-restricted",
+    });
+
+    const toolNames = tools.map((t) => t.name);
+    expect(toolNames).toContain("read");
+    expect(toolNames).not.toContain("bash");
+    expect(toolNames).not.toContain("write");
+    expect(toolNames).not.toContain("edit");
+  });
+
+  it("should allow different tool policies for different agents", () => {
+    const cfg: ClawdbotConfig = {
+      routing: {
+        agents: {
+          main: {
+            workspace: "~/clawd",
+            // No tools restriction - all tools available
+          },
+          family: {
+            workspace: "~/clawd-family",
+            tools: {
+              allow: ["read"],
+              deny: ["bash", "write", "edit", "process"],
+            },
+          },
+        },
+      },
+    };
+
+    // main agent: all tools
+    const mainTools = createClawdbotCodingTools({
+      config: cfg,
+      sessionKey: "agent:main:main",
+      workspaceDir: "/tmp/test-main",
+      agentDir: "/tmp/agent-main",
+    });
+    const mainToolNames = mainTools.map((t) => t.name);
+    expect(mainToolNames).toContain("bash");
+    expect(mainToolNames).toContain("write");
+    expect(mainToolNames).toContain("edit");
+
+    // family agent: restricted
+    const familyTools = createClawdbotCodingTools({
+      config: cfg,
+      sessionKey: "agent:family:whatsapp:group:123",
+      workspaceDir: "/tmp/test-family",
+      agentDir: "/tmp/agent-family",
+    });
+    const familyToolNames = familyTools.map((t) => t.name);
+    expect(familyToolNames).toContain("read");
+    expect(familyToolNames).not.toContain("bash");
+    expect(familyToolNames).not.toContain("write");
+    expect(familyToolNames).not.toContain("edit");
+  });
+
+  it("should combine global and agent-specific deny lists", () => {
+    const cfg: ClawdbotConfig = {
+      agent: {
+        tools: {
+          deny: ["browser"], // Global deny
+        },
+      },
+      routing: {
+        agents: {
+          work: {
+            workspace: "~/clawd-work",
+            tools: {
+              deny: ["bash", "process"], // Agent deny
+            },
+          },
+        },
+      },
+    };
+
+    const tools = createClawdbotCodingTools({
+      config: cfg,
+      sessionKey: "agent:work:slack:dm:user123",
+      workspaceDir: "/tmp/test-work",
+      agentDir: "/tmp/agent-work",
+    });
+
+    const toolNames = tools.map((t) => t.name);
+    // Both global and agent denies should be applied
+    expect(toolNames).not.toContain("browser");
+    expect(toolNames).not.toContain("bash");
+    expect(toolNames).not.toContain("process");
+  });
+
+  it("should work with sandbox tools filtering", () => {
+    const cfg: ClawdbotConfig = {
+      agent: {
+        sandbox: {
+          mode: "all",
+          scope: "agent",
+          tools: {
+            allow: ["read", "write", "bash"], // Sandbox allows these
+            deny: [],
+          },
+        },
+      },
+      routing: {
+        agents: {
+          restricted: {
+            workspace: "~/clawd-restricted",
+            sandbox: {
+              mode: "all",
+              scope: "agent",
+            },
+            tools: {
+              allow: ["read"], // Agent further restricts to only read
+              deny: ["bash", "write"],
+            },
+          },
+        },
+      },
+    };
+
+    const tools = createClawdbotCodingTools({
+      config: cfg,
+      sessionKey: "agent:restricted:main",
+      workspaceDir: "/tmp/test-restricted",
+      agentDir: "/tmp/agent-restricted",
+      sandbox: {
+        enabled: true,
+        sessionKey: "agent:restricted:main",
+        workspaceDir: "/tmp/sandbox",
+        agentWorkspaceDir: "/tmp/test-restricted",
+        workspaceAccess: "none",
+        containerName: "test-container",
+        containerWorkdir: "/workspace",
+        docker: {} as any,
+        tools: {
+          allow: ["read", "write", "bash"],
+          deny: [],
+        },
+      },
+    });
+
+    const toolNames = tools.map((t) => t.name);
+    // Agent policy should be applied first, then sandbox
+    // Agent allows only "read", sandbox allows ["read", "write", "bash"]
+    // Result: only "read" (most restrictive wins)
+    expect(toolNames).toContain("read");
+    expect(toolNames).not.toContain("bash");
+    expect(toolNames).not.toContain("write");
+  });
+});

From bf4b89e8733abbd21c17506d0f804d961ba1ed05 Mon Sep 17 00:00:00 2001
From: sheeek <gitlab@ott.team>
Date: Wed, 7 Jan 2026 11:58:49 +0100
Subject: [PATCH 09/14] docs(config): document routing.agents sandbox and tools
 fields

Update routing.agents section:
- Add sandbox field documentation (mode, scope, workspaceRoot)
- Add tools field documentation (allow, deny)
- Note that agent-specific settings override global config
---
 docs/gateway/configuration.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index 5ad3e51e9..e3ce95beb 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -334,6 +334,13 @@ Run multiple isolated agents (separate workspace, `agentDir`, sessions) inside o
   - `workspace`: default `~/clawd-<agentId>` (for `main`, falls back to legacy `agent.workspace`).
   - `agentDir`: default `~/.clawdbot/agents/<agentId>/agent`.
   - `model`: per-agent default model (provider/model), overrides `agent.model` for that agent.
+  - `sandbox`: per-agent sandbox config (overrides `agent.sandbox`).
+    - `mode`: `"off"` | `"non-main"` | `"all"`
+    - `scope`: `"session"` | `"agent"` | `"shared"`
+    - `workspaceRoot`: custom sandbox workspace root
+  - `tools`: per-agent tool restrictions (applied before sandbox tool policy).
+    - `allow`: array of allowed tool names
+    - `deny`: array of denied tool names (deny wins)
 - `routing.bindings[]`: routes inbound messages to an `agentId`.
   - `match.provider` (required)
   - `match.accountId` (optional; `*` = any account; omitted = default account)

From dad1a99a2044e21dc13c2db1dd9aa7dc8a1b3d54 Mon Sep 17 00:00:00 2001
From: sheeek <gitlab@ott.team>
Date: Wed, 7 Jan 2026 11:59:04 +0100
Subject: [PATCH 10/14] docs(multi-agent): add section on per-agent sandbox and
 tools

Add new section explaining:
- How to configure per-agent sandbox settings
- How to configure per-agent tool restrictions
- Benefits (security isolation, resource control, flexible policies)
- Link to detailed guide

Include example config showing personal assistant (no sandbox)
vs family bot (sandboxed with read-only tools).
---
 docs/concepts/multi-agent.md | 38 ++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/concepts/multi-agent.md b/docs/concepts/multi-agent.md
index d17a556a8..1196a9619 100644
--- a/docs/concepts/multi-agent.md
+++ b/docs/concepts/multi-agent.md
@@ -131,3 +131,41 @@ multiple phone numbers without mixing sessions.
   },
 }
 ```
+
+## Per-Agent Sandbox and Tool Configuration
+
+Starting with v2026.1.6, each agent can have its own sandbox and tool restrictions:
+
+```js
+{
+  routing: {
+    agents: {
+      personal: {
+        workspace: "~/clawd-personal",
+        sandbox: {
+          mode: "off",  // No sandbox for personal agent
+        },
+        // No tool restrictions - all tools available
+      },
+      family: {
+        workspace: "~/clawd-family",
+        sandbox: {
+          mode: "all",     // Always sandboxed
+          scope: "agent",  // One container per agent
+        },
+        tools: {
+          allow: ["read"],                    // Only read tool
+          deny: ["bash", "write", "edit"],    // Deny others
+        },
+      },
+    },
+  },
+}
+```
+
+**Benefits:**
+- **Security isolation**: Restrict tools for untrusted agents
+- **Resource control**: Sandbox specific agents while keeping others on host
+- **Flexible policies**: Different permissions per agent
+
+See [Multi-Agent Sandbox & Tools](/docs/multi-agent-sandbox-tools) for detailed examples.

From 1143b3eff08e1033513b07d13de1d21ea2a45250 Mon Sep 17 00:00:00 2001
From: sheeek <gitlab@ott.team>
Date: Wed, 7 Jan 2026 11:59:16 +0100
Subject: [PATCH 11/14] docs: add comprehensive guide for multi-agent sandbox
 and tools
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add docs/multi-agent-sandbox-tools.md covering:
- Configuration examples (personal + restricted, work agents)
- Different sandbox modes per agent
- Tool restriction patterns (read-only, safe execution, communication-only)
- Configuration precedence rules
- Migration guide from single-agent setups
- Troubleshooting tips

Add PR_SUMMARY.md for upstream submission with:
- Feature overview and use cases
- Implementation details (49 LoC across 5 files)
- Test coverage (18 new tests, all existing tests pass)
- Backward compatibility confirmation
- Migration examples

---

Kudos to Eula, the beautiful and selfless family owl 🦉
This feature was developed to enable safe, restricted access
for family group chats while maintaining full access for
the personal assistant. Schuhu!
---
 PR_SUMMARY.md                     | 203 ++++++++++++++++++++++
 docs/multi-agent-sandbox-tools.md | 278 ++++++++++++++++++++++++++++++
 2 files changed, 481 insertions(+)
 create mode 100644 PR_SUMMARY.md
 create mode 100644 docs/multi-agent-sandbox-tools.md

diff --git a/PR_SUMMARY.md b/PR_SUMMARY.md
new file mode 100644
index 000000000..f21887543
--- /dev/null
+++ b/PR_SUMMARY.md
@@ -0,0 +1,203 @@
+# PR: Agent-specific Sandbox and Tool Configuration
+
+## Summary
+
+Adds support for per-agent sandbox and tool configurations in multi-agent setups. This allows running multiple agents with different security profiles (e.g., personal assistant with full access, family bot with read-only restrictions).
+
+## Changes
+
+### Core Implementation (5 files, +49 LoC)
+
+1. **`src/config/types.ts`** (+4 lines)
+   - Added `sandbox` and `tools` fields to `routing.agents[agentId]` type
+
+2. **`src/config/zod-schema.ts`** (+6 lines)
+   - Added Zod validation for `routing.agents[].sandbox` and `routing.agents[].tools`
+
+3. **`src/agents/agent-scope.ts`** (+12 lines)
+   - Extended `resolveAgentConfig()` to return `sandbox` and `tools` fields
+
+4. **`src/agents/sandbox.ts`** (+12 lines)
+   - Modified `defaultSandboxConfig()` to accept `agentId` parameter
+   - Added logic to prefer agent-specific sandbox config over global config
+   - Updated `resolveSandboxContext()` and `ensureSandboxWorkspaceForSession()` to extract and pass `agentId`
+
+5. **`src/agents/pi-tools.ts`** (+15 lines)
+   - Added agent-specific tool filtering before sandbox tool filtering
+   - Imports `resolveAgentConfig` and `resolveAgentIdFromSessionKey`
+
+### Tests (3 new test files, 18 tests)
+
+1. **`src/agents/agent-scope.test.ts`** (7 tests)
+   - Tests for `resolveAgentConfig()` with sandbox and tools fields
+
+2. **`src/agents/sandbox-agent-config.test.ts`** (6 tests)
+   - Tests for agent-specific sandbox mode, scope, and workspaceRoot overrides
+   - Tests for multiple agents with different sandbox configs
+
+3. **`src/agents/pi-tools-agent-config.test.ts`** (5 tests)
+   - Tests for agent-specific tool filtering
+   - Tests for combined global + agent + sandbox tool policies
+
+### Documentation (3 files)
+
+1. **`docs/multi-agent-sandbox-tools.md`** (new)
+   - Comprehensive guide for per-agent sandbox and tool configuration
+   - Examples for common use cases
+   - Migration guide from single-agent configs
+
+2. **`docs/concepts/multi-agent.md`** (updated)
+   - Added section on per-agent sandbox and tool configuration
+   - Link to detailed guide
+
+3. **`docs/gateway/configuration.md`** (updated)
+   - Added documentation for `routing.agents[].sandbox` and `routing.agents[].tools` fields
+
+## Features
+
+### Agent-specific Sandbox Config
+
+```json
+{
+  "routing": {
+    "agents": {
+      "main": {
+        "workspace": "~/clawd",
+        "sandbox": { "mode": "off" }
+      },
+      "family": {
+        "workspace": "~/clawd-family",
+        "sandbox": {
+          "mode": "all",
+          "scope": "agent"
+        }
+      }
+    }
+  }
+}
+```
+
+**Result:**
+- `main` agent runs on host (no Docker)
+- `family` agent runs in Docker with one container per agent
+
+### Agent-specific Tool Restrictions
+
+```json
+{
+  "routing": {
+    "agents": {
+      "family": {
+        "workspace": "~/clawd-family",
+        "tools": {
+          "allow": ["read"],
+          "deny": ["bash", "write", "edit", "process"]
+        }
+      }
+    }
+  }
+}
+```
+
+**Result:**
+- `family` agent can only use the `read` tool
+- All other tools are denied
+
+## Configuration Precedence
+
+### Sandbox Config
+Agent-specific settings override global:
+- `routing.agents[id].sandbox.mode` > `agent.sandbox.mode`
+- `routing.agents[id].sandbox.scope` > `agent.sandbox.scope`
+- `routing.agents[id].sandbox.workspaceRoot` > `agent.sandbox.workspaceRoot`
+
+Note: `docker`, `browser`, `tools`, and `prune` settings from `agent.sandbox` remain global.
+
+### Tool Filtering
+Filtering order (each level can only further restrict):
+1. Global tool policy (`agent.tools`)
+2. **Agent-specific tool policy** (`routing.agents[id].tools`) ← NEW
+3. Sandbox tool policy (`agent.sandbox.tools`)
+4. Subagent tool policy (if applicable)
+
+## Backward Compatibility
+
+✅ **100% backward compatible**
+- All existing configs work unchanged
+- New fields (`routing.agents[].sandbox`, `routing.agents[].tools`) are optional
+- Default behavior: if no agent-specific config exists, use global config
+- All 1325 existing tests pass
+
+## Testing
+
+### New Tests: 18 tests, all passing
+```
+✓ src/agents/agent-scope.test.ts (7 tests)
+✓ src/agents/sandbox-agent-config.test.ts (6 tests)
+✓ src/agents/pi-tools-agent-config.test.ts (5 tests)
+```
+
+### Existing Tests: All passing
+```
+Test Files  227 passed | 2 skipped (229)
+Tests      1325 passed | 2 skipped (1327)
+```
+
+Specifically verified:
+- Discord provider tests: ✓ 23 tests
+- Telegram provider tests: ✓ 42 tests
+- Routing tests: ✓ 7 tests
+- Gateway tests: ✓ All passed
+
+## Use Cases
+
+### Use Case 1: Personal Assistant + Restricted Family Bot
+- Personal agent: Host, all tools
+- Family agent: Docker, read-only
+
+### Use Case 2: Work Agent with Limited Access
+- Personal agent: Full access
+- Work agent: Docker, no browser/gateway tools
+
+### Use Case 3: Public-facing Bot
+- Main agent: Trusted, full access
+- Public agent: Always sandboxed, minimal tools
+
+## Migration Path
+
+**Before (global config):**
+```json
+{
+  "agent": {
+    "sandbox": { "mode": "non-main" }
+  }
+}
+```
+
+**After (per-agent config):**
+```json
+{
+  "routing": {
+    "agents": {
+      "main": { "sandbox": { "mode": "off" } },
+      "family": { "sandbox": { "mode": "all", "scope": "agent" } }
+    }
+  }
+}
+```
+
+## Related Issues
+
+- Addresses need for per-agent security policies in multi-agent setups
+- Complements existing multi-agent routing feature (introduced in 7360abad)
+- Prepares for upcoming `clawdbot agents` CLI (announced 2026-01-07)
+
+## Checklist
+
+- [x] Code changes implemented
+- [x] Tests written and passing
+- [x] Documentation updated
+- [x] Backward compatibility verified
+- [x] No breaking changes
+- [x] TypeScript types updated
+- [x] Zod schema validation added
diff --git a/docs/multi-agent-sandbox-tools.md b/docs/multi-agent-sandbox-tools.md
new file mode 100644
index 000000000..102c68c5c
--- /dev/null
+++ b/docs/multi-agent-sandbox-tools.md
@@ -0,0 +1,278 @@
+# Multi-Agent Sandbox & Tools Configuration
+
+## Overview
+
+Each agent in a multi-agent setup can now have its own:
+- **Sandbox configuration** (`mode`, `scope`, `workspaceRoot`)
+- **Tool restrictions** (`allow`, `deny`)
+
+This allows you to run multiple agents with different security profiles:
+- Personal assistant with full access
+- Family/work agents with restricted tools
+- Public-facing agents in sandboxes
+
+---
+
+## Configuration Examples
+
+### Example 1: Personal + Restricted Family Agent
+
+```json
+{
+  "routing": {
+    "defaultAgentId": "main",
+    "agents": {
+      "main": {
+        "name": "Personal Assistant",
+        "workspace": "~/clawd",
+        "sandbox": {
+          "mode": "off"
+        }
+        // No tool restrictions - all tools available
+      },
+      "family": {
+        "name": "Family Bot",
+        "workspace": "~/clawd-family",
+        "sandbox": {
+          "mode": "all",
+          "scope": "agent"
+        },
+        "tools": {
+          "allow": ["read"],
+          "deny": ["bash", "write", "edit", "process", "browser"]
+        }
+      }
+    },
+    "bindings": [
+      {
+        "agentId": "family",
+        "match": {
+          "provider": "whatsapp",
+          "accountId": "*",
+          "peer": {
+            "kind": "group",
+            "id": "120363424282127706@g.us"
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+**Result:**
+- `main` agent: Runs on host, full tool access
+- `family` agent: Runs in Docker (one container per agent), only `read` tool
+
+---
+
+### Example 2: Work Agent with Shared Sandbox
+
+```json
+{
+  "routing": {
+    "agents": {
+      "personal": {
+        "workspace": "~/clawd-personal",
+        "sandbox": { "mode": "off" }
+      },
+      "work": {
+        "workspace": "~/clawd-work",
+        "sandbox": {
+          "mode": "all",
+          "scope": "shared",
+          "workspaceRoot": "/tmp/work-sandboxes"
+        },
+        "tools": {
+          "allow": ["read", "write", "bash"],
+          "deny": ["browser", "gateway", "discord"]
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+### Example 3: Different Sandbox Modes per Agent
+
+```json
+{
+  "agent": {
+    "sandbox": {
+      "mode": "non-main",  // Global default
+      "scope": "session"
+    }
+  },
+  "routing": {
+    "agents": {
+      "main": {
+        "workspace": "~/clawd",
+        "sandbox": {
+          "mode": "off"  // Override: main never sandboxed
+        }
+      },
+      "public": {
+        "workspace": "~/clawd-public",
+        "sandbox": {
+          "mode": "all",  // Override: public always sandboxed
+          "scope": "agent"
+        },
+        "tools": {
+          "allow": ["read"],
+          "deny": ["bash", "write", "edit"]
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Configuration Precedence
+
+When both global (`agent.*`) and agent-specific (`routing.agents[id].*`) configs exist:
+
+### Sandbox Config
+Agent-specific settings override global:
+```
+routing.agents[id].sandbox.mode > agent.sandbox.mode
+routing.agents[id].sandbox.scope > agent.sandbox.scope
+routing.agents[id].sandbox.workspaceRoot > agent.sandbox.workspaceRoot
+```
+
+**Note:** `docker`, `browser`, `tools`, and `prune` settings from `agent.sandbox` are still **global** and apply to all sandboxed agents.
+
+### Tool Restrictions
+The filtering order is:
+1. **Global tool policy** (`agent.tools`)
+2. **Agent-specific tool policy** (`routing.agents[id].tools`)
+3. **Sandbox tool policy** (`agent.sandbox.tools` or `routing.agents[id].sandbox.tools`)
+4. **Subagent tool policy** (if applicable)
+
+Each level can further restrict tools, but cannot grant back denied tools from earlier levels.
+
+---
+
+## Migration from Single Agent
+
+**Before (single agent):**
+```json
+{
+  "agent": {
+    "workspace": "~/clawd",
+    "sandbox": {
+      "mode": "non-main",
+      "tools": {
+        "allow": ["read", "write", "bash"],
+        "deny": []
+      }
+    }
+  }
+}
+```
+
+**After (multi-agent with different profiles):**
+```json
+{
+  "routing": {
+    "defaultAgentId": "main",
+    "agents": {
+      "main": {
+        "workspace": "~/clawd",
+        "sandbox": {
+          "mode": "off"
+        }
+      }
+    }
+  }
+}
+```
+
+The global `agent.workspace` and `agent.sandbox` are still supported for backward compatibility, but we recommend using `routing.agents` for clarity in multi-agent setups.
+
+---
+
+## Tool Restriction Examples
+
+### Read-only Agent
+```json
+{
+  "tools": {
+    "allow": ["read"],
+    "deny": ["bash", "write", "edit", "process"]
+  }
+}
+```
+
+### Safe Execution Agent (no file modifications)
+```json
+{
+  "tools": {
+    "allow": ["read", "bash", "process"],
+    "deny": ["write", "edit", "browser", "gateway"]
+  }
+}
+```
+
+### Communication-only Agent
+```json
+{
+  "tools": {
+    "allow": ["sessions_list", "sessions_send", "sessions_history"],
+    "deny": ["bash", "write", "edit", "read", "browser"]
+  }
+}
+```
+
+---
+
+## Testing
+
+After configuring multi-agent sandbox and tools:
+
+1. **Check agent resolution:**
+   ```bash
+   clawdbot agents list
+   ```
+
+2. **Verify sandbox containers:**
+   ```bash
+   docker ps --filter "label=clawdbot.sandbox=1"
+   ```
+
+3. **Test tool restrictions:**
+   - Send a message requiring restricted tools
+   - Verify the agent cannot use denied tools
+
+4. **Monitor logs:**
+   ```bash
+   tail -f ~/.clawdbot/logs/gateway.log | grep -E "routing|sandbox|tools"
+   ```
+
+---
+
+## Troubleshooting
+
+### Agent not sandboxed despite `mode: "all"`
+- Check if there's a global `agent.sandbox.mode` that overrides it
+- Agent-specific config takes precedence, so set `routing.agents[id].sandbox.mode: "all"`
+
+### Tools still available despite deny list
+- Check tool filtering order: global → agent → sandbox → subagent
+- Each level can only further restrict, not grant back
+- Verify with logs: `[tools] filtering tools for agent:${agentId}`
+
+### Container not isolated per agent
+- Set `scope: "agent"` in agent-specific sandbox config
+- Default is `"session"` which creates one container per session
+
+---
+
+## See Also
+
+- [Multi-Agent Routing](/concepts/multi-agent)
+- [Sandbox Configuration](/gateway/configuration#agent-sandbox)
+- [Session Management](/concepts/session)

From 6352f33799c459c1f3d3fdfb6987c476f1c00d89 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 7 Jan 2026 12:24:12 +0100
Subject: [PATCH 12/14] fix: per-agent sandbox overrides

---
 CHANGELOG.md                             |   1 +
 PR_SUMMARY.md                            | 203 -----------------------
 docs/concepts/multi-agent.md             |   2 +-
 docs/gateway/configuration.md            |   2 +
 docs/multi-agent-sandbox-tools.md        |   6 +-
 src/agents/agent-scope.test.ts           |  10 ++
 src/agents/agent-scope.ts                |   5 +
 src/agents/pi-tools-agent-config.test.ts |  11 +-
 src/agents/pi-tools.ts                   |   4 +-
 src/agents/sandbox-agent-config.test.ts  |  78 ++++++++-
 src/agents/sandbox.ts                    |  23 ++-
 src/config/types.ts                      |   7 +
 src/config/zod-schema.ts                 |   9 +
 13 files changed, 138 insertions(+), 223 deletions(-)
 delete mode 100644 PR_SUMMARY.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8635852b9..fb6fe86ad 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,7 @@
 - Pairing: lock + atomically write pairing stores with 0600 perms and stop logging pairing codes in provider logs.
 - Discord: include all inbound attachments in `MediaPaths`/`MediaUrls` (back-compat `MediaPath`/`MediaUrl` still first).
 - Sandbox: add `agent.sandbox.workspaceAccess` (`none`/`ro`/`rw`) to control agent workspace visibility inside the container; `ro` hard-disables `write`/`edit`.
+- Routing: allow per-agent sandbox overrides (including `workspaceAccess` and `sandbox.tools`) plus per-agent tool policies in multi-agent configs. Thanks @pasogott for PR #380.
 - Tools: add Telegram/WhatsApp reaction tools (with per-provider gating). Thanks @zats for PR #353.
 - Tools: unify reaction removal semantics across Discord/Slack/Telegram/WhatsApp and allow WhatsApp reaction routing across accounts.
 - Gateway/CLI: add daemon runtime selection (Node recommended; Bun optional) and document WhatsApp/Baileys Bun WebSocket instability on reconnect.
diff --git a/PR_SUMMARY.md b/PR_SUMMARY.md
deleted file mode 100644
index f21887543..000000000
--- a/PR_SUMMARY.md
+++ /dev/null
@@ -1,203 +0,0 @@
-# PR: Agent-specific Sandbox and Tool Configuration
-
-## Summary
-
-Adds support for per-agent sandbox and tool configurations in multi-agent setups. This allows running multiple agents with different security profiles (e.g., personal assistant with full access, family bot with read-only restrictions).
-
-## Changes
-
-### Core Implementation (5 files, +49 LoC)
-
-1. **`src/config/types.ts`** (+4 lines)
-   - Added `sandbox` and `tools` fields to `routing.agents[agentId]` type
-
-2. **`src/config/zod-schema.ts`** (+6 lines)
-   - Added Zod validation for `routing.agents[].sandbox` and `routing.agents[].tools`
-
-3. **`src/agents/agent-scope.ts`** (+12 lines)
-   - Extended `resolveAgentConfig()` to return `sandbox` and `tools` fields
-
-4. **`src/agents/sandbox.ts`** (+12 lines)
-   - Modified `defaultSandboxConfig()` to accept `agentId` parameter
-   - Added logic to prefer agent-specific sandbox config over global config
-   - Updated `resolveSandboxContext()` and `ensureSandboxWorkspaceForSession()` to extract and pass `agentId`
-
-5. **`src/agents/pi-tools.ts`** (+15 lines)
-   - Added agent-specific tool filtering before sandbox tool filtering
-   - Imports `resolveAgentConfig` and `resolveAgentIdFromSessionKey`
-
-### Tests (3 new test files, 18 tests)
-
-1. **`src/agents/agent-scope.test.ts`** (7 tests)
-   - Tests for `resolveAgentConfig()` with sandbox and tools fields
-
-2. **`src/agents/sandbox-agent-config.test.ts`** (6 tests)
-   - Tests for agent-specific sandbox mode, scope, and workspaceRoot overrides
-   - Tests for multiple agents with different sandbox configs
-
-3. **`src/agents/pi-tools-agent-config.test.ts`** (5 tests)
-   - Tests for agent-specific tool filtering
-   - Tests for combined global + agent + sandbox tool policies
-
-### Documentation (3 files)
-
-1. **`docs/multi-agent-sandbox-tools.md`** (new)
-   - Comprehensive guide for per-agent sandbox and tool configuration
-   - Examples for common use cases
-   - Migration guide from single-agent configs
-
-2. **`docs/concepts/multi-agent.md`** (updated)
-   - Added section on per-agent sandbox and tool configuration
-   - Link to detailed guide
-
-3. **`docs/gateway/configuration.md`** (updated)
-   - Added documentation for `routing.agents[].sandbox` and `routing.agents[].tools` fields
-
-## Features
-
-### Agent-specific Sandbox Config
-
-```json
-{
-  "routing": {
-    "agents": {
-      "main": {
-        "workspace": "~/clawd",
-        "sandbox": { "mode": "off" }
-      },
-      "family": {
-        "workspace": "~/clawd-family",
-        "sandbox": {
-          "mode": "all",
-          "scope": "agent"
-        }
-      }
-    }
-  }
-}
-```
-
-**Result:**
-- `main` agent runs on host (no Docker)
-- `family` agent runs in Docker with one container per agent
-
-### Agent-specific Tool Restrictions
-
-```json
-{
-  "routing": {
-    "agents": {
-      "family": {
-        "workspace": "~/clawd-family",
-        "tools": {
-          "allow": ["read"],
-          "deny": ["bash", "write", "edit", "process"]
-        }
-      }
-    }
-  }
-}
-```
-
-**Result:**
-- `family` agent can only use the `read` tool
-- All other tools are denied
-
-## Configuration Precedence
-
-### Sandbox Config
-Agent-specific settings override global:
-- `routing.agents[id].sandbox.mode` > `agent.sandbox.mode`
-- `routing.agents[id].sandbox.scope` > `agent.sandbox.scope`
-- `routing.agents[id].sandbox.workspaceRoot` > `agent.sandbox.workspaceRoot`
-
-Note: `docker`, `browser`, `tools`, and `prune` settings from `agent.sandbox` remain global.
-
-### Tool Filtering
-Filtering order (each level can only further restrict):
-1. Global tool policy (`agent.tools`)
-2. **Agent-specific tool policy** (`routing.agents[id].tools`) ← NEW
-3. Sandbox tool policy (`agent.sandbox.tools`)
-4. Subagent tool policy (if applicable)
-
-## Backward Compatibility
-
-✅ **100% backward compatible**
-- All existing configs work unchanged
-- New fields (`routing.agents[].sandbox`, `routing.agents[].tools`) are optional
-- Default behavior: if no agent-specific config exists, use global config
-- All 1325 existing tests pass
-
-## Testing
-
-### New Tests: 18 tests, all passing
-```
-✓ src/agents/agent-scope.test.ts (7 tests)
-✓ src/agents/sandbox-agent-config.test.ts (6 tests)
-✓ src/agents/pi-tools-agent-config.test.ts (5 tests)
-```
-
-### Existing Tests: All passing
-```
-Test Files  227 passed | 2 skipped (229)
-Tests      1325 passed | 2 skipped (1327)
-```
-
-Specifically verified:
-- Discord provider tests: ✓ 23 tests
-- Telegram provider tests: ✓ 42 tests
-- Routing tests: ✓ 7 tests
-- Gateway tests: ✓ All passed
-
-## Use Cases
-
-### Use Case 1: Personal Assistant + Restricted Family Bot
-- Personal agent: Host, all tools
-- Family agent: Docker, read-only
-
-### Use Case 2: Work Agent with Limited Access
-- Personal agent: Full access
-- Work agent: Docker, no browser/gateway tools
-
-### Use Case 3: Public-facing Bot
-- Main agent: Trusted, full access
-- Public agent: Always sandboxed, minimal tools
-
-## Migration Path
-
-**Before (global config):**
-```json
-{
-  "agent": {
-    "sandbox": { "mode": "non-main" }
-  }
-}
-```
-
-**After (per-agent config):**
-```json
-{
-  "routing": {
-    "agents": {
-      "main": { "sandbox": { "mode": "off" } },
-      "family": { "sandbox": { "mode": "all", "scope": "agent" } }
-    }
-  }
-}
-```
-
-## Related Issues
-
-- Addresses need for per-agent security policies in multi-agent setups
-- Complements existing multi-agent routing feature (introduced in 7360abad)
-- Prepares for upcoming `clawdbot agents` CLI (announced 2026-01-07)
-
-## Checklist
-
-- [x] Code changes implemented
-- [x] Tests written and passing
-- [x] Documentation updated
-- [x] Backward compatibility verified
-- [x] No breaking changes
-- [x] TypeScript types updated
-- [x] Zod schema validation added
diff --git a/docs/concepts/multi-agent.md b/docs/concepts/multi-agent.md
index 1196a9619..131ed3a96 100644
--- a/docs/concepts/multi-agent.md
+++ b/docs/concepts/multi-agent.md
@@ -168,4 +168,4 @@ Starting with v2026.1.6, each agent can have its own sandbox and tool restrictio
 - **Resource control**: Sandbox specific agents while keeping others on host
 - **Flexible policies**: Different permissions per agent
 
-See [Multi-Agent Sandbox & Tools](/docs/multi-agent-sandbox-tools) for detailed examples.
+See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for detailed examples.
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index e3ce95beb..8a5be2d8c 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -336,8 +336,10 @@ Run multiple isolated agents (separate workspace, `agentDir`, sessions) inside o
   - `model`: per-agent default model (provider/model), overrides `agent.model` for that agent.
   - `sandbox`: per-agent sandbox config (overrides `agent.sandbox`).
     - `mode`: `"off"` | `"non-main"` | `"all"`
+    - `workspaceAccess`: `"none"` | `"ro"` | `"rw"`
     - `scope`: `"session"` | `"agent"` | `"shared"`
     - `workspaceRoot`: custom sandbox workspace root
+    - `tools`: per-agent sandbox tool policy (deny wins; overrides `agent.sandbox.tools`)
   - `tools`: per-agent tool restrictions (applied before sandbox tool policy).
     - `allow`: array of allowed tool names
     - `deny`: array of denied tool names (deny wins)
diff --git a/docs/multi-agent-sandbox-tools.md b/docs/multi-agent-sandbox-tools.md
index 102c68c5c..124b69cc8 100644
--- a/docs/multi-agent-sandbox-tools.md
+++ b/docs/multi-agent-sandbox-tools.md
@@ -3,7 +3,7 @@
 ## Overview
 
 Each agent in a multi-agent setup can now have its own:
-- **Sandbox configuration** (`mode`, `scope`, `workspaceRoot`)
+- **Sandbox configuration** (`mode`, `scope`, `workspaceRoot`, `workspaceAccess`, `tools`)
 - **Tool restrictions** (`allow`, `deny`)
 
 This allows you to run multiple agents with different security profiles:
@@ -141,9 +141,10 @@ Agent-specific settings override global:
 routing.agents[id].sandbox.mode > agent.sandbox.mode
 routing.agents[id].sandbox.scope > agent.sandbox.scope
 routing.agents[id].sandbox.workspaceRoot > agent.sandbox.workspaceRoot
+routing.agents[id].sandbox.workspaceAccess > agent.sandbox.workspaceAccess
 ```
 
-**Note:** `docker`, `browser`, `tools`, and `prune` settings from `agent.sandbox` are still **global** and apply to all sandboxed agents.
+**Note:** `docker`, `browser`, and `prune` settings from `agent.sandbox` are still **global** and apply to all sandboxed agents.
 
 ### Tool Restrictions
 The filtering order is:
@@ -153,6 +154,7 @@ The filtering order is:
 4. **Subagent tool policy** (if applicable)
 
 Each level can further restrict tools, but cannot grant back denied tools from earlier levels.
+If `routing.agents[id].sandbox.tools` is set, it replaces `agent.sandbox.tools` for that agent.
 
 ---
 
diff --git a/src/agents/agent-scope.test.ts b/src/agents/agent-scope.test.ts
index 339087959..322e66ac9 100644
--- a/src/agents/agent-scope.test.ts
+++ b/src/agents/agent-scope.test.ts
@@ -55,7 +55,12 @@ describe("resolveAgentConfig", () => {
               mode: "all",
               scope: "agent",
               perSession: false,
+              workspaceAccess: "ro",
               workspaceRoot: "~/sandboxes",
+              tools: {
+                allow: ["read"],
+                deny: ["bash"],
+              },
             },
           },
         },
@@ -66,7 +71,12 @@ describe("resolveAgentConfig", () => {
       mode: "all",
       scope: "agent",
       perSession: false,
+      workspaceAccess: "ro",
       workspaceRoot: "~/sandboxes",
+      tools: {
+        allow: ["read"],
+        deny: ["bash"],
+      },
     });
   });
 
diff --git a/src/agents/agent-scope.ts b/src/agents/agent-scope.ts
index adc5e3789..384976e9c 100644
--- a/src/agents/agent-scope.ts
+++ b/src/agents/agent-scope.ts
@@ -29,9 +29,14 @@ export function resolveAgentConfig(
       model?: string;
       sandbox?: {
         mode?: "off" | "non-main" | "all";
+        workspaceAccess?: "none" | "ro" | "rw";
         scope?: "session" | "agent" | "shared";
         perSession?: boolean;
         workspaceRoot?: string;
+        tools?: {
+          allow?: string[];
+          deny?: string[];
+        };
       };
       tools?: {
         allow?: string[];
diff --git a/src/agents/pi-tools-agent-config.test.ts b/src/agents/pi-tools-agent-config.test.ts
index 0b8affd39..65c429781 100644
--- a/src/agents/pi-tools-agent-config.test.ts
+++ b/src/agents/pi-tools-agent-config.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import type { ClawdbotConfig } from "../config/config.js";
 import { createClawdbotCodingTools } from "./pi-tools.js";
+import type { SandboxDockerConfig } from "./sandbox.js";
 
 describe("Agent-specific tool filtering", () => {
   it("should apply global tool policy when no agent-specific policy exists", () => {
@@ -188,7 +189,15 @@ describe("Agent-specific tool filtering", () => {
         workspaceAccess: "none",
         containerName: "test-container",
         containerWorkdir: "/workspace",
-        docker: {} as any,
+        docker: {
+          image: "test-image",
+          containerPrefix: "test-",
+          workdir: "/workspace",
+          readOnlyRoot: true,
+          tmpfs: [],
+          network: "none",
+          capDrop: [],
+        } satisfies SandboxDockerConfig,
         tools: {
           allow: ["read", "write", "bash"],
           deny: [],
diff --git a/src/agents/pi-tools.ts b/src/agents/pi-tools.ts
index 7687e788d..80de703fd 100644
--- a/src/agents/pi-tools.ts
+++ b/src/agents/pi-tools.ts
@@ -596,7 +596,7 @@ export function createClawdbotCodingTools(options?: {
       options.config.agent.tools.deny?.length)
       ? filterToolsByPolicy(filtered, options.config.agent.tools)
       : filtered;
-  
+
   // Agent-specific tool policy
   let agentFiltered = globallyFiltered;
   if (options?.sessionKey && options?.config) {
@@ -606,7 +606,7 @@ export function createClawdbotCodingTools(options?: {
       agentFiltered = filterToolsByPolicy(globallyFiltered, agentConfig.tools);
     }
   }
-  
+
   const sandboxed = sandbox
     ? filterToolsByPolicy(agentFiltered, sandbox.tools)
     : agentFiltered;
diff --git a/src/agents/sandbox-agent-config.test.ts b/src/agents/sandbox-agent-config.test.ts
index 040b3d483..2333e67fc 100644
--- a/src/agents/sandbox-agent-config.test.ts
+++ b/src/agents/sandbox-agent-config.test.ts
@@ -1,13 +1,33 @@
-import { describe, expect, it } from "vitest";
+import { EventEmitter } from "node:events";
+import { Readable } from "node:stream";
+import { describe, expect, it, vi } from "vitest";
 import type { ClawdbotConfig } from "../config/config.js";
 
 // We need to test the internal defaultSandboxConfig function, but it's not exported.
 // Instead, we test the behavior through resolveSandboxContext which uses it.
 
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>();
+  return {
+    ...actual,
+    spawn: () => {
+      const child = new EventEmitter() as {
+        stdout?: Readable;
+        stderr?: Readable;
+        on: (event: string, cb: (...args: unknown[]) => void) => void;
+      };
+      child.stdout = new Readable({ read() {} });
+      child.stderr = new Readable({ read() {} });
+      queueMicrotask(() => child.emit("close", 0));
+      return child;
+    },
+  };
+});
+
 describe("Agent-specific sandbox config", () => {
   it("should use global sandbox config when no agent-specific config exists", async () => {
     const { resolveSandboxContext } = await import("./sandbox.js");
-    
+
     const cfg: ClawdbotConfig = {
       agent: {
         sandbox: {
@@ -36,7 +56,7 @@ describe("Agent-specific sandbox config", () => {
 
   it("should override with agent-specific sandbox mode 'off'", async () => {
     const { resolveSandboxContext } = await import("./sandbox.js");
-    
+
     const cfg: ClawdbotConfig = {
       agent: {
         sandbox: {
@@ -68,7 +88,7 @@ describe("Agent-specific sandbox config", () => {
 
   it("should use agent-specific sandbox mode 'all'", async () => {
     const { resolveSandboxContext } = await import("./sandbox.js");
-    
+
     const cfg: ClawdbotConfig = {
       agent: {
         sandbox: {
@@ -100,7 +120,7 @@ describe("Agent-specific sandbox config", () => {
 
   it("should use agent-specific scope", async () => {
     const { resolveSandboxContext } = await import("./sandbox.js");
-    
+
     const cfg: ClawdbotConfig = {
       agent: {
         sandbox: {
@@ -134,7 +154,7 @@ describe("Agent-specific sandbox config", () => {
 
   it("should use agent-specific workspaceRoot", async () => {
     const { resolveSandboxContext } = await import("./sandbox.js");
-    
+
     const cfg: ClawdbotConfig = {
       agent: {
         sandbox: {
@@ -169,7 +189,7 @@ describe("Agent-specific sandbox config", () => {
 
   it("should prefer agent config over global for multiple agents", async () => {
     const { resolveSandboxContext } = await import("./sandbox.js");
-    
+
     const cfg: ClawdbotConfig = {
       agent: {
         sandbox: {
@@ -213,4 +233,48 @@ describe("Agent-specific sandbox config", () => {
     expect(familyContext).toBeDefined();
     expect(familyContext?.enabled).toBe(true);
   });
+
+  it("should prefer agent-specific sandbox tool policy", async () => {
+    const { resolveSandboxContext } = await import("./sandbox.js");
+
+    const cfg: ClawdbotConfig = {
+      agent: {
+        sandbox: {
+          mode: "all",
+          scope: "agent",
+          tools: {
+            allow: ["read"],
+            deny: ["bash"],
+          },
+        },
+      },
+      routing: {
+        agents: {
+          restricted: {
+            workspace: "~/clawd-restricted",
+            sandbox: {
+              mode: "all",
+              scope: "agent",
+              tools: {
+                allow: ["read", "write"],
+                deny: ["edit"],
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const context = await resolveSandboxContext({
+      config: cfg,
+      sessionKey: "agent:restricted:main",
+      workspaceDir: "/tmp/test-restricted",
+    });
+
+    expect(context).toBeDefined();
+    expect(context?.tools).toEqual({
+      allow: ["read", "write"],
+      deny: ["edit"],
+    });
+  });
 });
diff --git a/src/agents/sandbox.ts b/src/agents/sandbox.ts
index 547553268..eeb2ea96f 100644
--- a/src/agents/sandbox.ts
+++ b/src/agents/sandbox.ts
@@ -226,9 +226,12 @@ function resolveSandboxScopeKey(scope: SandboxScope, sessionKey: string) {
   return `agent:${agentId}`;
 }
 
-function defaultSandboxConfig(cfg?: ClawdbotConfig, agentId?: string): SandboxConfig {
+function defaultSandboxConfig(
+  cfg?: ClawdbotConfig,
+  agentId?: string,
+): SandboxConfig {
   const agent = cfg?.agent?.sandbox;
-  
+
   // Agent-specific sandbox config overrides global
   let agentSandbox: typeof agent | undefined;
   if (agentId && cfg?.routing?.agents) {
@@ -237,15 +240,19 @@ function defaultSandboxConfig(cfg?: ClawdbotConfig, agentId?: string): SandboxCo
       agentSandbox = agentConfig.sandbox;
     }
   }
-  
+
   return {
     mode: agentSandbox?.mode ?? agent?.mode ?? "off",
     scope: resolveSandboxScope({
       scope: agentSandbox?.scope ?? agent?.scope,
       perSession: agentSandbox?.perSession ?? agent?.perSession,
     }),
-    workspaceAccess: agentSandbox?.workspaceAccess ?? agent?.workspaceAccess ?? "none",
-    workspaceRoot: agentSandbox?.workspaceRoot ?? agent?.workspaceRoot ?? DEFAULT_SANDBOX_WORKSPACE_ROOT,
+    workspaceAccess:
+      agentSandbox?.workspaceAccess ?? agent?.workspaceAccess ?? "none",
+    workspaceRoot:
+      agentSandbox?.workspaceRoot ??
+      agent?.workspaceRoot ??
+      DEFAULT_SANDBOX_WORKSPACE_ROOT,
     docker: {
       image: agent?.docker?.image ?? DEFAULT_SANDBOX_IMAGE,
       containerPrefix:
@@ -281,8 +288,10 @@ function defaultSandboxConfig(cfg?: ClawdbotConfig, agentId?: string): SandboxCo
       enableNoVnc: agent?.browser?.enableNoVnc ?? true,
     },
     tools: {
-      allow: agent?.tools?.allow ?? DEFAULT_TOOL_ALLOW,
-      deny: agent?.tools?.deny ?? DEFAULT_TOOL_DENY,
+      allow:
+        agentSandbox?.tools?.allow ?? agent?.tools?.allow ?? DEFAULT_TOOL_ALLOW,
+      deny:
+        agentSandbox?.tools?.deny ?? agent?.tools?.deny ?? DEFAULT_TOOL_DENY,
     },
     prune: {
       idleHours: agent?.prune?.idleHours ?? DEFAULT_SANDBOX_IDLE_HOURS,
diff --git a/src/config/types.ts b/src/config/types.ts
index a1c8adb44..e8a16f23d 100644
--- a/src/config/types.ts
+++ b/src/config/types.ts
@@ -586,11 +586,18 @@ export type RoutingConfig = {
       model?: string;
       sandbox?: {
         mode?: "off" | "non-main" | "all";
+        /** Agent workspace access inside the sandbox. */
+        workspaceAccess?: "none" | "ro" | "rw";
         /** Container/workspace scope for sandbox isolation. */
         scope?: "session" | "agent" | "shared";
         /** Legacy alias for scope ("session" when true, "shared" when false). */
         perSession?: boolean;
         workspaceRoot?: string;
+        /** Tool allow/deny policy for sandboxed sessions (deny wins). */
+        tools?: {
+          allow?: string[];
+          deny?: string[];
+        };
       };
       tools?: {
         allow?: string[];
diff --git a/src/config/zod-schema.ts b/src/config/zod-schema.ts
index 0f4e018d3..b3dfef5ab 100644
--- a/src/config/zod-schema.ts
+++ b/src/config/zod-schema.ts
@@ -236,6 +236,9 @@ const RoutingSchema = z
                     z.literal("all"),
                   ])
                   .optional(),
+                workspaceAccess: z
+                  .union([z.literal("none"), z.literal("ro"), z.literal("rw")])
+                  .optional(),
                 scope: z
                   .union([
                     z.literal("session"),
@@ -245,6 +248,12 @@ const RoutingSchema = z
                   .optional(),
                 perSession: z.boolean().optional(),
                 workspaceRoot: z.string().optional(),
+                tools: z
+                  .object({
+                    allow: z.array(z.string()).optional(),
+                    deny: z.array(z.string()).optional(),
+                  })
+                  .optional(),
               })
               .optional(),
             tools: z

From e3e0980b2787101e2c96e736080fd63ac4b79333 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 7 Jan 2026 16:54:37 +0100
Subject: [PATCH 13/14] docs: explain why Twilio is unsupported

---
 docs/providers/whatsapp.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/docs/providers/whatsapp.md b/docs/providers/whatsapp.md
index c8f3dcd8b..42dfb0572 100644
--- a/docs/providers/whatsapp.md
+++ b/docs/providers/whatsapp.md
@@ -5,7 +5,7 @@ read_when:
 ---
 # WhatsApp (web provider)
 
-Updated: 2025-12-23
+Updated: 2026-01-07
 
 Status: WhatsApp Web via Baileys only. Gateway owns the session(s).
 
@@ -35,6 +35,13 @@ WhatsApp requires a real mobile number for verification. VoIP and virtual number
 
 **WhatsApp Business:** You can use WhatsApp Business on the same phone with a different number. This is a great option if you want to keep your personal WhatsApp separate — just install WhatsApp Business and register it with Clawdbot's dedicated number.
 
+## Why Not Twilio?
+- Early Clawdbot builds supported Twilio’s WhatsApp Business integration.
+- WhatsApp Business numbers are a poor fit for a personal assistant.
+- Meta enforces a 24‑hour reply window; if you haven’t responded in the last 24 hours, the business number can’t initiate new messages.
+- High-volume or “chatty” usage triggers aggressive blocking, because business accounts aren’t meant to send dozens of personal assistant messages.
+- Result: unreliable delivery and frequent blocks, so support was removed.
+
 ## Login + credentials
 - Login command: `clawdbot login` (QR via Linked Devices).
 - Multi-account login: `clawdbot login --account <id>` (`<id>` = `accountId`).

From d81627da72d51f2ec2b1af6f7b5ed64c2180fd60 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 7 Jan 2026 17:15:53 +0100
Subject: [PATCH 14/14] docs: document streaming + chunking

---
 docs/concepts/agent.md        |  1 +
 docs/concepts/streaming.md    | 85 +++++++++++++++++++++++++++++++++++
 docs/gateway/configuration.md |  1 +
 docs/index.md                 |  1 +
 docs/providers/telegram.md    |  1 +
 docs/start/hubs.md            |  1 +
 6 files changed, 90 insertions(+)
 create mode 100644 docs/concepts/streaming.md

diff --git a/docs/concepts/agent.md b/docs/concepts/agent.md
index 307aaa534..a4d4bb780 100644
--- a/docs/concepts/agent.md
+++ b/docs/concepts/agent.md
@@ -102,6 +102,7 @@ Control soft block chunking with `agent.blockStreamingChunk` (defaults to
 800–1200 chars; prefers paragraph breaks, then newlines; sentences last).
 Verbose tool summaries are emitted at tool start (no debounce); Control UI
 streams tool output via agent events when available.
+More details: [Streaming + chunking](/concepts/streaming).
 
 ## Configuration (minimal)
 
diff --git a/docs/concepts/streaming.md b/docs/concepts/streaming.md
new file mode 100644
index 000000000..26c216b82
--- /dev/null
+++ b/docs/concepts/streaming.md
@@ -0,0 +1,85 @@
+---
+summary: "Streaming + chunking behavior (block replies, draft streaming, limits)"
+read_when:
+  - Explaining how streaming or chunking works on providers
+  - Changing block streaming or provider chunking behavior
+  - Debugging duplicate/early block replies or draft streaming
+---
+# Streaming + chunking
+
+Clawdbot has two separate “streaming” layers:
+- **Block streaming (providers):** emit completed **blocks** as the assistant writes. These are normal provider messages (not token deltas).
+- **Token-ish streaming (Telegram only):** update a **draft bubble** with partial text while generating; final message is sent at the end.
+
+There is **no real token streaming** to external provider messages today. Telegram draft streaming is the only partial-stream surface.
+
+## Block streaming (provider messages)
+
+Block streaming sends assistant output in coarse chunks as it becomes available.
+
+```
+Model output
+  └─ text_delta/events
+       ├─ (blockStreamingBreak=text_end)
+       │    └─ chunker emits blocks as buffer grows
+       └─ (blockStreamingBreak=message_end)
+            └─ chunker flushes at message_end
+                   └─ provider send (block replies)
+```
+Legend:
+- `text_delta/events`: model stream events (may be sparse for non-streaming models).
+- `chunker`: `EmbeddedBlockChunker` applying min/max bounds + break preference.
+- `provider send`: actual outbound messages (block replies).
+
+**Controls:**
+- `agent.blockStreamingDefault`: `"on"`/`"off"` (default on).
+- `agent.blockStreamingBreak`: `"text_end"` or `"message_end"`.
+- `agent.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`.
+- Provider hard cap: `*.textChunkLimit` (e.g., `whatsapp.textChunkLimit`).
+
+**Boundary semantics:**
+- `text_end`: stream blocks as soon as chunker emits; flush on each `text_end`.
+- `message_end`: wait until assistant message finishes, then flush buffered output.
+
+`message_end` still uses the chunker if the buffered text exceeds `maxChars`, so it can emit multiple chunks at the end.
+
+## Chunking algorithm (low/high bounds)
+
+Block chunking is implemented by `EmbeddedBlockChunker`:
+- **Low bound:** don’t emit until buffer >= `minChars` (unless forced).
+- **High bound:** prefer splits before `maxChars`; if forced, split at `maxChars`.
+- **Break preference:** `paragraph` → `newline` → `sentence` → `whitespace` → hard break.
+- **Code fences:** never split inside fences; when forced at `maxChars`, close + reopen the fence to keep Markdown valid.
+
+`maxChars` is clamped to the provider `textChunkLimit`, so you can’t exceed per-provider caps.
+
+## “Stream chunks or everything”
+
+This maps to:
+- **Stream chunks:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (emit as you go).
+- **Stream everything at end:** `blockStreamingBreak: "message_end"` (flush once, possibly multiple chunks if very long).
+- **No block streaming:** `blockStreamingDefault: "off"` (only final reply).
+
+## Telegram draft streaming (token-ish)
+
+Telegram is the only provider with draft streaming:
+- Uses Bot API `sendMessageDraft` in **private chats with topics**.
+- `telegram.streamMode: "partial" | "block" | "off"`.
+  - `partial`: draft updates with the latest stream text.
+  - `block`: draft updates in chunked blocks (same chunker rules).
+  - `off`: no draft streaming.
+- Final reply is still a normal message.
+- `/reasoning stream` writes reasoning into the draft bubble (Telegram only).
+
+When draft streaming is active, Clawdbot disables block streaming for that reply to avoid double-streaming.
+
+```
+Telegram (private + topics)
+  └─ sendMessageDraft (draft bubble)
+       ├─ streamMode=partial → update latest text
+       └─ streamMode=block   → chunker updates draft
+  └─ final reply → normal message
+```
+Legend:
+- `sendMessageDraft`: Telegram draft bubble (not a real message).
+- `final reply`: normal Telegram message send.
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index 8a5be2d8c..0b39a9580 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -826,6 +826,7 @@ Block streaming:
     }
   }
   ```
+See [/concepts/streaming](/concepts/streaming) for behavior + chunking details.
 
 `agent.model.primary` should be set as `provider/model` (e.g. `anthropic/claude-opus-4-5`).
 Aliases come from `agent.models.*.alias` (e.g. `Opus`).
diff --git a/docs/index.md b/docs/index.md
index cd3b4be50..410ff452d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -80,6 +80,7 @@ Most operations flow through the **Gateway** (`clawdbot gateway`), a single long
 - 🎮 **Discord Bot** — DMs + guild channels via discord.js
 - 💬 **iMessage** — Local imsg CLI integration (macOS)
 - 🤖 **Agent bridge** — Pi (RPC mode) with tool streaming
+- ⏱️ **Streaming + chunking** — Block streaming + Telegram draft streaming details ([/concepts/streaming](/concepts/streaming))
 - 🧠 **Multi-agent routing** — Route provider accounts/peers to isolated agents (workspace + per-agent sessions)
 - 🔐 **Subscription auth** — Anthropic (Claude Pro/Max) + OpenAI (ChatGPT/Codex) via OAuth
 - 💬 **Sessions** — Direct chats collapse into shared `main` (default); groups are isolated
diff --git a/docs/providers/telegram.md b/docs/providers/telegram.md
index ef8b7bac8..3772ebc81 100644
--- a/docs/providers/telegram.md
+++ b/docs/providers/telegram.md
@@ -94,6 +94,7 @@ Reasoning stream (Telegram only):
 - `/reasoning stream` streams reasoning into the draft bubble while the reply is
   generating, then sends the final answer without reasoning.
 - If `telegram.streamMode` is `off`, reasoning stream is disabled.
+More context: [Streaming + chunking](/concepts/streaming).
 
 ## Agent tool (reactions)
 - Tool: `telegram` with `react` action (`chatId`, `messageId`, `emoji`).
diff --git a/docs/start/hubs.md b/docs/start/hubs.md
index bddfaea85..77b943b47 100644
--- a/docs/start/hubs.md
+++ b/docs/start/hubs.md
@@ -34,6 +34,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [Agent runtime](https://docs.clawd.bot/concepts/agent)
 - [Agent workspace](https://docs.clawd.bot/concepts/agent-workspace)
 - [Agent loop](https://docs.clawd.bot/concepts/agent-loop)
+- [Streaming + chunking](/concepts/streaming)
 - [Multi-agent routing](https://docs.clawd.bot/concepts/multi-agent)
 - [Sessions](https://docs.clawd.bot/concepts/session)
 - [Sessions (alias)](https://docs.clawd.bot/concepts/sessions)